ucn 5.0.2 → 5.0.4

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

@@ -30,12 +30,14 @@ The release board independently cross-checks overlapping stable-handle answers f
 Publish-blocking semantic gates also compare stratified samples from pinned real repositories with independent language-native oracles: ts-morph, Pyright, gopls, rust-analyzer, JDT LS, clangd, and Roslyn. This validates the measured static evidence classes; it does not turn dynamic dispatch, generated code, reflection, or external dependencies into complete runtime knowledge.
 
 MCP keeps its process and project index warm across calls. CLI and MCP share
-the same text budget: targeted commands default to 10K output characters,
-broad commands to 3K, with a 100K hard ceiling. Use CLI `--max-chars`, MCP
-`max_chars`, a narrower file/directory scope, or a smaller section projection
-when necessary. Truncation must retain the accounting/contract lines needed to
-interpret the answer, and the requested limit includes both the notice and the
-preserved metadata.
+the same text budget: broad sweep commands (`repo`, `entrypoints`,
+`endpoints`, `deadcode`, `deps`, `check`, `audit-async`) default to 3K output
+characters, all other commands to 10K, with a 100K hard ceiling. Use CLI
+`--max-chars`, MCP `max_chars`, a narrower file/directory scope, or a smaller
+section projection when necessary. Truncated output keeps the head of the
+answer, a notice stating the full size and limit, and the accounting/contract
+lines needed to interpret what remains; the requested limit includes all
+three. The text block is the whole response on every surface.
 
 Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use.
 

package/core/analysis.js

@@ -1768,6 +1768,8 @@ function diffImpact(index, options = {}) {
     if (!diffText || !diffText.trim()) {
         return {
             base: staged ? '(staged)' : base,
+            changedPaths: 0,
+            nonSourcePaths: 0,
             functions: [],
             moduleLevelChanges: [],
             newFunctions: [],
@@ -1803,9 +1805,13 @@ function diffImpact(index, options = {}) {
     let totalCallSites = 0;
     let totalUnverifiedSites = 0;
 
+    // fix #283: count changed paths the analysis can't see (docs, config,
+    // unsupported languages) so "no changes to analyze" can say why.
+    let nonSourcePaths = 0;
+
     for (const change of changes) {
         const lang = detectLanguage(change.filePath);
-        if (!lang) continue;
+        if (!lang) { nonSourcePaths++; continue; }
 
         const fileEntry = index.files.get(change.filePath);
 
@@ -2172,6 +2178,8 @@ function diffImpact(index, options = {}) {
 
     return {
         base: staged ? '(staged)' : base,
+        changedPaths: changes.length,
+        nonSourcePaths,
         functions,
         moduleLevelChanges,
         newFunctions,

package/core/bridge.js

@@ -8,10 +8,13 @@
  * server route — across language boundaries.
  *
  * REUSES the call cache (getCachedCalls) and AST-derived symbol metadata
- * (decoratorsWithArgs/annotationsWithArgs/attributesWithArgs). The only file
- * I/O is index-driven; we never re-parse files. Extraction results are cached
- * lazily on `index._endpointsCache` and invalidated on rebuild via the same
- * mechanism as `_reachableSymbols`.
+ * (decoratorsWithArgs/annotationsWithArgs/attributesWithArgs). File I/O is
+ * index-driven; the one re-parse is the router-mount scan (fix #282), which
+ * AST-parses only the files whose call cache mentions a router factory or an
+ * include/mount call — keyword arguments (`prefix=`) and mount references
+ * aren't in the call cache. Extraction results are cached lazily on
+ * `index._endpointsCache` and invalidated on rebuild via the same mechanism
+ * as `_reachableSymbols`.
  *
  * Output shape:
  *   serverRoutes: [{ method, path, normalizedPath, handler, file, line, framework, raw }]
@@ -26,6 +29,7 @@ const fs = require('fs');
 const { codeUnitCompare } = require('./shared');
 const path = require('path');
 const { getCachedCalls } = require('./callers');
+const { getParser, safeParse } = require('../languages');
 
 // ============================================================================
 // HTTP METHOD CONSTANTS
@@ -86,6 +90,57 @@ function joinRoutePath(prefix, sub) {
     return p + '/' + s;
 }
 
+/** Join two PREFIX fragments (fix #282). Unlike joinRoutePath, two empty
+ *  fragments compose to '' — a router with no mount prefix anywhere must not
+ *  gain a spurious '/'. */
+function joinPrefixes(a, b) {
+    if (!a) return b || '';
+    if (!b) return a;
+    return a.replace(/\/+$/, '') + '/' + b.replace(/^\/+/, '');
+}
+
+/**
+ * Compose mount-prefix chains transitively (fix #282). A router's full
+ * prefix = (each mounter's full prefix + the mount-call prefix) + its own
+ * constructor prefix — FastAPI/Flask include semantics; Express has no
+ * constructor prefix so `ctorPrefixes` is simply empty there.
+ *
+ * @param {Map<string, Array<{mounterKey: string|null, prefix: string, overridesCtor?: boolean}>>} edges
+ *        targetKey -> incoming mounts (mounterKey null = unresolvable mounter,
+ *        treated as a root). `overridesCtor` models Flask's register_blueprint
+ *        semantics: an explicit url_prefix REPLACES the blueprint's own prefix
+ *        (FastAPI's include_router prefix composes with it instead).
+ * @param {Map<string, string>} ctorPrefixes - key -> constructor prefix
+ * @returns {Map<string, string[]>} key -> composed full prefixes (sorted)
+ */
+function composeMountPrefixes(edges, ctorPrefixes) {
+    const memo = new Map();
+    const resolve = (key, depth, stack) => {
+        if (key == null) return [''];
+        if (memo.has(key)) return memo.get(key);
+        if (depth > 8 || stack.has(key)) return [''];
+        stack.add(key);
+        const own = ctorPrefixes.get(key) || '';
+        const incoming = edges.get(key) || [];
+        const full = incoming.length === 0 ? [own]
+            : incoming.flatMap(e => resolve(e.mounterKey, depth + 1, stack)
+                .map(parentFull => joinPrefixes(joinPrefixes(parentFull, e.prefix),
+                    e.overridesCtor ? '' : own)));
+        const out = [...new Set(full.length ? full : [own])].sort(codeUnitCompare);
+        stack.delete(key);
+        memo.set(key, out);
+        return out;
+    };
+    // Only router keys are exposed — mounter-only keys (the app object) are
+    // resolved for composition but would shadow group-prefix fallbacks if kept.
+    const routerKeys = new Set([...edges.keys(), ...ctorPrefixes.keys()]);
+    const out = new Map();
+    for (const key of [...routerKeys].sort(codeUnitCompare)) {
+        out.set(key, resolve(key, 0, new Set()));
+    }
+    return out;
+}
+
 // ============================================================================
 // FRAMEWORK PATTERNS
 // ============================================================================
@@ -281,6 +336,7 @@ function extractServerRoutes(index) {
 
     const routes = [];
     const mountedPrefixes = collectProjectRouterMounts(index);
+    const pythonMounts = collectPythonRouterMounts(index);
     const pythonReceiverFrameworks = new Map();
     for (const [filePath, entry] of index.files) {
         if (entry.language !== 'python') continue;
@@ -332,18 +388,26 @@ function extractServerRoutes(index) {
             const declRoutes = collectMethodRoutes(sym, lang, classPrefix, fileEntry,
                 pythonReceiverFrameworks.get(sym.file));
             for (const r of declRoutes) {
-                routes.push({
-                    method: r.method,
-                    path: r.path,
-                    normalizedPath: normalizePath(r.path),
-                    handler: sym.name,
-                    file: sym.relativePath || sym.file,
-                    absoluteFile: sym.file,
-                    line: sym.startLine,
-                    framework: r.framework,
-                    classPrefix: classPrefix || undefined,
-                    raw: r.raw || `${r.method} ${r.path}`,
-                });
+                // fix #282: FastAPI/Flask routers serve under their composed
+                // mount prefixes (APIRouter(prefix=) + include_router(prefix=)).
+                const prefixes = (lang === 'python' && r.receiver &&
+                    pythonMounts.get(`${sym.file}:${r.receiver}`)) || [''];
+                for (const prefix of prefixes) {
+                    const fullPath = prefix ? joinRoutePath(prefix, r.path) : r.path;
+                    routes.push({
+                        method: r.method,
+                        path: fullPath,
+                        normalizedPath: normalizePath(fullPath),
+                        handler: sym.name,
+                        file: sym.relativePath || sym.file,
+                        absoluteFile: sym.file,
+                        line: sym.startLine,
+                        framework: r.framework,
+                        classPrefix: classPrefix || undefined,
+                        ...(prefix && { mountPrefix: prefix }),
+                        raw: r.raw || `${r.method} ${fullPath}`,
+                    });
+                }
             }
         }
     }
@@ -476,6 +540,9 @@ function collectMethodRoutes(sym, lang, classPrefix, fileEntry = null,
                     method: r.method,
                     path: r.path,
                     framework: r.framework,
+                    // fix #282: the decorator's receiver variable keys the
+                    // composed mount-prefix lookup in extractServerRoutes.
+                    receiver: r.receiver,
                 });
             }
         }
@@ -587,10 +654,10 @@ function parsePythonDecoratorFull(raw, fileEntry = null, receiverFramework = nul
             const methods = methodsMatch[1].split(',').map(s => s.trim().replace(/['"]/g, '').toUpperCase()).filter(Boolean);
             // Caller will receive ONE entry; we return GET if methods empty, else first.
             if (methods.length > 0) {
-                return { method: methods[0], path: pathStr, framework: 'flask' };
+                return { method: methods[0], path: pathStr, framework: 'flask', receiver: m[1] };
             }
         }
-        return { method: 'GET', path: pathStr, framework: 'flask' };
+        return { method: 'GET', path: pathStr, framework: 'flask', receiver: m[1] };
     }
     if (['get','post','put','delete','patch','options','head'].includes(verb)) {
         const modules = (fileEntry?.imports || []).map(value =>
@@ -601,43 +668,193 @@ function parsePythonDecoratorFull(raw, fileEntry = null, receiverFramework = nul
                 ? 'flask' : modules.some(module => /^fastapi\b/.test(module)) &&
                   !modules.some(module => /^flask\b/.test(module))
                     ? 'fastapi' : 'unknown-python');
-        return { method: verb.toUpperCase(), path: pathStr, framework };
+        return { method: verb.toUpperCase(), path: pathStr, framework, receiver: m[1] };
+    }
+    return null;
+}
+
+// ── Python router mounts (fix #282) ─────────────────────────────────────────
+// FastAPI: `router = APIRouter(prefix="/api")` + `app.include_router(r, prefix="/v2")`.
+// Flask:   `bp = Blueprint(..., url_prefix="/api")` + `app.register_blueprint(bp, url_prefix="/v2")`.
+// Neither prefix mechanism is in the call cache (both are keyword arguments,
+// and the mounted router is a non-string argument), so every route rendered
+// with its bare decorator path — /list for the real /api/things/list — and
+// --bridge matched nothing on a prefixed application.
+const PY_ROUTER_FACTORIES = new Set(['APIRouter', 'Blueprint']);
+const PY_INCLUDE_METHODS = new Set(['include_router', 'register_blueprint']);
+const PY_PREFIX_KWARGS = new Set(['prefix', 'url_prefix']);
+
+/** Unquote a Python string literal node ("/api", '/api', r"/api"). */
+function pyStringText(node) {
+    if (!node || node.type !== 'string') return null;
+    const m = node.text.match(/^[rbuf]{0,2}(['"])([\s\S]*)\1$/i);
+    return m ? m[2] : null;
+}
+
+/** First `prefix=`/`url_prefix=` string keyword argument of a call node. */
+function pyPrefixKwarg(argsNode) {
+    if (!argsNode) return null;
+    for (let i = 0; i < argsNode.namedChildCount; i++) {
+        const arg = argsNode.namedChild(i);
+        if (arg.type !== 'keyword_argument') continue;
+        const nameNode = arg.childForFieldName('name') || arg.namedChild(0);
+        if (!nameNode || !PY_PREFIX_KWARGS.has(nameNode.text)) continue;
+        const valueNode = arg.childForFieldName('value') || arg.namedChild(1);
+        return pyStringText(valueNode);
     }
     return null;
 }
 
-/** Map exported router receiver variables to their literal project mounts. */
+/**
+ * Map Python router variables to their composed mount prefixes.
+ * Returns Map `${absFile}:${routerVar}` -> [full prefix strings].
+ * Only files whose call cache mentions a router factory or include call are
+ * AST-parsed; unresolvable mount references contribute no edge (the route
+ * keeps its bare path — conservative under the advisory contract).
+ */
+function collectPythonRouterMounts(index) {
+    const relevant = [];
+    for (const [filePath, entry] of index.files) {
+        if (entry.language !== 'python') continue;
+        const calls = getCachedCalls(index, filePath) || [];
+        if (calls.some(c => (PY_ROUTER_FACTORIES.has(c.name) && c.assignedTo) ||
+            PY_INCLUDE_METHODS.has(c.name))) {
+            relevant.push([filePath, entry]);
+        }
+    }
+    if (relevant.length === 0) return new Map();
+    let parser;
+    try { parser = getParser('python'); } catch (e) { return new Map(); }
+    if (!parser) return new Map();
+
+    const ctorPrefixes = new Map();
+    const edges = new Map();
+    for (const [filePath, entry] of relevant) {
+        let tree = null;
+        try {
+            tree = safeParse(parser, fs.readFileSync(filePath, 'utf8'));
+        } catch (e) { /* unreadable/unparseable → no prefixes from this file */ }
+        if (!tree) continue;
+        const visit = (node) => {
+            if (node.type === 'call') visitPyRouterCall(node, filePath, entry, index, ctorPrefixes, edges);
+            for (let i = 0; i < node.namedChildCount; i++) visit(node.namedChild(i));
+        };
+        visit(tree.rootNode);
+    }
+    return composeMountPrefixes(edges, ctorPrefixes);
+}
+
+function visitPyRouterCall(callNode, filePath, entry, index, ctorPrefixes, edges) {
+    const fn = callNode.childForFieldName('function');
+    if (!fn) return;
+
+    // `<var> = APIRouter(prefix="/api")` — constructor prefix.
+    if (fn.type === 'identifier' && PY_ROUTER_FACTORIES.has(fn.text)) {
+        const parent = callNode.parent;
+        if (!parent || parent.type !== 'assignment') return;
+        const left = parent.childForFieldName('left');
+        if (!left || left.type !== 'identifier') return;
+        const prefix = pyPrefixKwarg(callNode.childForFieldName('arguments'));
+        if (prefix) ctorPrefixes.set(`${filePath}:${left.text}`, prefix);
+        return;
+    }
+
+    // `<recv>.include_router(<ref>, prefix="/v2")` — mount edge.
+    if (fn.type !== 'attribute') return;
+    const attrNode = fn.childForFieldName('attribute');
+    if (!attrNode || !PY_INCLUDE_METHODS.has(attrNode.text)) return;
+    const recvNode = fn.childForFieldName('object');
+    // Non-identifier receivers (self.app, factories) can't be keyed — treat
+    // as a root mounter so the edge prefix still applies.
+    const mounterKey = recvNode && recvNode.type === 'identifier'
+        ? `${filePath}:${recvNode.text}` : null;
+    const argsNode = callNode.childForFieldName('arguments');
+    if (!argsNode) return;
+    let refNode = null;
+    for (let i = 0; i < argsNode.namedChildCount; i++) {
+        const arg = argsNode.namedChild(i);
+        if (arg.type === 'keyword_argument' || arg.type.includes('comment')) continue;
+        refNode = arg;
+        break;
+    }
+    if (!refNode) return;
+    const explicitPrefix = pyPrefixKwarg(argsNode);
+    const prefix = explicitPrefix || '';
+    // Flask: register_blueprint's url_prefix REPLACES the blueprint's own
+    // url_prefix; FastAPI's include_router prefix composes with it.
+    const overridesCtor = explicitPrefix != null && attrNode.text === 'register_blueprint';
+
+    let targetKey = null;
+    if (refNode.type === 'attribute') {
+        // `app.include_router(mod.router)` — module attribute.
+        const obj = refNode.childForFieldName('object');
+        const attr = refNode.childForFieldName('attribute');
+        if (obj && obj.type === 'identifier' && attr) {
+            const binding = (entry.importBindings || []).find(b => b.name === obj.text);
+            const rel = binding && entry.moduleResolved?.[binding.module];
+            if (rel) targetKey = `${path.join(index.root, rel)}:${attr.text}`;
+        }
+    } else if (refNode.type === 'identifier') {
+        // Bare name: alias-aware from-import first, then same-file variable.
+        const aliasEntry = (entry.importAliases || []).find(a => a.local === refNode.text);
+        const original = aliasEntry ? aliasEntry.original : refNode.text;
+        const binding = (entry.importBindings || []).find(b =>
+            b.name === original && entry.moduleResolved?.[b.module]);
+        targetKey = binding
+            ? `${path.join(index.root, entry.moduleResolved[binding.module])}:${original}`
+            : `${filePath}:${refNode.text}`;
+    }
+    if (!targetKey) return;
+    const list = edges.get(targetKey) || [];
+    list.push({ mounterKey, prefix, ...(overridesCtor && { overridesCtor }) });
+    edges.set(targetKey, list);
+}
+
+/** Map exported router receiver variables to their literal project mounts.
+ *  fix #282: same-file mounts (`app.use('/api', localRouter)`), NAMED-export
+ *  routers, and transitive composition (`app.use('/api', parent)` +
+ *  `parent.use('/sub', child)` → child serves under /api/sub). */
 function collectProjectRouterMounts(index) {
-    const mounts = new Map();
+    const edges = new Map();
     for (const [filePath, fileEntry] of index.files) {
         if (!['javascript', 'typescript', 'tsx'].includes(fileEntry.language)) continue;
         const calls = getCachedCalls(index, filePath) || [];
+        const localRouters = collectRouterReceivers(calls, fileEntry.language);
         for (const call of calls) {
             if (call.name !== 'use' || !call.receiver || !call.firstStringArg ||
                 (call.argCount != null && call.argCount < 2)) continue;
+            const mounterKey = `${filePath}:${call.receiver}`;
             const refs = calls.filter(candidate => candidate.line === call.line &&
                 candidate !== call && (candidate.isFunctionReference || candidate.isPotentialCallback));
             for (const ref of refs) {
+                const targetKeys = [];
                 const binding = (fileEntry.importBindings || []).find(item => item.name === ref.name);
                 const rel = binding && fileEntry.moduleResolved?.[binding.module];
-                if (!rel) continue;
-                const targetFile = path.join(index.root, rel);
-                const targetEntry = index.files.get(targetFile);
-                if (!targetEntry) continue;
-                const exportedReceivers = (targetEntry.exportDetails || [])
-                    .filter(exp => exp.type === 'module.exports' || exp.isDefault ||
-                        exp.kind === 'default' || exp.type === 'export-default')
-                    .map(exp => exp.localName || exp.name).filter(Boolean);
-                for (const receiver of exportedReceivers) {
-                    const key = `${targetFile}:${receiver}`;
-                    const list = mounts.get(key) || [];
-                    if (!list.includes(call.firstStringArg)) list.push(call.firstStringArg);
-                    mounts.set(key, list);
+                if (rel) {
+                    const targetFile = path.join(index.root, rel);
+                    const targetEntry = index.files.get(targetFile);
+                    if (targetEntry) {
+                        const exportedReceivers = (targetEntry.exportDetails || [])
+                            .filter(exp => exp.type === 'module.exports' || exp.isDefault ||
+                                exp.kind === 'default' || exp.type === 'export-default' ||
+                                exp.name === ref.name)
+                            .map(exp => exp.localName || exp.name).filter(Boolean);
+                        for (const receiver of exportedReceivers) {
+                            targetKeys.push(`${targetFile}:${receiver}`);
+                        }
+                    }
+                } else if (localRouters.has(ref.name)) {
+                    targetKeys.push(`${filePath}:${ref.name}`);
+                }
+                for (const key of targetKeys) {
+                    const list = edges.get(key) || [];
+                    list.push({ mounterKey, prefix: call.firstStringArg });
+                    edges.set(key, list);
                 }
             }
         }
     }
-    return mounts;
+    return composeMountPrefixes(edges, new Map());
 }
 
 /**

package/core/cache.js

@@ -599,7 +599,7 @@ function clearAllCaches() {
 // v166: C++ nested aliases persist their lexical owner ranges, and `auto`
 // return functions persist a unanimously inferred local concrete type. v165
 // was used during prerelease development before both fields were complete.
-const CACHE_FORMAT_VERSION = 166;
+const CACHE_FORMAT_VERSION = 167;
 
 /**
  * Save index to cache file

package/core/check.js

@@ -80,13 +80,25 @@ function check(index, options = {}) {
     ];
 
     if (!dr || (modified.length === 0 && added.length === 0 && deleted.length === 0)) {
+        // fix #283: say what the diff actually contained. "no changes
+        // detected" with three changed files reads as a false negative in a
+        // pre-commit hook — the truth is the changes are outside what the
+        // symbol analysis can see.
+        const changedPaths = dr?.changedPaths || 0;
+        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`;
+        } else if (changedPaths > 0) {
+            reason = 'no callable-symbol changes in the diff';
+        }
         return {
             base: options.base || 'HEAD',
             staged: !!options.staged,
             ok: true,
             status: 'clean',
             empty: true,
-            reason: 'no changes detected',
+            reason,
         };
     }
 

package/core/execute.js

@@ -65,6 +65,15 @@ function editDistance(a, b) {
 
 function symbolNotFound(index, name, label = 'Symbol') {
     const query = String(name || '');
+    // Malformed handle (fix #283): `path:name` is a handle missing its line
+    // segment, not a symbol whose name contains a colon (identifiers can't).
+    // Saying "not found" here steered users into concluding the index missed
+    // the symbol. Single colon only — Rust `Type::method` paths never match.
+    const handleish = query.match(/^([^:]+):([A-Za-z_$][\w$]*)$/);
+    if (handleish && /[/\\]|\.[A-Za-z0-9]{1,8}$/.test(handleish[1])) {
+        return `Malformed handle "${query}": expected file:line:name. ` +
+            `Run find "${handleish[2]}" to get the exact handle.`;
+    }
     const lower = query.toLowerCase();
     let best = null;
     for (const candidate of index.symbols.keys()) {
@@ -822,7 +831,13 @@ const HANDLERS = {
     impact: (index, p) => {
         // Public v5 overload: no symbol means Git-diff impact. This replaces
         // the separate diff-impact command without changing the symbol path.
-        if (!p.name || (typeof p.name === 'string' && !p.name.trim())) {
+        // An EXPLICIT empty string is an error, not diff mode (fix #283): a
+        // pipeline whose handle extraction produced "" would otherwise get a
+        // diff answer indistinguishable from "this symbol has no callers".
+        if (typeof p.name === 'string' && p.name.trim() === '') {
+            return { ok: false, error: 'Empty symbol target. Omit the argument entirely for Git-diff impact, or pass a symbol name/handle.' };
+        }
+        if (p.name == null) {
             const response = HANDLERS.diffImpact(index, { ...p });
             if (response.ok) addMode(response.result, 'diff');
             return response;
@@ -1078,6 +1093,10 @@ const HANDLERS = {
     check: (index, p) => {
         // Public v5 overload: a symbol target performs the former verify
         // operation; a target-less invocation remains the diff/precommit check.
+        // An EXPLICIT empty string is an error, not diff mode (fix #283).
+        if (typeof p.name === 'string' && p.name.trim() === '') {
+            return { ok: false, error: 'Empty symbol target. Omit the argument entirely for the pre-commit diff check, or pass a symbol name/handle.' };
+        }
         if (p.name && String(p.name).trim()) {
             const response = HANDLERS.verify(index, { ...p });
             if (response.ok) addMode(response.result, 'symbol');

package/core/output/analysis-ext.js

@@ -210,6 +210,11 @@ function formatDiffImpact(result, options = {}) {
     parts.push(`${s.totalCallSites || 0} call sites across ${s.affectedFiles || 0} files`);
     if (s.unverifiedCallSites > 0) parts.push(`${s.unverifiedCallSites} unverified`);
     lines.push(parts.join(', '));
+    // fix #283: changed paths outside supported source are invisible to the
+    // symbol analysis — disclose instead of silently narrowing the diff.
+    if (result.nonSourcePaths > 0) {
+        lines.push(`Note: ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
+    }
     lines.push('');
 
     // Modified functions

package/core/output/refactoring.js

@@ -274,7 +274,13 @@ function formatVerify(result, options = {}) {
             const flags = _formatPatternFlags(m.patterns);
             lines.push(`  ${m.file}:${m.line}${flags}`);
             lines.push(`    ${m.expression}`);
-            lines.push(`    Expected ${m.expected}, got ${m.actual}: [${m.args?.join(', ') || ''}]`);
+            // fix #281: keyword-binding problems carry their own sentence —
+            // the raw count fits, so "Expected N, got N" would be misleading.
+            if (m.problem) {
+                lines.push(`    ${m.problem}: [${m.args?.join(', ') || ''}]`);
+            } else {
+                lines.push(`    Expected ${m.expected}, got ${m.actual}: [${m.args?.join(', ') || ''}]`);
+            }
         }
     }
 
@@ -343,6 +349,7 @@ function formatVerifyJson(result) {
                 expression: m.expression,
                 expected: m.expected,
                 actual: m.actual,
+                ...(m.problem && { problem: m.problem }),
                 args: m.args || [],
                 patterns: m.patterns,
             })),

package/core/public-command.js

@@ -31,10 +31,13 @@ function buildPublicParams(command, arg, params = {}) {
     switch (command) {
         case 'search': return { ...clean, term: arg || clean.term };
         case 'source': return parseSourceTarget(arg || clean.name, clean);
-        case 'impact': return { ...clean, ...(arg ? { name: arg } : {}) };
+        // fix #283: an EXPLICIT empty-string arg must reach the handler (which
+        // rejects it) instead of silently selecting diff mode — `arg ? ...`
+        // made `impact ""` indistinguishable from `impact`.
+        case 'impact': return { ...clean, ...(arg != null ? { name: arg } : {}) };
         case 'deps': return { ...clean, file: arg || clean.file };
         case 'api': return { ...clean, file: arg || clean.file };
-        case 'check': return { ...clean, ...(arg ? { name: arg } : {}) };
+        case 'check': return { ...clean, ...(arg != null ? { name: arg } : {}) };
         case 'stacktrace': return { ...clean, stack: clean.stack || arg };
         default: return clean;
     }

package/core/registry.js

@@ -153,10 +153,12 @@ const FLAG_APPLICABILITY = {
     auditAsync:   ['file', 'exclude', 'limit'],
 };
 
-// Commands whose output is project-wide — truncation means you need a filter, not more text.
-// Used by MCP server for tighter default output limits.
+// Project/change-wide sweep commands with no required symbol argument —
+// truncation means you need a filter, not more text. Drives the shared
+// CLI/MCP output budget: broad commands default to 3K chars, everything
+// else (symbol-targeted commands like usages/tests included) to 10K.
 const BROAD_COMMANDS = new Set([
-    'repo', 'entrypoints', 'endpoints', 'tests', 'deadcode', 'usages',
+    'repo', 'entrypoints', 'endpoints', 'deadcode',
     'deps', 'check', 'auditAsync',
 ]);
 

package/core/verify.js

@@ -413,13 +413,28 @@ function formatTypedSignature(def, overrides = {}) {
     const ps = overrides.paramsStructured != null ? overrides.paramsStructured : def.paramsStructured;
     if (Array.isArray(ps)) {
         const paramTypes = def.paramTypes || {};
-        const parts2 = ps.map(p => {
+        // Python binding-position markers (fix #281): re-render the bare `*`
+        // before the first keyword-only param (unless `*args` already plays
+        // that role) and the `/` after the last positional-only param, so the
+        // displayed signature matches the source contract.
+        const lastPosOnly = ps.reduce(
+            (acc, p, i) => (p && p.positionalOnly ? i : acc), -1);
+        let starShown = false;
+        const parts2 = [];
+        ps.forEach((p, i) => {
             // Apply paramTypes mapping when paramsStructured doesn't carry types
             const merged = { ...p };
             if (!merged.type && paramTypes[p.name]) merged.type = paramTypes[p.name];
-            return formatTypedParam(merged);
+            if (p && p.rest && /^\*(?!\*)/.test(String(p.name))) starShown = true;
+            if (!starShown && p && p.keywordOnly) {
+                parts2.push('*');
+                starShown = true;
+            }
+            const tok = formatTypedParam(merged);
+            if (tok) parts2.push(tok);
+            if (i === lastPosOnly) parts2.push('/');
         });
-        parts.push(`(${parts2.filter(Boolean).join(', ')})`);
+        parts.push(`(${parts2.join(', ')})`);
     } else if (def.params !== undefined) {
         parts.push(`(${def.params})`);
     }
@@ -874,6 +889,28 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
             args.push(argNode.text.trim());
         }
 
+        // Python argument structure (fix #281): keyword arguments bind by
+        // NAME, and `*seq` / `**map` unpacking makes the argument count
+        // non-static. Both were invisible before — keyword args counted as
+        // positional slots and unpacking fell through to a hard mismatch.
+        const keywordArgNames = [];
+        let unpackingArgs = 0;
+        let pyPositional = 0;
+        if (language === 'python') {
+            for (let i = 0; i < argsNode.namedChildCount; i++) {
+                const argNode = argsNode.namedChild(i);
+                if (argNode.type.includes('comment')) continue;
+                if (argNode.type === 'keyword_argument') {
+                    const nameNode = argNode.childForFieldName('name') || argNode.namedChild(0);
+                    if (nameNode) keywordArgNames.push(nameNode.text);
+                } else if (argNode.type === 'list_splat' || argNode.type === 'dictionary_splat') {
+                    unpackingArgs++;
+                } else {
+                    pyPositional++;
+                }
+            }
+        }
+
         // Function.prototype indirection has a precise, AST-visible argument
         // mapping. `fn.call(thisArg, a, b)` invokes fn(a, b). `fn.apply`
         // is countable only when its argument array is a literal. `bind`
@@ -922,7 +959,9 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
         return {
             args,
             argCount: args.length,
-            hasSpread: args.some(a => a.startsWith('...')),
+            hasSpread: args.some(a => a.startsWith('...')) || unpackingArgs > 0,
+            ...(unpackingArgs > 0 && { unpackingSpread: true }),
+            ...(language === 'python' && { positionalCount: pyPositional, keywordArgNames }),
             hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a)),
             isMethodCall,
             ...(indirectKind && { indirectKind }),
@@ -1129,6 +1168,70 @@ function identifyCallPatterns(callSites, funcName) {
     return patterns;
 }
 
+// Decorators that provably keep the declared call interface. Any OTHER
+// decorator may reshape the signature (click/celery/functools partials), so
+// keyword-binding violations against the declared parameters route to the
+// UNCERTAIN band instead of hard mismatches (fix #281 — the #205 "decorators
+// reshape signatures" rule applied to verify's claim).
+const SIGNATURE_PRESERVING_DECORATORS = new Set([
+    'staticmethod', 'classmethod', 'abstractmethod', 'override', 'final',
+]);
+
+/**
+ * Bind a keyword-argument call against structured parameters (fix #281).
+ * Mirrors the interpreter's rules: positional args fill non-keyword-only
+ * slots in order, each keyword arg must name a known non-positional-only
+ * parameter (unless `**kwargs` absorbs it), and every required parameter
+ * must end up bound. Returns problem strings (empty = binds cleanly).
+ * Callers gate on the `keywordArguments` trait — languages without named
+ * arguments allow short calls, so required-coverage would false-flag.
+ */
+function bindKeywordCall(params, analysis) {
+    const problems = [];
+    const isListRest = p => p.rest && /^\*(?!\*)/.test(String(p.name));
+    const isDictRest = p => p.rest && /^\*\*/.test(String(p.name));
+    const slots = params.filter(p => !p.rest && !p.keywordOnly);
+    const hasListRest = params.some(isListRest);
+    const hasDictRest = params.some(isDictRest);
+    const positional = analysis.positionalCount != null
+        ? analysis.positionalCount : analysis.argCount;
+    const tooManyPositional = positional > slots.length && !hasListRest;
+    if (tooManyPositional) {
+        problems.push(`takes ${slots.length} positional argument(s) but ` +
+            `${positional} ${positional === 1 ? 'was' : 'were'} given`);
+    }
+    const bound = new Set(
+        slots.slice(0, Math.min(positional, slots.length)).map(p => p.name));
+    for (const kw of analysis.keywordArgNames || []) {
+        const param = params.find(p => !p.rest && p.name === kw);
+        if (!param) {
+            if (!hasDictRest) problems.push(`unexpected keyword argument '${kw}'`);
+        } else if (param.positionalOnly) {
+            // With **kwargs the name is absorbed there — but then the
+            // positional-only parameter itself stays unbound (missing check).
+            if (!hasDictRest) {
+                problems.push(`'${kw}' is positional-only and cannot be passed by keyword`);
+            }
+        } else if (bound.has(kw)) {
+            problems.push(`got multiple values for argument '${kw}'`);
+        } else {
+            bound.add(kw);
+        }
+    }
+    // Skip required-coverage when positionals already overflowed — the extra
+    // positionals were almost certainly aimed at the unbound keyword-only
+    // params, and the interpreter reports only the positional error too.
+    if (!tooManyPositional) {
+        const missing = params
+            .filter(p => !p.rest && !p.optional && p.default === undefined && !bound.has(p.name))
+            .map(p => `'${p.name}'`);
+        if (missing.length > 0) {
+            problems.push(`missing required argument(s): ${missing.join(', ')}`);
+        }
+    }
+    return problems;
+}
+
 /**
  * Verify that all call sites match a function's signature
  * @param {object} index - ProjectIndex instance
@@ -1216,6 +1319,18 @@ function verify(index, name, options = {}) {
 
     const defIsMethod = !!(def.isMethod || def.type === 'method' || def.className);
 
+    // fix #281: keyword-argument binding validation. Applies only where the
+    // language binds by name (Python), the target has ONE parameter list
+    // (overload groups keep the count-range check), and the arity isn't an
+    // inherited-constructor unknown.
+    const keywordBindable = langTraits(lang)?.keywordArguments === true &&
+        rawParamLists.length === 1 && !inheritedCtorOnly;
+    const decoratorReshapes = keywordBindable && Array.isArray(def.decorators) &&
+        def.decorators.some(d => {
+            const dName = String(d).replace(/^@/, '').split('(')[0].trim();
+            return !SIGNATURE_PRESERVING_DECORATORS.has(dName.split('.').pop());
+        });
+
     // Helper: extract pattern flags (Feature A/B) from analyzeCallSite result.
     // Reused so each valid/mismatch/uncertain entry carries the same shape.
     function patternFlagsFrom(a) {
@@ -1261,7 +1376,9 @@ function verify(index, name, options = {}) {
                 file: call.relativePath,
                 line: call.line,
                 expression: call.content.trim(),
-                reason: 'Uses spread operator',
+                reason: analysis.unpackingSpread
+                    ? 'Uses argument unpacking (*/**) — argument count is not static'
+                    : 'Uses spread operator',
                 patterns: patternFlagsFrom(analysis),
                 ...carry,
             });
@@ -1285,33 +1402,40 @@ function verify(index, name, options = {}) {
         }
 
         // Check if arg count is valid
-        if (hasRest) {
-            // With rest param, need at least minArgs
-            if (argCount >= minArgs) {
-                valid.push({
-                    file: call.relativePath,
-                    line: call.line,
-                    patterns: patternFlagsFrom(analysis),
-                    ...carry,
-                });
-            } else {
-                mismatches.push({
+        const countOk = hasRest
+            ? argCount >= minArgs
+            : (argCount >= minArgs && argCount <= expectedParamCount);
+        if (!countOk) {
+            mismatches.push({
+                file: call.relativePath,
+                line: call.line,
+                expression: call.content.trim(),
+                expected: hasRest
+                    ? `at least ${minArgs} arg(s)`
+                    : (minArgs === expectedParamCount
+                        ? `${expectedParamCount} arg(s)`
+                        : `${minArgs}-${expectedParamCount} arg(s)`),
+                actual: argCount,
+                args: analysis.args,
+                patterns: patternFlagsFrom(analysis),
+                ...carry,
+            });
+            continue;
+        }
+
+        // fix #281: the count fits — for keyword-binding languages, check the
+        // NAME-level contract too (keyword-only slots, unknown keyword names,
+        // required coverage). A reshaping decorator demotes violations to
+        // UNCERTAIN: the declared parameters may not be the call interface.
+        const bindingProblems = keywordBindable ? bindKeywordCall(params, analysis) : [];
+        if (bindingProblems.length > 0) {
+            if (decoratorReshapes) {
+                uncertain.push({
                     file: call.relativePath,
                     line: call.line,
                     expression: call.content.trim(),
-                    expected: `at least ${minArgs} arg(s)`,
-                    actual: argCount,
-                    args: analysis.args,
-                    patterns: patternFlagsFrom(analysis),
-                    ...carry,
-                });
-            }
-        } else {
-            // Without rest, need between minArgs and expectedParamCount
-            if (argCount >= minArgs && argCount <= expectedParamCount) {
-                valid.push({
-                    file: call.relativePath,
-                    line: call.line,
+                    reason: `Against the declared parameters: ${bindingProblems.join('; ')}. ` +
+                        'The definition is decorated, and the decorator may reshape the call interface.',
                     patterns: patternFlagsFrom(analysis),
                     ...carry,
                 });
@@ -1320,16 +1444,27 @@ function verify(index, name, options = {}) {
                     file: call.relativePath,
                     line: call.line,
                     expression: call.content.trim(),
-                    expected: minArgs === expectedParamCount
-                        ? `${expectedParamCount} arg(s)`
-                        : `${minArgs}-${expectedParamCount} arg(s)`,
+                    expected: hasRest
+                        ? `at least ${minArgs} arg(s)`
+                        : (minArgs === expectedParamCount
+                            ? `${expectedParamCount} arg(s)`
+                            : `${minArgs}-${expectedParamCount} arg(s)`),
                     actual: argCount,
                     args: analysis.args,
+                    problem: bindingProblems.join('; '),
                     patterns: patternFlagsFrom(analysis),
                     ...carry,
                 });
             }
+            continue;
         }
+
+        valid.push({
+            file: call.relativePath,
+            line: call.line,
+            patterns: patternFlagsFrom(analysis),
+            ...carry,
+        });
     }
     clearTreeCache(index);
 
@@ -1415,7 +1550,10 @@ function verify(index, name, options = {}) {
         params: params.map(p => ({
             name: p.name,
             optional: p.optional || p.default !== undefined,
-            hasDefault: p.default !== undefined
+            hasDefault: p.default !== undefined,
+            // fix #281: binding-position markers (Python `*` / `/`)
+            ...(p.keywordOnly && { keywordOnly: true }),
+            ...(p.positionalOnly && { positionalOnly: true }),
         })),
         // max: null = unbounded (rest param) — typed for JSON consumers;
         // the text formatter renders it as `${min}+` (fix #230, was the

package/languages/index.js

@@ -55,6 +55,13 @@ const STRUCTURAL_TRAITS = {
     // Whether `Type(...)` constructs a class without a `new` token. Python
     // classes are ordinary callable objects; JS/TS classes require `new`.
     classesCallableWithoutNew: false,
+    // Whether call sites bind arguments by parameter NAME (Python keyword
+    // arguments). Drives verify/check keyword binding validation (fix #281):
+    // keyword names checked against the signature, keyword-only/positional-only
+    // markers honored, required coverage enforced. Languages without named
+    // arguments must stay false — a JS call with fewer args than params is
+    // legal, so required-coverage checks would false-flag.
+    keywordArguments: false,
 };
 const NOMINAL_TRAITS = {
     typeSystem: 'nominal',
@@ -64,6 +71,11 @@ const NOMINAL_TRAITS = {
     exportVisibility: 'keyword',
     hasDynamicImports: true,
     testDirs: [],
+    // Call sites don't bind arguments by parameter name here (see
+    // STRUCTURAL_TRAITS.keywordArguments — Python overrides true). C# HAS
+    // named arguments but its parser doesn't record them yet; the trait stays
+    // false there until that family is measured (fix #281, classified-deferred).
+    keywordArguments: false,
     // Go/Java/Rust have no default parameter values — see STRUCTURAL_TRAITS.
     hasDefaultParams: false,
     // Whether ANY instance method call can dynamically dispatch to a subtype
@@ -177,6 +189,9 @@ const LANGUAGES = {
             // from-imports bind values only (`import * as ns` is parser-marked).
             submoduleImports: true,
             classesCallableWithoutNew: true,
+            // Call sites bind by parameter name (f(x=1)); signatures carry
+            // keyword-only (`*`) and positional-only (`/`) markers (fix #281).
+            keywordArguments: true,
             testFileCandidates: (base, ext) => [`test_${base}.py`, `${base}_test.py`],
             testDirs: ['tests'],
         },

package/languages/utils.js

@@ -80,10 +80,29 @@ function parseStructuredParams(paramsNode, language) {
         return params;
     }
 
+    // Python binding-position markers (fix #281): a bare `*` makes every later
+    // param keyword-only, a bare `/` makes every earlier param positional-only,
+    // and `*args` plays the same separator role as `*`. Dropping them collapsed
+    // `f(a, *, b)` to `f(a, b)` and verify green-lit guaranteed TypeErrors.
+    let pyKeywordOnly = false;
+
     for (let i = 0; i < paramsNode.namedChildCount; i++) {
         const param = paramsNode.namedChild(i);
         const paramInfo = {};
 
+        if (language === 'python') {
+            if (param.type === 'keyword_separator') {
+                pyKeywordOnly = true;
+                continue;
+            }
+            if (param.type === 'positional_separator') {
+                for (const prev of params) {
+                    if (!prev.rest) prev.positionalOnly = true;
+                }
+                continue;
+            }
+        }
+
         // Different handling per language
         if (language === 'javascript' || language === 'typescript' || language === 'tsx') {
             parseJSParam(param, paramInfo);
@@ -98,6 +117,13 @@ function parseStructuredParams(paramsNode, language) {
         }
 
         if (paramInfo.name) {
+            if (language === 'python') {
+                if (pyKeywordOnly && !paramInfo.rest) paramInfo.keywordOnly = true;
+                // `*args` ends the positional section exactly like a bare `*`.
+                if (paramInfo.rest && /^\*(?!\*)/.test(String(paramInfo.name))) {
+                    pyKeywordOnly = true;
+                }
+            }
             params.push(paramInfo);
             // Go multi-name declarations: `a, b int` → expand additional params
             if (paramInfo._additionalNames) {

package/mcp/server.js

@@ -133,17 +133,12 @@ function toolResult(text, command, maxChars, suffixNote, params = {}) {
         surface: 'mcp',
         params,
     });
-    const response = { content: [{ type: 'text', text: budget.text + suffix }] };
-    if (budget.truncated) {
-        response.structuredContent = {
-            truncated: true,
-            fullChars: budget.fullChars,
-            requestedLimit: budget.requestedLimit,
-            contractMetadata: budget.contractMetadata,
-            contractMetadataComplete: budget.contractMetadataComplete,
-        };
-    }
-    return response;
+    // The text block is the ONLY payload channel. Truncation facts live in the
+    // text itself (the OUTPUT TRUNCATED notice carries full size, limit, and
+    // narrowing hints; preserved contract lines follow). A structuredContent
+    // side-channel is rendered INSTEAD of content by MCP clients that prefer
+    // structured results, which discards the entire answer (fix #284).
+    return { content: [{ type: 'text', text: budget.text + suffix }] };
 }
 
 function toolError(message) {
@@ -324,7 +319,7 @@ server.registerTool(
             line: z.number().int().positive().optional().describe('Definition line pin. Resolves the symbol defined at this exact line (the middle component of a file:line:name handle). Disambiguates same-file same-name definitions.'),
             limit: z.number().int().positive().max(1000000).optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, and repo files. Must be a positive integer.'),
             max_files: z.number().int().positive().max(10000000).optional().describe('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.'),
-            max_chars: z.number().int().positive().max(100000).optional().describe('Max output chars before truncation. Targeted commands default to 10K; broad commands default to 3K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.'),
+            max_chars: z.number().int().positive().max(100000).optional().describe('Max output chars before truncation. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.'),
             // Structural search flags (search command)
             type: z.string().optional().describe('Symbol type filter for structural search: function, class, call, method, type, state, field, constant, macro. Triggers index-based search.'),
             param: z.string().optional().describe('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "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",