---
name: compiler-port
description: Port a compiler pass from TypeScript to Rust. Gathers context, plans the port, implements in a subagent with test-fix loop, then reviews.
---

# Port Compiler Pass

Port a compiler pass from TypeScript to Rust end-to-end.

Arguments:
- $ARGUMENTS: Pass name exactly as it appears in Pipeline.ts log entries (e.g., `PruneMaybeThrows`, `SSA`, `ConstantPropagation`)

## Step 0: Validate pass name

1. Read `compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts`
2. Search for `name: '$ARGUMENTS'` in log entries
3. If not found, list all available pass names from the `log({...name: '...'})` calls and stop
4. Check the `kind` field of the matching log entry:
   - If `kind: 'ast'`, report that test-rust-port only supports `hir` and `reactive` kind passes currently and stop
   - If `kind: 'hir'` or `kind: 'reactive'`, proceed

## Step 1: Determine TS source files and Rust crate

1. Follow the import in Pipeline.ts to find the actual TypeScript file(s) for the pass
2. Map the TS folder to a Rust crate using this mapping:

| TypeScript Path | Rust Crate |
|---|---|
| `src/HIR/` (excluding `BuildHIR.ts`, `HIRBuilder.ts`) | `react_compiler_hir` |
| `src/HIR/BuildHIR.ts`, `src/HIR/HIRBuilder.ts` | `react_compiler_lowering` |
| `src/Babel/`, `src/Entrypoint/` | `react_compiler` |
| `src/CompilerError.ts` | `react_compiler_diagnostics` |
| `src/ReactiveScopes/` | `react_compiler_reactive_scopes` |
| `src/<Name>/` | `react_compiler_<name>` (1:1, e.g., `src/Optimization/` -> `react_compiler_optimization`) |

3. Check if the pass is already ported:
   - Check if the corresponding Rust file exists in the target crate
   - Check if `compiler/crates/react_compiler/src/entrypoint/pipeline.rs` already calls it
   - If both are true, report the pass is already ported and stop

## Step 2: Gather context

Read the following files (all reads happen in main context):

1. **Architecture guide**: `compiler/docs/rust-port/rust-port-architecture.md`
2. **Pass documentation**: Check `compiler/packages/babel-plugin-react-compiler/docs/passes/` for docs about this pass
3. **TypeScript source**: All TypeScript source files for the pass + any helpers imported from the same folder
4. **Rust pipeline**: `compiler/crates/react_compiler/src/entrypoint/pipeline.rs`
5. **Rust HIR types**: Key type files in `compiler/crates/react_compiler_hir/src/` (especially `hir.rs`, `environment.rs`)
6. **Rust reactive types**: For reactive passes, also read `compiler/crates/react_compiler_hir/src/reactive_function.rs`
7. **Target crate**: If the target crate already exists, read its `Cargo.toml`, `src/lib.rs`, and existing files to understand the current structure

## Step 3: Create implementation plan

Based on the gathered context, create and present a plan covering:

1. **New types needed**: Any Rust types that need to be added or modified
2. **Files to create**: List of new Rust files with their TS counterparts
3. **Crate setup**: Whether a new crate is needed or adding to an existing one
4. **Pipeline wiring**: How the pass will be called from `pipeline.rs`
5. **Key translation decisions**: Any non-obvious TS-to-Rust translations

Present the plan to the user, then proceed to implementation.

## Step 4: Implementation

Launch the `port-pass` agent with all gathered context:

- Pass name: `$ARGUMENTS`
- TypeScript source file content(s)
- Target Rust crate name and path
- Pipeline wiring details
- Implementation plan from Step 3
- Architecture guide content
- Current pipeline.rs content
- Existing crate structure (if any)

The agent will:
1. Port the TypeScript code to Rust
2. Create or update the crate as needed
3. Wire the pass into pipeline.rs
4. Run the test-fix loop until 0 failures (see agent prompt for details)

## Step 5: Review loop

1. Run `/compiler-review` on the changes
2. If issues are found:
   - Launch the `port-pass` agent again with:
     - The review findings
     - Instruction to fix the issues
     - Instruction to re-run `bash compiler/scripts/test-rust-port.sh` (no args, auto-detects last ported pass) to confirm 0 failures still hold
   - After the agent completes, run `/compiler-review` again
3. Repeat until review is clean

## Step 6: Final report

Report to the user:
- Files created and modified
- Test results (pass count)
- Review status
- Do NOT auto-commit (user should review and commit manually, or use `/compiler-commit`)