@markuplint/vue-parser 4.6.21 → 4.6.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,283 @@
+# @markuplint/vue-parser
+
+## 概要
+
+`@markuplint/vue-parser` は markuplint 用の Vue Single File Component（SFC）テンプレートパーサーです。vue-eslint-parser を使用して Vue SFC の `<template>` ブロックを vue-eslint-parser AST にパースし、その後統一された markuplint AST 形式（`MLASTDocument`）に変換します。Vue 固有のディレクティブ（`v-bind`、`v-on`、`v-model`、`v-slot`）、テンプレート式コンテナ（`{{ }}`）、テンプレートコメント、PascalCase コンポーネント検出を処理します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                — parser を再エクスポート
+├── parser.ts               — Parser<ASTNode, State> を拡張する VueParser クラス
+├── index.spec.ts           — VueParser の統合テスト
+└── vue-parser/
+    └── index.ts            — vue-eslint-parser ラッパー、ASTNode/ASTComment 型エクスポート
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        mlAst["@markuplint/ml-ast\n(AST 型定義)"]
+        parserUtils["@markuplint/parser-utils\n(抽象 Parser クラス)"]
+        vueEslintParser["vue-eslint-parser\n(Vue SFC トークナイザ)"]
+    end
+
+    subgraph pkg ["@markuplint/vue-parser"]
+        vueParser["VueParser\nextends Parser‹ASTNode, State›"]
+        vueParseFn["vueParse()\nvue-eslint-parser ラッパー"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    mlAst -->|"AST 型"| vueParser
+    parserUtils -->|"Parser 基底クラス"| vueParser
+    vueEslintParser -->|"parse()"| vueParseFn
+    vueParseFn -->|"ESLintProgram AST"| vueParser
+
+    vueParser -->|"MLASTDocument を生成"| mlCore
+```
+
+## VueParser クラス
+
+### 継承関係
+
+```
+Parser<ASTNode, State>  (@markuplint/parser-utils)
+    └── VueParser        (このパッケージ)
+```
+
+### コンストラクタ
+
+コンストラクタは2つの引数でパーサーを構成します:
+
+| 引数            | 値                      | 用途                                                                               |
+| --------------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `ParserOptions` | `{ endTagType: 'xml' }` | Vue テンプレートは明示的な閉じタグを使用（XML スタイル）、HTML void ルールではない |
+| 初期 State      | `{ comments: [] }`      | 空のコメント配列。`tokenize()` で設定される                                        |
+
+`tagNameCaseSensitive` の動作は基底クラスから継承され、Vue の `detectElementType` オーバーライドと組み合わせて PascalCase コンポーネント名を正しく処理します。
+
+### State 型
+
+パーサーは `State` 型を通じて内部状態を管理します:
+
+| フィールド | 型                      | 用途                                                                                         |
+| ---------- | ----------------------- | -------------------------------------------------------------------------------------------- |
+| `comments` | `readonly ASTComment[]` | tokenize 中に vue-eslint-parser から抽出されたテンプレートコメント。後の flattenNodes で注入 |
+
+### オーバーライドメソッド
+
+| メソッド              | 用途                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `tokenize()`          | vue-eslint-parser を呼び出し、`templateBody.children` とコメントを抽出                        |
+| `parseError()`        | vue-eslint-parser の `SyntaxError`（`lineNumber`/`column` 付き）を `ParserError` に変換       |
+| `nodeize()`           | vue-eslint-parser AST ノード（VText、VElement、VExpressionContainer）を markuplint AST に変換 |
+| `flattenNodes()`      | 基底のフラット化を拡張し、兄弟ノード間にテンプレートコメントを注入                            |
+| `afterFlattenNodes()` | `exposeWhiteSpace: false`、`exposeInvalidNode: false`、`concatText: false` で基底を呼び出す   |
+| `visitAttr()`         | Vue ディレクティブの省略形を `potentialName`/`isDirective` メタデータに解決                   |
+| `detectElementType()` | PascalCase コンポーネントと Vue 組み込みコンポーネントを検出                                  |
+
+### `duplicatableAttrs`
+
+`'class'` と `'style'` を含む `Set<string>` -- `v-bind:class` と `class` が同一要素に共存できるように、重複可能な属性を定義します。
+
+## tokenize()
+
+`tokenize()` メソッドは vue-eslint-parser AST を取得するエントリーポイントです:
+
+1. `vueParse(this.rawCode)` を呼び出し、内部で `VueESLintParser.parse(vueTemplate, { parser: false })` を実行
+2. `ast.templateBody?.comments` が存在する場合、`this.state.comments` に格納して後の注入に備える
+3. `{ ast: ast.templateBody?.children ?? [], isFragment: true }` を返す
+
+`parser: false` オプションは vue-eslint-parser に `<script>` のパースをスキップするよう指示します（markuplint にとって関連するのは `<template>` ブロックのみ）。ソースに `<template>` ブロックがないか空の場合、`templateBody?.children` は `undefined` を返し、パーサーは空の配列を受け取ります。
+
+## nodeize() の詳細
+
+`nodeize()` メソッドは `originNode.type` フィールドに基づいてディスパッチします:
+
+### VText -> visitText
+
+テキストノードは `this.sliceFragment(range[0], range[1])` でソースからスライスされ、depth と parentNode と共に基底の `visitText()` メソッドに渡されます。
+
+### VExpressionContainer -> visitPsBlock
+
+`{{ expression }}` のような式コンテナは `visitPsBlock()` で擬似ブロックノードに変換されます:
+
+- `nodeName`: `'vue-expression-container'`
+- `isFragment`: `false`
+
+これにより、Vue テンプレート式は JavaScript コンテンツのパースを試みるのではなく、markuplint AST 内で不透明なブロックとして扱われます。
+
+### VElement -> visitElement
+
+要素ノードの場合、メソッドは:
+
+1. `originNode.startTag.range` から**開始タグ**トークンをスライス
+2. 要素の `name` と `namespace` と共に `visitElement()` を呼び出す
+3. `originNode.children` を子ノードとして渡す -- テンプレートルートを表すノードの場合、これは `templateBody.children`
+4. エンドタグトークンファクトリ（`createEndTagToken`）を作成 -- 要素が自己閉じの場合は `null` を返し、そうでなければ `originNode.endTag.range` からスライス
+
+## flattenNodes()
+
+`flattenNodes()` メソッドは基底の `Parser.flattenNodes()` を拡張してテンプレートコメントを注入します:
+
+1. `super.flattenNodes(nodeTree)` を呼び出して初期フラットノードリストを取得
+2. ノードリストを走査し、隣接するノードペア間のコメントを確認
+3. `prevNode.endOffset`（最初のノードの場合は `parentNode.endOffset`）と `node.startOffset` の間の各ギャップについて、そのギャップ内に範囲が収まるコメントを `this.state.comments` から検索
+4. コメントが見つかった場合、`this.visitComment()` で作成し、コメントの type に基づいて `isBogus` を設定（`HTMLBogusComment` の場合は true）
+5. `this.appendChild()` でコメントを親ノードに追加
+
+この2パスアプローチが必要な理由は、vue-eslint-parser がコメントをメインノードツリーとは別に提供するため、正しい位置にインターリーブする必要があるからです。
+
+## 属性処理（visitAttr）
+
+`visitAttr()` メソッドはまず `super.visitAttr(token)` を呼び出し、その後 Vue 固有のディレクティブ解決を適用します。
+
+### クォートセット
+
+基底パーサーは標準 HTML クォート（`"`、`'`）を処理します。Vue テンプレートは式バインディングの暗黙的な値デリミタとして `{}` も使用しますが、属性値自体は標準のクォーティングを使用します。
+
+### Vue ディレクティブ処理
+
+ディレクティブは優先順位に従って処理されます。最初にマッチするパターンが適用されます:
+
+#### `v-on` / `@`（イベントバインディング）
+
+- **パターン**: `/^(v-on:|@)([^.]+)(?:\.([^.]+))?$/i`
+- **結果**: `potentialName: 'on' + eventName.toLowerCase()`、`isDynamicValue: true`
+- **例**:
+  - `@click` -> `potentialName: 'onclick'`
+  - `v-on:click.stop` -> `potentialName: 'onclick'`
+  - `@keydown.enter` -> `potentialName: 'onkeydown'`
+
+#### `v-bind` / `:`（プロパティバインディング）
+
+- **パターン**: `/^(v-bind:|:)([^.]+)(?:\.([^.]+))?$/i`
+- **結果**（修飾子なし）: `potentialName: propName`、`isDynamicValue: true`
+- **結果**（`.attr` 修飾子）: `potentialName: propName`、`isDynamicValue: true`
+- **結果**（`.prop` / `.camel` / その他修飾子）: `isDirective: true`、`potentialName` が正規化された形式に設定
+- **`isDuplicatable`**: バインドされたプロパティが `duplicatableAttrs` に含まれる場合（class、style）、`isDuplicatable` が `true` に設定
+- **例**:
+  - `:data-attr` -> `potentialName: 'data-attr'`
+  - `v-bind:class` -> `potentialName: 'class'`、`isDuplicatable: true`
+  - `:title.attr` -> `potentialName: 'title'`
+  - `:foo.prop` -> `isDirective: true`
+
+#### `v-model`
+
+- **パターン**: `/^(v-model)(?:\.([^.]+))?$/i`
+- **結果**: `isDirective: true`
+- **例**:
+  - `v-model` -> `isDirective: true`
+  - `v-model.lazy` -> `isDirective: true`
+
+#### `v-slot` / `#`（スロット）
+
+- **パターン**: `/^(v-slot:|#)(.+)$/i`
+- **結果**: `isDirective: true`、`potentialName: 'v-slot:' + slotName`（raw name と異なる場合）
+- **例**:
+  - `#header` -> `potentialName: 'v-slot:header'`、`isDirective: true`
+  - `v-slot:default` -> `isDirective: true`
+
+#### その他の `v-` ディレクティブ
+
+- **パターン**: `v-` で始まる
+- **結果**: `isDirective: true`
+- **例**: `v-if`、`v-for`、`v-show`、`v-else`、`v-else-if`、`v-pre`、`v-cloak`、`v-once`、`v-memo`、`v-html`、`v-text`
+
+## 要素タイプ検出
+
+`detectElementType()` メソッドは Vue 固有のコンポーネント検出のためのマッチャー配列を使って `super.detectElementType(nodeName, matchers)` を呼び出します:
+
+| マッチャー          | 型     | マッチ対象                                      |
+| ------------------- | ------ | ----------------------------------------------- |
+| `'Transition'`      | String | Vue 組み込み `<Transition>` コンポーネント      |
+| `'TransitionGroup'` | String | Vue 組み込み `<TransitionGroup>` コンポーネント |
+| `'KeepAlive'`       | String | Vue 組み込み `<KeepAlive>` コンポーネント       |
+| `'Teleport'`        | String | Vue 組み込み `<Teleport>` コンポーネント        |
+| `'Suspense'`        | String | Vue 組み込み `<Suspense>` コンポーネント        |
+| `'component'`       | String | Vue 特殊要素 `<component :is="...">`            |
+| `'slot'`            | String | Vue 特殊要素 `<slot>`                           |
+| `/^[A-Z]/`          | RegExp | PascalCase のタグ名（ユーザーコンポーネント）   |
+
+タグ名がこれらのいずれかにマッチする場合、`detectElementType()` は `'authored'`（コンポーネントを示す）を返します。それ以外は標準の HTML 要素検出が適用されます:
+
+- `div`、`span`、`p` 等 -> `'html'`
+- `x-foo`、`my-element` -> `'web-component'`
+
+`<transition>`（小文字）は組み込みリストにマッチ**しない**ため標準 HTML 要素（`'html'`）として扱われますが、`<Transition>`（PascalCase）は `'authored'` として扱われることに注意してください。
+
+## afterFlattenNodes()
+
+`afterFlattenNodes()` メソッドは特定のオプションで基底実装を呼び出します:
+
+| オプション          | 値      | 効果                                                     |
+| ------------------- | ------- | -------------------------------------------------------- |
+| `exposeWhiteSpace`  | `false` | 空白のみのテキストノードは別の無効ノードとして公開しない |
+| `exposeInvalidNode` | `false` | 無効なノードは公開しない                                 |
+| `concatText`        | `false` | 隣接するテキストノードは結合しない                       |
+
+これらの設定は、Vue のテンプレートパーサーが空白やノードの妥当性を生の HTML パースとは異なる方法で処理することを反映しています。
+
+## バージョン互換性
+
+vue-eslint-parser 依存は Vue 2 と Vue 3 の両方のテンプレート構文をサポートしています。パーサーは AST レベルで Vue バージョンを区別しません -- どちらも同じ `VElement`、`VText`、`VExpressionContainer` ノードタイプを生成します。Vue 3 固有の機能（`<Teleport>` や `<Suspense>` など）はパーサーレベルの変更ではなく、要素タイプ検出を通じて処理されます。
+
+## 主要ソースファイル
+
+| ファイル                  | 用途                                                              |
+| ------------------------- | ----------------------------------------------------------------- |
+| `src/parser.ts`           | 全オーバーライドメソッドを持つ VueParser クラス                   |
+| `src/vue-parser/index.ts` | vue-eslint-parser ラッパーと型定義（ASTNode、ASTComment）         |
+| `src/index.ts`            | モジュールエントリーポイント、parser インスタンスを再エクスポート |
+| `src/index.spec.ts`       | パース、ディレクティブ、名前空間をカバーする統合テスト            |
+
+## 外部依存
+
+| 依存パッケージ             | 用途                                                             |
+| -------------------------- | ---------------------------------------------------------------- |
+| `@markuplint/ml-ast`       | AST 型定義（`MLASTParentNode`、`MLASTNodeTreeItem` 等）          |
+| `@markuplint/parser-utils` | 抽象 `Parser` クラス、`ParserError`、`Token`、`ChildToken`       |
+| `@markuplint/html-parser`  | ピア依存（直接インポートされないが、パーサーエコシステムの一部） |
+| `vue-eslint-parser`        | Vue SFC テンプレートパース（`parse`、AST 型）                    |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        mlAst["@markuplint/ml-ast\n(AST 型定義)"]
+        parserUtils["@markuplint/parser-utils\n(Parser 基底クラス)"]
+        vueEslintParser["vue-eslint-parser\n(Vue SFC トークナイザ)"]
+    end
+
+    subgraph pkg ["@markuplint/vue-parser"]
+        vueParser["VueParser"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    upstream -->|"型、パース"| vueParser
+    vueParser -->|"MLASTDocument を生成"| mlCore
+```
+
+### 上流
+
+- **`@markuplint/ml-ast`** -- パーサー全体で使用される AST 型定義
+- **`@markuplint/parser-utils`** -- `VueParser` が拡張する抽象 `Parser` クラスと `ParserError` およびユーティリティ型
+- **`vue-eslint-parser`** -- テンプレートのトークン化とツリー構築を行う基盤 Vue SFC パーサー
+
+### 下流
+
+- **`@markuplint/ml-core`** -- `VueParser` が生成する `MLASTDocument` を消費し、ルール評価のための MLDOM を構築
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,283 @@
+# @markuplint/vue-parser
+
+## Overview
+
+`@markuplint/vue-parser` is a Vue Single File Component (SFC) template parser for markuplint. It uses vue-eslint-parser to parse the `<template>` block of Vue SFCs into a vue-eslint-parser AST, then converts that AST into the unified markuplint AST format (`MLASTDocument`). The package handles Vue-specific directives (`v-bind`, `v-on`, `v-model`, `v-slot`), template expression containers (`{{ }}`), template comments, and PascalCase component detection.
+
+## Directory Structure
+
+```
+src/
+├── index.ts                — Re-exports parser
+├── parser.ts               — VueParser class extending Parser<ASTNode, State>
+├── index.spec.ts           — Integration tests for VueParser
+└── vue-parser/
+    └── index.ts            — vue-eslint-parser wrapper, ASTNode/ASTComment type exports
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        mlAst["@markuplint/ml-ast\n(AST types)"]
+        parserUtils["@markuplint/parser-utils\n(Abstract Parser class)"]
+        vueEslintParser["vue-eslint-parser\n(Vue SFC tokenizer)"]
+    end
+
+    subgraph pkg ["@markuplint/vue-parser"]
+        vueParser["VueParser\nextends Parser‹ASTNode, State›"]
+        vueParseFn["vueParse()\nvue-eslint-parser wrapper"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    mlAst -->|"AST types"| vueParser
+    parserUtils -->|"Parser base class"| vueParser
+    vueEslintParser -->|"parse()"| vueParseFn
+    vueParseFn -->|"ESLintProgram AST"| vueParser
+
+    vueParser -->|"produces MLASTDocument"| mlCore
+```
+
+## VueParser Class
+
+### Inheritance
+
+```
+Parser<ASTNode, State>  (from @markuplint/parser-utils)
+    └── VueParser        (this package)
+```
+
+### Constructor
+
+The constructor configures the parser with two arguments:
+
+| Argument        | Value                   | Purpose                                                                  |
+| --------------- | ----------------------- | ------------------------------------------------------------------------ |
+| `ParserOptions` | `{ endTagType: 'xml' }` | Vue templates use explicit closing tags (XML-style), not HTML void rules |
+| Initial State   | `{ comments: [] }`      | Empty comments array, populated during `tokenize()`                      |
+
+The `tagNameCaseSensitive` behavior is inherited from the base class and combined with Vue's `detectElementType` override to correctly handle PascalCase component names.
+
+### State Type
+
+The parser maintains internal state through the `State` type:
+
+| Field      | Type                    | Purpose                                                                                            |
+| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `comments` | `readonly ASTComment[]` | Template comments extracted from vue-eslint-parser during tokenize, injected later in flattenNodes |
+
+### Override Methods
+
+| Method                | Purpose                                                                                        |
+| --------------------- | ---------------------------------------------------------------------------------------------- |
+| `tokenize()`          | Invokes vue-eslint-parser and extracts `templateBody.children` and comments                    |
+| `parseError()`        | Converts vue-eslint-parser `SyntaxError` (with `lineNumber`/`column`) into `ParserError`       |
+| `nodeize()`           | Converts vue-eslint-parser AST nodes (VText, VElement, VExpressionContainer) to markuplint AST |
+| `flattenNodes()`      | Extends base flattening to inject template comments between sibling nodes                      |
+| `afterFlattenNodes()` | Calls base with `exposeWhiteSpace: false`, `exposeInvalidNode: false`, `concatText: false`     |
+| `visitAttr()`         | Resolves Vue directive shorthands to `potentialName`/`isDirective` metadata                    |
+| `detectElementType()` | Detects PascalCase components and Vue built-in components                                      |
+
+### `duplicatableAttrs`
+
+A `Set<string>` containing `'class'` and `'style'` -- attributes that may appear multiple times on a single element (via `v-bind:class` alongside `class`).
+
+## tokenize()
+
+The `tokenize()` method is the entry point for obtaining the vue-eslint-parser AST:
+
+1. Calls `vueParse(this.rawCode)` which invokes `VueESLintParser.parse(vueTemplate, { parser: false })`
+2. If `ast.templateBody?.comments` exists, stores them in `this.state.comments` for later injection
+3. Returns `{ ast: ast.templateBody?.children ?? [], isFragment: true }`
+
+The `parser: false` option tells vue-eslint-parser to skip `<script>` parsing (only the `<template>` block is relevant for markuplint). If the source has no `<template>` block or it is empty, `templateBody?.children` returns `undefined` and the parser receives an empty array.
+
+## nodeize() Details
+
+The `nodeize()` method dispatches based on the `originNode.type` field:
+
+### VText -> visitText
+
+Text nodes are sliced from the source using `this.sliceFragment(range[0], range[1])` and passed to the base `visitText()` method with depth and parentNode.
+
+### VExpressionContainer -> visitPsBlock
+
+Expression containers like `{{ expression }}` are converted to pseudo-block nodes via `visitPsBlock()`:
+
+- `nodeName`: `'vue-expression-container'`
+- `isFragment`: `false`
+
+This treats Vue template expressions as opaque blocks in the markuplint AST rather than attempting to parse their JavaScript content.
+
+### VElement -> visitElement
+
+For element nodes, the method:
+
+1. Slices the **start tag** token from `originNode.startTag.range`
+2. Calls `visitElement()` with the element's `name` and `namespace`
+3. Passes `originNode.children` as child nodes -- these are `templateBody.children` when the node represents the template root
+4. Creates an end tag token factory (`createEndTagToken`) that returns `null` if the element is self-closing, otherwise slices from `originNode.endTag.range`
+
+## flattenNodes()
+
+The `flattenNodes()` method extends the base `Parser.flattenNodes()` to inject template comments:
+
+1. Calls `super.flattenNodes(nodeTree)` to get the initial flat node list
+2. Iterates through the node list, checking for comments between each pair of adjacent nodes
+3. For each gap between `prevNode.endOffset` (or `parentNode.endOffset` for the first node) and `node.startOffset`, searches `this.state.comments` for a comment whose range falls within that gap
+4. When a comment is found, creates it via `this.visitComment()` with `isBogus` set based on the comment's type (`HTMLBogusComment` vs standard)
+5. Appends the comment to the parent node via `this.appendChild()`
+
+This two-pass approach is necessary because vue-eslint-parser provides comments separately from the main node tree, and they must be interleaved at the correct positions.
+
+## Attribute Processing (visitAttr)
+
+The `visitAttr()` method calls `super.visitAttr(token)` first, then applies Vue-specific directive resolution.
+
+### Quote Set
+
+The base parser handles standard HTML quotes (`"`, `'`). Vue templates also use `{}` as implicit value delimiters for expression bindings, though the attribute value itself uses standard quoting.
+
+### Vue Directive Processing
+
+Directives are processed in priority order. The first matching pattern wins:
+
+#### `v-on` / `@` (Event Binding)
+
+- **Pattern**: `/^(v-on:|@)([^.]+)(?:\.([^.]+))?$/i`
+- **Result**: `potentialName: 'on' + eventName.toLowerCase()`, `isDynamicValue: true`
+- **Examples**:
+  - `@click` -> `potentialName: 'onclick'`
+  - `v-on:click.stop` -> `potentialName: 'onclick'`
+  - `@keydown.enter` -> `potentialName: 'onkeydown'`
+
+#### `v-bind` / `:` (Property Binding)
+
+- **Pattern**: `/^(v-bind:|:)([^.]+)(?:\.([^.]+))?$/i`
+- **Result** (no modifier): `potentialName: propName`, `isDynamicValue: true`
+- **Result** (`.attr` modifier): `potentialName: propName`, `isDynamicValue: true`
+- **Result** (`.prop` / `.camel` / other modifiers): `isDirective: true`, `potentialName` set to normalized form
+- **`isDuplicatable`**: If the bound property is in `duplicatableAttrs` (class, style), `isDuplicatable` is set to `true`
+- **Examples**:
+  - `:data-attr` -> `potentialName: 'data-attr'`
+  - `v-bind:class` -> `potentialName: 'class'`, `isDuplicatable: true`
+  - `:title.attr` -> `potentialName: 'title'`
+  - `:foo.prop` -> `isDirective: true`
+
+#### `v-model`
+
+- **Pattern**: `/^(v-model)(?:\.([^.]+))?$/i`
+- **Result**: `isDirective: true`
+- **Examples**:
+  - `v-model` -> `isDirective: true`
+  - `v-model.lazy` -> `isDirective: true`
+
+#### `v-slot` / `#` (Slot)
+
+- **Pattern**: `/^(v-slot:|#)(.+)$/i`
+- **Result**: `isDirective: true`, `potentialName: 'v-slot:' + slotName` (if different from raw name)
+- **Examples**:
+  - `#header` -> `potentialName: 'v-slot:header'`, `isDirective: true`
+  - `v-slot:default` -> `isDirective: true`
+
+#### Other `v-` Directives
+
+- **Pattern**: Starts with `v-`
+- **Result**: `isDirective: true`
+- **Examples**: `v-if`, `v-for`, `v-show`, `v-else`, `v-else-if`, `v-pre`, `v-cloak`, `v-once`, `v-memo`, `v-html`, `v-text`
+
+## Element Type Detection
+
+The `detectElementType()` method calls `super.detectElementType(nodeName, matchers)` with an array of matchers for Vue-specific component detection:
+
+| Matcher             | Type   | Matches                                     |
+| ------------------- | ------ | ------------------------------------------- |
+| `'Transition'`      | String | Vue built-in `<Transition>` component       |
+| `'TransitionGroup'` | String | Vue built-in `<TransitionGroup>` component  |
+| `'KeepAlive'`       | String | Vue built-in `<KeepAlive>` component        |
+| `'Teleport'`        | String | Vue built-in `<Teleport>` component         |
+| `'Suspense'`        | String | Vue built-in `<Suspense>` component         |
+| `'component'`       | String | Vue special element `<component :is="...">` |
+| `'slot'`            | String | Vue special element `<slot>`                |
+| `/^[A-Z]/`          | RegExp | Any PascalCase tag name (user components)   |
+
+When a tag name matches any of these, `detectElementType()` returns `'authored'` (indicating a component). Otherwise, standard HTML element detection applies:
+
+- `div`, `span`, `p` etc. -> `'html'`
+- `x-foo`, `my-element` -> `'web-component'`
+
+Note that `<transition>` (lowercase) does **not** match the built-in list and is treated as a standard HTML element (`'html'`), while `<Transition>` (PascalCase) is treated as `'authored'`.
+
+## afterFlattenNodes()
+
+The `afterFlattenNodes()` method calls the base implementation with specific options:
+
+| Option              | Value   | Effect                                                               |
+| ------------------- | ------- | -------------------------------------------------------------------- |
+| `exposeWhiteSpace`  | `false` | Whitespace-only text nodes are not exposed as separate invalid nodes |
+| `exposeInvalidNode` | `false` | Invalid nodes are not exposed                                        |
+| `concatText`        | `false` | Adjacent text nodes are not concatenated                             |
+
+These settings reflect that Vue's template parser handles whitespace and node validity differently from raw HTML parsing.
+
+## Version Compatibility
+
+The vue-eslint-parser dependency supports both Vue 2 and Vue 3 template syntax. The parser does not distinguish between Vue versions at the AST level -- both produce the same `VElement`, `VText`, and `VExpressionContainer` node types. Vue 3-specific features like `<Teleport>` and `<Suspense>` are handled through element type detection rather than parser-level changes.
+
+## Key Source Files
+
+| File                      | Purpose                                                              |
+| ------------------------- | -------------------------------------------------------------------- |
+| `src/parser.ts`           | VueParser class with all override methods                            |
+| `src/vue-parser/index.ts` | vue-eslint-parser wrapper and type definitions (ASTNode, ASTComment) |
+| `src/index.ts`            | Module entry point, re-exports parser instance                       |
+| `src/index.spec.ts`       | Integration tests covering parsing, directives, namespaces           |
+
+## External Dependencies
+
+| Dependency                 | Purpose                                                              |
+| -------------------------- | -------------------------------------------------------------------- |
+| `@markuplint/ml-ast`       | AST type definitions (`MLASTParentNode`, `MLASTNodeTreeItem`, etc.)  |
+| `@markuplint/parser-utils` | Abstract `Parser` class, `ParserError`, `Token`, `ChildToken`        |
+| `@markuplint/html-parser`  | Peer dependency (not directly imported but part of parser ecosystem) |
+| `vue-eslint-parser`        | Vue SFC template parsing (`parse`, AST types)                        |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        mlAst["@markuplint/ml-ast\n(AST types)"]
+        parserUtils["@markuplint/parser-utils\n(Parser base class)"]
+        vueEslintParser["vue-eslint-parser\n(Vue SFC tokenizer)"]
+    end
+
+    subgraph pkg ["@markuplint/vue-parser"]
+        vueParser["VueParser"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    upstream -->|"types, parsing"| vueParser
+    vueParser -->|"produces MLASTDocument"| mlCore
+```
+
+### Upstream
+
+- **`@markuplint/ml-ast`** -- AST type definitions used throughout the parser
+- **`@markuplint/parser-utils`** -- Abstract `Parser` class that `VueParser` extends, plus `ParserError` and utility types
+- **`vue-eslint-parser`** -- The underlying Vue SFC parser that performs template tokenization and tree construction
+
+### Downstream
+
+- **`@markuplint/ml-core`** -- Consumes the `MLASTDocument` produced by `VueParser` and constructs the MLDOM for rule evaluation
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/vue-parser@4.6.20...@markuplint/vue-parser@4.6.21) (2025-08-24)
+## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/vue-parser@4.6.22...@markuplint/vue-parser@4.6.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/vue-parser
 
+## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/vue-parser@4.6.21...@markuplint/vue-parser@4.6.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/vue-parser
 
+## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/vue-parser@4.6.20...@markuplint/vue-parser@4.6.21) (2025-08-24)
 
+**Note:** Version bump only for package @markuplint/vue-parser
 
 ## [4.6.20](https://github.com/markuplint/markuplint/compare/@markuplint/vue-parser@4.6.19...@markuplint/vue-parser@4.6.20) (2025-08-13)
 

package/SKILL.md

@@ -0,0 +1,137 @@
+---
+description: Maintenance tasks for @markuplint/vue-parser
+globs:
+  - packages/@markuplint/vue-parser/src/**/*.ts
+alwaysApply: false
+---
+
+# vue-parser-maintenance
+
+Perform maintenance tasks for `@markuplint/vue-parser`: add Vue directives, modify element type
+detection, update vue-eslint-parser version support, and fix comment injection.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                            | Description                                      |
+| ------------------------------- | ------------------------------------------------ |
+| `add-directive`                 | Add or modify a Vue directive in visitAttr()     |
+| `modify-element-type-detection` | Update detectElementType() matchers              |
+| `update-vue-version-support`    | Handle vue-eslint-parser API changes             |
+| `fix-comment-injection`         | Fix template comment injection in flattenNodes() |
+
+If omitted, defaults to `add-directive`.
+
+## 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:
+
+- `ARCHITECTURE.md` -- Package overview, directive processing, and element type detection
+- `src/parser.ts` -- VueParser class (source of truth for all override methods)
+
+## Task: add-directive
+
+Add or modify a Vue directive in `visitAttr()`. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Understand the directive
+
+1. Read `src/parser.ts` and find the `visitAttr()` method
+2. Identify where in the priority chain the new directive should be processed
+3. Determine whether the directive needs `potentialName`, `isDirective`, or `isDynamicValue`
+
+### Step 2: Add the directive pattern
+
+1. Create a new regex block following the existing pattern (scoped block with destructuring)
+2. Use `attr.name.raw.match()` to extract the directive prefix and value
+3. Set the appropriate metadata:
+   - `potentialName` — maps the directive to an equivalent HTML attribute name
+   - `isDirective` — marks as a Vue-only directive with no HTML equivalent
+   - `isDynamicValue` — indicates the attribute value is a JavaScript expression
+4. Check if the attribute should be in `duplicatableAttrs` (e.g., class, style)
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/vue-parser`
+2. Add test cases to `src/index.spec.ts` covering:
+   - The directive with its full form (e.g., `v-bind:prop`)
+   - The shorthand form if applicable (e.g., `:prop`)
+   - Edge cases with modifiers (e.g., `.stop`, `.lazy`)
+3. Test: `yarn test --scope @markuplint/vue-parser`
+
+## Task: modify-element-type-detection
+
+Update `detectElementType()` matchers. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Understand current matchers
+
+1. Read the `detectElementType()` method in `src/parser.ts`
+2. Review the matcher array: string literals for built-in components, regex for PascalCase
+
+### Step 2: Make the change
+
+1. To add a new built-in component: add the component name as a string to the matcher array
+2. To add a new pattern: add a regex to the matcher array
+3. Components matching any entry return `'authored'` element type
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/vue-parser`
+2. Add test cases to the `elementType` test block in `src/index.spec.ts`
+3. Test: `yarn test --scope @markuplint/vue-parser`
+
+## Task: update-vue-version-support
+
+Handle vue-eslint-parser API changes. Follow recipe #3 in `docs/maintenance.md`.
+
+### Step 1: Understand the change
+
+1. Read `src/vue-parser/index.ts` — the wrapper around vue-eslint-parser
+2. Check the vue-eslint-parser changelog for breaking changes
+3. Verify the `ASTNode` and `ASTComment` type exports still match
+
+### Step 2: Make the change
+
+1. Update `vueParse()` if the `parse()` API signature changed
+2. Update type exports (`ASTNode`, `ASTComment`, `VueTokens`) if AST types changed
+3. Update `tokenize()` in `src/parser.ts` if `templateBody` structure changed
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/vue-parser`
+2. Test: `yarn test --scope @markuplint/vue-parser`
+3. Test with real Vue SFC files to ensure correct parsing
+
+## Task: fix-comment-injection
+
+Fix template comment injection in `flattenNodes()`. Follow recipe #4 in `docs/maintenance.md`.
+
+### Step 1: Understand the issue
+
+1. Read the `flattenNodes()` method in `src/parser.ts`
+2. Understand the two-pass approach: first flatten, then inject comments
+3. Check how `this.state.comments` is populated in `tokenize()`
+
+### Step 2: Fix the injection logic
+
+1. Verify the comment range check: `lastOffset <= comment.range[0] && comment.range[1] <= node.startOffset`
+2. Verify `this.visitComment()` is called with the correct `isBogus` flag
+3. Verify `this.appendChild()` correctly attaches the comment to the parent
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/vue-parser`
+2. Test with Vue templates containing HTML comments (`<!-- -->`), bogus comments (`<!...>`), and mixed content
+3. Test: `yarn test --scope @markuplint/vue-parser`
+
+## Rules
+
+1. **Use vue-eslint-parser** for all template parsing — never parse Vue templates manually.
+2. **Use `potentialName`** for directives that map to HTML attributes (e.g., `@click` -> `onclick`).
+3. **Use `isDirective: true`** for directives with no HTML equivalent (e.g., `v-if`, `v-for`).
+4. **Test with `nodeListToDebugMaps`** — this is the standard assertion pattern for parser tests.
+5. **Add JSDoc comments** to all new public methods and properties.
+6. **Preserve directive priority order** in `visitAttr()` — `v-on` before `v-bind` before `v-model` before `v-slot` before generic `v-`.

package/docs/maintenance.ja.md

@@ -0,0 +1,203 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                    | 説明                   |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/vue-parser` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/vue-parser`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/vue-parser` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/vue-parser`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル  | カバレッジ                                                                     |
+| --------------- | ------------------------------------------------------------------------------ |
+| `index.spec.ts` | VueParser 統合テスト（パース、ディレクティブ、名前空間、要素タイプ、コメント） |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from '@markuplint/vue-parser';
+
+const doc = parser.parse('<template><div class="foo">text</div></template>');
+const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
+expect(debugMaps).toStrictEqual([
+  // 期待されるデバッグ出力
+]);
+```
+
+属性メタデータのテスト（ディレクティブ、potentialName、isDynamicValue）:
+
+```ts
+const doc = parser.parse('<template><div v-bind:title="val"></div></template>');
+expect(doc.nodeList[0].attributes[0].potentialName).toBe('title');
+expect(doc.nodeList[0].attributes[0].isDynamicValue).toBeTruthy();
+```
+
+要素タイプのテスト:
+
+```ts
+const doc = parser.parse('<template><MyComponent/></template>');
+expect(doc.nodeList[0].elementType).toBe('authored');
+```
+
+## レシピ
+
+### 1. Vue ディレクティブの追加・変更
+
+1. `src/parser.ts` を読み、`visitAttr()` メソッドを見つける
+2. 優先チェーン内の正しい位置を特定:
+   - `v-on` / `@`（イベントバインディング） — 最初
+   - `v-bind` / `:`（プロパティバインディング） — 2番目
+   - `v-model` — 3番目
+   - `v-slot` / `#` — 4番目
+   - 汎用 `v-*` — 最後（キャッチオール）
+3. 正規表現パターンを持つ新しいスコープブロックを作成:
+   ```ts
+   {
+     const [, directive, name] = attr.name.raw.match(/^(v-newdir:|shorthand)(.+)$/i) ?? [];
+     if (directive && name) {
+       return {
+         ...attr,
+         potentialName: name, // HTML 属性にマッピングする場合
+         isDirective: true as const, // Vue 専用の場合
+         isDynamicValue: true as const, // 値が JavaScript の場合
+       };
+     }
+   }
+   ```
+4. ビルド: `yarn build --scope @markuplint/vue-parser`
+5. `src/index.spec.ts` にテストを追加:
+   - 完全形: `v-newdir:value`
+   - 省略形（該当する場合）
+   - 修飾子付き（該当する場合）
+6. テスト: `yarn test --scope @markuplint/vue-parser`
+
+### 2. 要素タイプ検出の変更
+
+1. `src/parser.ts` を読み、`detectElementType()` メソッドを見つける
+2. マッチャー配列は以下をサポート:
+   - **文字列リテラル** — 完全一致（例: `'Transition'`、`'component'`、`'slot'`）
+   - **RegExp** — パターンマッチ（例: PascalCase 用の `/^[A-Z]/`）
+3. 新しい Vue 組み込みコンポーネントを追加するには:
+   ```ts
+   detectElementType(nodeName: string) {
+     return super.detectElementType(nodeName, [
+       // Built-in components
+       'Transition',
+       'TransitionGroup',
+       'KeepAlive',
+       'Teleport',
+       'Suspense',
+       'NewBuiltIn',  // <-- ここに追加
+       // Special elements
+       'component',
+       'slot',
+       // Backward compatibility
+       /^[A-Z]/,
+     ]);
+   }
+   ```
+4. ビルドとテスト: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+5. `src/index.spec.ts` の `elementType` テストブロックにテストケースを追加
+
+### 3. vue-eslint-parser バージョンサポートの更新
+
+1. `src/vue-parser/index.ts` を読む — vue-eslint-parser のラッパー
+2. vue-eslint-parser のリリースノートで破壊的変更を確認
+3. 主な統合ポイント:
+   - `VueESLintParser.parse(vueTemplate, { parser: false })` — メインのパース呼び出し
+   - `ast.templateBody?.children` — テンプレートの子ノード
+   - `ast.templateBody?.comments` — テンプレートのコメント
+   - `VueESLintParser.AST.VElement` / `VText` / `VExpressionContainer` — ノードタイプ
+4. AST 型が変更された場合、型エクスポートを更新:
+   ```ts
+   export type ASTNode =
+     | VueESLintParser.AST.VElement
+     | VueESLintParser.AST.VText
+     | VueESLintParser.AST.VExpressionContainer;
+   ```
+5. ビルドとテスト: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+
+### 4. テンプレートコメント注入の修正
+
+1. `src/parser.ts` の `flattenNodes()` メソッドを読む
+2. コメント注入のロジック:
+   - コメントは `tokenize()` 中に `this.state.comments` に格納される
+   - フラット化中、隣接するノードペアごとにコメントがその間にあるか確認
+   - 範囲チェック: `lastOffset <= comment.range[0] && comment.range[1] <= node.startOffset`
+3. よくある問題:
+   - コメントが注入されない: 範囲チェックがギャップを正しくカバーしているか確認
+   - コメントが間違った位置にある: `lastOffset` の計算を確認（`prevNode?.endOffset ?? node.parentNode?.endOffset ?? 0`）
+   - ボーガスコメント検出: `betweenComment.type === 'HTMLBogusComment'` を検証
+4. ビルドとテスト: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+
+## 上流影響チェックリスト
+
+上流パッケージへの変更がこのパッケージに影響を与える可能性があります:
+
+| パッケージ                 | 影響                                                                     |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `@markuplint/parser-utils` | 基底 `Parser` クラスの変更が全オーバーライドメソッドに影響する可能性あり |
+| `@markuplint/ml-ast`       | AST 型の変更が nodeize() の戻り値の型の更新を必要とする可能性あり        |
+| `vue-eslint-parser`        | AST 構造の変更が tokenize()、nodeize()、型の更新を必要とする可能性あり   |
+
+上流パッケージが変更された場合、以下を実行:
+
+```shell
+yarn test --scope @markuplint/vue-parser
+```
+
+## トラブルシューティング
+
+### Vue ディレクティブが認識されない
+
+**症状:** `v-custom` のような Vue ディレクティブが `isDirective: true` としてマークされず、通常の HTML 属性として扱われる。
+
+**原因:** `visitAttr()` でディレクティブパターンがマッチしないか、新しいディレクティブブロックが汎用 `v-*` キャッチオールの後に配置されている。
+
+**解決策:**
+
+1. ディレクティブブロックの正規表現パターンを確認 — 完全な属性名にマッチすることを確認
+2. ブロックが `visitAttr()` 末尾の汎用 `v-*` キャッチオールの前に配置されていることを確認
+3. 返却オブジェクトに `isDirective: true as const` が含まれていることを検証
+
+### テンプレートコメントが AST に含まれていない
+
+**症状:** Vue テンプレート内の HTML コメント（`<!-- ... -->`）がパースされたノードリストに存在しない。
+
+**原因:** `flattenNodes()` でコメントが注入されていないか、`tokenize()` でキャプチャされていない。
+
+**解決策:**
+
+1. `tokenize()` を確認 — `ast.templateBody?.comments` が `this.state.comments` に格納されていることを検証
+2. `flattenNodes()` を確認 — 範囲チェックロジックが隣接ノード間のコメントを見つけていることを検証
+3. 特定のコメント位置でテストケースを追加し、`nodeListToDebugMaps` 出力を確認
+
+### PascalCase コンポーネントが 'authored' として検出されない
+
+**症状:** `<MyComponent>` のようなコンポーネントが `'authored'` ではなく `elementType: 'html'` となる。
+
+**原因:** `detectElementType()` 内の `/^[A-Z]/` 正規表現がマッチしていないか、マッチャー配列が誤って構成されている。
+
+**解決策:**
+
+1. コンポーネント名が大文字で始まることを確認
+2. `/^[A-Z]/` 正規表現がマッチャー配列に存在することを検証
+3. `<component>` や `<slot>` のような小文字の Vue 組み込みは正規表現ではなく文字列でマッチされることに注意
+
+### SyntaxError が正しく報告されない
+
+**症状:** Vue テンプレートの構文エラーが `ParserError` を生成する代わりにプロセスをクラッシュさせる。
+
+**原因:** `parseError()` メソッドがエラーをキャッチしていないか、エラーオブジェクトに `lineNumber`/`column` プロパティがない。
+
+**解決策:**
+
+1. `parseError()` を確認 — `instanceof SyntaxError` と `'lineNumber' in error` のチェックを検証
+2. vue-eslint-parser のエラーには `lineNumber`（1ベース）と `column`（0ベース）が含まれる
+3. フォールバックの `super.parseError(error)` は非 SyntaxError ケースを処理する

package/docs/maintenance.md

@@ -0,0 +1,203 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                     | Description            |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/vue-parser` | Build this package     |
+| `yarn dev --scope @markuplint/vue-parser`   | Watch mode build       |
+| `yarn clean --scope @markuplint/vue-parser` | Remove build artifacts |
+| `yarn test --scope @markuplint/vue-parser`  | Run tests              |
+
+## Testing
+
+Test files follow the `*.spec.ts` naming convention and are located in the `src/` directory:
+
+| Test File       | Coverage                                                                               |
+| --------------- | -------------------------------------------------------------------------------------- |
+| `index.spec.ts` | VueParser integration tests (parsing, directives, namespaces, element types, comments) |
+
+The primary testing pattern uses `nodeListToDebugMaps` for snapshot-style assertions:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from '@markuplint/vue-parser';
+
+const doc = parser.parse('<template><div class="foo">text</div></template>');
+const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
+expect(debugMaps).toStrictEqual([
+  // expected debug output
+]);
+```
+
+To test attribute metadata (directives, potentialName, isDynamicValue):
+
+```ts
+const doc = parser.parse('<template><div v-bind:title="val"></div></template>');
+expect(doc.nodeList[0].attributes[0].potentialName).toBe('title');
+expect(doc.nodeList[0].attributes[0].isDynamicValue).toBeTruthy();
+```
+
+To test element types:
+
+```ts
+const doc = parser.parse('<template><MyComponent/></template>');
+expect(doc.nodeList[0].elementType).toBe('authored');
+```
+
+## Recipes
+
+### 1. Adding or Modifying a Vue Directive
+
+1. Read `src/parser.ts` and find the `visitAttr()` method
+2. Identify the correct position in the priority chain:
+   - `v-on` / `@` (event binding) — first
+   - `v-bind` / `:` (property binding) — second
+   - `v-model` — third
+   - `v-slot` / `#` — fourth
+   - Generic `v-*` — last (catch-all)
+3. Create a new scoped block with a regex pattern:
+   ```ts
+   {
+     const [, directive, name] = attr.name.raw.match(/^(v-newdir:|shorthand)(.+)$/i) ?? [];
+     if (directive && name) {
+       return {
+         ...attr,
+         potentialName: name, // if it maps to an HTML attribute
+         isDirective: true as const, // if it's Vue-only
+         isDynamicValue: true as const, // if value is JavaScript
+       };
+     }
+   }
+   ```
+4. Build: `yarn build --scope @markuplint/vue-parser`
+5. Add tests to `src/index.spec.ts`:
+   - Full form: `v-newdir:value`
+   - Shorthand form if applicable
+   - With modifiers if applicable
+6. Test: `yarn test --scope @markuplint/vue-parser`
+
+### 2. Modifying Element Type Detection
+
+1. Read `src/parser.ts` and find the `detectElementType()` method
+2. The matcher array supports:
+   - **String literals** — exact match (e.g., `'Transition'`, `'component'`, `'slot'`)
+   - **RegExp** — pattern match (e.g., `/^[A-Z]/` for PascalCase)
+3. To add a new Vue built-in component:
+   ```ts
+   detectElementType(nodeName: string) {
+     return super.detectElementType(nodeName, [
+       // Built-in components
+       'Transition',
+       'TransitionGroup',
+       'KeepAlive',
+       'Teleport',
+       'Suspense',
+       'NewBuiltIn',  // <-- add here
+       // Special elements
+       'component',
+       'slot',
+       // Backward compatibility
+       /^[A-Z]/,
+     ]);
+   }
+   ```
+4. Build and test: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+5. Add test cases to the `elementType` test block in `src/index.spec.ts`
+
+### 3. Updating vue-eslint-parser Version Support
+
+1. Read `src/vue-parser/index.ts` — this is the wrapper around vue-eslint-parser
+2. Check the vue-eslint-parser release notes for breaking changes
+3. Key integration points:
+   - `VueESLintParser.parse(vueTemplate, { parser: false })` — main parse call
+   - `ast.templateBody?.children` — template child nodes
+   - `ast.templateBody?.comments` — template comments
+   - `VueESLintParser.AST.VElement` / `VText` / `VExpressionContainer` — node types
+4. Update type exports if AST types changed:
+   ```ts
+   export type ASTNode =
+     | VueESLintParser.AST.VElement
+     | VueESLintParser.AST.VText
+     | VueESLintParser.AST.VExpressionContainer;
+   ```
+5. Build and test: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+
+### 4. Fixing Template Comment Injection
+
+1. Read the `flattenNodes()` method in `src/parser.ts`
+2. The comment injection logic:
+   - Comments are stored in `this.state.comments` during `tokenize()`
+   - During flattening, for each pair of adjacent nodes, the method checks if a comment falls between them
+   - The range check: `lastOffset <= comment.range[0] && comment.range[1] <= node.startOffset`
+3. Common issues:
+   - Comment not injected: check that the range check covers the gap correctly
+   - Comment at wrong position: check `lastOffset` calculation (`prevNode?.endOffset ?? node.parentNode?.endOffset ?? 0`)
+   - Bogus comment detection: verify `betweenComment.type === 'HTMLBogusComment'`
+4. Build and test: `yarn build --scope @markuplint/vue-parser && yarn test --scope @markuplint/vue-parser`
+
+## Upstream Impact Checklist
+
+Changes to upstream packages can affect this package:
+
+| Package                    | Impact                                                                        |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `@markuplint/parser-utils` | Base `Parser` class changes may affect all override methods                   |
+| `@markuplint/ml-ast`       | AST type changes may require updates to nodeize() return types                |
+| `vue-eslint-parser`        | AST structure changes may require updates to tokenize(), nodeize(), and types |
+
+When upstream packages change, run:
+
+```shell
+yarn test --scope @markuplint/vue-parser
+```
+
+## Troubleshooting
+
+### Vue directive is not recognized
+
+**Symptom:** A Vue directive like `v-custom` is treated as a regular HTML attribute instead of being marked as `isDirective: true`.
+
+**Cause:** The directive pattern does not match in `visitAttr()`, or the new directive block is placed after the generic `v-*` catch-all.
+
+**Solution:**
+
+1. Check the regex pattern in your directive block — ensure it matches the full attribute name
+2. Ensure the block is placed before the generic `v-*` catch-all at the end of `visitAttr()`
+3. Verify the return object includes `isDirective: true as const`
+
+### Template comments are missing from the AST
+
+**Symptom:** HTML comments (`<!-- ... -->`) in the Vue template are not present in the parsed node list.
+
+**Cause:** The comments are not being injected during `flattenNodes()`, or they are not captured during `tokenize()`.
+
+**Solution:**
+
+1. Check `tokenize()` — verify `ast.templateBody?.comments` is being stored in `this.state.comments`
+2. Check `flattenNodes()` — verify the range check logic finds the comment between adjacent nodes
+3. Add a test case with the specific comment position and check `nodeListToDebugMaps` output
+
+### PascalCase component not detected as 'authored'
+
+**Symptom:** A component like `<MyComponent>` has `elementType: 'html'` instead of `'authored'`.
+
+**Cause:** The `/^[A-Z]/` regex in `detectElementType()` is not matching, or the matcher array is misconfigured.
+
+**Solution:**
+
+1. Check that the component name starts with an uppercase letter
+2. Verify the `/^[A-Z]/` regex is still present in the matcher array
+3. Note that lowercase Vue built-ins like `<component>` and `<slot>` are matched by string, not regex
+
+### SyntaxError not properly reported
+
+**Symptom:** Vue template syntax errors crash the process instead of producing a `ParserError`.
+
+**Cause:** The `parseError()` method is not catching the error, or the error object does not have `lineNumber`/`column` properties.
+
+**Solution:**
+
+1. Check `parseError()` — verify the `instanceof SyntaxError` and `'lineNumber' in error` checks
+2. vue-eslint-parser errors include `lineNumber` (1-based) and `column` (0-based)
+3. The fallback `super.parseError(error)` handles non-SyntaxError cases

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module
+ * Vue Single File Component (SFC) template parser for markuplint. Provides a parser
+ * that transforms Vue template syntax into markuplint's AST using the vue-eslint-parser,
+ * handling Vue-specific directives such as `v-bind`, `v-on`, `v-model`, and `v-slot`.
+ */
 export { parser } from './parser.js';

package/lib/index.js

@@ -1 +1,7 @@
+/**
+ * @module
+ * Vue Single File Component (SFC) template parser for markuplint. Provides a parser
+ * that transforms Vue template syntax into markuplint's AST using the vue-eslint-parser,
+ * handling Vue-specific directives such as `v-bind`, `v-on`, `v-model`, and `v-slot`.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -5,6 +5,12 @@ import { ParserError, Parser } from '@markuplint/parser-utils';
 type State = {
     comments: readonly ASTComment[];
 };
+/**
+ * Parser implementation for Vue SFC templates.
+ * Extends the base Parser to handle Vue elements, text nodes, expression containers,
+ * directives (`v-bind`, `v-on`, `v-model`, `v-slot`), and template comments.
+ * Recognizes Vue built-in components and PascalCase user components.
+ */
 declare class VueParser extends Parser<ASTNode, State> {
     readonly duplicatableAttrs: Set<string>;
     constructor();
@@ -13,9 +19,35 @@ declare class VueParser extends Parser<ASTNode, State> {
         isFragment: boolean;
     };
     parseError(error: any): ParserError;
+    /**
+     * Converts a Vue AST node into markuplint node tree items.
+     * Handles VText (text nodes), VExpressionContainer (template expressions),
+     * and VElement (elements with start/end tags and children).
+     *
+     * @param originNode - The Vue AST node to convert
+     * @param parentNode - The parent node in the markuplint tree, or null for root nodes
+     * @param depth - The nesting depth of the node
+     * @returns An array of markuplint node tree items
+     */
     nodeize(originNode: ASTNode, parentNode: MLASTParentNode | null, depth: number): readonly MLASTNodeTreeItem[];
+    /**
+     * Extends the base flattening to inject Vue template comments between sibling nodes.
+     * Comments from the vue-eslint-parser are inserted at the correct positions
+     * based on their source offsets relative to adjacent nodes.
+     *
+     * @param nodeTree - The hierarchical node tree to flatten
+     * @returns A flat list of nodes including interleaved comments
+     */
     flattenNodes(nodeTree: readonly MLASTNodeTreeItem[]): MLASTNodeTreeItem[];
     afterFlattenNodes(nodeList: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Visits an attribute token and resolves Vue-specific directive shorthands.
+     * Handles `v-on` / `@` (event binding), `v-bind` / `:` (property binding),
+     * `v-model`, `v-slot` / `#`, and other `v-` prefixed directives.
+     *
+     * @param token - The token representing the attribute
+     * @returns The parsed attribute node with Vue-specific metadata
+     */
     visitAttr(token: Token): (import("@markuplint/ml-ast").MLASTHTMLAttr & {
         __rightText?: string;
     }) | (import("@markuplint/ml-ast").MLASTSpreadAttr & {

package/lib/parser.js

@@ -1,5 +1,11 @@
 import { ParserError, Parser } from '@markuplint/parser-utils';
 import { vueParse } from './vue-parser/index.js';
+/**
+ * Parser implementation for Vue SFC templates.
+ * Extends the base Parser to handle Vue elements, text nodes, expression containers,
+ * directives (`v-bind`, `v-on`, `v-model`, `v-slot`), and template comments.
+ * Recognizes Vue built-in components and PascalCase user components.
+ */
 class VueParser extends Parser {
     constructor() {
         super({
@@ -29,6 +35,16 @@ class VueParser extends Parser {
         }
         return super.parseError(error);
     }
+    /**
+     * Converts a Vue AST node into markuplint node tree items.
+     * Handles VText (text nodes), VExpressionContainer (template expressions),
+     * and VElement (elements with start/end tags and children).
+     *
+     * @param originNode - The Vue AST node to convert
+     * @param parentNode - The parent node in the markuplint tree, or null for root nodes
+     * @param depth - The nesting depth of the node
+     * @returns An array of markuplint node tree items
+     */
     nodeize(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, parentNode, depth) {
@@ -74,6 +90,14 @@ class VueParser extends Parser {
             }
         }
     }
+    /**
+     * Extends the base flattening to inject Vue template comments between sibling nodes.
+     * Comments from the vue-eslint-parser are inserted at the correct positions
+     * based on their source offsets relative to adjacent nodes.
+     *
+     * @param nodeTree - The hierarchical node tree to flatten
+     * @returns A flat list of nodes including interleaved comments
+     */
     flattenNodes(nodeTree) {
         const nodeList = super.flattenNodes(nodeTree);
         const newNodeList = [];
@@ -111,6 +135,14 @@ class VueParser extends Parser {
             concatText: false,
         });
     }
+    /**
+     * Visits an attribute token and resolves Vue-specific directive shorthands.
+     * Handles `v-on` / `@` (event binding), `v-bind` / `:` (property binding),
+     * `v-model`, `v-slot` / `#`, and other `v-` prefixed directives.
+     *
+     * @param token - The token representing the attribute
+     * @returns The parsed attribute node with Vue-specific metadata
+     */
     visitAttr(token) {
         const attr = super.visitAttr(token);
         if (attr.type === 'spread') {

package/lib/vue-parser/index.d.ts

@@ -1,5 +1,14 @@
 import * as VueESLintParser from 'vue-eslint-parser';
+/** The top-level AST produced by vue-eslint-parser, containing template body and comments. */
 export type VueTokens = VueESLintParser.AST.ESLintProgram;
+/**
+ * Parses a Vue SFC template string into a vue-eslint-parser AST.
+ *
+ * @param vueTemplate - The raw Vue template source code
+ * @returns The parsed AST program node containing the template body
+ */
 export declare function vueParse(vueTemplate: string): VueTokens;
+/** Union of AST node types that can appear as children in a Vue template. */
 export type ASTNode = VueESLintParser.AST.VElement | VueESLintParser.AST.VText | VueESLintParser.AST.VExpressionContainer;
+/** Represents a comment token in the Vue template AST with location information. */
 export type ASTComment = VueESLintParser.AST.Token & VueESLintParser.AST.HasLocation;

package/lib/vue-parser/index.js

@@ -1,4 +1,10 @@
 import * as VueESLintParser from 'vue-eslint-parser';
+/**
+ * Parses a Vue SFC template string into a vue-eslint-parser AST.
+ *
+ * @param vueTemplate - The raw Vue template source code
+ * @returns The parsed AST program node containing the template body
+ */
 export function vueParse(vueTemplate) {
     const ast = VueESLintParser.parse(vueTemplate, { parser: false });
     return ast;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/vue-parser",
-	"version": "4.6.21",
+	"version": "4.6.23",
 	"description": "Vue parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -21,10 +21,10 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.21",
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/parser-utils": "4.8.9",
+		"@markuplint/html-parser": "4.6.23",
+		"@markuplint/ml-ast": "4.4.11",
+		"@markuplint/parser-utils": "4.8.11",
 		"vue-eslint-parser": "10.2.0"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }