@osdlc/repo-cleaner 0.17.2 → 0.18.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,5 @@ 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[];
+export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): RemoteRow[];

package/dist/branches.js

@@ -12,7 +12,7 @@
 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";
 /**
  * Five fields in one pass, so a repository costs one `for-each-ref`. The full
  * sha, so it compares with a PR's `headRefOid`.
@@ -23,7 +23,7 @@ const LOCAL_FORMAT = '%(refname:short)%09%(upstream:short)%09%(upstream:track)%0
  * 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 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,52 +31,45 @@ 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) {
+function noPrSentence(repo) {
     const provider = repo.provider;
     if (provider === null)
         return 'No PR lookup (no provider).';
     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({
+function branchRisks(unmerged, pr) {
+    return risksFor({
         'abandon-unmerged': unmerged,
         'confirm-open-pr': pr?.state === 'OPEN',
     });
@@ -137,25 +130,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 +153,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,85 +164,56 @@ 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 ────────────────────────────────────────────────────────
@@ -280,103 +236,67 @@ export function gatherRemoteBranches(repo, prs, localBranchNames, git, only, tic
     }
     return items;
 }
-export function classifyRemoteBranch(opts) {
-    const { name, sha, repo, prs, localBranchNames, git } = opts;
-    const id = `${repo.remote}/${name}`;
-    const facts = {
-        branch: name,
-        remote: repo.remote,
+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.
     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);
+    evidence.ancestorOfRemoteMain = isAncestor;
+    const pr = prs.get(branch);
+    const { landed, gap } = recordPr(evidence, 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.
     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 risks = branchRisks(unmerged, pr);
+    const commands = repo.remote === null ? [] : [remoteDeleteCommand(repo.remote, branch, sha)];
+    const deletes = (why) => row({ verdict: 'delete', action: 'delete', why, commands, risks });
+    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}.` : 'No PR found.');
     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,
     });
 }

package/dist/clean.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Cleaning up: `check` a plan against an approval, then `run` what it shows.
+ *
+ * `check` resolves the approval (the rows picked, the rows spared, the risks
+ * allowed), refuses one that contradicts itself, sweeps every plan repository
+ * again and drops each selected row that is gone, cannot be deleted, moved
+ * since the plan, or carries a risk not allowed. It returns the steps a run
+ * would take. `run` sweeps once more and takes those steps in a fixed order,
+ * stopping at the first failure:
+ *
+ * 1. spared remote branches, each tip checked with `ls-remote`;
+ * 2. worktrees, each unlocked first when its lock's owner is dead, and each
+ *    checked again for live processes just before it is unlocked or removed;
+ *    one with submodules is removed with `--force` after its files and every
+ *    submodule are checked again;
+ * 3. local branches;
+ * 4. remote branches.
+ *
+ * A worktree whose directory is gone goes by its own record. One left without
+ * its `.git` takes the repository-wide prune, last, and only while that prune
+ * would drop nothing the run does not select.
+ *
+ * Branch deletes are compare-and-swap on the planned sha. Every step is
+ * verified, and the receipt is rewritten after each.
+ */
+import type { Annotate } from './hooks.ts';
+import { type Plan } from './plan.ts';
+import { type Dropped, type Receipt, type Step } from './receipt.ts';
+import { type Runners } from './sweep.ts';
+import { type Kind, type Risk, type RowId, type Sweep, type SweepProgress, type SweptWith } from './types.ts';
+/** A risk allowed for every row (`row` absent), or for one row. */
+export interface Allow {
+    risk: Risk;
+    /** A row id or bare name, resolved as a pick is. */
+    row?: string | undefined;
+}
+/**
+ * What a person approved. Rows are named by id (`branch:feat/x`), or by a
+ * bare name or path when only one plan row has it.
+ *
+ *   `pick`   work on exactly these rows; a `review` row, or a `keep` row with
+ *            an action, runs only when picked. Default: every `delete` row.
+ *   `spare`  leave these rows alone; a spared remote branch is still checked,
+ *            and the run stops if it is gone or moved since the plan.
+ *   `allow`  the risks a row's action may carry.
+ */
+export interface Approval {
+    pick?: readonly string[] | undefined;
+    spare?: readonly string[] | undefined;
+    allow?: readonly (Risk | Allow)[] | undefined;
+}
+/** A row reference resolved to one plan row. */
+export interface Resolved {
+    repo: string;
+    id: RowId;
+}
+/** An approval with every row resolved to its plan row. */
+export interface ResolvedApproval {
+    pick: Resolved[];
+    spare: Resolved[];
+    allow: {
+        risk: Risk;
+        row: Resolved | null;
+    }[];
+}
+interface Shared extends Runners {
+    /** Where the caller stands: the base for relative worktree paths, and a worktree never removed. Defaults to the process's cwd. */
+    cwd?: string | undefined;
+    /** A host's re-ranking, applied to every re-sweep as the sweep applied it. */
+    annotate?: Annotate | undefined;
+    /** Told what the re-sweep is doing, for a status line. */
+    onProgress?: ((progress: SweepProgress) => void) | undefined;
+}
+export interface CheckOptions extends Shared {
+    /**
+     * A sweep made just now, used as the re-check instead of sweeping again: for
+     * a preview straight after a sweep. `run` always sweeps again.
+     */
+    sweep?: Sweep | undefined;
+    /** Where remote URL clones are kept; a plan repository there must still push only where it fetches from. */
+    cacheDir?: string | undefined;
+}
+export interface RunOptions extends Shared {
+    /** Where the receipt is rewritten after each step; none when absent. */
+    receiptPath?: string | undefined;
+    /** Where the plan came from, recorded in the receipt. Default `(memory)`. */
+    source?: string | undefined;
+    now?: (() => Date) | undefined;
+    /** Told once the steps are known, before the first runs; each step's `result` is updated in place. */
+    onStart?: ((steps: readonly Step[]) => void) | undefined;
+    /** Told before each step: its index, the step count and the step. */
+    onStep?: ((index: number, total: number, step: Step) => void) | undefined;
+    /** Told after each step, with its `result` set, before the receipt is saved. */
+    onStepDone?: ((index: number, total: number, step: Step) => void) | undefined;
+}
+/** What a run would do, for a person to approve: the steps, and the rows dropped and why. */
+export interface Preview {
+    plan: Plan;
+    approval: ResolvedApproval;
+    /** Each with `result: 'would-run'`. */
+    steps: Step[];
+    dropped: Dropped[];
+    /** Allowed risks no row that runs carries. Not an error: what a row carries can change between runs. */
+    unusedAllows: {
+        risk: Risk;
+        row: RowId | null;
+    }[];
+}
+/** A row reference as typed: a kind and a name, or a bare name (`kind: null`). */
+export interface RowRef {
+    kind: Kind | null;
+    name: string;
+}
+/**
+ * `kind:name`, or a bare name. A word before a colon that is not a kind is an
+ * error (a typo such as `wt:x`), but a path is a bare name whatever colons it
+ * holds: a prefix with a path separator in it is never a kind.
+ */
+export declare function parseRowRef(text: string): RowRef;
+/** `<risk>` for every row, or `<risk>=<row>` for one. */
+export declare function parseAllow(text: string): Allow;
+/**
+ * What can be refused of `approval` before anything is swept: a malformed
+ * row or risk, a row a sweep with `options` could never hold, and a row
+ * picked and spared as written. A row named two ways, and an `allow` for a
+ * spared or unpicked row, are found when the approval is resolved against
+ * the plan.
+ */
+export declare function checkApproval(options: Pick<SweptWith, 'only' | 'branch'>, approval: Approval): void;
+/**
+ * `approval` resolved against `plan`, or a {@link RepoCleanerError} for one
+ * that contradicts itself or names rows the plan does not have.
+ */
+export declare function resolveApproval(plan: Plan, approval: Approval, cwd: string): ResolvedApproval;
+/**
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export declare function networkRemoteKey(url: string): string | null;
+/**
+ * What running `plan` under `approval` would do now: sweeps every repository
+ * the selection is in again (or reads `opts.sweep`), and returns the steps
+ * and the rows dropped, with why. Deletes nothing.
+ *
+ * @throws RepoCleanerError for an approval that contradicts itself, names a
+ *   row the plan does not have or names one ambiguously, or spares a remote
+ *   branch that moved. Nothing has been touched.
+ */
+export declare function check(plan: Plan, approval: Approval, opts?: CheckOptions): Preview;
+/**
+ * Take the steps `preview` showed: sweeps again, drops a row that moved since
+ * the preview, and runs the rest in order, compare-and-swap, verifying each
+ * step and stopping at the first failure. Only what the preview showed runs; a
+ * row it dropped stays dropped.
+ *
+ * @throws RepoCleanerError (`spared-changed`) when a spared remote branch moved
+ *   since the preview. Nothing has been touched.
+ */
+export declare function run(preview: Preview, opts?: RunOptions): Receipt;
+export {};