@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/priorresolve.ts

@@ -0,0 +1,343 @@
+import { postedFindingChains } from "@quickchatai/pi-quickreview/src/priorfindings.js";
+import { markerTwins, type FindingCommentRow } from "./outcomes.js";
+// Resolving the bot's own threads for findings a follow-up round verified
+// FIXED.
+//
+// A follow-up round verifies every open prior finding at the new head and
+// reports each one's status in its findings record's `prior` array (stored
+// in `prior_finding_checks`). Ping-pong resolves a thread only when the
+// author replies in it, so a finding fixed by a push with no reply would
+// otherwise keep its thread open, and the reviewed repo's merge rule (every
+// conversation resolved) would leave a human to resolve the bot's threads.
+//
+// So when a round's findings record lands, the daemon resolves the bot's own
+// root comment of every prior finding that round reported `fixed` or
+// `obsolete` (the code it was anchored on is gone) — through the adapter's one
+// resolve path, `resolveOwnReviewThread`, which reads the thread first and
+// resolves only a thread whose root the bot authored, refuses a `[check this]`
+// or `[deferred]` thread (both human-only to resolve; `[check this]` is
+// the never-hand-to-a-human rule), and goes through the MutationGate (suppressed in
+// dry-run like every other kind).
+// `open`, `unverifiable`, `conceded` and `settled` are left alone: an open one
+// still holds, and the last two are ping-pong's and the ledger's.
+//
+// Which comment is a finding's: the outcome capture's settled link
+// (`finding_comments`) for that posting, else the findings
+// record's own `thread_id`. A finding re-posted across rounds (a carried
+// chain) has a thread per posting; the round reported its latest ref, and the
+// earlier postings' threads are resolved with it when the round's prior list
+// sidecar names them (`earlier_refs`). A thread with no known comment is
+// logged, never guessed.
+//
+// Total and quiet: every resolve is its own try, every outcome an event
+// (`prior_thread_resolved` / `prior_thread_resolve_skipped` /
+// `prior_thread_resolve_failed`), and nothing here wakes anyone or holds a
+// round. A resolve that fails for a reason other than the adapter's own
+// refusal (a GitHub 5xx, a dropped connection) is tried again twice, a few
+// seconds apart, before it is recorded failed. Durable per-thread outcomes
+// let a restart resume only unfinished work; an exhausted failure is terminal. It never unresolves anything and never touches another identity's
+// thread.
+
+import { ThreadResolutionRefusal } from "./thread-resolution-refusal.js";
+import { readFileSync } from "node:fs";
+import { parsePriorRef } from "@quickchatai/pi-quickreview/src/findingsrecord.js";
+import type { GitHubAdapter } from "./github.js";
+import type { StateStore } from "./state.js";
+
+/** The prior statuses whose thread the bot resolves. */
+export const RESOLVABLE_PRIOR_STATUSES: ReadonlySet<string> = new Set(["fixed", "obsolete"]);
+
+/** One thread to resolve: the finding it belongs to and its root comment. */
+export interface PriorThread {
+  round_no: number;
+  finding_key: string;
+  status: string;
+  comment_id: number;
+}
+
+/** A finding's root comments: the outcome capture's settled link for that
+ * posting, else the findings record's `thread_id`. */
+function commentIdsOf(
+  store: StateStore,
+  pr: number,
+  roundNo: number,
+  findingKey: string,
+): number[] {
+  const ids = new Set<number>();
+  const hasLinks = store.db
+    .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'finding_comments'")
+    .get();
+  if (hasLinks) {
+    for (const r of store.db
+      .prepare(
+        "SELECT comment_id FROM finding_comments WHERE pr = ? AND round_no = ? AND finding_key = ?",
+      )
+      .all(pr, roundNo, findingKey) as Array<{ comment_id: number }>)
+      ids.add(r.comment_id);
+  }
+  if (ids.size === 0) {
+    for (const r of store.db
+      .prepare(
+        "SELECT thread_id FROM round_findings WHERE pr = ? AND round_no = ? AND finding_key = ? AND thread_id IS NOT NULL",
+      )
+      .all(pr, roundNo, findingKey) as Array<{ thread_id: number }>)
+      ids.add(r.thread_id);
+  }
+  if (hasLinks) {
+    const comments = store.db
+      .prepare("SELECT * FROM finding_comments WHERE pr=? ORDER BY comment_id")
+      .all(pr) as FindingCommentRow[];
+    // A captured root may not have been linked yet. Its round's durable
+    // thread id still establishes that root, but only its exact marker may
+    // establish twins (a positional link does not confer marker identity).
+    const rooted = comments.map((comment) =>
+      ids.has(comment.comment_id) &&
+      comment.round_no === null &&
+      comment.finding_key === null &&
+      comment.marker_round === roundNo &&
+      comment.marker_key === findingKey
+        ? { ...comment, round_no: roundNo, finding_key: findingKey, via: "marker" as const }
+        : comment,
+    );
+    const twins = markerTwins(rooted);
+    for (const id of [...ids]) for (const twin of twins.get(id) ?? []) ids.add(twin);
+  }
+  return [...ids];
+}
+
+/** The earlier postings of each listed finding, from the round's prior-list
+ * sidecar (`{findings:[{ref, earlier_refs}]}`); empty when unreadable, with
+ * the parse error handed to `onMalformed`. */
+export function earlierRefsFromSidecar(
+  text: string | undefined,
+  onMalformed?: (err: unknown) => void,
+): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  if (!text) return out;
+  try {
+    const parsed = JSON.parse(text) as {
+      findings?: Array<{ ref?: unknown; earlier_refs?: unknown }>;
+    };
+    for (const f of parsed.findings ?? []) {
+      if (typeof f.ref !== "string" || !Array.isArray(f.earlier_refs)) continue;
+      out.set(
+        f.ref,
+        f.earlier_refs.filter((r): r is string => typeof r === "string"),
+      );
+    }
+  } catch (err) {
+    // An unreadable sidecar resolves the latest posting's thread only.
+    onMalformed?.(err);
+  }
+  return out;
+}
+
+/**
+ * The threads to resolve for round `checkedRound` of `pr`: every prior finding
+ * it reported fixed or obsolete, with each posting's root comment. Findings
+ * with no known comment are returned in `unlinked`, for the log.
+ */
+export function priorThreadsToResolve(
+  store: StateStore,
+  pr: number,
+  checkedRound: number,
+  earlier: Map<string, string[]> = new Map(),
+): { threads: PriorThread[]; unlinked: string[] } {
+  const threads: PriorThread[] = [];
+  const unlinked: string[] = [];
+  const seen = new Set<number>();
+  const checks = store.priorFindingChecks(pr);
+  const families = postedFindingChains(store.roundFindings(pr));
+  // A report decides only what came after the chain's latest posting (the
+  // prior-list rule, packages/pi-plugin/src/priorfindings.ts): a posting at or after the checked
+  // round re-opens the finding, and this round's fixed report no longer holds.
+  const newer = (round: number, key: string) => {
+    const root = families.find(`${round}:${key}`);
+    return (
+      (families.members.get(root) ?? []).some((m) => m.round_no >= checkedRound) ||
+      checks.some(
+        (c) =>
+          families.find(`${c.round_no}:${c.finding_key}`) === root &&
+          c.checked_round > checkedRound &&
+          c.status !== null,
+      )
+    );
+  };
+  for (const c of checks) {
+    if (c.checked_round !== checkedRound || c.status === null) continue;
+    if (newer(c.round_no, c.finding_key)) continue;
+    if (!RESOLVABLE_PRIOR_STATUSES.has(c.status)) continue;
+    const ref = `${c.round_no}:${c.finding_key}`;
+    const postings = [
+      { round_no: c.round_no, finding_key: c.finding_key },
+      ...(earlier.get(ref) ?? [])
+        .map(parsePriorRef)
+        .filter((p): p is NonNullable<typeof p> => p !== null),
+    ];
+    for (const p of postings) {
+      if (newer(p.round_no, p.finding_key)) continue;
+      const ids = commentIdsOf(store, pr, p.round_no, p.finding_key);
+      if (ids.length === 0) unlinked.push(`${p.round_no}:${p.finding_key}`);
+      for (const id of ids) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        threads.push({
+          round_no: p.round_no,
+          finding_key: p.finding_key,
+          status: c.status,
+          comment_id: id,
+        });
+      }
+    }
+  }
+  return { threads, unlinked };
+}
+
+export interface PriorResolveDeps {
+  store: StateStore;
+  adapter: Pick<GitHubAdapter, "resolveOwnReviewThread">;
+  /** The round's prior-list sidecar path (packages/pi-plugin/src/priorfindings.ts), for the
+   * earlier postings of carried findings. */
+  sidecarPath?: (pr: number, roundNo: number) => string;
+  log?: (msg: string, extra?: unknown) => void;
+  /** The waits before each retry of a failed resolve; default 2 s then 8 s. */
+  retryDelaysMs?: readonly number[];
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const RETRY_DELAYS_MS: readonly number[] = [2_000, 8_000];
+
+/** The adapter's own refusals (`resolveOwnReviewThread`): not this bot's
+ * thread, or no thread at all. A retry cannot change either answer. */
+function isRefusal(err: unknown): boolean {
+  return err instanceof ThreadResolutionRefusal;
+}
+
+/** Retry a transient resolve failure; refusal or exhausted attempts reject
+ * to the caller, which records the thread's outcome. */
+async function resolveWithRetry(
+  deps: PriorResolveDeps,
+  pr: number,
+  commentId: number,
+  stillCurrent: () => boolean,
+): Promise<Awaited<ReturnType<PriorResolveDeps["adapter"]["resolveOwnReviewThread"]>> | undefined> {
+  const delays = deps.retryDelaysMs ?? RETRY_DELAYS_MS;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  for (let attempt = 0; ; attempt++) {
+    if (!stillCurrent()) return undefined;
+    try {
+      return await deps.adapter.resolveOwnReviewThread(pr, commentId);
+    } catch (err) {
+      if (attempt >= delays.length || isRefusal(err)) throw err;
+      deps.log?.(`priorresolve: #${pr} thread ${commentId} resolve failed, retrying`, err);
+      await sleep(delays[attempt]!);
+    }
+  }
+}
+
+export async function resolveVerifiedPriorThreads(
+  deps: PriorResolveDeps,
+  pr: number,
+  roundNo: number,
+): Promise<{
+  resolved: number;
+  skipped: number;
+  failed: number;
+  unlinked: number;
+  readable: boolean;
+}> {
+  const tally = { resolved: 0, skipped: 0, failed: 0, unlinked: 0, readable: false };
+  let earlier = new Map<string, string[]>();
+  if (deps.sidecarPath) {
+    const path = deps.sidecarPath(pr, roundNo);
+    let text: string | undefined;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch (err) {
+      // A round with no prior list (a full round) has no sidecar: that is
+      // ordinary. Any other failure costs the earlier postings' threads.
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT")
+        deps.log?.(
+          `priorresolve: #${pr} round ${roundNo} sidecar ${path} unreadable — earlier postings' threads not resolved`,
+          err,
+        );
+      text = undefined;
+    }
+    earlier = earlierRefsFromSidecar(text, (err) =>
+      deps.log?.(
+        `priorresolve: #${pr} round ${roundNo} sidecar ${path} malformed — earlier postings' threads not resolved`,
+        err,
+      ),
+    );
+  }
+  let plan: ReturnType<typeof priorThreadsToResolve>;
+  try {
+    plan = priorThreadsToResolve(deps.store, pr, roundNo, earlier);
+  } catch (err) {
+    deps.log?.(`priorresolve: #${pr} round ${roundNo} threads not listed`, err);
+    return tally;
+  }
+  tally.readable = true;
+  tally.unlinked = plan.unlinked.length;
+  if (plan.unlinked.length > 0)
+    deps.store.logEvent("prior_thread_resolve_skipped", pr, {
+      round_no: roundNo,
+      reason: "no-known-comment",
+      refs: plan.unlinked,
+    });
+  const completed = deps.store.db.prepare(`SELECT 1 FROM events WHERE pr=?
+    AND kind IN ('prior_thread_resolved','prior_thread_resolve_skipped','prior_thread_resolve_failed')
+    AND json_extract(payload, '$.round_no')=? AND json_extract(payload, '$.comment_id')=? LIMIT 1`);
+  for (const t of plan.threads) {
+    // A resumed invocation skips completed and exhausted outcomes. Retrying
+    // interrupted work must never turn the finite retry policy into a loop.
+    if (completed.get(pr, roundNo, t.comment_id)) {
+      tally.skipped++;
+      continue;
+    }
+    const base = {
+      round_no: roundNo,
+      ref: `${t.round_no}:${t.finding_key}`,
+      comment_id: t.comment_id,
+      status: t.status,
+    };
+    try {
+      const r = await resolveWithRetry(deps, pr, t.comment_id, () =>
+        priorThreadsToResolve(deps.store, pr, roundNo, earlier).threads.some(
+          (current) => current.comment_id === t.comment_id && current.status === t.status,
+        ),
+      );
+      if (r === undefined) {
+        tally.skipped += 1;
+        deps.store.logEvent("prior_thread_resolve_skipped", pr, {
+          ...base,
+          reason: "superseded-prior-report",
+        });
+      } else if (r.skipped) {
+        tally.skipped += 1;
+        deps.store.logEvent("prior_thread_resolve_skipped", pr, { ...base, reason: r.skipped });
+      } else if (r.result && r.result.executed === false) {
+        // Dry-run, or a guard refused it: the gate's own record says which.
+        tally.skipped += 1;
+        deps.store.logEvent("prior_thread_resolve_skipped", pr, {
+          ...base,
+          reason: "not-executed",
+        });
+      } else {
+        tally.resolved += 1;
+        deps.store.logEvent("prior_thread_resolved", pr, base);
+      }
+    } catch (err) {
+      tally.failed += 1;
+      deps.store.logEvent("prior_thread_resolve_failed", pr, {
+        ...base,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  if (plan.threads.length > 0 || plan.unlinked.length > 0)
+    deps.log?.(
+      `priorresolve: #${pr} round ${roundNo} — ${tally.resolved} thread(s) resolved, ${tally.skipped} skipped, ${tally.failed} failed, ${tally.unlinked} with no known comment`,
+    );
+  return tally;
+}

package/src/qcrbin.ts

@@ -0,0 +1,186 @@
+// The `qcr` bin's front door (bin/qcr.js). The app's entry, src/cli.ts, loads
+// the whole operator CLI, the state database's SQLite driver among it; the
+// verbs a person runs from an npm install are routed here first and load only
+// what they use, so they work where that native driver cannot load:
+//
+//   qcr                the admin TUI (`qcr tui`)
+//   qcr version        the install's identity (src/version.ts)
+//   qcr review …       a daemonless review (src/reviewcli.ts)
+//   qcr login [p]      pi's own /login in the pinned pi (src/npmverbs.ts)
+//   qcr pi [args]      the pinned pi with the qcr plugin preloaded
+//   qcr update         the installing package manager updates qcr
+//
+// Every other verb goes to src/cli.ts `main` unchanged. The image's
+// `node /opt/qcr/dist/src/cli.js` never comes through here. After a verb, a
+// newer published version is mentioned once on stderr (src/updatenotice.ts).
+import { join } from "node:path";
+import { isSqliteUnavailable, sqliteHint } from "./sqlitehint.js";
+import { fsDeniedLine } from "./fsdenied.js";
+import { MissingConfigError } from "./missingconfig.js";
+
+/** The bin's own lines on top of the app's usage (`qcr help`). */
+export const BIN_HELP = [
+  "qcr — QuickReview",
+  "",
+  "  qcr                     open the admin TUI",
+  "  qcr review [target]     review code here, with no daemon (`qcr review --help`)",
+  "  qcr login [provider]    log in with pi's own /login, for the review sessions",
+  "  qcr pi [args]           pi with the qcr plugin (/review, /scan, /selfimprove, /qcr-setup)",
+  "  qcr update              update qcr with the package manager that installed it",
+  "  qcr version [--json]    this install's version, schemas and pi pin",
+  "",
+  "Every app verb:",
+].join("\n");
+
+/** The verbs that never print the update notice: the ones that hand the
+ * terminal over (the TUI, pi) or are about versions themselves. */
+const QUIET_VERBS = new Set(["tui", "pi", "update", "version", "login"]);
+
+/** What `runBin` would do with `argv`, before doing it. */
+export type BinRoute =
+  | { route: "tui" }
+  | { route: "help" }
+  | { route: "pi"; args: string[] }
+  | { route: "version" | "update" | "login" | "review"; args: string[]; json: boolean }
+  | { route: "app"; argv: string[] };
+
+export function binRoute(argv: readonly string[]): BinRoute {
+  if (argv.length === 0) return { route: "tui" };
+  // pi's arguments are pi's, `--json` included
+  if (argv[0] === "pi") return { route: "pi", args: argv.slice(1) };
+  // `qcr message` carries free text: src/cli.ts reads its argv as it is
+  if (argv[0] === "message") return { route: "app", argv: [...argv] };
+  const json = argv.includes("--json");
+  const rest = argv.filter((a) => a !== "--json");
+  const [cmd, ...args] = rest;
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") return { route: "help" };
+  if (cmd === "version" || cmd === "update" || cmd === "login" || cmd === "review")
+    return { route: cmd, args, json };
+  return { route: "app", argv: [...argv] };
+}
+
+async function appMain(argv: string[]): Promise<void> {
+  const { main } = await import("./cli.js");
+  await main(argv);
+}
+
+/** The GitHub token handed over as a file (packages/pi-plugin/src/ghcred.ts):
+ * read and unlinked before a review can start a child, as src/cli.ts `main`
+ * does for its verbs. False (and said) when it cannot be taken. */
+async function takeHandoff(json: boolean): Promise<boolean> {
+  const { takeHandoffToken } = await import("@quickchatai/pi-quickreview/src/ghcred.js");
+  try {
+    takeHandoffToken();
+    return true;
+  } catch (err) {
+    const error = `the GitHub token handoff failed: ${err instanceof Error ? err.message : String(err)}`;
+    if (json) console.log(JSON.stringify({ error }));
+    else console.error(`qcr: ${error}`);
+    return false;
+  }
+}
+
+async function packageRoot(): Promise<string> {
+  const { sandboxRoot } = await import("./config.js");
+  return sandboxRoot();
+}
+
+/** The update notice after a verb, when one is due (never throws). */
+async function maybeNotice(json: boolean): Promise<void> {
+  try {
+    const [{ updateNotice, updateCachePath, spawnRefresh }, { detectInstall, CLI_PACKAGE }] =
+      await Promise.all([import("./updatenotice.js"), import("./npmverbs.js")]);
+    const { stateHome } = await import("./homes.js");
+    const { readFileSync, realpathSync } = await import("node:fs");
+    const root = realpathSync(await packageRoot());
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+      version?: unknown;
+    };
+    const cachePath = updateCachePath(stateHome());
+    const line = updateNotice({
+      current: typeof pkg.version === "string" ? pkg.version : "0.0.0",
+      cachePath,
+      env: process.env,
+      tty: Boolean(process.stderr.isTTY),
+      json,
+      installed: detectInstall(root, process.env).kind === "global",
+      now: Date.now(),
+      refresh: () => spawnRefresh(cachePath, CLI_PACKAGE),
+    });
+    if (line !== null) console.error(line);
+  } catch {
+    // the notice is a courtesy: it never costs the verb
+  }
+}
+
+async function route(r: BinRoute): Promise<void> {
+  switch (r.route) {
+    case "tui":
+      return appMain(["tui"]);
+    case "help":
+      console.log(BIN_HELP);
+      try {
+        await appMain(["help"]);
+      } catch {
+        // the app's usage then loads the config to surface its errors, and a
+        // fresh install has none: the usage above is the answer
+      }
+      return;
+    case "version": {
+      const { cmdVersion } = await import("./version.js");
+      return cmdVersion(r.json);
+    }
+    case "review": {
+      if (!(await takeHandoff(r.json))) {
+        process.exitCode = 1;
+        return;
+      }
+      const { cmdReview } = await import("./reviewcli.js");
+      const { openReviewMemoryPortAt } = await import("./reviewmemory.js");
+      process.exitCode = await cmdReview(r.args, r.json, { memory: openReviewMemoryPortAt });
+      return;
+    }
+    case "login": {
+      const { cmdLogin, npmVerbDeps } = await import("./npmverbs.js");
+      process.exitCode = await cmdLogin(r.args, npmVerbDeps(await packageRoot()));
+      return;
+    }
+    case "pi": {
+      const { cmdPi, npmVerbDeps } = await import("./npmverbs.js");
+      process.exitCode = cmdPi(r.args, npmVerbDeps(await packageRoot()));
+      return;
+    }
+    case "update": {
+      const { cmdUpdate, detectInstall, npmVerbDeps } = await import("./npmverbs.js");
+      const root = await packageRoot();
+      // The image keeps its own `qcr update`: whatever the app's entry says.
+      if (detectInstall(root, process.env).kind === "image") return appMain(["update"]);
+      process.exitCode = cmdUpdate(r.args, npmVerbDeps(root));
+      return;
+    }
+    case "app":
+      return appMain(r.argv);
+  }
+}
+
+/** Run the `qcr` bin on `argv` (the process's arguments after the script). */
+export async function runBin(argv: readonly string[]): Promise<void> {
+  const r = binRoute(argv);
+  try {
+    await route(r);
+  } catch (err) {
+    const verb = r.route === "app" ? r.argv.find((a) => a !== "--json") : r.route;
+    const line = isSqliteUnavailable(err)
+      ? sqliteHint(verb, err)
+      : err instanceof MissingConfigError
+        ? `qcr ${verb}: ${err.message}`
+        : fsDeniedLine(verb, err);
+    if (line === null) throw err;
+    console.error(line);
+    process.exitCode = 1;
+    return;
+  }
+  const verb = r.route === "app" ? r.argv.find((a) => a !== "--json") : r.route;
+  if (r.route !== "tui" && r.route !== "help" && !QUIET_VERBS.has(verb ?? ""))
+    await maybeNotice("json" in r ? r.json : r.route === "app" && r.argv.includes("--json"));
+}