punctilio 3.9.3 → 3.11.0

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

@@ -0,0 +1,61 @@
+/**
+ * Prettier plugin applying punctilio's typographic transforms to Markdown.
+ *
+ * @example
+ * ```jsonc
+ * // .prettierrc
+ * { "plugins": ["punctilio/prettier-plugin"] }
+ *
+ * // .punctiliorc.json (optional)
+ * { "punctuationStyle": "british", "skipTags": ["pre", "code"] }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { dirname } from "node:path"
+
+import * as prettierMarkdown from "prettier/plugins/markdown"
+import type { Parser, Plugin } from "prettier"
+import type { Root } from "mdast"
+import { cosmiconfig } from "cosmiconfig"
+
+import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
+
+const upstreamMarkdown = prettierMarkdown.parsers.markdown as Parser<Root>
+const explorer = cosmiconfig("punctilio")
+
+async function loadPunctilioConfig(searchFrom: string): Promise<RemarkPunctilioOptions> {
+  const result = await explorer.search(searchFrom)
+  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: {
+      ...upstreamMarkdown,
+      async parse(text, options) {
+        const ast = await upstreamMarkdown.parse(text, options)
+        const searchFrom = typeof options.filepath === "string" ? dirname(options.filepath) : process.cwd()
+        const opts = await loadPunctilioConfig(searchFrom)
+        await runRemarkPunctilio(opts, ast)
+        return ast
+      },
+    },
+  },
+}
+
+export default plugin

package/src/quotes.ts

@@ -25,7 +25,8 @@ const TERMINAL_PUNCTUATION_CLASS = TERMINAL_PUNCTUATION.join("")
  */
 const MAX_NESTED_QUOTES = 4
 
-export type PunctuationStyle = "american" | "british" | "german" | "french" | "none"
+export const PUNCTUATION_STYLES = ["american", "british", "german", "french", "none"] as const
+export type PunctuationStyle = (typeof PUNCTUATION_STYLES)[number]
 
 export interface QuoteOptions {
   /** Boundary marker for HTML element boundaries. Default: "\uE000\uE001" */
@@ -214,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
+}