57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
---
|
||
title: "SemanticCodeGraph"
|
||
type: concept
|
||
tags: ["code-intelligence", "semantic-graph", "LSP", "symbol-index", "navigation"]
|
||
sources: ["lsp-index-engineer.md"]
|
||
last_updated: 2026-04-29
|
||
---
|
||
|
||
## Definition
|
||
语义代码图谱（Semantic Code Graph）是以**节点**（文件/模块/符号）和**边**（语义关系）表示代码结构统一语义抽象的数据结构。相比纯文本搜索和 AST 解析，语义图谱能够表达代码的深层语义关系（调用链、继承关系、类型层次），为代码导航、重构分析和可视化提供结构化数据基础。
|
||
|
||
## Core Mechanism
|
||
|
||
### Node Schema
|
||
```typescript
|
||
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
|
||
```typescript
|
||
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]]
|