@markuplint/ejs-parser 4.6.22 → 4.18.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,87 @@
+# @markuplint/ejs-parser
+
+## 概要
+
+`@markuplint/ejs-parser` は `HtmlParser` を拡張し、EJS（Embedded JavaScript）テンプレート式を含む HTML のリントを可能にします。
+
+## 動作の仕組み
+
+このパーサーは基底の `HtmlParser` が提供する `ignoreTags` メカニズムを使用します:
+
+1. **マスク** — パース前に、すべての EJS テンプレート式（`<% ... %>` およびそのバリアント）が開始/終了デリミタにより識別され、プレースホルダーテキストに置換される
+2. **パース** — マスクされた HTML は、テンプレート式が存在しないかのように標準 HTML パーサー（parse5）によってパースされる
+3. **保持** — 元の EJS 式は AST 内に `#ps:*`（PreprocessorSpecificBlock）ノードとして保持され、ソース位置も維持される
+
+このアプローチにより、markuplint は EJS 構文に影響されることなく HTML 構造をリントできます。
+
+## ignoreTags 設定
+
+`EJSParser` コンストラクタは、正しいマッチングを保証するために、最も具体的なものから順に5つのパターンを定義しています:
+
+| タイプ                    | 開始        | 終了 | 説明                                           |
+| ------------------------- | ----------- | ---- | ---------------------------------------------- |
+| `ejs-whitespace-slurping` | `<%_`       | `%>` | 空白除去スクリプトレット（前方の空白をトリム） |
+| `ejs-output-value`        | `<%=`       | `%>` | エスケープ済み出力（HTML セーフ）              |
+| `ejs-output-unescaped`    | `<%-`       | `%>` | エスケープなし出力（生 HTML）                  |
+| `ejs-comment`             | `<%#`       | `%>` | EJS コメント（レンダリングされない）           |
+| `ejs-scriptlet`           | `/<%(?!%)/` | `%>` | プレーンスクリプトレット（制御フロー等）       |
+
+`ejs-scriptlet` パターンは否定先読み `(?!%)` を持つ正規表現を使用し、リテラルエスケープシーケンス `<%%` とのマッチを回避しています。
+
+## サポートされない構文
+
+**引用符なしの属性値**内のテンプレート式はサポートされていません。これはすべてのテンプレートエンジンパーサーに共通する既知の制限です（[#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 を拡張する EJSParser クラス
+└── index.spec.ts   — パーサー統合テスト
+```
+
+## 主要ソースファイル
+
+| ファイル        | 用途                                                             |
+| --------------- | ---------------------------------------------------------------- |
+| `src/parser.ts` | `EJSParser` クラスを定義し、シングルトン `parser` をエクスポート |
+| `src/index.ts`  | パッケージエントリーポイント。`parser` を再エクスポート          |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser クラス)"]
+    end
+
+    subgraph pkg ["@markuplint/ejs-parser"]
+        ejsParser["EJSParser\nextends HtmlParser\n(ignoreTags のみ)"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    htmlParser -->|"継承"| ejsParser
+    ejsParser -->|"MLASTDocument を生成"| mlCore
+```
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) — コマンド、レシピ、テスト

package/ARCHITECTURE.md

@@ -0,0 +1,87 @@
+# @markuplint/ejs-parser
+
+## Overview
+
+`@markuplint/ejs-parser` extends `HtmlParser` to lint HTML containing EJS (Embedded JavaScript) template expressions.
+
+## How It Works
+
+The parser uses the `ignoreTags` mechanism provided by the base `HtmlParser`:
+
+1. **Mask** — Before parsing, all EJS template expressions (`<% ... %>` and variants) are identified by their start/end delimiters and replaced with placeholder text
+2. **Parse** — The masked HTML is parsed by the standard HTML parser (parse5) as if the template expressions did not exist
+3. **Preserve** — The original EJS expressions are preserved in the AST as `#ps:*` (PreprocessorSpecificBlock) nodes, maintaining their source positions
+
+This approach allows markuplint to lint the HTML structure without being confused by EJS syntax.
+
+## ignoreTags Configuration
+
+The `EJSParser` constructor defines five ignore patterns, ordered from most specific to least specific to ensure correct matching:
+
+| Type                      | Start       | End  | Description                                            |
+| ------------------------- | ----------- | ---- | ------------------------------------------------------ |
+| `ejs-whitespace-slurping` | `<%_`       | `%>` | Whitespace-slurping scriptlets (trims preceding space) |
+| `ejs-output-value`        | `<%=`       | `%>` | Escaped output (HTML-safe)                             |
+| `ejs-output-unescaped`    | `<%-`       | `%>` | Unescaped output (raw HTML)                            |
+| `ejs-comment`             | `<%#`       | `%>` | EJS comments (not rendered)                            |
+| `ejs-scriptlet`           | `/<%(?!%)/` | `%>` | Plain scriptlets (control flow, etc.)                  |
+
+The `ejs-scriptlet` pattern uses a regex with a negative lookahead `(?!%)` to avoid matching the literal escape sequence `<%%`.
+
+## 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
+├── parser.ts       — EJSParser class extending HtmlParser
+└── index.spec.ts   — Parser integration tests
+```
+
+## Key Source Files
+
+| File            | Purpose                                                           |
+| --------------- | ----------------------------------------------------------------- |
+| `src/parser.ts` | Defines `EJSParser` class and exports singleton `parser` instance |
+| `src/index.ts`  | Package entry point; re-exports `parser`                          |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser class)"]
+    end
+
+    subgraph pkg ["@markuplint/ejs-parser"]
+        ejsParser["EJSParser\nextends HtmlParser\n(ignoreTags only)"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    htmlParser -->|"extends"| ejsParser
+    ejsParser -->|"produces MLASTDocument"| mlCore
+```
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) — Commands, recipes, and testing

package/CHANGELOG.md

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

package/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Perform maintenance tasks for @markuplint/ejs-parser
+globs:
+  - packages/@markuplint/ejs-parser/src/**
+alwaysApply: false
+---
+
+# @markuplint/ejs-parser Maintenance
+
+You are maintaining `@markuplint/ejs-parser`, the EJS template parser for markuplint.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full architecture overview including the ignoreTags mechanism and integration points.
+
+For detailed maintenance procedures, see [docs/maintenance.md](docs/maintenance.md) ([Japanese](docs/maintenance.ja.md)).
+
+## Key Files
+
+| File            | Role                                          |
+| --------------- | --------------------------------------------- |
+| `src/parser.ts` | EJSParser class with ignoreTags configuration |
+| `src/index.ts`  | Package entry point; re-exports parser        |
+
+## Tasks
+
+### add-ignore-tag
+
+Add a new EJS tag variant to the ignoreTags configuration.
+
+1. Open `src/parser.ts`
+2. Add a new entry to the `ignoreTags` array in the `EJSParser` constructor
+   - Place it **before** `ejs-scriptlet` (the catch-all pattern must remain last)
+   - Use a string for the `start` delimiter if it is a fixed prefix
+   - Use a regex for `start` only if pattern matching is needed
+3. Add a test case in `src/index.spec.ts` under the `Tags` describe block:
+   ```ts
+   test('new-type-name', () => {
+     expect(parse('<new-delimiter any %>').nodeList[0].nodeName).toBe('#ps:new-type-name');
+   });
+   ```
+4. Build: `yarn build --scope @markuplint/ejs-parser`
+5. Test: `yarn test --scope @markuplint/ejs-parser`
+
+### modify-ignore-tag
+
+Modify an existing EJS tag pattern (start/end delimiter or type name).
+
+1. Open `src/parser.ts`
+2. Find the target entry in the `ignoreTags` array and update `type`, `start`, or `end`
+3. Update affected test cases in `src/index.spec.ts`
+   - Check both `Tags` tests (nodeName assertions) and `Node list` tests (debug map snapshots)
+4. Build: `yarn build --scope @markuplint/ejs-parser`
+5. Test: `yarn test --scope @markuplint/ejs-parser`

package/docs/maintenance.ja.md

@@ -0,0 +1,84 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                    | 説明                   |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/ejs-parser` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/ejs-parser`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/ejs-parser` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/ejs-parser`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル  | カバレッジ                                                 |
+| --------------- | ---------------------------------------------------------- |
+| `index.spec.ts` | EJSParser 統合テスト（ノードリスト構造、タグタイプ検出等） |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const doc = parser.parse('<div><%= value %></div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:18](5,17)#ps:ejs-output-value: <%=␣value␣%>',
+  '[1:18]>[1:24](17,23)div: </div>',
+]);
+```
+
+タグタイプ検出テストでは、各 EJS バリアントが正しい `#ps:*` ノード名を生成することを検証します:
+
+```ts
+expect(parse('<%_ any _%>').nodeList[0].nodeName).toBe('#ps:ejs-whitespace-slurping');
+expect(parse('<%= any %>').nodeList[0].nodeName).toBe('#ps:ejs-output-value');
+expect(parse('<%- any -%>').nodeList[0].nodeName).toBe('#ps:ejs-output-unescaped');
+expect(parse('<%# any %>').nodeList[0].nodeName).toBe('#ps:ejs-comment');
+expect(parse('<% any %>').nodeList[0].nodeName).toBe('#ps:ejs-scriptlet');
+```
+
+## レシピ
+
+### 1. ignoreTags パターンの追加
+
+新しい EJS タグバリアントのサポートが必要な場合:
+
+1. `src/parser.ts` を開く
+2. コンストラクタの `ignoreTags` 配列に新しいエントリを追加:
+   ```ts
+   {
+     type: 'ejs-new-variant',
+     start: '<%X',
+     end: '%>',
+   },
+   ```
+3. **順序が重要** — 新しいエントリは `ejs-scriptlet` の前に配置すること。`ejs-scriptlet` パターンはキャッチオール正規表現（`/<%(?!%)/`）を使用しており、より具体的なパターンとのマッチを避けるため最後に配置する必要がある
+4. `src/index.spec.ts` にタグ検出テストを追加:
+   ```ts
+   test('ejs-new-variant', () => {
+     expect(parse('<%X any %>').nodeList[0].nodeName).toBe('#ps:ejs-new-variant');
+   });
+   ```
+5. 新しいバリアントに特別なパース動作がある場合、ノードリスト統合テストも追加
+6. ビルド: `yarn build --scope @markuplint/ejs-parser`
+7. テスト: `yarn test --scope @markuplint/ejs-parser`
+
+### 2. ignoreTags パターンの変更
+
+開始/終了デリミタの変更やタイプ名の変更:
+
+1. `src/parser.ts` を開き、`ignoreTags` 内の対象エントリを見つける
+2. `type`、`start`、`end` フィールドを必要に応じて変更
+3. `src/index.spec.ts` 内の影響を受けるすべてのテストを更新:
+   - **タグタイプテスト**（`Tags` describe ブロック）— `nodeName` アサーションを更新
+   - **ノードリストテスト**（`Node list` describe ブロック）— デバッグマップスナップショット内の `#ps:*` エントリを更新
+4. ビルド: `yarn build --scope @markuplint/ejs-parser`
+5. テスト: `yarn test --scope @markuplint/ejs-parser`
+
+## 下流への影響
+
+このパッケージはリーフパーサーであり、他のパッケージはこれに依存していません。`@markuplint/ejs-parser` への変更は、下流パッケージのテストを必要としません。

package/docs/maintenance.md

@@ -0,0 +1,84 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                     | Description            |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/ejs-parser` | Build this package     |
+| `yarn dev --scope @markuplint/ejs-parser`   | Watch mode build       |
+| `yarn clean --scope @markuplint/ejs-parser` | Remove build artifacts |
+| `yarn test --scope @markuplint/ejs-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` | EJSParser integration tests (node list structure, tag type detection, etc.) |
+
+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><%= value %></div>');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:1]>[1:6](0,5)div: <div>',
+  '[1:6]>[1:18](5,17)#ps:ejs-output-value: <%=␣value␣%>',
+  '[1:18]>[1:24](17,23)div: </div>',
+]);
+```
+
+Tag type detection tests verify that each EJS variant produces the correct `#ps:*` node name:
+
+```ts
+expect(parse('<%_ any _%>').nodeList[0].nodeName).toBe('#ps:ejs-whitespace-slurping');
+expect(parse('<%= any %>').nodeList[0].nodeName).toBe('#ps:ejs-output-value');
+expect(parse('<%- any -%>').nodeList[0].nodeName).toBe('#ps:ejs-output-unescaped');
+expect(parse('<%# any %>').nodeList[0].nodeName).toBe('#ps:ejs-comment');
+expect(parse('<% any %>').nodeList[0].nodeName).toBe('#ps:ejs-scriptlet');
+```
+
+## Recipes
+
+### 1. Adding an ignoreTags Pattern
+
+When a new EJS tag variant needs to be supported:
+
+1. Open `src/parser.ts`
+2. Add a new entry to the `ignoreTags` array in the constructor:
+   ```ts
+   {
+     type: 'ejs-new-variant',
+     start: '<%X',
+     end: '%>',
+   },
+   ```
+3. **Ordering matters** — Place the new entry before `ejs-scriptlet`. The `ejs-scriptlet` pattern uses a catch-all regex (`/<%(?!%)/`) and must remain last to avoid matching more specific patterns
+4. Add a tag detection test in `src/index.spec.ts`:
+   ```ts
+   test('ejs-new-variant', () => {
+     expect(parse('<%X any %>').nodeList[0].nodeName).toBe('#ps:ejs-new-variant');
+   });
+   ```
+5. Add a node list integration test if the new variant has special parsing behavior
+6. Build: `yarn build --scope @markuplint/ejs-parser`
+7. Test: `yarn test --scope @markuplint/ejs-parser`
+
+### 2. Modifying an ignoreTags Pattern
+
+When changing a start/end delimiter or renaming a type:
+
+1. Open `src/parser.ts` and find the target entry in `ignoreTags`
+2. Modify the `type`, `start`, or `end` fields as needed
+3. Update all affected tests in `src/index.spec.ts`:
+   - **Tag type tests** (`Tags` describe block) — update the `nodeName` assertions
+   - **Node list tests** (`Node list` describe block) — update the `#ps:*` entries in debug map snapshots
+4. Build: `yarn build --scope @markuplint/ejs-parser`
+5. Test: `yarn test --scope @markuplint/ejs-parser`
+
+## Downstream Impact
+
+This package is a leaf parser — no other packages depend on it. Changes to `@markuplint/ejs-parser` do not require testing downstream packages.

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/ejs-parser
+ * Markuplint parser plugin for EJS (Embedded JavaScript) templates. Extends the
+ * standard HTML parser to treat EJS 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/ejs-parser
+ * Markuplint parser plugin for EJS (Embedded JavaScript) templates. Extends the
+ * standard HTML parser to treat EJS 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 EJS (Embedded JavaScript) templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize all EJS tag variants as opaque blocks:
+ * - `<%_ ... %>` (whitespace-slurping scriptlets)
+ * - `<%= ... %>` (escaped output)
+ * - `<%- ... %>` (unescaped output)
+ * - `<%# ... %>` (comments)
+ * - `<% ... %>` (plain scriptlets)
+ */
 declare class EJSParser extends HtmlParser {
     constructor();
 }
+/**
+ * Singleton EJS parser instance for use by the markuplint engine.
+ */
 export declare const parser: EJSParser;
 export {};

package/lib/parser.js

@@ -1,4 +1,14 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for EJS (Embedded JavaScript) templates that extends the standard HTML parser.
+ *
+ * Configures the HTML parser to recognize all EJS tag variants as opaque blocks:
+ * - `<%_ ... %>` (whitespace-slurping scriptlets)
+ * - `<%= ... %>` (escaped output)
+ * - `<%- ... %>` (unescaped output)
+ * - `<%# ... %>` (comments)
+ * - `<% ... %>` (plain scriptlets)
+ */
 class EJSParser extends HtmlParser {
     constructor() {
         super({
@@ -32,4 +42,7 @@ class EJSParser extends HtmlParser {
         });
     }
 }
+/**
+ * Singleton EJS parser instance for use by the markuplint engine.
+ */
 export const parser = new EJSParser();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ejs-parser",
-	"version": "4.6.22",
+	"version": "4.18.0",
 	"description": "EJS 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.18.0"
 	},
 	"devDependencies": {
-		"@markuplint/parser-utils": "4.8.10"
+		"@markuplint/parser-utils": "4.18.0"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "1885af6349def3f19df975b9e9c399dd47361de1"
 }