From 3b44e9950883a17218b8c923a238a850681c5c6f Mon Sep 17 00:00:00 2001
From: DMI <david.maier@schmalz.de>
Date: Wed, 3 Jun 2026 14:38:39 +0000
Subject: [PATCH] feat: add vacuum-lint action with documentation

---
 vacuum-lint/README.md  | 25 ++++++++++++++++
 vacuum-lint/action.yml | 65 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 vacuum-lint/README.md
 create mode 100644 vacuum-lint/action.yml

diff --git a/vacuum-lint/README.md b/vacuum-lint/README.md
new file mode 100644
index 0000000..4193a98
--- /dev/null
+++ b/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`.
diff --git a/vacuum-lint/action.yml b/vacuum-lint/action.yml
new file mode 100644
index 0000000..222640a
--- /dev/null
+++ b/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 ""