@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/reporter/ndjson.ts

@@ -0,0 +1,37 @@
+/**
+ * ARV-10 (m-15): NDJSON streaming reporter for `zond checks run`.
+ *
+ * Each event is a single JSON line on stdout — agents pipe the stream
+ * into `jq` / ajv / their own consumer and act on findings *as they
+ * happen* instead of waiting for the run to wrap up. The discriminated
+ * union of event shapes lives in `src/cli/json-schemas.ts` (zod source
+ * of truth) and ships as `docs/json-schema/ndjson-events.schema.json`.
+ *
+ * The CLI passes `emitToStdout` as the `onEvent` callback to runChecks;
+ * tests can pass an in-memory accumulator instead.
+ */
+import type { z } from "zod";
+import type {
+  NdjsonCheckStartEventSchema,
+  NdjsonCheckResultEventSchema,
+  NdjsonFindingEventSchema,
+  NdjsonSummaryEventSchema,
+  NdjsonEventSchema,
+} from "../../cli/json-schemas.ts";
+
+export type NdjsonCheckStartEvent = z.infer<typeof NdjsonCheckStartEventSchema>;
+export type NdjsonCheckResultEvent = z.infer<typeof NdjsonCheckResultEventSchema>;
+export type NdjsonFindingEvent = z.infer<typeof NdjsonFindingEventSchema>;
+export type NdjsonSummaryEvent = z.infer<typeof NdjsonSummaryEventSchema>;
+export type NdjsonEvent = z.infer<typeof NdjsonEventSchema>;
+
+/** Write one event to stdout as a single line. AC #5 — when the CLI is
+ *  in `--ndjson` mode, *every* user-readable message goes to stderr, so
+ *  stdout stays a clean NDJSON stream that pipes into `jq` / ajv. */
+export function emitToStdout(ev: NdjsonEvent): void {
+  process.stdout.write(`${JSON.stringify(ev)}\n`);
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}

package/src/core/reporter/types.ts

@@ -3,6 +3,9 @@ import type { TestRunResult } from "../runner/types.ts";
 export interface ReporterOptions {
   /** Whether to use ANSI colors. Default: auto-detect via isTTY. */
   color?: boolean;
+  /** TASK-265: suppress per-suite/per-test detail and emit only the
+   *  grand-total summary line. Exit code still carries pass/fail. */
+  quiet?: boolean;
 }
 
 export type ReporterName = "console" | "json" | "junit";

package/src/core/runner/assertions.ts

@@ -233,6 +233,7 @@ export function checkAssertions(expect: TestStepExpect, response: HttpResponse):
       passed: allowed.includes(response.status),
       actual: response.status,
       expected: expect.status,
+      kind: "primary",
     });
   }
 
@@ -243,6 +244,7 @@ export function checkAssertions(expect: TestStepExpect, response: HttpResponse):
       passed: response.duration_ms <= expect.duration,
       actual: response.duration_ms,
       expected: expect.duration,
+      kind: "auxiliary",
     });
   }
 
@@ -256,12 +258,14 @@ export function checkAssertions(expect: TestStepExpect, response: HttpResponse):
           passed: actual === rule,
           actual,
           expected: rule,
+          kind: "auxiliary",
         });
       } else {
         // AssertionRule in header — supports capture and other checks
         const ruleResults = checkRule(key, rule, actual).map(r => ({
           ...r,
           field: r.field.replace(/^body\./, "headers."),
+          kind: "auxiliary" as const,
         }));
         results.push(...ruleResults);
       }
@@ -278,7 +282,11 @@ export function checkAssertions(expect: TestStepExpect, response: HttpResponse):
       } else {
         actual = getByPath(response.body_parsed, path);
       }
-      results.push(...checkRule(path, rule, actual));
+      const bodyResults = checkRule(path, rule, actual).map((r) => ({
+        ...r,
+        kind: "primary" as const,
+      }));
+      results.push(...bodyResults);
     }
   }
 
@@ -324,3 +332,52 @@ export function extractCaptures(
 
   return captures;
 }
+
+/**
+ * Find capture rules whose path didn't resolve in the response, returning
+ * `{ var, source, path }` per miss. Surfaced as auxiliary assertion failures
+ * so the user sees "captures: {}" with a reason instead of silent emptiness —
+ * the empty-captures pitfall is the #1 footgun in CRUD chains because the
+ * downstream step is silently skipped or runs with `undefined`. TASK-256.
+ */
+export function findMissedCaptures(
+  bodyRules: Record<string, AssertionRule> | undefined,
+  responseBody: unknown,
+  headerRules?: Record<string, string | AssertionRule>,
+  responseHeaders?: Record<string, string>,
+): Array<{ var: string; source: "body" | "header"; path: string }> {
+  const misses: Array<{ var: string; source: "body" | "header"; path: string }> = [];
+
+  if (bodyRules) {
+    for (const [path, rule] of Object.entries(bodyRules)) {
+      if (!rule.capture) continue;
+      if (responseBody === undefined) {
+        misses.push({ var: rule.capture, source: "body", path });
+        continue;
+      }
+      let value: unknown;
+      if (path === "_body") {
+        value = responseBody;
+      } else if (path.startsWith("_body.")) {
+        value = getByPath(responseBody, path.slice(6));
+      } else {
+        value = getByPath(responseBody, path);
+      }
+      if (value === undefined) {
+        misses.push({ var: rule.capture, source: "body", path });
+      }
+    }
+  }
+
+  if (headerRules) {
+    for (const [key, rule] of Object.entries(headerRules)) {
+      if (typeof rule === "string" || !rule.capture) continue;
+      const value = responseHeaders ? responseHeaders[key.toLowerCase()] : undefined;
+      if (value === undefined) {
+        misses.push({ var: rule.capture, source: "header", path: key });
+      }
+    }
+  }
+
+  return misses;
+}

package/src/core/runner/async-pool.ts

@@ -0,0 +1,108 @@
+/**
+ * ARV-8 (m-15): bounded async-pool for `zond checks run --workers N`.
+ *
+ * Cooperative concurrency on a single Bun event loop — no threading,
+ * no Workers, just N coroutines that pull from a shared cursor. The
+ * design choice is deliberate:
+ *
+ *   * Threads/Workers would need request-context plumbing (auth headers,
+ *     rate-limiter state, per-run schema validators are not transferable
+ *     without serialization), and Bun's HTTP client is already
+ *     non-blocking — so cooperative concurrency is faster *and* simpler.
+ *   * `Promise.all(items.map(fn))` would saturate at items.length, which
+ *     defeats the rate-limiter and tends to drown small mock servers.
+ *
+ * `runPool` preserves input order in the result array — callers (the
+ * checks runner, mainly) want to merge per-op findings deterministically
+ * regardless of which worker finished first.
+ */
+import os from "node:os";
+
+const WORKERS_MIN = 1;
+const WORKERS_MAX = 64;
+/** `--workers auto` ceiling — beyond ~8 the gains on a typical mock
+ *  server are dominated by network/IO contention, not parallelism. */
+const WORKERS_AUTO_CEILING = 8;
+
+/**
+ * Run `fn` over `items` with at most `workers` in-flight at once.
+ *
+ * Results are returned in input order, *not* completion order — keep
+ * call-sites that compose findings/snapshots deterministic.
+ *
+ * Errors propagate: the first rejection cancels remaining workers'
+ * dispatch (they finish their in-flight task and exit). Caller should
+ * `try/catch` if it wants partial results — none of zond's callers do
+ * today (a runner crash is fatal anyway).
+ */
+export async function runPool<T, R>(
+  items: readonly T[],
+  workers: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) return [];
+  // Effective worker count is clamped both ways: never more than items
+  // (idle workers waste a closure), never below 1 (else nothing runs).
+  const effective = Math.max(1, Math.min(workers, items.length));
+  // Sequential fast-path — preserves the *exact* old behaviour
+  // (microtask ordering, error timing) for AC #4 backward-compat.
+  if (effective === 1) {
+    const out: R[] = new Array(items.length);
+    for (let i = 0; i < items.length; i++) {
+      out[i] = await fn(items[i]!, i);
+    }
+    return out;
+  }
+  const out: R[] = new Array(items.length);
+  let cursor = 0;
+  let aborted: unknown = null;
+  async function worker(): Promise<void> {
+    while (true) {
+      if (aborted !== null) return;
+      const i = cursor++;
+      if (i >= items.length) return;
+      try {
+        out[i] = await fn(items[i]!, i);
+      } catch (err) {
+        // First rejection wins — store it, drain in-flight tasks, then
+        // re-throw at the join point.
+        if (aborted === null) aborted = err;
+        return;
+      }
+    }
+  }
+  const swarm: Promise<void>[] = [];
+  for (let w = 0; w < effective; w++) swarm.push(worker());
+  await Promise.all(swarm);
+  if (aborted !== null) throw aborted;
+  return out;
+}
+
+/**
+ * Parse a `--workers` flag value:
+ *
+ *   undefined      → 1 (backward-compat default — AC #4)
+ *   "auto" / "AUTO"→ min(cpus, WORKERS_AUTO_CEILING) (AC #5)
+ *   numeric        → clamp [1, 64] (AC #5)
+ *   anything else  → throws (caller maps to a friendly CLI error)
+ */
+export function parseWorkers(value: string | number | undefined): number {
+  if (value === undefined || value === null || value === "") return 1;
+  if (typeof value === "string") {
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed === "auto") {
+      return Math.max(WORKERS_MIN, Math.min(os.cpus().length, WORKERS_AUTO_CEILING));
+    }
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(n)) throw new Error(`Invalid --workers value: "${value}"`);
+    return Math.max(WORKERS_MIN, Math.min(n, WORKERS_MAX));
+  }
+  if (!Number.isFinite(value)) throw new Error(`Invalid --workers value: ${value}`);
+  return Math.max(WORKERS_MIN, Math.min(Math.trunc(value), WORKERS_MAX));
+}
+
+export const WORKERS_LIMITS = {
+  min: WORKERS_MIN,
+  max: WORKERS_MAX,
+  autoCeiling: WORKERS_AUTO_CEILING,
+} as const;

package/src/core/runner/auth-path.ts

@@ -0,0 +1,8 @@
+/**
+ * Heuristic for "auth-shaped" endpoint paths used by `--safe` mode and
+ * the env-symptom diagnostics in `db-analysis.ts`. Anything matching is
+ * treated as a login/refresh route — `--safe` whitelists it for live
+ * runs, and the diagnostics flag concentrated POST failures here as
+ * `auth_required` rather than per-endpoint bugs.
+ */
+export const AUTH_PATH_RE = /\/(auth|login|signin|token|oauth)\b/i;

package/src/core/runner/ci-context.ts

@@ -0,0 +1,72 @@
+/**
+ * TASK-116: detect CI context (commit sha, branch, trigger) from common
+ * environment variables. Returns `null` for fields when nothing is present
+ * — caller decides whether to default `trigger` to `"manual"`.
+ *
+ * Supported providers (autodetected — no opt-in required):
+ *   GitHub Actions  GITHUB_ACTIONS=true, GITHUB_SHA, GITHUB_REF_NAME
+ *   GitLab CI       GITLAB_CI=true, CI_COMMIT_SHA, CI_COMMIT_REF_NAME
+ *   CircleCI        CIRCLECI=true, CIRCLE_SHA1, CIRCLE_BRANCH
+ *   Buildkite       BUILDKITE=true, BUILDKITE_COMMIT, BUILDKITE_BRANCH
+ *   Jenkins         JENKINS_URL set, GIT_COMMIT, BRANCH_NAME / GIT_BRANCH
+ *   Generic         CI=true triggers `trigger=ci` even when no provider
+ *                   matches — caller can still pass nullable commit/branch.
+ *
+ * Manual override is via the explicit `--commit-sha` / `--branch` /
+ * `--trigger` flags or the env vars `ZOND_COMMIT_SHA` / `ZOND_BRANCH` /
+ * `ZOND_TRIGGER`. These win over autodetection.
+ */
+export interface CiContext {
+  trigger: "ci" | "manual";
+  commit_sha: string | null;
+  branch: string | null;
+  /** Provider tag (github-actions / gitlab-ci / circleci / …) for diagnostics. */
+  provider: string | null;
+}
+
+export function detectCiContext(env: NodeJS.ProcessEnv = process.env): CiContext {
+  const overrideCommit = env.ZOND_COMMIT_SHA?.trim() || null;
+  const overrideBranch = env.ZOND_BRANCH?.trim() || null;
+  const overrideTrigger = env.ZOND_TRIGGER?.trim() || null;
+
+  let provider: string | null = null;
+  let commit: string | null = null;
+  let branch: string | null = null;
+
+  if (env.GITHUB_ACTIONS === "true") {
+    provider = "github-actions";
+    commit = env.GITHUB_SHA?.trim() || null;
+    branch = env.GITHUB_REF_NAME?.trim() || env.GITHUB_HEAD_REF?.trim() || null;
+  } else if (env.GITLAB_CI === "true") {
+    provider = "gitlab-ci";
+    commit = env.CI_COMMIT_SHA?.trim() || null;
+    branch = env.CI_COMMIT_REF_NAME?.trim() || null;
+  } else if (env.CIRCLECI === "true") {
+    provider = "circleci";
+    commit = env.CIRCLE_SHA1?.trim() || null;
+    branch = env.CIRCLE_BRANCH?.trim() || null;
+  } else if (env.BUILDKITE === "true") {
+    provider = "buildkite";
+    commit = env.BUILDKITE_COMMIT?.trim() || null;
+    branch = env.BUILDKITE_BRANCH?.trim() || null;
+  } else if (env.JENKINS_URL) {
+    provider = "jenkins";
+    commit = env.GIT_COMMIT?.trim() || null;
+    branch = env.BRANCH_NAME?.trim() || env.GIT_BRANCH?.trim() || null;
+  }
+
+  const inferredCi = !!provider || env.CI === "true" || env.CI === "1";
+  const trigger: "ci" | "manual" =
+    overrideTrigger === "ci" || overrideTrigger === "manual"
+      ? overrideTrigger
+      : inferredCi
+        ? "ci"
+        : "manual";
+
+  return {
+    trigger,
+    commit_sha: overrideCommit ?? commit,
+    branch: overrideBranch ?? branch,
+    provider: provider ?? (inferredCi ? "generic" : null),
+  };
+}