punctilio 1.3.1 → 1.4.0

package/src/quotes.ts

@@ -0,0 +1,132 @@
+/**
+ * Smart quote transformation: straight quotes → curly quotes.
+ */
+
+import escapeStringRegexp from "escape-string-regexp"
+import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS } from "./constants.js"
+
+const {
+  EM_DASH,
+  LEFT_DOUBLE_QUOTE,
+  RIGHT_DOUBLE_QUOTE,
+  LEFT_SINGLE_QUOTE,
+  RIGHT_SINGLE_QUOTE,
+  ELLIPSIS,
+} = UNICODE_SYMBOLS
+
+export type PunctuationStyle = "american" | "british" | "none"
+
+export interface QuoteOptions {
+  /** Boundary marker for HTML element boundaries. Default: "\uE000" */
+  separator?: string
+  /** "american" (inside), "british" (outside), "none". Default: "american" */
+  punctuationStyle?: PunctuationStyle
+}
+
+/** Convert straight single quotes to curly quotes and apostrophes */
+function convertSingleQuotes(text: string, sep: string): string {
+  const escapedSep = escapeStringRegexp(sep)
+
+  // Handle empty single quotes '' and whitespace-only quotes ' ' first
+  // Only match straight quotes, not already-converted curly quotes
+  const singleQuoteChars = `'${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}`
+  text = text.replace(new RegExp(`(?<![${singleQuoteChars}])''(?![${singleQuoteChars}])`, "g"), `${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}`)
+  text = text.replace(new RegExp(`(?<![${singleQuoteChars}])'(\\s+)'(?![${singleQuoteChars}])`, "g"), `${LEFT_SINGLE_QUOTE}$1${RIGHT_SINGLE_QUOTE}`)
+
+  const afterEndingSinglePatterns = `\\s\\.!?;,\\)${EM_DASH}\\-\\]"`
+  const afterEndingSingle = `(?=${escapedSep}?(?:s${escapedSep}?)?(?:[${afterEndingSinglePatterns}]|$))`
+  const endingSingle = `(?<=[^\\s${LEFT_DOUBLE_QUOTE}'])[']${afterEndingSingle}`
+  text = text.replace(new RegExp(endingSingle, "gm"), RIGHT_SINGLE_QUOTE)
+
+  const contraction = `(?<=[${LATIN_LETTERS}])['${RIGHT_SINGLE_QUOTE}](?=${escapedSep}?[${LATIN_LETTERS}])`
+  text = text.replace(new RegExp(contraction, "gm"), RIGHT_SINGLE_QUOTE)
+
+  const apostropheWhitelist = `(?=n${RIGHT_SINGLE_QUOTE} )`
+  const endQuoteNotContraction = `(?!${contraction})${RIGHT_SINGLE_QUOTE}${afterEndingSingle}`
+  // Limit lookahead scan to 1000 chars to prevent catastrophic backtracking on pathological inputs
+  const apostropheRegex = new RegExp(
+    `(?<=^|[^\\w])'(${apostropheWhitelist}|(?![^${LEFT_SINGLE_QUOTE}'\\n]{0,1000}${endQuoteNotContraction}))`,
+    "gm"
+  )
+  text = text.replace(apostropheRegex, RIGHT_SINGLE_QUOTE)
+
+  const beginningSingle = `(?<beforeContext>(?:^|[\\s${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${EM_DASH}\\-\\(])${escapedSep}?)['](?=${escapedSep}?\\S)`
+  text = text.replace(new RegExp(beginningSingle, "gm"), `$<beforeContext>${LEFT_SINGLE_QUOTE}`)
+
+  return text
+}
+
+/** Convert straight double quotes to curly quotes */
+function convertDoubleQuotes(text: string, sep: string): string {
+  const escapedSep = escapeStringRegexp(sep)
+
+  // Handle empty quotes "" first - match only when not part of adjacent quotes
+  // Require word boundary or start/end of string on at least one side
+  text = text.replace(/(?<=^|[\s([{])""(?=$|[\s)\]}.!?,;:])/g, `${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}`)
+  // Handle whitespace-only quotes " " - require non-quote chars on both sides
+  text = text.replace(/(?<=^|[\s([{])"(?<whitespace>\s+)"(?=$|[\s)\]}.!?,;:])/g, `${LEFT_DOUBLE_QUOTE}$<whitespace>${RIGHT_DOUBLE_QUOTE}`)
+
+  const beginningDouble = new RegExp(
+    `(?<=^|[\\s\\(\\/\\[\\{\\-${EM_DASH}${escapedSep}])(?<beforeChr>${escapedSep}?)["](?<afterChr>(?<sepWithPunct>${escapedSep}[ .,])|(?=${escapedSep}?\\.{3}|${escapedSep}?[^\\s\\)\\${EM_DASH},!?${escapedSep};:.\\}]))`,
+    "gm"
+  )
+  text = text.replace(beginningDouble, `$<beforeChr>${LEFT_DOUBLE_QUOTE}$<afterChr>`)
+
+  text = text.replace(new RegExp(`(?<=\\{)(?<sepSpace>${escapedSep}? )?["]`, "g"), `$<sepSpace>${LEFT_DOUBLE_QUOTE}`)
+
+  const endingDouble = `(?<beforeQuote>[^\\s\\(])["]((?<sepAfter>${escapedSep})?)(?=${escapedSep}|[\\s/\\).,;${EM_DASH}:\\-\\}!?s]|$)`
+  text = text.replace(new RegExp(endingDouble, "g"), `$<beforeQuote>${RIGHT_DOUBLE_QUOTE}$<sepAfter>`)
+
+  text = text.replace(new RegExp(`["](?<sepEnd>${escapedSep}?)$`, "g"), `${RIGHT_DOUBLE_QUOTE}$<sepEnd>`)
+  text = text.replace(new RegExp(`'(?=${RIGHT_DOUBLE_QUOTE})`, "gu"), RIGHT_SINGLE_QUOTE)
+
+  return text
+}
+
+/** Apply American or British punctuation style */
+function applyPunctuationStyle(text: string, sep: string, style: PunctuationStyle): string {
+  const escapedSep = escapeStringRegexp(sep)
+
+  if (style === "american") {
+    // Period outside → inside: "Hello". → "Hello."
+    const periodOutsideRegex = new RegExp(
+      `(?<![!?:\\.${ELLIPSIS}])(?<sepBefore>${escapedSep}?)(?<quote>[${RIGHT_SINGLE_QUOTE}${RIGHT_DOUBLE_QUOTE}])(?<sepAfter>${escapedSep}?)(?!\\.\\.\\.)\\.`,
+      "g"
+    )
+    text = text.replace(periodOutsideRegex, "$<sepBefore>.$<quote>$<sepAfter>")
+
+    // Comma outside → inside: "Hello", → "Hello,"
+    const commaOutsideRegex = new RegExp(
+      `(?<sepBefore>${escapedSep}?)(?<quote>[${RIGHT_SINGLE_QUOTE}${RIGHT_DOUBLE_QUOTE}])(?<sepAfter>${escapedSep}?),`,
+      "g"
+    )
+    text = text.replace(commaOutsideRegex, "$<sepBefore>,$<quote>$<sepAfter>")
+  } else if (style === "british") {
+    // Period inside → outside: "Hello." → "Hello".
+    const periodInsideRegex = new RegExp(
+      `(?<![!?:\\.${ELLIPSIS}])(?<sepBefore>${escapedSep}?)\\.(?<sepMiddle>${escapedSep}?)(?<quote>[${RIGHT_SINGLE_QUOTE}${RIGHT_DOUBLE_QUOTE}])`,
+      "g"
+    )
+    text = text.replace(periodInsideRegex, "$<sepBefore>$<sepMiddle>$<quote>.")
+
+    // Comma inside → outside: "Hello," → "Hello",
+    const commaInsideRegex = new RegExp(
+      `(?<![!?]),(?<sepAndQuote>${escapedSep}?[${RIGHT_DOUBLE_QUOTE}${RIGHT_SINGLE_QUOTE}])`,
+      "g"
+    )
+    text = text.replace(commaInsideRegex, "$<sepAndQuote>,")
+  }
+  return text
+}
+
+/** Convert straight quotes to smart quotes. */
+export function niceQuotes(text: string, options: QuoteOptions = {}): string {
+  const sep = options.separator ?? DEFAULT_SEPARATOR
+  const punctuationStyle = options.punctuationStyle ?? "american"
+
+  text = convertSingleQuotes(text, sep)
+  text = convertDoubleQuotes(text, sep)
+  text = applyPunctuationStyle(text, sep, punctuationStyle)
+
+  return text
+}

package/src/rehype.ts

@@ -0,0 +1,503 @@
+/**
+ * Rehype plugin for applying punctilio typography transformations to HTML.
+ *
+ * This plugin integrates punctilio with the unified/rehype ecosystem,
+ * allowing you to apply smart typography transformations to HTML ASTs.
+ *
+ * @packageDocumentation
+ */
+
+import type { Root, Element, Text, ElementContent, Parent, RootContent } from "hast"
+import type { Transformer } from "unified"
+
+import { visitParents } from "unist-util-visit-parents"
+
+import { transform, type TransformOptions } from "./index.js"
+import { DEFAULT_SEPARATOR } from "./constants.js"
+import { formatErrorString } from "./utils.js"
+
+/**
+ * Options for the rehype-punctilio plugin.
+ */
+export interface RehypePunctilioOptions extends TransformOptions {
+  /**
+   * HTML tag names to skip when applying transformations.
+   * Content inside these elements won't have formatting improvements applied.
+   *
+   * Default: ["code", "pre", "script", "style", "kbd", "var", "samp"]
+   */
+  skipTags?: string[]
+
+  /**
+   * CSS class names that indicate content should skip formatting.
+   * Elements with any of these classes (or descendants of such elements)
+   * will be skipped.
+   *
+   * Default: []
+   */
+  skipClasses?: string[]
+}
+
+const DEFAULT_SKIP_TAGS = ["code", "pre", "script", "style", "kbd", "var", "samp"]
+
+/**
+ * Maximum recursion depth for tree traversal functions.
+ * Prevents stack overflow from maliciously deep HTML nesting.
+ */
+const MAX_RECURSION_DEPTH = 1000
+
+/**
+ * Check if an element has a specific CSS class.
+ */
+function hasClass(node: Element, className: string): boolean {
+  const classNames = node.properties?.className
+  if (Array.isArray(classNames)) {
+    return classNames.includes(className)
+  }
+  /* istanbul ignore next -- rehype-parse always produces arrays, but handle strings defensively */
+  if (typeof classNames === "string") {
+    return classNames.split(/\s+/).includes(className)
+  }
+  return false
+}
+
+/**
+ * Check if any ancestor of a node matches a predicate.
+ */
+function hasAncestor(
+  ancestors: Parent[],
+  predicate: (node: Element) => boolean
+): boolean {
+  return ancestors.some((ancestor) => {
+    if (ancestor.type === "element") {
+      return predicate(ancestor as Element)
+    }
+    return false
+  })
+}
+
+/**
+ * Flattens text nodes from an element tree into a single array.
+ *
+ * @param node - The element or element content to process
+ * @param shouldSkip - Function to determine which elements to skip
+ * @param depth - Current recursion depth (internal use)
+ * @returns Array of Text nodes
+ *
+ * @example
+ * ```ts
+ * const textNodes = flattenTextNodes(paragraphElement, (el) => el.tagName === 'code')
+ * ```
+ */
+export function flattenTextNodes(
+  node: Element | ElementContent,
+  shouldSkip: (n: Element) => boolean,
+  depth: number = 0
+): Text[] {
+  if (depth > MAX_RECURSION_DEPTH) {
+    return []
+  }
+
+  if (node.type === "element" && shouldSkip(node)) {
+    return []
+  }
+
+  if (node.type === "text") {
+    return [node]
+  }
+
+  if (node.type === "element" && "children" in node) {
+    return node.children.flatMap((child) => flattenTextNodes(child, shouldSkip, depth + 1))
+  }
+
+  return []
+}
+
+/**
+ * Extracts concatenated text content from an element.
+ *
+ * @param node - The element to extract text from
+ * @param shouldSkip - Optional function to determine which elements to skip
+ * @returns The combined text content
+ *
+ * @example
+ * ```ts
+ * const text = getTextContent(paragraphElement)
+ * // Returns "Hello, world!" for <p>Hello, <em>world!</em></p>
+ * ```
+ */
+export function getTextContent(
+  node: Element,
+  shouldSkip: (n: Element) => boolean = () => false
+): string {
+  return flattenTextNodes(node, shouldSkip)
+    .map((n) => n.value)
+    .join("")
+}
+
+/**
+ * Recursively finds the first text node in a tree of HTML elements.
+ *
+ * @param node - The root node to search from
+ * @param depth - Current recursion depth (internal use)
+ * @returns The first text node found, or null if no text nodes exist
+ *
+ * @example
+ * ```ts
+ * const textNode = getFirstTextNode(divElement)
+ * if (textNode) console.log(textNode.value)
+ * ```
+ */
+export function getFirstTextNode(
+  node: Parent | RootContent,
+  depth: number = 0
+): Text | null {
+  if (!node || depth > MAX_RECURSION_DEPTH) return null
+
+  if (node.type === "text" && "value" in node) {
+    return node as Text
+  }
+
+  if ("children" in node && node.children.length > 0) {
+    for (const child of node.children) {
+      const textNode = getFirstTextNode(child as Parent, depth + 1)
+      if (textNode) return textNode
+    }
+  }
+
+  return null
+}
+
+/**
+ * Validates that smart quotes in a text string are properly matched.
+ *
+ * @param input - The text to validate
+ * @throws Error if quotes are mismatched
+ *
+ * @example
+ * ```ts
+ * assertSmartQuotesMatch('\u201CHello\u201D') // OK
+ * assertSmartQuotesMatch('\u201CHello')        // throws Error
+ * ```
+ */
+export function assertSmartQuotesMatch(input: string): void {
+  if (!input) return
+
+  const quoteMap: Record<string, string> = { "\u201C": "\u201D", "\u201D": "\u201C" }
+  const stack: string[] = []
+
+  for (const char of input) {
+    if (char in quoteMap) {
+      if (stack.length > 0 && quoteMap[stack[stack.length - 1]] === char) {
+        stack.pop()
+      } else {
+        stack.push(char)
+      }
+    }
+  }
+
+  if (stack.length > 0) {
+    throw new Error(`Mismatched quotes in ${input}`)
+  }
+}
+
+/**
+ * Applies a transformation to element text content while preserving HTML structure.
+ *
+ * This function uses a marker technique to handle text that spans multiple
+ * HTML elements. It:
+ * 1. Appends a private-use Unicode character to each child's text content
+ * 2. Concatenates and transforms the whole paragraph
+ * 3. Splits the result back into the original text nodes
+ *
+ * @param node - The element to transform
+ * @param transformFn - The transformation function to apply
+ * @param shouldSkip - Function to determine which elements to skip
+ * @param separator - The marker character to use (default: DEFAULT_SEPARATOR)
+ * @param checkInvariance - Whether to verify that the transform produces the same
+ *   result with and without markers. When true, checks that
+ *   `stripMarkers(transform(textWithMarkers)) === transform(stripMarkers(text))`.
+ *   Useful for debugging transforms that accidentally interact with markers.
+ *   Default: false
+ * @throws Error if transformation alters the number of text nodes
+ * @throws Error if checkInvariance is true and the invariance check fails
+ *
+ * @example
+ * ```ts
+ * import { transformElement, DEFAULT_SEPARATOR } from 'punctilio/rehype'
+ *
+ * // Apply a custom transform to an element
+ * transformElement(
+ *   paragraphElement,
+ *   (text) => text.replace(/eg\b/g, 'e.g.'),
+ *   (el) => el.tagName === 'code',
+ *   DEFAULT_SEPARATOR
+ * )
+ * ```
+ */
+export function transformElement(
+  node: Element,
+  transformFn: (input: string) => string,
+  shouldSkip: (input: Element) => boolean,
+  separator: string,
+  checkInvariance: boolean = false
+): void {
+  /* istanbul ignore if -- defensive: elements should always have children array */
+  if (!node?.children) {
+    return
+  }
+
+  const textNodes = flattenTextNodes(node, shouldSkip)
+  /* istanbul ignore if -- only hit when element has no text descendants */
+  if (textNodes.length === 0) {
+    return
+  }
+
+  // Append marker and concatenate all text nodes
+  const markedContent = textNodes.map((n) => n.value + separator).join("")
+
+  const transformedContent = transformFn(markedContent)
+
+  // Split and overwrite. Last fragment is always empty because strings end with marker
+  const transformedFragments = transformedContent.split(separator).slice(0, -1)
+
+  /* istanbul ignore if -- defensive: transform should never consume separator chars */
+  if (transformedFragments.length !== textNodes.length) {
+    throw new Error(
+      `Transformation altered the number of text nodes. ` +
+        `Expected ${textNodes.length}, got ${transformedFragments.length}. ` +
+        `Input: ${formatErrorString(markedContent, "input")}`
+    )
+  }
+
+  textNodes.forEach((n, index) => {
+    n.value = transformedFragments[index]
+  })
+
+  if (checkInvariance) {
+    const stripSep = (s: string) => s.replaceAll(separator, "")
+    const strippedTransformed = stripSep(transformedContent)
+    const expected = transformFn(stripSep(markedContent))
+
+    if (expected !== strippedTransformed) {
+      throw new Error(
+        `Transform invariance check failed: ` +
+          `expected ${formatErrorString(expected, "expected")} ` +
+          `but got ${formatErrorString(strippedTransformed, "actual")}`
+      )
+    }
+  }
+}
+
+/**
+ * HTML elements that can contain transformable text content.
+ * We traverse into these to find text nodes to transform.
+ */
+const TRANSFORMABLE_ELEMENTS = [
+  "p",
+  "em",
+  "strong",
+  "i",
+  "b",
+  "u",
+  "s",
+  "sub",
+  "sup",
+  "small",
+  "del",
+  "ins",
+  "mark",
+  "span",
+  "div",
+  "td",
+  "th",
+  "dt",
+  "dd",
+  "li",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "figcaption",
+  "blockquote",
+  "cite",
+  "q",
+  "a",
+  "label",
+  "legend",
+  "caption",
+  "summary",
+  "address",
+  "article",
+  "aside",
+  "footer",
+  "header",
+  "main",
+  "nav",
+  "section",
+  "time",
+  "abbr",
+  "dfn",
+  "data",
+  "bdi",
+  "bdo",
+  "ruby",
+  "rt",
+  "rp",
+]
+
+/**
+ * Collects elements that should have text transformations applied.
+ * Only collects elements that directly contain text nodes.
+ *
+ * @param node - The root element to search from
+ * @param shouldSkip - Function to determine which elements to skip
+ * @param depth - Current recursion depth (internal use)
+ * @returns Array of elements that contain transformable text
+ */
+export function collectTransformableElements(
+  node: Element,
+  shouldSkip: (n: Element) => boolean,
+  depth: number = 0
+): Element[] {
+  /* istanbul ignore if -- defensive: prevents stack overflow from malicious HTML */
+  if (depth > MAX_RECURSION_DEPTH) {
+    return []
+  }
+
+  const results: Element[] = []
+
+  if (shouldSkip(node)) {
+    return []
+  }
+
+  // If this node is a transformable element with direct text children, collect it
+  if (
+    TRANSFORMABLE_ELEMENTS.includes(node.tagName) &&
+    node.children.some((child) => child.type === "text")
+  ) {
+    results.push(node)
+  } else {
+    // Otherwise, recurse into children
+    for (const child of node.children) {
+      if (child.type === "element") {
+        results.push(...collectTransformableElements(child, shouldSkip, depth + 1))
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * Recursively marks all element descendants as transformed.
+ * Used to prevent redundant processing of nested elements whose text
+ * was already processed as part of a parent element.
+ */
+function markDescendants(node: Element, set: Set<Element>, depth: number = 0): void {
+  /* istanbul ignore if -- defensive: prevents stack overflow from malicious HTML */
+  if (depth > MAX_RECURSION_DEPTH) {
+    return
+  }
+
+  for (const child of node.children) {
+    if (child.type === "element") {
+      set.add(child)
+      markDescendants(child, set, depth + 1)
+    }
+  }
+}
+
+/**
+ * Rehype plugin that applies punctilio typography transformations to HTML.
+ *
+ * @param options - Plugin configuration options
+ * @returns Unified transformer function
+ *
+ * @example
+ * ```ts
+ * import { unified } from 'unified'
+ * import remarkParse from 'remark-parse'
+ * import remarkRehype from 'remark-rehype'
+ * import rehypeStringify from 'rehype-stringify'
+ * import { rehypePunctilio } from 'punctilio/rehype'
+ *
+ * const result = await unified()
+ *   .use(remarkParse)
+ *   .use(remarkRehype)
+ *   .use(rehypePunctilio, {
+ *     punctuationStyle: 'american',
+ *     dashStyle: 'american',
+ *   })
+ *   .use(rehypeStringify)
+ *   .process('"Hello," she said -- "it\'s nice."')
+ *
+ * // Output HTML will have smart quotes and em-dashes
+ * ```
+ */
+export function rehypePunctilio(
+  options: RehypePunctilioOptions = {}
+): Transformer<Root, Root> {
+  const {
+    skipTags = DEFAULT_SKIP_TAGS,
+    skipClasses = [],
+    separator = DEFAULT_SEPARATOR,
+    ...transformOptions
+  } = options
+
+  const shouldSkip = (node: Element): boolean => {
+    if (skipTags.includes(node.tagName)) {
+      return true
+    }
+    if (skipClasses.some((cls) => hasClass(node, cls))) {
+      return true
+    }
+    return false
+  }
+
+  const transformFn = (text: string): string => {
+    return transform(text, { ...transformOptions, separator })
+  }
+
+  return (tree: Root) => {
+    // Track transformed elements to avoid double-processing
+    const transformed = new Set<Element>()
+
+    visitParents(tree, (node, ancestors) => {
+      // Only process element nodes
+      if (node.type !== "element") {
+        return
+      }
+
+      const element = node as Element
+
+      // Skip if already transformed
+      if (transformed.has(element)) {
+        return
+      }
+
+      // Check if this node or any ancestor should be skipped
+      if (shouldSkip(element)) {
+        return
+      }
+      if (hasAncestor(ancestors as Parent[], shouldSkip)) {
+        return
+      }
+
+      // Collect and transform elements with text content
+      const elementsToTransform = collectTransformableElements(element, shouldSkip)
+      for (const elt of elementsToTransform) {
+        if (!transformed.has(elt)) {
+          transformElement(elt, transformFn, shouldSkip, separator)
+          transformed.add(elt)
+          // Mark all descendants as processed since their text was included
+          markDescendants(elt, transformed)
+        }
+      }
+    })
+  }
+}
+
+export default rehypePunctilio