@markuplint/erb-parser 4.6.21 → 4.6.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,88 @@
+# @markuplint/erb-parser
+
+## 概要
+
+`@markuplint/erb-parser` は、ERB（Embedded Ruby）テンプレート式を含む HTML をリントするために `HtmlParser` を拡張したテンプレートエンジンパーサーです。`ignoreTags` メカニズムを使用して ERB タグ（`<%= %>`、`<%# %>`、`<% %>`）を不透明なブロックとして扱い、Ruby コードを解釈せずに周囲の HTML 構造を検証できるようにします。
+
+## 動作の仕組み
+
+このパーサーは `HtmlParser`（`@markuplint/html-parser`）を継承し、親のコンストラクタに `ignoreTags` 設定を渡します。これにより、HTML パーサーが ERB タグパターンを認識し、HTML としてパースを試みる代わりに AST 内のプレースホルダーノード（`#ps:*`）に置換します。ERB 式はソースマッピングのためにノードの生コンテンツとしてそのまま保持されます。
+
+`ignoreTags` パターンは順番にマッチングされるため、より具体的なパターン（例: 式用の `<%=`）が汎用的な `<%`（Ruby コードブロック用）よりも先にチェックされます。`erb-ruby-code` パターンの否定先読み `(?!%)` により、`<%%`（エスケープされた ERB デリミタ）がマッチしないようになっています。
+
+## ignoreTags 設定
+
+| タイプ                | 開始パターン | 終了パターン | AST ノード名              | 説明                    |
+| --------------------- | ------------ | ------------ | ------------------------- | ----------------------- |
+| `erb-ruby-expression` | `<%=`        | `%>`         | `#ps:erb-ruby-expression` | Ruby 式の出力           |
+| `erb-comment`         | `<%#`        | `%>`         | `#ps:erb-comment`         | ERB コメント            |
+| `erb-ruby-code`       | `/<%(?!%)/`  | `%>`         | `#ps:erb-ruby-code`       | Ruby コード実行ブロック |
+
+**注意:** trim_mode（`%` プレフィックス行）は現在サポートされていません。将来の実装のためにコメントアウトされたエントリがあります。
+
+## サポートされない構文
+
+**引用符なしの属性値**内のテンプレート式はサポートされていません。これはすべてのテンプレートエンジンパーサーに共通する既知の制限です（[#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 を継承する ERubyParser クラス
+└── index.spec.ts   — ERB タグパースのテスト
+```
+
+## 主要ソースファイル
+
+| ファイル        | 用途                                                                        |
+| --------------- | --------------------------------------------------------------------------- |
+| `parser.ts`     | `ERubyParser` クラスを定義; `ignoreTags` を設定しシングルトンをエクスポート |
+| `index.ts`      | モジュールエントリポイント; `parser` を再エクスポート                       |
+| `index.spec.ts` | すべての ERB タグタイプと HTML/ERB 混在コンテンツのテスト                   |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser クラス)"]
+    end
+
+    subgraph pkg ["@markuplint/erb-parser"]
+        erbParser["ERubyParser\nextends HtmlParser\n(ignoreTags 設定のみ)"]
+    end
+
+    subgraph consumer ["コンシューマー"]
+        mlCore["@markuplint/ml-core\n(リントエンジン)"]
+    end
+
+    htmlParser -->|"継承"| erbParser
+    erbParser -->|"MLASTDocument を生成"| mlCore
+```
+
+### 上流
+
+- **`@markuplint/html-parser`** -- すべての HTML パースロジックと `ignoreTags` メカニズムを提供する `HtmlParser` 基底クラス
+
+### 下流
+
+このパッケージには下流のパーサー依存はありません。markuplint エンジンから直接使用されるリーフパーサーです。
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# @markuplint/erb-parser
+
+## Overview
+
+`@markuplint/erb-parser` is a template engine parser for markuplint that extends `HtmlParser` to lint HTML containing ERB (Embedded Ruby) template expressions. It uses the `ignoreTags` mechanism to treat ERB tags (`<%= %>`, `<%# %>`, `<% %>`) as opaque blocks, allowing markuplint to validate the surrounding HTML structure without interpreting the Ruby code.
+
+## How It Works
+
+The parser extends `HtmlParser` (from `@markuplint/html-parser`) and passes an `ignoreTags` configuration to the parent constructor. This tells the HTML parser to recognize ERB tag patterns and replace them with placeholder nodes (`#ps:*`) in the AST instead of attempting to parse them as HTML. The ERB expressions are preserved as-is in the node's raw content for source mapping purposes.
+
+The `ignoreTags` patterns are matched in order, so more specific patterns (e.g., `<%=` for expressions) are checked before the general `<%` pattern for Ruby code blocks. The negative lookahead `(?!%)` in the `erb-ruby-code` pattern prevents `<%%` (escaped ERB delimiters) from being matched.
+
+## ignoreTags Configuration
+
+| Type                  | Start Pattern | End Pattern | AST Node Name             | Description                |
+| --------------------- | ------------- | ----------- | ------------------------- | -------------------------- |
+| `erb-ruby-expression` | `<%=`         | `%>`        | `#ps:erb-ruby-expression` | Ruby expression output     |
+| `erb-comment`         | `<%#`         | `%>`        | `#ps:erb-comment`         | ERB comments               |
+| `erb-ruby-code`       | `/<%(?!%)/`   | `%>`        | `#ps:erb-ruby-code`       | Ruby code execution blocks |
+
+**Note:** trim_mode (`%`-prefixed lines) is not currently supported. There is a commented-out entry for future implementation.
+
+## 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 parser instance
+├── parser.ts       — ERubyParser class extending HtmlParser
+└── index.spec.ts   — Tests for ERB tag parsing
+```
+
+## Key Source Files
+
+| File            | Purpose                                                                    |
+| --------------- | -------------------------------------------------------------------------- |
+| `parser.ts`     | Defines `ERubyParser` class; configures `ignoreTags` and exports singleton |
+| `index.ts`      | Module entry point; re-exports `parser`                                    |
+| `index.spec.ts` | Tests covering all ERB tag types and mixed HTML/ERB content                |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser class)"]
+    end
+
+    subgraph pkg ["@markuplint/erb-parser"]
+        erbParser["ERubyParser\nextends HtmlParser\n(ignoreTags config only)"]
+    end
+
+    subgraph consumer ["Consumer"]
+        mlCore["@markuplint/ml-core\n(Lint engine)"]
+    end
+
+    htmlParser -->|"extends"| erbParser
+    erbParser -->|"produces MLASTDocument"| mlCore
+```
+
+### Upstream
+
+- **`@markuplint/html-parser`** -- Provides the `HtmlParser` base class that handles all HTML parsing logic and the `ignoreTags` mechanism
+
+### Downstream
+
+This package has no downstream parser dependencies. It is a leaf parser consumed directly by the markuplint engine.
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/erb-parser@4.6.20...@markuplint/erb-parser@4.6.21) (2025-08-24)
+## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/erb-parser@4.6.22...@markuplint/erb-parser@4.6.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/erb-parser
 
+## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/erb-parser@4.6.21...@markuplint/erb-parser@4.6.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/erb-parser
 
+## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/erb-parser@4.6.20...@markuplint/erb-parser@4.6.21) (2025-08-24)
 
+**Note:** Version bump only for package @markuplint/erb-parser
 
 ## [4.6.20](https://github.com/markuplint/markuplint/compare/@markuplint/erb-parser@4.6.19...@markuplint/erb-parser@4.6.20) (2025-08-13)
 

package/SKILL.md

@@ -0,0 +1,80 @@
+---
+description: Perform maintenance tasks for @markuplint/erb-parser
+globs:
+  - packages/@markuplint/erb-parser/src/**
+alwaysApply: false
+---
+
+# erb-parser-maintenance
+
+Perform maintenance tasks for `@markuplint/erb-parser`: add or modify ERB ignoreTags patterns.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                | Description                             |
+| ------------------- | --------------------------------------- |
+| `add-ignore-tag`    | Add a new ERB tag pattern to ignoreTags |
+| `modify-ignore-tag` | Modify an existing ignoreTags pattern   |
+
+If omitted, defaults to `add-ignore-tag`.
+
+## 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` -- ERubyParser class (source of truth for ignoreTags configuration)
+
+## Task: add-ignore-tag
+
+Add a new ERB tag pattern to the ignoreTags array. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Determine the pattern
+
+1. Read `src/parser.ts` to see existing ignoreTags entries
+2. Define the new tag's `type`, `start`, and `end` patterns
+3. Determine the correct position in the array (more specific patterns first)
+
+### Step 2: Add the entry
+
+1. Add the new entry to the `ignoreTags` array in the `ERubyParser` constructor
+2. Use a string for literal start patterns, or a regex for patterns requiring lookahead/lookbehind
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/erb-parser`
+2. Add test cases to `src/index.spec.ts` verifying the new tag type appears as `#ps:<type>` in the AST
+3. Test: `yarn test --scope @markuplint/erb-parser`
+
+## Task: modify-ignore-tag
+
+Modify an existing ignoreTags pattern. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Identify the pattern
+
+1. Read `src/parser.ts` and locate the ignoreTags entry to modify
+2. Understand why the change is needed (e.g., new ERB syntax, false matches)
+
+### Step 2: Make the change
+
+1. Update the `start`, `end`, or `type` fields as needed
+2. Ensure pattern ordering is still correct (more specific patterns first)
+3. If changing a regex pattern, verify it does not match escaped ERB delimiters (`<%%`)
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/erb-parser`
+2. Update test cases in `src/index.spec.ts` if the AST node names changed
+3. Test: `yarn test --scope @markuplint/erb-parser`
+
+## Rules
+
+1. **Pattern order matters** -- More specific patterns (e.g., `<%=`, `<%#`) must appear before general patterns (e.g., `/<%(?!%)/`).
+2. **Escaped delimiters** -- `<%%` must not be matched by any pattern. Use negative lookahead `(?!%)` on general patterns.
+3. **Add JSDoc comments** to document any new tag types.
+4. **No downstream impact** -- This is a leaf parser with no downstream dependencies.

package/docs/maintenance.ja.md

@@ -0,0 +1,78 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                    | 説明                   |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/erb-parser` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/erb-parser`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/erb-parser` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/erb-parser`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル  | カバレッジ                                                  |
+| --------------- | ----------------------------------------------------------- |
+| `index.spec.ts` | ERB タグパース、HTML/ERB 混在コンテンツ、エスケープデリミタ |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const parse = parser.parse.bind(parser);
+const doc = parse('<div><%= name %></div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:18](5,17)#ps:erb-ruby-expression: <%=\u2420name\u2420%>',
+  '[1:18]>[1:24](17,23)div: </div>',
+]);
+```
+
+タグタイプが正しく認識されているかの検証:
+
+```ts
+expect(parse('<%= any %>').nodeList[0].nodeName).toBe('#ps:erb-ruby-expression');
+expect(parse('<%# any %>').nodeList[0].nodeName).toBe('#ps:erb-comment');
+expect(parse('<% any %>').nodeList[0].nodeName).toBe('#ps:erb-ruby-code');
+```
+
+## レシピ
+
+### 1. 新しい ignoreTags パターンの追加
+
+1. `src/parser.ts` を読み、既存の `ignoreTags` 配列を確認
+2. 新しいタグの `type` 名を決定（命名規則: `erb-<説明>`）
+3. `start` と `end` パターンを定義:
+   - 固定の開始シーケンスには文字列リテラルを使用（例: `'<%='`）
+   - 先読み/後読みが必要なパターンには正規表現を使用（例: `/<%(?!%)/`）
+4. 正しい位置にエントリを挿入:
+   - より具体的なパターンを汎用パターンの前に配置
+   - 例: `<%=` を `<%` の前に
+5. `src/index.spec.ts` にテストケースを追加:
+   - ノード名が `#ps:<type>` であることを検証
+   - エスケープされたデリミタ（`<%%`）にマッチしないことを検証
+6. ビルドとテスト:
+
+```shell
+yarn build --scope @markuplint/erb-parser && yarn test --scope @markuplint/erb-parser
+```
+
+### 2. 既存の ignoreTags パターンの変更
+
+1. `src/parser.ts` を読み、変更するエントリを特定
+2. `start`、`end`、または `type` を変更
+3. 変更後もパターンの順序が正しいことを確認
+4. ノード名が変更された場合は `src/index.spec.ts` のテストケースを更新
+5. ビルドとテスト:
+
+```shell
+yarn build --scope @markuplint/erb-parser && yarn test --scope @markuplint/erb-parser
+```
+
+## 下流影響
+
+このパッケージには下流のパーサー依存はありません。markuplint エンジンから直接使用されるリーフパーサーであるため、変更が他のパーサーパッケージに影響を与えることはありません。

package/docs/maintenance.md

@@ -0,0 +1,78 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                     | Description            |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/erb-parser` | Build this package     |
+| `yarn dev --scope @markuplint/erb-parser`   | Watch mode build       |
+| `yarn clean --scope @markuplint/erb-parser` | Remove build artifacts |
+| `yarn test --scope @markuplint/erb-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` | ERB tag parsing, mixed HTML/ERB content, escaped delimiters |
+
+The primary testing pattern uses `nodeListToDebugMaps` for snapshot-style assertions:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const parse = parser.parse.bind(parser);
+const doc = parse('<div><%= name %></div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:18](5,17)#ps:erb-ruby-expression: <%=\u2420name\u2420%>',
+  '[1:18]>[1:24](17,23)div: </div>',
+]);
+```
+
+To verify a tag type is correctly recognized:
+
+```ts
+expect(parse('<%= any %>').nodeList[0].nodeName).toBe('#ps:erb-ruby-expression');
+expect(parse('<%# any %>').nodeList[0].nodeName).toBe('#ps:erb-comment');
+expect(parse('<% any %>').nodeList[0].nodeName).toBe('#ps:erb-ruby-code');
+```
+
+## Recipes
+
+### 1. Adding a New ignoreTags Pattern
+
+1. Read `src/parser.ts` and review the existing `ignoreTags` array
+2. Determine the new tag's `type` name (convention: `erb-<description>`)
+3. Define the `start` and `end` patterns:
+   - Use a string literal for fixed start sequences (e.g., `'<%='`)
+   - Use a regex for patterns requiring lookahead/lookbehind (e.g., `/<%(?!%)/`)
+4. Insert the entry in the correct position:
+   - More specific patterns must come before general patterns
+   - Example: `<%=` before `<%`
+5. Add test cases to `src/index.spec.ts`:
+   - Verify the node name is `#ps:<type>`
+   - Verify it doesn't match escaped delimiters (`<%%`)
+6. Build and test:
+
+```shell
+yarn build --scope @markuplint/erb-parser && yarn test --scope @markuplint/erb-parser
+```
+
+### 2. Modifying an Existing ignoreTags Pattern
+
+1. Read `src/parser.ts` and locate the entry to modify
+2. Make the change to `start`, `end`, or `type`
+3. Verify pattern ordering is still correct after the change
+4. Update test cases in `src/index.spec.ts` if node names changed
+5. Build and test:
+
+```shell
+yarn build --scope @markuplint/erb-parser && yarn test --scope @markuplint/erb-parser
+```
+
+## Downstream Impact
+
+This package has no downstream parser dependencies. It is a leaf parser consumed directly by the markuplint engine, so changes do not affect other parser packages.

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/erb-parser
+ * Markuplint parser plugin for ERB (Embedded Ruby) templates. Extends the standard
+ * HTML parser to treat ERB tags 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/erb-parser
+ * Markuplint parser plugin for ERB (Embedded Ruby) templates. Extends the standard
+ * HTML parser to treat ERB tags as opaque blocks, allowing markuplint to lint
+ * the surrounding HTML structure.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -1,6 +1,19 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for ERB (Embedded Ruby) templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize ERB tag variants as opaque blocks:
+ * - `<%= ... %>` (Ruby expression output)
+ * - `<%# ... %>` (comments)
+ * - `<% ... %>` (Ruby code execution)
+ *
+ * Note: trim_mode (`%`-prefixed lines) is not currently supported.
+ */
 declare class ERubyParser extends HtmlParser {
     constructor();
 }
+/**
+ * Singleton ERB parser instance for use by the markuplint engine.
+ */
 export declare const parser: ERubyParser;
 export {};

package/lib/parser.js

@@ -1,4 +1,14 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for ERB (Embedded Ruby) templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize ERB tag variants as opaque blocks:
+ * - `<%= ... %>` (Ruby expression output)
+ * - `<%# ... %>` (comments)
+ * - `<% ... %>` (Ruby code execution)
+ *
+ * Note: trim_mode (`%`-prefixed lines) is not currently supported.
+ */
 class ERubyParser extends HtmlParser {
     constructor() {
         super({
@@ -29,4 +39,7 @@ class ERubyParser extends HtmlParser {
         });
     }
 }
+/**
+ * Singleton ERB parser instance for use by the markuplint engine.
+ */
 export const parser = new ERubyParser();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/erb-parser",
-	"version": "4.6.21",
+	"version": "4.6.23",
 	"description": "eRuby 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.21"
+		"@markuplint/html-parser": "4.6.23"
 	},
 	"devDependencies": {
-		"@markuplint/parser-utils": "4.8.9"
+		"@markuplint/parser-utils": "4.8.11"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }