ucn 3.4.6 → 3.4.8

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

@@ -81,15 +81,15 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 
 | Situation | Command | What it does |
 |-----------|---------|-------------|
-| Need function + all its helpers inline | `ucn smart <name>` | Returns function source with every helper it calls expanded below it |
+| Need function + all its helpers inline | `ucn smart <name>` | Returns function source with every helper it calls expanded below it. Use instead of `about` when you need code, not metadata |
 | Checking if a refactor broke signatures | `ucn verify <name>` | Validates all call sites match the function's parameter count |
 | Understanding a file's role in the project | `ucn imports <file>` | What it depends on |
 | Understanding who depends on a file | `ucn exporters <file>` | Which files import it |
 | Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
 | Finding all usages (not just calls) | `ucn usages <name>` | Groups into: definitions, calls, imports, type references |
-| Finding related code to refactor together | `ucn related <name>` | Functions sharing dependencies or in same file |
+| Finding sibling/related functions | `ucn related <name>` | Name-based + structural matching (same file, shared deps). Not semantic — best for parse/format pairs |
 | Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
-| Dependency tree for a file | `ucn graph <file> --depth=2` | Visual import tree |
+| File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Can be noisy — use depth=1 for large/tightly-coupled projects. For function-level flow, use `trace` instead |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
 
 ## Command Format

package/core/discovery.js

@@ -95,7 +95,7 @@ const TEST_PATTERNS = {
     python: [
         /^test_.*\.py$/,
         /.*_test\.py$/,
-        /\/tests?\//
+        /(^|\/)tests?\//
     ],
     go: [
         /.*_test\.go$/
@@ -107,7 +107,7 @@ const TEST_PATTERNS = {
     ],
     rust: [
         /.*_test\.rs$/,
-        /\/tests\//
+        /(^|\/)tests\//
     ]
 };
 

package/core/project.js

@@ -2127,12 +2127,22 @@ class ProjectIndex {
 
                 // Python: Magic/dunder methods are called by the interpreter, not user code
                 // test_* functions/methods are called by pytest/unittest via reflection
+                // setUp/tearDown are unittest.TestCase framework methods called by test runner
+                // pytest_* are pytest plugin hooks called by the framework
                 const isPythonEntryPoint = lang === 'python' &&
-                    (/^__\w+__$/.test(name) || /^test_/.test(name));
+                    (/^__\w+__$/.test(name) || /^test_/.test(name) ||
+                     /^(setUp|tearDown)(Class|Module)?$/.test(name) ||
+                     /^pytest_/.test(name));
 
-                // Rust: main() is entry point, #[test] functions are called by test runner
+                // Rust: main() is entry point, #[test] and #[bench] functions are called by test/bench runner
                 const isRustEntryPoint = lang === 'rust' &&
-                    (name === 'main' || mods.includes('test'));
+                    (name === 'main' || mods.includes('test') || mods.includes('bench'));
+
+                // Rust: trait impl methods are invoked via trait dispatch, not direct calls
+                // They can never be "dead" - the trait contract requires them to exist
+                // className for trait impls contains " for " (e.g., "PartialEq for Glob")
+                const isRustTraitImpl = lang === 'rust' && symbol.isMethod &&
+                    symbol.className && symbol.className.includes(' for ');
 
                 // Go: Test*, Benchmark*, Example* functions are called by go test
                 const isGoTestFunc = lang === 'go' &&
@@ -2141,6 +2151,15 @@ class ProjectIndex {
                 // Java: @Test annotated methods are called by JUnit
                 const isJavaTestMethod = lang === 'java' && mods.includes('test');
 
+                // Java: @Override methods are invoked via polymorphic dispatch
+                // They implement interface/superclass contracts and can't be dead
+                const isJavaOverride = lang === 'java' && mods.includes('override');
+
+                // Skip trait impl / @Override methods entirely - they're required by the type system
+                if (isRustTraitImpl || isJavaOverride) {
+                    continue;
+                }
+
                 const isEntryPoint = isGoEntryPoint || isGoTestFunc ||
                     isJavaEntryPoint || isJavaTestMethod ||
                     isPythonEntryPoint || isRustEntryPoint;

package/mcp/server.js

@@ -807,7 +807,7 @@ server.registerTool(
 server.registerTool(
     'ucn_about',
     {
-        description: 'Everything about a code symbol: definition, source code, callers, callees, tests. First stop when investigating any function or class. Works on JS/TS, Python, Go, Rust, Java.',
+        description: 'Everything about a symbol in one call: definition, source code, callers, callees, tests. START HERE when investigating any function or class — replaces 3-4 grep+read cycles. For narrower views, use ucn_context (callers/callees only), ucn_smart (code + dependencies), or ucn_impact (call sites for refactoring).',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -832,7 +832,7 @@ server.registerTool(
 server.registerTool(
     'ucn_context',
     {
-        description: 'Quick view of who calls a function and what it calls. Shows callers and callees with file locations and call weights.',
+        description: 'Lightweight caller/callee list with numbered items. Use when you just need "who calls X and what does X call" without full source code. Items are numbered — use ucn_expand to drill into any item. For the full picture (code + tests + everything), use ucn_about instead.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -866,7 +866,7 @@ server.registerTool(
 server.registerTool(
     'ucn_impact',
     {
-        description: 'Before changing a function, see every call site grouped by file. Shows arguments used at each call site. Essential for signature changes.',
+        description: 'Every call site of a function, grouped by file, with the actual arguments used at each site. Use BEFORE changing a function signature — shows exactly what will break. For a lighter caller list without arguments, use ucn_context.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -890,7 +890,7 @@ server.registerTool(
 server.registerTool(
     'ucn_smart',
     {
-        description: 'Function source code with all its dependencies expanded inline. Everything you need to understand or modify a function in one response.',
+        description: 'Function source code with all its dependencies expanded inline. Use when you need to read or modify a function and want its helpers included — saves multiple file reads. For call relationships without source code, use ucn_context.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -922,7 +922,7 @@ server.registerTool(
 server.registerTool(
     'ucn_trace',
     {
-        description: 'Call tree visualization showing execution flow. Traces what a function calls, what those call, etc. Depth-limited.',
+        description: 'Call tree visualization showing execution flow from a function downward. Maps architecture — shows which modules a pipeline touches. For file-level dependency trees, use ucn_graph instead.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -1180,7 +1180,7 @@ server.registerTool(
 server.registerTool(
     'ucn_related',
     {
-        description: 'Find functions related to a symbol: same file, similar names, shared callers/callees. Useful for discovering associated code.',
+        description: 'Find structurally related functions: same file, similar names, shared callers/callees. Results are name-based and structural, not semantic — best for finding sibling functions (e.g. parse/format pairs) rather than conceptually related code.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             name: nameParam,
@@ -1204,7 +1204,7 @@ server.registerTool(
 server.registerTool(
     'ucn_graph',
     {
-        description: 'Dependency graph for a file. Shows import/export tree as a visual hierarchy.',
+        description: 'File-level dependency graph showing import/export relationships between files. Best for understanding module structure. Can be noisy in tightly-coupled projects — use depth=1 for large codebases. For function-level execution flow, use ucn_trace instead.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             file: z.string().describe('File path (relative to project root or absolute) to graph dependencies for'),
@@ -1490,7 +1490,7 @@ server.registerTool(
 server.registerTool(
     'ucn_api',
     {
-        description: 'Show exported/public symbols in the project or a specific file. Lists the public API surface.',
+        description: 'Show exported/public symbols in the project. Works best with JS/TS (export keyword), Go (capitalized names), Rust (pub), Java (public). For Python, requires __all__ — projects without it will return empty results. Use ucn_toc for a general overview instead.',
         inputSchema: z.object({
             project_dir: projectDirParam,
             file: z.string().optional().describe('Optional file path to show exports for (relative to project root)')

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ucn",
-  "version": "3.4.6",
+  "version": "3.4.8",
   "description": "Code navigation built by AI, for AI. Reduces context usage when working with large codebases.",
   "main": "index.js",
   "bin": {
-    "ucn": "./cli/index.js",
-    "ucn-mcp": "./mcp/server.js"
+    "ucn": "cli/index.js",
+    "ucn-mcp": "mcp/server.js"
   },
   "scripts": {
     "test": "node --test test/parser.test.js"

package/test/parser.test.js

@@ -6631,5 +6631,252 @@ module.exports = { usedUtil };
     });
 });
 
+// Regression: Rust trait impl methods should not appear as deadcode
+describe('Regression: deadcode skips Rust trait impl methods', () => {
+    it('should not report trait impl methods as dead code', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-test-rust-trait-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'Cargo.toml'), '[package]\nname = "test"\nversion = "0.1.0"');
+            fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+            // A struct with an inherent impl and a trait impl
+            fs.writeFileSync(path.join(tmpDir, 'src', 'main.rs'), `
+struct Foo {
+    val: i32,
+}
+
+impl Foo {
+    fn new(val: i32) -> Self {
+        Foo { val }
+    }
+
+    fn unused_method(&self) -> i32 {
+        self.val
+    }
+}
+
+impl std::fmt::Display for Foo {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        write!(f, "{}", self.val)
+    }
+}
+
+impl PartialEq for Foo {
+    fn eq(&self, other: &Self) -> bool {
+        self.val == other.val
+    }
+}
+
+fn main() {
+    let f = Foo::new(42);
+}
+`);
+            const idx = new ProjectIndex(tmpDir);
+            idx.build(null, { quiet: true });
+            const dead = idx.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // Trait impl methods should NOT appear
+            assert.ok(!deadNames.includes('fmt'), 'fmt (trait impl) should not be dead code');
+            assert.ok(!deadNames.includes('eq'), 'eq (trait impl) should not be dead code');
+
+            // Genuinely unused inherent method SHOULD appear
+            assert.ok(deadNames.includes('unused_method'), 'unused_method should be dead code');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+// Regression: Rust #[bench] functions should be treated as entry points
+describe('Regression: deadcode treats Rust #[bench] as entry points', () => {
+    it('should not report #[bench] functions as dead code', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-test-rust-bench-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'Cargo.toml'), '[package]\nname = "test"\nversion = "0.1.0"');
+            fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+            fs.mkdirSync(path.join(tmpDir, 'benches'), { recursive: true });
+            fs.writeFileSync(path.join(tmpDir, 'src', 'main.rs'), `
+fn main() {}
+
+fn helper() -> i32 { 42 }
+`);
+            fs.writeFileSync(path.join(tmpDir, 'benches', 'my_bench.rs'), `
+#![feature(test)]
+extern crate test;
+use test::Bencher;
+
+#[bench]
+fn bench_something(b: &mut Bencher) {
+    b.iter(|| 1 + 1);
+}
+
+fn unused_bench_helper() -> i32 {
+    42
+}
+`);
+            const idx = new ProjectIndex(tmpDir);
+            idx.build(null, { quiet: true });
+            const dead = idx.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // #[bench] should NOT appear as dead code
+            assert.ok(!deadNames.includes('bench_something'), 'bench_something should not be dead code');
+
+            // Genuinely unused function SHOULD appear
+            assert.ok(deadNames.includes('unused_bench_helper'), 'unused_bench_helper should be dead code');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+// Regression: test file patterns should match relative paths starting with tests/
+describe('Regression: test file patterns match relative paths', () => {
+    it('should detect tests/ at start of relative path for Python', () => {
+        const { isTestFile } = require('../core/discovery');
+        // Relative paths starting with tests/ should match
+        assert.ok(isTestFile('tests/test_app.py', 'python'),
+            'tests/test_app.py should be a test file');
+        assert.ok(isTestFile('tests/helpers/factory.py', 'python'),
+            'tests/helpers/factory.py should be a test file');
+        // Subdirectory should still work
+        assert.ok(isTestFile('src/tests/test_util.py', 'python'),
+            'src/tests/test_util.py should be a test file');
+        // Non-test paths should not match
+        assert.ok(!isTestFile('src/utils.py', 'python'),
+            'src/utils.py should not be a test file');
+    });
+
+    it('should detect tests/ at start of relative path for Rust', () => {
+        const { isTestFile } = require('../core/discovery');
+        assert.ok(isTestFile('tests/integration.rs', 'rust'),
+            'tests/integration.rs should be a test file');
+        assert.ok(isTestFile('tests/examples/hello.rs', 'rust'),
+            'tests/examples/hello.rs should be a test file');
+        // Non-test paths should not match
+        assert.ok(!isTestFile('src/lib.rs', 'rust'),
+            'src/lib.rs should not be a test file');
+    });
+});
+
+// Regression: Java @Override methods should not appear as deadcode
+describe('Regression: deadcode skips Java @Override methods', () => {
+    it('should not report @Override methods as dead code', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-test-java-override-'));
+        try {
+            fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+            fs.writeFileSync(path.join(tmpDir, 'pom.xml'), '<project></project>');
+            fs.writeFileSync(path.join(tmpDir, 'src', 'MyClass.java'), `
+public class MyClass implements Runnable {
+    @Override
+    public void run() {
+        System.out.println("running");
+    }
+
+    @Override
+    public String toString() {
+        return "MyClass";
+    }
+
+    void unusedMethod() {
+        System.out.println("unused");
+    }
+
+    public static void main(String[] args) {
+        new MyClass().run();
+    }
+}
+`);
+            const idx = new ProjectIndex(tmpDir);
+            idx.build(null, { quiet: true });
+            const dead = idx.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // @Override methods should NOT appear
+            assert.ok(!deadNames.includes('run'), 'run (@Override) should not be dead code');
+            assert.ok(!deadNames.includes('toString'), 'toString (@Override) should not be dead code');
+
+            // Genuinely unused method SHOULD appear
+            assert.ok(deadNames.includes('unusedMethod'), 'unusedMethod should be dead code');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+// Regression: Python setUp/tearDown and pytest_* should be entry points
+describe('Regression: deadcode treats Python framework methods as entry points', () => {
+    it('should not report setUp/tearDown as dead code', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-test-py-setup-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'pyproject.toml'), '[project]\nname = "test"');
+            // setUp/tearDown in a non-test file (e.g., scripts/ directory)
+            fs.writeFileSync(path.join(tmpDir, 'release_tests.py'), `
+import unittest
+
+class TestFoo(unittest.TestCase):
+    def setUp(self):
+        self.x = 42
+
+    def tearDown(self):
+        pass
+
+    def test_something(self):
+        assert self.x == 42
+`);
+            // Separate non-test file with genuinely unused code
+            fs.writeFileSync(path.join(tmpDir, 'utils.py'), `
+def unused_helper():
+    return 1
+`);
+            const idx = new ProjectIndex(tmpDir);
+            idx.build(null, { quiet: true });
+            const dead = idx.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // Framework methods should NOT appear (even in non-test files)
+            assert.ok(!deadNames.includes('setUp'), 'setUp should not be dead code');
+            assert.ok(!deadNames.includes('tearDown'), 'tearDown should not be dead code');
+            assert.ok(!deadNames.includes('test_something'), 'test_something should not be dead code');
+
+            // Genuinely unused function SHOULD appear
+            assert.ok(deadNames.includes('unused_helper'), 'unused_helper should be dead code');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+
+    it('should not report pytest_* hooks as dead code', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-test-py-pytest-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'pyproject.toml'), '[project]\nname = "test"');
+            fs.writeFileSync(path.join(tmpDir, 'conftest.py'), `
+def pytest_configure(config):
+    config.addinivalue_line("markers", "slow: slow test")
+
+def pytest_collection_modifyitems(config, items):
+    pass
+
+def unused_function():
+    return 1
+`);
+            const idx = new ProjectIndex(tmpDir);
+            idx.build(null, { quiet: true });
+            const dead = idx.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // pytest hooks should NOT appear
+            assert.ok(!deadNames.includes('pytest_configure'), 'pytest_configure should not be dead code');
+            assert.ok(!deadNames.includes('pytest_collection_modifyitems'),
+                'pytest_collection_modifyitems should not be dead code');
+
+            // Genuinely unused function SHOULD appear
+            assert.ok(deadNames.includes('unused_function'), 'unused_function should be dead code');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
 console.log('UCN v3 Test Suite');
 console.log('Run with: node --test test/parser.test.js');