specshift 1.0.0__py3-none-any.whl

specshift/__init__.py

@@ -0,0 +1,20 @@
+"""
+specshift - a CLI tool that detects, classifies, and (optionally)
+summarizes changes in OpenAPI and Swagger contracts using AI.
+"""
+
+from specshift.differ import diff_specs
+from specshift.models import Change, Severity, ChangeType, DiffResult
+from specshift.spec_loader import load_spec
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "diff_specs",
+    "load_spec",
+    "Change",
+    "Severity",
+    "ChangeType",
+    "DiffResult",
+    "__version__",
+]

specshift/ai_summary.py

@@ -0,0 +1,201 @@
+"""
+Generates a natural-language summary from a DiffResult.
+
+This module is entirely optional. If neither GROQ_API_KEY nor GEMINI_API_KEY
+is set, a rule-based summary is produced without making any network calls.
+This keeps the project fully functional without depending on any paid
+service.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import requests
+
+from specshift.models import DiffResult, Severity
+
+GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions"
+GROQ_DEFAULT_MODEL = "llama-3.3-70b-versatile"
+
+GEMINI_API_URL_TEMPLATE = (
+    "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key}"
+)
+GEMINI_DEFAULT_MODEL = "gemini-2.0-flash"
+
+OPENAI_COMPATIBLE_URL_ENV = "SPECSHIFT_OPENAI_BASE_URL"
+
+
+class AISummaryError(Exception):
+    """Raised when the AI summary could not be generated."""
+
+
+def generate_summary(
+    result: DiffResult,
+    provider: Optional[str] = None,
+    model: Optional[str] = None,
+    timeout: int = 30,
+) -> str:
+    """
+    Returns a natural-language summary using a configured AI provider when
+    possible, otherwise falls back to a rule-based summary. Never raises an
+    exception that would halt execution; failures fall back silently.
+    """
+    prompt = _build_prompt(result)
+
+    chosen_provider = provider or _detect_provider()
+
+    if chosen_provider == "groq" and os.environ.get("GROQ_API_KEY"):
+        try:
+            return _call_groq(prompt, model or GROQ_DEFAULT_MODEL, timeout)
+        except AISummaryError:
+            pass
+
+    if chosen_provider == "gemini" and os.environ.get("GEMINI_API_KEY"):
+        try:
+            return _call_gemini(prompt, model or GEMINI_DEFAULT_MODEL, timeout)
+        except AISummaryError:
+            pass
+
+    if chosen_provider == "openai_compatible" and os.environ.get("SPECSHIFT_API_KEY"):
+        try:
+            return _call_openai_compatible(prompt, model, timeout)
+        except AISummaryError:
+            pass
+
+    return build_template_summary(result)
+
+
+def _detect_provider() -> Optional[str]:
+    if os.environ.get("GROQ_API_KEY"):
+        return "groq"
+    if os.environ.get("GEMINI_API_KEY"):
+        return "gemini"
+    if os.environ.get("SPECSHIFT_API_KEY") and os.environ.get(OPENAI_COMPATIBLE_URL_ENV):
+        return "openai_compatible"
+    return None
+
+
+def _build_prompt(result: DiffResult) -> str:
+    counts = result.summary_counts()
+    lines = [
+        "Below is a list of contract changes detected between two versions "
+        "of an API. Read this list and write a short, clear, professional "
+        "summary in English that a developer consuming this API would "
+        "understand. First highlight the most important breaking changes, "
+        "then anything worth paying attention to, and finally briefly "
+        "mention minor additions. Do not use lists or headings, write in "
+        "flowing paragraphs. Do not invent information, base the summary "
+        "only on the changes given.",
+        "",
+        f"Total: {counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} informational changes.",
+        "",
+    ]
+    for change in result.sorted_changes()[:60]:
+        lines.append(f"- [{change.severity.value}] {change.location}: {change.message}")
+
+    return "\n".join(lines)
+
+
+def _call_groq(prompt: str, model: str, timeout: int) -> str:
+    api_key = os.environ["GROQ_API_KEY"]
+    try:
+        response = requests.post(
+            GROQ_API_URL,
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json={
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "temperature": 0.3,
+                "max_tokens": 700,
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["choices"][0]["message"]["content"].strip()
+    except (requests.RequestException, KeyError, IndexError, ValueError) as exc:
+        raise AISummaryError(f"Groq request failed: {exc}") from exc
+
+
+def _call_gemini(prompt: str, model: str, timeout: int) -> str:
+    api_key = os.environ["GEMINI_API_KEY"]
+    url = GEMINI_API_URL_TEMPLATE.format(model=model, key=api_key)
+    try:
+        response = requests.post(
+            url,
+            json={
+                "contents": [{"parts": [{"text": prompt}]}],
+                "generationConfig": {"temperature": 0.3, "maxOutputTokens": 700},
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["candidates"][0]["content"]["parts"][0]["text"].strip()
+    except (requests.RequestException, KeyError, IndexError, ValueError) as exc:
+        raise AISummaryError(f"Gemini request failed: {exc}") from exc
+
+
+def _call_openai_compatible(prompt: str, model: Optional[str], timeout: int) -> str:
+    api_key = os.environ["SPECSHIFT_API_KEY"]
+    base_url = os.environ[OPENAI_COMPATIBLE_URL_ENV].rstrip("/")
+    try:
+        response = requests.post(
+            f"{base_url}/chat/completions",
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json={
+                "model": model or "default",
+                "messages": [{"role": "user", "content": prompt}],
+                "temperature": 0.3,
+                "max_tokens": 700,
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["choices"][0]["message"]["content"].strip()
+    except (requests.RequestException, KeyError, IndexError, ValueError) as exc:
+        raise AISummaryError(f"Custom endpoint request failed: {exc}") from exc
+
+
+def build_template_summary(result: DiffResult) -> str:
+    """A deterministic, rule-based summary that works without any API key."""
+    counts = result.summary_counts()
+
+    if result.is_empty:
+        return "No differences were detected between the two specifications."
+
+    parts: list[str] = []
+
+    if counts["breaking"] > 0:
+        top_breaking = result.breaking_changes[:5]
+        breaking_desc = "; ".join(f"{c.location} ({c.message.rstrip('.')})" for c in top_breaking)
+        extra = counts["breaking"] - len(top_breaking)
+        extra_note = f" and {extra} more breaking change(s)" if extra > 0 else ""
+        parts.append(
+            f"This update contains {counts['breaking']} breaking change(s) and may affect "
+            f"existing API consumers. Notably: {breaking_desc}{extra_note}. "
+            "Clients using this API should review these points before migrating."
+        )
+    else:
+        parts.append(
+            "This update does not contain any breaking changes, existing clients "
+            "can continue working without any additional action."
+        )
+
+    if counts["warning"] > 0:
+        parts.append(
+            f"There are also {counts['warning']} change(s) worth paying attention to; "
+            "these are not directly breaking but may cause behavioral differences "
+            "in some usage scenarios."
+        )
+
+    if counts["info"] > 0:
+        parts.append(
+            f"The remaining {counts['info']} change(s) are new features or improvements "
+            "and do not pose a risk to existing integrations."
+        )
+
+    return " ".join(parts)

specshift/cli.py

@@ -0,0 +1,256 @@
+"""SpecShift command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+from specshift import __version__
+from specshift.ai_summary import generate_summary
+from specshift.config import SpecShiftConfig, write_default_config
+from specshift.differ import diff_specs
+from specshift.git_utils import GitError, load_spec_from_git
+from specshift.models import DiffResult
+from specshift.notifier import NotifyError, notify_discord, notify_slack
+from specshift.reporter import print_console_report, render_json_report, render_markdown_report
+from specshift.spec_loader import SpecLoadError, load_spec
+
+CACHE_DIR = Path(".specshift_cache")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="specshift",
+        description="Detects and classifies changes in OpenAPI/Swagger specifications.",
+    )
+    parser.add_argument("--version", action="version", version=f"specshift {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    diff_parser = subparsers.add_parser("diff", help="Compare two specifications")
+    diff_parser.add_argument("old", help="Old specification: file path or URL")
+    diff_parser.add_argument("new", help="New specification: file path or URL")
+    _add_common_diff_args(diff_parser)
+
+    check_parser = subparsers.add_parser(
+        "check", help="For CI: compares the current specification against a git reference"
+    )
+    check_parser.add_argument("--spec", help="Path to the specification file (overrides config)")
+    check_parser.add_argument("--base-ref", help="Git reference to compare against (overrides config)")
+    check_parser.add_argument("--config", default=None, help="Path to the configuration file")
+    _add_common_diff_args(check_parser)
+
+    watch_parser = subparsers.add_parser(
+        "watch", help="Periodically watches a URL and sends a notification when it changes"
+    )
+    watch_parser.add_argument("url", help="URL of the OpenAPI specification to watch")
+    watch_parser.add_argument("--interval", type=int, default=300, help="Polling interval in seconds, default 300")
+    watch_parser.add_argument("--once", action="store_true", help="Check only once and exit")
+    watch_parser.add_argument("--slack-webhook", help="Slack webhook URL")
+    watch_parser.add_argument("--discord-webhook", help="Discord webhook URL")
+    watch_parser.add_argument("--ai", action="store_true", help="Add an AI summary to notifications")
+    watch_parser.add_argument("--ai-provider", choices=["groq", "gemini", "openai_compatible"], default=None)
+
+    init_parser = subparsers.add_parser("init", help="Creates a sample .specshift.yml configuration file")
+    init_parser.add_argument("--path", default=".specshift.yml", help="Path of the file to create")
+    init_parser.add_argument("--force", action="store_true", help="Overwrite an existing file")
+
+    return parser
+
+
+def _add_common_diff_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--format", choices=["console", "markdown", "json"], default="console", help="Output format"
+    )
+    parser.add_argument("--output", help="Write the output to a file (stdout if omitted)")
+    parser.add_argument("--ai", action="store_true", help="Generate a natural-language AI summary")
+    parser.add_argument(
+        "--ai-provider", choices=["groq", "gemini", "openai_compatible"], default=None, help="AI provider to use"
+    )
+    parser.add_argument("--ai-model", default=None, help="Name of the AI model to use")
+    parser.add_argument(
+        "--fail-on",
+        choices=["breaking", "warning", "none"],
+        default="breaking",
+        help="Determines at which severity level a non-zero exit code is returned",
+    )
+    parser.add_argument("--quiet", action="store_true", help="Only print the summary line")
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "diff":
+            return _run_diff(args)
+        if args.command == "check":
+            return _run_check(args)
+        if args.command == "watch":
+            return _run_watch(args)
+        if args.command == "init":
+            return _run_init(args)
+    except (SpecLoadError, GitError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("\nStopped.")
+        return 130
+
+    parser.print_help()
+    return 1
+
+
+def _run_diff(args: argparse.Namespace) -> int:
+    old_spec = load_spec(args.old)
+    new_spec = load_spec(args.new)
+    result = diff_specs(old_spec, new_spec)
+    return _emit_result(result, args)
+
+
+def _run_check(args: argparse.Namespace) -> int:
+    config = SpecShiftConfig.load(args.config)
+    spec_path = args.spec or config.spec_path
+    base_ref = args.base_ref or config.base_ref
+
+    old_spec = load_spec_from_git(spec_path, base_ref)
+    new_spec = load_spec(spec_path)
+
+    result = diff_specs(old_spec, new_spec)
+
+    if not args.ai_provider and config.ai_provider:
+        args.ai_provider = config.ai_provider
+    if not args.ai_model and config.ai_model:
+        args.ai_model = config.ai_model
+    if args.fail_on == "breaking" and config.fail_on != "breaking":
+        args.fail_on = config.fail_on
+
+    exit_code = _emit_result(result, args)
+
+    if config.slack_webhook or config.discord_webhook:
+        ai_summary = None
+        if args.ai:
+            ai_summary = generate_summary(result, provider=args.ai_provider, model=args.ai_model)
+        _send_notifications(result, config.slack_webhook, config.discord_webhook, ai_summary)
+
+    return exit_code
+
+
+def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
+    ai_summary = None
+    if args.ai:
+        ai_summary = generate_summary(result, provider=args.ai_provider, model=args.ai_model)
+
+    output_text: str
+    if args.format == "json":
+        output_text = render_json_report(result, ai_summary=ai_summary)
+    elif args.format == "markdown":
+        output_text = render_markdown_report(result, ai_summary=ai_summary)
+    else:
+        output_text = None  # console format is printed directly
+
+    if args.format == "console":
+        if args.output:
+            from specshift.reporter import render_plain_text_report
+
+            Path(args.output).write_text(render_plain_text_report(result), encoding="utf-8")
+            if not args.quiet:
+                print(f"Report written to: {args.output}")
+        else:
+            print_console_report(result, verbose=not args.quiet)
+            if ai_summary:
+                print(f"\nAI Summary:\n{ai_summary}")
+    else:
+        if args.output:
+            Path(args.output).write_text(output_text, encoding="utf-8")
+            print(f"Report written to: {args.output}")
+        else:
+            print(output_text)
+
+    return _exit_code_for(result, args.fail_on)
+
+
+def _exit_code_for(result: DiffResult, fail_on: str) -> int:
+    if fail_on == "none":
+        return 0
+    if fail_on == "warning":
+        return 1 if (result.has_breaking_changes or result.warnings) else 0
+    return 1 if result.has_breaking_changes else 0
+
+
+def _run_init(args: argparse.Namespace) -> int:
+    target = Path(args.path)
+    if target.exists() and not args.force:
+        print(f"'{target}' already exists. Use --force to overwrite it.", file=sys.stderr)
+        return 1
+
+    write_default_config(str(target))
+    print(f"Configuration file created: {target}")
+    return 0
+
+
+def _run_watch(args: argparse.Namespace) -> int:
+    CACHE_DIR.mkdir(exist_ok=True)
+    cache_key = hashlib.sha256(args.url.encode("utf-8")).hexdigest()[:16]
+    cache_file = CACHE_DIR / f"{cache_key}.json"
+
+    while True:
+        try:
+            current_spec = load_spec(args.url)
+        except SpecLoadError as exc:
+            print(f"Warning: could not fetch specification ({exc}), will retry.", file=sys.stderr)
+            if args.once:
+                return 2
+            time.sleep(args.interval)
+            continue
+
+        if cache_file.exists():
+            previous_spec = json.loads(cache_file.read_text(encoding="utf-8"))
+            result = diff_specs(previous_spec, current_spec)
+
+            if not result.is_empty:
+                print_console_report(result)
+                ai_summary = None
+                if args.ai:
+                    ai_summary = generate_summary(result, provider=args.ai_provider)
+
+                _send_notifications(result, args.slack_webhook, args.discord_webhook, ai_summary)
+            else:
+                print("No changes found.")
+        else:
+            print(f"Initial snapshot saved: {args.url}")
+
+        cache_file.write_text(json.dumps(current_spec), encoding="utf-8")
+
+        if args.once:
+            return 0
+
+        time.sleep(args.interval)
+
+
+def _send_notifications(
+    result: DiffResult, slack_webhook: Optional[str], discord_webhook: Optional[str], ai_summary: Optional[str]
+) -> None:
+    if result.is_empty:
+        return
+
+    if slack_webhook:
+        try:
+            notify_slack(slack_webhook, result, ai_summary=ai_summary)
+        except NotifyError as exc:
+            print(f"Failed to send Slack notification: {exc}", file=sys.stderr)
+
+    if discord_webhook:
+        try:
+            notify_discord(discord_webhook, result, ai_summary=ai_summary)
+        except NotifyError as exc:
+            print(f"Failed to send Discord notification: {exc}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

specshift/config.py

@@ -0,0 +1,79 @@
+"""Reads the '.specshift.yml' configuration file and merges it with defaults."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+DEFAULT_CONFIG_FILENAMES = (".specshift.yml", ".specshift.yaml")
+
+
+@dataclass
+class SpecShiftConfig:
+    spec_path: str = "openapi.yaml"
+    base_ref: str = "main"
+    fail_on: str = "breaking"  # breaking | warning | none
+    ai_provider: Optional[str] = None
+    ai_model: Optional[str] = None
+    slack_webhook: Optional[str] = None
+    discord_webhook: Optional[str] = None
+    ignore_paths: list = field(default_factory=list)
+
+    @classmethod
+    def load(cls, path: Optional[str] = None) -> "SpecShiftConfig":
+        candidates = [path] if path else list(DEFAULT_CONFIG_FILENAMES)
+
+        for candidate in candidates:
+            if not candidate:
+                continue
+            file_path = Path(candidate)
+            if file_path.exists():
+                data = yaml.safe_load(file_path.read_text(encoding="utf-8")) or {}
+                return cls._from_dict(data)
+
+        return cls()
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SpecShiftConfig":
+        return cls(
+            spec_path=data.get("spec_path", cls.spec_path),
+            base_ref=data.get("base_ref", cls.base_ref),
+            fail_on=data.get("fail_on", cls.fail_on),
+            ai_provider=data.get("ai_provider"),
+            ai_model=data.get("ai_model"),
+            slack_webhook=data.get("slack_webhook"),
+            discord_webhook=data.get("discord_webhook"),
+            ignore_paths=data.get("ignore_paths", []),
+        )
+
+
+def write_default_config(path: str = ".specshift.yml") -> None:
+    content = """\
+# specshift configuration file
+# For detailed documentation, see: https://github.com/Lethe044/specshift
+
+# Path to the OpenAPI/Swagger file to track (relative to the repo root)
+spec_path: openapi.yaml
+
+# The base git reference to compare against (branch, tag, or commit)
+base_ref: main
+
+# Determines at which severity level the CI build should fail: breaking | warning | none
+fail_on: breaking
+
+# Optional: AI provider for the natural-language summary (groq | gemini | openai_compatible)
+# The API key must be provided as an environment variable: GROQ_API_KEY or GEMINI_API_KEY
+# ai_provider: groq
+# ai_model: llama-3.3-70b-versatile
+
+# Optional: notification webhook URLs
+# slack_webhook: https://hooks.slack.com/services/...
+# discord_webhook: https://discord.com/api/webhooks/...
+
+# Path patterns to ignore during the diff (optional)
+ignore_paths: []
+"""
+    Path(path).write_text(content, encoding="utf-8")