scip-query 0.3.4 → 0.3.5

package/README.md

@@ -487,31 +487,6 @@ scip-query isolated --scope src/utils
 
 ---
 
-#### `doc-coverage`
-
-Check what percentage of symbols have documentation strings. Lists undocumented symbols.
-
-```bash
-scip-query doc-coverage --min-loc 5
-# Documentation coverage: 78%
-#   Total symbols:   122
-#   Documented:      95
-#   Undocumented:    27
-#
-# Undocumented:
-#   src/utils/format.ts:15  formatCurrency
-#   src/utils/format.ts:28  formatDate
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum LOC to consider (default: 3)
-- `-n, --limit <n>` — Max undocumented symbols to show (default: 50)
-
-**Value:** Documentation health check. Focus efforts on the undocumented list.
-
----
-
 ### Codebase Metrics
 
 These commands measure structural properties of the codebase — hotspots, coupling, bottlenecks, fan-in/out.
@@ -1148,7 +1123,7 @@ scip-query similar-signatures --min-loc 5
 
 ## Programmatic API
 
-All 50 commands are available as TypeScript functions:
+All 49 commands are available as TypeScript functions:
 
 ```typescript
 import {

package/dist/{chunk-FYYOWQXK.js → chunk-6FKIA6EI.js}

@@ -1,21 +1,21 @@
-import {
-  staleAbstractions
-} from "./chunk-P4WO3BBW.js";
 import {
   stats
 } from "./chunk-74RFWB5T.js";
 import {
   wrapperCandidates
 } from "./chunk-4JCSOF2O.js";
-import {
-  passthroughCandidates
-} from "./chunk-ZEUCXQBN.js";
 import {
   similarAll
 } from "./chunk-OIDHN6GD.js";
+import {
+  staleAbstractions
+} from "./chunk-YGGFLMTM.js";
 import {
   isolated
 } from "./chunk-UQEQ6AHX.js";
+import {
+  passthroughCandidates
+} from "./chunk-ZEUCXQBN.js";
 import {
   drift
 } from "./chunk-7KIMF5PV.js";
@@ -57,20 +57,7 @@ function health(db, opts = {}) {
   const trueIsolatedCount = isolatedResult.filter(
     (s2) => !isEntrySurface(db, s2.relativePath)
   ).length;
-  const filesWithFunctions = new Set(
-    db.all(
-      `SELECT DISTINCT d.relative_path
-       FROM global_symbols gs
-       JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
-       JOIN documents d ON der.document_id = d.id
-       WHERE gs.symbol LIKE '%().'
-         ${db.pathExclusionsFor("d")}`
-    ).map((r) => r.relative_path)
-  );
-  const trueStaleCount = staleResult.filter((s2) => {
-    if (s2.consumers === 0 && filesWithFunctions.has(s2.file)) return false;
-    return true;
-  }).length;
+  const trueStaleCount = staleResult.length;
   const trueDriftCount = driftResult.results.length;
   const trueSimilarCount = similarResult.length;
   const actions = [];
@@ -145,11 +132,7 @@ function health(db, opts = {}) {
     });
   }
   if (trueStaleCount > 0) {
-    const trueStaleSymbols = staleResult.filter((s2) => {
-      if (s2.consumers === 0 && filesWithFunctions.has(s2.file)) return false;
-      return true;
-    });
-    const unused = trueStaleSymbols.filter((s2) => s2.consumers === 0).length;
+    const unused = staleResult.filter((s2) => s2.consumers === 0).length;
     const singleUse = trueStaleCount - unused;
     const parts = [];
     if (unused > 0) parts.push(`${unused} unused`);
@@ -160,7 +143,7 @@ function health(db, opts = {}) {
       effort: "low",
       impact: "medium",
       count: trueStaleCount,
-      locRecoverable: staleResult.filter((s2) => s2.consumers === 0 || !s2.file.includes("types")).reduce((sum, r) => sum + r.loc, 0)
+      locRecoverable: staleResult.reduce((sum, r) => sum + r.loc, 0)
     });
   }
   if (trueDriftCount > 0) {
@@ -235,4 +218,4 @@ function health(db, opts = {}) {
 export {
   health
 };
-//# sourceMappingURL=chunk-FYYOWQXK.js.map
+//# sourceMappingURL=chunk-6FKIA6EI.js.map

package/dist/{chunk-HLKAFWWJ.js → chunk-EN2Z2CLO.js}

@@ -115,102 +115,26 @@ function byKind(db, kindQuery, opts = {}) {
   if (kindNum === null) {
     return [];
   }
-  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : "";
-  const hasKinds = db.get(
-    `SELECT COUNT(*) AS c FROM global_symbols WHERE kind IS NOT NULL`
-  );
-  if (!hasKinds || hasKinds.c === 0) {
-    return inferByKind(db, kindNum, scope, limit);
-  }
-  const rows = db.all(
-    `SELECT gs.symbol, gs.kind, d.relative_path, der.start_line, der.end_line
-    FROM global_symbols gs
-    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
-    JOIN documents d ON der.document_id = d.id
-    WHERE gs.kind = ?
-      ${db.pathExclusionsFor("d")}
-      ${scopeFilter}
-    ORDER BY d.relative_path, der.start_line
-    LIMIT ?`,
-    kindNum,
-    limit
-  );
-  return rows.filter((r) => !db.isIgnored(r.relative_path)).map((r) => ({
-    symbol: r.symbol,
-    shortName: shortenSymbol(r.symbol),
-    kind: r.kind,
-    kindName: KIND_NAMES[r.kind] ?? "Unknown",
-    relativePath: r.relative_path,
-    startLine: r.start_line,
-    endLine: r.end_line
-  }));
-}
-function kindCounts(db, opts = {}) {
-  const scopeFilter = opts.scope ? `AND d.relative_path LIKE '%${opts.scope}%'` : "";
-  const rows = db.all(
-    `SELECT gs.kind, COUNT(*) AS cnt
-    FROM global_symbols gs
-    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
-    JOIN documents d ON der.document_id = d.id
-    WHERE 1 = 1
-      ${db.pathExclusionsFor("d")}
-      AND gs.kind IS NOT NULL
-      AND gs.kind != 0
-      ${scopeFilter}
-    GROUP BY gs.kind
-    ORDER BY cnt DESC`
-  );
-  if (rows.length === 0) {
-    return inferKindCounts(db, opts.scope);
-  }
-  return rows.map((r) => ({
-    kind: r.kind,
-    kindName: KIND_NAMES[r.kind] ?? "Unknown",
-    count: r.cnt
-  }));
-}
-function inferByKind(db, kindNum, scope, limit = 100) {
-  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : "";
-  const rows = db.all(
-    `SELECT gs.symbol, d.relative_path, der.start_line, der.end_line, gs.documentation, gs.enclosing_symbol
-     FROM global_symbols gs
-     JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
-     JOIN documents d ON der.document_id = d.id
-     WHERE 1 = 1
-       ${db.pathExclusionsFor("d")}
-       ${scopeFilter}
-     ORDER BY d.relative_path, der.start_line`
-  );
-  return rows.filter((row) => !db.isIgnored(row.relative_path)).map((row) => ({
+  const rows = loadKindRows(db, scope).map((row) => ({
     row,
-    inferredKind: inferKindNumber(row.symbol, row.documentation, row.enclosing_symbol)
-  })).filter((entry) => entry.inferredKind === kindNum).slice(0, limit).map(({ row, inferredKind }) => ({
+    resolvedKind: resolveKindNumber(row)
+  })).filter((entry) => entry.resolvedKind === kindNum).slice(0, limit);
+  return rows.map(({ row, resolvedKind }) => ({
     symbol: row.symbol,
     shortName: shortenSymbol(row.symbol),
-    kind: inferredKind,
-    kindName: KIND_NAMES[inferredKind] ?? "Unknown",
+    kind: resolvedKind,
+    kindName: KIND_NAMES[resolvedKind] ?? "Unknown",
     relativePath: row.relative_path,
     startLine: row.start_line,
     endLine: row.end_line
   }));
 }
-function inferKindCounts(db, scope) {
-  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : "";
-  const rows = db.all(
-    `SELECT gs.symbol, gs.documentation, gs.enclosing_symbol, d.relative_path
-     FROM global_symbols gs
-     JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
-     JOIN documents d ON der.document_id = d.id
-     WHERE 1 = 1
-       ${db.pathExclusionsFor("d")}
-       ${scopeFilter}`
-  );
+function kindCounts(db, opts = {}) {
   const counts = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    if (db.isIgnored(row.relative_path)) continue;
-    const inferred = inferKindNumber(row.symbol, row.documentation, row.enclosing_symbol);
-    if (inferred === null || inferred === 0) continue;
-    counts.set(inferred, (counts.get(inferred) ?? 0) + 1);
+  for (const row of loadKindRows(db, opts.scope)) {
+    const kind = resolveKindNumber(row);
+    if (kind === null || kind === 0) continue;
+    counts.set(kind, (counts.get(kind) ?? 0) + 1);
   }
   return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0]).map(([kind, count]) => ({
     kind,
@@ -218,22 +142,66 @@ function inferKindCounts(db, scope) {
     count
   }));
 }
+function loadKindRows(db, scope) {
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : "";
+  return db.all(
+    `SELECT
+      gs.symbol,
+      gs.kind,
+      gs.documentation,
+      gs.enclosing_symbol,
+      d.relative_path,
+      der.start_line,
+      der.end_line
+    FROM global_symbols gs
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d ON der.document_id = d.id
+    WHERE 1 = 1
+      ${db.pathExclusionsFor("d")}
+      ${scopeFilter}
+    ORDER BY d.relative_path, der.start_line`
+  ).filter((row) => !db.isIgnored(row.relative_path));
+}
+function resolveKindNumber(row) {
+  if (row.kind !== null && row.kind !== 0) {
+    return normalizeIndexedKind(row.kind, row.symbol, row.documentation);
+  }
+  return inferKindNumber(row.symbol, row.documentation, row.enclosing_symbol);
+}
+function normalizeIndexedKind(kind, symbol, documentation) {
+  const signature = (documentation ?? "").toLowerCase();
+  const suffix = leafSuffix(symbol);
+  if (suffix === "type") {
+    if (signature.includes("type ")) return 76;
+    if (signature.includes("interface ")) return 27;
+    if (signature.includes("struct ")) return 68;
+    if (signature.includes("trait ")) return 73;
+    if (signature.includes("class ")) return 9;
+  }
+  return kind;
+}
 function inferKindNumber(symbol, documentation, enclosingSymbol) {
   const parsed = parseSymbol(symbol);
   if ("kind" in parsed) {
     return null;
   }
   const descriptors = parsed.descriptors;
-  const last = descriptors[descriptors.length - 1] ?? null;
   const parent = descriptors[descriptors.length - 2] ?? null;
   const suffix = leafSuffix(symbol);
-  if (suffix === "type") return 9;
+  const signature = (documentation ?? "").toLowerCase();
+  if (suffix === "type") {
+    if (signature.includes("type ")) return 76;
+    if (signature.includes("interface ")) return 27;
+    if (signature.includes("struct ")) return 68;
+    if (signature.includes("trait ")) return 73;
+    if (signature.includes("class ")) return 9;
+    return 9;
+  }
   if (suffix === "method") {
     return parent?.suffix === "type" ? 33 : 23;
   }
   if (suffix === "namespace") return 39;
   if (suffix !== "term") return null;
-  const signature = (documentation ?? "").toLowerCase();
   if (signature.includes("async def ") || signature.includes("def ")) {
     return 23;
   }
@@ -248,4 +216,4 @@ export {
   byKind,
   kindCounts
 };
-//# sourceMappingURL=chunk-HLKAFWWJ.js.map
+//# sourceMappingURL=chunk-EN2Z2CLO.js.map

package/dist/chunk-FVH3Y44U.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-FVH3Y44U.js.map

package/dist/{chunk-HJZUSUPU.js → chunk-TRESG7OB.js}

@@ -37,11 +37,11 @@ function convergence(db, symbolPatternA, symbolPatternB) {
   } else if (shared.length === 0) {
     strategy = "These functions do not share any callees. They are not a callee-based consolidation candidate.";
   } else if (uniqueA.length === 0 && uniqueB.length === 0) {
-    strategy = "These functions have identical callee sets. One can replace the other directly.";
+    strategy = "These functions have identical tracked callee sets. They are a strong structural match, but identical callees do not prove interchangeable semantics; inspect signatures, control flow, and return values before consolidating.";
   } else if (uniqueA.length === 0) {
-    strategy = `A is a subset of B. A can be replaced by calling B (B does everything A does plus more).`;
+    strategy = `A's tracked callees are a subset of B's. B may subsume part of A's structure, but verify signatures, guards, and non-call logic before replacing A with B.`;
   } else if (uniqueB.length === 0) {
-    strategy = `B is a subset of A. B can be replaced by calling A (A does everything B does plus more).`;
+    strategy = `B's tracked callees are a subset of A's. A may subsume part of B's structure, but verify signatures, guards, and non-call logic before replacing B with A.`;
   } else if (uniqueA.length <= 2 && uniqueB.length <= 2) {
     strategy = `Create a shared function with the ${shared.length} common callees. Pass the ${uniqueA.length + uniqueB.length} divergent callees as parameters or strategy callbacks.`;
   } else {
@@ -73,4 +73,4 @@ function convergence(db, symbolPatternA, symbolPatternB) {
 export {
   convergence
 };
-//# sourceMappingURL=chunk-HJZUSUPU.js.map
+//# sourceMappingURL=chunk-TRESG7OB.js.map

package/dist/{chunk-GJDHTTR2.js → chunk-VMM4SYV4.js}

@@ -1,4 +1,5 @@
 import {
+  findFirstSymbolMatch,
   resolveIndexedFile
 } from "./chunk-AXQKUYKF.js";
 import {
@@ -7,21 +8,22 @@ import {
 
 // src/queries/fan.ts
 function fanIn(db, symbolPattern) {
-  const rows = db.all(
-    `SELECT gs.symbol, COUNT(DISTINCT c.document_id) AS file_count
-    FROM mentions m
-    JOIN chunks c ON m.chunk_id = c.id
-    JOIN global_symbols gs ON m.symbol_id = gs.id
-    WHERE gs.symbol LIKE ?
-      AND m.role != 1
-    GROUP BY gs.id
-    ORDER BY file_count DESC`,
-    `%${symbolPattern}%`
+  const match = findFirstSymbolMatch(db, symbolPattern);
+  if (!match) {
+    return [];
+  }
+  const row = db.get(
+    `SELECT COUNT(DISTINCT c.document_id) AS file_count
+     FROM mentions m
+     JOIN chunks c ON m.chunk_id = c.id
+     WHERE m.symbol_id = ?
+       AND m.role != 1`,
+    match.symbolId
   );
-  return rows.map((r) => ({
-    name: shortenSymbol(r.symbol),
-    count: r.file_count
-  }));
+  return [{
+    name: shortenSymbol(match.symbol),
+    count: row?.file_count ?? 0
+  }];
 }
 function fanOut(db, filePattern) {
   const resolvedFile = resolveIndexedFile(db, filePattern);
@@ -106,4 +108,4 @@ export {
   topFanIn,
   topFanOut
 };
-//# sourceMappingURL=chunk-GJDHTTR2.js.map
+//# sourceMappingURL=chunk-VMM4SYV4.js.map

package/dist/{chunk-P4WO3BBW.js → chunk-YGGFLMTM.js}

@@ -37,17 +37,11 @@ function staleAbstractions(db, opts) {
         AND (der.end_line - der.start_line + 1) >= ?
         ${scopeFilter}
     ) WHERE consumers <= 1
-    ORDER BY loc DESC
-    LIMIT ?`,
-    minLoc,
-    limit
+    ORDER BY loc DESC, file ASC, start_line ASC`,
+    minLoc
   );
-  return rows.filter((r) => !db.isIgnored(r.file)).filter((r) => {
-    const basename = r.file.split("/").pop() ?? "";
-    const isTypeFile = basename.includes("types") || r.file.includes("/types/");
-    if (isTypeFile && r.consumers > 0) return false;
-    return true;
-  }).map((r) => ({
+  const filesWithFunctions = getFilesWithFunctions(db, scope);
+  return rows.filter((r) => !db.isIgnored(r.file)).filter((r) => isTrueStaleAbstraction(r, filesWithFunctions)).map((r) => ({
     symbol: r.symbol,
     shortName: shortenSymbol(r.symbol),
     file: r.file,
@@ -55,10 +49,35 @@ function staleAbstractions(db, opts) {
     endLine: r.end_line,
     loc: r.loc,
     consumers: r.consumers
-  }));
+  })).slice(0, limit);
+}
+function getFilesWithFunctions(db, scope) {
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : "";
+  return new Set(
+    db.all(
+      `SELECT DISTINCT d.relative_path
+       FROM global_symbols gs
+       JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+       JOIN documents d ON der.document_id = d.id
+       WHERE gs.symbol LIKE '%().'
+         ${db.pathExclusionsFor("d")}
+         ${scopeFilter}`
+    ).map((row) => row.relative_path).filter((path) => !db.isIgnored(path))
+  );
+}
+function isTrueStaleAbstraction(row, filesWithFunctions) {
+  const basename = row.file.split("/").pop() ?? "";
+  const isTypeFile = basename.includes("types") || row.file.includes("/types/");
+  if (isTypeFile && row.consumers > 0) {
+    return false;
+  }
+  if (row.consumers === 0 && filesWithFunctions.has(row.file)) {
+    return false;
+  }
+  return true;
 }
 
 export {
   staleAbstractions
 };
-//# sourceMappingURL=chunk-P4WO3BBW.js.map
+//# sourceMappingURL=chunk-YGGFLMTM.js.map