ucn 5.2.2 → 5.3.0

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),

package/core/output/graph.js

@@ -21,7 +21,7 @@ function formatImports(imports, filePath) {
     if (internal.length > 0) {
         lines.push('INTERNAL:');
         for (const imp of internal) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.resolved) {
                 lines.push(`    -> ${imp.resolved}${imp.indexed === false
                     ? ' (not indexed; absent from dependency graph)'
@@ -37,7 +37,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0) lines.push('');
         lines.push('EXTERNAL:');
         for (const imp of external) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -48,7 +48,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0 || external.length > 0) lines.push('');
         lines.push('DYNAMIC (unresolved):');
         for (const imp of dynamic) {
-            lines.push(`  ${imp.module || '(variable)'}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module || '(variable)'}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -407,6 +407,22 @@ function formatGraphJson(graph) {
     return JSON.stringify(result, null, 2);
 }
 
+// fix #338: deferred-edge vocabulary shared by deps and cycle output.
+const DEFERRED_REASON_LABELS = {
+    'function-local': 'function-local import',
+    'type-checking': 'TYPE_CHECKING-only import, never executed at runtime',
+    'type-only': 'type-only import, erased at compile time',
+};
+function deferredReasonLabel(reason) {
+    return DEFERRED_REASON_LABELS[reason] || 'deferred import';
+}
+const EAGER_CYCLE_DISPLAY_LIMIT = 25;
+const DEFERRED_CYCLE_DISPLAY_LIMIT = 10;
+function deferredImportLabel(imp) {
+    if (!imp.deferred) return '';
+    return imp.deferredReason ? ` [deferred: ${imp.deferredReason}]` : ' [deferred]';
+}
+
 function formatCircularDeps(result) {
     if (!result) return 'No results.';
     const lines = [];
@@ -420,7 +436,7 @@ function formatCircularDeps(result) {
 
     const scannedCount = result.filesWithImports != null ? result.filesWithImports : result.totalFiles;
 
-    if (result.cycles.length === 0) {
+    if (result.cycles.length === 0 && !(result.components || []).length && !result.summary?.truncated) {
         lines.push('');
         lines.push('No circular dependencies found.');
         lines.push(`Scanned ${scannedCount} files with import relationships.`);
@@ -429,12 +445,32 @@ function formatCircularDeps(result) {
 
     const eager = result.cycles.filter(cycle => cycle.classification !== 'deferred');
     const deferred = result.cycles.filter(cycle => cycle.classification === 'deferred');
+
+    // Groups first: a strongly connected file set is the unit a refactor has
+    // to break, and a 14-file tangle can hold hundreds of elementary cycles.
+    const groups = result.components || [];
+    if (groups.length > 0) {
+        lines.push('');
+        lines.push(`CYCLE GROUPS (${groups.length}) — every member reaches every other member:`);
+        for (const group of groups) {
+            const counts = [];
+            if (group.eagerCycles != null) counts.push(`${group.eagerCycles} import-time`);
+            if (group.deferredCycles != null) counts.push(`${group.deferredCycles} deferred`);
+            const suffix = counts.length > 0 ? `  [${counts.join(', ')}${result.summary.truncated ? '; enumerated counts only' : ''}]` : '';
+            lines.push(`  ${group.size} files: ${group.files.join(', ')}${suffix}`);
+        }
+    }
+
     let cycleNumber = 0;
-    const renderGroup = (title, group, deferredGroup = false) => {
+    const renderGroup = (title, group, deferredGroup, displayLimit) => {
         if (group.length === 0) return;
+        const shown = group.slice(0, displayLimit);
         lines.push('');
-        lines.push(`${title} (${group.length}):`);
-        for (const cycle of group) {
+        const heading = shown.length < group.length
+            ? `${title} (${group.length}, showing ${shown.length} shortest):`
+            : `${title} (${group.length}):`;
+        lines.push(heading);
+        for (const cycle of shown) {
             cycleNumber++;
             lines.push('');
             lines.push(`Cycle ${cycleNumber} (${cycle.length} files):`);
@@ -442,19 +478,32 @@ function formatCircularDeps(result) {
             if (deferredGroup) {
                 for (const edge of cycle.deferredEdges || []) {
                     const at = edge.line != null ? `:${edge.line}` : '';
-                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (function-local import)`);
+                    const why = (edge.reasons || []).map(deferredReasonLabel).join('; ') || 'function-local import';
+                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (${why})`);
                 }
             }
         }
+        if (shown.length < group.length) {
+            lines.push(`  ... and ${group.length - shown.length} more (use --json for the full list)`);
+        }
     };
-    renderGroup('IMPORT-TIME CYCLES', eager);
-    renderGroup('DEFERRED CYCLES', deferred, true);
+    renderGroup('IMPORT-TIME CYCLES', eager, false, EAGER_CYCLE_DISPLAY_LIMIT);
+    renderGroup('DEFERRED CYCLES', deferred, true, DEFERRED_CYCLE_DISPLAY_LIMIT);
 
     lines.push('');
     const { totalCycles, filesInCycles } = result.summary;
     lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} (${scannedCount} files with imports scanned).`);
+    if (result.summary.truncated) {
+        if (result.summary.truncationReasons?.includes('component-size')) {
+            lines.push(`Cycle enumeration skipped groups larger than ${result.summary.maxComponentSize} files.`);
+        }
+        if (!result.summary.truncationReasons || result.summary.truncationReasons.includes('cycle-limit')) {
+            lines.push(`Enumeration stopped at ${result.summary.cycleLimit} elementary cycles.`);
+        }
+        lines.push('The CYCLE GROUPS list and files-in-cycles count are complete; enumerated cycle counts are lower bounds.');
+    }
     if (deferred.length > 0) {
-        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} contain a function-local import; they are not unconditional import-time cycles, but may still matter if invoked during initialization.`);
+        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} close only through deferred edges (function-local, TYPE_CHECKING-only, or type-only imports); they are not unconditional import-time cycles, but a function-local edge may still matter if invoked during initialization.`);
     }
 
     return lines.join('\n');