josecleiton/crux_analyzer

# crux_analyzer 针对 **Rust + Crux** 应用的语义分析器：将代码转化为生动的 文档。解析器（Rust，通过 `syn`）会生成一个 **中间模型**； 每个客户端——Web UI、CLI 文档生成器、VS Code 插件—— 都仅通过 JSON Schema 契约消费该模型。 **完整文档：[docs/](docs/README.md)** — 包含架构、解析器 语义、Schema 参考、CLI、Web UI、国际化、开发 指南，以及由 CLI 本身生成的[示例输出](docs/examples/mini-recorder.md)。也可在 [Português (Brasil)](docs/pt-BR/README.md) 查看。 UI 和生成的文档支持英语和巴西葡萄牙语 （`--locale en|pt-BR`，外加 Web 工具栏中的切换按钮）——参见 [docs/i18n.md](docs/i18n.md)。 ## 演示 **在线体验：[josecleiton.github.io/crux_analyzer](https://josecleiton.github.io/crux_analyzer/)** —— 以下测试用例由 CI 最新构建的分析器进行分析，并在 每次推送到 `main` 分支时发布。  该录屏中的所有内容均非手工编写。这是针对 [crates/parser/fixtures/mini_recorder/](crates/parser/fixtures/mini_recorder/) 的 Web UI， 也就是 [mini_recorder.rs](crates/parser/tests/mini_recorder.rs) 所断言的同一个测试用例 —— 因此你看到的每一个状态、转换、事件、effect 和描述， 都是解析器从该 Rust 源码中提取出来的： - 通过赋值分析发现的**两个正交区域**（`RecorderState`, `UploadState`）， 每个都渲染为独立的区块； - 选中状态的**检查器** —— 其传入/传出事件， 进入时请求的 effect（`AudioOperation::Stop`），以及测试用例本身编写的 `///` 文档； - 沿着 `Idle → Recording → Paused → Recording → Uploading → Failed → Uploading → Completed` 路径进行的**模拟**，图中会高亮显示 当前状态和最后一次转换，直到 `FINAL` 状态不再提供任何事件； - **标签过滤器**（`retryable`，一个在文档注释中声明的 `@tag`）， 未记录状态的高亮显示，以及语言环境和主题的切换按钮。 无需 Crux 应用，即可针对同一测试用例进行复现： ``` just model crates/parser/fixtures/mini_recorder "Mini Recorder" just dev ``` 或者阅读 CLI 对同一输入的处理结果，见 [docs/examples/mini-recorder.md](docs/examples/mini-recorder.md)。 ## 结构 ``` apps/web/ React + TypeScript + React Flow + ELKJS — visualization + simulation apps/vscode/ VS Code extension: the web UI in a panel, regenerating on save crates/parser/ Rust lib: walks the syn AST and extracts states/transitions/effects crates/docgen/ Rust lib: Mermaid + Markdown generators (consume only the model) crates/cli/ `crux-analyzer` binary: generate | docs, with --watch crates/i18n/ Rust lib: the shared `Locale` type + detection (no catalogs) crates/model/ Rust lib: semantic structs (Project, Core, Machine, State, ...) shared/schema/ JSON Schema contract — every client depends ONLY on this ``` UI 数据流（各层）： ``` Parser JSON → Domain Model → React Flow Model → Components ↘ Simulation Engine (pure, drives the graph via props) ``` ## 解析器能理解的内容 解析器完全不依赖 Crux —— 它对源码进行静态分析： - 核心：`impl App for X`；通过 `Event` 关联类型获取事件，并追踪 嵌套的事件枚举和导入别名；通过 `Effect` 闭包获取 effect。 - 通过赋值分析识别状态机（无需命名约定）：代码中编写的每个 `(enum, field)` 都会成为一个状态机 —— 状态图风格的 正交区域，在 UI 中渲染为独立的区块。 - 从以下来源解析状态：`matches!` 守卫、针对状态的 `match` 分支（通配符 会解析为前面分支的补集）、`==`/`!=` 比较（同样适用于 `find(|d| ...)` 闭包、`if let` 和 `let-else` 内部），以及状态枚举上的 断言方法（从其函数体中解析，包括取反操作）。 - 从直接变体赋值和 `T::default()` 结构体重置中解析目标状态 （落点位于 `#[default]` 变体上）。 - 没有状态证据的转换会从任何状态触发（在契约中为 `"*"`）； 无法解析的证据和运行时值目标会被报告为 警告，而不会被静默丢弃。 - 每次转换的 effect：每个事件分支请求的操作 （`AudioOperation::Start`，crux 的 `render()` → `Render`，...）。 - 应用已经编写的文档：状态枚举上的 `///` 会成为 状态机的描述，每个变体上的 `///` 会成为其状态的描述，其中的 `@failure` / `@deprecated` / `@tag ` 行会被读取为声明的 标记。作者编写的文字将原样保留，绝不进行翻译。 ## 运行 使用 [`just`](https://just.systems)（每一个指令详见 [Justfile](Justfile)）： ``` just model path/to/app/src MyApp # analyze a Crux app and feed the UI just dev # web app: graph sections, inspector, simulation just docs path/to/app/src MyApp # Markdown docs (or: ... mermaid) just docs path/to/app/src MyApp markdown pt-BR # ...in Portuguese just check # full validation: Rust + clippy + web ``` 原生等价命令： ``` # 分析 Crux app 并提供给 UI（添加 --watch 以获取 living docs） cargo run -p crux-analyzer-cli -- generate \ --src path/to/app/src --name MyApp --out apps/web/public/model.json # 生成文档 cargo run -p crux-analyzer-cli -- docs --src path/to/app/src # Markdown cargo run -p crux-analyzer-cli -- docs --src path/to/app/src --format mermaid # UI — 显示生成的 model，或在缺少该模型时显示打包的 fake example pnpm install pnpm dev # web app (Vite) pnpm test # mapping layers + simulation engine # Crates cargo check cargo test # parser unit + fixture + docgen tests APP_SRC=path/to/app/shared/src cargo test # + a local target-app test, if you wrote one ``` ## 模拟 选择一个状态（可选）并点击 **Simulate**：右侧面板会显示 当前状态可以触发的事件，触发它们将驱动状态机运转 —— 图中会高亮显示当前状态和所执行的最后一次转换。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。 第三方依赖保留其各自的许可证，并且每个构建产物都附带其 声明：**[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)** 是根据 每个产物实际包含的内容生成的 —— 可以使用 `just notices` 重新生成， 如果内容过期，`just check` 将会失败。 除了用于未修改的图表布局的 [elkjs](https://github.com/kieler/elkjs) 外，所有内容均为宽松许可（MIT / ISC / BSD-3-Clause / CC0 / Unicode-3.0）， 它基于 `EPL-2.0 OR GPL-3.0-or-later` 提供 —— 本项目**选择 EPL-2.0**，并将 elkjs 作为其独立的包块输出。这不会对你 使用 crux_analyzer 施加任何限制：EPL-2.0 是文件级的弱 Copyleft 许可，crux_analyzer 仅 调用 ELK 的 API。

标签：Rust, SOC Prime, 云安全监控, 代码可视化, 可视化界面, 开发工具, 文档生成, 状态机, 网络流量审计, 通知系统, 静态分析