punctilio 3.11.2 → 3.11.4

package/src/index.ts

@@ -1,55 +1,31 @@
-/**
- * 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 { niceQuotes, classifyApostrophes, type QuoteOptions, type PunctuationStyle } from "./quotes.js"
+export { DEFAULT_SEPARATOR, UNICODE_SYMBOLS } from "./constants.js"
 import type { PunctuationStyle } from "./quotes.js"
 export {
-  hyphenReplace,
-  enDashNumberRange,
+  type DashOptions,
+  type DashStyle,
   enDashDateRange,
+  enDashNumberRange,
+  hyphenReplace,
   minusReplace,
   numberRangeDisallowedPrefixes,
-  type DashOptions,
-  type DashStyle,
 } from "./dashes.js"
 import type { DashStyle } from "./dashes.js"
 export {
-  ellipsis,
-  multiplication,
-  mathSymbols,
-  legalSymbols,
-  arrows,
-  degrees,
-  fractions,
-  primeMarks,
-  collapseSpaces,
-  superscriptOrdinal,
-  punctuationLigatures,
-  symbolTransform,
-  type SymbolOptions,
-} from "./symbols.js"
-export {
-  nbspAfterShortWords,
-  nbspBetweenNumberAndUnit,
-  nbspBeforeLastWord,
+  HONORIFICS,
+  nbspAfterCopyrightSymbols,
+  nbspAfterHonorifics,
   nbspAfterReferenceAbbreviations,
   nbspAfterSectionSymbols,
-  nbspAfterHonorifics,
-  nbspAfterCopyrightSymbols,
+  nbspAfterShortWords,
+  nbspBeforeLastWord,
   nbspBetweenInitials,
+  nbspBetweenNumberAndUnit,
+  type NbspOptions,
   nbspTransform,
-  UNITS,
-  HONORIFICS,
   REFERENCE_ABBREVIATIONS,
-  type NbspOptions,
+  UNITS,
 } from "./nbsp.js"
+export { classifyApostrophes, niceQuotes, type PunctuationStyle, type QuoteOptions } from "./quotes.js"
 
 export interface TransformOptions {
   /**
@@ -171,13 +147,27 @@ export interface TransformOptions {
 
 import { niceQuotes } from "./quotes.js"
 import { hyphenReplace } from "./dashes.js"
-import { symbolTransform, fractions as fractionsTransform, degrees as degreesTransform, superscriptOrdinal as superscriptTransform, primeMarks, collapseSpaces as collapseSpacesTransform, punctuationLigatures as ligaturesTransform } from "./symbols.js"
+import { collapseSpaces as collapseSpacesTransform, degrees as degreesTransform, fractions as fractionsTransform, punctuationLigatures as ligaturesTransform, primeMarks, superscriptOrdinal as superscriptTransform, symbolTransform } from "./symbols.js"
 import { nbspTransform as nbspTransformFn } from "./nbsp.js"
 import { assertSeparatorCountPreserved, filterUndefined, formatErrorString } from "./utils.js"
 import { DEFAULT_SEPARATOR, ISSUES_URL, UNICODE_SYMBOLS } from "./constants.js"
 
+export {
+  arrows,
+  collapseSpaces,
+  degrees,
+  ellipsis,
+  fractions,
+  legalSymbols,
+  mathSymbols,
+  multiplication,
+  primeMarks,
+  punctuationLigatures,
+  superscriptOrdinal,
+  type SymbolOptions,
+  symbolTransform,
+} from "./symbols.js"
 export { assertSeparatorAbsent, assertSeparatorCountPreserved, countSeparators, transformTextNodes } from "./utils.js"
-export { DEFAULT_SEPARATOR, UNICODE_SYMBOLS } from "./constants.js"
 export const MODIFIER_LETTER_APOSTROPHE = UNICODE_SYMBOLS.MODIFIER_LETTER_APOSTROPHE
 
 const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
@@ -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,14 +1,4 @@
-/**
- * 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 { UNICODE_SYMBOLS, LATIN_LETTERS, SPACE_CHARS, NBSP_CHARS, wordBoundaryEnd, getEscapedSeparator, cachedRegExp } from "./constants.js"
+import { cachedRegExp, getEscapedSeparator, LATIN_LETTERS, NBSP_CHARS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
 
 const {
   NBSP,
@@ -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.

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 { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS, TERMINAL_PUNCTUATION, getEscapedSeparator, cachedRegExp } 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"