@markuplint/ml-ast 5.0.0-rc.2 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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)
+
+### Features
+
+- **ml-ast:** add documentMode to ParserOptions ([530493e](https://github.com/markuplint/markuplint/commit/530493e7f99eb27dd2f420666474e233db450c26)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+- **ml-ast:** add MLASTParseError + MLASTParseErrorCode types and parseErrors field ([be34fbd](https://github.com/markuplint/markuplint/commit/be34fbd36ba7fb36b0a07cd6e865c8d81d8752ae)), 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/ml-ast
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/ml-ast
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 **Note:** Version bump only for package @markuplint/ml-ast

package/README.md

@@ -16,9 +16,3 @@ $ yarn add @markuplint/ml-ast
 ```
 
 </details>
-
-## Documentation
-
-- [Architecture](ARCHITECTURE.md) -- Package overview, type hierarchy diagrams, and integration points
-- [Node Reference](docs/node-reference.md) -- Detailed documentation of each AST node type
-- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/lib/index.d.ts

@@ -1 +1,17 @@
+/**
+ * The language-independent AST contract of markuplint: every parser package
+ * must produce these types and `@markuplint/ml-core` consumes them, so the
+ * core and rules can operate on a unified AST regardless of the source
+ * language.
+ *
+ * This package intentionally contains zero runtime code and zero
+ * dependencies — keep it type-only so parsers and downstream consumers can
+ * share the contract without runtime coupling.
+ *
+ * Backward-compatibility convention: when adding a field to an existing node
+ * interface, prefer an optional field so existing parser implementations do
+ * not break.
+ *
+ * @module
+ */
 export * from './types.js';

package/lib/index.js

@@ -1 +1,17 @@
+/**
+ * The language-independent AST contract of markuplint: every parser package
+ * must produce these types and `@markuplint/ml-core` consumes them, so the
+ * core and rules can operate on a unified AST regardless of the source
+ * language.
+ *
+ * This package intentionally contains zero runtime code and zero
+ * dependencies — keep it type-only so parsers and downstream consumers can
+ * share the contract without runtime coupling.
+ *
+ * Backward-compatibility convention: when adding a field to an existing node
+ * interface, prefer an optional field so existing parser implementations do
+ * not break.
+ *
+ * @module
+ */
 export * from './types.js';

package/lib/types.d.ts

@@ -11,6 +11,10 @@
  * - `'invalid'`   – A node that could not be parsed correctly
  * - `'attr'`      – A regular HTML attribute
  * - `'spread'`    – A spread attribute (e.g. `{...props}` in JSX)
+ *
+ * Adding a value here requires a corresponding `case` in `ml-core`'s
+ * `createNode()` (`packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`);
+ * an unhandled value throws `TypeError: Invalid AST node types` at runtime.
  */
 export type MLASTNodeType = 'doctype' | 'starttag' | 'endtag' | 'comment' | 'text' | 'omittedtag' | 'psblock' | 'invalid' | 'attr' | 'spread';
 /**
@@ -54,7 +58,14 @@ export type MLASTAttr = MLASTHTMLAttr | MLASTSpreadAttr;
  * in `@markuplint/parser-utils`.
  */
 export interface MLASTToken {
-    /** Unique identifier for this token instance */
+    /**
+     * Unique identifier for this token instance.
+     *
+     * Cross-references between nodes (`parentNodeUuid`, `pairNodeUuid`) use
+     * UUID strings rather than object references so the AST stays free of
+     * circular references and can be serialized as JSON; consumers resolve a
+     * UUID against `MLASTDocument.nodeList`.
+     */
     readonly uuid: string;
     /** The original raw source text of this token */
     readonly raw: string;
@@ -109,7 +120,7 @@ export interface MLASTElement extends MLASTAbstractNode {
     readonly namespace: NamespaceURI;
     /** Whether the element is native HTML, a Web Component, or an authored component */
     readonly elementType: ElementType;
-    /** Whether this element acts as a fragment (no actual DOM node) */
+    /** Whether this element acts as a fragment (no actual DOM node, e.g. a JSX fragment `<>` or a Vue `<template>` wrapper) */
     readonly isFragment: boolean;
     /** Attributes on this element */
     readonly attributes: readonly MLASTAttr[];
@@ -130,12 +141,17 @@ export interface MLASTElement extends MLASTAbstractNode {
     readonly tagOpenChar: string;
     /** The characters that close this tag (usually `">"`) */
     readonly tagCloseChar: string;
-    /** Whether this element is a ghost node (omitted tag inferred by the parser) */
+    /** Whether this element is a ghost node (omitted tag inferred by the parser, e.g. an implicit `<tbody>`); ghost nodes have an empty `raw` */
     readonly isGhost: boolean;
 }
 /**
  * A closing element tag (e.g. `</div>`).
  * Always paired with an {@link MLASTElement} via `pairNodeUuid`.
+ *
+ * Close tags are not part of DOM tree traversal in `ml-core`: `createNode()`
+ * skips `'endtag'` entries in the node list, and the paired `MLElement`
+ * instead resolves `pairNodeUuid` to create its `MLElementCloseTag`, which
+ * exists only as a satellite of that element.
  */
 export interface MLASTElementCloseTag extends MLASTAbstractNode {
     readonly type: 'endtag';
@@ -157,6 +173,11 @@ export interface MLASTElementCloseTag extends MLASTAbstractNode {
  * A preprocessor-specific block node, representing control-flow constructs
  * from template engines and frameworks (e.g. `{#if}`, `{#each}` in Svelte,
  * `v-if` blocks in Vue, `<% if %>` in EJS/ERB).
+ *
+ * In `ml-core` this maps to `MLBlock` — a markuplint-specific extension with
+ * the custom `nodeType` `101` (no DOM Standard equivalent) — which acts as a
+ * transparent container: its children are treated as belonging to the parent
+ * node for tree traversal purposes.
  */
 export interface MLASTPreprocessorSpecificBlock extends MLASTAbstractNode {
     readonly type: 'psblock';
@@ -168,7 +189,7 @@ export interface MLASTPreprocessorSpecificBlock extends MLASTAbstractNode {
     readonly isFragment: boolean;
     /** Direct child nodes within this block */
     readonly childNodes: readonly MLASTChildNode[];
-    /** Block behavior associated with this block, if any */
+    /** Block behavior associated with this block, or `null` when the block has no control-flow semantic (e.g. a pure expression output like `<%= expr %>` in EJS) */
     readonly blockBehavior: MLASTBlockBehavior | null;
     /** Whether this block is bogus (unparsable or malformed) */
     readonly isBogus: boolean;
@@ -177,6 +198,10 @@ export interface MLASTPreprocessorSpecificBlock extends MLASTAbstractNode {
  * Describes the behavior of a preprocessor block or element,
  * capturing both the kind of control-flow construct and the
  * source expression that drives it.
+ *
+ * `ml-core` uses the `type` to enumerate conditional branches
+ * (`conditionalChildNodes()`) so content-model rules such as
+ * `permitted-contents` can analyze each branch separately.
  */
 export interface MLASTBlockBehavior {
     /** The kind of block behavior (e.g. `'if'`, `'each'`, `'await'`) */
@@ -196,7 +221,12 @@ export interface MLASTComment extends MLASTAbstractNode {
     readonly nodeName: '#comment';
     /** Nesting depth in the document tree */
     readonly depth: number;
-    /** Whether the comment is bogus (e.g. a malformed comment) */
+    /**
+     * Whether the comment is bogus (malformed per the HTML parsing spec,
+     * e.g. `<!...>` or a processing instruction such as `<?xml ... ?>`).
+     * The parser still captures these as comment nodes but flags them so
+     * lint rules can report them.
+     */
     readonly isBogus: boolean;
 }
 /**
@@ -211,6 +241,12 @@ export interface MLASTText extends MLASTAbstractNode {
 /**
  * A node representing markup that could not be parsed correctly.
  * Always marked as bogus.
+ *
+ * This is a recovery node: the parser captures unparsable content instead of
+ * failing the whole parse. It is never preserved as-is in the DOM —
+ * `ml-core` converts it to an `MLElement` named `x-invalid` (when `kind` is
+ * `'starttag'`) or to an `MLText` (otherwise), so lint rules can still
+ * operate on the content based on the parser's best guess.
  */
 export interface MLASTInvalid extends MLASTAbstractNode {
     readonly type: 'invalid';
@@ -225,6 +261,12 @@ export interface MLASTInvalid extends MLASTAbstractNode {
 /**
  * A regular HTML attribute node, decomposed into its constituent tokens
  * (name, equal sign, quotes, value, and surrounding whitespace).
+ *
+ * The decomposition exists so lint rules can validate whitespace around the
+ * equal sign, quoting style, and attribute naming conventions with precise
+ * source locations. For boolean attributes without a value (e.g.
+ * `disabled`), the `equal`, `startQuote`, `value`, and `endQuote` tokens
+ * still exist but have empty `raw` strings.
  */
 export interface MLASTHTMLAttr extends MLASTToken {
     readonly type: 'attr';
@@ -250,7 +292,7 @@ export interface MLASTHTMLAttr extends MLASTToken {
     readonly isDynamicValue?: true;
     /** Whether the attribute is a framework directive (e.g. `v-if`, `@click`) */
     readonly isDirective?: true;
-    /** The resolved attribute name when the actual name is a framework-specific directive */
+    /** The resolved attribute name when the actual name is a framework-specific directive (e.g. Vue's `:class` resolves to `class`, `@click` to `onclick`) */
     readonly potentialName?: string;
     /** The resolved attribute value when the actual value is dynamic */
     readonly potentialValue?: string;
@@ -258,16 +300,66 @@ export interface MLASTHTMLAttr extends MLASTToken {
     readonly valueType?: 'string' | 'number' | 'boolean' | 'code';
     /** A candidate attribute name for auto-correction */
     readonly candidate?: string;
-    /** Whether this attribute is allowed to appear multiple times on the same element */
+    /** Whether this attribute is allowed to appear multiple times on the same element (e.g. `class` in template engines that merge values) */
     readonly isDuplicatable: boolean;
 }
 /**
  * A spread attribute node (e.g. `{...props}` in JSX).
+ *
+ * Minimal by design: a spread cannot be statically decomposed into
+ * name/value tokens, so only the positional token information is kept.
  */
 export interface MLASTSpreadAttr extends MLASTToken {
     readonly type: 'spread';
     readonly nodeName: '#spread';
 }
+/**
+ * Stable identifier for a non-fatal parser conformance error. The full set
+ * mirrors parse5's `ERR` enum (HTML LS tokenizer / tree-construction parse
+ * errors) — each value is a kebab-case string that appears verbatim in the
+ * `code` field of `MLASTParseError` and as the key in
+ * `severity.parseError`'s `Record` form.
+ *
+ * Source of truth: `parse5/dist/common/error-codes.d.ts`. When parse5
+ * adds a new code, append it here and update the migration guide.
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parse-errors
+ */
+export type MLASTParseErrorCode = 'control-character-in-input-stream' | 'noncharacter-in-input-stream' | 'surrogate-in-input-stream' | 'non-void-html-element-start-tag-with-trailing-solidus' | 'end-tag-with-attributes' | 'end-tag-with-trailing-solidus' | 'unexpected-solidus-in-tag' | 'unexpected-null-character' | 'unexpected-question-mark-instead-of-tag-name' | 'invalid-first-character-of-tag-name' | 'unexpected-equals-sign-before-attribute-name' | 'missing-end-tag-name' | 'unexpected-character-in-attribute-name' | 'unknown-named-character-reference' | 'missing-semicolon-after-character-reference' | 'absence-of-digits-in-numeric-character-reference' | 'null-character-reference' | 'surrogate-character-reference' | 'character-reference-outside-unicode-range' | 'control-character-reference' | 'noncharacter-character-reference' | 'unexpected-character-in-unquoted-attribute-value' | 'missing-attribute-value' | 'missing-whitespace-between-attributes' | 'duplicate-attribute' | 'unexpected-character-after-doctype-system-identifier' | 'missing-whitespace-after-doctype-public-keyword' | 'missing-whitespace-between-doctype-public-and-system-identifiers' | 'missing-whitespace-after-doctype-system-keyword' | 'missing-quote-before-doctype-public-identifier' | 'missing-quote-before-doctype-system-identifier' | 'missing-doctype-public-identifier' | 'missing-doctype-system-identifier' | 'abrupt-doctype-public-identifier' | 'abrupt-doctype-system-identifier' | 'missing-whitespace-before-doctype-name' | 'missing-doctype-name' | 'invalid-character-sequence-after-doctype-name' | 'non-conforming-doctype' | 'missing-doctype' | 'misplaced-doctype' | 'eof-in-doctype' | 'incorrectly-opened-comment' | 'incorrectly-closed-comment' | 'nested-comment' | 'abrupt-closing-of-empty-comment' | 'eof-in-comment' | 'cdata-in-html-content' | 'eof-in-cdata' | 'eof-in-script-html-comment-like-text' | 'eof-before-tag-name' | 'eof-in-tag' | 'eof-in-element-that-can-contain-only-text' | 'end-tag-without-matching-open-element' | 'closing-of-element-with-open-child-elements' | 'disallowed-content-in-noscript-in-head' | 'open-elements-left-after-eof' | 'abandoned-head-element-child' | 'misplaced-start-tag-for-head-element' | 'nested-noscript-in-head';
+/**
+ * Non-fatal parser-level conformance error emitted by the underlying parser
+ * during tokenisation (e.g., parse5's `onParseError` events). Unlike
+ * `unknownParseError` these do not abort the parse — the document is still
+ * usable — but they correspond to HTML LS tokenizer / tree-construction
+ * conformance errors that the `parse-error` rule surfaces as lint
+ * violations.
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parse-errors
+ */
+export interface MLASTParseError {
+    /**
+     * Stable kebab-case identifier from the underlying parser. The current
+     * full enumeration mirrors parse5's `ERR` enum and is captured by
+     * {@link MLASTParseErrorCode}; framework parsers that surface a code
+     * outside that set should still use a kebab-case identifier so user
+     * configuration (`severity.parseError`) can target it.
+     */
+    readonly code: MLASTParseErrorCode;
+    /** Zero-based offset into the source where the error starts. */
+    readonly startOffset: number;
+    /** 1-based line where the error starts. */
+    readonly startLine: number;
+    /** 1-based column where the error starts. */
+    readonly startCol: number;
+    /** Zero-based offset into the source where the error ends. */
+    readonly endOffset: number;
+    /** 1-based line where the error ends. */
+    readonly endLine: number;
+    /** 1-based column where the error ends. */
+    readonly endCol: number;
+    /** The slice of the source between `startOffset` and `endOffset`. */
+    readonly raw: string;
+}
 /**
  * The root document node returned by a parser.
  * Contains the full node list and metadata about the parse result.
@@ -275,12 +367,34 @@ export interface MLASTSpreadAttr extends MLASTToken {
 export interface MLASTDocument {
     /** The full original source code */
     readonly raw: string;
-    /** Flat list of top-level AST nodes in document order */
+    /**
+     * Depth-first flattened list of all AST nodes in document order (the
+     * order they appear in the source) — nodes also appear in their parent's
+     * `childNodes`. UUID cross-references (`parentNodeUuid`, `pairNodeUuid`)
+     * are resolved against this list, so every node referenced by UUID must
+     * be present in it.
+     */
     readonly nodeList: readonly MLASTNodeTreeItem[];
     /** Whether the document is a fragment (no root element required) */
     readonly isFragment: boolean;
     /** A description of any unknown parse error that occurred, if any */
     readonly unknownParseError?: string;
+    /**
+     * Non-fatal parser-level conformance errors collected during tokenisation.
+     * Populated by parsers that support it (e.g., `@markuplint/html-parser`
+     * via parse5's `onParseError`); omitted otherwise. Consumed by
+     * `@markuplint/ml-core`'s verify pipeline, which surfaces each entry as a
+     * `ruleId: 'parse-error'` violation (sharing the channel with fatal
+     * `ParserError`s; controlled by `severity.parseError`).
+     *
+     * **Order contract**: entries must appear in the order the parser emitted
+     * them, and `ml-core` pushes them onto the violations list **before** any
+     * rule iteration runs — so they always precede rule-level violations in
+     * test fixtures and reporter output. Custom parsers populating this field
+     * must preserve emit order; downstream consumers (including 80+ rule spec
+     * files) rely on it.
+     */
+    readonly parseErrors?: readonly MLASTParseError[];
 }
 /**
  * Interface for a markuplint-compatible parser.
@@ -333,6 +447,29 @@ export type ParserOptions = {
     readonly ignoreFrontMatter?: boolean;
     /** How to distinguish authored (component) element names from native HTML elements */
     readonly authoredElementName?: ParserAuthoredElementNameDistinguishing;
+    /**
+     * Override how the underlying HTML parser decides between full-document
+     * and fragment parsing.
+     *
+     * - `'auto'` (default) — inspect the source: input starting with
+     *   `<!doctype html>` or `<html>` is treated as a full document;
+     *   anything else as a fragment. Backwards-compatible behaviour.
+     * - `'document'` — force full-document parsing. Use for sources that
+     *   are complete HTML pages without an explicit doctype, so that
+     *   document-level parse5 errors (`missing-doctype`, `misplaced-doctype`,
+     *   etc.) surface via the `parse-error` channel.
+     * - `'fragment'` — force fragment parsing. Use for SSR / template
+     *   partials whose source intentionally starts with `<head>`, `<meta>`,
+     *   `<title>`, … as legitimate inserted chunks (parse5 should not emit
+     *   `missing-doctype` for those).
+     *
+     * Template-engine parsers that internally re-invoke the HTML parser for
+     * embedded HTML chunks (Markdown HTML blocks, Pug raw HTML output, …)
+     * pass `'fragment'` to that internal call by default; users can still
+     * override that via `parserOptions` when their template legitimately
+     * carries a full document.
+     */
+    readonly documentMode?: 'auto' | 'document' | 'fragment';
 };
 /**
  * Configuration for distinguishing authored (component) elements from native HTML elements.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-ast",
-	"version": "5.0.0-rc.2",
+	"version": "5.0.0-rc.5",
 	"description": "The markuplint AST types.",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"type": "module",
 	"exports": {
@@ -30,5 +30,5 @@
 		"dev": "tsc --watch --project tsconfig.build.json",
 		"clean": "tsc --build --clean  tsconfig.build.json"
 	},
-	"gitHead": "e43763858d9234c417053becc73dbd088c1e7ea6"
+	"gitHead": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
 }

package/ARCHITECTURE.ja.md

@@ -1,309 +0,0 @@
-# @markuplint/ml-ast
-
-## 概要
-
-`@markuplint/ml-ast` は、markuplint の言語非依存な抽象構文木（AST）中間表現を定義する純粋な型定義パッケージです。**ランタイムコードはゼロ**、**依存関係もゼロ**で、すべてのパーサーが生成し、すべての下流パッケージが消費する TypeScript 型定義のみを含みます。
-
-すべてのマークアップ言語パーサー（HTML、JSX、Vue、Svelte、Astro、Pug など）はソースコードをここで定義された型にパースし、markuplint のコアとルールがソース言語に関係なく統一された AST 上で動作できるようにします。
-
-## ディレクトリ構成
-
-```
-src/
-├── index.ts   — types.ts からすべての型を再エクスポート
-└── types.ts   — すべての型定義（約470行）
-```
-
-## アーキテクチャ図
-
-```mermaid
-flowchart TD
-    subgraph parsers ["パーサー（上流）"]
-        html["@markuplint/html-parser"]
-        jsx["@markuplint/jsx-parser"]
-        vue["@markuplint/vue-parser"]
-        svelte["@markuplint/svelte-parser"]
-        astro["@markuplint/astro-parser"]
-        pug["@markuplint/pug-parser"]
-        parserUtils["@markuplint/parser-utils"]
-    end
-
-    subgraph ast ["@markuplint/ml-ast"]
-        types["型定義\n(MLASTDocument, MLASTElement,\nMLASTComment, MLASTText, ...)"]
-    end
-
-    subgraph downstream ["下流"]
-        mlCore["@markuplint/ml-core\n(AST → DOM マッピング)"]
-        mlConfig["@markuplint/ml-config"]
-        mlSpec["@markuplint/ml-spec"]
-        rules["@markuplint/rules"]
-        fileResolver["@markuplint/file-resolver"]
-    end
-
-    parsers -->|"生成"| types
-    types -->|"消費"| downstream
-    mlCore -->|"DOM ノードを作成"| types
-```
-
-## 型継承図
-
-```mermaid
-classDiagram
-    class MLASTToken {
-        <<interface>>
-        +uuid: string
-        +raw: string
-        +offset: number
-        +line: number
-        +col: number
-    }
-
-    class MLASTAbstractNode {
-        <<interface>>
-        +type: MLASTNodeType
-        +nodeName: string
-        +parentNodeUuid: string | null
-    }
-
-    class MLASTDoctype {
-        <<interface>>
-        +type: "doctype"
-        +depth: number
-        +name: string
-        +publicId: string
-        +systemId: string
-    }
-
-    class MLASTElement {
-        <<interface>>
-        +type: "starttag"
-        +depth: number
-        +namespace: string
-        +elementType: ElementType
-        +attributes: MLASTAttr[]
-        +childNodes: MLASTChildNode[]
-        +blockBehavior: MLASTBlockBehavior | null
-        +pairNodeUuid: string | null
-        +isGhost: boolean
-        +isFragment: boolean
-    }
-
-    class MLASTElementCloseTag {
-        <<interface>>
-        +type: "endtag"
-        +depth: number
-        +pairNodeUuid: string | null
-    }
-
-    class MLASTComment {
-        <<interface>>
-        +type: "comment"
-        +depth: number
-        +isBogus: boolean
-    }
-
-    class MLASTText {
-        <<interface>>
-        +type: "text"
-        +depth: number
-    }
-
-    class MLASTPreprocessorSpecificBlock {
-        <<interface>>
-        +type: "psblock"
-        +blockBehavior: MLASTBlockBehavior | null
-        +depth: number
-        +childNodes: MLASTChildNode[]
-        +isBogus: boolean
-    }
-
-    class MLASTInvalid {
-        <<interface>>
-        +type: "invalid"
-        +depth: number
-        +kind: MLASTChildNode type
-        +isBogus: true
-    }
-
-    class MLASTHTMLAttr {
-        <<interface>>
-        +type: "attr"
-        +name: MLASTToken
-        +value: MLASTToken
-        +isDynamicValue: boolean
-        +isDirective: boolean
-    }
-
-    class MLASTSpreadAttr {
-        <<interface>>
-        +type: "spread"
-    }
-
-    MLASTToken <|-- MLASTAbstractNode
-    MLASTAbstractNode <|-- MLASTDoctype
-    MLASTAbstractNode <|-- MLASTElement
-    MLASTAbstractNode <|-- MLASTElementCloseTag
-    MLASTAbstractNode <|-- MLASTComment
-    MLASTAbstractNode <|-- MLASTText
-    MLASTAbstractNode <|-- MLASTPreprocessorSpecificBlock
-    MLASTAbstractNode <|-- MLASTInvalid
-    MLASTToken <|-- MLASTHTMLAttr
-    MLASTToken <|-- MLASTSpreadAttr
-```
-
-## 共用体型
-
-```mermaid
-flowchart TD
-    subgraph MLASTNode ["MLASTNode（全ノード型）"]
-        subgraph MLASTNodeTreeItem ["MLASTNodeTreeItem"]
-            MLASTDoctype["MLASTDoctype"]
-            subgraph MLASTChildNode ["MLASTChildNode"]
-                subgraph MLASTTag ["MLASTTag"]
-                    MLASTElement["MLASTElement"]
-                    MLASTElementCloseTag["MLASTElementCloseTag"]
-                end
-                MLASTText["MLASTText"]
-                MLASTComment["MLASTComment"]
-                MLASTPreprocessorSpecificBlock["MLASTPreprocessorSpecificBlock"]
-                MLASTInvalid["MLASTInvalid"]
-            end
-        end
-        subgraph MLASTAttr ["MLASTAttr"]
-            MLASTHTMLAttr["MLASTHTMLAttr"]
-            MLASTSpreadAttr["MLASTSpreadAttr"]
-        end
-    end
-
-    style MLASTElement fill:#e1f5fe
-    style MLASTPreprocessorSpecificBlock fill:#e1f5fe
-
-    note1["MLASTParentNode = MLASTElement | MLASTPreprocessorSpecificBlock\n(青でハイライト)"]
-```
-
-## ノード型一覧
-
-| 型                               | `type` 値    | 代表例                 | 説明                                     |
-| -------------------------------- | ------------ | ---------------------- | ---------------------------------------- |
-| `MLASTDoctype`                   | `'doctype'`  | `<!DOCTYPE html>`      | DOCTYPE 宣言                             |
-| `MLASTElement`                   | `'starttag'` | `<div class="foo">`    | 開始タグ。属性・子ノード・名前空間を保持 |
-| `MLASTElementCloseTag`           | `'endtag'`   | `</div>`               | 閉じタグ。開始タグとペア                 |
-| `MLASTComment`                   | `'comment'`  | `<!-- ... -->`         | HTML コメント。bogus フラグ付き          |
-| `MLASTText`                      | `'text'`     | テキスト内容           | 要素間の文字データ                       |
-| `MLASTPreprocessorSpecificBlock` | `'psblock'`  | `{#if}`, `<% %>`       | テンプレートエンジン構文                 |
-| `MLASTInvalid`                   | `'invalid'`  | パース不能マークアップ | 不正ノード。意図された種別のヒント付き   |
-| `MLASTHTMLAttr`                  | `'attr'`     | `class="foo"`          | 完全分解された HTML 属性                 |
-| `MLASTSpreadAttr`                | `'spread'`   | `{...props}`           | JSX スプレッド属性                       |
-
-各型の詳細は[ノードリファレンス](docs/node-reference.ja.md)を参照してください。
-
-## AST から MLDOM へのマッピング
-
-各 AST ノードは、最終的に `@markuplint/ml-core` によって **MLDOM** ノードに変換されます。MLDOM は [DOM Standard](https://dom.spec.whatwg.org/) に準拠しており、各クラスは対応する DOM インターフェース（`Node`、`Element`、`DocumentType`、`Comment`、`Text` など）を実装しているため、リントルールは標準 DOM API を使って検査できます。
-
-| AST 型（`ml-ast`）                   | MLDOM クラス（`ml-core`）  | DOM インターフェース     | `nodeType` |
-| ------------------------------------ | -------------------------- | ------------------------ | ---------- |
-| `MLASTDoctype`                       | `MLDocumentType`           | `DocumentType`           | `10`       |
-| `MLASTElement`                       | `MLElement`                | `Element`, `HTMLElement` | `1`        |
-| `MLASTComment`                       | `MLComment`                | `Comment`                | `8`        |
-| `MLASTText`                          | `MLText`                   | `Text`                   | `3`        |
-| `MLASTPreprocessorSpecificBlock`     | `MLBlock`                  | _（markuplint 独自）_    | `101`      |
-| `MLASTInvalid`（`kind: 'starttag'`） | `MLElement`（`x-invalid`） | `Element`, `HTMLElement` | `1`        |
-| `MLASTInvalid`（その他）             | `MLText`                   | `Text`                   | `3`        |
-| `MLASTHTMLAttr` / `MLASTSpreadAttr`  | `MLAttr`                   | `Attr`                   | `2`        |
-
-**特殊なノード：**
-
-- **`MLBlock`**（`nodeType: 101`）は DOM Standard に相当するものがない markuplint 独自の拡張です。透過的なコンテナとして機能し、子ノードはツリー走査時に親に属するものとして扱われます。
-- **`MLElementCloseTag`** は `createNode()` で生成されません。代わりに `MLElement` が `pairNodeUuid` を解決して閉じタグの AST ノードを検索し、`MLElementCloseTag` を生成します。ペアとなる要素の付属物としてのみ存在し、DOM ツリー走査の対象ではありません。
-- **`MLASTInvalid`** はリカバリノードです。MLDOM にそのまま保持されることはなく、`kind` フィールドに応じて `MLElement`（タグ名 `x-invalid`）または `MLText` に変換されます。
-
-詳細は[ノードリファレンス -- AST から MLDOM へのマッピング](docs/node-reference.ja.md#ast-から-mldom-へのマッピング)を参照してください。
-
-## 属性分解モデル
-
-`MLASTHTMLAttr` は各属性を完全な位置情報を持つ個別のトークンに分解します：
-
-```
- ·class="container"
- ↑     ↑↑         ↑
- │     ││         └─ endQuote
- │     │└─ value
- │     └─ startQuote
- │        equal
- └─ spacesBeforeName
-    name
-```
-
-これにより、リントルールは `=` 前後のホワイトスペース、引用符スタイル、属性命名規則を正確なソース位置で検証できます。完全なフィールドドキュメントは[ノードリファレンス](docs/node-reference.ja.md#mlasthtmlattr)を参照してください。
-
-## パーサーインターフェース
-
-| 型               | 説明                                                     |
-| ---------------- | -------------------------------------------------------- |
-| `MLParser`       | markuplint 互換パーサーのインターフェース                |
-| `MLParserModule` | パーサーインスタンスをエクスポートするモジュールラッパー |
-
-`MLParser` は `MLASTDocument` を返す `parse(sourceCode, options?)` メソッドを必要とします。オプションフィールドには `endTag`（終了タグ処理戦略）、`booleanish`（ブール属性検出）、`tagNameCaseSensitive`（XHTML/JSX 用）があります。
-
-## 設定型
-
-| 型                                        | 説明                                                                   |
-| ----------------------------------------- | ---------------------------------------------------------------------- |
-| `MLASTNodeType`                           | ノード種別の判別共用体タグ                                             |
-| `ElementType`                             | 要素分類：`'html' \| 'web-component' \| 'authored'`                    |
-| `EndTagType`                              | 終了タグ戦略：`'xml' \| 'omittable' \| 'never'`                        |
-| `Namespace`                               | 短い名前空間識別子：`'html' \| 'svg' \| 'mml' \| 'xlink'`              |
-| `NamespaceURI`                            | HTML、SVG、MathML、XLink の完全な名前空間 URI                          |
-| `ParserOptions`                           | パーサーに渡すオプション（`ignoreFrontMatter`、`authoredElementName`） |
-| `ParserAuthoredElementNameDistinguishing` | 著者定義要素を区別するための設定                                       |
-| `Walker<Node>`                            | AST ノードを走査するコールバック                                       |
-
-## 外部依存関係
-
-なし。このパッケージはランタイム依存関係がゼロです。TypeScript の型定義のみをエクスポートします。
-
-## 統合ポイント
-
-```mermaid
-flowchart TD
-    subgraph upstream ["上流（パーサー）"]
-        htmlParser["@markuplint/html-parser"]
-        parserUtils["@markuplint/parser-utils"]
-        jsxParser["@markuplint/jsx-parser"]
-        astroParser["@markuplint/astro-parser"]
-        vueParser["@markuplint/vue-parser"]
-        svelteParser["@markuplint/svelte-parser"]
-        pugParser["@markuplint/pug-parser"]
-    end
-
-    subgraph pkg ["@markuplint/ml-ast"]
-        astTypes["型定義"]
-    end
-
-    subgraph downstream ["下流"]
-        mlCore["@markuplint/ml-core"]
-        mlConfig["@markuplint/ml-config"]
-        mlSpec["@markuplint/ml-spec"]
-        fileResolver["@markuplint/file-resolver"]
-    end
-
-    upstream -->|"MLParser を実装\nMLASTDocument を生成"| astTypes
-    astTypes -->|"MLASTNode 型\nMLParser インターフェース"| downstream
-```
-
-### 上流
-
-すべてのパーサーは `MLParser` インターフェースを実装し、このパッケージで定義された AST ノード型を含む `MLASTDocument` インスタンスを生成します。
-
-### 下流
-
-- **`@markuplint/ml-core`** は AST ノードを消費し、`createNode()` を通じて DOM ノードにマッピングします。`MLASTElement` が `MLElement` に、`MLASTText` が `MLText` になるなど、主要な統合ポイントです。
-- **`@markuplint/ml-config`** は設定スキーマ定義で AST 型を参照します。
-- **`@markuplint/ml-spec`** は名前空間と要素型の定義を使用します。
-- **`@markuplint/file-resolver`** はパーサー関連の型を参照します。
-
-## ドキュメントマップ
-
-- [ノードリファレンス](docs/node-reference.ja.md) -- 各 AST ノード型の詳細ドキュメント
-- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング