codegraph-engine 2.1.1__py3-none-any.whl

codegraph/retrieval_policy.py

@@ -0,0 +1,220 @@
+"""Intent-specific retrieval policies for CodeGraph MCP v2.1.
+
+Each policy defines:
+  - Allowed relationship types (graph edges that may participate)
+  - Preferred coverage layers (ordered)
+  - Traversal flags (callers, callees, tests, git, framework, architecture)
+  - Maximum graph depth
+
+Downstream retrieval MUST filter graph candidates to allowed_relationship_types.
+This prevents unrelated relationships from polluting context merely because
+they exist in the graph.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RetrievalPolicy:
+    intent: str
+    allowed_relationship_types: frozenset[str]
+    preferred_flow: tuple[str, ...]
+    include_callers: bool = True
+    include_callees: bool = True
+    include_tests: bool = True
+    include_git: bool = False
+    include_framework: bool = True
+    include_architecture: bool = False
+    max_graph_depth: int = 3
+    preferred_target_types: tuple[str, ...] = ()
+
+    def allows(self, relationship: str) -> bool:
+        """Return True if the relationship type is permitted for this policy."""
+        if not self.allowed_relationship_types:
+            return True
+        return relationship.upper() in self.allowed_relationship_types
+
+
+# ---------------------------------------------------------------------------
+# Policy definitions
+# ---------------------------------------------------------------------------
+
+_POLICIES: dict[str, RetrievalPolicy] = {}
+
+
+def _register(policy: RetrievalPolicy) -> None:
+    _POLICIES[policy.intent.upper()] = policy
+
+
+# TRACE — follow the full call chain from endpoint to data layer
+_register(RetrievalPolicy(
+    intent="TRACE",
+    allowed_relationship_types=frozenset({
+        "HANDLED_BY", "ROUTES_TO", "CALLS", "DEPENDS_ON", "IMPORTS", "TESTS",
+        "POSSIBLE_CALLS", "DEFINES", "CONTAINS", "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("ENTRYPOINT", "HANDLER", "SERVICE", "DATA", "TEST"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=True,
+    include_framework=True,
+    max_graph_depth=4,
+    preferred_target_types=("API_ENDPOINT", "FUNCTION", "METHOD", "CLASS"),
+))
+
+# UNDERSTAND — explain structure, definitions, dependencies
+_register(RetrievalPolicy(
+    intent="UNDERSTAND",
+    allowed_relationship_types=frozenset({
+        "DEFINES", "CONTAINS", "CALLS", "IMPORTS", "DEPENDS_ON",
+        "POSSIBLE_CALLS", "EXTENDS", "IMPLEMENTS", "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("TARGET", "DEFINITIONS", "DEPENDENCIES", "CALLERS_CALLEES"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=False,
+    include_framework=True,
+    max_graph_depth=2,
+    preferred_target_types=("CLASS", "FUNCTION", "MODULE"),
+))
+
+# DEBUG — find callers, callees, error paths, tests
+_register(RetrievalPolicy(
+    intent="DEBUG",
+    allowed_relationship_types=frozenset({
+        "CALLS", "CALLED_BY", "DEPENDS_ON", "TESTS", "IMPORTS",
+        "POSSIBLE_CALLS", "DEFINES", "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("TARGET", "EXECUTION_PATH", "ERROR_PATH", "TEST"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=True,
+    include_framework=True,
+    max_graph_depth=3,
+    preferred_target_types=("FUNCTION", "METHOD", "CLASS"),
+))
+
+# IMPACT — what depends on, calls, or tests the target?
+_register(RetrievalPolicy(
+    intent="IMPACT",
+    allowed_relationship_types=frozenset({
+        "CALLED_BY", "DEPENDS_ON", "IMPLEMENTED_BY", "TESTS", "CALLS",
+        "IMPORTS", "POSSIBLE_CALLS",
+    }),
+    preferred_flow=("TARGET", "CALLERS", "DEPENDENTS", "TEST"),
+    include_callers=True,
+    include_callees=False,
+    include_tests=True,
+    include_framework=False,
+    max_graph_depth=3,
+    preferred_target_types=("CLASS", "FUNCTION", "METHOD", "MODULE"),
+))
+
+# REVIEW — review changes; needs callers, callees, tests, and git context
+_register(RetrievalPolicy(
+    intent="REVIEW",
+    allowed_relationship_types=frozenset({
+        "CALLS", "CALLED_BY", "DEPENDS_ON", "TESTS", "IMPORTS", "POSSIBLE_CALLS",
+    }),
+    preferred_flow=("TARGET", "HANDLER", "SERVICE", "TEST"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=True,
+    include_git=True,
+    include_framework=True,
+    max_graph_depth=2,
+    preferred_target_types=("CLASS", "FUNCTION", "METHOD"),
+))
+
+# REFACTOR — similar to UNDERSTAND but emphasizes callers and tests
+_register(RetrievalPolicy(
+    intent="REFACTOR",
+    allowed_relationship_types=frozenset({
+        "DEFINES", "CONTAINS", "CALLS", "IMPORTS", "DEPENDS_ON",
+        "POSSIBLE_CALLS", "EXTENDS", "IMPLEMENTS", "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("TARGET", "DEFINITIONS", "CALLERS_CALLEES", "TEST"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=True,
+    include_framework=False,
+    max_graph_depth=2,
+    preferred_target_types=("CLASS", "FUNCTION", "METHOD"),
+))
+
+# CHANGE — modify existing behavior; needs definition + callers + tests
+_register(RetrievalPolicy(
+    intent="CHANGE",
+    allowed_relationship_types=frozenset({
+        "DEFINES", "CALLS", "CALLED_BY", "IMPORTS", "DEPENDS_ON", "TESTS",
+        "POSSIBLE_CALLS", "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("TARGET", "HANDLER", "SERVICE", "DATA", "TEST"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=True,
+    include_framework=True,
+    max_graph_depth=3,
+    preferred_target_types=("FUNCTION", "METHOD", "CLASS", "API_ENDPOINT"),
+))
+
+# TEST — locate and contextualize test coverage
+_register(RetrievalPolicy(
+    intent="TEST",
+    allowed_relationship_types=frozenset({
+        "TESTS", "CALLS", "DEPENDS_ON", "DEFINES", "IMPORTS",
+    }),
+    preferred_flow=("TEST", "TARGET", "DEFINITIONS", "DEPENDENCIES"),
+    include_callers=False,
+    include_callees=True,
+    include_tests=True,
+    include_framework=False,
+    max_graph_depth=2,
+    preferred_target_types=("TEST", "FUNCTION", "METHOD"),
+))
+
+# ARCHITECTURE — top-level module and service relationships
+_register(RetrievalPolicy(
+    intent="ARCHITECTURE",
+    allowed_relationship_types=frozenset({
+        "IMPORTS", "DEPENDS_ON", "EXTERNAL_SERVICE", "ROUTES_TO",
+        "DEFINES", "CONTAINS",
+    }),
+    preferred_flow=("ENTRYPOINT", "SERVICE", "DATA", "EXTERNAL"),
+    include_callers=False,
+    include_callees=False,
+    include_tests=False,
+    include_architecture=True,
+    include_framework=True,
+    max_graph_depth=1,
+    preferred_target_types=("MODULE", "API_ENDPOINT", "CLASS"),
+))
+
+# EXPLAIN — like UNDERSTAND but includes framework/route facts
+_register(RetrievalPolicy(
+    intent="EXPLAIN",
+    allowed_relationship_types=frozenset({
+        "DEFINES", "CONTAINS", "CALLS", "IMPORTS", "DEPENDS_ON",
+        "HANDLED_BY", "ROUTES_TO", "POSSIBLE_CALLS", "EXTENDS", "IMPLEMENTS",
+        "PARALLEL_IMPLEMENTATION",
+    }),
+    preferred_flow=("TARGET", "DEFINITIONS", "DEPENDENCIES", "CALLERS_CALLEES"),
+    include_callers=True,
+    include_callees=True,
+    include_tests=False,
+    include_framework=True,
+    max_graph_depth=2,
+    preferred_target_types=("CLASS", "FUNCTION", "METHOD"),
+))
+
+# Default fallback (same as UNDERSTAND)
+_DEFAULT_POLICY = _POLICIES["UNDERSTAND"]
+
+
+def get_retrieval_policy(intent: str) -> RetrievalPolicy:
+    """Return the RetrievalPolicy for the given intent string.
+
+    Falls back to UNDERSTAND if the intent is not recognized.
+    """
+    return _POLICIES.get(intent.upper().strip(), _DEFAULT_POLICY)

codegraph/search/__init__.py

@@ -0,0 +1,23 @@
+from .hybrid import (
+    SearchResult,
+    search,
+    search_exact_canonical_id,
+    search_exact_qualified,
+    search_exact_symbol,
+    search_lexical,
+    search_route,
+)
+from .semantic import EmbeddingProvider, SemanticSearchUnavailable, status
+
+__all__ = [
+    "EmbeddingProvider",
+    "SearchResult",
+    "SemanticSearchUnavailable",
+    "search",
+    "search_exact_canonical_id",
+    "search_exact_qualified",
+    "search_exact_symbol",
+    "search_lexical",
+    "search_route",
+    "status",
+]

codegraph/search/hybrid.py

@@ -0,0 +1,301 @@
+"""Lexical search using SQLite FTS5.
+
+Retrieval is lexical + path/symbol ranking.  No semantic embeddings.
+"""
+from __future__ import annotations
+
+import re
+import sqlite3
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    file: str
+    symbol: str | None
+    start_line: int
+    end_line: int
+    score: float
+    reason: str
+    snippet: str
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+# FTS5 reserved words that cannot appear as bare terms
+_FTS5_RESERVED = frozenset({
+    "AND", "OR", "NOT",
+})
+
+# FTS5 special characters to strip from terms
+_FTS5_SPECIAL = re.compile(r"[^\w]")  # keep only word chars inside terms
+
+
+def _safe_fts5_terms(query: str) -> list[str]:
+    """Extract word-like tokens safe for FTS5 MATCH expressions.
+
+    - Splits on non-alphanumeric characters (dots, dashes, etc.)
+    - Drops single-character tokens
+    - Drops FTS5 reserved words
+    - Returns deduplicated list preserving order
+    """
+    # Split on anything that is not alphanumeric or underscore
+    raw_tokens = re.split(r"[^A-Za-z0-9_]+", query)
+    seen: set[str] = set()
+    result: list[str] = []
+    for tok in raw_tokens:
+        tok = tok.strip()
+        if len(tok) < 2:
+            continue
+        if tok.upper() in _FTS5_RESERVED:
+            continue
+        if tok not in seen:
+            seen.add(tok)
+            result.append(tok)
+    return result
+
+
+def search(
+    con: sqlite3.Connection,
+    query: str,
+    top_k: int = 10,
+    include_generated: bool = False,
+) -> list[SearchResult]:
+    terms = _safe_fts5_terms(query)
+    if not terms:
+        return []
+    clauses = " OR ".join(terms)
+    try:
+        if include_generated:
+            rows = con.execute(
+                "SELECT c.path, c.symbol, c.start_line, c.end_line, c.content, "
+                "bm25(chunks_fts) AS rank "
+                "FROM chunks_fts "
+                "JOIN chunks c ON c.id = chunks_fts.rowid "
+                "WHERE chunks_fts MATCH ? ORDER BY rank LIMIT ?",
+                (clauses, top_k * 3),
+            ).fetchall()
+        else:
+            rows = con.execute(
+                "SELECT c.path, c.symbol, c.start_line, c.end_line, c.content, "
+                "bm25(chunks_fts) AS rank "
+                "FROM chunks_fts "
+                "JOIN chunks c ON c.id = chunks_fts.rowid "
+                "LEFT JOIN files f ON f.path = c.path "
+                "WHERE chunks_fts MATCH ? AND (f.category IS NULL OR f.category != 'GENERATED') "
+                "ORDER BY rank LIMIT ?",
+                (clauses, top_k * 3),
+            ).fetchall()
+    except sqlite3.OperationalError:
+        try:
+            rows = con.execute(
+                "SELECT c.path, c.symbol, c.start_line, c.end_line, c.content, "
+                "bm25(chunks_fts) AS rank "
+                "FROM chunks_fts "
+                "JOIN chunks c ON c.id = chunks_fts.rowid "
+                "WHERE chunks_fts MATCH ? ORDER BY rank LIMIT ?",
+                (clauses, top_k * 3),
+            ).fetchall()
+        except sqlite3.OperationalError:
+            return []
+
+    results: list[SearchResult] = []
+    query.lower()
+    for row in rows:
+        path_bonus = 1.0 if any(t.lower() in row["path"].lower() for t in terms) else 0.0
+        symbol_bonus = (
+            1.0
+            if row["symbol"] and any(t.lower() in row["symbol"].lower() for t in terms)
+            else 0.0
+        )
+        # Exact symbol match (highest bonus)
+        exact_bonus = (
+            0.5
+            if row["symbol"] and any(
+                t.lower() == row["symbol"].lower()
+                or t.lower() == row["symbol"].split(".")[-1].lower()
+                for t in terms
+            )
+            else 0.0
+        )
+        score = round(min(1.0, 0.3 + path_bonus * 0.15 + symbol_bonus * 0.2 + exact_bonus * 0.35), 2)
+        reason = "lexical match"
+        if symbol_bonus:
+            reason += ", symbol match"
+        if path_bonus:
+            reason += ", path match"
+        snippet = row["content"][:900]
+        results.append(
+            SearchResult(
+                row["path"],
+                row["symbol"],
+                row["start_line"],
+                row["end_line"],
+                score,
+                reason,
+                snippet,
+            )
+        )
+
+    # Sort by score descending (bm25 is negative, lower = better match)
+    results.sort(key=lambda r: r.score, reverse=True)
+    return results[:top_k]
+
+
+def search_lexical(con: sqlite3.Connection, query: str, top_k: int = 10) -> list[SearchResult]:
+    """Lexical FTS5 search (wrapper around search)."""
+    return search(con, query, top_k=top_k)
+
+
+def _fetch_snippet(
+    con: sqlite3.Connection, path: str, start: int, end: int, symbol: str | None = None
+) -> str:
+    try:
+        row = con.execute(
+            "SELECT content FROM chunks WHERE path=? AND start_line<=? AND end_line>=? LIMIT 1",
+            (path, start, end),
+        ).fetchone()
+        if row and row["content"]:
+            return str(row["content"])[:900]
+        if symbol:
+            row = con.execute(
+                "SELECT content FROM chunks WHERE symbol=? LIMIT 1", (symbol,)
+            ).fetchone()
+            if row and row["content"]:
+                return str(row["content"])[:900]
+    except sqlite3.OperationalError:
+        pass
+    return ""
+
+
+def search_exact_canonical_id(
+    con: sqlite3.Connection, canonical_id: str
+) -> list[SearchResult]:
+    """Look up symbol by exact canonical ID."""
+    clean = canonical_id.strip()
+    if not clean:
+        return []
+    try:
+        rows = con.execute(
+            "SELECT canonical_id, qualified_name, path, start_line, end_line "
+            "FROM symbols WHERE canonical_id=? ORDER BY path, start_line",
+            (clean,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+
+    results: list[SearchResult] = []
+    for r in rows:
+        snippet = _fetch_snippet(con, r["path"], r["start_line"], r["end_line"], r["qualified_name"])
+        results.append(
+            SearchResult(
+                file=r["path"],
+                symbol=r["qualified_name"] or r["canonical_id"],
+                start_line=r["start_line"],
+                end_line=r["end_line"],
+                score=1.0,
+                reason="exact canonical id match",
+                snippet=snippet,
+            )
+        )
+    return results
+
+
+def search_exact_qualified(
+    con: sqlite3.Connection, qualified_name: str
+) -> list[SearchResult]:
+    """Look up symbol by exact qualified name."""
+    clean = qualified_name.strip()
+    if not clean:
+        return []
+    try:
+        rows = con.execute(
+            "SELECT canonical_id, qualified_name, path, start_line, end_line "
+            "FROM symbols WHERE qualified_name=? OR canonical_id=? ORDER BY path, start_line",
+            (clean, clean),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+
+    results: list[SearchResult] = []
+    for r in rows:
+        snippet = _fetch_snippet(con, r["path"], r["start_line"], r["end_line"], r["qualified_name"])
+        results.append(
+            SearchResult(
+                file=r["path"],
+                symbol=r["qualified_name"],
+                start_line=r["start_line"],
+                end_line=r["end_line"],
+                score=0.95,
+                reason="exact qualified match",
+                snippet=snippet,
+            )
+        )
+    return results
+
+
+def search_exact_symbol(
+    con: sqlite3.Connection, name: str
+) -> list[SearchResult]:
+    """Look up symbol by short identifier name."""
+    clean = name.strip()
+    if not clean:
+        return []
+    try:
+        rows = con.execute(
+            "SELECT canonical_id, qualified_name, path, start_line, end_line "
+            "FROM symbols WHERE name=? ORDER BY path, start_line",
+            (clean,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+
+    results: list[SearchResult] = []
+    for r in rows:
+        snippet = _fetch_snippet(con, r["path"], r["start_line"], r["end_line"], r["qualified_name"])
+        results.append(
+            SearchResult(
+                file=r["path"],
+                symbol=r["qualified_name"],
+                start_line=r["start_line"],
+                end_line=r["end_line"],
+                score=0.90,
+                reason="exact symbol match",
+                snippet=snippet,
+            )
+        )
+    return results
+
+
+def search_route(
+    con: sqlite3.Connection, route_or_endpoint: str
+) -> list[SearchResult]:
+    """Look up framework route by path or endpoint ID."""
+    clean = route_or_endpoint.strip()
+    if not clean:
+        return []
+    try:
+        rows = con.execute(
+            "SELECT route_path, http_method, handler_name, file_path, line, endpoint_id, evidence "
+            "FROM framework_routes WHERE route_path=? OR endpoint_id=? ORDER BY file_path, line",
+            (clean, clean),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+
+    results: list[SearchResult] = []
+    for r in rows:
+        snippet = _fetch_snippet(con, r["file_path"], r["line"], r["line"], r["handler_name"])
+        results.append(
+            SearchResult(
+                file=r["file_path"],
+                symbol=r["handler_name"] or r["route_path"],
+                start_line=r["line"],
+                end_line=r["line"],
+                score=0.95,
+                reason=f"route match: {r['http_method']} {r['route_path']}",
+                snippet=snippet,
+            )
+        )
+    return results

codegraph/search/semantic.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+class SemanticSearchUnavailable(RuntimeError):
+    """No embedding provider has been configured for semantic retrieval."""
+
+
+class EmbeddingProvider(ABC):
+    """Provider-neutral embeddings interface; implementations must be deterministic in tests."""
+
+    @abstractmethod
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class SemanticStatus:
+    available: bool
+    detail: str
+
+
+def status(provider: EmbeddingProvider | None) -> SemanticStatus:
+    if provider is None:
+        return SemanticStatus(False, "No embedding provider configured; lexical and symbol retrieval remain active.")
+    return SemanticStatus(True, "Embedding provider configured.")

codegraph/security/__init__.py

@@ -0,0 +1,3 @@
+from .paths import DEFAULT_SENSITIVE_PATTERNS, is_sensitive, safe_path
+
+__all__ = ["DEFAULT_SENSITIVE_PATTERNS", "is_sensitive", "safe_path"]

codegraph/security/paths.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+from urllib.parse import unquote
+
+from codegraph.errors import SecurityError
+
+DEFAULT_SENSITIVE_PATTERNS = (
+    ".env", ".env.*", "*.pem", "*.key", "id_rsa", "credentials.*", "secrets.*",
+    "service-account*.json", ".aws/*", ".ssh/*",
+)
+
+
+def is_sensitive(relative_path: Path, patterns: tuple[str, ...] = DEFAULT_SENSITIVE_PATTERNS) -> bool:
+    value = relative_path.as_posix()
+    name = relative_path.name
+    return any(fnmatch.fnmatch(value, p) or fnmatch.fnmatch(name, p) for p in patterns)
+
+
+def safe_path(repository: Path, requested: str | Path) -> Path:
+    """Resolve a repo-relative path and reject traversal and symlink escapes."""
+    root = repository.resolve(strict=True)
+    raw_value = unquote(str(requested))
+    if "\x00" in raw_value:
+        raise SecurityError("null bytes are not allowed in paths")
+    raw = Path(raw_value)
+    if raw.is_absolute():
+        raise SecurityError("absolute paths are not allowed")
+    candidate = (root / raw).resolve(strict=False)
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:
+        raise SecurityError("path escapes the configured repository") from exc
+    return candidate