Code Commits Issues Pulls Sessions CI/CD

main

md 14.1 KB

View source Raw

React Compiler Rust Port — Workflow Guide

Analysis of 141 Claude Code sessions from 2026-03-13 to 2026-04-10, totaling ~17,460 tool invocations across the Rust compiler port.

1. Project Timeline & Phases

Phase	Dates	Focus	Sessions
Research	Mar 13–14	Feasibility study, shared mutability analysis, pass-by-pass research	~10
Planning	Mar 14–16	Architecture docs, numbered plans (0001–0005), scope types	~15
Core Implementation	Mar 16–25	Babel AST crate, HIR lowering, pass porting, BuildHIR	~50
Testing & Stabilization	Mar 25–31	Snap tests, test-rust-port 100%, OXC/SWC frontends	~30
E2E & Diagnostics	Apr 1–4	Error formatting, diagnostic events, CI, e2e tests	~20
Internal Validation	Apr 6–10	Testing against Meta internal code, minimize-rust-delta, hermes-parser	~10

Key Milestones

Mar 25: All 1717/1717 pass-level + code-level tests passing
Mar 30: Snap tests 1717/1718 (99.9%)
Mar 31: OptimizeForSSR ported, snap 1725/1725
Apr 2: E2E babel 1722/1724, diagnostic events aligned
Apr 4: CI workflow configured, SWC/OXC e2e progress
Apr 6–10: Internal codebase validation against Meta internal production code

2. Custom Skills (Claude Code)

Seven custom skills were created in compiler/.claude/skills/. These are critical to the workflow and should be loaded at the start of each session:

Skill	Usage Count	Purpose
`/compiler-verify`	47	Detects TS vs Rust changes, runs appropriate test suites
`/compiler-commit`	30	Runs verify + review, then commits with `[compiler]` or `[rust-compiler]` prefix, updates orchestrator log
`/compiler-review`	21	Launches a review subagent that compares Rust port against TS originals
`/compiler-orchestrator`	5	Autonomous loop: discover frontier → fix failures → port next pass → review → commit
`/compiler-port`	5	Port a single named pass end-to-end (looks up in Pipeline.ts, maps to Rust crate, implements, tests)
`/rust-port-status`	—	Reports current test pass rates
`/plan-update`	—	Updates numbered plan documents

Typical Workflow Loop

1. /compiler-orchestrator (or manual work)
   └── Discovers current test state
   └── Fixes failures or ports next pass
   └── Calls /compiler-verify internally
   └── Calls /compiler-review internally
   └── Calls /compiler-commit when ready

2. Manual variant:
   > "Fix X"
   > /compiler-verify
   > /compiler-review
   > /compiler-commit

Important Skill Loading Note

The /compiler-orchestrator skill sometimes fails to auto-load. The workaround is:

> load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md

This happened multiple times in the trajectory history and your team should be aware of it.

3. Test Commands & Infrastructure

Primary Test Scripts (by frequency of use)

Command	Invocations	Purpose
`bash compiler/scripts/test-rust-port.sh`	1,345	Compare Rust vs TS compiler output per-pass for all fixtures
`bash compiler/scripts/test-e2e.sh`	269	End-to-end: code output + diagnostic events across babel/swc/oxc
`cargo check`	251	Fast Rust compilation check
`npx tsx`	207	Run TypeScript scripts directly
`cargo build`	179	Full Rust build
`bash compiler/scripts/test-babel-ast.sh`	174	Babel AST round-trip serialization tests
`yarn snap --rust`	121	Snap fixture tests using Rust compiler backend
`yarn snap`	63	Snap fixture tests using TS compiler
`cargo test`	46	Rust unit tests

Test Result Formats

test-rust-port.sh supports --json for machine-readable output: ```bash bash compiler/scripts/test-rust-port.sh --json 2>/dev/null

Returns: { pass, autoDetected, total, passed, failed, frontier, perPass, failures }


`test-e2e.sh` reports in table format:

| variant | code | events | total | | babel | 1725/1725 (100%) | 1725/1725 (100%) | ... | | swc | 1723/1725 (99.9%) | ... | ... | ```

Test Against Internal Codebase

Recent work (Apr 6–10) tested against Meta internal production code. Key patterns:

# Run with specific compilation mode against an external directory
bash compiler/scripts/test-rust-port.sh --mode syntax <path-to-source-dir>

# Use test-internal-files.sh with the production config and source root
bash compiler/scripts/test-internal-files.sh <config-path> <source-root> [flags]

Files with @flow need hermes-parser (recently added to test-rust-port.ts)
Must pass compilationMode to match production config
Use yarn snap minimize-rust-delta <path> to find minimal repro for TS/Rust differences

4. Cargo & Rust Workflow

Crate Structure

Crate	Purpose
`react_compiler`	Main entrypoint, pipeline orchestration
`react_compiler_ast`	Babel AST types + serde
`react_compiler_hir`	HIR types, environment, visitors
`react_compiler_lowering`	BuildHIR, HIRBuilder (AST → HIR)
`react_compiler_inference`	Mutation/aliasing/type inference
`react_compiler_optimization`	Optimization passes
`react_compiler_validation`	Validation passes
`react_compiler_reactive_scopes`	Reactive scope building + codegen
`react_compiler_diagnostics`	Error types, code frames
`react_compiler_e2e_cli`	E2E test binary
`react_compiler_swc`	SWC frontend
`react_compiler_oxc`	OXC frontend

Common Cargo Patterns

# Fast check (most common, 214 invocations)
cargo check --manifest-path compiler/crates/Cargo.toml

# Build the NAPI binary for JS interop
cargo build --manifest-path compiler/crates/Cargo.toml

# Run Rust unit tests
cargo test --manifest-path compiler/crates/Cargo.toml

5. Agent Patterns

994 total agent invocations across sessions.

Agent Type	Count	Typical Use
`general` / `general-purpose`	748	Implementation, fixing, research
`meta_codesearch:code_search`	204	Codebase exploration
`Plan`	20	Architecture/implementation planning
`Explore`	16	Codebase navigation
`statusline-setup`	4	Terminal UI configuration

Common Agent Patterns

Parallel pass research: Launch one agent per compiler pass to analyze TS implementation for port feasibility
Review agents: Dedicated "Review Rust port changes" agents (14 invocations)
Fix-specific agents: "Fix AnalyseFunctions failures" (4x), "Fix PruneMaybeThrows validation failures" (2x)
Worktree isolation: 16 worktree entries for isolated implementation work

Worktree Usage

Worktrees were used for larger changes that might need to be abandoned: - worktree-build-hir-impl — BuildHIR implementation - worktree-structured-yawning-forest-rust — test-rust-port enhancements - worktree-ts-to-rust-transpiler — explored mechanical TS→Rust transpilation (abandoned) - worktree-module-type-provider — module type provider work

6. Key Files (by edit frequency)

Most Frequently Modified Files

File	Edits	Reads	Purpose
`rust-port-orchestrator-log.md`	135	104	Running log of orchestrator progress
`build_hir.rs`	112	162	Core HIR lowering from AST
`program.rs` (entrypoint)	103	173	Main compilation entrypoint
`rust-port-research.md`	85	47+21	Research & analysis document
`test-rust-port.ts`	77	90	Primary test comparison script
`pipeline.rs`	48	64	Compiler pass pipeline
`test-e2e.ts`	42	27	End-to-end test script
`hir_builder.rs`	37	53	HIR builder utilities
`infer_mutation_aliasing_effects.rs`	32	48	Most complex inference pass
`runner.ts` (snap)	32	35	Snap test runner

7. Repeated Workflow Patterns

Pattern 1: "Analyze → Don't Fix → Report"

Used extensively in recent internal validation work: ```

Try running test-rust-port.sh with --mode 'syntax' against . Analyze success/failure to categorize and report back. Do not proactively fix. ```

Pattern 2: "Research → Plan → Implement → Verify → Review → Commit"

The standard development cycle: ```

Do additional research into Create a plan in compiler/docs/rust-port/... Implement the work in /compiler-verify /compiler-review /compiler-commit ```

Pattern 3: "Team of Agents"

For large implementation tasks: ```

Use a team of agents (opus) to implement the remainder of the items in . Make sure to thoroughly test, verify the implementation against the plan. Use /compiler-verify and /compiler-commit. ```

Pattern 4: "Orchestrator Loop"

For autonomous progress: ```

/compiler-orchestrator (or: load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md) ```

Pattern 5: "Debug CI"

> debug the GitHub CI failure run at <github-actions-url>
> <paste error output>
> /compiler-commit

Pattern 6: "Minimize Delta"

For finding minimal repros of TS/Rust differences: ```

yarn snap minimize-rust-delta ```

Pattern 7: "Interrupt and Redirect"

Joe frequently interrupts Claude mid-task to correct course: - [Request interrupted by user] appears ~50+ times - Common pattern: interrupt → provide specific guidance → continue - Example: "you should be using env.record_error(...)?."

8. Key Architectural Decisions (from trajectory)

These came up repeatedly in prompts and are important context:

InstructionId over InstructionValue references: Key insight that caches in InferMutationAliasingEffects can use InstructionId (interned) instead of holding references to InstructionValue objects, avoiding Rust borrow conflicts.
Environment is shared mutable: Like HIR, the Environment object is mutably shared. Both needed careful Rust representation.
Error handling convention: env.record_error(...)? — record_error returns Err only for Invariant category errors. Use ? for short-circuit. Only use let _ = ... when both the category is non-Invariant AND you explicitly want to continue.
Keep logic in Rust core: The babel/swc/oxc integrations should be thin wrappers. All interesting logic belongs in the Rust crates.
Commit prefix convention: [rust-compiler] for changes to compiler/crates/, [compiler] for everything else.
No normalization in tests: Minimize output normalization — run code through prettier only, compare directly. Added: reparse with babel → regenerate with compact:true → prettier.

9. Current State & Remaining Work

Test Results (as of latest orchestrator log)

test-rust-port: 1724/1724 (100%)
yarn snap --rust: 1725/1725 (100%)
E2E babel: 1722/1724 (2 inherent platform differences)
E2E swc: Partial — event matching in progress
E2E oxc: Partial — event matching in progress

Active Work Streams (as of Apr 10)

Internal validation: Testing against Meta internal production code with production configs
Minimize rust deltas: Using yarn snap minimize-rust-delta to find minimal repro cases for TS/Rust differences
New test-internal-files script: compiler/scripts/test-internal-files.ts — for testing against an external codebase with its production config
compilationMode: 'syntax' support was recently added and validated
hermes-parser integration: For @flow files in the internal codebase

Remaining Gaps

SWC/OXC e2e event differences (structural, not code)
Some internal codebase fixtures still show code differences between TS and Rust
Internal skip list exists at compiler/.test-internal-skip-list
Performance optimization: potential for returning per-function replacements instead of full program

10. Recommendations for Team Picking Up

Getting Started

Read compiler/docs/rust-port/rust-port-research.md and rust-port-notes.md for architectural context
Read all numbered plans in compiler/docs/rust-port/rust-port-0001-* through 0005-*
Review compiler/docs/rust-port/rust-port-orchestrator-log.md for chronological progress
Review compiler/docs/rust-port/rust-port-gap-analysis.md for known gaps

Essential Skill Loading

At the start of each Claude session: ```

load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md ``` This ensures all six custom skills are available. If a skill isn't recognized, load it explicitly.

Daily Workflow

# Check current state
bash compiler/scripts/test-rust-port.sh
bash compiler/scripts/test-e2e.sh
yarn snap --rust

# After making changes
/compiler-verify
/compiler-review
/compiler-commit <title>

Key Commands to Know

# Fast iteration cycle
cargo check --manifest-path compiler/crates/Cargo.toml
bash compiler/scripts/test-rust-port.sh
yarn snap --rust

# Debug a specific fixture
yarn snap --rust -p <fixture-name> -d

# Compare TS vs Rust for a specific file
npx tsx compiler/scripts/test-rust-port.ts <pass-name>

# Find minimal repro for TS/Rust difference
yarn snap minimize-rust-delta <fixture-path>

# Test against an external codebase with its production config
bash compiler/scripts/test-internal-files.sh <config-path> <source-root> [flags]

# E2E test across all frontends
bash compiler/scripts/test-e2e.sh

Working Style Notes

Joe used Opus 4.6 as the primary model throughout
Frequent use of /clear between logical work units
Heavy use of "analyze and report, don't fix" for investigation phases
Corrections were provided inline with specific code patterns (e.g., "you should be using env.record_error(...)?")
Plans were maintained in numbered markdown docs and updated as work progressed
The orchestrator log (rust-port-orchestrator-log.md) serves as the canonical progress record

CI Configuration

GitHub CI workflow: .github/workflows/compiler_rust.yml - Triggers on changes to compiler/ directory - Runs: cargo check → cargo build → test-babel-ast.sh → test-rust-port.sh → yarn snap --rust - Job name appears as "React Compiler (Rust) Tests" in GitHub

Generated 2026-04-10 from analysis of 141 Claude Code conversation trajectories.

#React Compiler Rust Port — Workflow Guide

#1. Project Timeline & Phases

#Key Milestones

#2. Custom Skills (Claude Code)

#Typical Workflow Loop

#Important Skill Loading Note

#3. Test Commands & Infrastructure

#Primary Test Scripts (by frequency of use)

#Test Result Formats

#Returns: { pass, autoDetected, total, passed, failed, frontier, perPass, failures }

#Test Against Internal Codebase

#4. Cargo & Rust Workflow

#Crate Structure

#Common Cargo Patterns

#5. Agent Patterns

#Common Agent Patterns

#Worktree Usage

#6. Key Files (by edit frequency)

#Most Frequently Modified Files

#7. Repeated Workflow Patterns

#Pattern 1: "Analyze → Don't Fix → Report"

#Pattern 2: "Research → Plan → Implement → Verify → Review → Commit"

#Pattern 3: "Team of Agents"

#Pattern 4: "Orchestrator Loop"

#Pattern 5: "Debug CI"

#Pattern 6: "Minimize Delta"

#Pattern 7: "Interrupt and Redirect"

#8. Key Architectural Decisions (from trajectory)

#9. Current State & Remaining Work

#Test Results (as of latest orchestrator log)

#Active Work Streams (as of Apr 10)

#Remaining Gaps

#10. Recommendations for Team Picking Up

#Getting Started

#Essential Skill Loading

#Daily Workflow

#Key Commands to Know

#Working Style Notes

#CI Configuration