@jokeran/frontend-code-skimmer 0.4.0 → 0.4.2

package/README.md

@@ -2,7 +2,14 @@
 
 > 不读全文，只看骨架；不搜字符，搜语义关联。
 
-AI 代码助手的智能代码索引引擎，支持 **Vue 2 / Vue 3 / React Hooks**。
+AI 代码助手的智能代码索引引擎，面向 **Vue 2 / Vue 3 / React / 纯 TS/JS 工具模块** 的结构化检索与影响分析场景。
+
+当前版本的能力重点：
+
+- 支持 Vue 2、Vue 3、React 组件/模块索引
+- `precision_mode="precise"` 支持 **JS / JSX / TS / TSX** 的跨文件 import/export 精确绑定
+- 对 **纯 TS/JS 工具类模块** 提供基础符号提取（class / method / function / constant）
+- `skimmer_index_health` 可显示**真实失败文件与错误信息**，便于排障
 
 ## 解决什么问题？
 
@@ -13,6 +20,9 @@ AI 代码助手的智能代码索引引擎，支持 **Vue 2 / Vue 3 / React Hook
 - **修改前评估影响**：`skimmer_get_blast_radius` 告诉你改一个函数会影响哪些地方
 - **变量数据流追踪**：`skimmer_trace_data_lifecycle` 一次调用聚合声明、属性修改、参数传递、Storage 落点 4 个维度
 - **索引过期行号偏移**：`skimmer_get_component_outline` 和 `skimmer_get_code_slice` 会自动检测索引是否过期并给出警告
+- **纯 TS/JS 工具类模块也能审**：支持提取 class、method、top-level function、const，适合 parser / indexer / cache / CLI / MCP 工具模块
+- **跨文件 import 关系误判少**：precise 模式会识别本地 shadowing，import 名在局部作用域被参数/变量遮蔽时不会误标为精确边
+- **索引坏了怎么查**：`skimmer_index_health` 可直接看到失败文件数量、最近失败文件和错误摘要
 
 ## 12 个 MCP 工具
 
@@ -28,9 +38,17 @@ AI 代码助手的智能代码索引引擎，支持 **Vue 2 / Vue 3 / React Hook
 | `skimmer_trace_data_lifecycle`   | ⭐ 变量完整生命周期追踪（首选，一键聚合 5 维度） |
 | `skimmer_get_call_graph`         | 函数调用关系图谱（支持 callers / callees / both） |
 | `skimmer_get_blast_radius`       | 修改影响范围评估                             |
-| `skimmer_index_health`           | 索引健康检查（索引文件数、符号数、watcher 状态、DB 大小） |
+| `skimmer_index_health`           | 索引健康检查（索引文件/符号/关系/行为、失败文件、watcher、DB 大小） |
 | `skimmer_get_project_overview`   | 项目整体概览（文件数、符号数、框架分布）     |
 
+## 最近增强 / 稳定性说明
+
+- **JSX precise 生效**：precise 模式不再局限于 `ts/tsx`，现在会对 `js/jsx/ts/tsx` 模块做跨文件 import/export 绑定增强
+- **re-export / barrel 链扩散更完整**：`selective_precise=true` 会把 `re-export` 也纳入依赖签名和反向依赖扩散，barrel 变更不再只重算当前文件
+- **local shadowing 保护**：若 import 名在函数局部被参数或变量重新声明，会保留 heuristic，避免把本地变量误判成跨文件精确调用
+- **工具类模块覆盖增强**：新增 Tooling TS/JS Parser，能抽取 class、class method、top-level function、constant 等基础符号
+- **index health 更真实**：索引失败文件会持久化，`skimmer_index_health` 可查看最近失败文件和错误，而不是只看总量
+
 ## 安装
 
 ### 方式一：npx 直接使用（推荐）
@@ -136,14 +154,14 @@ npm run build
 
 ## 环境变量（全部可选）
 
-| 变量                       | 说明                                        | 默认值  |
-| -------------------------- | ------------------------------------------- | ------- |
-| `SKIMMER_PROJECT`          | 全局默认项目路径                            | 无      |
-| `SKIMMER_AUTO_INDEX`       | 启动时自动索引默认项目（需配合上一项使用）  | `false` |
-| `SKIMMER_DB`               | 自定义数据库路径（仅单项目场景有效）        | 自动    |
-| `SKIMMER_MAX_OPEN_PROJECTS`| 最大同时打开的项目数（LRU 淘汰）           | `8`     |
-| `SKIMMER_DB_IDLE_MINUTES`  | 项目空闲多久后自动关闭数据库连接（分钟）    | `30`    |
-| `SKIMMER_DB_TTL_DAYS`      | 全局缓存数据库的 TTL（天），过期自动清理     | `14`    |
+| 变量                        | 说明                                       | 默认值  |
+| --------------------------- | ------------------------------------------ | ------- |
+| `SKIMMER_PROJECT`           | 全局默认项目路径                           | 无      |
+| `SKIMMER_AUTO_INDEX`        | 启动时自动索引默认项目（需配合上一项使用） | `false` |
+| `SKIMMER_DB`                | 自定义数据库路径（仅单项目场景有效）       | 自动    |
+| `SKIMMER_MAX_OPEN_PROJECTS` | 最大同时打开的项目数（LRU 淘汰）           | `8`     |
+| `SKIMMER_DB_IDLE_MINUTES`   | 项目空闲多久后自动关闭数据库连接（分钟）   | `30`    |
+| `SKIMMER_DB_TTL_DAYS`       | 全局缓存数据库的 TTL（天），过期自动清理   | `14`    |
 
 ## 使用示例
 
@@ -212,23 +230,83 @@ skimmer_get_call_graph({ symbol_name: "saveToCache", direction: "both" })
 skimmer_get_blast_radius({ symbol_name: "saveToCache" })
 ```
 
-### 8. 索引行号不准怎么办？
+### 8. 精度模式（precise）
+
+`precision_mode="precise"` 用于增强跨文件 import/export 绑定。
+
+前提与边界：
+
+- 需要项目根目录存在 `tsconfig.json`，否则会自动降级到 `heuristic`
+- 当前精确绑定覆盖 **JS / JSX / TS / TSX** 文件
+- 适合查 `import { foo } from './bar'` 这类跨文件调用，不等于完整类型系统求值
+- 若 import 名在局部作用域被参数/变量遮蔽，会保留 heuristic，避免误判
+
+示例：
+
+```js
+skimmer_index_project({
+  project_path: "/work/project-a",
+  precision_mode: "precise"
+})
+```
+
+### 9. 选择性 precise 重算（大项目推荐）
+
+`selective_precise=true` 会在索引后只重算**变更文件 + 受影响文件**，降低 precise 全量成本。
+
+当前规则：
+
+- `body_only`：只重算当前文件 precise
+- `import_changed`：只重算当前文件
+- `export_changed` / `full_changed`：重算当前文件 + 所有直接/间接依赖它的文件
+- `re-export` / barrel 链会纳入 import 签名与反向依赖扩散
+
+示例：
+
+```js
+skimmer_index_project({
+  project_path: "/work/project-a",
+  precision_mode: "precise",
+  selective_precise: true,
+  max_precise_files: 20
+})
+```
+
+### 10. 索引行号不准怎么办？
 
-行号偏移的根本原因是索引未及时更新。排查步骤：
+行号偏移的根本原因通常是索引未及时更新。排查步骤：
 
-1. `skimmer_get_component_outline` 返回 `⚠️ [索引已过期]` → 立即执行第 2 步
+1. `skimmer_get_component_outline` 返回 `⚠️ [索引已过期]` → 立即执行第 3 步
 2. `skimmer_get_code_slice` 返回 `⚠️ [行号偏移]` → 说明代码切片位置不对
 3. 强制重建：`skimmer_index_project({ project_path: "...", force: true })`
 
-> v0.2.7 起：增量索引同时校验 **mtime + 文件大小**，解决部分编辑器不更新 mtime 导致的漏检问题。
+> 当前增量索引使用 **mtime + 文件大小** 做快速跳过，能覆盖大多数变更场景；如果你的编辑器或同步工具存在极端时间戳行为，仍建议在异常时执行 `force: true` 全量重建。
+
+### 11. 索引坏了怎么排障？
+
+```js
+skimmer_index_health({ project_path: "/work/project-a" })
+```
+
+可直接看到：
+
+- 已索引文件数 / 符号数 / 关系数 / 行为数
+- 最后索引时间
+- 失败文件数量
+- 最近失败文件和错误信息
+- watcher 是否活跃
+- 数据库大小与路径
+
+当你发现“文件明明在，但工具查不到”时，先看这里，而不是只看总文件数。
 
 ## 框架支持
 
-| 框架  | SFC 分离                 | AST 解析             | 支持的模式                          |
-| ----- | ------------------------ | -------------------- | ----------------------------------- |
-| Vue 2 | `vue-template-compiler`  | `@babel/parser`      | Options API                         |
-| Vue 3 | `@vue/compiler-sfc`      | `@babel/parser`      | `<script setup>` + Composition API  |
-| React | —                        | `@babel/parser` + JSX| 函数组件 + Hooks                    |
+| 类型 | 解析方式 | 支持范围 | 说明 |
+| ---- | -------- | -------- | ---- |
+| Vue 2 | `vue-template-compiler` + `@babel/parser` | Options API | 适合 SFC 组件骨架、行为标签、调用关系 |
+| Vue 3 | `@vue/compiler-sfc` + `@babel/parser` | `<script setup>` + Composition API | 适合现代 Vue 单文件组件分析 |
+| React | `@babel/parser` + JSX | 函数组件 + Hooks | 适合组件骨架、事件入口、行为标签、调用关系 |
+| 纯 TS/JS 工具模块 | `@babel/parser` | class / method / top-level function / constant | 基础结构化符号提取，适合 parser / indexer / cache / CLI / MCP / util，不等于完整框架语义分析 |
 
 ## 行为检测