@osdlc/repo-cleaner 0.11.0 → 0.14.0

package/dist/providers/gitlab.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Merge requests from GitLab, through `glab api`.
+ *
+ * The REST listing, not `glab mr list`: it carries the source and target
+ * project ids, which is how a fork's merge request is told apart, and it takes
+ * an explicit host and project, so a checkout with several remotes is read
+ * against the one the sweep measures.
+ */
+import { type CommandRunner } from '@osdlc/command-seam';
+import type { PRInfo } from '../types.ts';
+import type { PrProvider } from './types.ts';
+/** The fields of a merge request this reads. */
+interface MergeRequest {
+    iid: number;
+    state: string;
+    source_branch: string;
+    target_branch: string;
+    sha?: string | null;
+    merged_at?: string | null;
+    web_url?: string;
+    title?: string;
+    source_project_id: number;
+    target_project_id: number;
+}
+/** 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.
+ */
+export declare function gitlabProvider(glab: CommandRunner): PrProvider;
+export {};

package/dist/providers/gitlab.js

@@ -0,0 +1,117 @@
+/**
+ * Merge requests from GitLab, through `glab api`.
+ *
+ * The REST listing, not `glab mr list`: it carries the source and target
+ * project ids, which is how a fork's merge request is told apart, and it takes
+ * 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 { 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. */
+const STATE = {
+    opened: 'OPEN',
+    locked: 'OPEN',
+    merged: 'MERGED',
+    closed: 'CLOSED',
+};
+/** Absent, or of the given type (null counting where `nullable`). */
+function optional(value, type, nullable = false) {
+    return value === undefined || (nullable && value === null) || typeof value === type;
+}
+function isMergeRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const mr = value;
+    return (optional(mr['sha'], 'string', true) &&
+        optional(mr['merged_at'], 'string', true) &&
+        optional(mr['web_url'], 'string') &&
+        optional(mr['title'], 'string') &&
+        typeof mr['iid'] === 'number' &&
+        typeof mr['state'] === 'string' &&
+        typeof mr['source_branch'] === 'string' &&
+        typeof mr['target_branch'] === 'string' &&
+        typeof mr['source_project_id'] === 'number' &&
+        typeof mr['target_project_id'] === 'number');
+}
+/** One merge request as a {@link PRInfo}, or null for a fork's or an unknown state's. */
+export function mergeRequestToPr(mr) {
+    // A fork's source branch is not this repository's branch, whatever its name.
+    if (mr.source_project_id !== mr.target_project_id)
+        return null;
+    const state = STATE[mr.state];
+    if (state === undefined || mr.source_branch === '')
+        return null;
+    return {
+        number: mr.iid,
+        state,
+        mergedAt: mr.merged_at ?? null,
+        headRef: mr.source_branch,
+        headOid: typeof mr.sha === 'string' && mr.sha !== '' ? mr.sha : null,
+        baseRef: mr.target_branch,
+        title: mr.title ?? '',
+        url: mr.web_url ?? '',
+    };
+}
+/** Exited 0 with all its output captured. */
+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.
+ */
+export function gitlabProvider(glab) {
+    const run = (root, argv) => glab.run(argv, { cwd: root });
+    const hostArgs = (host) => (host === null ? [] : ['--hostname', host]);
+    return {
+        name: 'gitlab',
+        words: { tool: 'glab', noun: 'merge request', listing: 'glab api' },
+        probe(root, target) {
+            const available = succeeded(run(root, ['--version']));
+            const authenticated = available && succeeded(run(root, ['auth', 'status', ...hostArgs(target.host)]));
+            return { available, authenticated };
+        },
+        listPrs(root, target, branch) {
+            if (target.project === null)
+                return null;
+            const project = encodeURIComponent(target.project);
+            const prs = [];
+            for (let page = 1; (page - 1) * PER_PAGE < PR_LIMIT; page++) {
+                const query = new URLSearchParams({
+                    state: 'all',
+                    per_page: String(PER_PAGE),
+                    page: String(page),
+                    order_by: 'updated_at',
+                    sort: 'desc',
+                });
+                if (branch !== undefined)
+                    query.set('source_branch', branch);
+                const result = run(root, [
+                    'api',
+                    ...hostArgs(target.host),
+                    `projects/${project}/merge_requests?${query.toString()}`,
+                ]);
+                // A failed, cut-short or unreadable page fails the listing: a missing
+                // open MR would read as no MR.
+                if (!succeeded(result))
+                    return null;
+                const listed = parseJsonResult(result);
+                if (!listed.ok || !Array.isArray(listed.value))
+                    return null;
+                const rows = listed.value;
+                for (const row of rows) {
+                    if (!isMergeRequest(row))
+                        continue;
+                    const pr = mergeRequestToPr(row);
+                    if (pr !== null)
+                        prs.push(pr);
+                }
+                if (rows.length < PER_PAGE)
+                    break;
+            }
+            return prs;
+        },
+    };
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Choosing a provider for a repository, from the caller's choice and the
+ * remote's host.
+ */
+import { type CommandRunner } from '@osdlc/command-seam';
+import type { Gh } from '@osdlc/typed-gh';
+import type { ForgeTarget, PrProvider, ProviderChoice, ProviderName, ProviderStatus } from './types.ts';
+export { githubProvider } from './github.ts';
+export { gitlabProvider } from './gitlab.ts';
+export * from './types.ts';
+/** Every known provider, over the given clients. `glab` defaults to the real binary. */
+export declare function providers(clients: {
+    gh: Gh;
+    glab?: CommandRunner | undefined;
+}): Record<ProviderName, PrProvider>;
+/**
+ * The host and full project path a remote URL names, groups kept
+ * (`gitlab.com:group/sub/name.git` is project `group/sub/name`). A local path
+ * or a `file:` URL names no forge.
+ */
+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.
+ */
+export declare function chooseProvider(choice: ProviderChoice, target: ForgeTarget): ProviderName | null;
+/** The chosen provider for a repository, probed; null for none. */
+export declare function probeProvider(choice: ProviderChoice, root: string, target: ForgeTarget, all: Record<ProviderName, PrProvider>): ProviderStatus | null;

package/dist/providers/index.js

@@ -0,0 +1,63 @@
+/**
+ * Choosing a provider for a repository, from the caller's choice and the
+ * remote's host.
+ */
+import { resolveRunner } from '@osdlc/command-seam';
+import { githubProvider } from "./github.js";
+import { gitlabProvider } from "./gitlab.js";
+export { githubProvider } from "./github.js";
+export { gitlabProvider } from "./gitlab.js";
+export * from "./types.js";
+/** Every known provider, over the given clients. `glab` defaults to the real binary. */
+export function providers(clients) {
+    return {
+        github: githubProvider(clients.gh),
+        gitlab: gitlabProvider(resolveRunner('glab', clients.glab)),
+    };
+}
+const NO_TARGET = { host: null, project: null };
+/**
+ * The host and full project path a remote URL names, groups kept
+ * (`gitlab.com:group/sub/name.git` is project `group/sub/name`). A local path
+ * or a `file:` URL names no forge.
+ */
+export function forgeTarget(url) {
+    if (url === null)
+        return NO_TARGET;
+    const trimmed = url.trim();
+    if (/^file:/i.test(trimmed))
+        return NO_TARGET;
+    // scp form, user optional (`host:path` is valid git). A one-letter host is a
+    // Windows drive (`C:/repo`), which git reads as a local path.
+    const scp = /^(?:[\w.-]+@)?([^:/\\]{2,}):(?!\/\/)(.+)$/.exec(trimmed);
+    const uri = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+)$/i.exec(trimmed);
+    const match = uri ?? scp;
+    if (match === null)
+        return NO_TARGET;
+    const path = match[2].replace(/^\/+|\/+$/g, '').replace(/\.git$/, '');
+    const parts = path.split('/').filter((p) => p !== '');
+    if (parts.length < 2)
+        return { host: match[1].toLowerCase(), project: null };
+    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.
+ */
+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';
+}
+/** The chosen provider for a repository, probed; null for none. */
+export function probeProvider(choice, root, target, all) {
+    const name = chooseProvider(choice, target);
+    if (name === null)
+        return null;
+    const provider = all[name];
+    return { name, ...provider.words, ...target, ...provider.probe(root, target) };
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where pull request evidence comes from. A provider answers two questions
+ * for a repository: can its CLI be asked at all, and which pull (or merge)
+ * requests exist. Classification reads {@link PRInfo} and never knows which
+ * provider answered.
+ */
+import type { PRInfo } from '../types.ts';
+/** The providers this build knows. */
+export declare const PROVIDER_NAMES: readonly ["github", "gitlab"];
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+/** What a caller may ask for: one provider, none, or the one the remote's host suggests. */
+export declare const PROVIDER_CHOICES: readonly ["auto", "github", "gitlab", "none"];
+export type ProviderChoice = (typeof PROVIDER_CHOICES)[number];
+/** The forge a remote points at, read off its URL. */
+export interface ForgeTarget {
+    /** The host, lower-cased, without a port; null when the remote names none. */
+    host: string | null;
+    /** The full project path, groups included (`group/sub/name`); null when there is none. */
+    project: string | null;
+}
+/** How a report names a provider's requests and the lookup that lists them. */
+export interface ProviderWords {
+    /** The CLI the provider runs: `gh`, `glab`. */
+    tool: string;
+    /** What the forge calls one request: `PR`, `merge request`. */
+    noun: string;
+    /** The command that lists them, as a report quotes it: `gh pr list`. */
+    listing: string;
+}
+/** The provider chosen for a repository, and what its probe found. */
+export interface ProviderStatus extends ForgeTarget, ProviderWords {
+    name: ProviderName;
+    /** The CLI is installed. */
+    available: boolean;
+    /** The CLI has credentials for `host`. */
+    authenticated: boolean;
+}
+/** One source of pull request evidence. */
+export interface PrProvider {
+    readonly name: ProviderName;
+    readonly words: ProviderWords;
+    /** Whether the CLI is installed and signed in for `target`'s host. */
+    probe(root: string, target: ForgeTarget): {
+        available: boolean;
+        authenticated: boolean;
+    };
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    listPrs(root: string, target: ForgeTarget, branch?: string): PRInfo[] | null;
+}

package/dist/providers/types.js

@@ -0,0 +1,10 @@
+/**
+ * Where pull request evidence comes from. A provider answers two questions
+ * for a repository: can its CLI be asked at all, and which pull (or merge)
+ * requests exist. Classification reads {@link PRInfo} and never knows which
+ * provider answered.
+ */
+/** The providers this build knows. */
+export const PROVIDER_NAMES = ['github', 'gitlab'];
+/** What a caller may ask for: one provider, none, or the one the remote's host suggests. */
+export const PROVIDER_CHOICES = ['auto', ...PROVIDER_NAMES, 'none'];

package/dist/prs.d.ts

@@ -1,26 +1,30 @@
 /**
  * The pull requests of a repository, indexed by head branch.
  *
- * One `gh pr list` per repository, not one query per branch: a repository with
+ * One listing per repository, not one query per branch: a repository with
  * sixty branches would otherwise pay sixty round trips to answer a question
- * one listing covers.
+ * one listing covers. Which forge answers is the provider's business; see
+ * `providers/`.
  */
-import type { Gh } from '@osdlc/typed-gh';
+import type { PrProvider } from './providers/index.ts';
 import type { PRInfo, RepoInfo } from './types.ts';
 /**
  * Every same-repository pull request, keyed by head branch. Fork PRs are
- * dropped: a fork branch that shares a name proves nothing about ours.
+ * 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 `gh` is missing, unauthenticated or
- * failing. Classification degrades to git evidence and the report says so.
+ * 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.
  *
- * @param headPrefix Ask `gh` only for PRs whose head starts with this; the map is
- *   still keyed by exact head. typed-gh's `head` is exact, so the prefix goes
- *   through gh's `head:` search, which matches by prefix, and is checked again here.
+ * @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, gh: Gh, headPrefix?: string): Map<string, PRInfo>;
+export declare function fetchPrs(repo: RepoInfo, provider: PrProvider, branch?: string): Map<string, PRInfo>;

package/dist/prs.js

@@ -1,72 +1,48 @@
 /**
  * The pull requests of a repository, indexed by head branch.
  *
- * One `gh pr list` per repository, not one query per branch: a repository with
+ * One listing per repository, not one query per branch: a repository with
  * sixty branches would otherwise pay sixty round trips to answer a question
- * one listing covers.
+ * one listing covers. Which forge answers is the provider's business; see
+ * `providers/`.
  */
-/** The fields classification consults. Asking for more costs latency. */
-const FIELDS = [
-    'number',
-    'state',
-    'mergedAt',
-    'headRefName',
-    'headRefOid',
-    'baseRefName',
-    'isCrossRepository',
-    'title',
-    'url',
-];
-const LIMIT = 300;
 /** 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: a fork branch that shares a name proves nothing about ours.
+ * 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 `gh` is missing, unauthenticated or
- * failing. Classification degrades to git evidence and the report says so.
+ * 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.
  *
- * @param headPrefix Ask `gh` only for PRs whose head starts with this; the map is
- *   still keyed by exact head. typed-gh's `head` is exact, so the prefix goes
- *   through gh's `head:` search, which matches by prefix, and is checked again here.
+ * @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, gh, headPrefix) {
+export function fetchPrs(repo, provider, branch) {
     const byHead = new Map();
-    if (!(repo.hasGh && repo.ghAuthenticated))
+    const status = repo.provider;
+    if (status === null || status.name !== provider.name || !status.authenticated)
         return byHead;
-    const rows = gh.at(repo.root).prList({
-        state: 'all',
-        limit: LIMIT,
-        fields: FIELDS,
-        search: headPrefix === undefined ? undefined : `head:${headPrefix}`,
-    });
+    const rows = provider.listPrs(repo.root, status, branch);
     if (rows === null)
         return byHead;
-    for (const row of rows.rows) {
-        const head = row.headRefName;
-        // A fork's head branch is not this repository's branch, whatever its name.
-        if (!head || row.isCrossRepository)
+    for (const info of rows) {
+        const head = info.headRef;
+        if (!head)
             continue;
-        if (headPrefix !== undefined && !head.startsWith(headPrefix))
+        if (branch !== undefined && head !== branch)
             continue;
-        const info = {
-            number: row.number,
-            state: row.state,
-            mergedAt: row.mergedAt,
-            headRef: head,
-            headOid: row.headRefOid,
-            baseRef: row.baseRefName,
-            title: row.title,
-            url: row.url,
-        };
         const existing = byHead.get(head);
         if (existing === undefined) {
             byHead.set(head, info);

package/dist/receipt.d.ts

@@ -26,6 +26,7 @@ export declare const DroppedSchema: z.ZodObject<{
         "facts-changed": "facts-changed";
         "not-authorized": "not-authorized";
         duplicate: "duplicate";
+        kept: "kept";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
@@ -41,6 +42,7 @@ export declare const StepSchema: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strip>>;
     action: z.ZodEnum<{
+        "verify-remote": "verify-remote";
         "unlock-worktree": "unlock-worktree";
         "remove-worktree": "remove-worktree";
         "delete-local": "delete-local";
@@ -85,6 +87,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             "facts-changed": "facts-changed";
             "not-authorized": "not-authorized";
             duplicate: "duplicate";
+            kept: "kept";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
@@ -99,6 +102,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             id: z.ZodString;
         }, z.core.$strip>>;
         action: z.ZodEnum<{
+            "verify-remote": "verify-remote";
             "unlock-worktree": "unlock-worktree";
             "remove-worktree": "remove-worktree";
             "delete-local": "delete-local";

package/dist/receipt.js

@@ -13,6 +13,7 @@ export const DroppedSchema = RowRefSchema.extend({
         'facts-changed',
         'not-authorized',
         'duplicate',
+        'kept',
     ]),
     detail: z.string(),
 });
@@ -21,6 +22,7 @@ export const StepSchema = z.object({
     /** Null for the closing prune, which belongs to no row. */
     row: RowRefSchema.nullable(),
     action: z.enum([
+        'verify-remote',
         'unlock-worktree',
         'remove-worktree',
         'delete-local',

package/dist/render.d.ts

@@ -6,8 +6,31 @@
  * find. JSON carries everything the text report elides, including the facts
  * behind every verdict.
  */
-import type { Receipt } from './receipt.ts';
+import type { Receipt, Step } from './receipt.ts';
 import { type RepoSweep, type SweepItem, type SweepResult } 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
+ * color.
+ */
+export interface Style {
+    /** What a run deletes. */
+    delete(text: string): string;
+    /** A stale link a run prunes. */
+    prune(text: string): string;
+    /** What a person has to look at: a review row, a dropped row. */
+    review(text: string): string;
+    /** What stays, or a step that succeeded. */
+    keep(text: string): string;
+    /** Detail under a row: commands, the receipt path. */
+    muted(text: string): string;
+    /** A heading or the line a person is asked to approve. */
+    strong(text: string): string;
+}
+/** No color. */
+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.
@@ -16,6 +39,7 @@ export declare function requiresNote(item: Pick<SweepItem, 'requires' | 'facts'>
 /** One repository's rows, indented under its header. */
 export declare function renderRepo(sweep: RepoSweep, opts?: {
     keep?: boolean;
+    style?: Style;
 }): string;
 /**
  * What the search cost, or null when nothing was searched — every entry
@@ -27,19 +51,20 @@ export declare function renderRepo(sweep: RepoSweep, opts?: {
  */
 export declare function renderScan(result: SweepResult): string | null;
 /** The one-line verdict a person reads first, and often only. */
-export declare function renderSummary(result: SweepResult): string;
+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): string;
+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;
+    style?: Style;
 }): string;
 /**
  * The whole run as JSON, facts included. `extra` adds top-level keys, such as
@@ -71,5 +96,23 @@ export declare function summarizeReceipt(receipt: Receipt): ApplySummary;
 export declare function rowsActedOn(summary: ApplySummary): number;
 /** The closing lines of an apply run: what it deleted, dropped and could not finish. */
 export declare function renderApplySummary(receipt: Receipt): 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.
+ */
+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;
+/**
+ * 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.
+ */
+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. */
-export declare function renderReceipt(receipt: Receipt, receiptPath: string | null): string;
+export declare function renderReceipt(receipt: Receipt, receiptPath: string | null, style?: Style, opts?: {
+    steps?: boolean;
+}): string;