#413: Load plugins from JAR files

.github/ISSUE_TEMPLATE/New_plugin.md

@@ -0,0 +1,13 @@
+---
+name: Add a new third-party plugin
+about: Update OFT documentation to include a new third-party plugin
+
+---
+
+## Plugin Details
+
+* Name:
+* Description:
+* Web page:
+* Source code repository:
+* Plugin type (importer, exporter or reporter):

.github/workflows/broken_links_checker.yml

@@ -2,7 +2,7 @@ name: Broken Links Checker
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
 
 jobs:
@@ -18,6 +18,6 @@ jobs:
           echo '{ "aliveStatusCodes": [429, 200] }' > ./target/broken_links_checker.json
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
-          use-quiet-mode: 'yes'
-          use-verbose-mode: 'yes'
-          config-file: ./target/broken_links_checker.json
+          use-quiet-mode: "yes"
+          use-verbose-mode: "yes"
+          config-file: ./target/broken_links_checker.json

.github/workflows/build.yml

@@ -2,17 +2,16 @@ name: Build
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
 
 jobs:
   matrix-build:
-
     permissions:
       contents: read
 
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         java: [17]
         os: [ubuntu-latest, macos-latest, windows-latest]
@@ -34,83 +33,81 @@ jobs:
       DEFAULT_OS: ubuntu-latest
 
     steps:
-
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - uses: actions/setup-java@v4
-      with:
-        distribution: 'temurin'
-        java-version: |
-          17
-          21
-        cache: 'maven'
-
-    - name: Cache SonarQube packages
-      if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
-      uses: actions/cache@v4
-      with:
-        path: ~/.sonar/cache
-        key: ${{ runner.os }}-sonar
-        restore-keys: ${{ runner.os }}-sonar
-
-    - name: Build with Java ${{ matrix.java }}
-      run: |
-        mvn --batch-mode -T 1C clean org.jacoco:jacoco-maven-plugin:prepare-agent install \
-            -Djava.version=${{ matrix.java }}
-
-    - name: Sonar analysis
-      if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java && env.SONAR_TOKEN != null }}
-      run: |
-        mvn --batch-mode org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
-            -Dsonar.token=$SONAR_TOKEN
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-
-    - name: Verify reproducible build
-      # Build fails on Windows with error "Failed to execute goal org.apache.maven.plugins:maven-artifact-plugin:3.5.0:compare (default-cli) on project openfasttrace-reporter-plaintext: Could not copy D:\a\openfasttrace\openfasttrace\reporter\plaintext\target\openfasttrace-reporter-plaintext-3.8.0.buildcompareto D:\a\openfasttrace\openfasttrace\target\openfasttrace-root-0.0.0.buildcompare"
-      if: ${{ matrix.os != 'windows-latest' }}
-      run: |
-        mvn --batch-mode -T 1C clean verify artifact:compare -DskipTests \
-            -Djava.version=${{ matrix.java }}
-
-    - name: Archive aggregated reproducible build report
-      uses: actions/upload-artifact@v4
-      if: ${{ matrix.os != 'windows-latest' }}
-      with:
-        name: reproducible-build-report-${{ matrix.os }}-java-${{ matrix.java }}
-        path: |
-          target/openfasttrace-root-0.0.0.buildcompare
-          target/openfasttrace-root-0.0.0.buildinfo
-        if-no-files-found: error
-
-    - name: Archive oft binary
-      uses: actions/upload-artifact@v4
-      if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
-      with:
-        name: openfasttrace-binaries
-        path: |
-          product/target/openfasttrace-*.jar
-          !product/target/openfasttrace-*-javadoc.jar
-          !product/target/openfasttrace-*-sources.jar
-        if-no-files-found: error
-
-    - name: Run self-trace
-      run: ./oft-self-trace.sh
-
-    - name: Upload self-tracing report
-      uses: actions/upload-artifact@v4
-      if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
-      with:
-        name: self-tracing-report
-        path: target/self-trace-report.html
-        if-no-files-found: error
-
-    - name: Check shell scripts
-      if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
-      run: .github/workflows/run_shellcheck.sh 
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-java@v4
+        name: Set up Java ${{ matrix.java }}
+        with:
+          distribution: "temurin"
+          java-version: ${{ matrix.java }}
+          cache: "maven"
+
+      - name: Cache SonarQube packages
+        if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
+        uses: actions/cache@v4
+        with:
+          path: ~/.sonar/cache
+          key: ${{ runner.os }}-sonar
+          restore-keys: ${{ runner.os }}-sonar
+
+      - name: Build with Java ${{ matrix.java }}
+        run: |
+          mvn --batch-mode -T 1C clean org.jacoco:jacoco-maven-plugin:prepare-agent install \
+              -Djava.version=${{ matrix.java }}
+
+      - name: Sonar analysis
+        if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java && env.SONAR_TOKEN != null }}
+        run: |
+          mvn --batch-mode org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
+              -Dsonar.token=$SONAR_TOKEN
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+      - name: Verify reproducible build
+        # Build fails on Windows with error "Failed to execute goal org.apache.maven.plugins:maven-artifact-plugin:3.5.0:compare (default-cli) on project openfasttrace-reporter-plaintext: Could not copy D:\a\openfasttrace\openfasttrace\reporter\plaintext\target\openfasttrace-reporter-plaintext-3.8.0.buildcompareto D:\a\openfasttrace\openfasttrace\target\openfasttrace-root-0.0.0.buildcompare"
+        if: ${{ matrix.os != 'windows-latest' }}
+        run: |
+          mvn --batch-mode -T 1C clean verify artifact:compare -DskipTests \
+              -Djava.version=${{ matrix.java }}
+
+      - name: Archive aggregated reproducible build report
+        uses: actions/upload-artifact@v4
+        if: ${{ matrix.os != 'windows-latest' }}
+        with:
+          name: reproducible-build-report-${{ matrix.os }}-java-${{ matrix.java }}
+          path: |
+            target/openfasttrace-root-0.0.0.buildcompare
+            target/openfasttrace-root-0.0.0.buildinfo
+          if-no-files-found: error
+
+      - name: Archive oft binary
+        uses: actions/upload-artifact@v4
+        if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
+        with:
+          name: openfasttrace-binaries
+          path: |
+            product/target/openfasttrace-*.jar
+            !product/target/openfasttrace-*-javadoc.jar
+            !product/target/openfasttrace-*-sources.jar
+          if-no-files-found: error
+
+      - name: Run self-trace
+        run: ./oft-self-trace.sh
+
+      - name: Upload self-tracing report
+        uses: actions/upload-artifact@v4
+        if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
+        with:
+          name: self-tracing-report
+          path: target/self-trace-report.html
+          if-no-files-found: error
+
+      - name: Check shell scripts
+        if: ${{ env.DEFAULT_OS == matrix.os && env.DEFAULT_JAVA == matrix.java }}
+        run: .github/workflows/run_shellcheck.sh
 
   build:
     needs: matrix-build

.github/workflows/codeql-analysis.yml

@@ -2,11 +2,11 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
   schedule:
-    - cron: '0 4 * * 3'
+    - cron: "0 4 * * 3"
 
 jobs:
   analyze:
@@ -21,22 +21,22 @@ jobs:
       cancel-in-progress: true
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
-    - uses: actions/setup-java@v4
-      with:
-        distribution: 'temurin'
-        java-version: 17
-        cache: 'maven'
+      - uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: 17
+          cache: "maven"
 
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
-      with:
-        languages: java
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: java
 
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
 
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.github/workflows/gh-pages.yml

@@ -4,9 +4,6 @@ on:
   push:
     branches: ["main"]
   workflow_dispatch:
-  # Temporarily also run on pull requests
-  pull_request:
-    branches: ["main"]
 
 permissions:
   contents: read

.vscode/launch.json

@@ -0,0 +1,34 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "java",
+            "name": "Run Self-Trace",
+            "request": "launch",
+            "mainClass": "org.itsallcode.openfasttrace.core.cli.CliStarter",
+            "projectName": "openfasttrace",
+            "args": [
+                "trace",
+                "--log-level",
+                "INFO",
+                "${workspaceFolder}/doc/spec",
+                "${workspaceFolder}/importer/lightweightmarkup/src",
+                "${workspaceFolder}/importer/markdown/src",
+                "${workspaceFolder}/importer/restructuredtext/src",
+                "${workspaceFolder}/importer/specobject/src",
+                "${workspaceFolder}/importer/zip/src",
+                "${workspaceFolder}/importer/tag/src",
+                "${workspaceFolder}/core/src/main",
+                "${workspaceFolder}/core/src/test/java",
+                "${workspaceFolder}/reporter/plaintext/src",
+                "${workspaceFolder}/reporter/html/src",
+                "${workspaceFolder}/reporter/aspec/src",
+                "${workspaceFolder}/product/src/test/java",
+                "${workspaceFolder}/api/src",
+                "${workspaceFolder}/exporter/specobject/src",
+                "${workspaceFolder}/exporter/common/src",
+                "${workspaceFolder}/testutil/src"
+            ]
+        }
+    ]
+}

README.md

@@ -32,6 +32,7 @@ Sonarcloud status:
 **User Guides**
 
 * [📖 User Guide](doc/user_guide.md)
+* [🔌 Extending OpenFastTrace With Plugins](doc/plugins.md)
 * [💲 Command Line Usage](core/src/main/resources/usage.txt)
 
 **News and Discussions**
@@ -47,6 +48,7 @@ Sonarcloud status:
 
 * [🎟️ Project Board](https://github.com/orgs/itsallcode/projects/3/views/1)
 * [🦮 Developer Guide](doc/developer_guide.md)
+* [🔌 Plugin Developer Guide](doc/plugin_developer_guide.md)
 * [🎁 Contributing Guide](CONTRIBUTING.md)
 * [💡 System Requirements](doc/spec/system_requirements.md)
 * [👜 Design](doc/spec/design.md)

api/src/main/java/org/itsallcode/openfasttrace/api/importer/MultiFileImporter.java

@@ -26,8 +26,8 @@ public interface MultiFileImporter
     MultiFileImporter importFile(InputFile file);
 
     /**
-     * Import from the path, independently of whether it is represents a
-     * directory or a file.
+     * Import from the path, independently of whether it represents a directory
+     * or a file.
      * 
      * @param paths
      *            lists of paths to files or directories

core/src/main/java/module-info.java

@@ -10,12 +10,13 @@
     exports org.itsallcode.openfasttrace.core;
     exports org.itsallcode.openfasttrace.core.cli;
     exports org.itsallcode.openfasttrace.core.cli.commands;
+    exports org.itsallcode.openfasttrace.core.cli.logging;
     exports org.itsallcode.openfasttrace.core.report;
     exports org.itsallcode.openfasttrace.core.exporter;
     exports org.itsallcode.openfasttrace.core.importer;
     exports org.itsallcode.openfasttrace.core.serviceloader;
 
-    requires java.logging;
+    requires transitive java.logging;
     requires transitive org.itsallcode.openfasttrace.api;
 
     uses org.itsallcode.openfasttrace.api.exporter.ExporterFactory;

core/src/main/java/org/itsallcode/openfasttrace/core/ServiceFactory.java

@@ -13,7 +13,6 @@
 import org.itsallcode.openfasttrace.core.importer.ImporterServiceImpl;
 import org.itsallcode.openfasttrace.core.report.ReportService;
 import org.itsallcode.openfasttrace.core.report.ReporterFactoryLoader;
-import org.itsallcode.openfasttrace.core.serviceloader.InitializingServiceLoader;
 
 class ServiceFactory
 {
@@ -25,15 +24,12 @@ ExporterService createExporterService()
     ImporterService createImporterService(final ImportSettings settings)
     {
         final ImporterContext context = new ImporterContext(settings);
-        final InitializingServiceLoader<ImporterFactory, ImporterContext> serviceLoader = InitializingServiceLoader
-                .load(ImporterFactory.class, context);
-        final ImporterService service = new ImporterServiceImpl(
-                new ImporterFactoryLoader(serviceLoader), settings);
+        final ImporterService service = new ImporterServiceImpl(new ImporterFactoryLoader(context), settings);
         context.setImporterService(service);
         return service;
     }
 
-    Linker createLinker(List<SpecificationItem> items)
+    Linker createLinker(final List<SpecificationItem> items)
     {
         return new Linker(items);
     }