@markuplint/parser-utils 5.0.0-rc.4 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **parser-utils:** handle raw-text element body in parseCodeFragment per HTML LS §13.2.5.1 ([4a1b0f7](https://github.com/markuplint/markuplint/commit/4a1b0f701c5c0eec91b325c4f3a9f9fb773766e8)), closes [#3825](https://github.com/markuplint/markuplint/issues/3825)
+
+### Features
+
+- **parser-utils:** introduce accumulateParseErrors() for embedded parser delegation ([49e15d6](https://github.com/markuplint/markuplint/commit/49e15d6f528282ca145e77baf03ae8f6561b2b09)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+- **parser-utils:** propagate Tokenized.parseErrors onto MLASTDocument ([37c8430](https://github.com/markuplint/markuplint/commit/37c8430f454d24d691e093fda9e9fb71b658b4d2)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+
 # [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
 
 **Note:** Version bump only for package @markuplint/parser-utils

package/README.md

@@ -16,9 +16,3 @@ $ yarn add @markuplint/parser-utils
 ```
 
 </details>
-
-## Documentation
-
-- [Architecture](ARCHITECTURE.md) ([日本語](ARCHITECTURE.ja.md)) — Package overview, module relationships, and integration points
-- [Parser Class Reference](docs/parser-class.md) ([日本語](docs/parser-class.ja.md)) — Complete reference for the abstract `Parser` class
-- [Maintenance Guide](docs/maintenance.md) ([日本語](docs/maintenance.ja.md)) — Commands, recipes, and troubleshooting

package/lib/const.d.ts

@@ -1,17 +1,8 @@
 export declare const MASK_CHAR = "\uE000";
 /**
- * SVG Element list
- *
  * @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element
  */
 export declare const svgElementList: string[];
 export declare const reTagName: RegExp;
 export declare const reSplitterTag: RegExp;
-/**
- * - U+0009 CHARACTER TABULATION (tab) => `\t`
- * - U+000A LINE FEED (LF) => `\n`
- * - U+000C FORM FEED (FF) => `\f`
- * - U+000D CARRIAGE RETURN (CR) => `\r`
- * - U+0020 SPACE => ` `
- */
 export declare const defaultSpaces: readonly ["\t", "\n", "\f", "\r", " "];

package/lib/const.js

@@ -1,7 +1,5 @@
 export const MASK_CHAR = '\uE000';
 /**
- * SVG Element list
- *
  * @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element
  */
 export const svgElementList = [
@@ -97,11 +95,4 @@ export const svgElementList = [
 // eslint-disable-next-line no-control-regex -- WHATWG HTML spec requires matching NULL character
 export const reTagName = /^[a-z][^\0\t\n\f />]*/i;
 export const reSplitterTag = /<[^>]+>/g;
-/**
- * - U+0009 CHARACTER TABULATION (tab) => `\t`
- * - U+000A LINE FEED (LF) => `\n`
- * - U+000C FORM FEED (FF) => `\f`
- * - U+000D CARRIAGE RETURN (CR) => `\r`
- * - U+0020 SPACE => ` `
- */
 export const defaultSpaces = ['\t', '\n', '\f', '\r', ' '];

package/lib/decision.d.ts

@@ -1,8 +1,2 @@
-/**
- *
- *
- * @param nodeName
- * @returns
- */
 export declare function isSVGElement(nodeName: string): boolean;
 export declare function isPotentialCustomElementName(tagName: string): boolean;

package/lib/decision.js

@@ -1,11 +1,5 @@
 import { isCustomElementName } from '@markuplint/types';
 import { svgElementList } from './const.js';
-/**
- *
- *
- * @param nodeName
- * @returns
- */
 export function isSVGElement(nodeName) {
     return svgElementList.includes(nodeName);
 }

package/lib/ignore-block.d.ts

@@ -1,5 +1,14 @@
 import type { Parser } from './parser.js';
 import type { IgnoreBlock, IgnoreTag } from './types.js';
 import type { MLASTNodeTreeItem } from '@markuplint/ml-ast';
+/**
+ * Masks the source regions that match the given tag patterns so that
+ * template expressions do not interfere with HTML tokenization.
+ *
+ * Invariant: the masked output must keep exactly the same character count
+ * and line breaks as the original source — `restoreNode` and all position
+ * reporting depend on offsets and line numbers in the masked code matching
+ * the original.
+ */
 export declare function ignoreBlock(source: string, tags: readonly IgnoreTag[], maskChar?: string): IgnoreBlock;
 export declare function restoreNode(parser: Parser<any, any>, nodeList: readonly MLASTNodeTreeItem[], ignoreBlock: IgnoreBlock, throwErrorWhenTagHasUnresolved?: boolean): MLASTNodeTreeItem[];

package/lib/ignore-block.js

@@ -1,6 +1,15 @@
 import { MASK_CHAR } from './const.js';
 import { getPosition } from './get-location.js';
 import { ParserError } from './parser-error.js';
+/**
+ * Masks the source regions that match the given tag patterns so that
+ * template expressions do not interfere with HTML tokenization.
+ *
+ * Invariant: the masked output must keep exactly the same character count
+ * and line breaks as the original source — `restoreNode` and all position
+ * reporting depend on offsets and line numbers in the masked code matching
+ * the original.
+ */
 export function ignoreBlock(source, tags, maskChar = MASK_CHAR) {
     let replaced = source;
     const stack = [];
@@ -9,6 +18,11 @@ export function ignoreBlock(source, tags, maskChar = MASK_CHAR) {
             const mask = maskChar.repeat(startTag.length) +
                 taggedCode.replaceAll(/[^\n]/g, maskChar) +
                 maskChar.repeat((endTag ?? '').length);
+            // Wrap in `<!` ... `>` (bogus comment syntax) so the HTML tokenizer
+            // consumes the masked region as a single bogus comment node instead of
+            // interpreting it as text or markup. The slices drop three mask
+            // characters to compensate for the three wrapper characters,
+            // preserving the total length.
             const taggedMask = `<!${mask.slice(2).slice(0, -1)}>`;
             return taggedMask;
         });
@@ -165,7 +179,6 @@ ignoreBlock, throwErrorWhenTagHasUnresolved = true) {
                         attr.value.raw +
                         attr.endQuote.raw);
                 }
-                // Update node raw
                 const length = attr.raw.length;
                 const offset = attr.offset - node.offset;
                 const above = node.raw.slice(0, offset);

package/lib/parser.d.ts

@@ -1,5 +1,5 @@
 import type { Token, ChildToken, QuoteSet, ParseOptions, ParserOptions, Tokenized, ValueType } from './types.js';
-import type { EndTagType, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTBlockBehavior } from '@markuplint/ml-ast';
+import type { EndTagType, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTBlockBehavior, MLASTParseError } from '@markuplint/ml-ast';
 import { AttrState } from './enums.js';
 import { ParserError } from './parser-error.js';
 /**
@@ -8,6 +8,24 @@ import { ParserError } from './parser-error.js';
  * Subclasses must implement `nodeize` to convert language-specific AST nodes
  * into the markuplint AST format.
  *
+ * When adding framework support, choose the lightest extension that fits:
+ *
+ * - **Spec-only package** (`ExtendedSpec`, no parser) when the framework is
+ *   valid HTML plus extra attributes.
+ * - **`HtmlParser` subclass** (from `@markuplint/html-parser`) configuring
+ *   only `ignoreTags` when the syntax is HTML with embedded template
+ *   expressions (EJS, ERB, Liquid, Mustache, Nunjucks, PHP, Smarty) — the
+ *   expressions are masked before HTML parsing and restored as `psblock`
+ *   nodes, so no external parsing library is needed.
+ * - **Direct `Parser` subclass** only when the document structure itself
+ *   diverges from HTML (JSX, Vue SFC, Svelte, Pug, Astro).
+ *
+ * Direct subclasses should delegate tokenization to the framework's
+ * established parser library rather than hand-rolling one, and those
+ * libraries are chosen to span multiple major framework versions (e.g.
+ * `vue-eslint-parser` covers both Vue 2 and Vue 3 template syntax) so the
+ * parsers keep working across version ranges without frequent updates.
+ *
  * @template Node - The language-specific AST node type produced by the tokenizer
  * @template State - An optional parser state type that persists across tokenization
  */
@@ -68,6 +86,11 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * the raw source code. The default implementation prepends offset spaces
      * based on the parse options.
      *
+     * Overrides must call `super.beforeParse()` first: the offset spaces
+     * prepended here are removed again by {@link Parser.afterParse}, and the
+     * two hooks must stay symmetric or position reporting for embedded code
+     * fragments (e.g., a `<template>` block inside a `.vue` file) breaks.
+     *
      * @param rawCode - The raw source code about to be parsed
      * @param options - Parse options that may specify offset positioning
      * @returns The preprocessed source code to be used for tokenization
@@ -88,6 +111,9 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * to perform final transformations on the node list. The default implementation
      * removes any offset spaces that were prepended during preprocessing.
      *
+     * Overrides must call `super.afterParse()` first: it is the counterpart of
+     * {@link Parser.beforeParse} and removes the offset spaces prepended there.
+     *
      * @param nodeList - The fully parsed and flattened node list
      * @param options - The parse options used for this parse invocation
      * @returns The post-processed node list
@@ -259,6 +285,10 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * Also detects spread attributes. If there is leftover text after the attribute,
      * it is returned in the `__rightText` property for further processing.
      *
+     * Subclass contract: overrides must call `super.visitAttr()` first — the base
+     * implementation owns the token decomposition; subclasses only post-process
+     * the returned node (e.g. directive detection).
+     *
      * @param token - The token containing the raw attribute text and position
      * @param options - Controls quoting behavior, value types, and the initial parser state
      * @returns The parsed attribute AST node with an optional `__rightText` for remaining unparsed content
@@ -274,11 +304,27 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
     /**
      * Re-parses a text token to discover embedded HTML/XML tags within it,
      * splitting the content into a sequence of tag and text AST nodes.
-     * Handles self-closing detection, depth tracking, and void element recognition.
+     * Handles self-closing detection, depth tracking, void element recognition,
+     * and the raw-text element body short-circuit (HTML LS §13.2.5.1).
+     *
+     * Raw-text element handling only covers the elements listed in
+     * `rawTextElements` (default `['style', 'script']`). HTML LS *escapable* raw
+     * text elements — `<title>` and `<textarea>` — are intentionally NOT in the
+     * default. They allow character references (`&amp;` etc.) in their body, and
+     * decoding is not implemented in this short-circuit. A subclass that adds
+     * them via the `rawTextElements` option will see character references passed
+     * through verbatim.
+     *
+     * `@markuplint/astro-parser` is the only downstream caller that hands a full
+     * element raw (start tag + body + end tag) to this method, so it is the only
+     * package that exercises the raw-text branch — when changing that branch,
+     * its tests are the most sensitive regression signal.
      *
      * @param token - The child token containing the code fragment to re-parse
      * @param options - Controls whether nameless fragments (JSX `<>`) are recognized
      * @returns An array of tag and text AST nodes discovered in the code fragment
+     * @see https://html.spec.whatwg.org/multipage/syntax.html#cdata-rcdata-restrictions
+     * @see https://github.com/markuplint/markuplint/issues/3825
      */
     parseCodeFragment(token: ChildToken, options?: {
         readonly namelessFragment?: boolean;
@@ -388,4 +434,24 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * @param replacementChildNodes - The replacement nodes to insert at the old child's position
      */
     replaceChild(parentNode: MLASTParentNode, oldChildNode: MLASTChildNode, ...replacementChildNodes: readonly MLASTChildNode[]): void;
+    /**
+     * Subclass hook for parsers that delegate to an embedded parse() call —
+     * e.g., `@markuplint/markdown-parser` parsing inline HTML blocks via a
+     * private `HtmlParser` instance, or `@markuplint/pug-parser` re-running
+     * each raw HTML line through `HtmlInPugParser`. Push the embedded
+     * document's `parseErrors` here so the top-level `parse()` can merge
+     * them into the outer `MLASTDocument.parseErrors`.
+     *
+     * If the embedded document has no `parseErrors`, this is a no-op.
+     *
+     * @param parseErrors - Parse errors collected by the embedded parser. May be `undefined`.
+     */
+    protected accumulateParseErrors(parseErrors: readonly MLASTParseError[] | undefined): void;
+    /**
+     * @internal Read-only snapshot of accumulated embedded parse errors.
+     * Used by {@link Parser.parse} to merge them with the top-level tokenize
+     * result. Subclasses should not call this directly — push via
+     * {@link Parser.accumulateParseErrors} instead.
+     */
+    get embeddedParseErrors(): readonly MLASTParseError[];
 }

package/lib/parser.js

@@ -18,6 +18,24 @@ const timer = new PerformanceTimer();
  * Subclasses must implement `nodeize` to convert language-specific AST nodes
  * into the markuplint AST format.
  *
+ * When adding framework support, choose the lightest extension that fits:
+ *
+ * - **Spec-only package** (`ExtendedSpec`, no parser) when the framework is
+ *   valid HTML plus extra attributes.
+ * - **`HtmlParser` subclass** (from `@markuplint/html-parser`) configuring
+ *   only `ignoreTags` when the syntax is HTML with embedded template
+ *   expressions (EJS, ERB, Liquid, Mustache, Nunjucks, PHP, Smarty) — the
+ *   expressions are masked before HTML parsing and restored as `psblock`
+ *   nodes, so no external parsing library is needed.
+ * - **Direct `Parser` subclass** only when the document structure itself
+ *   diverges from HTML (JSX, Vue SFC, Svelte, Pug, Astro).
+ *
+ * Direct subclasses should delegate tokenization to the framework's
+ * established parser library rather than hand-rolling one, and those
+ * libraries are chosen to span multiple major framework versions (e.g.
+ * `vue-eslint-parser` covers both Vue 2 and Vue 3 template syntax) so the
+ * parsers keep working across version ranges without frequent updates.
+ *
  * @template Node - The language-specific AST node type produced by the tokenizer
  * @template State - An optional parser state type that persists across tokenization
  */
@@ -31,6 +49,25 @@ export class Parser {
     #selfCloseType = 'html';
     #spaceChars = defaultSpaces;
     #rawTextElements = ['style', 'script'];
+    /**
+     * Buffer for parse errors collected from **embedded** parse() calls
+     * (e.g., Markdown's inline HTML blocks, Pug's raw HTML lines — these
+     * invoke a separate HtmlParser instance from inside `nodeize()`).
+     *
+     * Subclasses that delegate to an internal parser should push the
+     * resulting `parseErrors` onto this array via {@link Parser.accumulateParseErrors}.
+     * The base `parse()` merges them with the top-level tokenize result so
+     * the final `MLASTDocument.parseErrors` is complete.
+     *
+     * Reset on every `parse()` invocation.
+     */
+    #embeddedParseErrors = [];
+    /**
+     * Keyed by the original tag name (as authored in source) so a
+     * `tagNameCaseSensitive` parser that preserves casing reuses the same
+     * `RegExp` for every occurrence.
+     */
+    #rawTextCloseTagPatternCache = new Map();
     #authoredElementName;
     #originalRawCode = '';
     #rawCode = '';
@@ -117,6 +154,11 @@ export class Parser {
      * the raw source code. The default implementation prepends offset spaces
      * based on the parse options.
      *
+     * Overrides must call `super.beforeParse()` first: the offset spaces
+     * prepended here are removed again by {@link Parser.afterParse}, and the
+     * two hooks must stay symmetric or position reporting for embedded code
+     * fragments (e.g., a `<template>` block inside a `.vue` file) breaks.
+     *
      * @param rawCode - The raw source code about to be parsed
      * @param options - Parse options that may specify offset positioning
      * @returns The preprocessed source code to be used for tokenization
@@ -157,6 +199,7 @@ export class Parser {
             const tokenized = this.tokenize(options);
             const ast = tokenized.ast;
             const isFragment = tokenized.isFragment;
+            const parseErrors = tokenized.parseErrors;
             this.#defaultDepth = options?.depth ?? this.#defaultDepth;
             timer.push('traverse');
             const traversed = this.traverse(ast, null, this.#defaultDepth);
@@ -205,11 +248,17 @@ export class Parser {
             }
             timer.log();
             domLog(nodeList);
+            // Merge top-level tokenizer parseErrors with any parseErrors
+            // pushed by embedded parser delegations (Markdown / Pug HTML
+            // regions). Snapshot before #reset() clears the buffer.
+            const embeddedErrors = this.embeddedParseErrors;
+            const mergedParseErrors = parseErrors || embeddedErrors.length > 0 ? [...(parseErrors ?? []), ...embeddedErrors] : undefined;
             this.#reset();
             return {
                 raw: rawCode,
                 nodeList,
                 isFragment,
+                ...(mergedParseErrors && mergedParseErrors.length > 0 ? { parseErrors: mergedParseErrors } : {}),
             };
         }
         catch (error) {
@@ -221,6 +270,9 @@ export class Parser {
      * to perform final transformations on the node list. The default implementation
      * removes any offset spaces that were prepended during preprocessing.
      *
+     * Overrides must call `super.afterParse()` first: it is the counterpart of
+     * {@link Parser.beforeParse} and removes the offset spaces prepended there.
+     *
      * @param nodeList - The fully parsed and flattened node list
      * @param options - The parse options used for this parse invocation
      * @returns The post-processed node list
@@ -574,6 +626,10 @@ export class Parser {
      * Also detects spread attributes. If there is leftover text after the attribute,
      * it is returned in the `__rightText` property for further processing.
      *
+     * Subclass contract: overrides must call `super.visitAttr()` first — the base
+     * implementation owns the token decomposition; subclasses only post-process
+     * the returned node (e.g. directive detection).
+     *
      * @param token - The token containing the raw attribute text and position
      * @param options - Controls quoting behavior, value types, and the initial parser state
      * @returns The parsed attribute AST node with an optional `__rightText` for remaining unparsed content
@@ -646,11 +702,27 @@ export class Parser {
     /**
      * Re-parses a text token to discover embedded HTML/XML tags within it,
      * splitting the content into a sequence of tag and text AST nodes.
-     * Handles self-closing detection, depth tracking, and void element recognition.
+     * Handles self-closing detection, depth tracking, void element recognition,
+     * and the raw-text element body short-circuit (HTML LS §13.2.5.1).
+     *
+     * Raw-text element handling only covers the elements listed in
+     * `rawTextElements` (default `['style', 'script']`). HTML LS *escapable* raw
+     * text elements — `<title>` and `<textarea>` — are intentionally NOT in the
+     * default. They allow character references (`&amp;` etc.) in their body, and
+     * decoding is not implemented in this short-circuit. A subclass that adds
+     * them via the `rawTextElements` option will see character references passed
+     * through verbatim.
+     *
+     * `@markuplint/astro-parser` is the only downstream caller that hands a full
+     * element raw (start tag + body + end tag) to this method, so it is the only
+     * package that exercises the raw-text branch — when changing that branch,
+     * its tests are the most sensitive regression signal.
      *
      * @param token - The child token containing the code fragment to re-parse
      * @param options - Controls whether nameless fragments (JSX `<>`) are recognized
      * @returns An array of tag and text AST nodes discovered in the code fragment
+     * @see https://html.spec.whatwg.org/multipage/syntax.html#cdata-rcdata-restrictions
+     * @see https://github.com/markuplint/markuplint/issues/3825
      */
     parseCodeFragment(token, options) {
         const nodes = [];
@@ -732,6 +804,51 @@ export class Parser {
                 }
                 nodes.push(tag);
             }
+            /**
+             * Raw-text element body short-circuit (HTML Living Standard §13.2.5.1
+             * — "Restrictions on the contents of raw text and escapable raw text
+             * elements". The spec section anchor is `cdata-rcdata-restrictions`,
+             * where RCDATA stands for "Raw text + Character REF data" — the broader
+             * class that covers escapable raw text such as `<title>` / `<textarea>`).
+             *
+             * Per spec, the contents of `<script>` / `<style>` (and any caller-supplied
+             * raw-text element) are NOT re-tokenized as HTML — the only thing that
+             * terminates the body is `</tagName` followed by a tab/LF/FF/CR/space/`>`
+             * /`/`. Without this guard, fragments like `<script>const t = s.replace(
+             * /<br\s*\/?>/gi, " ");</script>` would feed the regex to `#parseTag`,
+             * which would try to parse `<br\s*\/?>` as a tag and throw on the
+             * backslash (#3825).
+             *
+             * This is dormant for `jsx-parser` and `mdx-parser` because their upstream
+             * tokenizers reject bare `<` in element body before reaching here, but the
+             * fix keeps `parseCodeFragment` honest for any future caller.
+             *
+             * @see https://html.spec.whatwg.org/multipage/syntax.html#cdata-rcdata-restrictions
+             * @see https://github.com/markuplint/markuplint/issues/3825
+             */
+            if (tag.type === 'starttag' && !isSelfClose && this.#rawTextElements.includes(tag.nodeName.toLowerCase())) {
+                const closeTagPattern = this.#getRawTextCloseTagPattern(tag.nodeName);
+                const match = closeTagPattern.exec(raw);
+                if (match) {
+                    const bodyRaw = raw.slice(0, match.index);
+                    if (bodyRaw) {
+                        const bodyToken = this.createToken(bodyRaw, curOffset, curLine, curCol);
+                        const bodyNode = {
+                            ...bodyToken,
+                            type: 'text',
+                            depth,
+                            nodeName: '#text',
+                            parentNode: null,
+                            parentNodeUuid: null,
+                        };
+                        nodes.push(bodyNode);
+                        ({ offset: curOffset, line: curLine, col: curCol } = this.#getEndLocation(bodyToken));
+                    }
+                    raw = raw.slice(match.index);
+                }
+                // If no matching close tag is found, fall through to the generic loop
+                // so the existing "unclosed tag" handling remains in effect.
+            }
         }
         return nodes;
     }
@@ -1026,13 +1143,24 @@ export class Parser {
         };
     }
     /**
-     * Checks whether a node is a descendant of another node by walking up
-     * the parent chain.
-     *
-     * @param node - The node to test.
-     * @param potentialAncestor - The node that may be an ancestor.
-     * @returns `true` if `node` is a descendant of `potentialAncestor`.
+     * The pattern matches `</tagName` followed by a tab/LF/FF/CR/space/`>`/`/`
+     * (HTML LS §13.2.5.1) ASCII-case-insensitively. Caching avoids recompiling the
+     * `RegExp` for every `<script>` / `<style>` start tag in large documents.
      */
+    #getRawTextCloseTagPattern(tagName) {
+        const cached = this.#rawTextCloseTagPatternCache.get(tagName);
+        if (cached) {
+            return cached;
+        }
+        const escapedName = tagName.replaceAll(/[$()*+.?[\\\]^{|}]/g, '\\$&');
+        // `regexp/strict` cannot statically verify a pattern built from the
+        // dynamic `escapedName` interpolation; the escape above is the contract
+        // that makes this safe for any caller-supplied `rawTextElements` value.
+        // eslint-disable-next-line regexp/strict
+        const pattern = new RegExp(`</${escapedName}(?=[\\t\\n\\f\\r >/])`, 'i');
+        this.#rawTextCloseTagPatternCache.set(tagName, pattern);
+        return pattern;
+    }
     #isDescendantOf(node, potentialAncestor) {
         let current = 'parentNode' in node ? (node.parentNode ?? null) : null;
         while (current) {
@@ -1282,13 +1410,7 @@ export class Parser {
      * @param nodeOrders [Disruptive change]
      */
     #removeDeprecatedNode(nodeOrders) {
-        /**
-         * sorting
-         */
         const sorted = nodeOrders.toSorted(sortNodes);
-        /**
-         * remove duplicated node
-         */
         const stack = {};
         const removeIndexes = [];
         for (const [i, node] of sorted.entries()) {
@@ -1330,34 +1452,54 @@ export class Parser {
         return nodeList;
     }
     #reset() {
-        // Reset state
         this.state = structuredClone(this.#defaultState);
         this.#defaultDepth = 0;
+        this.#embeddedParseErrors = [];
+    }
+    /**
+     * Subclass hook for parsers that delegate to an embedded parse() call —
+     * e.g., `@markuplint/markdown-parser` parsing inline HTML blocks via a
+     * private `HtmlParser` instance, or `@markuplint/pug-parser` re-running
+     * each raw HTML line through `HtmlInPugParser`. Push the embedded
+     * document's `parseErrors` here so the top-level `parse()` can merge
+     * them into the outer `MLASTDocument.parseErrors`.
+     *
+     * If the embedded document has no `parseErrors`, this is a no-op.
+     *
+     * @param parseErrors - Parse errors collected by the embedded parser. May be `undefined`.
+     */
+    accumulateParseErrors(parseErrors) {
+        if (parseErrors && parseErrors.length > 0) {
+            this.#embeddedParseErrors.push(...parseErrors);
+        }
+    }
+    /**
+     * @internal Read-only snapshot of accumulated embedded parse errors.
+     * Used by {@link Parser.parse} to merge them with the top-level tokenize
+     * result. Subclasses should not call this directly — push via
+     * {@link Parser.accumulateParseErrors} instead.
+     */
+    get embeddedParseErrors() {
+        return this.#embeddedParseErrors;
     }
     #setRawCode(rawCode, originalRawCode) {
         this.#rawCode = rawCode;
         this.#originalRawCode = originalRawCode ?? this.#originalRawCode;
     }
     /**
-     * Trims text nodes whose source range overlaps with the next node in
-     * the flat list. This prevents text content from bleeding into adjacent
-     * elements that occupy a later (or overlapping) source range.
+     * Prevents text content from bleeding into adjacent elements that
+     * occupy a later (or overlapping) source range.
      *
      * Skips trimming when the text node is a descendant of the next node
      * in the tree hierarchy, because synthetic parsers (e.g., Markdown)
      * can produce child elements that share the same source range as their
      * parent and therefore appear before the parent in offset-sorted order.
-     *
-     * @param nodeList - The flat, offset-sorted node list to process.
-     * @returns A new node list with overlapping text nodes trimmed.
      */
     #trimText(nodeList) {
         const newNodeList = [];
         let prevNode = null;
         for (const node of nodeList) {
-            if (prevNode?.type === 'text' &&
-                // Empty node
-                node.raw.length > 0) {
+            if (prevNode?.type === 'text' && node.raw.length > 0) {
                 const prevNodeEndOffset = prevNode.offset + prevNode.raw.length;
                 const nodeStartOffset = node.offset;
                 if (prevNodeEndOffset > nodeStartOffset && !this.#isDescendantOf(prevNode, node)) {

package/lib/sort-nodes.d.ts

@@ -1,10 +1,2 @@
 import type { MLASTNodeTreeItem } from '@markuplint/ml-ast';
-/**
- * Comparator function for sorting AST nodes by their source position.
- * Sorts primarily by offset, then by end offset for nodes at the same position.
- *
- * @param a - The first node to compare
- * @param b - The second node to compare
- * @returns A negative, zero, or positive number for sort ordering
- */
 export declare function sortNodes(a: MLASTNodeTreeItem, b: MLASTNodeTreeItem): number;

package/lib/sort-nodes.js

@@ -1,11 +1,3 @@
-/**
- * Comparator function for sorting AST nodes by their source position.
- * Sorts primarily by offset, then by end offset for nodes at the same position.
- *
- * @param a - The first node to compare
- * @param b - The second node to compare
- * @returns A negative, zero, or positive number for sort ordering
- */
 export function sortNodes(a, b) {
     if (a.offset === b.offset) {
         return sort(a.offset + a.raw.length, b.offset + b.raw.length);

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { EndTagType, MLASTParentNode, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
+import type { EndTagType, MLASTParentNode, MLASTParseError, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
 /**
  * Configuration options for initializing a Parser instance,
  * controlling how the parser handles tags, attributes, and whitespace.
@@ -34,6 +34,13 @@ export type Tokenized<N extends {} = {}, State extends unknown = null> = {
     readonly ast: N[];
     readonly isFragment: boolean;
     readonly state?: State;
+    /**
+     * Non-fatal parser conformance errors collected during tokenisation.
+     * Optional — parsers that have no equivalent surface (e.g., raw regex
+     * tokenizers) simply omit it. Propagated unchanged onto
+     * `MLASTDocument.parseErrors` by {@link Parser.parse}.
+     */
+    readonly parseErrors?: readonly MLASTParseError[];
 };
 /**
  * A minimal source token representing a raw string fragment

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/parser-utils",
-	"version": "5.0.0-rc.4",
+	"version": "5.0.0-rc.5",
 	"description": "Utility module for markuplint parser plugin",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"type": "module",
 	"exports": {
@@ -35,16 +35,16 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.0.0-rc.4",
-		"@markuplint/ml-spec": "5.0.0-rc.4",
-		"@markuplint/shared": "5.0.0-rc.4",
-		"@markuplint/types": "5.0.0-rc.4",
+		"@markuplint/ml-ast": "5.0.0-rc.5",
+		"@markuplint/ml-spec": "5.0.0-rc.5",
+		"@markuplint/shared": "5.0.0-rc.5",
+		"@markuplint/types": "5.0.0-rc.5",
 		"debug": "4.4.3",
 		"espree": "11.2.0",
 		"type-fest": "5.6.0"
 	},
 	"devDependencies": {
-		"@typescript-eslint/typescript-estree": "8.58.2"
+		"@typescript-eslint/typescript-estree": "8.59.0"
 	},
-	"gitHead": "97a6339bbae23f556de5d307b3ce2ef7cfd9402d"
+	"gitHead": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
 }