tompassarelli/chartroom

# Chartroom **代码即声明，基于 [Fram](https://github.com/tompassarelli/fram)。** Chartroom 将 beagle 源码树投射到 Lodestar 用于生活和工作的同一个具象化声明图中，然后从该图中*推导*出代码智能——如调用图、作用域正确的调用者 解析、传递杠杆——将其作为对该图的查询，而不是对文本的 定制处理过程。 这与 Lodestar 所做的尝试如出一辙，且直指源码：**扁平的、 基于文本与 grep 的代码库视图会腐化且无法计算关系问题； 而图始终是最新的，并且能免费给出答案。** Chartroom 存在的意义在于弄清楚，与现有的冷解析、 单跳工具相比，这是否真的能带来实质性的提升——又或者并非如此。 ## 流水线 ``` *.bjs ──beagle-claims──▶ CNF triples ──load──▶ Fram claim store ──Datalog──▶ leverage / callers (AST as claims) [s "p" o] (interned graph) (transitive closure) ``` 1. **`beagle-claims`**（位于 [beagle](https://github.com/tompassarelli/beagle)，`bin/beagle-claims`）将文件的 AST 转化为换行符分隔的 EDN 声明三元组 `[subj "pred" obj]` — 包含 `form-kind`、`name`、`calls` 以及统一的 **`child`** 包含边。 它是一种横切的*分析*投影，而非编译目标：它能处理 `.bjs` / `.bclj` / `.bnix`，忽略每个文件的 `#lang`。 2. **`bin/emit-corpus`** 在源码树上运行该操作 → `build/.claims`。 3. **`src/chartroom.clj`** 将三元组折叠进 Fram 存储中，推导出 **命名空间正确**的函数调用图（调用绑定在其自身 模块中的 defn——即裸符号匹配所忽略的作用域），并运行基准测试。 ## 前置条件 Chartroom 是三个同级项目之上的粘合层；将它们克隆到该 仓库旁边（下方命令假设采用 `~/code/` 的目录结构），并确保 [Babashka](https://github.com/babashka/babashka) (`bb`) 在 `PATH` 中： - **[fram](https://github.com/tompassarelli/fram)** — 声明存储 + Datalog 引擎。构建其 classpath 目录（`fram/out`）；运行器会加载 `-cp ~/code/fram/out`。 - **[beagle](https://github.com/tompassarelli/beagle)** — 提供 `bin/beagle-claims` 和 `bin/beagle-roundtrip`（AST→声明投影器）。这里的 `bin/*` 通过 `$BEAGLE`（默认为 `$HOME/code/beagle`）来解析它；如果在其他地方检出，请覆盖此变量。 - **[gjoa](https://github.com/tompassarelli/gjoa)** — RESULTS.md 中基准测试所运行的 活跃语料库。任何 beagle 源码树都可以；gjoa 只是其中被测量的那一个。 ## 运行说明 ``` bin/emit-corpus ~/code/gjoa/src ~/code/gjoa/tools ~/code/gjoa/tests build/gjoa.claims bb -cp ~/code/fram/out src/chartroom.clj build/gjoa.claims ``` ## 它证明了什么（以及没证明什么） 有关测量结论，请参阅 **[RESULTS.md](RESULTS.md)**。简而言之：在活跃的 gjoa 语料库上，该图回答了现有工具无法回答的两个问题——**作用域正确的 调用者**（在裸符号匹配错误率为 33–67% 的情况下，实现了完美的准确度）和 **传递性爆炸半径**（这是单跳工具在结构上根本无法 呈现的基石）——并且 Fram 的 Datalog 正确地计算出了真实的调用图闭包。 两种投影，两项任务（均源自同一份源码）： - **查询投影** (`beagle-claims`) — 带有语义 覆盖（`calls`/`name`/`child`）的紧凑型 AST 声明。非常适合杠杆查询；但存在信息丢失（舍弃了 类型/参数）。约 18 个三元组/form。 - **真值投影** (`beagle-roundtrip`) — 冗长的读取器数据声明， 能够**无损地**往返程序（类型作为 token 保留，注释作为 已解析的引用保留）。图作为*事实来源*；文本作为可重新生成的 视图。约 238 个三元组/form。 ## 状态 分阶段构建并验证：投影 → 杠杆基准测试 → 无损 往返 → 图原生重命名 → 作用域正确的词法解析器 → 重命名正确的注释。核心关卡保持在 **1100/1100 forms, 97/97 files**。 测量结果见 **[RESULTS.md](RESULTS.md)**；逐阶段构建 日志见 **[docs/build-log.md](docs/build-log.md)**。

标签：AST解析, Clojure, Datalog, 云安全监控, 代码分析, 凭证管理, 调用图, 静态分析