docs(meta/design): add ast-mutation design doc#9338
Merged
Conversation
✅ Deploy Preview for rolldown-rs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new design document capturing rolldown’s current approach to threading per-AST-node metadata across passes using Span-keyed side tables, intended as a baseline for evaluating a future move to oxc AstNodeId.
Changes:
- Add
meta/design/ast-mutation.mddocumenting the scan → link → finalize pipeline and where AST mutation occurs. - Describe the Span-as-identity contract and the pre-scan span normalization performed by
PreProcessor. - Catalog common side-table flow patterns and current fragilities/limitations of Span-keying.
Member
|
|
Member
Author
|
Good call — added an "Address-as-identity (alternative key)" section in d886f45 covering the |
Member
Author
Merge activity
|
IWANABETHATGUY
approved these changes
May 12, 2026
## Summary Adds `meta/design/ast-mutation.md` describing how rolldown currently threads per-AST-node metadata between the scan, link, and finalize passes via side tables keyed by oxc `Span`. The doc covers: - The three-stage pipeline (scan → link → finalize) and which stage mutates the AST. - The Span-as-identity contract: insertion at scan/link, lookup by `node.span()` in the finalizer. - The pre-scan span normalization performed by `PreProcessor` (`crates/rolldown/src/utils/tweak_ast_for_scanning.rs`) — targeted deduplication for the node kinds used as side-table keys (`ModuleDeclaration`, `ImportExpression`, `ThisExpression`, `require` call/ident, `NewExpression`). - Three classical patterns that side tables instantiate: scan→finalize, scan→link→finalize, and scan→link. - Known fragilities: cloned spans, synthetic-`SPAN` collisions, hand-maintained `PreProcessor` coverage, no post-scan validation, and the existing `member_expr_ref.rs` FIXME pointing at `AstNodeId`. - Why this is on the radar: oxc is introducing `AstNodeId`, and this doc is the baseline for evaluating that migration. This is descriptive only — no code changes, no proposal. It captures the current state so a future migration has something concrete to compare against. ## Test plan - [ ] Doc reads cleanly end-to-end - [ ] File:line citations resolve to the code they reference 🤖 Generated with [Claude Code](https://claude.com/claude-code)
graphite-app
Bot
force-pushed
the
ember-gecko
branch
from
d886f45 to
9f77a9c
Compare
Merged
shulaoda
added a commit
that referenced
this pull request
May 13, 2026
## [1.0.1] - 2026-05-13 ### 🚀 Features - experimental/lazy-barrel: advice on oversized barrel modules (#9236) by @shulaoda - rolldown: inline optional-chain enum access (#9379) by @Dunqing - chunk-optimization: dedupe already-loaded dynamic deps (#9305) by @IWANABETHATGUY - binding: call moduleParsed hook in ParallelJsPlugin (#9318) by @jaehafe ### 🐛 Bug Fixes - transform: enable `enum_eval` for `transformSync` and vite TS transform (#9325) by @Dunqing - error: remove severity prefix from diagnostic messages (#9262) by @Kyujenius - deps: pin pnpm to 10.23.0 to work around catalog mismatch on Netlify (#9364) by @shulaoda - ci: pin mimalloc-safe to 0.1.58 (#9361) by @shulaoda - dev/lazy: fix exports of lazy requests in lazy chunks (#9249) by @h-a-n-a - rolldown_plugin_vite_resolve: handle errors in `resolveSubpathImports` callback (#9355) by @sapphi-red - rolldown_plugin_lazy_compilation: use loadExports for fetched proxy to preserve original export names (#9132) by @h-a-n-a - common: include offending index in HybridIndexVec panic message (#9296) by @SAY-5 ### 🚜 Refactor - ecmascript: extract semantic_builder_for_transform helper (#9326) by @Dunqing - test: extract reusable static-import-cycle helper (#9332) by @IWANABETHATGUY ### 📚 Documentation - clarify scope of `topLevelVar` (#9380) by @IWANABETHATGUY - meta/design: add ast-mutation design doc (#9338) by @hyf0 - feat: add ai policy in contribution guide (#9315) by @mdong1909 ### ⚡ Performance - binding: enable mimalloc v3 to reduce idle memory (#9349) by @shulaoda ### 🧪 Testing - mcs: cover require() in `$initial` group (#9376) by @hyf0 - add regression for CJS facade chunk merge into entry (#9351) by @IWANABETHATGUY ### ⚙️ Miscellaneous Tasks - switch prepare-release to manual dispatch with version input (#9383) by @shulaoda - migrate `@rolldown/pluginutils` to `rolldown/plugins` (#9317) by @shulaoda - deps: pin libmimalloc-sys2 to 0.1.54 (#9372) by @shulaoda - replace `igorskyflyer/action-readfile` with `cat` (#9369) by @sapphi-red - deps: update test262 submodule for tests (#9371) by @rolldown-guard[bot] - use app token for test dep update PRs (#9368) by @sapphi-red - replace some actions with gh commands (#9367) by @sapphi-red - replace action-semantic-pull-request with inline regex (#9366) by @sapphi-red - remove pull_request_target workflows (#9188) by @Boshen - deps: upgrade oxc to 0.130.0 (#9360) by @shulaoda - deps: update github actions (major) (#9348) by @renovate[bot] - deps: update github actions (#9341) by @renovate[bot] - deps: update rust crates (#9344) by @renovate[bot] - deps: update crate-ci/typos action to v1.46.1 (#9357) by @renovate[bot] - deps: update npm packages (#9343) by @renovate[bot] - deps: update pnpm to v10.33.4 (#9347) by @renovate[bot] - deps: update dependency rolldown-plugin-dts to ^0.25.0 (#9346) by @renovate[bot] - .claude: add rolldown-repl encoder, rename decode skill (#9352) by @IWANABETHATGUY - deps: update crate-ci/typos action to v1.46.0 (#9345) by @renovate[bot] - deps: update napi to v3.8.6 (#9342) by @renovate[bot] - deps: update dependency vite-plus to v0.1.20 (#9340) by @renovate[bot] - enable rollup chunking-form test (#9335) by @IWANABETHATGUY - typo: fix typo in watcher options comment (#9324) by @thescripted ### ❤️ New Contributors * @Kyujenius made their first contribution in [#9262](#9262) * @SAY-5 made their first contribution in [#9296](#9296) * @thescripted made their first contribution in [#9324](#9324) Co-authored-by: shulaoda <[email protected]>
IWANABETHATGUY
pushed a commit
that referenced
this pull request
May 18, 2026
## Summary Adds `meta/design/ast-mutation.md` describing how rolldown currently threads per-AST-node metadata between the scan, link, and finalize passes via side tables keyed by oxc `Span`. The doc covers: - The three-stage pipeline (scan → link → finalize) and which stage mutates the AST. - The Span-as-identity contract: insertion at scan/link, lookup by `node.span()` in the finalizer. - The pre-scan span normalization performed by `PreProcessor` (`crates/rolldown/src/utils/tweak_ast_for_scanning.rs`) — targeted deduplication for the node kinds used as side-table keys (`ModuleDeclaration`, `ImportExpression`, `ThisExpression`, `require` call/ident, `NewExpression`). - Three classical patterns that side tables instantiate: scan→finalize, scan→link→finalize, and scan→link. - Known fragilities: cloned spans, synthetic-`SPAN` collisions, hand-maintained `PreProcessor` coverage, no post-scan validation, and the existing `member_expr_ref.rs` FIXME pointing at `AstNodeId`. - Why this is on the radar: oxc is introducing `AstNodeId`, and this doc is the baseline for evaluating that migration. This is descriptive only — no code changes, no proposal. It captures the current state so a future migration has something concrete to compare against. ## Test plan - [ ] Doc reads cleanly end-to-end - [ ] File:line citations resolve to the code they reference 🤖 Generated with [Claude Code](https://claude.com/claude-code)
IWANABETHATGUY
pushed a commit
that referenced
this pull request
May 18, 2026
## [1.0.1] - 2026-05-13 ### 🚀 Features - experimental/lazy-barrel: advice on oversized barrel modules (#9236) by @shulaoda - rolldown: inline optional-chain enum access (#9379) by @Dunqing - chunk-optimization: dedupe already-loaded dynamic deps (#9305) by @IWANABETHATGUY - binding: call moduleParsed hook in ParallelJsPlugin (#9318) by @jaehafe ### 🐛 Bug Fixes - transform: enable `enum_eval` for `transformSync` and vite TS transform (#9325) by @Dunqing - error: remove severity prefix from diagnostic messages (#9262) by @Kyujenius - deps: pin pnpm to 10.23.0 to work around catalog mismatch on Netlify (#9364) by @shulaoda - ci: pin mimalloc-safe to 0.1.58 (#9361) by @shulaoda - dev/lazy: fix exports of lazy requests in lazy chunks (#9249) by @h-a-n-a - rolldown_plugin_vite_resolve: handle errors in `resolveSubpathImports` callback (#9355) by @sapphi-red - rolldown_plugin_lazy_compilation: use loadExports for fetched proxy to preserve original export names (#9132) by @h-a-n-a - common: include offending index in HybridIndexVec panic message (#9296) by @SAY-5 ### 🚜 Refactor - ecmascript: extract semantic_builder_for_transform helper (#9326) by @Dunqing - test: extract reusable static-import-cycle helper (#9332) by @IWANABETHATGUY ### 📚 Documentation - clarify scope of `topLevelVar` (#9380) by @IWANABETHATGUY - meta/design: add ast-mutation design doc (#9338) by @hyf0 - feat: add ai policy in contribution guide (#9315) by @mdong1909 ### ⚡ Performance - binding: enable mimalloc v3 to reduce idle memory (#9349) by @shulaoda ### 🧪 Testing - mcs: cover require() in `$initial` group (#9376) by @hyf0 - add regression for CJS facade chunk merge into entry (#9351) by @IWANABETHATGUY ### ⚙️ Miscellaneous Tasks - switch prepare-release to manual dispatch with version input (#9383) by @shulaoda - migrate `@rolldown/pluginutils` to `rolldown/plugins` (#9317) by @shulaoda - deps: pin libmimalloc-sys2 to 0.1.54 (#9372) by @shulaoda - replace `igorskyflyer/action-readfile` with `cat` (#9369) by @sapphi-red - deps: update test262 submodule for tests (#9371) by @rolldown-guard[bot] - use app token for test dep update PRs (#9368) by @sapphi-red - replace some actions with gh commands (#9367) by @sapphi-red - replace action-semantic-pull-request with inline regex (#9366) by @sapphi-red - remove pull_request_target workflows (#9188) by @Boshen - deps: upgrade oxc to 0.130.0 (#9360) by @shulaoda - deps: update github actions (major) (#9348) by @renovate[bot] - deps: update github actions (#9341) by @renovate[bot] - deps: update rust crates (#9344) by @renovate[bot] - deps: update crate-ci/typos action to v1.46.1 (#9357) by @renovate[bot] - deps: update npm packages (#9343) by @renovate[bot] - deps: update pnpm to v10.33.4 (#9347) by @renovate[bot] - deps: update dependency rolldown-plugin-dts to ^0.25.0 (#9346) by @renovate[bot] - .claude: add rolldown-repl encoder, rename decode skill (#9352) by @IWANABETHATGUY - deps: update crate-ci/typos action to v1.46.0 (#9345) by @renovate[bot] - deps: update napi to v3.8.6 (#9342) by @renovate[bot] - deps: update dependency vite-plus to v0.1.20 (#9340) by @renovate[bot] - enable rollup chunking-form test (#9335) by @IWANABETHATGUY - typo: fix typo in watcher options comment (#9324) by @thescripted ### ❤️ New Contributors * @Kyujenius made their first contribution in [#9262](#9262) * @SAY-5 made their first contribution in [#9296](#9296) * @thescripted made their first contribution in [#9324](#9324) Co-authored-by: shulaoda <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
meta/design/ast-mutation.mddescribing how rolldown currently threads per-AST-node metadata between the scan, link, and finalize passes via side tables keyed by oxcSpan.The doc covers:
node.span()in the finalizer.PreProcessor(crates/rolldown/src/utils/tweak_ast_for_scanning.rs) — targeted deduplication for the node kinds used as side-table keys (ModuleDeclaration,ImportExpression,ThisExpression,requirecall/ident,NewExpression).SPANcollisions, hand-maintainedPreProcessorcoverage, no post-scan validation, and the existingmember_expr_ref.rsFIXME pointing atAstNodeId.AstNodeId, and this doc is the baseline for evaluating that migration.This is descriptive only — no code changes, no proposal. It captures the current state so a future migration has something concrete to compare against.
Test plan
🤖 Generated with Claude Code