apisurface

apisurface

ライブラリのバージョン 2 をリリースしようとしています。アップグレードすると、利用者に影響が出るでしょうか？apisurface は、ソースコードを一切読まずに、公開 API の概要（各バージョンが公開するエクスポート）を記述した 2 つのプレーンなデータから、その答えを導き出します。

• 削除されたエクスポート — 以前は存在していたが、後のバージョンではなくなったものです。 破壊的変更です。
• 追加されたエクスポート — 後のバージョンで新たに追加されたものです。 非破壊的変更です。
• 種類の変更 — エクスポートが function から class になった場合や、function、class、interface、type、const、enum の間で種類が変わった場合です。 破壊的変更で、詳細には before kind -> after kind が記録されます。
• シグネチャの変更 — 両方のバージョンに同じエクスポートのシグネチャがあり、そのテキストが異なる場合です。 破壊的変更で、詳細に両方のシグネチャが記録されます。片方にしかないシグネチャは、それだけでは変更とはみなされません。
• メンバーの変更 — メンバーを列挙するエクスポート（クラス、インターフェース、列挙型）が対象です。なくなった名前は、以前に記載されていた順に、破壊的変更のエントリー 1 件にまとめられます。追加された名前は、後のバージョンに記載された順に、非破壊的変更のエントリー 1 件にまとめられます。メンバーリストがないエクスポートは、メンバーがないものとして扱われます。
• 非推奨状態の変更 — エクスポートが非推奨になった場合、または非推奨ではなくなった場合です。どちらも非破壊的変更のエントリーです。

1 つのエクスポートから複数のエントリーが作成されることがあります。たとえば、ウィジェットの種類が変わり、メンバーが削除され、同時に非推奨になった場合、3 つのエントリーが作成されます。各エントリーにはエクスポート名、種類（エクスポートが引き続き存在する場合は後のバージョンの種類）、変更内容と破壊的かどうかが示され、変更に詳細が定義されている場合は詳細文字列も含まれます。

結果はエントリーを breaking リストと non_breaking リストに分け、それぞれエクスポート名、次に変更内容の順で並べ替えます。また、各サーフェスに含まれるエクスポート数、各リストに入ったエントリー数、および判定をまとめた概要も含まれます。判定は、破壊的変更が 1 件以上ある場合は breaking、それ以外は clean です。処理は純粋なローカル処理です。ネットワーク、設定、渡された入力以外のファイルは必要ありません。不正な入力（exports リストがないサーフェス、名前のないエクスポート、許可された集合に含まれない種類、1 つのサーフェス内で重複したエクスポート名）は、対象側と正確なパスを示すエラーで拒否され、差分の一部だけが出力されることはありません。

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 — 2 つのバージョン間で公開 API の概要を比較します。
  • before（サーフェスオブジェクト、必須）— 以前のバージョン。各エクスポートが {name, kind, signature?, members?, deprecated?} の形式で、全体を {exports} として記述します。
  • 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 — Copyright (c) 2026 Rene Turcios