codmap 0.0.4__tar.gz → 0.0.6__tar.gz

{codmap-0.0.4 → codmap-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.4
+Version: 0.0.6
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **732 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.4 → codmap-0.0.6}/README.md

@@ -8,7 +8,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **732 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.4 → codmap-0.0.6}/codemap/apidiff.py

@@ -142,6 +142,21 @@ def _classify_signature(sid: str, old: Node, new: Node) -> list[Change]:
         if old_p is not None and p.required and not old_p.required:
             out.append(Change(sid, "param-made-required", BREAKING,
                               f"parameter `{name}` is now required"))
+    # R1-C34: a parameter that became keyword-only breaks every positional caller,
+    # and the reverse only widens. `_Param.keyword_only` was parsed from the start and
+    # never read — and could not have been trusted anyway: until R1-C34 the renderer
+    # dropped the `*` marker, so every stored signature parsed as if nothing were
+    # keyword-only, and `def f(a, b)` -> `def f(a, *, b)` was a no-op here.
+    for name, p in sn.params.items():
+        old_p = so.params.get(name)
+        if old_p is None:
+            continue
+        if p.keyword_only and not old_p.keyword_only:
+            out.append(Change(sid, "param-made-keyword-only", BREAKING,
+                              f"parameter `{name}` is now keyword-only"))
+        elif old_p.keyword_only and not p.keyword_only:
+            out.append(Change(sid, "param-made-positional", INFO,
+                              f"parameter `{name}` is no longer keyword-only"))
     # variadic removed (*args / **kwargs that existed).
     if so.has_vararg and not sn.has_vararg:
         out.append(Change(sid, "variadic-removed", BREAKING, "`*args` removed"))

{codmap-0.0.4 → codmap-0.0.6}/codemap/arch.py

@@ -33,7 +33,7 @@ of the code.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 
 from codemap.tomlio import read_toml
@@ -56,6 +56,10 @@ class ArchitectureContract:
     no_lazy_cycles: bool = False
     exhaustive: bool = False
     error: str | None = None
+    # R1-C35: the file this contract was looked for in. "No contract found" is only
+    # actionable next to *where* we looked — a reader in the wrong directory cannot tell
+    # an absent contract from a mislocated one, and both exit 0.
+    path: str | None = None
 
     def is_empty(self) -> bool:
         return not (self.layers or self.independent or self.forbidden
@@ -80,10 +84,15 @@ def load_contract(root: str | Path = ".") -> ArchitectureContract:
     file that will not parse is reported through ``error`` rather than being returned as an
     absent contract: a typo used to turn a failing gate green (R1-C27).
     """
-    data, error = read_toml(Path(root) / "codemap.toml")
+    # Absolute on purpose: "not found in codemap.toml" is what the reader already
+    # assumed. The whole value of the line is *which* codemap.toml, so it answers with a
+    # path that is unambiguous from any working directory. (The graph artifact stays free
+    # of absolute paths — D5 — but this is terminal output, not the artifact.)
+    path = Path(root).resolve() / "codemap.toml"
+    data, error = read_toml(path)
     if error:
-        return ArchitectureContract(error=error)
-    return parse_contract(data.get("architecture", {}))
+        return ArchitectureContract(error=error, path=str(path))
+    return replace(parse_contract(data.get("architecture", {})), path=str(path))
 
 
 def parse_contract(section: dict) -> ArchitectureContract:

{codmap-0.0.4 → codmap-0.0.6}/codemap/cli.py

@@ -318,7 +318,14 @@ def _print_query_text(r) -> None:
     print("defined at:", ", ".join(r["defined_at"]) or "—")
     for m in r["matches"]:
         loc = f" — {m['file']}:{m['lines'][0]}" if m.get("file") and m["lines"][0] else ""
-        print(f"  - {m['id']} ({m['kind']}){loc}")
+        dep = " [deprecated]" if m.get("deprecated") else ""
+        print(f"  - {m['id']} ({m['kind']}){loc}{dep}")
+        # R1-C33: the declared shape, on the line below the location. A class shows its
+        # own constructor under that name — not as if the class had a signature.
+        if m.get("signature"):
+            print(f"      {m['signature']}")
+        elif m.get("constructor"):
+            print(f"      constructor: {m['constructor']}")
     for mid, dep in r.get("modules", {}).items():
         print(f"\n[{mid}]")
         print("  imports:", ", ".join(dep["dependencies"]) or "—")

{codmap-0.0.4 → codmap-0.0.6}/codemap/extract/griffe_extractor.py

@@ -54,6 +54,30 @@ class _Walk:
     aliased: list = field(default_factory=list)   # (skipped_id, owner_id)
 
 
+def _assert_is_the_target(loaded, pkg_dir: Path, module_name: str) -> None:
+    """Raise unless what griffe loaded is the directory we were handed (R1-C36).
+
+    Separate from its caller so the decision can be tested on shapes that a single
+    ``search_paths`` entry cannot produce end to end. A **namespace package reports a
+    list** of directories rather than one path — the shape that once crashed the
+    extractor (issue #4) — and a package assembled from several parts is a legitimate
+    hit as long as the requested directory is one of them.
+
+    An empty ``loaded`` is not treated as a mismatch: "griffe told us nothing about the
+    file" is not "griffe told us the wrong file", and inventing a failure from silence
+    is the same error in the other direction.
+    """
+    candidates = loaded if isinstance(loaded, (list, tuple)) else ([loaded] if loaded else [])
+    dirs = {(q if q.is_dir() else q.parent).resolve() for q in map(Path, candidates)}
+    if dirs and pkg_dir not in dirs:
+        raise ValueError(
+            f"resolved `{module_name}` to {', '.join(sorted(str(d) for d in dirs))} but was "
+            f"asked for {pkg_dir}. A same-named package is shadowing the target (an "
+            "installed copy, or one in the current directory). Build from a different "
+            "working directory, or rename the target."
+        )
+
+
 def build_structural(package_path: str | Path):
     """The cheap, deterministic base: griffe load + definition nodes + structural
     edges (contains / imports / inherits / decorated_by / export). No behavioral
@@ -68,7 +92,17 @@ def build_structural(package_path: str | Path):
 
     module_name = pkg_dir.name
     search_path = pkg_dir.parent
-    root = griffe.load(module_name, search_paths=[str(search_path)])
+    # R1-C36: `try_relative_path` (griffe's default) reinterprets the module *name* as a
+    # path relative to the current directory, and that wins over `search_paths`. Run from
+    # a repo whose root holds `pkg/`, `build /elsewhere/pkg` then silently analysed the
+    # local `pkg` — same shape of answer, different code. We always know the directory we
+    # were handed, so the name must resolve through `search_paths` and nowhere else.
+    root = griffe.load(module_name, search_paths=[str(search_path)], try_relative_path=False)
+    # Defence in depth: whatever the finder does next (a .pth file, a namespace package,
+    # a future default), a graph must describe the directory that was asked for. A wrong
+    # answer here is invisible downstream — it is well-formed, complete and about the
+    # wrong tree — so it fails loudly instead.
+    _assert_is_the_target(getattr(root, "filepath", None), pkg_dir, module_name)
 
     graph = Graph(target=module_name)
     walk = _Walk()
@@ -516,17 +550,58 @@ def _registry_binding(obj) -> dict | None:
     return None
 
 
+def _param(p, *, bare: bool = False) -> str:
+    """One parameter, PEP8-spaced: ``x=1`` bare, ``x: int = 1`` annotated.
+
+    ``bare`` is for ``*args`` / ``**kwargs``, where griffe reports a default of
+    ``()`` / ``{}``. That default is the collection the callee receives, not
+    something written in the source, and printing it invents an argument.
+    """
+    s = p.name
+    if p.annotation is not None:
+        s += f": {p.annotation}"
+    if not bare and p.default is not None:
+        s += f" = {p.default}" if p.annotation is not None else f"={p.default}"
+    return s
+
+
 def _signature(obj) -> str | None:
+    """The declared signature, as written — including parameter *kind*.
+
+    R1-C34. The first version of this dropped kind entirely: `*args` came out as a
+    parameter named `args` with a default of `()`, `**kw` as `kw={}`, and both `/`
+    and the bare `*` marker vanished. So `def h(*args, **kw)` — accepts anything —
+    and `def h(args=(), kw={})` — two optional positionals — rendered to the same
+    string, and `def f(a, b)` -> `def f(a, *, b)`, which breaks every positional
+    caller, was invisible to `apidiff` because both sides rendered `f(a, b)`.
+
+    The string is consumed by `report api-surface`, `apidiff` (which re-parses it as
+    `def <sig>: ...`), the exports, and — since R1-C33 — the `query` dossier. All
+    four were reading a signature that could not be called.
+    """
     if obj.kind.value != "function":
         return None
-    parts = []
-    for p in obj.parameters:
-        s = p.name
-        if p.annotation is not None:
-            s += f": {p.annotation}"
-        if p.default is not None:
-            s += f" = {p.default}"
-        parts.append(s)
+    params = list(obj.parameters)
+    kinds = [getattr(p.kind, "name", "positional_or_keyword") for p in params]
+    parts: list[str] = []
+    star = False  # a `*` or `*args` is already in scope, so `*` must not repeat
+    for i, (p, kind) in enumerate(zip(params, kinds)):
+        if kind != "positional_only" and i and kinds[i - 1] == "positional_only":
+            parts.append("/")
+        if kind == "var_positional":
+            parts.append("*" + _param(p, bare=True))
+            star = True
+        elif kind == "var_keyword":
+            parts.append("**" + _param(p, bare=True))
+        elif kind == "keyword_only":
+            if not star:
+                parts.append("*")
+                star = True
+            parts.append(_param(p))
+        else:
+            parts.append(_param(p))
+    if kinds and kinds[-1] == "positional_only":
+        parts.append("/")
     sig = f"{obj.name}({', '.join(parts)})"
     if obj.returns is not None:
         sig += f" -> {obj.returns}"

{codmap-0.0.4 → codmap-0.0.6}/codemap/serve/check.py

@@ -56,6 +56,9 @@ def build_check(query, contract: ArchitectureContract, violations: list[Violatio
         "target": query.graph.target,
         "contract_empty": contract.is_empty(),
         "contract_error": contract.error,
+        # R1-C35: where the contract was looked for. A machine reader of `contract_empty`
+        # has the same "absent or mislocated?" question a human does.
+        "contract_path": contract.path,
         "ok": not violations and contract.error is None,
         "violations": [
             {"rule": v.rule, "summary": v.summary,
@@ -73,14 +76,21 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
     # reported as a contract that does not exist, which is how one missing `]` turned a
     # failing gate green. Nothing was enforced either way — but only one of the two is the
     # user's decision, and the caller exits non-zero on this one.
+    where = f"`{contract.path}`" if contract.path else "`codemap.toml`"
     if contract.error:
         return (f"# Architecture check — `{target}`\n\n"
                 f"❌ **Contract not read — nothing was enforced.** {contract.error}\n\n"
-                "_Fix `codemap.toml` (or remove it) and run again. This is a failure, not "
+                f"_Fix {where} (or remove it) and run again. This is a failure, not "
                 "an absent contract: rules may exist that no rule-check ran against._\n")
     if contract.is_empty():
+        # R1-C35: name the file we looked in, and name the flag that turns this into a
+        # failure. Without the path, a run from the wrong directory is indistinguishable
+        # from a project that has no contract; without the flag, the same output is a
+        # green CI step that enforced nothing.
         return (f"# Architecture check — `{target}`\n\n"
-                "_No `[architecture]` contract found in codemap.toml — nothing to enforce._\n")
+                f"_No `[architecture]` contract found in {where} — nothing to enforce, "
+                "and this exits 0. Use `--require-contract` to make a missing contract a "
+                "failure, or `--root DIR` if the file lives elsewhere._\n")
     if not violations:
         rules = []
         if contract.layers:

{codmap-0.0.4 → codmap-0.0.6}/codemap/serve/mcp_server.py

@@ -121,9 +121,15 @@ def build_mcp_server(session: "Session", name: str = "codemap") -> Any:
 
     @server.tool()
     def query(name: str) -> dict:
-        """Full dossier for a symbol name: where defined (file:line), bases/impls for
+        """Full dossier for a symbol name: where defined (file:line) with the declared
+        `signature` (a class carries its own `constructor` instead), bases/impls for
         classes, callers/callees/columns for functions, registration recipe, column
-        dataflow. The main lookup."""
+        dataflow. The main lookup.
+
+        `signature` is how the symbol is declared; `call_contract` is how it is called
+        in fact (posargs / kwargs / splat per call site) — ask that one for the second
+        question, not for the first. A missing field means the graph has nothing there,
+        never that it was not looked up."""
         return op("query", {"name": name})
 
     @server.tool()

{codmap-0.0.4 → codmap-0.0.6}/codemap/serve/session.py

@@ -67,6 +67,64 @@ _UNLIMITED_BY_DESIGN = {
 }
 
 
+def _match(q: Query, n) -> dict:
+    """One entry of the ``matches`` list: where the symbol is, and how it is declared.
+
+    R1-C33. The question after "where is it" is "how is it called", and the declared
+    signature was already on the node — asking ``call_contract`` for it was a second
+    round-trip for something the graph carried all along. Fields that would say nothing
+    are omitted rather than emitted as ``null``: a caller can tell "no signature here"
+    from "a signature we did not look up" only if the absent case is absent.
+
+    Note the two are different questions and keep different names. ``signature`` is how
+    the symbol is *declared*; ``call_contract`` answers how it is *called in fact*
+    (posargs / kwargs / splat per call site), which no node field can know.
+    """
+    e = {"id": n.id, "kind": n.kind, "file": n.file, "lines": [n.lineno, n.endlineno]}
+    if n.signature:
+        e["signature"] = n.signature
+    elif n.kind == "class":
+        # A class has no signature of its own in the model (only functions get one).
+        # Its constructor answers what a caller standing on the class actually wants,
+        # so it travels under its own name — never dressed up as the class's signature.
+        # Only the class's *own* __init__: an inherited one is not resolved here, and
+        # for that case saying nothing is the honest answer (unknown != none).
+        init = q.graph.nodes.get(f"{n.id}.__init__")
+        if init is not None and init.signature:
+            e["constructor"] = init.signature
+    if n.is_deprecated:
+        e["deprecated"] = True
+    return e
+
+
+def tool_drift(running: str | None, installed: str | None) -> dict | None:
+    """Say when this process is running code the installed distribution has moved past.
+
+    R1-C38. A warm server holds two things that go stale independently: the graph and the
+    **code**. `reload` refreshes the graph, and nothing refreshes the code — a process
+    started before an upgrade keeps answering in the shape it was born with, over a graph
+    that carries everything the new shape needs. Measured, not imagined: a server started
+    before R1-C33 served a freshly rebuilt 0.13 graph and returned dossiers without the
+    `signature` the artifact contained, with nothing in the answer to say why.
+
+    `stats` already separates the graph's schema from the running tool's. This is the same
+    separation one level up, and it is only visible because the version is read from the
+    installed metadata at call time while the code was loaded at import.
+    """
+    if not running or not installed or running == installed:
+        return None
+    return {
+        "code": "tool_restart_needed",
+        "severity": "warning",
+        "running": running,
+        "installed": installed,
+        "consequence": "Answers keep the shape of the running code; `reload` refreshes the "
+                       "graph, never the code.",
+        "message": f"this server is running codemap {running} while {installed} is installed — "
+                   "restart it to serve the installed version.",
+    }
+
+
 def build_query_result(q: Query, name: str) -> dict:
     """The full symbol dossier — shared by ``codemap query`` and warm serve."""
     matches = q.find(name)
@@ -75,8 +133,7 @@ def build_query_result(q: Query, name: str) -> dict:
         "defined_at": q.where_defined(name),
         # F12: carry file:line so an agent can jump to source; the id here is the
         # canonical node (not a re-export), so it also chains into relational ops.
-        "matches": [{"id": n.id, "kind": n.kind, "file": n.file,
-                     "lines": [n.lineno, n.endlineno]} for n in matches],
+        "matches": [_match(q, n) for n in matches],
     }
     modules = [n.id for n in matches if n.kind == "module"]
     if modules:
@@ -238,11 +295,21 @@ class Session:
         # edges from a layout the extractor didn't understand), rather than letting every
         # downstream conclusion silently inherit the emptiness.
         from codemap.diagnostics import diagnostics
-        diags = diagnostics(self.graph)
+        diags = list(diagnostics(self.graph))
+        # R1-C38: the graph is not the only thing that goes stale in a warm server.
+        drift = self._tool_drift()
+        if drift:
+            diags.append(drift)
         if diags:
             out["diagnostics"] = diags
         return out
 
+    @staticmethod
+    def _tool_drift() -> dict | None:
+        import codemap
+        from codemap.provenance import tool_version
+        return tool_drift(getattr(codemap, "__version__", None), tool_version())
+
     def _op_reload(self, args) -> dict:
         """Reload the on-disk artifact into the served graph, without a restart (#3).
 
@@ -268,10 +335,16 @@ class Session:
         self.query = Query(graph)
         self._served_mtime = self._current_mtime()
         after = {"nodes": len(graph.nodes), "edges": len(graph.edges)}
-        return {"reloaded": True, "before": before, "after": after,
-                "changed": before != after,
-                "freshness": freshness(self.graph_path,
-                                       served_mtime=self._served_mtime)}
+        out = {"reloaded": True, "before": before, "after": after,
+               "changed": before != after,
+               "freshness": freshness(self.graph_path,
+                                      served_mtime=self._served_mtime)}
+        # R1-C38: this is the op whose name promises freshness, so it is the op that owes
+        # the caller the half it cannot deliver — the code, which only a restart replaces.
+        drift = self._tool_drift()
+        if drift:
+            out["diagnostics"] = [drift]
+        return out
 
     def _op_query(self, args) -> dict:
         return build_query_result(self.query, args["name"])

{codmap-0.0.4 → codmap-0.0.6}/codmap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.4
+Version: 0.0.6
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **732 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.4 → codmap-0.0.6}/codmap.egg-info/SOURCES.txt

@@ -100,6 +100,12 @@ tests/test_r1c30f1_reexport_calls.py
 tests/test_r1c30f2_check_scope.py
 tests/test_r1c31_path_origin.py
 tests/test_r1c32_report_json.py
+tests/test_r1c33_query_signature.py
+tests/test_r1c34_signature_kinds.py
+tests/test_r1c35_contract_location.py
+tests/test_r1c36_target_resolution.py
+tests/test_r1c37_rule_mutation.py
+tests/test_r1c38_tool_drift.py
 tests/test_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
 tests/test_r1c4_complexity.py

{codmap-0.0.4 → codmap-0.0.6}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # version. README says this plainly, since `pip install codmap` / `import codemap` is a
 # seam a reader will otherwise hit by surprise.
 name = "codmap"
-version = "0.0.4"
+version = "0.0.6"
 description = "Static analyzer that turns a package's source into a queryable code graph."
 readme = "README.md"
 # M20/D1: measured, not assumed. Each release of the declared range runs the full suite in

codmap-0.0.6/tests/test_r1c33_query_signature.py

@@ -0,0 +1,189 @@
+"""R1-C33 — the declared signature travels with the dossier.
+
+Not a defect report: this came from auditing the "what we'd take" list in the CodeGraph
+разбор (`research/tools/codegraph.md`) and finding that three of its four items had been
+closed while item 2 had never been carded at all. It sat for three days as an invisible
+line inside prose, because a list without status reads as done — the same blindness
+R1-C28 is about, turned on our own notes instead of an answer envelope.
+
+The substance is small and one-directional: a caller who has just learned *where* a
+symbol is asks next *how it is called*, and `Node.signature` was already in the graph
+(`serve/api_surface.py` reads it). Getting it meant a second op — `call_contract` — which
+answers a different question.
+
+Two lines this file holds:
+
+* **`signature` (declared) is not `call_contract` (called in fact).** The first is a node
+  field; the second is per-call-site argument shape. Keeping the names apart is the point.
+* **Absent means absent.** A node with nothing to say omits the key rather than emitting
+  `null` — a class has no signature of its own (only functions get one), so it carries its
+  own `__init__` under `constructor`, and an *inherited* constructor is not resolved here.
+  Saying nothing about it is the honest answer (unknown != none), and this file pins that
+  rather than leaving it to be "fixed" later by a guess.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+import pytest
+
+from codemap.extract import extract
+from codemap.query import Query
+from codemap.serve.session import Session, build_query_result
+from codemap.store import save
+
+SRC = {
+    "__init__.py": "",
+    "shapes.py": (
+        '"""Shapes."""\n'
+        "\n"
+        "\n"
+        "class Base:\n"
+        "    def __init__(self, name: str, size: int = 1) -> None:\n"
+        "        self.name = name\n"
+        "        self.size = size\n"
+        "\n"
+        "\n"
+        "class Derived(Base):\n"
+        '    """No __init__ of its own — the constructor is inherited."""\n'
+        "\n"
+        "    def area(self) -> float:\n"
+        "        return 0.0\n"
+    ),
+    "api.py": (
+        '"""Api."""\n'
+        "\n"
+        "from warnings import deprecated\n"
+        "\n"
+        "\n"
+        "def run(target: str, *, retries: int = 3) -> bool:\n"
+        '    """Do the thing."""\n'
+        "    return bool(target) and retries > 0\n"
+        "\n"
+        "\n"
+        "@deprecated('use run')\n"
+        "def run_old(target):\n"
+        "    return run(target)\n"
+    ),
+}
+
+
+@pytest.fixture(scope="module")
+def pkg(tmp_path_factory):
+    root = tmp_path_factory.mktemp("src") / "pkg"
+    root.mkdir()
+    for name, src in SRC.items():
+        (root / name).write_text(src)
+    return root
+
+
+@pytest.fixture(scope="module")
+def graph(pkg):
+    return extract(str(pkg))
+
+
+@pytest.fixture(scope="module")
+def q(graph):
+    return Query(graph)
+
+
+def _match(q, name, node_id=None):
+    ms = build_query_result(q, name)["matches"]
+    if node_id:
+        ms = [m for m in ms if m["id"] == node_id]
+    assert ms, f"no match for {name}"
+    return ms[0]
+
+
+# -- the declared signature --------------------------------------------------
+
+def test_a_function_carries_its_declared_signature(q):
+    m = _match(q, "run")
+    assert m["signature"] == "run(target: str, *, retries: int = 3) -> bool"
+
+
+def test_the_signature_is_the_node_field_not_a_recomputation(q, graph):
+    """If these ever diverge, one of the two is inventing something."""
+    m = _match(q, "run")
+    assert m["signature"] == graph.nodes["pkg.api.run"].signature
+
+
+def test_annotations_and_defaults_survive(q):
+    """The half a caller actually needs: it is not just the parameter names."""
+    sig = _match(q, "run")["signature"]
+    assert ": str" in sig and "retries: int = 3" in sig and "-> bool" in sig
+
+
+# -- absent means absent -----------------------------------------------------
+
+def test_a_module_has_no_signature_key_at_all(q):
+    m = _match(q, "api", node_id="pkg.api")
+    assert m["kind"] == "module"
+    assert "signature" not in m and "constructor" not in m
+
+
+def test_a_class_reports_its_own_constructor_under_its_own_name(q):
+    m = _match(q, "Base")
+    assert m["kind"] == "class"
+    # Never dressed up as the class's signature — the class has none.
+    assert "signature" not in m
+    assert m["constructor"] == "__init__(self, name: str, size: int = 1) -> None"
+
+
+def test_an_inherited_constructor_is_not_claimed(q):
+    """`Derived` has no `__init__` of its own. We do not walk bases to find one, and
+    guessing would be worse than the silence: the honest answer is no field."""
+    m = _match(q, "Derived")
+    assert "constructor" not in m and "signature" not in m
+
+
+def test_no_field_is_ever_null(q):
+    for name in ("run", "Base", "Derived", "api", "area"):
+        for m in build_query_result(q, name)["matches"]:
+            assert m.get("signature", "x") is not None
+            assert m.get("constructor", "x") is not None
+
+
+# -- deprecation, since it is on the same node -------------------------------
+
+def test_a_deprecated_symbol_says_so(q):
+    assert _match(q, "run_old").get("deprecated") is True
+
+
+def test_a_live_symbol_carries_no_deprecated_key(q):
+    assert "deprecated" not in _match(q, "run")
+
+
+# -- one builder: CLI, warm serve and MCP cannot drift apart -----------------
+
+def test_warm_serve_and_the_cli_return_the_same_dossier(graph, q, tmp_path):
+    out = tmp_path / "g.json"
+    save(graph, str(out))
+    cli = subprocess.run([sys.executable, "-m", "codemap.cli", "query", "run",
+                          "--graph", str(out), "--format", "json"],
+                         capture_output=True, text=True)
+    assert cli.returncode == 0, cli.stderr
+    served = Session(graph).handle({"op": "query", "args": {"name": "run"}})
+    assert served["ok"]
+    assert json.loads(cli.stdout)["matches"] == served["result"]["matches"]
+
+
+def test_the_text_form_prints_the_signature_and_labels_a_constructor(graph, tmp_path):
+    out = tmp_path / "g.json"
+    save(graph, str(out))
+
+    def run_text(name):
+        r = subprocess.run([sys.executable, "-m", "codemap.cli", "query", name,
+                            "--graph", str(out), "--format", "text"],
+                           capture_output=True, text=True)
+        assert r.returncode == 0, r.stderr
+        return r.stdout
+
+    text = run_text("run")
+    assert '"signature"' not in text, "this must exercise the text renderer, not json"
+    assert "      run(target: str, *, retries: int = 3) -> bool" in text
+    assert "constructor: __init__(self, name: str, size: int = 1) -> None" in run_text("Base")
+    assert "[deprecated]" in run_text("run_old")