punctilio 5.4.8 → 5.4.10

package/src/cli.ts

@@ -2,7 +2,7 @@
 
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"
-import { readFile, rename, writeFile } from "node:fs/promises"
+import { chmod, readFile, realpath, rename, rm, stat, 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"
@@ -11,9 +11,10 @@ import { cosmiconfig } from "cosmiconfig"
 import ignore, { type Ignore } from "ignore"
 import { glob } from "tinyglobby"
 
+import { HTML_ONLY_OPTION_KEYS, MARKDOWN_ONLY_OPTION_KEYS } from "./sink-option-keys.js"
 import type { MarkdownOptions } from "./markdown.js"
 import type { HtmlOptions } from "./html.js"
-import { HTML_ONLY_OPTION_KEYS, HTML_OPTION_KEYS, MARKDOWN_ONLY_OPTION_KEYS, MARKDOWN_OPTION_KEYS } from "./sink-option-keys.js"
+import { loadSinkTransform, MissingPeerDependencyError, type PeerImporter } from "./peer-dependencies.js"
 import { PUNCTUATION_STYLES, type PunctuationStyle } from "./quotes.js"
 import { DASH_STYLES, type DashStyle } from "./dashes.js"
 import { assertKnownOptionKeys, omitKeys, stableStringify } from "./utils.js"
@@ -25,6 +26,8 @@ interface CliIO {
   stdin: AsyncIterable<string | Buffer>
   stdout: NodeJS.WritableStream
   stderr: NodeJS.WritableStream
+  /** Overrides how optional peer dependencies are imported; tests use it to simulate one being absent. */
+  importPeer?: PeerImporter
 }
 
 class UsageError extends Error {}
@@ -133,7 +136,7 @@ Options:
   --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
+  --no-fragment               always parse HTML as a full document (default: a full document is detected from a leading <!doctype> or <html>)
   -h, --help                  display help for command
 `
 
@@ -230,11 +233,74 @@ function inferFileType(path: string, override?: FileType): FileType {
   )
 }
 
+interface ConfigValueRule {
+  expected: string
+  isValid: (value: unknown) => boolean
+}
+
+const BOOLEAN_RULE: ConfigValueRule = {
+  expected: "a boolean",
+  isValid: (value) => typeof value === "boolean",
+}
+const STRING_ARRAY_RULE: ConfigValueRule = {
+  expected: "an array of strings",
+  isValid: (value) => Array.isArray(value) && value.every((item) => typeof item === "string"),
+}
+const FUNCTION_RULE: ConfigValueRule = {
+  expected: "a function",
+  isValid: (value) => typeof value === "function",
+}
+
+function oneOfRule(choices: readonly string[]): ConfigValueRule {
+  return {
+    expected: `one of ${choices.join(", ")}`,
+    isValid: (value) => typeof value === "string" && choices.includes(value),
+  }
+}
+
+// `satisfies` makes the compiler flag any option key that lacks a rule.
+const CONFIG_VALUE_RULES = {
+  symbols: BOOLEAN_RULE,
+  collapseSpaces: BOOLEAN_RULE,
+  includeArrows: BOOLEAN_RULE,
+  fractions: BOOLEAN_RULE,
+  degrees: BOOLEAN_RULE,
+  superscript: BOOLEAN_RULE,
+  ligatures: BOOLEAN_RULE,
+  nbsp: BOOLEAN_RULE,
+  fragment: BOOLEAN_RULE,
+  transformAllElements: BOOLEAN_RULE,
+  punctuationStyle: oneOfRule(PUNCTUATION_STYLES),
+  dashStyle: oneOfRule(DASH_STYLES),
+  emphasisMarker: oneOfRule(EMPHASIS_MARKERS),
+  strongMarker: oneOfRule(EMPHASIS_MARKERS),
+  bulletMarker: oneOfRule(BULLET_MARKERS),
+  ruleMarker: oneOfRule(RULE_MARKERS),
+  skipTags: STRING_ARRAY_RULE,
+  skipClasses: STRING_ARRAY_RULE,
+  shouldSkipText: FUNCTION_RULE,
+} as const satisfies Record<keyof CliOptions, ConfigValueRule>
+
 // 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]),
-]
+const CLI_CONFIG_KEYS: readonly string[] = Object.keys(CONFIG_VALUE_RULES)
+
+// Keys are checked first, so every key present has a rule.
+function assertValidConfig(config: unknown, source: string): asserts config is CliOptions {
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new UsageError(`${source} must contain an object of options.`)
+  }
+  assertKnownOptionKeys(config, CLI_CONFIG_KEYS, source)
+  for (const [key, value] of Object.entries(config)) {
+    if (value === undefined) continue
+    const rule: ConfigValueRule = CONFIG_VALUE_RULES[key as keyof CliOptions]
+    if (!rule.isValid(value)) {
+      throw new UsageError(
+        `Invalid value for "${key}" in ${source}: expected ${rule.expected}, got ${JSON.stringify(value)}.`,
+      )
+    }
+  }
+}
 
 // Config keys must match library option names (punctuationStyle, skipTags, …),
 // not the kebab-cased CLI flag names.
@@ -248,11 +314,11 @@ async function loadConfig(
   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}`)
+    assertValidConfig(result.config, `config file ${result.filepath}`)
   } catch (err) {
-    throw new UsageError((err as Error).message)
+    throw err instanceof UsageError ? err : new UsageError((err as Error).message)
   }
-  return result.config as CliOptions
+  return result.config
 }
 
 function loadIgnore(cwd: string, ignorePath: string | undefined): Ignore {
@@ -273,9 +339,20 @@ function isLiteralPath(pattern: string, cwd: string): boolean {
   return !hasGlobMetacharacters(pattern) || existsSync(resolve(cwd, pattern))
 }
 
-// Literal positionals pass through untouched so they error loudly if missing and
-// bypass ignore rules (naming a file explicitly is an intent to format it).
-// Ignore rules and the zero-match warning apply only to glob-expanded paths.
+// Dependency and VCS trees are never project sources; glob expansion skips them.
+const DEFAULT_GLOB_IGNORES = ["**/node_modules/**", "**/.git/**"]
+
+function isIgnored(file: string, cwd: string, ig: Ignore): boolean {
+  const rel = relative(cwd, file)
+  return !rel.startsWith("..") && ig.ignores(rel)
+}
+
+// Literal positionals pass through to the read step so a missing file errors
+// loudly. Ignore rules apply to literals and glob expansions alike, because
+// tools like pre-commit pass every staged file by name. Each glob is expanded
+// on its own, so one that matches nothing is a usage error even when another
+// glob matches; one whose matches are all ignored only warns. Negated globs
+// (`!pattern`) exclude from every other glob rather than matching on their own.
 async function discoverFiles(
   patterns: string[],
   cwd: string,
@@ -284,17 +361,33 @@ async function discoverFiles(
 ): Promise<string[]> {
   const literals = patterns.filter((p) => isLiteralPath(p, cwd))
   const globs = patterns.filter((p) => !isLiteralPath(p, cwd))
-  const expanded = globs.length > 0
-    ? await glob(globs, { cwd, absolute: true, onlyFiles: true })
-    : []
-  const kept = expanded.filter((file) => {
-    const rel = relative(cwd, file)
-    return rel.startsWith("..") || !ig.ignores(rel)
-  })
-  if (globs.length > 0 && kept.length === 0) {
-    stderr.write(`Warning: no files matched: ${globs.join(" ")}\n`)
+  const negatedGlobs = globs.filter((pattern) => pattern.startsWith("!"))
+  const positiveGlobs = globs.filter((pattern) => !pattern.startsWith("!"))
+  const expansions = await Promise.all(
+    positiveGlobs.map(async (pattern) => ({
+      pattern,
+      files: await glob([pattern, ...negatedGlobs], {
+        cwd,
+        absolute: true,
+        onlyFiles: true,
+        ignore: DEFAULT_GLOB_IGNORES,
+      }),
+    })),
+  )
+  const unmatched = positiveGlobs.length === 0
+    ? globs
+    : expansions.filter(({ files }) => files.length === 0).map(({ pattern }) => pattern)
+  if (unmatched.length > 0) {
+    throw new UsageError(`no files matched: ${unmatched.join(" ")}`)
   }
-  return [...new Set([...literals.map((p) => resolve(cwd, p)), ...kept])]
+  const keptExpanded: string[] = []
+  for (const { pattern, files } of expansions) {
+    const kept = files.filter((file) => !isIgnored(file, cwd, ig))
+    if (kept.length === 0) stderr.write(`Warning: every file matched by ${pattern} is ignored\n`)
+    keptExpanded.push(...kept)
+  }
+  const keptLiterals = literals.map((p) => resolve(cwd, p)).filter((file) => !isIgnored(file, cwd, ig))
+  return [...new Set([...keptLiterals, ...keptExpanded])]
 }
 
 interface CacheEntry {
@@ -347,10 +440,20 @@ function saveCache(location: string, cache: Cache): void {
 
 // Replace a file's contents atomically: write a sibling temp file, then rename
 // it over the target so an interrupted run can never leave a half-written file.
-async function atomicWriteFile(path: string, contents: string): Promise<void> {
-  const tmpPath = `${path}.${process.pid}.tmp`
-  await writeFile(tmpPath, contents)
-  await rename(tmpPath, path)
+// The temp file replaces the symlink's target (not the link itself) and takes
+// over the original file's permission bits; it is removed if anything fails.
+export async function atomicWriteFile(path: string, contents: string): Promise<void> {
+  const targetPath = await realpath(path)
+  const { mode } = await stat(targetPath)
+  const tmpPath = `${targetPath}.${process.pid}.tmp`
+  try {
+    await writeFile(tmpPath, contents, { mode: mode & 0o7777 })
+    await chmod(tmpPath, mode & 0o7777)
+    await rename(tmpPath, targetPath)
+  } catch (err) {
+    await rm(tmpPath, { force: true })
+    throw err
+  }
 }
 
 // cwd-relative so the cache survives directory moves and cross-machine syncs.
@@ -382,30 +485,42 @@ function buildOptions(flags: ParsedFlags): CliOptions {
 
 // 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. The sinks
-// load lazily because they import the optional unified peers, which --help,
-// --version and usage errors must not need.
-async function transformContent(input: string, type: FileType, opts: CliOptions): Promise<string> {
+// each sink's strict key validation only sees keys it understands.
+async function transformContent(
+  input: string,
+  type: FileType,
+  opts: CliOptions,
+  importPeer: PeerImporter | undefined,
+): Promise<string> {
   if (type === "md") {
-    const { transformMarkdown } = await import("./markdown.js")
+    const transformMarkdown = await loadSinkTransform("md", importPeer)
     return transformMarkdown(input, omitKeys(opts, HTML_ONLY_OPTION_KEYS) as MarkdownOptions)
   }
-  const { transformHtml } = await import("./html.js")
+  const transformHtml = await loadSinkTransform("html", importPeer)
   return transformHtml(input, omitKeys(opts, MARKDOWN_ONLY_OPTION_KEYS) as HtmlOptions)
 }
 
-// The unified pipelines emit LF-only output and unconditionally append a
-// trailing newline. Restore the source's line-ending style and trailing-newline
-// presence so a CRLF file doesn't gain mixed endings (which would make --check
-// report a change forever and --write churn on every run).
+async function formatDocument(
+  original: string,
+  type: FileType,
+  opts: CliOptions,
+  importPeer: PeerImporter | undefined,
+): Promise<string> {
+  return matchLineEndings(original, await transformContent(original, type, opts, importPeer))
+}
+
+// The unified pipelines emit LF-only output. Markdown always ends in a newline;
+// a full HTML document may end without one (its final newline can be dropped
+// or sit inside <body>). Restore the source's line-ending style and
+// trailing-newline presence so a CRLF file doesn't gain mixed endings (which
+// would make --check report a change forever and --write churn on every run).
 function matchLineEndings(original: string, formatted: string): string {
-  // Normalize the LF output back to CRLF when the source used it.
-  let out = original.includes("\r\n")
+  const lineEnding = original.includes("\r\n") ? "\r\n" : "\n"
+  const out = lineEnding === "\r\n"
     ? formatted.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n")
     : formatted
-  // Drop the appended trailing newline if the original had none.
-  if (!/\n$/.test(original)) out = out.replace(/\r?\n$/, "")
-  return out
+  if (!original.endsWith("\n")) return out.replace(/\r?\n$/, "")
+  return out.endsWith("\n") ? out : out + lineEnding
 }
 
 async function readStdin(stdin: AsyncIterable<string | Buffer>): Promise<string> {
@@ -443,7 +558,7 @@ export async function runCli(args: string[], io: CliIO): Promise<number> {
     }
     return await runValidated(buildFlags(values, tokens), positionals, io, version)
   } catch (err) {
-    if (err instanceof UsageError) {
+    if (err instanceof UsageError || err instanceof MissingPeerDependencyError) {
       io.stderr.write(`Error: ${err.message}\n`)
       return 2
     }
@@ -475,6 +590,10 @@ async function runValidated(
     throw new UsageError("--write and --check are mutually exclusive.")
   }
 
+  if (flags.stdinFilepath !== undefined && positionals.some((p) => p !== "-")) {
+    throw new UsageError("--stdin-filepath cannot be combined with file arguments.")
+  }
+
   if (readsStdin(positionals, flags)) {
     if (write) {
       throw new UsageError("--write cannot be used when reading from stdin.")
@@ -489,7 +608,7 @@ async function runValidated(
       throw new UsageError("Reading from stdin requires --type md|html or --stdin-filepath <path>.")
     }
     const input = await readStdin(io.stdin)
-    const output = matchLineEndings(input, await transformContent(input, type, opts))
+    const output = await formatDocument(input, type, opts, io.importPeer)
     if (check) return input === output ? 0 : 1
     io.stdout.write(output)
     return 0
@@ -502,6 +621,9 @@ async function runValidated(
 
   const ig = loadIgnore(cwd, flags.ignorePath)
   const files = await discoverFiles(positionals, cwd, ig, io.stderr)
+  // Resolve every file's type up front so an unsupported extension fails
+  // before any file has been rewritten.
+  const types = files.map((file) => inferFileType(file, flags.type))
 
   // 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.
@@ -512,8 +634,8 @@ async function runValidated(
   const optionsHash = cache ? hashOptions(opts) : ""
 
   let anyChanged = false
-  for (const path of files) {
-    const type = inferFileType(path, flags.type)
+  for (const [index, path] of files.entries()) {
+    const type = types[index]
     const original = await readFile(path, "utf8")
     const key = cache ? cacheKey(path, cwd) : ""
     if (cache) {
@@ -527,7 +649,7 @@ async function runValidated(
       ) continue
     }
 
-    const formatted = matchLineEndings(original, await transformContent(original, type, opts))
+    const formatted = await formatDocument(original, type, opts, io.importPeer)
     if (!write && !check) {
       io.stdout.write(formatted)
       continue
@@ -551,9 +673,19 @@ async function runValidated(
   return check && anyChanged ? 1 : 0
 }
 
+// npm links bins through symlinks, so argv[1] is the link, not the module file.
+export function isMainModule(moduleUrl: string, entryPath: string | undefined): boolean {
+  if (entryPath === undefined) return false
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(entryPath)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false
+    throw err
+  }
+}
+
 /* istanbul ignore next -- entry-point bootstrap; logic is covered via runCli */
-// npm runs the bin through a node_modules/.bin symlink, so compare real paths.
-if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
+if (isMainModule(import.meta.url, process.argv[1])) {
   runCli(process.argv.slice(2), {
     stdin: process.stdin,
     stdout: process.stdout,

package/src/constants.ts

@@ -130,6 +130,9 @@ const BRACKET_PAIRS: readonly (readonly [string, string])[] = [
   [UNICODE_SYMBOLS.LEFT_LENTICULAR_BRACKET, UNICODE_SYMBOLS.RIGHT_LENTICULAR_BRACKET],
 ]
 
+/** Opening brackets, the counterparts of {@link CLOSING_BRACKETS}. */
+export const OPENING_BRACKETS: readonly string[] = BRACKET_PAIRS.map(([opening]) => opening)
+
 /**
  * Punctuation that opens a construct and so binds rightward, to the text after
  * it rather than the text before: brackets, the Spanish inverted marks, and the
@@ -142,7 +145,7 @@ const BRACKET_PAIRS: readonly (readonly [string, string])[] = [
  * settle, so a consumer that wants to treat one as an opener owns that call.
  */
 export const OPENING_PUNCTUATION: readonly string[] = [
-  ...BRACKET_PAIRS.map(([opening]) => opening),
+  ...OPENING_BRACKETS,
   UNICODE_SYMBOLS.INVERTED_EXCLAMATION,
   UNICODE_SYMBOLS.INVERTED_QUESTION,
   UNICODE_SYMBOLS.LEFT_DOUBLE_QUOTE,

package/src/dashes.ts

@@ -12,6 +12,7 @@ export interface DashOptions {
 const {
   EN_DASH, EM_DASH, MINUS, MULTIPLICATION, PLUS_MINUS,
   LEFT_DOUBLE_QUOTE, RIGHT_DOUBLE_QUOTE, LEFT_SINGLE_QUOTE, RIGHT_SINGLE_QUOTE,
+  MODIFIER_LETTER_APOSTROPHE, LEFT_GUILLEMET,
 } = UNICODE_SYMBOLS
 
 // Prevents false-positive ranges in model names like "Llama-2-7B".
@@ -781,7 +782,7 @@ function minusSubtractionPrefixOk(match: RegExpExecArray, view: ProseView, prefi
   return NUM_BODY_RE.test(view.text.slice(numStart, truncatedEnd))
 }
 
-const MINUS_BEFORE_CLASS_RE = new RegExp(`[\\s("'${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}]`)
+const MINUS_BEFORE_CLASS_RE = new RegExp(`[\\s("'${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}${LEFT_GUILLEMET}]`)
 // The folded word glyphs block like the word chars they fold from ("1x|-0"
 // and "1×|-0" must agree), the folded math operators block like the operator
 // chars they fold from (the `!=` → `≠` fold consumes the `=` that blocked
@@ -860,7 +861,7 @@ function convertParentheticalDashes(view: ProseView, style: DashStyle): void {
   if (style === "british") convertUnspacedEmDashes(view, rendered)
 }
 
-const QUOTE_CHARS = `"'${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}`
+const QUOTE_CHARS = `"'${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}${MODIFIER_LETTER_APOSTROPHE}`
 
 const DASH_RUN_CHARS = new Set(["-", EN_DASH, EM_DASH])
 

package/src/html.ts

@@ -1,27 +1,59 @@
+import { Tokenizer } from "parse5"
 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"
-import { HTML_ONLY_OPTION_KEYS, HTML_OPTION_KEYS } from "./sink-option-keys.js"
-import { assertKnownOptionKeys, stableStringify } from "./utils.js"
+import { HTML_OPTION_KEYS } from "./sink-option-keys.js"
+import { assertKnownOptionKeys, omitKeys, stableStringify, transformPreservingBom } from "./utils.js"
+
+export { HTML_ONLY_OPTION_KEYS, HTML_OPTION_KEYS } from "./sink-option-keys.js"
 
 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`.
+   * document. When unset, input that begins with `<!doctype` or `<html`
+   * (after optional whitespace and comments) is parsed as a complete
+   * document and anything else as a fragment.
    */
   fragment?: boolean
 }
 
-export { HTML_ONLY_OPTION_KEYS, HTML_OPTION_KEYS }
+/** True when the first token that is not whitespace or a comment is a doctype
+ * or an `<html>` start tag. Stops tokenizing at that token. */
+function startsFullDocument(input: string): boolean {
+  let isFullDocument: boolean | undefined
+  // Pausing takes effect after the current token, so a token the tokenizer
+  // emits in the same step (a doctype flushed behind text) must not overwrite
+  // the first verdict.
+  const decide = (verdict: boolean): void => {
+    if (isFullDocument !== undefined) return
+    isFullDocument = verdict
+    tokenizer.pause()
+  }
+  const tokenizer = new Tokenizer(
+    {},
+    {
+      onComment: () => {},
+      onWhitespaceCharacter: () => {},
+      onEof: () => {},
+      onDoctype: () => decide(true),
+      onStartTag: (token) => decide(token.tagName === "html"),
+      onEndTag: () => decide(false),
+      onCharacter: () => decide(false),
+      onNullCharacter: () => decide(false),
+    },
+  )
+  tokenizer.write(input, true)
+  return isFullDocument === true
+}
 
-function createProcessor(options: HtmlOptions) {
-  const { fragment, ...punctilioOptions } = options
+function createProcessor(options: HtmlOptions, fragment: boolean) {
+  const punctilioOptions = omitKeys(options, ["fragment"])
   return unified()
-    .use(rehypeParse, { fragment: fragment ?? true })
+    .use(rehypeParse, { fragment })
     .use(rehypePunctilio, punctilioOptions)
     .use(rehypeStringify)
 }
@@ -42,23 +74,32 @@ export async function transformHtml(
   options: HtmlOptions = {}
 ): Promise<string> {
   assertKnownOptionKeys(options, HTML_OPTION_KEYS, "transformHtml")
+  return transformPreservingBom(input, (text) => processHtml(text, options))
+}
 
-  // 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 = stableStringify(options)
+/** Function-valued options aren't JSON-serializable, so the cache key
+ * can't distinguish them; those bypass the cache to avoid returning a
+ * processor wired to a different shouldSkipText. */
+function getProcessor(options: HtmlOptions, fragment: boolean) {
+  if (typeof options.shouldSkipText === "function") return createProcessor(options, fragment)
 
+  const optionsKey = stableStringify({ ...options, fragment })
   let processor = processorCache.get(optionsKey)
   if (!processor) {
-    processor = createProcessor(options)
+    processor = createProcessor(options, fragment)
     processorCache.set(optionsKey, processor)
   }
+  return processor
+}
+
+// The HTML parser files whitespace after `</html>` inside <body>. Moving the
+// input's final newline back out keeps repeated runs from adding a newline
+// inside <body> each time.
+const NEWLINE_INSIDE_DOCUMENT_END_RE = /\n(?<documentEnd><\/body><\/html>)$/
 
-  const result = await processor.process(input)
-  return String(result)
+async function processHtml(input: string, options: HtmlOptions): Promise<string> {
+  const fragment = options.fragment ?? !startsFullDocument(input)
+  const output = String(await getProcessor(options, fragment).process(input))
+  if (fragment || !input.endsWith("\n")) return output
+  return output.replace(NEWLINE_INSIDE_DOCUMENT_END_RE, "$<documentEnd>\n")
 }

package/src/markdown.ts

@@ -4,9 +4,11 @@ import remarkGfm from "remark-gfm"
 import remarkStringify from "remark-stringify"
 import QuickLRU from "quick-lru"
 
+import { MARKDOWN_OPTION_KEYS } from "./sink-option-keys.js"
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
-import { MARKDOWN_ONLY_OPTION_KEYS, MARKDOWN_OPTION_KEYS } from "./sink-option-keys.js"
-import { assertKnownOptionKeys, stableStringify } from "./utils.js"
+import { assertKnownOptionKeys, stableStringify, transformPreservingBom } from "./utils.js"
+
+export { MARKDOWN_ONLY_OPTION_KEYS, MARKDOWN_OPTION_KEYS } from "./sink-option-keys.js"
 
 /**
  * Options for `transformMarkdown`. Inherits the Markdown-sink default of
@@ -33,8 +35,6 @@ export interface MarkdownOptions extends RemarkPunctilioOptions {
   ruleMarker?: "-" | "*" | "_"
 }
 
-export { MARKDOWN_ONLY_OPTION_KEYS, MARKDOWN_OPTION_KEYS }
-
 function createProcessor(options: MarkdownOptions) {
   const {
     emphasisMarker,
@@ -74,12 +74,41 @@ export function clearProcessorCache(): void {
   processorCache.clear()
 }
 
-export async function transformMarkdown(
-  input: string,
-  options: MarkdownOptions = {}
-): Promise<string> {
-  assertKnownOptionKeys(options, MARKDOWN_OPTION_KEYS, "transformMarkdown")
+// Opening fence → fences that may close the block (YAML accepts `...` too).
+// A Map, so a first line like `constructor` cannot resolve to an inherited
+// Object.prototype member.
+const FRONTMATTER_CLOSING_FENCES: ReadonlyMap<string, readonly string[]> = new Map([
+  ["---", ["---", "..."]],
+  ["+++", ["+++"]],
+])
+
+/**
+ * Length of the YAML (`---`) or TOML (`+++`) front matter block at the very
+ * start of `input`, through its closing fence line and newline. 0 when the
+ * input has no terminated front matter block.
+ */
+function frontmatterLength(input: string): number {
+  let lineStart = 0
+  let closingFences: readonly string[] | undefined
+  while (lineStart < input.length) {
+    const newlineIndex = input.indexOf("\n", lineStart)
+    const lineEnd = newlineIndex === -1 ? input.length : newlineIndex + 1
+    const fence = input.slice(lineStart, lineEnd).trimEnd()
+    if (closingFences === undefined) {
+      closingFences = FRONTMATTER_CLOSING_FENCES.get(fence)
+      if (closingFences === undefined) return 0
+    } else if (closingFences.includes(fence)) {
+      return lineEnd
+    }
+    lineStart = lineEnd
+  }
+  return 0
+}
 
+/** Matches blank lines that separate front matter from the document body. */
+const LEADING_BLANK_LINES_RE = /^(?:[ \t]*\r?\n)*/
+
+async function processMarkdown(input: string, options: MarkdownOptions): Promise<string> {
   const optionsKey = stableStringify(options)
 
   let processor = processorCache.get(optionsKey)
@@ -91,3 +120,23 @@ export async function transformMarkdown(
   const result = await processor.process(input)
   return String(result)
 }
+
+export async function transformMarkdown(
+  input: string,
+  options: MarkdownOptions = {}
+): Promise<string> {
+  assertKnownOptionKeys(options, MARKDOWN_OPTION_KEYS, "transformMarkdown")
+  return transformPreservingBom(input, (text) => transformWithFrontmatter(text, options))
+}
+
+async function transformWithFrontmatter(input: string, options: MarkdownOptions): Promise<string> {
+  const frontmatterEnd = frontmatterLength(input)
+  if (frontmatterEnd === 0) return processMarkdown(input, options)
+
+  // Front matter is data (YAML/TOML), not prose; remark would parse it as a
+  // thematic break plus a heading and rewrite it.
+  const body = input.slice(frontmatterEnd)
+  const blankLines = LEADING_BLANK_LINES_RE.exec(body)![0]
+  const transformedBody = await processMarkdown(body.slice(blankLines.length), options)
+  return input.slice(0, frontmatterEnd) + blankLines + transformedBody
+}