codmap 0.0.3__py3-none-any.whl

codemap/serve/rag.py

@@ -0,0 +1,142 @@
+"""RAG export — consumer A (DESIGN §1-A, §4, M2.1).
+
+One self-contained *chunk* per symbol for retrieval-augmented generation: what it
+is, where it lives, and its graph neighborhood (calls / callers / bases /
+subclasses / module). Emits JSONL (one chunk per line — the standard RAG ingest
+format); the ``text`` field is a compact rendering ready to embed.
+
+The neighborhood is exactly what a plain source read does NOT cheaply give an AI:
+"what calls this", "what this returns and who consumes it", "its subclasses" —
+resolved across the whole package, not one file.
+"""
+
+from __future__ import annotations
+
+import json
+
+from codemap.query import Query
+
+_SYMBOL_KINDS = {"class", "function"}
+
+
+def build_chunks(query: Query) -> list[dict]:
+    """Structured RAG chunks for every class/function symbol, sorted by id."""
+    graph = query.graph
+    chunks = []
+    for node in sorted(graph.nodes.values(), key=lambda n: n.id):
+        if node.kind not in _SYMBOL_KINDS:
+            continue
+        module = node.id.rsplit(".", 1)[0]
+        neighbors = _neighbors(query, node)
+        chunk = {
+            "id": node.id,
+            "kind": node.kind,
+            "module": module,
+            "file": node.file,
+            "lines": [node.lineno, node.endlineno],
+            "signature": node.signature,
+            "docstring": node.docstring,
+            "deprecated": node.is_deprecated or None,
+            "neighbors": neighbors,
+            "text": _embed_text(node, module, neighbors),
+        }
+        chunks.append({k: v for k, v in chunk.items() if v not in (None, {}, [])})
+    return chunks
+
+
+def render_rag(query: Query) -> str:
+    """RAG chunks as JSONL (one JSON object per line)."""
+    return "".join(
+        json.dumps(c, ensure_ascii=False) + "\n" for c in build_chunks(query)
+    )
+
+
+def _neighbors(query: Query, node) -> dict:
+    n: dict = {}
+    if node.kind == "function":
+        callees = query.callees(node.id)
+        callers = query.callers(node.id)
+        if callees:
+            n["calls"] = callees
+        if callers:
+            n["called_by"] = callers
+        ret = node.extras.get("returns")
+        if ret:
+            n["returns"] = ret
+    if node.kind == "class":
+        bases = query.bases(node.id)
+        subs = query.subclasses(node.id)
+        if bases:
+            n["bases"] = bases
+        if subs:
+            n["subclasses"] = subs
+        reg = node.extras.get("registry")
+        if reg:
+            n["registered_as"] = reg.get("key")
+        # M9/F4: registry family — the Protocol satisfied and its implementers,
+        # neither of which is reachable via inheritance (structural typing).
+        impls = query.implements(node.id)
+        implers = query.implementers(node.id)
+        if impls:
+            n["implements"] = impls
+        if implers:
+            n["implementers"] = implers
+        # M10/F3: aggregate the call-neighbours of the class' own methods so the
+        # class chunk is self-sufficient. A class' behaviour (e.g. a deprecated
+        # wrapper delegating to `analyze_zones`) lives on its methods; a retriever
+        # pulling the class chunk otherwise never sees that delegation seam.
+        via = _methods_calls(query, node.id)
+        if via:
+            n["calls_via_methods"] = via
+    return n
+
+
+def _methods_calls(query: Query, class_id: str) -> list[dict]:
+    """Distinct call targets of the class' methods, each tagged with one via-method."""
+    prefix = class_id + "."
+    seen: dict[str, str] = {}  # target -> via-method (first, deterministic)
+    for mid in sorted(query.graph.nodes):
+        if not mid.startswith(prefix):
+            continue
+        if query.graph.nodes[mid].kind != "function":
+            continue
+        for tgt in query.callees(mid):
+            if tgt.startswith(prefix):
+                continue  # sibling method — internal, not an outward seam
+            seen.setdefault(tgt, mid)
+    return [{"target": t, "via": seen[t]} for t in sorted(seen)]
+
+
+def _embed_text(node, module, neighbors) -> str:
+    """A compact, self-contained string for the embedding model."""
+    name = node.id.rsplit(".", 1)[-1]
+    parts = [f"{node.kind} {name} in {module}."]
+    if node.signature:
+        parts.append(f"Signature: {node.signature}.")
+    if node.docstring:
+        first = node.docstring.strip().splitlines()[0].strip()
+        if first:
+            parts.append(first)
+    if neighbors.get("bases"):
+        parts.append("Inherits: " + ", ".join(_short(b) for b in neighbors["bases"]) + ".")
+    if neighbors.get("calls"):
+        parts.append("Calls: " + ", ".join(_short(c) for c in neighbors["calls"][:8]) + ".")
+    if neighbors.get("called_by"):
+        parts.append("Called by: " + ", ".join(_short(c) for c in neighbors["called_by"][:8]) + ".")
+    if neighbors.get("registered_as"):
+        parts.append(f"Registered as '{neighbors['registered_as']}'.")
+    if neighbors.get("implements"):
+        parts.append("Implements: " + ", ".join(_short(p) for p in neighbors["implements"]) + ".")
+    if neighbors.get("implementers"):
+        parts.append("Implemented by: " + ", ".join(_short(c) for c in neighbors["implementers"][:8]) + ".")
+    if neighbors.get("calls_via_methods"):
+        seams = ", ".join(
+            f"{_short(v['target'])} (via {_short(v['via'])})"
+            for v in neighbors["calls_via_methods"][:8]
+        )
+        parts.append("Methods call: " + seams + ".")
+    return " ".join(parts)
+
+
+def _short(node_id: str) -> str:
+    return node_id.rsplit(".", 1)[-1]

codemap/serve/review.py

@@ -0,0 +1,197 @@
+"""Change-set review — turn a diff into a consolidated review dossier (M15/F17).
+
+The reviewer's real input is a **diff** (files + changed line ranges), not a symbol
+name. A11 dogfood found the pieces existed (impact, call_contract, columns_of,
+references) but nothing stitched them: 4 changed symbols meant ~20 manual op-calls.
+
+``build_review`` resolves hunks → symbols (via ``Query.symbols_in_range``), then per
+symbol assembles callers / signature-change contract / touched columns / cross-root
+consumers, plus a synthesized **risk** rank (the signals are all present — F17/R3),
+a union blast-radius summary, and a risk-sorted order. ``render_review`` is the
+human markdown. No schema change — pure aggregation over existing edges.
+"""
+
+from __future__ import annotations
+
+from codemap.query import Query
+
+
+def resolve_hunks(query: Query, hunks: list[dict]) -> list[str]:
+    """[{file, ranges: [[start,end], …]}] → distinct changed symbol ids."""
+    changed: set[str] = set()
+    for h in hunks:
+        file = h["file"]
+        for rng in h.get("ranges", []):
+            start, end = int(rng[0]), int(rng[-1])
+            changed.update(query.symbols_in_range(file, start, end))
+    return sorted(changed)
+
+
+def _consumers_by_root(query: Query, sid: str) -> dict[str, int]:
+    by_root: dict[str, int] = {}
+    for ref in query.references_to(sid):
+        by_root[ref["root"]] = by_root.get(ref["root"], 0) + 1
+    return by_root
+
+
+def _risk(caller_n: int, consumers: dict[str, int], contract_sites: int,
+          touches_columns: bool) -> tuple[str, int]:
+    """Synthesize a review-priority label from the blast signals (F17/R3).
+
+    Heuristic, honest and documented — not a proof: more inbound reach, more
+    external (cross-root) consumers, more distinct call-site shapes, and dataflow
+    contact all raise how much a change here warrants scrutiny.
+    """
+    external = sum(v for r, v in consumers.items() if r != "core")
+    score = caller_n + 2 * external + contract_sites + (1 if touches_columns else 0)
+    if external or score >= 5:
+        return "high", score
+    if score >= 2:
+        return "medium", score
+    return "low", score
+
+
+def build_symbol_dossier(query: Query, sid: str) -> dict:
+    """Everything a reviewer needs about one changed symbol (F17)."""
+    node = query.graph.nodes.get(sid)
+    kind = node.kind if node else None
+    callers = query.callers(sid)
+    contract = query.call_contract(sid)
+    cols = query.columns_of(sid) if kind == "function" else {"reads": [], "writes": []}
+    consumers = _consumers_by_root(query, sid)
+    touches = bool(cols["reads"] or cols["writes"])
+    risk, score = _risk(len(callers), consumers, len(contract), touches)
+    return {
+        "symbol": sid,
+        "kind": kind,
+        "file": node.file if node else None,
+        "lines": [node.lineno, node.endlineno] if node else None,
+        "callers": callers,
+        "callees": query.callees(sid) if kind == "function" else [],
+        "call_contract": contract,      # signature-change surface (F7)
+        "columns": cols,                # dataflow contact (F6/F11)
+        "consumers_by_root": consumers,  # cross-root blast (F1)
+        "risk": risk,
+        "risk_score": score,
+    }
+
+
+def build_review(query: Query, *, hunks: list[dict] | None = None,
+                 symbols: list[str] | None = None, base_graph=None) -> dict:
+    """Consolidated change-set review from diff hunks and/or explicit symbols.
+
+    Returns ``{changed: [dossier…], summary}`` with dossiers risk-sorted (highest
+    first). ``summary`` carries the symbol count, union blast-radius by root, and
+    the count of unresolved hunks (module-level / unknown files) so nothing is
+    silently dropped.
+
+    ``base_graph`` (R1-C5): a 'before' graph to API-diff against. Hunk-based review
+    sees only *modified* lines; the diff adds the symbols hunks miss — **removed**
+    and **added** public symbols and **breaking** signature changes — under
+    ``api_diff``.
+    """
+    ids = set(symbols or [])
+    unresolved = []
+    if hunks:
+        for h in hunks:
+            file = h["file"]
+            for rng in h.get("ranges", []):
+                start, end = int(rng[0]), int(rng[-1])
+                got = query.symbols_in_range(file, start, end)
+                if got:
+                    ids.update(got)
+                else:
+                    unresolved.append({"file": file, "range": [start, end]})
+    ids = {query.canonical(i) or i for i in ids}
+    dossiers = [build_symbol_dossier(query, sid) for sid in sorted(ids)]
+    dossiers.sort(key=lambda d: (-d["risk_score"], d["symbol"]))
+
+    union_by_root: dict[str, int] = {}
+    for d in dossiers:
+        for r, v in d["consumers_by_root"].items():
+            union_by_root[r] = union_by_root.get(r, 0) + v
+    summary = {
+        "changed_symbols": len(dossiers),
+        "blast_by_root": union_by_root,
+        "high_risk": [d["symbol"] for d in dossiers if d["risk"] == "high"],
+        "unresolved_hunks": unresolved,
+    }
+    result = {"changed": dossiers, "summary": summary}
+    if base_graph is not None:
+        from codemap.serve.apidiff import build_apidiff
+        result["api_diff"] = build_apidiff(base_graph, query.graph)
+    return result
+
+
+def render_review(query: Query, *, hunks: list[dict] | None = None,
+                  symbols: list[str] | None = None, base_graph=None) -> str:
+    """Human markdown for a change-set review (highest risk first)."""
+    rv = build_review(query, hunks=hunks, symbols=symbols, base_graph=base_graph)
+    s = rv["summary"]
+    out = ["# Change-set review", ""]
+    out.append(f"**{s['changed_symbols']} changed symbol(s)**; "
+               f"blast by root: {s['blast_by_root'] or '—'}.")
+    if "api_diff" in rv:
+        ad = rv["api_diff"]["summary"]
+        out.append(f"**API diff vs baseline:** {ad['breaking_total']} breaking, "
+                   f"{ad['removed']} removed, {ad['added']} added.")
+    if s["high_risk"]:
+        out.append(f"**Review first (high risk):** {', '.join(s['high_risk'])}")
+    if s["unresolved_hunks"]:
+        out.append(f"_Unresolved hunks (module-level / unknown file): "
+                   f"{len(s['unresolved_hunks'])} — inspect manually._")
+    out.append("")
+    if "api_diff" in rv:
+        ad = rv["api_diff"]
+        breaking = [c for c in ad["changes"] if c["severity"] == "breaking"]
+        if ad["removed"] or breaking:
+            out.append("## API breaking changes (not in the hunks)")
+            for sym in ad["removed"][:20]:
+                out.append(f"- **removed** `{sym}`")
+            for c in breaking[:20]:
+                out.append(f"- **{c['kind']}** `{c['symbol']}` — {c['detail']}")
+            out.append("")
+    for d in rv["changed"]:
+        loc = f" ({d['file']}:{d['lines'][0]})" if d["file"] and d["lines"] else ""
+        out.append(f"## [{d['risk']}] {d['symbol']}{loc}")
+        if d["consumers_by_root"]:
+            out.append(f"- Consumers by root: {d['consumers_by_root']}")
+        if d["callers"]:
+            out.append(f"- Callers ({len(d['callers'])}): "
+                       f"{', '.join(d['callers'][:8])}{' …' if len(d['callers']) > 8 else ''}")
+        if d["call_contract"]:
+            out.append(f"- Call-site contract: {len(d['call_contract'])} site(s) "
+                       f"— check on signature change")
+        cols = d["columns"]
+        if cols["reads"] or cols["writes"]:
+            out.append(f"- Columns: reads {cols['reads'] or '—'}, writes {cols['writes'] or '—'}")
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+# -- unified-diff hunk parsing (for CLI `codemap review <diff>`) --------------
+
+def parse_unified_diff(text: str) -> list[dict]:
+    """Parse a unified diff → [{file, ranges: [[start,end], …]}] (new-file lines).
+
+    Reads ``+++ b/<path>`` targets and ``@@ -a,b +c,d @@`` hunk headers, taking the
+    **new-file** side (``+c,d`` → lines ``c … c+d-1``). Deletions (``d == 0``)
+    anchor a zero-width range at ``c`` so a pure deletion still maps to its site.
+    """
+    import re
+    hdr = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+    files: dict[str, list] = {}
+    current = None
+    for ln in text.splitlines():
+        if ln.startswith("+++ "):
+            path = ln[4:].strip().split("\t")[0]
+            if path.startswith("b/"):
+                path = path[2:]
+            current = None if path == "/dev/null" else path
+            files.setdefault(current, [])
+        elif current and (m := hdr.match(ln)):
+            start = int(m.group(1))
+            count = int(m.group(2)) if m.group(2) is not None else 1
+            end = start + count - 1 if count else start
+            files[current].append([start, max(start, end)])
+    return [{"file": f, "ranges": r} for f, r in files.items() if f and r]

codemap/serve/scip.py

@@ -0,0 +1,183 @@
+"""SCIP export — codemap's graph as a SCIP index (R1-C1).
+
+SCIP (Sourcegraph Code Intelligence Protocol) is the ascendant open interchange
+format for precise code intelligence: emit one ``index.scip`` and Sourcegraph,
+Glean and any SCIP consumer light up go-to-definition, symbol search and type
+hierarchy across the ecosystem. The research landscape (``research/00_landscape.md``)
+ranked this the highest-value interop move.
+
+**Honest scope.** codemap's graph is *symbol-level*: edges relate symbol→symbol
+but carry no call-site coordinates. SCIP occurrences are *location-based*. So this
+exporter emits exactly what codemap knows precisely:
+
+- **Definition occurrences** — one per node with a file location (module / class /
+  function / attribute) → go-to-definition + symbol search.
+- **SymbolInformation** — kind, docstring, and ``inherits`` / ``implements`` as SCIP
+  ``relationships`` (``is_implementation``) → type hierarchy.
+
+It does **not** emit reference occurrences (find-references): that needs token
+positions codemap does not track. Emitting fake positions would be worse than
+omitting them, so we omit them and say so — consistent with codemap's other
+lower-bound disclaimers.
+
+``protobuf`` is an **optional** dependency (``pip install codemap[scip]``); the
+vendored bindings (``_scip_pb2.py``) are generated from the official ``scip.proto``.
+The import is lazy so codemap works without it.
+"""
+
+from __future__ import annotations
+
+import os
+
+from codemap.model import Graph
+from codemap.query import Query
+
+# Descriptor suffix per node kind (SCIP symbol grammar): namespace ``/``, type
+# ``#``, method ``().``, term ``.``. Functions and methods both use the method
+# descriptor (as scip-python does). Unknown intermediates default to namespace.
+_SUFFIX = {"module": "/", "class": "#", "function": "().", "attribute": "."}
+
+# Names outside this set must be backtick-escaped in a SCIP symbol (grammar).
+_SIMPLE = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_+$")
+
+
+def _load_pb2():
+    """Import the vendored SCIP bindings, with a friendly error if protobuf is absent."""
+    try:
+        from codemap.serve import _scip_pb2  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - exercised via the extra
+        raise RuntimeError(
+            "SCIP export needs the optional 'scip' extra — install it with "
+            "`pip install codemap[scip]` (adds protobuf)."
+        ) from exc
+    return _scip_pb2
+
+
+def _escape(name: str) -> str:
+    """Escape a descriptor name per the SCIP symbol grammar (backtick-wrap if needed)."""
+    if name and all(c in _SIMPLE for c in name):
+        return name
+    return "`" + name.replace("`", "``") + "`"
+
+
+def _symbol(nodes: dict, node_id: str, prefix: str) -> str:
+    """Build the SCIP symbol string for ``node_id`` from its ancestor chain.
+
+    Each dotted segment becomes a descriptor whose suffix is chosen by the kind of
+    the node at that prefix (looked up in the graph); missing intermediates default
+    to a namespace descriptor.
+    """
+    parts = node_id.split(".")
+    out = []
+    for i in range(1, len(parts) + 1):
+        pid = ".".join(parts[:i])
+        node = nodes.get(pid)
+        last = i == len(parts)
+        kind = node.kind if node else ("attribute" if last else "module")
+        out.append(_escape(parts[i - 1]) + _SUFFIX.get(kind, "/"))
+    return prefix + "".join(out)
+
+
+def _kind(pb2, kind: str, parent_kind: str | None):
+    K = pb2.SymbolInformation.Kind
+    if kind == "module":
+        return K.Module
+    if kind == "class":
+        return K.Class
+    if kind == "function":
+        return K.Method if parent_kind == "class" else K.Function
+    if kind == "attribute":
+        return K.Field if parent_kind == "class" else K.Variable
+    return K.UnspecifiedKind
+
+
+def _language(file: str, pb2) -> str:
+    return "Python" if file.endswith(".py") else ""
+
+
+def build_scip(
+    query: Query,
+    *,
+    project_root: str,
+    package: str | None = None,
+    version: str = ".",
+    tool_version: str = "0.0.1",
+    scheme: str = "codemap",
+    manager: str = "python",
+):
+    """Build a ``scip_pb2.Index`` from the graph (definitions + symbol info)."""
+    pb2 = _load_pb2()
+    graph: Graph = query.graph
+    nodes = graph.nodes
+    package = package or graph.target
+    prefix = f"{scheme} {manager} {package} {version} "
+
+    # Index edges by source for relationship lookup (inherits / implements).
+    rels_by_src: dict[str, list[tuple[str, str]]] = {}
+    for e in graph.edges:
+        if e.type in ("inherits", "implements"):
+            rels_by_src.setdefault(e.source, []).append((e.type, e.target))
+
+    # Group definition occurrences + symbol info by file.
+    by_file: dict[str, dict] = {}
+    for nid in sorted(nodes):
+        node = nodes[nid]
+        if node.kind not in _SUFFIX or not node.file:
+            continue  # skip synthetic column nodes, doc nodes, locationless overlays
+        sym = _symbol(nodes, nid, prefix)
+        line0 = (node.lineno - 1) if node.lineno else 0
+        parent_kind = None
+        if "." in nid:
+            parent = nodes.get(nid.rsplit(".", 1)[0])
+            parent_kind = parent.kind if parent else None
+
+        occ = pb2.Occurrence(symbol=sym, symbol_roles=pb2.SymbolRole.Definition)
+        occ.single_line_range.line = line0
+        occ.single_line_range.start_character = 0
+        occ.single_line_range.end_character = 0
+        # Test-code provenance (honest signal to consumers).
+        if node.extras.get("root") == "tests":
+            occ.symbol_roles |= pb2.SymbolRole.Test
+        # Enclosing range = the full definition span (proto guidance for defs).
+        if node.endlineno and node.endlineno - 1 != line0:
+            occ.multi_line_enclosing_range.start_line = line0
+            occ.multi_line_enclosing_range.start_character = 0
+            occ.multi_line_enclosing_range.end_line = node.endlineno - 1
+            occ.multi_line_enclosing_range.end_character = 0
+
+        info = pb2.SymbolInformation(symbol=sym, kind=_kind(pb2, node.kind, parent_kind))
+        if node.docstring:
+            info.documentation.append(node.docstring)
+        for _etype, target in sorted(rels_by_src.get(nid, [])):
+            if target in nodes:  # only relate to symbols we can name canonically
+                info.relationships.append(
+                    pb2.Relationship(symbol=_symbol(nodes, target, prefix),
+                                     is_implementation=True))
+
+        bucket = by_file.setdefault(node.file, {"occ": [], "sym": []})
+        bucket["occ"].append(occ)
+        bucket["sym"].append(info)
+
+    index = pb2.Index()
+    index.metadata.version = pb2.ProtocolVersion.UnspecifiedProtocolVersion
+    index.metadata.tool_info.name = "codemap"
+    index.metadata.tool_info.version = tool_version
+    index.metadata.project_root = "file://" + os.path.abspath(project_root)
+    index.metadata.text_document_encoding = pb2.TextEncoding.UTF8
+
+    for rel_path in sorted(by_file):
+        bucket = by_file[rel_path]
+        doc = pb2.Document(
+            relative_path=rel_path,
+            language=_language(rel_path, pb2),
+            position_encoding=pb2.PositionEncoding.UTF8CodeUnitOffsetFromLineStart,
+        )
+        doc.occurrences.extend(sorted(bucket["occ"], key=lambda o: o.symbol))
+        doc.symbols.extend(sorted(bucket["sym"], key=lambda s: s.symbol))
+        index.documents.append(doc)
+    return index
+
+
+def write_scip(index) -> bytes:
+    """Serialize a SCIP ``Index`` to deterministic protobuf bytes."""
+    return index.SerializeToString(deterministic=True)

codemap/serve/semantic.py

@@ -0,0 +1,71 @@
+"""Semantic search via a retrieval adapter, enriched to codemap symbols (R1-C16).
+
+The codemap-native half of a retrieval adapter. Lives in ``serve`` (not
+``integrations``) because it needs the query layer: the ``integrations`` layer is a
+near-leaf opt-in gate and may not depend on ``query`` (enforced by codemap's own
+architecture contract). So the adapter returns raw location hits (no graph), and
+this module — allowed to use both ``query`` and ``integrations`` — resolves each
+``(file, line)`` to the **exact codemap symbol** at that location. The external tool
+supplies fuzzy relevance; codemap supplies exact structure — the composition (fuzzy
+retrieval → codemap symbols) neither gives alone.
+
+Adapter-mode only (``mode=ADAPTER``): a router can only forward its answer as-is, so
+it can't be enriched — for a router-only semantic tool (e.g. GitNexus, NC-licensed),
+use ``codemap route semantic-search`` instead. The core works without any of this:
+no enabled+installed adapter → ``{resolver: None, hits: []}``, never an error.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from codemap.integrations import (
+    IntegrationConfig, IntegrationMode, SemanticHit, is_permissive, load_config, resolve,
+)
+from codemap.query import Query
+
+
+def semantic_search(query: Query, text: str, *, root: str = ".",
+                    config: IntegrationConfig | None = None,
+                    limit: int = 10) -> dict[str, Any]:
+    """Resolve a semantic-search adapter, run it, enrich hits to codemap symbols.
+
+    Returns ``{resolver, disclaimer, hits}`` where ``hits`` is a list of
+    :class:`~codemap.integrations.base.SemanticHit` dicts sorted by score (each
+    de-duplicated to one entry per resolved symbol, keeping its best-scoring chunk).
+    ``resolver`` is None when no adapter is enabled+installed — the caller degrades.
+    """
+    cfg = config if config is not None else load_config(root)
+    adapter = resolve("semantic-search", config=cfg, root=root,
+                      mode=IntegrationMode.ADAPTER)
+    if adapter is None:
+        return {"resolver": None, "disclaimer": None, "hits": []}
+
+    raw = adapter.search("semantic-search", text, root=root, limit=limit)
+    hits: list[SemanticHit] = []
+    seen: dict[str, int] = {}  # symbol id → index in `hits` (dedup, keep best score)
+    for r in raw:
+        file, line = r["file"], r["start_line"]
+        symbol = query.symbol_at(file, line)
+        hit = SemanticHit(
+            file=file, start_line=line, end_line=r.get("end_line"),
+            score=r["score"], symbol=symbol,
+            resolution="symbol" if symbol else "unresolved",
+        )
+        if symbol is not None and symbol in seen:
+            if hit.score > hits[seen[symbol]].score:  # same symbol → keep higher score
+                hits[seen[symbol]] = hit
+            continue
+        if symbol is not None:
+            seen[symbol] = len(hits)
+        hits.append(hit)
+
+    hits.sort(key=lambda h: (-h.score, h.file, h.start_line))
+    # Adapters are permissive by policy, so disclaimer is normally None; kept for
+    # uniformity with the router path (and any future edge case).
+    disclaimer = None if is_permissive(adapter.license) else adapter.disclaimer()
+    return {
+        "resolver": adapter.name,
+        "disclaimer": disclaimer,
+        "hits": [h.to_dict() for h in hits],
+    }

codemap/serve/server.py

@@ -0,0 +1,43 @@
+"""Line-delimited JSON stdio loop over a warm ``Session`` (DESIGN §14.4, M3.1).
+
+Transport for the resident process: one JSON request per input line, one JSON
+response per output line. Zero startup per call — the graph is loaded once by the
+caller and reused for the life of the process. Transport-neutral by design: an
+MCP adapter can wrap the same ``Session.handle`` later without touching this loop.
+
+    $ codemap serve --graph graph.json
+    {"op": "query", "args": {"name": "analyze_zones"}}
+    {"ok": true, "result": {...}}
+    {"op": "column", "args": {"name": "macd_hist"}}
+    {"ok": true, "result": {"writes": [...], "reads": [...]}}
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from codemap.serve.session import Session
+
+
+def serve_stdio(session: Session, stdin=None, stdout=None) -> int:
+    """Read JSON requests line-by-line, write JSON responses. EOF ends the loop.
+
+    A blank line is skipped; a malformed line yields an error response rather than
+    crashing the resident process. Returns 0 at EOF.
+    """
+    stdin = stdin if stdin is not None else sys.stdin
+    stdout = stdout if stdout is not None else sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as exc:
+            response = {"ok": False, "error": f"invalid JSON: {exc}"}
+        else:
+            response = session.handle(request)
+        stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+        stdout.flush()
+    return 0