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

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。式が `.map()` または `.filter()` 呼び出しを含む場合（`detectBlockBehavior()` で検出）、開始フラグメントにはそれぞれ `blockBehavior: { type: 'each' }` または `{ type: 'if' }` が設定される
+2. **ネストされた HTML 要素**: `<li>{item}</li>` — 通常の要素として処理
+3. **終了式フラグメント**: `)}` — `isFragment: false` の別の MustacheTag psblock。開始フラグメントに `blockBehavior` がある場合、終了フラグメントには `blockBehavior: { type: 'end' }` が設定される
+
+分割ロジックは式の 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. If the expression contains a `.map()` or `.filter()` call (detected by `detectBlockBehavior()`), the opening fragment receives `blockBehavior: { type: 'each' }` or `{ type: 'if' }` respectively
+2. **Nested HTML elements**: `<li>{item}</li>` — processed as normal elements
+3. **Closing expression fragment**: `)}` — a separate MustacheTag psblock with `isFragment: false`. If the opening fragment had a `blockBehavior`, the closing fragment receives `blockBehavior: { type: 'end' }`
+
+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,37 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/astro-parser@4.6.21...@markuplint/astro-parser@4.6.22) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/astro-parser
+### Bug Fixes
+
+- **ml-core:** improve detection of namespace ([5b507ad](https://github.com/markuplint/markuplint/commit/5b507ad7c19c5015b8ce587845d901e31dfa6518))
+
+- refactor(astro-parser)!: update for simplified AST token properties ([4c05de1](https://github.com/markuplint/markuplint/commit/4c05de151d30233a8d4a184c4cb70c26de19b36b))
+
+### Features
+
+- **astro-parser:** support loop blocks ([ebe2eb6](https://github.com/markuplint/markuplint/commit/ebe2eb6b85aa32ff3f29964e333d058afe99d18b))
 
+### BREAKING CHANGES
 
+- Adapt to renamed token properties and remove
+  selfClosingSolidus test.
 
+* Token property access: startOffset -> offset, startLine -> line,
+  startCol -> col
+* Replace selfClosingSolidus check with tagCloseChar
+* Remove selfClosingSolidus test case
 
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+## [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)
 

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.