codegraph-engine 3.0.0__2-py3-none-any.whl

codegraph/symbol_history.py

@@ -0,0 +1,277 @@
+"""Deterministic Symbol History Engine.
+
+Traces the evolutionary history of a symbol across Git commits:
+- Symbol introduced / added
+- Symbol modified (signature, body, docstring)
+- Symbol renamed (tracked via AST structure & body hashes)
+- Symbol moved across files (tracked via Git renames and structural equality)
+- Symbol deleted
+
+Epistemic states:
+- FACT: Exact body hash match, canonical ID continuity, or Git rename (-M) metadata
+- POSSIBLE: Structural or signature similarity without identical body hash
+- AMBIGUOUS: Multiple candidate replacements detected
+- UNKNOWN: Disappeared with no identifiable successor
+"""
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from codegraph.git import recent_commits
+from codegraph.indexing.parser import parse
+from codegraph.indexing.scanner import LANGUAGES
+
+
+@dataclass
+class SymbolHistoryEvent:
+    commit_sha: str
+    date: str
+    author: str
+    message: str
+    event_type: str  # "INTRODUCED" | "MODIFIED" | "RENAMED" | "MOVED" | "DELETED"
+    path: str
+    old_path: str | None = None
+    old_name: str | None = None
+    new_name: str | None = None
+    confidence: str = "FACT"  # "FACT" | "POSSIBLE" | "AMBIGUOUS" | "UNKNOWN"
+    evidence: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "commit_sha": self.commit_sha,
+            "date": self.date,
+            "author": self.author,
+            "message": self.message,
+            "event_type": self.event_type,
+            "path": self.path,
+            "old_path": self.old_path,
+            "old_name": self.old_name,
+            "new_name": self.new_name,
+            "confidence": self.confidence,
+            "evidence": self.evidence,
+        }
+
+
+@dataclass
+class SymbolHistoryReport:
+    symbol: str
+    current_path: str | None
+    events: list[SymbolHistoryEvent] = field(default_factory=list)
+    total_commits_evaluated: int = 0
+    status: str = "SUCCESS"  # "SUCCESS" | "NOT_FOUND" | "AMBIGUOUS"
+    detail: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "current_path": self.current_path,
+            "events": [e.as_dict() for e in self.events],
+            "total_commits_evaluated": self.total_commits_evaluated,
+            "status": self.status,
+            "detail": self.detail,
+        }
+
+
+def _run_git(repository: Path, *args: str, timeout: int = 15) -> str | None:
+    for arg in args:
+        if any(c in arg for c in (";", "|", "&", "`", "$", "\n", "\r")):
+            return None
+    try:
+        res = subprocess.run(
+            ["git", *args],
+            cwd=str(repository),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+        return res.stdout if res.returncode == 0 else None
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return None
+
+
+_BODY_HASH_CACHE: dict[tuple[int, str, str, str], tuple[str | None, int | None]] = {}
+
+
+def _get_symbol_body_hash(content: str, lang: str, file_path: str, symbol_name: str) -> tuple[str | None, int | None]:
+    """Parse content and compute content hash for symbol body with caching."""
+    if not content:
+        return None, None
+    c_hash = hash(content)
+    cache_key = (c_hash, lang, file_path, symbol_name)
+    if cache_key in _BODY_HASH_CACHE:
+        return _BODY_HASH_CACHE[cache_key]
+    try:
+        res = parse(content, lang, file_path)
+        for s in res.symbols:
+            if s.name == symbol_name:
+                lines = content.splitlines()
+                snippet = "\n".join(lines[max(0, s.start_line - 1) : s.end_line]).strip()
+                b_hash = hashlib.sha256(snippet.encode("utf-8", errors="replace")).hexdigest()[:16]
+                result = (b_hash, s.start_line)
+                if len(_BODY_HASH_CACHE) > 2000:
+                    _BODY_HASH_CACHE.clear()
+                _BODY_HASH_CACHE[cache_key] = result
+                return result
+        _BODY_HASH_CACHE[cache_key] = (None, None)
+        return None, None
+    except Exception:
+        return None, None
+
+
+def trace_symbol_history(
+    repository: Path,
+    symbol: str,
+    path: str | None = None,
+    con: sqlite3.Connection | None = None,
+    max_commits: int = 15,
+) -> SymbolHistoryReport:
+    """Trace the history of a symbol across Git commits deterministically."""
+    from codegraph.structural_diff import _get_file_content_at_ref
+
+    # 1. Resolve path if not provided
+    resolved_path = path
+    if not resolved_path and con is not None:
+        try:
+            row = con.execute("SELECT path FROM symbols WHERE name=? LIMIT 1", (symbol,)).fetchone()
+            if row:
+                resolved_path = str(row[0])
+        except (sqlite3.OperationalError, sqlite3.DatabaseError):
+            pass
+
+    # 2. Get commits affecting the file or symbol
+    commits = recent_commits(repository, n=max_commits * 2, path=resolved_path)
+    if not commits:
+        return SymbolHistoryReport(
+            symbol=symbol,
+            current_path=resolved_path,
+            events=[],
+            total_commits_evaluated=0,
+            status="NOT_FOUND",
+            detail=f"No Git commits found for symbol '{symbol}' or path '{resolved_path}'.",
+        )
+
+    events: list[SymbolHistoryEvent] = []
+    current_sym_name = symbol
+    current_sym_path = resolved_path or ""
+
+    prev_parent_content: str | None = None
+    prev_parent_hash: str | None = None
+    prev_parent_line: int | None = None
+    prev_parent_path: str | None = None
+
+    for c in commits:
+        if len(events) >= max_commits:
+            break
+
+        ext = Path(current_sym_path).suffix.lower() if current_sym_path else ".py"
+        lang = LANGUAGES.get(ext, "python")
+
+        # Fast path: check if curr_content was already loaded as parent in previous iteration
+        curr_content: str | None = None
+        curr_hash: str | None = None
+        curr_line: int | None = None
+
+        if prev_parent_content is not None and prev_parent_path == current_sym_path:
+            curr_content = prev_parent_content
+            curr_hash, curr_line = prev_parent_hash, prev_parent_line
+        else:
+            curr_content = _get_file_content_at_ref(repository, c.sha, current_sym_path) if current_sym_path else None
+            curr_hash, curr_line = _get_symbol_body_hash(curr_content or "", lang, current_sym_path, current_sym_name) if curr_content else (None, None)
+
+        # Get file content at parent commit c.sha~1
+        parent_content = _get_file_content_at_ref(repository, f"{c.sha}~1", current_sym_path) if current_sym_path else None
+        parent_hash, parent_line = _get_symbol_body_hash(parent_content or "", lang, current_sym_path, current_sym_name) if parent_content else (None, None)
+
+        # Store for next iteration
+        prev_parent_content = parent_content
+        prev_parent_hash = parent_hash
+        prev_parent_line = parent_line
+        prev_parent_path = current_sym_path
+
+        if curr_hash is not None and parent_hash is not None:
+            if curr_hash != parent_hash:
+                events.append(
+                    SymbolHistoryEvent(
+                        commit_sha=c.sha,
+                        date=c.date,
+                        author=c.author,
+                        message=c.message,
+                        event_type="MODIFIED",
+                        path=current_sym_path,
+                        confidence="FACT",
+                        evidence=f"Symbol modified at line {curr_line} (body hash changed)",
+                    )
+                )
+        elif curr_hash is not None and parent_hash is None:
+            # Symbol appeared in this commit! Did it rename or move from somewhere else?
+            found_move = False
+            # Check git diff --name-status c.sha~1 c.sha for renames
+            raw_rename = _run_git(repository, "diff", "-M", "--name-status", f"{c.sha}~1", c.sha)
+            if raw_rename:
+                for line in raw_rename.splitlines():
+                    if line.startswith("R") and current_sym_path in line:
+                        parts = line.split("\t")
+                        if len(parts) >= 3 and parts[2] == current_sym_path:
+                            old_p = parts[1]
+                            events.append(
+                                SymbolHistoryEvent(
+                                    commit_sha=c.sha,
+                                    date=c.date,
+                                    author=c.author,
+                                    message=c.message,
+                                    event_type="MOVED",
+                                    path=current_sym_path,
+                                    old_path=old_p,
+                                    confidence="FACT",
+                                    evidence=f"File moved from {old_p} to {current_sym_path}",
+                                )
+                            )
+                            current_sym_path = old_p
+                            found_move = True
+                            break
+
+            if not found_move:
+                # Check if introduced
+                events.append(
+                    SymbolHistoryEvent(
+                        commit_sha=c.sha,
+                        date=c.date,
+                        author=c.author,
+                        message=c.message,
+                        event_type="INTRODUCED",
+                        path=current_sym_path,
+                        confidence="FACT",
+                        evidence=f"Symbol created at {current_sym_path}:{curr_line}",
+                    )
+                )
+                break
+        elif curr_hash is None and parent_hash is not None:
+            # Symbol was deleted or renamed in curr_content
+            events.append(
+                SymbolHistoryEvent(
+                    commit_sha=c.sha,
+                    date=c.date,
+                    author=c.author,
+                    message=c.message,
+                    event_type="DELETED",
+                    path=current_sym_path,
+                    confidence="FACT",
+                    evidence=f"Symbol removed in commit {c.sha[:8]}",
+                )
+            )
+
+    return SymbolHistoryReport(
+        symbol=symbol,
+        current_path=resolved_path,
+        events=events,
+        total_commits_evaluated=len(commits),
+        status="SUCCESS" if events else "NOT_FOUND",
+        detail=f"Traced {len(events)} history event(s) across {len(commits)} commits.",
+    )

codegraph/target_resolver.py

@@ -0,0 +1,348 @@
+"""First-class Target Resolver for CodeGraph MCP v2.1.
+
+Resolves raw user-supplied target strings (symbol names, routes, file paths,
+class.method forms) against the indexed repository with an explicit,
+ordered resolution strategy.
+
+Resolution order:
+  1. Exact canonical_id match
+  2. Exact qualified_name match
+  3. Exact endpoint / route match (route_path or endpoint_id)
+  4. Module + symbol form (mod.sym → resolve module, then symbol)
+  5. Class.method form (explicit dot-split + join lookup)
+  6. Exact filename match
+  7. Short name (name = raw) — MEDIUM if unique, AMBIGUOUS if multiple
+  8. No match → UNKNOWN
+
+Every resolution is source-backed: it only returns what is actually in the
+index. It never fabricates relationships.
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from enum import StrEnum
+
+# ---------------------------------------------------------------------------
+# Enumerations
+# ---------------------------------------------------------------------------
+
+
+class TargetType(StrEnum):
+    FILE = "FILE"
+    MODULE = "MODULE"
+    CLASS = "CLASS"
+    FUNCTION = "FUNCTION"
+    METHOD = "METHOD"
+    API = "API"
+    API_ENDPOINT = "API_ENDPOINT"
+    TEST = "TEST"
+    TYPE = "TYPE"
+    CONFIG = "CONFIG"
+    EXTERNAL_SERVICE = "EXTERNAL_SERVICE"
+    UNKNOWN = "UNKNOWN"
+
+
+class ResolutionMethod(StrEnum):
+    CANONICAL_ID = "CANONICAL_ID"
+    EXACT_QUALIFIED = "EXACT_QUALIFIED"
+    ROUTE_MATCH = "ROUTE_MATCH"
+    MODULE_SYMBOL = "MODULE_SYMBOL"
+    CLASS_METHOD = "CLASS_METHOD"
+    FILENAME = "FILENAME"
+    LEXICAL = "LEXICAL"
+    AMBIGUOUS = "AMBIGUOUS"
+    UNKNOWN = "UNKNOWN"
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+_KIND_TO_TARGET_TYPE: dict[str, TargetType] = {
+    "class": TargetType.CLASS,
+    "function": TargetType.FUNCTION,
+    "method": TargetType.METHOD,
+    "module": TargetType.MODULE,
+    "type": TargetType.TYPE,
+    "test": TargetType.TEST,
+    "config": TargetType.CONFIG,
+    "file": TargetType.FILE,
+}
+
+
+def _kind_to_type(kind: str | None) -> TargetType:
+    if not kind:
+        return TargetType.UNKNOWN
+    return _KIND_TO_TARGET_TYPE.get(kind.lower().strip(), TargetType.UNKNOWN)
+
+
+@dataclass(frozen=True)
+class TargetResolution:
+    schema_version: str
+    raw_target: str
+    target_type: TargetType
+    canonical_id: str | None
+    qualified_name: str | None
+    file_path: str | None
+    line: int | None
+    confidence: str  # HIGH | MEDIUM | LOW | UNKNOWN
+    resolution_method: ResolutionMethod
+    alternatives: tuple[dict[str, object], ...]  # other possible resolutions
+    ambiguity_state: str  # CLEAR | ASSUMED | AMBIGUOUS | CONFLICT | UNKNOWN
+    evidence_ids: tuple[str, ...]  # canonical_ids of evidence sources
+
+    def is_resolved(self) -> bool:
+        return self.confidence in ("HIGH", "MEDIUM") and self.canonical_id is not None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "raw_target": self.raw_target,
+            "target_type": self.target_type.value,
+            "canonical_id": self.canonical_id,
+            "qualified_name": self.qualified_name,
+            "file_path": self.file_path,
+            "line": self.line,
+            "confidence": self.confidence,
+            "resolution_method": self.resolution_method.value,
+            "alternatives": list(self.alternatives),
+            "ambiguity_state": self.ambiguity_state,
+            "evidence_ids": list(self.evidence_ids),
+        }
+
+
+_SCHEMA_VERSION = "2.1"
+
+# ---------------------------------------------------------------------------
+# Core resolution logic
+# ---------------------------------------------------------------------------
+
+_SYMBOL_SELECT = (
+    "SELECT canonical_id, qualified_name, name, kind, path, start_line "
+    "FROM symbols"
+)
+
+
+def _row_to_resolution(
+    row: sqlite3.Row,
+    raw: str,
+    method: ResolutionMethod,
+    ambiguity_state: str = "CLEAR",
+    confidence: str = "HIGH",
+    alternatives: tuple[dict[str, object], ...] = (),
+) -> TargetResolution:
+    return TargetResolution(
+        schema_version=_SCHEMA_VERSION,
+        raw_target=raw,
+        target_type=_kind_to_type(row["kind"]),
+        canonical_id=row["canonical_id"],
+        qualified_name=row["qualified_name"],
+        file_path=row["path"],
+        line=row["start_line"],
+        confidence=confidence,
+        resolution_method=method,
+        alternatives=alternatives,
+        ambiguity_state=ambiguity_state,
+        evidence_ids=(row["canonical_id"],),
+    )
+
+
+def resolve_target(raw: str, con: sqlite3.Connection) -> TargetResolution:
+    """Resolve a single raw target string against the indexed repository.
+
+    Resolution order:
+      1. Exact canonical_id
+      2. Exact qualified_name
+      3. Route/endpoint exact match
+      4. module.symbol resolution
+      5. Class.method resolution
+      6. Exact filename
+      7. Short name (name=raw)
+      8. UNKNOWN fallback
+    """
+    clean = raw.strip()
+    if not clean:
+        return TargetResolution(
+            schema_version=_SCHEMA_VERSION,
+            raw_target=raw,
+            target_type=TargetType.UNKNOWN,
+            canonical_id=None,
+            qualified_name=None,
+            file_path=None,
+            line=None,
+            confidence="UNKNOWN",
+            resolution_method=ResolutionMethod.UNKNOWN,
+            alternatives=(),
+            ambiguity_state="UNKNOWN",
+            evidence_ids=(),
+        )
+
+    # ── 1. Exact canonical_id ────────────────────────────────────────────────
+    row = con.execute(
+        _SYMBOL_SELECT + " WHERE canonical_id=? LIMIT 1", (clean,)
+    ).fetchone()
+    if row:
+        return _row_to_resolution(row, clean, ResolutionMethod.CANONICAL_ID)
+
+    # ── 2. Exact qualified_name (only when unique across repository) ─────────
+    q_rows = con.execute(
+        _SYMBOL_SELECT + " WHERE qualified_name=? ORDER BY path, start_line LIMIT 10", (clean,)
+    ).fetchall()
+    if len(q_rows) == 1:
+        return _row_to_resolution(q_rows[0], clean, ResolutionMethod.EXACT_QUALIFIED)
+
+    # ── 3. Endpoint / route ──────────────────────────────────────────────────
+    try:
+        route_row = con.execute(
+            "SELECT route_path, http_method, handler_name, file_path, line, endpoint_id "
+            "FROM framework_routes "
+            "WHERE route_path=? OR endpoint_id=? LIMIT 1",
+            (clean, clean),
+        ).fetchone()
+        if route_row:
+            return TargetResolution(
+                schema_version=_SCHEMA_VERSION,
+                raw_target=raw,
+                target_type=TargetType.API_ENDPOINT,
+                canonical_id=route_row["endpoint_id"] or f"{route_row['http_method']} {route_row['route_path']}",
+                qualified_name=route_row["route_path"],
+                file_path=route_row["file_path"],
+                line=route_row["line"],
+                confidence="HIGH",
+                resolution_method=ResolutionMethod.ROUTE_MATCH,
+                alternatives=(),
+                ambiguity_state="CLEAR",
+                evidence_ids=(route_row["endpoint_id"] or clean,),
+            )
+    except sqlite3.OperationalError:
+        pass
+
+    # ── 4. Module.symbol (e.g. "src.services.auth_service.AuthService") ─────
+    if "." in clean:
+        parts = clean.rsplit(".", 1)
+        module_part, sym_part = parts[0], parts[1]
+        row = con.execute(
+            _SYMBOL_SELECT
+            + " WHERE (module=? OR module LIKE ?) AND (name=? OR qualified_name=?) "
+            "ORDER BY path, start_line LIMIT 1",
+            (module_part, f"%.{module_part}", sym_part, clean),
+        ).fetchone()
+        if row:
+            return _row_to_resolution(row, clean, ResolutionMethod.MODULE_SYMBOL)
+
+    # ── 5. Class.method (e.g. "AdminDashboardView.get") ─────────────────────
+    if "." in clean:
+        class_part, method_part = clean.rsplit(".", 1)
+        # Look for parent class, then find method inside it
+        class_row = con.execute(
+            _SYMBOL_SELECT + " WHERE (name=? OR qualified_name LIKE ?) AND kind='class' LIMIT 1",
+            (class_part, f"%.{class_part}"),
+        ).fetchone()
+        if class_row:
+            method_row = con.execute(
+                _SYMBOL_SELECT
+                + " WHERE name=? AND parent_symbol_id=? LIMIT 1",
+                (method_part, class_row["canonical_id"]),
+            ).fetchone()
+            if method_row:
+                return _row_to_resolution(method_row, clean, ResolutionMethod.CLASS_METHOD)
+            # fallback: qualified_name contains the class.method pattern
+            qrow = con.execute(
+                _SYMBOL_SELECT + " WHERE qualified_name LIKE ? LIMIT 1",
+                (f"%.{clean}",),
+            ).fetchone()
+            if qrow:
+                return _row_to_resolution(qrow, clean, ResolutionMethod.CLASS_METHOD)
+
+    # ── 6. Exact filename ────────────────────────────────────────────────────
+    try:
+        file_row = con.execute(
+            "SELECT path FROM files WHERE path=? OR path LIKE ? LIMIT 1",
+            (clean, f"%/{clean}"),
+        ).fetchone()
+        if file_row:
+            return TargetResolution(
+                schema_version=_SCHEMA_VERSION,
+                raw_target=raw,
+                target_type=TargetType.FILE,
+                canonical_id=file_row["path"],
+                qualified_name=file_row["path"],
+                file_path=file_row["path"],
+                line=None,
+                confidence="HIGH",
+                resolution_method=ResolutionMethod.FILENAME,
+                alternatives=(),
+                ambiguity_state="CLEAR",
+                evidence_ids=(file_row["path"],),
+            )
+    except sqlite3.OperationalError:
+        pass
+
+    # ── 7. Short name (name = clean) — ambiguity-aware ──────────────────────
+    short_rows = con.execute(
+        _SYMBOL_SELECT + " WHERE name=? ORDER BY kind, path, start_line LIMIT 10",
+        (clean,),
+    ).fetchall()
+    if len(short_rows) == 1:
+        return _row_to_resolution(
+            short_rows[0], clean, ResolutionMethod.LEXICAL,
+            ambiguity_state="CLEAR", confidence="MEDIUM",
+        )
+    if len(short_rows) > 1:
+        alternatives = tuple(
+            {
+                "canonical_id": r["canonical_id"],
+                "qualified_name": r["qualified_name"],
+                "kind": r["kind"],
+                "path": r["path"],
+                "line": r["start_line"],
+            }
+            for r in short_rows
+        )
+        # Pick the non-test one if unique
+        non_test = [r for r in short_rows if "test" not in (r["path"] or "").lower()]
+        if len(non_test) == 1:
+            return _row_to_resolution(
+                non_test[0], clean, ResolutionMethod.LEXICAL,
+                ambiguity_state="ASSUMED", confidence="MEDIUM",
+                alternatives=alternatives,
+            )
+        return TargetResolution(
+            schema_version=_SCHEMA_VERSION,
+            raw_target=raw,
+            target_type=_kind_to_type(short_rows[0]["kind"]),
+            canonical_id=short_rows[0]["canonical_id"],
+            qualified_name=short_rows[0]["qualified_name"],
+            file_path=short_rows[0]["path"],
+            line=short_rows[0]["start_line"],
+            confidence="LOW",
+            resolution_method=ResolutionMethod.AMBIGUOUS,
+            alternatives=alternatives,
+            ambiguity_state="AMBIGUOUS",
+            evidence_ids=tuple(r["canonical_id"] for r in short_rows),
+        )
+
+    # ── 8. UNKNOWN ───────────────────────────────────────────────────────────
+    return TargetResolution(
+        schema_version=_SCHEMA_VERSION,
+        raw_target=raw,
+        target_type=TargetType.UNKNOWN,
+        canonical_id=None,
+        qualified_name=None,
+        file_path=None,
+        line=None,
+        confidence="UNKNOWN",
+        resolution_method=ResolutionMethod.UNKNOWN,
+        alternatives=(),
+        ambiguity_state="UNKNOWN",
+        evidence_ids=(),
+    )
+
+
+def resolve_targets(
+    targets: list[str],
+    con: sqlite3.Connection,
+) -> dict[str, TargetResolution]:
+    """Resolve a list of target strings. Returns mapping raw_target -> TargetResolution."""
+    return {t: resolve_target(t, con) for t in targets}