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

package/docs/maintenance.ja.md

@@ -0,0 +1,183 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                      | 説明                   |
+| --------------------------------------------- | ---------------------- |
+| `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. 名前空間スコーピングの変更
+
+1. `src/parser.ts` を読む — `#updateScopeNS()` プライベートメソッド
+2. このメソッドには2つの条件がある:
+   - XHTML → SVG: 現在の名前空間が XHTML で、ノードが `<svg>` 要素の場合
+   - SVG → XHTML: 現在の名前空間が SVG で、親が `<foreignObject>` の場合
+3. 新しい名前空間遷移を追加する場合（例: MathML）:
+   ```ts
+   if (
+     parentNS === 'http://www.w3.org/1999/xhtml' &&
+     originNode.type === 'element' &&
+     originNode.name?.toLowerCase() === 'math'
+   ) {
+     this.state.scopeNS = 'http://www.w3.org/1998/Math/MathML';
+   }
+   ```
+4. ビルドとテスト: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
+5. `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 名前空間を持つ。
+
+**原因:** `#updateScopeNS()` が要素タイプを正しく検出していないか、`scopeNS` 状態がリセットされていない。
+
+**解決策:**
+
+1. `originNode.type === 'element'` を確認 — 要素ノードのみが名前空間の変更をトリガー
+2. `originNode.name?.toLowerCase()` を確認 — `svg` の比較はケースインセンシティブである必要がある
+3. `parentNode.nodeName === 'foreignObject'` の比較を確認 — これは Astro AST の名前ではなく markuplint のノード名を使用
+4. 特定のネストパターンのテストケースを `src/parser.spec.ts` に追加
+
+### テンプレートディレクティブが検出されない
+
+**症状:** `set:html={content}` のような属性に `isDirective: true` が設定されない、または `class:list` に `potentialName: 'class'` が設定されない。
+
+**原因:** 正規表現 `/^([^:]+):([^:]+)$/` がマッチしなかった、またはスイッチケースが欠落。
+
+**解決策:**
+
+1. 属性名の形式を確認 — 正規表現はコロンが1つだけで、両側に空でない部分が必要
+2. `switch (lowerCaseDirectiveName)` を確認 — ディレクティブプレフィックスがケースにマッチする必要がある
+3. 新しいディレクティブプレフィックスの場合は、新しいケースを追加（レシピ #1 参照）

package/docs/maintenance.md

@@ -0,0 +1,183 @@
+# 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
+
+1. Read `src/parser.ts` — the `#updateScopeNS()` private method
+2. The method has two conditions:
+   - XHTML → SVG: when current namespace is XHTML and node is a `<svg>` element
+   - SVG → XHTML: when current namespace is SVG and parent is `<foreignObject>`
+3. To add a new namespace transition (e.g., MathML):
+   ```ts
+   if (
+     parentNS === 'http://www.w3.org/1999/xhtml' &&
+     originNode.type === 'element' &&
+     originNode.name?.toLowerCase() === 'math'
+   ) {
+     this.state.scopeNS = 'http://www.w3.org/1998/Math/MathML';
+   }
+   ```
+4. Build and test: `yarn build --scope @markuplint/astro-parser && yarn test --scope @markuplint/astro-parser`
+5. 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:** `#updateScopeNS()` is not detecting the element type correctly, or the `scopeNS` state is not being reset.
+
+**Solution:**
+
+1. Check that `originNode.type === 'element'` — only element nodes trigger namespace changes
+2. Check `originNode.name?.toLowerCase()` — the comparison must be case-insensitive for `svg`
+3. Check the `parentNode.nodeName === 'foreignObject'` comparison — this uses the markuplint node name, not the Astro AST name
+4. Add a test case with the specific nesting pattern to `src/parser.spec.ts`
+
+### 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)

package/lib/astro-parser.d.ts

@@ -1,3 +1,10 @@
 import type { RootNode } from '@astrojs/compiler/types';
 export type { RootNode, ElementNode, CustomElementNode, ComponentNode, FragmentNode, AttributeNode, Node, } from '@astrojs/compiler/types';
+/**
+ * Parses an Astro component source string into the Astro compiler's root AST node.
+ * Delegates to astro-eslint-parser and converts any diagnostics into ParserErrors.
+ *
+ * @param code - The raw Astro component source code
+ * @returns The root AST node produced by the Astro compiler
+ */
 export declare function astroParse(code: string): RootNode;

package/lib/astro-parser.js

@@ -1,5 +1,12 @@
 import { ParserError } from '@markuplint/parser-utils';
 import { parseTemplate } from 'astro-eslint-parser';
+/**
+ * Parses an Astro component source string into the Astro compiler's root AST node.
+ * Delegates to astro-eslint-parser and converts any diagnostics into ParserErrors.
+ *
+ * @param code - The raw Astro component source code
+ * @returns The root AST node produced by the Astro compiler
+ */
 export function astroParse(code) {
     const { result } = parseTemplate(code);
     if (result.diagnostics[0]) {

package/lib/detect-block-behavior.d.ts

@@ -0,0 +1,10 @@
+import type { MLASTBlockBehavior } from '@markuplint/ml-ast';
+/**
+ * Detects the block behavior of an Astro expression by inspecting its raw
+ * source for `.map()` or `.filter()` array method calls. Maps `.map()` to
+ * `'each'` (iteration) and `.filter()` to `'if'` (conditional filtering).
+ *
+ * @param raw - The raw source text of the expression to analyze
+ * @returns The detected block behavior, or `null` if no recognized pattern is found
+ */
+export declare function detectBlockBehavior(raw: string): MLASTBlockBehavior | null;

package/lib/detect-block-behavior.js

@@ -0,0 +1,20 @@
+/**
+ * Detects the block behavior of an Astro expression by inspecting its raw
+ * source for `.map()` or `.filter()` array method calls. Maps `.map()` to
+ * `'each'` (iteration) and `.filter()` to `'if'` (conditional filtering).
+ *
+ * @param raw - The raw source text of the expression to analyze
+ * @returns The detected block behavior, or `null` if no recognized pattern is found
+ */
+export function detectBlockBehavior(raw) {
+    const re = /\.+\s*(?<type>map|filter)\s*\((?:function\s*\(.[^\n\r{\u2028\u2029]*\{.*return\s*$|.+=>\s*\(?\s*)/;
+    const match = raw.match(re);
+    if (!match) {
+        return null;
+    }
+    const type = match.groups?.type === 'map' ? 'each' : 'if';
+    return {
+        type,
+        expression: raw,
+    };
+}

package/lib/index.d.ts

@@ -1 +1,8 @@
+/**
+ * @module
+ * Astro component parser for markuplint. Provides a parser that transforms Astro
+ * component syntax into markuplint's AST, handling frontmatter blocks, expression
+ * syntax (`{}`), Astro-specific directives (e.g., `class:list`, `set:html`),
+ * and namespace-aware element resolution.
+ */
 export { parser } from './parser.js';

package/lib/index.js

@@ -1 +1,8 @@
+/**
+ * @module
+ * Astro component parser for markuplint. Provides a parser that transforms Astro
+ * component syntax into markuplint's AST, handling frontmatter blocks, expression
+ * syntax (`{}`), Astro-specific directives (e.g., `class:list`, `set:html`),
+ * and namespace-aware element resolution.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -1,21 +1,59 @@
 import type { Node } from './astro-parser.js';
-import type { MLASTParentNode, MLASTNodeTreeItem } from '@markuplint/ml-ast';
+import type { MLASTNodeTreeItem, MLASTParentNode } from '@markuplint/ml-ast';
 import type { ChildToken, Token } from '@markuplint/parser-utils';
 import { Parser } from '@markuplint/parser-utils';
-type State = {
-    scopeNS: string;
-};
-declare class AstroParser extends Parser<Node, State> {
-    #private;
+/**
+ * Parser implementation for Astro component templates.
+ * Extends the base Parser to handle Astro-specific syntax including frontmatter blocks,
+ * expression containers (`{}`), component/element/fragment types, Astro directives
+ * (e.g., `class:list`, `set:html`), and shorthand attributes.
+ */
+declare class AstroParser extends Parser<Node> {
     constructor();
     tokenize(): {
         ast: Node[];
         isFragment: boolean;
     };
+    /**
+     * Converts an Astro AST node into markuplint node tree items.
+     * Handles frontmatter, doctype, text, comment, component/element/fragment,
+     * and expression nodes.
+     *
+     * @param originNode - The Astro 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: Node, parentNode: MLASTParentNode | null, depth: number): readonly MLASTNodeTreeItem[];
     afterFlattenNodes(nodeList: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Visits an element token by first parsing the raw HTML fragment to extract
+     * the start tag, then delegating to the base visitElement with Astro-specific
+     * options including nameless fragment support.
+     *
+     * @param token - The child token representing the element
+     * @param childNodes - The child Astro AST nodes within the element
+     * @returns An array of markuplint node tree items
+     */
     visitElement(token: ChildToken, childNodes: readonly Node[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Visits child nodes and verifies that no sibling nodes with differing
+     * hierarchy levels are produced. Throws a ParserError if unexpected
+     * sibling nodes are discovered.
+     *
+     * @param children - The child Astro AST nodes to visit
+     * @param parentNode - The parent node in the markuplint tree
+     * @returns An empty array (all children are attached via the visitor)
+     */
     visitChildren(children: readonly Node[], parentNode: MLASTParentNode | null): never[];
+    /**
+     * Visits an attribute token, handling Astro-specific syntax including
+     * curly-brace expression values, shorthand attributes (`{name}`),
+     * and template directives (e.g., `class:list`, `set:html`).
+     *
+     * @param token - The token representing the attribute
+     * @returns The parsed attribute node with Astro-specific metadata
+     */
     visitAttr(token: Token): (import("@markuplint/ml-ast").MLASTSpreadAttr & {
         __rightText?: string;
     }) | {
@@ -38,12 +76,9 @@ declare class AstroParser extends Parser<Node, State> {
         isDuplicatable: boolean;
         uuid: string;
         raw: string;
-        startOffset: number;
-        endOffset: number;
-        startLine: number;
-        endLine: number;
-        startCol: number;
-        endCol: number;
+        offset: number;
+        line: number;
+        col: number;
         __rightText?: string;
     };
     /**