[#10] Add support for filtering spec items using OFT tags (#11)

The OFT Action has been extended to support a new input parameter
for specifying tag values which are passed on to the run-oft.sh script.

Author: sophokles73

.github/workflows/requirements-tracing.yaml

@@ -23,7 +23,7 @@ jobs:
         with:
           report-filename: ${{ env.REPORT_FILENAME }}
           report-format: "html"
-          file-patterns: "."
+          file-patterns: ${{ github.workspace }}
 
       - name: Upload tracing report
         id: upload-report

Dockerfile

@@ -1,5 +1,7 @@
 # [impl->req~run-oft-trace-command~1]
 FROM eclipse-temurin:22-jre-alpine
+# alpine comes with sh only, by default
+RUN apk add --no-cache bash
 
 ARG OFT_CORE_VERSION=4.1.0
 ARG OFT_ASCIIDOC_PLUGIN_VERSION=0.2.0
@@ -13,6 +15,6 @@ wget -P $LIB_DIR ${base_url}/openfasttrace/releases/download/$OFT_CORE_VERSION/o
 wget -P $LIB_DIR ${base_url}/openfasttrace-asciidoc-plugin/releases/download/$OFT_ASCIIDOC_PLUGIN_VERSION/openfasttrace-asciidoc-plugin-$OFT_ASCIIDOC_PLUGIN_VERSION-with-dependencies.jar
 EOF
 
-COPY run-oft.sh /opt/oft/run-oft.sh 
+COPY run-oft.sh /opt/oft/run-oft.sh
 
 ENTRYPOINT [ "/opt/oft/run-oft.sh" ]

README.md

@@ -6,15 +6,57 @@ Runs OpenFastTrace CLI's `trace` command using Temurin JRE 22 on the local works
 
 The action has the following inputs:
 
-| Name              | Required | Description                                                                                                                                                                                                                                         |
-| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `file-patterns`   | `false`  | A whitespace separated list of (Bash standard) glob patterns which specify the files and directories to include in the OFT trace run.<br>If not specified, the local workspace directory is used.                                                   |
-| `report-filename` | `true`   | The name of the file that OpenFastTrace should write the analysis results to.                                                                                                                                                                       |
-| `report-format`   | `false`  | The format of the report that OpenFastTrace should produce. Default value is `plain`.                                                                                                                                                               |
-| `fail-on-error`   | `false`  | By default, the action will never fail but indicate the result of running the trace command in the `oft-exit-code` output variable.<br>Setting this parameter to `true` will let the Action return the exit code produced by running OpenFastTrace. |
+| Name              | Required | Description                                                                                                                                                                                                                                                                                 |
+| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `file-patterns`   | `false`  | A whitespace separated list of (Bash standard) glob patterns which specify the files and directories to include in the OFT trace run.<br>If not specified, the local workspace directory is used.                                                                                           |
+| `report-filename` | `true`   | The name of the file that OpenFastTrace should write the analysis results to.                                                                                                                                                                                                               |
+| `report-format`   | `false`  | The format of the report that OpenFastTrace should produce. Default value is `plain`.                                                                                                                                                                                                       |
+| `tags`            | `false`  | A comma separated list of tags to use for [filtering specification items](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md#distributing-the-detailing-work).<br>If not set explicitly, all specification items from files matching the file patterns are considered. |
+| `fail-on-error`   | `false`  | By default, the action will never fail but indicate the result of running the trace command in the `oft-exit-code` output variable.<br>Setting this parameter to `true` will let the Action return the exit code produced by running OpenFastTrace.                                         |
 
 The action has the following outputs:
 
 | Name            | Description                                                                                                                                                    |
 | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `oft-exit-code` | `0`: OFT has run successfully and all specification items are covered<br>`>1`: OFT has either failed to run or at least one specification item is not covered. |
+
+## Example workflow
+
+The following workflow illustrates how the action can be used to trace requirements in the local workspace. The report will always be uploaded as an attachment to the workflow run, even if the trace run fails.
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  tracing:
+    name: Run OpenFastTrace
+    runs-on: ubuntu-latest
+    env
+      TRACING_REPORT_FILE_NAME: oft-tracing-report.html
+    outputs:
+      tracing-report-url: ${{ steps.upload-tracing-report.artifact-url }}
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Run OpenFastTrace
+      id: run-oft
+      uses: itsallcode/openfasttrace-github-action@v0
+      with:
+        file-patterns: *.md *.adoc src/
+        report-format: "html"
+        report-filename: ${{ env.TRACING_REPORT_FILE_NAME }}
+        tags: Priority1,OtherComponent
+
+    - name: Upload tracing report (html)
+      uses: actions/upload-artifact@v4
+      id: upload-tracing-report
+      if: ${{ steps.run-oft.outputs.oft-exit-code != '' }}
+      with:
+        name: tracing-report-html
+        path: ${{ env.TRACING_REPORT_FILE_NAME }}
+
+    - name: "Determine exit code"
+      run: |
+        exit ${{ steps.run-oft.outputs.oft-exit-code }}
+```

action.yaml

@@ -8,7 +8,7 @@ description: |
 inputs:
   file-patterns:
     description: |
-      A whitespace separated list of (Bash standard) glob patterns which specify the files and directories to include in the OFT trace run.
+      A whitespace separated list of (standard Bash) glob patterns which specify the files and directories to include in the OFT trace run.
       If not specified, the local workspace directory is used.
     default: "."
     required: false
@@ -20,6 +20,10 @@ inputs:
     description: The format of the report that OpenFastTrace should produce.
     default: "plain"
     required: false
+  tags:
+    description: |
+      A comma separated list of tags to use for filtering specification items.
+    required: false
   fail-on-error:
     description: |
       By default, the action will never fail but indicate the result of running the trace command in the "oft-exit-code" output variable.
@@ -35,8 +39,9 @@ outputs:
 runs:
   using: "docker"
   image: "Dockerfile"
-  args:
-    - ${{ inputs.fail-on-error }}
-    - ${{ inputs.report-filename }}
-    - ${{ inputs.report-format }}
-    - ${{ inputs.file-patterns }}
+  env:
+    OFT_FILE_PATTERNS: ${{ inputs.file-patterns }}
+    OFT_REPORT_FORMAT: ${{ inputs.report-format }}
+    OFT_REPORT_FILENAME: ${{ inputs.report-filename }}
+    OFT_TAGS: ${{ inputs.tags }}
+    OFT_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}

doc/spec/system_requirements.md

@@ -33,3 +33,13 @@ Covers:
 - feat~standard-github-action~1
 
 Needs: impl
+
+### Filter specification items based on tags
+`req~filter-specitems-using-tags~1`
+
+The OFT Action supports filtering relevant specification items using OFT Tags.
+
+Covers:
+- feat~standard-github-action~1
+
+Needs: impl

run-oft.sh

@@ -1,20 +1,24 @@
-#!/bin/sh
+#!/bin/bash
 
-# [impl->req~run-oft-trace-command~1]
-fail_on_error=$1
-report_file_name=$2
-report_format=$3
-files=$4
+fail_on_error=${OFT_FAIL_ON_ERROR:-"false"}
+report_file_name=${OFT_REPORT_FILENAME:-"trace-report.txt"}
+report_format=${OFT_REPORT_FORMAT:-"plain"}
+tags=${OFT_TAGS:-""}
+file_patterns=${OFT_FILE_PATTERNS:-"."}
+
+options=(-o "$report_format" -f "$report_file_name")
+# [impl->req~filter-specitems-using-tags~1]
+if [[ -n "$tags" ]]; then
+  options=("${options[@]}" -t "$tags")
+fi
 
 echo "::notice::using OpenFastTrace JARs from: ${LIB_DIR}"
+echo "::notice::running OpenFastTrace for file patterns: $file_patterns"
 
-# Run OpenFastTrace
+# [impl->req~run-oft-trace-command~1]
 # shellcheck disable=SC2086
 # we need to provide the file patterns unquoted in order for the shell to expand any glob patterns like "*.md"
-if (java -cp "${LIB_DIR}/*" \
-  org.itsallcode.openfasttrace.core.cli.CliStarter trace -o "${report_format}" \
-  -f "${report_file_name}" \
-  ${files})
+if (java -cp "${LIB_DIR}/*" org.itsallcode.openfasttrace.core.cli.CliStarter trace "${options[@]}" $file_patterns)
 then
   echo "oft-exit-code=0" >> "${GITHUB_OUTPUT}"
   echo "All specification items are covered." >> "${GITHUB_STEP_SUMMARY}"