@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/classifier/recommended-action.ts

@@ -0,0 +1,222 @@
+/**
+ * ARV-56: single producer of `recommended_action` across every source
+ * that emits findings — run results (`db diagnose`), spec lint
+ * (`lint-spec.Issue`), probe-security findings, probe-mass-assignment
+ * verdicts, and conformance checks (`zond checks run`).
+ *
+ * Before this module, "what action does an agent take?" was answered in
+ * five different places:
+ *   - `recommendedAction` / `recommendedActionForGenerated`     (db-analysis)
+ *   - `recommendForCheck`                                       (checks runner)
+ *   - `stampRecommendedAction` (mass-assignment) + per-severity policy
+ *   - `stampAction`            (security) + per-severity policy
+ *   - inline `"fix_spec"` literal                               (lint)
+ *
+ * Each accumulated branches independently — ARV-11 added per-check
+ * actions, ARV-42 added a generator-aware override, TASK-294 layered
+ * probe severity mappings, the env-issue detector then overrode the
+ * result of all of them. By the time ARV-56 landed, the same logical
+ * question — "given this finding, what should the agent do?" — had four
+ * different entry points with subtle drift.
+ *
+ * This file owns that question. Every producer hands the classifier a
+ * `ClassifierContext` (a frozen description of the finding) and gets
+ * back a `RecommendedAction`. The classifier is **pure** — no I/O, no
+ * config reads, no side effects — so it can be table-tested.
+ *
+ * The thin wrappers (`recommendedAction`, `recommendedActionForGenerated`,
+ * `recommendForCheck`, `stampRecommendedAction`, `stampAction`) now
+ * delegate here instead of carrying their own switches. Removing a
+ * branch means editing one switch in this file.
+ */
+
+import type { RecommendedAction } from "../diagnostics/failure-hints.ts";
+import type { RunKind } from "../runner/run-kind.ts";
+
+export type FindingClass =
+  // db-analysis run-result rows ────────────────────────────────────
+  | "test:network_error"
+  | "test:api_error"
+  | "test:assertion_failed"
+
+  // checks/<id>  ────────────────────────────────────────────────────
+  | "check:status_code_conformance"
+  | "check:content_type_conformance"
+  | "check:response_headers_conformance"
+  | "check:response_schema_conformance"
+  | "check:not_a_server_error"
+  | "check:unsupported_method"
+  | "check:positive_data_acceptance"
+  | "check:use_after_free"
+  | "check:ensure_resource_availability"
+  | "check:negative_data_rejection"
+  | "check:missing_required_header"
+  | "check:ignored_auth"
+  | "check:cross_call_references"
+  | "check:idempotency_replay"
+  | "check:pagination_invariants"
+  | "check:lifecycle_transitions"
+  | "check:open_cors_on_sensitive"
+  | "check:rate_limit_headers_absent"
+  | "check:network_error"
+
+  // probe verdicts (severity already classified upstream) ───────────
+  | "probe:mass_assignment"
+  | "probe:security"
+
+  // lint-spec ───────────────────────────────────────────────────────
+  | "lint:issue";
+
+/** Optional severity hint — probe families surface a 5-level enum;
+ *  here we only care about the buckets the action mapping branches on. */
+export type FindingSeverity =
+  | "high"
+  | "medium"
+  | "inconclusive-5xx"
+  | "inconclusive-baseline"
+  | "low"
+  | "ok"
+  | "skipped";
+
+export interface ClassifierContext {
+  finding_class: FindingClass;
+  /** HTTP status code observed for the finding, when applicable.
+   *  null/undefined means "unknown / not relevant". */
+  status?: number | null;
+  /** Severity already assigned by the probe layer (mass-assignment /
+   *  security). The classifier reads it instead of re-deriving from
+   *  status — severity captures multi-step reasoning (baseline + attack
+   *  + follow-up GET) that status alone can't recover. */
+  severity?: FindingSeverity;
+  /** Run kind for the finding's parent run — currently informational; the
+   *  classifier may consult it in the future to e.g. downgrade probe-run
+   *  signal. Captured now so the contract is forward-compatible. */
+  run_kind?: RunKind;
+  /** Provenance of the failing test (only relevant for test:* classes). */
+  provenance?: { type?: string; generator?: string } | null;
+  /** Suite path used to detect generator-emitted tests. */
+  suite_path?: string | null;
+  /** When the env-issue detector flagged the suite, it overrides the
+   *  classifier's default. Producers set this *after* clustering. */
+  baseline_status?: number | null;
+  /** ARV-103 (F8): true when at least one assertion on the failing step
+   *  has `kind: "schema"`. Schema violations are real contract bugs — per
+   *  zond/SKILL.md L376-377 they should route to report_backend_bug, not
+   *  fix_test_logic. Producers (db-analysis) set this after walking the
+   *  step's assertions array. */
+  schema_violation?: boolean;
+}
+
+/**
+ * Decide the action for a finding. Returns `undefined` only for finding
+ * classes that intentionally don't carry an action (e.g. severity:low
+ * security findings — the producer should leave the field unset rather
+ * than coerce a value).
+ */
+export function classify(ctx: ClassifierContext): RecommendedAction | undefined {
+  switch (ctx.finding_class) {
+    // ── Run-result rows (db diagnose) ───────────────────────────────
+    case "test:api_error":
+      return "report_backend_bug";
+
+    case "test:network_error":
+      if (ctx.status === 401 || ctx.status === 403) return "fix_auth_config";
+      return "fix_network_config";
+
+    case "test:assertion_failed": {
+      // 401/403 → auth always wins.
+      if (ctx.status === 401 || ctx.status === 403) return "fix_auth_config";
+      // ARV-103 (F8): schema-kind assertions are real contract bugs (the
+      // server returned a body that violates its own spec). Route to
+      // report_backend_bug — same bucket as 5xx. Skill (zond/SKILL.md
+      // L376-377) explicitly says "treat them like 5xx, do not edit the
+      // expectation away". Wins over the generator-aware override below
+      // because regenerate_suite would silently re-emit the same broken
+      // assertion against the same broken response.
+      if (ctx.schema_violation) return "report_backend_bug";
+      // ARV-42: generator-emitted suites get a different default — editing
+      // the YAML gets clobbered on the next `zond audit`.
+      const generated = isGeneratedSource(ctx.provenance, ctx.suite_path);
+      if (generated) {
+        if (ctx.status === 404) return "fix_fixture";
+        if (ctx.status === 400 || ctx.status === 422) return "regenerate_suite";
+      }
+      return "fix_test_logic";
+    }
+
+    // ── checks/<id> ────────────────────────────────────────────────
+    case "check:status_code_conformance":
+    case "check:content_type_conformance":
+    case "check:response_headers_conformance":
+    case "check:response_schema_conformance":
+      return "fix_spec";
+
+    case "check:not_a_server_error":
+    case "check:unsupported_method":
+    case "check:positive_data_acceptance":
+    case "check:use_after_free":
+    case "check:ensure_resource_availability":
+    case "check:cross_call_references":
+    case "check:idempotency_replay":
+    case "check:pagination_invariants":
+    case "check:lifecycle_transitions":
+      return "report_backend_bug";
+
+    case "check:negative_data_rejection":
+      return "tighten_validation";
+
+    case "check:missing_required_header":
+      return "add_required_header";
+
+    case "check:ignored_auth":
+    case "check:open_cors_on_sensitive":
+      return "fix_auth_config";
+
+    case "check:rate_limit_headers_absent":
+      // ARV-256: missing rate-limit on write endpoints is an
+      // infrastructure-config gap — closest existing action is
+      // "fix_auth_config" (server-side hardening) rather than report-
+      // backend-bug (the spec doesn't say rate-limit must exist).
+      return "fix_auth_config";
+
+    case "check:network_error":
+      if (ctx.status === 401 || ctx.status === 403) return "fix_auth_config";
+      return "fix_network_config";
+
+    // ── Probe verdicts ─────────────────────────────────────────────
+    case "probe:mass_assignment":
+      switch (ctx.severity) {
+        case "high":
+        case "medium":
+        case "inconclusive-5xx":
+          return "report_backend_bug";
+        case "inconclusive-baseline":
+          return "fix_fixture";
+        default:
+          return undefined; // low / ok / skipped: no action
+      }
+
+    case "probe:security":
+      // TASK-294 policy: high/low both routed to backend-bug. Low is
+      // "server returned 2xx without echoing the payload" — still a
+      // surprising acceptance the backend should review.
+      if (ctx.severity === "high" || ctx.severity === "low") {
+        return "report_backend_bug";
+      }
+      return undefined;
+
+    // ── Lint findings ─────────────────────────────────────────────
+    case "lint:issue":
+      return "fix_spec";
+  }
+}
+
+function isGeneratedSource(
+  provenance: ClassifierContext["provenance"],
+  suite_path: ClassifierContext["suite_path"],
+): boolean {
+  if (provenance?.type === "openapi-generated") return true;
+  if (provenance?.generator && provenance.generator.toLowerCase().includes("zond")) return true;
+  if (typeof suite_path === "string" && /(^|\/)apis\/[^/]+\/tests\//.test(suite_path)) return true;
+  return false;
+}

package/src/core/context/current.ts

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { findWorkspaceRoot } from "../workspace/root.ts";
+
+/**
+ * TASK-290: current-API resolution chain.
+ *  - Global --api flag is mirrored into ZOND_API_GLOBAL by program.ts preAction.
+ *  - Users can also export ZOND_API in their shell.
+ *  - Persisted choice lives in `.zond/current-api` (was `.zond-current`).
+ */
+const FILENAME = ".zond/current-api";
+
+export function currentApiPath(cwd?: string): string {
+  const base = cwd ?? findWorkspaceRoot().root;
+  return join(base, FILENAME);
+}
+
+/**
+ * Returns the active API name. Resolution order:
+ *  1. ZOND_API_GLOBAL  (mirrored from `zond --api <name> ...`)
+ *  2. ZOND_API         (user env)
+ *  3. `.zond/current-api` file (set by `zond use <name>`)
+ */
+export function readCurrentApi(cwd?: string): string | null {
+  const fromGlobalFlag = process.env.ZOND_API_GLOBAL?.trim();
+  if (fromGlobalFlag) return fromGlobalFlag;
+  const fromEnv = process.env.ZOND_API?.trim();
+  if (fromEnv) return fromEnv;
+  const path = currentApiPath(cwd);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf-8").trim();
+  return raw.length > 0 ? raw : null;
+}
+
+/** Writes the API collection name to `.zond/current-api`. Creates the dir if needed. */
+export function writeCurrentApi(name: string, cwd?: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error("API name cannot be empty");
+  const path = currentApiPath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, trimmed + "\n", "utf-8");
+  return path;
+}
+
+/** Deletes `.zond/current-api`. Returns true when a file was removed, false when it did not exist. */
+export function clearCurrentApi(cwd?: string): boolean {
+  const path = currentApiPath(cwd);
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}

package/src/core/context/session.ts

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { findWorkspaceRoot } from "../workspace/root.ts";
+
+const SESSION_DIR = ".zond";
+const SESSION_FILE = "current-session";
+
+export interface SessionRecord {
+  id: string;
+  label?: string;
+  started_at: string;
+}
+
+export function sessionFilePath(cwd?: string): string {
+  const base = cwd ?? findWorkspaceRoot().root;
+  return join(base, SESSION_DIR, SESSION_FILE);
+}
+
+export function readCurrentSession(cwd?: string): SessionRecord | null {
+  const path = sessionFilePath(cwd);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf-8").trim();
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as Partial<SessionRecord>;
+    if (typeof parsed.id !== "string" || parsed.id.length === 0) return null;
+    return {
+      id: parsed.id,
+      label: typeof parsed.label === "string" ? parsed.label : undefined,
+      started_at: typeof parsed.started_at === "string" ? parsed.started_at : new Date().toISOString(),
+    };
+  } catch {
+    // legacy / hand-edited single-line UUID
+    return { id: raw, started_at: new Date().toISOString() };
+  }
+}
+
+export function writeCurrentSession(record: SessionRecord, cwd?: string): string {
+  const path = sessionFilePath(cwd);
+  const dir = path.slice(0, path.lastIndexOf("/"));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  else {
+    const st = statSync(dir);
+    if (!st.isDirectory()) {
+      throw new Error(`${dir} exists and is not a directory; remove it before running 'zond session start'`);
+    }
+  }
+  writeFileSync(path, JSON.stringify(record) + "\n", "utf-8");
+  return path;
+}
+
+export function clearCurrentSession(cwd?: string): boolean {
+  const path = sessionFilePath(cwd);
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}
+
+/**
+ * Resolution order for the session_id used by `zond run`:
+ *   1. explicit --session-id flag
+ *   2. ZOND_SESSION_ID env var
+ *   3. .zond/current-session file (written by `zond session start`)
+ *
+ * Returns null when none of the three is set.
+ */
+export function resolveSessionId(opts: {
+  flag?: string | null;
+  env?: string | null;
+  cwd?: string;
+}): string | null {
+  const flag = opts.flag?.trim();
+  if (flag) return flag;
+  const env = opts.env?.trim();
+  if (env) return env;
+  const record = readCurrentSession(opts.cwd);
+  return record?.id ?? null;
+}

package/src/core/coverage/loader.ts

@@ -0,0 +1,185 @@
+/**
+ * I/O wrapper around the pure `buildCoverageMatrix` engine — loads the
+ * registered API's spec snapshot, parses suites in the workspace to find
+ * ephemeral-tagged endpoints, reads `.api-fixtures.yaml` and `.env.yaml`,
+ * pulls run results from SQLite, and feeds it all into the engine.
+ *
+ * Server `/api/coverage`, the HTML exporter, and any future CLI command
+ * call this loader so they stay in sync.
+ */
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { findCollectionByNameOrId, getLatestRunByCollection, getResultsByRunId, getRunById, listRunsBySession, listRunsByCollectionFiltered } from "../../db/queries.ts";
+import type { RunRecord } from "../../db/queries.ts";
+import { assertLocalSpec } from "../setup-api.ts";
+import { readOpenApiSpec, extractEndpoints } from "../generator/openapi-reader.ts";
+import { parseDirectorySafe } from "../parser/yaml-parser.ts";
+import { loadEnvironment } from "../parser/variables.ts";
+import { findWorkspaceRoot } from "../workspace/root.ts";
+import {
+  buildCoverageMatrix,
+  type CoverageMatrix,
+  type BuildMatrixInput,
+} from "./reasons.ts";
+
+export interface CoverageLoadOptions {
+  apiName: string;
+  runId?: number;
+  /** TASK-255: union across multiple runs (e.g. tests-run + probes-run from
+   *  the same session). Loader concatenates results from each run before
+   *  feeding the matrix engine — buildCoverageMatrix is order-agnostic. When
+   *  set, takes precedence over `runId`. */
+  runIds?: number[];
+  /** TASK-255: when set, expanded to all runs in the session (filtered to
+   *  this collection). Wins over `runIds` and `runId`. */
+  sessionId?: string;
+  /** TASK-274: ISO timestamp lower bound (inclusive) — fold every run of
+   *  this collection started at-or-after this point. Wins over `runIds`
+   *  and `runId`, loses to `sessionId`. */
+  sinceIso?: string;
+  /** TASK-274: tag membership filter — fold every run of this collection
+   *  whose stored `tags` JSON contains this name. Wins over `runIds`
+   *  and `runId`, loses to `sessionId` / `sinceIso`. */
+  tag?: string;
+  profile?: "safe" | "full";
+  tagFilter?: string[];
+  /** Override workspace root (defaults to findWorkspaceRoot). */
+  workspaceRoot?: string;
+}
+
+export interface CoverageLoadResult {
+  apiName: string;
+  baseDir: string;
+  specPath: string;
+  matrix: CoverageMatrix;
+  /** Latest of the runs included in the coverage. Null if no runs found.
+   *  Kept singular for back-compat; for the full list use `runs`. */
+  run: RunRecord | null;
+  /** TASK-255: every run that contributed results to this coverage matrix,
+   *  ordered by started_at ascending. Single-element when no union flags
+   *  were used. */
+  runs: RunRecord[];
+  /** TASK-274: which selector resolved the run set, for diagnostics and
+   *  the JSON envelope (`union_mode`). null when only a single run
+   *  contributed and no union selector was used. */
+  unionMode: "session" | "since" | "tag" | "runs" | null;
+  profile: "safe" | "full";
+  tagFilter: string[];
+  ephemeralCount: number;
+}
+
+async function readFixturesAffected(baseDir: string): Promise<BuildMatrixInput["fixturesAffected"]> {
+  const path = join(baseDir, ".api-fixtures.yaml");
+  if (!existsSync(path)) return new Map();
+  const text = await Bun.file(path).text();
+  const parsed = Bun.YAML.parse(text) as { fixtures?: Array<{ name: string; required: boolean; source: string; affectedEndpoints?: string[] }> };
+  const out = new Map<string, { name: string; required: boolean; source: string }[]>();
+  for (const f of parsed.fixtures ?? []) {
+    for (const ep of f.affectedEndpoints ?? []) {
+      if (ep === "*") continue;
+      const list = out.get(ep) ?? [];
+      list.push({ name: f.name, required: f.required, source: f.source });
+      out.set(ep, list);
+    }
+  }
+  return out;
+}
+
+async function readEphemeralEndpoints(workspaceRoot: string): Promise<Set<string>> {
+  const out = new Set<string>();
+  const { suites } = await parseDirectorySafe(workspaceRoot);
+  for (const suite of suites) {
+    if (!suite.tags?.includes("ephemeral")) continue;
+    for (const t of suite.tests) out.add(`${t.method.toUpperCase()} ${t.path}`);
+  }
+  return out;
+}
+
+export async function loadCoverage(options: CoverageLoadOptions): Promise<CoverageLoadResult> {
+  const root = options.workspaceRoot ?? findWorkspaceRoot().root;
+  const collection = findCollectionByNameOrId(options.apiName);
+  if (!collection) throw new Error(`API '${options.apiName}' is not registered. Run \`zond add api --spec <path>\`.`);
+
+  const baseDir = collection.base_dir ?? join(root, "apis", collection.name);
+  const specPath = collection.openapi_spec
+    ? assertLocalSpec(collection.openapi_spec, collection.name)
+    : (() => { throw new Error(`Collection '${collection.name}' has no spec recorded.`); })();
+
+  const doc = await readOpenApiSpec(specPath);
+  const endpoints = extractEndpoints(doc);
+
+  // Resolve which runs contribute results. Precedence:
+  // sessionId > sinceIso > tag > runIds > runId > latest. since:/tag: are
+  // filtered to this collection only — the user has named an API, so they
+  // want runs of that API, not every collection that happens to share a tag.
+  let runs: RunRecord[] = [];
+  let unionMode: "session" | "since" | "tag" | "runs" | null = null;
+  if (options.sessionId) {
+    const sessRuns = listRunsBySession(options.sessionId);
+    // Include runs whose collection matches AND runs with NULL collection_id —
+    // the latter covers probe-suites and ad-hoc runs that didn't tag the API
+    // explicitly but still produced results against this session's workdir.
+    // Filtering them out makes `coverage --union session` silently show only
+    // the test-suite run (the original feedback-12 #F1 symptom).
+    runs = sessRuns
+      .filter((r) => r.collection_id === collection.id || r.collection_id == null)
+      .map((r) => getRunById(r.id))
+      .filter((r): r is RunRecord => r !== null);
+    unionMode = "session";
+  } else if (options.sinceIso) {
+    runs = listRunsByCollectionFiltered(collection.id, { since: options.sinceIso });
+    unionMode = "since";
+  } else if (options.tag) {
+    runs = listRunsByCollectionFiltered(collection.id, { tag: options.tag });
+    unionMode = "tag";
+  } else if (options.runIds && options.runIds.length > 0) {
+    runs = options.runIds
+      .map((id) => getRunById(id))
+      .filter((r): r is RunRecord => r !== null);
+    unionMode = "runs";
+  } else if (options.runId != null) {
+    const r = getRunById(options.runId);
+    if (r) runs = [r];
+  } else {
+    const latest = getLatestRunByCollection(collection.id);
+    if (latest) runs = [latest];
+  }
+  const results = runs.flatMap((r) => getResultsByRunId(r.id));
+  // `run` (singular) reflects the latest contributing run for back-compat
+  // with consumers that only care about a single run label.
+  const run = runs.length > 0 ? runs[runs.length - 1]! : null;
+
+  const fixturesAffected = await readFixturesAffected(baseDir);
+  const ephemeralEndpoints = await readEphemeralEndpoints(root);
+  const envVarsObj = await loadEnvironment(undefined, baseDir);
+  const envVars = new Set(Object.keys(envVarsObj).filter((k) => {
+    const v = envVarsObj[k];
+    return typeof v === "string" ? v.length > 0 : v != null;
+  }));
+
+  const profile = options.profile ?? "full";
+  const tagFilter = options.tagFilter ?? [];
+
+  const matrix = buildCoverageMatrix({
+    endpoints, results, fixturesAffected, envVars, ephemeralEndpoints,
+    tagFilter, profile,
+  });
+
+  return {
+    apiName: collection.name,
+    baseDir,
+    specPath,
+    matrix,
+    run,
+    runs,
+    unionMode,
+    profile,
+    tagFilter,
+    ephemeralCount: ephemeralEndpoints.size,
+  };
+}
+
+async function listRegisteredApiNames(): Promise<string[]> {
+  const { listCollections } = await import("../../db/queries.ts");
+  return listCollections().map((c) => c.name);
+}