codmap 0.0.20__tar.gz → 0.0.21__tar.gz

{codmap-0.0.20 → codmap-0.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.20
+Version: 0.0.21
 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, **972 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **990 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.20 → codmap-0.0.21}/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, **972 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **990 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.20 → codmap-0.0.21}/codemap/arch.py

@@ -57,6 +57,11 @@ class ArchitectureContract:
     no_lazy_cycles: bool = False
     no_type_only_cycles: bool = False
     exhaustive: bool = False
+    # R1-C62: the mirror of `exhaustive`. That one asks "is every layer of the code
+    # declared?"; this asks "does every declared name exist?". Opt-in, because a contract
+    # written ahead of the code is a documented, legitimate use (see the module docstring)
+    # and failing on it by default would turn that practice red on somebody else's tree.
+    no_phantom_rules: 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
@@ -66,7 +71,8 @@ class ArchitectureContract:
     def is_empty(self) -> bool:
         return not (self.layers or self.independent or self.forbidden
                     or self.no_cycles or self.no_lazy_cycles
-                    or self.no_type_only_cycles or self.exhaustive)
+                    or self.no_type_only_cycles or self.exhaustive
+                    or self.no_phantom_rules)
 
 
 @dataclass(frozen=True)
@@ -117,9 +123,46 @@ def parse_contract(section: dict) -> ArchitectureContract:
         no_lazy_cycles=bool(section.get("no_lazy_cycles", False)),
         no_type_only_cycles=bool(section.get("no_type_only_cycles", False)),
         exhaustive=bool(section.get("exhaustive", False)),
+        no_phantom_rules=bool(section.get("no_phantom_rules", False)),
     )
 
 
+def _graph_layers(query) -> set[str]:
+    """Layer names that exist in the core import graph."""
+    return {query._layer_of(m) for m in query.import_graph.nodes
+            if query.root_of(m) == "core"}
+
+
+def applicability(query, contract: ArchitectureContract) -> dict:
+    """Per-rule *declared* vs *applicable* counts, plus the names that do not exist (R1-C62).
+
+    A rule naming a layer the graph does not contain is **inert by design** — no module, no
+    edge, nothing to break — which is what lets a contract be written ahead of the code. The
+    defect that made this function necessary is not the inertness: it is that the gate
+    counted such a rule as *enforced*, so a renamed layer left a green tick over a rule that
+    could no longer fire.
+
+    Applicability is presence of the **name**, nothing cleverer: `layers` needs the layer,
+    `independent` needs at least two members of the group (one cannot import itself), and
+    `forbidden` needs both ends. Whether a violation is even possible between two existing
+    layers is not asked, and should not be.
+    """
+    present = _graph_layers(query)
+    named = set(contract.layers) | {m for grp in contract.independent for m in grp}
+    named |= {n for pair in contract.forbidden for n in pair}
+    return {
+        "layers": {"declared": len(contract.layers),
+                   "applicable": sum(1 for x in contract.layers if x in present)},
+        "independent": {"declared": len(contract.independent),
+                        "applicable": sum(1 for g in contract.independent
+                                          if len([x for x in g if x in present]) >= 2)},
+        "forbidden": {"declared": len(contract.forbidden),
+                      "applicable": sum(1 for (a, b) in contract.forbidden
+                                        if a in present and b in present)},
+        "absent_names": tuple(sorted(n for n in named if n not in present)),
+    }
+
+
 def _core_layer_edges(query) -> list[tuple[str, str, str, str]]:
     """Cross-layer core→core import edges as (importer, imported, layer_i, layer_j)."""
     ig = query.import_graph
@@ -266,4 +309,18 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 modules=tuple(undeclared),
             ))
 
+    # -- no_phantom_rules: every name the contract mentions must exist -----------
+    # R1-C62, the mirror of `exhaustive`. Off by default on purpose: inert rules are how a
+    # contract gets written ahead of the code. On, it catches the drift the count alone
+    # only *discloses* — a layer renamed while the contract kept guarding the old name.
+    if contract.no_phantom_rules:
+        absent = applicability(query, contract)["absent_names"]
+        if absent:
+            violations.append(Violation(
+                "no_phantom_rules",
+                f"{len(absent)} name(s) in the contract are absent from the graph, "
+                "so the rules naming them cannot apply",
+                modules=absent,
+            ))
+
     return violations

{codmap-0.0.20 → codmap-0.0.21}/codemap/cli.py

@@ -73,6 +73,23 @@ _REPORTS = {
 _REPORT_KINDS = sorted(_REPORTS) + ["impact", "communities", "flows"]  # extra args
 
 
+def _emit_answer(text: str) -> None:
+    """Print a markdown answer with the answer-format trailer (R1-C63).
+
+    One seam rather than a line in every renderer: the renderers stay pure functions of the
+    graph, and there is one place to forget rather than nine. The trailer is what a consumer
+    diffing our output sees when the *shape* of an answer changes deliberately — 0.0.20
+    changed the gate's lines while the graph stayed byte-identical, and on a text diff that
+    looked exactly like the #20 defect, where the text moved between runs of one version. The
+    only thing that told them apart was a message written by hand.
+    """
+    from codemap.model import ANSWER_FORMAT, SCHEMA_VERSION
+    print(text, end="")
+    if not text.endswith("\n"):
+        print()
+    print(f"_answer format {ANSWER_FORMAT} · schema {SCHEMA_VERSION}_")
+
+
 def _graph_from(args):
     if getattr(args, "build", None):
         return extract(args.build, deep=getattr(args, "deep", False))
@@ -507,28 +524,28 @@ def _cmd_report(args) -> int:
     if args.kind == "impact":
         if not args.symbol:
             raise SystemExit("error: report impact needs --symbol <name>")
-        print(render_impact(Query(graph), args.symbol, depth=args.depth,
-                            flow_depth=args.flow_depth), end="")
+        _emit_answer(render_impact(Query(graph), args.symbol, depth=args.depth,
+                        flow_depth=args.flow_depth))
         return 0
     if args.kind in ("communities", "flows"):
         from codemap.serve.subsystems import render_communities, render_flows
         q = Query(graph)
         out = (render_communities(q) if args.kind == "communities"
                else render_flows(q, args.symbol, depth=args.depth))
-        print(out, end="")
+        _emit_answer(out)
         return 0
     if args.kind == "dead-code":
         from codemap.serve.audit import load_dead_code_whitelist
         root = getattr(args, "source_root", None) or os.getcwd()
         whitelist, wl_error = load_dead_code_whitelist(root)
-        print(render_dead_code(Query(graph),
+        _emit_answer(render_dead_code(Query(graph),
                                whitelist=whitelist,
                                min_confidence=args.min_confidence,
-                               whitelist_error=wl_error), end="")
+                               whitelist_error=wl_error))
         return 0
     renderer = _REPORTS[args.kind]
     payload = renderer(graph) if args.kind == "api-surface" else renderer(Query(graph))
-    print(payload, end="")
+    _emit_answer(payload)
     return 0
 
 
@@ -755,13 +772,13 @@ def _cmd_check(args) -> int:
     # would sort an unreadable contract into the success branch of every `if rc == 2` that
     # already exists in someone's pipeline.
     if contract.error:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         return 2
     if contract.is_empty() and args.require_contract:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         raise SystemExit("error: no [architecture] contract found (--require-contract)")
     violations = check_contract(q, contract)
-    print(render_check(q, contract, violations), end="")
+    _emit_answer(render_check(q, contract, violations))
     return 2 if violations else 0
 
 

{codmap-0.0.20 → codmap-0.0.21}/codemap/model.py

@@ -77,6 +77,24 @@ from typing import Any
 #       (they had ``lineno`` alone, so `search` answered a line number with no file).
 SCHEMA_VERSION = "0.13"
 
+# R1-C63: the *answer* has a shape too, and consumers diff it. `SCHEMA_VERSION` versions the
+# artifact; 0.0.20 left the graph byte-identical and changed the architecture report and the
+# gate's lines completely (a cycle answer became a tangle), which on a text diff is
+# indistinguishable from the #20 defect — where the text moved between runs of one version,
+# without anyone deciding it. The only thing that told the consumer apart was a message I
+# wrote by hand.
+#
+# Bump on a change to the **structure a consumer sees**: a block appears or vanishes, a
+# counted unit changes meaning, a verdict or heading changes shape, a field in a structured
+# answer changes type or semantics. Do **not** bump for wording, typos or added prose inside
+# an existing note — a version that ticks on whitespace stops being read, which is worse than
+# not having one. Independent of SCHEMA_VERSION by design: the graph can be identical while
+# this moves, and that is the case it exists for.
+#
+# Starts at 1 with 0.0.21 and makes no claim about earlier releases: the answer format changed
+# many times before it, and numbering that retroactively would be inventing a history.
+ANSWER_FORMAT = 1
+
 # Closed vocabulary of edge types (R1-C7). Node ``kind`` is deliberately an OPEN set
 # (DESIGN §2 — new entity kinds may appear), but edges are TYPED: every relationship
 # codemap emits is one of these, each with a fixed meaning. This is the machine-

{codmap-0.0.20 → codmap-0.0.21}/codemap/serve/check.py

@@ -8,7 +8,7 @@ mechanical.
 
 from __future__ import annotations
 
-from codemap.arch import ArchitectureContract, Violation
+from codemap.arch import ArchitectureContract, Violation, applicability
 
 _EDGE_CAP = 25   # offending edges listed per rule before "+N more"
 
@@ -54,6 +54,44 @@ def _not_judged(query, contract: ArchitectureContract) -> list[dict]:
     }]
 
 
+def _applicability_payload(query, contract: ArchitectureContract) -> dict:
+    """``applicability`` with its list of absent names as a plain list (JSON-friendly)."""
+    a = applicability(query, contract)
+    return {**{k: v for k, v in a.items() if k != "absent_names"},
+            "absent_names": list(a["absent_names"])}
+
+
+def _phantom_note(a: dict, contract: ArchitectureContract) -> str:
+    """Name the contract names the graph does not have (R1-C62), or say nothing.
+
+    Silent when there are none — a note on every clean run is noise, and this text is
+    diffed by consumers. Silent too when ``no_phantom_rules`` is enforced: then the
+    violation has already said it, and saying it twice reads as two findings.
+    """
+    absent = a["absent_names"]
+    if not absent or contract.no_phantom_rules:
+        return ""
+    names = ", ".join(f"`{n}`" for n in absent)
+    return (f"\n_{len(absent)} name(s) in this contract are absent from the graph — {names} — "
+            "so the rules naming them could not apply; they are counted as *declared*, not as "
+            "*applicable*, above. A contract may legitimately be written ahead of the code; "
+            "if a missing name means drift instead, `no_phantom_rules = true` makes it a "
+            "failure._\n")
+
+
+def _rule_count(name: str, a: dict) -> str:
+    """``layered (7)`` when every declared name exists, ``layered (7 declared, 5 applicable)``
+    when it does not (R1-C62).
+
+    The count only grows a second half where there is something to disclose. Printing both
+    numbers always would move the text of every green run on every tree for zero
+    information — and this line is diffed by consumers.
+    """
+    key = {"layered": "layers"}.get(name, name)
+    dec, app = a[key]["declared"], a[key]["applicable"]
+    return f"{name} ({dec})" if dec == app else f"{name} ({dec} declared, {app} applicable)"
+
+
 def build_check(query, contract: ArchitectureContract, violations: list[Violation]) -> dict:
     """Structured result: ok flag + violations with their concrete edges.
 
@@ -73,6 +111,11 @@ def build_check(query, contract: ArchitectureContract, violations: list[Violatio
         # has the same "absent or mislocated?" question a human does.
         "contract_path": contract.path,
         "ok": not violations and contract.error is None,
+        # R1-C62: declared vs applicable per rule, and the names that do not exist. Always
+        # present while a contract is readable — a consumer cannot tell "nothing phantom"
+        # from "this build does not report it" if the field comes and goes (R1-C28).
+        "applicability": (None if contract.is_empty() or contract.error
+                          else _applicability_payload(query, contract)),
         "violations": [
             {"rule": v.rule, "summary": v.summary,
              "edges": [list(e) for e in v.edges],
@@ -109,13 +152,14 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
         # rule that ran and stayed silent is the R1-C30-f2 defect from the other side —
         # there the reader concluded more than was checked, here less. `tests/
         # test_r1c49_type_only_cycles.py` fails if a new rule is added and not listed.
+        appl = applicability(query, contract)
         rules = []
         if contract.layers:
-            rules.append(f"layered ({len(contract.layers)})")
+            rules.append(_rule_count("layered", appl))
         if contract.independent:
-            rules.append(f"independent ({len(contract.independent)})")
+            rules.append(_rule_count("independent", appl))
         if contract.forbidden:
-            rules.append(f"forbidden ({len(contract.forbidden)})")
+            rules.append(_rule_count("forbidden", appl))
         if contract.no_cycles:
             rules.append("no_cycles")
         if contract.no_lazy_cycles:
@@ -124,9 +168,11 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
             rules.append("no_type_only_cycles")
         if contract.exhaustive:
             rules.append("exhaustive")
+        if contract.no_phantom_rules:
+            rules.append("no_phantom_rules")
         return (f"# Architecture check — `{target}`\n\n"
                 f"✅ **Contract satisfied.** Rules enforced: {', '.join(rules)}.\n"
-                + _render_scope(query, contract))
+                + _phantom_note(appl, contract) + _render_scope(query, contract))
 
     out = [f"# Architecture check — `{target}`", "",
            f"❌ **{len(violations)} rule(s) broken.**", ""]
@@ -141,7 +187,9 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
         for m in v.modules:
             out.append(f"- {m}")
         out.append("")
-    return "\n".join(out).rstrip() + "\n" + _render_scope(query, contract)
+    return ("\n".join(out).rstrip() + "\n"
+            + _phantom_note(applicability(query, contract), contract)
+            + _render_scope(query, contract))
 
 
 def _render_scope(query, contract: ArchitectureContract) -> str:

{codmap-0.0.20 → codmap-0.0.21}/codemap/serve/session.py

@@ -14,7 +14,8 @@ from __future__ import annotations
 
 from collections import Counter
 
-from codemap.model import SCHEMA_VERSION, SPLICED_EDGE_TYPES as _SPLICED_EDGE_TYPES, Graph
+from codemap.model import (ANSWER_FORMAT, SCHEMA_VERSION,
+                           SPLICED_EDGE_TYPES as _SPLICED_EDGE_TYPES, Graph)
 from codemap.query import Query
 from codemap.serve.api_surface import render_api_surface
 from codemap.serve.architecture import build_architecture, render_architecture
@@ -397,7 +398,11 @@ class Session:
         self._filter = None
         self._scope = None
         try:
-            env = {"ok": True, "result": fn(self, args)}
+            env = {"ok": True, "result": fn(self, args),
+                   # R1-C63: the shape of this answer, versioned independently of the
+                   # graph's schema. Always present — a field that appears only when
+                   # something changed cannot be read by a machine (R1-C28).
+                   "answer_format": ANSWER_FORMAT}
         except Exception as exc:  # a bad arg must not kill the resident process
             return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
         r = self._resolution

{codmap-0.0.20 → codmap-0.0.21}/codmap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.20
+Version: 0.0.21
 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, **972 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **990 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.20 → codmap-0.0.21}/codmap.egg-info/SOURCES.txt

@@ -129,6 +129,8 @@ tests/test_r1c56_stub_files.py
 tests/test_r1c57_facade_package.py
 tests/test_r1c58_cycle_tangles.py
 tests/test_r1c5_apidiff.py
+tests/test_r1c62_phantom_rules.py
+tests/test_r1c63_answer_format.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py
 tests/test_r1c8_deadcode.py

{codmap-0.0.20 → codmap-0.0.21}/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.20"
+version = "0.0.21"
 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.21/tests/test_r1c62_phantom_rules.py

@@ -0,0 +1,167 @@
+"""R1-C62 — a rule with nothing to cover was counted as enforced.
+
+Measured on a two-layer package (`api`, `core`) with a contract in which every name is
+fictional:
+
+    layers = ["frontend", "middleware", "persistence"]
+    independent = [["frontend", "middleware"]]
+    forbidden = [{ from = "middleware", to = "persistence" }]
+
+    ✅ Contract satisfied. Rules enforced: layered (3), independent (1), forbidden (1), no_cycles.
+    exit 0
+
+Six rules reported as enforced; five of them cannot fire. The inertness itself is **not** the
+defect — it is a documented decision (`codemap/arch.py`: rules naming an absent layer are
+inert, so a contract can be written ahead of the code), and breaking it would turn a
+legitimate practice red on other people's trees. The defect is the report: "Rules enforced:
+layered (3)" is a claim of fact and it is false, and the green tick reads as coverage. R1-C28's
+family — a rule covering nothing is partiality, and partiality must be declared.
+
+The question came from outside: a third-party repo about requirements that stop being true
+(`research/05_curated_sources.md` §4a). Design: `docs/design/vacuous_contract_rules.md`.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codemap.arch import applicability, check_contract, parse_contract
+from codemap.extract import extract
+from codemap.query import Query
+from codemap.serve.check import build_check, render_check
+
+PHANTOM = {
+    "layers": ["frontend", "middleware", "persistence"],
+    "independent": [["frontend", "middleware"]],
+    "forbidden": [{"from": "middleware", "to": "persistence"}],
+    "no_cycles": True,
+}
+HEALTHY = {
+    "layers": ["api", "core"],
+    "forbidden": [{"from": "core", "to": "api"}],
+    "no_cycles": True,
+    "exhaustive": True,
+}
+
+
+@pytest.fixture(scope="module")
+def two_layers(tmp_path_factory):
+    """`api` imports `core`; nothing else. Layers present: exactly `api` and `core`."""
+    pkg = tmp_path_factory.mktemp("r1c62") / "pkg"
+    (pkg / "core").mkdir(parents=True)
+    (pkg / "api").mkdir()
+    (pkg / "__init__.py").write_text("")
+    (pkg / "core" / "__init__.py").write_text("")
+    (pkg / "core" / "util.py").write_text("def helper():\n    return 1\n")
+    (pkg / "api" / "__init__.py").write_text("")
+    (pkg / "api" / "route.py").write_text(
+        "from pkg.core.util import helper\n\n\ndef handler():\n    return helper()\n")
+    return Query(extract(str(pkg)))
+
+
+def _render(query, section):
+    contract = parse_contract(section)
+    return contract, render_check(query, contract, check_contract(query, contract))
+
+
+# -- D1: applicability is counted, and disclosed only when it differs --------------------
+
+def test_a_phantom_rule_is_not_counted_as_applicable(two_layers):
+    _, md = _render(two_layers, PHANTOM)
+    assert "layered (3 declared, 0 applicable)" in md
+    assert "independent (1 declared, 0 applicable)" in md
+    assert "forbidden (1 declared, 0 applicable)" in md
+
+
+def test_the_absent_names_are_named(two_layers):
+    _, md = _render(two_layers, PHANTOM)
+    for name in ("frontend", "middleware", "persistence"):
+        assert f"`{name}`" in md
+    assert "could not apply" in md
+    assert "no_phantom_rules = true" in md, "the note points at the opt-in"
+
+
+def test_a_healthy_contract_does_not_move_a_byte(two_layers):
+    """The control, and the reason the second half is conditional: this text is diffed by
+    consumers, so a green run on a sound contract must read exactly as before."""
+    _, md = _render(two_layers, HEALTHY)
+    assert "Rules enforced: layered (2), forbidden (1), no_cycles, exhaustive." in md
+    assert "applicable" not in md
+    assert "absent from the graph" not in md
+
+
+def test_applicability_is_precise_about_partial_names(two_layers):
+    """One end present is not enough: `independent` needs two members, `forbidden` two ends."""
+    a = applicability(two_layers, parse_contract({
+        "layers": ["api", "core", "ghost"],
+        "independent": [["api", "ghost"], ["api", "core"]],
+        "forbidden": [{"from": "api", "to": "ghost"}, {"from": "api", "to": "core"}],
+    }))
+    assert a["layers"] == {"declared": 3, "applicable": 2}
+    assert a["independent"] == {"declared": 2, "applicable": 1}
+    assert a["forbidden"] == {"declared": 2, "applicable": 1}
+    assert a["absent_names"] == ("ghost",)
+
+
+# -- D2: turning a phantom into a failure is opt-in --------------------------------------
+
+def test_the_opt_in_makes_it_a_violation(two_layers):
+    contract = parse_contract({**PHANTOM, "no_phantom_rules": True})
+    violations = check_contract(two_layers, contract)
+    assert [v.rule for v in violations] == ["no_phantom_rules"]
+    assert violations[0].modules == ("frontend", "middleware", "persistence")
+
+
+def test_the_opt_in_is_silent_on_a_sound_contract(two_layers):
+    """Positive control: the rule must not fire where every name exists."""
+    contract = parse_contract({**HEALTHY, "no_phantom_rules": True})
+    assert check_contract(two_layers, contract) == []
+
+
+def test_the_note_is_not_repeated_when_the_rule_is_enforced(two_layers):
+    _, md = _render(two_layers, {**PHANTOM, "no_phantom_rules": True})
+    assert "`no_phantom_rules`" in md, "the violation says it"
+    assert "could not apply; they are counted" not in md, "and the note does not say it again"
+
+
+def test_off_by_default(two_layers):
+    """A contract that does not ask for it keeps exiting 0 on phantoms — the documented
+    write-ahead use must not become red on an upgrade."""
+    contract = parse_contract(PHANTOM)
+    assert contract.no_phantom_rules is False
+    assert check_contract(two_layers, contract) == []
+
+
+# -- D3: the structured answer carries it too --------------------------------------------
+
+def test_the_payload_carries_applicability(two_layers):
+    contract = parse_contract(PHANTOM)
+    payload = build_check(two_layers, contract, check_contract(two_layers, contract))
+    a = payload["applicability"]
+    assert a["layers"] == {"declared": 3, "applicable": 0}
+    assert a["absent_names"] == ["frontend", "middleware", "persistence"]
+    assert payload["ok"] is True, "disclosure is not a failure by itself"
+
+
+def test_the_payload_declares_it_on_a_sound_contract_too(two_layers):
+    """R1-C28: a field that appears only when there is something to say cannot be read —
+    a machine consumer could not tell "nothing phantom" from "this build does not report it"."""
+    contract = parse_contract(HEALTHY)
+    a = build_check(two_layers, contract, check_contract(two_layers, contract))["applicability"]
+    assert a is not None and a["absent_names"] == []
+    assert a["layers"] == {"declared": 2, "applicable": 2}
+
+
+# -- the semantics did not change --------------------------------------------------------
+
+def test_a_real_violation_still_fires_next_to_phantoms(two_layers):
+    """Phantom names must not shadow a rule that *can* fire: `core` importing `api` is
+    still caught while three fictional layers sit in the same contract."""
+    contract = parse_contract({
+        "layers": ["core", "api", "ghost"],          # deliberately inverted: api → core is "up"
+        "forbidden": [{"from": "ghost", "to": "api"}],
+        "no_cycles": True,
+    })
+    violations = check_contract(two_layers, contract)
+    assert [v.rule for v in violations] == ["layered"]
+    assert violations[0].edges == (("pkg.api.route", "pkg.core.util"),)

codmap-0.0.21/tests/test_r1c63_answer_format.py

@@ -0,0 +1,148 @@
+"""R1-C63 — the artifact is versioned; the answer, which is what consumers diff, was not.
+
+`SCHEMA_VERSION` versions `graph.json`. In 0.0.20 the graph stayed byte-identical and the gate's
+output and the architecture report changed completely — a cycle answer became a tangle. On a text
+diff that is indistinguishable from the #20 defect, where the rendered text moved *between runs of
+one version* because of hash order, and nobody had decided anything. One was a deliberate change
+of shape, the other a bug; the only thing that told the consumer apart was a message written by
+hand.
+
+So the answer gets its own version, independent of the schema: bumped when the structure a
+consumer sees changes, not when prose is edited. Two surfaces, one per consumer — a one-line
+trailer on CLI markdown (what a text diff shows) and `answer_format` in the serve/MCP envelope
+(what a machine reads).
+
+The pinned hash below is the other half: it does not know whether a text change is structural —
+that judgement cannot be automated — it only refuses to let one pass **silently**. Design:
+`docs/design/answer_format_version.md`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+import pytest
+
+from codemap.arch import check_contract, parse_contract
+from codemap.cli import main
+from codemap.extract import extract
+from codemap.model import ANSWER_FORMAT, SCHEMA_VERSION
+from codemap.query import Query
+from codemap.serve.api_surface import render_api_surface
+from codemap.serve.architecture import render_architecture
+from codemap.serve.audit import render_behavior, render_dead_code, render_dependencies
+from codemap.serve.check import render_check
+from codemap.serve.session import Session
+
+# Bump together with ANSWER_FORMAT when a change of answer *structure* is intended.
+# The fixture is owned by this test on purpose: pinned against the live dogfood tree the hash
+# would move whenever somebody edits that tree, and the test would be measuring the target
+# instead of the tool (R1-C25 — the mistake `tests/frozen.py` exists to prevent).
+RENDERED_SHA = "980ee1b8a07b8b0f8d6f08d707035f4af9b3b568a1526493719c0e57d9c28ba0"
+
+FILES = {
+    "__init__.py": "",
+    "core/__init__.py": "",
+    "core/util.py": "def helper():\n    return 1\n\n\ndef unused():\n    return 2\n",
+    "api/__init__.py": "",
+    "api/route.py": ("from pkg.core.util import helper\n\n\n"
+                     "class Handler:\n"
+                     "    def run(self, n: int) -> int:\n"
+                     "        return helper() + n\n"),
+}
+CONTRACT = {"layers": ["api", "core"], "no_cycles": True, "exhaustive": True}
+
+
+@pytest.fixture(scope="module")
+def pkg(tmp_path_factory):
+    root = tmp_path_factory.mktemp("r1c63") / "pkg"
+    for rel, body in FILES.items():
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body)
+    return Query(extract(str(root)))
+
+
+def _rendered(query) -> str:
+    """Every markdown surface a consumer reads, concatenated in a fixed order."""
+    contract = parse_contract(CONTRACT)
+    return "\n@@\n".join([
+        render_check(query, contract, check_contract(query, contract)),
+        render_architecture(query),
+        render_api_surface(query.graph),
+        render_dead_code(query),
+        render_dependencies(query),
+        render_behavior(query),
+    ])
+
+
+# -- the version itself ------------------------------------------------------------------
+
+def test_the_answer_format_is_its_own_version(pkg):
+    assert isinstance(ANSWER_FORMAT, int) and ANSWER_FORMAT >= 1
+    assert ANSWER_FORMAT != SCHEMA_VERSION, "two different facts, two different fields"
+
+
+def test_the_envelope_carries_it_on_every_answer(pkg):
+    """Machine-readable half, and always present: a field that appears only when something
+    changed cannot be read (R1-C28)."""
+    session = Session(pkg.graph)
+    for op, args in (("stats", {}), ("architecture", {}), ("query", {"name": "helper"})):
+        env = session.handle({"op": op, "args": args})
+        assert env["answer_format"] == ANSWER_FORMAT, op
+
+
+# -- the CLI trailer ---------------------------------------------------------------------
+
+def test_the_cli_trailer_names_both_versions(pkg, tmp_path, capsys, monkeypatch):
+    from codemap import store
+    out = tmp_path / "g.json"
+    store.save(pkg.graph, str(out))
+    monkeypatch.chdir(tmp_path)                      # no codemap.toml here: empty contract
+    assert main(["check", "--graph", str(out)]) == 0
+    tail = capsys.readouterr().out.rstrip().splitlines()[-1]
+    assert tail == f"_answer format {ANSWER_FORMAT} · schema {SCHEMA_VERSION}_"
+
+
+def test_the_trailer_is_on_reports_too(pkg, tmp_path, capsys):
+    from codemap import store
+    out = tmp_path / "g.json"
+    store.save(pkg.graph, str(out))
+    main(["report", "architecture", "--graph", str(out)])
+    assert capsys.readouterr().out.rstrip().endswith(
+        f"_answer format {ANSWER_FORMAT} · schema {SCHEMA_VERSION}_")
+
+
+def test_json_output_has_no_trailer(pkg, tmp_path, capsys):
+    """The trailer is presentation. A `--format json` answer must stay parseable."""
+    from codemap import store
+    out = tmp_path / "g.json"
+    store.save(pkg.graph, str(out))
+    main(["report", "architecture", "--graph", str(out), "--format", "json"])
+    json.loads(capsys.readouterr().out)              # raises if a trailer leaked in
+
+
+# -- the guard that makes a silent change impossible --------------------------------------
+
+def test_rendered_answers_match_the_pin(pkg):
+    """Six markdown surfaces over a fixture this test owns, hashed.
+
+    This does not decide whether a change is structural — that judgement is a human's, and
+    pretending to automate it would be the R1-C37 defect in a new place. It only refuses to let
+    the shape of an answer move **silently**.
+    """
+    got = hashlib.sha256(_rendered(pkg).encode()).hexdigest()
+    assert got == RENDERED_SHA, (
+        "the rendered answers changed.\n"
+        "  • intended change of structure? bump ANSWER_FORMAT in codemap/model.py, update\n"
+        "    RENDERED_SHA here in the same commit, and say so in the release note\n"
+        "  • only wording? update RENDERED_SHA alone — the version is about structure\n"
+        "  • neither? this is a regression, and the pin just caught it\n"
+        f"  expected {RENDERED_SHA}\n  got      {got}")
+
+
+def test_the_pin_is_over_a_fixture_this_test_owns(pkg):
+    """Positive control for the pin: it must not be hashing the live dogfood tree."""
+    assert pkg.graph.target == "pkg"
+    assert len(pkg.graph.nodes) < 40, "a fixture, not a real package"