@optave/codegraph 3.1.2 → 3.1.4

package/src/graph/builders/temporal.js

@@ -0,0 +1,33 @@
+/**
+ * Build a co-change (temporal) graph weighted by Jaccard similarity.
+ */
+
+import { CodeGraph } from '../model.js';
+
+/**
+ * @param {object} db - Open better-sqlite3 database (readonly)
+ * @param {{ minJaccard?: number }} [opts]
+ * @returns {CodeGraph} Undirected graph weighted by Jaccard similarity
+ */
+export function buildTemporalGraph(db, opts = {}) {
+  const minJaccard = opts.minJaccard ?? 0.0;
+  const graph = new CodeGraph({ directed: false });
+
+  // Check if co_changes table exists
+  const tableCheck = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='co_changes'")
+    .get();
+  if (!tableCheck) return graph;
+
+  const rows = db
+    .prepare('SELECT file_a, file_b, jaccard FROM co_changes WHERE jaccard >= ?')
+    .all(minJaccard);
+
+  for (const r of rows) {
+    if (!graph.hasNode(r.file_a)) graph.addNode(r.file_a, { label: r.file_a });
+    if (!graph.hasNode(r.file_b)) graph.addNode(r.file_b, { label: r.file_b });
+    graph.addEdge(r.file_a, r.file_b, { jaccard: r.jaccard });
+  }
+
+  return graph;
+}

package/src/graph/classifiers/index.js

@@ -0,0 +1,2 @@
+export { DEFAULT_WEIGHTS, minMaxNormalize, ROLE_WEIGHTS, scoreRisk } from './risk.js';
+export { classifyRoles, FRAMEWORK_ENTRY_PREFIXES } from './roles.js';

package/src/graph/classifiers/risk.js

@@ -0,0 +1,85 @@
+/**
+ * Risk scoring — pure logic, no DB.
+ */
+
+// Weights sum to 1.0. Complexity gets the highest weight because cognitive load
+// is the strongest predictor of defect density. Fan-in and churn are next as
+// they reflect coupling and volatility. Role adds architectural context, and MI
+// (maintainability index) is a weaker composite signal, so it gets the least.
+export const DEFAULT_WEIGHTS = {
+  fanIn: 0.25,
+  complexity: 0.3,
+  churn: 0.2,
+  role: 0.15,
+  mi: 0.1,
+};
+
+// Role weights reflect structural importance: core modules are central to the
+// dependency graph, utilities are widely imported, entry points are API
+// surfaces. Adapters bridge subsystems but are replaceable. Leaves and dead
+// code have minimal downstream impact.
+export const ROLE_WEIGHTS = {
+  core: 1.0,
+  utility: 0.9,
+  entry: 0.8,
+  adapter: 0.5,
+  leaf: 0.2,
+  dead: 0.1,
+};
+
+const DEFAULT_ROLE_WEIGHT = 0.5;
+
+/** Min-max normalize an array of numbers. All-equal → all zeros. */
+export function minMaxNormalize(values) {
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  if (max === min) return values.map(() => 0);
+  const range = max - min;
+  return values.map((v) => (v - min) / range);
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}
+
+/**
+ * Score risk for a list of items.
+ *
+ * @param {{ fan_in: number, cognitive: number, churn: number, mi: number, role: string|null }[]} items
+ * @param {object} [weights] - Override DEFAULT_WEIGHTS
+ * @returns {{ normFanIn: number, normComplexity: number, normChurn: number, normMI: number, roleWeight: number, riskScore: number }[]}
+ *   Parallel array with risk metrics for each input item.
+ */
+export function scoreRisk(items, weights = {}) {
+  const w = { ...DEFAULT_WEIGHTS, ...weights };
+
+  const fanIns = items.map((r) => r.fan_in);
+  const cognitives = items.map((r) => r.cognitive);
+  const churns = items.map((r) => r.churn);
+  const mis = items.map((r) => r.mi);
+
+  const normFanIns = minMaxNormalize(fanIns);
+  const normCognitives = minMaxNormalize(cognitives);
+  const normChurns = minMaxNormalize(churns);
+  const normMIsRaw = minMaxNormalize(mis);
+  const normMIs = normMIsRaw.map((v) => round4(1 - v));
+
+  return items.map((r, i) => {
+    const roleWeight = ROLE_WEIGHTS[r.role] ?? DEFAULT_ROLE_WEIGHT;
+    const riskScore =
+      w.fanIn * normFanIns[i] +
+      w.complexity * normCognitives[i] +
+      w.churn * normChurns[i] +
+      w.role * roleWeight +
+      w.mi * normMIs[i];
+
+    return {
+      normFanIn: round4(normFanIns[i]),
+      normComplexity: round4(normCognitives[i]),
+      normChurn: round4(normChurns[i]),
+      normMI: round4(normMIs[i]),
+      roleWeight,
+      riskScore: round4(riskScore),
+    };
+  });
+}

package/src/graph/classifiers/roles.js

@@ -0,0 +1,64 @@
+/**
+ * Node role classification — pure logic, no DB.
+ *
+ * Roles: entry, core, utility, adapter, leaf, dead
+ */
+
+export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
+
+function median(sorted) {
+  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];
+}
+
+/**
+ * Classify nodes into architectural roles based on fan-in/fan-out metrics.
+ *
+ * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean }[]} nodes
+ * @returns {Map<string, string>} nodeId → role
+ */
+export function classifyRoles(nodes) {
+  if (nodes.length === 0) return new Map();
+
+  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);
+
+  const medFanIn = median(nonZeroFanIn);
+  const medFanOut = median(nonZeroFanOut);
+
+  const result = new Map();
+
+  for (const node of nodes) {
+    const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
+    const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+
+    let role;
+    const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
+    if (isFrameworkEntry) {
+      role = 'entry';
+    } else if (node.fanIn === 0 && !node.isExported) {
+      role = 'dead';
+    } else if (node.fanIn === 0 && node.isExported) {
+      role = 'entry';
+    } else if (highIn && !highOut) {
+      role = 'core';
+    } else if (highIn && highOut) {
+      role = 'utility';
+    } else if (!highIn && highOut) {
+      role = 'adapter';
+    } else {
+      role = 'leaf';
+    }
+
+    result.set(node.id, role);
+  }
+
+  return result;
+}

package/src/graph/index.js

@@ -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.js

@@ -0,0 +1,230 @@
+/**
+ * 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.
+ */
+
+import Graph from 'graphology';
+
+export class CodeGraph {
+  /**
+   * @param {{ directed?: boolean }} [opts]
+   */
+  constructor(opts = {}) {
+    this._directed = opts.directed !== false;
+    /** @type {Map<string, object>} */
+    this._nodes = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (target → edgeAttrs) */
+    this._successors = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (source → edgeAttrs) */
+    this._predecessors = new Map();
+  }
+
+  get directed() {
+    return this._directed;
+  }
+
+  get nodeCount() {
+    return this._nodes.size;
+  }
+
+  get edgeCount() {
+    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, attrs = {}) {
+    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) {
+    return this._nodes.has(String(id));
+  }
+
+  getNodeAttrs(id) {
+    return this._nodes.get(String(id));
+  }
+
+  /** @returns {IterableIterator<[string, object]>} */
+  nodes() {
+    return this._nodes.entries();
+  }
+
+  /** @returns {string[]} */
+  nodeIds() {
+    return [...this._nodes.keys()];
+  }
+
+  // ─── Edge operations ────────────────────────────────────────────
+
+  addEdge(source, target, attrs = {}) {
+    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, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.has(src) && this._successors.get(src).has(tgt);
+  }
+
+  getEdgeAttrs(source, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.get(src)?.get(tgt);
+  }
+
+  /** @yields {[string, string, object]} source, target, attrs */
+  *edges() {
+    const seen = this._directed ? null : new Set();
+    for (const [src, targets] of this._successors) {
+      for (const [tgt, attrs] of targets) {
+        if (!this._directed) {
+          // \0 is safe as separator — node IDs are file paths/symbols, never contain null bytes
+          const key = src < tgt ? `${src}\0${tgt}` : `${tgt}\0${src}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        yield [src, tgt, attrs];
+      }
+    }
+  }
+
+  // ─── Adjacency ──────────────────────────────────────────────────
+
+  /** Direct successors of a node (outgoing edges). */
+  successors(id) {
+    const key = String(id);
+    const map = this._successors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** Direct predecessors of a node (incoming edges). */
+  predecessors(id) {
+    const key = String(id);
+    const map = this._predecessors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** All neighbors (union of successors + predecessors). */
+  neighbors(id) {
+    const key = String(id);
+    const set = new Set();
+    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) {
+    const map = this._successors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  inDegree(id) {
+    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) {
+    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) {
+    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() {
+    const result = [];
+    for (const [source, target] of this.edges()) {
+      result.push({ source, target });
+    }
+    return result;
+  }
+
+  /** Convert to graphology instance (for Louvain etc). */
+  toGraphology(opts = {}) {
+    const type = opts.type || (this._directed ? 'directed' : 'undirected');
+    const g = new Graph({ type });
+    for (const [id] of this._nodes) {
+      g.addNode(id);
+    }
+
+    for (const [src, tgt] of this.edges()) {
+      if (src === tgt) continue;
+      if (!g.hasEdge(src, tgt)) g.addEdge(src, tgt);
+    }
+    return g;
+  }
+
+  // ─── Utilities ──────────────────────────────────────────────────
+
+  clone() {
+    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) {
+    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.js

@@ -1,237 +1,66 @@
 /**
  * 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 'codegraph';
+ *   import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph';
  */
 
-// AST node queries
-export { AST_NODE_KINDS, astQuery, astQueryData } from './ast.js';
-// Audit (composite report)
+export { astQueryData } from './ast.js';
 export { auditData } from './audit.js';
-// Batch querying
-export {
-  BATCH_COMMANDS,
-  batchData,
-  multiBatchData,
-  splitTargets,
-} from './batch.js';
-// Architecture boundary rules
-export { evaluateBoundaries, PRESETS, validateBoundaryConfig } from './boundaries.js';
-// Branch comparison
-export { branchCompareData, branchCompareMermaid } from './branch-compare.js';
-// Graph building
-export { buildGraph, collectFiles, loadPathAliases, resolveImportPath } from './builder.js';
-// Control flow graph (intraprocedural)
-export {
-  buildCFGData,
-  buildFunctionCFG,
-  CFG_RULES,
-  cfgData,
-  cfgToDOT,
-  cfgToMermaid,
-} from './cfg.js';
-// Check (CI validation predicates)
+export { batchData } from './batch.js';
+export { branchCompareData } from './branch-compare.js';
+export { buildGraph } from './builder.js';
+export { cfgData } from './cfg.js';
 export { checkData } from './check.js';
-// Co-change analysis
-export {
-  analyzeCoChanges,
-  coChangeData,
-  coChangeForFiles,
-  coChangeTopData,
-  computeCoChanges,
-  scanGitHistory,
-} from './cochange.js';
-export { audit } from './commands/audit.js';
-export { batch, batchQuery } from './commands/batch.js';
-export { cfg } from './commands/cfg.js';
-export { check } from './commands/check.js';
-export { communities } from './commands/communities.js';
-export { complexity } from './commands/complexity.js';
-export { dataflow } from './commands/dataflow.js';
-export { manifesto } from './commands/manifesto.js';
-export { owners } from './commands/owners.js';
-export { sequence } from './commands/sequence.js';
-export { formatHotspots, formatModuleBoundaries, formatStructure } from './commands/structure.js';
-export { triage } from './commands/triage.js';
-// Community detection
-export { communitiesData, communitySummaryForStats } from './communities.js';
-// Complexity metrics
-export {
-  COMPLEXITY_RULES,
-  complexityData,
-  computeFunctionComplexity,
-  computeHalsteadMetrics,
-  computeLOCMetrics,
-  computeMaintainabilityIndex,
-  findFunctionNode,
-  HALSTEAD_RULES,
-  iterComplexity,
-} from './complexity.js';
-// Configuration
+export { coChangeData } from './cochange.js';
+export { communitiesData } from './communities.js';
+export { complexityData } from './complexity.js';
 export { loadConfig } from './config.js';
-// Shared constants
-export { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-// Circular dependency detection
-export { findCycles, formatCycles } from './cycles.js';
-// Dataflow analysis
-export {
-  buildDataflowEdges,
-  dataflowData,
-  dataflowImpactData,
-  dataflowPathData,
-  extractDataflow,
-} from './dataflow.js';
-// Database utilities
-export {
-  countEdges,
-  countFiles,
-  countNodes,
-  fanInJoinSQL,
-  fanOutJoinSQL,
-  findDbPath,
-  findNodesForTriage,
-  findNodesWithFanIn,
-  getBuildMeta,
-  initSchema,
-  iterateFunctionNodes,
-  kindInClause,
-  listFunctionNodes,
-  NodeQuery,
-  openDb,
-  openReadonlyOrFail,
-  setBuildMeta,
-  testFilterSQL,
-} from './db.js';
-// Embeddings
+export { EXTENSIONS, IGNORE_DIRS } from './constants.js';
+export { findCycles } from './cycles.js';
+export { dataflowData } from './dataflow.js';
 export {
   buildEmbeddings,
-  cosineSim,
-  DEFAULT_MODEL,
-  disposeModel,
-  EMBEDDING_STRATEGIES,
-  embed,
-  estimateTokens,
-  ftsSearchData,
   hybridSearchData,
-  MODELS,
   multiSearchData,
-  search,
   searchData,
-} from './embedder.js';
-// Export (DOT/Mermaid/JSON/GraphML/GraphSON/Neo4j CSV)
+} from './embeddings/index.js';
 export {
-  exportDOT,
-  exportGraphML,
-  exportGraphSON,
-  exportJSON,
-  exportMermaid,
-  exportNeo4jCSV,
-} from './export.js';
-// Execution flow tracing
-export { entryPointType, flowData, listEntryPointsData } from './flow.js';
-// Result formatting
-export { outputResult } from './infrastructure/result-formatter.js';
-// Test file detection
-export { isTestFile, TEST_PATTERN } from './infrastructure/test-filter.js';
-// Logger
-export { setVerbose } from './logger.js';
-// Manifesto rule engine
-export { manifestoData, RULE_DEFS } from './manifesto.js';
-// Native engine
-export { isNativeAvailable } from './native.js';
-// Ownership (CODEOWNERS)
-export { matchOwners, ownersData, ownersForFiles, parseCodeowners } from './owners.js';
-// Pagination utilities
-export { MCP_DEFAULTS, MCP_MAX_LIMIT, paginate, paginateResult, printNdjson } from './paginate.js';
-// Unified parser API
-export { getActiveEngine, isWasmAvailable, parseFileAuto, parseFilesAuto } from './parser.js';
-// Query functions (data-returning)
+  AnalysisError,
+  BoundaryError,
+  CodegraphError,
+  ConfigError,
+  DbError,
+  EngineError,
+  ParseError,
+  ResolutionError,
+} from './errors.js';
+export { exportDOT, exportJSON, exportMermaid } from './export.js';
+export { flowData, listEntryPointsData } from './flow.js';
+export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './kinds.js';
+export { manifestoData } from './manifesto.js';
+export { ownersData } from './owners.js';
 export {
-  ALL_SYMBOL_KINDS,
-  CORE_EDGE_KINDS,
-  CORE_SYMBOL_KINDS,
   childrenData,
   contextData,
   diffImpactData,
-  diffImpactMermaid,
-  EVERY_EDGE_KIND,
-  EVERY_SYMBOL_KIND,
-  EXTENDED_SYMBOL_KINDS,
   explainData,
   exportsData,
-  FALSE_POSITIVE_CALLER_THRESHOLD,
-  FALSE_POSITIVE_NAMES,
   fileDepsData,
   fnDepsData,
   fnImpactData,
   impactAnalysisData,
-  iterListFunctions,
-  iterRoles,
-  iterWhere,
-  kindIcon,
   moduleMapData,
-  normalizeSymbol,
   pathData,
   queryNameData,
   rolesData,
-  STRUCTURAL_EDGE_KINDS,
   statsData,
-  VALID_ROLES,
   whereData,
 } from './queries.js';
-// Query CLI display wrappers
-export {
-  children,
-  context,
-  diffImpact,
-  explain,
-  fileDeps,
-  fileExports,
-  fnDeps,
-  fnImpact,
-  impactAnalysis,
-  moduleMap,
-  queryName,
-  roles,
-  stats,
-  symbolPath,
-  where,
-} from './queries-cli.js';
-// Registry (multi-repo)
-export {
-  listRepos,
-  loadRegistry,
-  pruneRegistry,
-  REGISTRY_PATH,
-  registerRepo,
-  resolveRepoDbPath,
-  saveRegistry,
-  unregisterRepo,
-} from './registry.js';
-// Sequence diagram generation
-export { sequenceData, sequenceToMermaid } from './sequence.js';
-// Snapshot management
-export {
-  snapshotDelete,
-  snapshotList,
-  snapshotRestore,
-  snapshotSave,
-  snapshotsDir,
-  validateSnapshotName,
-} from './snapshot.js';
-// Structure analysis
-export {
-  buildStructure,
-  classifyNodeRoles,
-  FRAMEWORK_ENTRY_PREFIXES,
-  hotspotsData,
-  moduleBoundariesData,
-  structureData,
-} from './structure.js';
-// Triage — composite risk audit
+export { sequenceData } from './sequence.js';
+export { hotspotsData, moduleBoundariesData, structureData } from './structure.js';
 export { triageData } from './triage.js';
-// Interactive HTML viewer
-export { generatePlotHTML, loadPlotConfig } from './viewer.js';
-// Watch mode
-export { watchProject } from './watcher.js';