Skip to content

Commit b354bbd

Browse files
authored
[compiler] Update docs with fault tolerance summary, remove planning doc (facebook#35888)
Add concise fault tolerance documentation to CLAUDE.md and the passes README covering error accumulation, tryRecord wrapping, and the distinction between validation vs infrastructure passes. Remove the detailed planning document now that the work is complete.
1 parent c92c579 commit b354bbd

File tree

3 files changed

+23
-348
lines changed

3 files changed

+23
-348
lines changed

compiler/CLAUDE.md

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -229,20 +229,19 @@ Would enable the `enableJsxOutlining` feature and disable the `enableNameAnonymo
229229
3. Look for `Impure`, `Render`, `Capture` effects on instructions
230230
4. Check the pass ordering in Pipeline.ts to understand when effects are populated vs validated
231231

232-
## Error Handling for Unsupported Features
232+
## Error Handling and Fault Tolerance
233233

234-
When the compiler encounters an unsupported but known pattern, use `CompilerError.throwTodo()` instead of `CompilerError.invariant()`. Todo errors cause graceful bailouts in production; Invariant errors are hard failures indicating unexpected/invalid states.
234+
The compiler is fault-tolerant: it runs all passes and accumulates errors on the `Environment` rather than throwing on the first error. This lets users see all compilation errors at once.
235235

236-
```typescript
237-
// Unsupported but expected pattern - graceful bailout
238-
CompilerError.throwTodo({
239-
reason: `Support [description of unsupported feature]`,
240-
loc: terminal.loc,
241-
});
242-
243-
// Invariant is for truly unexpected/invalid states - hard failure
244-
CompilerError.invariant(false, {
245-
reason: `Unexpected [thing]`,
246-
loc: terminal.loc,
247-
});
248-
```
236+
**Recording errors** — Passes record errors via `env.recordError(diagnostic)`. Errors are accumulated on `Environment.#errors` and checked at the end of the pipeline via `env.hasErrors()` / `env.aggregateErrors()`.
237+
238+
**`tryRecord()` wrapper** — In Pipeline.ts, validation passes are wrapped in `env.tryRecord(() => pass(hir))` which catches thrown `CompilerError`s (non-invariant) and records them. Infrastructure/transformation passes are NOT wrapped in `tryRecord()` because later passes depend on their output being structurally valid.
239+
240+
**Error categories:**
241+
- `CompilerError.throwTodo()` — Unsupported but known pattern. Graceful bailout. Can be caught by `tryRecord()`.
242+
- `CompilerError.invariant()` — Truly unexpected/invalid state. Always throws immediately, never caught by `tryRecord()`.
243+
- Non-`CompilerError` exceptions — Always re-thrown.
244+
245+
**Key files:** `Environment.ts` (`recordError`, `tryRecord`, `hasErrors`, `aggregateErrors`), `Pipeline.ts` (pass orchestration), `Program.ts` (`tryCompileFunction` handles the `Result`).
246+
247+
**Test fixtures:** `__tests__/fixtures/compiler/fault-tolerance/` contains multi-error fixtures verifying all errors are reported.

0 commit comments

Comments
 (0)