pr-shepherd 0.2.0 → 0.3.0

package/dist/cli/args.mjs

@@ -0,0 +1,153 @@
+/**
+ * CLI argument-parsing helpers extracted from cli.mts for testability.
+ * Note: parseCommonArgs calls loadConfig() for cache TTL defaults.
+ */
+import { loadConfig } from "../config/load.mjs";
+import { deriveVerdict } from "../commands/status.mjs";
+// Flags that consume the next argument as their value.
+const FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--cache-ttl",
+    "--last-push-time",
+    "--ready-delay",
+    "--cooldown-seconds",
+    "--require-sha",
+    "--message",
+]);
+export function parseCommonArgs(args) {
+    const config = loadConfig();
+    const format = (getFlag(args, "--format") ?? "text");
+    const noCache = hasFlag(args, "--no-cache");
+    const cacheTtlStr = getFlag(args, "--cache-ttl");
+    const cacheTtlSeconds = cacheTtlStr ? parseInt(cacheTtlStr, 10) : config.cache.ttlSeconds;
+    // Only global flags are stripped from `extra`; subcommand-specific flags
+    // must remain so handlers like handleIterate/handleResolve can read them.
+    const globalFlagsWithValues = new Set(["--format", "--cache-ttl"]);
+    const skipForPrDetect = new Set(); // indices to skip when finding PR number
+    const excludeFromExtra = new Set(); // indices to strip from extra (global only)
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--no-cache") {
+            skipForPrDetect.add(i);
+            excludeFromExtra.add(i);
+        }
+        else if (globalFlagsWithValues.has(arg)) {
+            skipForPrDetect.add(i);
+            excludeFromExtra.add(i);
+            if (i + 1 < args.length) {
+                skipForPrDetect.add(i + 1);
+                excludeFromExtra.add(i + 1);
+            }
+            i += 1;
+        }
+        else 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) {
+                const flagName = arg.slice(0, eqIdx);
+                if (FLAGS_WITH_VALUES.has(flagName)) {
+                    skipForPrDetect.add(i);
+                    if (globalFlagsWithValues.has(flagName))
+                        excludeFromExtra.add(i);
+                }
+            }
+        }
+    }
+    // First non-skipped positional arg that looks like a PR number.
+    const prArg = args.find((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && /^\d+$/.test(a));
+    const prNumber = prArg ? parseInt(prArg, 10) : undefined;
+    // Only strip global flags from extra — subcommand flags are passed through.
+    const extra = args.filter((_, index) => !excludeFromExtra.has(index));
+    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/dist/cli.mjs

@@ -0,0 +1,203 @@
+/**
+ * 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, 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.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
+// 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.exit(statusToExitCode(report.status));
+}
+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 ? parseInt(lastPushTimeStr, 10) : 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
+        ? parseInt(cooldownSecondsStr, 10)
+        : 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.exit(iterateActionToExitCode(result.action));
+}
+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.exit(1);
+    }
+    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.exit(allReady ? 0 : 1);
+}
+// ---------------------------------------------------------------------------
+// Output formatters
+// ---------------------------------------------------------------------------
+function formatFetchResult(result) {
+    const lines = [];
+    if (result.autoResolved.length > 0) {
+        lines.push(`Auto-resolved outdated (${result.autoResolved.length}):`);
+        for (const t of result.autoResolved) {
+            lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+        }
+    }
+    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/dist/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";
+}