@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/setup/scanbuild.ts

@@ -0,0 +1,168 @@
+// The scan agent build and the settings a scan runs with.
+//
+// A scan's leaves are the production lenses — `pass-scan` for stage 1, the
+// validator when `[scan] validator` is on (the default: the scan validator is
+// the skeptic, composed with the `mode: "scan"` `scan-skeptic-validate`
+// addendum and run at the tier of the lens it judges, so every tier's variant
+// is built), and stage 2's deep lenses (every suggestible lens the profile
+// leaves on, at the tier its row names) — built by the one agent build
+// (`packages/pi-plugin/src/include.ts buildAgents`) in `"scan"` mode:
+//
+//   * the scan-mode anchor addendum composes (`mode: "scan"` in PASS_ADDENDA)
+//     — in this build and in no other: the daemon's, the bench's and the
+//     replay's builds are `"pr"` builds and never carry it;
+//   * `agents/scan/` joins `agents/` as a source, so `pass-scan` exists here
+//     and nowhere else;
+//   * every variant's tools are `SCAN_LEAF_TOOLS` — a scan leaf runs with no
+//     extensions, so there is no bash guard to stand between it and a shell;
+//   * a DEEP scan (`[scan] depth = "deep"`, or a stage-2 proposal made deep)
+//     also composes the `depth: "deep"` addenda: `scan-deep-suggest` on
+//     `pass-scan` (a deep lens named for every focus file) and `scan-deep-dig`
+//     on every lens a scan may run (follow callers and siblings, the state ×
+//     obligation table, what each early exit drops). A standard scan build is
+//     byte-identical without them.
+//
+// Everything a PR build composes from the repo's profile composes here too
+// (the pack, the per-lens emphasis/ceiling/guide, a lens's `effort`), so a
+// scan reviews the way this repo's PR rounds do. `pass-scan` itself is tuned
+// by `[scan] tier`/`effort`, config.toml's defaults under the profile's
+// `[scan]` table — the profile wins.
+//
+// The build lands in `<state home>/scan/agents/`, which the scan's case
+// runner reads; it is rebuilt at every start, so a profile edit reaches the
+// next run without anything else to remember.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseConfig, type Config } from "../config.js";
+import { homeProfileLookup, locateConfig } from "../install.js";
+import {
+  PASS_ADDENDA,
+  buildAgents,
+  configAddenda,
+  identityVars,
+  type BuiltAgent,
+} from "@quickchatai/pi-quickreview/src/include.js";
+import {
+  applyProfileTuning,
+  effortSpec,
+  lensModelOverrides,
+  lensTuningAddenda,
+} from "@quickchatai/pi-quickreview/src/lenstuning.js";
+import { PASS_TIER_ORDER } from "@quickchatai/pi-quickreview/src/types.js";
+import {
+  applyProfileScan,
+  loadProfileAddenda,
+  loadProfileEcosystem,
+  loadProfileLensTuning,
+  loadProfileScan,
+  type ProfileLookup,
+} from "@quickchatai/pi-quickreview/src/profiles.js";
+import type { Refusal } from "./engine.js";
+import { SCAN_PASS } from "./scan.js";
+import type { ScanSettings } from "./scanrun.js";
+
+/** Where the scan build lands, relative to the state home. */
+export const SCAN_AGENTS_DIR = "scan/agents";
+
+/** The scan-only lens sources, relative to the app's root. */
+export const SCAN_AGENTS_SRC = "agents/scan";
+
+/** The config a scan runs with: config.toml parsed, the profile's per-lens
+ * tuning and `[scan]` overrides applied (the profile wins). Throws on a bad
+ * config or profile — the caller reports it. */
+export function scanConfig(
+  root: string,
+  toml: string,
+  lookup: ProfileLookup = homeProfileLookup(),
+): Config {
+  const parsed = parseConfig(toml);
+  const profile = parsed.review.profile;
+  const tuned = applyProfileTuning(parsed, loadProfileLensTuning(root, profile, lookup));
+  return applyProfileScan(tuned, loadProfileScan(root, profile, lookup));
+}
+
+/** The live config (the install locator's answer), as `scanConfig` reads
+ * it — or why it cannot be read. Never `loadConfig`: that also demands the
+ * Slack token files, which the companion does not mount. */
+export function loadScanConfig(
+  root: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { ok: true; cfg: Config } | Refusal {
+  let path: string;
+  try {
+    path = locateConfig({ env }).path;
+  } catch (err) {
+    return { ok: false, errors: [`no live config: ${String(err)}`] };
+  }
+  let toml: string;
+  try {
+    toml = readFileSync(path, "utf8");
+  } catch (err) {
+    return { ok: false, errors: [`the live config ${path} cannot be read: ${String(err)}`] };
+  }
+  try {
+    return { ok: true, cfg: scanConfig(root, toml, homeProfileLookup(env)) };
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [
+        `the live config or its profile is invalid: ${err instanceof Error ? err.message : String(err)}`,
+      ],
+    };
+  }
+}
+
+/** The settings a scan run takes from a resolved config. */
+export function scanSettings(cfg: Config): ScanSettings {
+  return {
+    scan: cfg.scan,
+    // Stage 2: which deep lenses run, at which tiers and effort —
+    // the same per-lens tuning the build composes.
+    lenses: cfg.lenses,
+    riskPasses: cfg.models.risk_passes,
+  };
+}
+
+/** `pass-scan`'s model spec: the `[scan] tier`'s spec at `[scan] effort`
+ * (`high` = the model's ceiling), through the same per-variant hook a
+ * lens's `effort` uses. One variant — stage 1 runs at that tier alone. */
+export function scanPassModels(cfg: Pick<Config, "models" | "scan">): Record<string, string> {
+  return {
+    [`${SCAN_PASS}--${cfg.scan.tier}`]: effortSpec(cfg.models, cfg.scan.tier, cfg.scan.effort),
+  };
+}
+
+/** Build the scan agents into `outDir` — `buildAgents` in `"scan"` mode at
+ * `cfg.scan.depth`, the profile's pack and tuning composed exactly as a PR
+ * build composes them. */
+export function buildScanAgents(
+  root: string,
+  outDir: string,
+  cfg: Config,
+  lookup: ProfileLookup = homeProfileLookup(),
+): BuiltAgent[] {
+  return buildAgents(join(root, "agents"), outDir, {
+    root,
+    mode: "scan",
+    scanDepth: cfg.scan.depth,
+    extraSrcDirs: [join(root, SCAN_AGENTS_SRC)],
+    tiers: cfg.models.tiers,
+    riskPasses: cfg.models.risk_passes,
+    // The skeptic runs at the tier of the lens it judges — stage 1's
+    // `[scan] tier`, a stage-2 row's own — so every tier keeps a variant
+    // (never `validate_tier`, never floored upward).
+    validateTier: PASS_TIER_ORDER[0],
+    vars: identityVars(cfg),
+    ecosystem: loadProfileEcosystem(root, cfg.review.profile, lookup),
+    models: { ...lensModelOverrides(cfg.models, cfg.lenses), ...scanPassModels(cfg) },
+    // Stage 1 runs `pass-scan--<[scan] tier>` and nothing else names it
+    // (stage 2 rows refuse it), so no other tier's variant is built.
+    onlyTiers: { [SCAN_PASS]: [cfg.scan.tier] },
+    addenda: [
+      ...PASS_ADDENDA,
+      ...configAddenda(cfg.review),
+      ...loadProfileAddenda(root, cfg.review.profile, lookup),
+      ...lensTuningAddenda(cfg.lenses),
+    ],
+  });
+}

package/src/setup/scanfacts.ts

@@ -0,0 +1,107 @@
+// What the scan adds to the repo portrait: after a scan, the portrait's facts carry
+// what it FOUND — the last finished scan, the findings by unit and state, and
+// the per-unit hotspots the companion wrote to scan memory — so a later
+// re-tune (retune.ts) and the narrative both read the scan, not only the repo.
+//
+// Read from the state home's own scan records, never recomputed: the run
+// record (scanrun.ts), the findings store (findings.ts) and the scan memory
+// ledger (triage.ts). Counts only — no claim, no line, no fingerprint: the
+// portrait is a summary, and individual findings stay in the findings store.
+// A record that cannot be read makes the section UNKNOWN (and says why in the
+// facts' problems), never "no findings".
+import type { StateFs } from "./engine.js";
+import { FindingsStore } from "./findings.js";
+import type { PortraitScan, ScanUnitFacts } from "./portrait.js";
+import { SEVERITIES } from "./scan.js";
+import { isOpenFinding } from "./scanreport.js";
+import { finishedRuns } from "./scanrun.js";
+import { readScanMemory } from "./triage.js";
+
+/**
+ * The portrait's scan section, or null when nothing was ever scanned (no
+ * finished run, no stored finding) — a portrait from before the first scan
+ * is exactly what it was. `problems` lists the records that could not be read.
+ */
+export function scanFacts(state: StateFs): { scan: PortraitScan | null; problems: string[] } {
+  const problems: string[] = [];
+  const runs = finishedRuns(state);
+  if (runs.error !== null) problems.push(runs.error);
+  const stored = new FindingsStore(state).load();
+  if (stored.error !== null) problems.push(stored.error);
+  const memory = readScanMemory(state);
+  if (memory.error !== null) problems.push(memory.error);
+  const last = runs.runs[0] ?? null;
+  if (problems.length === 0 && last === null && stored.findings.length === 0)
+    return { scan: null, problems };
+
+  const bySeverity: Record<string, number> = {};
+  const units = new Map<string, ScanUnitFacts & { by: Set<string> }>();
+  const totals = { open: 0, promoted: 0, dismissed: 0, fixed: 0, doubted: 0 };
+  for (const f of stored.findings) {
+    const u = units.get(f.unit) ?? {
+      unit: f.unit,
+      open: 0,
+      promoted: 0,
+      dismissed: 0,
+      fixed: 0,
+      doubted: 0,
+      open_by: [],
+      by: new Set<string>(),
+    };
+    units.set(f.unit, u);
+    const open = isOpenFinding(f);
+    if (open) {
+      u.open++;
+      totals.open++;
+      bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+      u.by.add(`${f.severity} ${f.lens}`);
+      if (f.doubt) {
+        u.doubted++;
+        totals.doubted++;
+      }
+    }
+    if (f.state === "promoted" || f.state === "dismissed" || f.state === "fixed") {
+      u[f.state]++;
+      totals[f.state]++;
+    }
+  }
+  const rank = (s: string): number => {
+    const i = (SEVERITIES as readonly string[]).indexOf(s.split(" ")[0]!);
+    return i < 0 ? SEVERITIES.length : i;
+  };
+  const unitFacts: ScanUnitFacts[] = [...units.values()]
+    .sort((a, b) => a.unit.localeCompare(b.unit))
+    .map(({ by, ...u }) => ({
+      ...u,
+      open_by: [...by].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)),
+    }));
+
+  // The latest hotspot per unit, across every scan that wrote one.
+  const hot = new Map<string, { unit: string; text: string; sha: string; at: string }>();
+  for (const [sha, rec] of Object.entries(memory.file.scans)) {
+    for (const [unit, h] of Object.entries(rec?.hotspots ?? {})) {
+      if (typeof h?.text !== "string") continue;
+      const at = typeof h.at === "string" ? h.at : "";
+      const cur = hot.get(unit);
+      if (!cur || at > cur.at) hot.set(unit, { unit, text: h.text, sha, at });
+    }
+  }
+
+  return {
+    scan: {
+      state: problems.length === 0 ? "ok" : "unreadable",
+      last: last
+        ? {
+            id: last.id,
+            mode: last.mode,
+            sha: last.sha,
+            state: last.state,
+            finished_at: last.finished_at,
+          }
+        : null,
+      findings: { ...totals, by_severity: bySeverity, units: unitFacts },
+      hotspots: [...hot.values()].sort((a, b) => a.unit.localeCompare(b.unit)),
+    },
+    problems,
+  };
+}

package/src/setup/scanlease.ts

@@ -0,0 +1,297 @@
+// The scan driver lease: which process drives the scan in flight, across
+// processes. A ScanRunner knows its OWN run (`active`); a run recorded as
+// `running` that this runner does not drive is either interrupted or driven
+// by another process sharing the state home — the companion, or a
+// `qcr scan start` driver. The lease tells them apart: the driving runner
+// holds it and renews it while it drives; a holder that stopped renewing
+// (killed, its machine asleep) has let it lapse, and its run reads as
+// interrupted again.
+//
+// The lease is a sequence of GENERATIONS, `scan/driver/<n>.json`, the highest
+// one current. A claim creates the next generation with an exclusive create
+// (the record is written aside and hard-linked into place, which fails when
+// the name exists — or, on a filesystem that refuses hard links, an O_EXCL
+// create), so of any number of processes claiming at once exactly one wins
+// each generation; the winner then checks no newer generation appeared before
+// it takes the lease. A holder renews only its own generation; once a newer
+// one exists (its lease lapsed and was taken over) it no longer holds the
+// lease, and renewal says so. An unreadable current generation (an O_EXCL
+// create not yet written, or a corrupt file) counts as live until its file is
+// as old as the lease's life, then as no lease. A claim prunes every
+// generation but the one before its own, and temp files older than the
+// lease's life.
+//
+// What the lease does NOT serialise: the records other processes may write
+// while a run is driven elsewhere. `qcr scan match` / `dismiss` and the
+// companion's triage rewrite `scan/findings.json`, and a driver's reconcile
+// does too, each as a fresh read, a change and a write — between one
+// process's read and its write another's write can be lost. The run record
+// `scan/run.json` is written only by the lease holder; a holder that lost the
+// lease stops its run and writes it no more (scanrun.ts).
+//
+// A leaf: node built-ins only, so the TUI's scan tab reads the lease too.
+import { randomUUID } from "node:crypto";
+import {
+  linkSync,
+  statSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+export const DRIVER_DIR = "scan/driver";
+/** How often a driving runner renews its lease. */
+export const LEASE_RENEW_MS = 5_000;
+/** A lease not renewed for this long has lapsed. */
+export const LEASE_TTL_MS = 30_000;
+
+export interface LeaseRecord {
+  holder: string;
+  /** The run it drives; null while a start is still planning. */
+  run: string | null;
+  pid: number;
+  host: string;
+  at: string;
+}
+
+/** The lease port a ScanRunner drives. */
+export interface ScanLease {
+  /** This runner's holder id. */
+  readonly holder: string;
+  /** Take the lease for `run` — or renew it when this runner holds it
+   * already; false when another live holder has it, or another claim won. */
+  claim(run: string | null): boolean;
+  /** Renew the lease this runner holds; false when it holds none any more. */
+  renew(run: string | null): boolean;
+  /** Give the lease up — only when this runner still holds it. */
+  release(): void;
+  /** Why the last claim failed, when it was not another holder's live lease. */
+  readonly lastError: string | null;
+  /** The live lease of ANOTHER holder, or null. */
+  other(): LeaseRecord | null;
+}
+
+function parse(text: string): LeaseRecord | null {
+  try {
+    const r = JSON.parse(text) as Partial<LeaseRecord>;
+    if (typeof r.holder !== "string" || typeof r.at !== "string") return null;
+    return {
+      holder: r.holder,
+      run: typeof r.run === "string" ? r.run : null,
+      pid: typeof r.pid === "number" ? r.pid : 0,
+      host: typeof r.host === "string" ? r.host : "",
+      at: r.at,
+    };
+  } catch {
+    return null;
+  }
+}
+
+const GEN = /^(\d+)\.json$/;
+
+/** Has the file at `path` been written within the lease's life? Files carry
+ * the real clock's mtime, so this reads the real clock. */
+function fresh(path: string): boolean {
+  try {
+    return Date.now() - statSync(path).mtimeMs < LEASE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+const errText = (err: unknown): string =>
+  err instanceof Error
+    ? `${(err as NodeJS.ErrnoException).code ?? "error"}: ${err.message}`
+    : String(err);
+
+/** Where a hard link is refused rather than the name taken. */
+const NO_LINK = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+
+/** The current generation and its record (null: unreadable), or null when
+ * there is no lease at all. */
+function current(dir: string): { gen: number; record: LeaseRecord | null } | null {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const gens = names.flatMap((n) => {
+    const m = GEN.exec(n);
+    return m ? [Number(m[1])] : [];
+  });
+  if (gens.length === 0) return null;
+  const gen = Math.max(...gens);
+  let record: LeaseRecord | null = null;
+  try {
+    record = parse(readFileSync(join(dir, `${gen}.json`), "utf8"));
+  } catch {
+    record = null;
+  }
+  return { gen, record };
+}
+
+const isLive = (r: LeaseRecord, now: Date): boolean => {
+  const at = Date.parse(r.at);
+  return Number.isFinite(at) && now.getTime() - at < LEASE_TTL_MS;
+};
+
+/** The current lease record under the state home `home`, live or not —
+ * null when there is none or it cannot be read. For a reader that holds
+ * none (the TUI), which judges it with `leaseIsLive`. */
+export function currentLease(home: string): LeaseRecord | null {
+  return current(join(home, DRIVER_DIR))?.record ?? null;
+}
+
+export const leaseIsLive = (r: LeaseRecord, now: Date = new Date()): boolean => isLive(r, now);
+
+/** The live lease under the state home `home`, or null. */
+export function liveLease(home: string, now: Date = new Date()): LeaseRecord | null {
+  const r = currentLease(home);
+  return r && isLive(r, now) ? r : null;
+}
+
+/** The lease as generation files under the state home `home`. Total: a
+ * failed write is a failed claim or renewal, never a throw. */
+export function fileLease(
+  home: string,
+  opts: {
+    clock?: () => Date;
+    holder?: string;
+    /** Called between reading the lease and creating the next generation. */
+    beforeCreate?: () => void;
+    /** Called right after generation `gen` was created, before the check
+     * that no newer one appeared. */
+    afterCreate?: (gen: number) => void;
+    /** The hard link (`fs.linkSync`). */
+    link?: (existing: string, path: string) => void;
+  } = {},
+): ScanLease {
+  const dir = join(home, DRIVER_DIR);
+  const clock = opts.clock ?? (() => new Date());
+  const holder = opts.holder ?? `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+  const link = opts.link ?? linkSync;
+  let mine: number | null = null;
+  let lastError: string | null = null;
+  const record = (run: string | null, at = clock()): string =>
+    `${JSON.stringify({ holder, run, pid: process.pid, host: hostname(), at: at.toISOString() })}\n`;
+  // Only its holder rewrites a generation: tmp + rename.
+  const rewrite = (gen: number, text: string): boolean => {
+    const tmp = join(dir, `.${gen}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(tmp, text);
+      renameSync(tmp, join(dir, `${gen}.json`));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const prune = (below: number): void => {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const m = GEN.exec(name);
+      const stale =
+        (m !== null && Number(m[1]) < below) ||
+        (name.startsWith(".") && name.endsWith(".tmp") && !fresh(join(dir, name)));
+      if (!stale) continue;
+      try {
+        unlinkSync(join(dir, name));
+      } catch {
+        // Another claimer pruned it first.
+      }
+    }
+  };
+  /** Create generation `gen` exclusively; null, or why not. */
+  const create = (gen: number, text: string): string | null => {
+    const path = join(dir, `${gen}.json`);
+    const tmp = join(dir, `.claim.${randomUUID()}.tmp`);
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(tmp, text);
+      try {
+        link(tmp, path);
+        return null;
+      } catch (err) {
+        if (!NO_LINK.has((err as NodeJS.ErrnoException).code ?? "")) throw err;
+      }
+      writeFileSync(path, text, { flag: "wx" });
+      return null;
+    } catch (err) {
+      return errText(err);
+    } finally {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Never written.
+      }
+    }
+  };
+  const lease: ScanLease = {
+    holder,
+    get lastError() {
+      return lastError;
+    },
+    claim(run) {
+      lastError = null;
+      const cur = current(dir);
+      if (cur !== null && mine === cur.gen) return lease.renew(run);
+      if (cur !== null && cur.record === null && fresh(join(dir, `${cur.gen}.json`))) {
+        lastError = `generation ${cur.gen} is unreadable and was written within the lease's life — it may still be being written`;
+        return false;
+      }
+      if (cur?.record && cur.record.holder !== holder && isLive(cur.record, clock())) return false;
+      opts.beforeCreate?.();
+      const gen = (cur?.gen ?? 0) + 1;
+      const failed = create(gen, record(run));
+      if (failed !== null) {
+        lastError = `generation ${gen} could not be created (${failed})`;
+        return false;
+      }
+      opts.afterCreate?.(gen);
+      // Won the create; still the newest?
+      if (current(dir)?.gen !== gen) {
+        lastError = `a newer generation than ${gen} appeared as it was created`;
+        return false;
+      }
+      mine = gen;
+      prune(gen - 1);
+      return true;
+    },
+    renew(run) {
+      const cur = current(dir);
+      if (
+        mine === null ||
+        cur === null ||
+        cur.gen !== mine ||
+        cur.record === null ||
+        !isLive(cur.record, clock())
+      ) {
+        mine = null;
+        return false;
+      }
+      return rewrite(mine, record(run));
+    },
+    release() {
+      const cur = current(dir);
+      if (mine !== null && cur !== null && cur.gen === mine)
+        rewrite(mine, record(null, new Date(0)));
+      mine = null;
+    },
+    other() {
+      const cur = current(dir);
+      if (cur === null || cur.record === null || cur.gen === mine) return null;
+      return isLive(cur.record, clock()) ? cur.record : null;
+    },
+  };
+  return lease;
+}