Files (1063)
docs/proposals/skip-unless.md
GitHubProposal: Source-text pre-check for rule skipping (skip_unless!)
Status: Deferred — documented for future consideration when the pipeline is stable and cross-module helper detection is settled.
Problem
In the multi-module unpack path, thousands of modules each run through ~50 rules. Many rules target specific transpiler patterns (Babel helpers, webpack interop, TS downlevel) that are absent from most modules. Each rule still performs a full AST walk even when its target pattern cannot possibly exist in the module.
Idea
Before running a guarded rule, do a cheap source.contains(needle) check on
the original module source text. If the needle string is absent, skip the rule
entirely — no AST walk needed.
macro_rules! skip_unless {
($rule:expr, $name:expr, $($needle:expr),+) => {
if started {
if $(source_has(source, $needle))||+ {
module.visit_mut_with(&mut $rule);
}
// observer + stop_after handling omitted for brevity
}
};
}
fn source_has(source: Option<&str>, needle: &str) -> bool {
source.is_none_or(|s| s.contains(needle))
}
When source is None, the guard is transparent — rules always run. The
optimization only activates in the multi-module path where the original module
source text is available.
Needle inventory
Each needle was chosen by reading the rule's visitor implementation. The needle must appear in any source text that contains a pattern the rule can transform.
| Rule | Needle(s) | Rationale |
|---|---|---|
| UnInteropRequireDefault | __esModule |
Interop check: e && e.__esModule |
| UnInteropRequireWildcard | __esModule |
Same interop check in wildcard form |
| UnToConsumableArray | Array.isArray |
Body-shape marker in Babel helper |
| UnObjectSpread | Object.assign, getOwnPropertyDescriptor |
Extends uses Object.assign; objectSpread2 uses getOwnPropertyDescriptors |
| UnSlicedToArray | Symbol |
Body contains Symbol.iterator |
| UnDefineProperty | defineProperty |
Body contains Object.defineProperty(...) |
| UnClassCallCheck | instanceof |
Body contains instanceof operator |
| UnPossibleConstructorReturn | ReferenceError |
Body contains throw new ReferenceError(...) |
| UnTypeofPolyfill | Symbol |
Body checks typeof Symbol |
| UnEsmoduleFlag | __esModule |
All three patterns reference __esModule |
| UnUseStrict | use strict |
The literal directive string |
| UnWebpackInterop | __esModule |
Getter pattern checks base.__esModule |
| UnClassFields | __init |
Matches __init* method names |
| UnAsyncAwait | __awaiter, __generator, or detected TypeScript async helper aliases |
Async/generator helper recovery |
| UnPrototypeClass | prototype |
Matches Foo.prototype.method = ... (very common, rarely skipped) |
| UnWebpackObjectGetters | defineProperties |
Calls Object.defineProperties(...) |
Key invariant
Needles are checked against the original source text, not the current AST. This is safe because rules only remove transpiler patterns — they never synthesize new ones. If a future rule introduces code containing a guarded needle, the guard would incorrectly skip that rule.
Source range
The source text is &unpacked.code — the code of the current split module:
- Webpack factories: raw extracted factory body
- Esbuild factories: raw extracted factory body
- Esbuild scope-hoisted modules: re-emitted code (
emit_items())
Helper detection (collect_transpiler_helpers) only scans the current module. A helper
defined in module A and called in module B would not be detected in module B,
so skip_unless correctly skips the rule there too (it would be a no-op anyway).
Benchmark results
Tested on a large esbuild bundle (thousands of scope-hoisted modules):
| Metric | With skip_unless | Without | Delta |
|---|---|---|---|
| Wall time | ~6.9s | ~7.7s | -10% |
On webpack bundles (hundreds of modules) the difference is in the noise because most modules contain the guarded patterns.
Why deferred
Maintenance burden: Two macros (
run!andskip_unless!) with duplicated range-tracking logic. Every pipeline change must update both.Mental overhead: Each guarded rule requires reasoning about what strings must appear in the source for the rule to match. Wrong needles silently break transformations.
Cross-module helper detection: If we later support detecting helpers in one module and transforming calls in another, the skip_unless model breaks — the calling module's source won't contain the helper body markers.
Modest impact: ~10% on the largest fixture. Other optimizations (parse once, parallel writes, scope-hoisted extraction) provide larger wins without the invariant complexity.
When to reconsider
- Pipeline is stable and rule set is frozen
- Cross-module helper detection design is finalized
- Profiling shows rule dispatch is a bottleneck on real-world inputs