ucn 5.5.3 → 5.6.1

package/core/project.js

@@ -9,11 +9,9 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
+const { paramDefault } = require('./registry');
 const { UcnError } = require('./errors');
-const {
-    expandGlob, findProjectRoot, detectProjectPattern, isTestFile,
-    parseGitignore, gitTrackedPaths, gitListing, DEFAULT_IGNORES, compareNames, classifyUnsupportedSourceFile,
-} = require('./discovery');
+const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, gitTrackedPaths, gitListing, compareNames, classifyUnsupportedSourceFile, projectDiscoveryOptions } = require('./discovery');
 const { cleanHtmlScriptTags } = require('./parser');
 const { detectLanguage, getParser, getLanguageAdapter, safeParse, langTraits, PARSE_OPTIONS } = require('../languages');
 const { validateFileIR } = require('./ir');
@@ -102,8 +100,11 @@ class ProjectIndex {
      * Create a new ProjectIndex
      * @param {string} rootDir - Project root directory
      */
-    constructor(rootDir) {
-        this.root = findProjectRoot(rootDir);
+    constructor(rootDir, options = {}) {
+        // `exactRoot`: the directory IS the project root. A tree exported
+        // from the git index has no `.git` to stop the walk toward a marker,
+        // and must not adopt a directory above itself.
+        this.root = options.exactRoot ? path.resolve(rootDir) : findProjectRoot(rootDir);
         this.files = new Map();           // path -> FileEntry
         this.symbols = new Map();         // name -> SymbolEntry[]
         this.importGraph = new Map();     // file -> [imported files]
@@ -128,6 +129,7 @@ class ProjectIndex {
         this.macroExpansionDirty = false;  // persisted C/C++ macro-expansion records (core/macro-expansion.js)
         this._macroExpansionPersisted = null;
         this.failedFiles = new Set();    // files that failed to index (e.g. large minified bundles)
+        this._failedFileStats = new Map(); // failed file -> { size, mtimeMs } AT the failure (see _noteFailedFile)
         this.unsupportedFiles = [];      // common source files skipped by the parser registry
         this.discoveryIssues = [];       // explicit reasons the index may be partial
         this._opContentCache = null;     // per-operation file content cache (Map<filePath, string>)
@@ -151,9 +153,15 @@ class ProjectIndex {
         this._usageResultCache = new Map();
         this._usageResultCacheWeight = 0;
         this.usageCacheDirty = false;
+        // HOT rankings already computed for this index state, by request
+        // (core/hot-summary.js); stored beside the index when dirty.
+        this._hotSummaries = null;
+        this._hotSummarySavedGeneration = null;
+        this.hotSummaryDirty = false;
         // Exact text-ground sets are likewise immutable for one built index.
         // The cache is cleared at every build and bounded in account.js.
         this._groundSetCache = new Map();
+        this._sourceUniverse = null; // non-indexed source classification (core/source-universe.js)
         this._groundSetCacheLines = 0;
         // Bounded cross-operation memo for immutable name-level export
         // ownership. Agent workflows ask show/impact/tests about related
@@ -545,6 +553,29 @@ class ProjectIndex {
         }
     }
 
+    /**
+     * Record a file the parser could not ingest, with what it looked like
+     * when it failed. A failed file is in no index, so its size and mtime
+     * are the only way to tell that it changed and deserves another try;
+     * they must be taken here, at the failure, never at the first later
+     * check (by then a repaired file already looks "unchanged").
+     */
+    _noteFailedFile(filePath) {
+        this.failedFiles.add(filePath);
+        if (!this._failedFileStats) this._failedFileStats = new Map();
+        try {
+            const stat = fs.statSync(filePath);
+            this._failedFileStats.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs });
+        } catch (_) {
+            this._failedFileStats.delete(filePath);
+        }
+    }
+
+    _clearFailedFile(filePath) {
+        this.failedFiles.delete(filePath);
+        if (this._failedFileStats) this._failedFileStats.delete(filePath);
+    }
+
     /**
      * Load .ucn.json config if present (data-only, no code execution)
      */
@@ -574,6 +605,7 @@ class ProjectIndex {
         // a text-universe answer across that boundary. Hash-keyed usage
         // results remain safe and useful for unchanged files.
         this._groundSetCache = new Map();
+        this._sourceUniverse = null; // non-indexed source classification (core/source-universe.js)
         this._groundSetCacheLines = 0;
         this._nameBindingReachCache = new Map();
         this._returnTypeFlowCache = new Map();
@@ -630,17 +662,20 @@ class ProjectIndex {
                 pattern = detectProjectPattern(this.root);
             }
 
-            const globOpts = {
-                root: this.root,
-                maxFiles: options.maxFiles || this.config.maxFiles || 50000,
-                maxDepth: options.maxDepth ?? this.config.maxDepth,
-                maxFileSize: options.maxFileSize ?? this.config.maxFileSize,
+            // Shared with the staleness walk (cache.js): both must read the
+            // project's configuration the same way.
+            const globOpts = projectDiscoveryOptions(this.root, this.config, {
+                maxFiles: options.maxFiles,
+                maxDepth: options.maxDepth,
+                maxFileSize: options.maxFileSize,
                 followSymlinks: options.followSymlinks,
                 includeBundled: this.includeBundled,
-            };
+            });
 
             // Merge .gitignore and .ucn.json exclude into file discovery
-            const listing = gitListing(this.root);
+            // A snapshot exported from the git index is not a repository:
+            // its tracked inventory and ignore files come with it.
+            const listing = options.gitListing !== undefined ? options.gitListing : gitListing(this.root);
             const gitignoreRules = parseGitignore(this.root, listing);
             globOpts.gitignoreRules = gitignoreRules;
             globOpts.trackedPaths = gitTrackedPaths(this.root, listing);
@@ -654,13 +689,6 @@ class ProjectIndex {
                     detail: `${listing.failure.detail}; tracked files that match .gitignore rules could not be identified and are not indexed`,
                 });
             }
-            const configExclude = Array.isArray(this.config.exclude)
-                ? this.config.exclude
-                : (this.config.exclude ? [String(this.config.exclude)] : []);
-            if (configExclude.length > 0) {
-                globOpts.ignores = [...DEFAULT_IGNORES, ...configExclude];
-            }
-            globOpts.disclosureIgnores = configExclude;
             globOpts.onDiscoveryIssue = recordDiscoveryIssue;
 
             if (implicitProjectDiscovery) {
@@ -683,7 +711,7 @@ class ProjectIndex {
         }
 
         // Track if files were truncated by maxFiles limit
-        const maxFiles = options.maxFiles || this.config.maxFiles || 50000;
+        const maxFiles = options.maxFiles || this.config.maxFiles || paramDefault('maxFiles');
         const maxFileIssues = this.discoveryIssues.filter(issue => issue.reason === 'max-files');
         if (!Array.isArray(pattern) && maxFileIssues.length > 0) {
             this.truncated = { indexed: files.length, maxFiles, skipped: maxFileIssues.length };
@@ -727,6 +755,7 @@ class ProjectIndex {
         this._callNameCache = null;
         this._callsGenerationKey = null;
         this._completenessCache = null;
+        require('./hot-summary').reset(this);
         this._attrTypeCache = null;
         this._computedDispatchBlindspots = null;
         this._reflectionPatternIndex = null;
@@ -743,6 +772,7 @@ class ProjectIndex {
         let indexed = 0;
         let changed = 0;
         if (!this.failedFiles) this.failedFiles = new Set();
+        if (!this._failedFileStats) this._failedFileStats = new Map();
 
         // Try parallel build for large projects
         const workersSetting = options.workers;
@@ -862,9 +892,9 @@ class ProjectIndex {
                     try {
                         if (this.indexFile(file)) changed++;
                         indexed++;
-                        this.failedFiles.delete(file); // Succeeded now, remove from failed
+                        this._clearFailedFile(file); // Succeeded now, remove from failed
                     } catch (e) {
-                        this.failedFiles.add(file); // Track files that fail to index
+                        this._noteFailedFile(file); // Track files that fail to index
                         if (!quiet) {
                             console.error(`  Warning: Could not index ${file}: ${e.message}`);
                         }
@@ -1031,6 +1061,7 @@ class ProjectIndex {
         // These query caches depend on project symbols and include closure.
         // A changed file can alter either even before a full rebuild reaches
         // its graph phase, so no prior call-identity verdict may survive.
+        require('./hot-summary').reset(this);
         this._implicitConversionOwners = null;
         this._constructionAliases = null;
         this._cppScope = null;
@@ -1126,6 +1157,52 @@ class ProjectIndex {
         return true;
     }
 
+    /**
+     * Where a file of this index lives in the git repository it describes.
+     * The same path, except for a snapshot exported from the git index
+     * (core/snapshot.js), whose files stand in for the repository's.
+     */
+    repoPathOf(filePath) {
+        if (!this.repoRoot || !filePath) return filePath;
+        const relative = path.relative(this.root, filePath);
+        return relative.startsWith('..') ? filePath : path.join(this.repoRoot, relative);
+    }
+
+    /**
+     * The file entry another revision of a file would have: its symbols,
+     * exports and bindings as the index records them, built from `content`
+     * and attached to nothing. The index is not changed. Used to read a
+     * base revision (a diff's old side) with the same eyes as the current
+     * one. Returns null for a file no language claims or a parse the
+     * adapter rejects.
+     */
+    fileEntryForContent(filePath, content) {
+        const language = detectLanguage(filePath, this.root);
+        if (!language || content == null) return null;
+        try {
+            const adapter = getLanguageAdapter(language);
+            const parser = getParser(language);
+            const externalMacros = this._macroDictionary
+                ? require('./external-macros').contextFor(this._macroDictionary, language) : null;
+            const ir = adapter.analyze(content, parser, filePath,
+                externalMacros ? { externalMacros } : undefined);
+            if (validateFileIR(ir).length > 0) return null;
+            const fileEntry = createFileEntryFromIR({
+                ir,
+                filePath,
+                relativePath: path.relative(this.root, filePath),
+                hash: null,
+                mtime: 0,
+                size: Buffer.byteLength(content),
+                lineCount: content.length === 0 ? 0 : content.split('\n').length,
+            });
+            populateFileEntryFromIR(fileEntry, ir, null);
+            return fileEntry;
+        } catch (_) {
+            return null;
+        }
+    }
+
     /**
      * Remove a file's symbols from the global map
      */
@@ -1133,6 +1210,7 @@ class ProjectIndex {
         const existing = this.files.get(filePath);
         if (!existing) return;
 
+        require('./hot-summary').reset(this);
         this._implicitConversionOwners = null;
         this._constructionAliases = null;
         this._cppScope = null;
@@ -3063,6 +3141,11 @@ class ProjectIndex {
         return indexCache.saveUsageCache(this, cachePath);
     }
 
+    /** Persist the HOT rankings computed for the saved index state. */
+    saveHotSummaries(cachePath = undefined) {
+        return require('./hot-summary').save(this, cachePath);
+    }
+
     /** Return this project's default per-user cache file path. */
     getCachePath() { return indexCache.getProjectCachePath(this.root); }
 

package/core/provenance-type.js

@@ -185,7 +185,11 @@ function constructionDenotes(index, resolver, query, definition, seen = new Set(
     const visited = new Set(seen).add(key);
     const traits = lazyLanguagesModule().langTraits(entry.language);
     if (query.localShadow && !localConstructionBinding(index, query, definition, traits, entry.language)) return false;
-    if (traits.constructorInheritance?.order === 'single' && definition.decorators?.length) return false;
+    // A decorated class may be replaced by its decorator: no proof that its
+    // constructor runs. Which class the name denotes (`identity`) is the
+    // declaration all the same, as the language's own typing reads it.
+    if (!query.identity && traits.constructorInheritance?.order === 'single' && definition.decorators?.length) return false;
+    const identity = query.identity ? { identity: true } : null;
     if (traits.functionalTypeConstruction) {
         const classes = cppConstructionClasses(index, query, resolver);
         return classes.length > 0 && classes.every(def =>
@@ -228,7 +232,7 @@ function constructionDenotes(index, resolver, query, definition, seen = new Set(
         const bindings = (entry.importBindings || []).filter(b => (b.alias || b.name) === qualifier);
         if (bindings.length !== 1) return false;
         const target = moduleFile(`${bindings[0].module}.${bindings[0].name}`) || moduleFile(bindings[0].module);
-        return !!target && constructionDenotes(index, resolver, { file: target, line: 1, name }, definition, visited);
+        return !!target && constructionDenotes(index, resolver, { file: target, line: 1, name, ...identity }, definition, visited);
     }
     const aliases = (entry.moduleValueAliases || []).filter(alias => alias.name === name);
     if (aliases.length) {
@@ -238,11 +242,11 @@ function constructionDenotes(index, resolver, query, definition, seen = new Set(
                 if (alternative.target) {
                     const parts = alternative.target.split('.'), targetName = parts.pop();
                     return constructionDenotes(index, resolver, { file, line: alias.line || line,
-                        name: targetName, qualifier: parts.join('.') || null }, definition, visited);
+                        name: targetName, qualifier: parts.join('.') || null, ...identity }, definition, visited);
                 }
                 const target = moduleFile(alternative.module);
                 return !!target && !!alternative.imported && constructionDenotes(index, resolver,
-                    { file: target, line: 1, name: alternative.imported }, definition, visited);
+                    { file: target, line: 1, name: alternative.imported, ...identity }, definition, visited);
             });
         });
     }
@@ -252,13 +256,16 @@ function constructionDenotes(index, resolver, query, definition, seen = new Set(
             !def.lexicalScopeStartLine && !['class', 'struct', 'interface', 'type'].includes(def.type));
         return !shadows.length && !(entry.moduleAssignedNames || []).includes(name);
     }
+    // A name the module assigns, or a function writes through its module
+    // binding, does not hold its import's value at every use.
+    if ((entry.moduleAssignedNames || []).includes(name)) return false;
     const links = [...(entry.importBindings || []).filter(b => (b.alias || b.name) === name &&
         b.name !== '*' && b.kind !== 'namespace'), ...(entry.exportDetails || []).filter(e =>
         e.type === 're-export' && (e.alias || e.name) === name && e.source)];
     if (links.length !== 1) return false;
     const target = moduleFile(links[0].module || links[0].source);
     return !!target && constructionDenotes(index, resolver, { file: target, line: 1,
-        name: links[0].name }, definition, visited);
+        name: links[0].name, ...identity }, definition, visited);
 }
 
 // A construction through a method's own receiver (fix #434): the class

package/core/public-command.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { CANONICAL_COMMANDS } = require('./registry');
+const { CANONICAL_COMMANDS, GLOBAL_PARAMS } = require('./registry');
 
 const NAME_COMMANDS = new Set(['show', 'find', 'usages', 'trace', 'tests', 'plan']);
 
@@ -34,14 +34,16 @@ function sourceRangeTarget(params) {
 /** Build normalized execute() params from the shared CLI-style positional arg. */
 function buildPublicParams(command, arg, params = {}) {
     const clean = { ...params };
-    if (clean.top === 0 && params.topRaw == null) delete clean.top;
-    if (clean.maxLines == null) delete clean.maxLines;
-    // Surface-only values never belong in execute params.
-    for (const key of ['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'includeBundled', 'interactive',
-        'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'maxChars', 'maxCharsRaw',
-        'depthRaw', 'contextRaw', 'workersRaw',
-        '_fileFromFileMode']) delete clean[key];
+    // Process flags and the build/transport parameters every command accepts
+    // never belong in execute params: the surface applies them itself.
+    for (const key of ['json', 'quiet', 'cache', 'clearCache', 'interactive', 'workers', '_fileFromFileMode',
+        ...GLOBAL_PARAMS]) delete clean[key];
 
+    return withoutUnset(subjectParams(command, arg, clean));
+}
+
+/** The params with the positional argument placed as the command's subject. */
+function subjectParams(command, arg, clean) {
     if (NAME_COMMANDS.has(command)) return { ...clean, name: arg || clean.name };
     switch (command) {
         case 'search': return { ...clean, term: arg || clean.term };
@@ -58,8 +60,32 @@ function buildPublicParams(command, arg, params = {}) {
     }
 }
 
+/** A parameter that was not given has no key: the same object MCP arguments make. */
+function withoutUnset(params) {
+    for (const key of Object.keys(params)) {
+        if (params[key] === undefined) delete params[key];
+    }
+    return params;
+}
+
+/**
+ * What to say about a parameter a command accepts and that changes nothing,
+ * or less than its name suggests, there. One text for every surface, in CLI
+ * spelling: the surface renders it with formatSurfaceMessage.
+ */
+function noOpNotes(command, params = {}) {
+    if (!params.includeMethods) return [];
+    if (['impact', 'trace', 'tests', 'check'].includes(command)) {
+        return [`--include-methods has no effect on '${command}' — method calls are always tiered by receiver evidence.`];
+    }
+    if (command === 'show') {
+        return [`--include-methods on '${command}' affects only method-callee display for standalone-function targets — caller tiers are always evidence-based, and method targets analyze method calls by default.`];
+    }
+    return [];
+}
+
 function isPublicCommand(command) {
     return CANONICAL_COMMANDS.includes(command);
 }
 
-module.exports = { buildPublicParams, isPublicCommand, parseSourceTarget, sourceRangeTarget };
+module.exports = { buildPublicParams, isPublicCommand, noOpNotes, parseSourceTarget, sourceRangeTarget };