@markuplint/ml-ast 4.4.10 → 4.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/ARCHITECTURE.ja.md +314 -0
  2. package/ARCHITECTURE.md +314 -0
  3. package/CHANGELOG.md +12 -0
  4. package/README.md +6 -0
  5. package/SKILL.md +124 -0
  6. package/docs/maintenance.ja.md +215 -0
  7. package/docs/maintenance.md +215 -0
  8. package/docs/node-reference.ja.md +485 -0
  9. package/docs/node-reference.md +485 -0
  10. package/lib/types.d.ts +191 -0
  11. package/package.json +2 -2
package/docs/node-reference.ja.md ADDED
@@ -0,0 +1,485 @@
1
+ # ノードリファレンス
2
+
3
+ `@markuplint/ml-ast` で定義されている全 AST ノード型の詳細リファレンスです。
4
+
5
+ ## 概要
6
+
7
+ すべての AST ノードは `type` フィールドに基づく**判別共用体（discriminated union）**パターンを使用しています。TypeScript の `switch` 文で網羅的な型の絞り込みが可能です：
8
+
9
+ ```typescript
10
+ import type { MLASTNode } from '@markuplint/ml-ast';
11
+
12
+ function handle(node: MLASTNode) {
13
+ switch (node.type) {
14
+ case 'doctype':
15
+ /* node は MLASTDoctype */ break;
16
+ case 'starttag':
17
+ /* node は MLASTElement */ break;
18
+ case 'endtag':
19
+ /* node は MLASTElementCloseTag */ break;
20
+ case 'comment':
21
+ /* node は MLASTComment */ break;
22
+ case 'text':
23
+ /* node は MLASTText */ break;
24
+ case 'psblock':
25
+ /* node は MLASTPreprocessorSpecificBlock */ break;
26
+ case 'invalid':
27
+ /* node は MLASTInvalid */ break;
28
+ case 'attr':
29
+ /* node は MLASTHTMLAttr */ break;
30
+ case 'spread':
31
+ /* node は MLASTSpreadAttr */ break;
32
+ }
33
+ }
34
+ ```
35
+
36
+ ## AST から MLDOM へのマッピング
37
+
38
+ このパッケージで定義されたすべての AST ノードは、最終的に `@markuplint/ml-core` によって **MLDOM** ノードに変換されます。MLDOM は markuplint の DOM 実装であり、**[DOM Standard](https://dom.spec.whatwg.org/) に準拠**しています。各 MLDOM クラスは対応する DOM インターフェース（`Node`、`Element`、`DocumentType`、`Comment`、`Text` など）を実装しており、リントルールは標準 DOM API を使って検査できます。
39
+
40
+ マッピングは `ml-core` の `createNode()` で実行されます：
41
+
42
+ | AST 型（`ml-ast`） | MLDOM クラス（`ml-core`） | 実装する DOM インターフェース | `nodeType` |
43
+ | ------------------------------------ | -------------------------- | ----------------------------- | ---------- |
44
+ | `MLASTDoctype` | `MLDocumentType` | `DocumentType` | `10` |
45
+ | `MLASTElement` | `MLElement` | `Element`, `HTMLElement` | `1` |
46
+ | `MLASTComment` | `MLComment` | `Comment` | `8` |
47
+ | `MLASTText` | `MLText` | `Text` | `3` |
48
+ | `MLASTPreprocessorSpecificBlock` | `MLBlock` | _（markuplint 独自）_ | `101` |
49
+ | `MLASTInvalid`（`kind: 'starttag'`） | `MLElement`（`x-invalid`） | `Element`, `HTMLElement` | `1` |
50
+ | `MLASTInvalid`（その他） | `MLText` | `Text` | `3` |
51
+
52
+ ### 特殊なノード
53
+
54
+ - **`MLASTElementCloseTag`** は `createNode()` を**経由しません**。代わりに `MLElement` が内部で `pairNode` 参照から `MLElementCloseTag` を生成します。`MLElementCloseTag` は DOM ツリー走査の対象ではなく、ペアとなる要素の付属物としてのみ存在します。
55
+ - **`MLASTPreprocessorSpecificBlock`** は `MLBlock` にマッピングされます。これは DOM Standard に相当するものがない **markuplint 独自の拡張**です。DOM Standard の範囲外であるカスタム `nodeType` `101` を使用します。`MLBlock` は透過的であり、子ノードはツリー走査時に親ノードに属するものとして扱われます。
56
+ - **`MLASTHTMLAttr`** と **`MLASTSpreadAttr`** は `MLAttr` にマッピングされ、DOM `Attr` インターフェース（`nodeType: 2`）を実装します。属性は `createNode()` を経由せず、`MLElement.attributes`（`MLNamedNodeMap`）を通じてアクセスされます。
57
+
58
+ ## 基底型
59
+
60
+ ### MLASTToken
61
+
62
+ すべての位置情報の基盤となるインターフェースです。すべての AST ノードとサブトークンがこれを継承します。
63
+
64
+ | フィールド | 型 | 説明 |
65
+ | ------------- | -------- | ------------------------------------------ |
66
+ | `uuid` | `string` | このトークンインスタンスの一意識別子 |
67
+ | `raw` | `string` | 元のソーステキスト |
68
+ | `startOffset` | `number` | トークン開始位置のゼロベース文字オフセット |
69
+ | `endOffset` | `number` | トークン終了位置のゼロベース文字オフセット |
70
+ | `startLine` | `number` | トークン開始位置の1ベース行番号 |
71
+ | `endLine` | `number` | トークン終了位置の1ベース行番号 |
72
+ | `startCol` | `number` | トークン開始位置の1ベース列番号 |
73
+ | `endCol` | `number` | トークン終了位置の1ベース列番号 |
74
+
75
+ **座標系について：** オフセットはゼロベース（0から数える）、行と列は1ベース（1から数える）です。これはほとんどのテキストエディタやエラーレポーターの慣例に一致しています。
76
+
77
+ ### MLASTAbstractNode
78
+
79
+ `MLASTToken` を継承し構造的メタデータを追加する内部（非エクスポート）基底インターフェースです。すべての具象ノード型がこれを継承します。
80
+
81
+ | フィールド | 型 | 説明 |
82
+ | ------------ | ------------------------- | --------------------------------------------- |
83
+ | `type` | `MLASTNodeType` | 具象ノード種別を識別する判別タグ |
84
+ | `nodeName` | `string` | ノード名（タグ名、`#text`、`#comment` など） |
85
+ | `parentNode` | `MLASTParentNode \| null` | 親ノードへの参照、トップレベルの場合は `null` |
86
+
87
+ ## MLASTDocument
88
+
89
+ **役割：** すべてのパーサーが返すルートコンテナです。AST ツリー内のノードではなく、パース結果を保持するラッパーです。
90
+
91
+ | フィールド | 型 | 説明 |
92
+ | ------------------- | ------------------------------ | ------------------------------------------------------- |
93
+ | `raw` | `string` | 元のソースコード全体 |
94
+ | `nodeList` | `readonly MLASTNodeTreeItem[]` | ドキュメント順のトップレベル AST ノードのフラットリスト |
95
+ | `isFragment` | `boolean` | フラグメントかどうか（ルート要素不要） |
96
+ | `unknownParseError` | `string \| undefined` | 未知のパースエラーの説明 |
97
+
98
+ **重要：** `nodeList` はツリーではなく**フラットリスト**です。子ノードは各要素の `childNodes` プロパティからアクセスできます。リストはドキュメント順（ソース内の出現順）でノードを含みます。
99
+
100
+ ## MLASTDoctype
101
+
102
+ **type 判別子：** `'doctype'`
103
+
104
+ **役割：** DOCTYPE 宣言（例：`<!DOCTYPE html>`）を表します。常にドキュメントのトップレベルに出現します。
105
+
106
+ | フィールド | 型 | 説明 |
107
+ | ---------- | ----------- | ---------------------------------------------- |
108
+ | `type` | `'doctype'` | 判別タグ |
109
+ | `depth` | `number` | ネストの深さ（DOCTYPE では常に 0） |
110
+ | `name` | `string` | 宣言されたドキュメントタイプ名（例：`"html"`） |
111
+ | `publicId` | `string` | DOCTYPE のパブリック識別子（ある場合） |
112
+ | `systemId` | `string` | DOCTYPE のシステム識別子（ある場合） |
113
+
114
+ **例：**
115
+
116
+ ```html
117
+ <!DOCTYPE html>
118
+ ```
119
+
120
+ `name: "html"`、`publicId: ""`、`systemId: ""` のノードが生成されます。
121
+
122
+ ## MLASTElement
123
+
124
+ **type 判別子：** `'starttag'`
125
+
126
+ **役割：** 開始タグ（例：`<div class="foo">`）を表します。AST における主要な要素表現であり、最も機能豊富なノード型です。子ノード、属性を所有し、対応する閉じタグへの参照を保持します。
127
+
128
+ | フィールド | 型 | 説明 |
129
+ | -------------------- | ------------------------------ | ---------------------------------------------------------------- |
130
+ | `type` | `'starttag'` | 判別タグ |
131
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
132
+ | `namespace` | `string` | 名前空間 URI（例：`"http://www.w3.org/1999/xhtml"`） |
133
+ | `elementType` | `ElementType` | `'html'`、`'web-component'`、`'authored'` のいずれか |
134
+ | `isFragment` | `boolean` | フラグメントとして機能するか（例：React `<>`、Vue `<template>`） |
135
+ | `attributes` | `readonly MLASTAttr[]` | この要素の属性 |
136
+ | `hasSpreadAttr` | `boolean \| undefined` | スプレッド属性を持つかどうか |
137
+ | `childNodes` | `readonly MLASTChildNode[]` | この要素の直接の子ノード |
138
+ | `pairNode` | `MLASTElementCloseTag \| null` | 対応する閉じタグ、void/自己閉じ要素の場合は `null` |
139
+ | `selfClosingSolidus` | `MLASTToken \| undefined` | 自己閉じスラッシュトークン（`/`）（例：`<br />`） |
140
+ | `tagOpenChar` | `string` | タグを開く文字（通常 `"<"`） |
141
+ | `tagCloseChar` | `string` | タグを閉じる文字（通常 `">"`） |
142
+ | `isGhost` | `boolean` | ゴーストノード（パーサーが推定した省略タグ）かどうか |
143
+
144
+ ### 要素タイプの分類
145
+
146
+ `elementType` フィールドは要素を3つのカテゴリに分類します：
147
+
148
+ | 値 | 説明 | 例 |
149
+ | ----------------- | -------------------------------------------------------- | ------------------------ |
150
+ | `'html'` | HTML Standard に基づくネイティブ HTML 要素 | `<div>`, `<span>`, `<p>` |
151
+ | `'web-component'` | HTML Standard に準拠する Web Component（ハイフン含む） | `<my-component>` |
152
+ | `'authored'` | ビューフレームワークやテンプレートエンジンの著者定義要素 | `<MyComponent>`（JSX） |
153
+
154
+ ### タグデリミタ
155
+
156
+ `tagOpenChar` と `tagCloseChar` はタグを区切る実際の文字を表します。標準 HTML では `"<"` と `">"` ですが、テンプレートエンジンは異なるデリミタを使用する場合があります。
157
+
158
+ ### ゴーストノード（省略タグ）
159
+
160
+ `isGhost` が `true` の場合、その要素はソースに明示的に記述されておらず、パーサーによって推定されたものです。HTML では特定のタグが省略可能です（例：`<table>` 内の `<tbody>`）。ゴーストノードの `raw` は空文字列です。
161
+
162
+ ### ペアノードの関係
163
+
164
+ `pairNode` フィールドは開始タグと閉じタグの間に**双方向リンク**を作成します：
165
+
166
+ - `MLASTElement.pairNode` は対応する `MLASTElementCloseTag` を指す
167
+ - `MLASTElementCloseTag.pairNode` は対応する `MLASTElement` を指す
168
+
169
+ void 要素（`<br>`、`<img>` など）と自己閉じ要素の場合、`pairNode` は `null` です。
170
+
171
+ ### フラグメント要素
172
+
173
+ `isFragment` が `true` の場合、その要素は実際の DOM ノードを持たない透過的なラッパーとして機能します。React フラグメント（`<>...</>`）や Vue の `<template>` ラッパーなどのフレームワーク固有の構文に使用されます。
174
+
175
+ **例：**
176
+
177
+ ```html
178
+ <div class="container" id="main">
179
+ <p>Hello</p>
180
+ </div>
181
+ ```
182
+
183
+ `<div>` は以下の `MLASTElement` を生成します：
184
+
185
+ - `nodeName: "div"`
186
+ - `elementType: "html"`
187
+ - `namespace: "http://www.w3.org/1999/xhtml"`
188
+ - `attributes`：`class` と `id` 属性を含む配列
189
+ - `childNodes`：`<p>` 要素とテキストノードを含む配列
190
+ - `pairNode`：`</div>` 閉じタグへの参照
191
+
192
+ ## MLASTElementCloseTag
193
+
194
+ **type 判別子：** `'endtag'`
195
+
196
+ **役割：** 閉じタグ（例：`</div>`）を表します。`pairNode` フィールドを通じて常に `MLASTElement` とペアになります。
197
+
198
+ | フィールド | 型 | 説明 |
199
+ | -------------- | -------------- | ---------------------------------- |
200
+ | `type` | `'endtag'` | 判別タグ |
201
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
202
+ | `parentNode` | `null` | 閉じタグでは常に `null` |
203
+ | `pairNode` | `MLASTElement` | 対応する開始タグ |
204
+ | `tagOpenChar` | `string` | タグを開く文字（通常 `"</"`） |
205
+ | `tagCloseChar` | `string` | タグを閉じる文字（通常 `">"`） |
206
+
207
+ **`parentNode` が常に `null` である理由：** AST モデルでは、開始タグ（`MLASTElement`）のみが親子ツリー構造に参加します。閉じタグは `pairNode` を通じて開始タグにリンクされた別のノードとして存在しますが、どの親ノードの子でもありません。これによりツリー内での要素の重複を避けています。
208
+
209
+ ## MLASTComment
210
+
211
+ **type 判別子：** `'comment'`
212
+
213
+ **役割：** HTML コメント（例：`<!-- ... -->`）を表します。
214
+
215
+ | フィールド | 型 | 説明 |
216
+ | ---------- | ------------ | ---------------------------------- |
217
+ | `type` | `'comment'` | 判別タグ |
218
+ | `nodeName` | `'#comment'` | 常に `'#comment'` |
219
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
220
+ | `isBogus` | `boolean` | ボーガス（不正形式）かどうか |
221
+
222
+ ### ボーガスコメント
223
+
224
+ `isBogus` が `true` の場合、そのコメントは HTML 仕様に従って不正形式です。ボーガスコメントの例：
225
+
226
+ - `<!...>`（有効な DOCTYPE でもコメントでもない）
227
+ - `<?xml version="1.0"?>`（HTML における処理命令）
228
+
229
+ パーサーはこれらをコメントノードとしてキャプチャしますが、リントルールが報告できるようにボーガスとしてフラグを立てます。
230
+
231
+ ## MLASTText
232
+
233
+ **type 判別子：** `'text'`
234
+
235
+ **役割：** 要素間の文字データを表します。
236
+
237
+ | フィールド | 型 | 説明 |
238
+ | ---------- | --------- | ---------------------------------- |
239
+ | `type` | `'text'` | 判別タグ |
240
+ | `nodeName` | `'#text'` | 常に `'#text'` |
241
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
242
+
243
+ `raw` フィールド（`MLASTToken` から継承）にはホワイトスペースを**含む**完全なテキスト内容が格納されます。2つの要素間のテキストノードは、完全にホワイトスペース（改行、インデントなど）で構成される場合があります。
244
+
245
+ **例：**
246
+
247
+ ```html
248
+ <p>Hello, world!</p>
249
+ ```
250
+
251
+ テキスト `Hello, world!` は `raw: "Hello, world!"` の `MLASTText` ノードとして表現されます。
252
+
253
+ ## MLASTPreprocessorSpecificBlock
254
+
255
+ **type 判別子：** `'psblock'`
256
+
257
+ **役割：** テンプレートエンジンやフレームワークの制御フロー・反復構文を表します。標準 HTML には存在しないが、Svelte、Vue、EJS、ERB などのプリプロセッサで使用される構文です。
258
+
259
+ | フィールド | 型 | 説明 |
260
+ | ----------------- | ----------------------------------------------- | ---------------------------------------- |
261
+ | `type` | `'psblock'` | 判別タグ |
262
+ | `conditionalType` | `MLASTPreprocessorSpecificBlockConditionalType` | 条件分岐・反復構文の種別 |
263
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
264
+ | `nodeName` | `string` | パーサーが決定したブロック名 |
265
+ | `isFragment` | `boolean` | 透過的なフラグメントとして機能するか |
266
+ | `childNodes` | `readonly MLASTChildNode[]` | このブロック内の直接の子ノード |
267
+ | `isBogus` | `boolean` | ボーガス（パース不能・不正形式）かどうか |
268
+
269
+ ### conditionalType の値
270
+
271
+ `conditionalType` フィールドはブロックの意味的な役割を示します：
272
+
273
+ | 値 | 説明 | 例（Svelte） | 例（EJS/ERB） |
274
+ | ------------------ | ---------------------------- | ----------------------- | ------------------- |
275
+ | `'if'` | 条件分岐（開始） | `{#if condition}` | `<% if (x) { %>` |
276
+ | `'if:elseif'` | 代替条件分岐 | `{:else if condition}` | `<% } else if { %>` |
277
+ | `'if:else'` | デフォルト（else）分岐 | `{:else}` | `<% } else { %>` |
278
+ | `'switch:case'` | switch case 分岐 | -- | -- |
279
+ | `'switch:default'` | switch default 分岐 | -- | -- |
280
+ | `'each'` | 反復（ループ）ブロック | `{#each items as item}` | `<% for (...) { %>` |
281
+ | `'each:empty'` | 反復ブロックの空状態 | `{:else}`（`#each` 内） | -- |
282
+ | `'await'` | 非同期ブロック（保留状態） | `{#await promise}` | -- |
283
+ | `'await:then'` | 非同期ブロックの解決状態 | `{:then value}` | -- |
284
+ | `'await:catch'` | 非同期ブロックの拒否状態 | `{:catch error}` | -- |
285
+ | `'end'` | 閉じブロック | `{/if}`, `{/each}` | `<% } %>` |
286
+ | `null` | 特定の条件セマンティクスなし | -- | `<%= expr %>` |
287
+
288
+ ### フレームワーク固有の例
289
+
290
+ **Svelte：**
291
+
292
+ ```svelte
293
+ {#if loggedIn}
294
+ <p>Welcome!</p>
295
+ {:else}
296
+ <p>Please log in.</p>
297
+ {/if}
298
+ ```
299
+
300
+ 3つの `psblock` ノードが生成されます：
301
+
302
+ 1. `conditionalType: 'if'`：`{#if loggedIn}`
303
+ 2. `conditionalType: 'if:else'`：`{:else}`
304
+ 3. `conditionalType: 'end'`：`{/if}`
305
+
306
+ **Vue（v-if ディレクティブは異なる方法で処理されます -- psblock ではなく要素属性経由）。**
307
+
308
+ **EJS：**
309
+
310
+ ```ejs
311
+ <% if (user) { %>
312
+ <p><%= user.name %></p>
313
+ <% } %>
314
+ ```
315
+
316
+ 生成されるノード：
317
+
318
+ 1. `conditionalType: 'if'`：`<% if (user) { %>`
319
+ 2. `conditionalType: 'end'`：`<% } %>`
320
+ 3. `conditionalType: null`：`<%= user.name %>`（式出力、条件セマンティクスなし）
321
+
322
+ ## MLASTInvalid
323
+
324
+ **type 判別子：** `'invalid'`
325
+
326
+ **役割：** 正しくパースできなかったマークアップを表します。パーサーはパース不能なコンテンツを完全に失敗するのではなく、invalid ノードとしてキャプチャし、リントルールが問題を報告できるようにします。
327
+
328
+ | フィールド | 型 | 説明 |
329
+ | ---------- | --------------------------------------------------------- | ---------------------------------- |
330
+ | `type` | `'invalid'` | 判別タグ |
331
+ | `nodeName` | `'#invalid'` | 常に `'#invalid'` |
332
+ | `depth` | `number` | ドキュメントツリーでのネストの深さ |
333
+ | `kind` | `Exclude<MLASTChildNode['type'], 'invalid'> \| undefined` | 本来意図されていたノードの種類 |
334
+ | `isBogus` | `true` | invalid ノードでは常に `true` |
335
+
336
+ ### `kind` フィールドと ml-core での変換
337
+
338
+ `kind` フィールドは、パーサーが不正なコンテンツが本来何であるべきだと考えるかを記録します。この情報は `ml-core` が AST を DOM ツリーに変換する際に使用されます：
339
+
340
+ | `kind` の値 | ml-core での変換 |
341
+ | -------------------- | ----------------------------------------------------------------------------- |
342
+ | `'starttag'` | `nodeName: 'x-invalid'`、`elementType: 'web-component'` の `MLElement` に変換 |
343
+ | その他 / `undefined` | `nodeName: '#text'` の `MLText` ノードに変換 |
344
+
345
+ この変換により、リントルールは不正なコンテンツに対しても動作でき、パーサーの推測に応じて要素またはテキストとして扱います。
346
+
347
+ ## MLASTHTMLAttr
348
+
349
+ **type 判別子：** `'attr'`
350
+
351
+ **役割：** 通常の HTML 属性を表し、構成トークンに完全に分解されます。この粒度の高い分解により、リントルールは属性の個々の部分（ホワイトスペース、引用符スタイル、名前、値）を検査・検証できます。
352
+
353
+ | フィールド | 型 | 説明 |
354
+ | ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
355
+ | `type` | `'attr'` | 判別タグ |
356
+ | `nodeName` | `string` | 文字列としての属性名 |
357
+ | `spacesBeforeName` | `MLASTToken` | 属性名の前のホワイトスペーストークン |
358
+ | `name` | `MLASTToken` | 属性名トークン |
359
+ | `spacesBeforeEqual` | `MLASTToken` | 名前と等号の間のホワイトスペーストークン |
360
+ | `equal` | `MLASTToken` | 等号トークン |
361
+ | `spacesAfterEqual` | `MLASTToken` | 等号と値の間のホワイトスペーストークン |
362
+ | `startQuote` | `MLASTToken` | 開始引用符トークン |
363
+ | `value` | `MLASTToken` | 属性値トークン |
364
+ | `endQuote` | `MLASTToken` | 終了引用符トークン |
365
+ | `isDynamicValue` | `true \| undefined` | 値が動的式かどうか（例：フレームワークバインディング） |
366
+ | `isDirective` | `true \| undefined` | フレームワークディレクティブかどうか（例：`v-if`、`@click`） |
367
+ | `potentialName` | `string \| undefined` | 実際の名前がディレクティブの場合の解決済み属性名 |
368
+ | `potentialValue` | `string \| undefined` | 実際の値が動的な場合の解決済み属性値 |
369
+ | `valueType` | `'string' \| 'number' \| 'boolean' \| 'code' \| undefined` | 属性値のセマンティックな型 |
370
+ | `candidate` | `string \| undefined` | 自動修正用の候補属性名 |
371
+ | `isDuplicatable` | `boolean` | この属性が同一要素上に複数回出現可能かどうか |
372
+
373
+ ### 属性の分解
374
+
375
+ 属性は個別のトークンに分解され、それぞれが独自の位置情報を持ちます：
376
+
377
+ ```
378
+ ·class="container"
379
+ ↑ ↑↑ ↑
380
+ │ ││ └─ endQuote (raw: '"')
381
+ │ │└─ value (raw: 'container')
382
+ │ └─ startQuote (raw: '"')
383
+ │ equal (raw: '=')
384
+ │ spacesBeforeEqual (raw: '')
385
+ │ spacesAfterEqual (raw: '')
386
+ └─ spacesBeforeName (raw: ' ')
387
+ name (raw: 'class')
388
+ ```
389
+
390
+ 値のないブール属性（例：`disabled`）の場合、`equal`、`startQuote`、`value`、`endQuote` トークンは存在しますが、`raw` は空文字列です。
391
+
392
+ ### フレームワーク拡張フィールド
393
+
394
+ これらのフィールドはフレームワーク固有のパーサーによって設定されます：
395
+
396
+ - **`isDynamicValue`**：属性値が動的式の場合 `true`。例えば Vue の `<div :class="expr">` では、値 `expr` は動的です。
397
+ - **`isDirective`**：属性がフレームワークディレクティブの場合 `true`。例：Vue の `v-if`、`v-for`、`@click`、Svelte の `on:click`。
398
+ - **`potentialName`**：解決された標準属性名。例：`:class` は `class` に解決、`@click` は `onclick` に解決。
399
+ - **`potentialValue`**：動的式が静的に解析可能な場合の解決された属性値。
400
+ - **`valueType`**：値のセマンティックな型 -- `'string'`、`'number'`、`'boolean'`、`'code'`（式）。
401
+ - **`candidate`**：属性名の修正候補。自動修正ルールで使用。
402
+ - **`isDuplicatable`**：同一要素上で属性が複数回出現可能な場合 `true`（例：値をマージするテンプレートエンジンでの `class`）。
403
+
404
+ ## MLASTSpreadAttr
405
+
406
+ **type 判別子：** `'spread'`
407
+
408
+ **役割：** スプレッド属性（例：JSX の `{...props}`）を表します。スプレッド属性は静的に分解できないため、最小限のノード型です。
409
+
410
+ | フィールド | 型 | 説明 |
411
+ | ---------- | ----------- | ---------------- |
412
+ | `type` | `'spread'` | 判別タグ |
413
+ | `nodeName` | `'#spread'` | 常に `'#spread'` |
414
+
415
+ `MLASTSpreadAttr` は `MLASTAbstractNode` ではなく `MLASTToken` を直接継承するため、位置情報（`uuid`、`raw`、`startOffset` など）はありますが、`parentNode` や `depth` はありません。
416
+
417
+ ## 共用体型リファレンス
418
+
419
+ | 共用体型 | メンバー | 用途 |
420
+ | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
421
+ | `MLASTNode` | `MLASTDoctype \| MLASTTag \| MLASTComment \| MLASTText \| MLASTPreprocessorSpecificBlock \| MLASTInvalid \| MLASTAttr` | すべての AST ノード型 |
422
+ | `MLASTParentNode` | `MLASTElement \| MLASTPreprocessorSpecificBlock` | 子ノードを含むことができるノード |
423
+ | `MLASTChildNode` | `MLASTTag \| MLASTText \| MLASTComment \| MLASTPreprocessorSpecificBlock \| MLASTInvalid` | 子として出現できるノード |
424
+ | `MLASTNodeTreeItem` | `MLASTChildNode \| MLASTDoctype` | `MLASTDocument.nodeList` のトップレベルアイテム |
425
+ | `MLASTTag` | `MLASTElement \| MLASTElementCloseTag` | タグノード（開始または終了） |
426
+ | `MLASTAttr` | `MLASTHTMLAttr \| MLASTSpreadAttr` | 属性ノード |
427
+
428
+ ## 型の絞り込みパターン
429
+
430
+ ### `type` による絞り込み
431
+
432
+ 最も一般的なパターン -- `switch` 文で網羅的に絞り込みます：
433
+
434
+ ```typescript
435
+ import type { MLASTChildNode } from '@markuplint/ml-ast';
436
+
437
+ function processChild(node: MLASTChildNode) {
438
+ switch (node.type) {
439
+ case 'starttag':
440
+ console.log(`要素: <${node.nodeName}>, 属性数: ${node.attributes.length}`);
441
+ break;
442
+ case 'endtag':
443
+ console.log(`閉じタグ: </${node.nodeName}>`);
444
+ break;
445
+ case 'text':
446
+ console.log(`テキスト: "${node.raw}"`);
447
+ break;
448
+ case 'comment':
449
+ console.log(`コメント (bogus: ${node.isBogus})`);
450
+ break;
451
+ case 'psblock':
452
+ console.log(`ブロック: ${node.nodeName}, conditional: ${node.conditionalType}`);
453
+ break;
454
+ case 'invalid':
455
+ console.log(`不正: kind=${node.kind}`);
456
+ break;
457
+ }
458
+ }
459
+ ```
460
+
461
+ ### 親ノードの判定
462
+
463
+ ```typescript
464
+ import type { MLASTNode, MLASTParentNode } from '@markuplint/ml-ast';
465
+
466
+ function isParent(node: MLASTNode): node is MLASTParentNode {
467
+ return node.type === 'starttag' || node.type === 'psblock';
468
+ }
469
+ ```
470
+
471
+ ### 属性型の判別
472
+
473
+ ```typescript
474
+ import type { MLASTAttr } from '@markuplint/ml-ast';
475
+
476
+ function processAttr(attr: MLASTAttr) {
477
+ if (attr.type === 'attr') {
478
+ // MLASTHTMLAttr -- name, value, quotes などを持つ
479
+ console.log(`${attr.name.raw}="${attr.value.raw}"`);
480
+ } else {
481
+ // MLASTSpreadAttr -- raw と位置情報のみ
482
+ console.log(`スプレッド: ${attr.raw}`);
483
+ }
484
+ }
485
+ ```