punctilio 2.3.0 → 3.0.1

package/src/index.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 
-export { niceQuotes, type QuoteOptions, type PunctuationStyle } from "./quotes.js"
+export { niceQuotes, classifyApostrophes, type QuoteOptions, type PunctuationStyle } from "./quotes.js"
 import type { PunctuationStyle } from "./quotes.js"
 export {
   hyphenReplace,
@@ -155,17 +155,6 @@ export interface TransformOptions {
    */
   checkIdempotency?: boolean
 
-  /**
-   * Use modifier letter apostrophe (U+02BC) instead of right single quote
-   * (U+2019) for contractions and possessives. This distinguishes apostrophes
-   * from closing quotes in most cases, though some ambiguous patterns (e.g.,
-   * `dogs'` vs a closing single quote) cannot be resolved without semantic
-   * understanding. May also break downstream regex patterns that expect
-   * standard quote characters like /don\u2019t/ or /O\u2019Brien/.
-   *
-   * Default: false
-   */
-  useModifierLetterApostrophe?: boolean
 }
 
 import { niceQuotes } from "./quotes.js"
@@ -224,7 +213,6 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
   checkIdempotency: true,
   punctuationStyle: "american",
   dashStyle: "american",
-  useModifierLetterApostrophe: false,
 }
 
 export function transform(text: string, options: TransformOptions = {}): string {
@@ -241,29 +229,24 @@ export function transform(text: string, options: TransformOptions = {}): string
   }
 
   const original = text
-  const { symbols, fractions, degrees, superscript, ligatures, nbsp, collapseSpaces, checkIdempotency, useModifierLetterApostrophe, ...separatorOpts } = { ...defaultOpts, ...options }
+  const { symbols, fractions, degrees, superscript, ligatures, nbsp, collapseSpaces, checkIdempotency, ...separatorOpts } = { ...defaultOpts, ...options }
 
   text = hyphenReplace(text, separatorOpts)
   if (separatorOpts.punctuationStyle !== "none") {
     text = primeMarks(text, separatorOpts)
   }
-  // niceQuotes must output MLA here regardless of the user's option,
-  // because NBSP's PUNCTUATION_OR_QUOTE class includes RSQ but not MLA.
-  // Without this, apostrophes in "don't" would act as word boundaries
-  // during NBSP insertion. The final MLA→RSQ conversion at line 286
-  // runs after all transforms complete.
-  text = niceQuotes(text, { ...separatorOpts, useModifierLetterApostrophe: true })
+  text = niceQuotes(text, separatorOpts)
 
   if (symbols) {
     text = symbolTransform(text, separatorOpts)
   }
 
   if (fractions) {
-    text = fractionsTransform(text)
+    text = fractionsTransform(text, separatorOpts)
   }
 
   if (degrees) {
-    text = degreesTransform(text)
+    text = degreesTransform(text, separatorOpts)
   }
 
   if (superscript) {
@@ -284,12 +267,6 @@ export function transform(text: string, options: TransformOptions = {}): string
 
   assertSeparatorCountPreserved(original, text, separator, "transform")
 
-  // Convert MLA→RSQ for regex-friendly output, after all transforms
-  // (especially NBSP which relies on MLA being letter-like).
-  if (!useModifierLetterApostrophe) {
-    text = text.replaceAll(UNICODE_SYMBOLS.MODIFIER_LETTER_APOSTROPHE, UNICODE_SYMBOLS.RIGHT_SINGLE_QUOTE)
-  }
-
   if (checkIdempotency) {
     const secondPass = transform(text, { ...options, checkIdempotency: false })
     /* istanbul ignore if -- defensive check that should never trigger */

package/src/quotes.ts

@@ -22,17 +22,6 @@ export interface QuoteOptions {
   separator?: string
   /** "american" (inside), "british" (outside), "none". Default: "american" */
   punctuationStyle?: PunctuationStyle
-  /**
-   * Use modifier letter apostrophe (U+02BC) instead of right single quote
-   * (U+2019) for contractions and possessives. This distinguishes apostrophes
-   * from closing quotes in most cases, though some ambiguous patterns (e.g.,
-   * `dogs'` vs a closing single quote) cannot be resolved without semantic
-   * understanding. May also break downstream regex patterns that expect
-   * standard quote characters like /don\u2019t/ or /O\u2019Brien/.
-   *
-   * Default: false
-   */
-  useModifierLetterApostrophe?: boolean
 }
 
 /** Convert straight single quotes to curly quotes and apostrophes */
@@ -177,8 +166,8 @@ function applyPunctuationStyle(text: string, sep: string, style: PunctuationStyl
   return text
 }
 
-/** Convert straight quotes to smart quotes. */
-export function niceQuotes(text: string, options: QuoteOptions = {}): string {
+/** 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"
   if (punctuationStyle === "none") return text
@@ -187,12 +176,27 @@ export function niceQuotes(text: string, options: QuoteOptions = {}): string {
   text = convertDoubleQuotes(text, sep)
   text = applyPunctuationStyle(text, sep, punctuationStyle)
 
+  return text
+}
+
+/** Convert straight quotes to smart quotes. */
+export function niceQuotes(text: string, options: QuoteOptions = {}): string {
   // MLA is used internally so applyPunctuationStyle can distinguish
   // apostrophes (MLA, don't move) from closing quotes (RSQ, do move).
-  // Convert back to RSQ unless the caller opts into the distinction.
-  if (!options.useModifierLetterApostrophe) {
-    text = text.replaceAll(MODIFIER_LETTER_APOSTROPHE, RIGHT_SINGLE_QUOTE)
-  }
+  // Always convert back to RSQ for standard output per Unicode.
+  return processQuotes(text, options).replaceAll(MODIFIER_LETTER_APOSTROPHE, RIGHT_SINGLE_QUOTE)
+}
 
-  return text
+/**
+ * Classify apostrophes vs. closing single quotes.
+ *
+ * Returns the text with smart quotes applied, where apostrophes are
+ * U+02BC (MODIFIER LETTER APOSTROPHE) and closing single quotes are
+ * U+2019 (RIGHT SINGLE QUOTATION MARK).
+ *
+ * For display output, use {@link niceQuotes} or `transform()` instead,
+ * which use U+2019 for both per the Unicode Standard.
+ */
+export function classifyApostrophes(text: string, options: QuoteOptions = {}): string {
+  return processQuotes(text, options)
 }

package/src/rehype.ts

@@ -183,15 +183,19 @@ export function getFirstTextNode(
 export function assertSmartQuotesMatch(input: string): void {
   if (!input) return
 
-  const quoteMap: Record<string, string> = { "\u201C": "\u201D", "\u201D": "\u201C" }
+  const openers = new Set(["\u201C"])   // left double quote opens
+  const closerToOpener: Record<string, string> = { "\u201D": "\u201C" }  // right closes left
   const stack: string[] = []
 
   for (const char of input) {
-    if (char in quoteMap) {
-      if (stack.length > 0 && quoteMap[stack[stack.length - 1]] === char) {
+    if (openers.has(char)) {
+      stack.push(char)
+    } else if (char in closerToOpener) {
+      if (stack.length > 0 && stack[stack.length - 1] === closerToOpener[char]) {
         stack.pop()
       } else {
-        stack.push(char)
+        // Unmatched closer
+        throw new Error(`Mismatched quotes in ${input}`)
       }
     }
   }

package/src/symbols.ts

@@ -116,32 +116,38 @@ export function mathSymbols(text: string): string {
   return text
 }
 
-/** Legal symbol replacement map: ASCII → Unicode */
-const LEGAL_SYMBOL_MAP: [RegExp, string][] = [
-  [/\(r\)/gi, REGISTERED],
-  [/\(tm\)/gi, TRADEMARK],
-]
+/**
+ * Context-aware replacement for legal symbols like (c), (r), (tm).
+ * Extracts surrounding text and delegates the convert/skip decision to a predicate.
+ */
+function contextAwareLegalReplace(
+  text: string,
+  pattern: RegExp,
+  replacement: string,
+  shouldConvert: (before: string, after: string) => boolean,
+): string {
+  return text.replace(pattern, (match: string, offset: number, str: string) => {
+    const before = str.slice(Math.max(0, offset - 25), offset)
+    const after = str.slice(offset + match.length, offset + match.length + 25)
+    return shouldConvert(before, after) ? replacement : match
+  })
+}
 
 /** Convert (c), (r), (tm) to ©, ®, ™. */
 export function legalSymbols(text: string): string {
-  // (c) needs context-aware replacement to avoid false positives in essays,
-  // enumerations like "(a), (b), (c)", and legal citations like "(c)(2)(A)".
-  // Only convert when there's positive copyright evidence:
-  //   - Followed by a 4-digit year (19xx/20xx) within a short window
-  //   - Preceded by the word "copyright"
-  text = text.replace(/\(c\)/gi, (match, offset, str) => {
-    const after = str.slice(offset + 3, offset + 25)
-    if (/^\s*(?:19|20)\d{2}\b/.test(after)) return COPYRIGHT
-
-    const before = str.slice(Math.max(0, offset - 20), offset)
-    if (/\bcopyright\s*$/i.test(before)) return COPYRIGHT
-
-    return match
-  })
+  // (c) → © only with positive copyright evidence (year or "copyright" keyword)
+  text = contextAwareLegalReplace(text, /\(c\)/gi, COPYRIGHT, (before, after) =>
+    /^\s*(?:19|20)\d{2}\b/.test(after) || /\bcopyright\s*$/i.test(before)
+  )
+
+  // (r) → ® unless in enumeration "(q), (r)" or legal citation "(r)(1)" context
+  text = contextAwareLegalReplace(text, /\(r\)/gi, REGISTERED, (before, after) =>
+    !/\([a-z]\)[,;]\s*$/i.test(before) && !/^\(\d/.test(after)
+  )
+
+  // (tm) → ™ unconditionally
+  text = text.replace(/\(tm\)/gi, TRADEMARK)
 
-  for (const [pattern, replacement] of LEGAL_SYMBOL_MAP) {
-    text = text.replace(pattern, replacement)
-  }
   return text
 }
 

package/src/tests/dashes.test.ts

@@ -124,6 +124,17 @@ describe("hyphenReplace", () => {
     })
   })
 
+  describe("tilde preservation", () => {
+    it.each([
+      ["word ~ word", "word ~ word"],
+      ["word ~~ word", "word ~~ word"],
+      ["the ~5% range", "the ~5% range"],
+      ["~approximately", "~approximately"],
+    ])('preserves tilde in "%s"', (input) => {
+      expect(hyphenReplace(input)).toBe(input)
+    })
+  })
+
   describe("with separator character", () => {
     const sep = "\uE000"
     it.each([

package/src/tests/index.test.ts

@@ -11,6 +11,9 @@ const {
   ELLIPSIS,
   MULTIPLICATION,
   NOT_EQUAL,
+  PLUS_MINUS,
+  LESS_EQUAL,
+  GREATER_EQUAL,
   COPYRIGHT,
   NBSP,
   PRIME,
@@ -18,6 +21,7 @@ const {
   TRADEMARK,
   REGISTERED,
   DEGREE,
+  MINUS,
   FRACTION_1_2,
   SUPERSCRIPT_ST,
 } = UNICODE_SYMBOLS
@@ -183,11 +187,11 @@ describe("transform", () => {
         // Date ranges - all competitors fail
         ["January-March", `January${EN_DASH}March`],
         // Minus signs - most competitors fail
-        ["-5", `−5`],
-        ["(-5)", `(−5)`],
+        ["-5", `${MINUS}5`],
+        ["(-5)", `(${MINUS}5)`],
         // Prime marks - smartypants/typograf fail
-        ['5\'10"', `5′10″`],
-        ['He is 6\'2" tall', `He is 6′2″ tall`],
+        ['5\'10"', `5${PRIME}10${DOUBLE_PRIME}`],
+        ['He is 6\'2" tall', `He is 6${PRIME}2${DOUBLE_PRIME} tall`],
       ])('correctly transforms: "%s"', (input, expected) => {
         expect(transform(input, { symbols: true, degrees: true, nbsp: false })).toBe(expected)
       })
@@ -229,7 +233,7 @@ describe("transform", () => {
 
     it("handles technical documentation", () => {
       const input = 'The API returns x != y when a <= b and c >= d. Error tolerance: +-5%.'
-      const expected = `The API returns x ${NOT_EQUAL} y when a ≤ b and c ≥ d. Error tolerance: ±5%.`
+      const expected = `The API returns x ${NOT_EQUAL} y when a ${LESS_EQUAL} b and c ${GREATER_EQUAL} d. Error tolerance: ${PLUS_MINUS}5%.`
       expect(transform(input, { nbsp: false })).toBe(expected)
     })
 
@@ -263,11 +267,11 @@ describe("transform", () => {
     it.each([
       [
         '"Wait..." she said - "it\'s pages 1-5."',
-        `${LEFT_DOUBLE_QUOTE}Wait…${RIGHT_DOUBLE_QUOTE} she said${EM_DASH}${LEFT_DOUBLE_QUOTE}it${RIGHT_SINGLE_QUOTE}s pages 1–5.${RIGHT_DOUBLE_QUOTE}`,
+        `${LEFT_DOUBLE_QUOTE}Wait${ELLIPSIS}${RIGHT_DOUBLE_QUOTE} she said${EM_DASH}${LEFT_DOUBLE_QUOTE}it${RIGHT_SINGLE_QUOTE}s pages 1${EN_DASH}5.${RIGHT_DOUBLE_QUOTE}`,
       ],
       [
         "(c) 2024 - Room is 10x12, set to 72 F",
-        `${COPYRIGHT} 2024${EM_DASH}Room is 10×12, set to 72 °F`,
+        `${COPYRIGHT} 2024${EM_DASH}Room is 10${MULTIPLICATION}12, set to 72 ${DEGREE}F`,
       ],
     ])('handles complex transform: "%s"', (input, expected) => {
       expect(transform(input, { degrees: true, nbsp: false })).toBe(expected)
@@ -313,7 +317,7 @@ describe("transform", () => {
       const count = 50
       const input = "pages 1-5 ".repeat(count)
       const result = transform(input, { nbsp: false })
-      const enDashCount = (result.match(/–/g) || []).length
+      const enDashCount = (result.match(new RegExp(EN_DASH, "g")) || []).length
       expect(enDashCount).toBe(count)
     })
 
@@ -321,7 +325,7 @@ describe("transform", () => {
       const count = 50
       const input = "Wait... ".repeat(count)
       const result = transform(input, { nbsp: false })
-      const ellipsisCount = (result.match(/…/g) || []).length
+      const ellipsisCount = (result.match(new RegExp(ELLIPSIS, "g")) || []).length
       expect(ellipsisCount).toBe(count)
     })
   })
@@ -373,7 +377,7 @@ describe("transform", () => {
 
     it.each([
       [`word${sep} - ${sep}word`, `word${sep}${EM_DASH}${sep}word`],
-      [`1${sep}-${sep}5`, `1${sep}–${sep}5`],
+      [`1${sep}-${sep}5`, `1${sep}${EN_DASH}${sep}5`],
     ])('handles separator in dashes', (input, expected) => {
       expect(transform(input, { separator: sep, nbsp: false })).toBe(expected)
     })
@@ -390,6 +394,16 @@ describe("transform", () => {
       const input = `Text with ${sep} in it`
       expect(() => transform(input, { separator: sep, nbsp: false })).not.toThrow()
     })
+
+    it("handles separator in fractions", () => {
+      const input = `1${sep}/2`
+      expect(transform(input, { separator: sep, fractions: true, nbsp: false })).toBe(`${sep}${FRACTION_1_2}`)
+    })
+
+    it("handles separator in degrees", () => {
+      const input = `72${sep} F`
+      expect(transform(input, { separator: sep, degrees: true, nbsp: false })).toBe(`72${sep} ${DEGREE}F`)
+    })
   })
 
   describe("additional idempotency", () => {
@@ -407,10 +421,10 @@ describe("transform", () => {
     it.each([
       `${LEFT_DOUBLE_QUOTE}Hello${RIGHT_DOUBLE_QUOTE}`,
       `word${EM_DASH}word`,
-      `1–5`,
-      `Wait…`,
-      `5×5`,
-      `20${NBSP}°C`,
+      `1${EN_DASH}5`,
+      `Wait${ELLIPSIS}`,
+      `5${MULTIPLICATION}5`,
+      `20${NBSP}${DEGREE}C`,
       `${COPYRIGHT}${NBSP}2024`,
     ])('stable for: "%s"', (input) => {
       expect(transform(input)).toBe(input)
@@ -506,12 +520,12 @@ describe("transform", () => {
     it.each([
       ['"start', `${LEFT_DOUBLE_QUOTE}start`],
       ["'start", `${RIGHT_SINGLE_QUOTE}start`],
-      ["-5 start", `−5 start`],
-      ["...start", `… start`],
+      ["-5 start", `${MINUS}5 start`],
+      ["...start", `${ELLIPSIS} start`],
       ['end"', `end${RIGHT_DOUBLE_QUOTE}`],
       ["end'", `end${RIGHT_SINGLE_QUOTE}`],
-      ["end...", `end…`],
-      ["5x", `5×`],
+      ["end...", `end${ELLIPSIS}`],
+      ["5x", `5${MULTIPLICATION}`],
     ])('handles boundary: "%s"', (input, expected) => {
       expect(transform(input, { nbsp: false })).toBe(expected)
     })

package/src/tests/nbsp.test.ts

@@ -15,7 +15,7 @@ import {
 } from "../nbsp.js"
 import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR } from "../constants.js"
 
-const NBSP = UNICODE_SYMBOLS.NBSP
+const { NBSP, COPYRIGHT, REGISTERED, TRADEMARK } = UNICODE_SYMBOLS
 const SEP = DEFAULT_SEPARATOR
 
 /** Calls fn with separator option, checking all cases produce correct nbsp. */
@@ -183,18 +183,18 @@ describe("nbspAfterHonorifics", () => {
 
 describe("nbspAfterCopyrightSymbols", () => {
   it.each([
-    ["© 2024", `©${NBSP}2024`],
-    ["® Brand", `®${NBSP}Brand`],
-    ["™ Product", `™${NBSP}Product`],
-    ["© 2024 Company", `©${NBSP}2024 Company`],
-    ["© company", "© company"],
+    [`${COPYRIGHT} 2024`, `${COPYRIGHT}${NBSP}2024`],
+    [`${REGISTERED} Brand`, `${REGISTERED}${NBSP}Brand`],
+    [`${TRADEMARK} Product`, `${TRADEMARK}${NBSP}Product`],
+    [`${COPYRIGHT} 2024 Company`, `${COPYRIGHT}${NBSP}2024 Company`],
+    [`${COPYRIGHT} company`, `${COPYRIGHT} company`],
   ])('"%s" → "%s"', (input, expected) => {
     expect(nbspAfterCopyrightSymbols(input)).toBe(expected)
   })
 
   it("preserves separator after symbol", () => {
     expectSep(nbspAfterCopyrightSymbols, [
-      [`©${SEP} 2024`, `©${SEP}${NBSP}2024`],
+      [`${COPYRIGHT}${SEP} 2024`, `${COPYRIGHT}${SEP}${NBSP}2024`],
     ])
   })
 })
@@ -224,8 +224,8 @@ describe("nbspTransform", () => {
   })
 
   it("handles multiple rules on the same text", () => {
-    expect(nbspTransform("© 2024 by J. K. Rowling"))
-      .toBe(`©${NBSP}2024 by${NBSP}J.${NBSP}K.${NBSP}Rowling`)
+    expect(nbspTransform(`${COPYRIGHT} 2024 by J. K. Rowling`))
+      .toBe(`${COPYRIGHT}${NBSP}2024 by${NBSP}J.${NBSP}K.${NBSP}Rowling`)
   })
 
   it("nbspBeforeLastWord fires on plain text", () => {