@markuplint/parser-utils 4.8.10 → 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,208 @@
+# @markuplint/parser-utils
+
+## 概要
+
+`@markuplint/parser-utils` は全 markuplint パーサーの共通基盤パッケージです。完全なパースパイプラインを実装する抽象 `Parser` クラスと、トークン化、エラー処理、デバッグ、AST 操作のためのユーティリティモジュール群を提供します。すべてのマークアップ言語パーサー（HTML、JSX、Vue、Svelte、Astro、Pug）はこのパッケージの `Parser` クラスを拡張し、言語固有の AST ノードを `@markuplint/ml-ast` で定義された統一 markuplint AST 形式に変換します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts               — 全パブリック API の再エクスポート
+├── parser.ts              — abstract class Parser<Node, State>（約1825行、コア）
+├── types.ts               — ParserOptions, ParseOptions, Token, ChildToken, IgnoreTag 等
+├── enums.ts               — TagState, AttrState ステートマシン
+├── attr-tokenizer.ts      — 属性トークナイザ（AttrState 使用）
+├── script-parser.ts       — espree による JavaScript パース
+├── ignore-block.ts        — テンプレート式のマスキングと復元
+├── ignore-front-matter.ts — YAML フロントマター検出・マスキング
+├── detect-element-type.ts — 要素種別判定（html/web-component/authored）
+├── idl-attributes.ts      — IDL ↔ コンテンツ属性名マッピング（React 互換）
+├── debugger.ts            — デバッグ・テスト用ユーティリティ
+├── parser-error.ts        — ParserError, TargetParserError, ConfigParserError
+├── sort-nodes.ts          — ノード位置ソート
+├── const.ts               — MASK_CHAR, SVG 要素リスト, defaultSpaces
+├── get-location.ts        — 行/列/オフセット計算ユーティリティ
+└── decision.ts            — カスタム要素名判定
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph core ["コアモジュール"]
+        parser["parser.ts\nabstract Parser"]
+    end
+
+    subgraph utils ["ユーティリティモジュール"]
+        attrTokenizer["attr-tokenizer.ts\n属性トークナイザ"]
+        ignoreBlock["ignore-block.ts\nマスク・復元"]
+        ignoreFM["ignore-front-matter.ts\nフロントマター"]
+        detectType["detect-element-type.ts\n要素種別判定"]
+        scriptParser["script-parser.ts\nJS パース"]
+        idlAttrs["idl-attributes.ts\nIDL マッピング"]
+    end
+
+    subgraph support ["サポートモジュール"]
+        enums["enums.ts\nTagState, AttrState"]
+        errors["parser-error.ts\nエラークラス"]
+        debugger["debugger.ts\nデバッグ"]
+        location["get-location.ts\n位置計算"]
+        sort["sort-nodes.ts\nソート"]
+        consts["const.ts\n定数"]
+        decision["decision.ts\nカスタム要素名"]
+    end
+
+    subgraph deps ["外部依存"]
+        mlAst["@markuplint/ml-ast\n型定義"]
+        mlSpec["@markuplint/ml-spec\nvoid 要素"]
+        espree["espree\nJS トークナイザ"]
+        cryptoLib["node:crypto\nノード ID"]
+    end
+
+    parser --> attrTokenizer
+    parser --> ignoreBlock
+    parser --> ignoreFM
+    parser --> detectType
+    parser --> enums
+    parser --> errors
+    parser --> location
+    parser --> sort
+    parser --> consts
+
+    attrTokenizer --> enums
+    attrTokenizer --> scriptParser
+    scriptParser --> espree
+    detectType --> decision
+    ignoreBlock --> location
+    ignoreBlock --> errors
+
+    parser --> mlAst
+    parser --> mlSpec
+    parser --> cryptoLib
+    decision --> mlAst
+```
+
+## モジュール責務
+
+| モジュール               | 責務                                       | 主要エクスポート                                                                                                                          |
+| ------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `parser.ts`              | コアパースパイプライン、抽象 Parser クラス | `Parser`                                                                                                                                  |
+| `types.ts`               | 型定義                                     | `ParserOptions`, `ParseOptions`, `Token`, `ChildToken`, `IgnoreTag`, `IgnoreBlock`, `QuoteSet`, `ValueType`, `SelfCloseType`, `Tokenized` |
+| `enums.ts`               | ステートマシン列挙型                       | `TagState`, `AttrState`                                                                                                                   |
+| `attr-tokenizer.ts`      | 属性文字列のトークン化                     | `attrTokenizer`                                                                                                                           |
+| `script-parser.ts`       | 組み込みスクリプトの JavaScript パース     | `scriptParser`, `safeScriptParser`                                                                                                        |
+| `ignore-block.ts`        | テンプレート式のマスキングと復元           | `ignoreBlock`, `restoreNode`                                                                                                              |
+| `ignore-front-matter.ts` | YAML フロントマター処理                    | `ignoreFrontMatter`                                                                                                                       |
+| `detect-element-type.ts` | 要素の分類                                 | `detectElementType`                                                                                                                       |
+| `idl-attributes.ts`      | IDL ↔ コンテンツ属性名マッピング           | `searchIDLAttribute`                                                                                                                      |
+| `debugger.ts`            | テスト・デバッグユーティリティ             | `nodeListToDebugMaps`, `attributesToDebugMaps`, `nodeTreeDebugView`                                                                       |
+| `parser-error.ts`        | エラークラス                               | `ParserError`, `TargetParserError`, `ConfigParserError`                                                                                   |
+| `sort-nodes.ts`          | ノードの位置ソート                         | `sortNodes`                                                                                                                               |
+| `const.ts`               | 定数                                       | `MASK_CHAR`, `svgElementList`, `defaultSpaces`                                                                                            |
+| `get-location.ts`        | 位置計算                                   | `getPosition`, `getEndLine`, `getEndCol`, `getEndPosition`, `getOffsetsFromCode`                                                          |
+| `decision.ts`            | カスタム要素名判定                         | `isPotentialCustomElementName`, `isSVGElement`                                                                                            |
+
+## パースパイプライン概要
+
+Parser クラスの `parse()` メソッドは11ステップのパイプラインを実行します:
+
+```mermaid
+flowchart LR
+    A["beforeParse"] --> B["frontMatter"]
+    B --> C["ignoreBlock"]
+    C --> D["tokenize"]
+    D --> E["traverse"]
+    E --> F["afterTraverse"]
+    F --> G["flatten"]
+    G --> H["afterFlatten"]
+    H --> I["restore"]
+    I --> J["afterParse"]
+```
+
+詳細は [Parser クラスリファレンス](docs/parser-class.ja.md) を参照してください。
+
+## ステートマシン概要
+
+パッケージには2つのステートマシンがあります:
+
+- **TagState** -- タグレベルのパースで使用（`<` 検出 → タグ名 → 属性 → `>` 検出）
+- **AttrState** -- 属性レベルのパースで使用（名前 → `=` → 値）
+
+詳細な状態遷移図は [Parser クラスリファレンス](docs/parser-class.ja.md#ステートマシン) を参照してください。
+
+## エラー処理
+
+```
+ParserError (基底クラス)
+├── line, col, raw — ソース位置情報
+├── TargetParserError — 特定要素に関するエラー（nodeName を含む）
+└── ConfigParserError — 設定ファイルのエラー（filePath を含む）
+```
+
+## デバッグユーティリティ
+
+- **`nodeListToDebugMaps`** -- AST ノードリストを人間が読めるデバッグ文字列に変換。スナップショットテストに使用
+- **`attributesToDebugMaps`** -- 属性を名前、等号、値、引用符の各部品に分解して表示
+- **`nodeTreeDebugView`** -- ツリー構造の可視化。深さ、親子関係、ペアノードを表示
+
+## IDL 属性マッピング
+
+`searchIDLAttribute` は React スタイルの IDL 属性名と HTML コンテンツ属性名の双方向マッピングを提供します（例: `className` → `class`、`htmlFor` → `for`）。spec が `useIDLAttributeNames: true` を設定している場合に、`@markuplint/ml-core` の `MLAttr` コンストラクタから呼び出されます。
+
+## 外部依存
+
+| 依存パッケージ        | 用途                               |
+| --------------------- | ---------------------------------- |
+| `@markuplint/ml-ast`  | AST 型定義                         |
+| `@markuplint/ml-spec` | void 要素判定                      |
+| `@markuplint/types`   | カスタム要素名検証                 |
+| `node:crypto`         | AST ノード UUID 生成               |
+| `debug`               | パフォーマンスタイミング・ロギング |
+| `espree`              | JavaScript トークン化・パース      |
+| `type-fest`           | TypeScript ユーティリティ型        |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        mlAst["@markuplint/ml-ast\n型定義"]
+        mlSpec["@markuplint/ml-spec\nvoid 要素判定"]
+    end
+
+    subgraph pkg ["@markuplint/parser-utils"]
+        parser["abstract Parser"]
+    end
+
+    subgraph downstream ["下流（パーサー群）"]
+        html["@markuplint/html-parser"]
+        jsx["@markuplint/jsx-parser"]
+        vue["@markuplint/vue-parser"]
+        svelte["@markuplint/svelte-parser"]
+        astro["@markuplint/astro-parser"]
+        pug["@markuplint/pug-parser"]
+    end
+
+    subgraph indirect ["間接的"]
+        mlCore["@markuplint/ml-core"]
+    end
+
+    upstream -->|"型・ユーティリティ"| pkg
+    pkg -->|"Parser クラスを拡張"| downstream
+    downstream -->|"MLASTDocument を生成"| mlCore
+```
+
+### 上流
+
+- **`@markuplint/ml-ast`** -- 全 AST 型定義（`MLASTElement`, `MLASTText` 等）
+- **`@markuplint/ml-spec`** -- `isVoidElement` による自己閉じタグ判定
+
+### 下流
+
+6つのパーサーパッケージが Parser クラスを拡張: html-parser, jsx-parser, vue-parser, svelte-parser, astro-parser, pug-parser
+
+## ドキュメントマップ
+
+- [Parser クラスリファレンス](docs/parser-class.ja.md) -- Parser クラスの完全リファレンス
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,251 @@
+# @markuplint/parser-utils
+
+## Overview
+
+`@markuplint/parser-utils` is the shared foundation for all markuplint parsers. It provides the abstract `Parser` class that implements the full parsing pipeline and a set of utility modules for tokenization, error handling, debugging, and AST manipulation. Every markup language parser (HTML, JSX, Vue, Svelte, Astro, Pug) extends this package's `Parser` class to convert language-specific AST nodes into the unified markuplint AST format defined by `@markuplint/ml-ast`.
+
+## Directory Structure
+
+```
+src/
+├── index.ts               — Re-exports all public API
+├── parser.ts              — Abstract class Parser<Node, State> (~1825 lines, core)
+├── types.ts               — ParserOptions, ParseOptions, Token, ChildToken, IgnoreTag, etc.
+├── enums.ts               — TagState, AttrState state machines
+├── attr-tokenizer.ts      — Attribute tokenizer (uses AttrState)
+├── script-parser.ts       — JavaScript parsing via espree
+├── ignore-block.ts        — Template expression masking and restoration
+├── ignore-front-matter.ts — YAML front matter detection and masking
+├── detect-element-type.ts — Element type classification (html/web-component/authored)
+├── idl-attributes.ts      — IDL <-> content attribute name mapping (React-compatible)
+├── debugger.ts            — Debug and test utilities (nodeListToDebugMaps, etc.)
+├── debug.ts               — Performance timer and debug logging via `debug` package
+├── parser-error.ts        — ParserError, TargetParserError, ConfigParserError
+├── sort-nodes.ts          — Node position sorting
+├── const.ts               — MASK_CHAR, SVG element list, defaultSpaces
+├── get-location.ts        — Line/column/offset calculation utilities
+└── decision.ts            — Custom element name detection
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph core ["Core"]
+        parser["parser.ts\nAbstract Parser Class"]
+        types["types.ts\nParserOptions, Token, etc."]
+        enums["enums.ts\nTagState, AttrState"]
+    end
+
+    subgraph tokenizer ["Tokenizer Utilities"]
+        attrTok["attr-tokenizer.ts\nattrTokenizer()"]
+        scriptParser["script-parser.ts\nscriptParser(), safeScriptParser()"]
+    end
+
+    subgraph masking ["Masking & Preprocessing"]
+        ignoreBlock["ignore-block.ts\nignoreBlock(), restoreNode()"]
+        ignoreFM["ignore-front-matter.ts\nignoreFrontMatter()"]
+    end
+
+    subgraph classification ["Classification"]
+        detectType["detect-element-type.ts\ndetectElementType()"]
+        decision["decision.ts\nisPotentialCustomElementName()"]
+        idlAttrs["idl-attributes.ts\nsearchIDLAttribute()"]
+    end
+
+    subgraph utilities ["Utilities"]
+        debugger["debugger.ts\nnodeListToDebugMaps()"]
+        debugMod["debug.ts\nPerformanceTimer, domLog()"]
+        parserError["parser-error.ts\nParserError hierarchy"]
+        sortNodes["sort-nodes.ts\nsortNodes()"]
+        getLoc["get-location.ts\ngetPosition(), getEndLine()"]
+        constMod["const.ts\nMASK_CHAR, svgElementList"]
+    end
+
+    subgraph external ["External Dependencies"]
+        mlAst["@markuplint/ml-ast\n(AST types)"]
+        mlSpec["@markuplint/ml-spec\n(void element detection)"]
+        mlTypes["@markuplint/types\n(custom element validation)"]
+        espree["espree\n(JS tokenization)"]
+        cryptoLib["node:crypto\n(node ID generation)"]
+        debugLib["debug\n(logging)"]
+    end
+
+    parser --> types
+    parser --> enums
+    parser --> attrTok
+    parser --> ignoreBlock
+    parser --> ignoreFM
+    parser --> detectType
+    parser --> sortNodes
+    parser --> getLoc
+    parser --> constMod
+    parser --> parserError
+    parser --> debugMod
+    attrTok --> enums
+    attrTok --> scriptParser
+    detectType --> decision
+    ignoreBlock --> constMod
+    ignoreBlock --> getLoc
+    decision --> mlTypes
+    parser --> mlAst
+    parser --> mlSpec
+    parser --> cryptoLib
+    scriptParser --> espree
+    debugMod --> debugLib
+```
+
+## Module Responsibilities
+
+| Module                   | Responsibility                                                                  | Key Exports                                                                                                                               |
+| ------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `parser.ts`              | Core parsing pipeline; abstract `Parser` class that all language parsers extend | `Parser`                                                                                                                                  |
+| `types.ts`               | Type definitions for parser configuration and tokenization                      | `ParserOptions`, `ParseOptions`, `Token`, `ChildToken`, `IgnoreTag`, `IgnoreBlock`, `QuoteSet`, `ValueType`, `SelfCloseType`, `Tokenized` |
+| `enums.ts`               | State machine enumerations for tag and attribute parsing                        | `TagState`, `AttrState`                                                                                                                   |
+| `attr-tokenizer.ts`      | Attribute string tokenization using `AttrState` state machine                   | `attrTokenizer`                                                                                                                           |
+| `script-parser.ts`       | JavaScript parsing for embedded scripts using espree                            | `scriptParser`, `safeScriptParser`                                                                                                        |
+| `ignore-block.ts`        | Template expression masking before parsing and restoration after                | `ignoreBlock`, `restoreNode`                                                                                                              |
+| `ignore-front-matter.ts` | YAML front matter detection and masking                                         | `ignoreFrontMatter`                                                                                                                       |
+| `detect-element-type.ts` | Element classification into `html`, `web-component`, or `authored`              | `detectElementType`                                                                                                                       |
+| `idl-attributes.ts`      | IDL-to-content attribute name mapping (React-compatible)                        | `searchIDLAttribute`                                                                                                                      |
+| `debugger.ts`            | Test and debug snapshot utilities                                               | `nodeListToDebugMaps`, `attributesToDebugMaps`, `nodeTreeDebugView`                                                                       |
+| `debug.ts`               | Performance timing and debug logging                                            | `PerformanceTimer`, `domLog`, `log`                                                                                                       |
+| `parser-error.ts`        | Error classes with positional information                                       | `ParserError`, `TargetParserError`, `ConfigParserError`                                                                                   |
+| `sort-nodes.ts`          | Node position sorting by offset                                                 | `sortNodes`                                                                                                                               |
+| `const.ts`               | Constants used across the package                                               | `MASK_CHAR`, `svgElementList`, `defaultSpaces`                                                                                            |
+| `get-location.ts`        | Line/column/offset position calculations                                        | `getPosition`, `getEndLine`, `getEndCol`, `getEndPosition`, `getOffsetsFromCode`                                                          |
+| `decision.ts`            | Custom element name detection and SVG element lookup                            | `isPotentialCustomElementName`, `isSVGElement`                                                                                            |
+
+## Parse Pipeline Overview
+
+The `Parser` class implements the complete parse pipeline. Each language-specific parser extends `Parser` and provides a `tokenize()` method that produces language-specific AST nodes, plus a `nodeize()` method that converts those nodes into markuplint AST nodes. See [Parser Class Reference](docs/parser-class.md) for the full pipeline documentation.
+
+```mermaid
+flowchart TD
+    source["Source Code"]
+    fm["ignoreFrontMatter()\nMask YAML front matter"]
+    ib["ignoreBlock()\nMask template expressions"]
+    tokenize["tokenize()\nLanguage-specific tokenization"]
+    traverse["traverse()\nWalk language AST"]
+    nodeize["nodeize()\nConvert to MLASTNode"]
+    flatten["flattenNodes()\nBuild flat node list"]
+    walk["walk()\nParent/child linking, depth"]
+    restore["restoreNode()\nRestore masked content"]
+    doc["MLASTDocument"]
+
+    source --> fm --> ib --> tokenize --> traverse --> nodeize --> flatten --> walk --> restore --> doc
+```
+
+## State Machines Overview
+
+The parser uses two state machine enumerations to drive character-by-character tokenization:
+
+**TagState** controls the tag-level parse loop:
+
+`BeforeOpenTag` -> `FirstCharOfTagName` -> `TagName` -> `Attrs` -> `AfterAttrs` -> `AfterOpenTag`
+
+**AttrState** controls the attribute-level parse loop:
+
+`BeforeName` -> `Name` -> `Equal` -> `BeforeValue` -> `Value` -> `AfterValue`
+
+See [Parser Class Reference](docs/parser-class.md) for detailed state transition diagrams.
+
+## Error Handling
+
+The package provides a three-level error class hierarchy for parser errors:
+
+| Class               | Extends       | Additional Fields    | Purpose                                                                      |
+| ------------------- | ------------- | -------------------- | ---------------------------------------------------------------------------- |
+| `ParserError`       | `Error`       | `line`, `col`, `raw` | Base parser error with source position                                       |
+| `TargetParserError` | `ParserError` | `nodeName`           | Error tied to a specific element, includes the element name in the message   |
+| `ConfigParserError` | `ParserError` | `filePath`           | Error from configuration file parsing, includes the file path in the message |
+
+All error classes automatically format their messages with positional information (e.g., `(line:col)`).
+
+## Debug Utilities
+
+The package provides three debug functions for testing and visualization:
+
+- **`nodeListToDebugMaps`** -- Converts a flat AST node list into human-readable debug strings showing each node's position, type, and raw content. The primary tool for snapshot testing in parser tests.
+- **`attributesToDebugMaps`** -- Converts attributes into detailed debug strings showing all attribute components (name, equal sign, value, quotes) with positional information and metadata flags (`isDirective`, `isDynamicValue`).
+- **`nodeTreeDebugView`** -- Produces an indented tree view of the AST showing depth, parent-child relationships, pair node links, and ghost/bogus markers. Useful for visual inspection of parse results.
+
+Additionally, `debug.ts` provides `PerformanceTimer` for measuring parse phase durations and `domLog` for structured logging via the `debug` package (enabled with `DEBUG=ml-parser`).
+
+## IDL Attribute Mapping
+
+`searchIDLAttribute` maps between React-style IDL attribute names and HTML content attribute names. It is called by `@markuplint/ml-core`'s `MLAttr` constructor when the spec sets `useIDLAttributeNames: true`. It maintains a comprehensive mapping table derived from React's `possibleStandardNames.js`, covering:
+
+- HTML attributes (e.g., `className` -> `class`, `htmlFor` -> `for`, `tabIndex` -> `tabindex`)
+- SVG attributes (e.g., `strokeWidth` -> `stroke-width`, `clipPath` -> `clip-path`)
+- Event handler attributes (e.g., `onClick` -> `onclick`)
+
+The lookup handles camelCase IDL names, lowercase content attribute names, and hyphenated variants.
+
+## External Dependencies
+
+| Dependency            | Purpose                                                                    |
+| --------------------- | -------------------------------------------------------------------------- |
+| `@markuplint/ml-ast`  | AST type definitions (`MLASTDocument`, `MLASTElement`, `MLASTToken`, etc.) |
+| `@markuplint/ml-spec` | Void element detection (`isVoidElement`) for self-closing tag handling     |
+| `@markuplint/types`   | Custom element name validation (`isCustomElementName`)                     |
+| `node:crypto`         | AST node UUID generation via `crypto.randomUUID()`                         |
+| `debug`               | Performance timing and structured logging                                  |
+| `espree`              | JavaScript tokenization and parsing for embedded script content            |
+| `type-fest`           | TypeScript utility types                                                   |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        mlAst["@markuplint/ml-ast\n(AST type definitions)"]
+        mlSpec["@markuplint/ml-spec\n(void element detection)"]
+        mlTypes["@markuplint/types\n(custom element validation)"]
+    end
+
+    subgraph pkg ["@markuplint/parser-utils"]
+        parser["Abstract Parser Class\n+ Utility Modules"]
+    end
+
+    subgraph downstream ["Downstream Parsers"]
+        htmlParser["@markuplint/html-parser"]
+        jsxParser["@markuplint/jsx-parser"]
+        vueParser["@markuplint/vue-parser"]
+        svelteParser["@markuplint/svelte-parser"]
+        astroParser["@markuplint/astro-parser"]
+        pugParser["@markuplint/pug-parser"]
+    end
+
+    subgraph indirect ["Indirect Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument -> MLDOM)"]
+    end
+
+    upstream -->|"types, specs"| parser
+    parser -->|"extends Parser"| downstream
+    downstream -->|"produces MLASTDocument"| mlCore
+```
+
+### Upstream
+
+- **`@markuplint/ml-ast`** -- All AST type definitions (`MLASTDocument`, `MLASTElement`, `MLASTAttr`, `MLASTToken`, etc.) that the Parser class produces.
+- **`@markuplint/ml-spec`** -- `isVoidElement` function used to determine self-closing behavior for HTML void elements.
+- **`@markuplint/types`** -- `isCustomElementName` function used by `decision.ts` to validate custom element names per the HTML spec.
+
+### Downstream
+
+Six parser packages extend the abstract `Parser` class:
+
+- **`@markuplint/html-parser`** -- Standard HTML parsing
+- **`@markuplint/jsx-parser`** -- JSX/TSX parsing (extends html-parser)
+- **`@markuplint/vue-parser`** -- Vue Single File Component parsing
+- **`@markuplint/svelte-parser`** -- Svelte component parsing
+- **`@markuplint/astro-parser`** -- Astro component parsing
+- **`@markuplint/pug-parser`** -- Pug template parsing
+
+Each downstream parser implements the `tokenize()` and `nodeize()` abstract methods to convert their language-specific AST into the unified markuplint AST format.
+
+## Documentation Map
+
+- [Parser Class Reference](docs/parser-class.md) -- Detailed documentation of the Parser class, its methods, and parse pipeline
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,44 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.8.10](https://github.com/markuplint/markuplint/compare/@markuplint/parser-utils@4.8.9...@markuplint/parser-utils@4.8.10) (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/parser-utils
+### Bug Fixes
+
+- **ml-core:** improve detection of namespace ([5b507ad](https://github.com/markuplint/markuplint/commit/5b507ad7c19c5015b8ce587845d901e31dfa6518))
+- resolve additional eslint-plugin-unicorn v63 errors ([e58a72c](https://github.com/markuplint/markuplint/commit/e58a72c17c97bbec522f9513b99777fac6904d64))
+- use explicit `export type` for type-only re-exports ([7c77c05](https://github.com/markuplint/markuplint/commit/7c77c05619518c8d18a183132040f5b2cd0ab6ec))
+
+- feat(parser-utils)!: adapt to simplified MLASTToken properties ([5cbbc9c](https://github.com/markuplint/markuplint/commit/5cbbc9ca8f77a71d99bffa14b193c79b26c1c415))
+
+### BREAKING CHANGES
+
+- Update Token type and parser internals for
+  simplified AST token properties.
+
+Token type property renames:
 
+- startOffset -> offset
+- startLine -> line
+- startCol -> col
 
+Parser changes:
 
+- createToken() no longer produces endOffset/endLine/endCol
+- visitPsBlock() parameter: conditionalType -> blockBehavior
+- visitElement() accepts blockBehavior option
+- Remove selfClosingSolidus token generation
+- Add getEndPosition() helper to get-location.ts
 
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+## [4.8.11](https://github.com/markuplint/markuplint/compare/@markuplint/parser-utils@4.8.10...@markuplint/parser-utils@4.8.11) (2026-02-10)
+
+**Note:** Version bump only for package @markuplint/parser-utils
+
+## [4.8.10](https://github.com/markuplint/markuplint/compare/@markuplint/parser-utils@4.8.9...@markuplint/parser-utils@4.8.10) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/parser-utils
 
 ## [4.8.9](https://github.com/markuplint/markuplint/compare/@markuplint/parser-utils@4.8.8...@markuplint/parser-utils@4.8.9) (2025-08-24)
 

package/README.md

@@ -16,3 +16,9 @@ $ yarn add @markuplint/parser-utils
 ```
 
 </details>
+
+## Documentation
+
+- [Architecture](ARCHITECTURE.md) ([日本語](ARCHITECTURE.ja.md)) — Package overview, module relationships, and integration points
+- [Parser Class Reference](docs/parser-class.md) ([日本語](docs/parser-class.ja.md)) — Complete reference for the abstract `Parser` class
+- [Maintenance Guide](docs/maintenance.md) ([日本語](docs/maintenance.ja.md)) — Commands, recipes, and troubleshooting

package/SKILL.md

@@ -0,0 +1,126 @@
+---
+description: Perform maintenance tasks for @markuplint/parser-utils
+---
+
+# parser-utils-maintenance
+
+Perform maintenance tasks for `@markuplint/parser-utils`: create new parsers,
+add ignore tag patterns, add IDL attribute mappings, and customize attribute parsing.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                       | Description                                |
+| -------------------------- | ------------------------------------------ |
+| `create-parser`            | Create a new parser extending Parser class |
+| `add-ignore-tag <type>`    | Add an IgnoreTag pattern                   |
+| `add-idl-attribute <name>` | Add an IDL attribute mapping               |
+| `customize-attr-parsing`   | Customize attribute parsing behavior       |
+
+If omitted, defaults to `create-parser`.
+
+## 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:
+
+- `docs/parser-class.md` -- Complete Parser class reference with override patterns
+- `ARCHITECTURE.md` -- Package overview, module relationships, and integration points
+
+## Task: create-parser
+
+Create a new parser extending the abstract Parser class. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Set up the package
+
+1. Create a new package under `packages/@markuplint/`
+2. Add `@markuplint/parser-utils` as a dependency
+3. Create the main parser file extending `Parser<YourNode, YourState>`
+
+### Step 2: Implement required methods
+
+1. Read `docs/parser-class.md` for the full override pattern reference
+2. Implement `tokenize()` -- invoke the language-specific tokenizer on `this.rawCode`
+3. Implement `nodeize()` -- convert each AST node using visitor methods
+4. Set constructor options (`endTagType`, `tagNameCaseSensitive`, `ignoreTags`, etc.)
+
+### Step 3: Export the parser module
+
+1. Export as `MLParserModule`: `export default { parser: new MyParser() }`
+2. Build: `yarn build --scope @markuplint/<package-name>`
+3. Test with `nodeListToDebugMaps` snapshot assertions
+
+## Task: add-ignore-tag
+
+Add an IgnoreTag pattern for masking template expressions. Follow recipe #3 in `docs/maintenance.md`.
+
+### Step 1: Define the pattern
+
+1. Identify the start and end delimiters of the template expression
+2. Choose a `type` name (becomes the `#ps:` node name prefix)
+3. Start and end can be strings or RegExp patterns
+
+### Step 2: Add to constructor
+
+1. Add the `IgnoreTag` entry to the `ignoreTags` array in the parser constructor
+2. Consider if a custom `maskChar` is needed (default is `\uE000`)
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/<package-name>`
+2. Test that the template expression is correctly masked and restored
+3. Verify the restored node has the expected `#ps:<type>` name
+
+## Task: add-idl-attribute
+
+Add an IDL attribute mapping. Follow recipe #5 in `docs/maintenance.md`.
+
+### Step 1: Add the mapping
+
+1. Read `src/idl-attributes.ts` and find the `idlContentMap` object
+2. Add a new entry: `idlPropName: 'content-attr-name'`
+3. Follow naming conventions: key is camelCase IDL name, value is lowercase content name
+
+### Step 2: Verify
+
+1. Build: `yarn build --scope @markuplint/parser-utils`
+2. Test with `searchIDLAttribute()` to confirm the mapping resolves correctly
+
+## Task: customize-attr-parsing
+
+Customize attribute parsing behavior for a specific parser. Follow recipe #4 in `docs/maintenance.md`.
+
+### Step 1: Override visitAttr
+
+1. Read `docs/parser-class.md` for the `visitAttr()` documentation
+2. Override `visitAttr()` in your parser subclass
+3. Call `super.visitAttr(token, options)` with custom options:
+   - `quoteSet` -- custom quote delimiters (e.g., `{` `}` for JSX)
+   - `startState` -- initial AttrState (usually `BeforeName`)
+   - `noQuoteValueType` -- value type for unquoted values
+
+### Step 2: Post-process
+
+1. After calling `super`, use `this.updateAttr()` to set metadata:
+   - `isDirective` for framework directives
+   - `isDynamicValue` for dynamic bindings
+   - `potentialName` for directive-to-attribute name resolution
+2. Use `searchIDLAttribute()` to resolve IDL property names
+
+### Step 3: Verify
+
+1. Build the parser package
+2. Test attribute parsing with `attributesToDebugMaps` for snapshot assertions
+3. Verify all framework-specific directive patterns are recognized
+
+## Rules
+
+1. **Always call `super.visitAttr()`** when overriding. It handles token decomposition.
+2. **Always call `super.detectElementType()`** when overriding. Pass framework-specific patterns as the `defaultPattern` argument.
+3. **Never call `super.tokenize()` or `super.nodeize()`** -- the defaults return empty arrays.
+4. **Always call `super.beforeParse()` and `super.afterParse()`** -- they handle offset spaces.
+5. **Test across all downstream parsers** when modifying the Parser class.
+6. **Add JSDoc comments** to all new public methods and properties.