@optave/codegraph 2.3.1-dev.1aeea34 → 2.5.0

package/src/queries.js

@@ -5,6 +5,7 @@ import { coChangeForFiles } from './cochange.js';
 import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
+import { paginateResult } from './paginate.js';
 import { LANGUAGE_REGISTRY } from './parser.js';
 
 /**
@@ -172,7 +173,7 @@ function findMatchingNodes(db, name, opts = {}) {
   return nodes;
 }
 
-function kindIcon(kind) {
+export function kindIcon(kind) {
   switch (kind) {
     case 'function':
       return 'f';
@@ -248,7 +249,8 @@ export function queryNameData(name, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { query: name, results };
+  const base = { query: name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function impactAnalysisData(file, customDbPath, opts = {}) {
@@ -565,6 +567,255 @@ export function fnImpactData(name, customDbPath, opts = {}) {
   return { name, results };
 }
 
+export function pathData(from, to, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+  const maxDepth = opts.maxDepth || 10;
+  const edgeKinds = opts.edgeKinds || ['calls'];
+  const reverse = opts.reverse || false;
+
+  const fromNodes = findMatchingNodes(db, from, {
+    noTests,
+    file: opts.fromFile,
+    kind: opts.kind,
+  });
+  if (fromNodes.length === 0) {
+    db.close();
+    return {
+      from,
+      to,
+      found: false,
+      error: `No symbol matching "${from}"`,
+      fromCandidates: [],
+      toCandidates: [],
+    };
+  }
+
+  const toNodes = findMatchingNodes(db, to, {
+    noTests,
+    file: opts.toFile,
+    kind: opts.kind,
+  });
+  if (toNodes.length === 0) {
+    db.close();
+    return {
+      from,
+      to,
+      found: false,
+      error: `No symbol matching "${to}"`,
+      fromCandidates: fromNodes
+        .slice(0, 5)
+        .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
+      toCandidates: [],
+    };
+  }
+
+  const sourceNode = fromNodes[0];
+  const targetNode = toNodes[0];
+
+  const fromCandidates = fromNodes
+    .slice(0, 5)
+    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
+  const toCandidates = toNodes
+    .slice(0, 5)
+    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
+
+  // Self-path
+  if (sourceNode.id === targetNode.id) {
+    db.close();
+    return {
+      from,
+      to,
+      fromCandidates,
+      toCandidates,
+      found: true,
+      hops: 0,
+      path: [
+        {
+          name: sourceNode.name,
+          kind: sourceNode.kind,
+          file: sourceNode.file,
+          line: sourceNode.line,
+          edgeKind: null,
+        },
+      ],
+      alternateCount: 0,
+      edgeKinds,
+      reverse,
+      maxDepth,
+    };
+  }
+
+  // Build edge kind filter
+  const kindPlaceholders = edgeKinds.map(() => '?').join(', ');
+
+  // BFS — direction depends on `reverse` flag
+  // Forward: source_id → target_id (A calls... calls B)
+  // Reverse: target_id → source_id (B is called by... called by A)
+  const neighborQuery = reverse
+    ? `SELECT n.id, n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+       FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind IN (${kindPlaceholders})`
+    : `SELECT n.id, n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+       FROM edges e JOIN nodes n ON e.target_id = n.id
+       WHERE e.source_id = ? AND e.kind IN (${kindPlaceholders})`;
+  const neighborStmt = db.prepare(neighborQuery);
+
+  const visited = new Set([sourceNode.id]);
+  // parent map: nodeId → { parentId, edgeKind }
+  const parent = new Map();
+  let queue = [sourceNode.id];
+  let found = false;
+  let alternateCount = 0;
+  let foundDepth = -1;
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextQueue = [];
+    for (const currentId of queue) {
+      const neighbors = neighborStmt.all(currentId, ...edgeKinds);
+      for (const n of neighbors) {
+        if (noTests && isTestFile(n.file)) continue;
+        if (n.id === targetNode.id) {
+          if (!found) {
+            found = true;
+            foundDepth = depth;
+            parent.set(n.id, { parentId: currentId, edgeKind: n.edge_kind });
+          }
+          alternateCount++;
+          continue;
+        }
+        if (!visited.has(n.id)) {
+          visited.add(n.id);
+          parent.set(n.id, { parentId: currentId, edgeKind: n.edge_kind });
+          nextQueue.push(n.id);
+        }
+      }
+    }
+    if (found) break;
+    queue = nextQueue;
+    if (queue.length === 0) break;
+  }
+
+  if (!found) {
+    db.close();
+    return {
+      from,
+      to,
+      fromCandidates,
+      toCandidates,
+      found: false,
+      hops: null,
+      path: [],
+      alternateCount: 0,
+      edgeKinds,
+      reverse,
+      maxDepth,
+    };
+  }
+
+  // alternateCount includes the one we kept; subtract 1 for "alternates"
+  alternateCount = Math.max(0, alternateCount - 1);
+
+  // Reconstruct path from target back to source
+  const pathIds = [targetNode.id];
+  let cur = targetNode.id;
+  while (cur !== sourceNode.id) {
+    const p = parent.get(cur);
+    pathIds.push(p.parentId);
+    cur = p.parentId;
+  }
+  pathIds.reverse();
+
+  // Build path with node info
+  const nodeCache = new Map();
+  const getNode = (id) => {
+    if (nodeCache.has(id)) return nodeCache.get(id);
+    const row = db.prepare('SELECT name, kind, file, line FROM nodes WHERE id = ?').get(id);
+    nodeCache.set(id, row);
+    return row;
+  };
+
+  const resultPath = pathIds.map((id, idx) => {
+    const node = getNode(id);
+    const edgeKind = idx === 0 ? null : parent.get(id).edgeKind;
+    return { name: node.name, kind: node.kind, file: node.file, line: node.line, edgeKind };
+  });
+
+  db.close();
+  return {
+    from,
+    to,
+    fromCandidates,
+    toCandidates,
+    found: true,
+    hops: foundDepth,
+    path: resultPath,
+    alternateCount,
+    edgeKinds,
+    reverse,
+    maxDepth,
+  };
+}
+
+export function symbolPath(from, to, customDbPath, opts = {}) {
+  const data = pathData(from, to, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (data.error) {
+    console.log(data.error);
+    return;
+  }
+
+  if (!data.found) {
+    const dir = data.reverse ? 'reverse ' : '';
+    console.log(`No ${dir}path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
+    if (data.fromCandidates.length > 1) {
+      console.log(
+        `\n  "${from}" matched ${data.fromCandidates.length} symbols — using top match: ${data.fromCandidates[0].name} (${data.fromCandidates[0].file}:${data.fromCandidates[0].line})`,
+      );
+    }
+    if (data.toCandidates.length > 1) {
+      console.log(
+        `  "${to}" matched ${data.toCandidates.length} symbols — using top match: ${data.toCandidates[0].name} (${data.toCandidates[0].file}:${data.toCandidates[0].line})`,
+      );
+    }
+    return;
+  }
+
+  if (data.hops === 0) {
+    console.log(`\n"${from}" and "${to}" resolve to the same symbol (0 hops):`);
+    const n = data.path[0];
+    console.log(`  ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}\n`);
+    return;
+  }
+
+  const dir = data.reverse ? ' (reverse)' : '';
+  console.log(
+    `\nPath from ${from} to ${to} (${data.hops} ${data.hops === 1 ? 'hop' : 'hops'})${dir}:\n`,
+  );
+  for (let i = 0; i < data.path.length; i++) {
+    const n = data.path[i];
+    const indent = '  '.repeat(i + 1);
+    if (i === 0) {
+      console.log(`${indent}${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`);
+    } else {
+      console.log(
+        `${indent}--[${n.edgeKind}]--> ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`,
+      );
+    }
+  }
+
+  if (data.alternateCount > 0) {
+    console.log(
+      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
+    );
+  }
+  console.log();
+}
+
 /**
  * Fix #2: Shell injection vulnerability.
  * Uses execFileSync instead of execSync to prevent shell interpretation of user input.
@@ -904,7 +1155,8 @@ export function listFunctionsData(customDbPath, opts = {}) {
   if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
 
   db.close();
-  return { count: rows.length, functions: rows };
+  const base = { count: rows.length, functions: rows };
+  return paginateResult(base, 'functions', { limit: opts.limit, offset: opts.offset });
 }
 
 export function statsData(customDbPath, opts = {}) {
@@ -1114,6 +1366,32 @@ export function statsData(customDbPath, opts = {}) {
   const roles = {};
   for (const r of roleRows) roles[r.role] = r.c;
 
+  // Complexity summary
+  let complexity = null;
+  try {
+    const cRows = db
+      .prepare(
+        `SELECT fc.cognitive, fc.cyclomatic, fc.max_nesting, fc.maintainability_index
+       FROM function_complexity fc JOIN nodes n ON fc.node_id = n.id
+       WHERE n.kind IN ('function','method') ${testFilter}`,
+      )
+      .all();
+    if (cRows.length > 0) {
+      const miValues = cRows.map((r) => r.maintainability_index || 0);
+      complexity = {
+        analyzed: cRows.length,
+        avgCognitive: +(cRows.reduce((s, r) => s + r.cognitive, 0) / cRows.length).toFixed(1),
+        avgCyclomatic: +(cRows.reduce((s, r) => s + r.cyclomatic, 0) / cRows.length).toFixed(1),
+        maxCognitive: Math.max(...cRows.map((r) => r.cognitive)),
+        maxCyclomatic: Math.max(...cRows.map((r) => r.cyclomatic)),
+        avgMI: +(miValues.reduce((s, v) => s + v, 0) / miValues.length).toFixed(1),
+        minMI: +Math.min(...miValues).toFixed(1),
+      };
+    }
+  } catch {
+    /* table may not exist in older DBs */
+  }
+
   db.close();
   return {
     nodes: { total: totalNodes, byKind: nodesByKind },
@@ -1124,11 +1402,21 @@ export function statsData(customDbPath, opts = {}) {
     embeddings,
     quality,
     roles,
+    complexity,
   };
 }
 
-export function stats(customDbPath, opts = {}) {
+export async function stats(customDbPath, opts = {}) {
   const data = statsData(customDbPath, { noTests: opts.noTests });
+
+  // Community detection summary (async import for lazy-loading)
+  try {
+    const { communitySummaryForStats } = await import('./communities.js');
+    data.communities = communitySummaryForStats(customDbPath, { noTests: opts.noTests });
+  } catch {
+    /* graphology may not be available */
+  }
+
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1236,13 +1524,39 @@ export function stats(customDbPath, opts = {}) {
     }
   }
 
+  // Complexity
+  if (data.complexity) {
+    const cx = data.complexity;
+    const miPart = cx.avgMI != null ? ` | avg MI: ${cx.avgMI} | min MI: ${cx.minMI}` : '';
+    console.log(
+      `\nComplexity: ${cx.analyzed} functions | avg cognitive: ${cx.avgCognitive} | avg cyclomatic: ${cx.avgCyclomatic} | max cognitive: ${cx.maxCognitive}${miPart}`,
+    );
+  }
+
+  // Communities
+  if (data.communities) {
+    const cm = data.communities;
+    console.log(
+      `\nCommunities: ${cm.communityCount} detected | modularity: ${cm.modularity} | drift: ${cm.driftScore}%`,
+    );
+  }
+
   console.log();
 }
 
 // ─── Human-readable output (original formatting) ───────────────────────
 
 export function queryName(name, customDbPath, opts = {}) {
-  const data = queryNameData(name, customDbPath, { noTests: opts.noTests });
+  const data = queryNameData(name, customDbPath, {
+    noTests: opts.noTests,
+    limit: opts.limit,
+    offset: opts.offset,
+  });
+  if (opts.ndjson) {
+    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
+    for (const r of data.results) console.log(JSON.stringify(r));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1698,6 +2012,27 @@ export function contextData(name, customDbPath, opts = {}) {
       });
     }
 
+    // Complexity metrics
+    let complexityMetrics = null;
+    try {
+      const cRow = db
+        .prepare(
+          'SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume FROM function_complexity WHERE node_id = ?',
+        )
+        .get(node.id);
+      if (cRow) {
+        complexityMetrics = {
+          cognitive: cRow.cognitive,
+          cyclomatic: cRow.cyclomatic,
+          maxNesting: cRow.max_nesting,
+          maintainabilityIndex: cRow.maintainability_index || 0,
+          halsteadVolume: cRow.halstead_volume || 0,
+        };
+      }
+    } catch {
+      /* table may not exist */
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -1707,6 +2042,7 @@ export function contextData(name, customDbPath, opts = {}) {
       endLine: node.end_line || null,
       source,
       signature,
+      complexity: complexityMetrics,
       callees,
       callers,
       relatedTests,
@@ -1741,6 +2077,17 @@ export function context(name, customDbPath, opts = {}) {
       console.log();
     }
 
+    // Complexity
+    if (r.complexity) {
+      const cx = r.complexity;
+      const miPart = cx.maintainabilityIndex ? ` | MI: ${cx.maintainabilityIndex}` : '';
+      console.log('## Complexity');
+      console.log(
+        `  Cognitive: ${cx.cognitive} | Cyclomatic: ${cx.cyclomatic} | Max Nesting: ${cx.maxNesting}${miPart}`,
+      );
+      console.log();
+    }
+
     // Source
     if (r.source) {
       console.log('## Source');
@@ -1959,6 +2306,27 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
       .filter((r) => isTestFile(r.file))
       .map((r) => ({ file: r.file }));
 
+    // Complexity metrics
+    let complexityMetrics = null;
+    try {
+      const cRow = db
+        .prepare(
+          'SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume FROM function_complexity WHERE node_id = ?',
+        )
+        .get(node.id);
+      if (cRow) {
+        complexityMetrics = {
+          cognitive: cRow.cognitive,
+          cyclomatic: cRow.cyclomatic,
+          maxNesting: cRow.max_nesting,
+          maintainabilityIndex: cRow.maintainability_index || 0,
+          halsteadVolume: cRow.halstead_volume || 0,
+        };
+      }
+    } catch {
+      /* table may not exist */
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -1969,6 +2337,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
       lineCount,
       summary,
       signature,
+      complexity: complexityMetrics,
       callees,
       callers,
       relatedTests,
@@ -2118,6 +2487,14 @@ export function explain(target, customDbPath, opts = {}) {
         if (r.signature.returnType) console.log(`${indent}  Returns: ${r.signature.returnType}`);
       }
 
+      if (r.complexity) {
+        const cx = r.complexity;
+        const miPart = cx.maintainabilityIndex ? ` MI=${cx.maintainabilityIndex}` : '';
+        console.log(
+          `${indent}  Complexity: cognitive=${cx.cognitive} cyclomatic=${cx.cyclomatic} nesting=${cx.maxNesting}${miPart}`,
+        );
+      }
+
       if (r.callees.length > 0) {
         console.log(`\n${indent}  Calls (${r.callees.length}):`);
         for (const c of r.callees) {
@@ -2261,11 +2638,17 @@ export function whereData(target, customDbPath, opts = {}) {
   const results = fileMode ? whereFileImpl(db, target) : whereSymbolImpl(db, target, noTests);
 
   db.close();
-  return { target, mode: fileMode ? 'file' : 'symbol', results };
+  const base = { target, mode: fileMode ? 'file' : 'symbol', results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function where(target, customDbPath, opts = {}) {
   const data = whereData(target, customDbPath, opts);
+  if (opts.ndjson) {
+    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
+    for (const r of data.results) console.log(JSON.stringify(r));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2347,11 +2730,17 @@ export function rolesData(customDbPath, opts = {}) {
   }
 
   db.close();
-  return { count: rows.length, summary, symbols: rows };
+  const base = { count: rows.length, summary, symbols: rows };
+  return paginateResult(base, 'symbols', { limit: opts.limit, offset: opts.offset });
 }
 
 export function roles(customDbPath, opts = {}) {
   const data = rolesData(customDbPath, opts);
+  if (opts.ndjson) {
+    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
+    for (const s of data.symbols) console.log(JSON.stringify(s));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;

package/src/structure.js

@@ -162,6 +162,48 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     }
   }
 
+  // Build reverse index: file → set of ancestor directories (O(files × depth))
+  const fileToAncestorDirs = new Map();
+  for (const [dir, files] of dirFiles) {
+    for (const f of files) {
+      if (!fileToAncestorDirs.has(f)) fileToAncestorDirs.set(f, new Set());
+      fileToAncestorDirs.get(f).add(dir);
+    }
+  }
+
+  // Single O(E) pass: pre-aggregate edge counts per directory
+  const dirEdgeCounts = new Map();
+  for (const dir of allDirs) {
+    dirEdgeCounts.set(dir, { intra: 0, fanIn: 0, fanOut: 0 });
+  }
+  for (const { source_file, target_file } of importEdges) {
+    const srcDirs = fileToAncestorDirs.get(source_file);
+    const tgtDirs = fileToAncestorDirs.get(target_file);
+    if (!srcDirs && !tgtDirs) continue;
+
+    // For each directory that contains the source file
+    if (srcDirs) {
+      for (const dir of srcDirs) {
+        const counts = dirEdgeCounts.get(dir);
+        if (!counts) continue;
+        if (tgtDirs?.has(dir)) {
+          counts.intra++;
+        } else {
+          counts.fanOut++;
+        }
+      }
+    }
+    // For each directory that contains the target but NOT the source
+    if (tgtDirs) {
+      for (const dir of tgtDirs) {
+        if (srcDirs?.has(dir)) continue; // already counted as intra
+        const counts = dirEdgeCounts.get(dir);
+        if (!counts) continue;
+        counts.fanIn++;
+      }
+    }
+  }
+
   const computeDirMetrics = db.transaction(() => {
     for (const [dir, files] of dirFiles) {
       const dirRow = getNodeId.get(dir, 'directory', dir, 0);
@@ -169,9 +211,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
 
       const fileCount = files.length;
       let symbolCount = 0;
-      let totalFanIn = 0;
-      let totalFanOut = 0;
-      const filesInDir = new Set(files);
 
       for (const f of files) {
         const sym = fileSymbols.get(f);
@@ -187,23 +226,10 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         }
       }
 
-      // Compute cross-boundary fan-in/fan-out and cohesion
-      let intraEdges = 0;
-      let crossEdges = 0;
-      for (const { source_file, target_file } of importEdges) {
-        const srcInside = filesInDir.has(source_file);
-        const tgtInside = filesInDir.has(target_file);
-        if (srcInside && tgtInside) {
-          intraEdges++;
-        } else if (srcInside || tgtInside) {
-          crossEdges++;
-          if (!srcInside && tgtInside) totalFanIn++;
-          if (srcInside && !tgtInside) totalFanOut++;
-        }
-      }
-
-      const totalEdges = intraEdges + crossEdges;
-      const cohesion = totalEdges > 0 ? intraEdges / totalEdges : null;
+      // O(1) lookup from pre-aggregated edge counts
+      const counts = dirEdgeCounts.get(dir) || { intra: 0, fanIn: 0, fanOut: 0 };
+      const totalEdges = counts.intra + counts.fanIn + counts.fanOut;
+      const cohesion = totalEdges > 0 ? counts.intra / totalEdges : null;
 
       upsertMetric.run(
         dirRow.id,
@@ -211,8 +237,8 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         symbolCount,
         null,
         null,
-        totalFanIn,
-        totalFanOut,
+        counts.fanIn,
+        counts.fanOut,
         cohesion,
         fileCount,
       );
@@ -226,6 +252,8 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
 
 // ─── Node role classification ─────────────────────────────────────────
 
+export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
+
 function median(sorted) {
   if (sorted.length === 0) return 0;
   const mid = Math.floor(sorted.length / 2);
@@ -235,7 +263,7 @@ function median(sorted) {
 export function classifyNodeRoles(db) {
   const rows = db
     .prepare(
-      `SELECT n.id, n.kind, n.file,
+      `SELECT n.id, n.name, n.kind, n.file,
         COALESCE(fi.cnt, 0) AS fan_in,
         COALESCE(fo.cnt, 0) AS fan_out
       FROM nodes n
@@ -287,7 +315,10 @@ export function classifyNodeRoles(db) {
     const isExported = exportedIds.has(row.id);
 
     let role;
-    if (row.fan_in === 0 && !isExported) {
+    const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => row.name.startsWith(p));
+    if (isFrameworkEntry) {
+      role = 'entry';
+    } else if (row.fan_in === 0 && !isExported) {
       role = 'dead';
     } else if (row.fan_in === 0 && isExported) {
       role = 'entry';
@@ -330,6 +361,8 @@ export function structureData(customDbPath, opts = {}) {
   const maxDepth = opts.depth || null;
   const sortBy = opts.sort || 'files';
   const noTests = opts.noTests || false;
+  const full = opts.full || false;
+  const fileLimit = opts.fileLimit || 25;
 
   // Get all directory nodes with their metrics
   let dirs = db
@@ -403,6 +436,33 @@ export function structureData(customDbPath, opts = {}) {
   });
 
   db.close();
+
+  // Apply global file limit unless full mode
+  if (!full) {
+    const totalFiles = result.reduce((sum, d) => sum + d.files.length, 0);
+    if (totalFiles > fileLimit) {
+      let shown = 0;
+      for (const d of result) {
+        const remaining = fileLimit - shown;
+        if (remaining <= 0) {
+          d.files = [];
+        } else if (d.files.length > remaining) {
+          d.files = d.files.slice(0, remaining);
+          shown = fileLimit;
+        } else {
+          shown += d.files.length;
+        }
+      }
+      const suppressed = totalFiles - fileLimit;
+      return {
+        directories: result,
+        count: result.length,
+        suppressed,
+        warning: `${suppressed} files omitted (showing ${fileLimit}/${totalFiles}). Use --full to show all files, or narrow with --directory.`,
+      };
+    }
+  }
+
   return { directories: result, count: result.length };
 }
 
@@ -539,6 +599,10 @@ export function formatStructure(data) {
       );
     }
   }
+  if (data.warning) {
+    lines.push('');
+    lines.push(`⚠ ${data.warning}`);
+  }
   return lines.join('\n');
 }