@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/spec/infer-schema.ts

@@ -0,0 +1,102 @@
+/**
+ * ARV-175: infer a JSON Schema (draft-07 subset) from a set of sample
+ * response bodies. Built-in, zero-dependency — quicktype/genson would each
+ * drag in a large dependency tree, which contradicts zond's dumb-tool /
+ * minimal-deps charter (see src/CLAUDE.md). The `--engine` flag keeps the
+ * seam open if a heavier engine is ever wanted, but `builtin` is the default
+ * and the only one wired.
+ *
+ * Strategy — structural union over the samples:
+ *   - primitives → { type }
+ *   - arrays     → { type: "array", items: <merge of every element> }
+ *   - objects    → { type: "object", properties, required }
+ *                  `required` = keys present in EVERY object sample (an
+ *                  intersection — a field missing from one sample is optional).
+ *   - mixed types across samples → { type: [sorted, unique] } (or a bare
+ *     type when they all agree). null folds into the type list so a
+ *     sometimes-null field reads as `["null","string"]`.
+ *
+ * Not a full inference engine: no format detection, no enum mining, no
+ * anyOf for heterogeneous array items beyond a type union. Good enough to
+ * seed `response_schema_conformance` on specs that declare no response
+ * schema, which is the whole point (ARV-175 goal).
+ */
+
+export type JsonSchema = Record<string, unknown>;
+
+type JsonType = "null" | "boolean" | "integer" | "number" | "string" | "array" | "object";
+
+function typeOf(v: unknown): JsonType {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  const t = typeof v;
+  if (t === "boolean") return "boolean";
+  if (t === "number") return Number.isInteger(v) ? "integer" : "number";
+  if (t === "string") return "string";
+  return "object";
+}
+
+/** Infer a schema from one or more samples of the same logical value. */
+export function inferSchema(samples: unknown[]): JsonSchema {
+  const nonEmpty = samples.filter((s) => s !== undefined);
+  if (nonEmpty.length === 0) return {};
+
+  const types = new Set<JsonType>();
+  for (const s of nonEmpty) types.add(typeOf(s));
+
+  // Object: merge properties across every object sample.
+  if (types.has("object")) {
+    const objSamples = nonEmpty.filter((s) => typeOf(s) === "object") as Array<Record<string, unknown>>;
+    const propSamples = new Map<string, unknown[]>();
+    for (const obj of objSamples) {
+      for (const [k, v] of Object.entries(obj)) {
+        if (!propSamples.has(k)) propSamples.set(k, []);
+        propSamples.get(k)!.push(v);
+      }
+    }
+    // required = keys present in ALL object samples (intersection).
+    const required = [...propSamples.keys()].filter(
+      (k) => objSamples.every((obj) => Object.prototype.hasOwnProperty.call(obj, k)),
+    );
+    const properties: JsonSchema = {};
+    for (const [k, vs] of propSamples) properties[k] = inferSchema(vs);
+
+    const schema: JsonSchema = { type: mergeType(types, "object") };
+    if (Object.keys(properties).length > 0) schema.properties = sortKeys(properties);
+    if (required.length > 0) schema.required = required.sort();
+    return schema;
+  }
+
+  // Array: items schema is the union of every element across every sample.
+  if (types.has("array")) {
+    const elements: unknown[] = [];
+    for (const s of nonEmpty) if (Array.isArray(s)) elements.push(...s);
+    const schema: JsonSchema = { type: mergeType(types, "array") };
+    if (elements.length > 0) schema.items = inferSchema(elements);
+    return schema;
+  }
+
+  // Primitives only.
+  return { type: mergeType(types) };
+}
+
+/** Collapse the observed type set into a single `type` value: a string when
+ *  they agree (preferring `primary` if given, e.g. object/array), otherwise a
+ *  sorted unique list. `integer`+`number` collapses to `number`. */
+function mergeType(types: Set<JsonType>, primary?: JsonType): string | string[] {
+  const t = new Set(types);
+  if (t.has("number") && t.has("integer")) t.delete("integer");
+  if (primary && t.size > 1) {
+    // Object/array with a stray null etc. — keep the structural type plus null.
+    const rest = [...t].filter((x) => x !== primary);
+    if (rest.length === 1 && rest[0] === "null") return [primary, "null"].sort();
+  }
+  const arr = [...t].sort();
+  return arr.length === 1 ? arr[0]! : arr;
+}
+
+function sortKeys(obj: JsonSchema): JsonSchema {
+  const out: JsonSchema = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}

package/src/core/spec/merge-specs.ts

@@ -0,0 +1,156 @@
+/**
+ * Deterministic union of two or more dereferenced OpenAPI documents into
+ * one (ARV-375). Motivation: an org running multiple API versions
+ * side-by-side (v1/v2, deprecated-but-live + current) wants combined
+ * coverage instead of re-scanning each version and reconciling reports by
+ * hand. Before this, that merge was a one-off python script per session.
+ *
+ * Policy — pure, deterministic, no judgment (belongs in zond core per the
+ * litmus test):
+ *   - `paths`: union; on a path-key collision the LATER spec wins, and the
+ *     collision is recorded so the caller can warn (silent shadowing of a
+ *     real endpoint is a correctness trap).
+ *   - `components.*`: union per sub-bucket (schemas, securitySchemes,
+ *     parameters, responses, …); later wins. A component-name collision
+ *     whose two definitions DIFFER (deep-unequal) is reported separately —
+ *     that is the dangerous case (same name, different shape).
+ *   - `servers`, `security`, `tags`: unioned & de-duped by value/name.
+ *   - `info`: taken from the first spec; `version` becomes the unique
+ *     source versions joined with `+` so the merged target is self-labelling.
+ *
+ * Inputs are assumed already dereferenced (readOpenApiSpec output), so path
+ * operations are self-contained — no cross-spec $ref resolution needed.
+ */
+
+import type { OpenAPIV3 } from "openapi-types";
+
+export interface MergeInput {
+  /** Source label (path or URL) for the merge summary. */
+  source: string;
+  doc: OpenAPIV3.Document;
+}
+
+export interface MergeSummary {
+  sources: { source: string; paths: number }[];
+  totalPaths: number;
+  /** Path keys declared by more than one spec (later-wins applied). */
+  pathCollisions: string[];
+  /** `components.<bucket>.<name>` whose definition differs across specs. */
+  schemaConflicts: string[];
+}
+
+export interface MergeResult {
+  merged: OpenAPIV3.Document;
+  summary: MergeSummary;
+}
+
+const COMPONENT_BUCKETS = [
+  "schemas",
+  "responses",
+  "parameters",
+  "examples",
+  "requestBodies",
+  "headers",
+  "securitySchemes",
+  "links",
+  "callbacks",
+] as const;
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  // Cheap structural compare — specs are plain JSON after dereference.
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function mergeOpenApiDocs(inputs: MergeInput[]): MergeResult {
+  if (inputs.length === 0) throw new Error("mergeOpenApiDocs: no specs to merge");
+  const first = inputs[0]!.doc;
+
+  const paths: NonNullable<OpenAPIV3.Document["paths"]> = {};
+  const pathCollisions: string[] = [];
+  const sources: MergeSummary["sources"] = [];
+
+  for (const { source, doc } of inputs) {
+    const specPaths = doc.paths ?? {};
+    let count = 0;
+    for (const [p, item] of Object.entries(specPaths)) {
+      if (p in paths) pathCollisions.push(p);
+      paths[p] = item as OpenAPIV3.PathItemObject;
+      count++;
+    }
+    sources.push({ source, paths: count });
+  }
+
+  // Merge components bucket-by-bucket; flag same-name-different-shape.
+  const schemaConflicts: string[] = [];
+  const components: Record<string, Record<string, unknown>> = {};
+  for (const { doc } of inputs) {
+    const comps = (doc.components ?? {}) as Record<string, Record<string, unknown> | undefined>;
+    for (const bucket of COMPONENT_BUCKETS) {
+      const incoming = comps[bucket];
+      if (!incoming) continue;
+      const target = (components[bucket] ??= {});
+      for (const [name, def] of Object.entries(incoming)) {
+        if (name in target && !deepEqual(target[name], def)) {
+          schemaConflicts.push(`${bucket}.${name}`);
+        }
+        target[name] = def;
+      }
+    }
+  }
+
+  // Union servers by url, security by value, tags by name.
+  const servers = dedupeBy(
+    inputs.flatMap((i) => i.doc.servers ?? []),
+    (s) => s.url,
+  );
+  const security = dedupeBy(
+    inputs.flatMap((i) => i.doc.security ?? []),
+    (s) => JSON.stringify(s),
+  );
+  const tags = dedupeBy(
+    inputs.flatMap((i) => i.doc.tags ?? []),
+    (t) => t.name,
+  );
+
+  const versions = dedupe(inputs.map((i) => i.doc.info?.version).filter(Boolean) as string[]);
+
+  const merged: OpenAPIV3.Document = {
+    ...first,
+    openapi: first.openapi ?? "3.0.0",
+    info: {
+      ...first.info,
+      version: versions.join("+") || first.info?.version || "merged",
+    },
+    paths,
+    ...(Object.keys(components).length > 0 ? { components: components as OpenAPIV3.ComponentsObject } : {}),
+    ...(servers.length > 0 ? { servers } : {}),
+    ...(security.length > 0 ? { security } : {}),
+    ...(tags.length > 0 ? { tags } : {}),
+  };
+
+  return {
+    merged,
+    summary: {
+      sources,
+      totalPaths: Object.keys(paths).length,
+      pathCollisions: dedupe(pathCollisions),
+      schemaConflicts: dedupe(schemaConflicts),
+    },
+  };
+}
+
+function dedupe<T>(arr: T[]): T[] {
+  return [...new Set(arr)];
+}
+
+function dedupeBy<T>(arr: T[], key: (x: T) => string): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const x of arr) {
+    const k = key(x);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(x);
+  }
+  return out;
+}

package/src/core/spec/schema-from-runs.ts

@@ -0,0 +1,117 @@
+/**
+ * ARV-175: extract 2xx response bodies from a persisted run and infer a
+ * JSON Schema per (endpoint, status). The output `patch.schema.json` is the
+ * input to `refresh-api --merge-schema` (ARV-176), which folds it into the
+ * spec overlay so `response_schema_conformance` has something to check on
+ * APIs whose upstream spec declares no response schemas.
+ */
+
+import { inferSchema, type JsonSchema } from "./infer-schema.ts";
+import { specPathToRegex, normalizePath } from "../generator/coverage-scanner.ts";
+import type { EndpointInfo } from "../generator/types.ts";
+
+export interface SchemaFromRunsResult {
+  /** endpoint label (`METHOD /path/{tpl}`) → status code → inferred schema. */
+  patch: Record<string, Record<string, JsonSchema>>;
+  /** Per-group accounting for the CLI to report. */
+  groups: Array<{
+    endpoint: string;
+    status: string;
+    samples: number;
+    emitted: boolean;
+    reason?: string;
+  }>;
+}
+
+export interface ResultRow {
+  request_method: string | null;
+  request_url: string | null;
+  response_status: number | null;
+  response_body: string | null;
+}
+
+/** Strip base URL, query, and trailing slash from a concrete request URL,
+ *  leaving just the path for spec-template matching. */
+function pathOf(rawUrl: string): string {
+  let p = rawUrl;
+  // Drop scheme+host if present.
+  const schemeIdx = p.indexOf("://");
+  if (schemeIdx !== -1) {
+    const afterScheme = p.slice(schemeIdx + 3);
+    const slash = afterScheme.indexOf("/");
+    p = slash === -1 ? "/" : afterScheme.slice(slash);
+  }
+  const q = p.indexOf("?");
+  if (q !== -1) p = p.slice(0, q);
+  return p.replace(/\/+$/, "") || "/";
+}
+
+/** Match a concrete path to the most specific spec endpoint (fewest params
+ *  wins, so `/users/me` beats `/users/{id}`). Returns the endpoint label. */
+function matchEndpoint(
+  method: string,
+  concretePath: string,
+  endpoints: EndpointInfo[],
+): string | null {
+  const norm = normalizePath(concretePath);
+  const candidates = endpoints
+    .filter((e) => e.method.toUpperCase() === method.toUpperCase())
+    .filter((e) => specPathToRegex(e.path).test(norm))
+    .sort((a, b) => paramCount(a.path) - paramCount(b.path));
+  const best = candidates[0];
+  return best ? `${best.method.toUpperCase()} ${best.path}` : null;
+}
+
+function paramCount(path: string): number {
+  return (path.match(/\{[^}]+\}/g) ?? []).length;
+}
+
+export interface SchemaFromRunsOptions {
+  results: ResultRow[];
+  endpoints: EndpointInfo[];
+  /** Minimum 2xx samples per (endpoint, status) group to emit a schema. */
+  minSamples: number;
+}
+
+export function schemaFromRuns(opts: SchemaFromRunsOptions): SchemaFromRunsResult {
+  const { results, endpoints, minSamples } = opts;
+  // (endpoint → status → parsed bodies)
+  const buckets = new Map<string, Map<string, unknown[]>>();
+  // Preserve unmatched URLs so the CLI can hint at spec/base-url drift.
+  for (const r of results) {
+    if (r.response_status == null || r.response_status < 200 || r.response_status >= 300) continue;
+    if (!r.response_body || !r.request_url || !r.request_method) continue;
+    let body: unknown;
+    try {
+      body = JSON.parse(r.response_body);
+    } catch {
+      continue; // non-JSON 2xx body — nothing to infer for application/json
+    }
+    const endpoint = matchEndpoint(r.request_method, pathOf(r.request_url), endpoints);
+    if (!endpoint) continue;
+    const status = String(r.response_status);
+    if (!buckets.has(endpoint)) buckets.set(endpoint, new Map());
+    const byStatus = buckets.get(endpoint)!;
+    if (!byStatus.has(status)) byStatus.set(status, []);
+    byStatus.get(status)!.push(body);
+  }
+
+  const patch: SchemaFromRunsResult["patch"] = {};
+  const groups: SchemaFromRunsResult["groups"] = [];
+  // Deterministic order: sort by endpoint then status.
+  for (const endpoint of [...buckets.keys()].sort()) {
+    const byStatus = buckets.get(endpoint)!;
+    for (const status of [...byStatus.keys()].sort()) {
+      const samples = byStatus.get(status)!;
+      if (samples.length < minSamples) {
+        groups.push({ endpoint, status, samples: samples.length, emitted: false, reason: `<${minSamples} samples` });
+        continue;
+      }
+      const schema = inferSchema(samples);
+      if (!patch[endpoint]) patch[endpoint] = {};
+      patch[endpoint]![status] = schema;
+      groups.push({ endpoint, status, samples: samples.length, emitted: true });
+    }
+  }
+  return { patch, groups };
+}

package/src/core/spec/schema-overlay.ts

@@ -0,0 +1,130 @@
+/**
+ * ARV-176: response-schema overlay. `schema-from-runs` (ARV-175) emits a
+ * `patch.schema.json` of inferred response schemas keyed by `METHOD /path` →
+ * status. `refresh-api --merge-schema` folds that patch into a persistent
+ * overlay (`apis/<name>/.api-schema.local.yaml`) and applies it onto the
+ * freshly-pulled spec.json.
+ *
+ * Why a dedicated overlay file (not `.api-resources.local.yaml`): that file
+ * is resource-shaped (ResourceYaml[]); response schemas are a different
+ * dimension and shoehorning them in would muddy both. Same survives-refresh
+ * contract as ARV-111's resource overlay — refresh-api re-applies it on every
+ * run, so an upstream re-pull never loses the mined schemas.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { JsonSchema } from "./infer-schema.ts";
+
+export const SCHEMA_OVERLAY_FILENAME = ".api-schema.local.yaml";
+
+/** `METHOD /path` → status code → JSON Schema. */
+export type ResponseSchemaPatch = Record<string, Record<string, JsonSchema>>;
+
+interface SchemaOverlayFile {
+  version: 1;
+  response_schemas: ResponseSchemaPatch;
+}
+
+export function overlayPath(baseDir: string): string {
+  return join(baseDir, SCHEMA_OVERLAY_FILENAME);
+}
+
+/** Load the overlay for an API, or null when absent. */
+export function loadSchemaOverlay(baseDir: string): ResponseSchemaPatch | null {
+  const p = overlayPath(baseDir);
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = parseYaml(readFileSync(p, "utf-8")) as Partial<SchemaOverlayFile> | null;
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed.response_schemas ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Union two patches; entries in `incoming` win on collision. */
+export function mergePatch(base: ResponseSchemaPatch | null, incoming: ResponseSchemaPatch): ResponseSchemaPatch {
+  const out: ResponseSchemaPatch = {};
+  for (const [ep, byStatus] of Object.entries(base ?? {})) out[ep] = { ...byStatus };
+  for (const [ep, byStatus] of Object.entries(incoming)) {
+    out[ep] = { ...(out[ep] ?? {}), ...byStatus };
+  }
+  return out;
+}
+
+/** Persist the overlay (sorted for a stable, diff-friendly file). */
+export function saveSchemaOverlay(baseDir: string, patch: ResponseSchemaPatch): void {
+  const sorted: ResponseSchemaPatch = {};
+  for (const ep of Object.keys(patch).sort()) {
+    const byStatus = patch[ep]!;
+    sorted[ep] = {};
+    for (const st of Object.keys(byStatus).sort()) sorted[ep]![st] = byStatus[st]!;
+  }
+  const file: SchemaOverlayFile = { version: 1, response_schemas: sorted };
+  writeFileSync(overlayPath(baseDir), stringifyYaml(file), "utf-8");
+}
+
+export interface ApplyOverlayResult {
+  /** `METHOD /path status` labels that got a schema written. */
+  applied: string[];
+  /** Labels skipped because a schema already existed (no --force). */
+  preserved: string[];
+  /** Labels skipped because the endpoint no longer exists upstream. */
+  conflicts: string[];
+}
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+
+/**
+ * Apply a response-schema patch onto a dereferenced OpenAPI doc, in place.
+ * Fills `responses.<status>.content['application/json'].schema` where it is
+ * absent (or with `force`). An endpoint/method missing from the doc is a
+ * conflict (upstream drift) and is skipped, not fabricated.
+ */
+export function applySchemaOverlay(
+  doc: unknown,
+  patch: ResponseSchemaPatch,
+  opts: { force?: boolean } = {},
+): ApplyOverlayResult {
+  const result: ApplyOverlayResult = { applied: [], preserved: [], conflicts: [] };
+  const paths = (doc as { paths?: Record<string, unknown> }).paths;
+  if (!paths) {
+    for (const [ep, byStatus] of Object.entries(patch)) {
+      for (const st of Object.keys(byStatus)) result.conflicts.push(`${ep} ${st}`);
+    }
+    return result;
+  }
+
+  for (const [endpoint, byStatus] of Object.entries(patch)) {
+    const sp = endpoint.indexOf(" ");
+    const method = endpoint.slice(0, sp).toLowerCase();
+    const path = endpoint.slice(sp + 1);
+    const pathItem = paths[path] as Record<string, unknown> | undefined;
+    const op = pathItem && HTTP_METHODS.includes(method)
+      ? (pathItem[method] as { responses?: Record<string, unknown> } | undefined)
+      : undefined;
+
+    for (const [status, schema] of Object.entries(byStatus)) {
+      const label = `${endpoint} ${status}`;
+      if (!op) {
+        result.conflicts.push(label);
+        continue;
+      }
+      if (!op.responses) op.responses = {};
+      const responses = op.responses as Record<string, { content?: Record<string, { schema?: unknown }> }>;
+      if (!responses[status]) responses[status] = { content: {} } as { content: Record<string, { schema?: unknown }> };
+      const resp = responses[status]!;
+      if (!resp.content) resp.content = {};
+      const mt = resp.content["application/json"] ?? (resp.content["application/json"] = {});
+      if (mt.schema !== undefined && !opts.force) {
+        result.preserved.push(label);
+        continue;
+      }
+      mt.schema = schema;
+      result.applied.push(label);
+    }
+  }
+  return result;
+}

package/src/core/util/ajv.ts

@@ -0,0 +1,13 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+/** OpenAPI 3.1 → JSON Schema Draft 2020-12 (Ajv2020); 3.0 → Draft 4/7-ish
+ *  (plain Ajv). Both get the `ajv-formats` format keywords registered. */
+export function makeAjv(isV31: boolean, opts: ConstructorParameters<typeof Ajv>[0] = {}): Ajv {
+  const ajv = isV31
+    ? new (Ajv2020 as unknown as typeof Ajv)(opts)
+    : new Ajv(opts);
+  addFormats(ajv);
+  return ajv;
+}

package/src/core/util/headers.ts

@@ -0,0 +1,9 @@
+/** Case-insensitive check whether a header is already present in the map.
+ *  Deliberately not `new Headers(headers).has(name)` — the WHATWG Headers
+ *  constructor throws on values with invalid characters (e.g. raw CRLF),
+ *  which real interpolated var values can contain; a plain key scan never
+ *  throws on the value shape. */
+export function hasHeaderCI(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}

package/src/core/util/url.ts

@@ -0,0 +1,24 @@
+/** Concatenate baseUrl and path, stripping any trailing slashes from base. */
+export function joinBaseAndPath(baseUrl: string | undefined, path: string): string {
+  if (!baseUrl) return path;
+  return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}
+
+export type QueryValue = string | number | boolean;
+
+/** Build a URL from base + path with an optional query record. Values are
+ *  coerced to strings via String(); URL-encoding is delegated to
+ *  URLSearchParams. */
+export function buildUrl(
+  baseUrl: string | undefined,
+  path: string,
+  query?: Record<string, QueryValue>,
+): string {
+  let url = joinBaseAndPath(baseUrl, path);
+  if (query && Object.keys(query).length > 0) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) params.append(k, String(v));
+    url += `?${params.toString()}`;
+  }
+  return url;
+}

package/src/core/workspace/fixture-gap-report.ts

@@ -0,0 +1,84 @@
+/**
+ * ARV-349/350: deterministic fixture-gap report for `prepare-fixtures`.
+ *
+ * prepare-fixtures is a single-pass discover (ARV-336 removed the autonomous
+ * seed engine). It fills FK ids it can resolve from list endpoints, but it
+ * used to neither fill NOR flag two other classes of gap, so suites ran with
+ * unresolved placeholders and produced noisy 400/404s:
+ *
+ *   - undefinedVars (ARV-349): a suite references {{bank_code}} / {{tax_id}}
+ *     that nothing produces — not an env value, not a prior-step capture, not
+ *     a manifest entry. The user / agent must supply it.
+ *   - unseededRoots (ARV-350): a REQUIRED manifest var (e.g. {{account}}) that
+ *     is empty in env, referenced by a suite, and captured by no step — the
+ *     dependency-chain HEAD that gates dependent CRUD suites (persons-crud,
+ *     external_accounts-crud all skip: "required fixture {{account}} is empty").
+ *     Source-agnostic on purpose: real manifests model this root as `path`
+ *     required:true with an empty default, not necessarily `capture-chain`.
+ *
+ * REPORT ONLY — never invents a value (ARV-349 #2) and never auto-seeds
+ * (ARV-350 #2). Deterministic (same suites+env+manifest → same report), so it
+ * belongs in zond; supplying the values is the agent's/user's job.
+ */
+
+import type { TestSuite } from "../parser/types.ts";
+import {
+  preflightCheckVars,
+  collectCapturesAndSets,
+  collectStepRefs,
+} from "../runner/preflight-vars.ts";
+
+export interface FixtureGapReport {
+  /** Suite {{vars}} with no producer (not env, capture, param, or generator). */
+  undefinedVars: { variable: string; refs: number; suites: string[] }[];
+  /** Required manifest vars that are empty, suite-referenced, and step-unseeded. */
+  unseededRoots: { variable: string }[];
+}
+
+export function reportFixtureGaps(
+  suites: TestSuite[],
+  env: Record<string, string>,
+  requiredEmptyVars: Set<string>,
+): FixtureGapReport {
+  // Match runtime capture scoping: only `setup: true` suites share their
+  // captures into other suites (TestSuite.setup); a regular suite's captures
+  // stay local to itself. So a var is "seeded" for suite S iff env holds it,
+  // a setup suite captures it, or S itself captures it.
+  const setupProduced = new Set<string>();
+  for (const suite of suites) {
+    if (!suite.setup) continue;
+    for (const step of suite.tests) collectCapturesAndSets(step, setupProduced);
+  }
+
+  // Unseeded root = required + empty in env + SOME referencing suite cannot
+  // produce it (not a setup capture, not captured within that suite). This
+  // catches cross-suite roots like {{account}}: crud-accounts creates it, but
+  // persons-crud references it without a create → that suite skips at runtime.
+  const rootSet = new Set<string>();
+  for (const suite of suites) {
+    const seeded = new Set<string>(setupProduced);
+    for (const step of suite.tests) collectCapturesAndSets(step, seeded);
+    for (const step of suite.tests) {
+      for (const v of collectStepRefs(step)) {
+        if (requiredEmptyVars.has(v) && !seeded.has(v)) rootSet.add(v);
+      }
+    }
+  }
+  const unseededRoots = [...rootSet].sort().map(variable => ({ variable }));
+
+  // Undefined vars = preflight hits, minus the roots we already called out
+  // (a root absent from env would otherwise land in both buckets).
+  const byVar = new Map<string, { refs: number; suites: Set<string> }>();
+  for (const h of preflightCheckVars(suites, env)) {
+    if (rootSet.has(h.variable)) continue;
+    let e = byVar.get(h.variable);
+    if (!e) { e = { refs: 0, suites: new Set() }; byVar.set(h.variable, e); }
+    e.refs++;
+    e.suites.add(h.suite);
+  }
+  const undefinedVars = [...byVar.entries()]
+    .map(([variable, e]) => ({ variable, refs: e.refs, suites: [...e.suites].sort() }))
+    .sort((a, b) => a.variable.localeCompare(b.variable));
+
+  return { undefinedVars, unseededRoots };
+}