agent-codinglanguage-mapper 1.0.0__py3-none-any.whl

agent_codinglanguage_mapper/mapper.py

@@ -0,0 +1,596 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from dataclasses import replace
+from pathlib import Path
+from typing import cast
+
+from .indexer import WorkspaceIndexCache, build_workspace_snapshot
+from .models import Language, Problem, Project, Reference, Relation, Resolution, SourceRange, Symbol
+from .protocol import AgentRequest, AgentResponse, Context, Focus, Page, ProtocolError
+from .workspace import WorkspaceSnapshot, stable_id
+
+
+_SOURCE_CHUNK_CHARS = 6000
+
+
+def _symbol_mapping(symbol: Symbol) -> dict[str, object]:
+    return {
+        "target_id": symbol.target_id,
+        "name": symbol.name,
+        "qualified_name": symbol.qualified_name,
+        "kind": symbol.kind,
+        "language": symbol.language.value,
+        "project_id": symbol.project_id,
+        "file_id": symbol.file_id,
+        "citation": _citation(symbol.name_range or symbol.range),
+        "signature": symbol.signature,
+        "native_kind": symbol.native_kind,
+        "role": symbol.role,
+        "parent_id": symbol.parent_id,
+        "name_range": (
+            {
+                "path": symbol.name_range.path,
+                "start_line": symbol.name_range.start_line,
+                "start_character": symbol.name_range.start_character,
+                "end_line": symbol.name_range.end_line,
+                "end_character": symbol.name_range.end_character,
+            }
+            if symbol.name_range is not None
+            else None
+        ),
+        "range": {
+            "path": symbol.range.path,
+            "start_line": symbol.range.start_line,
+            "start_character": symbol.range.start_character,
+            "end_line": symbol.range.end_line,
+            "end_character": symbol.range.end_character,
+        },
+    }
+
+
+def _range_mapping(source_range: SourceRange) -> dict[str, object]:
+    return {
+        "path": source_range.path,
+        "start_line": source_range.start_line,
+        "start_character": source_range.start_character,
+        "end_line": source_range.end_line,
+        "end_character": source_range.end_character,
+    }
+
+
+def _citation(source_range: SourceRange) -> str:
+    return f"{source_range.path}:{source_range.start_line + 1}"
+
+
+def _reference_mapping(reference: Reference) -> dict[str, object]:
+    return {
+        "source_id": reference.source_id,
+        "target_id": reference.target_id,
+        "name": reference.name,
+        "language": reference.language.value,
+        "resolution": reference.resolution.value,
+        "reference_kind": reference.reference_kind,
+        "qualifier": reference.qualifier,
+        "import_path": reference.import_path,
+        "imported_symbols": [list(item) for item in reference.imported_symbols],
+        "module_alias": reference.module_alias,
+        "wildcard_import": reference.wildcard_import,
+        "project_wide": reference.project_wide,
+        "range": _range_mapping(reference.range),
+        "citation": _citation(reference.range),
+    }
+
+
+def _relation_mapping(
+    relation: Relation,
+    source_symbol: Symbol | None,
+    target_symbol: Symbol | None,
+) -> dict[str, object]:
+    return {
+        "source_id": relation.source_id,
+        "target_id": relation.target_id,
+        "target_name": relation.target_name,
+        "target_library": relation.target_library,
+        "kind": relation.kind,
+        "language": source_symbol.language.value if source_symbol is not None else "",
+        "resolution": relation.resolution.value,
+        "evidence": [_range_mapping(item) for item in relation.evidence],
+        "citations": [_citation(item) for item in relation.evidence],
+        "source_symbol": _symbol_mapping(source_symbol) if source_symbol is not None else None,
+        "target_symbol": _symbol_mapping(target_symbol) if target_symbol is not None else None,
+    }
+
+
+def _problem_mapping(problem: Problem) -> dict[str, object]:
+    return {
+        "code": problem.code,
+        "message": problem.message,
+        "severity": problem.severity,
+        "language": problem.language.value if problem.language is not None else "",
+        "range": _range_mapping(problem.range) if problem.range is not None else None,
+        "citation": _citation(problem.range) if problem.range is not None else "",
+        "metadata": problem.metadata,
+    }
+
+
+class CodebaseMapper:
+    def __init__(
+        self,
+        root: str | Path,
+        snapshot: WorkspaceSnapshot | None = None,
+        *,
+        languages: tuple[Language, ...] | None = None,
+        lazy_details: bool = False,
+        index_cache: WorkspaceIndexCache | None = None,
+    ) -> None:
+        self.root = Path(root).expanduser().resolve()
+        self.snapshot = snapshot or self._synthetic_snapshot()
+        self._languages = languages
+        self._lazy_details = lazy_details
+        self._index_cache = index_cache
+        self._detailed_files: set[str] = set()
+        self._focus = Focus()
+        self._closed = False
+
+    def _synthetic_snapshot(self) -> WorkspaceSnapshot:
+        project_id = stable_id("project", str(self.root))
+        return WorkspaceSnapshot(projects=(Project(project_id, self.root.name or str(self.root), str(self.root)),))
+
+    @classmethod
+    def open(cls, root: str | Path, languages: str | tuple[Language, ...] = "auto") -> "CodebaseMapper":
+        selected = None if languages == "auto" else tuple(Language(item) if isinstance(item, str) else item for item in languages)
+        index_cache = WorkspaceIndexCache()
+        return cls(
+            root,
+            build_workspace_snapshot(root, selected, detail_files=(), index_cache=index_cache),
+            languages=selected,
+            lazy_details=True,
+            index_cache=index_cache,
+        )
+
+    def __enter__(self) -> "CodebaseMapper":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._closed = True
+
+    def dispatch(self, request: AgentRequest) -> AgentResponse:
+        if self._closed:
+            raise RuntimeError("mapper is closed")
+        self._refresh_changed_sources()
+        request = self._request_with_focus(request)
+        if request.action == "open":
+            items: list[dict[str, object]] = [
+                {
+                    "project_id": project.project_id,
+                    "name": project.name,
+                    "root": project.root,
+                    "languages": [language.value for language in project.languages],
+                    "kind": project.kind,
+                }
+                for project in self.snapshot.projects
+            ]
+            return self._page_response(request, items)
+        if request.action == "find":
+            query = request.query.casefold()
+            requested_source = self.snapshot.files_by_id.get(request.file_id)
+            symbols = [symbol for symbol in self.snapshot.symbols
+                       if (query in symbol.name.casefold() or query in symbol.qualified_name.casefold())
+                       and (not request.project_id or symbol.project_id == request.project_id)
+                       and (
+                           not request.file_id
+                           or symbol.file_id == request.file_id
+                           or requested_source is not None
+                           and Path(symbol.range.path).as_posix() == requested_source.path
+                       )
+                       and (not request.languages or symbol.language in request.languages)]
+            return self._page_response(request, [_symbol_mapping(symbol) for symbol in symbols])
+        if request.action in {"inspect", "focus"}:
+            self._ensure_details(request)
+            symbol = self.snapshot.symbols_by_id.get(request.target_id)
+            if symbol is None:
+                return AgentResponse(self.snapshot.revision, {"items": []}, focus=self._focus)
+            if request.action == "focus":
+                self._focus = Focus(
+                    project_id=request.project_id or symbol.project_id,
+                    file_id=request.file_id or symbol.file_id,
+                    target_id=symbol.target_id,
+                    languages=request.languages or (symbol.language,),
+                )
+            response_focus = self._focus
+            if not response_focus.target_id:
+                response_focus = Focus(
+                    project_id=symbol.project_id,
+                    file_id=symbol.file_id,
+                    target_id=symbol.target_id,
+                    languages=(symbol.language,),
+                )
+            return self._inspect_response(request, symbol, response_focus)
+        if request.action == "problems":
+            items = [_problem_mapping(problem) for problem in self.snapshot.problems]
+            return self._page_response(request, items)
+        self._ensure_details(request)
+        return self._trace_response(request)
+
+    request = dispatch
+    handle = dispatch
+
+    def _request_with_focus(self, request: AgentRequest) -> AgentRequest:
+        if not self._focus.target_id:
+            return request
+        target_id = request.target_id
+        project_id = request.project_id
+        file_id = request.file_id
+        languages = request.languages
+        if request.action in {"inspect", "trace", "focus"} and not target_id:
+            target_id = self._focus.target_id
+        if request.action == "find":
+            if request.project_id or request.file_id or request.languages:
+                project_id = request.project_id
+                file_id = request.file_id
+                languages = request.languages
+            else:
+                project_id = self._focus.project_id
+                file_id = file_id or self._focus.file_id
+                languages = self._focus.languages
+        if (
+            target_id == request.target_id
+            and project_id == request.project_id
+            and file_id == request.file_id
+            and languages == request.languages
+        ):
+            return request
+        return replace(
+            request,
+            target_id=target_id,
+            project_id=project_id,
+            file_id=file_id,
+            languages=languages,
+        )
+
+    def _refresh_changed_sources(self) -> None:
+        if (
+            not self._lazy_details
+            or self._index_cache is None
+            or not self._index_cache.sources_changed(self.root)
+        ):
+            return
+        self.snapshot = build_workspace_snapshot(
+            self.root,
+            self._languages,
+            detail_files=(),
+            index_cache=self._index_cache,
+        )
+        self._detailed_files.clear()
+        self._focus = Focus()
+
+    def _ensure_details(self, request: AgentRequest) -> None:
+        if not self._lazy_details or not request.target_id:
+            return
+        target = self.snapshot.symbols_by_id.get(request.target_id)
+        if target is None:
+            return
+        if request.action in {"inspect", "focus"} or request.relation in {"callees", "uses"}:
+            source_file = self.snapshot.files_by_id.get(target.file_id)
+            required = {source_file.path} if source_file is not None else set()
+        else:
+            required = {item.path for item in self.snapshot.files}
+        missing = required - self._detailed_files
+        if not missing:
+            return
+        self.snapshot = build_workspace_snapshot(
+            self.root,
+            self._languages,
+            detail_files=missing,
+            base_snapshot=self.snapshot,
+            index_cache=self._index_cache,
+        )
+        self._detailed_files.update(missing)
+
+    def _inspect_response(
+        self,
+        request: AgentRequest,
+        symbol: Symbol,
+        focus: Focus,
+    ) -> AgentResponse:
+        if request.detail == "members":
+            members = [item for item in self.snapshot.symbols if item.parent_id == symbol.target_id]
+            return self._page_response(request, [_symbol_mapping(item) for item in members], focus)
+        if request.detail == "implementations":
+            implementations = self._implementation_symbols(symbol)
+            return self._page_response(request, [_symbol_mapping(item) for item in implementations], focus)
+
+        item = _symbol_mapping(symbol)
+        text_key = ""
+        full_text = ""
+        text_offset = 0
+        if request.detail == "declaration":
+            text_key = "declaration"
+            full_text = symbol.signature
+            item["citation"] = _citation(symbol.name_range or symbol.range)
+        elif request.detail in {"body", "context"}:
+            source_range = symbol.range
+            context_lines = 8 if request.detail == "context" else 0
+            full_text, source_path, first_line = self._source_excerpt(source_range, context_lines=context_lines)
+            text_key = "source"
+            item["citation"] = f"{source_path}:{first_line}"
+        if text_key:
+            text_offset = self._decode_cursor(request)
+            if text_offset > len(full_text) or (request.cursor and text_offset == len(full_text)):
+                raise ProtocolError("cursor offset is invalid")
+            item[text_key] = full_text[text_offset:text_offset + _SOURCE_CHUNK_CHARS]
+            if text_key == "source":
+                line_offset = full_text[:text_offset].count("\n")
+                item["citation"] = f"{symbol.range.path}:{int(str(item['citation']).rsplit(':', 1)[1]) + line_offset}"
+            item["truncated"] = text_offset + len(cast(str, item[text_key])) < len(full_text)
+        item = self._bounded_detail_item(item, request.detail, request.max_chars)
+        item_chars = len(json.dumps(item, sort_keys=True, separators=(",", ":")))
+        page = Page()
+        if text_key:
+            returned_text = cast(str, item.get(text_key, ""))
+            if not returned_text and text_offset < len(full_text):
+                raise ProtocolError("max_chars is too small to return source evidence")
+            end = text_offset + len(returned_text)
+            source_truncated = end < len(full_text)
+            item["truncated"] = bool(item.get("truncated")) or source_truncated
+            page = Page(
+                returned=1,
+                total=1,
+                truncated=source_truncated,
+                next_cursor=self._encode_cursor(request, end) if source_truncated else "",
+            )
+        return AgentResponse(
+            self.snapshot.revision,
+            {"item": item},
+            focus,
+            page=page,
+            context=Context(chars=item_chars),
+        )
+
+    def _implementation_symbols(self, symbol: Symbol) -> list[Symbol]:
+        target_ids = {symbol.target_id}
+        if symbol.language is Language.DELPHI:
+            key = symbol.qualified_name.casefold()
+            signature_key = self._normalized_delphi_signature(symbol)
+            for candidate in self.snapshot.symbols:
+                roles = {candidate.role, symbol.role}
+                if (
+                    candidate.project_id == symbol.project_id
+                    and candidate.language is symbol.language
+                    and candidate.kind == symbol.kind
+                    and candidate.qualified_name.casefold() == key
+                    and self._normalized_delphi_signature(candidate) == signature_key
+                    and "implementation" in roles
+                    and bool(roles.intersection({"declaration", "definition"}))
+                ):
+                    target_ids.add(candidate.target_id)
+        for relation in self.snapshot.relations_by_target.get(symbol.target_id, ()):
+            if relation.kind == "implements" and relation.resolution is Resolution.COMPLETE and relation.source_id:
+                target_ids.add(relation.source_id)
+        return [item for item in self.snapshot.symbols if item.target_id in target_ids]
+
+    @staticmethod
+    def _normalized_delphi_signature(symbol: Symbol) -> str:
+        signature = " ".join(symbol.signature.casefold().split())
+        indexed_name = symbol.name.casefold()
+        simple_name = symbol.qualified_name.rsplit(".", 1)[-1].casefold()
+        signature = signature.replace(indexed_name, simple_name, 1)
+
+        depth = 0
+        for index, character in enumerate(signature):
+            if character == "(":
+                depth += 1
+            elif character == ")" and depth:
+                depth -= 1
+            elif character == ";" and depth == 0:
+                signature = signature[:index]
+                break
+        return "".join(signature.split())
+
+    @staticmethod
+    def _bounded_detail_item(
+        item: dict[str, object],
+        detail: str,
+        max_chars: int,
+    ) -> dict[str, object]:
+        def encoded_size(value: dict[str, object]) -> int:
+            return len(json.dumps(value, sort_keys=True, separators=(",", ":")))
+
+        if encoded_size(item) <= max_chars:
+            return item
+
+        bounded: dict[str, object] = {"target_id": item["target_id"], "truncated": True}
+        for key in ("citation", "name", "language"):
+            candidate = {**bounded, key: item[key]}
+            if encoded_size(candidate) <= max_chars:
+                bounded = candidate
+
+        detail_key = "source" if detail in {"body", "context"} else "declaration" if detail == "declaration" else ""
+        if detail_key:
+            text = cast(str, item[detail_key])
+            low = 0
+            high = len(text)
+            while low <= high:
+                middle = (low + high) // 2
+                candidate = {**bounded, detail_key: text[:middle]}
+                if encoded_size(candidate) <= max_chars:
+                    low = middle + 1
+                else:
+                    high = middle - 1
+            bounded[detail_key] = text[:max(0, high)]
+            return bounded
+
+        for key in ("kind", "role", "project_id", "file_id", "qualified_name", "signature"):
+            candidate = {**bounded, key: item[key]}
+            if encoded_size(candidate) <= max_chars:
+                bounded = candidate
+        return bounded
+
+    def _source_excerpt(self, source_range: SourceRange, *, context_lines: int) -> tuple[str, str, int]:
+        cached = self._index_cache.entries.get(source_range.path) if self._index_cache is not None else None
+        if cached is not None:
+            lines = cached.source.splitlines()
+        else:
+            path = Path(source_range.path)
+            source_path = path if path.is_absolute() else self.root / path
+            try:
+                lines = source_path.read_text(encoding="utf-8", errors="replace").splitlines()
+            except OSError:
+                return "", source_range.path, source_range.start_line + 1
+        start = max(0, source_range.start_line - context_lines)
+        end = min(len(lines), source_range.end_line + context_lines + 1)
+        text = "\n".join(lines[start:end])
+        return text, source_range.path, start + 1
+
+    def _trace_response(self, request: AgentRequest) -> AgentResponse:
+        relation = request.relation
+        references = self.snapshot.references
+        aliases = self.snapshot.symbol_aliases_by_id.get(request.target_id, ())
+        request_target_ids = tuple(dict.fromkeys(item.target_id for item in aliases))
+        if not request_target_ids:
+            request_target_ids = (request.target_id,)
+        request_target_id_set = set(request_target_ids)
+        if relation == "references":
+            selected = [item for item in references if item.target_id in request_target_id_set]
+            return self._page_response(request, [_reference_mapping(item) for item in selected])
+        if relation in {"callers", "used_by"}:
+            target_ids = {
+                item.source_id for item in references if item.target_id in request_target_id_set
+            }
+            target_ids.update(
+                item.source_id
+                for item in self.snapshot.relations
+                if relation == "used_by" and item.target_id in request_target_id_set
+            )
+            caller_symbols = [
+                self.snapshot.symbols_by_id[item] for item in target_ids if item in self.snapshot.symbols_by_id
+            ]
+            return self._page_response(request, [_symbol_mapping(item) for item in caller_symbols])
+        if relation in {"callees", "uses"}:
+            target_ids = {
+                item.target_id
+                for item in references
+                if item.source_id in request_target_id_set and item.target_id
+            }
+            target_ids.update(
+                item.target_id
+                for item in self.snapshot.relations
+                if relation == "uses"
+                and item.source_id in request_target_id_set
+                and item.target_id
+            )
+            callee_symbols = [
+                self.snapshot.symbols_by_id[item] for item in target_ids if item in self.snapshot.symbols_by_id
+            ]
+            return self._page_response(request, [_symbol_mapping(item) for item in callee_symbols])
+
+        relations = tuple(
+            dict.fromkeys(
+                item
+                for target_id in request_target_ids
+                for item in (
+                    self.snapshot.relations_by_source.get(target_id, ())
+                    + self.snapshot.relations_by_target.get(target_id, ())
+                )
+            )
+        )
+        if relation:
+            relations = tuple(item for item in relations if item.kind == relation)
+        relation_items: list[dict[str, object]] = []
+        for item in relations:
+            source_symbol = self.snapshot.symbols_by_id.get(item.source_id)
+            target_symbol = self.snapshot.symbols_by_id.get(item.target_id)
+            relation_items.append(_relation_mapping(item, source_symbol, target_symbol))
+        return self._page_response(request, relation_items)
+
+    def _page_response(
+        self,
+        request: AgentRequest,
+        items: list[dict[str, object]],
+        focus: Focus | None = None,
+    ) -> AgentResponse:
+        start = self._decode_cursor(request)
+        selected: list[dict[str, object]] = []
+        used = 0
+        for item in items[start:start + request.max_items]:
+            size = len(json.dumps(item, sort_keys=True, separators=(",", ":")))
+            if used + size > request.max_chars:
+                if not selected:
+                    bounded = self._bounded_page_item(item, request.max_chars)
+                    selected.append(bounded)
+                    used = len(json.dumps(bounded, sort_keys=True, separators=(",", ":")))
+                break
+            selected.append(item)
+            used += size
+        end = start + len(selected)
+        cursor = self._encode_cursor(request, end) if end < len(items) and selected else ""
+        return AgentResponse(
+            self.snapshot.revision,
+            {"items": selected},
+            focus=self._focus if focus is None else focus,
+            page=Page(
+                returned=len(selected),
+                total=len(items),
+                truncated=end < len(items),
+                next_cursor=cursor,
+            ),
+            context=Context(chars=used),
+        )
+
+    @staticmethod
+    def _bounded_page_item(item: dict[str, object], max_chars: int) -> dict[str, object]:
+        bounded: dict[str, object] = {"truncated": True}
+        identifying_fields = (
+            "target_id",
+            "name",
+            "language",
+            "citation",
+            "kind",
+            "role",
+            "project_id",
+            "file_id",
+            "source_id",
+            "qualified_name",
+            "code",
+            "resolution",
+            "target_name",
+        )
+        for key in identifying_fields:
+            if key not in item:
+                continue
+            candidate = {**bounded, key: item[key]}
+            if len(json.dumps(candidate, sort_keys=True, separators=(",", ":"))) <= max_chars:
+                bounded = candidate
+        return bounded
+
+    def _fingerprint(self, request: AgentRequest) -> str:
+        data = request.to_mapping()
+        data.pop("cursor")
+        return json.dumps(data, sort_keys=True, separators=(",", ":"))
+
+    def _encode_cursor(self, request: AgentRequest, offset: int) -> str:
+        payload = {"revision": self.snapshot.revision, "request": self._fingerprint(request), "offset": offset}
+        raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        return base64.urlsafe_b64encode(raw).decode("ascii")
+
+    def _decode_cursor(self, request: AgentRequest) -> int:
+        if not request.cursor:
+            return 0
+        try:
+            data = json.loads(base64.urlsafe_b64decode(request.cursor.encode("ascii")).decode("utf-8"))
+            if data["revision"] != self.snapshot.revision or data["request"] != self._fingerprint(request):
+                raise ProtocolError("cursor does not match this workspace or request")
+            offset = data["offset"]
+            if isinstance(offset, bool) or not isinstance(offset, int) or offset < 0:
+                raise ProtocolError("cursor offset is invalid")
+            return cast(int, offset)
+        except ProtocolError:
+            raise
+        except (binascii.Error, KeyError, TypeError, UnicodeDecodeError, ValueError, json.JSONDecodeError) as exc:
+            raise ProtocolError("cursor is invalid") from exc

agent_codinglanguage_mapper/models.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Language(str, Enum):
+    PYTHON = "python"
+    RUST = "rust"
+    CSHARP = "csharp"
+    DELPHI = "delphi"
+    CPP = "cpp"
+
+
+class Resolution(str, Enum):
+    COMPLETE = "complete"
+    SOUND_PARTIAL = "sound_partial"
+    AMBIGUOUS = "ambiguous"
+    UNRESOLVED = "unresolved"
+
+
+@dataclass(frozen=True)
+class SourceRange:
+    path: str
+    start_line: int
+    start_character: int
+    end_line: int
+    end_character: int
+
+
+@dataclass(frozen=True)
+class Project:
+    project_id: str
+    name: str
+    root: str
+    languages: tuple[Language, ...] = ()
+    kind: str = "synthetic"
+    include_paths: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class SourceFile:
+    file_id: str
+    path: str
+    language: Language
+    project_id: str
+
+
+@dataclass(frozen=True)
+class Symbol:
+    target_id: str
+    name: str
+    qualified_name: str
+    kind: str
+    language: Language
+    range: SourceRange
+    project_id: str
+    file_id: str
+    signature: str = ""
+    native_kind: str = ""
+    parent_id: str = ""
+    name_range: SourceRange | None = None
+    role: str = "definition"
+
+
+@dataclass(frozen=True)
+class Reference:
+    source_id: str
+    target_id: str
+    name: str
+    language: Language
+    range: SourceRange
+    resolution: Resolution = Resolution.COMPLETE
+    reference_kind: str = "reference"
+    qualifier: str = ""
+    import_path: str = ""
+    imported_symbols: tuple[tuple[str, str], ...] = ()
+    module_alias: str = ""
+    wildcard_import: bool = False
+    project_wide: bool = False
+
+
+@dataclass(frozen=True)
+class Relation:
+    source_id: str
+    target_id: str
+    kind: str
+    resolution: Resolution = Resolution.COMPLETE
+    evidence: tuple[SourceRange, ...] = ()
+    target_name: str = ""
+    target_library: str = ""
+
+
+@dataclass(frozen=True)
+class Problem:
+    code: str
+    message: str
+    severity: str = "warning"
+    language: Language | None = None
+    range: SourceRange | None = None
+    metadata: dict[str, object] = field(default_factory=dict)