@jphutchins/code-review 0.1.0-alpha.23 → 0.1.0-alpha.25

package/README.md

@@ -39,6 +39,9 @@ npx @jphutchins/code-review <subcommand>
 | --- | --- |
 | `post` | Post a complete review (inline comments + sticky summary) from findings + envelope + diff — the one-call path |
 | `gather` | Resolve the PR from the CI head SHA and gather the review inputs (diff with git-diff fallback, PR context, prior bot review, failing-job logs) into the workspace for the agent |
+| `parse-command` | Resolve a PR's head from its number and parse a ChatOps trigger comment (`/code-review [24m] [$1.00] <instructions>`) into review overrides — the on-demand comment trigger |
+| `react` | Add/remove a GitHub comment reaction — the ChatOps acknowledgement (👀 on receipt, 🚀 on completion) |
+| `await-ci` | Wait for a PR head's CI run to conclude and emit its real conclusion + run id — so an on-demand comment review routes on the CI result (success → full, failure → mechanic) instead of reviewing blind |
 | `render` | Render the sticky-comment markdown from findings + usage + prices |
 | `inline` | Build the GitHub reviews `comments[]` payload from findings + diff (in-diff validation; strays demote to the summary) |
 | `adapt` | Map a native agent-CLI result envelope onto the abstract result envelope (`src/schema.ts`) |
@@ -69,6 +72,13 @@ in [templates/](templates/). See [docs/adapters.md](docs/adapters.md) for the ad
    introducing PR won't review itself — then open a test PR.
 5. First run: consider `egress-policy: audit` to discover the real allowlist, then switch to `block`
    ([SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
+6. Optional — add on-demand reviews too: copy
+   [examples/workflows/review-on-comment.yaml](examples/workflows/review-on-comment.yaml) so a
+   write-access user can comment `/code-review [24m] [$1.00] <instructions>` on a PR to review it
+   now, with an optional per-run budget and focus. Comment before CI finishes and it waits for CI and
+   routes on the real result (success → full review, failure → mechanic), same as the CI trigger. See the
+   [ChatOps section](examples/workflows/README.md#comment--chatops-trigger-on-demand-reviews) for the
+   security model.
 
 Every model knob is committed step `env` on the workflow's triage and review steps — models,
 efforts, the subagent model, and the tier aliases, right where each is consumed — edited and

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import { readFileSync, writeFileSync, statSync, copyFileSync, readdirSync } from 'fs';
+import { randomBytes } from 'crypto';
 import { resolve as resolve$1, join, dirname, basename, extname } from 'path';
 import { Eta } from 'eta';
 import parseDiff from 'parse-diff';
@@ -8,6 +9,7 @@ import { Ajv2020 } from 'ajv/dist/2020.js';
 import _addFormats from 'ajv-formats';
 import * as t from 'io-ts';
 import { execFile } from 'child_process';
+import { PathReporter } from 'io-ts/lib/PathReporter.js';
 
 // src/cost.ts
 var defaultWarn = (message) => {
@@ -459,12 +461,12 @@ var sumTranscriptUsage = (entries) => {
     },
     { totals: /* @__PURE__ */ new Map(), turns: 0, seen: /* @__PURE__ */ new Set() }
   );
-  const models = [...summed.totals].map(([model, t4]) => ({
+  const models = [...summed.totals].map(([model, t7]) => ({
     model,
-    input_tokens: t4.input,
-    output_tokens: t4.output,
-    cache_read_tokens: t4.cacheRead,
-    cache_write_tokens: t4.cacheWrite
+    input_tokens: t7.input,
+    output_tokens: t7.output,
+    cache_read_tokens: t7.cacheRead,
+    cache_write_tokens: t7.cacheWrite
   }));
   const bounds = entries.reduce(
     (acc, entry) => {
@@ -801,7 +803,7 @@ var writesToDraft = (toolName, toolInput, draftPath) => {
   const targets = [draftPath, basename(draftPath), "$DRAFT", "${DRAFT}"];
   if (WRITE_TOOLS.has(toolName)) {
     const fp = rec?.["file_path"] ?? rec?.["notebook_path"];
-    if (typeof fp === "string" && targets.some((t4) => fp === t4 || basename(fp) === basename(t4)))
+    if (typeof fp === "string" && targets.some((t7) => fp === t7 || basename(fp) === basename(t7)))
       return true;
   }
   if (toolName === "Bash") {
@@ -897,9 +899,9 @@ var parseWallMs = (raw) => {
 };
 var parseEpochSecMs = (raw) => {
   if (raw === void 0) return null;
-  const t4 = raw.trim();
-  if (!/^\d+$/.test(t4)) return null;
-  const n = Number.parseInt(t4, 10);
+  const t7 = raw.trim();
+  if (!/^\d+$/.test(t7)) return null;
+  const n = Number.parseInt(t7, 10);
   return Number.isFinite(n) && n > 0 ? n * 1e3 : null;
 };
 var anchoredElapsedMs = (src) => {
@@ -1314,8 +1316,8 @@ var priorBotCommentIds = (raw, botLogin) => {
   const nodes = conn?.nodes;
   if (!Array.isArray(nodes)) return { ids: [], truncated };
   const logins = [botLogin.replace(/\[bot\]$/, ""), botLogin];
-  const ids = nodes.flatMap((t4) => {
-    const cnodes = t4.comments?.nodes;
+  const ids = nodes.flatMap((t7) => {
+    const cnodes = t7.comments?.nodes;
     return Array.isArray(cnodes) ? cnodes.map((c) => priorBotCommentId(c, logins)).filter((id) => id !== null) : [];
   });
   return { ids, truncated };
@@ -1579,6 +1581,238 @@ var post = async (input, ghApi = runGhApi) => {
     }
   }
 };
+var DURATION_RE = /^(\d+)(h|m|s)$/;
+var USD_RE = /^\$(\d+(?:\.\d+)?)$/;
+var toSeconds = (n, unit) => unit === "h" ? n * 3600 : unit === "m" ? n * 60 : n;
+var stripTrigger = (body, trigger) => {
+  const trimmed = body.replace(/^\s+/, "");
+  if (!trimmed.startsWith(trigger)) return null;
+  const after = trimmed.slice(trigger.length);
+  return after === "" || /^\s/.test(after) ? after : null;
+};
+var scanLeading = (s, acc) => {
+  const m = /^(\s*)(\S+)([\s\S]*)$/.exec(s);
+  if (m === null) return { ...acc, rest: "" };
+  const [, , token = "", tail = ""] = m;
+  const dm = DURATION_RE.exec(token);
+  if (dm && acc.durationSec === null)
+    return scanLeading(tail, {
+      ...acc,
+      durationSec: toSeconds(Number.parseInt(dm[1] ?? "", 10), dm[2] ?? "s")
+    });
+  const um = USD_RE.exec(token);
+  if (um && acc.usd === null)
+    return scanLeading(tail, { ...acc, usd: Number.parseFloat(um[1] ?? "") });
+  return { ...acc, rest: s };
+};
+var clampDuration = (requested, ceiling) => requested !== null && ceiling !== null && requested > ceiling ? {
+  value: ceiling,
+  notes: [
+    `requested duration ${String(requested)}s exceeds the ${String(ceiling)}s ceiling \u2014 clamped to ${String(ceiling)}s`
+  ]
+} : { value: requested, notes: [] };
+var clampUsd = (requested, ceiling) => requested !== null && ceiling !== null && requested > ceiling ? {
+  value: ceiling,
+  notes: [
+    `requested $${requested.toFixed(2)} exceeds the $${ceiling.toFixed(2)} ceiling \u2014 clamped to $${ceiling.toFixed(2)}`
+  ]
+} : { value: requested, notes: [] };
+var capInstructions = (text, maxLen) => text.length > maxLen ? {
+  value: text.slice(0, maxLen),
+  notes: [
+    `instructions truncated from ${String(text.length)} to ${String(maxLen)} characters`
+  ]
+} : { value: text, notes: [] };
+var parseCommandArgs = (body, options) => {
+  const afterTrigger = stripTrigger(body, options.trigger);
+  if (afterTrigger === null) return { kind: "not-a-command" };
+  const scan = scanLeading(afterTrigger, { durationSec: null, usd: null });
+  const duration = clampDuration(scan.durationSec, options.maxDurationSec);
+  const usd = clampUsd(scan.usd, options.maxUsd);
+  const instructions = capInstructions(scan.rest.trim(), options.maxInstructionsLen);
+  return {
+    kind: "command",
+    args: {
+      durationSec: duration.value,
+      usd: usd.value,
+      instructions: instructions.value,
+      notes: [...duration.notes, ...usd.notes, ...instructions.notes]
+    }
+  };
+};
+var PrHeadCodec = t.type({
+  head_sha: t.string,
+  head_ref: t.string,
+  head_repo: t.union([t.string, t.null]),
+  state: t.string
+});
+var resolvePrHead = async (repo, prNumber, ghApi) => {
+  const stdout = await ghApi([
+    `repos/${repo}/pulls/${String(prNumber)}`,
+    "--jq",
+    "{head_sha: .head.sha, head_ref: .head.ref, head_repo: .head.repo.full_name, state: .state}"
+  ]);
+  const decoded = PrHeadCodec.decode(JSON.parse(stdout));
+  if (decoded._tag === "Left") {
+    throw new Error(`PR head for #${String(prNumber)} did not match the expected shape`);
+  }
+  return decoded.right;
+};
+var parseCommand = async (input, ghApi = runGhApi) => {
+  const parse = parseCommandArgs(input.body, input.options);
+  if (parse.kind === "not-a-command") {
+    return {
+      kind: "skip",
+      reason: `comment does not begin with the trigger "${input.options.trigger}"`
+    };
+  }
+  const head = await resolvePrHead(input.repo, input.prNumber, ghApi).catch(
+    (err) => err instanceof Error ? err : new Error(String(err))
+  );
+  if (head instanceof Error) {
+    return {
+      kind: "skip",
+      reason: `could not resolve PR #${String(input.prNumber)}: ${head.message}`
+    };
+  }
+  if (head.state !== "open") {
+    return {
+      kind: "skip",
+      reason: `PR #${String(input.prNumber)} is not open (state: ${head.state})`
+    };
+  }
+  return {
+    kind: "run",
+    headSha: head.head_sha,
+    headBranch: head.head_ref,
+    headRepo: head.head_repo ?? input.repo,
+    args: parse.args
+  };
+};
+var safeHeredocDelim = (instructions, randomHex, attemptsLeft = 8) => {
+  const candidate = `GHOUT_${randomHex()}`;
+  if (!instructions.split("\n").includes(candidate)) return candidate;
+  if (attemptsLeft <= 0) throw new Error("could not derive a collision-free heredoc delimiter");
+  return safeHeredocDelim(instructions, randomHex, attemptsLeft - 1);
+};
+var renderCommandOutputs = (result, delim) => {
+  if (result.kind === "skip") return "should_run=false\n";
+  const { headSha, headBranch, headRepo, args } = result;
+  return `${[
+    "should_run=true",
+    `head_sha=${headSha}`,
+    `head_branch=${headBranch}`,
+    `head_repo=${headRepo}`,
+    `duration=${args.durationSec === null ? "" : `${String(args.durationSec)}s`}`,
+    `usd=${args.usd === null ? "" : args.usd.toFixed(2)}`,
+    `instructions<<${delim}`,
+    args.instructions,
+    delim
+  ].join("\n")}
+`;
+};
+var REACTIONS = [
+  "+1",
+  "-1",
+  "laugh",
+  "confused",
+  "heart",
+  "hooray",
+  "rocket",
+  "eyes"
+];
+var isReaction = (s) => REACTIONS.includes(s);
+var ReactionCodec = t.type({ id: t.number, content: t.string });
+var reactionsPath = (repo, commentId) => `repos/${repo}/issues/comments/${String(commentId)}/reactions`;
+var removeReactions = async (repo, commentId, content, ghApi) => {
+  const stdout = await ghApi([
+    reactionsPath(repo, commentId),
+    "--paginate",
+    "--jq",
+    ".[] | {id, content}"
+  ]);
+  for (const line of stdout.split("\n").filter((l) => l.trim() !== "")) {
+    const parsed = tryParseJson(line);
+    const decoded = parsed.ok ? ReactionCodec.decode(parsed.value) : void 0;
+    if (decoded === void 0 || decoded._tag === "Left") {
+      process.stderr.write("code-review react: could not decode a reaction entry \u2014 skipping\n");
+      continue;
+    }
+    if (decoded.right.content !== content) continue;
+    await ghApi([
+      "--method",
+      "DELETE",
+      `${reactionsPath(repo, commentId)}/${String(decoded.right.id)}`
+    ]).catch(
+      (err) => process.stderr.write(
+        `code-review react: could not remove reaction ${String(decoded.right.id)} (${errMsg(err)}) \u2014 skipping
+`
+      )
+    );
+  }
+};
+var react = async (input, ghApi = runGhApi) => {
+  if (input.add !== void 0) {
+    await ghApi([
+      "--method",
+      "POST",
+      reactionsPath(input.repo, input.commentId),
+      "-f",
+      `content=${input.add}`
+    ]);
+  }
+  if (input.remove !== void 0) {
+    await removeReactions(input.repo, input.commentId, input.remove, ghApi);
+  }
+};
+var RunCodec = t.type({
+  id: t.number,
+  name: t.union([t.string, t.null]),
+  status: t.union([t.string, t.null]),
+  conclusion: t.union([t.string, t.null]),
+  run_number: t.number
+});
+var RunsCodec = t.type({ workflow_runs: t.array(RunCodec) });
+var resolveCiRun = async (repo, headSha, workflowName, ghApi) => {
+  const stdout = await ghApi([`repos/${repo}/actions/runs?head_sha=${headSha}&per_page=100`]);
+  const decoded = RunsCodec.decode(JSON.parse(stdout));
+  if (decoded._tag === "Left")
+    throw new Error(
+      `workflow runs for ${headSha} did not match the expected shape: ${PathReporter.report(decoded).join("; ")}`
+    );
+  const runs = decoded.right.workflow_runs;
+  const latest = runs.filter((r) => r.name === workflowName).reduce(
+    (best, r) => best === null || r.run_number > best.run_number ? r : best,
+    null
+  );
+  return {
+    run: latest === null ? null : { id: latest.id, status: latest.status ?? "unknown", conclusion: latest.conclusion },
+    seenNames: [...new Set(runs.flatMap((r) => r.name === null ? [] : [r.name]))]
+  };
+};
+var awaitCiConclusion = async (repo, headSha, options, deps = { ghApi: runGhApi, sleep: defaultSleep, elapsedMs: monotonicElapsed() }) => {
+  const poll = async () => {
+    const { run, seenNames } = await resolveCiRun(repo, headSha, options.workflowName, deps.ghApi);
+    if (run !== null && run.status === "completed")
+      return { kind: "concluded", conclusion: run.conclusion ?? "unknown", runId: run.id };
+    if (deps.elapsedMs() >= options.timeoutMs)
+      return { kind: "timed-out", runId: run === null ? null : run.id, seenNames };
+    await deps.sleep(options.pollIntervalMs);
+    return poll();
+  };
+  return poll();
+};
+var defaultSleep = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+var monotonicElapsed = () => {
+  const start = Date.now();
+  return () => Date.now() - start;
+};
+var renderCiOutputs = (outcome) => outcome.kind === "concluded" ? `ci_settled=true
+ci_conclusion=${outcome.conclusion}
+ci_run_id=${String(outcome.runId)}
+` : `ci_settled=false
+ci_run_id=${outcome.runId === null ? "" : String(outcome.runId)}
+`;
 var renderOutputs = (result) => {
   switch (result.kind) {
     case "skip":
@@ -3095,6 +3329,164 @@ var postCmd = defineCommand({
     });
   }
 });
+var requireCeilingSec = (raw) => {
+  if (raw === void 0) return null;
+  const ms = parseWallMs(raw);
+  if (ms === null)
+    return fail(`--max-duration must be a duration like 60m, 3600s, or 1h (got "${raw}")`);
+  return Math.floor(ms / 1e3);
+};
+var requireCeilingUsd = (raw) => {
+  if (raw === void 0) return null;
+  const n = Number.parseFloat(raw.replace(/^\$/, ""));
+  if (!Number.isFinite(n) || n < 0) fail(`--max-usd must be a non-negative number (got "${raw}")`);
+  return n;
+};
+var requireMaxInstructions = (raw) => {
+  if (raw === void 0) return 4e3;
+  if (!/^\d+$/.test(raw)) fail(`--max-instructions must be a non-negative integer (got "${raw}")`);
+  return Number.parseInt(raw, 10);
+};
+var requirePositiveInt = (raw, flag) => {
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) && n > 0 && /^\d+$/.test(raw) ? n : fail(`${flag} must be a positive integer; got "${raw}"`);
+};
+var requireWallMs = (raw, flag, fallback) => {
+  const ms = parseWallMs(raw || fallback);
+  return ms === null ? fail(`${flag} must be a duration like 30m, 15s, or 1h (got "${raw ?? ""}")`) : ms;
+};
+var parseCommandCmd = defineCommand({
+  meta: {
+    name: "parse-command",
+    description: `Resolve a PR's head (SHA/branch/repo) from its NUMBER via the API and parse a ChatOps trigger comment ("/code-review [24m] [$1.00] <instructions>") into $GITHUB_OUTPUT lines. The untrusted comment is parsed here in type-safe code, never in workflow bash, and the head is resolved from the trusted PR number, never from the comment text. Emits should_run=false (and nothing else) when the comment is not the trigger, the PR is closed, or resolution fails.`
+  },
+  args: {
+    repo: { type: "string", description: "Repository (owner/name)", required: true },
+    pr: {
+      type: "string",
+      description: "PR number (from github.event.issue.number \u2014 trusted event data)",
+      required: true
+    },
+    "comment-body": {
+      type: "string",
+      description: "The comment body to parse (default: the CODE_REVIEW_COMMENT_BODY env var \u2014 the safe way to pass untrusted text without shell interpolation)"
+    },
+    trigger: {
+      type: "string",
+      description: 'Trigger token the comment must begin with (default: "/code-review")'
+    },
+    "max-duration": {
+      type: "string",
+      description: "Ceiling the requested duration is clamped to (e.g. 60m); omit for no clamp \u2014 a comment could then request an unbounded wall, so set this"
+    },
+    "max-usd": {
+      type: "string",
+      description: "Ceiling the requested USD budget is clamped to (e.g. 5); omit for no clamp"
+    },
+    "max-instructions": {
+      type: "string",
+      description: "Max characters of free-form instructions kept (default: 4000)"
+    }
+  },
+  run: async ({ args }) => {
+    const body = args["comment-body"] || process.env["CODE_REVIEW_COMMENT_BODY"] || "";
+    const result = await parseCommand({
+      repo: args.repo,
+      prNumber: requirePositiveInt(args.pr, "--pr"),
+      body,
+      options: {
+        trigger: args.trigger || "/code-review",
+        maxDurationSec: requireCeilingSec(args["max-duration"]),
+        maxUsd: requireCeilingUsd(args["max-usd"]),
+        maxInstructionsLen: requireMaxInstructions(args["max-instructions"])
+      }
+    });
+    if (result.kind === "skip") {
+      process.stderr.write(`code-review parse-command: not running \u2014 ${result.reason}
+`);
+      process.stdout.write(renderCommandOutputs(result, "UNUSED"));
+      return;
+    }
+    for (const note of result.args.notes)
+      process.stderr.write(`code-review parse-command: ${note}
+`);
+    const delim = safeHeredocDelim(result.args.instructions, () => randomBytes(16).toString("hex"));
+    process.stdout.write(renderCommandOutputs(result, delim));
+  }
+});
+var requireReaction = (name) => isReaction(name) ? name : fail(`Unknown reaction "${name}" \u2014 one of: ${REACTIONS.join(", ")}`);
+var reactCmd = defineCommand({
+  meta: {
+    name: "react",
+    description: "Add and/or remove a GitHub reaction on a PR/issue comment \u2014 the ChatOps acknowledgement (\u{1F440} on receipt, swapped to \u{1F680} on completion). Cosmetic: warns and exits 0 on any API error so a reaction never fails the job."
+  },
+  args: {
+    repo: { type: "string", description: "Repository (owner/name)", required: true },
+    "comment-id": {
+      type: "string",
+      description: "Comment id to react on (github.event.comment.id)",
+      required: true
+    },
+    add: { type: "string", description: `Reaction to add: ${REACTIONS.join(" | ")}` },
+    remove: {
+      type: "string",
+      description: "Reaction (of the token owner) to remove after adding \u2014 for the \u{1F440}\u2192\u{1F680} swap"
+    }
+  },
+  run: async ({ args }) => {
+    const commentId = requirePositiveInt(args["comment-id"], "--comment-id");
+    const add = args.add ? requireReaction(args.add) : void 0;
+    const remove = args.remove ? requireReaction(args.remove) : void 0;
+    if (add === void 0 && remove === void 0)
+      fail("react: nothing to do \u2014 pass --add and/or --remove");
+    await react({ repo: args.repo, commentId, add, remove }).catch(
+      (err) => process.stderr.write(
+        `code-review react: reaction update failed (${errMsg(err)}) \u2014 continuing (reactions are cosmetic)
+`
+      )
+    );
+  }
+});
+var awaitCiCmd = defineCommand({
+  meta: {
+    name: "await-ci",
+    description: "Wait for the PR head's CI workflow run to conclude, then emit its REAL conclusion + run id to $GITHUB_OUTPUT (ci_settled, ci_conclusion, ci_run_id). The on-demand comment trigger uses this so it routes on the same CI result the CI-completion trigger would \u2014 success \u2192 full review, failure \u2192 mechanic with that run's logs \u2014 instead of reviewing blind. Polls until the run completes or the timeout elapses; ci_settled=false \u21D2 no conclusive result (caller should decline to review, not guess)."
+  },
+  args: {
+    repo: { type: "string", description: "Repository (owner/name)", required: true },
+    "head-sha": {
+      type: "string",
+      description: "PR head SHA to find the CI run for (resolved from the trusted PR number)",
+      required: true
+    },
+    "ci-workflow": {
+      type: "string",
+      description: 'CI workflow name to wait for \u2014 the name: of your CI workflow (default: "CI")'
+    },
+    timeout: {
+      type: "string",
+      description: "Give up waiting after this wall (default: 30m)"
+    },
+    "poll-interval": {
+      type: "string",
+      description: "How often to re-check the run status (default: 15s)"
+    }
+  },
+  run: async ({ args }) => {
+    const workflowName = args["ci-workflow"] || "CI";
+    const outcome = await awaitCiConclusion(args.repo, args["head-sha"], {
+      workflowName,
+      pollIntervalMs: requireWallMs(args["poll-interval"], "--poll-interval", "15s"),
+      timeoutMs: requireWallMs(args.timeout, "--timeout", "30m")
+    });
+    process.stderr.write(
+      outcome.kind === "concluded" ? `code-review await-ci: CI run ${String(outcome.runId)} ("${workflowName}") concluded "${outcome.conclusion}"
+` : `code-review await-ci: no run named "${workflowName}" concluded before the timeout \u2014 not reviewing.${outcome.seenNames.length > 0 ? ` Workflow names seen for this head SHA: ${outcome.seenNames.join(", ")} \u2014 check --ci-workflow matches one.` : " No workflow runs were seen for this head SHA at all."}
+`
+    );
+    process.stdout.write(renderCiOutputs(outcome));
+  }
+});
 var main = defineCommand({
   meta: {
     name: "code-review",
@@ -3103,6 +3495,9 @@ var main = defineCommand({
   },
   subCommands: {
     gather: gatherCmd,
+    "parse-command": parseCommandCmd,
+    react: reactCmd,
+    "await-ci": awaitCiCmd,
     render: renderCmd,
     inline: inlineCmd,
     post: postCmd,