@easbot/codebase 0.3.26 → 0.3.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -4,6 +4,9 @@
4
4
 
5
5
  Code Knowledge Graph SDK - A code indexing and querying system based on the Property Graph model
6
6
 
7
+ ## Version
8
+
9
+ v0.3.28
7
10
  ## Features
8
11
 
9
12
  - **Property Graph Model**: Store code entities and their relationships using nodes and edges
@@ -154,13 +157,13 @@ $ easbot codebase doctor
154
157
 
155
158
  ### Key Fields
156
159
 
157
- | Field | Description |
158
- |-------|-------------|
159
- | `LLM.initialized` | Whether LLM is initialized (valid config + reachable) |
160
- | `LLM.capabilities` | Three capabilities: `embedding` / `graphLlm` / `rerankLlm`, each shows model name or ✗ |
161
- | `Vector enabled` | Whether vector index is enabled |
162
- | `Embedding dims` | **Probed** embedding dimension (not just from config), probed at status end and written back to meta table |
163
- | `embedding_dims_consistency` | Doctor check #9: compares meta / probe / config dimensions for consistency |
160
+ | Field | Description |
161
+ | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
162
+ | `LLM.initialized` | Whether LLM is initialized (valid config + reachable) |
163
+ | `LLM.capabilities` | Three capabilities: `embedding` / `graphLlm` / `rerankLlm`, each shows model name or ✗ |
164
+ | `Vector enabled` | Whether vector index is enabled |
165
+ | `Embedding dims` | **Probed** embedding dimension (not just from config), probed at status end and written back to meta table |
166
+ | `embedding_dims_consistency` | Doctor check #9: compares meta / probe / config dimensions for consistency |
164
167
 
165
168
  ### JSON Output (`--json`)
166
169
 
@@ -200,52 +203,52 @@ Main class providing complete code knowledge graph functionality.
200
203
 
201
204
  ```typescript
202
205
  interface CodeKnowledgeGraphConfig {
203
- workspaceDir: string; // Workspace directory
206
+ workspaceDir: string; // Workspace directory
204
207
  database?: {
205
- path: string; // Database path
206
- walMode?: boolean; // WAL mode
208
+ path: string; // Database path
209
+ walMode?: boolean; // WAL mode
207
210
  };
208
211
  parser?: {
209
- languages?: Language[]; // Supported languages
210
- lazyLoad?: boolean; // Lazy loading
212
+ languages?: Language[]; // Supported languages
213
+ lazyLoad?: boolean; // Lazy loading
211
214
  };
212
215
  indexer?: {
213
- batchSize: number; // Batch size
214
- ignorePatterns: string[]; // Ignore patterns
215
- incremental: boolean; // Incremental updates
216
+ batchSize: number; // Batch size
217
+ ignorePatterns: string[]; // Ignore patterns
218
+ incremental: boolean; // Incremental updates
216
219
  };
217
220
  }
218
221
  ```
219
222
 
220
223
  #### Main Methods
221
224
 
222
- | Method | Description |
223
- |--------|-------------|
224
- | `initialize()` | Initialize graph |
225
- | `indexFile(path)` | Index single file |
226
- | `indexDirectory(dir?)` | Index directory |
227
- | `sync()` | Incremental sync |
228
- | `search(query, options?)` | Hybrid search |
229
- | `queryNodes(filter)` | Query nodes |
230
- | `queryEdges(filter)` | Query edges |
231
- | `queryNeighbors(nodeId, options?)` | Query neighbors |
232
- | `queryCallGraph(nodeId, depth?)` | Query call graph |
233
- | `queryInheritance(nodeId)` | Query inheritance |
234
- | `getStatus()` | Get status |
235
- | `healthCheck()` | Health check |
236
- | `close()` | Close graph |
225
+ | Method | Description |
226
+ | ---------------------------------- | ----------------- |
227
+ | `initialize()` | Initialize graph |
228
+ | `indexFile(path)` | Index single file |
229
+ | `indexDirectory(dir?)` | Index directory |
230
+ | `sync()` | Incremental sync |
231
+ | `search(query, options?)` | Hybrid search |
232
+ | `queryNodes(filter)` | Query nodes |
233
+ | `queryEdges(filter)` | Query edges |
234
+ | `queryNeighbors(nodeId, options?)` | Query neighbors |
235
+ | `queryCallGraph(nodeId, depth?)` | Query call graph |
236
+ | `queryInheritance(nodeId)` | Query inheritance |
237
+ | `getStatus()` | Get status |
238
+ | `healthCheck()` | Health check |
239
+ | `close()` | Close graph |
237
240
 
238
241
  ### Search Options
239
242
 
240
243
  ```typescript
241
244
  interface SearchOptions {
242
- maxResults?: number; // Max results
243
- minScore?: number; // Min score
244
- language?: Language; // Language filter
245
- filePath?: string; // File path filter
246
- astType?: string; // AST type filter
247
- enableFts?: boolean; // Enable FTS
248
- ftsWeight?: number; // FTS weight
245
+ maxResults?: number; // Max results
246
+ minScore?: number; // Min score
247
+ language?: Language; // Language filter
248
+ filePath?: string; // File path filter
249
+ astType?: string; // AST type filter
250
+ enableFts?: boolean; // Enable FTS
251
+ ftsWeight?: number; // FTS weight
249
252
  }
250
253
  ```
251
254
 
@@ -255,11 +258,11 @@ The 5 graph operations (`node` / `callers` / `callees` / `impact` / `context`) s
255
258
 
256
259
  ### 3-tier SQL fallback (priority order)
257
260
 
258
- | Tier | Match Mode | SQL Condition | Use Case |
259
- |------|-----------|---------------|----------|
260
- | 1. **exact** | `name` field equality | `WHERE name = ?` | Short class names / namespaces / fully qualified names (with `@<line>`) |
261
- | 2. **qualified** | `name` contains target string (fallback) | `WHERE name LIKE %?%` | Short method names / class name prefix mismatch |
262
- | 3. **substring** | When tier 1-2 return 0 + `file`/`kind` filter | `WHERE name LIKE %?% AND file_path/kind` | Extreme edge cases (e.g., typo in class name) |
261
+ | Tier | Match Mode | SQL Condition | Use Case |
262
+ | ---------------- | --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------- |
263
+ | 1. **exact** | `name` field equality | `WHERE name = ?` | Short class names / namespaces / fully qualified names (with `@<line>`) |
264
+ | 2. **qualified** | `name` contains target string (fallback) | `WHERE name LIKE %?%` | Short method names / class name prefix mismatch |
265
+ | 3. **substring** | When tier 1-2 return 0 + `file`/`kind` filter | `WHERE name LIKE %?% AND file_path/kind` | Extreme edge cases (e.g., typo in class name) |
263
266
 
264
267
  ### Recommended LLM Workflow
265
268
 
@@ -281,7 +284,9 @@ await service.callers(ctx, { name: 'AuthService', file: 'auth-service.ts' });
281
284
  await service.callers(ctx, { name: 'AuthService.login@20' });
282
285
 
283
286
  // ✅ Recommended: nodeId direct lookup (zero ambiguity)
284
- await service.callers(ctx, { nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20' });
287
+ await service.callers(ctx, {
288
+ nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20',
289
+ });
285
290
 
286
291
  // ❌ Anti-pattern: short class name without file
287
292
  await service.callers(ctx, { name: 'AuthService' });
@@ -290,47 +295,47 @@ await service.callers(ctx, { name: 'AuthService' });
290
295
 
291
296
  ### Error Handling
292
297
 
293
- | Error | Trigger | Fix |
294
- |-------|---------|-----|
295
- | `NotFoundError` | 0 candidates | Check `name` spelling / typo / non-existent symbol |
298
+ | Error | Trigger | Fix |
299
+ | ---------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
300
+ | `NotFoundError` | 0 candidates | Check `name` spelling / typo / non-existent symbol |
296
301
  | `AmbiguousError` | ≥2 candidates and no `file` disambiguation | Pick one `name + file` from the returned `candidates[]` list and retry |
297
302
 
298
303
  ## Data Model
299
304
 
300
305
  ### Node
301
306
 
302
- | Field | Type | Description |
303
- |-------|------|-------------|
304
- | id | string | Unique identifier |
305
- | name | string | Name |
306
- | ast_type | string | AST type |
307
- | language | string | Language |
308
- | file_path | string | File path |
309
- | start_line | number | Start line |
310
- | start_col | number | Start column |
311
- | end_line | number | End line |
312
- | end_col | number | End column |
313
- | text | string | Code text |
307
+ | Field | Type | Description |
308
+ | ---------- | ------ | ----------------- |
309
+ | id | string | Unique identifier |
310
+ | name | string | Name |
311
+ | ast_type | string | AST type |
312
+ | language | string | Language |
313
+ | file_path | string | File path |
314
+ | start_line | number | Start line |
315
+ | start_col | number | Start column |
316
+ | end_line | number | End line |
317
+ | end_col | number | End column |
318
+ | text | string | Code text |
314
319
 
315
320
  ### Edge
316
321
 
317
- | Field | Type | Description |
318
- |-------|------|-------------|
319
- | id | string | Unique identifier |
320
- | source | string | Source node ID |
321
- | target | string | Target node ID |
322
- | relation | string | Relation type |
322
+ | Field | Type | Description |
323
+ | -------- | ------ | ----------------- |
324
+ | id | string | Unique identifier |
325
+ | source | string | Source node ID |
326
+ | target | string | Target node ID |
327
+ | relation | string | Relation type |
323
328
 
324
329
  ### Relation Types
325
330
 
326
- | Relation | Description |
327
- |----------|-------------|
328
- | CONTAINS | Parent-child AST relationship |
329
- | CALLS | Function call relationship |
330
- | INHERITS_FROM | Class inheritance |
331
- | IMPLEMENTS | Interface implementation |
332
- | IMPORTS | Module import |
333
- | REFERENCES | Variable/identifier reference |
331
+ | Relation | Description |
332
+ | ------------- | ----------------------------- |
333
+ | CONTAINS | Parent-child AST relationship |
334
+ | CALLS | Function call relationship |
335
+ | INHERITS_FROM | Class inheritance |
336
+ | IMPLEMENTS | Interface implementation |
337
+ | IMPORTS | Module import |
338
+ | REFERENCES | Variable/identifier reference |
334
339
 
335
340
  ## Architecture
336
341
 
package/README.md CHANGED
@@ -4,6 +4,9 @@
4
4
 
5
5
  代码知识图谱 SDK - 基于 Property Graph 模型的代码索引与查询系统
6
6
 
7
+ ## 版本
8
+
9
+ v0.3.28
7
10
  ## 特性
8
11
 
9
12
  - **Property Graph 模型**: 使用节点和边存储代码实体及其关系
@@ -152,13 +155,13 @@ $ easbot codebase doctor
152
155
 
153
156
  ### 关键字段说明
154
157
 
155
- | 字段 | 说明 |
156
- |------|------|
157
- | `LLM.initialized` | LLM 是否已初始化(配置有效且可达) |
158
- | `LLM.capabilities` | 三大能力:`embedding` / `graphLlm` / `rerankLlm`,各显示模型名或 ✗ |
159
- | `Vector enabled` | 向量索引是否启用 |
160
- | `Embedding dims` | **实测** embedding 维度(非仅读 config),status 末尾探测并回填 meta 表 |
161
- | `embedding_dims_consistency` | doctor 第 9 项检查:对比 meta / probe / config 三方维度是否一致 |
158
+ | 字段 | 说明 |
159
+ | ---------------------------- | ----------------------------------------------------------------------- |
160
+ | `LLM.initialized` | LLM 是否已初始化(配置有效且可达) |
161
+ | `LLM.capabilities` | 三大能力:`embedding` / `graphLlm` / `rerankLlm`,各显示模型名或 ✗ |
162
+ | `Vector enabled` | 向量索引是否启用 |
163
+ | `Embedding dims` | **实测** embedding 维度(非仅读 config),status 末尾探测并回填 meta 表 |
164
+ | `embedding_dims_consistency` | doctor 第 9 项检查:对比 meta / probe / config 三方维度是否一致 |
162
165
 
163
166
  ### JSON 输出(`--json`)
164
167
 
@@ -234,52 +237,52 @@ await graph.close();
234
237
 
235
238
  ```typescript
236
239
  interface CodeKnowledgeGraphConfig {
237
- workspaceDir: string; // 工作区目录
240
+ workspaceDir: string; // 工作区目录
238
241
  database?: {
239
- path: string; // 数据库路径
240
- walMode?: boolean; // WAL 模式
242
+ path: string; // 数据库路径
243
+ walMode?: boolean; // WAL 模式
241
244
  };
242
245
  parser?: {
243
- languages?: Language[]; // 支持的语言
244
- lazyLoad?: boolean; // 延迟加载
246
+ languages?: Language[]; // 支持的语言
247
+ lazyLoad?: boolean; // 延迟加载
245
248
  };
246
249
  indexer?: {
247
- batchSize: number; // 批处理大小
248
- ignorePatterns: string[]; // 忽略模式
249
- incremental: boolean; // 增量更新
250
+ batchSize: number; // 批处理大小
251
+ ignorePatterns: string[]; // 忽略模式
252
+ incremental: boolean; // 增量更新
250
253
  };
251
254
  }
252
255
  ```
253
256
 
254
257
  #### 主要方法
255
258
 
256
- | 方法 | 说明 |
257
- |------|------|
258
- | `initialize()` | 初始化图谱 |
259
- | `indexFile(path)` | 索引单个文件 |
260
- | `indexDirectory(dir?)` | 索引目录 |
261
- | `sync()` | 增量同步 |
262
- | `search(query, options?)` | 混合搜索 |
263
- | `queryNodes(filter)` | 查询节点 |
264
- | `queryEdges(filter)` | 查询边 |
265
- | `queryNeighbors(nodeId, options?)` | 查询邻居 |
266
- | `queryCallGraph(nodeId, depth?)` | 查询调用图 |
267
- | `queryInheritance(nodeId)` | 查询继承关系 |
268
- | `getStatus()` | 获取状态 |
269
- | `healthCheck()` | 健康检查 |
270
- | `close()` | 关闭图谱 |
259
+ | 方法 | 说明 |
260
+ | ---------------------------------- | ------------ |
261
+ | `initialize()` | 初始化图谱 |
262
+ | `indexFile(path)` | 索引单个文件 |
263
+ | `indexDirectory(dir?)` | 索引目录 |
264
+ | `sync()` | 增量同步 |
265
+ | `search(query, options?)` | 混合搜索 |
266
+ | `queryNodes(filter)` | 查询节点 |
267
+ | `queryEdges(filter)` | 查询边 |
268
+ | `queryNeighbors(nodeId, options?)` | 查询邻居 |
269
+ | `queryCallGraph(nodeId, depth?)` | 查询调用图 |
270
+ | `queryInheritance(nodeId)` | 查询继承关系 |
271
+ | `getStatus()` | 获取状态 |
272
+ | `healthCheck()` | 健康检查 |
273
+ | `close()` | 关闭图谱 |
271
274
 
272
275
  ### 搜索选项
273
276
 
274
277
  ```typescript
275
278
  interface SearchOptions {
276
- maxResults?: number; // 最大结果数
277
- minScore?: number; // 最小分数
278
- language?: Language; // 语言过滤
279
- filePath?: string; // 文件路径过滤
280
- astType?: string; // AST 类型过滤
281
- enableFts?: boolean; // 启用 FTS
282
- ftsWeight?: number; // FTS 权重
279
+ maxResults?: number; // 最大结果数
280
+ minScore?: number; // 最小分数
281
+ language?: Language; // 语言过滤
282
+ filePath?: string; // 文件路径过滤
283
+ astType?: string; // AST 类型过滤
284
+ enableFts?: boolean; // 启用 FTS
285
+ ftsWeight?: number; // FTS 权重
283
286
  }
284
287
  ```
285
288
 
@@ -289,11 +292,11 @@ interface SearchOptions {
289
292
 
290
293
  ### 3 层 SQL fallback(按优先级)
291
294
 
292
- | 层级 | 匹配模式 | SQL 条件 | 适用场景 |
293
- |------|---------|---------|---------|
294
- | 1. **exact** | `name` 字段全等 | `WHERE name = ?` | 短类名 / namespace / 完全限定名(含 `@<line>`) |
295
- | 2. **qualified** | `name` 含目标字符串(兜底) | `WHERE name LIKE %?%` | 短方法名 / 类名前缀不匹配 |
296
- | 3. **substring** | 前两层全空 + `file`/`kind` 过滤 | `WHERE name LIKE %?% AND file_path/kind` | 极端罕见场景(如类名拼写模糊) |
295
+ | 层级 | 匹配模式 | SQL 条件 | 适用场景 |
296
+ | ---------------- | ------------------------------- | ---------------------------------------- | ----------------------------------------------- |
297
+ | 1. **exact** | `name` 字段全等 | `WHERE name = ?` | 短类名 / namespace / 完全限定名(含 `@<line>`) |
298
+ | 2. **qualified** | `name` 含目标字符串(兜底) | `WHERE name LIKE %?%` | 短方法名 / 类名前缀不匹配 |
299
+ | 3. **substring** | 前两层全空 + `file`/`kind` 过滤 | `WHERE name LIKE %?% AND file_path/kind` | 极端罕见场景(如类名拼写模糊) |
297
300
 
298
301
  ### LLM 推荐用法(workflow)
299
302
 
@@ -315,7 +318,9 @@ await service.callers(ctx, { name: 'AuthService', file: 'auth-service.ts' });
315
318
  await service.callers(ctx, { name: 'AuthService.login@20' });
316
319
 
317
320
  // ✅ 推荐:nodeId 直接定位(零歧义)
318
- await service.callers(ctx, { nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20' });
321
+ await service.callers(ctx, {
322
+ nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20',
323
+ });
319
324
 
320
325
  // ❌ 反模式:短类名 + 无 file
321
326
  await service.callers(ctx, { name: 'AuthService' });
@@ -324,47 +329,47 @@ await service.callers(ctx, { name: 'AuthService' });
324
329
 
325
330
  ### 错误处理
326
331
 
327
- | 错误 | 触发条件 | 修复 |
328
- |------|---------|------|
329
- | `NotFoundError` | 0 候选 | 检查 `name` 拼写 / 拼写错误 / 不存在的符号 |
332
+ | 错误 | 触发条件 | 修复 |
333
+ | ---------------- | ----------------------- | ----------------------------------------------------------- |
334
+ | `NotFoundError` | 0 候选 | 检查 `name` 拼写 / 拼写错误 / 不存在的符号 |
330
335
  | `AmbiguousError` | ≥2 候选且无 `file` 消歧 | 从错误返回的 `candidates[]` 列表中选一个 `name + file` 重试 |
331
336
 
332
337
  ## 数据模型
333
338
 
334
339
  ### 节点 (Node)
335
340
 
336
- | 字段 | 类型 | 说明 |
337
- |------|------|------|
338
- | id | string | 唯一标识 |
339
- | name | string | 名称 |
340
- | ast_type | string | AST 类型 |
341
- | language | string | 语言 |
342
- | file_path | string | 文件路径 |
343
- | start_line | number | 起始行 |
344
- | start_col | number | 起始列 |
345
- | end_line | number | 结束行 |
346
- | end_col | number | 结束列 |
347
- | text | string | 代码文本 |
341
+ | 字段 | 类型 | 说明 |
342
+ | ---------- | ------ | -------- |
343
+ | id | string | 唯一标识 |
344
+ | name | string | 名称 |
345
+ | ast_type | string | AST 类型 |
346
+ | language | string | 语言 |
347
+ | file_path | string | 文件路径 |
348
+ | start_line | number | 起始行 |
349
+ | start_col | number | 起始列 |
350
+ | end_line | number | 结束行 |
351
+ | end_col | number | 结束列 |
352
+ | text | string | 代码文本 |
348
353
 
349
354
  ### 边 (Edge)
350
355
 
351
- | 字段 | 类型 | 说明 |
352
- |------|------|------|
353
- | id | string | 唯一标识 |
354
- | source | string | 源节点 ID |
355
- | target | string | 目标节点 ID |
356
- | relation | string | 关系类型 |
356
+ | 字段 | 类型 | 说明 |
357
+ | -------- | ------ | ----------- |
358
+ | id | string | 唯一标识 |
359
+ | source | string | 源节点 ID |
360
+ | target | string | 目标节点 ID |
361
+ | relation | string | 关系类型 |
357
362
 
358
363
  ### 关系类型
359
364
 
360
- | 关系 | 说明 |
361
- |------|------|
362
- | CONTAINS | 包含关系(类包含方法) |
363
- | CALLS | 调用关系(函数调用) |
364
- | INHERITS_FROM | 继承关系 |
365
- | IMPLEMENTS | 实现接口 |
366
- | IMPORTS | 导入模块 |
367
- | REFERENCES | 引用关系 |
365
+ | 关系 | 说明 |
366
+ | ------------- | ---------------------- |
367
+ | CONTAINS | 包含关系(类包含方法) |
368
+ | CALLS | 调用关系(函数调用) |
369
+ | INHERITS_FROM | 继承关系 |
370
+ | IMPLEMENTS | 实现接口 |
371
+ | IMPORTS | 导入模块 |
372
+ | REFERENCES | 引用关系 |
368
373
 
369
374
  ## 架构
370
375