@osdlc/repo-cleaner 0.17.2 → 0.18.0

package/dist/types.d.ts

@@ -1,43 +1,219 @@
 /**
  * The inventory a sweep produces, and the vocabulary it is described in.
  *
- * One shape serves every category. A caller that wants only worktrees filters
- * by `category` rather than reading a different type, and a host that adds its
- * own knowledge (an issue tracker's linkage, say) rewrites rows in place.
+ * A sweep returns rows. Each row is one thing that could be deleted — a
+ * worktree, a local branch, a remote branch — with the sweep's verdict on it,
+ * the action that would delete it, the risks that action carries, and the
+ * evidence behind it all. A host that knows more than git does rewrites rows
+ * through the `annotate` hook rather than reaching into classification.
  */
+import type { LandingCheck } from './landing.ts';
+import type { Plan } from './plan.ts';
+import type { ProcessHolder } from './processes.ts';
 import type { ProviderStatus } from './providers/types.ts';
-/** What the sweep concluded about an item. */
-export type Classification = 'safe-to-delete' | 'safe-to-keep' | 'needs-investigation';
-/** The kinds of thing a sweep inventories. */
-export type Category = 'local_branch' | 'worktree' | 'remote_branch';
+/** The kinds of row, in the order a run acts on them. */
+export declare const KINDS: readonly ["worktree", "branch", "remote"];
+/** A worktree, a local branch, or a branch on a remote. */
+export type Kind = (typeof KINDS)[number];
 /**
- * What a sweep is doing, for a status line. `repo` is the path being swept;
- * `index` and `of` place it among the run's repositories. `done` and `total`
- * count items within a step that walks many.
+ * A row's name with its kind in front: `worktree:<path>`, `branch:<name>`,
+ * `remote:<remote>/<name>`. Unique within a repository.
  */
-export interface SweepProgress {
-    repo: string;
-    index: number;
-    of: number;
-    step: 'discover' | 'fetch' | 'prs' | 'worktrees' | 'local-branches' | 'remote-branches';
-    done?: number;
-    total?: number;
-    /** The CLI asked during the `prs` step: `gh`, `glab`. */
-    tool?: string;
-}
-/** Which categories to gather. */
-export declare const ALL_SCOPES: readonly ["local-branches", "worktrees", "remote-branches"];
-export type Scope = (typeof ALL_SCOPES)[number];
+export type RowId = `${Kind}:${string}`;
+/** The row id of `name` in `kind`. */
+export declare function rowId(kind: Kind, name: string): RowId;
+/**
+ * `<kind>:<name>` split, or null when `text` has no kind in front. A
+ * one-letter prefix is a Windows drive (`C:\\…`), not a kind.
+ */
+export declare function parseRowId(text: string): {
+    kind: Kind;
+    name: string;
+} | null;
+/**
+ * What the sweep concluded about a row.
+ *
+ *   `delete`   its work is on the default branch, or it is otherwise safe to lose
+ *   `review`   the signals are mixed, or it holds work; deleted only when picked
+ *   `keep`     structural (the default branch, the current checkout), or in use
+ *              (an open pull request); a kept row with an action is deleted only
+ *              when picked
+ *   `blocked`  something rules removal out; never deleted, whatever is granted
+ */
+export declare const VERDICTS: readonly ["delete", "review", "keep", "blocked"];
+export type Verdict = (typeof VERDICTS)[number];
+/**
+ * What deleting a row does: `remove` a worktree, `prune` the stale record of
+ * a worktree whose directory is gone, `delete` a branch. Null on a row that
+ * can never be deleted.
+ */
+export declare const ACTIONS: readonly ["remove", "prune", "delete"];
+export type Action = (typeof ACTIONS)[number];
 /**
- * A risk a delete or remove carries, which the user approves by name:
- *   `abandon-unmerged`  drops commits not on the default branch or a merged PR
- *   `discard-changes`   drops a worktree's modified, staged or untracked files
- *   `confirm-open-pr`   the branch has an open PR; deleting the remote branch closes it
+ * A risk an action carries, which a person approves by name:
+ *   `abandon-unmerged`  drops commits not on the default branch, or a worktree's
+ *                       (or its submodules') commits and stashes no remote has
+ *   `discard-changes`   drops modified, staged or untracked files in a worktree
+ *                       or any of its submodules
+ *   `confirm-open-pr`   the branch has an open pull request; deleting the remote
+ *                       branch closes it
  */
-export declare const AUTHORIZATIONS: readonly ["abandon-unmerged", "discard-changes", "confirm-open-pr"];
-export type Authorization = (typeof AUTHORIZATIONS)[number];
-/** The authorizations whose flag is set, in canonical order. */
-export declare function authorizationsFor(flags: Partial<Record<Authorization, boolean>>): Authorization[];
+export declare const RISKS: readonly ["abandon-unmerged", "discard-changes", "confirm-open-pr"];
+export type Risk = (typeof RISKS)[number];
+/** The risks whose flag is set, in canonical order. */
+export declare function risksFor(flags: Partial<Record<Risk, boolean>>): Risk[];
+/** A condition that rules out removing a worktree, whatever is granted. */
+export type Blocker = 'locked-worktree' | 'live-process' | 'process-probe-failed' | 'hidden-index-flags' | 'nested-repository' | 'branch-in-other-worktree' | 'submodule-unreadable';
+/** Why a merged PR does not prove that a tip landed. */
+export type PrEvidenceGap = 'other-base' | 'head-moved';
+/** A pull request, reduced to what classification consults. */
+export interface PRInfo {
+    number: number;
+    state: string;
+    mergedAt: string | null;
+    headRef: string;
+    /** The PR's head commit; null when the provider did not report one. */
+    headOid: string | null;
+    /** The branch the PR targets. */
+    baseRef: string;
+    title: string;
+    url: string;
+}
+/** A row's pull request, as evidence: the PR without its head branch, which the row names already. */
+export type PrEvidence = Omit<PRInfo, 'headRef'> & {
+    /** For a merged PR: `exact-head` when it proves the tip landed, otherwise the gap. */
+    proof?: 'exact-head' | PrEvidenceGap;
+};
+/** Evidence every kind of row records about whether its work landed. */
+export interface LandingEvidence {
+    pr?: PrEvidence;
+    /** The work is on the default branch: by ancestry, an exact-head merged PR, or a patch match. Absent on a row not judged. */
+    merged?: boolean;
+    /** Commits not on the default branch; null when they could not be counted. */
+    uniqueCommits?: number | null;
+    /** Set when the work landed under other commit ids. */
+    landing?: 'patch-equivalent';
+    /** Which patch check passed. */
+    landingCheck?: LandingCheck;
+    /** True when `git merge-tree` agreed the content is on the default branch. */
+    landingContentConfirmed?: boolean;
+    /** Commits of a partly landed branch that have no patch-equivalent commit. */
+    unmatchedCommits?: string[];
+}
+/** How a branch shows it was worked on, for a worktree merged by ancestry alone. */
+export type BranchUse = 'commits' | 'upstream';
+/** One submodule of a worktree, as evidence. */
+export interface SubmoduleEvidence {
+    path: string;
+    populated: boolean;
+    head: string | null;
+    recorded: string | null;
+    dirtyFiles: number;
+    unpushedCommits: number;
+    stashes: number;
+    error?: string;
+}
+export interface WorktreeEvidence extends LandingEvidence {
+    path: string;
+    branch: string | null;
+    head: string | null;
+    bare: boolean;
+    detached: boolean;
+    primary: boolean;
+    /** The directory is there and is still a checkout. */
+    onDisk?: boolean;
+    /** The directory is there but is no longer a checkout (its `.git` is gone). */
+    directoryLeft?: boolean;
+    dirtyFiles?: number;
+    unpushedCommits?: number;
+    /** What `unpushedCommits` was counted against: the upstream, or the default branch. */
+    compareAgainst?: string;
+    branchExists?: boolean;
+    /** Set for a worktree merged by ancestry alone; null when its branch looks freshly made. */
+    branchUsed?: BranchUse | null;
+    lockReason?: string | null;
+    /** The lock's owner is dead, so the lock is cleared before the remove. */
+    staleLock?: boolean;
+    lockOwner?: {
+        pid: number;
+        startedAt: string | null;
+    };
+    liveProcesses?: ProcessHolder[];
+    idleShells?: ProcessHolder[];
+    processProbeError?: string;
+    /** Count of skip-worktree and assume-unchanged files. */
+    hiddenIndexFlags?: number;
+    /** The first ten of them. */
+    hiddenIndexPaths?: string[];
+    nestedRepositories?: string[];
+    otherWorktrees?: string[];
+    submodules?: SubmoduleEvidence[];
+    submoduleDirtyFiles?: number;
+    /** Its submodules make plain `git worktree remove` refuse, so the remove is forced. */
+    forcedForSubmodules?: boolean;
+}
+export interface BranchEvidence extends LandingEvidence {
+    branch: string;
+    upstream: string | null;
+    track: string | null;
+    lastCommit: string;
+    sha: string;
+    compareAgainst?: string;
+    /** Null when the remote default branch was not found. */
+    ancestorOfRemoteMain?: boolean | null;
+    /** The worktree whose removal frees this branch; it is deleted only when that worktree goes in the same run. */
+    worktree?: string;
+}
+export interface RemoteEvidence extends LandingEvidence {
+    branch: string;
+    remote: string;
+    sha: string;
+    /** A local branch has the same name. */
+    hasLocal: boolean;
+    ancestorOfRemoteMain?: boolean;
+}
+interface RowCommon {
+    id: RowId;
+    /** The row's name within its kind: a worktree's path, a branch name, `<remote>/<branch>`. */
+    name: string;
+    verdict: Verdict;
+    /** What deleting it does; null when it can never be deleted. */
+    action: Action | null;
+    /** One line, already phrased for a report. */
+    why: string;
+    /** What its action would lose, which a person must allow by name. */
+    risks: Risk[];
+    /** Non-empty exactly when `verdict` is `blocked`. */
+    blockers: Blocker[];
+    /** The literal commands that would carry out `action`. Never run by the sweep. */
+    commands: string[];
+    /**
+     * Sentences on what is unclear or what to do about a blocker. A list, so a
+     * host appends its own before anything is rendered.
+     */
+    notes: string[];
+}
+export interface WorktreeRow extends RowCommon {
+    kind: 'worktree';
+    evidence: WorktreeEvidence;
+}
+export interface BranchRow extends RowCommon {
+    kind: 'branch';
+    evidence: BranchEvidence;
+}
+export interface RemoteRow extends RowCommon {
+    kind: 'remote';
+    evidence: RemoteEvidence;
+}
+/** One thing that could be deleted, and the sweep's verdict on it. */
+export type Row = WorktreeRow | BranchRow | RemoteRow;
+/** A row whose deletion only prunes a stale worktree record. */
+export declare function isPrune(row: Pick<Row, 'verdict' | 'action'>): boolean;
+type Defaulted = 'commands' | 'notes' | 'risks' | 'blockers';
+/** The fields a classifier supplies for a row of type `R`; kind, name and evidence it fixes once. */
+export type RowFields<R extends Row> = Omit<R, Defaulted | 'id' | 'kind' | 'name' | 'evidence'> & Partial<Pick<R, Defaulted>>;
+/** Build a row, defaulting its lists to empty. */
+export declare function makeRow<R extends Row>(partial: Omit<R, Defaulted | 'id'> & Partial<Pick<R, Defaulted>>): R;
 /** What the sweep learned about a repository before inventorying it. */
 export interface RepoInfo {
     /** The main checkout's root, even when the sweep was pointed at a worktree. */
@@ -51,9 +227,8 @@ export interface RepoInfo {
     remote: string | null;
     currentBranch: string;
     /**
-     * The provider asked for pull requests and what its probe found: whether
-     * its CLI is installed and signed in. Null when none was asked
-     * (`--provider none`, or a sweep without `--remotes`).
+     * The provider asked for pull requests and what its probe found. Null when
+     * none was asked (`provider: 'none'`, or a sweep without remote branches).
      */
     provider: ProviderStatus | null;
     /** True when the sweep fetched the remote before classifying. */
@@ -63,70 +238,48 @@ export interface RepoInfo {
 export declare function landedRef(repo: RepoInfo): string;
 /** True when the repository has a remote the sweep did not fetch, so its refs may be stale. */
 export declare function isUnfetched(repo: RepoInfo): boolean;
-/** Why a merged PR does not prove that a tip landed. */
-export type PrEvidenceGap = 'other-base' | 'head-moved';
-/** A pull request, reduced to what classification consults. */
-export interface PRInfo {
-    number: number;
-    state: string;
-    mergedAt: string | null;
-    headRef: string;
-    /** The PR's head commit; null when `gh` did not report one. */
-    headOid: string | null;
-    /** The branch the PR targets. */
-    baseRef: string;
-    title: string;
-    url: string;
-}
-export interface SweepItem {
-    category: Category;
-    id: string;
-    classification: Classification;
-    action: string;
-    /** One line, already phrased for a report. */
-    reason: string;
-    /** The evidence behind the verdict. A host re-ranking a row reads these. */
-    facts: Record<string, unknown>;
-    /** Literal commands that would carry out `action`. Never run by this library. */
-    commands: string[];
-    /**
-     * Sentences explaining what is unclear, for a `needs-investigation` row.
-     *
-     * Parts rather than one string: a host with knowledge this library does not
-     * have appends its own sentence before anything is rendered. Empty for a row
-     * that needs no investigation.
-     */
-    investigationParts: string[];
-    /** What deleting or removing this row would need approved. */
-    requires: Authorization[];
-    /**
-     * False for a row kept for structure, such as the default branch, and for a
-     * blocked worktree. Never offered for deletion.
-     */
-    deletable: boolean;
+/** Rows of one kind, counted by what the sweep concluded. */
+export interface Bucket {
+    total: number;
+    /** Rows whose work is on the default branch. Rows kept for structure are not judged. */
+    merged: number;
+    /** `delete` rows that delete something. */
+    delete: number;
+    /** `delete` rows that only prune a stale worktree record. */
+    prune: number;
+    review: number;
+    blocked: number;
+    keep: number;
 }
-/** One repository's inventory, or the reason there is none. */
+export type Counts = Record<Kind, Bucket>;
+export declare function emptyBucket(): Bucket;
+/** Per-kind counts over `rows`, every kind present. */
+export declare function countRows(rows: readonly Row[]): Counts;
+/** `counts` summed across kinds. */
+export declare function totalOf(counts: Counts): Bucket;
+/** One repository's rows, or the reason there are none. */
 export interface RepoSweep {
-    /** Present when the repository could be read. */
-    repo: RepoInfo | null;
     /** The path the sweep was pointed at, whether or not it could be read. */
     path: string;
-    items: SweepItem[];
-    /** Why this repository produced no inventory. Null on success. */
+    /** Present when the repository could be read. */
+    repo: RepoInfo | null;
+    rows: Row[];
+    counts: Counts;
+    /** Why this repository produced no rows. Null on success. */
     error: string | null;
 }
-/** An entry that named no repository. */
+/** A target that named no repository. */
 export interface UnresolvedEntry {
     entry: string;
     reason: string;
 }
 /**
- * What resolving the entries cost. An entry that is itself a checkout costs
- * nothing to find; a container is walked, and a person who points one at the
- * wrong directory deserves to be told how much was read.
+ * What resolving the targets cost. A target that is itself a checkout costs
+ * nothing to find; a directory is walked, and a person who points one at the
+ * wrong place deserves to be told how much was read.
  */
 export interface ScanStats {
-    /** Entries that had to be searched, rather than naming a checkout outright. */
+    /** Targets that had to be searched, rather than naming a checkout outright. */
     containers: number;
     /** Directories read across those searches. */
     directoriesScanned: number;
@@ -141,12 +294,18 @@ export interface DuplicateCheckout {
     /** Main-checkout paths, sorted. */
     roots: string[];
 }
-/** Every repository swept in one run, plus the entries that named none. */
-export interface SweepResult {
+/** The options a sweep ran with, as a plan records them so a re-check runs the same sweep. */
+export type SweptWith = Plan['options'];
+/** Every repository swept in one run, plus the targets that named none. */
+export interface Sweep {
     repos: RepoSweep[];
     unresolved: UnresolvedEntry[];
     scan: ScanStats;
     duplicates: DuplicateCheckout[];
+    /** Every repository's counts, summed per kind. */
+    counts: Counts;
+    /** What was swept, for a plan. */
+    options: SweptWith;
 }
 /**
  * Slugs shared by two or more of `repos`, roots sorted. A null entry or a
@@ -157,22 +316,34 @@ export declare function findDuplicateCheckouts(repos: readonly ({
     slug: string | null;
 } | null)[]): DuplicateCheckout[];
 export declare function emptyScan(): ScanStats;
-export interface SummaryBucket {
-    total: number;
-    /** Rows whose work is on the default branch (`facts.merged`). Rows kept for structure are not judged. */
-    merged: number;
-    'safe-to-delete': number;
-    /** The `safe-to-delete` rows that only prune a stale worktree link (`action: 'prune'`); the directory, if any, stays. */
-    prune: number;
-    'safe-to-keep': number;
-    'needs-investigation': number;
-}
-export declare function emptyBucket(): SummaryBucket;
-/** Per-category counts over `items`. */
-export declare function summarize(items: readonly SweepItem[]): Record<string, SummaryBucket>;
-/** A row whose deletion only prunes a stale worktree link. */
-export declare function isPrune(item: Pick<SweepItem, 'classification' | 'action'>): boolean;
-type Defaulted = 'facts' | 'commands' | 'investigationParts' | 'requires' | 'deletable';
-/** Build an item, defaulting the collection fields and `deletable: true`. */
-export declare function makeItem(partial: Omit<SweepItem, Defaulted> & Partial<Pick<SweepItem, Defaulted>>): SweepItem;
+/**
+ * What a sweep is doing, for a status line. `repo` is the path being swept;
+ * `index` and `of` place it among the run's repositories. `done` and `total`
+ * count rows within a step that walks many.
+ */
+export interface SweepProgress {
+    repo: string;
+    index: number;
+    of: number;
+    step: 'discover' | 'fetch' | 'prs' | Kind;
+    done?: number;
+    total?: number;
+    /** The CLI asked during the `prs` step: `gh`, `glab`. */
+    tool?: string;
+}
+/**
+ * Why the library refused. Nothing has been touched when it throws.
+ *
+ *   `conflict`        options that contradict each other, or one that would have no effect
+ *   `bad-input`       a malformed row id or an unknown risk
+ *   `not-found`       a picked, spared or allowed row the plan does not have
+ *   `ambiguous`       a row id that matches rows in more than one repository
+ *   `spared-changed`  a spared remote branch is gone or moved since the plan
+ *   `bad-plan`        a plan that cannot be read, or one from another plan version
+ */
+export type ErrorCode = 'conflict' | 'bad-input' | 'not-found' | 'ambiguous' | 'spared-changed' | 'bad-plan';
+export declare class RepoCleanerError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
 export {};

package/dist/types.js

@@ -1,22 +1,76 @@
 /**
  * The inventory a sweep produces, and the vocabulary it is described in.
  *
- * One shape serves every category. A caller that wants only worktrees filters
- * by `category` rather than reading a different type, and a host that adds its
- * own knowledge (an issue tracker's linkage, say) rewrites rows in place.
+ * A sweep returns rows. Each row is one thing that could be deleted — a
+ * worktree, a local branch, a remote branch — with the sweep's verdict on it,
+ * the action that would delete it, the risks that action carries, and the
+ * evidence behind it all. A host that knows more than git does rewrites rows
+ * through the `annotate` hook rather than reaching into classification.
  */
-/** Which categories to gather. */
-export const ALL_SCOPES = ['local-branches', 'worktrees', 'remote-branches'];
+/** The kinds of row, in the order a run acts on them. */
+export const KINDS = ['worktree', 'branch', 'remote'];
+/** The row id of `name` in `kind`. */
+export function rowId(kind, name) {
+    return `${kind}:${name}`;
+}
+/**
+ * `<kind>:<name>` split, or null when `text` has no kind in front. A
+ * one-letter prefix is a Windows drive (`C:\\…`), not a kind.
+ */
+export function parseRowId(text) {
+    const colon = text.indexOf(':');
+    if (colon <= 1)
+        return null;
+    const kind = text.slice(0, colon);
+    if (!KINDS.includes(kind))
+        return null;
+    return { kind: kind, name: text.slice(colon + 1) };
+}
+/**
+ * What the sweep concluded about a row.
+ *
+ *   `delete`   its work is on the default branch, or it is otherwise safe to lose
+ *   `review`   the signals are mixed, or it holds work; deleted only when picked
+ *   `keep`     structural (the default branch, the current checkout), or in use
+ *              (an open pull request); a kept row with an action is deleted only
+ *              when picked
+ *   `blocked`  something rules removal out; never deleted, whatever is granted
+ */
+export const VERDICTS = ['delete', 'review', 'keep', 'blocked'];
 /**
- * A risk a delete or remove carries, which the user approves by name:
- *   `abandon-unmerged`  drops commits not on the default branch or a merged PR
- *   `discard-changes`   drops a worktree's modified, staged or untracked files
- *   `confirm-open-pr`   the branch has an open PR; deleting the remote branch closes it
+ * What deleting a row does: `remove` a worktree, `prune` the stale record of
+ * a worktree whose directory is gone, `delete` a branch. Null on a row that
+ * can never be deleted.
  */
-export const AUTHORIZATIONS = ['abandon-unmerged', 'discard-changes', 'confirm-open-pr'];
-/** The authorizations whose flag is set, in canonical order. */
-export function authorizationsFor(flags) {
-    return AUTHORIZATIONS.filter((name) => flags[name] === true);
+export const ACTIONS = ['remove', 'prune', 'delete'];
+/**
+ * A risk an action carries, which a person approves by name:
+ *   `abandon-unmerged`  drops commits not on the default branch, or a worktree's
+ *                       (or its submodules') commits and stashes no remote has
+ *   `discard-changes`   drops modified, staged or untracked files in a worktree
+ *                       or any of its submodules
+ *   `confirm-open-pr`   the branch has an open pull request; deleting the remote
+ *                       branch closes it
+ */
+export const RISKS = ['abandon-unmerged', 'discard-changes', 'confirm-open-pr'];
+/** The risks whose flag is set, in canonical order. */
+export function risksFor(flags) {
+    return RISKS.filter((name) => flags[name] === true);
+}
+/** A row whose deletion only prunes a stale worktree record. */
+export function isPrune(row) {
+    return row.verdict === 'delete' && row.action === 'prune';
+}
+/** Build a row, defaulting its lists to empty. */
+export function makeRow(partial) {
+    return {
+        ...partial,
+        id: rowId(partial.kind, partial.name),
+        commands: partial.commands ?? [],
+        notes: partial.notes ?? [],
+        risks: partial.risks ?? [],
+        blockers: partial.blockers ?? [],
+    };
 }
 /** The ref a branch must reach to count as landed: `<remote>/<default>`, or the local default without a remote. */
 export function landedRef(repo) {
@@ -26,6 +80,33 @@ export function landedRef(repo) {
 export function isUnfetched(repo) {
     return repo.remote !== null && !repo.fetched;
 }
+export function emptyBucket() {
+    return { total: 0, merged: 0, delete: 0, prune: 0, review: 0, blocked: 0, keep: 0 };
+}
+/** Per-kind counts over `rows`, every kind present. */
+export function countRows(rows) {
+    const out = Object.fromEntries(KINDS.map((k) => [k, emptyBucket()]));
+    for (const row of rows) {
+        const bucket = out[row.kind];
+        bucket.total += 1;
+        if (row.evidence.merged === true)
+            bucket.merged += 1;
+        if (isPrune(row))
+            bucket.prune += 1;
+        else
+            bucket[row.verdict] += 1;
+    }
+    return out;
+}
+/** `counts` summed across kinds. */
+export function totalOf(counts) {
+    const out = emptyBucket();
+    for (const kind of KINDS) {
+        for (const key of Object.keys(out))
+            out[key] += counts[kind][key];
+    }
+    return out;
+}
 /**
  * Slugs shared by two or more of `repos`, roots sorted. A null entry or a
  * repository without a slug is left out.
@@ -47,46 +128,11 @@ export function findDuplicateCheckouts(repos) {
 export function emptyScan() {
     return { containers: 0, directoriesScanned: 0, depthLimited: 0, checkoutsFound: 0 };
 }
-export function emptyBucket() {
-    return {
-        total: 0,
-        merged: 0,
-        'safe-to-delete': 0,
-        prune: 0,
-        'safe-to-keep': 0,
-        'needs-investigation': 0,
-    };
-}
-/** Per-category counts over `items`. */
-export function summarize(items) {
-    const out = {};
-    for (const item of items) {
-        const bucket = (out[item.category] ??= emptyBucket());
-        bucket.total += 1;
-        if (item.facts['merged'] === true)
-            bucket.merged += 1;
-        if (isPrune(item))
-            bucket.prune += 1;
-        bucket[item.classification] += 1;
+export class RepoCleanerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RepoCleanerError';
+        this.code = code;
     }
-    return out;
-}
-/** A row whose deletion only prunes a stale worktree link. */
-export function isPrune(item) {
-    return item.classification === 'safe-to-delete' && item.action === 'prune';
-}
-/** Build an item, defaulting the collection fields and `deletable: true`. */
-export function makeItem(partial) {
-    return {
-        category: partial.category,
-        id: partial.id,
-        classification: partial.classification,
-        action: partial.action,
-        reason: partial.reason,
-        facts: partial.facts ?? {},
-        commands: partial.commands ?? [],
-        investigationParts: partial.investigationParts ?? [],
-        requires: partial.requires ?? [],
-        deletable: partial.deletable ?? true,
-    };
 }

package/dist/util.d.ts

@@ -0,0 +1,7 @@
+/** Small helpers every module of the package shares. */
+/** True when `path` is a directory; false for anything else, or when it cannot be read. */
+export declare function isDir(path: string): boolean;
+/** An error as one line for a person: a failed git call's own output, or the message. */
+export declare function errorText(err: unknown): string;
+/** `1 commit`, `3 commits`. */
+export declare const plural: (n: number, one: string, many: string) => string;

package/dist/util.js

@@ -0,0 +1,20 @@
+/** Small helpers every module of the package shares. */
+import { statSync } from 'node:fs';
+import { CommandFailed } from '@osdlc/typed-git';
+/** True when `path` is a directory; false for anything else, or when it cannot be read. */
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** An error as one line for a person: a failed git call's own output, or the message. */
+export function errorText(err) {
+    if (err instanceof CommandFailed)
+        return err.detail.trim() || err.message;
+    return err instanceof Error ? err.message : String(err);
+}
+/** `1 commit`, `3 commits`. */
+export const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, from its package.json when it was built. */
-export declare const VERSION = "0.17.2";
+export declare const VERSION = "0.18.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 // Generated by cli-tool-stamp-version from package.json. Do not edit.
 /** This package's version, from its package.json when it was built. */
-export const VERSION = '0.17.2';
+export const VERSION = '0.18.0';