@markuplint/mustache-parser 4.6.22 → 4.6.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,106 @@
+# @markuplint/mustache-parser
+
+## 概要
+
+`@markuplint/mustache-parser` は `HtmlParser` を拡張し、Mustache および Handlebars テンプレート式を含む HTML ファイルのリントを可能にします。完全なテンプレートパーサーを実装するのではなく、`HtmlParser` の `ignoreTags` メカニズムを設定して Mustache/Handlebars 構文を不透明なブロックとして扱います。これにより、markuplint はテンプレート式をスキップしながら周囲の HTML 構造を検証できます。
+
+Handlebars は Mustache のスーパーセットであり、同じデリミタ構文を使用するため、このパッケージは Handlebars とも互換性があります。
+
+## 動作原理
+
+パーサーは `HtmlParser` のコンストラクタで3つの `ignoreTags` エントリを宣言することで動作します。トークン化の際、基底 `Parser` クラスがソース内でこれらのデリミタペアを検索し、`#ps:*`（PreprocessorSpecific）ノードとして抽出し、残りの HTML を通常通りパースします。
+
+`ignoreTags` エントリの順序は重要です。より具体的なパターンを、より一般的なパターンの前に配置する必要があります。例えば、`{{{`（トリプルスタッシュ）は `{{`（ダブルスタッシュ）の前にマッチする必要があり、`{{!`（コメント）も `{{` の前にマッチする必要があります。
+
+## ignoreTags 設定
+
+| タイプ               | 開始  | 終了  | 説明                                                     |
+| -------------------- | ----- | ----- | -------------------------------------------------------- |
+| `mustache-comment`   | `{{!` | `}}`  | Mustache コメント（`{{! comment }}`）                    |
+| `mustache-unescaped` | `{{{` | `}}}` | エスケープなし / トリプルスタッシュ出力（`{{{ raw }}}`） |
+| `mustache-tag`       | `{{`  | `}}`  | 標準的な補間とブロックヘルパー                           |
+
+マッチした式は `#ps:mustache-tag`、`#ps:mustache-unescaped`、`#ps:mustache-comment` のような名前を持つ AST ノードになります。
+
+## サポートされない構文
+
+**引用符なしの属性値**内のテンプレート式はサポートされていません。これはすべてのテンプレートエンジンパーサーに共通する既知の制限です（[#240](https://github.com/markuplint/markuplint/issues/240)）。[ウェブサイトのドキュメント](https://markuplint.dev/docs/guides/besides-html)も参照してください。
+
+使用可能:
+
+```html
+<div attr="{{ value }}"></div>
+<div attr="{{ value }}"></div>
+<div attr="{{ value }}-{{ value2 }}-{{ value3 }}"></div>
+```
+
+使用不可（引用符なし）:
+
+```html
+<div attr="{{" value }}></div>
+```
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts        — parser シングルトンを再エクスポート
+├── parser.ts       — HtmlParser を拡張する MustacheParser クラス
+└── index.spec.ts   — タグ認識とノードリスト構造のテスト
+```
+
+## 主要ソースファイル
+
+### `parser.ts`
+
+上記3つの `ignoreTags` エントリを持つ `MustacheParser`（`HtmlParser` を拡張）を定義します。シングルトンインスタンスが `parser` としてエクスポートされます。
+
+### `index.ts`
+
+`parser.ts` から `parser` をパブリック API として再エクスポートします。
+
+### `index.spec.ts`
+
+テストカバレッジ:
+
+- テキストや HTML 要素に挟まれた単一・複数の `{{ }}` タグ
+- ネストされた HTML を含むブロックヘルパー（`{{#user}}...{{/user}}`）
+- ベアテキスト（HTML 要素でラップされていない場合）
+- 各タグタイプの正しい `nodeName`（`#ps:mustache-tag`、`#ps:mustache-unescaped`、`#ps:mustache-comment`）
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser 基底クラス)"]
+        parserUtils["@markuplint/parser-utils\n(抽象 Parser, nodeListToDebugMaps)"]
+    end
+
+    subgraph pkg ["@markuplint/mustache-parser"]
+        mustacheParser["MustacheParser\nextends HtmlParser"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument -> MLDOM)"]
+        config["markuplint 設定\n(parser オプション)"]
+    end
+
+    htmlParser -->|"継承"| mustacheParser
+    parserUtils -->|"テストユーティリティ"| mustacheParser
+    mustacheParser -->|"MLASTDocument を生成"| mlCore
+    config -->|"パーサーを選択"| mustacheParser
+```
+
+### 上流
+
+- **`@markuplint/html-parser`** -- `MustacheParser` が拡張する基底クラス `HtmlParser` を提供。HTML パースロジック（parse5 統合、ゴースト要素、名前空間解決）はすべて継承される。
+
+### 下流
+
+- **`@markuplint/ml-core`** -- このパーサーが生成する `MLASTDocument` を消費
+- **markuplint 設定** -- ユーザーが markuplint 設定の `parser` オプションでこのパーサーを選択
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# @markuplint/mustache-parser
+
+## Overview
+
+`@markuplint/mustache-parser` extends `HtmlParser` to lint HTML files containing Mustache and Handlebars template expressions. Instead of implementing a full template parser, it configures `HtmlParser`'s `ignoreTags` mechanism to treat Mustache/Handlebars syntax as opaque blocks. This lets markuplint validate the surrounding HTML structure while skipping over template expressions.
+
+The package is also compatible with Handlebars, since Handlebars is a superset of Mustache and uses the same delimiter syntax.
+
+## How It Works
+
+The parser works by declaring three `ignoreTags` entries in the `HtmlParser` constructor. During tokenization, the base `Parser` class scans the source for these delimiter pairs, extracts them as `#ps:*` (PreprocessorSpecific) nodes, and parses the remaining HTML normally.
+
+The order of `ignoreTags` entries matters: more specific patterns must appear before less specific ones. For example, `{{{` (triple-stache) must be matched before `{{` (double-stache), and `{{!` (comment) must be matched before `{{` as well.
+
+## ignoreTags Configuration
+
+| Type                 | Start | End   | Description                                      |
+| -------------------- | ----- | ----- | ------------------------------------------------ |
+| `mustache-comment`   | `{{!` | `}}`  | Mustache comments (`{{! comment }}`)             |
+| `mustache-unescaped` | `{{{` | `}}}` | Unescaped / triple-stache output (`{{{ raw }}}`) |
+| `mustache-tag`       | `{{`  | `}}`  | Standard interpolation and block helpers         |
+
+Matched expressions become AST nodes with names like `#ps:mustache-tag`, `#ps:mustache-unescaped`, and `#ps:mustache-comment`.
+
+## Unsupported Syntaxes
+
+Template expressions inside **unquoted attribute values** are not supported. This is a known limitation shared by all template engine parsers ([#240](https://github.com/markuplint/markuplint/issues/240)). See also the [website documentation](https://markuplint.dev/docs/guides/besides-html).
+
+Available:
+
+```html
+<div attr="{{ value }}"></div>
+<div attr="{{ value }}"></div>
+<div attr="{{ value }}-{{ value2 }}-{{ value3 }}"></div>
+```
+
+Unavailable (unquoted):
+
+```html
+<div attr="{{" value }}></div>
+```
+
+## Directory Structure
+
+```
+src/
+├── index.ts        — Re-exports the parser singleton
+├── parser.ts       — MustacheParser class extending HtmlParser
+└── index.spec.ts   — Tests for tag recognition and node list structure
+```
+
+## Key Source Files
+
+### `parser.ts`
+
+Defines `MustacheParser` which extends `HtmlParser` with the three `ignoreTags` entries listed above. A singleton instance is exported as `parser`.
+
+### `index.ts`
+
+Re-exports `parser` from `parser.ts` as the public API.
+
+### `index.spec.ts`
+
+Tests cover:
+
+- Single and multiple `{{ }}` tags interleaved with text and HTML elements
+- Block helpers (`{{#user}}...{{/user}}`) with nested HTML
+- Bare text (no wrapping HTML element)
+- Correct `nodeName` for each tag type (`#ps:mustache-tag`, `#ps:mustache-unescaped`, `#ps:mustache-comment`)
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser base class)"]
+        parserUtils["@markuplint/parser-utils\n(Abstract Parser, nodeListToDebugMaps)"]
+    end
+
+    subgraph pkg ["@markuplint/mustache-parser"]
+        mustacheParser["MustacheParser\nextends HtmlParser"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument -> MLDOM)"]
+        config["markuplint config\n(parser option)"]
+    end
+
+    htmlParser -->|"extends"| mustacheParser
+    parserUtils -->|"test utility"| mustacheParser
+    mustacheParser -->|"produces MLASTDocument"| mlCore
+    config -->|"selects parser"| mustacheParser
+```
+
+### Upstream
+
+- **`@markuplint/html-parser`** -- Provides `HtmlParser`, the base class that `MustacheParser` extends. All HTML parsing logic (parse5 integration, ghost elements, namespace resolution) is inherited.
+
+### Downstream
+
+- **`@markuplint/ml-core`** -- Consumes the `MLASTDocument` produced by this parser
+- **markuplint config** -- Users select this parser via the `parser` option in their markuplint configuration
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,13 @@
 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/mustache-parser@4.6.21...@markuplint/mustache-parser@4.6.22) (2025-11-05)
+## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/mustache-parser@4.6.22...@markuplint/mustache-parser@4.6.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/mustache-parser
 
+## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/mustache-parser@4.6.21...@markuplint/mustache-parser@4.6.22) (2025-11-05)
 
-
-
+**Note:** Version bump only for package @markuplint/mustache-parser
 
 ## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/mustache-parser@4.6.20...@markuplint/mustache-parser@4.6.21) (2025-08-24)
 

package/SKILL.md

@@ -0,0 +1,100 @@
+---
+description: Perform maintenance tasks for @markuplint/mustache-parser
+globs:
+  - packages/@markuplint/mustache-parser/src/**
+alwaysApply: false
+---
+
+# mustache-parser-maintenance
+
+Perform maintenance tasks for `@markuplint/mustache-parser`: modify ignoreTags configuration,
+add new Mustache/Handlebars tag types, and update parser behavior.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task               | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `modify-ignoretag` | Modify or add an ignoreTags entry            |
+| `fix-parsing`      | Fix a parsing issue with Mustache/Handlebars |
+| `update-tests`     | Add or update test cases                     |
+
+If omitted, defaults to `modify-ignoretag`.
+
+## 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, ignoreTags configuration, and integration points
+- `src/parser.ts` -- MustacheParser class (source of truth for ignoreTags)
+
+## Task: modify-ignoretag
+
+Modify or add an ignoreTags entry. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Understand the current configuration
+
+1. Read `src/parser.ts` and review the existing `ignoreTags` array
+2. Understand the matching order: more specific patterns must come before less specific ones
+
+### Step 2: Make the change
+
+1. Add or modify the entry in the `ignoreTags` array in the `MustacheParser` constructor
+2. Ensure correct ordering (e.g., `{{{` before `{{`, `{{!` before `{{`)
+3. Each entry needs `type`, `start`, and `end` properties
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/mustache-parser`
+2. Add test cases to `src/index.spec.ts` for the new tag type
+3. Test: `yarn test --scope @markuplint/mustache-parser`
+
+## Task: fix-parsing
+
+Fix a parsing issue with Mustache/Handlebars templates. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Reproduce the issue
+
+1. Create a minimal HTML template that demonstrates the parsing problem
+2. Write a failing test case in `src/index.spec.ts`
+
+### Step 2: Investigate
+
+1. Read `src/parser.ts` to check if the issue is in the ignoreTags configuration
+2. If the issue is in the base parser, check `@markuplint/html-parser` (HtmlParser)
+
+### Step 3: Fix and verify
+
+1. Apply the fix
+2. Build: `yarn build --scope @markuplint/mustache-parser`
+3. Test: `yarn test --scope @markuplint/mustache-parser`
+
+## Task: update-tests
+
+Add or update test cases. Follow recipe #3 in `docs/maintenance.md`.
+
+### Step 1: Understand the testing pattern
+
+1. Read `src/index.spec.ts` to understand the existing test structure
+2. Tests use `nodeListToDebugMaps` from `@markuplint/parser-utils` for assertions
+
+### Step 2: Write the tests
+
+1. Use `parser.parse()` to parse the template
+2. Assert against `nodeListToDebugMaps(doc.nodeList)` for node structure
+3. Assert against `doc.nodeList[n]?.nodeName` for individual node names
+
+### Step 3: Verify
+
+1. Test: `yarn test --scope @markuplint/mustache-parser`
+
+## Rules
+
+1. **Maintain ignoreTags ordering** -- more specific patterns (`{{{`, `{{!`) must appear before the general `{{` pattern.
+2. **Keep the parser minimal** -- this package only configures `ignoreTags`; HTML parsing logic belongs in `@markuplint/html-parser`.
+3. **Add JSDoc comments** to all new public exports.
+4. **Test all tag types** when modifying the ignoreTags configuration.

package/docs/maintenance.ja.md

@@ -0,0 +1,120 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                         | 説明                   |
+| ------------------------------------------------ | ---------------------- |
+| `yarn build --scope @markuplint/mustache-parser` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/mustache-parser`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/mustache-parser` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/mustache-parser`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル  | カバレッジ                                                 |
+| --------------- | ---------------------------------------------------------- |
+| `index.spec.ts` | タグ認識、ノードリスト構造、ブロックヘルパー、ベアテキスト |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const doc = parser.parse('<div>{{ name }}</div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:15](5,14)#ps:mustache-tag: {{␣name␣}}',
+  '[1:15]>[1:21](14,20)div: </div>',
+]);
+```
+
+個別のタグタイプのアサーション:
+
+```ts
+expect(parse('{{ any }}').nodeList[0]?.nodeName).toBe('#ps:mustache-tag');
+expect(parse('{{{ any }}}').nodeList[0]?.nodeName).toBe('#ps:mustache-unescaped');
+expect(parse('{{! any }}').nodeList[0]?.nodeName).toBe('#ps:mustache-comment');
+```
+
+## レシピ
+
+### 1. ignoreTags エントリの追加・変更
+
+1. `src/parser.ts` を読み、`MustacheParser` コンストラクタの `ignoreTags` 配列を確認
+2. エントリを追加または変更し、正しい順序を維持:
+   - より具体的な開始デリミタは、より一般的なものの前に配置する必要がある
+   - 現在の順序: `{{!` -> `{{{` -> `{{`
+3. 各エントリには `type`（文字列識別子）、`start`（開始デリミタ）、`end`（終了デリミタ）が必要
+4. ビルド: `yarn build --scope @markuplint/mustache-parser`
+5. `src/index.spec.ts` にテストケースを追加し、新しいタグタイプが正しい `#ps:*` ノード名を生成することを検証
+6. テスト: `yarn test --scope @markuplint/mustache-parser`
+
+### 2. パース問題の修正
+
+1. 最小限の再現テンプレートを作成し、`src/index.spec.ts` に失敗するテストを記述
+2. 問題の所在を特定:
+   - **ignoreTags 設定**（このパッケージ）-- デリミタのマッチング、順序
+   - **基底 HTML パーサー**（`@markuplint/html-parser`）-- HTML 構造処理
+3. 適切なパッケージで修正を適用
+4. ビルドとテスト: `yarn build --scope @markuplint/mustache-parser && yarn test --scope @markuplint/mustache-parser`
+5. 修正が `@markuplint/html-parser` にある場合: `yarn test --scope @markuplint/html-parser` も実行
+
+### 3. テストケースの追加
+
+1. `src/index.spec.ts` を読み、既存のテスト構造を理解
+2. ノードリストテストには `nodeListToDebugMaps` パターンを使用:
+   ```ts
+   const doc = parse('テンプレート文字列');
+   expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([...]);
+   ```
+3. タグタイプテストには `nodeName` でアサート:
+   ```ts
+   expect(parse('{{ expr }}').nodeList[0]?.nodeName).toBe('#ps:mustache-tag');
+   ```
+4. テスト: `yarn test --scope @markuplint/mustache-parser`
+
+## 上流の影響
+
+このパッケージは `@markuplint/html-parser` に依存しています。`HtmlParser` の変更（特に `ignoreTags` 処理、`visitText`、`researchTags` メカニズム）はこのパーサーに影響を与える可能性があります。
+
+`@markuplint/html-parser` が更新された場合は、以下を実行してください:
+
+```shell
+yarn test --scope @markuplint/mustache-parser
+```
+
+## トラブルシューティング
+
+### Mustache タグが認識されない
+
+**症状:** `{{ name }}` のような Mustache 式が `#ps:mustache-tag` ノードではなく生テキストとして表示される。
+
+**原因:** `ignoreTags` エントリが欠落しているか、start/end デリミタが不正。
+
+**解決策:**
+
+1. `src/parser.ts` を確認 -- `ignoreTags` 配列に `start: '{{'` と `end: '}}'` のエントリが含まれていることを検証
+2. エントリの順序を確認 -- より具体的なパターンが先に配置されている必要がある
+
+### トリプルスタッシュがダブルスタッシュとしてパースされる
+
+**症状:** `{{{ raw }}}` が `#ps:mustache-unescaped` ではなく `#ps:mustache-tag` ノードを生成する。
+
+**原因:** `mustache-unescaped` エントリ（`{{{` / `}}}`）が `mustache-tag` エントリ（`{{` / `}}`）の後に配置されているため、より一般的なパターンが先にマッチする。
+
+**解決策:**
+
+1. `ignoreTags` 配列内で `mustache-unescaped` エントリを `mustache-tag` エントリの前に移動
+
+### コメントタグが通常のタグとしてパースされる
+
+**症状:** `{{! comment }}` が `#ps:mustache-comment` ではなく `#ps:mustache-tag` ノードを生成する。
+
+**原因:** `mustache-comment` エントリ（`{{!` / `}}`）が `mustache-tag` エントリ（`{{` / `}}`）の後に配置されている。
+
+**解決策:**
+
+1. `ignoreTags` 配列内で `mustache-comment` エントリが `mustache-tag` エントリの前にリストされていることを確認

package/docs/maintenance.md

@@ -0,0 +1,120 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                          | Description            |
+| ------------------------------------------------ | ---------------------- |
+| `yarn build --scope @markuplint/mustache-parser` | Build this package     |
+| `yarn dev --scope @markuplint/mustache-parser`   | Watch mode build       |
+| `yarn clean --scope @markuplint/mustache-parser` | Remove build artifacts |
+| `yarn test --scope @markuplint/mustache-parser`  | Run tests              |
+
+## Testing
+
+Test files follow the `*.spec.ts` naming convention and are located in the `src/` directory:
+
+| Test File       | Coverage                                                       |
+| --------------- | -------------------------------------------------------------- |
+| `index.spec.ts` | Tag recognition, node list structure, block helpers, bare text |
+
+The primary testing pattern uses `nodeListToDebugMaps` for snapshot-style assertions:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const doc = parser.parse('<div>{{ name }}</div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:15](5,14)#ps:mustache-tag: {{␣name␣}}',
+  '[1:15]>[1:21](14,20)div: </div>',
+]);
+```
+
+Individual tag type assertions:
+
+```ts
+expect(parse('{{ any }}').nodeList[0]?.nodeName).toBe('#ps:mustache-tag');
+expect(parse('{{{ any }}}').nodeList[0]?.nodeName).toBe('#ps:mustache-unescaped');
+expect(parse('{{! any }}').nodeList[0]?.nodeName).toBe('#ps:mustache-comment');
+```
+
+## Recipes
+
+### 1. Adding or Modifying an ignoreTags Entry
+
+1. Read `src/parser.ts` and review the `ignoreTags` array in the `MustacheParser` constructor
+2. Add or modify the entry, preserving correct ordering:
+   - More specific start delimiters must appear before less specific ones
+   - Current order: `{{!` -> `{{{` -> `{{`
+3. Each entry requires: `type` (string identifier), `start` (opening delimiter), `end` (closing delimiter)
+4. Build: `yarn build --scope @markuplint/mustache-parser`
+5. Add test cases to `src/index.spec.ts` to verify the new tag type produces the correct `#ps:*` node name
+6. Test: `yarn test --scope @markuplint/mustache-parser`
+
+### 2. Fixing a Parsing Issue
+
+1. Create a minimal reproducing template and write a failing test in `src/index.spec.ts`
+2. Determine whether the issue is in:
+   - **ignoreTags configuration** (this package) -- delimiter matching, ordering
+   - **Base HTML parser** (`@markuplint/html-parser`) -- HTML structure handling
+3. Apply the fix in the appropriate package
+4. Build and test: `yarn build --scope @markuplint/mustache-parser && yarn test --scope @markuplint/mustache-parser`
+5. If the fix is in `@markuplint/html-parser`, also run: `yarn test --scope @markuplint/html-parser`
+
+### 3. Adding Test Cases
+
+1. Read `src/index.spec.ts` to understand the existing test structure
+2. For node list tests, use the `nodeListToDebugMaps` pattern:
+   ```ts
+   const doc = parse('template string here');
+   expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([...]);
+   ```
+3. For tag type tests, assert against `nodeName`:
+   ```ts
+   expect(parse('{{ expr }}').nodeList[0]?.nodeName).toBe('#ps:mustache-tag');
+   ```
+4. Test: `yarn test --scope @markuplint/mustache-parser`
+
+## Upstream Impact
+
+This package depends on `@markuplint/html-parser`. Changes in `HtmlParser` (especially `ignoreTags` processing, `visitText`, or the `researchTags` mechanism) may affect this parser.
+
+When `@markuplint/html-parser` is updated, run:
+
+```shell
+yarn test --scope @markuplint/mustache-parser
+```
+
+## Troubleshooting
+
+### Mustache tags are not recognized
+
+**Symptom:** Mustache expressions like `{{ name }}` appear as raw text instead of `#ps:mustache-tag` nodes.
+
+**Cause:** The `ignoreTags` entry is missing or the start/end delimiters are incorrect.
+
+**Solution:**
+
+1. Check `src/parser.ts` -- verify the `ignoreTags` array includes an entry with `start: '{{'` and `end: '}}'`
+2. Verify the entry ordering -- more specific patterns must appear first
+
+### Triple-stache parsed as double-stache
+
+**Symptom:** `{{{ raw }}}` produces a `#ps:mustache-tag` node instead of `#ps:mustache-unescaped`.
+
+**Cause:** The `mustache-unescaped` entry (`{{{` / `}}}`) appears after the `mustache-tag` entry (`{{` / `}}`), so the less specific pattern matches first.
+
+**Solution:**
+
+1. Move the `mustache-unescaped` entry before the `mustache-tag` entry in the `ignoreTags` array
+
+### Comment tags parsed as regular tags
+
+**Symptom:** `{{! comment }}` produces a `#ps:mustache-tag` node instead of `#ps:mustache-comment`.
+
+**Cause:** The `mustache-comment` entry (`{{!` / `}}`) appears after the `mustache-tag` entry (`{{` / `}}`).
+
+**Solution:**
+
+1. Ensure the `mustache-comment` entry is listed before the `mustache-tag` entry in the `ignoreTags` array

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/mustache-parser
+ * Markuplint parser plugin for Mustache and Handlebars templates. Extends the standard
+ * HTML parser to treat Mustache/Handlebars tags, unescaped expressions, and comments
+ * as opaque blocks, allowing markuplint to lint the surrounding HTML structure.
+ */
 export { parser } from './parser.js';

package/lib/index.js

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/mustache-parser
+ * Markuplint parser plugin for Mustache and Handlebars templates. Extends the standard
+ * HTML parser to treat Mustache/Handlebars tags, unescaped expressions, and comments
+ * as opaque blocks, allowing markuplint to lint the surrounding HTML structure.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -1,6 +1,17 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for Mustache and Handlebars templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize Mustache/Handlebars tag variants as opaque blocks:
+ * - `{{! ... }}` (comments)
+ * - `{{{ ... }}}` (unescaped / triple-stache output)
+ * - `{{ ... }}` (standard interpolation and block helpers)
+ */
 declare class MustacheParser extends HtmlParser {
     constructor();
 }
+/**
+ * Singleton Mustache/Handlebars parser instance for use by the markuplint engine.
+ */
 export declare const parser: MustacheParser;
 export {};

package/lib/parser.js

@@ -1,4 +1,12 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for Mustache and Handlebars templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize Mustache/Handlebars tag variants as opaque blocks:
+ * - `{{! ... }}` (comments)
+ * - `{{{ ... }}}` (unescaped / triple-stache output)
+ * - `{{ ... }}` (standard interpolation and block helpers)
+ */
 class MustacheParser extends HtmlParser {
     constructor() {
         super({
@@ -22,4 +30,7 @@ class MustacheParser extends HtmlParser {
         });
     }
 }
+/**
+ * Singleton Mustache/Handlebars parser instance for use by the markuplint engine.
+ */
 export const parser = new MustacheParser();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/mustache-parser",
-	"version": "4.6.22",
+	"version": "4.6.23",
 	"description": "The mustache template parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -21,10 +21,10 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.22"
+		"@markuplint/html-parser": "4.6.23"
 	},
 	"devDependencies": {
-		"@markuplint/parser-utils": "4.8.10"
+		"@markuplint/parser-utils": "4.8.11"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }