Contractscope
OpenAPI 規格比較與相容性規則。
比較兩份 OpenAPI 規格，列出可能影響既有呼叫端的結構性變更。遇到尚未支援的規則時，結果會保留涵蓋警告。
請求與回應的相容方向
只看 schema diff，很容易把「多了一個欄位」當成絕對相容。但請求與回應的集合方向並不相同：原本有效的請求必須繼續被接受；回應端則不能任意產生舊版合約沒有宣告的值。
| 變更 | Request | Response |
|---|---|---|
| 擴充 enum 值 | 相容 | 破壞性變更 |
| 既有欄位改為必填 | 破壞性變更 | 相容 |
| 移除媒體類型 | 破壞性變更 | 破壞性變更 |
這裡的「相容」僅指已支援的結構規則；不代表實際伺服器行為、SDK 或商業邏輯也相容。
解析與比較流程
讀取 JSON／YAML，拒絕重複鍵、過深結構與過量展開；每份輸入限制 512 KiB。
解析 path、method、繼承參數、本地 JSON Pointer 參照與 operation 中實際用到的 schema。
對 required、enum、type、封閉物件與媒體類型套用對應規則。
UI 的篩選、匯出和 CLI 退出碼，都來自同一份比較結果。
npm ci
npm run diff -- samples/baseline.json samples/candidate.json
npm test
npm run build更改任一份規格時，前一次結果會清除。非同步讀檔使用獨立的輸入序號，避免較舊的讀檔覆蓋剛貼上的新資料；合約內容只在本機瀏覽器記憶體中處理。
涵蓋範圍與 CLI 退出碼
結果分為兩個面向：status 是目前辨識到的相容性變更，coverage 是是否碰到工具不支援的語意。即使已找到 breaking，只要涵蓋不完整，就必須保留警告。
| Code | 意義 |
|---|---|
0 | 分析完整，且未觸發破壞性變更阻擋條件 |
1 | 分析完整，且 --fail-on-breaking 偵測到 breaking |
2 | 涵蓋不完整，即使也找到 breaking 仍回傳非零 |
3 | 輸入、檔案或命令參數無效 |
測試有成對檢查請求／回應方向、本地參照循環、節點預算、重複鍵和真實 Node 子程序的退出碼。設計紀錄亦保留了曾將「回應媒體格式刪除」誤判為相容、後續修正的案例。
支援範圍與限制
開放物件、複合 schema、範圍與格式、security、外部參照、未知 dialect 等，都可能造成涵蓋警告。這不是完整 OpenAPI validator，也不執行真實伺服器或產生 SDK。
建議審查順序：先用內建範例產生報告，查看 規則與反例，最後對照 CLI 測試。完整分析不等於正式部署絕對安全。