@markuplint/vue-parser 4.6.22 → 5.0.0-alpha.0

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 directivePatterns (vue-spec) |
+| `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 `directivePatterns` (`@markuplint/vue-spec`). Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Understand the directive
+
+1. Open `@markuplint/vue-spec` (`packages/@markuplint/vue-spec/src/index.ts`) and find the `directivePatterns` array
+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 `directivePatterns` — `.prop` shorthand before `v-bind` with modifiers before `v-bind`/`:` before `v-on`/`@` 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. `@markuplint/vue-spec`（`packages/@markuplint/vue-spec/src/index.ts`）を開き、`directivePatterns` 配列を確認する
+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 属性として扱われる。
+
+**原因:** `directivePatterns`（`@markuplint/vue-spec` で定義）でディレクティブパターンがマッチしないか、新しいパターンが汎用 `v-*` キャッチオールの後に配置されている。
+
+**解決策:**
+
+1. ディレクティブブロックの正規表現パターンを確認 — 完全な属性名にマッチすることを確認
+2. パターンが `directivePatterns` 配列内の汎用 `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. Open `@markuplint/vue-spec` (`packages/@markuplint/vue-spec/src/index.ts`) and find the `directivePatterns` array
+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 `directivePatterns` (defined in `@markuplint/vue-spec`), or the new pattern 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 pattern is placed before the generic `v-*` catch-all in the `directivePatterns` array
+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

@@ -1,26 +1,43 @@
 import type { ASTNode, ASTComment } from './vue-parser/index.js';
 import type { MLASTParentNode, MLASTNodeTreeItem } from '@markuplint/ml-ast';
-import type { Token } from '@markuplint/parser-utils';
 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();
     tokenize(): {
-        ast: (import("vue-eslint-parser/ast/nodes").VElement | import("vue-eslint-parser/ast/nodes").VText | import("vue-eslint-parser/ast/nodes").VExpressionContainer)[];
-        isFragment: boolean;
+        readonly ast: ASTNode[];
+        readonly 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[];
-    visitAttr(token: Token): (import("@markuplint/ml-ast").MLASTHTMLAttr & {
-        __rightText?: string;
-    }) | (import("@markuplint/ml-ast").MLASTSpreadAttr & {
-        __rightText?: string;
-    });
     /**
      * > In SFCs, it's recommended to use `PascalCase` tag names
      * > for child components to differentiate from native HTML elements.