@markuplint/astro-parser 4.6.21 → 4.6.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,229 @@
+# @markuplint/astro-parser
+
+## 概要
+
+`@markuplint/astro-parser` は markuplint における Astro コンポーネントファイル（`.astro`）のパーサーです。`astro-eslint-parser`（`@astrojs/compiler` をラップ）を使用して Astro ソースコードをトークン化し、その結果の AST を markuplint の統一 AST 形式（`MLASTDocument`）に変換します。フロントマターブロック（`---...---`）、式コンテナ（`{expression}`）、テンプレートディレクティブ（例: `class:list`、`set:html`）、ショートハンド属性（`{prop}`）、名前空間対応の要素解決（XHTML vs SVG）など、Astro 固有の構文を処理します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                — parser インスタンスを再エクスポート
+├── parser.ts               — Parser<Node, State> を拡張する AstroParser クラス
+├── astro-parser.ts         — astro-eslint-parser ラッパーと型の再エクスポート
+├── parser.spec.ts          — AstroParser 統合テスト
+└── astro-parser.spec.ts    — astro-eslint-parser ラッパーテスト
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        mlAst["@markuplint/ml-ast\n(AST 型定義)"]
+        parserUtils["@markuplint/parser-utils\n(抽象 Parser クラス)"]
+        astroEslintParser["astro-eslint-parser\n(Astro トークナイザ)"]
+        astroCompiler["@astrojs/compiler\n(AST 型定義)"]
+    end
+
+    subgraph pkg ["@markuplint/astro-parser"]
+        astroParser["AstroParser\nextends Parser‹Node, State›"]
+        astroParseFn["astroParse()\nastro-eslint-parser ラッパー"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    mlAst -->|"AST 型"| astroParser
+    parserUtils -->|"Parser 基底クラス"| astroParser
+    astroEslintParser -->|"parseTemplate()"| astroParseFn
+    astroCompiler -->|"Node 型"| astroParseFn
+    astroParseFn -->|"RootNode.children"| astroParser
+    astroParser -->|"MLASTDocument を生成"| mlCore
+```
+
+## AstroParser クラス
+
+### 継承関係
+
+```
+Parser<Node, State>  (@markuplint/parser-utils)
+    └── AstroParser  (このパッケージ)
+```
+
+### コンストラクタ
+
+コンストラクタは Astro 固有のオプションで基底 `Parser` を設定します:
+
+| オプション             | 値           | 用途                                                                         |
+| ---------------------- | ------------ | ---------------------------------------------------------------------------- |
+| `endTagType`           | `'xml'`      | Astro は XML のように明示的な閉じタグを使用                                  |
+| `selfCloseType`        | `'html+xml'` | HTML void 要素と XML スタイルの自己閉じ（`<Component />`）の両方を受け入れる |
+| `tagNameCaseSensitive` | `true`       | コンポーネント（`<MyComp>`）と HTML 要素（`<div>`）を区別                    |
+
+### State 型
+
+パーサーは `State` 型を通じて内部状態を管理します:
+
+| フィールド | 型       | 用途                                                            |
+| ---------- | -------- | --------------------------------------------------------------- |
+| `scopeNS`  | `string` | 現在の名前空間 URI、デフォルトは `http://www.w3.org/1999/xhtml` |
+
+`scopeNS` 状態は `#updateScopeNS()` によってパーサーが要素を走査する際に更新され、`<svg>` 要素内で SVG 名前空間に切り替わり、`<foreignObject>` 内で XHTML に戻ります。
+
+### オーバーライドメソッド
+
+| メソッド              | 用途                                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `tokenize()`          | `astroParse()` を呼び出して Astro AST を取得し、`{ ast: rootNode.children, isFragment: true }` を返す                          |
+| `nodeize()`           | Astro AST ノードを markuplint ノードに変換。ノードタイプ（frontmatter, doctype, text, comment, element, expression）で振り分け |
+| `afterFlattenNodes()` | `{ exposeInvalidNode: false }` で親に委譲                                                                                      |
+| `visitElement()`      | `parseCodeFragment()` で `namelessFragment: true` として生の HTML フラグメントをパースし、名前空間と終了タグ処理で親に委譲     |
+| `visitChildren()`     | 親に委譲した後、予期しない兄弟ノードが残っていないことをアサート                                                               |
+| `visitAttr()`         | 波括弧式の値、ショートハンド属性、テンプレートディレクティブを処理                                                             |
+| `detectElementType()` | `/^[A-Z]/` パターンでコンポーネントと HTML 要素を検出（大文字始まりの名前はコンポーネント）                                    |
+
+## フロントマター処理
+
+Astro コンポーネントは `---` で区切られたフロントマターブロックを含むことができます:
+
+```astro
+---
+const name = "World";
+---
+<div>{name}</div>
+```
+
+`astro-eslint-parser` は `type: 'frontmatter'` のノードを生成します。パーサーはこれを `nodeName: 'Frontmatter'` かつ `isFragment: false` の **psblock**（疑似ブロック）に変換します。区切り文字 `---` を含むブロック全体が単一の不透明ノードとしてキャプチャされます。フロントマター内のコンテンツは HTML としてパースされません。
+
+## 式の処理
+
+Astro の式（`{expression}`）は Astro AST で `type: 'expression'` ノードとして表現されます。パーサーはこれらを **MustacheTag** psblock ノードに変換します。
+
+### 単純な式
+
+`{name}` のような単純な式は単一のテキスト子ノードを持ちます。式全体が `isFragment: true` の1つの MustacheTag psblock として出力されます。
+
+### HTML を含むネストされた式
+
+式が HTML 要素を含む場合（例: `{list.map(item => <li>{item}</li>)}`）、パーサーは複数のノードに分割します:
+
+1. **開始式フラグメント**: `{list.map(item => ` — 子ノードを含む MustacheTag psblock
+2. **ネストされた HTML 要素**: `<li>{item}</li>` — 通常の要素として処理
+3. **終了式フラグメント**: `)}` — `isFragment: false` の別の MustacheTag psblock
+
+分割ロジックは式の children 配列で `firstChild !== lastChild` かどうかを確認します。該当する場合:
+
+- 式の開始から最初の子の終了までの領域が開始フラグメントになる
+- 最後の子の開始から式の終了までの領域が終了フラグメントになる
+- 間の子は開始フラグメントの psblock 内で通常通り訪問される
+
+## 名前空間スコーピング
+
+`#updateScopeNS()` プライベートメソッドは、パーサーが要素を走査する際に名前空間コンテキストを管理します:
+
+| 条件                                                  | アクション                                           |
+| ----------------------------------------------------- | ---------------------------------------------------- |
+| 現在の名前空間が XHTML で、ノードが `<svg>` 要素      | `scopeNS` を `http://www.w3.org/2000/svg` に切り替え |
+| 現在の名前空間が SVG で、親ノードが `<foreignObject>` | `scopeNS` を `http://www.w3.org/1999/xhtml` に戻す   |
+
+これは `nodeize()` のノードタイプ switch の前に呼び出されるため、すべての子ノードが正しい名前空間を継承します。名前空間は `visitElement()` 内で `overwriteProps: { namespace: this.state.scopeNS }` を通じて要素に適用されます。
+
+名前空間解決の例:
+
+```html
+<div>
+  <!-- XHTML -->
+  <svg>
+    <!-- SVG -->
+    <text />
+    <!-- SVG -->
+    <foreignObject>
+      <!-- SVG -->
+      <div />
+      <!-- XHTML（リセット） -->
+    </foreignObject>
+  </svg>
+</div>
+```
+
+## 属性処理
+
+### クォートセット
+
+`visitAttr()` メソッドは式の値用に波括弧を含むカスタムクォートセットを使用します:
+
+| 開始 | 終了 | タイプ   |
+| ---- | ---- | -------- |
+| `"`  | `"`  | `string` |
+| `'`  | `'`  | `string` |
+| `{`  | `}`  | `script` |
+
+### ショートハンド属性
+
+属性トークンが `{` で始まる場合（例: `{prop}`）、パーサーは `startState: AttrState.BeforeValue` を設定し、名前のパースをスキップして直接値の抽出に進みます。結果の属性は:
+
+- `name.raw` = `''`（空）
+- `value.raw` = `prop`
+- `potentialName` = `prop`（値から推論）
+- `isDynamicValue` = `true`
+
+### テンプレートディレクティブ
+
+Astro テンプレートディレクティブは `name:modifier` 構文を使用します。パーサーは正規表現 `/^([^:]+):([^:]+)$/` でこれらを検出します:
+
+| ディレクティブ | `potentialName` | `isDirective` | 動作                                   |
+| -------------- | --------------- | ------------- | -------------------------------------- |
+| `class:list`   | `'class'`       | `undefined`   | 標準の `class` 属性にマッピング        |
+| `set:html`     | `undefined`     | `true`        | Astro 固有ディレクティブとして扱われる |
+| `set:text`     | `undefined`     | `true`        | Astro 固有ディレクティブとして扱われる |
+| `is:raw`       | `undefined`     | `true`        | Astro 固有ディレクティブとして扱われる |
+| `transition:*` | `undefined`     | `true`        | Astro 固有ディレクティブとして扱われる |
+
+`class` ディレクティブは特別で、`potentialName: 'class'` を取得するため、`class` 属性に対する markuplint ルールが適用されます。その他すべてのディレクティブは `isDirective: true` を取得し、フレームワーク固有であり標準 HTML 属性として検証すべきでないことを markuplint に伝えます。
+
+### 動的な値
+
+開始クォートが `{` の属性はすべて `isDynamicValue: true` を取得します。以下に適用されます:
+
+- 明示的な動的値: `prop={value}`
+- ショートハンド属性: `{prop}`
+- ネストされた式: `style={{ a: b }}`
+
+## jsx-parser との比較
+
+| 機能                           | `astro-parser`                         | `jsx-parser`                                      |
+| ------------------------------ | -------------------------------------- | ------------------------------------------------- |
+| **トークナイザ**               | `astro-eslint-parser`                  | TypeScript ESTree（`@typescript-eslint/parser`）  |
+| **フロントマター**             | サポート（`---...---` psblock）        | 該当なし                                          |
+| **式の構文**                   | `{expr}` を MustacheTag psblock として | `{expr}` を JSXExpressionContainer psblock として |
+| **テンプレートディレクティブ** | `class:list`、`set:html` 等            | 該当なし                                          |
+| **名前空間管理**               | `#updateScopeNS()` で手動管理          | html-parser の `getNamespace()` に委譲            |
+| **コンポーネント検出**         | `/^[A-Z]/` パターン                    | `/^[A-Z]/` パターン                               |
+| **自己閉じタイプ**             | `html+xml`                             | デフォルト（XML のみ）                            |
+| **booleanish 属性**            | 未設定                                 | `booleanish: true`                                |
+| **名前なしフラグメント**       | `<>...</>` サポート                    | `<>...</>` サポート                               |
+| **スプレッド属性**             | 基底パーサーで処理                     | カスタム `visitSpreadAttr()` で IDL ルックアップ  |
+
+## バージョン互換性
+
+パースチェーンは以下に依存します:
+
+```
+astro-eslint-parser → @astrojs/compiler → Astro 構文サポート
+```
+
+`astro-eslint-parser` は `parseTemplate()` を提供するランタイム依存です。`@astrojs/compiler` は AST 型定義（`Node`、`RootNode`、`ElementNode` 等）にのみ使用される開発依存です。`astro-eslint-parser` を更新する際は、`@astrojs/compiler` 開発依存も `astro-eslint-parser` が内部で使用するバージョンに合わせて更新する必要があります。
+
+## 主要ソースファイル
+
+| ファイル          | 用途                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `parser.ts`       | `AstroParser` クラス — 全オーバーライドメソッドと名前空間スコーピング                 |
+| `astro-parser.ts` | `astroParse()` ラッパー — `astro-eslint-parser` に委譲し、診断を `ParserError` に変換 |
+| `index.ts`        | 公開 API — シングルトン `parser` インスタンスを再エクスポート                         |
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,229 @@
+# @markuplint/astro-parser
+
+## Overview
+
+`@markuplint/astro-parser` is a parser for Astro component files (`.astro`) in markuplint. It uses `astro-eslint-parser` (which wraps `@astrojs/compiler`) to tokenize Astro source code, then converts the resulting AST into markuplint's unified AST format (`MLASTDocument`). The parser handles Astro-specific syntax including frontmatter blocks (`---...---`), expression containers (`{expression}`), template directives (e.g., `class:list`, `set:html`), shorthand attributes (`{prop}`), and namespace-aware element resolution (XHTML vs SVG).
+
+## Directory Structure
+
+```
+src/
+├── index.ts                — Re-exports parser instance
+├── parser.ts               — AstroParser class extending Parser<Node, State>
+├── astro-parser.ts         — astro-eslint-parser wrapper and type re-exports
+├── parser.spec.ts          — AstroParser integration tests
+└── astro-parser.spec.ts    — astro-eslint-parser wrapper tests
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        mlAst["@markuplint/ml-ast\n(AST types)"]
+        parserUtils["@markuplint/parser-utils\n(Abstract Parser class)"]
+        astroEslintParser["astro-eslint-parser\n(Astro tokenizer)"]
+        astroCompiler["@astrojs/compiler\n(AST types)"]
+    end
+
+    subgraph pkg ["@markuplint/astro-parser"]
+        astroParser["AstroParser\nextends Parser‹Node, State›"]
+        astroParseFn["astroParse()\nastro-eslint-parser wrapper"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    mlAst -->|"AST types"| astroParser
+    parserUtils -->|"Parser base class"| astroParser
+    astroEslintParser -->|"parseTemplate()"| astroParseFn
+    astroCompiler -->|"Node types"| astroParseFn
+    astroParseFn -->|"RootNode.children"| astroParser
+    astroParser -->|"produces MLASTDocument"| mlCore
+```
+
+## AstroParser Class
+
+### Inheritance
+
+```
+Parser<Node, State>  (from @markuplint/parser-utils)
+    └── AstroParser  (this package)
+```
+
+### Constructor
+
+The constructor configures the base `Parser` with Astro-specific options:
+
+| Option                 | Value        | Purpose                                                                      |
+| ---------------------- | ------------ | ---------------------------------------------------------------------------- |
+| `endTagType`           | `'xml'`      | Astro uses explicit closing tags like XML                                    |
+| `selfCloseType`        | `'html+xml'` | Accepts both HTML void elements and XML-style self-closing (`<Component />`) |
+| `tagNameCaseSensitive` | `true`       | Distinguishes components (`<MyComp>`) from HTML elements (`<div>`)           |
+
+### State Type
+
+The parser maintains internal state through the `State` type:
+
+| Field     | Type     | Purpose                                                           |
+| --------- | -------- | ----------------------------------------------------------------- |
+| `scopeNS` | `string` | Current namespace URI, defaults to `http://www.w3.org/1999/xhtml` |
+
+The `scopeNS` state is updated by `#updateScopeNS()` as the parser traverses elements, switching to SVG namespace inside `<svg>` elements and back to XHTML inside `<foreignObject>`.
+
+### Override Methods
+
+| Method                | Purpose                                                                                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tokenize()`          | Calls `astroParse()` to get the Astro AST, returns `{ ast: rootNode.children, isFragment: true }`                                                  |
+| `nodeize()`           | Converts Astro AST nodes to markuplint nodes, dispatching by node type (frontmatter, doctype, text, comment, element, expression)                  |
+| `afterFlattenNodes()` | Delegates to parent with `{ exposeInvalidNode: false }`                                                                                            |
+| `visitElement()`      | Parses the raw HTML fragment via `parseCodeFragment()` with `namelessFragment: true`, then delegates to parent with namespace and end tag handling |
+| `visitChildren()`     | Delegates to parent, then asserts no unexpected sibling nodes remain                                                                               |
+| `visitAttr()`         | Handles curly-brace expression values, shorthand attributes, and template directives                                                               |
+| `detectElementType()` | Detects component vs HTML element using `/^[A-Z]/` pattern (capitalized names are components)                                                      |
+
+## Frontmatter Handling
+
+Astro components can include a frontmatter block delimited by `---`:
+
+```astro
+---
+const name = "World";
+---
+<div>{name}</div>
+```
+
+The `astro-eslint-parser` produces a node with `type: 'frontmatter'`. The parser converts this to a **psblock** (pseudo-block) with `nodeName: 'Frontmatter'` and `isFragment: false`. The entire `---...---` block including delimiters is captured as a single opaque node. Content inside the frontmatter is not parsed as HTML.
+
+## Expression Handling
+
+Astro expressions (`{expression}`) are represented as `type: 'expression'` nodes in the Astro AST. The parser converts these to **MustacheTag** psblock nodes.
+
+### Simple Expressions
+
+A simple expression like `{name}` has a single text child. The entire expression is emitted as one MustacheTag psblock with `isFragment: true`.
+
+### Nested Expressions with HTML
+
+When an expression contains HTML elements (e.g., `{list.map(item => <li>{item}</li>)}`), the parser splits it into multiple nodes:
+
+1. **Opening expression fragment**: `{list.map(item => ` — a MustacheTag psblock containing the child nodes
+2. **Nested HTML elements**: `<li>{item}</li>` — processed as normal elements
+3. **Closing expression fragment**: `)}` — a separate MustacheTag psblock with `isFragment: false`
+
+The splitting logic checks whether `firstChild !== lastChild` in the expression's children array. If so:
+
+- The region from the expression start to the first child's end becomes the opening fragment
+- The region from the last child's start to the expression end becomes the closing fragment
+- The children between are visited normally within the opening fragment's psblock
+
+## Namespace Scoping
+
+The `#updateScopeNS()` private method manages namespace context as the parser traverses elements:
+
+| Condition                                                     | Action                                                  |
+| ------------------------------------------------------------- | ------------------------------------------------------- |
+| Current namespace is XHTML and node is `<svg>` element        | Switch `scopeNS` to `http://www.w3.org/2000/svg`        |
+| Current namespace is SVG and parent node is `<foreignObject>` | Switch `scopeNS` back to `http://www.w3.org/1999/xhtml` |
+
+This is called at the beginning of `nodeize()` before the node type switch, so all child nodes inherit the correct namespace. The namespace is applied to elements via `overwriteProps: { namespace: this.state.scopeNS }` in `visitElement()`.
+
+Example namespace resolution:
+
+```html
+<div>
+  <!-- XHTML -->
+  <svg>
+    <!-- SVG -->
+    <text />
+    <!-- SVG -->
+    <foreignObject>
+      <!-- SVG -->
+      <div />
+      <!-- XHTML (reset) -->
+    </foreignObject>
+  </svg>
+</div>
+```
+
+## Attribute Processing
+
+### Quote Set
+
+The `visitAttr()` method uses a custom quote set that includes curly braces for expression values:
+
+| Start | End | Type     |
+| ----- | --- | -------- |
+| `"`   | `"` | `string` |
+| `'`   | `'` | `string` |
+| `{`   | `}` | `script` |
+
+### Shorthand Attributes
+
+When an attribute token starts with `{` (e.g., `{prop}`), the parser sets `startState: AttrState.BeforeValue`, which skips name parsing and goes directly to value extraction. The resulting attribute has:
+
+- `name.raw` = `''` (empty)
+- `value.raw` = `prop`
+- `potentialName` = `prop` (inferred from value)
+- `isDynamicValue` = `true`
+
+### Template Directives
+
+Astro template directives use the `name:modifier` syntax. The parser detects these with the regex `/^([^:]+):([^:]+)$/`:
+
+| Directive      | `potentialName` | `isDirective` | Behavior                            |
+| -------------- | --------------- | ------------- | ----------------------------------- |
+| `class:list`   | `'class'`       | `undefined`   | Maps to standard `class` attribute  |
+| `set:html`     | `undefined`     | `true`        | Treated as Astro-specific directive |
+| `set:text`     | `undefined`     | `true`        | Treated as Astro-specific directive |
+| `is:raw`       | `undefined`     | `true`        | Treated as Astro-specific directive |
+| `transition:*` | `undefined`     | `true`        | Treated as Astro-specific directive |
+
+The `class` directive is special: it gets `potentialName: 'class'` so markuplint rules for the `class` attribute apply. All other directives get `isDirective: true`, which tells markuplint they are framework-specific and should not be validated as standard HTML attributes.
+
+### Dynamic Values
+
+Any attribute whose start quote is `{` gets `isDynamicValue: true`. This applies to:
+
+- Explicit dynamic values: `prop={value}`
+- Shorthand attributes: `{prop}`
+- Nested expressions: `style={{ a: b }}`
+
+## Comparison with jsx-parser
+
+| Feature                   | `astro-parser`                  | `jsx-parser`                                    |
+| ------------------------- | ------------------------------- | ----------------------------------------------- |
+| **Tokenizer**             | `astro-eslint-parser`           | TypeScript ESTree (`@typescript-eslint/parser`) |
+| **Frontmatter**           | Supported (`---...---` psblock) | Not applicable                                  |
+| **Expression syntax**     | `{expr}` as MustacheTag psblock | `{expr}` as JSXExpressionContainer psblock      |
+| **Template directives**   | `class:list`, `set:html`, etc.  | Not applicable                                  |
+| **Namespace management**  | Manual via `#updateScopeNS()`   | Delegates to `getNamespace()` from html-parser  |
+| **Component detection**   | `/^[A-Z]/` pattern              | `/^[A-Z]/` pattern                              |
+| **Self-close type**       | `html+xml`                      | Default (XML-only)                              |
+| **Booleanish attributes** | Not configured                  | `booleanish: true`                              |
+| **Nameless fragments**    | `<>...</>` supported            | `<>...</>` supported                            |
+| **Spread attributes**     | Handled by base parser          | Custom `visitSpreadAttr()` with IDL lookup      |
+
+## Version Compatibility
+
+The parsing chain depends on:
+
+```
+astro-eslint-parser → @astrojs/compiler → Astro syntax support
+```
+
+`astro-eslint-parser` is a runtime dependency that provides `parseTemplate()`. `@astrojs/compiler` is a dev dependency used only for AST type definitions (`Node`, `RootNode`, `ElementNode`, etc.). When updating `astro-eslint-parser`, the `@astrojs/compiler` dev dependency should also be updated to match the version that `astro-eslint-parser` uses internally.
+
+## Key Source Files
+
+| File              | Purpose                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| `parser.ts`       | `AstroParser` class — all override methods and namespace scoping                                   |
+| `astro-parser.ts` | `astroParse()` wrapper — delegates to `astro-eslint-parser`, converts diagnostics to `ParserError` |
+| `index.ts`        | Public API — re-exports the singleton `parser` instance                                            |
+
+## 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/astro-parser@4.6.20...@markuplint/astro-parser@4.6.21) (2025-08-24)
+## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/astro-parser@4.6.22...@markuplint/astro-parser@4.6.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/astro-parser
 
+## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/astro-parser@4.6.21...@markuplint/astro-parser@4.6.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/astro-parser
 
+## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/astro-parser@4.6.20...@markuplint/astro-parser@4.6.21) (2025-08-24)
 
+**Note:** Version bump only for package @markuplint/astro-parser
 
 ## [4.6.20](https://github.com/markuplint/markuplint/compare/@markuplint/astro-parser@4.6.19...@markuplint/astro-parser@4.6.20) (2025-08-13)
 

package/SKILL.md

@@ -0,0 +1,109 @@
+---
+description: Maintenance tasks for @markuplint/astro-parser
+globs:
+  - packages/@markuplint/astro-parser/src/**/*.ts
+alwaysApply: false
+---
+
+# astro-parser-maintenance
+
+Perform maintenance tasks for `@markuplint/astro-parser`: add template directives,
+modify namespace scoping, update expression handling, and manage astro-eslint-parser integration.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                         | Description                                         |
+| ---------------------------- | --------------------------------------------------- |
+| `add-directive`              | Add a new Astro template directive                  |
+| `modify-namespace-scoping`   | Modify SVG/XHTML namespace scoping logic            |
+| `update-expression-handling` | Update expression splitting or MustacheTag handling |
+
+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, attribute processing, namespace scoping
+- `src/parser.ts` -- AstroParser class (source of truth for override methods)
+- `src/astro-parser.ts` -- astro-eslint-parser wrapper
+
+## Task: add-directive
+
+Add a new Astro template directive. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Understand the directive pattern
+
+1. Read `src/parser.ts` — the `visitAttr()` method
+2. Identify the regex: `/^([^:]+):([^:]+)$/`
+3. Understand the `switch (lowerCaseDirectiveName)` block
+
+### Step 2: Add the directive case
+
+1. Add a new `case` in the switch for the directive prefix
+2. Decide whether it maps to a `potentialName` (like `class:list` → `class`) or is a pure directive (`isDirective: true`)
+3. If it maps to a standard HTML attribute, set `potentialName` to the attribute name
+4. If it is Astro-specific, set `isDirective = true`
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/astro-parser`
+2. Add test cases to `src/parser.spec.ts` using `nodeListToDebugMaps`
+3. Test: `yarn test --scope @markuplint/astro-parser`
+
+## Task: modify-namespace-scoping
+
+Modify the SVG/XHTML namespace scoping logic. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Understand the current logic
+
+1. Read `src/parser.ts` — the `#updateScopeNS()` private method
+2. Understand the two conditions: `<svg>` → SVG namespace, `<foreignObject>` parent → XHTML namespace
+3. Note that `scopeNS` is applied in `visitElement()` via `overwriteProps`
+
+### Step 2: Make the change
+
+1. Add or modify conditions in `#updateScopeNS()`
+2. For new namespaces (e.g., MathML), add a new condition checking `originNode.name`
+3. Ensure the namespace URI constant is correct
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/astro-parser`
+2. Add namespace test cases to `src/parser.spec.ts`
+3. Test: `yarn test --scope @markuplint/astro-parser`
+
+## Task: update-expression-handling
+
+Update expression splitting or MustacheTag handling. Follow recipe #3 in `docs/maintenance.md`.
+
+### Step 1: Understand the current logic
+
+1. Read `src/parser.ts` — the `case 'expression'` block in `nodeize()`
+2. Understand the splitting logic: `firstChild !== lastChild` check
+3. Understand how opening and closing fragments are created
+
+### Step 2: Make the change
+
+1. Modify the splitting logic in the `expression` case
+2. Ensure `startExpressionRaw` and `startExpressionStartLine`/`startExpressionStartCol` are correctly set
+3. Ensure the closing fragment location is correctly calculated from `lastChild`
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/astro-parser`
+2. Test with expressions containing nested HTML (e.g., `{list.map(item => <li>{item}</li>)}`)
+3. Test: `yarn test --scope @markuplint/astro-parser`
+
+## Rules
+
+1. **Delegate tokenization to astro-eslint-parser** — never parse Astro syntax manually; always use `astroParse()`.
+2. **Use `potentialName` for attribute mapping** — when a directive maps to a standard HTML attribute, set `potentialName` instead of modifying the attribute name.
+3. **Test with `nodeListToDebugMaps`** — all parser tests should use `nodeListToDebugMaps` for snapshot-style assertions that verify positions, names, and types.
+4. **Maintain `scopeNS` state** — namespace scoping must be updated before node type dispatch in `nodeize()`.
+5. **Add JSDoc comments** to all new public methods and properties.

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,2 @@
+import type { MLASTBlockBehavior } from '@markuplint/ml-ast';
+export declare function detectBlockBehavior(raw: string): MLASTBlockBehavior | null;

package/lib/detect-block-behavior.js

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

@@ -5,6 +5,13 @@ import { Parser } from '@markuplint/parser-utils';
 type State = {
     scopeNS: string;
 };
+/**
+ * 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`), shorthand attributes, and namespace-aware
+ * element resolution (XHTML vs SVG).
+ */
 declare class AstroParser extends Parser<Node, State> {
     #private;
     constructor();
@@ -12,10 +19,46 @@ declare class AstroParser extends Parser<Node, State> {
         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. Manages namespace scoping for SVG elements.
+     *
+     * @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 namespace scoping and 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;
     }) | {

package/lib/parser.js

@@ -6,6 +6,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _AstroParser_instances, _AstroParser_updateScopeNS;
 import { AttrState, Parser, ParserError } from '@markuplint/parser-utils';
 import { astroParse } from './astro-parser.js';
+/**
+ * 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`), shorthand attributes, and namespace-aware
+ * element resolution (XHTML vs SVG).
+ */
 class AstroParser extends Parser {
     constructor() {
         super({
@@ -23,6 +30,16 @@ class AstroParser extends Parser {
             isFragment: true,
         };
     }
+    /**
+     * Converts an Astro AST node into markuplint node tree items.
+     * Handles frontmatter, doctype, text, comment, component/element/fragment,
+     * and expression nodes. Manages namespace scoping for SVG elements.
+     *
+     * @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(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, parentNode, depth) {
@@ -125,6 +142,15 @@ class AstroParser extends Parser {
             exposeInvalidNode: false,
         });
     }
+    /**
+     * 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 namespace scoping and 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, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     childNodes) {
@@ -154,6 +180,15 @@ class AstroParser extends Parser {
             },
         });
     }
+    /**
+     * 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(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     children, parentNode) {
@@ -163,6 +198,14 @@ class AstroParser extends Parser {
         }
         return [];
     }
+    /**
+     * 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) {
         const attr = super.visitAttr(token, {
             quoteSet: [

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/astro-parser",
-	"version": "4.6.21",
+	"version": "4.6.23",
 	"description": "astro parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -21,12 +21,12 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/parser-utils": "4.8.9",
+		"@markuplint/ml-ast": "4.4.11",
+		"@markuplint/parser-utils": "4.8.11",
 		"astro-eslint-parser": "1.2.2"
 	},
 	"devDependencies": {
-		"@astrojs/compiler": "2.12.2"
+		"@astrojs/compiler": "2.13.1"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }