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

package/lib/find-template-literals.js

@@ -0,0 +1,116 @@
+import { AST_NODE_TYPES, parse } from '@typescript-eslint/typescript-estree';
+/** Length of the `${` expression start delimiter */
+const EXPR_START_LEN = 2;
+/** Length of the `}` expression end delimiter */
+const EXPR_END_LEN = 1;
+/**
+ * Resolves the tag name from a TaggedTemplateExpression's tag node.
+ * For identifiers (e.g., `html`), returns the name directly.
+ * For member expressions (e.g., `LitElement.html`), returns the property name.
+ * Returns an empty string for unrecognized tag forms.
+ *
+ * @param tag - The AST node representing the tag expression
+ * @returns The resolved tag name, or an empty string if unresolvable
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function resolveTagName(tag) {
+    switch (tag.type) {
+        case AST_NODE_TYPES.Identifier: {
+            return tag.name;
+        }
+        case AST_NODE_TYPES.MemberExpression: {
+            if (tag.property.type === AST_NODE_TYPES.Identifier) {
+                return tag.property.name;
+            }
+            return '';
+        }
+        default: {
+            return '';
+        }
+    }
+}
+/**
+ * Recursively searches an AST for TaggedTemplateExpression nodes matching
+ * the specified tag names.
+ *
+ * @param node - The AST node to search
+ * @param tagNames - Set of tag names to match (e.g., `html`, `svg`)
+ * @param results - Accumulator for found template literals
+ * @param sourceCode - The original source code string
+ */
+function searchTaggedTemplates(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+tagNames, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+results, sourceCode) {
+    if (node.type === AST_NODE_TYPES.TaggedTemplateExpression) {
+        const tagName = resolveTagName(node.tag);
+        if (tagNames.has(tagName)) {
+            const quasi = node.quasi;
+            const contentStart = quasi.range[0] + 1; // skip opening backtick
+            const contentEnd = quasi.range[1] - 1; // skip closing backtick
+            const htmlContent = sourceCode.slice(contentStart, contentEnd);
+            const expressions = quasi.expressions.map(expr => ({
+                raw: sourceCode.slice(expr.range[0] - EXPR_START_LEN, expr.range[1] + EXPR_END_LEN),
+                start: expr.range[0] - EXPR_START_LEN,
+                end: expr.range[1] + EXPR_END_LEN,
+            }));
+            results.push({
+                tagName,
+                htmlContent,
+                contentStart,
+                contentEnd,
+                expressions,
+            });
+        }
+    }
+    // Manual AST traversal via Object.keys instead of typescript-estree's simpleTraverse,
+    // because simpleTraverse does not expose enough control over which nodes are visited
+    // and would add an additional import dependency for minimal benefit.
+    for (const key of Object.keys(node)) {
+        if (key === 'parent') {
+            continue;
+        }
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (item && typeof item === 'object' && 'type' in item) {
+                        searchTaggedTemplates(item, tagNames, results, sourceCode);
+                    }
+                }
+            }
+            else if ('type' in value) {
+                searchTaggedTemplates(value, tagNames, results, sourceCode);
+            }
+        }
+    }
+}
+/**
+ * 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 function findTemplateLiterals(sourceCode, tagNames = ['html']) {
+    const ast = parse(sourceCode, {
+        comment: false,
+        errorOnUnknownASTType: false,
+        jsx: false,
+        loc: true,
+        range: true,
+        tokens: false,
+    });
+    const tagNameSet = new Set(tagNames);
+    const results = [];
+    for (const statement of ast.body) {
+        searchTaggedTemplates(statement, tagNameSet, results, sourceCode);
+    }
+    return results;
+}

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module @markuplint/tagged-template-literal-parser
+ * Tagged template literal parser for markuplint. Extracts HTML from tagged
+ * template literals (e.g., `html\`<div>...</div>\``) in TypeScript/JavaScript
+ * files and parses the HTML content for linting.
+ */
+export { TaggedTemplateLiteralParser, parser } from './parser.js';

package/lib/index.js

@@ -0,0 +1,7 @@
+/**
+ * @module @markuplint/tagged-template-literal-parser
+ * Tagged template literal parser for markuplint. Extracts HTML from tagged
+ * template literals (e.g., `html\`<div>...</div>\``) in TypeScript/JavaScript
+ * files and parses the HTML content for linting.
+ */
+export { TaggedTemplateLiteralParser, parser } from './parser.js';

package/lib/parser.d.ts

@@ -0,0 +1,36 @@
+import type { MLASTDocument } from '@markuplint/ml-ast';
+import type { ParseOptions } from '@markuplint/parser-utils';
+import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for tagged template literals containing HTML.
+ * Extracts HTML content from tagged template expressions (e.g., `html\`<div>...</div>\``)
+ * and delegates HTML parsing to the standard HtmlParser with `${...}` expressions
+ * masked as preprocessor-specific blocks.
+ */
+export declare class TaggedTemplateLiteralParser extends HtmlParser {
+    #private;
+    /**
+     * Creates a new parser for tagged template literals.
+     *
+     * @param tagNames - Tag function names to recognize as HTML templates (default: `['html']`).
+     *   For example, `['html', 'svg']` would match both `html\`...\`` and `svg\`...\``.
+     *   Member expressions are resolved to their property name, so `LitElement.html\`...\``
+     *   matches the tag name `'html'`.
+     */
+    constructor(tagNames?: readonly string[]);
+    /**
+     * Parses a TypeScript/JavaScript source file, extracts tagged template literals
+     * matching the configured tag names, and parses their HTML content.
+     * Each `${...}` expression within the template is preserved as a
+     * `#ps:ttl-expression` preprocessor-specific block in the resulting AST.
+     *
+     * @param rawCode - The full TypeScript/JavaScript source code
+     * @param options - Parse options forwarded to the underlying HTML parser
+     * @returns The parsed AST document containing nodes from all matched template literals
+     */
+    parse(rawCode: string, options?: ParseOptions): MLASTDocument;
+}
+/**
+ * Default singleton parser instance configured to match the `html` tag name.
+ */
+export declare const parser: TaggedTemplateLiteralParser;

package/lib/parser.js

@@ -0,0 +1,109 @@
+import { HtmlParser } from '@markuplint/html-parser';
+import { ParserError } from '@markuplint/parser-utils';
+import { findTemplateLiterals } from './find-template-literals.js';
+/**
+ * Parser for tagged template literals containing HTML.
+ * Extracts HTML content from tagged template expressions (e.g., `html\`<div>...</div>\``)
+ * and delegates HTML parsing to the standard HtmlParser with `${...}` expressions
+ * masked as preprocessor-specific blocks.
+ */
+export class TaggedTemplateLiteralParser extends HtmlParser {
+    #tagNames;
+    /**
+     * Creates a new parser for tagged template literals.
+     *
+     * @param tagNames - Tag function names to recognize as HTML templates (default: `['html']`).
+     *   For example, `['html', 'svg']` would match both `html\`...\`` and `svg\`...\``.
+     *   Member expressions are resolved to their property name, so `LitElement.html\`...\``
+     *   matches the tag name `'html'`.
+     */
+    constructor(tagNames = ['html']) {
+        super({
+            ignoreTags: [
+                {
+                    type: 'ttl-expression',
+                    start: '${',
+                    end: '}',
+                },
+            ],
+        });
+        this.#tagNames = tagNames;
+    }
+    /**
+     * Parses a TypeScript/JavaScript source file, extracts tagged template literals
+     * matching the configured tag names, and parses their HTML content.
+     * Each `${...}` expression within the template is preserved as a
+     * `#ps:ttl-expression` preprocessor-specific block in the resulting AST.
+     *
+     * @param rawCode - The full TypeScript/JavaScript source code
+     * @param options - Parse options forwarded to the underlying HTML parser
+     * @returns The parsed AST document containing nodes from all matched template literals
+     */
+    parse(rawCode, options) {
+        let templateLiterals;
+        try {
+            templateLiterals = findTemplateLiterals(rawCode, this.#tagNames);
+        }
+        catch (error) {
+            if (error instanceof Error && 'location' in error) {
+                const loc = error.location;
+                if (loc.start) {
+                    throw new ParserError(error.message, {
+                        line: loc.start.line,
+                        col: loc.start.column,
+                    });
+                }
+            }
+            throw error;
+        }
+        if (templateLiterals.length === 0) {
+            return {
+                raw: rawCode,
+                nodeList: [],
+                isFragment: true,
+            };
+        }
+        // Parse all matched template literals and merge their node lists.
+        const allNodeLists = [];
+        for (const tpl of templateLiterals) {
+            const { line: offsetLine, col: offsetColumn } = getLineAndColumn(rawCode, tpl.contentStart);
+            const doc = super.parse(tpl.htmlContent, {
+                ...options,
+                offsetOffset: tpl.contentStart,
+                offsetLine,
+                offsetColumn,
+            });
+            allNodeLists.push(...doc.nodeList);
+        }
+        return {
+            raw: rawCode,
+            nodeList: allNodeLists,
+            isFragment: true,
+        };
+    }
+}
+/**
+ * Computes the 1-based line number and 1-based column for a given offset in a string.
+ *
+ * @param source - The source string
+ * @param offset - The character offset (0-based)
+ * @returns An object with 1-based `line` and `col` values
+ */
+function getLineAndColumn(source, offset) {
+    let line = 1;
+    let col = 1;
+    for (let i = 0; i < offset; i++) {
+        if (source[i] === '\n') {
+            line++;
+            col = 1;
+        }
+        else {
+            col++;
+        }
+    }
+    return { line, col };
+}
+/**
+ * Default singleton parser instance configured to match the `html` tag name.
+ */
+export const parser = new TaggedTemplateLiteralParser();

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@markuplint/tagged-template-literal-parser",
+	"version": "5.0.0-alpha.0",
+	"description": "Tagged template literal parser for markuplint",
+	"repository": "git@github.com:markuplint/markuplint.git",
+	"author": "Yusuke Hirao <yusukehirao@me.com>",
+	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./lib/index.js",
+			"types": "./lib/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc --project tsconfig.build.json",
+		"dev": "tsc --watch --project tsconfig.build.json",
+		"clean": "tsc --build --clean tsconfig.build.json"
+	},
+	"dependencies": {
+		"@markuplint/html-parser": "5.0.0-alpha.0",
+		"@markuplint/ml-ast": "5.0.0-alpha.0",
+		"@markuplint/parser-utils": "5.0.0-alpha.0",
+		"@typescript-eslint/types": "8.56.0",
+		"@typescript-eslint/typescript-estree": "8.56.0"
+	},
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
+}

package/src/find-template-literals.spec.ts

@@ -0,0 +1,161 @@
+import { describe, test, expect } from 'vitest';
+
+import { findTemplateLiterals } from './find-template-literals.js';
+
+describe('findTemplateLiterals', () => {
+	test('finds a simple html tagged template', () => {
+		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>');
+		expect(results[0].contentStart).toBe(15);
+		expect(results[0].contentEnd).toBe(26);
+		expect(results[0].expressions).toHaveLength(0);
+	});
+
+	test('extracts expression positions', () => {
+		const code = 'const t = html`<div>${name}</div>`;';
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+		expect(results[0].expressions).toHaveLength(1);
+		expect(results[0].expressions[0].raw).toBe('${name}');
+	});
+
+	test('extracts multiple expressions', () => {
+		const code = 'const t = html`${a} ${b} ${c}`;';
+		const results = findTemplateLiterals(code);
+		expect(results[0].expressions).toHaveLength(3);
+		expect(results[0].expressions[0].raw).toBe('${a}');
+		expect(results[0].expressions[1].raw).toBe('${b}');
+		expect(results[0].expressions[2].raw).toBe('${c}');
+	});
+
+	test('ignores untagged template literals', () => {
+		const results = findTemplateLiterals('const t = `<div></div>`;');
+		expect(results).toHaveLength(0);
+	});
+
+	test('ignores non-matching tag names', () => {
+		const results = findTemplateLiterals('const t = css`div {}`;');
+		expect(results).toHaveLength(0);
+	});
+
+	test('supports custom tag names', () => {
+		const results = findTemplateLiterals('const t = svg`<circle />`;', ['svg']);
+		expect(results).toHaveLength(1);
+		expect(results[0].tagName).toBe('svg');
+	});
+
+	test('supports multiple custom tag names simultaneously', () => {
+		const code = 'const a = html`<div></div>`; const b = svg`<circle />`;';
+		const results = findTemplateLiterals(code, ['html', 'svg']);
+		expect(results).toHaveLength(2);
+		expect(results[0].tagName).toBe('html');
+		expect(results[1].tagName).toBe('svg');
+	});
+
+	test('supports member expression tags', () => {
+		const results = findTemplateLiterals('const t = LitElement.html`<div></div>`;');
+		expect(results).toHaveLength(1);
+		expect(results[0].tagName).toBe('html');
+	});
+
+	test('computed member expression tag resolves property name', () => {
+		// obj[html] is a MemberExpression with computed=true, but the property
+		// is an Identifier with name 'html', so it resolves to 'html'
+		const results = findTemplateLiterals('const t = obj[html]`<div></div>`;');
+		expect(results).toHaveLength(1);
+		expect(results[0].tagName).toBe('html');
+	});
+
+	test('call expression tag is ignored', () => {
+		const results = findTemplateLiterals('const t = getTag()`<div></div>`;');
+		expect(results).toHaveLength(0);
+	});
+
+	test('finds multiple template literals', () => {
+		const code = `const a = html\`<div></div>\`;
+const b = html\`<span></span>\`;`;
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(2);
+		expect(results[0].htmlContent).toBe('<div></div>');
+		expect(results[1].htmlContent).toBe('<span></span>');
+	});
+
+	test('handles multiline template literal', () => {
+		const code = `const t = html\`
+<div>
+  <span>text</span>
+</div>
+\`;`;
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+		expect(results[0].htmlContent).toContain('<div>');
+		expect(results[0].htmlContent).toContain('</div>');
+	});
+
+	test('returns empty for non-JS content', () => {
+		expect(() => findTemplateLiterals('not valid js @#$')).toThrow();
+	});
+
+	test('handles no template literals', () => {
+		const results = findTemplateLiterals('const x = 42;');
+		expect(results).toHaveLength(0);
+	});
+
+	test('handles empty string input', () => {
+		const results = findTemplateLiterals('');
+		expect(results).toHaveLength(0);
+	});
+
+	test('expression start/end include ${ and }', () => {
+		const code = 'const t = html`${name}`;';
+		const results = findTemplateLiterals(code);
+		const expr = results[0].expressions[0];
+		expect(code.slice(expr.start, expr.end)).toBe('${name}');
+	});
+
+	test('complex expression', () => {
+		const code = 'const t = html`${items.map(i => i.name)}`;';
+		const results = findTemplateLiterals(code);
+		expect(results[0].expressions[0].raw).toBe('${items.map(i => i.name)}');
+	});
+
+	test('template literal in function body', () => {
+		const code = `function render() {
+  return html\`<div></div>\`;
+}`;
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+	});
+
+	test('template literal in arrow function', () => {
+		const code = 'const render = () => html`<div></div>`;';
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+	});
+
+	test('template literal in class method', () => {
+		const code = `class MyElement {
+  render() {
+    return html\`<div></div>\`;
+  }
+}`;
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+	});
+
+	test('nested tagged template literal', () => {
+		const code = 'const t = html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`;';
+		const results = findTemplateLiterals(code);
+		// Both outer and inner html`` should be found
+		expect(results.length).toBeGreaterThanOrEqual(2);
+	});
+
+	test('TypeScript source with generics', () => {
+		const code = 'const t: TemplateResult<1> = html`<div></div>`;';
+		const results = findTemplateLiterals(code);
+		expect(results).toHaveLength(1);
+		expect(results[0].htmlContent).toBe('<div></div>');
+	});
+});

package/src/find-template-literals.ts

@@ -0,0 +1,160 @@
+import type { TSESTree } from '@typescript-eslint/types';
+
+import { AST_NODE_TYPES, parse } from '@typescript-eslint/typescript-estree';
+
+/** Length of the `${` expression start delimiter */
+const EXPR_START_LEN = 2;
+/** Length of the `}` expression end delimiter */
+const EXPR_END_LEN = 1;
+
+/**
+ * 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[];
+}
+
+/**
+ * Resolves the tag name from a TaggedTemplateExpression's tag node.
+ * For identifiers (e.g., `html`), returns the name directly.
+ * For member expressions (e.g., `LitElement.html`), returns the property name.
+ * Returns an empty string for unrecognized tag forms.
+ *
+ * @param tag - The AST node representing the tag expression
+ * @returns The resolved tag name, or an empty string if unresolvable
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function resolveTagName(tag: TSESTree.Expression): string {
+	switch (tag.type) {
+		case AST_NODE_TYPES.Identifier: {
+			return tag.name;
+		}
+		case AST_NODE_TYPES.MemberExpression: {
+			if (tag.property.type === AST_NODE_TYPES.Identifier) {
+				return tag.property.name;
+			}
+			return '';
+		}
+		default: {
+			return '';
+		}
+	}
+}
+
+/**
+ * Recursively searches an AST for TaggedTemplateExpression nodes matching
+ * the specified tag names.
+ *
+ * @param node - The AST node to search
+ * @param tagNames - Set of tag names to match (e.g., `html`, `svg`)
+ * @param results - Accumulator for found template literals
+ * @param sourceCode - The original source code string
+ */
+function searchTaggedTemplates(
+	// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+	node: TSESTree.Node,
+	// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+	tagNames: ReadonlySet<string>,
+	// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+	results: TemplateLiteralInfo[],
+	sourceCode: string,
+) {
+	if (node.type === AST_NODE_TYPES.TaggedTemplateExpression) {
+		const tagName = resolveTagName(node.tag);
+		if (tagNames.has(tagName)) {
+			const quasi = node.quasi;
+			const contentStart = quasi.range[0] + 1; // skip opening backtick
+			const contentEnd = quasi.range[1] - 1; // skip closing backtick
+			const htmlContent = sourceCode.slice(contentStart, contentEnd);
+
+			const expressions: TemplateExpression[] = quasi.expressions.map(expr => ({
+				raw: sourceCode.slice(expr.range[0] - EXPR_START_LEN, expr.range[1] + EXPR_END_LEN),
+				start: expr.range[0] - EXPR_START_LEN,
+				end: expr.range[1] + EXPR_END_LEN,
+			}));
+
+			results.push({
+				tagName,
+				htmlContent,
+				contentStart,
+				contentEnd,
+				expressions,
+			});
+		}
+	}
+
+	// Manual AST traversal via Object.keys instead of typescript-estree's simpleTraverse,
+	// because simpleTraverse does not expose enough control over which nodes are visited
+	// and would add an additional import dependency for minimal benefit.
+	for (const key of Object.keys(node)) {
+		if (key === 'parent') {
+			continue;
+		}
+		const value = (node as unknown as Record<string, unknown>)[key];
+		if (value && typeof value === 'object') {
+			if (Array.isArray(value)) {
+				for (const item of value) {
+					if (item && typeof item === 'object' && 'type' in item) {
+						searchTaggedTemplates(item as TSESTree.Node, tagNames, results, sourceCode);
+					}
+				}
+			} else if ('type' in value) {
+				searchTaggedTemplates(value as TSESTree.Node, tagNames, results, sourceCode);
+			}
+		}
+	}
+}
+
+/**
+ * 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 function findTemplateLiterals(
+	sourceCode: string,
+	tagNames: readonly string[] = ['html'],
+): readonly TemplateLiteralInfo[] {
+	const ast = parse(sourceCode, {
+		comment: false,
+		errorOnUnknownASTType: false,
+		jsx: false,
+		loc: true,
+		range: true,
+		tokens: false,
+	});
+
+	const tagNameSet = new Set(tagNames);
+	const results: TemplateLiteralInfo[] = [];
+
+	for (const statement of ast.body) {
+		searchTaggedTemplates(statement, tagNameSet, results, sourceCode);
+	}
+
+	return results;
+}