k-cli-for-devs 1.0.0__py3-none-any.whl

k_cli/git/repo_map.py

@@ -0,0 +1,1780 @@
+"""
+repo_map.py - Advanced Semantic Codebase Repository Map & AST Navigator for K-CLI.
+
+Features:
+1. Deep AST & Regex Symbol Extraction across Python, JS/TS, C/C++, Rust, and Go
+   (Classes, Methods, Async Functions, Structs, Enums, Traits, Interfaces, Type Signatures).
+2. Dependency Graph Analysis (Import tree resolution, caller-callee mapping, cyclic import detection).
+3. Compact Token-Optimized Topological Summary for LLM context injection.
+4. Incremental Hashing Cache (mtime + blake2b/sha256 hashing) for sub-millisecond updates.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import logging
+import os
+import re
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CacheEntry:
+    """Internal cache entry storing file metadata, content hash, and extracted AST symbols."""
+    mtime: float
+    size: int
+    content_hash: str
+    symbols: List[Dict[str, Any]]
+    file_info: Dict[str, Any]
+
+
+class RepoMap:
+    """
+    AST-driven Codebase Repository Map extractor, dependency analyzer, and ranker.
+    
+    Provides fast, memory-efficient multi-language symbol extraction, dependency graph
+    analysis (caller-callee, cyclic imports), topological summary generation, and
+    incremental hashing cache for sub-millisecond latency.
+    """
+
+    DEFAULT_IGNORED_DIRS: Set[str] = {
+        ".git",
+        ".agents",
+        ".pytest_cache",
+        ".venv",
+        "k_cli_env",
+        "venv",
+        "env",
+        "data",
+        ".pytest_cache",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        ".tox",
+        ".idea",
+        ".vscode",
+        ".mypy_cache",
+        ".ruff_cache",
+        "site-packages",
+        ".eggs",
+        "target",
+        "vendor",
+        ".next",
+        ".turbo",
+        ".cache",
+        ".agents",
+    }
+
+    SUPPORTED_EXTENSIONS: Set[str] = {
+        ".py",
+        ".pyi",
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+        ".mjs",
+        ".cjs",
+        ".c",
+        ".cc",
+        ".cpp",
+        ".cxx",
+        ".h",
+        ".hh",
+        ".hpp",
+        ".hxx",
+        ".rs",
+        ".go",
+    }
+
+    def __init__(
+        self,
+        root_dir: str = ".",
+        ignored_dirs: Optional[Set[str]] = None,
+        supported_extensions: Optional[Set[str]] = None,
+    ) -> None:
+        """
+        Initializes the RepoMap with a workspace root directory.
+        
+        Args:
+            root_dir: Path to the workspace root directory.
+            ignored_dirs: Optional set of directory names to ignore during scanning.
+            supported_extensions: Optional set of file extensions to include.
+        """
+        self.root_dir = Path(root_dir).resolve()
+        if ignored_dirs is not None:
+            self.ignored_dirs = set(ignored_dirs)
+        else:
+            self.ignored_dirs = set(self.DEFAULT_IGNORED_DIRS)
+
+        if supported_extensions is not None:
+            self.supported_extensions = set(supported_extensions)
+        else:
+            self.supported_extensions = set(self.SUPPORTED_EXTENSIONS)
+
+        # Incremental Cache: str_path -> CacheEntry
+        self._cache: Dict[str, CacheEntry] = {}
+        self._cache_hits: int = 0
+        self._cache_misses: int = 0
+
+    # ==========================================================================
+    # Workspace Traversal & File Filtering
+    # ==========================================================================
+
+    def _should_skip_dir(self, dir_name: str, full_dir_path: Optional[str] = None) -> bool:
+        """Determines if a directory should be skipped during workspace traversal."""
+        if dir_name.startswith("."):
+            return True
+        if dir_name.endswith(".egg-info"):
+            return True
+        if dir_name in self.ignored_dirs:
+            return True
+        if full_dir_path:
+            # Detect virtualenvs dynamically by checking common venv signatures
+            if os.path.isfile(os.path.join(full_dir_path, "pyvenv.cfg")):
+                return True
+            if os.path.isfile(os.path.join(full_dir_path, "bin", "activate")) or os.path.isfile(
+                os.path.join(full_dir_path, "Scripts", "activate")
+            ):
+                return True
+        return False
+
+    def _should_skip_file(self, file_name: str) -> bool:
+        """Determines if a file should be skipped."""
+        if file_name.startswith("."):
+            return True
+        _, ext = os.path.splitext(file_name)
+        return ext.lower() not in self.supported_extensions
+
+    def _is_binary(self, bytes_sample: bytes) -> bool:
+        """Checks if a byte sample contains null bytes or binary characters."""
+        return b"\x00" in bytes_sample
+
+    def scan_workspace_files(self) -> List[str]:
+        """
+        Recursively scans workspace directory for candidate source code files,
+        skipping ignored directories and hidden/binary files.
+        
+        Returns:
+            Sorted list of absolute file paths to valid source files.
+        """
+        if not self.root_dir.exists() or not self.root_dir.is_dir():
+            return []
+
+        source_files: List[str] = []
+        for root, dirs, files in os.walk(str(self.root_dir)):
+            # Filter dirs in-place to prevent walking ignored subtrees
+            dirs[:] = [d for d in dirs if not self._should_skip_dir(d, os.path.join(root, d))]
+            for file_name in files:
+                if not self._should_skip_file(file_name):
+                    full_path = os.path.join(root, file_name)
+                    source_files.append(full_path)
+
+        source_files.sort()
+        return source_files
+
+    # ==========================================================================
+    # Incremental Cache Management
+    # ==========================================================================
+
+    def invalidate_cache(self, file_path: Optional[str] = None) -> None:
+        """Invalidates cache for a specific file or clears entire cache if None."""
+        if file_path is None:
+            self._cache.clear()
+            self._cache_hits = 0
+            self._cache_misses = 0
+        else:
+            path = Path(file_path)
+            if not path.is_absolute():
+                path = (self.root_dir / path).resolve()
+            self._cache.pop(str(path), None)
+
+    def clear_cache(self) -> None:
+        """Clears all cached symbols and statistics."""
+        self.invalidate_cache(None)
+
+    def get_cache_stats(self) -> Dict[str, int]:
+        """Returns cache hit/miss statistics and entry count."""
+        return {
+            "hits": self._cache_hits,
+            "misses": self._cache_misses,
+            "cached_files": len(self._cache),
+        }
+
+    # ==========================================================================
+    # Symbol & Metadata Extraction (Multi-Language)
+    # ==========================================================================
+
+    def extract_symbols(self, file_path: str) -> List[Dict[str, Any]]:
+        """
+        Extracts structured symbol metadata from a source file.
+        
+        Args:
+            file_path: Relative or absolute path to the source file.
+            
+        Returns:
+            List of symbol dictionaries for classes, structs, methods, functions,
+            enums, traits, interfaces, and type aliases.
+            Returns an empty list on syntax errors, missing files, or binary files.
+        """
+        symbols, _ = self._extract_file_info(file_path)
+        return symbols
+
+    def _extract_file_info(self, file_path: str) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """
+        Extracts symbols and cross-file reference metadata from a file.
+        Uses dual-tier fast stat + content hash caching for sub-millisecond lookups.
+        """
+        path = Path(file_path)
+        if not path.is_absolute():
+            path = (self.root_dir / path).resolve()
+
+        if not path.exists() or not path.is_file():
+            return [], {}
+
+        try:
+            stat_res = path.stat()
+            mtime = stat_res.st_mtime
+            size = stat_res.st_size
+        except OSError:
+            return [], {}
+
+        str_path = str(path)
+        cached = self._cache.get(str_path)
+
+        # Tier 1: Fast stat check (sub-millisecond)
+        if cached is not None and cached.mtime == mtime and cached.size == size:
+            self._cache_hits += 1
+            return cached.symbols, cached.file_info
+
+        # Read content safely
+        try:
+            with open(path, "rb") as f:
+                raw_bytes = f.read()
+        except OSError:
+            return [], {}
+
+        if self._is_binary(raw_bytes[:8192]):
+            return [], {}
+
+        # Tier 2: Content Hash check (SHA-256 / Blake2b)
+        content_hash = hashlib.sha256(raw_bytes).hexdigest()
+        if cached is not None and cached.content_hash == content_hash:
+            self._cache_hits += 1
+            # Update mtime and size in cache without re-parsing
+            cached.mtime = mtime
+            cached.size = size
+            return cached.symbols, cached.file_info
+
+        self._cache_misses += 1
+
+        try:
+            source = raw_bytes.decode("utf-8-sig")
+        except UnicodeDecodeError:
+            try:
+                source = raw_bytes.decode("latin-1")
+            except Exception:
+                return [], {}
+
+        source = source.lstrip("\ufeff")
+        if not source.strip():
+            entry = CacheEntry(
+                mtime=mtime,
+                size=size,
+                content_hash=content_hash,
+                symbols=[],
+                file_info={},
+            )
+            self._cache[str_path] = entry
+            return [], {}
+
+        ext = path.suffix.lower()
+        symbols: List[Dict[str, Any]] = []
+        file_info: Dict[str, Any] = {}
+
+        if ext in (".py", ".pyi"):
+            symbols, file_info = self._parse_python(source, str_path)
+        elif ext in (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"):
+            symbols, file_info = self._parse_javascript_typescript(source, str_path, ext)
+        elif ext == ".rs":
+            symbols, file_info = self._parse_rust(source, str_path)
+        elif ext == ".go":
+            symbols, file_info = self._parse_go(source, str_path)
+        elif ext in (".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx"):
+            symbols, file_info = self._parse_cpp(source, str_path)
+        else:
+            symbols, file_info = [], {}
+
+        entry = CacheEntry(
+            mtime=mtime,
+            size=size,
+            content_hash=content_hash,
+            symbols=symbols,
+            file_info=file_info,
+        )
+        self._cache[str_path] = entry
+        return symbols, file_info
+
+    # --------------------------------------------------------------------------
+    # Language Parsers
+    # --------------------------------------------------------------------------
+
+    def _parse_python(self, source: str, str_path: str) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Parses Python source using the native `ast` module."""
+        try:
+            tree = ast.parse(source, filename=str_path)
+        except (SyntaxError, ValueError, MemoryError, RecursionError) as e:
+            logger.debug("Skipping syntax error / invalid AST in %s: %s", str_path, e)
+            return [], {}
+
+        symbols: List[Dict[str, Any]] = []
+        defined_names: Set[str] = set()
+        imported_names: Set[str] = set()
+        referenced_names: Set[str] = set()
+        raw_imports: List[str] = []
+        caller_callees: Dict[str, Set[str]] = defaultdict(set)
+
+        # Collect references, imports, and calls from full AST
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imported_names.add(alias.name.split(".")[0])
+                    raw_imports.append(alias.name)
+                    if alias.asname:
+                        imported_names.add(alias.asname)
+            elif isinstance(node, ast.ImportFrom):
+                mod = node.module or ""
+                if mod:
+                    imported_names.add(mod.split(".")[0])
+                    raw_imports.append(mod)
+                for alias in node.names:
+                    imported_names.add(alias.name)
+                    if mod:
+                        raw_imports.append(f"{mod}.{alias.name}")
+                    if alias.asname:
+                        imported_names.add(alias.asname)
+            elif isinstance(node, ast.Name):
+                referenced_names.add(node.id)
+            elif isinstance(node, ast.Attribute):
+                referenced_names.add(node.attr)
+
+        # Helper to extract calls inside a function or method body
+        def _extract_body_calls(body_nodes: List[ast.stmt]) -> Set[str]:
+            calls: Set[str] = set()
+            for b_node in body_nodes:
+                for sub in ast.walk(b_node):
+                    if isinstance(sub, ast.Call):
+                        if isinstance(sub.func, ast.Name):
+                            calls.add(sub.func.id)
+                        elif isinstance(sub.func, ast.Attribute):
+                            calls.add(sub.func.attr)
+            return calls
+
+        # Traverse top-level nodes for symbol extraction
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                class_sym, class_methods = self._parse_python_class(node)
+                symbols.append(class_sym)
+                symbols.extend(class_methods)
+                defined_names.add(node.name)
+                for m in node.body:
+                    if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        full_name = f"{node.name}.{m.name}"
+                        defined_names.add(m.name)
+                        defined_names.add(full_name)
+                        caller_callees[full_name].update(_extract_body_calls(m.body))
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                func_sym = self._parse_python_func(node, parent_class=None)
+                symbols.append(func_sym)
+                defined_names.add(node.name)
+                caller_callees[node.name].update(_extract_body_calls(node.body))
+
+        file_info: Dict[str, Any] = {
+            "defined_names": defined_names,
+            "imported_names": imported_names,
+            "referenced_names": referenced_names,
+            "raw_imports": raw_imports,
+            "caller_callee": {k: sorted(v) for k, v in caller_callees.items()},
+            "line_count": len(source.splitlines()),
+        }
+
+        return symbols, file_info
+
+    def _parse_python_class(self, node: ast.ClassDef) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
+        """Parses a Python ClassDef AST node into a class symbol and method symbols."""
+        class_name = node.name
+        lineno = node.lineno
+        end_lineno = getattr(node, "end_lineno", lineno)
+        docstring = ast.get_docstring(node)
+        bases = [ast.unparse(b) for b in node.bases]
+        decorators = [ast.unparse(d) for d in node.decorator_list]
+
+        bases_suffix = f"({', '.join(bases)})" if bases else ""
+        signature = f"class {class_name}{bases_suffix}:"
+
+        methods: List[Dict[str, Any]] = []
+        for item in node.body:
+            if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                method_sym = self._parse_python_func(item, parent_class=class_name)
+                methods.append(method_sym)
+
+        class_sym: Dict[str, Any] = {
+            "name": class_name,
+            "type": "class",
+            "parent": None,
+            "class_name": None,
+            "lineno": lineno,
+            "line_number": lineno,
+            "end_lineno": end_lineno,
+            "signature": signature,
+            "docstring": docstring,
+            "bases": bases,
+            "decorators": decorators,
+            "is_async": False,
+            "methods": methods,
+        }
+
+        return class_sym, methods
+
+    def _parse_python_func(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        parent_class: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Parses a Python FunctionDef or AsyncFunctionDef AST node."""
+        is_async = isinstance(node, ast.AsyncFunctionDef)
+        name = node.name
+        lineno = node.lineno
+        end_lineno = getattr(node, "end_lineno", lineno)
+        docstring = ast.get_docstring(node)
+        decorators = [ast.unparse(d) for d in node.decorator_list]
+
+        args_str = ast.unparse(node.args)
+        ret_str = f" -> {ast.unparse(node.returns)}" if node.returns else ""
+        prefix = "async def" if is_async else "def"
+        signature = f"{prefix} {name}({args_str}){ret_str}:"
+
+        all_args = [a.arg for a in node.args.posonlyargs + node.args.args + node.args.kwonlyargs]
+        return_type = ast.unparse(node.returns) if node.returns else None
+
+        node_type: str
+        if parent_class:
+            node_type = "async_method" if is_async else "method"
+        else:
+            node_type = "async_function" if is_async else "function"
+
+        return {
+            "name": name,
+            "type": node_type,
+            "parent": parent_class,
+            "class_name": parent_class,
+            "lineno": lineno,
+            "line_number": lineno,
+            "end_lineno": end_lineno,
+            "signature": signature,
+            "docstring": docstring,
+            "decorators": decorators,
+            "is_async": is_async,
+            "args": all_args,
+            "return_type": return_type,
+        }
+
+    # --------------------------------------------------------------------------
+    # JavaScript & TypeScript Parser
+    # --------------------------------------------------------------------------
+
+    def _parse_javascript_typescript(
+        self, source: str, str_path: str, ext: str
+    ) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Parses JavaScript / TypeScript source for classes, interfaces, enums, functions, and imports."""
+        symbols: List[Dict[str, Any]] = []
+        defined_names: Set[str] = set()
+        imported_names: Set[str] = set()
+        referenced_names: Set[str] = set()
+        raw_imports: List[str] = []
+        caller_callees: Dict[str, Set[str]] = defaultdict(set)
+
+        lines = source.splitlines()
+
+        import_from_re = re.compile(r"""(?:import|export)\s+(?:(?:(?:\*\s+as\s+[\w$]+|[\w$,\s{}]+)\s+from\s+)?['"]([^'"]+)['"]|['"]([^'"]+)['"])""")
+        require_re = re.compile(r"""(?:const|let|var)\s+(?:[\w$,\s{}]+)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)""")
+
+        for line in lines:
+            for match in import_from_re.finditer(line):
+                mod = match.group(1) or match.group(2)
+                if mod:
+                    raw_imports.append(mod)
+                    imported_names.add(os.path.basename(mod).split(".")[0])
+            for match in require_re.finditer(line):
+                mod = match.group(1)
+                if mod:
+                    raw_imports.append(mod)
+                    imported_names.add(os.path.basename(mod).split(".")[0])
+
+        class_re = re.compile(
+            r"^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z0-9_$]+)(?:<[^>]+>)?(?:\s+extends\s+([A-Za-z0-9_$.<>]+))?(?:\s+implements\s+([A-Za-z0-9_$,.<>\s]+))?"
+        )
+        interface_re = re.compile(
+            r"^\s*(?:export\s+)?interface\s+([A-Za-z0-9_$]+)(?:<[^>]+>)?(?:\s+extends\s+([^{]+))?"
+        )
+        enum_re = re.compile(r"^\s*(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z0-9_$]+)")
+        type_alias_re = re.compile(r"^\s*(?:export\s+)?type\s+([A-Za-z0-9_$]+)(?:<[^>]+>)?\s*=")
+        func_re = re.compile(
+            r"^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*(?:\*\s*)?([A-Za-z0-9_$]+)\s*(?:<[^>]+>)?\s*\(([^)]*)\)(?:\s*:\s*([^{;]+))?"
+        )
+        arrow_func_re = re.compile(
+            r"^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*(?::\s*[^=]+)?\s*=\s*(?:async\s*)?(?:\(([^)]*)\)|([A-Za-z0-9_$]+))(?:\s*:\s*(.*?))?\s*=>"
+        )
+        method_re = re.compile(
+            r"^\s*(?:(?:public|private|protected|static|readonly|override|async)\s+)*(?:get\s+|set\s+)?([A-Za-z0-9_$]+)\s*(?:<[^>]+>)?\s*\(([^)]*)\)(?:\s*:\s*([^{;]+))?"
+        )
+
+        non_methods = {
+            "if", "for", "while", "switch", "catch", "return", "super", "require",
+            "import", "export", "typeof", "delete", "this", "new", "throw", "yield", "await"
+        }
+
+        current_class: Optional[Dict[str, Any]] = None
+        current_class_methods: List[Dict[str, Any]] = []
+        brace_depth = 0
+        class_brace_start = 0
+
+        for i, line in enumerate(lines, start=1):
+            trimmed = line.strip()
+            if not trimmed or trimmed.startswith("//") or trimmed.startswith("/*") or trimmed.startswith("*"):
+                continue
+
+            # Check for Class
+            m_class = class_re.match(line)
+            if m_class and not current_class:
+                name = m_class.group(1)
+                base = m_class.group(2)
+                impl = m_class.group(3)
+                bases = []
+                if base:
+                    bases.append(base.strip())
+                if impl:
+                    bases.extend([x.strip() for x in impl.split(",") if x.strip()])
+                bases_str = f" extends {base.strip()}" if base else ""
+                sig = f"class {name}{bases_str}:"
+                current_class = {
+                    "name": name,
+                    "type": "class",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": sig,
+                    "docstring": None,
+                    "bases": bases,
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                }
+                defined_names.add(name)
+                current_class_methods = []
+                class_brace_start = brace_depth + 1
+                brace_depth += line.count("{") - line.count("}")
+                continue
+
+            # Check for Interface
+            m_iface = interface_re.match(line)
+            if m_iface and not current_class:
+                name = m_iface.group(1)
+                ext_str = m_iface.group(2)
+                bases = [x.strip() for x in ext_str.split(",") if x.strip()] if ext_str else []
+                sig = f"interface {name}:"
+                symbols.append({
+                    "name": name,
+                    "type": "interface",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": sig,
+                    "docstring": None,
+                    "bases": bases,
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Check for Enum
+            m_enum = enum_re.match(line)
+            if m_enum and not current_class:
+                name = m_enum.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "enum",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"enum {name}:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Check for Type Alias
+            m_type = type_alias_re.match(line)
+            if m_type and not current_class:
+                name = m_type.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "type_alias",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"type {name} = ...",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Check for Methods inside current class (only at class scope)
+            if current_class and brace_depth == class_brace_start:
+                m_meth = method_re.match(line)
+                if m_meth:
+                    m_name = m_meth.group(1)
+                    if m_name not in non_methods:
+                        args_raw = m_meth.group(2) or ""
+                        ret_raw = m_meth.group(3)
+                        is_async = "async " in line[: line.find(m_name)]
+                        ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                        prefix = "async def" if is_async else "def"
+                        sig = f"{prefix} {m_name}({args_raw.strip()}){ret_str}:"
+                        method_sym = {
+                            "name": m_name,
+                            "type": "async_method" if is_async else "method",
+                            "parent": current_class["name"],
+                            "class_name": current_class["name"],
+                            "lineno": i,
+                            "line_number": i,
+                            "end_lineno": i,
+                            "signature": sig,
+                            "docstring": None,
+                            "decorators": [],
+                            "is_async": is_async,
+                            "args": [a.split(":")[0].strip() for a in args_raw.split(",") if a.strip()],
+                            "return_type": ret_raw.strip() if ret_raw else None,
+                        }
+                        current_class_methods.append(method_sym)
+                        defined_names.add(f"{current_class['name']}.{m_name}")
+                        defined_names.add(m_name)
+
+            # Check for Top-Level Functions
+            if not current_class:
+                m_fn = func_re.match(line)
+                if m_fn:
+                    name = m_fn.group(1)
+                    args_raw = m_fn.group(2) or ""
+                    ret_raw = m_fn.group(3)
+                    is_async = "async " in line[: line.find(name)]
+                    ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                    prefix = "async def" if is_async else "def"
+                    sig = f"{prefix} {name}({args_raw.strip()}){ret_str}:"
+                    symbols.append({
+                        "name": name,
+                        "type": "async_function" if is_async else "function",
+                        "parent": None,
+                        "class_name": None,
+                        "lineno": i,
+                        "line_number": i,
+                        "end_lineno": i,
+                        "signature": sig,
+                        "docstring": None,
+                        "decorators": [],
+                        "is_async": is_async,
+                        "args": [a.split(":")[0].strip() for a in args_raw.split(",") if a.strip()],
+                        "return_type": ret_raw.strip() if ret_raw else None,
+                    })
+                    defined_names.add(name)
+
+                # Check for Arrow Functions
+                m_arrow = arrow_func_re.match(line)
+                if m_arrow:
+                    name = m_arrow.group(1)
+                    args_raw = m_arrow.group(2) or m_arrow.group(3) or ""
+                    ret_raw = m_arrow.group(4)
+                    is_async = "async" in line[: line.find("=>")]
+                    ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                    prefix = "async def" if is_async else "def"
+                    sig = f"{prefix} {name}({args_raw.strip()}){ret_str}:"
+                    symbols.append({
+                        "name": name,
+                        "type": "async_function" if is_async else "function",
+                        "parent": None,
+                        "class_name": None,
+                        "lineno": i,
+                        "line_number": i,
+                        "end_lineno": i,
+                        "signature": sig,
+                        "docstring": None,
+                        "decorators": [],
+                        "is_async": is_async,
+                        "args": [a.split(":")[0].strip() for a in args_raw.split(",") if a.strip()],
+                        "return_type": ret_raw.strip() if ret_raw else None,
+                    })
+                    defined_names.add(name)
+
+            # Update brace depth and check for class end
+            brace_depth += line.count("{") - line.count("}")
+            if current_class and brace_depth < class_brace_start:
+                current_class["end_lineno"] = i
+                current_class["methods"] = current_class_methods
+                symbols.append(current_class)
+                symbols.extend(current_class_methods)
+                current_class = None
+                current_class_methods = []
+
+        if current_class:
+            current_class["end_lineno"] = len(lines)
+            current_class["methods"] = current_class_methods
+            symbols.append(current_class)
+            symbols.extend(current_class_methods)
+
+        # Collect identifier references
+        ident_re = re.compile(r"\b([A-Za-z_$][A-Za-z0-9_$]*)\b")
+        for word in ident_re.findall(source):
+            referenced_names.add(word)
+
+        file_info = {
+            "defined_names": defined_names,
+            "imported_names": imported_names,
+            "referenced_names": referenced_names,
+            "raw_imports": raw_imports,
+            "caller_callee": {k: sorted(v) for k, v in caller_callees.items()},
+            "line_count": len(lines),
+        }
+
+        return symbols, file_info
+
+    # --------------------------------------------------------------------------
+    # Rust Parser
+    # --------------------------------------------------------------------------
+
+    def _parse_rust(self, source: str, str_path: str) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Parses Rust source for structs, enums, traits, impls, functions, and use statements."""
+        symbols: List[Dict[str, Any]] = []
+        defined_names: Set[str] = set()
+        imported_names: Set[str] = set()
+        referenced_names: Set[str] = set()
+        raw_imports: List[str] = []
+        caller_callees: Dict[str, Set[str]] = defaultdict(set)
+
+        lines = source.splitlines()
+
+        use_re = re.compile(r"^\s*use\s+([^;]+);")
+        mod_re = re.compile(r"^\s*(?:pub(?:\([^)]+\))?\s+)?mod\s+([A-Za-z0-9_]+);")
+
+        for line in lines:
+            m_use = use_re.match(line)
+            if m_use:
+                raw_imports.append(m_use.group(1).strip())
+                imported_names.add(m_use.group(1).split("::")[-1].strip())
+            m_mod = mod_re.match(line)
+            if m_mod:
+                raw_imports.append(m_mod.group(1).strip())
+                imported_names.add(m_mod.group(1).strip())
+
+        struct_re = re.compile(r"^\s*(?:pub(?:\([^)]+\))?\s+)?struct\s+([A-Za-z0-9_]+)(?:<[^>]+>)?")
+        enum_re = re.compile(r"^\s*(?:pub(?:\([^)]+\))?\s+)?enum\s+([A-Za-z0-9_]+)(?:<[^>]+>)?")
+        trait_re = re.compile(r"^\s*(?:pub(?:\([^)]+\))?\s+)?trait\s+([A-Za-z0-9_]+)(?:<[^>]+>)?")
+        impl_re = re.compile(r"^\s*impl(?:<[^>]+>)?\s+(?:([A-Za-z0-9_:]+(?:<[^>]+>)?)\s+for\s+)?([A-Za-z0-9_:]+(?:<[^>]+>)?)(?:\s+where\s+[^{]+)?\s*\{")
+        fn_re = re.compile(r"^\s*(?:pub(?:\([^)]+\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern(?:\s+\"[^\"]+\")?\s+)?(?:const\s+)?fn\s+([A-Za-z0-9_]+)(?:<[^>]+>)?\s*\(([^)]*)\)(?:\s*->\s*([^{;]+))?")
+
+        current_impl_target: Optional[str] = None
+        brace_depth = 0
+        impl_brace_start = 0
+
+        struct_map: Dict[str, Dict[str, Any]] = {}
+
+        for i, line in enumerate(lines, start=1):
+            trimmed = line.strip()
+            if not trimmed or trimmed.startswith("//") or trimmed.startswith("/*") or trimmed.startswith("*"):
+                continue
+
+            # Struct
+            m_struct = struct_re.match(line)
+            if m_struct:
+                name = m_struct.group(1)
+                struct_sym = {
+                    "name": name,
+                    "type": "struct",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"struct {name}:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                }
+                symbols.append(struct_sym)
+                struct_map[name] = struct_sym
+                defined_names.add(name)
+
+            # Enum
+            m_enum = enum_re.match(line)
+            if m_enum:
+                name = m_enum.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "enum",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"enum {name}:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Trait
+            m_trait = trait_re.match(line)
+            if m_trait:
+                name = m_trait.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "trait",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"trait {name}:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Impl Block
+            m_impl = impl_re.match(line)
+            if m_impl:
+                trait_name = m_impl.group(1)
+                target_type = m_impl.group(2).split("<")[0].strip()
+                current_impl_target = target_type
+                impl_brace_start = brace_depth + line.count("{") - line.count("}")
+
+            # Function / Method
+            m_fn = fn_re.match(line)
+            if m_fn:
+                name = m_fn.group(1)
+                args_raw = m_fn.group(2) or ""
+                ret_raw = m_fn.group(3)
+                is_async = "async " in line[: line.find(name)]
+                ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                prefix = "async fn" if is_async else "fn"
+                sig = f"{prefix} {name}({args_raw.strip()}){ret_str}:"
+
+                if current_impl_target:
+                    # Method inside impl
+                    method_sym = {
+                        "name": name,
+                        "type": "async_method" if is_async else "method",
+                        "parent": current_impl_target,
+                        "class_name": current_impl_target,
+                        "lineno": i,
+                        "line_number": i,
+                        "end_lineno": i,
+                        "signature": sig,
+                        "docstring": None,
+                        "decorators": [],
+                        "is_async": is_async,
+                        "args": [a.split(":")[0].strip() for a in args_raw.split(",") if a.strip()],
+                        "return_type": ret_raw.strip() if ret_raw else None,
+                    }
+                    symbols.append(method_sym)
+                    if current_impl_target in struct_map:
+                        struct_map[current_impl_target]["methods"].append(method_sym)
+                    defined_names.add(f"{current_impl_target}.{name}")
+                    defined_names.add(name)
+                else:
+                    # Free Function
+                    symbols.append({
+                        "name": name,
+                        "type": "async_function" if is_async else "function",
+                        "parent": None,
+                        "class_name": None,
+                        "lineno": i,
+                        "line_number": i,
+                        "end_lineno": i,
+                        "signature": sig,
+                        "docstring": None,
+                        "decorators": [],
+                        "is_async": is_async,
+                        "args": [a.split(":")[0].strip() for a in args_raw.split(",") if a.strip()],
+                        "return_type": ret_raw.strip() if ret_raw else None,
+                    })
+                    defined_names.add(name)
+
+            brace_depth += line.count("{") - line.count("}")
+            if current_impl_target and brace_depth < impl_brace_start:
+                current_impl_target = None
+
+        # Identifiers
+        ident_re = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\b")
+        for word in ident_re.findall(source):
+            referenced_names.add(word)
+
+        file_info = {
+            "defined_names": defined_names,
+            "imported_names": imported_names,
+            "referenced_names": referenced_names,
+            "raw_imports": raw_imports,
+            "caller_callee": {k: sorted(v) for k, v in caller_callees.items()},
+            "line_count": len(lines),
+        }
+
+        return symbols, file_info
+
+    # --------------------------------------------------------------------------
+    # Go Parser
+    # --------------------------------------------------------------------------
+
+    def _parse_go(self, source: str, str_path: str) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Parses Go source for structs, interfaces, methods, functions, and imports."""
+        symbols: List[Dict[str, Any]] = []
+        defined_names: Set[str] = set()
+        imported_names: Set[str] = set()
+        referenced_names: Set[str] = set()
+        raw_imports: List[str] = []
+        caller_callees: Dict[str, Set[str]] = defaultdict(set)
+
+        lines = source.splitlines()
+
+        in_import_block = False
+        import_line_re = re.compile(r'^\s*(?:[A-Za-z0-9_.]+\s+)?"([^"]+)"')
+
+        for line in lines:
+            trimmed = line.strip()
+            if trimmed.startswith("import ("):
+                in_import_block = True
+                continue
+            if in_import_block:
+                if trimmed.startswith(")"):
+                    in_import_block = False
+                else:
+                    m = import_line_re.match(trimmed)
+                    if m:
+                        pkg = m.group(1)
+                        raw_imports.append(pkg)
+                        imported_names.add(os.path.basename(pkg))
+            elif trimmed.startswith("import "):
+                m = import_line_re.match(trimmed[7:].strip())
+                if m:
+                    pkg = m.group(1)
+                    raw_imports.append(pkg)
+                    imported_names.add(os.path.basename(pkg))
+
+        struct_re = re.compile(r"^\s*type\s+([A-Za-z0-9_]+)\s+struct\s*\{")
+        iface_re = re.compile(r"^\s*type\s+([A-Za-z0-9_]+)\s+interface\s*\{")
+        type_re = re.compile(r"^\s*type\s+([A-Za-z0-9_]+)\s+([^{;=]+)")
+        method_re = re.compile(
+            r"^\s*func\s*\(\s*(?:[A-Za-z0-9_]+\s+)?\*?([A-Za-z0-9_]+)\s*\)\s*([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*(?:\(([^)]*)\)|([^{;]+)))?"
+        )
+        func_re = re.compile(
+            r"^\s*func\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*(?:\(([^)]*)\)|([^{;]+)))?"
+        )
+
+        struct_map: Dict[str, Dict[str, Any]] = {}
+
+        for i, line in enumerate(lines, start=1):
+            trimmed = line.strip()
+            if not trimmed or trimmed.startswith("//") or trimmed.startswith("/*"):
+                continue
+
+            # Struct
+            m_struct = struct_re.match(line)
+            if m_struct:
+                name = m_struct.group(1)
+                struct_sym = {
+                    "name": name,
+                    "type": "struct",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"type {name} struct:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                }
+                symbols.append(struct_sym)
+                struct_map[name] = struct_sym
+                defined_names.add(name)
+                continue
+
+            # Interface
+            m_iface = iface_re.match(line)
+            if m_iface:
+                name = m_iface.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "interface",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"type {name} interface:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+                continue
+
+            # Method (with receiver)
+            m_meth = method_re.match(line)
+            if m_meth:
+                recv = m_meth.group(1)
+                name = m_meth.group(2)
+                args_raw = m_meth.group(3) or ""
+                ret_raw = m_meth.group(4) or m_meth.group(5)
+                ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                sig = f"func (r *{recv}) {name}({args_raw.strip()}){ret_str}:"
+                method_sym = {
+                    "name": name,
+                    "type": "method",
+                    "parent": recv,
+                    "class_name": recv,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": sig,
+                    "docstring": None,
+                    "decorators": [],
+                    "is_async": False,
+                    "args": [a.split()[0].strip() for a in args_raw.split(",") if a.strip()],
+                    "return_type": ret_raw.strip() if ret_raw else None,
+                }
+                symbols.append(method_sym)
+                if recv in struct_map:
+                    struct_map[recv]["methods"].append(method_sym)
+                defined_names.add(f"{recv}.{name}")
+                defined_names.add(name)
+                continue
+
+            # Function
+            m_fn = func_re.match(line)
+            if m_fn:
+                name = m_fn.group(1)
+                args_raw = m_fn.group(2) or ""
+                ret_raw = m_fn.group(3) or m_fn.group(4)
+                ret_str = f" -> {ret_raw.strip()}" if ret_raw else ""
+                sig = f"func {name}({args_raw.strip()}){ret_str}:"
+                symbols.append({
+                    "name": name,
+                    "type": "function",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": sig,
+                    "docstring": None,
+                    "decorators": [],
+                    "is_async": False,
+                    "args": [a.split()[0].strip() for a in args_raw.split(",") if a.strip()],
+                    "return_type": ret_raw.strip() if ret_raw else None,
+                })
+                defined_names.add(name)
+
+        # Identifiers
+        ident_re = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\b")
+        for word in ident_re.findall(source):
+            referenced_names.add(word)
+
+        file_info = {
+            "defined_names": defined_names,
+            "imported_names": imported_names,
+            "referenced_names": referenced_names,
+            "raw_imports": raw_imports,
+            "caller_callee": {k: sorted(v) for k, v in caller_callees.items()},
+            "line_count": len(lines),
+        }
+
+        return symbols, file_info
+
+    # --------------------------------------------------------------------------
+    # C / C++ Parser
+    # --------------------------------------------------------------------------
+
+    def _parse_cpp(self, source: str, str_path: str) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Parses C/C++ source for classes, structs, enums, functions, and includes."""
+        symbols: List[Dict[str, Any]] = []
+        defined_names: Set[str] = set()
+        imported_names: Set[str] = set()
+        referenced_names: Set[str] = set()
+        raw_imports: List[str] = []
+        caller_callees: Dict[str, Set[str]] = defaultdict(set)
+
+        lines = source.splitlines()
+
+        include_re = re.compile(r'^\s*#include\s*["<]([^">]+)[">]')
+        for line in lines:
+            m_inc = include_re.match(line)
+            if m_inc:
+                inc_target = m_inc.group(1)
+                raw_imports.append(inc_target)
+                imported_names.add(os.path.basename(inc_target).split(".")[0])
+
+        class_re = re.compile(
+            r"^\s*(?:template\s*<[^>]+>\s*)?(class|struct)\s+([A-Za-z0-9_]+)(?:\s*:\s*([^{;]+))?\s*\{"
+        )
+        enum_re = re.compile(
+            r"^\s*enum\s+(?:class\s+|struct\s+)?([A-Za-z0-9_]+)(?:\s*:\s*[^{;]+)?\s*\{"
+        )
+        fn_re = re.compile(
+            r"^\s*(?:template\s*<[^>]+>\s*)?(?:(?:static|virtual|inline|explicit|constexpr|friend|extern)\s+)*([A-Za-z0-9_<>:~&*]+)\s+([A-Za-z0-9_~]+)\s*\(([^)]*)\)(?:\s*const)?(?:\s*override|\s*final|\s*noexcept)?(?:\s*=\s*0)?\s*[{;]"
+        )
+
+        current_class: Optional[Dict[str, Any]] = None
+        current_class_methods: List[Dict[str, Any]] = []
+        brace_depth = 0
+        class_brace_start = 0
+
+        for i, line in enumerate(lines, start=1):
+            trimmed = line.strip()
+            if not trimmed or trimmed.startswith("//") or trimmed.startswith("/*") or trimmed.startswith("*") or trimmed.startswith("#"):
+                continue
+
+            # Class / Struct
+            m_cls = class_re.match(line)
+            if m_cls and not current_class:
+                kind = m_cls.group(1)
+                name = m_cls.group(2)
+                bases_raw = m_cls.group(3)
+                bases = [b.strip().split()[-1] for b in bases_raw.split(",") if b.strip()] if bases_raw else []
+                bases_str = f"({', '.join(bases)})" if bases else ""
+                sig = f"{kind} {name}{bases_str}:"
+                current_class = {
+                    "name": name,
+                    "type": "class" if kind == "class" else "struct",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": sig,
+                    "docstring": None,
+                    "bases": bases,
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                }
+                defined_names.add(name)
+                current_class_methods = []
+                class_brace_start = brace_depth + line.count("{") - line.count("}")
+                brace_depth += line.count("{") - line.count("}")
+                continue
+
+            # Enum
+            m_enum = enum_re.match(line)
+            if m_enum and not current_class:
+                name = m_enum.group(1)
+                symbols.append({
+                    "name": name,
+                    "type": "enum",
+                    "parent": None,
+                    "class_name": None,
+                    "lineno": i,
+                    "line_number": i,
+                    "end_lineno": i,
+                    "signature": f"enum {name}:",
+                    "docstring": None,
+                    "bases": [],
+                    "decorators": [],
+                    "is_async": False,
+                    "methods": [],
+                })
+                defined_names.add(name)
+
+            # Function / Method
+            m_fn = fn_re.match(line)
+            if m_fn:
+                ret_type = m_fn.group(1)
+                name = m_fn.group(2)
+                args_raw = m_fn.group(3) or ""
+                if name not in ("if", "for", "while", "switch", "catch", "return") and ret_type not in ("return", "else", "new"):
+                    sig = f"{ret_type} {name}({args_raw.strip()}):"
+                    if current_class:
+                        method_sym = {
+                            "name": name,
+                            "type": "method",
+                            "parent": current_class["name"],
+                            "class_name": current_class["name"],
+                            "lineno": i,
+                            "line_number": i,
+                            "end_lineno": i,
+                            "signature": sig,
+                            "docstring": None,
+                            "decorators": [],
+                            "is_async": False,
+                            "args": [a.split()[-1].lstrip("*&").strip() for a in args_raw.split(",") if a.strip()],
+                            "return_type": ret_type,
+                        }
+                        current_class_methods.append(method_sym)
+                        defined_names.add(f"{current_class['name']}.{name}")
+                        defined_names.add(name)
+                    else:
+                        symbols.append({
+                            "name": name,
+                            "type": "function",
+                            "parent": None,
+                            "class_name": None,
+                            "lineno": i,
+                            "line_number": i,
+                            "end_lineno": i,
+                            "signature": sig,
+                            "docstring": None,
+                            "decorators": [],
+                            "is_async": False,
+                            "args": [a.split()[-1].lstrip("*&").strip() for a in args_raw.split(",") if a.strip()],
+                            "return_type": ret_type,
+                        })
+                        defined_names.add(name)
+
+            brace_depth += line.count("{") - line.count("}")
+            if current_class and brace_depth <= class_brace_start - 1:
+                current_class["end_lineno"] = i
+                current_class["methods"] = current_class_methods
+                symbols.append(current_class)
+                symbols.extend(current_class_methods)
+                current_class = None
+                current_class_methods = []
+
+        if current_class:
+            current_class["end_lineno"] = len(lines)
+            current_class["methods"] = current_class_methods
+            symbols.append(current_class)
+            symbols.extend(current_class_methods)
+
+        ident_re = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\b")
+        for word in ident_re.findall(source):
+            referenced_names.add(word)
+
+        file_info = {
+            "defined_names": defined_names,
+            "imported_names": imported_names,
+            "referenced_names": referenced_names,
+            "raw_imports": raw_imports,
+            "caller_callee": {k: sorted(v) for k, v in caller_callees.items()},
+            "line_count": len(lines),
+        }
+
+        return symbols, file_info
+
+    # ==========================================================================
+    # Dependency Graph & Topological Analysis
+    # ==========================================================================
+
+    def _resolve_relative_path(self, abs_path: str) -> str:
+        """Converts an absolute path to a normalized relative workspace path."""
+        try:
+            return os.path.relpath(abs_path, str(self.root_dir)).replace("\\", "/")
+        except ValueError:
+            return abs_path.replace("\\", "/")
+
+    def _build_workspace_metadata(self) -> List[Dict[str, Any]]:
+        """Scans workspace and gathers symbols and metadata for all supported files."""
+        files = self.scan_workspace_files()
+        file_data: List[Dict[str, Any]] = []
+
+        for fpath in files:
+            rel_path = self._resolve_relative_path(fpath)
+            symbols, info = self._extract_file_info(fpath)
+            file_data.append({
+                "full_path": fpath,
+                "rel_path": rel_path,
+                "symbols": symbols,
+                "info": info,
+            })
+
+        return file_data
+
+    def get_dependency_graph(self) -> Dict[str, List[str]]:
+        """
+        Builds the workspace forward dependency graph (file -> list of files it imports).
+        
+        Returns:
+            Dictionary mapping relative file paths to lists of imported relative file paths.
+        """
+        file_data = self._build_workspace_metadata()
+        all_rel_paths = {item["rel_path"] for item in file_data}
+
+        # Build module resolution index
+        module_index: Dict[str, str] = {}
+        for rel in all_rel_paths:
+            base, _ = os.path.splitext(rel)
+            module_index[rel] = rel
+            module_index[base] = rel
+            module_index[base.replace("/", ".")] = rel
+            module_index[os.path.basename(base)] = rel
+
+        dep_graph: Dict[str, Set[str]] = {item["rel_path"]: set() for item in file_data}
+
+        for item in file_data:
+            src_rel = item["rel_path"]
+            src_dir = os.path.dirname(src_rel)
+            raw_imports = item["info"].get("raw_imports", [])
+            imported_names = item["info"].get("imported_names", set())
+
+            # 1. Resolve raw import strings
+            for raw in raw_imports:
+                clean_raw = raw.strip().lstrip("./").replace("\\", "/")
+                # Try relative to src_dir
+                rel_target = os.path.normpath(os.path.join(src_dir, clean_raw)).replace("\\", "/")
+                resolved = None
+                if rel_target in module_index:
+                    resolved = module_index[rel_target]
+                elif clean_raw in module_index:
+                    resolved = module_index[clean_raw]
+                elif raw.replace(".", "/") in module_index:
+                    resolved = module_index[raw.replace(".", "/")]
+
+                if resolved and resolved != src_rel and resolved in all_rel_paths:
+                    dep_graph[src_rel].add(resolved)
+
+            # 2. Resolve cross-file referenced symbols if not already captured
+            for other in file_data:
+                other_rel = other["rel_path"]
+                if other_rel == src_rel:
+                    continue
+                other_defs = other["info"].get("defined_names", set())
+                if other_defs & imported_names:
+                    dep_graph[src_rel].add(other_rel)
+
+        return {k: sorted(v) for k, v in dep_graph.items()}
+
+    def get_reverse_dependency_graph(self) -> Dict[str, List[str]]:
+        """
+        Builds the workspace reverse dependency graph (file -> list of files that depend on it).
+        
+        Returns:
+            Dictionary mapping relative file paths to lists of dependent relative file paths.
+        """
+        dep_graph = self.get_dependency_graph()
+        rev_graph: Dict[str, Set[str]] = {k: set() for k in dep_graph}
+
+        for src, targets in dep_graph.items():
+            for tgt in targets:
+                if tgt in rev_graph:
+                    rev_graph[tgt].add(src)
+
+        return {k: sorted(v) for k, v in rev_graph.items()}
+
+    def get_import_tree(self, file_path: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Returns the import tree for a specific file or the whole workspace.
+        """
+        dep_graph = self.get_dependency_graph()
+        if file_path:
+            norm = self._resolve_relative_path(file_path)
+            return {norm: dep_graph.get(norm, [])}
+        return dep_graph
+
+    def get_caller_callee_map(self) -> Dict[str, List[str]]:
+        """
+        Builds a mapping of functions/methods to the list of symbols they call.
+        
+        Returns:
+            Dictionary mapping caller symbol name to list of callee symbol names.
+        """
+        file_data = self._build_workspace_metadata()
+        all_callers: Dict[str, Set[str]] = defaultdict(set)
+
+        for item in file_data:
+            cc = item["info"].get("caller_callee", {})
+            for caller, callees in cc.items():
+                all_callers[caller].update(callees)
+
+        return {k: sorted(v) for k, v in all_callers.items()}
+
+    def detect_cyclic_imports(self) -> List[List[str]]:
+        """
+        Detects circular/cyclic import dependencies across workspace files.
+        
+        Returns:
+            List of detected cycles represented as lists of relative file paths.
+        """
+        dep_graph = self.get_dependency_graph()
+        visited: Dict[str, int] = {}  # 0: unvisited, 1: visiting, 2: visited
+        cycles: List[List[str]] = []
+
+        def dfs(node: str, path: List[str]):
+            visited[node] = 1
+            path.append(node)
+
+            for neighbor in dep_graph.get(node, []):
+                if visited.get(neighbor, 0) == 1:
+                    # Cycle found!
+                    try:
+                        idx = path.index(neighbor)
+                        cycle = path[idx:] + [neighbor]
+                        cycles.append(cycle)
+                    except ValueError:
+                        pass
+                elif visited.get(neighbor, 0) == 0:
+                    dfs(neighbor, path)
+
+            path.pop()
+            visited[node] = 2
+
+        for node in dep_graph:
+            if visited.get(node, 0) == 0:
+                dfs(node, [])
+
+        # Deduplicate and normalize cycles
+        unique_cycles: List[List[str]] = []
+        seen_cycle_keys: Set[str] = set()
+
+        for c in cycles:
+            inner = c[:-1]
+            if not inner:
+                continue
+            min_idx = inner.index(min(inner))
+            canonical = inner[min_idx:] + inner[:min_idx]
+            key = "->".join(canonical)
+            if key not in seen_cycle_keys:
+                seen_cycle_keys.add(key)
+                unique_cycles.append(canonical + [canonical[0]])
+
+        return unique_cycles
+
+    def get_symbol_references(self, symbol_name: str) -> List[str]:
+        """
+        Finds all workspace files referencing a given symbol.
+        """
+        file_data = self._build_workspace_metadata()
+        referencing_files: List[str] = []
+
+        for item in file_data:
+            ref_names = item["info"].get("referenced_names", set())
+            imp_names = item["info"].get("imported_names", set())
+            if symbol_name in ref_names or symbol_name in imp_names:
+                referencing_files.append(item["rel_path"])
+
+        referencing_files.sort()
+        return referencing_files
+
+    # ==========================================================================
+    # Map Generation & Token Budgeting
+    # ==========================================================================
+
+    def _matches_focus(self, rel_path: str, full_path: str, focus_files: Optional[List[str]]) -> bool:
+        """Checks if a relative or absolute file path matches any focus file pattern."""
+        if not focus_files:
+            return False
+        rel_norm = rel_path.replace("\\", "/").strip()
+        full_norm = full_path.replace("\\", "/").strip()
+        base_name = os.path.basename(rel_norm)
+
+        for f in focus_files:
+            f_norm = f.replace("\\", "/").strip()
+            if not f_norm:
+                continue
+            if (
+                rel_norm == f_norm
+                or rel_norm.endswith("/" + f_norm)
+                or base_name == f_norm
+                or full_norm == f_norm
+                or full_norm.endswith("/" + f_norm)
+            ):
+                return True
+        return False
+
+    def get_repo_map(
+        self,
+        max_tokens: int = 400,
+        focus_files: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Generates a compact hierarchical tree view of workspace symbols
+        bounded strictly to < max_tokens words/tokens.
+        
+        Prioritizes focus files and architecturally significant symbols.
+        
+        Args:
+            max_tokens: Maximum token/word budget for the returned map text.
+            focus_files: Optional list of file paths to prioritize.
+            
+        Returns:
+            Compact string representation of the codebase map.
+        """
+        if max_tokens <= 0:
+            return ""
+
+        file_data = self._build_workspace_metadata()
+        if not file_data:
+            return ""
+
+        # Score and rank files
+        rev_graph = self.get_reverse_dependency_graph()
+
+        for item in file_data:
+            rel_path = item["rel_path"]
+            full_path = item["full_path"]
+            score = 0.0
+
+            # 1. Focus file priority boost (+10000)
+            if self._matches_focus(rel_path, full_path, focus_files):
+                score += 10000.0
+
+            # 2. In-degree / Cross-file references score
+            dependents = rev_graph.get(rel_path, [])
+            score += len(dependents) * 20.0
+
+            # 3. Architectural significance
+            base_name = os.path.basename(rel_path)
+            if base_name in {
+                "main.py",
+                "app.py",
+                "cli.py",
+                "orchestrator.py",
+                "service.py",
+                "models.py",
+                "core.py",
+                "verifier.py",
+                "llm_driver.py",
+                "index.ts",
+                "main.rs",
+                "main.go",
+                "main.cpp",
+            }:
+                score += 10.0
+            elif base_name in {"__init__.py", "mod.rs"}:
+                score += 2.0
+
+            # 4. Symbol count contribution
+            score += len(item["symbols"]) * 1.5
+
+            # 5. Path depth penalty (shallow files ranked slightly higher)
+            depth = rel_path.count("/")
+            score -= depth * 0.5
+
+            item["score"] = score
+
+        # Sort files by descending importance score
+        file_data.sort(key=lambda x: (-x["score"], x["rel_path"]))
+
+        # Build hierarchical representation respecting token budget
+        return self._render_tree(file_data, max_tokens)
+
+    def _render_tree(self, file_data: List[Dict[str, Any]], max_tokens: int) -> str:
+        """
+        Renders a compact hierarchical tree string from sorted file metadata,
+        strictly enforcing the token budget.
+        """
+        output_lines: List[str] = []
+        current_words = 0
+
+        for item in file_data:
+            symbols = item["symbols"]
+            if not symbols:
+                continue
+
+            rel_path = item["rel_path"]
+            file_header = f"{rel_path}:"
+            header_words = len(file_header.split())
+
+            if current_words + header_words > max_tokens:
+                break
+
+            file_lines: List[str] = [file_header]
+
+            classes: List[Dict[str, Any]] = [
+                s for s in symbols if s.get("type") in ("class", "struct", "interface", "trait", "enum")
+            ]
+            top_funcs: List[Dict[str, Any]] = [
+                s for s in symbols if s.get("type") in ("function", "async_function")
+            ]
+
+            for cls in classes:
+                cls_sig = cls.get("signature", f"class {cls['name']}:")
+                file_lines.append(f"  {cls_sig}")
+                for m in cls.get("methods", []):
+                    m_sig = m.get("signature", f"def {m['name']}(...):")
+                    file_lines.append(f"    {m_sig}")
+
+            for fn in top_funcs:
+                fn_sig = fn.get("signature", f"def {fn['name']}(...):")
+                file_lines.append(f"  {fn_sig}")
+
+            # Append lines while within budget
+            for line in file_lines:
+                line_words = len(line.split())
+                if current_words + line_words <= max_tokens:
+                    output_lines.append(line)
+                    current_words += line_words
+                else:
+                    break
+
+        result = "\n".join(output_lines)
+        return result
+
+    # ==========================================================================
+    # Compact Topological Summary for LLM Context Injection
+    # ==========================================================================
+
+    def get_topological_summary(
+        self,
+        max_tokens: int = 400,
+        focus_files: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Generates a token-optimized topological summary of the codebase,
+        ordering files from foundational dependencies up to high-level entrypoints.
+        
+        Args:
+            max_tokens: Maximum word/token budget for the summary.
+            focus_files: Optional list of focus files to prioritize.
+            
+        Returns:
+            Compact topological summary string suitable for LLM system prompt injection.
+        """
+        if max_tokens <= 0:
+            return ""
+
+        file_data = self._build_workspace_metadata()
+        if not file_data:
+            return ""
+
+        dep_graph = self.get_dependency_graph()
+        cycles = self.detect_cyclic_imports()
+
+        # Compute In-degrees (how many files depend on this file)
+        in_degrees: Dict[str, int] = {item["rel_path"]: 0 for item in file_data}
+        for src, tgts in dep_graph.items():
+            for t in tgts:
+                if t in in_degrees:
+                    in_degrees[t] += 1
+
+        # Layer computation: Leaves (0 outgoing deps in workspace) -> Layer 0
+        layers: Dict[int, List[Dict[str, Any]]] = defaultdict(list)
+        depth_map: Dict[str, int] = {}
+
+        def get_depth(node: str, visited: Set[str]) -> int:
+            if node in depth_map:
+                return depth_map[node]
+            if node in visited:
+                return 0
+            visited.add(node)
+            deps = [d for d in dep_graph.get(node, []) if d != node]
+            if not deps:
+                depth_map[node] = 0
+                return 0
+            max_d = 1 + max(get_depth(d, visited) for d in deps)
+            depth_map[node] = max_d
+            return max_d
+
+        for item in file_data:
+            rel = item["rel_path"]
+            d = get_depth(rel, set())
+            layers[d].append(item)
+
+        output_lines: List[str] = ["[Topological Architecture Map]"]
+        current_words = len(output_lines[0].split())
+
+        # Cycle notice if any
+        if cycles:
+            cycle_str = f"[!] Cyclic Imports Detected: {len(cycles)} cycle(s)"
+            if current_words + len(cycle_str.split()) <= max_tokens:
+                output_lines.append(cycle_str)
+                current_words += len(cycle_str.split())
+
+        # Render layer by layer
+        layer_names = {
+            0: "Base / Foundation Modules",
+            1: "Core Components & Utilities",
+            2: "Services & Domain Logic",
+            3: "Application Orchestrators & APIs",
+            4: "Entrypoints & CLI",
+        }
+
+        for layer_idx in sorted(layers.keys()):
+            layer_items = layers[layer_idx]
+            # Prioritize focus files and high in-degree within layer
+            layer_items.sort(
+                key=lambda x: (
+                    -1000 if self._matches_focus(x["rel_path"], x["full_path"], focus_files) else 0,
+                    -in_degrees.get(x["rel_path"], 0),
+                    x["rel_path"],
+                )
+            )
+
+            layer_title = layer_names.get(layer_idx, f"Layer {layer_idx}")
+            header = f"\n=== {layer_title} ==="
+            header_words = len(header.split())
+            if current_words + header_words > max_tokens:
+                break
+            output_lines.append(header)
+            current_words += header_words
+
+            for item in layer_items:
+                rel = item["rel_path"]
+                deps = dep_graph.get(rel, [])
+                deps_suffix = f" (deps: {', '.join(deps)})" if deps else ""
+                file_line = f"  • {rel}{deps_suffix}"
+                file_words = len(file_line.split())
+                if current_words + file_words > max_tokens:
+                    break
+                output_lines.append(file_line)
+                current_words += file_words
+
+                # Add compact symbol summary
+                classes = [s for s in item["symbols"] if s.get("type") in ("class", "struct", "interface", "trait", "enum")]
+                funcs = [s for s in item["symbols"] if s.get("type") in ("function", "async_function")]
+
+                for cls in classes:
+                    cls_line = f"    - {cls.get('signature', cls['name'])}"
+                    cls_words = len(cls_line.split())
+                    if current_words + cls_words <= max_tokens:
+                        output_lines.append(cls_line)
+                        current_words += cls_words
+
+                for fn in funcs:
+                    fn_line = f"    - {fn.get('signature', fn['name'])}"
+                    fn_words = len(fn_line.split())
+                    if current_words + fn_words <= max_tokens:
+                        output_lines.append(fn_line)
+                        current_words += fn_words
+
+        return "\n".join(output_lines).strip()
+