run-api-contract-audit
Runs a static, name-matching heuristic diff between backend Pydantic/SQLModel response fields and the frontend's hand-written API TypeScript interfaces, to surface likely drift after either side changes. Use after editing a FastAPI endpoint's response model, a SQLModel/Pydantic schema, or the frontend's apiHandlers/types.ts — before assuming the two sides still agree on field names.
Source facts
- Repository
- districtr/districtr-v2
- Last source activity
- September 18, 2026 at 14:42
- Detected SKILL.md language
- English
- Stars
- 6
- Forks
- 3
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
File Explorer
2 filesShowing SKILL.md
SKILL.md
Source instructions · Read-only preview- name
- run-api-contract-audit
- description
- Runs a static, name-matching heuristic diff between backend Pydantic/SQLModel response fields and the frontend's hand-written API TypeScript interfaces, to surface likely drift after either side changes. Use after editing a FastAPI endpoint's response model, a SQLModel/Pydantic schema, or the frontend's apiHandlers/types.ts — before assuming the two sides still agree on field names.
# API contract audit
This repo has no generated OpenAPI client: `app/src/app/utils/api/apiHandlers/types.ts` is hand-maintained against the backend's Pydantic/SQLModel response models, so the two can drift silently whenever one side changes without the other.
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/audit_contracts.py
```
Run from the repo root (`--help` for path overrides). Exits nonzero on drift, so it works as a pre-push check. The report explains its own labels and prints its limitations at the end of every run — treat a reported drift as a lead to verify against the actual endpoint and type definitions, not a verdict.
This audit is a stopgap. Issue #756 proposes generating the client types from the backend's OpenAPI schema (HeyAPI); if that lands, the drift class this skill checks for stops existing and the skill retires with it.
View on GitHub