@quolu/lattice 0.43.0 → 0.45.0

package/sensor/dist/resolution/name-matcher.js

@@ -18,9 +18,11 @@ exports.matchCppCallChain = matchCppCallChain;
 exports.matchScopedCallChain = matchScopedCallChain;
 exports.matchDottedCallChain = matchDottedCallChain;
 exports.normalizeInferredTypeName = normalizeInferredTypeName;
+exports.clearNameMatcherMemos = clearNameMatcherMemos;
 exports.localReceiverTypePatterns = localReceiverTypePatterns;
 exports.matchMethodCall = matchMethodCall;
 exports.matchFuzzy = matchFuzzy;
+exports.dumpNameMatcherProfile = dumpNameMatcherProfile;
 exports.matchReference = matchReference;
 /**
  * Ceiling on how many same-named definitions a FUZZY name-match strategy will
@@ -229,6 +231,15 @@ function matchFunctionRef(ref, context) {
         ref.language === 'arkts' ||
         ref.language === 'cpp' || ref.language === 'python' ||
         ref.language === 'php';
+    // Python additionally accepts CLASS targets for bare identifiers (#1478):
+    // class-as-value is a core Python idiom (`return SomeSerializer`,
+    // `Meta.model = Org`, registry dicts, `admin.site.register(Model, Admin)`)
+    // and, unlike TS, Python has no type-annotation recovery path. The
+    // false-positive mechanism behind the function-only rule was lowercase
+    // locals colliding with same-named METHODS (docopt.py) — a candidate must
+    // be an exact-name CLASS node here, and the extraction gate (same-file
+    // class ∪ imports) plus unique-or-drop still apply. Methods stay excluded.
+    const bareClassOk = ref.language === 'python';
     // Qualified member-pointer (`&Widget::on_click` → "Widget::on_click"):
     // resolve the member ON THAT SCOPE — exempt from bareFnOnly (the `&Cls::m`
     // shape is an explicit member reference). Unique-or-drop like everything else.
@@ -257,7 +268,9 @@ function matchFunctionRef(ref, context) {
     }
     let candidates = context
         .getNodesByName(ref.referenceName)
-        .filter((n) => (n.kind === 'function' || (!bareFnOnly && n.kind === 'method')) &&
+        .filter((n) => (n.kind === 'function' ||
+        (!bareFnOnly && n.kind === 'method') ||
+        (bareClassOk && n.kind === 'class')) &&
         sameLanguageFamily(n.language, ref.language) &&
         n.id !== ref.fromNodeId // a function registering itself is not a dependency edge
     );
@@ -546,11 +559,16 @@ depth = 0) {
         // populated in the conformance pass. Still VALIDATED (the method must exist on
         // a supertype), so a wrong inference produces no edge.
         if (depth < 4 && context.getSupertypes) {
-            for (const supertype of context.getSupertypes(typeName, ref.language)) {
-                const via = resolveMethodOnType(supertype, methodName, ref, context, confidence, resolvedBy, preferredFqn, depth + 1);
-                if (via)
-                    return via;
-            }
+            const viaSupers = nmTimedT('rmot-supers', ref, () => {
+                for (const supertype of context.getSupertypes(typeName, ref.language)) {
+                    const via = resolveMethodOnType(supertype, methodName, ref, context, confidence, resolvedBy, preferredFqn, depth + 1);
+                    if (via)
+                        return via;
+                }
+                return null;
+            });
+            if (viaSupers)
+                return viaSupers;
         }
         return null;
     }
@@ -1032,7 +1050,50 @@ function normalizeInferredTypeName(raw) {
  * PascalCase is required in the capture where the language convention allows,
  * as a cheap false-positive guard on top of resolveMethodOnType's validation.
  */
+/**
+ * Compiled-pattern memo for the receiver-type pattern builders below. They
+ * run for EVERY `receiver.method()` ref the matcher attempts, compiling 2–4
+ * fresh RegExp objects per call — and receivers repeat massively (`self`
+ * alone accounts for tens of thousands of refs on a Lua repo, measured 41µs
+ * per methodCall miss on kong with compilation a large slice). The patterns
+ * are a pure function of (language, receiver) and non-global (`.match()`
+ * never touches lastIndex), so shared instances are behavior-identical.
+ * FIFO-capped with no per-get mutation (the §7a.6 LRU-churn lesson): a hit
+ * costs one Map lookup, overflow evicts oldest, and an evicted entry simply
+ * recompiles exactly as every call did before this memo.
+ */
+const PATTERN_MEMO = new Map();
+const PATTERN_MEMO_CAP = 8192;
+const INFER_SCAN_STATES = new WeakMap();
+function getInferScanStates(context) {
+    let m = INFER_SCAN_STATES.get(context);
+    if (!m) {
+        m = new Map();
+        INFER_SCAN_STATES.set(context, m);
+    }
+    return m;
+}
+/** Drop the per-context scan states (see ReferenceResolver.clearCaches). */
+function clearNameMatcherMemos(context) {
+    INFER_SCAN_STATES.delete(context);
+}
+function memoPatterns(key, build) {
+    const hit = PATTERN_MEMO.get(key);
+    if (hit)
+        return hit;
+    const patterns = build();
+    if (PATTERN_MEMO.size >= PATTERN_MEMO_CAP) {
+        const oldest = PATTERN_MEMO.keys().next().value;
+        if (oldest !== undefined)
+            PATTERN_MEMO.delete(oldest);
+    }
+    PATTERN_MEMO.set(key, patterns);
+    return patterns;
+}
 function localReceiverTypePatterns(language, r) {
+    return memoPatterns(`${language}|${r}`, () => buildLocalReceiverTypePatterns(language, r));
+}
+function buildLocalReceiverTypePatterns(language, r) {
     switch (language) {
         case 'typescript':
         case 'javascript':
@@ -1275,6 +1336,53 @@ function inferLocalReceiverType(receiverName, ref, context) {
         }
         return null;
     };
+    // Incremental-scan memo (INFER_SCAN_STATES): this scan runs for EVERY
+    // `receiver.method()` ref and was measured at 61µs/ref on kong (2.4s of
+    // worker time, 99% misses — `self:` calls hunting a declaration Lua never
+    // writes). Refs for the same (file, scope, receiver) arrive in ~ascending
+    // line order, and the scan is a pure function of the file's immutable
+    // lines, so each line pays its regex matches ONCE per key instead of once
+    // per ref: query(c) = highest matching line in [startIdx..c]; a monotonic
+    // call extends the stored watermark by scanning only (hi..c] (the region
+    // at-or-below the previous answer is already proven empty above it); a
+    // non-monotonic call (rare — refs are rowid-ordered) falls back to the
+    // plain bounded scan and leaves the state alone. componentScoped is keyed
+    // out — its position-independent whole-file sweep below has different
+    // semantics.
+    if (!componentScoped) {
+        const states = getInferScanStates(context);
+        const key = `${ref.filePath}|${startIdx}|${ref.language}|${scanReceiver}`;
+        const state = states.get(key);
+        if (!state) {
+            for (let i = callIdx; i >= startIdx; i--) {
+                const type = matchLine(i);
+                if (type) {
+                    states.set(key, { hi: callIdx, ansIdx: i, ansType: type });
+                    return type;
+                }
+            }
+            states.set(key, { hi: callIdx, ansIdx: -1, ansType: null });
+            return null;
+        }
+        if (callIdx >= state.hi) {
+            for (let i = callIdx; i > state.hi; i--) {
+                const type = matchLine(i);
+                if (type) {
+                    state.ansIdx = i;
+                    state.ansType = type;
+                    break;
+                }
+            }
+            state.hi = callIdx;
+            return state.ansIdx >= startIdx ? state.ansType : null;
+        }
+        for (let i = callIdx; i >= startIdx; i--) {
+            const type = matchLine(i);
+            if (type)
+                return type;
+        }
+        return null;
+    }
     // Nearest declaration wins: scan backward from the call to the scope start.
     for (let i = callIdx; i >= startIdx; i--) {
         const type = matchLine(i);
@@ -1317,6 +1425,9 @@ function inferLocalReceiverType(receiverName, ref, context) {
  * shape is handled by inferPhpAssignedPropertyType instead.
  */
 function phpPropertyTypePatterns(r) {
+    return memoPatterns(`php-prop|${r}`, () => buildPhpPropertyTypePatterns(r));
+}
+function buildPhpPropertyTypePatterns(r) {
     return [
         new RegExp(`\\b(?:(?:private|protected|public|readonly|static|final)(?:\\(set\\))?\\s+)+\\??([A-Za-z_\\\\][\\w\\\\]*)\\s+&?\\$${r}\\b`), // private readonly ?Foo $prop  (typed property / promoted param)
         new RegExp(`\\$this->${r}\\b\\s*=\\s*new\\s+([A-Za-z_\\\\][\\w\\\\]*)`), // $this->prop = new Foo()
@@ -1450,9 +1561,9 @@ function matchMethodCall(ref, context) {
     // shared source-based inferrer. resolveMethodOnType validates the method
     // exists on the inferred type, so a mis-inference produces no edge.
     if (inferableReceiver) {
-        const inferredType = ref.language === 'cpp'
+        const inferredType = nmTimedT('mc-infer', ref, () => ref.language === 'cpp'
             ? inferCppReceiverType(objectOrClass, ref, context)
-            : inferLocalReceiverType(objectOrClass, ref, context);
+            : inferLocalReceiverType(objectOrClass, ref, context));
         if (inferredType) {
             // Java/Kotlin: when two classes share the simple name, the file's import
             // pins WHICH one (#314). Other languages disambiguate by call-site file.
@@ -1461,7 +1572,7 @@ function matchMethodCall(ref, context) {
                     .getImportMappings(ref.filePath, ref.language)
                     .find((i) => i.localName === inferredType)?.source
                 : undefined;
-            const typedMatch = resolveMethodOnType(inferredType, methodName, ref, context, 0.9, 'instance-method', importedFqn);
+            const typedMatch = nmTimedT('mc-rmot', ref, () => resolveMethodOnType(inferredType, methodName, ref, context, 0.9, 'instance-method', importedFqn));
             if (typedMatch) {
                 return typedMatch;
             }
@@ -1494,7 +1605,7 @@ function matchMethodCall(ref, context) {
             // imported FQN so resolveMethodOnType can disambiguate (#314).
             const imports = context.getImportMappings(ref.filePath, ref.language);
             const importedFqn = imports.find((i) => i.localName === inferredType)?.source;
-            const typedMatch = resolveMethodOnType(inferredType, methodName, ref, context, 0.9, 'instance-method', importedFqn);
+            const typedMatch = nmTimedT('mc-rmot', ref, () => resolveMethodOnType(inferredType, methodName, ref, context, 0.9, 'instance-method', importedFqn));
             if (typedMatch) {
                 return typedMatch;
             }
@@ -1505,32 +1616,9 @@ function matchMethodCall(ref, context) {
     // with a `Logger` in both `a/` and `b/`), try the class in the call site's
     // own file first — otherwise the first-indexed class wins and a call in `b/`
     // resolves to `a/`'s method (#1079).
-    const classCandidates = preferCallSiteFile(context.getNodesByName(objectOrClass), ref.filePath);
-    for (const classNode of classCandidates) {
-        if (classNode.kind === 'class' || classNode.kind === 'struct' || classNode.kind === 'interface') {
-            // Skip cross-language class matches
-            if (classNode.language !== ref.language)
-                continue;
-            const nodesInFile = context.getNodesInFile(classNode.filePath);
-            const methodNode = nodesInFile.find((n) => n.kind === 'method' &&
-                n.name === methodName &&
-                n.qualifiedName.includes(classNode.name));
-            if (methodNode) {
-                return {
-                    original: ref,
-                    targetNodeId: methodNode.id,
-                    confidence: 0.85,
-                    resolvedBy: 'qualified-name',
-                };
-            }
-        }
-    }
-    // Strategy 2: Instance variable receiver - try capitalized form to find class
-    // e.g., "permissionEngine" → look for classes containing "PermissionEngine"
-    const capitalizedReceiver = objectOrClass.charAt(0).toUpperCase() + objectOrClass.slice(1);
-    if (capitalizedReceiver !== objectOrClass) {
-        const fuzzyClassCandidates = preferCallSiteFile(context.getNodesByName(capitalizedReceiver), ref.filePath);
-        for (const classNode of fuzzyClassCandidates) {
+    const strat1 = nmTimedT('mc-class', ref, () => {
+        const classCandidates = preferCallSiteFile(context.getNodesByName(objectOrClass), ref.filePath);
+        for (const classNode of classCandidates) {
             if (classNode.kind === 'class' || classNode.kind === 'struct' || classNode.kind === 'interface') {
                 // Skip cross-language class matches
                 if (classNode.language !== ref.language)
@@ -1543,68 +1631,106 @@ function matchMethodCall(ref, context) {
                     return {
                         original: ref,
                         targetNodeId: methodNode.id,
-                        confidence: 0.8,
-                        resolvedBy: 'instance-method',
+                        confidence: 0.85,
+                        resolvedBy: 'qualified-name',
                     };
                 }
             }
         }
+        return null;
+    });
+    if (strat1)
+        return strat1;
+    // Strategy 2: Instance variable receiver - try capitalized form to find class
+    // e.g., "permissionEngine" → look for classes containing "PermissionEngine"
+    const capitalizedReceiver = objectOrClass.charAt(0).toUpperCase() + objectOrClass.slice(1);
+    if (capitalizedReceiver !== objectOrClass) {
+        const strat2 = nmTimedT('mc-capital', ref, () => {
+            const fuzzyClassCandidates = preferCallSiteFile(context.getNodesByName(capitalizedReceiver), ref.filePath);
+            for (const classNode of fuzzyClassCandidates) {
+                if (classNode.kind === 'class' || classNode.kind === 'struct' || classNode.kind === 'interface') {
+                    // Skip cross-language class matches
+                    if (classNode.language !== ref.language)
+                        continue;
+                    const nodesInFile = context.getNodesInFile(classNode.filePath);
+                    const methodNode = nodesInFile.find((n) => n.kind === 'method' &&
+                        n.name === methodName &&
+                        n.qualifiedName.includes(classNode.name));
+                    if (methodNode) {
+                        return {
+                            original: ref,
+                            targetNodeId: methodNode.id,
+                            confidence: 0.8,
+                            resolvedBy: 'instance-method',
+                        };
+                    }
+                }
+            }
+            return null;
+        });
+        if (strat2)
+            return strat2;
     }
     // Strategy 3: Find methods by name across the codebase, match by receiver
     // name similarity with the containing class. Handles abbreviated variable
     // names like permissionEngine → PermissionRuleEngine.
     if (methodName) {
-        const methodCandidates = context.getNodesByName(methodName);
-        // Ubiquitous-method ceiling (#999): a method name re-declared across a
-        // vendored theme/SDK (Metronic's `init`/`update`/… on every widget) yields
-        // K candidates that receiver-word overlap can't reliably disambiguate —
-        // and filtering + scoring all K per call is the O(K²) cost that wedged
-        // "Resolving refs" for 15-28 min. Bail before the O(K) work; Strategy 1/2
-        // (class-name match) already had their precise shot above.
-        if (methodCandidates.length > AMBIGUOUS_NAME_CEILING) {
-            return null;
-        }
-        const methods = methodCandidates.filter((n) => n.kind === 'method' && n.name === methodName);
-        // Filter to same-language candidates first
-        const sameLanguageMethods = methods.filter(m => m.language === ref.language);
-        const targetMethods = sameLanguageMethods.length > 0 ? sameLanguageMethods : methods;
-        // If only one same-language method with this name exists, use it
-        if (targetMethods.length === 1 && targetMethods[0].language === ref.language) {
-            return {
-                original: ref,
-                targetNodeId: targetMethods[0].id,
-                confidence: 0.7,
-                resolvedBy: 'instance-method',
-            };
-        }
-        // Multiple methods: score by receiver name word overlap with class name
-        if (targetMethods.length > 1) {
-            const receiverWords = splitCamelCase(objectOrClass);
-            let bestMatch;
-            let bestScore = 0;
-            // Same-file candidates first, so a score tie (`score > bestScore` keeps
-            // the first seen) resolves to the call site's own file rather than the
-            // first-indexed duplicate (#1079).
-            for (const method of preferCallSiteFile(targetMethods, ref.filePath)) {
-                const classWords = splitCamelCase(method.qualifiedName);
-                let score = receiverWords.filter(w => classWords.some(cw => cw.toLowerCase() === w.toLowerCase())).length;
-                // Bonus for same language
-                if (method.language === ref.language)
-                    score += 1;
-                if (score > bestScore) {
-                    bestScore = score;
-                    bestMatch = method;
-                }
+        const strat3 = nmTimedT('mc-byname', ref, () => {
+            const methodCandidates = context.getNodesByName(methodName);
+            // Ubiquitous-method ceiling (#999): a method name re-declared across a
+            // vendored theme/SDK (Metronic's `init`/`update`/… on every widget) yields
+            // K candidates that receiver-word overlap can't reliably disambiguate —
+            // and filtering + scoring all K per call is the O(K²) cost that wedged
+            // "Resolving refs" for 15-28 min. Bail before the O(K) work; Strategy 1/2
+            // (class-name match) already had their precise shot above.
+            if (methodCandidates.length > AMBIGUOUS_NAME_CEILING) {
+                return null;
             }
-            if (bestMatch && bestScore >= 2) {
+            const methods = methodCandidates.filter((n) => n.kind === 'method' && n.name === methodName);
+            // Filter to same-language candidates first
+            const sameLanguageMethods = methods.filter(m => m.language === ref.language);
+            const targetMethods = sameLanguageMethods.length > 0 ? sameLanguageMethods : methods;
+            // If only one same-language method with this name exists, use it
+            if (targetMethods.length === 1 && targetMethods[0].language === ref.language) {
                 return {
                     original: ref,
-                    targetNodeId: bestMatch.id,
-                    confidence: 0.65,
+                    targetNodeId: targetMethods[0].id,
+                    confidence: 0.7,
                     resolvedBy: 'instance-method',
                 };
             }
-        }
+            // Multiple methods: score by receiver name word overlap with class name
+            if (targetMethods.length > 1) {
+                const receiverWords = splitCamelCase(objectOrClass);
+                let bestMatch;
+                let bestScore = 0;
+                // Same-file candidates first, so a score tie (`score > bestScore` keeps
+                // the first seen) resolves to the call site's own file rather than the
+                // first-indexed duplicate (#1079).
+                for (const method of preferCallSiteFile(targetMethods, ref.filePath)) {
+                    const classWords = splitCamelCase(method.qualifiedName);
+                    let score = receiverWords.filter(w => classWords.some(cw => cw.toLowerCase() === w.toLowerCase())).length;
+                    // Bonus for same language
+                    if (method.language === ref.language)
+                        score += 1;
+                    if (score > bestScore) {
+                        bestScore = score;
+                        bestMatch = method;
+                    }
+                }
+                if (bestMatch && bestScore >= 2) {
+                    return {
+                        original: ref,
+                        targetNodeId: bestMatch.id,
+                        confidence: 0.65,
+                        resolvedBy: 'instance-method',
+                    };
+                }
+            }
+            return null;
+        });
+        if (strat3)
+            return strat3;
     }
     return null;
 }
@@ -1846,6 +1972,45 @@ function matchFuzzy(ref, context) {
  */
 /** ArkUI attribute-helper decorators a `.attr(...)` chain may resolve to. */
 const ARKUI_ATTRIBUTE_DECORATORS = new Set(['Extend', 'Styles', 'AnimatableExtend', 'Builder']);
+/**
+ * LATTICE_SENSOR_RESOLVE_PROFILE=2 sub-stage attribution for matchReference's
+ * strategy pipeline (`nm:<stage>|<refKind>|hit/miss`). Module-global because
+ * the matcher is a free function; each thread (main + every pool worker) has
+ * its own module instance, and dumpNameMatcherProfile is invoked from
+ * ReferenceResolver.dumpResolveProfile so worker tables surface too.
+ */
+const NM_PROFILE = process.env.LATTICE_SENSOR_RESOLVE_PROFILE === '2' ? new Map() : null;
+function nmTimedT(stage, ref, fn) {
+    if (!NM_PROFILE)
+        return fn();
+    const t0 = process.hrtime.bigint();
+    const r = fn();
+    const dt = process.hrtime.bigint() - t0;
+    const key = `nm:${stage}|${ref.referenceKind}|${r ? 'hit' : 'miss'}`;
+    const slot = NM_PROFILE.get(key);
+    if (slot) {
+        slot.n++;
+        slot.ns += dt;
+    }
+    else {
+        NM_PROFILE.set(key, { n: 1, ns: dt });
+    }
+    return r;
+}
+function nmTimed(stage, ref, fn) {
+    return nmTimedT(stage, ref, fn);
+}
+/** Dump this thread's matchReference sub-stage table to stderr (no-op unless =2). */
+function dumpNameMatcherProfile(label) {
+    if (!NM_PROFILE || NM_PROFILE.size === 0)
+        return;
+    const rows = [...NM_PROFILE.entries()]
+        .map(([k, v]) => ({ k, n: v.n, ms: Number(v.ns / 1000000n) }))
+        .sort((a, b) => b.ms - a.ms);
+    for (const r of rows) {
+        console.error(`[resolve-profile] ${label} ${r.k}: n=${r.n} total=${(r.ms / 1000).toFixed(1)}s avg=${((r.ms * 1000) / Math.max(1, r.n)).toFixed(0)}µs`);
+    }
+}
 function matchReference(ref, context) {
     // Function-as-value refs (#756) resolve ONLY through the dedicated matcher —
     // never the fuzzy/qualified fallthrough below (a wrong callback edge is
@@ -1907,18 +2072,18 @@ function matchReference(ref, context) {
     // Try strategies in order of confidence
     let result;
     // 0. File path match (e.g., "snippets/drawer-menu.liquid" → file node)
-    result = matchByFilePath(ref, context);
+    result = nmTimed('filePath', ref, () => matchByFilePath(ref, context));
     if (result)
         return result;
     // 1. Qualified name match (highest confidence)
-    result = matchByQualifiedName(ref, context);
+    result = nmTimed('qualifiedName', ref, () => matchByQualifiedName(ref, context));
     if (result)
         return result;
     // 1b. C++ chained call whose receiver is another call — `Foo::instance().bar()`
     // encoded as `Foo::instance().bar` by the extractor (#645). Resolve the
     // receiver's type from what the inner call returns, then the method on it.
     if (ref.language === 'cpp' || ref.language === 'c') {
-        result = matchCppCallChain(ref, context);
+        result = nmTimed('cppChain', ref, () => matchCppCallChain(ref, context));
         if (result)
             return result;
     }
@@ -1927,7 +2092,7 @@ function matchReference(ref, context) {
     // type is the factory's `self` (PHP `: self`/`: static`, Rust `-> Self`) or
     // concrete return type.
     if (ref.language === 'php' || ref.language === 'rust') {
-        result = matchScopedCallChain(ref, context);
+        result = nmTimed('scopedChain', ref, () => matchScopedCallChain(ref, context));
         if (result)
             return result;
     }
@@ -1947,20 +2112,20 @@ function matchReference(ref, context) {
         ref.language === 'dart' ||
         ref.language === 'objc' ||
         ref.language === 'pascal') {
-        result = matchDottedCallChain(ref, context);
+        result = nmTimed('dottedChain', ref, () => matchDottedCallChain(ref, context));
         if (result)
             return result;
     }
     // 2. Method call pattern
-    result = matchMethodCall(ref, context);
+    result = nmTimed('methodCall', ref, () => matchMethodCall(ref, context));
     if (result)
         return result;
     // 3. Exact name match
-    result = matchByExactName(ref, context);
+    result = nmTimed('exactName', ref, () => matchByExactName(ref, context));
     if (result)
         return result;
     // 4. Fuzzy match (lowest confidence)
-    result = matchFuzzy(ref, context);
+    result = nmTimed('fuzzy', ref, () => matchFuzzy(ref, context));
     if (result)
         return result;
     return null;