ucn 4.2.3 → 5.0.2

package/core/output/find.js

@@ -26,7 +26,7 @@ function firstSentenceShort(text) {
 /**
  * Format find command output
  */
-function formatFind(symbols, query, top) {
+function formatFind(symbols, query, top = undefined) {
     if (symbols.length === 0) {
         return `No symbols found for "${query}"`;
     }
@@ -55,13 +55,21 @@ function formatFind(symbols, query, top) {
         if (s.usageCounts !== undefined) {
             const c = s.usageCounts;
             const parts = [];
-            if (c.calls > 0) parts.push(`${c.calls} calls`);
+            if (c.calls > 0 && c.confirmedCalls !== undefined) {
+                const tiers = [];
+                if (c.confirmedCalls > 0) tiers.push(`${c.confirmedCalls} confirmed`);
+                if (c.unverifiedCalls > 0) tiers.push(`${c.unverifiedCalls} unverified`);
+                parts.push(`${c.calls} target call candidate(s) (${tiers.join(', ')})`);
+            } else if (c.calls > 0) parts.push(`${c.calls} calls`);
             if (c.definitions > 0) parts.push(`${c.definitions} def`);
             if (c.imports > 0) parts.push(`${c.imports} imports`);
             if (c.references > 0) parts.push(`${c.references} refs`);
+            const excluded = c.otherTargetCalls > 0
+                ? `; ${c.otherTargetCalls} same-name call(s) excluded as another target`
+                : '';
             lines.push(parts.length > 0
-                ? `  (${c.total} usages: ${parts.join(', ')})`
-                : `  (${c.total} usages)`);
+                ? `  (${c.total} usages: ${parts.join(', ')}${excluded})`
+                : `  (${c.total} usages${excluded})`);
         } else if (s.usageCount !== undefined) {
             lines.push(`  (${s.usageCount} usages)`);
         }
@@ -92,12 +100,12 @@ function formatFindJson(items) {
 }
 
 /**
- * Format find results with depth/confidence features (detailed view).
+ * Format find results with confidence and optional source.
  * Returns a string. Used by CLI and interactive mode.
  *
  * @param {Array} symbols - Find result array
  * @param {string} query - Original search query
- * @param {object} options - { depth, top, all }
+ * @param {object} options - { depth, top, all, compact, withSource, limitHint }
  */
 function formatFindDetailed(symbols, query, options = {}) {
     const { top, all, compact } = options;
@@ -111,14 +119,25 @@ function formatFindDetailed(symbols, query, options = {}) {
     }
 
     const lines = [];
+    const sameNameDefinitionCounts = new Map();
+    for (const symbol of symbols) {
+        sameNameDefinitionCounts.set(
+            symbol.name,
+            (sameNameDefinitionCounts.get(symbol.name) || 0) + 1,
+        );
+    }
+    for (const [name, count] of Object.entries(symbols.findInfo?.nameWideDefinitionCounts || {})) {
+        sameNameDefinitionCounts.set(name, count);
+    }
     const limit = all ? symbols.length : (top > 0 ? top : DEFAULT_LIMIT);
     const showing = Math.min(limit, symbols.length);
-    const hidden = symbols.length - showing;
+    const total = symbols.findInfo?.total ?? symbols.length;
+    const hidden = Math.max(0, total - showing);
 
     if (hidden > 0) {
-        lines.push(`Found ${symbols.length} match(es) for "${query}" (showing top ${showing}):`);
+        lines.push(`Found ${total} match(es) for "${query}" (showing top ${showing}):`);
     } else {
-        lines.push(`Found ${symbols.length} match(es) for "${query}":`);
+        lines.push(`Found ${total} match(es) for "${query}":`);
     }
     if (!compact) lines.push('─'.repeat(60));
 
@@ -144,7 +163,11 @@ function formatFindDetailed(symbols, query, options = {}) {
             // 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)`);
+                const scope = sameNameDefinitionCounts.get(s.name) > 1 ? ' name-wide' : '';
+                const label = s.usageCounts.complete === false
+                    ? `${scope} indexed activity; refs excluded`
+                    : `${scope} usages`;
+                parts.push(`(${s.usageCounts.total}${label})`);
             } else if (s.usageCount !== undefined) {
                 parts.push(`(${s.usageCount} usages)`);
             }
@@ -153,6 +176,12 @@ function formatFindDetailed(symbols, query, options = {}) {
                 if (snip) parts.push(`— ${snip}`);
             }
             lines.push(parts.join('  '));
+            if (options.withSource && s.code) {
+                lines.push('  ───');
+                for (const codeLine of String(s.code).split('\n')) {
+                    lines.push(`  ${codeLine}`);
+                }
+            }
             continue;
         }
 
@@ -164,11 +193,24 @@ function formatFindDetailed(symbols, query, options = {}) {
         if (s.usageCounts !== undefined) {
             const c = s.usageCounts;
             const parts = [];
-            if (c.calls > 0) parts.push(`${c.calls} calls`);
+            if (c.calls > 0 && c.confirmedCalls !== undefined) {
+                const tiers = [];
+                if (c.confirmedCalls > 0) tiers.push(`${c.confirmedCalls} confirmed`);
+                if (c.unverifiedCalls > 0) tiers.push(`${c.unverifiedCalls} unverified`);
+                parts.push(`${c.calls} target call candidate(s) (${tiers.join(', ')})`);
+            } else if (c.calls > 0) parts.push(`${c.calls} calls`);
             if (c.definitions > 0) parts.push(`${c.definitions} def`);
             if (c.imports > 0) parts.push(`${c.imports} imports`);
             if (c.references > 0) parts.push(`${c.references} refs`);
-            lines.push(`  (${c.total} usages: ${parts.join(', ')})`);
+            const scope = sameNameDefinitionCounts.get(s.name) > 1 ? 'name-wide ' : '';
+            const label = c.complete === false ? 'indexed activity' : 'usages';
+            const boundary = c.complete === false
+                ? '; references not counted — use usages for the full inventory'
+                : '';
+            const excluded = c.otherTargetCalls > 0
+                ? `; ${c.otherTargetCalls} same-name call(s) excluded as another target`
+                : '';
+            lines.push(`  (${c.total} ${scope}${label}: ${parts.join(', ')}${boundary}${excluded})`);
         } else if (s.usageCount !== undefined) {
             lines.push(`  (${s.usageCount} usages)`);
         }
@@ -177,8 +219,14 @@ function formatFindDetailed(symbols, query, options = {}) {
             lines.push(`  ⚠ ${confidence.reasons.join(', ')}`);
         }
 
-        // Depth 2: + first 10 lines of code
-        if (depth === '2' || depth === 'full') {
+        if (options.withSource && s.code) {
+            lines.push('  ───');
+            for (const codeLine of String(s.code).split('\n')) {
+                lines.push(`  ${codeLine}`);
+            }
+        // Legacy internal formatter mode. The v5 public command uses the
+        // explicit withSource contract instead of overloading graph depth.
+        } else if (depth === '2' || depth === 'full') {
             try {
                 const content = fs.readFileSync(s.file, 'utf-8');
                 const fileLines = content.split('\n');
@@ -199,7 +247,8 @@ function formatFindDetailed(symbols, query, options = {}) {
     }
 
     if (hidden > 0) {
-        lines.push(`... ${hidden} more result(s). Use --all to see all, or --top=N to see more.`);
+        lines.push(`... ${hidden} more result(s). ${options.limitHint ||
+            'Use --all to see all, or --top=N to see more.'}`);
     }
 
     return lines.join('\n');
@@ -245,11 +294,14 @@ function formatUsagesJson(usages, name) {
 
     const calls = refs.filter(u => u.usageType === 'call');
     const imports = refs.filter(u => u.usageType === 'import');
+    const textOccurrences = refs.filter(u => u.usageType === 'text');
+    const otherDefinitions = refs.filter(u => u.usageType === 'definition');
     // Exhaustive complement (fix #241): a non-definition record that is
     // neither call nor import lands in references — same-name definer sites
     // (usageType 'definition', isDefinition false: shadowing locals, other
     // defs of the name) used to inflate totals while rendering in NO band.
-    const references = refs.filter(u => u.usageType !== 'call' && u.usageType !== 'import');
+    const references = refs.filter(u =>
+        !['call', 'import', 'text', 'definition'].includes(u.usageType));
 
     // 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"
@@ -285,7 +337,11 @@ function formatUsagesJson(usages, name) {
             callCount: sc ? sc.calls : calls.length,
             importCount: sc ? sc.imports : imports.length,
             referenceCount: sc ? sc.references : references.length,
-            totalUsages: sc ? (sc.calls + sc.imports + sc.references) : refs.length,
+            otherDefinitionCount: sc ? (sc.otherDefinitions || 0) : otherDefinitions.length,
+            textCount: sc ? (sc.text || 0) : textOccurrences.length,
+            totalUsages: sc
+                ? (sc.calls + sc.imports + sc.references + (sc.text || 0))
+                : refs.length,
             definitions: definitions.map(d => {
                 const handle = formatSymbolHandle({ ...d, name: d.name || name });
                 return {
@@ -302,7 +358,12 @@ function formatUsagesJson(usages, name) {
             }),
             calls: calls.map(formatUsage),
             imports: imports.map(formatUsage),
-            references: references.map(formatUsage)
+            otherDefinitions: otherDefinitions.map(formatUsage),
+            references: references.map(formatUsage),
+            textOccurrences: textOccurrences.map(u => ({
+                ...formatUsage(u),
+                textKind: u.textKind || 'other-text',
+            })),
         }
     });
 }
@@ -315,15 +376,21 @@ function formatUsages(usages, name, options = {}) {
     const defs = usages.filter(u => u.isDefinition);
     const calls = usages.filter(u => u.usageType === 'call');
     const imports = usages.filter(u => u.usageType === 'import');
-    // Exhaustive complement (fix #241) — see formatUsagesJson.
-    const refs = usages.filter(u => !u.isDefinition && u.usageType !== 'call' && u.usageType !== 'import');
+    const textOccurrences = usages.filter(u => u.usageType === 'text');
+    const otherDefinitions = usages.filter(u => !u.isDefinition && u.usageType === 'definition');
+    const refs = usages.filter(u => !u.isDefinition &&
+        !['call', 'import', 'text', 'definition'].includes(u.usageType));
 
     // Under --limit the listed entries are truncated but the summary must
     // describe the FULL result set (fix #237) — the handler attaches the
     // full counts as a non-enumerable property.
     const sc = usages.summaryCounts;
     const lines = [];
-    lines.push(`Usages of "${name}": ${sc ? sc.definitions : defs.length} definitions, ${sc ? sc.calls : calls.length} calls, ${sc ? sc.imports : imports.length} imports, ${sc ? sc.references : refs.length} references`);
+    // "syntax-classified": classification is by syntax alone — a method
+    // reference is a `reference` here even when the engine confirms it as a
+    // caller. ACCOUNT lines in show/impact are engine-adjudicated, so the
+    // two breakdowns can legitimately differ; both count lines.
+    lines.push(`Usages of "${name}" (syntax-classified): ${sc ? sc.definitions : defs.length} definitions, ${sc ? (sc.otherDefinitions || 0) : otherDefinitions.length} other definitions, ${sc ? sc.calls : calls.length} calls, ${sc ? sc.imports : imports.length} imports, ${sc ? sc.references : refs.length} references, ${sc ? (sc.text || 0) : textOccurrences.length} other-text`);
     if (!compact) lines.push('═'.repeat(60));
 
     function renderContextLines(usage) {
@@ -343,8 +410,12 @@ function formatUsages(usages, name, options = {}) {
     }
 
     if (defs.length > 0) {
+        // Many same-name definitions (jsoup has 25 `parse` overloads) can
+        // consume the whole output budget before the rarer sections render —
+        // cap the section display; the header count stays complete.
+        const defLimit = !options.all && defs.length > 10 ? 10 : defs.length;
         lines.push(`${compact ? '' : '\n'}DEFINITIONS:`);
-        for (const d of defs) {
+        for (const d of defs.slice(0, defLimit)) {
             if (compact) {
                 lines.push(`  ${d.relativePath}:${d.line || d.startLine}${d.signature ? '  ' + d.signature : ''}`);
             } else {
@@ -352,23 +423,16 @@ function formatUsages(usages, name, options = {}) {
                 if (d.signature) lines.push(`    ${d.signature}`);
             }
         }
-    }
-
-    if (calls.length > 0) {
-        lines.push(`${compact ? '' : '\n'}CALLS:`);
-        for (const c of calls) {
-            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 (defLimit < defs.length) {
+            lines.push(`  ... and ${defs.length - defLimit} more definitions (${options.allHint || 'use --all'})`);
         }
     }
 
+    // Section order is bulk-LAST: imports, references, and other-text are
+    // small, high-signal sections the ACCOUNT explicitly routes agents to;
+    // CALLS is the homogeneous bulk that dominates large outputs. Rendering
+    // CALLS last means the output budget truncates redundant bulk instead of
+    // silently swallowing the rare sections (the header still promised them).
     if (imports.length > 0) {
         lines.push(`${compact ? '' : '\n'}IMPORTS:`);
         for (const i of imports) {
@@ -382,6 +446,14 @@ function formatUsages(usages, name, options = {}) {
         }
     }
 
+    if (otherDefinitions.length > 0) {
+        lines.push(`${compact ? '' : '\n'}OTHER DEFINITIONS (same spelling; not references to the selected target):`);
+        for (const d of otherDefinitions) {
+            const expression = d.content ? d.content.trim() : '';
+            lines.push(`  ${d.relativePath}:${d.line}${expression ? `\n    ${expression}` : ''}`);
+        }
+    }
+
     if (refs.length > 0) {
         lines.push(`${compact ? '' : '\n'}REFERENCES:`);
         for (const r of refs) {
@@ -397,6 +469,39 @@ function formatUsages(usages, name, options = {}) {
         }
     }
 
+    if (textOccurrences.length > 0) {
+        lines.push(`${compact ? '' : '\n'}OTHER TEXT (comments, strings, docstrings, or unclassified literal lines):`);
+        for (const occurrence of textOccurrences) {
+            const kind = occurrence.textKind || 'other-text';
+            if (compact) {
+                const expr = occurrence.content
+                    ? occurrence.content.trim().replace(/\s+/g, ' ').slice(0, 100)
+                    : '';
+                lines.push(`  ${occurrence.relativePath}:${occurrence.line} [${kind}]: ${expr}`);
+            } else {
+                lines.push(`  ${occurrence.relativePath}:${occurrence.line} [${kind}]`);
+                renderContextLines(occurrence);
+                lines.push(`    ${occurrence.content.trim()}`);
+                renderAfterLines(occurrence);
+            }
+        }
+    }
+
+    if (calls.length > 0) {
+        lines.push(`${compact ? '' : '\n'}CALLS:`);
+        for (const c of calls) {
+            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);
+            }
+        }
+    }
+
     return lines.join('\n');
 }
 

package/core/output/graph.js

@@ -23,7 +23,9 @@ function formatImports(imports, filePath) {
         for (const imp of internal) {
             lines.push(`  ${imp.module}`);
             if (imp.resolved) {
-                lines.push(`    -> ${imp.resolved}`);
+                lines.push(`    -> ${imp.resolved}${imp.indexed === false
+                    ? ' (not indexed; absent from dependency graph)'
+                    : ''}`);
             }
             if (imp.names && imp.names.length > 0 && imp.names[0] !== '*') {
                 lines.push(`    ${imp.names.join(', ')}`);
@@ -73,6 +75,7 @@ function formatImportsJson(imports, filePath) {
             names: i.names,
             type: i.type,
             resolved: i.resolved || null,
+            indexed: i.resolved ? i.indexed !== false : false,
             isDynamic: !!i.isDynamic,
             line: i.line ?? null
         }))
@@ -170,10 +173,6 @@ function formatApi(symbols, filePath) {
 
     if (symbols.length === 0) {
         lines.push('  (none found)');
-        if (filePath && filePath.endsWith('.py')) {
-            lines.push('');
-            lines.push('Note: Python requires __all__ for export detection. Use \'toc\' command to see all functions/classes.');
-        }
     } else {
         // Group by file, then dedup overloads within each file group.
         const byFile = new Map();
@@ -194,6 +193,10 @@ function formatApi(symbols, filePath) {
             lines.push('');
         }
     }
+    if (symbols.apiInfo?.pythonImplicitFiles > 0) {
+        lines.push('');
+        lines.push('Note: Python files without __all__ use the standard top-level non-underscore public-name convention; explicit `from X import Y as Y` re-exports are included.');
+    }
 
     return lines.join('\n');
 }
@@ -212,6 +215,9 @@ function formatApiJson(symbols, filePath) {
             command: 'api',
             count: deduped.length,
             ...(li && { total: li.total, truncated: true }),
+            ...(symbols.apiInfo?.pythonImplicitFiles > 0 && {
+                note: 'Python files without __all__ use the top-level non-underscore public-name convention; explicit redundant-alias re-exports are included.',
+            }),
         },
         ...(filePath && { file: filePath }),
         data: {