ucn 4.0.2 → 4.1.0

package/core/graph-build.js

@@ -30,8 +30,11 @@ function buildDirIndex(index) {
  * Resolve a Java package import to a project file.
  * Handles regular imports, static imports (strips member name), and wildcards (strips .*).
  * Progressively strips trailing segments to find the class file.
+ * With `opts.all`, returns an ARRAY of files: for a package wildcard
+ * (com.pkg.*) that's every file directly in the package — Java wildcard
+ * imports pull in the whole package, and they are NOT recursive.
  */
-function _resolveJavaPackageImport(index, importModule, javaFileIndex) {
+function _resolveJavaPackageImport(index, importModule, javaFileIndex, opts = {}) {
     const isWildcard = importModule.endsWith('.*');
     // Strip wildcard suffix (e.g., "com.pkg.Class.*" -> "com.pkg.Class")
     const mod = isWildcard ? importModule.slice(0, -2) : importModule;
@@ -48,7 +51,7 @@ function _resolveJavaPackageImport(index, importModule, javaFileIndex) {
                 const fileSuffix = '/' + segments.slice(0, i).join('/') + '.java';
                 for (const absPath of candidates) {
                     if (absPath.endsWith(fileSuffix)) {
-                        return absPath;
+                        return opts.all ? [absPath] : absPath;
                     }
                 }
             }
@@ -59,24 +62,31 @@ function _resolveJavaPackageImport(index, importModule, javaFileIndex) {
             const fileSuffix = '/' + segments.slice(0, i).join('/') + '.java';
             for (const absPath of index.files.keys()) {
                 if (absPath.endsWith(fileSuffix)) {
-                    return absPath;
+                    return opts.all ? [absPath] : absPath;
                 }
             }
         }
     }
 
     // For wildcard imports (com.pkg.model.*), the package may be a directory
-    // containing .java files. Check if any file lives under this package path.
+    // containing .java files. Match files DIRECTLY in the package directory —
+    // a bare `includes()` also matched subpackage files, but Java wildcards
+    // are not recursive.
     if (isWildcard) {
-        const dirSuffix = '/' + segments.join('/') + '/';
+        const dirSuffix = '/' + segments.join('/');
+        const matches = [];
         for (const absPath of index.files.keys()) {
-            if (absPath.includes(dirSuffix)) {
-                return absPath;
+            if (absPath.endsWith('.java') && path.dirname(absPath).endsWith(dirSuffix)) {
+                matches.push(absPath);
+                if (!opts.all) break;
             }
         }
+        if (matches.length > 0) {
+            return opts.all ? matches : matches[0];
+        }
     }
 
-    return null;
+    return opts.all ? [] : null;
 }
 
 /**
@@ -130,15 +140,27 @@ function buildImportGraph(index) {
 
             // Java package imports: resolve by progressive suffix matching
             // Handles regular, static (com.pkg.Class.method), and wildcard (com.pkg.Class.*) imports
+            let javaWildcardFiles = null;
             if (!resolved && fileEntry.language === 'java' && !importModule.startsWith('.')) {
-                resolved = _resolveJavaPackageImport(index, importModule, javaFileIndex);
+                if (importModule.endsWith('.*')) {
+                    // A package wildcard depends on EVERY file in the package
+                    // (the Go filesToLink analog) — linking only the first
+                    // dropped dependency edges for the rest of the package.
+                    const all = _resolveJavaPackageImport(index, importModule, javaFileIndex, { all: true });
+                    if (all.length > 0) {
+                        resolved = all[0];
+                        if (all.length > 1) javaWildcardFiles = all;
+                    }
+                } else {
+                    resolved = _resolveJavaPackageImport(index, importModule, javaFileIndex);
+                }
             }
 
             if (resolved && index.files.has(resolved)) {
                 moduleResolved[importModule] = path.relative(index.root, resolved);
                 // For Go, a package import means all files in that directory are dependencies
                 // (Go packages span multiple files in the same directory)
-                const filesToLink = [resolved];
+                const filesToLink = javaWildcardFiles ? [...javaWildcardFiles] : [resolved];
                 if (langTraits(fileEntry.language)?.packageScope === 'directory') {
                     const pkgDir = path.dirname(resolved);
                     const dirFiles = dirToGoFiles.get(pkgDir) || [];
@@ -161,6 +183,35 @@ function buildImportGraph(index) {
             }
         }
 
+        // From-import submodules (fix #224): `from . import jobs` binds
+        // jobs.py as a plain NAME — the parser can't know (a from-import name
+        // may be a symbol), the resolver can. Resolve the composed dotted
+        // specifier; a project-file hit records it in moduleResolved AND adds
+        // the import edge, so scope resolution and module-receiver ownership
+        // see the submodule exactly like `import jobs`.
+        if (langTraits(fileEntry.language)?.submoduleImports) {
+            for (const b of (fileEntry.importBindings || [])) {
+                if (!b || !b.name || b.module == null) continue;
+                const mod = String(b.module);
+                const spec = mod.endsWith('.') ? mod + b.name : mod + '.' + b.name;
+                if (moduleResolved[spec] || seenModules.has(spec)) continue;
+                seenModules.add(spec);
+                const resolved = resolveImport(spec, filePath, {
+                    aliases: index.config.aliases,
+                    language: fileEntry.language,
+                    root: index.root
+                });
+                if (resolved && index.files.has(resolved)) {
+                    moduleResolved[spec] = path.relative(index.root, resolved);
+                    importedFiles.add(resolved);
+                    if (!index.exportGraph.has(resolved)) {
+                        index.exportGraph.set(resolved, new Set());
+                    }
+                    index.exportGraph.get(resolved).add(filePath);
+                }
+            }
+        }
+
         index.importGraph.set(filePath, importedFiles);
         fileEntry.moduleResolved = moduleResolved;
     }

package/core/graph.js

@@ -8,6 +8,7 @@
 'use strict';
 
 const path = require('path');
+const { codeUnitCompare } = require('./shared');
 const { extractImports, resolveImport } = require('./imports');
 const { langTraits } = require('../languages');
 const { isTestFile } = require('./discovery');
@@ -32,9 +33,12 @@ function imports(index, filePath) {
         const content = index._readFile(normalizedPath);
         const { imports: rawImports } = extractImports(content, fileEntry.language);
 
-        const contentLines = content.split('\n');
-
         return rawImports.map(imp => {
+            // Every parser records the import's AST line; use it directly.
+            // (The old substring re-derivation matched 'os' inside 'osmosis',
+            // comments, and collapsed repeated modules to the first line.)
+            const line = imp.line ?? null;
+
             // Skip imports with null module (e.g. Rust include! with dynamic path)
             if (!imp.module) {
                 return {
@@ -44,7 +48,7 @@ function imports(index, filePath) {
                     resolved: null,
                     isExternal: false,
                     isDynamic: true,
-                    line: null
+                    line
                 };
             }
 
@@ -53,13 +57,6 @@ function imports(index, filePath) {
             // Go side-effect/dot imports and Rust glob uses also set dynamic=true but have valid module paths.
             const isUnresolvableDynamic = imp.dynamic && (imp.type === 'require' || imp.type === 'dynamic');
             if (isUnresolvableDynamic) {
-                let line = null;
-                for (let i = 0; i < contentLines.length; i++) {
-                    if (contentLines[i].includes(imp.module || 'require')) {
-                        line = i + 1;
-                        break;
-                    }
-                }
                 return {
                     module: imp.module,
                     names: imp.names,
@@ -83,22 +80,16 @@ function imports(index, filePath) {
                 resolvedPath = index._resolveJavaPackageImport(imp.module);
             }
 
-            // Find line number of import
-            let line = null;
-            for (let i = 0; i < contentLines.length; i++) {
-                if (contentLines[i].includes(imp.module)) {
-                    line = i + 1;
-                    break;
-                }
-            }
-
             return {
                 module: imp.module,
                 names: imp.names,
                 type: imp.type,
                 resolved: resolvedPath ? path.relative(index.root, resolvedPath) : null,
                 isExternal: !resolvedPath,
-                isDynamic: false,
+                // A string-literal dynamic import (import('./x'), importlib.import_module("x"))
+                // is still mechanically dynamic even when the path resolves —
+                // `type: 'dynamic'` with `isDynamic: false` was a contradiction.
+                isDynamic: imp.type === 'dynamic',
                 line
             };
         });
@@ -107,6 +98,45 @@ function imports(index, filePath) {
     }
 }
 
+/**
+ * Decide whether a symbol is exported, using evidence at the right scope:
+ * the file-level export list speaks for TOP-LEVEL names only — a struct
+ * field or method sharing an exported function's name is not itself exported.
+ * Member symbols (className set) are judged by their OWN visibility marker:
+ * export/public modifiers, Rust `pub`/`pub(crate)`, or Go capitalization.
+ */
+function symbolIsExported(symbol, fileEntry, exportedNames) {
+    const modifiers = symbol.modifiers || [];
+    if (modifiers.includes('export') || modifiers.includes('public')) return true;
+    if (modifiers.some(m => typeof m === 'string' && /^pub\b/.test(m))) return true;
+    if (langTraits(fileEntry.language)?.exportVisibility === 'capitalization' &&
+        /^[A-Z]/.test(symbol.name || '')) return true;
+    // Rust trait-impl members cannot carry `pub` (the compiler forbids it) —
+    // their visibility IS the implementing type's (fix #251:
+    // `impl Default for Config` methods of a pub Config are publicly
+    // callable but were listed nowhere).
+    if (symbol.traitImpl && symbol.className && fileEntry.language === 'rust') {
+        for (const s of fileEntry.symbols || []) {
+            if (s.name === symbol.className &&
+                ['struct', 'enum', 'class', 'type'].includes(s.type)) {
+                return (s.modifiers || []).some(m => typeof m === 'string' && /^pub\b/.test(m));
+            }
+        }
+        return exportedNames.has(symbol.className);
+    }
+    if (symbol.className) return false;
+    return exportedNames.has(symbol.name);
+}
+
+/**
+ * Signature for export listings: members render as `Class.name(...)` so a
+ * Go/Rust/Java method is distinguishable from a free function of the same name.
+ */
+function formatExportSignature(index, symbol) {
+    if (!symbol.className) return index.formatSignature(symbol);
+    return index.formatSignature({ ...symbol, name: `${symbol.className}.${symbol.name}` });
+}
+
 /**
  * Get files that import a given file
  * @param {object} index - ProjectIndex instance
@@ -120,39 +150,72 @@ function exporters(index, filePath) {
     const targetPath = resolved;
 
     const importers = index.exportGraph.get(targetPath) || new Set();
+    const targetRel = path.relative(index.root, targetPath);
+    const targetDir = path.dirname(targetRel);
 
-    return [...importers].map(importerPath => {
+    const results = [...importers].map(importerPath => {
         const fileEntry = index.files.get(importerPath);
 
-        // Find the import line
+        // Locate the import statement via the importer's own parsed import
+        // records: fileEntry.moduleResolved (built with the import graph) maps
+        // each module string to the project file it resolved to, and the
+        // parser records each import's AST line. (The old basename+'import'
+        // substring heuristic matched comments, returned null for Rust
+        // use/mod, and misfired on prose like 'important'.)
         let importLine = null;
-        try {
-            const content = index._readFile(importerPath);
-            const lines = content.split('\n');
-            let targetBasename = path.basename(targetPath, path.extname(targetPath));
-
-            // For __init__.py, search for the package name (parent dir)
-            // e.g., "from tools import X" → search for "tools" not "__init__"
-            if (targetBasename === '__init__') {
-                targetBasename = path.basename(path.dirname(targetPath));
-            }
-
-            for (let i = 0; i < lines.length; i++) {
-                if (lines[i].includes(targetBasename) &&
-                    (lines[i].includes('import') || lines[i].includes('require') || lines[i].includes('from'))) {
-                    importLine = i + 1;
-                    break;
+        let importModule = null;
+        const mr = (fileEntry && fileEntry.moduleResolved) || {};
+        let matchModules = Object.keys(mr).filter(m => mr[m] === targetRel);
+        if (matchModules.length === 0) {
+            // Directory-level links: a Go package import (or Java wildcard)
+            // links every file in the target's directory — the module string
+            // resolved to a sibling, but the statement still covers the target.
+            matchModules = Object.keys(mr).filter(m => {
+                if (path.dirname(mr[m]) !== targetDir) return false;
+                const lang = fileEntry.language;
+                if (langTraits(lang)?.packageScope === 'directory') return true;
+                if (lang === 'java' && m.endsWith('.*')) return true;
+                return false;
+            });
+        }
+        if (matchModules.length > 0 && fileEntry) {
+            try {
+                const content = index._readFile(importerPath);
+                const { imports: rawImports } = extractImports(content, fileEntry.language);
+                const wanted = new Set(matchModules);
+                const submodules = langTraits(fileEntry.language)?.submoduleImports;
+                for (const imp of rawImports) {
+                    if (!imp.module) continue;
+                    let matched = wanted.has(imp.module) ? imp.module : null;
+                    // Python from-import submodules resolve under a composed
+                    // spec (`from . import jobs` → '.jobs', fix #224) that the
+                    // raw record stores as module '.' + name 'jobs'.
+                    if (!matched && submodules && imp.names) {
+                        for (const n of imp.names) {
+                            const spec = imp.module.endsWith('.') ? imp.module + n : imp.module + '.' + n;
+                            if (wanted.has(spec)) { matched = spec; break; }
+                        }
+                    }
+                    if (matched && imp.line != null &&
+                        (importLine === null || imp.line < importLine)) {
+                        importLine = imp.line;
+                        importModule = matched;
+                    }
                 }
+            } catch (e) {
+                // Skip — file unreadable, leave importLine null
             }
-        } catch (e) {
-            // Skip
         }
 
         return {
             file: fileEntry ? fileEntry.relativePath : path.relative(index.root, importerPath),
-            importLine
+            importLine,
+            ...(importModule !== null && { module: importModule })
         };
     });
+
+    results.sort((a, b) => codeUnitCompare(a.file, b.file));
+    return results;
 }
 
 /**
@@ -179,6 +242,21 @@ function fileExports(index, filePath, _visited) {
     const results = [];
     const exportedNames = new Set(fileEntry.exports);
 
+    // Names exported ONLY under an alias (`export { foo as myFoo }`, no
+    // plain export) are importable only AS the alias — the alias entry is
+    // added from exportDetails below; the bare name would be a lie (fix #245).
+    const aliasedAway = new Set();
+    if (fileEntry.exportDetails) {
+        const plainClauseNames = new Set(fileEntry.exportDetails
+            .filter(e => e.type === 'named' && !e.source && !e.alias)
+            .map(e => e.name));
+        for (const e of fileEntry.exportDetails) {
+            if (e.type === 'named' && !e.source && e.alias && !plainClauseNames.has(e.name)) {
+                aliasedAway.add(e.name);
+            }
+        }
+    }
+
     // Python convention: when a module declares no `__all__`, every top-level
     // non-`_` name is considered public. We don't want this in the underlying
     // export list (deadcode would think everything is exported), so fileExports
@@ -186,10 +264,11 @@ function fileExports(index, filePath, _visited) {
     const isPythonImplicit = fileEntry.language === 'python' && exportedNames.size === 0;
 
     for (const symbol of fileEntry.symbols) {
-        const isExported = exportedNames.has(symbol.name) ||
-            (symbol.modifiers && symbol.modifiers.includes('export')) ||
-            (symbol.modifiers && symbol.modifiers.includes('public')) ||
-            (langTraits(fileEntry.language)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(symbol.name)) ||
+        // impl blocks group members; the block itself is not an exportable
+        // symbol (its name collides with the struct's, which IS listed).
+        if (symbol.type === 'impl') continue;
+        if (aliasedAway.has(symbol.name) && !(symbol.modifiers || []).includes('export')) continue;
+        const isExported = symbolIsExported(symbol, fileEntry, exportedNames) ||
             (isPythonImplicit && symbol.name && !symbol.name.startsWith('_') && !symbol.className && !symbol.isMethod);
 
         if (isExported) {
@@ -199,9 +278,10 @@ function fileExports(index, filePath, _visited) {
                 file: fileEntry.relativePath,
                 startLine: symbol.startLine,
                 endLine: symbol.endLine,
+                ...(symbol.className && { className: symbol.className }),
                 params: symbol.params,
                 returnType: symbol.returnType,
-                signature: index.formatSignature(symbol)
+                signature: formatExportSignature(index, symbol)
             });
         }
     }
@@ -243,16 +323,32 @@ function fileExports(index, filePath, _visited) {
                             for (const srcExp of sourceExportsResult) {
                                 if (!matchedNames.has(srcExp.name)) {
                                     matchedNames.add(srcExp.name);
-                                    results.push({ ...srcExp, file: fileEntry.relativePath, reExportedFrom: srcExp.file });
+                                    // The entry belongs to the BARREL file —
+                                    // its line is the `export *` statement,
+                                    // never the source's line numbers (fix
+                                    // #245: barrel.ts:9-11 on a 1-line file).
+                                    results.push({
+                                        ...srcExp,
+                                        file: fileEntry.relativePath,
+                                        startLine: exp.line,
+                                        endLine: exp.line,
+                                        reExportedFrom: srcExp.file,
+                                    });
                                 }
                             }
                         } else {
-                            // Named re-export: find the specific symbol
+                            // Named re-export: find the specific symbol.
+                            // Consumers import the ALIAS when one exists —
+                            // `export { foo as myFoo } from './lib'` is
+                            // importable only as myFoo (fix #245); the
+                            // source-side name stays in sourceName.
+                            const displayName = exp.alias || exp.name;
                             const srcSymbol = sourceEntry.symbols.find(s => s.name === exp.name);
                             if (srcSymbol) {
                                 matchedNames.add(exp.name);
                                 results.push({
-                                    name: exp.name,
+                                    name: displayName,
+                                    ...(exp.alias && { sourceName: exp.name }),
                                     type: srcSymbol.type,
                                     file: fileEntry.relativePath,
                                     startLine: exp.line,
@@ -266,7 +362,8 @@ function fileExports(index, filePath, _visited) {
                                 // Symbol not found in source — still list it as a re-export
                                 matchedNames.add(exp.name);
                                 results.push({
-                                    name: exp.name,
+                                    name: displayName,
+                                    ...(exp.alias && { sourceName: exp.name }),
                                     type: 're-export',
                                     file: fileEntry.relativePath,
                                     startLine: exp.line,
@@ -282,6 +379,61 @@ function fileExports(index, filePath, _visited) {
                 }
             }
         }
+
+        // Local export clauses: `export { foo, bar }` / `export { foo as
+        // myFoo }`. A clause-exported CONST has no isVariable flag and no
+        // symbol entry, and a two-step barrel (`import { foo } from './lib';
+        // export { foo };`) matched nothing — both rendered empty (fix
+        // #245). Aliased local exports list under the ALIAS.
+        for (const exp of fileEntry.exportDetails) {
+            if (exp.type !== 'named' || exp.source || exp.isVariable) continue;
+            const displayName = exp.alias || exp.name;
+            if (matchedNames.has(displayName)) continue;
+            if (!exp.alias && matchedNames.has(exp.name)) continue;
+            const localSym = fileEntry.symbols.find(s => s.name === exp.name && !s.className);
+            if (localSym) {
+                matchedNames.add(displayName);
+                results.push({
+                    name: displayName,
+                    ...(exp.alias && { sourceName: exp.name }),
+                    type: localSym.type,
+                    file: fileEntry.relativePath,
+                    startLine: localSym.startLine,
+                    endLine: localSym.endLine,
+                    params: localSym.params,
+                    returnType: localSym.returnType,
+                    signature: index.formatSignature(localSym)
+                });
+                continue;
+            }
+            // Two-step barrel: the name is an import binding — resolve it
+            const binding = (fileEntry.importBindings || []).find(b => b.name === exp.name);
+            const resolvedRel = binding && fileEntry.moduleResolved && fileEntry.moduleResolved[binding.module];
+            let srcSymbol = null, srcRel = null;
+            if (resolvedRel) {
+                for (const [, fe2] of index.files) {
+                    if (fe2.relativePath === resolvedRel) {
+                        srcSymbol = fe2.symbols.find(s => s.name === exp.name && !s.className) || null;
+                        srcRel = fe2.relativePath;
+                        break;
+                    }
+                }
+            }
+            matchedNames.add(displayName);
+            results.push({
+                name: displayName,
+                ...(exp.alias && { sourceName: exp.name }),
+                type: srcSymbol ? srcSymbol.type : 'variable',
+                file: fileEntry.relativePath,
+                startLine: exp.line,
+                endLine: exp.line,
+                params: srcSymbol ? srcSymbol.params : undefined,
+                returnType: srcSymbol ? srcSymbol.returnType : null,
+                signature: srcSymbol ? index.formatSignature(srcSymbol)
+                    : `export ${exp.name}${exp.alias ? ' as ' + exp.alias : ''}`,
+                ...(srcRel && { reExportedFrom: srcRel })
+            });
+        }
     }
 
     // Python __all__ re-exports: names listed in __all__ that come from imports
@@ -399,21 +551,18 @@ function api(index, filePath, options = {}) {
         const exportedNames = new Set(fileEntry.exports);
 
         for (const symbol of fileEntry.symbols) {
-            const isExported = exportedNames.has(symbol.name) ||
-                (symbol.modifiers && symbol.modifiers.includes('export')) ||
-                (symbol.modifiers && symbol.modifiers.includes('public')) ||
-                (langTraits(fileEntry.language)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(symbol.name));
-
-            if (isExported) {
+            if (symbol.type === 'impl') continue;
+            if (symbolIsExported(symbol, fileEntry, exportedNames)) {
                 results.push({
                     name: symbol.name,
                     type: symbol.type,
                     file: fileEntry.relativePath,
                     startLine: symbol.startLine,
                     endLine: symbol.endLine,
+                    ...(symbol.className && { className: symbol.className }),
                     params: symbol.params,
                     returnType: symbol.returnType,
-                    signature: index.formatSignature(symbol)
+                    signature: formatExportSignature(index, symbol)
                 });
             }
         }
@@ -434,11 +583,52 @@ function api(index, filePath, options = {}) {
                         returnType: exp.typeAnnotation || null,
                         signature: sig
                     });
+                    matchedNames.add(exp.name);
+                }
+            }
+            // The fix #245 fileExports discipline, api side (fix #251 — the
+            // two commands diverged on the same file): consumers import the
+            // ALIAS, and clause-exported names with no indexed symbol
+            // (class/function expressions) are still API surface.
+            for (const exp of fileEntry.exportDetails) {
+                if (!exp || !exp.name || exp.module) continue;
+                if (exp.alias && exp.alias !== exp.name) {
+                    const entry = results.find(r =>
+                        r.file === fileEntry.relativePath && r.name === exp.name && !r.sourceName);
+                    if (entry) {
+                        entry.sourceName = exp.name;
+                        entry.name = exp.alias;
+                        if (entry.signature) {
+                            entry.signature = entry.signature.replace(exp.name, exp.alias);
+                        }
+                        matchedNames.add(exp.alias);
+                        continue;
+                    }
+                }
+                const shown = exp.alias || exp.name;
+                if (!matchedNames.has(shown) && !matchedNames.has(exp.name) &&
+                    exportedNames.has(exp.name)) {
+                    results.push({
+                        name: shown,
+                        ...(exp.alias && exp.alias !== exp.name && { sourceName: exp.name }),
+                        type: 'export',
+                        file: fileEntry.relativePath,
+                        startLine: exp.line || 1,
+                        endLine: exp.line || 1,
+                        params: undefined,
+                        returnType: null,
+                        signature: shown,
+                    });
+                    matchedNames.add(shown);
                 }
             }
         }
     }
 
+    // Rule 11: (file, line) ordering regardless of parse order — file mode
+    // used to emit symbols in extraction order (fix #251).
+    results.sort((a, b) => codeUnitCompare(a.file, b.file) ||
+        (a.startLine - b.startLine) || codeUnitCompare(a.name, b.name));
     return results;
 }
 
@@ -479,6 +669,9 @@ function graph(index, filePath, options = {}) {
         const visited = new Set();
         const nodes = [];
         const edges = [];
+        let truncated = false;
+
+        const cutNodes = [];
 
         const traverse = (file, depth) => {
             if (visited.has(file)) return;
@@ -488,8 +681,13 @@ function graph(index, filePath, options = {}) {
             const relPath = fileEntry ? fileEntry.relativePath : path.relative(index.root, file);
             nodes.push({ file, relativePath: relPath, depth });
 
-            // Stop traversal at max depth but still register the node above
-            if (depth >= maxDepth) return;
+            // Stop traversal at max depth but still register the node above.
+            // Edges from cut nodes are resolved in a post-pass (below) so the
+            // outcome never depends on visit order.
+            if (depth >= maxDepth) {
+                cutNodes.push(file);
+                return;
+            }
 
             const neighbors = dir === 'imports'
                 ? (index.importGraph.get(file) || new Set())
@@ -502,7 +700,26 @@ function graph(index, filePath, options = {}) {
         };
 
         traverse(targetPath, 0);
-        return { nodes, edges };
+
+        // Deterministic cut-frontier pass (fix #245): a cut node's edge to a
+        // node ALREADY in the result needs no deeper traversal — emit it
+        // (the diamond b→a edge used to vanish); only neighbors genuinely
+        // outside the result mark the graph depth-truncated. The in-traversal
+        // peek made both outcomes depend on import order.
+        for (const file of cutNodes) {
+            const neighbors = dir === 'imports'
+                ? (index.importGraph.get(file) || new Set())
+                : (index.exportGraph.get(file) || new Set());
+            for (const neighbor of neighbors) {
+                if (visited.has(neighbor)) {
+                    edges.push({ from: file, to: neighbor });
+                } else {
+                    truncated = true;
+                }
+            }
+        }
+
+        return { nodes, edges, truncated };
     };
 
     if (direction === 'both') {
@@ -513,6 +730,8 @@ function graph(index, filePath, options = {}) {
         return {
             root: targetPath,
             direction: 'both',
+            maxDepth,
+            depthTruncated: importsGraph.truncated || importersGraph.truncated,
             imports: { nodes: importsGraph.nodes, edges: importsGraph.edges },
             importers: { nodes: importersGraph.nodes, edges: importersGraph.edges },
             // Keep combined for backward compat
@@ -526,6 +745,8 @@ function graph(index, filePath, options = {}) {
     return {
         root: targetPath,
         direction,
+        maxDepth,
+        depthTruncated: subgraph.truncated,
         nodes: subgraph.nodes,
         edges: subgraph.edges
     };
@@ -608,7 +829,7 @@ function circularDeps(index, options = {}) {
             result = uniqueCycles.filter(c => c.files.some(f => f.includes(fileFilter)));
         }
 
-        result.sort((a, b) => a.length - b.length || a.files[0].localeCompare(b.files[0]));
+        result.sort((a, b) => a.length - b.length || codeUnitCompare(a.files[0], b.files[0]));
 
         // Count files that participate in import graph (have edges)
         let filesWithImports = 0;