tumwater 0.4.0 → 0.4.2

package/dist/src/backlog/backlog-archive.js

@@ -30,10 +30,9 @@ import { commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-ru
 import { mergeLockDir } from "../paths.js";
 import { plural } from "../text/phrases.js";
 import { collapseWhitespace, errorFirstLine, errorMessage } from "../text/text.js";
-import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle, parseEntryDetails } from "./backlog-md.js";
-import { actionableEntryRanges, strandedPlanEntries } from "./backlog-structure.js";
-import { appendBugEntryLocked } from "./backlog-write.js";
-import { formatDate } from "../text/datetime.js";
+import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle } from "./backlog-md.js";
+import { actionableEntryRanges } from "./backlog-index-data.js";
+import { strandedPlanEntries } from "./backlog-structure.js";
 /** The placeholder a role leaves under an emptied section: never archived content. */
 const PLACEHOLDER = /^_None yet\._$/;
 /** The text a new archive file starts with: a title, how to read the file, and the section
@@ -132,6 +131,57 @@ function entryBlocks(lines, entries) {
     }
     return out;
 }
+/** The selected entries of `entries`: the keep slice, or the baseKeys/park filter. */
+function selectArchiveEntries(entries, select) {
+    return "keep" in select
+        ? entries.slice(Math.max(0, select.keep))
+        : entries.filter((e) => !select.baseKeys.has(archiveKey(e.title)) && !(select.park?.has(archiveKey(e.title)) ?? false));
+}
+/** Add the 0-based live lines of `entries` to `into`. */
+function addEntryLines(entries, into) {
+    for (const e of entries)
+        for (let i = e.start - 1; i < e.end; i++)
+            into.add(i);
+}
+/** The bulk-archive split: the tail past the kept entries moves but for the dropped and staying
+ * entries, and a `_None yet._` placeholder stays in the live section, never in the archive.
+ * null when no entry sits past the kept ones. */
+function splitByKeep(lines, span, entries, keep, staying, droppedLine) {
+    const from = keep <= 0 ? span.heading + 1 : (entries[keep]?.start ?? 0) - 1;
+    if (from < 0)
+        return null; // no entry past the kept ones
+    // The tail moves but for the dropped and staying entries; a `_None yet._` placeholder stays
+    // in the live section, never in the archive. Staying entries follow the kept ones.
+    const stayLine = new Set();
+    addEntryLines(staying, stayLine);
+    const tail = [];
+    for (let i = from; i < span.end; i++)
+        if (!droppedLine.has(i) && !stayLine.has(i))
+            tail.push(lines[i] ?? "");
+    const moved = trimBlank(tail.filter((l) => !PLACEHOLDER.test(l.trim())));
+    const stayingBlocks = entryBlocks(lines, staying);
+    const head = keep <= 0 ? [] : trimBlank(lines.slice(span.heading + 1, from));
+    const kept = head.length > 0 && stayingBlocks.length > 0 ? [...head, "", ...stayingBlocks] : [...head, ...stayingBlocks];
+    return {
+        kept: kept.length === 0 ? tail.filter((l) => PLACEHOLDER.test(l.trim())).slice(0, 1) : kept,
+        moved,
+    };
+}
+/** The commit-time-sweep split: the kept body drops the moved and dropped lines, refusing when
+ * no archive exists and other content would stay in the live section. */
+function splitByBaseKeys(lines, span, archiveMd, moving, droppedLine) {
+    const leaves = new Set(droppedLine);
+    addEntryLines(moving, leaves);
+    let kept = [];
+    for (let i = span.heading + 1; i < span.end; i++)
+        if (!leaves.has(i))
+            kept.push(lines[i] ?? "");
+    kept = trimBlank(kept);
+    if (archiveMd === null && kept.some((l) => l.trim() !== "" && !PLACEHOLDER.test(l.trim())))
+        return null;
+    const moved = entryBlocks(lines, moving);
+    return { kept, moved };
+}
 /** Move the selected part of `liveMd`'s finished section to the top of `archiveMd`'s (a new
  * archive starts from archiveTemplate), keeping the moved lines' order. A selected entry whose
  * heading the archive already holds never moves (EntryFate): with the same text it is dropped
@@ -146,9 +196,7 @@ export function archiveFinishedText(liveMd, archiveMd, spec, select) {
     if (span === null)
         return null;
     const entries = entriesIn(liveMd, span, spec.section);
-    const selected = "keep" in select
-        ? entries.slice(Math.max(0, select.keep))
-        : entries.filter((e) => !select.baseKeys.has(archiveKey(e.title)) && !(select.park?.has(archiveKey(e.title)) ?? false));
+    const selected = selectArchiveEntries(entries, select);
     if (!("keep" in select) && selected.length === 0)
         return null;
     const archiveText = archiveMd ?? archiveTemplate(spec);
@@ -160,46 +208,14 @@ export function archiveFinishedText(liveMd, archiveMd, spec, select) {
     const withFate = (fate) => selected.filter((_, i) => fates[i] === fate);
     // The 0-based live lines of the entries that leave the live section without moving.
     const droppedLine = new Set();
-    for (const e of withFate("drop"))
-        for (let i = e.start - 1; i < e.end; i++)
-            droppedLine.add(i);
-    let moved;
-    let kept;
-    if ("keep" in select) {
-        const from = select.keep <= 0 ? span.heading + 1 : (entries[select.keep]?.start ?? 0) - 1;
-        if (from < 0)
-            return null; // no entry past the kept ones
-        // The tail moves but for the dropped and staying entries; a `_None yet._` placeholder stays
-        // in the live section, never in the archive. Staying entries follow the kept ones.
-        const stayLine = new Set();
-        for (const e of withFate("stay"))
-            for (let i = e.start - 1; i < e.end; i++)
-                stayLine.add(i);
-        const tail = [];
-        for (let i = from; i < span.end; i++)
-            if (!droppedLine.has(i) && !stayLine.has(i))
-                tail.push(lines[i] ?? "");
-        moved = trimBlank(tail.filter((l) => !PLACEHOLDER.test(l.trim())));
-        const staying = entryBlocks(lines, withFate("stay"));
-        const head = select.keep <= 0 ? [] : trimBlank(lines.slice(span.heading + 1, from));
-        kept = head.length > 0 && staying.length > 0 ? [...head, "", ...staying] : [...head, ...staying];
-        if (kept.length === 0)
-            kept = tail.filter((l) => PLACEHOLDER.test(l.trim())).slice(0, 1);
-    }
-    else {
-        const leaves = new Set(droppedLine);
-        for (const e of withFate("move"))
-            for (let i = e.start - 1; i < e.end; i++)
-                leaves.add(i);
-        kept = [];
-        for (let i = span.heading + 1; i < span.end; i++)
-            if (!leaves.has(i))
-                kept.push(lines[i] ?? "");
-        kept = trimBlank(kept);
-        if (archiveMd === null && kept.some((l) => l.trim() !== "" && !PLACEHOLDER.test(l.trim())))
-            return null;
-        moved = entryBlocks(lines, withFate("move"));
-    }
+    addEntryLines(withFate("drop"), droppedLine);
+    const split = "keep" in select
+        ? splitByKeep(lines, span, entries, select.keep, withFate("stay"), droppedLine)
+        : splitByBaseKeys(lines, span, archiveMd, withFate("move"), droppedLine);
+    if (split === null)
+        return null;
+    const moved = split.moved;
+    const kept = split.kept;
     const dropped = withFate("drop").map((e) => e.title);
     if (moved.length === 0 && dropped.length === 0)
         return null;
@@ -301,6 +317,15 @@ function archiveCommitWhat(plan) {
     const archived = `Archive ${plural(count, "finished entry", "finished entries")} to ${archives.join(" and ")}`;
     return dropped > 0 ? `${archived}; drop ${drop}` : archived;
 }
+/** One live backlog file's finished-history rows as liveFinishedHistory reports them, phrased
+ * and joined: `file ## <section> holds N finished entries (X KB)` rows separated by "; " — the
+ * shared detail head the doctor's `backlog archive` check (checkLiveFinished) and the always-on
+ * `backlog-archive` alert (src/ui/team-alert-backlog.ts) both render, so the row shape, the
+ * plural, and the KB rounding cannot drift between the two. Each caller appends its own trailing
+ * explanation, so the two texts stay byte-identical up to that suffix. */
+export function liveFinishedRowList(rows) {
+    return rows.map((l) => `${l.file} ## ${l.section} holds ${plural(l.entries, "finished entry", "finished entries")} (${Math.round(l.bytes / 1024)} KB)`).join("; ");
+}
 /** One archived file as a line of `tumwater archive`'s output and the team-start event: what
  * moved where, and what was dropped because the archive already held it. */
 export function describeArchivedFile(f) {
@@ -316,6 +341,17 @@ function planOrSkip(root, keep) {
         return { status: "skipped", reason: `a backlog file could not be read: ${errorFirstLine(err)}` };
     }
 }
+/** If the primary checkout is not on the base branch, the reason a main-side write should be
+ * skipped, else null. Both `archiveFinishedOnMain` and `fileBugsOnMain` (backlog-file-bugs.ts)
+ * guard on this before committing a backlog file. */
+export async function primaryOffBaseBranchReason(root) {
+    const primary = await currentBranch(root);
+    const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
+    if (primary !== base) {
+        return `your checkout is on ${primary ?? "a detached HEAD"}, not ${base}`;
+    }
+    return null;
+}
 /** The bulk archive, committed: move every live finished section of the primary checkout at
  * `root` (past its newest `keep` entries) to its archive file and commit the touched files on the
  * base branch as one `tumwater(operator):` commit. Holds the team's merge lock, so a merge
@@ -332,11 +368,9 @@ export async function archiveFinishedOnMain(root, opts = {}) {
     if (pre.length === 0)
         return { status: "nothing" };
     return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
-        const primary = await currentBranch(root);
-        const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
-        if (primary !== base) {
-            return { status: "skipped", reason: `your checkout is on ${primary ?? "a detached HEAD"}, not ${base}` };
-        }
+        const offBase = await primaryOffBaseBranchReason(root);
+        if (offBase !== null)
+            return { status: "skipped", reason: offBase };
         const files = FINISHED_ARCHIVES.flatMap((a) => [a.file, a.archive]);
         const status = await gitTry(root, "status", "--porcelain", "--", ...files);
         if (status === null)
@@ -402,121 +436,3 @@ export async function archiveAtTeamStart(root) {
         warnEventBestEffort(root, TUMWATER_SOURCE, `finished backlog entries were not archived: ${errorMessage(err)}`);
     }
 }
-/** The start of a quarantine entry's title for `test`, up to the date. appendBugEntryLocked
- * collapses whitespace in the title, so the test part is collapsed the same way; collapsing the
- * whole prefix would trim its trailing space. */
-function quarantineTitlePrefix(test) {
-    return collapseWhitespace(`\`${test}\` failed, then passed on the same tree`) + " (quarantined by tumwater ";
-}
-/** Output fenced into a bug body: a fence of its own length cannot be closed by the quoted text. */
-function fencedTail(tail) {
-    return ["~~~~", ...tail.replaceAll("~~~~", "~~~").split("\n").slice(-30), "~~~~"].join("\n");
-}
-/** File one BUGS.md `## Open` entry per given entry and commit BUGS.md on the base branch as one
- * `tumwater(operator):` commit (the subject built from the number of entries actually appended is
- * stamped under the operator role), under the merge lock and the primary-worktree lock exactly as
- * archiveFinishedOnMain does. Skipped,
- * writing nothing, when the primary checkout is off the base branch, BUGS.md has uncommitted
- * changes, or BUGS.md exists but cannot be read; a failed append or commit restores BUGS.md.
- * Every entry is appended verbatim as its own `## Open` heading — unless its `ifOpen` dedupe
- * matches an existing heading, which is reused instead — and the returned headings are the
- * entry headings in input order. */
-export async function fileBugsOnMain(root, entries, subject, opts = {}) {
-    return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
-        const primary = await currentBranch(root);
-        const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
-        if (primary !== base) {
-            return { status: "skipped", reason: `your checkout is on ${primary ?? "a detached HEAD"}, not ${base}` };
-        }
-        const status = await gitTry(root, "status", "--porcelain", "--", "BUGS.md");
-        if (status === null)
-            return { status: "skipped", reason: "could not read git status" };
-        if (status.trim() !== "" && !status.startsWith("??")) {
-            return { status: "skipped", reason: "BUGS.md has uncommitted changes" };
-        }
-        const file = path.join(root, "BUGS.md");
-        let before;
-        try {
-            before = readTextIfExists(file);
-        }
-        catch (err) {
-            return { status: "skipped", reason: `BUGS.md could not be read: ${errorFirstLine(err)}` };
-        }
-        const open = before === null ? [] : parseEntryDetails(before, "Open").map((e) => e.title);
-        const headings = [];
-        let appended = 0;
-        const restoreBugs = async () => {
-            await gitTry(root, "reset", "-q", "--", "BUGS.md");
-            if (before === null)
-                fs.rmSync(file, { force: true });
-            else
-                writeTextAtomic(file, before);
-        };
-        try {
-            for (const entry of entries) {
-                if (entry.ifOpen !== undefined) {
-                    const existing = entry.ifOpen(open);
-                    if (existing !== undefined) {
-                        headings.push(existing);
-                        continue;
-                    }
-                }
-                headings.push(appendBugEntryLocked(root, entry.title, entry.body));
-                appended++;
-            }
-        }
-        catch (err) {
-            await restoreBugs();
-            return { status: "skipped", reason: `a BUGS.md entry could not be written: ${errorFirstLine(err)}` };
-        }
-        if (appended === 0)
-            return { status: "filed", headings };
-        const commitSubject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
-        subject(appended));
-        try {
-            await git(root, "add", "--", "BUGS.md");
-            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", commitSubject, "--", "BUGS.md");
-        }
-        catch (err) {
-            await restoreBugs();
-            return { status: "skipped", reason: `the commit failed: ${errorFirstLine(err)}` };
-        }
-        return { status: "filed", headings };
-    }), opts.lockTimeoutMs);
-}
-/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
- * branch as one `tumwater(operator):` commit, delegating the locked write/commit to
- * fileBugsOnMain and preserving the existing subject. A test whose quarantine entry is already
- * under `## Open` (a filing whose markQuarantineFiled failed after the commit) gets that heading
- * back and is not filed again — the dedupe runs inside fileBugsOnMain under the merge lock (via
- * each entry's `ifOpen`), so concurrent quarantine filings cannot both append a duplicate, and
- * the real skip on a dirty or off-base BUGS.md is enforced under the same lock. */
-export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
-    const date = formatDate(new Date());
-    const toFile = [];
-    for (const { test, tail } of tests) {
-        const prefix = quarantineTitlePrefix(test);
-        const body = [
-            `The check failed on this test and then passed on a re-run of the same tree, so tumwater quarantined it: it counts as a known failure until this entry leaves \`## Open\`. Find why it is unstable and fix it.`,
-            ...(tail ? ["", fencedTail(tail)] : []),
-        ].join("\n");
-        toFile.push({
-            title: `${prefix}${date})`,
-            body,
-            // Dedupe under the lock, against the headings fileBugsOnMain reads: the reused heading
-            // (not a duplicate) is returned in headings and zipped back to this test below.
-            ifOpen: (open) => open.find((t) => t.startsWith(prefix)),
-        });
-    }
-    const outcome = await fileBugsOnMain(root, toFile, 
-    // Size the subject by what was actually appended: tests whose `## Open` entry was already
-    // present are reused, not filed, so a mixed batch keeps the original "File N …" wording
-    // with N the count of new entries only.
-    (appended) => `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`, opts);
-    if (outcome.status === "skipped")
-        return { status: "skipped", reason: outcome.reason };
-    // fileBugsOnMain's headings align with `tests` in order (reused headings or appended titles).
-    const bugs = new Map();
-    outcome.headings.forEach((heading, i) => bugs.set(tests[i].test, heading));
-    return { status: "filed", bugs };
-}

package/dist/src/backlog/backlog-cli-view.js

@@ -6,7 +6,7 @@ import { fail, say, sayJson } from "../cli/cli-output.js";
 import { parseCountFlag, rejectRepeatFlag, scanPositionArgs } from "../cli/cli-args.js";
 import { DONE_DATE_RE, FIXED_DATE_RE, completionDate, donePlanEntries, fixedBugEntries, openBugEntries, plannedPlanEntries, ageInDays, entryAgeSuffix, entryMatches, filingDate, } from "./backlog.js";
 import { backlogHolds, backlogInProgress, holdMark, inProgressMark } from "./backlog-eligibility.js";
-import { groupBlockedSeries, partsLabel } from "./backlog-structure.js";
+import { groupBlockedSeries, partsLabel } from "./backlog-index-data.js";
 import { rejectUnknownArgs } from "../cli/cli-flag-specs.js";
 import { refuseTeamWorkspace } from "../cli/cli-repo-gate.js";
 import { sectionNoun, showEntry } from "./backlog-write.js";
@@ -23,31 +23,12 @@ function positionRuns(positions) {
     }
     return runs.join(", ");
 }
-/** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
- * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same
- * entries, in the same file order, that locateEntry numbers for `--edit`/`--cancel`, pairs
- * each with its eligibility hold (backlogHolds), and prints them numbered from 1, or the
- * command's `no …` line on an empty or missing file. Like `tumwater backlog` and `tumwater
- * questions` it is read-only: no requireReadyRepo gate and no wake. `--list` and `--json` are
- * the two booleans this shell consumes (repeats refused), `--help`/`-h` is tolerated, and any
- * positional or other flag is refused through rejectUnknownArgs.
- *
- * `--grep <text>` searches the active entries too: it keeps the entries whose heading or
- * body contains the text (case-insensitive), each under its unfiltered number so a printed
- * position still reaches `--show`/`--edit`/`--cancel` — the active twin of the finished
- * entries' `--done --grep`.
- *
- * `--ready` keeps the entries with no hold under their unfiltered numbers (composes with
- * `--grep` and `--json`; refused with `--done`, whose entries carry no holds).
- *
- * `--done [-n <count>] [--grep <text>]` (each once; `-n` and `--grep` need `--done`) lists the
- * newest finished entries instead (BUGS.md ## Fixed or PLANS.md ## Done, numbered, default 10)
- * with `older` counting those left out; --json carries each entry's `position` and
- * `completedOn` heading date. `--grep` keeps the entries whose heading or body contains the
- * text (case-insensitive); each keeps its unfiltered number, so it is the `--show <n> --done`
- * number, and `older` counts matches left out. `plan --list` prose
- * groups a series' blocked parts into one line (groupBlockedSeries). */
-export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
+/** Scans the `--list` flag vocabulary (`--list`, `--json`, `--done`, `--ready`, `-n`, `--grep`,
+ * each once, plus tolerated `--help`/`-h`) into the parsed locals and returns them with `rest`,
+ * the leftover args rejectUnknownArgs will refuse. Reads no entry, filters nothing, prints
+ * nothing; the `fail` calls it makes are the flag-usage refusals (a repeat or a `--grep`/`-n`
+ * with missing text). */
+function parseListArgs(args, command) {
     let json = false;
     let list = false;
     let done = false;
@@ -95,52 +76,48 @@ export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
             continue;
         rest.push(arg);
     }
-    // rejectUnknownArgs names a stray positional and an unknown flag with this command's (empty)
-    // valid-flag list: the vocabulary a list invocation accepts is exactly --list and --json,
-    // both consumed above.
-    rejectUnknownArgs(command, rest, []);
-    refuseTeamWorkspace(root);
-    if (count !== null && !done)
-        fail("-n needs --done (it limits the finished entries listed)");
-    // BUGS.md's `## Open` is the one section whose noun is "bug"; every other caller is a plan.
-    if (ready && done)
-        fail("--ready needs the active list (finished entries carry no holds)");
-    const bugSection = sectionTitle === "Open";
-    if (done) {
-        const numbered = (bugSection ? fixedBugEntries(root) : donePlanEntries(root)).map((entry, i) => ({
-            entry,
-            position: i + 1,
-        }));
-        const pattern = grep;
-        const matches = pattern === null ? numbered : numbered.filter((m) => entryMatches(m.entry, pattern));
-        const limit = count ?? 10;
-        const shown = matches.slice(0, limit);
-        const older = matches.length - shown.length;
-        if (json) {
-            const dateRe = bugSection ? FIXED_DATE_RE : DONE_DATE_RE;
-            sayJson({
-                entries: shown.map(({ entry: e, position }) => ({
-                    position,
-                    title: e.title,
-                    body: e.body,
-                    completedOn: completionDate(e.title, dateRe),
-                })),
-                older,
-            });
-            return;
-        }
-        const what = bugSection ? "fixed bugs" : "done plans";
-        if (shown.length === 0) {
-            say(pattern === null ? `no ${what}` : `no ${what} match "${pattern}"`);
-            return;
-        }
-        const lines = shown.map((m) => `${m.position}. ${m.entry.title}`);
-        if (older > 0)
-            lines.push(`(${older} older; -n ${matches.length} shows more)`);
-        const header = pattern === null ? `${what} in ${fileName}, newest first:` : `${what} in ${fileName} matching "${pattern}", newest first:`;
-        say(`${header}\n${lines.join("\n")}`);
+    return { json, done, ready, count, grep, rest };
+}
+/** The `--done` half of the list shell: the newest finished entries (BUGS.md ## Fixed or
+ * PLANS.md ## Done), filtered by `--grep`, limited by `-n`, printed as `--json` or prose. */
+function announceFinishedList(root, fileName, bugSection, grep, count, json) {
+    const numbered = (bugSection ? fixedBugEntries(root) : donePlanEntries(root)).map((entry, i) => ({
+        entry,
+        position: i + 1,
+    }));
+    const pattern = grep;
+    const matches = pattern === null ? numbered : numbered.filter((m) => entryMatches(m.entry, pattern));
+    const limit = count ?? 10;
+    const shown = matches.slice(0, limit);
+    const older = matches.length - shown.length;
+    if (json) {
+        const dateRe = bugSection ? FIXED_DATE_RE : DONE_DATE_RE;
+        sayJson({
+            entries: shown.map(({ entry: e, position }) => ({
+                position,
+                title: e.title,
+                body: e.body,
+                completedOn: completionDate(e.title, dateRe),
+            })),
+            older,
+        });
+        return;
+    }
+    const what = bugSection ? "fixed bugs" : "done plans";
+    if (shown.length === 0) {
+        say(pattern === null ? `no ${what}` : `no ${what} match "${pattern}"`);
         return;
     }
+    const lines = shown.map((m) => `${m.position}. ${m.entry.title}`);
+    if (older > 0)
+        lines.push(`(${older} older; -n ${matches.length} shows more)`);
+    const header = pattern === null ? `${what} in ${fileName}, newest first:` : `${what} in ${fileName} matching "${pattern}", newest first:`;
+    say(`${header}\n${lines.join("\n")}`);
+}
+/** The active half of the list shell: the open entries with their holds, in-progress claim
+ * marks and age suffixes, optionally reduced to the ready ones, as `--json` or prose, grouping
+ * a plan's blocked parts into one line (groupBlockedSeries). */
+function announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json) {
     const entries = bugSection ? openBugEntries(root) : plannedPlanEntries(root);
     const holds = backlogHolds(root);
     const entryHolds = bugSection ? holds.bugs : holds.plans;
@@ -214,6 +191,48 @@ export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
         lines.push(hiddenNote);
     say(`${noun}s in ${fileName}:\n${lines.join("\n")}`);
 }
+/** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
+ * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same
+ * entries, in the same file order, that locateEntry numbers for `--edit`/`--cancel`, pairs
+ * each with its eligibility hold (backlogHolds), and prints them numbered from 1, or the
+ * command's `no …` line on an empty or missing file. Like `tumwater backlog` and `tumwater
+ * questions` it is read-only: no requireReadyRepo gate and no wake. `--list` and `--json` are
+ * the two booleans this shell consumes (repeats refused), `--help`/`-h` is tolerated, and any
+ * positional or other flag is refused through rejectUnknownArgs.
+ *
+ * `--grep <text>` searches the active entries too: it keeps the entries whose heading or
+ * body contains the text (case-insensitive), each under its unfiltered number so a printed
+ * position still reaches `--show`/`--edit`/`--cancel` — the active twin of the finished
+ * entries' `--done --grep`.
+ *
+ * `--ready` keeps the entries with no hold under their unfiltered numbers (composes with
+ * `--grep` and `--json`; refused with `--done`, whose entries carry no holds).
+ *
+ * `--done [-n <count>] [--grep <text>]` (each once; `-n` and `--grep` need `--done`) lists the
+ * newest finished entries instead (BUGS.md ## Fixed or PLANS.md ## Done, numbered, default 10)
+ * with `older` counting those left out; --json carries each entry's `position` and
+ * `completedOn` heading date. `--grep` keeps the entries whose heading or body contains the
+ * text (case-insensitive); each keeps its unfiltered number, so it is the `--show <n> --done`
+ * number, and `older` counts matches left out. `plan --list` prose
+ * groups a series' blocked parts into one line (groupBlockedSeries). */
+export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
+    const { json, done, ready, count, grep, rest } = parseListArgs(args, command);
+    // rejectUnknownArgs names a stray positional and an unknown flag with this command's (empty)
+    // valid-flag list: the vocabulary a list invocation accepts is exactly --list and --json,
+    // both consumed above.
+    rejectUnknownArgs(command, rest, []);
+    refuseTeamWorkspace(root);
+    if (count !== null && !done)
+        fail("-n needs --done (it limits the finished entries listed)");
+    // BUGS.md's `## Open` is the one section whose noun is "bug"; every other caller is a plan.
+    if (ready && done)
+        fail("--ready needs the active list (finished entries carry no holds)");
+    const bugSection = sectionTitle === "Open";
+    if (done)
+        announceFinishedList(root, fileName, bugSection, grep, count, json);
+    else
+        announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json);
+}
 /** The shell of `bug --show` and `plan --show`: `--show <n>` (once), an optional `--json`
  * and `--done` (each once; `--done` shows the Nth newest finished entry, as `--list --done`
  * numbers them, with its heading stamp kept and `completedOn` in --json),