@jphutchins/code-review 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import { readFileSync, writeFileSync, readdirSync } from 'fs';
-import { resolve as resolve$1, join, dirname } from 'path';
+import { resolve as resolve$1, join, dirname, basename } from 'path';
 import { Eta } from 'eta';
 import parseDiff from 'parse-diff';
 import { Ajv2020 } from 'ajv/dist/2020.js';
@@ -463,8 +463,9 @@ var sumTranscriptUsage = (entries) => {
   };
 };
 var subagentFiles = (mainPath) => {
+  const dir = join(dirname(mainPath), basename(mainPath, ".jsonl"), "subagents");
   try {
-    return readdirSync(join(dirname(mainPath), "subagents")).filter((name) => name.endsWith(".jsonl")).map((name) => join(dirname(mainPath), "subagents", name));
+    return readdirSync(dir).filter((name) => name.endsWith(".jsonl")).map((name) => join(dir, name));
   } catch {
     return [];
   }
@@ -659,7 +660,7 @@ var decideGate = (state, nudges, maxNudges, draftPath, kind) => {
     reason: [
       `This review is not complete \u2014 ${whatsWrong(state, draftPath, kind)}`,
       `The only deliverable is a ${kind} document that validates against the ${kind} schema \u2014 run "code-review print-schema ${kind}" to see the exact shape.`,
-      `Write it to ${draftPath}, then run "code-review validate ${draftPath} --kind ${kind}" until it exits 0 before ending your turn.`
+      `Write it to ${draftPath}, then run "code-review validate ${draftPath} --kind ${kind} --explain" until it exits 0 before ending your turn (--explain prints the schema when the shape is wrong).`
     ].join("\n")
   };
 };
@@ -722,19 +723,27 @@ var stopHookSettings = (command) => ({
 });
 
 // src/budget.ts
-var DEFAULT_RESERVE = { frac: 0.15, flatUsd: 0.02, flatMs: 12e4 };
+var DEADLINE_ENV = "CODE_REVIEW_DEADLINE_EPOCH";
+var DEFAULT_RESERVE = {
+  frac: 0.15,
+  growth: 0.25,
+  flatUsd: 0.02,
+  flatMs: 12e4
+};
 var SOFT_MULTIPLE = 2;
 var costAxis = (i) => i.spentUsd !== null && i.budgetUsd !== null && i.budgetUsd > 0 ? { used: i.spentUsd, limit: i.budgetUsd, flat: i.reserve.flatUsd } : null;
 var timeAxis = (i) => i.elapsedMs !== null && i.wallMs !== null && i.wallMs > 0 ? { used: i.elapsedMs, limit: i.wallMs, flat: i.reserve.flatMs } : null;
-var axisSeverity = (a, frac) => {
-  const hardReserve = Math.max(a.flat, frac * a.limit);
+var axisSeverity = (a, reserve) => {
+  const usedFrac = Math.min(1, Math.max(0, a.used / a.limit));
+  const effFrac = reserve.frac + reserve.growth * usedFrac;
+  const hardReserve = Math.max(a.flat, effFrac * a.limit);
   const remaining = a.limit - a.used;
   if (remaining <= hardReserve) return 2;
   if (remaining <= SOFT_MULTIPLE * hardReserve) return 1;
   return 0;
 };
 var decideBudget = (i) => {
-  const worst = [costAxis(i), timeAxis(i)].filter((a) => a !== null).reduce((max, a) => Math.max(max, axisSeverity(a, i.reserve.frac)), 0);
+  const worst = [costAxis(i), timeAxis(i)].filter((a) => a !== null).reduce((max, a) => Math.max(max, axisSeverity(a, i.reserve)), 0);
   return worst === 2 ? { kind: "hard" } : worst === 1 ? { kind: "soft" } : { kind: "ok" };
 };
 var pct = (n) => `${String(Math.round(n * 100))}%`;
@@ -742,7 +751,7 @@ var money = (n) => `$${n.toFixed(2)}`;
 var mins = (ms) => `${(ms / 6e4).toFixed(1)}m`;
 var spendClause = (i) => i.spentUsd === null ? null : i.budgetUsd !== null && i.budgetUsd > 0 ? `spent ${money(i.spentUsd)}/${money(i.budgetUsd)} (${pct(i.spentUsd / i.budgetUsd)})` : `spent ${money(i.spentUsd)}`;
 var timeClause = (i) => i.elapsedMs === null ? null : i.wallMs !== null && i.wallMs > 0 ? `${mins(i.elapsedMs)}/${mins(i.wallMs)} elapsed (${pct(i.elapsedMs / i.wallMs)})` : `${mins(i.elapsedMs)} elapsed`;
-var directive = (phase, draftPath) => phase.kind === "hard" ? `Budget nearly exhausted \u2014 STOP all new investigation now. Write your COMPLETE findings to ${draftPath} and run \`code-review validate ${draftPath}\` until it passes. Other tools are blocked until that draft is written.` : `Wind down investigation and write your COMPLETE findings to ${draftPath} now, then validate \u2014 you may run out of budget before you finish otherwise.`;
+var directive = (phase, draftPath) => phase.kind === "hard" ? `Budget nearly exhausted \u2014 STOP all new investigation now. Write your COMPLETE findings to ${draftPath} and run \`code-review validate ${draftPath} --explain\` until it passes (--explain prints the exact schema when the shape is wrong). Other tools are blocked until that draft is written.` : `Wind down investigation and write your COMPLETE findings to ${draftPath} now, then run \`code-review validate ${draftPath} --explain\` (it prints the exact schema if the shape is wrong) \u2014 you may run out of budget before you finish otherwise.`;
 var budgetMessage = (i, phase, draftPath) => {
   const status = [spendClause(i), timeClause(i)].filter((c) => c !== null).join(" \xB7 ");
   return `Budget check \u2014 ${status}. ${directive(phase, draftPath)}`;
@@ -810,6 +819,20 @@ var parseWallMs = (raw) => {
       return n * 36e5;
   }
 };
+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);
+  return Number.isFinite(n) && n > 0 ? n * 1e3 : null;
+};
+var anchoredElapsedMs = (src) => {
+  if (src.deadlineMs !== null && src.wallMs !== null)
+    return Math.max(0, src.wallMs - (src.deadlineMs - src.nowMs));
+  if (src.firstTsMs !== null) return Math.max(0, src.nowMs - src.firstTsMs);
+  return null;
+};
+var deadlineEpochSec = (wallMs, nowMs) => Math.floor(nowMs / 1e3) + Math.ceil(wallMs / 1e3);
 var parseFraction = (raw, fallback) => {
   if (raw === void 0) return fallback;
   const n = Number.parseFloat(raw);
@@ -822,6 +845,7 @@ var budgetHookCommand = (draftPath, opts) => [
   ...opts.wall ? ["--wall", shellQuote(opts.wall)] : [],
   ...opts.prices ? ["--prices", shellQuote(opts.prices)] : [],
   ...opts.reserveFrac ? ["--reserve-frac", shellQuote(opts.reserveFrac)] : [],
+  ...opts.reserveGrowth ? ["--reserve-growth", shellQuote(opts.reserveGrowth)] : [],
   ...opts.reserveUsd ? ["--reserve-usd", shellQuote(opts.reserveUsd)] : [],
   ...opts.reserveWall ? ["--reserve-wall", shellQuote(opts.reserveWall)] : []
 ].join(" ");
@@ -1362,7 +1386,7 @@ var post = async (input, ghApi = runGhApi) => {
 `
     );
   }
-  const botReviews = comments.length > 0 ? await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi) : [];
+  const botReviews = await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi);
   const alreadyReviewedThisSha = botReviews.some((r) => r.commitId === input.headSha);
   const initialDisposition = comments.length > 0 ? alreadyReviewedThisSha ? { kind: "suppressed-existing-review", sha: input.headSha } : void 0 : strays.length > 0 ? { kind: "none-in-diff" } : void 0;
   const commonRenderInput = {
@@ -1396,10 +1420,9 @@ var post = async (input, ghApi = runGhApi) => {
     renderBody(initialDisposition),
     ghApi
   );
-  if (comments.length === 0) return;
   if (alreadyReviewedThisSha) {
     process.stderr.write(
-      `A completed bot review already exists for ${input.headSha} \u2014 updated sticky only, no new inline review
+      `A completed bot review already exists for ${input.headSha} \u2014 updated sticky only, no new review
 `
     );
     return;
@@ -1418,11 +1441,11 @@ var post = async (input, ghApi = runGhApi) => {
     ghApi
   );
   process.stderr.write(
-    `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
+    `Posted a review with ${String(comments.length)} inline comment(s) on PR #${String(prNumber)}
 `
   );
   await minimizeSupersededComments(input.repo, prNumber, input.headSha, input.botLogin, ghApi);
-  if (stickyRef !== null) {
+  if (comments.length > 0 && stickyRef !== null) {
     const confirmedDisposition = {
       kind: "posted",
       count: comments.length,
@@ -1776,16 +1799,34 @@ var withMeta = (base, meta) => ({
   ...meta.route ? { route: meta.route } : {},
   ...meta.effort ? { effort: meta.effort } : {}
 });
-var nativeTelemetry = (native, meta) => withMeta(
+var resolveTelemetry = (native, meta) => {
+  const fb = native.models.length === 0 ? meta.transcriptFallback?.() : void 0;
+  const useFallback = fb !== void 0 && fb.models.length > 0;
+  return withMeta(
+    useFallback ? {
+      models: [...fb.models],
+      turns: fb.turns,
+      duration_ms: fb.durationMs,
+      vendor_cost_usd: native.vendorCostUsd
+    } : {
+      models: native.models,
+      turns: native.turns,
+      duration_ms: native.durationMs,
+      vendor_cost_usd: native.vendorCostUsd
+    },
+    meta
+  );
+};
+var nativeTelemetry = (native, meta) => resolveTelemetry(
   {
     models: mapModelUsage(native.modelUsage),
     turns: native.num_turns,
-    duration_ms: native.duration_ms,
-    vendor_cost_usd: native.total_cost_usd ?? null
+    durationMs: native.duration_ms,
+    vendorCostUsd: native.total_cost_usd ?? null
   },
   meta
 );
-var absentTelemetry = (meta) => withMeta({ models: [], turns: 0, duration_ms: 0, vendor_cost_usd: null }, meta);
+var absentTelemetry = (meta) => resolveTelemetry({ models: [], turns: 0, durationMs: 0, vendorCostUsd: null }, meta);
 var buildEnvelope = (telemetry, native, agentFilePath) => {
   const outcome = findingsOutcome(native, agentFilePath);
   switch (outcome.kind) {
@@ -1908,6 +1949,16 @@ var unwrapAdapt = (either) => {
   }
   throw new Error("unreachable");
 };
+var transcriptFallbackFrom = (path) => {
+  const tree = readTranscriptTree(resolve$1(path));
+  if (tree.missing)
+    process.stderr.write(
+      `code-review adapt: transcript ${path} is unreadable \u2014 no telemetry fallback (issue #36)
+`
+    );
+  const usage = sumTranscriptUsage(tree.entries);
+  return { models: usage.models, turns: usage.turns, durationMs: usage.durationMs };
+};
 var bundledPath = (...segments) => resolve$1(import.meta.dirname, "..", ...segments);
 var packageVersion = JSON.parse(readFileSync(bundledPath("package.json"), "utf-8")).version;
 var resolveTemplatePath = (templateArg) => templateArg ? resolve$1(templateArg) : bundledPath("templates", "comment.eta");
@@ -2128,7 +2179,11 @@ var budgetHookCmd = defineCommand({
     },
     "reserve-frac": {
       type: "string",
-      description: "Wind-down headroom as a fraction of each budget: converge once less than this remains (default: 0.15; the soft steer tier reserves 2\xD7 this)"
+      description: "Base wind-down headroom as a fraction of each budget: converge once less than this remains (default: 0.15; the soft steer tier reserves 2\xD7 this)"
+    },
+    "reserve-growth": {
+      type: "string",
+      description: "How much the reserve grows as a budget is spent \u2014 added at full usage, so convergence lands earlier the longer the run has gone (default: 0.25; 0 = flat reserve)"
     },
     "reserve-usd": {
       type: "string",
@@ -2148,13 +2203,20 @@ var budgetHookCmd = defineCommand({
       const usage = tree ? sumTranscriptUsage(tree.entries) : void 0;
       const prices = args.prices ? tryReadPrices(args.prices) : null;
       const spentUsd = prices !== null && usage ? computeCost(usage.models, prices).totalCostUSD : null;
+      const wallMs = args.wall ? parseWallMs(args.wall) : null;
       const output = evaluateBudgetHook(input, {
         spentUsd,
         budgetUsd: parseBudgetUsd(args["budget-usd"]),
-        elapsedMs: usage?.firstTsMs != null ? Math.max(0, Date.now() - usage.firstTsMs) : null,
-        wallMs: args.wall ? parseWallMs(args.wall) : null,
+        elapsedMs: anchoredElapsedMs({
+          deadlineMs: parseEpochSecMs(process.env[DEADLINE_ENV]),
+          wallMs,
+          firstTsMs: usage?.firstTsMs ?? null,
+          nowMs: Date.now()
+        }),
+        wallMs,
         reserve: {
           frac: parseFraction(args["reserve-frac"], DEFAULT_RESERVE.frac),
+          growth: parseFraction(args["reserve-growth"], DEFAULT_RESERVE.growth),
           flatUsd: parseBudgetUsd(args["reserve-usd"]) ?? DEFAULT_RESERVE.flatUsd,
           flatMs: args["reserve-wall"] ? parseWallMs(args["reserve-wall"]) ?? DEFAULT_RESERVE.flatMs : DEFAULT_RESERVE.flatMs
         },
@@ -2216,7 +2278,11 @@ var printSettingsCmd = defineCommand({
     },
     "reserve-frac": {
       type: "string",
-      description: "Wind-down headroom as a fraction of each budget (default: 0.15; soft tier is 2\xD7)"
+      description: "Base wind-down headroom as a fraction of each budget (default: 0.15; soft tier is 2\xD7)"
+    },
+    "reserve-growth": {
+      type: "string",
+      description: "How much the reserve grows as a budget is spent, converging earlier the longer the run has gone (default: 0.25; 0 = flat)"
     },
     "reserve-usd": {
       type: "string",
@@ -2244,6 +2310,7 @@ var printSettingsCmd = defineCommand({
         wall: args.wall,
         prices: args.prices,
         reserveFrac: args["reserve-frac"],
+        reserveGrowth: args["reserve-growth"],
         reserveUsd: args["reserve-usd"],
         reserveWall: args["reserve-wall"]
       }
@@ -2252,7 +2319,36 @@ var printSettingsCmd = defineCommand({
 `);
   }
 });
+var deadlineCmd = defineCommand({
+  meta: {
+    name: "deadline",
+    description: "Print the run's absolute deadline as Unix epoch seconds (now + --wall). The review job exports this as CODE_REVIEW_DEADLINE_EPOCH right before `claude -p` so every budget hook \u2014 the main agent's and each fan-out subagent's \u2014 measures the SAME true remaining wall instead of its own transcript's start, which reads \u22480 in a fresh subagent and leaves the fan-out unsteered (issue #45)."
+  },
+  args: {
+    wall: {
+      type: "string",
+      description: "Wall-clock budget for the run (e.g. 24m, 1200s, 2h) \u2014 the deadline is now + this",
+      required: true
+    }
+  },
+  run: async ({ args }) => {
+    const wallMs = parseWallMs(args.wall);
+    if (wallMs === null) {
+      fail(`--wall must be a duration like 24m, 1200s, or 2h (got '${args.wall}')`);
+    } else {
+      process.stdout.write(`${String(deadlineEpochSec(wallMs, Date.now()))}
+`);
+    }
+  }
+});
 var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredVersion(raw) : void 0;
+var printableSchema = (schemaPath) => {
+  const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+  const enforcementSchema = Object.fromEntries(
+    Object.entries(schema).filter(([key2]) => key2 !== "$schema")
+  );
+  return JSON.stringify(enforcementSchema, null, 2);
+};
 var validateCmd = defineCommand({
   meta: {
     name: "validate",
@@ -2275,6 +2371,10 @@ var validateCmd = defineCommand({
     "schema-version": {
       type: "string",
       description: "Schema major.minor version to validate against (default: the document's declared schema_version for findings, or the kind's latest)"
+    },
+    explain: {
+      type: "boolean",
+      description: "On failure, also print the schema after the errors \u2014 its field descriptions are the authoritative spec, so the document can be fixed in one pass instead of by trial and error"
     }
   },
   run: async ({ args }) => {
@@ -2288,6 +2388,14 @@ var validateCmd = defineCommand({
       process.stderr.write("\u274C invalid\n");
       for (const e of errors) process.stderr.write(`  - ${e}
 `);
+      if (args.explain) {
+        process.stderr.write(
+          `
+The ${kind} document must conform to this schema (the field descriptions are the authoritative spec \u2014 match the property names exactly):
+${printableSchema(schemaPath)}
+`
+        );
+      }
       process.exit(1);
     }
   }
@@ -2319,13 +2427,20 @@ var adaptCmd = defineCommand({
     effort: {
       type: "string",
       description: 'Effort label to stamp into the envelope (e.g. "max" or "low")'
+    },
+    transcript: {
+      type: "string",
+      description: "Path to the session transcript (the main .jsonl); when the native envelope carries no per-model usage \u2014 a wall-clock kill leaves it empty (issue #39) \u2014 telemetry is recovered from the transcript tree (main + subagents) so cost is real, not $0.00 (issue #36)"
     }
   },
   run: async ({ args }) => {
     const envelope = unwrapAdapt(
       adapt(requireAdapterName(args.adapter), readJSONOrAbsent(args.native), args["agent-file"], {
         route: args.route,
-        effort: args.effort
+        effort: args.effort,
+        ...args.transcript ? {
+          transcriptFallback: () => transcriptFallbackFrom(args.transcript)
+        } : {}
       })
     );
     process.stdout.write(`${JSON.stringify(envelope, null, 2)}
@@ -2493,11 +2608,7 @@ var printSchemaCmd = defineCommand({
   run: async ({ args }) => {
     const schemaKind = requireSchemaKind(args.name);
     const schemaPath = requireSchemaPath(schemaKind, args["schema-version"]);
-    const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
-    const enforcementSchema = Object.fromEntries(
-      Object.entries(schema).filter(([key2]) => key2 !== "$schema")
-    );
-    process.stdout.write(`${JSON.stringify(enforcementSchema, null, 2)}
+    process.stdout.write(`${printableSchema(schemaPath)}
 `);
   }
 });
@@ -2733,7 +2844,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, stop-gate, budget-hook, and print-settings"
+    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, stop-gate, budget-hook, print-settings, and deadline"
   },
   subCommands: {
     gather: gatherCmd,
@@ -2749,7 +2860,8 @@ var main = defineCommand({
     "print-schema": printSchemaCmd,
     "stop-gate": stopGateCmd,
     "budget-hook": budgetHookCmd,
-    "print-settings": printSettingsCmd
+    "print-settings": printSettingsCmd,
+    deadline: deadlineCmd
   }
 });
 if (!process.env["VITEST"]) {