A zero-dependency CLI, oas-drift, runs on Python 3.11+ and detects drift between an OpenAPI spec and a codebase, ensuring generated artifacts like SDKs and docs stay in sync with implementation.

OpenAPI specs drift when code changes, and oas-drift provides a minimal, deterministic, dependency-free way to detect and report drift, encouraging normalization of the spec side before comparison.

Normalization notes: path matching treats routes literally without resolving router prefixes, and drifting examples (such as POST vs PUT) are correctly reported, underscoring the importance of matching rules and router configurations.

In a real-world run, drift findings include /health being CODE ONLY, /items/{id} and /users/{id} with METHOD MISMATCH, and /admin/stats and /items as SPEC ONLY, illustrating practical drift scenarios.

The project acknowledges limitations: it currently supports only JSON OpenAPI 3.x ( YAML support planned), uses literal path matching, may hide f-string paths, and does not yet compare request/response schemas; all details are in the README.

Performance and reliability are underscored by 15 pure-function tests, validation against FastAPI templates, and guaranteed determinism by parsing sources with Python's ast module without executing code.

The tool scans a directory in read-only mode and outputs both human- and machine-readable results, designed as a detector to avoid becoming a gate that could break builds.

Drift types identified include SPEC ONLY (in spec but missing in code), CODE ONLY (in code but not in the spec), and METHOD MISMATCH (HTTP method differences on matching paths).

The author promotes treating the OpenAPI spec as a contract to be checked, arguing that CI gates are inappropriate for drift detection; oas-drift delivers deterministic results without executing code.