zod-openapi-contract-lint-kit 0.1.1__tar.gz

zod_openapi_contract_lint_kit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zod_openapi_contract_lint_kit-0.1.1/PKG-INFO

@@ -0,0 +1,80 @@
+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.

zod_openapi_contract_lint_kit-0.1.1/README.md

@@ -0,0 +1,56 @@
+# 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.

zod_openapi_contract_lint_kit-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zod-openapi-contract-lint-kit"
+version = "0.1.1"
+description = "Local read-only scanner for Zod/OpenAPI contract drift risks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Zod OpenAPI Contract Lint Kit contributors" }]
+keywords = ["zod", "openapi", "typescript", "api", "lint"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Quality Assurance"
+]
+
+[project.urls]
+Homepage = "https://github.com/vasiliy0/zod-openapi-contract-lint-kit"
+Repository = "https://github.com/vasiliy0/zod-openapi-contract-lint-kit"
+Issues = "https://github.com/vasiliy0/zod-openapi-contract-lint-kit/issues"
+
+[project.scripts]
+zod-openapi-contract-lint-kit = "zod_openapi_contract_lint_kit.cli:main"
+zod-openapi-lint = "zod_openapi_contract_lint_kit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+zod_openapi_contract_lint_kit = ["rules.json"]

zod_openapi_contract_lint_kit-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit/__init__.py

@@ -0,0 +1,3 @@
+"""Zod OpenAPI contract lint scanner."""
+
+__version__ = "0.1.1"

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit/cli.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Read-only static scanner for Zod/OpenAPI contract drift risks."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+DEFAULT_RULES = Path(__file__).with_name("rules.json")
+SUPPORTED_SUFFIXES = {".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"}
+SEVERITY_ORDER = {"low": 1, "medium": 2, "high": 3}
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    severity: str
+    pattern: str
+    why: str
+    fix: str
+    suppress_if_nearby: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Finding:
+    file: str
+    line: int
+    rule_id: str
+    severity: str
+    signal: str
+    why: str
+    fix: str
+
+
+def load_rules(path: Path = DEFAULT_RULES) -> list[Rule]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    rules = []
+    for item in data["rules"]:
+        rules.append(Rule(
+            id=item["id"],
+            severity=item["severity"],
+            pattern=item["pattern"],
+            why=item["why"],
+            fix=item["fix"],
+            suppress_if_nearby=tuple(item.get("suppress_if_nearby", [])),
+        ))
+    return rules
+
+
+def filter_rules(rules: Iterable[Rule], only_rule: set[str] | None = None, ignore_rule: set[str] | None = None) -> list[Rule]:
+    only_rule = only_rule or set()
+    ignore_rule = ignore_rule or set()
+    known_ids = {rule.id for rule in rules}
+    unknown = (only_rule | ignore_rule) - known_ids
+    if unknown:
+        raise ValueError("Unknown rule id(s): " + ", ".join(sorted(unknown)))
+    filtered = []
+    for rule in rules:
+        if only_rule and rule.id not in only_rule:
+            continue
+        if rule.id in ignore_rule:
+            continue
+        filtered.append(rule)
+    return filtered
+
+
+def discover(root: Path) -> list[Path]:
+    if root.is_file():
+        return [root] if root.suffix.lower() in SUPPORTED_SUFFIXES else []
+    ignored = {"node_modules", "dist", "build", ".git", ".next", "coverage"}
+    files = []
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix.lower() not in SUPPORTED_SUFFIXES:
+            continue
+        if any(part in ignored for part in path.parts):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def nearby_text(lines: list[str], index: int, radius: int = 4) -> str:
+    start = max(0, index - radius)
+    end = min(len(lines), index + radius + 1)
+    return "\n".join(lines[start:end])
+
+
+def is_suppressed(rule: Rule, lines: list[str], index: int) -> bool:
+    if not rule.suppress_if_nearby:
+        return False
+    context = nearby_text(lines, index)
+    return any(token in context for token in rule.suppress_if_nearby)
+
+
+def display_path(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def scan_file(path: Path, root: Path, rules: list[Rule]) -> list[Finding]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    findings: list[Finding] = []
+    for i, line in enumerate(lines):
+        for rule in rules:
+            if re.search(rule.pattern, line, flags=re.I):
+                if is_suppressed(rule, lines, i):
+                    continue
+                findings.append(Finding(
+                    file=display_path(path, root),
+                    line=i + 1,
+                    rule_id=rule.id,
+                    severity=rule.severity,
+                    signal=line.strip(),
+                    why=rule.why,
+                    fix=rule.fix,
+                ))
+    return findings
+
+
+def scan(root: Path, rules_path: Path = DEFAULT_RULES, only_rule: set[str] | None = None, ignore_rule: set[str] | None = None) -> dict[str, Any]:
+    root = root.resolve()
+    base = root if root.is_dir() else root.parent
+    rules = filter_rules(load_rules(rules_path), only_rule=only_rule, ignore_rule=ignore_rule)
+    files = discover(root)
+    findings: list[Finding] = []
+    for file in files:
+        findings.extend(scan_file(file, base, rules))
+    return {
+        "scanned_files": len(files),
+        "active_rule_count": len(rules),
+        "finding_count": len(findings),
+        "findings": [asdict(f) for f in findings],
+        "summary_by_severity": severity_summary(findings),
+        "summary_by_rule": rule_summary(findings),
+        "notes": [
+            "Read-only static scan; no TypeScript execution, imports, network calls, or file changes.",
+            "Findings are contract-review prompts and may need project-specific suppression rules.",
+        ],
+    }
+
+
+def severity_summary(findings: list[Finding]) -> dict[str, int]:
+    summary: dict[str, int] = {}
+    for finding in findings:
+        summary[finding.severity] = summary.get(finding.severity, 0) + 1
+    return summary
+
+
+def rule_summary(findings: list[Finding]) -> dict[str, int]:
+    summary: dict[str, int] = {}
+    for finding in findings:
+        summary[finding.rule_id] = summary.get(finding.rule_id, 0) + 1
+    return summary
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    lines = ["# Zod OpenAPI Contract Lint Report", ""]
+    lines.append(f"Scanned files: {report['scanned_files']}")
+    lines.append(f"Active rules: {report.get('active_rule_count', 'n/a')}")
+    lines.append(f"Findings: {report['finding_count']}")
+    if report["summary_by_severity"]:
+        lines.append("")
+        lines.append("## Summary by severity")
+        for severity, count in report["summary_by_severity"].items():
+            lines.append(f"- **{severity}**: {count}")
+    if report.get("summary_by_rule"):
+        lines.append("")
+        lines.append("## Summary by rule")
+        for rule_id, count in report["summary_by_rule"].items():
+            lines.append(f"- `{rule_id}`: {count}")
+    if report["findings"]:
+        lines.append("")
+        lines.append("## Findings")
+        for finding in report["findings"]:
+            lines.append(f"- **{finding['severity']}** `{finding['rule_id']}` in `{finding['file']}:{finding['line']}`")
+            lines.append(f"  - Signal: `{finding['signal']}`")
+            lines.append(f"  - Why: {finding['why']}")
+            lines.append(f"  - Fix: {finding['fix']}")
+    else:
+        lines.append("")
+        lines.append("No known contract drift signals found by the current rule set.")
+    lines.append("")
+    lines.append("## Notes")
+    for note in report["notes"]:
+        lines.append(f"- {note}")
+    return "\n".join(lines) + "\n"
+
+
+def should_fail(report: dict[str, Any], threshold: str) -> bool:
+    minimum = SEVERITY_ORDER[threshold]
+    return any(SEVERITY_ORDER.get(item["severity"], 0) >= minimum for item in report["findings"])
+
+
+def filter_findings_by_severity(findings: list[Finding], minimum_severity: str | None = None) -> list[Finding]:
+    if not minimum_severity:
+        return findings
+    minimum = SEVERITY_ORDER[minimum_severity]
+    return [finding for finding in findings if SEVERITY_ORDER.get(finding.severity, 0) >= minimum]
+
+
+def apply_report_filters(report: dict[str, Any], minimum_severity: str | None = None) -> dict[str, Any]:
+    if not minimum_severity:
+        return report
+    filtered = filter_findings_by_severity([Finding(**item) for item in report["findings"]], minimum_severity)
+    notes = list(report["notes"])
+    notes.append(f"Filtered findings below {minimum_severity} severity.")
+    return {
+        **report,
+        "finding_count": len(filtered),
+        "findings": [asdict(finding) for finding in filtered],
+        "summary_by_severity": severity_summary(filtered),
+        "summary_by_rule": rule_summary(filtered),
+        "notes": notes,
+    }
+
+
+def render_rule_inventory(rules: list[Rule], output_format: str = "markdown") -> str:
+    if output_format == "json":
+        return json.dumps({"rules": [asdict(rule) for rule in rules]}, indent=2) + "\n"
+    lines = ["# Zod OpenAPI Contract Lint rule inventory", ""]
+    for rule in rules:
+        lines.append(f"## `{rule.id}`")
+        lines.append("")
+        lines.append(f"- Severity: **{rule.severity}**")
+        lines.append(f"- Pattern: `{rule.pattern}`")
+        if rule.suppress_if_nearby:
+            lines.append("- Suppressed near: " + ", ".join(f"`{token}`" for token in rule.suppress_if_nearby))
+        lines.append(f"- Why: {rule.why}")
+        lines.append(f"- Fix: {rule.fix}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Scan Zod/OpenAPI contract drift risks.")
+    parser.add_argument("path", nargs="?", default=".", help="Project root or TypeScript file to scan")
+    parser.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    parser.add_argument("--output", "-o", help="Write report to a file instead of stdout")
+    parser.add_argument("--fail-on-severity", choices=["low", "medium", "high"], help="Exit 1 when findings at or above this severity are detected")
+    parser.add_argument("--min-severity", choices=["low", "medium", "high"], help="Only include findings at or above this severity in the report")
+    parser.add_argument("--only-rule", action="append", default=[], help="Run only this rule id; repeat for multiple rules")
+    parser.add_argument("--ignore-rule", action="append", default=[], help="Skip this rule id; repeat for multiple rules")
+    parser.add_argument("--list-rules", action="store_true", help="Print the active rule inventory and exit")
+    parser.add_argument("--rules", type=Path, default=DEFAULT_RULES)
+    args = parser.parse_args(argv)
+    try:
+        active_rules = filter_rules(load_rules(args.rules), only_rule=set(args.only_rule), ignore_rule=set(args.ignore_rule))
+        if args.list_rules:
+            print(render_rule_inventory(active_rules, args.format), end="")
+            return 0
+        report = scan(Path(args.path), args.rules, only_rule=set(args.only_rule), ignore_rule=set(args.ignore_rule))
+    except ValueError as exc:
+        parser.error(str(exc))
+    report = apply_report_filters(report, args.min_severity)
+    output = json.dumps(report, indent=2) if args.format == "json" else render_markdown(report)
+    if args.output:
+        Path(args.output).write_text(output + ("" if output.endswith("\n") else "\n"), encoding="utf-8")
+    else:
+        print(output, end="" if args.format == "markdown" else "\n")
+    if args.fail_on_severity and should_fail(report, args.fail_on_severity):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit/rules.json

@@ -0,0 +1,64 @@
+{
+  "rules": [
+    {
+      "id": "missing-openapi-metadata",
+      "severity": "high",
+      "pattern": "export\\s+const\\s+\\w+Schema\\s*=\\s*z\\.object\\(",
+      "why": "Exported Zod object schemas used as contracts often need OpenAPI metadata for stable docs and generated clients.",
+      "fix": "Add .openapi(...) metadata or .describe(...) fields, especially for public request/response schemas.",
+      "suppress_if_nearby": [".openapi(", ".describe("]
+    },
+    {
+      "id": "zod-any-unknown-contract",
+      "severity": "high",
+      "pattern": "z\\.(any|unknown)\\s*\\(",
+      "why": "z.any()/z.unknown() weakens generated OpenAPI schemas and client types.",
+      "fix": "Replace with explicit object/union/primitive schemas or document a deliberate escape hatch."
+    },
+    {
+      "id": "zod-date-serialization-review",
+      "severity": "medium",
+      "pattern": "z\\.date\\s*\\(",
+      "why": "z.date() is a runtime Date object while OpenAPI transports usually serialize dates as strings.",
+      "fix": "Use z.string().datetime()/date() for transport contracts, or document how the OpenAPI generator serializes Date values."
+    },
+    {
+      "id": "record-additional-properties-review",
+      "severity": "medium",
+      "pattern": "z\\.record\\s*\\(",
+      "why": "Map-like records can generate broad additionalProperties schemas that clients may handle inconsistently.",
+      "fix": "Review generated additionalProperties output and add examples/constraints where possible."
+    },
+    {
+      "id": "union-discriminator-review",
+      "severity": "medium",
+      "pattern": "z\\.union\\s*\\(",
+      "why": "Plain unions can produce ambiguous anyOf/oneOf output for generated clients.",
+      "fix": "Prefer discriminatedUnion when possible or add clear OpenAPI discriminator/description metadata.",
+      "suppress_if_nearby": ["discriminatedUnion", "discriminator"]
+    },
+    {
+      "id": "runtime-only-zod-effect",
+      "severity": "medium",
+      "pattern": "\\.(transform|refine|superRefine)\\s*\\(",
+      "why": "Runtime-only Zod effects may not be faithfully represented in OpenAPI output.",
+      "fix": "Keep transport contracts structural, and document runtime-only validation separately."
+    },
+    {
+      "id": "auth-route-missing-401-403-docs",
+      "severity": "high",
+      "pattern": "(requireAuth|withAuth|authMiddleware|bearerAuth|security)",
+      "why": "Authenticated routes should document 401/403 responses so clients can handle auth failures consistently.",
+      "fix": "Add explicit 401 and/or 403 response docs with a shared error schema.",
+      "suppress_if_nearby": ["401", "403"]
+    },
+    {
+      "id": "error-response-without-schema",
+      "severity": "medium",
+      "pattern": "status\\s*[:=]\\s*(400|401|403|404|409|422|500)|\\b(400|401|403|404|409|422|500)\\s*:",
+      "why": "Error responses without a documented schema cause inconsistent client error handling.",
+      "fix": "Reference a shared ErrorResponse schema/envelope in OpenAPI responses.",
+      "suppress_if_nearby": ["ErrorSchema", "ErrorResponse", "errorSchema"]
+    }
+  ]
+}

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+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.

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/zod_openapi_contract_lint_kit/__init__.py
+src/zod_openapi_contract_lint_kit/cli.py
+src/zod_openapi_contract_lint_kit/rules.json
+src/zod_openapi_contract_lint_kit.egg-info/PKG-INFO
+src/zod_openapi_contract_lint_kit.egg-info/SOURCES.txt
+src/zod_openapi_contract_lint_kit.egg-info/dependency_links.txt
+src/zod_openapi_contract_lint_kit.egg-info/entry_points.txt
+src/zod_openapi_contract_lint_kit.egg-info/top_level.txt
+tests/test_scanner.py

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+zod-openapi-contract-lint-kit = zod_openapi_contract_lint_kit.cli:main
+zod-openapi-lint = zod_openapi_contract_lint_kit.cli:main

zod_openapi_contract_lint_kit-0.1.1/src/zod_openapi_contract_lint_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+zod_openapi_contract_lint_kit

zod_openapi_contract_lint_kit-0.1.1/tests/test_scanner.py

@@ -0,0 +1,99 @@
+from pathlib import Path
+import importlib.util
+import json
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location("scanner", ROOT / "scanner.py")
+scanner = importlib.util.module_from_spec(spec)
+sys.modules["scanner"] = scanner
+spec.loader.exec_module(scanner)
+
+
+class TestScanner(unittest.TestCase):
+    def test_example_flags_contract_drift_risks(self):
+        report = scanner.scan(ROOT / "examples")
+        ids = {finding["rule_id"] for finding in report["findings"]}
+        self.assertIn("missing-openapi-metadata", ids)
+        self.assertIn("zod-any-unknown-contract", ids)
+        self.assertIn("zod-date-serialization-review", ids)
+        self.assertIn("record-additional-properties-review", ids)
+        self.assertIn("union-discriminator-review", ids)
+        self.assertIn("runtime-only-zod-effect", ids)
+        self.assertIn("auth-route-missing-401-403-docs", ids)
+        self.assertIn("error-response-without-schema", ids)
+        self.assertEqual(report["summary_by_rule"]["zod-date-serialization-review"], 1)
+
+    def test_nearby_openapi_metadata_suppresses_missing_metadata(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = Path(tmpdir) / "schema.ts"
+            path.write_text('import { z } from "zod";\nexport const UserSchema = z.object({ id: z.string() }).openapi("User");\n', encoding="utf-8")
+            report = scanner.scan(path)
+            ids = {finding["rule_id"] for finding in report["findings"]}
+            self.assertNotIn("missing-openapi-metadata", ids)
+
+    def test_markdown_contains_safety_note_and_rule_summary(self):
+        text = scanner.render_markdown(scanner.scan(ROOT / "examples"))
+        self.assertIn("Zod OpenAPI Contract Lint Report", text)
+        self.assertIn("Read-only static scan", text)
+        self.assertIn("Summary by rule", text)
+        self.assertIn("Active rules", text)
+
+    def test_output_json_and_fail_on_severity(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output = Path(tmpdir) / "report.json"
+            exit_code = scanner.main([str(ROOT / "examples"), "--format", "json", "--output", str(output), "--fail-on-severity", "high"])
+            self.assertEqual(exit_code, 1)
+            report = json.loads(output.read_text())
+            self.assertGreaterEqual(report["summary_by_severity"]["high"], 1)
+            self.assertIn("summary_by_rule", report)
+
+    def test_fail_on_severity_stays_zero_above_medium(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = Path(tmpdir) / "schema.ts"
+            path.write_text('import { z } from "zod";\nconst StartedAt = z.date();\n', encoding="utf-8")
+            self.assertEqual(scanner.main([str(path), "--fail-on-severity", "high"]), 0)
+            self.assertEqual(scanner.main([str(path), "--fail-on-severity", "medium"]), 1)
+
+    def test_only_rule_and_ignore_rule_filter_active_rules(self):
+        only_report = scanner.scan(ROOT / "examples", only_rule={"zod-date-serialization-review"})
+        self.assertEqual(only_report["active_rule_count"], 1)
+        self.assertEqual([f["rule_id"] for f in only_report["findings"]], ["zod-date-serialization-review"])
+
+        ignored_report = scanner.scan(ROOT / "examples", ignore_rule={"missing-openapi-metadata", "zod-any-unknown-contract", "auth-route-missing-401-403-docs"})
+        ids = {finding["rule_id"] for finding in ignored_report["findings"]}
+        self.assertNotIn("missing-openapi-metadata", ids)
+        self.assertNotIn("zod-any-unknown-contract", ids)
+        self.assertNotIn("auth-route-missing-401-403-docs", ids)
+        self.assertEqual(ignored_report["summary_by_severity"].get("high"), None)
+
+    def test_unknown_rule_is_cli_error(self):
+        with mock.patch("sys.stderr"):
+            with self.assertRaises(SystemExit):
+                scanner.main([str(ROOT / "examples"), "--only-rule", "missing-rule"])
+
+    def test_min_severity_filters_report_output(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output = Path(tmpdir) / "report.json"
+            exit_code = scanner.main([str(ROOT / "examples"), "--format", "json", "--output", str(output), "--min-severity", "high"])
+            self.assertEqual(exit_code, 0)
+            report = json.loads(output.read_text())
+            self.assertEqual(set(report["summary_by_severity"]), {"high"})
+            self.assertNotIn("zod-date-serialization-review", report["summary_by_rule"])
+            self.assertIn("Filtered findings below high severity.", report["notes"])
+
+    def test_list_rules_outputs_active_inventory(self):
+        rules = scanner.filter_rules(scanner.load_rules(), only_rule={"zod-date-serialization-review"})
+        text = scanner.render_rule_inventory(rules)
+        self.assertIn("zod-date-serialization-review", text)
+        self.assertIn("Severity", text)
+
+        data = json.loads(scanner.render_rule_inventory(rules, "json"))
+        self.assertEqual(data["rules"][0]["id"], "zod-date-serialization-review")
+
+
+if __name__ == "__main__":
+    unittest.main()