punctilio 3.11.3 → 3.11.4

package/src/prettier-plugin.ts

@@ -1,18 +1,3 @@
-/**
- * Prettier plugin applying punctilio's typographic transforms to Markdown.
- *
- * @example
- * ```jsonc
- * // .prettierrc
- * { "plugins": ["punctilio/prettier-plugin"] }
- *
- * // .punctiliorc.json (optional)
- * { "punctuationStyle": "british", "skipTags": ["pre", "code"] }
- * ```
- *
- * @packageDocumentation
- */
-
 import { dirname } from "node:path"
 
 import * as prettierMarkdown from "prettier/plugins/markdown"
@@ -30,11 +15,6 @@ async function loadPunctilioConfig(searchFrom: string): Promise<RemarkPunctilioO
   return !result || result.isEmpty ? {} : (result.config as RemarkPunctilioOptions)
 }
 
-/**
- * Runs `remarkPunctilio`'s transformer against an mdast tree. The plugin
- * mutates the tree in place; awaiting handles any future async variant
- * without churning callers.
- */
 async function runRemarkPunctilio(opts: RemarkPunctilioOptions, ast: Root): Promise<void> {
   // The unified `Transformer` signature requires a VFile and a callback,
   // but `remarkPunctilio` only ever reads the tree. Narrow to the actual

package/src/quotes.ts

@@ -1,9 +1,4 @@
-/**
- * Smart quote transformation: straight quotes → curly quotes.
- */
-
-import escapeStringRegexp from "escape-string-regexp"
-import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, TERMINAL_PUNCTUATION, UNICODE_SYMBOLS } from "./constants.js"
+import { cachedRegExp, DEFAULT_SEPARATOR, escapeStringRegexp, getEscapedSeparator, LATIN_LETTERS, TERMINAL_PUNCTUATION, UNICODE_SYMBOLS } from "./constants.js"
 
 const {
   EM_DASH,
@@ -14,15 +9,9 @@ const {
   MODIFIER_LETTER_APOSTROPHE,
 } = UNICODE_SYMBOLS
 
-/** Joined string of all terminal punctuation characters for use in regex character classes. */
 const TERMINAL_PUNCTUATION_CLASS = TERMINAL_PUNCTUATION.join("")
 
-/**
- * Maximum consecutive closing quotes the punctuation-placement regexes will
- * traverse in a single match (e.g., '". for two-deep nesting). Bounded to keep
- * the regex linear on pathological inputs that contain many closing quotes
- * without any following period or comma.
- */
+// Bounded to keep punctuation-placement regexes linear on pathological inputs.
 const MAX_NESTED_QUOTES = 4
 
 export const PUNCTUATION_STYLES = ["american", "british", "german", "french", "none"] as const
@@ -35,7 +24,6 @@ export interface QuoteOptions {
   punctuationStyle?: PunctuationStyle
 }
 
-/** Convert straight single quotes to curly quotes and apostrophes */
 function convertSingleQuotes(text: string, sep: string): string {
   const escapedSep = getEscapedSeparator({ separator: sep })
 
@@ -86,11 +74,8 @@ function convertSingleQuotes(text: string, sep: string): string {
   return text
 }
 
-/**
- * Convert unmatched RSQ after s/S to MLA (plural possessives like dogs', Bayes').
- * Tracks LSQ/RSQ balance left-to-right so that paired closing quotes
- * (e.g., 'yes' where s precedes RSQ) remain RSQ.
- */
+// Converts unmatched RSQ after s/S to MLA (plural possessives).
+// Tracks LSQ/RSQ balance so paired closing quotes remain RSQ.
 function convertUnmatchedPluralPossessives(text: string, sep: string): string {
   let singleQuoteBalance = 0
   return text.replace(
@@ -116,9 +101,6 @@ function convertUnmatchedPluralPossessives(text: string, sep: string): string {
   )
 }
 
-/**
- * Build the beginning-double-quote regex pattern from named fragments.
- */
 function buildBeginningDoublePattern(escapedSep: string, rawEscSep: string): string {
   // Consuming boundary (not a lookbehind): variable-width lookbehinds
   // with alternation cause ReDoS. Re-emitted via $<boundary> in the replacement.
@@ -140,7 +122,6 @@ function buildBeginningDoublePattern(escapedSep: string, rawEscSep: string): str
   return `${boundary}${beforeCapture}["](?:${afterConditions.join("|")})`
 }
 
-/** Convert straight double quotes to curly quotes */
 function convertDoubleQuotes(text: string, sep: string): string {
   const rawEscSep = escapeStringRegexp(sep)
   const escapedSep = getEscapedSeparator({ separator: sep })
@@ -166,18 +147,8 @@ function convertDoubleQuotes(text: string, sep: string): string {
 }
 
 /**
- * Build a regex that matches a punctuation mark sitting OUTSIDE one or more
- * consecutive closing quotes, for American-style inside-the-quotes placement.
- *
- * Shape: `<non-terminal>(sepBefore)(quotes)(sepAfter)<punctuation>`
- *
- * - The lookbehind ensures the char just before the match isn't already terminal
- *   punctuation (so we don't rewrite, e.g., "Stop!".).
- * - `quotes` matches 1 to MAX_NESTED_QUOTES closing quotes (possibly separated
- *   by element-boundary markers). The bound keeps the regex linear on
- *   pathological inputs — unbounded `*` causes catastrophic backtracking when
- *   many closing quotes appear with no following punctuation.
- * - `punctuationPattern` is the trailing pattern (e.g. `,` or `(?!\.\.\.)\.`).
+ * Matches punctuation OUTSIDE consecutive closing quotes (American style).
+ * `quotes` is bounded to MAX_NESTED_QUOTES to prevent catastrophic backtracking.
  */
 function buildOutsidePunctuationRegex(escapedSep: string, punctuationPattern: string): RegExp {
   const closingQuoteClass = `[${RIGHT_SINGLE_QUOTE}${RIGHT_DOUBLE_QUOTE}]`
@@ -192,10 +163,6 @@ function buildOutsidePunctuationRegex(escapedSep: string, punctuationPattern: st
   return cachedRegExp(pattern, "g")
 }
 
-/**
- * Move a punctuation mark sitting outside one or more consecutive closing
- * quotes to the inside (American style): `Hello'".` → `Hello.'"`.
- */
 function moveOutsideToInside(
   text: string,
   escapedSep: string,
@@ -206,7 +173,6 @@ function moveOutsideToInside(
   return text.replace(regex, `$<sepBefore>${replacementChar}$<quotes>$<sepAfter>`)
 }
 
-/** Apply American or British punctuation style */
 function applyPunctuationStyle(text: string, sep: string, style: PunctuationStyle): string {
   const escapedSep = getEscapedSeparator({ separator: sep })
 
@@ -238,11 +204,8 @@ function applyPunctuationStyle(text: string, sep: string, style: PunctuationStyl
   return text
 }
 
-/**
- * Normalize German quotes back to American for idempotent re-processing.
- * Tracks „..." (U+201E/U+201C) and ‚...' (U+201A/U+2018) pairs so that
- * the ambiguous closer characters are mapped to the correct American equivalents.
- */
+// Normalize German quotes back to American for idempotent re-processing.
+// Tracks „..." and ‚...' pairs so ambiguous closers map correctly.
 function normalizeGermanQuotes(text: string): string {
   const DLQ = UNICODE_SYMBOLS.DOUBLE_LOW_9_QUOTE
   const SLQ = UNICODE_SYMBOLS.SINGLE_LOW_9_QUOTE
@@ -280,7 +243,6 @@ function normalizeGermanQuotes(text: string): string {
   return chars.join("")
 }
 
-/** Remap American curly quotes to German low-9 style. Safe because apostrophes are still MLA at this stage. */
 function applyGermanQuotes(text: string): string {
   return text
     .replaceAll(LEFT_DOUBLE_QUOTE, UNICODE_SYMBOLS.DOUBLE_LOW_9_QUOTE)
@@ -289,11 +251,8 @@ function applyGermanQuotes(text: string): string {
     .replaceAll(RIGHT_SINGLE_QUOTE, LEFT_SINGLE_QUOTE)
 }
 
-/**
- * Normalize French guillemets back to American for idempotent re-processing.
- * Strips either NBSP or NNBSP padding — older outputs used NBSP before the
- * fix to the Unicode CLDR / Imprimerie nationale prescription of NNBSP.
- */
+// Normalize French guillemets back to American for idempotent re-processing.
+// Strips either NBSP or NNBSP padding (older outputs used NBSP).
 function normalizeFrenchQuotes(text: string): string {
   const innerSpace = `[${UNICODE_SYMBOLS.NBSP}${UNICODE_SYMBOLS.NNBSP}]`
   return text
@@ -301,12 +260,7 @@ function normalizeFrenchQuotes(text: string): string {
     .replace(cachedRegExp(`${innerSpace}?${UNICODE_SYMBOLS.RIGHT_GUILLEMET}`, "g"), RIGHT_DOUBLE_QUOTE)
 }
 
-/**
- * Remap American curly double quotes to French guillemets with NNBSP padding.
- * Uses U+202F (NARROW NO-BREAK SPACE) per Unicode CLDR fr locale and
- * Imprimerie nationale's "Lexique des règles typographiques" (6th ed., 2002),
- * which prescribe a narrow non-breaking space — not U+00A0 — inside `« … »`.
- */
+// Uses U+202F (NARROW NO-BREAK SPACE) per Unicode CLDR and Imprimerie nationale.
 function applyFrenchQuotes(text: string): string {
   return text
     .replaceAll(LEFT_DOUBLE_QUOTE, `${UNICODE_SYMBOLS.LEFT_GUILLEMET}${UNICODE_SYMBOLS.NNBSP}`)
@@ -318,13 +272,11 @@ interface LocaleQuoteTransform {
   apply: (text: string) => string
 }
 
-/** Locale-specific normalize (pre-pipeline) and apply (post-pipeline) functions. */
 const localeQuoteTransforms: Partial<Record<PunctuationStyle, LocaleQuoteTransform>> = {
   german: { normalize: normalizeGermanQuotes, apply: applyGermanQuotes },
   french: { normalize: normalizeFrenchQuotes, apply: applyFrenchQuotes },
 }
 
-/** Shared quote-processing pipeline. Returns text with MLA for apostrophes. */
 function processQuotes(text: string, options: QuoteOptions): string {
   const sep = options.separator ?? DEFAULT_SEPARATOR
   const punctuationStyle = options.punctuationStyle ?? "american"

package/src/rehype.ts

@@ -1,12 +1,3 @@
-/**
- * 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 { Element, ElementContent, Parent, Root, RootContent, Text } from "hast"
 import type { Transformer } from "unified"
 
@@ -16,29 +7,16 @@ import { transform, type TransformOptions } from "./index.js"
 import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
 import { formatErrorString, transformTextNodes } from "./utils.js"
 
-/** Predicate that decides whether an HTML element should be skipped during transformation. */
 type ElementPredicate = (node: Element) => boolean
 
-/** Function that transforms a plain-text string (e.g. smart quotes, dashes). */
 type TextTransformer = (input: string) => string
 
-/**
- * Predicate that decides whether an individual text node should be excluded
- * from transformation. Called after element-level `shouldSkip`, so it is
- * never invoked for text inside elements that are already skipped.
- *
- * `ancestors` is the chain of Element parents for the text node, ordered
- * root first, nearest last.
- */
+/** Per-text-node skip predicate, called after element-level `shouldSkip`. */
 export type TextNodeSkipPredicate = (
   textNode: Text,
   ancestors: readonly Element[],
 ) => boolean
 
-/**
- * Options shared by functions that flatten and transform text nodes inside
- * an element tree.
- */
 export interface ElementTransformOptions {
   /**
    * Optional per-text-node skip predicate. When it returns `true` for a
@@ -49,9 +27,6 @@ export interface ElementTransformOptions {
   shouldSkipText?: TextNodeSkipPredicate
 }
 
-/**
- * Options for the rehype-punctilio plugin.
- */
 export interface RehypePunctilioOptions
   extends TransformOptions,
     ElementTransformOptions {
@@ -75,18 +50,6 @@ export interface RehypePunctilioOptions
 
 const DEFAULT_SKIP_TAGS = ["code", "pre", "script", "style", "kbd", "var", "samp", "template", "math", "svg"]
 
-/**
- * Flattens text nodes from an element tree into a single array.
- *
- * Pass `options.shouldSkipText` to exclude individual text nodes from the
- * result. Applied after element-level `shouldSkip`, so the hook is never
- * invoked for text inside an already-skipped element.
- *
- * @example
- * ```ts
- * const textNodes = flattenTextNodes(paragraphElement, (el) => el.tagName === 'code')
- * ```
- */
 export function flattenTextNodes(
   node: Element | ElementContent,
   shouldSkip: ElementPredicate,
@@ -136,15 +99,6 @@ function flattenTextNodesImpl(
   return []
 }
 
-/**
- * Extracts concatenated text content from an element.
- *
- * @example
- * ```ts
- * const text = getTextContent(paragraphElement)
- * // Returns "Hello, world!" for <p>Hello, <em>world!</em></p>
- * ```
- */
 export function getTextContent(
   node: Element,
   shouldSkip: ElementPredicate = () => false
@@ -154,16 +108,6 @@ export function getTextContent(
     .join("")
 }
 
-/**
- * Recursively finds the first text node in a tree of HTML elements.
- * Returns 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
@@ -187,21 +131,8 @@ export function getFirstTextNode(
 const QUOTE_OPENERS = new Set(["\u201C"])
 const CLOSER_TO_OPENER: Record<string, string> = { "\u201D": "\u201C" }
 
-/**
- * Validates that smart double quotes in a text string are properly matched.
- *
- * Only checks double quotes (\u201C/\u201D). Single quotes are intentionally
- * excluded because \u2019 (right single quote) doubles as an apostrophe,
- * making balance-checking unreliable.
- *
- * @throws Error if double quotes are mismatched
- *
- * @example
- * ```ts
- * assertSmartQuotesMatch('\u201CHello\u201D') // OK
- * assertSmartQuotesMatch('\u201CHello')        // throws Error
- * ```
- */
+// Only checks double quotes \u2014 single quotes are excluded because
+// U+2019 doubles as an apostrophe, making balance-checking unreliable.
 export function assertSmartQuotesMatch(input: string): void {
   if (!input) return
 
@@ -225,38 +156,9 @@ export function assertSmartQuotesMatch(input: string): void {
 }
 
 /**
- * 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
- *
- * When `checkInvariance` is true, also verifies that the transform produces
- * the same result with and without markers — i.e.,
- * `stripMarkers(transform(textWithMarkers)) === transform(stripMarkers(text))`.
- * Useful for debugging transforms that accidentally interact with markers.
- *
- * Pass `options.shouldSkipText` to opt individual text nodes out of
- * transformation without skipping their enclosing element; skipped text
- * nodes keep their original `.value`.
- *
- * @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
- * )
- * ```
+ * Transforms element text using the separator-marking technique. When
+ * `checkInvariance` is true, verifies `stripMarkers(transform(marked)) ===
+ * transform(stripMarkers(text))` for debugging marker interactions.
  */
 export function transformElement(
   node: Element,
@@ -299,12 +201,8 @@ export function transformElement(
   }
 }
 
-/**
- * HTML block-level elements. When a transformable element has a block-level
- * child, its children are processed independently rather than as a single
- * unit. This prevents merging text across semantically independent blocks
- * (e.g., separate paragraphs inside a div).
- */
+// Block children cause per-block processing to avoid merging text across
+// semantically independent blocks (e.g., separate <p>s inside a <div>).
 const BLOCK_ELEMENTS = new Set([
   "address", "article", "aside", "blockquote", "details", "dialog",
   "dd", "div", "dl", "dt", "fieldset", "figcaption", "figure",
@@ -313,10 +211,6 @@ const BLOCK_ELEMENTS = new Set([
   "p", "pre", "section", "table", "ul",
 ])
 
-/**
- * HTML elements that can contain transformable text content.
- * We traverse into these to find text nodes to transform.
- */
 const TRANSFORMABLE_ELEMENTS = new Set([
   "p",
   "em",
@@ -374,11 +268,6 @@ const TRANSFORMABLE_ELEMENTS = new Set([
   "rp",
 ])
 
-/**
- * Checks whether an element has any text node descendants (skipping elements
- * matched by shouldSkip). Returns as soon as one is found — avoids allocating
- * an array of all text nodes just to check existence.
- */
 function hasTextDescendant(
   node: Element | ElementContent,
   shouldSkip: ElementPredicate,
@@ -403,20 +292,6 @@ function hasTextDescendant(
   return false
 }
 
-/**
- * Collects elements that should have text transformations applied.
- *
- * An element is collected as a single transformation unit when it:
- * 1. Has direct text children (original behavior), OR
- * 2. Has text descendants and NO block-level children — meaning all its
- *    content is inline (phrasing) and should share transformation context
- *    (e.g., `<p><em>"Hello</em><span>, world"</span></p>`).
- *
- * When an element has block-level children, we recurse so each block
- * is processed independently (e.g., `<div><p>A</p><p>B</p></div>`).
- *
- * @param alreadyTransformed - Elements already processed; skipped during traversal to avoid redundant work
- */
 export function collectTransformableElements(
   node: Element,
   shouldSkip: ElementPredicate,
@@ -462,11 +337,6 @@ export function collectTransformableElements(
   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) {
@@ -481,30 +351,6 @@ function markDescendants(node: Element, set: Set<Element>, depth: number = 0): v
   }
 }
 
-/**
- * Rehype plugin that applies punctilio typography transformations to HTML.
- *
- * @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> {

package/src/remark.ts

@@ -1,12 +1,3 @@
-/**
- * Remark plugin for applying punctilio typography transformations to Markdown.
- *
- * This plugin integrates punctilio with the unified/remark ecosystem,
- * allowing you to apply smart typography transformations to Markdown ASTs.
- *
- * @packageDocumentation
- */
-
 import type { PhrasingContent, Root, Text } from "mdast"
 import type { Transformer } from "unified"
 
@@ -18,21 +9,10 @@ import { transformTextNodes } from "./utils.js"
 
 export type RemarkPunctilioOptions = TransformOptions
 
-/**
- * MDAST node types that contain phrasing (inline) content and should
- * have their text transformed as a single unit.
- */
 const PHRASING_CONTAINERS = new Set(["paragraph", "heading", "tableCell"])
 
-/**
- * MDAST node types whose text content should not be transformed.
- */
 const SKIP_TYPES = new Set(["inlineCode", "html"])
 
-/**
- * Recursively collects text nodes from a phrasing content tree,
- * skipping code and HTML nodes.
- */
 function flattenTextNodes(
   node: PhrasingContent,
   depth: number = 0
@@ -59,28 +39,6 @@ function flattenTextNodes(
   return []
 }
 
-/**
- * Remark plugin that applies punctilio typography transformations to Markdown.
- *
- * @example
- * ```ts
- * import { unified } from 'unified'
- * import remarkParse from 'remark-parse'
- * import remarkStringify from 'remark-stringify'
- * import remarkPunctilio from 'punctilio/remark'
- *
- * const result = await unified()
- *   .use(remarkParse)
- *   .use(remarkPunctilio, {
- *     punctuationStyle: 'american',
- *     dashStyle: 'american',
- *   })
- *   .use(remarkStringify)
- *   .process('"Hello," she said -- "it\'s nice."')
- *
- * // Output Markdown will have smart quotes and em-dashes
- * ```
- */
 export function remarkPunctilio(
   options: RemarkPunctilioOptions = {}
 ): Transformer<Root, Root> {