codegraph-engine 2.2.1__py3-none-any.whl → 3.0.0__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/tsconfig.py

@@ -0,0 +1,236 @@
+"""TypeScript and JavaScript Path Alias Resolution (tsconfig.json / jsconfig.json).
+
+Provides deterministic resolution of compilerOptions.paths and baseUrl across
+monorepos, Next.js, Vite, and React projects without external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def strip_json_comments(text: str) -> str:
+    """Strip single-line and multi-line comments and trailing commas from tsconfig/jsconfig JSON."""
+    # Remove block comments /* ... */
+    text = re.sub(r"/\*[\s\S]*?\*/", "", text)
+    # Remove line comments // ... (not inside quotes)
+    lines: list[str] = []
+    for line in text.splitlines():
+        # Match // not preceded by a quote mark
+        cleaned_line = re.sub(r'(?<![:"\'\\])//.*$', '', line)
+        lines.append(cleaned_line)
+    cleaned = "\n".join(lines)
+    # Remove trailing commas before } or ]
+    cleaned = re.sub(r",\s*([}\]])", r"\1", cleaned)
+    return cleaned
+
+
+@dataclass(frozen=True)
+class TsConfig:
+    config_path: str
+    base_dir: str
+    base_url: str
+    paths: dict[str, tuple[str, ...]] = field(default_factory=dict)
+
+
+class TsConfigResolver:
+    """Manages tsconfig.json and jsconfig.json path mappings across workspaces."""
+
+    def __init__(self, configs: list[TsConfig] | None = None) -> None:
+        self.configs: list[TsConfig] = configs or []
+
+    @classmethod
+    def load_from_repo(cls, repo_root: Path) -> TsConfigResolver:
+        """Scan workspace for tsconfig.json, jsconfig.json, and vite.config.* files."""
+        configs: list[TsConfig] = []
+        candidates = (
+            list(repo_root.glob("**/tsconfig*.json"))
+            + list(repo_root.glob("**/jsconfig*.json"))
+            + list(repo_root.glob("**/vite.config.*"))
+        )
+
+        for c_path in candidates:
+            # Skip node_modules or build outputs
+            parts = c_path.parts
+            if any(p in ("node_modules", ".git", "dist", "build", ".next", ".cache") for p in parts):
+                continue
+            if c_path.name.startswith("vite.config."):
+                cfg = cls._parse_vite_config(c_path, repo_root)
+            else:
+                cfg = cls._parse_single_config(c_path, repo_root)
+            if cfg:
+                configs.append(cfg)
+
+        # Sort configs: deepest path first for nearest-config resolution
+        configs.sort(key=lambda c: len(c.base_dir), reverse=True)
+        return cls(configs)
+
+    @staticmethod
+    def _parse_vite_config(file_path: Path, repo_root: Path) -> TsConfig | None:
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+            parsed_paths: dict[str, tuple[str, ...]] = {}
+
+            # 1. Object alias: alias: { '@': path.resolve(__dirname, './src'), ... }
+            alias_match = re.search(r"alias\s*:\s*\{([^}]+)\}", content)
+            if alias_match:
+                entries = re.findall(
+                    r"""['"]([^'"]+)['"]\s*:\s*(?:(?:path\.)?resolve\([^)]*['"]([^'"]+)['"]\)|['"]([^'"]+)['"])""",
+                    alias_match.group(1),
+                )
+                for key, target1, target2 in entries:
+                    raw_target = (target1 or target2 or "").strip().replace("\\", "/").lstrip("./")
+                    if raw_target:
+                        clean_key = key.rstrip("/")
+                        parsed_paths[f"{clean_key}/*"] = (f"{raw_target}/*",)
+                        parsed_paths[clean_key] = (raw_target,)
+
+            # 2. Array alias: alias: [ { find: '@', replacement: path.resolve(__dirname, './src') } ]
+            array_entries = re.findall(
+                r"""find\s*:\s*['"]([^'"]+)['"][\s\S]*?replacement\s*:\s*(?:(?:path\.)?resolve\([^)]*['"]([^'"]+)['"]\)|['"]([^'"]+)['"])""",
+                content,
+            )
+            for key, target1, target2 in array_entries:
+                raw_target = (target1 or target2 or "").strip().replace("\\", "/").lstrip("./")
+                if raw_target:
+                    clean_key = key.rstrip("/")
+                    parsed_paths[f"{clean_key}/*"] = (f"{raw_target}/*",)
+                    parsed_paths[clean_key] = (raw_target,)
+
+            if not parsed_paths:
+                return None
+
+            base_dir_path = file_path.parent
+            rel_base_dir = posixpath.normpath(base_dir_path.relative_to(repo_root).as_posix())
+            if rel_base_dir == ".":
+                rel_base_dir = ""
+
+            return TsConfig(
+                config_path=posixpath.normpath(file_path.relative_to(repo_root).as_posix()),
+                base_dir=rel_base_dir,
+                base_url=".",
+                paths=parsed_paths,
+            )
+        except Exception:
+            return None
+
+    @staticmethod
+    def _parse_single_config(file_path: Path, repo_root: Path) -> TsConfig | None:
+        try:
+            raw = file_path.read_text(encoding="utf-8", errors="replace")
+            cleaned = strip_json_comments(raw)
+            data = json.loads(cleaned)
+            compiler_opts = data.get("compilerOptions", {})
+
+            base_dir_path = file_path.parent
+            rel_base_dir = posixpath.normpath(base_dir_path.relative_to(repo_root).as_posix())
+            if rel_base_dir == ".":
+                rel_base_dir = ""
+
+            base_url = compiler_opts.get("baseUrl", ".")
+            raw_paths = compiler_opts.get("paths", {})
+
+            parsed_paths: dict[str, tuple[str, ...]] = {}
+            for pattern, targets in raw_paths.items():
+                if isinstance(targets, list):
+                    parsed_paths[pattern] = tuple(str(t) for t in targets)
+                elif isinstance(targets, str):
+                    parsed_paths[pattern] = (targets,)
+
+            if not parsed_paths and base_url in (".", ""):
+                return None
+
+            return TsConfig(
+                config_path=posixpath.normpath(file_path.relative_to(repo_root).as_posix()),
+                base_dir=rel_base_dir,
+                base_url=base_url,
+                paths=parsed_paths,
+            )
+        except Exception:
+            return None
+
+    def resolve_alias(
+        self,
+        imported_module: str,
+        source_file: str,
+        known_files: set[str],
+    ) -> str | None:
+        """Resolve an aliased module (e.g. '@/components/Button') to a file path in known_files."""
+        if not imported_module or imported_module.startswith("."):
+            return None
+
+        clean_src = source_file.replace("\\", "/").lstrip("./")
+
+        # Pick matching config: deepest base_dir matching source_file, or fallback to root config
+        chosen_config: TsConfig | None = None
+        for cfg in self.configs:
+            if not cfg.base_dir or clean_src.startswith(f"{cfg.base_dir}/"):
+                chosen_config = cfg
+                break
+        if not chosen_config and self.configs:
+            chosen_config = self.configs[-1]
+
+        if not chosen_config:
+            return None
+
+        # Check paths mappings
+        for pattern, targets in chosen_config.paths.items():
+            if "*" in pattern:
+                star_idx = pattern.index("*")
+                prefix = pattern[:star_idx]
+                suffix = pattern[star_idx + 1:]
+                if imported_module.startswith(prefix) and (not suffix or imported_module.endswith(suffix)):
+                    wildcard = imported_module[len(prefix):len(imported_module) - len(suffix) if suffix else None]
+                    for target_tmpl in targets:
+                        target = target_tmpl.replace("*", wildcard)
+                        resolved = self._test_target(
+                            chosen_config.base_dir, chosen_config.base_url, target, known_files
+                        )
+                        if resolved:
+                            return resolved
+            else:
+                # Exact match pattern (e.g. "@lib": ["src/lib"])
+                if imported_module == pattern:
+                    for target in targets:
+                        resolved = self._test_target(
+                            chosen_config.base_dir, chosen_config.base_url, target, known_files
+                        )
+                        if resolved:
+                            return resolved
+
+        # Fallback to baseUrl-relative imports if baseUrl is configured
+        if chosen_config.base_url and chosen_config.base_url not in (".", ""):
+            resolved = self._test_target(
+                chosen_config.base_dir, chosen_config.base_url, imported_module, known_files
+            )
+            if resolved:
+                return resolved
+
+        return None
+
+    @staticmethod
+    def _test_target(
+        base_dir: str,
+        base_url: str,
+        target_path: str,
+        known_files: set[str],
+    ) -> str | None:
+        """Check candidate target path against known repository files with extensions and index files."""
+        # Join base_dir, base_url, and target_path in posix style
+        parts = [p for p in (base_dir, base_url, target_path) if p and p not in (".", "")]
+        base = posixpath.normpath("/".join(parts)).lstrip("./")
+
+        candidates = [base]
+        for ext in (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".css", ".scss"):
+            candidates.append(f"{base}{ext}")
+        for idx in ("index.ts", "index.tsx", "index.js", "index.jsx"):
+            candidates.append(posixpath.join(base, idx))
+
+        for cand in candidates:
+            cand_norm = cand.lstrip("./")
+            if cand_norm in known_files:
+                return cand_norm
+        return None

codegraph/ui/__init__.py

@@ -0,0 +1,6 @@
+"""CodeGraph UI module."""
+from __future__ import annotations
+
+from .server import start_ui_server
+
+__all__ = ["start_ui_server"]