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

package/ARCHITECTURE.ja.md

@@ -1,203 +0,0 @@
-# @markuplint/astro-parser
-
-## 概要
-
-`@markuplint/astro-parser` は markuplint における Astro コンポーネントファイル（`.astro`）のパーサーです。`astro-eslint-parser`（`@astrojs/compiler` をラップ）を使用して Astro ソースコードをトークン化し、その結果の AST を markuplint の統一 AST 形式（`MLASTDocument`）に変換します。フロントマターブロック（`---...---`）、式コンテナ（`{expression}`）、テンプレートディレクティブ（例: `class:list`、`set:html`、`client:load`）、ショートハンド属性（`{prop}`）など、Astro 固有の構文を処理します。
-
-## ディレクトリ構成
-
-```
-src/
-├── index.ts                    — parser インスタンスを再エクスポート
-├── parser.ts                   — Parser<Node> を拡張する AstroParser クラス
-├── astro-parser.ts             — astro-eslint-parser ラッパーと型の再エクスポート
-├── detect-block-behavior.ts    — .map()/.filter() のブロック動作検出
-├── component-scanner.ts        — pretenders 自動スキャン用コンポーネントスキャナー（サブパスエクスポート）
-├── parser.spec.ts              — AstroParser 統合テスト
-├── astro-parser.spec.ts        — astro-eslint-parser ラッパーテスト
-└── component-scanner.spec.ts   — コンポーネントスキャナーのテスト
-```
-
-## アーキテクチャ図
-
-```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›"]
-        astroParseFn["astroParse()\nastro-eslint-parser ラッパー"]
-        detectBlock["detectBlockBehavior()\n.map()/.filter() 検出"]
-        compScanner["componentScanner\n(サブパス: ./component-scanner)"]
-    end
-
-    subgraph downstream ["下流"]
-        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
-        pretenders["@markuplint/pretenders\n(自動スキャン)"]
-    end
-
-    mlAst -->|"AST 型"| astroParser
-    parserUtils -->|"Parser 基底クラス"| astroParser
-    astroEslintParser -->|"parseTemplate()"| astroParseFn
-    astroCompiler -->|"Node 型"| astroParseFn
-    astroParseFn -->|"RootNode.children"| astroParser
-    detectBlock -->|"blockBehavior"| astroParser
-    astroParser -->|"MLASTDocument を生成"| mlCore
-    astroParser -->|"parse()"| compScanner
-    compScanner -->|"ComponentScanResult"| pretenders
-```
-
-## AstroParser クラス
-
-### 継承関係
-
-```
-Parser<Node>  (@markuplint/parser-utils)
-    └── AstroParser  (このパッケージ)
-```
-
-### コンストラクタ
-
-コンストラクタは Astro 固有のオプションで基底 `Parser` を設定します:
-
-| オプション             | 値           | 用途                                                                         |
-| ---------------------- | ------------ | ---------------------------------------------------------------------------- |
-| `endTagType`           | `'xml'`      | Astro は XML のように明示的な閉じタグを使用                                  |
-| `selfCloseType`        | `'html+xml'` | HTML void 要素と XML スタイルの自己閉じ（`<Component />`）の両方を受け入れる |
-| `tagNameCaseSensitive` | `true`       | コンポーネント（`<MyComp>`）と HTML 要素（`<div>`）を区別                    |
-
-### オーバーライドメソッド
-
-| メソッド              | 用途                                                                                                                           |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `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 内で通常通り訪問される
-
-## 属性処理
-
-### クォートセット
-
-`visitAttr()` メソッドは式の値用に波括弧を含むカスタムクォートセットを使用します:
-
-| 開始 | 終了 | タイプ   |
-| ---- | ---- | -------- |
-| `"`  | `"`  | `string` |
-| `'`  | `'`  | `string` |
-| `{`  | `}`  | `script` |
-
-### ショートハンド属性
-
-属性トークンが `{` で始まる場合（例: `{prop}`）、パーサーは `startState: AttrState.BeforeValue` を設定し、名前のパースをスキップして直接値の抽出に進みます。結果の属性は:
-
-- `name.raw` = `''`（空）
-- `value.raw` = `prop`
-- `potentialName` = `prop`（値から推論）
-- `isDynamicValue` = `true`
-
-### テンプレートディレクティブ
-
-Astro テンプレートディレクティブは `name:modifier` 構文を使用します。パーサーは正規表現 `/^([^:]+):([^:]+)$/` でこれらを検出します:
-
-| ディレクティブプレフィックス | `potentialName` | `isDirective` | 動作                                                  |
-| ---------------------------- | --------------- | ------------- | ----------------------------------------------------- |
-| `class:`                     | `'class'`       | `false`       | 標準の `class` 属性にマッピング                       |
-| `client:`                    | —               | `true`        | Astro クライアントディレクティブ（load, idle 等）     |
-| `server:`                    | —               | `true`        | Astro サーバーディレクティブ（defer）                 |
-| `set:`                       | —               | `true`        | コンテンツディレクティブ（html, text）                |
-| `is:`                        | —               | `true`        | プロパティディレクティブ（inline, raw）               |
-| `define:`                    | —               | `true`        | スタイルディレクティブ（vars）                        |
-| `transition:`                | —               | `true`        | View Transition ディレクティブ（animate, name）       |
-| _（その他すべて）_           | —               | `true`        | キャッチオール: すべての `prefix:name` パターンに適用 |
-
-`class:` プレフィックスは特別扱いで、`potentialName: 'class'` を取得するため、`class` 属性に対する markuplint ルールが適用されます。その他のコロン区切りプレフィックスは `default` ケースに該当し `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` 等            | 該当なし                                          |
-| **名前空間管理**               | 基底 `Parser` に委譲                   | 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` インスタンスを再エクスポート                                                 |
-| `component-scanner.ts` | `@markuplint/pretenders` 自動スキャン用コンポーネントスキャナー（サブパスエクスポート `./component-scanner`） |
-
-## ドキュメントマップ
-
-- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -1,203 +0,0 @@
-# @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`, `client:load`), and shorthand attributes (`{prop}`).
-
-## Directory Structure
-
-```
-src/
-├── index.ts                    — Re-exports parser instance
-├── parser.ts                   — AstroParser class extending Parser<Node>
-├── astro-parser.ts             — astro-eslint-parser wrapper and type re-exports
-├── detect-block-behavior.ts    — Detects .map()/.filter() for block behavior
-├── component-scanner.ts        — Component scanner for pretenders auto scan (subpath export)
-├── parser.spec.ts              — AstroParser integration tests
-├── astro-parser.spec.ts        — astro-eslint-parser wrapper tests
-└── component-scanner.spec.ts   — Tests for component scanner
-```
-
-## 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›"]
-        astroParseFn["astroParse()\nastro-eslint-parser wrapper"]
-        detectBlock["detectBlockBehavior()\n.map()/.filter() detection"]
-        compScanner["componentScanner\n(subpath: ./component-scanner)"]
-    end
-
-    subgraph downstream ["Downstream"]
-        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
-        pretenders["@markuplint/pretenders\n(auto scan)"]
-    end
-
-    mlAst -->|"AST types"| astroParser
-    parserUtils -->|"Parser base class"| astroParser
-    astroEslintParser -->|"parseTemplate()"| astroParseFn
-    astroCompiler -->|"Node types"| astroParseFn
-    astroParseFn -->|"RootNode.children"| astroParser
-    detectBlock -->|"blockBehavior"| astroParser
-    astroParser -->|"produces MLASTDocument"| mlCore
-    astroParser -->|"parse()"| compScanner
-    compScanner -->|"ComponentScanResult"| pretenders
-```
-
-## AstroParser Class
-
-### Inheritance
-
-```
-Parser<Node>  (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>`)           |
-
-### 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 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
-
-## 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 prefix | `potentialName` | `isDirective` | Behavior                                        |
-| ---------------- | --------------- | ------------- | ----------------------------------------------- |
-| `class:`         | `'class'`       | `false`       | Maps to standard `class` attribute              |
-| `client:`        | —               | `true`        | Astro client directive (load, idle, visible...) |
-| `server:`        | —               | `true`        | Astro server directive (defer)                  |
-| `set:`           | —               | `true`        | Content directive (html, text)                  |
-| `is:`            | —               | `true`        | Property directive (inline, raw)                |
-| `define:`        | —               | `true`        | Style directive (vars)                          |
-| `transition:`    | —               | `true`        | View Transition directive (animate, name)       |
-| _(any other)_    | —               | `true`        | Catch-all: any `prefix:name` pattern            |
-
-The `class:` prefix is special-cased: it gets `potentialName: 'class'` so markuplint rules for the `class` attribute apply. All other colon-separated prefixes hit the `default` case and 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**  | Delegates to base `Parser`      | 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                                            |
-| `component-scanner.ts` | Component scanner for `@markuplint/pretenders` auto scan (subpath export `./component-scanner`)    |
-
-## Documentation Map
-
-- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/SKILL.md

@@ -1,133 +0,0 @@
----
-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 |
-| `update-component-scanner`   | Update component-scanner for pretenders auto scan   |
-
-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, directive handling
-- `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. Namespace resolution is handled by the base `Parser` class from `@markuplint/parser-utils`
-2. The Astro parser does **not** override namespace logic — there is no `#updateScopeNS()` method
-3. Any namespace changes require modifications in the base `Parser` class or adding an override in `AstroParser`
-
-### Step 2: Make the change
-
-1. If adding namespace handling to the Astro parser, override the relevant method from the base `Parser`
-2. For new namespaces (e.g., MathML), add a 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`
-
-## Task: update-component-scanner
-
-Update `src/component-scanner.ts` when Astro slot syntax or frontmatter handling changes.
-
-### When to update
-
-- New slot-like syntax is added to Astro
-- Frontmatter delimiter handling needs to change
-- The `extractComponentInfo` shared logic needs a fix (also update vue-parser and svelte-parser)
-
-### Step 1: Make the change
-
-1. Read `src/component-scanner.ts`
-2. Modify `detectSlots()` for new slot patterns, or `extractAstroFrontmatter()` for frontmatter changes
-3. If modifying `extractComponentInfo()`, apply the same change to all three parsers (vue, svelte, astro)
-
-### Step 2: Verify
-
-1. Update tests in `src/component-scanner.spec.ts`
-2. Build: `yarn build --scope @markuplint/astro-parser`
-3. Test: `npx vitest run packages/@markuplint/astro-parser/src/component-scanner.spec.ts`
-4. Run pretenders integration tests: `npx vitest run packages/@markuplint/pretenders`
-
-## 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.