Conservative OpenAPI 3.0.3 request compatibility analysis

openapi

compatibility

api

Download zip

Author

WeiR-h

Version

0.1.1

License

Apache-2.0

Repository

github.com/WeiR-h/moonapi-check

Last updated

7 hours ago

Downloads

#MoonAPI Check

用 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-demo	3 项破坏，退出 1
客户端升级评估	client-upgrade	0 项破坏，退出 0
共享组件影响排查	shared-components	2 个受影响操作，退出 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

Site source Report issue Packages Build queue Skills Statistics

moonapi_check

#MoonAPI Check

#快速运行

#命令与报告

#MoonBit 库

#三个可复现场景

#开发与 CI

#许可证、来源与路线

#Diagnostic

#Finding

#Location

#Report

#Report::exit_code

#Report::to_json_report

#Report::to_text

#check_json

#execution_error

#version

Source Files

Diagnostic

Finding

Location

Report

Report::exit_code

Report::to_json_report

Report::to_text

check_json

execution_error

version