@markuplint/astro-parser 5.0.0-rc.2 → 5.0.0-rc.5

package/docs/maintenance.ja.md

@@ -1,172 +0,0 @@
-# メンテナンスガイド
-
-## コマンド
-
-| コマンド                                      | 説明                   |
-| --------------------------------------------- | ---------------------- |
-| `yarn build --scope @markuplint/astro-parser` | このパッケージをビルド |
-| `yarn dev --scope @markuplint/astro-parser`   | ウォッチモードでビルド |
-| `yarn clean --scope @markuplint/astro-parser` | ビルド成果物を削除     |
-| `yarn test --scope @markuplint/astro-parser`  | テストを実行           |
-
-## テスト
-
-テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
-
-| テストファイル         | カバレッジ                                                                 |
-| ---------------------- | -------------------------------------------------------------------------- |
-| `parser.spec.ts`       | AstroParser 統合テスト（フロントマター、式、属性、名前空間、フラグメント） |
-| `astro-parser.spec.ts` | astro-eslint-parser ラッパーテスト（生の AST 出力、属性の種類、診断）      |
-
-主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
-
-```ts
-import { nodeListToDebugMaps } from '@markuplint/parser-utils';
-import { parser } from '@markuplint/astro-parser';
-
-const doc = parser.parse('<div class:list={["a"]}>{name}</div>');
-const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
-expect(debugMaps).toStrictEqual([
-  // 期待されるデバッグ出力
-]);
-```
-
-`nodeListToDebugMaps` の第2引数 `true` は出力に属性の詳細を含め、ディレクティブや動的な値の処理をテストする際に不可欠です。
-
-## レシピ
-
-### 1. 新しいテンプレートディレクティブの追加
-
-1. `src/parser.ts` を読む — `visitAttr()` メソッド、特に `switch (lowerCaseDirectiveName)` ブロック
-2. ディレクティブプレフィックスに新しい `case` を追加:
-   - ディレクティブが標準 HTML 属性にマッピングされる場合（`class:list` → `class` のように）、`potentialName` を HTML 属性名に設定
-   - ディレクティブが Astro 固有の場合（`set:html` のように）、`isDirective = true` を設定
-3. 例 — `style` にマッピングする仮の `style:inline` ディレクティブを追加:
-   ```ts
-   case 'style': {
-     potentialName = lowerCaseDirectiveName;
-     break;
-   }
-   ```
-4. ビルド: `yarn build --scope @markuplint/astro-parser`
-5. `src/parser.spec.ts` にテストケースを追加:
-   ```ts
-   test('style:inline directive', () => {
-     const ast = parse('<div style:inline={styles}></div>');
-     const map = nodeListToDebugMaps(ast.nodeList, true);
-     // potentialName: style と isDynamicValue: true を検証
-   });
-   ```
-6. テスト: `yarn test --scope @markuplint/astro-parser`
-
-### 2. 名前空間スコーピングの変更
-
-名前空間の解決は現在 `@markuplint/parser-utils` の基底 `Parser` クラスが処理しています。Astro パーサーは名前空間ロジックをオーバーライドしていません。
-
-1. カスタム名前空間処理が必要な場合は、`src/parser.ts` の `AstroParser` で該当メソッドをオーバーライド
-2. 新しい名前空間（例: MathML）の場合、要素名を検出して名前空間を切り替えるオーバーライドが必要
-3. ビルドとテスト: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
-4. `src/parser.spec.ts` に名前空間テストケースを追加:
-   ```ts
-   test('MathML namespace', () => {
-     const doc = parse('<div><math><mi>x</mi></math></div>');
-     expect(doc.nodeList[1].namespace).toBe('http://www.w3.org/1998/Math/MathML');
-   });
-   ```
-
-### 3. 式の処理の更新
-
-1. `src/parser.ts` を読む — `nodeize()` 内の `case 'expression'` ブロック
-2. 式の分割ロジックは以下のように動作する:
-   - 式に複数の子がある場合（`firstChild !== lastChild`）:
-     - 開始フラグメント: 式の開始から最初の子の終了まで
-     - 終了フラグメント: 最後の子の開始から式の終了まで
-     - 子は開始フラグメントの psblock 内で訪問される
-   - 式に子が1つまたは子がない場合:
-     - 式全体が1つの MustacheTag psblock として出力される
-3. 変更時の注意:
-   - `sliceFragment()` のオフセットが開始フラグメントと終了フラグメントの両方で正しいことを確認
-   - 終了フラグメントは `isFragment: false` である必要がある
-   - 開始フラグメントは `isFragment: true` で、子の訪問のために `originNode.children` を渡す必要がある
-4. ビルドとテスト: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
-5. 複雑な式でテスト:
-   ```ts
-   test('Nested expression with HTML', () => {
-     const ast = parse('<ul>{list.map(item => <li>{item}</li>)}</ul>');
-     const map = nodeListToDebugMaps(ast.nodeList);
-     // 開始 MustacheTag、ネストされた要素、終了 MustacheTag を検証
-   });
-   ```
-
-## 上流影響チェックリスト
-
-上流パッケージの変更がこのパーサーに影響を与える可能性があります:
-
-| パッケージ                 | 影響                                                        |
-| -------------------------- | ----------------------------------------------------------- |
-| `@markuplint/parser-utils` | 基底 `Parser` クラスの変更は全オーバーライドメソッドに影響  |
-| `@markuplint/ml-ast`       | AST 型の変更は `nodeize()` の戻り値の型に影響               |
-| `astro-eslint-parser`      | パーサー出力形式の変更は `tokenize()` と `nodeize()` に影響 |
-
-`astro-eslint-parser` を更新する場合:
-
-```shell
-# ランタイム依存を更新
-yarn upgrade astro-eslint-parser --scope @markuplint/astro-parser
-
-# 型用の開発依存を更新
-yarn upgrade @astrojs/compiler --scope @markuplint/astro-parser --dev
-
-# 互換性を検証
-yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser
-```
-
-## トラブルシューティング
-
-### フロントマターが認識されない
-
-**症状:** `---...---` ブロックが Frontmatter psblock としてパースされない、またはその内容が HTML AST に漏れる。
-
-**原因:** `astro-eslint-parser` が `type: 'frontmatter'` ノードを生成していないか、ノードの位置オフセットが不正。
-
-**解決策:**
-
-1. `src/astro-parser.spec.ts` にテストを追加し、`astroParse()` からの生の AST 出力を検証
-2. フロントマターノードの `position.start.offset` と `position.end.offset` が正しいことを確認
-3. `nodeize()` の `case 'frontmatter'` ブランチに到達していることを検証
-
-### 式の分割で不正なオフセットが生成される
-
-**症状:** MustacheTag psblock ノードの開始/終了位置が不正、または式内のネストされた HTML 要素の位置がずれている。
-
-**原因:** `case 'expression'` ブランチの `sliceFragment()` 呼び出しが Astro AST の子から間違ったオフセットを使用している。
-
-**解決策:**
-
-1. `firstChild.position?.end?.offset` と `lastChild.position?.start.offset` を確認 — これらは Astro AST の位置と正確に一致する必要がある
-2. `startExpressionEndOffset` が式の開始と最初の HTML 子の間にあることを検証
-3. `nodeListToDebugMaps` を使用して実際の位置と期待される位置を比較
-
-### 名前空間が正しく適用されない
-
-**症状:** `<svg>` 内の要素が XHTML 名前空間を持つ、または `<foreignObject>` 内の要素が SVG 名前空間を持つ。
-
-**原因:** 名前空間の解決は `@markuplint/parser-utils` の基底 `Parser` クラスが処理します。Astro パーサーは名前空間ロジックをオーバーライドしていません。
-
-**解決策:**
-
-1. 問題が `@markuplint/parser-utils` の基底 `Parser` クラスにあるかどうかを確認
-2. 特定のネストパターンのテストケースを `src/parser.spec.ts` に追加して期待される動作を確認
-3. 問題が上流にある場合は、基底 `Parser` の名前空間処理を調査
-
-### テンプレートディレクティブが検出されない
-
-**症状:** `set:html={content}` のような属性に `isDirective: true` が設定されない、または `class:list` に `potentialName: 'class'` が設定されない。
-
-**原因:** 正規表現 `/^([^:]+):([^:]+)$/` がマッチしなかった、またはスイッチケースが欠落。
-
-**解決策:**
-
-1. 属性名の形式を確認 — 正規表現はコロンが1つだけで、両側に空でない部分が必要
-2. `switch (lowerCaseDirectiveName)` を確認 — ディレクティブプレフィックスがケースにマッチする必要がある
-3. 新しいディレクティブプレフィックスの場合は、新しいケースを追加（レシピ #1 参照）

package/docs/maintenance.md

@@ -1,172 +0,0 @@
-# Maintenance Guide
-
-## Commands
-
-| Command                                       | Description            |
-| --------------------------------------------- | ---------------------- |
-| `yarn build --scope @markuplint/astro-parser` | Build this package     |
-| `yarn dev --scope @markuplint/astro-parser`   | Watch mode build       |
-| `yarn clean --scope @markuplint/astro-parser` | Remove build artifacts |
-| `yarn test --scope @markuplint/astro-parser`  | Run tests              |
-
-## Testing
-
-Test files follow the `*.spec.ts` naming convention and are located in the `src/` directory:
-
-| Test File              | Coverage                                                                                    |
-| ---------------------- | ------------------------------------------------------------------------------------------- |
-| `parser.spec.ts`       | AstroParser integration tests (frontmatter, expressions, attributes, namespaces, fragments) |
-| `astro-parser.spec.ts` | astro-eslint-parser wrapper tests (raw AST output, attribute kinds, diagnostics)            |
-
-The primary testing pattern uses `nodeListToDebugMaps` for snapshot-style assertions:
-
-```ts
-import { nodeListToDebugMaps } from '@markuplint/parser-utils';
-import { parser } from '@markuplint/astro-parser';
-
-const doc = parser.parse('<div class:list={["a"]}>{name}</div>');
-const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
-expect(debugMaps).toStrictEqual([
-  // expected debug output
-]);
-```
-
-The second argument `true` to `nodeListToDebugMaps` includes attribute details in the output, which is essential for testing directive and dynamic value handling.
-
-## Recipes
-
-### 1. Adding a New Template Directive
-
-1. Read `src/parser.ts` — the `visitAttr()` method, specifically the `switch (lowerCaseDirectiveName)` block
-2. Add a new `case` for the directive prefix:
-   - If the directive maps to a standard HTML attribute (like `class:list` → `class`), set `potentialName` to the HTML attribute name
-   - If the directive is Astro-specific (like `set:html`), set `isDirective = true`
-3. Example — adding a hypothetical `style:inline` directive that maps to `style`:
-   ```ts
-   case 'style': {
-     potentialName = lowerCaseDirectiveName;
-     break;
-   }
-   ```
-4. Build: `yarn build --scope @markuplint/astro-parser`
-5. Add test cases to `src/parser.spec.ts`:
-   ```ts
-   test('style:inline directive', () => {
-     const ast = parse('<div style:inline={styles}></div>');
-     const map = nodeListToDebugMaps(ast.nodeList, true);
-     // Verify potentialName: style and isDynamicValue: true
-   });
-   ```
-6. Test: `yarn test --scope @markuplint/astro-parser`
-
-### 2. Modifying Namespace Scoping
-
-Namespace resolution is currently handled by the base `Parser` class from `@markuplint/parser-utils`. The Astro parser does not override namespace logic.
-
-1. If you need to add custom namespace handling, you would override the relevant method in `AstroParser` in `src/parser.ts`
-2. For new namespaces (e.g., MathML), the override would need to detect the element name and switch the namespace
-3. Build and test: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
-4. Add namespace test cases to `src/parser.spec.ts`:
-   ```ts
-   test('MathML namespace', () => {
-     const doc = parse('<div><math><mi>x</mi></math></div>');
-     expect(doc.nodeList[1].namespace).toBe('http://www.w3.org/1998/Math/MathML');
-   });
-   ```
-
-### 3. Updating Expression Handling
-
-1. Read `src/parser.ts` — the `case 'expression'` block in `nodeize()`
-2. The expression splitting logic works as follows:
-   - If the expression has multiple children (`firstChild !== lastChild`):
-     - Opening fragment: from expression start to first child's end
-     - Closing fragment: from last child's start to expression end
-     - Children are visited within the opening fragment's psblock
-   - If the expression has a single child or no children:
-     - The entire expression is emitted as one MustacheTag psblock
-3. When modifying:
-   - Ensure `sliceFragment()` offsets are correct for both opening and closing fragments
-   - The closing fragment must have `isFragment: false`
-   - The opening fragment must have `isFragment: true` and pass `originNode.children` for child visitation
-4. Build and test: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
-5. Test with complex expressions:
-   ```ts
-   test('Nested expression with HTML', () => {
-     const ast = parse('<ul>{list.map(item => <li>{item}</li>)}</ul>');
-     const map = nodeListToDebugMaps(ast.nodeList);
-     // Verify opening MustacheTag, nested elements, and closing MustacheTag
-   });
-   ```
-
-## Upstream Impact Checklist
-
-Changes to upstream packages can affect this parser:
-
-| Package                    | Impact                                                           |
-| -------------------------- | ---------------------------------------------------------------- |
-| `@markuplint/parser-utils` | Base `Parser` class changes affect all override methods          |
-| `@markuplint/ml-ast`       | AST type changes affect `nodeize()` return types                 |
-| `astro-eslint-parser`      | Parser output format changes affect `tokenize()` and `nodeize()` |
-
-When updating `astro-eslint-parser`:
-
-```shell
-# Update the runtime dependency
-yarn upgrade astro-eslint-parser --scope @markuplint/astro-parser
-
-# Update the dev dependency for types
-yarn upgrade @astrojs/compiler --scope @markuplint/astro-parser --dev
-
-# Verify compatibility
-yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser
-```
-
-## Troubleshooting
-
-### Frontmatter is not recognized
-
-**Symptom:** The `---...---` block is not parsed as a Frontmatter psblock, or its content leaks into the HTML AST.
-
-**Cause:** `astro-eslint-parser` may not be producing a `type: 'frontmatter'` node, or the node's position offsets are incorrect.
-
-**Solution:**
-
-1. Add a test in `src/astro-parser.spec.ts` to verify the raw AST output from `astroParse()`
-2. Check that the frontmatter node has correct `position.start.offset` and `position.end.offset`
-3. Verify the `case 'frontmatter'` branch in `nodeize()` is being reached
-
-### Expression splitting produces wrong offsets
-
-**Symptom:** MustacheTag psblock nodes have incorrect start/end positions, or nested HTML elements inside expressions are misaligned.
-
-**Cause:** The `sliceFragment()` calls in the `case 'expression'` branch are using wrong offsets from the Astro AST children.
-
-**Solution:**
-
-1. Check `firstChild.position?.end?.offset` and `lastChild.position?.start.offset` — these must match the Astro AST positions exactly
-2. Verify that `startExpressionEndOffset` falls between the expression start and the first HTML child
-3. Use `nodeListToDebugMaps` to compare actual vs expected positions
-
-### Namespace is not applied correctly
-
-**Symptom:** Elements inside `<svg>` have XHTML namespace, or elements inside `<foreignObject>` have SVG namespace.
-
-**Cause:** Namespace resolution is handled by the base `Parser` class from `@markuplint/parser-utils`. The Astro parser does not override namespace logic.
-
-**Solution:**
-
-1. Check whether the issue is in the base `Parser` class in `@markuplint/parser-utils`
-2. Add a test case with the specific nesting pattern to `src/parser.spec.ts` to confirm expected behavior
-3. If the issue is upstream, investigate the base `Parser` namespace handling
-
-### Template directive not detected
-
-**Symptom:** An attribute like `set:html={content}` does not get `isDirective: true`, or `class:list` does not get `potentialName: 'class'`.
-
-**Cause:** The regex `/^([^:]+):([^:]+)$/` did not match, or the switch case is missing.
-
-**Solution:**
-
-1. Verify the attribute name format — the regex requires exactly one colon with non-empty parts on both sides
-2. Check the `switch (lowerCaseDirectiveName)` — the directive prefix must match a case
-3. If it is a new directive prefix, add a new case (see Recipe #1)