gitpulse-ai 0.1.0__py3-none-any.whl

git_pulse/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

git_pulse/analyst/engine.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+
+from litellm import completion
+
+from git_pulse.analyst.models import AnalystReport
+from git_pulse.analyst.prompts import build_system_prompt, build_user_prompt
+
+
+class AnalystEngine:
+    def __init__(self, model: str):
+        self.model = model
+
+    def analyze(self, report_dict: dict) -> AnalystReport:
+        """Send collector report to LLM and parse the response into an AnalystReport."""
+        system_prompt = build_system_prompt()
+        user_prompt = build_user_prompt(report_dict)
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        response = completion(model=self.model, messages=messages)
+        content = response.choices[0].message.content
+
+        try:
+            data = json.loads(content)
+            return AnalystReport.from_dict(data)
+        except (json.JSONDecodeError, KeyError):
+            return self._retry(messages, content)
+
+    def _retry(self, messages: list[dict], bad_content: str) -> AnalystReport:
+        """Retry with a correction prompt after malformed JSON."""
+        messages = messages + [
+            {"role": "assistant", "content": bad_content},
+            {
+                "role": "user",
+                "content": "Your response was not valid JSON. Please respond with ONLY valid JSON matching the schema from the system prompt. No markdown, no explanation.",
+            },
+        ]
+
+        response = completion(model=self.model, messages=messages)
+        content = response.choices[0].message.content
+
+        try:
+            data = json.loads(content)
+            return AnalystReport.from_dict(data)
+        except (json.JSONDecodeError, KeyError):
+            return AnalystReport(
+                summary="Failed to parse LLM response. Run with --verbose to see raw collector data.",
+                insights=[],
+                top_actions=[],
+            )

git_pulse/analyst/models.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+@dataclass
+class Insight:
+    category: str
+    title: str
+    severity: str
+    evidence: list[str]
+    recommendation: str
+
+@dataclass
+class AnalystReport:
+    summary: str
+    insights: list[Insight]
+    top_actions: list[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> AnalystReport:
+        insights = [
+            Insight(
+                category=i["category"],
+                title=i["title"],
+                severity=i["severity"],
+                evidence=i["evidence"],
+                recommendation=i["recommendation"],
+            )
+            for i in data.get("insights", [])
+        ]
+        return cls(
+            summary=data["summary"],
+            insights=insights,
+            top_actions=data.get("top_actions", []),
+        )

git_pulse/analyst/prompts.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+import json
+
+SYSTEM_PROMPT = """You are GitPulse, a development workflow analyst. You receive a structured report of git repository activity and produce actionable insights.
+
+For each category, produce 0-N insights ranked by impact. Each insight must include:
+- "category": one of the 5 categories below
+- "title": short descriptive title
+- "severity": "high", "medium", or "low"
+- "evidence": list of strings citing specific files, line ranges, commit patterns
+- "recommendation": one concrete, actionable next step
+
+Categories:
+1. REWORK_REDUCTION — Patterns where code was rewritten multiple times. What went wrong and how to get it right faster.
+2. AGENT_EFFECTIVENESS — If attribution data is present, how effectively are agents being used? Where do they struggle or excel? Skip if no attribution data.
+3. CODEBASE_HEALTH — Chronic hotspots, architectural issues causing repeated churn, files needing refactoring or decomposition.
+4. PROMPT_GUIDANCE — This is the MOST IMPORTANT category. Produce detailed, specific, and actionable prompt engineering advice. Skip if no attribution data. See detailed instructions below.
+5. WORKFLOW_OPTIMIZATION — Session patterns, productivity signals, process improvements.
+
+## PROMPT_GUIDANCE — Detailed Instructions
+
+This category must be HIGHLY SPECIFIC and ACTIONABLE. For each insight:
+
+1. **Diagnose the root cause**: Look at the rework patterns and diff snippets. What was the developer likely asking the agent to do? What went wrong — was the prompt too vague, missing constraints, missing context, requesting too much at once, or missing acceptance criteria?
+
+2. **Show a BAD prompt example**: Based on the rework pattern, write an example of the kind of vague/incomplete prompt that likely caused the rework. Infer this from the file names, the nature of changes, and the iteration pattern.
+
+3. **Show a GOOD prompt example**: Write a realistic, natural prompt the developer SHOULD have used instead. CRITICAL RULES for the better prompt:
+   - It must sound like something a developer would ACTUALLY type to an agent — conversational, not a specification document
+   - Developers should NOT be dictating method names, class hierarchies, or full implementation details — that defeats the purpose of using an agent
+   - Instead, the better prompt should POINT THE AGENT to existing code to learn from: "Look at how UserProvider is structured and follow the same pattern"
+   - Tell the agent what context to read first: "Read through services/ to understand our service layer before starting"
+   - Tell the agent what to ASK about: "If you're unsure about the state shape, ask me before implementing"
+   - Set constraints and boundaries: "Don't add persistence yet", "Use our existing theme", "Keep it under one file"
+   - Break big asks into smaller ones: "First just create the basic screen with a list, we'll add the edit flow next"
+   - Give the agent permission to ask questions rather than guess
+
+4. **Explain WHY the good prompt works**: What specifically about the improved prompt would have prevented the rework? Focus on how context pointers, scope constraints, and question-asking prevent the agent from guessing wrong.
+
+Format each PROMPT_GUIDANCE insight's "recommendation" field as a multi-line string with these sections:
+
+"recommendation": "PROBLEM: [What the developer likely prompted]\n\nBAD PROMPT EXAMPLE:\n```\n[example of the vague prompt that caused rework]\n```\n\nBETTER PROMPT EXAMPLE:\n```\n[detailed, specific prompt that would have avoided the rework]\n```\n\nWHY THIS WORKS: [2-3 sentences explaining what specifically prevents rework]"
+
+Real examples of the kind of detail expected:
+
+Example 1 (UI rework pattern):
+"recommendation": "PROBLEM: Developer asked agent to 'build the user list screen' without pointing it to existing patterns or setting scope boundaries.\n\nBAD PROMPT EXAMPLE:\n```\nCreate a user list screen for the app that shows users and lets them add/remove entries.\n```\n\nBETTER PROMPT EXAMPLE:\n```\nCreate a user list screen with swipe-to-delete. Before you start, look at how ProductListScreen is built — follow the same widget + provider pattern. Use our existing UserProvider for state. For the list item card, check widgets/user_card.dart — reuse it if it fits, otherwise ask me what the card should show. Don't add the 'add user' flow yet, just the list view with empty state. If you're unsure about theming, check how other screens use AppColors.\n```\n\nWHY THIS WORKS: Points agent to existing code to learn patterns from, explicitly scopes to just the list (not CRUD), tells agent where to look for answers, and gives permission to ask rather than guess."
+
+Example 2 (API rework pattern):
+"recommendation": "PROBLEM: Developer asked agent to 'add API endpoints' without pointing to existing service patterns or specifying which services to wire up.\n\nBAD PROMPT EXAMPLE:\n```\nAdd REST endpoints for the payment service that handle transactions.\n```\n\nBETTER PROMPT EXAMPLE:\n```\nAdd a POST /api/payments endpoint to server/main.py. Look at how the existing /api/orders endpoint is structured and follow the same pattern for error handling and response format. Wire it up to the payment_service.py we already have. For the request schema, I need amount (float) and currency (string). Ask me if you're unsure about what the response should look like — don't guess. Also read models/schemas.py to see how we define Pydantic models.\n```\n\nWHY THIS WORKS: Points to an existing endpoint as a reference pattern, names the specific service to integrate, gives partial schema but tells the agent to ask about the rest, preventing the agent from making wrong guesses that get reworked."
+
+Produce at LEAST 2-3 PROMPT_GUIDANCE insights when attribution data shows agent rework. Each must have the full BAD/BETTER prompt structure. These should be specific to the actual files and patterns in the data, not generic advice.
+
+## Response Format
+
+If the report shows no attribution data (has_attribution_data is false), skip AGENT_EFFECTIVENESS and PROMPT_GUIDANCE entirely.
+
+Respond ONLY with valid JSON matching this schema:
+{
+  "summary": "2-3 sentence executive summary",
+  "insights": [
+    {
+      "category": "CATEGORY_NAME",
+      "title": "Short title",
+      "severity": "high|medium|low",
+      "evidence": ["specific evidence strings"],
+      "recommendation": "Concrete action to take (see PROMPT_GUIDANCE instructions for that category's format)"
+    }
+  ],
+  "top_actions": ["Top 3 most impactful things to do right now"]
+}
+
+Be specific. Reference actual file names, line ranges, and commit patterns from the data. Do not give generic advice."""
+
+def build_system_prompt() -> str:
+    return SYSTEM_PROMPT
+
+def build_user_prompt(report_dict: dict) -> str:
+    return f"Analyze this repository activity report and provide insights:\n\n{json.dumps(report_dict, indent=2)}"

git_pulse/cli.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from git_pulse.config import load_config
+
+app = typer.Typer(
+    name="git-pulse",
+    help="Analyze git repo history for development hotspots with LLM-powered insights.",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+
+@app.command()
+def version():
+    """Show version information."""
+    from git_pulse import __version__
+
+    console.print(f"git-pulse version {__version__}")
+
+
+@app.command()
+def analyze(
+    path: str = typer.Argument(".", help="Path to a git repository"),
+    days: Optional[int] = typer.Option(None, help="Analyze last N days of history"),
+    commits: Optional[int] = typer.Option(None, help="Analyze last N commits"),
+    branch: Optional[str] = typer.Option(None, help="Branch to analyze (default: current)"),
+    include: Optional[list[str]] = typer.Option(None, help="Only analyze files matching glob"),
+    exclude: Optional[list[str]] = typer.Option(None, help="Skip files matching glob"),
+    max_hotspots: Optional[int] = typer.Option(None, help="Max hotspots to send to LLM"),
+    model: Optional[str] = typer.Option(None, help="LiteLLM model string"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON instead of terminal"),
+    output: Optional[str] = typer.Option(None, help="Write report to file"),
+    verbose: bool = typer.Option(False, help="Show collector metrics before LLM analysis"),
+    config: Optional[str] = typer.Option(None, help="Path to config file"),
+) -> None:
+    """Analyze a git repository for development hotspots and get LLM-powered insights."""
+    repo_path = Path(path).resolve()
+
+    # Validate repo
+    if not repo_path.exists():
+        console.print(f"[red]Error:[/red] Path does not exist: {repo_path}")
+        raise typer.Exit(1)
+    if not (repo_path / ".git").exists():
+        console.print(f"[red]Error:[/red] Not a git repository: {repo_path}")
+        raise typer.Exit(1)
+
+    # Load config
+    cfg = load_config(config_path=config, repo_path=str(repo_path))
+    effective_days = days or (None if commits else cfg.default_days)
+    effective_max_hotspots = max_hotspots or cfg.max_hotspots
+    effective_model = model or cfg.model
+    effective_exclude = (exclude or []) + cfg.exclude
+
+    # Collect
+    from git_pulse.collector.git_history import GitHistoryCollector
+    from git_pulse.collector.hotspot_detector import HotspotDetector
+    from git_pulse.collector.metrics import MetricsCalculator
+    from git_pulse.collector.models import CollectorReport
+
+    if not json_output:
+        console.print("[dim]Collecting git history...[/dim]")
+
+    collector = GitHistoryCollector(str(repo_path), branch=branch)
+    commit_data = collector.collect(
+        days=effective_days,
+        commits=commits,
+        include=include,
+        exclude=effective_exclude,
+    )
+
+    if not commit_data:
+        console.print("[yellow]No commits found in the specified range.[/yellow]")
+        raise typer.Exit(0)
+
+    # Detect hotspots
+    detector = HotspotDetector(commit_data, max_hotspots=effective_max_hotspots)
+    hotspots = detector.detect()
+
+    # Calculate metrics
+    calc = MetricsCalculator(commit_data)
+    file_churn = calc.file_churn()
+    change_velocity = calc.change_velocity()
+    agent_human_ratio = calc.agent_human_ratio()
+    rework_rate = calc.rework_rate()
+    sessions = calc.sessions()
+
+    from datetime import datetime
+
+    timestamps = [datetime.fromisoformat(c["timestamp"]) for c in commit_data]
+
+    collector_report = CollectorReport(
+        repo_path=str(repo_path),
+        branch=branch or collector.branch,
+        commit_range=(commit_data[-1]["hash"][:8], commit_data[0]["hash"][:8]),
+        time_range=(min(timestamps), max(timestamps)),
+        total_commits=len(commit_data),
+        total_files_changed=len(file_churn),
+        hotspots=hotspots,
+        file_churn=file_churn,
+        change_velocity=change_velocity,
+        agent_human_ratio=agent_human_ratio,
+        rework_rate=rework_rate,
+        sessions=sessions,
+        has_attribution_data=any(c["is_agent_attributed"] for c in commit_data),
+        attribution_source=next(
+            (c["attribution_source"] for c in commit_data if c["attribution_source"]),
+            None,
+        ),
+    )
+
+    # Analyze with LLM
+    if not json_output:
+        console.print("[dim]Analyzing with LLM...[/dim]")
+
+    from git_pulse.analyst.engine import AnalystEngine
+
+    engine = AnalystEngine(model=effective_model)
+
+    try:
+        analyst_report = engine.analyze(collector_report.to_dict())
+    except Exception as e:
+        console.print(f"[red]LLM analysis failed:[/red] {e}")
+        if verbose:
+            from git_pulse.renderer.terminal import _render_verbose
+            _render_verbose(console, collector_report)
+        raise typer.Exit(1)
+
+    # Render
+    if json_output:
+        from git_pulse.renderer.json_output import render_json
+
+        json_str = render_json(analyst_report)
+        if output:
+            Path(output).write_text(json_str)
+            console.print(f"[green]Report written to {output}[/green]")
+        else:
+            print(json_str)
+    else:
+        from git_pulse.renderer.terminal import render_terminal
+
+        render_terminal(
+            analyst_report=analyst_report,
+            collector_report=collector_report,
+            console=console,
+            verbose=verbose,
+        )
+        if output:
+            from git_pulse.renderer.json_output import render_json
+
+            Path(output).write_text(render_json(analyst_report))
+            console.print(f"\n[green]JSON report also written to {output}[/green]")

git_pulse/collector/git_history.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+from git import Repo
+
+
+# Patterns that indicate agent involvement
+AGENT_PATTERNS = [
+    re.compile(r"Co-Authored-By:\s*(.+)", re.IGNORECASE),
+    re.compile(r"\[(?:claude|copilot|cursor|aider|codeium|codex)\b", re.IGNORECASE),
+    re.compile(r"(?:generated|authored)\s+(?:by|with)\s+(\w+)", re.IGNORECASE),
+    re.compile(r"^aider:\s", re.IGNORECASE | re.MULTILINE),
+]
+
+
+class GitHistoryCollector:
+    def __init__(self, repo_path: str, branch: str | None = None):
+        self.repo = Repo(repo_path)
+        self.branch = branch or self.repo.active_branch.name
+
+    def collect(
+        self,
+        days: int | None = None,
+        commits: int | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+    ) -> list[dict]:
+        """Collect commit data from the repo. Returns list of commit dicts, most recent first."""
+        kwargs = {}
+        if days is not None:
+            since = datetime.now(timezone.utc) - timedelta(days=days)
+            kwargs["since"] = since.isoformat()
+        if commits is not None:
+            kwargs["max_count"] = commits
+
+        raw_commits = list(self.repo.iter_commits(self.branch, **kwargs))
+        result = []
+
+        for commit in raw_commits:
+            files = self._extract_files(commit, include, exclude)
+            is_agent, source = self._detect_attribution(commit.message)
+
+            result.append(
+                {
+                    "hash": commit.hexsha,
+                    "author": str(commit.author),
+                    "timestamp": commit.committed_datetime.isoformat(),
+                    "message": commit.message.strip(),
+                    "files": files,
+                    "is_agent_attributed": is_agent,
+                    "attribution_source": source,
+                }
+            )
+
+        return result
+
+    def _extract_files(self, commit, include, exclude) -> list[dict]:
+        """Extract file change data from a commit."""
+        if not commit.parents:
+            diffs = commit.diff(None, create_patch=True, R=True)
+        else:
+            diffs = commit.parents[0].diff(commit, create_patch=True)
+
+        files = []
+        for diff in diffs:
+            path = diff.b_path or diff.a_path
+            if not path:
+                continue
+            if include and not self._matches_any(path, include):
+                continue
+            if exclude and self._matches_any(path, exclude):
+                continue
+
+            diff_text = diff.diff.decode("utf-8", errors="replace") if diff.diff else ""
+            insertions = sum(1 for line in diff_text.splitlines() if line.startswith("+") and not line.startswith("+++"))
+            deletions = sum(1 for line in diff_text.splitlines() if line.startswith("-") and not line.startswith("---"))
+
+            files.append(
+                {
+                    "path": path,
+                    "insertions": insertions,
+                    "deletions": deletions,
+                    "diff": diff_text[:3000],
+                }
+            )
+
+        return files
+
+    def _detect_attribution(self, message: str) -> tuple[bool, str | None]:
+        """Check commit message for agent attribution markers."""
+        for pattern in AGENT_PATTERNS:
+            match = pattern.search(message)
+            if match:
+                return True, match.group(0).strip()
+        return False, None
+
+    @staticmethod
+    def _matches_any(path: str, patterns: list[str]) -> bool:
+        from fnmatch import fnmatch
+        return any(fnmatch(path, p) for p in patterns)

git_pulse/collector/hotspot_detector.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from git_pulse.collector.models import Hotspot
+
+
+# Max lines apart to be considered same region
+LINE_PROXIMITY = 5
+# Max hours apart to be considered same work session for hotspot grouping
+TIME_WINDOW_HOURS = 6
+
+
+class HotspotDetector:
+    def __init__(self, commits: list[dict], max_hotspots: int = 20):
+        self.commits = commits
+        self.max_hotspots = max_hotspots
+
+    def detect(self) -> list[Hotspot]:
+        """Detect hotspots from commit data. Returns ranked list."""
+        file_mods = self._group_modifications()
+        hotspots = []
+        for file_path, mods in file_mods.items():
+            clusters = self._cluster_modifications(mods)
+            for cluster in clusters:
+                if len(cluster) < 2:
+                    continue
+                hotspot = self._build_hotspot(file_path, cluster)
+                hotspots.append(hotspot)
+
+        hotspots.sort(key=lambda h: h.score, reverse=True)
+        return hotspots[: self.max_hotspots]
+
+    def _group_modifications(self) -> dict[str, list[dict]]:
+        """Group modifications by file path."""
+        file_mods: dict[str, list[dict]] = defaultdict(list)
+        for commit in self.commits:
+            ts = self._parse_timestamp(commit["timestamp"])
+            for f in commit["files"]:
+                line_start = self._parse_line_start(f["diff"])
+                file_mods[f["path"]].append(
+                    {
+                        "commit_hash": commit["hash"],
+                        "timestamp": ts,
+                        "line_start": line_start,
+                        "lines": f["insertions"] + f["deletions"],
+                        "diff_snippet": f["diff"][:500],
+                        "is_agent": commit["is_agent_attributed"],
+                        "attribution_source": commit.get("attribution_source"),
+                    }
+                )
+        return file_mods
+
+    def _cluster_modifications(self, mods: list[dict]) -> list[list[dict]]:
+        """Cluster modifications by spatiotemporal proximity."""
+        if not mods:
+            return []
+        mods.sort(key=lambda m: m["timestamp"])
+        clusters: list[list[dict]] = [[mods[0]]]
+        for mod in mods[1:]:
+            merged = False
+            for cluster in clusters:
+                if self._is_nearby(mod, cluster):
+                    cluster.append(mod)
+                    merged = True
+                    break
+            if not merged:
+                clusters.append([mod])
+        return clusters
+
+    def _is_nearby(self, mod: dict, cluster: list[dict]) -> bool:
+        """Check if mod is spatiotemporally close to any mod in the cluster."""
+        for existing in cluster:
+            time_diff = abs((mod["timestamp"] - existing["timestamp"]).total_seconds()) / 3600
+            line_diff = abs(mod["line_start"] - existing["line_start"])
+            if time_diff <= TIME_WINDOW_HOURS and line_diff <= LINE_PROXIMITY:
+                return True
+        return False
+
+    def _build_hotspot(self, file_path: str, cluster: list[dict]) -> Hotspot:
+        """Build a Hotspot from a cluster of modifications."""
+        timestamps = [m["timestamp"] for m in cluster]
+        time_span = (max(timestamps) - min(timestamps)).total_seconds() / 3600
+        time_span = max(time_span, 0.01)
+
+        line_starts = [m["line_start"] for m in cluster]
+        lines_affected = sum(m["lines"] for m in cluster)
+        mod_count = len(cluster)
+
+        score = (mod_count * 3) + (lines_affected * 0.5) + (1 / time_span * 10)
+        classification = self._classify(cluster)
+
+        return Hotspot(
+            file_path=file_path,
+            line_start=min(line_starts),
+            line_end=max(line_starts) + LINE_PROXIMITY,
+            modification_count=mod_count,
+            time_span_hours=round(time_span, 2),
+            classification=classification,
+            commit_hashes=[m["commit_hash"] for m in cluster],
+            diff_snippets=[m["diff_snippet"] for m in cluster],
+            score=round(score, 2),
+        )
+
+    def _classify(self, cluster: list[dict]) -> str:
+        """Classify the hotspot based on agent/human attribution patterns."""
+        agent_flags = [m["is_agent"] for m in cluster]
+        if not any(agent_flags):
+            if all(not f for f in agent_flags):
+                return "human-iteration"
+            return "unknown"
+
+        transitions = []
+        for i in range(len(agent_flags) - 1):
+            if agent_flags[i] and not agent_flags[i + 1]:
+                transitions.append("agent-to-human")
+            elif not agent_flags[i] and agent_flags[i + 1]:
+                transitions.append("human-to-agent")
+            elif agent_flags[i] and agent_flags[i + 1]:
+                transitions.append("agent-to-agent")
+
+        if not transitions:
+            return "unknown"
+
+        if transitions.count("agent-to-human") > len(transitions) / 2:
+            return "human-fixing-agent"
+        if transitions.count("agent-to-agent") > len(transitions) / 2:
+            return "repeated-agent"
+        if transitions.count("human-to-agent") > len(transitions) / 2:
+            return "agent-reworked"
+        return "unknown"
+
+    @staticmethod
+    def _parse_line_start(diff: str) -> int:
+        match = re.search(r"@@ -(\d+)", diff)
+        return int(match.group(1)) if match else 1
+
+    @staticmethod
+    def _parse_timestamp(ts: str) -> datetime:
+        return datetime.fromisoformat(ts)