feat: Enhance repository analysis with new hygiene metrics and API response structure

Author: MT-superdev

pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "langchain-google-vertexai>=2.1.2",
     "giturlparse>=0.1.0",
     "structlog>=24.1.0",
+    "gql[all]>=3.4.0",
 ]
 
 [project.optional-dependencies]

src/agents/base.py

@@ -90,13 +90,13 @@ async def _invoke_structured() -> T:
             exceptions=(Exception,),
         )
 
-    async def _execute_with_timeout(self, coro, timeout: float = 30.0):
+    async def _execute_with_timeout(self, coro, timeout: float = 60.0):
         """
         Execute a coroutine with timeout handling.
 
         Args:
             coro: The coroutine to execute
-            timeout: Timeout in seconds
+            timeout: Timeout in seconds (default: 60s for showcase stability)
 
         Returns:
             The result of the coroutine

src/agents/repository_analysis_agent/__init__.py

@@ -6,5 +6,27 @@
 """
 
 from src.agents.repository_analysis_agent.agent import RepositoryAnalysisAgent
+from src.agents.repository_analysis_agent.models import (
+    AnalysisState,
+    HygieneMetrics,
+    PRSignal,
+    RepoMetadata,
+    RepositoryAnalysisRequest,
+    RepositoryAnalysisResponse,
+    RepositoryFeatures,
+    RuleRecommendation,
+    parse_github_repo_identifier,
+)
 
-__all__ = ["RepositoryAnalysisAgent"]
+__all__ = [
+    "RepositoryAnalysisAgent",
+    "AnalysisState",
+    "HygieneMetrics",
+    "PRSignal",
+    "RepoMetadata",
+    "RepositoryAnalysisRequest",
+    "RepositoryAnalysisResponse",
+    "RepositoryFeatures",
+    "RuleRecommendation",
+    "parse_github_repo_identifier",
+]

src/agents/repository_analysis_agent/models.py

@@ -139,6 +139,30 @@ class HygieneMetrics(BaseModel):
     first_time_contributor_count: int = Field(
         ..., description="Count of unique first-time contributors in recent PRs (risk indicator)."
     )
+    ci_skip_rate: float = Field(
+        default=0.0,
+        description="Percentage (0.0-1.0) of PRs that skip CI checks via commit message.",
+    )
+    codeowner_bypass_rate: float = Field(
+        default=0.0,
+        description="Percentage (0.0-1.0) of PRs merged without required CODEOWNER approval. Detects governance violations.",
+    )
+    new_code_test_coverage: float = Field(
+        default=0.0,
+        description="Average ratio of test line additions relative to source code changes. Low values indicate untested contributions.",
+    )
+    issue_diff_mismatch_rate: float = Field(
+        default=0.0,
+        description="Percentage (0.0-1.0) of PRs where the linked issue doesn't semantically match the code diff. Detects low-effort contributions claiming to fix unrelated issues.",
+    )
+    ghost_contributor_rate: float = Field(
+        default=0.0,
+        description="Percentage (0.0-1.0) of PRs where the author never responded to review comments. Indicates drive-by contributions with no engagement.",
+    )
+    ai_generated_rate: float | None = Field(
+        default=None,
+        description="Percentage (0.0-1.0) of PRs flagged as AI-generated based on heuristic signatures (e.g., 'generated by Claude', 'Cursor'). Detects bulk AI spam.",
+    )
 
 
 class AnalysisState(BaseModel):

src/agents/repository_analysis_agent/nodes.py

@@ -183,77 +183,195 @@ async def fetch_pr_signals(state: AnalysisState) -> AnalysisState:
     It calculates HygieneMetrics from recent merged PRs to inform rule generation.
     """
     from src.agents.repository_analysis_agent.models import HygieneMetrics
+    from src.integrations.github.client import GitHubClient
 
     repo = state.repo_full_name
     if not repo:
         raise ValueError("Repository full name is missing in state.")
 
     logger.info("pr_signals_fetch_started", repo=repo)
 
+    # Extract owner and repo from full_name
     try:
-        # Fetch recent merged PRs (last 30)
-        pr_data_list = await github_client.fetch_recent_pull_requests(
-            repo_full_name=repo,
-            installation_id=None,  # Public repo access for now
-            limit=30,
-        )
+        owner, repo_name = repo.split("/", 1)
+    except ValueError as err:
+        raise ValueError(f"Invalid repo format: {repo}. Expected 'owner/repo'.") from err
+
+    # Initialize GraphQL-enabled client
+    client = GitHubClient()
+
+    try:
+        # Fetch PR hygiene stats using GraphQL (avoids N+1 problem)
+        pr_nodes = await client.fetch_pr_hygiene_stats(owner, repo_name)
 
-        if not pr_data_list:
+        if not pr_nodes:
             # New repo or no PRs - set default metrics to avoid LLM crash
             logger.warning(
                 "pr_signals_no_data", repo=repo, message="No merged PRs found. Using default hygiene metrics."
             )
             state.hygiene_summary = HygieneMetrics(
-                unlinked_issue_rate=0.0, average_pr_size=0, first_time_contributor_count=0
+                unlinked_issue_rate=0.0,
+                average_pr_size=0,
+                first_time_contributor_count=0,
+                issue_diff_mismatch_rate=0.0,
+                ghost_contributor_rate=0.0,
+                test_coverage_delta_avg=0.0,
+                codeowner_bypass_rate=0.0,
+                ai_generated_rate=0.0,
             )
             return state
 
-        # Convert raw PR data to PRSignal models
-        pr_signals = [_map_github_pr_to_signal(pr) for pr in pr_data_list]
-        state.pr_signals = pr_signals
-
-        # Calculate HygieneMetrics
-        total_prs = len(pr_signals)
-        unlinked_count = sum(1 for pr in pr_signals if not pr.has_linked_issue)
-        unlinked_rate = unlinked_count / total_prs if total_prs > 0 else 0.0
-
-        avg_pr_size = sum(pr.lines_changed for pr in pr_signals) // total_prs if total_prs > 0 else 0
-
-        first_timers = sum(1 for pr in pr_signals if pr.author_association in ["FIRST_TIME_CONTRIBUTOR", "NONE"])
+        # Calculate metrics from GraphQL response
+        total_prs = len(pr_nodes)
+
+        # Calculate average_pr_size from changedFiles
+        total_changed_files = sum(pr.get("changedFiles", 0) for pr in pr_nodes)
+        average_pr_size = total_changed_files / total_prs if total_prs > 0 else 0.0
+
+        # Calculate unlinked_issue_rate from closingIssuesReferences
+        unlinked_count = sum(1 for pr in pr_nodes if pr.get("closingIssuesReferences", {}).get("totalCount", 0) == 0)
+        unlinked_issue_rate = unlinked_count / total_prs if total_prs > 0 else 0.0
+
+        # Calculate engagement_rate (proxy for ghost contributor) from comments
+        total_comments = sum(pr.get("comments", {}).get("totalCount", 0) for pr in pr_nodes)
+        engagement_rate = total_comments / total_prs if total_prs > 0 else 0.0
+
+        # Legacy AI detection heuristic for demonstration
+        ai_generated_count = 0
+        for pr in pr_nodes:
+            body = (pr.get("body") or "").lower()
+            title = (pr.get("title") or "").lower()
+            ai_keywords = [
+                "generated by claude",
+                "cursor",
+                "copilot",
+                "chatgpt",
+                "ai-generated",
+                "llm",
+                "i am an ai",
+                "as an ai",
+            ]
+            if any(keyword in body or keyword in title for keyword in ai_keywords):
+                ai_generated_count += 1
+        ai_generated_rate = ai_generated_count / total_prs if total_prs > 0 else 0.0
+
+        # Calculate issue_diff_mismatch_rate
+        issue_diff_mismatch_count = 0
+        for pr in pr_nodes:
+            issue_title = ""
+            if pr.get("closingIssuesReferences", {}).get("nodes"):
+                issue_title = pr["closingIssuesReferences"]["nodes"][0].get("title", "").lower()
+
+            if issue_title:
+                changed_files = [edge["node"]["path"] for edge in pr.get("files", {}).get("edges", [])]
+
+                # Simple heuristic: check if any part of a changed file's path is in the issue title
+                mismatch = True
+                for file_path in changed_files:
+                    path_parts = file_path.split("/")
+                    if any(part in issue_title for part in path_parts if len(part) > 3):
+                        mismatch = False
+                        break
+                if mismatch:
+                    issue_diff_mismatch_count += 1
+
+        issue_diff_mismatch_rate = issue_diff_mismatch_count / total_prs if total_prs > 0 else 0.0
+
+        # Calculate codeowner_bypass_rate
+        codeowner_bypass_count = 0
+        for pr in pr_nodes:
+            reviews = pr.get("reviews", {}).get("nodes", [])
+            author = pr.get("author", {}).get("login")
+
+            # This is a simplified check. A real implementation would parse CODEOWNERS.
+            # For the demo, we assume any review from someone other than the author is sufficient.
+            approved = any(review["state"] == "APPROVED" and review["author"]["login"] != author for review in reviews)
+
+            if not approved:
+                # Simplified: if no approved review from another user, it might be a bypass.
+                # This doesn't actually check against CODEOWNERS file content.
+                codeowner_bypass_count += 1
+
+        codeowner_bypass_rate = codeowner_bypass_count / total_prs if total_prs > 0 else 0.0
+
+        # Calculate new_code_test_coverage
+        total_functions_added = 0
+        total_test_functions_added = 0
+        for pr in pr_nodes:
+            diff_content = pr.get("diff_content", "")
+            if diff_content:
+                lines = diff_content.split("\n")
+                for line in lines:
+                    if line.startswith("+") and not line.startswith("+++") and "def " in line:
+                        # Simple heuristic for Python: count new function definitions
+                        file_path_info = next((ln for ln in lines if ln.startswith("+++ b/")), None)
+                        if file_path_info:
+                            if "test" in file_path_info:
+                                total_test_functions_added += 1
+                            else:
+                                total_functions_added += 1
+
+        new_code_test_coverage = 0.0
+        if total_functions_added > 0:
+            new_code_test_coverage = total_test_functions_added / total_functions_added
 
         state.hygiene_summary = HygieneMetrics(
-            unlinked_issue_rate=unlinked_rate, average_pr_size=avg_pr_size, first_time_contributor_count=first_timers
+            unlinked_issue_rate=unlinked_issue_rate,
+            average_pr_size=int(average_pr_size),
+            first_time_contributor_count=0,  # Not available in GraphQL response
+            issue_diff_mismatch_rate=issue_diff_mismatch_rate,
+            ghost_contributor_rate=1.0 - min(engagement_rate / 5.0, 1.0),  # Inverse of engagement (normalized)
+            new_code_test_coverage=new_code_test_coverage,
+            codeowner_bypass_rate=codeowner_bypass_rate,
+            ai_generated_rate=ai_generated_rate,
         )
 
+        # Convert for legacy PRSignal compatibility
+        pr_signals = []
+        for pr in pr_nodes:
+            pr_signals.append(
+                PRSignal(
+                    pr_number=pr.get("number", 0),
+                    has_linked_issue=pr.get("closingIssuesReferences", {}).get("totalCount", 0) > 0,
+                    author_association="UNKNOWN",  # Not available in GraphQL query
+                    is_ai_generated_hint=any(
+                        keyword in (pr.get("body") or "").lower() + (pr.get("title") or "").lower()
+                        for keyword in ["generated by claude", "cursor", "copilot", "chatgpt", "ai-generated", "llm"]
+                    ),
+                    lines_changed=pr.get("changedFiles", 0),
+                )
+            )
+        state.pr_signals = pr_signals
+
         logger.info(
             "pr_signals_fetch_completed",
             repo=repo,
             total_prs=total_prs,
-            unlinked_rate=f"{unlinked_rate:.2%}",
-            avg_size=avg_pr_size,
-            first_timers=first_timers,
+            unlinked_rate=f"{unlinked_issue_rate:.2%}",
+            avg_size=int(average_pr_size),
+            engagement_rate=f"{engagement_rate:.2f}",
+            ai_rate=f"{ai_generated_rate:.2%}",
         )
 
         return state
 
-    except httpx.HTTPStatusError as e:
-        logger.error(
-            "pr_signals_fetch_failed",
+    except Exception as e:
+        logger.warning(
+            "pr_signals_graphql_fallback",
             repo=repo,
-            status_code=e.response.status_code,
-            error_type="network_error",
             error=str(e),
+            message="GraphQL failed, using safe defaults",
         )
-        # Set defaults on error
-        state.hygiene_summary = HygieneMetrics(
-            unlinked_issue_rate=0.0, average_pr_size=0, first_time_contributor_count=0
-        )
-        return state
-    except Exception as e:
-        logger.error("pr_signals_fetch_failed", repo=repo, error_type="unknown_error", error=str(e))
-        # Set defaults on error
+        # Set defaults on error - DO NOT crash the node
         state.hygiene_summary = HygieneMetrics(
-            unlinked_issue_rate=0.0, average_pr_size=0, first_time_contributor_count=0
+            unlinked_issue_rate=0.0,
+            average_pr_size=0,
+            first_time_contributor_count=0,
+            issue_diff_mismatch_rate=0.0,
+            ghost_contributor_rate=0.0,
+            test_coverage_delta_avg=0.0,
+            codeowner_bypass_rate=0.0,
+            ai_generated_rate=0.0,
         )
         return state
 

src/api/__init__.py

@@ -1 +1,10 @@
 # API endpoints package
+
+from src.api.recommendations import AnalysisResponse, AnalyzeRepoRequest, parse_repo_from_url, router
+
+__all__ = [
+    "AnalyzeRepoRequest",
+    "AnalysisResponse",
+    "parse_repo_from_url",
+    "router",
+]

src/api/recommendations.py

@@ -1,11 +1,11 @@
 import logging
+from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status
 from giturlparse import parse
 from pydantic import BaseModel, Field, HttpUrl
 
 from src.agents.repository_analysis_agent.agent import RepositoryAnalysisAgent
-from src.agents.repository_analysis_agent.models import RuleRecommendation
 from src.api.dependencies import get_current_user_optional
 from src.api.rate_limit import rate_limiter
 
@@ -35,9 +35,9 @@ class AnalysisResponse(BaseModel):
     Standardized response for the frontend.
     """
 
-    repository: str
-    is_public: bool
-    recommendations: list[RuleRecommendation]
+    rules_yaml: str
+    pr_plan: str
+    analysis_summary: dict[str, Any]
 
 
 # --- Helpers ---  # Utility—URL parsing brittle if GitHub changes format.
@@ -130,13 +130,32 @@ async def recommend_rules(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Analysis failed: {result.message}"
             )
 
-    # Step 5: Success—extract recommendations, return API response.
-    recommendations = result.data.get("recommendations", [])
+    # Step 5: Success—map agent state to the API response model.
+    final_state = result.data  # The agent's execute method returns the final state
+
+    # Generate rules_yaml from recommendations
+    import yaml
+
+    rules_output = {"rules": [rec.model_dump(exclude_none=True) for rec in final_state.get("recommendations", [])]}
+    rules_yaml = yaml.dump(rules_output, indent=2, sort_keys=False)
+
+    # Generate a markdown plan for the PR
+    pr_plan_lines = ["### Watchflow: Automated Governance Plan\n"]
+    for rec in final_state.get("recommendations", []):
+        pr_plan_lines.append(f"- **Rule:** `{rec.name}` (`{rec.key}`)")
+        pr_plan_lines.append(f"  - **Reasoning:** {rec.reasoning}")
+    pr_plan = "\n".join(pr_plan_lines)
+
+    # Populate the analysis summary from hygiene metrics
+    analysis_summary = {}
+    hygiene_summary = final_state.get("hygiene_summary")
+    if hygiene_summary:
+        analysis_summary = hygiene_summary.model_dump()
 
     return AnalysisResponse(
-        repository=repo_full_name,
-        is_public=True,  # Phase 1: always public—future: support private with token
-        recommendations=recommendations,
+        rules_yaml=rules_yaml,
+        pr_plan=pr_plan,
+        analysis_summary=analysis_summary,
     )