Add Docker based GitHub OFT Action (#1)

Author: sophokles73

.github/workflows/requirements-tracing.yaml

@@ -0,0 +1,34 @@
+name: Requirements tracing
+
+on:
+  pull_request:
+
+jobs:
+  tracing:
+    name: Run OpenFastTrace
+    runs-on: ubuntu-latest
+    outputs:
+      tracing-report-url: ${{ steps.upload-report.outputs.artifact-url }}
+    env:
+      REPORT_FILENAME: "requirements-tracing-report.html"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run OpenFastTrace
+        id: run-oft
+        uses: ./
+        with:
+          report-filename: ${{ env.REPORT_FILENAME }}
+          report-format: "html"
+          file-patterns: "."
+
+      - name: Upload tracing report
+        id: upload-report
+        uses: actions/upload-artifact@v4
+        with:
+          name: tracing-report
+          path: ${{ env.REPORT_FILENAME }}
+
+      - name: "Determine exit code"
+        run: |
+          exit ${{ steps.run-oft.outputs.oft-exit-code }}

Dockerfile

@@ -0,0 +1,18 @@
+# [impl->req~run-oft-trace-command~1]
+FROM eclipse-temurin:22-jre-alpine
+
+ARG OFT_CORE_VERSION=4.1.0
+ARG OFT_ASCIIDOC_PLUGIN_VERSION=0.2.0
+
+ENV LIB_DIR=/opt/oft/lib
+
+RUN <<EOF
+mkdir -p $LIB_DIR
+base_url=https://github.com/itsallcode
+wget -P $LIB_DIR ${base_url}/openfasttrace/releases/download/$OFT_CORE_VERSION/openfasttrace-$OFT_CORE_VERSION.jar
+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 
+
+ENTRYPOINT [ "/opt/oft/run-oft.sh" ]

README.md

@@ -1,2 +1,17 @@
 # openfasttrace-github-action
-GitHub Action for tracing requirements using OpenFastTrace
+
+A GitHub Action for tracing requirements using OpenFastTrace.
+
+Runs OpenFastTrace CLI's `trace` command using Temurin JRE 22 on the local workspace.
+
+The action has the following inputs:
+
+| Name | Description |
+| :--- | :---------- |
+
+
+The action has the following outputs:
+
+| Name                             | Description                                                                                                                                               |
+| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requirements-tracing-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. |

action.yaml

@@ -0,0 +1,35 @@
+# Perform requirements tracing against specification documents and source code using OpenFastTrace (https://github.com/itsallcode/openfasttrace)
+# Returns the URL of the created HTML report as an output
+
+# [impl->req~run-oft-trace-command~1]
+name: "Run OpenFastTrace"
+description: |
+  Runs OpenFastTrace with the `trace` command on files in the local workspace.
+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.
+      If not specified, the local workspace directory is used.
+    default: "."
+    required: false
+  report-filename:
+    description: |
+      The name of the file that OpenFastTrace should write the analysis results to.
+    required: true
+  report-format:
+    description: The format of the report that OpenFastTrace should produce.
+    default: "plain"
+    required: false
+outputs:
+  oft-exit-code:
+    description: |
+      The exit code indicating the outcome of running OpenFastTrace (0: success, 1: failure).
+      The report is created in any case, as long as OpenFastTrace could be run at all.
+
+runs:
+  using: "docker"
+  image: "Dockerfile"
+  args:
+    - ${{ inputs.report-filename }}
+    - ${{ inputs.report-format }}
+    - ${{ inputs.file-patterns }}

doc/spec/system_requirements.md

@@ -0,0 +1,32 @@
+# System Requirement Specification OpenFastTrace GitHub Action
+
+## Introduction
+
+[OpenFastTrace](https://github.com/itsallcode/openfasttrace) (OFT) is a requirement tracing suite written in Java.
+The OpenFastTrace Action wraps the execution of the OpenFastTrace `trace` command in a [GitHub Action](https://docs.github.com/en/actions).
+
+### Goals
+
+The main goal of the OFT Action is to provide an easy way to execute OpenFastTrace as part of [CI/CD pipelines implemented by means of GitHub Actions workflows](https://docs.github.com/en/actions/about-github-actions/about-continuous-integration-with-github-actions).
+
+## Features
+
+### Standard GitHub Action
+`feat~standard-github-action~1`
+
+The OFT Action is a standard GitHub Action which allows running the OpenFastTrace `trace` command on files in the local workspace.
+
+Rationale:
+
+Verifying that all requirements are covered by the code base is an important aspect of a CI build. Projects hosted on GitHub often use GitHub Actions based CI workflows. It has always been possible to run OFT from within a shell script executed as part of a workflow job. However, the script code tends to be rather boilerplate so it seems reasonable to provide a standard GitHub Action that can be used as easily as other already existing Actions.
+
+Needs: req
+
+## Functional Requirements
+
+### Run OFT trace command
+`req~run-oft-trace-command~1`
+
+The OFT Action runs the OpenFastTrace `trace` command.
+
+Needs: impl

run-oft.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# [impl->req~run-oft-trace-command~1]
+
+report_file_name=$1
+report_format=$2
+files=$3
+
+echo "::notice::using OpenFastTrace JARs from: ${LIB_DIR}"
+
+# Run OpenFastTrace
+if (java -cp "${LIB_DIR}/*" \
+  org.itsallcode.openfasttrace.core.cli.CliStarter trace -o "${report_format}" \
+  -f "${report_file_name}" \
+  ${files})
+then
+  echo "oft-exit-code=0" >> "${GITHUB_OUTPUT}"
+  echo "All specification items are covered." >> "${GITHUB_STEP_SUMMARY}"
+else
+  echo "oft-exit-code=$?" >> "${GITHUB_OUTPUT}"
+  echo "Some specification items are not covered. See created report (${report_file_name}) for details." >> "${GITHUB_STEP_SUMMARY}"
+fi