fastapi-breakgate 1.0.1__py3-none-any.whl

fastapi_contract/cli.py

@@ -0,0 +1,295 @@
+"""Typer CLI for fastapi-contract."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+
+from fastapi_contract.__version__ import __version__
+from fastapi_contract.check import run_check
+from fastapi_contract.comment import github_check_annotation_lines, render_text_summary
+from fastapi_contract.config import load_config
+from fastapi_contract.diff.classifier import diff_openapi
+from fastapi_contract.doctor import run_doctor
+from fastapi_contract.export import ExportError, export_openapi, write_snapshot
+from fastapi_contract.models import ExportMode
+
+app = typer.Typer(
+    name="fastapi-contract",
+    help="Production merge gate for FastAPI OpenAPI breaking changes.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+console = Console(stderr=True)
+out = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        out.print(__version__)
+        raise typer.Exit(0)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """fastapi-contract CLI."""
+
+
+@app.command("doctor")
+def doctor_cmd(
+    config: Path | None = typer.Option(None, "--config", "-c", help="Path to TOML config"),
+    app_path: str | None = typer.Option(None, "--app", help="module:attr FastAPI target"),
+    json_out: bool = typer.Option(False, "--json", help="Emit JSON"),
+) -> None:
+    """Diagnose OpenAPI export readiness."""
+    cfg = load_config(config, overrides={"app": app_path})
+    report = run_doctor(cfg)
+    if json_out:
+        payload = {
+            "ok": report.ok,
+            "checks": [
+                {
+                    "name": c.name,
+                    "ok": c.ok,
+                    "detail": c.detail,
+                    "hint": c.hint,
+                }
+                for c in report.checks
+            ],
+            "suggested_env": report.suggested_env,
+        }
+        out.print_json(data=payload)
+    else:
+        table = Table(title="fastapi-contract doctor")
+        table.add_column("Status")
+        table.add_column("Check")
+        table.add_column("Detail")
+        for check in report.checks:
+            table.add_row(
+                "[green]OK[/green]" if check.ok else "[red]FAIL[/red]",
+                check.name,
+                check.detail + (f"\nhint: {check.hint}" if check.hint else ""),
+            )
+        console.print(table)
+        console.print(
+            f"[bold]{'PASS' if report.ok else 'FAIL'}[/bold] — overall doctor status"
+        )
+    raise typer.Exit(0 if report.ok else 1)
+
+
+@app.command("export")
+def export_cmd(
+    output: Path = typer.Option(Path("openapi.json"), "--output", "-o"),
+    config: Path | None = typer.Option(None, "--config", "-c"),
+    app_path: str | None = typer.Option(None, "--app"),
+    export_mode: str | None = typer.Option(None, "--mode"),
+    app_factory: bool | None = typer.Option(None, "--factory/--no-factory"),
+) -> None:
+    """Export live (or snapshot) OpenAPI JSON."""
+    cfg = load_config(
+        config,
+        overrides={
+            "app": app_path,
+            "export_mode": export_mode,
+            "app_factory": app_factory,
+        },
+    )
+    try:
+        result = export_openapi(cfg)
+    except ExportError as exc:
+        console.print(f"[red]Export failed:[/red] {exc}")
+        raise typer.Exit(2) from exc
+    output.write_text(result.to_json(), encoding="utf-8")
+    for warning in result.warnings:
+        console.print(f"[yellow]warning:[/yellow] {warning}")
+    console.print(
+        f"[green]Wrote[/green] {output} via {result.strategy.value} "
+        f"({len(result.schema.get('paths', {}))} paths)"
+    )
+
+
+@app.command("snapshot")
+def snapshot_cmd(
+    config: Path | None = typer.Option(None, "--config", "-c"),
+    app_path: str | None = typer.Option(None, "--app"),
+    snapshot_path: Path | None = typer.Option(None, "--path"),
+    app_factory: bool | None = typer.Option(None, "--factory/--no-factory"),
+) -> None:
+    """Write/update committed OpenAPI snapshot from live export."""
+    cfg = load_config(
+        config,
+        overrides={
+            "app": app_path,
+            "app_factory": app_factory,
+            "export_mode": ExportMode.LIVE.value,
+        },
+    )
+    try:
+        result = export_openapi(cfg)
+    except ExportError as exc:
+        console.print(f"[red]Export failed:[/red] {exc}")
+        raise typer.Exit(2) from exc
+    path = snapshot_path or Path(cfg.snapshot_path)
+    write_snapshot(result.schema, path)
+    console.print(f"[green]Snapshot written[/green] {path}")
+
+
+@app.command("diff")
+def diff_cmd(
+    base_file: Path = typer.Option(..., "--base-file", help="Base OpenAPI JSON"),
+    candidate_file: Path | None = typer.Option(
+        None, "--candidate-file", help="Candidate OpenAPI JSON (default: live export)"
+    ),
+    config: Path | None = typer.Option(None, "--config", "-c"),
+    app_path: str | None = typer.Option(None, "--app"),
+    policy: str | None = typer.Option(None, "--policy"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """Diff two OpenAPI documents (or live app vs base file)."""
+    cfg = load_config(config, overrides={"app": app_path, "policy": policy})
+    base = json.loads(base_file.read_text(encoding="utf-8"))
+    if candidate_file is not None:
+        candidate = json.loads(candidate_file.read_text(encoding="utf-8"))
+    else:
+        try:
+            candidate = export_openapi(cfg).schema
+        except ExportError as exc:
+            console.print(f"[red]Export failed:[/red] {exc}")
+            raise typer.Exit(2) from exc
+    result = diff_openapi(base, candidate, policy=cfg.policy)
+    if json_out:
+        out.print_json(
+            data={
+                "engine": result.engine,
+                "breaking": [c.to_dict() for c in result.breaking],
+                "risky": [c.to_dict() for c in result.risky],
+                "safe": [c.to_dict() for c in result.safe],
+            }
+        )
+    else:
+        console.print(render_text_summary(result))
+        for change in result.changes:
+            color = {
+                "breaking": "red",
+                "risky": "yellow",
+                "safe": "green",
+            }[change.severity.value]
+            method = f"{change.method.upper()} " if change.method else ""
+            console.print(
+                f"[{color}]{change.severity.value}[/{color}] "
+                f"{method}{change.path} — {change.message}"
+            )
+    raise typer.Exit(1 if result.breaking else 0)
+
+
+@app.command("check")
+def check_cmd(
+    config: Path | None = typer.Option(None, "--config", "-c"),
+    app_path: str | None = typer.Option(None, "--app"),
+    base_file: Path | None = typer.Option(None, "--base-file"),
+    policy: str | None = typer.Option(None, "--policy"),
+    fail_on: str | None = typer.Option(None, "--fail-on"),
+    pr_title: str | None = typer.Option(
+        None, "--pr-title", help="PR title for intentional protocol"
+    ),
+    pr_labels: str | None = typer.Option(
+        None, "--pr-labels", help="Comma-separated PR labels"
+    ),
+    report_file: Path | None = typer.Option(
+        None, "--report", help="Write markdown report to file"
+    ),
+    annotations: bool = typer.Option(
+        False, "--annotations", help="Emit GitHub Actions annotations"
+    ),
+    app_factory: bool | None = typer.Option(None, "--factory/--no-factory"),
+) -> None:
+    """CI entrypoint: fail on accidental breaking changes."""
+    # Allow GitHub Actions env defaults
+    if pr_title is None:
+        pr_title = os.environ.get("FAC_PR_TITLE") or os.environ.get("PR_TITLE")
+    labels_list: list[str] = []
+    raw_labels = pr_labels or os.environ.get("FAC_PR_LABELS") or os.environ.get("PR_LABELS")
+    if raw_labels:
+        labels_list = [part.strip() for part in raw_labels.split(",") if part.strip()]
+
+    cfg = load_config(
+        config,
+        overrides={
+            "app": app_path,
+            "policy": policy,
+            "fail_on": fail_on,
+            "app_factory": app_factory,
+        },
+    )
+    try:
+        result = run_check(
+            cfg,
+            base_schema_path=base_file,
+            pr_title=pr_title,
+            pr_labels=labels_list,
+        )
+    except (ExportError, FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]Check failed to run:[/red] {exc}")
+        raise typer.Exit(2) from exc
+
+    out.print(Markdown(result.report_markdown))
+    if report_file is not None:
+        report_file.write_text(result.report_markdown, encoding="utf-8")
+        console.print(f"Report written to {report_file}")
+    if annotations:
+        for line in github_check_annotation_lines(result.diff):
+            # annotations must go to stdout for GHA
+            sys.stdout.write(line + "\n")
+    for message in result.messages:
+        console.print(f"[dim]{message}[/dim]")
+    raise typer.Exit(result.exit_code)
+
+
+@app.command("comment")
+def comment_cmd(
+    config: Path | None = typer.Option(None, "--config", "-c"),
+    app_path: str | None = typer.Option(None, "--app"),
+    base_file: Path | None = typer.Option(None, "--base-file"),
+    policy: str | None = typer.Option(None, "--policy"),
+    output: Path = typer.Option(Path("contract-comment.md"), "--output", "-o"),
+    pr_title: str | None = typer.Option(None, "--pr-title"),
+    pr_labels: str | None = typer.Option(None, "--pr-labels"),
+) -> None:
+    """Render PR markdown comment without enforcing exit semantics beyond generation."""
+    labels_list = [
+        part.strip() for part in (pr_labels or "").split(",") if part.strip()
+    ]
+    cfg = load_config(config, overrides={"app": app_path, "policy": policy})
+    try:
+        result = run_check(
+            cfg,
+            base_schema_path=base_file,
+            pr_title=pr_title,
+            pr_labels=labels_list,
+        )
+    except (ExportError, FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]Comment generation failed:[/red] {exc}")
+        raise typer.Exit(2) from exc
+    output.write_text(result.report_markdown, encoding="utf-8")
+    console.print(f"[green]Wrote[/green] {output}")
+    raise typer.Exit(0)
+
+
+if __name__ == "__main__":
+    app()

fastapi_contract/comment.py

@@ -0,0 +1,101 @@
+"""Render human-readable PR / terminal reports."""
+
+from __future__ import annotations
+
+from fastapi_contract.diff.classifier import ChangeSeverity, DiffResult
+from fastapi_contract.intentional import IntentionalStatus, suggest_semver_bump
+
+
+def render_markdown_report(
+    diff: DiffResult,
+    *,
+    intentional: IntentionalStatus | None = None,
+    failed: bool = False,
+    title: str = "fastapi-contract report",
+) -> str:
+    breaking = diff.breaking
+    risky = diff.risky
+    safe = diff.safe
+    bump = suggest_semver_bump(bool(breaking), bool(safe or risky))
+
+    status = "FAILED" if failed else "PASSED"
+    lines = [
+        f"## {title}",
+        "",
+        f"**Status:** {status}  ",
+        f"**Engine:** `{diff.engine}`  ",
+        f"**Paths:** base={diff.base_paths}, candidate={diff.candidate_paths}  ",
+        f"**Suggested SemVer bump:** `{bump}`",
+        "",
+        "| Severity | Count |",
+        "|----------|------:|",
+        f"| Breaking | {len(breaking)} |",
+        f"| Risky | {len(risky)} |",
+        f"| Safe | {len(safe)} |",
+        "",
+    ]
+
+    def section(name: str, items: list) -> None:
+        if not items:
+            return
+        lines.append(f"### {name}")
+        lines.append("")
+        for change in items:
+            method = f"{change.method.upper()} " if change.method else ""
+            lines.append(
+                f"- **{change.severity.value}** `{method}{change.path}` — {change.message}"
+            )
+        lines.append("")
+
+    section("Breaking changes", breaking)
+    section("Risky changes", risky)
+    section("Safe / additive changes", safe)
+
+    if intentional is not None:
+        lines.append("### Intentional break protocol")
+        lines.append("")
+        if intentional.allowed:
+            lines.append("Protocol **satisfied** — treat as reviewed intentional break.")
+        else:
+            lines.append("Protocol **not satisfied**:")
+            for reason in intentional.reasons:
+                lines.append(f"- {reason}")
+        lines.append("")
+
+    lines.append("### Next steps")
+    lines.append("")
+    if breaking and (intentional is None or not intentional.allowed):
+        lines.append(
+            "1. Revert accidental breaks, **or** complete the intentional protocol "
+            "(label/title marker + changelog `### Breaking` bullets)."
+        )
+        lines.append(
+            "2. Regenerate frontend clients if applicable "
+            "(`openapi-typescript`, hey-api, etc.)."
+        )
+    elif breaking and intentional and intentional.allowed:
+        lines.append("1. Confirm consumers are notified / versioned.")
+        lines.append("2. Regenerate generated clients and bump major version.")
+    else:
+        lines.append("1. No accidental breaking changes detected.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_text_summary(diff: DiffResult) -> str:
+    return (
+        f"{len(diff.breaking)} breaking, {len(diff.risky)} risky, "
+        f"{len(diff.safe)} safe ({diff.engine})"
+    )
+
+
+def github_check_annotation_lines(diff: DiffResult) -> list[str]:
+    """Simple annotation-style lines for CI logs."""
+    lines: list[str] = []
+    for change in diff.changes:
+        if change.severity == ChangeSeverity.SAFE:
+            continue
+        level = "error" if change.severity == ChangeSeverity.BREAKING else "warning"
+        method = f"{change.method.upper()} " if change.method else ""
+        lines.append(f"::{level} title=fastapi-contract::{method}{change.path}: {change.message}")
+    return lines

fastapi_contract/config.py

@@ -0,0 +1,161 @@
+"""Configuration loading from pyproject.toml / fastapi-contract.toml / CLI."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from fastapi_contract.models import ExportMode, FailOn, PolicyName
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass(frozen=True)
+class ContractConfig:
+    app: str = "main:app"
+    app_factory: bool = False
+    base_ref: str = "origin/main"
+    fail_on: FailOn = FailOn.BREAKING
+    policy: PolicyName = PolicyName.ADDITIVE_FRIENDLY
+    intentional_label: str = "breaking-change"
+    intentional_title_marker: str = "[breaking-change]"
+    changelog_path: str = "CHANGELOG.md"
+    changelog_required_heading: str = "### Breaking"
+    snapshot_path: str = "openapi.snapshot.json"
+    export_mode: ExportMode = ExportMode.AUTO
+    stub_env_file: str | None = ".env.contract"
+    skip_lifespan: bool = True
+    extra_env: dict[str, str] = field(default_factory=dict)
+    oasdiff_bin: str | None = None
+    prefer_oasdiff: bool = False
+
+    def with_overrides(self, **kwargs: Any) -> ContractConfig:
+        cleaned = {k: v for k, v in kwargs.items() if v is not None}
+        if "fail_on" in cleaned and not isinstance(cleaned["fail_on"], FailOn):
+            cleaned["fail_on"] = FailOn(str(cleaned["fail_on"]))
+        if "policy" in cleaned and not isinstance(cleaned["policy"], PolicyName):
+            cleaned["policy"] = PolicyName(str(cleaned["policy"]))
+        if "export_mode" in cleaned and not isinstance(cleaned["export_mode"], ExportMode):
+            cleaned["export_mode"] = ExportMode(str(cleaned["export_mode"]))
+        if "app_factory" in cleaned:
+            cleaned["app_factory"] = _as_bool(cleaned["app_factory"], self.app_factory)
+        if "skip_lifespan" in cleaned:
+            cleaned["skip_lifespan"] = _as_bool(cleaned["skip_lifespan"], self.skip_lifespan)
+        if "prefer_oasdiff" in cleaned:
+            cleaned["prefer_oasdiff"] = _as_bool(cleaned["prefer_oasdiff"], self.prefer_oasdiff)
+        return replace(self, **cleaned)
+
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in _TRUE:
+            return True
+        if lowered in _FALSE:
+            return False
+    return bool(value)
+
+
+def _as_enum(enum_cls: type[Any], value: Any, default: Any) -> Any:
+    if value is None:
+        return default
+    if isinstance(value, enum_cls):
+        return value
+    return enum_cls(str(value))
+
+
+def _find_config_file(start: Path | None = None) -> Path | None:
+    cwd = (start or Path.cwd()).resolve()
+    for directory in [cwd, *cwd.parents]:
+        for name in ("fastapi-contract.toml", "pyproject.toml"):
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+        if (directory / ".git").exists():
+            break
+    return None
+
+
+def _section_from_toml(path: Path) -> dict[str, Any]:
+    raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    if path.name == "fastapi-contract.toml":
+        return dict(raw.get("tool", {}).get("fastapi_contract", raw.get("fastapi_contract", raw)))
+    tool = raw.get("tool", {})
+    section = tool.get("fastapi_contract") or tool.get("fastapi-contract")
+    return dict(section or {})
+
+
+def load_config(
+    path: Path | None = None,
+    *,
+    overrides: dict[str, Any] | None = None,
+) -> ContractConfig:
+    """Load config from TOML, then apply optional CLI overrides."""
+    cfg = ContractConfig()
+    config_path = path or _find_config_file()
+    data: dict[str, Any] = {}
+    if config_path is not None:
+        data = _section_from_toml(config_path)
+
+    if data:
+        extra_env = data.get("extra_env") or data.get("env") or {}
+        if not isinstance(extra_env, dict):
+            extra_env = {}
+        cfg = ContractConfig(
+            app=str(data.get("app", cfg.app)),
+            app_factory=_as_bool(data.get("app_factory"), cfg.app_factory),
+            base_ref=str(data.get("base_ref", cfg.base_ref)),
+            fail_on=_as_enum(FailOn, data.get("fail_on"), cfg.fail_on),
+            policy=_as_enum(PolicyName, data.get("policy"), cfg.policy),
+            intentional_label=str(data.get("intentional_label", cfg.intentional_label)),
+            intentional_title_marker=str(
+                data.get("intentional_title_marker", cfg.intentional_title_marker)
+            ),
+            changelog_path=str(data.get("changelog_path", cfg.changelog_path)),
+            changelog_required_heading=str(
+                data.get("changelog_required_heading", cfg.changelog_required_heading)
+            ),
+            snapshot_path=str(data.get("snapshot_path", cfg.snapshot_path)),
+            export_mode=_as_enum(ExportMode, data.get("export_mode"), cfg.export_mode),
+            stub_env_file=(
+                None
+                if data.get("stub_env_file") in (None, "", False)
+                else str(data.get("stub_env_file", cfg.stub_env_file))
+            ),
+            skip_lifespan=_as_bool(data.get("skip_lifespan"), cfg.skip_lifespan),
+            extra_env={str(k): str(v) for k, v in extra_env.items()},
+            oasdiff_bin=(
+                str(data["oasdiff_bin"]) if data.get("oasdiff_bin") else cfg.oasdiff_bin
+            ),
+            prefer_oasdiff=_as_bool(data.get("prefer_oasdiff"), cfg.prefer_oasdiff),
+        )
+
+    if overrides:
+        mapped = dict(overrides)
+        if "fail_on" in mapped and mapped["fail_on"] is not None:
+            mapped["fail_on"] = _as_enum(FailOn, mapped["fail_on"], cfg.fail_on)
+        if "policy" in mapped and mapped["policy"] is not None:
+            mapped["policy"] = _as_enum(PolicyName, mapped["policy"], cfg.policy)
+        if "export_mode" in mapped and mapped["export_mode"] is not None:
+            mapped["export_mode"] = _as_enum(ExportMode, mapped["export_mode"], cfg.export_mode)
+        if "app_factory" in mapped and mapped["app_factory"] is not None:
+            mapped["app_factory"] = _as_bool(mapped["app_factory"], cfg.app_factory)
+        if "skip_lifespan" in mapped and mapped["skip_lifespan"] is not None:
+            mapped["skip_lifespan"] = _as_bool(mapped["skip_lifespan"], cfg.skip_lifespan)
+        if "prefer_oasdiff" in mapped and mapped["prefer_oasdiff"] is not None:
+            mapped["prefer_oasdiff"] = _as_bool(mapped["prefer_oasdiff"], cfg.prefer_oasdiff)
+        cfg = cfg.with_overrides(**mapped)
+    return cfg

fastapi_contract/diff/__init__.py

@@ -0,0 +1,5 @@
+"""OpenAPI diff and policy classification."""
+
+from fastapi_contract.diff.classifier import Change, ChangeSeverity, DiffResult, diff_openapi
+
+__all__ = ["Change", "ChangeSeverity", "DiffResult", "diff_openapi"]