moon-graph-ledger
Deterministic graph data ledger, audit and regression analysis
graph
audit
data
ci
Author
Version
0.1.0
License
MIT
Repository
Last updated
5 hours ago
Downloads
1
#MoonGraph Ledger
MoonBit 原生的本地图数据仓与回归审计工具。接收有向属性图，保存不可变快照、分析结构、执行质量规则、比较版本，并提供真实路径与来源信息解释结果。核心不访问网络、不读取时钟、不调用 AI；Node.js 仅作为 CLI 的文件系统与进程适配层。
#运行
要求 MoonBit 和 Node.js（建议 20+）。本机已验证工具链为 moon 0.1.20260920 / moonc v0.10.14。
在本目录打开 PowerShell：
$env:MOON_HOME = 'E:\moonbit\moonbit-cli'
$env:PATH = "$env:MOON_HOME\bin;$env:PATH"
moon check
moon build --target js
moon run --target js src/cmd/moon-graph -- --help以下示例用 node 直接运行 MoonBit 编译产物，避免反复启动构建过程：
$cli = '_build/js/debug/build/cmd/moon-graph/moon-graph.js'
node $cli import examples/docs-graph.json --out "$env:TEMP\graph.json"
node $cli commit "$env:TEMP\graph.json" --store .ledger
node $cli stats "$env:TEMP\graph.json"
node $cli diff examples/docs-graph.json examples/docs-graph-v2.json
node $cli impact examples/docs-graph.json docs/install.md --direction upstream
node $cli explain examples/docs-graph.json docs/index.mdcommit 是本地数据快照操作，不会创建 Git commit。快照写入 .ledger/snapshots/<fingerprint>.json，可以直接交给其他命令读取。相同内容复用同一文件；已有文件内容不一致时拒绝写入。发布通过同目录临时文件和排他硬链接完成，要求文件系统支持硬链接。
#一分钟演示：文档变更的质量门禁
node $cli docs examples/docs --out "$env:TEMP\docs.json"
node $cli audit "$env:TEMP\docs.json" --rules examples/docs-rules.json
node $cli audit "$env:TEMP\docs.json" --rules examples/docs-rules.json --format markdown示例故意引用不存在的 api.md。审计将报告 no_missing_targets，并返回退出码 1。explain <snapshot> api.md 可定位到 index.md:4 的引用边。图结构已完整保存，缺失文档以 missing_document 节点显式表示。
#数据交换
JSON：
{
"nodes": [{"id":"a","kind":"module","properties":{"owner":"core"}}, {"id":"b"}],
"edges": [{"id":"ab","from":"a","to":"b","kind":"depends_on","source":"build.json:12"}]
}JSONL：
{"type":"node","id":"a"}
{"type":"node","id":"b"}
{"type":"edge","id":"ab","from":"a","to":"b"}用 import input.jsonl --format jsonl --out snapshot.json 导入。允许边记录先于节点；当前实现会将输入装入内存，不是流式引擎。
节点字段：id、kind、label、source、properties。边字段：id、from、to、kind、source、properties。属性必须是 JSON 对象；数字按 MoonBit JSON 的 Double 语义处理，精确大整数应存成字符串。节点 ID 必填；省略边 ID 时以 [from,to,kind] 生成稳定 ID，多重边需提供不同的显式 ID。重复 ID、非字符串字段、悬空端点会被拒绝。source 是可自由填写的来源字符串，导入器不会推断不存在的来源。
#规则
{
"acyclic": true,
"no_isolated_nodes": true,
"no_missing_targets": true,
"max_out_degree": 12,
"required_root": "index.md"
}- acyclic：错误；提供沿真实有向边闭合的环路径，不把环下游节点误报为环成员。
- no_isolated_nodes：警告；列出没有入边和出边的节点。
- no_missing_targets：错误；列出文档引用图中的缺失目标。
- max_out_degree：警告；0 表示不限制，否则报告超限节点。
- required_root：错误；根必须存在，且所有节点必须能从它沿边方向到达。
默认仅启用 acyclic。未知规则名、错误类型、小数或负数阈值均报输入错误。规则方向有业务含义：依赖图不一定应要求从一个根访问所有依赖者，请按实际边语义配置。
退出码：0 成功（可能有警告），1 审计发现 error 或解释节点不存在，2 输入/参数/I/O 错误。警告不阻断 CI。
#分析和版本比较
- stats：节点数、边数、孤立点、最大出度、弱/强连通分量数、有向环判断。
- impact：默认 downstream，支持 upstream；每个结果附确定性最短路径。它表示图可达性，不预测业务故障概率。
- diff：按稳定 ID 报告新增、删除、属性或端点变化的节点/边；包括变更边 ID 和两侧指纹。
- explain：节点属性、来源、入边、出边和快照指纹。
- audit --format markdown：可读审计报告；默认输出 JSON。可用 --out 保存。
语义相同的节点/边排列和嵌套属性键排列产生相同快照与指纹。JSON 数字表示会规范化，数组内部顺序仍有意义。指纹是双滚动校验值，不是密码学哈希；不应单独用作可信签名或安全完整性证明。存储和 diff 都会检查内容，不仅比较指纹。
#MoonBit 库
模块名 code3055/moon-graph-ledger，用 moon add code3055/moon-graph-ledger 引入。公共 API 位于 src/graphledger/pkg.generated.mbti。图核心全部使用 MoonBit 与标准库，无第三方包；可通过 parse_graph / parse_jsonl / markdown_graph 创建有效图，再调用 audit、diff、impact、strong_components。直接构造 Graph 的调用者必须保证 ID 唯一、所有端点存在。
#验证
moon fmt --check
moon check
moon test
moon build --target js
node --test tests/cli.test.mjs或执行 ./verify.ps1 -MoonHome 'E:\moonbit\moonbit-cli'。测试包含三个节点的全部 512 种有向图、独立可达性预言机、2000 节点深链、语义规范化、JSONL、文档导入以及 CLI 与不可变快照的端到端检查。
#范围与后续
当前为可运行的本地 MVP：JSON/JSONL、Markdown 引用图、图分析与规则、JSON 快照仓、差异与解释、JSON/Markdown 报告。没有实现通用查询语言、持久化属性索引、事务数据库、流式增量更新或布局引擎。邻接与 ID 索引在分析时构建。
Markdown 采集是有限语法实现：识别简单内联链接，跳过常见 fenced code、单反引号代码、图片与外部 URL；不保证 CommonMark 完整兼容，不验证标题锚点，也不支持引用式链接、复杂转义、带标题/嵌套括号目标。CI 输入需符合此子集。后续优先完善解析器和存储格式版本演进，再扩展查询与增量分析。
MIT License。工程设计见 docs/DESIGN.md。
MIT
Updated 5 hours ago
1 downloads