ferdinandobons/LogicChart

# LogicChart **本地优先的静态分析工具，可将代码转换为供人类和编码 Agent 导航的决策流程图。具有确定性，支持 10 种语言，无需 API key。**  在 AI 时代，你很容易迷失对自己代码实际功能的掌控。你快速发布代码，结果却变得 不确定它是如何运行的，或者各部分是如何组合的，直到最后真的没人了解它。LogicChart 会将代码 重新转换为一张可导航的决策图谱，这样你就可以直观地查看它、对其进行推理，找出需要 修改的地方或漏洞所在。 它会读取你的源代码（绝不运行它），并将分支逻辑转换为清晰、可点击的流程图：包括 `if` / `switch` / `match` 路径、错误处理，以及将各个部分连接起来的调用。它是确定性的且完全离线的：相同的代码始终会得出相同的结果。 一个模型可以涵盖**单个函数、系统的某个部分（`backend/`、`frontend/`、 `edge/`），甚至是整个代码库**，并且你可以在它们之间自由缩放。它会以机器可读的模型、可审查的流程图和交互式查看器的形式提交到 git 中，无论是人类还是 编码 Agent 都能使用。每一项发现都标注了置信度（`VERIFIED`、`INFERRED` 或 `POTENTIAL_GAP`），因此绝不会把猜测粉饰成事实。 ## 30秒内看懂它 这个 Next.js route handler 对 `user.status` 进行了 switch 判断，但漏掉了 `UserStatus` enum 中声明的一个 case： ``` switch (user.status) { // user.status: UserStatus { ACTIVE, SUSPENDED, DELETED } case UserStatus.ACTIVE: return Response.json(user); case UserStatus.SUSPENDED: return new Response("Blocked", { status: 403 }); // no default, and DELETED is never handled } ``` `logicchart analyze` 会将这行内容写入提交的报告中，指出确切缺失的 成员，并标明它是如何知道的： ``` - **WARNING · INFERRED · enum_exhaustiveness** Declared UserStatus members not handled for user.status: UserStatus.DELETED ``` `INFERRED` 意味着这是基于声明的 enum 进行的确定性启发式判断，而不是猜测。这是在捆绑的 demo（包含 10 种语言、3 个 scope 的代码库）中**唯一**的发现。该模型在规模扩大时依然保持精确。你可以在 [`examples/demo`](examples/demo) 上自己运行试试。 ## 它的优势 在代码审查和重构时，无论是针对单个函数还是整个 repo 的任何范围： - **在代码审查前捕获缺失的 case**：没有 fallback 的 `switch` / `match` / `if` 链。 - **检查同级流程间的状态处理是否一致**：某个 route 处理了一个状态，而另一个却默默丢弃了，甚至跨越了不同文件和语言。 - **查看变更影响**：从你准备编辑的服务中可以到达哪些 entry point。 - **从单一模型中推理整个代码库或某个宏观部分**（backend、frontend 或 edge）。 - **为编码 Agent 提供确定性的控制流图谱**，这样它们就可以直接查询，而无需重新阅读文件。 ## 安装 LogicChart 尚未发布到 PyPI。你可以使用 [uv](https://docs.astral.sh/uv/) 从源码安装它： ``` git clone https://github.com/ferdinandobons/LogicChart.git logicchart cd logicchart uv tool install . # the `logicchart` command, available everywhere # uv tool install '.[mcp]' # 包含可选的 MCP 服务器 ``` 用于开发（无需全局安装即可运行）： ``` uv sync --extra dev --extra mcp uv run logicchart --help # prefix commands with `uv run` ``` ## 快速开始 进入你想要分析的项目： ``` logicchart analyze --full logicchart view ``` 不需要 `init` 步骤。LogicChart 具有实用的默认配置，除非你指定其他路径，否则它将分析当前目录（`.`）。只有在你需要自定义 root、排除项、scope、entrypoint、输出目录或 gated detector 时，才添加配置。 你会在 `logicchart-out/` 目录下获得三个文件： | 文件 | 用途 | |---|---| | `logic-flow.json` | 规范模型，由 CLI 和 MCP 使用；**请提交它** | | `logic-flow.md` | 可审查的 Mermaid 流程图 + 发现列表；**请提交它** | | `logic-flow.html` | 可导航的本地查看器（目录树 + 原地展开画布 + 源码/发现）；会自动重新生成，建议 git 忽略 | 在 Markdown 报告中，`VERIFIED` / `INFERRED` 发现位于主体部分，而 `POTENTIAL_GAP` 审查候选项被折叠在可展开的区块下（`--include-gaps` 会展开它）。无法解析的文件会被跳过并记录在报告中，绝不会导致运行中止。 ## 命令 每个命令都将项目路径作为位置参数（默认为 `.`）。以下示例 针对捆绑的 [`examples/demo`](examples/demo) 运行。 ### `analyze`：构建模型 ``` logicchart analyze examples/demo --full ``` ``` Analyzed 14 files: 25 flows, 1 finding. Incremental cache: 0 hits, 14 changed, 0 deleted. Wrote .../logic-flow.json Wrote .../logic-flow.md Wrote .../logic-flow.html ``` `--full` 会忽略增量缓存；`--no-html` 会跳过查看器；`--include-gaps` 会展开 Markdown 中仅供审查的发现项。当你需要公开示例 artifact、用于 LogicChart 自身内部结构测试的 dogfood 图谱，或者是写入到单独输出目录的全检出图谱时，请使用 `--profile demo`、`--profile self` 或 `--profile project`。 ### `update`：增量刷新 ``` logicchart update examples/demo ``` 仅重新分析内容发生变化的文件（基于内容哈希的缓存），然后重写 JSON 和 Markdown。在进行重大更改后，请提交这两个文件。 ### `query`：向模型提问 ``` logicchart query "where is suspended user status handled?" --path examples/demo ``` ``` 1. POST [route] frontend/app/api/users/route.ts:4 score=19 · `user` appears in a decision or action; `user` appears in a review finding; `status` appears in a decision or action 2. statusLabel [function] frontend/lib/status.js:3 score=13 · `suspended` appears in a decision or action; `status` matches the flow identity; `status` appears in a decision or action ``` 对与行为、状态或决策最相关的流程进行排名。添加 `--json` 可获得 机器可读的输出。查询排名使用流程标识、路径/scope/语言结构、 决策元数据和发现文本，因此 Agent 风格的问题可以超越单纯的 标签进行精准定位。使用 `--scope`、`--language` 或 `--finding-kind` 进行限制： ``` logicchart query "order status" --path examples/demo --scope backend logicchart query "enum exhaustiveness" --path examples/demo --finding-kind enum_exhaustiveness ``` ### `impact`：变更会影响什么？ ``` logicchart impact backend/users.py --path examples/demo ``` ``` Changed files: 1 Directly impacted flows: 3 Transitively impacted flows: 0 Related review findings: 0 Direct impact: - Repository.fetch (backend/users.py:9) - get_user (backend/users.py:23) - load_user (backend/users.py:32) ``` 如果没有提供文件参数，它会使用 `git diff` 来推断发生了什么变化。`--scope ` 会将 影响集限制在一个宏观部分。 ### `view`：可导航的代码库查看器 ``` logicchart view examples/demo ``` 渲染 `logic-flow.html` 并在 `http://127.0.0.1:8765/logic-flow.html` 提供服务：这是整个 代码库的可导航模型。左侧栏是目录树；中间是一个**原地展开画布** （scope 超级节点会原地展开为一个 scope 的流程，而流程会原地展开为其决策 图）；右侧栏显示所选流程的**源码**及其**逻辑 错误**。左侧栏包含流程搜索和语言过滤；错误面板包含 一个按优先级排序的审查队列。选择一个块、一行源码、一个树状文件或一个发现项 都会高亮其他相关项，并且全屏切换功能可以最大化画布。添加 `--render-only` 可在 不提供服务的情况下直接生成 HTML。  ### `validate`：检查 artifact 合约 ``` logicchart validate logicchart validate --check-sync ``` 根据捆绑的 schema 和当前的分析器注册表验证 `logic-flow.json`。 `--check-sync` 会重新分析源代码，如果提交的模型已过期，则会失败。 ### `doctor`：检查活动安装 ``` logicchart doctor ``` 检查你正在运行的 `logicchart` 命令是否能导入每一个 runtime parser 依赖。这可以捕获依赖项更改后过时的可编辑安装，并打印出适用于 当前 Python 解释器的修复命令。 ### `init` / `install` / `mcp` 这些命令是可选的。当你需要项目配置、持久的 Agent 指令或 MCP 集成时，请在首次成功分析后使用它们。 ``` logicchart init logicchart install logicchart mcp . ``` ## 整个代码库与 scope 一个模型就可以容纳整个多语言 repo。只需声明一次宏观部分，每个命令 （以及查看器）就可以被限制在其中一个部分中： ``` [logicchart.scopes] backend = ["backend/**", "services/**"] frontend = ["frontend/**", "web/**"] edge = ["edge/**", "workers/**"] ``` 如果没有 `[logicchart.scopes]` 块，顶层目录就是推断出的 scope，因此代码库 开箱即用地被划分为 backend/frontend/edge 风格的各个部分。向 `query` 和 `impact` 传递 `--scope `，并在查看器中使用 scope 和语言过滤器，即可 一次专注于一个部分或整个系统。每个流程都会记录它所属的 scope，并且 Markdown 头部 会汇总细分情况（例如 `backend (16) · edge (3) · frontend (6)`）。 ## 支持的代码 **语言：10 种支持控制流。** 控制流（函数、 方法、`if` / `else`、`switch` / `match`、异常、返回，以及连接 流程的内部调用）是从以下内容中提取的： | | | |---|---| | **Python** (`.py`) | 完整的 AST 分析器 | | **TypeScript / TSX** (`.ts`, `.tsx`) 和 **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`) | tree-sitter 分析器 | | **Go** (`.go`)、**Java** (`.java`)、**C#** (`.cs`)、**PHP** (`.php`)、**C** (`.c`, `.h`)、**Rust** (`.rs`)、**Ruby** (`.rb`) | 配置驱动的 tree-sitter 引擎 | 一种新的控制流语言只需要一个小的 *profile*（语法词汇表 + 少量提取器），而不是 一个定制分析器，因此无需 fork 流水线即可扩展覆盖范围。语言特定的 正确性得到了尊重：例如，Rust 的 `match` 在编译时是穷尽的，因此它永远不会被 标记为缺少 `default`。 **感知框架的 entry point：** - FastAPI 路由 - Next.js route handler、middleware、server action、page 和 layout - 浅层 React 组件、hook 和 event handler - 公开/导出的函数、包级函数和方法、CLI 命令和测试 **局限性（设计使然）：** LogicChart 不会运行你的代码、追踪 runtime 行为、执行 完整的符号执行，或重建深层的 React 状态。“浅层” React 意味着它会读取组件及其 hook 的结构，而不是它们在多次重新渲染时渲染的内容；请将这些 发现视为审查候选项。它映射的是每个 entry point 自身的控制流以及连接 流程的内部调用，而不是任意深度的调用链。 ## 证据级别 - `VERIFIED`：直接从语法或框架约定中提取。 - `INFERRED`：由可解释的确定性启发式方法生成。 - `POTENTIAL_GAP`：审查候选项，绝不自动视为 bug。 ## 发现类型 单流程（针对单个流程进行推理）： - `missing_branch`：基于类似状态主体的 `match` / `switch` 或 `if` / `elif` 链，没有显式 `else` / `default`。 - `dead_code`：在每个路径都已经返回或抛出异常的节点之后的代码。 - `broad_except_swallow`：默默丢弃错误的异常处理器：空主体或仅记录日志，没有重新抛出或错误返回。 - `no_op_branch`：具有空主体的显式 `if` 分支。 - `asymmetric_return`：大多数 case 都返回/抛出异常，但其中一个发生落空（可能缺少返回值）的 dispatch。 - `dead_guard`：对模块级布尔常量的真值守卫，因此某个分支永远是 dead code。 跨流程（比较同级流程）： - `inconsistent_case_handling`：大多数在相同主体和 enum/union 上分支的同级流程都处理了某个值，但此流程在没有显式 default 的情况下忽略了它。 - `enum_exhaustiveness`：某个流程对声明的 enum 进行 dispatch（处理了几个成员），但在没有显式 default 的情况下省略了其他声明的成员。 - `outcome_inconsistency`：相同的 `subject == value` 条件在这里产生了与大多数同级流程（例如抛出 410）不同的结果（例如抛出 404）。 - `logging_asymmetry`：同级流程在拒绝（抛出异常）时会进行记录/警告的守卫，在这里却被默默处理了。 - `auth_divergence`（受控，通过 `gated_detectors` 选择启用）：跳过了与其同文件伙伴执行的授权检查的 entry point。Middleware/DI 可以在无形中进行授权，因此它是一个审查候选项。 ## 配置 LogicChart 无需配置文件即可工作。只有在默认设置不够用时才运行 `logicchart init`；它会创建： ``` [logicchart] source_roots = ["."] exclude = [] include_public_functions = true max_call_depth = 4 output_dir = "logicchart-out" self_exclude = true gated_detectors = false [logicchart.entrypoints] include = [] exclude = [] # 代码库中已命名的 macro-parts（否则以顶级目录为 scope）： # [logicchart.scopes] # backend = ["backend/**", "services/**"] # frontend = ["frontend/**", "web/**"] # edge = ["edge/**", "workers/**"] ``` `gated_detectors`（默认为 `false`）启用了可选的审查层检测器，例如 `auth_divergence`，这些检测器更容易出现误报（middleware/DI 可以在无形中 进行授权），因此除非你手动开启，否则它们是关闭的。 `self_exclude`（默认为 `true`）将 LogicChart 自身安装的包（以及当你 分析其源码检出时，它的 `tests/`）排除在生成的模型之外，因此 artifact 绝不会因为工具扫描其自身内部结构受到污染。 对于不应分析的生成文件或目录，请使用 `.logicchartignore`。 内置 profile 是叠加在配置和忽略规则之上的快捷方式： | Profile | 源码 root | 输出目录 | 用途 | |---|---|---|---| | `demo` | `examples` | `logicchart-out/` | 公开演示 artifact | | `self` | `src/logicchart` | `logicchart-out/self/` | LogicChart 内部结构的 dogfood 图谱 | | `project` | `src`, `tests`, `examples` | `logicchart-out/project/` | 面向 Agent 的全检出图谱 | ## 高级：Agent 与 MCP ### Agent 指令 安装持久的指令，告诉编码 Agent 去查阅和刷新 LogicChart： ``` logicchart install logicchart install --mcp-config codex # optional: also write project-scoped MCP config ``` 这会更新受支持的项目级文件： - `AGENTS.md` (用于 Codex) - `CLAUDE.md` (用于 Claude Code) - `GEMINI.md` (用于 Gemini CLI) - `.cursor/rules/logicchart.mdc` (用于 Cursor) 使用 `--platform codex`、`claude`、`gemini` 或 `cursor` 仅安装一个目标。 当你还希望为支持它的客户端生成项目作用域内的 MCP 配置时，请使用 `--mcp-config codex`、`claude`、`cursor` 或 `all`。 ### MCP 服务器 安装可选的 MCP 依赖（从源码检出安装，因为 LogicChart 尚未发布到 PyPI）： ``` uv tool install '.[mcp]' # or, for development: uv sync --extra mcp ``` 在被分析的项目中启动 stdio 服务器： ``` logicchart mcp . ``` `logicchart install --mcp-config ...` 可以为受支持的客户端生成此配置。底层的 stdio 结构如下： ``` { "mcpServers": { "logicchart": { "command": "logicchart", "args": ["mcp", "/absolute/path/to/project"] } } } ``` 可用工具： - `logicchart_summary`：按类型/严重程度/证据划分的 flow/entrypoint 计数和发现 - `list_flows` - `get_flow` - `query_logic` - `get_findings` - `explain_finding_chain`：一项发现背后的确定性证据链 - `where_state_handled`：在域/值命名空间上分支的每个流程及其涵盖的值 - `find_decision_nodes`：对决策节点进行结构化搜索（域/主体/缺失回退） - `analyze_impact` - `review_queue`：针对当前 scope 或整个模型的优先级发现 - `context_pack`：用于 Agent 轮次的紧凑摘要 + 查询 + 影响 + 审查上下文 - `validate_artifacts` - `update_logicchart` 每个查询/列表工具都接受一个 `token_budget` 上限，以便 Agent 可以限制 单次调用返回的上下文量。 ## Roadmap 计划中的未来演进，对于早期独立维护的项目来说可能为时过早，但一旦 有团队真正开始使用 LogicChart，它们就是顺理成章的下一步： - **CI diff 门禁**：比较两个 `logic-flow.json` 快照，并在发现项 新出现时拒绝 pull request（带有用于代码扫描的 SARIF 输出）。 - **Git 自动同步 hook**：托管的 post-commit 和 post-checkout hook（加上 `logic-flow.json` 的 union merge 驱动程序），可自动保持提交模型的最新状态。 ## 开发 ``` uv run ruff check . uv run ruff format --check . uv run mypy uv run pytest --cov ``` 规范的 artifact 格式由 [schema/logic-flow.schema.json](schema/logic-flow.schema.json) 记录。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。 LogicChart 由 Ferdinando Bonsegna 创建。如果你使用、fork 或基于它进行构建， 请保持 [`NOTICE`](NOTICE) 文件完整，并附上返回此 仓库的链接以注明项目来源。

标签：AI辅助编程, JS文件枚举, SOC Prime, 云安全监控, 代码可视化, 代码理解, 可视化界面, 开发工具, 数据可视化, 日志审计, 逆向工具, 静态分析