@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/branches.d.ts

@@ -10,29 +10,21 @@
  * leaves the branch for a person to look at.
  */
 import { type Git } from '@osdlc/typed-git';
-import { type PRInfo, type PrEvidenceGap, type RepoInfo, type SweepItem } from './types.ts';
+import { type BranchRow, type LandingEvidence, type PRInfo, type PrEvidenceGap, type RemoteRow, type RepoInfo } from './types.ts';
 /**
- * True when merged `pr` proves `tip` landed: it targeted the default branch
- * and its head commit is `tip`. Fork PRs never reach here; `fetchPrs` drops
- * them. A PR with no reported head counts as `head-moved`.
- */
-export declare function prCapturesTip(pr: PRInfo, tip: string, repo: RepoInfo): true | PrEvidenceGap;
-/**
- * `facts.pr`, plus `evidence` for a merged PR: `exact-head` when it proves
+ * `evidence.pr`, plus `proof` for a merged PR: `exact-head` when it proves
  * `tip` landed, otherwise the gap. Returns whether it counts as landing proof.
  */
-export declare function recordPr(facts: Record<string, unknown>, pr: PRInfo | undefined, tip: string, repo: RepoInfo): {
+export declare function recordPr(evidence: LandingEvidence, pr: PRInfo | undefined, tip: string, repo: RepoInfo): {
     landed: boolean;
     gap: PrEvidenceGap | null;
 };
-/** Why a branch has no PR, naming where the sweep looked. */
-export declare function noPrSentence(repo: RepoInfo): string;
-/** One sentence on why a merged PR did not count, for `investigationParts`. */
+/** One sentence on why a merged PR did not count, for a row's notes. */
 export declare function gapSentence(pr: PRInfo, gap: PrEvidenceGap, repo: RepoInfo): string;
 /**
- * `facts.merged`: the work is on the default branch, by an exact-head merged
- * PR, by ancestry or by a patch match. Every category records it this way, so
- * `summary` counts one definition.
+ * `evidence.merged`: the work is on the default branch, by an exact-head
+ * merged PR, by ancestry or by a patch match. Every kind records it this way,
+ * so the counts use one definition.
  */
 export declare function mergedFact(e: {
     landed: boolean;
@@ -52,24 +44,33 @@ export declare const HELD_BY_WORKTREE = "checked out in a worktree (handle via t
 export declare function localDeleteCommand(name: string, sha: string): string;
 /** Delete `remote`'s branch `name` only while it still points at `sha`. */
 export declare function remoteDeleteCommand(remote: string, name: string, sha: string): string;
-export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
-export declare function classifyLocalBranch(opts: {
-    name: string;
-    upstream: string;
-    track: string;
-    lastCommit: string;
-    sha: string;
-    repo: RepoInfo;
-    prs: Map<string, PRInfo>;
-    worktreeBranches: ReadonlySet<string>;
-    git: Git;
-}): SweepItem;
-export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
-export declare function classifyRemoteBranch(opts: {
-    name: string;
-    sha: string;
-    repo: RepoInfo;
-    prs: Map<string, PRInfo>;
-    localBranchNames: ReadonlySet<string>;
-    git: Git;
-}): SweepItem;
+export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): BranchRow[];
+/** Remote branch rows, and the repository note when their tips had to come from disk. */
+export interface RemoteBranches {
+    rows: RemoteRow[];
+    /**
+     * Why the tips are not the remote's own: a live listing failed and they
+     * came from disk, or offline there were none on disk. Null otherwise.
+     */
+    note: string | null;
+}
+/**
+ * Remote branches, judged. With `live` the tips are the remote's own, read
+ * with `ls-remote`, which also sees branches a narrowed fetch refspec leaves
+ * out: after a fetch, and in `clean`'s re-check, which must see the remote as
+ * it is before deleting on it. Without it, as `--offline` asks of the report
+ * and `plan`, they are the remote-tracking refs on disk
+ * (`refs/remotes/<remote>/`), and the remote is not contacted.
+ *
+ * A live listing that fails is not "the remote has no branches" and not a
+ * reason to lose the repository's other rows: the tips come from disk
+ * instead, and each row and the returned note say so. With `strict` (`clean`'s
+ * re-check when nothing was fetched) the refs on disk are what the re-check
+ * is there to replace, so a failed listing throws instead.
+ */
+export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, opts: {
+    live: boolean;
+    strict?: boolean | undefined;
+    only?: string | undefined;
+    tick?: ((done: number, total: number) => void) | undefined;
+}): RemoteBranches;

package/dist/branches.js

@@ -12,7 +12,9 @@
 import { shellJoin } from '@osdlc/command-seam';
 import { forceWithLeaseArg } from '@osdlc/typed-git';
 import { confirmationNote, judgeLanding, landingConfirmed, recordLanding, unmatchedSentence, } from "./landing.js";
-import { authorizationsFor, landedRef, makeItem, } from "./types.js";
+import { landedRef, makeRow, risksFor, } from "./types.js";
+import { prsUnchecked } from "./prs.js";
+import { errorText } from "./util.js";
 /**
  * Five fields in one pass, so a repository costs one `for-each-ref`. The full
  * sha, so it compares with a PR's `headRefOid`.
@@ -20,10 +22,10 @@ import { authorizationsFor, landedRef, makeItem, } from "./types.js";
 const LOCAL_FORMAT = '%(refname:short)%09%(upstream:short)%09%(upstream:track)%09%(committerdate:iso8601-strict)%09%(objectname)';
 /**
  * True when merged `pr` proves `tip` landed: it targeted the default branch
- * and its head commit is `tip`. Fork PRs never reach here; `fetchPrs` drops
+ * and its head commit is `tip`. Fork PRs never reach here; the provider drops
  * them. A PR with no reported head counts as `head-moved`.
  */
-export function prCapturesTip(pr, tip, repo) {
+function prCapturesTip(pr, tip, repo) {
     if (pr.baseRef !== repo.mainBranch)
         return 'other-base';
     if (pr.headOid === null || pr.headOid !== tip)
@@ -31,54 +33,58 @@ export function prCapturesTip(pr, tip, repo) {
     return true;
 }
 /**
- * `facts.pr`, plus `evidence` for a merged PR: `exact-head` when it proves
+ * `evidence.pr`, plus `proof` for a merged PR: `exact-head` when it proves
  * `tip` landed, otherwise the gap. Returns whether it counts as landing proof.
  */
-export function recordPr(facts, pr, tip, repo) {
+export function recordPr(evidence, pr, tip, repo) {
     if (pr === undefined)
         return { landed: false, gap: null };
-    const out = {
-        number: pr.number,
-        state: pr.state,
-        merged_at: pr.mergedAt,
-        url: pr.url,
-        title: pr.title,
-        head_oid: pr.headOid,
-        base_ref: pr.baseRef,
-    };
-    facts['pr'] = out;
+    const { headRef: _, ...rest } = pr;
+    const out = rest;
+    evidence.pr = out;
     if (pr.state !== 'MERGED')
         return { landed: false, gap: null };
     const verdict = prCapturesTip(pr, tip, repo);
-    out['evidence'] = verdict === true ? 'exact-head' : verdict;
+    out.proof = verdict === true ? 'exact-head' : verdict;
     return verdict === true ? { landed: true, gap: null } : { landed: false, gap: verdict };
 }
-/** Why a branch has no PR, naming where the sweep looked. */
-export function noPrSentence(repo) {
+/** Why a branch has no PR, naming where the sweep looked, or why it could not. */
+function noPrSentence(repo) {
     const provider = repo.provider;
     if (provider === null)
         return 'No PR lookup (no provider).';
+    // The provider's own error is in the repository's note, not on every row.
+    const unchecked = prsUnchecked(provider);
+    if (unchecked !== null)
+        return `No ${provider.noun} lookup (${unchecked.why}).`;
     return `No ${provider.noun} found via \`${provider.listing}\`.`;
 }
-/** One sentence on why a merged PR did not count, for `investigationParts`. */
+/** One sentence on why a merged PR did not count, for a row's notes. */
 export function gapSentence(pr, gap, repo) {
     return gap === 'other-base'
         ? `PR #${pr.number} merged into \`${pr.baseRef}\`, not \`${repo.mainBranch}\`, so it is not landing proof (other-base).`
         : `PR #${pr.number} merged at head ${pr.headOid ?? '(unknown)'}, which is not this tip, so it is not landing proof (head-moved).`;
 }
 /**
- * `facts.merged`: the work is on the default branch, by an exact-head merged
- * PR, by ancestry or by a patch match. Every category records it this way, so
- * `summary` counts one definition.
+ * `evidence.merged`: the work is on the default branch, by an exact-head
+ * merged PR, by ancestry or by a patch match. Every kind records it this way,
+ * so the counts use one definition.
  */
 export function mergedFact(e) {
     return e.landed || e.ancestor || e.patchLanded;
 }
-/** What deleting a branch needs: its unlanded commits, and its open PR. */
-function branchRequires(unmerged, pr) {
-    return authorizationsFor({
+/**
+ * What deleting a branch needs: its unlanded commits, and its open PR.
+ *
+ * @param prUnknown No PR is known for the branch, and open PRs could not be
+ *   checked: the provider's CLI is missing or signed out, or its listing
+ *   failed. A remote branch is then treated as having an open PR: deleting a
+ *   PR's head branch closes the PR, and nothing here can say there is none.
+ */
+function branchRisks(unmerged, pr, prUnknown = false) {
+    return risksFor({
         'abandon-unmerged': unmerged,
-        'confirm-open-pr': pr?.state === 'OPEN',
+        'confirm-open-pr': pr?.state === 'OPEN' || prUnknown,
     });
 }
 /** `HEAD` as the branch checked out at `git`'s directory; any other name as given. */
@@ -137,25 +143,17 @@ export function gatherLocalBranches(repo, prs, worktreeBranches, git, only, tick
     }
     return items;
 }
-export function classifyLocalBranch(opts) {
+function classifyLocalBranch(opts) {
     const { name, upstream, track, lastCommit, sha, repo, prs, worktreeBranches, git } = opts;
-    const facts = {
+    const evidence = {
         branch: name,
         upstream: upstream || null,
         track: track || null,
-        last_commit: lastCommit,
+        lastCommit,
         sha,
     };
-    const keep = (reason, extra = {}) => makeItem({
-        category: 'local_branch',
-        id: name,
-        classification: 'safe-to-keep',
-        action: 'keep',
-        reason,
-        facts,
-        ...extra,
-    });
-    const pinned = (reason) => keep(reason, { deletable: false });
+    const row = (r) => makeRow({ kind: 'branch', name, evidence, ...r });
+    const pinned = (why) => row({ verdict: 'keep', action: null, why });
     if (name === repo.mainBranch)
         return pinned('default branch');
     const held = name === repo.currentBranch
@@ -168,8 +166,8 @@ export function classifyLocalBranch(opts) {
         // an exact-head merged PR, without the patch checks a deletable row gets.
         // `soft`: a missing default ref reads as not merged.
         const pr = prs.get(name);
-        const { landed } = recordPr(facts, pr, sha, repo);
-        facts['merged'] = mergedFact({
+        const { landed } = recordPr(evidence, pr, sha, repo);
+        evidence.merged = mergedFact({
             landed,
             ancestor: git.at(repo.root).soft.isAncestor(sha, landedRef(repo)),
             patchLanded: false,
@@ -179,204 +177,209 @@ export function classifyLocalBranch(opts) {
     // Work merged only into an unpushed local default has not landed. A missing
     // remote-tracking ref exits 128: ancestry unknown (null).
     const compareRef = landedRef(repo);
-    facts['compare_against'] = compareRef;
+    evidence.compareAgainst = compareRef;
     const ancestry = git.at(repo.root).try.isAncestor(name, compareRef);
     const ancestor = ancestry.ok ? ancestry.value : null;
-    facts['ancestor_of_remote_main'] = ancestor;
+    evidence.ancestorOfRemoteMain = ancestor;
     const isAncestor = ancestor === true;
     const pr = prs.get(name);
-    const { landed, gap } = recordPr(facts, pr, sha, repo);
+    const { landed, gap } = recordPr(evidence, pr, sha, repo);
     // Rebase merges, cherry-picks and squash merges leave the tip off the default
     // branch; the patches say whether the work is there anyway.
     const patch = landed || isAncestor ? null : judgeLanding(repo, sha, pr, gap, git);
     if (patch !== null)
-        recordLanding(facts, patch);
+        recordLanding(evidence, patch);
     const patchLanded = patch !== null && patch.check !== null;
     const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
-    facts['merged'] = mergedFact({ landed, ancestor: isAncestor, patchLanded });
+    evidence.merged = mergedFact({ landed, ancestor: isAncestor, patchLanded });
     if (!landed && !isAncestor) {
-        facts['unique_commits'] = git.at(repo.root).aheadBehind(repo.mainBranch, sha).ahead;
-    }
-    const requires = branchRequires(unmerged, pr);
-    const deleteCmd = [localDeleteCommand(name, sha)];
-    if (pr && landed) {
-        return makeItem({
-            category: 'local_branch',
-            id: name,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `PR #${pr.number} merged`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
-    }
-    if (isAncestor) {
-        return makeItem({
-            category: 'local_branch',
-            id: name,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `fully merged into ${compareRef}`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
+        evidence.uniqueCommits = git.at(repo.root).aheadBehind(repo.mainBranch, sha).ahead;
     }
+    const risks = branchRisks(unmerged, pr);
+    const commands = [localDeleteCommand(name, sha)];
+    const deletes = (why) => row({ verdict: 'delete', action: 'delete', why, commands, risks });
+    if (pr && landed)
+        return deletes(`PR #${pr.number} merged`);
+    if (isAncestor)
+        return deletes(`fully merged into ${compareRef}`);
     if (patchLanded) {
-        return makeItem({
-            category: 'local_branch',
-            id: name,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `patch-equivalent to commits on ${compareRef} (${patch.check}); ${confirmationNote(patch)}`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
+        return deletes(`patch-equivalent to commits on ${compareRef} (${patch.check}); ${confirmationNote(patch)}`);
+    }
+    if (pr && pr.state === 'OPEN') {
+        return row({ verdict: 'keep', action: 'delete', why: `open PR #${pr.number}`, commands, risks });
     }
-    if (pr && pr.state === 'OPEN')
-        return keep(`open PR #${pr.number}`, { requires });
     const lead = ancestor === null
         ? `Remote default branch \`${compareRef}\` was not found, so ancestry is unknown.`
         : `Branch \`${name}\` is not an ancestor of \`${compareRef}\`.`;
-    const parts = [lead];
-    parts.push(upstream ? `Tracks \`${upstream}\` (${track || 'in sync'}).` : 'Has no upstream.');
-    parts.push(pr ? `Associated PR #${pr.number} is ${pr.state} (${pr.url}).` : noPrSentence(repo));
+    const notes = [lead];
+    notes.push(upstream ? `Tracks \`${upstream}\` (${track || 'in sync'}).` : 'Has no upstream.');
+    notes.push(pr ? `Associated PR #${pr.number} is ${pr.state} (${pr.url}).` : noPrSentence(repo));
     if (pr && gap)
-        parts.push(gapSentence(pr, gap, repo));
+        notes.push(gapSentence(pr, gap, repo));
     const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
     if (unmatched !== null)
-        parts.push(unmatched);
-    parts.push(`Last commit: ${lastCommit} (${sha}).`);
-    return makeItem({
-        category: 'local_branch',
-        id: name,
-        classification: 'needs-investigation',
-        action: 'review',
-        reason: 'mixed or absent signals',
-        facts,
-        investigationParts: parts,
-        requires,
+        notes.push(unmatched);
+    notes.push(`Last commit: ${lastCommit} (${sha}).`);
+    return row({
+        verdict: 'review',
+        action: 'delete',
+        why: 'mixed or absent signals',
+        commands,
+        notes,
+        risks,
     });
 }
-// ── remote branches ────────────────────────────────────────────────────────
-export function gatherRemoteBranches(repo, prs, localBranchNames, git, only, tick) {
-    if (repo.remote === null)
-        return [];
-    // Default door: an unreachable remote throws rather than rendering as "the
-    // remote has no branches". `[]` here means the remote really has none.
-    const pattern = only === undefined ? undefined : `refs/heads/${only}`;
-    const rows = git.at(repo.root).lsRemote(repo.remote, pattern, { heads: true });
+/**
+ * Remote branches, judged. With `live` the tips are the remote's own, read
+ * with `ls-remote`, which also sees branches a narrowed fetch refspec leaves
+ * out: after a fetch, and in `clean`'s re-check, which must see the remote as
+ * it is before deleting on it. Without it, as `--offline` asks of the report
+ * and `plan`, they are the remote-tracking refs on disk
+ * (`refs/remotes/<remote>/`), and the remote is not contacted.
+ *
+ * A live listing that fails is not "the remote has no branches" and not a
+ * reason to lose the repository's other rows: the tips come from disk
+ * instead, and each row and the returned note say so. With `strict` (`clean`'s
+ * re-check when nothing was fetched) the refs on disk are what the re-check
+ * is there to replace, so a failed listing throws instead.
+ */
+export function gatherRemoteBranches(repo, prs, localBranchNames, git, opts) {
+    const remote = repo.remote;
+    if (remote === null)
+        return { rows: [], note: null };
+    const { only, tick } = opts;
+    let tips = null;
+    let note = null;
+    if (opts.live) {
+        const pattern = only === undefined ? undefined : `refs/heads/${only}`;
+        const listed = git.at(repo.root).try.lsRemote(remote, pattern, { heads: true });
+        if (listed.ok) {
+            tips = listed.value.flatMap(({ sha, ref }) => ref.startsWith('refs/heads/') ? [{ name: ref.slice('refs/heads/'.length), sha }] : []);
+        }
+        else if (opts.strict === true) {
+            throw new Error(`\`git ls-remote ${remote}\` failed (${errorText(listed.error)}); clean deletes on a remote only after asking it, so nothing was run`);
+        }
+        else {
+            note = `\`git ls-remote ${remote}\` failed (${errorText(listed.error)}); remote branches are read from the remote-tracking refs on disk.`;
+        }
+    }
+    if (tips === null) {
+        tips = trackingTips(repo.root, remote, git, only);
+        // A fetched remote has at least its default branch on disk; none at all
+        // means it was never fetched, or its refs live somewhere else.
+        if (!opts.live && tips.length === 0 && only === undefined) {
+            note = `No remote-tracking refs for \`${remote}\` on disk, so no remote branches to judge; fetch it once, or drop \`--offline\`.`;
+        }
+    }
     const items = [];
-    for (const [i, { sha, ref }] of rows.entries()) {
-        tick?.(i, rows.length);
-        if (!ref.startsWith('refs/heads/'))
-            continue;
-        const name = ref.slice('refs/heads/'.length);
+    for (const [i, { name, sha }] of tips.entries()) {
+        tick?.(i, tips.length);
         if (only !== undefined && name !== only)
             continue;
-        items.push(classifyRemoteBranch({ name, sha, repo, prs, localBranchNames, git }));
+        const row = classifyRemoteBranch({ name, sha, repo, prs, localBranchNames, git });
+        if (note !== null) {
+            row.notes.push(`Tip read from \`refs/remotes/${remote}/${name}\` on disk: \`git ls-remote\` failed.`);
+        }
+        items.push(row);
     }
-    return items;
+    return { rows: items, note };
 }
-export function classifyRemoteBranch(opts) {
-    const { name, sha, repo, prs, localBranchNames, git } = opts;
-    const id = `${repo.remote}/${name}`;
-    const facts = {
-        branch: name,
-        remote: repo.remote,
+/**
+ * `remote`'s branches as its remote-tracking refs on disk record them, under
+ * the default `refs/remotes/<remote>/` layout. The symbolic `HEAD` is not a
+ * branch.
+ */
+function trackingTips(root, remote, git, only) {
+    const prefix = `refs/remotes/${remote}/`;
+    const at = git.at(root);
+    // Git allows `/` in a remote's name: `origin/mirror`'s refs sit under
+    // `refs/remotes/origin/` too, and are not `origin`'s branches.
+    const nested = at
+        .remotes()
+        .filter((r) => r.startsWith(`${remote}/`))
+        .map((r) => `refs/remotes/${r}/`);
+    return at.refs(only === undefined ? prefix : `${prefix}${only}`).flatMap(({ sha, ref }) => {
+        if (nested.some((p) => ref.startsWith(p)))
+            return [];
+        const name = ref.slice(prefix.length);
+        return name === 'HEAD' ? [] : [{ name, sha }];
+    });
+}
+function classifyRemoteBranch(opts) {
+    const { name: branch, sha, repo, prs, localBranchNames, git } = opts;
+    const remote = repo.remote ?? '';
+    const name = `${remote}/${branch}`;
+    const evidence = {
+        branch,
+        remote,
         sha,
-        has_local: localBranchNames.has(name),
+        hasLocal: localBranchNames.has(branch),
     };
-    const keep = (reason, extra = {}) => makeItem({
-        category: 'remote_branch',
-        id,
-        classification: 'safe-to-keep',
-        action: 'keep',
-        reason,
-        facts,
-        ...extra,
-    });
-    if (name === repo.mainBranch)
-        return keep('default branch', { deletable: false });
+    const row = (r) => makeRow({ kind: 'remote', name, evidence, ...r });
+    if (branch === repo.mainBranch)
+        return row({ verdict: 'keep', action: null, why: 'default branch' });
     const remoteMain = landedRef(repo);
-    // `soft`: `sha` comes from `ls-remote`, so the clone may never have fetched
-    // it, and `remoteMain` may not exist either. Both exit 128; this row renders
-    // "cannot tell" as false.
+    // `soft`: `sha` may come from `ls-remote`, so the clone may never have
+    // fetched it, and `remoteMain` may not exist either. Both exit 128; this row
+    // renders "cannot tell" as false.
     const isAncestor = git.at(repo.root).soft.isAncestor(sha, remoteMain);
-    facts['ancestor_of_remote_main'] = isAncestor;
-    const pr = prs.get(name);
-    const { landed, gap } = recordPr(facts, pr, sha, repo);
-    // `sha` came from `ls-remote` and may not be in this clone; the check then
-    // finds nothing and the branch stays unlanded.
+    evidence.ancestorOfRemoteMain = isAncestor;
+    const pr = prs.get(branch);
+    const { landed, gap } = recordPr(evidence, pr, sha, repo);
+    // A `sha` from `ls-remote` may not be in this clone; the check then finds
+    // nothing and the branch stays unlanded.
     const patch = landed || isAncestor ? null : judgeLanding(repo, sha, pr, gap, git);
     if (patch !== null)
-        recordLanding(facts, patch);
+        recordLanding(evidence, patch);
     const patchLanded = patch !== null && patch.check !== null;
     const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
-    facts['merged'] = mergedFact({ landed, ancestor: isAncestor, patchLanded });
+    evidence.merged = mergedFact({ landed, ancestor: isAncestor, patchLanded });
     if (!landed && !isAncestor) {
         // Unknown (null) when the clone lacks `sha` or `remoteMain`, as above.
         const counted = git.at(repo.root).try.aheadBehind(remoteMain, sha);
-        facts['unique_commits'] = counted.ok ? counted.value.ahead : null;
-    }
-    const requires = branchRequires(unmerged, pr);
-    const deleteCmd = repo.remote === null ? [] : [remoteDeleteCommand(repo.remote, name, sha)];
-    if (pr && landed) {
-        return makeItem({
-            category: 'remote_branch',
-            id,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `PR #${pr.number} merged (auto-delete didn't fire)`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
-    }
-    if (isAncestor) {
-        return makeItem({
-            category: 'remote_branch',
-            id,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `fully merged into ${remoteMain}`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
+        evidence.uniqueCommits = counted.ok ? counted.value.ahead : null;
     }
+    const status = repo.provider;
+    // `--provider none` is a choice that this remote has no forge; anything else
+    // that left PRs unchecked means one could be open.
+    const unchecked = status === null || pr !== undefined ? null : prsUnchecked(status);
+    const unknownPr = status === null || unchecked === null
+        ? null
+        : `Whether it has an open ${status.noun} is unknown (${unchecked.why}), so deleting it needs confirm-open-pr.`;
+    const risks = branchRisks(unmerged, pr, unknownPr !== null);
+    const commands = repo.remote === null ? [] : [remoteDeleteCommand(repo.remote, branch, sha)];
+    const deletes = (why) => row({
+        verdict: 'delete',
+        action: 'delete',
+        why,
+        commands,
+        risks,
+        notes: unknownPr === null ? [] : [unknownPr],
+    });
+    if (pr && landed)
+        return deletes(`PR #${pr.number} merged (auto-delete didn't fire)`);
+    if (isAncestor)
+        return deletes(`fully merged into ${remoteMain}`);
     if (patchLanded) {
-        return makeItem({
-            category: 'remote_branch',
-            id,
-            classification: 'safe-to-delete',
-            action: 'delete',
-            reason: `patch-equivalent to commits on ${remoteMain} (${patch.check}); ${confirmationNote(patch)}`,
-            facts,
-            commands: deleteCmd,
-            requires,
-        });
+        return deletes(`patch-equivalent to commits on ${remoteMain} (${patch.check}); ${confirmationNote(patch)}`);
+    }
+    if (pr && pr.state === 'OPEN') {
+        return row({ verdict: 'keep', action: 'delete', why: `open PR #${pr.number}`, commands, risks });
     }
-    if (pr && pr.state === 'OPEN')
-        return keep(`open PR #${pr.number}`, { requires });
-    const parts = [`Remote branch \`${id}\` is not an ancestor of \`${remoteMain}\`.`];
-    parts.push(pr ? `Associated PR #${pr.number} is ${pr.state}.` : 'No PR found.');
+    const notes = [`Remote branch \`${name}\` is not an ancestor of \`${remoteMain}\`.`];
+    notes.push(pr ? `Associated PR #${pr.number} is ${pr.state}.` : (unknownPr ?? noPrSentence(repo)));
     if (pr && gap)
-        parts.push(gapSentence(pr, gap, repo));
+        notes.push(gapSentence(pr, gap, repo));
     const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
     if (unmatched !== null)
-        parts.push(unmatched);
-    parts.push('Decide whether to push more work, delete, or leave it as long-lived.');
-    return makeItem({
-        category: 'remote_branch',
-        id,
-        classification: 'needs-investigation',
-        action: 'review',
-        reason: 'mixed or absent signals',
-        facts,
-        investigationParts: parts,
-        requires,
+        notes.push(unmatched);
+    notes.push('Decide whether to push more work, delete, or leave it as long-lived.');
+    return row({
+        verdict: 'review',
+        action: 'delete',
+        why: 'mixed or absent signals',
+        commands,
+        notes,
+        risks,
     });
 }