Zod OpenAPI Contract Lint Kit

Local read-only prototype for finding common drift risks between Zod schemas, OpenAPI metadata, route responses, and generated API clients.

Why this exists

Teams often start with Zod as runtime validation and later generate OpenAPI specs/clients. Drift appears when schemas use constructs generators cannot represent cleanly, when route metadata is missing, or when auth/error responses are inconsistent.

This prototype scans TypeScript files and reports review items. It does not execute application code, import project modules, call network APIs, or modify files.

Current v1 checks

• Zod object schemas exported without nearby OpenAPI metadata (.openapi(...) or .describe(...)).
• z.any() / z.unknown() in public contracts.
• z.date() fields that may serialize differently in OpenAPI/client transports.
• z.record(...) map types that may need additionalProperties review.
• z.union(...) without a nearby discriminator hint.
• z.transform(...), .refine(...), .superRefine(...) in public schemas.
• Route handlers with auth hints but no visible 401 / 403 response docs nearby.
• Error responses without an obvious schema/envelope reference.

Try locally

python3 scanner.py examples
python3 scanner.py examples --format json
python3 scanner.py examples --output report.md
python3 scanner.py examples --fail-on-severity high
python3 scanner.py examples --min-severity high
python3 scanner.py examples --only-rule zod-date-serialization-review
python3 scanner.py --list-rules
python3 scanner.py --list-rules --format json
python3 scanner.py examples --ignore-rule runtime-only-zod-effect

CI usage

See docs/CI_USAGE.md for report-only, high-risk-only, and scoped rollout examples.

Safety

• Read-only local scan.
• No GitHub/npm/OpenAPI service account required.
• No dependency installation required for the prototype.
• Findings are review prompts, not automatic migration claims.
• CI failure is opt-in via --fail-on-severity.
• Rule filtering is explicit and local; unknown rule ids fail fast instead of silently changing coverage.
• --min-severity supports high-risk-only reports for CI summaries.
• --list-rules can be used to review active rule coverage before adding the scanner to CI.

Roadmap

• Expand fixtures across common Zod/OpenAPI routing patterns.
• Add fixtures for hono/zod-openapi/express-zod-api route variants.
• Package as a small developer CLI after the prototype stabilizes.
• Add more routing-library examples and release notes.