[compiler] Summaries of the compiler passes to assist agents in development

[everettbu]

Mirror of facebook/react#35595
Original author: josephsavona

---

Autogenerated summaries of each of the compiler passes which allow agents to get the key ideas of a compiler pass, including key input/output invariants, without having to reprocess the file each time. In the subsequent diff this seemed to help.

---

Stack created with Sapling. Best reviewed with ReviewStack.

• #35607
• #35298
• #35596
• #35573
• -> #35595
• #35539

[greptile-apps]

Greptile Summary

This PR adds autogenerated documentation for all 55 compiler passes to assist AI agents in understanding the React Compiler architecture without reprocessing files repeatedly. The documentation includes detailed summaries of each pass with input/output invariants, algorithms, edge cases, and examples.

Key additions:

• Created comprehensive documentation for all compiler passes (01-lower.md through 55-validateSourceLocations.md)
• Added top-level README.md with architecture diagram and pass categorization by phase
• Updated compiler/CLAUDE.md to reference the new documentation directory
• Enhanced test runner with autocomplete functionality using Levenshtein distance for better developer experience
• Added fixture status tracking (pass/fail) to help with test debugging

Documentation structure:

Each pass documentation follows a consistent format with sections for:

• File location
• Purpose and role in the pipeline
• Input invariants and output guarantees
• Algorithm description with code examples
• Key data structures
• Edge cases and TODOs
• Real examples from fixtures

The documentation is well-structured and comprehensive, covering the entire compilation pipeline from Babel AST lowering through SSA conversion, optimization, type/effect inference, reactive scope construction, and final code generation.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - it adds comprehensive documentation without modifying any compiler logic
• The changes are purely additive documentation and minor test tooling improvements. No compiler logic is modified, eliminating risk of breaking existing functionality. The documentation is well-structured, comprehensive, and follows a consistent format across all 55 passes.
• No files require special attention - all changes are documentation additions and non-critical test tooling enhancements

Important Files Changed

Filename	Overview
compiler/CLAUDE.md	Added reference to new pass documentation directory
compiler/packages/babel-plugin-react-compiler/docs/passes/README.md	Comprehensive overview of all 55 compiler passes with architecture diagram and pass categorization
compiler/packages/babel-plugin-react-compiler/docs/passes/01-lower.md	Detailed documentation of HIR lowering pass with input/output invariants and examples
compiler/packages/babel-plugin-react-compiler/docs/passes/08-inferMutationAliasingEffects.md	Comprehensive documentation of mutation/aliasing inference with abstract interpretation algorithm
compiler/packages/babel-plugin-react-compiler/docs/passes/31-codegenReactiveFunction.md	Detailed documentation of final codegen pass with memoization structure and cache slot allocation
compiler/packages/babel-plugin-react-compiler/docs/passes/40-validateUseMemo.md	Complete validation rules for useMemo callbacks with error messages and examples
compiler/packages/babel-plugin-react-compiler/docs/passes/41-validateHooksUsage.md	Rules of Hooks validation with abstract interpretation and conditional usage detection
compiler/packages/snap/src/runner-watch.ts	Added autocomplete functionality with Levenshtein distance and fixture status tracking
compiler/packages/snap/src/runner.ts	Added fixture status tracking for pass/fail results

[everettbu]

Upstream PR was closed or merged. Code is synced via branch mirror.