punctilio 3.11.3 → 3.11.4

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punctilio",
-  "version": "3.11.3",
+  "version": "3.11.4",
   "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
   "type": "module",
   "sideEffects": false,
@@ -92,7 +92,7 @@
     "hastscript": "9.0.1",
     "jest": "29.7.0",
     "lint-staged": "16.4.0",
-    "prettier": "3.8.1",
+    "prettier": "3.8.3",
     "recheck": "4.5.0",
     "rehype-parse": "9.0.1",
     "rehype-stringify": "10.0.1",
@@ -105,10 +105,10 @@
     "smartquotes": "2.3.2",
     "smartypants": "0.2.2",
     "tipograph": "0.7.4",
-    "ts-jest": "29.4.9",
-    "tsx": "4.21.0",
+    "ts-jest": "29.4.11",
+    "tsx": "4.22.3",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.59.2",
+    "typescript-eslint": "8.59.4",
     "typograf": "7.7.0",
     "unified": "11.0.5"
   },

package/src/cli.ts

@@ -1,10 +1,4 @@
 #!/usr/bin/env node
-/**
- * Command-line entry point: format Markdown and HTML files in place,
- * or check whether they would be reformatted (for use as a pre-commit hook).
- *
- * @packageDocumentation
- */
 
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
@@ -42,11 +36,7 @@ const RULE_MARKERS = ["-", "*", "_"] as const
 const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"])
 const HTML_EXTENSIONS = new Set([".html", ".htm"])
 
-/**
- * Shape of `program.opts()` after parsing. Fields named after their CLI
- * flags (camelCased by commander). `commander.choices()` guarantees the
- * literal types at runtime; we assert them at the boundary.
- */
+// Fields match commander's camelCased flag names; .choices() guarantees literals at runtime.
 interface ParsedFlags {
   check?: boolean
   cache?: boolean
@@ -147,8 +137,7 @@ function isGlobPattern(pattern: string): boolean {
   return /[*?[\]{}]/.test(pattern)
 }
 
-// Non-glob positionals pass through as literal paths so they error loudly
-// if missing, matching the prior behavior of `punctilio file.md`.
+// Non-glob positionals pass through as literal paths so they error loudly if missing.
 async function discoverFiles(
   patterns: string[],
   cwd: string,
@@ -213,12 +202,7 @@ function saveCache(location: string, cache: Cache): void {
   writeFileSync(location, JSON.stringify(cache))
 }
 
-/**
- * Cache key for a file. Always cwd-relative so a project that moves
- * directories (or syncs the cache file across machines via the same
- * repo layout) keeps hitting the cache. Files outside cwd appear as
- * `../foo.md` and still hash consistently.
- */
+// cwd-relative so the cache survives directory moves and cross-machine syncs.
 function cacheKey(filePath: string, cwd: string): string {
   return relative(cwd, filePath)
 }
@@ -249,12 +233,7 @@ async function transformContent(input: string, type: FileType, opts: CliOptions)
   return type === "md" ? transformMarkdown(input, opts) : transformHtml(input, opts)
 }
 
-/**
- * Preserves whether the original file ends with a trailing newline.
- * The unified pipelines for Markdown and HTML both unconditionally append
- * one, so without this adjustment every file lacking a trailing newline
- * would always appear as needing a rewrite.
- */
+// Unified pipelines unconditionally append a trailing newline; undo if original lacked one.
 function matchTrailingNewline(original: string, formatted: string): string {
   const originalHas = original.endsWith("\n")
   const formattedHas = formatted.endsWith("\n")
@@ -282,12 +261,7 @@ async function readPackageVersion(): Promise<string> {
   }
 }
 
-/**
- * Runs the CLI with the given arguments and I/O streams.
- *
- * @returns Exit code: 0 if no changes (or all changes written),
- * 1 if `--check` saw a file that would change, 2 for usage errors.
- */
+/** Returns exit code: 0 success, 1 `--check` saw changes, 2 usage error. */
 export async function runCli(args: string[], io: CliIO): Promise<number> {
   const version = await readPackageVersion()
   const program = buildProgram(version, io)

package/src/constants.ts

@@ -1,13 +1,8 @@
-/**
- * Shared Unicode constants and regex utilities.
- */
-
 import escapeStringRegexp from "escape-string-regexp"
 import QuickLRU from "quick-lru"
 
-/**
- * Unicode symbols for typography transformations.
- */
+export { escapeStringRegexp }
+
 export const UNICODE_SYMBOLS = {
   ELLIPSIS: "\u2026",
   MULTIPLICATION: "\u00D7",
@@ -82,13 +77,7 @@ export const UNICODE_SYMBOLS = {
   GREEK_QUESTION_MARK: "\u037E", // ; (visually identical to ASCII semicolon)
 } as const
 
-/**
- * All terminal punctuation characters that signal a quote is "already terminated".
- * Covers ASCII, ellipsis, punctuation ligatures, interrobang, CJK fullwidth,
- * CJK ideographic, Arabic, and Greek question mark.
- *
- * Used as a regex character class fragment in quotes.ts and as a test fixture.
- */
+/** All terminal punctuation chars for regex character classes (ASCII through CJK/Arabic/Greek). */
 export const TERMINAL_PUNCTUATION = [
   "!", "?", ".", ",", ";", ":",
   UNICODE_SYMBOLS.ELLIPSIS,
@@ -128,13 +117,8 @@ export const DEFAULT_SEPARATOR = "\uE000\uE001"
 const ESCAPED_DEFAULT_SEPARATOR = escapeStringRegexp(DEFAULT_SEPARATOR)
 
 /**
- * Returns the regex-escaped separator string for the given options,
- * wrapped in a non-capturing group so that quantifiers like `?` and `*`
- * apply to the entire separator sequence (critical for multi-character
- * separators like the default U+E000 U+E001).
- *
- * @param options - Object with an optional `separator` field
- * @returns Regex-escaped separator string wrapped in `(?:...)`
+ * Regex-escaped separator wrapped in `(?:...)` so quantifiers apply to
+ * the entire multi-character sequence.
  */
 export function getEscapedSeparator(options: { separator?: string }): string {
   const escaped = options.separator
@@ -143,10 +127,7 @@ export function getEscapedSeparator(options: { separator?: string }): string {
   return `(?:${escaped})`
 }
 
-/**
- * Characters that have special meaning in regular expressions.
- * Used for testing that separator escaping works correctly.
- */
+/** Regex-special characters, used for testing separator escaping. */
 export const REGEX_SPECIAL_CHARS = [".", "*", "+", "?", "^", "$", "[", "]", "\\", "|", "(", ")"] as const
 
 /**
@@ -179,45 +160,22 @@ export function wordBoundaryEnd(escapedSeparator: string): string {
   return `\\b(?!${escapedSeparator}{0,${MAX_BOUNDARY_SEPARATORS}}\\w)`
 }
 
-/**
- * Pattern string for space characters (regular space, tab, non-breaking space,
- * and narrow no-break space). Use inside regex character classes: `[${SPACE_CHARS}]`
- */
+/** Space chars for regex `[...]`: regular space, tab, NBSP, NNBSP. */
 export const SPACE_CHARS = ` \t${UNICODE_SYMBOLS.NBSP}${UNICODE_SYMBOLS.NNBSP}`
 
-/**
- * Pattern string for the non-breaking space characters only (NBSP and NNBSP).
- * Use inside regex character classes: `[${NBSP_CHARS}]`. Used by patterns
- * that need to detect existing nbsp chains without also matching plain spaces.
- */
+/** Non-breaking space chars only (NBSP, NNBSP) for regex `[...]`. */
 export const NBSP_CHARS = `${UNICODE_SYMBOLS.NBSP}${UNICODE_SYMBOLS.NNBSP}`
 
-/**
- * Maximum recursion depth used by the rehype and remark tree walkers.
- * Guards against stack overflow from maliciously or accidentally deep
- * AST nesting. Shared so both plugins behave identically.
- */
+/** Max AST recursion depth; guards against stack overflow from deep nesting. */
 export const MAX_RECURSION_DEPTH = 1000
 
-/**
- * Canonical issue tracker URL, referenced in user-facing error messages
- * so there's exactly one source of truth if the repository ever moves.
- */
+/** Single source of truth for issue tracker URL in error messages. */
 export const ISSUES_URL = "https://github.com/alexander-turner/punctilio/issues"
 
-/**
- * LRU cache for compiled RegExp objects keyed by `pattern + '\0' + flags`.
- * Avoids recompiling identical regexes on every function call (common
- * when using the default separator). Capped to prevent unbounded growth.
- */
 export const MAX_REGEX_CACHE_SIZE = 1000
 const regexCache = new QuickLRU<string, RegExp>({ maxSize: MAX_REGEX_CACHE_SIZE })
 
-/**
- * Returns a cached RegExp for the given pattern and flags.
- * Resets `lastIndex` before returning to prevent stale state when
- * callers use `.test()` or `.exec()` on global-flag regexes.
- */
+/** Returns a cached RegExp, resetting `lastIndex` to prevent stale global-flag state. */
 export function cachedRegExp(pattern: string, flags: string): RegExp {
   const key = `${pattern}\0${flags}`
   let re = regexCache.get(key)
@@ -229,19 +187,12 @@ export function cachedRegExp(pattern: string, flags: string): RegExp {
   return re
 }
 
-/**
- * Returns all currently cached RegExp objects. Exported for test
- * introspection only (e.g. ReDoS scanning every compiled pattern).
- * @internal
- */
+/** @internal */
 export function getCachedRegExps(): RegExp[] {
   return Array.from(regexCache.values())
 }
 
-/**
- * Clears the regex cache. Exported for test isolation only.
- * @internal
- */
+/** @internal */
 export function clearRegexCache(): void {
   regexCache.clear()
 }

package/src/dashes.ts

@@ -1,7 +1,3 @@
-/**
- * Dash transformation: hyphens → em-dashes, en-dashes, minus signs.
- */
-
 import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, UNICODE_SYMBOLS, wordBoundaryEnd, wordBoundaryStart } from "./constants.js"
 import { namedGroups } from "./utils.js"
 
@@ -17,19 +13,10 @@ export interface DashOptions {
 
 const { EN_DASH, EM_DASH, MINUS, LEFT_DOUBLE_QUOTE, RIGHT_DOUBLE_QUOTE, LEFT_SINGLE_QUOTE, RIGHT_SINGLE_QUOTE } = UNICODE_SYMBOLS
 
-/**
- * Characters that, when preceding a number, prevent it from being
- * treated as the start of a number range. This prevents false positives
- * in model names like "Llama-2-7B" where "2-7" should not become "2–7".
- */
+// Prevents false-positive ranges in model names like "Llama-2-7B".
 export const numberRangeDisallowedPrefixes = ["-", EN_DASH, EM_DASH, MINUS] as const
 
-/**
- * Regex character-class fragment built from {@link numberRangeDisallowedPrefixes}.
- * Non-ASCII dashes are escaped to `\uXXXX` form so the fragment is safe to
- * embed inside a `[...]` class regardless of the regex source encoding.
- * Computed once at module load — the inputs are `const`.
- */
+// Non-ASCII dashes escaped to \uXXXX for safe embedding in [...] classes.
 const DISALLOWED_PREFIX_CLASS_FRAGMENT = numberRangeDisallowedPrefixes
   .map((c) => (c === "-" ? c : `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`))
   .join("")
@@ -185,10 +172,6 @@ export function minusReplace(text: string, options: DashOptions = {}): string {
   return text
 }
 
-/**
- * Convert surrounded dashes to em/en dashes.
- * Handles patterns like "word - word" → "word—word" (Chicago) or "word – word" (Oxford).
- */
 function convertParentheticalDashes(text: string, sep: string, style: DashStyle): string {
   const localizedDash = style === "british" ? EN_DASH : EM_DASH
   const maybeSpace = style === "british" ? " " : ""
@@ -239,13 +222,8 @@ function convertParentheticalDashes(text: string, sep: string, style: DashStyle)
   return text
 }
 
-/**
- * Normalize em-dash spacing for Chicago style (American).
- * Removes all spaces around em-dashes per Chicago Manual of Style.
- *
- * TODO: Handle interrupted-then-resumed speech within quotes, where Chicago
- * allows a space after the dash: "Don't inter— Hey! Who threw that?"
- */
+// TODO: Handle interrupted-then-resumed speech within quotes, where Chicago
+// allows a space after the dash: "Don't inter— Hey! Who threw that?"
 function normalizeEmDashSpacing(text: string, sep: string): string {
   const escapedSep = getEscapedSeparator({ separator: sep })
 
@@ -265,7 +243,6 @@ function normalizeEmDashSpacing(text: string, sep: string): string {
   return text
 }
 
-/** Full dash transformation. */
 export function hyphenReplace(text: string, options: DashOptions = {}): string {
   const sep = options.separator ?? DEFAULT_SEPARATOR
   const style = options.dashStyle ?? "american"

package/src/html.ts

@@ -1,14 +1,3 @@
-/**
- * Convenience module for HTML-to-HTML typography transformations.
- *
- * Provides a single function that takes HTML input and returns
- * typographically improved HTML output.
- *
- * Requires `unified`, `rehype-parse`, and `rehype-stringify` to be installed.
- *
- * @packageDocumentation
- */
-
 import { unified } from "unified"
 import rehypeParse from "rehype-parse"
 import rehypeStringify from "rehype-stringify"
@@ -17,9 +6,6 @@ import QuickLRU from "quick-lru"
 import { rehypePunctilio, type RehypePunctilioOptions } from "./rehype.js"
 import { stableStringify } from "./utils.js"
 
-/**
- * Options for the HTML transform pipeline.
- */
 export interface HtmlOptions extends RehypePunctilioOptions {
   /**
    * Whether to parse the input as an HTML fragment (no implicit `<html>`,
@@ -43,29 +29,11 @@ const processorCache = new QuickLRU<string, ReturnType<typeof createProcessor>>(
   maxSize: MAX_PROCESSOR_CACHE_SIZE,
 })
 
-/**
- * Clears the processor cache. Exported for test isolation only.
- * @internal
- */
+/** @internal */
 export function clearProcessorCache(): void {
   processorCache.clear()
 }
 
-/**
- * Transforms HTML text with typographic improvements.
- *
- * Parses the input as HTML, applies punctilio typography transformations,
- * and serializes back to HTML. The unified processor pipeline is cached
- * and reused across calls with identical options.
- *
- * @example
- * ```ts
- * import { transformHtml } from 'punctilio/html'
- *
- * await transformHtml('<p>"Hello" -- world</p>')
- * // → '<p>“Hello”—world</p>'
- * ```
- */
 export async function transformHtml(
   input: string,
   options: HtmlOptions = {}

package/src/index.ts

@@ -1,13 +1,3 @@
-/**
- * punctilio - Smart typography transformations
- *
- * A library for converting plain ASCII punctuation into typographically
- * correct Unicode characters. Handles smart quotes, em-dashes, en-dashes,
- * minus signs, ellipses, multiplication signs, and more.
- *
- * @packageDocumentation
- */
-
 export { DEFAULT_SEPARATOR, UNICODE_SYMBOLS } from "./constants.js"
 import type { PunctuationStyle } from "./quotes.js"
 export {
@@ -194,36 +184,6 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
   dashStyle: "american",
 }
 
-/**
- * Applies all typography transformations: smart quotes, proper dashes,
- * and symbol improvements.
- *
- * This is a convenience function that applies transformations in sequence:
- * 1. hyphenReplace (em-dashes, en-dashes, minus signs)
- * 2. primeMarks (feet/inches, arcminutes/arcseconds)
- * 3. niceQuotes (smart quotes)
- * 4. symbolTransform (ellipses, multiplication, math symbols, legal symbols, arrows)
- * 5. fractions (disabled by default)
- * 6. degrees (disabled by default)
- * 7. superscript (disabled by default)
- * 8. ligatures (disabled by default)
- * 9. collapseSpaces (collapses multiple spaces into one)
- * 10. nbsp (non-breaking spaces, enabled by default)
- *
- * @example
- * ```ts
- * import { transform } from 'punctilio'
- *
- * transform('"Hello," she said - "it\'s pages 1-5."')
- * // → '"Hello," she said—"it's pages 1–5."'
- *
- * transform('Wait... 5x5 != 25 (c) 2024')
- * // → 'Wait… 5×5 ≠ 25 © 2024'
- *
- * transform('Add 1/2 cup', { fractions: true })
- * // → 'Add ½ cup'
- * ```
- */
 export function transform(text: string, options: TransformOptions = {}): string {
   const separator = options.separator ?? DEFAULT_SEPARATOR
 

package/src/markdown.ts

@@ -1,14 +1,3 @@
-/**
- * Convenience module for Markdown-to-Markdown typography transformations.
- *
- * Provides a single function that takes Markdown input and returns
- * typographically improved Markdown output.
- *
- * Requires `unified`, `remark-parse`, and `remark-stringify` to be installed.
- *
- * @packageDocumentation
- */
-
 import { unified } from "unified"
 import remarkParse from "remark-parse"
 import remarkGfm from "remark-gfm"
@@ -18,9 +7,6 @@ import QuickLRU from "quick-lru"
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
 import { stableStringify } from "./utils.js"
 
-/**
- * Options for the Markdown transform pipeline.
- */
 export interface MarkdownOptions extends RemarkPunctilioOptions {
   /**
    * Character for emphasis (`*text*` vs `_text_`) and strong (`**text**` vs `__text__`).
@@ -41,9 +27,6 @@ export interface MarkdownOptions extends RemarkPunctilioOptions {
   ruleMarker?: "-" | "*" | "_"
 }
 
-/**
- * Creates a unified processor pipeline for Markdown typography transformations.
- */
 function createProcessor(options: MarkdownOptions) {
   const {
     emphasisMarker,
@@ -78,31 +61,11 @@ const processorCache = new QuickLRU<string, ReturnType<typeof createProcessor>>(
   maxSize: MAX_PROCESSOR_CACHE_SIZE,
 })
 
-/**
- * Clears the processor cache. Exported for test isolation only.
- * @internal
- */
+/** @internal */
 export function clearProcessorCache(): void {
   processorCache.clear()
 }
 
-/**
- * Transforms Markdown text with typographic improvements.
- *
- * Parses the input as Markdown, applies punctilio typography transformations
- * (smart quotes, em-dashes, ellipses, etc.), and serializes back to Markdown.
- *
- * The unified processor pipeline is cached and reused across calls with
- * identical options, avoiding redundant pipeline construction.
- *
- * @example
- * ```ts
- * import { transformMarkdown } from 'punctilio/markdown'
- *
- * await transformMarkdown('"Hello" -- world')
- * // → '\u201CHello\u201D\u2014world'
- * ```
- */
 export async function transformMarkdown(
   input: string,
   options: MarkdownOptions = {}

package/src/nbsp.ts

@@ -1,13 +1,3 @@
-/**
- * Non-breaking space transformations for improved typography.
- *
- * Inserts non-breaking spaces (U+00A0) in positions where line breaks
- * would be typographically undesirable: after short words, between
- * numbers and units, before orphaned last words, etc.
- *
- * @module nbsp
- */
-
 import { cachedRegExp, getEscapedSeparator, LATIN_LETTERS, NBSP_CHARS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
 
 const {
@@ -26,15 +16,11 @@ export interface NbspOptions {
   separator?: string
 }
 
-/** Space pattern matching regular space, tab, and nbsp. */
 const SPACE = `[${SPACE_CHARS}]`
 
 const UNICODE_UPPERCASE = "\\p{Lu}"
 
-/**
- * Common units for the number-unit nbsp pattern. Only matches these specific
- * abbreviations after a number to avoid false positives like "chapter 3 above".
- */
+/** Only specific abbreviations are matched to avoid false positives. */
 export const UNITS: readonly string[] = [
   // Length
   "km", "cm", "mm", "mi", "ft", "yd", "nm", "pm", "m",
@@ -111,17 +97,8 @@ 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}]`
 
-/**
- * Adds non-breaking space after short words (1-2 letters) to prevent them from
- * being left alone at the end of a line.
- *
- * Skips when the short word is already preceded by an NBSP from an earlier
- * transform, or when this match immediately follows the previous one
- * (back-to-back short words in the same pass). Either case would bind three
- * or more words into a single line-break atom — defeating widow protection.
- *
- * @example "a cat" → "a\u00A0cat", "I am" → "I\u00A0am"
- */
+// 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)
   const pattern = cachedRegExp(
@@ -137,11 +114,6 @@ export function nbspAfterShortWords(text: string, options: NbspOptions = {}): st
   })
 }
 
-/**
- * Adds non-breaking space between numbers and common units.
- *
- * @example "100 km" → "100\u00A0km", "5 kg" → "5\u00A0kg"
- */
 export function nbspBetweenNumberAndUnit(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const wbe = wordBoundaryEnd(sep)
@@ -152,30 +124,12 @@ export function nbspBetweenNumberAndUnit(text: string, options: NbspOptions = {}
   return text.replace(pattern, `$<digit>$<marker1>${NBSP}$<marker2>$<unit>`)
 }
 
-/**
- * Maximum length, in characters, of the "last word" that gets an NBSP
- * glued to its preceding space. Short enough that a typical English word
- * qualifies but an entire trailing URL or long token does not. Only affects
- * widow prevention at end-of-string and paragraph breaks.
- */
 const MAX_LAST_WORD_LENGTH = 10
 
-/**
- * Maximum word length, in characters, considered for the cascade check.
- * Bounded so the lookbehind in `nbspBeforeLastWord` stays ReDoS-safe.
- */
+// Bounded so the lookbehind stays ReDoS-safe.
 const MAX_MIDDLE_WORD_LENGTH = 15
 
-/**
- * Adds non-breaking space before the last word to prevent widows.
- *
- * Only applies to final words of 1 to {@link MAX_LAST_WORD_LENGTH} characters,
- * at end of string or paragraph break (\n\n). Uses non-multiline mode so $
- * matches only the true end of string.
- *
- * Skips when the second-to-last word is already glued backwards via NBSP,
- * so the phrase doesn't become a 3-word non-breaking atom.
- */
+// 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}})`
@@ -187,12 +141,6 @@ export function nbspBeforeLastWord(text: string, options: NbspOptions = {}): str
   return text.replace(pattern, `${NBSP}$<lastWord>$<ending>`)
 }
 
-/**
- * Adds non-breaking space after reference abbreviations (Fig., Vol., p., etc.)
- * when followed by a number.
- *
- * @example "Fig. 1" → "Fig.\u00A01", "p. 42" → "p.\u00A042"
- */
 export function nbspAfterReferenceAbbreviations(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const pattern = cachedRegExp(
@@ -202,12 +150,6 @@ export function nbspAfterReferenceAbbreviations(text: string, options: NbspOptio
   return text.replace(pattern, `$<abbrev>$<marker>${NBSP}`)
 }
 
-/**
- * Adds non-breaking space after section (§) and paragraph (¶) symbols
- * when followed by a number.
- *
- * @example "§ 5" → "§\u00A05"
- */
 export function nbspAfterSectionSymbols(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const pattern = cachedRegExp(
@@ -217,11 +159,6 @@ export function nbspAfterSectionSymbols(text: string, options: NbspOptions = {})
   return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
 }
 
-/**
- * Adds non-breaking space after honorific titles when followed by a capitalized name.
- *
- * @example "Dr. Smith" → "Dr.\u00A0Smith", "Mr. Jones" → "Mr.\u00A0Jones"
- */
 export function nbspAfterHonorifics(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const pattern = cachedRegExp(
@@ -231,12 +168,6 @@ export function nbspAfterHonorifics(text: string, options: NbspOptions = {}): st
   return text.replace(pattern, `$<honorific>$<marker>${NBSP}`)
 }
 
-/**
- * Adds non-breaking space after copyright, registered, and trademark
- * symbols when followed by a year or capitalized name.
- *
- * @example "© 2024" → "©\u00A02024", "® Brand" → "®\u00A0Brand"
- */
 export function nbspAfterCopyrightSymbols(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const pattern = cachedRegExp(
@@ -246,11 +177,6 @@ export function nbspAfterCopyrightSymbols(text: string, options: NbspOptions = {
   return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
 }
 
-/**
- * Adds non-breaking space between initials (e.g., "J. K. Rowling").
- *
- * @example "J. K. Rowling" → "J.\u00A0K.\u00A0Rowling"
- */
 export function nbspBetweenInitials(text: string, options: NbspOptions = {}): string {
   const sep = getEscapedSeparator(options)
   const pattern = cachedRegExp(
@@ -262,13 +188,7 @@ export function nbspBetweenInitials(text: string, options: NbspOptions = {}): st
 
 type NbspFn = (text: string, options: NbspOptions) => string
 
-/**
- * Ordered list of nbsp transforms. Specific patterns (honorifics, abbreviations,
- * initials) come first so they claim their matches before the generic
- * `nbspAfterShortWords`. For example, "No. 5" is matched by
- * `nbspAfterReferenceAbbreviations` first, preventing `nbspAfterShortWords`
- * from also matching "No" as a 2-letter short word.
- */
+// Specific patterns first so they claim matches before generic nbspAfterShortWords.
 const NBSP_TRANSFORMS: NbspFn[] = [
   nbspAfterHonorifics,
   nbspAfterReferenceAbbreviations,
@@ -280,7 +200,6 @@ const NBSP_TRANSFORMS: NbspFn[] = [
   nbspBeforeLastWord,
 ]
 
-/** Apply all non-breaking space transformations in sequence. */
 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.