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

package/ARCHITECTURE.md

@@ -1,309 +0,0 @@
-# @markuplint/ml-ast
-
-## Overview
-
-`@markuplint/ml-ast` is a pure type-definition package that defines the language-independent Abstract Syntax Tree (AST) intermediate representation for markuplint. It contains **zero runtime code** and **zero dependencies** -- only TypeScript type definitions that all parsers must produce and all downstream packages consume.
-
-Every markup language parser (HTML, JSX, Vue, Svelte, Astro, Pug, etc.) parses source code into the types defined here, enabling markuplint's core and rules to operate on a unified AST regardless of the source language.
-
-## Directory Structure
-
-```
-src/
-├── index.ts   — Re-exports all types from types.ts
-└── types.ts   — All type definitions (~470 lines)
-```
-
-## Architecture Diagram
-
-```mermaid
-flowchart TD
-    subgraph parsers ["Parsers (upstream)"]
-        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["Type Definitions\n(MLASTDocument, MLASTElement,\nMLASTComment, MLASTText, ...)"]
-    end
-
-    subgraph downstream ["Downstream"]
-        mlCore["@markuplint/ml-core\n(AST → DOM mapping)"]
-        mlConfig["@markuplint/ml-config"]
-        mlSpec["@markuplint/ml-spec"]
-        rules["@markuplint/rules"]
-        fileResolver["@markuplint/file-resolver"]
-    end
-
-    parsers -->|"produce"| types
-    types -->|"consumed by"| downstream
-    mlCore -->|"creates DOM nodes from"| types
-```
-
-## Type Inheritance Diagram
-
-```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
-```
-
-## Union Types
-
-```mermaid
-flowchart TD
-    subgraph MLASTNode ["MLASTNode (all node types)"]
-        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(highlighted in blue)"]
-```
-
-## Node Types at a Glance
-
-| Type                             | `type` Value | Example             | Description                                              |
-| -------------------------------- | ------------ | ------------------- | -------------------------------------------------------- |
-| `MLASTDoctype`                   | `'doctype'`  | `<!DOCTYPE html>`   | DOCTYPE declaration                                      |
-| `MLASTElement`                   | `'starttag'` | `<div class="foo">` | Opening element tag with attributes, children, namespace |
-| `MLASTElementCloseTag`           | `'endtag'`   | `</div>`            | Closing element tag, paired with its opening tag         |
-| `MLASTComment`                   | `'comment'`  | `<!-- ... -->`      | HTML comment, with bogus flag                            |
-| `MLASTText`                      | `'text'`     | text content        | Character data between elements                          |
-| `MLASTPreprocessorSpecificBlock` | `'psblock'`  | `{#if}`, `<% %>`    | Template engine constructs                               |
-| `MLASTInvalid`                   | `'invalid'`  | unparsable markup   | Invalid node with intended kind hint                     |
-| `MLASTHTMLAttr`                  | `'attr'`     | `class="foo"`       | Fully decomposed HTML attribute                          |
-| `MLASTSpreadAttr`                | `'spread'`   | `{...props}`        | JSX spread attribute                                     |
-
-See [Node Reference](docs/node-reference.md) for detailed documentation of each type.
-
-## AST to MLDOM Mapping
-
-Each AST node is ultimately converted into an **MLDOM** node by `@markuplint/ml-core`. MLDOM conforms to the [DOM Standard](https://dom.spec.whatwg.org/) -- each class implements the corresponding DOM interface (`Node`, `Element`, `DocumentType`, `Comment`, `Text`, etc.), so lint rules can use standard DOM APIs for inspection.
-
-| AST Type (`ml-ast`)                 | MLDOM Class (`ml-core`)   | DOM Interface            | `nodeType` |
-| ----------------------------------- | ------------------------- | ------------------------ | ---------- |
-| `MLASTDoctype`                      | `MLDocumentType`          | `DocumentType`           | `10`       |
-| `MLASTElement`                      | `MLElement`               | `Element`, `HTMLElement` | `1`        |
-| `MLASTComment`                      | `MLComment`               | `Comment`                | `8`        |
-| `MLASTText`                         | `MLText`                  | `Text`                   | `3`        |
-| `MLASTPreprocessorSpecificBlock`    | `MLBlock`                 | _(markuplint-specific)_  | `101`      |
-| `MLASTInvalid` (`kind: 'starttag'`) | `MLElement` (`x-invalid`) | `Element`, `HTMLElement` | `1`        |
-| `MLASTInvalid` (other)              | `MLText`                  | `Text`                   | `3`        |
-| `MLASTHTMLAttr` / `MLASTSpreadAttr` | `MLAttr`                  | `Attr`                   | `2`        |
-
-**Special nodes:**
-
-- **`MLBlock`** (`nodeType: 101`) is a markuplint-specific extension with no DOM Standard equivalent. It acts as a transparent container -- its children are treated as belonging to the parent for tree traversal.
-- **`MLElementCloseTag`** is not created by `createNode()`. Instead, `MLElement` internally resolves the `pairNodeUuid` to look up the closing tag's AST node and creates an `MLElementCloseTag` from it. It exists only as a satellite of its paired element and is not part of the DOM tree traversal.
-- **`MLASTInvalid`** is a recovery node -- it is never preserved as-is in MLDOM, but converted to either an `MLElement` (with tag name `x-invalid`) or an `MLText`, depending on its `kind` field.
-
-See [Node Reference -- AST to MLDOM Mapping](docs/node-reference.md#ast-to-mldom-mapping) for details.
-
-## Attribute Decomposition Model
-
-`MLASTHTMLAttr` decomposes each attribute into individual tokens with full positional information:
-
-```
- ·class="container"
- ↑     ↑↑         ↑
- │     ││         └─ endQuote
- │     │└─ value
- │     └─ startQuote
- │        equal
- └─ spacesBeforeName
-    name
-```
-
-This enables lint rules to validate whitespace around `=`, quoting style, and attribute naming conventions with precise source locations. See [Node Reference](docs/node-reference.md#mlasthtmlattr) for complete field documentation.
-
-## Parser Interface
-
-| Type             | Description                                   |
-| ---------------- | --------------------------------------------- |
-| `MLParser`       | Interface for a markuplint-compatible parser  |
-| `MLParserModule` | Module wrapper that exports a parser instance |
-
-`MLParser` requires a `parse(sourceCode, options?)` method that returns an `MLASTDocument`. Optional fields include `endTag` (end tag handling strategy), `booleanish` (boolean attribute detection), and `tagNameCaseSensitive` (for XHTML/JSX).
-
-## Configuration Types
-
-| Type                                      | Description                                                            |
-| ----------------------------------------- | ---------------------------------------------------------------------- |
-| `MLASTNodeType`                           | Discriminant union tag for node kinds                                  |
-| `ElementType`                             | Element classification: `'html' \| 'web-component' \| 'authored'`      |
-| `EndTagType`                              | End tag strategy: `'xml' \| 'omittable' \| 'never'`                    |
-| `Namespace`                               | Short namespace identifiers: `'html' \| 'svg' \| 'mml' \| 'xlink'`     |
-| `NamespaceURI`                            | Full namespace URIs for HTML, SVG, MathML, XLink                       |
-| `ParserOptions`                           | Options passed to parsers (`ignoreFrontMatter`, `authoredElementName`) |
-| `ParserAuthoredElementNameDistinguishing` | Configuration for distinguishing authored elements                     |
-| `Walker<Node>`                            | Callback for walking AST nodes                                         |
-
-## External Dependencies
-
-None. This package has zero runtime dependencies. It exports only TypeScript type definitions.
-
-## Integration Points
-
-```mermaid
-flowchart TD
-    subgraph upstream ["Upstream (Parsers)"]
-        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["Type Definitions"]
-    end
-
-    subgraph downstream ["Downstream"]
-        mlCore["@markuplint/ml-core"]
-        mlConfig["@markuplint/ml-config"]
-        mlSpec["@markuplint/ml-spec"]
-        fileResolver["@markuplint/file-resolver"]
-    end
-
-    upstream -->|"implement MLParser\nproduce MLASTDocument"| astTypes
-    astTypes -->|"MLASTNode types\nMLParser interface"| downstream
-```
-
-### Upstream
-
-All parsers implement the `MLParser` interface and produce `MLASTDocument` instances containing the AST node types defined in this package.
-
-### Downstream
-
-- **`@markuplint/ml-core`** consumes AST nodes and maps them to DOM nodes via `createNode()`. This is the primary integration point where `MLASTElement` becomes `MLElement`, `MLASTText` becomes `MLText`, etc.
-- **`@markuplint/ml-config`** references AST types in configuration schema definitions.
-- **`@markuplint/ml-spec`** uses namespace and element type definitions.
-- **`@markuplint/file-resolver`** references parser-related types.
-
-## Documentation Map
-
-- [Node Reference](docs/node-reference.md) -- Detailed documentation of each AST node type
-- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/SKILL.md

@@ -1,123 +0,0 @@
----
-description: Perform maintenance tasks for @markuplint/ml-ast
----
-
-# ml-ast-maintenance
-
-Perform maintenance tasks for `@markuplint/ml-ast`: add AST node types,
-add fields to existing nodes, add conditional type values, and update the parser interface.
-
-## Input
-
-`$ARGUMENTS` specifies the task. Supported tasks:
-
-| Task                           | Description                                    |
-| ------------------------------ | ---------------------------------------------- |
-| `add-node-type <name>`         | Add a new AST node type                        |
-| `add-field <node> <field>`     | Add a field to an existing node type           |
-| `add-conditional-type <value>` | Add a conditional type value for psblock nodes |
-| `update-parser-interface`      | Modify the MLParser interface                  |
-
-If omitted, defaults to `add-node-type`.
-
-## Reference
-
-Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
-for the full guide. The recipes there are the source of truth for procedures.
-
-Also read:
-
-- `docs/node-reference.md` -- Detailed documentation of each AST node type
-- `ARCHITECTURE.md` -- Package overview, type hierarchy, and integration points
-
-## Task: add-node-type
-
-Add a new AST node type. Follow recipe #1 in `docs/maintenance.md`.
-
-### Step 1: Define the type
-
-1. Read `src/types.ts` to understand the existing type hierarchy
-2. Add the type value to `MLASTNodeType`
-3. Define the interface extending `MLASTAbstractNode`
-4. Add to relevant union types (`MLASTNode`, `MLASTChildNode`, etc.)
-
-### Step 2: Update downstream
-
-1. Update `ml-core`'s `createNode()` in `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`
-2. Add a `case` for the new type value in the `switch` statement
-3. Create or reuse an appropriate DOM node class
-
-### Step 3: Build and verify
-
-1. Build: `yarn build --scope @markuplint/ml-ast`
-2. Build: `yarn build --scope @markuplint/ml-core`
-3. Check the downstream impact checklist in `docs/maintenance.md`
-
-## Task: add-field
-
-Add a field to an existing node type. Follow recipe #2 in `docs/maintenance.md`.
-
-### Step 1: Add the field
-
-1. Read `src/types.ts` and find the target interface
-2. Add the field (prefer optional `?` for backward compatibility)
-3. Add JSDoc documentation for the new field
-
-### Step 2: Update consumers
-
-1. Update parsers that should populate the new field
-2. Update `ml-core` if the field affects DOM node creation
-
-### Step 3: Build and verify
-
-1. Build: `yarn build --scope @markuplint/ml-ast`
-2. Build affected packages
-3. Check the downstream impact checklist in `docs/maintenance.md`
-
-## Task: add-conditional-type
-
-Add a conditional type value for preprocessor-specific blocks. Follow recipe #4 in `docs/maintenance.md`.
-
-### Step 1: Add the value
-
-1. Read `src/types.ts` and find `MLASTPreprocessorSpecificBlockConditionalType`
-2. Add the new value to the union type
-3. Document the value's semantic meaning in the JSDoc comment
-
-### Step 2: Update parsers
-
-1. Update the parser that produces blocks with this conditional type
-2. Verify the value follows the naming convention (`category:variant`, e.g., `if:elseif`)
-
-### Step 3: Build and verify
-
-1. Build: `yarn build --scope @markuplint/ml-ast`
-2. Build the affected parser package
-
-## Task: update-parser-interface
-
-Modify the `MLParser` interface. Follow recipe #5 in `docs/maintenance.md`.
-
-### Step 1: Make changes
-
-1. Read `src/types.ts` and find `MLParser`
-2. Make changes (prefer adding optional fields for backward compatibility)
-
-### Step 2: Update all parsers
-
-1. Update all parser implementations (see the list in `docs/maintenance.md` recipe #5)
-2. Update `@markuplint/parser-utils` if it provides shared implementation
-
-### Step 3: Build and verify
-
-1. Build all packages: `yarn build`
-2. Run all tests: `yarn test`
-
-## Rules
-
-1. **All node types extend `MLASTAbstractNode`** (except attributes which extend `MLASTToken`).
-2. **Use `readonly` for all interface fields.** The AST is immutable after parsing.
-3. **Prefer optional fields** when adding to existing interfaces for backward compatibility.
-4. **Always update `createNode()` in `ml-core`** when adding new node types.
-5. **Follow the discriminated union pattern.** Every node must have a unique `type` literal value.
-6. **Add JSDoc comments** to all new exported types and fields.

package/docs/maintenance.ja.md

@@ -1,213 +0,0 @@
-# メンテナンスガイド
-
-`@markuplint/ml-ast` の実践的な操作・メンテナンスガイドです。
-
-## コマンド
-
-| コマンド                                      | 説明                              |
-| --------------------------------------------- | --------------------------------- |
-| `yarn build --scope @markuplint/ml-ast`       | TypeScript を `lib/` にコンパイル |
-| `yarn workspace @markuplint/ml-ast run dev`   | ウォッチモードコンパイル          |
-| `yarn workspace @markuplint/ml-ast run clean` | コンパイル出力をクリーン          |
-
-## テスト
-
-このパッケージには**テストファイルがありません**。純粋な型定義パッケージのため、正当性はビルド時に TypeScript コンパイラで検証されます。統合テストはこれらの型を消費する下流パッケージで実施されます。
-
-型の正当性を検証するには：
-
-```bash
-yarn build --scope @markuplint/ml-ast
-```
-
-## 一般的なレシピ
-
-### 1. 新しいノード型の追加
-
-新しい AST ノード型（例：仮想的な `MLASTDirective`）を追加する場合：
-
-1. **`MLASTNodeType` に型の値を追加**（`src/types.ts`）：
-
-   ```typescript
-   export type MLASTNodeType =
-     | 'doctype'
-     | 'starttag'
-     // ... 既存の値
-     | 'directive'; // ここに追加
-   ```
-
-2. **`MLASTAbstractNode` を継承するインターフェースを定義**：
-
-   ```typescript
-   export interface MLASTDirective extends MLASTAbstractNode {
-     readonly type: 'directive';
-     readonly depth: number;
-     // 型固有のフィールドを追加
-   }
-   ```
-
-3. **関連する共用体型に追加**：
-   - `MLASTNode` -- 常にこの共用体に追加
-   - `MLASTChildNode` -- 要素の子になれる場合
-   - `MLASTNodeTreeItem` -- `nodeList` のトップレベルに出現できる場合
-   - `MLASTParentNode` -- 子ノードを含むことができる場合
-
-4. **`ml-core` の `createNode()` を更新**（`packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`）：
-   - `switch` 文に新しい type 値の `case` を追加
-   - 適切な DOM ノードクラスを作成または再利用
-
-5. **このノード型を生成するパーサーを更新**
-
-6. **ビルドして検証**：
-   ```bash
-   yarn build --scope @markuplint/ml-ast
-   yarn build --scope @markuplint/ml-core
-   ```
-
-### 2. 既存ノード型へのフィールド追加
-
-既存のノードインターフェースに新しいフィールドを追加する場合：
-
-1. **`src/types.ts` のインターフェースにフィールドを追加**：
-
-   ```typescript
-   export interface MLASTElement extends MLASTAbstractNode {
-     // ... 既存のフィールド
-     readonly newField: string; // 必須フィールド
-     readonly optionalField?: boolean; // オプションフィールド（後方互換性のため推奨）
-   }
-   ```
-
-2. **後方互換性のためオプションフィールド**（`?`）を推奨 -- フィールドがなくても既存のパーサーが壊れません。
-
-3. **新しいフィールドを設定するパーサーを更新**
-
-4. **フィールドが DOM ノードの作成や動作に影響する場合は `ml-core` を更新**
-
-5. **全チェーンをビルド**：
-   ```bash
-   yarn build --scope @markuplint/ml-ast
-   yarn build --scope @markuplint/ml-core
-   ```
-
-### 3. 新しい属性バリアントの追加
-
-`MLASTHTMLAttr` と `MLASTSpreadAttr` に加えて新しい属性型を追加する場合：
-
-1. **`MLASTNodeType` に型の値を追加**（まだない場合）
-
-2. **`MLASTToken` を継承するインターフェースを定義**：
-
-   ```typescript
-   export interface MLASTNewAttr extends MLASTToken {
-     readonly type: 'newattr';
-     readonly nodeName: string;
-     // 属性固有のフィールドを追加
-   }
-   ```
-
-3. **`MLASTAttr` 共用体に追加**：
-
-   ```typescript
-   export type MLASTAttr = MLASTHTMLAttr | MLASTSpreadAttr | MLASTNewAttr;
-   ```
-
-4. **属性型で switch する下流の消費者を更新**
-
-5. **ビルドして検証**
-
-### 4. `MLASTBlockBehaviorType` の値追加
-
-プリプロセッサブロックの新しいブロック動作種別を追加する場合：
-
-1. **`src/types.ts` の `MLASTBlockBehaviorType` に値を追加**：
-
-   ```typescript
-   export type MLASTBlockBehaviorType =
-     | 'if'
-     | 'if:elseif'
-     // ... 既存の値
-     | 'newvalue'; // ここに追加
-   ```
-
-2. **この動作種別で `blockBehavior` を設定するパーサーを更新**
-
-3. **新しい値が DOM 作成時に特別な処理を必要とする場合は `ml-core` を更新**
-
-4. **ビルドして検証**：
-   ```bash
-   yarn build --scope @markuplint/ml-ast
-   ```
-
-### 5. `MLParser` インターフェースの変更
-
-パーサーインターフェースを変更する場合：
-
-1. **`src/types.ts` の `MLParser` を変更**
-
-2. **後方互換性を考慮**：
-   - オプションフィールドの追加は安全
-   - 必須フィールドの追加やシグネチャの変更は破壊的変更
-
-3. **すべてのパーサー実装を更新**：
-   - `@markuplint/html-parser`
-   - `@markuplint/jsx-parser`
-   - `@markuplint/vue-parser`
-   - `@markuplint/svelte-parser`
-   - `@markuplint/astro-parser`
-   - `@markuplint/pug-parser`
-   - `@markuplint/parser-utils`
-
-4. **影響を受けるすべてのパッケージをビルド**：
-   ```bash
-   yarn build
-   ```
-
-## 下流影響チェックリスト
-
-このパッケージの型を変更する際、以下の下流パッケージがビルド・テストに通ることを確認してください：
-
-- [ ] `@markuplint/html-parser` -- HTML パーサー
-- [ ] `@markuplint/parser-utils` -- パーサーユーティリティ関数
-- [ ] `@markuplint/jsx-parser` -- JSX パーサー
-- [ ] `@markuplint/astro-parser` -- Astro パーサー
-- [ ] `@markuplint/vue-parser` -- Vue SFC パーサー
-- [ ] `@markuplint/svelte-parser` -- Svelte パーサー
-- [ ] `@markuplint/pug-parser` -- Pug パーサー
-- [ ] `@markuplint/ml-core` -- コア DOM マッピング（最重要）
-- [ ] `@markuplint/ml-config` -- 設定型
-- [ ] `@markuplint/ml-spec` -- 仕様型
-- [ ] `@markuplint/file-resolver` -- ファイル解決
-
-最も重要な下流パッケージは `@markuplint/ml-core` で、`createNode()` -- `node.type` に対する `switch` 文で AST ノードを DOM ノードにマッピングする関数を含みます。
-
-## トラブルシューティング
-
-### 型変更後のビルドエラー
-
-**症状：** 型の変更後、下流パッケージのビルドが失敗する。
-
-**診断：**
-
-1. まずこのパッケージをビルド：`yarn build --scope @markuplint/ml-ast`
-2. 次に `ml-core` をビルド：`yarn build --scope @markuplint/ml-core`
-3. `switch` の網羅性エラーを確認 -- TypeScript は `node.type` の `switch` で新しい型値のケースが欠けている場合に報告します
-4. 共用体型の不一致を確認 -- 共用体に型を追加すると、既存の絞り込みコードの更新が必要になる場合があります
-
-### ml-core の `createNode()` のケース漏れ
-
-**症状：** 実行時に `TypeError: Invalid AST node types "newtype"` が発生する。
-
-**原因：** 新しいノード型が `MLASTNodeType` と関連する共用体型に追加されたが、`ml-core` の `createNode()` の switch 文が更新されていない。
-
-**修正：** `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts` に新しい型の `case` を追加してください。
-
-### パーサーが期待されるノードを生成しない
-
-**症状：** パーサーが新しく追加されたフィールドや型のノードを生成しない。
-
-**診断：**
-
-1. パーサーの実装が新しいフィールドを設定するように更新されているか確認
-2. オプションフィールドの場合、フィールドが暗黙的に `undefined` になっていないか検証
-3. パーサーとこのパッケージの両方をビルドして型の整合性を確認