punctilio 3.13.2 → 4.1.0

package/dist/utils.d.ts

@@ -1,6 +1,8 @@
 /**
  * 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 declare function formatErrorString(content: string, label: string): string;
 /** Throws if any text node contains the separator (would corrupt split/join). */
@@ -18,11 +20,26 @@ interface TextNode {
 export declare function transformTextNodes(textNodes: TextNode[], transformFn: (input: string) => string, separator: string): void;
 /** Throws if a transformation changed the separator count. */
 export declare function assertSeparatorCountPreserved(original: string, transformed: string, separator?: string, transformName?: string): void;
+/** Throws if `options` contains a key not present in `validKeys`. @internal */
+export declare function assertKnownOptionKeys(options: object, validKeys: readonly string[], context: string): void;
+/** Returns a copy of `obj` without the listed keys. @internal */
+export declare function omitKeys<T extends object>(obj: T, keys: readonly string[]): Partial<T>;
 /** Returns a copy of `obj` with `undefined`-valued keys removed. @internal */
 export declare function filterUndefined<T extends object>(obj: T): Partial<T>;
 /** Deterministic JSON string for an options object, suitable as cache key. @internal */
 export declare function stableStringify(obj: object): string;
 /** Extracts named groups from a `.replace()` callback's arguments. @internal */
 export declare function namedGroups<G>(args: unknown[]): 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 declare function replaceCallbackContext(args: unknown[]): {
+    offset: number;
+    input: string;
+};
 export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAanF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,CAS3F;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,EAAE,EACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACtC,SAAS,EAAE,MAAM,GAChB,IAAI,CAmBN;AAED,8DAA8D;AAC9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAA0B,EACrC,aAAa,GAAE,MAAoB,GAClC,IAAI,CAUN;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpE;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAEjD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAanF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,CAS3F;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,EAAE,EACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACtC,SAAS,EAAE,MAAM,GAChB,IAAI,CAmBN;AAED,8DAA8D;AAC9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAA0B,EACrC,aAAa,GAAE,MAAoB,GAClC,IAAI,CAUN;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,MAAM,GACd,IAAI,CAQN;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAMtF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpE;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAUzF"}

package/dist/utils.js

@@ -2,15 +2,17 @@ import { DEFAULT_SEPARATOR, ISSUES_URL } from "./constants.js";
 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, label) {
     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`);
         }
     }
@@ -75,6 +77,23 @@ export function assertSeparatorCountPreserved(original, transformed, separator =
             `Include the input text that caused this error.`);
     }
 }
+/** Throws if `options` contains a key not present in `validKeys`. @internal */
+export function assertKnownOptionKeys(options, validKeys, context) {
+    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(obj, keys) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (!keys.includes(k))
+            result[k] = v;
+    }
+    return result;
+}
 /** Returns a copy of `obj` with `undefined`-valued keys removed. @internal */
 export function filterUndefined(obj) {
     const result = {};
@@ -96,4 +115,22 @@ export function stableStringify(obj) {
 export function namedGroups(args) {
     return args[args.length - 1];
 }
+/**
+ * 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) {
+    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] };
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punctilio",
-  "version": "3.13.2",
+  "version": "4.1.0",
   "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
   "type": "module",
   "sideEffects": false,
@@ -76,7 +76,7 @@
   },
   "homepage": "https://github.com/alexander-turner/punctilio#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "devDependencies": {
     "@eslint/js": "9.39.4",
@@ -145,7 +145,6 @@
     }
   },
   "dependencies": {
-    "commander": "14.0.3",
     "cosmiconfig": "9.0.1",
     "escape-string-regexp": "5.0.0",
     "ignore": "7.0.5",

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/dashes.ts

@@ -79,10 +79,10 @@ export function enDashNumberRange(text: string, options: DashOptions = {}): stri
       // as ranges. Space/NNBSP/thin-space grouping isn't captured by the outer
       // range regex, so those variants currently aren't affected here.
       if (/^\d{3}$/.test(startNum) && /^\d{4}$/.test(endNum)) return args[0] as string
-      // Skip US toll-free prefix pattern: 1-800, 1-888, 1-877, etc.
-      // All US toll-free area codes start with 8 (800, 888, 877, 866, 855, 844, 833).
-      // We only block 1-8XX to avoid false negatives on legitimate ranges like 1-100.
-      if (/^1$/.test(startNum) && /^8\d{2}$/.test(endNum)) return args[0] as string
+      // Skip US toll-free prefix pattern: 1-800, 1-888, 1-877, etc. Only the
+      // seven real toll-free codes (800, 888, 877, 866, 855, 844, 833) are
+      // blocked, so genuine ranges like 1-850 or 1-810 still en-dash.
+      if (/^1$/.test(startNum) && /^8(?:00|88|77|66|55|44|33)$/.test(endNum)) return args[0] as string
       return `${groups.precedingAreaCode ?? ""}${groups.start}${EN_DASH}${groups.end}${groups.suffix ?? ""}`
     }
   )

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) {