@expo/code-review-cli 0.13.0 → 0.14.2

package/README.md

@@ -274,8 +274,8 @@ The boundary, in brief:
   many discovery and page fetches, so each call reports its own request ledger and
   the run reports totals.
 - **Root-only in routed monorepos** (it starts a host process); scope configs
-  cannot alter it. Result-cache reuse is disabled while research is enabled,
-  because web content can change without a config change.
+  cannot alter it. Research results are fetched and audited per run; cached review
+  results remain keyed by the ordinary trusted review inputs and make no network call.
 
 Full detail — providers, query grammar, `fetch_platform_doc` modes, provenance and
 citation grounding: [LLP 0013](./llp/0013-platform-research.explainer.md).
@@ -651,6 +651,44 @@ the defaults are asymmetric: [LLP 0011](./llp/0011-author-feedback.explainer.md)
 
 </details>
 
+<details>
+<summary><b>Inline PR comments (findings on the diff line)</b></summary>
+
+Off by default. When enabled, each finding anchored to a line that is actually in
+the PR's diff is posted as an inline review comment on that line, carrying the
+full rationale, sources, and suggestion. The main comment still lists every
+finding, but an inlined one renders short — title, links, category, id, and a
+one-line rationale — plus a `💬 inline comment` link to the thread. The main
+comment remains the single durable state store: `/dismiss`, embedded state, and
+reply adjudication are unchanged.
+
+```jsonc
+"inline": {
+  "enabled": false,
+  "maxComments": 20   // per PR (single comment mode) / per scope (per-scope mode)
+}
+```
+
+Behavior notes:
+
+- **Threads converge, never churn.** Each inline comment carries a per-finding
+  marker and is patched in place across re-reviews. The cap is sticky: a live
+  thread is never evicted to create a new one. A finding that leaves the set is
+  stubbed if humans replied in its thread (never deleted), deleted only when bare.
+- **Fail-safe teardown.** A failed run, a `--scopes` partial run, or a truncated
+  aggregate never tears threads down — teardown only runs when the target set is
+  provably complete. Creates are skipped (and logged) when the PR head moved
+  during the review.
+- **Replies on inline threads count as author feedback.** Replying in a thread
+  matches the reply to that finding structurally; clearing still requires the
+  `id:…` token in the replier's own words, same as main-comment replies.
+- **Notification fan-out.** The first enabled run on a PR sends one notification
+  per created inline comment; `maxComments` bounds it.
+- **Disabling later** leaves existing threads up (the sync no longer runs); a
+  comment-mode switch — or the reporter's clear path — stubs/removes them.
+
+</details>
+
 <details>
 <summary><b>External context (--context-file)</b></summary>
 

package/build/commands/ci.js

@@ -446,6 +446,7 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
         breakGlassMarker: config.breakGlassMarker,
         cwd,
         feedback: config.feedback,
+        inline: config.inline,
         headSha,
     });
     try {
@@ -554,6 +555,10 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
                 findings: [],
                 summary: `⚠️ The AI reviewer failed to run, so this change was **not** reviewed:\n\n> ${publicFailureReason(error)}`,
                 incomplete: [],
+                // A failed run's empty findings list proves nothing: this flag is what keeps
+                // the inline sync additive-only (no thread teardown) — and it renders the
+                // accurate "No review" decision label.
+                couldNotComplete: true,
             });
         }
         catch (postError) {
@@ -568,6 +573,10 @@ function failureReview(scopeName, reason) {
         findings: [],
         summary: `⚠️ The AI reviewer failed to run for scope **${scopeName}**, so those changes were **not** reviewed:\n\n> ${reason}`,
         incomplete: [],
+        // Empty-but-not-clean: keeps the inline sync additive-only for the whole
+        // aggregate (a failed scope's findings may still be live on the PR) and renders
+        // the accurate "No review" label in the scope table.
+        couldNotComplete: true,
     };
 }
 // @ref LLP 0007#routed-ci-fan-out [implements] — root tag wins; sequential per-scope budgets; partial --scopes merges prior state
@@ -704,6 +713,7 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         // Root-only feedback config (see loadScopeConfig): lets a reporter posting with
         // no explicit records match replies itself (annotate mode) at report time.
         feedback: rootConfig.feedback,
+        inline: rootConfig.inline,
         headSha,
     });
     // comment:'single' mode: every active scope's feedback seam AND the final
@@ -900,7 +910,12 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
             const aggFeedback = feedbackNeedsRunSeam(rootConfig.feedback)
                 ? mergeAggregateFeedback(results, finalResults, aggState?.feedback ?? [], rootConfig.feedback, headSha, aggState?.pins)
                 : undefined;
-            await aggregate.reportAggregate(finalResults, resolution.unmatched, aggFeedback);
+            // A --scopes partial run carries the other scopes out of (possibly truncated)
+            // embedded state, so its target set is incomplete: inline teardown must not
+            // run (failed scopes are handled inside reportAggregate itself).
+            await aggregate.reportAggregate(finalResults, resolution.unmatched, aggFeedback, {
+                inlineTeardown: !scopesFilter,
+            });
         }
         // Clean up any per-scope comments from a previous per-scope run. A partial run
         // only ever touches the named scopes' comments.

package/build/commands/dismiss.js

@@ -84,6 +84,8 @@ export async function dismissCommand(argv, mode) {
             // feedback policy in force now — without it a reply-cleared finding would be
             // un-hidden by an unrelated /dismiss.
             feedback: config.feedback,
+            // Lets the dismissal stub/revive the finding's inline thread (additive-only).
+            inline: config.inline,
         });
         const result = await reporter.applyDismissal(mode === "add" ? args.ids : [], mode === "remove" ? args.ids : [], args.by, args.reason);
         if (mode === "add") {

package/build/commands/post-review.js

@@ -113,6 +113,7 @@ export async function postReviewCommand(argv) {
             breakGlassMarker: config.breakGlassMarker,
             cwd,
             feedback: config.feedback,
+            inline: config.inline,
             headSha,
         });
         const result = await publishDeferredReview(reporter, artifact, async () => {

package/build/commands/review.js

@@ -242,6 +242,8 @@ export async function reviewCommand(argv) {
                         cwd,
                         // Root-only feedback config (loadScopeConfig inherits it from the root).
                         feedback: config.feedback,
+                        // Root-only too (loadScopeConfig inherits it from the root).
+                        inline: config.inline,
                         headSha: await reviewedHeadSha(source),
                     })
                     : null;
@@ -315,6 +317,7 @@ export async function reviewCommand(argv) {
                 breakGlassMarker: config.breakGlassMarker,
                 cwd,
                 feedback: config.feedback,
+                inline: config.inline,
                 headSha,
             })
             : null;

package/build/config/load.js

@@ -26,6 +26,11 @@ const FEEDBACK_CONFIG_DEFAULTS = {
     protectedCategories: ["secrets", "security"],
     maxAdjudications: 10,
 };
+/** Inline-comment config for a scope load (where `inline` is schema-rejected). */
+const INLINE_CONFIG_DEFAULTS = {
+    enabled: false,
+    maxComments: 20,
+};
 /** Research defaults for a scope load (where `research` is schema-rejected). */
 const RESEARCH_CONFIG_DEFAULTS = {
     enabled: false,
@@ -162,6 +167,8 @@ async function loadConfigDir(dir, schema) {
         // for a scope config and the defaults stand in (unused — the command layer
         // reads the ROOT config's feedback values; the comment lifecycle is global).
         feedback: parsed.feedback ?? FEEDBACK_CONFIG_DEFAULTS,
+        // Root-only, same reasoning as feedback.
+        inline: parsed.inline ?? INLINE_CONFIG_DEFAULTS,
     };
     return { config, raw: rawObject };
 }
@@ -296,6 +303,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         // run the default policy instead of the repo's real one.
         stack: rootConfig.stack,
         feedback: rootConfig.feedback,
+        inline: rootConfig.inline,
         research: rootConfig.research,
         scopeName: scope.name,
     };

package/build/config/schema.js

@@ -216,6 +216,20 @@ export const ReviewConfigSchema = z.object({
         protectedCategories: ["secrets", "security"],
         maxAdjudications: 10,
     }),
+    // Inline PR review comments for findings anchored to a line in the diff: the
+    // main comment stays the durable state store and renders such findings short,
+    // linking to the inline thread. ROOT-ONLY (the comment lifecycle is global) and
+    // off by default — a feature that mutates N comments per run earns trust with
+    // field data first. Turning it off later leaves existing threads up (documented);
+    // clear() still sweeps them on comment-mode switches.
+    inline: z
+        .object({
+        enabled: z.boolean().default(false),
+        // Cap on inline comments PER REPORTER: per PR in single/legacy comment mode,
+        // per scope in per-scope mode. Bounds create-notification fan-out and API use.
+        maxComments: z.number().int().positive().default(20),
+    })
+        .default({ enabled: false, maxComments: 20 }),
 });
 /** One routing scope: ordered globs → a directory containing .expo-code-review/. */
 export const RoutingScopeSchema = z.object({
@@ -317,6 +331,7 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
     stack: true,
     feedback: true,
     research: true,
+    inline: true,
 }).extend({
     auth: z
         .never({ error: "auth is locked to the root config; remove it from this scope config" })
@@ -342,4 +357,9 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
         error: "research is locked to the root config because it starts a trusted host process; remove it from this scope config",
     })
         .optional(),
+    inline: z
+        .never({
+        error: "inline is locked to the root config (the comment lifecycle is global); remove it from this scope config",
+    })
+        .optional(),
 });

package/build/core/claude-code.js

@@ -448,6 +448,7 @@ export function parseClaudeResult(stdout) {
     const tokens = {
         input: num(usage.input_tokens),
         output: num(usage.output_tokens),
+        reasoning: num(usage.output_tokens_details?.thinking_tokens),
         cache: {
             write: num(usage.cache_creation_input_tokens),
             read: num(usage.cache_read_input_tokens),

package/build/core/deferred-review.js

@@ -33,6 +33,10 @@ export function reviewPostingConfigFingerprint(config) {
         commentTag: config.commentTag,
         breakGlassMarker: config.breakGlassMarker,
         feedback: config.feedback,
+        // Inline comments change what posting does (N review-comment mutations), so a
+        // saved review must not post under a different inline policy than it was
+        // saved with.
+        inline: config.inline,
     }))
         .digest("hex");
 }

package/build/core/render.js

@@ -67,6 +67,27 @@ export function groupBySeverity(findings) {
 export function commentMarker(tag) {
     return `<!-- ${tag} -->`;
 }
+/**
+ * Per-finding identity marker of an inline (PR review) comment, always rendered at
+ * byte 0 of the body. Substring-safe against `commentMarker(tag)` and any derived
+ * scope tag (`<tag>:<scope>`) in both directions — the closing ` -->` differs —
+ * including a scope literally named `inline`.
+ */
+export function inlineCommentMarker(tag, fp) {
+    return `<!-- ${tag}:inline:fp=${fp} -->`;
+}
+/**
+ * The fingerprint an inline comment of OURS carries, or null. Anchored at byte 0
+ * and constrained to the fingerprint alphabet, so a marker echoed later in a body
+ * (untrusted prose, a quote-reply) can never parse as identity — mechanical
+ * safety, not just the incidental "our renderer emits it first". Identity itself
+ * is author + this marker (see the reporter); the parse alone proves nothing.
+ */
+export function parseInlineMarkerFp(body, tag) {
+    const escapedTag = tag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = body.match(new RegExp(`^<!-- ${escapedTag}:inline:fp=([a-f0-9]{6,64}) -->`));
+    return match ? match[1] : null;
+}
 // @ref LLP 0011#forged-state-markers [implements] — the first-match parsers make an earlier forged marker win, so untrusted prose never keeps a raw `<!--`
 /**
  * Neutralize anything that could impersonate this reviewer's embedded state
@@ -233,7 +254,41 @@ function sourceLabel(value) {
         .replace(/>/g, "&gt;")
         .replace(/([\\[\]])/g, "\\$1");
 }
+/** Longest one-line rationale excerpt the short form keeps in the main comment. */
+const SHORT_RATIONALE_CHARS = 160;
+/**
+ * A rationale reduced to one plain line for the short (inlined) form: whitespace
+ * collapsed, every `<` escaped so a truncated HTML block (`<details>`) can never
+ * leave an unclosed tag in the comment, cut at a word boundary with an ellipsis.
+ * This excerpt is the audit trail that survives the PR author collapsing or
+ * resolving the inline thread, so it must always be non-empty when the rationale is.
+ */
+export function oneLineRationale(text) {
+    const flat = text.replace(/</g, "&lt;").replace(/\s+/g, " ").trim();
+    if (flat.length <= SHORT_RATIONALE_CHARS) {
+        return flat;
+    }
+    const cut = flat.slice(0, SHORT_RATIONALE_CHARS);
+    const atWord = cut.slice(0, cut.lastIndexOf(" "));
+    return `${atWord.length > 0 ? atWord : cut}…`;
+}
+/** Only ever link to github.com from a stored/returned URL (see REPLY_URL_RE). */
+function validInlineUrl(link, id) {
+    const url = link?.inlineUrls?.get(id);
+    return url && REPLY_URL_RE.test(url) ? url : null;
+}
 function renderFindingLines(finding, link, id = fingerprintFinding(finding), reply) {
+    const inlineUrl = validInlineUrl(link, id);
+    if (inlineUrl) {
+        // Short form: the full text lives in the inline thread on the flagged line.
+        // The one-line rationale stays here as the durable audit trail (the author
+        // can collapse/resolve the thread; they cannot edit this comment).
+        return [
+            `- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} _(${finding.category})_ · \`id:${id}\` · 💬 [inline comment](${inlineUrl})${replyAnnotation(reply)}`,
+            ...indentContinuation(oneLineRationale(stripStateMarkers(finding.rationale))),
+            "",
+        ];
+    }
     const out = [
         `- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} _(${finding.category})_ · \`id:${id}\`${replyAnnotation(reply)}`,
         ...indentContinuation(stripStateMarkers(finding.rationale)),
@@ -255,6 +310,47 @@ function renderFindingLines(finding, link, id = fingerprintFinding(finding), rep
     out.push("");
     return out;
 }
+/**
+ * Full body of one inline (PR review) finding comment: identity marker at byte 0,
+ * then the finding rendered whole — everything model-written passes
+ * stripStateMarkers, same as the main comment. The footer teaches the clearing
+ * flow (an UNQUOTED id citation), since the main comment only shows the short form.
+ * The body must never contain `:state=`/`:fingerprints=` (it would be dropped as
+ * our own main comment by the reply matcher's backstop) — it doesn't.
+ */
+export function renderInlineCommentBody(finding, tag, fp) {
+    const lines = [
+        inlineCommentMarker(tag, fp),
+        `**${severityHeading(finding.severity)}: ${stripStateMarkers(finding.title)}** _(${finding.category})_ · \`id:${fp}\``,
+        "",
+        stripStateMarkers(finding.rationale),
+    ];
+    if (finding.sources?.length) {
+        const sources = finding.sources
+            .map((source) => `[${sourceLabel(source.title)}](<${source.url}>)`)
+            .join(", ");
+        lines.push("", `**Sources:** ${sources}`);
+    }
+    if (finding.suggestion) {
+        lines.push("", `**Suggestion:** ${stripStateMarkers(finding.suggestion)}`);
+    }
+    lines.push("", "---", `_🤖 AI review finding — reply here to respond; write \`id:${fp}\` (outside any quote) in your reply to formally answer it. Full review in the main PR comment._`);
+    return lines.join("\n");
+}
+/**
+ * What a no-longer-tracked inline comment is patched to when its thread has human
+ * replies (a bare one is deleted instead). Deliberately NEUTRAL: a finding leaves
+ * the inline set for many reasons that are not resolution — capped out, its line
+ * left the diff, aggregate-state truncation — so this text must never assert
+ * "resolved" or "dismissed". The marker stays, so a returning finding revives the
+ * same thread instead of opening a new one.
+ */
+export function inlineStubBody(tag, fp) {
+    return [
+        inlineCommentMarker(tag, fp),
+        "_🤖 This finding is no longer tracked inline — see the main review comment for current status._",
+    ].join("\n");
+}
 // @ref LLP 0012#run-points-command-and-review [implements] — setup advice renders outside the findings list, so it never blocks
 /** Advice about the reviewer's own setup (stale refs, cited code this PR moves). */
 function setupNote(notes = []) {

package/build/core/responses.js

@@ -15,6 +15,21 @@ const FINDING_ID_RE = /\bid:([a-f0-9]{6,64})\b/gi;
  * would let the review answer itself, so this is the tag-independent backstop.
  */
 const OWN_COMMENT_RE = /<!--[^\n]*:(?:state|fingerprints)=/;
+/** The tag-independent shape of an inline finding comment's identity marker. */
+const INLINE_MARKER_RE = /<!--[^\n]*:inline:fp=/;
+/**
+ * Tag-independent backstop for OUR inline finding comments, which carry an
+ * UNQUOTED `id:<fp>` token in the body (so a maintainer can copy it into a
+ * reply). If the author/tag filters ever miss one — a bot-login fallback, a
+ * commentTag rename, a second posting identity — matching it as a reply would
+ * let the review cite (and, with maintainer association, CLEAR) its own
+ * finding. Only UNQUOTED lines count: GitHub's "Quote reply" copies our marker
+ * verbatim behind `> `, and that comment is a genuine human reply that must
+ * still be matched.
+ */
+export function hasUnquotedInlineMarker(body) {
+    return body.split("\n").some((line) => !/^\s*>/.test(line) && INLINE_MARKER_RE.test(line));
+}
 /**
  * Markdown → comparable text: link text without the target, no backticks or
  * emphasis marks, collapsed whitespace, lowercase, no trailing punctuation. A
@@ -60,6 +75,19 @@ export function extractQuotedLines(body) {
     }
     return out;
 }
+/**
+ * Is `candidate` a more recent reply than `incumbent`? Issue comments carry
+ * positive ids; inline (PR review) replies carry NEGATED ids, so within the
+ * inline stream recency is the raw id's magnitude, not the signed value. The two
+ * sequences are independent, so cross-stream recency is undecidable — the issue
+ * comment wins deterministically (the main thread is the formal reply channel).
+ */
+export function replyIsNewer(candidate, incumbent) {
+    if (candidate >= 0 === incumbent >= 0) {
+        return Math.abs(candidate) > Math.abs(incumbent);
+    }
+    return candidate >= 0;
+}
 /** The `id:<hex>` tokens a comment cites, lowercased and deduped. */
 export function extractFindingIds(body) {
     const ids = [...body.matchAll(FINDING_ID_RE)].map((match) => match[1].toLowerCase());
@@ -108,7 +136,7 @@ export function matchReplies(comments, findings, opts) {
     }
     const newest = new Map();
     for (const comment of comments) {
-        if (OWN_COMMENT_RE.test(comment.body)) {
+        if (OWN_COMMENT_RE.test(comment.body) || hasUnquotedInlineMarker(comment.body)) {
             continue;
         }
         const matched = new Set();
@@ -116,6 +144,11 @@ export function matchReplies(comments, findings, opts) {
         // quote-matched reply still records WHETHER it cites the finding, because that is
         // what decides clearing.
         const cited = new Set(extractCitedFindingIds(comment.body));
+        // An inline reply names its finding structurally — the replier chose which
+        // thread to answer — so it matches in every `match` mode. Never sets `citedId`.
+        if (comment.threadFp && known.has(comment.threadFp)) {
+            matched.add(comment.threadFp);
+        }
         if (opts.match !== "quote") {
             for (const id of extractFindingIds(comment.body)) {
                 if (known.has(id)) {
@@ -139,7 +172,7 @@ export function matchReplies(comments, findings, opts) {
         }
         for (const fp of matched) {
             const previous = newest.get(fp);
-            if (previous && previous.commentId >= comment.id) {
+            if (previous && !replyIsNewer(comment.id, previous.commentId)) {
                 continue;
             }
             newest.set(fp, {

package/build/core/schema.js

@@ -336,7 +336,16 @@ export function applyPins(records, pins) {
     // A pin with no recorded commentId is never lifted by a reply: "unknown" must not
     // read as "older than every comment", which would let any maintainer reply lift it.
     pin.commentId === undefined ||
-        !records.some((record) => record.fp === pin.fp && record.maintainer === true && record.commentId > pin.commentId));
+        !records.some((record) => record.fp === pin.fp &&
+            record.maintainer === true &&
+            // "Posted after the pin" is only decidable within one id sequence. Issue
+            // comments carry positive ids and inline (PR review) replies carry NEGATED
+            // ones (see the reporter's replyComments); the two sequences are
+            // independent, so a cross-stream comparison says nothing about time — keep
+            // the pin. Within a stream, recency is the raw id's magnitude (negation
+            // inverts the signed order for inline ids).
+            record.commentId >= 0 === pin.commentId >= 0 &&
+            Math.abs(record.commentId) > Math.abs(pin.commentId)));
     const pinnedFps = new Set(kept.map((pin) => pin.fp));
     const stamped = records.map((record) => {
         if (pinnedFps.has(record.fp)) {