@readme/markdown 14.10.1 → 14.10.2

package/dist/lib/render-diff/differ.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural HTML diff for MDX-vs-MDXish render comparison.
+ *
+ * Algorithm overview:
+ *   parseDocument(html, { xmlMode: true }) → walk → canonical {tag, attrs, children} tree
+ *   apply canonicalization pipeline (sort/normalize/collapse)
+ *   compute bottom-up content hash
+ *   fast-path match if hashes equal
+ *   otherwise, recursive walk emitting Change records
+ *
+ * Tree-walk targets the htmlparser2 / domhandler node shape. The canonicalization
+ * rules and severity model are transplanted verbatim from the reference differ.ts
+ * (PR #18479 in the readme repo). The tree-walk is re-targeted to htmlparser2/domhandler.
+ *
+ * The lint disables below are intentional and scoped to this file:
+ * - `no-restricted-syntax` + `no-continue`: this is a tree-walker with greedy
+ *   alignment and lookahead; for-of with continue is the natural shape and
+ *   array iteration helpers would obscure the control flow.
+ * - `@typescript-eslint/no-use-before-define`: helpers are ordered bottom-up
+ *   (primitives first, public `diff()` last) so the public API anchors the
+ *   end of the file.
+ */
+import type { DiffOptions, DiffResult } from './types';
+/**
+ * Diff two rendered HTML strings.
+ *
+ * The diff tool is engine-agnostic — `leftHtml` and `rightHtml` are simply
+ * the two HTML strings to compare in that order. Common use cases:
+ * - MDX vs MDXish (Suite B in this repo)
+ * - Before vs after a `@readme/markdown` version bump on the same source
+ * - Any two HTML strings a consumer wants to compare
+ *
+ * Both strings are canonicalized (whitespace collapse, class sort, attribute
+ * normalization, noise-attr drop, heading-counter strip, void-tag handling,
+ * text-equivalent merging) before comparison.
+ *
+ * A bottom-up content hash provides a fast-path: if both trees hash identically,
+ * `{ status: 'match' }` is returned without a full walk.
+ *
+ * The returned `changes[]` is ordered by document position and is identical
+ * across repeated calls on the same input. Each change carries `left` and
+ * `right` fields corresponding to the two inputs.
+ *
+ * @param leftHtml  - First HTML string to compare.
+ * @param rightHtml - Second HTML string to compare.
+ * @param opts      - Optional canonicalization / diff configuration.
+ * @returns `{ status: 'match' }` or `{ status: 'differ', severity, changes }`.
+ */
+export declare function diff(leftHtml: string, rightHtml: string, opts?: DiffOptions): DiffResult;

package/dist/lib/render-diff/index.d.ts

@@ -0,0 +1,2 @@
+export { diff } from './differ';
+export type { Change, DiffOptions, DiffResult, Preset, Severity } from './types';

package/dist/lib/render-diff/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * TypeScript types for the render-diff HTML diffing tool.
+ *
+ * These types form the public contract for `lib/render-diff/differ.ts`.
+ */
+/**
+ * Severity level of a single diff change or aggregate page diff result.
+ *
+ * - `cosmetic` — minor presentation differences (e.g. `data-*` / `aria-*` attrs)
+ * - `structural` — tag, element, or layout differences
+ * - `content` — visible text or meaningful attribute value differences
+ */
+export type Severity = 'content' | 'cosmetic' | 'structural';
+/**
+ * A single diffed change between two rendered HTML inputs.
+ *
+ * The diff tool is engine-agnostic — `left` and `right` are simply the two
+ * HTML strings passed to `diff()` in that order. Suite B uses them as
+ * MDX vs MDXish; other consumers (e.g. before/after a markdown version bump)
+ * use them however they like.
+ *
+ * Each change is emitted at a specific document-position path.
+ */
+export interface Change {
+    /**
+     * Attribute name — populated only when `kind` is `'attr'`.
+     */
+    attrName?: string;
+    /**
+     * The type of difference detected.
+     *
+     * - `tag`     — element tag mismatch between `left` and `right`
+     * - `attr`    — attribute present, missing, or different value
+     * - `text`    — text node content differs
+     * - `missing` — node present in `left` but absent in `right`
+     * - `extra`   — node present in `right` but absent in `left`
+     */
+    kind: 'attr' | 'extra' | 'missing' | 'tag' | 'text';
+    /**
+     * String representation from the `left` input, or `null` when the node is absent.
+     */
+    left: string | null;
+    /**
+     * Document-position path of the diffed node (top-to-bottom tree-walk order).
+     */
+    path: string;
+    /**
+     * String representation from the `right` input, or `null` when the node is absent.
+     */
+    right: string | null;
+    /**
+     * Severity of this individual change.
+     */
+    severity: Severity;
+}
+/**
+ * Result returned by `diff(leftHtml, rightHtml)`.
+ *
+ * Discriminated union on `status`:
+ * - `'match'` arm collapses to `{ status: 'match' }` — no `severity` or `changes` keys.
+ * - `'differ'` arm carries the full `{ status, severity, changes }` shape.
+ *
+ * TypeScript narrowing on `result.status === 'differ'` exposes `severity` and `changes`.
+ */
+export type DiffResult = {
+    changes: Change[];
+    severity: Severity;
+    status: 'differ';
+} | {
+    status: 'match';
+};
+/**
+ * Canonicalization preset for `diff()`.
+ *
+ * - `'cross-engine'` — full normalization including span-flatten and adjacent-text
+ *   merge. Designed for MDX↔MDXish comparison (Suite B).
+ * - `'minimal'` — lighter normalization; span-flatten and adjacent-text merge are
+ *   skipped. Suitable for same-engine before/after comparison where those transforms
+ *   would mask real structural changes.
+ */
+export type Preset = 'cross-engine' | 'minimal';
+/**
+ * Options accepted by `diff()`.
+ *
+ * All fields are optional. Default behaviour: hash fast-path enabled, all
+ * heading counter suffixes stripped, no additional attributes ignored.
+ */
+export interface DiffOptions {
+    /**
+     * Additional attribute names to drop during canonicalization (lowercased).
+     * Added to the built-in noise-attr set (`data-reactroot`, `data-testid`,
+     * `suppresshydrationwarning`).
+     */
+    attrIgnore?: Set<string>;
+    /**
+     * When `true`, bypass the content-hash fast-path and always perform the full
+     * tree walk. Intended for testing only.
+     */
+    noHashFastPath?: boolean;
+    /**
+     * When `true`, skip stripping `-N` counter suffixes from heading `id` attrs.
+     * Default: `false` (suffixes are stripped so repeated headings compare equal).
+     */
+    preserveHeadingCounters?: boolean;
+    /**
+     * Canonicalization preset. Controls which structural-normalization transforms
+     * are applied before comparison.
+     *
+     * - `'cross-engine'` (default) — full normalization including span-flatten
+     *   and adjacent-text merge. Designed for MDX↔MDXish comparison (Suite B).
+     * - `'minimal'` — lighter normalization; span-flatten and adjacent-text merge
+     *   are skipped. Suitable for same-engine before/after comparison where those
+     *   transforms would mask real structural changes.
+     *
+     * Every normalization `'minimal'` performs is also performed by `'cross-engine'`.
+     * Default: omitting `preset` is equivalent to `'cross-engine'` (backward compatible).
+     */
+    preset?: Preset;
+}

package/dist/lib/render-fixture/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public barrel for `@readme/markdown/render-fixture`.
+ *
+ * Pairs with the engine-free `@readme/markdown/render-diff` subpath: this
+ * bundle DOES include the engine (it has to — its job is to render). A
+ * typical consumer that wants regression coverage across @readme/markdown
+ * version bumps pairs the two:
+ *
+ *   import { renderFixture } from '@readme/markdown/render-fixture';
+ *   import { diff } from '@readme/markdown/render-diff';
+ *
+ *   const oldHtml = readFileSync('snapshot.html', 'utf8');
+ *   const { html: newHtml } = renderFixture(body, ctx, 'mdxish');
+ *   const result = diff(oldHtml, newHtml, { preset: 'minimal' });
+ */
+export { loadFixture } from './loadFixture';
+export type { RenderContext } from './loadFixture';
+export { renderFixture } from './renderFixture';
+export type { Engine, FixtureRenderResult } from './renderFixture';

package/dist/lib/render-fixture/loadFixture.d.ts

@@ -0,0 +1,21 @@
+export interface RenderContext {
+    components: {
+        source: string;
+        tag: string;
+    }[];
+    glossary: {
+        definition: string;
+        term: string;
+    }[];
+    variables: {
+        defaults: {
+            default: string;
+            name: string;
+        }[];
+        user: Record<string, string>;
+    };
+}
+export declare function loadFixture(dir: string): {
+    body: string;
+    ctx: RenderContext;
+};

package/dist/lib/render-fixture/renderFixture.d.ts

@@ -0,0 +1,17 @@
+import type { RenderContext } from './loadFixture';
+export type Engine = 'mdx' | 'mdxish';
+export interface FixtureRenderResult {
+    error: string | null;
+    html: string;
+}
+/**
+ * Renders a fixture body string through the specified engine and returns the
+ * serialized HTML. Renders are deterministic — Date.now and Math.random are
+ * frozen for the duration of each render call.
+ *
+ * For MDXish, the components map is passed to BOTH mdxish() and renderMdxish()
+ * — both call sites need it for custom-block resolution.
+ *
+ * The loader's `ctx.glossary` is mapped onto the engine's `terms` parameter.
+ */
+export declare function renderFixture(body: string, ctx: RenderContext, engine: Engine): FixtureRenderResult;

package/dist/main.js

@@ -101750,6 +101750,22 @@ const positionEndingAtConsumed = (nodePosition, value, consumedLength) => {
         return nodePosition;
     return { start: nodePosition.start, end: pointAfter(nodePosition.start, value.slice(0, consumedLength)) };
 };
+/**
+ * Build a position ending right after the last occurrence of `closingTag` within
+ * this node's span in the original source. Used in the trailing-content path so
+ * the offset is computed against the real source bytes (including blockquote/list
+ * prefixes that were stripped from the html node's value).
+ */
+const positionEndingAtClosingTagInSource = (nodePosition, closingTag, source) => {
+    if (!nodePosition?.start || !nodePosition.end)
+        return nodePosition;
+    const nodeSource = source.slice(nodePosition.start.offset, nodePosition.end.offset);
+    const closingTagOffset = nodeSource.lastIndexOf(closingTag);
+    if (closingTagOffset === -1)
+        return nodePosition;
+    const consumed = nodeSource.slice(0, closingTagOffset + closingTag.length);
+    return { start: nodePosition.start, end: pointAfter(nodePosition.start, consumed) };
+};
 /**
  * Create an MdxJsxFlowElement node from component data.
  */
@@ -101793,9 +101809,10 @@ const substituteNodeWithMdxNode = (parent, index, mdxNode) => {
  * The opening tag, content, and closing tag are all captured in one HTML node
  * (guaranteed by the mdx-component tokenizer).
  */
-const mdxishMdxComponentBlocks = (opts = {}) => tree => {
+const mdxishMdxComponentBlocks = (opts = {}) => (tree, file) => {
     const stack = [tree];
     const safeMode = !!opts.safeMode;
+    const source = file?.value ? String(file.value) : null;
     const parseOpts = { preserveExpressionsAsText: safeMode };
     const processChildNode = (parent, index) => {
         const node = parent.children[index];
@@ -101876,8 +101893,17 @@ const mdxishMdxComponentBlocks = (opts = {}) => tree => {
                 attributes,
                 children: parsedChildren,
                 startPosition: node.position,
-                // End at the closing tag, not at trailing content re-parsed as siblings below.
-                endPosition: positionEndingAtConsumed(node.position, value, leadingWhitespace + openingTagEnd + closingTagIndex + closingTagStr.length),
+                // When trailing content follows the closing tag, compute the end position precisely
+                // within the html node's value so the component doesn't claim that content.
+                // Prefer source-based positioning when the original source is available: the html
+                // node's value has '> '/space prefixes stripped for blockquotes/list items, so
+                // positionEndingAtConsumed would undercount source offsets. When the entire node
+                // is consumed, use the original node position directly.
+                endPosition: contentAfterClose
+                    ? source
+                        ? positionEndingAtClosingTagInSource(node.position, closingTagStr, source)
+                        : positionEndingAtConsumed(node.position, value, leadingWhitespace + openingTagEnd + closingTagIndex + closingTagStr.length)
+                    : node.position,
             });
             substituteNodeWithMdxNode(parent, index, componentNode);
             // After the closing tag, there might be more content to be processed

package/dist/main.node.js

@@ -121974,6 +121974,22 @@ const positionEndingAtConsumed = (nodePosition, value, consumedLength) => {
         return nodePosition;
     return { start: nodePosition.start, end: pointAfter(nodePosition.start, value.slice(0, consumedLength)) };
 };
+/**
+ * Build a position ending right after the last occurrence of `closingTag` within
+ * this node's span in the original source. Used in the trailing-content path so
+ * the offset is computed against the real source bytes (including blockquote/list
+ * prefixes that were stripped from the html node's value).
+ */
+const positionEndingAtClosingTagInSource = (nodePosition, closingTag, source) => {
+    if (!nodePosition?.start || !nodePosition.end)
+        return nodePosition;
+    const nodeSource = source.slice(nodePosition.start.offset, nodePosition.end.offset);
+    const closingTagOffset = nodeSource.lastIndexOf(closingTag);
+    if (closingTagOffset === -1)
+        return nodePosition;
+    const consumed = nodeSource.slice(0, closingTagOffset + closingTag.length);
+    return { start: nodePosition.start, end: pointAfter(nodePosition.start, consumed) };
+};
 /**
  * Create an MdxJsxFlowElement node from component data.
  */
@@ -122017,9 +122033,10 @@ const substituteNodeWithMdxNode = (parent, index, mdxNode) => {
  * The opening tag, content, and closing tag are all captured in one HTML node
  * (guaranteed by the mdx-component tokenizer).
  */
-const mdxishMdxComponentBlocks = (opts = {}) => tree => {
+const mdxishMdxComponentBlocks = (opts = {}) => (tree, file) => {
     const stack = [tree];
     const safeMode = !!opts.safeMode;
+    const source = file?.value ? String(file.value) : null;
     const parseOpts = { preserveExpressionsAsText: safeMode };
     const processChildNode = (parent, index) => {
         const node = parent.children[index];
@@ -122100,8 +122117,17 @@ const mdxishMdxComponentBlocks = (opts = {}) => tree => {
                 attributes,
                 children: parsedChildren,
                 startPosition: node.position,
-                // End at the closing tag, not at trailing content re-parsed as siblings below.
-                endPosition: positionEndingAtConsumed(node.position, value, leadingWhitespace + openingTagEnd + closingTagIndex + closingTagStr.length),
+                // When trailing content follows the closing tag, compute the end position precisely
+                // within the html node's value so the component doesn't claim that content.
+                // Prefer source-based positioning when the original source is available: the html
+                // node's value has '> '/space prefixes stripped for blockquotes/list items, so
+                // positionEndingAtConsumed would undercount source offsets. When the entire node
+                // is consumed, use the original node position directly.
+                endPosition: contentAfterClose
+                    ? source
+                        ? positionEndingAtClosingTagInSource(node.position, closingTagStr, source)
+                        : positionEndingAtConsumed(node.position, value, leadingWhitespace + openingTagEnd + closingTagIndex + closingTagStr.length)
+                    : node.position,
             });
             substituteNodeWithMdxNode(parent, index, componentNode);
             // After the closing tag, there might be more content to be processed