@kirrosh/zond 0.26.1 → 0.27.0

package/src/core/context/session.ts

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

@@ -1,216 +0,0 @@
-/**
- * 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;
-  /** ARV-265: which `run_kind`s contribute to the matrix.
-   *   - 'test' (default, back-compat) — runs whose `run_kind` is
-   *     'regular' OR 'probe' (i.e. anything `zond run` produced). This
-   *     is what `pass-coverage` / `hit-coverage` have always measured.
-   *   - 'audit' — every kind (regular | probe | check | request |
-   *     fixture). Used by `audit-coverage` to answer "did this scan
-   *     reach the API?" regardless of producer. */
-  scope?: "test" | "audit";
-  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;
-  /** ARV-265: scope this matrix was built under. Echoes `options.scope`
-   *  (default 'test') so dual-metric callers can sanity-check the result. */
-  scope: "test" | "audit";
-}
-
-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.
-  // ARV-265: `scope` toggles which run_kinds survive the post-resolution
-  // filter (see CoverageLoadOptions.scope). Default 'test' keeps the
-  // pre-ARV-265 semantics (regular + probe rows contribute) so existing
-  // CI consumers see no surprise.
-  const scope = options.scope ?? "test";
-  const allowedKinds: ReadonlySet<string> = scope === "audit"
-    ? new Set(["regular", "probe", "check", "request", "fixture"])
-    : new Set(["regular", "probe"]);
-  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 if (scope === "audit") {
-    // ARV-265 audit mode latest-fallback: pick the most recent run of any
-    // kind so a scan that only ran `checks run` (no `zond run`) still
-    // produces a meaningful audit metric.
-    const latest = getLatestRunByCollection(collection.id, { runKind: "any" });
-    if (latest) runs = [latest];
-  } else {
-    const latest = getLatestRunByCollection(collection.id);
-    if (latest) runs = [latest];
-  }
-  // ARV-265: post-resolution kind filter. Session/since/tag may have
-  // pulled in audit-only kinds (check/request/fixture); the test-scope
-  // filter strips them so `pass-coverage` keeps the "curated suites
-  // passed" semantics. Audit scope keeps everything.
-  runs = runs.filter((r) => allowedKinds.has(r.run_kind));
-  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,
-    scope,
-  };
-}
-
-async function listRegisteredApiNames(): Promise<string[]> {
-  const { listCollections } = await import("../../db/queries.ts");
-  return listCollections().map((c) => c.name);
-}

package/src/core/coverage/reasons.ts

@@ -1,300 +0,0 @@
-/**
- * Coverage reasons engine — pure function: spec endpoints + run results +
- * workspace context → matrix cells with explicit reason codes.
- *
- * The matrix has rows per endpoint (METHOD path) and three status-class
- * columns (`2xx`, `4xx`, `5xx`). Each cell carries:
- *   - status: covered | partial | uncovered
- *   - reasons: zero or more codes that explain the cell state
- *   - results: stored step results that contributed to this cell
- *
- * "Default" branch is intentionally omitted — extractEndpoints already
- * skips OpenAPI's "default" status code, so making a column for it would
- * be permanently empty and noisy.
- *
- * The function is intentionally I/O-free: callers (server, exporter, CLI)
- * load endpoints/results/fixtures separately and feed them in. This keeps
- * the engine trivial to unit-test.
- */
-import type { EndpointInfo } from "../generator/types.ts";
-import type { StoredStepResult } from "../../db/queries.ts";
-
-export type StatusClass = "2xx" | "4xx" | "5xx";
-const STATUS_CLASSES: StatusClass[] = ["2xx", "4xx", "5xx"];
-
-export type ReasonCode =
-  | "covered"
-  | "partial-failed"
-  | "not-generated"
-  | "no-spec"
-  | "deprecated"
-  | "no-fixtures"
-  | "ephemeral-only"
-  | "auth-scope-mismatch"
-  | "tag-filtered";
-
-export interface CellResultRef {
-  resultId: number;
-  runId: number;
-  status: string;
-  responseStatus: number | null;
-  failureClass: string | null;
-  testName: string;
-  suiteFile: string | null;
-}
-
-export interface MatrixCell {
-  status: "covered" | "partial" | "uncovered";
-  reasons: ReasonCode[];
-  results: CellResultRef[];
-}
-
-export interface MatrixRow {
-  endpoint: string;
-  method: string;
-  path: string;
-  tags: string[];
-  deprecated: boolean;
-  security: string[];
-  declaredStatuses: number[];
-  cells: Record<StatusClass, MatrixCell>;
-}
-
-export interface BuildMatrixInput {
-  endpoints: EndpointInfo[];
-  results: StoredStepResult[];
-  fixturesAffected: Map<string, { name: string; required: boolean; source: string }[]>;
-  envVars: Set<string>;
-  ephemeralEndpoints: Set<string>;
-  tagFilter: string[];
-  profile: "safe" | "full";
-}
-
-export interface MatrixTotals {
-  endpoints: number;
-  cells: number;
-  covered: number;
-  partial: number;
-  uncovered: number;
-  byReason: Record<ReasonCode, number>;
-}
-
-export interface CoverageMatrix {
-  rows: MatrixRow[];
-  totals: MatrixTotals;
-}
-
-function endpointKey(method: string, path: string): string {
-  return `${method.toUpperCase()} ${path}`;
-}
-
-function classifyStatus(code: number): StatusClass | null {
-  if (code >= 200 && code < 300) return "2xx";
-  if (code >= 400 && code < 500) return "4xx";
-  if (code >= 500 && code < 600) return "5xx";
-  return null;
-}
-
-/**
- * Build a regex that matches a concrete URL path against an OpenAPI path
- * template. `/pets/{id}` becomes `^/pets/[^/]+$`.
- */
-function specPathToRegex(specPath: string): RegExp {
-  const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
-  return new RegExp(`^${pattern}$`);
-}
-
-function extractPathname(url: string | null): string | null {
-  if (!url) return null;
-  try {
-    const u = new URL(url);
-    return u.pathname;
-  } catch {
-    if (url.startsWith("/")) {
-      const q = url.indexOf("?");
-      return q === -1 ? url : url.slice(0, q);
-    }
-    return null;
-  }
-}
-
-function matchResultToEndpoint(
-  result: StoredStepResult,
-  endpointsByKey: Map<string, EndpointInfo>,
-  endpointsByMethod: Map<string, { ep: EndpointInfo; rx: RegExp }[]>,
-): EndpointInfo | null {
-  const provEp = (result.provenance as Record<string, unknown> | null)?.endpoint;
-  if (typeof provEp === "string") {
-    const sp = provEp.indexOf(" ");
-    const normalised = sp === -1
-      ? provEp
-      : `${provEp.slice(0, sp).toUpperCase()}${provEp.slice(sp)}`;
-    const direct = endpointsByKey.get(normalised);
-    if (direct) return direct;
-  }
-  const method = result.request_method?.toUpperCase();
-  if (!method) return null;
-  const candidates = endpointsByMethod.get(method);
-  if (!candidates) return null;
-  const pathname = extractPathname(result.request_url);
-  if (!pathname) return null;
-  for (const c of candidates) if (c.rx.test(pathname)) return c.ep;
-  return null;
-}
-
-function pathParamNames(path: string): string[] {
-  return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]!);
-}
-
-function hasMissingPathFixtures(
-  ep: EndpointInfo,
-  fixturesAffected: Map<string, { name: string; required: boolean; source: string }[]>,
-  envVars: Set<string>,
-): boolean {
-  const params = pathParamNames(ep.path);
-  if (params.length === 0) return false;
-  const label = endpointKey(ep.method, ep.path);
-  const declared = fixturesAffected.get(label) ?? [];
-  // Manifest entry per param? Required + missing = no-fixtures.
-  const required = declared.filter((f) => f.source === "path" && f.required);
-  for (const f of required) if (!envVars.has(f.name)) return true;
-  // Manifest may not enumerate every param when it was generated before this
-  // endpoint existed, so also require: every {param} must map to an env var.
-  for (const p of params) {
-    if (envVars.has(p)) continue;
-    const declaredForP = declared.find((f) => f.name === p);
-    if (declaredForP && envVars.has(declaredForP.name)) continue;
-    return true;
-  }
-  return false;
-}
-
-function hasMissingAuthFixtures(ep: EndpointInfo, envVars: Set<string>): boolean {
-  if (ep.security.length === 0) return false;
-  // Convention: a security scheme name maps to one of `<name>`, `<name>_token`,
-  // or the lowercased `<name>_token` env var. The endpoint is satisfied if
-  // *any* of its required schemes has a configured token.
-  for (const scheme of ep.security) {
-    const variants = [scheme, `${scheme}_token`, `${scheme.toLowerCase()}_token`, "auth_token"];
-    if (variants.some((v) => envVars.has(v))) return false;
-  }
-  return true;
-}
-
-function declaredStatusClasses(ep: EndpointInfo): Set<StatusClass> {
-  const out = new Set<StatusClass>();
-  for (const r of ep.responses) {
-    const cls = classifyStatus(r.statusCode);
-    if (cls) out.add(cls);
-  }
-  return out;
-}
-
-export function buildCoverageMatrix(input: BuildMatrixInput): CoverageMatrix {
-  const endpointsByKey = new Map<string, EndpointInfo>();
-  const endpointsByMethod = new Map<string, { ep: EndpointInfo; rx: RegExp }[]>();
-  for (const ep of input.endpoints) {
-    endpointsByKey.set(endpointKey(ep.method, ep.path), ep);
-    const method = ep.method.toUpperCase();
-    const list = endpointsByMethod.get(method) ?? [];
-    list.push({ ep, rx: specPathToRegex(ep.path) });
-    endpointsByMethod.set(method, list);
-  }
-
-  // Bucket results: key = "METHOD path" → statusClass → list of refs.
-  const buckets = new Map<string, Record<StatusClass, CellResultRef[]>>();
-  for (const r of input.results) {
-    const ep = matchResultToEndpoint(r, endpointsByKey, endpointsByMethod);
-    if (!ep) continue;
-    const key = endpointKey(ep.method, ep.path);
-    let bucket = buckets.get(key);
-    if (!bucket) {
-      bucket = { "2xx": [], "4xx": [], "5xx": [] };
-      buckets.set(key, bucket);
-    }
-    if (r.response_status == null) continue;
-    const cls = classifyStatus(r.response_status);
-    if (!cls) continue;
-    bucket[cls].push({
-      resultId: r.id,
-      runId: r.run_id,
-      status: r.status,
-      responseStatus: r.response_status,
-      failureClass: r.failure_class,
-      testName: r.test_name,
-      suiteFile: r.suite_file,
-    });
-  }
-
-  const totals: MatrixTotals = {
-    endpoints: input.endpoints.length,
-    cells: 0,
-    covered: 0,
-    partial: 0,
-    uncovered: 0,
-    byReason: {
-      "covered": 0, "partial-failed": 0, "not-generated": 0, "no-spec": 0,
-      "deprecated": 0, "no-fixtures": 0, "ephemeral-only": 0,
-      "auth-scope-mismatch": 0, "tag-filtered": 0,
-    },
-  };
-
-  const filterTags = new Set(input.tagFilter);
-  const rows: MatrixRow[] = input.endpoints.map((ep) => {
-    const key = endpointKey(ep.method, ep.path);
-    const bucket = buckets.get(key) ?? { "2xx": [], "4xx": [], "5xx": [] };
-    const declared = declaredStatusClasses(ep);
-    const tagFiltered = filterTags.size > 0 && !ep.tags.some((t) => filterTags.has(t));
-    const cells: Record<StatusClass, MatrixCell> = { "2xx": null!, "4xx": null!, "5xx": null!};
-
-    for (const cls of STATUS_CLASSES) {
-      const refs = bucket[cls];
-      const passing = refs.some((r) => r.status === "pass");
-      const failing = refs.some((r) => r.status !== "pass");
-      const reasons: ReasonCode[] = [];
-      let cellStatus: MatrixCell["status"];
-      if (passing && !failing) {
-        cellStatus = "covered";
-        reasons.push("covered");
-      } else if (passing && failing) {
-        cellStatus = "covered";
-        reasons.push("covered", "partial-failed");
-      } else if (failing) {
-        cellStatus = "partial";
-        reasons.push("partial-failed");
-      } else {
-        cellStatus = "uncovered";
-        if (!declared.has(cls)) reasons.push("no-spec");
-        if (ep.deprecated) reasons.push("deprecated");
-        if (input.ephemeralEndpoints.has(key) && input.profile === "safe") reasons.push("ephemeral-only");
-        if (tagFiltered) reasons.push("tag-filtered");
-        if (hasMissingPathFixtures(ep, input.fixturesAffected, input.envVars)) reasons.push("no-fixtures");
-        if (hasMissingAuthFixtures(ep, input.envVars)) reasons.push("auth-scope-mismatch");
-        if (reasons.length === 0) reasons.push("not-generated");
-      }
-      // Always tag deprecated even on covered cells — it's an awareness flag.
-      if (ep.deprecated && !reasons.includes("deprecated")) reasons.push("deprecated");
-
-      cells[cls] = { status: cellStatus, reasons, results: refs };
-
-      totals.cells += 1;
-      if (cellStatus === "covered") totals.covered += 1;
-      else if (cellStatus === "partial") totals.partial += 1;
-      else totals.uncovered += 1;
-      for (const code of reasons) totals.byReason[code] += 1;
-    }
-
-    return {
-      endpoint: key,
-      method: ep.method.toUpperCase(),
-      path: ep.path,
-      tags: ep.tags,
-      deprecated: !!ep.deprecated,
-      security: ep.security,
-      declaredStatuses: ep.responses.map((r) => r.statusCode).sort((a, b) => a - b),
-      cells,
-    };
-  });
-
-  return { rows, totals };
-}