codespy-ai 0.3.0__tar.gz → 0.3.2__tar.gz

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespy-ai
-Version: 0.3.0
+Version: 0.3.2
 Summary: Code review agent powered by DSPy
 License: MIT
 License-File: LICENSE
@@ -537,7 +537,7 @@ export DEFAULT_MODEL=anthropic/claude-opus-4-6
 export DEFAULT_MAX_ITERS=20
 
 # Per-signature settings (use signature name, not module name)
-export CODE_AND_DOC_REVIEW_MODEL=anthropic/claude-sonnet-4-5-20250929
+export CODE_REVIEW_MODEL=anthropic/claude-sonnet-4-5-20250929
 
 # Output settings
 export OUTPUT_STDOUT=false
@@ -693,10 +693,12 @@ output_git: true
 │                             │                                       │
 │  ┌──────────────────────────▼─────────────────────────────────┐     │
 │  │              Parallel Review Modules                       │     │
-│  │  ┌──────────────┐  ┌──────────────────────────────────┐    │     │
-│  │  │Supply Chain  │  │     Code & Doc Reviewer          │    │     │
-│  │  │  Auditor     │  │  (defects + documentation)       │    │     │
-│  │  └──────────────┘  └──────────────────────────────────┘    │     │
+│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────┐            │     │
+│  │  │ Supply Chain │ │ Code         │ │   Doc    │            │     │
+│  │  │   Auditor    │ │ Reviewer     │ │ Reviewer │            │     │
+│  │  │              │ │ (bug+sec+    │ │          │            │     │
+│  │  │              │ │  smell)      │ │          │            │     │
+│  │  └──────────────┘ └──────────────┘ └──────────┘            │     │
 │  └──────────────────────────┬─────────────────────────────────┘     │
 │                             │                                       │
 │  ┌──────────────────────────▼─────────────────────────────────┐     │
@@ -739,8 +741,9 @@ The review is powered by DSPy signatures that structure the LLM's analysis:
 
 | Signature | Config Key | Description |
 |-----------|------------|-------------|
-| **ScopeIdentifierSignature** | `scope_identification` | Identifies code scopes (frontend, backend, infra, microservice in mono repo, etc...) |
-| **CodeAndDocReviewSignature** | `code_and_doc_review` | Detects verified bugs, security vulnerabilities, and stale/wrong documentation in a single pass |
+| **ScopeIdentifierSignature** | `scope` | Identifies code scopes (frontend, backend, infra, microservice in mono repo, etc...) |
+| **CodeReviewSignature** | `code_review` | Detects verified bugs, security vulnerabilities, removed defensive code, and code smells |
+| **DocReviewSignature** | `doc` | Detects stale or wrong documentation caused by code changes |
 | **SupplyChainSecuritySignature** | `supply_chain` | Analyzes artifacts (Dockerfiles) and dependencies for supply chain security |
 | **IssueDeduplicationSignature** | `deduplication` | LLM-powered deduplication of issues across reviewers |
 | **MRSummarySignature** | `summarization` | Generates summary, quality assessment, and recommendation |

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/README.md

@@ -486,7 +486,7 @@ export DEFAULT_MODEL=anthropic/claude-opus-4-6
 export DEFAULT_MAX_ITERS=20
 
 # Per-signature settings (use signature name, not module name)
-export CODE_AND_DOC_REVIEW_MODEL=anthropic/claude-sonnet-4-5-20250929
+export CODE_REVIEW_MODEL=anthropic/claude-sonnet-4-5-20250929
 
 # Output settings
 export OUTPUT_STDOUT=false
@@ -642,10 +642,12 @@ output_git: true
 │                             │                                       │
 │  ┌──────────────────────────▼─────────────────────────────────┐     │
 │  │              Parallel Review Modules                       │     │
-│  │  ┌──────────────┐  ┌──────────────────────────────────┐    │     │
-│  │  │Supply Chain  │  │     Code & Doc Reviewer          │    │     │
-│  │  │  Auditor     │  │  (defects + documentation)       │    │     │
-│  │  └──────────────┘  └──────────────────────────────────┘    │     │
+│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────┐            │     │
+│  │  │ Supply Chain │ │ Code         │ │   Doc    │            │     │
+│  │  │   Auditor    │ │ Reviewer     │ │ Reviewer │            │     │
+│  │  │              │ │ (bug+sec+    │ │          │            │     │
+│  │  │              │ │  smell)      │ │          │            │     │
+│  │  └──────────────┘ └──────────────┘ └──────────┘            │     │
 │  └──────────────────────────┬─────────────────────────────────┘     │
 │                             │                                       │
 │  ┌──────────────────────────▼─────────────────────────────────┐     │
@@ -688,8 +690,9 @@ The review is powered by DSPy signatures that structure the LLM's analysis:
 
 | Signature | Config Key | Description |
 |-----------|------------|-------------|
-| **ScopeIdentifierSignature** | `scope_identification` | Identifies code scopes (frontend, backend, infra, microservice in mono repo, etc...) |
-| **CodeAndDocReviewSignature** | `code_and_doc_review` | Detects verified bugs, security vulnerabilities, and stale/wrong documentation in a single pass |
+| **ScopeIdentifierSignature** | `scope` | Identifies code scopes (frontend, backend, infra, microservice in mono repo, etc...) |
+| **CodeReviewSignature** | `code_review` | Detects verified bugs, security vulnerabilities, removed defensive code, and code smells |
+| **DocReviewSignature** | `doc` | Detects stale or wrong documentation caused by code changes |
 | **SupplyChainSecuritySignature** | `supply_chain` | Analyzes artifacts (Dockerfiles) and dependencies for supply chain security |
 | **IssueDeduplicationSignature** | `deduplication` | LLM-powered deduplication of issues across reviewers |
 | **MRSummarySignature** | `summarization` | Generates summary, quality assessment, and recommendation |

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "codespy-ai"
-version = "0.3.0"
+version = "0.3.2"
 description = "Code review agent powered by DSPy"
 readme = "README.md"
 license = "MIT"

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/src/codespy/__init__.py

@@ -1,3 +1,3 @@
 """codespy - Code review agent powered by DSPy."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/src/codespy/agents/cost_tracker.py

@@ -206,8 +206,8 @@ class SignatureContext:
     3. Summing costs/tokens from new entries
     
     Usage:
-        with SignatureContext("code_and_doc_review", cost_tracker):
-            # All LLM calls here will be attributed to code_and_doc_review
+        with SignatureContext("code_review", cost_tracker):
+            # All LLM calls here will be attributed to code_review
             result = await agent.acall(...)
     """
     

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/src/codespy/agents/reviewer/models.py

@@ -23,6 +23,7 @@ class IssueCategory(str, Enum):
     SECURITY = "security"
     BUG = "bug"
     DOCUMENTATION = "documentation"
+    SMELL = "smell"
 
 
 class ScopeType(str, Enum):
@@ -107,7 +108,7 @@ class Issue(BaseModel):
 class SignatureStatsResult(BaseModel):
     """Statistics for a single signature's execution during review."""
 
-    name: str = Field(description="Signature name (e.g., code_and_doc_review, supply_chain)")
+    name: str = Field(description="Signature name (e.g., code_review, doc, scope, supply_chain, deduplication, summarization)")
     cost: float = Field(default=0.0, description="Cost in USD for this signature")
     tokens: int = Field(default=0, description="Tokens used by this signature")
     call_count: int = Field(default=0, description="Number of LLM calls made by this signature")
@@ -183,6 +184,11 @@ class ReviewResult(BaseModel):
         """Get all documentation issues."""
         return [i for i in self.issues if i.category == IssueCategory.DOCUMENTATION]
 
+    @property
+    def smell_issues(self) -> list[Issue]:
+        """Get all code smell issues."""
+        return [i for i in self.issues if i.category == IssueCategory.SMELL]
+
     def issues_by_severity(self) -> dict[IssueSeverity, list[Issue]]:
         """Group issues by severity."""
         result: dict[IssueSeverity, list[Issue]] = {s: [] for s in IssueSeverity}
@@ -218,6 +224,7 @@ class ReviewResult(BaseModel):
             f"- **Security:** {len(self.security_issues)}",
             f"- **Bugs:** {len(self.bug_issues)}",
             f"- **Documentation:** {len(self.documentation_issues)}",
+            f"- **Smells:** {len(self.smell_issues)}",
             "",
         ])
 

{codespy_ai-0.3.0 → codespy_ai-0.3.2}/src/codespy/agents/reviewer/modules/__init__.py

@@ -1,12 +1,14 @@
 """DSPy modules for code review."""
 
-from codespy.agents.reviewer.modules.code_and_doc_reviewer import CodeAndDocReviewer
+from codespy.agents.reviewer.modules.code_reviewer import CodeReviewer
 from codespy.agents.reviewer.modules.deduplicator import IssueDeduplicator
+from codespy.agents.reviewer.modules.doc_reviewer import DocReviewer
 from codespy.agents.reviewer.modules.scope_identifier import ScopeIdentifier
 from codespy.agents.reviewer.modules.supply_chain_auditor import SupplyChainAuditor
 
 __all__ = [
-    "CodeAndDocReviewer",
+    "CodeReviewer",
+    "DocReviewer",
     "IssueDeduplicator",
     "ScopeIdentifier",
     "SupplyChainAuditor",

codespy_ai-0.3.2/src/codespy/agents/reviewer/modules/code_reviewer.py

@@ -0,0 +1,266 @@
+"""Unified code review module — defects, security, and code smells."""
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any, Sequence
+
+import dspy  # type: ignore[import-untyped]
+
+from codespy.agents import SignatureContext, get_cost_tracker
+from codespy.agents.reviewer.models import Issue, IssueCategory, ScopeResult
+from codespy.agents.reviewer.modules.helpers import (
+    MIN_CONFIDENCE,
+    make_scope_relative,
+    resolve_scope_root,
+    restore_repo_paths,
+)
+from codespy.config import get_settings
+from codespy.tools.mcp_utils import cleanup_mcp_contexts, connect_mcp_server
+
+logger = logging.getLogger(__name__)
+
+
+class CodeReviewSignature(dspy.Signature):
+    """Detect VERIFIED code defects, security vulnerabilities, and code smells.
+
+    You are a busy Principal Engineer with very little time.
+    Be extremely terse. Use imperative mood ("Fix X", not "You should fix X").
+    You have tools to explore the scope's filesystem, search for text, and analyze code.
+    All file paths are relative to the scope root directory (the current tool root).
+    Tools are restricted to this scope — you cannot access files outside it.
+
+    ═══════════════════════════════════════════════════════════════════════════════
+    ANALYZE CHANGES
+    ═══════════════════════════════════════════════════════════════════════════════
+
+    Review each changed file's patch. For each file, check ALL categories (A, B, C)
+    before moving to the next file.
+
+    TOOLS AVAILABLE:
+    - find_function_definitions: check function signatures and implementations
+    - find_function_calls: understand how functions are called, trace data flow
+    - find_function_usages / find_callers: trace usage patterns
+    - search_literal: find related patterns (sanitization, validation, naming)
+    - read_file:broader context not visible in the patch (use sparingly)
+
+    ─── A. BUGS & LOGIC ERRORS (category = "bug") ───────────────────────────────
+
+    EVIDENCE STANDARD: STRICT — you must VERIFY with tools before reporting.
+    DO NOT speculate. No "might be", "could be", "possibly" issues.
+    If you cannot point to the EXACT defective code with evidence, do NOT report.
+
+    - Logic errors: verify the condition is actually incorrect by checking related code
+    - Null/undefined references: verify the check is actually missing
+    - Resource leaks: verify there's no cleanup in finally/defer/close methods
+    - Error handling: verify errors aren't handled elsewhere in the call chain
+    - Type mismatches: verify types by checking definitions
+    - Off-by-one errors: verify by understanding the data structure bounds
+
+    REMOVED DEFENSIVE CODE (always report as "bug"):
+    If a guard (bounds check, null check, Math.max/min, default value, try/catch,
+    sanitization) existed in removed lines (-) and is absent from added lines (+),
+    report it. Use read_file or search_literal to confirm the guard was not relocated
+    elsewhere in the same function/file. If it was moved, do not report.
+
+    ─── B. SECURITY VULNERABILITIES (category = "security") ─────────────────────
+
+    EVIDENCE STANDARD: STRICT — you must VERIFY with tools before reporting.
+    DO NOT speculate. Trace data flow from source to sink.
+
+    - Injection (SQL, command, XSS): verify input reaches dangerous sink unsanitized
+    - Authentication/authorization: verify auth check is actually missing
+    - Sensitive data exposure: verify data is actually exposed, not just accessed
+    - Insecure crypto: verify the actual algorithm used
+    - Path traversal: verify path input is not sanitized
+    - Race conditions: verify shared state access without synchronization
+
+    ─── C. CODE SMELLS (category = "smell") ──────────────────────────────────────
+
+    EVIDENCE STANDARD: OBSERVATIONAL — the patch or function signature IS the evidence.
+    A function with 5 primitive parameters IS a smell — no further verification needed.
+    A variable named "data" IS a smell — the name itself is the evidence.
+    Use tools to confirm if needed (e.g., find_function_definitions for param lists),
+    but the structural pattern visible in the patch is sufficient to report.
+
+    UNCOMMUNICATIVE NAMES:
+    - Variables not describing data they hold (data, info, item, temp, val)
+    - Functions not starting with a verb (user(), process())
+    - Booleans not reading as predicates (valid, flag → isValid, hasPermission)
+    - Side-effect mismatch: getName() that writes to DB
+
+    PRIMITIVE OBSESSION:
+    - Functions taking 3+ related primitive parameters that travel together
+      Example: (string zip, string city, string street) → suggest Address struct/class
+    - Use find_function_definitions to inspect parameter lists if not visible in patch
+
+    COMPLEXITY:
+    - Double negatives, nested ternaries, >2 logical operators per condition
+    - Magic numbers in logic → suggest named constants
+    - 3+ nesting levels → suggest guard clauses/early returns
+    - 5+ switch/if-elif branches → suggest polymorphism
+
+    YAGNI:
+    - Abstract class/interface with single implementation (verify with find_callers)
+    - Unused parameters accepted "for future use"
+
+    DO NOT report as smells:
+    - Idiomatic short names (i, j, k, err, ctx, db, tx)
+    - Test file naming conventions
+
+    ═══════════════════════════════════════════════════════════════════════════════
+    OUTPUT RULES
+    ═══════════════════════════════════════════════════════════════════════════════
+
+    - Set category to one of the values provided in the categories input
+    - For security issues, include cwe_id where applicable
+    - Reference files by name and line number only — never copy source code into issues
+    - Do not repeat patch content in reasoning steps. Keep each step to 1-2 sentences
+    - Empty list if no issues found. No approval text ("LGTM", "looks good")
+    - description: ≤25 words, imperative tone, no filler ("Fix X", "Rename Y to Z")
+    - No polite or conversational language
+    - Do not populate code_snippet — use line numbers instead
+    """
+
+    scope: ScopeResult = dspy.InputField(
+        desc="Scope with changed files. Has: subroot, scope_type, "
+        "changed_files (filename + patch - analyze patch first), language, package_manifest. "
+        "File paths in changed_files are relative to the scope root (tool root)."
+    )
+    categories: list[IssueCategory] = dspy.InputField(
+        desc="Allowed issue categories. Use only these values for the 'category' field on each issue."
+    )
+
+    issues: list[Issue] = dspy.OutputField(
+        desc="Verified issues. Category must be one of the provided categories. "
+        "Titles <10 words. Descriptions ≤25 words, imperative. Empty list if none. "
+        "File paths must be relative to scope root."
+    )
+
+
+class CodeReviewer(dspy.Module):
+    """Unified code reviewer — defects, security, and smells in a single pass.
+
+    Merges DefectDetector and SmellDetector into one agent to avoid redundant
+    README reads, tool sessions, and input token costs per scope.
+
+    MCP tools are scope-restricted: for each scope, tools are rooted at
+    repo_path/scope.subroot so the agent cannot access files outside the scope.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the code reviewer."""
+        super().__init__()
+        self._cost_tracker = get_cost_tracker()
+        self._settings = get_settings()
+
+    async def _create_tools(
+        self, scope_root: Path
+    ) -> tuple[list[Any], list[Any]]:
+        """Create scope-restricted tools: filesystem + ripgrep + treesitter."""
+        tools: list[Any] = []
+        contexts: list[Any] = []
+        tools_dir = Path(__file__).parent.parent.parent.parent / "tools"
+        scope_root_str = str(scope_root)
+        caller = "code_reviewer"
+
+        tools.extend(await connect_mcp_server(
+            tools_dir / "filesystem" / "server.py",
+            [scope_root_str], contexts, caller,
+        ))
+        tools.extend(await connect_mcp_server(
+            tools_dir / "parsers" / "ripgrep" / "server.py",
+            [scope_root_str], contexts, caller,
+        ))
+        tools.extend(await connect_mcp_server(
+            tools_dir / "parsers" / "treesitter" / "server.py",
+            [scope_root_str], contexts, caller,
+        ))
+        return tools, contexts
+
+    async def aforward(
+        self, scopes: Sequence[ScopeResult], repo_path: Path
+    ) -> list[Issue]:
+        """Analyze scopes for defects, security issues, and code smells.
+
+        Args:
+            scopes: List of identified scopes with their changed files
+            repo_path: Path to the cloned repository
+
+        Returns:
+            List of bug, security, and smell issues found across all scopes
+        """
+        if not self._settings.is_signature_enabled("code_review"):
+            logger.debug("Skipping code_review: disabled")
+            return []
+
+        # Determine which categories are active
+        categories: list[IssueCategory] = []
+        categories.append(IssueCategory.BUG)
+        categories.append(IssueCategory.SECURITY)
+        categories.append(IssueCategory.SMELL)
+
+        changed_scopes = [s for s in scopes if s.has_changes and s.changed_files]
+        if not changed_scopes:
+            logger.info("No scopes with changes for code review")
+            return []
+
+        all_issues: list[Issue] = []
+        max_iters = self._settings.get_max_iters("code_review")
+
+        total_files = sum(len(s.changed_files) for s in changed_scopes)
+        logger.info(
+            f"Code review for {len(changed_scopes)} scopes "
+            f"({total_files} changed files)..."
+        )
+
+        for scope in changed_scopes:
+            scope_root = resolve_scope_root(repo_path, scope.subroot)
+            tools, contexts = await self._create_tools(scope_root)
+            try:
+                agent = dspy.ReAct(
+                    signature=CodeReviewSignature,
+                    tools=tools,
+                    max_iters=max_iters,
+                )
+                scoped = make_scope_relative(scope)
+                logger.info(
+                    f"  Code review: scope {scope.subroot} "
+                    f"({len(scope.changed_files)} files)"
+                )
+                async with SignatureContext("code_review", self._cost_tracker):
+                    result = await agent.acall(
+                        scope=scoped,
+                        categories=categories,
+                    )
+
+                issues = [
+                    issue for issue in (result.issues or [])
+                    if issue.confidence >= MIN_CONFIDENCE
+                ]
+                restore_repo_paths(issues, scope.subroot)
+                all_issues.extend(issues)
+                logger.debug(
+                    f"  Scope {scope.subroot}: {len(issues)} code review issues"
+                )
+            except Exception as e:
+                logger.error(f"Code review failed for scope {scope.subroot}: {e}")
+            finally:
+                await cleanup_mcp_contexts(contexts)
+
+        logger.info(f"Code review found {len(all_issues)} issues")
+        return all_issues
+
+    def forward(
+        self, scopes: Sequence[ScopeResult], repo_path: Path
+    ) -> list[Issue]:
+        """Analyze scopes for code issues (sync wrapper).
+
+        Args:
+            scopes: List of identified scopes with their changed files
+            repo_path: Path to the cloned repository
+
+        Returns:
+            List of bug, security, and smell issues found across all scopes
+        """
+        return asyncio.run(self.aforward(scopes, repo_path))

codespy_ai-0.3.2/src/codespy/agents/reviewer/modules/doc_extractor.py

@@ -0,0 +1,80 @@
+"""Deterministic documentation extractor — single tree scan, no LLM."""
+
+import logging
+import re
+from pathlib import Path
+
+from codespy.tools.filesystem.client import FileSystem
+from codespy.tools.filesystem.models import EntryType, TreeNode
+
+logger = logging.getLogger(__name__)
+
+# Filename patterns recognised as documentation (case-insensitive).
+_DOC_FILE_RE = re.compile(
+    r"^(readme|changelog|contributing|\.env\.example)",
+    re.IGNORECASE,
+)
+# Top-level directory names whose *entire* contents count as docs.
+_DOC_DIRS = {"docs", "documentation"}
+
+
+def _collect_all_files(node: TreeNode, prefix: str) -> list[str]:
+    """Recursively collect all file paths under a tree node."""
+    paths: list[str] = []
+    for child in node.children:
+        rel = f"{prefix}{child.name}"
+        if child.entry_type == EntryType.DIRECTORY:
+            paths.extend(_collect_all_files(child, f"{rel}/"))
+        else:
+            paths.append(rel)
+    return paths
+
+
+def _collect_doc_paths(node: TreeNode, prefix: str = "") -> list[str]:
+    """Walk a shallow tree and return relative paths of doc files.
+
+    Matches:
+    - Root-level files: README*, CHANGELOG*, CONTRIBUTING*, .env.example
+    - Everything under docs/ or documentation/ directories
+    """
+    paths: list[str] = []
+    for child in node.children:
+        rel = f"{prefix}{child.name}" if prefix else child.name
+        if child.entry_type == EntryType.DIRECTORY:
+            if child.name.lower() in _DOC_DIRS:
+                paths.extend(_collect_all_files(child, f"{rel}/"))
+            else:
+                # Recurse into non-doc subdirs (depth-2 tree already limits this).
+                paths.extend(_collect_doc_paths(child, f"{rel}/"))
+        elif _DOC_FILE_RE.match(child.name):
+            paths.append(rel)
+    return paths
+
+
+def extract_documentation(scope_root: Path) -> str:
+    """Extract documentation content from a scope directory.
+
+    Single tree scan at depth 2, fast-fail if no doc files found.
+
+    Returns:
+        Concatenated documentation with ``=== filename ===`` headers,
+        or empty string if no documentation exists.
+    """
+    fs = FileSystem(scope_root, create_if_missing=False)
+
+    # One tree scan — depth 2 covers root files + immediate subdirs.
+    tree = fs.get_tree(max_depth=2)
+    doc_paths = _collect_doc_paths(tree)
+
+    if not doc_paths:
+        return ""
+
+    parts: list[str] = []
+    for path in doc_paths:
+        try:
+            content = fs.read_file(path)
+            parts.append(f"=== {path} ===\n{content.content}")
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"Could not read doc file {path}: {e}")
+
+    return "\n\n".join(parts)