codmap 0.0.4__tar.gz → 0.0.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.4
+Version: 0.0.5
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

{codmap-0.0.4 → codmap-0.0.5}/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.5}/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.5}/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.5}/codemap/extract/griffe_extractor.py

@@ -68,7 +68,28 @@ 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.
+    loaded = getattr(root, "filepath", None)
+    # A namespace package reports a *list* of directories, not one path — the very shape
+    # that once crashed the extractor (issue #4). Handle it here rather than assume.
+    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."
+        )
 
     graph = Graph(target=module_name)
     walk = _Walk()
@@ -516,17 +537,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.5}/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.5}/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.5}/codemap/serve/session.py

@@ -67,6 +67,36 @@ _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 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 +105,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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.4
+Version: 0.0.5
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

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

@@ -100,6 +100,10 @@ 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_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
 tests/test_r1c4_complexity.py

{codmap-0.0.4 → codmap-0.0.5}/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.5"
 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.5/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")

codmap-0.0.5/tests/test_r1c34_signature_kinds.py

@@ -0,0 +1,150 @@
+"""R1-C34 — the stored signature keeps parameter *kind*, so it can be called.
+
+Found while doing R1-C33 (putting the declared signature into the `query` dossier): the
+first test asserted the signature of `def run(target: str, *, retries: int = 3) -> bool`
+and got back `run(target: str, retries: int = 3) -> bool`. The renderer dropped kind
+entirely, and had since M0:
+
+    def f(a, /, b, *args, c: int = 1, **kw)  ->  f(a, b, args = (), c: int = 1, kw = {})
+    def h(*args, **kw)                       ->  h(args = (), kw = {})
+
+Two different failures in one string. The `*` and `/` markers vanish, so a keyword-only
+parameter reads as positional — write the call the signature describes and Python raises
+TypeError. And the variadics come back as ordinary parameters carrying the *runtime*
+default griffe reports (`()` / `{}`), which is not written anywhere in the source: a
+function that accepts anything renders as one taking two optional positionals.
+
+It mattered beyond cosmetics because three consumers read this string as if it were the
+declaration: `report api-surface`, the exports, and `apidiff`, which re-parses it as
+`def <sig>: …`. In `apidiff` the loss silently disabled three of its own rules —
+`has_vararg`, `has_kwarg` and `_Param.keyword_only` could never be true, so "`*args`
+removed" was unreachable, and `def f(a, b)` → `def f(a, *, b)`, which breaks every
+positional caller, was classified as no change at all. The data to catch it had been
+parsed all along and could not be trusted, which is why the rule that reads it lands
+here rather than in its own change.
+
+The strong test in this file is the round-trip: render, re-parse, and compare parameter
+kinds against the source. A signature that does not survive that is not a declaration,
+it is a description of one.
+"""
+
+from __future__ import annotations
+
+import ast
+
+import pytest
+
+from codemap.apidiff import BREAKING, INFO, diff_api
+from codemap.extract import extract
+from codemap.model import Graph, Node
+
+# (source line, expected rendering) — the shapes that carry kind.
+CASES = [
+    ("def plain(a, b=2): ...", "plain(a, b=2)"),
+    ("def annotated(a: int, b: str = 'x') -> bool: ...", "annotated(a: int, b: str = 'x') -> bool"),
+    ("def kwonly(a, *, b=2): ...", "kwonly(a, *, b=2)"),
+    ("def kwonly_required(*, only): ...", "kwonly_required(*, only)"),
+    ("def posonly(a, /): ...", "posonly(a, /)"),
+    ("def posonly_then(a, /, b): ...", "posonly_then(a, /, b)"),
+    ("def variadic(*args, **kw): ...", "variadic(*args, **kw)"),
+    ("def variadic_typed(*args: int, **kw: str) -> None: ...", "variadic_typed(*args: int, **kw: str) -> None"),
+    ("def everything(a, /, b, *args, c: int = 1, **kw) -> None: ...",
+     "everything(a, /, b, *args, c: int = 1, **kw) -> None"),
+    ("def star_then_kwarg(*args, c=1, **kw): ...", "star_then_kwarg(*args, c=1, **kw)"),
+]
+
+
+@pytest.fixture(scope="module")
+def rendered(tmp_path_factory):
+    pkg = tmp_path_factory.mktemp("src") / "pkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("")
+    (pkg / "api.py").write_text("\n".join(src for src, _ in CASES) + "\n")
+    graph = extract(str(pkg))
+    return {n.id.rsplit(".", 1)[-1]: n.signature
+            for n in graph.nodes.values() if n.kind == "function"}
+
+
+def _kinds(sig_or_def: str) -> list[tuple[str, str]]:
+    """(kind, name) per parameter, from a `def` statement."""
+    fn = ast.parse(sig_or_def if sig_or_def.startswith("def ") else f"def {sig_or_def}: ...").body[0]
+    a = fn.args
+    out = [("positional_only", p.arg) for p in a.posonlyargs]
+    out += [("positional_or_keyword", p.arg) for p in a.args]
+    if a.vararg:
+        out.append(("var_positional", a.vararg.arg))
+    out += [("keyword_only", p.arg) for p in a.kwonlyargs]
+    if a.kwarg:
+        out.append(("var_keyword", a.kwarg.arg))
+    return out
+
+
+@pytest.mark.parametrize("src,expected", CASES, ids=[s.split("(")[0][4:] for s, _ in CASES])
+def test_the_signature_renders_as_written(rendered, src, expected):
+    name = src.split("(")[0][len("def "):]
+    assert rendered[name] == expected
+
+
+@pytest.mark.parametrize("src,_expected", CASES, ids=[s.split("(")[0][4:] for s, _ in CASES])
+def test_round_trip_preserves_every_parameter_kind(rendered, src, _expected):
+    """Render → re-parse → the kinds are the source's. This is the property; the exact
+    strings above are only how it happens to be spelled."""
+    name = src.split("(")[0][len("def "):]
+    assert _kinds(rendered[name]) == _kinds(src)
+
+
+@pytest.mark.parametrize("src,_expected", CASES, ids=[s.split("(")[0][4:] for s, _ in CASES])
+def test_every_signature_parses_as_a_def(rendered, src, _expected):
+    """apidiff's contract: it reads the stored string back as `def <sig>: ...`."""
+    name = src.split("(")[0][len("def "):]
+    ast.parse(f"def {rendered[name]}: ...")
+
+
+def test_a_variadic_does_not_acquire_an_invented_default(rendered):
+    """griffe reports `()` / `{}` for *args / **kw — the collection the callee receives,
+    not something written in the source."""
+    assert "= ()" not in rendered["variadic"] and "= {}" not in rendered["variadic"]
+    assert rendered["variadic"] == "variadic(*args, **kw)"
+
+
+def test_accepting_anything_does_not_look_like_two_optional_positionals(rendered):
+    """The old rendering of `def h(*args, **kw)` was `h(args = (), kw = {})` — a
+    different function, and a callable-looking one."""
+    assert _kinds(rendered["variadic"]) == [("var_positional", "args"), ("var_keyword", "kw")]
+
+
+def test_pep8_spacing_annotated_and_bare(rendered):
+    assert "b=2" in rendered["plain"]                       # bare default: no spaces
+    assert "b: str = 'x'" in rendered["annotated"]          # annotated: spaces
+
+
+# -- the consumer that could not see it --------------------------------------
+
+def _g(sig: str) -> Graph:
+    g = Graph(target="pkg")
+    g.add_node(Node(id="pkg.f", kind="function", file="pkg/api.py", signature=sig))
+    return g
+
+
+def test_making_a_parameter_keyword_only_is_breaking():
+    d = diff_api(_g("f(a, b)"), _g("f(a, *, b)"))
+    kinds = {(c.kind, c.severity) for c in d.changes}
+    assert ("param-made-keyword-only", BREAKING) in kinds
+
+
+def test_dropping_the_keyword_only_marker_only_widens():
+    d = diff_api(_g("f(a, *, b)"), _g("f(a, b)"))
+    kinds = {(c.kind, c.severity) for c in d.changes}
+    assert ("param-made-positional", INFO) in kinds
+    assert not any(c.severity == BREAKING for c in d.changes)
+
+
+def test_removing_a_variadic_is_now_reachable():
+    """`has_vararg` was dead: nothing ever rendered a `*`, so it was False on both sides
+    of every real diff."""
+    d = diff_api(_g("f(a, *args)"), _g("f(a)"))
+    assert ("variadic-removed", BREAKING) in {(c.kind, c.severity) for c in d.changes}
+
+
+def test_an_unchanged_signature_is_still_silent():
+    assert diff_api(_g("f(a, /, b, *args, c=1, **kw)"), _g("f(a, /, b, *args, c=1, **kw)")).changes == []