[English](./README.en.md) | 中文

# @easbot/codebase

代码知识图谱 SDK - 基于 Property Graph 模型的代码索引与查询系统

## 特性

- **Property Graph 模型**: 使用节点和边存储代码实体及其关系
- **多语言支持**: TypeScript、JavaScript、Python、Rust、Go、C/C++、C#、Java、Scala、Ruby、PHP、Zig
- **混合搜索**: FTS 全文搜索 + 结构化查询
- **增量更新**: 基于文件内容哈希的智能增量索引
- **Tree-sitter 解析**: 高性能 AST 解析
- **统一 DB 抽象**: 通过 `@easbot/database` 的 `SyncSqliteConnection` 接入，默认 `better-sqlite3` backend，可切到 `node:sqlite` / `@tursodatabase/database`

## 数据库 Backend

`packages/codebase` 通过 `@easbot/database` 接入 SQLite，不再直接依赖 `better-sqlite3` 的裸 binding。`DatabaseManager` 内部持有 `SyncSqliteConnection`（同步 facade，对标 codegraph `SqliteDatabase`），60+ 同步 DB 调用点**零改动**。

### 默认 backend：`better-sqlite3`

`DatabaseManager` 构造时显式传 `backend: 'better-sqlite3'`，不走 `'auto'` fallback。理由：

- codebase 性能基线（index / search / sync 各项指标）基于 `better-sqlite3` 同步 binding 测量
- 自动探测在容器 / Linux / Windows 等环境下可能 fallback 到未预期的 backend，runtime 行为难以预测
- `better-sqlite3@^12.9.0` 保留为 `packages/codebase` 的物理依赖（**未**移到 `optionalDependencies`），保证安装时一定拉取对应 native binding

### Backend 切换路径

应用层可通过 `createSyncSqliteConnection({ backend: 'node-sqlite' | '@tursodatabase/database', ... })` 切换。当前 codebase `DatabaseManager` 硬编码 `'better-sqlite3'`，如需切换请修改 `packages/codebase/src/database/database-manager.ts` constructor（约 L98）。

完整 backend 抽象与性能对照见：

- [`@easbot/database` README](file:///e:/work/apps/eas/easbot/packages/database/README.md)
- 决策 [`0036-storage-backend.md`](file:///e:/work/apps/eas/easbot/docs/decisions/0036-storage-backend.md)

### `:memory:` 字面量支持

`SyncSqliteConnection.initialize` 接受 `:memory:` 字面量（SQLite 生态默认）作为内存库信号；codebase `DatabaseManager` 跳过 `Filesystem.normalize` 让字面量透传。

## CLI / MCP / Installer

`packages/codebase` **当前未暴露独立 CLI**；调用方通过 `createCodebase()` API 集成，或通过 `easbot` 主 CLI（[H-M1 阶段落地后](file:///e:/work/apps/eas/easbot/.easbot/knowledge/tasks/codebase-refactor-plan/findings.md)）以二级命令 `easbot codebase ...` 形式调用。

## 安装

```bash
pnpm add @easbot/codebase
```

## 快速开始

```typescript
import { createCodebase } from '@easbot/codebase';

// 创建图谱实例
const graph = await createCodebase({
  workspaceDir: '/path/to/your/project',
});

// 索引项目
const result = await graph.indexDirectory();
console.log(`索引完成: ${result.filesProcessed} 文件, ${result.nodesCreated} 节点`);

// 搜索代码
const results = await graph.search('UserService');
for (const r of results) {
  console.log(`${r.name} (${r.astType}) - ${r.filePath}:${r.startLine}`);
}

// 查询节点
const classes = await graph.queryNodes({ astType: 'class_declaration' });

// 查询调用图
const callGraph = await graph.queryCallGraph('ts:src/service.ts:function_declaration:UserService');

// 关闭图谱
await graph.close();
```

## API 文档

### CodeKnowledgeGraph

主类，提供完整的代码知识图谱功能。

#### 构造选项

```typescript
interface CodeKnowledgeGraphConfig {
  workspaceDir: string;           // 工作区目录
  database?: {
    path: string;                 // 数据库路径
    walMode?: boolean;            // WAL 模式
  };
  parser?: {
    languages?: Language[];       // 支持的语言
    lazyLoad?: boolean;           // 延迟加载
  };
  indexer?: {
    batchSize: number;            // 批处理大小
    ignorePatterns: string[];     // 忽略模式
    incremental: boolean;         // 增量更新
  };
}
```

#### 主要方法

| 方法 | 说明 |
|------|------|
| `initialize()` | 初始化图谱 |
| `indexFile(path)` | 索引单个文件 |
| `indexDirectory(dir?)` | 索引目录 |
| `sync()` | 增量同步 |
| `search(query, options?)` | 混合搜索 |
| `queryNodes(filter)` | 查询节点 |
| `queryEdges(filter)` | 查询边 |
| `queryNeighbors(nodeId, options?)` | 查询邻居 |
| `queryCallGraph(nodeId, depth?)` | 查询调用图 |
| `queryInheritance(nodeId)` | 查询继承关系 |
| `getStatus()` | 获取状态 |
| `healthCheck()` | 健康检查 |
| `close()` | 关闭图谱 |

### 搜索选项

```typescript
interface SearchOptions {
  maxResults?: number;            // 最大结果数
  minScore?: number;              // 最小分数
  language?: Language;            // 语言过滤
  filePath?: string;              // 文件路径过滤
  astType?: string;               // AST 类型过滤
  enableFts?: boolean;            // 启用 FTS
  ftsWeight?: number;             // FTS 权重
}
```

## 数据模型

### 节点 (Node)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 唯一标识 |
| name | string | 名称 |
| ast_type | string | AST 类型 |
| language | string | 语言 |
| file_path | string | 文件路径 |
| start_line | number | 起始行 |
| start_col | number | 起始列 |
| end_line | number | 结束行 |
| end_col | number | 结束列 |
| text | string | 代码文本 |

### 边 (Edge)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 唯一标识 |
| source | string | 源节点 ID |
| target | string | 目标节点 ID |
| relation | string | 关系类型 |

### 关系类型

| 关系 | 说明 |
|------|------|
| CONTAINS | 包含关系（类包含方法） |
| CALLS | 调用关系（函数调用） |
| INHERITS_FROM | 继承关系 |
| IMPLEMENTS | 实现接口 |
| IMPORTS | 导入模块 |
| REFERENCES | 引用关系 |

## 架构

```
src/
├── types.ts              # 类型定义
├── errors.ts             # 错误类
├── index.ts              # 入口文件
├── code-knowledge-graph.ts  # 主类
├── database/
│   └── database-manager.ts  # 数据库管理
├── parser/
│   └── parser-manager.ts    # 解析器管理
├── extractor/
│   ├── node-extractor.ts    # 节点提取
│   └── edge-extractor.ts    # 边提取
├── indexer/
│   └── indexer.ts           # 索引器
└── query/
    └── query-interface.ts   # 查询接口
```

## 开发

```bash
# 安装依赖
pnpm install

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check

# 代码检查
pnpm lint
```

## 许可证

MIT