codecortex-context-engine 0.1.0a1__py3-none-any.whl

codecortex/indexing/resolution.py

@@ -0,0 +1,88 @@
+"""Cross-file symbol resolution with explicit confidence and ambiguity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from codecortex.indexing.graph import GraphNode
+
+
+@dataclass(frozen=True, slots=True)
+class ResolutionCandidate:
+    node_id: str
+    score: float
+    reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ResolutionResult:
+    target_id: str | None
+    confidence: float
+    ambiguity: float
+    candidates: tuple[ResolutionCandidate, ...]
+
+
+class CrossFileResolver:
+    """Rank same-name symbols while preserving uncertainty for downstream agents."""
+
+    def resolve(
+        self,
+        name: str,
+        source_path: str,
+        candidates: list[GraphNode],
+        relation_kind: str,
+    ) -> ResolutionResult:
+        ranked: list[ResolutionCandidate] = []
+        source = PurePosixPath(source_path)
+        for node in candidates:
+            if node.path is None:
+                continue
+            target = PurePosixPath(node.path)
+            score = 0.35
+            reasons = ["exact_symbol_name"]
+            if target == source:
+                score += 0.35
+                reasons.append("same_file")
+            elif target.parent == source.parent:
+                score += 0.20
+                reasons.append("same_directory")
+            else:
+                shared = len(set(source.parts[:-1]) & set(target.parts[:-1]))
+                if shared:
+                    score += min(0.12, shared * 0.03)
+                    reasons.append("shared_package_path")
+            if relation_kind == "calls" and node.kind in {
+                "function",
+                "async_function",
+                "method",
+            }:
+                score += 0.08
+                reasons.append("callable_kind")
+            if relation_kind in {"inherits", "implements"} and node.kind in {
+                "class",
+                "interface",
+            }:
+                score += 0.08
+                reasons.append("type_kind")
+            ranked.append(
+                ResolutionCandidate(
+                    node_id=node.id,
+                    score=min(1.0, score),
+                    reasons=tuple(reasons),
+                )
+            )
+        ranked.sort(key=lambda item: (-item.score, item.node_id))
+        if not ranked:
+            return ResolutionResult(None, 0.0, 1.0, ())
+        best = ranked[0]
+        second = ranked[1].score if len(ranked) > 1 else 0.0
+        margin = max(0.0, best.score - second)
+        ambiguity = 0.0 if len(ranked) == 1 else max(0.0, min(1.0, 1.0 - margin))
+        confidence = max(0.0, min(1.0, best.score * (1.0 - 0.45 * ambiguity)))
+        return ResolutionResult(
+            target_id=best.node_id,
+            confidence=confidence,
+            ambiguity=ambiguity,
+            candidates=tuple(ranked[:5]),
+        )

codecortex/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""Coding-agent integration helpers."""
+
+from codecortex.integrations.agents import AgentConfigurator, AgentMutation, AgentTarget
+
+__all__ = ["AgentConfigurator", "AgentMutation", "AgentTarget"]

codecortex/integrations/agents.py

@@ -0,0 +1,235 @@
+"""Merge-safe project configuration for MCP-capable coding agents."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class AgentTarget(StrEnum):
+    CLAUDE = "claude"
+    CODEX = "codex"
+    CURSOR = "cursor"
+    GEMINI = "gemini"
+    OPENCODE = "opencode"
+
+
+@dataclass(frozen=True, slots=True)
+class AgentMutation:
+    target: AgentTarget
+    path: Path
+    detected: bool
+    changed: bool
+    backup: Path | None = None
+    detail: str = ""
+
+
+class AgentConfigurationError(RuntimeError):
+    pass
+
+
+class AgentConfigurator:
+    """Configure project-local integrations without clobbering user-owned settings."""
+
+    COMMANDS = {
+        AgentTarget.CLAUDE: ("claude",),
+        AgentTarget.CODEX: ("codex",),
+        AgentTarget.GEMINI: ("gemini",),
+        AgentTarget.OPENCODE: ("opencode",),
+    }
+
+    def __init__(self, root: Path, *, executable: str = "cortex") -> None:
+        self.root = root.expanduser().resolve()
+        self.executable = executable
+
+    def detect(self) -> tuple[AgentTarget, ...]:
+        found: set[AgentTarget] = set()
+        for target, commands in self.COMMANDS.items():
+            if any(shutil.which(command) for command in commands):
+                found.add(target)
+        if (self.root / ".cursor").exists() or shutil.which("cursor"):
+            found.add(AgentTarget.CURSOR)
+        if (self.root / ".mcp.json").exists():
+            found.add(AgentTarget.CLAUDE)
+        if (self.root / ".gemini").exists():
+            found.add(AgentTarget.GEMINI)
+        if (self.root / ".codex").exists():
+            found.add(AgentTarget.CODEX)
+        if (self.root / "opencode.json").exists():
+            found.add(AgentTarget.OPENCODE)
+        return tuple(sorted(found, key=str))
+
+    def configure(
+        self,
+        targets: tuple[AgentTarget, ...] | None = None,
+        *,
+        dry_run: bool = False,
+    ) -> tuple[AgentMutation, ...]:
+        selected = targets or self.detect()
+        return tuple(self.configure_one(target, dry_run=dry_run) for target in selected)
+
+    def configure_one(self, target: AgentTarget, *, dry_run: bool = False) -> AgentMutation:
+        detected = target in self.detect()
+        if target == AgentTarget.CLAUDE:
+            return self._configure_json(
+                target,
+                self.root / ".mcp.json",
+                ("mcpServers",),
+                self._stdio_json(),
+                detected,
+                dry_run,
+            )
+        if target == AgentTarget.CURSOR:
+            return self._configure_json(
+                target,
+                self.root / ".cursor" / "mcp.json",
+                ("mcpServers",),
+                self._stdio_json(),
+                detected,
+                dry_run,
+            )
+        if target == AgentTarget.GEMINI:
+            return self._configure_json(
+                target,
+                self.root / ".gemini" / "settings.json",
+                ("mcpServers",),
+                self._stdio_json(),
+                detected,
+                dry_run,
+            )
+        if target == AgentTarget.OPENCODE:
+            return self._configure_json(
+                target,
+                self.root / "opencode.json",
+                ("mcp", "servers"),
+                {
+                    "type": "local",
+                    "command": [self.executable, "mcp", "--path", str(self.root)],
+                },
+                detected,
+                dry_run,
+                defaults={"$schema": "https://opencode.ai/config.json"},
+            )
+        if target == AgentTarget.CODEX:
+            return self._configure_codex(detected=detected, dry_run=dry_run)
+        raise ValueError(target)
+
+    def _stdio_json(self) -> dict[str, Any]:
+        return {
+            "command": self.executable,
+            "args": ["mcp", "--path", str(self.root)],
+            "env": {"CODECORTEX_BACKENDS": "auto"},
+        }
+
+    def _configure_json(
+        self,
+        target: AgentTarget,
+        path: Path,
+        container_keys: tuple[str, ...],
+        server: dict[str, Any],
+        detected: bool,
+        dry_run: bool,
+        *,
+        defaults: dict[str, Any] | None = None,
+    ) -> AgentMutation:
+        payload: dict[str, Any] = dict(defaults or {})
+        if path.exists():
+            try:
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                raise AgentConfigurationError(f"refusing to modify invalid JSON: {path}: {exc}") from exc
+            if not isinstance(loaded, dict):
+                raise AgentConfigurationError(f"expected a JSON object: {path}")
+            payload = loaded
+            for key, value in (defaults or {}).items():
+                payload.setdefault(key, value)
+        container: dict[str, Any] = payload
+        for key in container_keys:
+            child = container.get(key)
+            if child is None:
+                child = {}
+                container[key] = child
+            if not isinstance(child, dict):
+                raise AgentConfigurationError(f"cannot merge CodeCortex into non-object {'.'.join(container_keys)} in {path}")
+            container = child
+        previous = container.get("codecortex")
+        container["codecortex"] = server
+        changed = previous != server or not path.exists()
+        if not changed or dry_run:
+            return AgentMutation(target, path, detected, changed, detail="dry-run" if dry_run and changed else "already configured")
+        backup = self._backup(path)
+        self._atomic_write(path, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+        return AgentMutation(target, path, detected, True, backup=backup, detail="configured")
+
+    def _configure_codex(self, *, detected: bool, dry_run: bool) -> AgentMutation:
+        path = self.root / ".codex" / "config.toml"
+        begin = "# >>> codecortex managed mcp >>>"
+        end = "# <<< codecortex managed mcp <<<"
+        args = ["mcp", "--path", str(self.root)]
+        block = "\n".join(
+            [
+                begin,
+                "[mcp_servers.codecortex]",
+                f"command = {json.dumps(self.executable)}",
+                f"args = {json.dumps(args)}",
+                "env = { CODECORTEX_BACKENDS = \"auto\" }",
+                "enabled = true",
+                "startup_timeout_sec = 30",
+                "tool_timeout_sec = 120",
+                end,
+            ]
+        )
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        managed = re.compile(re.escape(begin) + r".*?" + re.escape(end), re.DOTALL)
+        if managed.search(existing):
+            # A callable replacement keeps Windows backslashes literal instead of
+            # letting re.sub interpret them as replacement-string escapes.
+            updated = managed.sub(lambda _match: block, existing)
+        else:
+            if re.search(r"(?m)^\s*\[mcp_servers\.codecortex\]\s*$", existing):
+                raise AgentConfigurationError(
+                    f"refusing to overwrite an unmanaged [mcp_servers.codecortex] table in {path}"
+                )
+            separator = "\n\n" if existing.strip() else ""
+            updated = existing.rstrip() + separator + block + "\n"
+        changed = updated != existing
+        if not changed or dry_run:
+            return AgentMutation(AgentTarget.CODEX, path, detected, changed, detail="dry-run" if dry_run and changed else "already configured")
+        backup = self._backup(path)
+        self._atomic_write(path, updated)
+        return AgentMutation(AgentTarget.CODEX, path, detected, True, backup=backup, detail="configured")
+
+    @staticmethod
+    def _backup(path: Path) -> Path | None:
+        if not path.exists():
+            return None
+        stamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S-%f")
+        backup = path.with_name(f"{path.name}.codecortex-{stamp}.bak")
+        backup.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, backup)
+        return backup
+
+    @staticmethod
+    def _atomic_write(path: Path, content: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temp_name, path)
+        except Exception:
+            try:
+                os.unlink(temp_name)
+            except OSError:
+                pass
+            raise

codecortex/interfaces/__init__.py

@@ -0,0 +1 @@
+"""External interface adapters."""

codecortex/interfaces/mcp_bridge.py

@@ -0,0 +1,66 @@
+"""Protocol-neutral tool bridge for MCP-compatible hosts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from codecortex.gateway import CodeCortexGateway
+
+
+class MCPBridge:
+    """Expose stable tool definitions without coupling the core to one transport."""
+
+    def __init__(self, gateway: CodeCortexGateway) -> None:
+        self.gateway = gateway
+
+    def tool_definitions(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "name": "cortex_route",
+                "description": "Classify a coding request and return the selected capabilities.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}},
+                    "required": ["query"],
+                },
+            },
+            {
+                "name": "cortex_query",
+                "description": "Run repository intelligence for a coding request.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}},
+                    "required": ["query"],
+                },
+            },
+            {
+                "name": "cortex_remember",
+                "description": "Save a project decision or reusable fact.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "key": {"type": "string"},
+                        "value": {"type": "string"},
+                    },
+                    "required": ["key", "value"],
+                },
+            },
+            {
+                "name": "cortex_health",
+                "description": "Return CodeCortex engine health.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+        ]
+
+    async def call(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        if name == "cortex_route":
+            return self.gateway.route(str(arguments["query"])).model_dump(mode="json")
+        if name == "cortex_query":
+            result = await self.gateway.query(str(arguments["query"]))
+            return result.model_dump(mode="json")
+        if name == "cortex_remember":
+            await self.gateway.remember(str(arguments["key"]), str(arguments["value"]))
+            return {"saved": True}
+        if name == "cortex_health":
+            return await self.gateway.health()
+        raise KeyError(f"Unknown tool: {name}")

codecortex/languages/__init__.py

@@ -0,0 +1,5 @@
+"""Language intelligence primitives."""
+
+from codecortex.languages.registry import LanguageRegistry, LanguageSpec, ParsedUnit
+
+__all__ = ["LanguageRegistry", "LanguageSpec", "ParsedUnit"]

codecortex/languages/native.py

@@ -0,0 +1,166 @@
+"""Optional Tree-sitter parser provider for production polyglot structure."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class NativeUnit:
+    name: str
+    kind: str
+    line: int
+    end_line: int
+    signature: str | None = None
+    return_type: str | None = None
+    bases: tuple[str, ...] = ()
+    references: tuple[str, ...] = ()
+
+
+class TreeSitterParserProvider:
+    """Parse major languages with native grammars when the parser extra is installed."""
+
+    aliases = {
+        "typescript": "typescript",
+        "javascript": "javascript",
+        "go": "go",
+        "rust": "rust",
+        "java": "java",
+        "c": "c",
+        "cpp": "cpp",
+        "csharp": "csharp",
+        "php": "php",
+        "ruby": "ruby",
+    }
+
+    kinds = {
+        "class_declaration": "class",
+        "class_definition": "class",
+        "class_specifier": "class",
+        "interface_declaration": "interface",
+        "trait_item": "interface",
+        "struct_item": "struct",
+        "struct_specifier": "struct",
+        "enum_item": "enum",
+        "enum_declaration": "enum",
+        "function_declaration": "function",
+        "function_definition": "function",
+        "function_item": "function",
+        "method_declaration": "method",
+        "method_definition": "method",
+        "constructor_declaration": "constructor",
+        "singleton_method": "method",
+    }
+
+    def __init__(self) -> None:
+        try:
+            from tree_sitter_language_pack import get_parser
+        except ImportError as exc:
+            raise RuntimeError("install CodeCortex with the `parsers` extra") from exc
+        self._get_parser = get_parser
+
+    @classmethod
+    def available(cls) -> bool:
+        try:
+            import tree_sitter_language_pack  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    def parse(self, language: str, source: str) -> list[NativeUnit]:
+        alias = self.aliases.get(language)
+        if alias is None:
+            return []
+        parser = self._get_parser(alias)
+        tree = parser.parse(source.encode("utf-8"))
+        root = tree.root_node
+        source_bytes = source.encode("utf-8")
+        units: list[NativeUnit] = []
+        stack = [root]
+        while stack:
+            node = stack.pop()
+            stack.extend(reversed(list(getattr(node, "children", ()))))
+            kind = self.kinds.get(str(getattr(node, "type", "")))
+            if kind is None:
+                continue
+            name_node = self._field(node, "name") or self._first_identifier(node)
+            if name_node is None:
+                continue
+            name = self._text(name_node, source_bytes).strip()
+            if not name:
+                continue
+            return_node = self._field(node, "return_type") or self._field(node, "type")
+            bases = self._bases(node, source_bytes)
+            refs = self._references(node, source_bytes, name)
+            units.append(
+                NativeUnit(
+                    name=name,
+                    kind=kind,
+                    line=int(node.start_point.row) + 1,
+                    end_line=int(node.end_point.row) + 1,
+                    signature=self._signature(node, source_bytes),
+                    return_type=(
+                        self._text(return_node, source_bytes).strip()
+                        if return_node is not None
+                        else None
+                    ),
+                    bases=bases,
+                    references=refs,
+                )
+            )
+        units.sort(key=lambda item: (item.line, item.end_line, item.name))
+        return units
+
+    @staticmethod
+    def _field(node: Any, name: str) -> Any | None:
+        method = getattr(node, "child_by_field_name", None)
+        return method(name) if callable(method) else None
+
+    @staticmethod
+    def _text(node: Any, source: bytes) -> str:
+        return source[int(node.start_byte) : int(node.end_byte)].decode("utf-8", errors="replace")
+
+    def _first_identifier(self, node: Any) -> Any | None:
+        stack = list(getattr(node, "children", ()))
+        while stack:
+            child = stack.pop(0)
+            if str(getattr(child, "type", "")) in {
+                "identifier",
+                "type_identifier",
+                "constant",
+                "name",
+            }:
+                return child
+            stack[0:0] = list(getattr(child, "children", ()))
+        return None
+
+    def _signature(self, node: Any, source: bytes) -> str | None:
+        body = self._field(node, "body")
+        end = int(body.start_byte) if body is not None else int(node.end_byte)
+        text = source[int(node.start_byte) : end].decode("utf-8", errors="replace").strip()
+        text = " ".join(text.split())
+        return text[:800] or None
+
+    def _bases(self, node: Any, source: bytes) -> tuple[str, ...]:
+        values: list[str] = []
+        for field in ("superclass", "interfaces", "base", "type_parameters"):
+            child = self._field(node, field)
+            if child is not None:
+                value = self._text(child, source).strip()
+                if value:
+                    values.append(value)
+        return tuple(dict.fromkeys(values))
+
+    def _references(self, node: Any, source: bytes, own_name: str) -> tuple[str, ...]:
+        values: list[str] = []
+        stack = list(getattr(node, "children", ()))
+        while stack and len(values) < 128:
+            child = stack.pop()
+            child_type = str(getattr(child, "type", ""))
+            if child_type in {"identifier", "type_identifier", "constant"}:
+                value = self._text(child, source).strip()
+                if value and value != own_name and value not in values:
+                    values.append(value)
+            stack.extend(getattr(child, "children", ()))
+        return tuple(values)