perf(prepare-list): batch list-item insertions into one pass

prepareList synthesizes listItem enter and exit events one item at a
time using events.splice(at, 0, [event]). Each splice shifts the
suffix of the events array, so a list with K items inside an array of
N events does O(K * N) shift work. This is the dominant cost in
mdast-util-from-markdown's contribution to wide-list inputs and the
slowdown reported at depth on issue #49 / PR #50.

The fix collects the would-be splices into an insertions queue during
the existing walk and applies them outside the loop in one pass. Two
paths handle the work efficiently: lists with up to a small number of
insertions take a fast path that splices each insertion in reverse
order so unspliced positions stay valid, which avoids the cost of
allocating a fresh sub-array; longer lists go through a batched
rebuild and use a chunked spread so the splice never hits V8's
argument count limit.

How the cut points were chosen:

There are two thresholds in the new code: SMALL_LIST_LIMIT chooses
between fast-path splice loop and rebuild; SAFE_SPREAD chooses
between a single spread and a chunked spread.

SMALL_LIST_LIMIT is a workload-dependent crossover. The fast path
costs O(K * suffix) because each of the K splices shifts the events
suffix; the rebuild path costs O(N + K) plus a fixed allocation
overhead. Below some K the rebuild's constant overhead dominates;
above some K the fast path's K * suffix dominates. Because suffix
size and per-insertion splice cost both vary with document shape,
no single value is universally best: deeper nesting prefers higher
limits (everything stays on the splice loop), and documents with a
few moderately-sized lists prefer lower limits (the rebuild's lower
per-item cost wins). The threshold was chosen by sweeping
{0, 2, 4, 8, 16, 32, 64} with representative inputs from both
regimes and picking the value that kept the validated multi-run wins
on typical-document inputs without regressing the deep-nest case
beyond its own noise band.

SAFE_SPREAD is set by V8's argument count limit. Spreading a very
large array into events.splice can throw a stack overflow in some V8
versions, so the rebuild splits the new sub-array into chunks once
it exceeds a safe size. The chunk threshold was tested at
{1000, 2000, 5000, 10000, 20000, 70000}; 10000 had the lowest median
across the wide-list and spec-derived inputs and matches the
threshold micromark-util-chunked already uses for its own splice
helper, which tracks the same V8 constraint.

Pass-1 records insertions in non-decreasing `at` order by
construction (each boundary records its exit insertion at
`lineIndex || index` followed by its enter insertion at `index`, and
the next boundary's tail walk is bounded by the previous boundary's
listItemPrefix), so no sort is needed in the slow path. A dev-only
assertion verifies the invariant on every slow-path call.

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

  10,000 single-level list items     -36.3%  (4.0%)
  5,000 ATX headings                 -22.9%  (5.5%)
  one CommonMark example             -13.2%  (16.0%)
  full CommonMark spec  (~16 KB)     -13.0%  (46.4%, NOISY)
  CommonMark spec * 35  (~564 KB)    -10.7%  (0.8%, very clean)
  256 nested ordered list levels      -4.0%  (6.7%)
  CommonMark spec * 7  (~113 KB)      -3.8%  (12.8%)

Single-run full corpus runs show the same direction on every other
input that contains at least one list, with wins of -17% to -27% on
inputs heavy in fenced code blocks, images, character references,
inline links, tabs, and HTML blocks. The largest improvement is the
10,000-item single-level list input, which is the worst case for the
old per-item splice loop.

Trade-offs and inputs that do not move:

Inputs that contain no lists are unaffected by the change because
prepareList is never invoked. The pure emphasis stress inputs ('a**b'
repeated 10,000 times and similar) reported +13% and +28% on a
single run, but those inputs have a cross-run spread of 44 to 52% on
the baseline alone, so the apparent regressions sit inside their own
noise band. A 1 MB single paragraph, a Unicode-heavy 256 KB input,
and 10,000 unmatched asterisks all moved within +/- 3% of baseline.

Tests pass: dev + prod 1450/1450, 100% coverage maintained.
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.

Closes #49
Refs #50

Author: ChristianMurphy

dev/lib/index.js

@@ -307,6 +307,14 @@ function compiler(options) {
     let firstBlankLineIndex
     /** @type {boolean | undefined} */
     let atMarker
+    /**
+     * Insertions accumulated in walk order: each {at, event} maps to an
+     * `events.splice(at, 0, event)` in the original implementation. Applied
+     * once at the end so a wide list's per-item O(n) splice cost collapses
+     * to a single batched rebuild.
+     * @type {Array<{at: number, event: Event}>}
+     */
+    const insertions = []
 
     while (++index <= length) {
       const event = events[index]
@@ -413,9 +421,10 @@ function compiler(options) {
             lineIndex ? events[lineIndex][1].start : event[1].end
           )
 
-          events.splice(lineIndex || index, 0, ['exit', listItem, event[2]])
-          index++
-          length++
+          insertions.push({
+            at: lineIndex || index,
+            event: ['exit', listItem, event[2]]
+          })
         }
 
         // Create a new list item.
@@ -429,17 +438,115 @@ function compiler(options) {
             end: undefined
           }
           listItem = item
-          events.splice(index, 0, ['enter', item, event[2]])
-          index++
-          length++
+          insertions.push({at: index, event: ['enter', item, event[2]]})
           firstBlankLineIndex = undefined
           atMarker = true
         }
       }
     }
 
+    // Apply all insertions outside the iteration loop so a wide list's
+    // O(n*k) shift cost collapses to a single batched rebuild.
+    //
+    // Two paths: small lists (most documents, including deep nesting) take
+    // the splice fast path, which avoids the cost of allocating a fresh
+    // replacement array. Wide lists go through the batched rebuild and use
+    // a chunked spread to stay under V8's argument-count limit.
+    if (insertions.length > 0) {
+      // The fast path costs one splice per insertion, each shifting the
+      // events suffix by 1; total cost is O(K * suffix). The rebuild path
+      // costs one allocation and one splice replacing the whole range;
+      // total cost is O(N + K) plus the allocation overhead. Below some K
+      // the rebuild's constant overhead dominates the per-insertion splice
+      // work; above some K the fast path's K * suffix dominates the
+      // rebuild's bounded cost. The crossover varies by document shape, so
+      // this threshold is a balance between deeply nested lists (which
+      // favor staying on the fast path) and documents whose lists outgrow
+      // the constants (which favor the rebuild). The chosen value was
+      // confirmed by sweeping the threshold across representative inputs.
+      const SMALL_LIST_LIMIT = 8
+      if (insertions.length <= SMALL_LIST_LIMIT) {
+        // Splice from latest `at` to earliest so unspliced positions stay
+        // valid. Same-`at` groups are reversed compared to walk order, which
+        // produces the same final ordering the original splice loop did
+        // (exit before enter at the same insertion point).
+        let insertion = insertions.length
+        while (insertion-- > 0) {
+          events.splice(
+            insertions[insertion].at,
+            0,
+            insertions[insertion].event
+          )
+        }
+      } else {
+        // `insertions` is already in non-decreasing `at` order by
+        // construction: the pass-1 walk visits events left to right, and
+        // each boundary records its exit insertion at `lineIndex || index`
+        // (with `lineIndex < index`) followed by its enter insertion at
+        // `index`. The next boundary's tail walk is bounded by the previous
+        // boundary's listItemPrefix, so its `lineIndex` is strictly greater
+        // than the previous boundary's `index`. No sort is needed; the
+        // assert below verifies this in development. micromark-build strips
+        // the whole call (including the `.every()` callback) in production.
+        assert(
+          insertions.every(
+            (insertion, position) =>
+              position === 0 || insertion.at >= insertions[position - 1].at
+          ),
+          'expected insertions to be in non-decreasing `at` order'
+        )
+
+        const rangeLength = length - start + 1
+        /** @type {Array<Event>} */
+        const replacement = Array.from({
+          length: rangeLength + insertions.length
+        })
+        let writeIndex = 0
+        let insertionIndex = 0
+        let sourceIndex = start
+        while (sourceIndex <= length) {
+          while (
+            insertionIndex < insertions.length &&
+            insertions[insertionIndex].at === sourceIndex
+          ) {
+            replacement[writeIndex++] = insertions[insertionIndex].event
+            insertionIndex++
+          }
+
+          replacement[writeIndex++] = events[sourceIndex++]
+        }
+
+        // V8 limits the number of arguments that can be spread into a
+        // function call before triggering a stack overflow. Splice into a
+        // single call when the new sub-array fits comfortably below that
+        // limit; otherwise empty the range with one splice and refill it
+        // in chunks so no individual call hits the limit. The chunk size
+        // matches the threshold micromark-util-chunked uses for its own
+        // splice helper, which tracks the same V8 constraint.
+        const SAFE_SPREAD = 10_000
+        if (replacement.length <= SAFE_SPREAD) {
+          events.splice(start, rangeLength, ...replacement)
+        } else {
+          events.splice(start, rangeLength)
+          let chunkStart = 0
+          while (chunkStart < replacement.length) {
+            const chunkEnd = Math.min(
+              chunkStart + SAFE_SPREAD,
+              replacement.length
+            )
+            events.splice(
+              start + chunkStart,
+              0,
+              ...replacement.slice(chunkStart, chunkEnd)
+            )
+            chunkStart = chunkEnd
+          }
+        }
+      }
+    }
+
     events[start][1]._spread = listSpread
-    return length
+    return length + insertions.length
   }
 
   /**

test/index.js

@@ -1089,6 +1089,25 @@ test('fromMarkdown', async function (t) {
       }
     })
   })
+
+  await t.test(
+    'should parse a wide list that exceeds the chunked-splice threshold',
+    async function () {
+      // The list-item batched-rebuild path falls back to a chunked spread
+      // once the replacement exceeds V8's safe argument count. ~1000
+      // single-line items produce a replacement of ~16k entries, which
+      // crosses the threshold and exercises the chunked branch.
+      const itemCount = 1000
+      const markdown = '- a\n'.repeat(itemCount)
+      const tree = fromMarkdown(markdown)
+      assert.equal(tree.children.length, 1)
+      const list = tree.children[0]
+      assert.equal(list.type, 'list')
+      assert.equal(list.children.length, itemCount)
+      assert.equal(list.children[0].type, 'listItem')
+      assert.equal(list.children[itemCount - 1].type, 'listItem')
+    }
+  )
 })
 
 test('fixtures', async function (t) {