ucn 3.7.0 → 3.7.1

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

@@ -2617,9 +2617,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 +2651,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
             }

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.1",
   "description": "Universal Code Navigator — function relationships, call trees, and impact analysis across large codebases without reading entire files.",
   "main": "index.js",
   "bin": {

package/test/parser.test.js

@@ -12535,6 +12535,159 @@ 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 });
+    });
 });
 
 console.log('UCN v3 Test Suite');