thebabush/nonna

**nonna** 是一个用于编程 Agent 的结构化代码相似度引擎，基于 [Opengrep](https://github.com/opengrep/opengrep) 的 IL 构建。它将每个函数解析后的控制/数据流图哈希为一个特征集，并通过加权 Jaccard 和非对称包含度来对函数对进行评分。匹配不受重命名影响：变量名、字段名、字面量和具体类型默认会被忽略——只要两个函数的计算方式相同，它们就会匹配。 其核心循环是 **reuse-before-write**：Agent 起草一个函数，调用 `find_similar`，然后得知“这在依赖 X 中已经存在——直接调用它即可”，这一过程涵盖了整个工作区、所有传递性的 cargo 依赖以及 std。 设计、决策与评估：[DESIGN.md](DESIGN.md)。 在寻找 v1（带有 WASM 演示的 Python 劣质代码检测器）？ → [nonna-v1](https://github.com/thebabush/nonna-v1)。 ## 🏗️ 构建 [](https://github.com/thebabush/nonna/actions/workflows/ci.yml) 支持 Linux 和 macOS（在 Windows 上，请使用 WSL —— 该引擎的构建仅限 Unix）。 需要 OCaml 5.3.0 opam switch 和 bash ≥ 5。在仓库根目录下执行： ``` git submodule update --init --recursive # vendor/opengrep + its grammars export PATH=/opt/homebrew/bin:$PATH eval $(opam env --switch=opengrep-5.3.0 --set-switch) . vendor/opengrep/libs/ocaml-tree-sitter-core/tree-sitter-config.sh dune build nonna ``` 二进制文件：`_build/default/nonna/cli/main.exe`（下文简称为 `nonna`）。 首次构建会编译内置引擎（仅一次）。注意事项：tree-sitter 环境脚本是必须的（缺少它 C stubs 会编译失败），并且任何嵌入了该解析器的二进制文件都必须调用 `Parsing_init.init ()`（我们的程序已经这样做了）。 ## 🔪 CLI ``` nonna query -- # find fns similar to each fn in draft nonna dupes [-t 0.5] # intra-corpus clone pairs nonna features # debug: per-fn feature dump nonna graph --fn NAME [-o DIR] # DOT per propagation round (+ source) nonna dump-il [--fn NAME] # compact IL CFG nonna corpus # cargo deps + std discovery / cache # 基准测试 nonna mine [-o pairs.tsv] # mine ground-truth pairs (token-level) nonna eval [-o scores.tsv] # pairwise recall/FPR nonna rank # MRR / recall@k through the pipeline # servers nonna lsp # stdio LSP (diagnostics, find-similar) nonna mcp [root] # stdio MCP (per-session) nonna serve [root] [-p 8976] # HTTP MCP + duplication explorer UI # 全局标志: --profile structural|full, --iters N, --with ch1,ch2 ``` ## 🤖 Agent 集成 (MCP) ``` # 按会话（每次启动均为冷索引）: claude mcp add nonna -- /path/to/main.exe mcp /path/to/workspace # 或：由所有会话共享的一个 warm daemon /path/to/main.exe serve /path/to/workspace & claude mcp add --transport http nonna http://127.0.0.1:8976/mcp ``` 工具：`find_similar`（起草的代码 → 按相关性排序的现有函数及源码），`query_similar`（file + line|name），`diff_functions`（A∩B 分数 + 按源码行划分的各方独立区域 —— 对于 bug/修复对，A−B ≈ bug，B−A ≈ fix），`status`。服务器的 `instructions` 会向 Agent 解释分数的语义（jaccard ≈ 1：除了重命名外完全相同；containment ≈ 1：“它不仅实现了你的功能，还包含了更多”）。 语料库根目录会在启动时被索引（首先索引工作区，然后是 `~/.cache/nonna/sigdb` 下每个 `crate@version` 缓存中的 cargo 依赖和 std —— 首次索引依赖约需 1 分钟，热加载 < 0.5 秒）。在信任空结果之前，请先检查 `status`。 `nonna serve` 还在 `http://127.0.0.1:8976/` 提供了**重复代码探索器**：显示语料库中所有超过阈值的相似对，支持名称/文件/最小大小过滤器，以及可使用键盘导航的并排函数差异视图——它既是一个去重导航器，也是一种直观了解引擎如何对真实代码进行评分的方式。 ## 🧑‍💻 编辑器集成 (VSCode) `editor/vscode-nonna/` —— 在打开/保存时提供诊断信息（“`avg` 类似于 `mean` (util.rs:1) —— jaccard 1.00”），在“问题”面板中可展开相关位置，提供灯泡操作（函数体差异 / 在侧边打开），以及“nonna: Find Similar Functions”命令面板命令。设置：参见其 README；简短版本：在其中运行 `npm install`，将该文件夹软链接到 `~/.vscode/extensions/nonna-dev.nonna-0.0.1`，并设置 `nonna.serverPath`。 ## 🧪 测试与基准测试 ``` bash tests/run.sh # core regressions (fixtures) bash tests/sanity.sh # 16 invariant assertions across Rust/Python/JS/Go bash tests/lsp-smoke.sh # LSP protocol session bash tests/mcp-smoke.sh # MCP stdio + HTTP session (incl. diff algebra) bash tests/mine-registry.sh # mine + evaluate against your local cargo registry bash tests/sweep.sh bench-out/paths.txt # hyperparameter sweep (MRR/recall@k) uv run tests/llm_judge.py --pairs ... --scores ... # LLM-judged pair quality ``` 当前的核心数据（Rust 基准测试，5.6 万个单元的语料库）：ALL MRR 0.963；重命名的克隆代码 rank-1 准确率为 98.7%；版本演进的函数 r@10 为 0.92；候选遗漏率 ≤ 1.6%。完整表格和注意事项详见 DESIGN.md。 ## 📜 许可证 nonna 的代码采用 [MIT](LICENSE) 许可证。内置引擎（`vendor/opengrep`，一个 git 子模块 —— 本仓库不进行分发）采用 LGPL-2.1 许可证；从本仓库构建的二进制文件会静态链接该引擎，并且通过本仓库的公开源码和构建说明即可满足 LGPL §6 的要求（你可以针对修改后的引擎重新链接）。 注意：某些引擎源码头文件提到了链接例外，但该引擎的 LICENSE 文件中实际上并不包含此例外——我们保守地假定其为纯 LGPL-2.1。 ## 🍝 免责声明 满怀爱心地 Vibecoded（凭直觉编写）。

标签：AI编程助手, Rust, SOC Prime, Web安全扫描, 云安全监控, 代码相似度分析, 代码重用, 可视化界面, 开发工具, 漏洞数据库, 网络流量审计, 静态分析