fossa-spec-drift

fossa-spec-drift

Snapshot the vendored spec, fetch the live one, diff them at the operation level, and say which of the differences land on a tool this server actually registers. The output is a report, not a commit: the working tree is put back the way it was found unless the user says otherwise.

Why the diff is operation-level: the spec is 1.4 MB of pretty-printed JSON. A text diff drowns in key-order and formatting churn and cannot tell a doc-string tweak from a removed parameter. Comparing the parsed JSON path-by-path gives three clean lists — added, removed, changed — and "changed" is defined as parameters, request body, or responses differing. Nothing else counts as drift.

Everything below is procedure; the only question worth asking first is whether the user wants the report only (default) or also wants the new spec kept.

1. Snapshot the baseline

All commands run from the repo root: /Users/rashford/Library/Mobile Documents/com~apple~CloudDocs/Developer/fossa-mcp — quote the path, it contains spaces.

First confirm the baseline exists. What is tracked on the current branch is decided by git ls-files spec/ API_PARITY_PLAN.md and by nothing else — a per-branch inventory hardcoded into this file went stale the same day it was written. If spec/fossa-openapi.json is not in that output, there is no drift to measure — say so, and note that running the update script (step 2) establishes a baseline for next time.

$SCRATCHPAD is not predefined — in a fresh shell the cp below would target /spec-baseline.json and fail. Set it to the session scratchpad directory if one is listed, otherwise mktemp -d, and since shell state does not persist between commands, use the same absolute path in every later step.

SCRATCHPAD="${SCRATCHPAD:-$(mktemp -d)}"
cp spec/fossa-openapi.json "$SCRATCHPAD/spec-baseline.json"
python3 -c "
import json
s = json.load(open('spec/fossa-openapi.json'))
M = {'get','put','post','delete','patch','options','head','trace'}
print(s['info']['version'],
      sum(1 for item in s['paths'].values() for m in item if m in M), 'operations')
"