@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/workspace/manifest.ts

@@ -1,283 +0,0 @@
-/**
- * `.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

@@ -1,62 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-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/          — runtime state subdir (holds zond.db, current-api, …)
- *   apis/           — collections directory
- */
-export const WORKSPACE_MARKERS = ["zond.config.yml", ".zond", "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 must be a file
-    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` 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 {
-  // Explicit override for headless/CI/workflow runs: skip walk-up entirely and
-  // anchor the workspace at ZOND_WORKSPACE. Lets each run own an isolated root
-  // (its own .zond/zond.db, apis/) without depending on cwd or a parent marker.
-  const override = process.env.ZOND_WORKSPACE?.trim();
-  if (override) {
-    return { root: resolve(override), marker: "", fromFallback: false };
-  }
-
-  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 };
-}
-
-/** Test helper: reset the one-shot warning latch. */
-export function _resetWorkspaceWarning(): void {
-  warned = false;
-}

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

@@ -1,87 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-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,
-  );
-}