misterdev 0.2.0__py3-none-any.whl

misterdev/core/context/topography/_log.py

@@ -0,0 +1,10 @@
+"""Shared package logger.
+
+Named for the package (not this submodule) so log output keeps the pre-split
+logger name ``misterdev.core.context.topography`` after the
+god-module was broken into sections.
+"""
+
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__.rsplit(".", 1)[0])

misterdev/core/context/topography/cache.py

@@ -0,0 +1,91 @@
+"""Disk-backed per-file symbol cache, keyed by content hash + lang + format."""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Any
+
+from misterdev.utils.file_utils import atomic_write_json
+
+from ._log import logger
+from .nodes import SymbolNode, _symbol_to_dict, _symbol_from_dict
+
+# Bump when the parse output shape or any _traverse_* logic changes, so a stale
+# on-disk cache from an older grammar/format is discarded rather than served.
+_CACHE_FORMAT_VERSION = 1
+
+
+class _TopographyCache:
+    """Disk-backed per-file symbol cache, keyed by content hash + lang + format.
+
+    Maps a project-relative path to ``{"key": <hash>, "symbols": [...]}`` where
+    the key folds the file's content sha256, its language, and the cache-format
+    version. An entry is only reused when the recomputed key matches, so an edit
+    (content change), a language change, or a format bump all invalidate it; mtime
+    is never consulted. Every read/write is best-effort: a corrupt or unreadable
+    cache degrades to an empty in-memory map and a full parse, never a raise and
+    never stale symbols.
+    """
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self.entries: Dict[str, Dict[str, Any]] = {}
+
+    @staticmethod
+    def make_key(content_bytes: bytes, lang: str) -> str:
+        h = hashlib.sha256()
+        h.update(f"{_CACHE_FORMAT_VERSION}\x00{lang}\x00".encode("utf-8"))
+        h.update(content_bytes)
+        return h.hexdigest()
+
+    def load(self) -> None:
+        if not self.path.exists():
+            return
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, ValueError) as e:
+            logger.debug(f"Topography cache unreadable, starting fresh: {e}")
+            self.entries = {}
+            return
+        if (
+            not isinstance(data, dict)
+            or data.get("format") != _CACHE_FORMAT_VERSION
+            or not isinstance(data.get("files"), dict)
+        ):
+            logger.debug("Topography cache format mismatch; starting fresh")
+            self.entries = {}
+            return
+        self.entries = data["files"]
+
+    def get(self, rel_path: str, key: str) -> Optional[List["SymbolNode"]]:
+        """Cached symbols for ``rel_path`` iff its key matches, else None."""
+        entry = self.entries.get(rel_path)
+        if not isinstance(entry, dict) or entry.get("key") != key:
+            return None
+        raw = entry.get("symbols")
+        if not isinstance(raw, list):
+            return None
+        try:
+            return [_symbol_from_dict(d) for d in raw]
+        except (KeyError, TypeError) as e:
+            logger.debug(f"Topography cache entry for {rel_path} malformed: {e}")
+            return None
+
+    def put(self, rel_path: str, key: str, symbols: List["SymbolNode"]) -> None:
+        self.entries[rel_path] = {
+            "key": key,
+            "symbols": [_symbol_to_dict(s) for s in symbols],
+        }
+
+    def prune(self, live_paths: Set[str]) -> None:
+        """Drop entries for files no longer present in the source tree."""
+        for stale in [p for p in self.entries if p not in live_paths]:
+            del self.entries[stale]
+
+    def save(self) -> None:
+        try:
+            atomic_write_json(
+                self.path, {"format": _CACHE_FORMAT_VERSION, "files": self.entries}
+            )
+        except OSError as e:
+            logger.debug(f"Topography cache write failed (non-fatal): {e}")

misterdev/core/context/topography/engine.py

@@ -0,0 +1,172 @@
+"""The Topography Engine: a lazy-loaded facade over the symbol graph."""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Any
+
+from ._log import logger
+from .nodes import SymbolNode
+from .graph import SymbolGraph
+
+
+class TopographyEngine:
+    """Topography Engine with Vector Persistence and Lazy Loading."""
+
+    def __init__(self, project_path: Path, llm_client: Any, golden_paths=None):
+        self.project_path = project_path
+        self.llm = llm_client
+        self.graph = SymbolGraph(project_path, golden_paths=golden_paths)
+        self._initialized = False
+
+    def initialize(self, force: bool = False):
+        if self._initialized and not force:
+            return
+
+        logger.info("Initializing Topography Engine...")
+        self.graph.build()
+        logger.info(f"Symbol graph: {len(self.graph.symbols)} symbols indexed")
+        self._initialized = True
+
+    def invalidate(self) -> None:
+        """Mark the symbol graph stale so the next access rebuilds it.
+
+        The graph is built once and then never reflected the edits tasks made, so
+        later tasks saw a stale map — missing new symbols, listing deleted ones —
+        which weakens reference discovery and the dangling-reference gate. Calling
+        this after a task changes the tree makes the next task rebuild from the
+        current on-disk state. Rebuild is cheap: the per-file symbol cache is
+        content-hashed, so only files that actually changed are re-parsed.
+        """
+        self._initialized = False
+
+    def get_file_outline(self, file_path: str) -> str:
+        self.initialize()
+        return self.graph.file_outline(file_path)
+
+    def get_file_symbols(self, file_path: str):
+        self.initialize()
+        return self.graph.file_symbols(file_path)
+
+    def get_project_outline(self) -> str:
+        self.initialize()
+        return self.graph.project_outline()
+
+    def get_context_for_task(
+        self,
+        query: str,
+        related_files: List[str],
+        max_symbols: int = 30,
+        ranker=None,
+        exclude_files: Optional[Set[str]] = None,
+    ) -> str:
+        """Retrieves functional neighborhood and semantic context. Triggers lazy init.
+
+        When more candidate symbols are found than fit (``max_symbols``) and a
+        semantic ``ranker`` is supplied, the kept symbols are the ones most
+        relevant to ``query`` rather than an arbitrary slice.
+
+        ``exclude_files`` names files already sent verbatim IN FULL by another
+        context section (small target files in code_context). Their own symbols
+        are dropped here so the same code isn't duplicated across two sections;
+        their cross-file call-neighbors are still surfaced. Files shown only as a
+        windowed excerpt must NOT be excluded — their out-of-window symbols are
+        complementary, not duplicate.
+        """
+        self.initialize()
+        excluded = exclude_files or set()
+
+        context_symbols: Set[str] = set()
+        for file in related_files:
+            for key, sym in self.graph.symbols.items():
+                if sym.file_path == file:
+                    if file not in excluded:
+                        context_symbols.add(key)
+                    context_symbols.update(sym.outgoing_calls)
+                    context_symbols.update(sym.incoming_calls)
+
+        if excluded:
+            context_symbols = {
+                key
+                for key in context_symbols
+                if key not in self.graph.symbols
+                or self.graph.symbols[key].file_path not in excluded
+            }
+
+        if not context_symbols:
+            return ""
+
+        # Cap to avoid blowing LLM context, keeping the most task-relevant
+        # symbols when a semantic ranker is available.
+        if ranker is not None and len(context_symbols) > max_symbols:
+            candidates = {
+                key: self.graph.symbols[key].content
+                for key in context_symbols
+                if key in self.graph.symbols
+            }
+            symbol_list = ranker.top_k(query, candidates, max_symbols)
+        else:
+            symbol_list = list(context_symbols)[:max_symbols]
+
+        output = "## Topological Context\n"
+        by_file: Dict[str, List[SymbolNode]] = {}
+        for key in symbol_list:
+            if key in self.graph.symbols:
+                sym = self.graph.symbols[key]
+                by_file.setdefault(sym.file_path, []).append(sym)
+
+        for file_path, syms in by_file.items():
+            output += f"\n### Symbols in {file_path}\n"
+            for sym in syms:
+                output += f"\n# {sym.kind.upper()}: {sym.name}\n{sym.content}\n"
+
+        if len(context_symbols) > max_symbols:
+            output += (
+                f"\n(... {len(context_symbols) - max_symbols} more symbols omitted)\n"
+            )
+
+        return output
+
+    def reference_sites(self, target_files: List[str], max_refs: int = 80) -> str:
+        """Every EXTERNAL call site of the symbols defined in ``target_files``.
+
+        A delete/rename/refactor task must update every reference to the symbol
+        it changes, but the referencing files often sit outside the task's
+        declared scope — so the model discovers them one build-error at a time
+        and runs out of attempts (whack-a-mole). Listing all of them up front,
+        with exact file:line, lets one attempt update them completely. Only
+        references OUTSIDE the target files are listed (in-file uses are already
+        visible in code_context). Returns '' when there are none.
+        """
+        self.initialize()
+        targets = set(target_files)
+        blocks: List[str] = []
+        shown = 0
+        for sym in self.graph.symbols.values():
+            if sym.file_path not in targets or not sym.incoming_calls:
+                continue
+            sites = set()
+            for caller_key in sym.incoming_calls:
+                caller = self.graph.symbols.get(caller_key)
+                if caller is not None and caller.file_path not in targets:
+                    sites.add((caller.file_path, caller.start_line, caller.name))
+            if not sites:
+                continue
+            lines = [f"- `{sym.name}` ({sym.kind}) is referenced by:"]
+            for fp, ln, nm in sorted(sites):
+                if shown >= max_refs:
+                    lines.append("    - (... more references omitted)")
+                    break
+                lines.append(f"    - {fp}:{ln} (in {nm})")
+                shown += 1
+            blocks.append("\n".join(lines))
+            if shown >= max_refs:
+                break
+        if not blocks:
+            return ""
+        return (
+            "## Complete External Reference Sites\n"
+            "Every reference to a symbol defined in the files you are editing "
+            "that lives OUTSIDE those files. If this task removes, renames, or "
+            "changes the signature of such a symbol, you MUST update ALL of these "
+            "sites in this attempt — the build fails on any you miss:\n"
+            + "\n".join(blocks)
+        )