pr-shepherd 0.2.0 → 0.4.0

package/bin/cli/args.mjs

@@ -0,0 +1,173 @@
+/**
+ * CLI argument-parsing helpers extracted from cli.mts for testability.
+ * Note: parseCommonArgs calls loadConfig() for cache TTL defaults.
+ */
+import { parseArgs } from "node:util";
+import { loadConfig } from "../config/load.mjs";
+import { deriveVerdict } from "../commands/status.mjs";
+// Flags that consume the next argument as their value (used for PR-number
+// detection only — prevents a flag's value from being mistaken for a PR number).
+const FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--cache-ttl",
+    "--last-push-time",
+    "--ready-delay",
+    "--cooldown-seconds",
+    "--require-sha",
+    "--message",
+]);
+// ---------------------------------------------------------------------------
+// Strict integer parsing
+// ---------------------------------------------------------------------------
+export function parseIntStrict(value, flag) {
+    if (!/^-?\d+$/.test(value.trim())) {
+        throw new Error(`Invalid value for ${flag}: "${value}" is not an integer`);
+    }
+    return parseInt(value, 10);
+}
+export function parseCommonArgs(args) {
+    const config = loadConfig();
+    const { values, tokens } = parseArgs({
+        args,
+        strict: false,
+        allowPositionals: true,
+        tokens: true,
+        options: {
+            format: { type: "string" },
+            "cache-ttl": { type: "string" },
+            "no-cache": { type: "boolean" },
+        },
+    });
+    const format = (values.format ?? "text");
+    const noCache = (values["no-cache"] ?? false);
+    const cacheTtlStr = values["cache-ttl"];
+    const cacheTtlSeconds = cacheTtlStr
+        ? parseIntStrict(cacheTtlStr, "--cache-ttl")
+        : config.cache.ttlSeconds;
+    // Build the set of arg indices consumed by global flags so we can strip
+    // them from `extra`.  Subcommand-specific flags are left untouched.
+    const consumedIndices = new Set();
+    for (const tok of tokens ?? []) {
+        if (tok.kind === "option" &&
+            (tok.name === "format" || tok.name === "cache-ttl" || tok.name === "no-cache")) {
+            consumedIndices.add(tok.index);
+            // When the value is a separate arg (--flag value, not --flag=value),
+            // inlineValue is false and the value occupies tok.index + 1.
+            if ("inlineValue" in tok && tok.inlineValue === false && tok.value != null) {
+                consumedIndices.add(tok.index + 1);
+            }
+        }
+    }
+    // Find the first positional arg that looks like a PR number, skipping values
+    // that belong to flags in FLAGS_WITH_VALUES (subcommand flags included).
+    const skipForPrDetect = new Set();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (FLAGS_WITH_VALUES.has(arg)) {
+            skipForPrDetect.add(i);
+            if (i + 1 < args.length)
+                skipForPrDetect.add(i + 1);
+            i += 1;
+        }
+        else {
+            const eqIdx = arg.indexOf("=");
+            if (eqIdx > 0 && FLAGS_WITH_VALUES.has(arg.slice(0, eqIdx))) {
+                skipForPrDetect.add(i);
+            }
+        }
+    }
+    const prIndex = args.findIndex((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && /^\d+$/.test(a));
+    const prNumber = prIndex !== -1 ? parseInt(args[prIndex], 10) : undefined;
+    // Remove consumed global-flag indices (and the PR number itself) from extra.
+    if (prIndex !== -1) {
+        consumedIndices.add(prIndex);
+    }
+    const extra = args.filter((_, i) => !consumedIndices.has(i));
+    return {
+        prNumber,
+        global: { format, noCache, cacheTtlSeconds },
+        extra,
+    };
+}
+/** Get the value of a flag like `--flag value` or `--flag=value`. */
+export function getFlag(args, name) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === name && i + 1 < args.length)
+            return args[i + 1];
+        if (arg.startsWith(`${name}=`))
+            return arg.slice(name.length + 1);
+    }
+    return null;
+}
+export function hasFlag(args, name) {
+    return args.includes(name);
+}
+export function parseList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function parseStatusPrNumbers(args) {
+    const prNumbers = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (FLAGS_WITH_VALUES.has(arg)) {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        const n = parseInt(arg, 10);
+        if (Number.isFinite(n))
+            prNumbers.push(n);
+    }
+    return prNumbers;
+}
+// ---------------------------------------------------------------------------
+// Duration parsing
+// ---------------------------------------------------------------------------
+export function parseDurationToMinutes(s, defaultMinutes) {
+    const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
+    if (!m)
+        return defaultMinutes ?? loadConfig().watch.readyDelayMinutes;
+    const n = parseInt(m[1], 10);
+    const unit = m[2] ?? "m";
+    if (unit.startsWith("h"))
+        return n * 60;
+    return n;
+}
+// ---------------------------------------------------------------------------
+// Exit code mapping
+// ---------------------------------------------------------------------------
+export function statusToExitCode(status) {
+    switch (status) {
+        case "READY":
+            return 0;
+        case "IN_PROGRESS":
+            return 2;
+        case "UNRESOLVED_COMMENTS":
+            return 3;
+        default:
+            return 1;
+    }
+}
+export function iterateActionToExitCode(action) {
+    switch (action) {
+        case "fix_code":
+        case "rebase":
+            return 1;
+        case "cancel":
+            return 2;
+        case "escalate":
+            return 3;
+        default:
+            return 0;
+    }
+}
+export function deriveSimpleReady(s) {
+    return deriveVerdict(s) === "READY";
+}

package/bin/cli.mjs

@@ -0,0 +1,204 @@
+/**
+ * CLI argument parsing and subcommand dispatch for pr-shepherd.
+ *
+ * Usage:
+ *   pr-shepherd check [PR] [--format text|json] [--no-cache] [--cache-ttl N]
+ *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
+ *                            [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]
+ *                            [--last-push-time N]
+ *   pr-shepherd iterate [PR] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-time N]
+ *   pr-shepherd status PR1 [PR2 …]
+ */
+import { runCheck } from "./commands/check.mjs";
+import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
+import { runIterate } from "./commands/iterate.mjs";
+import { runStatus, formatStatusTable } from "./commands/status.mjs";
+import { getRepoInfo } from "./github/client.mjs";
+import { formatJson } from "./reporters/json.mjs";
+import { formatText } from "./reporters/text.mjs";
+import { loadConfig } from "./config/load.mjs";
+import { parseCommonArgs, getFlag, hasFlag, parseList, parseStatusPrNumbers, parseDurationToMinutes, parseIntStrict, statusToExitCode, iterateActionToExitCode, deriveSimpleReady, } from "./cli/args.mjs";
+// ---------------------------------------------------------------------------
+// Entry
+// ---------------------------------------------------------------------------
+export async function main(argv) {
+    const args = argv.slice(2); // strip node + script path
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "check":
+            await handleCheck(args.slice(1));
+            break;
+        case "resolve":
+            await handleResolve(args.slice(1));
+            break;
+        case "iterate":
+            await handleIterate(args.slice(1));
+            break;
+        case "status":
+            await handleStatus(args.slice(1));
+            break;
+        default:
+            process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
+            process.stderr.write("Usage: pr-shepherd <check|resolve|iterate|status> [options]\n");
+            process.exitCode = 1;
+            return;
+    }
+}
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+async function handleCheck(args) {
+    const { prNumber, global: globalOpts } = parseCommonArgs(args);
+    const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
+    const output = globalOpts.format === "json" ? formatJson(report) : formatText(report);
+    process.stdout.write(`${output}\n`);
+    process.exitCode = statusToExitCode(report.status);
+    return;
+}
+async function handleResolve(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
+    const minimizeCommentIds = parseList(getFlag(extra, "--minimize-comment-ids"));
+    const dismissReviewIds = parseList(getFlag(extra, "--dismiss-review-ids"));
+    const dismissMessage = getFlag(extra, "--message") ?? undefined;
+    const requireSha = getFlag(extra, "--require-sha") ?? undefined;
+    const fetchMode = hasFlag(extra, "--fetch") ||
+        (resolveThreadIds.length === 0 &&
+            minimizeCommentIds.length === 0 &&
+            dismissReviewIds.length === 0);
+    if (fetchMode) {
+        const result = await runResolveFetch({ ...globalOpts, prNumber });
+        process.stdout.write(globalOpts.format === "json"
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatFetchResult(result));
+    }
+    else {
+        const result = await runResolveMutate({
+            ...globalOpts,
+            prNumber,
+            resolveThreadIds,
+            minimizeCommentIds,
+            dismissReviewIds,
+            dismissMessage,
+            requireSha,
+        });
+        process.stdout.write(globalOpts.format === "json"
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatMutateResult(result));
+    }
+}
+async function handleIterate(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const lastPushTimeStr = getFlag(extra, "--last-push-time");
+    const lastPushTime = lastPushTimeStr
+        ? parseIntStrict(lastPushTimeStr, "--last-push-time")
+        : undefined;
+    const readyDelayStr = getFlag(extra, "--ready-delay");
+    const cfg = loadConfig();
+    const readyDelaySeconds = parseDurationToMinutes(readyDelayStr ?? "", cfg.watch.readyDelayMinutes) * 60;
+    const cooldownSecondsStr = getFlag(extra, "--cooldown-seconds");
+    const cooldownSeconds = cooldownSecondsStr
+        ? parseIntStrict(cooldownSecondsStr, "--cooldown-seconds")
+        : cfg.iterate.cooldownSeconds;
+    const noAutoRerun = hasFlag(extra, "--no-auto-rerun");
+    const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
+    const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
+    const result = await runIterate({
+        ...globalOpts,
+        prNumber,
+        lastPushTime,
+        readyDelaySeconds,
+        cooldownSeconds,
+        noAutoRerun,
+        noAutoMarkReady,
+        noAutoCancelActionable,
+    });
+    if (globalOpts.format === "json") {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatIterateResult(result)}\n`);
+    }
+    process.exitCode = iterateActionToExitCode(result.action);
+    return;
+}
+async function handleStatus(args) {
+    const { global: globalOpts } = parseCommonArgs(args);
+    const prNumbers = parseStatusPrNumbers(args);
+    if (prNumbers.length === 0) {
+        process.stderr.write("Usage: pr-shepherd status PR1 [PR2 …]\n");
+        process.exitCode = 1;
+        return;
+    }
+    const repo = await getRepoInfo();
+    const summaries = await runStatus({ ...globalOpts, prNumbers });
+    const output = globalOpts.format === "json"
+        ? JSON.stringify(summaries, null, 2)
+        : formatStatusTable(summaries, `${repo.owner}/${repo.name}`);
+    process.stdout.write(`${output}\n`);
+    const allReady = summaries.every((s) => deriveSimpleReady(s));
+    process.exitCode = allReady ? 0 : 1;
+    return;
+}
+// ---------------------------------------------------------------------------
+// Output formatters
+// ---------------------------------------------------------------------------
+function formatFetchResult(result) {
+    const lines = [];
+    if (result.actionableThreads.length > 0) {
+        lines.push(`\nActionable Review Threads (${result.actionableThreads.length}):`);
+        for (const t of result.actionableThreads) {
+            lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author}): ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+        }
+    }
+    if (result.actionableComments.length > 0) {
+        lines.push(`\nActionable PR Comments (${result.actionableComments.length}):`);
+        for (const c of result.actionableComments) {
+            lines.push(`  - commentId=${c.id} (@${c.author}): ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+        }
+    }
+    if (result.changesRequestedReviews.length > 0) {
+        lines.push(`\nPending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length}):`);
+        for (const r of result.changesRequestedReviews) {
+            lines.push(`  - reviewId=${r.id} (@${r.author})`);
+        }
+    }
+    const total = result.actionableThreads.length +
+        result.actionableComments.length +
+        result.changesRequestedReviews.length;
+    lines.push(`\nSummary: ${total === 0 ? "0 actionable — all threads resolved/minimized" : `${total} actionable item(s)`}`);
+    return `${lines.join("\n")}\n`;
+}
+function formatMutateResult(result) {
+    const lines = [];
+    if (result.resolvedThreads.length)
+        lines.push(`Resolved threads (${result.resolvedThreads.length}): ${result.resolvedThreads.join(", ")}`);
+    if (result.minimizedComments.length)
+        lines.push(`Minimized comments (${result.minimizedComments.length}): ${result.minimizedComments.join(", ")}`);
+    if (result.dismissedReviews.length)
+        lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
+    if (result.errors.length)
+        lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
+    return `${lines.join("\n")}\n`;
+}
+function formatIterateResult(result) {
+    const base = `PR #${result.pr} [${result.action.toUpperCase()}] status=${result.status} merge=${result.mergeStateStatus}`;
+    switch (result.action) {
+        case "cooldown":
+            return `${base} (cooldown: CI still starting)`;
+        case "wait":
+            return `${base} (${result.remainingSeconds}s until cancel)`;
+        case "cancel":
+            return `${base} (ready-delay elapsed)`;
+        case "fix_code":
+            return `${base} threads=${result.fix.threads.length} comments=${result.fix.comments.length} checks=${result.fix.checks.length} cancelled=${result.cancelled.length}`;
+        case "rerun_ci":
+            return `${base} reran=${result.reran.join(",")}`;
+        case "rebase":
+            return `${base} (branch is behind main)`;
+        case "mark_ready":
+            return `${base} markedReady=${result.markedReady}`;
+        case "escalate":
+            return `${base} triggers=${result.escalate.triggers.join(",")} — ${result.escalate.suggestion}`;
+    }
+}

package/bin/commands/check.mjs

@@ -0,0 +1,140 @@
+/**
+ * `shepherd check [PR]`
+ *
+ * Read-only snapshot of PR status. Fetches CI + comments + merge status in
+ * one GraphQL request, applies all classifiers, and returns a ShepherdReport.
+ *
+ * Exit codes:
+ *   0  READY — all checks passed, no unresolved threads, CLEAN merge status.
+ *   1  FAILING — one or more CI checks failed.
+ *   2  IN_PROGRESS — CI checks still running.
+ *   3  UNRESOLVED_COMMENTS — CI ok but actionable threads remain.
+ *   1  (also) BLOCKED/CONFLICTS/UNKNOWN merge status.
+ */
+import { fetchPrBatch } from "../github/batch.mjs";
+import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
+import { cacheGet, cacheSet } from "../cache/file-cache.mjs";
+import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
+import { triageFailingChecks } from "../checks/triage.mjs";
+import { getOutdatedThreads } from "../comments/outdated.mjs";
+import { autoResolveOutdated } from "../comments/resolve.mjs";
+import { deriveMergeStatus } from "../merge-status/derive.mjs";
+export async function runCheck(opts) {
+    const repo = await getRepoInfo();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    }
+    const cacheKey = { owner: repo.owner, repo: repo.name, pr: prNumber, shape: "check" };
+    // When autoResolve is enabled the command will mutate (resolve threads, minimize
+    // comments) — always bypass cache so we act on fresh data, not a stale snapshot.
+    const cacheOpts = {
+        disabled: opts.noCache || opts.autoResolve,
+        ttlSeconds: opts.cacheTtlSeconds,
+    };
+    // Try cache first.
+    let batchData = await cacheGet(cacheKey, cacheOpts);
+    if (batchData === null) {
+        const result = await fetchPrBatch(prNumber, repo);
+        batchData = result.data;
+        // Don't cache UNKNOWN merge state — it's transient and would poison the
+        // cache for the full TTL window, causing stale UNKNOWN on the next sweep.
+        if (batchData.mergeable !== "UNKNOWN" && batchData.mergeStateStatus !== "UNKNOWN") {
+            await cacheSet(cacheKey, batchData, cacheOpts);
+        }
+    }
+    // GraphQL sometimes returns UNKNOWN for mergeable/mergeStateStatus while the
+    // REST API already has the correct value. Fall back to REST in that case.
+    // Skip for non-OPEN PRs — REST also returns UNKNOWN for merged/closed PRs.
+    if ((batchData.state ?? "OPEN") === "OPEN" &&
+        (batchData.mergeable === "UNKNOWN" || batchData.mergeStateStatus === "UNKNOWN")) {
+        const restState = await getMergeableState(prNumber, repo.owner, repo.name);
+        batchData = { ...batchData, ...restState };
+    }
+    // Classify checks.
+    const classifiedChecks = classifyChecks(batchData.checks);
+    const verdict = getCiVerdict(classifiedChecks);
+    const passing = classifiedChecks.filter((c) => c.category === "passed");
+    const failing = classifiedChecks.filter((c) => c.category === "failing");
+    const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
+    const skipped = classifiedChecks.filter((c) => c.category === "skipped");
+    const filtered = classifiedChecks.filter((c) => c.category === "filtered");
+    // Triage failures (fetch logs) — skipped when caller will short-circuit before needing failureKind.
+    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing) : failing;
+    // Resolve threads and comments.
+    const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved);
+    const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
+    // Auto-resolve outdated threads.
+    const outdated = getOutdatedThreads(unresolvedThreads);
+    let autoResolved = [];
+    let autoResolveErrors = [];
+    if (opts.autoResolve && outdated.length > 0) {
+        const { resolved: resolvedIds, errors } = await autoResolveOutdated(outdated.map((t) => t.id));
+        autoResolved = outdated.filter((t) => resolvedIds.includes(t.id));
+        autoResolveErrors = errors;
+    }
+    const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
+    // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
+    const actionableThreads = activeThreads;
+    const actionableComments = visibleComments;
+    // Derive merge status.
+    const mergeStatus = deriveMergeStatus(batchData);
+    // Derive blockedByFilteredCheck ghost state.
+    const blockedByFilteredCheck = mergeStatus.status === "BLOCKED" &&
+        !verdict.anyFailing &&
+        !verdict.anyInProgress &&
+        verdict.filteredNames.length > 0;
+    // Compute overall status.
+    const status = computeStatus(verdict, actionableThreads.length, actionableComments.length, mergeStatus.status, batchData.changesRequestedReviews.length);
+    return {
+        pr: prNumber,
+        repo: `${repo.owner}/${repo.name}`,
+        status,
+        mergeStatus,
+        checks: {
+            passing,
+            failing: triaged,
+            inProgress: inProgress,
+            skipped,
+            filtered,
+            filteredNames: verdict.filteredNames,
+            blockedByFilteredCheck,
+        },
+        threads: {
+            actionable: actionableThreads,
+            autoResolved,
+            autoResolveErrors,
+        },
+        comments: {
+            actionable: actionableComments,
+        },
+        changesRequestedReviews: batchData.changesRequestedReviews,
+        lastPushTime: opts.lastPushTime,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews) {
+    // Merge conflicts are always terminal regardless of CI state.
+    if (mergeStatus === "CONFLICTS")
+        return "FAILING";
+    // Check CI state before merge-blocking states: BLOCKED/UNSTABLE/BEHIND are
+    // often caused by CI not having passed yet, so they shouldn't mask IN_PROGRESS.
+    if (verdict.anyFailing)
+        return "FAILING";
+    if (verdict.anyInProgress)
+        return "IN_PROGRESS";
+    if (mergeStatus === "BLOCKED" || mergeStatus === "UNSTABLE" || mergeStatus === "BEHIND")
+        return "FAILING";
+    if (mergeStatus === "UNKNOWN")
+        return "UNKNOWN";
+    if (changesRequestedReviews > 0)
+        return "UNRESOLVED_COMMENTS";
+    if (unresolvedThreads > 0 || unresolvedComments > 0)
+        return "UNRESOLVED_COMMENTS";
+    // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
+    if ((mergeStatus === "CLEAN" || mergeStatus === "DRAFT") && verdict.allPassed)
+        return "READY";
+    return "UNKNOWN";
+}