@osdlc/repo-cleaner 0.15.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @osdlc/repo-cleaner
 
+## 0.17.1
+
+### Patch Changes
+
+- Updated dependencies [4f764b7]
+  - @osdlc/typed-gh@0.15.0
+
+## 0.17.0
+
+### Minor Changes
+
+- b036603: `holdFreedBranches(items)` keeps a branch freed for its worktree's removal when that worktree no longer goes, such as when a host's `annotate` holds the worktree back. `applyPlan` runs it after `annotate`. A host should run it on its own annotated rows too, so the counts and the plan match what `apply` will do.
+
+## 0.16.0
+
+### Minor Changes
+
+- db33c17: **Breaking (CLI):** `--remote <name>` is now `--measure-remote <name>`, so it is no longer one letter away from `--remotes`. Typing `--remote` when you meant `--remotes` used to fail with "argument missing". `--no-gh` is gone; use `--provider none`, which does the same. The help no longer says the tool asks `gh`, since the provider can be GitLab.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -386,10 +386,9 @@ Every command that sweeps takes these:
 | `--only <list>` | `worktrees`, `branches`, `remotes` (default: `worktrees,branches`) |
 | `--remotes` | Also sweep remote branches. Slower: each one is compared with the default branch |
 | `--branch <name\|HEAD>` | One branch of this repository: its worktree and local branch, and its remote branch with `--remotes`. Refuses the default branch |
-| `--remote <name>` | Remote to measure against (default `origin`) |
+| `--measure-remote <name>` | The remote whose default branch work is measured against (default `origin`) |
 | `--remote-url <url>` | Sweep this remote's branches with no checkout of your own (see [A remote with no checkout](#a-remote-with-no-checkout)); repeatable |
-| `--provider <name>` | With `--remotes`: where pull requests come from: `auto` (default, by the remote's host), `github`, `gitlab` or `none` |
-| `--no-gh` | With `--remotes`: classify on git evidence alone; the same as `--provider none`. Without `--remotes`, no provider is asked |
+| `--provider <name>` | With `--remotes`: where pull requests come from: `auto` (default, by the remote's host), `github`, `gitlab`, or `none` to classify on git evidence alone |
 | `--no-fetch` | With `--remotes`: skip the fetch; the header then says `not fetched`. Without `--remotes`, nothing is fetched |
 
 `status` also takes:
@@ -530,8 +529,14 @@ so the rows it checks again are the rows the host planned from.
 
 This works because of how the ladder is ordered. Every verdict the sweep
 reaches on its own evidence outranks anything a host could contribute, so a
-host never has to veto one. It only sharpens the rows left at `safe-to-keep`
-or `needs-investigation`.
+host rarely has to veto one. It mostly sharpens the rows left at
+`safe-to-keep` or `needs-investigation`.
+
+A host that does hold back or demote a worktree row must also keep that
+worktree's branch, which the sweep freed because the worktree was going. Pass
+the annotated rows through `holdFreedBranches(items, { branchScoped })`, with
+`branchScoped` set for a `branch` sweep. `applyPlan` does the same after its
+`annotate` hook, so the plan and the run agree.
 
 An issue tracker's linkage, applied this way, is a host's own layer over the
 sweep and `applyPlan`.

package/dist/apply.d.ts

@@ -55,7 +55,8 @@ export interface ApplyOptions extends HostHooks {
     safeOnly?: boolean | undefined;
     /**
      * Items to re-check against instead of sweeping again, keyed by repository
-     * root, already annotated: the hook is not applied to them again. For a
+     * root, already annotated: the hook is not applied to them again, though
+     * `holdFreedBranches` is, so a freed branch matches its worktree. For a
      * preview straight after a sweep; the run that deletes should always sweep
      * again.
      */

package/dist/apply.js

@@ -22,7 +22,7 @@ import { localDeleteCommand, remoteDeleteCommand } from "./branches.js";
 import { busyHolders, defaultProcessProbe, parseLockOwner } from "./processes.js";
 import { PLAN_CATEGORIES, fingerprint, isPlanCategory, sameFingerprint, } from "./plan.js";
 import { RECEIPT_VERSION } from "./receipt.js";
-import { sweepRepo } from "./sweep.js";
+import { holdFreedBranches, sweepRepo } from "./sweep.js";
 import { AUTHORIZATIONS, } from "./types.js";
 import { worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand } from "./worktrees.js";
 import { writeJsonAtomic } from "./write-json.js";
@@ -89,9 +89,10 @@ const SCOPE_OF = {
 };
 /** The plan repository's rows as they stand now, with the host's overlay applied. */
 function resweep(repo, scope, opts) {
+    const branchScoped = repo.branch != null;
     const given = opts.swept?.get(repo.root);
     if (given !== undefined) {
-        return [...given];
+        return holdFreedBranches([...given], { branchScoped });
     }
     const sweep = sweepRepo(repo.root, {
         remote: repo.remote,
@@ -110,7 +111,9 @@ function resweep(repo, scope, opts) {
     if (sweep.repo === null || sweep.error !== null) {
         throw new Error(sweep.error ?? `could not read repository: ${repo.root}`);
     }
-    return opts.annotate === undefined ? sweep.items : opts.annotate(sweep.repo, sweep.items);
+    return opts.annotate === undefined
+        ? sweep.items
+        : holdFreedBranches(opts.annotate(sweep.repo, sweep.items), { branchScoped });
 }
 /** Re-sweep, then split the selection into rows to run and rows dropped. */
 function recheck(selected, kept, grants, implicit, opts) {

package/dist/branches.d.ts

@@ -41,11 +41,13 @@ export declare function mergedFact(e: {
 }): boolean;
 /** `HEAD` as the branch checked out at `git`'s directory; any other name as given. */
 export declare function resolveBranch(value: string, git: Git): string;
+/** Why a branch checked out in a worktree is kept. */
+export declare const HELD_BY_WORKTREE = "checked out in a worktree (handle via that worktree)";
 /**
  * Delete local branch `name` only while it still points at `sha` (the full
- * sha). Same caveats as `deleteRef` in `@osdlc/typed-git`. Only a `branch`
- * sweep proposes a branch checked out in a worktree, and only alongside that
- * worktree's removal, which must run first.
+ * sha). Same caveats as `deleteRef` in `@osdlc/typed-git`. A sweep proposes a
+ * branch checked out in a worktree only alongside that worktree's removal,
+ * which must run first.
  */
 export declare function localDeleteCommand(name: string, sha: string): string;
 /** Delete `remote`'s branch `name` only while it still points at `sha`. */

package/dist/branches.js

@@ -90,11 +90,13 @@ export function resolveBranch(value, git) {
         throw new Error(`--branch HEAD: no branch is checked out at ${git.cwd}`);
     return current;
 }
+/** Why a branch checked out in a worktree is kept. */
+export const HELD_BY_WORKTREE = 'checked out in a worktree (handle via that worktree)';
 /**
  * Delete local branch `name` only while it still points at `sha` (the full
- * sha). Same caveats as `deleteRef` in `@osdlc/typed-git`. Only a `branch`
- * sweep proposes a branch checked out in a worktree, and only alongside that
- * worktree's removal, which must run first.
+ * sha). Same caveats as `deleteRef` in `@osdlc/typed-git`. A sweep proposes a
+ * branch checked out in a worktree only alongside that worktree's removal,
+ * which must run first.
  */
 export function localDeleteCommand(name, sha) {
     return shellJoin(['git', 'update-ref', '-d', `refs/heads/${name}`, sha]);
@@ -159,7 +161,7 @@ export function classifyLocalBranch(opts) {
     const held = name === repo.currentBranch
         ? 'current HEAD'
         : worktreeBranches.has(name)
-            ? 'checked out in a worktree (handle via that worktree)'
+            ? HELD_BY_WORKTREE
             : null;
     if (held !== null) {
         // Never deletable here, but still counted as merged or not: by ancestry or

package/dist/cli.js

@@ -65,10 +65,10 @@ const SWEEP_FLAGS = {
         valueName: 'name|HEAD',
         help: 'only this branch of this repository: its worktree and local branch, and its remote branch with --remotes',
     },
-    remote: {
+    measureRemote: {
         kind: 'string',
         valueName: 'name',
-        help: 'remote to measure against (default: origin)',
+        help: 'the remote whose default branch work is measured against (default: origin)',
     },
     remoteUrl: {
         kind: 'list',
@@ -77,16 +77,11 @@ const SWEEP_FLAGS = {
         commaSeparated: false,
         help: 'sweep the branches of this remote with no checkout of your own, through a clone kept in the cache directory; repeatable',
     },
-    gh: {
-        kind: 'boolean',
-        negatable: true,
-        help: 'with --remotes: classify on git evidence alone, the same as --provider none (without --remotes no provider is asked)',
-    },
     provider: {
         kind: 'enum',
         choices: PROVIDER_CHOICES,
         valueName: 'name',
-        help: 'with --remotes: where pull requests come from: auto (by remote host), github (gh), gitlab (glab), none',
+        help: 'with --remotes: where pull requests come from: auto (by remote host), github (gh), gitlab (glab), or none to classify on git evidence alone',
     },
     fetch: {
         kind: 'boolean',
@@ -117,7 +112,7 @@ const statusCli = () => defineCli({
     name: NAME,
     summary: 'Inventory local branches and worktrees (remote branches too with --remotes), and say ' +
         'which have been merged into the default branch. Offline unless --remotes, which fetches ' +
-        'each remote first and asks gh about pull requests; deletes nothing.',
+        'each remote first and asks the remote host about pull requests; deletes nothing.',
     positionals: PATHS,
     flags: {
         ...SWEEP_FLAGS,
@@ -276,7 +271,7 @@ function remotesNote(swept, style) {
         return '';
     if (!swept.result.repos.some((r) => r.repo?.remote != null))
         return '';
-    return (style.muted('Local only: nothing fetched, no gh, remote branches not checked; add --remotes for all three.') + '\n');
+    return (style.muted('Local only: nothing fetched, no pull requests looked up, remote branches not checked; add --remotes for all three.') + '\n');
 }
 /** Where `--remote-url` keeps its clones. */
 function mirrorCache(ctx) {
@@ -322,10 +317,6 @@ function sweep(name, v, paths, ctx, status) {
         if (conflict !== null)
             return { kind: 'exit', code: usageError(ctx, name, conflict) };
     }
-    if (!v.gh && v.provider !== undefined && v.provider !== 'none') {
-        const message = `--no-gh asks no provider; drop it or --provider ${v.provider}`;
-        return { kind: 'exit', code: usageError(ctx, name, message) };
-    }
     let branch;
     try {
         branch = v.branch === undefined ? undefined : resolveBranch(v.branch, new Git(ctx.cwd));
@@ -338,8 +329,8 @@ function sweep(name, v, paths, ctx, status) {
     const options = {
         baseDir: ctx.cwd,
         cwd: ctx.cwd,
-        // Local by default means offline: the fetch and gh go with remote branches.
-        noProvider: !(online && v.gh) || v.provider === 'none',
+        // Local by default means offline: the fetch and the pull-request lookup go with remote branches.
+        noProvider: !online || v.provider === 'none',
         fetch: online && v.fetch,
         provider: v.provider,
         branch,
@@ -348,7 +339,7 @@ function sweep(name, v, paths, ctx, status) {
         onWarn: (message) => ctx.io.stderr(`${NAME}: ${message}\n`),
         ...(v.progress ? { onProgress: (p) => status.update(describeSweep(p)) } : {}),
         scope,
-        ...(v.remote === undefined ? {} : { remote: v.remote }),
+        ...(v.measureRemote === undefined ? {} : { remote: v.measureRemote }),
     };
     let entries = paths.length > 0 ? [...paths] : [ctx.cwd];
     if (urls.length > 0) {
@@ -393,7 +384,7 @@ function reportUnreadable(ctx, name, result) {
 }
 function planOf(swept, now) {
     const opts = {
-        remote: swept.values.remote ?? null,
+        remote: swept.values.measureRemote ?? null,
         noProvider: swept.noProvider,
         provider: swept.values.provider,
         branch: swept.branch ?? null,
@@ -539,7 +530,7 @@ function applyConflict(v, paths) {
             paths.length > 0 ? 'paths' : null,
             v.only !== undefined ? '--only' : null,
             v.branch !== undefined ? '--branch' : null,
-            v.remote !== undefined ? '--remote' : null,
+            v.measureRemote !== undefined ? '--measure-remote' : null,
             v.remoteUrl.length > 0 ? '--remote-url' : null,
         ].filter((f) => f !== null);
         if (sweepFlags.length > 0)

package/dist/hooks.d.ts

@@ -7,7 +7,10 @@
 import type { RepoInfo, SweepItem } from './types.ts';
 /**
  * Re-rank a repository's swept rows with what the host knows. Runs after the
- * sweep, on its output; it never reaches into classification.
+ * sweep, on its output; it never reaches into classification. A host that
+ * holds back or demotes a worktree passes its own annotated rows through
+ * `holdFreedBranches`, as `applyPlan` does, so that worktree's branch is kept
+ * too.
  */
 export type Annotate = (repo: RepoInfo, items: SweepItem[]) => SweepItem[];
 export interface HostHooks {

package/dist/index.d.ts

@@ -26,6 +26,6 @@ export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, type De
 export { fetchPrs } from './prs.ts';
 export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, type ForgeTarget, type PrProvider, type ProviderChoice, type ProviderName, type ProviderStatus, } from './providers/index.ts';
 export { expandTilde, isCheckoutRoot, resolveEntries, type Resolution, type ResolveOptions, } from './resolve.ts';
-export { sweepRepo, sweepRepos, type SweepOptions, type SweepReposOptions } from './sweep.ts';
+export { holdFreedBranches, sweepRepo, sweepRepos, type SweepOptions, type SweepReposOptions, } from './sweep.ts';
 export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, type ApplySummary, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
 export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, type Authorization, type Category, type Classification, type DuplicateCheckout, type PRInfo, type RepoInfo, type RepoSweep, type ScanStats, type Scope, type SummaryBucket, type SweepItem, type SweepProgress, type SweepResult, type UnresolvedEntry, } from './types.ts';

package/dist/index.js

@@ -25,6 +25,6 @@ export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, } from
 export { fetchPrs } from "./prs.js";
 export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, } from "./providers/index.js";
 export { expandTilde, isCheckoutRoot, resolveEntries, } from "./resolve.js";
-export { sweepRepo, sweepRepos } from "./sweep.js";
+export { holdFreedBranches, sweepRepo, sweepRepos, } from "./sweep.js";
 export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
 export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, } from "./types.js";

package/dist/sweep.d.ts

@@ -8,7 +8,7 @@
 import type { CommandRunner } from '@osdlc/command-seam';
 import { type ProcessProbe } from './processes.ts';
 import { type ProviderChoice } from './providers/index.ts';
-import { type RepoSweep, type Scope, type SweepProgress, type SweepResult } from './types.ts';
+import { type RepoSweep, type Scope, type SweepItem, type SweepProgress, type SweepResult } from './types.ts';
 export interface SweepOptions {
     /** Which categories to gather. Defaults to all of them. */
     scope?: Iterable<Scope | string>;
@@ -37,7 +37,8 @@ export interface SweepOptions {
      * its remote branch. The default branch is refused. `cwd` is ignored, so the
      * worktree is judged on its facts, and the local branch is not pinned for
      * being checked out there: apply removes the worktree first. It stays pinned
-     * when that worktree is blocked or cannot be removed.
+     * when that worktree is blocked or cannot be removed, or when `scope` leaves
+     * worktrees out.
      */
     branch?: string | undefined;
     /** Injected runners. Defaults spawn the real `git`, `gh` and `glab`. */
@@ -80,3 +81,13 @@ export interface SweepReposOptions extends SweepOptions {
  * row and the sweep continues.
  */
 export declare function sweepRepos(entries: readonly string[], opts?: SweepReposOptions): SweepResult;
+/**
+ * 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.
+ */
+export declare function holdFreedBranches(items: SweepItem[], opts?: {
+    branchScoped?: boolean;
+}): SweepItem[];

package/dist/sweep.js

@@ -7,7 +7,7 @@
  */
 import { Git } from '@osdlc/typed-git';
 import { Gh } from '@osdlc/typed-gh';
-import { gatherLocalBranches, gatherRemoteBranches } from "./branches.js";
+import { HELD_BY_WORKTREE, gatherLocalBranches, gatherRemoteBranches } from "./branches.js";
 import { DiscoveryFailed, discoverRepo } from "./discover.js";
 import { defaultProcessProbe } from "./processes.js";
 import { fetchPrs } from "./prs.js";
@@ -107,9 +107,9 @@ export function sweepRepo(path, opts = {}) {
             if (scope.has('worktrees')) {
                 for (const item of worktreeItems) {
                     const branch = item.facts['branch'];
-                    const goes = item.deletable && (only !== undefined || item.classification === 'safe-to-delete');
-                    if (goes && typeof branch === 'string')
+                    if (freesBranch(item, only !== undefined) && typeof branch === 'string') {
                         freed.set(branch, item.id);
+                    }
                 }
             }
             const pinned = new Set([...worktreeBranches].filter((name) => !freed.has(name)));
@@ -161,3 +161,42 @@ export function sweepRepos(entries, opts = {}) {
         duplicates: findDuplicateCheckouts(repos.map((sweep) => sweep.repo)),
     };
 }
+/**
+ * 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');
+}
+/**
+ * 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.
+ */
+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;
+        return {
+            ...item,
+            classification: 'safe-to-keep',
+            action: 'keep',
+            reason: HELD_BY_WORKTREE,
+            facts,
+            commands: [],
+            investigationParts: [],
+            requires: [],
+            deletable: false,
+        };
+    });
+}

package/dist/types.d.ts

@@ -53,7 +53,7 @@ export interface RepoInfo {
     /**
      * 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`, `--no-gh`, or a sweep without `--remotes`).
+     * (`--provider none`, or a sweep without `--remotes`).
      */
     provider: ProviderStatus | null;
     /** True when the sweep fetched the remote before classifying. */

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.15.0";
+export declare const VERSION = "0.17.1";

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.15.0';
+export const VERSION = '0.17.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.15.0",
+  "version": "0.17.1",
   "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",
@@ -50,11 +50,11 @@
   "dependencies": {
     "zod": "^4.6.6",
     "@osdlc/cli-tool": "^0.16.0",
+    "@osdlc/typed-gh": "^0.15.0",
     "@osdlc/command-seam": "^0.14.0",
-    "@osdlc/typed-gh": "^0.14.1",
     "@osdlc/typed-git": "^0.12.0",
-    "@osdlc/path-guard": "^0.3.1",
-    "@osdlc/ux": "^0.1.1"
+    "@osdlc/ux": "^0.1.1",
+    "@osdlc/path-guard": "^0.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
@@ -63,8 +63,8 @@
     "prettier": "3.9.6",
     "typescript": "~6.0.3",
     "vitest": "^5.0.5",
-    "@osdlc/prettier-config": "^0.3.1",
-    "@osdlc/tsconfig": "^0.4.1"
+    "@osdlc/tsconfig": "^0.4.1",
+    "@osdlc/prettier-config": "^0.3.1"
   },
   "scripts": {
     "build": "cli-tool-stamp-version && tsc -p tsconfig.build.json",