pi-lens 4.1.2 → 4.1.4

package/dist/clients/dispatch/runners/ast-grep-napi.js

@@ -2,22 +2,24 @@
  * ast-grep NAPI runner for dispatch system
  *
  * Uses @ast-grep/napi for programmatic parsing instead of CLI.
- * Handles TypeScript/JavaScript/CSS/HTML files with YAML rule support.
+ * The languages it can serve are exactly the grammars that addon bundles —
+ * see `NAPI_LANGUAGE_BINDINGS` for the matrix and for what the other twelve
+ * catalog languages deliver through instead.
  *
  * Replaces CLI-based runners for faster performance (100x speedup).
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { incrementDegradationCount, recordDegradationOnce, } from "../../degradation-ledger.js";
 import { loadAstGrepNapi, } from "../../deps/ast-grep-napi.js";
 import { minimatch } from "../../deps/minimatch.js";
-import { getAstGrepRuleSources, } from "../../sgconfig.js";
 import { logLatency } from "../../latency-logger.js";
+import { hasAuxiliaryLspPublishedForRoot } from "../../lsp/index.js";
+import { clearPendingAuxiliaryCoverage, hasPendingAuxiliaryCoverage, recordNapiFallbackCoverage, } from "../../lsp/pending-aux-coverage.js";
+import { getAstGrepRuleSources, } from "../../sgconfig.js";
 import { hasEslintConfig } from "../../tool-policy.js";
 import { enabledAuxiliaryLspServerIds } from "../auxiliary-lsp.js";
 import { classifyDefect } from "../diagnostic-taxonomy.js";
-import { recordDegradationOnce } from "../../degradation-ledger.js";
-import { isAuxiliaryLspAlive } from "../../lsp/index.js";
-import { resolveAstGrepNativeExe } from "../../lsp/wait-policy/index.js";
 import { PRIORITY } from "../priorities.js";
 import { calculateRuleComplexity, isOverlyBroadPattern, isStructuredRule, loadYamlRules, loadYamlRulesFresh, MAX_BLOCKING_RULE_COMPLEXITY, } from "./yaml-rule-parser.js";
 const defaultUnsupportedLanguageLog = new Set();
@@ -200,8 +202,85 @@ export function resetAstGrepNapiLoadState() {
     sgSessionHold = false;
     sgHoldReason = undefined;
 }
-// Supported extensions for NAPI
-const SUPPORTED_EXTS = [".ts", ".tsx", ".js", ".jsx", ".css", ".html", ".htm"];
+const NAPI_LANGUAGE_BINDINGS = [
+    // `.mts`/`.cts` and `.mjs`/`.cjs` are the same two grammars under a
+    // module-system-flavored extension; leaving them off the old hand list meant
+    // the whole catalog went dark on every ES/CommonJS module file (#2215).
+    {
+        ruleLanguage: "typescript",
+        napiExport: "ts",
+        extensions: [".ts", ".mts", ".cts"],
+    },
+    { ruleLanguage: "tsx", napiExport: "tsx", extensions: [".tsx"] },
+    {
+        ruleLanguage: "javascript",
+        napiExport: "js",
+        // `.jsx` stays on the `js` grammar it has always used here. The addon
+        // also exports a separate `jsx`, but switching to it is a matching
+        // change, not a coverage one, and belongs with its own fixtures.
+        extensions: [".js", ".jsx", ".mjs", ".cjs"],
+    },
+    { ruleLanguage: "css", napiExport: "css", extensions: [".css"] },
+    { ruleLanguage: "html", napiExport: "html", extensions: [".html", ".htm"] },
+];
+const BINDING_BY_EXTENSION = new Map(NAPI_LANGUAGE_BINDINGS.flatMap((binding) => binding.extensions.map((ext) => [ext, binding])));
+const SUPPORTED_RULE_LANGUAGES = NAPI_LANGUAGE_BINDINGS.map((binding) => binding.ruleLanguage);
+/**
+ * Rule `language:` tokens the shipped catalog carries that NO bundled napi
+ * grammar can parse. Their rules deliver through the ast-grep LSP/CLI, which
+ * ships its own grammar set — never in-process. One shared reason, so this is
+ * a list of decisions rather than twelve copies of a sentence: the addon
+ * bundles six grammars (see `NAPI_LANGUAGE_BINDINGS`) and nothing registers
+ * more at runtime.
+ *
+ * The LSP/CLI half of that claim is measured, not assumed: every entry below
+ * was run through the real `ast-grep run -l <lang>` on 2026-08-26 and parsed,
+ * with `cobol` as the negative control (`cobol is not supported!`, exit 2). So
+ * no catalog language is unreachable by BOTH engines — the issue's
+ * "genuinely missing" bucket is empty, and this list is a routing fact rather
+ * than a coverage hole.
+ *
+ * This is the deliberate-exclusion half of the #2215 contract; the served half
+ * is derived from the addon itself. `ast-grep-napi-language-coverage.test.ts`
+ * reds when a catalog language with enabled rules is in neither half.
+ */
+export const AST_GREP_LSP_ONLY_RULE_LANGUAGES = [
+    "c",
+    "cpp",
+    "csharp",
+    "go",
+    "java",
+    "kotlin",
+    "php",
+    "python",
+    "ruby",
+    "rust",
+    "scala",
+    "swift",
+];
+const LSP_ONLY_RULE_LANGUAGES = new Set(AST_GREP_LSP_ONLY_RULE_LANGUAGES);
+/**
+ * How a rule's declared language reaches the user. `unclassified` is the
+ * runtime signal that the #2215 class regrew: rules ship for a language nobody
+ * decided a delivery route for, so they may run nowhere at all.
+ */
+export function deliveryRouteForRuleLanguage(ruleLanguage) {
+    if (SUPPORTED_RULE_LANGUAGES.includes(ruleLanguage))
+        return "napi";
+    return LSP_ONLY_RULE_LANGUAGES.has(ruleLanguage)
+        ? "ast-grep-lsp-cli"
+        : "unclassified";
+}
+/**
+ * Delivery route for one aggregated skip key. A `mismatch:<rule>-><file>` key
+ * is a rule whose language this engine DOES serve and that simply isn't this
+ * file's grammar, so it still routes through napi on its own files.
+ */
+function skipRouteFor(key) {
+    return key.startsWith("mismatch:")
+        ? "napi"
+        : deliveryRouteForRuleLanguage(key);
+}
 /** Maximum matches per rule to prevent excessive false positives */
 const MAX_MATCHES_PER_RULE = 10;
 /** Maximum total diagnostics per file to prevent output spam */
@@ -302,7 +381,7 @@ function matchesRuleIgnores(filePath, root, patterns) {
     return patterns.some((pattern) => minimatch(rel, pattern, { dot: true }));
 }
 export function canHandle(filePath) {
-    return SUPPORTED_EXTS.includes(path.extname(filePath).toLowerCase());
+    return BINDING_BY_EXTENSION.has(path.extname(filePath).toLowerCase());
 }
 /**
  * The TypeScript grammar is a syntactic superset of JavaScript, so a
@@ -327,40 +406,246 @@ export function canHandle(filePath) {
  * parsed as tsx (ast-grep-tsx-coverage.test.ts) rather than assumed.
  * Without this exception the entire TS ruleset silently never runs on
  * `.tsx` files. `TSX`-tagged rules stay `.tsx`-exclusive; the exception
- * is TS→TSX only. Returns undefined for extensions this scoping doesn't
- * apply to (css/html), where no filtering is added.
+ * is TS→TSX only. Returns undefined for an extension outside the matrix.
  */
 export function ruleLanguageForFile(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
-    switch (ext) {
-        case ".ts":
-            return "typescript";
-        case ".tsx":
-            return "tsx";
-        case ".js":
-        case ".jsx":
-            return "javascript";
-        default:
-            return undefined;
-    }
+    return BINDING_BY_EXTENSION.get(path.extname(filePath).toLowerCase())
+        ?.ruleLanguage;
 }
+/**
+ * The grammar for `filePath` on the addon that actually loaded, or undefined
+ * when there is none.
+ *
+ * Both callers (this file's runner and clients/project-diagnostics/scanner.ts)
+ * gate on `canHandle` first, so an undefined return HERE means the matrix
+ * admitted the file and the addon then dropped it — the silent skip #2215 is
+ * about, which is why it records instead of just returning. An extension
+ * outside the matrix was never admitted, so it records nothing.
+ */
 export function getLang(filePath, sgModule) {
-    const ext = path.extname(filePath).toLowerCase();
-    switch (ext) {
-        case ".ts":
-            return sgModule.ts;
-        case ".tsx":
-            return sgModule.tsx;
-        case ".js":
-        case ".jsx":
-            return sgModule.js;
-        case ".css":
-            return sgModule.css;
-        case ".html":
-        case ".htm":
-            return sgModule.html;
-        default:
-            return undefined;
+    const binding = BINDING_BY_EXTENSION.get(path.extname(filePath).toLowerCase());
+    if (!binding)
+        return undefined;
+    const lang = sgModule[binding.napiExport];
+    if (!lang) {
+        recordDegradationOnce({
+            kind: "ast-grep-napi-language-unavailable",
+            subject: binding.ruleLanguage,
+            reason: `@ast-grep/napi exposes no "${binding.napiExport}" grammar; every ${binding.ruleLanguage} rule is skipped in-process this session`,
+        });
+    }
+    return lang;
+}
+/**
+ * Budget for embedded-`<script>` evaluation (#2347 review F2/F4). Every nonempty
+ * script body is reparsed as JS and EVERY `language: JavaScript` rule runs
+ * against it, so the work is `rules * bodies * body-size`, all multiplied by
+ * the native addon's per-call overhead. Measured on this seam (full catalog,
+ * real addon, 2026-08-30): ~8.5 ms per small body, ~9 s for 500 blocks, and
+ * ~19.5 s for one ~1 MiB dense body (the shape that made the byte axis the
+ * real bound). The caps apply to EVERY body — first one included — so an
+ * oversized single inline script is omitted and recorded like any other
+ * over-budget body. Hand-authored HTML carries a handful of small inline
+ * scripts, so the caps only ever trip on generated/pathological pages, where a
+ * bounded, recorded partial evaluation beats a seconds-long synchronous stall
+ * on the per-edit hook. Budget truncation is a coverage loss and is recorded
+ * (see `emitHtmlScriptDegradations`).
+ */
+export const MAX_SCRIPT_BODIES_EVALUATED = 64;
+/**
+ * Cumulative parsed script-body size cap; bounds the `rules * bytes` work.
+ * Every body — including the first — must fit within the running total.
+ */
+export const MAX_SCRIPT_BODY_BYTES_EVALUATED = 128 * 1024;
+/**
+ * UTF-16 code-unit indexes, in the original file, of every line start, newest
+ * line last. `@ast-grep/napi` reports line/column/index in UTF-16 code units
+ * (verified against 0.45.1 with `é` and emoji), so the line table must be
+ * built in the SAME unit; a UTF-8 byte walk would shift every coordinate that
+ * follows a multibyte character.
+ */
+function computeLineStartsUtf16(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 0x0a)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 0-based line and code-unit column for a UTF-16 index, via binary search. */
+function filePositionForIndex(lineStarts, index) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= index)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo, column: index - lineStarts[lo] };
+}
+/**
+ * Extract every `<script>` body from an HTML root and parse it as JavaScript
+ * (#2347). Mirrors the ast-grep CLI/LSP: the injection is unconditional —
+ * `type` and `src` attributes do not suppress it (verified against the 0.45.1
+ * CLI with `text/template`, `application/ld+json`, and `src`-bearing script
+ * tags, all injected). Whitespace-only bodies are skipped (nothing to match).
+ * A body the JS grammar cannot parse is dropped the way an unparseable `.js`
+ * file would be; the failure is counted, never silent. The evaluation budget
+ * (count + cumulative bytes) is applied BEFORE any grammar parse. The caller
+ * emits the bounded degradation records from the result — collection stays
+ * pure so the count evidence is directly testable.
+ */
+export function collectHtmlScriptInjections(htmlRoot, sgModule) {
+    // SAFETY: `AstGrepNapi` is the loaded addon module's own (typed) shape, so
+    // its `js` accessor is guaranteed present while the addon lives; this
+    // narrowing only names the subshape this helper consumes (a `js` grammar
+    // whose parses expose `findAll`), and the absence check right below
+    // degrades to "no embedded coverage" rather than throwing when the addon
+    // ever drops the grammar.
+    const addon = sgModule;
+    if (!addon.js) {
+        return {
+            injections: [],
+            scriptElementCount: 0,
+            bodiesEvaluated: 0,
+            truncatedBodies: 0,
+            parseFailures: 0,
+            missingJsGrammar: true,
+            htmlScanFailure: false,
+        };
+    }
+    let scripts;
+    try {
+        scripts = htmlRoot.findAll({ rule: { kind: "script_element" } });
+    }
+    catch {
+        return {
+            injections: [],
+            scriptElementCount: 0,
+            bodiesEvaluated: 0,
+            truncatedBodies: 0,
+            parseFailures: 0,
+            missingJsGrammar: false,
+            htmlScanFailure: true,
+        };
+    }
+    // Extract every nonempty body first (text extraction is cheap) so the raw
+    // script-element count is exact, then apply the budget BEFORE parsing any
+    // of them.
+    let scriptElementCount = 0;
+    const candidates = [];
+    for (const element of scripts) {
+        scriptElementCount += 1;
+        let raw;
+        for (const child of element.children()) {
+            if (child.kind() === "raw_text") {
+                raw = child;
+                break;
+            }
+        }
+        if (!raw)
+            continue;
+        const body = raw.text();
+        if (!body.trim())
+            continue;
+        candidates.push({
+            body,
+            startIndex: raw.range().start.index,
+        });
+    }
+    let budgetedBytes = 0;
+    const selected = [];
+    let truncatedBodies = 0;
+    for (const candidate of candidates) {
+        const bytes = Buffer.byteLength(candidate.body, "utf8");
+        // EVERY body must fit inside both caps — including the first. There is
+        // no "one big script" allowance: a single over-cap body (a ~1 MiB dense
+        // inline script measured 19.5 s of synchronous rule traversal on this
+        // seam) is omitted like any other over-budget body, and the omission is
+        // recorded via `truncatedBodies`, so the bounded
+        // `ast-grep-napi-html-script-budget` degradation record always explains
+        // why that file lost embedded coverage.
+        if (selected.length >= MAX_SCRIPT_BODIES_EVALUATED ||
+            budgetedBytes + bytes > MAX_SCRIPT_BODY_BYTES_EVALUATED) {
+            truncatedBodies += 1;
+            continue;
+        }
+        selected.push(candidate);
+        budgetedBytes += bytes;
+    }
+    const injections = [];
+    let parseFailures = 0;
+    for (const candidate of selected) {
+        try {
+            const root = addon.js.parse(candidate.body).root();
+            injections.push({
+                body: candidate.body,
+                startIndex: candidate.startIndex,
+                root,
+            });
+        }
+        catch {
+            parseFailures += 1;
+        }
+    }
+    return {
+        injections,
+        scriptElementCount,
+        bodiesEvaluated: selected.length,
+        truncatedBodies,
+        parseFailures,
+        missingJsGrammar: false,
+        htmlScanFailure: false,
+    };
+}
+/**
+ * Emit bounded, discriminating degradation records for every embedded-script
+ * coverage loss (#2347 review F3). Each failure mode keeps its own kind so the
+ * ledger answers WHICH failure and WHICH file; subjects are the normalized file
+ * path, bounded by the ledger's own per-kind window. Collection failures
+ * (`missingJsGrammar`, `htmlScanFailure`) are once-per-file-per-session
+ * categorical events; parse failures and budget truncation are counted per file
+ * so the EXACT totals survive past the retained-entry window.
+ */
+function emitHtmlScriptDegradations(filePath, result) {
+    if (result.missingJsGrammar) {
+        recordDegradationOnce({
+            kind: "ast-grep-napi-html-js-grammar-missing",
+            subject: filePath,
+            reason: "addon exposes no js grammar; embedded <script> coverage dropped",
+        });
+    }
+    if (result.htmlScanFailure) {
+        recordDegradationOnce({
+            kind: "ast-grep-napi-html-script-scan-failed",
+            subject: filePath,
+            reason: "script_element enumeration failed; embedded <script> coverage dropped",
+        });
+    }
+    if (result.parseFailures > 0) {
+        incrementDegradationCount({
+            kind: "ast-grep-napi-html-script-parse-failed",
+            subject: filePath,
+            reason: `${result.parseFailures} of ${result.bodiesEvaluated} script bodies refused to parse as JS`,
+            metadata: {
+                scriptElementCount: result.scriptElementCount,
+                parseFailures: result.parseFailures,
+            },
+        });
+    }
+    if (result.truncatedBodies > 0) {
+        incrementDegradationCount({
+            kind: "ast-grep-napi-html-script-budget",
+            subject: filePath,
+            reason: `script budget truncated coverage: ${result.bodiesEvaluated}/${result.scriptElementCount} bodies evaluated, ${result.truncatedBodies} dropped`,
+            metadata: {
+                scriptElementCount: result.scriptElementCount,
+                bodiesEvaluated: result.bodiesEvaluated,
+                truncatedBodies: result.truncatedBodies,
+            },
+        });
     }
 }
 function duplicateRuleIds(rules) {
@@ -439,6 +724,38 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
     const seenRuleIds = new Set();
     const suppressLinterOverlap = kind === "jsts" && hasEslintConfig(cwd);
     const fileLang = ruleLanguageForFile(filePath);
+    // Embedded `<script>` coverage (#2347): on an HTML file, every script body
+    // is parsed as JavaScript and `language: JavaScript` rules run inside it —
+    // the exact behavior the ast-grep CLI/LSP has (verified against 0.45.1).
+    // `content` + `sgModule` are only needed for HTML; other callers of this
+    // shared seam (the per-edit runner and the project scanner both now pass
+    // them) cost a no-op on non-HTML files. The collection is budget-bounded
+    // and every silent-failure mode plus the budget cut is recorded, so "no
+    // embedded findings" stays distinguishable from "coverage was dropped"
+    // (#2347 review F2/F3).
+    const htmlCollection = fileLang === "html" &&
+        options.content !== undefined &&
+        options.sgModule !== undefined
+        ? collectHtmlScriptInjections(rootNode, options.sgModule)
+        : {
+            injections: [],
+            scriptElementCount: 0,
+            bodiesEvaluated: 0,
+            truncatedBodies: 0,
+            parseFailures: 0,
+            missingJsGrammar: false,
+            htmlScanFailure: false,
+        };
+    const htmlInjections = htmlCollection.injections;
+    emitHtmlScriptDegradations(filePath, htmlCollection);
+    // UTF-16 code-unit index of each line start in the ORIGINAL file, used to
+    // translate an injected match's body-relative UTF-16 index back to file
+    // line/column. The unit matters: napi positions are UTF-16, so a UTF-8 byte
+    // table would shift every coordinate after a multibyte character (#2347
+    // review F1).
+    const fileLineStarts = htmlInjections.length > 0 && options.content !== undefined
+        ? computeLineStartsUtf16(options.content)
+        : [];
     // Unsupported-language skips are expected in bulk (every non-jsts rule in the
     // catalog, e.g. ~30 Python rules) — aggregate them into ONE latency-log entry
     // per evaluation instead of per-rule terminal lines (#282 follow-up).
@@ -467,6 +784,25 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                     {
                         count: ruleIds.length,
                         ruleIds: ruleIds.slice(0, UNSUPPORTED_RULE_ID_SAMPLE_SIZE),
+                        // #2215: a skip count alone says a rule did not run and
+                        // nothing about whether it runs anywhere else. `route` names
+                        // the delivery path (`ast-grep-lsp-cli` for the twelve
+                        // grammar-less catalog languages); `unclassified` means rules
+                        // ship for a language nobody decided a route for, which is the
+                        // class this issue closed regrowing.
+                        route: skipRouteFor(language),
+                        // #2347 observability: on an HTML file the per-language skip
+                        // count is only part of the picture — `mismatch:*->html`
+                        // entries name a rule family that never enters scripts, and
+                        // `htmlInlineScriptCount` says whether the file offered any
+                        // script bodies to enter. A `javascript->html` mismatch here
+                        // is necessarily `0` (JS rules RUN when scripts exist), so the
+                        // field makes "no injection target" distinguishable from the
+                        // same key on a plain non-HTML file, keeping the residual
+                        // coverage gap countable in production.
+                        ...(fileLang === "html"
+                            ? { htmlInlineScriptCount: htmlInjections.length }
+                            : {}),
                     },
                 ])),
             },
@@ -520,11 +856,14 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 !isStructuredRule(rule)) {
                 continue;
             }
+            // CSS and HTML rules are scoped to their parsed roots.
+            // Without this scope, language-tagged rules scan unrelated roots.
+            // The file-language mismatch check below enforces this scope.
+            // CSS rules therefore run only on CSS roots.
+            // This preserves CSS rule findings while avoiding unrelated scans.
+            // The fallback and LSP paths share the same parsed-language scope.
             const lang = rule.language?.toLowerCase();
-            if (lang &&
-                lang !== "typescript" &&
-                lang !== "tsx" &&
-                lang !== "javascript") {
+            if (lang && !SUPPORTED_RULE_LANGUAGES.includes(lang)) {
                 if (!unsupportedLanguageLog.has(lang)) {
                     const ids = newlyUnsupported.get(lang) ?? [];
                     ids.push(rule.id);
@@ -544,9 +883,20 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
             // rules) goes dark on every .tsx file. `language: TSX` rules
             // stay tsx-exclusive — they're already scoped to fileLang
             // "tsx" by the exact-match check.
+            // #2347: `language: JavaScript` rules run INSIDE an HTML file's
+            // embedded `<script>` bodies instead of being filtered out as a
+            // language mismatch — that filter is what closed napi's embedded
+            // coverage entirely while the ast-grep CLI/LSP resolves the
+            // injections itself. Only when the file has at least one inline
+            // script body; with none, a `javascript->html` rule stays a
+            // genuine mismatch with nothing to run against (countable via
+            // `htmlInlineScriptCount` in the skip record).
+            const runsInsideHtmlScript = fileLang === "html" &&
+                lang === "javascript" &&
+                htmlInjections.length > 0;
             if (lang && fileLang && lang !== fileLang) {
                 const runsAsTsOnTsx = fileLang === "tsx" && lang === "typescript";
-                if (!runsAsTsOnTsx) {
+                if (!runsAsTsOnTsx && !runsInsideHtmlScript) {
                     const key = `mismatch:${lang}->${fileLang}`;
                     if (!unsupportedLanguageLog.has(key)) {
                         const ids = newlyUnsupported.get(key) ?? [];
@@ -565,7 +915,31 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
             if (!rule.rule)
                 continue;
             try {
-                let matches = [];
+                // A `language: JavaScript` rule on an HTML file with inline
+                // scripts runs against EACH parsed script body; every other rule
+                // runs against the file root. `scope.position` maps a match onto
+                // 0-based FILE line/column — injection matches are body-relative
+                // and must be translated via the injection's `startIndex` and the
+                // file's line-start table, all in UTF-16 code units (#2347); the
+                // file-root scope is the node's own range, so its derived
+                // id/diagnostic stay byte-identical to the pre-#2347 path.
+                const scopes = runsInsideHtmlScript
+                    ? htmlInjections.map((injection) => ({
+                        root: injection.root,
+                        position(match) {
+                            const start = match.range().start;
+                            return filePositionForIndex(fileLineStarts, injection.startIndex + start.index);
+                        },
+                    }))
+                    : [
+                        {
+                            root: rootNode,
+                            position(match) {
+                                const start = match.range().start;
+                                return { line: start.line, column: start.column };
+                            },
+                        },
+                    ];
                 // Delegate matching to napi's native engine, which handles the
                 // full ast-grep rule grammar (pattern, kind, has/inside/follows/
                 // precedes/stopBy/field/nthChild, any/all/not) plus metavariable
@@ -574,28 +948,41 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 // (#663; `NapiConfig.utils: Record<string, Rule>` per
                 // @ast-grep/napi's types, same shape napi already expects for
                 // `rule`/`constraints`). A faithful js-yaml parse feeds the rule
-                // object straight through. If napi rejects the rule (a malformed
-                // or invalid-kind rule, or an unresolved `matches:` reference),
-                // skip it — never silently match nothing through a partial
-                // interpreter.
+                // object straight through. If napi rejects the rule for a scope
+                // (a malformed or invalid-kind rule, or an unresolved `matches:`
+                // reference), skip that scope — never silently match nothing
+                // through a partial interpreter. The reject log fires once per
+                // rule; a grammar-level rejection is uniform across scopes.
                 const nativeConfig = { rule: rule.rule };
                 if (rule.constraints)
                     nativeConfig.constraints = rule.constraints;
                 if (rule.utils)
                     nativeConfig.utils = rule.utils;
-                try {
-                    matches = rootNode.findAll(nativeConfig);
-                }
-                catch (err) {
-                    matches = [];
-                    log?.(`ast-grep-napi: rule "${rule.id}" rejected by native engine (${err instanceof Error ? err.message : String(err)})`);
+                const collected = [];
+                let rejectLogged = false;
+                for (const scope of scopes) {
+                    let found;
+                    try {
+                        found = scope.root.findAll(nativeConfig);
+                    }
+                    catch (err) {
+                        if (!rejectLogged) {
+                            rejectLogged = true;
+                            log?.(`ast-grep-napi: rule "${rule.id}" rejected by native engine (${err instanceof Error ? err.message : String(err)})`);
+                        }
+                        continue;
+                    }
+                    for (const match of found) {
+                        if (collected.length >= maxMatchesPerRule)
+                            break;
+                        collected.push({ match, position: scope.position(match) });
+                    }
+                    if (collected.length >= maxMatchesPerRule)
+                        break;
                 }
-                const limitedMatches = matches.slice(0, maxMatchesPerRule);
-                for (const match of limitedMatches) {
+                for (const { position } of collected) {
                     if (diagnostics.length >= maxTotalDiagnostics)
                         break;
-                    const node = match;
-                    const range = node.range();
                     // #1777: carry the rule's own tier through. The old collapse
                     // (`=== "error" ? "error" : "warning"`) erased hint and info,
                     // so the quiet tier the #1727 anti-slop rules ship at did not
@@ -608,11 +995,11 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                     const defectClass = classifyDefect(rule.id, "ast-grep-napi", rule.message || rule.id);
                     const ruleFix = explicitRuleFixSuggestion(rule);
                     diagnostics.push({
-                        id: `ast-grep-napi-${range.start.line}-${rule.id}`,
+                        id: `ast-grep-napi-${position.line}-${rule.id}`,
                         message: `[${rule.metadata?.category || "slop"}] ${rule.message || rule.id}`,
                         filePath,
-                        line: range.start.line + 1,
-                        column: range.start.column + 1,
+                        line: position.line + 1,
+                        column: position.column + 1,
                         severity,
                         semantic,
                         tool: "ast-grep-napi",
@@ -640,9 +1027,8 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
 // --- Runner Definition ---
 const astGrepNapiRunner = {
     id: "ast-grep-napi",
-    appliesTo: ["jsts"],
+    appliesTo: ["jsts", "css", "html"],
     priority: PRIORITY.SPECIALIZED_ANALYSIS,
-    enabledByDefault: true,
     skipTestFiles: true,
     async run(ctx) {
         if (!canHandle(ctx.filePath)) {
@@ -654,20 +1040,31 @@ const astGrepNapiRunner = {
         // report against the LSP's `tool: ast-grep` diagnostics. Resume ONLY as the
         // fallback when the binary is absent / can't spawn (Gate B).
         const astGrepLspEnabled = enabledAuxiliaryLspServerIds((f) => ctx.pi?.getFlag?.(f)).includes("ast-grep");
-        // Gate B asks whether the LSP will handle this file, not whether a bare
-        // `ast-grep` command happens to be on PATH. The launcher first tries the
-        // platform-native package binary, then PATH; mirror that resolution here.
-        // A live client covers the already-warm case, while a resolvable binary
-        // covers the cold case before the LSP has spawned for this root.
-        const astGrepLspAlive = astGrepLspEnabled
-            ? await isAuxiliaryLspAlive("ast-grep", ctx.filePath)
+        // Gate B asks whether the LSP has proved it can handle this root, not
+        // whether an ast-grep process or binary merely exists.
+        // A first publication covers the warm case. Process liveness and binary
+        // resolution do not: both precede proof that this root can publish findings.
+        const astGrepLspPublished = astGrepLspEnabled
+            ? await hasAuxiliaryLspPublishedForRoot("ast-grep", ctx.filePath)
             : false;
-        let astGrepBinaryResolvable = false;
-        if (astGrepLspEnabled && !astGrepLspAlive) {
-            astGrepBinaryResolvable =
-                Boolean(resolveAstGrepNativeExe()) || (await ctx.hasTool("ast-grep"));
-        }
-        if (astGrepLspEnabled && (astGrepLspAlive || astGrepBinaryResolvable)) {
+        if (astGrepLspEnabled && astGrepLspPublished) {
+            // #2324 F2/R2-C: "has this server EVER published for this file" can go
+            // stale — a LATER touch's aux-grace wait can find the server silent
+            // for the CURRENT content while an OLDER revision's publication still
+            // satisfies this per-file gate. Any pending late-aux entry visible
+            // HERE is necessarily a LEFTOVER from an earlier touch, never this
+            // one: the wait that marks a pair for THIS touch runs to completion
+            // (up to its own grace budget, ~1800ms) strictly AFTER this
+            // synchronous Gate-B check returns, so it cannot have marked
+            // anything yet. Re-running napi here would risk the F3 duplicate
+            // this fix closes, so the loss is made observable instead.
+            if (hasPendingAuxiliaryCoverage(ctx.filePath, "ast-grep")) {
+                incrementDegradationCount({
+                    kind: "aux-runner-findings-lost",
+                    subject: "ast-grep",
+                    reason: `Gate B skipped napi for ${ctx.filePath}: a pending late-auxiliary pair from an EARLIER touch is still undelivered while a prior publication satisfies the per-file gate`,
+                });
+            }
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
         const sgModule = await loadSg();
@@ -718,11 +1115,87 @@ const astGrepNapiRunner = {
         catch {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
+        // #2336: napi is standing in for the ast-grep auxiliary LSP exactly when
+        // that server is expected but has not published for this root. Gate B
+        // above already returned for the published case, so reaching here with
+        // the auxiliary enabled IS the substitute role.
+        const runningAsLspSubstitute = astGrepLspEnabled && !astGrepLspPublished;
+        if (runningAsLspSubstitute) {
+            // #2324 F3/R2-A/R2-B: napi is about to ACTUALLY EVALUATE RULES —
+            // every early-return skip above (load failure, missing file,
+            // unresolved language, stat/size/read/parse failure) is now behind
+            // us, so this run genuinely covers the file rather than reporting a
+            // zero-finding no-op. Placing this here (not at Gate-B's decision
+            // point) matters twice over:
+            //   - R2-B: a napi run that never reached rule evaluation must NOT
+            //     consume anything — an unparseable .html file, say, would
+            //     otherwise silence the LSP's legitimate late delivery for a
+            //     file napi never actually covered.
+            //   - R2-A: recording coverage HERE, keyed by timestamp, lets the
+            //     aux-grace wait (clients/lsp/index.ts) — which decides whether
+            //     to mark a pending pair for THIS touch strictly AFTER this
+            //     synchronous call returns — see that napi already delivered
+            //     and skip marking, instead of racing a clear against a mark
+            //     that has not been written yet.
+            // The clear below only ever removes a LEFTOVER pair from an
+            // EARLIER touch (this touch's own pair, if the wait decides to
+            // mark one, is marked strictly later) — that pair describes a
+            // PREVIOUS revision this fresh evaluation supersedes, so dropping
+            // it is safe. Unknown pairs are a no-op.
+            recordNapiFallbackCoverage(ctx.filePath);
+            clearPendingAuxiliaryCoverage(ctx.filePath, "ast-grep");
+        }
+        // #2336: the substitute runs at the severity floor the server it replaces
+        // would have used. The ast-grep auxiliary profile states that floor in
+        // words — "the rule severity is deliberate, so preserve ast-grep's
+        // severity semantics: ERROR can block, WARNING/INFO stay advisory"
+        // (clients/dispatch/auxiliary-lsp.ts:179-183). `blockingOnly` drops every
+        // rule whose declared severity is not `error`, which is 380 of the 481
+        // bundled rules, so the substitute delivered a fifth of the coverage the
+        // LSP delivers and the runner reported zero diagnostics in all 255
+        // retained dispatch records. Nothing downstream needs the filter for
+        // noise control: `dispatcher.ts` already shows only `semantic:
+        // "blocking"` diagnostics inline and routes warning-tier ones to
+        // lens_diagnostics, and `tree-sitter.ts:525` already runs its full query
+        // set under `blockingOnly` for the same reason.
+        //
+        // Scoped to the substitute role deliberately. Evaluating the full catalog
+        // costs ~6x more per file (measured on this repo: 2.4 ms -> 23 ms at 68
+        // lines, 19 ms -> 188 ms at 1275 lines), and outside the substitute role
+        // either the LSP is publishing (Gate B skipped napi already) or the user
+        // retired ast-grep with `no-ast-grep`. Paying the cost only when napi is
+        // the sole ast-grep surface buys coverage that nothing else provides.
         const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, {
-            blockingOnly: ctx.blockingOnly,
+            blockingOnly: runningAsLspSubstitute ? false : ctx.blockingOnly,
             projectRoot: ctx.projectRoot,
             log: (message) => ctx.log(message),
+            content,
+            sgModule,
         });
+        if (runningAsLspSubstitute) {
+            // #2336 observability: the dispatcher's own runner record carries
+            // `diagnosticCount`, which is what showed 0 of 255. It cannot say WHICH
+            // severity floor produced that count. One line per substitute run —
+            // the same cadence as the runner record it annotates — names the floor
+            // and the tier mix, so a future "napi found nothing" reading can tell
+            // an empty catalog pass from a filtered one.
+            const bySeverity = {};
+            for (const d of diagnostics) {
+                bySeverity[d.severity] = (bySeverity[d.severity] ?? 0) + 1;
+            }
+            logLatency({
+                type: "phase",
+                phase: "astgrep_napi_substitute_floor",
+                filePath: ctx.filePath,
+                durationMs: 0,
+                metadata: {
+                    floor: "lsp-equivalent",
+                    ctxBlockingOnly: ctx.blockingOnly === true,
+                    diagnosticCount: diagnostics.length,
+                    bySeverity,
+                },
+            });
+        }
         const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
         let semantic = "none";
         if (hasBlocking) {