gitnexus-impact-analysis

使用 GitNexus 进行影响分析

何时使用

• “修改这个函数安全吗？”
• “如果我改动 X，会破坏什么？”
• “给我看看爆炸半径”
• “谁在使用这段代码？”
• 在进行非平凡的代码改动之前
• 在提交之前 —— 以了解你的改动会影响什么

先绑定仓库

影响分析是授权编辑的闸门，因此它必须针对你即将编辑的仓库给出答案。

在第一次工具调用之前调用 list_repos {}。如果只有一个已索引的仓库，就按下面的示例原样使用。如果有多个，就在每次调用时都传入 repo：省略 repo 通常会导致报错，但在配置了默认值的 MCP 策略下，它会静默解析为该默认值。如果你无法确定指的是哪个仓库，就停下来并询问 —— 歧义身份之下的每个结果都继承这种歧义。list_repos 是分页的，因此在断定某个仓库不存在之前，要用 offset: pagination.nextOffset 翻页，直到 hasMore 为 false。

当你的改动位于 MCP 服务启动时所在工作区之外的链接工作区时，detect_changes 会接收 worktree。服务只有在从某个工作区内部启动时才会自动检测该工作区；否则 git diff 会在错误的检出中运行，并报告零个变更符号 —— 这是一种虚假的干净检查，不带有下文描述的任何降级标志。在命令行回退方案中，--repo . 表示当前检出；当你不在目标仓库中时，请改为传入预期的仓库路径。

在你的风险报告中说明绑定的身份：

Repository: <name> (<path>)   Worktree: <path>   Index: <commit>, <n> behind HEAD

工作流

0. list_repos {}                                           → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user, echoing repo/worktree/index identity

如果显示 “Index is stale” → 在终端运行 node .gitnexus/run.cjs analyze。 热工具 staleness 会指明是哪个索引作出的回答（branch/lastCommit）以及它有多新（status）。仅对 behind 或 diverged 重新分析 —— current 是同一性，unknown 是不可测量。 如果 .gitnexus/run.cjs 缺失，请在回退命令中把 node .gitnexus/run.cjs 替换为 npx gitnexus。

检查清单

- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity

理解输出

深度	风险级别	含义
d=1	WILL BREAK	直接调用方/导入方
d=2	LIKELY AFFECTED	间接依赖
d=3	MAY NEED TESTING	传递性影响

风险评估

受影响情况	风险
<5 个符号，少量流程	LOW
5-15 个符号，2-5 个流程	MEDIUM
>15 个符号或大量流程	HIGH
关键路径（认证、支付）	CRITICAL
未找到调用方	UNKNOWN

UNKNOWN 不是这一量表中的低档 —— 它意味着遍历无法给出答案。空的调用方集合既符合“确实未使用”，也符合“调用方无法被索引解析”（普通对象属性访问、动态分派、跨语言调用），因此调用方少 ⇒ LOW 并不适用。结果会带有 riskNote 说明这一点。在将该符号视为可以安全修改或删除之前，请用文本搜索加以确认。

risk 是编辑闸门：在 HIGH/CRITICAL 时警告，在 UNKNOWN 时停止，直到不确定性得到解决。在单仓库模式下，用本地 riskSharedAxes（仅 direct/total）比较 File 与符号目标。在 group 模式下，只比较 group 结果：它们的 riskSharedAxes 会在该本地值之上叠加已解析的跨仓库穿越。切勿使用这两个字段中的任何一个来豁免编辑闸门。在比较种类之前，请检查 riskScale.unusedAxes：MCP File 遍历会省略 process/module 轴，而 web Graph-RAG 会在增强之前将 File 目标展开为文件内符号。

工具

impact —— 用于符号影响范围的主要工具。如果 MCP 不可用，请改用 node .gitnexus/run.cjs impact <symbol> --direction upstream --repo .：

impact({
  target: "validateUser",
  repo: "my-app",          // required once >1 repository is indexed
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

→ d=1 (WILL BREAK):
  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]

→ d=2 (LIKELY AFFECTED):
  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]

detect_changes —— 基于 git-diff 的影响分析。如果 MCP 不可用，请改用 node .gitnexus/run.cjs detect-changes --scope all --repo .：

detect_changes({scope: "all"})

→ Changed: 5 symbols in 3 files
→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
→ Risk: MEDIUM

当索引了多个仓库时，再添加 repo；当你的改动位于一个链接工作树中，而服务并非从该工作树启动时，添加 worktree: "<abs path>"。

partial: true（图查询失败）或 truncated: true（变更符号列表被截断）意味着结果并非全部真相，读起来就像上面的 UNKNOWN：那里的零意味着未被看到，而非未受影响。请重新运行它，而不是勾选 pre-commit 检查。

错误工作树的零既不带任何标志，又与真正的干净结果在形态上完全相同，因此在将空变更集视为通过的检查之前，请确认你编辑的检出正是被 diff 的那个。

示例："What breaks if I change validateUser?"

0. list_repos {}
   → total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly

1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
   → d=1: loginHandler, apiMiddleware (WILL BREAK)
   → d=2: authRouter, sessionManager (LIKELY AFFECTED)

2. READ gitnexus://repo/my-app/processes
   → LoginFlow and TokenRefresh touch validateUser

3. Risk: 2 direct callers, 2 processes = MEDIUM
   Repository: my-app (/abs/path/my-app)  Worktree: same  Index: current

当只有一个已索引的仓库时，第 0 步返回 total: 1，且上述每次调用中的 repo 参数都会被省略。