io.github.CloudCorpRecords/apisurface

apisurface

You are about to release version two of a library. Will it break anyone who upgrades? apisurface answers that from two plain descriptions of the public surface — the exports each version exposes — without reading any source code:

• Removed exports — present before, gone after. Breaking.
• Added exports — new in the later version. Non-breaking.
• Kind changes — an export that was a function and is now a class, or any other switch among function, class, interface, type, const, and enum. Breaking, with the detail recorded as before kind -> after kind.
• Signature changes — when both versions carry a signature for the same export and the text differs. Breaking, with both signatures in the detail. A signature present on only one side is not, on its own, a change.
• Member changes — for exports that list members (classes, interfaces, enums): names that disappeared are one breaking entry, in the order they appeared before; names that appeared are one non-breaking entry, in the order they appear after. An export with no members list counts as having no members.
• Deprecation flips — an export that became deprecated, or one that stopped being deprecated. Both are non-breaking entries.

A single export can contribute several entries — a widget that changed kind, lost a member, and was deprecated all at once produces three. Every entry names the export, reports its kind (the later kind when the export still exists), says what changed and whether it breaks, and carries a detail string where the change defines one.

The result splits entries into a breaking list and a non_breaking list, each sorted by export name and then by change, plus a summary: how many exports each surface had, how many entries landed in each list, and a verdict — breaking when the breaking list is non-empty, clean otherwise. The computation is pure and local: no network, no configuration, no files beyond the input you pass in. Malformed input — a surface without its exports list, an export with no name, a kind outside the allowed set, a duplicated export name inside one surface — is rejected with an error naming the side and the exact path, and no partial diff is produced.

CLI

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

args.json contains the full arguments object:

{
  "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, and deprecated are optional per export. The diff is printed as JSON.

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/apisurface mcp

MCP client config:

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

Tools

• diff_api_surface — Diff the public API surface between two versions.

  • before (surface object, required) — the earlier version, as {exports} where each export is {name, kind, signature?, members?, deprecated?}
  • after (surface object, required) — the later version, in the same shape

  Returns {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

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios