| 1 | --- |
| 2 | name: compiler-port |
| 3 | description: Port a compiler pass from TypeScript to Rust. Gathers context, plans the port, implements in a subagent with test-fix loop, then reviews. |
| 4 | --- |
| 5 | |
| 6 | # Port Compiler Pass |
| 7 | |
| 8 | Port a compiler pass from TypeScript to Rust end-to-end. |
| 9 | |
| 10 | Arguments: |
| 11 | - $ARGUMENTS: Pass name exactly as it appears in Pipeline.ts log entries (e.g., `PruneMaybeThrows`, `SSA`, `ConstantPropagation`) |
| 12 | |
| 13 | ## Step 0: Validate pass name |
| 14 | |
| 15 | 1. Read `compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts` |
| 16 | 2. Search for `name: '$ARGUMENTS'` in log entries |
| 17 | 3. If not found, list all available pass names from the `log({...name: '...'})` calls and stop |
| 18 | 4. Check the `kind` field of the matching log entry: |
| 19 | - If `kind: 'ast'`, report that test-rust-port only supports `hir` and `reactive` kind passes currently and stop |
| 20 | - If `kind: 'hir'` or `kind: 'reactive'`, proceed |
| 21 | |
| 22 | ## Step 1: Determine TS source files and Rust crate |
| 23 | |
| 24 | 1. Follow the import in Pipeline.ts to find the actual TypeScript file(s) for the pass |
| 25 | 2. Map the TS folder to a Rust crate using this mapping: |
| 26 | |
| 27 | | TypeScript Path | Rust Crate | |
| 28 | |---|---| |
| 29 | | `src/HIR/` (excluding `BuildHIR.ts`, `HIRBuilder.ts`) | `react_compiler_hir` | |
| 30 | | `src/HIR/BuildHIR.ts`, `src/HIR/HIRBuilder.ts` | `react_compiler_lowering` | |
| 31 | | `src/Babel/`, `src/Entrypoint/` | `react_compiler` | |
| 32 | | `src/CompilerError.ts` | `react_compiler_diagnostics` | |
| 33 | | `src/ReactiveScopes/` | `react_compiler_reactive_scopes` | |
| 34 | | `src/<Name>/` | `react_compiler_<name>` (1:1, e.g., `src/Optimization/` -> `react_compiler_optimization`) | |
| 35 | |
| 36 | 3. Check if the pass is already ported: |
| 37 | - Check if the corresponding Rust file exists in the target crate |
| 38 | - Check if `compiler/crates/react_compiler/src/entrypoint/pipeline.rs` already calls it |
| 39 | - If both are true, report the pass is already ported and stop |
| 40 | |
| 41 | ## Step 2: Gather context |
| 42 | |
| 43 | Read the following files (all reads happen in main context): |
| 44 | |
| 45 | 1. **Architecture guide**: `compiler/docs/rust-port/rust-port-architecture.md` |
| 46 | 2. **Pass documentation**: Check `compiler/packages/babel-plugin-react-compiler/docs/passes/` for docs about this pass |
| 47 | 3. **TypeScript source**: All TypeScript source files for the pass + any helpers imported from the same folder |
| 48 | 4. **Rust pipeline**: `compiler/crates/react_compiler/src/entrypoint/pipeline.rs` |
| 49 | 5. **Rust HIR types**: Key type files in `compiler/crates/react_compiler_hir/src/` (especially `hir.rs`, `environment.rs`) |
| 50 | 6. **Rust reactive types**: For reactive passes, also read `compiler/crates/react_compiler_hir/src/reactive_function.rs` |
| 51 | 7. **Target crate**: If the target crate already exists, read its `Cargo.toml`, `src/lib.rs`, and existing files to understand the current structure |
| 52 | |
| 53 | ## Step 3: Create implementation plan |
| 54 | |
| 55 | Based on the gathered context, create and present a plan covering: |
| 56 | |
| 57 | 1. **New types needed**: Any Rust types that need to be added or modified |
| 58 | 2. **Files to create**: List of new Rust files with their TS counterparts |
| 59 | 3. **Crate setup**: Whether a new crate is needed or adding to an existing one |
| 60 | 4. **Pipeline wiring**: How the pass will be called from `pipeline.rs` |
| 61 | 5. **Key translation decisions**: Any non-obvious TS-to-Rust translations |
| 62 | |
| 63 | Present the plan to the user, then proceed to implementation. |
| 64 | |
| 65 | ## Step 4: Implementation |
| 66 | |
| 67 | Launch the `port-pass` agent with all gathered context: |
| 68 | |
| 69 | - Pass name: `$ARGUMENTS` |
| 70 | - TypeScript source file content(s) |
| 71 | - Target Rust crate name and path |
| 72 | - Pipeline wiring details |
| 73 | - Implementation plan from Step 3 |
| 74 | - Architecture guide content |
| 75 | - Current pipeline.rs content |
| 76 | - Existing crate structure (if any) |
| 77 | |
| 78 | The agent will: |
| 79 | 1. Port the TypeScript code to Rust |
| 80 | 2. Create or update the crate as needed |
| 81 | 3. Wire the pass into pipeline.rs |
| 82 | 4. Run the test-fix loop until 0 failures (see agent prompt for details) |
| 83 | |
| 84 | ## Step 5: Review loop |
| 85 | |
| 86 | 1. Run `/compiler-review` on the changes |
| 87 | 2. If issues are found: |
| 88 | - Launch the `port-pass` agent again with: |
| 89 | - The review findings |
| 90 | - Instruction to fix the issues |
| 91 | - Instruction to re-run `bash compiler/scripts/test-rust-port.sh` (no args, auto-detects last ported pass) to confirm 0 failures still hold |
| 92 | - After the agent completes, run `/compiler-review` again |
| 93 | 3. Repeat until review is clean |
| 94 | |
| 95 | ## Step 6: Final report |
| 96 | |
| 97 | Report to the user: |
| 98 | - Files created and modified |
| 99 | - Test results (pass count) |
| 100 | - Review status |
| 101 | - Do NOT auto-commit (user should review and commit manually, or use `/compiler-commit`) |