punctilio 3.11.2 → 3.11.4

package/src/rehype.ts

@@ -1,44 +1,22 @@
-/**
- * Rehype plugin for applying punctilio typography transformations to HTML.
- *
- * This plugin integrates punctilio with the unified/rehype ecosystem,
- * allowing you to apply smart typography transformations to HTML ASTs.
- *
- * @packageDocumentation
- */
-
-import type { Root, Element, Text, ElementContent, Parent, RootContent } from "hast"
+import type { Element, ElementContent, Parent, Root, RootContent, Text } from "hast"
 import type { Transformer } from "unified"
 
-import { visitParents, SKIP } from "unist-util-visit-parents"
+import { SKIP, visitParents } from "unist-util-visit-parents"
 
 import { transform, type TransformOptions } from "./index.js"
 import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
-import { transformTextNodes, formatErrorString } from "./utils.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,13 +1,4 @@
-/**
- * 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 { Root, PhrasingContent, Text } from "mdast"
+import type { PhrasingContent, Root, Text } from "mdast"
 import type { Transformer } from "unified"
 
 import { visitParents } from "unist-util-visit-parents"
@@ -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> {

package/src/symbols.ts

@@ -1,8 +1,4 @@
-/**
- * Symbol transformations: ellipses, multiplication, math symbols, arrows.
- */
-
-import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryEnd, SPACE_CHARS, cachedRegExp, getEscapedSeparator } from "./constants.js"
+import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
 import { namedGroups } from "./utils.js"
 
 export interface SymbolOptions {
@@ -138,19 +134,10 @@ export function multiplication(text: string, options: SymbolOptions = {}): strin
   return text
 }
 
-/**
- * Builds a negative lookahead that must see through an optional separator
- * so e.g. `!<SEP>=` is correctly recognized as the start of `!==`.
- */
 type MathLookaheadBuilder = (escapedSeparator: string) => string
 
-/** [leftChars, rightChars, negativeLookaheadBuilder, replacement] */
 type MathSymbolRule = [string, string, MathLookaheadBuilder, string]
 
-/**
- * Math symbol replacement map.
- * The separator is inserted between left and right when building the regex.
- */
 const MATH_SYMBOL_MAP: MathSymbolRule[] = [
   ["!", "=", (chr) => `(?!${chr}?=)`, NOT_EQUAL],
   ["\\+/", "-", () => "", PLUS_MINUS],
@@ -178,18 +165,11 @@ export function mathSymbols(text: string, options: SymbolOptions = {}): string {
   return text
 }
 
-/** Predicate that decides whether a legal symbol should be converted based on surrounding text. */
 type ContextPredicate = (before: string, after: string) => boolean
 
-/**
- * Context window, in characters, examined on each side of a legal-symbol
- * candidate. Large enough to fit a 4-digit year plus surrounding whitespace
- * or the word "copyright" plus a space, but small enough that the slice
- * stays cheap on long inputs.
- */
+// 25 chars: fits "copyright " or a 4-digit year with padding, without making slicing expensive.
 const LEGAL_SYMBOL_CONTEXT_WINDOW = 25
 
-/** Returns true when the context window ends with a path-like fragment (slash + non-whitespace). */
 const isPathContext = (before: string): boolean => {
   const parts = before.split(/\s+/)
   const trailing = parts[parts.length - 1]
@@ -197,11 +177,6 @@ const isPathContext = (before: string): boolean => {
   return slashIdx >= 0 && slashIdx < trailing.length - 1
 }
 
-/**
- * Context-aware replacement for legal symbols like (c), (r), (tm).
- * Extracts surrounding text, strips separator characters from the context
- * windows, and delegates the convert/skip decision to a predicate.
- */
 function contextAwareLegalReplace(
   text: string,
   pattern: RegExp,
@@ -249,19 +224,9 @@ export function legalSymbols(text: string, options: SymbolOptions = {}): string
   return text
 }
 
-/**
- * Builds an arrow-shape regex fragment from the escaped separator pattern.
- * The separator may appear between the halves of a bidirectional `<->`.
- */
 type ArrowPatternBuilder = (escapedSeparator: string) => string
 
-/**
- * Arrow pattern map: shape builder → Unicode symbol.
- *
- * The leading `<` on the bidi pattern anchors its repeated-dash-run group
- * so it stays linear-time; the right/left arrows can't anchor that way, so
- * they only admit one optional separator at the un-anchored end.
- */
+// Leading `<` on bidi anchors the dash-run group for linear time.
 const ARROW_RULES: readonly [ArrowPatternBuilder, string][] = [
   [(sep) => `<${sep}?-+(?:${sep}-+)*${sep}?>`, ARROW_LEFT_RIGHT],
   [(sep) => `-+${sep}?>`, ARROW_RIGHT],
@@ -292,7 +257,6 @@ export function arrows(text: string, options: SymbolOptions = {}): string {
   return text
 }
 
-/** Convert "20 C" or "20 F" to "20 °C" or "20 °F". Only matches uppercase C/F. */
 export function degrees(text: string, options: SymbolOptions = {}): string {
   const chr = getEscapedSeparator(options)
 
@@ -309,7 +273,7 @@ export function degrees(text: string, options: SymbolOptions = {}): string {
 }
 
 /**
- * Build a regex that matches all quote characters in priority order:
+ * Matches quote characters in priority order:
  * 1. Prime candidate: digit + quote + non-letter (e.g., 5', 12")
  * 2. Contraction: letter + quote + letter (e.g., it's, don't, O'Brien)
  * 3. Trailing apostrophe: letter + quote + non-letter (e.g., dogs')
@@ -329,19 +293,9 @@ function buildQuoteClassificationPattern(
   )
 }
 
-/**
- * Replace callback that converts prime candidates while respecting quote balance.
- * Contractions and trailing apostrophes are recognized so they don't poison the
- * balance tracker. A prime candidate converts only when no unmatched opening
- * quote precedes it; otherwise it acts as a closing quote.
- *
- * For double primes (″): since ' and " are processed in separate passes,
- * 5'10" becomes 5′10" after the single-quote pass. Inside balanced double
- * quotes (e.g., "He is 5′10" tall"), the balance tracker would normally treat
- * the " after 10 as a closing quote. To handle this, we check whether the "
- * is preceded by ′ + digits — if so, it's inches notation and converts
- * regardless of balance.
- */
+// Converts prime candidates while tracking quote balance. A prime after a
+// digit converts only when no unmatched opener precedes it. Inside balanced
+// quotes, a ′+digits context (feet-inches like 5′10") still converts.
 function balancedPrimeReplacer(primeChar: string, escapedSeparator: string) {
   // Pre-compile the feet-inches context pattern for the double-prime pass.
   // Matches when the text before a prime candidate ends with ′ followed by
@@ -421,13 +375,8 @@ export function primeMarks(text: string, options: SymbolOptions = {}): string {
   return text
 }
 
-/** [numerator, denominator, unicodeChar] */
 type FractionRule = [string, string, string]
 
-/**
- * Supported Unicode fractions.
- * The regex alternation and lookup map are both derived from this list.
- */
 const FRACTION_TUPLES: FractionRule[] = [
   ["1", "4", UNICODE_SYMBOLS.FRACTION_1_4],
   ["1", "2", UNICODE_SYMBOLS.FRACTION_1_2],
@@ -504,7 +453,7 @@ export function superscriptOrdinal(text: string, options: SymbolOptions = {}): s
   })
 }
 
-/** Collapse multiple spaces (including tabs) to single space. Preserves the highest-priority space type present in the run: NBSP > NNBSP > regular. Leading whitespace at the start of a line (after `\n` or start-of-string) is preserved so indented blocks (e.g. HN-style code) survive. */
+// Preserves highest-priority space type (NBSP > NNBSP > regular) and leading indentation.
 export function collapseSpaces(text: string): string {
   return text.replace(cachedRegExp(`(?<=[^\\n${SPACE_CHARS}])[${SPACE_CHARS}]{2,}`, "g"), (match) => {
     if (match.includes(NBSP)) return NBSP
@@ -513,14 +462,9 @@ export function collapseSpaces(text: string): string {
   })
 }
 
-/** [firstChar, repeatedChar, replacement] */
 type LigatureRule = [string, string, string]
 
-/**
- * Punctuation ligature map.
- * Pattern: first(sep)?repeated(?:sep?repeated)* → replacement
- * Order matters: handle mixed punctuation first, then repeated
- */
+// Order matters: mixed punctuation first, then repeated.
 const PUNCTUATION_LIGATURE_MAP: LigatureRule[] = [
   ["\\?", "!", QUESTION_EXCLAMATION],  // ?!+ → ⁈
   ["!", "\\?", EXCLAMATION_QUESTION],  // !?+ → ⁉
@@ -528,7 +472,7 @@ const PUNCTUATION_LIGATURE_MAP: LigatureRule[] = [
   ["!", "!", "!"],                      // !!+ → ! (normalize)
 ]
 
-/** Convert ?? to ⁇, ?! to ⁈, !? to ⁉. Poor font support, disabled by default. */
+/** Convert ?? to ⁇, ?! to ⁈, !? to ⁉. Disabled by default (poor font support). */
 export function punctuationLigatures(text: string, options: SymbolOptions = {}): string {
   const chr = getEscapedSeparator(options)
   const sepPattern = cachedRegExp(chr, "g")
@@ -548,7 +492,6 @@ export function punctuationLigatures(text: string, options: SymbolOptions = {}):
   return text
 }
 
-/** Apply all symbol transforms. degrees/fractions excluded (too aggressive). */
 export function symbolTransform(text: string, options: SymbolOptions = {}): string {
   text = ellipsis(text, options)
   text = multiplication(text, options)

package/src/utils.ts

@@ -1,20 +1,10 @@
-/**
- * Utility functions for text transformation validation.
- *
- * @module utils
- */
-
 import { DEFAULT_SEPARATOR, ISSUES_URL } from "./constants.js"
 
-/** Threshold above which strings are truncated in error messages. */
 const ERROR_STRING_THRESHOLD = 2000
 
 /**
- * Formats a string for error messages. If the string exceeds the threshold,
- * truncates it and shows the total length.
- *
- * In Node.js environments, also writes the full content to stderr
- * so it's available in build logs for debugging.
+ * Formats a string for error messages, truncating above the threshold.
+ * Writes full content to stderr in Node.js so build logs capture it.
  */
 export function formatErrorString(content: string, label: string): string {
   if (content.length <= ERROR_STRING_THRESHOLD) {
@@ -36,12 +26,7 @@ export function formatErrorString(content: string, label: string): string {
   return `[${label}: ${JSON.stringify(truncated)}... (${content.length} chars total)]`
 }
 
-/**
- * Throws if any text node contains the separator character, which would
- * corrupt the split/join mechanism used by the rehype and remark plugins.
- *
- * @throws Error if the separator is found in any text value
- */
+/** Throws if any text node contains the separator (would corrupt split/join). */
 export function assertSeparatorAbsent(textValues: string[], separator: string): void {
   for (const value of textValues) {
     if (!value.includes(separator)) continue
@@ -57,9 +42,6 @@ export function assertSeparatorAbsent(textValues: string[], separator: string):
   }
 }
 
-/**
- * Counts non-overlapping occurrences of the separator string in the text.
- */
 export function countSeparators(text: string, separator: string = DEFAULT_SEPARATOR): number {
   if (separator.length === 0) return 0
   let count = 0
@@ -71,24 +53,15 @@ export function countSeparators(text: string, separator: string = DEFAULT_SEPARA
   return count
 }
 
-/** Minimal text-node interface shared by mdast.Text and hast.Text. */
 interface TextNode {
   value: string
 }
 
 /**
  * Applies a text transformation across an array of text nodes using the
- * separator-marking technique.
- *
- * 1. Validates no text node already contains the separator.
- * 2. Appends the separator to each node's value, concatenates into one string.
- * 3. Runs the transform function on the concatenated string.
- * 4. Splits the result back on the separator and writes each fragment
- *    back into the corresponding text node.
- *
- * `textNodes` is mutated in place.
- *
- * @throws Error if the transformation alters the number of text nodes
+ * separator-marking technique: appends the separator to each node's value,
+ * concatenates, transforms, then splits back on the separator and writes
+ * each fragment into the corresponding text node. Mutates `textNodes`.
  */
 export function transformTextNodes(
   textNodes: TextNode[],
@@ -115,12 +88,7 @@ export function transformTextNodes(
   })
 }
 
-/**
- * Validates that a transformation preserved the separator count.
- * Throws an error if separators were added or removed.
- *
- * @throws Error if separator count changed
- */
+/** Throws if a transformation changed the separator count. */
 export function assertSeparatorCountPreserved(
   original: string,
   transformed: string,
@@ -138,12 +106,7 @@ 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
- */
+/** Returns a copy of `obj` with `undefined`-valued keys removed. @internal */
 export function filterUndefined<T extends object>(obj: T): Partial<T> {
   const result: Record<string, unknown> = {}
   for (const [k, v] of Object.entries(obj)) {
@@ -152,13 +115,7 @@ export function filterUndefined<T extends object>(obj: T): Partial<T> {
   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
- */
+/** Deterministic JSON string for an options object, suitable as cache key. @internal */
 export function stableStringify(obj: object): string {
   const entries = Object.entries(obj)
     .filter(([, v]) => v !== undefined)
@@ -166,14 +123,7 @@ export function stableStringify(obj: object): string {
   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
- */
+/** Extracts named groups from a `.replace()` callback's arguments. @internal */
 export function namedGroups<G>(args: unknown[]): G {
   return args[args.length - 1] as G
 }