🥮 mooncakes.io

    moonapi_check

    Conservative OpenAPI 3.0.3 request compatibility analysis

    openapi
    compatibility
    api
    ci
    Download zip
    Author
    Version
    0.1.1
    License
    Apache-2.0
    Repository
    Last updated
    8 hours ago
    Downloads
    6

    #MoonAPI Check

    CI

    用 MoonBit 检查 OpenAPI 接口变更是否破坏旧请求。规则、引用解析和报告均由 MoonBit 实现，Node.js 只负责文件与进程接口。

    发现删除接口、新增必填请求字段、收紧字符串枚举，定位受影响操作和共享定义。分析不完整时退出 2，阻止 CI 静默放行。

    版本：0.1.1。工程验证与发布状态见验收证据，实现路径见架构说明。

    #快速运行

    需要 Node.js 24 和 MoonBit 官方工具链。已验证编译器 v0.10.11+6ff76a5f9，见工具链记录。不需要 npm 第三方依赖或 API Key。

    git clone https://github.com/WeiR-h/moonapi-check.git
cd moonapi-check
npm run check
npm test
node scripts/scenarios.mjs
node dist/moonapi-check.js check examples/compatibility-demo/old.openapi.json examples/compatibility-demo/new.openapi.json --format text

    最后一条命令预期退出码 1，报告 3 个问题：新增必填 phone、删除允许值 cancelled、删除 GET /orders/{orderId}。这个 1 表示检测到破坏，不是程序崩溃。Windows 用 $LASTEXITCODE 查看退出码，Ubuntu 用 echo $?。

    构建后，将 dist/moonapi-check.js 和 dist/core.mjs 一起复制到另一目录，即可仅用 Node.js 24 运行。预构建压缩包见 GitHub Releases，实际发布进度见交付记录。输入内容不会发往网络。

    #命令与报告

    node dist/moonapi-check.js check old.json new.json
node dist/moonapi-check.js check old.json new.json --format json
node dist/moonapi-check.js --help
node dist/moonapi-check.js --version

    含空格的路径需要引号。报告写入标准输出，可以重定向到文件。

    退出码含义
    0支持的检查完成，未发现破坏
    1支持的检查完成，发现破坏
    2输入无效、执行失败或分析不完整；优先于 1

    JSON 顶层包含 status、exit_code、findings、diagnostics、scope。每项变更包含 rule_id、method、path、old_location、new_location、reason。位置包含逻辑使用位置 pointer 和实际定义位置 definition_pointer；不存在的位置为 null。

    complete 表示V1 声明范围的检查完成，不能理解为所有 OpenAPI 语义或服务器行为均兼容。未覆盖契约的变化会报告未分析，保留已发现问题。详见支持矩阵和规则说明。

    #MoonBit 库

    已发布版本的安装命令：

    moon add WeiR-h/moonapi_check@0.1.1

    在调用方的 moon.pkg 中添加：

    import {
  "WeiR-h/moonapi_check" @check,
}

    调用示例：

    fn main {
      let before = "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Demo\",\"version\":\"1\"},\"paths\":{}}"
      let report = @check.check_json(before, before)
      println(report.to_text())
      println(report.exit_code()) // 0
    }

    运行 moon run --target js。公共 API：check_json(String, String) -> Report，Report::exit_code()、Report::to_text()、Report::to_json_report()。MoonBit 方法字段为 http_method，正式 JSON 中为 method。请用 to_json_report() 生成交换格式；派生 ToJson 是语言数据表示，与报告协议不同。

    #三个可复现场景

    场景目录预期
    发布检查compatibility-demo3 项破坏，退出 1
    客户端升级评估client-upgrade0 项破坏，退出 0
    共享组件影响排查shared-components2 个受影响操作，退出 1

    node scripts/scenarios.mjs 验证预期退出码和问题数量。场景均为人工构造，尚无真实用户采用或收益数据。

    #开发与 CI

    npm run check
npm run test:moon
npm run build
npm run test:cli
node scripts/moon.mjs fmt --check
node scripts/check-package.mjs

    GitHub Actions 在 Windows 和 Ubuntu 上安装固定版 MoonBit，执行检查、格式验证、构建、核心与 CLI 测试及三个场景。测试包含正反例、参数覆盖、嵌套对象、引用转义、循环/缺失引用、不完整分析、中文路径、有限枚举空间的独立对照。见验收证据。

    目录内容
    src/MoonBit 分析库、报告、测试、JS 导出桥接
    cmd/Node 文件与进程入口
    tests/CLI 与外部行为验证
    examples/三个人工场景
    scripts/构建、验证、发布包检查
    docs/设计、支持矩阵、赛事资料、交付证据

    .tools/moon、缓存和认证文件均排除于 Git/mooncakes 包。构建优先使用 MOON_HOME，其次项目 .tools/moon，最后 PATH 中的 moon。

    #许可证、来源与路线

    Apache-2.0。见 NOTICE、来源声明、CHANGELOG。没有调用外部兼容性检查器，不依赖 MoonContract 简化解析结果。AI 辅助实现、调试和文档；参赛者负责理解边界、人工申报和实际验收。

    仓库只保留源码、工程脚本、样例和技术文档。参赛规划与个人材料在本地同级资料目录管理，不是库的运行或发布依赖。赛事申报及审核结果另行记录。

    安装复验和预构建发布脚本默认把生成物写入源码目录旁的 MoonAPI Check 工程产物，可用 MOONAPI_CHECK_ARTIFACTS 指定其他位置；.tools/moon 是本机工具链，_build 和 dist 是必要构建输出，均不纳入源码提交。

    Diagnostic

    source
    pub(all) struct Diagnostic {
      code : String
      severity : String
      side : String
      http_method : String
      path : String
      location : Location
      reason : String
    } derive(Eq, ToJson)

    An input error or a reason why analysis could not be completed.

    Finding

    source
    pub(all) struct Finding {
      rule_id : String
      http_method : String
      path : String
      old_location : Location?
      new_location : Location?
      reason : String
    } derive(Eq, ToJson)

    A supported breaking change, attributed to an affected operation.

    Location

    source
    pub(all) struct Location {
      pointer : String
      definition_pointer : String
    } derive(Eq, ToJson)

    A JSON Pointer at the use site and at the resolved definition.

    Report

    source
    pub(all) struct Report {
      status : String
      findings : Array[Finding]
      diagnostics : Array[Diagnostic]
    } derive(Eq, ToJson)

    status is complete, incomplete, or invalid; it does not mean full OAS compatibility.

    Report::exit_code

    source
    fn Report::exit_code(self : Report) -> Int

    Exit code 2 takes precedence over breaking changes (1).

    Report::to_json_report

    source
    fn Report::to_json_report(self : Report) -> String

    Stable machine-readable report. JSON uses "method" for the HTTP method.

    Report::to_text

    source
    fn Report::to_text(self : Report) -> String

    Human-readable report containing all findings and diagnostics.

    check_json

    source
    fn check_json(old_text : String, new_text : String) -> Report

    Compare local OpenAPI 3.0.3 JSON using the explicitly documented V1 profile.

    execution_error

    source
    fn execution_error(message : String) -> Report

    Construct a host I/O or execution diagnostic without reimplementing reports in Node.

    version

    source
    fn version() -> String

    Version shared by the library report and CLI bridge.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io