@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/workspace/manifest.ts

@@ -0,0 +1,283 @@
+/**
+ * `.zond/manifest.json` — auto-generated file tracking (TASK-156, m-9).
+ *
+ * Every command that writes files into the workspace appends an entry
+ * here so `zond clean` can later remove only what zond produced, leaving
+ * user edits intact (sha256 mismatch → manually-edited → skipped).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const MANIFEST_VERSION = 1;
+const MANIFEST_RELPATH = ".zond/manifest.json";
+
+export type ManifestCategory =
+  | "spec"
+  | "catalog"
+  | "resources"
+  | "fixtures"
+  | "env"
+  | "tests"
+  | "probes"
+  | "other";
+
+export interface ManifestEntry {
+  /** Workspace-relative POSIX path. */
+  path: string;
+  /** sha256 of the file contents at write-time. */
+  sha256: string;
+  /** Command that emitted the file (e.g. "zond generate", "zond probe-validation --emit"). */
+  by: string;
+  /** ISO 8601 timestamp. */
+  ts: string;
+  /** API name when applicable (used by `zond clean --api <name>`). */
+  api?: string;
+  /** Logical category for `zond clean --probes` etc. */
+  category?: ManifestCategory;
+}
+
+export interface Manifest {
+  version: number;
+  generated: ManifestEntry[];
+}
+
+function getManifestPath(workspaceRoot: string): string {
+  return join(workspaceRoot, MANIFEST_RELPATH);
+}
+
+export function loadManifest(workspaceRoot: string): Manifest {
+  const p = getManifestPath(workspaceRoot);
+  if (!existsSync(p)) return { version: MANIFEST_VERSION, generated: [] };
+  try {
+    const raw = readFileSync(p, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.generated)) {
+      return { version: MANIFEST_VERSION, generated: [] };
+    }
+    return {
+      version: typeof parsed.version === "number" ? parsed.version : MANIFEST_VERSION,
+      generated: parsed.generated as ManifestEntry[],
+    };
+  } catch {
+    return { version: MANIFEST_VERSION, generated: [] };
+  }
+}
+
+function saveManifest(workspaceRoot: string, manifest: Manifest): void {
+  const p = getManifestPath(workspaceRoot);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+/** Workspace-relative POSIX path. */
+export function toWorkspacePath(workspaceRoot: string, filePath: string): string {
+  const abs = isAbsolute(filePath) ? filePath : resolve(filePath);
+  let rel = relative(workspaceRoot, abs);
+  if (sep === "\\") rel = rel.split(sep).join("/");
+  return rel;
+}
+
+export function sha256OfFile(filePath: string): string | null {
+  try {
+    const buf = readFileSync(filePath);
+    return createHash("sha256").update(buf).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function sha256OfString(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export interface RecordInput {
+  /** Absolute or workspace-relative path of the file just written. */
+  path: string;
+  by: string;
+  api?: string;
+  category?: ManifestCategory;
+  /** Pre-computed sha256; if absent, the file is read from disk. */
+  sha256?: string;
+}
+
+/**
+ * Append (or replace) entries in the manifest. Existing entries with the
+ * same `path` are replaced so re-running a generator updates the hash
+ * instead of accumulating duplicates.
+ */
+export function recordGeneratedFiles(workspaceRoot: string, entries: RecordInput[]): void {
+  if (entries.length === 0) return;
+  const ts = new Date().toISOString();
+  const accepted: ManifestEntry[] = [];
+
+  for (const e of entries) {
+    const abs = isAbsolute(e.path) ? e.path : resolve(workspaceRoot, e.path);
+    const rel = toWorkspacePath(workspaceRoot, abs);
+    // Refuse to record paths that escape the workspace — happens when tests
+    // run setupApi from a tmp dir but findWorkspaceRoot walks up to the host
+    // project root. Without this guard, a `../../../tmp/...` entry pollutes
+    // the host workspace's manifest.
+    if (rel.startsWith("..") || isAbsolute(rel)) continue;
+    const sha = e.sha256 ?? sha256OfFile(abs);
+    if (!sha) continue; // file vanished; skip
+    accepted.push({
+      path: rel,
+      sha256: sha,
+      by: e.by,
+      ts,
+      api: e.api,
+      category: e.category,
+    });
+  }
+
+  // Don't touch disk when nothing applied to this workspace — keeps tests
+  // (which run from /tmp but inherit the host's workspace root) from
+  // creating an empty `.zond/manifest.json` in the dev repo.
+  if (accepted.length === 0) return;
+
+  const manifest = loadManifest(workspaceRoot);
+  const byPath = new Map<string, ManifestEntry>();
+  for (const e of manifest.generated) byPath.set(e.path, e);
+  for (const e of accepted) byPath.set(e.path, e);
+
+  manifest.version = MANIFEST_VERSION;
+  manifest.generated = [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+  saveManifest(workspaceRoot, manifest);
+}
+
+export function recordGeneratedFile(workspaceRoot: string, entry: RecordInput): void {
+  recordGeneratedFiles(workspaceRoot, [entry]);
+}
+
+export interface CleanFilter {
+  api?: string;
+  category?: ManifestCategory;
+  /** When true, include all entries regardless of api/category. */
+  all?: boolean;
+}
+
+export interface SelectEntriesResult {
+  selected: ManifestEntry[];
+  /** Entries that match `api` filter but were excluded because the user
+   *  did not explicitly opt into the `probes` category. Surfaced so the
+   *  CLI can hint at how to reach them (TASK-258). */
+  probesPreserved: ManifestEntry[];
+}
+
+export function selectEntries(manifest: Manifest, filter: CleanFilter): ManifestEntry[] {
+  return selectEntriesEx(manifest, filter).selected;
+}
+
+export function selectEntriesEx(manifest: Manifest, filter: CleanFilter): SelectEntriesResult {
+  const selected: ManifestEntry[] = [];
+  const probesPreserved: ManifestEntry[] = [];
+  // TASK-258: when scoping by --api alone (no explicit --probes / --all),
+  // probes/ belongs to a separate pipeline (zond probe-validation/-methods)
+  // and re-generating it costs ~30s on a 200-endpoint spec. Treat it as
+  // out-of-scope and surface a hint instead of silently nuking suites.
+  const protectProbes = !!filter.api && filter.category !== "probes" && !filter.all;
+  for (const e of manifest.generated) {
+    // spec.json is the source-of-truth snapshot downloaded from the network.
+    // It is never auto-deleted — removal requires manual action or re-adding the API.
+    if (e.category === "spec") continue;
+    if (filter.all) {
+      selected.push(e);
+      continue;
+    }
+    if (filter.api) {
+      const matchesApi = e.api === filter.api ||
+        e.path.startsWith(`apis/${filter.api}/`);
+      if (!matchesApi) continue;
+    }
+    if (filter.category && e.category !== filter.category) continue;
+    if (protectProbes && e.category === "probes") {
+      probesPreserved.push(e);
+      continue;
+    }
+    selected.push(e);
+  }
+  return { selected, probesPreserved };
+}
+
+export type CleanVerdict = "delete" | "modified" | "missing";
+
+export interface CleanItem {
+  entry: ManifestEntry;
+  absPath: string;
+  verdict: CleanVerdict;
+  /** Current sha256 if file exists. */
+  currentSha256?: string;
+}
+
+export function inspectEntries(workspaceRoot: string, entries: ManifestEntry[]): CleanItem[] {
+  const items: CleanItem[] = [];
+  for (const entry of entries) {
+    const abs = resolve(workspaceRoot, entry.path);
+    if (!existsSync(abs)) {
+      items.push({ entry, absPath: abs, verdict: "missing" });
+      continue;
+    }
+    const cur = sha256OfFile(abs);
+    if (cur && cur !== entry.sha256) {
+      items.push({ entry, absPath: abs, verdict: "modified", currentSha256: cur });
+    } else {
+      items.push({ entry, absPath: abs, verdict: "delete", currentSha256: cur ?? undefined });
+    }
+  }
+  return items;
+}
+
+/**
+ * Drop entries from the manifest by absolute or workspace-relative path.
+ */
+export function removeManifestEntries(workspaceRoot: string, paths: string[]): void {
+  if (paths.length === 0) return;
+  const manifest = loadManifest(workspaceRoot);
+  const drop = new Set(paths.map((p) => toWorkspacePath(workspaceRoot, p)));
+  manifest.generated = manifest.generated.filter((e) => !drop.has(e.path));
+  saveManifest(workspaceRoot, manifest);
+}
+
+/** True when the workspace has a manifest file. */
+export function hasManifest(workspaceRoot: string): boolean {
+  return existsSync(getManifestPath(workspaceRoot));
+}
+
+/**
+ * Header comment prepended to every YAML/MD file zond writes, so a human
+ * opening the file sees who wrote it and how to regenerate it. Pair with
+ * `recordGeneratedFile` for the machine-readable audit trail.
+ */
+export function autoGenHeader(by: string, regenerate?: string): string {
+  const lines = [
+    `# Auto-generated by ${by}.`,
+    `# ⚠️ Edits will be overwritten on regenerate. Drop from .zond/manifest.json (or rename) to keep changes.`,
+  ];
+  if (regenerate) lines.push(`# Regenerate: ${regenerate}`);
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Best-effort: derive the API name from a path like `apis/<name>/tests`.
+ * Returns undefined for non-conventional layouts so manifest entries stay
+ * un-tagged rather than mis-tagged.
+ */
+export function inferApiName(outputDir: string): string | undefined {
+  const norm = outputDir.replace(/\\/g, "/");
+  const m = norm.match(/(?:^|\/)apis\/([^/]+)(?:\/|$)/);
+  return m?.[1];
+}
+
+/** Cheap sanity check used by zond doctor — true when path lives in workspace. */
+function isWithinWorkspace(workspaceRoot: string, candidate: string): boolean {
+  const abs = isAbsolute(candidate) ? candidate : resolve(workspaceRoot, candidate);
+  try {
+    statSync(abs);
+  } catch {
+    return false;
+  }
+  const rel = relative(workspaceRoot, abs);
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}

package/src/core/workspace/output-rotation.ts

@@ -0,0 +1,62 @@
+/**
+ * Auto-rotate `--output <path>` targets so a second `zond report ...` (or
+ * `zond probe-* --output ...`) does not silently clobber the previous
+ * artifact (TASK-162, m-9 P6).
+ *
+ * Strategy: when `path` already exists, rename it to `<basename>-vN<ext>`
+ * with the smallest free N (≥ 2) and return that rotation info so the
+ * caller can print it. The `--overwrite` flag short-circuits to no-op so
+ * users keep the previous behaviour when they explicitly ask for it.
+ */
+
+import { existsSync, renameSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+
+export interface RotationResult {
+  /** The path that was renamed (the old artifact). undefined when no rotation happened. */
+  rotatedFrom?: string;
+  /** Where the old artifact moved to. undefined when no rotation happened. */
+  rotatedTo?: string;
+  /** True when caller asked for `--overwrite` (or the target didn't exist). */
+  overwrite: boolean;
+}
+
+export interface RotateOptions {
+  /** When true, skip rotation entirely (overwrite-in-place). */
+  overwrite?: boolean;
+  /** Optional callback for the human-facing notice; defaults to stderr. */
+  notice?: (msg: string) => void;
+}
+
+/**
+ * Rename `targetPath` to `<base>-vN<ext>` if it exists and `--overwrite`
+ * is not set. Returns rotation info; the caller is responsible for
+ * actually writing the new artifact at `targetPath`.
+ */
+export function rotateOutputTarget(targetPath: string, opts: RotateOptions = {}): RotationResult {
+  if (opts.overwrite) return { overwrite: true };
+  if (!existsSync(targetPath)) return { overwrite: false };
+
+  const dir = dirname(targetPath);
+  const ext = extname(targetPath);
+  const stem = basename(targetPath, ext);
+  // Strip an existing `-vN` suffix from the stem so successive rotations
+  // produce `digest-v2.md`, `digest-v3.md` rather than
+  // `digest-v2-v2.md` etc.
+  const stemBare = stem.replace(/-v\d+$/, "");
+
+  let n = 2;
+  while (n < 1000) {
+    const candidate = join(dir, `${stemBare}-v${n}${ext}`);
+    if (!existsSync(candidate)) {
+      renameSync(targetPath, candidate);
+      const notice = opts.notice ?? ((m: string) => process.stderr.write(m + "\n"));
+      notice(`Previous artifact moved to ${candidate}`);
+      return { rotatedFrom: targetPath, rotatedTo: candidate, overwrite: false };
+    }
+    n++;
+  }
+  // Pathological: 1000 versions exist. Fall back to overwrite to avoid
+  // an infinite-loop UX failure.
+  return { overwrite: true };
+}

package/src/core/workspace/root.ts

@@ -0,0 +1,94 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Files / directories that mark a workspace root. Order matters — earlier
+ * markers win when more than one is present in the same directory.
+ *
+ *   zond.config.yml — explicit project config (T12)
+ *   .zond/          — `zond init --here` subdir convention (T19)
+ *   zond.db         — flat layout from `zond init`
+ *   apis/           — flat layout (collections directory)
+ */
+export const WORKSPACE_MARKERS = ["zond.config.yml", ".zond", "zond.db", "apis"] as const;
+export type WorkspaceMarker = (typeof WORKSPACE_MARKERS)[number];
+
+export interface WorkspaceInfo {
+  /** Absolute path to the workspace root. */
+  root: string;
+  /** Marker that triggered detection, or "" when fallback (cwd) was used. */
+  marker: WorkspaceMarker | "";
+  /** True when no marker was found and we fell back to `cwd`. */
+  fromFallback: boolean;
+}
+
+let warned = false;
+
+function hasMarker(dir: string): WorkspaceMarker | null {
+  for (const m of WORKSPACE_MARKERS) {
+    const p = join(dir, m);
+    if (!existsSync(p)) continue;
+    // .zond and apis must be directories; zond.config.yml and zond.db must be files
+    try {
+      const st = statSync(p);
+      if (m === ".zond" || m === "apis") {
+        if (st.isDirectory()) return m;
+      } else if (st.isFile()) {
+        return m;
+      }
+    } catch {
+      /* race / permissions — treat as no marker */
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk-up from `cwd` (default `process.cwd()`) to the nearest workspace
+ * marker. The walk stops at `os.homedir()` to avoid accidentally picking up
+ * `~/apis` or `~/zond.db` when the user runs zond from somewhere unrelated.
+ *
+ * When no marker is found, returns `{ root: cwd, fromFallback: true }` and
+ * prints a one-time stderr warning so the user knows zond is operating in
+ * cwd-mode.
+ */
+export function findWorkspaceRoot(cwd?: string): WorkspaceInfo {
+  const start = resolve(cwd ?? process.cwd());
+  const stop = resolve(homedir());
+
+  let dir = start;
+  // Walk strictly while above (or equal to) HOME's length, but include HOME
+  // itself as a candidate only when start is inside HOME. If start is outside
+  // HOME (e.g. /tmp), walk all the way to "/".
+  const insideHome = start === stop || start.startsWith(stop + "/") || start.startsWith(stop + "\\");
+
+  while (true) {
+    const marker = hasMarker(dir);
+    if (marker) return { root: dir, marker, fromFallback: false };
+
+    const parent = dirname(dir);
+    if (parent === dir) break;                 // filesystem root
+    if (insideHome && dir === stop) break;     // do not climb past HOME
+    dir = parent;
+  }
+
+  if (!warned) {
+    warned = true;
+    process.stderr.write(
+      `[zond] no workspace marker found from ${start}; using cwd. ` +
+      `Run 'zond init' or create zond.config.yml to anchor the workspace.\n`,
+    );
+  }
+  return { root: start, marker: "", fromFallback: true };
+}
+
+/** Resolve `relative` against the workspace root (auto-detected from `cwd`). */
+export function resolveWorkspacePath(relative: string, cwd?: string): string {
+  return resolve(findWorkspaceRoot(cwd).root, relative);
+}
+
+/** Test helper: reset the one-shot warning latch. */
+export function _resetWorkspaceWarning(): void {
+  warned = false;
+}

package/src/core/workspace/triage-path.ts

@@ -0,0 +1,87 @@
+/**
+ * Default `triage/` path for `--output` (TASK-163, m-9 P7).
+ *
+ * Rule: when the user runs a report-emitting command without `--output`,
+ * we drop the artifact into:
+ *
+ *     <workspace>/triage/<api|"adhoc">/<run-id>/<command>-<timestamp>.<ext>
+ *
+ * If they pass `--output some-filename.md` (no slash), that filename is
+ * used as the basename inside the same directory. An `--output` that
+ * includes a directory component is honoured verbatim.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { findWorkspaceRoot } from "./root.ts";
+
+export interface TriageOpts {
+  /** Logical command name — used in the auto-filename. */
+  command: string;
+  /** Run id (or undefined for ad-hoc artifacts). */
+  runId?: number | null;
+  /** API/collection name; falls back to `"adhoc"` when not known. */
+  api?: string | null;
+  /** Default extension (md / html / json). Without a leading dot. */
+  ext: string;
+  /** What the user typed in --output (may be undefined). */
+  userOutput?: string;
+  /** Optional explicit timestamp for tests. */
+  now?: Date;
+}
+
+export interface ResolvedTriagePath {
+  /** Absolute path to write. */
+  absolute: string;
+  /** Workspace-relative path for prettier console output. */
+  relative: string;
+  /** True when we landed under triage/ vs. honoured the user path. */
+  underTriage: boolean;
+}
+
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+
+function timestamp(d: Date): string {
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+export function resolveTriageOutput(opts: TriageOpts): ResolvedTriagePath {
+  const ws = findWorkspaceRoot();
+  const root = ws.root;
+  const ext = opts.ext.replace(/^\./, "");
+  const ts = timestamp(opts.now ?? new Date());
+  const apiSlug = opts.api ?? "adhoc";
+  const runSlug = opts.runId != null ? `run-${opts.runId}` : "adhoc";
+
+  // 1) User passed a path with a directory component → honour verbatim.
+  if (opts.userOutput && /[\\/]/.test(opts.userOutput)) {
+    const abs = isAbsolute(opts.userOutput) ? opts.userOutput : resolve(opts.userOutput);
+    mkdirSync(dirname(abs), { recursive: true });
+    return {
+      absolute: abs,
+      relative: relPath(abs, root),
+      underTriage: false,
+    };
+  }
+
+  // 2) Default location.
+  const dir = join(root, "triage", apiSlug, runSlug);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const basename = opts.userOutput ?? `${opts.command}-${ts}.${ext}`;
+  const abs = join(dir, basename);
+  return {
+    absolute: abs,
+    relative: relPath(abs, root),
+    underTriage: true,
+  };
+}
+
+function relPath(abs: string, root: string): string {
+  if (abs.startsWith(root)) {
+    const r = abs.slice(root.length).replace(/^[\\/]+/, "");
+    return r.replace(/\\/g, "/");
+  }
+  return abs;
+}

package/src/db/lint-runs.ts

@@ -0,0 +1,47 @@
+import type { Database } from "bun:sqlite";
+import type { Issue, LintConfig, LintStats } from "../core/lint/index.ts";
+
+export interface LintRunRow {
+  id: number;
+  spec_path: string;
+  started_at: string;
+  finished_at: string | null;
+  total: number;
+  high_count: number;
+  medium_count: number;
+  low_count: number;
+  endpoint_count: number;
+}
+
+export function createLintRun(db: Database, specPath: string): number {
+  const startedAt = new Date().toISOString();
+  const stmt = db.prepare(
+    "INSERT INTO lint_runs (spec_path, started_at) VALUES (?, ?)",
+  );
+  const info = stmt.run(specPath, startedAt) as { lastInsertRowid: number | bigint };
+  return Number(info.lastInsertRowid);
+}
+
+export function finalizeLintRun(
+  db: Database,
+  id: number,
+  issues: Issue[],
+  stats: LintStats,
+  config: LintConfig,
+): void {
+  db.prepare(
+    `UPDATE lint_runs SET
+      finished_at = ?,
+      total = ?, high_count = ?, medium_count = ?, low_count = ?,
+      endpoint_count = ?,
+      config_json = ?, issues_json = ?
+     WHERE id = ?`,
+  ).run(
+    new Date().toISOString(),
+    stats.total, stats.high, stats.medium, stats.low,
+    stats.endpoints,
+    JSON.stringify({ rules: config.rules, heuristics: config.heuristics, ignore_paths: config.ignore_paths }),
+    JSON.stringify(issues),
+    id,
+  );
+}