specshield 3.3.6 → 3.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # SpecShield CLI changelog
 
+## 3.4.0 — 2026-07-29 — `govern` command (API governance in the CLI)
+
+### Added
+
+- **`specshield govern <spec>` — API governance & linting from the CLI.** Scores an
+  OpenAPI spec against SpecShield's governance rules (OWASP + design) via the hosted
+  gate (`POST /api/governance/gate`) and prints findings (grouped by severity, with
+  rule id + location), a compliance score + A–F grade, and a PASS/FAIL verdict.
+  Exit codes match the other gates: `0` pass · `1` fail · `2` error.
+  - Flags: `--ruleset <path>` (lint against a Spectral-format ruleset file),
+    `--min-score <n>`, `--fail-on-warning`, `--no-fail-on-error`, `--org <key>`
+    (apply the org's active waivers), `--advisory` (report but never fail CI),
+    `--json`, `--output <file>`, `--api-token`, `--server`.
+  - Team plan and above (needs an API key); free/unauthed callers get a friendly
+    "requires a paid plan" message and exit `2`.
+- README: new **Governance** section + command reference; the "API governance"
+  use case now points at `specshield govern` instead of "not a CLI command yet".
+
 ## 3.3.6 — 2026-07-28 — Docs & platform positioning
 
 Documentation-only release — **no CLI behavior change**; existing CI keeps working.

package/README.md

@@ -17,6 +17,9 @@
 **Commands — local & hosted compare**
 - [Local Compare](#local-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
 
+**Governance — lint & gate**
+- [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
+
 **Contract Compatibility Testing — the `bdct` commands**
 - [Overview & full command reference](#bi-directional-contract-testing-bdct)
 - [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
@@ -34,7 +37,7 @@
 
 ---
 
-> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
+> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · API Governance & Linting · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
 
 ---
 
@@ -42,15 +45,16 @@
 
 **SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
 
-It's the one CLI that does four things to keep your API safe:
+It's the one CLI that does five things to keep your API safe:
 
 1. **Diff** two OpenAPI specs and fail CI on breaking changes.
 2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
-3. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
-4. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
+3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations.
+4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
+5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
 
 ```
-OpenAPI diff  +  contract compatibility checks  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
+OpenAPI diff  +  contract compatibility checks  +  API governance  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
 ```
 
 No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.
@@ -210,7 +214,7 @@ specshield bdct can-i-deploy     --version $GITHUB_SHA
 - **CI/CD gating** — exit code `1` stops the pipeline automatically.
 - **Microservices contract safety** — consumers publish what they expect, providers verify they deliver it, no cross-team surprises.
 - **API drift tracking** — track how your specs change over time across the platform; know what changed, when, and by whom.
-- **API governance & linting** — score every spec against OWASP + design rules, adopt standard rule packs or bring your own ruleset, and gate PRs on violations. Available through the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/33137-specshield), the [GitHub Action](https://github.com/marketplace/actions/specshield-bdct), the [MCP server](https://github.com/specshield26/specshield-mcp-server), and the [dashboard](https://specshield.io). *(Not a `specshield` CLI command yet.)*
+- **API governance & linting** — score every spec against OWASP + design rules, bring your own Spectral ruleset, and gate PRs on violations with [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr). The same engine also powers the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/33137-specshield), the [GitHub Action](https://github.com/marketplace/actions/specshield-bdct), the [MCP server](https://github.com/specshield26/specshield-mcp-server), and the [dashboard](https://specshield.io).
 - **Provider conformance** — make sure your *running* service actually matches its published OpenAPI spec, not just on paper.
 - **Pact-free consumer contracts** — record real traffic with `capture from-har` and get an OpenAPI consumer contract without writing a single line of Pact DSL.
 
@@ -357,6 +361,68 @@ github:
 
 ---
 
+## Governance — lint a spec and gate the PR
+
+**Static API governance: score your OpenAPI spec against OWASP + design rules and fail CI on violations.** *(Team plan and above — runs on SpecShield's hosted engine, so it needs an API key.)*
+
+```bash
+# Lint against SpecShield's built-in governance rules
+specshield govern api/openapi.yaml
+
+# Lint against a Spectral-format ruleset (OWASP pack, your house style, …)
+specshield govern api/openapi.yaml --ruleset .specshield/ruleset.yaml
+
+# Gate CI: require a minimum score, and fail on warnings too
+specshield govern api/openapi.yaml --min-score 80 --fail-on-warning
+
+# Report only — print findings but never fail the build
+specshield govern api/openapi.yaml --advisory
+```
+
+Sample output:
+
+```
+  SpecShield™ Governance Report
+  ─────────────────────────────────────────
+  error    security-scheme-missing  $.paths./payments.post
+           operation has no security scheme
+           fix: add a security requirement
+  info     operation-operation-id   $.paths./health.get
+           operation is missing an operationId
+  ─────────────────────────────────────────
+  Score 74/100 · grade C  ·  1 error · 0 warning · 1 info
+
+  ✖ FAIL — governance policy not met:
+    • 1 error-severity finding
+```
+
+Exit codes: `0` = passed the gate · `1` = failed the gate · `2` = error (invalid spec, missing token, or paid-plan required).
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--ruleset <path>` | Lint against a Spectral-format ruleset file (uses the ruleset engine). | built-in rules |
+| `--min-score <n>` | Minimum compliance score (0–100) required to pass. | `70` |
+| `--fail-on-warning` | Fail the gate when any warning-severity finding is present. | off |
+| `--no-fail-on-error` | Do **not** fail the gate on error-severity findings. | fails on error |
+| `--org <key>` | Apply your org's active governance waivers to the verdict. | none |
+| `--advisory` | Report findings but always exit `0` (never fail CI). | off |
+| `--json` | Machine-readable JSON output (the full gate response). | off |
+| `--output <file>` | Also save the JSON result to a file. | — |
+| `--api-token <token>` | API token (else `SPECSHIELD_API_KEY` / stored config). | — |
+| `--server <url>` | Override the SpecShield server URL (self-hosted / staging). | `https://specshield.io` |
+
+Run it in CI right after your build:
+
+```yaml
+- name: Govern the API spec
+  env: { SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }} }
+  run: specshield govern api/openapi.yaml --min-score 80
+```
+
+> The same governance engine powers the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/33137-specshield), the [GitHub Action](https://github.com/marketplace/actions/specshield-bdct), the [MCP server](https://github.com/specshield26/specshield-mcp-server), and the [dashboard](https://specshield.io) — with catalog scorecards, waivers, and SARIF/JUnit/HTML reports.
+
+---
+
 # Bi-Directional Contract Testing (BDCT)
 
 **Compatibility without Pact's broker overhead or DSL.**
@@ -1347,6 +1413,23 @@ specshield share <reportId | base.yaml target.yaml> [options]
 | `--expires <days>` | Make the link expire after N days (default: never) |
 | `--api-key <key>` | Override stored API key |
 
+```bash
+specshield govern <spec> [options]
+```
+
+| Option | Description |
+|---|---|
+| `--ruleset <path>` | Lint against a Spectral-format ruleset file |
+| `--min-score <n>` | Minimum compliance score (0–100) to pass (default 70) |
+| `--fail-on-warning` | Fail the gate on any warning-severity finding |
+| `--no-fail-on-error` | Do not fail the gate on error-severity findings |
+| `--org <key>` | Apply the org's active governance waivers |
+| `--advisory` | Report findings but always exit 0 |
+| `--json` | Machine-readable JSON output |
+| `--output <file>` | Save the JSON result to a file |
+| `--api-token <token>` | API token (overrides env / stored config) |
+| `--server <url>` | Override SpecShield server URL |
+
 ```bash
 specshield bdct <subcommand> [options]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.3.6",
+  "version": "3.4.1",
   "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
   "main": "src/cli.js",
   "bin": {

package/src/api/bdctClient.js

@@ -108,6 +108,19 @@ async function listConsumerContracts(server, apiToken, { org, consumer, provider
   } catch (err) { throw apiError(err); }
 }
 
+/**
+ * Run the governance deploy gate on a spec. Always returns HTTP 200 with a
+ * pass/fail verdict in the body (a failed gate is a valid result, not an error),
+ * so only real failures (400 invalid spec, 402 paid-plan, 403 org, 503 disabled,
+ * network) throw. `payload` = { spec, ruleset?, policy?, orgKey? }.
+ */
+async function governanceGate(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/governance/gate', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
 module.exports = {
   publishProviderSpec,
   publishConsumerContract,
@@ -117,4 +130,5 @@ module.exports = {
   getMatrix,
   listProviderSpecs,
   listConsumerContracts,
+  governanceGate,
 };

package/src/cli.js

@@ -7,6 +7,7 @@ const initCommand = require('./commands/init');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const bdctCommand = require('./commands/bdct');
+const governCommand = require('./commands/govern');
 const historyCommand = require('./commands/history');
 const shareCommand = require('./commands/share');
 const whoamiCommand = require('./commands/whoami');
@@ -27,6 +28,7 @@ program.addCommand(initCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);
+program.addCommand(governCommand);
 program.addCommand(historyCommand);
 program.addCommand(shareCommand);
 program.addCommand(whoamiCommand);

package/src/commands/govern.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const fsExtra = require('fs-extra');
+const logger = require('../utils/logger');
+const { loadSpec } = require('../core/loadSpec');
+const { getStoredApiKey } = require('../config/localConfig');
+const { governanceGate } = require('../api/bdctClient');
+
+// Token precedence mirrors the bdct subcommands.
+async function resolveApiToken(opts) {
+  return opts.apiToken || process.env.SPECSHIELD_API_KEY || (await getStoredApiKey()) || null;
+}
+
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+
+function sevLabel(sev) {
+  const s = String(sev || '').toLowerCase();
+  if (s === 'error')   return chalk.red('error  ');
+  if (s === 'warning') return chalk.yellow('warning');
+  return chalk.blue('info   ');
+}
+
+function gradeColor(grade) {
+  const g = String(grade || '—').toUpperCase();
+  if (g === 'A' || g === 'B') return chalk.green(g);
+  if (g === 'C')              return chalk.yellow(g);
+  return chalk.red(g);
+}
+
+const govern = new Command('govern')
+  .description('Lint an OpenAPI spec against governance rules (OWASP + design) and gate the PR')
+  .argument('<spec>', 'Path to the OpenAPI spec to govern (YAML or JSON)')
+  .option('--ruleset <path>', 'Lint against a Spectral-format ruleset file (uses the ruleset engine)')
+  .option('--min-score <n>', 'Minimum compliance score (0–100) required to pass (default 70)', (v) => parseInt(v, 10))
+  .option('--fail-on-warning', 'Fail the gate when any warning-severity finding is present')
+  .option('--no-fail-on-error', 'Do NOT fail the gate on error-severity findings')
+  .option('--org <key>', 'Org key — applies your org’s active governance waivers to the verdict')
+  .option('--advisory', 'Report findings but always exit 0 (never fail CI)')
+  .option('--json', 'Output machine-readable JSON')
+  .option('--output <file>', 'Also save the JSON result to this file')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token (overrides env / stored config)')
+  .action(async (specPath, opts) => {
+    try {
+      const token = await resolveApiToken(opts);
+      if (!token) {
+        logger.error('No API token found. Pass --api-token, set SPECSHIELD_API_KEY, or run: specshield login --api-key <KEY>');
+        process.exit(2);
+      }
+
+      const spinner = opts.json ? null : ora('Loading spec...').start();
+      const specText = await loadSpec(specPath);
+      const ruleset = opts.ruleset ? await loadSpec(opts.ruleset) : null;
+
+      // Only send policy fields the user overrode; the server applies documented
+      // defaults (minScore 70, failOnError true, failOnWarning false) otherwise.
+      const policy = {};
+      if (opts.minScore !== undefined && !Number.isNaN(opts.minScore)) policy.minScore = opts.minScore;
+      if (opts.failOnWarning) policy.failOnWarning = true;
+      if (opts.failOnError === false) policy.failOnError = false; // set by --no-fail-on-error
+
+      if (spinner) spinner.text = 'Running governance review...';
+      const resp = await governanceGate(opts.server, token, {
+        spec: specText,
+        ruleset,
+        policy: Object.keys(policy).length ? policy : null,
+        orgKey: opts.org || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        const out = JSON.stringify(resp, null, 2);
+        process.stdout.write(out + '\n');
+        if (opts.output) await fsExtra.outputFile(opts.output, out);
+      } else {
+        renderHuman(resp);
+        if (opts.output) await fsExtra.outputFile(opts.output, JSON.stringify(resp, null, 2));
+      }
+
+      if (opts.advisory) process.exit(0);
+      process.exit(resp.passed ? 0 : 1);
+    } catch (err) {
+      if (err.status === 402) {
+        logger.error('API governance requires a paid plan (Team or above). See https://specshield.io/pricing');
+        process.exit(2);
+      }
+      if (err.status === 503) {
+        logger.error('Governance is not enabled on this SpecShield server.');
+        process.exit(2);
+      }
+      logger.error(`Error: ${err.message}`);
+      process.exit(2);
+    }
+  });
+
+function renderHuman(resp) {
+  const review = resp.review || {};
+  const findings = Array.isArray(review.findings) ? review.findings.slice() : [];
+  const score = review.score || {};
+
+  process.stdout.write('\n  ' + chalk.bold('SpecShield™ Governance Report') + '\n');
+  process.stdout.write('  ' + chalk.gray('─────────────────────────────────────────') + '\n');
+
+  if (findings.length === 0) {
+    process.stdout.write('  ' + chalk.green('✔ No governance findings.') + '\n');
+  } else {
+    findings.sort((a, b) =>
+      (SEV_ORDER[String(a.severity).toLowerCase()] ?? 3) - (SEV_ORDER[String(b.severity).toLowerCase()] ?? 3));
+    for (const f of findings) {
+      const loc = f.location ? chalk.gray('  ' + f.location) : '';
+      process.stdout.write(`  ${sevLabel(f.severity)}  ${chalk.cyan(f.ruleId || '')}${loc}\n`);
+      if (f.message) process.stdout.write(`           ${f.message}\n`);
+      if (f.suggestedFix) process.stdout.write(`           ${chalk.gray('fix: ' + f.suggestedFix)}\n`);
+    }
+  }
+
+  process.stdout.write('  ' + chalk.gray('─────────────────────────────────────────') + '\n');
+  const scoreVal = (score.value === undefined || score.value === null) ? '—' : score.value;
+  process.stdout.write(
+    `  Score ${chalk.bold(scoreVal)}/100 · grade ${gradeColor(score.grade)}  ·  `
+    + `${chalk.red((review.errorCount || 0) + ' error')} · `
+    + `${chalk.yellow((review.warningCount || 0) + ' warning')} · `
+    + `${chalk.blue((review.infoCount || 0) + ' info')}`
+    + (resp.waivedCount ? `  ·  ${chalk.gray(resp.waivedCount + ' waived')}` : '')
+    + '\n'
+  );
+
+  if (resp.passed) {
+    process.stdout.write('\n  ' + chalk.green.bold('✔ PASS')
+      + chalk.gray(` — meets the governance policy (min score ${resp.scoreThreshold}).`) + '\n\n');
+  } else {
+    process.stdout.write('\n  ' + chalk.red.bold('✖ FAIL') + chalk.gray(' — governance policy not met:') + '\n');
+    for (const r of (resp.reasons || [])) process.stdout.write('    ' + chalk.red('•') + ' ' + r + '\n');
+    if (resp.recommendedAction) process.stdout.write('\n  ' + chalk.gray(resp.recommendedAction) + '\n');
+    process.stdout.write('\n');
+  }
+}
+
+module.exports = govern;

package/src/core/projectConfig.js

@@ -92,9 +92,30 @@ const REQUIRED_FIELDS = {
   'list-consumers':   ['org'],
 };
 
+/**
+ * Option names that CAN be defaulted from `.specshield.yml`.
+ *
+ * Deliberately NOT every required field: `version`, `consumerVersion` and
+ * `providerVersion` are per-invocation values (a git SHA, a release tag) with no
+ * sensible project-wide default, so `bdctDefaultFor` has no case for them.
+ *
+ * This set exists so the "missing required options" error can tell the truth about
+ * where each field can be set. Pointing a user at `.specshield.yml` for a field the
+ * config can never supply sends them to edit a file, re-run, hit the identical error,
+ * and conclude the config file is broken.
+ *
+ * MUST stay in sync with the cases handled in {@link bdctDefaultFor} — the
+ * "config-backed fields" test asserts both directions.
+ */
+const CONFIG_BACKED_FIELDS = new Set([
+  'org', 'server', 'env',
+  'provider', 'consumer', 'service',
+  'spec', 'contract', 'format', 'branch',
+]);
+
 /**
  * Map a CLI option name to a path inside `.specshield.yml > bdct`.
- * Returns null when there is no defaulting rule for that option.
+ * Returns undefined when there is no defaulting rule for that option.
  */
 function bdctDefaultFor(bdct, name, command) {
   if (!bdct) return undefined;
@@ -181,14 +202,35 @@ function applyBdctDefaults(opts, command, { cwd = process.cwd() } = {}) {
   const missing  = required.filter(k => !opts[k]);
   if (missing.length > 0) {
     const flagFor = (k) => '--' + k.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+    const list = (ks) => ks.map(flagFor).join(', ');
+
+    // Split the advice: only fields the config can actually supply get pointed at
+    // `.specshield.yml`. The rest are flag-only and must say so, or the user edits
+    // the config, re-runs, and hits the same error with no idea why.
+    const configurable = missing.filter(k => CONFIG_BACKED_FIELDS.has(k));
+    const flagOnly     = missing.filter(k => !CONFIG_BACKED_FIELDS.has(k));
+
     const msg = [
       `Missing required ${missing.length === 1 ? 'option' : 'options'} for \`bdct ${command}\`: `
-        + missing.map(flagFor).join(', '),
+        + list(missing),
     ];
-    if (cfg._file) {
-      msg.push(`Set them as CLI flags or add them under \`bdct\` in ${cfg._file}.`);
-    } else {
-      msg.push('Pass them as CLI flags, or run `specshield init` to write a `.specshield.yml`.');
+
+    if (flagOnly.length > 0) {
+      msg.push(
+        `  ${list(flagOnly)} must be passed as CLI ${flagOnly.length === 1 ? 'flag' : 'flags'} — ` +
+        `${flagOnly.length === 1 ? 'it has' : 'they have'} no \`.specshield.yml\` equivalent ` +
+        '(version values change per run).');
+    }
+
+    if (configurable.length > 0) {
+      msg.push(cfg._file
+        ? `  ${list(configurable)} can be passed as CLI flags or set under \`bdct\` in ${cfg._file}.`
+        : `  ${list(configurable)} can be passed as CLI flags, or run \`specshield init\` to write a \`.specshield.yml\`.`);
+    }
+
+    if (command === 'verify' && flagOnly.length > 0) {
+      msg.push('  e.g. specshield bdct verify --consumer <NAME> --provider <NAME> '
+             + '--consumer-version <VER> --provider-version <VER>');
     }
     const err = new Error(msg.join('\n'));
     err.code = 'MISSING_REQUIRED_OPTIONS';
@@ -205,4 +247,6 @@ module.exports = {
   clearCache,
   applyBdctDefaults,
   REQUIRED_FIELDS,
+  CONFIG_BACKED_FIELDS,
+  bdctDefaultFor,
 };