@reteps/tree-sitter-htmlmustache 0.4.2 → 0.5.1

package/README.md

@@ -212,6 +212,52 @@ Create a `.htmlmustache.jsonc` file in your project root to configure formatting
 }
 ```
 
+### Lint Rules
+
+The following checks are always enabled and report as errors:
+
+- **Syntax errors** — invalid or unparseable template syntax
+- **Missing tokens** — e.g. a missing closing `>`
+- **Mismatched mustache sections** — `{{/wrong}}` closing a different section than was opened
+- **Mismatched HTML tags** — closing tags that don't match their opening tag, including across mustache branches
+- **Unclosed HTML tags** — non-void elements that are never closed
+
+Additionally, the following rules are configurable. Set their severities (`"error"`, `"warning"`, or `"off"`) in the `rules` object:
+
+```jsonc
+{
+  "rules": {
+    "consecutiveDuplicateSections": "off",
+    "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 |
+
+<!-- RULES_TABLE_END -->
+
+### Disabling Lint Rules
+
+Disable a configurable 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.
+
 ### EditorConfig
 
 Both the CLI and VS Code extension respect your `.editorconfig` file for indentation settings (`indent_style`, `indent_size`). EditorConfig values override `.htmlmustache.jsonc` for indentation, and CLI flags override everything.

package/cli/out/main.js

@@ -544,6 +544,51 @@ function parseDocument(source) {
 // lsp/server/src/configFile.ts
 var fs = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
+
+// lsp/server/src/ruleMetadata.ts
+var RULES = [
+  {
+    name: "nestedDuplicateSections",
+    defaultSeverity: "error",
+    description: "Flags `{{#name}}` nested inside another `{{#name}}` with the same name"
+  },
+  {
+    name: "unquotedMustacheAttributes",
+    defaultSeverity: "error",
+    description: "Requires quotes around mustache expressions used as attribute values"
+  },
+  {
+    name: "consecutiveDuplicateSections",
+    defaultSeverity: "warning",
+    description: "Warns when adjacent same-name sections can be merged"
+  },
+  {
+    name: "selfClosingNonVoidTags",
+    defaultSeverity: "error",
+    description: "Disallows self-closing syntax on non-void HTML elements (e.g. `<div/>`)"
+  },
+  {
+    name: "duplicateAttributes",
+    defaultSeverity: "error",
+    description: "Detects duplicate HTML attributes on the same element"
+  },
+  {
+    name: "unescapedEntities",
+    defaultSeverity: "warning",
+    description: "Flags unescaped `&` and `>` characters in text content"
+  },
+  {
+    name: "preferMustacheComments",
+    defaultSeverity: "off",
+    description: "Suggests replacing HTML comments with mustache comments"
+  }
+];
+var KNOWN_RULE_NAMES = new Set(RULES.map((r) => r.name));
+var RULE_DEFAULTS = Object.fromEntries(
+  RULES.map((r) => [r.name, r.defaultSeverity])
+);
+
+// lsp/server/src/configFile.ts
 var VALID_CSS_DISPLAY_VALUES = /* @__PURE__ */ new Set([
   "block",
   "inline",
@@ -563,6 +608,7 @@ var VALID_CSS_DISPLAY_VALUES = /* @__PURE__ */ new Set([
   "ruby-text",
   "none"
 ]);
+var VALID_RULE_SEVERITIES = /* @__PURE__ */ new Set(["error", "warning", "off"]);
 var CONFIG_FILENAME = ".htmlmustache.jsonc";
 function parseJsonc(text2) {
   let result = "";
@@ -682,6 +728,18 @@ function validateConfig(raw) {
     }
     config.customTags = Array.from(mergedMap.values());
   }
+  if (obj.rules && typeof obj.rules === "object" && !Array.isArray(obj.rules)) {
+    const rawRules = obj.rules;
+    const rules = {};
+    let hasRules = false;
+    for (const [key, value] of Object.entries(rawRules)) {
+      if (KNOWN_RULE_NAMES.has(key) && typeof value === "string" && VALID_RULE_SEVERITIES.has(value)) {
+        rules[key] = value;
+        hasRules = true;
+      }
+    }
+    if (hasRules) config.rules = rules;
+  }
   return config;
 }
 function loadConfigFileForPath(filePath) {
@@ -1274,6 +1332,35 @@ function checkUnescapedEntities(rootNode) {
   visit(rootNode);
   return errors;
 }
+function checkHtmlComments(rootNode) {
+  const errors = [];
+  function visit(node) {
+    if (node.type === "html_comment") {
+      const raw = node.text;
+      let content = raw;
+      if (content.startsWith("<!--")) content = content.slice(4);
+      if (content.endsWith("-->")) content = content.slice(0, -3);
+      content = content.trim();
+      errors.push({
+        node,
+        message: `HTML comment found \u2014 use mustache comment {{! ... }} instead`,
+        severity: "warning",
+        fix: [{
+          startIndex: node.startIndex,
+          endIndex: node.endIndex,
+          newText: `{{! ${content} }}`
+        }],
+        fixDescription: "Replace HTML comment with mustache comment"
+      });
+      return;
+    }
+    for (const child of node.children) {
+      visit(child);
+    }
+  }
+  visit(rootNode);
+  return errors;
+}
 function checkDuplicateAttributes(rootNode) {
   const errors = [];
   function visit(node) {
@@ -1335,7 +1422,39 @@ function errorMessageForNode(nodeType, node) {
   }
   return `Missing ${nodeType}`;
 }
-function collectErrors(tree) {
+function resolveRuleSeverity(rules, ruleName) {
+  return rules?.[ruleName] ?? RULE_DEFAULTS[ruleName] ?? "off";
+}
+function parseDisableDirective(node) {
+  if (node.type !== "html_comment" && node.type !== "mustache_comment") return null;
+  let inner = 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();
+  return KNOWN_RULE_NAMES.has(ruleName) ? ruleName : null;
+}
+function collectDisabledRules(rootNode) {
+  const disabled = /* @__PURE__ */ new Set();
+  function walk(node) {
+    const rule = parseDisableDirective(node);
+    if (rule) {
+      disabled.add(rule);
+      return;
+    }
+    for (const child of node.children) walk(child);
+  }
+  walk(rootNode);
+  return disabled;
+}
+function collectErrors(tree, rules) {
   const errors = [];
   const cursor = tree.walk();
   function visit() {
@@ -1364,30 +1483,42 @@ function collectErrors(tree) {
   for (const error of unclosedErrors) {
     errors.push({ node: error.node, message: error.message });
   }
+  const disabledRules = collectDisabledRules(tree.rootNode);
+  const effectiveRules = { ...rules };
+  for (const rule of disabledRules) {
+    effectiveRules[rule] = "off";
+  }
   const sourceText = tree.rootNode.text;
-  const mustacheChecks = [
-    ...checkNestedSameNameSections(tree.rootNode),
-    ...checkUnquotedMustacheAttributes(tree.rootNode),
-    ...checkConsecutiveSameNameSections(tree.rootNode, sourceText),
-    ...checkSelfClosingNonVoidTags(tree.rootNode),
-    ...checkDuplicateAttributes(tree.rootNode),
-    ...checkUnescapedEntities(tree.rootNode)
+  const ruleChecks = [
+    { 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) }
   ];
-  for (const error of mustacheChecks) {
-    errors.push({
-      node: error.node,
-      message: error.message,
-      severity: error.severity,
-      fix: error.fix,
-      fixDescription: error.fixDescription
-    });
+  for (const { rule, errors: getErrors } of ruleChecks) {
+    const severity = resolveRuleSeverity(effectiveRules, rule);
+    if (severity === "off") continue;
+    for (const error of getErrors()) {
+      errors.push({
+        node: error.node,
+        message: error.message,
+        severity,
+        fix: error.fix,
+        fixDescription: error.fixDescription
+      });
+    }
   }
-  return errors;
+  return errors.filter(
+    (e) => !(e.message.includes("HTML comment found") && parseDisableDirective(e.node) !== null)
+  );
 }
 
 // cli/src/check.ts
-function collectErrors2(tree, file) {
-  const errors = collectErrors(tree);
+function collectErrors2(tree, file, rules) {
+  const errors = collectErrors(tree, rules);
   return errors.map((error) => ({
     file,
     line: error.node.startPosition.row + 1,
@@ -1570,12 +1701,13 @@ async function run(args) {
   let filesWithErrors = 0;
   const cwd = process.cwd();
   const errorOutput = [];
+  const rules = config?.rules;
   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);
+      const errors2 = collectErrors2(tree2, displayPath, rules);
       const fixed = applyFixes(source, errors2);
       if (fixed !== source) {
         import_node_fs.default.writeFileSync(file, fixed, "utf-8");
@@ -1583,7 +1715,7 @@ async function run(args) {
       }
     }
     const tree = parseDocument(source);
-    const errors = collectErrors2(tree, displayPath);
+    const errors = collectErrors2(tree, displayPath, rules);
     const fileErrors = errors.filter((e) => e.severity !== "warning");
     const fileWarnings = errors.filter((e) => e.severity === "warning");
     if (errors.length > 0) {
@@ -2764,25 +2896,21 @@ function formatScriptStyleElement(node, context) {
           const dedented = dedentContent(child.text);
           if (dedented.length > 0) {
             const contentLines = dedented.split("\n");
-            if (contentLines.length === 1) {
-              parts.push(text(contentLines[0]));
-            } else {
-              const lineDocs = [];
-              for (let j = 0; j < contentLines.length; j++) {
-                if (j > 0) {
-                  if (contentLines[j] === "") {
-                    lineDocs.push("\n");
-                  } else {
-                    lineDocs.push(hardline);
-                  }
-                }
-                if (contentLines[j] !== "") {
-                  lineDocs.push(text(contentLines[j]));
+            const lineDocs = [];
+            for (let j = 0; j < contentLines.length; j++) {
+              if (j > 0) {
+                if (contentLines[j] === "") {
+                  lineDocs.push("\n");
+                } else {
+                  lineDocs.push(hardline);
                 }
               }
-              parts.push(indent(concat([hardline, ...lineDocs])));
-              parts.push(hardline);
+              if (contentLines[j] !== "") {
+                lineDocs.push(text(contentLines[j]));
+              }
             }
+            parts.push(indent(concat([hardline, ...lineDocs])));
+            parts.push(hardline);
           }
         }
       }
@@ -3160,7 +3288,8 @@ function formatBlockChildren(nodes, context) {
       pendingBlankLine = false;
     } else if (node.type === "html_comment" || node.type === "mustache_comment") {
       const isMultiline = node.startPosition.row !== node.endPosition.row;
-      if (isMultiline) {
+      const isOnOwnLine = i > 0 && node.startPosition.row > nodes[i - 1].endPosition.row;
+      if (isMultiline || isOnOwnLine) {
         if (currentLine.length > 0) {
           const lineContent = trimDoc(flushCurrentLine());
           if (hasDocContent(lineContent)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reteps/tree-sitter-htmlmustache",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "HTML with Mustache/Handlebars template syntax grammar for tree-sitter",
   "repository": {
     "type": "git",
@@ -89,6 +89,7 @@
     "prestart": "tree-sitter build --wasm",
     "start": "tree-sitter playground",
     "test": "tree-sitter test && node --test bindings/node/*_test.js",
-    "test:cli": "vitest run --config cli/vitest.config.ts"
+    "test:cli": "vitest run --config cli/vitest.config.ts",
+    "generate:rule-docs": "tsx scripts/generate-rule-docs.ts"
   }
 }