@kirrosh/zond 0.22.0 → 0.26.0

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/format-eta.ts

@@ -0,0 +1,21 @@
+/**
+ * ARV-249: human-readable duration formatter for ETA / progress lines.
+ *
+ * Distinct from `core/reporter/console.formatDuration`, which is geared to
+ * per-step latencies (sub-second resolution, single unit). Here we drop
+ * sub-second precision but emit two units once we cross a minute, so a
+ * five-minute ETA reads `5m12s` instead of `5m 12s`.
+ */
+export function formatEta(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return "?";
+  const s = Math.round(seconds);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) {
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return rem > 0 ? `${m}m${rem}s` : `${m}m`;
+  }
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return m > 0 ? `${h}h${m}m` : `${h}h`;
+}

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/utils.ts

@@ -1,5 +1,9 @@
 export function getByPath(obj: unknown, path: string, defaultVal?: unknown): unknown {
-  const keys = path.split(".");
+  // Normalize JSONPath-like bracket indexing (`data[0].id`) to dotted form
+  // (`data.0.id`) so callers can use either spelling. Numeric segments also
+  // index arrays correctly because `array["0"]` is equivalent to `array[0]`.
+  const normalized = path.replace(/\[(\d+)\]/g, ".$1").replace(/^\./, "");
+  const keys = normalized.split(".");
   let result: unknown = obj;
   for (const key of keys) {
     result = (result as Record<string, unknown>)?.[key];

package/src/core/workspace/config.ts

@@ -0,0 +1,129 @@
+/**
+ * Workspace `zond.config.yml` loader (TASK-301).
+ *
+ * Centralises read-only access to workspace-level defaults. Right now only
+ * two fields are honoured:
+ *
+ *   defaults:
+ *     timeout_ms: 30000   # used by cleanup / prepare-fixtures / probe
+ *                         # mass-assignment / probe security / request
+ *     rate_limit: 5       # used by `zond run` (number, or "auto")
+ *
+ * Resolution chain across the CLI (highest wins):
+ *
+ *   CLI flag → per-API .env.yaml meta → workspace defaults → hard-coded fallback
+ *
+ * Per-API overrides live in `apis/<name>/.env.yaml` as `rateLimit:` /
+ * `timeoutMs:` (see `loadEnvMeta`); we deliberately don't carve a second
+ * channel into this file to avoid two ways of saying the same thing.
+ *
+ * Read-once-and-cache: the file is parsed at most once per process from
+ * the workspace root resolved by `findWorkspaceRoot`. Tests can call
+ * `_resetWorkspaceConfigCache()` between runs.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findWorkspaceRoot } from "./root.ts";
+
+export interface WorkspaceDefaults {
+  /** Per-request timeout in ms applied when the CLI flag and `.env.yaml` are silent. */
+  timeoutMs?: number;
+  /** Run-time rate limit (rps) or `"auto"`. */
+  rateLimit?: number | "auto";
+}
+
+let cache: { root: string; defaults: WorkspaceDefaults } | null = null;
+
+function parseTimeoutMs(v: unknown): number | undefined {
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
+  if (typeof v === "string") {
+    const n = Number.parseInt(v, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return undefined;
+}
+
+function parseRateLimit(v: unknown): number | "auto" | undefined {
+  if (v === "auto") return "auto";
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
+  if (typeof v === "string") {
+    if (v === "auto") return "auto";
+    const n = Number.parseFloat(v);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return undefined;
+}
+
+function readDefaults(configPath: string): WorkspaceDefaults {
+  if (!existsSync(configPath)) return {};
+  let parsed: unknown;
+  try {
+    const text = readFileSync(configPath, "utf8");
+    parsed = Bun.YAML.parse(text);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  const obj = parsed as Record<string, unknown>;
+  const defaultsRaw = obj.defaults;
+  if (typeof defaultsRaw !== "object" || defaultsRaw === null || Array.isArray(defaultsRaw)) return {};
+  const d = defaultsRaw as Record<string, unknown>;
+  const out: WorkspaceDefaults = {};
+  const t = parseTimeoutMs(d.timeout_ms ?? d.timeoutMs);
+  if (t !== undefined) out.timeoutMs = t;
+  const r = parseRateLimit(d.rate_limit ?? d.rateLimit);
+  if (r !== undefined) out.rateLimit = r;
+  return out;
+}
+
+/**
+ * Returns the workspace defaults block, cached for the lifetime of the
+ * process. When no workspace marker is found, returns `{}` (no defaults).
+ */
+export function loadWorkspaceDefaults(cwd?: string): WorkspaceDefaults {
+  const ws = findWorkspaceRoot(cwd);
+  if (ws.fromFallback) return {};
+  if (cache && cache.root === ws.root) return cache.defaults;
+  const defaults = readDefaults(join(ws.root, "zond.config.yml"));
+  cache = { root: ws.root, defaults };
+  return defaults;
+}
+
+/** Test helper: drop the parse cache so the next call re-reads from disk. */
+export function _resetWorkspaceConfigCache(): void {
+  cache = null;
+}
+
+export const HARD_DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Resolve `--timeout` via CLI > per-API `.env.yaml` (`timeoutMs`) > workspace
+ * `defaults.timeout_ms` > 30000. Each layer accepts `undefined` to mean
+ * "fall through".
+ */
+export function resolveTimeoutMs(
+  cliFlag: number | undefined,
+  envMetaTimeout: number | undefined,
+  cwd?: string,
+): number {
+  if (cliFlag !== undefined) return cliFlag;
+  if (envMetaTimeout !== undefined) return envMetaTimeout;
+  const ws = loadWorkspaceDefaults(cwd);
+  return ws.timeoutMs ?? HARD_DEFAULT_TIMEOUT_MS;
+}
+
+/**
+ * Resolve `--rate-limit` via CLI > per-API `.env.yaml` (`rateLimit`) >
+ * workspace `defaults.rate_limit` > undefined (no throttling).
+ */
+export function resolveRateLimit(
+  cliFlag: number | "auto" | undefined,
+  envMetaRateLimit: number | "auto" | undefined,
+  cwd?: string,
+): number | "auto" | undefined {
+  if (cliFlag !== undefined) return cliFlag;
+  if (envMetaRateLimit !== undefined) return envMetaRateLimit;
+  const ws = loadWorkspaceDefaults(cwd);
+  return ws.rateLimit;
+}

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 };
+}

package/src/core/workspace/fixture-gaps.ts

@@ -0,0 +1,71 @@
+/**
+ * ARV-324: `.fixture-gaps.yaml` — per-API sidecar recording operations
+ * that `prepare-fixtures`/`discover` already confirmed return a client
+ * error (or an empty list) while hunting for fixture values — e.g. an
+ * empty/under-provisioned test account.
+ *
+ * `checks run` runs as a separate process invocation and, without this
+ * file, has no way to tell "known fixture gap" apart from "new backend
+ * bug" — both would land on the same operation with
+ * `recommended_action: report_backend_bug`. Loading this file lets the
+ * classifier downgrade to `fix_fixture` instead (see
+ * `core/classifier/recommended-action.ts`).
+ *
+ * Not the manifest (`.api-fixtures.yaml` stays spec-derived/read-only,
+ * regenerated only by `refresh-api`) — this is runtime-observed state,
+ * so it gets its own file, rewritten wholesale on every
+ * discover/prepare-fixtures run so a since-fixed gap doesn't linger.
+ */
+
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+
+export interface FixtureGap {
+  method: string;
+  path: string;
+  resource: string;
+  var: string;
+  reason: string;
+}
+
+const FILENAME = ".fixture-gaps.yaml";
+
+export async function readFixtureGaps(apiDir: string): Promise<FixtureGap[]> {
+  const file = Bun.file(join(apiDir, FILENAME));
+  if (!(await file.exists())) return [];
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(await file.text());
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray((parsed as { gaps?: unknown }).gaps)) {
+    return [];
+  }
+  return (parsed as { gaps: FixtureGap[] }).gaps;
+}
+
+export async function writeFixtureGaps(apiDir: string, gaps: FixtureGap[]): Promise<void> {
+  const path = join(apiDir, FILENAME);
+  const header = `# .fixture-gaps.yaml — auto-written by prepare-fixtures/discover (ARV-324)
+#
+# Operations that returned a client error (or an empty list) while zond
+# hunted for a fixture value — a resource that's empty/inaccessible in
+# the target API. Read by \`checks run\` so it doesn't relabel the same
+# known gap as report_backend_bug. Safe to delete — regenerated on the
+# next prepare-fixtures / discover run.
+`;
+  const { stringify } = await import("yaml");
+  const body = stringify({ gaps }, { lineWidth: 0, defaultStringType: "PLAIN" });
+  await writeFile(path, header + "\n" + body, "utf-8");
+}
+
+/** Key an operation the same way on both the write side (discover/bootstrap,
+ *  always GET list-probes) and the read side (`CheckFinding.operation`). */
+export function gapKey(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+export function gapIndex(gaps: FixtureGap[]): Set<string> {
+  return new Set(gaps.map((g) => gapKey(g.method, g.path)));
+}