@easbot/codebase 0.3.21 → 0.3.22

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.
Files changed (48) hide show
  1. package/README.en.md +46 -0
  2. package/README.md +46 -0
  3. package/dist/chunks/{chunk-AGZFRKQ4.mjs → chunk-22NIJF4D.mjs} +12 -12
  4. package/dist/chunks/chunk-2DGOSNEH.mjs +34 -0
  5. package/dist/chunks/{chunk-BEQN3CKO.cjs → chunk-HRFLFP6O.cjs} +1 -1
  6. package/dist/chunks/{chunk-YYF5OQDS.cjs → chunk-MRPT44H3.cjs} +22 -22
  7. package/dist/chunks/{chunk-WXWENWCY.mjs → chunk-QQXDOGRV.mjs} +1 -1
  8. package/dist/chunks/chunk-R26JQOPF.mjs +47 -0
  9. package/dist/chunks/{chunk-22PKTMO5.mjs → chunk-T2ZV7FU4.mjs} +19 -19
  10. package/dist/chunks/chunk-VF3U3DPM.cjs +34 -0
  11. package/dist/chunks/{chunk-JWTI3BWI.cjs → chunk-ZCH5GLXA.cjs} +19 -19
  12. package/dist/chunks/{chunk-VFTVDTEY.cjs → chunk-ZK7YSBLG.cjs} +12 -12
  13. package/dist/chunks/cli-handler-2PSSL33N.mjs +1 -0
  14. package/dist/chunks/cli-handler-EYQH2TDL.cjs +1 -0
  15. package/dist/chunks/code-base-2ACRJ2UT.cjs +1 -0
  16. package/dist/chunks/code-base-SNQ2LWU6.mjs +1 -0
  17. package/dist/chunks/database-manager-MG7JMWGN.mjs +1 -0
  18. package/dist/chunks/database-manager-ZDJSRVBR.cjs +1 -0
  19. package/dist/chunks/file-watcher-HVST5PAC.cjs +1 -0
  20. package/dist/chunks/file-watcher-LCQ55MPE.mjs +1 -0
  21. package/dist/chunks/{interfaces-5HZADUYB.mjs → interfaces-DPFLQBQ6.mjs} +1 -1
  22. package/dist/chunks/{interfaces-ORRCH4XV.cjs → interfaces-YX56SVRQ.cjs} +1 -1
  23. package/dist/chunks/{llm-MPD7FHPM.mjs → llm-ADBGTSCV.mjs} +1 -1
  24. package/dist/chunks/{llm-JQV6XWGD.cjs → llm-BDMNIGOH.cjs} +1 -1
  25. package/dist/chunks/stdio-server-7CFU5X3T.cjs +47 -0
  26. package/dist/chunks/stdio-server-UNJPQYXA.mjs +47 -0
  27. package/dist/cli.cjs +1 -1
  28. package/dist/cli.mjs +1 -1
  29. package/dist/index.cjs +1 -1
  30. package/dist/index.d.cts +35 -3
  31. package/dist/index.d.ts +35 -3
  32. package/dist/index.mjs +1 -1
  33. package/package.json +10 -10
  34. package/dist/chunks/chunk-CSMSBVAG.mjs +0 -34
  35. package/dist/chunks/chunk-R74KIJM2.cjs +0 -34
  36. package/dist/chunks/chunk-TR3DFBJH.mjs +0 -47
  37. package/dist/chunks/cli-handler-3I5JC3HY.cjs +0 -1
  38. package/dist/chunks/cli-handler-IJ2PNNTK.mjs +0 -1
  39. package/dist/chunks/code-base-6TM7JDJ6.cjs +0 -1
  40. package/dist/chunks/code-base-BSRUQYXN.mjs +0 -1
  41. package/dist/chunks/database-manager-26PY6VTD.mjs +0 -1
  42. package/dist/chunks/database-manager-U7D7QIHC.cjs +0 -1
  43. package/dist/chunks/file-watcher-GHRFHOQF.cjs +0 -1
  44. package/dist/chunks/file-watcher-OORREWFV.mjs +0 -1
  45. package/dist/chunks/stdio-server-2GBPZY6J.cjs +0 -47
  46. package/dist/chunks/stdio-server-BZYPM34X.mjs +0 -47
  47. /package/dist/chunks/{chunk-TMICZT3L.mjs → chunk-2YMB6W5S.mjs} +0 -0
  48. /package/dist/chunks/{chunk-NVGACA7W.cjs → chunk-M2YU5LAI.cjs} +0 -0
package/README.en.md CHANGED
@@ -249,6 +249,52 @@ interface SearchOptions {
249
249
  }
250
250
  ```
251
251
 
252
+ ## Name Lookup Behavior (Decision 0087)
253
+
254
+ The 5 graph operations (`node` / `callers` / `callees` / `impact` / `context`) share a `resolveName()` function to locate nodes. This section explains its matching semantics and the recommended LLM workflow.
255
+
256
+ ### 3-tier SQL fallback (priority order)
257
+
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) |
263
+
264
+ ### Recommended LLM Workflow
265
+
266
+ ```
267
+ search → (pick name + file) → callers | callees | impact | context | node
268
+ ↑ ↓
269
+ └─────────────── explore (PRIMARY, source code + 1-level) ←──────┘
270
+ ```
271
+
272
+ **Step 1**: First call `search(query="AuthService")` to obtain `name + file_path`.
273
+
274
+ **Step 2**: Use the `name + file` returned by `search` as input to subsequent operations:
275
+
276
+ ```typescript
277
+ // ✅ Recommended: short class name + file filter (strongest disambiguation signal)
278
+ await service.callers(ctx, { name: 'AuthService', file: 'auth-service.ts' });
279
+
280
+ // ✅ Recommended: fully qualified name (with namespace + @<line>)
281
+ await service.callers(ctx, { name: 'AuthService.login@20' });
282
+
283
+ // ✅ Recommended: nodeId direct lookup (zero ambiguity)
284
+ await service.callers(ctx, { nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20' });
285
+
286
+ // ❌ Anti-pattern: short class name without file
287
+ await service.callers(ctx, { name: 'AuthService' });
288
+ // → AmbiguousError: 3 candidates (AuthService class + AuthService.login@20 + AuthService.validate@30)
289
+ ```
290
+
291
+ ### Error Handling
292
+
293
+ | Error | Trigger | Fix |
294
+ |-------|---------|-----|
295
+ | `NotFoundError` | 0 candidates | Check `name` spelling / typo / non-existent symbol |
296
+ | `AmbiguousError` | ≥2 candidates and no `file` disambiguation | Pick one `name + file` from the returned `candidates[]` list and retry |
297
+
252
298
  ## Data Model
253
299
 
254
300
  ### Node
package/README.md CHANGED
@@ -283,6 +283,52 @@ interface SearchOptions {
283
283
  }
284
284
  ```
285
285
 
286
+ ## Name Lookup 行为(决策 0087)
287
+
288
+ 5 个图操作(`node` / `callers` / `callees` / `impact` / `context`)通过共享 `resolveName()` 函数定位节点。本节说明其匹配语义与 LLM 推荐用法。
289
+
290
+ ### 3 层 SQL fallback(按优先级)
291
+
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` | 极端罕见场景(如类名拼写模糊) |
297
+
298
+ ### LLM 推荐用法(workflow)
299
+
300
+ ```
301
+ search → (pick name + file) → callers | callees | impact | context | node
302
+ ↑ ↓
303
+ └─────────────── explore (PRIMARY, source code + 1-level) ←──────┘
304
+ ```
305
+
306
+ **Step 1**:先用 `search(query="AuthService")` 拿到 `name + file_path`。
307
+
308
+ **Step 2**:以 `search` 返回的 `name + file` 作为后续操作的输入:
309
+
310
+ ```typescript
311
+ // ✅ 推荐:短类名 + file 过滤(最强消歧信号)
312
+ await service.callers(ctx, { name: 'AuthService', file: 'auth-service.ts' });
313
+
314
+ // ✅ 推荐:完全限定名(name 含 namespace + @<line>)
315
+ await service.callers(ctx, { name: 'AuthService.login@20' });
316
+
317
+ // ✅ 推荐:nodeId 直接定位(零歧义)
318
+ await service.callers(ctx, { nodeId: 'ts:src/auth-service.ts:method_definition:AuthService.login@20' });
319
+
320
+ // ❌ 反模式:短类名 + 无 file
321
+ await service.callers(ctx, { name: 'AuthService' });
322
+ // → AmbiguousError: 3 candidates (AuthService 类 + AuthService.login@20 + AuthService.validate@30)
323
+ ```
324
+
325
+ ### 错误处理
326
+
327
+ | 错误 | 触发条件 | 修复 |
328
+ |------|---------|------|
329
+ | `NotFoundError` | 0 候选 | 检查 `name` 拼写 / 拼写错误 / 不存在的符号 |
330
+ | `AmbiguousError` | ≥2 候选且无 `file` 消歧 | 从错误返回的 `candidates[]` 列表中选一个 `name + file` 重试 |
331
+
286
332
  ## 数据模型
287
333
 
288
334
  ### 节点 (Node)