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:

FUZZ_RULE=<rule-id> FUZZ_STRICT=1 FUZZ_ITERATIONS=500 nr fuzz

Useful variants:

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:

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:

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:

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.