fuzz

# Fuzz rules Use `packages/fuzz` after focused rule tests pass. Read its `README.md` for harness architecture and corpus setup. ## Run the harness Run the target rule first: ```sh FUZZ_RULE=<rule-id> FUZZ_STRICT=1 FUZZ_ITERATIONS=500 nr fuzz ``` Useful variants: ```sh nr fuzz FUZZ_RULE=<rule-id> FUZZ_SEED=42 nr fuzz FUZZ_INVARIANTS=1 nr fuzz FUZZ_CORPUS_DIR=<repository-directory> nr fuzz FUZZ_RULE=<rule-id> FUZZ_PRINT_SILENT=1 nr fuzz ``` Confirm that the target rule fires. A silent rule only exercises early exits. If it stays silent, add a triggering shape to `packages/fuzz/src/snippet-pools.ts` and rerun. Use `FUZZ_TAG=<tag>` instead of `FUZZ_RULE` to exercise an entire registry cohort. Recommended full sweep (e.g. before a rule-batch release), pointing the corpus at real checkouts. Ready-made corpora work on any machine — see the package README "Canonical corpora": `bun scripts/sync-fuzz-corpus.ts` materializes a pinned 48-repo sample (symlinking the RDE cache when present, cloning otherwise), and `bun scripts/build-bench-corpus.ts` extracts react-bench's diagnostic-dense RD-health target files: ```sh cd packages/fuzz bun scripts/sync-fuzz-corpus.ts FUZZ_INVARIANTS=1 FUZZ_ITERATIONS=100 FUZZ_CORPUS_DIR=tmp/corpus-repos nr fuzz ``` Run the direct false-positive check when a rule change affects common syntax: ```sh cd packages/fuzz bun scripts/hunt-false-positives.ts ``` ## Triage findings Reproducers live in `packages/fuzz/tmp/fuzz-findings/`. - **Crash**: minimize the program, add a no-throw regression test, fix the rule, and replay the seed - **Slow case**: profile the pathological shape, bound the walk, and keep the existing threshold - **Verdict drop**: fix detection that depends on incidental syntax, then add the rule to the robustness gate when appropriate - **Invariant violation**: decide whether the rule should react to the rewrite; fix and test unexpected changes - **False positive**: add the valid program to the rule tests and fuzz regression corpus Replay one finding: ```sh FUZZ_RULE=<rule-id> FUZZ_SEED=<seed> FUZZ_ITERATIONS=1 nr fuzz ``` ## Preserve false positives For every confirmed false positive: 1. Add a minimal fixture to `packages/fuzz/corpus/regressions/<rule-id>--<slug>.tsx`. 2. Include the rule ID, weakness class, and source in the fixture header. 3. Add a focused valid case to the rule test suite. 4. Add a generator snippet when the existing pools cannot produce the weakness. 5. Run `nr -C packages/fuzz test` and replay the target rule. Use a stable weakness name such as `library-idiom`, `control-flow`, `wrapper-transparency`, `name-heuristic`, `alias-guard`, `cross-file`, `framework-gating`, `paren-shape`, `default-parameter`, `dynamic-computed`, `private-member`, or `copy-tracking`. Project-level dead-code and dependency findings belong in core tests, not the rule fuzzer. ## Report results Record the command, target-rule fire count, findings, replay seeds, corpus fixtures, and generator changes. Pass confirmed implementation findings to `rule-validate`.