perf(compile): pre-declare position in node factories

[ChristianMurphy]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything or linked relevant results below
• I made sure the docs are up to date
• I included tests (or that’s not needed)

Description of changes

Each node factory returned an object literal that did not include a position property. enter() then patched the property in. V8 treated the property addition as a hidden-class transition for every node, so property reads in enter, exit, the compile loop, and any consumer walked a polymorphic shape instead of a stable one.

The fix declares 'position: undefined' as the trailing property on every node factory and on the root tree literal. enter() still mutates position to a real value, but the property already exists, so no hidden-class transition fires. V8 keeps a single hidden class per node type from construction onward.

Inputs that benefit, with multi-run median-of-medians vs the baseline (spread in parentheses):

10,000 character entity references -27.7% (1.2%, very clean)
1,000 fenced code blocks -29.9% (13.6%, borderline)
CommonMark spec * 35 (~564 KB) -9.3% (6.9%)
one CommonMark example -7.5% (9.5%)
full CommonMark spec (~16 KB) -6.3% (8.3%)
CommonMark spec * 7 (~113 KB) -2.2% (7.7%)

Single-run full corpus shows the same direction across every input that creates a non-trivial number of nodes: a 1,000-image input -25.9%, a 1,000-link input -24.9%, a 5,000-tab-heavy input -22.4%, a 5,000-HTML-block input -11.6%, a 10,000-list-item input -10.3%, a 5,000-heading input -9.4%, a 10,000-code-span input -8.8%, a 1,000-emphasis-chain input -4.7%, the 'xxxx' x 10,000 input -6.5%, a 1,000-autolink input -5.6%.

Trade-offs:

In exchange for stable hidden classes, every node now carries a 'position: undefined' field even when position would never have been added. In practice every node in this codebase gets a real position assigned by enter(), so the only cost is one undefined slot for the brief window between factory and enter() call.

Inputs where the gain is small or absent:

A 1 MB single paragraph reported +2.9% on a single run. That input produces one giant text node whose hidden-class shape was already monomorphic, so the change has no benefit there and the small move sits inside the input's noise band. A 5,000-reference-link-definition input and a 10,000-unmatched-asterisks input each moved +/- 2% on a single run, also inside their respective noise bands. Multi-run showed legacy-defs at -0.0% (clean, no movement).

The pure emphasis stress inputs ('a**b' repeated 10,000 times and similar) reported +17% to +29% on single runs but their cross-run spread is 12 to 50% on this stack alone, and these inputs do not exercise the node-creation hot path that this change targets, so the deltas are noise.

Tests pass: dev + prod 1448/1448, mdast-util-gfm 54/54, mdast-util-mdx 11/13. The two failing mdx tests reproduce on upstream/main and are not introduced by this branch.

[Copilot]

Pull request overview

This PR applies a small performance optimization in the markdown compiler by pre-declaring the position field on built-in mdast node factories and on the root node. In this codebase, enter() is responsible for attaching positional data during compilation, so the change aims to keep node object shapes stable throughout parsing.

Changes:

• Pre-declare position: undefined on the root AST node created in compile().
• Pre-declare position: undefined on all built-in node factory return values.
• Add an inline comment documenting the hidden-class rationale for the change.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ChristianMurphy]

📓 on this, plugins, like GFM should also pre-allocate position, otherwise adding plugins will get back to a spot where the node types are polymorphic and the speed up is partially lost.