@kirrosh/zond 0.21.0 → 0.23.0

package/src/db/migrate.ts

@@ -0,0 +1,126 @@
+/**
+ * ARV-127 (m-19): file-based SQLite migration runner.
+ *
+ * Why a new runner. The legacy migration path in `schema.ts`
+ * (`runMigrations` + `PRAGMA user_version`) is fine for the additive
+ * column changes shipped through v10, but the knowledge-base work
+ * planned past m-19 will need richer migrations (multi-statement,
+ * data backfills, optional rollback notes). Inlining those as `if
+ * (ver >= N && ver < N+1)` blocks in TypeScript stops scaling once
+ * each migration becomes a small project of its own.
+ *
+ * This module sits on top of the legacy path:
+ *   - `runMigrations()` is untouched — it owns the PRAGMA-version era
+ *     and keeps fresh DBs / older snapshots correct.
+ *   - `applyMigrations()` runs *after* `runMigrations()`, walks the
+ *     registered migration list, and applies anything not yet recorded
+ *     in `schema_migrations`. New work (v11+) lands as files; the
+ *     0001_run_kind.sql file mirrors the most recent legacy migration
+ *     so the two systems agree on the post-v10 schema for fresh DBs.
+ *
+ * Existing-DB compatibility (AC#5). On a `.zond/zond.db` that already
+ * survived the legacy `runMigrations` path (user_version >= 10), the
+ * `run_kind` column already exists — re-running `0001_run_kind.sql`
+ * would throw a `duplicate column` error. We seed the legacy ids into
+ * `schema_migrations` once, on first contact with the new runner, so
+ * those rows are treated as "already applied" without executing.
+ *
+ * Distribution. The SQL bodies are imported as embedded text so
+ * `bun build --compile` packs them into the binary (no on-disk
+ * lookup at runtime — same pattern as the init/templates skills).
+ */
+import type { Database } from "bun:sqlite";
+
+import migration_0001_run_kind from "./migrations/0001_run_kind.sql" with { type: "text" };
+
+/** Migration manifest. Each entry is a `{ id, sql }` pair; order in
+ *  this array is the apply order, matching the lexical sort that the
+ *  Django / Rails-style `<id>_<slug>.sql` convention would produce on
+ *  disk. Adding a new migration = add a text-import + push to this
+ *  list. The runner reads this constant, not the filesystem. */
+const MIGRATIONS: ReadonlyArray<{ id: string; sql: string }> = [
+  { id: "0001_run_kind", sql: migration_0001_run_kind },
+];
+
+/** Pre-existing migration ids that were already applied by the legacy
+ *  PRAGMA-version path. When the new runner first encounters a DB
+ *  whose `user_version >= 10`, we record these as applied without
+ *  running them — the inline `runMigrations` already did. */
+const LEGACY_SEED_IDS: ReadonlyArray<{ id: string; minUserVersion: number }> = [
+  { id: "0001_run_kind", minUserVersion: 10 },
+];
+
+function currentUserVersion(db: Database): number {
+  const row = db.query("PRAGMA user_version").get() as
+    | { user_version: number }
+    | undefined;
+  return row?.user_version ?? 0;
+}
+
+/**
+ * Idempotently apply every pending migration. Safe to call on every
+ * DB open — the registry table makes the no-op case cheap.
+ *
+ * Failure semantics: each migration runs in its own transaction. A
+ * script that throws (bad SQL, constraint violation) rolls its own
+ * statements back and re-raises; later migrations don't run. The
+ * caller (DB open path) treats this as fatal — there is no partial
+ * upgrade.
+ *
+ * The optional `overrides` parameter lets tests inject a synthetic
+ * migration list (e.g. to exercise a migration order or a failing
+ * script) without touching the shipped manifest.
+ */
+export function applyMigrations(
+  db: Database,
+  overrides?: { migrations?: ReadonlyArray<{ id: string; sql: string }>; legacySeed?: ReadonlyArray<{ id: string; minUserVersion: number }> },
+): { applied: string[]; skipped: string[] } {
+  const migrations = overrides?.migrations ?? MIGRATIONS;
+  const legacySeed = overrides?.legacySeed ?? LEGACY_SEED_IDS;
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id          TEXT PRIMARY KEY,
+      applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+
+  // Legacy seed: mark already-applied-by-the-PRAGMA-runner ids as done.
+  const userVersion = currentUserVersion(db);
+  const insertSeed = db.prepare(
+    "INSERT OR IGNORE INTO schema_migrations (id) VALUES (?)",
+  );
+  for (const seed of legacySeed) {
+    if (userVersion >= seed.minUserVersion) {
+      insertSeed.run(seed.id);
+    }
+  }
+
+  const appliedRows = db
+    .query("SELECT id FROM schema_migrations")
+    .all() as Array<{ id: string }>;
+  const alreadyApplied = new Set(appliedRows.map((r) => r.id));
+
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const migration of migrations) {
+    if (alreadyApplied.has(migration.id)) {
+      skipped.push(migration.id);
+      continue;
+    }
+    db.transaction(() => {
+      db.exec(migration.sql);
+      db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+    })();
+    applied.push(migration.id);
+  }
+
+  return { applied, skipped };
+}
+
+/** Exported for tests + downstream tooling that wants to know which
+ *  migration ids ship with the binary. */
+export function listShippedMigrations(): string[] {
+  return MIGRATIONS.map((m) => m.id);
+}

package/src/db/migrations/0001_run_kind.sql

@@ -0,0 +1,25 @@
+-- ARV-127 (m-19): captures the legacy v9→v10 inline migration as the
+-- first file-based migration of the new runner. Mirrors the SQL block
+-- previously written in src/db/schema.ts `runMigrations()`. Existing
+-- `.zond/zond.db` files that already ran the inline migration are
+-- pre-seeded as "applied" by `applyMigrations`, so this script never
+-- re-executes the ALTER on a DB where `run_kind` already exists.
+--
+-- Source: ARV-55 — classify each historical run by suite kind so the
+-- coverage default query becomes a column compare.
+
+ALTER TABLE runs ADD COLUMN run_kind TEXT NOT NULL DEFAULT 'regular';
+
+UPDATE runs SET run_kind = 'probe'
+WHERE id IN (
+  SELECT r.id FROM runs r
+  WHERE EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file LIKE '%probes/%')
+    AND NOT EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file NOT LIKE '%probes/%')
+);
+
+UPDATE runs SET run_kind = 'check'
+WHERE id IN (
+  SELECT r.id FROM runs r
+  WHERE EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file LIKE '%checks/%')
+    AND NOT EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file NOT LIKE '%checks/%')
+);

package/src/db/migrations/sql.d.ts

@@ -0,0 +1,4 @@
+declare module "*.sql" {
+  const content: string;
+  export default content;
+}

package/src/db/queries/collections.ts

@@ -0,0 +1,133 @@
+import { getDb } from "../schema.ts";
+import {
+  normalizePath,
+  type CollectionRecord,
+  type CollectionSummary,
+  type CreateCollectionOpts,
+  type RunRecord,
+} from "./types.ts";
+
+export function createCollection(opts: CreateCollectionOpts): number {
+  const db = getDb();
+  const stmt = db.prepare(`
+    INSERT INTO collections (name, base_dir, test_path, openapi_spec)
+    VALUES ($name, $base_dir, $test_path, $openapi_spec)
+  `);
+  const result = stmt.run({
+    $name: opts.name,
+    $base_dir: opts.base_dir ?? null,
+    $test_path: opts.test_path,
+    $openapi_spec: opts.openapi_spec ?? null,
+  });
+  return Number(result.lastInsertRowid);
+}
+
+export function getCollectionById(id: number): CollectionRecord | null {
+  const db = getDb();
+  return db.query("SELECT * FROM collections WHERE id = ?").get(id) as CollectionRecord | null;
+}
+
+export function getLatestRunByCollection(
+  collectionId: number,
+  opts: { runKind?: "regular" | "probe" | "check" | "any" } = {},
+): RunRecord | null {
+  const db = getDb();
+  // ARV-55: 'regular' is the default so coverage skips probe-only runs
+  // without an explicit predicate. 'any' opts back into the legacy
+  // behaviour (used by `coverage`'s probe-run hint logic).
+  const kind = opts.runKind ?? "regular";
+  const kindClause = kind === "any" ? "" : "AND run_kind = ?";
+  const params: (string | number)[] = [collectionId];
+  if (kind !== "any") params.push(kind);
+  const row = db.query(`
+    SELECT * FROM runs
+    WHERE collection_id = ? AND finished_at IS NOT NULL ${kindClause}
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get(...params) as (Record<string, unknown> & { tags?: unknown }) | null;
+  if (!row) return null;
+  let tags: string[] | null = null;
+  if (typeof row.tags === "string") {
+    try {
+      const v = JSON.parse(row.tags);
+      if (Array.isArray(v) && v.every((x) => typeof x === "string")) tags = v;
+    } catch {
+      // legacy/corrupt — leave null
+    }
+  }
+  // ARV-55: normalise run_kind alongside tags so RunRecord stays consistent.
+  const rk = row.run_kind;
+  const run_kind: import("../../core/runner/run-kind.ts").RunKind =
+    rk === "probe" || rk === "check" ? rk : "regular";
+  return { ...(row as unknown as RunRecord), tags, run_kind };
+}
+
+export function listCollections(): CollectionSummary[] {
+  const db = getDb();
+  return db.query(`
+    SELECT
+      c.id, c.name, c.base_dir, c.test_path, c.openapi_spec, c.created_at,
+      COUNT(r.id) AS total_runs,
+      CASE WHEN SUM(r.total) > 0
+        THEN ROUND(SUM(r.passed) * 100.0 / SUM(r.total), 1)
+        ELSE 0 END AS pass_rate,
+      MAX(r.started_at) AS last_run_at,
+      COALESCE((SELECT passed FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_passed,
+      COALESCE((SELECT failed FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_failed,
+      COALESCE((SELECT total FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_total
+    FROM collections c
+    LEFT JOIN runs r ON r.collection_id = c.id AND r.finished_at IS NOT NULL
+    GROUP BY c.id
+    ORDER BY c.name
+  `).all() as CollectionSummary[];
+}
+
+export function updateCollection(id: number, opts: Partial<CreateCollectionOpts>): boolean {
+  const db = getDb();
+  const sets: string[] = [];
+  const params: Record<string, any> = { $id: id };
+
+  if (opts.name !== undefined) { sets.push("name = $name"); params.$name = opts.name; }
+  if (opts.base_dir !== undefined) { sets.push("base_dir = $base_dir"); params.$base_dir = opts.base_dir; }
+  if (opts.test_path !== undefined) { sets.push("test_path = $test_path"); params.$test_path = opts.test_path; }
+  if (opts.openapi_spec !== undefined) { sets.push("openapi_spec = $openapi_spec"); params.$openapi_spec = opts.openapi_spec; }
+
+  if (sets.length === 0) return false;
+
+  const result = db.prepare(`UPDATE collections SET ${sets.join(", ")} WHERE id = $id`).run(params);
+  return result.changes > 0;
+}
+
+export function deleteCollection(id: number, deleteRuns = false): boolean {
+  const db = getDb();
+  if (deleteRuns) {
+    const runIds = db.query("SELECT id FROM runs WHERE collection_id = ?").all(id) as { id: number }[];
+    for (const row of runIds) {
+      db.prepare("DELETE FROM results WHERE run_id = ?").run(row.id);
+    }
+    db.prepare("DELETE FROM runs WHERE collection_id = ?").run(id);
+  } else {
+    db.prepare("UPDATE runs SET collection_id = NULL WHERE collection_id = ?").run(id);
+  }
+  const result = db.prepare("DELETE FROM collections WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function findCollectionByTestPath(path: string): CollectionRecord | null {
+  const db = getDb();
+  const normalized = normalizePath(path);
+  return db.query("SELECT * FROM collections WHERE test_path = ?").get(normalized) as CollectionRecord | null;
+}
+
+export function findCollectionByNameOrId(nameOrId: string): CollectionRecord | null {
+  const db = getDb();
+  // Try as numeric ID first
+  const id = parseInt(nameOrId, 10);
+  if (!isNaN(id)) {
+    const byId = db.query("SELECT * FROM collections WHERE id = ?").get(id) as CollectionRecord | null;
+    if (byId) return byId;
+  }
+  // Then by name (case-insensitive)
+  return db.query("SELECT * FROM collections WHERE lower(name) = lower(?)").get(nameOrId) as CollectionRecord | null;
+}
+

package/src/db/queries/coverage.ts

@@ -0,0 +1,9 @@
+/**
+ * Reserved for coverage-domain DB queries. As of TASK-187, coverage
+ * tables (`coverage_runs`, etc.) are still managed entirely from
+ * `src/core/coverage/`; nothing in `queries.ts` was coverage-specific to
+ * move here. The file exists so the per-domain layout is future-proof
+ * — when a coverage table-backed feature lands, queries land here and
+ * the cli/UI imports stay stable.
+ */
+export {};

package/src/db/queries/dashboard.ts

@@ -0,0 +1,59 @@
+import { getDb } from "../schema.ts";
+import type {
+  DashboardStats,
+  PassRateTrendPoint,
+  SlowestTest,
+  FlakyTest,
+} from "./types.ts";
+
+export function getDashboardStats(): DashboardStats {
+  const db = getDb();
+  const row = db.query(`
+    SELECT
+      COUNT(*)            AS totalRuns,
+      COALESCE(SUM(total), 0)   AS totalTests,
+      CASE WHEN SUM(total) > 0
+        THEN ROUND(SUM(passed) * 100.0 / SUM(total), 1)
+        ELSE 0 END        AS overallPassRate,
+      COALESCE(ROUND(AVG(duration_ms), 0), 0) AS avgDuration
+    FROM runs
+    WHERE finished_at IS NOT NULL
+  `).get() as { totalRuns: number; totalTests: number; overallPassRate: number; avgDuration: number };
+  return row;
+}
+
+export function getPassRateTrend(limit = 30): PassRateTrendPoint[] {
+  const db = getDb();
+  return db.query(`
+    SELECT id AS run_id, started_at,
+      CASE WHEN total > 0 THEN ROUND(passed * 100.0 / total, 1) ELSE 0 END AS pass_rate
+    FROM runs
+    WHERE finished_at IS NOT NULL
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(limit) as PassRateTrendPoint[];
+}
+
+export function getSlowestTests(limit = 5): SlowestTest[] {
+  const db = getDb();
+  return db.query(`
+    SELECT suite_name, test_name, ROUND(AVG(duration_ms), 0) AS avg_duration
+    FROM results
+    GROUP BY suite_name, test_name
+    ORDER BY avg_duration DESC
+    LIMIT ?
+  `).all(limit) as SlowestTest[];
+}
+
+export function getFlakyTests(runsBack = 20, limit = 5): FlakyTest[] {
+  const db = getDb();
+  return db.query(`
+    SELECT r.suite_name, r.test_name, COUNT(DISTINCT r.status) AS distinct_statuses
+    FROM results r
+    INNER JOIN (SELECT id FROM runs ORDER BY started_at DESC LIMIT ?) recent ON r.run_id = recent.id
+    GROUP BY r.suite_name, r.test_name
+    HAVING COUNT(DISTINCT r.status) > 1
+    ORDER BY distinct_statuses DESC
+    LIMIT ?
+  `).all(runsBack, limit) as FlakyTest[];
+}

package/src/db/queries/results.ts

@@ -0,0 +1,128 @@
+import { getDb, withDbRetry } from "../schema.ts";
+import type { TestRunResult } from "../../core/runner/types.ts";
+import { getSecretRegistry } from "../../core/secrets/registry.ts";
+import type { StoredStepResult } from "./types.ts";
+
+function parseProvenance(raw: unknown): import("../../core/parser/types.ts").SourceMetadata | null {
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveResults(runId: number, suiteResults: TestRunResult[]): void {
+  const db = getDb();
+
+  const stmt = db.prepare(`
+    INSERT INTO results
+      (run_id, suite_name, test_name, status, duration_ms,
+       request_method, request_url, request_body,
+       response_status, response_body, response_headers, error_message, assertions, captures, suite_file, provenance, failure_class, failure_class_reason, spec_pointer, spec_excerpt)
+    VALUES
+      ($run_id, $suite_name, $test_name, $status, $duration_ms,
+       $request_method, $request_url, $request_body,
+       $response_status, $response_body, $response_headers, $error_message, $assertions, $captures, $suite_file, $provenance, $failure_class, $failure_class_reason, $spec_pointer, $spec_excerpt)
+  `);
+
+  // TASK-167 (m-10): every string field that can carry a leaked secret
+  // (URL with token in query, body echo on 401, Set-Cookie header, etc.)
+  // goes through the registry sanitizer before INSERT.
+  const reg = getSecretRegistry();
+  const redactString = (s: string | null | undefined): string | null =>
+    s == null ? null : reg.redact(s);
+  const redactJson = (v: unknown): string | null => {
+    if (v == null) return null;
+    if (typeof v === "string") return reg.redact(v);
+    return reg.redact(JSON.stringify(v));
+  };
+
+  withDbRetry("saveResults", () => db.transaction(() => {
+    for (const suite of suiteResults) {
+      for (const step of suite.steps) {
+        const maxBodySize = 50_000;
+        const truncBody = (s: string | null | undefined) =>
+          s && s.length > maxBodySize ? s.slice(0, maxBodySize) + "\n...[truncated]" : (s ?? null);
+        stmt.run({
+          $run_id: runId,
+          $suite_name: suite.suite_name,
+          $test_name: step.name,
+          $status: step.status,
+          $duration_ms: step.duration_ms,
+          $request_method: step.request.method,
+          $request_url: redactString(step.request.url),
+          $request_body: redactString(truncBody(step.request.body)),
+          $response_status: step.response?.status ?? null,
+          $response_body: redactString(truncBody(step.response?.body)),
+          $response_headers: step.response?.headers
+            ? redactJson(step.response.headers)
+            : null,
+          $error_message: redactString(step.error ?? null),
+          $assertions: step.assertions.length > 0 ? redactJson(step.assertions) : null,
+          $captures: Object.keys(step.captures).length > 0 ? redactJson(step.captures) : null,
+          $suite_file: suite.suite_file ?? null,
+          $provenance: step.provenance ? JSON.stringify(step.provenance) : null,
+          $failure_class: step.failure_class ?? null,
+          $failure_class_reason: step.failure_class_reason ?? null,
+          $spec_pointer: step.spec_pointer ?? null,
+          $spec_excerpt: redactString(step.spec_excerpt ?? null),
+        });
+      }
+    }
+  })());
+}
+
+export function getResultsByRunId(runId: number): StoredStepResult[] {
+  const db = getDb();
+  const rows = db.query("SELECT * FROM results WHERE run_id = ? ORDER BY id").all(runId) as Array<
+    Omit<StoredStepResult, "assertions" | "captures" | "provenance"> & {
+      assertions: string | null;
+      captures: string | null;
+      provenance: string | null;
+    }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+    provenance: parseProvenance(row.provenance),
+  }));
+}
+
+export function getFilteredResults(
+  runId: number,
+  filters: {
+    method?: string;
+    /** Compiled SQL fragment for the `--status` filter (TASK-140). */
+    statusSql?: { sql: string; params: number[] };
+  },
+): StoredStepResult[] {
+  const db = getDb();
+  const conditions = ["run_id = ?"];
+  const params: (string | number)[] = [runId];
+
+  if (filters.method) {
+    conditions.push("request_method = ?");
+    params.push(filters.method.toUpperCase());
+  }
+  if (filters.statusSql) {
+    conditions.push(filters.statusSql.sql);
+    params.push(...filters.statusSql.params);
+  }
+
+  const rows = db.query(`SELECT * FROM results WHERE ${conditions.join(" AND ")} ORDER BY id`).all(...params) as Array<
+    Omit<StoredStepResult, "assertions" | "captures" | "provenance"> & {
+      assertions: string | null;
+      captures: string | null;
+      provenance: string | null;
+    }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+    provenance: parseProvenance(row.provenance),
+  }));
+}