🥮 mooncakes.io

    moonlayout

    A deterministic MoonBit graph layout quality audit and regression library.

    graph
    audit
    snapshot
    svg
    ci
    moonbit
    Download zip
    Author
    Version
    0.2.0
    License
    MIT
    Repository
    Last updated
    19 days ago
    Downloads
    24

    No dependencies

    #MoonLayout Audit

    MoonLayout Audit 是一个 MoonBit 原生的图布局质量审计与回归验证库。 它不重新实现图自动布局算法，而是接收 Moon ELK、Graphviz、d3-force 或自定义 布局程序生成的坐标快照，检查节点和连线是否满足可读性与构建质量要求。

    项目的核心价值是：纯计算、无网络、确定性、可解释、适合 CI。相同的快照和审计 阈值会产生相同的报告、指纹和 SVG 标注结果。

    #为什么需要它

    自动布局引擎解决“如何摆放节点”，但工程团队还需要知道结果是否合格：节点是否 重叠、边是否交叉、节点是否越界、一次升级是否让文档图形发生意外漂移。MoonLayout Audit 将这些检查独立出来，作为布局引擎和文档构建之间的质量门禁。

    它与 MoonBit 社区中的图布局项目形成互补关系，而不是替代某个布局算法：布局由 其他工具完成，MoonLayout Audit 负责验证和记录结果。

    #快速开始

    要求 MoonBit 工具链和 Node.js（JS 目标只用于 CLI 文件读写）。

    moon fmt
moon check --deny-warn
moon test --deny-warn
moon build --target js src/cmd/moonlayout
moon run src/cmd/moonlayout -- \
  --input examples/pipeline.snapshot \
  --report audit-report.json \
  --svg audit.svg

    审计通过时 CLI 返回退出码 0，发现质量问题时返回 1，输入或参数错误时返回 2。audit-report.json 是机器可读报告，audit.svg 会把问题节点和问题边标成红色。 仓库中的示例产物见 examples/pipeline-audit.svg 和 examples/pipeline-report.json。

    #快照格式

    快照是一个简单、可审阅、可放入 Git 的文本文件：

    canvas 900 600
node Client 120 260 44 44
node API 360 260 44 44
node DB 600 180 44 44
node Queue 600 340 44 44
edge Client API
edge API DB
edge API Queue

    每行分别表示画布、节点或有向边。节点坐标是中心点，后两个数字是节点宽度和高度。 解析器会报告行号、重复节点、非法数字和不存在的边端点；空行和 # 注释可以忽略。

    #CLI 选项

    --input <file>            .snapshot 输入（缺省使用内置示例）
--report <file>           JSON 审计报告
--svg <file>              带问题标注的 SVG
--max-overlaps <n>        允许的重叠节点对，默认 0
--max-crossings <n>       允许的边交叉数，默认 0
--max-out-of-bounds <n>   允许的越界节点数，默认 0
--min-edge-length <n>     最小曼哈顿边长，默认不限制
--max-edge-length <n>     最大曼哈顿边长，默认不限制

    #MoonBit API

    let snapshot = @core.make_snapshot(
      900,
      600,
      [
        { id: "Client", x: 120, y: 260, width: 44, height: 44 },
        { id: "API", x: 360, y: 260, width: 44, height: 44 },
      ],
      [{ source: "Client", target: "API" }],
    )
    let report = @core.audit_snapshot(snapshot, @core.default_audit_config())
    let json = @core.report_to_json(report)
    let svg = @core.render_audit_svg(snapshot, report)

    审计指标包括：

    • 节点越界数量；
    • 节点重叠对数量；
    • 重复坐标数量；
    • 非共享端点的边交叉数量；
    • 最小、最大和平均边长；
    • 稳定布局指纹；
    • 逐条机器可读的违规记录。

    #预期使用场景

    1. 架构图 CI：布局引擎先生成服务架构坐标，MoonLayout Audit 在 Pull Request 中 阻止重叠节点或交叉边进入文档。
    2. 文档回归：提交上一次的快照指纹，升级布局引擎后重新审计，发现坐标漂移或 质量指标恶化时给出明确报告。
    3. 多引擎统一验证：Moon ELK、Graphviz、d3-force 和自定义布局器输出同一种快照， 使用同一套阈值进行比较。
    4. 教学与报告发布：生成 SVG 前检查标签、边线和画布边界，避免发布不可读图形。

    #项目边界与差异化

    MoonLayout Audit 不实现 Layered、Force、Radial 或其他通用自动布局算法，也不复制 Eclipse ELK、Graphviz 或 d3-force 的源代码。社区中的 moon_elk 等布局项目负责生成坐标， 本项目专注于布局快照审计、确定性回归和 CI 质量门禁。

    项目代码为原创 MoonBit 实现，采用 MIT License。

    #验收命令

    moon fmt
moon check --deny-warn
moon test --deny-warn
moon info
moon build --target js src/cmd/moonlayout
node --test tests/cli.integration.test.mjs
moon run src/cmd/moonlayout -- --input examples/pipeline.snapshot --report audit-report.json --svg audit.svg

    #License

    MIT

    AuditConfig

    source
    pub(all) struct AuditConfig {
      max_overlaps : Int
      max_crossings : Int
      max_out_of_bounds : Int
      min_edge_length : Int
      max_edge_length : Int
    }

    Thresholds used by the deterministic audit.

    AuditReport

    source
    pub(all) struct AuditReport {
      nodes : Int
      edges : Int
      overlap_pairs : Int
      duplicate_positions : Int
      out_of_bounds : Int
      edge_crossings : Int
      invalid_edge_endpoints : Int
      min_edge_length : Int
      max_edge_length : Int
      average_edge_length : Int
      passed : Bool
      fingerprint : String
      violations : Array[Violation]
    }

    The complete result of auditing a snapshot.

    Edge

    source
    pub(all) struct Edge {
      source : String
      target : String
    }

    A directed edge between two node identifiers.

    LayoutSnapshot

    source
    pub(all) struct LayoutSnapshot {
      width : Int
      height : Int
      nodes : Array[PositionedNode]
      edges : Array[Edge]
    }

    A layout snapshot produced by any graph layout engine.

    PositionedNode

    source
    pub(all) struct PositionedNode {
      id : String
      x : Int
      y : Int
      width : Int
      height : Int
    }

    A positioned node from a layout snapshot.

    Violation

    source
    pub(all) struct Violation {
      kind : String
      first : String
      second : String
      detail : String
    }

    A single machine-readable quality finding.

    audit_snapshot

    source
    fn audit_snapshot(snapshot : LayoutSnapshot, config : AuditConfig) -> AuditReport

    Audits a snapshot without changing it. All computations are integer based so a report is reproducible on every supported MoonBit target.

    default_audit_config

    source
    fn default_audit_config() -> AuditConfig

    make_snapshot

    source
    fn make_snapshot(width : Int, height : Int, nodes : Array[PositionedNode], edges : Array[Edge]) -> LayoutSnapshot

    parse_snapshot

    source
    fn parse_snapshot(input : String) -> Result[LayoutSnapshot, String]

    Parses the line-oriented .snapshot format used by the CLI.

    render_audit_svg

    source
    fn render_audit_svg(snapshot : LayoutSnapshot, report : AuditReport) -> String

    Renders a snapshot and highlights every audit finding in a self-contained SVG.

    report_to_json

    source
    fn report_to_json(report : AuditReport) -> String

    report_to_text

    source
    fn report_to_text(report : AuditReport) -> String

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsBuild queueStatistics

    © 2026 mooncakes.io