AGENTS.md
GitHubWakaru
Wakaru is a JavaScript decompiler that transforms minified/bundled code back into readable, modern ESNext. It unpacks bundles (webpack4, webpack5, browserify, SystemJS, esbuild/Bun, AMD, plus heuristic scope-hoisted splitting), restores transpiler helpers (Babel, TypeScript), and applies an ordered pipeline of rewrite rules to recover idiomatic source (the registry in crates/core/src/rules/pipeline.rs is the authoritative list). It can also experimentally recover Vue 3 SFC-like artifacts from compiled render modules (--vue-sfc).
Written in Rust using the SWC AST ecosystem. The workspace is split into four crates under crates/: core, cli, formatter, and wasm.
Understand the Project
Read docs/architecture.md first — pipeline flow, components, design
patterns. It is the universal entry point. Then read by task, instead of
reading everything:
| Task | Also read |
|---|---|
| Any code change | docs/testing.md — test patterns, helpers, required verification |
| Rule bugfix / snapshot regression | docs/debugging.md — rule tracing, snapshot layers, fixture workflow |
| New rule, or moving a rule | docs/rule-dependency-inventory.md — ordering rationale, fragile edges; docs/rewrite-assumptions.md — level gating, named assumptions |
| Transpiler helper work | docs/helper-detection.md — detection design and what was already rejected |
| Cross-module / unpack behavior | docs/fact-system.md — the two-phase barrier and module facts |
Vue SFC recovery (--vue-sfc) |
docs/vue-decompile.md — the recovery path and CLI behavior; docs/vue-sfc-recovery-status.md — experimental status and known gaps |
| Correctness / semantics questions | docs/rewrite-assumptions.md, docs/test262-roundtrip.md |
| Before proposing a redesign | docs/learnings/ — approaches already built, measured, and reverted |
| CLI flag or output changes | docs/cli.md — the user-facing CLI reference; SKILL.md — the agent skill (keep both in sync) |
| Agent / tool integration | SKILL.md — CLI-based agent surface |
| Cutting a release | docs/releasing.md |
docs/README.md carries this same map for agents and tools that do not
auto-load this file.
Building and Running
All cargo commands run from the repo root.
cargo build # debug build
cargo run -p wakaru-cli -- input.js -o output.js # decompile single file
cargo run -p wakaru-cli -- --unpack bundle.js -o unpacked/ # unpack bundle
cargo run -p wakaru-cli -- --unpack --raw bundle.js -o raw/ # raw extraction (no rules)
cargo run -p wakaru-cli -- input.js -m input.js.map # with source map
cargo run -p wakaru-cli -- debug trace path/to/module.js # debug: per-rule diffs
Branch worktrees live as sibling checkouts at ../wakaru-<branch-suffix>
(e.g. ../wakaru-repro-edge-cases for branch codex/repro-edge-cases).
Run git worktree list before creating one — it usually already exists.
Testing
cargo nextest run -p wakaru-core # full core suite (~25x faster than cargo test)
cargo nextest run --workspace # everything
cargo test -p wakaru-core --test my_rule_rule # one test file
cargo test -p wakaru-core --test smart_inline_rule -- inline_single_use # one test
cargo fmt --check # verify Rust formatting
cargo clippy -p wakaru-core --all-targets -- -D warnings # lint core changes
The full suite runs much faster under nextest (one global
parallel pool vs. cargo test's sequential per-binary runs). Install once with
cargo install cargo-nextest --locked (or curl -LsSf https://get.nexte.st/latest/<os> | tar zxf - -C $HOME/.cargo/bin).
cargo test still works for everything; nextest does not run doctests (there
are none today — use cargo test --doc if that changes).
Snapshot drift fails the test and writes a .snap.new (via INSTA_UPDATE=new
in .cargo/config.toml). Review the diff, then accept intentional changes with
cargo insta accept (or INSTA_UPDATE=always cargo test for a one-off bulk accept).
See docs/testing.md for test helpers, patterns, and organization.
Developing a Rule
Every change needs a unit test
No code change is committed without a corresponding unit test. Pipeline snapshot updates alone are not sufficient — they test the whole pipeline, not the individual change.
Write tests before implementation when the input→output is known:
- Create
crates/core/tests/my_rule_rule.rswith failing test cases - Implement
crates/core/src/rules/my_rule.rsuntil tests pass - Run pipeline tests to check for regressions
For bugfixes to existing rules: add a regression test that reproduces the exact bug.
Adding a new rule
- Create
crates/core/tests/my_rule_rule.rswith test cases (they will fail) - Create
crates/core/src/rules/my_rule.rsimplementing SWC'sVisitMuttrait - Add
mod my_rule;andpub use my_rule::MyRule;incrates/core/src/rules/mod.rs - Add a
RuleDescriptorfor the rule at the right position incrates/core/src/rules/pipeline.rs - Run tests until all pass
Where to place it in the pipeline
Rules run in a fixed order. Check crates/core/src/rules/pipeline.rs and place your rule where its dependencies are satisfied:
- Needs
["default"]normalized to.default? Place afterUnBracketNotation - Needs
require()calls present? Place beforeUnEsm - Creates new IIFEs? Place before the second
UnIifepass - Needs alias var declarations intact? Place before
SmartInline(it removesvar h = p) - Needs export specifiers to reference real bindings? Place after
SmartInline
Constructing declarations
If your rule builds a VarDecl and runs before VarDeclToLetConst, carry the
declaration kind of the statements you consumed (or var) — never hardcode
const/let. VarDeclToLetConst decides mutability late with full write
analysis, and it never widens an existing const, so a hardcoded const on a
binding that is later reassigned becomes a runtime TypeError.
Scope-aware identifier matching
If your rule matches identifiers by name, you must check SyntaxContext to avoid matching the wrong binding:
if id.ctxt.outer() != self.unresolved_mark {
return;
}
Every new visitor that matches identifiers by name must take unresolved_mark: Mark and gate on it. See docs/architecture.md for details.
Renaming identifiers
Always use rename_utils::BindingRenamer (via rename_bindings_in_module or rename_bindings). Never write a custom VisitMut that renames by sym alone — it will hit inner-scope locals and parameters with the same name.
Definition of Done
- Run the focused rule tests you touched
- Run the full core suite (covers all pipeline + unpack snapshot tests):
cargo nextest run -p wakaru-core
- If you changed a rule that a reproduction matrix covers (see
scripts/repro/), verify the recovery-rate baseline:node scripts/repro/collect-stats.mjs --check- If rates deliberately moved, regenerate without
--checkand commit thestats.jsondiff with the change - The
commit/datefields instats.jsonare provenance from regeneration time (typically the parent of the commit carrying the diff);--checkcompares only the measured numbers
- Run formatting and lint checks:
cargo fmt --checkcargo clippy -p wakaru-core --all-targets -- -D warningsfor core/rule changes- Use the relevant package or
cargo clippy --workspace --all-targets -- -D warningswhen touching other crates or shared workspace code
- If snapshots change, inspect the diff — confirm the output is semantically better, not just different
- If your change makes any statement in
docs/(or this file) false, fix the doc in the same commit — agents trust the docs, so a wrong doc is worse than a missing one git status --short— no stale.snap.newfiles or unrelated changes
Important Rules
- All changes must be tested — no exceptions.
- Always check
SyntaxContext— rules matching identifiers by name must guard onunresolved_mark. - Use
BindingRenamerfor renames — never rename bysymalone. - Formatting must pass, but don't format opportunistically — run
cargo fmt --check; if formatting is needed, keep it limited to files you intentionally changed and avoid unrelated rustfmt churn. - Inspect snapshot diffs — "different" without "better" is a regression.
- Be honest about what works — never overstate what was accomplished.
Code Review Self-Check
- Before making a non-obvious choice, ask "why this and not the alternative?" Research until you can answer.
- If neighboring code does something differently, find out why before deviating — its choices are often load-bearing.
- Don't take a bug report's suggested fix at face value; verify it's the right layer.
- Use
render_pipeline_until()ordebug traceto verify the AST shape reaching your rule.