ucn 5.3.1 → 5.3.2

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

@@ -157,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/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;
                     }

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/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;
@@ -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/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

@@ -3140,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);
@@ -3158,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('*');
@@ -3171,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.1",
+  "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",