ucn 3.4.5 → 3.4.6

package/README.md

@@ -155,125 +155,11 @@ ucn verify the_function                 # Did all call sites survive?
 ucn deadcode --exclude=test             # What can be deleted?
 ucn toc                                 # Project overview
 ```
+
 ## Supported Languages
 
 JavaScript, TypeScript, Python, Go, Rust, Java
 
-## Install
-
-```bash
-npm install -g ucn
-```
-
-### MCP Server
-
-UCN includes a built-in [MCP](https://modelcontextprotocol.io) server, so any MCP-compatible AI client can use it as a tool.
-
-**Claude Code** (`~/.claude/mcp-config.json`):
-```json
-{
-  "mcpServers": {
-    "ucn": {
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-**Claude Desktop** (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "ucn": {
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json` in project):
-```json
-{
-  "mcpServers": {
-    "ucn": {
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
-```json
-{
-  "mcpServers": {
-    "ucn": {
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-**VS Code Copilot** (`.vscode/mcp.json`):
-```json
-{
-  "servers": {
-    "ucn": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-**Zed** (Settings > `settings.json`):
-```json
-{
-  "context_servers": {
-    "ucn": {
-      "command": "npx",
-      "args": ["-y", "ucn", "--mcp"]
-    }
-  }
-}
-```
-
-The MCP server exposes 27 tools: `ucn_about`, `ucn_context`, `ucn_impact`, `ucn_smart`, `ucn_trace`, `ucn_find`, `ucn_usages`, `ucn_toc`, `ucn_deadcode`, `ucn_fn`, `ucn_class`, `ucn_verify`, `ucn_imports`, `ucn_exporters`, `ucn_tests`, `ucn_related`, `ucn_graph`, `ucn_file_exports`, `ucn_search`, `ucn_plan`, `ucn_typedef`, `ucn_stacktrace`, `ucn_example`, `ucn_expand`, `ucn_lines`, `ucn_api`, `ucn_stats`.
-
-### Claude Code Skill (alternative)
-
-To use UCN as a skill in Claude Code (alternative to MCP):
-
-```bash
-mkdir -p ~/.claude/skills
-
-# If installed via npm:
-cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/
-
-# If cloned from git:
-git clone https://github.com/mleoca/ucn.git
-cp -r ucn/.claude/skills/ucn ~/.claude/skills/
-```
-
-### Codex (optional)
-
-To use UCN as a skill in OpenAI Codex:
-
-```bash
-mkdir -p ~/.agents/skills
-
-# If installed via npm:
-cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/
-
-# If cloned from git:
-git clone https://github.com/mleoca/ucn.git
-cp -r ucn/.claude/skills/ucn ~/.agents/skills/
-```
-
 ## Usage
 
 ```
@@ -368,6 +254,87 @@ Quick Start:
   ucn --interactive                   # Multiple queries
 ```
 
+## Install
+
+```bash
+npm install -g ucn
+```
+
+### MCP Server
+
+UCN includes a built-in [MCP](https://modelcontextprotocol.io) server, so any MCP-compatible AI client can use it as a tool. It exposes 27 tools (`ucn_about`, `ucn_context`, `ucn_impact`, `ucn_smart`, `ucn_trace`, `ucn_find`, `ucn_usages`, `ucn_toc`, `ucn_deadcode`, `ucn_fn`, `ucn_class`, `ucn_verify`, `ucn_imports`, `ucn_exporters`, `ucn_tests`, `ucn_related`, `ucn_graph`, `ucn_file_exports`, `ucn_search`, `ucn_plan`, `ucn_typedef`, `ucn_stacktrace`, `ucn_example`, `ucn_expand`, `ucn_lines`, `ucn_api`, `ucn_stats`).
+
+**One-line setup** (for clients that support it):
+
+| Client | Command |
+|--------|---------|
+| Claude Code | `claude mcp add ucn -- npx -y ucn --mcp` |
+| OpenAI Codex CLI | `codex mcp add ucn -- npx -y ucn --mcp` |
+| VS Code Copilot | `code --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'` |
+
+**Manual config** — add to the appropriate config file for your client:
+
+| Client | Config file |
+|--------|-------------|
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` in project |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | VS Code sidebar > MCP Servers > Configure |
+| Claude Code | `~/.claude/mcp-config.json` |
+
+```json
+{
+  "mcpServers": {
+    "ucn": {
+      "command": "npx",
+      "args": ["-y", "ucn", "--mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary>VS Code Copilot uses a slightly different format (<code>.vscode/mcp.json</code>)</summary>
+
+```json
+{
+  "servers": {
+    "ucn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "ucn", "--mcp"]
+    }
+  }
+}
+```
+</details>
+
+### Claude Code Skill (alternative to MCP)
+
+```bash
+mkdir -p ~/.claude/skills
+
+# If installed via npm:
+cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/
+
+# If cloned from git:
+git clone https://github.com/mleoca/ucn.git
+cp -r ucn/.claude/skills/ucn ~/.claude/skills/
+```
+
+### Codex Skill (alternative to MCP)
+
+```bash
+mkdir -p ~/.agents/skills
+
+# If installed via npm:
+cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/
+
+# If cloned from git:
+git clone https://github.com/mleoca/ucn.git
+cp -r ucn/.claude/skills/ucn ~/.agents/skills/
+```
+
 ## License
 
 MIT

package/core/project.js

@@ -1803,7 +1803,7 @@ class ProjectIndex {
         // Find all test files
         const testFiles = [];
         for (const [filePath, fileEntry] of this.files) {
-            if (isTestFile(filePath, fileEntry.language)) {
+            if (isTestFile(fileEntry.relativePath, fileEntry.language)) {
                 testFiles.push({ path: filePath, entry: fileEntry });
             }
         }
@@ -2108,14 +2108,13 @@ class ProjectIndex {
                     continue;
                 }
 
+                const fileEntry = this.files.get(symbol.file);
+                const lang = fileEntry?.language;
+
                 // Skip test files unless requested
-                if (!options.includeTests && isTestFile(symbol.file, symbol.language)) {
+                if (!options.includeTests && isTestFile(symbol.relativePath, lang)) {
                     continue;
                 }
-
-                // Check if exported
-                const fileEntry = this.files.get(symbol.file);
-                const lang = fileEntry?.language;
                 const mods = symbol.modifiers || [];
 
                 // Language-specific entry points (called by runtime, no AST-visible callers)
@@ -3653,7 +3652,7 @@ class ProjectIndex {
             totalState += state.length;
             totalLines += fileEntry.lines;
             totalDynamic += fileEntry.dynamicImports || 0;
-            if (isTestFile(filePath)) totalTests += 1;
+            if (isTestFile(fileEntry.relativePath, fileEntry.language)) totalTests += 1;
 
             const entry = {
                 file: fileEntry.relativePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.4.5",
+  "version": "3.4.6",
   "description": "Code navigation built by AI, for AI. Reduces context usage when working with large codebases.",
   "main": "index.js",
   "bin": {

package/test/mcp-edge-cases.js

@@ -3,7 +3,7 @@
 /**
  * MCP Server Edge Case Test Suite
  * 
- * Tests all 23 UCN MCP tools with null/crash safety, input validation,
+ * Tests UCN MCP tools with null/crash safety, input validation,
  * and normal operation edge cases.
  * 
  * Communicates with the MCP server over stdio using newline-delimited JSON-RPC.
@@ -13,7 +13,7 @@ const { spawn } = require('child_process');
 const path = require('path');
 
 const SERVER_PATH = path.join(__dirname, '..', 'mcp', 'server.js');
-const PROJECT_DIR = '/Users/mihail/ucn';
+const PROJECT_DIR = path.resolve(__dirname, '..');
 const TIMEOUT_MS = 30000;
 
 // ============================================================================
@@ -242,6 +242,25 @@ const tests = [
         args: { project_dir: PROJECT_DIR, file: 'nonexistent/path/to/file.js' }
     },
 
+    {
+        category: 'Null/Crash Safety',
+        tool: 'ucn_api',
+        desc: 'nonexistent file',
+        args: { project_dir: PROJECT_DIR, file: 'nonexistent/path/to/file.js' }
+    },
+    {
+        category: 'Null/Crash Safety',
+        tool: 'ucn_lines',
+        desc: 'nonexistent file',
+        args: { project_dir: PROJECT_DIR, file: 'nonexistent/path/to/file.js', range: '1-10' }
+    },
+    {
+        category: 'Null/Crash Safety',
+        tool: 'ucn_expand',
+        desc: 'no prior context call',
+        args: { project_dir: PROJECT_DIR, number: 1 }
+    },
+
     // ========================================================================
     // CATEGORY 2: Input Validation
     // ========================================================================
@@ -321,6 +340,24 @@ const tests = [
         desc: 'search for "TODO"',
         args: { project_dir: PROJECT_DIR, term: 'TODO' }
     },
+    {
+        category: 'Normal Operations',
+        tool: 'ucn_api',
+        desc: 'project API',
+        args: { project_dir: PROJECT_DIR }
+    },
+    {
+        category: 'Normal Operations',
+        tool: 'ucn_stats',
+        desc: 'project stats',
+        args: { project_dir: PROJECT_DIR }
+    },
+    {
+        category: 'Normal Operations',
+        tool: 'ucn_lines',
+        desc: 'extract lines 1-5 from discovery.js',
+        args: { project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-5' }
+    },
 ];
 
 // ============================================================================

package/test/parser.test.js

@@ -6392,5 +6392,244 @@ class DataService:
     });
 });
 
+// Regression: isTestFile should use relative paths, not absolute paths
+// Bug: When project lived at /Users/x/test/project/, the /test/ in the parent
+// path matched the Python test pattern /\/tests?\//, marking ALL files as test files.
+// This caused deadcode to either miss real dead code or produce false positives.
+describe('Regression: deadcode uses relative paths for isTestFile', () => {
+    it('should not treat non-test files as test files when project is inside a /test/ directory', () => {
+        // Simulate a project inside a directory named "test"
+        const tmpDir = path.join(os.tmpdir(), `ucn-test-relpath-${Date.now()}`, 'test', 'myproject');
+        const toolsDir = path.join(tmpDir, 'tools');
+        fs.mkdirSync(toolsDir, { recursive: true });
+
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'setup.py'), '');
+            fs.writeFileSync(path.join(toolsDir, '__init__.py'), '');
+            fs.writeFileSync(path.join(toolsDir, 'helper.py'), `
+def unused_helper():
+    return 42
+
+def used_helper():
+    return 1
+`);
+            fs.writeFileSync(path.join(tmpDir, 'main.py'), `
+from tools.helper import used_helper
+
+def main():
+    print(used_helper())
+`);
+
+            const index = new ProjectIndex(tmpDir);
+            index.build(null, { quiet: true });
+
+            const dead = index.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // unused_helper should be flagged as dead code
+            assert.ok(deadNames.includes('unused_helper'),
+                `unused_helper should be flagged as dead code, got: ${deadNames.join(', ')}`);
+
+            // used_helper should NOT be flagged
+            assert.ok(!deadNames.includes('used_helper'),
+                `used_helper should not be flagged as dead code`);
+        } finally {
+            fs.rmSync(path.join(os.tmpdir(), `ucn-test-relpath-${Date.now()}`), { recursive: true, force: true });
+            // Clean up the created dir tree
+            const topDir = tmpDir.split('/test/myproject')[0];
+            if (topDir.includes('ucn-test-relpath')) {
+                fs.rmSync(topDir, { recursive: true, force: true });
+            }
+        }
+    });
+
+    it('should correctly filter test files even when project is inside /test/ directory', () => {
+        const tmpDir = path.join(os.tmpdir(), `ucn-test-relpath2-${Date.now()}`, 'test', 'myproject');
+        const testsDir = path.join(tmpDir, 'tests');
+        fs.mkdirSync(testsDir, { recursive: true });
+
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'setup.py'), '');
+            fs.writeFileSync(path.join(tmpDir, 'app.py'), `
+def exported_func():
+    return 42
+
+def unused_func():
+    return 0
+`);
+            fs.writeFileSync(path.join(testsDir, 'test_app.py'), `
+from app import exported_func
+
+def test_exported():
+    assert exported_func() == 42
+
+def _helper_in_test():
+    return 'setup'
+`);
+
+            const index = new ProjectIndex(tmpDir);
+            index.build(null, { quiet: true });
+
+            // Default: test files excluded
+            const deadDefault = index.deadcode();
+            const deadDefaultNames = deadDefault.map(d => d.name);
+
+            // unused_func from app.py should appear
+            assert.ok(deadDefaultNames.includes('unused_func'),
+                `unused_func should be in deadcode results`);
+
+            // _helper_in_test from test file should NOT appear (test files excluded by default)
+            assert.ok(!deadDefaultNames.includes('_helper_in_test'),
+                `_helper_in_test should not appear without --include-tests`);
+
+            // With --include-tests: test file symbols should appear
+            const deadWithTests = index.deadcode({ includeTests: true });
+            const deadWithTestsNames = deadWithTests.map(d => d.name);
+
+            assert.ok(deadWithTestsNames.includes('_helper_in_test'),
+                `_helper_in_test should appear with --include-tests`);
+
+            // test_* functions should still be excluded (they're entry points)
+            assert.ok(!deadWithTestsNames.includes('test_exported'),
+                `test_exported should not be flagged (entry point)`);
+        } finally {
+            const topDir = tmpDir.split('/test/myproject')[0];
+            if (topDir.includes('ucn-test-relpath2')) {
+                fs.rmSync(topDir, { recursive: true, force: true });
+            }
+        }
+    });
+});
+
+// Regression: deadcode --include-exported should not include test file symbols
+// unless --include-tests is also specified
+describe('Regression: deadcode --include-exported respects test file filtering', () => {
+    it('should not show test methods when only --include-exported is set', () => {
+        const tmpDir = path.join(os.tmpdir(), `ucn-test-exported-${Date.now()}`);
+        const testsDir = path.join(tmpDir, 'tests');
+        fs.mkdirSync(testsDir, { recursive: true });
+
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'setup.py'), '');
+            fs.writeFileSync(path.join(tmpDir, 'lib.py'), `
+def public_func():
+    return 42
+`);
+            fs.writeFileSync(path.join(testsDir, 'test_lib.py'), `
+from lib import public_func
+
+class TestLib:
+    def test_public_func(self):
+        assert public_func() == 42
+
+    def test_another(self):
+        assert True
+`);
+
+            const index = new ProjectIndex(tmpDir);
+            index.build(null, { quiet: true });
+
+            // --include-exported but NOT --include-tests
+            const dead = index.deadcode({ includeExported: true, includeTests: false });
+            const deadNames = dead.map(d => d.name);
+
+            // Test methods should NOT appear
+            assert.ok(!deadNames.includes('test_public_func'),
+                `test methods should not appear with only --include-exported`);
+            assert.ok(!deadNames.includes('test_another'),
+                `test methods should not appear with only --include-exported`);
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+// Regression: isTestFile relative path fix applies to all languages (not just Python)
+// Rust has /\/tests\// pattern that could match parent directories
+describe('Regression: deadcode relative path fix works for Rust projects', () => {
+    it('should not treat non-test Rust files as test files when project is inside /tests/ directory', () => {
+        // Project lives inside a directory called "tests"
+        const tmpDir = path.join(os.tmpdir(), `ucn-test-rust-relpath-${Date.now()}`, 'tests', 'myproject');
+        const srcDir = path.join(tmpDir, 'src');
+        fs.mkdirSync(srcDir, { recursive: true });
+
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'Cargo.toml'), '[package]\nname = "test"');
+            fs.writeFileSync(path.join(srcDir, 'lib.rs'), `
+fn unused_helper() -> i32 {
+    42
+}
+
+pub fn used_func() -> i32 {
+    unused_helper()
+}
+`);
+
+            const index = new ProjectIndex(tmpDir);
+            index.build(null, { quiet: true });
+
+            const dead = index.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // unused_helper should be flagged (it has a caller but let's check it's not filtered)
+            // The key assertion: src/lib.rs should NOT be treated as a test file
+            const { isTestFile } = require('../core/discovery');
+            assert.ok(!isTestFile('src/lib.rs', 'rust'),
+                'src/lib.rs should not be a test file');
+
+            // Verify the old bug: absolute path WOULD falsely match
+            const absPath = path.join(tmpDir, 'src', 'lib.rs');
+            // The absolute path contains /tests/ from parent dir
+            assert.ok(absPath.includes('/tests/'),
+                'Absolute path should contain /tests/ from parent directory');
+        } finally {
+            const topDir = tmpDir.split('/tests/myproject')[0];
+            if (topDir.includes('ucn-test-rust-relpath')) {
+                fs.rmSync(topDir, { recursive: true, force: true });
+            }
+        }
+    });
+});
+
+// Regression: deadcode relative path fix works for JS projects with __tests__ in parent
+describe('Regression: deadcode relative path fix works for JS projects', () => {
+    it('should not treat non-test JS files as test files when project is inside /__tests__/ directory', () => {
+        const tmpDir = path.join(os.tmpdir(), `ucn-test-js-relpath-${Date.now()}`, '__tests__', 'myproject');
+        const srcDir = path.join(tmpDir, 'src');
+        fs.mkdirSync(srcDir, { recursive: true });
+
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "test"}');
+            fs.writeFileSync(path.join(srcDir, 'utils.js'), `
+function unusedUtil() {
+    return 42;
+}
+
+function usedUtil() {
+    return unusedUtil();
+}
+
+module.exports = { usedUtil };
+`);
+
+            const index = new ProjectIndex(tmpDir);
+            index.build(null, { quiet: true });
+
+            const dead = index.deadcode();
+            const deadNames = dead.map(d => d.name);
+
+            // src/utils.js should NOT be treated as a test file
+            const { isTestFile } = require('../core/discovery');
+            assert.ok(!isTestFile('src/utils.js', 'javascript'),
+                'src/utils.js should not be a test file');
+        } finally {
+            const topDir = tmpDir.split('/__tests__/myproject')[0];
+            if (topDir.includes('ucn-test-js-relpath')) {
+                fs.rmSync(topDir, { recursive: true, force: true });
+            }
+        }
+    });
+});
+
 console.log('UCN v3 Test Suite');
 console.log('Run with: node --test test/parser.test.js');

package/test/reliability-test-prompt.md

@@ -1,58 +0,0 @@
-Run UCN reliability tests on 5 real-world projects. IMPORTANT: use node /Users/mihail/ucn/cli/index.js (NOT the global ucn) to test the current dev version. Use --clear-cache on every command.
-
-First run the unit tests: node --test test/parser.test.js — should be 212 pass, 0 fail.
-
-1. Clone these repos to /tmp/ucn-reliability-test-2/ (shallow clone --depth 1):
-   - fastify: https://github.com/fastify/fastify.git (JavaScript)
-   - httpx: https://github.com/encode/httpx.git (Python)
-   - hugo: https://github.com/gohugoio/hugo.git (Go)
-   - alacritty: https://github.com/alacritty/alacritty.git (Rust)
-   - spring-boot: https://github.com/spring-projects/spring-boot.git (Java — use spring-boot-project/spring-boot/src/main/java/org/springframework/boot only, pass that as the target path)
-
-2. Launch 5 parallel agents (one per project). Each agent should run ALL of these commands with --clear-cache and 30s timeout:
-
-   toc, toc --detailed, find <sym1>, find <sym2>, about <sym1>,
-   context <class>, context <function>, impact <sym1>, smart <sym1>,
-   trace <sym1> --depth=2, usages <sym2>, deadcode, fn <method>,
-   imports <file>, exporters <file>, search "<term>", verify <sym1>,
-   find nonexistentXYZ (edge case), context "" (edge case)
-
-3. Key symbols per project:
-   - fastify: route, FastifyInstance, inject, Reply, register
-   - httpx: get, Client, request, Response, __init__
-   - hugo: Build, Site, Execute, Page, New
-   - alacritty: main, update, Display, build, new
-   - spring-boot: run, SpringApplication, main, ApplicationContext, refresh
-
-   For `fn` command, specifically test class methods (Python __init__, Java overloaded methods) — these were broken before and fixed in this version.
-
-4. Focus areas for EVERY command — check ALL of the following (AST tree-sitter reliability is the main focus):
-   - toc shows correct file/function/class counts, no crashes on large projects
-   - toc --detailed lists all symbols with line ranges, no truncation errors
-   - find returns ranked results by usage count, no duplicates
-   - about prefers lib/src/core definitions over test/example files, shows usages/callers/callees/code
-   - context <class> shows class name (not "undefined"), lists methods with signatures
-   - context <function> shows callers and callees with correct counts and weights
-   - context for non-existent symbols returns "Symbol not found" (NOT empty callers/callees)
-   - impact groups call sites by file with code context, shows argument patterns
-   - smart shows function code + inlined dependency code, overloads show ALL overload callees
-   - trace builds correct call tree with depth levels, weights, and multiplicity
-   - usages categorizes by type (definition/call/import/reference), no false positives
-   - deadcode completes within timeout, correctly excludes entry points (main, init, __init__, #[test])
-   - fn extracts correct code for BOTH top-level functions AND class methods (previously broken, now fixed)
-   - fn auto-resolves best definition (prefers lib/src over test)
-   - imports shows internal + external imports with resolved paths
-   - exporters finds importers for the file (Python relative imports work, Java package imports resolve)
-   - search returns matches with file grouping, respects project ignores
-   - verify checks call signatures, totalCalls equals valid+mismatches+uncertain (no inflated counts from filtered method calls)
-   - Edge cases: find nonexistentXYZ returns clean "not found", context "" returns usage error (no crash)
-
-5. Each agent reports: command, status (OK/ERROR/CRASH/UNEXPECTED), notes.
-   At the end: total pass/fail, issues by severity, patterns.
-
-6. After all agents finish, compile a cross-project summary comparing results to the previous run (which had 85/95 = 89.5% before fixes, target is 95%+ with 0 crashes). The fixes applied were:
-   - fn command now uses symbol index startLine/endLine directly (fixes class method extraction)
-   - verify totalCalls now computed as valid+mismatches+uncertain (fixes inflated counts)
-   - context returns null for undefined symbols (CLI shows "Symbol not found")
-
-All code uses tree-sitter AST parsing — reliability and correctness of AST-based analysis is the main focus. Any crash, incorrect result, or hang is a bug.