pi-lens 3.8.69 → 3.8.71

package/dist/clients/dispatch/facts/function-facts.js

@@ -1,3 +1,4 @@
+import { findOwnerName } from "../../symbol-containment.js";
 import { extractFactsFromTree, firstChildOfType, walk, } from "./tree-sitter-facts.js";
 const BOUNDARY_PREFIXES = [
     "fetch",
@@ -160,6 +161,62 @@ function collectOutgoingCalls(body) {
     });
     return [...calls];
 }
+/**
+ * `obj.method()` call sites with a simple-identifier receiver (refs #655
+ * phase 2). Only the plain shape `identifier.identifier(...)` is captured —
+ * chained (`a.b.c()`), computed (`a[x]()`), and `this.`-receiver calls are
+ * left out of this list (they still show up in `outgoingCalls`'s flattened
+ * text form as before); those richer shapes need real type inference to
+ * resolve safely, which is out of scope for this bounded slice.
+ */
+function collectMemberCallSites(body) {
+    const sites = [];
+    walk(body, (node) => {
+        if (node.type !== "call_expression")
+            return;
+        const callee = (node.children ?? [])[0];
+        if (!callee || callee.type !== "member_expression")
+            return;
+        const object = (callee.children ?? [])[0];
+        const property = (callee.children ?? []).find((c) => c?.type === "property_identifier");
+        if (!object || object.type !== "identifier" || !property)
+            return;
+        sites.push({ receiver: object.text, method: property.text });
+    });
+    return sites;
+}
+/**
+ * Best-effort receiver -> class-name map for one function (refs #655 phase
+ * 2). Two clear, common shapes only — see {@link FunctionSummary.receiverTypes}.
+ */
+function collectReceiverTypes(body, params) {
+    const types = {};
+    for (const param of params) {
+        const id = firstNamedChild(param);
+        if (!id || id.type !== "identifier")
+            continue;
+        const typeAnnotation = (param.children ?? []).find((c) => c?.type === "type_annotation");
+        const typeId = typeAnnotation
+            ? firstChildOfType(typeAnnotation, "type_identifier")
+            : undefined;
+        if (typeId)
+            types[id.text] = typeId.text;
+    }
+    walk(body, (node) => {
+        if (node.type !== "variable_declarator")
+            return;
+        const id = firstChildOfType(node, "identifier");
+        if (!id)
+            return;
+        const value = (node.children ?? []).find((c) => c?.type === "new_expression");
+        if (!value)
+            return;
+        const ctor = firstNamedChild(value);
+        if (ctor?.type === "identifier")
+            types[id.text] = ctor.text;
+    });
+    return types;
+}
 function hasAwaitInNode(node) {
     let found = false;
     walk(node, (n) => {
@@ -192,6 +249,13 @@ export const functionFactProvider = {
     async run(ctx, store) {
         await extractFactsFromTree(ctx, store, { "file.functionSummaries": [] }, (root) => {
             const summaries = [];
+            // Class/interface declarations, collected in the SAME walk over the
+            // already-parsed tree (refs #655 phase 2) so owner/qualified-name
+            // computation for jsts needs no second parse — see
+            // `symbol-containment.ts`'s doc comment for why this can't literally
+            // share code with module-report.ts's tree-sitter-symbol-extractor path
+            // (different tree-sitter integration), only the same algorithm.
+            const containers = [];
             const addSummary = (node) => {
                 const body = getBody(node);
                 if (!body)
@@ -210,6 +274,7 @@ export const functionFactProvider = {
                     name: getFunctionName(node),
                     line: node.startPosition.row + 1,
                     column: node.startPosition.column + 1,
+                    endLine: body.endPosition.row + 1,
                     isAsync: Boolean(firstChildOfType(node, "async")),
                     hasAwait: hasAwaitInNode(body),
                     hasReturnAwaitCall: hasReturnAwaitCall(body),
@@ -221,12 +286,30 @@ export const functionFactProvider = {
                     cyclomaticComplexity: calcCyclomaticComplexity(body),
                     maxNestingDepth: calcMaxNestingDepth(body),
                     outgoingCalls: collectOutgoingCalls(body),
+                    memberCallSites: collectMemberCallSites(body),
+                    receiverTypes: collectReceiverTypes(body, params),
                 });
             };
             walk(root, (node) => {
                 if (FUNCTION_TYPES.has(node.type))
                     addSummary(node);
+                if (node.type === "class_declaration" ||
+                    node.type === "interface_declaration") {
+                    const nameNode = firstChildOfType(node, "type_identifier");
+                    if (nameNode) {
+                        containers.push({
+                            name: nameNode.text,
+                            startLine: node.startPosition.row + 1,
+                            endLine: node.endPosition.row + 1,
+                        });
+                    }
+                }
             });
+            for (const summary of summaries) {
+                const owner = findOwnerName(containers, summary.line, summary.endLine ?? summary.line);
+                if (owner)
+                    summary.owner = owner;
+            }
             return { "file.functionSummaries": summaries };
         });
     },

package/dist/clients/dispatch/integration.js

@@ -821,7 +821,13 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 coldSnapshotPaths.push(neighborPath);
                 continue;
             }
-            const diags = convertLspDiagnostics(entry.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath, { source: "cascade" });
+            // #692: `source: "cascade"` used to be passed here to label `rule`
+            // (`cascade:<code>`) — that override is gone (identity must come from
+            // the diagnostic's own source; see `scanOrigin`'s doc comment), and
+            // cascade neighbor diagnostics are ephemeral display-only output
+            // (never reconciled into persisted widget/dedup state), so the label
+            // had no remaining purpose and is simply dropped rather than migrated.
+            const diags = convertLspDiagnostics(entry.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath);
             producedLspData = true;
             const durationMs = Date.now() - neighborStart;
             logCascade({
@@ -994,7 +1000,11 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             });
             if (!rawDiags)
                 return undefined;
-            const diags = convertLspDiagnostics(rawDiags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath, { source: "cascade" });
+            // #692: `source: "cascade"` no longer overrides `rule` (see the
+            // doc comment on the sibling call above) — dropped rather than
+            // migrated to `scanOrigin` since cascade output never touches
+            // persisted widget/dedup state.
+            const diags = convertLspDiagnostics(rawDiags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath);
             const durationMs = Date.now() - neighborStart;
             // Update cache for this neighbor at the current write sequence
             if (writeSeq != null) {
@@ -1051,10 +1061,13 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                     error: String(result.reason),
                 });
                 const entry = allDiags.get(normalizeMapKey(neighborPath));
+                // #692: `source: "cascade"` dropped (see the doc comment above the
+                // first cascade call site in this file) — no longer affects `rule`
+                // and cascade output never touches persisted widget/dedup state.
                 const diags = entry && Date.now() - entry.ts < CASCADE_TTL_MS
                     ? convertLspDiagnostics(entry.diags
                         .filter((d) => d.severity === 1)
-                        .slice(0, MAX_PER_FILE), neighborPath, { source: "cascade" })
+                        .slice(0, MAX_PER_FILE), neighborPath)
                     : [];
                 neighbors.push({
                     filePath: neighborPath,
@@ -1162,7 +1175,9 @@ function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd) {
             continue;
         if (now - ts > CASCADE_TTL_MS)
             continue;
-        const errors = convertLspDiagnostics(diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), diagPath, { source: "cascade" });
+        // #692: `source: "cascade"` dropped — see the doc comment above the
+        // first cascade `convertLspDiagnostics` call site in this file.
+        const errors = convertLspDiagnostics(diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), diagPath);
         if (errors.length === 0)
             continue;
         neighbors.push({

package/dist/clients/dispatch/rules/async-noise.js

@@ -23,7 +23,7 @@ export const asyncNoiseRule = {
                 fn.statementCount > 1) {
                 diagnostics.push({
                     id: `async-noise:${ctx.filePath}:${fn.line}:${fn.column}`,
-                    tool: "async-noise",
+                    tool: "fact-rules",
                     filePath: ctx.filePath,
                     line: fn.line,
                     column: fn.column,

package/dist/clients/dispatch/rules/async-unnecessary-wrapper.js

@@ -12,7 +12,7 @@ export const asyncUnnecessaryWrapperRule = {
                 continue;
             diagnostics.push({
                 id: `async-unnecessary-wrapper:${ctx.filePath}:${f.line}`,
-                tool: "async-unnecessary-wrapper",
+                tool: "fact-rules",
                 rule: "async-unnecessary-wrapper",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/rules/cors-wildcard.js

@@ -38,7 +38,7 @@ export const corsWildcardRule = {
             if (isWildcard) {
                 diagnostics.push({
                     id: `cors-wildcard:${ctx.filePath}:${i + 1}`,
-                    tool: "cors-wildcard",
+                    tool: "fact-rules",
                     rule: "cors-wildcard",
                     filePath: ctx.filePath,
                     line: i + 1,

package/dist/clients/dispatch/rules/error-obscuring.js

@@ -16,7 +16,8 @@ export const errorObscuringRule = {
                 !s.bodyText.includes(s.catchParam)) {
                 diagnostics.push({
                     id: `error-obscuring:${ctx.filePath}:${s.line}:${s.column}`,
-                    tool: "error-obscuring",
+                    tool: "fact-rules",
+                    rule: "error-obscuring",
                     filePath: ctx.filePath,
                     line: s.line,
                     column: s.column,

package/dist/clients/dispatch/rules/error-swallowing.js

@@ -13,7 +13,8 @@ export const errorSwallowingRule = {
             if (s.isEmpty && !s.isDocumentedLocalFallback && s.boundaryCategory !== "fs") {
                 diagnostics.push({
                     id: `error-swallowing:${ctx.filePath}:${s.line}:${s.column}`,
-                    tool: "error-swallowing",
+                    tool: "fact-rules",
+                    rule: "error-swallowing",
                     filePath: ctx.filePath,
                     line: s.line,
                     column: s.column,

package/dist/clients/dispatch/rules/framework-call-noise.js

@@ -0,0 +1,67 @@
+/**
+ * Shared test-framework-call recognition for `high-fan-out` and `high-complexity`
+ * (#577). A normal `it()`/`describe()` body naturally invokes many assertion/mock
+ * helpers — that's test structure, not a coordination smell or genuine complexity.
+ *
+ * Two complementary heuristics, both call-name-based (no `ctx.fileRole` gating —
+ * these calls only exist in test-framework code, so the signal is safe to apply
+ * unconditionally):
+ *
+ * 1. `isTestFrameworkNoiseCall` — filters individual "meaningful calls" the same
+ *    way `console.*`/`Math.*`/etc. are already excluded in high-fan-out. Handles
+ *    assertion-heavy `it()` bodies directly.
+ * 2. `isTestSuiteOrganizer` — a `describe()`/`it()`/`test()` wrapper's own
+ *    FunctionSummary aggregates every call and branch from ALL of its nested test
+ *    bodies (the shared tree-sitter walk in function-facts.ts does not stop at
+ *    nested-function boundaries, since each nested callback also gets its own,
+ *    correctly-scoped, FunctionSummary). That aggregation is not real fan-out or
+ *    complexity — it's the sum of independent nested tests. A function is an
+ *    "organizer" if it directly invokes `it`/`test`/`describe` (or their
+ *    `.only`/`.skip`/`.each` variants) — i.e. it exists to group other tests, not
+ *    to implement logic itself. This does NOT exempt genuinely complex/tangled
+ *    test HELPER functions, since those don't call `it`/`describe`/`test`
+ *    themselves.
+ */
+const EXPECT_CHAIN_PREFIX = "expect(";
+const TEST_LIFECYCLE_NAMES = new Set([
+    "it",
+    "test",
+    "describe",
+    "beforeeach",
+    "aftereach",
+    "beforeall",
+    "afterall",
+]);
+const TEST_LIFECYCLE_PREFIXES = ["it.", "test.", "describe."];
+const MOCK_LIBRARY_PREFIXES = ["vi.", "jest."];
+/**
+ * True if `call` (a raw callee string from `FunctionSummary.outgoingCalls`) is
+ * test-framework noise: an `expect(...)` assertion chain, a test lifecycle call
+ * (`it`/`describe`/`test`/`beforeEach`/etc., including `.only`/`.skip`/`.each`
+ * variants), or a mock-library call (`vi.*`/`jest.*`).
+ */
+export function isTestFrameworkNoiseCall(call) {
+    const lower = call.toLowerCase();
+    if (lower === "expect" || lower.startsWith(EXPECT_CHAIN_PREFIX))
+        return true;
+    if (TEST_LIFECYCLE_NAMES.has(lower))
+        return true;
+    if (TEST_LIFECYCLE_PREFIXES.some((p) => lower.startsWith(p)))
+        return true;
+    if (MOCK_LIBRARY_PREFIXES.some((p) => lower.startsWith(p)))
+        return true;
+    return false;
+}
+/**
+ * True if this function's (unfiltered) outgoing calls include a direct call to
+ * `it`/`test`/`describe` — i.e. it groups nested test bodies rather than
+ * implementing logic itself. Its aggregated fan-out/complexity reflects the sum
+ * of independent nested tests, not one function's real signal.
+ */
+export function isTestSuiteOrganizer(calls) {
+    return calls.some((call) => {
+        const lower = call.toLowerCase();
+        const base = lower.split("(")[0].split(".")[0];
+        return base === "it" || base === "test" || base === "describe";
+    });
+}

package/dist/clients/dispatch/rules/high-complexity.js

@@ -1,3 +1,4 @@
+import { isTestSuiteOrganizer } from "./framework-call-noise.js";
 // Defaults match the historical hardcoded values so behavior is unchanged for
 // projects without a config. Project-specific overrides are read from the
 // per-dispatch context; these mutable fallbacks exist for tests/legacy direct
@@ -35,6 +36,16 @@ export const highComplexityRule = {
         const configuredCcThreshold = ctx.projectConfig?.rules["high-complexity"]?.threshold;
         const activeCcThreshold = configuredCcThreshold ?? ccThreshold;
         for (const f of fns) {
+            // A describe()/it()/test() wrapper's own complexity/nesting-depth
+            // aggregates branches from ALL of its nested test bodies (#577) — e.g. a
+            // `for` loop inside each of several `it()`s sums into the enclosing
+            // `describe()`'s cyclomatic complexity, even though no single test is
+            // complex. Unlike high-fan-out's call-name filter, there's no per-call
+            // signal to exclude for branch counting, so the equivalent fix here is to
+            // skip the organizer function itself. Genuinely complex test HELPER
+            // functions don't call it/describe/test themselves, so they're unaffected.
+            if (isTestSuiteOrganizer(f.outgoingCalls))
+                continue;
             const ccBreached = f.cyclomaticComplexity >= activeCcThreshold;
             const depthBreached = f.maxNestingDepth >= depthThreshold;
             if (!ccBreached && !depthBreached)
@@ -46,7 +57,7 @@ export const highComplexityRule = {
                 parts.push(`nesting depth ${f.maxNestingDepth}`);
             diagnostics.push({
                 id: `high-complexity:${ctx.filePath}:${f.line}`,
-                tool: "high-complexity",
+                tool: "fact-rules",
                 rule: "high-complexity",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/rules/high-fan-out.js

@@ -1,3 +1,4 @@
+import { isTestFrameworkNoiseCall, isTestSuiteOrganizer, } from "./framework-call-noise.js";
 // Default matches the historical hardcoded value so behavior is unchanged for
 // projects without a config. Project-specific overrides are read from the
 // per-dispatch context; this mutable fallback exists for tests/legacy direct
@@ -27,7 +28,16 @@ export const highFanOutRule = {
         const configuredFanOutThreshold = ctx.projectConfig?.rules["high-fan-out"]?.threshold;
         const activeFanOutThreshold = configuredFanOutThreshold ?? fanOutThreshold;
         for (const f of fns) {
-            // Filter out noise: utility calls, logging, type assertions
+            // A describe()/it()/test() wrapper's own call list aggregates every call
+            // from ALL of its nested test bodies (#577) — not real fan-out. Genuinely
+            // complex test HELPER functions don't call it/describe/test themselves, so
+            // they're unaffected.
+            if (isTestSuiteOrganizer(f.outgoingCalls))
+                continue;
+            // Filter out noise: utility calls, logging, type assertions, and
+            // test-framework calls (expect/it/describe/vi.*/jest.*, #577) — assertion-
+            // and mock-heavy test bodies naturally call many of these; that's test
+            // structure, not a coordination smell.
             const meaningful = f.outgoingCalls.filter((c) => {
                 const lower = c.toLowerCase();
                 return (!lower.startsWith("console.") &&
@@ -42,13 +52,14 @@ export const highFanOutRule = {
                     c !== "resolve" &&
                     c !== "reject" &&
                     c !== "next" &&
-                    c !== "done");
+                    c !== "done" &&
+                    !isTestFrameworkNoiseCall(c));
             });
             if (meaningful.length < activeFanOutThreshold)
                 continue;
             diagnostics.push({
                 id: `high-fan-out:${ctx.filePath}:${f.line}`,
-                tool: "high-fan-out",
+                tool: "fact-rules",
                 rule: "high-fan-out",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/rules/high-import-coupling.js

@@ -23,7 +23,7 @@ export const highImportCouplingRule = {
         return [
             {
                 id: `high-import-coupling:${ctx.filePath}:1:1`,
-                tool: "high-import-coupling",
+                tool: "fact-rules",
                 rule: "high-import-coupling",
                 filePath: ctx.filePath,
                 line: 1,

package/dist/clients/dispatch/rules/missing-error-propagation.js

@@ -46,7 +46,7 @@ export const missingErrorPropagationRule = {
                     continue;
                 diagnostics.push({
                     id: `missing-error-propagation:${ctx.filePath}:${c.line}`,
-                    tool: "missing-error-propagation",
+                    tool: "fact-rules",
                     rule: "missing-error-propagation",
                     filePath: ctx.filePath,
                     line: c.line,

package/dist/clients/dispatch/rules/no-commented-credentials.js

@@ -34,7 +34,7 @@ export const commentedCredentialsRule = {
                 if (p.test(line)) {
                     diagnostics.push({
                         id: `no-commented-credentials:${ctx.filePath}:${i + 1}`,
-                        tool: "no-commented-credentials",
+                        tool: "fact-rules",
                         rule: "no-commented-credentials",
                         filePath: ctx.filePath,
                         line: i + 1,

package/dist/clients/dispatch/rules/pass-through-wrappers.js

@@ -23,7 +23,7 @@ export const passThroughWrappersRule = {
                 continue;
             diagnostics.push({
                 id: `pass-through-wrapper:${ctx.filePath}:${fn.line}:${fn.column}`,
-                tool: "pass-through-wrappers",
+                tool: "fact-rules",
                 filePath: ctx.filePath,
                 line: fn.line,
                 column: fn.column,

package/dist/clients/dispatch/rules/placeholder-comments.js

@@ -25,7 +25,7 @@ export const placeholderCommentsRule = {
                 continue;
             diagnostics.push({
                 id: `placeholder-comments:${ctx.filePath}:${comment.line}:1`,
-                tool: "placeholder-comments",
+                tool: "fact-rules",
                 filePath: ctx.filePath,
                 line: comment.line,
                 column: 1,

package/dist/clients/dispatch/rules/unsafe-boundary.js

@@ -80,7 +80,7 @@ export const unsafeBoundaryRule = {
                 continue;
             diagnostics.push({
                 id: `unsafe-boundary:${ctx.filePath}:${f.line}`,
-                tool: "unsafe-boundary",
+                tool: "fact-rules",
                 rule: "unsafe-boundary",
                 filePath: ctx.filePath,
                 line: f.line,

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

@@ -38,14 +38,31 @@ const SUPPORTED_EXTS = [".ts", ".tsx", ".js", ".jsx", ".css", ".html", ".htm"];
 const MAX_MATCHES_PER_RULE = 10;
 /** Maximum total diagnostics per file to prevent output spam */
 const MAX_TOTAL_DIAGNOSTICS = 50;
-/** Rules already covered by tree-sitter runner (priority 14, runs first) */
-const TREE_SITTER_OVERLAP = new Set([
-    "constructor-super",
-    "empty-catch",
-    "long-parameter-list",
-    "nested-ternary",
-    "no-dupe-class-members",
-]);
+/**
+ * #660: this runner used to skip a hardcoded set of rule ids
+ * (`constructor-super`, `empty-catch`, `long-parameter-list`,
+ * `nested-ternary`, `no-dupe-class-members`) on the assumption that the
+ * tree-sitter query runner (priority 14) already covered them, to avoid
+ * double-reporting. That assumption was false for every entry: three of
+ * them (`nested-ternary`, `long-parameter-list`, `no-dupe-class-members`)
+ * have no active tree-sitter query — their would-be queries either live
+ * under `rules/tree-sitter-queries/typescript-disabled/` (excluded from
+ * loading, see clients/tree-sitter-query-loader.ts) or were never written —
+ * so those three rule ids had ZERO coverage in the NAPI fallback runner
+ * (used when the ast-grep binary isn't installed) despite having a
+ * perfectly good, shipped, active ast-grep rule sitting right there. The
+ * other two (`constructor-super`, `empty-catch`) are disabled everywhere
+ * (ast-grep AND tree-sitter, see rules-disabled/, #206), so skipping them
+ * was already a no-op. The whole skip-set has been removed; if tree-sitter
+ * coverage is ever added back for one of these rule ids, reintroduce a
+ * scoped skip alongside the query that actually covers it — don't recreate
+ * a blanket assumption-based list.
+ *
+ * Note: `no-dupe-class-members` didn't actually fire immediately
+ * post-removal — its rule YAML uses a top-level `utils:` block that this
+ * runner's native-config passthrough dropped entirely, a separate bug
+ * (affecting 5 shipped rules, not just this one) fixed in #663.
+ */
 /**
  * Rules commonly covered by ESLint/Biome correctness checks.
  * We can suppress these from ast-grep in lint-enabled projects to reduce noise.
@@ -103,6 +120,32 @@ function normalizeRuleId(ruleId) {
 export function canHandle(filePath) {
     return SUPPORTED_EXTS.includes(path.extname(filePath).toLowerCase());
 }
+/**
+ * The TypeScript grammar is a syntactic superset of JavaScript, so a
+ * `JavaScript`-tagged rule using generic node kinds (`variable_declarator`,
+ * `assignment_expression`, …) still matches against a parsed `.ts`/`.tsx`
+ * root — and vice versa isn't an issue since JS files never parse
+ * TS-only syntax, but a `TypeScript`-tagged rule with a plain-JS-compatible
+ * body would equally double-fire alongside a `JavaScript` twin on a `.ts`
+ * file. Without this, `language:` reads as a real filter but isn't one for
+ * ts↔js pairs, so twin rules sharing a base name (e.g. `hardcoded-url` /
+ * `hardcoded-url-js`) both match the same construct in the SAME runner
+ * invocation (#657). Returns undefined for extensions this scoping doesn't
+ * apply to (css/html), where no filtering is added.
+ */
+export function ruleLanguageForFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case ".ts":
+        case ".tsx":
+            return "typescript";
+        case ".js":
+        case ".jsx":
+            return "javascript";
+        default:
+            return undefined;
+    }
+}
 export function getLang(filePath, sgModule) {
     const ext = path.extname(filePath).toLowerCase();
     switch (ext) {
@@ -169,9 +212,11 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
     const maxMatchesPerRule = options.maxMatchesPerRule ?? MAX_MATCHES_PER_RULE;
     const maxTotalDiagnostics = options.maxTotalDiagnostics ?? MAX_TOTAL_DIAGNOSTICS;
     const blockingOnly = options.blockingOnly === true;
+    const log = options.log;
     const diagnostics = [];
     const seenRuleIds = new Set();
     const suppressLinterOverlap = kind === "jsts" && hasEslintConfig(cwd);
+    const fileLang = ruleLanguageForFile(filePath);
     // Shared with the raw sgconfig materializer so both surfaces walk the same
     // workspace-rooted sources in the same precedence order.
     const ruleSources = getAstGrepRuleSources(options.projectRoot ?? cwd);
@@ -205,9 +250,6 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 !NON_SUPPRESSIBLE.has(normalizeRuleId(rule.id))) {
                 continue;
             }
-            // Skip rules already handled by tree-sitter runner (priority 14)
-            if (TREE_SITTER_OVERLAP.has(rule.id))
-                continue;
             // Skip rules whose top-level pattern is overly broad ($NAME, $X, etc.)
             // without additional structural constraints to narrow matches.
             if (rule.rule &&
@@ -219,6 +261,12 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
             if (lang && lang !== "typescript" && lang !== "javascript") {
                 continue;
             }
+            // Scope TypeScript/JavaScript-tagged rules to the file's actual
+            // grammar (#657) — otherwise a `-js` twin sharing generic node
+            // kinds with its TS sibling double-fires on every .ts file.
+            if (lang && fileLang && lang !== fileLang) {
+                continue;
+            }
             if (blockingOnly && rule.rule) {
                 const complexity = calculateRuleComplexity(rule.rule);
                 if (complexity > MAX_BLOCKING_RULE_COMPLEXITY) {
@@ -232,18 +280,26 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 // 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
-                // `constraints` (#206). A faithful js-yaml parse feeds the rule
+                // `constraints` (#206) AND top-level `utils` — reusable named
+                // matchers referenced via `matches: <name>` inside `rule`
+                // (#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), skip it — never silently match nothing
-                // through a partial interpreter.
-                const nativeConfig = rule.constraints
-                    ? { rule: rule.rule, constraints: rule.constraints }
-                    : { rule: rule.rule };
+                // or invalid-kind rule, or an unresolved `matches:` reference),
+                // skip it — never silently match nothing through a partial
+                // interpreter.
+                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 {
+                catch (err) {
                     matches = [];
+                    log?.(`ast-grep-napi: rule "${rule.id}" rejected by native engine (${err instanceof Error ? err.message : String(err)})`);
                 }
                 const limitedMatches = matches.slice(0, maxMatchesPerRule);
                 for (const match of limitedMatches) {
@@ -355,6 +411,7 @@ const astGrepNapiRunner = {
         const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, {
             blockingOnly: ctx.blockingOnly,
             projectRoot: ctx.projectRoot,
+            log: (message) => ctx.log(message),
         });
         const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
         let semantic = "none";