mcp-vector-search 0.12.6__py3-none-any.whl → 1.0.3__py3-none-any.whl

mcp_vector_search/__init__.py

@@ -1,7 +1,7 @@
 """MCP Vector Search - CLI-first semantic code search with MCP integration."""
 
-__version__ = "0.12.6"
-__build__ = "55"
+__version__ = "1.0.3"
+__build__ = "93"
 __author__ = "Robert Matsuoka"
 __email__ = "bobmatnyc@gmail.com"
 

mcp_vector_search/analysis/__init__.py

@@ -0,0 +1,64 @@
+"""Structural code analysis module.
+
+This module provides dataclasses and interfaces for collecting and storing
+code quality metrics during semantic code analysis.
+
+Key Components:
+    - ChunkMetrics: Metrics for individual functions/methods/classes
+    - FileMetrics: Aggregated metrics for entire files
+    - ProjectMetrics: Project-wide metric aggregates
+    - MetricCollector: Abstract base class for metric collection
+    - CollectorContext: Shared context during AST traversal
+
+Example:
+    # Create chunk metrics
+    chunk = ChunkMetrics(
+        cognitive_complexity=8,
+        cyclomatic_complexity=5,
+        max_nesting_depth=3,
+        parameter_count=2,
+        lines_of_code=25
+    )
+
+    # Chunk automatically computes grade
+    assert chunk.complexity_grade == "B"  # 6-10 range
+
+    # Store in ChromaDB-compatible format
+    metadata = chunk.to_metadata()
+
+    # Aggregate file metrics
+    file_metrics = FileMetrics(
+        file_path="src/module.py",
+        chunks=[chunk]
+    )
+    file_metrics.compute_aggregates()
+
+    # Project-wide analysis
+    project = ProjectMetrics(project_root="/path/to/project")
+    project.files["src/module.py"] = file_metrics
+    project.compute_aggregates()
+    hotspots = project.get_hotspots(limit=5)
+"""
+
+from .collectors.base import CollectorContext, MetricCollector
+from .collectors.complexity import (
+    CognitiveComplexityCollector,
+    CyclomaticComplexityCollector,
+    MethodCountCollector,
+    NestingDepthCollector,
+    ParameterCountCollector,
+)
+from .metrics import ChunkMetrics, FileMetrics, ProjectMetrics
+
+__all__ = [
+    "ChunkMetrics",
+    "FileMetrics",
+    "ProjectMetrics",
+    "CollectorContext",
+    "MetricCollector",
+    "CognitiveComplexityCollector",
+    "CyclomaticComplexityCollector",
+    "NestingDepthCollector",
+    "ParameterCountCollector",
+    "MethodCountCollector",
+]

mcp_vector_search/analysis/collectors/__init__.py

@@ -0,0 +1,39 @@
+"""Metric collector implementations.
+
+This module provides the base interface and context for implementing
+metric collectors that traverse AST nodes during code analysis.
+
+Example:
+    from mcp_vector_search.analysis.collectors import MetricCollector, CollectorContext
+
+    class MyCollector(MetricCollector):
+        @property
+        def name(self) -> str:
+            return "my_collector"
+
+        def collect_node(self, node, context, depth):
+            # Process node
+            pass
+
+        def finalize_function(self, node, context):
+            return {"my_metric": 42}
+"""
+
+from .base import CollectorContext, MetricCollector
+from .complexity import (
+    CognitiveComplexityCollector,
+    CyclomaticComplexityCollector,
+    MethodCountCollector,
+    NestingDepthCollector,
+    ParameterCountCollector,
+)
+
+__all__ = [
+    "CollectorContext",
+    "MetricCollector",
+    "CognitiveComplexityCollector",
+    "CyclomaticComplexityCollector",
+    "NestingDepthCollector",
+    "ParameterCountCollector",
+    "MethodCountCollector",
+]

mcp_vector_search/analysis/collectors/base.py

@@ -0,0 +1,164 @@
+"""Base collector interface for metric collection during AST traversal."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+
+@dataclass
+class CollectorContext:
+    """Shared context passed to all collectors during AST traversal.
+
+    Provides state management for tracking the current position and scope
+    during tree-sitter AST traversal. All collectors receive the same
+    context instance and can read/modify it during traversal.
+
+    Attributes:
+        file_path: Path to the file being analyzed
+        source_code: Raw source code as bytes (required by tree-sitter)
+        language: Programming language identifier (e.g., "python", "javascript")
+        current_function: Name of the function currently being analyzed
+        current_class: Name of the class currently being analyzed
+        nesting_stack: Stack tracking nested scopes (for depth calculation)
+
+    Example:
+        context = CollectorContext(
+            file_path="/path/to/file.py",
+            source_code=b"def foo(): pass",
+            language="python"
+        )
+
+        # During traversal
+        context.current_function = "foo"
+        context.nesting_stack.append("function")
+        depth = len(context.nesting_stack)
+    """
+
+    file_path: str
+    source_code: bytes
+    language: str
+
+    # Accumulator for current function being analyzed
+    current_function: str | None = None
+    current_class: str | None = None
+
+    # Stack for tracking nesting
+    nesting_stack: list[str] = field(default_factory=list)
+
+
+class MetricCollector(ABC):
+    """Abstract base class for metric collectors.
+
+    Collectors implement the visitor pattern for AST traversal. Each collector
+    is responsible for tracking specific metrics (e.g., complexity, nesting)
+    during tree-sitter node traversal.
+
+    Lifecycle:
+    1. collect_node() called for each AST node during traversal
+    2. Collector accumulates state during traversal
+    3. finalize_function() called when exiting a function/method
+    4. reset() called to prepare for next function
+
+    Subclasses must implement:
+    - name: Unique identifier for the collector
+    - collect_node(): Process individual AST nodes
+    - finalize_function(): Return final metrics for completed function
+
+    Example Implementation:
+        class ComplexityCollector(MetricCollector):
+            def __init__(self):
+                self._complexity = 0
+
+            @property
+            def name(self) -> str:
+                return "complexity"
+
+            def collect_node(self, node: Node, context: CollectorContext, depth: int) -> None:
+                if node.type in ("if_statement", "while_statement"):
+                    self._complexity += 1
+
+            def finalize_function(self, node: Node, context: CollectorContext) -> dict[str, Any]:
+                return {"cognitive_complexity": self._complexity}
+
+            def reset(self) -> None:
+                self._complexity = 0
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for this collector.
+
+        Returns:
+            Collector name (e.g., "complexity", "nesting", "parameters")
+        """
+        pass
+
+    @abstractmethod
+    def collect_node(self, node: Node, context: CollectorContext, depth: int) -> None:
+        """Called for each AST node during traversal.
+
+        Collectors accumulate state here by examining node properties
+        and updating internal counters/state.
+
+        Args:
+            node: Current tree-sitter AST node being visited
+            context: Shared context with file info and current scope
+            depth: Current nesting depth in the AST
+
+        Example:
+            def collect_node(self, node, context, depth):
+                if node.type == "if_statement":
+                    self._if_count += 1
+                elif node.type == "for_statement":
+                    self._loop_count += 1
+        """
+        pass
+
+    @abstractmethod
+    def finalize_function(
+        self, node: Node, context: CollectorContext
+    ) -> dict[str, Any]:
+        """Called when exiting a function/method.
+
+        Returns final metrics for this function. The returned dictionary
+        should contain metric names as keys and their values.
+
+        Args:
+            node: The function/method definition node
+            context: Shared context with file info and scope
+
+        Returns:
+            Dictionary of metric names to values
+            Example: {"cognitive_complexity": 5, "max_nesting": 3}
+
+        Example:
+            def finalize_function(self, node, context):
+                return {
+                    "cognitive_complexity": self._complexity,
+                    "nesting_depth": self._max_depth
+                }
+        """
+        pass
+
+    def reset(self) -> None:
+        """Reset collector state for next function.
+
+        Called after finalize_function() to prepare the collector
+        for analyzing the next function/method.
+
+        Default implementation does nothing. Override if collector
+        maintains state that needs clearing.
+
+        Example:
+            def reset(self):
+                self._complexity = 0
+                self._nesting_stack.clear()
+                self._max_depth = 0
+        """
+        return  # Default no-op implementation - subclasses override if needed