punctilio 3.11.3 → 3.11.4

package/src/symbols.ts

@@ -1,7 +1,3 @@
-/**
- * Symbol transformations: ellipses, multiplication, math symbols, arrows.
- */
-
 import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
 import { namedGroups } from "./utils.js"
 
@@ -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
 }