@readme/markdown 14.10.0 → 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

@@ -76783,6 +76783,7 @@ const readmeComponents = (opts) => () => tree => {
 
 
 
+
 const imageAttrs = ['align', 'alt', 'caption', 'border', 'height', 'src', 'title', 'width', 'lazy', 'className'];
 const readmeToMdx = () => tree => {
     // Unwrap pinned nodes, replace rdme-pin with its child node
@@ -76873,7 +76874,11 @@ const readmeToMdx = () => tree => {
         }
     });
     visit(tree, NodeTypes.imageBlock, (image, index, parent) => {
-        const attributes = toAttributes({ ...image, ...image.data.hProperties }, imageAttrs);
+        // Special case for caption: Captions are parsed as children of the image node, so we need to extract them explicitly
+        const captionChildren = Array.isArray(image.children) ? image.children : [];
+        // We want to add it back to the attributes, so re-serialize it to string
+        const caption = captionChildren.length ? toMarkdown({ type: 'root', children: captionChildren }).trim() : '';
+        const attributes = toAttributes({ ...image, ...image.data.hProperties, ...(caption && { caption }) }, imageAttrs);
         if (hasExtra(attributes)) {
             parent.children.splice(index, 1, {
                 type: 'mdxJsxFlowElement',
@@ -98611,6 +98616,11 @@ function smartCamelCase(str) {
     if (str.includes('-')) {
         return str.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
     }
+    // Keys that already carry casing (e.g. `cardWidth`) are correct as-is; running
+    // boundary matching over them mangles inner matches (e.g. `id` inside `Width`).
+    if (/[A-Z]/.test(str)) {
+        return str;
+    }
     const allBoundaries = [...REACT_HTML_PROP_BOUNDARIES, ...CSS_STYLE_PROP_BOUNDARIES, ...CUSTOM_PROP_BOUNDARIES];
     // Return as-is if already a boundary word to avoid incorrect splitting
     if (allBoundaries.includes(str.toLowerCase())) {
@@ -101719,6 +101729,43 @@ const parseSibling = (stack, parent, index, sibling, safeMode) => {
         stack.push(parent);
     }
 };
+/**
+ * Advance a point by the substring of source consumed from it.
+ */
+const pointAfter = (start, consumed) => {
+    const newlineIndex = consumed.lastIndexOf('\n');
+    const newlineCount = newlineIndex === -1 ? 0 : consumed.split('\n').length - 1;
+    return {
+        line: start.line + newlineCount,
+        column: newlineCount === 0 ? start.column + consumed.length : consumed.length - newlineIndex,
+        offset: start.offset + consumed.length,
+    };
+};
+/**
+ * Build a position ending at `consumedLength` into the html node's value, so the
+ * component doesn't claim trailing content the tokenizer swallowed into one node.
+ */
+const positionEndingAtConsumed = (nodePosition, value, consumedLength) => {
+    if (!nodePosition?.start)
+        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.
  */
@@ -101762,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];
@@ -101778,10 +101826,16 @@ const mdxishMdxComponentBlocks = (opts = {}) => tree => {
         const value = node.value;
         if (node.type !== 'html' || typeof value !== 'string')
             return;
-        const parsed = parseTag(value.trim(), parseOpts);
+        const trimmed = value.trim();
+        const parsed = parseTag(trimmed, parseOpts);
         if (!parsed)
             return;
         const { tag, attributes, selfClosing, contentAfterTag = '' } = parsed;
+        // Offset of `trimmed` within the (possibly whitespace-padded) html node value,
+        // so consumed-length math maps back onto the node's real source offsets.
+        const leadingWhitespace = value.length - value.trimStart().length;
+        // Index right after the opening tag's `>` within `trimmed`.
+        const openingTagEnd = trimmed.length - contentAfterTag.length;
         // Skip tags that have dedicated transformers
         if (GENERIC_MDX_COMPONENT_EXCLUDED_TAGS.has(tag))
             return;
@@ -101806,6 +101860,8 @@ const mdxishMdxComponentBlocks = (opts = {}) => tree => {
                 attributes,
                 children: [],
                 startPosition: node.position,
+                // End at the self-closing tag, not at any trailing content.
+                endPosition: positionEndingAtConsumed(node.position, value, leadingWhitespace + openingTagEnd),
             });
             substituteNodeWithMdxNode(parent, index, componentNode);
             // Check and parse if there's relevant content after the current closing tag
@@ -101837,6 +101893,17 @@ const mdxishMdxComponentBlocks = (opts = {}) => tree => {
                 attributes,
                 children: parsedChildren,
                 startPosition: node.position,
+                // 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
@@ -104107,6 +104174,24 @@ function restoreHTMLElements(content, htmlElements) {
         return content;
     return content.replace(HTML_ELEM_PLACEHOLDER, (_m, idx) => htmlElements[parseInt(idx, 10)]);
 }
+const ESM_DECLARATION_START = /^(?:export|import)\b/;
+/**
+ * Whether a line begins a top-level `export`/`import` declaration. Its braces
+ * are valid JS owned by the mdxjsEsm tokenizer (which tolerates blank lines),
+ * so escaping them would corrupt the source and break acorn parsing.
+ */
+function startsEsmDeclaration(chars, lineStart) {
+    return ESM_DECLARATION_START.test(chars.slice(lineStart, lineStart + 7).join(''));
+}
+function isBlankLine(chars, lineStart) {
+    for (let i = lineStart; i < chars.length; i += 1) {
+        if (chars[i] === '\n')
+            return true;
+        if (chars[i] !== ' ' && chars[i] !== '\t')
+            return false;
+    }
+    return true;
+}
 /**
  * Escapes unbalanced and paragraph-spanning braces so MDX doesn't trip on them.
  */
@@ -104122,8 +104207,18 @@ function escapeProblematicBraces(content) {
     // Convert to array of Unicode code points so that emojis and multi-byte characters are correctly tracked
     const chars = Array.from(protectedContent);
     const openStack = [];
+    // Whether the current top-level statement is an `export`/`import` declaration.
+    let insideEsmDeclaration = false;
     for (let i = 0; i < chars.length; i += 1) {
         const ch = chars[i];
+        // At a top-level (brace depth 0) line start, decide whether we're inside an
+        // ESM declaration. The flag persists across the declaration's own lines.
+        if (openStack.length === 0 && (i === 0 || chars[i - 1] === '\n')) {
+            if (startsEsmDeclaration(chars, i))
+                insideEsmDeclaration = true;
+            else if (isBlankLine(chars, i))
+                insideEsmDeclaration = false;
+        }
         // Track string delimiters inside expressions to ignore braces within them
         if (openStack.length > 0) {
             if (strDelim) {
@@ -104181,19 +104276,22 @@ function escapeProblematicBraces(content) {
             if (!isAttrExpr && openStack.length > 0 && openStack[openStack.length - 1].isAttrExpr) {
                 isAttrExpr = true;
             }
-            openStack.push({ pos: i, hasBlankLine: false, isAttrExpr });
+            openStack.push({ pos: i, hasBlankLine: false, isAttrExpr, isEsmDeclaration: insideEsmDeclaration });
             lastNewlinePos = -2;
         }
         else if (ch === '}') {
             if (openStack.length > 0) {
                 const entry = openStack.pop();
+                // The declaration's braces are closed; later top-level braces are not ESM.
+                if (openStack.length === 0)
+                    insideEsmDeclaration = false;
                 // Pure `{/* ... */}` comments are handled downstream by the jsxComment
                 // tokenizer — escaping their braces would prevent it from running.
                 const isPureJsxComment = chars[entry.pos + 1] === '/' &&
                     chars[entry.pos + 2] === '*' &&
                     chars[i - 1] === '/' &&
                     chars[i - 2] === '*';
-                if (entry.hasBlankLine && !isPureJsxComment && !entry.isAttrExpr) {
+                if (entry.hasBlankLine && !isPureJsxComment && !entry.isAttrExpr && !entry.isEsmDeclaration) {
                     toEscape.add(entry.pos);
                     toEscape.add(i);
                 }
@@ -104202,9 +104300,16 @@ function escapeProblematicBraces(content) {
                 toEscape.add(i);
             }
         }
+        else if (ch === ';' && openStack.length === 0) {
+            // A top-level `;` ends the current statement, ESM or otherwise.
+            insideEsmDeclaration = false;
+        }
     }
     // Anything still open is unbalanced.
-    openStack.forEach(entry => toEscape.add(entry.pos));
+    openStack.forEach(entry => {
+        if (!entry.isEsmDeclaration)
+            toEscape.add(entry.pos);
+    });
     // Reconstruct the content with the escaped braces.
     const escapedContent = toEscape.size === 0 ? protectedContent : chars.map((ch, i) => (toEscape.has(i) ? `\\${ch}` : ch)).join('');
     return restoreHTMLElements(escapedContent, htmlElements);
@@ -105703,11 +105808,18 @@ function exportComponentsForRehype(components) {
  * semantics). That breaks any component prop that is genuinely an array. With
  * `passNode: true` we get the original hast node in `props.node` for components
  * and can read the raw properties directly.
+ *
+ * Only arrays win over `rest`, overwriting other shapes would undo correct
+ * React conversions like `style="color:red"` → `{ color: 'red' }`.
  */
 function createElementPreservingHastProps(type, props, ...children) {
     if (props?.node?.properties) {
         const { node, ...rest } = props;
-        const mergedProps = { ...rest, ...node.properties };
+        const mergedProps = { ...rest };
+        Object.entries(node.properties).forEach(([key, value]) => {
+            if (Array.isArray(value))
+                mergedProps[key] = value;
+        });
         // Strip undefined so positional args don't shadow node.properties.children
         const definedChildren = children.filter(c => c !== undefined);
         return external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_default().createElement(type, mergedProps, ...definedChildren);