@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/reference.js

@@ -0,0 +1,152 @@
+/**
+ * The full reference `--help --extended` prints: what every option means,
+ * the words the report uses, and which combinations are refused. The README
+ * says the same in its own layout; keep the two in step.
+ */
+const TARGETS = `Targets
+  A target is what to sweep:
+    a checkout            that repository; a linked worktree sweeps the repository it belongs to
+    a directory           every checkout found under it, three levels deep at most
+    a remote URL          its remote branches only, through a clone kept in the cache
+                          directory (https://, ssh://, file://, or user@host:path)
+  No target sweeps the directory you are in, read the same way.`;
+const SWEEP = `Sweep options (the report, plan and clean)
+  --remote                Also judge remote branches. Turns on the network: fetches
+                          each remote first and asks GitHub or GitLab about pull
+                          requests. Slower.
+  --offline               With --remote: do not fetch; judge against the
+                          remote-tracking refs already on disk, remote branches
+                          included, so judging does not contact the remote. Tips can
+                          be stale; clean asks the remote before deleting on it.
+                          Pull requests are still looked up; add --provider none
+                          to judge with no network at all.
+  --only <kinds>          Only these kinds of row: worktree, branch, remote,
+                          comma-separated. Default: worktree,branch, plus remote with
+                          --remote. Naming remote implies --remote.
+  --branch <name|HEAD>    Only the rows of one branch: its worktree, its local branch,
+                          and its remote branch with --remote. HEAD is the branch
+                          checked out at the target. Never the default branch.
+  --against <remote>      The remote whose default branch counts as "merged into".
+                          Default: origin, then the first remote.
+  --provider <name>       With --remote: where pull requests come from. auto (by the
+                          remote's host), github, gitlab, or none to judge on git
+                          evidence alone.
+  --no-progress           No progress line on stderr.`;
+const REPORT = `The report: repo-cleaner [target...]
+  Deletes nothing. Lists each row with its verdict, why, the risks it carries,
+  and the command that would delete it.
+  --all                   Also show keep rows. By default only delete, review and
+                          blocked rows are listed. Only with --format text.
+  --format text           The report. The default.
+  --format summary        Counts per repository: total, merged, delete, prune,
+                          review, blocked, keep.
+  --format commands       Only the commands of delete rows that carry no risk.
+  --format json           Everything, evidence included, for scripts.`;
+const PLAN = `repo-cleaner plan [target...]
+  Sweeps and saves every row, each with a fingerprint of the evidence behind its
+  verdict, so it can be reviewed now and run later with clean --plan.
+  -o, --out <file>        Where the plan goes; - (the default) is stdout.`;
+const CLEAN = `repo-cleaner clean [target...]
+  Sweeps (or reads --plan), checks every row again, shows the steps, asks, then
+  deletes, compare-and-swap, verifying each step and stopping at the first failure.
+  Without --pick it runs every row judged delete.
+  --pick <row>            Work on exactly these rows. Narrows the run to them, and opts
+                          in review rows and kept rows with an action (an open pull
+                          request), which never run otherwise. A picked row still
+                          needs --allow for its risks. A blocked row is skipped.
+                          Repeatable.
+  --spare <row>           Leave this row alone, and make sure it is what you saw. A
+                          spared row is not deleted, even if it is judged delete. A
+                          spared remote branch is still checked: if its tip moved or
+                          it is gone since the plan, the run stops before deleting
+                          anything. Sparing a worktree also spares its branch.
+                          Repeatable.
+  --allow <risk>          Accept this risk for every row that carries it.
+  --allow <risk>=<row>    Accept it for that one row only.
+  --plan <file|->         Run a saved plan instead of sweeping now (- reads stdin).
+                          Rows whose evidence changed since the plan are dropped.
+  -y, --yes               Do not ask. Without it, and with no terminal to ask on,
+                          clean refuses.
+  --dry-run               Check and show the steps, then stop.
+  --receipt <file>        Write a record of every step, rewritten after each one.
+                          Default: next to a --plan file; none otherwise.
+  --format text|json      How the steps and the outcome are shown.`;
+const CACHE = `repo-cleaner cache [list | remove <url>... | remove --all]
+  Lists or removes the clones kept for remote URL targets. A removed clone is
+  cloned again by the next sweep of its URL; a plan that names it cannot run.`;
+const WORDS = `Rows
+  One thing that could be deleted, named <kind>:<name>:
+    worktree:<path>         a linked worktree: removed with git worktree remove, or,
+                            when its directory is already gone, its record pruned
+    branch:<name>           a local branch, deleted with git update-ref -d <sha>
+    remote:<remote>/<name>  a branch on a remote, deleted by a push with a lease
+  A bare name or path works when only one row has it.
+
+Verdicts
+  delete    Its work is on the default branch, or it is otherwise safe to lose.
+            clean deletes it, once its risks are allowed.
+  review    The signals are mixed, or it holds work. Deleted only when picked and
+            its risks are allowed.
+  blocked   Something rules removal out: a lock, a running process, a submodule
+            that cannot be read, hidden index flags, a nested repository, a branch
+            checked out twice. Never deleted; fix the cause and sweep again.
+  keep      Structural (the default branch, the current checkout, the primary
+            worktree): never deleted. Or in use (an open pull request): deleted
+            only when picked and confirm-open-pr is allowed.
+  prune     Shown for a delete row whose worktree directory is already gone: only
+            the stale record goes.
+
+Risks (approve each by name with --allow)
+  abandon-unmerged   Commits that are not on the default branch, or a worktree's
+                     (or its submodules') commits and stashes that no remote has.
+  discard-changes    Uncommitted or untracked files in the worktree or any of its
+                     submodules.
+  confirm-open-pr    The branch has an open pull request, or open pull requests could
+                     not be checked (the CLI is missing or signed out, or the listing
+                     failed); deleting the remote branch closes it.
+  A worktree's submodules are part of it: one --allow on the worktree row covers
+  the same risk in every submodule.`;
+const CONFLICTS = `Refused before anything is deleted (exit 2)
+  A combination is refused when it contradicts itself, or when one of its options
+  would have no effect. Most are refused before anything is swept; a row named
+  two ways (a bare name and its id), and an --allow for a row, are checked
+  against the plan, after the sweep.
+    the same row in --pick and --spare
+    --allow <risk>=<row> for a spared row, or for a row outside --pick
+    a picked or spared row of a kind --only leaves out
+    a picked or spared row that is not one of --branch's rows
+    --branch with more than one target, or with a remote URL, or the default branch
+    --plan with targets or sweep options: the plan already fixed them
+    --plan - without --yes or --dry-run: stdin carries the plan, so nothing can ask
+    --yes with --dry-run
+    --receipt with --dry-run
+    --offline or --provider without --remote
+    --remote with an --only that leaves remote out
+    a remote URL target with --only worktree or --only branch, with --offline, or
+      mixed with checkout targets
+    --all with any --format but text
+
+Refused after the sweep, before deleting (exit 1)
+    a picked, spared or allowed row the plan does not have
+    a row name that matches rows in more than one repository
+    a spared remote branch that moved since the plan, or that the re-check no longer finds
+
+Allowed, because nothing contradicts
+    the same row picked twice: it runs once
+    --allow <risk> with --allow <risk>=<row>: the broader one covers it
+    --allow for a risk no row that runs carries: the preview lists it as unused
+    picking a blocked or keep row: it is skipped and shown with the reason
+    --only remote without --remote: asking for remote branches implies the network`;
+const EXIT = `Exit codes
+  0    swept; or clean ran, was declined, or had nothing to do
+  1    failed against the state it found: an unreadable plan, a row not in it
+  2    cannot run as typed: an unknown flag, a malformed row, a refused combination
+  10   no target named a repository
+  11   clean stopped at a failed step; the receipt says which`;
+/** The extended help for each command: its own options, then the shared vocabulary. */
+export const REFERENCE = {
+    report: [TARGETS, SWEEP, REPORT, WORDS, CONFLICTS, EXIT].join('\n\n'),
+    plan: [TARGETS, SWEEP, PLAN, WORDS, EXIT].join('\n\n'),
+    clean: [TARGETS, SWEEP, CLEAN, WORDS, CONFLICTS, EXIT].join('\n\n'),
+    cache: CACHE,
+};

package/dist/remote-mirror.d.ts

@@ -8,7 +8,7 @@
  * 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
+ * plan names the clone's directory, and `clean` re-sweeps and pushes deletes
  * from there. A later run reuses it, and the sweep's fetch brings it up to
  * date.
  */
@@ -77,3 +77,11 @@ export declare function listMirrors(cacheDir: string, opts?: {
  * given, credentials included.
  */
 export declare function cachedMirrorOf(url: string, cacheDir: string): string | null;
+/**
+ * True when `target` names a remote rather than a directory: a URL with a
+ * scheme (`https://`, `ssh://`, `file://`), or the scp form `user@host:path`
+ * that names no directory on disk. A Windows drive path is never one.
+ */
+export declare function isRemoteUrl(target: string, exists: (path: string) => boolean): boolean;
+/** Where remote URL targets' clones are kept: `repo-cleaner/remotes` under the user's cache directory. */
+export declare function defaultCacheDir(env?: Record<string, string | undefined>): string;

package/dist/remote-mirror.js

@@ -8,14 +8,16 @@
  * 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
+ * plan names the clone's directory, and `clean` 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, lstatSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { systemDirs } from '@osdlc/cli-tool';
 import { Git, parseRemoteRepo } from '@osdlc/typed-git';
+import { VENDOR_DIRS } from "./devlink.js";
 /** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
 export class RemoteMirrorError extends Error {
     constructor(message) {
@@ -163,3 +165,19 @@ export function cachedMirrorOf(url, cacheDir) {
     const dir = join(cacheDir, mirrorName(url));
     return existsSync(dir) ? dir : null;
 }
+/**
+ * True when `target` names a remote rather than a directory: a URL with a
+ * scheme (`https://`, `ssh://`, `file://`), or the scp form `user@host:path`
+ * that names no directory on disk. A Windows drive path is never one.
+ */
+export function isRemoteUrl(target, exists) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target))
+        return true;
+    if (/^[a-z]:[\\/]/i.test(target))
+        return false;
+    return /^(?:[^@/:\\]+@)?[^/:\\]+:(?!\/\/).+$/.test(target) && !exists(target);
+}
+/** Where remote URL targets' clones are kept: `repo-cleaner/remotes` under the user's cache directory. */
+export function defaultCacheDir(env = process.env) {
+    return systemDirs(VENDOR_DIRS, { env }).standalone('repo-cleaner').cache().app('remotes').path;
+}

package/dist/render.d.ts

@@ -1,13 +1,14 @@
 /**
- * Rendering a sweep for a terminal, and for a program.
+ * Rendering a sweep and a run, for a terminal and for a program.
  *
  * The text report is columnar because it is read by eye across repositories:
- * the eye finds a column, and a line-per-item paragraph gives it nothing to
- * find. JSON carries everything the text report elides, including the facts
- * behind every verdict.
+ * the eye finds a column, and a line-per-row paragraph gives it nothing to
+ * find. JSON carries everything the text report leaves out, the evidence
+ * behind every verdict included.
  */
-import type { Receipt, Step } from './receipt.ts';
-import { type RepoSweep, type SweepItem, type SweepResult } from './types.ts';
+import type { Preview } from './clean.ts';
+import type { Dropped, Receipt, Step } from './receipt.ts';
+import { type Kind, type RepoSweep, type Sweep } from './types.ts';
 /**
  * How a report colors its words. {@link PLAIN} leaves them as they are; the
  * CLI passes {@link TERMINAL_STYLE} when the stream is a terminal that takes
@@ -31,57 +32,43 @@ export interface Style {
 export declare const PLAIN: Style;
 /** The basic terminal colors: red to delete, blue to prune, yellow to review, green to keep. */
 export declare const TERMINAL_STYLE: Style;
-/**
- * A row's authorizations for a report, e.g. `requires abandon-unmerged (drops 3
- * commits), confirm-open-pr`. Empty when the row needs none.
- */
-export declare function requiresNote(item: Pick<SweepItem, 'requires' | 'facts'>): string;
-/** One repository's rows, indented under its header. */
+/** One repository's rows, indented under its header. `all` shows `keep` rows too. */
 export declare function renderRepo(sweep: RepoSweep, opts?: {
-    keep?: boolean;
+    all?: boolean;
     style?: Style;
 }): string;
 /**
- * What the search cost, or null when nothing was searched — every entry
+ * What the search cost, or null when nothing was searched — every target
  * named a checkout outright.
  *
- * Worth a line because the numbers are how a person catches an entry
+ * Worth a line because the numbers are how a person catches a target
  * pointing at the wrong directory: thousands of directories read for three
- * repositories says the entry is a home directory, not a workspace.
+ * repositories says the target is a home directory, not a workspace.
  */
-export declare function renderScan(result: SweepResult): string | null;
+export declare function renderScan(sweep: Pick<Sweep, 'scan'>): string | null;
 /** The one-line verdict a person reads first, and often only. */
-export declare function renderSummary(result: SweepResult, style?: Style): string;
-/**
- * One repository as counts: a row per category with its total, how many are
- * 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. */
-export declare function renderCountsText(result: SweepResult, style?: Style): string;
-/** The whole run's counts as JSON: no rows, no facts. */
-export declare function renderCountsJson(result: SweepResult): string;
-/** The whole run as text: duplicate checkouts, a section per repository, then the summary. */
-export declare function renderText(result: SweepResult, opts?: {
-    keep?: boolean;
+export declare function renderTotals(sweep: Sweep, style?: Style): string;
+/** The sweep as counts (`--format summary`): a table per repository, then the totals line. */
+export declare function renderSummary(sweep: Sweep, style?: Style): string;
+/** The sweep as text: duplicate checkouts, a section per repository, then the totals. */
+export declare function renderText(sweep: Sweep, opts?: {
+    all?: boolean;
     style?: Style;
 }): string;
-/**
- * The whole run as JSON, facts included. `extra` adds top-level keys, such as
- * the path of a plan the run wrote.
- */
-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[];
-/** 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. */
+/** The sweep as JSON: every row with its evidence, the counts, and what was swept. */
+export declare function renderJson(sweep: Sweep, extra?: Record<string, unknown>): string;
+/** Every command of a `delete` row that carries no risk, in report order (`--format commands`). */
+export declare function renderCommands(sweep: Sweep): string[];
+/** What a run did, or would do, counted by kind. */
+export interface RunSummary {
+    /**
+     * Rows deleted (or, in a preview, that would be), by kind. Pruned worktrees,
+     * and remote branches a delete step found already gone, are counted apart.
+     */
+    deleted: Record<Kind, number>;
+    /** Remote branches a delete step found the remote had already deleted. */
+    gone: number;
+    /** Worktrees whose stale record was pruned; their directories were gone or left alone. */
     pruned: number;
     /** Dropped rows by reason. */
     dropped: Record<string, number>;
@@ -90,29 +77,47 @@ export interface ApplySummary {
     /** 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, skipped and could not finish. */
-export declare function renderApplySummary(receipt: Receipt): string[];
+/** Count what `steps` did and `dropped` left out. A preview's `would-run` steps count as done. */
+export declare function summarizeRun(r: {
+    steps: readonly Step[];
+    dropped: readonly Dropped[];
+}): RunSummary;
+/** Rows a run deletes or prunes, which is what a person is asked to approve. */
+export declare function rowsActedOn(summary: RunSummary): number;
+/** The closing lines of a run or preview: what it deleted, skipped and could not finish. */
+export declare function renderRunSummary(r: {
+    steps: readonly Step[];
+    dropped: readonly Dropped[];
+}, opts?: {
+    preview?: boolean;
+}): string[];
 /** The word a preview shows for a step: what it does to the row. */
 export declare const STEP_VERB: Record<Step['action'], string>;
 /**
- * What `apply` is about to do, for the person asked to approve it: per
- * repository, each row and the command that deletes it, the rows it will
- * skip and why, then the counts. Terminal controls are stripped from what it
- * shows, so a path or name cannot hide part of what is approved.
+ * What a run is about to do, for the person asked to approve it: per
+ * repository, each row and the command that deletes it, the rows it will skip
+ * and why, the allows no row needed, then the counts. Terminal controls are
+ * stripped from what it shows, so a path or name cannot hide part of what is
+ * approved.
  */
-export declare function renderPreview(receipt: Receipt, style?: Style): string;
-/** Rows dropped by a live run's own re-check, after the preview: each with why. */
-export declare function renderPreviewDrops(dropped: Receipt['dropped'], style?: Style): string;
+export declare function renderPreview(p: Pick<Preview, 'steps' | 'dropped'> & Partial<Pick<Preview, 'unusedAllows'>>, style?: Style): string;
+/** Rows dropped by a run's own re-check after the preview, each with why. */
+export declare function renderLateDrops(dropped: readonly Dropped[], style?: Style): string;
 /**
  * A failed step for a run shown live: `✗`, the row, and the error in full,
- * which the step's row on the board is too narrow to hold.
+ * which the step's line on the board is too narrow to hold.
  */
 export declare function renderStepFailure(step: Step, style?: Style): string;
-/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
+/** A run as text: dropped rows, each step, a summary, then where the receipt is. */
 export declare function renderReceipt(receipt: Receipt, receiptPath: string | null, style?: Style, opts?: {
     steps?: boolean;
 }): string;
+/** The renderers a library user needs: the CLI's own formats. */
+export declare const render: {
+    text: typeof renderText;
+    json: typeof renderJson;
+    summary: typeof renderSummary;
+    commands: typeof renderCommands;
+    preview: typeof renderPreview;
+    receipt: typeof renderReceipt;
+};