feat(action): React Doctor Review composite action

[aidenybai]

Mirrors the hosted react.review bot's doctor-only review pipeline as a self-hosted GitHub Action that lives in this repo. Consumers add it to their workflow and get inline doctor diagnostics, a sticky summary comment, thread reconciliation, and a check run — driven by their own CI, no hosted service required.

What ships

• action.yml at the repo root — new composite action: setup-node → pnpm install (filtered to @react-doctor/review-action... + react-doctor... to keep cold-start install minimal) → pnpm --filter react-doctor build → tsx actions/review/src/index.ts. Inputs: token (defaults to ${{ github.token }}), directory, node-version.
• actions/review/ — new workspace package @react-doctor/review-action with three TypeScript modules co-located per the AGENTS.md "resist over-splitting" guideline:
  • src/pipeline.ts — pure helpers: unified-diff parser, runDiagnoseAcrossWorkspace (monorepo fan-out + weighted score + path remap), computeDiagnosticsDelta (count-delta keyed by (relativePath, rule, message)), inline-candidate builder, comment formatters (formatPendingReviewComment / formatNoIssuesComment / formatRegressionComment / formatAnalysisFailureComment), and getReviewCheckAssessment for the check-run body.
  • src/github.ts — Octokit IO: compareCommitsWithBasehead (with ${headOwner}:${headRef} for fork PRs), paginated pulls.listFiles, sticky-comment upsert/delete, pulls.createReview for inline comments, GraphQL reviewThreads pagination + resolveReviewThread mutation, check-run create/complete.
  • src/index.ts — entrypoint that wires everything together.
  • src/constants.ts — magic numbers (MAX_INLINE_COMMENTS_COUNT = 25, sticky/inline markers, check-run name, GraphQL page size) per the AGENTS.md SCREAMING_SNAKE_CASE rule.
• actions/inspect/action.yml — the previous "scan + sticky comment" composite action moved here so existing consumers can pin to millionco/react-doctor/actions/inspect@main without breaking.
• .github/workflows/doctor-action.yml — dogfood workflow that runs the action against this repo's own PRs via uses: ./.
• README updates — new "PR Review (recommended)" section plus a "Scan + sticky comment (legacy)" subsection. All previous millionco/react-doctor@main references for the legacy inputs are repointed to millionco/react-doctor/actions/inspect@main.

What the action does on every PR

On pull_request (opened / synchronize / reopened):

1. Reads the event payload from GITHUB_EVENT_PATH, extracts owner/repo/PR number/head SHA/base ref, and detects fork PRs via head.repo.full_name vs base.repo.full_name.
2. Resolves the merge base via octokit.repos.compareCommitsWithBasehead.
3. Materializes the base commit alongside the runner's head checkout via git fetch --depth=1 <remote> <baseSha> + git worktree add --detach <baseDir> <baseSha>. The base remote URL embeds https://x-access-token:<token>@github.com/... so private repos work.
4. Lists changed files via octokit.pulls.listFiles (paginated). Each file's addedLineContents: Map<lineNumber, content> is derived from the unified-diff patch — required for resolving which diagnostic lines landed on + lines.
5. Runs react-doctor/api's diagnose() in-process on both the head checkout and the base worktree. Pre-discovers React subprojects via discoverReactSubprojects (workspaces in package.json + pnpm-workspace.yaml), fans out per project, combines diagnostics with paths remapped to be relative to the repo root, and weight-averages scores by sourceFileCount.
6. Diffs head vs base diagnostics using a (relativePath, rule, message) key with count deltas (not boolean presence) so duplicate diagnostics are counted correctly.
7. Inline candidates are net-new diagnostics with severity === "error" whose line lives in the file's addedLineContents map.
8. Reconciles existing inline threads via the GraphQL repository.pullRequest.reviewThreads query:
   • Threads matching a current candidate (by parsed threadKey in the HTML marker) are marked active.
   • Threads no longer in the candidate set get ✅ Addressed in <headSha> appended via pulls.updateReviewComment and resolved via the resolveReviewThread mutation.
9. Posts remaining (non-active) candidates via octokit.pulls.createReview({ event: "COMMENT" }), capped at MAX_INLINE_COMMENTS_COUNT (25) per run.
10. Upserts the sticky summary comment by <!-- react-doctor-review --> marker. A pending-review comment is posted before analysis starts; it's swapped for either formatRegressionComment (regressions found) or formatNoIssuesComment (clean PR) once diagnostics are computed, with a doctor metrics table in a <details> block. On catch, falls back to formatAnalysisFailureComment.
11. Creates a check run on the head SHA before analysis, then completes it with the assessment body — score table, new-diagnostics list, project metadata.

Edge cases handled

• Fork PRs — head.repo.full_name !== base.repo.full_name triggers a warning, and write failures on inline / sticky posts are caught (the workflow GITHUB_TOKEN is read-only on fork PRs). Consumers can pass a PAT or App installation token via the token input to unlock fork-PR review.
• Diagnostic path resolution — tries absolute under the repo root, absolute under the project root, relative + project-prefixed, and "already prefixed" in that order so monorepo packages report under the correct workspace.
• NoReactDependencyError / PackageJsonNotFoundError / ProjectNotFoundError — the check run concludes as skipped with a "not a React project" summary and the pending sticky comment is deleted. Doesn't loud-fail.
• Same diagnostic occurring multiple times — the diff uses count deltas keyed by (relativePath, rule, message), picking head occurrences in order.
• Inline comment markers — every inline body is prefixed with <!-- react-doctor-review-inline:<threadKey> --> so the next run can parse the marker out of the GraphQL response and decide whether to skip, resolve, or post.
• Base worktree cleanup — git worktree remove --force runs in a finally block.

Token strategy (dual-mode)

• Default — workflow GITHUB_TOKEN (action.yml default). Comments author as github-actions[bot]. Works for same-repo PRs; read-only on fork PRs (warning logged, posts attempted).
• token input override — consumer passes a PAT or GitHub App installation token via secrets for fork-PR support or branded identity.

OIDC token-broker mode is intentionally not in scope for v1 — that flow lives in the hosted react.review service and shouldn't couple this standalone action to it.

Out of scope (intentionally)

• No LLM / agent layer (the hosted bot's agent-review.ts is not ported — this is doctor-only review).
• No Vercel Sandbox dependency (everything runs in-process on the runner).
• No Upstash rate limit / no-react cache (multi-tenant guardrails the hosted service needs, irrelevant for single-repo CI).
• No proprietary react.review URLs in the comment body — branding is react-doctor-flavored (_Reviewed by [react-doctor](https://github.com/millionco/react-doctor) — local CI, no hosted service._).

Definition of done

A consumer adds:

permissions:
  contents: read
  pull-requests: write
  checks: write
  issues: write
steps:
  - uses: actions/checkout@v5
    with: { fetch-depth: 0 }
  - uses: millionco/react-doctor@main

…and on their next PR sees inline comments on net-new violations, a sticky summary with the doctor metrics table, a check run on the head SHA, and resolved threads with ✅ Addressed in <sha> when they push fixes.

Verification

• pnpm typecheck ✓
• pnpm lint ✓
• pnpm format:check ✓
• pnpm test ✓ (existing github-action.test.ts contract test repointed at actions/inspect/action.yml)
• Smoke-tested the entrypoint locally to confirm imports resolve and the missing-event error path is handled gracefully.

  

[reactreview]

Copy as prompt

Check if these React Review issues are valid. If so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.

Run this before and after your changes to verify the result:
npx react-doctor@latest --verbose --diff

Do not modify the react-doctor configuration unless explicitly asked.
Fix the underlying code issues instead of changing or suppressing the rules.

React Review found 0 errors and 5 warnings. This PR leaves the React health score unchanged.

<file name="actions/review/src/pipeline.ts">

<violation number="1" location="actions/review/src/pipeline.ts:207">
Severity: Warning

await inside a for…of loop runs the calls sequentially — for independent operations, collect them and use `await Promise.all(items.map(...))` to run them concurrently

Collect the items and use `await Promise.all(items.map(...))` to run independent operations concurrently

Rule: `async-await-in-loop`
</violation>

<violation number="2" location="actions/review/src/pipeline.ts:225">
Severity: Warning

result.project.sourceFileCount is read 3 times inside this loop — hoist into a const at the top of the loop body

Hoist the deep member access into a const at the top of the loop body: `const { x, y } = obj.deeply.nested`

Rule: `js-cache-property-access`
</violation>

</file>

<file name="actions/review/src/github.ts">

<violation number="1" location="actions/review/src/github.ts:196">
Severity: Warning

await inside a for…of loop runs the calls sequentially — for independent operations, collect them and use `await Promise.all(items.map(...))` to run them concurrently

Collect the items and use `await Promise.all(items.map(...))` to run independent operations concurrently

Rule: `async-await-in-loop`
</violation>

<violation number="2" location="actions/review/src/github.ts:194">
Severity: Warning

array.includes() in a loop is O(n) per call — convert to a Set for O(1) lookups

Use a `Set` or `Map` for repeated membership tests / keyed lookups — `Array.includes`/`find` is O(n) per call

Rule: `js-set-map-lookups`
</violation>

</file>

<file name="actions/review/src/index.ts">

<violation number="1" location="actions/review/src/index.ts:320">
Severity: Warning

.filter().map() iterates the array twice — combine into a single loop with .reduce() or for...of

Combine `.map().filter()` (or similar chains) into a single pass with `.reduce()` or a `for...of` loop to avoid iterating the array twice

Rule: `js-combine-iterations`
</violation>

</file>

^{Reviewed by reactreview for commit 9c44b26. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-doctor-website	Ready	Preview, Comment	May 23, 2026 3:29am

[github-actions]

React Doctor Review

Score: 99/100 - Excellent (unchanged from base)

No new React Doctor regressions in this PR.

Doctor metrics

Project	Directory	Framework	React	Files	Errors	Warnings	Score
website	packages/website	nextjs	19.2.5	17	0	5	99

Reviewed by react-doctor - local CI, no hosted service.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8cc2f23. Configure here.}

[cursor]

Resolves threads when line shifts

Medium Severity

Thread reconciliation treats buildThreadKey as an exact match, including the diagnostic line number. When a push keeps the same rule violation but moves it to another line, the old inline thread’s key no longer appears in the active set, so the action appends “Addressed” and resolves the thread even though the regression still appears in the sticky summary and may get a new inline comment.

Additional Locations (1)

• actions/review/src/index.ts#L318-L338

 

^{Reviewed by Cursor Bugbot for commit 8cc2f23. Configure here.}