apisurface

apisurface

你即将发布一个库的第二个版本。升级会不会导致用户遇到问题？apisurface 只需两个对外公开接口的简单描述——每个版本导出的内容——就能回答这个问题，无需读取任何源代码：

• 已移除的导出项 — 之前存在，之后不再存在。 属于破坏性变更。
• 新增的导出项 — 后续版本中新加入。 不属于破坏性变更。
• 类型变更 — 导出项原本是 function，现在变成了 class，或在 function、class、interface、type、const 和 enum 之间发生了其他类型转换。 属于破坏性变更，详情记录为 before kind -> after kind。
• 签名变更 — 当两个版本都为同一导出项提供签名，且文本不同时。 属于破坏性变更，详情中包含两个签名。如果签名只出现在其中一侧，本身不算变更。
• 成员变更 — 对于列出成员的导出项（类、接口、枚举）：消失的名称合并为一条破坏性变更，顺序按之前的出现顺序排列；新增的名称合并为一条非破坏性变更，顺序按之后的出现顺序排列。没有成员列表的导出项视为没有成员。
• 弃用状态变化 — 某个导出项被标记为弃用，或不再被标记为弃用。两者都是非破坏性变更。

单个导出项可能产生多条变更记录——例如，一个组件同时变更类型、丢失成员并被标记为弃用，就会产生三条记录。每条记录都会注明导出项及其类型（如果该导出项仍然存在，则为后续版本中的类型）、说明变更内容和是否会造成破坏，并在变更类型定义了详情时附上详情字符串。

结果会将记录分别放入 breaking 和 non_breaking 列表，每个列表都按导出项名称和变更类型排序；此外还会提供摘要：每个接口面包含多少个导出项、每个列表中有多少条记录，以及最终判定——breaking 表示存在破坏性变更，clean 表示没有破坏性变更。整个计算是纯本地操作：不访问网络、不需要配置，也不会读取你提供的输入以外的文件。对于格式错误的输入——缺少导出项列表的接口面、缺少名称的导出项、不在允许范围内的类型，或同一接口面内出现重复的导出项名称——程序会报错并指出对应的一侧和精确路径，不会生成部分差异结果。

CLI

npx @reneturcios/apisurface diff --input args.json
npx @reneturcios/apisurface --version

args.json 包含完整的参数对象：

{
  "before": {
    "exports": [
      { "name": "parse", "kind": "function", "signature": "(text: string) => Ast" },
      { "name": "Widget", "kind": "class", "members": ["render", "mount"] }
    ]
  },
  "after": {
    "exports": [
      { "name": "parse", "kind": "function", "signature": "(text: string, opts: Opts) => Ast" },
      { "name": "Widget", "kind": "class", "members": ["render"] },
      { "name": "format", "kind": "function" }
    ]
  }
}

每个导出项的 signature、members 和 deprecated 都是可选项。差异将以 JSON 格式输出。

退出代码：成功时为 0，发生运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/apisurface mcp

MCP 客户端配置：

{
  "mcpServers": {
    "apisurface": {
      "command": "npx",
      "args": ["-y", "@reneturcios/apisurface", "mcp"]
    }
  }
}

工具

• diff_api_surface — 比较两个版本的公开 API 接口面。
  • before（接口面对象，必需）— 较早的版本，格式为 {exports}，其中每个导出项为 {name, kind, signature?, members?, deprecated?}
  • after（接口面对象，必需）— 较晚的版本，格式相同

返回 {breaking, non_breaking, summary}。

Docker

docker run -i ghcr.io/cloudcorprecords/apisurface
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/apisurface diff --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios