@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/sweep.js

@@ -1,39 +1,225 @@
 /**
- * The sweep itself: one repository, or many.
+ * The sweep: resolve the targets, then inventory every repository they name.
  *
- * Every item carries the command that would act on it, and running that
- * command is the caller's decision. The only write is the optional fetch,
- * which updates remote-tracking refs and nothing else.
+ * Every row carries the commands that would act on it, and running them is
+ * the caller's decision. The only write is the fetch a sweep of remote
+ * branches makes, which updates remote-tracking refs and nothing else, and the
+ * clone a remote URL target is swept through.
  */
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
 import { Git } from '@osdlc/typed-git';
 import { Gh } from '@osdlc/typed-gh';
-import { HELD_BY_WORKTREE, gatherLocalBranches, gatherRemoteBranches } from "./branches.js";
-import { DiscoveryFailed, discoverRepo } from "./discover.js";
+import { HELD_BY_WORKTREE, gatherLocalBranches, gatherRemoteBranches, resolveBranch, } from "./branches.js";
+import { discoverRepo } from "./discover.js";
 import { defaultProcessProbe } from "./processes.js";
-import { fetchPrs } from "./prs.js";
-import { providers } from "./providers/index.js";
-import { resolveEntries } from "./resolve.js";
-import { ALL_SCOPES, findDuplicateCheckouts, } from "./types.js";
+import { lookupPrs, prsUnchecked } from "./prs.js";
+import { PROVIDER_CHOICES, providers } from "./providers/index.js";
+import { defaultCacheDir, ensureMirror, isRemoteUrl, redactUrl } from "./remote-mirror.js";
+import { expandTilde, resolveEntries } from "./resolve.js";
+import { KINDS, RepoCleanerError, countRows, emptyScan, findDuplicateCheckouts, } from "./types.js";
+import { errorText } from "./util.js";
 import { gatherWorktrees } from "./worktrees.js";
-function scopeSet(scope) {
-    return new Set(scope === undefined ? ALL_SCOPES : [...scope]);
+const LOCAL = ['worktree', 'branch'];
+/**
+ * The sweep `targets` and `opts` ask for, as a plan records it. Throws a
+ * {@link RepoCleanerError} for options that contradict each other or would
+ * have no effect, before anything is read.
+ */
+export function sweptWith(targets, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const conflict = (message) => {
+        throw new RepoCleanerError('conflict', message);
+    };
+    if (targets.some((t) => t.trim() === '')) {
+        throw new RepoCleanerError('bad-input', 'a target is empty');
+    }
+    const only = opts.only === undefined ? undefined : [...new Set(opts.only)];
+    const unknown = (only ?? []).filter((k) => !KINDS.includes(k));
+    if (unknown.length > 0) {
+        throw new RepoCleanerError('bad-input', `unknown kind(s) ${unknown.join(', ')}: expected ${KINDS.join(', ')}`);
+    }
+    if (only !== undefined && only.length === 0) {
+        throw new RepoCleanerError('bad-input', 'only names no kind');
+    }
+    if (opts.provider !== undefined &&
+        !PROVIDER_CHOICES.includes(opts.provider)) {
+        throw new RepoCleanerError('bad-input', `unknown provider ${JSON.stringify(opts.provider)}`);
+    }
+    const exists = (t) => existsSync(resolve(cwd, expandTilde(t)));
+    const isUrl = targets.map((t) => isRemoteUrl(t, exists));
+    const urls = isUrl.some(Boolean);
+    if (urls && !isUrl.every(Boolean)) {
+        conflict('a remote URL target sweeps remote branches only; sweep it apart from checkouts');
+    }
+    if (urls && only !== undefined && only.some((k) => k !== 'remote')) {
+        conflict(`a remote URL has only remote branches; drop --only ${only.join(',')}`);
+    }
+    if (urls && opts.branch !== undefined) {
+        conflict('--branch reads one branch of a checkout; it does not take a remote URL');
+    }
+    if (urls && opts.offline === true) {
+        conflict('a remote URL target is fetched to be swept; --offline would have no effect');
+    }
+    if (opts.branch !== undefined && targets.length > 1) {
+        conflict(`--branch sweeps one repository; ${targets.length} targets given`);
+    }
+    const remote = urls || opts.remote === true || (only ?? []).includes('remote');
+    if (opts.remote === true && only !== undefined && !only.includes('remote')) {
+        conflict(`--remote includes remote branches, but --only ${only.join(',')} leaves them out`);
+    }
+    if (opts.offline === true && !remote) {
+        conflict('--offline has no effect without --remote: nothing is fetched anyway');
+    }
+    if (opts.provider !== undefined && !remote) {
+        conflict('--provider has no effect without --remote: pull requests are looked up only for remote branches');
+    }
+    const kinds = urls
+        ? ['remote']
+        : only !== undefined
+            ? KINDS.filter((k) => only.includes(k))
+            : remote
+                ? [...LOCAL, 'remote']
+                : [...LOCAL];
+    // `HEAD` is the branch checked out at the target, resolved here so the
+    // options checked before the sweep are the ones the plan records.
+    let branch = opts.branch ?? null;
+    if (branch === 'HEAD') {
+        const at = targets[0] === undefined ? cwd : resolve(cwd, expandTilde(targets[0]));
+        try {
+            branch = resolveBranch('HEAD', new Git(at, { runner: opts.git }));
+        }
+        catch (err) {
+            throw new RepoCleanerError('conflict', err instanceof Error ? err.message : String(err));
+        }
+    }
+    return {
+        only: kinds,
+        remote,
+        offline: opts.offline === true,
+        against: opts.against ?? null,
+        provider: remote ? (opts.provider ?? 'auto') : 'none',
+        branch,
+        urls,
+    };
 }
-function clients(path, opts) {
+/**
+ * Sweep `targets`: checkouts, directories to search for checkouts, or remote
+ * URLs (swept through a clone kept in `cacheDir`, remote branches only). No
+ * targets means `[cwd]`, resolved the same way.
+ *
+ * Never throws for a repository it cannot read: that one comes back with
+ * `error` set, because a fan-out must not end on its first bad entry. Throws a
+ * {@link RepoCleanerError} for options that contradict each other, before
+ * reading anything.
+ */
+export function sweep(targets, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const { urls, ...options } = sweptWith(targets, opts);
+    const branch = options.branch ?? undefined;
+    const failed = [];
+    let entries = targets.length > 0 ? [...targets] : [cwd];
+    if (urls) {
+        const cache = opts.cacheDir ?? defaultCacheDir();
+        entries = [];
+        for (const url of targets) {
+            try {
+                entries.push(ensureMirror(url, cache, { git: opts.git }));
+            }
+            catch (err) {
+                failed.push(errorSweep(redactUrl(url), err));
+            }
+        }
+    }
+    const resolution = entries.length === 0
+        ? { repos: [], unresolved: [], scan: emptyScan() }
+        : resolveEntries(entries, {
+            git: new Git(cwd, { runner: opts.git }),
+            baseDir: cwd,
+            ...(opts.onWarn === undefined ? {} : { onWarn: opts.onWarn }),
+        });
+    if (branch !== undefined && resolution.repos.length > 1) {
+        throw new RepoCleanerError('conflict', `--branch sweeps one repository; ${resolution.repos.length} found under ${entries[0]}`);
+    }
+    const of = resolution.repos.length;
+    const repos = [
+        ...failed,
+        ...resolution.repos.map((root, i) => sweepRepo(root, {
+            ...opts,
+            only: options.only,
+            against: options.against ?? undefined,
+            provider: options.provider,
+            fetch: options.remote && !options.offline,
+            branch,
+            cwd,
+            position: { index: i + 1, of },
+        })),
+    ];
     return {
-        git: new Git(path, { runner: opts.git }),
-        gh: new Gh(path, { runner: opts.gh }),
+        repos,
+        unresolved: resolution.unresolved,
+        scan: resolution.scan,
+        duplicates: findDuplicateCheckouts(repos.map((s) => s.repo)),
+        counts: countRows(repos.flatMap((s) => s.rows)),
+        options,
     };
 }
 /**
- * Inventory one repository.
+ * The repository's note about its pull request lookup, or null when the
+ * provider answered or nothing hangs on it. A failed listing is always noted;
+ * a CLI that is missing or signed out only when a remote branch could be
+ * deleted on its account, which then needs confirm-open-pr.
+ */
+function providerNote(repo, kinds, choice) {
+    const status = repo.provider;
+    const unchecked = status === null ? null : prsUnchecked(status);
+    // With no remote there is no remote branch to gate and no forge to point
+    // at; the local rows already say the lookup failed.
+    if (status === null || unchecked === null || repo.remote === null)
+        return null;
+    // A local remote names no forge, and `auto` asks GitHub for any host that
+    // is not GitLab's, so a host that is not a forge lands here too. github.com
+    // is a forge: there the cause is access, not the provider.
+    const hint = status.host === null ||
+        (choice === 'auto' && status.name === 'github' && status.host !== 'github.com')
+        ? ' Pass `--provider none` if this remote has no forge.'
+        : '';
+    if (unchecked.kind === 'list-failed') {
+        return `Listing ${status.noun}s with \`${status.listing}\` failed (${status.listError}); judged on git evidence alone.${hint}`;
+    }
+    if (!kinds.has('remote'))
+        return null;
+    const fix = unchecked.kind === 'not-installed'
+        ? `Install \`${status.tool}\``
+        : `Sign in to \`${status.tool}\``;
+    return `Could not check for open ${status.noun}s: ${unchecked.why}, so deleting a remote branch needs confirm-open-pr. ${fix}, or pass \`--allow confirm-open-pr\` once you have checked.${hint}`;
+}
+function errorSweep(path, err) {
+    return {
+        path,
+        repo: null,
+        rows: [],
+        counts: countRows([]),
+        notes: [],
+        error: err instanceof Error ? err.message : String(err),
+    };
+}
+/**
+ * Inventory one repository, annotated and with freed branches held, as
+ * {@link sweep} does for each. The engine `check` and `run` re-sweep with.
+ * Never throws for a repository it cannot read; throws a `conflict` for a
+ * `branch` that is the default branch.
  *
- * Never throws for a repository that cannot be read: the failure is returned
- * as `error`, because a fan-out must not end on its first bad entry. A
- * single-repository caller checks that field.
+ * A failed fetch fails the repository. A lookup that only adds evidence does
+ * not: a remote whose branches `ls-remote` cannot list is read from the
+ * remote-tracking refs the fetch just wrote, and a provider whose listing
+ * fails leaves no pull request evidence. Each is a sentence in `notes`, and
+ * every row is judged on the evidence that is left.
  */
-export function sweepRepo(path, opts = {}) {
-    const scope = scopeSet(opts.scope);
-    const { git, gh } = clients(path, opts);
+export function sweepRepo(path, opts) {
+    const kinds = new Set(opts.only);
+    const git = new Git(path, { runner: opts.git });
+    const gh = new Gh(path, { runner: opts.gh });
     const known = providers({ gh, glab: opts.glab });
     const only = opts.branch;
     const at = opts.position ?? { index: 1, of: 1 };
@@ -49,8 +235,8 @@ export function sweepRepo(path, opts = {}) {
     let repo;
     try {
         repo = discoverRepo(path, {
-            remote: opts.remote ?? null,
-            allowProvider: opts.noProvider !== true,
+            remote: opts.against ?? null,
+            allowProvider: opts.provider !== 'none',
             provider: opts.provider,
             git,
             gh,
@@ -58,145 +244,173 @@ export function sweepRepo(path, opts = {}) {
         });
     }
     catch (err) {
-        if (err instanceof DiscoveryFailed)
-            return { repo: null, path, items: [], error: err.message };
-        return { repo: null, path, items: [], error: err instanceof Error ? err.message : String(err) };
+        // A `DiscoveryFailed`, or anything else that kept the repository from being read.
+        return errorSweep(path, err);
     }
     if (only === repo.mainBranch) {
-        return { repo, path, items: [], error: `refusing to clean up the default branch \`${only}\`` };
+        throw new RepoCleanerError('conflict', `--branch ${only} is the default branch, which is never a candidate for deletion`);
     }
-    const cwd = only === undefined ? (opts.cwd ?? process.cwd()) : repo.root;
-    if (opts.fetch === true && repo.remote !== null) {
+    // A branch sweep judges the worktree on its own evidence, wherever the caller stands.
+    const cwd = only === undefined ? opts.cwd : repo.root;
+    if (opts.fetch && repo.remote !== null) {
         report('fetch');
         const fetched = git
             .at(repo.root)
             .try.fetch(repo.remote, undefined, { prune: true, quiet: true, noWriteFetchHead: true });
+        // Unlike the lookups below, a failed fetch fails the repository: every
+        // row, local ones included, would be judged against a default branch
+        // older than the one asked for.
         if (!fetched.ok) {
             return {
+                ...errorSweep(path, new Error(`fetch failed: ${errorText(fetched.error)}`)),
                 repo,
-                path,
-                items: [],
-                error: `fetch failed: ${fetched.error.detail || fetched.error.message}`,
             };
         }
         repo = { ...repo, fetched: true };
     }
+    const notes = [];
     try {
         const status = repo.provider ?? null;
         if (status?.authenticated === true)
             report('prs', undefined, undefined, status.tool);
-        const prs = status === null ? new Map() : fetchPrs(repo, known[status.name], only);
-        const items = [];
+        let prs = new Map();
+        if (status !== null) {
+            const looked = lookupPrs(repo, known[status.name], only);
+            prs = looked.prs;
+            if (looked.error !== null) {
+                repo = { ...repo, provider: { ...status, listError: looked.error } };
+            }
+            const note = providerNote(repo, kinds, opts.provider);
+            if (note !== null)
+                notes.push(note);
+        }
+        const rows = [];
         // Worktrees are gathered whenever local branches are, even if they are not
         // reported: a branch checked out in one must not be judged on its own.
-        let worktreeItems = [];
+        let worktreeRows = [];
         let worktreeBranches = new Set();
-        if (scope.has('worktrees') || scope.has('local-branches')) {
+        if (kinds.has('worktree') || kinds.has('branch')) {
             ;
-            [worktreeItems, worktreeBranches] = gatherWorktrees(repo, prs, cwd, git, only, opts.probe ?? defaultProcessProbe(), ticker('worktrees'));
+            [worktreeRows, worktreeBranches] = gatherWorktrees(repo, prs, cwd, git, { branch: only, path: opts.worktree }, opts.probe ?? defaultProcessProbe(), ticker('worktree'));
         }
-        if (scope.has('worktrees'))
-            items.push(...worktreeItems);
+        if (kinds.has('worktree'))
+            rows.push(...worktreeRows);
         let localBranchNames = new Set();
-        if (scope.has('local-branches') || scope.has('remote-branches')) {
-            // A branch whose worktree goes in the same plan is judged on its own:
-            // apply removes worktrees before it deletes branches. A full sweep frees
-            // the branch of a safe-to-delete worktree; a branch-scoped sweep frees
-            // the named branch when its worktree is deletable at all.
+        if (kinds.has('branch') || kinds.has('remote')) {
+            // A branch whose worktree goes in the same run is judged on its own:
+            // a run removes worktrees before it deletes branches.
             const freed = new Map();
-            if (scope.has('worktrees')) {
-                for (const item of worktreeItems) {
-                    const branch = item.facts['branch'];
-                    if (freesBranch(item, only !== undefined) && typeof branch === 'string') {
-                        freed.set(branch, item.id);
-                    }
+            if (kinds.has('worktree')) {
+                for (const row of worktreeRows) {
+                    const branch = row.evidence.branch;
+                    if (freesBranch(row, only !== undefined) && branch !== null)
+                        freed.set(branch, row.name);
                 }
             }
             const pinned = new Set([...worktreeBranches].filter((name) => !freed.has(name)));
-            const localItems = gatherLocalBranches(repo, prs, pinned, git, only, ticker('local-branches'));
-            // Apply drops a freed branch unless the same run removes its worktree.
-            for (const item of localItems) {
-                const worktree = freed.get(item.id);
+            const localRows = gatherLocalBranches(repo, prs, pinned, git, only, ticker('branch'));
+            // A run drops a freed branch unless it also removes the worktree.
+            for (const row of localRows) {
+                const worktree = freed.get(row.name);
                 if (worktree !== undefined)
-                    item.facts['worktree'] = worktree;
+                    row.evidence.worktree = worktree;
             }
-            localBranchNames = new Set(localItems.map((item) => item.id));
-            if (scope.has('local-branches'))
-                items.push(...localItems);
+            localBranchNames = new Set(localRows.map((row) => row.name));
+            if (kinds.has('branch'))
+                rows.push(...localRows);
         }
-        if (scope.has('remote-branches')) {
-            items.push(...gatherRemoteBranches(repo, prs, localBranchNames, git, only, ticker('remote-branches')));
+        if (kinds.has('remote')) {
+            const remote = gatherRemoteBranches(repo, prs, localBranchNames, git, {
+                live: repo.fetched || opts.liveRemoteTips === true,
+                strict: opts.liveRemoteTips === true && !repo.fetched,
+                only,
+                tick: ticker('remote'),
+            });
+            rows.push(...remote.rows);
+            if (remote.note !== null)
+                notes.push(remote.note);
         }
-        return { repo, path, items, error: null };
+        const annotated = opts.annotate === undefined
+            ? rows
+            : holdFreedBranches(opts.annotate(repo, rows).map(blockedHasNoAction), only !== undefined);
+        return { path, repo, rows: annotated, counts: countRows(annotated), notes, error: null };
     }
     catch (err) {
-        return {
-            repo,
-            path,
-            items: [],
-            error: err instanceof Error ? err.message : String(err),
-        };
+        if (err instanceof RepoCleanerError)
+            throw err;
+        return { ...errorSweep(path, err), repo, notes };
     }
 }
 /**
- * Resolve `entries` and inventory every repository they name.
- *
- * Entries may be checkouts or directories containing checkouts; see
- * {@link resolveEntries}. A repository that fails discovery becomes an error
- * row and the sweep continues.
+ * Whether worktree row `row` frees its branch to be judged on its own. A full
+ * sweep frees it only for a worktree judged `delete`; a branch sweep, where the
+ * caller named the branch, for any worktree that can be removed.
  */
-export function sweepRepos(entries, opts = {}) {
-    const probe = new Git(opts.baseDir ?? process.cwd(), { runner: opts.git });
-    const resolution = resolveEntries(entries, {
-        git: probe,
-        ...(opts.baseDir === undefined ? {} : { baseDir: opts.baseDir }),
-        ...(opts.onWarn === undefined ? {} : { onWarn: opts.onWarn }),
-    });
-    const of = resolution.repos.length;
-    const repos = resolution.repos.map((root, i) => sweepRepo(root, { ...opts, position: { index: i + 1, of } }));
-    return {
-        repos,
-        unresolved: resolution.unresolved,
-        scan: resolution.scan,
-        duplicates: findDuplicateCheckouts(repos.map((sweep) => sweep.repo)),
-    };
+function freesBranch(row, branchScoped) {
+    return row.action !== null && (branchScoped || row.verdict === 'delete');
 }
-/**
- * Whether worktree row `item` frees its branch to be judged on its own. A full
- * sweep frees it only for a safe-to-delete worktree; a branch-scoped sweep,
- * where the caller named the branch, for any deletable one.
- */
-function freesBranch(item, branchScoped) {
-    return item.deletable && (branchScoped || item.classification === 'safe-to-delete');
+/** A row a host marked `blocked` can never be deleted: it keeps no action and no command. */
+function blockedHasNoAction(row) {
+    return row.verdict === 'blocked' && row.action !== null
+        ? { ...row, action: null, commands: [] }
+        : row;
 }
 /**
- * Keep again each branch a sweep freed for its worktree's removal when that
- * worktree no longer frees it by the sweep's own rule: a host's `annotate`
- * held it back or demoted it, or dropped its row. Run it on annotated rows,
- * with `branchScoped` set for a `branch` sweep, so the counts and the plan
- * match what `applyPlan` will do. Running it twice changes nothing.
+ * Keep again each branch the sweep freed for its worktree's removal when that
+ * worktree no longer frees it: a host's `annotate` held it back, demoted it,
+ * or dropped its row. Running it twice changes nothing.
  */
-export function holdFreedBranches(items, opts = {}) {
-    const going = new Set(items
-        .filter((it) => it.category === 'worktree' && freesBranch(it, opts.branchScoped === true))
-        .map((it) => it.id));
-    return items.map((item) => {
-        const worktree = item.facts['worktree'];
-        if (item.category !== 'local_branch' || typeof worktree !== 'string')
-            return item;
-        if (going.has(worktree))
-            return item;
-        const { worktree: _, ...facts } = item.facts;
+export function holdFreedBranches(rows, branchScoped) {
+    const going = new Set(rows.filter((r) => r.kind === 'worktree' && freesBranch(r, branchScoped)).map((r) => r.name));
+    return rows.map((row) => {
+        if (row.kind !== 'branch' || row.evidence.worktree === undefined)
+            return row;
+        if (going.has(row.evidence.worktree))
+            return row;
+        const { worktree: _, ...evidence } = row.evidence;
         return {
-            ...item,
-            classification: 'safe-to-keep',
-            action: 'keep',
-            reason: HELD_BY_WORKTREE,
-            facts,
+            ...row,
+            verdict: 'keep',
+            action: null,
+            why: HELD_BY_WORKTREE,
+            evidence,
             commands: [],
-            investigationParts: [],
-            requires: [],
-            deletable: false,
+            notes: [],
+            risks: [],
         };
     });
 }
+/**
+ * The worktree at `path`, judged as a sweep judges it: its verdict, risks,
+ * blockers and evidence, submodules included. Reads git and the process
+ * table; asks no provider.
+ *
+ * The main checkout is a worktree too: it comes back as its `keep` row
+ * ("primary worktree").
+ *
+ * @throws RepoCleanerError (`not-found`) when `path` is not a worktree of a
+ *   repository git can read.
+ */
+export function inspectWorktree(path, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const abs = isAbsolute(path) ? path : resolve(cwd, path);
+    const there = existsSync(abs);
+    const real = there ? realpathSync(abs) : resolve(abs);
+    // From the worktree itself when it is there; a gone one is read from the
+    // repository the caller stands in. The sweep finds the main checkout.
+    const swept = sweepRepo(there ? real : cwd, {
+        ...opts,
+        only: ['worktree'],
+        provider: 'none',
+        fetch: false,
+        cwd,
+        worktree: real,
+    });
+    if (swept.error !== null)
+        throw new RepoCleanerError('not-found', swept.error);
+    const row = swept.rows.find((r) => r.kind === 'worktree');
+    if (row === undefined) {
+        throw new RepoCleanerError('not-found', `${path} is not a worktree of ${swept.repo?.root ?? cwd}`);
+    }
+    return row;
+}