@reteps/tree-sitter-htmlmustache 0.8.0 → 0.8.1

package/README.md

@@ -294,41 +294,57 @@ Each custom rule requires an `id`, `selector`, and `message`. The `severity` def
 
 **Selector syntax:**
 
-| Selector                                  | Matches                                       |
-| ----------------------------------------- | --------------------------------------------- |
-| `div`                                     | HTML elements by tag name                     |
-| `*`                                       | Any HTML element                              |
-| `#main`                                   | ID (shorthand for `[id="main"]`)              |
-| `.panel`                                  | Class (shorthand for `[class~="panel"]`)      |
-| `div span`                                | Descendant (span anywhere inside div)         |
-| `div > span`                              | Direct child                                  |
-| `[style]`                                 | Attribute presence                            |
-| `input[type=hidden]`                      | Attribute value (exact)                       |
-| `[src^="prefix/"]`                        | Attribute starts with                         |
-| `[href*="substring"]`                     | Attribute contains                            |
-| `[src$=".png"]`                           | Attribute ends with                           |
-| `[class~="warning"]`                      | Attribute contains whitespace-token           |
-| `img:not([alt])`                          | Negated attribute / class / id                |
-| `{{foo}}`                                 | Escaped variable `{{foo}}`                    |
-| `{{data.foo}}`                            | Variable with a dotted path                   |
-| `{{{foo}}}`                               | Triple / unescaped variable                   |
-| `{{options.*}}`                           | Variable path prefix match                    |
-| `{{*.deprecated}}`                        | Variable path suffix match                    |
-| `{{*}}`                                   | Any escaped variable                          |
-| `{{{*}}}`                                 | Any triple                                    |
-| `{{#items}}`                              | Section `{{#items}}...{{/items}}`             |
-| `{{^items}}`                              | Inverted section `{{^items}}...{{/items}}`    |
-| `{{#items}} > li`                         | Direct child inside a section                 |
-| `{{!TODO}}`                               | Comment with exact content                    |
-| `{{!*TODO*}}`                             | Comment containing "TODO"                     |
-| `{{>header}}`                             | Partial invocation                            |
-| `{{>legacy_*}}`                           | Partial name prefix                           |
-| `pl-multiple-choice:has({{foo}})`         | Element containing a given variable           |
-| `pl-multiple-choice:not(:has(pl-answer))` | Element missing a required descendant         |
-| `div, span`                               | Comma-separated alternatives                  |
+| Selector                                  | Matches                                    |
+| ----------------------------------------- | ------------------------------------------ |
+| `div`                                     | HTML elements by tag name                  |
+| `*`                                       | Any HTML element                           |
+| `#main`                                   | ID (shorthand for `[id="main"]`)           |
+| `.panel`                                  | Class (shorthand for `[class~="panel"]`)   |
+| `div span`                                | Descendant (span anywhere inside div)      |
+| `div > span`                              | Direct child                               |
+| `[style]`                                 | Attribute presence                         |
+| `input[type=hidden]`                      | Attribute value (exact)                    |
+| `[src^="prefix/"]`                        | Attribute starts with                      |
+| `[href*="substring"]`                     | Attribute contains                         |
+| `[src$=".png"]`                           | Attribute ends with                        |
+| `[class~="warning"]`                      | Attribute contains whitespace-token        |
+| `img:not([alt])`                          | Negated attribute / class / id             |
+| `{{foo}}`                                 | Escaped variable `{{foo}}`                 |
+| `{{data.foo}}`                            | Variable with a dotted path                |
+| `{{{foo}}}`                               | Triple / unescaped variable                |
+| `{{options.*}}`                           | Variable path prefix match                 |
+| `{{*.deprecated}}`                        | Variable path suffix match                 |
+| `{{*}}`                                   | Any escaped variable                       |
+| `{{{*}}}`                                 | Any triple                                 |
+| `{{#items}}`                              | Section `{{#items}}...{{/items}}`          |
+| `{{^items}}`                              | Inverted section `{{^items}}...{{/items}}` |
+| `{{#items}} > li`                         | Direct child inside a section              |
+| `{{!TODO}}`                               | Comment with exact content                 |
+| `{{!*TODO*}}`                             | Comment containing "TODO"                  |
+| `{{>header}}`                             | Partial invocation                         |
+| `{{>legacy_*}}`                           | Partial name prefix                        |
+| `pl-multiple-choice:has({{foo}})`         | Element containing a given variable        |
+| `pl-multiple-choice:not(:has(pl-answer))` | Element missing a required descendant      |
+| `div, span`                               | Comma-separated alternatives               |
+| `:root`                                   | The document root (the whole parse tree)   |
+| `:root:has(pl-answer-panel)`              | Document contains a descendant anywhere    |
+| `:root:not(:has(pl-answer-panel))`        | Document is missing a descendant anywhere  |
+| `:root > section`                         | Top-level element (direct child of root)   |
 
 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. `{{#foo}}` matches only positive sections — to target inverted sections use `{{^foo}}`.
 
+**Document-scoped conditional rules.** Use `:root` with `:has(...)` / `:not(:has(...))` to express rules that depend on the overall document. Chained `:has(...)` acts as AND, so you can combine "contains X" and "missing Y" in one selector:
+
+```jsonc
+{
+  "id": "question-needs-answer-panel",
+  "selector": ":root:has(pl-question-panel):not(:has(pl-answer-panel))",
+  "message": "A question-panel document must also declare a pl-answer-panel.",
+}
+```
+
+When `:root` matches, the diagnostic is reported at the start of the document (row 0, column 0) so the squiggle doesn't span the whole file. `:root` here is the tree-sitter fragment root, so it works on partial templates and fragments — unlike browser CSS, which anchors `:root` on `<html>`. Inside `:has(...)`, `:root` refers to the element being has-checked, not the document.
+
 ### Disabling Lint Rules
 
 Disable a lint rule for an entire file with an inline comment:

package/cli/out/main.js

@@ -1963,6 +1963,7 @@ function segmentFromCompound(ast) {
   let kind;
   let name = null;
   let pathRegex;
+  let rootOnly = false;
   const attributes = [];
   const descendantChecks = [];
   const forbidChange = (requested) => {
@@ -2021,6 +2022,11 @@ function segmentFromCompound(ast) {
           if (!applyNegatedSubtree(token.subtree, attributes, descendantChecks)) return null;
           break;
         }
+        if (token.name === "root") {
+          rootOnly = true;
+          if (kind === void 0) kind = "html";
+          break;
+        }
         return null;
       }
       default:
@@ -2030,9 +2036,12 @@ function segmentFromCompound(ast) {
   if (kind === void 0) {
     kind = "html";
   }
+  if (rootOnly) {
+    if (name !== null || attributes.length > 0 || kind !== "html") return null;
+  }
   const isHtml = kind === "html";
   const finalAttrs = isHtml ? attributes : [];
-  return { kind, name, pathRegex, attributes: finalAttrs, descendantChecks, combinator: "descendant" };
+  return { kind, rootOnly, name, pathRegex, attributes: finalAttrs, descendantChecks, combinator: "descendant" };
 }
 function mustacheKindFromMarker(name) {
   switch (name) {
@@ -2227,7 +2236,11 @@ function matchesName(actual, segment) {
   if (segment.pathRegex) return segment.pathRegex.test(actual);
   return actual === segment.name;
 }
-function nodeMatchesSegment(node, segment) {
+function nodeMatchesSegment(node, segment, rootNode) {
+  if (segment.rootOnly) {
+    if (node !== rootNode) return false;
+    return checkDescendants(node, segment.descendantChecks);
+  }
   switch (segment.kind) {
     case "html": {
       if (!HTML_ELEMENT_TYPES.has(node.type)) return false;
@@ -2271,7 +2284,10 @@ function checkAncestors(ancestors, segments, segIdx, childCombinator) {
   if (childCombinator === "child") {
     for (let a2 = ancestors.length - 1; a2 >= 0; a2--) {
       const entry = ancestors[a2];
-      if (entry.kind !== ancestorKind) continue;
+      if (entry.kind !== ancestorKind) {
+        if (ancestorKind === "root" && entry.kind === "html") return false;
+        continue;
+      }
       if (!matchesName(entry.name, segment)) return false;
       if (segment.kind === "html" && !checkAttributes(entry.node, segment.attributes)) return false;
       if (!checkDescendants(entry.node, segment.descendantChecks)) return false;
@@ -2292,12 +2308,13 @@ function checkAncestors(ancestors, segments, segIdx, childCombinator) {
   return false;
 }
 function ancestorKindForSegment(segment) {
+  if (segment.rootOnly) return "root";
   if (segment.kind === "html") return "html";
   if (segment.kind === "section") return "section";
   if (segment.kind === "inverted") return "inverted";
   return null;
 }
-function getReportNode(node) {
+function getReportNode(node, rootNode) {
   if (HTML_ELEMENT_TYPES.has(node.type)) {
     const startTag = node.children.find(
       (c2) => c2.type === "html_start_tag" || c2.type === "html_self_closing_tag"
@@ -2310,15 +2327,26 @@ function getReportNode(node) {
     );
     return begin ?? node;
   }
+  if (rootNode && node === rootNode) {
+    return {
+      type: node.type,
+      text: "",
+      startPosition: node.startPosition,
+      endPosition: { row: node.startPosition.row, column: node.startPosition.column + 1 },
+      startIndex: node.startIndex,
+      endIndex: Math.min(node.startIndex + 1, node.endIndex),
+      children: []
+    };
+  }
   return node;
 }
 function matchAlternative(rootNode, segments) {
   const results = [];
   const lastSegment = segments[segments.length - 1];
   function walk(node, ancestors) {
-    if (nodeMatchesSegment(node, lastSegment)) {
+    if (nodeMatchesSegment(node, lastSegment, rootNode)) {
       if (segments.length === 1 || checkAncestors(ancestors, segments, segments.length - 2, lastSegment.combinator)) {
-        results.push(getReportNode(node));
+        results.push(getReportNode(node, rootNode));
       }
     }
     let newAncestors = ancestors;
@@ -2331,7 +2359,7 @@ function matchAlternative(rootNode, segments) {
     }
     for (const child of node.children) walk(child, newAncestors);
   }
-  walk(rootNode, []);
+  walk(rootNode, [{ kind: "root", name: "", node: rootNode }]);
   return results;
 }
 function matchSelector(rootNode, selector) {

package/package.json

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