feat: add vacuum-lint action with documentation

.forgejo/workflows/tag-release.yml

@@ -29,6 +29,7 @@ on:
           - terraform-apply
           - terraform-validate
           - upload-artifact
+          - vacuum-lint
       major-version:
         description: 'Major version number (e.g. 1)'
         required: true

README.md

@@ -22,7 +22,7 @@ Shared actions for Forgejo CI/CD pipelines.
 | [terraform-apply](terraform-apply) | Apply Terraform configuration files using the official Terraform CLI |
 | [terraform-validate](terraform-validate) | Validate Terraform configuration files using the official Terraform CLI |
 | [upload-artifact](upload-artifact) | Upload files as a Forgejo Actions artifact |
-
+| [vacuum-lint](vacuum-lint) | Validate and lint OpenAPI specifications using Vacuum |
 
 ## Security
 
@@ -38,4 +38,4 @@ Reference actions from your project's workflow:
     # see each action's README for inputs
 ```
 
-Each action has its own README with inputs, usage examples, and notes.
+Each action has its own README with inputs, usage examples, and notes.

vacuum-lint/README.md

@@ -0,0 +1,25 @@
+# vacuum-lint
+
+Action for validating and linting OpenAPI specifications using [Vacuum](https://github.com/daveshanley/vacuum).
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `spec-dir` | No | `spec` | Directory containing the OpenAPI spec |
+| `spec-filename` | No | `openapi.json` | Filename of the OpenAPI spec |
+| `rules-filename` | No | `vacuum.rules.yaml` | Filename of the lint rules config file |
+| `ignore-filename` | No | `vacuum.ignore.yaml` | Filename of the lint ignore file |
+| `min-score` | No | `70` | Minimum linting score for the check to pass |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/vacuum-lint@vacuum-lint-v1
+```
+
+## Notes
+
+- If `rules-filename` is found inside `spec-dir`, it is passed to Vacuum via `-r` to apply custom rulesets; otherwise Vacuum uses its default rules.
+- If `ignore-filename` is found inside `spec-dir`, it is passed to Vacuum via `--ignore-file` to suppress known violations.
+- The action fails when the computed linting score falls below `min-score`.

vacuum-lint/action.yml

@@ -0,0 +1,65 @@
+name: Vacuum Lint
+description: >
+  Validate and lint OpenAPI specifications using Vacuum.
+
+inputs:
+  spec-dir:
+    description: Directory containing OpenAPI spec
+    required: false
+    default: "spec"
+  spec-filename:
+    description: Filename of the OpenAPI spec 
+    required: false
+    default: "openapi.json"
+  rules-filename:
+    description: Filename of the lint rules config file
+    required: false
+    default: "vacuum.rules.yaml"
+  ignore-filename:
+    description: Filename of the lint ignore file
+    required: false
+    default: "vacuum.ignore.yaml"
+  min-score:
+    description: Minimum linting score for the check to pass
+    required: false
+    default: "70"
+
+runs:
+  using: composite
+  steps:
+      # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+      - name: Install Vacuum
+        shell: bash
+        run: curl -fsSL https://raw.githubusercontent.com/daveshanley/vacuum/8222bba0c8b21a3a94faf472e06c4db06f06c6ce/bin/install.sh | sudo sh > /dev/null 2>&1
+
+      - name: Lint Spec
+        shell: bash
+        env:
+          SPEC_DIR: ${{ inputs.spec-dir }}
+          SPEC_FILE: ${{ inputs.spec-filename }}
+          RULES_FILE: ${{ inputs.rules-filename }}
+          IGNORE_FILE: ${{ inputs.ignore-filename }}
+          MIN_SCORE: ${{ inputs.min-score }}
+        run: |
+          echo "Linting: [$SPEC_DIR/$SPEC_FILE]"
+
+          # base command
+          CMD="vacuum lint $SPEC_DIR/$SPEC_FILE -x --min-score $MIN_SCORE"
+
+          # check for rules file
+          if [ -f "$SPEC_DIR/$RULES_FILE" ]; then
+              CMD="$CMD -r $SPEC_DIR/$RULES_FILE"
+              echo "  - using ruleset [$SPEC_DIR/$RULES_FILE]"
+          fi
+
+          # check for ignore file
+          if [ -f "$SPEC_DIR/$IGNORE_FILE" ]; then
+              CMD="$CMD --ignore-file $SPEC_DIR/$IGNORE_FILE"
+              echo "  - using ignore file [$SPEC_DIR/$IGNORE_FILE]"
+          fi
+
+          # execute command
+          $CMD
+    
+          echo "Linted: [$SPEC_DIR/$SPEC_FILE]"
+          echo ""