@kirrosh/zond 0.26.0 → 0.27.0

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

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-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

@@ -1,21 +0,0 @@
-/**
- * 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

@@ -1,9 +0,0 @@
-/** 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

@@ -1,24 +0,0 @@
-/** 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,13 +0,0 @@
-export function getByPath(obj: unknown, path: string, defaultVal?: unknown): unknown {
-  // 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];
-    if (result === undefined) return defaultVal;
-  }
-  return result;
-}

package/src/core/workspace/config.ts

@@ -1,129 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * 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

@@ -1,71 +0,0 @@
-/**
- * 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)));
-}