@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/setup/scanreport.ts

@@ -1,373 +1,3 @@
-// The scan report's read side and its stop channel: what the TUI's `[8] scan`
-// tab reads out of the state home, and the one file through which it asks
-// the companion to stop a running scan. A leaf like stage2request.ts:
-// it reaches its siblings by type only, so the TUI (which never imports the
-// setup engine — tests/single-shepherd.test.ts) can read the run record and
-// the findings store without carrying the case runner along.
-//
-// Two record files, both the engine's (this module owns their names and
-// their parsers, so the engine and the TUI can never read them differently):
-// `scan/run.json` (scanrun.ts — the current run and a short history) and
-// `scan/findings.json` (findings.ts — every finding with its state). Each is
-// read totally and is one of three facts: absent (no scan has written it),
-// read, or unreadable with the reason — never an empty list standing in for
-// a file that could not be read (the honest-unknown rule).
-//
-// The stop channel mirrors the stage-2 start channel: the TUI writes
-// `SCAN_STOP_FILE` naming the run it showed running; the companion's scan
-// belt picks it up within seconds, stops exactly that run (in-flight cases
-// aborted, the ledger resumes the rest) and answers in
-// `SCAN_STOP_RESULT_FILE`, naming the request it answered — so a stop is
-// answered once and never replayed onto a later run.
-import { join } from "node:path";
-import { readTextIfPresent, writeAtomic } from "../channelfs.js";
-import type { FindingsFile, MatchQuestion, ResemblesDismissed, ScanFinding } from "./findings.js";
-import type { RunFile, ScanRun, ScanRunSummary } from "./scanrun.js";
-
-export type { FindingState, ScanFinding } from "./findings.js";
-export type { ScanCaseState, ScanRun, ScanRunSummary } from "./scanrun.js";
-export type { ScanSeverity } from "./scan.js";
-
-export const FINDING_STATES = ["new", "promoted", "dismissed", "fixed"] as const;
-
-export const RUN_FILE = "scan/run.json";
-export const RUN_VERSION = 1;
-export const FINDINGS_FILE = "scan/findings.json";
-export const FINDINGS_VERSION = 1;
-export const SCAN_STOP_FILE = "scan/stop.json";
-export const SCAN_STOP_RESULT_FILE = "scan/stop-result.json";
-
-// ---- validity tiers (the scan validator is the skeptic) -----------------
-
-/** The skeptic's tier for a stored scan finding: `confirmed` (it traced a
- * concrete scenario), `likely` (a real mechanism, reachability not fully
- * traced), `doubtful` (refuted, class-matched, or anything it would have
- * killed — kept, never dropped). */
-export type Validity = "confirmed" | "likely" | "doubtful";
-export const VALIDITIES: readonly Validity[] = ["confirmed", "likely", "doubtful"];
-/** A tier, or `unknown`: no skeptic judged it (the validator was off or
- * failed) or it was stored before tiers existed — never guessed. */
-export type ValidityView = Validity | "unknown";
-/** Display order: confirmed first, unknown last. */
-export const VALIDITY_ORDER: readonly ValidityView[] = [...VALIDITIES, "unknown"];
-
-/** The longest dismissal reason triage takes. The TUI checks it before
- * asking, so an over-long reason is refused where it is typed. */
-export const DISMISS_REASON_MAX = 500;
-
-/** A dismissed finding a re-scan settled as no longer reported (findings.ts
- * `unreported`): out of play, as a fixed one is, until a scan reports it again. */
-export const goneDismissal = (f: Pick<ScanFinding, "state" | "unreported">): boolean =>
-  f.state === "dismissed" && f.unreported != null;
-
-/** A finding's tier as stored — `unknown` when it carries none. */
-export function validityOf(f: { validity?: Validity | null }): ValidityView {
-  return f.validity !== undefined &&
-    f.validity !== null &&
-    (VALIDITIES as readonly string[]).includes(f.validity)
-    ? f.validity
-    : "unknown";
-}
-
-const clean = (err: unknown): string => (err instanceof Error ? err.message : String(err));
-
-// ---- the two records ---------------------------------------------------------------
-
-/** Is a finding still standing — new, or promoted and not yet fixed? The
- * portrait's counts and the scan tab's weights read open the same way. */
-export const isOpenFinding = (f: Pick<ScanFinding, "state">): boolean =>
-  f.state === "new" || f.state === "promoted";
-
-/** A finding's resemblance to a DISMISSED one (findings.ts sets it when it
- * stores the finding), as a reader shows it: only on a finding still
- * untriaged (`new`) — once the operator promotes or dismisses it, the
- * resemblance is answered. */
-export function dismissedLookalike(
-  f: Pick<ScanFinding, "state" | "resembles_dismissed">,
-): ResemblesDismissed | null {
-  return f.state === "new" ? (f.resembles_dismissed ?? null) : null;
-}
-
-/** 1 for a finding flagged as resembling a dismissed one, else 0 — the sort
- * key that puts it below the unflagged findings of its tier. */
-export const lookalikeRank = (f: Pick<ScanFinding, "state" | "resembles_dismissed">): number =>
-  dismissedLookalike(f) ? 1 : 0;
-
-/** Parse the run record; throws on anything this version does not read. */
-export function parseRunFile(text: string): RunFile {
-  const raw = JSON.parse(text) as Partial<RunFile> | null;
-  if (typeof raw !== "object" || raw === null || raw.version !== RUN_VERSION)
-    throw new Error("unknown version");
-  const current = raw.current ?? null;
-  if (current !== null && (typeof current !== "object" || !Array.isArray(current.cases))) {
-    throw new Error("`current` is not a scan run");
-  }
-  return { version: RUN_VERSION, current, history: Array.isArray(raw.history) ? raw.history : [] };
-}
-
-/** Parse the findings store; throws on anything this version does not read. */
-export function parseFindingsFile(text: string): FindingsFile {
-  const raw = JSON.parse(text) as Partial<FindingsFile> | null;
-  if (
-    typeof raw !== "object" ||
-    raw === null ||
-    raw.version !== FINDINGS_VERSION ||
-    !Array.isArray(raw.findings)
-  ) {
-    throw new Error("not a version-1 findings store");
-  }
-  for (const f of raw.findings) {
-    if (
-      typeof f?.fingerprint !== "string" ||
-      typeof f.path !== "string" ||
-      typeof f.state !== "string"
-    ) {
-      throw new Error("a finding has no fingerprint, path or state");
-    }
-  }
-  const q = raw.question ?? null;
-  if (
-    q !== null &&
-    (typeof q.key !== "string" || !Array.isArray(q.unreported) || !Array.isArray(q.fresh))
-  ) {
-    throw new Error("the pending match question is malformed");
-  }
-  return {
-    version: FINDINGS_VERSION,
-    findings: currentLookalikes(raw.findings.map(stickyDismissal)),
-    question: q,
-  };
-}
-
-/** A `resembles_dismissed` flag is written when a finding is stored; the
- * dismissal it names can change after that — re-dismissed with another
- * reason, promoted (the operator changed their mind), or folded into a fresh
- * finding by a match answer. Every reader goes through this parse, so the
- * flag is re-read against the store here: it names the finding that now
- * carries that fingerprint (itself, or the one it became an alias of) and
- * that finding's current reason while it is still dismissed, and it is
- * dropped otherwise — a stale "looks like a finding you dismissed" never
- * reaches the operator. */
-function currentLookalikes(findings: ScanFinding[]): ScanFinding[] {
-  if (!findings.some((f) => f.resembles_dismissed)) return findings;
-  const owner = new Map<string, ScanFinding>();
-  for (const f of findings) for (const a of f.aliases ?? []) owner.set(a, f);
-  for (const f of findings) owner.set(f.fingerprint, f);
-  return findings.map((f) => {
-    if (!f.resembles_dismissed) return f;
-    const { resembles_dismissed: flag, ...rest } = f;
-    const d = owner.get(flag.fingerprint);
-    if (!d || d.state !== "dismissed" || d.fingerprint === f.fingerprint) return rest;
-    return {
-      ...rest,
-      resembles_dismissed: {
-        fingerprint: d.fingerprint,
-        reason: d.dismissal?.reason ?? flag.reason,
-      },
-    };
-  });
-}
-
-/** A legacy store may hold a dismissed finding recorded as `fixed` with
- * `fixed.from = "dismissed"`: it reads back as the dismissal it is, its fix
- * kept as the `unreported` audit stamp (findings.ts). Every other finding is
- * returned as it is. */
-function stickyDismissal(f: ScanFinding): ScanFinding {
-  if (f.state !== "fixed" || f.fixed?.from !== "dismissed") return f;
-  const { run, sha, at } = f.fixed;
-  return { ...f, state: "dismissed", fixed: null, unreported: { run, sha, at } };
-}
-
-/** One record file: absent, read, or why it could not be. */
-export type RecordRead<T> =
-  { kind: "absent" } | { kind: "read"; value: T } | { kind: "unreadable"; why: string };
-
-function readRecord<T>(home: string, rel: string, parse: (text: string) => T): RecordRead<T> {
-  let text: string | null;
-  try {
-    text = readTextIfPresent(join(home, rel));
-  } catch (err) {
-    return { kind: "unreadable", why: `${rel} cannot be read: ${clean(err)}` };
-  }
-  if (text === null) return { kind: "absent" };
-  try {
-    return { kind: "read", value: parse(text) };
-  } catch (err) {
-    return { kind: "unreadable", why: `${rel} is not a record this version reads (${clean(err)})` };
-  }
-}
-
-/** The scan run record in the state home at `home`. */
-export function readScanRuns(
-  home: string,
-): RecordRead<{ current: ScanRun | null; history: ScanRunSummary[] }> {
-  return readRecord(home, RUN_FILE, (t) => {
-    const f = parseRunFile(t);
-    return { current: f.current, history: f.history };
-  });
-}
-
-/** The findings store in the state home at `home`. */
-export function readScanFindings(
-  home: string,
-): RecordRead<{ findings: ScanFinding[]; question: MatchQuestion | null }> {
-  return readRecord(home, FINDINGS_FILE, (t) => {
-    const f = parseFindingsFile(t);
-    return { findings: f.findings, question: f.question ?? null };
-  });
-}
-
-// ---- the stop channel --------------------------------------------------------------
-
-export interface ScanStopRequest {
-  /** Unique per click; the result names it. */
-  id: string;
-  /** The run the TUI showed running — only that run is stopped. */
-  run: string;
-  at: string;
-  /** Who asked: the TUI's stop, `qcr scan stop`, or the companion's
-   * scan_stop for a run another process drives. */
-  by: "tui" | "cli" | "companion";
-}
-
-export interface ScanStopResult {
-  request: string;
-  run: string;
-  at: string;
-  ok: boolean;
-  errors: string[];
-  /** The run the answering companion was driving when it answered — `null`
-   * when it drove none. Absent from an answer that does not say. A run the
-   * record still calls running that the companion says it is not driving was
-   * interrupted (a companion restart loses the run in flight). */
-  in_flight?: string | null;
-}
-
-/** Parse a stop request, or null when it is not one. */
-export function parseStopRequest(text: string): ScanStopRequest | null {
-  try {
-    const r = JSON.parse(text) as Partial<ScanStopRequest> | null;
-    if (
-      typeof r !== "object" ||
-      r === null ||
-      typeof r.id !== "string" ||
-      r.id === "" ||
-      typeof r.run !== "string" ||
-      r.run === ""
-    )
-      return null;
-    return {
-      id: r.id,
-      run: r.run,
-      at: typeof r.at === "string" ? r.at : "",
-      by: r.by === "cli" || r.by === "companion" ? r.by : "tui",
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Parse a stop result, or null when it is not one. */
-export function parseStopResult(text: string): ScanStopResult | null {
-  try {
-    const r = JSON.parse(text) as Partial<ScanStopResult> | null;
-    if (
-      typeof r !== "object" ||
-      r === null ||
-      typeof r.request !== "string" ||
-      typeof r.ok !== "boolean"
-    )
-      return null;
-    return {
-      request: r.request,
-      run: typeof r.run === "string" ? r.run : "",
-      at: typeof r.at === "string" ? r.at : "",
-      ok: r.ok,
-      errors: Array.isArray(r.errors)
-        ? r.errors.filter((e): e is string => typeof e === "string")
-        : [],
-      ...(typeof r.in_flight === "string" || r.in_flight === null
-        ? { in_flight: r.in_flight }
-        : {}),
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * The TUI's stop: ask the companion to stop the run `run`, which the TUI
- * showed running. Refused when the record cannot be read or no longer shows
- * that run running — a stop is never aimed at a run the operator did not see.
- * The notice line says what was asked, or why nothing was.
- */
-export function clickStopScan(
-  home: string,
-  run: string,
-  now: Date = new Date(),
-  by: ScanStopRequest["by"] = "tui",
-): { ok: true; request: string; line: string } | { ok: false; line: string } {
-  const read = readScanRuns(home);
-  if (read.kind === "unreadable") return { ok: false, line: `scan not stopped: ${read.why}` };
-  const cur = read.kind === "read" ? read.value.current : null;
-  if (cur === null || cur.id !== run || cur.state !== "running") {
-    return {
-      ok: false,
-      line: `scan not stopped: ${run} is no longer running — look at the report again`,
-    };
-  }
-  const request: ScanStopRequest = {
-    id: `${now.toISOString()}-${Math.random().toString(36).slice(2, 8)}`,
-    run,
-    at: now.toISOString(),
-    by,
-  };
-  try {
-    writeAtomic(join(home, SCAN_STOP_FILE), `${JSON.stringify(request)}\n`);
-  } catch (err) {
-    return {
-      ok: false,
-      line: `scan not stopped: the stop request could not be written: ${clean(err)}`,
-    };
-  }
-  return {
-    ok: true,
-    request: request.id,
-    line: `stop asked for ${run} — the companion stops it within seconds; the ledger resumes the rest`,
-  };
-}
-
-/** The companion's latest stop answer: none yet (`absent`, or a file this
- * version does not read as one), the answer, or `unreadable` with the reason
- * — never a throw, and an unreadable answer is never mistaken for none. */
-export type StopResultRead =
-  | { kind: "absent" }
-  | { kind: "read"; result: ScanStopResult }
-  | { kind: "unreadable"; why: string };
-
-export function readStopResult(home: string): StopResultRead {
-  let text: string | null;
-  try {
-    text = readTextIfPresent(join(home, SCAN_STOP_RESULT_FILE));
-  } catch (err) {
-    return { kind: "unreadable", why: `${SCAN_STOP_RESULT_FILE}: ${clean(err)}` };
-  }
-  const r = text === null ? null : parseStopResult(text);
-  return r === null ? { kind: "absent" } : { kind: "read", result: r };
-}
-
-/** What became of the stop `request`: the companion's answer, or null while
- * it has not answered (a companion that is down stops nothing — and runs
- * nothing either). */
-export function scanStopOutcome(home: string, request: string): string | null {
-  const read = readStopResult(home);
-  // Not "no answer yet": the answer may be there, unreadable — said once,
-  // never polled for silently.
-  if (read.kind === "unreadable")
-    return `the scan stop's answer cannot be read (${read.why}) — check scan_status`;
-  if (read.kind === "absent" || read.result.request !== request) return null;
-  const r = read.result;
-  return r.ok
-    ? `scan ${r.run} stopped — what finished is in the ledger`
-    : `scan stop refused: ${r.errors.join("; ")}`;
-}
+// Moved to the plugin (packages/pi-plugin/src/scan/scanreport.ts), the scan engine's
+// home: this name stays for the app's importers.
+export * from "@quickchatai/pi-quickreview/src/scan/scanreport.js";