punctilio 4.3.1 → 5.0.0

package/src/nbsp.ts

@@ -1,4 +1,5 @@
-import { cachedRegExp, getEscapedSeparator, LATIN_LETTERS, NBSP_CHARS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
+import { cachedRegExp, LATIN_LETTERS, NBSP_CHARS, SPACE_CHARS, UNICODE_SYMBOLS } from "./constants.js"
+import { boundaryCountAt, overInput, type ProseView, replaceAllInView } from "./prose-view.js"
 
 const {
   NBSP,
@@ -11,11 +12,6 @@ const {
   TRADEMARK,
 } = UNICODE_SYMBOLS
 
-export interface NbspOptions {
-  /** Boundary marker for HTML element boundaries. Default: "\uE000\uE001" */
-  separator?: string
-}
-
 const SPACE = `[${SPACE_CHARS}]`
 
 const UNICODE_UPPERCASE = "\\p{Lu}"
@@ -97,31 +93,104 @@ const ABBREVIATION_PATTERN = REFERENCE_ABBREVIATIONS.map((a) => `${a}\\.`).join(
 const PUNCTUATION_OR_QUOTE = `[.,!?:;)(${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}\u00AB\u00BB${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}"]`
 const COPYRIGHT_SYMBOLS = `[${COPYRIGHT}${REGISTERED}${TRADEMARK}]`
 
+
+// The boundary-tolerance positions in this module reproduce the element-boundary
+// semantics of the pre-v5 sentinel-marked pipeline; they are pinned by the golden
+// corpus and the migration's differential fuzz.
+
+/**
+ * A tolerated slot admits exactly ONE node boundary at that position; two
+ * adjacent boundaries block the match. This enforces that: at most one boundary
+ * at `offset`, and every interior boundary in the span must sit at one of the
+ * allowed slot offsets.
+ */
+function boundariesOnlyAtSlots(view: ProseView, start: number, end: number, slots: number[]): boolean {
+  for (const boundary of view.boundaries) {
+    if (boundary <= start || boundary >= end) continue
+    if (!slots.includes(boundary)) return false
+  }
+  for (const slot of slots) {
+    if (boundaryCountAt(view, slot) > 1) return false
+  }
+  return true
+}
+
 // Skips when preceded by NBSP or back-to-back with the previous match,
 // preventing 3+ words from binding into a single line-break atom.
-export function nbspAfterShortWords(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
+export function nbspAfterShortWords(input: string): string
+export function nbspAfterShortWords(input: ProseView): void
+export function nbspAfterShortWords(input: string | ProseView): string | void {
+  return overInput(input, nbspAfterShortWordsOverView)
+}
+
+function nbspAfterShortWordsOverView(view: ProseView): void {
   const pattern = cachedRegExp(
-    `(?<=^|${SPACE}|${PUNCTUATION_OR_QUOTE}|>)(?<shortWord>[${LATIN_LETTERS}]{1,2})(?<marker>${sep}?)${SPACE}`,
+    `(?<=^|${SPACE}|${PUNCTUATION_OR_QUOTE}|>)(?<shortWord>[${LATIN_LETTERS}]{1,2})${SPACE}`,
     "gmu"
   )
-  let previousMatchEnd = -1
-  return text.replace(pattern, (match, shortWord: string, marker: string, offset: number) => {
-    if (offset === previousMatchEnd) return match
-    if (offset > 0 && NBSP_CHARS.includes(text[offset - 1])) return match
-    previousMatchEnd = offset + match.length
-    return `${shortWord}${marker}${NBSP}`
-  })
+  {
+    const clean = view.text
+    let previousMatchEnd = -1
+    replaceAllInView(
+      view,
+      pattern,
+      (match, v) => {
+        const offset = match.index
+        if (offset === previousMatchEnd) return null
+        // A boundary directly before the short word fails the
+        // `(?<=^|space|punct|>)` lookbehind (a boundary is not one of those).
+        if (view.hasBoundary(offset)) return null
+        if (offset > 0 && NBSP_CHARS.includes(clean[offset - 1])) return null
+        previousMatchEnd = offset + match[0].length
+        // Edit only the space so any boundary keeps its side of the NBSP.
+        v.replace(offset + match[0].length - 1, offset + match[0].length, NBSP)
+        return null
+      },
+      {
+        allowBoundaries: (match, v) =>
+          boundariesOnlyAtSlots(v, match.index, match.index + match[0].length, [
+            match.index + match[0].length - 1,
+          ]),
+      }
+    )
+  }
+  view.commit()
 }
 
-export function nbspBetweenNumberAndUnit(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
-  const wbe = wordBoundaryEnd(sep)
+export function nbspBetweenNumberAndUnit(input: string): string
+export function nbspBetweenNumberAndUnit(input: ProseView): void
+export function nbspBetweenNumberAndUnit(input: string | ProseView): string | void {
+  return overInput(input, nbspBetweenNumberAndUnitOverView)
+}
+
+function nbspBetweenNumberAndUnitOverView(view: ProseView): void {
   const pattern = cachedRegExp(
-    `(?<digit>\\d)(?<marker1>${sep}?)${SPACE}(?<marker2>${sep}?)(?<unit>${UNIT_PATTERN})${wbe}`,
+    `(?<digit>\\d)${SPACE}(?<unit>${UNIT_PATTERN})\\b`,
     "gm"
   )
-  return text.replace(pattern, `$<digit>$<marker1>${NBSP}$<marker2>$<unit>`)
+  {
+    replaceAllInView(
+      view,
+      pattern,
+      (match, v) => {
+        // Edit only the space (after the single digit) so any boundaries keep
+        // their sides.
+        v.replace(match.index + 1, match.index + 2, NBSP)
+        return null
+      },
+      {
+        // Tolerated slots: between digit and space (index+1) and between space
+        // and unit (index+2). The unit literal itself must be boundary-free,
+        // which the default interior-boundary skip already enforces.
+        allowBoundaries: (match, v) =>
+          boundariesOnlyAtSlots(v, match.index, match.index + match[0].length, [
+            match.index + 1,
+            match.index + 2,
+          ]),
+      }
+    )
+  }
+  view.commit()
 }
 
 const MAX_LAST_WORD_LENGTH = 10
@@ -129,84 +198,192 @@ const MAX_LAST_WORD_LENGTH = 10
 // Bounded so the lookbehind stays ReDoS-safe.
 const MAX_MIDDLE_WORD_LENGTH = 15
 
+const LATIN_LETTER_RE = cachedRegExp(`[${LATIN_LETTERS}]`, "u")
+
+/**
+ * The cascade lookbehind `(?<![NBSP][LATIN]{1,15})` over clean text: blocks
+ * when an NBSP/NNBSP is followed by 1..15 Latin letters ending at the space. A
+ * node boundary anywhere in that backward run breaks the run, re-enabling the
+ * match.
+ */
+function cascadeBlocksLastWord(view: ProseView, spaceOffset: number): boolean {
+  const text = view.text
+  let j = spaceOffset - 1
+  let run = 0
+  while (j >= 0 && run < MAX_MIDDLE_WORD_LENGTH && !view.hasBoundary(j + 1) && LATIN_LETTER_RE.test(text[j])) {
+    j--
+    run++
+  }
+  if (run === 0 || view.hasBoundary(j + 1)) return false
+  return j >= 0 && NBSP_CHARS.includes(text[j])
+}
+
 // Skips when the second-to-last word is already glued backwards via NBSP.
-export function nbspBeforeLastWord(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
-  const cascadeBlock = `(?<![${NBSP_CHARS}][${LATIN_LETTERS}]{1,${MAX_MIDDLE_WORD_LENGTH}})`
-  // Use alternation instead of character classes for multi-char separator support
-  const pattern = cachedRegExp(
-    `${cascadeBlock}(?<=\\w|${sep})${SPACE}(?<lastWord>(?:(?!\\s)(?!${sep}).){1,${MAX_LAST_WORD_LENGTH}})(?<ending>${sep}?(?:\\n\\n|$))`,
-    "g"
-  )
-  return text.replace(pattern, `${NBSP}$<lastWord>$<ending>`)
+export function nbspBeforeLastWord(input: string): string
+export function nbspBeforeLastWord(input: ProseView): void
+export function nbspBeforeLastWord(input: string | ProseView): string | void {
+  return overInput(input, nbspBeforeLastWordOverView)
 }
 
-export function nbspAfterReferenceAbbreviations(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
+function nbspBeforeLastWordOverView(view: ProseView): void {
+  // The `(?<=\w|boundary)` lookbehind and the `[NBSP][LATIN]{1,15}` cascade
+  // lookbehind are enforced in the replacer, where boundaries are visible.
   const pattern = cachedRegExp(
-    `(?<abbrev>${ABBREVIATION_PATTERN})(?<marker>${sep}?)${SPACE}(?=${sep}?\\d)`,
+    `${SPACE}(?<lastWord>(?:(?!\\s).){1,${MAX_LAST_WORD_LENGTH}})(?<ending>\\n\\n|$)`,
     "g"
   )
-  return text.replace(pattern, `$<abbrev>$<marker>${NBSP}`)
+  {
+    const clean = view.text
+    replaceAllInView(
+      view,
+      pattern,
+      (match, v) => {
+        const start = match.index
+        const end = start + match[0].length
+        // `(?<=\w|sep)`: a word char before the space, or a boundary there.
+        const precededByWord = start > 0 && /\w/.test(clean[start - 1])
+        if (!precededByWord && !view.hasBoundary(start)) return null
+        if (cascadeBlocksLastWord(v, start)) return null
+        // The `ending` group tolerates exactly one boundary at the slot before
+        // `\n\n`/end-of-text; two adjacent boundaries block the match. The
+        // end-of-text slot sits at the match end (never an interior boundary),
+        // so the cap is checked here rather than only in allowBoundaries.
+        if (boundaryCountAt(v, end - match.groups!.ending.length) > 1) return null
+        // Edit only the leading space so the lastWord/ending (and any boundary
+        // before \n\n) keep their positions.
+        v.replace(start, start + 1, NBSP)
+        return null
+      },
+      {
+        // The space-lookbehind boundary (== match.index) is not interior. The
+        // last word admits no interior boundary, so a boundary inside it blocks
+        // the match (the default skip). The only interior slot is the `ending`
+        // group's slot before a `\n\n`: one boundary tolerated.
+        allowBoundaries: (match, v) => {
+          const end = match.index + match[0].length
+          const endingSlot = end - match.groups!.ending.length
+          return boundariesOnlyAtSlots(v, match.index, end, [endingSlot])
+        },
+      }
+    )
+  }
+  view.commit()
 }
 
-export function nbspAfterSectionSymbols(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
+/**
+ * Shared driver for the abbreviation-family rules: `(thing)(SPACE)(?=context)`
+ * where the slot between thing and space and the lookahead slot (between space
+ * and context) each tolerate one boundary.
+ */
+function nbspBeforeContext(
+  view: ProseView,
+  thingPattern: string,
+  contextPattern: string,
+  flags: string,
+  thingGroup: string,
+): void {
   const pattern = cachedRegExp(
-    `(?<symbol>[§¶])(?<marker>${sep}?)${SPACE}(?=${sep}?\\d)`,
-    "g"
+    `(?<${thingGroup}>${thingPattern})${SPACE}(?=${contextPattern})`,
+    flags
   )
-  return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
+  {
+    const clean = view.text
+    pattern.lastIndex = 0
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(clean)) !== null) {
+      const start = match.index
+      const end = start + match[0].length
+      // Slot between the `thing` literal and the space (offset = end - 1);
+      // lookahead slot at the match end. Each tolerates one boundary; the
+      // literal itself must be boundary-free.
+      const allowed =
+        boundariesOnlyAtSlots(view, start, end, [end - 1]) && boundaryCountAt(view, end) <= 1
+      if (!allowed) {
+        // A boundary broke the (possibly longer) literal; let the scan re-anchor
+        // one position later so a shorter sub-abbreviation can still match.
+        pattern.lastIndex = start + 1
+        continue
+      }
+      // Edit only the trailing space so the slot/lookahead boundaries keep their
+      // sides.
+      view.replace(end - 1, end, NBSP)
+    }
+  }
+  view.commit()
 }
 
-export function nbspAfterHonorifics(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
-  const pattern = cachedRegExp(
-    `(?<honorific>${HONORIFIC_PATTERN})(?<marker>${sep}?)${SPACE}(?=${sep}?${UNICODE_UPPERCASE})`,
-    "gu"
-  )
-  return text.replace(pattern, `$<honorific>$<marker>${NBSP}`)
+function nbspAfterReferenceAbbreviationsOverView(view: ProseView): void {
+  nbspBeforeContext(view, ABBREVIATION_PATTERN, "\\d", "g", "abbrev")
 }
 
-export function nbspAfterCopyrightSymbols(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
-  const pattern = cachedRegExp(
-    `(?<symbol>${COPYRIGHT_SYMBOLS})(?<marker>${sep}?)${SPACE}(?=${sep}?[\\d${UNICODE_UPPERCASE}])`,
-    "gu"
-  )
-  return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
+function nbspAfterSectionSymbolsOverView(view: ProseView): void {
+  nbspBeforeContext(view, "[\u00A7\u00B6]", "\\d", "g", "symbol")
 }
 
-export function nbspBetweenInitials(text: string, options: NbspOptions = {}): string {
-  const sep = getEscapedSeparator(options)
-  const pattern = cachedRegExp(
-    `(?<initial>${UNICODE_UPPERCASE}\\.)(?<marker>${sep}?)${SPACE}(?=${sep}?${UNICODE_UPPERCASE})`,
-    "gu"
-  )
-  return text.replace(pattern, `$<initial>$<marker>${NBSP}`)
+function nbspAfterHonorificsOverView(view: ProseView): void {
+  nbspBeforeContext(view, HONORIFIC_PATTERN, UNICODE_UPPERCASE, "gu", "honorific")
+}
+
+function nbspAfterCopyrightSymbolsOverView(view: ProseView): void {
+  nbspBeforeContext(view, COPYRIGHT_SYMBOLS, `[\\d${UNICODE_UPPERCASE}]`, "gu", "symbol")
 }
 
-type NbspFn = (text: string, options: NbspOptions) => string
+function nbspBetweenInitialsOverView(view: ProseView): void {
+  nbspBeforeContext(view, `${UNICODE_UPPERCASE}\\.`, UNICODE_UPPERCASE, "gu", "initial")
+}
+
+export function nbspAfterReferenceAbbreviations(input: string): string
+export function nbspAfterReferenceAbbreviations(input: ProseView): void
+export function nbspAfterReferenceAbbreviations(input: string | ProseView): string | void {
+  return overInput(input, nbspAfterReferenceAbbreviationsOverView)
+}
+
+export function nbspAfterSectionSymbols(input: string): string
+export function nbspAfterSectionSymbols(input: ProseView): void
+export function nbspAfterSectionSymbols(input: string | ProseView): string | void {
+  return overInput(input, nbspAfterSectionSymbolsOverView)
+}
+
+export function nbspAfterHonorifics(input: string): string
+export function nbspAfterHonorifics(input: ProseView): void
+export function nbspAfterHonorifics(input: string | ProseView): string | void {
+  return overInput(input, nbspAfterHonorificsOverView)
+}
+
+export function nbspAfterCopyrightSymbols(input: string): string
+export function nbspAfterCopyrightSymbols(input: ProseView): void
+export function nbspAfterCopyrightSymbols(input: string | ProseView): string | void {
+  return overInput(input, nbspAfterCopyrightSymbolsOverView)
+}
+
+export function nbspBetweenInitials(input: string): string
+export function nbspBetweenInitials(input: ProseView): void
+export function nbspBetweenInitials(input: string | ProseView): string | void {
+  return overInput(input, nbspBetweenInitialsOverView)
+}
 
 // Specific patterns first so they claim matches before generic nbspAfterShortWords.
-const NBSP_TRANSFORMS: NbspFn[] = [
-  nbspAfterHonorifics,
-  nbspAfterReferenceAbbreviations,
-  nbspAfterSectionSymbols,
-  nbspAfterCopyrightSymbols,
-  nbspBetweenInitials,
-  nbspBetweenNumberAndUnit,
-  nbspAfterShortWords,
-  nbspBeforeLastWord,
+const NBSP_TRANSFORMS: ((view: ProseView) => void)[] = [
+  nbspAfterHonorificsOverView,
+  nbspAfterReferenceAbbreviationsOverView,
+  nbspAfterSectionSymbolsOverView,
+  nbspAfterCopyrightSymbolsOverView,
+  nbspBetweenInitialsOverView,
+  nbspBetweenNumberAndUnitOverView,
+  nbspAfterShortWordsOverView,
+  nbspBeforeLastWordOverView,
 ]
 
-export function nbspTransform(text: string, options: NbspOptions = {}): string {
-  // All nbsp patterns require a space, tab, or existing nbsp to match.
-  // Short-circuit if the text contains none of these.
-  if (!cachedRegExp(`[${SPACE_CHARS}]`, "").test(text)) return text
+export function nbspTransform(input: string): string
+export function nbspTransform(input: ProseView): void
+export function nbspTransform(input: string | ProseView): string | void {
+  return overInput(input, (view) => {
+    // All nbsp patterns require a space, tab, or existing nbsp to match.
+    // Short-circuit if the text contains none of these.
+    if (!cachedRegExp(`[${SPACE_CHARS}]`, "").test(view.text)) return
 
-  for (const fn of NBSP_TRANSFORMS) {
-    text = fn(text, options)
-  }
-  return text
+    for (const fn of NBSP_TRANSFORMS) {
+      fn(view)
+    }
+  })
 }