eezz4/zzop

# zzop ( Zero Zone Of Pain ) [](https://github.com/eezz4/zzop/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@zzop/cli) [](./LICENSE) 一个多语言 SAST / 架构分析引擎，使用 Rust 编写。它将源代码树解析为 语言中立的 IR，在其上运行分层规则系统（原生全图分析 + 声明式 JSON 规则 包），并以 JSON 文档的形式返回结构发现、依赖/死代码分析以及健康评分。 - 文档网站：（源码位于 [`site/`](site/)） - 仓库内文档：[`docs/README.md`](docs/README.md) - 外部解析器协议：[`docs/NORMALIZED_AST.md`](docs/NORMALIZED_AST.md) ## 快速开始 以 CLI 方式运行 zzop —— 编写一个 `zzop.config.jsonc`，运行 `npx zzop`，ESLint 风格。`@zzop/cli` 包 依赖于 `@zzop/native`，后者会自动安装合适的预编译平台二进制文件（无需 编译）。需要 Node.js >= 18。 ``` npm i -D @zzop/cli # add to your project (or one-off: npx @zzop/cli) npx zzop init # writes an annotated zzop.config.jsonc npx zzop # analyzes using that config and prints a report ``` `@zzop/cli` 和 `@zzop/native` 已发布至 npm；每个带有标签的版本都会驱动对应的发布版本。完整 CLI 及配置参考请参阅 [`packages/cli/README.md`](packages/cli/README.md)。 若要嵌入引擎而不是运行 CLI，请直接依赖 `@zzop/native` 并以 JSON 输入 / JSON 输出的方式调用： ``` import zzop from '@zzop/native'; const report = JSON.parse(zzop.analyze(JSON.stringify({ root: '.' }))); ``` ### 结果（节选） 每个发现都包含规则 ID、严重程度以及 `file:line` 位置，例如： ``` { "findings": [ { "ruleId": "sql/nplus1", "severity": "warning", "file": "src/routes/orders.ts", "line": 42, "message": "Query inside a loop — likely N+1. Batch with a single IN (...) query or a join." } ], "scores": { /* structural subscores, 0-100 */ }, "health": { "pain": 12.4, "contributors": [ /* metrics driving the pain score, highest first */ ] }, "recommendations": [ /* refactor-first candidates, ROI-ordered */ ], "warnings": [ /* anything this run could not provide */ ] } ``` `analyzeTrees`（多树）还会额外返回 `crossLayerFindings` —— 即前端 fetch <-> 后端 路由的关联 —— 这在单树模式中没有对应的实现。 ## 支持的语言 | 语言 | 支持 | |---|---| | TypeScript / JavaScript (`.ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts`) | 原生，全面支持：symbols, imports, calls, HTTP routes/egress | | Prisma schema (`.prisma`) | 原生支持：schema models/fields（结构化 + 感知使用的 schema 规则） | | Java (`.java`) | 原生，词法级别：仅限 method/class body spans，足以支持 `method-scan` 规则 | | 其他任何语言（Python, JSP, ...） | 树内词法回退（仅限行数统计 + `line-scan` 规则），或通过符合 [Normalized AST 协议](docs/NORMALIZED_AST.md) 的外部解析器适配器提供一等支持 | ## 版本控制与稳定性 zzop 处于 **1.0 之前阶段（`0.x`）且不稳定** —— 任何版本都可能在未经通知的情况下更改行为、输出、规则或 默认设置，因此请锁定确切版本（`@zzop/cli@0.6.0`，而不是 `^0.6.0`）并在升级前 重新测试。语义化版本控制和维护的更新日志将从 `1.0.0` 开始。完整政策： [VERSIONING.md](VERSIONING.md)。 ## 布局 - `packages/core` — 引擎库：通用 IR、跨层链接器、图分析、调用图、规则 DSL 解释器（line/method/symbol/io matchers）、统一规则注册表 + gating - `packages/metrics` — 被 `engine` 消耗的评分通道：roi/health/criticality/coupling/ seams/recommendations/diagnostics - `packages/metrics` — 被 `engine` 消耗的评分通道：roi/health/criticality/coupling/ seams/recommendations/diagnostics - `packages/engine` — 融合执行 pipeline：语言分发（TS/Prisma/Java-lexical） → rayon 每文件解析 + 每文件规则 → AST drop → 全图 passes；优雅降级、缓存 消费、git/scores 集成、多树跨层 join、规则性能分析 - `packages/git` — git 历史收集（单次 `git log --numstat` 遍历 → 每文件统计 + 每 commit 集合） - `packages/cache` — 每文件 IR/findings 缓存（内容哈希 + parser fingerprint + ruleset fingerprint） - `packages/napi` — 唯一的 Node↔Rust 边界（`analyze`/`analyzeTrees`/`analyzeEnvelope`/`version`） + npm 发布骨架（[packages/napi/README.md](packages/napi/README.md)) - `parser/` — 解析器前端：source → 通用 IR，包括跨 语言和框架的 HTTP route/consume 提取（[parser/README.md](parser/README.md)) - `rules/native/` — 全图原生规则（`rules-graph`, `rules-http`, `rules-cross-layer`, `rules-schema`）以及 `rules/dsl/` 声明式 JSON 规则包（[rules/README.md](rules/README.md)） ## 开发 ### 构建与测试 ``` cargo test --workspace cargo clippy --workspace --all-targets # kept at 0 warnings cargo fmt --all ``` 有关 N-API addon 的构建/工具链详细信息，请参阅 [`packages/napi/README.md`](packages/napi/README.md) （`cargo build -p zzop-napi --release --features addon`）。 在实际代码树上的冷/热启动 benchmark： ``` cargo run --release -p zzop-engine --example bench -- --packs rules/dsl --cache --git ``` 其他 `packages/engine/examples/` 中的临时测试工具：`cross_layer_rule_counts`（统计跨 1 个或多个树根节点的每个 `cross-layer/*` 规则的 finding 数量；设置 `ZZOP_DUMP_MESSAGES=` 以打印示例消息）， `dep_graph_export`（以 Graphviz DOT 或 Mermaid 格式导出文件级依赖图），以及 `fastapi_overlay_adapter`（参考外部适配器 —— 一个提供 `EngineConfig::adapter_overlays`（模式 B）支持的词法级 FastAPI/Python 路由扫描器，也可通过 napi 的 `adapterOverlays` 配置字段访问；请参阅 [`docs/NORMALIZED_AST.md`](docs/NORMALIZED_AST.md) 的“Adapter overlays”部分）。 运行纯英文源码检查（面向 OSS 的文件必须是英文；韩文仅限于内部的 notes 目录，该目录已被 gitignore，不属于此仓库的发布内容）： ``` bash scripts/check-english-source.sh ``` ## License MIT — 请参阅 [`LICENSE`](./LICENSE)。

标签：MITM代理, Rust, SAST, 代码架构分析, 可视化界面, 安全专业人员, 暗色界面, 死代码分析, 盲注攻击, 网络流量审计, 通知系统, 错误基检测, 静态代码分析