optave-codegraph 3.13.0

package/src/graph/classifiers/roles.ts

@@ -0,0 +1,226 @@
+/**
+ * Node role classification — pure logic, no DB.
+ *
+ * Roles: entry, core, utility, adapter, leaf, dead-*, test-only
+ *
+ * Dead sub-categories refine the coarse "dead" bucket:
+ *   dead-leaf       — parameters, properties, constants (leaf nodes by definition)
+ *   dead-entry      — framework dispatch: CLI commands, MCP tools, event handlers
+ *   dead-ffi        — cross-language FFI boundaries (e.g. Rust napi-rs bindings)
+ *   dead-unresolved — genuinely unreferenced callables (the real dead code)
+ */
+
+import type { DeadSubRole, Role } from '../../types.js';
+
+export const FRAMEWORK_ENTRY_PREFIXES: readonly string[] = ['route:', 'event:', 'command:'];
+
+// ── Dead sub-classification helpers ────────────────────────────────
+
+const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
+
+/**
+ * Type definition kinds that are consumed via type annotations rather than calls.
+ * These have no inbound call edges by design — they are "used" by type references,
+ * struct literals, and generic parameters, none of which produce call edges.
+ * If the same file has active callables, type definitions are almost certainly live.
+ */
+const TYPE_DEF_KINDS = new Set(['struct', 'enum', 'trait', 'type', 'interface', 'record']);
+
+const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
+
+/** Path patterns indicating framework-dispatched entry points. */
+const ENTRY_PATH_PATTERNS: readonly RegExp[] = [
+  /cli[/\\]commands[/\\]/,
+  /mcp[/\\]/,
+  /routes?[/\\]/,
+  /handlers?[/\\]/,
+  /middleware[/\\]/,
+];
+
+/**
+ * Well-known Commander.js dispatch method names.
+ * When a method with one of these names lives in a file that matches
+ * ENTRY_PATH_PATTERNS, it is the actual framework entry point — not merely a
+ * candidate — so it must be classified as `entry` rather than `dead-entry`.
+ *
+ * `execute` — the action callback invoked by Commander on `program.action()`.
+ * `validate` — a pre-execution argument/option validator called before `execute`.
+ */
+const COMMANDER_DISPATCH_NAMES = new Set(['execute', 'validate']);
+
+export interface ClassifiableNode {
+  kind?: string;
+  file?: string;
+}
+
+/**
+ * Refine a "dead" classification into a sub-category.
+ */
+function classifyDeadSubRole(node: ClassifiableNode): DeadSubRole {
+  // Leaf kinds are dead by definition — they can't have callers
+  if (node.kind && LEAF_KINDS.has(node.kind)) return 'dead-leaf';
+
+  if (node.file) {
+    // Cross-language FFI: compiled-language files in a JS/TS project
+    // Priority: dead-ffi is checked before dead-entry deliberately — an FFI
+    // boundary is a more fundamental classification than a path-based hint.
+    // A .so/.dll in a routes/ directory is still FFI, not an entry point.
+    const dotIdx = node.file.lastIndexOf('.');
+    if (dotIdx !== -1 && FFI_EXTENSIONS.has(node.file.slice(dotIdx))) return 'dead-ffi';
+
+    // Framework-dispatched entry points (CLI commands, MCP tools, routes)
+    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file!))) return 'dead-entry';
+  }
+
+  return 'dead-unresolved';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+export function median(sorted: number[]): number {
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
+}
+
+export interface RoleClassificationNode {
+  id: string;
+  name: string;
+  kind?: string;
+  file?: string;
+  fanIn: number;
+  fanOut: number;
+  isExported: boolean;
+  testOnlyFanIn?: number;
+  productionFanIn?: number;
+  /**
+   * True when the same file contains at least one callable connected to the graph
+   * (fanIn > 0 or fanOut > 0) that is not itself an annotation-only kind.
+   * Annotation-only kinds are `constant` and all members of `TYPE_DEF_KINDS`
+   * (struct, enum, trait, type, interface, record) — these are excluded because
+   * they are consumed via references/type-annotations rather than call edges and
+   * would otherwise produce a circular dependency in the active-file heuristic.
+   * Populated only for `constant` and `TYPE_DEF_KINDS` nodes; `undefined` for
+   * regular callables (functions, methods, classes, etc.) which don't need it.
+   */
+  hasActiveFileSiblings?: boolean;
+}
+
+/**
+ * Compute median fan-in and fan-out across nodes with non-zero values.
+ * Used as thresholds for "high" fan-in/out classification.
+ */
+function computeFanMedians(nodes: RoleClassificationNode[]): { fanIn: number; fanOut: number } {
+  const nonZeroFanIn = nodes
+    .filter((n) => n.fanIn > 0)
+    .map((n) => n.fanIn)
+    .sort((a, b) => a - b);
+  const nonZeroFanOut = nodes
+    .filter((n) => n.fanOut > 0)
+    .map((n) => n.fanOut)
+    .sort((a, b) => a - b);
+  return { fanIn: median(nonZeroFanIn), fanOut: median(nonZeroFanOut) };
+}
+
+/**
+ * Classify a node with `fanIn === 0` that is not exported.
+ * Covers framework-active constants, test-only callables, and the dead-* family.
+ */
+function classifyUnreferencedNode(node: RoleClassificationNode): Role {
+  if (node.hasActiveFileSiblings) {
+    if (node.kind === 'constant') {
+      // Constants consumed via identifier reference (not calls) have no
+      // inbound call edges. If the same file has active callables, the
+      // constant is almost certainly used locally — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind && TYPE_DEF_KINDS.has(node.kind)) {
+      // Type definitions (struct, enum, trait, type, interface, record) are
+      // consumed via type annotations and struct literals — not calls — so they
+      // never get inbound call edges. If the same file has active callables,
+      // these types are almost certainly live — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind === 'method' && node.fanOut > 0) {
+      // Methods implementing interfaces are dispatched via conditional property
+      // access e.g. `if (v.enterFunction) v.enterFunction(...)`. Codegraph
+      // resolves the call to the property accessor rather than to the concrete
+      // method implementation, so the method has no inbound call edge. We
+      // require `fanOut > 0` as evidence of non-triviality, mirroring the
+      // function case — trivially-inert dead helper methods remain visible.
+      return 'leaf';
+    }
+    if (node.kind === 'function' && node.fanOut > 0) {
+      // Functions referenced as logical-or fallback defaults — e.g.
+      // `const fn = options._fetchLatest || fetchLatestVersion` — appear as
+      // value references, not call sites, so no call edge is produced. We
+      // require `fanOut > 0` as evidence that the function is non-trivial
+      // (i.e. it calls something), ruling out truly inert dead helpers.
+      return 'leaf';
+    }
+  }
+  if (node.testOnlyFanIn != null && node.testOnlyFanIn > 0) return 'test-only';
+  return classifyDeadSubRole(node);
+}
+
+/**
+ * Pick a role from fan-in/fan-out shape: core/utility/adapter/leaf.
+ * Called after entry/test-only/dead cases have been ruled out.
+ */
+function classifyByFanShape(highIn: boolean, highOut: boolean): Role {
+  if (highIn && !highOut) return 'core';
+  if (highIn && highOut) return 'utility';
+  if (!highIn && highOut) return 'adapter';
+  return 'leaf';
+}
+
+/**
+ * Apply role-classification rules to a single node.
+ * Order matters — framework entries are tagged first, then dead/test cases,
+ * then the fan-in/fan-out shape decides among the structural roles.
+ */
+function classifyNodeRole(node: RoleClassificationNode, medFanIn: number, medFanOut: number): Role {
+  if (FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p))) return 'entry';
+
+  if (node.fanIn === 0) {
+    if (!node.isExported) {
+      // Well-known Commander.js dispatch methods (execute, validate) in framework
+      // directories are confirmed entry points, not candidates. Promote them to
+      // `entry` directly so they don't appear in `--role dead` output.
+      if (
+        node.file &&
+        COMMANDER_DISPATCH_NAMES.has(node.name) &&
+        ENTRY_PATH_PATTERNS.some((p) => p.test(node.file!))
+      ) {
+        return 'entry';
+      }
+      return classifyUnreferencedNode(node);
+    }
+    return 'entry';
+  }
+
+  const hasProdFanIn = typeof node.productionFanIn === 'number';
+  if (hasProdFanIn && node.productionFanIn === 0 && !node.isExported) return 'test-only';
+
+  const highIn = node.fanIn >= medFanIn;
+  const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+  return classifyByFanShape(highIn, highOut);
+}
+
+/**
+ * Classify nodes into architectural roles based on fan-in/fan-out metrics.
+ */
+export function classifyRoles(
+  nodes: RoleClassificationNode[],
+  medianOverrides?: { fanIn: number; fanOut: number },
+): Map<string, Role> {
+  if (nodes.length === 0) return new Map();
+
+  const { fanIn: medFanIn, fanOut: medFanOut } = medianOverrides ?? computeFanMedians(nodes);
+
+  const result = new Map<string, Role>();
+  for (const node of nodes) {
+    result.set(node.id, classifyNodeRole(node, medFanIn, medFanOut));
+  }
+  return result;
+}

package/src/graph/index.ts

@@ -0,0 +1,13 @@
+// Graph subsystem barrel export
+
+export { bfs, fanInOut, louvainCommunities, shortestPath, tarjan } from './algorithms/index.js';
+export { buildDependencyGraph, buildStructureGraph, buildTemporalGraph } from './builders/index.js';
+export {
+  classifyRoles,
+  DEFAULT_WEIGHTS,
+  FRAMEWORK_ENTRY_PREFIXES,
+  minMaxNormalize,
+  ROLE_WEIGHTS,
+  scoreRisk,
+} from './classifiers/index.js';
+export { CodeGraph } from './model.js';

package/src/graph/model.ts

@@ -0,0 +1,238 @@
+/**
+ * Unified in-memory graph model.
+ *
+ * Stores directed (default) or undirected graphs with node/edge attributes.
+ * Node IDs are always strings. DB integer IDs should be stringified before use.
+ */
+
+export interface NodeAttrs {
+  [key: string]: unknown;
+}
+
+export interface EdgeAttrs {
+  [key: string]: unknown;
+}
+
+export interface CodeGraphOpts {
+  directed?: boolean;
+}
+
+/** Canonical key for an undirected edge — smallest ID first, null-byte separated. */
+function undirectedEdgeKey(a: string, b: string): string {
+  return a < b ? `${a}\0${b}` : `${b}\0${a}`;
+}
+
+export class CodeGraph {
+  private _directed: boolean;
+  private _nodes: Map<string, NodeAttrs>;
+  private _successors: Map<string, Map<string, EdgeAttrs>>;
+  private _predecessors: Map<string, Map<string, EdgeAttrs>>;
+
+  constructor(opts: CodeGraphOpts = {}) {
+    this._directed = opts.directed !== false;
+    this._nodes = new Map();
+    this._successors = new Map();
+    this._predecessors = new Map();
+  }
+
+  get directed(): boolean {
+    return this._directed;
+  }
+
+  get nodeCount(): number {
+    return this._nodes.size;
+  }
+
+  get edgeCount(): number {
+    let count = 0;
+    for (const targets of this._successors.values()) count += targets.size;
+    // Undirected graphs store each edge twice (a→b and b→a)
+    return this._directed ? count : count / 2;
+  }
+
+  // ─── Node operations ────────────────────────────────────────────
+
+  addNode(id: string | number, attrs: NodeAttrs = {}): this {
+    const key = String(id);
+    this._nodes.set(key, attrs);
+    if (!this._successors.has(key)) this._successors.set(key, new Map());
+    if (!this._predecessors.has(key)) this._predecessors.set(key, new Map());
+    return this;
+  }
+
+  hasNode(id: string | number): boolean {
+    return this._nodes.has(String(id));
+  }
+
+  getNodeAttrs(id: string | number): NodeAttrs | undefined {
+    return this._nodes.get(String(id));
+  }
+
+  nodes(): IterableIterator<[string, NodeAttrs]> {
+    return this._nodes.entries();
+  }
+
+  nodeIds(): string[] {
+    return [...this._nodes.keys()];
+  }
+
+  // ─── Edge operations ────────────────────────────────────────────
+
+  addEdge(source: string | number, target: string | number, attrs: EdgeAttrs = {}): this {
+    const src = String(source);
+    const tgt = String(target);
+    // Auto-add nodes if missing
+    if (!this._nodes.has(src)) this.addNode(src);
+    if (!this._nodes.has(tgt)) this.addNode(tgt);
+
+    this._successors.get(src)!.set(tgt, attrs);
+    this._predecessors.get(tgt)!.set(src, attrs);
+
+    if (!this._directed) {
+      this._successors.get(tgt)!.set(src, attrs);
+      this._predecessors.get(src)!.set(tgt, attrs);
+    }
+    return this;
+  }
+
+  hasEdge(source: string | number, target: string | number): boolean {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.has(src) && this._successors.get(src)!.has(tgt);
+  }
+
+  getEdgeAttrs(source: string | number, target: string | number): EdgeAttrs | undefined {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.get(src)?.get(tgt);
+  }
+
+  *edges(): Generator<[string, string, EdgeAttrs]> {
+    if (this._directed) {
+      yield* this._directedEdges();
+    } else {
+      yield* this._undirectedEdges();
+    }
+  }
+
+  private *_directedEdges(): Generator<[string, string, EdgeAttrs]> {
+    for (const [src, targets] of this._successors) {
+      for (const [tgt, attrs] of targets) yield [src, tgt, attrs];
+    }
+  }
+
+  private *_undirectedEdges(): Generator<[string, string, EdgeAttrs]> {
+    // \0 is safe as separator — node IDs are file paths/symbols, never contain null bytes
+    const seen = new Set<string>();
+    for (const [src, targets] of this._successors) {
+      for (const [tgt, attrs] of targets) {
+        const key = undirectedEdgeKey(src, tgt);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        yield [src, tgt, attrs];
+      }
+    }
+  }
+
+  // ─── Adjacency ──────────────────────────────────────────────────
+
+  /** Direct successors of a node (outgoing edges). */
+  successors(id: string | number): string[] {
+    const key = String(id);
+    const map = this._successors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** Direct predecessors of a node (incoming edges). */
+  predecessors(id: string | number): string[] {
+    const key = String(id);
+    const map = this._predecessors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** All neighbors (union of successors + predecessors). */
+  neighbors(id: string | number): string[] {
+    const key = String(id);
+    const set = new Set<string>();
+    const succ = this._successors.get(key);
+    if (succ) for (const k of succ.keys()) set.add(k);
+    const pred = this._predecessors.get(key);
+    if (pred) for (const k of pred.keys()) set.add(k);
+    return [...set];
+  }
+
+  outDegree(id: string | number): number {
+    const map = this._successors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  inDegree(id: string | number): number {
+    const map = this._predecessors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  // ─── Filtering ──────────────────────────────────────────────────
+
+  /** Return a new graph containing only nodes matching the predicate. */
+  subgraph(predicate: (id: string, attrs: NodeAttrs) => boolean): CodeGraph {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      if (predicate(id, attrs)) g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (g.hasNode(src) && g.hasNode(tgt)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  /** Return a new graph containing only edges matching the predicate. */
+  filterEdges(predicate: (source: string, target: string, attrs: EdgeAttrs) => boolean): CodeGraph {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (predicate(src, tgt, attrs)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  // ─── Conversion ─────────────────────────────────────────────────
+
+  /** Convert to flat edge array for native Rust interop. */
+  toEdgeArray(): { source: string; target: string }[] {
+    const result: { source: string; target: string }[] = [];
+    for (const [source, target] of this.edges()) {
+      result.push({ source, target });
+    }
+    return result;
+  }
+
+  // ─── Utilities ──────────────────────────────────────────────────
+
+  clone(): CodeGraph {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      g.addEdge(src, tgt, { ...attrs });
+    }
+    return g;
+  }
+
+  /** Merge another graph into this one. Nodes/edges from other override on conflict. */
+  merge(other: CodeGraph): this {
+    for (const [id, attrs] of other.nodes()) {
+      this.addNode(id, attrs);
+    }
+    for (const [src, tgt, attrs] of other.edges()) {
+      this.addEdge(src, tgt, attrs);
+    }
+    return this;
+  }
+}

package/src/index.cjs

@@ -0,0 +1,16 @@
+/**
+ * CJS compatibility wrapper — delegates to ESM via dynamic import().
+ *
+ * This wrapper always returns a Promise on every Node version, because
+ * import() is unconditionally async. You must always await the result:
+ *
+ *   const codegraph = await require('@optave/codegraph');
+ *
+ * // Named destructuring at require-time does NOT work — always await the full result first.
+ * // BAD:  const { buildGraph } = require('@optave/codegraph');  // buildGraph is undefined
+ * // GOOD: const { buildGraph } = await require('@optave/codegraph');
+ */
+// Note: if import() rejects (e.g. missing dependency), the rejected Promise is cached
+// by the CJS module system and every subsequent require() call will re-surface the same
+// rejection without re-attempting the load.
+module.exports = import('./index.ts');

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * codegraph — Programmatic API
+ *
+ * Curated public surface: *Data() query functions, graph building,
+ * export formats, and essential constants. CLI formatters and internal
+ * utilities are not exported — import them directly if needed.
+ *
+ * Usage:
+ *   import { buildGraph, queryNameData, findCycles, exportDOT } from 'optave-codegraph';
+ */
+
+export { buildGraph } from './domain/graph/builder.js';
+export { findCycles } from './domain/graph/cycles.js';
+export {
+  briefData,
+  childrenData,
+  contextData,
+  diffImpactData,
+  explainData,
+  exportsData,
+  fileDepsData,
+  fnDepsData,
+  fnImpactData,
+  impactAnalysisData,
+  moduleMapData,
+  pathData,
+  queryNameData,
+  rolesData,
+  statsData,
+  whereData,
+} from './domain/queries.js';
+export {
+  buildEmbeddings,
+  hybridSearchData,
+  multiSearchData,
+  searchData,
+} from './domain/search/index.js';
+export { astQueryData } from './features/ast.js';
+export { auditData } from './features/audit.js';
+export { batchData } from './features/batch.js';
+export { branchCompareData } from './features/branch-compare.js';
+export { cfgData } from './features/cfg.js';
+export { checkData } from './features/check.js';
+export { coChangeData } from './features/cochange.js';
+export { communitiesData } from './features/communities.js';
+export { complexityData } from './features/complexity.js';
+export { dataflowData } from './features/dataflow.js';
+export { exportDOT, exportJSON, exportMermaid } from './features/export.js';
+export { flowData, listEntryPointsData } from './features/flow.js';
+export { manifestoData } from './features/manifesto.js';
+export { ownersData } from './features/owners.js';
+export { sequenceData } from './features/sequence.js';
+export { hotspotsData, moduleBoundariesData, structureData } from './features/structure.js';
+export { triageData } from './features/triage.js';
+export {
+  loadConfig,
+  loadConfigWithProvenance,
+  resolveUserConfigPath,
+} from './infrastructure/config.js';
+export type { ArrayCompatSet } from './shared/constants.js';
+export { EXTENSIONS, IGNORE_DIRS } from './shared/constants.js';
+export {
+  AnalysisError,
+  BoundaryError,
+  CodegraphError,
+  ConfigError,
+  DbError,
+  EngineError,
+  ParseError,
+  ResolutionError,
+} from './shared/errors.js';
+export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './shared/kinds.js';