@kirrosh/zond 0.26.1 → 0.27.0

package/src/core/runner/form-encode.ts

@@ -1,41 +0,0 @@
-/**
- * ARV-149 / ARV-150: encode a nested JS object as
- * `application/x-www-form-urlencoded` using bracket notation — the
- * canonical Stripe / Rails / PHP convention for nested fields:
- *
- *   { address: { line1: "x", line2: "y" }, items: [{ id: 1 }, { id: 2 }] }
- *   →  address[line1]=x&address[line2]=y&items[0][id]=1&items[1][id]=2
- *
- * Shared between `zond request --form`, the YAML runner's `form:` step,
- * and the mass-assignment probe's form-bodied endpoints. The probe-side
- * adoption (ARV-150) is what restores 265 SKIPPED Stripe endpoints.
- */
-function appendFormParam(params: URLSearchParams, key: string, value: unknown): void {
-  if (value === null || value === undefined) return;
-  if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) appendFormParam(params, `${key}[${i}]`, value[i]);
-  } else if (typeof value === "object") {
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      appendFormParam(params, `${key}[${k}]`, v);
-    }
-  } else {
-    params.append(key, String(value));
-  }
-}
-
-export function encodeFormBody(body: Record<string, unknown>): string {
-  const params = new URLSearchParams();
-  for (const [k, v] of Object.entries(body)) appendFormParam(params, k, v);
-  return params.toString();
-}
-
-/** Flatten a nested JS object to a `Record<string, string>` using the same
- *  bracket-notation walk as `encodeFormBody`, suitable for the YAML
- *  runner's `form:` step (which is typed as `Record<string, string>` and
- *  serialised via `URLSearchParams`). */
-export function flattenToFormFields(body: unknown): Record<string, string> {
-  if (!body || typeof body !== "object") return {};
-  const params = new URLSearchParams();
-  for (const [k, v] of Object.entries(body as Record<string, unknown>)) appendFormParam(params, k, v);
-  return Object.fromEntries(params.entries());
-}

package/src/core/runner/http-client.ts

@@ -1,224 +0,0 @@
-import type { HttpRequest, HttpResponse } from "./types.ts";
-import { type RateLimiter, parseRetryAfter, parseRateLimitHeaders } from "./rate-limiter.ts";
-
-/**
- * ARV-265: module-level audit hook for commands that don't drive their
- * HTTP through the suite runner. Each `executeRequest` call fires the
- * registered recorder with the final outcome (or the swallowed network
- * error if the call exhausted its retry budget). Recorders MUST NOT
- * throw — the http client treats them as fire-and-forget telemetry.
- *
- * Convention: a command sets the recorder before the live work begins,
- * unsets it in a `finally` block. There can be at most one recorder at
- * a time; nesting is a bug (we surface it on stderr but keep the inner
- * recorder so the live command's results take precedence).
- */
-export interface AuditRecord {
-  request: HttpRequest;
-  response?: HttpResponse;
-  durationMs: number;
-  error?: string;
-}
-
-let _auditRecorder: ((rec: AuditRecord) => void) | null = null;
-
-export function setHttpAuditRecorder(recorder: ((rec: AuditRecord) => void) | null): void {
-  if (recorder && _auditRecorder) {
-    process.stderr.write("zond: nested HTTP audit recorder — overriding the outer scope.\n");
-  }
-  _auditRecorder = recorder;
-}
-
-export interface FetchOptions {
-  timeout: number;
-  retries: number;
-  retry_delay: number;
-  follow_redirects: boolean;
-  rate_limiter?: RateLimiter;
-  rate_limit_retries: number;
-  rate_limit_max_delay_ms: number;
-  /** TASK-144: number of network-level retries (ECONNRESET, EPIPE, socket hang
-   *  up, fetch failed without HTTP response, timeout without response). HTTP
-   *  status codes are NEVER retried by this path. Exponential backoff with
-   *  jitter, base = `network_retry_base_ms`. Default 0 (CLI sets it to 1). */
-  network_retries: number;
-  network_retry_base_ms: number;
-  network_retry_max_delay_ms: number;
-}
-
-const DEFAULT_FETCH_OPTIONS: FetchOptions = {
-  timeout: 30000,
-  retries: 0,
-  retry_delay: 1000,
-  follow_redirects: true,
-  rate_limit_retries: 5,
-  rate_limit_max_delay_ms: 30000,
-  network_retries: 0,
-  network_retry_base_ms: 250,
-  network_retry_max_delay_ms: 8000,
-};
-
-/**
- * Recognise transient TCP/transport-level errors that warrant a retry. We
- * deliberately do NOT include HTTP status codes — a 5xx is a real response
- * the server chose to send, not a flaky socket. Patterns cover Node/Bun
- * error codes (`ECONNRESET`, `EPIPE`, `ECONNREFUSED`, `ETIMEDOUT`,
- * `EAI_AGAIN`), the WHATWG `fetch failed` wrapper Bun throws, classic
- * `socket hang up`, and `AbortError` raised by our own timeout watchdog.
- */
-export function isTransientNetworkError(err: unknown): boolean {
-  if (!err) return false;
-  const e = err as { code?: string; cause?: unknown; name?: string; message?: string };
-  const code = e.code ?? (e.cause as { code?: string } | undefined)?.code;
-  if (code) {
-    if (
-      code === "ECONNRESET" ||
-      code === "EPIPE" ||
-      code === "ECONNREFUSED" ||
-      code === "ETIMEDOUT" ||
-      code === "EAI_AGAIN" ||
-      code === "ENOTFOUND" ||
-      code === "ENETUNREACH"
-    ) {
-      return true;
-    }
-  }
-  const msg = (e.message ?? String(err)).toLowerCase();
-  if (e.name === "AbortError" || msg.includes("aborted")) return true;
-  if (msg.includes("socket hang up")) return true;
-  if (msg.includes("fetch failed")) return true;
-  if (msg.includes("connection reset") || msg.includes("econnreset")) return true;
-  if (msg.includes("epipe")) return true;
-  if (msg.includes("network error")) return true;
-  return false;
-}
-
-/** Exponential backoff with full jitter (AWS-style): pick uniformly in
- *  [0, min(cap, base * 2^attempt)). Returns ms. */
-export function networkBackoffMs(attempt: number, baseMs: number, capMs: number): number {
-  const exp = Math.min(capMs, baseMs * 2 ** attempt);
-  return Math.floor(Math.random() * exp);
-}
-
-export async function executeRequest(
-  request: HttpRequest,
-  options?: Partial<FetchOptions>,
-): Promise<HttpResponse> {
-  const opts = { ...DEFAULT_FETCH_OPTIONS, ...options };
-  let lastError: Error | undefined;
-  let networkAttempt = 0;
-  let networkRetryCount = 0;
-  let rate429Attempt = 0;
-
-  while (true) {
-    if (opts.rate_limiter) {
-      await opts.rate_limiter.acquire();
-    }
-
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), opts.timeout);
-      const start = performance.now();
-
-      const response = await fetch(request.url, {
-        method: request.method,
-        headers: request.headers,
-        body: request.formData ?? request.body ?? undefined,
-        signal: controller.signal,
-        redirect: opts.follow_redirects ? "follow" : "manual",
-        tls: { rejectUnauthorized: false },
-      });
-
-      clearTimeout(timeoutId);
-      const duration_ms = Math.round(performance.now() - start);
-
-      if (response.status === 429 && rate429Attempt < opts.rate_limit_retries) {
-        const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
-        const backoffMs = Math.min(
-          opts.retry_delay * 2 ** rate429Attempt,
-          opts.rate_limit_max_delay_ms,
-        );
-        const waitMs = Math.min(retryAfterMs ?? backoffMs, opts.rate_limit_max_delay_ms);
-        rate429Attempt++;
-        // Drain body so the connection can be reused
-        await response.text().catch(() => undefined);
-        await Bun.sleep(waitMs);
-        continue;
-      }
-
-      const bodyText = await response.text();
-      let body_parsed: unknown = undefined;
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        try {
-          body_parsed = JSON.parse(bodyText);
-        } catch {
-          // Body is not valid JSON despite content-type
-        }
-      }
-      // Fallback: for non-JSON responses, store trimmed body as string
-      // so that captures like `_body` work for text/plain, text/html, etc.
-      if (body_parsed === undefined && bodyText.length > 0) {
-        // Try JSON parse as fallback (some APIs omit content-type)
-        try {
-          body_parsed = JSON.parse(bodyText);
-        } catch {
-          body_parsed = bodyText.trim();
-        }
-      }
-
-      const headers: Record<string, string> = {};
-      response.headers.forEach((v, k) => {
-        headers[k] = v;
-      });
-
-      // Feed ratelimit-* headers back into the limiter so it can pause the
-      // stream proactively when the window is nearly exhausted (TASK-81).
-      if (opts.rate_limiter?.note) {
-        const meta = parseRateLimitHeaders(headers);
-        if (meta.remaining !== undefined || meta.reset !== undefined) {
-          opts.rate_limiter.note(meta);
-        }
-      }
-
-      const httpResp: HttpResponse = {
-        status: response.status,
-        headers,
-        body: bodyText,
-        body_parsed,
-        duration_ms,
-        network_retry_count: networkRetryCount,
-      };
-      if (_auditRecorder) {
-        try { _auditRecorder({ request, response: httpResp, durationMs: duration_ms }); }
-        catch { /* recorder is fire-and-forget */ }
-      }
-      return httpResp;
-    } catch (err) {
-      lastError = err instanceof Error ? err : new Error(String(err));
-      const isNet = isTransientNetworkError(lastError);
-      // TASK-144 path: dedicated network-retry budget with exp+jitter backoff.
-      if (isNet && networkRetryCount < opts.network_retries) {
-        const wait = networkBackoffMs(
-          networkRetryCount,
-          opts.network_retry_base_ms,
-          opts.network_retry_max_delay_ms,
-        );
-        networkRetryCount++;
-        await Bun.sleep(wait);
-        continue;
-      }
-      // Legacy linear path (yaml suite.config.retries).
-      if (networkAttempt < opts.retries) {
-        networkAttempt++;
-        await Bun.sleep(opts.retry_delay);
-        continue;
-      }
-      if (_auditRecorder) {
-        try { _auditRecorder({ request, durationMs: 0, error: lastError.message }); }
-        catch { /* recorder is fire-and-forget */ }
-      }
-      throw lastError;
-    }
-  }
-}

package/src/core/runner/learn-drift.ts

@@ -1,293 +0,0 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
-import type { TestRunResult, AssertionResult, StepResult } from "./types.ts";
-
-export interface DriftCase {
-  suite_name: string;
-  suite_file?: string;
-  step_name: string;
-  method?: string;
-  path?: string;
-  expected: number;
-  observed: number;
-  schema_validated: boolean;
-}
-
-/**
- * Detect status-code drift cases: step would have passed if `expect.status`
- * matched the observed status, every body/header assertion is green, and the
- * response body matches the OpenAPI schema (no `kind: schema` failures).
- *
- * Skipped on purpose:
- *  - `error` steps (network/transport — not a drift signal)
- *  - `expect.status` arrays (`one of [...]`) — drift only triggers on a single
- *    expected value; arrays already encode tolerance
- *  - steps without `kind: schema` evidence — treated as drift_without_schema
- *    and surfaced separately to the caller via `schema_validated: false`
- */
-export interface DetectOptions {
-  /** True when the run was launched with a schema validator attached. The
-   *  validator produces no assertions on success, so step.assertions alone
-   *  can't distinguish "schema ok" from "no validator". */
-  schemaValidatorAttached: boolean;
-}
-
-export function detectStatusDrifts(results: TestRunResult[], opts: DetectOptions = { schemaValidatorAttached: false }): DriftCase[] {
-  const cases: DriftCase[] = [];
-  for (const r of results) {
-    for (const step of r.steps) {
-      const drift = classifyStep(step, opts);
-      if (!drift) continue;
-      cases.push({
-        suite_name: r.suite_name,
-        suite_file: r.suite_file,
-        step_name: step.name,
-        method: step.request?.method,
-        path: extractPathFromUrl(step.request?.url),
-        expected: drift.expected,
-        observed: drift.observed,
-        schema_validated: drift.schemaValidated,
-      });
-    }
-  }
-  return cases;
-}
-
-interface StepDrift {
-  expected: number;
-  observed: number;
-  schemaValidated: boolean;
-}
-
-function classifyStep(step: StepResult, opts: DetectOptions): StepDrift | null {
-  if (step.status !== "fail") return null;
-  if (!step.response) return null;
-
-  const statusFails = step.assertions.filter(
-    a => a.field === "status" && !a.passed && typeof a.rule === "string" && a.rule.startsWith("equals "),
-  );
-  if (statusFails.length !== 1) return null;
-
-  const otherFails = step.assertions.filter(a => !a.passed && a !== statusFails[0]);
-  if (otherFails.length > 0) return null;
-
-  const expected = parseExpected(statusFails[0]!);
-  if (expected === null) return null;
-
-  const observed = step.response.status;
-  if (expected === observed) return null;
-
-  // Schema validation evidence — when the validator was attached, assertions
-  // contain `kind: "schema"` entries on failure and nothing on success. So
-  // "validator attached AND no failing schema assertion" is the success case.
-  const schemaFails = step.assertions.filter(a => a.kind === "schema" && !a.passed);
-  if (schemaFails.length > 0) return null; // body diverges from spec — not a drift
-  const schemaValidated = opts.schemaValidatorAttached;
-
-  return { expected, observed, schemaValidated };
-}
-
-function parseExpected(a: AssertionResult): number | null {
-  if (typeof a.expected === "number") return a.expected;
-  if (typeof a.expected === "string") {
-    const n = Number(a.expected);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
-}
-
-function extractPathFromUrl(url: string | undefined): string | undefined {
-  if (!url) return undefined;
-  try {
-    return new URL(url).pathname;
-  } catch {
-    return url;
-  }
-}
-
-export function formatDriftPlan(cases: DriftCase[]): string {
-  if (cases.length === 0) return "No status-code drift detected.\n";
-  const lines: string[] = [];
-  lines.push(`Drift detected (${cases.length} case${cases.length === 1 ? "" : "s"}):`);
-  for (const c of cases) {
-    const ep = `${c.method ?? "?"} ${c.path ?? "?"}`.padEnd(40);
-    const schema = c.schema_validated ? "body-schema=ok" : "body-schema=unverified";
-    lines.push(`  ${ep} spec=${c.expected}  observed=${c.observed}  ${schema}  → suggest: update test, or add to drifts`);
-  }
-  lines.push("");
-  lines.push("Run with --learn-apply --learn-target=test     to rewrite expect.status in YAML");
-  lines.push("Run with --learn-apply --learn-target=drifts   to record in apis/<name>/tolerated-drifts.yaml");
-  return lines.join("\n") + "\n";
-}
-
-export interface ApplyResult {
-  updated: number;
-  errors: { suite_file: string; step_name: string; reason: string }[];
-}
-
-/**
- * Rewrite `expect.status: <expected>` → `<observed>` in each suite file.
- *
- * Implementation is line-based: locate the step block by `name:`, then scan
- * forward until the next sibling step or dedent looking for the first
- * `status:` line at a deeper indent. We don't reparse the YAML — preserves
- * comments, key order, and trailing whitespace so the diff is minimal.
- */
-export async function applyDriftsToTests(cases: DriftCase[]): Promise<ApplyResult> {
-  const result: ApplyResult = { updated: 0, errors: [] };
-
-  // Group by file — read once, write once per file.
-  const byFile = new Map<string, DriftCase[]>();
-  for (const c of cases) {
-    if (!c.suite_file) {
-      result.errors.push({ suite_file: "<unknown>", step_name: c.step_name, reason: "suite_file missing" });
-      continue;
-    }
-    const list = byFile.get(c.suite_file) ?? [];
-    list.push(c);
-    byFile.set(c.suite_file, list);
-  }
-
-  for (const [file, fileCases] of byFile) {
-    let content: string;
-    try {
-      content = await readFile(file, "utf-8");
-    } catch (err) {
-      for (const c of fileCases) {
-        result.errors.push({ suite_file: file, step_name: c.step_name, reason: `read failed: ${(err as Error).message}` });
-      }
-      continue;
-    }
-
-    let lines = content.split("\n");
-    let touched = false;
-    for (const c of fileCases) {
-      const edited = rewriteExpectStatus(lines, c.step_name, c.expected, c.observed);
-      if (edited.ok) {
-        lines = edited.lines;
-        touched = true;
-        result.updated++;
-      } else {
-        result.errors.push({ suite_file: file, step_name: c.step_name, reason: edited.reason });
-      }
-    }
-
-    if (touched) {
-      try {
-        await writeFile(file, lines.join("\n"), "utf-8");
-      } catch (err) {
-        for (const c of fileCases) {
-          result.errors.push({ suite_file: file, step_name: c.step_name, reason: `write failed: ${(err as Error).message}` });
-        }
-      }
-    }
-  }
-
-  return result;
-}
-
-function rewriteExpectStatus(
-  lines: string[],
-  stepName: string,
-  expected: number,
-  observed: number,
-): { ok: true; lines: string[] } | { ok: false; reason: string } {
-  // Match `- name: foo` or `- name: "foo"` — capture indent of the dash so we
-  // know where the step block ends.
-  const nameRe = new RegExp(`^(\\s*)-\\s+name:\\s+["']?${escapeRegExp(stepName)}["']?\\s*$`);
-  let stepStart = -1;
-  let stepIndent = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i]!.match(nameRe);
-    if (m) {
-      stepStart = i;
-      stepIndent = m[1]!.length;
-      break;
-    }
-  }
-  if (stepStart < 0) return { ok: false, reason: `step "${stepName}" not found in YAML` };
-
-  // Step block ends at next sibling (`- name:` at the same indent) or at the
-  // first line that dedents past the step's column.
-  let stepEnd = lines.length;
-  for (let i = stepStart + 1; i < lines.length; i++) {
-    const line = lines[i]!;
-    if (line.trim() === "") continue;
-    const indent = line.match(/^(\s*)/)![1]!.length;
-    if (indent <= stepIndent) {
-      stepEnd = i;
-      break;
-    }
-  }
-
-  const statusRe = new RegExp(`^(\\s*)status:\\s*${expected}\\s*(#.*)?$`);
-  for (let i = stepStart + 1; i < stepEnd; i++) {
-    const m = lines[i]!.match(statusRe);
-    if (m) {
-      const tail = m[2] ? ` ${m[2]}` : "";
-      lines[i] = `${m[1]}status: ${observed}${tail}`;
-      return { ok: true, lines };
-    }
-  }
-  return { ok: false, reason: `expect.status: ${expected} not found within step "${stepName}"` };
-}
-
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Append drift cases to `<apiDir>/tolerated-drifts.yaml`. The file is a flat
- * `drifts:` list; we de-duplicate on (method, path, expected, observed).
- *
- * Format kept intentionally minimal — runner-side enforcement (skip the
- * status assertion when a tolerated drift matches) is a follow-up task; this
- * call just records the data so a human can review.
- */
-export async function appendToleratedDrifts(apiDir: string, cases: DriftCase[]): Promise<{ written: number; file: string }> {
-  const file = `${apiDir}/tolerated-drifts.yaml`;
-  let existing = "";
-  try {
-    existing = await readFile(file, "utf-8");
-  } catch {
-    // new file — keep empty
-  }
-
-  const seen = new Set<string>();
-  const driftRe = /^\s*-\s*method:\s*(\w+)\s*$\n\s*path:\s*(\S+)\s*$\n\s*expected:\s*(\d+)\s*$\n\s*observed:\s*(\d+)/gm;
-  let m: RegExpExecArray | null;
-  while ((m = driftRe.exec(existing)) !== null) {
-    seen.add(`${m[1]!.toUpperCase()} ${m[2]} ${m[3]}->${m[4]}`);
-  }
-
-  const fresh: DriftCase[] = [];
-  for (const c of cases) {
-    const key = `${(c.method ?? "?").toUpperCase()} ${c.path ?? "?"} ${c.expected}->${c.observed}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    fresh.push(c);
-  }
-
-  if (fresh.length === 0) return { written: 0, file };
-
-  let body = existing;
-  if (!/^drifts:\s*$/m.test(body)) {
-    body = body.trim();
-    if (body.length > 0) body += "\n";
-    body += "drifts:\n";
-  } else if (!body.endsWith("\n")) {
-    body += "\n";
-  }
-
-  for (const c of fresh) {
-    body += `  - method: ${c.method ?? "?"}\n`;
-    body += `    path: ${c.path ?? "?"}\n`;
-    body += `    expected: ${c.expected}\n`;
-    body += `    observed: ${c.observed}\n`;
-    body += `    note: ""\n`;
-  }
-
-  await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, body, "utf-8");
-  return { written: fresh.length, file };
-}