@mishasinitcyn/betterrank 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mishasinitcyn/betterrank",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Structural code index with PageRank-ranked repo maps, symbol search, call-graph queries, and dependency analysis. Built on tree-sitter and graphology.",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -19,6 +19,7 @@ Commands:
   deps        <file>                                What this file imports (ranked)
   dependents  <file>                                What imports this file (ranked)
   neighborhood <file> [--hops N] [--max-files N]    Local subgraph (ranked by PageRank)
+  orphans     [--level file|symbol] [--kind type]   Find disconnected files/symbols
   reindex                                           Force full rebuild
   stats                                             Index statistics
 
@@ -146,6 +147,30 @@ Examples:
   betterrank neighborhood src/auth/handlers.ts --root ./backend
   betterrank neighborhood src/api/bid.js --hops 3 --max-files 20 --root .`,
 
+  orphans: `betterrank orphans [--level file|symbol] [--kind type] [--root <path>]
+
+Find disconnected files or symbols — the "satellites" in the graph UI.
+
+Levels:
+  file     Files with zero cross-file imports (default)
+  symbol   Symbols never referenced from outside their own file (dead code candidates)
+
+Options:
+  --level <type>   "file" or "symbol" (default: file)
+  --kind <type>    Filter symbols: function, class, type, variable (only with --level symbol)
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+False positives (entry points, config files, tests, framework hooks, dunders,
+etc.) are automatically excluded.
+
+Examples:
+  betterrank orphans --root ./backend
+  betterrank orphans --level symbol --root .
+  betterrank orphans --level symbol --kind function --root .
+  betterrank orphans --count --root .`,
+
   reindex: `betterrank reindex [--root <path>]
 
 Force a full rebuild of the index. Use after branch switches, large merges,
@@ -465,6 +490,55 @@ async function main() {
       break;
     }
 
+    case 'orphans': {
+      const level = flags.level || 'file';
+      if (level !== 'file' && level !== 'symbol') {
+        console.error(`Unknown level: "${level}". Use "file" or "symbol".`);
+        process.exit(1);
+      }
+      const effectiveLimit = countMode ? undefined : (userLimit !== undefined ? userLimit : DEFAULT_LIMIT);
+      const result = await idx.orphans({ level, kind: flags.kind, count: countMode, offset, limit: effectiveLimit });
+
+      if (countMode) {
+        console.log(`total: ${result.total}`);
+      } else if (level === 'file') {
+        for (const f of result) {
+          console.log(`${f.file}  (${f.symbolCount} symbols)`);
+        }
+        if (result.length === 0) {
+          console.log('(no orphan files found)');
+        } else {
+          const total = await idx.orphans({ level, count: true });
+          if (result.length < total.total) {
+            console.log(`\nShowing ${result.length} of ${total.total} orphan files (use --limit N for more)`);
+          }
+        }
+      } else {
+        // symbol level — group by file like map output
+        const byFile = new Map();
+        for (const s of result) {
+          if (!byFile.has(s.file)) byFile.set(s.file, []);
+          byFile.get(s.file).push(s);
+        }
+        for (const [file, syms] of byFile) {
+          console.log(`${file}:`);
+          for (const s of syms) {
+            console.log(`  ${String(s.lineStart).padStart(4)}│ [${s.kind}] ${s.signature}`);
+          }
+          console.log('');
+        }
+        if (result.length === 0) {
+          console.log('(no orphan symbols found)');
+        } else {
+          const total = await idx.orphans({ level, kind: flags.kind, count: true });
+          if (result.length < total.total) {
+            console.log(`Showing ${result.length} of ${total.total} orphan symbols across ${byFile.size} files (use --limit N for more)`);
+          }
+        }
+      }
+      break;
+    }
+
     case 'reindex': {
       const t0 = Date.now();
       const result = await idx.reindex();

package/src/index.js

@@ -3,6 +3,132 @@ import { join, dirname, relative, sep, basename } from 'path';
 import { CodeIndexCache } from './cache.js';
 import { rankedSymbols } from './graph.js';
 
+// ── Orphan false-positive filters ──────────────────────────────────────────
+//
+// Orphan detection finds files/symbols with no cross-file connections.
+// Many of these are false positives: entry points, config, tests, framework
+// hooks, etc. that are invoked by runtimes, not by other source files.
+// These filters aggressively exclude them (at the cost of some true positives).
+
+// File basenames (without extension) that are runtime entry points, config,
+// or package markers — they have no incoming IMPORTS because the runtime
+// loads them directly, not because they're dead.
+const ORPHAN_EXCLUDED_BASENAMES = new Set([
+  'index', 'main', 'app', 'server', 'cli', 'mod', 'lib',
+  'manage', 'wsgi', 'asgi', 'handler', 'lambda',
+  '__init__', '__main__',
+  'config', 'settings', 'conf', 'conftest', 'setup',
+  'gulpfile', 'gruntfile', 'makefile', 'rakefile', 'taskfile',
+]);
+
+// Path segments indicating test/spec directories
+const TEST_PATH_SEGMENTS = [
+  '/test/', '/tests/', '/__tests__/', '/spec/', '/specs/',
+  '/testing/', '/fixtures/', '/mocks/', '/e2e/', '/cypress/',
+];
+
+function isTestFile(filePath) {
+  const lower = '/' + filePath.toLowerCase();
+  for (const seg of TEST_PATH_SEGMENTS) {
+    if (lower.includes(seg)) return true;
+  }
+  const stem = basename(filePath).replace(/\.[^.]+$/, '').toLowerCase();
+  return (
+    stem.startsWith('test_') || stem.startsWith('test.') ||
+    stem.endsWith('.test') || stem.endsWith('.spec') ||
+    stem.endsWith('_test') || stem.endsWith('_spec')
+  );
+}
+
+function isOrphanFalsePositiveFile(filePath) {
+  const base = basename(filePath);
+  const stem = base.replace(/\.[^.]+$/, '').toLowerCase();
+
+  if (ORPHAN_EXCLUDED_BASENAMES.has(stem)) return true;
+
+  // Dotfiles are always config (.eslintrc, .prettierrc, etc.)
+  if (base.startsWith('.')) return true;
+
+  // Type definition files (.d.ts) — consumed by the compiler, not by imports
+  if (filePath.endsWith('.d.ts')) return true;
+
+  // Config files with compound names (vite.config.ts, jest.config.js, etc.)
+  if (/[./]config$/i.test(stem) || /\.rc$/i.test(stem)) return true;
+
+  // Test/spec files — invoked by test runners
+  if (isTestFile(filePath)) return true;
+
+  return false;
+}
+
+// Symbol names that are entry points, lifecycle hooks, or framework-called.
+const FRAMEWORK_INVOKED_SYMBOLS = new Set([
+  'main', 'run', 'start', 'serve', 'handler', 'execute', 'app',
+  'setup', 'teardown', 'setUp', 'tearDown',
+  'beforeAll', 'afterAll', 'beforeEach', 'afterEach', 'before', 'after',
+  'constructor', 'init', 'initialize', 'configure', 'register',
+  'middleware', 'plugin', 'default', 'module', 'exports',
+]);
+
+/**
+ * Detect if a function signature is likely a class/instance method rather
+ * than a standalone function. Method calls (obj.method()) are intentionally
+ * not tracked as references (too noisy without type info), so all methods
+ * appear orphaned. We exclude them to avoid flooding the results.
+ */
+function isLikelyMethod(signature, filePath) {
+  if (!signature) return false;
+  const s = signature.trimStart();
+
+  const ext = filePath.substring(filePath.lastIndexOf('.'));
+
+  // JS/TS: standalone functions always use the `function` keyword.
+  // Class methods don't: `async ensure()`, `getGraph()`, `constructor()`.
+  // Arrow functions assigned to vars are kind='variable', not 'function',
+  // so they don't reach this check.
+  if (['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'].includes(ext)) {
+    return !/^(export\s+)?(default\s+)?(async\s+)?function[\s(]/.test(s);
+  }
+
+  // Python: methods have self or cls as first parameter
+  if (ext === '.py') {
+    return /\(\s*(self|cls)\s*[,)]/.test(s);
+  }
+
+  // Java/C#/Go: harder to detect without parent context — don't filter
+  return false;
+}
+
+function isOrphanFalsePositiveSymbol(name, kind, filePath, signature) {
+  if (FRAMEWORK_INVOKED_SYMBOLS.has(name)) return true;
+
+  // Python dunders — called implicitly by the runtime
+  if (name.startsWith('__') && name.endsWith('__')) return true;
+
+  // Test functions — called by test runners
+  if (name.startsWith('test_') || name.startsWith('Test') ||
+      name.startsWith('spec_') || name.startsWith('Spec')) return true;
+
+  // Very short names — too generic, ambiguity cap probably suppressed real refs
+  if (name.length <= 2) return true;
+
+  // Class/instance methods — obj.method() calls aren't tracked as references,
+  // so every method appears orphaned. Filter them out.
+  if (kind === 'function' && isLikelyMethod(signature, filePath)) return true;
+
+  // Symbols in test files — all invoked by the test runner
+  if (isTestFile(filePath)) return true;
+
+  // Symbols in entry point / config files — reachable via runtime
+  if (isOrphanFalsePositiveFile(filePath)) return true;
+
+  // Symbol name matches file basename — likely the primary export
+  const fileBase = basename(filePath).replace(/\.[^.]+$/, '');
+  if (name === fileBase || name.toLowerCase() === fileBase.toLowerCase()) return true;
+
+  return false;
+}
+
 /**
  * Find file nodes in the graph that look similar to the given path.
  * Uses basename matching and substring matching on the full path.
@@ -635,6 +761,98 @@ class CodeIndex {
     };
   }
 
+  /**
+   * Find orphaned files or symbols — nodes with no cross-file connections.
+   *
+   * level='file': files with zero IMPORTS edges (neither importing nor imported).
+   *   These are the "satellites" in the graph UI.
+   *
+   * level='symbol': symbols with no incoming REFERENCES from outside their own file.
+   *   Dead code candidates — defined but never used cross-file.
+   *
+   * False positives (entry points, config files, test files, framework hooks,
+   * dunders, etc.) are excluded by default.
+   *
+   * @param {object} [opts]
+   * @param {'file'|'symbol'} [opts.level='file'] - Granularity
+   * @param {string} [opts.kind] - Filter symbols by kind (only for level='symbol')
+   * @param {number} [opts.offset] - Skip first N results
+   * @param {number} [opts.limit] - Max results to return
+   * @param {boolean} [opts.count=false] - If true, return only { total }
+   * @returns {Array|{total: number}}
+   */
+  async orphans({ level = 'file', kind, offset, limit, count = false } = {}) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph || graph.order === 0) return count ? { total: 0 } : [];
+
+    if (level === 'file') {
+      const results = [];
+      graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'file') return;
+
+        // Skip false positives: entry points, config, tests
+        if (isOrphanFalsePositiveFile(node)) return;
+
+        // Check for any IMPORTS edge (in or out)
+        let hasImport = false;
+        graph.forEachEdge(node, (_edge, edgeAttrs) => {
+          if (!hasImport && edgeAttrs.type === 'IMPORTS') hasImport = true;
+        });
+
+        if (!hasImport) {
+          results.push({ file: node, symbolCount: attrs.symbolCount || 0 });
+        }
+      });
+
+      // Meatier files first — more likely to be real orphans worth investigating
+      results.sort((a, b) => b.symbolCount - a.symbolCount);
+      if (count) return { total: results.length };
+      return paginate(results, { offset, limit }).items;
+    }
+
+    if (level === 'symbol') {
+      const results = [];
+      graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'symbol') return;
+        if (kind && attrs.kind !== kind) return;
+
+        // Skip false positives: framework hooks, dunders, test funcs, methods, etc.
+        if (isOrphanFalsePositiveSymbol(attrs.name, attrs.kind, attrs.file, attrs.signature)) return;
+
+        // Check for any incoming REFERENCES from a different file
+        let hasExternalRef = false;
+        graph.forEachInEdge(node, (_edge, edgeAttrs, source) => {
+          if (hasExternalRef) return;
+          if (edgeAttrs.type !== 'REFERENCES') return;
+          try {
+            const sourceFile = graph.getNodeAttribute(source, 'file') || source;
+            if (sourceFile !== attrs.file) hasExternalRef = true;
+          } catch {
+            if (source !== attrs.file) hasExternalRef = true;
+          }
+        });
+
+        if (!hasExternalRef) {
+          results.push({
+            name: attrs.name,
+            kind: attrs.kind,
+            file: attrs.file,
+            lineStart: attrs.lineStart,
+            signature: attrs.signature,
+          });
+        }
+      });
+
+      // Group by file, then by line within file
+      results.sort((a, b) => a.file.localeCompare(b.file) || a.lineStart - b.lineStart);
+      if (count) return { total: results.length };
+      return paginate(results, { offset, limit }).items;
+    }
+
+    throw new Error(`Unknown level: "${level}". Use "file" or "symbol".`);
+  }
+
   /**
    * File-level dependency graph for visualization.
    * Returns nodes (files) ranked by PageRank and IMPORTS edges between them.

package/src/server.js

@@ -257,6 +257,24 @@ const routes = {
     json(res, result);
   },
 
+  'GET /api/orphans': async (req, res) => {
+    if (!requireIndex(res)) return;
+    const p = params(req.url);
+    const level = p.get('level', 'file');
+    const results = await currentIndex.orphans({
+      level,
+      kind: p.get('kind', undefined),
+      offset: p.getInt('offset', undefined),
+      limit: p.getInt('limit', 50),
+    });
+    const total = await currentIndex.orphans({
+      level,
+      kind: p.get('kind', undefined),
+      count: true,
+    });
+    json(res, { results, total: total.total });
+  },
+
   'GET /api/structure': async (req, res) => {
     if (!requireIndex(res)) return;
     const p = params(req.url);