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

agent_codinglanguage_mapper/protocol.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .models import Language
+
+
+SCHEMA_VERSION = 3
+ACTIONS = frozenset({"open", "find", "inspect", "trace", "focus", "problems"})
+DETAILS = frozenset({"summary", "declaration", "members", "context", "body", "implementations"})
+RELATIONS = frozenset({"references", "callers", "callees", "uses", "used_by", "inherits", "implements", "ffi"})
+REQUEST_FIELDS = frozenset({"action", "query", "target_id", "project_id", "file_id", "languages", "detail", "relation", "cursor", "max_items", "max_chars"})
+
+
+class ProtocolError(ValueError):
+    """Raised when a request cannot be represented by protocol schema 3."""
+
+
+@dataclass(frozen=True)
+class AgentRequest:
+    action: str
+    query: str = ""
+    target_id: str = ""
+    project_id: str = ""
+    file_id: str = ""
+    languages: tuple[Language, ...] = ()
+    detail: str = "summary"
+    relation: str | None = None
+    cursor: str = ""
+    max_items: int = 12
+    max_chars: int = 12000
+
+    def __post_init__(self) -> None:
+        if self.action not in ACTIONS:
+            raise ProtocolError("action must be one of: " + ", ".join(sorted(ACTIONS)))
+        if self.detail not in DETAILS:
+            raise ProtocolError("detail must be one of: " + ", ".join(sorted(DETAILS)))
+        if self.relation is not None and self.relation not in RELATIONS:
+            raise ProtocolError("relation must be one of: " + ", ".join(sorted(RELATIONS)))
+        if isinstance(self.max_items, bool) or not isinstance(self.max_items, int):
+            raise ProtocolError("max_items must be an integer")
+        if isinstance(self.max_chars, bool) or not isinstance(self.max_chars, int):
+            raise ProtocolError("max_chars must be an integer")
+        if not 1 <= self.max_items <= 50:
+            raise ProtocolError("max_items must be between 1 and 50")
+        if not 256 <= self.max_chars <= 40000:
+            raise ProtocolError("max_chars must be between 256 and 40000")
+        if not isinstance(self.languages, tuple) or not all(isinstance(language, Language) for language in self.languages):
+            raise ProtocolError("languages must be a tuple of Language values")
+        for name in ("query", "target_id", "project_id", "file_id", "cursor"):
+            if not isinstance(getattr(self, name), str):
+                raise ProtocolError(f"{name} must be a string")
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "AgentRequest":
+        if not isinstance(value, Mapping):
+            raise ProtocolError("request must be an object")
+        unknown = set(value) - REQUEST_FIELDS
+        if unknown:
+            raise ProtocolError("unknown request fields: " + ", ".join(sorted(unknown)))
+        if not isinstance(value.get("action"), str):
+            raise ProtocolError("action is required and must be a string")
+        languages = value.get("languages", [])
+        if not isinstance(languages, list) or not all(isinstance(item, str) for item in languages):
+            raise ProtocolError("languages must be an array of strings")
+        for name in ("query", "target_id", "project_id", "file_id", "detail", "cursor"):
+            if name in value and not isinstance(value[name], str):
+                raise ProtocolError(f"{name} must be a string")
+        relation = value.get("relation")
+        if relation is not None and not isinstance(relation, str):
+            raise ProtocolError("relation must be a string or null")
+        for name in ("max_items", "max_chars"):
+            if name in value and (isinstance(value[name], bool) or not isinstance(value[name], int)):
+                raise ProtocolError(f"{name} must be an integer")
+        try:
+            parsed_languages = tuple(Language(item) for item in languages)
+        except ValueError as exc:
+            raise ProtocolError("languages contains an unsupported language") from exc
+        return cls(action=value["action"], query=value.get("query", ""), target_id=value.get("target_id", ""),
+                   project_id=value.get("project_id", ""), file_id=value.get("file_id", ""), languages=parsed_languages,
+                   detail=value.get("detail", "summary"), relation=relation, cursor=value.get("cursor", ""),
+                   max_items=value.get("max_items", 12), max_chars=value.get("max_chars", 12000))
+
+    def to_mapping(self) -> dict[str, object]:
+        return {"action": self.action, "query": self.query, "target_id": self.target_id, "project_id": self.project_id,
+                "file_id": self.file_id, "languages": [language.value for language in self.languages], "detail": self.detail,
+                "relation": self.relation, "cursor": self.cursor, "max_items": self.max_items, "max_chars": self.max_chars}
+
+
+@dataclass(frozen=True)
+class Page:
+    returned: int = 0
+    total: int = 0
+    truncated: bool = False
+    next_cursor: str = ""
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "returned": self.returned,
+            "total": self.total,
+            "truncated": self.truncated,
+            "next_cursor": self.next_cursor,
+        }
+
+
+@dataclass(frozen=True)
+class Focus:
+    project_id: str = ""
+    file_id: str = ""
+    target_id: str = ""
+    languages: tuple[Language, ...] = ()
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "project_id": self.project_id,
+            "file_id": self.file_id,
+            "target_id": self.target_id,
+            "languages": [language.value for language in self.languages],
+        }
+
+
+@dataclass(frozen=True)
+class Context:
+    chars: int = 0
+
+    @property
+    def approx_tokens(self) -> int:
+        return (self.chars + 3) // 4
+
+    def to_mapping(self) -> dict[str, int]:
+        return {"chars": self.chars, "approx_tokens": self.approx_tokens}
+
+
+@dataclass(frozen=True)
+class AgentResponse:
+    workspace_revision: str
+    result: dict[str, object]
+    focus: Focus = Focus()
+    page: Page = Page()
+    context: Context = Context()
+    schema: int = SCHEMA_VERSION
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "schema": self.schema,
+            "workspace_revision": self.workspace_revision,
+            "focus": self.focus.to_mapping(),
+            "result": self.result,
+            "page": self.page.to_mapping(),
+            "context": self.context.to_mapping(),
+        }

agent_codinglanguage_mapper/rendering.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+from .mapper import CodebaseMapper
+from .models import Language
+from .protocol import AgentRequest
+
+
+def layer_data(
+    mapper: CodebaseMapper,
+    layer: str,
+    *,
+    query: str = "",
+    languages: Iterable[Language] = (),
+) -> dict[str, object]:
+    snapshot = mapper.snapshot
+    selected_languages = tuple(languages)
+    if layer == "overview":
+        return {
+            "workspace": str(mapper.root),
+            "revision": snapshot.revision,
+            "counts": {
+                "projects": len(snapshot.projects),
+                "files": len(snapshot.files),
+                "symbols": len(snapshot.symbols),
+                "references": len(snapshot.references),
+                "relations": len(snapshot.relations),
+                "problems": len(snapshot.problems),
+            },
+            "languages": sorted({item.language.value for item in snapshot.files}),
+        }
+    if layer == "projects":
+        return {"items": [_jsonable(item) for item in snapshot.projects]}
+    if layer == "languages":
+        counts = {
+            language.value: sum(1 for item in snapshot.files if item.language is language)
+            for language in Language
+            if any(item.language is language for item in snapshot.files)
+        }
+        return {"items": [{"language": name, "files": count} for name, count in sorted(counts.items())]}
+    if layer == "files":
+        items = [
+            _jsonable(item)
+            for item in snapshot.files
+            if (not query or query.casefold() in item.path.casefold())
+            and (not selected_languages or item.language in selected_languages)
+        ]
+        return {"items": items}
+    if layer == "file":
+        source_file = next(
+            (
+                item
+                for item in snapshot.files
+                if item.file_id == query or item.path.casefold() == query.casefold()
+            ),
+            None,
+        )
+        if source_file is None:
+            return {"items": []}
+        return {
+            "item": _jsonable(source_file),
+            "symbols": [_jsonable(item) for item in snapshot.symbols_by_file.get(source_file.file_id, ())],
+        }
+    if layer == "symbols":
+        response = mapper.request(
+            AgentRequest(action="find", query=query, languages=selected_languages, max_items=50, max_chars=40000)
+        )
+        return response.result
+    if layer in {"symbol", "implementation", "references"}:
+        target_id = _target_id(mapper, query, selected_languages)
+        if not target_id:
+            return {"items": []}
+        if layer == "references":
+            return mapper.request(
+                AgentRequest(action="trace", target_id=target_id, relation="references", max_items=50, max_chars=40000)
+            ).result
+        detail = "body" if layer == "implementation" else "summary"
+        return mapper.request(AgentRequest(action="inspect", target_id=target_id, detail=detail)).result
+    if layer == "problems":
+        return mapper.request(AgentRequest(action="problems", max_items=50, max_chars=40000)).result
+    raise ValueError(f"unsupported layer: {layer}")
+
+
+def render_markdown(data: dict[str, object], *, title: str) -> str:
+    lines = [f"# {title}"]
+    if "items" in data and isinstance(data["items"], list):
+        for item in data["items"]:
+            if isinstance(item, dict):
+                name = item.get("qualified_name") or item.get("name") or item.get("path") or item.get("language")
+                lines.append(f"- **{name}**")
+                for key in ("kind", "language", "citation", "signature", "files", "resolution"):
+                    if item.get(key) not in (None, ""):
+                        lines.append(f"  - {key}: `{item[key]}`")
+            else:
+                lines.append(f"- {item}")
+    else:
+        lines.append("```json")
+        lines.append(json.dumps(data, indent=2, sort_keys=True))
+        lines.append("```")
+    return "\n".join(lines) + "\n"
+
+
+def snapshot_mapping(mapper: CodebaseMapper) -> dict[str, object]:
+    snapshot = mapper.snapshot
+    return {
+        "schema": 3,
+        "workspace": str(mapper.root),
+        "revision": snapshot.revision,
+        "projects": [_jsonable(item) for item in snapshot.projects],
+        "files": [_jsonable(item) for item in snapshot.files],
+        "symbols": [_jsonable(item) for item in snapshot.symbols],
+        "references": [_jsonable(item) for item in snapshot.references],
+        "relations": [_jsonable(item) for item in snapshot.relations],
+        "problems": [_jsonable(item) for item in snapshot.problems],
+    }
+
+
+def write_index(mapper: CodebaseMapper, output: str | Path) -> Path:
+    path = Path(output).expanduser()
+    if not path.is_absolute():
+        path = mapper.root / path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(snapshot_mapping(mapper), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def _target_id(mapper: CodebaseMapper, query: str, languages: tuple[Language, ...]) -> str:
+    if query in mapper.snapshot.symbols_by_id:
+        return query
+    response = mapper.request(
+        AgentRequest(action="find", query=query, languages=languages, max_items=1, max_chars=12000)
+    )
+    items = response.result.get("items", [])
+    return str(items[0]["target_id"]) if isinstance(items, list) and items else ""
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable(asdict(value))
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    return value

agent_codinglanguage_mapper/templates/opencode/plugins/codebase_map.ts

@@ -0,0 +1,191 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import { createInterface, type Interface } from "node:readline"
+
+const PYTHON_EXECUTABLE = {{PYTHON_EXECUTABLE}}
+const WORKER_TIMEOUT_MS = 30_000
+const WORKER_IDLE_TIMEOUT_MS = 60_000
+const MAX_STDERR_CHARS = 8_000
+
+type Unrefable = { unref?: () => void }
+
+function unref(handle: unknown): void {
+  ;(handle as Unrefable | undefined)?.unref?.()
+}
+
+type WorkerSession = {
+  process: ChildProcessWithoutNullStreams
+  lines: Interface
+  queue: Promise<unknown>
+  stderr: string
+  error?: Error
+}
+
+type WorkerState = {
+  worker?: WorkerSession
+  idleTimer?: ReturnType<typeof setTimeout>
+}
+
+function startWorker(root: string): WorkerSession {
+  const child = spawn(
+    PYTHON_EXECUTABLE,
+    ["-m", "agent_codinglanguage_mapper", "worker", "--root", root],
+    { stdio: ["pipe", "pipe", "pipe"], shell: false },
+  )
+  const session: WorkerSession = {
+    process: child,
+    lines: createInterface({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY }),
+    queue: Promise.resolve(),
+    stderr: "",
+  }
+  child.stderr.on("data", (chunk: Buffer | string) => {
+    session.stderr = `${session.stderr}${String(chunk)}`.slice(-MAX_STDERR_CHARS)
+  })
+  child.on("error", (error: Error) => {
+    session.error = error
+  })
+  child.unref()
+  unref(child.stdin)
+  unref(child.stdout)
+  unref(child.stderr)
+  return session
+}
+
+function sendRequest(session: WorkerSession, payload: Record<string, unknown>): Promise<string> {
+  return new Promise((resolve, reject) => {
+    if (session.error) {
+      reject(session.error)
+      return
+    }
+    let settled = false
+    let timeout: ReturnType<typeof setTimeout>
+    const failure = (message: string): Error => {
+      const details = session.stderr.trim()
+      return new Error(details ? `${message}\n${details}` : message)
+    }
+    const cleanup = (): void => {
+      clearTimeout(timeout)
+      session.process.removeListener("exit", onExit)
+      session.process.removeListener("error", onError)
+      session.lines.removeListener("line", onLine)
+    }
+    const fail = (error: Error): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      reject(error)
+    }
+    const onLine = (line: string): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(line)
+    }
+    const onExit = (): void => fail(failure("codebase mapper worker exited before responding"))
+    const onError = (error: Error): void => fail(failure(`codebase mapper worker failed to start: ${error.message}`))
+    timeout = setTimeout(() => {
+      session.process.kill()
+      fail(failure(`codebase mapper worker timed out after ${WORKER_TIMEOUT_MS}ms`))
+    }, WORKER_TIMEOUT_MS)
+    session.process.once("exit", onExit)
+    session.process.once("error", onError)
+    session.lines.once("line", onLine)
+    try {
+      session.process.stdin.write(`${JSON.stringify(payload)}\n`, (error?: Error | null) => {
+        if (error) fail(failure(`codebase mapper worker input failed: ${error.message}`))
+      })
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)))
+    }
+  })
+}
+
+export const CodebaseMapPlugin: Plugin = async ({ directory, worktree }) => {
+  const root = directory || worktree
+  const sessions = new Map<string, WorkerState>()
+
+  const stateFor = (sessionID: string): WorkerState => {
+    const existing = sessions.get(sessionID)
+    if (existing) return existing
+    const created: WorkerState = {}
+    sessions.set(sessionID, created)
+    return created
+  }
+
+  const cancelWorkerStop = (state: WorkerState): void => {
+    if (state.idleTimer === undefined) return
+    clearTimeout(state.idleTimer)
+    state.idleTimer = undefined
+  }
+
+  const stopWorker = (sessionID: string): void => {
+    const state = sessions.get(sessionID)
+    if (!state) return
+    cancelWorkerStop(state)
+    sessions.delete(sessionID)
+    const active = state.worker
+    state.worker = undefined
+    if (!active) return
+    active.lines.close()
+    if (active.process.stdin.writable) active.process.stdin.end()
+    if (active.process.exitCode === null && active.process.signalCode === null) active.process.kill()
+  }
+
+  const scheduleWorkerStop = (sessionID: string): void => {
+    const state = sessions.get(sessionID)
+    if (!state?.worker) return
+    cancelWorkerStop(state)
+    state.idleTimer = setTimeout(() => {
+      state.idleTimer = undefined
+      stopWorker(sessionID)
+    }, WORKER_IDLE_TIMEOUT_MS)
+    unref(state.idleTimer)
+  }
+
+  const runSerialized = (sessionID: string, payload: Record<string, unknown>): Promise<string> => {
+    const state = stateFor(sessionID)
+    cancelWorkerStop(state)
+    if (
+      !state.worker ||
+      state.worker.process.exitCode !== null ||
+      state.worker.process.signalCode !== null ||
+      !state.worker.process.stdin.writable
+    ) state.worker = startWorker(root)
+    const active = state.worker
+    const next = active.queue.then(() => sendRequest(active, payload)).catch((error: unknown) => {
+      if (state.worker === active) state.worker = undefined
+      if (active.process.exitCode === null && active.process.signalCode === null) active.process.kill()
+      throw error
+    })
+    active.queue = next.then(() => undefined, () => undefined)
+    return next
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.deleted") stopWorker(event.properties.info.id)
+      else if (event.type === "session.idle") scheduleWorkerStop(event.properties.sessionID)
+    },
+    tool: {
+      codebase_map: tool({
+        description: "Query the persistent Protocol 3 semantic map for this mixed-language workspace directory.",
+        args: {
+          action: tool.schema.enum(["open", "find", "inspect", "trace", "focus", "problems"]),
+          query: tool.schema.string().optional(),
+          target_id: tool.schema.string().optional(),
+          project_id: tool.schema.string().optional(),
+          file_id: tool.schema.string().optional(),
+          languages: tool.schema.array(tool.schema.enum(["python", "rust", "csharp", "delphi", "cpp"])).optional(),
+          detail: tool.schema.enum(["summary", "declaration", "members", "context", "body", "implementations"]).optional(),
+          relation: tool.schema.enum(["references", "callers", "callees", "uses", "used_by", "inherits", "implements", "ffi"]).optional(),
+          cursor: tool.schema.string().optional(),
+          max_items: tool.schema.number().int().min(1).max(50).optional(),
+          max_chars: tool.schema.number().int().min(256).max(40000).optional(),
+        },
+        async execute(args, context): Promise<string> {
+          return runSerialized(context.sessionID, args as Record<string, unknown>)
+        },
+      }),
+    },
+  }
+}

agent_codinglanguage_mapper/templates/skill/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mixed-codebase-navigator
+description: Inspect Python, Rust, C#, Delphi, C++, and mixed-language workspaces through a bounded semantic codebase map without raw filesystem search tools.
+license: MPL-2.0
+compatibility: opencode
+metadata:
+  protocol: "3"
+  package: agent-codinglanguage-mapper
+---
+
+# Mixed Codebase Navigator
+
+Use this skill whenever a task requires understanding source code, projects, symbols, calls, inheritance, implementations, references, FFI, or parser problems in the current workspace.
+
+## Tool Boundary
+
+- Use only `skill` and `codebase_map` while investigating source code.
+- Never call or request `read`, `grep`, `glob`, `list`, `bash`, `cat`, or an equivalent raw filesystem tool.
+- Do not infer a relation that is not present in tool output.
+- Treat `sound_partial`, `ambiguous`, and `unresolved` as explicit uncertainty.
+
+## Protocol 3 Workflow
+
+1. Call `codebase_map` with `action: open` to establish the workspace revision and projects.
+2. Use `action: find` with a narrow symbol or concept query. Filter with `languages`, `project_id`, or `file_id` when useful.
+3. Use `action: inspect` for the chosen `target_id`. Start with `detail: summary`, then request only the required `declaration`, `members`, `context`, `body`, or `implementations` detail.
+4. Use `action: trace` with exactly one relation: `references`, `callers`, `callees`, `uses`, `used_by`, `inherits`, `implements`, or `ffi`.
+5. Use `action: focus` to preserve the selected project, file, target, and languages while changing detail.
+6. Use `action: problems` before concluding that a missing result means the code does not exist.
+7. Follow `page.next_cursor` until the required evidence is found. Reuse the same request fields when advancing a cursor.
+
+## Layered Context
+
+Move from broad to narrow: `overview` -> `projects` -> `languages` -> `files` -> `file` -> `symbols` -> `symbol` -> `implementation` -> `references` -> `problems`.
+
+Keep only the current focus and directly relevant evidence in context. Prefer summaries and declarations before source bodies. Source chunks are bounded to 6,000 characters; request another focused target instead of asking for an entire file.
+
+## Relations
+
+Trace only the explicit Protocol 3 relations returned by `codebase_map`; never turn a name match into a call, inheritance, implementation, or FFI claim.
+
+For a resolved FFI trace, cite the returned `source_symbol.citation` and `target_symbol.citation` directly. These fields identify both language endpoints without a second name-based search.
+
+## Evidence Rules
+
+- Use a returned symbol's `role` to distinguish a declaration from an implementation; do not infer that distinction from name shape or raw ranges.
+- Preserve returned citations exactly; they are one-based even though protocol ranges are zero-based and half-open.
+- Never recalculate a citation from `range` or `name_range`; copy the returned `citation` field verbatim.
+- Cite every code claim with the returned one-based `path:line` citation.
+- State the language for mixed-workspace findings.
+- Distinguish declarations from implementations and explicit FFI from same-name coincidence.
+- Report ambiguity or unresolved project variables rather than guessing.

agent_codinglanguage_mapper/worker.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TextIO
+
+from .mapper import CodebaseMapper
+from .protocol import AgentRequest, ProtocolError, SCHEMA_VERSION
+
+
+def serve_worker(root: str | Path, input_stream: TextIO, output_stream: TextIO) -> int:
+    with CodebaseMapper.open(root) as mapper:
+        for raw_line in input_stream:
+            line = raw_line.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+                request = AgentRequest.from_mapping(payload)
+                response: dict[str, object] = mapper.request(request).to_mapping()
+            except (json.JSONDecodeError, ProtocolError, TypeError, ValueError) as exc:
+                response = {
+                    "schema": SCHEMA_VERSION,
+                    "workspace_revision": mapper.snapshot.revision,
+                    "error": {"code": "invalid_request", "message": str(exc)},
+                }
+            output_stream.write(json.dumps(response, sort_keys=True, separators=(",", ":")) + "\n")
+            output_stream.flush()
+    return 0