ucn 5.2.2 → 5.3.1

package/cli/index.js

@@ -30,6 +30,16 @@ const { buildPublicParams, isPublicCommand } = require('../core/public-command')
 const { execute } = require('../core/execute');
 const { applyOutputBudget, MAX_OUTPUT_CHARS } = require('../core/output-budget');
 const { clearAllCaches } = require('../core/cache');
+const { commentLines } = require('../core/output/lines');
+
+// A downstream consumer such as head may finish before our write drains.
+// Handle the pipe closure without an unhandled Node error or bypassing cache
+// cleanup. Other write failures are real command errors.
+process.stdout.on('error', error => {
+    if (error.code === 'EPIPE') return;
+    process.stderr.write(`Error writing stdout: ${error.message}\n`);
+    process.exitCode = 2;
+});
 
 let activeCanonicalCommand = null;
 
@@ -315,6 +325,8 @@ function parseFlags(tokens) {
         functions: tokens.includes('--functions') || undefined,
         hot: tokens.includes('--hot') || undefined,
         diverse: tokens.includes('--diverse') || undefined,
+        raw: tokens.includes('--raw') || undefined,
+        lines: tokens.includes('--lines') || undefined,
         git: tokens.includes('--git') || undefined,
         className: getValueFlag('--class-name'),
         // Explicit line pin (fix #249: our own disambiguation notes advertise
@@ -396,7 +408,7 @@ if (unknownFlags.length > 0) {
     emitCliError(
         `Unknown flag(s): ${unknownFlags.join(', ')}. Use --help to see available flags.`,
     );
-    process.exit(1);
+    process.exit(flags.lines || flags.raw ? 2 : 1);
 }
 
 // Validate numeric flag values up front so bad input fails before we build
@@ -407,7 +419,7 @@ try {
 } catch (e) {
     if (e instanceof FlagValidationError) {
         emitCliError(e.message);
-        process.exit(1);
+        process.exit(flags.lines || flags.raw ? 2 : 1);
     }
     throw e;
 }
@@ -456,6 +468,16 @@ function formatCliText(command, result, params, execution, displayFlags) {
         ...execution,
         surface: 'cli',
     });
+    // --lines / --raw are pipe surfaces: records are compact, a truncated
+    // function body is worse than a long one, and an empty answer must stay
+    // empty (grep prints nothing and exits 1). An explicit --max-chars acts
+    // as a fail-before-output guard, never a lossy source/record truncation.
+    if (params?.lines || params?.raw) {
+        if (displayFlags?.maxChars && text.length > displayFlags.maxChars) {
+            fail(`Output exceeds --max-chars=${displayFlags.maxChars}; shell output cannot be truncated. Narrow the query, use --limit/--max-lines, or omit --max-chars.`);
+        }
+        return text;
+    }
     return applyOutputBudget(text, {
         command,
         maxChars: displayFlags?.maxChars,
@@ -465,6 +487,36 @@ function formatCliText(command, result, params, execution, displayFlags) {
     }).text;
 }
 
+/**
+ * Print a formatted answer the way the mode asks for it (fix #341).
+ * --lines: `path:line:text` records on stdout, `# ` comment lines (ACCOUNT,
+ * notes) on stderr, exit 1 when nothing matched — grep's own contract.
+ * --raw: the text verbatim with exactly one trailing newline.
+ */
+function emitCliText(text, params, json, note) {
+    if (!json && params?.lines) {
+        const records = [];
+        const comments = [];
+        for (const line of String(text).split('\n')) {
+            if (line === '') continue;
+            (line.startsWith('# ') ? comments : records).push(line);
+        }
+        if (records.length > 0) process.stdout.write(records.join('\n') + '\n');
+        if (comments.length > 0) process.stderr.write(comments.join('\n') + '\n');
+        if (records.length === 0) process.exitCode = Math.max(process.exitCode || 0, 1);
+        return;
+    }
+    if (!json && params?.raw) {
+        const body = String(text);
+        process.stdout.write(body.endsWith('\n') ? body : body + '\n');
+        // Code lines are never reinterpreted (a Python comment starts with
+        // "# " too), so the note travels on its own channel.
+        if (note) process.stderr.write(commentLines(formatSurfaceMessage(note, 'cli')).join('\n') + '\n');
+        return;
+    }
+    console.log(text);
+}
+
 // ============================================================================
 // MAIN
 // ============================================================================
@@ -555,7 +607,7 @@ function main() {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = 1;
+        process.exitCode = flags.lines || flags.raw ? 2 : 1;
     }
 }
 
@@ -665,11 +717,11 @@ function runFileCommand(filePath, command, arg) {
     const execution = execute(index, canonical, params);
     const { ok, result, error } = execution;
     if (!ok) fail(formatSurfaceMessage(error, 'cli'));
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, result, params, {
             ...execution, surface: 'cli',
         })
-        : formatCliText(canonical, result, params, execution, scopedFlags));
+        : formatCliText(canonical, result, params, execution, scopedFlags), params, flags.json, execution.note);
 }
 
 // ============================================================================
@@ -737,11 +789,12 @@ function runProjectCommand(rootDir, command, arg) {
     if (!publicExecution.ok) {
         fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
             ...publicExecution, surface: 'cli',
         })
-        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags),
+    publicParams, flags.json, publicExecution.note);
     // A gate that could not run (check outside git / bad base ref) must not
     // exit 0 — CI gating on the exit code would read "could not run" as "passed".
     process.exitCode = Math.max(process.exitCode || 0,
@@ -750,7 +803,7 @@ function runProjectCommand(rootDir, command, arg) {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = 1;
+        process.exitCode = flags.lines || flags.raw ? 2 : 1;
     } finally {
         // Save cache after command execution so callsCache populated
         // by findCallers/findCallees gets persisted to disk.
@@ -796,11 +849,12 @@ function runGlobCommand(pattern, command, arg) {
     if (!publicExecution.ok) {
         fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
             ...publicExecution, surface: 'cli',
         })
-        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags),
+    publicParams, flags.json, publicExecution.note);
     process.exitCode = Math.max(process.exitCode || 0,
         resultExitCode(canonical, publicExecution.result));
 }
@@ -860,6 +914,13 @@ Common flags:
   --range=N-M (source with --file=PATH)
   --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
   --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
+  --lines  find/usages/search/show/impact: grep -n shape, one path:line:text
+           record per line (tags after a tab: # unverified: <reason>, # import,
+           # callee); accounting and notes go to stderr as "# " lines; exit 1
+           when nothing matched; exit 2 on errors. No default result cap.
+           show defaults to callers; --sections=callers,callees selects bands.
+  --raw    source: full code, no header or gutter (including large classes).
+           Shell modes fail before output if an explicit --max-chars is exceeded.
   Cache: per-user by default; set UCN_CACHE_DIR to override the cache root.
 
 Accepted flags by command:

package/core/analysis.js

@@ -980,6 +980,113 @@ function related(index, name, options = {}) {
  * @param {object} options - { file, className, exclude, top }
  * @returns {object|null}
  */
+// Kinds whose dependents are annotation/reference sites rather than calls.
+// Classes and structs stay out: `new X()` / `X{}` are call-shaped and already
+// flow through the caller sweep.
+const TYPE_REFERENCE_KINDS = new Set(['type', 'interface', 'enum', 'trait', 'record']);
+
+/**
+ * fix #345: tiered annotation-site band for a type-kind definition.
+ * Confirmed needs identity evidence: same file as the definition, or an
+ * import binding of the name in the referencing file that reaches the
+ * definition's file (the #215/#217 scope discipline). Anything else is
+ * VISIBLE unverified with a reason. A same-name definition elsewhere is
+ * excluded as other-target. Spelling alone never confirms.
+ */
+function findTypeReferences(index, name, def, options = {}) {
+    if (!def || !TYPE_REFERENCE_KINDS.has(def.type)) return null;
+    const { usages } = require('./search');
+    const { _importReaches, _sameNominalPackageDir } = require('./callers');
+    const records = usages(index, name, {
+        includeTests: true, codeOnly: true, exclude: options.exclude,
+    });
+    const targetFiles = new Set([def.file]);
+    const sameNameDefs = (index.symbols.get(name) || []).filter(d => d !== def);
+    const confirmed = [];
+    const unverified = [];
+    const excluded = [];
+    for (const u of (Array.isArray(records) ? records : records?.usages || [])) {
+        if (u.isDefinition || u.usageType !== 'reference') continue;
+        const site = {
+            file: u.relativePath, line: u.line,
+            expression: (u.content || '').trim(),
+        };
+        // A same-name type defined in the referencing file owns that file's
+        // bare references (the #215 scope rule): excluded, never confirmed.
+        if (u.file !== def.file && sameNameDefs.some(d => d.file === u.file && TYPE_REFERENCE_KINDS.has(d.type))) {
+            excluded.push({ ...site, reason: 'other-definition' });
+            continue;
+        }
+        if (sameNameDefs.some(d => d.file === u.file && (d.nameLine || d.startLine) === u.line)) {
+            excluded.push({ ...site, reason: 'other-definition' });
+            continue;
+        }
+        if (u.file === def.file) {
+            confirmed.push({ ...site, evidence: 'same-file' });
+            continue;
+        }
+        const fileEntry = index.files.get(u.file);
+        // Directory-scoped packages (Go) and Java packages see sibling files'
+        // types without an import; a same-name def in another package would
+        // have been excluded above only if it shared the line, so require the
+        // pinned def to be the package's own.
+        const packageScoped = fileEntry && (
+            (langTraits(fileEntry.language).packageScope === 'directory' &&
+                path.dirname(u.file) === path.dirname(def.file)) ||
+            (fileEntry.language === 'java' &&
+                _sameNominalPackageDir(path.dirname(def.file), path.dirname(u.file), 'java')));
+        if (packageScoped) {
+            const foreign = sameNameDefs.some(d => TYPE_REFERENCE_KINDS.has(d.type) &&
+                path.dirname(d.file) === path.dirname(u.file));
+            if (foreign) unverified.push({ ...site, reason: 'same-package-ambiguous' });
+            else confirmed.push({ ...site, evidence: 'package-scope' });
+            continue;
+        }
+        const bindings = (fileEntry?.importBindings || []).filter(b =>
+            b.name === name || b.alias === name);
+        if (bindings.length > 0) {
+            const reaches = bindings.some(b => {
+                const rel = fileEntry.moduleResolved && fileEntry.moduleResolved[b.module];
+                return rel && _importReaches(index, path.join(index.root, rel), targetFiles);
+            });
+            if (reaches) { confirmed.push({ ...site, evidence: 'import' }); continue; }
+            const otherProject = bindings.some(b =>
+                fileEntry.moduleResolved && fileEntry.moduleResolved[b.module]);
+            if (otherProject) { excluded.push({ ...site, reason: 'other-definition-import' }); continue; }
+            unverified.push({ ...site, reason: 'import-unresolved' });
+            continue;
+        }
+        if (fileEntry?.importNames?.includes('*')) {
+            unverified.push({ ...site, reason: 'star-import' });
+            continue;
+        }
+        unverified.push({ ...site, reason: 'no-import-link' });
+    }
+    if (confirmed.length === 0 && unverified.length === 0 && excluded.length === 0) {
+        return { owner: def.type, confirmedCount: 0, unverifiedCount: 0, totalCandidates: 0,
+            byFile: [], unverifiedSites: [], excluded: { total: 0, byReason: {} } };
+    }
+    const bySite = (a, b) => a.file !== b.file ? codeUnitCompare(a.file, b.file) : a.line - b.line;
+    confirmed.sort(bySite); unverified.sort(bySite);
+    const byFile = new Map();
+    for (const site of confirmed) {
+        if (!byFile.has(site.file)) byFile.set(site.file, []);
+        byFile.get(site.file).push(site);
+    }
+    return {
+        owner: def.type,
+        confirmedCount: confirmed.length,
+        unverifiedCount: unverified.length,
+        totalCandidates: confirmed.length + unverified.length,
+        byFile: [...byFile.entries()].map(([file, sites]) => ({ file, count: sites.length, sites })),
+        unverifiedSites: unverified,
+        excluded: {
+            total: excluded.length,
+            byReason: excluded.reduce((out, s) => { out[s.reason] = (out[s.reason] || 0) + 1; return out; }, {}),
+        },
+    };
+}
+
 function impact(index, name, options = {}) {
     index._beginOp();
     try {
@@ -1270,6 +1377,13 @@ function impact(index, name, options = {}) {
         };
     }
 
+    // fix #345: a type/interface/enum/trait is consumed through annotations,
+    // not calls. Those sites were counted in the ACCOUNT as references and
+    // listed nowhere, so the headline said 0 for a type with dozens of
+    // dependents. Same design as the accessor band: a separate band, never
+    // fake caller edges (the caller oracle and the account stay call-shaped).
+    let typeReferences = findTypeReferences(index, name, def, options);
+
     // Apply top limit if specified (limits total call sites shown)
     const totalBeforeLimit = filteredSites.length;
     if (options.top && options.top > 0 && filteredSites.length > options.top) {
@@ -1315,6 +1429,8 @@ function impact(index, name, options = {}) {
         ...Array.from(byFile.keys()),
         ...(propertyAccesses?.byFile || []).map(group => group.file),
         ...(propertyAccesses?.unverifiedSites || []).map(site => site.file),
+        ...(typeReferences?.byFile || []).map(group => group.file),
+        ...(typeReferences?.unverifiedSites || []).map(site => site.file),
     ]);
 
     return {
@@ -1332,6 +1448,11 @@ function impact(index, name, options = {}) {
             totalDependencySites: totalBeforeLimit + propertyAccesses.confirmedCount,
             affectedFiles: affectedFiles.size,
         }),
+        ...(typeReferences && {
+            typeReferences,
+            totalDependencySites: totalBeforeLimit + typeReferences.confirmedCount,
+            affectedFiles: affectedFiles.size,
+        }),
         account: impactAccount,
         hasEntrypoints: !!impactReachable && impactReachable.size > 0,
         callerHistogram,
@@ -1876,19 +1997,6 @@ function diffImpact(index, options = {}) {
         }
     }
 
-    if (!diffText || !diffText.trim()) {
-        return {
-            base: staged ? '(staged)' : base,
-            changedPaths: 0,
-            nonSourcePaths: 0,
-            functions: [],
-            moduleLevelChanges: [],
-            newFunctions: [],
-            deletedFunctions: [],
-            summary: { modifiedFunctions: 0, deletedFunctions: 0, newFunctions: 0, totalCallSites: 0, unverifiedCallSites: 0, affectedFiles: 0 }
-        };
-    }
-
     // Diff paths are git-root-relative. Resolve to index.root for file lookup.
     // Normalize both through realpath to handle macOS /var → /private/var symlinks.
     let realGitRoot, realProjectRoot;
@@ -1908,6 +2016,58 @@ function diffImpact(index, options = {}) {
         changes.push({ ...c, gitRelativePath: c.relativePath, filePath: path.join(index.root, localRel), relativePath: localRel });
     }
 
+    // fix #346: untracked files are new work too. `git diff <base>` only
+    // sees tracked paths, so a session's brand-new modules were invisible to
+    // the pre-commit gate until `git add -N` — a silent pass on exactly the
+    // code that has never been checked. Indexed, gitignore-respecting
+    // untracked source files join the working-tree diff as whole-file
+    // additions (staged mode keeps its index-only meaning).
+    let untrackedPaths = 0;
+    if (!staged) {
+        const lsArgs = ['ls-files', '--others', '--exclude-standard', '-z'];
+        if (file) lsArgs.push('--', file);
+        let untrackedText = '';
+        try {
+            untrackedText = execFileSync('git', lsArgs, {
+                cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        } catch (_) { untrackedText = ''; }
+        const known = new Set(changes.map(c => c.relativePath));
+        for (const localRel of untrackedText.split('\0').filter(Boolean).sort(codeUnitCompare)) {
+            if (known.has(localRel)) continue;
+            const filePath = path.join(index.root, localRel);
+            const fileEntry = index.files.get(filePath);
+            if (!fileEntry || !detectLanguage(filePath)) continue;
+            let lineCount = fileEntry.lines;
+            if (!Number.isFinite(lineCount)) {
+                try { lineCount = fs.readFileSync(filePath, 'utf-8').split('\n').length; } catch (_) { continue; }
+            }
+            const addedLines = [];
+            for (let i = 1; i <= lineCount; i++) addedLines.push(i);
+            untrackedPaths++;
+            changes.push({
+                filePath, relativePath: localRel,
+                gitRelativePath: projectPrefix ? `${projectPrefix}/${localRel}` : localRel,
+                addedLines, deletedLines: [], untracked: true,
+            });
+        }
+    }
+
+    if (changes.length === 0) {
+        return {
+            base: staged ? '(staged)' : base,
+            changedPaths: 0,
+            nonSourcePaths: 0,
+            untrackedPaths: 0,
+            functions: [],
+            moduleLevelChanges: [],
+            newFunctions: [],
+            deletedFunctions: [],
+            summary: { modifiedFunctions: 0, deletedFunctions: 0, newFunctions: 0, totalCallSites: 0, unverifiedCallSites: 0, affectedFiles: 0 }
+        };
+    }
+
     const functions = [];
     const moduleLevelChanges = [];
     const newFunctions = [];
@@ -2111,7 +2271,10 @@ function diffImpact(index, options = {}) {
             const { symbol, addedLines } = data;
             const identityKey = `${symbol.name}\0${symbol.className || ''}`;
             let isNew;
-            if (oldSymbolIdentities !== null) {
+            if (change.untracked) {
+                // fix #346: nothing in an untracked file existed at the base.
+                isNew = true;
+            } else if (oldSymbolIdentities !== null) {
                 isNew = !oldSymbolIdentities.has(identityKey);
             } else {
                 // Fallback: 80% of body lines added and no deletions hit this symbol.
@@ -2291,6 +2454,7 @@ function diffImpact(index, options = {}) {
         base: staged ? '(staged)' : base,
         changedPaths: changes.length,
         nonSourcePaths,
+        untrackedPaths,
         functions,
         moduleLevelChanges,
         newFunctions,

package/core/cache.js

@@ -690,7 +690,14 @@ function clearAllCaches() {
 // types for values bound from declared map, slice, and array indexes.
 // v208 (fix #335): Go indexed-value calls preserve receiver-root/field
 // provenance so sibling-file container declarations resolve query-time.
-const CACHE_FORMAT_VERSION = 208;
+// v210 (fixes #337-#339): importDetails persisted for every language (was Python-only),
+// require(path.join(__dirname, ...)) composes to a static relative specifier,
+// and import records carry deferredReason (function-local / type-checking / type-only).
+// v211: path-utility composition requires unshadowed binding evidence; mixed
+// default/type imports and inline type re-exports preserve execution timing.
+// Python TYPE_CHECKING guards require typing ownership and no rebinding.
+// v212 (fix #342): extendsGraph/extendedByGraph no longer persisted (rebuilt on load).
+const CACHE_FORMAT_VERSION = 212;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**
@@ -901,9 +908,13 @@ function saveCache(index, cachePath) {
         symbols: strippedSymbols,
         importGraph: relGraph(index.importGraph),
         exportGraph: relGraph(index.exportGraph),
-        // extendsGraph/extendedByGraph use class names as keys (not file paths)
-        extendsGraph: Array.from(index.extendsGraph.entries()),
-        extendedByGraph: Array.from(index.extendedByGraph.entries()),
+        // extendsGraph/extendedByGraph are NOT persisted (fix #342): their
+        // entries carry absolute file paths in the build-time spelling, and
+        // the cache key is realpath-normalized — a root reached through a
+        // symlink (/var → /private/var on macOS) loaded a graph whose files
+        // matched nothing, so an overriding Go embed read as a non-overriding
+        // subclass and confirmed two false callers. loadCache rebuilds both
+        // from the rehydrated symbols (8ms on 1037 files).
         failedFiles: index.failedFiles
             ? Array.from(index.failedFiles).map(f => path.relative(root, f))
             : [],
@@ -1116,13 +1127,8 @@ function loadCache(index, cachePath) {
         index.buildTime = cacheData.buildTime;
 
         // Restore optional graphs if present
-        // extendsGraph/extendedByGraph use class names as keys (not file paths)
-        if (Array.isArray(cacheData.extendsGraph)) {
-            index.extendsGraph = new Map(cacheData.extendsGraph);
-        }
-        if (Array.isArray(cacheData.extendedByGraph)) {
-            index.extendedByGraph = new Map(cacheData.extendedByGraph);
-        }
+        // extendsGraph/extendedByGraph are derived below from the rehydrated
+        // symbols (fix #342) — never read from the payload.
 
         // Prepare lazy calls cache loading — load manifest but defer shard parsing.
         // Shards are loaded on first getCachedCalls access via ensureCallsCacheLoaded().
@@ -1194,13 +1200,16 @@ function loadCache(index, cachePath) {
             }
         }
 
-        // Only rebuild graphs if config changed (e.g., aliases modified)
+        // Only rebuild the import graph if config changed (e.g., aliases
+        // modified); it is persisted with relative paths. The inheritance
+        // graph is always derived from the rehydrated symbols (fix #342) so
+        // its file paths agree with index.root whatever spelling built it.
         const currentConfigHash = crypto.createHash('md5')
             .update(JSON.stringify(index.config || {})).digest('hex');
         if (currentConfigHash !== cacheData.configHash) {
             index.buildImportGraph();
-            index.buildInheritanceGraph();
         }
+        index.buildInheritanceGraph();
 
         loadUsageCache(index, cacheFile);