@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/providers/gitlab.d.ts

@@ -25,8 +25,9 @@ interface MergeRequest {
 /** One merge request as a {@link PRInfo}, or null for a fork's or an unknown state's. */
 export declare function mergeRequestToPr(mr: MergeRequest): PRInfo | null;
 /**
- * A provider over `glab`. It needs `target.project`: without one there is
- * nothing to ask, and the listing answers null.
+ * A provider over `glab`. It needs `target.project`. A listing it cannot
+ * make or read throws with the reason: no project in the remote URL, `glab`'s
+ * own error, or a page that cannot be read.
  */
 export declare function gitlabProvider(glab: CommandRunner): PrProvider;
 export {};

package/dist/providers/gitlab.js

@@ -6,7 +6,7 @@
  * an explicit host and project, so a checkout with several remotes is read
  * against the one the sweep measures.
  */
-import { parseJsonResult, runFailed, } from '@osdlc/command-seam';
+import { parseJsonResult, runFailed, stderrOrError, } from '@osdlc/command-seam';
 import { PR_LIMIT } from "./github.js";
 const PER_PAGE = 100;
 /** GitLab's states, as the GitHub names classification reads. A locked MR is an open one mid-update. */
@@ -59,8 +59,9 @@ function succeeded(result) {
     return !runFailed(result);
 }
 /**
- * A provider over `glab`. It needs `target.project`: without one there is
- * nothing to ask, and the listing answers null.
+ * A provider over `glab`. It needs `target.project`. A listing it cannot
+ * make or read throws with the reason: no project in the remote URL, `glab`'s
+ * own error, or a page that cannot be read.
  */
 export function gitlabProvider(glab) {
     const run = (root, argv) => glab.run(argv, { cwd: root });
@@ -75,7 +76,7 @@ export function gitlabProvider(glab) {
         },
         listPrs(root, target, branch) {
             if (target.project === null)
-                return null;
+                throw new Error('the remote URL names no GitLab project');
             const project = encodeURIComponent(target.project);
             const prs = [];
             for (let page = 1; (page - 1) * PER_PAGE < PR_LIMIT; page++) {
@@ -95,11 +96,16 @@ export function gitlabProvider(glab) {
                 ]);
                 // A failed, cut-short or unreadable page fails the listing: a missing
                 // open MR would read as no MR.
-                if (!succeeded(result))
-                    return null;
+                if (!succeeded(result)) {
+                    // Not stdout: a page cut short is half a JSON listing, not a reason.
+                    throw new Error(result.outputIncomplete === true
+                        ? `page ${page} was cut short`
+                        : stderrOrError(result) || `glab exited ${String(result.exitCode)}`);
+                }
                 const listed = parseJsonResult(result);
-                if (!listed.ok || !Array.isArray(listed.value))
-                    return null;
+                if (!listed.ok || !Array.isArray(listed.value)) {
+                    throw new Error(`page ${page} is not a merge request list`);
+                }
                 const rows = listed.value;
                 for (const row of rows) {
                     if (!isMergeRequest(row))

package/dist/providers/index.d.ts

@@ -20,10 +20,11 @@ export declare function providers(clients: {
  */
 export declare function forgeTarget(url: string | null): ForgeTarget;
 /**
- * The provider `choice` names for `target`. `auto` reads the host: one with
- * `gitlab` in its name is GitLab, any other is GitHub, which is what the sweep
- * did before providers existed (`gh` answers nothing for a host it does not
- * know). `none` is no provider.
+ * The provider `choice` names for `target`. `auto` reads the host: none, for
+ * a remote that names no host (a local path or `file://`), which cannot have
+ * pull requests; one with `gitlab` in its name is GitLab; any other is
+ * GitHub, which is what the sweep did before providers existed (`gh` answers
+ * nothing for a host it does not know). `none` is no provider.
  */
 export declare function chooseProvider(choice: ProviderChoice, target: ForgeTarget): ProviderName | null;
 /** The chosen provider for a repository, probed; null for none. */

package/dist/providers/index.js

@@ -41,17 +41,20 @@ export function forgeTarget(url) {
     return { host: match[1].toLowerCase(), project: parts.join('/') };
 }
 /**
- * The provider `choice` names for `target`. `auto` reads the host: one with
- * `gitlab` in its name is GitLab, any other is GitHub, which is what the sweep
- * did before providers existed (`gh` answers nothing for a host it does not
- * know). `none` is no provider.
+ * The provider `choice` names for `target`. `auto` reads the host: none, for
+ * a remote that names no host (a local path or `file://`), which cannot have
+ * pull requests; one with `gitlab` in its name is GitLab; any other is
+ * GitHub, which is what the sweep did before providers existed (`gh` answers
+ * nothing for a host it does not know). `none` is no provider.
  */
 export function chooseProvider(choice, target) {
     if (choice === 'none')
         return null;
     if (choice !== 'auto')
         return choice;
-    return target.host !== null && target.host.includes('gitlab') ? 'gitlab' : 'github';
+    if (target.host === null)
+        return null;
+    return target.host.includes('gitlab') ? 'gitlab' : 'github';
 }
 /** The chosen provider for a repository, probed; null for none. */
 export function probeProvider(choice, root, target, all) {

package/dist/providers/types.d.ts

@@ -34,6 +34,11 @@ export interface ProviderStatus extends ForgeTarget, ProviderWords {
     available: boolean;
     /** The CLI has credentials for `host`. */
     authenticated: boolean;
+    /**
+     * Set by the sweep when the provider was asked and its listing failed: why,
+     * in the provider's words. Absent when it answered or was not asked.
+     */
+    listError?: string | undefined;
 }
 /** One source of pull request evidence. */
 export interface PrProvider {
@@ -46,8 +51,9 @@ export interface PrProvider {
     };
     /**
      * The repository's pull requests, fork PRs already dropped, in any order;
-     * null when the listing failed. A failure is not "no PRs": the caller
-     * classifies on git evidence alone.
+     * null, or a throw whose message says why, when the listing failed. A
+     * failure is not "no PRs": the caller classifies on git evidence alone and
+     * notes the failure on the repository.
      *
      * @param branch Narrow the listing to this exact head branch. The caller
      *   checks the head again, so a provider that cannot narrow may list all.

package/dist/prs.d.ts

@@ -7,24 +7,52 @@
  * `providers/`.
  */
 import type { PrProvider } from './providers/index.ts';
+import type { ProviderStatus } from './providers/types.ts';
 import type { PRInfo, RepoInfo } from './types.ts';
+/** Why the provider did not answer, and the words for it. */
+export interface PrsUnchecked {
+    kind: 'not-installed' | 'not-signed-in' | 'list-failed';
+    /** For a sentence: "`gh` is not installed", "`gh pr list` failed". */
+    why: string;
+}
 /**
- * Every same-repository pull request, keyed by head branch. Fork PRs are
- * dropped by the provider: a fork branch that shares a name proves nothing
- * about ours.
+ * Why open pull requests cannot be ruled out for this repository, or null
+ * when the provider answered. A missing or signed-out CLI was never asked, and
+ * a failed listing answered nothing; either way a remote branch with no known
+ * PR may still have an open one. Every sentence about a lookup that did not
+ * answer is built from this one answer.
+ */
+export declare function prsUnchecked(status: ProviderStatus): PrsUnchecked | null;
+/** A provider's answer for one repository: its pull requests, or why there are none to read. */
+export interface PrLookup {
+    /** Pull requests keyed by head branch; empty when the lookup failed or was not made. */
+    prs: Map<string, PRInfo>;
+    /**
+     * Why the listing failed, in the provider's own words where it gave any;
+     * null when it answered, or when it was not asked at all.
+     */
+    error: string | null;
+}
+/**
+ * Every same-repository pull request, keyed by head branch, and why there are
+ * none when the listing failed. Fork PRs are dropped by the provider: a fork
+ * branch that shares a name proves nothing about ours.
  *
  * A branch can carry several PRs over its life. The one that decides a
  * verdict is the most live: an open PR means keep whatever else happened, and
  * a merged one means the work landed. Ties go to the higher number, so two
  * runs over unchanged state agree.
  *
- * An empty map is the honest answer when the provider's CLI is missing,
- * unauthenticated or failing, or when there is no provider. Classification
- * degrades to git evidence and the report says so.
+ * The map is empty when the provider's CLI is missing or unauthenticated, when
+ * there is no provider, and when the listing fails. A provider that answers
+ * null or throws has failed (a repository the signed-in account cannot see, a
+ * forge that is down, output that cannot be read), and `error` says why.
+ * Classification then degrades to git evidence, and the sweep notes it rather
+ * than losing every row to one listing.
  *
  * @param provider The provider to ask. It is asked only when it is the one
  *   `repo.provider` names and that probe found it signed in.
  * @param branch Ask only for PRs whose head is exactly this branch; rows
  *   for any other head are dropped here too.
  */
-export declare function fetchPrs(repo: RepoInfo, provider: PrProvider, branch?: string): Map<string, PRInfo>;
+export declare function lookupPrs(repo: RepoInfo, provider: PrProvider, branch?: string): PrLookup;

package/dist/prs.js

@@ -6,37 +6,70 @@
  * one listing covers. Which forge answers is the provider's business; see
  * `providers/`.
  */
+import { errorText } from "./util.js";
+/**
+ * Why open pull requests cannot be ruled out for this repository, or null
+ * when the provider answered. A missing or signed-out CLI was never asked, and
+ * a failed listing answered nothing; either way a remote branch with no known
+ * PR may still have an open one. Every sentence about a lookup that did not
+ * answer is built from this one answer.
+ */
+export function prsUnchecked(status) {
+    if (!status.available)
+        return { kind: 'not-installed', why: `\`${status.tool}\` is not installed` };
+    if (!status.authenticated) {
+        return { kind: 'not-signed-in', why: `\`${status.tool}\` is not signed in` };
+    }
+    if (status.listError !== undefined) {
+        return { kind: 'list-failed', why: `\`${status.listing}\` failed` };
+    }
+    return null;
+}
 /** Open outranks merged outranks closed, and a newer PR outranks an older. */
 function priority(state) {
     return { OPEN: 3, MERGED: 2, CLOSED: 1 }[state] ?? 0;
 }
 /**
- * Every same-repository pull request, keyed by head branch. Fork PRs are
- * dropped by the provider: a fork branch that shares a name proves nothing
- * about ours.
+ * Every same-repository pull request, keyed by head branch, and why there are
+ * none when the listing failed. Fork PRs are dropped by the provider: a fork
+ * branch that shares a name proves nothing about ours.
  *
  * A branch can carry several PRs over its life. The one that decides a
  * verdict is the most live: an open PR means keep whatever else happened, and
  * a merged one means the work landed. Ties go to the higher number, so two
  * runs over unchanged state agree.
  *
- * An empty map is the honest answer when the provider's CLI is missing,
- * unauthenticated or failing, or when there is no provider. Classification
- * degrades to git evidence and the report says so.
+ * The map is empty when the provider's CLI is missing or unauthenticated, when
+ * there is no provider, and when the listing fails. A provider that answers
+ * null or throws has failed (a repository the signed-in account cannot see, a
+ * forge that is down, output that cannot be read), and `error` says why.
+ * Classification then degrades to git evidence, and the sweep notes it rather
+ * than losing every row to one listing.
  *
  * @param provider The provider to ask. It is asked only when it is the one
  *   `repo.provider` names and that probe found it signed in.
  * @param branch Ask only for PRs whose head is exactly this branch; rows
  *   for any other head are dropped here too.
  */
-export function fetchPrs(repo, provider, branch) {
+export function lookupPrs(repo, provider, branch) {
     const byHead = new Map();
     const status = repo.provider;
-    if (status === null || status.name !== provider.name || !status.authenticated)
-        return byHead;
-    const rows = provider.listPrs(repo.root, status, branch);
+    if (status === null || status.name !== provider.name || !status.authenticated) {
+        return { prs: byHead, error: null };
+    }
+    let rows;
+    try {
+        rows = provider.listPrs(repo.root, status, branch);
+    }
+    catch (err) {
+        // A bug in the provider is not a listing that failed: let it fail loudly,
+        // as an error on the repository, rather than gate every remote branch.
+        if (err instanceof TypeError || err instanceof ReferenceError)
+            throw err;
+        return { prs: byHead, error: errorText(err) };
+    }
     if (rows === null)
-        return byHead;
+        return { prs: byHead, error: 'the provider gave no reason' };
     for (const info of rows) {
         const head = info.headRef;
         if (!head)
@@ -54,5 +87,5 @@ export function fetchPrs(repo, provider, branch) {
             byHead.set(head, info);
         }
     }
-    return byHead;
+    return { prs: byHead, error: null };
 }

package/dist/receipt.d.ts

@@ -1,56 +1,53 @@
-/** What `applyPlan` did, step by step, rewritten after every step. */
+/** What a run did, step by step, rewritten after every step. */
 import { z } from 'zod';
 /** The receipt format's version, written into every receipt. */
-export declare const RECEIPT_VERSION = 1;
-export declare const RowRefSchema: z.ZodObject<{
-    category: z.ZodEnum<{
-        local_branch: "local_branch";
-        worktree: "worktree";
-        remote_branch: "remote_branch";
-    }>;
-    id: z.ZodString;
-}, z.core.$strip>;
-export type RowRef = z.infer<typeof RowRefSchema>;
+export declare const RECEIPT_VERSION = 2;
+/**
+ * Why a row did not run:
+ *
+ *   `gone`         no longer in the sweep
+ *   `blocked`      the sweep now finds a blocker
+ *   `keep`         the sweep keeps it for structure; it has no action
+ *   `held`         a branch whose worktree this run does not remove
+ *   `needs-pick`   not judged `delete`; it runs only when picked
+ *   `changed`      its evidence moved since the plan
+ *   `not-allowed`  it carries a risk that was not allowed
+ *   `duplicate`    another checkout of the same remote deletes the same branch
+ *   `spared`       the same remote branch is spared through another checkout
+ */
+export declare const DROP_REASONS: readonly ["gone", "blocked", "keep", "held", "needs-pick", "changed", "not-allowed", "duplicate", "spared"];
+export type DropReason = (typeof DROP_REASONS)[number];
 export declare const DroppedSchema: z.ZodObject<{
-    category: z.ZodEnum<{
-        local_branch: "local_branch";
-        worktree: "worktree";
-        remote_branch: "remote_branch";
-    }>;
-    id: z.ZodString;
     repo: z.ZodString;
+    row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
     reason: z.ZodEnum<{
+        keep: "keep";
+        blocked: "blocked";
         gone: "gone";
-        "not-deletable": "not-deletable";
-        "needs-review": "needs-review";
-        "facts-changed": "facts-changed";
-        "not-authorized": "not-authorized";
+        held: "held";
+        "needs-pick": "needs-pick";
+        changed: "changed";
+        "not-allowed": "not-allowed";
         duplicate: "duplicate";
-        kept: "kept";
+        spared: "spared";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
 export type Dropped = z.infer<typeof DroppedSchema>;
+export declare const STEP_ACTIONS: readonly ["verify-remote", "unlock-worktree", "remove-worktree", "delete-branch", "delete-remote", "prune-worktrees"];
 export declare const StepSchema: z.ZodObject<{
     repo: z.ZodString;
-    row: z.ZodNullable<z.ZodObject<{
-        category: z.ZodEnum<{
-            local_branch: "local_branch";
-            worktree: "worktree";
-            remote_branch: "remote_branch";
-        }>;
-        id: z.ZodString;
-    }, z.core.$strip>>;
+    row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
     action: z.ZodEnum<{
         "verify-remote": "verify-remote";
         "unlock-worktree": "unlock-worktree";
         "remove-worktree": "remove-worktree";
-        "delete-local": "delete-local";
+        "delete-branch": "delete-branch";
         "delete-remote": "delete-remote";
         "prune-worktrees": "prune-worktrees";
     }>;
     command: z.ZodString;
-    expected_sha: z.ZodNullable<z.ZodString>;
+    expectedSha: z.ZodNullable<z.ZodString>;
     result: z.ZodEnum<{
         pending: "pending";
         "would-run": "would-run";
@@ -59,58 +56,49 @@ export declare const StepSchema: z.ZodObject<{
     }>;
     error: z.ZodNullable<z.ZodString>;
     verification: z.ZodNullable<z.ZodString>;
+    gone: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type Step = z.infer<typeof StepSchema>;
 export declare const ReceiptSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     plan: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
         "dry-run": "dry-run";
-        applying: "applying";
+        running: "running";
         complete: "complete";
     }>;
-    started_at: z.ZodString;
-    finished_at: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodNullable<z.ZodString>;
     dropped: z.ZodArray<z.ZodObject<{
-        category: z.ZodEnum<{
-            local_branch: "local_branch";
-            worktree: "worktree";
-            remote_branch: "remote_branch";
-        }>;
-        id: z.ZodString;
         repo: z.ZodString;
+        row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
         reason: z.ZodEnum<{
+            keep: "keep";
+            blocked: "blocked";
             gone: "gone";
-            "not-deletable": "not-deletable";
-            "needs-review": "needs-review";
-            "facts-changed": "facts-changed";
-            "not-authorized": "not-authorized";
+            held: "held";
+            "needs-pick": "needs-pick";
+            changed: "changed";
+            "not-allowed": "not-allowed";
             duplicate: "duplicate";
-            kept: "kept";
+            spared: "spared";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
     steps: z.ZodArray<z.ZodObject<{
         repo: z.ZodString;
-        row: z.ZodNullable<z.ZodObject<{
-            category: z.ZodEnum<{
-                local_branch: "local_branch";
-                worktree: "worktree";
-                remote_branch: "remote_branch";
-            }>;
-            id: z.ZodString;
-        }, z.core.$strip>>;
+        row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
         action: z.ZodEnum<{
             "verify-remote": "verify-remote";
             "unlock-worktree": "unlock-worktree";
             "remove-worktree": "remove-worktree";
-            "delete-local": "delete-local";
+            "delete-branch": "delete-branch";
             "delete-remote": "delete-remote";
             "prune-worktrees": "prune-worktrees";
         }>;
         command: z.ZodString;
-        expected_sha: z.ZodNullable<z.ZodString>;
+        expectedSha: z.ZodNullable<z.ZodString>;
         result: z.ZodEnum<{
             pending: "pending";
             "would-run": "would-run";
@@ -119,6 +107,7 @@ export declare const ReceiptSchema: z.ZodObject<{
         }>;
         error: z.ZodNullable<z.ZodString>;
         verification: z.ZodNullable<z.ZodString>;
+        gone: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Receipt = z.infer<typeof ReceiptSchema>;

package/dist/receipt.js

@@ -1,46 +1,70 @@
-/** What `applyPlan` did, step by step, rewritten after every step. */
+/** What a run did, step by step, rewritten after every step. */
 import { z } from 'zod';
-import { PLAN_CATEGORIES } from "./plan.js";
+import { RowIdSchema } from "./plan.js";
 /** The receipt format's version, written into every receipt. */
-export const RECEIPT_VERSION = 1;
-export const RowRefSchema = z.object({ category: z.enum(PLAN_CATEGORIES), id: z.string() });
-export const DroppedSchema = RowRefSchema.extend({
+export const RECEIPT_VERSION = 2;
+/**
+ * Why a row did not run:
+ *
+ *   `gone`         no longer in the sweep
+ *   `blocked`      the sweep now finds a blocker
+ *   `keep`         the sweep keeps it for structure; it has no action
+ *   `held`         a branch whose worktree this run does not remove
+ *   `needs-pick`   not judged `delete`; it runs only when picked
+ *   `changed`      its evidence moved since the plan
+ *   `not-allowed`  it carries a risk that was not allowed
+ *   `duplicate`    another checkout of the same remote deletes the same branch
+ *   `spared`       the same remote branch is spared through another checkout
+ */
+export const DROP_REASONS = [
+    'gone',
+    'blocked',
+    'keep',
+    'held',
+    'needs-pick',
+    'changed',
+    'not-allowed',
+    'duplicate',
+    'spared',
+];
+export const DroppedSchema = z.object({
     repo: z.string(),
-    reason: z.enum([
-        'gone',
-        'not-deletable',
-        'needs-review',
-        'facts-changed',
-        'not-authorized',
-        'duplicate',
-        'kept',
-    ]),
+    row: RowIdSchema,
+    reason: z.enum(DROP_REASONS),
     detail: z.string(),
 });
+export const STEP_ACTIONS = [
+    'verify-remote',
+    'unlock-worktree',
+    'remove-worktree',
+    'delete-branch',
+    'delete-remote',
+    'prune-worktrees',
+];
 export const StepSchema = z.object({
     repo: z.string(),
-    /** Null for the closing prune, which belongs to no row. */
-    row: RowRefSchema.nullable(),
-    action: z.enum([
-        'verify-remote',
-        'unlock-worktree',
-        'remove-worktree',
-        'delete-local',
-        'delete-remote',
-        'prune-worktrees',
-    ]),
+    /** The row the step acts on. */
+    row: RowIdSchema,
+    action: z.enum(STEP_ACTIONS),
     command: z.string(),
-    expected_sha: z.string().nullable(),
+    expectedSha: z.string().nullable(),
     result: z.enum(['pending', 'would-run', 'ok', 'failed']),
     error: z.string().nullable(),
     verification: z.string().nullable(),
+    /**
+     * The remote no longer listed the branch when the step ran: someone deleted
+     * it after the run's re-check. A `delete-remote` step so marked deleted
+     * nothing, and the run summary counts it apart. Absent otherwise.
+     */
+    gone: z.literal(true).optional(),
 });
 export const ReceiptSchema = z.object({
     version: z.literal(RECEIPT_VERSION),
+    /** Where the plan came from: a path, `(stdin)`, or `(swept)`. */
     plan: z.string(),
-    status: z.enum(['dry-run', 'applying', 'complete', 'failed']),
-    started_at: z.string(),
-    finished_at: z.string().nullable(),
+    status: z.enum(['dry-run', 'running', 'complete', 'failed']),
+    startedAt: z.string(),
+    finishedAt: z.string().nullable(),
     dropped: z.array(DroppedSchema),
     steps: z.array(StepSchema),
 });

package/dist/reference.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+/** The extended help for each command: its own options, then the shared vocabulary. */
+export declare const REFERENCE: {
+    readonly report: string;
+    readonly plan: string;
+    readonly clean: string;
+    readonly cache: "repo-cleaner cache [list | remove <url>... | remove --all]\n  Lists or removes the clones kept for remote URL targets. A removed clone is\n  cloned again by the next sweep of its URL; a plan that names it cannot run.";
+};