semantic-diff 0.1.0__py3-none-any.whl

semantic_diff/analyzers/llm_analyzer.py

@@ -0,0 +1,413 @@
+"""
+LLM-based semantic analyzer using Claude
+"""
+import os
+import json
+import time
+import random
+import logging
+from datetime import datetime
+from typing import List, Optional
+import anthropic
+from dotenv import load_dotenv
+
+from semantic_diff.models import (
+    FileChange, SemanticAnalysis, Intent, ImpactMap, Impact,
+    RiskAssessment, Risk, ReviewQuestion, RiskLevel
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LLMAnalyzer:
+    """Analyzes code changes using Claude for semantic understanding"""
+    
+    ANALYSIS_PROMPT = """You are a senior code reviewer analyzing a git commit. Your task is to provide semantic analysis that goes beyond what a simple diff shows.
+
+## Commit Information
+- **Hash:** {commit_hash}
+- **Message:** {commit_message}
+- **Author:** {author}
+- **Date:** {date}
+
+## Project Context
+{project_context}
+
+## Files Changed
+{files_summary}
+
+## Detailed Diffs
+{diffs}
+
+---
+
+Analyze this commit and provide a structured response in the following JSON format:
+
+```json
+{{
+    "intent": {{
+        "summary": "One sentence describing WHAT the developer was trying to accomplish (not what changed, but WHY)",
+        "reasoning": "2-3 sentences explaining your reasoning",
+        "confidence": 0.0-1.0
+    }},
+    "impact_map": {{
+        "direct_impacts": [
+            {{"area": "affected area", "description": "how it's affected", "severity": "low|medium|high|critical"}}
+        ],
+        "indirect_impacts": [
+            {{"area": "indirectly affected area", "description": "potential ripple effects", "severity": "low|medium|high|critical"}}
+        ],
+        "affected_components": ["list", "of", "components"]
+    }},
+    "risk_assessment": {{
+        "overall_risk": "low|medium|high|critical",
+        "risks": [
+            {{
+                "description": "specific risk",
+                "severity": "low|medium|high|critical",
+                "mitigation": "how to mitigate",
+                "edge_cases": ["edge case 1", "edge case 2"]
+            }}
+        ],
+        "breaking_changes": true/false,
+        "requires_migration": true/false
+    }},
+    "review_questions": [
+        {{
+            "question": "Question for the author",
+            "context": "Why this question matters",
+            "priority": "low|medium|high|critical"
+        }}
+    ]
+}}
+```
+
+Focus on:
+1. **Intent**: What problem is being solved? What's the motivation?
+2. **Impact**: What else in the system might be affected? Consider imports, API consumers, tests.
+3. **Risk**: What could break? What edge cases exist? Is this backwards compatible?
+4. **Questions**: What would you ask the author in a code review?
+
+Be specific and actionable. Avoid generic observations."""
+
+    def __init__(self, model: Optional[str] = None):
+        load_dotenv()
+        
+        self.api_key = os.getenv('ANTHROPIC_API_KEY')
+        if not self.api_key:
+            raise ValueError("ANTHROPIC_API_KEY not found in environment")
+        
+        self.model = model or os.getenv('SEMANTIC_DIFF_MODEL', 'claude-sonnet-4-5-20250929')
+        self.client = anthropic.Anthropic(api_key=self.api_key)
+        self.last_usage = None
+    
+    def _format_files_summary(self, files: List[FileChange]) -> str:
+        """Format file changes for the prompt"""
+        lines = []
+        for f in files:
+            lang = f"[{f.language}]" if f.language else ""
+            lines.append(f"- {f.path} ({f.change_type}) +{f.additions}/-{f.deletions} {lang}")
+        return "\n".join(lines)
+    
+    def _format_diffs(self, files: List[FileChange], max_total_chars: int = 15000) -> str:
+        """Format diffs for the prompt, respecting token limits"""
+        diffs = []
+        total_chars = 0
+        
+        for f in files:
+            if total_chars >= max_total_chars:
+                diffs.append(f"\n... (truncated - {len(files) - len(diffs)} more files)")
+                break
+            
+            header = f"\n### {f.path} ({f.change_type})\n```{f.language or 'diff'}\n"
+            content = f.diff_content
+            footer = "\n```\n"
+            
+            # Truncate individual file if too long
+            available = max_total_chars - total_chars - len(header) - len(footer)
+            if len(content) > available:
+                content = content[:available] + "\n... (truncated)"
+            
+            diff_block = header + content + footer
+            diffs.append(diff_block)
+            total_chars += len(diff_block)
+        
+        return "\n".join(diffs)
+    
+    def _format_project_context(self, context: dict) -> str:
+        """Format project context for the prompt"""
+        lines = [
+            f"- **Languages:** {', '.join(context.get('languages', ['unknown']))}",
+            f"- **Package Manager:** {context.get('package_manager', 'unknown')}",
+            f"- **Has Tests:** {'Yes' if context.get('has_tests') else 'No'}",
+            f"- **Has CI:** {'Yes' if context.get('has_ci') else 'No'}",
+            f"- **Root Files:** {', '.join(context.get('root_files', [])[:10])}",
+            f"- **Directories:** {', '.join(context.get('directories', [])[:10])}",
+        ]
+        return "\n".join(lines)
+    
+    def _parse_response(self, response_text: str) -> dict:
+        """Extract JSON from Claude's response"""
+        # Try to find JSON block
+        if "```json" in response_text:
+            start = response_text.find("```json") + 7
+            end = response_text.find("```", start)
+            json_str = response_text[start:end].strip()
+        elif "```" in response_text:
+            start = response_text.find("```") + 3
+            end = response_text.find("```", start)
+            json_str = response_text[start:end].strip()
+        else:
+            # Try to parse the whole response as JSON
+            json_str = response_text.strip()
+        
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse LLM response as JSON: {e}\nResponse: {response_text[:500]}")
+    
+    def _call_api_with_retry(
+        self,
+        prompt: str,
+        max_retries: Optional[int] = None,
+        base_delay: float = 1.0,
+        max_total_wait: Optional[float] = None
+    ):
+        """
+        Call Claude API with exponential backoff + jitter retry.
+        Handles rate limits, timeouts, and transient errors.
+        Respects Retry-After headers when present.
+        """
+        if max_retries is None:
+            max_retries = int(os.getenv('SEMANTIC_DIFF_MAX_RETRIES', '3'))
+        if max_total_wait is None:
+            max_total_wait = float(os.getenv('SEMANTIC_DIFF_MAX_WAIT', '30.0'))
+        
+        last_exception = None
+        total_waited = 0.0
+        
+        for attempt in range(max_retries):
+            try:
+                response = self.client.messages.create(
+                    model=self.model,
+                    max_tokens=4096,
+                    messages=[
+                        {"role": "user", "content": prompt}
+                    ]
+                )
+                return response
+            except anthropic.RateLimitError as e:
+                last_exception = e
+                # Check for Retry-After header (can be seconds or HTTP-date)
+                retry_after = getattr(e, 'retry_after', None)
+                if retry_after:
+                    try:
+                        delay = float(retry_after)
+                    except (ValueError, TypeError):
+                        # Retry-After might be HTTP-date format, fall back to exponential
+                        logger.debug(f"Could not parse Retry-After '{retry_after}', using exponential backoff")
+                        delay = base_delay * (2 ** attempt)
+                else:
+                    delay = base_delay * (2 ** attempt)
+                # Add jitter (10-30% of delay)
+                jitter = delay * random.uniform(0.1, 0.3)
+                delay += jitter
+                
+                if total_waited + delay > max_total_wait:
+                    logger.warning(f"Retry would exceed max_total_wait ({max_total_wait}s), giving up")
+                    break
+                
+                logger.warning(f"Rate limited, retry {attempt + 1}/{max_retries} in {delay:.1f}s")
+                time.sleep(delay)
+                total_waited += delay
+                
+            except anthropic.APITimeoutError as e:
+                last_exception = e
+                delay = base_delay * (2 ** attempt) + random.uniform(0, base_delay)
+                
+                if total_waited + delay > max_total_wait:
+                    break
+                    
+                logger.warning(f"Timeout, retry {attempt + 1}/{max_retries} in {delay:.1f}s")
+                time.sleep(delay)
+                total_waited += delay
+                
+            except anthropic.APIConnectionError as e:
+                last_exception = e
+                delay = base_delay * (2 ** attempt) + random.uniform(0, base_delay)
+                
+                if total_waited + delay > max_total_wait:
+                    break
+                    
+                logger.warning(f"Connection error, retry {attempt + 1}/{max_retries} in {delay:.1f}s")
+                time.sleep(delay)
+                total_waited += delay
+                
+            except anthropic.APIStatusError as e:
+                if e.status_code >= 500:
+                    last_exception = e
+                    delay = base_delay * (2 ** attempt) + random.uniform(0, base_delay)
+                    
+                    if total_waited + delay > max_total_wait:
+                        break
+                        
+                    logger.warning(f"Server error {e.status_code}, retry {attempt + 1}/{max_retries} in {delay:.1f}s")
+                    time.sleep(delay)
+                    total_waited += delay
+                else:
+                    raise
+        
+        raise RuntimeError(f"API call failed after {max_retries} retries (waited {total_waited:.1f}s): {last_exception}")
+
+    def _validate_response_data(self, data: dict) -> dict:
+        """
+        Validate and fill missing fields in LLM response.
+        Returns sanitized data with defaults for missing fields.
+        Logs warnings when defaults are applied.
+        """
+        defaults_applied = []
+        
+        # Ensure intent exists with defaults
+        if 'intent' not in data:
+            data['intent'] = {}
+            defaults_applied.append('intent')
+        if 'summary' not in data['intent']:
+            data['intent']['summary'] = 'Unable to determine intent'
+            defaults_applied.append('intent.summary')
+        if 'reasoning' not in data['intent']:
+            data['intent']['reasoning'] = 'Analysis incomplete'
+            defaults_applied.append('intent.reasoning')
+        if 'confidence' not in data['intent']:
+            data['intent']['confidence'] = 0.5
+            defaults_applied.append('intent.confidence')
+        
+        # Ensure impact_map exists with defaults
+        if 'impact_map' not in data:
+            data['impact_map'] = {}
+            defaults_applied.append('impact_map')
+        data['impact_map'].setdefault('direct_impacts', [])
+        data['impact_map'].setdefault('indirect_impacts', [])
+        data['impact_map'].setdefault('affected_components', [])
+        
+        # Ensure risk_assessment exists with defaults
+        if 'risk_assessment' not in data:
+            data['risk_assessment'] = {}
+            defaults_applied.append('risk_assessment')
+        if 'overall_risk' not in data['risk_assessment']:
+            data['risk_assessment']['overall_risk'] = 'medium'
+            defaults_applied.append('risk_assessment.overall_risk')
+        data['risk_assessment'].setdefault('risks', [])
+        data['risk_assessment'].setdefault('breaking_changes', False)
+        data['risk_assessment'].setdefault('requires_migration', False)
+        
+        # Ensure review_questions exists
+        data.setdefault('review_questions', [])
+        
+        # Log warning if defaults were applied
+        if defaults_applied:
+            logger.warning(
+                f"LLM response missing fields, defaults applied: {', '.join(defaults_applied)}. "
+                "This may indicate a prompt issue or API degradation."
+            )
+            # Mark low confidence when critical fields were missing
+            if any(field in defaults_applied for field in ['intent', 'intent.summary', 'risk_assessment']):
+                data['intent']['confidence'] = min(data['intent']['confidence'], 0.3)
+        
+        return data
+    
+    def analyze(
+        self,
+        commit_info: dict,
+        files: List[FileChange],
+        project_context: dict
+    ) -> SemanticAnalysis:
+        """
+        Analyze a commit using Claude.
+        Returns structured SemanticAnalysis.
+        """
+        # Build the prompt
+        prompt = self.ANALYSIS_PROMPT.format(
+            commit_hash=commit_info['short_hash'],
+            commit_message=commit_info['message'],
+            author=commit_info['author'],
+            date=commit_info['date'],
+            project_context=self._format_project_context(project_context),
+            files_summary=self._format_files_summary(files),
+            diffs=self._format_diffs(files)
+        )
+        
+        # Call Claude with retry
+        response = self._call_api_with_retry(prompt)
+        
+        self.last_usage = {
+            'input_tokens': response.usage.input_tokens,
+            'output_tokens': response.usage.output_tokens,
+            'total_tokens': response.usage.input_tokens + response.usage.output_tokens
+        }
+        
+        # Parse and validate response
+        response_text = response.content[0].text
+        data = self._parse_response(response_text)
+        data = self._validate_response_data(data)
+        
+        # Build structured response
+        intent = Intent(
+            summary=data['intent']['summary'],
+            reasoning=data['intent']['reasoning'],
+            confidence=data['intent']['confidence']
+        )
+        
+        impact_map = ImpactMap(
+            direct_impacts=[
+                Impact(
+                    area=i['area'],
+                    description=i['description'],
+                    severity=RiskLevel(i['severity'])
+                ) for i in data['impact_map'].get('direct_impacts', [])
+            ],
+            indirect_impacts=[
+                Impact(
+                    area=i['area'],
+                    description=i['description'],
+                    severity=RiskLevel(i['severity'])
+                ) for i in data['impact_map'].get('indirect_impacts', [])
+            ],
+            affected_components=data['impact_map'].get('affected_components', [])
+        )
+        
+        risk_assessment = RiskAssessment(
+            overall_risk=RiskLevel(data['risk_assessment']['overall_risk']),
+            risks=[
+                Risk(
+                    description=r['description'],
+                    severity=RiskLevel(r['severity']),
+                    mitigation=r.get('mitigation'),
+                    edge_cases=r.get('edge_cases', [])
+                ) for r in data['risk_assessment'].get('risks', [])
+            ],
+            breaking_changes=data['risk_assessment'].get('breaking_changes', False),
+            requires_migration=data['risk_assessment'].get('requires_migration', False)
+        )
+        
+        review_questions = [
+            ReviewQuestion(
+                question=q['question'],
+                context=q['context'],
+                priority=RiskLevel(q.get('priority', 'medium'))
+            ) for q in data.get('review_questions', [])
+        ]
+        
+        return SemanticAnalysis(
+            commit_hash=commit_info['hash'],
+            commit_message=commit_info['message'],
+            author=commit_info['author'],
+            date=commit_info['date'],
+            files_changed=files,
+            intent=intent,
+            impact_map=impact_map,
+            risk_assessment=risk_assessment,
+            review_questions=review_questions,
+            analysis_model=self.model,
+            analysis_timestamp=datetime.now().isoformat(),
+            tokens_used=self.last_usage['total_tokens']
+        )

semantic_diff/cli.py

@@ -0,0 +1,86 @@
+"""
+CLI interface for semantic-diff
+"""
+import click
+from pathlib import Path
+import sys
+import os
+
+from semantic_diff.parsers.git_parser import GitParser
+from semantic_diff.analyzers.llm_analyzer import LLMAnalyzer
+from semantic_diff.formatters.console_formatter import ConsoleFormatter
+
+
+@click.command()
+@click.argument('commit_hash', default='HEAD')
+@click.option('--repo', '-r', default='.', help='Path to git repository')
+@click.option('--model', '-m', default=None, help='Model to use (default: from .env)')
+@click.option('--json', 'output_json', is_flag=True, help='Output as JSON')
+@click.option('--verbose', '-v', is_flag=True, help='Verbose output')
+def main(commit_hash: str, repo: str, model: str, output_json: bool, verbose: bool):
+    """
+    Analyze a git commit semantically.
+    
+    COMMIT_HASH: The commit to analyze (default: HEAD)
+    
+    Examples:
+    
+        semantic-diff HEAD
+        
+        semantic-diff abc123
+        
+        semantic-diff HEAD~1 --repo /path/to/repo
+    """
+    try:
+        # Initialize components
+        if verbose:
+            click.echo(f"Initializing parser for {repo}...")
+        
+        parser = GitParser(repo if repo != '.' else None)
+        
+        if verbose:
+            click.echo(f"Getting commit info for {commit_hash}...")
+        
+        # Get commit data
+        commit_info = parser.get_commit_info(commit_hash)
+        files = parser.get_file_changes(commit_hash)
+        project_context = parser.get_project_context()
+        
+        if verbose:
+            click.echo(f"Found {len(files)} changed files")
+            click.echo(f"Project languages: {project_context.get('languages', [])}")
+        
+        if not files:
+            click.echo("No changes found in this commit.", err=True)
+            sys.exit(0)
+        
+        # Analyze
+        if verbose:
+            click.echo("Calling LLM for analysis...")
+        
+        analyzer = LLMAnalyzer(model=model)
+        analysis = analyzer.analyze(commit_info, files, project_context)
+        
+        # Output
+        if output_json:
+            import json
+            # Convert to dict, handling enums
+            data = analysis.model_dump()
+            click.echo(json.dumps(data, indent=2, default=str))
+        else:
+            formatter = ConsoleFormatter()
+            formatter.format(analysis)
+        
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        if verbose:
+            import traceback
+            click.echo(traceback.format_exc(), err=True)
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

semantic_diff/formatters/console_formatter.py

@@ -0,0 +1,165 @@
+"""
+Console formatter for semantic diff output using Rich
+"""
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.markdown import Markdown
+from rich.text import Text
+from rich import box
+
+from semantic_diff.models import SemanticAnalysis, RiskLevel
+
+
+class ConsoleFormatter:
+    """Formats SemanticAnalysis for terminal output"""
+    
+    RISK_COLORS = {
+        RiskLevel.LOW: "green",
+        RiskLevel.MEDIUM: "yellow",
+        RiskLevel.HIGH: "red",
+        RiskLevel.CRITICAL: "bold red",
+    }
+    
+    RISK_ICONS = {
+        RiskLevel.LOW: "✓",
+        RiskLevel.MEDIUM: "⚠",
+        RiskLevel.HIGH: "⚡",
+        RiskLevel.CRITICAL: "🔥",
+    }
+    
+    def __init__(self):
+        self.console = Console()
+    
+    def _risk_style(self, level: RiskLevel) -> str:
+        return self.RISK_COLORS.get(level, "white")
+    
+    def _risk_icon(self, level: RiskLevel) -> str:
+        return self.RISK_ICONS.get(level, "•")
+    
+    def format(self, analysis: SemanticAnalysis) -> None:
+        """Print formatted analysis to console"""
+        
+        # Header
+        self.console.print()
+        self.console.print(Panel(
+            f"[bold]{analysis.commit_message}[/bold]\n\n"
+            f"[dim]{analysis.commit_hash[:8]} by {analysis.author}[/dim]\n"
+            f"[dim]{analysis.date}[/dim]",
+            title="📋 Semantic Diff Analysis",
+            border_style="blue"
+        ))
+        
+        # Files changed summary
+        files_table = Table(box=box.SIMPLE, show_header=True, header_style="bold")
+        files_table.add_column("File", style="cyan")
+        files_table.add_column("Change", style="dim")
+        files_table.add_column("+", style="green", justify="right")
+        files_table.add_column("-", style="red", justify="right")
+        files_table.add_column("Lang", style="dim")
+        
+        for f in analysis.files_changed[:10]:  # Limit to 10
+            files_table.add_row(
+                f.path[:50] + "..." if len(f.path) > 50 else f.path,
+                f.change_type,
+                str(f.additions),
+                str(f.deletions),
+                f.language or "-"
+            )
+        
+        if len(analysis.files_changed) > 10:
+            files_table.add_row(
+                f"... and {len(analysis.files_changed) - 10} more",
+                "", "", "", ""
+            )
+        
+        self.console.print(Panel(files_table, title="📁 Files Changed", border_style="dim"))
+        
+        # Intent
+        confidence_bar = "█" * int(analysis.intent.confidence * 10) + "░" * (10 - int(analysis.intent.confidence * 10))
+        self.console.print(Panel(
+            f"[bold]{analysis.intent.summary}[/bold]\n\n"
+            f"{analysis.intent.reasoning}\n\n"
+            f"[dim]Confidence: [{confidence_bar}] {analysis.intent.confidence:.0%}[/dim]",
+            title="🎯 Intent",
+            border_style="green"
+        ))
+        
+        # Impact Map
+        impact_text = Text()
+        
+        if analysis.impact_map.direct_impacts:
+            impact_text.append("Direct Impacts:\n", style="bold")
+            for impact in analysis.impact_map.direct_impacts:
+                icon = self._risk_icon(impact.severity)
+                color = self._risk_style(impact.severity)
+                impact_text.append(f"  {icon} ", style=color)
+                impact_text.append(f"{impact.area}: ", style="bold")
+                impact_text.append(f"{impact.description}\n")
+            impact_text.append("\n")
+        
+        if analysis.impact_map.indirect_impacts:
+            impact_text.append("Indirect Impacts:\n", style="bold")
+            for impact in analysis.impact_map.indirect_impacts:
+                icon = self._risk_icon(impact.severity)
+                color = self._risk_style(impact.severity)
+                impact_text.append(f"  {icon} ", style=color)
+                impact_text.append(f"{impact.area}: ", style="bold")
+                impact_text.append(f"{impact.description}\n")
+            impact_text.append("\n")
+        
+        if analysis.impact_map.affected_components:
+            impact_text.append("Affected Components: ", style="bold")
+            impact_text.append(", ".join(analysis.impact_map.affected_components))
+        
+        self.console.print(Panel(impact_text, title="🗺️  Impact Map", border_style="yellow"))
+        
+        # Risk Assessment
+        risk = analysis.risk_assessment
+        risk_color = self._risk_style(risk.overall_risk)
+        risk_icon = self._risk_icon(risk.overall_risk)
+        
+        risk_text = Text()
+        risk_text.append(f"Overall Risk: {risk_icon} {risk.overall_risk.value.upper()}\n\n", style=f"bold {risk_color}")
+        
+        if risk.breaking_changes:
+            risk_text.append("⚠️  BREAKING CHANGES DETECTED\n", style="bold red")
+        if risk.requires_migration:
+            risk_text.append("📦 Migration required\n", style="bold yellow")
+        
+        if risk.risks:
+            risk_text.append("\nIdentified Risks:\n", style="bold")
+            for r in risk.risks:
+                icon = self._risk_icon(r.severity)
+                color = self._risk_style(r.severity)
+                risk_text.append(f"\n  {icon} ", style=color)
+                risk_text.append(f"[{r.severity.value}] ", style=f"bold {color}")
+                risk_text.append(f"{r.description}\n")
+                if r.mitigation:
+                    risk_text.append(f"     💡 Mitigation: {r.mitigation}\n", style="dim")
+                if r.edge_cases:
+                    risk_text.append(f"     ⚡ Edge cases: {', '.join(r.edge_cases)}\n", style="dim")
+        
+        self.console.print(Panel(risk_text, title="⚠️  Risk Assessment", border_style=risk_color))
+        
+        # Review Questions
+        if analysis.review_questions:
+            questions_text = Text()
+            for i, q in enumerate(analysis.review_questions, 1):
+                icon = self._risk_icon(q.priority)
+                color = self._risk_style(q.priority)
+                questions_text.append(f"{i}. ", style="bold")
+                questions_text.append(f"{q.question}\n", style="bold")
+                questions_text.append(f"   {icon} ", style=color)
+                questions_text.append(f"{q.context}\n\n", style="dim")
+            
+            self.console.print(Panel(questions_text, title="❓ Review Questions", border_style="cyan"))
+        
+        # Footer
+        self.console.print()
+        self.console.print(
+            f"[dim]Analysis by {analysis.analysis_model} | "
+            f"{analysis.tokens_used:,} tokens | "
+            f"{analysis.analysis_timestamp}[/dim]"
+        )
+        self.console.print()

semantic_diff/models.py

@@ -0,0 +1,86 @@
+"""
+Data models for semantic diff analysis
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from enum import Enum
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class FileChange(BaseModel):
+    """Represents a single file change in a commit"""
+    path: str
+    change_type: str  # added, modified, deleted, renamed
+    additions: int = 0
+    deletions: int = 0
+    diff_content: str = ""
+    language: Optional[str] = None
+
+
+class Intent(BaseModel):
+    """What the developer was trying to accomplish"""
+    summary: str = Field(description="One-line summary of the intent")
+    reasoning: str = Field(description="Detailed reasoning behind this assessment")
+    confidence: float = Field(ge=0, le=1, description="Confidence in this assessment")
+
+
+class Impact(BaseModel):
+    """A single impact point"""
+    area: str = Field(description="What area is affected")
+    description: str = Field(description="How it's affected")
+    severity: RiskLevel = Field(description="How significant is this impact")
+
+
+class ImpactMap(BaseModel):
+    """Map of all areas impacted by the change"""
+    direct_impacts: List[Impact] = Field(default_factory=list)
+    indirect_impacts: List[Impact] = Field(default_factory=list)
+    affected_components: List[str] = Field(default_factory=list)
+
+
+class Risk(BaseModel):
+    """A single identified risk"""
+    description: str
+    severity: RiskLevel
+    mitigation: Optional[str] = None
+    edge_cases: List[str] = Field(default_factory=list)
+
+
+class RiskAssessment(BaseModel):
+    """Overall risk assessment"""
+    overall_risk: RiskLevel
+    risks: List[Risk] = Field(default_factory=list)
+    breaking_changes: bool = False
+    requires_migration: bool = False
+
+
+class ReviewQuestion(BaseModel):
+    """A question for the code author"""
+    question: str
+    context: str
+    priority: RiskLevel = RiskLevel.MEDIUM
+
+
+class SemanticAnalysis(BaseModel):
+    """Complete semantic analysis of a commit"""
+    commit_hash: str
+    commit_message: str
+    author: str
+    date: str
+    files_changed: List[FileChange]
+    
+    intent: Intent
+    impact_map: ImpactMap
+    risk_assessment: RiskAssessment
+    review_questions: List[ReviewQuestion]
+    
+    # Metadata
+    analysis_model: str
+    analysis_timestamp: str
+    tokens_used: int = 0

semantic_diff/parsers/git_parser.py

@@ -0,0 +1,208 @@
+"""
+Git diff parser - extracts structured information from git commits
+"""
+import os
+from typing import Optional, List
+from git import Repo, InvalidGitRepositoryError
+from pathlib import Path
+
+from semantic_diff.models import FileChange
+
+
+class GitParser:
+    """Parses git repository information"""
+    
+    LANGUAGE_EXTENSIONS = {
+        '.py': 'python',
+        '.js': 'javascript',
+        '.ts': 'typescript',
+        '.tsx': 'typescript',
+        '.jsx': 'javascript',
+        '.rs': 'rust',
+        '.go': 'go',
+        '.java': 'java',
+        '.rb': 'ruby',
+        '.php': 'php',
+        '.c': 'c',
+        '.cpp': 'cpp',
+        '.h': 'c',
+        '.hpp': 'cpp',
+        '.cs': 'csharp',
+        '.swift': 'swift',
+        '.kt': 'kotlin',
+        '.scala': 'scala',
+        '.sql': 'sql',
+        '.md': 'markdown',
+        '.json': 'json',
+        '.yaml': 'yaml',
+        '.yml': 'yaml',
+        '.toml': 'toml',
+        '.xml': 'xml',
+        '.html': 'html',
+        '.css': 'css',
+        '.scss': 'scss',
+        '.sh': 'bash',
+        '.bash': 'bash',
+    }
+    
+    def __init__(self, repo_path: Optional[str] = None):
+        """
+        Initialize parser with repository path.
+        If not provided, uses current directory.
+        """
+        self.repo_path = repo_path or os.getcwd()
+        try:
+            self.repo = Repo(self.repo_path)
+        except InvalidGitRepositoryError:
+            raise ValueError(f"Not a git repository: {self.repo_path}")
+    
+    def get_commit(self, commit_hash: str):
+        """Get a commit by hash (full or short)"""
+        try:
+            return self.repo.commit(commit_hash)
+        except Exception as e:
+            raise ValueError(f"Could not find commit: {commit_hash}") from e
+    
+    def get_commit_info(self, commit_hash: str) -> dict:
+        """Get basic commit information"""
+        commit = self.get_commit(commit_hash)
+        return {
+            'hash': commit.hexsha,
+            'short_hash': commit.hexsha[:8],
+            'message': commit.message.strip(),
+            'author': f"{commit.author.name} <{commit.author.email}>",
+            'date': commit.committed_datetime.isoformat(),
+            'parents': [p.hexsha for p in commit.parents],
+        }
+    
+    def detect_language(self, filepath: str) -> Optional[str]:
+        """Detect programming language from file extension"""
+        ext = Path(filepath).suffix.lower()
+        return self.LANGUAGE_EXTENSIONS.get(ext)
+    
+    def get_file_changes(self, commit_hash: str) -> List[FileChange]:
+        """
+        Get all file changes for a commit.
+        Returns structured FileChange objects.
+        """
+        commit = self.get_commit(commit_hash)
+        changes = []
+        
+        # Handle initial commit (no parents)
+        if not commit.parents:
+            for item in commit.tree.traverse():
+                if item.type == 'blob':
+                    content = ""
+                    diff_content = "[binary file]"
+                    try:
+                        content = item.data_stream.read().decode('utf-8', errors='replace')
+                        diff_content = f"+{content}"
+                    except (UnicodeDecodeError, IOError, OSError):
+                        pass  # Keep defaults: empty content, binary marker
+                    
+                    changes.append(FileChange(
+                        path=item.path,
+                        change_type='added',
+                        additions=len(content.split('\n')) if content else 0,
+                        deletions=0,
+                        diff_content=diff_content[:5000],  # Limit size
+                        language=self.detect_language(item.path)
+                    ))
+            return changes
+        
+        # Normal commit with parent
+        parent = commit.parents[0]
+        diffs = parent.diff(commit, create_patch=True)
+        
+        for diff in diffs:
+            # Determine change type
+            if diff.new_file:
+                change_type = 'added'
+                path = diff.b_path
+            elif diff.deleted_file:
+                change_type = 'deleted'
+                path = diff.a_path
+            elif diff.renamed:
+                change_type = 'renamed'
+                path = f"{diff.a_path} -> {diff.b_path}"
+            else:
+                change_type = 'modified'
+                path = diff.b_path or diff.a_path
+            
+            # Get diff content
+            try:
+                diff_content = diff.diff.decode('utf-8', errors='replace')
+            except (UnicodeDecodeError, AttributeError, TypeError):
+                diff_content = "[binary file]"
+            
+            # Count additions/deletions
+            additions = 0
+            deletions = 0
+            for line in diff_content.split('\n'):
+                if line.startswith('+') and not line.startswith('+++'):
+                    additions += 1
+                elif line.startswith('-') and not line.startswith('---'):
+                    deletions += 1
+            
+            changes.append(FileChange(
+                path=path,
+                change_type=change_type,
+                additions=additions,
+                deletions=deletions,
+                diff_content=diff_content[:5000],  # Limit size for LLM
+                language=self.detect_language(path)
+            ))
+        
+        return changes
+    
+    def get_project_context(self, max_files: int = 20) -> dict:
+        """
+        Get project context - file structure, main files, etc.
+        Useful for understanding impact.
+        """
+        context = {
+            'root_files': [],
+            'directories': [],
+            'languages': set(),
+            'has_tests': False,
+            'has_ci': False,
+            'package_manager': None,
+        }
+        
+        # Check root files
+        for item in self.repo.tree().traverse():
+            if item.type == 'blob':
+                path = item.path
+                
+                # Root level important files
+                if '/' not in path:
+                    context['root_files'].append(path)
+                    
+                    # Detect package manager
+                    if path == 'package.json':
+                        context['package_manager'] = 'npm'
+                    elif path == 'requirements.txt' or path == 'pyproject.toml':
+                        context['package_manager'] = 'pip'
+                    elif path == 'Cargo.toml':
+                        context['package_manager'] = 'cargo'
+                    elif path == 'go.mod':
+                        context['package_manager'] = 'go'
+                
+                # Detect tests
+                if 'test' in path.lower() or 'spec' in path.lower():
+                    context['has_tests'] = True
+                
+                # Detect CI
+                if '.github/workflows' in path or '.gitlab-ci' in path:
+                    context['has_ci'] = True
+                
+                # Track languages
+                lang = self.detect_language(path)
+                if lang:
+                    context['languages'].add(lang)
+            
+            elif item.type == 'tree' and '/' not in item.path:
+                context['directories'].append(item.path)
+        
+        context['languages'] = list(context['languages'])
+        return context

semantic_diff-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: semantic-diff
+Version: 0.1.0
+Summary: AI-powered semantic analysis of git commits
+Author-email: Kenaz GmbH <hello@kenaz.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tkenaz/semantic_diff
+Project-URL: Repository, https://github.com/tkenaz/semantic_diff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# semantic-diff
+
+AI-powered semantic analysis of git commits. Goes beyond `git diff` to show **intent**, **impact**, **risk**, and **review questions**.
+
+## What it does
+
+Regular `git diff` shows *what* changed. `semantic-diff` shows:
+
+- **🎯 Intent** — What was the developer trying to accomplish? (not what changed, but *why*)
+- **🗺️ Impact Map** — What parts of the system are affected directly and indirectly?
+- **⚠️ Risk Assessment** — What could break? Edge cases? Breaking changes?
+- **❓ Review Questions** — What should a reviewer ask the author?
+
+## Installation
+
+```bash
+# Clone the repo
+git clone git@github.com:tkenaz/semantic_diff.git
+cd semantic_diff
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install
+pip install -e .
+```
+
+## Configuration
+
+Create a `.env` file:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+SEMANTIC_DIFF_MODEL=claude-sonnet-4-5-20250929  # or claude-opus-4-5-20251101
+SEMANTIC_DIFF_MAX_RETRIES=3  # optional, API retry attempts
+SEMANTIC_DIFF_MAX_WAIT=30.0  # optional, max total retry wait time in seconds
+```
+
+## Usage
+
+```bash
+# Analyze HEAD commit in current repo
+semantic-diff
+
+# Analyze specific commit
+semantic-diff abc123
+
+# Analyze commit in another repo
+semantic-diff HEAD --repo /path/to/repo
+
+# Output as JSON (for piping to other tools)
+semantic-diff HEAD --json
+
+# Verbose mode
+semantic-diff HEAD -v
+```
+
+## Example Output
+
+```
+╭──────────────────── 📋 Semantic Diff Analysis ────────────────────╮
+│ Fix authentication bypass in login endpoint                       │
+│                                                                    │
+│ abc12345 by developer@example.com                                  │
+│ 2024-12-22T10:30:00                                                │
+╰────────────────────────────────────────────────────────────────────╯
+
+╭──────────────────────── 🎯 Intent ────────────────────────╮
+│ Prevent unauthorized access by validating session tokens  │
+│ before processing login requests.                         │
+│                                                            │
+│ Confidence: [████████░░] 85%                               │
+╰────────────────────────────────────────────────────────────╯
+
+╭──────────────────── ⚠️ Risk Assessment ───────────────────╮
+│ Overall Risk: ⚡ HIGH                                      │
+│                                                            │
+│ ⚠️  BREAKING CHANGES DETECTED                              │
+│                                                            │
+│ Identified Risks:                                          │
+│   ⚡ [high] Existing sessions may be invalidated           │
+│      💡 Mitigation: Add migration for active sessions      │
+╰────────────────────────────────────────────────────────────╯
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black semantic_diff
+ruff check semantic_diff
+```
+
+## License
+
+MIT — Kenaz GmbH

semantic_diff-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+semantic_diff/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_diff/cli.py,sha256=8y-y_lNxGR5AiUweGQACWcvQ0D8pD9idxIoiOOBB2vg,2680
+semantic_diff/models.py,sha256=pkV1dskq9frikpGTzATuPeEM4LY99IdezlJFpsF2rTM,2368
+semantic_diff/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_diff/analyzers/llm_analyzer.py,sha256=B7yhKKqbjDGHCxOXrNtzHZNZYEcXaDtUsyTdjJ0y5_c,16286
+semantic_diff/formatters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_diff/formatters/console_formatter.py,sha256=MybzynifCnULBqNI3P1_sF_q3lm-MECATw0cN14dZTQ,6745
+semantic_diff/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_diff/parsers/git_parser.py,sha256=59iZ1LLDO28zxAhM-YiEDkvGSbjH-rW7WTzS4QVXiBw,7369
+semantic_diff-0.1.0.dist-info/METADATA,sha256=H5ZXRBCNLrHEGAtcItvfRzEfY7LGi5jnmyo8mljCFlk,4821
+semantic_diff-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+semantic_diff-0.1.0.dist-info/entry_points.txt,sha256=jAOkEjqBBPCIYz-fHkAjOWEk6CSJmAgCSNukSN9oQCw,57
+semantic_diff-0.1.0.dist-info/top_level.txt,sha256=KnLPUVj5bNp8QVIRhay9drM_pXoC1S-Dof7bwzo0v2o,14
+semantic_diff-0.1.0.dist-info/RECORD,,

semantic_diff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semantic_diff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semantic-diff = semantic_diff.cli:main

semantic_diff-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+semantic_diff