docs/fact-system.md
GitHubCross-Module Fact System
See also: Architecture for the multi-module pipeline design, Rule dependency inventory for where fact-reading rules fit in the pipeline.
What it is
A barrier-and-read mechanism that lets Phase 2 rules read import/export shape
from other modules in the same bundle. Used today by
namespace_decomposition and helper recovery rules that need to prove a helper
identity across module boundaries.
Why it's simpler than the original proposal
The original design imagined rules writing per-module "observations" into
shared state, merging them at a barrier, and reading back immutable facts.
We do not need that. After UnEsm runs, ESM import/export declarations are
already a normalized, AST-level representation of module shape. That AST is
the fact. Fact extraction is then a pure function of the module — no rule-
written observations, no merge step.
Shape
Multi-module unpack runs in two parallel phases with a single barrier between
them (crates/core/src/driver/unpack.rs::unpack_multi_module):
Phase 1 (per module, parallel):
parse → resolver → rule range through UnEsm
recover webpack factory IIFE ESM shapes
collect_module_facts(&module) ← pure AST → facts
AST discarded
──── barrier: ModuleFactsMap assembled from all modules ────
Phase 2 (per module, parallel):
parse → resolver → rule range through UnEsm
run_namespace_decomposition(&mut module, facts) ← reads cross-module facts
rule range from UnTemplateLiteral through UnReturn
targeted late cleanup/recovery
The through-UnEsm range runs twice per module — the first pass feeds fact
extraction, the second runs the real output pipeline. Re-parsing is required
because SWC's SyntaxContext must remain continuous within the emitted module
pipeline; reusing the Phase 1 AST after a separate parse would break downstream
ctxt-sensitive rules.
Facts
crates/core/src/facts.rs:
ImportFact { local, source, kind: Default | Namespace | Named(imported) }ExportFact { exported, local, kind: Default | Named }HelperExportFact { exported, local, kind }ModuleFacts { imports, exports, helper_exports, ts_helper_exports, ts_helper_namespace_factory_exports, passthrough_target }ModuleFactsMap— keyed by normalized module specifier (handles./foo,foo,foo.jsvariants)
Extraction (collect_module_facts) reads the post-Stage-2 AST and returns
these structures. No mutation, no shared state.
Helper export facts are still pure AST facts. They only record helper identity when the exported local binding matches a known helper body shape or runtime export shape after Stage 2. They do not speculate from consumer-side usage.
Rules that read facts
namespace_decomposition— rewritesimport r from "./x"; r.foo()intoimport { foo } from "./x"; foo()when./xexportsfooand no collision prevents the rewrite. Handles aliased pre-existing specifiers, inner-scope shadowing, mixed default+named imports, and readability backoff when too many collisions would force aliasing.UnObjectSpread— in multi-module unpack, recognizes object spread helpers imported from a helper module whose default/named export fact proves it is Babel'sextendsorobjectSpreadhelper. This covers helpers split into their own module before consumer calls are rewritten to object spread syntax. The consumer import is retained for now because helper identity does not by itself prove that evaluating the helper module is side-effect-free.UnRegenerator— in multi-module unpack, recognizes async-to-generator helpers that were hoisted into their own module and consumed through generatedrequire()/interop aliases such ash.default(...), but only when the target module's helper export fact proves the default export is the async helper.UnAsyncAwait— recognizes direct imports and namespace members only when raw TypeScript helper facts prove__awaiter/__generator. For scope-hoisted CommonJS wrappers, a separate provider-side fact proves that the imported zero-argument factory returns the registered helper namespace; consumer-side property spelling alone is never sufficient.
Adding a new fact-reading rule
For a cross-module late pass that naturally runs at the Stage 2 barrier:
- Put the pass in
crates/core/src/as a free function taking(&mut Module, &ModuleFactsMap). - Call it from
unpack_multi_modulebetweenapply_rules(..., RulePipelineOptions::until("UnEsm"))and theUnTemplateLiteral-through-UnReturnrule range. - Do all AST mutation locally to the module — never write back to
ModuleFactsMap. - Add unit tests following
crates/core/tests/namespace_decomposition_rule.rs(usefacts_for(source)to synthesize a target module's facts).
For an existing rule that must stay at its current pipeline position, add an
optional fact-aware constructor and thread ModuleFactsMap through the
multi-module rule runner only. Single-file decompile() should keep using the
normal constructor.
Gotchas when synthesizing new idents
- Use
DUMMY_SPfor new import specifiers, aliases, and rewritten usage idents.apply_sourcemap_renames()skips idents only whenspan.is_dummy(); real spans would cause the source-map rename pass to vote on positions the bundler never emitted. - Propagate
SyntaxContextwhen reusing an existing binding. If your rewrite replacesR.foowith a reference to an existing local, stamp the existing local's ctxt on the new ident — otherwise later(sym, ctxt)passes (e.g.UnImportRenameStage 6) will rename the binding + original usages but miss yours, leaving an undefined reference. For newly-created import specifiers,SyntaxContext::empty()on both binding and usage is fine (they match each other and the resolver isn't re-run).
Non-goals
- No shared mutable state between rules in the same phase.
- No multi-round merging.
- No speculative facts ("this might be an X"). A fact holds iff the post-Stage-2 AST says it does.
Rules that need heavier semantic conclusions (e.g. "this namespace projection is always equivalent to a direct import binding") should derive them inside the rule from the facts they read — not emit them back into the map.