punctilio 3.13.2 → 4.1.0

package/src/markdown.ts

@@ -4,9 +4,15 @@ import remarkGfm from "remark-gfm"
 import remarkStringify from "remark-stringify"
 import QuickLRU from "quick-lru"
 
+import { TRANSFORM_OPTION_KEYS } from "./index.js"
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
-import { stableStringify } from "./utils.js"
+import { assertKnownOptionKeys, stableStringify } from "./utils.js"
 
+/**
+ * Options for `transformMarkdown`. Inherits the Markdown-sink default of
+ * `nbsp: false` from {@link RemarkPunctilioOptions}; pass `nbsp: true` to
+ * opt in to non-breaking space insertion.
+ */
 export interface MarkdownOptions extends RemarkPunctilioOptions {
   /**
    * Character for emphasis (`*text*` vs `_text_`) and strong (`**text**` vs `__text__`).
@@ -27,6 +33,12 @@ export interface MarkdownOptions extends RemarkPunctilioOptions {
   ruleMarker?: "-" | "*" | "_"
 }
 
+/** Option keys handled by `transformMarkdown` itself rather than `transform()`. */
+export const MARKDOWN_ONLY_OPTION_KEYS: readonly string[] = ["emphasisMarker", "strongMarker", "bulletMarker", "ruleMarker"]
+
+/** Runtime list of valid `transformMarkdown` option keys. */
+export const MARKDOWN_OPTION_KEYS: readonly string[] = [...TRANSFORM_OPTION_KEYS, ...MARKDOWN_ONLY_OPTION_KEYS]
+
 function createProcessor(options: MarkdownOptions) {
   const {
     emphasisMarker,
@@ -70,6 +82,8 @@ export async function transformMarkdown(
   input: string,
   options: MarkdownOptions = {}
 ): Promise<string> {
+  assertKnownOptionKeys(options, MARKDOWN_OPTION_KEYS, "transformMarkdown")
+
   const optionsKey = stableStringify(options)
 
   let processor = processorCache.get(optionsKey)

package/src/prettier-plugin.ts

@@ -5,14 +5,26 @@ import type { Parser, Plugin } from "prettier"
 import type { Root } from "mdast"
 import { cosmiconfig } from "cosmiconfig"
 
+import { HTML_ONLY_OPTION_KEYS } from "./html.js"
+import { MARKDOWN_ONLY_OPTION_KEYS } from "./markdown.js"
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
+import { omitKeys } from "./utils.js"
 
 const upstreamMarkdown = prettierMarkdown.parsers.markdown as Parser<Root>
 const explorer = cosmiconfig("punctilio")
 
+// A config file may be shared with the CLI, so it can carry markdown-only
+// keys (prettier controls stringification itself) and HTML-only keys. Strip
+// those; unknown keys still fail loudly inside remarkPunctilio.
+const INAPPLICABLE_CONFIG_KEYS: readonly string[] = [
+  ...MARKDOWN_ONLY_OPTION_KEYS,
+  ...HTML_ONLY_OPTION_KEYS,
+]
+
 async function loadPunctilioConfig(searchFrom: string): Promise<RemarkPunctilioOptions> {
   const result = await explorer.search(searchFrom)
-  return !result || result.isEmpty ? {} : (result.config as RemarkPunctilioOptions)
+  if (!result || result.isEmpty) return {}
+  return omitKeys(result.config as RemarkPunctilioOptions, INAPPLICABLE_CONFIG_KEYS)
 }
 
 async function runRemarkPunctilio(opts: RemarkPunctilioOptions, ast: Root): Promise<void> {

package/src/rehype.ts

@@ -3,9 +3,9 @@ import type { Transformer } from "unified"
 
 import { SKIP, visitParents } from "unist-util-visit-parents"
 
-import { transform, type TransformOptions } from "./index.js"
+import { transform, TRANSFORM_OPTION_KEYS, type TransformOptions } from "./index.js"
 import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
-import { formatErrorString, transformTextNodes } from "./utils.js"
+import { assertKnownOptionKeys, formatErrorString, transformTextNodes } from "./utils.js"
 
 type ElementPredicate = (node: Element) => boolean
 
@@ -46,10 +46,40 @@ export interface RehypePunctilioOptions
    * Default: []
    */
   skipClasses?: string[]
+
+  /**
+   * Invert the element model: transform text inside every element except the
+   * skip-list (`skipTags`/`skipClasses`) plus `textarea`/`input`/`select`,
+   * whose text is a literal form-control value rather than prose. The default
+   * (`false`) keeps the `TRANSFORMABLE_ELEMENTS` allowlist, transforming only
+   * known prose-bearing tags (and custom elements).
+   *
+   * Default: false
+   */
+  transformAllElements?: boolean
 }
 
 const DEFAULT_SKIP_TAGS = ["code", "pre", "script", "style", "kbd", "var", "samp", "template", "math", "svg"]
 
+// Form elements whose text content is a literal control value, not prose.
+// Hard-skipped (whole subtree) under `transformAllElements`, on top of the
+// user skip-list, so their values are protected even when nested inside a
+// transformable element.
+const FORM_VALUE_TAGS = ["textarea", "input"]
+
+// `<select>` is not prose itself, but its `<option>` children are (and are
+// transformed under the default allowlist). Under `transformAllElements` we
+// exclude `select` as a transform *unit* while still recursing into — and
+// transforming — its options, so the inverted mode never transforms less than
+// the allowlist.
+const NON_PROSE_CONTAINER_TAGS = new Set(["select"])
+
+/** Option keys handled by `rehypePunctilio` itself rather than `transform()`. */
+export const REHYPE_ONLY_OPTION_KEYS: readonly string[] = ["skipTags", "skipClasses", "shouldSkipText", "transformAllElements"]
+
+/** Runtime list of valid `rehypePunctilio` option keys. */
+export const REHYPE_OPTION_KEYS: readonly string[] = [...TRANSFORM_OPTION_KEYS, ...REHYPE_ONLY_OPTION_KEYS]
+
 export function flattenTextNodes(
   node: Element | ElementContent,
   shouldSkip: ElementPredicate,
@@ -266,8 +296,18 @@ const TRANSFORMABLE_ELEMENTS = new Set([
   "ruby",
   "rt",
   "rp",
+  "title",
+  "button",
+  "option",
+  "output",
 ])
 
+// A tag name containing "-" is a custom element per the HTML custom-element
+// naming rule; assume those hold transformable prose like built-in elements.
+function isTransformableElement(tagName: string): boolean {
+  return TRANSFORMABLE_ELEMENTS.has(tagName) || tagName.includes("-")
+}
+
 function hasTextDescendant(
   node: Element | ElementContent,
   shouldSkip: ElementPredicate,
@@ -296,7 +336,8 @@ export function collectTransformableElements(
   node: Element,
   shouldSkip: ElementPredicate,
   depth: number = 0,
-  alreadyTransformed?: ReadonlySet<Element>
+  alreadyTransformed?: ReadonlySet<Element>,
+  isTransformable: (tagName: string) => boolean = isTransformableElement
 ): Element[] {
   /* istanbul ignore if -- defensive: prevents stack overflow from malicious HTML */
   if (depth > MAX_RECURSION_DEPTH) {
@@ -319,7 +360,7 @@ export function collectTransformableElements(
     hasTextDescendant(node, shouldSkip)
 
   if (
-    TRANSFORMABLE_ELEMENTS.has(node.tagName) &&
+    isTransformable(node.tagName) &&
     (hasDirectText || hasTextDescendants)
   ) {
     results.push(node)
@@ -328,7 +369,7 @@ export function collectTransformableElements(
     // children that should be independent, or has no text to transform.
     for (const child of node.children) {
       if (child.type === "element") {
-        const childResults = collectTransformableElements(child, shouldSkip, depth + 1, alreadyTransformed)
+        const childResults = collectTransformableElements(child, shouldSkip, depth + 1, alreadyTransformed, isTransformable)
         for (const r of childResults) results.push(r)
       }
     }
@@ -354,17 +395,29 @@ function markDescendants(node: Element, set: Set<Element>, depth: number = 0): v
 export function rehypePunctilio(
   options: RehypePunctilioOptions = {}
 ): Transformer<Root, Root> {
+  assertKnownOptionKeys(options, REHYPE_OPTION_KEYS, "rehypePunctilio")
+
   const {
     skipTags = DEFAULT_SKIP_TAGS,
     skipClasses = [],
     separator = DEFAULT_SEPARATOR,
     shouldSkipText,
+    transformAllElements = false,
     ...transformOptions
   } = options
 
-  const skipTagSet = new Set(skipTags)
+  // In inverted mode, form-value elements join the skip-list so their literal
+  // values are neither transformed nor flattened into a transformable ancestor.
+  const skipTagSet = new Set(transformAllElements ? [...skipTags, ...FORM_VALUE_TAGS] : skipTags)
   const skipClassSet = new Set(skipClasses)
 
+  // Inverted mode transforms every non-skipped element except non-prose
+  // containers; the default keeps the `TRANSFORMABLE_ELEMENTS` allowlist (plus
+  // custom elements).
+  const isTransformable = transformAllElements
+    ? (tagName: string) => !NON_PROSE_CONTAINER_TAGS.has(tagName)
+    : isTransformableElement
+
   const hasSkipClass = (node: Element): boolean => {
     if (skipClassSet.size === 0) return false
     const classNames = node.properties?.className
@@ -377,11 +430,7 @@ export function rehypePunctilio(
   const shouldSkip = (node: Element): boolean =>
     skipTagSet.has(node.tagName) || hasSkipClass(node)
 
-  // Default idempotency check to false in plugin context — the separator
-  // count check already guards against corruption, and the double-pass
-  // penalty compounds across every block-level element.
   const pluginOptions = {
-    checkIdempotency: false,
     ...transformOptions,
     separator,
   }
@@ -412,7 +461,7 @@ export function rehypePunctilio(
       }
 
       // Collect and transform elements with text content
-      const elementsToTransform = collectTransformableElements(node, shouldSkip, 0, transformed)
+      const elementsToTransform = collectTransformableElements(node, shouldSkip, 0, transformed, isTransformable)
       for (const elt of elementsToTransform) {
         if (!transformed.has(elt)) {
           transformElement(elt, transformFn, shouldSkip, separator, false, elementOptions)

package/src/remark.ts

@@ -3,10 +3,15 @@ import type { Transformer } from "unified"
 
 import { visitParents } from "unist-util-visit-parents"
 
-import { transform, type TransformOptions } from "./index.js"
+import { transform, TRANSFORM_OPTION_KEYS, type TransformOptions } from "./index.js"
 import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
-import { transformTextNodes } from "./utils.js"
+import { assertKnownOptionKeys, transformTextNodes } from "./utils.js"
 
+/**
+ * Same options as `transform()`, except `nbsp` defaults to `false`:
+ * invisible U+00A0 characters written into Markdown source files break
+ * grep/Ctrl+F matching. Pass `nbsp: true` explicitly to opt in.
+ */
 export type RemarkPunctilioOptions = TransformOptions
 
 const PHRASING_CONTAINERS = new Set(["paragraph", "heading", "tableCell"])
@@ -42,14 +47,16 @@ function flattenTextNodes(
 export function remarkPunctilio(
   options: RemarkPunctilioOptions = {}
 ): Transformer<Root, Root> {
+  assertKnownOptionKeys(options, TRANSFORM_OPTION_KEYS, "remarkPunctilio")
+
   const separator = options.separator ?? DEFAULT_SEPARATOR
 
-  // Default idempotency check to false in plugin context — the separator
-  // count check already guards against corruption, and the double-pass
-  // penalty compounds across every block-level element.
+  // Markdown is a source format, so default `nbsp` to false (`?? false`
+  // rather than spread defaults so an explicit `nbsp: undefined` also gets
+  // the Markdown default instead of falling through to transform's).
   const pluginOptions = {
-    checkIdempotency: false,
     ...options,
+    nbsp: options.nbsp ?? false,
     separator,
   }
 

package/src/symbols.ts

@@ -1,5 +1,5 @@
 import { cachedRegExp, DEFAULT_SEPARATOR, getEscapedSeparator, LATIN_LETTERS, SPACE_CHARS, UNICODE_SYMBOLS, wordBoundaryEnd } from "./constants.js"
-import { namedGroups } from "./utils.js"
+import { namedGroups, replaceCallbackContext } from "./utils.js"
 
 export interface SymbolOptions {
   /** Boundary marker for HTML element boundaries. Default: "\uE000\uE001" */
@@ -337,8 +337,7 @@ function balancedPrimeReplacer(primeChar: string, escapedSeparator: string) {
       // Inside balanced quotes: check if this is feet-inches notation
       // (e.g., 5′10" where ″ is inches, not a closing quote)
       if (feetInchesContext) {
-        const matchOffset = args.at(-3) as number
-        const fullString = args.at(-2) as string
+        const { offset: matchOffset, input: fullString } = replaceCallbackContext(args)
         if (feetInchesContext.test(fullString.substring(0, matchOffset))) {
           return `${digit}${sep}${primeChar}${afterSep}`
         }

package/src/utils.ts

@@ -4,16 +4,18 @@ const ERROR_STRING_THRESHOLD = 2000
 
 /**
  * Formats a string for error messages, truncating above the threshold.
- * Writes full content to stderr in Node.js so build logs capture it.
+ * When the PUNCTILIO_DEBUG environment variable is set to a non-empty
+ * value, also writes the 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) {
     return JSON.stringify(content)
   }
 
-  // In Node.js, write full content to stderr for debugging
+  // In Node.js, write full content to stderr for debugging when opted in
   try {
-    if (typeof globalThis.process?.stderr?.write === "function") {
+    if (globalThis.process?.env?.PUNCTILIO_DEBUG && typeof globalThis.process?.stderr?.write === "function") {
       globalThis.process.stderr.write(
         `\n[punctilio ${label} full content (${content.length} chars)]:\n${content}\n\n`
       )
@@ -106,6 +108,30 @@ export function assertSeparatorCountPreserved(
   }
 }
 
+/** Throws if `options` contains a key not present in `validKeys`. @internal */
+export function assertKnownOptionKeys(
+  options: object,
+  validKeys: readonly string[],
+  context: string,
+): void {
+  for (const key of Object.keys(options)) {
+    if (!validKeys.includes(key)) {
+      throw new Error(
+        `Unknown option "${key}" for ${context}. Valid options: ${[...validKeys].sort().join(", ")}.`
+      )
+    }
+  }
+}
+
+/** Returns a copy of `obj` without the listed keys. @internal */
+export function omitKeys<T extends object>(obj: T, keys: readonly string[]): Partial<T> {
+  const result: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (!keys.includes(k)) result[k] = v
+  }
+  return result as Partial<T>
+}
+
 /** 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> = {}
@@ -128,3 +154,22 @@ export function stableStringify(obj: object): string {
 export function namedGroups<G>(args: unknown[]): G {
   return args[args.length - 1] as G
 }
+
+/**
+ * Extracts the match offset and input string from a `.replace()` callback's
+ * arguments, independent of capture-group count. The trailing arguments are
+ * `..., offset, input[, namedGroups]`: the input is the last string (the
+ * named-groups object, when present, follows it) and the offset is the
+ * number immediately before the input. @internal
+ */
+export function replaceCallbackContext(args: unknown[]): { offset: number; input: string } {
+  let inputIndex = args.length - 1
+  while (inputIndex >= 0 && typeof args[inputIndex] !== "string") {
+    inputIndex--
+  }
+  const offset = args[inputIndex - 1]
+  if (inputIndex < 1 || typeof offset !== "number") {
+    throw new Error("Could not locate offset and input in replace-callback arguments.")
+  }
+  return { offset, input: args[inputIndex] as string }
+}