@markuplint/tagged-template-literal-parser 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,102 @@
+# @markuplint/tagged-template-literal-parser
+
+## 概要
+
+`@markuplint/tagged-template-literal-parser` は、TypeScript/JavaScript ソースファイル内のタグ付きテンプレートリテラル（例: `` html`<div>...</div>` ``）に埋め込まれた HTML をパースします。TypeScript AST 解析と標準 HTML パースパイプラインを組み合わせて、markuplint AST を生成します。
+
+## 動作の仕組み
+
+パーサーは2段階で動作します:
+
+1. **抽出** — `@typescript-eslint/typescript-estree` を使用して TypeScript/JavaScript ソース全体をパースします。AST を走査し、タグ名が設定リスト（デフォルト: `html`）に一致する `TaggedTemplateExpression` ノードを検出します。各マッチに対して、テンプレートリテラルの内容（バッククォート間）と `${...}` 式の位置情報を抽出します。
+
+2. **パース** — 抽出された各 HTML 文字列は、オフセットオプション（`offsetOffset`、`offsetLine`、`offsetColumn`）付きで基底の `HtmlParser` に渡されます。これにより、結果の AST 内のソース位置が元ファイルに正しくマッピングされます。`${...}` 式は `ignoreTags` メカニズム（開始: `${`、終了: `}`）により処理され、HTML パース前にマスクされた後、`#ps:ttl-expression` プリプロセッサ固有ブロックノードとして復元されます。
+
+```
+.ts/.js ソースファイル
+    |
+    v
+[findTemplateLiterals] — typescript-estree AST 走査
+    |                      TaggedTemplateExpression ノードを検出
+    v
+[HtmlParser.parse()]   — 位置マッピング用オフセットオプション付き
+    |                      ${...} は ignoreTags でマスク
+    v
+markuplint AST         — 位置情報は元ファイルを参照
+```
+
+## タグ名の解決
+
+パーサーは `TaggedTemplateExpression.tag` ノードからタグ名を解決します:
+
+| タグ形式         | 解決される名前 | 例                           |
+| ---------------- | -------------- | ---------------------------- |
+| Identifier       | `tag.name`     | `` html`...` `` → `html`     |
+| MemberExpression | プロパティ名   | `` Lit.html`...` `` → `html` |
+| その他の式形式   | `''`（空文字） | マッチしない                 |
+
+## ignoreTags 設定
+
+パーサーは単一の ignore パターンを定義します:
+
+| タイプ           | 開始 | 終了 | 説明                             |
+| ---------------- | ---- | ---- | -------------------------------- |
+| `ttl-expression` | `${` | `}`  | テンプレートリテラルの式スロット |
+
+これは、テンプレートエンジンパーサー（EJS、Liquid 等）がテンプレート構文に使用するのと同じマスク/復元パイプラインを再利用しています。
+
+## 複数テンプレートリテラル
+
+ソースファイルに複数のタグ付きテンプレートリテラルがある場合、それぞれが独立してパースされ、結果のノードリストがソース順（`contentStart` 順）に連結されます。各テンプレートリテラルのノードは、元ソースファイル内の位置に正しくマッピングされます。
+
+## 制限事項
+
+- **`ignoreBlock` の文字列マッチング**: `${...}` のマスキングは単純な開始/終了デリミタマッチングを使用します。ネストされた `}` 文字を含む式（例: `${{ key: value }}`）は誤って分割される可能性があります。`findTemplateLiterals` 関数は AST から正確な式の位置情報を抽出していますが、この情報はまだ `ignoreBlock` メカニズムの代替として利用されていません。
+- **JSX**: TypeScript パーサーは `jsx: false` で設定されています。JSX 構文を含むファイル（`.tsx`）はパースに失敗します。JSX/TSX ファイルには `@markuplint/jsx-parser` を使用してください。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                        — parser と TaggedTemplateLiteralParser クラスを再エクスポート
+├── parser.ts                       — TaggedTemplateLiteralParser クラス
+├── find-template-literals.ts       — テンプレート抽出用 TypeScript AST 走査
+├── index.spec.ts                   — パーサー統合テスト
+└── find-template-literals.spec.ts  — テンプレート抽出ユニットテスト
+```
+
+## 主要ソースファイル
+
+| ファイル                        | 用途                                                                                     |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `src/parser.ts`                 | `HtmlParser` を拡張する `TaggedTemplateLiteralParser`。シングルトン `parser`             |
+| `src/find-template-literals.ts` | タグ付きテンプレートリテラルの検出・抽出のための AST 走査                                |
+| `src/index.ts`                  | パッケージエントリーポイント。`parser` と `TaggedTemplateLiteralParser` を再エクスポート |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser クラス)"]
+        tsEstree["@typescript-eslint/typescript-estree\n(TypeScript AST)"]
+    end
+
+    subgraph pkg ["@markuplint/tagged-template-literal-parser"]
+        findTpl["findTemplateLiterals()\n(AST 走査)"]
+        ttlParser["TaggedTemplateLiteralParser\nextends HtmlParser"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    tsEstree -->|"ソースをパース"| findTpl
+    findTpl -->|"テンプレート情報"| ttlParser
+    htmlParser -->|"継承"| ttlParser
+    ttlParser -->|"MLASTDocument を生成"| mlCore
+```
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) — コマンド、レシピ、テスト

package/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# @markuplint/tagged-template-literal-parser
+
+## Overview
+
+`@markuplint/tagged-template-literal-parser` parses HTML embedded in tagged template literals (e.g., `` html`<div>...</div>` ``) within TypeScript/JavaScript source files. It combines TypeScript AST analysis with the standard HTML parsing pipeline to produce a markuplint AST.
+
+## How It Works
+
+The parser operates in two stages:
+
+1. **Extract** — The full TypeScript/JavaScript source is parsed using `@typescript-eslint/typescript-estree`. The AST is traversed to find `TaggedTemplateExpression` nodes whose tag name matches the configured list (default: `html`). For each match, the template literal's content (between the backticks) and its `${...}` expression positions are extracted.
+
+2. **Parse** — Each extracted HTML string is passed to the base `HtmlParser` with offset options (`offsetOffset`, `offsetLine`, `offsetColumn`) so that source positions in the resulting AST map back to the original file. The `${...}` expressions are handled via the `ignoreTags` mechanism (start: `${`, end: `}`), which masks them before HTML parsing and restores them as `#ps:ttl-expression` preprocessor-specific block nodes.
+
+```
+.ts/.js source file
+    |
+    v
+[findTemplateLiterals] — typescript-estree AST traversal
+    |                      finds TaggedTemplateExpression nodes
+    v
+[HtmlParser.parse()]   — with offset options for position mapping
+    |                      ${...} masked via ignoreTags
+    v
+markuplint AST         — positions reference the original file
+```
+
+## Tag Name Resolution
+
+The parser resolves tag names from the `TaggedTemplateExpression.tag` node:
+
+| Tag Form               | Resolved Name | Example                      |
+| ---------------------- | ------------- | ---------------------------- |
+| Identifier             | `tag.name`    | `` html`...` `` → `html`     |
+| MemberExpression       | property name | `` Lit.html`...` `` → `html` |
+| Other expression forms | `''` (empty)  | Not matched                  |
+
+## ignoreTags Configuration
+
+The parser defines a single ignore pattern:
+
+| Type             | Start | End | Description                      |
+| ---------------- | ----- | --- | -------------------------------- |
+| `ttl-expression` | `${`  | `}` | Template literal expression slot |
+
+This reuses the same masking/restoration pipeline that template engine parsers (EJS, Liquid, etc.) use for their template syntax.
+
+## Multiple Template Literals
+
+When a source file contains multiple tagged template literals, each is parsed independently and the resulting node lists are concatenated in source order (ordered by `contentStart`). Each template literal's nodes have positions correctly mapped to their location in the original source file.
+
+## Limitations
+
+- **`ignoreBlock` string matching**: The `${...}` masking uses simple start/end delimiter matching. Expressions containing nested `}` characters (e.g., `${{ key: value }}`) may be incorrectly split. The `findTemplateLiterals` function extracts precise expression positions via the AST, but this information is not yet used to replace the `ignoreBlock` mechanism.
+- **JSX**: The TypeScript parser is configured with `jsx: false`. Files containing JSX syntax (`.tsx`) will fail to parse. Use `@markuplint/jsx-parser` for JSX/TSX files.
+
+## Directory Structure
+
+```
+src/
+├── index.ts                        — Re-exports parser and TaggedTemplateLiteralParser class
+├── parser.ts                       — TaggedTemplateLiteralParser class
+├── find-template-literals.ts       — TypeScript AST traversal for template extraction
+├── index.spec.ts                   — Parser integration tests
+└── find-template-literals.spec.ts  — Template extraction unit tests
+```
+
+## Key Source Files
+
+| File                            | Purpose                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `src/parser.ts`                 | `TaggedTemplateLiteralParser` extending `HtmlParser`; singleton `parser`   |
+| `src/find-template-literals.ts` | AST traversal to locate and extract tagged template literals               |
+| `src/index.ts`                  | Package entry point; re-exports `parser` and `TaggedTemplateLiteralParser` |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        htmlParser["@markuplint/html-parser\n(HtmlParser class)"]
+        tsEstree["@typescript-eslint/typescript-estree\n(TypeScript AST)"]
+    end
+
+    subgraph pkg ["@markuplint/tagged-template-literal-parser"]
+        findTpl["findTemplateLiterals()\n(AST traversal)"]
+        ttlParser["TaggedTemplateLiteralParser\nextends HtmlParser"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument → MLDOM)"]
+    end
+
+    tsEstree -->|"parses source"| findTpl
+    findTpl -->|"template info"| ttlParser
+    htmlParser -->|"extends"| ttlParser
+    ttlParser -->|"produces MLASTDocument"| mlCore
+```
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) — Commands, recipes, and testing

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
+
+### Features
+
+- **tagged-template-literal-parser:** add tagged template literal parser ([5224ef4](https://github.com/markuplint/markuplint/commit/5224ef40c5d5c6baa4621b86f9a1b251a83b2b91)), closes [#221](https://github.com/markuplint/markuplint/issues/221)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2024 Yusuke Hirao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @markuplint/tagged-template-literal-parser
+
+[![npm version](https://badge.fury.io/js/%40markuplint%2Ftagged-template-literal-parser.svg)](https://www.npmjs.com/package/@markuplint/tagged-template-literal-parser)
+
+Use **markuplint** with [**tagged template literals**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) containing HTML, such as those used by [lit-html](https://lit.dev/docs/templates/overview/), [lit-element](https://lit.dev/docs/components/rendering/), and similar libraries.
+
+## Install
+
+```shell
+$ npm install -D @markuplint/tagged-template-literal-parser
+
+$ yarn add -D @markuplint/tagged-template-literal-parser
+```
+
+## Usage
+
+Add `parser` option to your [configuration](https://markuplint.dev/configuration/#properties/parser).
+
+```json
+{
+  "parser": {
+    "\\.ts$": "@markuplint/tagged-template-literal-parser"
+  }
+}
+```
+
+This parser extracts HTML from tagged template literals like:
+
+```ts
+import { html } from 'lit';
+
+const greeting = html` <h1>Hello ${name}</h1> `;
+```
+
+The `${...}` expressions are treated as opaque blocks and preserved in the AST as `#ps:ttl-expression` nodes.
+
+## Supported Tag Names
+
+By default, this parser recognizes template literals tagged with `html`. Member expression tags are also supported (e.g., `LitElement.html`).
+
+### Custom Tag Names
+
+To support additional tag names (e.g., `svg`), import the `TaggedTemplateLiteralParser` class and create a custom instance:
+
+```ts
+import { TaggedTemplateLiteralParser } from '@markuplint/tagged-template-literal-parser';
+
+const parser = new TaggedTemplateLiteralParser(['html', 'svg']);
+```
+
+## :warning: Known Limitations
+
+- **Nested `}` in expressions**: The `${...}` masking uses a simple start/end delimiter match. Expressions containing unmatched `}` characters (e.g., `${{ key: value }}`) may be incorrectly split.
+- **Unquoted attribute values with expressions**: Template expressions inside unquoted attribute values are not supported. This is a shared limitation across all template engine parsers.
+- **`.tsx` files**: This parser uses `jsx: false` when parsing TypeScript. Files containing JSX syntax (`.tsx`) may fail to parse. Use `@markuplint/jsx-parser` for JSX/TSX files instead.

package/SKILL.md

@@ -0,0 +1,57 @@
+---
+description: Maintenance tasks for @markuplint/tagged-template-literal-parser
+globs:
+  - packages/@markuplint/tagged-template-literal-parser/src/**/*.ts
+alwaysApply: false
+---
+
+# @markuplint/tagged-template-literal-parser Maintenance
+
+You are maintaining `@markuplint/tagged-template-literal-parser`, the tagged template literal parser for markuplint.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full architecture overview including the two-stage parsing pipeline 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`                 | TaggedTemplateLiteralParser class extending HtmlParser    |
+| `src/find-template-literals.ts` | TypeScript AST traversal to find tagged template literals |
+| `src/index.ts`                  | Package entry point; re-exports parser and class          |
+
+## Tasks
+
+### add-tag-name
+
+Add support for a new tag function name (e.g., `svg`, `css`).
+
+1. The default parser instance in `src/parser.ts` is configured with `['html']`
+2. To add more default tags, modify the constructor default: `tagNames: readonly string[] = ['html', 'svg']`
+3. Add a test in `src/find-template-literals.spec.ts` to verify the new tag is recognized
+4. Add an integration test in `src/index.spec.ts` to verify HTML is correctly parsed from the new tag
+5. Build: `yarn build --scope @markuplint/tagged-template-literal-parser`
+6. Test: `npx vitest run packages/@markuplint/tagged-template-literal-parser/src/`
+
+### modify-expression-handling
+
+Modify how `${...}` expressions are handled (e.g., changing the PSBlock type name).
+
+1. Open `src/parser.ts` and modify the `ignoreTags` entry in the constructor
+2. Update the `type` field to change the PSBlock node name (currently `ttl-expression`)
+3. Update all affected test assertions in `src/index.spec.ts` (search for `#ps:ttl-expression`)
+4. Build: `yarn build --scope @markuplint/tagged-template-literal-parser`
+5. Test: `npx vitest run packages/@markuplint/tagged-template-literal-parser/src/`
+
+### add-tag-resolution-pattern
+
+Add support for a new tag expression form (e.g., call expressions like `html(options)\`...\``).
+
+1. Open `src/find-template-literals.ts`
+2. Add a new case to `resolveTagName()` for the expression type
+3. Add a test in `src/find-template-literals.spec.ts` to verify the tag is resolved
+4. Add an integration test in `src/index.spec.ts`
+5. Build and test as above

package/docs/maintenance.ja.md

@@ -0,0 +1,96 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                                             | 説明                   |
+| -------------------------------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/tagged-template-literal-parser`      | このパッケージをビルド |
+| `yarn dev --scope @markuplint/tagged-template-literal-parser`        | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/tagged-template-literal-parser`      | ビルド成果物を削除     |
+| `npx vitest run packages/@markuplint/tagged-template-literal-parser` | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル                   | カバレッジ                                                   |
+| -------------------------------- | ------------------------------------------------------------ |
+| `index.spec.ts`                  | パーサー統合テスト（ノードリスト構造、式、属性等）           |
+| `find-template-literals.spec.ts` | テンプレートリテラル抽出ユニットテスト（タグ検出、式の位置） |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from './parser.js';
+
+const doc = parser.parse('const t = html`<div>${name}</div>`;');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:16]>[1:21](15,20)div: <div>',
+  '[1:21]>[1:28](20,27)#ps:ttl-expression: ${name}',
+  '[1:28]>[1:34](27,33)div: </div>',
+]);
+```
+
+テンプレートリテラル抽出テストでは、タグ付きテンプレートが正しく検出され位置が正確であることを検証します:
+
+```ts
+import { findTemplateLiterals } from './find-template-literals.js';
+
+const results = findTemplateLiterals('const t = html`<div></div>`;');
+expect(results).toHaveLength(1);
+expect(results[0].tagName).toBe('html');
+expect(results[0].htmlContent).toBe('<div></div>');
+```
+
+## レシピ
+
+### 1. デフォルトタグ名の追加
+
+新しいタグ関数名をデフォルトでサポートする必要がある場合:
+
+1. `src/parser.ts` を開く
+2. コンストラクタのデフォルトパラメータを変更して新しいタグを含める:
+   ```ts
+   constructor(tagNames: readonly string[] = ['html', 'svg']) {
+   ```
+3. `src/find-template-literals.spec.ts` にテストを追加:
+   ```ts
+   test('finds svg tagged template by default', () => {
+     const results = findTemplateLiterals('const t = svg`<circle />`;', ['svg']);
+     expect(results).toHaveLength(1);
+   });
+   ```
+4. `src/index.spec.ts` に統合テストを追加
+5. ビルド: `yarn build --scope @markuplint/tagged-template-literal-parser`
+6. テスト: `npx vitest run packages/@markuplint/tagged-template-literal-parser/src/`
+
+### 2. 新しいタグ解決パターンの追加
+
+新しいタグ式形式の認識が必要な場合（例: コール式）:
+
+1. `src/find-template-literals.ts` を開く
+2. `resolveTagName` 関数に新しいケースを追加:
+   ```ts
+   case AST_NODE_TYPES.CallExpression: {
+     // html(options)`...` パターンを処理
+     return resolveTagName(tag.callee);
+   }
+   ```
+3. `src/find-template-literals.spec.ts` にテストを追加
+4. `src/index.spec.ts` に統合テストを追加
+5. 上記と同様にビルド・テスト
+
+### 3. 式の処理の変更
+
+`${...}` 式のマスクまたは復元方法を変更する場合:
+
+1. `src/parser.ts` を開き、コンストラクタ内の `ignoreTags` 配列を見つける
+2. `type`、`start`、`end` フィールドを必要に応じて変更
+3. `src/index.spec.ts` 内の影響を受けるすべてのテストを更新:
+   - `#ps:ttl-expression` を検索し、新しいタイプ名に更新
+4. 上記と同様にビルド・テスト
+
+## 下流への影響
+
+このパッケージはリーフパーサーであり、他のパッケージはこれに依存していません。`@markuplint/tagged-template-literal-parser` への変更は、下流パッケージのテストを必要としません。

package/docs/maintenance.md

@@ -0,0 +1,96 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                                              | Description            |
+| -------------------------------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/tagged-template-literal-parser`      | Build this package     |
+| `yarn dev --scope @markuplint/tagged-template-literal-parser`        | Watch mode build       |
+| `yarn clean --scope @markuplint/tagged-template-literal-parser`      | Remove build artifacts |
+| `npx vitest run packages/@markuplint/tagged-template-literal-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`                  | Parser integration tests (node list structure, expressions, attributes, etc.) |
+| `find-template-literals.spec.ts` | Template literal extraction unit tests (tag detection, expression positions)  |
+
+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('const t = html`<div>${name}</div>`;');
+expect(nodeListToDebugMaps(doc.nodeList)).toStrictEqual([
+  '[1:16]>[1:21](15,20)div: <div>',
+  '[1:21]>[1:28](20,27)#ps:ttl-expression: ${name}',
+  '[1:28]>[1:34](27,33)div: </div>',
+]);
+```
+
+Template literal extraction tests verify that tagged templates are correctly found and positions are accurate:
+
+```ts
+import { findTemplateLiterals } from './find-template-literals.js';
+
+const results = findTemplateLiterals('const t = html`<div></div>`;');
+expect(results).toHaveLength(1);
+expect(results[0].tagName).toBe('html');
+expect(results[0].htmlContent).toBe('<div></div>');
+```
+
+## Recipes
+
+### 1. Adding a Default Tag Name
+
+When a new tag function name needs to be supported by default:
+
+1. Open `src/parser.ts`
+2. Modify the constructor default parameter to include the new tag:
+   ```ts
+   constructor(tagNames: readonly string[] = ['html', 'svg']) {
+   ```
+3. Add a test in `src/find-template-literals.spec.ts`:
+   ```ts
+   test('finds svg tagged template by default', () => {
+     const results = findTemplateLiterals('const t = svg`<circle />`;', ['svg']);
+     expect(results).toHaveLength(1);
+   });
+   ```
+4. Add an integration test in `src/index.spec.ts`
+5. Build: `yarn build --scope @markuplint/tagged-template-literal-parser`
+6. Test: `npx vitest run packages/@markuplint/tagged-template-literal-parser/src/`
+
+### 2. Adding a New Tag Resolution Pattern
+
+When a new tag expression form needs to be recognized (e.g., call expressions):
+
+1. Open `src/find-template-literals.ts`
+2. Add a new case to the `resolveTagName` function:
+   ```ts
+   case AST_NODE_TYPES.CallExpression: {
+     // Handle html(options)`...` patterns
+     return resolveTagName(tag.callee);
+   }
+   ```
+3. Add a test in `src/find-template-literals.spec.ts`
+4. Add an integration test in `src/index.spec.ts`
+5. Build and test as above
+
+### 3. Modifying Expression Handling
+
+When changing how `${...}` expressions are masked or restored:
+
+1. Open `src/parser.ts` and find the `ignoreTags` array in the constructor
+2. Modify the `type`, `start`, or `end` fields as needed
+3. Update all affected tests in `src/index.spec.ts`:
+   - Search for `#ps:ttl-expression` and update to the new type name
+4. Build and test as above
+
+## Downstream Impact
+
+This package is a leaf parser — no other packages depend on it. Changes to `@markuplint/tagged-template-literal-parser` do not require testing downstream packages.

package/lib/find-template-literals.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Represents a template literal expression (`${...}`) within a tagged template.
+ */
+export interface TemplateExpression {
+    /** The raw source text of the expression including `${` and `}` */
+    readonly raw: string;
+    /** Start offset in the original source */
+    readonly start: number;
+    /** End offset in the original source */
+    readonly end: number;
+}
+/**
+ * Represents a tagged template literal found in the source code.
+ */
+export interface TemplateLiteralInfo {
+    /** The tag name (e.g., 'html') */
+    readonly tagName: string;
+    /** The full raw content between the backticks (excluding the backticks themselves) */
+    readonly htmlContent: string;
+    /** Start offset of the content (after the opening backtick) */
+    readonly contentStart: number;
+    /** End offset of the content (before the closing backtick) */
+    readonly contentEnd: number;
+    /** The expressions (`${...}`) found within the template literal */
+    readonly expressions: readonly TemplateExpression[];
+}
+/**
+ * Finds all tagged template literals in a TypeScript/JavaScript source file
+ * that match the given tag names. Uses `@typescript-eslint/typescript-estree`
+ * to parse the source and recursively searches the AST for
+ * `TaggedTemplateExpression` nodes whose tag resolves to one of the specified names.
+ *
+ * @param sourceCode - The raw TypeScript/JavaScript source code to search
+ * @param tagNames - Array of tag function names to match (default: `['html']`)
+ * @returns Array of template literal information objects, ordered by their position in the source
+ */
+export declare function findTemplateLiterals(sourceCode: string, tagNames?: readonly string[]): readonly TemplateLiteralInfo[];