@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/setup-api.ts

@@ -1,9 +1,172 @@
-import { resolve, join } from "path";
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "fs";
+import { resolve, join, relative } from "path";
+import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from "fs";
 import { getDb } from "../db/schema.ts";
 import { createCollection, deleteCollection, findCollectionByNameOrId, normalizePath } from "../db/queries.ts";
-import { readOpenApiSpec, extractEndpoints } from "./generator/index.ts";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  buildCatalog,
+  serializeCatalog,
+  buildApiResourceMap,
+  serializeApiResourceMap,
+  buildApiFixtureManifest,
+  serializeApiFixtureManifest,
+} from "./generator/index.ts";
+import { decycleSchema } from "./generator/schema-utils.ts";
+import { mergeOpenApiDocs } from "./spec/merge-specs.ts";
+import { schemeVarName } from "./generator/suite-generator.ts";
+import type { SecuritySchemeInfo } from "./generator/types.ts";
+import { hashSpec } from "./meta/meta-store.ts";
 import { findWorkspaceRoot } from "./workspace/root.ts";
+import { recordGeneratedFiles, type RecordInput } from "./workspace/manifest.ts";
+import { CANONICAL_IDENTITY_KEYS } from "./identity/identity-file.ts";
+
+/** Filename of the dereferenced spec snapshot inside `apis/<name>/`. */
+export const SPEC_SNAPSHOT_FILENAME = "spec.json";
+
+interface WriteArtifactsParams {
+  /** Dereferenced OpenAPI document. */
+  doc: unknown;
+  /** Absolute path to apis/<name>/. */
+  baseDir: string;
+  /** Collection name (goes into the catalog header). */
+  apiName: string;
+  /** Resolved server URL or "". */
+  baseUrl: string;
+  /** Absolute workspace root, used to compute the relative specSource. */
+  workspaceRoot: string;
+  /** Caller label for manifest entries (defaults to "zond add api"). */
+  by?: string;
+}
+
+/**
+ * Snapshot the dereferenced spec into `apis/<name>/spec.json` and emit the
+ * three derived artifacts (`.api-catalog.yaml`, `.api-resources.yaml`,
+ * `.api-fixtures.yaml`). Pure side-effect; safe to call from `setupApi` at
+ * register time and from `refreshApi` for re-snapshot.
+ */
+export function writeArtifactsFromDoc(params: WriteArtifactsParams): void {
+  const { doc, baseDir, apiName, baseUrl, workspaceRoot, by = "zond add api" } = params;
+  const localSpecAbsPath = join(baseDir, SPEC_SNAPSHOT_FILENAME);
+  // Pass through decycleSchema first — large specs (Stripe, GitHub) contain
+  // mutually-recursive `$ref` chains that resolve to true object cycles after
+  // dereference, and raw JSON.stringify crashes on those with "cannot
+  // serialize cyclic structures" (ARV-145). decycleSchema collapses the
+  // second visit to `{ "x-circular": true }` (vendor-extension sentinel —
+  // NOT `$ref`, otherwise the parser tries to resolve "[Circular]" as a
+  // file path when re-reading spec.json, ARV-146) so the on-disk snapshot
+  // is self-contained, parser-safe JSON.
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(decycleSchema(doc), null, 2);
+  } catch (err) {
+    const m = (err as Error).message;
+    throw new Error(
+      `spec_serialize_failed: could not serialize dereferenced spec for '${apiName}' — ${m}. ` +
+      `This usually means the spec contains a structure decycleSchema could not collapse; please open an issue with the spec URL.`,
+    );
+  }
+  writeFileSync(localSpecAbsPath, serialized + "\n", "utf-8");
+
+  const endpoints = extractEndpoints(doc as any);
+  const securitySchemes = extractSecuritySchemes(doc as any);
+  // Hash the on-disk file bytes — this is what `zond doctor` re-hashes when
+  // checking artifact freshness (TASK-215). Both sides now read the decycled
+  // form: setup-api writes it here, doctor re-reads the same file.
+  const specHash = hashSpec(readFileSync(localSpecAbsPath, "utf-8"));
+  const localSpecRelPath = relative(workspaceRoot, localSpecAbsPath).replace(/\\/g, "/");
+
+  const catalog = buildCatalog({
+    endpoints,
+    securitySchemes,
+    specSource: localSpecRelPath,
+    specHash,
+    apiName,
+    apiVersion: (doc as any).info?.version,
+    baseUrl,
+  });
+  const catalogPath = join(baseDir, ".api-catalog.yaml");
+  writeFileSync(catalogPath, serializeCatalog(catalog), "utf-8");
+
+  const resources = buildApiResourceMap({ endpoints, specHash });
+  const resourcesPath = join(baseDir, ".api-resources.yaml");
+  writeFileSync(resourcesPath, serializeApiResourceMap(resources), "utf-8");
+
+  const fixtures = buildApiFixtureManifest({
+    endpoints,
+    securitySchemes,
+    baseUrl: baseUrl || undefined,
+    specHash,
+    resourceMap: resources,
+  });
+  const fixturesPath = join(baseDir, ".api-fixtures.yaml");
+  writeFileSync(fixturesPath, serializeApiFixtureManifest(fixtures), "utf-8");
+
+  // Record artifacts in .zond/manifest.json (TASK-156).
+  try {
+    const entries: RecordInput[] = [
+      { path: localSpecAbsPath, by, api: apiName, category: "spec" },
+      { path: catalogPath, by, api: apiName, category: "catalog" },
+      { path: resourcesPath, by, api: apiName, category: "resources" },
+      { path: fixturesPath, by, api: apiName, category: "fixtures" },
+    ];
+    recordGeneratedFiles(workspaceRoot, entries);
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Resolve a `collections.openapi_spec` value to a concrete file path the
+ * caller can read. Throws on a legacy / broken workspace so the user gets
+ * a single clear instruction instead of a downstream ENOENT.
+ *
+ * Resolution order:
+ *   1. URL (http/https) — return as-is.
+ *   2. Workspace-relative path (e.g. `apis/<name>/spec.json`) that exists.
+ *   3. Absolute filesystem path that exists. Treated as legacy: the spec
+ *      is outside the workspace and not snapshotted into `apis/<name>/`.
+ *      We let it through, but `assertLocalSpec` (used by run/report/doctor)
+ *      will reject it.
+ *   4. Otherwise — throw a "legacy / stale workspace" error pointing at
+ *      `zond refresh-api`.
+ */
+export function resolveCollectionSpec(specRef: string): string {
+  if (/^https?:\/\//i.test(specRef)) return specRef;
+  const root = findWorkspaceRoot().root;
+  const local = resolve(root, specRef);
+  if (existsSync(local)) return local;
+  if (specRef.startsWith("/") && existsSync(specRef)) return specRef;
+  throw new Error(
+    `Spec for this API is missing at ${local}` +
+    (specRef.startsWith("/") ? ` (DB recorded an external path: ${specRef})` : "") +
+    `. The workspace looks legacy or stale — run \`zond refresh-api <name> [--spec <path|url>]\` to re-snapshot.`,
+  );
+}
+
+/**
+ * Strict variant for code paths that must read the workspace-local
+ * snapshot (run/report/doctor). Returns the local absolute path or
+ * throws — never returns an external URL or path.
+ */
+export function assertLocalSpec(specRef: string, apiName: string): string {
+  if (/^https?:\/\//i.test(specRef)) {
+    throw new Error(
+      `API '${apiName}' has a remote spec recorded (${specRef}) but no local snapshot. ` +
+      `Run \`zond refresh-api ${apiName}\` to materialise apis/${apiName}/${SPEC_SNAPSHOT_FILENAME}.`,
+    );
+  }
+  const root = findWorkspaceRoot().root;
+  const local = resolve(root, specRef);
+  if (!existsSync(local)) {
+    throw new Error(
+      `Local spec missing for API '${apiName}' (expected ${local}). ` +
+      `Run \`zond refresh-api ${apiName}\` to regenerate it.`,
+    );
+  }
+  return local;
+}
 
 function toYaml(vars: Record<string, string>): string {
   const lines: string[] = [];
@@ -17,11 +180,17 @@ function toYaml(vars: Record<string, string>): string {
 export interface SetupApiOptions {
   name?: string;
   spec?: string;
+  /** ARV-375: additional specs to union into one merged document. When
+   *  set (length > 1), takes precedence over `spec`; the specs are
+   *  dereferenced individually then merged deterministically (last-wins on
+   *  path/component collision, collisions surfaced as warnings). */
+  specs?: string[];
   dir?: string;
   envVars?: Record<string, string>;
   dbPath?: string;
   force?: boolean;
   insecure?: boolean;
+  caPath?: string;
 }
 
 export interface SetupApiResult {
@@ -32,11 +201,40 @@ export interface SetupApiResult {
   baseUrl: string;
   specEndpoints: number;
   pathParams?: Record<string, string>;
+  /** Auth-related env-var names auto-seeded as `@secret:<name>` (TASK-209). */
+  authVars?: string[];
   warnings?: string[];
 }
 
+/**
+ * Walk the security schemes and derive the env-var names that
+ * `@readme/openapi-parser`-derived suites/probes will reference for auth
+ * tokens. Mirrors `getAuthHeaders` in src/core/probe/shared.ts:
+ *   - HTTP bearer/basic/empty-scheme → schemeVarName(...) (default "auth_token")
+ *   - apiKey in header named "Authorization" → schemeVarName(...)
+ *   - apiKey in header (other name) → "api_key"
+ */
+function deriveAuthVarNames(schemes: SecuritySchemeInfo[]): string[] {
+  const vars = new Set<string>();
+  for (const s of schemes) {
+    if (s.type === "http" && (s.scheme === "bearer" || s.scheme === "basic" || !s.scheme)) {
+      vars.add(schemeVarName(s, schemes));
+    } else if (s.type === "apiKey" && s.in === "header" && s.apiKeyName) {
+      if (s.apiKeyName === "Authorization") vars.add(schemeVarName(s, schemes));
+      else vars.add("api_key");
+    }
+  }
+  return [...vars];
+}
+
 export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult> {
-  const { spec, dbPath } = options;
+  const { dbPath } = options;
+  // ARV-375: `--spec` may be repeated. `specs` (from the variadic CLI
+  // collector) wins; fall back to the single `spec` for back-compat.
+  const specList = options.specs && options.specs.length > 0
+    ? options.specs
+    : (options.spec ? [options.spec] : []);
+  const spec = specList[0];
 
   getDb(dbPath);
 
@@ -47,11 +245,72 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   const pathParams = new Map<string, string>();
   const warnings: string[] = [];
   let specTitle: string | undefined;
-  if (spec) {
-    const doc = await readOpenApiSpec(spec, { insecure: options.insecure });
-    openapiSpec = spec;
+  // The dereferenced doc is captured here so we can copy it into the
+  // workspace after the target dir is computed (below). We snapshot the
+  // *dereferenced* form so all consumers (probe-*, generate, describe) read
+  // a self-contained file — no external $ref resolution at runtime.
+  let dereferencedDoc: unknown = null;
+  let authVarNames: string[] = [];
+  if (specList.length > 0) {
+    // Read + validate each spec independently. dereference() happily
+    // round-trips arbitrary JSON (e.g. a marketing-site landing payload),
+    // so without this guard `zond add api foo --spec https://example.com`
+    // silently registers a 0-endpoint API.
+    const loaded: { source: string; doc: any }[] = [];
+    for (const s of specList) {
+      const d = await readOpenApiSpec(s, { insecure: options.insecure, caPath: options.caPath });
+      const dAny = d as any;
+      if (typeof dAny?.openapi !== "string" && typeof dAny?.swagger !== "string") {
+        throw new Error(
+          `Spec at ${s} is not an OpenAPI/Swagger document — missing top-level 'openapi' (3.x) or 'swagger' (2.x) field. Check the URL points to the JSON spec, not the API root.`,
+        );
+      }
+      loaded.push({ source: s, doc: d });
+    }
+
+    let doc: any;
+    if (loaded.length === 1) {
+      doc = loaded[0]!.doc;
+      openapiSpec = spec!;
+    } else {
+      // ARV-375: deterministic union of N specs into one audit target.
+      const { merged, summary } = mergeOpenApiDocs(loaded);
+      doc = merged;
+      openapiSpec = null; // no single source path — rely on the local snapshot
+      const per = summary.sources.map((s) => `${s.paths} from ${s.source}`).join(", ");
+      warnings.push(`Merged ${summary.sources.length} specs → ${summary.totalPaths} paths (${per}).`);
+      if (summary.pathCollisions.length > 0) {
+        warnings.push(
+          `${summary.pathCollisions.length} path collision(s) — later spec wins: ${summary.pathCollisions.join(", ")}.`,
+        );
+      }
+      if (summary.schemaConflicts.length > 0) {
+        warnings.push(
+          `${summary.schemaConflicts.length} component collision(s) with differing shapes (later wins, verify): ${summary.schemaConflicts.join(", ")}.`,
+        );
+      }
+    }
+    dereferencedDoc = doc;
+    const docAny = doc as any;
     if ((doc as any).servers?.[0]?.url) {
       baseUrl = (doc as any).servers[0].url;
+      // Resolve OpenAPI server variables (e.g. {region}) using their declared defaults.
+      // Without this, the raw placeholder ends up in .env.yaml and causes cryptic TLS
+      // errors because the hostname literally contains "{region}".
+      const serverVars = (doc as any).servers[0].variables as
+        Record<string, { default?: string }> | undefined;
+      if (serverVars && baseUrl.includes("{")) {
+        baseUrl = baseUrl.replace(/\{([^}]+)\}/g, (_: string, name: string) =>
+          serverVars[name]?.default ?? `{${name}}`
+        );
+      }
+      // Warn if any placeholder remains unresolved (spec didn't provide a default).
+      const unresolved = [...baseUrl.matchAll(/\{([^}]+)\}/g)].map(m => m[1]);
+      if (unresolved.length > 0) {
+        warnings.push(
+          `base_url contains unresolved server variable${unresolved.length === 1 ? "" : "s"}: ${unresolved.map(v => `{${v}}`).join(", ")}. Edit .env.yaml and replace with a concrete value.`,
+        );
+      }
     }
     if (baseUrl && !baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
       warnings.push(`Spec server URL "${baseUrl}" is relative — requests will fail without a host. Override with envVars: {"base_url": "https://your-host${baseUrl}"}`);
@@ -59,16 +318,28 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     specTitle = (doc as any).info?.title;
     const endpoints = extractEndpoints(doc);
     endpointCount = endpoints.length;
+    authVarNames = deriveAuthVarNames(extractSecuritySchemes(doc));
+
+    if (endpointCount === 0) {
+      const hasPaths = docAny?.paths && typeof docAny.paths === "object" && Object.keys(docAny.paths).length > 0;
+      warnings.push(
+        hasPaths
+          ? `Spec declares paths but no operations were extracted — every method may be filtered out (deprecated, unsupported method, etc.). Verify with \`zond catalog --api <name>\`.`
+          : `Spec contains 0 endpoints — 'paths' field is empty or missing. generate/probe/checks will produce nothing until the spec is fixed or replaced.`,
+      );
+    }
 
-    // Collect unique path parameters with default values
+    // Collect unique path parameters. The default is empty string so that
+    // generated `skip_if: "{{<id>}} =="` checks auto-skip until the user
+    // fills the value in .env.yaml (TASK-210). Spec-provided examples are
+    // kept verbatim so they are still useful as concrete fixtures.
     for (const ep of endpoints) {
       for (const param of (ep.parameters ?? []).filter(p => p.in === "path")) {
         if (pathParams.has(param.name)) continue;
         const schema = param.schema as any;
         if (param.example !== undefined) pathParams.set(param.name, String(param.example));
         else if (schema?.example !== undefined) pathParams.set(param.name, String(schema.example));
-        else if (schema?.type === "integer" || schema?.type === "number") pathParams.set(param.name, "1");
-        else pathParams.set(param.name, "example");
+        else pathParams.set(param.name, "");
       }
     }
   }
@@ -96,9 +367,63 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     : resolve(findWorkspaceRoot().root, `apis/${dirName}/`);
   const testPath = join(baseDir, "tests");
 
+  // Track whether we created baseDir from scratch so we can clean it up on
+  // failure — without this, a crash mid-setup (e.g. JSON.stringify on a
+  // cyclic spec, ARV-145) leaves apis/<slug>/tests/ behind and confuses the
+  // next `zond add api` invocation.
+  const baseDirPreExisted = existsSync(baseDir);
+
   // Create directories
   mkdirSync(testPath, { recursive: true });
 
+  try {
+    return await finalizeSetup({
+      name,
+      baseDir,
+      testPath,
+      baseUrl,
+      pathParams,
+      authVarNames,
+      envVarsOverride: options.envVars,
+      spec,
+      dereferencedDoc,
+      openapiSpec,
+      endpointCount,
+      warnings,
+    });
+  } catch (err) {
+    // Roll back partial filesystem state (apis/<slug>/tests/, spec.json, etc.)
+    // when we created the dir from scratch. Without this, the next
+    // `zond add api <same-name>` would still find a stale dir and demand
+    // --force, even though no collection was actually registered. ARV-145.
+    if (!baseDirPreExisted) {
+      try { rmSync(baseDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+}
+
+interface FinalizeSetupParams {
+  name: string;
+  baseDir: string;
+  testPath: string;
+  baseUrl: string;
+  pathParams: Map<string, string>;
+  authVarNames: string[];
+  envVarsOverride?: Record<string, string>;
+  spec?: string;
+  dereferencedDoc: unknown;
+  openapiSpec: string | null;
+  endpointCount: number;
+  warnings: string[];
+}
+
+async function finalizeSetup(p: FinalizeSetupParams): Promise<SetupApiResult> {
+  const {
+    name, baseDir, testPath, baseUrl, pathParams, authVarNames,
+    envVarsOverride, spec, dereferencedDoc, openapiSpec, endpointCount, warnings,
+  } = p;
+
   // Build environment variables
   const envVars: Record<string, string> = {};
   if (baseUrl) envVars.base_url = baseUrl;
@@ -106,8 +431,33 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   for (const [k, v] of pathParams) {
     if (!(k in envVars)) envVars[k] = v;
   }
-  if (options.envVars) {
-    Object.assign(envVars, options.envVars);
+  // Auto-wire auth env-vars to .secrets.yaml so generated suites and probes
+  // resolve `{{auth_token}}` (etc.) without manual editing of .env.yaml
+  // (TASK-209). The matching `<var>: ""` placeholder is seeded into
+  // .secrets.yaml below — the user only fills the secret value.
+  for (const v of authVarNames) {
+    if (!(v in envVars)) envVars[v] = `@secret:${v}`;
+  }
+  // ARV-201 (R10/F2): when the spec declares no `components.securitySchemes`
+  // (GitHub publishes its OpenAPI this way), `deriveAuthVarNames` returns []
+  // and the loop above is a no-op — yet `zond request --api <name>` knows
+  // to attach `Authorization: Bearer <auth_token>` if the env carries an
+  // `auth_token`. Mirror the `.secrets.yaml` fallback (which already seeds
+  // `auth_token: ""` when authVarNames is empty) into `.env.yaml` so users
+  // do not need to hand-add `auth_token: "@secret:auth_token"` just to
+  // surface the Bearer header on bare specs.
+  if (authVarNames.length === 0 && !("auth_token" in envVars)) {
+    envVars.auth_token = "@secret:auth_token";
+  }
+  if (envVarsOverride) {
+    Object.assign(envVars, envVarsOverride);
+  }
+
+  // Spec-less registration is allowed, but we need a base_url from somewhere
+  // (server URL extracted from the spec, or envVars.base_url passed in by the
+  // caller). Without it the API is useless — `zond run` can't resolve {{base_url}}.
+  if (!spec && !envVars.base_url) {
+    throw new Error("setupApi requires --spec or envVars.base_url to register an API");
   }
 
   // Write .env.yaml in base_dir
@@ -116,26 +466,112 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     writeFileSync(envFilePath, toYaml(envVars) + "\n", "utf-8");
   }
 
-  // Create/update .gitignore to exclude env files
+  // Create/update .gitignore to exclude env / secret files
   const gitignorePath = join(baseDir, ".gitignore");
-  const gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+  let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+  let gitignoreDirty = false;
   if (!gitignoreContent.includes(".env*.yaml")) {
-    writeFileSync(
-      gitignorePath,
-      gitignoreContent + (gitignoreContent.endsWith("\n") || !gitignoreContent ? "" : "\n") + ".env*.yaml\n",
-      "utf-8",
-    );
+    gitignoreContent +=
+      (gitignoreContent.endsWith("\n") || !gitignoreContent ? "" : "\n") + ".env*.yaml\n";
+    gitignoreDirty = true;
+  }
+  // TASK-170 (m-10): keep `.secrets.yaml` git-invisible. Older `.env*.yaml`
+  // pattern matched it accidentally; pin it explicitly so a future glob
+  // narrowing can't regress.
+  if (!gitignoreContent.includes(".secrets.yaml")) {
+    gitignoreContent += ".secrets.yaml\n";
+    gitignoreDirty = true;
+  }
+  // TASK-174 (m-10): identity values are not secrets but they identify
+  // the user's account; keep them out of git too.
+  if (!gitignoreContent.includes(".identity.yaml")) {
+    gitignoreContent += ".identity.yaml\n";
+    gitignoreDirty = true;
+  }
+  if (gitignoreDirty) {
+    writeFileSync(gitignorePath, gitignoreContent, "utf-8");
+  }
+
+  // Seed `.secrets.yaml` placeholder once. The file lives gitignored
+  // alongside `.env.yaml`; values placed here are auto-registered with
+  // the SecretRegistry on load and never appear in artifacts.
+  const secretsPath = join(baseDir, ".secrets.yaml");
+  if (!existsSync(secretsPath)) {
+    const seedKeys = authVarNames.length > 0 ? authVarNames : ["auth_token"];
+    const lines = [
+      "# .secrets.yaml — gitignored, holds raw secret values.",
+      "# Reference these in .env.yaml as @secret:<key>.",
+      "# Values here are auto-registered for redaction in DB writes,",
+      "# HTML/JSON/JUnit reports, case-studies, and probe digests.",
+    ];
+    for (const k of seedKeys) lines.push(`${k}: ""  # required for live probes`);
+    lines.push("");
+    writeFileSync(secretsPath, lines.join("\n"), "utf-8");
+  }
+
+  // TASK-174 (m-10): seed `.identity.yaml` with placeholders for any
+  // canonical identity-keys that appear as path-params in the spec. The
+  // file is gitignored — values are visible locally for triage and
+  // hidden from outbound shares only when --redact-identity is set.
+  const identityKeys = [...pathParams.keys()].filter((k) =>
+    CANONICAL_IDENTITY_KEYS.has(k),
+  );
+  if (identityKeys.length > 0) {
+    const identityPath = join(baseDir, ".identity.yaml");
+    if (!existsSync(identityPath)) {
+      const lines = [
+        "# .identity.yaml — gitignored, holds non-secret-but-identifying values.",
+        "# Reference these in .env.yaml as @identity:<key>.",
+        "# Values are visible locally and in case-study drafts; pass",
+        "# --redact-identity (TASK-173) to swap them for placeholders when",
+        "# sharing reports outbound.",
+      ];
+      for (const k of identityKeys.sort()) {
+        lines.push(`${k}: ""  # fill with your ${k}`);
+      }
+      lines.push("");
+      writeFileSync(identityPath, lines.join("\n"), "utf-8");
+    }
+  }
+
+  const workspaceRoot = findWorkspaceRoot().root;
+
+  // Snapshot the dereferenced spec into apis/<name>/spec.json so all later
+  // commands (catalog, describe, generate, probe-*) read a self-contained
+  // local file. The spec lives inside the workspace and is git-trackable;
+  // an external --spec path is only consulted at register/refresh time.
+  let localSpecAbsPath: string | null = null;
+  if (dereferencedDoc) {
+    localSpecAbsPath = join(baseDir, SPEC_SNAPSHOT_FILENAME);
+    writeArtifactsFromDoc({
+      doc: dereferencedDoc,
+      baseDir,
+      apiName: name,
+      baseUrl,
+      workspaceRoot,
+    });
   }
 
   const normalizedTestPath = normalizePath(testPath);
   const normalizedBaseDir = normalizePath(baseDir);
 
+  // Persist the workspace-relative path to the local snapshot in
+  // collections.openapi_spec so we don't rely on the user's external path
+  // sticking around. Falls back to the external path only when the snapshot
+  // could not be created (no spec given to setupApi).
+  // Don't run normalizePath on the relative form — it calls resolve() and
+  // would re-absolutize the path. Posix-style separators are enough for
+  // SQLite + Windows compat.
+  const dbSpecPath = localSpecAbsPath
+    ? relative(workspaceRoot, localSpecAbsPath).replace(/\\/g, "/")
+    : (openapiSpec ?? undefined);
+
   // Create collection in DB
   const collectionId = createCollection({
     name,
     base_dir: normalizedBaseDir,
     test_path: normalizedTestPath,
-    openapi_spec: openapiSpec ?? undefined,
+    openapi_spec: dbSpecPath,
   });
 
   const pathParamsObj = pathParams.size > 0 ? Object.fromEntries(pathParams) : undefined;
@@ -148,6 +584,7 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     baseUrl,
     specEndpoints: endpointCount,
     ...(pathParamsObj ? { pathParams: pathParamsObj } : {}),
+    ...(authVarNames.length > 0 ? { authVars: authVarNames } : {}),
     ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

package/src/core/severity/category.ts

@@ -0,0 +1,94 @@
+/**
+ * Finding category taxonomy (ARV-251, m-21 pivot).
+ *
+ * Four categories replace the old SARIF-internal trio
+ * (conformance/security/data-rejection/other). Each finding belongs to
+ * exactly one category. Categories drive the per-section roll-up in
+ * reports — a small team sees `0 security, 12 reliability, 40 contract,
+ * 200 hygiene` and knows where to start, instead of one flat HIGH/LOW
+ * pile.
+ *
+ * Definitions:
+ * - `security`: exploit / auth / data-exposure / injection signals.
+ *   IDOR, mass-assignment with persistence, missing-auth, open CORS,
+ *   reflected XSS / CRLF in dangerous context.
+ * - `reliability`: server crashes / 5xx on valid input / rate-limit
+ *   absent / timeouts. Not security per se but production-impact.
+ * - `contract`: spec ↔ runtime drift. Schema mismatch, wrong status
+ *   codes, content-type negotiation failures, data-rejection contract
+ *   violations, missing required headers.
+ * - `hygiene`: static spec-lint, accept-without-impact, framework-level
+ *   "could be intentional" signals, naming/style. Bulk volume lives here.
+ */
+
+export type Category = "security" | "reliability" | "contract" | "hygiene";
+
+export const CATEGORY_ORDER: readonly Category[] = [
+  "security",
+  "reliability",
+  "contract",
+  "hygiene",
+] as const;
+
+/**
+ * Category lookup by check-id / probe-class-id. Adding a new
+ * finding-producer requires extending this map — the SARIF + reporter
+ * tests assert full coverage so a missing entry fails loudly rather
+ * than silently routing to a fallback.
+ */
+export const CATEGORY_BY_ID: Record<string, Category> = {
+  // ── reliability ──────────────────────────────────────────────
+  // 5xx on valid input is a server crash, not a security issue.
+  not_a_server_error: "reliability",
+
+  // ── contract ─────────────────────────────────────────────────
+  // Spec-conformance checks. Server behaviour drifts from declared
+  // contract — fix-worthy, but rarely security per se.
+  status_code_conformance: "contract",
+  content_type_conformance: "contract",
+  response_headers_conformance: "contract",
+  response_schema_conformance: "contract",
+  missing_required_header: "contract",
+  unsupported_method: "contract",
+  // Data-rejection: server should reject malformed bodies per spec.
+  // Falls under contract (spec said "reject", server accepted).
+  negative_data_rejection: "contract",
+  positive_data_acceptance: "contract",
+  // m-20 state-aware probes — cross-resource contract invariants.
+  cross_call_references: "contract",
+  idempotency_replay: "contract",
+  pagination_invariants: "contract",
+  lifecycle_transitions: "contract",
+  // ARV-256 (m-21) — small-team value-add. Rate-limit absence is a
+  // production reliability concern, not a security exploit.
+  rate_limit_headers_absent: "reliability",
+  open_cors_on_sensitive: "security",
+
+  // ── security ─────────────────────────────────────────────────
+  ignored_auth: "security",
+  use_after_free: "security",
+  ensure_resource_availability: "security",
+  // Probe classes
+  "mass-assignment": "security",
+  ssrf: "security",
+  crlf: "security",
+  xss: "security",
+  sqli: "security",
+  "open-redirect": "security",
+  "path-traversal": "security",
+  webhooks: "security",
+};
+
+/**
+ * Map check-id / probe-class-id to category. Falls back to "hygiene"
+ * for unknown ids — the SARIF reporter & tests assert this fallback
+ * never triggers for registered checks/probes.
+ */
+export function categoryFor(id: string): Category {
+  return CATEGORY_BY_ID[id] ?? "hygiene";
+}
+
+export function emptyCategoryBuckets(): Record<Category, number> {
+  return { security: 0, reliability: 0, contract: 0, hygiene: 0 };
+}
+