docs/helper-detection.md
GitHubHelper Detection Design
Before proposing a generic matcher to "reduce the LOC" here, read learnings/helper-detection-pattern-engine.md. Replacing bespoke detection with a corpus matcher / ast-grep-style DSL / skeleton-pattern engine was built, measured against real bundles, and reverted: ~93% of detection is marker-based or stateful and can't be expressed as a fixed pattern, and the migratable remainder is too small for a shared engine to pay off. The size is the cost of the problem, not a missing abstraction. Keep matchers bespoke.
Design notes for detecting and restoring transpiler runtime helpers in wakaru. See architecture.md for overall pipeline structure and rule-dependency-inventory.md for where helper rules sit in the pipeline ordering.
Problem
Transpilers (Babel, TypeScript/tslib, SWC) inject runtime helper functions to polyfill modern syntax for older targets. In bundled output, these helpers appear in several forms:
- Imported from a runtime package —
require("@babel/runtime/helpers/interopRequireDefault")orimport _extends from "@babel/runtime/helpers/extends" - Inlined at the top of each module — the function body is copied directly, no import
- Hoisted into a shared webpack module — accessed via numeric
require(42), name lost entirely - Minified — parameter and function names are mangled, but the body structure is preserved
The TS wakaru handles case 1 (match by import path) and case 3 (top level declaration, matching with regex). Rust wakaru should handle all four.
Approach: match by function body shape
Instead of matching import paths or function names, detect helpers by their AST structure (ignoring variable names). This naturally handles all four cases above.
Example — interopRequireDefault across transpilers and minifiers:
// Babel 7
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
// SWC
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
// Minified
function(e) { return e && e.__esModule ? e : { default: e }; }
The essential shape is always: single param, conditional on __esModule, returns {default: param}. A matcher checks these structural properties and ignores names.
What we decided NOT to do
These ideas were explored and rejected:
Custom IR layer — SWC's AST is already high-level (has CallExpr, AwaitExpr, YieldExpr, etc.). A second IR would duplicate representation and debugging cost without solving the actual problems. We already do generator-to-async restoration directly on SWC AST in
un_async_await.rs.CFG hashing / structural fingerprints — Sounds appealing but fragile in practice. Small codegen/minifier changes scramble naive hashes, and stable canonicalization is the hard part (not storing the graph). Overkill for functions that are typically 1-5 lines.
Version auto-detect via runtime strings — Bundled code often strips version markers, and inlined helpers erase them entirely. Designing around version gating would fail on real-world bundles.
Configurable pass graphs / incremental re-analysis — Premature optimization. The current linear pipeline in
crates/core/src/rules/pipeline.rsis descriptor-based but still intentionally fixed-order.
Architecture
Helper recovery is intentionally split into three layers. This gives us more structure than scattered hand-written tuple checks, without committing to a general AST pattern DSL.
Binding-aware matching (match_context.rs)
MatchContext is used inside helper body-shape matchers when several
identifiers must refer to the same binding. It extracts named slots from
function params or discovered locals, then exposes checks like
ctx.is_binding(expr, "source") and ctx.is_member_of(expr, "source", "default").
Use it when matching a helper implementation where shadowing or swapped
operands would produce a false positive. Examples include Babel helpers such as
_classCallCheck, _inherits, _possibleConstructorReturn, and
_objectWithoutProperties.
Do not use MatchContext as a full AST pattern engine. The surrounding matcher
should still be ordinary Rust over SWC nodes; MatchContext exists to make
binding identity explicit and hard to forget.
Helper lifecycle utilities (helper_matcher.rs)
helper_matcher.rs contains the low-level binding primitives shared by helper
rules across Babel, TypeScript, webpack, and template helper recovery:
BindingKeyand extraction helpers such asbinding_key(),expr_binding_key(), andvar_declarator_binding_key()- binding-safe predicates such as
ident_matches_binding(),expr_matches_binding(), andmember_of_binding() - declaration cleanup helpers such as
remaining_refs_outside_*(),remove_fn_decls_by_binding(), andremove_var_declarators_by_binding()
Use these when a rule has already identified helper bindings and needs to track uses, rewrite call sites, or remove consumed declarations. This keeps the common scope-sensitive lifecycle code in one place while leaving each rule's semantic matching local to that rule.
Rule-local matching
Rules still own domain-specific shape recognition. For example:
transpiler_helper_utils.rsclassifies known Babel/TypeScript helper bodies and runtime imports.un_typeof_polyfill.rsrecognizes Babel/SWCtypeof Symbol.iteratorpolyfills, including the self-redefining cached function form. That form is matched against the declaration'sBindingKey: both the cache assignment and recursive call must target the same function binding and the recursive argument must be the helper parameter.un_to_consumable_array.rsrecognizes TypeScript__spreadArray.un_template_literal.rsrecognizes Babel/SWC/TypeScript tagged-template helper calls and cache factories. Detection uses body-shape signals — see "Tagged template body shapes" below.un_webpack_interop.rsrecognizes webpackrequire.n,require.t, andrequire.ohelper forms.un_object_spread.rsrecognizes esbuild's mangled__spreadValues/__spreadPropshelpers. This detection is stateful and stays rule-local on purpose: esbuild aliasesObject.defineProperty,Object.prototype.hasOwnProperty, etc. into local variables, and the spread helpers are matched relative to those module-wide aliases rather than by a self-contained body shape. The central scanner's matchers arefn(&Function) -> booland must not depend on bundler-specific module state, so moving this in would couple the scanner to esbuild internals. This is the documented "deliberate exception" the unification proposal anticipated; see learnings/helper-detection-pattern-engine.md.
This is deliberate. A helper matcher should encode the smallest semantic shape that proves the transform is safe, while shared utilities handle binding identity and declaration lifecycle mechanics.
Detection (transpiler_helper_utils.rs)
The collect_transpiler_helpers() function scans module-level declarations (function declarations, function-assigned variables, TypeScript helper imports, and Babel runtime imports) and returns helper identities by running each candidate through a set of shape matchers or matching known runtime package paths.
Pipeline consumers do not call collect_transpiler_helpers() directly. apply_rules() lazily builds a LocalHelperContext the first time a helper rule needs local helper bindings, after earlier syntax normalization rules have run. Later helper rules in the same pipeline range reuse that context instead of rescanning the module. Direct rule tests can still run individual VisitMut rules; those rules build a local context for themselves.
scan module-level declarations
→ for each function body, run shape matchers
→ for each Babel runtime import, map the import path to a helper kind
→ for each tslib import/require alias, map the raw TS helper kind
→ collect (binding_key, TranspilerHelperKind) pairs
Shape matchers are plain functions over SWC nodes. Most are
fn(&Function) -> bool; self-referential helpers additionally receive the
declaration's binding identity. They check essential structural elements and
ignore variable names. Writing a new matcher for a new helper is just writing
a new predicate.
LocalHelperContext also records TypeScript and tslib helper identities. Consumers use those binding identities directly; for example UnAsyncAwait matches detected __awaiter / __generator aliases instead of first renaming aliases to canonical global names. Shared call-site helpers such as is_helper_callee() cover local helper bindings, tslib namespace members, and direct require("tslib").helper calls.
Helper utilities include LocalHelperContext::helpers_of_kind() (filter by kind), remove_helper_declarations() (delete the helper function), helpers_with_remaining_refs() (check if a helper binding is still referenced elsewhere), and TS cleanup helpers such as remove_unused_inline_ts_helpers() / remove_unused_ts_helper_bindings().
collect_module_facts() records two helper export channels:
helper_exportsfor semantic transpiler helpers represented byTranspilerHelperKind/ publicHelperKind.ts_helper_exportsfor raw TypeScript/tslib helpers such as__awaiter,__generator, and__spreadArray.ts_helper_namespace_factory_exportsfor exported zero-argument CommonJS wrapper functions whose bodies both register raw tslib helpers and return the corresponding namespace object.
Cross-module consumers use both channels. UnAsyncAwait, for example, accepts
named helper imports, namespace members, and proven namespace-factory results;
it does not infer helper identity from a .__awaiter or .__generator property
name alone.
Restoration
Each helper kind has its own dedicated rule struct (e.g., UnInteropRequireDefault, UnInteropRequireWildcard, UnClassCallCheck). Each rule implements VisitMut for focused rule execution and also exposes a cached pipeline entry point that receives LocalHelperContext, then rewrites call sites.
For example, UnInteropRequireDefault:
var _a = _interopRequireDefault(require("a"))becomesvar _a = require("a")_a.defaultbecomes_a(at all reference sites)- The helper function declaration is removed
UnEsm also handles Babel's equivalent helper body when it is inlined directly
at a require() site:
var wrapped = (temp = require("a")) && temp.__esModule
? temp
: { default: temp };
use(wrapped.default);
It recovers a default import only when every use of wrapped is a read through
.default and the assigned temp is a hoisted var or an earlier
uninitialized let used exclusively by that exact helper expression. A later
lexical declaration bails out so removing the assignment cannot erase a TDZ
failure. Bare, computed, written, or otherwise escaping wrapper uses also bail
out. This matcher stays rule-local because the proof combines
the producer shape with module-wide binding-use facts; helper names alone carry
no provenance. Calling a recovered .default binding also relies on the
call_receiver_independence assumption documented in
rewrite-assumptions.md.
Where it runs in the pipeline
Helper detection and restoration runs within Stage 2 of the apply_rules() pipeline, after Stage 1 syntax normalization. Stage 1 rules like UnIndirectCall and UnBracketNotation must run first to normalize patterns like (0, x.default)() and ["default"] before helper detection can match reliably.
Transpiler helper coverage
Priority targets, roughly ordered by real-world frequency:
| Helper | Babel | tslib | SWC | Semantics |
|---|---|---|---|---|
interopRequireDefault |
_interopRequireDefault |
— | _interop_require_default |
Unwrap default import |
interopRequireWildcard |
_interopRequireWildcard |
— | _interop_require_wildcard |
Unwrap namespace import |
extends |
_extends |
__assign |
_extends |
Object.assign polyfill |
classCallCheck |
_classCallCheck |
— | _class_call_check |
if (!(this instanceof X)) throw guard |
createClass |
_createClass |
— | _create_class |
defineProperties for class methods |
slicedToArray |
_slicedToArray |
__read |
_sliced_to_array |
Destructuring arrays from iterables |
toConsumableArray |
_toConsumableArray |
__spreadArray |
_to_consumable_array |
[...arr] polyfill |
objectWithoutProperties |
_objectWithoutProperties |
__rest |
_object_without_properties |
const {a, ...rest} = obj |
typeof |
_typeof |
— | _type_of |
Native typeof, including self-caching declarations |
asyncToGenerator |
_asyncToGenerator |
__awaiter + __generator |
_async_to_generator |
async/await (already handled in un_async_await.rs) |
esbuild helpers (__commonJS, __esm, __toESM, __toCommonJS) are bundler-level and already handled in the unpacker, not here.
UnSlicedToArray also restores callback-local destructuring when a proven
helper is applied directly to one callback parameter. It accepts either an
unconditional leading declaration such as
const value = sliced(entry, 2)[1] or a direct equality comparison of that
indexed result. The parameter must have no other uses, the limit and index must
be bounded literals, and the recovered array pattern retains trailing elisions
so it consumes exactly the helper's requested number of iterator values.
Conditional/deferred access, arguments, direct eval, with, and minimal
rewrite mode all preserve the lowered form.
Tagged template body shapes
taggedTemplateLiteral detection uses signal-based matching on a 2-param
function body. Three transpiler variants are recognized:
| Variant | Signals required | Body pattern |
|---|---|---|
| Babel spec | slice_copy + freeze_define_raw |
Object.freeze(Object.defineProperties(strings, {raw: {value: Object.freeze(raws)}})) |
| Babel loose | slice_copy + raw_assignment |
strings.raw = raws (simple property assignment) |
| TypeScript | define_property_raw |
Object.defineProperty(strings, "raw", {value: raws}) |
slice_copy matches strings.slice(0) (the fallback copy when raws is
absent). raw_assignment matches strings.raw = raws as an AssignExpr.
define_property_raw matches Object.defineProperty(strings, "raw", ...).
The spec variant uses Object.freeze and Object.defineProperties as global
anchors, making it reliably detectable even when mangled. The loose variant
has no global anchors — it's detected only by the slice(0) + .raw =
combination on the two params. The esbuild variant aliases Object.freeze and
Object.defineProperty into local variables, which breaks global-anchored
matching in raw minified output. UnBuiltinAliases runs after early
declaration splitting and before helper-dependent structural recovery, so
module-scope builtin aliases are normalized back to global member reads before
the central body-shape scanner sees the helper.
Handling version drift
Babel helpers do change across versions (bug fixes, spec compliance, browser capability changes). The solution is relaxed matching — check the essential semantic structure, not exact AST equality.
For interopRequireDefault, the essential structure has been stable for years because it's defined by the ES module spec: "if __esModule, return as-is; otherwise wrap in {default: ...}". If a future version fundamentally changes what a helper does, it's a new helper and gets a new matcher.
In practice, most variation across versions is:
- Different conditional forms (ternary vs if/else)
- Property access style (
.defaultvs["default"]) - Extra
Object.definePropertyfor non-configurable exports - Added null checks
A good matcher checks for the presence of __esModule and default in the right structural positions, and tolerates everything else.