punctilio 3.13.1 → 4.0.0

package/src/cli.ts

@@ -5,17 +5,17 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { readFile, writeFile } from "node:fs/promises"
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
 
-import { Command, CommanderError, Option } from "commander"
 import { cosmiconfig } from "cosmiconfig"
 import ignore, { type Ignore } from "ignore"
 import { glob } from "tinyglobby"
 
-import { type MarkdownOptions, transformMarkdown } from "./markdown.js"
-import { type HtmlOptions, transformHtml } from "./html.js"
+import { MARKDOWN_ONLY_OPTION_KEYS, MARKDOWN_OPTION_KEYS, type MarkdownOptions, transformMarkdown } from "./markdown.js"
+import { HTML_ONLY_OPTION_KEYS, HTML_OPTION_KEYS, type HtmlOptions, transformHtml } from "./html.js"
 import { PUNCTUATION_STYLES, type PunctuationStyle } from "./quotes.js"
 import { DASH_STYLES, type DashStyle } from "./dashes.js"
-import { stableStringify } from "./utils.js"
+import { assertKnownOptionKeys, omitKeys, stableStringify } from "./utils.js"
 
 type CliOptions = MarkdownOptions & HtmlOptions
 type FileType = "md" | "html"
@@ -36,8 +36,9 @@ const RULE_MARKERS = ["-", "*", "_"] as const
 const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"])
 const HTML_EXTENSIONS = new Set([".html", ".htm"])
 
-// Fields match commander's camelCased flag names; .choices() guarantees literals at runtime.
+// camelCased flag values; buildFlags validates choice literals at runtime.
 interface ParsedFlags {
+  write?: boolean
   check?: boolean
   cache?: boolean
   cacheLocation?: string
@@ -64,42 +65,158 @@ interface ParsedFlags {
   fragment?: boolean
 }
 
-function buildProgram(version: string, io: CliIO): Command {
-  return new Command()
-    .name("punctilio")
-    .description("Apply typographic improvements to Markdown and HTML files.")
-    .version(version, "-V, --version", "show version")
-    .argument("[files...]", "files to format (pass '-' to read from stdin)")
-    .option("--check", "exit 1 if any file would change; write nothing")
-    .option("--config <path>", "path to a punctilio config file (otherwise auto-discovered)")
-    .option("--no-config", "ignore any auto-discovered config file")
-    .option("--ignore-path <path>", "path to an ignore file (otherwise .punctilioignore in cwd)")
-    .option("--no-cache", "disable the incremental cache (default location node_modules/.cache/punctilio/cache.json)")
-    .option("--cache-location <path>", "override the cache file location")
-    .option("--stdin-filepath <path>", "treat stdin as if it were this filename (infers type from extension)")
-    .addOption(new Option("--type <type>", "force file type (otherwise inferred from extension)").choices(FILE_TYPES))
-    .addOption(new Option("--punctuation-style <style>", "quote and punctuation style").choices(PUNCTUATION_STYLES))
-    .addOption(new Option("--dash-style <style>", "dash style").choices(DASH_STYLES))
-    .option("--no-symbols", "disable symbol transforms (ellipsis, ×, ©, etc.)")
-    .option("--no-nbsp", "disable non-breaking space insertion")
-    .option("--no-collapse-spaces", "preserve runs of consecutive spaces")
-    .option("--no-arrows", "disable -> → arrow transforms")
-    .option("--fractions", "enable 1/2 → ½")
-    .option("--degrees", "enable 20 C → 20 °C")
-    .option("--superscript", "enable 1st → 1ˢᵗ")
-    .option("--ligatures", "enable !? → ⁉")
-    .addOption(new Option("--emphasis-marker <char>", "markdown emphasis character").choices(EMPHASIS_MARKERS))
-    .addOption(new Option("--strong-marker <char>", "markdown strong emphasis character").choices(EMPHASIS_MARKERS))
-    .addOption(new Option("--bullet-marker <char>", "markdown list bullet character").choices(BULLET_MARKERS))
-    .addOption(new Option("--rule-marker <char>", "markdown thematic break character").choices(RULE_MARKERS))
-    .option("--skip-tag <tag...>", "HTML tags whose contents are left alone (repeatable)")
-    .option("--skip-class <class...>", "HTML class names whose elements are skipped (repeatable)")
-    .option("--no-fragment", "parse input as a full HTML document")
-    .exitOverride()
-    .configureOutput({
-      writeOut: (str) => { io.stdout.write(str) },
-      writeErr: (str) => { io.stderr.write(str) },
+const PARSE_ARGS_OPTIONS = {
+  "bullet-marker": { type: "string" },
+  "cache-location": { type: "string" },
+  check: { type: "boolean" },
+  config: { type: "string" },
+  "dash-style": { type: "string" },
+  degrees: { type: "boolean" },
+  "emphasis-marker": { type: "string" },
+  fractions: { type: "boolean" },
+  help: { short: "h", type: "boolean" },
+  "ignore-path": { type: "string" },
+  ligatures: { type: "boolean" },
+  nbsp: { type: "boolean" },
+  "no-arrows": { type: "boolean" },
+  "no-cache": { type: "boolean" },
+  "no-collapse-spaces": { type: "boolean" },
+  "no-config": { type: "boolean" },
+  "no-fragment": { type: "boolean" },
+  "no-nbsp": { type: "boolean" },
+  "no-symbols": { type: "boolean" },
+  "punctuation-style": { type: "string" },
+  "rule-marker": { type: "string" },
+  "skip-class": { multiple: true, type: "string" },
+  "skip-tag": { multiple: true, type: "string" },
+  "stdin-filepath": { type: "string" },
+  "strong-marker": { type: "string" },
+  superscript: { type: "boolean" },
+  type: { type: "string" },
+  version: { short: "V", type: "boolean" },
+  write: { type: "boolean" },
+} as const
+
+const HELP_TEXT = `Usage: punctilio [options] [files...]
+
+Apply typographic improvements to Markdown and HTML files.
+
+Arguments:
+  files                       files to format (pass '-' to read from stdin)
+
+Options:
+  -V, --version               show version
+  --write                     rewrite files in place (default prints formatted output to stdout)
+  --check                     exit 1 if any file would change; write nothing
+  --config <path>             path to a punctilio config file (otherwise auto-discovered)
+  --no-config                 ignore any auto-discovered config file
+  --ignore-path <path>        path to an ignore file (otherwise .punctilioignore in cwd)
+  --no-cache                  disable the incremental cache (default location node_modules/.cache/punctilio/cache.json)
+  --cache-location <path>     override the cache file location
+  --stdin-filepath <path>     treat stdin as if it were this filename (infers type from extension)
+  --type <type>               force file type (otherwise inferred from extension) (choices: ${FILE_TYPES.join(", ")})
+  --punctuation-style <style> quote and punctuation style (choices: ${PUNCTUATION_STYLES.join(", ")})
+  --dash-style <style>        dash style (choices: ${DASH_STYLES.join(", ")})
+  --no-symbols                disable symbol transforms (ellipsis, ×, ©, etc.)
+  --nbsp                      enable non-breaking space insertion (default: on for HTML, off for Markdown)
+  --no-nbsp                   disable non-breaking space insertion
+  --no-collapse-spaces        preserve runs of consecutive spaces
+  --no-arrows                 disable -> → arrow transforms
+  --fractions                 enable 1/2 → ½
+  --degrees                   enable 20 C → 20 °C
+  --superscript               enable 1st → 1ˢᵗ
+  --ligatures                 enable !? → ⁉
+  --emphasis-marker <char>    markdown emphasis character (choices: ${EMPHASIS_MARKERS.join(", ")})
+  --strong-marker <char>      markdown strong emphasis character (choices: ${EMPHASIS_MARKERS.join(", ")})
+  --bullet-marker <char>      markdown list bullet character (choices: ${BULLET_MARKERS.join(", ")})
+  --rule-marker <char>        markdown thematic break character (choices: ${RULE_MARKERS.join(", ")})
+  --skip-tag <tag>            HTML tag whose contents are left alone (repeatable)
+  --skip-class <class>        HTML class name whose elements are skipped (repeatable)
+  --no-fragment               parse input as a full HTML document
+  -h, --help                  display help for command
+`
+
+function parseRawArgs(args: string[]) {
+  try {
+    return parseArgs({
+      args,
+      allowPositionals: true,
+      options: PARSE_ARGS_OPTIONS,
+      strict: true,
+      tokens: true,
     })
+  } catch (err) {
+    // parseArgs throws on unknown options and missing option values.
+    throw new UsageError((err as Error).message)
+  }
+}
+
+type ParsedValues = ReturnType<typeof parseRawArgs>["values"]
+type ParsedTokens = ReturnType<typeof parseRawArgs>["tokens"]
+
+function parseChoice<T extends string>(
+  flag: string,
+  value: string | undefined,
+  choices: readonly T[],
+): T | undefined {
+  if (value === undefined) return undefined
+  if (!(choices as readonly string[]).includes(value)) {
+    throw new UsageError(
+      `option '${flag}' argument '${value}' is invalid. Allowed choices are ${choices.join(", ")}.`,
+    )
+  }
+  return value as T
+}
+
+/** Maps a `--no-x` boolean to the library's `x: false`, or undefined when unset. */
+function negated(noFlag: boolean | undefined): false | undefined {
+  return noFlag ? false : undefined
+}
+
+/** Returns the name of whichever of `names` appears last on the command line. */
+function lastFlagToken(tokens: ParsedTokens, names: readonly string[]): string | undefined {
+  let lastName: string | undefined
+  for (const token of tokens) {
+    if (token.kind === "option" && names.includes(token.name)) lastName = token.name
+  }
+  return lastName
+}
+
+function buildFlags(values: ParsedValues, tokens: ParsedTokens): ParsedFlags {
+  const flags: ParsedFlags = {
+    write: values.write,
+    check: values.check,
+    cache: negated(values["no-cache"]),
+    cacheLocation: values["cache-location"],
+    ignorePath: values["ignore-path"],
+    stdinFilepath: values["stdin-filepath"],
+    type: parseChoice("--type", values.type, FILE_TYPES),
+    punctuationStyle: parseChoice("--punctuation-style", values["punctuation-style"], PUNCTUATION_STYLES),
+    dashStyle: parseChoice("--dash-style", values["dash-style"], DASH_STYLES),
+    symbols: negated(values["no-symbols"]),
+    collapseSpaces: negated(values["no-collapse-spaces"]),
+    arrows: negated(values["no-arrows"]),
+    fractions: values.fractions,
+    degrees: values.degrees,
+    superscript: values.superscript,
+    ligatures: values.ligatures,
+    emphasisMarker: parseChoice("--emphasis-marker", values["emphasis-marker"], EMPHASIS_MARKERS),
+    strongMarker: parseChoice("--strong-marker", values["strong-marker"], EMPHASIS_MARKERS),
+    bulletMarker: parseChoice("--bullet-marker", values["bullet-marker"], BULLET_MARKERS),
+    ruleMarker: parseChoice("--rule-marker", values["rule-marker"], RULE_MARKERS),
+    skipTag: values["skip-tag"],
+    skipClass: values["skip-class"],
+    fragment: negated(values["no-fragment"]),
+  }
+  // nbsp is tri-state: --nbsp / --no-nbsp / unset stays undefined so the
+  // per-sink default applies (on for HTML, off for Markdown). When both
+  // appear, the last one on the command line wins.
+  const nbspToken = lastFlagToken(tokens, ["nbsp", "no-nbsp"])
+  if (nbspToken !== undefined) flags.nbsp = nbspToken === "nbsp"
+  // config is likewise last-one-wins between --config <path> and --no-config.
+  const configToken = lastFlagToken(tokens, ["config", "no-config"])
+  if (configToken !== undefined) flags.config = configToken === "config" ? values.config : false
+  return flags
 }
 
 function inferFileType(path: string, override?: FileType): FileType {
@@ -112,6 +229,12 @@ function inferFileType(path: string, override?: FileType): FileType {
   )
 }
 
+// A config file may legitimately mix markdown-only and HTML-only keys for use
+// across file types; transformContent strips the keys the sink doesn't accept.
+const CLI_CONFIG_KEYS: readonly string[] = [
+  ...new Set([...MARKDOWN_OPTION_KEYS, ...HTML_OPTION_KEYS]),
+]
+
 // Config keys must match library option names (punctuationStyle, skipTags, …),
 // not the kebab-cased CLI flag names.
 async function loadConfig(
@@ -123,6 +246,11 @@ async function loadConfig(
   const explorer = cosmiconfig("punctilio")
   const result = configPath ? await explorer.load(configPath) : await explorer.search(cwd)
   if (!result || result.isEmpty) return {}
+  try {
+    assertKnownOptionKeys(result.config as object, CLI_CONFIG_KEYS, `config file ${result.filepath}`)
+  } catch (err) {
+    throw new UsageError((err as Error).message)
+  }
   return result.config as CliOptions
 }
 
@@ -212,7 +340,7 @@ function buildOptions(flags: ParsedFlags): CliOptions {
   if (flags.punctuationStyle) opts.punctuationStyle = flags.punctuationStyle
   if (flags.dashStyle) opts.dashStyle = flags.dashStyle
   if (flags.symbols === false) opts.symbols = false
-  if (flags.nbsp === false) opts.nbsp = false
+  if (flags.nbsp !== undefined) opts.nbsp = flags.nbsp
   if (flags.collapseSpaces === false) opts.collapseSpaces = false
   if (flags.arrows === false) opts.includeArrows = false
   if (flags.fractions) opts.fractions = true
@@ -229,8 +357,13 @@ function buildOptions(flags: ParsedFlags): CliOptions {
   return opts
 }
 
+// The merged options may carry keys for the other sink (e.g. emphasisMarker
+// alongside skipTags from one shared config); strip the inapplicable ones so
+// each sink's strict key validation only sees keys it understands.
 async function transformContent(input: string, type: FileType, opts: CliOptions): Promise<string> {
-  return type === "md" ? transformMarkdown(input, opts) : transformHtml(input, opts)
+  return type === "md"
+    ? transformMarkdown(input, omitKeys(opts, HTML_ONLY_OPTION_KEYS) as MarkdownOptions)
+    : transformHtml(input, omitKeys(opts, MARKDOWN_ONLY_OPTION_KEYS) as HtmlOptions)
 }
 
 // Unified pipelines unconditionally append a trailing newline; undo if original lacked one.
@@ -264,22 +397,18 @@ async function readPackageVersion(): Promise<string> {
 /** Returns exit code: 0 success, 1 `--check` saw changes, 2 usage error. */
 export async function runCli(args: string[], io: CliIO): Promise<number> {
   const version = await readPackageVersion()
-  const program = buildProgram(version, io)
-
-  try {
-    program.parse(args, { from: "user" })
-  } catch (err) {
-    /* istanbul ignore if -- commander only throws CommanderError from parse */
-    if (!(err instanceof CommanderError)) throw err
-    if (err.code === "commander.helpDisplayed" || err.code === "commander.version") return 0
-    return 2
-  }
-
-  const flags = program.opts() as ParsedFlags
-  const positionals = program.args
 
   try {
-    return await runValidated(flags, positionals, io, program, version)
+    const { positionals, tokens, values } = parseRawArgs(args)
+    if (values.help) {
+      io.stdout.write(HELP_TEXT)
+      return 0
+    }
+    if (values.version) {
+      io.stdout.write(`${version}\n`)
+      return 0
+    }
+    return await runValidated(buildFlags(values, tokens), positionals, io, version)
   } catch (err) {
     if (err instanceof UsageError) {
       io.stderr.write(`Error: ${err.message}\n`)
@@ -298,7 +427,6 @@ async function runValidated(
   flags: ParsedFlags,
   positionals: string[],
   io: CliIO,
-  program: Command,
   version: string,
 ): Promise<number> {
   const cwd = process.cwd()
@@ -309,8 +437,15 @@ async function runValidated(
   )
   const opts: CliOptions = { ...config, ...buildOptions(flags) }
   const check = flags.check ?? false
+  const write = flags.write ?? false
+  if (check && write) {
+    throw new UsageError("--write and --check are mutually exclusive.")
+  }
 
   if (readsStdin(positionals, flags)) {
+    if (write) {
+      throw new UsageError("--write cannot be used when reading from stdin.")
+    }
     const fileArgs = positionals.filter((p) => p !== "-")
     if (fileArgs.length > 0) {
       throw new UsageError("'-' cannot be combined with file arguments.")
@@ -328,14 +463,16 @@ async function runValidated(
   }
 
   if (positionals.length === 0) {
-    io.stderr.write(program.helpInformation())
+    io.stderr.write(HELP_TEXT)
     return 2
   }
 
   const ig = loadIgnore(cwd, flags.ignorePath)
   const files = await discoverFiles(positionals, cwd, ig)
 
-  const cacheLocation = flags.cache === false
+  // In stdout mode every file's content must be produced, so a cache hit
+  // could never skip work; only --write and --check use the cache.
+  const cacheLocation = flags.cache === false || (!write && !check)
     ? undefined
     : resolve(cwd, flags.cacheLocation ?? DEFAULT_CACHE_LOCATION)
   const cache = cacheLocation ? loadCache(cacheLocation, io.stderr) : undefined
@@ -357,6 +494,10 @@ async function runValidated(
     }
 
     const formatted = matchTrailingNewline(original, await transformContent(original, type, opts))
+    if (!write && !check) {
+      io.stdout.write(formatted)
+      continue
+    }
     const unchanged = original === formatted
     if (!unchanged) {
       anyChanged = true

package/src/html.ts

@@ -3,8 +3,8 @@ import rehypeParse from "rehype-parse"
 import rehypeStringify from "rehype-stringify"
 import QuickLRU from "quick-lru"
 
-import { rehypePunctilio, type RehypePunctilioOptions } from "./rehype.js"
-import { stableStringify } from "./utils.js"
+import { REHYPE_ONLY_OPTION_KEYS, REHYPE_OPTION_KEYS, rehypePunctilio, type RehypePunctilioOptions } from "./rehype.js"
+import { assertKnownOptionKeys, stableStringify } from "./utils.js"
 
 export interface HtmlOptions extends RehypePunctilioOptions {
   /**
@@ -15,6 +15,13 @@ export interface HtmlOptions extends RehypePunctilioOptions {
   fragment?: boolean
 }
 
+/** Option keys handled by the HTML pipeline (parser plus rehype plugin)
+ * rather than `transform()`. */
+export const HTML_ONLY_OPTION_KEYS: readonly string[] = ["fragment", ...REHYPE_ONLY_OPTION_KEYS]
+
+/** Runtime list of valid `transformHtml` option keys. */
+export const HTML_OPTION_KEYS: readonly string[] = [...REHYPE_OPTION_KEYS, "fragment"]
+
 function createProcessor(options: HtmlOptions) {
   const { fragment, ...punctilioOptions } = options
   return unified()
@@ -38,6 +45,8 @@ export async function transformHtml(
   input: string,
   options: HtmlOptions = {}
 ): Promise<string> {
+  assertKnownOptionKeys(options, HTML_OPTION_KEYS, "transformHtml")
+
   // 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.

package/src/index.ts

@@ -139,9 +139,11 @@ export interface TransformOptions {
   /**
    * Whether to verify that the transformation is idempotent (running twice
    * produces the same result). When enabled, throws an error if the second
-   * pass produces a different result than the first.
+   * pass produces a different result than the first. The check doubles the
+   * cost of every transform and only detects punctilio's own bugs, so it is
+   * off by default; enable it in test suites or when debugging.
    *
-   * Default: true
+   * Default: false
    */
   checkIdempotency?: boolean
 
@@ -151,7 +153,7 @@ import { niceQuotes } from "./quotes.js"
 import { hyphenReplace } from "./dashes.js"
 import { collapseSpaces as collapseSpacesTransform, degrees as degreesTransform, fractions as fractionsTransform, punctuationLigatures as ligaturesTransform, primeMarks, superscriptOrdinal as superscriptTransform, symbolTransform } from "./symbols.js"
 import { nbspTransform as nbspTransformFn } from "./nbsp.js"
-import { assertSeparatorCountPreserved, filterUndefined, formatErrorString } from "./utils.js"
+import { assertKnownOptionKeys, assertSeparatorCountPreserved, filterUndefined, formatErrorString } from "./utils.js"
 import { DEFAULT_SEPARATOR, ISSUES_URL, UNICODE_SYMBOLS } from "./constants.js"
 
 export {
@@ -181,12 +183,21 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
   ligatures: false,
   nbsp: true,
   collapseSpaces: true,
-  checkIdempotency: true,
+  checkIdempotency: false,
   punctuationStyle: "american",
   dashStyle: "american",
 }
 
+/** Runtime list of valid `transform()` option keys, derived from the option
+ * defaults so it cannot drift from {@link TransformOptions}. */
+export const TRANSFORM_OPTION_KEYS: readonly string[] = [
+  ...Object.keys(defaultOpts),
+  "separator",
+]
+
 export function transform(text: string, options: TransformOptions = {}): string {
+  assertKnownOptionKeys(options, TRANSFORM_OPTION_KEYS, "transform")
+
   const separator = options.separator ?? DEFAULT_SEPARATOR
 
   if (separator.length === 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
 
@@ -50,6 +50,12 @@ export interface RehypePunctilioOptions
 
 const DEFAULT_SKIP_TAGS = ["code", "pre", "script", "style", "kbd", "var", "samp", "template", "math", "svg"]
 
+/** Option keys handled by `rehypePunctilio` itself rather than `transform()`. */
+export const REHYPE_ONLY_OPTION_KEYS: readonly string[] = ["skipTags", "skipClasses", "shouldSkipText"]
+
+/** 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 +272,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,
@@ -319,7 +335,7 @@ export function collectTransformableElements(
     hasTextDescendant(node, shouldSkip)
 
   if (
-    TRANSFORMABLE_ELEMENTS.has(node.tagName) &&
+    isTransformableElement(node.tagName) &&
     (hasDirectText || hasTextDescendants)
   ) {
     results.push(node)
@@ -354,6 +370,8 @@ 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 = [],
@@ -377,11 +395,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,
   }

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}`
         }