commit-defender 0.1.0__py3-none-any.whl

commit_defender/__init__.py

@@ -0,0 +1,3 @@
+"""commit-defender: AI-powered git pre-commit code validator."""
+
+__version__ = "0.1.0"

commit_defender/ai_agent.py

@@ -0,0 +1,336 @@
+"""AI review agent using the Azure OpenAI SDK."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .config import AIReviewConfig, Config
+from .models import FileComment, LintFinding, ReviewResult
+from .settings import Settings, load_settings
+
+# ── Skill loader ──────────────────────────────────────────────────────────────
+
+def _load_skills(repo_path: Path) -> str:
+    """Read all SKILL.md files from <repo>/.commit-defender/*/SKILL.md.
+
+    Returns a formatted string ready to embed in the system prompt, or an
+    empty string if no skill directory exists.
+    """
+    skill_dir = repo_path / ".commit-defender"
+    if not skill_dir.is_dir():
+        return ""
+
+    sections: list[str] = []
+    for skill_md in sorted(skill_dir.glob("*/SKILL.md")):
+        category = skill_md.parent.name
+        content = skill_md.read_text(encoding="utf-8").strip()
+        sections.append(f"### [{category}]\n\n{content}")
+
+    if not sections:
+        return ""
+
+    return "## Active Review Skills\n\n" + "\n\n---\n\n".join(sections)
+
+
+# ── Behavior modifiers ────────────────────────────────────────────────────────
+
+_SEVERITY_PROMPTS: dict[str, str] = {
+    "severe": (
+        "Apply the absolute strictest possible review. Flag every deviation from "
+        "best practice, every style inconsistency, every potential issue — no matter "
+        "how minor. Zero tolerance."
+    ),
+    "rigorous": (
+        "Apply a strict review. Flag most issues including minor style and "
+        "best-practice deviations. Err on the side of raising concerns."
+    ),
+    "moderate": (
+        "Apply a balanced review. Flag meaningful issues and genuine best-practice "
+        "violations, but do not nitpick trivial style details."
+    ),
+    "generous": (
+        "Apply a lenient review. Only flag significant issues that carry clear risk "
+        "or that deviate substantially from convention. Allow minor imperfections."
+    ),
+    "lean": (
+        "Apply a minimal review. Only flag critical issues: those that will break "
+        "functionality, introduce security vulnerabilities, or cause data loss."
+    ),
+}
+
+_RICHNESS_PROMPTS: dict[str, str] = {
+    "colorful": (
+        "For each finding, provide an elaborate explanation: describe the problem in "
+        "depth, give a concrete example of the fix, explain the reasoning, and mention "
+        "any trade-offs. The summary may be up to 600 words."
+    ),
+    "chatty": (
+        "For each finding, provide helpful context and a suggested fix. "
+        "The summary should be thorough but focused, up to 400 words."
+    ),
+    "moderate": (
+        "Provide clear, concise explanations for each finding. "
+        "Keep the summary under 300 words."
+    ),
+    "simple": (
+        "Be brief. One or two sentences per finding. "
+        "Keep the summary under 150 words."
+    ),
+    "silent": (
+        "Output one-line descriptions only. No elaboration, no examples, no context. "
+        "Keep the summary under 60 words."
+    ),
+}
+
+_LOCALE_PROMPTS: dict[str, str] = {
+    "en": "Write all output in English.",
+    "ko": "모든 출력을 한국어로 작성하세요.",
+}
+
+_BASE_SYSTEM_PROMPT = """\
+You are commit-defender, an AI code reviewer integrated into a git pre-commit hook.
+
+Your job is to review the provided git diff and static analysis findings, then produce a
+concise, actionable review that helps the developer understand what needs to be fixed
+before committing.
+
+## Core guidelines
+- Be direct and specific. Reference file names and line numbers.
+- Group related issues together.
+- Distinguish between must-fix issues (errors) and suggestions (warnings/style).
+- Do not repeat every lint finding verbatim — synthesize patterns and highlight the most important ones.
+- If the code looks good overall, say so clearly.
+
+## Output format
+Respond ONLY with a valid JSON object matching this schema:
+{
+  "summary": "<narrative review, markdown allowed>",
+  "blocking": <true if the code should not be committed as-is, false otherwise>,
+  "file_comments": [
+    {
+      "file": "<path relative to repo root, e.g. src/main.py>",
+      "line": <1-based line number from the diff; 0 for a file-level comment>,
+      "comment": "<actionable suggestion, markdown allowed>"
+    }
+  ]
+}
+
+Rules for file_comments:
+- Only reference lines that appear in the provided diff.
+- Limit to at most 15 comments total.
+- Omit the array (or use []) if there is nothing specific to annotate.
+- Do not include anything outside the JSON object.
+"""
+
+
+def _build_system_prompt(
+    settings: Settings,
+    config: Config,
+    skills_text: str,
+    project_suffix: str,
+) -> str:
+    parts = [_BASE_SYSTEM_PROMPT]
+
+    if skills_text:
+        parts.append(skills_text)
+
+    # Priority: env var (set by VS Code / hook) > .commit-defender/settings.json > built-in default
+    rs = config.review_settings
+    severity = settings.cd_severity_level.strip().lower() or rs.severityLevel
+    richness = settings.cd_richness_level.strip().lower() or rs.richnessLevel
+    locale   = settings.cd_locale.strip().lower()          or rs.locale
+
+    modifier_lines = [
+        f"- Severity: {_SEVERITY_PROMPTS.get(severity, _SEVERITY_PROMPTS['moderate'])}",
+        f"- Detail level: {_RICHNESS_PROMPTS.get(richness, _RICHNESS_PROMPTS['moderate'])}",
+        f"- Language: {_LOCALE_PROMPTS.get(locale, _LOCALE_PROMPTS['en'])}",
+    ]
+    parts.append("## Review behavior\n\n" + "\n".join(modifier_lines))
+
+    if project_suffix:
+        parts.append(f"## Project-specific context\n\n{project_suffix}")
+
+    return "\n\n".join(parts)
+
+
+# ── JSON parsing ─────────────────────────────────────────────────────────────
+
+def _parse_json(raw: str) -> dict:
+    """Parse JSON from the model response, stripping markdown fences if present."""
+    # Direct parse — works when response_format=json_object was honoured
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+
+    # Extract the first {...} block (handles ```json ... ``` wrapping)
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group())
+        except json.JSONDecodeError:
+            pass
+
+    raise json.JSONDecodeError("No valid JSON found in response", raw, 0)
+
+
+# ── Agent ─────────────────────────────────────────────────────────────────────
+
+class AIReviewAgent:
+    def __init__(self, config: AIReviewConfig, full_config: Config | None = None) -> None:
+        self.config = config
+        self._full_config = full_config
+
+    def review(
+        self,
+        diff: str,
+        lint_findings: list[LintFinding],
+        repo_path: Path | None = None,
+    ) -> ReviewResult:
+        settings = load_settings()
+
+        if not self.config.enabled or settings.skip_ai:
+            return ReviewResult.skipped()
+
+        missing = settings.missing_azure_fields()
+        if missing:
+            return ReviewResult.error(
+                f"Missing credentials in ~/.commit-defender.env: {', '.join(missing)}"
+            )
+
+        try:
+            from openai import (
+                AzureOpenAI,
+                APIConnectionError,
+                APIStatusError,
+                APITimeoutError,
+                AuthenticationError,
+                RateLimitError,
+            )
+        except ImportError:
+            return ReviewResult.error("openai package not installed")
+
+        client = AzureOpenAI(
+            api_key=settings.azure_openai_api_key,
+            azure_endpoint=settings.azure_openai_endpoint,
+            api_version=settings.azure_openai_api_version,
+        )
+
+        deployment = settings.azure_openai_deployment or self.config.model
+
+        # Load skill guidelines from the repo's .commit-defender directory
+        skills_text = _load_skills(repo_path) if repo_path else ""
+
+        # Use the full Config for review_settings fallback; build a default if absent
+        from .config import Config as _Config
+        full_cfg = self._full_config or _Config()
+
+        system_content = _build_system_prompt(
+            settings,
+            full_cfg,
+            skills_text,
+            self.config.system_prompt_suffix,
+        )
+
+        findings_text = "\n".join(str(f) for f in lint_findings) if lint_findings else "None"
+
+        user_message = f"""\
+## Staged diff
+
+```diff
+{diff or '(no diff available)'}
+```
+
+## Static analysis findings
+
+```
+{findings_text}
+```
+
+Please review the above and respond with the JSON object as instructed.
+"""
+
+        try:
+            # Try with structured JSON mode first; fall back to plain text if the
+            # deployment does not support response_format (older API versions, fine-tuned
+            # models, or deployments with content-filtering restrictions).
+            try:
+                response = client.chat.completions.create(
+                    model=deployment,
+                    max_completion_tokens=self.config.max_tokens,
+                    response_format={"type": "json_object"},
+                    messages=[
+                        {"role": "system", "content": system_content},
+                        {"role": "user", "content": user_message},
+                    ],
+                )
+            except Exception as fmt_err:
+                # response_format not supported — retry without it
+                _fmt_msg = str(fmt_err).lower()
+                if not any(k in _fmt_msg for k in ("response_format", "json_object", "unsupported")):
+                    raise  # unrelated error — re-raise
+                response = client.chat.completions.create(
+                    model=deployment,
+                    max_completion_tokens=self.config.max_tokens,
+                    messages=[
+                        {"role": "system", "content": system_content},
+                        {"role": "user", "content": user_message},
+                    ],
+                )
+
+            raw = response.choices[0].message.content.strip()
+
+            # Extract JSON even when the model wraps it in markdown fences
+            data = _parse_json(raw)
+
+            file_comments = [
+                FileComment(
+                    file=fc["file"],
+                    line=int(fc.get("line", 0)),
+                    comment=fc["comment"],
+                )
+                for fc in data.get("file_comments", [])
+                if "file" in fc and "comment" in fc
+            ]
+            return ReviewResult(
+                summary=data.get("summary", "(no summary)"),
+                blocking=bool(data.get("blocking", False)),
+                raw_response=raw,
+                file_comments=file_comments,
+            )
+
+        except AuthenticationError as e:
+            return ReviewResult.error(
+                f"Authentication failed — check AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT.\n"
+                f"  Detail: {e.message}"
+            )
+        except APIConnectionError as e:
+            return ReviewResult.error(
+                f"Could not reach Azure OpenAI endpoint '{settings.azure_openai_endpoint}'.\n"
+                f"  Check your network and AZURE_OPENAI_ENDPOINT value.\n"
+                f"  Detail: {e}"
+            )
+        except APITimeoutError:
+            return ReviewResult.error(
+                "Request to Azure OpenAI timed out. "
+                "Check network connectivity or increase max_tokens."
+            )
+        except RateLimitError as e:
+            return ReviewResult.error(
+                f"Azure OpenAI rate limit exceeded — try again in a moment.\n"
+                f"  Detail: {e.message}"
+            )
+        except APIStatusError as e:
+            return ReviewResult.error(
+                f"Azure OpenAI returned HTTP {e.status_code}.\n"
+                f"  Detail: {e.message}"
+            )
+        except json.JSONDecodeError:
+            return ReviewResult.error(
+                f"Could not parse AI response as JSON.\n"
+                f"  Raw response (first 300 chars): {raw[:300] if 'raw' in dir() else '(none)'}"
+            )
+        except Exception as e:
+            return ReviewResult.error(f"Unexpected error: {type(e).__name__}: {e}")

commit_defender/config.py

@@ -0,0 +1,99 @@
+"""Configuration loader for commit-defender."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field
+
+AnalysisMode = Literal["hybrid", "ai-powered", "rule-based"]
+SeverityLevel = Literal["severe", "rigorous", "moderate", "generous", "lean"]
+RichnessLevel = Literal["colorful", "chatty", "moderate", "simple", "silent"]
+Locale = Literal["en", "ko"]
+
+
+class LinterConfig(BaseModel):
+    enabled: bool = True
+    tool: str = ""
+    args: list[str] = Field(default_factory=list)
+
+
+class AIReviewConfig(BaseModel):
+    enabled: bool = True
+    model: str = "gpt-5.1"
+    max_tokens: int = 1024
+    blocking: bool = False
+    system_prompt_suffix: str = ""
+
+
+class LinterMap(BaseModel):
+    python: LinterConfig = Field(default_factory=lambda: LinterConfig(tool="ruff"))
+    javascript: LinterConfig = Field(default_factory=lambda: LinterConfig(tool="eslint"))
+    typescript: LinterConfig = Field(default_factory=lambda: LinterConfig(tool="eslint"))
+    shell: LinterConfig = Field(default_factory=lambda: LinterConfig(tool="shellcheck"))
+    markdown: LinterConfig = Field(
+        default_factory=lambda: LinterConfig(enabled=False, tool="markdownlint")
+    )
+
+
+class ReviewSettings(BaseModel):
+    """Loaded from .commit-defender/settings.json; overridden by env vars."""
+    analysisMode: AnalysisMode = "hybrid"
+    severityLevel: SeverityLevel = "moderate"
+    richnessLevel: RichnessLevel = "moderate"
+    locale: Locale = "en"
+    excludePatterns: list[str] = Field(default_factory=list)
+
+
+class Config(BaseModel):
+    version: int = 1
+    blocking_severity: str = "error"
+    linters: LinterMap = Field(default_factory=LinterMap)
+    ai_review: AIReviewConfig = Field(default_factory=AIReviewConfig)
+    exclude: list[str] = Field(
+        default_factory=lambda: ["*.lock", "dist/**", "node_modules/**", "*.min.js"]
+    )
+    # Loaded from .commit-defender/settings.json; env vars take priority at runtime
+    review_settings: ReviewSettings = Field(default_factory=ReviewSettings)
+
+
+def _load_review_settings(repo_path: Path) -> ReviewSettings:
+    """Read .commit-defender/settings.json if present."""
+    settings_file = repo_path / ".commit-defender" / "settings.json"
+    if not settings_file.exists():
+        return ReviewSettings()
+    try:
+        raw: dict[str, Any] = json.loads(settings_file.read_text(encoding="utf-8"))
+        return ReviewSettings.model_validate(raw)
+    except Exception:
+        return ReviewSettings()
+
+
+def load_config(repo_path: Path | None = None) -> Config:
+    """Load config from commit-defender.yaml and .commit-defender/settings.json."""
+    config_path_env = os.environ.get("CD_CONFIG_PATH")
+
+    candidates: list[Path] = []
+    if config_path_env:
+        candidates.append(Path(config_path_env))
+    if repo_path:
+        candidates.append(repo_path / "commit-defender.yaml")
+    candidates.append(Path("/repo/commit-defender.yaml"))
+
+    cfg_dict: dict[str, Any] = {}
+    for candidate in candidates:
+        if candidate.exists():
+            cfg_dict = yaml.safe_load(candidate.read_text()) or {}
+            break
+
+    config = Config.model_validate(cfg_dict)
+
+    # Overlay review_settings from .commit-defender/settings.json
+    resolved_repo = repo_path or Path("/repo")
+    config.review_settings = _load_review_settings(resolved_repo)
+
+    return config

commit_defender/diff_extractor.py

@@ -0,0 +1,85 @@
+"""Extract git diffs for staged files."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+# Limit diff size sent to AI to avoid token overflow (~100K chars ≈ ~25K tokens)
+MAX_DIFF_CHARS = 80_000
+
+
+class DiffExtractor:
+    def __init__(self, repo_path: Path) -> None:
+        self.repo_path = repo_path
+
+    def get_full_diff(self, files: list[Path]) -> str:
+        """Return combined unified diff for all staged files."""
+        if not files:
+            return ""
+
+        rel_paths = [str(f.relative_to(self.repo_path)) for f in files]
+
+        # Handle initial commit: no HEAD yet
+        try:
+            result = self._run_git(["diff", "--cached", "--diff-filter=d", "--"] + rel_paths)
+        except subprocess.CalledProcessError:
+            # Fallback: diff against empty tree (first commit)
+            empty_tree = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+            result = self._run_git(["diff", "--cached", "--diff-filter=d", empty_tree, "--"] + rel_paths)
+
+        diff = result.stdout
+        if len(diff) > MAX_DIFF_CHARS:
+            diff = diff[:MAX_DIFF_CHARS] + "\n\n[... diff truncated for token limit ...]"
+        return diff
+
+    def get_file_diff(self, file: Path) -> str:
+        """Return unified diff for a single staged file."""
+        rel = str(file.relative_to(self.repo_path))
+        try:
+            result = self._run_git(["diff", "--cached", "--", rel])
+            return result.stdout
+        except subprocess.CalledProcessError:
+            return ""
+
+    def get_working_diff(self, files: list[Path]) -> str:
+        """Return diff of working-tree files vs HEAD (for on-demand analysis).
+
+        Falls back to full file content for untracked files.
+        """
+        if not files:
+            return ""
+
+        parts: list[str] = []
+        for f in files:
+            rel = str(f.relative_to(self.repo_path))
+            # Try staged+unstaged combined (HEAD vs working tree)
+            try:
+                result = self._run_git(["diff", "HEAD", "--diff-filter=d", "--", rel])
+                if result.stdout.strip():
+                    parts.append(result.stdout)
+                    continue
+            except subprocess.CalledProcessError:
+                pass
+
+            # Untracked / new file — show full content as an addition diff
+            try:
+                content = f.read_text(encoding="utf-8", errors="replace")
+                added = "\n".join(f"+{line}" for line in content.splitlines())
+                header = f"diff --git a/{rel} b/{rel}\nnew file mode 100644\n--- /dev/null\n+++ b/{rel}\n"
+                parts.append(header + added)
+            except OSError:
+                pass
+
+        diff = "\n".join(parts)
+        if len(diff) > MAX_DIFF_CHARS:
+            diff = diff[:MAX_DIFF_CHARS] + "\n\n[... diff truncated for token limit ...]"
+        return diff
+
+    def _run_git(self, args: list[str]) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(self.repo_path)] + args,
+            capture_output=True,
+            text=True,
+            check=True,
+        )

commit_defender/entrypoint.py

@@ -0,0 +1,126 @@
+"""Main entrypoint for commit-defender container."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+
+
+def run() -> int:
+    """Execute the full pre-commit validation pipeline. Returns exit code."""
+
+    # ── Early diagnostics — printed before any heavy imports ──────────────────
+    # These appear in the VS Code output channel so users can debug path issues.
+    cd_repo  = os.environ.get("CD_REPO_PATH", "(not set — will use cwd)")
+    cd_files = os.environ.get("CD_TARGET_FILES") or os.environ.get("CD_STAGED_FILES") or "(not set)"
+    cd_json  = os.environ.get("CD_JSON", "0")
+    file_count = len([l for l in cd_files.splitlines() if l.strip()]) if cd_files != "(not set)" else 0
+    print(
+        f"[commit-defender] repo={cd_repo}  files={file_count}  json={cd_json}",
+        file=sys.stderr, flush=True,
+    )
+
+    from .ai_agent import AIReviewAgent
+    from .config import load_config
+    from .diff_extractor import DiffExtractor
+    from .exit_resolver import ExitCodeResolver
+    from .linters import build_linters
+    from .models import Report
+    from .settings import load_settings
+    from .staged_files import StagedFilesReader
+
+    settings = load_settings()
+    repo_path = Path(settings.repo_path)
+    dry_run = settings.dry_run
+
+    config = load_config(repo_path)
+
+    reader = StagedFilesReader(repo_path, config, settings)
+    staged = reader.read()
+
+    if not staged:
+        target_src = "CD_TARGET_FILES" if settings.cd_target_files else "CD_STAGED_FILES"
+        print(
+            f"[commit-defender] No files matched for analysis "
+            f"(repo={repo_path}, source={target_src}).",
+            file=sys.stderr, flush=True,
+        )
+        if settings.json_mode:
+            from .json_renderer import JsonRenderer
+            from .models import ReviewResult
+            empty_report = Report(
+                staged_files=[],
+                lint_findings=[],
+                review=ReviewResult(summary="No files matched for analysis."),
+                duration_ms=0,
+            )
+            JsonRenderer().render(empty_report, exit_code=0, repo_path=str(repo_path))
+        return 0
+
+    # Resolve analysis mode: env var > settings.json > default
+    mode = (settings.cd_analysis_mode.strip() or config.review_settings.analysisMode)
+    run_linters = mode in ("hybrid", "rule-based")
+    run_ai      = mode in ("hybrid", "ai-powered")
+
+    start = time.monotonic()
+
+    # Static analysis (skipped in ai-powered mode)
+    lint_findings = []
+    if run_linters:
+        by_lang = reader.by_language(staged)
+        for lang, files in by_lang.items():
+            linter_cfg = getattr(config.linters, lang, None)
+            if linter_cfg is None or not linter_cfg.enabled:
+                continue
+            linters = build_linters(lang, linter_cfg)
+            for linter in linters:
+                lint_findings.extend(linter.run(files))
+
+    # Diff extraction — use working-tree diff when files were passed explicitly
+    diff_extractor = DiffExtractor(repo_path)
+    if settings.cd_target_files:
+        full_diff = diff_extractor.get_working_diff(staged)
+    else:
+        full_diff = diff_extractor.get_full_diff(staged)
+
+    # AI review (skipped in rule-based mode)
+    if run_ai:
+        ai_agent = AIReviewAgent(config.ai_review, full_config=config)
+        review = ai_agent.review(full_diff, lint_findings, repo_path=repo_path)
+    else:
+        from .models import ReviewResult
+        review = ReviewResult(summary="AI review disabled (rule-based mode).", blocking=False)
+
+    duration_ms = int((time.monotonic() - start) * 1000)
+
+    report = Report(
+        staged_files=[str(f.relative_to(repo_path)) for f in staged],
+        lint_findings=lint_findings,
+        review=review,
+        duration_ms=duration_ms,
+    )
+
+    resolver = ExitCodeResolver(config)
+    exit_code = resolver.resolve(report) if not dry_run else 0
+
+    # ANSI report always goes to stderr (visible in terminal and hook output)
+    from .renderer import ReportRenderer
+    ReportRenderer().render(report, blocked=(exit_code == 1))
+
+    # JSON output goes to stdout when requested (consumed by VS Code extension / CI)
+    if settings.json_mode:
+        from .json_renderer import JsonRenderer
+        JsonRenderer().render(report, exit_code, repo_path=str(repo_path))
+
+    return exit_code
+
+
+def cli() -> None:
+    """CLI entry point (used by installer for direct invocation)."""
+    sys.exit(run())
+
+
+if __name__ == "__main__":
+    cli()

commit_defender/exit_resolver.py

@@ -0,0 +1,28 @@
+"""Resolve the final exit code from a Report."""
+
+from .config import Config
+from .models import Report
+
+
+class ExitCodeResolver:
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    def resolve(self, report: Report) -> int:
+        """Return 0 (pass) or 1 (block)."""
+        # API / infrastructure errors only block when ai_review is a hard gate.
+        # When ai_review.blocking=false the review is advisory — a network hiccup
+        # must not prevent a commit from landing.
+        if report.review.is_error and self.config.ai_review.blocking:
+            return 1
+
+        # Lint findings at or above the configured threshold always block.
+        blocking_findings = report.findings_at_or_above(self.config.blocking_severity)
+        if blocking_findings:
+            return 1
+
+        # AI review blocks only when both the config gate and the AI say so.
+        if self.config.ai_review.blocking and report.review.blocking:
+            return 1
+
+        return 0