@markuplint/vue-parser 5.0.0-rc.4 → 5.0.0-rc.5

package/docs/maintenance.ja.md

@@ -1,203 +0,0 @@
-# メンテナンスガイド
-
-## コマンド
-
-| コマンド                                    | 説明                   |
-| ------------------------------------------- | ---------------------- |
-| `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

@@ -1,203 +0,0 @@
-# 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