@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/live/read.ts

@@ -1,86 +0,0 @@
-// Finding and reading a round's LiveEvent logs: what `qcr review status` and
-// `qcr live` do with a run directory. No writer and no engine here, so a
-// daemon-side or TUI reader can import it.
-import { readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-import {
-  LIVE_MAIN_FILE,
-  readLiveEvents,
-  type LiveEvent,
-} from "@quickchatai/pi-quickreview/src/live/events.js";
-import { projectRoundProgress } from "./projection.js";
-import type { RoundProgressSnapshot } from "@quickchatai/pi-quickreview/src/round-progress.js";
-
-export interface LiveRoundRef {
-  /** `state/live/<key>/r<round>` */
-  dir: string;
-  key: string;
-  round: number;
-}
-
-const names = (dir: string): string[] => {
-  try {
-    return readdirSync(dir);
-  } catch {
-    return [];
-  }
-};
-
-/** Every round log directory under `<root>/state/live/`, oldest round first. */
-export function listLiveRounds(root: string): LiveRoundRef[] {
-  const base = join(root, "state", "live");
-  const found: LiveRoundRef[] = [];
-  for (const key of names(base)) {
-    for (const r of names(join(base, key))) {
-      const m = /^r(\d+)$/.exec(r);
-      if (m) found.push({ dir: join(base, key, r), key, round: Number(m[1]) });
-    }
-  }
-  return found.sort((a, b) => a.key.localeCompare(b.key) || a.round - b.round);
-}
-
-function mtime(path: string): number {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return 0;
-  }
-}
-
-/** The round that was written last. */
-export function latestLiveRound(root: string): LiveRoundRef | undefined {
-  return listLiveRounds(root).reduce<LiveRoundRef | undefined>(
-    (best, r) =>
-      best === undefined ||
-      mtime(join(r.dir, LIVE_MAIN_FILE)) >= mtime(join(best.dir, LIVE_MAIN_FILE))
-        ? r
-        : best,
-    undefined,
-  );
-}
-
-/** The ids of the lens sessions a round logged, in file-name order. */
-export function lensLogIds(dir: string): string[] {
-  return names(dir)
-    .flatMap((f) => /^lens-(.+)\.jsonl$/.exec(f)?.[1] ?? [])
-    .sort();
-}
-
-export interface RoundView {
-  ref: LiveRoundRef;
-  events: readonly LiveEvent[];
-  /** The round-progress v2 snapshot the main log projects to. */
-  snapshot: RoundProgressSnapshot | undefined;
-  lenses: string[];
-}
-
-/** Read one round's main log and project it. */
-export function viewRound(ref: LiveRoundRef): RoundView {
-  const { events } = readLiveEvents(join(ref.dir, LIVE_MAIN_FILE));
-  return {
-    ref,
-    events,
-    snapshot: projectRoundProgress(events)?.snapshot,
-    lenses: lensLogIds(ref.dir),
-  };
-}

package/src/onboard/launch.ts

@@ -1,115 +0,0 @@
-// `qcr onboard` mechanics: launch pi at the pinned version via npx
-// (pi stays a non-dependency — this works from a bare clone with only Node and
-// the checkout), hand it the onboarding system prompt + exactly one onboarding
-// extension + a restricted built-in tool set, and on exit either exec the TUI
-// (checklist complete) or say how to resume.
-//
-// Everything effectful is injected (spawn, completion read, log), so tests
-// drive the whole flow with fakes; src/cli.ts cmdOnboard is the one real
-// assembly.
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-export interface PiPin {
-  package: string;
-  version: string;
-}
-
-/** The pin from package.json's "qcrPi" block — the mirror that exists on a bare
- * public clone, where config.toml does not (the wizard writes it later).
- * config.toml [pi] stays the preferred source when it loads (cmdOnboard tries
- * it first); both mirror the same pinned version by rule 7's discipline. */
-export function piPinFromPackageJson(
-  root: string,
-  readFile: (p: string) => string = (p) => readFileSync(p, "utf8"),
-): PiPin | null {
-  try {
-    const pkg = JSON.parse(readFile(join(root, "package.json"))) as {
-      qcrPi?: { package?: unknown; version?: unknown };
-    };
-    const pi = pkg.qcrPi;
-    if (pi && typeof pi.package === "string" && typeof pi.version === "string") {
-      return { package: pi.package, version: pi.version };
-    }
-  } catch {
-    // fall through — the caller reports the missing pin
-  }
-  return null;
-}
-
-/** Dedicated onboarding session store — never the reviewer/companion dirs, so
- * onboarding cannot pollute (or be polluted by) any other pi session store. */
-export function onboardingSessionDir(root: string): string {
-  return join(root, "state", "onboarding", "pi-sessions");
-}
-
-/**
- * The full npx argv for the onboarding pi session.
- *
- * `--approve` is the same never-block-on-input rule as buildPiCommand
- * (src/sessions.ts) and the companion's piArgv: the wizard must never stall
- * on pi's interactive "Trust project folder?" modal.
- *
- * VERIFY-ON-PIN: `--no-extensions`, `--no-skills`, `--no-context-files`,
- * `-e <path>` and `--tools <list>` against the pinned pi version's --help —
- * the intent (no ambient extensions, exactly one onboarding extension, a
- * read-only built-in belt) is the design decision; the exact flag spellings
- * are unverified statically and belong to the named onboarding smoke step.
- */
-export function onboardingPiArgv(pin: PiPin, root: string): string[] {
-  return [
-    "npx",
-    "-y",
-    `${pin.package}@${pin.version}`,
-    "--approve",
-    "--no-extensions",
-    "--no-skills",
-    "--no-context-files",
-    "-e",
-    join(root, "extensions", "cli", "onboarding.ts"),
-    "--system-prompt",
-    join(root, "prompts", "onboarding.md"),
-    "--tools",
-    "read,ls,grep",
-    "--session-dir",
-    onboardingSessionDir(root),
-  ];
-}
-
-export interface OnboardRunDeps {
-  pin: PiPin;
-  root: string;
-  /** Spawn with stdio inherited; resolves with the exit code (a spawn failure
-   * is a nonzero code, never a throw). */
-  spawn(cmd: string, args: string[]): Promise<number>;
-  /** Does the checklist file say every step verified? (engine.checklistComplete
-   * over state/ — the finish tool only sets the flag after a green re-verify.) */
-  isComplete(): boolean;
-  log(line: string): void;
-  /** Compiled CLI path for the TUI handoff (dist/src/cli.js). */
-  cliPath: string;
-  /** Node binary for the handoff; defaults to the running one. */
-  nodeBin?: string;
-}
-
-/**
- * Run the onboarding session and handle the handoff:
- *   - checklist complete after pi exits ⇒ open the TUI (same stdio);
- *   - otherwise print how to resume — `qcr onboard` again re-verifies
- *     completed steps and continues at the first unfinished one.
- */
-export async function runOnboard(deps: OnboardRunDeps): Promise<number> {
-  const argv = onboardingPiArgv(deps.pin, deps.root);
-  deps.log(
-    `onboarding: launching pi ${deps.pin.package}@${deps.pin.version} via npx (first run downloads it — give it a moment)`,
-  );
-  const code = await deps.spawn(argv[0]!, argv.slice(1));
-  if (deps.isComplete()) {
-    deps.log("onboarding: checklist verified complete — opening the TUI.");
-    return deps.spawn(deps.nodeBin ?? process.execPath, [deps.cliPath, "tui"]);
-  }
-  deps.log(
-    "onboarding: not finished yet. Run `qcr onboard` again to resume — completed steps are re-verified, not repeated.",
-  );
-  return code;
-}

package/src/setup/ledger.ts

@@ -1,324 +0,0 @@
-// The COVERAGE LEDGER (spec "Ledger"): what the
-// scan has read — one row per file + content hash + lens, with the tier,
-// effort, validator setting, scan sha and cost it was read at. Two jobs:
-//
-//   * the RESUME GRAIN — stage 1 never re-reads a file whose NEWEST ledger
-//     row for the lens is at the same content hash, so an interrupted scan (a TUI
-//     quit, an expired login, a stop, the hard stop) continues where it
-//     stopped and a finished one costs nothing to start again;
-//   * the PRICE — after the first-scan calibration run, every cost preview is
-//     measured from these rows' actual costs, never from a constant.
-//
-// A file too big for one case is read in LINE RANGES (scan.ts cutRanges):
-// one row per range, carrying it, so a file is covered only when the ranges
-// of its newest reading cover every line — a run cut short between ranges
-// leaves the rest to read, and changed content re-reads every range.
-//
-// A row records the DEPTH it was read at (`[scan] depth`; absent = standard,
-// so a ledger written before depths reads as standard). A deep reading is its
-// own coverage: a standard reading of a file never covers it for a deep run
-// (a deep run on a scanned repo would otherwise read nothing), while a deep
-// reading covers it for a standard one. A standard row and a deep row of the
-// same file, content and lens stand side by side.
-//
-// A row is written only when its case FINISHED — a case cut short leaves no
-// row, so it is read again in full. A case's cost is apportioned over its
-// files by lines; a case the runner could not price writes null costs, which
-// the rate ignores (it never reads as free).
-//
-// Persistence: `<state home>/scan/ledger.json`, tmp+rename atomic through the
-// state port. An unreadable ledger is REPORTED and refuses writes: it is the
-// record of money already spent, and starting over on top of it would pay
-// for the same files twice.
-import type { ScanDepth } from "../config.js";
-import type { StateFs } from "./engine.js";
-import { coverKey, rangesCover, type FileRange, type ScanRate } from "./scan.js";
-
-export const LEDGER_FILE = "scan/ledger.json";
-export const LEDGER_VERSION = 1;
-
-export interface LedgerEntry {
-  path: string;
-  /** The file's git blob hash at `sha`. */
-  blob: string;
-  lens: string;
-  /** The line range this row read, when the file was cut into ranges;
-   * absent (or null) = the whole file. Part of the row's identity. */
-  range?: FileRange | null;
-  tier: string;
-  effort: string;
-  /** Whether validation was enabled for this case; a lens returning NONE needs no validator run. */
-  validator: boolean;
-  /** `"deep"` for a deep scan's reading; absent = standard. */
-  depth?: ScanDepth;
-  sha: string;
-  /** Lines read: the file's, or its range's. */
-  lines: number;
-  /** This file's share of its case's cost; null when the runner reported
-   * none. */
-  cost_usd: number | null;
-  run: string;
-  /** The case, within the run (`<unit>` or `<unit>#<i>`). */
-  case: string;
-  at: string;
-}
-
-/** What a price is measured over: the same lens at the same settings — at
- * one depth when `depth` is given, at any otherwise. */
-export interface RateKey {
-  lens: string;
-  tier: string;
-  effort: string;
-  validator: boolean;
-  depth?: ScanDepth;
-}
-
-/** The depth a row was read at. */
-export const depthOf = (e: Pick<LedgerEntry, "depth">): ScanDepth =>
-  e.depth === "deep" ? "deep" : "standard";
-
-export interface LedgerFile {
-  version: number;
-  entries: LedgerEntry[];
-}
-
-const entryKey = (e: Pick<LedgerEntry, "path" | "blob" | "lens" | "range" | "depth">): string =>
-  `${e.lens}\0${coverKey(e.path, e.blob)}${e.range ? `\0${e.range.start}-${e.range.end}` : ""}${depthOf(e) === "deep" ? "\0deep" : ""}`;
-
-export class Ledger {
-  constructor(private readonly state: StateFs) {}
-
-  /** The ledger, or why it cannot be read (then `entries` is empty and
-   * UNKNOWN, not absent). */
-  load(): { entries: LedgerEntry[]; error: string | null } {
-    let text: string | null;
-    try {
-      text = this.state.read(LEDGER_FILE);
-    } catch (err) {
-      return {
-        entries: [],
-        error: `${LEDGER_FILE} in ${this.state.location} cannot be read: ${String(err)}`,
-      };
-    }
-    if (text === null) return { entries: [], error: null };
-    try {
-      const raw = JSON.parse(text) as Partial<LedgerFile> | null;
-      if (
-        typeof raw !== "object" ||
-        raw === null ||
-        raw.version !== LEDGER_VERSION ||
-        !Array.isArray(raw.entries)
-      ) {
-        throw new Error("not a version-1 ledger");
-      }
-      for (const e of raw.entries) {
-        if (
-          typeof e?.path !== "string" ||
-          typeof e.blob !== "string" ||
-          typeof e.lens !== "string"
-        ) {
-          throw new Error("an entry has no path, blob or lens");
-        }
-      }
-      return { entries: raw.entries, error: null };
-    } catch (err) {
-      return {
-        entries: [],
-        error:
-          `${LEDGER_FILE} in ${this.state.location} is not a coverage ledger this version reads (${String(err)}) — ` +
-          "nothing will overwrite it; move it aside to start the ledger over",
-      };
-    }
-  }
-
-  /** Add (or replace, by file + content hash + lens + range + depth)
-   * finished rows. Throws when the stored ledger cannot be read — never
-   * writes over it. */
-  record(rows: readonly LedgerEntry[]): void {
-    const { entries, error } = this.load();
-    if (error !== null) throw new Error(error);
-    const byKey = new Map(entries.map((e) => [entryKey(e), e]));
-    for (const r of rows) byKey.set(entryKey(r), r);
-    const file: LedgerFile = { version: LEDGER_VERSION, entries: [...byKey.values()] };
-    this.state.write(LEDGER_FILE, `${JSON.stringify(file)}\n`);
-  }
-}
-
-/** `path\0blob` of each file's NEWEST reading by `lens` — the same newest
- * row `FindingsStore.reconcile` settles findings against — complete at
- * `depth` (`readings`). An older reading a later one superseded covers
- * nothing: its findings may since have been settled `fixed`, so content that
- * comes back to it (a revert) must be read again for them to come back too. */
-export function coveredBy(
-  entries: readonly LedgerEntry[],
-  lens: string,
-  depth: ScanDepth = "standard",
-): Set<string> {
-  const out = new Set<string>();
-  for (const [path, r] of readings(entries, lens, depth))
-    if (r.complete) out.add(coverKey(path, r.blob));
-  return out;
-}
-
-/** A file's newest reading by one lens: the rows at its newest content,
- * back to the last row at other content (an older reading of the same
- * content, superseded since, is not part of it). */
-export interface Reading {
-  blob: string;
-  /** The newest row of the reading. */
-  newest: LedgerEntry;
-  /** Whole file, or ranges covering every line. */
-  complete: boolean;
-  /** The ranges read so far (empty when a whole-file row stands). */
-  ranges: FileRange[];
-  /** Every run that wrote a row of this reading — a ranged reading cut short
-   * is finished by a later run, and both re-read the file. */
-  runs: string[];
-}
-
-/** Every path's newest reading by `lens`, as `depth` counts it. The newest
- * content is settled by every row whatever its depth (a later reading of
- * other content supersedes a deep one too); within it, a `"standard"` reading
- * is made of every row — a deep reading is at least a standard one — and a
- * `"deep"` reading of the deep rows alone, so a path whose newest content was
- * read only at standard depth has no deep reading. */
-export function readings(
-  entries: readonly LedgerEntry[],
-  lens: string,
-  depth: ScanDepth = "standard",
-): Map<string, Reading> {
-  const byPath = new Map<string, LedgerEntry[]>();
-  for (const e of entries) {
-    if (e.lens !== lens) continue;
-    const rows = byPath.get(e.path);
-    if (rows) rows.push(e);
-    else byPath.set(e.path, [e]);
-  }
-  const out = new Map<string, Reading>();
-  for (const [path, rows] of byPath) {
-    // Stable by time: equal stamps keep ledger order, as `newestRead` does.
-    const sorted = rows
-      .map((e, i) => ({ e, i }))
-      .sort((a, b) => compareAt(a.e.at, b.e.at) || a.i - b.i);
-    const newest = sorted[sorted.length - 1]!.e;
-    const all: LedgerEntry[] = [];
-    for (let k = sorted.length - 1; k >= 0 && sorted[k]!.e.blob === newest.blob; k--)
-      all.push(sorted[k]!.e);
-    const streak = depth === "deep" ? all.filter((e) => depthOf(e) === "deep") : all;
-    if (streak.length === 0) continue;
-    const whole = streak.some((e) => !e.range);
-    const ranges = streak.filter((e) => e.range).map((e) => e.range!);
-    const total = ranges[0]?.total ?? 0;
-    out.set(path, {
-      blob: newest.blob,
-      newest: streak[0]!,
-      complete: whole || (ranges.length > 0 && rangesCover(ranges, 1, total)),
-      ranges: whole ? [] : ranges,
-      runs: [...new Set(streak.map((e) => e.run))],
-    });
-  }
-  return out;
-}
-
-/** `path\0blob` → the ranges of each newest reading by `lens` at `depth` that
- * is not yet complete: the ranges a plan need not read again. */
-export function partialRanges(
-  entries: readonly LedgerEntry[],
-  lens: string,
-  depth: ScanDepth = "standard",
-): Map<string, FileRange[]> {
-  const out = new Map<string, FileRange[]>();
-  for (const [path, r] of readings(entries, lens, depth))
-    if (!r.complete && r.ranges.length > 0) out.set(coverKey(path, r.blob), r.ranges);
-  return out;
-}
-
-/** One case's identity across its rows: the run it ran in and its id there. */
-const caseId = (e: LedgerEntry): string => `${e.run}\0${e.case}`;
-
-/** Was `e` written at `key`'s settings — its depth too, when the key names one? */
-function atKey(e: LedgerEntry, key: RateKey): boolean {
-  return (
-    e.lens === key.lens &&
-    e.tier === key.tier &&
-    e.effort === key.effort &&
-    e.validator === key.validator &&
-    (key.depth === undefined || depthOf(e) === key.depth)
-  );
-}
-
-/** Rows written for `key` at all, and how many of their cases were priced —
- * which is how a preview tells "never calibrated" from "calibrated, but the
- * runner reports no cost". */
-export function casesFor(
-  entries: readonly LedgerEntry[],
-  key: RateKey,
-): { cases: number; priced: number } {
-  const cases = new Map<string, boolean>();
-  for (const e of entries) {
-    if (!atKey(e, key)) continue;
-    const id = caseId(e);
-    cases.set(id, (cases.get(id) ?? false) || e.cost_usd !== null);
-  }
-  return { cases: cases.size, priced: [...cases.values()].filter(Boolean).length };
-}
-
-/** The measured price for `key`: every priced row's cost over its lines, or
- * null when no priced case has finished at these settings. */
-export function measuredRate(entries: readonly LedgerEntry[], key: RateKey): ScanRate | null {
-  return rateWhere(entries, (e) => atKey(e, key));
-}
-
-/** The measured price over the priced rows `keep` selects (stage 2 borrows
- * another lens's price at the same settings this way), or null when none. */
-export function rateWhere(
-  entries: readonly LedgerEntry[],
-  keep: (e: LedgerEntry) => boolean,
-): ScanRate | null {
-  let cost = 0;
-  let lines = 0;
-  const cases = new Set<string>();
-  for (const e of entries) {
-    if (!keep(e) || e.cost_usd === null) continue;
-    cost += e.cost_usd;
-    // The file's REAL lines — the count the preview showed. An empty file
-    // (an `__init__.py`) is 0 here as there; `Math.max(lines, 1)` belongs to
-    // splitting a case's cost across its rows, never to the rate's basis.
-    lines += e.lines;
-    cases.add(caseId(e));
-  }
-  if (cases.size === 0 || lines === 0) return null;
-  return { usd_per_kline: (cost / lines) * 1000, cases: cases.size, lines, cost_usd: cost };
-}
-
-// ---- the delta's basis ----
-
-/** Timestamp order, the one rule `readings` and `newestRead` both sort by. */
-function compareAt(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
-/** Each path's NEWEST content hash read by `lens` — the reading findings
- * are settled against. A path whose content is not that one has CHANGED
- * since it was scanned, even when an older, superseded reading saw exactly
- * this content (a revert): that reading's findings may since be `fixed`. */
-export function newestRead(entries: readonly LedgerEntry[], lens: string): Map<string, string> {
-  const newest = new Map<string, LedgerEntry>();
-  for (const e of entries) {
-    if (e.lens !== lens) continue;
-    const had = newest.get(e.path);
-    if (!had || compareAt(e.at, had.at) >= 0) newest.set(e.path, e);
-  }
-  return new Map([...newest].map(([path, e]) => [path, e.blob]));
-}
-
-/** The sha of the LAST scan by `lens` — its newest row's — or null when the
- * ledger holds none: what a delta re-scan compares the tree against. */
-export function lastScanned(
-  entries: readonly LedgerEntry[],
-  lens: string,
-): { sha: string; at: string; run: string } | null {
-  let last: LedgerEntry | null = null;
-  for (const e of entries) if (e.lens === lens && (last === null || e.at >= last.at)) last = e;
-  return last === null ? null : { sha: last.sha, at: last.at, run: last.run };
-}