ucn 3.8.23 → 3.8.26

package/core/output/endpoints.js

@@ -0,0 +1,239 @@
+/**
+ * core/output/endpoints.js — Formatters for the `endpoints` command.
+ *
+ * Two surfaces: text (human) and JSON (machine).
+ *
+ * Layout principles:
+ *   - Routes grouped by file when no --bridge flag.
+ *   - With --bridge: routes listed individually, each followed by matched clients
+ *     and a confidence tag, then unmatched routes/requests.
+ *   - Counts at the top so the user knows the size up front.
+ */
+
+'use strict';
+
+const SEP_TIER = { exact: 'EXACT', partial: 'PARTIAL', uncertain: 'UNCERTAIN' };
+
+function pad(s, n) {
+    if (typeof s !== 'string') s = String(s);
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+
+function formatEndpoints(result, options = {}) {
+    if (!result) return 'No endpoints data.';
+    const { routes, requests, bridges, unmatchedRoutes, unmatchedRequests, meta } = result;
+    const showBridge = options.bridge;
+
+    if (!showBridge) {
+        return formatRoutesAndRequests(routes, requests, meta, options);
+    }
+    return formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options);
+}
+
+/**
+ * Compute the unique-request match percentage. A single client request that
+ * matches multiple server routes (e.g., trailing-slash dups) must count once,
+ * not once per bridge — otherwise "Matched: N (200%)" shows up. Returns an
+ * integer percentage clamped to [0, 100].
+ */
+function uniqueMatchPercent(bridges, totalRequests) {
+    if (!totalRequests || totalRequests <= 0) return 0;
+    const matchedRequestKeys = new Set();
+    for (const b of bridges) {
+        const r = b.request;
+        matchedRequestKeys.add(`${r.absoluteFile || r.file}:${r.line}:${r.method}:${r.path}`);
+    }
+    const pct = Math.round((matchedRequestKeys.size / totalRequests) * 100);
+    return Math.min(100, Math.max(0, pct));
+}
+
+function formatRoutesAndRequests(routes, requests, meta, options) {
+    const lines = [];
+    const showServer = !options.clientOnly;
+    const showClient = !options.serverOnly;
+
+    if (showServer) {
+        if (routes.length === 0) {
+            lines.push('No server routes detected.');
+        } else {
+            lines.push(`Server Routes: ${routes.length}`);
+            const fwSummary = Object.entries(meta.byFramework || {})
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (fwSummary) lines.push(`Frameworks: ${fwSummary}`);
+            lines.push('');
+
+            const byFile = new Map();
+            for (const r of routes) {
+                const list = byFile.get(r.file) || [];
+                list.push(r);
+                byFile.set(r.file, list);
+            }
+            for (const [file, list] of byFile) {
+                lines.push(`${file}`);
+                for (const r of list) {
+                    const handler = r.handler || '<anonymous>';
+                    const fw = r.framework ? `[${r.framework}]` : '';
+                    lines.push(`  ${pad(r.method, 7)} ${pad(r.path, 40)} → ${handler} ${fw} :${r.line}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+
+    if (showClient) {
+        if (requests.length === 0) {
+            if (showServer) lines.push('No client requests detected.');
+        } else {
+            if (showServer) lines.push('');
+            lines.push(`Client Requests: ${requests.length}`);
+            lines.push('');
+
+            const byFile = new Map();
+            for (const r of requests) {
+                const list = byFile.get(r.file) || [];
+                list.push(r);
+                byFile.set(r.file, list);
+            }
+            for (const [file, list] of byFile) {
+                lines.push(`${file}`);
+                for (const r of list) {
+                    const inferred = r.methodInferred ? '?' : '';
+                    const interp = r.interp ? ' (interp)' : '';
+                    const fw = r.framework ? `[${r.framework}]` : '';
+                    lines.push(`  ${pad(r.method + inferred, 7)} ${pad(r.path + interp, 40)} from ${r.callerName} ${fw} :${r.line}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+
+    return lines.join('\n').trimEnd();
+}
+
+function formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options = {}) {
+    const lines = [];
+    const matched = bridges.length;
+    const unmatchedOnly = !!options.unmatched;
+
+    lines.push(`Endpoint Bridges`);
+    lines.push(`================`);
+    lines.push(`Server routes: ${meta.totalRoutes}    Client requests: ${meta.totalRequests}`);
+    // HIGH-3: percentage = unique matched client requests / total client
+    // requests. Counting bridges directly inflates >100% on many-to-many
+    // matches (trailing-slash dups, wildcard overlap, etc.).
+    const pct = uniqueMatchPercent(bridges, meta.totalRequests);
+    lines.push(`Matched: ${matched} (${pct}%)    Unmatched routes: ${unmatchedRoutes.length}    Unmatched requests: ${unmatchedRequests.length}`);
+    lines.push('');
+
+    // HIGH-2: in --unmatched mode, suppress the Matched section entirely.
+    if (matched > 0 && !unmatchedOnly) {
+        // Group bridges by route for display
+        const byRoute = new Map();
+        for (const b of bridges) {
+            const key = `${b.route.absoluteFile}:${b.route.line}:${b.route.method}:${b.route.path}`;
+            const list = byRoute.get(key) || { route: b.route, clients: [] };
+            list.clients.push(b);
+            byRoute.set(key, list);
+        }
+        // Sort routes alphabetically
+        const sorted = [...byRoute.values()].sort((a, b) => {
+            if (a.route.file !== b.route.file) return a.route.file.localeCompare(b.route.file);
+            return a.route.line - b.route.line;
+        });
+
+        lines.push(`Matched (${sorted.length} routes):`);
+        for (const { route, clients } of sorted) {
+            lines.push(`  ${pad(route.method, 7)} ${route.path}  [${route.framework}]  ${route.file}:${route.line}`);
+            for (const b of clients) {
+                const conf = b.confidence.toFixed(2);
+                const tier = b.matchType.toUpperCase();
+                const inf = b.methodInferred ? ' method?' : '';
+                lines.push(`    ↔ ${pad(b.request.method + inf, 9)} ${pad(b.request.path, 30)}  ${tier} (${conf})  from ${b.request.callerName}  ${b.request.file}:${b.request.line}`);
+            }
+            lines.push('');
+        }
+    }
+
+    if (unmatchedRoutes.length > 0) {
+        lines.push(`Unmatched server routes (${unmatchedRoutes.length}):`);
+        for (const r of unmatchedRoutes) {
+            lines.push(`  ${pad(r.method, 7)} ${pad(r.path, 40)} → ${r.handler}  [${r.framework}]  ${r.file}:${r.line}`);
+        }
+        lines.push('');
+    }
+
+    if (unmatchedRequests.length > 0) {
+        lines.push(`Unmatched client requests (${unmatchedRequests.length}):`);
+        for (const r of unmatchedRequests) {
+            const inferred = r.methodInferred ? '?' : '';
+            const interp = r.interp ? ' (interp)' : '';
+            lines.push(`  ${pad(r.method + inferred, 7)} ${pad(r.path + interp, 40)} from ${r.callerName}  [${r.framework}]  ${r.file}:${r.line}`);
+        }
+    }
+
+    return lines.join('\n').trimEnd();
+}
+
+function formatEndpointsJson(result, options = {}) {
+    if (!result) return JSON.stringify({ meta: {}, data: {} }, null, 2);
+    const { routes, requests, bridges, unmatchedRoutes, unmatchedRequests, meta } = result;
+    // Read `unmatched` from explicit options OR sticky result property (set by
+    // execute.js when the user passed --unmatched). The CLI/MCP wrappers may
+    // not pass options through to JSON output, so we use both as fallbacks.
+    const unmatchedOnly = !!(options.unmatched || result._unmatched);
+
+    const trimRoute = (r) => ({
+        method: r.method,
+        path: r.path,
+        normalizedPath: r.normalizedPath,
+        handler: r.handler,
+        file: r.file,
+        line: r.line,
+        framework: r.framework,
+        ...(r.classPrefix && { classPrefix: r.classPrefix }),
+    });
+    const trimReq = (r) => ({
+        method: r.method,
+        path: r.path,
+        normalizedPath: r.normalizedPath,
+        ...(r.interp && { interp: true }),
+        file: r.file,
+        line: r.line,
+        callerName: r.callerName,
+        ...(r.callerStartLine && { callerStartLine: r.callerStartLine }),
+        framework: r.framework,
+        ...(r.methodInferred && { methodInferred: true }),
+    });
+    const trimBridge = (b) => ({
+        route: trimRoute(b.route),
+        request: trimReq(b.request),
+        matchType: b.matchType,
+        confidence: b.confidence,
+        ...(b.methodInferred && { methodInferred: true }),
+    });
+
+    return JSON.stringify({
+        meta: {
+            ok: true,
+            ...meta,
+            // HIGH-2: signal to consumers that bridges array was suppressed
+            // because the user filtered to unmatched-only.
+            ...(unmatchedOnly && { filterMode: 'unmatched' }),
+        },
+        data: {
+            routes: routes.map(trimRoute),
+            requests: requests.map(trimReq),
+            // In unmatched-only mode, the matched bridges array is suppressed
+            // — consumers that want both should not pass --unmatched.
+            bridges: unmatchedOnly ? [] : bridges.map(trimBridge),
+            unmatchedRoutes: unmatchedRoutes.map(trimRoute),
+            unmatchedRequests: unmatchedRequests.map(trimReq),
+        },
+    }, null, 2);
+}
+
+module.exports = {
+    formatEndpoints,
+    formatEndpointsJson,
+};

package/core/output/extraction.js

@@ -45,6 +45,7 @@ function formatFunctionJson(fn, code) {
         endLine: fn.endLine,
         modifiers: fn.modifiers || [],
         ...(fn.returnType && { returnType: fn.returnType }),
+        ...(fn.paramTypes && { paramTypes: fn.paramTypes }),
         ...(fn.generics && { generics: fn.generics }),
         ...(fn.docstring && { docstring: fn.docstring }),
         ...(fn.isArrow && { isArrow: true }),
@@ -82,6 +83,7 @@ function formatFnResultJson(result) {
         endLine: match.endLine,
         modifiers: match.modifiers || [],
         ...(match.returnType && { returnType: match.returnType }),
+        ...(match.paramTypes && { paramTypes: match.paramTypes }),
         ...(match.generics && { generics: match.generics }),
         ...(match.docstring && { docstring: match.docstring }),
         ...(match.isArrow && { isArrow: true }),

package/core/output/find.js

@@ -9,6 +9,20 @@ const {
     computeConfidence,
 } = require('./shared');
 
+const { formatSymbolHandle } = require('../shared');
+
+/**
+ * Trim a docstring to a single short sentence (max 80 chars) for inline display.
+ */
+function firstSentenceShort(text) {
+    if (!text) return null;
+    const trimmed = text.trim();
+    const m = trimmed.match(/^(.+?[.!?])(?:\s|$)/);
+    let s = m ? m[1] : trimmed;
+    if (s.length > 80) s = s.slice(0, 77) + '...';
+    return s;
+}
+
 /**
  * Format find command output
  */
@@ -34,6 +48,10 @@ function formatFind(symbols, query, top) {
             ? formatFunctionSignature(s)
             : formatClassSignature(s);
         lines.push(`${s.relativePath}:${s.startLine}  ${sig}`);
+        if (s.docstring) {
+            const snip = firstSentenceShort(s.docstring);
+            if (snip) lines.push(`  "${snip}"`);
+        }
         if (s.usageCounts !== undefined) {
             const c = s.usageCounts;
             const parts = [];
@@ -57,6 +75,7 @@ function formatFind(symbols, query, top) {
 }
 
 function formatFindJson(items) {
+    const { formatSymbolHandle } = require('../shared');
     return JSON.stringify({
         meta: { command: 'find', count: items.length },
         data: items.map(m => ({
@@ -65,6 +84,7 @@ function formatFindJson(items) {
             file: m.relativePath || m.file,
             line: m.startLine,
             endLine: m.endLine,
+            handle: formatSymbolHandle(m),
             ...(m.className && { className: m.className }),
             ...(m.receiver && { receiver: m.receiver }),
         })),
@@ -80,7 +100,7 @@ function formatFindJson(items) {
  * @param {object} options - { depth, top, all }
  */
 function formatFindDetailed(symbols, query, options = {}) {
-    const { depth, top, all } = options;
+    const { depth, top, all, compact } = options;
     const DEFAULT_LIMIT = 5;
 
     if (symbols.length === 0) {
@@ -97,7 +117,7 @@ function formatFindDetailed(symbols, query, options = {}) {
     } else {
         lines.push(`Found ${symbols.length} match(es) for "${query}":`);
     }
-    lines.push('─'.repeat(60));
+    if (!compact) lines.push('─'.repeat(60));
 
     for (let i = 0; i < showing; i++) {
         const s = symbols[i];
@@ -114,8 +134,30 @@ function formatFindDetailed(symbols, query, options = {}) {
 
         const confidence = computeConfidence(s);
         const confStr = confidence.level !== 'high' ? ` [${confidence.level}]` : '';
+        const handle = formatSymbolHandle(s);
+        const loc = handle || (s.relativePath + ':' + s.startLine);
+
+        if (compact) {
+            // One line per result: "<handle>  <sig>  <usages?>  <doc snippet?>"
+            const parts = [`${loc}  ${sig}${confStr}`];
+            if (s.usageCounts !== undefined && s.usageCounts.total > 0) {
+                parts.push(`(${s.usageCounts.total} usages)`);
+            } else if (s.usageCount !== undefined) {
+                parts.push(`(${s.usageCount} usages)`);
+            }
+            if (s.docstring) {
+                const snip = firstSentenceShort(s.docstring);
+                if (snip) parts.push(`— ${snip}`);
+            }
+            lines.push(parts.join('  '));
+            continue;
+        }
 
-        lines.push(`${s.relativePath}:${s.startLine}  ${sig}${confStr}`);
+        lines.push(`${loc}  ${sig}${confStr}`);
+        if (s.docstring) {
+            const snip = firstSentenceShort(s.docstring);
+            if (snip) lines.push(`  "${snip}"`);
+        }
         if (s.usageCounts !== undefined) {
             const c = s.usageCounts;
             const parts = [];
@@ -150,7 +192,7 @@ function formatFindDetailed(symbols, query, options = {}) {
                 // Skip code extraction on error
             }
         }
-        lines.push('');
+        if (!compact) lines.push('');
     }
 
     if (hidden > 0) {
@@ -164,6 +206,7 @@ function formatFindDetailed(symbols, query, options = {}) {
  * Format symbol search results as JSON
  */
 function formatSymbolJson(symbols, query) {
+    const { formatSymbolHandle } = require('../shared');
     return JSON.stringify({
         meta: { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
         data: {
@@ -175,9 +218,12 @@ function formatSymbolJson(symbols, query) {
                 file: s.relativePath || s.file,
                 startLine: s.startLine,
                 endLine: s.endLine,
+                handle: formatSymbolHandle(s),
                 ...(s.params && { params: s.params }),  // FULL params
                 ...(s.paramsStructured && { paramsStructured: s.paramsStructured }),
                 ...(s.returnType && { returnType: s.returnType }),
+                ...(s.paramTypes && { paramTypes: s.paramTypes }),
+                ...(s.docstring && { docstring: s.docstring }),
                 ...(s.modifiers && { modifiers: s.modifiers }),
                 ...(s.usageCount !== undefined && { usageCount: s.usageCount }),
                 ...(s.usageCounts !== undefined && { usageCounts: s.usageCounts })
@@ -190,6 +236,7 @@ function formatSymbolJson(symbols, query) {
  * Format usages as JSON - FULL expressions, never truncated
  */
 function formatUsagesJson(usages, name) {
+    const { formatSymbolHandle } = require('../shared');
     const definitions = usages.filter(u => u.isDefinition);
     const refs = usages.filter(u => !u.isDefinition);
 
@@ -197,14 +244,29 @@ function formatUsagesJson(usages, name) {
     const imports = refs.filter(u => u.usageType === 'import');
     const references = refs.filter(u => u.usageType === 'reference');
 
-    const formatUsage = (u) => ({
-        file: u.relativePath || u.file,
-        line: u.line,
-        expression: u.content,  // FULL expression - key improvement
-        ...(u.args && { args: u.args }),  // Parsed arguments
-        ...(u.before && u.before.length > 0 && { before: u.before }),
-        ...(u.after && u.after.length > 0 && { after: u.after })
-    });
+    // Each usage record points at a call site. We emit a per-occurrence handle
+    // pointing at the SITE itself in the form "relativePath:line:callerName"
+    // (or "relativePath:line:_topLevel" when the call is at module scope and has
+    // no enclosing function). When the enclosing function position is known, we
+    // also emit `enclosingHandle` as a jump-back target to the function head.
+    const formatUsage = (u) => {
+        const file = u.relativePath || u.file;
+        const callerToken = u.callerName || '_topLevel';
+        const handle = `${file}:${u.line}:${callerToken}`;
+        const enclosingHandle = (u.callerStartLine && u.callerName)
+            ? `${file}:${u.callerStartLine}:${u.callerName}`
+            : undefined;
+        return {
+            file,
+            line: u.line,
+            handle,
+            ...(enclosingHandle && { enclosingHandle }),
+            expression: u.content,  // FULL expression - key improvement
+            ...(u.args && { args: u.args }),  // Parsed arguments
+            ...(u.before && u.before.length > 0 && { before: u.before }),
+            ...(u.after && u.after.length > 0 && { after: u.after })
+        };
+    };
 
     return JSON.stringify({
         meta: { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
@@ -215,15 +277,20 @@ function formatUsagesJson(usages, name) {
             importCount: imports.length,
             referenceCount: references.length,
             totalUsages: refs.length,
-            definitions: definitions.map(d => ({
-                file: d.relativePath || d.file,
-                line: d.line,
-                signature: d.signature || null,  // FULL signature
-                type: d.type || null,
-                ...(d.returnType && { returnType: d.returnType }),
-                ...(d.before && d.before.length > 0 && { before: d.before }),
-                ...(d.after && d.after.length > 0 && { after: d.after })
-            })),
+            definitions: definitions.map(d => {
+                const handle = formatSymbolHandle({ ...d, name: d.name || name });
+                return {
+                    file: d.relativePath || d.file,
+                    line: d.line,
+                    ...(handle && { handle }),
+                    signature: d.signature || null,  // FULL signature
+                    type: d.type || null,
+                    ...(d.returnType && { returnType: d.returnType }),
+                    ...(d.docstring && { docstring: d.docstring }),
+                    ...(d.before && d.before.length > 0 && { before: d.before }),
+                    ...(d.after && d.after.length > 0 && { after: d.after })
+                };
+            }),
             calls: calls.map(formatUsage),
             imports: imports.map(formatUsage),
             references: references.map(formatUsage)
@@ -234,7 +301,8 @@ function formatUsagesJson(usages, name) {
 /**
  * Format usages command output
  */
-function formatUsages(usages, name) {
+function formatUsages(usages, name, options = {}) {
+    const compact = !!options.compact;
     const defs = usages.filter(u => u.isDefinition);
     const calls = usages.filter(u => u.usageType === 'call');
     const imports = usages.filter(u => u.usageType === 'import');
@@ -242,7 +310,7 @@ function formatUsages(usages, name) {
 
     const lines = [];
     lines.push(`Usages of "${name}": ${defs.length} definitions, ${calls.length} calls, ${imports.length} imports, ${refs.length} references`);
-    lines.push('═'.repeat(60));
+    if (!compact) lines.push('═'.repeat(60));
 
     function renderContextLines(usage) {
         if (usage.before && usage.before.length > 0) {
@@ -261,38 +329,57 @@ function formatUsages(usages, name) {
     }
 
     if (defs.length > 0) {
-        lines.push('\nDEFINITIONS:');
+        lines.push(`${compact ? '' : '\n'}DEFINITIONS:`);
         for (const d of defs) {
-            lines.push(`  ${d.relativePath}:${d.line || d.startLine}`);
-            if (d.signature) lines.push(`    ${d.signature}`);
+            if (compact) {
+                lines.push(`  ${d.relativePath}:${d.line || d.startLine}${d.signature ? '  ' + d.signature : ''}`);
+            } else {
+                lines.push(`  ${d.relativePath}:${d.line || d.startLine}`);
+                if (d.signature) lines.push(`    ${d.signature}`);
+            }
         }
     }
 
     if (calls.length > 0) {
-        lines.push('\nCALLS:');
+        lines.push(`${compact ? '' : '\n'}CALLS:`);
         for (const c of calls) {
-            lines.push(`  ${c.relativePath}:${c.line}`);
-            renderContextLines(c);
-            lines.push(`    ${c.content.trim()}`);
-            renderAfterLines(c);
+            if (compact) {
+                const expr = c.content ? c.content.trim().replace(/\s+/g, ' ').slice(0, 100) : '';
+                lines.push(`  ${c.relativePath}:${c.line}: ${expr}`);
+            } else {
+                lines.push(`  ${c.relativePath}:${c.line}`);
+                renderContextLines(c);
+                lines.push(`    ${c.content.trim()}`);
+                renderAfterLines(c);
+            }
         }
     }
 
     if (imports.length > 0) {
-        lines.push('\nIMPORTS:');
+        lines.push(`${compact ? '' : '\n'}IMPORTS:`);
         for (const i of imports) {
-            lines.push(`  ${i.relativePath}:${i.line}`);
-            lines.push(`    ${i.content.trim()}`);
+            if (compact) {
+                const expr = i.content ? i.content.trim().replace(/\s+/g, ' ').slice(0, 100) : '';
+                lines.push(`  ${i.relativePath}:${i.line}: ${expr}`);
+            } else {
+                lines.push(`  ${i.relativePath}:${i.line}`);
+                lines.push(`    ${i.content.trim()}`);
+            }
         }
     }
 
     if (refs.length > 0) {
-        lines.push('\nREFERENCES:');
+        lines.push(`${compact ? '' : '\n'}REFERENCES:`);
         for (const r of refs) {
-            lines.push(`  ${r.relativePath}:${r.line}`);
-            renderContextLines(r);
-            lines.push(`    ${r.content.trim()}`);
-            renderAfterLines(r);
+            if (compact) {
+                const expr = r.content ? r.content.trim().replace(/\s+/g, ' ').slice(0, 100) : '';
+                lines.push(`  ${r.relativePath}:${r.line}: ${expr}`);
+            } else {
+                lines.push(`  ${r.relativePath}:${r.line}`);
+                renderContextLines(r);
+                lines.push(`    ${r.content.trim()}`);
+                renderAfterLines(r);
+            }
         }
     }
 

package/core/output/graph.js

@@ -105,6 +105,22 @@ function formatExportersJson(exporters, filePath) {
     }, null, 2);
 }
 
+/**
+ * Dedup exported/api symbols. TypeScript overloads emit one symbol per overload
+ * declaration with identical name/signature; collapse them to a single entry.
+ * Key is "name|signature" (falls back to name|startLine when no signature).
+ */
+function dedupExportSymbols(symbols) {
+    if (!Array.isArray(symbols)) return symbols;
+    const seen = new Map();
+    for (const s of symbols) {
+        const sig = s.signature || (s.params !== undefined ? `${s.name}(${s.params})` : '');
+        const key = sig ? `${s.name}|${sig}` : `${s.name}|${s.startLine}`;
+        if (!seen.has(key)) seen.set(key, s);
+    }
+    return Array.from(seen.values());
+}
+
 /**
  * Format file-exports command output
  */
@@ -112,9 +128,10 @@ function formatFileExports(exports, filePath) {
     if (exports?.error) return formatFileError(exports, filePath);
     if (exports.length === 0) return `No exports found in ${filePath}`;
 
+    const deduped = dedupExportSymbols(exports);
     const lines = [];
     lines.push(`Exports from ${filePath}:\n`);
-    for (const exp of exports) {
+    for (const exp of deduped) {
         lines.push(`  ${lineRange(exp.startLine, exp.endLine)} ${exp.signature || exp.name}`);
     }
     return lines.join('\n');
@@ -123,11 +140,13 @@ function formatFileExports(exports, filePath) {
 function formatFileExportsJson(result, filePath) {
     if (!result) return JSON.stringify({ found: false });
     // result is an array of exported symbols from index.fileExports()
+    const rawExports = Array.isArray(result) ? result : (result.exports || []);
+    const exports = dedupExportSymbols(rawExports);
     return JSON.stringify({
         meta: { command: 'fileExports', file: filePath || (Array.isArray(result) ? result[0]?.file : result.file) },
         data: {
             file: filePath || (Array.isArray(result) ? result[0]?.file : result.file),
-            exports: Array.isArray(result) ? result : (result.exports || []),
+            exports,
         },
     }, null, 2);
 }
@@ -148,7 +167,7 @@ function formatApi(symbols, filePath) {
             lines.push('Note: Python requires __all__ for export detection. Use \'toc\' command to see all functions/classes.');
         }
     } else {
-        // Group by file
+        // Group by file, then dedup overloads within each file group.
         const byFile = new Map();
         for (const sym of symbols) {
             if (!byFile.has(sym.file)) {
@@ -159,7 +178,8 @@ function formatApi(symbols, filePath) {
 
         for (const [file, syms] of byFile) {
             lines.push(file);
-            for (const s of syms) {
+            const dedupedSyms = dedupExportSymbols(syms);
+            for (const s of dedupedSyms) {
                 const sig = s.signature || `${s.type} ${s.name}`;
                 lines.push(`  ${lineRange(s.startLine, s.endLine)} ${sig}`);
             }
@@ -174,19 +194,32 @@ function formatApi(symbols, filePath) {
  * Format api as JSON
  */
 function formatApiJson(symbols, filePath) {
+    const { formatSymbolHandle } = require('../shared');
+    const deduped = dedupExportSymbols(symbols);
     return JSON.stringify({
+        meta: { command: 'api', count: deduped.length },
         ...(filePath && { file: filePath }),
-        exportCount: symbols.length,
-        exports: symbols.map(s => ({
-            name: s.name,
-            type: s.type,
-            file: s.file,
-            startLine: s.startLine,
-            endLine: s.endLine,
-            ...(s.params && { params: s.params }),
-            ...(s.returnType && { returnType: s.returnType }),
-            ...(s.signature && { signature: s.signature })
-        }))
+        data: {
+            exportCount: deduped.length,
+            exports: deduped.map(s => {
+                const handleSym = { ...s, relativePath: s.relativePath || s.file };
+                const handle = formatSymbolHandle(handleSym);
+                return {
+                    name: s.name,
+                    type: s.type,
+                    file: s.file,
+                    startLine: s.startLine,
+                    endLine: s.endLine,
+                    ...(handle && { handle }),
+                    ...(s.params && { params: s.params }),
+                    ...(s.paramsStructured && { paramsStructured: s.paramsStructured }),
+                    ...(s.paramTypes && { paramTypes: s.paramTypes }),
+                    ...(s.returnType && { returnType: s.returnType }),
+                    ...(s.docstring && { docstring: s.docstring }),
+                    ...(s.signature && { signature: s.signature }),
+                };
+            }),
+        },
     }, null, 2);
 }