codmap 0.0.3__py3-none-any.whl

codemap/serve/livingdocs.py

@@ -0,0 +1,174 @@
+"""Living docs — a narrative document generated from the graph (R1-C15).
+
+The honest answer to "auto-generated codebase wiki". Tools like CodeWiki / neuro-
+articles narrate what code *does* by guessing; codemap only states what the graph
+proves. Everything here is traceable: structure (modules/classes/functions/imports/
+inheritance) is exact static fact; docstrings are the authors' own words, quoted
+verbatim — never generated, and an undocumented symbol is *marked*, not invented;
+call-flow-derived claims carry the static lower-bound caveat (epistemic: partial).
+
+Organised by **discovered subsystem** (communities, R1-C18) rather than a flat
+module list — "what is this made of, and how does it run" — and deterministic, so
+re-running refreshes it (the "living" part). Feeds nothing it can't cite.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from codemap.model import Graph
+from codemap.query import Query
+
+_SYM_KINDS = {"class", "function"}
+_PER_SUBSYSTEM = 25   # symbols listed per subsystem before "+N more"
+_ENTRY_POINTS = 15    # behavioural entry points listed
+_FLOW_DEPTH = 4
+
+
+def _first_line(docstring: str | None) -> str | None:
+    if not docstring:
+        return None
+    for line in docstring.strip().splitlines():
+        if line.strip():
+            return line.strip()
+    return None
+
+
+def _module_of(node_id: str) -> str:
+    return node_id.rsplit(".", 1)[0]
+
+
+def _public_symbols_by_module(graph: Graph) -> dict[str, list]:
+    """Public top-level class/function nodes of the **core** package, by module id.
+
+    Core only: living docs document the package, not its tests/docs/examples
+    (consumer roots), which on a repo-scoped graph would otherwise leak in.
+    """
+    by_module: dict[str, list] = defaultdict(list)
+    for n in graph.nodes.values():
+        if (n.kind in _SYM_KINDS and n.visibility == "public"
+                and n.extras.get("root", "core") == "core"):
+            by_module[_module_of(n.id)].append(n)
+    return by_module
+
+
+def _render_symbol(n) -> list[str]:
+    name = n.id.rsplit(".", 1)[-1]
+    head = n.signature or name
+    marker = " **⚠ deprecated**" if n.is_deprecated else ""
+    doc = _first_line(n.docstring)
+    line = f"- **`{head}`** ({n.kind}){marker}"
+    return [line, f"  - {doc}"] if doc else [line, "  - _(undocumented)_"]
+
+
+def render_docs(query: Query) -> str:
+    graph = query.graph
+    target = graph.target
+    by_module = _public_symbols_by_module(graph)
+    kinds = defaultdict(int)
+    for n in graph.nodes.values():
+        kinds[n.kind] += 1
+    total_public = sum(len(v) for v in by_module.values())
+
+    out = [f"# {target} — living documentation", ""]
+    out.append(
+        f"_{kinds['module']} modules · {kinds['class']} classes · {kinds['function']} "
+        f"functions · {total_public} public symbols. Generated from the code graph — "
+        f"structure is exact static fact; docstrings are the authors' own words, "
+        f"quoted verbatim._"
+    )
+    out.append("")
+
+    # -- subsystems (communities) -------------------------------------------
+    comms = query.communities()
+    grouped_modules: set[str] = set()
+    out.append("## Subsystems")
+    out.append("")
+    if not comms:
+        out.append("_No import edges to cluster — see the module list below._")
+        out.append("")
+    for i, c in enumerate(comms, 1):
+        out.append(f"### {i}. {c['label']} — {c['size']} modules")
+        out.append("")
+        syms = []
+        for m in c["modules"]:
+            grouped_modules.add(m)
+            syms.extend(sorted(by_module.get(m, []), key=lambda n: n.id))
+        if not syms:
+            out.append("_No public symbols (internal-only subsystem)._")
+            out.append("")
+            continue
+        for n in syms[:_PER_SUBSYSTEM]:
+            out.extend(_render_symbol(n))
+        if len(syms) > _PER_SUBSYSTEM:
+            out.append(f"- _… {len(syms) - _PER_SUBSYSTEM} more public symbols_")
+        out.append("")
+
+    # -- ungrouped modules (completeness: nothing dropped) ------------------
+    ungrouped = sorted(
+        m for m in by_module
+        if m not in grouped_modules and query.root_of(m) == "core" and by_module[m]
+    )
+    if ungrouped:
+        out.append("## Other modules (no import clustering)")
+        out.append("")
+        for m in ungrouped:
+            out.append(f"### `{m}`")
+            out.append("")
+            for n in sorted(by_module[m], key=lambda n: n.id)[:_PER_SUBSYSTEM]:
+                out.extend(_render_symbol(n))
+            out.append("")
+
+    # -- behavioural entry points (flows) -----------------------------------
+    eps = query.entry_points()
+    if eps:
+        out.append("## Behavioural entry points")
+        out.append("")
+        out.append(
+            f"_Where execution starts — functions that call out but are never called "
+            f"(resolved edges). Reach = symbols touched within {_FLOW_DEPTH} calls. "
+            f"**Static lower bound** (epistemic: partial): Python call resolution is "
+            f"incomplete, so an unresolved caller can leave a real internal here._"
+        )
+        out.append("")
+        ranked = sorted(
+            ((query.flow(ep, max_depth=_FLOW_DEPTH)["reached"], ep) for ep in eps),
+            reverse=True,
+        )
+        for reached, ep in ranked[:_ENTRY_POINTS]:
+            out.append(f"- `{ep}` → reaches {reached}")
+        if len(ranked) > _ENTRY_POINTS:
+            out.append(f"- _… {len(ranked) - _ENTRY_POINTS} more entry points_")
+        out.append("")
+
+    # -- architecture caveats (the honest health section) -------------------
+    cycles = query.import_cycles()
+    lay = query.layers()
+    gods = query.hotspots()["god_classes"]
+    out.append("## Architecture notes")
+    out.append("")
+    if cycles:
+        out.append(f"- **{len(cycles)} import cycle(s)** — e.g. "
+                   + "; ".join(" → ".join(c) for c in sorted(cycles, key=len)[:3]))
+    else:
+        out.append("- Import graph is acyclic.")
+    if lay["violations"]:
+        out.append("- **Layer violations (mutual dependency):** "
+                   + ", ".join(f"{a} ↔ {b}" for a, b in lay["violations"]))
+    if gods:
+        out.append("- **God-object candidates:** "
+                   + ", ".join(f"`{g['class']}` ({g['methods']} methods)" for g in gods[:5]))
+    out.append("")
+
+    # -- honesty footer -----------------------------------------------------
+    out.append("---")
+    out.append("")
+    out.append(
+        "_Generated by codemap from the canonical code graph. **Exact:** modules, "
+        "classes, functions, imports, inheritance (static parse). **Verbatim:** "
+        "docstrings — the authors' words, never generated; undocumented symbols are "
+        "marked, not invented. **Lower bound (epistemic: partial):** call-flows and "
+        "entry-point reach — Python dynamism is not fully statically resolvable. "
+        "Deterministic — re-run to refresh._"
+    )
+    return "\n".join(out).rstrip() + "\n"

codemap/serve/mcp_server.py

@@ -0,0 +1,278 @@
+"""MCP adapter — expose the warm serve surface as Model Context Protocol tools.
+
+The `serve` layer is deliberately transport-neutral: ``Session.handle({op, args})``
+takes and returns plain dicts. This module is the thin wrapper that maps each op to
+one MCP tool, so an MCP client (an AI agent host) can drive codemap directly. No new
+logic — every tool just calls ``session.handle`` and returns its envelope
+(``{ok, result, resolved?}``), so the caller still sees the ambiguity signal (F14)
+and error handling for free.
+
+MCP is an **optional dependency** (`pip install codemap[mcp]`): the import is lazy so
+`codemap` works without it; only `codemap serve --mcp` needs it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from codemap.serve.session import Session
+
+_INSTRUCTIONS = (
+    "codemap exposes a static code graph of a package. Start with `search` (find "
+    "symbols by substring) or `stats` (graph overview), then `query` a symbol for its "
+    "dossier. Use `impact`/`callers`/`callees` for blast radius, `review` to turn a "
+    "diff into a change-set review, `architecture` for the system shape, `check` to "
+    "enforce the [architecture] contract, `diff` for a two-snapshot API breaking-change "
+    "report, `communities` "
+    "for module subsystems and `flows` for forward call-flow from an entry. `tests` "
+    "answers which tests exercise a symbol (and `covers` the inverse) on a repo-scoped "
+    "graph. Relational "
+    "tools accept a short name or re-export id; when a name is ambiguous the response "
+    "carries a `resolved.ambiguous` flag — check it before trusting the answer."
+)
+
+
+def _compact_impact(env: dict, limit: int) -> dict:
+    """Shrink an impact envelope for MCP (F22): drop the duplicate markdown and cap
+    each entry's flat ref list at ``limit`` — the ``by_root`` counts stay complete."""
+    if not env.get("ok"):
+        return env
+    env = dict(env)
+    result = dict(env.get("result") or {})
+    result.pop("markdown", None)  # structured refs already carry everything
+    entries = []
+    for e in result.get("impact", []):
+        e = dict(e)
+        refs = e.get("refs", [])
+        if len(refs) > limit:
+            e = {**e, "refs": refs[:limit],
+                 "refs_shown": limit, "refs_total": len(refs)}
+        entries.append(e)
+    result["impact"] = entries
+    env["result"] = result
+    return env
+
+
+def _cap_list(env: dict, limit: int) -> dict:
+    """Cap a list-valued result at ``limit`` (F22), noting the total when truncated."""
+    if not env.get("ok"):
+        return env
+    res = env.get("result")
+    if isinstance(res, list) and len(res) > limit:
+        env = {**env, "result": res[:limit], "shown": limit, "total": len(res)}
+    return env
+
+
+def build_mcp_server(session: "Session", name: str = "codemap") -> Any:
+    """Build an MCP server exposing the session's ops as tools (lazy mcp import)."""
+    try:
+        from mcp.server import MCPServer
+    except ImportError as exc:  # pragma: no cover - exercised via CLI message
+        raise RuntimeError(
+            "MCP support requires the optional 'mcp' dependency: "
+            "pip install 'codemap[mcp]'"
+        ) from exc
+
+    server = MCPServer(name, instructions=_INSTRUCTIONS)
+
+    def op(name: str, args: dict | None = None) -> dict:
+        return session.handle({"op": name, "args": args or {}})
+
+    @server.tool()
+    def stats() -> dict:
+        """Graph overview: target, schema version, node/edge counts by kind/type, and
+        `freshness` for the graph ACTUALLY served — `stale: true` (+reason) if the
+        on-disk artifact was rebuilt after this server loaded it. Call `reload` then."""
+        return op("stats")
+
+    @server.tool()
+    def reload() -> dict:
+        """Reload the on-disk graph into this server without restarting — pick up an
+        external rebuild (e.g. `codemap build --incremental`). Returns before/after
+        counts and refreshed freshness. No-op with a reason if started from --build."""
+        return op("reload")
+
+    @server.tool()
+    def search(term: str, kind: str | None = None, limit: int = 50) -> dict:
+        """Find symbols whose id contains `term` (case-insensitive). The discovery
+        entry point for a cold agent. Optional `kind`: module|class|function|column."""
+        return op("search", {"term": term, "kind": kind, "limit": limit})
+
+    @server.tool()
+    def query(name: str) -> dict:
+        """Full dossier for a symbol name: where defined (file:line), bases/impls for
+        classes, callers/callees/columns for functions, registration recipe, column
+        dataflow. The main lookup."""
+        return op("query", {"name": name})
+
+    @server.tool()
+    def resolve(name: str) -> dict:
+        """Resolve a short name / re-export id to the canonical node id, with an
+        `ambiguous` flag and `alternatives` when the name maps to several defs."""
+        return op("resolve", {"name": name})
+
+    @server.tool()
+    def callers(symbol: str) -> dict:
+        """Functions that statically call `symbol` (resolved calls only)."""
+        return op("callers", {"symbol": symbol})
+
+    @server.tool()
+    def callees(symbol: str) -> dict:
+        """Internal symbols that `symbol` statically calls."""
+        return op("callees", {"symbol": symbol})
+
+    @server.tool()
+    def tests(symbol: str, depth: int = 3, cap: int = 25) -> dict:
+        """Which tests exercise `symbol` — the NEAREST band of test functions that reach
+        it, as runnable pytest node ids. `confidence` is high/medium by distance and
+        `unknown` when nothing is found within `depth`: unknown means unknown, never
+        "untested". Needs a repo-scoped graph (`--consumer tests --mode full`). Raise
+        `depth` above 3 only for low-confidence candidates."""
+        return op("tests", {"symbol": symbol, "depth": depth, "cap": cap})
+
+    @server.tool()
+    def covers(test: str, depth: int = 3, cap: int = 25) -> dict:
+        """The inverse of `tests`: which core symbols this test reaches, by distance.
+        Use it to check whether a test exercises what its name claims."""
+        return op("covers", {"test": test, "depth": depth, "cap": cap})
+
+    @server.tool()
+    def impact(symbol: str, depth: int = 2, limit: int = 40, full: bool = False) -> dict:
+        """Blast radius of changing `symbol`: inbound references up to `depth`, counted
+        by provenance root (core/tests/docs/…). Compact by default (F22): omits the
+        duplicate markdown and caps the flat ref list at `limit` (by_root counts stay
+        complete). Pass full=true for the entire payload including markdown."""
+        env = op("impact", {"symbol": symbol, "depth": depth})
+        return env if full else _compact_impact(env, limit)
+
+    @server.tool()
+    def call_contract(symbol: str, limit: int = 30, full: bool = False) -> dict:
+        """Per-caller argument contract of calls into `symbol` (call-sites, posargs,
+        kwargs, splat) — for reasoning about a signature change. Capped at `limit`
+        entries by default (F22); pass full=true for all of them."""
+        env = op("call_contract", {"symbol": symbol})
+        return env if full else _cap_list(env, limit)
+
+    @server.tool()
+    def implementers(protocol: str) -> dict:
+        """Concrete classes that implement `protocol` (registry family)."""
+        return op("implementers", {"protocol": protocol})
+
+    @server.tool()
+    def family(cls: str) -> dict:
+        """The Protocol(s) `cls` satisfies and its sibling implementations."""
+        return op("family", {"class": cls})
+
+    @server.tool()
+    def families() -> dict:
+        """All registry/Protocol families with their registration recipe (decorator +
+        key per member) — how to add a new implementation."""
+        return op("families")
+
+    @server.tool()
+    def column(name: str) -> dict:
+        """Producers/consumers of a string-keyed column `name` (dataflow)."""
+        return op("column", {"name": name})
+
+    @server.tool()
+    def columns_of(symbol: str) -> dict:
+        """Which string-key columns a function reads / writes (reverse dataflow)."""
+        return op("columns_of", {"symbol": symbol})
+
+    @server.tool()
+    def accessors(attribute: str) -> dict:
+        """Who reads / writes a class `attribute` (field blast-radius; R1-C20).
+
+        The attribute analog of `column`: `{reads: [funcs], writes: [funcs]}`.
+        Lower bound — attribute access is modelled best-effort (self./ClassName./
+        construction, and obj.field on the deep tier)."""
+        return op("accessors", {"attribute": attribute})
+
+    @server.tool()
+    def locate(file: str, line: int | None = None,
+               start: int | None = None, end: int | None = None) -> dict:
+        """Map a diff location to symbol(s): pass `file` + `line`, or `file` + `start`/
+        `end` for a hunk range. Returns the innermost enclosing symbol(s)."""
+        if line is not None:
+            return op("locate", {"file": file, "line": line})
+        return op("locate", {"file": file, "lines": [start, end]})
+
+    @server.tool()
+    def review(hunks: list[dict] | None = None, symbols: list[str] | None = None) -> dict:
+        """Change-set review: pass `hunks` ([{file, ranges:[[start,end]]}]) and/or
+        `symbols`. Returns a risk-sorted dossier per changed symbol + a blast summary."""
+        return op("review", {"hunks": hunks, "symbols": symbols})
+
+    @server.tool()
+    def architecture() -> dict:
+        """Whole-system shape: layers + direction/violations, coupling (Ca/Ce/
+        instability), god-objects & call-hubs, import cycles."""
+        return op("architecture")
+
+    @server.tool()
+    def diff(base: str) -> dict:
+        """API diff a baseline graph.json (`base`) → this server's graph. Returns
+        {ok, added, removed, changes:[{symbol, kind, severity, detail}], summary} —
+        public-API breaking-change detection between two snapshots."""
+        return op("diff", {"base": base})
+
+    @server.tool()
+    def check(root: str | None = None) -> dict:
+        """Architecture-contract gate: does the graph still satisfy the [architecture]
+        rules in codemap.toml? Returns {ok, violations:[{rule, summary, edges}]} — the
+        'what did I break' check. `root` overrides where codemap.toml is read from."""
+        return op("check", {"root": root})
+
+    @server.tool()
+    def communities() -> list:
+        """Data-driven module subsystems: clusters of modules that import each other
+        more than the rest (deterministic greedy modularity), labelled by layer."""
+        return op("communities")
+
+    @server.tool()
+    def flows(symbol: str | None = None, depth: int = 5) -> dict:
+        """Forward call-flow: what calling `symbol` sets in motion (edges by distance,
+        the mirror of impact). Omit `symbol` to list entry points with their reach."""
+        return op("flows", {"symbol": symbol, "depth": depth})
+
+    @server.tool()
+    def source(symbol: str) -> dict:
+        """Source span of a symbol: {file, lines, code} (code when readable under the
+        server's source-root)."""
+        return op("source", {"symbol": symbol})
+
+    @server.tool()
+    def report(kind: str) -> dict:
+        """Render a markdown report. kind: api-surface | dependencies | dead-code |
+        behavior | architecture."""
+        return op("report", {"kind": kind})
+
+    @server.tool()
+    def semantic_search(query: str, limit: int = 10) -> dict:
+        """Concept search → codemap symbols. Routes the natural-language `query` to an
+        opt-in semantic-search adapter (cocoindex), then resolves each fuzzy hit to the
+        exact codemap symbol at its location — fuzzy retrieval, exact structure. Returns
+        {resolver, hits:[{symbol, score, file, lines}]}; empty if no adapter is enabled."""
+        return op("semantic", {"query": query, "limit": limit})
+
+    @server.tool()
+    def pack(budget: int = 2000, seeds: list[str] | None = None) -> dict:
+        """Token-budgeted context pack: the most relevant slice of the graph under `budget`
+        tokens, ranked by PageRank importance — or by relevance to `seeds` (symbol / file
+        ids you're working on). Returns {budget, used_tokens, included, truncated,
+        items:[{id, kind, rank, tokens, text}]}, top hubs first."""
+        return op("pack", {"budget": budget, "seeds": seeds or []})
+
+    return server
+
+
+# tool names registered above (kept in sync for tests / introspection)
+MCP_TOOLS = (
+    "stats", "reload", "search", "query", "resolve", "callers", "callees", "impact",
+    "call_contract", "tests", "covers", "implementers", "family", "families",
+    "column", "columns_of",
+    "accessors",
+    "locate", "review", "architecture", "check", "diff", "communities", "flows", "source", "report",
+    "semantic_search", "pack",
+)

codemap/serve/mermaid.py

@@ -0,0 +1,120 @@
+"""Mermaid diagram views — consumer A/B (DESIGN §4.1-A, M2.3).
+
+Renders scoped subgraphs of the canonical graph as Mermaid text (browsable in
+Obsidian, GitHub, docs):
+
+- ``class`` — class hierarchy from ``inherits`` edges (``classDiagram``);
+- ``deps``  — module dependency graph from ``imports`` edges;
+- ``calls`` — call graph around a root symbol from ``calls`` edges (BFS).
+
+Scoping keeps diagrams legible: ``scope`` filters to an id-prefix subtree; the
+call graph is always rooted with a depth bound (§4.2 — scoped subgraphs).
+"""
+
+from __future__ import annotations
+
+from codemap.query import Query
+
+
+def _san(node_id: str) -> str:
+    """Mermaid-safe node id (dots/brackets break the parser)."""
+    return node_id.replace(".", "_").replace("[", "_").replace("]", "_")
+
+
+def _short(node_id: str) -> str:
+    return node_id.rsplit(".", 1)[-1]
+
+
+def _in_scope(node_id: str, scope: str | None) -> bool:
+    return scope is None or node_id == scope or node_id.startswith(scope + ".")
+
+
+def render_class_diagram(query: Query, scope: str | None = None) -> str:
+    """Class hierarchy as a Mermaid ``classDiagram``.
+
+    ``inherits`` edges render as inheritance (``<|--``); ``implements`` edges
+    (M9/F4 — registry-family members → Protocol, never inherited) render as
+    realization (``<|..``), so a strategy family is no longer an empty diagram.
+    """
+    graph = query.graph
+    inh = sorted({(e.source, e.target) for e in graph.edges if e.type == "inherits"})
+    inh = [(s, t) for s, t in inh if _in_scope(s, scope)]
+    impl = sorted({(e.source, e.target) for e in graph.edges if e.type == "implements"})
+    impl = [(s, t) for s, t in impl if _in_scope(s, scope) or _in_scope(t, scope)]
+    nodes = {n for pair in inh + impl for n in pair}
+
+    lines = ["```mermaid", "classDiagram"]
+    for nid in sorted(nodes):
+        lines.append(f'    class {_san(nid)}["{_short(nid)}"]')
+    for sub, base in inh:
+        # Mermaid: Base <|-- Sub  (arrow points from subclass to base)
+        lines.append(f"    {_san(base)} <|-- {_san(sub)}")
+    for cls, proto in impl:
+        # realization: Protocol <|.. Impl
+        lines.append(f"    {_san(proto)} <|.. {_san(cls)}")
+    lines.append("```")
+    return "\n".join(lines) + "\n"
+
+
+def render_dep_graph(query: Query, scope: str | None = None) -> str:
+    """Module dependency graph (``imports`` edges) as a Mermaid flowchart."""
+    graph = query.graph
+    edges = sorted(
+        {(e.source, e.target) for e in graph.edges if e.type == "imports"}
+    )
+    edges = [(s, t) for s, t in edges if _in_scope(s, scope) and _in_scope(t, scope)]
+    nodes = {n for pair in edges for n in pair}
+
+    lines = ["```mermaid", "graph LR"]
+    for nid in sorted(nodes):
+        lines.append(f'    {_san(nid)}["{_short(nid)}"]')
+    for src, tgt in edges:
+        lines.append(f"    {_san(src)} --> {_san(tgt)}")
+    lines.append("```")
+    return "\n".join(lines) + "\n"
+
+
+def render_call_graph(query: Query, root: str, depth: int = 2) -> str:
+    """Call graph reachable from ``root`` within ``depth`` hops (``calls`` edges)."""
+    if root not in query.graph.nodes:
+        matches = query.find(root)
+        if not matches:
+            raise KeyError(f"symbol not found: {root}")
+        root = matches[0].id
+
+    seen = {root}
+    frontier = [root]
+    edges: set[tuple[str, str]] = set()
+    for _ in range(max(depth, 0)):
+        nxt = []
+        for node in frontier:
+            for callee in query.callees(node):
+                edges.add((node, callee))
+                if callee not in seen:
+                    seen.add(callee)
+                    nxt.append(callee)
+        frontier = nxt
+
+    lines = ["```mermaid", "graph LR"]
+    for nid in sorted(seen):
+        marker = ":::root" if nid == root else ""
+        lines.append(f'    {_san(nid)}["{_short(nid)}"]{marker}')
+    for src, tgt in sorted(edges):
+        lines.append(f"    {_san(src)} --> {_san(tgt)}")
+    lines.append("    classDef root fill:#f9f,stroke:#333;")
+    lines.append("```")
+    return "\n".join(lines) + "\n"
+
+
+_KINDS = {"class": render_class_diagram, "deps": render_dep_graph}
+
+
+def render_mermaid(query: Query, kind: str, scope: str | None = None,
+                   root: str | None = None, depth: int = 2) -> str:
+    if kind == "calls":
+        if not root:
+            raise ValueError("mermaid 'calls' needs --root <symbol>")
+        return render_call_graph(query, root, depth)
+    if kind not in _KINDS:
+        raise ValueError(f"unknown mermaid kind: {kind}")
+    return _KINDS[kind](query, scope)

codemap/serve/pack.py

@@ -0,0 +1,93 @@
+"""Token-budgeted context pack (R1-C6) — codemap as a context provider.
+
+codemap answers point queries; this adds the other half an AI-context tool needs:
+*ranking* (what matters most) + a *budgeted render* (fit the most relevant slice of
+the graph into N tokens). Nodes are scored by personalized PageRank
+(:meth:`codemap.query.Query.rank`) — global importance, or relevance to ``seeds``
+you're working on — then rendered highest-rank-first until the token budget is spent.
+
+Token counting is a deterministic, dependency-free heuristic (~4 chars/token, the
+common rule of thumb) — no tokenizer to install, and stable across runs. The pack is
+a *lower bound on relevance, upper bound on size*: it never exceeds the budget, and
+top hubs land before leaves (the acceptance).
+"""
+
+from __future__ import annotations
+
+from codemap.query import Query
+
+# The signals a context consumer wants per symbol, compact. Kept deterministic.
+_KIND_TAG = {"module": "mod", "class": "class", "function": "fn"}
+
+
+def estimate_tokens(text: str) -> int:
+    """Cheap, deterministic token estimate (~4 chars/token); >=1 for any content."""
+    return max(1, len(text) // 4)
+
+
+def _item_text(node) -> str:
+    """One compact context line for a symbol: id, kind, signature, docstring head."""
+    tag = _KIND_TAG.get(node.kind, node.kind)
+    sig = f" {node.signature}" if node.signature else ""
+    doc = ""
+    if node.docstring:
+        first = node.docstring.strip().splitlines()[0].strip()
+        if first:
+            doc = f" — {first}"
+    dep = " [deprecated]" if node.is_deprecated else ""
+    return f"{node.id} ({tag}){sig}{dep}{doc}"
+
+
+def build_pack(query: Query, *, budget: int, seeds=(), root: str | None = None) -> dict:
+    """Rank symbols and greedily pack the most relevant under ``budget`` tokens.
+
+    Returns ``{budget, used_tokens, total_ranked, included, truncated, items}`` where
+    ``items`` is rank-ordered ``[{id, kind, rank, tokens, text}]``. Rank-order iteration
+    means top hubs (or seed-relevant symbols) are included before leaves; an item that
+    would overflow the budget is skipped so smaller relevant items can still fit.
+    """
+    ranked = query.rank(seeds=seeds, root=root)
+    order = sorted(ranked, key=lambda n: (-ranked[n], n))  # rank desc, id tiebreak
+    items: list[dict] = []
+    used = 0
+    truncated = False
+    for nid in order:
+        node = query.graph.nodes.get(nid)
+        if node is None:
+            continue
+        text = _item_text(node)
+        cost = estimate_tokens(text)
+        if used + cost > budget:
+            truncated = True
+            continue  # skip; a later, smaller item may still fit
+        items.append({"id": nid, "kind": node.kind, "rank": ranked[nid],
+                      "tokens": cost, "text": text})
+        used += cost
+    return {
+        "budget": budget,
+        "used_tokens": used,
+        "total_ranked": len(order),
+        "included": len(items),
+        "truncated": truncated,
+        "items": items,
+    }
+
+
+def render_pack(query: Query, *, budget: int, seeds=(), root: str | None = None) -> str:
+    """Human/agent-readable markdown for a budgeted context pack."""
+    p = build_pack(query, budget=budget, seeds=seeds, root=root)
+    seed_note = f" · seeds: {', '.join(seeds)}" if seeds else " · global importance"
+    lines = [
+        f"# Context pack — `{query.graph.target}`{seed_note}",
+        "",
+        f"_{p['included']} / {p['total_ranked']} symbols · "
+        f"{p['used_tokens']} / {p['budget']} tokens"
+        f"{' · truncated (budget reached)' if p['truncated'] else ''}. "
+        "Ranked by PageRank importance; token estimate ≈ 4 chars/token._",
+        "",
+    ]
+    for it in p["items"]:
+        lines.append(f"- {it['text']}")
+    if not p["items"]:
+        lines.append("_nothing fit the budget._")
+    return "\n".join(lines).rstrip() + "\n"