Metadata-Version: 2.4
Name: zod-openapi-contract-lint-kit
Version: 0.1.1
Summary: Local read-only scanner for Zod/OpenAPI contract drift risks.
Author: Zod OpenAPI Contract Lint Kit contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/vasiliy0/zod-openapi-contract-lint-kit
Project-URL: Repository, https://github.com/vasiliy0/zod-openapi-contract-lint-kit
Project-URL: Issues, https://github.com/vasiliy0/zod-openapi-contract-lint-kit/issues
Keywords: zod,openapi,typescript,api,lint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
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`](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.
