punctilio 5.4.8 → 5.4.9

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

package/src/peer-dependencies.ts

@@ -0,0 +1,58 @@
+import type { HtmlOptions } from "./html.js"
+import type { MarkdownOptions } from "./markdown.js"
+
+export type SinkType = "md" | "html"
+
+/** Imports a bare package specifier; injectable so tests can simulate an uninstalled peer. */
+export type PeerImporter = (packageName: string) => Promise<unknown>
+
+export interface SinkTransformers {
+  md: (input: string, options: MarkdownOptions) => Promise<string>
+  html: (input: string, options: HtmlOptions) => Promise<string>
+}
+
+/** The optional peer dependencies each sink needs at runtime. */
+export const SINK_PEER_DEPENDENCIES: Readonly<Record<SinkType, readonly string[]>> = {
+  md: ["unified", "remark-parse", "remark-gfm", "remark-stringify"],
+  html: ["unified", "rehype-parse", "rehype-stringify"],
+}
+
+/** Thrown when an optional peer dependency needed for the requested file type is not installed. */
+export class MissingPeerDependencyError extends Error {}
+
+const MODULE_NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"])
+
+function isMissingPackage(err: unknown, packageName: string): boolean {
+  const { code, message } = err as NodeJS.ErrnoException
+  return MODULE_NOT_FOUND_CODES.has(code ?? "") && message.includes(`'${packageName}'`)
+}
+
+const importPackage: PeerImporter = (packageName) => import(packageName)
+
+/**
+ * Lazily loads the transform for `type`, so only the peers for the file type
+ * being processed need to be installed.
+ * @throws MissingPeerDependencyError naming every absent peer and the install command.
+ */
+export async function loadSinkTransform<T extends SinkType>(
+  type: T,
+  importPeer: PeerImporter = importPackage,
+): Promise<SinkTransformers[T]> {
+  const missing: string[] = []
+  for (const packageName of SINK_PEER_DEPENDENCIES[type]) {
+    try {
+      await importPeer(packageName)
+    } catch (err) {
+      if (!isMissingPackage(err, packageName)) throw err
+      missing.push(packageName)
+    }
+  }
+  if (missing.length > 0) {
+    throw new MissingPeerDependencyError(
+      `Processing ${type === "md" ? "Markdown" : "HTML"} files requires ${missing.join(", ")}, which ` +
+      `${missing.length === 1 ? "is" : "are"} not installed. Install with: npm install ${missing.join(" ")}`,
+    )
+  }
+  if (type === "md") return (await import("./markdown.js")).transformMarkdown as SinkTransformers[T]
+  return (await import("./html.js")).transformHtml as SinkTransformers[T]
+}

package/src/prettier-plugin.ts

@@ -5,8 +5,7 @@ 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 { HTML_ONLY_OPTION_KEYS, MARKDOWN_ONLY_OPTION_KEYS } from "./sink-option-keys.js"
 import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
 import { omitKeys } from "./utils.js"
 

package/src/utils.ts

@@ -41,6 +41,20 @@ export function assertKnownOptionKeys(
   }
 }
 
+const BYTE_ORDER_MARK = "\uFEFF"
+
+/**
+ * Runs `transform` on `input` without its leading BOM, which would otherwise
+ * be parsed as content, and restores the BOM on the result. @internal
+ */
+export async function transformPreservingBom(
+  input: string,
+  transform: (inputWithoutBom: string) => Promise<string>,
+): Promise<string> {
+  if (!input.startsWith(BYTE_ORDER_MARK)) return transform(input)
+  return BYTE_ORDER_MARK + (await transform(input.slice(BYTE_ORDER_MARK.length)))
+}
+
 /** 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> = {}