punctilio 4.3.1 → 5.0.1

package/src/prose-view.ts

@@ -1,6 +1,3 @@
-import { DEFAULT_SEPARATOR } from "./constants.js"
-import { transformTextNodes } from "./utils.js"
-
 export interface ProseNode {
   value: string
 }
@@ -54,8 +51,8 @@ class ProseViewImpl implements ProseView {
     return this.cachedBoundaries
   }
 
-  /** Recompute `text` and `boundaries` from the current node values. @internal */
-  refresh(): void {
+  /** Recompute `text` and `boundaries` from the current node values. */
+  private refresh(): void {
     let text = ""
     const boundaries: number[] = []
     this.nodes.forEach((node, index) => {
@@ -68,16 +65,6 @@ class ProseViewImpl implements ProseView {
     this.cachedBoundaries = boundaries
   }
 
-  /** @internal */
-  hasQueuedEdits(): boolean {
-    return this.edits.length > 0
-  }
-
-  /** @internal */
-  getNodes(): ProseNode[] {
-    return this.nodes
-  }
-
   hasBoundary(offset: number): boolean {
     const boundaries = this.cachedBoundaries
     let low = 0
@@ -292,34 +279,242 @@ export function replaceAllInView(
 }
 
 /**
- * Splits sentinel-marked text on the separator, builds a ProseView over the
- * fragments, runs `run` against the clean-text view, commits the queued edits,
- * and rejoins the fragments with the separator. The separator count is
- * preserved exactly: each fragment maps to one source node, and `commit()`
- * never creates or destroys node boundaries.
+ * String↔view bridge: builds a single-node ProseView over `text`, runs `run`
+ * against it, commits any queued edits, and returns the resulting text.
  */
-export function withProseView(
-  markedText: string,
-  separator: string,
-  run: (view: ProseView) => void,
-): string {
-  const fragments = separator.length > 0 ? markedText.split(separator) : [markedText]
-  const nodes: ProseNode[] = fragments.map((value) => ({ value }))
-  const view = buildProseView(nodes)
+export function withProseView(text: string, run: (view: ProseView) => void): string {
+  const node: ProseNode = { value: text }
+  const view = buildProseView([node])
   run(view)
   view.commit()
-  return nodes.map((node) => node.value).join(separator)
+  return node.value
 }
 
-export function runLegacyPass(
-  view: ProseView,
-  passFn: (markedText: string) => string,
-  separator: string = DEFAULT_SEPARATOR,
-): void {
-  const impl = view as ProseViewImpl
-  if (impl.hasQueuedEdits()) {
-    throw new Error("runLegacyPass() cannot run while the view has uncommitted queued edits.")
+/**
+ * A pass with the same dual-input shape as the built-ins (`niceQuotes`,
+ * `hyphenReplace`, ...): string in, transformed string out; ProseView in,
+ * edits committed onto it in place.
+ */
+export type ProsePass = {
+  (input: string): string
+  (input: ProseView): void
+}
+
+export interface DefinePassOptions {
+  /**
+   * How matches that contain an interior node boundary are handled:
+   *
+   * - `"skip"` (default, safe): such matches are left untouched, so a pass
+   *   never rewrites text that spans two source nodes.
+   * - `"allow"`: such matches are always replaced; the replacement text lands
+   *   in the node containing the match start, collapsing the boundary after it.
+   * - predicate: forwarded as `allowBoundaries` to {@link replaceAllInView};
+   *   return `true` to allow that particular boundary-spanning match.
+   */
+  boundaries?: "skip" | "allow" | ((match: RegExpExecArray, view: ProseView) => boolean)
+}
+
+type ReplacementPart =
+  | { kind: "literal"; text: string }
+  | { kind: "whole" }
+  | { kind: "indexed"; index: number; fallback?: { index: number; literal: string } }
+  | { kind: "named"; name: string }
+
+function isAsciiDigit(char: string | undefined): char is string {
+  return char !== undefined && char >= "0" && char <= "9"
+}
+
+/** Parses the `$`-token starting at `dollarIndex`; returns the part and the offset past it. */
+function parseDollarToken(template: string, dollarIndex: number): { part: ReplacementPart; next: number } {
+  const unsupported = (): Error =>
+    new Error(
+      `Unsupported "$" form in replacement template ${JSON.stringify(template)}; ` +
+      `supported forms are $$, $&, $1-$99, and $<name>.`
+    )
+
+  const next = template[dollarIndex + 1]
+  if (next === "$") {
+    return { part: { kind: "literal", text: "$" }, next: dollarIndex + 2 }
+  }
+  if (next === "&") {
+    return { part: { kind: "whole" }, next: dollarIndex + 2 }
+  }
+  if (isAsciiDigit(next)) {
+    const digits = isAsciiDigit(template[dollarIndex + 2])
+      ? next + template[dollarIndex + 2]
+      : next
+    const index = parseInt(digits, 10)
+    // `$12` means group 12 when it exists, otherwise group 1 followed by a
+    // literal "2" — matching String.replace. `$0`/`$00` reference nothing.
+    const fallbackIndex = parseInt(digits[0], 10)
+    const fallback = digits.length === 2 && fallbackIndex > 0
+      ? { index: fallbackIndex, literal: digits[1] }
+      : undefined
+    if (index === 0 && fallback === undefined) {
+      throw new Error(
+        `Unsupported group reference $${digits} in replacement template ` +
+        `${JSON.stringify(template)}; numbered groups start at $1.`
+      )
+    }
+    return { part: { kind: "indexed", index, fallback }, next: dollarIndex + 1 + digits.length }
+  }
+  if (next === "<") {
+    const close = template.indexOf(">", dollarIndex + 2)
+    if (close === -1 || close === dollarIndex + 2) {
+      throw unsupported()
+    }
+    return {
+      part: { kind: "named", name: template.slice(dollarIndex + 2, close) },
+      next: close + 1,
+    }
+  }
+  throw unsupported()
+}
+
+/**
+ * Parses a `String.replace`-style replacement template into parts. Supported
+ * forms: `$$` (literal `$`), `$&` (whole match), `$1`–`$99` (numbered
+ * groups), and `$<name>` (named groups). Any other `$` form (`$0`, ``$` ``,
+ * `$'`, a bare or malformed `$`) throws rather than silently substituting.
+ */
+function parseReplacementTemplate(template: string): ReplacementPart[] {
+  const parts: ReplacementPart[] = []
+  let literalStart = 0
+  let i = 0
+
+  while (i < template.length) {
+    if (template[i] !== "$") {
+      i++
+      continue
+    }
+    if (i > literalStart) {
+      parts.push({ kind: "literal", text: template.slice(literalStart, i) })
+    }
+    const { part, next } = parseDollarToken(template, i)
+    parts.push(part)
+    i = next
+    literalStart = next
+  }
+
+  if (template.length > literalStart) {
+    parts.push({ kind: "literal", text: template.slice(literalStart) })
+  }
+
+  return parts
+}
+
+/** Renders a numbered group reference, applying the `$12` → `$1` + "2" fallback. */
+function renderIndexedPart(
+  part: { index: number; fallback?: { index: number; literal: string } },
+  match: RegExpExecArray,
+): string {
+  if (part.index < match.length) {
+    return match[part.index] ?? ""
+  }
+  if (part.fallback && part.fallback.index < match.length) {
+    return (match[part.fallback.index] ?? "") + part.fallback.literal
+  }
+  throw new Error(
+    `Replacement references group $${part.index} but the pattern only has ` +
+    `${match.length - 1} capture group(s).`
+  )
+}
+
+/**
+ * Compiles a replacement template into a replacer. Group references are
+ * resolved per match: a reference to a group the pattern does not define
+ * throws, while a defined group that simply did not participate in the match
+ * substitutes the empty string (as with String.replace).
+ */
+function compileReplacementTemplate(template: string): (match: RegExpExecArray) => string {
+  const parts = parseReplacementTemplate(template)
+  return (match) =>
+    parts
+      .map((part) => {
+        switch (part.kind) {
+          case "literal":
+            return part.text
+          case "whole":
+            return match[0]
+          case "indexed":
+            return renderIndexedPart(part, match)
+          case "named": {
+            const groups = match.groups
+            if (!groups || !(part.name in groups)) {
+              throw new Error(
+                `Replacement references group $<${part.name}> but the pattern ` +
+                `has no capture group named "${part.name}".`
+              )
+            }
+            return groups[part.name] ?? ""
+          }
+        }
+      })
+      .join("")
+}
+
+/**
+ * Defines a boundary-aware pass with the same dual-input shape as the
+ * built-in passes, suitable for composing with them (e.g. via `applyPasses`
+ * from `punctilio/rehype`).
+ *
+ * `replacement` is either a template string (supporting `$$`, `$&`,
+ * `$1`–`$99`, and `$<name>`; any other `$` form throws at definition time)
+ * or a replacer `(match, view) => string | null`, where `null` leaves that
+ * match untouched.
+ *
+ * Patterns that can match the empty string (e.g. pure lookarounds) insert
+ * the replacement at every position they match; prefer patterns that
+ * consume at least one character.
+ */
+export function definePass(
+  pattern: RegExp,
+  replacement: string | ((match: RegExpExecArray, view: ProseView) => string | null),
+  options: DefinePassOptions = {},
+): ProsePass {
+  if (!pattern.global) {
+    throw new Error("definePass() requires a pattern with the global (g) flag.")
+  }
+
+  const boundaries = options.boundaries ?? "skip"
+  let allowBoundaries: ReplaceAllOptions["allowBoundaries"]
+  if (boundaries === "allow") {
+    allowBoundaries = () => true
+  } else if (typeof boundaries === "function") {
+    allowBoundaries = boundaries
+  } else if (boundaries !== "skip") {
+    throw new Error(
+      `Invalid boundaries option: ${JSON.stringify(boundaries)}. ` +
+      `Must be "skip", "allow", or a predicate.`
+    )
+  }
+
+  const replacer = typeof replacement === "string"
+    ? compileReplacementTemplate(replacement)
+    : replacement
+
+  function pass(input: string): string
+  function pass(input: ProseView): void
+  function pass(input: string | ProseView): string | void {
+    return overInput(input, (view) => {
+      replaceAllInView(view, pattern, replacer, allowBoundaries ? { allowBoundaries } : undefined)
+    })
+  }
+  return pass
+}
+
+/**
+ * Dual-input driver shared by the public passes: a string runs through a
+ * single-node view and returns the transformed string; a ProseView has the
+ * pass's edits queued and committed onto it in place (returns nothing).
+ */
+export function overInput(input: string, run: (view: ProseView) => void): string
+export function overInput(input: ProseView, run: (view: ProseView) => void): void
+export function overInput(input: string | ProseView, run: (view: ProseView) => void): string | void
+export function overInput(input: string | ProseView, run: (view: ProseView) => void): string | void {
+  if (typeof input === "string") {
+    return withProseView(input, run)
   }
-  transformTextNodes(impl.getNodes(), passFn, separator)
-  impl.refresh()
+  run(input)
+  input.commit()
 }