@osdlc/repo-cleaner 0.10.0 → 0.11.0

package/dist/remote-mirror.js

@@ -0,0 +1,123 @@
+/**
+ * Sweep a remote with no checkout of your own: a clone of it, kept in
+ * repo-cleaner's cache directory, stands in for the checkout.
+ *
+ * The clone is `--no-checkout`, so no files are written outside `.git`. It is
+ * not a partial (`--filter=blob:none`) clone: the patch comparison that
+ * finds squash-merged branches reads file contents, and a partial clone
+ * fetches them over the network one comparison at a time, which made a sweep
+ * of a few hundred branches take minutes instead of seconds. It is kept
+ * rather than thrown away so a plan written from it can be applied later: the
+ * plan names the clone's directory, and `apply` re-sweeps and pushes deletes
+ * from there. A later run reuses it, and the sweep's fetch brings it up to
+ * date.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Git, parseRemoteRepo } from '@osdlc/typed-git';
+/** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
+export class RemoteMirrorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RemoteMirrorError';
+    }
+}
+/** Characters kept in a directory name; anything else becomes `-`. */
+const UNSAFE = /[^A-Za-z0-9._-]+/g;
+/**
+ * `text` with every URL's credentials removed: the user-info before `@` in a
+ * `scheme://` URL, and any query string or fragment. For a message or a name
+ * that must not carry a token.
+ */
+export function redactUrl(text) {
+    return text
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1')
+        .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s?#]*)[?#]\S*/gi, '$1');
+}
+/**
+ * The directory name for `url`'s mirror: readable `host-owner-repo`, then a
+ * hash of the whole URL so two URLs never share a mirror. The readable part
+ * is read from the URL with its credentials, query and fragment removed, so a
+ * token never reaches the name.
+ */
+export function mirrorName(url) {
+    const hash = createHash('sha256').update(url).digest('hex').slice(0, 12);
+    const parsed = parseRemoteRepo(redactUrl(url));
+    const readable = parsed === null
+        ? 'remote'
+        : `${parsed.host}-${parsed.owner}-${parsed.repo}`.replace(UNSAFE, '-');
+    return `${readable.replace(/^[.-]+/, '')}-${hash}`;
+}
+/**
+ * Why `dir` is not a mirror of `url` — or of whatever it was cloned from, when
+ * `url` is omitted — or null when it is. A mirror's `origin` has one fetch URL
+ * and pushes to that URL alone, so a delete cannot be sent elsewhere.
+ */
+export function mirrorProblem(dir, url, opts = {}) {
+    const git = new Git(dir, { runner: opts.git });
+    const fetch = git.try.remoteGetUrls('origin');
+    const push = git.try.remoteGetUrls('origin', { push: true });
+    if (!fetch.ok || !push.ok)
+        return `${dir} has no readable origin remote`;
+    const [from] = fetch.value;
+    if (fetch.value.length !== 1 || from === undefined) {
+        return `${dir} has ${fetch.value.length} origin URLs`;
+    }
+    if (url !== undefined && from !== url)
+        return `${dir} is a mirror of another URL`;
+    if (push.value.length !== 1 || push.value[0] !== from) {
+        return `${dir} pushes somewhere other than the URL it was cloned from`;
+    }
+    return null;
+}
+/**
+ * The directory of `url`'s mirror under `cacheDir`, cloned on first use. An
+ * existing mirror is reused as it is, once {@link mirrorProblem} finds
+ * nothing wrong with it; the sweep's own fetch brings it up to date. A first
+ * clone goes to a sibling directory and is renamed into place, so a clone
+ * that fails leaves nothing behind, and a run that loses a race to clone the
+ * same URL uses the winner's clone. Messages carry the URL with its
+ * credentials removed.
+ *
+ * @throws RemoteMirrorError when `url` is empty or looks like an option, when
+ *   the clone fails, or when the directory is not a mirror of `url`.
+ */
+export function ensureMirror(url, cacheDir, opts = {}) {
+    if (url === '' || url.startsWith('-')) {
+        throw new RemoteMirrorError(`not a remote URL: ${JSON.stringify(redactUrl(url))}`);
+    }
+    const shown = redactUrl(url);
+    const dir = join(cacheDir, mirrorName(url));
+    if (existsSync(dir)) {
+        const problem = mirrorProblem(dir, url, opts);
+        if (problem !== null) {
+            throw new RemoteMirrorError(`${problem}, not a mirror of ${shown}; remove the directory and run again`);
+        }
+        return dir;
+    }
+    mkdirSync(dirname(dir), { recursive: true });
+    const staging = `${dir}.partial-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    try {
+        new Git(dirname(dir), { runner: opts.git }).rawChecked([
+            'clone',
+            '--quiet',
+            '--no-checkout',
+            '--',
+            url,
+            staging,
+        ]);
+        renameSync(staging, dir);
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        // Another run cloned the same URL first and won the rename: use its clone.
+        if (existsSync(dir) && mirrorProblem(dir, url, opts) === null)
+            return dir;
+        const detail = err.failure?.detail ??
+            (err instanceof Error ? err.message : String(err));
+        throw new RemoteMirrorError(`cannot clone ${shown}: ${redactUrl(detail.split(url).join(shown)).trim()}`);
+    }
+    return dir;
+}

package/dist/render.d.ts

@@ -30,7 +30,7 @@ export declare function renderScan(result: SweepResult): string | null;
 export declare function renderSummary(result: SweepResult): string;
 /**
  * One repository as counts: a row per category with its total, how many are
- * merged, and how many the sweep would delete, review or keep.
+ * merged, and how many the sweep would delete, prune, review or keep.
  */
 export declare function renderCounts(sweep: RepoSweep): string;
 /** The whole run as counts: a table per repository, then the one-line summary. */
@@ -48,5 +48,28 @@ export declare function renderText(result: SweepResult, opts?: {
 export declare function renderJson(result: SweepResult, extra?: Record<string, unknown>): string;
 /** Every command a `safe-to-delete` row that needs no authorization proposes, in report order. */
 export declare function proposedCommands(result: SweepResult): string[];
-/** An apply run as text: dropped rows, each step, then where the receipt is. */
+/** What an apply run did, or would do, counted by kind. */
+export interface ApplySummary {
+    /** Rows deleted (or, in a dry run, that would be), by category. Pruned worktrees are not counted here. */
+    deleted: {
+        worktree: number;
+        local_branch: number;
+        remote_branch: number;
+    };
+    /** Worktrees whose stale registration was pruned; their directories were gone or left alone. */
+    pruned: number;
+    /** Dropped rows by reason. */
+    dropped: Record<string, number>;
+    /** Steps that failed: 0 or 1, since the first failure stops the run. */
+    failed: number;
+    /** Row steps never reached because a step failed. */
+    notRun: number;
+}
+/** Count a receipt's outcome. A dry run's `would-run` steps count as done. */
+export declare function summarizeReceipt(receipt: Receipt): ApplySummary;
+/** Rows a receipt deletes or prunes, which is what a person is asked to approve. */
+export declare function rowsActedOn(summary: ApplySummary): number;
+/** The closing lines of an apply run: what it deleted, dropped and could not finish. */
+export declare function renderApplySummary(receipt: Receipt): string[];
+/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
 export declare function renderReceipt(receipt: Receipt, receiptPath: string | null): string;

package/dist/render.js

@@ -6,7 +6,7 @@
  * find. JSON carries everything the text report elides, including the facts
  * behind every verdict.
  */
-import { emptyBucket, isUnfetched, summarize, } from "./types.js";
+import { emptyBucket, isPrune, isUnfetched, summarize, } from "./types.js";
 import { hasBlockers } from "./worktrees.js";
 /** Order categories consistently, whatever order they were gathered in. */
 const CATEGORY_ORDER = ['local_branch', 'worktree', 'remote_branch'];
@@ -69,7 +69,9 @@ export function renderRepo(sweep, opts = {}) {
     const idWidth = Math.min(38, Math.max(...shown.map((item) => ellipsize(item.id, 38).length)));
     const categoryWidth = Math.max(...shown.map((item) => item.category.length));
     for (const item of shown) {
-        const action = ACTION_LABEL[item.classification] ?? item.classification;
+        const action = isPrune(item)
+            ? 'prune'
+            : (ACTION_LABEL[item.classification] ?? item.classification);
         const note = requiresNote(item);
         lines.push(`  ${pad(item.category, categoryWidth)}  ${pad(ellipsize(item.id, 38), idWidth)}  ${pad(action, 6)}  ${item.reason}${note ? `; ${note}` : ''}`);
         // A blocked row has no commands; what to do about each blocker goes there instead.
@@ -86,6 +88,7 @@ function totals(result) {
             out.total += bucket.total;
             out.merged += bucket.merged;
             out['safe-to-delete'] += bucket['safe-to-delete'];
+            out.prune += bucket.prune;
             out['safe-to-keep'] += bucket['safe-to-keep'];
             out['needs-investigation'] += bucket['needs-investigation'];
         }
@@ -116,6 +119,10 @@ export function renderScan(result) {
         return line;
     return `${line} ${count(scan.depthLimited)} left unopened at the depth limit.`;
 }
+/** The `safe-to-delete` rows that delete something, not the ones that only prune a stale link. */
+function deleteOnly(bucket) {
+    return bucket['safe-to-delete'] - bucket.prune;
+}
 /** The one-line verdict a person reads first, and often only. */
 export function renderSummary(result) {
     const counts = totals(result);
@@ -128,24 +135,26 @@ export function renderSummary(result) {
         tail.push(`${result.unresolved.length} ${result.unresolved.length === 1 ? 'entry' : 'entries'} unresolved`);
     }
     const suffix = tail.length > 0 ? ` (${tail.join(', ')})` : '';
-    return `${counts['safe-to-delete']} to delete, ${counts['needs-investigation']} to review, across ${repos}${suffix}.`;
+    const prune = counts.prune > 0 ? `${counts.prune} to prune, ` : '';
+    return `${deleteOnly(counts)} to delete, ${prune}${counts['needs-investigation']} to review, across ${repos}${suffix}.`;
 }
 const COUNT_LABEL = {
     local_branch: 'local branches',
     worktree: 'worktrees',
     remote_branch: 'remote branches',
 };
+/** A count table's columns. `delete` leaves out the rows `prune` counts, so each row is in one of delete, prune, review and keep. */
 const COUNT_COLUMNS = [
-    'total',
-    'merged',
-    'safe-to-delete',
-    'needs-investigation',
-    'safe-to-keep',
+    { heading: 'total', of: (b) => b.total },
+    { heading: 'merged', of: (b) => b.merged },
+    { heading: 'delete', of: deleteOnly },
+    { heading: 'prune', of: (b) => b.prune },
+    { heading: 'review', of: (b) => b['needs-investigation'] },
+    { heading: 'keep', of: (b) => b['safe-to-keep'] },
 ];
-const COUNT_HEADINGS = ['total', 'merged', 'delete', 'review', 'keep'];
 /**
  * One repository as counts: a row per category with its total, how many are
- * merged, and how many the sweep would delete, review or keep.
+ * merged, and how many the sweep would delete, prune, review or keep.
  */
 export function renderCounts(sweep) {
     const lines = [repoHeader(sweep)];
@@ -156,10 +165,10 @@ export function renderCounts(sweep) {
     const buckets = summarize(sweep.items);
     const labelWidth = Math.max(...Object.values(COUNT_LABEL).map((l) => l.length));
     const cell = (text, heading) => text.padStart(Math.max(heading.length, 5));
-    lines.push(`  ${' '.repeat(labelWidth)}  ${COUNT_HEADINGS.map((h) => cell(h, h)).join('  ')}`);
+    lines.push(`  ${' '.repeat(labelWidth)}  ${COUNT_COLUMNS.map(({ heading }) => cell(heading, heading)).join('  ')}`);
     for (const category of CATEGORY_ORDER) {
         const bucket = buckets[category] ?? emptyBucket();
-        const cells = COUNT_COLUMNS.map((col, i) => cell(count(bucket[col]), COUNT_HEADINGS[i]));
+        const cells = COUNT_COLUMNS.map(({ heading, of }) => cell(count(of(bucket)), heading));
         lines.push(`  ${pad(COUNT_LABEL[category], labelWidth)}  ${cells.join('  ')}`);
     }
     return lines.join('\n');
@@ -264,7 +273,74 @@ export function proposedCommands(result) {
     }
     return out;
 }
-/** An apply run as text: dropped rows, each step, then where the receipt is. */
+/** Count a receipt's outcome. A dry run's `would-run` steps count as done. */
+export function summarizeReceipt(receipt) {
+    const out = {
+        deleted: { worktree: 0, local_branch: 0, remote_branch: 0 },
+        pruned: 0,
+        dropped: {},
+        failed: 0,
+        notRun: 0,
+    };
+    for (const d of receipt.dropped)
+        out.dropped[d.reason] = (out.dropped[d.reason] ?? 0) + 1;
+    for (const s of receipt.steps) {
+        if (s.result === 'failed')
+            out.failed += 1;
+        if (s.row === null)
+            continue;
+        if (s.result === 'pending') {
+            if (s.action !== 'unlock-worktree')
+                out.notRun += 1;
+            continue;
+        }
+        if (s.result !== 'ok' && s.result !== 'would-run')
+            continue;
+        if (s.action === 'remove-worktree')
+            out.deleted.worktree += 1;
+        else if (s.action === 'prune-worktrees')
+            out.pruned += 1;
+        else if (s.action === 'delete-local')
+            out.deleted.local_branch += 1;
+        else if (s.action === 'delete-remote')
+            out.deleted.remote_branch += 1;
+    }
+    return out;
+}
+/** Rows a receipt deletes or prunes, which is what a person is asked to approve. */
+export function rowsActedOn(summary) {
+    const d = summary.deleted;
+    return d.worktree + d.local_branch + d.remote_branch + summary.pruned;
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/** The closing lines of an apply run: what it deleted, dropped and could not finish. */
+export function renderApplySummary(receipt) {
+    const s = summarizeReceipt(receipt);
+    const dry = receipt.status === 'dry-run';
+    const parts = [
+        s.deleted.worktree > 0 ? plural(s.deleted.worktree, 'worktree', 'worktrees') : null,
+        s.deleted.local_branch > 0
+            ? plural(s.deleted.local_branch, 'local branch', 'local branches')
+            : null,
+        s.deleted.remote_branch > 0
+            ? plural(s.deleted.remote_branch, 'remote branch', 'remote branches')
+            : null,
+        s.pruned > 0 ? `${plural(s.pruned, 'stale worktree', 'stale worktrees')} pruned` : null,
+    ].filter((p) => p !== null);
+    const lines = [
+        `${dry ? 'would delete' : 'deleted'}: ${parts.length > 0 ? parts.join(', ') : 'nothing'}`,
+    ];
+    const dropped = Object.entries(s.dropped);
+    if (dropped.length > 0) {
+        const total = dropped.reduce((n, [, c]) => n + c, 0);
+        lines.push(`dropped ${total}: ${dropped.map(([reason, c]) => `${c} ${reason}`).join(', ')}`);
+    }
+    if (s.failed > 0) {
+        lines.push(`stopped at a failed step; ${plural(s.notRun, 'row', 'rows')} not run`);
+    }
+    return lines;
+}
+/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
 export function renderReceipt(receipt, receiptPath) {
     const lines = [];
     for (const d of receipt.dropped) {
@@ -275,6 +351,9 @@ export function renderReceipt(receipt, receiptPath) {
         const tail = s.error ?? s.verification;
         lines.push(`${s.result.padEnd(8)} ${what}${tail ? ` (${tail})` : ''}`);
     }
+    if (lines.length > 0)
+        lines.push('');
+    lines.push(...renderApplySummary(receipt));
     lines.push(receiptPath === null
         ? `status: ${receipt.status}`
         : `receipt: ${receiptPath} (${receipt.status})`);

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.0";
+export declare const VERSION = "0.11.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.0';
+export const VERSION = '0.11.0';

package/dist/worktrees.js

@@ -9,7 +9,7 @@ import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, join, sep } from 'node:path';
 import { shellJoin } from '@osdlc/command-seam';
 import { nodeGuard } from '@osdlc/path-guard/node';
-import { gapSentence, recordPr } from "./branches.js";
+import { gapSentence, mergedFact, recordPr } from "./branches.js";
 import { confirmationNote, judgeLanding, landingConfirmed, recordLanding, unmatchedSentence, } from "./landing.js";
 import { busyHolders, isIdleHolder, parseLockOwner } from "./processes.js";
 import { authorizationsFor, landedRef, makeItem, } from "./types.js";
@@ -251,10 +251,12 @@ export function classifyWorktree(opts) {
     const patchLanded = patch !== null && patch.check !== null;
     const unlanded = unpushed.length > 0 && !landed && !landingConfirmed(patch);
     if (onDisk && head !== null) {
-        // Merged: HEAD's work is on the default branch. `soft`: a missing default
-        // ref reads as not merged.
-        facts['merged'] =
-            landed || patchLanded || git.at(repo.root).soft.isAncestor(head, landedRef(repo));
+        // `soft`: a missing default ref reads as not merged.
+        facts['merged'] = mergedFact({
+            landed,
+            patchLanded,
+            ancestor: git.at(repo.root).soft.isAncestor(head, landedRef(repo)),
+        });
     }
     const requires = authorizationsFor({
         'abandon-unmerged': unlanded,
@@ -291,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@osdlc/cli-tool": "^0.12.0",
+    "@osdlc/cli-tool": "^0.13.0",
     "@osdlc/command-seam": "^0.14.0",
     "@osdlc/path-guard": "^0.3.1",
     "@osdlc/typed-gh": "^0.14.1",