ucn 5.2.2 → 5.3.1

package/core/callers.js

@@ -592,10 +592,22 @@ function findCallers(index, name, options = {}) {
     // completion. Phase 2 still only enriches the first `maxResults` items —
     // file reads stay bounded, but the candidate count reflects the true total.
     const needsTotal = !!options.needsTotal;
-    const localTypeCache = new Map(); // `${filePath}:${startLine}` -> localTypes Map or null
-    const returnFlowCache = new Map(); // filePath -> return-type-flow map (see _buildReturnTypeFlowMap)
-    const foldCtxCache = new Map(); // filePath -> chained-receiver fold context (fix #258)
-    const pythonIndexedReceiverCache = new Map();
+    // Per-file query-time derivations that depend only on a file's immutable
+    // call records — never on the pinned target — so they live for the whole
+    // OPERATION, not one findCallers call (fix #340): stats --hot / repo run
+    // findCallers for hundreds of candidates over the same files, and
+    // rebuilding fold contexts (producer index, flow maps) and typed-local
+    // maps per candidate made grpc-go's `repo` cost 40s (1375 calls).
+    if (!index._opFindCallersCaches) {
+        index._opFindCallersCaches = {
+            localTypeCache: new Map(), // `${filePath}:${startLine}` -> localTypes Map or null
+            returnFlowCache: new Map(), // filePath -> return-type-flow map (see _buildReturnTypeFlowMap)
+            foldCtxCache: new Map(), // filePath -> chained-receiver fold context (fix #258)
+            pythonIndexedReceiverCache: new Map(),
+        };
+    }
+    const { localTypeCache, returnFlowCache, foldCtxCache, pythonIndexedReceiverCache } =
+        index._opFindCallersCaches;
 
     // Use inverted callee index to skip files that don't contain calls to this name
     let calleeFiles = index.getCalleeFiles(name);
@@ -1157,12 +1169,8 @@ function findCallers(index, name, options = {}) {
                                 receiverTypeFlowFile: path.join(index.root, project.rel),
                             };
                         } else {
-                            const projectish = bindings.some(b => {
-                                const mod = String(b.module || '');
-                                const first = mod.split(/[./]/).filter(Boolean)[0];
-                                return mod.startsWith('.') ||
-                                    (first && _projectTopLevelNames(index).has(first));
-                            });
+                            const projectish = bindings.some(b =>
+                                _unresolvedModuleIsGap(index, b.module, b));
                             const via = `${bindings[0].module}.${bindings[0].name}`;
                             if (BUILTIN_RECEIVER_TYPES.has(call.receiverType)) {
                                 // Stable stdlib runtime classes (StringIO,
@@ -1657,10 +1665,7 @@ function findCallers(index, name, options = {}) {
                         for (const binding of cbNameBindings) {
                             const rel = fileEntry.moduleResolved?.[binding.module];
                             if (!rel) {
-                                const mod = String(binding.module || '');
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, binding.module, binding)) {
                                     cbBindingUnknown = true;
                                 }
                                 continue;
@@ -2851,10 +2856,7 @@ function findCallers(index, name, options = {}) {
                                 // relative (project-internal by construction)
                                 // or its first segment names a project path
                                 // (resolution gap, not externality evidence)
-                                const mod = String(b.module);
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, b.module, b)) {
                                     undetermined = true;
                                 }
                                 continue;
@@ -3129,10 +3131,7 @@ function findCallers(index, name, options = {}) {
                             const rel = recvSubmoduleRel ||
                                 (fileEntry.moduleResolved && fileEntry.moduleResolved[b.module]);
                             if (!rel) {
-                                const mod = String(b.module);
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, b.module, b)) {
                                     projectish = true;
                                     undetermined = true;
                                 }
@@ -7956,10 +7955,7 @@ function _buildReturnTypeFlowMap(index, filePath, calls) {
                 // project `info`) is not identity evidence. Same externality
                 // test as #209 module ownership: relative or project-ish
                 // modules are resolver gaps, never externality evidence.
-                const mod = String(binding.module);
-                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                if (!mod.startsWith('.') &&
-                    !(firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                if (!_unresolvedModuleIsGap(index, binding.module, binding)) {
                     const scope = call.enclosingFunction ? `${call.enclosingFunction.startLine}` : '';
                     if (!map) map = new Map();
                     const key = `${scope}:${call.assignedTo}`;
@@ -9103,9 +9099,7 @@ function _structuralQualifiedReceiverOrigin(index, fileEntry, qualifier, typeNam
                 fromFile: path.join(index.root, rel),
             };
         }
-        const first = moduleName.split(/[./]/).filter(Boolean)[0];
-        if (moduleName.startsWith('.') ||
-            (first && _projectTopLevelNames(index).has(first))) {
+        if (_unresolvedModuleIsGap(index, moduleName)) {
             projectish = true;
         }
     }
@@ -9296,10 +9290,7 @@ function _nameBindingReaches(index, startAbs, name, targetFiles, maxDepth = 4) {
                     // Unresolved: relative or project-ish → resolver gap, not
                     // a terminal; clearly external → that path pins outside
                     // the project (dead end, consistent with #209c).
-                    const mod = String(module);
-                    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                    if (mod.startsWith('.') ||
-                        (firstSeg && _projectTopLevelNames(index).has(firstSeg))) unknown = true;
+                    if (_unresolvedModuleIsGap(index, module)) unknown = true;
                     return;
                 }
                 next.push([path.join(index.root, rel), nextAttr]);
@@ -9860,6 +9851,25 @@ function _projectTopLevelNames(index) {
     return names;
 }
 
+/**
+ * Is an UNRESOLVED module specifier a resolver gap rather than externality
+ * evidence? (fix #337b) Relative specifiers and first segments naming a
+ * project top-level path were already gaps (#209); a NON-LITERAL specifier —
+ * `require(path.join(__dirname, ...))`, `require(name)`, template paths — is
+ * one too: the parser records the expression text as the module, which can
+ * never match a package name, so judging it external excluded true callers as
+ * `other-definition-import`. Statically composable `__dirname` paths are
+ * resolved parser-side; whatever stays dynamic must route 'unknown'.
+ */
+function _unresolvedModuleIsGap(index, module, binding) {
+    const mod = String(module || '');
+    if (binding && binding.dynamic) return true;
+    if (mod.startsWith('.')) return true;
+    if (/[()$`{}+\s]/.test(mod)) return true;
+    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
+    return !!(firstSeg && _projectTopLevelNames(index).has(firstSeg));
+}
+
 const IDENTITY_TYPE_KINDS = new Set(['class', 'struct', 'interface', 'trait', 'enum']);
 
 /**
@@ -10740,10 +10750,9 @@ function _goQualifierNamesImport(index, fieldFile, qualifier) {
 function _iterExternalProducerVia(index, fileEntry, call) {
     if (!fileEntry || langTraits(fileEntry.language)?.typeSystem === 'nominal') return null;
     const externalModule = (mod) => {
-        if (!mod || mod.startsWith('.')) return false;
+        if (!mod) return false;
         if (fileEntry.moduleResolved?.[mod]) return false;
-        const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-        return !(firstSeg && _projectTopLevelNames(index).has(firstSeg));
+        return !_unresolvedModuleIsGap(index, mod);
     };
     if (call.isMethod && call.receiverIsModule && call.receiver) {
         const binding = _structuralModuleBindings(fileEntry, call)[0];
@@ -10831,10 +10840,9 @@ function _structuralCompositeModuleOwnership(
 
 function _pythonBuiltinContractAllowed(index, fileEntry, moduleName) {
     const module = String(moduleName || '');
-    if (!module || module.startsWith('.')) return false;
+    if (!module) return false;
     if (fileEntry.moduleResolved?.[module]) return false;
-    const first = module.split('.')[0];
-    return !first || !_projectTopLevelNames(index).has(first);
+    return !_unresolvedModuleIsGap(index, module);
 }
 
 function _structuralImportedReceiverType(index, fileEntry, receiver) {
@@ -10957,10 +10965,7 @@ function _calleeStructuralBindingRoute(index, fileEntry, call, language, binding
     for (const binding of bindings) {
         const rel = fileEntry.moduleResolved && fileEntry.moduleResolved[binding.module];
         if (!rel) {
-            const mod = String(binding.module || '');
-            const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-            if (mod.startsWith('.') ||
-                (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+            if (_unresolvedModuleIsGap(index, binding.module, binding)) {
                 sawProjectish = true;
                 sawUnknown = true;
             }
@@ -11008,10 +11013,7 @@ function _calleeExportDefinitions(index, startAbs, exposedName, language, call,
             const enqueue = (module, nextAttr) => {
                 const rel = fe.moduleResolved && fe.moduleResolved[module];
                 if (!rel) {
-                    const mod = String(module || '');
-                    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                    if (mod.startsWith('.') ||
-                        (firstSeg && _projectTopLevelNames(index).has(firstSeg))) unknown = true;
+                    if (_unresolvedModuleIsGap(index, module)) unknown = true;
                     return;
                 }
                 next.push([path.join(index.root, rel), nextAttr]);
@@ -15600,10 +15602,7 @@ function _typeOfCallResultFoldInner(index, fileEntry, filePath, record, ctx, con
             (binding && fileEntry.moduleResolved &&
                 fileEntry.moduleResolved[binding.module]);
         if (binding && !rel) {
-            const mod = String(binding.module);
-            const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-            if (!mod.startsWith('.') &&
-                !(firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+            if (!_unresolvedModuleIsGap(index, binding.module, binding)) {
                 return {
                     externalVia: `${record.receiver}.${name}`,
                     ...(/^[A-Z]/.test(name) && { externalConcrete: true }),
@@ -16129,4 +16128,4 @@ function findCallbackUsages(index, name) {
     return usages;
 }
 
-module.exports = { getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };
+module.exports = { _unresolvedModuleIsGap, _importReaches, _sameNominalPackageDir, getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };

package/core/check.js

@@ -88,9 +88,9 @@ function check(index, options = {}) {
         const nonSourcePaths = dr?.nonSourcePaths || 0;
         let reason = 'no changes detected';
         if (changedPaths > 0 && nonSourcePaths === changedPaths) {
-            reason = `${changedPaths} changed path(s), all outside supported source files`;
+            reason = `${changedPaths} changed path(s), all outside supported source files; untracked source files are included`;
         } else if (changedPaths > 0) {
-            reason = 'no callable-symbol changes in the diff';
+            reason = 'no callable-symbol changes in the diff or untracked source files';
         }
         return {
             base: options.base || 'HEAD',

package/core/execute.js

@@ -464,6 +464,14 @@ const PUBLIC_COMMAND_SET = new Set(CANONICAL_COMMANDS);
  * glob, file, and programmatic callers receive the same answer.
  */
 function validatePublicParams(command, p) {
+    if (p.raw && command !== 'source') return '--raw is supported only by source.';
+    if (p.lines && !['find', 'usages', 'search', 'show', 'impact'].includes(command)) {
+        return '--lines is supported by find, usages, search, show, and impact.';
+    }
+    if (p.lines && command === 'show' && p.sections) {
+        const parsed = parseSections(p.sections, ['callers'], new Set(['callers', 'callees']), 'show --lines');
+        if (parsed.error) return parsed.error;
+    }
     const hasName = typeof p.name === 'string' && p.name.trim() !== '';
     const gitScope = p.staged || (typeof p.base === 'string' && p.base.trim() !== '');
     if ((command === 'impact' || command === 'check') && hasName && gitScope) {
@@ -569,7 +577,7 @@ const HANDLERS = {
         } : query;
         const parsed = parseSections(
             p.sections,
-            ['summary', 'callers', 'callees'],
+            p.lines ? ['callers'] : ['summary', 'callers', 'callees'],
             SHOW_SECTIONS,
             'show',
         );
@@ -693,6 +701,8 @@ const HANDLERS = {
         const notes = [
             ...(resolved.warnings || []).map(warning => warning.message),
             response.note,
+            ...(p.raw ? (response.result.entries || []).filter(entry => entry.truncated)
+                .map(entry => `Source truncated: ${entry.match.relativePath}:${entry.match.startLine}; showing ${entry.shownLines || entry.maxLines} of ${entry.totalLines} lines (--max-lines).`) : []),
         ].filter(Boolean);
         return notes.length > 0
             ? { ...response, note: combineNotes(notes) }
@@ -1174,6 +1184,9 @@ const HANDLERS = {
             file: p.file,
             className: p.className,
             exact: p.exact || false,
+            // A shell definition listing renders no activity counts. Avoid a
+            // full pinned caller query for every definition in a wildcard.
+            skipCounts: !!p.lines,
             exclude,
             in: p.in,
         });
@@ -1430,7 +1443,7 @@ const HANDLERS = {
                 exclude,
                 in: p.in,
                 file: p.file,
-                top: topVal || 50,
+                top: topVal || (p.lines ? undefined : 50),
             });
             if (result.meta.error) return { ok: false, error: result.meta.error };
             const unsupported = (!p.regex && (p.term || p.name))
@@ -1456,7 +1469,7 @@ const HANDLERS = {
         // default at 500 and retain total/truncated metadata for controlled
         // expansion with an explicit top/limit.
         const topVal = num(p.top, undefined) || num(p.limit, undefined);
-        const effectiveLimit = topVal || 500;
+        const effectiveLimit = topVal || (p.lines ? undefined : 500);
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
@@ -2014,9 +2027,12 @@ const HANDLERS = {
 
         if (matches.length > 1 && p.all) {
             for (const m of matches) {
-                const code = readAndExtract(m);
+                const fullCode = readAndExtract(m);
                 const totalLines = m.endLine - m.startLine + 1;
-                entries.push({ match: m, code, totalLines, summaryMode: false, truncated: false });
+                const truncated = !!maxLines && totalLines > maxLines;
+                const code = truncated ? fullCode.split('\n').slice(0, maxLines).join('\n') : fullCode;
+                entries.push({ match: m, code, totalLines, summaryMode: false, truncated,
+                    ...(truncated && { maxLines }) });
             }
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
         }
@@ -2035,7 +2051,7 @@ const HANDLERS = {
         const totalLines = match.endLine - match.startLine + 1;
 
         // Large class summary mode (>200 lines, no maxLines)
-        if (totalLines > 200 && !maxLines) {
+        if (totalLines > 200 && !maxLines && !p.raw) {
             const methods = index.findMethodsForType(match.name, match);
             entries.push({ match, code: null, methods, totalLines, summaryMode: true, truncated: false });
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
@@ -2457,6 +2473,8 @@ function execute(index, command, params = {}) {
     // logged params object; a frozen object silently no-oped the
     // normalizers and returned wrong not-found answers).
     params = { ...params };
+    // Listing completeness belongs to execution, including direct API calls.
+    if (params.lines) params.all = true;
     try {
         if (PUBLIC_COMMAND_SET.has(command)) {
             const validationError = validatePublicParams(command, params);

package/core/graph.js

@@ -13,6 +13,16 @@ const { extractImports, resolveImport } = require('./imports');
 const { langTraits } = require('../languages');
 const { isTestFile } = require('./discovery');
 
+function importDeferralFields(imp, fileEntry) {
+    // A project-local typing module can expose a true TYPE_CHECKING flag.
+    // Parser spelling evidence alone cannot prove that guard runtime-false.
+    if (imp.deferredReason === 'type-checking' && fileEntry.moduleResolved?.typing) {
+        return { deferred: false };
+    }
+    return { deferred: !!imp.deferred,
+        ...(imp.deferredReason && { deferredReason: imp.deferredReason }) };
+}
+
 /**
  * Resolve imports in a file
  * @param {object} index - ProjectIndex instance
@@ -49,7 +59,7 @@ function imports(index, filePath) {
                     isExternal: false,
                     isDynamic: true,
                     line,
-                    deferred: !!imp.deferred,
+                    ...importDeferralFields(imp, fileEntry),
                 };
             }
 
@@ -66,7 +76,7 @@ function imports(index, filePath) {
                     isExternal: false,
                     isDynamic: true,
                     line,
-                    deferred: !!imp.deferred,
+                    ...importDeferralFields(imp, fileEntry),
                 };
             }
 
@@ -97,7 +107,7 @@ function imports(index, filePath) {
                 // `type: 'dynamic'` with `isDynamic: false` was a contradiction.
                 isDynamic: imp.type === 'dynamic',
                 line,
-                deferred: !!imp.deferred,
+                ...importDeferralFields(imp, fileEntry),
             };
         });
     } catch (e) {
@@ -735,17 +745,15 @@ function graph(index, filePath, options = {}) {
  * @param {object} options - { file, exclude }
  * @returns {object} - { cycles, totalFiles, summary }
  */
+const DEFAULT_CYCLE_LIMIT = 500;
+const MAX_ENUMERATED_COMPONENT = 2000;
+
 function circularDeps(index, options = {}) {
     index._beginOp();
     try {
         const exclude = options.exclude || [];
         const fileFilter = options.file || null;
 
-        const WHITE = 0, GRAY = 1, BLACK = 2;
-        const color = new Map();
-        const cycles = [];
-        const stack = [];
-
         const shouldSkip = (file) => {
             if (!index.files.has(file)) return true;
             if (exclude.length > 0) {
@@ -755,37 +763,137 @@ function circularDeps(index, options = {}) {
             return false;
         };
 
-        const dfs = (file) => {
-            color.set(file, GRAY);
-            stack.push(file);
-
-            const neighbors = index.importGraph.get(file) || new Set();
-
-            for (const neighbor of neighbors) {
-                if (neighbor === file) continue;  // Skip self-imports (not a cycle)
-                if (shouldSkip(neighbor)) continue;
-                const nc = color.get(neighbor) || WHITE;
-                if (nc === GRAY) {
-                    const idx = stack.indexOf(neighbor);
-                    cycles.push(stack.slice(idx));
-                } else if (nc === WHITE) {
-                    dfs(neighbor);
+        // Complete, order-independent enumeration (fix #339). The previous
+        // 3-color DFS reported only back-edge cycles: a cycle closing through
+        // an already-finished node was never emitted, so the answer depended
+        // on traversal order (click: 10 cycles in canonical order, 20 with
+        // reversed neighbor order, 4 shared). Tarjan strongly connected
+        // components + Johnson's elementary-circuit search over a canonically
+        // sorted adjacency — the same cycles for every build history — capped
+        // and disclosed (`summary.truncated`) so a dense tangle cannot explode.
+        const nodes = [...index.files.keys()].filter(f => !shouldSkip(f)).sort(codeUnitCompare);
+        const nodeIndex = new Map(nodes.map((f, i) => [f, i]));
+        const adj = nodes.map(f => {
+            const out = new Set();
+            for (const n of index.importGraph.get(f) || []) {
+                const j = nodeIndex.get(n);
+                if (j != null && n !== f) out.add(j);  // self-imports are not cycles
+            }
+            return [...out].sort((a, b) => a - b);
+        });
+        const components = [];
+        {
+            let counter = 0;
+            const idxOf = new Array(nodes.length).fill(-1);
+            const low = new Array(nodes.length).fill(0);
+            const onStack = new Array(nodes.length).fill(false);
+            const tarjanStack = [];
+            for (let root = 0; root < nodes.length; root++) {
+                if (idxOf[root] !== -1) continue;
+                idxOf[root] = low[root] = counter++;
+                tarjanStack.push(root); onStack[root] = true;
+                const work = [[root, 0]];
+                while (work.length > 0) {
+                    const frame = work[work.length - 1];
+                    const v = frame[0];
+                    if (frame[1] < adj[v].length) {
+                        const w = adj[v][frame[1]++];
+                        if (idxOf[w] === -1) {
+                            idxOf[w] = low[w] = counter++;
+                            tarjanStack.push(w); onStack[w] = true;
+                            work.push([w, 0]);
+                        } else if (onStack[w]) {
+                            low[v] = Math.min(low[v], idxOf[w]);
+                        }
+                    } else {
+                        work.pop();
+                        if (work.length > 0) {
+                            const u = work[work.length - 1][0];
+                            low[u] = Math.min(low[u], low[v]);
+                        }
+                        if (low[v] === idxOf[v]) {
+                            const comp = [];
+                            let w;
+                            do { w = tarjanStack.pop(); onStack[w] = false; comp.push(w); } while (w !== v);
+                            components.push(comp.sort((a, b) => a - b));
+                        }
+                    }
                 }
             }
-
-            stack.pop();
-            color.set(file, BLACK);
-        };
-
-        for (const file of index.files.keys()) {
-            if ((color.get(file) || WHITE) === WHITE && !shouldSkip(file)) {
-                dfs(file);
+        }
+        const cycleLimit = Number.isInteger(options.maxCycles) && options.maxCycles > 0
+            ? options.maxCycles : DEFAULT_CYCLE_LIMIT;
+        const cycles = [];
+        let truncated = false;
+        let limitReached = false;
+        const truncationReasons = new Set();
+        const cyclicComponents = components.filter(c => c.length >= 2).sort((a, b) => a[0] - b[0]);
+        for (const comp of cyclicComponents) {
+            if (limitReached) break;
+            if (comp.length > MAX_ENUMERATED_COMPONENT) {
+                truncated = true;
+                truncationReasons.add('component-size');
+                continue;
+            }
+            const inComp = new Set(comp);
+            for (const s of comp) {
+                if (limitReached) break;
+                const allowed = (v) => v >= s && inComp.has(v);
+                const blocked = new Map();
+                const blockedBy = new Map();
+                const trail = [];
+                const unblock = (u) => {
+                    blocked.set(u, false);
+                    const set = blockedBy.get(u);
+                    if (!set) return;
+                    blockedBy.set(u, new Set());
+                    for (const w of set) if (blocked.get(w)) unblock(w);
+                };
+                const circuit = (v) => {
+                    let found = false;
+                    trail.push(v);
+                    blocked.set(v, true);
+                    for (const w of adj[v]) {
+                        if (!allowed(w)) continue;
+                        if (w === s) {
+                            // Probe one extra cycle to distinguish a full list
+                            // of exactly N from a genuinely truncated list.
+                            if (cycles.length === cycleLimit) {
+                                truncated = limitReached = true;
+                                truncationReasons.add('cycle-limit');
+                                break;
+                            }
+                            cycles.push(trail.map(i => nodes[i]));
+                            found = true;
+                        } else if (!blocked.get(w)) {
+                            if (circuit(w)) found = true;
+                            if (limitReached) break;
+                        }
+                    }
+                    if (found) {
+                        unblock(v);
+                    } else {
+                        for (const w of adj[v]) {
+                            if (!allowed(w)) continue;
+                            if (!blockedBy.has(w)) blockedBy.set(w, new Set());
+                            blockedBy.get(w).add(v);
+                        }
+                    }
+                    trail.pop();
+                    return found;
+                };
+                circuit(s);
             }
         }
+        const componentSummaries = cyclicComponents.map(comp => ({
+            files: comp.map(i => index.files.get(nodes[i])?.relativePath || path.relative(index.root, nodes[i]))
+                .sort(codeUnitCompare),
+            size: comp.length,
+        }));
 
         const importEdgeDetails = (fromFile, toFile) => {
             const entry = index.files.get(fromFile);
-            if (!entry || entry.language !== 'python') return [];
+            if (!entry) return [];
             const matches = [];
             for (const detail of entry.importDetails || []) {
                 const specs = [detail.module];
@@ -804,7 +912,7 @@ function circularDeps(index, options = {}) {
                     from: entry.relativePath,
                     to: index.files.get(toFile)?.relativePath || path.relative(index.root, toFile),
                     line: detail.line ?? null,
-                    deferred: !!detail.deferred,
+                    ...importDeferralFields(detail, entry),
                 });
             }
             return matches;
@@ -832,10 +940,14 @@ function circularDeps(index, options = {}) {
                     const to = rotatedAbs[(edgeIndex + 1) % rotatedAbs.length];
                     const details = importEdgeDetails(from, to);
                     const deferred = details.length > 0 && details.every(detail => detail.deferred);
+                    const deferredReasons = deferred
+                        ? [...new Set(details.map(detail => detail.deferredReason).filter(Boolean))].sort()
+                        : [];
                     edges.push({
                         from: rotated[edgeIndex],
                         to: rotated[(edgeIndex + 1) % rotated.length],
                         deferred,
+                        ...(deferredReasons.length > 0 && { deferredReasons }),
                         ...(details.length > 0 && {
                             lines: [...new Set(details.map(detail => detail.line)
                                 .filter(line => line != null))].sort((a, b) => a - b),
@@ -847,6 +959,7 @@ function circularDeps(index, options = {}) {
                         from: edge.from,
                         to: edge.to,
                         line: edge.lines?.[0] ?? null,
+                        ...(edge.deferredReasons && { reasons: edge.deferredReasons }),
                         ...(edge.lines?.length > 1 && { lines: edge.lines }),
                     }));
                 uniqueCycles.push({
@@ -865,7 +978,7 @@ function circularDeps(index, options = {}) {
             result = uniqueCycles.filter(c => c.files.some(f => f.includes(fileFilter)));
         }
 
-        result.sort((a, b) => a.length - b.length || codeUnitCompare(a.files[0], b.files[0]));
+        result.sort((a, b) => a.length - b.length || codeUnitCompare(a.files.join('\0'), b.files.join('\0')));
 
         // Count files that participate in import graph (have edges)
         let filesWithImports = 0;
@@ -875,16 +988,35 @@ function circularDeps(index, options = {}) {
 
         const eagerCycles = result.filter(cycle => cycle.classification !== 'deferred').length;
         const deferredCycles = result.length - eagerCycles;
+        const groupOf = new Map();
+        componentSummaries.forEach((group, i) => { for (const f of group.files) groupOf.set(f, i); });
+        for (const group of componentSummaries) { group.eagerCycles = 0; group.deferredCycles = 0; }
+        for (const cycle of result) {
+            const group = componentSummaries[groupOf.get(cycle.files[0])];
+            if (!group) continue;
+            if (cycle.classification === 'deferred') group.deferredCycles++;
+            else group.eagerCycles++;
+        }
+        const cycleGroups = fileFilter
+            ? componentSummaries.filter(c => c.files.some(f => f.includes(fileFilter)))
+            : componentSummaries;
         return {
             cycles: result,
+            // Strongly connected groups: every file in a group sits on at
+            // least one cycle with every other member — the refactor unit.
+            components: cycleGroups,
             totalFiles: index.files.size,
             filesWithImports,
             fileFilter: fileFilter || undefined,
             summary: {
                 totalCycles: result.length,
-                filesInCycles: new Set(result.flatMap(c => c.files)).size,
+                filesInCycles: new Set(cycleGroups.flatMap(c => c.files)).size,
                 eagerCycles,
                 deferredCycles,
+                componentCount: cycleGroups.length,
+                ...(truncated && { truncated: true, cycleLimit,
+                    maxComponentSize: MAX_ENUMERATED_COMPONENT,
+                    truncationReasons: [...truncationReasons] }),
             }
         };
     } finally {

package/core/index-ir.js

@@ -21,6 +21,7 @@ function createImportBindings(imports) {
                 ...(rename && { alias: rename.local }),
                 ...(item.defaultLike && { defaultLike: true }),
                 ...(item.deferred && { deferred: true }),
+                ...(item.dynamic && { dynamic: true }),
             };
         }));
 }
@@ -47,15 +48,17 @@ function createFileEntryFromIR({
         mtime,
         size,
         imports: imports.map(item => item.module),
-        ...(ir.language === 'python' && {
-            importDetails: imports.map(item => ({
-                module: item.module,
-                names: [...(item.names || [])],
-                ...(item.type && { type: item.type }),
-                ...(item.line != null && { line: item.line }),
-                ...(item.deferred && { deferred: true }),
-            })),
-        }),
+        // Per-import detail records (fix #307, Python-only then; un-gated in
+        // fix #338 so JS/TS function-local require()/import() and type-only
+        // imports classify cycle edges the same way).
+        importDetails: imports.map(item => ({
+            module: item.module,
+            names: [...(item.names || [])],
+            ...(item.type && { type: item.type }),
+            ...(item.line != null && { line: item.line }),
+            ...(item.deferred && { deferred: true }),
+            ...(item.deferredReason && { deferredReason: item.deferredReason }),
+        })),
         globalImports: imports.filter(item => item.global).map(item => item.module),
         importNames: imports.flatMap(item => item.names || []),
         importBindings: createImportBindings(imports),