ucn 5.3.0 → 5.3.2

package/.claude/skills/ucn/SKILL.md

@@ -69,6 +69,16 @@ identity; matching attribute syntax with an unresolved receiver stays
 unverified. These are change dependencies, not fabricated caller edges, so
 the caller `ACCOUNT` remains a call-shaped partition.
 
+When the selected definition is a type, interface, enum, trait, or record,
+`impact` adds a `TYPE REFERENCE SITES` band: annotation and reference sites
+confirmed by an import link to the definition's file (or package scope in
+Go/Java), the rest visible as unverified with a reason. `DEPENDENCY SITES`
+counts them; `CALL SITES` stays call-shaped.
+
+Target-less `impact` and `check` diff the working tree against `HEAD` AND
+include untracked, non-ignored source files as whole-file additions, so new
+modules are checked before `git add`. `--staged` keeps its index-only meaning.
+
 An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
 
 When a plain name selects more than one definition, action-oriented commands
@@ -147,9 +157,17 @@ definition, and `--raw` when the next step is an edit.
 
 Treat `deadcode` as a candidate generator. Before deletion, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`; then corroborate with the compiler/type checker and tests. Computed dispatch such as `handlers[key]()` is a reported blind spot; registry members reached by a modeled computed receiver are withheld. Statically named reflection such as `getattr(obj, "run")` is positive liveness evidence, so every matching member spelling is withheld; recognized dynamic reflection is counted and warned because it cannot be attributed to one member. Unknown decorators/annotations and member-assigned event handlers are also withheld by default because they can be the registration itself. All remaining candidates are still review-only. Never delete solely from `deadcode` or an observed-text-zero result.
 
-`usages` includes comment/string/docstring occurrences in an `OTHER TEXT` section unless
-`--code-only` is set. This is a literal-name inventory, not exact target
-binding. `search` treats its term literally by default; pass `--regex` only
+`usages` includes comment/string/docstring occurrences and non-code text
+(JSX children, HTML markup and attributes) in an `OTHER TEXT` section unless
+`--code-only` is set, so it lists every line the `ACCOUNT` counts. This is a
+literal-name inventory, not exact target binding. Identifier boundaries are
+Unicode-aware: `hit` never matches inside `hitΔ`.
+
+`endpoints` recognizes client receivers by evidence (a receiver typed to an
+HTTP client class, or bound to a pytest fixture that constructs one), not only
+by name. Request-shaped calls with a path literal on an unrecognized receiver
+are listed under `Possible client requests` (JSON `uncertainRequests`),
+counted in `meta`, never in the inventory. `search` treats its term literally by default; pass `--regex` only
 when regular-expression semantics are intended. Ordinary regex patterns run
 through an RE2-compatible linear-time engine; unsafe nested repetition is
 rejected, and unsupported advanced syntax should be handed to ripgrep.

package/core/account.js

@@ -52,7 +52,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegExp, codeUnitCompare } = require('./shared');
+const { codeUnitCompare, literalNameRegex } = require('./shared');
 
 // Unsupported-language site listings are capped so a Rails-sized repo cannot
 // flood the account object; the counts always cover the full set.
@@ -83,7 +83,7 @@ function computeGroundSet(index, name) {
         index._groundSetCache.set(name, cached);
         return cached.result;
     }
-    const wordRe = new RegExp('\\b' + escapeRegExp(name) + '\\b');
+    const wordRe = literalNameRegex(name);
     const perFile = new Map();
     let total = 0;
     let fileCount = 0;
@@ -158,7 +158,7 @@ function scanFailedFiles(index, name) {
     if (!index.failedFiles || index.failedFiles.size === 0) {
         return { unparsed, unreadableFiles };
     }
-    const wordRe = new RegExp('\\b' + escapeRegExp(name) + '\\b');
+    const wordRe = literalNameRegex(name);
     for (const failedPath of index.failedFiles) {
         if (index.files.has(failedPath)) continue;
         let content;
@@ -204,7 +204,7 @@ function scanUnsupportedFiles(index, name, opts = {}) {
     if (!Array.isArray(index.unsupportedFiles) || index.unsupportedFiles.length === 0) {
         return unsupported;
     }
-    const wordRe = new RegExp('\\b' + escapeRegExp(name) + '\\b');
+    const wordRe = literalNameRegex(name);
     const languageCounts = new Map();
     for (const skipped of index.unsupportedFiles) {
         const absPath = path.join(index.root, skipped.relativePath);

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/bridge.js

@@ -1066,11 +1066,60 @@ function extractNextjsRoutes(index) {
  * Detect HTTP client requests across the project.
  * Cached on `index._endpointsCache.clientRequests`.
  */
+// Python HTTP client types whose instances are receivers of request calls.
+// A receiver typed to one of these (with-binding, constructor assignment) or
+// bound to a pytest fixture that constructs one is a client by evidence, not
+// by name (fix #349: 145 of 625 real `tc.get("/api/...")` sites on one repo
+// were invisible because the receiver was not literally named `client`).
+const PY_CLIENT_TYPES = new Set([
+    'TestClient', 'Client', 'AsyncClient', 'Session', 'FlaskClient',
+    'ClientSession', 'AsyncSession', 'HTTPConnection', 'HTTPSConnection',
+]);
+const PY_CLIENT_FACTORIES = new Set(['test_client', 'Session', 'Client', 'AsyncClient']);
+const PY_REQUEST_METHODS = /^(get|post|put|delete|patch|options|head|request)$/;
+
+function _pythonClientFixtures(index) {
+    if (index._endpointsCache?.pyClientFixtures) return index._endpointsCache.pyClientFixtures;
+    const fixtures = new Set();
+    for (const [filePath, fileEntry] of index.files) {
+        if (fileEntry.language !== 'python') continue;
+        const fixtureDefs = (fileEntry.symbols || []).filter(s =>
+            (s.decorators || []).some(d => /(^|\.)fixture$/.test(String(d))));
+        if (fixtureDefs.length === 0) continue;
+        const calls = getCachedCalls(index, filePath) || [];
+        for (const def of fixtureDefs) {
+            const constructsClient = calls.some(c =>
+                c.enclosingFunction?.name === def.name &&
+                c.enclosingFunction?.startLine === def.startLine &&
+                (PY_CLIENT_TYPES.has(c.name) || (c.isMethod && PY_CLIENT_FACTORIES.has(c.name))));
+            if (constructsClient) fixtures.add(def.name);
+        }
+    }
+    if (!index._endpointsCache) index._endpointsCache = {};
+    index._endpointsCache.pyClientFixtures = fixtures;
+    return fixtures;
+}
+
+function _pythonClientReceiver(index, fileEntry, call, fixtures) {
+    if (!call.isMethod || !call.receiver || !PY_REQUEST_METHODS.test(call.name)) return null;
+    if (call.receiverType && PY_CLIENT_TYPES.has(String(call.receiverType).split('.').pop())) {
+        return 'python-client';
+    }
+    if (fixtures.size === 0 || !fixtures.has(call.receiver)) return null;
+    const fn = call.enclosingFunction;
+    if (!fn) return null;
+    const sym = (fileEntry.symbols || []).find(s => s.name === fn.name && s.startLine === fn.startLine);
+    const params = String(sym?.params || '').split(',').map(p => p.trim().split(/[:=]/)[0].trim());
+    return params.includes(call.receiver) ? 'pytest-client-fixture' : null;
+}
+
 function extractClientRequests(index) {
     if (index._endpointsCache && index._endpointsCache.clientRequests) {
         return index._endpointsCache.clientRequests;
     }
     const requests = [];
+    const uncertain = [];
+    const pyFixtures = _pythonClientFixtures(index);
 
     for (const [filePath, fileEntry] of index.files) {
         const lang = fileEntry.language;
@@ -1079,8 +1128,30 @@ function extractClientRequests(index) {
 
         for (const call of calls) {
             if (!call.firstStringArg) continue;
-            const r = matchClientRequest(call, lang, calls);
-            if (!r) continue;
+            let r = matchClientRequest(call, lang, calls);
+            if (!r && lang === 'python') {
+                const framework = _pythonClientReceiver(index, fileEntry, call, pyFixtures);
+                if (framework) {
+                    r = { method: call.name.toUpperCase() === 'REQUEST' ? 'ALL' : call.name.toUpperCase(),
+                        framework, methodInferred: call.name === 'request' };
+                }
+            }
+            if (!r) {
+                // Visible uncertainty: request-shaped call on an unrecognized
+                // receiver with a path-shaped literal. Listed, never counted.
+                const conf = CLIENT_PATTERNS[lang];
+                const pathShaped = call.firstStringArg.startsWith('/') || call.firstStringArg.includes('://');
+                if (conf && call.isMethod && call.receiver && pathShaped &&
+                    conf.receivers.some(p => p.methodPattern.test(call.name))) {
+                    uncertain.push({
+                        receiver: call.receiver, method: call.name, path: call.firstStringArg,
+                        file: fileEntry.relativePath || filePath, absoluteFile: filePath, line: call.line,
+                        callerName: call.enclosingFunction?.name || '<top-level>',
+                        reason: 'receiver-unrecognized',
+                    });
+                }
+                continue;
+            }
 
             // Python's common `session.get("key")` / `s.get("key")`
             // dictionary and ORM idioms are not HTTP requests.  Without
@@ -1114,6 +1185,9 @@ function extractClientRequests(index) {
     }
 
     // Stable sort
+    uncertain.sort((a, b) => a.file !== b.file ? codeUnitCompare(a.file, b.file) : a.line - b.line);
+    if (!index._endpointsCache) index._endpointsCache = {};
+    index._endpointsCache.uncertainRequests = uncertain;
     requests.sort((a, b) => {
         if (a.file !== b.file) return codeUnitCompare(a.file, b.file);
         if (a.line !== b.line) return a.line - b.line;
@@ -1418,6 +1492,13 @@ function endpoints(index, options = {}) {
 
     let routes = opts.clientOnly ? [] : extractServerRoutes(index);
     let requests = (opts.serverOnly ? [] : extractClientRequests(index));
+    let uncertainRequests = opts.serverOnly ? [] : (index._endpointsCache?.uncertainRequests || []);
+    if (uncertainRequests.length > 0) {
+        // A server route registration (`@app.get("/x")`, `router.get("/x", h)`)
+        // is request-shaped too; the route inventory already owns those lines.
+        const routeLines = new Set(extractServerRoutes(index).map(r => `${r.absoluteFile}:${r.line}`));
+        uncertainRequests = uncertainRequests.filter(r => !routeLines.has(`${r.absoluteFile}:${r.line}`));
+    }
 
     // Apply filters
     if (opts.method) {
@@ -1427,6 +1508,10 @@ function endpoints(index, options = {}) {
     if (opts.prefix) {
         routes = routes.filter(r => r.path.startsWith(opts.prefix) || r.normalizedPath.startsWith(opts.prefix));
         requests = requests.filter(r => r.path.startsWith(opts.prefix) || r.normalizedPath.startsWith(opts.prefix));
+        uncertainRequests = uncertainRequests.filter(r => r.path.startsWith(opts.prefix));
+    }
+    if (opts.method) {
+        uncertainRequests = uncertainRequests.filter(r => r.method.toUpperCase() === opts.method || r.method === 'request');
     }
 
     let bridges = opts.bridge ? bridgeEndpoints(index) : [];
@@ -1472,12 +1557,14 @@ function endpoints(index, options = {}) {
             : 'incomplete-endpoint-inventory',
         routes,
         requests,
+        uncertainRequests,
         bridges,
         unmatchedRoutes,
         unmatchedRequests,
         meta: {
             totalRoutes: routes.length,
             totalRequests: requests.length,
+            uncertainRequests: uncertainRequests.length,
             totalBridges: bridges.length,
             unmatchedRoutes: unmatchedRoutes.length,
             unmatchedRequests: unmatchedRequests.length,

package/core/cache.js

@@ -697,7 +697,9 @@ function clearAllCaches() {
 // 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;
+// v213 (fix #348): Python from-import records carry per-name `renames` so
+// import bindings pair each alias with its own module.
+const CACHE_FORMAT_VERSION = 213;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**

package/core/callers.js

@@ -2802,7 +2802,9 @@ function findCallers(index, name, options = {}) {
                     // source name from DIFFERENT modules — the record's local
                     // alias (call.name) picks its own binding; source-name
                     // matching alone over-follows into the other module.
-                    if (call.resolvedName && nameBindings.some(b => b.alias)) {
+                    // Python records carry the alias as `calledAs` rather
+                    // than resolvedName; both name the paired binding.
+                    if ((call.resolvedName || calledAs) && nameBindings.some(b => b.alias)) {
                         const paired = nameBindings.filter(b => b.alias === call.name);
                         if (paired.length > 0) nameBindings = paired;
                     }
@@ -16128,4 +16130,4 @@ function findCallbackUsages(index, name) {
     return usages;
 }
 
-module.exports = { _unresolvedModuleIsGap, getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };
+module.exports = { _unresolvedModuleIsGap, _importReaches, _sameNominalPackageDir, getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };

package/core/check.js

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

package/core/execute.js

@@ -1836,6 +1836,7 @@ const HANDLERS = {
         result.meta = {
             totalRoutes: result.routes.length,
             totalRequests: result.requests.length,
+            uncertainRequests: (result.uncertainRequests || []).length,
             totalBridges: result.bridges.length,
             unmatchedRoutes: result.unmatchedRoutes.length,
             unmatchedRequests: result.unmatchedRequests.length,

package/core/output/analysis-ext.js

@@ -215,6 +215,10 @@ function formatDiffImpact(result, options = {}) {
     if (result.nonSourcePaths > 0) {
         lines.push(`Note: ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
     }
+    // fix #346: untracked source files join the working-tree diff.
+    if (result.untrackedPaths > 0) {
+        lines.push(`Note: ${result.untrackedPaths} untracked source file(s) included as whole-file additions.`);
+    }
     lines.push('');
 
     // Modified functions

package/core/output/analysis.js

@@ -786,8 +786,8 @@ function formatImpact(impact, options = {}) {
     // Summary (confirmed + unverified tiers reported separately)
     const impactUnverified = impact.unverifiedSites || [];
     const unverifiedSuffix = impactUnverified.length > 0 ? ` confirmed + ${impactUnverified.length} unverified` : '';
-    if (impact.propertyAccesses) {
-        const pa = impact.propertyAccesses;
+    if (impact.propertyAccesses || impact.typeReferences) {
+        const pa = impact.propertyAccesses || impact.typeReferences;
         const uv = pa.unverifiedCount ? ` + ${pa.unverifiedCount} unverified` : '';
         lines.push(`DEPENDENCY SITES: ${impact.totalDependencySites} confirmed${uv}`);
     }
@@ -885,6 +885,34 @@ function formatImpact(impact, options = {}) {
         }
     }
 
+    // fix #345: annotation sites of a type-kind definition, tiered like the
+    // accessor band. The headline no longer says 0 for a type with dependents.
+    if (impact.typeReferences) {
+        const refs = impact.typeReferences;
+        lines.push(`${compact ? '' : '\n'}TYPE REFERENCE SITES: ${refs.confirmedCount} confirmed` +
+            (refs.unverifiedCount ? ` + ${refs.unverifiedCount} unverified` : '') +
+            (refs.excluded?.total ? ` (${refs.excluded.total} other-target)` : ''));
+        for (const group of refs.byFile) {
+            for (const site of group.sites) {
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${group.file}:${site.line}${expr}`);
+            }
+        }
+        if (refs.unverifiedSites.length > 0) {
+            lines.push(`${compact ? '' : '\n'}UNVERIFIED TYPE REFERENCE CANDIDATES (${refs.unverifiedSites.length}) — name matches, no import link to this definition:`);
+            for (const site of refs.unverifiedSites.slice(0, 10)) {
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${site.file}:${site.line}${expr} (${site.reason})`);
+            }
+            if (refs.unverifiedSites.length > 10) {
+                lines.push(`  (+${refs.unverifiedSites.length - 10} more unverified)`);
+            }
+        }
+        if (refs.confirmedCount === 0 && refs.unverifiedCount === 0) {
+            lines.push('  (no annotation sites outside the definition)');
+        }
+    }
+
     // Unverified tier: visible, capped at 10 one-liners
     if (impactUnverified.length > 0) {
         lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call syntax, no binding/receiver evidence:`);

package/core/output/endpoints.js

@@ -26,7 +26,7 @@ function formatEndpoints(result, options = {}) {
     const showBridge = options.bridge;
 
     if (!showBridge) {
-        return formatRoutesAndRequests(routes, requests, meta, options, result.advisory);
+        return formatRoutesAndRequests(routes, requests, meta, options, result.advisory, result);
     }
     return formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options, result.advisory);
 }
@@ -48,7 +48,20 @@ function uniqueMatchPercent(bridges, totalRequests) {
     return Math.min(100, Math.max(0, pct));
 }
 
-function formatRoutesAndRequests(routes, requests, meta, options, advisory = null) {
+function formatUncertainRequests(result, options) {
+    const list = result?.uncertainRequests || [];
+    if (list.length === 0) return [];
+    const lines = [];
+    lines.push(`Possible client requests (${list.length}) — request-shaped call with a path literal, receiver not recognized as an HTTP client:`);
+    const cap = options.all ? Infinity : 10;
+    for (const r of list.slice(0, cap)) {
+        lines.push(`  ${r.file}:${r.line} ${r.receiver}.${r.method}(${JSON.stringify(r.path)}) in ${r.callerName}`);
+    }
+    if (list.length > cap) lines.push(`  (+${list.length - cap} more — use --all)`);
+    return lines;
+}
+
+function formatRoutesAndRequests(routes, requests, meta, options, advisory = null, result = null) {
     const lines = [];
     const showServer = !options.clientOnly;
     const showClient = !options.serverOnly;
@@ -84,7 +97,7 @@ function formatRoutesAndRequests(routes, requests, meta, options, advisory = nul
 
     if (showClient) {
         if (requests.length === 0) {
-            if (showServer) lines.push('No client requests detected.');
+            if (showServer) lines.push('Client Requests: 0 — no static route literal found in any indexed file (wrapped or dynamically built request paths are invisible to this scan).');
         } else {
             if (showServer) lines.push('');
             lines.push(`Client Requests: ${requests.length}`);
@@ -109,6 +122,10 @@ function formatRoutesAndRequests(routes, requests, meta, options, advisory = nul
         }
     }
 
+    if (showClient) {
+        const uncertain = formatUncertainRequests(result, options);
+        if (uncertain.length > 0) lines.push('', ...uncertain);
+    }
     const routeAdvisory = advisoryLine(advisory);
     if (routeAdvisory) lines.push('', routeAdvisory);
     return lines.join('\n').trimEnd();
@@ -230,6 +247,10 @@ function formatEndpointsJson(result, options = {}) {
         data: {
             routes: routes.map(trimRoute),
             requests: requests.map(trimReq),
+            uncertainRequests: (result.uncertainRequests || []).map(r => ({
+                receiver: r.receiver, method: r.method, path: r.path,
+                file: r.file, line: r.line, callerName: r.callerName, reason: r.reason,
+            })),
             // In unmatched-only mode, the matched bridges array is suppressed
             // — consumers that want both should not pass --unmatched.
             bridges: unmatchedOnly ? [] : bridges.map(trimBridge),

package/core/output/lines.js

@@ -184,6 +184,7 @@ function impactRecords(result) {
         const summary = result.summary || {};
         notes.push(`# Diff: ${summary.modifiedFunctions || 0} modified, ${summary.newFunctions || 0} new, ${summary.deletedFunctions || 0} deleted functions; ${(result.moduleLevelChanges || []).length} file(s) with module-level changes.`);
         if (result.nonSourcePaths) notes.push(`# ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
+        if (result.untrackedPaths) notes.push(`# ${result.untrackedPaths} untracked source file(s) included as whole-file additions.`);
         return { records: [...new Set(out)], notes };
     }
     for (const group of result.byFile || []) {
@@ -207,6 +208,18 @@ function impactRecords(result) {
         }
         notes.push(`# PROPERTY ACCESS SITES: ${accesses.confirmedCount} confirmed, ${accesses.unverifiedCount} unverified, ${accesses.excluded?.total || 0} other-target (separate from caller ACCOUNT).`);
     }
+    if (result.typeReferences) {
+        const refs = result.typeReferences;
+        for (const group of refs.byFile || []) {
+            for (const site of group.sites || []) {
+                out.push(record(group.file, site.line, site.expression, 'type-reference'));
+            }
+        }
+        for (const site of refs.unverifiedSites || []) {
+            out.push(record(pathOf(site), site.line, site.expression, `unverified: ${site.reason}; type-reference`));
+        }
+        notes.push(`# TYPE REFERENCE SITES: ${refs.confirmedCount} confirmed, ${refs.unverifiedCount} unverified, ${refs.excluded?.total || 0} other-target (separate from caller ACCOUNT).`);
+    }
     notes.push(...accountComments(result.account));
     for (const warning of result.warnings || []) notes.push(...commentLines(warning.message));
     if (result.scopeWarning?.hint) notes.push(...commentLines(result.scopeWarning.hint));

package/core/output/tracing.js

@@ -532,6 +532,14 @@ function formatReverseTraceJson(result) {
 /**
  * Format affected-tests command output - text
  */
+// fix #347: a hub symbol at depth 2 links hundreds of names per test file;
+// the list is the answer only for leaves. Cap at 8 unless --all.
+function linkList(names, options) {
+    const MAX_LINKS = options?.all ? Infinity : 8;
+    if (!Array.isArray(names) || names.length <= MAX_LINKS) return (names || []).join(', ');
+    return `${names.slice(0, MAX_LINKS).join(', ')}, +${names.length - MAX_LINKS} more`;
+}
+
 function formatAffectedTests(result, options = {}) {
     if (!result) return 'Function not found.';
 
@@ -553,7 +561,7 @@ function formatAffectedTests(result, options = {}) {
         lines.push(`Test files to run (${summary.totalTestFiles}):`);
         lines.push('');
         for (const tf of displayFiles) {
-            lines.push(`  ${tf.file} (links: ${tf.linkedFunctions.join(', ')})`);
+            lines.push(`  ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
             // Show up to 5 key matches per file
             const keyMatches = tf.matches
                 .filter(m => m.matchType === 'call' || m.matchType === 'test-case')
@@ -581,7 +589,7 @@ function formatAffectedTests(result, options = {}) {
             lines.push(`  Additional test files (${pat.length}):`);
             const MAX_POSSIBLE = options.all ? Infinity : 10;
             for (const tf of pat.slice(0, MAX_POSSIBLE)) {
-                lines.push(`    ${tf.file} (links: ${tf.linkedFunctions.join(', ')})`);
+                lines.push(`    ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
             }
             if (pat.length > MAX_POSSIBLE) {
                 lines.push(`    ... ${pat.length - MAX_POSSIBLE} more (${options.allHint || 'use --all'})`);

package/core/project.js

@@ -17,7 +17,7 @@ const { detectLanguage, getParser, getLanguageAdapter, safeParse, langTraits, PA
 const { validateFileIR } = require('./ir');
 const { createFileEntryFromIR, populateFileEntryFromIR } = require('./index-ir');
 const { getTokenTypeAtPosition } = require('../languages/utils');
-const { escapeRegExp, NON_CALLABLE_TYPES, codeUnitCompare } = require('./shared');
+const { escapeRegExp, NON_CALLABLE_TYPES, codeUnitCompare, literalNameRegex } = require('./shared');
 const stacktrace = require('./stacktrace');
 const indexCache = require('./cache');
 const deadcodeModule = require('./deadcode');
@@ -1523,7 +1523,7 @@ class ProjectIndex {
 
         // Detailed path: full AST-based counting (original algorithm)
         // Note: no 'g' flag - we only need to test for presence per line
-        const regex = new RegExp('\\b' + escapeRegExp(name) + '\\b');
+        const regex = literalNameRegex(name);
 
         // Get files that could reference this symbol:
         // 1. The file where it's defined
@@ -1941,6 +1941,25 @@ class ProjectIndex {
         }
     }
 
+    /**
+     * True when the AST node at (line, column) is an identifier token — code
+     * the usage scan saw (and may have deliberately dropped), as opposed to
+     * JSX children, HTML markup, or other non-code text (fix #350).
+     */
+    isIdentifierAtPosition(content, lineNum, column, filePath) {
+        const language = detectLanguage(filePath, this.root);
+        if (!language) return false;
+        try {
+            const tree = this._getParsedTree(filePath, content, language) ||
+                safeParse(getParser(language), content);
+            if (!tree) return false;
+            const node = tree.rootNode.descendantForPosition({ row: lineNum - 1, column });
+            return !!node && /identifier|^name$|^word$/.test(node.type);
+        } catch (e) {
+            return false;
+        }
+    }
+
     /**
      * Check if a position in code is inside a comment or string using AST
      * @param {string} content - File content

package/core/search.js

@@ -8,7 +8,7 @@
 'use strict';
 
 const path = require('path');
-const { escapeRegExp, codeUnitCompare, inlineTestRanges, lineInRanges, classDispatchNames, CALLABLE_SYMBOL_KINDS } = require('./shared');
+const { escapeRegExp, codeUnitCompare, inlineTestRanges, lineInRanges, classDispatchNames, CALLABLE_SYMBOL_KINDS, literalNameRegex } = require('./shared');
 const { isTestFile } = require('./discovery');
 const { detectLanguage, getParser, getLanguageAdapter, langTraits } = require('../languages');
 const { getCachedCalls } = require('./callers');
@@ -49,11 +49,6 @@ function matchesSubstring(text, pattern, caseSensitive) {
     return text.toLowerCase().includes(pattern.toLowerCase());
 }
 
-function literalNameRegex(name) {
-    return new RegExp(
-        `(?<![A-Za-z0-9_$])${escapeRegExp(name)}(?![A-Za-z0-9_$])`,
-    );
-}
 
 /**
  * Complete the AST-classified usage inventory with literal-name lines that
@@ -82,14 +77,21 @@ function appendTextComplements(index, {
         const lineNum = idx + 1;
         const commentOrString = index.isCommentOrStringAtPosition(
             content, lineNum, match.index, filePath);
-        if (!commentOrString) continue;
+        // A literal match that no AST identifier record claimed and that is
+        // not inside a comment or string is non-code text: JSX children,
+        // HTML markup and attributes, regex bodies. The ACCOUNT counts these
+        // lines as other-text; the escape hatch must list them too. A line
+        // the AST scan classified and then deliberately dropped (Rust enum
+        // variants against a struct pin, #234) is code, not text: skip it.
+        if (!commentOrString &&
+            index.isIdentifierAtPosition(content, lineNum, match.index, filePath)) continue;
         const usage = {
             file: filePath,
             relativePath: fileEntry.relativePath,
             line: lineNum,
             content: line,
             usageType: 'text',
-            textKind: 'comment-or-string',
+            textKind: commentOrString ? 'comment-or-string' : 'markup-or-text',
             isDefinition: false,
         };
         if (context > 0) {
@@ -397,7 +399,7 @@ function usages(index, name, options = {}) {
             }
 
             // Fallback to regex-based detection
-            const regex = new RegExp('\\b' + escapeRegExp(name) + '\\b');
+            const regex = literalNameRegex(name);
             lines.forEach((line, idx) => {
                 const lineNum = idx + 1;
 

package/core/shared.js

@@ -118,6 +118,18 @@ function addTestExclusions(exclude) {
 /**
  * Escape special regex characters
  */
+/**
+ * Whole-identifier match for a symbol name. `\b` is ASCII-only in JS, so
+ * `hit` matched inside `hitΔ` while every compiler and ripgrep treat Δ as an
+ * identifier character. Letters, digits, `_` and `$` on either side break a
+ * match; anything else (punctuation, whitespace, line edges) is a boundary.
+ */
+function literalNameRegex(name, flags = '') {
+    return new RegExp(
+        `(?<![\\p{L}\\p{N}_$])${escapeRegExp(name)}(?![\\p{L}\\p{N}_$])`,
+        flags.includes('u') ? flags : flags + 'u');
+}
+
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -463,7 +475,7 @@ function maskBlockComments(content, language) {
     return out.join('');
 }
 
-module.exports = {
+module.exports = { literalNameRegex,
     pickBestDefinition,
     addTestExclusions,
     escapeRegExp,

package/languages/python.js

@@ -1317,34 +1317,59 @@ function pythonTargetBindsName(left, name) {
     return false;
 }
 
-function pythonScopeBindsName(scopeNode, name) {
-    for (let i = 0; i < scopeNode.namedChildCount; i++) {
-        const child = scopeNode.namedChild(i);
-        if (child.type === 'function_definition' ||
-            child.type === 'async_function_definition' ||
-            child.type === 'class_definition') {
-            // The nested body is a separate scope, but the declaration name
-            // binds in this scope.
-            if (child.childForFieldName('name')?.text === name) return true;
-            continue;
+// One walk per scope body collects every name it binds at this scope level
+// (declarations, assignment targets, for/with targets; nested def/class bodies
+// are separate scopes, lambdas too). Memoized per tree by native node id: the
+// caller loop asks the same body about many names, and a per-name walk made
+// the Python build cost functions x tracked names x body size (measured 10s of
+// a 60s sequential build on a 20MB Python repo).
+const scopeBoundNamesByTree = new WeakMap();
+function pythonScopeBoundNames(scopeNode) {
+    let byId = scopeBoundNamesByTree.get(scopeNode.tree);
+    if (!byId) { byId = new Map(); scopeBoundNamesByTree.set(scopeNode.tree, byId); }
+    const cached = byId.get(scopeNode.id);
+    if (cached) return cached;
+    const names = new Set();
+    const addTarget = (left) => {
+        if (!left) return;
+        if (left.type === 'identifier') names.add(left.text);
+        else if (left.type === 'pattern_list' || left.type === 'tuple_pattern') {
+            for (const item of left.namedChildren) {
+                if (item.type === 'identifier') names.add(item.text);
+            }
         }
-        if (child.type === 'lambda') continue;
-        if (child.type === 'assignment' ||
-            child.type === 'augmented_assignment' ||
-            child.type === 'named_expression') {
-            if (pythonTargetBindsName(
-                child.childForFieldName('left') || child.childForFieldName('name'),
-                name)) return true;
-        } else if (child.type === 'for_statement') {
-            if (pythonTargetBindsName(child.childForFieldName('left'), name)) return true;
-        } else if (child.type === 'with_statement') {
-            const text = child.namedChild(0)?.text || '';
-            const match = text.match(/\bas\s+([A-Za-z_][A-Za-z0-9_]*)/);
-            if (match && match[1] === name) return true;
-        }
-        if (pythonScopeBindsName(child, name)) return true;
-    }
-    return false;
+    };
+    const walk = (node) => {
+        for (const child of node.namedChildren) {
+            if (child.type === 'function_definition' ||
+                child.type === 'async_function_definition' ||
+                child.type === 'class_definition') {
+                const declared = child.childForFieldName('name')?.text;
+                if (declared) names.add(declared);
+                continue;
+            }
+            if (child.type === 'lambda') continue;
+            if (child.type === 'assignment' ||
+                child.type === 'augmented_assignment' ||
+                child.type === 'named_expression') {
+                addTarget(child.childForFieldName('left') || child.childForFieldName('name'));
+            } else if (child.type === 'for_statement') {
+                addTarget(child.childForFieldName('left'));
+            } else if (child.type === 'with_statement') {
+                const text = child.namedChild(0)?.text || '';
+                const match = text.match(/\bas\s+([A-Za-z_][A-Za-z0-9_]*)/);
+                if (match) names.add(match[1]);
+            }
+            walk(child);
+        }
+    };
+    walk(scopeNode);
+    byId.set(scopeNode.id, names);
+    return names;
+}
+
+function pythonScopeBindsName(scopeNode, name) {
+    return pythonScopeBoundNames(scopeNode).has(name);
 }
 
 const PY_COMPREHENSIONS = new Set([
@@ -3115,6 +3140,7 @@ function findImportsInCode(code, parser) {
             const deferral = importDeferral(node);
             let modulePath = '';
             const names = [];
+            const renames = [];
 
             for (let i = 0; i < node.namedChildCount; i++) {
                 const child = node.namedChild(i);
@@ -3133,6 +3159,7 @@ function findImportsInCode(code, parser) {
                     if (nameNode && aliasNode && aliasNode.text !== nameNode.text) {
                         if (!importAliases) importAliases = [];
                         importAliases.push({ original: nameNode.text, local: aliasNode.text });
+                        renames.push({ original: nameNode.text, local: aliasNode.text });
                     }
                 } else if (child.type === 'wildcard_import') {
                     names.push('*');
@@ -3146,6 +3173,7 @@ function findImportsInCode(code, parser) {
                     names,
                     type: isRelative ? 'relative' : 'from',
                     line,
+                    ...(renames.length > 0 && { renames }),
                     ...(deferral && { deferred: true, deferredReason: deferral })
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",