nexus/wiki/concepts/SemanticCodeGraph.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
SemanticCodeGraph	concept	code-intelligence semantic-graph LSP symbol-index navigation	lsp-index-engineer.md	2026-04-29

Definition

语义代码图谱（Semantic Code Graph）是以节点（文件/模块/符号）和边（语义关系）表示代码结构统一语义抽象的数据结构。相比纯文本搜索和 AST 解析，语义图谱能够表达代码的深层语义关系（调用链、继承关系、类型层次），为代码导航、重构分析和可视化提供结构化数据基础。

Core Mechanism

Node Schema

interface GraphNode {
  id: string;        // "file:src/foo.ts" or "sym:AppController#method"
  kind: 'file' | 'module' | 'class' | 'function' | 'variable' | 'type';
  file?: string;     // Parent file path
  range?: Range;     // LSP Range for symbol location
  detail?: string;  // Type signature or brief description
}

Edge Schema

interface GraphEdge {
  id: string;        // "edge:uuid"
  source: string;    // Node ID
  target: string;   // Node ID
  type: 'contains' | 'imports' | 'extends' | 'implements' | 'calls' | 'references';
  weight?: number;  // Importance/frequency weight
}

Consistency Invariants

• 每个符号有且仅有一个定义节点
• 所有边必须引用有效节点 ID
• 文件节点必须先于其包含的符号节点存在
• Import 边必须解析到实际文件/模块节点
• Reference 边必须指向定义节点

Graph Construction Pipeline

1. 收集文件：通过 glob 扫描所有源文件
2. 创建文件节点：为每个文件创建 file: 节点
3. 提取符号：通过 LSP textDocument/documentSymbol 提取符号
4. 添加符号节点：为每个符号创建 sym: 节点
5. 添加 Contains 边：文件节点 → 符号节点
6. 解析引用：通过 LSP textDocument/references 解析引用关系
7. 添加语义边：imports / calls / references / extends / implements

Connections

• SemanticCodeGraph ← built_by ← GraphDaemon
• SemanticCodeGraph ← uses ← LSPOrchestrator
• SemanticCodeGraph ← persisted_as ← nav.index.jsonl
• SemanticCodeGraph ← indexed_via ← LSIF