@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/context/current.ts

@@ -1,32 +1,48 @@
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { findWorkspaceRoot } from "../workspace/root.ts";
 
-const FILENAME = ".zond-current";
+/**
+ * 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 API collection name stored in `.zond-current`, or null when the file is absent or empty. */
+/**
+ * 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`. The file is single-line plain text. */
+/** 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`. Returns true when a file was removed, false when it did not exist. */
+/** 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;

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,216 @@
+/**
+ * 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

@@ -0,0 +1,300 @@
+/**
+ * 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 };
+}