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

agent_codinglanguage_mapper/integration.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Final
+
+AGENT_NAME: Final[str] = "mixed-codebase-navigator"
+WORKTREE_PERMISSIONS: Final[dict[str, str]] = {
+    "*": "deny",
+    "skill": "allow",
+    "codebase_map": "allow",
+}
+
+SKILL_RELATIVE_PATH: Final[Path] = Path(".agents/skills/mixed-codebase-navigator/SKILL.md")
+OPENCODE_PLUGIN_RELATIVE_PATH: Final[Path] = Path(".opencode/plugins/codebase_map.ts")
+OPENCODE_CONFIG_RELATIVE_PATH: Final[Path] = Path("opencode.json")
+
+SKILL_TEMPLATE_PATH: Final[Path] = Path("skill", "SKILL.md")
+OPENCODE_PLUGIN_TEMPLATE_PATH: Final[Path] = Path("opencode", "plugins", "codebase_map.ts")
+_TEMPLATES_ROOT: Final[Path] = Path(__file__).resolve().parent / "templates"
+
+
+def install_skill(target: Path, force: bool = False) -> Path:
+    return _install_file(_normalize_target(target), SKILL_RELATIVE_PATH, SKILL_TEMPLATE_PATH, force=force)
+
+
+def install_opencode(
+    target: Path,
+    python_executable: str | os.PathLike[str],
+    force: bool = False,
+    write_config: bool = False,
+) -> tuple[Path, Path] | tuple[Path, Path, Path]:
+    target_root = _normalize_target(target)
+    skill_path = _safe_join(target_root, SKILL_RELATIVE_PATH)
+    plugin_path = _safe_join(target_root, OPENCODE_PLUGIN_RELATIVE_PATH)
+    _preflight_overwrite((skill_path, plugin_path), force=force)
+    rendered_skill = _load_template(SKILL_TEMPLATE_PATH)
+    rendered_plugin = _render_plugin(str(python_executable))
+    config_path: Path | None = None
+    config: dict[str, Any] | None = None
+    changed = False
+    if write_config:
+        config_path = _safe_join(target_root, OPENCODE_CONFIG_RELATIVE_PATH)
+        config = _load_json_object(config_path)
+        changed = _merge_opencode_agent_config(config, force=force)
+
+    _write_atomic_text(skill_path, rendered_skill, force=True)
+    _write_atomic_text(plugin_path, rendered_plugin, force=True)
+    if config_path is not None and config is not None and changed:
+        _write_atomic_json(config_path, config)
+    if not write_config:
+        return skill_path, plugin_path
+    assert config_path is not None
+    return skill_path, plugin_path, config_path
+
+
+def _normalize_target(target: Path) -> Path:
+    normalized = target.expanduser().resolve()
+    if normalized.exists() and not normalized.is_dir():
+        raise NotADirectoryError(f"Target must be a directory: {normalized}")
+    normalized.mkdir(parents=True, exist_ok=True)
+    return normalized
+
+
+def _install_file(
+    target: Path,
+    destination: Path,
+    template_path: Path | None = None,
+    rendered_template: str | None = None,
+    force: bool = False,
+) -> Path:
+    if template_path is None and rendered_template is None:
+        raise ValueError("Either template_path or rendered_template must be provided.")
+    if template_path is not None and rendered_template is not None:
+        raise ValueError("Provide only one source template.")
+
+    if template_path is not None:
+        rendered_template = _load_template(template_path)
+    assert rendered_template is not None
+
+    destination_path = _safe_join(target, destination)
+    _write_atomic_text(destination_path, rendered_template, force=force)
+    return destination_path
+
+
+def _safe_join(target: Path, relative: Path) -> Path:
+    destination = (target / relative).resolve()
+    target_resolved = target.resolve()
+    destination.relative_to(target_resolved)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    return destination
+
+
+def _preflight_overwrite(paths: tuple[Path, ...], *, force: bool) -> None:
+    if force:
+        return
+    existing = [path for path in paths if path.exists()]
+    if existing:
+        raise FileExistsError(f"Refusing to overwrite existing file: {existing[0]}")
+
+
+def _load_template(relative_path: Path) -> str:
+    template = _TEMPLATES_ROOT / relative_path
+    return template.read_text(encoding="utf-8")
+
+
+def _render_plugin(python_executable: str) -> str:
+    template = _load_template(OPENCODE_PLUGIN_TEMPLATE_PATH)
+    escaped_python_executable = json.dumps(str(python_executable))
+    return template.replace("{{PYTHON_EXECUTABLE}}", escaped_python_executable)
+
+
+def _write_atomic_text(path: Path, content: str, force: bool = False) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"Refusing to overwrite existing file: {path}")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile("w", encoding="utf-8", newline="\n", dir=path.parent, delete=False) as handle:
+        handle.write(content)
+        tmp_path = Path(handle.name)
+    os.chmod(tmp_path, 0o644)
+    os.replace(tmp_path, path)
+
+
+def _load_json_object(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as handle:
+        data: Any = json.load(handle)
+    if not isinstance(data, dict):
+        raise ValueError(f"Invalid opencode config object in {path}")
+    return data
+
+
+def _merge_opencode_agent_config(config: dict[str, Any], *, force: bool) -> bool:
+    changed = False
+    if "$schema" not in config:
+        config["$schema"] = "https://opencode.ai/config.json"
+        changed = True
+    agents = config.get("agent")
+    if agents is None:
+        config["agent"] = {}
+        agents = config["agent"]
+    if not isinstance(agents, dict):
+        raise ValueError("Expected 'agent' to be an object.")
+
+    agent_config = agents.get(AGENT_NAME)
+    if agent_config is None:
+        agents[AGENT_NAME] = {
+            "description": "Navigate mixed-language codebases through the bounded semantic mapper.",
+            "permission": WORKTREE_PERMISSIONS.copy(),
+        }
+        return True
+    if not isinstance(agent_config, dict):
+        raise ValueError(f"Invalid agent block for {AGENT_NAME}")
+
+    permissions = agent_config.get("permission")
+    if permissions is None:
+        agent_config["permission"] = WORKTREE_PERMISSIONS.copy()
+        return True
+    if not isinstance(permissions, dict):
+        raise ValueError("permission must be an object")
+
+    for key, required_value in WORKTREE_PERMISSIONS.items():
+        current_value = permissions.get(key)
+        if current_value is not None and current_value != required_value:
+            if not force:
+                raise FileExistsError(
+                    "Permission conflict in .opencode/opencode.json: "
+                    f"key={key} expected={required_value!r} got={current_value!r}"
+                )
+            changed = True
+
+    normalized_permissions = WORKTREE_PERMISSIONS.copy()
+    if permissions != normalized_permissions:
+        permissions.clear()
+        permissions.update(normalized_permissions)
+        changed = True
+    return changed
+
+
+def _write_atomic_json(path: Path, payload: dict[str, Any]) -> None:
+    serialized = json.dumps(payload, sort_keys=True, indent=2) + "\n"
+    _write_atomic_text(path, serialized, force=True)

agent_codinglanguage_mapper/lsp_server.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+import re
+from urllib.parse import quote, unquote, urlparse
+
+from ._version import __version__
+from .lsp_service import LanguageService, SafeRenameError
+from .models import Problem, SourceRange
+
+if TYPE_CHECKING:
+    from pygls.server import LanguageServer
+    from lsprotocol.types import (
+        CompletionItem,
+        CompletionItemKind,
+        CompletionList,
+        CompletionParams,
+        DefinitionParams,
+        Diagnostic,
+        DocumentSymbol,
+        DocumentSymbolParams,
+        Hover,
+        HoverParams,
+        InitializeParams,
+        InitializeResult,
+        Location,
+        Range,
+        ReferenceParams,
+        RenameParams,
+        SymbolInformation,
+        SymbolKind,
+        WorkspaceSymbolParams,
+    )
+
+
+@dataclass
+class _ServerState:
+    service: LanguageService | None = None
+
+
+def _feature(constants: object, name: str, fallback: str) -> str:
+    return str(getattr(constants, name, fallback))
+
+
+def _uri_to_path(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme == "file":
+        path = unquote(parsed.path)
+        if re.match(r"^/[A-Za-z]:/", path):
+            return path[1:]
+        return path
+
+    if parsed.scheme:
+        return unquote(value)
+
+    return unquote(value)
+
+
+def _to_file_uri(path: str | Path) -> str:
+    text = str(path)
+    if re.match(r"^[A-Za-z]:[\\/]", text):
+        drive = text[0].upper()
+        rest = quote(text[2:].replace("\\", "/"), safe="/")
+        return f"file:///{drive}:{rest}"
+
+    parsed = urlparse(text)
+    if parsed.scheme:
+        return text
+
+    candidate = Path(text).expanduser()
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+    return candidate.resolve().as_uri()
+
+
+def _source_range_to_lsp_range(source_range: SourceRange) -> "Range":
+    from lsprotocol.types import Position, Range
+
+    return Range(
+        start=Position(line=source_range.start_line, character=source_range.start_character),
+        end=Position(line=source_range.end_line, character=source_range.end_character),
+    )
+
+
+def _problem_to_diagnostic(problem: Problem) -> "Diagnostic":
+    from lsprotocol.types import Diagnostic, DiagnosticSeverity
+
+    source_range = problem.range or SourceRange("", 0, 0, 0, 1)
+
+    severity_map = {
+        "error": DiagnosticSeverity.Error,
+        "warning": DiagnosticSeverity.Warning,
+        "hint": DiagnosticSeverity.Hint,
+        "info": DiagnosticSeverity.Information,
+        "information": DiagnosticSeverity.Information,
+    }
+    severity = severity_map.get(problem.severity.casefold(), DiagnosticSeverity.Warning)
+
+    return Diagnostic(
+        range=_source_range_to_lsp_range(source_range),
+        message=problem.message,
+        severity=severity,
+        code=problem.code,
+    )
+
+
+def _symbol_kind(kind: str) -> "SymbolKind":
+    from lsprotocol.types import SymbolKind
+
+    mapping = {
+        "module": SymbolKind.Module,
+        "class": SymbolKind.Class,
+        "interface": SymbolKind.Interface,
+        "enum": SymbolKind.Enum,
+        "enum_value": SymbolKind.EnumMember,
+        "record": SymbolKind.Struct,
+        "method": SymbolKind.Method,
+        "function": SymbolKind.Function,
+        "procedure": SymbolKind.Function,
+        "constructor": SymbolKind.Constructor,
+        "destructor": SymbolKind.Method,
+        "variable": SymbolKind.Variable,
+        "parameter": SymbolKind.Variable,
+        "property": SymbolKind.Property,
+        "field": SymbolKind.Field,
+        "constant": SymbolKind.Constant,
+    }
+    return mapping.get(kind.lower(), SymbolKind.String)
+
+
+def _completion_kind(kind: str) -> "CompletionItemKind":
+    from lsprotocol.types import CompletionItemKind
+
+    mapping = {
+        "class": CompletionItemKind.Class,
+        "interface": CompletionItemKind.Interface,
+        "enum": CompletionItemKind.Enum,
+        "enum_value": CompletionItemKind.EnumMember,
+        "record": CompletionItemKind.Struct,
+        "method": CompletionItemKind.Method,
+        "function": CompletionItemKind.Function,
+        "procedure": CompletionItemKind.Function,
+        "constructor": CompletionItemKind.Constructor,
+        "destructor": CompletionItemKind.Method,
+        "variable": CompletionItemKind.Variable,
+        "parameter": CompletionItemKind.Variable,
+        "property": CompletionItemKind.Property,
+        "field": CompletionItemKind.Field,
+        "constant": CompletionItemKind.Constant,
+    }
+    return mapping.get(kind.lower(), CompletionItemKind.Text)
+
+
+def _state(server: "LanguageServer") -> _ServerState:
+    if not hasattr(server, "_acm_lsp_state"):
+        setattr(server, "_acm_lsp_state", _ServerState())
+    return cast(_ServerState, getattr(server, "_acm_lsp_state"))
+
+
+def _resolve_workspace_root(params: object) -> Path:
+    workspace_folders = getattr(params, "workspace_folders", None)
+    if workspace_folders:
+        first = workspace_folders[0]
+        candidate = getattr(first, "uri", None)
+        if isinstance(candidate, str) and candidate:
+            return Path(_uri_to_path(candidate)).expanduser().resolve()
+
+    root_uri = getattr(params, "root_uri", None)
+    if isinstance(root_uri, str) and root_uri:
+        return Path(_uri_to_path(root_uri)).expanduser().resolve()
+
+    root_path = getattr(params, "root_path", None)
+    if isinstance(root_path, str) and root_path:
+        return Path(root_path).expanduser().resolve()
+
+    return Path.cwd()
+
+
+def _workspace_service(server: "LanguageServer") -> LanguageService:
+    state = _state(server)
+    if state.service is None:
+        state.service = LanguageService(Path.cwd())
+    return state.service
+
+
+def _publish_diagnostics_for_uri(server: "LanguageServer", service: LanguageService, uri: str) -> None:
+    path = _uri_to_path(uri)
+    diagnostics = [_problem_to_diagnostic(problem) for problem in service.diagnostics(path)]
+    server.publish_diagnostics(uri, diagnostics)
+
+
+def create_server() -> "LanguageServer":
+    try:
+        from lsprotocol import types as lsp_types
+        from pygls.server import LanguageServer
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise RuntimeError("pygls and lsprotocol are required for the LSP server") from exc
+
+    server = LanguageServer("agent-codinglanguage-mapper", __version__)
+    state = _state(server)
+    # ensure deterministic test access to internal state
+    state.service = None
+
+    initialize = _feature(lsp_types, "INITIALIZE", "initialize")
+    did_open = _feature(lsp_types, "TEXT_DOCUMENT_DID_OPEN", "textDocument/didOpen")
+    did_change = _feature(lsp_types, "TEXT_DOCUMENT_DID_CHANGE", "textDocument/didChange")
+    did_close = _feature(lsp_types, "TEXT_DOCUMENT_DID_CLOSE", "textDocument/didClose")
+    definition = _feature(lsp_types, "TEXT_DOCUMENT_DEFINITION", "textDocument/definition")
+    hover = _feature(lsp_types, "TEXT_DOCUMENT_HOVER", "textDocument/hover")
+    references = _feature(lsp_types, "TEXT_DOCUMENT_REFERENCES", "textDocument/references")
+    rename = _feature(lsp_types, "TEXT_DOCUMENT_RENAME", "textDocument/rename")
+    document_symbol = _feature(lsp_types, "TEXT_DOCUMENT_DOCUMENT_SYMBOL", "textDocument/documentSymbol")
+    workspace_symbol = _feature(lsp_types, "WORKSPACE_SYMBOL", "workspace/symbol")
+    completion = _feature(lsp_types, "TEXT_DOCUMENT_COMPLETION", "textDocument/completion")
+
+    @server.feature(initialize)
+    def on_initialize(ls: "LanguageServer", params: "InitializeParams") -> "InitializeResult":
+        root = _resolve_workspace_root(params)
+        _state(ls).service = LanguageService(root)
+        return lsp_types.InitializeResult(
+            capabilities=lsp_types.ServerCapabilities(
+                text_document_sync=lsp_types.TextDocumentSyncOptions(
+                    open_close=True,
+                    change=lsp_types.TextDocumentSyncKind.Full,
+                ),
+                definition_provider=True,
+                hover_provider=True,
+                references_provider=True,
+                rename_provider=True,
+                document_symbol_provider=True,
+                workspace_symbol_provider=True,
+                completion_provider=lsp_types.CompletionOptions(),
+            )
+        )
+
+    @server.feature(did_open)
+    def on_did_open(ls: "LanguageServer", params: Any) -> None:
+        service = _workspace_service(ls)
+        uri = getattr(params.text_document, "uri")
+        text = getattr(params.text_document, "text")
+        service.update_document(_uri_to_path(uri), text)
+        _publish_diagnostics_for_uri(ls, service, uri)
+
+    @server.feature(did_change)
+    def on_did_change(ls: "LanguageServer", params: Any) -> None:
+        changes = getattr(params, "content_changes", ())
+        if not changes:
+            return
+        service = _workspace_service(ls)
+        text = changes[-1].text
+        uri = params.text_document.uri
+        service.update_document(_uri_to_path(uri), text)
+        _publish_diagnostics_for_uri(ls, service, uri)
+
+    @server.feature(did_close)
+    def on_did_close(ls: "LanguageServer", params: Any) -> None:
+        service = _workspace_service(ls)
+        uri = params.text_document.uri
+        service.close_document(_uri_to_path(uri))
+        ls.publish_diagnostics(uri, [])
+
+    @server.feature(definition)
+    def on_definition(ls: "LanguageServer", params: "DefinitionParams") -> "Location | None":
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+        symbol_range = service.definition(path, params.position.line, params.position.character)
+        if symbol_range is None:
+            return None
+
+        return lsp_types.Location(
+            uri=service.path_uri(symbol_range.path),
+            range=_source_range_to_lsp_range(symbol_range),
+        )
+
+    @server.feature(hover)
+    def on_hover(ls: "LanguageServer", params: "HoverParams") -> "Hover | None":
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+        contents = service.hover(path, params.position.line, params.position.character)
+        if contents is None:
+            return None
+
+        return lsp_types.Hover(
+            contents=lsp_types.MarkupContent(kind=lsp_types.MarkupKind.Markdown, value=contents)
+        )
+
+    @server.feature(references)
+    def on_references(ls: "LanguageServer", params: "ReferenceParams") -> list["Location"]:
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+
+        context = getattr(params, "context", None)
+        include_declaration = True
+        if context is not None and getattr(context, "include_declaration", None) is not None:
+            include_declaration = bool(context.include_declaration)
+
+        return [
+            lsp_types.Location(
+                uri=service.path_uri(item.path),
+                range=_source_range_to_lsp_range(item),
+            )
+            for item in service.references(path, params.position.line, params.position.character, include_declaration=include_declaration)
+        ]
+
+    @server.feature(rename)
+    def on_rename(ls: "LanguageServer", params: "RenameParams") -> Any:
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+        try:
+            edits = service.rename(path, params.position.line, params.position.character, params.new_name)
+        except SafeRenameError:
+            return None
+
+        if not edits:
+            return None
+
+        return lsp_types.WorkspaceEdit(
+            changes={
+                service.path_uri(file_name): [
+                    lsp_types.TextEdit(
+                        range=_source_range_to_lsp_range(edit.range),
+                        new_text=edit.new_text,
+                    )
+                    for edit in file_edits
+                ]
+                for file_name, file_edits in edits.items()
+            }
+        )
+
+    @server.feature(document_symbol)
+    def on_document_symbols(
+        ls: "LanguageServer",
+        params: "DocumentSymbolParams",
+    ) -> list["DocumentSymbol"]:
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+        symbols = service.document_symbols(path)
+
+        return [
+            lsp_types.DocumentSymbol(
+                name=item.name,
+                detail=item.signature or None,
+                kind=_symbol_kind(item.kind),
+                range=_source_range_to_lsp_range(item.range),
+                selection_range=_source_range_to_lsp_range(item.name_range or item.range),
+            )
+            for item in symbols
+        ]
+
+    @server.feature(workspace_symbol)
+    def on_workspace_symbols(
+        ls: "LanguageServer",
+        params: "WorkspaceSymbolParams",
+    ) -> list["SymbolInformation"]:
+        service = _workspace_service(ls)
+        symbols = service.workspace_symbols(getattr(params, "query", "") or "")
+        return [
+            lsp_types.SymbolInformation(
+                name=item.name,
+                kind=_symbol_kind(item.kind),
+                location=lsp_types.Location(
+                    uri=service.path_uri(item.range.path),
+                    range=_source_range_to_lsp_range(item.range),
+                ),
+                container_name=item.qualified_name.rpartition(".")[0] or None,
+            )
+            for item in symbols
+        ]
+
+    @server.feature(completion)
+    def on_completion(
+        ls: "LanguageServer",
+        params: "CompletionParams",
+    ) -> "CompletionList | list[CompletionItem]":
+        service = _workspace_service(ls)
+        path = _uri_to_path(params.text_document.uri)
+        matches = service.completions(path)
+        items = [
+            lsp_types.CompletionItem(
+                label=item.name,
+                kind=_completion_kind(item.kind),
+                detail=item.signature,
+                documentation=item.qualified_name,
+            )
+            for item in matches
+        ]
+        return lsp_types.CompletionList(is_incomplete=False, items=items)
+
+    # Expose handlers for focused non-stdio unit tests.
+    setattr(server, "_handle_initialize", on_initialize)
+    setattr(server, "_handle_did_open", on_did_open)
+    setattr(server, "_handle_did_change", on_did_change)
+    setattr(server, "_handle_did_close", on_did_close)
+    setattr(server, "_handle_definition", on_definition)
+    setattr(server, "_handle_hover", on_hover)
+    setattr(server, "_handle_references", on_references)
+    setattr(server, "_handle_rename", on_rename)
+    setattr(server, "_handle_document_symbols", on_document_symbols)
+    setattr(server, "_handle_workspace_symbols", on_workspace_symbols)
+    setattr(server, "_handle_completion", on_completion)
+    setattr(server, "_acm_state", state)
+    setattr(server, "_acm_lsp_state", state)
+
+    return server
+
+
+def main() -> None:
+    create_server().start_io()
+
+
+__all__ = ["create_server", "main", "_to_file_uri", "_uri_to_path", "_source_range_to_lsp_range"]