ucn 3.7.0 → 3.7.2

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

@@ -1,13 +1,13 @@
 ---
 name: ucn
-description: "Code relationship analyzer (callers, call trees, impact, dead code) via tree-sitter AST. PREFER over grep+read when you need: who calls a function, what breaks if you change it, or the full call chain of a pipeline. One `ucn about` replaces 3-4 grep+read cycles. One `ucn trace` maps an entire execution flow without reading any files. Works on Python, JS/TS, Go, Rust, Java, HTML. Skip for plain text search or codebases under 500 LOC."
+description: "Code relationship analyzer (callers, call trees, impact, dead code) via tree-sitter AST. PREFER over grep+read when you need: who calls a function, what breaks if you change it, or the full call chain of a pipeline. One `ucn about` replaces 3-4 grep+read cycles. One `ucn trace` maps an entire execution flow without reading any files. Works on JS/TS, Python, Go, Rust, Java, HTML. Skip for plain text search or codebases under 500 LOC."
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
 argument-hint: "[command] [symbol-name] [--flags]"
 ---
 
 # UCN — Universal Code Navigator
 
-Understands code structure via tree-sitter ASTs: who calls what, what breaks if you change something, full call trees, dead code. Works on Python, JS/TS, Go, Rust, Java, HTML (inline scripts).
+Understands code structure via tree-sitter ASTs: who calls what, what breaks if you change something, full call trees, dead code. Works on JS/TS, Python, Go, Rust, Java. Also parses HTML files (inline scripts and event handlers).
 
 ## When to Reach for UCN Instead of Grep/Read
 
@@ -23,7 +23,7 @@ Understands code structure via tree-sitter ASTs: who calls what, what breaks if
 
 - Searching for a string literal, error message, TODO, or config value
 - The codebase is under 500 LOC — just read the files
-- Language not supported (only Python, JS/TS, Go, Rust, Java, HTML)
+- Language not supported (only JS/TS, Python, Go, Rust, Java, HTML)
 - Finding files by name — use glob
 
 ## The 5 Commands You'll Use Most

package/README.md

@@ -2,6 +2,8 @@
 
 UCN is designed to work with large files and codebases, helping AI agents ingest exactly the data they need. Its surgical output discourages agents from cutting corners, and without UCN, agents working with large codebases tend to skip parts of the code structure, assuming they have "enough data."
 
+Supported languages: JS/TS, Python, Go, Rust, Java. Also parses HTML files (inline scripts and event handlers).
+
 ---
 
 ## Three Ways to Use UCN
@@ -91,9 +93,10 @@ Instead of reading entire files, ask precise questions:
                           │
                     tree-sitter AST
                           │
-            ┌─────────────┴─────────────┐
-            │    Supported Languages    │ 
-            └───────────────────────────┘
+      ┌───────────────────┴─────────────────┐
+      │          Supported Languages        │
+      │ JS/TS, Python, Go, Rust, Java, HTML │
+      └─────────────────────────────────────┘
 ```
 
 No cloud. No API keys. Parses locally, stays local.
@@ -496,7 +499,7 @@ ucn toc                                   # Project overview
   │  Limitation              │  What happens                            │
   ├──────────────────────────┼──────────────────────────────────────────┤
   │                          │                                          │
-  │  6 languages only        │  JS/TS, Python, Go, Rust, Java, HTML.    │
+  │  5 languages + HTML      │  JS/TS, Python, Go, Rust, Java.          │
   │  (no C, Ruby, PHP, etc.) │  Agents fall back to grep for the rest.  │
   │                          │  UCN complements, doesn't replace.       │
   │                          │                                          │

package/core/project.js

@@ -8,10 +8,10 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, DEFAULT_IGNORES } = require('./discovery');
 const { extractImports, extractExports, resolveImport } = require('./imports');
-const { parseFile, cleanHtmlScriptTags } = require('./parser');
+const { parse, parseFile, cleanHtmlScriptTags } = require('./parser');
 const { detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS, safeParse } = require('../languages');
 const { getTokenTypeAtPosition } = require('../languages/utils');
 
@@ -402,7 +402,15 @@ class ProjectIndex {
                         return parent;
                     });
 
-                    this.extendsGraph.set(symbol.name, resolvedParents);
+                    // Store with file scope to avoid collisions when same class name
+                    // appears in multiple files (F-002 fix)
+                    if (!this.extendsGraph.has(symbol.name)) {
+                        this.extendsGraph.set(symbol.name, []);
+                    }
+                    this.extendsGraph.get(symbol.name).push({
+                        file: filePath,
+                        parents: resolvedParents
+                    });
 
                     for (const parent of resolvedParents) {
                         if (!this.extendedByGraph.has(parent)) {
@@ -419,6 +427,66 @@ class ProjectIndex {
         }
     }
 
+    /**
+     * Get inheritance parents for a class, scoped by file to handle
+     * duplicate class names across files.
+     * @param {string} className - Class name to look up
+     * @param {string} contextFile - File path for scoping (prefer same-file match)
+     * @returns {string[]|null} Parent class names, or null if none
+     */
+    _getInheritanceParents(className, contextFile) {
+        const entries = this.extendsGraph.get(className);
+        if (!entries || entries.length === 0) return null;
+
+        // New format: array of {file, parents}
+        if (typeof entries[0] === 'object' && entries[0].file !== undefined) {
+            // Prefer same-file match
+            const match = entries.find(e => e.file === contextFile);
+            if (match) return match.parents;
+
+            // Try imported file
+            if (contextFile) {
+                const imports = this.importGraph.get(contextFile);
+                if (imports) {
+                    const imported = entries.find(e => imports.includes(e.file));
+                    if (imported) return imported.parents;
+                }
+            }
+
+            // Fallback to first entry
+            return entries[0].parents;
+        }
+
+        // Old format (cache compat): plain array of parent names
+        return entries;
+    }
+
+    /**
+     * Resolve which file a class is defined in, preferring contextFile.
+     * Used during inheritance BFS to find grandparent chains.
+     * @param {string} className - Class name to resolve
+     * @param {string} contextFile - Preferred file (e.g., child's file)
+     * @returns {string|null} Resolved file path
+     */
+    _resolveClassFile(className, contextFile) {
+        const symbols = this.symbols.get(className);
+        if (!symbols) return contextFile;
+        const classSymbols = symbols.filter(s =>
+            ['class', 'interface', 'struct', 'trait'].includes(s.type));
+        if (classSymbols.length === 0) return contextFile;
+        // Prefer same file as context
+        if (classSymbols.some(s => s.file === contextFile)) return contextFile;
+        // Prefer imported
+        if (contextFile) {
+            const imports = this.importGraph.get(contextFile);
+            if (imports) {
+                const imported = classSymbols.find(s => imports.includes(s.file));
+                if (imported) return imported.file;
+            }
+        }
+        return classSymbols[0].file;
+    }
+
 
     // ========================================================================
     // QUERY METHODS
@@ -1246,21 +1314,23 @@ class ProjectIndex {
                             let matchesDef = call.receiver === 'super'
                                 ? false
                                 : definitions.some(d => d.className === callerSymbol.className);
-                            // Walk inheritance chain if not found in same class
+                            // Walk inheritance chain using BFS if not found in same class
                             if (!matchesDef) {
-                                let parents = this.extendsGraph.get(callerSymbol.className);
                                 const visited = new Set([callerSymbol.className]);
-                                while (parents && !matchesDef) {
-                                    for (const parent of parents) {
-                                        if (visited.has(parent)) continue;
-                                        visited.add(parent);
-                                        matchesDef = definitions.some(d => d.className === parent);
-                                        if (matchesDef) break;
-                                    }
+                                const callerFile = callerSymbol.file || filePath;
+                                const startParents = this._getInheritanceParents(callerSymbol.className, callerFile) || [];
+                                const queue = startParents.map(p => ({ name: p, contextFile: callerFile }));
+                                while (queue.length > 0 && !matchesDef) {
+                                    const { name: current, contextFile } = queue.shift();
+                                    if (visited.has(current)) continue;
+                                    visited.add(current);
+                                    matchesDef = definitions.some(d => d.className === current);
                                     if (!matchesDef) {
-                                        const nextParent = parents.find(p => !visited.has(p));
-                                        if (!nextParent) break;
-                                        parents = this.extendsGraph.get(nextParent);
+                                        const resolvedFile = this._resolveClassFile(current, contextFile);
+                                        const grandparents = this._getInheritanceParents(current, resolvedFile) || [];
+                                        for (const gp of grandparents) {
+                                            if (!visited.has(gp)) queue.push({ name: gp, contextFile: resolvedFile });
+                                        }
                                     }
                                 }
                             }
@@ -1665,22 +1735,23 @@ class ProjectIndex {
                         ? null
                         : symbols.find(s => s.className === def.className);
 
-                    // Walk inheritance chain if not found in same class
+                    // Walk inheritance chain using BFS if not found in same class
                     if (!match) {
-                        let parents = this.extendsGraph.get(def.className);
                         const visited = new Set([def.className]);
-                        while (parents && !match) {
-                            for (const parent of parents) {
-                                if (visited.has(parent)) continue;
-                                visited.add(parent);
-                                match = symbols.find(s => s.className === parent);
-                                if (match) break;
-                            }
+                        const defFile = def.file;
+                        const startParents = this._getInheritanceParents(def.className, defFile) || [];
+                        const queue = startParents.map(p => ({ name: p, contextFile: defFile }));
+                        while (queue.length > 0 && !match) {
+                            const { name: current, contextFile } = queue.shift();
+                            if (visited.has(current)) continue;
+                            visited.add(current);
+                            match = symbols.find(s => s.className === current);
                             if (!match) {
-                                // Follow first parent's chain (simplified MRO)
-                                const nextParent = parents.find(p => !visited.has(p));
-                                if (!nextParent) break;
-                                parents = this.extendsGraph.get(nextParent);
+                                const resolvedFile = this._resolveClassFile(current, contextFile);
+                                const grandparents = this._getInheritanceParents(current, resolvedFile) || [];
+                                for (const gp of grandparents) {
+                                    if (!visited.has(gp)) queue.push({ name: gp, contextFile: resolvedFile });
+                                }
                             }
                         }
                     }
@@ -2617,9 +2688,11 @@ class ProjectIndex {
                     const htmlParser = getParser('html');
                     const jsParser = getParser('javascript');
                     const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
-                    if (blocks.length === 0) continue;
-                    const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
-                    tree = jsParser.parse(virtualJS, undefined, PARSE_OPTIONS);
+                    if (blocks.length === 0 && !htmlModule.extractEventHandlerCalls) continue;
+                    if (blocks.length > 0) {
+                        const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
+                        tree = jsParser.parse(virtualJS, undefined, PARSE_OPTIONS);
+                    }
                 } else {
                     const parser = getParser(language);
                     if (!parser) continue;
@@ -2649,7 +2722,25 @@ class ProjectIndex {
                         traverse(node.child(i));
                     }
                 };
-                traverse(tree.rootNode);
+                if (tree) traverse(tree.rootNode);
+
+                // For HTML files, also extract identifiers from event handler attributes
+                // (onclick="foo()" etc. — these are in HTML, not in <script> blocks)
+                if (language === 'html') {
+                    const htmlModule = getLanguageModule('html');
+                    const htmlParser = getParser('html');
+                    const handlerCalls = htmlModule.extractEventHandlerCalls(content, htmlParser);
+                    for (const call of handlerCalls) {
+                        if (!usageIndex.has(call.name)) {
+                            usageIndex.set(call.name, []);
+                        }
+                        usageIndex.get(call.name).push({
+                            file: filePath,
+                            line: call.line,
+                            relativePath: fileEntry.relativePath
+                        });
+                    }
+                }
             } catch (e) {
                 // Skip files that can't be processed
             }
@@ -4810,8 +4901,8 @@ class ProjectIndex {
             throw new Error('Not a git repository. diff-impact requires git.');
         }
 
-        // Build git diff command
-        const diffArgs = ['git', 'diff', '--unified=0'];
+        // Build git diff command (use execFileSync to avoid shell expansion)
+        const diffArgs = ['diff', '--unified=0'];
         if (staged) {
             diffArgs.push('--staged');
         } else {
@@ -4823,7 +4914,7 @@ class ProjectIndex {
 
         let diffText;
         try {
-            diffText = execSync(diffArgs.join(' '), { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+            diffText = execFileSync('git', diffArgs, { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
         } catch (e) {
             // git diff exits non-zero when there are diff errors, but also for invalid refs
             if (e.stdout) {
@@ -4858,7 +4949,31 @@ class ProjectIndex {
             if (!lang) continue;
 
             const fileEntry = this.files.get(change.filePath);
-            if (!fileEntry) continue;
+
+            // Handle deleted files: entire file was removed, all functions are deleted
+            if (!fileEntry) {
+                if (change.isDeleted && change.deletedLines.length > 0) {
+                    const ref = staged ? 'HEAD' : base;
+                    try {
+                        const oldContent = execFileSync(
+                            'git', ['show', `${ref}:${change.relativePath}`],
+                            { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
+                        );
+                        const oldParsed = parse(oldContent, lang);
+                        for (const oldFn of extractCallableSymbols(oldParsed)) {
+                            deletedFunctions.push({
+                                name: oldFn.name,
+                                filePath: change.filePath,
+                                relativePath: change.relativePath,
+                                startLine: oldFn.startLine
+                            });
+                        }
+                    } catch (e) {
+                        // git show failed — skip
+                    }
+                }
+                continue;
+            }
 
             // Track which functions are affected by added/modified lines
             const affectedSymbols = new Map(); // symbolName -> { symbol, addedLines, deletedLines }
@@ -4940,6 +5055,57 @@ class ProjectIndex {
                 }
             }
 
+            // Detect deleted functions: compare old file symbols with current by identity.
+            // Uses name+className counts to handle overloads (e.g. Java method overloading).
+            if (change.deletedLines.length > 0) {
+                const ref = staged ? 'HEAD' : base;
+                try {
+                    const oldContent = execFileSync(
+                        'git', ['show', `${ref}:${change.relativePath}`],
+                        { cwd: this.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
+                    );
+                    const fileLang = detectLanguage(change.filePath);
+                    if (fileLang) {
+                        const oldParsed = parse(oldContent, fileLang);
+                        const nonCallableTypes = new Set(['class', 'struct', 'interface', 'type', 'state', 'impl', 'enum', 'trait']);
+                        // Count current symbols by identity (name + className)
+                        const currentCounts = new Map();
+                        for (const s of fileEntry.symbols) {
+                            if (nonCallableTypes.has(s.type)) continue;
+                            const key = `${s.name}\0${s.className || ''}`;
+                            currentCounts.set(key, (currentCounts.get(key) || 0) + 1);
+                        }
+                        // Count old symbols by identity and detect deletions
+                        const oldCounts = new Map();
+                        const oldSymbols = extractCallableSymbols(oldParsed);
+                        for (const oldFn of oldSymbols) {
+                            const key = `${oldFn.name}\0${oldFn.className || ''}`;
+                            oldCounts.set(key, (oldCounts.get(key) || 0) + 1);
+                        }
+                        // For each identity, if old count > current count, the difference are deletions
+                        for (const [key, oldCount] of oldCounts) {
+                            const curCount = currentCounts.get(key) || 0;
+                            if (oldCount > curCount) {
+                                // Find the specific old symbols with this identity that were deleted
+                                const matching = oldSymbols.filter(s => `${s.name}\0${s.className || ''}` === key);
+                                // Report the extra ones (by startLine descending — later ones more likely deleted)
+                                const toReport = matching.slice(curCount);
+                                for (const oldFn of toReport) {
+                                    deletedFunctions.push({
+                                        name: oldFn.name,
+                                        filePath: change.filePath,
+                                        relativePath: change.relativePath,
+                                        startLine: oldFn.startLine
+                                    });
+                                }
+                            }
+                        }
+                    }
+                } catch (e) {
+                    // File didn't exist in base, or git error — skip
+                }
+            }
+
             // For each affected function, find callers
             for (const [, data] of affectedSymbols) {
                 const { symbol, addedLines: aLines, deletedLines: dLines } = data;
@@ -4992,6 +5158,40 @@ class ProjectIndex {
     }
 }
 
+/**
+ * Extract all callable symbols (functions + class methods) from a parse result,
+ * matching how indexFile builds the symbol list. Methods get className added.
+ * @param {object} parsed - Result from parse()
+ * @returns {Array<{name, className, startLine}>}
+ */
+function extractCallableSymbols(parsed) {
+    const symbols = [];
+    for (const fn of parsed.functions) {
+        symbols.push({ name: fn.name, className: fn.className || '', startLine: fn.startLine });
+    }
+    for (const cls of parsed.classes) {
+        if (cls.members) {
+            for (const m of cls.members) {
+                symbols.push({ name: m.name, className: cls.name, startLine: m.startLine });
+            }
+        }
+    }
+    return symbols;
+}
+
+/**
+ * Unquote a git diff path: unescape C-style backslash sequences and strip tab metadata.
+ * Git quotes paths containing special chars as "a/path\"with\"quotes".
+ * @param {string} raw - Raw path string (may contain backslash escapes)
+ * @returns {string} Unquoted path
+ */
+function unquoteDiffPath(raw) {
+    const ESCAPES = { '\\\\': '\\', '\\"': '"', '\\n': '\n', '\\t': '\t' };
+    return raw
+        .split('\t')[0]
+        .replace(/\\[\\"nt]/g, m => ESCAPES[m]);
+}
+
 /**
  * Parse unified diff output into structured change data
  * @param {string} diffText - Output from `git diff --unified=0`
@@ -5001,16 +5201,39 @@ class ProjectIndex {
 function parseDiff(diffText, root) {
     const changes = [];
     let currentFile = null;
+    let pendingOldPath = null; // Track --- a/ path for deleted files
 
     for (const line of diffText.split('\n')) {
-        // Match file header: +++ b/path/to/file.js
-        if (line.startsWith('+++ b/')) {
-            const relativePath = line.slice(6);
+        // Track old file path from --- header for deleted-file detection
+        // Handles both unquoted (--- a/path) and quoted (--- "a/path") formats
+        const oldMatch = line.match(/^--- (?:"a\/((?:[^"\\]|\\.)*)"|a\/(.+?))\s*$/);
+        if (oldMatch) {
+            const raw = oldMatch[1] !== undefined ? oldMatch[1] : oldMatch[2];
+            pendingOldPath = unquoteDiffPath(raw);
+            continue;
+        }
+
+        // Match file header: +++ b/path or +++ "b/path" or +++ /dev/null
+        if (line.startsWith('+++ ')) {
+            let relativePath;
+            const isDevNull = line.startsWith('+++ /dev/null');
+            if (isDevNull) {
+                // File was deleted — use the --- a/ path
+                if (!pendingOldPath) continue;
+                relativePath = pendingOldPath;
+            } else {
+                const newMatch = line.match(/^\+\+\+ (?:"b\/((?:[^"\\]|\\.)*)"|b\/(.+?))\s*$/);
+                if (!newMatch) continue;
+                const raw = newMatch[1] !== undefined ? newMatch[1] : newMatch[2];
+                relativePath = unquoteDiffPath(raw);
+            }
+            pendingOldPath = null;
             currentFile = {
                 filePath: path.join(root, relativePath),
                 relativePath,
                 addedLines: [],
-                deletedLines: []
+                deletedLines: [],
+                ...(isDevNull && { isDeleted: true })
             };
             changes.push(currentFile);
             continue;

package/languages/html.js

@@ -144,6 +144,81 @@ function extractJS(htmlContent, htmlParser) {
     return { virtualJS, jsParser, jsModule };
 }
 
+/**
+ * Extract function calls from HTML event handler attributes (onclick, onchange, etc.).
+ * Walks the HTML AST for elements with on* attributes, extracts function names
+ * from the attribute values using regex, and returns call objects.
+ *
+ * @param {string} htmlContent - Raw HTML source
+ * @param {object} htmlParser - tree-sitter parser configured for HTML
+ * @returns {Array<{name: string, line: number, isMethod: boolean, enclosingFunction: null, uncertain: boolean, isEventHandler: boolean}>}
+ */
+function extractEventHandlerCalls(htmlContent, htmlParser) {
+    const { safeParse, getParseOptions } = require('./index');
+    const tree = safeParse(htmlParser, htmlContent, undefined, getParseOptions(htmlContent.length));
+    const calls = [];
+
+    const JS_KEYWORDS = new Set([
+        'if', 'for', 'while', 'switch', 'catch', 'function', 'return',
+        'typeof', 'void', 'delete', 'new', 'throw', 'class', 'const',
+        'let', 'var', 'true', 'false', 'null', 'undefined', 'this'
+    ]);
+
+    const visit = (node) => {
+        // Skip script elements — their content is handled separately
+        if (node.type === 'script_element') return;
+
+        if (node.type === 'attribute') {
+            const nameNode = node.children.find(c => c.type === 'attribute_name');
+            if (!nameNode || !nameNode.text.toLowerCase().startsWith('on')) {
+                for (let i = 0; i < node.childCount; i++) visit(node.child(i));
+                return;
+            }
+
+            const valueNode = node.children.find(c =>
+                c.type === 'quoted_attribute_value' || c.type === 'attribute_value'
+            );
+            if (!valueNode) return;
+
+            let valueText;
+            if (valueNode.type === 'quoted_attribute_value') {
+                const inner = valueNode.children.find(c => c.type === 'attribute_value');
+                valueText = inner ? inner.text : '';
+            } else {
+                valueText = valueNode.text;
+            }
+            if (!valueText) return;
+
+            const line = nameNode.startPosition.row + 1; // 1-indexed
+
+            // Extract standalone function calls (not method calls like obj.method())
+            const regex = /([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/g;
+            let match;
+            while ((match = regex.exec(valueText)) !== null) {
+                const fnName = match[1];
+                if (JS_KEYWORDS.has(fnName)) continue;
+                // Skip if preceded by dot (method call on object)
+                if (match.index > 0 && valueText[match.index - 1] === '.') continue;
+
+                calls.push({
+                    name: fnName,
+                    line,
+                    isMethod: false,
+                    enclosingFunction: null,
+                    uncertain: false,
+                    isEventHandler: true
+                });
+            }
+            return;
+        }
+
+        for (let i = 0; i < node.childCount; i++) visit(node.child(i));
+    };
+
+    visit(tree.rootNode);
+    return calls;
+}
+
 // ── Exported language module interface ──────────────────────────────────────
 
 function parse(code, parser) {
@@ -185,9 +260,14 @@ function findStateObjects(code, parser) {
 }
 
 function findCallsInCode(code, parser) {
-    const result = extractJS(code, parser);
-    if (!result) return [];
-    return result.jsModule.findCallsInCode(result.virtualJS, result.jsParser);
+    const scriptCalls = (() => {
+        const result = extractJS(code, parser);
+        if (!result) return [];
+        return result.jsModule.findCallsInCode(result.virtualJS, result.jsParser);
+    })();
+    const handlerCalls = extractEventHandlerCalls(code, parser);
+    if (handlerCalls.length === 0) return scriptCalls;
+    return scriptCalls.concat(handlerCalls);
 }
 
 function findCallbackUsages(code, name, parser) {
@@ -233,5 +313,6 @@ module.exports = {
     findUsagesInCode,
     // Exported for testing
     extractScriptBlocks,
-    buildVirtualJSContent
+    buildVirtualJSContent,
+    extractEventHandlerCalls
 };

package/mcp/server.js

@@ -169,7 +169,7 @@ function requireName(name) {
 // CONSOLIDATED TOOL REGISTRATION
 // ============================================================================
 
-const TOOL_DESCRIPTION = `Universal Code Navigator powered by tree-sitter ASTs. Analyzes code structure — functions, callers, callees, dependencies — across JavaScript/TypeScript, Python, Go, Rust, Java, and HTML (inline scripts). Use instead of grep/read for code relationships.
+const TOOL_DESCRIPTION = `Universal Code Navigator powered by tree-sitter ASTs. Analyzes code structure — functions, callers, callees, dependencies — across JavaScript/TypeScript, Python, Go, Rust, Java, and HTML (inline scripts and event handlers). Use instead of grep/read for code relationships.
 
 TOP 5 (covers 90% of tasks): about, impact, trace, find, deadcode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "Universal Code Navigator — function relationships, call trees, and impact analysis across large codebases without reading entire files.",
   "main": "index.js",
   "bin": {

package/test/accuracy.test.js

@@ -1376,7 +1376,7 @@ class Child(Base):
         } finally { rm(d); }
     });
 
-    it('LIMITATION: deep inheritance chain (3+ levels)', () => {
+    it('PASS: deep inheritance chain (3+ levels)', () => {
         const d = tmp({
             'package.json': '{"name":"t"}',
             'lib.js': `

package/test/parser.test.js

@@ -12535,6 +12535,494 @@ function main() { return helper(); }
 
         fs.rmSync(tmpDir, { recursive: true, force: true });
     });
+
+    // ── HTML event handler tests (fix #90) ──────────────────────────────────
+
+    it('extractEventHandlerCalls extracts calls from onclick attributes', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = '<button onclick="resetGame()">Click</button>';
+        const calls = extractEventHandlerCalls(html, parser);
+        assert.strictEqual(calls.length, 1);
+        assert.strictEqual(calls[0].name, 'resetGame');
+        assert.strictEqual(calls[0].line, 1);
+        assert.strictEqual(calls[0].isMethod, false);
+        assert.strictEqual(calls[0].isEventHandler, true);
+    });
+
+    it('extractEventHandlerCalls handles multiple calls in one handler', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = '<button onclick="validateForm(); submitData()">Go</button>';
+        const calls = extractEventHandlerCalls(html, parser);
+        assert.strictEqual(calls.length, 2);
+        assert.strictEqual(calls[0].name, 'validateForm');
+        assert.strictEqual(calls[1].name, 'submitData');
+    });
+
+    it('extractEventHandlerCalls skips method calls on objects', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = '<button onclick="event.stopPropagation(); selectCar(\'abc\')">Buy</button>';
+        const calls = extractEventHandlerCalls(html, parser);
+        const names = calls.map(c => c.name);
+        assert.ok(!names.includes('stopPropagation'), 'should skip event.stopPropagation()');
+        assert.ok(names.includes('selectCar'), 'should detect selectCar()');
+    });
+
+    it('extractEventHandlerCalls skips JS keywords', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = '<button onclick="if (confirm(\'sure?\')) deleteItem(id)">Del</button>';
+        const calls = extractEventHandlerCalls(html, parser);
+        const names = calls.map(c => c.name);
+        assert.ok(!names.includes('if'), 'should skip keyword if');
+        assert.ok(names.includes('confirm'));
+        assert.ok(names.includes('deleteItem'));
+    });
+
+    it('extractEventHandlerCalls works with various on* attributes', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = `<input onchange="updateValue()" onfocus="highlight()" onblur="unhighlight()">`;
+        const calls = extractEventHandlerCalls(html, parser);
+        const names = calls.map(c => c.name);
+        assert.ok(names.includes('updateValue'));
+        assert.ok(names.includes('highlight'));
+        assert.ok(names.includes('unhighlight'));
+    });
+
+    it('extractEventHandlerCalls does not extract from script elements', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = `<script>function foo() { bar(); }</script>
+<button onclick="foo()">Click</button>`;
+        const calls = extractEventHandlerCalls(html, parser);
+        // Should only find foo from onclick, not bar from <script>
+        assert.strictEqual(calls.length, 1);
+        assert.strictEqual(calls[0].name, 'foo');
+    });
+
+    it('extractEventHandlerCalls reports correct line numbers', () => {
+        const { extractEventHandlerCalls } = require('../languages/html');
+        const parser = getParser('html');
+        const html = `<html>
+<body>
+<div>text</div>
+<button onclick="doA()">A</button>
+<button onclick="doB()">B</button>
+</body>
+</html>`;
+        const calls = extractEventHandlerCalls(html, parser);
+        assert.strictEqual(calls.length, 2);
+        assert.strictEqual(calls[0].name, 'doA');
+        assert.strictEqual(calls[0].line, 4);
+        assert.strictEqual(calls[1].name, 'doB');
+        assert.strictEqual(calls[1].line, 5);
+    });
+
+    it('findCallsInCode includes event handler calls for HTML', () => {
+        const { parser, mod } = getHtmlTools();
+        const html = `<button onclick="handleClick()">Click</button>
+<script>
+function handleClick() { doWork(); }
+function doWork() { return 42; }
+</script>`;
+        const calls = mod.findCallsInCode(html, parser);
+        const names = calls.map(c => c.name);
+        assert.ok(names.includes('handleClick'), 'should find handleClick from onclick');
+        assert.ok(names.includes('doWork'), 'should find doWork from script');
+    });
+
+    it('deadcode does not report functions called from HTML event handlers', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-html-onclick-'));
+        fs.writeFileSync(path.join(tmpDir, 'page.html'), `<html><body>
+<button onclick="resetGame()">Reset</button>
+<button onclick="startGame('easy')">Start</button>
+<script>
+function resetGame() { init(); }
+function startGame(mode) { setup(mode); }
+function init() { return 1; }
+function setup(m) { return m; }
+function unusedFn() { return 0; }
+</script>
+</body></html>`);
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "test"}');
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build();
+
+        const dead = index.deadcode({ includeExported: true });
+        const deadNames = dead.map(d => d.name);
+        // resetGame and startGame are called from onclick — NOT dead
+        assert.ok(!deadNames.includes('resetGame'), 'resetGame should not be dead (called from onclick)');
+        assert.ok(!deadNames.includes('startGame'), 'startGame should not be dead (called from onclick)');
+        // init and setup are called from script — NOT dead
+        assert.ok(!deadNames.includes('init'), 'init should not be dead (called from resetGame)');
+        assert.ok(!deadNames.includes('setup'), 'setup should not be dead (called from startGame)');
+        // unusedFn has no callers — dead
+        assert.ok(deadNames.includes('unusedFn'), 'unusedFn should be dead');
+
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('findCallers detects callers from HTML event handlers', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-html-callers-'));
+        fs.writeFileSync(path.join(tmpDir, 'page.html'), `<html><body>
+<button onclick="doStuff()">Go</button>
+<script>
+function doStuff() { return 42; }
+</script>
+</body></html>`);
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "test"}');
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build();
+
+        const callers = index.findCallers('doStuff');
+        assert.strictEqual(callers.length, 1);
+        assert.strictEqual(callers[0].line, 2);
+        assert.ok(callers[0].content.includes('onclick="doStuff()"'));
+
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+});
+
+// FIX 91: Deep inheritance chain (3+ levels) — BFS traversal
+it('FIX 91 — deep inheritance chain resolves callees through 3+ levels', () => {
+    const tmpDir = path.join(os.tmpdir(), `ucn-deep-inherit-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'lib.js'), `
+class A {
+    helper() { return 1; }
+}
+class B extends A {
+    other() { return 2; }
+}
+class C extends B {
+    process() { return this.helper(); }
+}
+module.exports = { A, B, C };
+`);
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+
+        // Callees: C.process() should resolve this.helper() to A.helper via C → B → A
+        const processDef = index.symbols.get('process')?.[0];
+        const callees = index.findCallees(processDef);
+        assert.ok(callees.some(c => c.name === 'helper' && c.className === 'A'),
+            'Deep chain callees: C → B → A, this.helper() resolves to A.helper');
+
+        // Callers: A.helper should be found as called from C.process()
+        const callers = index.findCallers('helper');
+        assert.ok(callers.some(c => c.callerName === 'process'),
+            'Deep chain callers: A.helper() called from C.process() via inheritance');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 92: Inheritance graph key collision with duplicate class names across files
+it('FIX 92 — duplicate class names across files resolve independently', () => {
+    const tmpDir = path.join(os.tmpdir(), `ucn-dup-class-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'a1.js'), `
+class A { helper() { return 1; } }
+class C extends A { process() { return this.helper(); } }
+module.exports = { A, C };
+`);
+        fs.writeFileSync(path.join(tmpDir, 'a2.js'), `
+class B { helper() { return 2; } }
+class C extends B { run() { return this.helper(); } }
+module.exports = { B, C };
+`);
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+
+        // C in a1.js extends A → helper should resolve to A.helper (a1.js)
+        const processDef = index.symbols.get('process').find(s => s.file.endsWith('a1.js'));
+        const processCallees = index.findCallees(processDef);
+        const helperFromProcess = processCallees.find(c => c.name === 'helper');
+        assert.ok(helperFromProcess, 'process() resolves this.helper()');
+        assert.strictEqual(helperFromProcess.className, 'A', 'process() helper is from class A');
+        assert.ok(helperFromProcess.file.endsWith('a1.js'), 'process() helper is in a1.js');
+
+        // C in a2.js extends B → helper should resolve to B.helper (a2.js)
+        const runDef = index.symbols.get('run').find(s => s.file.endsWith('a2.js'));
+        const runCallees = index.findCallees(runDef);
+        const helperFromRun = runCallees.find(c => c.name === 'helper');
+        assert.ok(helperFromRun, 'run() resolves this.helper()');
+        assert.strictEqual(helperFromRun.className, 'B', 'run() helper is from class B');
+        assert.ok(helperFromRun.file.endsWith('a2.js'), 'run() helper is in a2.js');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 93: diffImpact detects deleted functions
+it('FIX 93 — diffImpact detects deleted functions', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-del-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'app.js'), `function foo() { return 1; }
+function bar() { return foo(); }
+`);
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        // Delete foo, keep bar
+        fs.writeFileSync(path.join(tmpDir, 'app.js'), `function bar() { return 2; }
+`);
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.ok(result.deletedFunctions.length >= 1, 'Should detect deleted function');
+        assert.ok(result.deletedFunctions.some(f => f.name === 'foo'), 'foo should be in deletedFunctions');
+        assert.strictEqual(result.summary.deletedFunctions, result.deletedFunctions.length,
+            'Summary count should match deletedFunctions length');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 94: diffImpact detects deleted functions when entire file is removed
+it('FIX 94 — diffImpact detects all functions in a deleted file', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-filedel-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'a.js'), 'function foo() { return 1; }\nfunction bar() { return 2; }\n');
+        fs.writeFileSync(path.join(tmpDir, 'b.js'), 'function baz() { return 3; }\n');
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        // Delete entire file a.js
+        fs.unlinkSync(path.join(tmpDir, 'a.js'));
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.ok(result.deletedFunctions.some(f => f.name === 'foo'), 'foo should be detected as deleted');
+        assert.ok(result.deletedFunctions.some(f => f.name === 'bar'), 'bar should be detected as deleted');
+        assert.ok(!result.deletedFunctions.some(f => f.name === 'baz'), 'baz should NOT be deleted');
+        assert.strictEqual(result.summary.deletedFunctions, 2);
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 95: diffImpact detects same-name method deletion by identity
+it('FIX 95 — diffImpact detects A.foo deleted while B.foo remains', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-samename-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'app.js'), `
+class A { foo() { return 1; } }
+class B { foo() { return 2; } }
+module.exports = { A, B };
+`);
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        // Delete A.foo but keep B.foo
+        fs.writeFileSync(path.join(tmpDir, 'app.js'), `
+class A { }
+class B { foo() { return 2; } }
+module.exports = { A, B };
+`);
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.strictEqual(result.deletedFunctions.length, 1, 'Exactly one foo should be deleted');
+        assert.strictEqual(result.deletedFunctions[0].name, 'foo');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 96: parseDiff handles filenames with spaces and tab metadata
+it('FIX 96 — diffImpact works with filenames containing spaces', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-spaces-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'a b.js'), 'function spaceFn() { return 1; }\nfunction gone() { return 2; }\n');
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        // Modify spaceFn, delete gone
+        fs.writeFileSync(path.join(tmpDir, 'a b.js'), 'function spaceFn() { return 99; }\n');
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.ok(result.functions.some(f => f.name === 'spaceFn'), 'spaceFn should be detected as modified');
+        assert.ok(result.deletedFunctions.some(f => f.name === 'gone'), 'gone should be detected as deleted');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 97: git show uses execFileSync (no shell expansion of $ in filenames)
+it('FIX 97 — diffImpact works with $ in filenames', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-dollar-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+        fs.writeFileSync(path.join(tmpDir, 'a$HOME.js'), 'function dollarFn() { return 1; }\nfunction gone() { return 2; }\n');
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'a$HOME.js'), 'function dollarFn() { return 99; }\n');
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.ok(result.functions.some(f => f.name === 'dollarFn'), 'dollarFn should be detected as modified');
+        assert.ok(result.deletedFunctions.some(f => f.name === 'gone'), 'gone should be detected as deleted');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 98: deleted-function identity handles overloads (same name+class, different signatures)
+it('FIX 98 — diffImpact detects deleted overload while sibling remains', () => {
+    const { execSync } = require('child_process');
+    const tmpDir = path.join(os.tmpdir(), `ucn-diff-overload-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+
+        fs.writeFileSync(path.join(tmpDir, 'pom.xml'), '<project></project>\n');
+        fs.writeFileSync(path.join(tmpDir, 'A.java'), `
+public class A {
+    public void foo(int x) { System.out.println(x); }
+    public void foo(String s) { System.out.println(s); }
+    public void bar() { foo(1); }
+}
+`);
+        execSync('git add -A && git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+
+        // Delete one overload
+        fs.writeFileSync(path.join(tmpDir, 'A.java'), `
+public class A {
+    public void foo(String s) { System.out.println(s); }
+    public void bar() { foo("hi"); }
+}
+`);
+
+        const { ProjectIndex } = require('../core/project');
+        const index = new ProjectIndex(tmpDir);
+        index.build(null, { quiet: true });
+        const result = index.diffImpact({ base: 'HEAD' });
+
+        assert.strictEqual(result.deletedFunctions.length, 1, 'Exactly one overload should be deleted');
+        assert.strictEqual(result.deletedFunctions[0].name, 'foo');
+    } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+});
+
+// FIX 99: parseDiff handles quoted diff headers (special chars in filenames)
+it('FIX 99 — parseDiff handles quoted paths with special characters', () => {
+    const { parseDiff } = require('../core/project');
+
+    // Quoted path with escaped quotes
+    const diffText = `diff --git "a/a\\"b.js" "b/a\\"b.js"
+--- "a/a\\"b.js"
++++ "b/a\\"b.js"
+@@ -1 +1 @@
+`;
+    const changes = parseDiff(diffText, '/tmp/test');
+    assert.strictEqual(changes.length, 1);
+    assert.strictEqual(changes[0].relativePath, 'a"b.js');
+
+    // Quoted deleted file
+    const diffText2 = `diff --git "a/a\\"b.js" "b/a\\"b.js"
+--- "a/a\\"b.js"
++++ /dev/null
+@@ -1,2 +0,0 @@
+`;
+    const changes2 = parseDiff(diffText2, '/tmp/test');
+    assert.strictEqual(changes2.length, 1);
+    assert.strictEqual(changes2[0].isDeleted, true);
+    assert.strictEqual(changes2[0].relativePath, 'a"b.js');
+
+    // Unquoted path still works
+    const diffText3 = `diff --git a/normal.js b/normal.js
+--- a/normal.js
++++ b/normal.js
+@@ -1 +1 @@
+`;
+    const changes3 = parseDiff(diffText3, '/tmp/test');
+    assert.strictEqual(changes3.length, 1);
+    assert.strictEqual(changes3[0].relativePath, 'normal.js');
+
+    // Literal backslash+n in filename must not become a newline (single-pass unescape)
+    // Git represents a\\n.js as a\\\\n.js in quoted headers
+    const diffText4 = `diff --git "a/a\\\\n.js" "b/a\\\\n.js"
+--- "a/a\\\\n.js"
++++ "b/a\\\\n.js"
+@@ -1 +1 @@
+`;
+    const changes4 = parseDiff(diffText4, '/tmp/test');
+    assert.strictEqual(changes4.length, 1);
+    assert.strictEqual(changes4[0].relativePath, 'a\\n.js',
+        'Literal backslash-n in filename must be preserved, not converted to newline');
 });
 
 console.log('UCN v3 Test Suite');