Lunvtik/ariadne

`ariadne` 读取代码库并构建一个映射：**依赖图**、**调用图**、 **循环**、**热点**（fan-in/out）、**无效导出**，以及一个基于名称的 **能力可达性**层——入口点能否到达 `EXEC` / `CODE` / `NET` / `DESERIALIZE` / `FS` / `ENV`？输出格式为 `text`、`json` 或独立的 `html` 报告。支持语言：Python、TypeScript (+ TSX)、JavaScript (+ JSX)、Rust。 ## 安装 每种语言只需一个附加依赖——仅安装你需要的： ``` pip install "daedalus[lang-python]" # Python only pip install "daedalus[lang-typescript]" # TypeScript (+ TSX) pip install "daedalus[lang-javascript]" # JavaScript (+ JSX) pip install "daedalus[lang-rust]" # Rust pip install "daedalus[all]" # everything ``` 缺少语言语法会使文件被直接 `skip`，绝不会导致崩溃。 ## 用法 ``` ariadne path/to/repo --format text # human-readable report ariadne path/to/repo --format json # machine-readable map ariadne path/to/repo --format html > report.html # self-contained black-glass report ``` | 参数 | 描述 | 默认值 | |---|---|---| | `root` | 要分析的目录路径（必填） | — | | `--level` | 分析级别（`macro`） | `macro` | | `--format` | 输出格式（`text` / `json` / `html`） | `text` | `text` 输出示例： ``` ariadne · /path/to/your/repo Files : 42 Languages : python Cycles : 2 Dead Exports : 5 certain / 3 uncertain Skipped : 12 Hotspots (3): 12 in / 45 out src/utils/helpers.py 8 in / 12 out src/core/engine.py 3 in / 20 out src/main/cli.py ``` ## 功能 - **依赖图** —— 本地和外部依赖，已解析和未解析的导入 - **调用图** —— 函数和方法之间的调用关系 - **循环检测** —— 循环依赖，以链的形式显示 - **热点** —— 具有高 fan-in / fan-out 的文件作为维护指标 - **无效导出** —— 未被引用的公共符号及其置信度评级 - **能力可达性** —— 基于 `EXEC`、`CODE`、`NET`、`DESERIALIZE`、`FS`、`ENV` 名称的信号 - **三种输出格式** —— `text`、`json`、独立的 `html` - **垂直切片架构** —— 每种语言都是一个可删除的特性切片 ## HTML 报告 一个完全独立的 `report.html` 文件——无需服务器，无需外部资产，直接打开即可。黑色玻璃 主题，语法高亮，所有视图只需在页头点击一次即可访问。

Calls — who calls whom, ranked by fan-out.	Hotspots — fan-in / fan-out ranking.
Capabilities — symbols reaching EXEC / NET / FS / ENV.	Dead exports — public symbols nothing imports.
Files — every file with language and stability.	External packages — third-party deps and who uses them.

## 语言 | 语言 | 语法 | 附加依赖 | |---|---|---| | Python | `tree-sitter-python` | `ariadne[lang-python]` | | TypeScript (+ TSX) | `tree-sitter-typescript` | `ariadne[lang-typescript]` | | JavaScript (+ JSX) | `tree-sitter-javascript` | `ariadne[lang-javascript]` | | Rust | `tree-sitter-rust` | `ariadne[lang-rust]` | ## 能力 在入口点对敏感模式进行的基于名称的检测： | 能力 | 示例 | 风险 | |---|---|---| | `EXEC` | `os.system`, `subprocess.run` | 高 | | `CODE` | `eval`, `exec` | 高 | | `NET` | `requests.get`, `httpx` | 高 | | `DESERIALIZE` | `pickle.load`, `yaml.load` | 高 | | `FS` | `open`, `Path.write_text` | 中 | | `ENV` | `os.environ` | 低 | 检测基于名称模式，而非数据流——它能可靠地找到 `os.system()` 但可能产生误报（名称相似）和漏报（间接调用）。 请将其用作排查信号，而非确凿证据。 ## 架构 `src/` 下的特性优先垂直切片。每个 `lang_*` 切片通过 `register(reg)` 自动注册；加载器会扫描 `features/`，因此删除一种语言只需进行文件夹 操作。 ``` src/ ├── constants/ # global constants (skip-dirs, size cap, walk depth) ├── contracts/ # shared Pydantic models (FileAnalysis, ImportInfo, …) ├── loading/ # registry, discovery, walker, grammars ├── main/ # CLI, pipeline, renderer ├── nodes/ # AST node types ├── safe_io/ # secure I/O (path containment + size cap) └── features/ ├── capabilities/ # capability reachability ├── graph/ # dependency graph, call graph, cycles, metrics ├── lang_python/ # Python slice ├── lang_typescript/ # TypeScript slice ├── lang_javascript/ # JavaScript slice └── lang_rust/ # Rust slice ``` 流水线：`discover()` → `walk_file()` → `build_graph()` → `analyze_capabilities()` → `render()`。 ## 安全 `ariadne` 会解析不受信任的第三方代码；`safe_io` 是其安全边界： - **路径限制** —— 符号链接解析后，路径必须保留在根目录内 - **大小上限** —— 单次 TOCTOU 安全的有界读取（无“先检查后打开”竞态条件）；超过 2 MB 的文件会被跳过 - **遍历深度** —— 上限为 450 - **禁止执行** —— 绝不运行被解析的代码 请按照 [SECURITY.md](SECURITY.md) 报告漏洞——请勿通过公开的 issue 报告。 ## 常见问题 **它与 linter 有何不同？** 它映射的是*结构*——依赖关系、调用、 循环、热点。它不是 linter 的替代品，也不是安全扫描器。 **为什么文件会被 `skip`？** `no_plugin`（该扩展名没有对应的语法），`too_large` （超过 2 MB），`missing_grammar`（语法无法加载），或 `parse_error`。 **支持 CI/CD 吗？** 是的——`ariadne . --format json > ariadne-report.json`，然后处理该 JSON。 **无效导出的 `confidence` 代表什么？** `high` = 未在任何地方被导入； `low`/`medium` = 可能够通过通配符导入到达，或情况不确定。 **支持 Monorepos 吗？** 是的——支持递归，并将外部依赖与本地依赖分离。 ## 发布说明 **0.1.0 — Beta。** 依赖图 + 调用图、循环检测、热点、带置信度的 无效导出、基于名称的能力、三种输出格式、四种语言、 自动注册的垂直切片插件。已知限制：基于名称的能力（无 数据流）、仅支持 `macro` 级别、仅语法解析。 ## 许可证 [GNU Affero General Public License v3.0](LICENSE)。自由且开源：你可以使用、 研究、修改并分享它。**强 Copyleft** —— 如果你分发它，或作为 网络服务运行修改后的版本，你必须在相同的许可证下发布你的全部源代码。 如需其他安排，请联系 public.magician350@passinbox.com。

标签：IPv6支持, Python, Tree-sitter, 依赖图, 文档结构分析, 无后门, 调用图, 逆向工具, 错误基检测, 静态代码分析