@reteps/tree-sitter-htmlmustache 0.6.0 → 0.7.1

package/README.md

@@ -228,36 +228,87 @@ Additionally, the following rules are configurable. Set their severities (`"erro
 {
   "rules": {
     "consecutiveDuplicateSections": "off",
-    "preferMustacheComments": "warning"
-  }
+    "preferMustacheComments": "warning",
+  },
 }
 ```
 
 <!-- RULES_TABLE_START -->
 
-| Rule | Default | Description |
-| --- | --- | --- |
-| `nestedDuplicateSections` | `error` | Flags `{{#name}}` nested inside another `{{#name}}` with the same name |
-| `unquotedMustacheAttributes` | `error` | Requires quotes around mustache expressions used as attribute values |
-| `consecutiveDuplicateSections` | `warning` | Warns when adjacent same-name sections can be merged |
-| `selfClosingNonVoidTags` | `error` | Disallows self-closing syntax on non-void HTML elements (e.g. `<div/>`) |
-| `duplicateAttributes` | `error` | Detects duplicate HTML attributes on the same element |
-| `unescapedEntities` | `warning` | Flags unescaped `&` and `>` characters in text content |
-| `preferMustacheComments` | `off` | Suggests replacing HTML comments with mustache comments |
-| `unrecognizedHtmlTags` | `error` | Flags HTML tags that are not standard HTML elements or valid custom elements |
+| Rule                           | Default   | Description                                                                  |
+| ------------------------------ | --------- | ---------------------------------------------------------------------------- |
+| `nestedDuplicateSections`      | `error`   | Flags `{{#name}}` nested inside another `{{#name}}` with the same name       |
+| `unquotedMustacheAttributes`   | `error`   | Requires quotes around mustache expressions used as attribute values         |
+| `consecutiveDuplicateSections` | `warning` | Warns when adjacent same-name sections can be merged                         |
+| `selfClosingNonVoidTags`       | `error`   | Disallows self-closing syntax on non-void HTML elements (e.g. `<div/>`)      |
+| `duplicateAttributes`          | `error`   | Detects duplicate HTML attributes on the same element                        |
+| `unescapedEntities`            | `warning` | Flags unescaped `&` and `>` characters in text content                       |
+| `preferMustacheComments`       | `off`     | Suggests replacing HTML comments with mustache comments                      |
+| `unrecognizedHtmlTags`         | `error`   | Flags HTML tags that are not standard HTML elements or valid custom elements |
 
 <!-- RULES_TABLE_END -->
 
+### Custom Rules
+
+Define project-specific lint rules using CSS-like selectors to match HTML elements and Mustache sections:
+
+```jsonc
+{
+  "customRules": [
+    {
+      "id": "no-font",
+      "selector": "font",
+      "message": "The <font> tag is deprecated. Use CSS instead.",
+    },
+    {
+      "id": "no-inline-styles",
+      "selector": "[style]",
+      "message": "Avoid inline styles",
+      "severity": "warning",
+    },
+    {
+      "id": "images-need-alt",
+      "selector": "img:not([alt])",
+      "message": "Images must have alt text for accessibility",
+    },
+    {
+      "id": "no-hidden-inputs-in-list",
+      "selector": "#items > input[type=hidden]",
+      "message": "Hidden inputs inside {{#items}} sections are usually a mistake",
+    },
+  ],
+}
+```
+
+Each custom rule requires an `id`, `selector`, and `message`. The `severity` defaults to `"error"` but can be set to `"warning"` or `"off"`.
+
+**Selector syntax:**
+
+| Selector             | Matches                                  |
+| -------------------- | ---------------------------------------- |
+| `div`                | HTML elements by tag name                |
+| `#items`             | Mustache sections by name (`{{#items}}`) |
+| `*`                  | Any HTML element                         |
+| `#`                  | Any Mustache section                     |
+| `div span`           | Descendant (span anywhere inside div)    |
+| `div > span`         | Direct child (span directly inside div)  |
+| `[style]`            | Attribute presence                       |
+| `input[type=hidden]` | Attribute value                          |
+| `img:not([alt])`     | Negated attribute                        |
+| `div, span`          | Comma-separated alternatives             |
+
+The `>` (child) combinator is kind-transparent: `div > span` matches even if a Mustache section sits between them (e.g. `<div>{{#show}}<span>{{/show}}</div>`), and `#a > #b` matches across intervening HTML elements.
+
 ### Disabling Lint Rules
 
-Disable a configurable lint rule for an entire file with an inline comment:
+Disable a lint rule for an entire file with an inline comment:
 
 ```html
 <!-- htmlmustache-disable preferMustacheComments -->
 {{! htmlmustache-disable selfClosingNonVoidTags }}
 ```
 
-The comment can appear anywhere in the file. Only configurable rules (listed above) can be disabled. Use multiple comments to disable multiple rules.
+The comment can appear anywhere in the file. Both built-in and custom rules can be disabled by name/id. Use multiple comments to disable multiple rules.
 
 ### EditorConfig
 

package/cli/out/main.js

@@ -748,6 +748,22 @@ function validateConfig(raw) {
     }
     if (hasRules) config.rules = rules;
   }
+  if (Array.isArray(obj.customRules)) {
+    const rules = [];
+    for (const entry of obj.customRules) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const e = entry;
+      if (typeof e.id !== "string" || e.id.length === 0) continue;
+      if (typeof e.selector !== "string" || e.selector.length === 0) continue;
+      if (typeof e.message !== "string" || e.message.length === 0) continue;
+      const rule = { id: e.id, selector: e.selector, message: e.message };
+      if (typeof e.severity === "string" && VALID_RULE_SEVERITIES.has(e.severity)) {
+        rule.severity = e.severity;
+      }
+      rules.push(rule);
+    }
+    if (rules.length > 0) config.customRules = rules;
+  }
   return config;
 }
 function loadConfigFileForPath(filePath) {
@@ -921,18 +937,29 @@ function mergeAdjacentForks(items) {
   }
   return result;
 }
-function hasTagEvents(items) {
+function isBranchBalanced(items) {
+  const stack = [];
   for (const item of items) {
-    if (item.type !== "fork") return true;
-    if (hasTagEvents(item.truthy) || hasTagEvents(item.falsy)) return true;
+    if (item.type === "fork") {
+      if (!isBranchBalanced(item.truthy) || !isBranchBalanced(item.falsy)) {
+        return false;
+      }
+    } else if (item.type === "open") {
+      stack.push(item.tagName);
+    } else {
+      if (stack.length === 0 || stack[stack.length - 1] !== item.tagName) {
+        return false;
+      }
+      stack.pop();
+    }
   }
-  return false;
+  return stack.length === 0;
 }
 function collectSectionNames(items) {
   const names = /* @__PURE__ */ new Set();
   for (const item of items) {
     if (item.type === "fork") {
-      if (hasTagEvents(item.truthy) || hasTagEvents(item.falsy)) {
+      if (!isBranchBalanced(item.truthy) || !isBranchBalanced(item.falsy)) {
         names.add(item.sectionName);
       }
       for (const name of collectSectionNames(item.truthy)) names.add(name);
@@ -1573,6 +1600,281 @@ function checkDuplicateAttributes(rootNode) {
   return errors;
 }
 
+// lsp/server/src/selectorMatcher.ts
+function isNameChar(ch) {
+  return /[a-zA-Z0-9\-_]/.test(ch);
+}
+function parseAttributes(raw, pos) {
+  const attrs = [];
+  while (pos.i < raw.length) {
+    if (raw[pos.i] === ":") {
+      if (raw.slice(pos.i, pos.i + 6).toLowerCase() !== ":not([") return attrs;
+      pos.i += 6;
+      const attr = parseOneAttribute(raw, pos, true);
+      if (!attr) return attrs;
+      if (raw[pos.i] !== "]" || raw[pos.i + 1] !== ")") return attrs;
+      pos.i += 2;
+      attrs.push(attr);
+    } else if (raw[pos.i] === "[") {
+      pos.i++;
+      const attr = parseOneAttribute(raw, pos, false);
+      if (!attr) return attrs;
+      if (raw[pos.i] !== "]") return attrs;
+      pos.i++;
+      attrs.push(attr);
+    } else {
+      break;
+    }
+  }
+  return attrs;
+}
+function parseOneAttribute(raw, pos, negated) {
+  let name = "";
+  while (pos.i < raw.length && isNameChar(raw[pos.i])) {
+    name += raw[pos.i];
+    pos.i++;
+  }
+  if (name.length === 0) return null;
+  let value;
+  if (raw[pos.i] === "=") {
+    pos.i++;
+    value = "";
+    if (raw[pos.i] === '"' || raw[pos.i] === "'") {
+      const quote = raw[pos.i];
+      pos.i++;
+      while (pos.i < raw.length && raw[pos.i] !== quote) {
+        value += raw[pos.i];
+        pos.i++;
+      }
+      if (pos.i < raw.length) pos.i++;
+    } else {
+      while (pos.i < raw.length && raw[pos.i] !== "]") {
+        value += raw[pos.i];
+        pos.i++;
+      }
+    }
+  }
+  return { name: name.toLowerCase(), value, negated };
+}
+function parseSelector(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+  const parts = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (parts.length === 0) return null;
+  const alternatives = [];
+  for (const part of parts) {
+    const alt = parseSingleSelector(part);
+    if (!alt) return null;
+    alternatives.push(alt);
+  }
+  return { alternatives };
+}
+function parseSingleSelector(raw) {
+  const segments = [];
+  let i = 0;
+  let nextCombinator = "descendant";
+  while (i < raw.length) {
+    while (i < raw.length && raw[i] === " ") i++;
+    if (i >= raw.length) break;
+    if (raw[i] === ">") {
+      if (segments.length === 0) return null;
+      nextCombinator = "child";
+      i++;
+      while (i < raw.length && raw[i] === " ") i++;
+      if (i >= raw.length) return null;
+      continue;
+    }
+    const pos = { i };
+    const segment = parseOneSegment(raw, pos);
+    if (!segment) return null;
+    i = pos.i;
+    segment.combinator = nextCombinator;
+    nextCombinator = "descendant";
+    segments.push(segment);
+  }
+  if (segments.length === 0) return null;
+  return { segments };
+}
+function parseOneSegment(raw, pos) {
+  let kind;
+  let name;
+  if (raw[pos.i] === "#") {
+    kind = "mustache";
+    pos.i++;
+    name = "";
+    while (pos.i < raw.length && isNameChar(raw[pos.i])) {
+      name += raw[pos.i];
+      pos.i++;
+    }
+    if (name.length === 0) name = null;
+    else name = name.toLowerCase();
+    return { kind, name, attributes: [], combinator: "descendant" };
+  }
+  if (raw[pos.i] === "*") {
+    kind = "html";
+    name = null;
+    pos.i++;
+    const attrs2 = parseAttributes(raw, pos);
+    return { kind, name, attributes: attrs2, combinator: "descendant" };
+  }
+  if (raw[pos.i] === "[" || raw[pos.i] === ":") {
+    kind = "html";
+    name = null;
+    const attrs2 = parseAttributes(raw, pos);
+    if (attrs2.length === 0) return null;
+    return { kind, name, attributes: attrs2, combinator: "descendant" };
+  }
+  if (!isNameChar(raw[pos.i])) return null;
+  kind = "html";
+  name = "";
+  while (pos.i < raw.length && isNameChar(raw[pos.i])) {
+    name += raw[pos.i];
+    pos.i++;
+  }
+  name = name.toLowerCase();
+  const attrs = parseAttributes(raw, pos);
+  return { kind, name, attributes: attrs, combinator: "descendant" };
+}
+function getNodeAttributes(node) {
+  const startTag = node.children.find(
+    (c) => c.type === "html_start_tag" || c.type === "html_self_closing_tag"
+  );
+  if (!startTag) return [];
+  const attrs = [];
+  for (const child of startTag.children) {
+    if (child.type === "html_attribute") {
+      let attrName = "";
+      let attrValue;
+      for (const part of child.children) {
+        if (part.type === "html_attribute_name") {
+          attrName = part.text.toLowerCase();
+        } else if (part.type === "html_quoted_attribute_value") {
+          attrValue = part.text.replace(/^["']|["']$/g, "");
+        } else if (part.type === "html_attribute_value") {
+          attrValue = part.text;
+        }
+      }
+      if (attrName) attrs.push({ name: attrName, value: attrValue });
+    }
+  }
+  return attrs;
+}
+function checkAttributes(node, constraints) {
+  if (constraints.length === 0) return true;
+  const nodeAttrs = getNodeAttributes(node);
+  for (const constraint of constraints) {
+    const found = nodeAttrs.find((a) => a.name === constraint.name);
+    if (constraint.negated) {
+      if (found) return false;
+    } else if (constraint.value !== void 0) {
+      if (!found || found.value !== constraint.value) return false;
+    } else {
+      if (!found) return false;
+    }
+  }
+  return true;
+}
+function nodeMatchesSegment(node, segment) {
+  if (segment.kind === "html") {
+    if (!HTML_ELEMENT_TYPES.has(node.type)) return false;
+    if (segment.name !== null) {
+      const tagName = getTagName(node)?.toLowerCase();
+      if (tagName !== segment.name) return false;
+    }
+    return checkAttributes(node, segment.attributes);
+  }
+  if (!MUSTACHE_SECTION_TYPES.has(node.type)) return false;
+  if (segment.name !== null) {
+    const sectionName = getSectionName(node)?.toLowerCase();
+    if (sectionName !== segment.name) return false;
+  }
+  return true;
+}
+function checkAncestors(ancestors, segments, segIdx, childCombinator) {
+  if (segIdx < 0) return true;
+  const segment = segments[segIdx];
+  if (childCombinator === "child") {
+    for (let a = ancestors.length - 1; a >= 0; a--) {
+      const entry = ancestors[a];
+      if (entry.kind !== segment.kind) continue;
+      if (segment.name !== null && entry.name !== segment.name) return false;
+      if (segment.kind === "html" && segment.attributes.length > 0) {
+        if (!checkAttributes(entry.node, segment.attributes)) return false;
+      }
+      return checkAncestors(ancestors.slice(0, a), segments, segIdx - 1, segment.combinator);
+    }
+    return false;
+  }
+  for (let a = ancestors.length - 1; a >= 0; a--) {
+    const entry = ancestors[a];
+    if (entry.kind !== segment.kind) continue;
+    if (segment.name !== null && entry.name !== segment.name) continue;
+    if (segment.kind === "html" && segment.attributes.length > 0) {
+      if (!checkAttributes(entry.node, segment.attributes)) continue;
+    }
+    if (checkAncestors(ancestors.slice(0, a), segments, segIdx - 1, segment.combinator)) {
+      return true;
+    }
+  }
+  return false;
+}
+function getReportNode(node) {
+  if (HTML_ELEMENT_TYPES.has(node.type)) {
+    const startTag = node.children.find(
+      (c) => c.type === "html_start_tag" || c.type === "html_self_closing_tag"
+    );
+    return startTag ?? node;
+  }
+  if (MUSTACHE_SECTION_TYPES.has(node.type)) {
+    const begin = node.children.find(
+      (c) => c.type === "mustache_section_begin" || c.type === "mustache_inverted_section_begin"
+    );
+    return begin ?? node;
+  }
+  return node;
+}
+function matchAlternative(rootNode, alt) {
+  const results = [];
+  const lastSegment = alt.segments[alt.segments.length - 1];
+  function walk(node, ancestors) {
+    if (nodeMatchesSegment(node, lastSegment)) {
+      if (alt.segments.length === 1 || checkAncestors(ancestors, alt.segments, alt.segments.length - 2, lastSegment.combinator)) {
+        results.push(getReportNode(node));
+      }
+    }
+    let newAncestors = ancestors;
+    if (HTML_ELEMENT_TYPES.has(node.type)) {
+      const tagName = getTagName(node)?.toLowerCase();
+      if (tagName) {
+        newAncestors = [...ancestors, { kind: "html", name: tagName, node }];
+      }
+    } else if (MUSTACHE_SECTION_TYPES.has(node.type)) {
+      const sectionName = getSectionName(node)?.toLowerCase();
+      if (sectionName) {
+        newAncestors = [...ancestors, { kind: "mustache", name: sectionName, node }];
+      }
+    }
+    for (const child of node.children) {
+      walk(child, newAncestors);
+    }
+  }
+  walk(rootNode, []);
+  return results;
+}
+function matchSelector(rootNode, selector) {
+  const allResults = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const alt of selector.alternatives) {
+    for (const node of matchAlternative(rootNode, alt)) {
+      if (!seen.has(node)) {
+        seen.add(node);
+        allResults.push(node);
+      }
+    }
+  }
+  return allResults;
+}
+
 // lsp/server/src/collectErrors.ts
 var ERROR_NODE_TYPES = /* @__PURE__ */ new Set([
   "ERROR",
@@ -1592,7 +1894,7 @@ function errorMessageForNode(nodeType, node) {
 function resolveRuleSeverity(rules, ruleName) {
   return rules?.[ruleName] ?? RULE_DEFAULTS[ruleName] ?? "off";
 }
-function parseDisableDirective(node) {
+function parseDisableDirective(node, customRuleIds) {
   if (node.type !== "html_comment" && node.type !== "mustache_comment") return null;
   let inner = null;
   if (node.type === "html_comment") {
@@ -1606,12 +1908,14 @@ function parseDisableDirective(node) {
   const prefix = "htmlmustache-disable ";
   if (!inner.startsWith(prefix)) return null;
   const ruleName = inner.slice(prefix.length).trim();
-  return KNOWN_RULE_NAMES.has(ruleName) ? ruleName : null;
+  if (KNOWN_RULE_NAMES.has(ruleName)) return ruleName;
+  if (customRuleIds?.has(ruleName)) return ruleName;
+  return null;
 }
-function collectDisabledRules(rootNode) {
+function collectDisabledRules(rootNode, customRuleIds) {
   const disabled = /* @__PURE__ */ new Set();
   function walk(node) {
-    const rule = parseDisableDirective(node);
+    const rule = parseDisableDirective(node, customRuleIds);
     if (rule) {
       disabled.add(rule);
       return;
@@ -1621,7 +1925,7 @@ function collectDisabledRules(rootNode) {
   walk(rootNode);
   return disabled;
 }
-function collectErrors(tree, rules, customTagNames) {
+function collectErrors(tree, rules, customTagNames, customRules) {
   const errors = [];
   const cursor = tree.walk();
   function visit() {
@@ -1650,7 +1954,8 @@ function collectErrors(tree, rules, customTagNames) {
   for (const error of unclosedErrors) {
     errors.push({ node: error.node, message: error.message });
   }
-  const disabledRules = collectDisabledRules(tree.rootNode);
+  const customRuleIds = customRules ? new Set(customRules.map((r) => r.id)) : void 0;
+  const disabledRules = collectDisabledRules(tree.rootNode, customRuleIds);
   const effectiveRules = { ...rules };
   for (const rule of disabledRules) {
     effectiveRules[rule] = "off";
@@ -1675,18 +1980,32 @@ function collectErrors(tree, rules, customTagNames) {
         message: error.message,
         severity,
         fix: error.fix,
-        fixDescription: error.fixDescription
+        fixDescription: error.fixDescription,
+        ruleName: rule
       });
     }
   }
+  if (customRules) {
+    for (const rule of customRules) {
+      if (disabledRules.has(rule.id)) continue;
+      const severity = rule.severity ?? "error";
+      if (severity === "off") continue;
+      const parsed = parseSelector(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 });
+      }
+    }
+  }
   return errors.filter(
-    (e) => !(e.message.includes("HTML comment found") && parseDisableDirective(e.node) !== null)
+    (e) => !(e.message.includes("HTML comment found") && parseDisableDirective(e.node, customRuleIds) !== null)
   );
 }
 
 // cli/src/check.ts
-function collectErrors2(tree, file, rules, customTagNames) {
-  const errors = collectErrors(tree, rules, customTagNames);
+function collectErrors2(tree, file, rules, customTagNames, customRules) {
+  const errors = collectErrors(tree, rules, customTagNames, customRules);
   return errors.map((error) => ({
     file,
     line: error.node.startPosition.row + 1,
@@ -1871,12 +2190,13 @@ async function run(args) {
   const errorOutput = [];
   const rules = config?.rules;
   const customTagNames = config?.customTags?.map((t) => t.name);
+  const customRules = config?.customRules;
   for (const file of files) {
     const displayPath = import_node_path.default.relative(cwd, file) || file;
     let source = import_node_fs.default.readFileSync(file, "utf-8");
     if (fixMode) {
       const tree2 = parseDocument(source);
-      const errors2 = collectErrors2(tree2, displayPath, rules, customTagNames);
+      const errors2 = collectErrors2(tree2, displayPath, rules, customTagNames, customRules);
       const fixed = applyFixes(source, errors2);
       if (fixed !== source) {
         import_node_fs.default.writeFileSync(file, fixed, "utf-8");
@@ -1884,7 +2204,7 @@ async function run(args) {
       }
     }
     const tree = parseDocument(source);
-    const errors = collectErrors2(tree, displayPath, rules, customTagNames);
+    const errors = collectErrors2(tree, displayPath, rules, customTagNames, customRules);
     const fileErrors = errors.filter((e) => e.severity !== "warning");
     const fileWarnings = errors.filter((e) => e.severity === "warning");
     if (errors.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reteps/tree-sitter-htmlmustache",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "HTML with Mustache/Handlebars template syntax grammar for tree-sitter",
   "repository": {
     "type": "git",