Generate analysis results references documentation

.github/workflows/internal-report-reference-documentation.yml

@@ -0,0 +1,76 @@
+name: Generate report reference documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "analysis-results/**" # Only run on changed analysis results
+      - "!analysis-results/*.md" # Ignore report reference documentation changes (endless loop prevention)
+      - ".github/workflows/internal-report-reference-documentation.yml" # Also run when this file was changed
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "analysis-results/**" # Only run on changed analysis results
+      - "!analysis-results/*.md" # Ignore report reference documentation changes (endless loop prevention)
+      - ".github/workflows/internal-report-reference-documentation.yml" # Also run when this file was changed
+
+jobs:
+  generate-report-reference-documentation:
+    runs-on: ubuntu-latest
+    outputs:
+      generated_documents_changed: ${{ steps.set-generated_documents_changed.outputs.generated_documents_changed }}
+      documentation-upload-name: ${{ steps.set-documentation-upload-name.outputs.documentation-upload-name }}
+
+    steps:
+      - name: Checkout git repository
+        uses: actions/checkout@v4
+
+      - name: Generate report reference document
+        working-directory: analysis-results
+        run: |
+          ./../documentation/analysis-reports-reference/generateReportReferences.sh
+
+      - name: Use git to detect changes in the regenerated documentation and set generated_documents_changed
+        working-directory: analysis-results
+        id: set-generated_documents_changed
+        run: |
+          git diff --quiet || echo "generated_documents_changed=true" >> "$GITHUB_OUTPUT"
+          git --no-pager diff --name-only
+
+      - name: Display generated_documents_changed
+        run: echo "generated_documents_changed=${{ steps.set-generated_documents_changed.outputs.generated_documents_changed }}"
+
+      - name: Generate ARTIFACT_UPLOAD_ID
+        if: steps.set-generated_documents_changed.outputs.generated_documents_changed == 'true'
+        run: echo "ARTIFACT_UPLOAD_ID=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 10)" >> $GITHUB_ENV
+
+      - name: Set documentation-upload-name
+        if: steps.set-generated_documents_changed.outputs.generated_documents_changed == 'true'
+        id: set-documentation-upload-name
+        run: echo "documentation-upload-name=report-reference-documentation-${{ env.ARTIFACT_UPLOAD_ID }}" >> "$GITHUB_OUTPUT"
+
+      - name: Archive generated report references documents
+        if: steps.set-generated_documents_changed.outputs.generated_documents_changed == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.set-documentation-upload-name.outputs.documentation-upload-name }}
+          path: ./analysis-results/*.md
+          if-no-files-found: error
+          retention-days: 5
+
+
+  commit-analysis-results:
+    name: Commit Analysis Results
+    needs: [generate-report-reference-documentation]
+    uses: ./.github/workflows/internal-commit-results.yml
+    if: needs.generate-report-reference-documentation.outputs.generated_documents_changed == 'true'
+    with:
+      commit-author-name: "${{ github.event.repository.name }} Continuous Integration"
+      commit-author-email: "7671054+JohT@users.noreply.github.com"
+      commit-message: "Automated code structure analysis results (CI)"
+      commit-directory: "./analysis-results/*.md"
+      uploaded-artifact-name: ${{ needs.generate-report-reference-documentation.outputs.documentation-upload-name }}
+    secrets:
+      repository-commit-token: ${{ secrets.WORKFLOW_GIT_ACCESS_TOKEN }}

.github/workflows/java-code-analysis.yml

@@ -7,6 +7,7 @@ on:
     # Ignore changes in documentation, general configuration and analysis-results for push events
     paths-ignore: 
       - 'analysis-results/**'
+      - 'documentation/**'
       - '**/*.md'
       - '**/*.txt'
       - '**/*.css'
@@ -24,6 +25,7 @@ on:
     # Ignore changes in documentation, general configuration and analysis-results for pull request events
     paths-ignore: 
       - 'analysis-results/**'
+      - 'documentation/**'
       - '**/*.md'
       - '**/*.txt'
       - '**/*.css'

.github/workflows/typescript-code-analysis.yml

@@ -7,6 +7,7 @@ on:
     # Ignore changes in documentation, general configuration and analysis-results for push events
     paths-ignore: 
       - 'analysis-results/**'
+      - 'documentation/**'
       - '**/*.md'
       - '**/*.txt'
       - '**/*.css'
@@ -24,6 +25,7 @@ on:
     # Ignore changes in documentation, general configuration and analysis-results for pull request events
     paths-ignore: 
       - 'analysis-results/**'
+      - 'documentation/**'
       - '**/*.md'
       - '**/*.txt'
       - '**/*.css'

COMMANDS.md

@@ -0,0 +1,42 @@
+# Code Graph Analysis Pipeline - Commands
+
+<!-- TOC -->
+
+- [Generate Markdown References](#generate-markdown-references)
+    - [Generate CSV Cypher Query Results Report Reference](#generate-csv-cypher-query-results-report-reference)
+    - [Generate Jupyter Notebook Report Reference](#generate-jupyter-notebook-report-reference)
+    - [Generate Image Reference](#generate-image-reference)
+
+<!-- /TOC -->
+
+## Generate Markdown References
+
+### Generate CSV Cypher Query Results Report Reference
+
+Change into the [analysis-results](./analysis-results/) directory e.g. with `cd analysis-results` and then execute the script [generateCsvReportReference.sh](./documentation/analysis-reports-reference/generateCsvReportReference.sh) with the following command:
+
+👉**Note:** This script is automatically triggered in the pipeline [internal-report-reference-documentation.yml](.github/workflows/internal-report-reference-documentation.yml) and doesn't need to be executed manually normally.
+
+```script
+./../documentation/analysis-reports-reference/generateCsvReportReference.sh
+```
+
+### Generate Jupyter Notebook Report Reference
+
+Change into the [analysis-results](./analysis-results/) directory e.g. with `cd analysis-results` and then execute the script [generateJupyterReportReference.sh](./documentation/analysis-reports-reference/generateJupyterReportReference.sh) with the following command:
+
+👉**Note:** This script is automatically triggered in the pipeline [internal-report-reference-documentation.yml](.github/workflows/internal-report-reference-documentation.yml) and doesn't need to be executed manually normally.
+
+```script
+./../documentation/analysis-reports-reference/generateJupyterReportReference.sh
+```
+
+### Generate Image Reference
+
+Change into the [analysis-results](./analysis-results/) directory e.g. with `cd analysis-results` and then execute the script [generateImageReference.sh](./documentation/analysis-reports-reference/generateImageReference.sh) with the following command:
+
+👉**Note:** This script is automatically triggered in the pipeline [internal-report-reference-documentation.yml](.github/workflows/internal-report-reference-documentation.yml) and doesn't need to be executed manually normally.
+
+```script
+./../documentation/analysis-reports-reference/generateImageReference.sh
+```

README.md

@@ -83,6 +83,18 @@ Here are ten examples from over a hundred reports generated by the analysis. The
 
 <img src="./analysis-results/AxonFramework/AxonFramework-4.10.3/wordcloud/Wordcloud_files/Wordcloud_17_0.png" width="600" alt="Word cloud of git authors">
 
+## :page_with_curl: CSV Cypher Query Report Reference
+
+[CSV_REPORTS.md](./analysis-results/CSV_REPORTS.md) lists all CSV Cypher query result reports inside the [results](./results) directory. It can be generated as described in [Generate CSV Report Reference](./COMMANDS.md#generate-csv-cypher-query-report-reference).
+
+## :page_with_curl: Jupyter Notebook Report Reference
+
+[JUPYTER_REPORTS.md](./analysis-results/JUPYTER_REPORTS.md) lists all Jupyter Notebook reports inside the [results](./results) directory. It can be generated as described in [Generate Jupyter Notebook Report Reference](./COMMANDS.md#generate-jupyter-notebook-report-reference).
+
+## :camera: Image Reference
+
+[IMAGES.md](./analysis-results/IMAGES.md) lists all PNG images inside the [results](./results) directory. It can be generated as described in [Generate Image Reference](./COMMANDS.md#generate-image-reference).
+
 ## Keeping the Analysis Workflow Updated with Renovate
 
 This repository uses [Renovate](https://docs.renovatebot.com) to automatically update the analysis workflow to the latest version. To enable this, add the following extension to your Renovate configuration: