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

mcp_vector_search/parsers/python.py

@@ -181,18 +181,148 @@ class PythonParser(BaseParser):
 
         return chunks
 
+    def _extract_class_skeleton(self, node, lines: list[str], file_path: Path) -> str:
+        """Extract class skeleton with method signatures only (no method bodies).
+
+        This reduces redundancy since method chunks contain full implementations.
+        """
+        skeleton_lines = []
+
+        # Find the class body block
+        class_block = None
+        for child in node.children:
+            if child.type == "block":
+                class_block = child
+                break
+
+        if not class_block:
+            # No block found, return full class content
+            start_line = node.start_point[0] + 1
+            end_line = node.end_point[0] + 1
+            return self._get_line_range(lines, start_line, end_line)
+
+        # Add class definition line(s) and decorators (everything before the block)
+        # but NOT the block's opening line (to avoid duplicating the docstring)
+        class_start = node.start_point[0]
+        block_start = class_block.start_point[0]
+
+        for line_idx in range(class_start, block_start):
+            if line_idx < len(lines):
+                line = lines[line_idx].rstrip()
+                # Add the line, ensuring we get the colon on the class definition
+                skeleton_lines.append(line)
+
+        # Add the colon line if it wasn't already added
+        if skeleton_lines and not skeleton_lines[-1].rstrip().endswith(":"):
+            # The class definition might span multiple lines
+            # Find and add up to the colon
+            for line_idx in range(class_start, block_start + 1):
+                if line_idx < len(lines):
+                    line = lines[line_idx].rstrip()
+                    if line not in [s.rstrip() for s in skeleton_lines]:
+                        skeleton_lines.append(line)
+                    if line.endswith(":"):
+                        break
+
+        # Process class body - add class variables and method signatures
+        indent = "    "  # Standard Python indent
+        docstring_added = False
+
+        for stmt in class_block.children:
+            if stmt.type == "expression_statement":
+                # Check if it's a docstring (first statement after class def)
+                for expr_child in stmt.children:
+                    if expr_child.type == "string":
+                        # Add docstring only once
+                        if not docstring_added:
+                            doc_start = stmt.start_point[0]
+                            doc_end = stmt.end_point[0]
+                            for line_idx in range(doc_start, doc_end + 1):
+                                if line_idx < len(lines):
+                                    skeleton_lines.append(lines[line_idx].rstrip())
+                            docstring_added = True
+                        break
+                else:
+                    # Not a docstring - could be a class variable assignment
+                    # Add it to the skeleton
+                    stmt_start = stmt.start_point[0]
+                    stmt_end = stmt.end_point[0]
+                    for line_idx in range(stmt_start, stmt_end + 1):
+                        if line_idx < len(lines):
+                            skeleton_lines.append(lines[line_idx].rstrip())
+
+            elif stmt.type in ("assignment", "annotated_assignment"):
+                # Class variable - add it
+                stmt_start = stmt.start_point[0]
+                stmt_end = stmt.end_point[0]
+                for line_idx in range(stmt_start, stmt_end + 1):
+                    if line_idx < len(lines):
+                        skeleton_lines.append(lines[line_idx].rstrip())
+
+            elif stmt.type == "function_definition":
+                # Method - add only the signature (no body)
+                _ = self._get_node_name(stmt)  # Not used, but validates method
+
+                # Add decorators
+                for deco_child in stmt.children:
+                    if deco_child.type == "decorator":
+                        deco_line = deco_child.start_point[0]
+                        if deco_line < len(lines):
+                            skeleton_lines.append(lines[deco_line].rstrip())
+
+                # Add the def line (with parameters and return type)
+                def_line_start = stmt.start_point[0]
+
+                # Find where the actual body starts (after the colon)
+                # We want everything up to and including the colon
+                for child in stmt.children:
+                    if child.type == "block":
+                        # The block starts after the colon
+                        # Get lines up to the colon
+                        block_line = child.start_point[0]
+                        for line_idx in range(def_line_start, block_line + 1):
+                            if line_idx < len(lines):
+                                line = lines[line_idx].rstrip()
+                                skeleton_lines.append(line)
+                                # Stop if we've added the colon line
+                                if ":" in line:
+                                    break
+
+                        # Check if there's a docstring in the method
+                        for block_child in child.children:
+                            if block_child.type == "expression_statement":
+                                for expr_child in block_child.children:
+                                    if expr_child.type == "string":
+                                        # Add method docstring
+                                        doc_start = block_child.start_point[0]
+                                        doc_end = block_child.end_point[0]
+                                        for line_idx in range(doc_start, doc_end + 1):
+                                            if line_idx < len(lines):
+                                                skeleton_lines.append(
+                                                    lines[line_idx].rstrip()
+                                                )
+                                        break
+                                break
+
+                        # Add placeholder for method body
+                        skeleton_lines.append(f"{indent}{indent}...")
+                        skeleton_lines.append("")  # Blank line between methods
+                        break
+
+        return "\n".join(skeleton_lines)
+
     def _extract_class(
         self, node, lines: list[str], file_path: Path
     ) -> list[CodeChunk]:
-        """Extract class definition as a chunk."""
+        """Extract class definition as a chunk (skeleton only, no method bodies)."""
         chunks = []
 
         class_name = self._get_node_name(node)
         start_line = node.start_point[0] + 1
         end_line = node.end_point[0] + 1
 
-        # Get class content
-        content = self._get_line_range(lines, start_line, end_line)
+        # Get class skeleton (without method bodies)
+        content = self._extract_class_skeleton(node, lines, file_path)
 
         # Extract docstring if present
         docstring = self._extract_docstring(node, lines)
@@ -339,11 +469,16 @@ class PythonParser(BaseParser):
             class_content = self._get_line_range(lines, start_line, end_line)
 
             if class_content.strip():  # Only add if content is not empty
+                # Extract class skeleton (method signatures only)
+                skeleton_content = self._extract_class_skeleton_regex(
+                    class_content, start_line, lines
+                )
+
                 # Extract class docstring
-                docstring = self._extract_docstring_regex(class_content)
+                docstring = self._extract_docstring_regex(skeleton_content)
 
                 chunk = self._create_chunk(
-                    content=class_content,
+                    content=skeleton_content,
                     file_path=file_path,
                     start_line=start_line,
                     end_line=end_line,
@@ -397,6 +532,151 @@ class PythonParser(BaseParser):
         """Find the end line of a class using indentation."""
         return self._find_function_end(lines, start_line)
 
+    def _extract_class_skeleton_regex(
+        self, class_content: str, start_line: int, all_lines: list[str]
+    ) -> str:
+        """Extract class skeleton using regex (fallback when tree-sitter unavailable).
+
+        Returns class with method signatures only, no method bodies.
+        """
+        lines = class_content.splitlines()
+        skeleton_lines = []
+        i = 0
+
+        # Get class definition line(s)
+        while i < len(lines):
+            line = lines[i]
+            skeleton_lines.append(line)
+            # Stop at the colon that ends the class definition
+            if line.rstrip().endswith(":"):
+                i += 1
+                break
+            i += 1
+
+        # Track indentation level
+        class_indent = None
+        if skeleton_lines:
+            first_line = skeleton_lines[0]
+            class_indent = len(first_line) - len(first_line.lstrip())
+
+        # Process class body
+        in_method = False
+        method_indent = None
+
+        while i < len(lines):
+            line = lines[i]
+            stripped = line.strip()
+
+            if not stripped:
+                # Keep blank lines if not in a method body
+                if not in_method:
+                    skeleton_lines.append(line)
+                i += 1
+                continue
+
+            # Calculate indentation
+            current_indent = len(line) - len(line.lstrip())
+
+            # Check if we're back at class level or beyond
+            if class_indent is not None and current_indent <= class_indent and stripped:
+                # End of class
+                break
+
+            # Check if this is a method definition
+            if re.match(r"^\s*(async\s+)?def\s+\w+", line):
+                in_method = True
+                method_indent = current_indent
+
+                # Add any decorators before this method
+                # (look backwards for @ lines)
+                j = i - 1
+                decorator_lines = []
+                while j >= 0:
+                    prev_line = lines[j]
+                    if prev_line.strip().startswith("@"):
+                        decorator_lines.insert(0, prev_line)
+                        j -= 1
+                    elif prev_line.strip():
+                        break
+                    else:
+                        j -= 1
+
+                # Remove decorators if we already added them
+                if decorator_lines:
+                    # Check if they're not already in skeleton_lines
+                    for dec in decorator_lines:
+                        if dec not in skeleton_lines[-len(decorator_lines) :]:
+                            skeleton_lines.append(dec)
+
+                # Add method signature line
+                skeleton_lines.append(line)
+
+                # Check if there's a docstring on next lines
+                j = i + 1
+                while j < len(lines):
+                    next_line = lines[j]
+                    next_stripped = next_line.strip()
+
+                    if not next_stripped:
+                        j += 1
+                        continue
+
+                    # Check for docstring
+                    if next_stripped.startswith('"""') or next_stripped.startswith(
+                        "'''"
+                    ):
+                        quote_type = next_stripped[:3]
+                        # Add docstring
+                        skeleton_lines.append(next_line)
+                        if not (
+                            next_stripped.endswith(quote_type)
+                            and len(next_stripped) > 6
+                        ):
+                            # Multi-line docstring
+                            j += 1
+                            while j < len(lines):
+                                doc_line = lines[j]
+                                skeleton_lines.append(doc_line)
+                                if doc_line.strip().endswith(quote_type):
+                                    j += 1
+                                    break
+                                j += 1
+                        else:
+                            j += 1
+                        break
+                    else:
+                        break
+
+                # Add placeholder for method body
+                if method_indent is not None:
+                    skeleton_lines.append(" " * (method_indent + 4) + "...")
+                else:
+                    skeleton_lines.append("        ...")
+
+                i += 1
+                continue
+
+            # Check if we're still in a method
+            if in_method:
+                if method_indent is not None and current_indent <= method_indent:
+                    # End of method
+                    in_method = False
+                    # Don't skip this line, process it in next iteration
+                    continue
+                else:
+                    # Inside method body - skip it
+                    i += 1
+                    continue
+
+            # Class-level statement (not a method)
+            # This could be a class variable, docstring, etc.
+            if current_indent > (class_indent or 0):
+                skeleton_lines.append(line)
+
+            i += 1
+
+        return "\n".join(skeleton_lines)
+
     def _extract_docstring_regex(self, content: str) -> str | None:
         """Extract docstring using regex patterns."""
         # Look for triple-quoted strings at the beginning of the content

mcp_vector_search/utils/__init__.py

@@ -6,6 +6,7 @@ from .gitignore import (
     create_gitignore_parser,
     is_path_gitignored,
 )
+from .gitignore_updater import ensure_gitignore_entry
 from .timing import (
     PerformanceProfiler,
     SearchProfiler,
@@ -24,6 +25,7 @@ __all__ = [
     "GitignorePattern",
     "create_gitignore_parser",
     "is_path_gitignored",
+    "ensure_gitignore_entry",
     # Timing utilities
     "PerformanceProfiler",
     "TimingResult",

mcp_vector_search/utils/gitignore.py

@@ -65,9 +65,6 @@ class GitignorePattern:
                 parent = "/".join(path_parts[:i])
                 if fnmatch.fnmatch(parent, pattern):
                     return True
-            # If no parent matches and this is not a directory, don't exclude
-            if not is_directory:
-                return False
 
         # Try exact match first
         if fnmatch.fnmatch(path, pattern):

mcp_vector_search/utils/gitignore_updater.py

@@ -0,0 +1,212 @@
+"""Gitignore file update utilities for automatic .gitignore entry management."""
+
+from pathlib import Path
+
+from loguru import logger
+
+
+def ensure_gitignore_entry(
+    project_root: Path,
+    pattern: str = ".mcp-vector-search/",
+    comment: str | None = "MCP Vector Search index directory",
+    create_if_missing: bool = True,
+) -> bool:
+    """Ensure a pattern exists in .gitignore file.
+
+    This function safely adds a pattern to .gitignore if it doesn't already exist.
+    It handles various edge cases including:
+    - Non-existent .gitignore files (creates if in git repo)
+    - Empty .gitignore files
+    - Existing patterns in various formats
+    - Negation patterns (conflict detection)
+    - Permission errors
+    - Encoding issues
+
+    Design Decision: Non-Blocking Operation
+    ----------------------------------------
+    This function is designed to be non-critical and non-blocking. It will:
+    - NEVER raise exceptions (returns False on errors)
+    - Log warnings for failures instead of blocking
+    - Allow project initialization to continue even if gitignore update fails
+
+    Rationale: .gitignore updates are a quality-of-life improvement, not a
+    requirement for mcp-vector-search functionality. Users can manually add
+    the entry if automatic update fails.
+
+    Pattern Detection Strategy
+    --------------------------
+    The function checks for semantic equivalents of the pattern:
+    - `.mcp-vector-search/` (exact match)
+    - `.mcp-vector-search` (without trailing slash)
+    - `.mcp-vector-search/*` (with wildcard)
+    - `/.mcp-vector-search/` (root-relative)
+
+    All are treated as equivalent to avoid duplicate entries.
+
+    Edge Cases Handled
+    ------------------
+    1. .gitignore does not exist -> Create (if in git repo)
+    2. .gitignore is empty -> Add pattern
+    3. Pattern already exists -> Skip (log debug)
+    4. Similar pattern exists -> Skip (log debug)
+    5. Negation pattern exists -> Warn and skip (respects user intent)
+    6. Not a git repository -> Skip (no .gitignore needed)
+    7. Permission denied -> Warn and skip (log manual instructions)
+    8. Encoding errors -> Try fallback encoding
+    9. Missing parent directory -> Should not occur (project_root exists)
+    10. Concurrent modification -> Safe (append operation is atomic-ish)
+
+    Args:
+        project_root: Project root directory (must exist)
+        pattern: Pattern to add to .gitignore (default: .mcp-vector-search/)
+        comment: Optional comment to add before the pattern
+        create_if_missing: Create .gitignore if it doesn't exist (default: True)
+
+    Returns:
+        True if pattern was added or already exists, False on error
+
+    Performance:
+        - Time Complexity: O(n) where n = lines in .gitignore (typically <1000)
+        - Space Complexity: O(n) for reading file into memory
+        - Expected Runtime: <10ms for typical .gitignore files
+
+    Notes:
+        - Only creates .gitignore in git repositories (checks for .git directory)
+        - Preserves existing file structure and encoding (UTF-8)
+        - Handles negation patterns gracefully (warns but doesn't override)
+        - Non-blocking: logs warnings instead of raising exceptions
+
+    Examples:
+        >>> # Basic usage during project initialization
+        >>> ensure_gitignore_entry(Path("/path/to/project"))
+        True
+
+        >>> # Custom pattern with custom comment
+        >>> ensure_gitignore_entry(
+        ...     Path("/path/to/project"),
+        ...     pattern=".custom-dir/",
+        ...     comment="Custom tool directory"
+        ... )
+        True
+
+        >>> # Don't create .gitignore if missing
+        >>> ensure_gitignore_entry(
+        ...     Path("/path/to/project"),
+        ...     create_if_missing=False
+        ... )
+        False
+    """
+    gitignore_path = project_root / ".gitignore"
+
+    # Edge Case 1: Check if this is a git repository
+    # Only create/modify .gitignore in git repositories to avoid polluting non-git projects
+    git_dir = project_root / ".git"
+    if not git_dir.exists():
+        logger.debug(
+            "Not a git repository (no .git directory), skipping .gitignore update"
+        )
+        return False
+
+    try:
+        # Edge Case 2: Handle non-existent .gitignore
+        if not gitignore_path.exists():
+            if not create_if_missing:
+                logger.debug(".gitignore does not exist and create_if_missing=False")
+                return False
+
+            # Create new .gitignore with the pattern
+            content = f"# {comment}\n{pattern}\n" if comment else f"{pattern}\n"
+            gitignore_path.write_text(content, encoding="utf-8")
+            logger.info(f"Created .gitignore with {pattern} entry")
+            return True
+
+        # Read existing content with UTF-8 encoding
+        try:
+            content = gitignore_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            # Edge Case 8: Fallback to more lenient encoding
+            logger.debug("UTF-8 decode failed, trying with error replacement")
+            try:
+                content = gitignore_path.read_text(encoding="utf-8", errors="replace")
+            except Exception as e:
+                logger.warning(
+                    f"Failed to read .gitignore due to encoding error: {e}. "
+                    f"Please manually add '{pattern}' to your .gitignore"
+                )
+                return False
+
+        # Edge Case 3: Handle empty .gitignore
+        stripped_content = content.strip()
+        if not stripped_content:
+            content = f"# {comment}\n{pattern}\n" if comment else f"{pattern}\n"
+            gitignore_path.write_text(content, encoding="utf-8")
+            logger.info(f"Added {pattern} to empty .gitignore")
+            return True
+
+        # Check for existing patterns (Edge Cases 4, 5, 6)
+        lines = content.split("\n")
+        normalized_pattern = pattern.rstrip("/").lstrip("/")
+
+        for line in lines:
+            # Skip comments and empty lines
+            stripped_line = line.strip()
+            if not stripped_line or stripped_line.startswith("#"):
+                continue
+
+            # Edge Case 6: Check for negation pattern (conflict)
+            # Negation patterns indicate explicit user intent to track the directory
+            if stripped_line.startswith("!") and normalized_pattern in stripped_line:
+                logger.warning(
+                    f".gitignore contains negation pattern: {stripped_line}. "
+                    "This indicates you want to track .mcp-vector-search/ in git. "
+                    "Skipping automatic entry to respect your configuration."
+                )
+                return False
+
+            # Normalize line for comparison
+            normalized_line = stripped_line.rstrip("/").lstrip("/")
+
+            # Edge Cases 4 & 5: Check for exact or similar matches
+            # These patterns are semantically equivalent for .gitignore:
+            # - .mcp-vector-search/
+            # - .mcp-vector-search
+            # - .mcp-vector-search/*
+            # - /.mcp-vector-search/
+            if (
+                normalized_line == normalized_pattern
+                or normalized_line == normalized_pattern + "/*"
+            ):
+                logger.debug(f"Pattern already exists in .gitignore: {stripped_line}")
+                return True
+
+        # Pattern doesn't exist, add it
+        # Preserve file structure: ensure proper newline handling
+        if not content.endswith("\n"):
+            content += "\n"
+
+        # Add blank line before comment for visual separation
+        content += "\n"
+
+        if comment:
+            content += f"# {comment}\n"
+        content += f"{pattern}\n"
+
+        # Write back to file
+        gitignore_path.write_text(content, encoding="utf-8")
+        logger.info(f"Added {pattern} to .gitignore")
+        return True
+
+    except PermissionError:
+        # Edge Case 7: Handle read-only .gitignore or protected directory
+        logger.warning(
+            f"Cannot update .gitignore: Permission denied. "
+            f"Please manually add '{pattern}' to your .gitignore file at {gitignore_path}"
+        )
+        return False
+    except Exception as e:
+        # Catch-all for unexpected errors (don't block initialization)
+        logger.warning(
+            f"Failed to update .gitignore: {e}. "
+            f"Please manually add '{pattern}' to your .gitignore"
+        )
+        return False

mcp_vector_search/utils/monorepo.py

@@ -6,6 +6,34 @@ from typing import NamedTuple
 
 from loguru import logger
 
+# Directories to exclude from subproject detection
+# These are typically test/example/docs directories, not actual subprojects
+EXCLUDED_SUBPROJECT_DIRS = {
+    "tests",
+    "test",
+    "examples",
+    "example",
+    "docs",
+    "doc",
+    "scripts",
+    "tools",
+    "benchmarks",
+    "benchmark",
+    "node_modules",
+    ".git",
+    ".github",
+    ".gitlab",
+    "build",
+    "dist",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "coverage",
+    ".coverage",
+    "htmlcov",
+}
+
 
 class Subproject(NamedTuple):
     """Represents a subproject in a monorepo."""
@@ -27,6 +55,23 @@ class MonorepoDetector:
         self.project_root = project_root
         self._subprojects: list[Subproject] | None = None
 
+    def _is_excluded_path(self, path: Path) -> bool:
+        """Check if a path should be excluded from subproject detection.
+
+        Args:
+            path: Path to check (relative to project root)
+
+        Returns:
+            True if path should be excluded from subproject detection
+        """
+        try:
+            relative_path = path.relative_to(self.project_root)
+            # Check if any part of the path is in the excluded set
+            return any(part in EXCLUDED_SUBPROJECT_DIRS for part in relative_path.parts)
+        except ValueError:
+            # Path is not relative to project root
+            return True
+
     def is_monorepo(self) -> bool:
         """Check if project is a monorepo.
 
@@ -162,6 +207,13 @@ class MonorepoDetector:
             if base_path.exists():
                 for subdir in base_path.iterdir():
                     if subdir.is_dir() and not subdir.name.startswith("."):
+                        # Skip excluded directories
+                        if self._is_excluded_path(subdir):
+                            logger.debug(
+                                f"Skipping excluded nx workspace path: {subdir.relative_to(self.project_root)}"
+                            )
+                            continue
+
                         package_json = subdir / "package.json"
                         name = self._get_package_name(package_json) or subdir.name
                         relative = str(subdir.relative_to(self.project_root))
@@ -179,14 +231,17 @@ class MonorepoDetector:
 
         # Only search up to 3 levels deep
         for package_json in self.project_root.rglob("package.json"):
-            # Skip node_modules
-            if "node_modules" in package_json.parts:
-                continue
-
             # Skip root package.json
             if package_json.parent == self.project_root:
                 continue
 
+            # Skip excluded directories (tests, examples, docs, etc.)
+            if self._is_excluded_path(package_json.parent):
+                logger.debug(
+                    f"Skipping excluded path: {package_json.relative_to(self.project_root)}"
+                )
+                continue
+
             # Check depth
             relative_parts = package_json.relative_to(self.project_root).parts
             if len(relative_parts) > 4:  # Too deep
@@ -223,6 +278,13 @@ class MonorepoDetector:
                 if path.name.startswith("."):
                     continue
 
+                # Skip excluded directories (tests, examples, docs, etc.)
+                if self._is_excluded_path(path):
+                    logger.debug(
+                        f"Skipping excluded workspace path: {path.relative_to(self.project_root)}"
+                    )
+                    continue
+
                 # Try to get name from package.json
                 package_json = path / "package.json"
                 name = self._get_package_name(package_json) or path.name

mcp_vector_search/utils/timing.py

@@ -142,12 +142,16 @@ class PerformanceProfiler:
             "min": min(durations),
             "max": max(durations),
             "std_dev": statistics.stdev(durations) if len(durations) > 1 else 0.0,
-            "p95": statistics.quantiles(durations, n=20)[18]
-            if len(durations) >= 20
-            else max(durations),
-            "p99": statistics.quantiles(durations, n=100)[98]
-            if len(durations) >= 100
-            else max(durations),
+            "p95": (
+                statistics.quantiles(durations, n=20)[18]
+                if len(durations) >= 20
+                else max(durations)
+            ),
+            "p99": (
+                statistics.quantiles(durations, n=100)[98]
+                if len(durations) >= 100
+                else max(durations)
+            ),
         }
 
     def get_operation_breakdown(self) -> dict[str, dict[str, Any]]: