@colbymchenry/codegraph-darwin-arm64 1.2.0 → 1.3.1

package/lib/dist/resolution/index.js

@@ -240,6 +240,17 @@ class ReferenceResolver {
     nameCache; // name → nodes cache
     lowerNameCache; // lower(name) → nodes cache
     qualifiedNameCache; // qualified_name → nodes cache
+    fileLinesCache; // file → split lines cache
+    methodMatchCache; // lang\0Type::method → matching method nodes
+    // Node kinds are a small fixed set (~24), so this is a plain Map, not an LRU.
+    // getNodesByKind returns the FULL node list for a kind; it was previously
+    // uncached — a per-ref `SELECT * FROM nodes WHERE kind=?` + row-mapping. Called
+    // for every dotted call ref by the Spring resolver (constants) and every
+    // `hook_` ref by the Drupal resolver (functions), that scan dominated
+    // resolution on large repos (#1180). The node set is stable within a
+    // resolution pass (same lifetime assumption as nameCache); clearCaches() resets
+    // it between passes. Callers must treat the returned array as read-only.
+    nodesByKindCache = new Map();
     knownNames = null; // all known symbol names for fast pre-filtering
     knownFiles = null;
     cachesWarmed = false;
@@ -265,6 +276,10 @@ class ReferenceResolver {
         this.nameCache = new lru_cache_1.LRUCache(limit);
         this.lowerNameCache = new lru_cache_1.LRUCache(limit);
         this.qualifiedNameCache = new lru_cache_1.LRUCache(limit);
+        // Split-lines arrays are heavier than content strings; refs arrive
+        // file-ordered, so a small cache still hits nearly always.
+        this.fileLinesCache = new lru_cache_1.LRUCache(contentLimit);
+        this.methodMatchCache = new lru_cache_1.LRUCache(limit);
         this.context = this.createContext();
     }
     /**
@@ -320,6 +335,28 @@ class ReferenceResolver {
         this.knownNames = new Set(this.queries.getAllNodeNames());
         this.cachesWarmed = true;
     }
+    /**
+     * warmCaches for the async resolution entry points: streams the distinct
+     * name set with periodic yields instead of one synchronous `.all()`. On a
+     * multi-million-node index the DISTINCT scan is a solid multi-second block
+     * (measured up to 28s inside `codegraph sync` on the Linux kernel index),
+     * long enough to matter to the #850 watchdog on slower hardware. Same
+     * result, same memory — only the event loop keeps turning.
+     */
+    async warmCachesYielding(onYield) {
+        if (this.cachesWarmed)
+            return;
+        this.knownFiles = new Set(this.queries.getAllFilePaths());
+        const names = new Set();
+        let scanned = 0;
+        for (const name of this.queries.iterateNodeNames()) {
+            names.add(name);
+            if ((++scanned & 8191) === 0)
+                await onYield();
+        }
+        this.knownNames = names;
+        this.cachesWarmed = true;
+    }
     /**
      * Clear internal caches
      */
@@ -331,10 +368,30 @@ class ReferenceResolver {
         this.nameCache.clear();
         this.lowerNameCache.clear();
         this.qualifiedNameCache.clear();
+        this.fileLinesCache.clear();
+        this.methodMatchCache.clear();
+        this.nodesByKindCache.clear();
         this.knownNames = null;
         this.knownFiles = null;
         this.cachesWarmed = false;
     }
+    /** `readFile` through the LRU content cache (null = read failed, also cached). */
+    readFileCached(filePath) {
+        if (this.fileCache.has(filePath)) {
+            return this.fileCache.get(filePath);
+        }
+        const fullPath = path.join(this.projectRoot, filePath);
+        try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            this.fileCache.set(filePath, content);
+            return content;
+        }
+        catch (error) {
+            (0, errors_1.logDebug)('Failed to read file for resolution', { filePath, error: String(error) });
+            this.fileCache.set(filePath, null);
+            return null;
+        }
+    }
     /**
      * Create the resolution context
      */
@@ -354,6 +411,30 @@ class ReferenceResolver {
                 this.nameCache.set(name, result);
                 return result;
             },
+            getMethodMatches: (typeName, methodName, language) => {
+                const key = `${language} ${typeName}::${methodName}`;
+                const cached = this.methodMatchCache.get(key);
+                if (cached !== undefined)
+                    return cached;
+                let candidates = this.nameCache.get(methodName);
+                if (candidates === undefined) {
+                    candidates = this.queries.getNodesByName(methodName);
+                    this.nameCache.set(methodName, candidates);
+                }
+                const want = `${typeName}::${methodName}`;
+                const matches = [];
+                for (const m of candidates) {
+                    if (m.kind !== 'method')
+                        continue;
+                    if (m.language !== language)
+                        continue;
+                    const qn = m.qualifiedName;
+                    if (qn === want || qn.endsWith(`::${want}`))
+                        matches.push(m);
+                }
+                this.methodMatchCache.set(key, matches);
+                return matches;
+            },
             getNodesByQualifiedName: (qualifiedName) => {
                 const cached = this.qualifiedNameCache.get(qualifiedName);
                 if (cached !== undefined)
@@ -363,8 +444,18 @@ class ReferenceResolver {
                 return result;
             },
             getNodesByKind: (kind) => {
-                return this.queries.getNodesByKind(kind);
+                const cached = this.nodesByKindCache.get(kind);
+                if (cached !== undefined)
+                    return cached;
+                const result = this.queries.getNodesByKind(kind);
+                this.nodesByKindCache.set(kind, result);
+                return result;
             },
+            // Streamed, uncached — synthesizers scan-and-filter whole kinds, and
+            // both the materialized array AND the per-kind cache retention are
+            // O(nodes) memory (#1212). Per-ref resolvers keep the cached array
+            // variant above.
+            iterateNodesByKind: (kind) => this.queries.iterateNodesByKind(kind),
             fileExists: (filePath) => {
                 // Check pre-built known files set first (O(1))
                 if (this.knownFiles) {
@@ -383,21 +474,15 @@ class ReferenceResolver {
                     return false;
                 }
             },
-            readFile: (filePath) => {
-                if (this.fileCache.has(filePath)) {
-                    return this.fileCache.get(filePath);
-                }
-                const fullPath = path.join(this.projectRoot, filePath);
-                try {
-                    const content = fs.readFileSync(fullPath, 'utf-8');
-                    this.fileCache.set(filePath, content);
-                    return content;
-                }
-                catch (error) {
-                    (0, errors_1.logDebug)('Failed to read file for resolution', { filePath, error: String(error) });
-                    this.fileCache.set(filePath, null);
-                    return null;
-                }
+            readFile: (filePath) => this.readFileCached(filePath),
+            getFileLines: (filePath) => {
+                const cached = this.fileLinesCache.get(filePath);
+                if (cached !== undefined)
+                    return cached;
+                const source = this.readFileCached(filePath);
+                const lines = source === null ? null : source.split(/\r?\n/);
+                this.fileLinesCache.set(filePath, lines);
+                return lines;
             },
             getProjectRoot: () => this.projectRoot,
             getAllFiles: () => {
@@ -500,7 +585,7 @@ class ReferenceResolver {
                 // `.ts` index barrel and silently break the chain (#629). Re-key
                 // the parse on the barrel's extension so the chase works no matter
                 // what kind of file imports through it.
-                const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?)$/i.test(filePath);
+                const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?|ets)$/i.test(filePath);
                 const reExports = (0, import_resolver_1.extractReExports)(content, isJsFamily ? 'typescript' : language);
                 this.reExportCache.set(filePath, reExports);
                 return reExports;
@@ -667,13 +752,36 @@ class ReferenceResolver {
         if (this.isBuiltInOrExternal(ref)) {
             return null;
         }
+        // CFML component paths in inheritance (#1152): `extends="coldbox.system.web.
+        // Controller"` names the supertype by its dot-separated path (or `extends=
+        // "../base"` by relative file path) — the graph indexes the class under its
+        // final segment only, so these die at the fast pre-filter below and never
+        // resolved. Handled by a dedicated path-corroborated matcher, gated to
+        // inheritance refs only (a dotted `calls` ref is a member-access chain, not
+        // a component path). No fallthrough on miss: the full path string can only
+        // ever mis-match downstream, and an unresolvable supertype usually lives in
+        // an out-of-repo library (mxunit, testbox) — silent beats wrong.
+        if ((ref.language === 'cfml' || ref.language === 'cfscript') &&
+            (ref.referenceKind === 'extends' || ref.referenceKind === 'implements') &&
+            (ref.referenceName.includes('.') || ref.referenceName.includes('/'))) {
+            return this.resolveCfmlComponentPath(ref);
+        }
         // Fast pre-filter: skip if no symbol with this name exists anywhere
         // AND the name doesn't match a local import. The import escape is
         // necessary because re-export rename chains (`import { login }
         // from './barrel'` where the barrel has `export { signIn as login }
         // from './auth'`) intentionally call a name that has no
         // declaration anywhere — only the renamed upstream symbol does.
-        if (!this.hasAnyPossibleMatch(ref.referenceName) &&
+        // ArkTS chained-attribute refs carry a leading dot (`.titleStyle`) that
+        // routes them to the decorator-gated matcher; the symbol itself is
+        // indexed under the bare name, so the existence check strips the dot.
+        // Nix static path imports (`import ./x.nix`) name a FILE, not a symbol —
+        // they bypass the symbol-existence check and resolve via resolveViaImport.
+        const existenceName = ref.language === 'arkts' && ref.referenceName.startsWith('.')
+            ? ref.referenceName.slice(1)
+            : ref.referenceName;
+        if (!(0, import_resolver_1.isNixPathImportRef)(ref) &&
+            !this.hasAnyPossibleMatch(existenceName) &&
             !this.matchesAnyImport(ref) &&
             !this.frameworks.some((f) => f.claimsReference?.(ref.referenceName))) {
             return null;
@@ -739,13 +847,40 @@ class ReferenceResolver {
         // If that didn't find the file, do NOT fall back to the symbol
         // name-matcher — it would mis-connect e.g. "inc/db.php" to an unrelated
         // db.php elsewhere in the tree (a wrong edge is worse than none, #660).
-        if ((0, import_resolver_1.isPhpIncludePathRef)(ref)) {
+        // Terraform refs are directory-scoped by language semantics — the
+        // framework resolver IS the whole rulebook (`var.X` can never legally
+        // bind outside its module directory), so the name-matcher's
+        // qualified-name fallback would only ever add wrong cross-module edges.
+        // Nix static path imports are file references for the same reason —
+        // falling through would let "./x.nix" name-match an unrelated node.
+        if ((0, import_resolver_1.isPhpIncludePathRef)(ref) || (0, import_resolver_1.isCobolCopybookRef)(ref) || (0, import_resolver_1.isNixPathImportRef)(ref) || ref.language === 'terraform') {
             return candidates.length > 0
                 ? candidates.reduce((best, curr) => curr.confidence > best.confidence ? curr : best)
                 : null;
         }
         // Strategy 3: Try name matching
-        const nameResult = this.gateLanguage((0, name_matcher_1.matchReference)(ref, this.context), ref);
+        let nameResult = this.gateLanguage((0, name_matcher_1.matchReference)(ref, this.context), ref);
+        // Nix has no ambient cross-file namespace — a callee binds lexically
+        // (same file) or through explicit import/callPackage wiring (the import
+        // path above). A cross-file name match is wrong by construction: every
+        // module `inherit (lib) mkOption`s the same nixpkgs helpers, so the
+        // matcher would link each `mkOption` call to whichever file's inherit
+        // binding it happened to pick. Same-file matches only.
+        if (nameResult) {
+            const target = this.queries.getNodeById(nameResult.targetNodeId);
+            if (ref.language === 'nix') {
+                if (!target || target.filePath !== ref.filePath) {
+                    nameResult = null;
+                }
+            }
+            else if (target && target.language === 'nix') {
+                // The reverse direction is just as impossible: no other language can
+                // symbolically call into a .nix binding (interop is eval/CLI, never a
+                // linkable symbol) — without this, a Python script's `split()` lands
+                // on some module's `split = ...` binding as a low-confidence match.
+                nameResult = null;
+            }
+        }
         if (nameResult) {
             candidates.push(nameResult);
         }
@@ -832,6 +967,20 @@ class ReferenceResolver {
                 referenceKind: r.original.referenceKind,
             })));
         }
+        // Delete unresolvable refs too — parity with resolveAndPersistBatched.
+        // Keeping them bought nothing: a ref is only ever retried when its file
+        // is re-extracted, which cascade-deletes and re-inserts its rows anyway.
+        // And it broke the #1187 orphan sweep's invariant — after a COMPLETED
+        // pass the table must hold nothing that pass processed, so that any row
+        // still present belongs to an interrupted run and the sweep can key off
+        // a bare row count.
+        if (result.unresolved.length > 0) {
+            this.queries.deleteSpecificResolvedReferences(result.unresolved.map((r) => ({
+                fromNodeId: r.fromNodeId,
+                referenceName: r.referenceName,
+                referenceKind: r.referenceKind,
+            })));
+        }
         return result;
     }
     /**
@@ -882,37 +1031,53 @@ class ReferenceResolver {
         return edges.length;
     }
     /**
-     * Resolve one batch in smaller sub-chunks, yielding to the event loop between
-     * them so the #850 liveness heartbeat can fire on a slow/dense batch (#1091).
-     * Behaviourally identical to a single `resolveAll(batch)`: `warmCaches()` is
-     * idempotent (guarded) and `resolveOne` is independent per ref, so splitting
-     * and re-merging changes only timing, never which edges get created. Falls
-     * through to a plain `resolveAll` when the batch is already small.
+     * Resolve one batch with a yield checkpoint between EVERY ref so the #850
+     * liveness heartbeat can fire on a slow/dense batch (#1091). The checkpoint
+     * granularity is per-ref — not per-N-refs — because per-ref cost is unbounded
+     * in the worst case (a collision-heavy method name whose candidate set misses
+     * the LRU re-fetches tens of thousands of rows): any fixed N multiplies that
+     * worst case into the watchdog window, which is how v1.2.0 still got killed
+     * at "Resolving refs" on large Java monorepos (#1122). `maybeYield()` is a
+     * ~ns time check when under budget, so per-ref checkpoints cost nothing.
+     * Behaviourally identical to `resolveAll(batch)`: `warmCaches()` is
+     * idempotent (guarded) and `resolveOne` is independent per ref, so yielding
+     * between refs changes only timing, never which edges get created.
      */
-    async resolveBatchYielding(batch, maybeYield, subChunkSize = 500) {
-        if (batch.length <= subChunkSize)
-            return this.resolveAll(batch);
+    async resolveBatchYielding(batch, maybeYield) {
+        this.warmCaches();
         const resolved = [];
         const unresolved = [];
         const byMethod = {};
-        let total = 0;
-        let resolvedCount = 0;
-        let unresolvedCount = 0;
-        for (let i = 0; i < batch.length; i += subChunkSize) {
-            const chunk = this.resolveAll(batch.slice(i, i + subChunkSize));
-            for (const r of chunk.resolved)
-                resolved.push(r);
-            for (const u of chunk.unresolved)
-                unresolved.push(u);
-            total += chunk.stats.total;
-            resolvedCount += chunk.stats.resolved;
-            unresolvedCount += chunk.stats.unresolved;
-            for (const [m, c] of Object.entries(chunk.stats.byMethod)) {
-                byMethod[m] = (byMethod[m] || 0) + c;
+        for (const raw of batch) {
+            const ref = {
+                fromNodeId: raw.fromNodeId,
+                referenceName: raw.referenceName,
+                referenceKind: raw.referenceKind,
+                line: raw.line,
+                column: raw.column,
+                filePath: raw.filePath || this.getFilePathFromNodeId(raw.fromNodeId),
+                language: raw.language || this.getLanguageFromNodeId(raw.fromNodeId),
+            };
+            const result = this.resolveOne(ref);
+            if (result) {
+                resolved.push(result);
+                byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
+            }
+            else {
+                unresolved.push(ref);
             }
             await maybeYield();
         }
-        return { resolved, unresolved, stats: { total, resolved: resolvedCount, unresolved: unresolvedCount, byMethod } };
+        return {
+            resolved,
+            unresolved,
+            stats: {
+                total: batch.length,
+                resolved: resolved.length,
+                unresolved: unresolved.length,
+                byMethod,
+            },
+        };
     }
     /**
      * Resolve and persist in batches to keep memory bounded.
@@ -920,7 +1085,6 @@ class ReferenceResolver {
      * up resolved refs after each batch to avoid accumulating large arrays.
      */
     async resolveAndPersistBatched(onProgress, batchSize = 5000) {
-        this.warmCaches();
         // Resolution runs on the indexer's MAIN thread, and the #850 liveness
         // watchdog SIGKILLs a process whose event loop stalls past its window (60s
         // by default). A single dense batch's resolveAll — or the synthesis pass
@@ -928,6 +1092,7 @@ class ReferenceResolver {
         // (#1091). A shared yielder lets both give the watchdog heartbeat a regular
         // window to fire; see ./cooperative-yield.
         const maybeYield = (0, cooperative_yield_1.createYielder)();
+        await this.warmCachesYielding(maybeYield);
         const total = this.queries.getUnresolvedReferencesCount();
         let processed = 0;
         const aggregateStats = {
@@ -944,26 +1109,39 @@ class ReferenceResolver {
             if (batch.length === 0)
                 break;
             const result = await this.resolveBatchYielding(batch, maybeYield);
+            // Persist in bounded sub-transactions with yields between: a whole
+            // batch's edge insert / keyed deletes are otherwise one solid
+            // synchronous span each on a multi-GB index, sitting BETWEEN the
+            // per-ref yields — the last unyielded stretch of the resolution loop.
+            // Crash semantics are unchanged (already several transactions): edges
+            // land before their refs are deleted, so a kill mid-way re-resolves
+            // the remainder idempotently on the next run/sweep (#1187).
+            const PERSIST_CHUNK = 1000;
             // Persist edges immediately
             const edges = this.createEdges(result.resolved);
-            if (edges.length > 0) {
-                this.queries.insertEdges(edges);
+            for (let i = 0; i < edges.length; i += PERSIST_CHUNK) {
+                this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
+                await maybeYield();
             }
             // Clean up resolved refs so they don't appear in the next batch
-            if (result.resolved.length > 0) {
-                this.queries.deleteSpecificResolvedReferences(result.resolved.map((r) => ({
-                    fromNodeId: r.original.fromNodeId,
-                    referenceName: r.original.referenceName,
-                    referenceKind: r.original.referenceKind,
-                })));
+            const resolvedKeys = result.resolved.map((r) => ({
+                fromNodeId: r.original.fromNodeId,
+                referenceName: r.original.referenceName,
+                referenceKind: r.original.referenceKind,
+            }));
+            for (let i = 0; i < resolvedKeys.length; i += PERSIST_CHUNK) {
+                this.queries.deleteSpecificResolvedReferences(resolvedKeys.slice(i, i + PERSIST_CHUNK));
+                await maybeYield();
             }
             // Delete unresolvable refs from this batch to avoid re-processing them
-            if (result.unresolved.length > 0) {
-                this.queries.deleteSpecificResolvedReferences(result.unresolved.map((r) => ({
-                    fromNodeId: r.fromNodeId,
-                    referenceName: r.referenceName,
-                    referenceKind: r.referenceKind,
-                })));
+            const unresolvedKeys = result.unresolved.map((r) => ({
+                fromNodeId: r.fromNodeId,
+                referenceName: r.referenceName,
+                referenceKind: r.referenceKind,
+            }));
+            for (let i = 0; i < unresolvedKeys.length; i += PERSIST_CHUNK) {
+                this.queries.deleteSpecificResolvedReferences(unresolvedKeys.slice(i, i + PERSIST_CHUNK));
+                await maybeYield();
             }
             // Aggregate stats
             aggregateStats.total += result.stats.total;
@@ -976,11 +1154,13 @@ class ReferenceResolver {
             onProgress?.(processed, total);
             // Yield so progress UI can render between batches
             await new Promise(resolve => setImmediate(resolve));
-            // If nothing was resolved or removed in this batch, we'd loop forever
-            // on the same rows. Break to avoid infinite loop.
-            if (result.resolved.length === 0 && result.unresolved.length === batch.length) {
-                break;
-            }
+            // NOTE: there used to be an extra early break here when a batch resolved
+            // nothing (`result.unresolved.length === batch.length`). That was wrong:
+            // an all-unresolvable batch still DELETES its rows (progress), yet the
+            // break abandoned every batch after it in the same run — on a repo whose
+            // first 5000 refs are all external/stdlib calls, resolution stopped at
+            // batch one and left the rest of the table as permanent orphans (#1187).
+            // The count-based guard below catches the true no-progress case.
             // Non-progress guard (defense-in-depth). Because we re-read from offset 0
             // each pass, the unresolved_refs table MUST shrink every iteration — both
             // resolved and unresolved refs are deleted above. If it didn't shrink, a
@@ -1022,11 +1202,18 @@ class ReferenceResolver {
     isBuiltInOrExternal(ref) {
         const name = ref.referenceName;
         const isJsTs = ref.language === 'typescript' || ref.language === 'javascript'
-            || ref.language === 'tsx' || ref.language === 'jsx';
+            || ref.language === 'tsx' || ref.language === 'jsx' || ref.language === 'arkts';
         // JavaScript/TypeScript built-ins
         if (isJsTs && JS_BUILT_INS.has(name)) {
             return true;
         }
+        // ArkTS resource-reference intrinsics — `$r('app.string.x')` /
+        // `$rawfile('x.png')` are framework-provided and appear dozens of times
+        // per UI file; without this they can resolve to a stray same-named
+        // symbol (e.g. a checked-in hvigor wrapper's `$r`).
+        if (ref.language === 'arkts' && (name === '$r' || name === '$rawfile')) {
+            return true;
+        }
         // Common JS/TS library calls (console.log, Math.floor, JSON.parse)
         if (isJsTs && (name.startsWith('console.') || name.startsWith('Math.') || name.startsWith('JSON.'))) {
             return true;
@@ -1191,6 +1378,96 @@ class ReferenceResolver {
         const target = found.values().next().value;
         return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
     }
+    /**
+     * Resolve a CFML inheritance reference written as a component path (#1152).
+     * Two forms exist in real code:
+     *
+     * - Dotted: `extends="coldbox.system.web.Controller"` — dots are directory
+     *   separators from the webroot or a CFML mapping. Mappings live in server
+     *   config / Application.cfc, so the leading segments may not exist in the
+     *   repo at all (in the coldbox repo itself the path is `system/web/
+     *   Controller.cfc` — the `coldbox.` root IS the repo). Matched by final
+     *   segment (the class), corroborated right-to-left against the candidate's
+     *   parent directories.
+     * - Relative: `extends="../base"` / `extends="./base"` (the FW/1 style) —
+     *   resolved against the referencing file's own directory.
+     *
+     * Conservative by design: a candidate needs at least one corroborating
+     * directory segment (a dotted path whose only same-named class sits in an
+     * unrelated directory is almost always an out-of-repo library supertype —
+     * mxunit/testbox/coldbox-as-dependency), and a corroboration tie yields no
+     * edge. Directory comparison is case-insensitive (CFML path resolution is);
+     * the class segment itself is matched exactly, which real code satisfies —
+     * dotted paths are written to match the on-disk file name.
+     */
+    resolveCfmlComponentPath(ref) {
+        const cfmlCandidates = (name) => this.context
+            .getNodesByName(name)
+            .filter((n) => (n.kind === 'class' || n.kind === 'interface') &&
+            (n.language === 'cfml' || n.language === 'cfscript'));
+        const norm = (p) => p.replace(/\\/g, '/').toLowerCase();
+        // Relative-path form: `../base`, `./base`, `sub/thing` — resolve against
+        // the referencing file's directory and require an exact (case-insensitive)
+        // file match.
+        if (ref.referenceName.includes('/')) {
+            const rel = ref.referenceName.replace(/\.cfc$/i, '');
+            const fromDir = ref.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
+            const parts = [...fromDir];
+            for (const seg of rel.split('/')) {
+                if (seg === '' || seg === '.')
+                    continue;
+                if (seg === '..') {
+                    if (parts.length === 0)
+                        return null; // escapes the project root
+                    parts.pop();
+                }
+                else {
+                    parts.push(seg);
+                }
+            }
+            const wantPath = norm(parts.join('/') + '.cfc');
+            const className = parts[parts.length - 1];
+            if (!className)
+                return null;
+            const target = cfmlCandidates(className).find((c) => norm(c.filePath) === wantPath);
+            return target
+                ? { original: ref, targetNodeId: target.id, confidence: 0.95, resolvedBy: 'file-path' }
+                : null;
+        }
+        // Dotted form.
+        const segments = ref.referenceName.split('.').map((s) => s.trim()).filter(Boolean);
+        if (segments.length < 2)
+            return null;
+        const className = segments[segments.length - 1];
+        const dirSegments = segments.slice(0, -1);
+        let best = null;
+        let bestScore = 0;
+        let tie = false;
+        for (const cand of cfmlCandidates(className)) {
+            const dirs = cand.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
+            // Count matching directory segments right-to-left: for
+            // `coldbox.system.web.Controller` vs `system/web/Controller.cfc`,
+            // `web` and `system` match, then the repo root ends the run → score 2.
+            let score = 0;
+            while (score < dirSegments.length &&
+                score < dirs.length &&
+                dirSegments[dirSegments.length - 1 - score].toLowerCase() ===
+                    dirs[dirs.length - 1 - score].toLowerCase()) {
+                score++;
+            }
+            if (score > bestScore) {
+                best = cand;
+                bestScore = score;
+                tie = false;
+            }
+            else if (score === bestScore && score > 0) {
+                tie = true;
+            }
+        }
+        if (!best || bestScore === 0 || tie)
+            return null;
+        return { original: ref, targetNodeId: best.id, confidence: 0.9, resolvedBy: 'qualified-name' };
+    }
     /**
      * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
      * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The