specshield 3.2.2 → 3.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {
@@ -54,6 +54,9 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "axios": "^1.6.7",
     "chalk": "^4.1.2",
     "commander": "^12.0.0",

package/src/cli.js

@@ -9,6 +9,7 @@ const logoutCommand = require('./commands/logout');
 const bdctCommand = require('./commands/bdct');
 const historyCommand = require('./commands/history');
 const shareCommand = require('./commands/share');
+const whoamiCommand = require('./commands/whoami');
 
 const program = new Command();
 
@@ -28,6 +29,7 @@ program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);
 program.addCommand(historyCommand);
 program.addCommand(shareCommand);
+program.addCommand(whoamiCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/bdct.js

@@ -70,6 +70,8 @@ function hr() {
   return chalk.gray('  ─────────────────────────────────────────────────────');
 }
 
+const { stripVersionPrefix } = require('../util/versionStrip');
+
 /**
  * Flatten a verification result's mismatches.
  * Current backend returns `resultJson` (JSON string of [{endpoint,status,mismatches:[...]}]).
@@ -275,6 +277,11 @@ const verifyCommand = new Command('verify')
     const token = await resolveApiToken(opts);
     requireToken(token);
 
+    // Tolerate a leading `v` on either version (see can-i-deploy for the
+    // full rationale — readers paste back display values like `v1.0.0`).
+    opts.consumerVersion = stripVersionPrefix(opts.consumerVersion);
+    opts.providerVersion = stripVersionPrefix(opts.providerVersion);
+
     const spinner = opts.json ? null : ora(`Verifying ${opts.consumer} → ${opts.provider}...`).start();
 
     try {
@@ -361,6 +368,13 @@ const canIDeployCommand = new Command('can-i-deploy')
     const token = await resolveApiToken(opts);
     requireToken(token);
 
+    // Both the UI and the CLI render versions as `v<version>` for readability.
+    // When a user reads that and pastes it back into `--version`, the query
+    // silently matches nothing (the stored value never has a leading `v`).
+    // Strip a `v` that's followed by a digit, then use the cleaned version
+    // for the network call AND the human display so we never print `vv…`.
+    opts.version = stripVersionPrefix(opts.version);
+
     const spinner = opts.json ? null : ora(`Checking deployment safety for ${opts.service}@${opts.version}...`).start();
 
     try {
@@ -380,11 +394,15 @@ const canIDeployCommand = new Command('can-i-deploy')
         process.exit(deployable ? 0 : 1);
       }
 
+      // Idempotent `v` prefix on display — don't double it when the stored
+      // version legitimately starts with `v` (e.g. `vendor-tag-99`). Mirrors
+      // the UI pill at `BdctCanIDeploy.jsx:392`.
+      const vDisplay = /^v/i.test(opts.version) ? opts.version : `v${opts.version}`;
       process.stdout.write('\n');
       if (deployable) {
-        process.stdout.write(chalk.green.bold('  ✔  PASS') + chalk.white(`: ${opts.service} v${opts.version} is deployable${envLabel}\n`));
+        process.stdout.write(chalk.green.bold('  ✔  PASS') + chalk.white(`: ${opts.service} ${vDisplay} is deployable${envLabel}\n`));
       } else {
-        process.stdout.write(chalk.red.bold('  ✖  FAIL') + chalk.white(`: ${opts.service} v${opts.version} is NOT deployable${envLabel}\n`));
+        process.stdout.write(chalk.red.bold('  ✖  FAIL') + chalk.white(`: ${opts.service} ${vDisplay} is NOT deployable${envLabel}\n`));
       }
       process.stdout.write(hr() + '\n');
 
@@ -689,6 +707,164 @@ const listConsumersCommand = new Command('list-consumers')
     }
   });
 
+// ─── capture (Fix 2 — turn recorded traffic into a consumer contract) ────────
+// Reads a HAR file (any browser/Cypress/Playwright/k6 can export one) and
+// emits an OpenAPI 3.0 consumer-contract subset describing only the
+// endpoints/fields the consumer actually called/read. Pure local CLI work —
+// no API token required.
+
+const captureFromHarCommand = new Command('from-har')
+  .description('Generate a consumer OpenAPI contract from a recorded HAR file')
+  .requiredOption('--in <path>',          'Input HAR file (HTTP Archive 1.2)')
+  .option('--out <path>',                 'Output file (default: write to stdout)')
+  .option('--base-url <url>',             'Keep only entries matching this URL prefix (e.g. https://api.acme.com or https://api.acme.com/v1)')
+  .option('--method <verbs>',             'Comma-separated methods to include (e.g. GET,POST). Default: all')
+  .option('--title <title>',              'OpenAPI info.title', 'Captured consumer contract')
+  .option('--version <ver>',              'OpenAPI info.version', '0.1.0')
+  .option('--format <fmt>',               'Output format: yaml | json', 'yaml')
+  .option('--include-non-json',           'Keep entries with non-JSON bodies (default: drop them)')
+  .action(async (opts) => {
+    const { captureFromHarFile } = require('../core/har');
+    const inputPath = path.resolve(opts.in);
+    if (!fsExtra.existsSync(inputPath)) {
+      logger.error(`HAR file not found: ${inputPath}`);
+      process.exit(2);
+    }
+    const methods = opts.method
+      ? opts.method.split(',').map(s => s.trim()).filter(Boolean)
+      : undefined;
+
+    let result;
+    try {
+      result = captureFromHarFile(inputPath, {
+        baseUrl: opts.baseUrl,
+        methods,
+        onlyJson: !opts.includeNonJson,
+        title: opts.title,
+        version: opts.version,
+        format: opts.format,
+      });
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+
+    if (opts.out) {
+      const outPath = path.resolve(opts.out);
+      fsExtra.outputFileSync(outPath, result.text);
+      process.stderr.write(chalk.green('✔ ') +
+        `Wrote ${chalk.cyan(opts.out)}  ` +
+        chalk.gray(`(${result.summary.endpoints} endpoints, ${result.summary.operations} ops from ${result.summary.recordsKept}/${result.summary.harEntries} entries)`) + '\n');
+    } else {
+      process.stdout.write(result.text);
+      process.stderr.write(chalk.gray(
+        `# ${result.summary.endpoints} endpoints, ${result.summary.operations} ops from ${result.summary.recordsKept}/${result.summary.harEntries} HAR entries\n`
+      ));
+    }
+  });
+
+const captureCommand = new Command('capture')
+  .description('Capture a consumer OpenAPI contract from observed traffic (currently: HAR ingest)');
+captureCommand.addCommand(captureFromHarCommand);
+
+// ─── verify-provider (Fix 3 — spec-vs-production conformance) ─────────────────
+// Fires probes derived from the OpenAPI spec at the running provider and
+// validates that every response body actually matches its documented schema.
+// Pure local CLI work (calls the customer's service directly); no API token.
+// Safe-by-default: only GET/HEAD/OPTIONS unless --include-mutating.
+
+const verifyProviderCommand = new Command('verify-provider')
+  .description('Check that a running provider service matches its OpenAPI spec')
+  .requiredOption('--spec <path>',         'Path to the provider OpenAPI spec (YAML or JSON)')
+  .requiredOption('--base-url <url>',      'Base URL of the running provider, e.g. https://staging.payments.acme.com')
+  .option('--include-mutating',            'Also probe POST/PUT/PATCH/DELETE (off by default for safety)')
+  .option('--path-params <kvList>',        'Resolve path params: name=val,other=val (overrides spec examples)', collectPathParams, {})
+  .option('--header <header>',             'Extra request header to send, e.g. "Authorization: Bearer X" (repeatable)', collectHeaders, {})
+  .option('--timeout-ms <ms>',             'Per-request timeout in ms', v => parseInt(v, 10), 8000)
+  .option('--json',                        'Output raw JSON instead of the human report')
+  .action(async (opts) => {
+    const { verifyProvider } = require('../core/conformance');
+    const specPath = path.resolve(opts.spec);
+    if (!fsExtra.existsSync(specPath)) {
+      logger.error(`Spec file not found: ${specPath}`);
+      process.exit(2);
+    }
+    const spinner = opts.json ? null : ora('Probing provider…').start();
+    let report;
+    try {
+      report = await verifyProvider({
+        spec: specPath,
+        baseUrl: opts.baseUrl,
+        includeMutating: !!opts.includeMutating,
+        pathParams: opts.pathParams,
+        headers: opts.header,
+        timeoutMs: opts.timeoutMs,
+      });
+    } catch (err) {
+      if (spinner) spinner.fail('Conformance run failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+    if (spinner) spinner.stop();
+
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      process.exit(report.summary.fail + report.summary.error > 0 ? 1 : 0);
+    }
+
+    // Human report.
+    process.stdout.write('\n' + chalk.bold('  Provider conformance — spec vs ') + chalk.cyan(opts.baseUrl) + '\n');
+    process.stdout.write('  ' + '─'.repeat(60) + '\n');
+    for (const r of report.results) {
+      const label = `${r.method.padEnd(6)} ${r.routePath}`;
+      const tag =
+        r.status === 'PASS'    ? chalk.green('  PASS  ') :
+        r.status === 'FAIL'    ? chalk.red('  FAIL  ')   :
+        r.status === 'ERROR'   ? chalk.red(' ERROR  ')   :
+                                  chalk.yellow(' SKIP   ');
+      process.stdout.write(`  ${tag} ${label}` +
+        (r.httpStatus ? chalk.gray(`  (${r.httpStatus})`) : '') + '\n');
+      if (r.status === 'FAIL' && r.mismatches && r.mismatches.length > 0) {
+        for (const m of r.mismatches.slice(0, 5)) {
+          process.stdout.write(chalk.gray(`           ${m.path || '(root)'}: ${m.message}\n`));
+        }
+        if (r.mismatches.length > 5) {
+          process.stdout.write(chalk.gray(`           …and ${r.mismatches.length - 5} more\n`));
+        }
+      } else if (r.status === 'FAIL' && r.reason) {
+        process.stdout.write(chalk.gray(`           ${r.reason}\n`));
+      } else if (r.status === 'ERROR') {
+        process.stdout.write(chalk.gray(`           ${r.error}\n`));
+      } else if (r.status === 'SKIPPED') {
+        process.stdout.write(chalk.gray(`           ${r.reason}: ${r.skipReason}\n`));
+      }
+    }
+    const s = report.summary;
+    process.stdout.write('  ' + '─'.repeat(60) + '\n');
+    process.stdout.write(`  ${s.pass} pass · ${s.fail} fail · ${s.error} error · ${s.skipped} skip   (${s.total} probes)\n\n`);
+    process.exit(s.fail + s.error > 0 ? 1 : 0);
+  });
+
+// Repeatable --header parser: collects into a map.
+function collectHeaders(val, acc) {
+  const idx = val.indexOf(':');
+  if (idx < 0) return acc;
+  const k = val.slice(0, idx).trim();
+  const v = val.slice(idx + 1).trim();
+  if (k) acc[k] = v;
+  return acc;
+}
+
+// --path-params name=val,name=val parser: merges into the accumulator so the
+// flag can be passed multiple times.
+function collectPathParams(val, acc) {
+  for (const pair of String(val).split(',')) {
+    const [k, ...rest] = pair.split('=');
+    if (k && k.trim()) acc[k.trim()] = rest.join('=').trim();
+  }
+  return acc;
+}
+
 // ─── Parent bdct command ──────────────────────────────────────────────────────
 
 const bdct = new Command('bdct')
@@ -702,5 +878,7 @@ bdct.addCommand(listCommand);
 bdct.addCommand(matrixCommand);
 bdct.addCommand(listProvidersCommand);
 bdct.addCommand(listConsumersCommand);
+bdct.addCommand(captureCommand);
+bdct.addCommand(verifyProviderCommand);
 
 module.exports = bdct;

package/src/commands/whoami.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * `specshield whoami` — print the active customer's identity and the list of
+ * organizations they can use as `--org` values. Reuses /auth/validate-api-key
+ * (for the customer summary) and /me/orgs (for the org list) — the same two
+ * endpoints the init wizard hits.
+ *
+ * Why it exists: the dashboard now surfaces orgKey, but terminal-native users
+ * and CI engineers shouldn't have to open a browser to discover what their
+ * org_key is. This command makes it a one-line lookup.
+ *
+ * Resolves the API token the same way every other command does:
+ *   --api-token flag  >  $SPECSHIELD_API_KEY  >  stored ~/.specshield/config.json
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const axios = require('axios');
+const logger = require('../utils/logger');
+const { getStoredApiKey } = require('../config/localConfig');
+
+const DEFAULT_SERVER = 'https://specshield.io';
+
+const whoami = new Command('whoami');
+
+whoami
+  .description('Show the signed-in customer and the orgKeys you can use as --org')
+  .option('--api-token <key>', 'Override stored / env API token for this call')
+  .option('--server <url>',    'Override the SpecShield server URL', DEFAULT_SERVER)
+  .option('--json',            'Output machine-readable JSON instead of a table')
+  .action(async (opts) => {
+    const token = opts.apiToken
+      || process.env.SPECSHIELD_API_KEY
+      || (await getStoredApiKey());
+    if (!token) {
+      logger.error('Not logged in. Run: specshield login --api-key <KEY>');
+      process.exit(2);
+    }
+
+    const server = (opts.server || DEFAULT_SERVER).replace(/\/$/, '');
+    const headers = { 'X-Api-Key': token, 'X-SpecShield-Client': 'cli' };
+
+    let me, orgs;
+    try {
+      const meRes = await axios.post(`${server}/auth/validate-api-key`, {}, { headers, timeout: 8000 });
+      if (!meRes.data || !meRes.data.valid) {
+        logger.error('API key did not validate against ' + server);
+        process.exit(2);
+      }
+      me = meRes.data;
+    } catch (err) {
+      logger.error(err.response
+        ? `Failed to validate token: ${err.response.status} ${JSON.stringify(err.response.data)}`
+        : `Could not reach ${server}: ${err.message}`);
+      process.exit(2);
+    }
+
+    try {
+      const orgsRes = await axios.get(`${server}/me/orgs`, { headers, timeout: 8000 });
+      orgs = Array.isArray(orgsRes.data) ? orgsRes.data : (orgsRes.data?.orgs || []);
+    } catch (err) {
+      // Org fetch is best-effort; the customer info already printed below
+      // is the more important part.
+      orgs = [];
+    }
+
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        customer: { name: me.name, email: me.email, plan: me.plan, customerId: me.customerId },
+        server,
+        orgs: orgs.map(o => ({ orgKey: o.orgKey, name: o.name, role: o.myRole || o.role || null })),
+      }, null, 2) + '\n');
+      return;
+    }
+
+    // Human-readable output. Two sections — identity, then orgs table.
+    process.stdout.write('\n');
+    process.stdout.write(`  ${chalk.bold('Logged in as:')} ${me.name || '(no name)'} `);
+    if (me.email) process.stdout.write(chalk.gray(`(${me.email})`));
+    process.stdout.write(`   ${chalk.gray('· plan:')} ${chalk.cyan(me.plan || 'FREE')}\n`);
+    process.stdout.write(`  ${chalk.gray('Server:')}       ${server}\n`);
+    process.stdout.write('\n');
+
+    if (orgs.length === 0) {
+      process.stdout.write(chalk.yellow('  You are not a member of any organization yet.\n'));
+      process.stdout.write(chalk.gray(`  Create one at ${server}/account/team to get an org_key.\n\n`));
+      return;
+    }
+
+    process.stdout.write(`  ${chalk.bold('Organizations you can use as --org:')}\n`);
+    process.stdout.write(chalk.gray('  ─────────────────────────────────────────────────────\n'));
+    const widestKey = Math.max(...orgs.map(o => (o.orgKey || '').length), 8);
+    for (const o of orgs) {
+      const key  = (o.orgKey || '').padEnd(widestKey);
+      const role = o.myRole || o.role || '';
+      process.stdout.write(
+        `    ${chalk.cyan(key)}   ${o.name || ''}` +
+        (role ? `   ${chalk.gray('(' + role + ')')}` : '') + '\n');
+    }
+    process.stdout.write('\n');
+    process.stdout.write(chalk.gray(`  Tip: paste an org_key into --org on CLI commands or bdct.org in .specshield.yml\n\n`));
+  });
+
+module.exports = whoami;

package/src/core/conformance/index.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * One-call orchestrator for `specshield bdct verify-provider` — the
+ * "spec-vs-production conformance" check (Fix 3 of the BDCT fidelity
+ * roadmap).
+ *
+ * Loads + dereferences an OpenAPI spec, derives a probe list (safe methods
+ * only by default), fires the probes at the running provider, validates
+ * each response body against the spec's schema for that status, and
+ * returns a structured result + summary.
+ *
+ * Defaults are deliberately conservative — this tool is pointed at REAL
+ * customer services (typically staging, sometimes prod), so:
+ *
+ *   - Only GET / HEAD / OPTIONS unless `includeMutating: true`.
+ *   - Probes whose path params can't be resolved are SKIPPED, not guessed.
+ *   - Network errors are reported as ERROR results — never thrown — so a
+ *     single flaky endpoint doesn't kill the whole run.
+ */
+
+const axios = require('axios');
+const SwaggerParser = require('@apidevtools/swagger-parser');
+const { buildProbes } = require('./probeBuilder');
+const { runProbes }   = require('./runner');
+
+async function verifyProvider(opts) {
+  const spec = await SwaggerParser.dereference(opts.spec);
+  const probes = buildProbes(spec, { includeMutating: !!opts.includeMutating });
+  const http = opts.http || defaultHttpAdapter;
+  return runProbes(spec, probes, {
+    baseUrl: opts.baseUrl,
+    pathParams: opts.pathParams,
+    headers: opts.headers,
+    timeoutMs: opts.timeoutMs,
+    http,
+  });
+}
+
+/** Default HTTP adapter (axios). Returns { status, body } and rejects only
+ *  on connection-level failures — HTTP error statuses come back as data. */
+async function defaultHttpAdapter(method, url, { headers, timeoutMs }) {
+  const res = await axios.request({
+    method, url, headers, timeout: timeoutMs,
+    validateStatus: () => true,    // never throw on 4xx/5xx; the validator decides
+    responseType: 'json',
+    transitional: { silentJSONParsing: true, forcedJSONParsing: true },
+  });
+  return { status: res.status, body: res.data };
+}
+
+module.exports = { verifyProvider, defaultHttpAdapter };

package/src/core/conformance/pathResolver.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * Resolve OpenAPI path-template parameters into concrete URL paths.
+ * Sources, in priority order:
+ *   1. caller-supplied overrides (e.g. CLI `--path-params paymentId=pay-123`)
+ *   2. the operation's `parameters[].example` for each path-param
+ *   3. the path-item-level `parameters[].example`
+ *   4. the parameter schema's `example`
+ *
+ * If a required path param can't be resolved, the probe is skipped (with a
+ * `missing` list so the runner can report it).
+ */
+
+/**
+ * @param template     '/users/{userId}/orders/{orderId}'
+ * @param resolvedMap  { userId: 'u-1', orderId: 'o-7' }   (already-resolved)
+ * @returns            { resolved: string, missing: string[] }
+ */
+function substitute(template, resolvedMap) {
+  const missing = [];
+  const resolved = template.replace(/\{([^}]+)\}/g, (_full, name) => {
+    const v = resolvedMap && Object.prototype.hasOwnProperty.call(resolvedMap, name)
+      ? resolvedMap[name]
+      : undefined;
+    if (v === undefined || v === null || v === '') { missing.push(name); return `{${name}}`; }
+    return encodeURIComponent(String(v));
+  });
+  return { resolved, missing };
+}
+
+/**
+ * Walk the spec to gather examples for path params. Returns a map per-route:
+ *   { '/users/{userId}': { GET: { userId: 'u-1' }, … }, … }
+ *
+ * Operation-level params override path-item-level params (standard OAS rule).
+ */
+function collectSpecExamples(spec) {
+  const out = {};
+  const paths = (spec && spec.paths) || {};
+  const METHODS = ['get','put','post','delete','options','head','patch','trace'];
+
+  for (const [routePath, item] of Object.entries(paths)) {
+    if (!item || typeof item !== 'object') continue;
+    out[routePath] = {};
+
+    const pathLevelParams = Array.isArray(item.parameters) ? item.parameters : [];
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      const opParams = Array.isArray(op.parameters) ? op.parameters : [];
+
+      const merged = {};
+      for (const p of pathLevelParams) addExample(merged, p);
+      for (const p of opParams)        addExample(merged, p);   // op overrides
+      out[routePath][method.toUpperCase()] = merged;
+    }
+  }
+  return out;
+}
+
+function addExample(target, param) {
+  if (!param || param.in !== 'path' || !param.name) return;
+  const ex = param.example
+         ?? (param.examples && firstExampleValue(param.examples))
+         ?? (param.schema && param.schema.example);
+  if (ex !== undefined) target[param.name] = ex;
+}
+
+function firstExampleValue(examples) {
+  for (const v of Object.values(examples || {})) {
+    if (v && v.value !== undefined) return v.value;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a single probe's path. CLI overrides win over spec examples.
+ *
+ * @param routePath        '/users/{userId}'
+ * @param method           'GET'
+ * @param specExamples     output of collectSpecExamples(spec)
+ * @param cliOverrides     { userId: 'u-7', ... } (global)
+ */
+function resolveProbePath(routePath, method, specExamples, cliOverrides) {
+  const fromSpec = (specExamples[routePath] && specExamples[routePath][method.toUpperCase()]) || {};
+  const merged = { ...fromSpec, ...(cliOverrides || {}) };
+  return substitute(routePath, merged);
+}
+
+/**
+ * Parse a CLI string `paymentId=pay-123,userId=u-7` into a map.
+ * Multiple `--path-params` flags can be joined by the caller before parsing.
+ */
+function parsePathParamsArg(arg) {
+  if (!arg) return {};
+  const map = {};
+  for (const pair of String(arg).split(',')) {
+    const [k, ...rest] = pair.split('=');
+    if (!k) continue;
+    map[k.trim()] = rest.join('=').trim();
+  }
+  return map;
+}
+
+module.exports = {
+  substitute, collectSpecExamples, resolveProbePath, parsePathParamsArg,
+};

package/src/core/conformance/probeBuilder.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Build a flat list of conformance probes from a dereferenced OAS document.
+ *
+ *   Probe = {
+ *     routePath:    '/users/{userId}',
+ *     method:       'GET',
+ *     operationId:  string | undefined,
+ *     expectedResponses: { '200': schema, '404': schema, default?: schema },
+ *     responseHeadersForStatus: { '200': { 'X-RateLimit-Remaining': { schema } } },
+ *   }
+ *
+ * Safety: by default we only probe **safe** methods (GET, HEAD, OPTIONS).
+ * Mutating verbs are opt-in via `includeMutating: true` so we never
+ * accidentally side-effect a customer's staging data.
+ */
+
+const SAFE_METHODS    = new Set(['get', 'head', 'options']);
+const ALL_METHODS     = ['get','put','post','delete','options','head','patch','trace'];
+const JSON_MIME       = /\bjson\b/i;
+
+/**
+ * @param spec               dereferenced OAS document
+ * @param opts.includeMutating   default false
+ * @returns Probe[]
+ */
+function buildProbes(spec, opts = {}) {
+  const includeMutating = opts.includeMutating === true;
+  const allowed = includeMutating ? new Set(ALL_METHODS) : SAFE_METHODS;
+  const out = [];
+
+  const paths = (spec && spec.paths) || {};
+  for (const [routePath, item] of Object.entries(paths)) {
+    if (!item || typeof item !== 'object') continue;
+    for (const method of ALL_METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      if (!allowed.has(method)) continue;
+
+      out.push({
+        routePath,
+        method: method.toUpperCase(),
+        operationId: op.operationId,
+        expectedResponses: extractResponses(op.responses || {}),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * { '200': { content: { 'application/json': { schema } } }, '4XX': … }
+ * →
+ * { '200': schema | null, '4XX': schema | null, default?: schema | null }
+ *
+ * Pulls the JSON-content schema only (other content types deferred).
+ */
+function extractResponses(responses) {
+  const out = {};
+  for (const [code, body] of Object.entries(responses)) {
+    if (!body) continue;
+    const content = body.content || {};
+    let schema = null;
+    for (const [mime, c] of Object.entries(content)) {
+      if (JSON_MIME.test(mime) && c && c.schema) { schema = c.schema; break; }
+    }
+    out[code] = schema;       // null = "documented status, no JSON schema"
+  }
+  return out;
+}
+
+/**
+ * Match an actual response status (e.g. 200) against the spec's response keys
+ * (which can be exact `"200"`, wildcard `"2XX"`, or `"default"`).
+ * Returns the matching schema (possibly null) or undefined if nothing matches.
+ */
+function pickResponseSchema(probe, actualStatus) {
+  const r = probe.expectedResponses;
+  const code = String(actualStatus);
+  if (Object.prototype.hasOwnProperty.call(r, code)) return r[code];
+  const wildcard = code[0] + 'XX';
+  if (Object.prototype.hasOwnProperty.call(r, wildcard)) return r[wildcard];
+  if (Object.prototype.hasOwnProperty.call(r, wildcard.toLowerCase())) return r[wildcard.toLowerCase()];
+  if (Object.prototype.hasOwnProperty.call(r, 'default')) return r['default'];
+  return undefined;
+}
+
+module.exports = {
+  buildProbes, extractResponses, pickResponseSchema,
+  SAFE_METHODS, ALL_METHODS,
+};