@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/runner/preflight-vars.ts

@@ -1,153 +0,0 @@
-import type { TestSuite, TestStep, AssertionRule } from "../parser/types.ts";
-import { GENERATORS } from "../parser/variables.ts";
-
-const VAR_PATTERN = /\{\{([^{}]+)\}\}/g;
-
-function scanRefs(value: unknown, out: Set<string>): void {
-  if (typeof value === "string") {
-    for (const match of value.matchAll(VAR_PATTERN)) {
-      const key = match[1]!.trim();
-      if (!key.startsWith("$")) out.add(key);
-    }
-  } else if (Array.isArray(value)) {
-    for (const item of value) scanRefs(item, out);
-  } else if (typeof value === "object" && value !== null) {
-    for (const v of Object.values(value)) scanRefs(v, out);
-  }
-}
-
-export function collectCapturesAndSets(step: TestStep, out: Set<string>): void {
-  if (step.set) {
-    for (const k of Object.keys(step.set)) out.add(k);
-  }
-  if (step.for_each?.var) out.add(step.for_each.var);
-  const scanRule = (rule: AssertionRule | undefined): void => {
-    if (!rule) return;
-    if (rule.capture) out.add(rule.capture);
-    if (rule.each) {
-      for (const r of Object.values(rule.each)) scanRule(r);
-    }
-    if (rule.contains_item) {
-      for (const r of Object.values(rule.contains_item)) scanRule(r);
-    }
-  };
-  if (step.expect?.body) {
-    for (const r of Object.values(step.expect.body)) scanRule(r);
-  }
-  if (step.expect?.headers) {
-    for (const v of Object.values(step.expect.headers)) {
-      if (typeof v === "object" && v !== null) scanRule(v as AssertionRule);
-    }
-  }
-}
-
-export interface MissingVarHit {
-  suite: string;
-  file?: string;
-  step?: string;
-  variable: string;
-}
-
-/**
- * Pre-flight scan: find {{var}} references in suites that have no producer
- * (env value, suite-level parameterize/set, prior-step capture). Excludes
- * built-in $generators.
- *
- * Conservative: per-suite — accumulates all captures/sets across steps, so
- * forward references inside the suite are tolerated (correctness requires
- * runtime ordering checks anyway).
- */
-/** All non-generator {{var}} references a step reads (path, headers, body,
- *  query, skip_if, retry_until, set, for_each). Excludes `$generators`. */
-export function collectStepRefs(step: TestStep): Set<string> {
-  const refs = new Set<string>();
-  scanRefs(step.path, refs);
-  scanRefs(step.headers, refs);
-  scanRefs(step.json, refs);
-  scanRefs(step.form, refs);
-  scanRefs(step.multipart, refs);
-  scanRefs(step.query, refs);
-  if (step.skip_if) scanRefs(step.skip_if, refs);
-  if (step.retry_until) scanRefs(step.retry_until.condition, refs);
-  if (step.set) scanRefs(step.set, refs);
-  if (step.for_each) scanRefs(step.for_each.in, refs);
-  return refs;
-}
-
-export function preflightCheckVars(
-  suites: TestSuite[],
-  env: Record<string, string>,
-): MissingVarHit[] {
-  const hits: MissingVarHit[] = [];
-  const generatorKeys = new Set(Object.keys(GENERATORS));
-
-  for (const suite of suites) {
-    const known = new Set<string>(Object.keys(env));
-    if (suite.parameterize) {
-      for (const k of Object.keys(suite.parameterize)) known.add(k);
-    }
-    for (const step of suite.tests) collectCapturesAndSets(step, known);
-
-    const scanStepRefs = collectStepRefs;
-
-    const suiteRefs = new Set<string>();
-    if (suite.base_url) scanRefs(suite.base_url, suiteRefs);
-    if (suite.headers) scanRefs(suite.headers, suiteRefs);
-    for (const v of suiteRefs) {
-      if (!known.has(v) && !generatorKeys.has(v)) {
-        hits.push({ suite: suite.name, file: suite.filePath, variable: v });
-      }
-    }
-
-    for (const step of suite.tests) {
-      const refs = scanStepRefs(step);
-      for (const v of refs) {
-        if (!known.has(v) && !generatorKeys.has(v)) {
-          hits.push({
-            suite: suite.name,
-            file: suite.filePath,
-            step: step.name,
-            variable: v,
-          });
-        }
-      }
-    }
-  }
-
-  return hits;
-}
-
-export function formatMissingVarLine(hit: MissingVarHit): string {
-  const where = hit.step ? `${hit.suite} → ${hit.step}` : hit.suite;
-  const file = hit.file ? ` (${hit.file})` : "";
-  return `Undefined variable {{${hit.variable}}} in ${where}${file}`;
-}
-
-/**
- * TASK-248: collapse per-(suite,step,variable) hits into one summary line per
- * unique variable. When the same {{var}} is referenced in 8–12 places (typical
- * when running outside a workspace and `.env.yaml` is missing), per-hit emit
- * spams stderr — the aggregated form keeps signal (the *names* of the missing
- * vars) while dropping noise.
- */
-export function summarizeMissingVars(hits: MissingVarHit[]): string[] {
-  if (hits.length === 0) return [];
-  const byVar = new Map<string, { refs: number; suites: Set<string> }>();
-  for (const h of hits) {
-    let entry = byVar.get(h.variable);
-    if (!entry) {
-      entry = { refs: 0, suites: new Set() };
-      byVar.set(h.variable, entry);
-    }
-    entry.refs++;
-    entry.suites.add(h.suite);
-  }
-  const names = [...byVar.keys()].sort();
-  const totalRefs = hits.length;
-  const totalSuites = new Set(hits.map((h) => h.suite)).size;
-  const head = names.slice(0, 6).map((n) => `{{${n}}}`).join(", ");
-  const tail = names.length > 6 ? `, … and ${names.length - 6} more` : "";
-  return [
-    `Undefined variables: ${head}${tail} (${totalRefs} reference${totalRefs === 1 ? "" : "s"} across ${totalSuites} suite${totalSuites === 1 ? "" : "s"})`,
-  ];
-}

package/src/core/runner/progress-tracker.ts

@@ -1,73 +0,0 @@
-/**
- * ARV-249: lightweight progress tracker for `zond run`. A separate module
- * so the formatter can be unit-tested without spinning up an executor.
- *
- * Architecture: run.ts owns the tracker + `setInterval`. Every completed
- * step calls `tracker.recordStep(...)` via `RunSuiteOptions.onStepDone`,
- * the interval ticks every PROGRESS_INTERVAL_MS and writes one stderr
- * line, and run.ts clears the interval before printing the final report.
- */
-import { formatEta } from "../util/format-eta.ts";
-import type { StepResult } from "./types.ts";
-
-export const PROGRESS_INTERVAL_MS = 5000;
-/** Wait this long before emitting the first progress line. Short runs
- *  that finish under the threshold stay silent. */
-export const PROGRESS_QUIET_MS = 5000;
-
-export interface ProgressSnapshot {
-  elapsedMs: number;
-  completedSteps: number;
-  totalSteps: number;
-  httpRequests: number;
-  effectiveRps: number;
-  etaSeconds: number;
-}
-
-export class ProgressTracker {
-  private completedSteps = 0;
-  private httpRequests = 0;
-  private readonly startedAt: number;
-
-  constructor(private readonly totalSteps: number, now: number = Date.now()) {
-    this.startedAt = now;
-  }
-
-  recordStep(step: StepResult): void {
-    this.completedSteps += 1;
-    if (step.status !== "skip" && step.response !== undefined) {
-      this.httpRequests += 1;
-    }
-  }
-
-  snapshot(now: number = Date.now()): ProgressSnapshot {
-    const elapsedMs = Math.max(0, now - this.startedAt);
-    const elapsedSec = elapsedMs / 1000;
-    const effectiveRps = elapsedSec > 0 ? this.httpRequests / elapsedSec : 0;
-    const remaining = Math.max(0, this.totalSteps - this.completedSteps);
-    const stepRate = elapsedSec > 0 ? this.completedSteps / elapsedSec : 0;
-    const etaSeconds = stepRate > 0 ? remaining / stepRate : Infinity;
-    return {
-      elapsedMs,
-      completedSteps: this.completedSteps,
-      totalSteps: this.totalSteps,
-      httpRequests: this.httpRequests,
-      effectiveRps,
-      etaSeconds,
-    };
-  }
-}
-
-/** Format a progress snapshot for stderr. Stable wording — agents may
- *  grep the line. */
-export function formatProgressLine(snap: ProgressSnapshot): string {
-  const elapsed = formatEta(snap.elapsedMs / 1000);
-  const pct = snap.totalSteps > 0
-    ? Math.min(100, Math.floor((snap.completedSteps / snap.totalSteps) * 100))
-    : 0;
-  const rps = snap.effectiveRps >= 10
-    ? Math.round(snap.effectiveRps).toString()
-    : snap.effectiveRps.toFixed(1);
-  const eta = Number.isFinite(snap.etaSeconds) ? formatEta(snap.etaSeconds) : "?";
-  return `zond: [${elapsed}] ${snap.completedSteps}/${snap.totalSteps} steps (${pct}%), ${snap.httpRequests} req, ~${rps} req/s, ETA ${eta}`;
-}

package/src/core/runner/rate-limiter.ts

@@ -1,185 +0,0 @@
-export interface RateLimiter {
-  acquire(): Promise<void>;
-  /**
-   * Feed rate-limit metadata from the latest response back into the limiter.
-   * Two effects: (1) when `remaining` falls at or below the threshold, the
-   * limiter postpones the next acquire until the API's reset window expires;
-   * (2) when the response carries a `RateLimit-Policy` (RFC 9568), the
-   * limiter learns the per-request spacing so subsequent parallel acquires
-   * are forced into single-file at burst=1.
-   *
-   * Optional so existing callers / mocks need not implement it.
-   */
-  note?(meta: RateLimitMeta, now?: number): void;
-}
-
-export interface RateLimitMeta {
-  /** Requests remaining in the current window. */
-  remaining?: number;
-  /** Either seconds-until-reset (RFC draft) or a Unix epoch in seconds (GitHub style). */
-  reset?: number;
-  /** Window cap; used for diagnostics and spacing fallback. */
-  limit?: number;
-  /**
-   * Minimum spacing between requests in ms — derived from `RateLimit-Policy:
-   * N;w=W` (RFC 9568). When set, the limiter raises its own interval to at
-   * least this value so a burst of parallel requests is paced one-by-one
-   * instead of overshooting the window.
-   */
-  intervalMs?: number;
-}
-
-/**
- * When `remaining` is at or below this number we proactively pause until reset.
- * Conservative threshold — at 2, we still have buffer for one in-flight retry
- * (if we paused at 5 we'd over-throttle on small windows like 5-req/1-sec
- * policies, where every request would trigger a sleep).
- */
-const THROTTLE_THRESHOLD = 2;
-
-/**
- * Padding added to policy-derived spacing to absorb clock drift between the
- * server's window and our local Date.now() (TASK-88). Without this, spacing
- * exactly at `W/N` ms can still hit the window boundary on the wrong side.
- */
-const POLICY_SAFETY_MS = 50;
-
-/** Magnitudes above this are treated as Unix timestamps; below as relative
- *  seconds. 10^9 seconds ≈ Sep 2001, so any real reset window is far below. */
-const UNIX_TS_BOUNDARY = 1_000_000_000;
-
-function applyResetPause(prevNextAvailable: number, meta: RateLimitMeta, now: number): number {
-  if (meta.remaining === undefined) return prevNextAvailable;
-  if (meta.remaining > THROTTLE_THRESHOLD) return prevNextAvailable;
-  if (meta.reset === undefined || !Number.isFinite(meta.reset)) return prevNextAvailable;
-  const resetMs = meta.reset > UNIX_TS_BOUNDARY ? meta.reset * 1000 : now + Math.max(0, meta.reset) * 1000;
-  return Math.max(prevNextAvailable, resetMs);
-}
-
-class IntervalRateLimiter implements RateLimiter {
-  private nextAvailable = 0;
-  /** 0 means adaptive: no proactive throttling until a policy is learned
-   *  from a response (matches the original AdaptiveRateLimiter behaviour). */
-  private intervalMs: number;
-
-  constructor(reqPerSec?: number) {
-    if (reqPerSec === undefined) {
-      this.intervalMs = 0;
-    } else {
-      if (!Number.isFinite(reqPerSec) || reqPerSec <= 0) {
-        throw new Error(`Invalid rate limit: ${reqPerSec}`);
-      }
-      this.intervalMs = 1000 / reqPerSec;
-    }
-  }
-
-  async acquire(): Promise<void> {
-    const now = Date.now();
-    const slot = Math.max(now, this.nextAvailable);
-    const waitMs = slot - now;
-    this.nextAvailable = slot + this.intervalMs;
-    if (waitMs > 0) {
-      await Bun.sleep(waitMs);
-    }
-  }
-
-  note(meta: RateLimitMeta, now: number = Date.now()): void {
-    if (meta.intervalMs !== undefined && meta.intervalMs > this.intervalMs) {
-      // Already-reserved slots were spaced at the OLD interval; push
-      // nextAvailable forward by the delta so the new spacing kicks in
-      // immediately rather than only on the next-next request.
-      this.nextAvailable += meta.intervalMs - this.intervalMs;
-      this.intervalMs = meta.intervalMs;
-    }
-    this.nextAvailable = applyResetPause(this.nextAvailable, meta, now);
-  }
-}
-
-export function createRateLimiter(reqPerSec: number | undefined): RateLimiter | undefined {
-  if (reqPerSec === undefined || reqPerSec === null) return undefined;
-  if (!Number.isFinite(reqPerSec) || reqPerSec <= 0) return undefined;
-  return new IntervalRateLimiter(reqPerSec);
-}
-
-/**
- * Adaptive limiter for `--rate-limit auto`. Issues no proactive throttling on
- * its own initially, but reacts to ratelimit-* response headers via `note()`:
- * (a) pauses the request stream until the API's reset window elapses when
- * remaining headroom drops; (b) once a `RateLimit-Policy` is seen, paces
- * subsequent requests at the policy's `W/N` spacing — this prevents bursts
- * from blowing through small windows (e.g. 5-req/1-sec policies).
- */
-export function createAdaptiveRateLimiter(): RateLimiter {
-  return new IntervalRateLimiter();
-}
-
-/**
- * Read RFC 9568 `ratelimit-*` headers (was draft-ietf-httpapi-ratelimit-headers)
- * plus the GitHub / Stripe style `x-ratelimit-*` aliases out of a response
- * header bag. All keys are matched case-insensitively. Unparseable values are
- * dropped.
- *
- * `RateLimit-Policy: N;w=W` is parsed into a per-request `intervalMs` of
- * `(W/N)*1000 + POLICY_SAFETY_MS` so the limiter can pace bursts.
- */
-export function parseRateLimitHeaders(headers: Record<string, string>): RateLimitMeta {
-  const lower: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
-  const num = (v: string | undefined): number | undefined => {
-    if (v === undefined) return undefined;
-    // RFC draft `ratelimit-remaining` may carry `q="value"` quoted-string form;
-    // strip leading numeric run.
-    const match = v.match(/-?\d+(?:\.\d+)?/);
-    if (!match) return undefined;
-    const n = Number.parseFloat(match[0]);
-    return Number.isFinite(n) ? n : undefined;
-  };
-  const policy = lower["ratelimit-policy"] ?? lower["x-ratelimit-policy"];
-  const intervalMs = derivePolicyIntervalMs(policy);
-  return {
-    limit: num(lower["ratelimit-limit"] ?? lower["x-ratelimit-limit"]),
-    remaining: num(lower["ratelimit-remaining"] ?? lower["x-ratelimit-remaining"]),
-    reset: num(lower["ratelimit-reset"] ?? lower["x-ratelimit-reset"]),
-    intervalMs,
-  };
-}
-
-/**
- * Parse `RateLimit-Policy: 5;w=1` (or comma-separated multi-policy — we honour
- * the *strictest* one). Returns the implied per-request interval in ms,
- * including a small safety margin. Returns undefined when the header is
- * malformed or missing.
- */
-function derivePolicyIntervalMs(policy: string | undefined): number | undefined {
-  if (!policy) return undefined;
-  let strictest: number | undefined;
-  for (const item of policy.split(",")) {
-    const parts = item.trim().split(";").map(s => s.trim()).filter(Boolean);
-    if (parts.length === 0) continue;
-    const limit = Number.parseFloat(parts[0]!);
-    if (!Number.isFinite(limit) || limit <= 0) continue;
-    const wPart = parts.find(p => p.startsWith("w="));
-    if (!wPart) continue;
-    const window = Number.parseFloat(wPart.slice(2));
-    if (!Number.isFinite(window) || window <= 0) continue;
-    const interval = (window / limit) * 1000 + POLICY_SAFETY_MS;
-    if (strictest === undefined || interval > strictest) strictest = interval;
-  }
-  return strictest;
-}
-
-export function parseRetryAfter(header: string | null | undefined, now: number = Date.now()): number | undefined {
-  if (!header) return undefined;
-  const trimmed = header.trim();
-  if (trimmed === "") return undefined;
-  if (/^\d+(\.\d+)?$/.test(trimmed)) {
-    const seconds = Number.parseFloat(trimmed);
-    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
-    return undefined;
-  }
-  const date = Date.parse(trimmed);
-  if (!Number.isNaN(date)) {
-    return Math.max(0, date - now);
-  }
-  return undefined;
-}

package/src/core/runner/run-kind.ts

@@ -1,45 +0,0 @@
-/**
- * ARV-55: single source of truth for classifying a run by *what kind of
- * suites it executed*. Before this module the answer was inferred from
- * `suite_file` paths in three places (coverage's `isProbeOnlyRun`,
- * `db diagnose` recommendation branching, and a handful of skill prompts).
- *
- * We resolve the kind once at INSERT-time and persist it in `runs.run_kind`;
- * downstream filters become a column compare instead of a per-result regex.
- *
- * Encoding:
- *   - `probe`   — every suite path lives under `apis/<api>/probes/` (or a
- *                 bare `probes/` segment for ad-hoc setups). Coverage hides
- *                 these by default — probe runs deliberately exercise a
- *                 subset of endpoints and would otherwise read as a
- *                 regression vs the prior smoke/CRUD run.
- *   - `check`   — every suite path lives under `apis/<api>/checks/`. Mirrors
- *                 the same logic: conformance checks don't reflect endpoint
- *                 coverage breadth.
- *   - `request` — a single ad-hoc `zond request` invocation persisted into
- *                 the session DB (ARV-265). Excluded from `pass-coverage`
- *                 but counted toward `audit-coverage`.
- *   - `fixture` — `prepare-fixtures --cascade` discovery list-calls
- *                 (ARV-265). Pure HTTP touches in service of fixture
- *                 derivation; audit-coverage only.
- *   - `regular` — anything else, including mixed runs (probe + smoke). A
- *                 mixed run is treated as regular because at least one
- *                 suite contributed real coverage signal.
- */
-
-export type RunKind = "regular" | "probe" | "check" | "request" | "fixture";
-
-const PROBE_SEGMENT_RE = /(^|\/)probes(\/|$)/;
-const CHECK_SEGMENT_RE = /(^|\/)checks(\/|$)/;
-
-export function detectRunKind(suiteFiles: ReadonlyArray<string | null | undefined>): RunKind {
-  // Empty / all-empty arrays default to 'regular' — the DB CHECK constraint
-  // refuses NULL so callers always receive a concrete kind.
-  const paths = suiteFiles
-    .filter((p): p is string => typeof p === "string" && p.length > 0);
-  if (paths.length === 0) return "regular";
-
-  if (paths.every((p) => PROBE_SEGMENT_RE.test(p))) return "probe";
-  if (paths.every((p) => CHECK_SEGMENT_RE.test(p))) return "check";
-  return "regular";
-}