@osdlc/repo-cleaner 0.10.1 → 0.13.0

package/dist/step-board.js

@@ -0,0 +1,101 @@
+/**
+ * `apply`'s steps as a vertical list redrawn in place on a terminal: one row
+ * per step with its own bar, empty while it waits, half full while it runs,
+ * full and ticked when it is done, and a bar for the whole run under the
+ * list. The run is synchronous, so the board moves between steps, not on a
+ * timer.
+ */
+import { fitWidth, stripControls } from '@osdlc/ux';
+import { PLAIN, STEP_VERB } from "./render.js";
+import { progressBar } from "./status-line.js";
+/** A step bar's cells, and the run bar's at most. */
+const BAR = 10;
+const TOTAL_BAR = 30;
+function label(step) {
+    const verb = STEP_VERB[step.action];
+    if (step.row === null)
+        return verb;
+    return stripControls(`${verb.padEnd(6)}  ${step.row.category}  ${step.row.id}`);
+}
+/**
+ * One step's row, cut to `width` columns before it is colored, so the color
+ * codes never count against the width and the row never wraps.
+ */
+function stepRow(step, running, width, style) {
+    const [bar, mark, color, text] = step.result === 'ok'
+        ? ['█'.repeat(BAR), '✓', style.keep, (t) => t]
+        : step.result === 'failed'
+            ? ['█'.repeat(BAR), '✗', style.delete, (t) => t]
+            : running
+                ? ['█'.repeat(BAR / 2) + '░'.repeat(BAR / 2), '›', style.review, style.strong]
+                : ['░'.repeat(BAR), ' ', style.muted, style.muted];
+    const head = `  ${bar} ${mark} `;
+    if (width <= head.length)
+        return color(fitWidth(head, width));
+    return `  ${color(bar)} ${color(mark)} ${text(fitWidth(label(step), width - head.length))}`;
+}
+/** The run's bar and count, shrunk to fit `width` columns. */
+function totalRow(done, total, failed, width, style) {
+    const count = ` ${done}/${total}`;
+    const cells = Math.min(TOTAL_BAR, width - 2 - count.length);
+    const line = cells > 0
+        ? `  ${progressBar(done, total, cells)}${count}`
+        : fitWidth(`  ${count.trim()}`, width);
+    return failed ? style.delete(line) : style.strong(line);
+}
+/**
+ * The board's lines, each at most `width` columns, and at most `height - 1`
+ * of them: the cursor sits on the row under the last line, which must stay
+ * on screen. That is the run's bar under the rows that fit; a list longer
+ * than that shows a window that keeps the running step in view, with a line
+ * for the rows above and below it when there is room for one.
+ */
+export function boardLines(steps, running, size, style = PLAIN) {
+    const width = Math.max(1, size.width);
+    const room = Math.max(1, size.height - 2);
+    let first = 0;
+    let last = steps.length;
+    const windowed = steps.length > room;
+    // The above and below notes need a row each, and a row for a step besides.
+    const notes = windowed && room >= 3;
+    if (windowed) {
+        const at = running ?? steps.findIndex((s) => s.result === 'pending');
+        const focus = at < 0 ? steps.length - 1 : at;
+        const shown = notes ? room - 2 : room;
+        first = Math.min(Math.max(0, focus - Math.floor(shown / 3)), steps.length - shown);
+        last = first + shown;
+    }
+    const note = (text) => style.muted(fitWidth(text, width));
+    const lines = [];
+    if (notes)
+        lines.push(note(`  … ${first} above`));
+    for (let i = first; i < last; i++)
+        lines.push(stepRow(steps[i], i === running, width, style));
+    if (notes)
+        lines.push(note(`  … ${steps.length - last} below`));
+    const done = steps.filter((s) => s.result === 'ok' || s.result === 'failed').length;
+    const failed = steps.some((s) => s.result === 'failed');
+    lines.push(totalRow(done, steps.length, failed, width, style));
+    return lines;
+}
+/**
+ * A board on `write`. The first draw prints its lines; each later one moves
+ * the cursor back to the board's first line and rewrites them, erasing any
+ * line an earlier, taller frame left below. Lines are cut to one column
+ * short of the width, so none wraps and the line count stays right.
+ */
+export function stepBoard(write, steps, size, style = PLAIN) {
+    let drawn = 0;
+    return {
+        draw(running) {
+            const { width, height } = size();
+            const lines = boardLines(steps, running, { width: width - 1, height }, style);
+            // A frame shorter than the last one blanks the rows the last one used.
+            while (lines.length < drawn)
+                lines.push('');
+            const up = drawn > 0 ? `\x1b[${drawn}A` : '';
+            write(up + lines.map((l) => `\r\x1b[2K${l}\n`).join(''));
+            drawn = lines.length;
+        },
+    };
+}

package/dist/types.d.ts

@@ -155,12 +155,16 @@ export interface SummaryBucket {
     /** 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;

package/dist/types.js

@@ -48,7 +48,14 @@ export function emptyScan() {
     return { containers: 0, directoriesScanned: 0, depthLimited: 0, checkoutsFound: 0 };
 }
 export function emptyBucket() {
-    return { total: 0, merged: 0, 'safe-to-delete': 0, 'safe-to-keep': 0, 'needs-investigation': 0 };
+    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) {
@@ -58,10 +65,16 @@ export function summarize(items) {
         bucket.total += 1;
         if (item.facts['merged'] === true)
             bucket.merged += 1;
+        if (isPrune(item))
+            bucket.prune += 1;
         bucket[item.classification] += 1;
     }
     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 {

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.10.1";
+export declare const VERSION = "0.13.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.10.1';
+export const VERSION = '0.13.0';

package/dist/worktrees.d.ts

@@ -46,3 +46,15 @@ export declare function classifyWorktree(opts: {
     /** Answers lock-owner and working-directory questions. One per sweep: it caches the process table. */
     probe: ProcessProbe;
 }): SweepItem;
+/** How a branch shows it was worked on, for a worktree merged by ancestry alone. */
+export type BranchUse = 'commits' | 'upstream';
+/**
+ * The sign that `branch` was worked on, or null for a branch that looks
+ * freshly made. `commits`: its reflog records work (see {@link isWorkEntry}). `upstream`: it tracks a branch on a remote, and not
+ * the default branch (`mainBranch`) of any remote, so someone pushed it as
+ * its own branch. A branch with neither, such as one `git worktree add -b`
+ * just made from the default branch, with or without `--track`, reads as
+ * null: removing its worktree could lose ignored files from work about to
+ * start.
+ */
+export declare function branchUse(git: Git, branch: string, mainBranch: string): BranchUse | null;

package/dist/worktrees.js

@@ -293,7 +293,7 @@ export function classifyWorktree(opts) {
             category: 'worktree',
             id: path,
             classification: 'safe-to-delete',
-            action: 'remove',
+            action: 'prune',
             reason: dirPresent
                 ? 'directory is no longer a checkout (no .git); prune the stale link, the directory stays'
                 : 'worktree directory no longer on disk; prune the stale link',
@@ -360,6 +360,24 @@ export function classifyWorktree(opts) {
     }
     if (pr && pr.state === 'OPEN')
         return keep(`open PR #${pr.number}`, { requires });
+    // Merged by ancestry alone: a worktree just made from the default branch is
+    // merged that way too, so ancestry needs a sign the branch was worked on.
+    if (facts['merged'] === true && branch && head !== null) {
+        const used = branchUse(git.at(repo.root), branch, repo.mainBranch);
+        facts['branch_used'] = used;
+        if (used !== null) {
+            return makeItem({
+                category: 'worktree',
+                id: path,
+                classification: 'safe-to-delete',
+                action: 'remove',
+                reason: `clean; merged into ${landedRef(repo)}, and ${USE_REASON[used]}`,
+                facts,
+                commands: safeRemove,
+                requires,
+            });
+        }
+    }
     const parts = [`Worktree \`${path}\` is clean.`];
     if (branch)
         parts.push(`Branch: \`${branch}\`.`);
@@ -380,3 +398,42 @@ export function classifyWorktree(opts) {
         requires,
     });
 }
+const USE_REASON = {
+    commits: 'the branch has commits made on it',
+    upstream: 'the branch was pushed to its own upstream',
+};
+/**
+ * Reflog entries that put work on a branch: a commit, a cherry-pick, an `am`,
+ * or a merge or pull that made a merge commit. A fast-forward merge or pull,
+ * a rebase, a reset or a rename only moves a branch, which a fresh branch
+ * tracking the default branch does on its first `git pull`.
+ */
+function isWorkEntry(entry) {
+    if (/^(commit|cherry-pick|am)\b/.test(entry))
+        return true;
+    return /^(merge|pull)\b/.test(entry) && !/Fast-forward/.test(entry);
+}
+/**
+ * The sign that `branch` was worked on, or null for a branch that looks
+ * freshly made. `commits`: its reflog records work (see {@link isWorkEntry}). `upstream`: it tracks a branch on a remote, and not
+ * the default branch (`mainBranch`) of any remote, so someone pushed it as
+ * its own branch. A branch with neither, such as one `git worktree add -b`
+ * just made from the default branch, with or without `--track`, reads as
+ * null: removing its worktree could lose ignored files from work about to
+ * start.
+ */
+export function branchUse(git, branch, mainBranch) {
+    // `raw`: a branch with no reflog (core.logAllRefUpdates off) exits non-zero.
+    const reflog = git.raw(['reflog', 'show', '--format=%gs', `refs/heads/${branch}`, '--']);
+    if (reflog.exitCode === 0 && reflog.stdout.split('\n').some(isWorkEntry)) {
+        return 'commits';
+    }
+    // From the branch's own config, not the resolved name: a branch tracking a
+    // local branch has remote `.`, and one tracking `upstream/main` merges the
+    // default branch however its remote is spelled.
+    const remote = git.configGet(`branch.${branch}.remote`);
+    const merge = git.configGet(`branch.${branch}.merge`);
+    if (remote && remote !== '.' && merge && merge !== `refs/heads/${mainBranch}`)
+        return 'upstream';
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.10.1",
+  "version": "0.13.0",
   "description": "What has been merged into the default branch, and what can go away. Inventories local branches, worktrees and remote branches across one repository or many, classifying each with the evidence behind the verdict and the command that would act on it. Plans and applies approved deletes, compare-and-swap.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -48,13 +48,13 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "zod": "4.4.3",
-    "@osdlc/cli-tool": "^0.12.0",
-    "@osdlc/path-guard": "^0.3.1",
+    "zod": "^4.6.6",
+    "@osdlc/cli-tool": "^0.14.0",
     "@osdlc/command-seam": "^0.14.0",
-    "@osdlc/typed-git": "^0.12.0",
+    "@osdlc/path-guard": "^0.3.1",
     "@osdlc/typed-gh": "^0.14.1",
-    "@osdlc/ux": "^0.1.1"
+    "@osdlc/ux": "^0.1.1",
+    "@osdlc/typed-git": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
@@ -63,8 +63,8 @@
     "prettier": "3.9.6",
     "typescript": "~6.0.3",
     "vitest": "^5.0.5",
-    "@osdlc/tsconfig": "^0.4.1",
-    "@osdlc/prettier-config": "^0.3.1"
+    "@osdlc/prettier-config": "^0.3.1",
+    "@osdlc/tsconfig": "^0.4.1"
   },
   "scripts": {
     "build": "cli-tool-stamp-version && tsc -p tsconfig.build.json",