Simvidence

Simvidence（预证）

改之前先模拟它：查看每个影响的源头、证据位置和可信度。 Simulate a change before it exists—and see every likely impact with its source, evidence location, and confidence.

中文： 代码图是一张地图；Simvidence 在地图上增加了一次“施工模拟”。真正修改代码之前，你可以先问：哪里可能受影响，为什么？每条关系都带着来源、证据位置和置信度，因此 AI 编码智能体可以回到仓库核验，而不必盲信一张黑盒图。

English: A code graph is a map; Simvidence adds a construction simulation. Before touching the code, you can ask what might be affected and why. Every relationship carries its source, evidence location, and confidence, so an AI coding agent can verify the graph against the repository instead of trusting a black box.

flowchart LR
    change["未实施改动<br/>Proposed change"] -->|"模拟 simulation · 0.35"| event["order.created"]
    producer["create_order"] -->|"AST · src/orders.py:6 · 0.82"| event
    event -->|"词法分析 lexical · src/notifications.ts · 0.72"| consumer["notifyCustomer"]

中文： Simvidence（simulate + evidence，中文名“预证”）面向在陌生或混合语言仓库中工作的 AI 编码智能体、资深开发者和架构师。它既可以作为 CLI 使用，也可以作为 Codex MCP 服务运行；索引保存在本地 SQLite 中，无需托管服务或账号。

English: Simvidence—formed from simulate and evidence—is an analysis kernel for AI coding agents, senior developers, and architects working in unfamiliar or mixed-language repositories. It runs as either a CLI or a Codex MCP server, stores its index in local SQLite, and requires no hosted service or account.

它解决什么问题 / The problem it removes

中文： 没有 Simvidence 时，回答“这个改动可能影响什么？”通常要反复做几轮人工搜索：定位符号、追踪导入和调用、搜索事件名、检查 API 或 schema 文件、对齐 Python 与 TypeScript，再把文件和行号抄给编码智能体。缺少证据的依赖结论，最后仍要人工重新发现并核对。

索引完成后，Simvidence 可以围绕事件、模块、符号、契约、需求、Git diff 或尚未实施的改动查询同一份本地证据。结果不只是“A 依赖 B”，而是一张可复核的候选影响图：关系从哪里得出、应去哪里检查、分析器有多大把握。它用于指导源码审查，并不声称找到了所有运行时路径。

English: Without Simvidence, answering “what could this change affect?” usually means repeating several manual searches: find a symbol, follow its imports and calls, search event names, inspect API or schema files, reconcile Python with TypeScript, and copy file-and-line evidence into notes for the coding agent. A dependency claim without evidence still has to be rediscovered and checked by hand.

Once indexed, Simvidence lets you query the same local evidence by event, module, symbol, contract, requirement, Git diff, or a proposed change. The result is not merely “A depends on B”; it is a reviewable candidate-impact map that explains where each relationship came from, where to inspect it, and how confident the analyzer is. It guides source review; it does not claim to find every runtime path.

它与同类工具有何不同 / How it differs from other code-graph tools

中文： Simvidence 与 codegraph、code-graph-mcp、CodeGraphContext 等项目确有共同能力。仓库索引、节点与边、依赖导航、图查询和 MCP 接入都很有用，但并非 Simvidence 独有。差异在于产品契约的组合：先建立仓库地图，再模拟尚未发生的改动，最后把可核验的证据和不确定性一起交给智能体。

English: Simvidence shares genuine common ground with projects such as codegraph, code-graph-mcp, and CodeGraphContext. Repository indexing, nodes and edges, dependency navigation, graph queries, and MCP access are useful, but none is unique to Simvidence. The distinction is the combined product contract: map the repository, simulate a change that has not happened yet, and return verifiable evidence together with uncertainty.

维度 / Area	常见能力 / Common territory	Simvidence 的侧重点 / Simvidence emphasis
Repository understanding / 仓库理解	Index files, symbols, imports, calls, and dependencies / 索引文件、符号、导入、调用和依赖	Connect APIs, events, schemas, requirements, and Git evidence across Python and JS/TS / 跨语言连接契约与 Git 证据
Change analysis / 改动分析	Query current dependencies or an existing symbol/diff / 查询现有依赖、符号或 diff	What-if analysis / 假设分析： represent an unimplemented change and return its candidate blast radius before coding / 编码前模拟未实施改动
Trust / 可核验性	Return relationships or a visualization / 返回关系或可视化	Attach source/provenance, evidence location, and confidence to every relationship / 每条关系附来源、证据位置和置信度
Primary consumer / 主要使用者	Several projects also support agents or MCP / 多个项目同样支持智能体或 MCP	Make machine-readable evidence, uncertainty, and pre-change analysis the primary contract / 以机器可读证据、不确定性和改前分析为核心契约

能做什么 / What it can do

中文： 当前版本可以：

• 构建模块、文件、符号、API、事件、schema、需求和任务的关系图。
• 追踪已索引 Python 与 JavaScript/TypeScript 代码中的依赖流、数据流和事件流。
• 把 OpenAPI、AsyncAPI、GraphQL SDL 和 Proto 描述读入契约图。
• 估算符号、契约、需求、Git diff 和假设改动的影响范围。
• 通过 CLI 和 JSON-RPC MCP 服务暴露同一套分析能力。

English: The current release can:

• Build a graph of modules, files, symbols, APIs, events, schemas, requirements, and tasks.
• Trace dependency, data, and event flows across indexed Python and JavaScript/TypeScript code.
• Read OpenAPI, AsyncAPI, GraphQL SDL, and Proto descriptions into the contract graph.
• Estimate the impact of symbols, contracts, requirements, Git diffs, and hypothetical changes.
• Expose the same analysis surface through both CLI commands and a JSON-RPC MCP server.

中文： 这是一个 MVP。Python 分析使用原生 AST；JavaScript/TypeScript 分析暂时采用保守启发式规则，后续可接入 Tree-sitter 或 TypeScript 服务增强器。

English: This is an MVP. Python analysis uses the native AST; JavaScript/TypeScript analysis intentionally uses conservative heuristics until a Tree-sitter or TypeScript-service enricher is added.

两分钟上手 / Try it in two minutes

中文： 需要 Python 3.10+ 和 Git。克隆仓库后，在当前 Python 环境中以可编辑模式安装。项目尚未发布到 PyPI。

English: Requires Python 3.10+ and Git. Clone the repository, then install it in editable mode in an active Python environment. The project is not yet published on PyPI.

macOS 与 Linux / macOS and Linux

git clone https://github.com/Osirisdynasty/Simvidence.git
cd Simvidence
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
simvidence index examples/commerce --db commerce.db
simvidence simulate-change --db commerce.db --description "change the order.created notification flow" --targets EVENT:order.created

Windows PowerShell / Windows PowerShell 环境

git clone https://github.com/Osirisdynasty/Simvidence.git
Set-Location Simvidence
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
simvidence index .\examples\commerce --db .\commerce.db
simvidence simulate-change --db .\commerce.db --description "change the order.created notification flow" --targets EVENT:order.created

中文： 最后一条命令就是假设分析。它不会改动示例源码，而是在本地图中加入一个明确标记的假设节点，将它连接到 order.created，再返回候选邻域和模拟假设。随后还可以运行 simvidence trace-event order.created --db commerce.db、simvidence project-map --db commerce.db 或 simvidence requirement-impact "notify a customer when an order is placed" --db commerce.db。真实开源仓库上的可复现结果见 Click 案例。

English: The final command is the what-if step. It does not edit the example source. Instead, it adds a clearly marked hypothetical node to the local graph, connects it to order.created, and returns the candidate neighborhood plus the assumptions behind the simulation. Next, try simvidence trace-event order.created --db commerce.db, simvidence project-map --db commerce.db, or simvidence requirement-impact "notify a customer when an order is placed" --db commerce.db. See the Click case study for a reproducible run against a real public repository.

输出示例 / What you will see

中文： 下面是内置 commerce 示例的真实索引输出；其中与机器相关的绝对 root 路径已缩短。

English: This is real indexing output from the included commerce example; the machine-specific absolute root path is shortened.

{
  "root": ".../Simvidence/examples/commerce",
  "sources": 4,
  "contracts": 5,
  "nodes": 48,
  "edges": 67
}

中文： simulate-change 会返回一条假设边，以及目标周围的真实关系。以下选摘字段直接来自输出：

English: simulate-change returns a hypothetical edge and the real relationships around its target. The selected fields below come directly from that output:

{
  "source": "MODULE:hypothetical:change the order.created notification flow",
  "target": "EVENT:order.created",
  "type": "DEPENDS_ON",
  "confidence": 0.35,
  "provenance": "simulation",
  "evidence": "change the order.created notification flow",
  "attrs": { "hypothetical": true }
}
{
  "source": "SYMBOL:src.orders.create_order",
  "target": "EVENT:order.created",
  "type": "PUBLISHES",
  "confidence": 0.82,
  "provenance": "ast",
  "evidence": "src/orders.py:6"
}
{
  "source": "SYMBOL:src.notifications.notifyCustomer",
  "target": "EVENT:order.created",
  "type": "SUBSCRIBES",
  "confidence": 0.72,
  "provenance": "lexical",
  "evidence": "src/notifications.ts"
}

中文： 完整响应还会说明："Edges are hypothetical with confidence 0.35; validate contracts and call sites before implementation." 上例统一使用 / 以便跨平台阅读；CLI 会采用当前平台的原生路径分隔符。

下图是已有的静态 evidence view（证据视图），展示追踪到的事件和证据位置；它不是假设改动模拟。

English: The full response also states: "Edges are hypothetical with confidence 0.35; validate contracts and call sites before implementation." Paths use / above for cross-platform readability; the CLI uses the platform's native path separator.

The static image below is an evidence view showing the traced event and its evidence locations. It is not a what-if simulation.

中文： 图片来自内置的 commerce 示例。create_order 在 src/orders.py:6 发布 order.created；notifyCustomer 在 src/notifications.ts 订阅它。TypeScript 边来自启发式分析，采取行动前应回看源码。

English: The image comes from the included commerce example. create_order publishes order.created at src/orders.py:6; notifyCustomer subscribes in src/notifications.ts. The TypeScript edge is heuristic, so review the source before acting on it.

与 Codex 一起使用 / Use with Codex

中文： 仓库包含 Codex 插件清单和 .mcp.json。先把 Python 包安装到 Codex 使用的 PATH 能找到 simvidence-mcp 的环境中，再从本地 marketplace 安装插件，或直接配置 MCP 服务。服务名为 simvidence。simvidence-mcp 优先读取 SIMVIDENCE_DB；未设置时，会在工作目录打开 simvidence.db。若要固定数据库路径，可运行 simvidence serve --db <path>。

该插件尚未进入公开 Codex marketplace；只克隆仓库不会自动在 Codex 中启用它。上面的 CLI 快速上手流程不依赖 Codex。运行 simvidence --help 可查看全部命令，运行 python -m unittest discover -s tests -v 可执行测试套件。

English: The repository contains a Codex plugin manifest and .mcp.json. First install the Python package in an environment where simvidence-mcp is on the PATH used by Codex, then install the plugin from a local marketplace or configure its MCP server directly. The server name is simvidence. simvidence-mcp reads SIMVIDENCE_DB when set; otherwise it opens simvidence.db in its working directory. To use a fixed database path, run simvidence serve --db <path>.

The plugin is not yet available in a public Codex marketplace; cloning the repository alone does not activate it in Codex. The CLI quick start above works independently of Codex. Run simvidence --help to list all commands and python -m unittest discover -s tests -v to execute the test suite.

工具示例 / Tool examples

中文： 以下命令共用快速上手阶段生成的 commerce.db。代码块只列一次，中英文读者执行同一组命令。

English: These commands reuse the commerce.db created during the quick start. The block appears once because both audiences run the same commands.

simvidence module-contract src.orders --db commerce.db
simvidence symbol-impact src.orders.create_order --db commerce.db
simvidence git-diff-impact --db commerce.db --repo examples/commerce --rev HEAD~1..HEAD
simvidence snapshot --db commerce.db --out before.json
simvidence index examples/commerce --db commerce.db
simvidence snapshot --db commerce.db --out after.json
simvidence graph-diff --before before.json --after after.json
simvidence verify-spec --db commerce.db --spec examples/commerce/spec.json

中文： graph-diff 直接比较两个快照，不需要 --db。verify-spec 接受 {"requirements":[{"id":"REQ-1","text":"...","must_touch":["module.name"]}]}，可独立运行：它检查每个声明的 must_touch 模块是否存在，以及索引图中是否至少有一条事实命中需求里的有效词。它不要求事先运行 requirement-impact。内置契约适配器支持 OpenAPI/AsyncAPI JSON、GraphQL SDL 和 Proto；YAML API 描述会被报告为适配器候选，除非先转换成 JSON，YAML 适配器暂未实现。

English: graph-diff compares two snapshots directly and does not require --db. verify-spec accepts {"requirements":[{"id":"REQ-1","text":"...","must_touch":["module.name"]}]} and runs independently: it checks that every declared must_touch module exists and that the indexed graph contains at least one fact matching a meaningful requirement term. It does not require a prior requirement-impact call. Built-in contract adapters support OpenAPI/AsyncAPI JSON, GraphQL SDL, and Proto. YAML API descriptions are reported as adapter candidates unless converted to JSON; a YAML adapter is not yet implemented.

已实现 / What is implemented

中文： 当前实现包括：

• SQLite 节点/边持久化，边记录证据、来源、置信度和 commit。
• Python AST 索引、依赖/调用图，以及轻量读写和事件启发式分析。
• JavaScript/TypeScript 导入、声明、调用和事件的后备词法解析器，以及可选 TypeScript 适配器接口。
• 契约适配器接口，以及 OpenAPI、AsyncAPI、GraphQL 和 Proto 的 MVP 适配器。
• 需求候选映射、假设改动、快照比较、Git diff 和共同改动增强。
• CLI、JSON-RPC MCP 服务、示例仓库和单元测试。

English: The current implementation includes:

• SQLite node/edge persistence with evidence, provenance, confidence, and commit fields on edges.
• A Python AST indexer, dependency/call graph, and lightweight read/write and event heuristics.
• A JavaScript/TypeScript fallback parser for imports, declarations, calls, and events, plus an optional TypeScript adapter seam.
• Contract adapter interfaces and MVP adapters for OpenAPI, AsyncAPI, GraphQL, and Proto.
• Requirement candidate mapping, hypothetical changes, snapshot comparison, Git diff analysis, and co-change enrichment.
• A CLI, JSON-RPC MCP server, example repository, and unit tests.

已知限制 / Known limitations

中文： JavaScript/TypeScript 对“路由宿主”与“HTTP 客户端接收者”的分类采用词法启发式规则，依赖同一文件中的接收者名称和赋值。设计原则是：面对歧义，宁可漏掉，也不要误判。因此，跨文件场景中只有直接相对导入、且明确导出了 Router 别名的情况才会被视为路由宿主。跨文件同名冲突、重命名导入、再导出链、动态构造、包别名，以及默认或命名空间导入都可能不可靠或被遗漏。精确处理需要 Tree-sitter 或 TypeScript 类型服务，目前均未实现。

English: JavaScript/TypeScript route-host versus HTTP-client receiver classification is lexical and heuristic; it depends on receiver names and assignments in the same file. The design chooses “may miss, must not misclassify” for ambiguous forms, so only direct relative named imports of an explicitly exported Router alias are treated as cross-file route hosts. Cross-file same-name collisions, renamed imports, re-export chains, dynamic construction, package aliases, and default or namespace imports are unreliable and may be missed. Precise handling requires Tree-sitter or a TypeScript type service, neither of which is implemented.

尚未实现 / Not yet implemented

中文： 以下能力仍在范围之外：

• 完整的 TypeScript 编译器或 Tree-sitter 解析、包别名解析，以及框架专用路由分析。
• 精确的过程间、控制流和污点分析；未来可接入 Joern 或 CodeQL 增强器。
• 运行时关联；未来可由 OpenTelemetry 增强器以 provenance=runtime 导入追踪数据。
• YAML 解析、语义化需求提取、鉴权感知的 API 发现，以及可视化图 UI。

更多四层模型与扩展架构见 DESIGN.md。

English: The following capabilities remain out of scope for the current release:

• Full TypeScript compiler or Tree-sitter resolution, package alias resolution, and framework-specific routing.
• Precise interprocedural, control-flow, or taint analysis; a future Joern or CodeQL enricher can provide it.
• Runtime correlation; a future OpenTelemetry enricher can ingest traces with provenance=runtime.
• YAML parsing, semantic requirement extraction, auth-aware API discovery, and a visual graph UI.

See DESIGN.md for the four-layer model and extension architecture.

许可证 / License

中文： 使用 MIT 许可证。欢迎通过 GitHub issues 和 pull requests 提交可复现的问题与贡献。

English: Licensed under MIT. Contributions and reproducible bug reports are welcome through GitHub issues and pull requests.