@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/clean.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Cleaning up: `check` a plan against an approval, then `run` what it shows.
+ *
+ * `check` resolves the approval (the rows picked, the rows spared, the risks
+ * allowed), refuses one that contradicts itself, sweeps every plan repository
+ * again and drops each selected row that is gone, cannot be deleted, moved
+ * since the plan, or carries a risk not allowed. It returns the steps a run
+ * would take. `run` sweeps once more and takes those steps in a fixed order,
+ * stopping at the first failure:
+ *
+ * 1. spared remote branches, each tip checked with `ls-remote`;
+ * 2. worktrees, each unlocked first when its lock's owner is dead, and each
+ *    checked again for live processes just before it is unlocked or removed;
+ *    one with submodules is removed with `--force` after its files and every
+ *    submodule are checked again;
+ * 3. local branches;
+ * 4. remote branches.
+ *
+ * A worktree whose directory is gone goes by its own record. One left without
+ * its `.git` takes the repository-wide prune, last, and only while that prune
+ * would drop nothing the run does not select.
+ *
+ * Branch deletes are compare-and-swap on the planned sha. Every step is
+ * verified, and the receipt is rewritten after each.
+ */
+import type { Annotate } from './hooks.ts';
+import { type Plan } from './plan.ts';
+import { type Dropped, type Receipt, type Step } from './receipt.ts';
+import { type Runners } from './sweep.ts';
+import { type Kind, type Risk, type RowId, type Sweep, type SweepProgress, type SweptWith, type RepoNote } from './types.ts';
+/** A risk allowed for every row (`row` absent), or for one row. */
+export interface Allow {
+    risk: Risk;
+    /** A row id or bare name, resolved as a pick is. */
+    row?: string | undefined;
+}
+/**
+ * What a person approved. Rows are named by id (`branch:feat/x`), or by a
+ * bare name or path when only one plan row has it.
+ *
+ *   `pick`   work on exactly these rows; a `review` row, or a `keep` row with
+ *            an action, runs only when picked. Default: every `delete` row.
+ *   `spare`  leave these rows alone; a spared remote branch is still checked,
+ *            and the run stops if it moved or is gone since the plan.
+ *   `allow`  the risks a row's action may carry.
+ */
+export interface Approval {
+    pick?: readonly string[] | undefined;
+    spare?: readonly string[] | undefined;
+    allow?: readonly (Risk | Allow)[] | undefined;
+}
+/** A row reference resolved to one plan row. */
+export interface Resolved {
+    repo: string;
+    id: RowId;
+}
+/** An approval with every row resolved to its plan row. */
+export interface ResolvedApproval {
+    pick: Resolved[];
+    spare: Resolved[];
+    allow: {
+        risk: Risk;
+        row: Resolved | null;
+    }[];
+}
+interface Shared extends Runners {
+    /** Where the caller stands: the base for relative worktree paths, and a worktree never removed. Defaults to the process's cwd. */
+    cwd?: string | undefined;
+    /** A host's re-ranking, applied to every re-sweep as the sweep applied it. */
+    annotate?: Annotate | undefined;
+    /** Told what the re-sweep is doing, for a status line. */
+    onProgress?: ((progress: SweepProgress) => void) | undefined;
+}
+export interface CheckOptions extends Shared {
+    /**
+     * A sweep made just now, used as the re-check instead of sweeping again: for
+     * a preview straight after a sweep. A repository whose remote rows it read
+     * from disk (offline) is swept again, asking the remote. `run` always sweeps
+     * again.
+     */
+    sweep?: Sweep | undefined;
+    /** Where remote URL clones are kept; a plan repository there must still push only where it fetches from. */
+    cacheDir?: string | undefined;
+}
+export interface RunOptions extends Shared {
+    /** Where the receipt is rewritten after each step; none when absent. */
+    receiptPath?: string | undefined;
+    /** Where the plan came from, recorded in the receipt. Default `(memory)`. */
+    source?: string | undefined;
+    now?: (() => Date) | undefined;
+    /** Told once the steps are known, before the first runs; each step's `result` is updated in place. */
+    onStart?: ((steps: readonly Step[]) => void) | undefined;
+    /** Told before each step: its index, the step count and the step. */
+    onStep?: ((index: number, total: number, step: Step) => void) | undefined;
+    /** Told after each step, with its `result` set, before the receipt is saved. */
+    onStepDone?: ((index: number, total: number, step: Step) => void) | undefined;
+    /**
+     * Told the run's own re-check's notes, before the first step: what it judged
+     * without. The re-check may differ from the preview's, for example when a
+     * listing fails only at the run.
+     */
+    onNotes?: ((notes: RepoNote[]) => void) | undefined;
+}
+/** What a run would do, for a person to approve: the steps, and the rows dropped and why. */
+export interface Preview {
+    plan: Plan;
+    approval: ResolvedApproval;
+    /** Each with `result: 'would-run'`. */
+    steps: Step[];
+    dropped: Dropped[];
+    /** Allowed risks no row that runs carries. Not an error: what a row carries can change between runs. */
+    unusedAllows: {
+        risk: Risk;
+        row: RowId | null;
+    }[];
+    /**
+     * `RepoSweep.notes`, with each repository's root: what the re-check judged
+     * without. With a sweep passed in (`CheckOptions.sweep`), every repository
+     * of that sweep; otherwise each plan repository the re-check swept again.
+     */
+    notes: RepoNote[];
+}
+/** A row reference as typed: a kind and a name, or a bare name (`kind: null`). */
+export interface RowRef {
+    kind: Kind | null;
+    name: string;
+}
+/**
+ * `kind:name`, or a bare name. A word before a colon that is not a kind is an
+ * error (a typo such as `wt:x`), but a path is a bare name whatever colons it
+ * holds: a prefix with a path separator in it is never a kind.
+ */
+export declare function parseRowRef(text: string): RowRef;
+/** `<risk>` for every row, or `<risk>=<row>` for one. */
+export declare function parseAllow(text: string): Allow;
+/**
+ * What can be refused of `approval` before anything is swept: a malformed
+ * row or risk, a row a sweep with `options` could never hold, and a row
+ * picked and spared as written. A row named two ways, and an `allow` for a
+ * spared or unpicked row, are found when the approval is resolved against
+ * the plan.
+ */
+export declare function checkApproval(options: Pick<SweptWith, 'only' | 'branch'>, approval: Approval): void;
+/**
+ * `approval` resolved against `plan`, or a {@link RepoCleanerError} for one
+ * that contradicts itself or names rows the plan does not have.
+ */
+export declare function resolveApproval(plan: Plan, approval: Approval, cwd: string): ResolvedApproval;
+/**
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export declare function networkRemoteKey(url: string): string | null;
+/**
+ * What running `plan` under `approval` would do now: sweeps every repository
+ * the selection is in again (or reads `opts.sweep`), and returns the steps
+ * and the rows dropped, with why. Deletes nothing.
+ *
+ * @throws RepoCleanerError for an approval that contradicts itself, names a
+ *   row the plan does not have or names one ambiguously, or spares a remote
+ *   branch that moved. A plain `Error`, naming the repository, when the
+ *   re-check cannot read one: a failed fetch, or a remote `ls-remote` cannot
+ *   reach. Nothing has been touched.
+ */
+export declare function check(plan: Plan, approval: Approval, opts?: CheckOptions): Preview;
+/**
+ * Take the steps `preview` showed: sweeps again, drops a row that moved since
+ * the preview, and runs the rest in order, compare-and-swap, verifying each
+ * step and stopping at the first failure. Only what the preview showed runs; a
+ * row it dropped stays dropped.
+ *
+ * @throws RepoCleanerError (`spared-changed`) when a spared remote branch moved
+ *   since the preview, and a plain `Error` when the re-check cannot read a
+ *   repository, as {@link check} does. Nothing has been touched.
+ */
+export declare function run(preview: Preview, opts?: RunOptions): Receipt;
+export {};