punctilio 3.11.2 → 3.11.4

package/dist/utils.d.ts

@@ -1,76 +1,28 @@
 /**
- * Utility functions for text transformation validation.
- *
- * @module utils
- */
-/**
- * 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 declare 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.
- *
- * @throws Error if the separator is found in any text value
- */
+/** Throws if any text node contains the separator (would corrupt split/join). */
 export declare function assertSeparatorAbsent(textValues: string[], separator: string): void;
-/**
- * Counts non-overlapping occurrences of the separator string in the text.
- */
 export declare function countSeparators(text: string, separator?: string): number;
-/** 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 declare function transformTextNodes(textNodes: TextNode[], transformFn: (input: string) => string, separator: string): void;
-/**
- * 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 declare function assertSeparatorCountPreserved(original: string, transformed: string, separator?: string, transformName?: string): void;
-/**
- * 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 declare function filterUndefined<T extends object>(obj: T): 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 declare function stableStringify(obj: object): string;
-/**
- * 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 declare function namedGroups<G>(args: unknown[]): G;
 export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAanF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,CAS3F;AAED,sEAAsE;AACtE,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,EAAE,EACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACtC,SAAS,EAAE,MAAM,GAChB,IAAI,CAmBN;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAA0B,EACrC,aAAa,GAAE,MAAoB,GAClC,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAEjD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAanF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,CAS3F;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,EAAE,EACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACtC,SAAS,EAAE,MAAM,GAChB,IAAI,CAmBN;AAED,8DAA8D;AAC9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAA0B,EACrC,aAAa,GAAE,MAAoB,GAClC,IAAI,CAUN;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpE;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAEjD"}

package/dist/utils.js

@@ -1,17 +1,8 @@
-/**
- * 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, label) {
     if (content.length <= ERROR_STRING_THRESHOLD) {
@@ -29,12 +20,7 @@ export function formatErrorString(content, label) {
     const truncated = content.slice(0, ERROR_STRING_THRESHOLD);
     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, separator) {
     for (const value of textValues) {
         if (!value.includes(separator))
@@ -47,9 +33,6 @@ export function assertSeparatorAbsent(textValues, separator) {
             `Text: ${formatErrorString(value, "input")}`);
     }
 }
-/**
- * Counts non-overlapping occurrences of the separator string in the text.
- */
 export function countSeparators(text, separator = DEFAULT_SEPARATOR) {
     if (separator.length === 0)
         return 0;
@@ -63,17 +46,9 @@ export function countSeparators(text, separator = DEFAULT_SEPARATOR) {
 }
 /**
  * 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, transformFn, separator) {
     assertSeparatorAbsent(textNodes.map((n) => n.value), separator);
@@ -90,12 +65,7 @@ export function transformTextNodes(textNodes, transformFn, separator) {
         n.value = transformedFragments[index];
     });
 }
-/**
- * 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, transformed, separator = DEFAULT_SEPARATOR, transformName = "transform") {
     const originalCount = countSeparators(original, separator);
     const transformedCount = countSeparators(transformed, separator);
@@ -105,12 +75,7 @@ export function assertSeparatorCountPreserved(original, transformed, separator =
             `Include the input text that caused this error.`);
     }
 }
-/**
- * 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(obj) {
     const result = {};
     for (const [k, v] of Object.entries(obj)) {
@@ -119,27 +84,14 @@ export function filterUndefined(obj) {
     }
     return result;
 }
-/**
- * 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) {
     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
- */
+/** Extracts named groups from a `.replace()` callback's arguments. @internal */
 export function namedGroups(args) {
     return args[args.length - 1];
 }

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.2",
+  "version": "3.11.4",
   "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
   "type": "module",
   "sideEffects": false,
@@ -86,12 +86,13 @@
     "@types/node": "20.19.30",
     "@types/seedrandom": "3.0.8",
     "eslint": "9.39.2",
+    "eslint-plugin-perfectionist": "5.9.0",
     "eslint-plugin-redos": "4.5.0",
     "eslint-plugin-regexp": "3.1.0",
     "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",
@@ -104,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"
@@ -17,8 +11,8 @@ import { cosmiconfig } from "cosmiconfig"
 import ignore, { type Ignore } from "ignore"
 import { glob } from "tinyglobby"
 
-import { transformMarkdown, type MarkdownOptions } from "./markdown.js"
-import { transformHtml, type HtmlOptions } from "./html.js"
+import { type MarkdownOptions, transformMarkdown } from "./markdown.js"
+import { type HtmlOptions, transformHtml } from "./html.js"
 import { PUNCTUATION_STYLES, type PunctuationStyle } from "./quotes.js"
 import { DASH_STYLES, type DashStyle } from "./dashes.js"
 import { stableStringify } from "./utils.js"
@@ -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,8 +1,4 @@
-/**
- * Dash transformation: hyphens → em-dashes, en-dashes, minus signs.
- */
-
-import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryStart, wordBoundaryEnd, getEscapedSeparator, cachedRegExp } from "./constants.js"
+import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, UNICODE_SYMBOLS, wordBoundaryEnd, wordBoundaryStart } from "./constants.js"
 import { namedGroups } from "./utils.js"
 
 export const DASH_STYLES = ["american", "british", "none"] as const
@@ -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 = {}