{"_id":"@api-common/governance-pipeline-auditor","_rev":"2-61b59845d815ef215877e59e79bc33ee","name":"@api-common/governance-pipeline-auditor","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@api-common/governance-pipeline-auditor","version":"0.1.0","keywords":["spectral","api-governance","ci","github-actions","pipeline","linting","maturity","audit","api-commons"],"author":{"url":"https://apievangelist.com","name":"API Evangelist"},"license":"Apache-2.0","_id":"@api-common/governance-pipeline-auditor@0.1.0","maintainers":[{"name":"api-commons","email":"info@apicommons.org"}],"homepage":"https://auditor.apicommons.org","bugs":{"url":"https://github.com/api-commons/governance-pipeline-auditor/issues"},"bin":{"gpa":"bin/cli.js","governance-pipeline-auditor":"bin/cli.js"},"dist":{"shasum":"75ab8664131b718c985aa239d6cc665d3b15def6","tarball":"https://registry.npmjs.org/@api-common/governance-pipeline-auditor/-/governance-pipeline-auditor-0.1.0.tgz","fileCount":11,"integrity":"sha512-zKKyOpeaq48n+TJ4KtPOQbDYLL4Gs0waRZdLdC9Nk184xeR1y3wV5ORkxvYAOBMaw//nLdpT33R9PwQw0B7mSA==","signatures":[{"sig":"MEYCIQC5Kotk3oYWZZCWkwWkxTsjZuZktI/I8O2pUWQTqQZpQQIhAJb42zqALMDTuaudX/Omr5MD+BAYOobww3PezGt2gn05","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60429},"type":"module","engines":{"node":">=18"},"exports":{".":"./src/audit.js","./report":"./src/report-html.js"},"gitHead":"9b5b9fa6c9524926478eb381fd389f2f0ce4986c","scripts":{"cli":"node bin/cli.js","dev":"vite","test":"node --test","build":"vite build","preview":"vite preview","build:site":"vite build"},"_npmUser":{"name":"api-commons","email":"info@apicommons.org"},"repository":{"url":"git+https://github.com/api-commons/governance-pipeline-auditor.git","type":"git"},"_npmVersion":"11.6.2","description":"Lint your linting: audit a repo's API-governance CI setup against an 8-point maturity rubric and get a prioritized punch-list of fixes. The sequel to spectral-reporter. An API Commons tool.","directories":{},"_nodeVersion":"25.2.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.4.11","typescript":"^5.7.2"},"_npmOperationalInternal":{"tmp":"tmp/governance-pipeline-auditor_0.1.0_1783113459999_0.8799697148478425","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@api-common/governance-pipeline-auditor","version":"0.1.1","description":"Lint your linting: audit a repo's API-governance CI setup against an 8-point maturity rubric and get a prioritized punch-list of fixes. The sequel to spectral-reporter. An API Commons tool.","type":"module","license":"Apache-2.0","author":{"name":"API Evangelist","url":"https://apievangelist.com"},"homepage":"https://auditor.apicommons.org","repository":{"type":"git","url":"git+https://github.com/api-commons/governance-pipeline-auditor.git"},"bugs":{"url":"https://github.com/api-commons/governance-pipeline-auditor/issues"},"keywords":["spectral","api-governance","ci","github-actions","pipeline","linting","maturity","audit","api-commons"],"bin":{"governance-pipeline-auditor":"bin/cli.js","gpa":"bin/cli.js"},"exports":{".":"./src/audit.js","./report":"./src/report-html.js"},"engines":{"node":">=18"},"scripts":{"test":"node --test","dev":"vite","build:site":"vite build","build":"vite build","preview":"vite preview","cli":"node bin/cli.js"},"devDependencies":{"typescript":"^5.7.2","vite":"^5.4.11"},"publishConfig":{"access":"public"},"gitHead":"8b146e03bbea8dc328c8c6acb8e9e76662dbb31e","_id":"@api-common/governance-pipeline-auditor@0.1.1","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-vVACV1LJfJHHs45TnR3xnTXyc7C//nzNBcJ1F7VFqLuwT8+qqZGeuGoNQ7mDXP2drHzOHFNYJHV+ULrJ6xblFA==","shasum":"5a6180065985e349239db843fd816edf492a7031","tarball":"https://registry.npmjs.org/@api-common/governance-pipeline-auditor/-/governance-pipeline-auditor-0.1.1.tgz","fileCount":11,"unpackedSize":61220,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDCV2ZwzhkY8b/dADLVv2j9vCvJ4wTCIJVImTlH1lLraAiB6EcKIwyTvTWMjU7+fDXuYAtpuYh41Dk8UK4+Ur8Yuew=="}]},"_npmUser":{"name":"api-commons","email":"info@apicommons.org"},"directories":{},"maintainers":[{"name":"api-commons","email":"info@apicommons.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/governance-pipeline-auditor_0.1.1_1784235173979_0.9904319675399136"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T21:17:39.903Z","modified":"2026-07-16T20:52:54.244Z","0.1.0":"2026-07-03T21:17:40.127Z","0.1.1":"2026-07-16T20:52:54.111Z"},"bugs":{"url":"https://github.com/api-commons/governance-pipeline-auditor/issues"},"author":{"name":"API Evangelist","url":"https://apievangelist.com"},"license":"Apache-2.0","homepage":"https://auditor.apicommons.org","keywords":["spectral","api-governance","ci","github-actions","pipeline","linting","maturity","audit","api-commons"],"repository":{"type":"git","url":"git+https://github.com/api-commons/governance-pipeline-auditor.git"},"description":"Lint your linting: audit a repo's API-governance CI setup against an 8-point maturity rubric and get a prioritized punch-list of fixes. The sequel to spectral-reporter. An API Commons tool.","maintainers":[{"name":"api-commons","email":"info@apicommons.org"}],"readme":"# Governance Pipeline Auditor\n\n**Lint your linting.** `@api-common/governance-pipeline-auditor` scans a repo's\n[Spectral](https://github.com/stoplightio/spectral) API-governance CI setup,\nscores it against an **8-point maturity rubric**, and hands back a **prioritized\npunch-list** of concrete fixes — each with a one-line *why* and a docs link.\n\nIt is the sequel to [Spectral Reporter](https://reporter.apicommons.org):\nthat reports on your **API**; this reports on your **pipeline**.\n\nThe rubric is lifted straight from the API Evangelist paper\n*\"The State of Spectral in API Pipelines,\"* a census of **1,005 real public\npipelines** where the maturity ceiling was 6/8 and nobody reached 7 or 8.\n\n- **Live demo:** https://auditor.apicommons.org\n- **An [API Commons](https://apicommons.org/tools/) tool** — free and open under Apache-2.0.\n\n---\n\n## The 8-point rubric\n\nOne point per signal. It deliberately measures only the **mechanical** surface a\nworkflow file exposes — the automatable quarter of governance. It says nothing\nabout whether a human wrote the rules on purpose, which is the three-quarters no\nfile census can see.\n\n| Signal | Question it answers |\n| --- | --- |\n| **Gates the PR** | Does governance fire before the merge, not after? |\n| **Custom ruleset** | Are the rules the organization's, not the tool's defaults? |\n| **Owned ruleset home** | Do the rules live in a dedicated dir or a shared/remote source? |\n| **Pinned tooling** | Is the enforcing tool pinned to a chosen version (SHA)? |\n| **Security layer** | Are OWASP/security rules present, not just style? |\n| **Real gate** | Does it fail the build on error rather than only annotate? |\n| **Path-filtered** | Does it run only when the spec/ruleset changes? |\n| **Machine-readable report** | Does it emit SARIF / a readable report / PR comment? |\n\nIt also flags the named anti-patterns from the paper: the default ruleset,\n`@latest` / floating pins, linting after the merge, toothless\n`continue-on-error`, and rules with no `documentationUrl`.\n\n### Maturity bands\n\n`8` Blueprint · `6–7` Strong · `4–5` Developing · `2–3` Thin · `0–1` Nominal.\n\n---\n\n## CLI usage\n\n```bash\n# Run it now, no install — audit the current repo\nnpx @api-common/governance-pipeline-auditor .\n\n# Short alias\nnpx @api-common/governance-pipeline-auditor . --json\ngpa .\n\n# Gate a pipeline: exit non-zero below the threshold\nnpx @api-common/governance-pipeline-auditor . --min-score 5\n\n# Write a self-contained HTML report\nnpx @api-common/governance-pipeline-auditor . --html governance-audit.html\n```\n\nPoint it at any repo path (default: the current directory). It finds\n`.github/workflows/*.y{a}ml` that run Spectral and any `.spectral.*` rulesets\n(including `.config/spectral/`, `tools/spectral/`, `rulesets/`), then prints the\nscore, per-signal PASS/FAIL with evidence, and the punch-list.\n\n### Flags\n\n| Flag | Effect |\n| --- | --- |\n| `--json` | Print the full audit as JSON. |\n| `--html <file>` | Write a self-contained HTML report (styled like Spectral Reporter). |\n| `--summary <file>` | Append a GitHub-flavored Markdown summary (for `$GITHUB_STEP_SUMMARY`). |\n| `--min-score <N>` | Exit non-zero if the score is below N — so it can gate a pipeline. |\n| `-h, --help` · `--version` | The usual. |\n\nInstall as a dev dependency instead of `npx`:\n\n```bash\nnpm install --save-dev @api-common/governance-pipeline-auditor\n```\n\n---\n\n## GitHub Action\n\nA composite action wraps the CLI so a team gets the score in the job summary and\na hard gate on the score:\n\n```yaml\n- uses: api-commons/governance-pipeline-auditor@v1\n  with:\n    path: .\n    min-score: 5            # fail the job below 5/8 (omit to never fail)\n    html: governance-audit.html\n- uses: actions/upload-artifact@v4\n  with:\n    name: governance-audit\n    path: governance-audit.html\n```\n\nThe action writes the maturity score, the signal table, and the punch-list to\n`$GITHUB_STEP_SUMMARY`, and exits non-zero when the score is below `min-score`.\n\n---\n\n## The shared scorer\n\nThe scoring logic is a single pure, dependency-free function —\n[`src/audit.js`](src/audit.js):\n\n```js\nimport { auditRepo } from '@api-common/governance-pipeline-auditor';\n\nconst audit = auditRepo([\n  { name: '.github/workflows/ci.yml', content: workflowYaml, kind: 'workflow' },\n  { name: '.spectral.yaml', content: rulesetYaml, kind: 'ruleset' },\n]);\n// -> { score, maxScore, maturity, signals, punchlist, antiPatterns, meta }\n```\n\nIt is imported verbatim by **all three** surfaces:\n\n- **the CLI** (`bin/cli.js`) — after [`src/collect.js`](src/collect.js) reads the files off disk;\n- **the GitHub Action** (`action.yml`) — via the CLI;\n- **the browser demo** ([`src/site.ts`](src/site.ts)) — the paste-in live demo.\n\nSo the score you see in the browser is byte-for-byte what CI produces. The HTML\nreport is likewise a shared pure renderer ([`src/report-html.js`](src/report-html.js),\nexported as `@api-common/governance-pipeline-auditor/report`).\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm test          # node:test — scores both fixtures, checks the punch-list\nnpm run dev       # the Vite demo site locally\nnpm run build     # build the site to dist/\n```\n\nFixtures in [`fixtures/`](fixtures/) model the two ends of the corpus: a\n`good-repo` that assembles the paper's blueprint (scores 8/8) and a `bad-repo`\nthat is the median row — default ruleset, `@latest`, no PR gate,\n`continue-on-error` (scores 0/8).\n\n---\n\n## TODOs (for the human who converges this)\n\n- **GitHub:** create `api-commons/governance-pipeline-auditor`, push, tag `v1`\n  (the Action reference above assumes a `v1` tag / major-version branch).\n- **npm:** publish `@api-common/governance-pipeline-auditor` (scope is\n  **`@api-common`**, singular; `publishConfig.access` is already `public`).\n- **DNS:** point `auditor.apicommons.org` at GitHub Pages (CNAME is committed at\n  the repo root and in `public/`), then enable Pages via the `deploy` workflow.\n- **Cross-linking:** add this tool to the `apicommons.org/tools/` page and to the\n  footer tool list on the sibling tools.\n\n---\n\n## About\n\nA project of [API Evangelist](https://apievangelist.com), maintained openly\nunder [API Commons](https://apicommons.org). The tools are free and open; API\nEvangelist offers expert [governance services](https://apievangelist.com/services/)\n— pipelines, rulesets, reviews, and policy — when you want experts in the loop.\n\nLicensed under [Apache-2.0](LICENSE).\n\n**Governance guidance** — the human *why* behind this tool: [Pipeline Maturity](https://guidance.apievangelist.com/store/pipeline-maturity/) at guidance.apievangelist.com.\n","readmeFilename":"README.md"}