ucn 5.2.2 → 5.3.0

package/languages/python.js

@@ -2936,20 +2936,123 @@ function findImportsInCode(code, parser) {
     // module initialization. Preserve that AST fact so dependency-cycle
     // reporting can distinguish an eager import loop from a deliberate lazy
     // edge without deleting either edge from the graph.
-    const isDeferredImport = (node) => {
+    // fix #338: `if TYPE_CHECKING:` (bare, `t.TYPE_CHECKING`,
+    // `typing.TYPE_CHECKING`) consequence blocks never execute at runtime —
+    // the import exists for the type checker only. Only the consequence
+    // branch is guarded: `else:` and `if not TYPE_CHECKING:` bodies DO run.
+    let typingBindings = null;
+    let typingWildcard = false;
+    const isNestedScope = node => {
+        for (let p = node.parent; p; p = p.parent) {
+            if (p.type === 'function_definition' || p.type === 'class_definition' || p.type === 'lambda') return true;
+        }
+        return false;
+    };
+    // Which local names prove a runtime-false guard, and where. A guard at
+    // module level reads the module binding: only module-level rebindings
+    // (assignments, loops, def/class names, walrus, `as` targets) and a
+    // second import of the same name can disturb it — a function parameter
+    // or a nested import lives in its own scope. A guard INSIDE a function
+    // can additionally be shadowed by that function's locals, so nested
+    // rebindings poison nested guards (conservative: any nested scope, not
+    // just the enclosing one). Same-spelled user flags/attributes can be
+    // true; only a unique `typing` binding proves the guard false.
+    const typingBindingKind = (name, guardNested) => {
+        if (!typingBindings) {
+            typingBindings = new Map();
+            const entry = local => {
+                let e = typingBindings.get(local);
+                if (!e) { e = { kind: null, imports: 0, moduleShadow: false, nestedShadow: false }; typingBindings.set(local, e); }
+                return e;
+            };
+            const shadow = (pattern, nested) => {
+                if (!pattern) return;
+                traverseTree(pattern, child => {
+                    if (child.type === 'identifier') {
+                        const e = entry(child.text);
+                        if (nested) e.nestedShadow = true; else e.moduleShadow = true;
+                    }
+                    return true;
+                });
+            };
+            traverseTree(tree.rootNode, n => {
+                const nested = isNestedScope(n);
+                if (n.type === 'import_statement' || n.type === 'import_from_statement') {
+                    if (n.namedChildren.some(item => item.type === 'wildcard_import')) typingWildcard = true;
+                    const moduleNode = n.childForFieldName('module_name');
+                    for (const item of n.namedChildren) {
+                        if (moduleNode && sameNode(moduleNode, item)) continue;
+                        const imported = item.type === 'aliased_import' ? item.childForFieldName('name')?.text : item.text;
+                        const local = item.type === 'aliased_import' ? item.childForFieldName('alias')?.text : imported?.split('.')[0];
+                        if (!local) continue;
+                        const e = entry(local);
+                        if (nested) { e.nestedShadow = true; continue; }
+                        const kind = n.type === 'import_statement'
+                            ? (imported === 'typing' ? 'module' : null)
+                            : (moduleNode?.text === 'typing' && imported === 'TYPE_CHECKING' ? 'flag' : null);
+                        e.imports++;
+                        e.kind = e.imports === 1 ? kind : null;
+                    }
+                } else if (n.type === 'assignment' || n.type === 'augmented_assignment' || n.type === 'for_statement' || n.type === 'for_in_clause') {
+                    shadow(n.childForFieldName('left'), nested);
+                } else if (n.type === 'parameters' || n.type === 'lambda_parameters') {
+                    // Parameter NAMES rebind; annotations (`x: t.Any`) and
+                    // default values are expressions that READ the outer
+                    // binding. Walking the whole subtree treated every
+                    // `t.`-annotated parameter as a rebinding of `t` and
+                    // reverted click's TYPE_CHECKING guards to eager.
+                    for (const param of n.namedChildren) {
+                        if (param.type === 'default_parameter' || param.type === 'typed_default_parameter') {
+                            shadow(param.childForFieldName('name'), true);
+                        } else if (param.type === 'typed_parameter') {
+                            shadow(param.namedChild(0), true);
+                        } else if (param.type !== 'keyword_separator' && param.type !== 'positional_separator') {
+                            shadow(param, true);
+                        }
+                    }
+                } else if (n.type === 'named_expression') shadow(n.childForFieldName('name'), nested);
+                else if (n.type === 'function_definition' || n.type === 'class_definition') shadow(n.childForFieldName('name'), nested);
+                else if (n.type === 'as_pattern') shadow(n.childForFieldName('alias'), nested);
+                return true;
+            });
+        }
+        if (typingWildcard) return null;
+        const e = typingBindings.get(name);
+        if (!e || e.imports !== 1 || e.moduleShadow) return null;
+        if (guardNested && e.nestedShadow) return null;
+        return e.kind;
+    };
+    const isTypeCheckingGuard = (condition, guardNested = true) => {
+        if (!condition) return false;
+        if (condition.type === 'parenthesized_expression') return isTypeCheckingGuard(condition.namedChild(0), guardNested);
+        if (condition.type === 'identifier') return typingBindingKind(condition.text, guardNested) === 'flag';
+        if (condition.type === 'attribute') {
+            const object = condition.childForFieldName('object');
+            return condition.childForFieldName('attribute')?.text === 'TYPE_CHECKING' &&
+                object?.type === 'identifier' && typingBindingKind(object.text, guardNested) === 'module';
+        }
+        return false;
+    };
+    const importDeferral = (node) => {
         for (let parent = node.parent; parent; parent = parent.parent) {
             if (parent.type === 'function_definition' || parent.type === 'lambda') {
-                return true;
+                return 'function-local';
+            }
+            if (parent.type === 'block' && parent.parent &&
+                (parent.parent.type === 'if_statement' || parent.parent.type === 'elif_clause') &&
+                sameNode(parent.parent.childForFieldName('consequence'), parent) &&
+                isTypeCheckingGuard(parent.parent.childForFieldName('condition'), isNestedScope(parent.parent))) {
+                return 'type-checking';
             }
         }
-        return false;
+        return null;
     };
 
     traverseTreeCached(tree.rootNode, (node) => {
         // import statement: import os, import sys as system
         if (node.type === 'import_statement') {
             const line = node.startPosition.row + 1;
-            const deferred = isDeferredImport(node);
+            const deferral = importDeferral(node);
 
             for (let i = 0; i < node.namedChildCount; i++) {
                 const child = node.namedChild(i);
@@ -2966,14 +3069,14 @@ function findImportsInCode(code, parser) {
                             names: [parts[0]],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                         imports.push({
                             module: child.text,
                             names: [],
                             type: 'import-submodule',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                     } else {
                         imports.push({
@@ -2981,7 +3084,7 @@ function findImportsInCode(code, parser) {
                             names: [child.text],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                     }
                 } else if (child.type === 'aliased_import') {
@@ -2994,7 +3097,7 @@ function findImportsInCode(code, parser) {
                             names: [aliasNode ? aliasNode.text : nameNode.text.split('.').pop()],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                         if (aliasNode && aliasNode.text !== nameNode.text) {
                             if (!importAliases) importAliases = [];
@@ -3009,7 +3112,7 @@ function findImportsInCode(code, parser) {
         // from ... import statement
         if (node.type === 'import_from_statement') {
             const line = node.startPosition.row + 1;
-            const deferred = isDeferredImport(node);
+            const deferral = importDeferral(node);
             let modulePath = '';
             const names = [];
 
@@ -3043,7 +3146,7 @@ function findImportsInCode(code, parser) {
                     names,
                     type: isRelative ? 'relative' : 'from',
                     line,
-                    ...(deferred && { deferred: true })
+                    ...(deferral && { deferred: true, deferredReason: deferral })
                 });
             }
             return true;
@@ -3058,7 +3161,7 @@ function findImportsInCode(code, parser) {
                 const firstArg = argsNode.namedChild(0);
                 if ((funcName === 'importlib.import_module' || funcName === '__import__') && firstArg) {
                     const line = node.startPosition.row + 1;
-                    const deferred = isDeferredImport(node);
+                    const deferral = importDeferral(node);
                     const isLiteral = firstArg.type === 'string';
                     imports.push({
                         module: isLiteral ? firstArg.text.replace(/^['"]|['"]$/g, '') : firstArg.text,
@@ -3066,7 +3169,7 @@ function findImportsInCode(code, parser) {
                         type: 'dynamic',
                         line,
                         dynamic: !isLiteral,
-                        ...(deferred && { deferred: true })
+                        ...(deferral && { deferred: true, deferredReason: deferral })
                     });
                 }
             }

package/mcp/server.js

@@ -271,7 +271,7 @@ const INPUT_SHAPE = {
     include_exported: booleanParam('Include exported symbols in deadcode results'),
     include_decorated: booleanParam('Include decorated/annotated symbols in deadcode results'),
     calls_only: booleanParam('tests: retain direct calls and test-case matches only.'),
-    max_lines: integerParam('source: maximum lines for large class-like declarations.', { exclusiveMinimum: 0, maximum: 1000000 }),
+    max_lines: integerParam('source: maximum lines per declaration; raw mode discloses any truncation.', { exclusiveMinimum: 0, maximum: 1000000 }),
     direction: stringParam('trace: callees/callers. deps: imports/importers/both.', { enum: ['callees', 'callers', 'imports', 'importers', 'both'] }),
     to: stringParam('trace with direction=callers: continue toward entry points.', { enum: ['entrypoints'] }),
     cycles: booleanParam('deps: report circular imports instead of a file graph.'),
@@ -280,6 +280,8 @@ const INPUT_SHAPE = {
     functions: booleanParam('repo stats: include per-function line counts sorted by size.'),
     hot: booleanParam('repo stats: include the top N most-called functions.'),
     diverse: booleanParam('show example: return representatives from distinct argument shapes.'),
+    lines: booleanParam('find/usages/search/show/impact: path:line:text listings without default row caps; explicit top/limit still apply. show accepts callers/callees sections, default callers. Tier tags follow a tab; accounting and notes follow as "# " lines. MCP transport budgets still apply and preserve accounting.'),
+    raw: booleanParam('source: code text without a header or line-number gutter, including full large classes. Notes follow as "# " lines; MCP transport budgets still apply.'),
     git: booleanParam('show summary: attach last-modified, author, and recent-change metadata.'),
     add_param: stringParam('Parameter name to add (plan command)'),
     remove_param: stringParam('Parameter name to remove (plan command)'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.2.2",
+  "version": "5.3.0",
   "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",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "version": "node scripts/sync-server-version.js && git add server.json",
-    "test": "node --test test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-c-family.test.js test/regression-cross.test.js test/regression-mcp.test.js test/mcp-protocol.test.js test/mcp-sdk-compat.test.js test/dependency-security.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/release-surface-regressions.test.js test/prerelease-audit.test.js test/release-readiness-audit.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/perf-optimizations.test.js test/performance-gate-policy.test.js test/oracle-gate-policy.test.js test/outcome-policy.test.js test/consistency-eval.test.js test/agent-public-surface-benchmark.test.js test/command-contracts.test.js test/language-adapter.test.js test/systematic-test.js test/mcp-edge-cases.js test/conservation.test.js test/parity-test.js test/trust-matrix.test.js",
+    "test": "node --test test/shell-output.test.js test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-c-family.test.js test/regression-cross.test.js test/regression-mcp.test.js test/mcp-protocol.test.js test/mcp-sdk-compat.test.js test/dependency-security.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/release-surface-regressions.test.js test/prerelease-audit.test.js test/release-readiness-audit.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/perf-optimizations.test.js test/performance-gate-policy.test.js test/oracle-gate-policy.test.js test/outcome-policy.test.js test/consistency-eval.test.js test/agent-public-surface-benchmark.test.js test/command-contracts.test.js test/language-adapter.test.js test/systematic-test.js test/mcp-edge-cases.js test/conservation.test.js test/parity-test.js test/trust-matrix.test.js",
     "benchmark:agent": "node test/agent-public-surface-benchmark.js",
     "benchmark:agent:gate": "node test/agent-public-surface-benchmark.js --gate",
     "benchmark:agent:legacy": "node test/agent-understanding-benchmark.js",

package/assets/demo.svg

@@ -1,31 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 453" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace" font-size="12">
-  <!-- Terminal window -->
-  <rect x="0.5" y="0.5" width="999" height="452" rx="10" fill="#0d1117" stroke="#30363d"/>
-  <!-- Title bar -->
-  <path d="M0.5 10.5 a10 10 0 0 1 10 -10 h979 a10 10 0 0 1 10 10 v23 h-999 z" fill="#161b22"/>
-  <line x1="0.5" y1="34" x2="999.5" y2="34" stroke="#30363d"/>
-  <circle cx="20" cy="17" r="6" fill="#ff5f57"/>
-  <circle cx="40" cy="17" r="6" fill="#febc2e"/>
-  <circle cx="60" cy="17" r="6" fill="#28c840"/>
-  <text x="500" y="21" text-anchor="middle" fill="#8b949e" font-size="11.5">ucn - ripgrep @ 82313cf9 (pinned oracle commit) - output abridged</text>
-  <!-- Session -->
-  <g fill="#c9d1d9">
-    <text x="24" y="62"><tspan fill="#8b949e">$ </tspan><tspan fill="#7ee787">ucn show Searcher.search_reader --sections=summary,callers --compact</tspan></text>
-    <text x="24" y="100">SUMMARY</text>
-    <text x="24" y="119">───────</text>
-    <text x="24" y="138">pub search_reader&lt;M, R, S&gt;(&amp;mut self, matcher: M, read_from: R, write_to: S): Result&lt;(), S::Error&gt;</text>
-    <text x="39" y="157">crates/searcher/src/searcher/mod.rs:727-765  (39 lines)</text>
-    <text x="39" y="176">handle: crates/searcher/src/searcher/mod.rs:727:search_reader</text>
-    <text x="39" y="195">"Execute a search over any implementation of `std::io::Read` and write"</text>
-    <text x="24" y="233">CALLERS — CONFIRMED (123):</text>
-    <text x="39" y="252">evidence: 2 exact-binding, 121 receiver-hint</text>
-    <text x="39" y="271">[1] crates/core/search.rs:426 [search_reader]: searcher.search_reader(&amp;matcher, &amp;mut rdr, &amp;mut sink)?;</text>
-    <text x="39" y="290">[4] crates/printer/src/json.rs:940 [binary_detection]: .search_reader(&amp;matcher, BINARY, printer.sink(&amp;matcher))</text>
-    <text x="39" y="309">[11] crates/printer/src/standard.rs:1788 [reports_match]: .search_reader(&amp;matcher, SHERLOCK.as_bytes(), &amp;mut sink)</text>
-    <text x="69" y="328" fill="#8b949e">… 120 more callers</text>
-    <text x="24" y="366">ACCOUNT: "search_reader" occurs on 136 lines in 8 files: 123 confirmed, 1 unverified,</text>
-    <text x="39" y="385">6 non-call, 6 other-target, 0 unaccounted</text>
-    <text x="24" y="404">CONTRACT: literal-name text partition complete; semantic completeness is not claimed.</text>
-    <text x="24" y="433"><tspan fill="#8b949e">$ </tspan><tspan fill="#c9d1d9">▍</tspan></text>
-  </g>
-</svg>