luthersystems/elps / .claude/skills/fuzz
fuzz
Verified/fuzz — Native Go Fuzzing Skill
Runs the repository's go test -fuzz targets, adds new ones, and triages
crashers. CI runs .github/workflows/fuzz.yml: 30s per target on PRs, 10m per
target nightly, sharded.
Trigger
Use when asked to fuzz, add or change a fuzz target, investigate a fuzz CI
failure, or triage a file under some package's testdata/fuzz/<Target>/.
Run
make fuzz-list # authoritative list of targets (discovered with go test -list)
make fuzz # every target, 30s each (the PR budget)
make fuzz FUZZTIME=10m # the nightly budget
make fuzz FUZZ_PKGS=./parser/rdparser/... # one package
go test -run='^$' -fuzz='^FuzzEval$' -fuzztime=60s ./lisp/ # one target by hand
scripts/fuzz.sh refuses to run without a parsable FUZZTIME and caps every
invocation with a hard -timeout; never write a -fuzz invocation without
-fuzztime (CI checks for that). FUZZ_TAGS=elpscheck fuzzes the tagged
build, whose targets are otherwise invisible.
Plain go test ./... (and so make test) replays every committed seed and
crasher in testdata/fuzz/ as a regression case.
Triage a crasher
- Find it:
go test -fuzzwritestestdata/fuzz/<Target>/<hash>in the target's package; CI uploads the same file as an artifact. - Reproduce without fuzzing:
go test -run='^<Target>$/^<hash>$' ./<pkg>/. - Classify: a real defect in the code under test, a harness defect (budget
too small for a terminating program, a watchdog on wall clock), or a
toolchain race.
make fuzz-classify-testcovers howscripts/fuzz.shreports each; read its output before assuming the product is at fault. - Fix the root cause with a focused regression test, and commit the
crasher file so
go testkeeps replaying it.
Add a target
- Put it in the package's
fuzz_test.go(or<area>_fuzz_test.go), namedFuzzXxx. Discovery is automatic — there is no registration table. - Seed from
internal/fuzzseed(All(),LispSources(),Adversarial(),Pathological()) plus target-specific adversarial input. - Assert a property with teeth (round-trip equality, no internal panic, termination), not merely "did not crash".
- Any termination watchdog must use
internal/fuzzwatch(scheduled-time budget, with a floor enforced by its call-site guard test), not a baretime.After. - Run
make fuzz-budget-check: each new target adds aFUZZTIMEto the nightly sweep, and the check derives whetherfuzz.yml'stimeout-minutesstill holds. Follow its printed options rather than raising the timeout by hand. - After touching
scripts/fuzz.shorfuzz.yml, runmake ci-gates-testandmake fuzz-classify-test.
Hazards that are load-bearing
Read the header comment of the target before changing it; these are the condensed reasons.
- Evaluator (
lisp.FuzzEval,lisp/eval_fuzz_test.go) — evaluation is Turing-complete andgo test -fuzzhas no per-input deadline, so every evaluation runs under explicit budgets (WithMaxSteps,WithMaxTailIterations,WithMaximumPhysicalStackHeight,WithMaxAlloc, a context deadline) plus a watchdog.env.evalrecovers Go panics into an ordinary-looking*LVal, so the real assertion islisp.IsInternalPanic(result) == false. Eval seeds are executed, sointernal/fuzzseed/evalseed.gois hand-written and does not seed fromLispSources(). Seeds are split:EvalRunawaymust error (a budget stopping an infinite loop is correct) andEvalTerminatingmust complete without error (a bounded program tripping a budget is a defect). - Debugger (
lisp/x/debugger.FuzzDebugEval) — attaching a debugger disables tail-call optimisation and stampsMacroExpansionInfoonto macro-expanded nodes, so it is a different eval path fromFuzzEval's. - Language server (
lsp.FuzzLSPSession,lsp/lsp_fuzz_test.go) — a fuzzer-chosen sequence of requests against fuzzer-chosen documents and cursor positions; the only target that reachesanalysis/andlint/. The server has four blanketrecover()s, so "no crash" means nothing until they are accounted for; the header documents which are neutralised, which is detected, and which is not covered.
Checklist
- Target asserts a real property, with budgets and a
fuzzwatchwatchdog if it evaluates - Seeds come from
internal/fuzzseed -
make fuzz-budget-checkpasses after adding a target - Crasher fixed at the root cause and its
testdata/fuzz/file committed -
make testpasses (replays the corpus)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |