@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/sweep.d.ts

@@ -1,93 +1,136 @@
 /**
- * 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 type { CommandRunner } from '@osdlc/command-seam';
+import type { Annotate } from './hooks.ts';
 import { type ProcessProbe } from './processes.ts';
 import { type ProviderChoice } from './providers/index.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>;
-    /** Remote to measure against. Defaults to `origin`, then the first one. */
-    remote?: string | null;
-    /** Ask no provider and classify on git evidence alone. Same as `provider: 'none'`, and wins over it. */
-    noProvider?: boolean;
+import { type Kind, type RepoSweep, type Row, type Sweep, type SweepProgress, type SweptWith, type WorktreeRow } from './types.ts';
+/** Runners and the process probe: what a test or a host injects. */
+export interface Runners {
+    /** Defaults spawn the real `git`, `gh` and `glab`. */
+    git?: CommandRunner | undefined;
+    gh?: CommandRunner | undefined;
+    glab?: CommandRunner | undefined;
     /**
-     * Which provider to ask for pull requests: `github` (`gh`), `gitlab`
-     * (`glab`), `none`, or `auto`, which reads the remote's host. Defaults to `auto`.
+     * Answers whether a worktree lock's owner is alive and which processes work
+     * inside a worktree. Defaults to {@link defaultProcessProbe}, over `ps` and
+     * `lsof`.
      */
+    probe?: ProcessProbe | undefined;
+}
+export interface SweepOptions extends Runners {
+    /** Only these kinds of row. Default: `worktree` and `branch`, and `remote` with `remote`. Naming `remote` implies `remote`. */
+    only?: readonly Kind[] | undefined;
+    /** Also judge remote branches: fetches each remote first and looks up pull requests. */
+    remote?: boolean | undefined;
+    /** With `remote`: do not fetch; judge against the remote-tracking refs on disk. */
+    offline?: boolean | undefined;
+    /** The remote whose default branch counts as "merged into". Default `origin`, then the first remote. */
+    against?: string | undefined;
+    /** With `remote`: where pull requests come from. Default `auto`, by the remote's host. */
     provider?: ProviderChoice | undefined;
     /**
-     * Run `git fetch --prune <remote>` before classifying, so ancestry is read
-     * against fresh remote-tracking refs. A failed fetch makes the repository
-     * an error row. Off by default.
+     * One branch only: its worktree, its local branch, and its remote branch
+     * with `remote`. `HEAD` is the branch checked out at the target. Takes at
+     * most one target, no remote URL, and never the default branch.
      */
-    fetch?: boolean;
+    branch?: string | undefined;
     /**
-     * Where the caller is standing. A worktree containing it is never proposed
-     * for removal. Defaults to the process's cwd.
+     * Where the caller is standing: the base for relative targets, the target
+     * when none is given, and a worktree that is never offered for removal.
+     * Defaults to the process's cwd.
      */
-    cwd?: string;
+    cwd?: string | undefined;
+    /** Where remote URL targets' clones are kept. Defaults to {@link defaultCacheDir}. */
+    cacheDir?: string | undefined;
+    /** A host's re-ranking of each repository's rows. */
+    annotate?: Annotate | undefined;
+    /** Told before each step, and before each row of a step that walks many. For a status line. */
+    onProgress?: ((progress: SweepProgress) => void) | undefined;
+    /** Told, mid-walk, that a target directory is enormous. Defaults to stderr. */
+    onWarn?: ((message: string) => void) | undefined;
+}
+/**
+ * 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 declare function sweptWith(targets: readonly string[], opts: Omit<SweepOptions, Exclude<keyof Runners, 'git'> | 'annotate' | 'onProgress' | 'onWarn' | 'cacheDir'>): SweptWith & {
+    urls: boolean;
+};
+/**
+ * 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 declare function sweep(targets: readonly string[], opts?: SweepOptions): Sweep;
+/** What {@link sweepRepo} takes: a sweep's options, already resolved. */
+interface RepoSweepOptions extends Runners {
+    only: readonly Kind[];
+    against?: string | undefined;
+    provider: ProviderChoice;
+    fetch: boolean;
     /**
-     * Inventory one branch only: the worktree holding it, its local branch and
-     * 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, or when `scope` leaves
-     * worktrees out.
+     * Read remote tips with `ls-remote` even without a fetch: `clean`'s
+     * re-check, which must not delete on the strength of a stale tracking ref.
+     * Without a fetch, a failed `ls-remote` then fails the repository rather
+     * than fall back to those refs.
      */
+    liveRemoteTips?: boolean | undefined;
     branch?: string | undefined;
-    /** Injected runners. Defaults spawn the real `git`, `gh` and `glab`. */
-    git?: CommandRunner | undefined;
-    gh?: CommandRunner | undefined;
-    glab?: CommandRunner | undefined;
-    /**
-     * Answers whether a worktree lock's owner is alive and which processes work
-     * inside a worktree. Defaults to {@link defaultProcessProbe}, one per
-     * repository, over `ps` and `lsof`.
-     */
-    probe?: ProcessProbe | undefined;
-    /** Told before each step, and before each item of a step that walks many. For a status line. */
+    /** Only the worktree at this path; for {@link inspectWorktree}. */
+    worktree?: string | undefined;
+    cwd: string;
+    annotate?: Annotate | undefined;
     onProgress?: ((progress: SweepProgress) => void) | undefined;
-    /** Where this repository sits in a run of several, for {@link onProgress}. Defaults to 1 of 1. */
     position?: {
         index: number;
         of: number;
     } | undefined;
 }
 /**
- * Inventory one repository.
+ * 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 declare function sweepRepo(path: string, opts?: SweepOptions): RepoSweep;
-export interface SweepReposOptions extends SweepOptions {
-    /** Base for a relative entry. Defaults to the process's cwd. */
-    baseDir?: string;
-    /** Told, mid-walk, that a container entry is enormous. Defaults to stderr. */
-    onWarn?: ((message: string) => void) | undefined;
-}
+export declare function sweepRepo(path: string, opts: RepoSweepOptions): RepoSweep;
 /**
- * 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.
+ * 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 declare function sweepRepos(entries: readonly string[], opts?: SweepReposOptions): SweepResult;
+export declare function holdFreedBranches(rows: Row[], branchScoped: boolean): 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.
+ * 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 declare function holdFreedBranches(items: SweepItem[], opts?: {
-    branchScoped?: boolean;
-}): SweepItem[];
+export declare function inspectWorktree(path: string, opts?: Runners & {
+    cwd?: string | undefined;
+    annotate?: Annotate | undefined;
+}): WorktreeRow;
+export {};