ucn 3.0.0 → 3.1.1

package/README.md

@@ -38,13 +38,8 @@ JavaScript, TypeScript, Python, Go, Rust, Java
 
 ## Install
 
-Not published to npm yet. Install from source:
-
 ```bash
-git clone https://github.com/mleoca/ucn.git
-cd ucn
-npm install
-npm link  # makes 'ucn' available globally
+npm install -g ucn
 ```
 
 ### Claude Code (optional)
@@ -53,6 +48,12 @@ To use UCN as a skill in Claude Code:
 
 ```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/
 ```
 
@@ -62,6 +63,12 @@ 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/
 ```
 

package/cli/index.js

@@ -1550,6 +1550,66 @@ function printBestExample(index, name) {
 }
 
 function printContext(ctx, options = {}) {
+    // Handle struct/interface types differently
+    if (ctx.type && ['struct', 'interface', 'type'].includes(ctx.type)) {
+        console.log(`Context for ${ctx.type} ${ctx.name}:`);
+        console.log('═'.repeat(60));
+
+        // Display warnings if any
+        if (ctx.warnings && ctx.warnings.length > 0) {
+            console.log('\n⚠️  WARNINGS:');
+            for (const w of ctx.warnings) {
+                console.log(`  ${w.message}`);
+            }
+        }
+
+        const expandable = [];
+        let itemNum = 1;
+
+        // Show methods for structs/interfaces
+        const methods = ctx.methods || [];
+        console.log(`\nMETHODS (${methods.length}):`);
+        for (const m of methods) {
+            const receiver = m.receiver ? `(${m.receiver}) ` : '';
+            const params = m.params || '...';
+            const returnType = m.returnType ? `: ${m.returnType}` : '';
+            console.log(`  [${itemNum}] ${receiver}${m.name}(${params})${returnType}`);
+            console.log(`    ${m.file}:${m.line}`);
+            expandable.push({
+                num: itemNum++,
+                type: 'method',
+                name: m.name,
+                relativePath: m.file,
+                startLine: m.line
+            });
+        }
+
+        // Show callers (type references/usages)
+        const callers = ctx.callers || [];
+        console.log(`\nUSAGES (${callers.length}):`);
+        for (const c of callers) {
+            const callerName = c.callerName || '(module level)';
+            const displayName = c.callerName ? ` [${callerName}]` : '';
+            console.log(`  [${itemNum}] ${c.relativePath}:${c.line}${displayName}`);
+            expandable.push({
+                num: itemNum++,
+                type: 'usage',
+                name: callerName,
+                file: c.callerFile || c.file,
+                relativePath: c.relativePath,
+                line: c.line,
+                startLine: c.callerStartLine || c.line,
+                endLine: c.callerEndLine || c.line
+            });
+            console.log(`    ${c.content.trim()}`);
+        }
+
+        console.log(`\nUse "ucn . expand <N>" to see code for item N`);
+        lastContextExpandable = expandable;
+        return;
+    }
+
+    // Standard function/method context
     console.log(`Context for ${ctx.function}:`);
     console.log('═'.repeat(60));
 
@@ -1565,8 +1625,9 @@ function printContext(ctx, options = {}) {
     const expandable = [];
     let itemNum = 1;
 
-    console.log(`\nCALLERS (${ctx.callers.length}):`);
-    for (const c of ctx.callers) {
+    const callers = ctx.callers || [];
+    console.log(`\nCALLERS (${callers.length}):`);
+    for (const c of callers) {
         // All callers are numbered for expand command
         const callerName = c.callerName || '(module level)';
         const displayName = c.callerName ? ` [${callerName}]` : '';
@@ -1584,8 +1645,9 @@ function printContext(ctx, options = {}) {
         console.log(`    ${c.content.trim()}`);
     }
 
-    console.log(`\nCALLEES (${ctx.callees.length}):`);
-    for (const c of ctx.callees) {
+    const callees = ctx.callees || [];
+    console.log(`\nCALLEES (${callees.length}):`);
+    for (const c of callees) {
         const weight = c.weight && c.weight !== 'normal' ? ` [${c.weight}]` : '';
         console.log(`  [${itemNum}] ${c.name}${weight} - ${c.relativePath}:${c.startLine}`);
         expandable.push({

package/core/imports.js

@@ -431,6 +431,12 @@ function resolveImport(importPath, fromFile, config = {}) {
             }
         }
 
+        // Check Go module imports
+        if (config.language === 'go') {
+            const resolved = resolveGoImport(importPath, fromFile, config.root);
+            if (resolved) return resolved;
+        }
+
         return null;  // External package
     }
 
@@ -439,6 +445,83 @@ function resolveImport(importPath, fromFile, config = {}) {
     return resolveFilePath(resolved, config.extensions || getExtensions(config.language));
 }
 
+// Cache for Go module paths
+const goModuleCache = new Map();
+
+/**
+ * Find and parse go.mod to get the module path
+ * @param {string} startDir - Directory to start searching from
+ * @returns {{modulePath: string, root: string}|null}
+ */
+function findGoModule(startDir) {
+    // Check cache first
+    if (goModuleCache.has(startDir)) {
+        return goModuleCache.get(startDir);
+    }
+
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const goModPath = path.join(dir, 'go.mod');
+        if (fs.existsSync(goModPath)) {
+            try {
+                const content = fs.readFileSync(goModPath, 'utf-8');
+                // Parse module line: module github.com/user/project
+                const match = content.match(/^module\s+(\S+)/m);
+                if (match) {
+                    const result = { modulePath: match[1], root: dir };
+                    goModuleCache.set(startDir, result);
+                    return result;
+                }
+            } catch (e) {
+                // Ignore read errors
+            }
+        }
+        dir = path.dirname(dir);
+    }
+
+    goModuleCache.set(startDir, null);
+    return null;
+}
+
+/**
+ * Resolve Go package import to local files
+ * @param {string} importPath - Go import path (e.g., "github.com/user/proj/pkg/util")
+ * @param {string} fromFile - File containing the import
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} - Directory path containing the package, or null if external
+ */
+function resolveGoImport(importPath, fromFile, projectRoot) {
+    const goMod = findGoModule(path.dirname(fromFile));
+    if (!goMod) return null;
+
+    const { modulePath, root } = goMod;
+
+    // Check if the import is within this module
+    if (importPath.startsWith(modulePath)) {
+        // Convert module path to relative path
+        // e.g., "github.com/user/proj/pkg/util" -> "pkg/util"
+        const relativePath = importPath.slice(modulePath.length).replace(/^\//, '');
+        const pkgDir = path.join(root, relativePath);
+
+        // Go imports are directories, find a .go file in the directory
+        if (fs.existsSync(pkgDir) && fs.statSync(pkgDir).isDirectory()) {
+            // Return the first .go file in the directory (not _test.go)
+            try {
+                const files = fs.readdirSync(pkgDir);
+                for (const file of files) {
+                    if (file.endsWith('.go') && !file.endsWith('_test.go')) {
+                        return path.join(pkgDir, file);
+                    }
+                }
+            } catch (e) {
+                // Ignore read errors
+            }
+        }
+    }
+
+    return null;
+}
+
 /**
  * Try to resolve a path with various extensions
  */

package/core/output.js

@@ -307,25 +307,59 @@ function formatUsagesJson(usages, name) {
  * Format context (callers + callees) as JSON
  */
 function formatContextJson(context) {
+    // Handle struct/interface types differently
+    if (context.type && ['struct', 'interface', 'type'].includes(context.type)) {
+        const callers = context.callers || [];
+        const methods = context.methods || [];
+        return JSON.stringify({
+            type: context.type,
+            name: context.name,
+            file: context.file,
+            startLine: context.startLine,
+            endLine: context.endLine,
+            methodCount: methods.length,
+            usageCount: callers.length,
+            methods: methods.map(m => ({
+                name: m.name,
+                file: m.file,
+                line: m.line,
+                params: m.params,
+                returnType: m.returnType,
+                receiver: m.receiver
+            })),
+            usages: callers.map(c => ({
+                file: c.relativePath || c.file,
+                line: c.line,
+                expression: c.content,
+                callerName: c.callerName
+            })),
+            ...(context.warnings && { warnings: context.warnings })
+        }, null, 2);
+    }
+
+    // Standard function/method context
+    const callers = context.callers || [];
+    const callees = context.callees || [];
     return JSON.stringify({
         function: context.function,
         file: context.file,
-        callerCount: context.callers.length,
-        calleeCount: context.callees.length,
-        callers: context.callers.map(c => ({
+        callerCount: callers.length,
+        calleeCount: callees.length,
+        callers: callers.map(c => ({
             file: c.relativePath || c.file,
             line: c.line,
             expression: c.content,  // FULL expression
             callerName: c.callerName
         })),
-        callees: context.callees.map(c => ({
+        callees: callees.map(c => ({
             name: c.name,
             type: c.type,
             file: c.relativePath || c.file,
             line: c.startLine,
             params: c.params,  // FULL params
             weight: c.weight || 'normal'  // Dependency weight: core, setup, utility
-        }))
+        })),
+        ...(context.warnings && { warnings: context.warnings })
     }, null, 2);
 }
 

package/core/project.js

@@ -166,7 +166,11 @@ class ProjectIndex {
                 ...(item.extends && { extends: item.extends }),
                 ...(item.implements && { implements: item.implements }),
                 ...(item.indent !== undefined && { indent: item.indent }),
-                ...(item.isNested && { isNested: item.isNested })
+                ...(item.isNested && { isNested: item.isNested }),
+                ...(item.isMethod && { isMethod: item.isMethod }),
+                ...(item.receiver && { receiver: item.receiver }),
+                ...(item.className && { className: item.className }),
+                ...(item.memberType && { memberType: item.memberType })
             };
             fileEntry.symbols.push(symbol);
 
@@ -649,6 +653,55 @@ class ProjectIndex {
         return usages;
     }
 
+    /**
+     * Find methods that belong to a class/struct/type
+     * Works for:
+     * - Go: methods with receiver field (e.g., receiver: "*TypeName")
+     * - Python/Java: methods with className field
+     * - Rust: impl methods with receiver field
+     * @param {string} typeName - The class/struct/interface name
+     * @returns {Array} Methods belonging to this type
+     */
+    findMethodsForType(typeName) {
+        const methods = [];
+        // Match both "TypeName" and "*TypeName" receivers (for Go/Rust pointer receivers)
+        const baseTypeName = typeName.replace(/^\*/, '');
+
+        for (const [name, symbols] of this.symbols) {
+            for (const symbol of symbols) {
+                // Skip non-method types (fields, properties, etc.)
+                if (symbol.type === 'field' || symbol.type === 'property') {
+                    continue;
+                }
+
+                // Check Go/Rust-style receiver (e.g., func (r *Router) Method())
+                if (symbol.isMethod && symbol.receiver) {
+                    const receiverBase = symbol.receiver.replace(/^\*/, '');
+                    if (receiverBase === baseTypeName) {
+                        methods.push(symbol);
+                        continue;
+                    }
+                }
+
+                // Check Python/Java/JS-style className (class members)
+                // Must be a method type, not just any symbol with className
+                if (symbol.className === baseTypeName &&
+                    (symbol.isMethod || symbol.type === 'method' || symbol.type === 'constructor')) {
+                    methods.push(symbol);
+                    continue;
+                }
+            }
+        }
+
+        // Sort by file then line
+        methods.sort((a, b) => {
+            if (a.relativePath !== b.relativePath) return a.relativePath.localeCompare(b.relativePath);
+            return a.startLine - b.startLine;
+        });
+
+        return methods;
+    }
+
     /**
      * Get context for a symbol (callers + callees)
      */
@@ -658,7 +711,53 @@ class ProjectIndex {
             return { function: name, file: null, callers: [], callees: [] };
         }
 
-        const def = definitions[0];  // Use first definition
+        // Prefer class/struct/interface definitions over functions/methods/constructors
+        // This ensures context('ClassName') finds the class, not a constructor with same name
+        const typeOrder = ['class', 'struct', 'interface', 'type', 'impl'];
+        let def = definitions[0];
+        for (const d of definitions) {
+            if (typeOrder.includes(d.type)) {
+                def = d;
+                break;
+            }
+        }
+
+        // Special handling for class/struct/interface types
+        if (['class', 'struct', 'interface', 'type'].includes(def.type)) {
+            const methods = this.findMethodsForType(name);
+
+            const result = {
+                type: def.type,
+                name: name,
+                file: def.relativePath,
+                startLine: def.startLine,
+                endLine: def.endLine,
+                methods: methods.map(m => ({
+                    name: m.name,
+                    file: m.relativePath,
+                    line: m.startLine,
+                    params: m.params,
+                    returnType: m.returnType,
+                    receiver: m.receiver
+                })),
+                // Also include places where the type is used in function parameters/returns
+                callers: this.findCallers(name, { includeMethods: options.includeMethods })
+            };
+
+            if (definitions.length > 1) {
+                result.warnings = [{
+                    type: 'ambiguous',
+                    message: `Found ${definitions.length} definitions for "${name}". Using ${def.relativePath}:${def.startLine}. Use --file to disambiguate.`,
+                    alternatives: definitions.slice(1).map(d => ({
+                        file: d.relativePath,
+                        line: d.startLine
+                    }))
+                }];
+            }
+
+            return result;
+        }
+
         const callers = this.findCallers(name, { includeMethods: options.includeMethods });
         const callees = this.findCallees(def, { includeMethods: options.includeMethods });
 
@@ -787,8 +886,9 @@ class ProjectIndex {
                     if (call.isMethod) {
                         // Always skip this/self/cls calls (internal state access, not function calls)
                         if (['this', 'self', 'cls'].includes(call.receiver)) continue;
-                        // Skip other method calls unless explicitly requested
-                        if (!options.includeMethods) continue;
+                        // Go doesn't use this/self/cls - always include Go method calls
+                        // For other languages, skip method calls unless explicitly requested
+                        if (fileEntry.language !== 'go' && !options.includeMethods) continue;
                     }
 
                     // Skip definition lines
@@ -1594,7 +1694,14 @@ class ProjectIndex {
         for (const [name, symbols] of this.symbols) {
             for (const symbol of symbols) {
                 // Skip non-function/class types
-                if (!['function', 'class', 'method'].includes(symbol.type)) {
+                // Include various method types from different languages:
+                // - function: standalone functions
+                // - class, struct, interface: type definitions (skip them in deadcode)
+                // - method: class methods
+                // - static, public, abstract: Java method modifiers used as types
+                // - constructor: constructors
+                const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
+                if (!callableTypes.includes(symbol.type)) {
                     continue;
                 }
 
@@ -1605,11 +1712,33 @@ class ProjectIndex {
 
                 // 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)
+                // Go: main() and init() are called by runtime
+                const isGoEntryPoint = lang === 'go' && (name === 'main' || name === 'init');
+
+                // Java: public static void main(String[] args) is the entry point
+                const isJavaEntryPoint = lang === 'java' && name === 'main' &&
+                    mods.includes('public') && mods.includes('static');
+
+                // Python: Magic/dunder methods are called by the interpreter, not user code
+                const isPythonMagicMethod = lang === 'python' && /^__\w+__$/.test(name);
+
+                // Rust: main() is entry point, #[test] functions are called by test runner
+                const isRustEntryPoint = lang === 'rust' &&
+                    (name === 'main' || mods.includes('test'));
+
+                const isEntryPoint = isGoEntryPoint || isJavaEntryPoint ||
+                    isPythonMagicMethod || isRustEntryPoint;
+
                 const isExported = fileEntry && (
                     fileEntry.exports.includes(name) ||
-                    (symbol.modifiers && symbol.modifiers.includes('export')) ||
-                    (symbol.modifiers && symbol.modifiers.includes('public')) ||
-                    (fileEntry.language === 'go' && /^[A-Z]/.test(name))
+                    mods.includes('export') ||
+                    mods.includes('public') ||
+                    (lang === 'go' && /^[A-Z]/.test(name)) ||
+                    isEntryPoint
                 );
 
                 // Skip exported unless requested
@@ -3130,7 +3259,7 @@ class ProjectIndex {
         }
 
         const cacheData = {
-            version: 2,  // Bump version for new cache format
+            version: 4,  // v4: className, memberType, isMethod for all languages
             root: this.root,
             buildTime: this.buildTime,
             timestamp: Date.now(),
@@ -3163,8 +3292,10 @@ class ProjectIndex {
         try {
             const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
 
-            // Check version compatibility (support v1 and v2)
-            if (cacheData.version !== 1 && cacheData.version !== 2) {
+            // Check version compatibility
+            // v4 adds className, memberType, isMethod for all languages
+            // Only accept exactly version 4 (or future versions handled explicitly)
+            if (cacheData.version !== 4) {
                 return false;
             }
 

package/languages/java.js

@@ -111,6 +111,12 @@ function findFunctions(code, parser) {
             if (processedRanges.has(rangeKey)) return true;
             processedRanges.add(rangeKey);
 
+            // Skip methods inside a class body (they're extracted as class members)
+            let parent = node.parent;
+            if (parent && parent.type === 'class_body') {
+                return true;  // Skip - this is a class method
+            }
+
             const nameNode = node.childForFieldName('name');
             const paramsNode = node.childForFieldName('parameters');
 
@@ -393,6 +399,7 @@ function extractClassMembers(classNode, code) {
                     endLine,
                     memberType,
                     modifiers,
+                    isMethod: true,  // Mark as method for context() lookups
                     ...(returnType && { returnType }),
                     ...(docstring && { docstring })
                 });
@@ -417,6 +424,7 @@ function extractClassMembers(classNode, code) {
                     endLine,
                     memberType: 'constructor',
                     modifiers,
+                    isMethod: true,  // Mark as method for context() lookups
                     ...(docstring && { docstring })
                 });
             }

package/languages/javascript.js

@@ -531,6 +531,7 @@ function extractClassMembers(classNode, code) {
                     memberType,
                     isAsync,
                     isGenerator: isGen,
+                    isMethod: true,  // Mark as method for context() lookups
                     ...(returnType && { returnType }),
                     ...(docstring && { docstring })
                 });
@@ -557,6 +558,7 @@ function extractClassMembers(classNode, code) {
                         endLine,
                         memberType: name.startsWith('#') ? 'private' : 'field',
                         isArrow: true,
+                        isMethod: true,  // Arrow fields are callable like methods
                         ...(returnType && { returnType })
                     });
                 } else {
@@ -565,6 +567,7 @@ function extractClassMembers(classNode, code) {
                         startLine,
                         endLine,
                         memberType: name.startsWith('#') ? 'private field' : 'field'
+                        // Not a method - regular field
                     });
                 }
             }

package/languages/python.js

@@ -73,6 +73,20 @@ function findFunctions(code, parser) {
             if (processedRanges.has(rangeKey)) return true;
             processedRanges.add(rangeKey);
 
+            // Skip functions that are inside a class (they're extracted as class members)
+            let parent = node.parent;
+            // Handle decorated_definition wrapper
+            if (parent && parent.type === 'decorated_definition') {
+                parent = parent.parent;
+            }
+            // Check if parent is a class body (block inside class_definition)
+            if (parent && parent.type === 'block') {
+                const grandparent = parent.parent;
+                if (grandparent && grandparent.type === 'class_definition') {
+                    return true;  // Skip - this is a class method
+                }
+            }
+
             const nameNode = node.childForFieldName('name');
             const paramsNode = node.childForFieldName('parameters');
 
@@ -282,6 +296,7 @@ function extractClassMembers(classNode, code) {
                     endLine,
                     memberType,
                     isAsync,
+                    isMethod: true,  // Mark as method for context() lookups
                     ...(returnType && { returnType }),
                     ...(docstring && { docstring }),
                     ...(memberDecorators.length > 0 && { decorators: memberDecorators })