specshift 1.0.0__py3-none-any.whl

specshift/git_utils.py

@@ -0,0 +1,82 @@
+"""Helper functions for reading file content across git revisions."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from specshift.spec_loader import SpecLoadError, parse_spec_text
+
+
+class GitError(Exception):
+    """Raised when a git command fails."""
+
+
+def _run_git(args: list[str], cwd: str | None = None) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git command not found. Make sure git is installed.") from exc
+    except subprocess.CalledProcessError as exc:
+        raise GitError(f"git command failed: {exc.stderr.strip()}") from exc
+
+    return result.stdout
+
+
+def is_git_repo(path: str = ".") -> bool:
+    try:
+        _run_git(["rev-parse", "--is-inside-work-tree"], cwd=path)
+        return True
+    except GitError:
+        return False
+
+
+def load_spec_from_git(file_path: str, ref: str, repo_path: str = ".") -> dict:
+    """
+    Reads the content of a file at a given git reference (e.g. 'main',
+    'HEAD~1', a tag, or a commit hash) and parses it as a specification.
+    """
+    relative_path = Path(file_path)
+    try:
+        # The command may be invoked from outside the repo root, so
+        # normalize the path relative to the repository root.
+        toplevel = _run_git(["rev-parse", "--show-toplevel"], cwd=repo_path).strip()
+        repo_root = Path(toplevel)
+        abs_target = (Path(repo_path).resolve() / relative_path).resolve()
+        rel_to_root = abs_target.relative_to(repo_root)
+        git_path = str(rel_to_root).replace("\\", "/")
+    except (GitError, ValueError):
+        git_path = str(relative_path).replace("\\", "/")
+
+    try:
+        content = _run_git(["show", f"{ref}:{git_path}"], cwd=repo_path)
+    except GitError as exc:
+        raise GitError(
+            f"Could not read '{ref}:{git_path}'. Make sure the file path and "
+            f"reference are correct. Details: {exc}"
+        ) from exc
+
+    try:
+        return parse_spec_text(content, hint=f"{ref}:{git_path}")
+    except SpecLoadError as exc:
+        raise GitError(str(exc)) from exc
+
+
+def current_branch(repo_path: str = ".") -> str:
+    try:
+        return _run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=repo_path).strip()
+    except GitError:
+        return "unknown"
+
+
+def short_sha(ref: str = "HEAD", repo_path: str = ".") -> str:
+    try:
+        return _run_git(["rev-parse", "--short", ref], cwd=repo_path).strip()
+    except GitError:
+        return ref

specshift/models.py

@@ -0,0 +1,110 @@
+"""Data models representing diff results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class Severity(str, Enum):
+    """Severity level of a detected change."""
+
+    BREAKING = "breaking"
+    WARNING = "warning"
+    INFO = "info"
+
+    @property
+    def rank(self) -> int:
+        return {"breaking": 2, "warning": 1, "info": 0}[self.value]
+
+    @property
+    def icon(self) -> str:
+        return {"breaking": "[BREAKING]", "warning": "[WARNING]", "info": "[INFO]"}[self.value]
+
+
+class ChangeType(str, Enum):
+    """The type of change that occurred."""
+
+    ADDED = "added"
+    REMOVED = "removed"
+    MODIFIED = "modified"
+
+
+@dataclass
+class Change:
+    """Represents a single change between the old and new specification."""
+
+    severity: Severity
+    change_type: ChangeType
+    location: str
+    message: str
+    old_value: Optional[Any] = None
+    new_value: Optional[Any] = None
+    category: str = "general"
+
+    def to_dict(self) -> dict:
+        return {
+            "severity": self.severity.value,
+            "change_type": self.change_type.value,
+            "location": self.location,
+            "message": self.message,
+            "old_value": _safe_repr(self.old_value),
+            "new_value": _safe_repr(self.new_value),
+            "category": self.category,
+        }
+
+
+def _safe_repr(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple, set)):
+        return [str(v) for v in value]
+    return str(value)
+
+
+@dataclass
+class DiffResult:
+    """The aggregated result of all changes between two specifications."""
+
+    changes: list[Change] = field(default_factory=list)
+    old_title: str = ""
+    new_title: str = ""
+    old_version: str = ""
+    new_version: str = ""
+
+    def add(self, change: Change) -> None:
+        self.changes.append(change)
+
+    @property
+    def breaking_changes(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == Severity.BREAKING]
+
+    @property
+    def warnings(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == Severity.WARNING]
+
+    @property
+    def info_changes(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == Severity.INFO]
+
+    @property
+    def has_breaking_changes(self) -> bool:
+        return len(self.breaking_changes) > 0
+
+    @property
+    def is_empty(self) -> bool:
+        return len(self.changes) == 0
+
+    def sorted_changes(self) -> list[Change]:
+        return sorted(self.changes, key=lambda c: (-c.severity.rank, c.location))
+
+    def summary_counts(self) -> dict:
+        return {
+            "breaking": len(self.breaking_changes),
+            "warning": len(self.warnings),
+            "info": len(self.info_changes),
+            "total": len(self.changes),
+        }

specshift/notifier.py

@@ -0,0 +1,66 @@
+"""Sends diff results via Slack or Discord webhooks."""
+
+from __future__ import annotations
+
+import requests
+
+from specshift.models import DiffResult
+
+
+class NotifyError(Exception):
+    """Raised when a notification could not be sent."""
+
+
+def notify_slack(webhook_url: str, result: DiffResult, ai_summary: str | None = None, timeout: int = 15) -> None:
+    counts = result.summary_counts()
+    color = "#e01e5a" if result.has_breaking_changes else ("#ecb22e" if counts["warning"] else "#2eb67d")
+
+    title = f"{result.old_title or 'API'} contract change: {result.old_version} -> {result.new_version}"
+    summary_line = f"{counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} info changes"
+
+    fields = []
+    for change in result.breaking_changes[:10]:
+        fields.append({"title": change.location, "value": change.message, "short": False})
+
+    payload = {
+        "attachments": [
+            {
+                "color": color,
+                "title": title,
+                "text": summary_line + ("\n\n" + ai_summary if ai_summary else ""),
+                "fields": fields,
+            }
+        ]
+    }
+
+    _post(webhook_url, payload, timeout)
+
+
+def notify_discord(webhook_url: str, result: DiffResult, ai_summary: str | None = None, timeout: int = 15) -> None:
+    counts = result.summary_counts()
+    color = 0xE01E5A if result.has_breaking_changes else (0xECB22E if counts["warning"] else 0x2EB67D)
+
+    title = f"{result.old_title or 'API'} contract change"
+    description = (
+        f"**{result.old_version} -> {result.new_version}**\n"
+        f"{counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} info changes found."
+    )
+    if ai_summary:
+        description += f"\n\n{ai_summary[:1500]}"
+
+    fields = [
+        {"name": change.location[:256], "value": change.message[:1024], "inline": False}
+        for change in result.breaking_changes[:10]
+    ]
+
+    payload = {"embeds": [{"title": title, "description": description[:4000], "color": color, "fields": fields}]}
+
+    _post(webhook_url, payload, timeout)
+
+
+def _post(webhook_url: str, payload: dict, timeout: int) -> None:
+    try:
+        response = requests.post(webhook_url, json=payload, timeout=timeout)
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise NotifyError(f"Failed to send webhook: {exc}") from exc

specshift/reporter.py

@@ -0,0 +1,167 @@
+"""Renders a DiffResult into console, Markdown, and JSON reports."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from specshift.models import DiffResult, Severity
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+    from rich.text import Text
+
+    _HAS_RICH = True
+except ImportError:  # fall back to plain text if rich is not installed
+    _HAS_RICH = False
+
+_SEVERITY_COLORS = {
+    Severity.BREAKING: "bold red",
+    Severity.WARNING: "bold yellow",
+    Severity.INFO: "cyan",
+}
+
+
+def print_console_report(result: DiffResult, verbose: bool = True) -> None:
+    """Prints the result to the terminal with colors. Falls back to plain text without rich."""
+    if _HAS_RICH:
+        _print_rich_report(result, verbose=verbose)
+    else:
+        print(render_plain_text_report(result, verbose=verbose))
+
+
+def _print_rich_report(result: DiffResult, verbose: bool) -> None:
+    console = Console()
+    counts = result.summary_counts()
+
+    header = f"{result.old_title or 'Specification'} : {result.old_version} -> {result.new_version}"
+    console.print(f"\n[bold]{header}[/bold]")
+    console.print(
+        f"[bold red]{counts['breaking']} breaking[/bold red], "
+        f"[bold yellow]{counts['warning']} warning[/bold yellow], "
+        f"[cyan]{counts['info']} info[/cyan] changes found.\n"
+    )
+
+    if result.is_empty:
+        console.print("[green]No differences found between the two specifications.[/green]")
+        return
+
+    changes = result.sorted_changes() if verbose else result.breaking_changes + result.warnings
+
+    table = Table(show_lines=False, expand=True)
+    table.add_column("Severity", width=10)
+    table.add_column("Location", ratio=1)
+    table.add_column("Description", ratio=2)
+
+    for change in changes:
+        color = _SEVERITY_COLORS.get(change.severity, "white")
+        table.add_row(
+            Text(change.severity.value.upper(), style=color),
+            change.location,
+            change.message,
+        )
+
+    console.print(table)
+
+    if result.has_breaking_changes:
+        console.print(
+            f"\n[bold red]Result: {counts['breaking']} breaking change(s) make this "
+            "specification update risky for consumers.[/bold red]"
+        )
+    else:
+        console.print("\n[bold green]Result: no breaking changes found.[/bold green]")
+
+
+def render_plain_text_report(result: DiffResult, verbose: bool = True) -> str:
+    lines: list[str] = []
+    counts = result.summary_counts()
+
+    lines.append(f"{result.old_title or 'Specification'} : {result.old_version} -> {result.new_version}")
+    lines.append(
+        f"{counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} info changes found."
+    )
+    lines.append("")
+
+    if result.is_empty:
+        lines.append("No differences found between the two specifications.")
+        return "\n".join(lines)
+
+    changes = result.sorted_changes() if verbose else result.breaking_changes + result.warnings
+
+    for change in changes:
+        lines.append(f"{change.severity.icon} {change.location} :: {change.message}")
+
+    lines.append("")
+    if result.has_breaking_changes:
+        lines.append(
+            f"Result: {counts['breaking']} breaking change(s) make this update risky."
+        )
+    else:
+        lines.append("Result: no breaking changes found.")
+
+    return "\n".join(lines)
+
+
+def render_markdown_report(result: DiffResult, ai_summary: str | None = None) -> str:
+    counts = result.summary_counts()
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    lines: list[str] = []
+    lines.append(f"# API Contract Change Report")
+    lines.append("")
+    lines.append(f"**Source:** {result.old_title or 'API'} ({result.old_version} -> {result.new_version})")
+    lines.append(f"**Generated at:** {timestamp}")
+    lines.append("")
+
+    if result.has_breaking_changes:
+        lines.append(f"## Summary: {counts['breaking']} breaking change(s) found")
+    else:
+        lines.append("## Summary: no breaking changes found")
+
+    lines.append("")
+    lines.append(f"| Severity | Count |")
+    lines.append(f"|---|---|")
+    lines.append(f"| Breaking | {counts['breaking']} |")
+    lines.append(f"| Warning | {counts['warning']} |")
+    lines.append(f"| Info | {counts['info']} |")
+    lines.append("")
+
+    if ai_summary:
+        lines.append("## AI Summary")
+        lines.append("")
+        lines.append(ai_summary)
+        lines.append("")
+
+    for severity, title in (
+        (Severity.BREAKING, "Breaking Changes"),
+        (Severity.WARNING, "Warnings"),
+        (Severity.INFO, "Informational Changes"),
+    ):
+        changes = [c for c in result.sorted_changes() if c.severity == severity]
+        if not changes:
+            continue
+        lines.append(f"## {title}")
+        lines.append("")
+        for change in changes:
+            lines.append(f"- **{change.location}**: {change.message}")
+        lines.append("")
+
+    if result.is_empty:
+        lines.append("No differences were found between the two specifications.")
+
+    return "\n".join(lines)
+
+
+def render_json_report(result: DiffResult, ai_summary: str | None = None) -> str:
+    payload = {
+        "old_title": result.old_title,
+        "new_title": result.new_title,
+        "old_version": result.old_version,
+        "new_version": result.new_version,
+        "summary": result.summary_counts(),
+        "has_breaking_changes": result.has_breaking_changes,
+        "ai_summary": ai_summary,
+        "changes": [c.to_dict() for c in result.sorted_changes()],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)

specshift/spec_loader.py

@@ -0,0 +1,122 @@
+"""Loads an OpenAPI/Swagger specification from a file, URL, or raw text."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import requests
+import yaml
+
+
+class SpecLoadError(Exception):
+    """Raised when a specification cannot be loaded."""
+
+
+def _parse_text(text: str, hint: str = "") -> dict:
+    """Tries to parse text as JSON first, then falls back to YAML."""
+    stripped = text.strip()
+    if not stripped:
+        raise SpecLoadError(f"Empty content: {hint}")
+
+    if stripped.startswith("{") or stripped.startswith("["):
+        try:
+            return json.loads(stripped)
+        except json.JSONDecodeError:
+            pass
+
+    try:
+        data = yaml.safe_load(stripped)
+    except yaml.YAMLError as exc:
+        raise SpecLoadError(f"YAML/JSON parsing error ({hint}): {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise SpecLoadError(f"Specification is not an object/mapping: {hint}")
+
+    return data
+
+
+def parse_spec_text(text: str, hint: str = "") -> dict:
+    """Public entry point for parsing raw specification text."""
+    return _parse_text(text, hint=hint)
+
+
+def is_url(source: str) -> bool:
+    return bool(re.match(r"^https?://", source.strip(), re.IGNORECASE))
+
+
+def load_spec(source: str, timeout: int = 15) -> dict:
+    """
+    Loads an OpenAPI/Swagger specification.
+
+    source can be a URL, a file path, or raw JSON/YAML text.
+    """
+    source = source.strip()
+
+    if is_url(source):
+        return _load_from_url(source, timeout=timeout)
+
+    path = Path(source)
+    if path.exists() and path.is_file():
+        return _load_from_file(path)
+
+    if source.startswith("{") or "openapi:" in source or "swagger:" in source:
+        return _parse_text(source, hint="inline text")
+
+    raise SpecLoadError(
+        f"Source not found or not recognized: '{source}'. "
+        "Expected a file path, an http(s) URL, or raw JSON/YAML text."
+    )
+
+
+def _load_from_url(url: str, timeout: int = 15) -> dict:
+    try:
+        response = requests.get(url, timeout=timeout, headers={"Accept": "application/json, text/yaml, */*"})
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise SpecLoadError(f"Could not fetch URL '{url}': {exc}") from exc
+
+    return _parse_text(response.text, hint=url)
+
+
+def _load_from_file(path: Path) -> dict:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SpecLoadError(f"Could not read file '{path}': {exc}") from exc
+
+    return _parse_text(text, hint=str(path))
+
+
+def resolve_ref(ref: str, root_spec: dict) -> dict:
+    """
+    Resolves a JSON pointer reference such as '#/components/schemas/User'.
+    Returns an empty dict if it cannot be resolved.
+    """
+    if not ref.startswith("#/"):
+        return {}
+
+    parts = ref[2:].split("/")
+    node: Any = root_spec
+    for part in parts:
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, dict) and part in node:
+            node = node[part]
+        else:
+            return {}
+
+    return node if isinstance(node, dict) else {}
+
+
+def resolve_schema(schema: dict, root_spec: dict, _depth: int = 0) -> dict:
+    """Follows a schema's $ref field (if present) and returns the resolved schema."""
+    if _depth > 20 or not isinstance(schema, dict):
+        return schema if isinstance(schema, dict) else {}
+
+    if "$ref" in schema:
+        resolved = resolve_ref(schema["$ref"], root_spec)
+        return resolve_schema(resolved, root_spec, _depth + 1)
+
+    return schema