punctilio 3.10.0 → 3.11.0

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.10.0",
+  "version": "3.11.0",
   "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
   "type": "module",
   "sideEffects": false,

package/src/cli.ts

@@ -9,7 +9,7 @@
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { readFile, writeFile } from "node:fs/promises"
-import { dirname, extname, join, relative, resolve } from "node:path"
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
 import { Command, CommanderError, Option } from "commander"
@@ -21,6 +21,7 @@ import { transformMarkdown, type MarkdownOptions } from "./markdown.js"
 import { transformHtml, type HtmlOptions } from "./html.js"
 import { PUNCTUATION_STYLES, type PunctuationStyle } from "./quotes.js"
 import { DASH_STYLES, type DashStyle } from "./dashes.js"
+import { stableStringify } from "./utils.js"
 
 type CliOptions = MarkdownOptions & HtmlOptions
 type FileType = "md" | "html"
@@ -182,18 +183,27 @@ function hashString(s: string): string {
 }
 
 function hashOptions(opts: CliOptions): string {
-  const stable = Object.entries(opts)
-    .filter(([, v]) => v !== undefined)
-    .sort(([a], [b]) => a.localeCompare(b))
-  return hashString(JSON.stringify(stable))
+  return hashString(stableStringify(opts))
 }
 
-function loadCache(location: string): Cache {
+function loadCache(location: string, stderr: NodeJS.WritableStream): Cache {
   if (!existsSync(location)) return { files: {} }
   try {
     const parsed = JSON.parse(readFileSync(location, "utf8")) as Cache
-    return parsed.files ? parsed : { files: {} }
+    if (!parsed.files) {
+      stderr.write(`Warning: cache at ${location} is missing the "files" key; discarding.\n`)
+      return { files: {} }
+    }
+    // Drop absolute-path keys carried over from a pre-cwd-relative version
+    // of the cache. They never match modern lookups, so keeping them
+    // forever would just bloat the cache file on every save.
+    const files: Record<string, CacheEntry> = {}
+    for (const [k, v] of Object.entries(parsed.files)) {
+      if (!isAbsolute(k)) files[k] = v
+    }
+    return { files }
   } catch {
+    stderr.write(`Warning: cache at ${location} could not be parsed; discarding.\n`)
     return { files: {} }
   }
 }
@@ -203,6 +213,16 @@ 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.
+ */
+function cacheKey(filePath: string, cwd: string): string {
+  return relative(cwd, filePath)
+}
+
 function buildOptions(flags: ParsedFlags): CliOptions {
   const opts: CliOptions = {}
   if (flags.punctuationStyle) opts.punctuationStyle = flags.punctuationStyle
@@ -344,18 +364,22 @@ async function runValidated(
   const cacheLocation = flags.cache === false
     ? undefined
     : resolve(cwd, flags.cacheLocation ?? DEFAULT_CACHE_LOCATION)
-  const cache = cacheLocation ? loadCache(cacheLocation) : undefined
+  const cache = cacheLocation ? loadCache(cacheLocation, io.stderr) : undefined
   const optionsHash = cache ? hashOptions(opts) : ""
 
   let anyChanged = false
   for (const path of files) {
     const type = inferFileType(path, flags.type)
     const original = await readFile(path, "utf8")
+    const key = cache ? cacheKey(path, cwd) : ""
     if (cache) {
-      const entry = cache.files[path]
-      if (entry?.contentHash === hashString(original)
-          && entry.optionsHash === optionsHash
-          && entry.version === version) continue
+      const entry = cache.files[key]
+      if (
+        entry !== undefined &&
+        entry.contentHash === hashString(original) &&
+        entry.optionsHash === optionsHash &&
+        entry.version === version
+      ) continue
     }
 
     const formatted = matchTrailingNewline(original, await transformContent(original, type, opts))
@@ -370,7 +394,7 @@ async function runValidated(
       }
     }
     if (cache && (unchanged || !check)) {
-      cache.files[path] = { contentHash: hashString(formatted), optionsHash, version }
+      cache.files[key] = { contentHash: hashString(formatted), optionsHash, version }
     }
   }
 

package/src/dashes.ts

@@ -3,6 +3,7 @@
  */
 
 import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryStart, wordBoundaryEnd, getEscapedSeparator, cachedRegExp } from "./constants.js"
+import { namedGroups } from "./utils.js"
 
 export const DASH_STYLES = ["american", "british", "none"] as const
 export type DashStyle = (typeof DASH_STYLES)[number]
@@ -69,7 +70,13 @@ export function enDashNumberRange(text: string, options: DashOptions = {}): stri
   text = text.replace(
     cachedRegExp(positiveRangePattern, "g"),
     (...args) => {
-      const groups = args.at(-1) as Record<string, string>
+      const groups = namedGroups<{
+        precedingAreaCode?: string
+        start: string
+        end: string
+        following?: string
+        suffix?: string
+      }>(args)
       if (groups.following) return args[0] as string
       const startNum = groups.start.replace(cachedRegExp(chr, "g"), "")
       const endNum = groups.end.replace(cachedRegExp(chr, "g"), "")
@@ -96,7 +103,13 @@ export function enDashNumberRange(text: string, options: DashOptions = {}): stri
       "g"
     ),
     (...args) => {
-      const groups = args.at(-1) as Record<string, string>
+      const groups = namedGroups<{
+        start: string
+        neg?: string
+        end: string
+        following?: string
+        suffix?: string
+      }>(args)
       if (groups.following) return args[0] as string
       return `${groups.start}${EN_DASH}${groups.neg ? MINUS : ""}${groups.end}${groups.suffix ?? ""}`
     }
@@ -121,7 +134,14 @@ export function enDashDateRange(text: string, options: DashOptions = {}): string
   return text.replace(
     cachedRegExp(`${wb}(?<startMonth>${monthPattern})${startYear}(?<preSep>${chr}?)(?<preSpace> ?)-(?<postSpace> ?)(?<postSep>${chr}?)(?<endMonth>${monthPattern})${endYear}${wbe}`, "g"),
     (...args) => {
-      const groups = args.at(-1) as Record<string, string>
+      const groups = namedGroups<{
+        startMonth: string
+        startYear?: string
+        preSep: string
+        endMonth: string
+        endYear?: string
+        postSep: string
+      }>(args)
       const [pre, post] = dashStyle === "british" ? [" ", " "] : ["", ""]
       return `${groups.startMonth}${groups.startYear || ""}${groups.preSep}${pre}${EN_DASH}${post}${groups.postSep}${groups.endMonth}${groups.endYear || ""}`
     }

package/src/html.ts

@@ -15,6 +15,7 @@ import rehypeStringify from "rehype-stringify"
 import QuickLRU from "quick-lru"
 
 import { rehypePunctilio, type RehypePunctilioOptions } from "./rehype.js"
+import { stableStringify } from "./utils.js"
 
 /**
  * Options for the HTML transform pipeline.
@@ -77,9 +78,7 @@ export async function transformHtml(
     return String(result)
   }
 
-  const optionsKey = JSON.stringify(
-    Object.entries(options).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b))
-  )
+  const optionsKey = stableStringify(options)
 
   let processor = processorCache.get(optionsKey)
   if (!processor) {

package/src/index.ts

@@ -173,7 +173,7 @@ 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 { nbspTransform as nbspTransformFn } from "./nbsp.js"
-import { assertSeparatorCountPreserved, formatErrorString } from "./utils.js"
+import { assertSeparatorCountPreserved, filterUndefined, formatErrorString } from "./utils.js"
 import { DEFAULT_SEPARATOR, ISSUES_URL, UNICODE_SYMBOLS } from "./constants.js"
 
 export { assertSeparatorAbsent, assertSeparatorCountPreserved, countSeparators, transformTextNodes } from "./utils.js"
@@ -210,10 +210,6 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
  * 9. collapseSpaces (collapses multiple spaces into one)
  * 10. nbsp (non-breaking spaces, enabled by default)
  *
- * @param text - The text to transform
- * @param options - Configuration options
- * @returns The text with all typography improvements applied
- *
  * @example
  * ```ts
  * import { transform } from 'punctilio'
@@ -231,52 +227,46 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
 export function transform(text: string, options: TransformOptions = {}): string {
   const separator = options.separator ?? DEFAULT_SEPARATOR
 
-  // Validate separator: must be non-empty and contain only BMP characters.
-  // for...of iterates by code point; surrogate pairs (non-BMP) yield a
-  // two-UTF16-unit string, so ch.length > 1 detects them.
   if (separator.length === 0) {
     throw new Error("Invalid separator: must not be empty.")
   }
-  for (const ch of separator) {
-    if (ch.length > 1) {
-      throw new Error(
-        `Invalid separator: must contain only BMP characters (no characters outside the Basic Multilingual Plane). ` +
-        `Received "${separator}" which contains a non-BMP character.`
-      )
-    }
+  // Non-BMP characters are encoded in UTF-16 as surrogate pairs in the range
+  // U+D800–U+DFFF. A surrogate code unit (paired or lone) means the separator
+  // would survive some regexes as a single char and split others as two units.
+  if (/[\uD800-\uDFFF]/.test(separator)) {
+    throw new Error(
+      `Invalid separator: must contain only BMP characters (no characters outside the Basic Multilingual Plane). ` +
+      `Received "${separator}" which contains a non-BMP character.`
+    )
   }
 
   const original = text
-  // Filter undefined so { nbsp: undefined } uses the default, not falsy override
-  const definedOptions = Object.fromEntries(
-    Object.entries(options).filter(([, v]) => v !== undefined)
-  ) as TransformOptions
-  const { symbols, fractions, degrees, superscript, ligatures, nbsp, collapseSpaces, checkIdempotency, ...separatorOpts } = { ...defaultOpts, ...definedOptions }
+  const { symbols, fractions, degrees, superscript, ligatures, nbsp, collapseSpaces, checkIdempotency, ...pipelineOpts } = { ...defaultOpts, ...filterUndefined(options) }
 
-  text = hyphenReplace(text, separatorOpts)
-  if (separatorOpts.punctuationStyle !== "none") {
-    text = primeMarks(text, separatorOpts)
+  text = hyphenReplace(text, pipelineOpts)
+  if (pipelineOpts.punctuationStyle !== "none") {
+    text = primeMarks(text, pipelineOpts)
   }
-  text = niceQuotes(text, separatorOpts)
+  text = niceQuotes(text, pipelineOpts)
 
   if (symbols) {
-    text = symbolTransform(text, separatorOpts)
+    text = symbolTransform(text, pipelineOpts)
   }
 
   if (fractions) {
-    text = fractionsTransform(text, separatorOpts)
+    text = fractionsTransform(text, pipelineOpts)
   }
 
   if (degrees) {
-    text = degreesTransform(text, separatorOpts)
+    text = degreesTransform(text, pipelineOpts)
   }
 
   if (superscript) {
-    text = superscriptTransform(text, separatorOpts)
+    text = superscriptTransform(text, pipelineOpts)
   }
 
   if (ligatures) {
-    text = ligaturesTransform(text, separatorOpts)
+    text = ligaturesTransform(text, pipelineOpts)
   }
 
   if (collapseSpaces) {
@@ -284,7 +274,7 @@ export function transform(text: string, options: TransformOptions = {}): string
   }
 
   if (nbsp) {
-    text = nbspTransformFn(text, separatorOpts)
+    text = nbspTransformFn(text, pipelineOpts)
   }
 
   assertSeparatorCountPreserved(original, text, separator, "transform")

package/src/markdown.ts

@@ -16,6 +16,7 @@ import remarkStringify from "remark-stringify"
 import QuickLRU from "quick-lru"
 
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
+import { stableStringify } from "./utils.js"
 
 /**
  * Options for the Markdown transform pipeline.
@@ -94,10 +95,6 @@ export function clearProcessorCache(): void {
  * The unified processor pipeline is cached and reused across calls with
  * identical options, avoiding redundant pipeline construction.
  *
- * @param input - The Markdown text to transform
- * @param options - Configuration options for both the transform and serializer
- * @returns The typographically improved Markdown text
- *
  * @example
  * ```ts
  * import { transformMarkdown } from 'punctilio/markdown'
@@ -110,9 +107,7 @@ export async function transformMarkdown(
   input: string,
   options: MarkdownOptions = {}
 ): Promise<string> {
-  const optionsKey = JSON.stringify(
-    Object.entries(options).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b))
-  )
+  const optionsKey = stableStringify(options)
 
   let processor = processorCache.get(optionsKey)
   if (!processor) {

package/src/prettier-plugin.ts

@@ -30,6 +30,19 @@ 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
+  // shape here so the cast lives in one well-commented place.
+  const transformer = remarkPunctilio(opts) as (tree: Root) => void | Promise<void>
+  await transformer(ast)
+}
+
 const plugin: Plugin = {
   parsers: {
     markdown: {
@@ -38,8 +51,7 @@ const plugin: Plugin = {
         const ast = await upstreamMarkdown.parse(text, options)
         const searchFrom = typeof options.filepath === "string" ? dirname(options.filepath) : process.cwd()
         const opts = await loadPunctilioConfig(searchFrom)
-        const transform = remarkPunctilio(opts) as (tree: Root) => void
-        transform(ast)
+        await runRemarkPunctilio(opts, ast)
         return ast
       },
     },

package/src/quotes.ts

@@ -215,7 +215,9 @@ function applyPunctuationStyle(text: string, sep: string, style: PunctuationStyl
     text = moveOutsideToInside(text, escapedSep, ".", `(?!\\.\\.\\.)\\.`)
     // Comma outside → inside: Hello", → Hello,"
     text = moveOutsideToInside(text, escapedSep, ",", `,`)
-  } else if (style === "british" || style === "german" || style === "french") {
+  } else {
+    // Every non-"american" non-"none" style (british/german/french) places
+    // punctuation outside the quotes.
     // Period inside → outside: "Hello." → "Hello".
     // No terminal punctuation guard — "Stop!." inside is always wrong; move the period out.
     // Match ALL consecutive closing quotes so nested quotes like .'" become '". in one pass.

package/src/rehype.ts

@@ -78,13 +78,9 @@ const DEFAULT_SKIP_TAGS = ["code", "pre", "script", "style", "kbd", "var", "samp
 /**
  * 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 options - Optional flattening options. Pass `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.
- * @returns Array of Text nodes
+ * 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
@@ -143,10 +139,6 @@ function flattenTextNodesImpl(
 /**
  * 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)
@@ -164,10 +156,7 @@ export function getTextContent(
 
 /**
  * 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
+ * Returns null if no text nodes exist.
  *
  * @example
  * ```ts
@@ -205,7 +194,6 @@ const CLOSER_TO_OPENER: Record<string, string> = { "\u201D": "\u201C" }
  * excluded because \u2019 (right single quote) doubles as an apostrophe,
  * making balance-checking unreliable.
  *
- * @param input - The text to validate
  * @throws Error if double quotes are mismatched
  *
  * @example
@@ -245,20 +233,17 @@ export function assertSmartQuotesMatch(input: string): void {
  * 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
- * @param options - Optional transform options. Pass `shouldSkipText` here to
- *   opt individual text nodes out of transformation without skipping their
- *   enclosing element. Skipped text nodes keep their original `.value`.
+ * 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
+ * @throws Error if `checkInvariance` is true and the invariance check fails
  *
  * @example
  * ```ts
@@ -430,11 +415,7 @@ function hasTextDescendant(
  * 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 node - The root element to search from
- * @param shouldSkip - Function to determine which elements to skip
- * @param depth - Current recursion depth (internal use)
  * @param alreadyTransformed - Elements already processed; skipped during traversal to avoid redundant work
- * @returns Array of elements that contain transformable text
  */
 export function collectTransformableElements(
   node: Element,
@@ -503,9 +484,6 @@ function markDescendants(node: Element, set: Set<Element>, depth: number = 0): v
 /**
  * Rehype plugin that applies punctilio typography transformations to HTML.
  *
- * @param options - Plugin configuration options
- * @returns Unified transformer function
- *
  * @example
  * ```ts
  * import { unified } from 'unified'

package/src/remark.ts

@@ -32,10 +32,6 @@ const SKIP_TYPES = new Set(["inlineCode", "html"])
 /**
  * Recursively collects text nodes from a phrasing content tree,
  * skipping code and HTML nodes.
- *
- * @param node - The phrasing content node to collect from
- * @param depth - Current recursion depth (internal use)
- * @returns Array of Text nodes
  */
 function flattenTextNodes(
   node: PhrasingContent,
@@ -66,9 +62,6 @@ function flattenTextNodes(
 /**
  * Remark plugin that applies punctilio typography transformations to Markdown.
  *
- * @param options - Plugin configuration options
- * @returns Unified transformer function
- *
  * @example
  * ```ts
  * import { unified } from 'unified'

package/src/symbols.ts

@@ -3,6 +3,7 @@
  */
 
 import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryEnd, SPACE_CHARS, cachedRegExp, getEscapedSeparator } from "./constants.js"
+import { namedGroups } from "./utils.js"
 
 export interface SymbolOptions {
   /** Boundary marker for HTML element boundaries. Default: "\uE000\uE001" */
@@ -49,7 +50,7 @@ export function ellipsis(text: string, options: SymbolOptions = {}): string {
   // into one ellipsis.
   const pattern = cachedRegExp(`\\.(?:[${SPACE_CHARS}]|(?<sep1>${chr}))?\\.(?:[${SPACE_CHARS}]?|(?<sep2>${chr})?)\\.`, "g")
   text = text.replace(pattern, (...args) => {
-    const { sep1, sep2 } = args.at(-1) as Record<string, string | undefined>
+    const { sep1, sep2 } = namedGroups<{ sep1?: string; sep2?: string }>(args)
     return ELLIPSIS + (sep1 ?? "") + (sep2 ?? "")
   })
 
@@ -94,7 +95,7 @@ export function multiplication(text: string, options: SymbolOptions = {}): strin
   )
 
   text = text.replace(chainPattern, (...args) => {
-    const { firstNum, rest } = args.at(-1) as Record<string, string>
+    const { firstNum, rest } = namedGroups<{ firstNum: string; rest: string }>(args)
     // Skip hexadecimal: 0x... or 0X...
     if (firstNum === "0" && /^x/i.test(rest)) return args[0] as string
 
@@ -111,7 +112,13 @@ export function multiplication(text: string, options: SymbolOptions = {}): strin
         "gy"
       ),
       (...innerArgs) => {
-        const groups = innerArgs.at(-1) as Record<string, string>
+        const groups = namedGroups<{
+          pre: string
+          spaceBefore: string
+          spaceAfter: string
+          post: string
+          num: string
+        }>(innerArgs)
         const space = groups.spaceBefore || groups.spaceAfter ? " " : ""
         return `${groups.pre}${space}${MULTIPLICATION}${space}${groups.post}${groups.num}`
       }
@@ -164,7 +171,7 @@ export function mathSymbols(text: string, options: SymbolOptions = {}): string {
     // and preserves the text-node-count invariant in transformTextNodes.
     const pattern = cachedRegExp(`${left}(?<sep>${chr})?${right}${lookahead(chr)}`, "g")
     text = text.replace(pattern, (...args) => {
-      const { sep } = args.at(-1) as Record<string, string | undefined>
+      const { sep } = namedGroups<{ sep?: string }>(args)
       return `${replacement}${sep ?? ""}`
     })
   }
@@ -348,7 +355,13 @@ function balancedPrimeReplacer(primeChar: string, escapedSeparator: string) {
   // Replace callback: (match, ...captures, offset, fullString, namedGroups)
   return (...args: unknown[]): string => {
     const fullMatch = args[0] as string
-    const groups = args.at(-1) as Record<string, string | undefined>
+    const groups = namedGroups<{
+      digit?: string
+      sep?: string
+      afterSep?: string
+      contraction?: string
+      trailing?: string
+    }>(args)
 
     // Contraction (letter + quote + letter): skip entirely
     if (groups.contraction !== undefined) {

package/src/utils.ts

@@ -40,8 +40,6 @@ export function formatErrorString(content: string, label: string): string {
  * Throws if any text node contains the separator character, which would
  * corrupt the split/join mechanism used by the rehype and remark plugins.
  *
- * @param textValues - The raw text values to check
- * @param separator - The separator character
  * @throws Error if the separator is found in any text value
  */
 export function assertSeparatorAbsent(textValues: string[], separator: string): void {
@@ -88,9 +86,8 @@ interface TextNode {
  * 4. Splits the result back on the separator and writes each fragment
  *    back into the corresponding text node.
  *
- * @param textNodes - The text nodes to transform (mutated in place)
- * @param transformFn - The transformation function to apply
- * @param separator - The marker string used to track node boundaries
+ * `textNodes` is mutated in place.
+ *
  * @throws Error if the transformation alters the number of text nodes
  */
 export function transformTextNodes(
@@ -122,10 +119,6 @@ export function transformTextNodes(
  * Validates that a transformation preserved the separator count.
  * Throws an error if separators were added or removed.
  *
- * @param original - The original text before transformation
- * @param transformed - The text after transformation
- * @param separator - The separator character to check (default: DEFAULT_SEPARATOR)
- * @param transformName - Name of the transform for error messages (default: "transform")
  * @throws Error if separator count changed
  */
 export function assertSeparatorCountPreserved(
@@ -144,3 +137,43 @@ export function assertSeparatorCountPreserved(
     )
   }
 }
+
+/**
+ * Returns a copy of `obj` with `undefined`-valued keys removed.
+ * Used so caller-supplied `{ foo: undefined }` doesn't override a default.
+ *
+ * @internal
+ */
+export function filterUndefined<T extends object>(obj: T): Partial<T> {
+  const result: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) result[k] = v
+  }
+  return result as Partial<T>
+}
+
+/**
+ * Returns a deterministic JSON-style string for an options object: drops
+ * `undefined` values and sorts keys, so equivalent option sets always
+ * produce the same string (suitable as a cache or LRU key).
+ *
+ * @internal
+ */
+export function stableStringify(obj: object): string {
+  const entries = Object.entries(obj)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => a.localeCompare(b))
+  return JSON.stringify(entries)
+}
+
+/**
+ * Extracts the named-groups object from a `String.prototype.replace`
+ * callback's argument tuple. The last element is always the groups
+ * object when the regex has named captures. Callers supply the group
+ * shape via the type parameter to localise the unavoidable type cast.
+ *
+ * @internal
+ */
+export function namedGroups<G>(args: unknown[]): G {
+  return args[args.length - 1] as G
+}