punctilio 3.9.2 → 3.10.0

package/src/html.ts

@@ -0,0 +1,92 @@
+/**
+ * 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"
+import QuickLRU from "quick-lru"
+
+import { rehypePunctilio, type RehypePunctilioOptions } from "./rehype.js"
+
+/**
+ * Options for the HTML transform pipeline.
+ */
+export interface HtmlOptions extends RehypePunctilioOptions {
+  /**
+   * Whether to parse the input as an HTML fragment (no implicit `<html>`,
+   * `<head>`, or `<body>` wrapping). Set to `false` to parse a complete
+   * document. Default: `true`.
+   */
+  fragment?: boolean
+}
+
+function createProcessor(options: HtmlOptions) {
+  const { fragment, ...punctilioOptions } = options
+  return unified()
+    .use(rehypeParse, { fragment: fragment ?? true })
+    .use(rehypePunctilio, punctilioOptions)
+    .use(rehypeStringify)
+}
+
+const MAX_PROCESSOR_CACHE_SIZE = 8
+
+const processorCache = new QuickLRU<string, ReturnType<typeof createProcessor>>({
+  maxSize: MAX_PROCESSOR_CACHE_SIZE,
+})
+
+/**
+ * Clears the processor cache. Exported for test isolation only.
+ * @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 = {}
+): Promise<string> {
+  // Function-valued options aren't JSON-serializable, so the cache key
+  // can't distinguish them. Bypass the cache to avoid returning a
+  // processor wired to a different shouldSkipText.
+  if (typeof options.shouldSkipText === "function") {
+    const result = await createProcessor(options).process(input)
+    return String(result)
+  }
+
+  const optionsKey = JSON.stringify(
+    Object.entries(options).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b))
+  )
+
+  let processor = processorCache.get(optionsKey)
+  if (!processor) {
+    processor = createProcessor(options)
+    processorCache.set(optionsKey, processor)
+  }
+
+  const result = await processor.process(input)
+  return String(result)
+}

package/src/prettier-plugin.ts

@@ -0,0 +1,49 @@
+/**
+ * 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)
+}
+
+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)
+        const transform = remarkPunctilio(opts) as (tree: Root) => void
+        transform(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" */