tumwater 0.2.0 → 0.4.0

package/dist/src/run/acceptance-greps.js

@@ -0,0 +1,119 @@
+/** The pre-queue self-check's acceptance-grep runner: a finished plan entry that says a `grep …`
+ * "finds nothing" is checked by running that grep in the worktree, so a change is not rejected
+ * for an acceptance grep that still matches. Only the strict "matches nothing" form runs;
+ * criteria worded "prints only …" need judgement and stay out. Staging-only (stage-check.ts). */
+import { execFileAsync } from "../process/process.js";
+import { moreSuffix } from "../text/phrases.js";
+import { collapseWhitespace, truncate } from "../text/text.js";
+const MAX_CRITERIA = 5;
+const GREP_TIMEOUT_MS = 20_000;
+const EMPTY_PHRASE_RE = new RegExp("^\\s*(?:(?:finds|prints|returns|outputs|matches|lists) nothing|is empty|lists none|" +
+    "(?:prints|finds|lists|returns|gives|shows) no (?:lines?|hits?|matches?|output))", "i");
+const ALLOWANCE_RE = /apart from|except|excluding|other than|besides|beyond/i;
+/** The backticked `grep …`/`git grep …` commands in `body` that the text says match nothing
+ * ("finds nothing", "is empty", …), without duplicates, in body order, at most five. A criterion
+ * whose sentence (up to the next `.` or `;`) allows some hits ("apart from", "except", …) is
+ * dropped. */
+export function emptyGrepCriteria(body) {
+    const text = collapseWhitespace(body);
+    const found = [];
+    for (const m of text.matchAll(/`([^`]+)`/g)) {
+        const cmd = m[1] ?? "";
+        if (!/^(?:git )?grep /.test(cmd))
+            continue;
+        const rest = text.slice((m.index ?? 0) + m[0].length);
+        const phrase = EMPTY_PHRASE_RE.exec(rest);
+        if (phrase === null)
+            continue;
+        const sentence = rest.slice(0, rest.search(/[.;]/) === -1 ? undefined : rest.search(/[.;]/));
+        if (ALLOWANCE_RE.test(sentence))
+            continue;
+        if (!found.includes(cmd))
+            found.push(cmd);
+        if (found.length >= MAX_CRITERIA)
+            break;
+    }
+    return found;
+}
+/** A minimal shell-word split of a `grep …`/`git grep …` command, or undefined when it uses
+ * shell syntax (an unquoted `|;&<>$()` or backtick) or leaves a quote open. Nothing runs through
+ * a shell, so `*` stays literal. */
+export function grepArgv(cmd) {
+    const words = [];
+    let cur = "";
+    let inWord = false;
+    let quote = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const c = cmd[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                cur += c;
+        }
+        else if (quote === '"') {
+            const next = cmd[i + 1];
+            if (c === "\\" && (next === '"' || next === "\\")) {
+                cur += next;
+                i++;
+            }
+            else if (c === '"')
+                quote = null;
+            else
+                cur += c;
+        }
+        else if (c === "'" || c === '"') {
+            quote = c;
+            inWord = true;
+        }
+        else if (c === "\\") {
+            if (i + 1 < cmd.length)
+                cur += cmd[++i];
+            inWord = true;
+        }
+        else if (/[|;&<>$()`]/.test(c)) {
+            return undefined;
+        }
+        else if (/\s/.test(c)) {
+            if (inWord)
+                words.push(cur);
+            cur = "";
+            inWord = false;
+        }
+        else {
+            cur += c;
+            inWord = true;
+        }
+    }
+    if (quote !== null)
+        return undefined;
+    if (inWord)
+        words.push(cur);
+    if (words[0] === "git" && words[1] === "grep")
+        return { file: "git", args: words.slice(1) };
+    if (words[0] === "grep")
+        return { file: "grep", args: words.slice(1) };
+    return undefined;
+}
+/** Run each entry's matches-nothing greps in `wt`; one finding per entry, for its first grep that
+ * still prints lines. An exit of 1 passes; any other failure (exit 2, timeout, spawn error) skips
+ * the criterion, since an unrunnable command is not evidence. */
+export async function acceptanceGrepFindings(wt, entries) {
+    const findings = [];
+    for (const entry of entries) {
+        for (const cmd of emptyGrepCriteria(entry.body)) {
+            const argv = grepArgv(cmd);
+            if (argv === undefined)
+                continue;
+            const out = await execFileAsync(argv.file, argv.args, { cwd: wt, timeout: GREP_TIMEOUT_MS }).then((r) => r.stdout, () => "");
+            const lines = out.split("\n").filter((l) => l !== "");
+            if (lines.length === 0)
+                continue;
+            const shown = lines.slice(0, 5).map((l) => truncate(l, 200)).join("; ");
+            findings.push(`PLANS.md's finished entry "${truncate(entry.title, 160)}" says \`${cmd}\` matches nothing, but it prints ` +
+                `${lines.length} line(s): ${shown}${moreSuffix(lines.length - 5)} — fix those lines, or correct the claim if the criterion is wrong`);
+            break;
+        }
+    }
+    return findings;
+}

package/dist/src/run/ci-parity.js

@@ -0,0 +1,121 @@
+/** The `ci` observer's CI-parity ledger (plans, part 3/3). Every `ci` run starts a fresh pi
+ * session, so the only durable memory of which main tip and `package-lock.json` each run
+ * covered is a runtime file the harness — not pi — maintains. The role runs the workflow's own
+ * full suite and e2e, which is minutes of work, so its nothing-to-do decision must be cheap:
+ * the parity block tells the fresh session what the last run covered, and when main has not
+ * moved (and the lock is unchanged) since a green run, the role declares nothing-to-do in one
+ * model run instead of re-running the whole suite. The ledger is gitignored runtime state
+ * under .tumwater/state/ and degrades to "no data" on any missing or malformed file: an
+ * observer must never fail a run on bookkeeping (the same policy as qa-coverage.ts). A stale
+ * verdict that stays stale past `CI_PARITY_STALE_MS` is a stall — the full suite has silently
+ * stopped covering new tips — surfaced as a doctor warn and a standing `ci-stale` alert through
+ * the one `ciParityStalled` predicate. */
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { ciParityPath } from "../paths.js";
+import { isJsonObject } from "../files/json-object.js";
+import { currentBranchFromHeadFile, readBranchHead, targetBranch } from "../git/git.js";
+import { DAY_MS } from "../text/datetime.js";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import path from "node:path";
+/** A stale verdict that stays stale past this window is a stall: the `ci` role — now the
+ * full suite's own runner — has silently stopped covering new tips (disabled, paused, wedged,
+ * or failing before it records). The doctor `ci parity` warn and the standing `ci-stale` alert
+ * share this one threshold, so the surfaces cannot disagree on when stale is a problem. */
+export const CI_PARITY_STALE_MS = 3 * DAY_MS;
+/** True only when a parity record exists, reads `stale` (a `failed` record already warns and
+ * a `current` one is verified for the tip), and has not covered a tip within the stall
+ * window. Parameter is structural — not `CiParityStatus` — so the status-polls → ci-parity
+ * import edge stays one-way. This is the single stall predicate shared by the doctor row and
+ * the alert. */
+export function ciParityStalled(parity, now) {
+    return !!parity && parity.state === "stale" && now - parity.lastRunAt > CI_PARITY_STALE_MS;
+}
+/** True when `value` is a well-formed parity record. A record missing any field, or carrying
+ * a non-`passed|failed` result, reads as no data — the caller renders no block and the run
+ * proceeds as before. */
+function isParityEntry(value) {
+    if (!isJsonObject(value))
+        return false;
+    return (typeof value.tip === "string" &&
+        typeof value.lockHash === "string" &&
+        (value.result === "passed" || value.result === "failed") &&
+        typeof value.lastRunAt === "number");
+}
+/** Read the parity ledger. A missing, torn, or wrong-shaped file reads as null — the caller
+ * renders no block and the run proceeds as before. */
+export function readCiParity(root) {
+    const file = readJsonFile(ciParityPath(root));
+    return file?.parity && isParityEntry(file.parity) ? file.parity : null;
+}
+/** Record what a `ci` run covered: the tip it named on its `CI:` line and the verdict that
+ * line carried, plus the lock hash of the coverage tree computed here. The single record is
+ * written atomically (writeJsonAtomic) so a concurrent reader never sees a torn file; a
+ * concurrent last-writer simply wins the slot. */
+export function recordParity(root, sha, result, now = Date.now()) {
+    writeJsonAtomic(ciParityPath(root), { parity: { tip: sha, lockHash: lockHashOf(root), result, lastRunAt: now } });
+}
+/** The hash of `package-lock.json` at `root` itself — what the current tree carries. An
+ * empty string when the file is missing (or unreadable) reads as an unmatched hash, so a
+ * swing to "no lock file" renders stale rather than pretending nothing moved. */
+export function lockHashOf(root) {
+    let file;
+    try {
+        file = fs.readFileSync(path.join(root, "package-lock.json"), "utf8");
+    }
+    catch {
+        return "";
+    }
+    return crypto.createHash("sha256").update(file).digest("hex");
+}
+/** The current main tip and lock hash, resolved synchronously from the ref files and the
+ * working tree (mirroring status-polls.ts's per-poll read: readBranchHead + targetBranch, no
+ * spawn). Either degrades to "" when it cannot be resolved, which the render treats as
+ * "has definitely not matched", so a resolution failure can never declare a false current. */
+export function currentCiParityState(root, config) {
+    const branch = targetBranch(config?.baseBranch, currentBranchFromHeadFile(root));
+    return { tip: readBranchHead(root, branch) ?? "", lockHash: lockHashOf(root) };
+}
+/** True when `entry` counts as "current": the last run passed AND it covered exactly this
+ * tip with exactly this lock hash. This is the single home of the "current" decision, so the
+ * ci prompt block (`renderParityBlock`) and the doctor `ci parity` row (`checkCiParity`) cannot
+ * disagree on what "current" means. `entry.tip` is whatever the run named on its `CI:` line — a
+ * 7-64-char abbreviated sha (the model's own shorthand) or the full 40-char head; match it as a
+ * prefix of the current tip so an abbreviated recorded tip still reads current once the full
+ * head shares that prefix. */
+export function parityIsCurrent(entry, tip, lockHash) {
+    return entry.result === "passed" && tip !== "" && tip.startsWith(entry.tip) && entry.lockHash === lockHash;
+}
+/** Shorten an id for display without losing its discriminating prefix (a 40-char sha and a
+ * 64-char lock hash both collapse to a 7-char prefix the model can compare). */
+function shortId(id) {
+    return id.length > 7 ? id.slice(0, 7) : id;
+}
+/** Render the parity block for the next `ci` prompt from the last record and the current
+ * main state. "current" only when the last run was green AND it covered exactly this tip with
+ * exactly this lock hash — the cheap nothing-to-do case. Every other combination — a failed
+ * last run, main moved, or the lock changed — renders "stale" naming both the covered and the
+ * current tip/hash, so the role runs the suite. */
+export function renderParityBlock(entry, tip, lockHash) {
+    const lines = ["CI parity (from this team's own record):"];
+    if (parityIsCurrent(entry, tip, lockHash)) {
+        lines.push(`  current — main is unmoved since the last green run covered tip ${shortId(entry.tip)} with lock ${shortId(entry.lockHash)}; declare nothing-to-do without running the suite.`);
+    }
+    else {
+        const covered = `${shortId(entry.tip)} @ ${shortId(entry.lockHash)} (${entry.result})`;
+        const now = tip === "" ? "could not be resolved" : `tip ${shortId(tip)} @ ${shortId(lockHash)}`;
+        lines.push(`  stale — the last run covered ${covered}; main is now ${now}. Run the full suite and e2e before declaring anything.`);
+    }
+    return lines.join("\n");
+}
+/** The full parity block for a `ci` prompt, or undefined when there is no record yet — a
+ * missing or malformed ledger must render nothing rather than an empty verdict, so the very
+ * first run carries no block and simply runs the suite (the same omission policy as qa's
+ * coverage block). */
+export function parityBlockFor(root, config) {
+    const record = readCiParity(root);
+    if (!record)
+        return undefined;
+    const { tip, lockHash } = currentCiParityState(root, config);
+    return renderParityBlock(record, tip, lockHash);
+}

package/dist/src/run/feedback-filings.js

@@ -0,0 +1,51 @@
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { feedbackFilingsPath } from "../paths.js";
+import { isJsonObject } from "../files/json-object.js";
+import { formatAge } from "../text/datetime.js";
+/** The `feedback` observer's per-install filing ledger (plans/feedback-role.md 2/2). Every
+ * `feedback` run starts a fresh pi session, so the only durable record of which GitHub issues
+ * this install already filed must live in harness state — the same cross-run memory qa's
+ * flow-coverage ledger provides (plans/observer-roles.md 2/2), and what makes the next run's
+ * prompt able to render a "previously filed" block so the charter's dedupe does not rely on the
+ * network alone. The ledger is gitignored runtime state under .tumwater/state/ and degrades to
+ * "no data" on any missing or malformed file: an observer must never fail a run on bookkeeping
+ * (a filing that fails to persist is a warning, never a run failure). */
+/** The newest bound the ledger keeps. A fresh session files at most one issue per run, so this
+ * caps the block's growth and the prompt's size; older filings are dropped (the charter still
+ * dedupes against the live `gh issue list`). */
+export const FEEDBACK_FILINGS_MAX = 100;
+function isFiling(value) {
+    if (!isJsonObject(value))
+        return false;
+    return (typeof value.issue === "number" &&
+        typeof value.title === "string" &&
+        typeof value.filedAt === "number");
+}
+/** Read the ledger, keeping only well-formed entries. A missing, torn, or wrong-shaped file
+ * reads as an empty ledger — the caller renders no block and the run proceeds as before. */
+export function readFeedbackFilings(root) {
+    const file = readJsonFile(feedbackFilingsPath(root));
+    const filings = file?.filings;
+    if (!Array.isArray(filings))
+        return [];
+    return filings.filter(isFiling);
+}
+/** Record that this install filed issue `issue` now (or at `now`, for tests). Reads-modifies-
+ * writes the whole ledger atomically so a concurrent writer cannot leave a torn file behind,
+ * and keeps only the newest FEEDBACK_FILINGS_MAX entries. */
+export function recordFiled(root, issue, title, now = Date.now()) {
+    const filings = readFeedbackFilings(root);
+    const entry = { issue, title, filedAt: now };
+    writeJsonAtomic(feedbackFilingsPath(root), {
+        filings: [entry, ...filings].slice(0, FEEDBACK_FILINGS_MAX),
+    });
+}
+/** Render the "previously filed" block for the next `feedback` prompt; undefined when the
+ * ledger is empty (the common first-run case), so the prompt is unchanged then. Newest-first,
+ * each line `#<n> <title> (<age>)` mirroring qa's coverage lines. */
+export function renderFilingsBlock(filings, now = Date.now()) {
+    if (filings.length === 0)
+        return undefined;
+    const lines = filings.map((f) => `  #${f.issue} ${f.title} (${formatAge(now - f.filedAt)})`);
+    return ["Previously filed from this install:", ...lines].join("\n");
+}

package/dist/src/run/qa-coverage.js

@@ -0,0 +1,125 @@
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { qaCoveragePath } from "../paths.js";
+import { isJsonObject, setOwn } from "../files/json-object.js";
+import { DAY_MS, formatAge } from "../text/datetime.js";
+/** The `qa` observer's flow-coverage ledger (plans/observer-roles.md 2/2). Every `qa` run
+ * starts a fresh pi session, so the only durable memory of which flow it last exercised is a
+ * runtime file the harness — not pi — maintains. A passing cheap check writes nothing into the
+ * repo (a note commit per check would move main and wake every sleeping role), so without this
+ * ledger the model picks a flow blind every run and converges on the top of its menu. The
+ * ledger is gitignored runtime state under .tumwater/state/ and degrades to "no data" on any
+ * missing or malformed file: an observer must never fail a run on bookkeeping. */
+/** The flows `qa` exercises, cheapest-first — the ordered menu from plans/qa-role.md, plus the
+ * expensive `run (real)` variant. The names are the universe the coverage block renders; a flow
+ * recorded by name but absent here (a project-specific flow) still renders, appended after. */
+export const QA_FLOWS = [
+    "init",
+    "status",
+    "logs",
+    "prompt",
+    "reset-counters",
+    "gui",
+    "tui",
+    "run",
+    "run (real)",
+];
+/** A coverage ledger whose newest exercise is older than this window is a stall: the `qa`
+ * role — the team's only flow-level observer, the one role that exercises the product's own
+ * flows like a user — has silently stopped recording any exercise (disabled, paused, wedged,
+ * or failing before it records). The doctor `qa coverage` warn and the standing `qa-stale`
+ * alert share this one threshold, mirroring `ciParityStalled`'s `CI_PARITY_STALE_MS`. */
+export const QA_COVERAGE_STALE_MS = 3 * DAY_MS;
+/** True only when the ledger has at least one well-formed entry and every entry's `lastRunAt`
+ * is older than the stall window (`now - max(lastRunAt) > QA_COVERAGE_STALE_MS`). An empty
+ * ledger — a missing file, or a project that never ran qa — is not a stall: "no record yet" is
+ * not "stopped recording", the same rule `ciParityStalled` applies to a missing parity record.
+ * This is the one stall predicate the doctor row (`checkQaCoverage`) and the alert
+ * (`qaCoverageAlert`) share, so the surfaces cannot disagree on when a quiet qa is a problem. */
+export function qaCoverageStalled(coverage, now) {
+    let newest = 0;
+    let has = false;
+    for (const entry of Object.values(coverage)) {
+        has = true;
+        if (entry.lastRunAt > newest)
+            newest = entry.lastRunAt;
+    }
+    return has && now - newest > QA_COVERAGE_STALE_MS;
+}
+function isResult(value) {
+    return value === "passed" || value === "bug";
+}
+/** Read the ledger, keeping only well-formed entries. A missing, torn, or wrong-shaped file
+ * reads as an empty ledger — the caller renders no block and the run proceeds as before. */
+export function readQaCoverage(root) {
+    const file = readJsonFile(qaCoveragePath(root));
+    const flows = file?.flows;
+    if (!isJsonObject(flows))
+        return {};
+    const out = {};
+    for (const [name, raw] of Object.entries(flows)) {
+        if (!isJsonObject(raw))
+            continue;
+        const entry = raw;
+        if (typeof entry.lastRunAt !== "number" || !isResult(entry.result))
+            continue;
+        setOwn(out, name, {
+            lastRunAt: entry.lastRunAt,
+            result: entry.result,
+            ...(typeof entry.summary === "string" ? { summary: entry.summary } : {}),
+        });
+    }
+    return out;
+}
+/** Record that `flow` was exercised now (or at `now`, for tests). Reads-modifies-writes the
+ * whole ledger atomically so a concurrent writer cannot leave a torn file behind. */
+export function recordFlow(root, flow, result, summary, now = Date.now()) {
+    const coverage = readQaCoverage(root);
+    setOwn(coverage, flow, { lastRunAt: now, result, ...(summary ? { summary } : {}) });
+    writeJsonAtomic(qaCoveragePath(root), { flows: coverage });
+}
+/** The coverage as ordered rows — the one universe (menu plus recorded project-specific flows)
+ * and one ordering (never-exercised first, then exercised stalest-first, ties in menu order)
+ * that the next `qa` prompt's block and the operator-facing views share, so they cannot drift.
+ * Never-exercised flows lead (age = ∞), then exercised flows oldest-first, so "exercise the
+ * flow at the top" actually rotates through the whole menu instead of re-picking whatever is
+ * cheapest. The flow universe is `QA_FLOWS` plus any recorded name (a project-specific flow
+ * still surfaces, appended after the menu). */
+export function coverageRows(coverage, now = Date.now()) {
+    const names = [...QA_FLOWS];
+    for (const name of Object.keys(coverage)) {
+        if (!names.includes(name))
+            names.push(name);
+    }
+    return names
+        .map((name, index) => ({ name, index, entry: coverage[name] }))
+        .sort((a, b) => {
+        const ageA = a.entry ? now - a.entry.lastRunAt : Number.POSITIVE_INFINITY;
+        const ageB = b.entry ? now - b.entry.lastRunAt : Number.POSITIVE_INFINITY;
+        if (ageA !== ageB)
+            return ageB - ageA; // stalest first; never-exercised (∞) leads
+        return a.index - b.index; // stable: keep the menu order among equals
+    })
+        .map(({ name, entry }) => ({
+        flow: name,
+        lastRunAt: entry?.lastRunAt ?? null,
+        result: entry?.result ?? null,
+        ...(entry?.summary !== undefined ? { summary: entry.summary } : {}),
+    }));
+}
+/** Render the coverage block for the next `qa` prompt — the same rows `coverageRows` orders,
+ * one line each (a two-space-prefixed row, never-exercised flows first). */
+export function renderCoverageBlock(coverage, now = Date.now()) {
+    const lines = coverageRows(coverage, now).map(({ flow, lastRunAt, result, summary }) => {
+        if (lastRunAt === null)
+            return `  ${flow} — never exercised`;
+        const age = formatAge(now - lastRunAt);
+        const status = result === "bug"
+            ? `bug filed (BUGS.md: "${summary ?? "see BUGS.md"}")`
+            : "passed";
+        return `  ${flow} — ${age} ago, ${status}`;
+    });
+    return [
+        "Flow coverage (from this team's own record; least recently exercised first):",
+        ...lines,
+    ].join("\n");
+}