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 that writes the replacement into a fresh array, then either
splices the whole replacement in one call (when it fits below V8's
spread argument limit) or shifts the suffix once and writes the
replacement into the vacated range. The in-place shift avoids the
per-chunk splice loop a chunked spread fallback would use, which
would re-introduce O(K * N) shift cost on very wide lists.

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 an in-place shift.

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 above the threshold the rebuild instead resizes
events once, shifts the suffix to its target position, and writes
the replacement into the vacated range. Total work is O(suffix +
replacement.length), independent of how many insertions were
queued. The single-spread 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.

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     -40.8%  (5.6%)
  5,000 ATX headings                 -20.6%  (4.3%)
  CommonMark spec * 35  (~564 KB)    -11.7%  (1.6%, very clean)
  one CommonMark example              -9.1%  (105%, NOISY)
  256 nested ordered list levels      -8.8%  (20.3%)
  full CommonMark spec  (~16 KB)      -7.0%  (35.4%, NOISY)
  CommonMark spec * 7  (~113 KB)      -3.6%  (1.0%, very clean)

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 large deltas in single
runs, 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 1452/1452, 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,125 @@ 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. For larger replacements, neither a single spread (would
+        // overflow the call stack) nor a loop of smaller splices (each
+        // would re-shift the suffix, restoring O(K * N) cost) is suitable;
+        // shift the suffix to its target position once, then write the
+        // replacement contents into the now-vacated range. Total work is
+        // O(suffix + replacement.length), independent of how the
+        // replacement is chunked. The single-spread threshold matches
+        // micromark-util-chunked's own splice helper.
+        const SAFE_SPREAD = 10_000
+        if (replacement.length <= SAFE_SPREAD) {
+          events.splice(start, rangeLength, ...replacement)
+        } else {
+          const oldEnd = start + rangeLength
+          const newEnd = start + replacement.length
+          const delta = newEnd - oldEnd
+          assert(
+            delta > 0,
+            'expected the replacement to be longer than the original range'
+          )
+
+          const oldEventsLength = events.length
+          events.length = oldEventsLength + delta
+          let shiftIndex = events.length
+          while (shiftIndex-- > newEnd) {
+            events[shiftIndex] = events[shiftIndex - delta]
+          }
+
+          let writeIndex = 0
+          while (writeIndex < replacement.length) {
+            events[start + writeIndex] = replacement[writeIndex]
+            writeIndex++
+          }
+        }
+      }
+    }
+
     events[start][1]._spread = listSpread
-    return length
+    return length + insertions.length
   }
 
   /**

test/index.js

@@ -1089,6 +1089,118 @@ 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 an in-place shift
+      // once the replacement exceeds V8's safe argument count for spread.
+      // ~1000 single-line items produce a replacement of ~16k entries,
+      // which crosses the threshold and exercises that branch. Validate
+      // that a wide list lines up with the small list's shape (list-level
+      // fields, per-item structure, position bookkeeping) so a regression
+      // in the wide-list-only branch cannot pass on count alone.
+      const referenceCount = 10
+      const wideCount = 1000
+
+      const reference = fromMarkdown('- a\n'.repeat(referenceCount))
+      const wide = fromMarkdown('- a\n'.repeat(wideCount))
+
+      assert.equal(wide.children.length, 1)
+      const referenceRoot = reference.children[0]
+      const wideRoot = wide.children[0]
+      if (referenceRoot.type !== 'list') throw new Error('expected list')
+      if (wideRoot.type !== 'list') throw new Error('expected list')
+
+      assert.equal(wideRoot.ordered, referenceRoot.ordered)
+      assert.equal(wideRoot.spread, referenceRoot.spread)
+      assert.equal(wideRoot.start, referenceRoot.start)
+      assert.equal(wideRoot.children.length, wideCount)
+
+      // Each list item must have the same per-item shape the reference
+      // list produces (paragraph wrapping a text node valued 'a').
+      const referenceItem = referenceRoot.children[0]
+      for (const wideItem of [
+        wideRoot.children[0],
+        wideRoot.children[Math.floor(wideCount / 2)],
+        wideRoot.children[wideCount - 1]
+      ]) {
+        assert.equal(wideItem.spread, referenceItem.spread)
+        assert.equal(wideItem.checked, referenceItem.checked)
+        assert.equal(wideItem.children.length, 1)
+        const wideParagraph = wideItem.children[0]
+        if (wideParagraph.type !== 'paragraph') {
+          throw new Error('expected paragraph')
+        }
+
+        assert.equal(wideParagraph.children.length, 1)
+        const wideText = wideParagraph.children[0]
+        if (wideText.type !== 'text') throw new Error('expected text')
+        assert.equal(wideText.value, 'a')
+      }
+
+      /** @type {Array<import('mdast').ListItem>} */
+      const items = wideRoot.children
+
+      // Positions on a sample of items must line up with the input lines.
+      const samples = [0, Math.floor(wideCount / 2), wideCount - 1]
+      let sampleIndex = -1
+      while (++sampleIndex < samples.length) {
+        const lineNumber = samples[sampleIndex]
+        const samplePosition = items[lineNumber].position
+        if (!samplePosition) throw new Error('expected listItem position')
+        assert.equal(samplePosition.start.line, lineNumber + 1)
+        assert.equal(samplePosition.start.column, 1)
+      }
+
+      // The list's own position must span from the first item's start to
+      // the last item's end.
+      const wideListPosition = wideRoot.position
+      const firstItemPosition = items[0].position
+      const lastItemPosition = items[wideCount - 1].position
+      if (!wideListPosition || !firstItemPosition || !lastItemPosition) {
+        throw new Error('expected positions')
+      }
+
+      assert.equal(
+        wideListPosition.start.offset,
+        firstItemPosition.start.offset
+      )
+      assert.equal(wideListPosition.end.offset, lastItemPosition.end.offset)
+    }
+  )
+
+  await t.test(
+    'should infer spread on a wide list with blank lines between items',
+    async function () {
+      // Blank lines between items mark a list as loose (spread = true).
+      // The spread inference happens during the same prepareList walk that
+      // produces the wide-list rebuild, so this input drives both paths
+      // together.
+      const referenceCount = 10
+      const wideCount = 1000
+
+      const reference = fromMarkdown('- a\n\n'.repeat(referenceCount))
+      const wide = fromMarkdown('- a\n\n'.repeat(wideCount))
+
+      const referenceRoot = reference.children[0]
+      const wideRoot = wide.children[0]
+      if (referenceRoot.type !== 'list') throw new Error('expected list')
+      if (wideRoot.type !== 'list') throw new Error('expected list')
+
+      assert.equal(referenceRoot.spread, true, 'reference must be loose')
+      assert.equal(wideRoot.spread, referenceRoot.spread)
+      assert.equal(wideRoot.children.length, wideCount)
+
+      const referenceSpread = referenceRoot.children[0].spread
+      for (const item of [
+        wideRoot.children[0],
+        wideRoot.children[wideCount - 1]
+      ]) {
+        assert.equal(item.spread, referenceSpread)
+      }
+    }
+  )
 })
 
 test('fixtures', async function (t) {