@reteps/tree-sitter-htmlmustache 0.8.0 → 0.9.0

package/src/browser/browser.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Smoke tests for the browser entry. Runs in Node via vitest; `locateWasm`
+ * returns absolute file paths (which `Language.load` / web-tree-sitter's
+ * Emscripten loader accept in Node contexts).
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLinter, DEFAULT_CONFIG, type Linter, type PrettierLike } from './index.js';
+import { GRAMMAR_WASM_FILENAME } from '../core/grammar.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const GRAMMAR_WASM_PATH = path.resolve(REPO_ROOT, GRAMMAR_WASM_FILENAME);
+
+let linter: Linter;
+
+beforeAll(async () => {
+  linter = await createLinter({
+    locateWasm: (name) => {
+      if (name === GRAMMAR_WASM_FILENAME) return GRAMMAR_WASM_PATH;
+      // Fall through for tree-sitter.wasm — web-tree-sitter resolves it from
+      // its own package in node_modules.
+      return path.resolve(REPO_ROOT, 'node_modules', 'web-tree-sitter', name);
+    },
+  });
+});
+
+describe('createLinter', () => {
+  it('is idempotent across multiple calls (returns working handles)', async () => {
+    const a = await createLinter({ locateWasm: GRAMMAR_WASM_PATH });
+    const b = await createLinter({ locateWasm: GRAMMAR_WASM_PATH });
+    expect(a.lint('<p></p>', DEFAULT_CONFIG)).toEqual([]);
+    expect(b.lint('<p></p>', DEFAULT_CONFIG)).toEqual([]);
+  });
+
+  it('accepts string locateWasm as grammar URL', async () => {
+    const h = await createLinter({ locateWasm: GRAMMAR_WASM_PATH });
+    expect(h.lint('<p></p>', DEFAULT_CONFIG)).toEqual([]);
+  });
+});
+
+describe('lint', () => {
+  it('returns [] for clean HTML', () => {
+    expect(linter.lint('<p>hi</p>', DEFAULT_CONFIG)).toEqual([]);
+  });
+
+  it('flags unquoted mustache attributes (built-in rule)', () => {
+    const d = linter.lint('<a href={{url}}></a>', DEFAULT_CONFIG);
+    expect(d.length).toBeGreaterThan(0);
+    const rule = d.find((x) => x.ruleName === 'unquotedMustacheAttributes');
+    expect(rule).toBeDefined();
+    expect(rule!.severity).toBe('error');
+    expect(rule!.line).toBe(1);
+    expect(rule!.column).toBeGreaterThan(0);
+  });
+
+  it('flags self-closing non-void tags with a fix', () => {
+    const d = linter.lint('<div/>', DEFAULT_CONFIG);
+    const rule = d.find((x) => x.ruleName === 'selfClosingNonVoidTags');
+    expect(rule).toBeDefined();
+    expect(rule!.fix).toBeDefined();
+    expect(rule!.fix!.length).toBeGreaterThanOrEqual(1);
+    const [start, end] = rule!.fix![0].range;
+    expect(typeof start).toBe('number');
+    expect(typeof end).toBe('number');
+    expect(end).toBeGreaterThan(start);
+  });
+
+  it('flags duplicate attributes', () => {
+    const d = linter.lint('<p id="a" id="b"></p>', DEFAULT_CONFIG);
+    expect(d.some((x) => x.ruleName === 'duplicateAttributes')).toBe(true);
+  });
+
+  it('flags nested duplicate sections', () => {
+    const d = linter.lint('{{#x}}{{#x}}hi{{/x}}{{/x}}', DEFAULT_CONFIG);
+    expect(d.some((x) => x.ruleName === 'nestedDuplicateSections')).toBe(true);
+  });
+
+  it('flags consecutive duplicate sections with a range-deletion fix', () => {
+    const d = linter.lint('{{#x}}a{{/x}}{{#x}}b{{/x}}', DEFAULT_CONFIG);
+    const rule = d.find((x) => x.ruleName === 'consecutiveDuplicateSections');
+    expect(rule).toBeDefined();
+    expect(rule!.fix).toBeDefined();
+    expect(Array.isArray(rule!.fix)).toBe(true);
+    expect(rule!.fix![0].newText).toBe('');
+  });
+
+  it('flags unrecognized HTML tags unless registered as customTag', () => {
+    const raw = linter.lint('<my-widget></my-widget>', {
+      rules: { unrecognizedHtmlTags: 'error' },
+    });
+    expect(raw.some((x) => x.ruleName === 'unrecognizedHtmlTags')).toBe(true);
+
+    const withCustom = linter.lint('<my-widget></my-widget>', {
+      rules: { unrecognizedHtmlTags: 'error' },
+      customTags: [{ name: 'my-widget' }],
+    });
+    expect(withCustom.some((x) => x.ruleName === 'unrecognizedHtmlTags')).toBe(false);
+  });
+
+  it('matches a custom selector-based rule', () => {
+    const d = linter.lint('<script>x</script>', {
+      customRules: [{ id: 'no-script', selector: 'script', message: 'Bare <script> is disallowed' }],
+    });
+    expect(d.some((x) => x.ruleName === 'no-script')).toBe(true);
+  });
+
+  it('honors <!-- htmlmustache-disable ruleName --> directives', () => {
+    const src = '<!-- htmlmustache-disable duplicateAttributes -->\n<p id="a" id="b"></p>';
+    const d = linter.lint(src, DEFAULT_CONFIG);
+    expect(d.some((x) => x.ruleName === 'duplicateAttributes')).toBe(false);
+  });
+
+  it('honors {{! htmlmustache-disable ruleName }} directives', () => {
+    const src = '{{! htmlmustache-disable duplicateAttributes }}\n<p id="a" id="b"></p>';
+    const d = linter.lint(src, DEFAULT_CONFIG);
+    expect(d.some((x) => x.ruleName === 'duplicateAttributes')).toBe(false);
+  });
+
+  it('is pure (same input → same output)', () => {
+    const src = '<p id="a" id="b"></p>';
+    const a = linter.lint(src, DEFAULT_CONFIG);
+    const b = linter.lint(src, DEFAULT_CONFIG);
+    expect(b).toEqual(a);
+  });
+
+  it('survives 500 iterations without throwing (rough memory / GC sanity)', () => {
+    const src = '<div><p>{{name}}</p><span class="x">{{value}}</span></div>';
+    for (let i = 0; i < 500; i++) linter.lint(src, DEFAULT_CONFIG);
+    // If web-tree-sitter was leaking a tree per iteration, this would OOM the
+    // native heap. Reaching here without throwing is the signal we want.
+    expect(true).toBe(true);
+  });
+
+  it('reports parse errors without a ruleName', () => {
+    const d = linter.lint('<div', DEFAULT_CONFIG);
+    const parseErr = d.find((x) => !x.ruleName);
+    expect(parseErr).toBeDefined();
+    expect(parseErr!.severity).toBe('error');
+  });
+});
+
+describe('format', () => {
+  it('formats nested blocks', async () => {
+    const out = await linter.format('<div><p>hi</p></div>');
+    expect(out).toBe('<div>\n  <p>hi</p>\n</div>\n');
+  });
+
+  it('is idempotent', async () => {
+    const src = '<div><p>{{name}}</p></div>';
+    const once = await linter.format(src);
+    const twice = await linter.format(once);
+    expect(twice).toBe(once);
+  });
+
+  it('respects printWidth + indentSize from config', async () => {
+    const out = await linter.format('<div><p>hi</p></div>', { indentSize: 4 });
+    expect(out).toBe('<div>\n    <p>hi</p>\n</div>\n');
+  });
+
+  it('applies mustacheSpaces from config', async () => {
+    const out = await linter.format('<p>{{name}}</p>', { mustacheSpaces: true });
+    expect(out).toBe('<p>{{ name }}</p>\n');
+  });
+
+  it('leaves <script> body untouched when no prettier provided', async () => {
+    const src = '<script>var  a=1 ;</script>';
+    const out = await linter.format(src);
+    expect(out).toContain('var  a=1 ;');
+  });
+
+  it('formats <script> body via injected prettier (per-call)', async () => {
+    const prettier: PrettierLike = {
+      format: (src, opts) => {
+        expect(opts.parser).toBe('babel');
+        return `/* PRETTIER-${src.trim()} */\n`;
+      },
+    };
+    const out = await linter.format('<script>var a=1;</script>', undefined, { prettier });
+    expect(out).toContain('/* PRETTIER-var a=1; */');
+  });
+
+  it('uses factory-level prettier by default', async () => {
+    const prettier: PrettierLike = {
+      format: () => 'FACTORY_OUT\n',
+    };
+    const h = await createLinter({ locateWasm: GRAMMAR_WASM_PATH, prettier });
+    const out = await h.format('<script>var a=1;</script>');
+    expect(out).toContain('FACTORY_OUT');
+  });
+});
+
+describe('DEFAULT_CONFIG', () => {
+  it('has rule entries for every built-in rule', () => {
+    const rules = DEFAULT_CONFIG.rules as Record<string, string>;
+    expect(rules.nestedDuplicateSections).toBeDefined();
+    expect(rules.unquotedMustacheAttributes).toBeDefined();
+    expect(rules.consecutiveDuplicateSections).toBeDefined();
+    expect(rules.selfClosingNonVoidTags).toBeDefined();
+    expect(rules.duplicateAttributes).toBeDefined();
+    expect(rules.unescapedEntities).toBeDefined();
+    expect(rules.preferMustacheComments).toBeDefined();
+    expect(rules.unrecognizedHtmlTags).toBeDefined();
+  });
+});

package/src/browser/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Browser entry point for `@reteps/tree-sitter-htmlmustache`.
+ *
+ * Exposes `createLinter({ locateWasm, prettier? })` returning a handle with
+ * `lint(source, config)` and `format(source, config, opts)`. Internally reuses
+ * the shared rule engine and formatter in `src/core/` — browser-safe, no fs.
+ */
+
+import { Parser, Language } from 'web-tree-sitter';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+
+import { collectErrors } from '../core/collectErrors.js';
+import type { WalkableTree } from '../core/collectErrors.js';
+import { formatDocument } from '../core/formatting/index.js';
+import type { FormattingOptions } from '../core/formatting/index.js';
+import { mergeOptions } from '../core/formatting/mergeOptions.js';
+import { formatEmbeddedRegions } from '../core/formatting/embedded.js';
+import type { PrettierLike } from '../core/formatting/embedded.js';
+import { RULE_DEFAULTS } from '../core/ruleMetadata.js';
+import { toDiagnostic } from '../core/diagnostic.js';
+import type { Diagnostic } from '../core/diagnostic.js';
+import { GRAMMAR_WASM_FILENAME } from '../core/grammar.js';
+import type {
+  HtmlMustacheConfig,
+  RulesConfig,
+  RuleSeverity,
+  CustomRule as CustomRuleType,
+} from '../core/configSchema.js';
+import type { CustomCodeTagConfig } from '../core/customCodeTags.js';
+
+export type Config = Omit<HtmlMustacheConfig, 'include' | 'exclude'>;
+export type CustomRule = CustomRuleType;
+export type CustomTag = CustomCodeTagConfig;
+export type { RulesConfig, RuleSeverity, PrettierLike, Diagnostic };
+
+export type LocateWasm = string | ((filename: string) => string);
+
+export interface CreateLinterOptions {
+  /**
+   * Locates the grammar WASM (`tree-sitter-htmlmustache.wasm`). If a string,
+   * treated as the URL for the grammar — web-tree-sitter's own
+   * `tree-sitter.wasm` will resolve via its default `locateFile`. Pass a
+   * callback to resolve both names explicitly.
+   */
+  locateWasm: LocateWasm;
+  /** Default prettier used for embedded-region formatting. */
+  prettier?: PrettierLike;
+}
+
+export interface FormatOptions {
+  /** Override the factory-level prettier for this call. */
+  prettier?: PrettierLike;
+}
+
+export interface Linter {
+  lint(source: string, config?: Config): Diagnostic[];
+  format(source: string, config?: Config, opts?: FormatOptions): Promise<string>;
+}
+
+/** Default severities for every built-in rule. */
+export const DEFAULT_CONFIG: Config = { rules: RULE_DEFAULTS as RulesConfig };
+
+const DEFAULT_FORMATTING_OPTIONS: FormattingOptions = { tabSize: 2, insertSpaces: true };
+
+function toLocateFile(locateWasm: LocateWasm): ((name: string) => string) | undefined {
+  // String form resolves only the grammar; runtime `tree-sitter.wasm` falls
+  // through to web-tree-sitter's own default `locateFile`.
+  return typeof locateWasm === 'function' ? (name) => locateWasm(name) : undefined;
+}
+
+function resolveGrammarUrl(locateWasm: LocateWasm): string {
+  return typeof locateWasm === 'string' ? locateWasm : locateWasm(GRAMMAR_WASM_FILENAME);
+}
+
+/**
+ * Create a linter/formatter handle. Consumers should cache the result — each
+ * call reloads the grammar WASM.
+ */
+export async function createLinter(opts: CreateLinterOptions): Promise<Linter> {
+  const { locateWasm, prettier: factoryPrettier } = opts;
+  const locateFile = toLocateFile(locateWasm);
+  // `Parser.init` is itself idempotent (Emscripten caches the runtime globally),
+  // so repeated calls with different `locateFile` are safe — the first wins.
+  await Parser.init(locateFile ? { locateFile } : undefined);
+  const parser = new Parser();
+  const language = await Language.load(resolveGrammarUrl(locateWasm));
+  parser.setLanguage(language);
+
+  return {
+    lint(source, config) {
+      const tree = parser.parse(source);
+      if (!tree) throw new Error('Failed to parse document');
+      try {
+        const customTagNames = config?.customTags?.map((t) => t.name);
+        const errors = collectErrors(
+          tree as unknown as WalkableTree,
+          config?.rules,
+          customTagNames,
+          config?.customRules,
+        );
+        return errors.map(toDiagnostic);
+      } finally {
+        tree.delete();
+      }
+    },
+
+    async format(source, config, callOpts) {
+      const prettier = callOpts?.prettier ?? factoryPrettier;
+      const options = mergeOptions(DEFAULT_FORMATTING_OPTIONS, config ?? null);
+      const tree = parser.parse(source);
+      if (!tree) throw new Error('Failed to parse document');
+      try {
+        const embeddedFormatted = await formatEmbeddedRegions(tree.rootNode, options, prettier);
+        const document = TextDocument.create('file:///input', 'htmlmustache', 1, source);
+        const edits = formatDocument(tree, document, options, {
+          customTags: config?.customTags,
+          printWidth: config?.printWidth,
+          mustacheSpaces: config?.mustacheSpaces,
+          noBreakDelimiters: config?.noBreakDelimiters,
+          embeddedFormatted: embeddedFormatted.size > 0 ? embeddedFormatted : undefined,
+        });
+        return edits.length === 0 ? source : edits[0].newText;
+      } finally {
+        tree.delete();
+      }
+    },
+  };
+}

package/src/browser/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "../../browser/out"
+  },
+  "include": ["index.ts", "../core/**/*.ts"],
+  "exclude": ["../core/**/*.test.ts"]
+}

package/src/core/collectErrors.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared error collection logic used by both the LSP diagnostics
+ * and the CLI linter.
+ */
+
+import type { BalanceNode } from './htmlBalanceChecker.js';
+import { checkHtmlBalance, checkUnclosedTags } from './htmlBalanceChecker.js';
+import {
+  checkNestedSameNameSections,
+  checkUnquotedMustacheAttributes,
+  checkConsecutiveSameNameSections,
+  checkSelfClosingNonVoidTags,
+  checkDuplicateAttributes,
+  checkUnescapedEntities,
+  checkHtmlComments,
+  checkUnrecognizedHtmlTags,
+  checkElementContentTooLong,
+} from './mustacheChecks.js';
+import type { TextReplacement } from './mustacheChecks.js';
+import type { RulesConfig, RuleSeverity, CustomRule, ElementContentTooLongOptions } from './configSchema.js';
+import { RULE_DEFAULTS, KNOWN_RULE_NAMES } from './ruleMetadata.js';
+import { parseSelector, matchSelector } from './selectorMatcher.js';
+import type { ParsedSelector } from './selectorMatcher.js';
+
+// Parsing a selector is non-trivial (runs parsel-js) and lint() is called
+// per-keystroke in browsers, so cache by raw selector string. `null` cached
+// when the selector is unparseable to avoid retrying.
+const selectorCache = new Map<string, ParsedSelector | null>();
+
+function parseSelectorCached(raw: string): ParsedSelector | null {
+  const hit = selectorCache.get(raw);
+  if (hit !== undefined) return hit;
+  const parsed = parseSelector(raw);
+  selectorCache.set(raw, parsed);
+  return parsed;
+}
+
+/** A tree that provides walk() and rootNode, compatible with both web-tree-sitter and CLI wasm. */
+export interface WalkableTree {
+  walk(): TreeCursor;
+  rootNode: BalanceNode;
+}
+
+interface TreeCursor {
+  currentNode: BalanceNode;
+  nodeType: string;
+  nodeIsMissing: boolean;
+  gotoFirstChild(): boolean;
+  gotoNextSibling(): boolean;
+  gotoParent(): boolean;
+}
+
+/** Unified error result from all checkers. */
+export interface CheckError {
+  node: BalanceNode;
+  message: string;
+  severity?: 'error' | 'warning';
+  fix?: TextReplacement[];
+  fixDescription?: string;
+  ruleName?: string;
+}
+
+const ERROR_NODE_TYPES = new Set([
+  'ERROR',
+  'mustache_erroneous_section_end',
+  'mustache_erroneous_inverted_section_end',
+]);
+
+function errorMessageForNode(nodeType: string, node: BalanceNode): string {
+  if (nodeType === 'mustache_erroneous_section_end' || nodeType === 'mustache_erroneous_inverted_section_end') {
+    const tagNameNode = node.children.find(c => c.type === 'mustache_erroneous_tag_name');
+    return `Mismatched mustache section: {{/${tagNameNode?.text || '?'}}}`;
+  }
+  if (nodeType === 'ERROR') {
+    return 'Syntax error';
+  }
+  // isMissing node
+  return `Missing ${nodeType}`;
+}
+
+function resolveRuleConfig<K extends keyof RulesConfig>(
+  rules: RulesConfig | undefined,
+  ruleName: K,
+): { severity: RuleSeverity; entry: RulesConfig[K] } {
+  const entry = rules?.[ruleName];
+  let severity: RuleSeverity;
+  if (entry === undefined) {
+    severity = RULE_DEFAULTS[ruleName] ?? 'off';
+  } else if (typeof entry === 'string') {
+    severity = entry;
+  } else {
+    severity = (entry as { severity: RuleSeverity }).severity;
+  }
+  return { severity, entry: entry as RulesConfig[K] };
+}
+
+function parseDisableDirective(node: BalanceNode, customRuleIds?: Set<string>): string | null {
+  if (node.type !== 'html_comment' && node.type !== 'mustache_comment') return null;
+  let inner: string | null = null;
+  if (node.type === 'html_comment') {
+    const match = node.text.match(/^<!--([\s\S]*)-->$/);
+    if (match) inner = match[1].trim();
+  } else {
+    const match = node.text.match(/^\{\{!([\s\S]*)\}\}$/);
+    if (match) inner = match[1].trim();
+  }
+  if (!inner) return null;
+  const prefix = 'htmlmustache-disable ';
+  if (!inner.startsWith(prefix)) return null;
+  const ruleName = inner.slice(prefix.length).trim();
+  if (KNOWN_RULE_NAMES.has(ruleName)) return ruleName;
+  if (customRuleIds?.has(ruleName)) return ruleName;
+  return null;
+}
+
+function collectDisabledRules(rootNode: BalanceNode, customRuleIds?: Set<string>): Set<string> {
+  const disabled = new Set<string>();
+  function walk(node: BalanceNode) {
+    const rule = parseDisableDirective(node, customRuleIds);
+    if (rule) { disabled.add(rule); return; }
+    for (const child of node.children) walk(child);
+  }
+  walk(rootNode);
+  return disabled;
+}
+
+/**
+ * Collect all errors from a parsed tree: syntax errors, balance errors,
+ * unclosed tags, and mustache lint checks.
+ */
+export function collectErrors(tree: WalkableTree, rules?: RulesConfig, customTagNames?: string[], customRules?: CustomRule[]): CheckError[] {
+  const errors: CheckError[] = [];
+  const cursor = tree.walk() as unknown as TreeCursor;
+
+  function visit() {
+    const node = cursor.currentNode;
+    const nodeType = cursor.nodeType;
+
+    if (ERROR_NODE_TYPES.has(nodeType) || cursor.nodeIsMissing) {
+      errors.push({
+        node,
+        message: errorMessageForNode(nodeType, node),
+      });
+
+      // Don't recurse into ERROR nodes — the children are not meaningful
+      if (nodeType === 'ERROR') return;
+    }
+
+    if (cursor.gotoFirstChild()) {
+      do { visit(); } while (cursor.gotoNextSibling());
+      cursor.gotoParent();
+    }
+  }
+
+  visit();
+
+  // Run balance checker for HTML tag mismatch detection across mustache paths
+  const balanceErrors = checkHtmlBalance(tree.rootNode);
+  for (const error of balanceErrors) {
+    errors.push({ node: error.node, message: error.message });
+  }
+
+  // Check for unclosed non-void HTML tags
+  const unclosedErrors = checkUnclosedTags(tree.rootNode);
+  for (const error of unclosedErrors) {
+    errors.push({ node: error.node, message: error.message });
+  }
+
+  // Collect inline disable directives and merge into effective rules
+  const customRuleIds = customRules ? new Set(customRules.map(r => r.id)) : undefined;
+  const disabledRules = collectDisabledRules(tree.rootNode, customRuleIds);
+  const effectiveRules = { ...rules };
+  for (const rule of disabledRules) {
+    (effectiveRules as Record<string, string>)[rule] = 'off';
+  }
+
+  // Configurable lint checks
+  const sourceText = tree.rootNode.text;
+
+  const ruleChecks: { rule: keyof RulesConfig; errors: (entry: RulesConfig[keyof RulesConfig]) => import('./mustacheChecks.js').FixableError[] }[] = [
+    { rule: 'nestedDuplicateSections', errors: () => checkNestedSameNameSections(tree.rootNode) },
+    { rule: 'unquotedMustacheAttributes', errors: () => checkUnquotedMustacheAttributes(tree.rootNode) },
+    { rule: 'consecutiveDuplicateSections', errors: () => checkConsecutiveSameNameSections(tree.rootNode, sourceText) },
+    { rule: 'selfClosingNonVoidTags', errors: () => checkSelfClosingNonVoidTags(tree.rootNode) },
+    { rule: 'duplicateAttributes', errors: () => checkDuplicateAttributes(tree.rootNode) },
+    { rule: 'unescapedEntities', errors: () => checkUnescapedEntities(tree.rootNode) },
+    { rule: 'preferMustacheComments', errors: () => checkHtmlComments(tree.rootNode) },
+    { rule: 'unrecognizedHtmlTags', errors: () => checkUnrecognizedHtmlTags(tree.rootNode, customTagNames) },
+    {
+      rule: 'elementContentTooLong',
+      errors: (entry) => {
+        const elements = (entry && typeof entry === 'object' ? (entry as ElementContentTooLongOptions).elements : undefined) ?? [];
+        return checkElementContentTooLong(tree.rootNode, elements);
+      },
+    },
+  ];
+
+  for (const { rule, errors: getErrors } of ruleChecks) {
+    const { severity, entry } = resolveRuleConfig(effectiveRules, rule);
+    if (severity === 'off') continue;
+
+    for (const error of getErrors(entry)) {
+      errors.push({
+        node: error.node,
+        message: error.message,
+        severity,
+        fix: error.fix,
+        fixDescription: error.fixDescription,
+        ruleName: rule,
+      });
+    }
+  }
+
+  // Custom selector-based rules
+  if (customRules) {
+    for (const rule of customRules) {
+      if (disabledRules.has(rule.id)) continue;
+      const severity = rule.severity ?? 'error';
+      if (severity === 'off') continue;
+      const parsed = parseSelectorCached(rule.selector);
+      if (!parsed) continue;
+      const matches = matchSelector(tree.rootNode, parsed);
+      for (const node of matches) {
+        errors.push({ node, message: rule.message, severity, ruleName: rule.id });
+      }
+    }
+  }
+
+  // Filter out preferMustacheComments warnings on disable-directive comments themselves
+  return errors.filter(e =>
+    !(e.message.includes('HTML comment found') && parseDisableDirective(e.node, customRuleIds) !== null)
+  );
+}