feat: add --show-errors flag to show detailed compiler errors

[frankieyan]

When React Compiler errors increase, the current output only shows counts like src/bad-hook.ts: +3. This makes it hard to know what actually broke. The new --show-errors flag displays the exact violation messages and line numbers:

❌ React Compiler errors have increased in:
  • src/bad-hook.ts: +3

Detailed errors:
    - src/bad-hook.ts: Line 6: Cannot access refs during render

Test plan

Test locally by running against the sample project fixtures:

npm run build
cd src/__fixtures__/sample-project

• Without --show-errors (baseline behavior) — shows only error counts

  node ../../../dist/index.mjs --check-files src/bad-hook.ts

  🔍 Checking 1 file for React Compiler errors…
  ❌ React Compiler errors have increased in:
    • src/bad-hook.ts: +3
  
  Please fix the errors and run the command again.
  

• With --show-errors — includes detailed error messages

  node ../../../dist/index.mjs --check-files --show-errors src/bad-hook.ts

  🔍 Checking 1 file for React Compiler errors…
  ❌ React Compiler errors have increased in:
    • src/bad-hook.ts: +3
  
  Detailed errors:
      - src/bad-hook.ts: Line 6: Cannot access refs during render
      - src/bad-hook.ts: Line 6: Cannot access refs during render
      - src/bad-hook.ts: Line 6: Cannot access refs during render
  
  Please fix the errors and run the command again.
  

• Multiple files — shows errors from all files

  node ../../../dist/index.mjs --check-files --show-errors src/bad-hook.ts src/bad-component.tsx

  🔍 Checking 2 files for React Compiler errors…
  ❌ React Compiler errors have increased in:
    • src/bad-hook.ts: +3
    • src/bad-component.tsx: +1
  
  Detailed errors:
      - src/bad-hook.ts: Line 6: Cannot access refs during render
      - src/bad-hook.ts: Line 6: Cannot access refs during render
      - src/bad-hook.ts: Line 6: Cannot access refs during render
      - src/bad-component.tsx: Line 6: Hooks must always be called in a consistent order...
  
  Please fix the errors and run the command again.
  

• Files with no errors — no detailed errors section shown

  node ../../../dist/index.mjs --check-files --show-errors src/good-component.tsx

  🔍 Checking 1 file for React Compiler errors…
  ✅ No new React Compiler errors in checked files
  

• Flag position flexibility — --show-errors works anywhere in the command

  node ../../../dist/index.mjs --show-errors --check-files src/bad-hook.ts
  node ../../../dist/index.mjs --check-files --show-errors src/bad-hook.ts
  node ../../../dist/index.mjs --check-files src/bad-hook.ts --show-errors

• Similarly, --show-errors can be used together with other flags like --overwrite, --stage-record-file, or when no mode flag is set

[doistbot-app]

The PR successfully implements the --show-errors flag, including robust argument parsing and integration with the React Compiler logger. The changes are well-tested and preserve existing default behaviors.

[doistbot-app]

[P3] String(event.data) may result in [object Object] if PipelineError carries an object payload. Consider checking if event.data is an Error instance to use its .message, or using JSON.stringify for generic objects, to ensure the detailed error message is actionable.

[gnapse]

I did not get to this on time. Please re-roll the dice.

[engfragui]

💭 (Out of my curiosity/for my own understanding) @frankieyan Do you plan to use this flag in todoist-web (and other relevant repos) by default, right? It shouldn't be up to the developer to run the command with the new flag, but it should happen by default, correct? 🙏

[engfragui]

🔍 Checking 1 file for React Compiler errors…
❌ React Compiler errors have increased in:
• src/bad-hook.ts: +3

Detailed errors:
- src/bad-hook.ts: Line 6: Cannot access refs during render
- src/bad-hook.ts: Line 6: Cannot access refs during render
- src/bad-hook.ts: Line 6: Cannot access refs during render

Please fix the errors and run the command again.

💭 (Not related to this PR specifically, but I'll note it regardless) It seems to me that, for this specific file, it'd make more sense (ideally) to output the "Cannot access refs during render" error only once (+1) instead of 3 times (since it's the same error, on the same line number, etc.), right?
Not sure how tricky/how worth it it would be, since it's not really a deal-breaker or anything 😅

[engfragui]

💭 I think the code and the unit tests provide enough "self-documentation", so very option to add the --show-errors to the README file.

[frankieyan]

Do you plan to use this flag in todoist-web (and other relevant repos) by default, right? It shouldn't be up to the developer to run the command with the new flag, but it should happen by default, correct?

IMO by default (for our pre-commit and CI hooks), we don't need to show the exact errors, but this would be helpful for LLMs when planning what to fix. Despite having the records file and being able to run Babel to extract the exact errors, I found that it goes off on fixes that don't actually target the violations.

I'll update this section of the docs to reference this flag and hopefully we'll have better results.

it'd make more sense (ideally) to output the "Cannot access refs during render" error only once (+1) instead of 3 times (since it's the same error, on the same line number, etc.), right?

That was bugging me a bit too, but wasn't enough for me to fix it. I'll throw this at my robot helper now that we have real user (i.e. you) feedback about this 😁

Thank you for the reminder about the readme too. Slipped my mind but I'll add it now 🙌