codmap 0.0.17__tar.gz → 0.0.18__tar.gz

{codmap-0.0.17 → codmap-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.17
+Version: 0.0.18
 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, **765 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **938 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.17 → codmap-0.0.18}/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, **765 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **938 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.17 → codmap-0.0.18}/codemap/query.py

@@ -21,6 +21,25 @@ def _grade_rank(grade: str | None) -> int:
     return CONFIDENCE_ORDER.index(grade) if grade in CONFIDENCE_ORDER else len(CONFIDENCE_ORDER)
 
 
+def _canonical_cycles(cycles) -> list[list[str]]:
+    """Cycles in a stable form: each rotated to start at its smallest node, then sorted.
+
+    R1-C54, reported by the lab as [issue #20](https://github.com/kogriv/codemap/issues/20).
+    ``nx.simple_cycles`` yields a cycle starting wherever its traversal happened to enter
+    it, and that traversal follows set-iteration order, i.e. string hashes. The chain is
+    the *same cycle* either way — but three consumers print it, and they printed three
+    different texts for one graph across eight hash seeds.
+
+    The sort afterwards is the point of the rotation: ``arch.py`` already sorted cycles by
+    ``(len, c)`` and that looked like canonicalisation, except the key itself moved with
+    the rotation — ``["a","b"]`` and ``["b","a"]`` are one cycle and two keys. Rotating
+    first makes the existing sort mean what it appeared to mean.
+    """
+    out = [c[i:] + c[:i] for c in (list(x) for x in cycles)
+           if (i := c.index(min(c))) >= 0]
+    return sorted(out, key=lambda c: (len(c), c))
+
+
 def _check_grade(min_confidence: str | None) -> None:
     if min_confidence is not None and min_confidence not in CONFIDENCE_ORDER:
         raise ValueError(f"min_confidence must be one of {CONFIDENCE_ORDER}, "
@@ -1069,7 +1088,7 @@ class Query:
         would report someone's fix as their bug. Those cycles are still real coupling
         and are returned by :meth:`lazy_import_cycles`.
         """
-        return [c for c in nx.simple_cycles(self._imports_eager)]
+        return _canonical_cycles(nx.simple_cycles(self._imports_eager))
 
     def lazy_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** through a function-local import.
@@ -1087,8 +1106,8 @@ class Query:
         them, or a tree could hide real coupling by adding one.
         """
         eager = {frozenset(c) for c in nx.simple_cycles(self._imports_eager)}
-        return [c for c in nx.simple_cycles(self._imports_runtime)
-                if frozenset(c) not in eager]
+        return _canonical_cycles(c for c in nx.simple_cycles(self._imports_runtime)
+                                 if frozenset(c) not in eager)
 
     def type_only_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** with an import under ``if TYPE_CHECKING:``.
@@ -1100,7 +1119,8 @@ class Query:
         opt-in rule instead.
         """
         runtime = {frozenset(c) for c in nx.simple_cycles(self._imports_runtime)}
-        return [c for c in nx.simple_cycles(self._imports) if frozenset(c) not in runtime]
+        return _canonical_cycles(c for c in nx.simple_cycles(self._imports)
+                                 if frozenset(c) not in runtime)
 
     def import_map(self) -> dict:
         """How much of the import graph each scope contributed (R1-C29).

{codmap-0.0.17 → codmap-0.0.18}/codemap/serve/mermaid.py

@@ -117,4 +117,16 @@ def render_mermaid(query: Query, kind: str, scope: str | None = None,
         return render_call_graph(query, root, depth)
     if kind not in _KINDS:
         raise ValueError(f"unknown mermaid kind: {kind}")
-    return _KINDS[kind](query, scope)
+    out = _KINDS[kind](query, scope)
+    if scope:
+        # R1-C53: `--scope` cut this diagram from 144 lines to 47 on the dogfood tree with
+        # no marker of any kind, so the picture read as "the class diagram of this package".
+        # A diagram is an answer too. Mermaid ignores `%%` lines, so the note costs nothing
+        # rendered and is visible in the source a reader diffs or pastes.
+        hidden = len(_KINDS[kind](query, None).splitlines()) - len(out.splitlines())
+        note = (f"%% scope: {scope} — {hidden} further line(s) exist in the unscoped "
+                "diagram of this graph")
+        lines = out.splitlines()
+        at = 1 if lines and lines[0].startswith("```") else 0
+        out = "\n".join(lines[:at] + [note] + lines[at:]) + "\n"
+    return out

{codmap-0.0.17 → codmap-0.0.18}/codemap/serve/session.py

@@ -50,6 +50,15 @@ _REPORTS = {
 #                     jedi sample (R1-C43).
 # `accessors` used to be in neither — it reads `accesses`, modelled best-effort, and
 # carried no `epistemic` at all (found by the R1-C44 measurement).
+# R1-C53 added the three column ops: they read `reads`/`writes`, which are an **over-set**
+# rather than a lower bound — a different partiality, so it gets its own reason below.
+#
+# `query` was considered here and deliberately left out. Its dossier *does* carry
+# call-derived fields, but most of it — where the symbol is defined, its signature, its
+# file — is exact, and one envelope-wide "this is a lower bound" would say the definition
+# is uncertain too. The rule this file already states is "absence of the label means
+# exact", so a **mixed** answer declares per field (see `_op_query`), not per envelope.
+# Over-claiming partiality is the same defect as hiding it, pointed the other way.
 _OP_EDGE_CLASSES = {
     "callers": frozenset({"calls"}),
     "callees": frozenset({"calls"}),
@@ -59,10 +68,19 @@ _OP_EDGE_CLASSES = {
     "accessors": frozenset({"accesses"}),
     "tests": frozenset({"calls", "references"}),
     "covers": frozenset({"calls", "references"}),
+    "column": frozenset({"reads", "writes"}),
+    "columns": frozenset({"reads", "writes"}),
+    "columns_of": frozenset({"reads", "writes"}),
 }
 _BEST_EFFORT_CLASSES = frozenset({"calls", "accesses"})
+#: Classes that are an over-set, not a lower bound: a literal subscript key cannot be told
+#: from a dict key, so the column set contains more than the DataFrame columns (F15/M12).
+#: The opposite error from `_BEST_EFFORT_CLASSES`, and it must not borrow its wording.
+_OVER_SET_CLASSES = frozenset({"reads", "writes"})
 _PARTIAL_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
-                         if cls & _BEST_EFFORT_CLASSES)
+                         if cls & (_BEST_EFFORT_CLASSES | _OVER_SET_CLASSES))
+_OVER_SET_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
+                          if cls & _OVER_SET_CLASSES)
 _SPLICE_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
                         if cls & _SPLICED_EDGE_TYPES)
 _EPISTEMIC_PARTIAL = {
@@ -70,6 +88,15 @@ _EPISTEMIC_PARTIAL = {
     "reason": "leans on static resolution of calls and attribute accesses (partial "
               "for Python) — a lower bound; pair with grep/tests before acting.",
 }
+# R1-C53: the over-set is partial in the *other* direction, and saying "a lower bound"
+# about it would be worse than saying nothing. A caller that trims by this set would trim
+# too little, not too much.
+_EPISTEMIC_OVER_SET = {
+    "epistemic": "partial",
+    "reason": "string-keyed dataflow is an **over-set**, not a lower bound: a literal "
+              "subscript key cannot be told from a dict key, so this set contains more "
+              "than the DataFrame columns. Confirm a key before acting on it.",
+}
 # D4 — the second reason, named separately: "a lower bound by static resolution" and
 # "part of this graph was carried over, not recomputed" are different facts.
 _EPISTEMIC_SPLICE = (
@@ -118,6 +145,24 @@ _UNLIMITED_BY_DESIGN = {
 }
 
 
+def _root_scope(query: Query, root: str, judged: list) -> dict:
+    """The `scope` block: which provenance root the answer covers, and what it leaves out.
+
+    R1-C53. `communities` judges the package and is silent about it; on a repo-scoped graph
+    a caller reads "9 subsystems" without learning that `tests` was never considered. Same
+    shape as `check`'s "not judged" line and `diff`'s root filter, now stated in one place.
+    """
+    others: dict[str, int] = {}
+    for n in query.graph.nodes.values():
+        if n.kind != "module":
+            continue
+        r = query.root_of(n.id)
+        if r != root:
+            others[r] = others.get(r, 0) + 1
+    return {"root": root, "judged": len(judged),
+            "not_judged": dict(sorted(others.items()))}
+
+
 def _grade_filter(min_confidence, every: list, kept: list, grades: dict) -> dict:
     """The `filter` block: what the route-grade filter kept, dropped, and out of what.
 
@@ -257,6 +302,17 @@ def build_query_result(q: Query, name: str) -> dict:
                     used_by[n.id] = by_root
         if used_by:
             result["used_by"] = used_by
+            # R1-C53: the dossier is *mixed* — `defined_at`, `matches` and the signatures
+            # are exact, while `used_by` comes from the same best-effort call/reference
+            # layer that makes `callers` a lower bound. An envelope-wide `epistemic` would
+            # have said the definition is uncertain too, and over-claiming partiality is
+            # the same defect as hiding it. So it is declared on the field, here — where
+            # the field is built — so the CLI dossier carries it as well as the op.
+            result["used_by_epistemic"] = (
+                "lower bound — `used_by` comes from statically resolved calls and "
+                "references (partial for Python); `defined_at` and the signatures are "
+                "exact. `callers`/`impact` carry the same caveat for a whole answer."
+            )
     col = q.column(name)
     if col and (col["writes"] or col["reads"]):
         result["column"] = col
@@ -334,6 +390,7 @@ class Session:
         self._resolution = None
         self._limit = None
         self._filter = None
+        self._scope = None
         try:
             env = {"ok": True, "result": fn(self, args)}
         except Exception as exc:  # a bad arg must not kill the resident process
@@ -359,6 +416,12 @@ class Session:
         # "this build does not report filtering".
         if self._filter is not None:
             env["filter"] = self._filter
+        # R1-C53: the third class. A `scope` narrowing is not a cut of a computed list and
+        # not a predicate over it — it is the answer covering **one provenance root** while
+        # the graph holds several, which is how `diff` came to count 40 test functions as
+        # API and how `communities` judges only the package while saying nothing.
+        if self._scope is not None:
+            env["scope"] = self._scope
         return env
 
     def _epistemic(self, op: str) -> dict:
@@ -368,7 +431,7 @@ class Session:
         sample, and only an op reading a spliced class reads it. On a full deep graph
         and on the fast tier the block is exactly the R1-C13 one.
         """
-        block = dict(_EPISTEMIC_PARTIAL)
+        block = dict(_EPISTEMIC_OVER_SET if op in _OVER_SET_OPS else _EPISTEMIC_PARTIAL)
         prov = self.graph.provenance or {}
         if op in _SPLICE_OPS and prov.get("tier") == "deep":
             if prov.get("incremental") is True:
@@ -467,7 +530,7 @@ class Session:
         result = build_query_result(self.query, args["name"])
         if not result["matches"]:  # R1-C44: an empty dossier says why it is empty
             self._resolution = _not_found(args["name"])
-        return result
+        return result  # the mixed-answer note rides on the field (see build_query_result)
 
     def _op_impact(self, args) -> dict:
         sym = args["symbol"]
@@ -512,7 +575,18 @@ class Session:
     def _op_columns(self, args) -> list:
         # F15: default to subscript-accessed keys (the real column-like set);
         # pass all=true for the full over-set incl. dict-literal payload keys.
-        return self.query.columns(subscripted_only=not args.get("all", False))
+        narrow = not args.get("all", False)
+        kept = self.query.columns(subscripted_only=narrow)
+        # R1-C53: the default hides the larger half and said nothing — measured on the
+        # dogfood tree, 331 of 1057. A deliberate narrowing still has to be declared, or
+        # the caller reads 331 as the answer to "which columns exist".
+        every = self.query.columns(subscripted_only=False) if narrow else kept
+        self._filter = {"basis": "subscripted_only" if narrow else None,
+                        "returned": len(kept), "total": len(every),
+                        "dropped": len(every) - len(kept),
+                        "note": "a key reached only through a dict literal is not a "
+                                "subscript access; pass all=true for the full over-set"}
+        return kept
 
     def _op_columns_of(self, args) -> dict:
         return self.query.columns_of(self._canon(args["symbol"]))
@@ -615,14 +689,38 @@ class Session:
         return build_check(self.query, contract, check_contract(self.query, contract))
 
     def _op_communities(self, args) -> list:
-        """R1-C18: data-driven module subsystems (greedy modularity)."""
-        return self.query.communities()
+        """R1-C18: data-driven module subsystems (greedy modularity).
+
+        R1-C53: subsystems are computed over the **package** only — a consumer root is not
+        a subsystem of it — and that was true in the code and absent from the answer.
+        """
+        out = self.query.communities()
+        self._scope = _root_scope(self.query, "core",
+                                  [m for c in out for m in c["modules"]])
+        return out
 
     def _op_flows(self, args) -> dict:
-        """R1-C18: forward call-flow from a symbol, or entry points if none given."""
+        """R1-C18: forward call-flow from a symbol, or entry points if none given.
+
+        R1-C53: the entry-point list is shaped by a *definition* — "calls out, and nothing
+        in its own root calls it" — which R1-C50 had to change after it disqualified a
+        library's public API for being used. A definition that can be wrong for a target
+        belongs in the answer, not only in a docstring.
+        """
         sym = args.get("symbol")
         if not sym:
-            return {"entry_points": self.query.entry_points()}
+            entries = self.query.entry_points()
+            self._scope = _root_scope(self.query, "core", entries)
+            return {
+                "entry_points": entries,
+                "definition": "a function that calls out and is called by nothing in its "
+                              "own provenance root; a call from `tests`/`examples` is a "
+                              "use, not an internal caller (R1-C50)",
+                "best_effort_both_ways": "an unresolved caller leaves a real internal "
+                                         "looking like an entry point, and resolving one "
+                                         "removes an entry point — so a more complete "
+                                         "graph can list fewer",
+            }
         return self.query.flow(self._canon(sym), max_depth=int(args.get("depth", 5)))
 
     def _op_semantic(self, args) -> dict:

{codmap-0.0.17 → codmap-0.0.18}/codmap.egg-info/PKG-INFO

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

@@ -122,6 +122,8 @@ tests/test_r1c48_type_checking_imports.py
 tests/test_r1c49_type_only_cycles.py
 tests/test_r1c4_complexity.py
 tests/test_r1c50_flow_entry_points.py
+tests/test_r1c53_narrowing_declared.py
+tests/test_r1c54_deterministic_rendering.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py

{codmap-0.0.17 → codmap-0.0.18}/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.17"
+version = "0.0.18"
 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.18/tests/test_r1c53_narrowing_declared.py

@@ -0,0 +1,199 @@
+"""R1-C53 — every narrowing declares itself, and the classes are enumerated.
+
+Not a bug report: a **count**. Eight of the twelve fixes R1-C41…R1-C52 were one defect —
+an answer narrower than it looks, silent about it — and four of the last five were found by
+a consumer rather than by us. So this file is about the mechanism, not the instances.
+
+Seven classes of narrowing, and what declares each:
+
+| class | what narrows | declared by |
+|---|---|---|
+| `limit` | a computed list is cut | `limit` block, always (R1-C28) |
+| `filter` | a predicate drops entries | `filter` block, always (R1-C51, R1-C53) |
+| `scope` | one provenance root is judged | `scope` block (R1-C53), `diff`'s `excluded` (R1-C52) |
+| `bound` | a walk stops at a depth | in-result (`by_distance`, `beyond_depth`, `nearest_beyond`) |
+| `tier` | the answer is a lower bound | `epistemic` (R1-C13), splice reason (R1-C43) |
+| `edge-class` | only some edge classes are read | `epistemic`, and the over-set variant (R1-C53) |
+| `definition` | the answer's shape depends on a definition that may not fit | in-result (`definition`) |
+
+The two tests that matter in a year are the guards at the bottom: one fails when an op
+learns a narrowing argument without joining a class, the other when a class's declaration
+stops being emitted. Everything above them is the evidence that each class is real.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from pathlib import Path
+
+import pytest
+
+from codemap.extract import extract, extract_repo
+from codemap.query import Query
+from codemap.serve import session as session_mod
+from codemap.serve.mermaid import render_mermaid
+from codemap.serve.session import (_LIMITED_OPS, _OVER_SET_OPS, _PARTIAL_OPS,
+                                   _UNLIMITED_BY_DESIGN, Session)
+
+FIX = Path(__file__).resolve().parent / "fixtures"
+
+
+@pytest.fixture(scope="module")
+def flowgraph():
+    return Query(extract(FIX / "flowpkg"))
+
+
+@pytest.fixture(scope="module")
+def repo():
+    return Query(extract_repo(FIX / "reporoot" / "core",
+                              consumers=(FIX / "reporoot" / "usage",),
+                              docs=(FIX / "reporoot" / "docs",), mode="full"))
+
+
+def _handle(q, op, args=None):
+    return Session(q.graph).handle({"op": op, "args": args or {}})
+
+
+# -- filter: the narrowing that hid the larger half -------------------------------------
+
+def test_columns_declares_the_half_it_hides(flowgraph):
+    """Measured on the dogfood tree before the fix: 331 returned of 1057, and the answer
+    was a bare list. The default narrowing is deliberate (F15) and was undeclared, which
+    is a different thing from being wrong."""
+    env = _handle(flowgraph, "columns")
+    f = env["filter"]
+    assert f["basis"] == "subscripted_only"
+    assert f["returned"] == len(env["result"])
+    assert f["total"] >= f["returned"] and f["dropped"] == f["total"] - f["returned"]
+    wide = _handle(flowgraph, "columns", {"all": True})
+    assert wide["filter"]["basis"] is None and wide["filter"]["dropped"] == 0
+    assert len(wide["result"]) == f["total"], "and the two agree on the total"
+
+
+def test_the_over_set_is_not_called_a_lower_bound(flowgraph):
+    """`reads`/`writes` are partial in the *other* direction. Borrowing the lower-bound
+    wording would tell a caller to widen when it must verify instead."""
+    for op, args in (("columns", {}), ("columns_of", {"symbol": "flowpkg.producer.make"})):
+        env = _handle(flowgraph, op, args)
+        reason = env.get("epistemic", {}).get("reason", "")
+        assert "over-set" in reason, (op, reason)
+        assert "lower bound" not in reason.replace("not a lower bound", ""), op
+    assert _OVER_SET_OPS == {"column", "columns", "columns_of"}
+    assert _OVER_SET_OPS <= _PARTIAL_OPS, "an over-set is still a partiality"
+
+
+# -- scope: one root judged, the others named -------------------------------------------
+
+def test_communities_names_the_root_it_judges(repo):
+    env = _handle(repo, "communities")
+    s = env["scope"]
+    assert s["root"] == "core"
+    assert s["not_judged"] == {"usage": 1}, "the consumer root is named, not silently cut"
+
+
+def test_entry_points_name_the_root_and_the_definition(repo):
+    env = _handle(repo, "flows")
+    assert env["scope"]["not_judged"] == {"usage": 1}
+    d = env["result"]
+    assert "use, not an internal caller" in d["definition"], "R1-C50, in the answer"
+    assert "fewer" in d["best_effort_both_ways"], "and the reverse direction too"
+
+
+def test_a_single_root_graph_says_so_without_inventing_exclusions(flowgraph):
+    env = _handle(flowgraph, "communities")
+    assert env["scope"]["root"] == "core" and env["scope"]["not_judged"] == {}
+
+
+# -- definition / mixed answers ----------------------------------------------------------
+
+def test_a_mixed_dossier_declares_per_field_not_per_envelope(flowgraph):
+    """The rule this file does **not** break: absence of `epistemic` means exact. A dossier
+    whose definition is exact and whose `used_by` is a lower bound must not be stamped
+    wholesale — over-claiming partiality is the same defect pointed the other way."""
+    q = Query(extract(FIX / "argpkg"))
+    env = _handle(q, "query", {"name": "configure"})
+    assert env["result"]["used_by"], "the fixture must carry the field being declared"
+    assert "epistemic" not in env, "the dossier as a whole is not a lower bound"
+    assert "lower bound" in env["result"]["used_by_epistemic"]
+    assert "are exact" in env["result"]["used_by_epistemic"]
+    # and the note lives where the field is built, so the CLI dossier carries it too
+    from codemap.serve.session import build_query_result
+    assert "used_by_epistemic" in build_query_result(q, "configure")
+    assert "used_by_epistemic" not in build_query_result(q, "nope_missing")
+
+
+def test_a_scoped_diagram_says_what_it_left_out(flowgraph):
+    scoped = render_mermaid(flowgraph, "class", scope="flowpkg.klass")
+    assert "%% scope: flowpkg.klass" in scoped and "further line(s) exist" in scoped
+    assert "%% scope" not in render_mermaid(flowgraph, "class")
+
+
+# -- the guards --------------------------------------------------------------------------
+
+_NARROWING_ARG = re.compile(
+    r"""args\.get\(\s*["'](?:\w+_)?(limit|cap|budget|max|top|min_confidence|all|scope|root)(?:_\w+)?["']""")
+
+#: Ops that read a narrowing argument and declare it, with the block that does the
+#: declaring. Hand-written on purpose: the guard below compares this list against the
+#: source, so a new narrowing forces an entry here rather than passing unnoticed.
+_DECLARED = {
+    "search": "limit", "semantic": "limit", "tests": "limit", "covers": "limit",
+    "callers": "filter", "callees": "filter", "columns": "filter",
+    "communities": "scope", "flows": "scope",
+}
+#: Read a narrowing-ish argument and deliberately declare nothing, with the reason.
+_NOT_A_NARROWING = {
+    "check": "`root` says where codemap.toml is read from — it does not narrow the answer; "
+             "what the contract left unjudged is already declared by the R1-C30-f2 block",
+    "export": "`root`/`scope` select *which view* to render rather than cutting an answer, "
+              "and the scoped mermaid diagram carries its own `%% scope:` line (R1-C53)",
+    "report": "a markdown report declares its own narrowing in prose — dead-code prints "
+              "`(min-confidence: …)` and impact prints the flow note; there is no "
+              "structured answer here for a block to describe",
+    "pack": _UNLIMITED_BY_DESIGN["pack"],
+    "impact": _UNLIMITED_BY_DESIGN["impact"],
+}
+
+
+def test_every_op_reading_a_narrowing_arg_is_classified():
+    """Fails when an op learns a narrowing without joining a class. The list it checks is
+    the ops' own source, because a hand-kept list is what gets forgotten — and the two
+    hand-kept sets here exist so that "exempt, deliberately" is distinguishable from
+    "nobody noticed"."""
+    for op, fn in session_mod._OPS.items():
+        if not _NARROWING_ARG.search(inspect.getsource(fn)):
+            continue
+        assert op in _DECLARED or op in _NOT_A_NARROWING, (
+            f"op {op!r} reads a narrowing argument and neither declares it nor records "
+            f"why it does not")
+    for op, reason in _NOT_A_NARROWING.items():
+        assert op in session_mod._OPS and len(reason) > 40, op
+    assert set(_DECLARED) & _LIMITED_OPS == {"search", "semantic", "tests", "covers"}
+
+
+def test_each_declared_op_actually_emits_its_block(flowgraph, repo):
+    calls = {
+        "search": (flowgraph, {"term": "hit"}), "tests": (flowgraph, {"symbol": "hit"}),
+        "covers": (flowgraph, {"test": "t"}),
+        "callers": (flowgraph, {"symbol": "flowpkg.leaf.hit"}),
+        "callees": (flowgraph, {"symbol": "flowpkg.entry.main"}),
+        "columns": (flowgraph, {}), "communities": (repo, {}), "flows": (repo, {}),
+    }
+    assert set(calls) | {"semantic"} == set(_DECLARED), "a declared op has no coverage here"
+    for op, (q, args) in calls.items():
+        env = _handle(q, op, args)
+        assert env["ok"], (op, env)
+        block = _DECLARED[op]
+        assert block in env, f"{op} promised a {block!r} block and emitted {sorted(env)}"
+
+
+def test_the_guard_catches_a_narrowing_name_it_has_not_seen():
+    """R1-C37 on the guard itself: shown the shapes it must catch, including the ones that
+    slipped past earlier versions of the pattern."""
+    for src in ('args.get("min_confidence")', 'args.get("all", False)',
+                'args.get("flow_limit", 5)', "args.get('max_results')",
+                'args.get("scope")', 'args.get("root")'):
+        assert _NARROWING_ARG.search(src), src
+    for src in ('args.get("symbol")', 'args.get("depth", 2)', 'args.get("base")'):
+        assert not _NARROWING_ARG.search(src), f"{src} is not a narrowing of the answer"

codmap-0.0.18/tests/test_r1c54_deterministic_rendering.py

@@ -0,0 +1,131 @@
+"""R1-C54 — the same graph renders the same text, whatever the hash seed.
+
+[Issue #20](https://github.com/kogriv/codemap/issues/20), filed by the lab while raising
+their pin 0.0.16 → 0.0.17. The graph was inert exactly as promised — 1904 nodes, 4652
+edges, the whole JSON byte-identical but for `provenance.version` — and the *printed cycle
+chains* differed between runs. They nearly recorded it as a behavioural change in the
+release, and did not only because they re-measured within one version first.
+
+`nx.simple_cycles` enters a cycle wherever its traversal happens to, and that follows
+set-iteration order, i.e. string hashes. `arch.py` sorted the cycles by `(len, c)`, which
+looked like canonicalisation but could not be: the key moves with the rotation.
+
+Gap: `gaps/cycle_rotation_nondeterminism_2026-09-12.md`. The perimeter measured there is
+wider than the report: three consumers of one source, one of them the **structured** MCP
+`architecture` answer, while `report dependencies` and the living docs were already stable
+because they print counts rather than chains.
+
+The guard has to spawn processes — `PYTHONHASHSEED` is read once at interpreter start, so
+an in-process monkeypatch cannot produce the condition. Its positive control is twofold:
+the rotation unit test below fails if canonicalisation is removed, and the cross-seed test
+was measured red on the pre-fix code (3 distinct outputs for each of three surfaces across
+8 seeds — recorded in the gap with the numbers).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from codemap import store
+from codemap.extract import extract
+from codemap.query import Query, _canonical_cycles
+
+PKG = {
+    "__init__.py": "",
+    # one lazy cycle over three modules: a → b → c → a, each closed in a function
+    "a.py": "def f():\n    from .b import g\n    return g()\n",
+    "b.py": "def g():\n    from .c import h\n    return h()\n",
+    "c.py": "def h():\n    from .a import f\n    return f()\n",
+    # a second, shorter cycle so the *order of cycles* is exercised too
+    "d.py": "def p():\n    from .e import q\n    return q()\n",
+    "e.py": "def q():\n    from .d import p\n    return p()\n",
+}
+
+_PROBE = textwrap.dedent('''
+    import hashlib, json, sys
+    from codemap import arch, store
+    from codemap.query import Query
+    from codemap.serve.architecture import build_architecture, render_architecture
+    from codemap.serve.audit import render_dependencies
+    from codemap.serve.livingdocs import render_docs
+
+    q = Query(store.load(sys.argv[1]))
+    h = lambda s: hashlib.md5(s.encode()).hexdigest()
+    c = arch.ArchitectureContract(no_cycles=True, no_lazy_cycles=True,
+                                  no_type_only_cycles=True)
+    print(json.dumps({
+        "architecture_md": h(render_architecture(q)),
+        "architecture_json": h(json.dumps(build_architecture(q))),
+        "dependencies_md": h(render_dependencies(q)),
+        "docs_md": h(render_docs(q)),
+        "check": h(json.dumps([[v.rule, v.summary, list(v.modules)]
+                               for v in arch.check_contract(q, c)])),
+        "graph_bytes": h(store.dumps(q.graph)),
+        "cycles": h(json.dumps(q.lazy_import_cycles())),
+    }))
+''')
+
+
+@pytest.fixture(scope="module")
+def graph_file(tmp_path_factory):
+    root = tmp_path_factory.mktemp("r1c54")
+    pkg = root / "cycpkg"
+    pkg.mkdir()
+    for name, body in PKG.items():
+        (pkg / name).write_text(body)
+    path = root / "g.json"
+    store.save(extract(pkg), path)
+    return path
+
+
+# -- the unit control: rotation in, one form out -----------------------------------------
+
+def test_every_rotation_of_a_cycle_canonicalises_to_one_form():
+    rotations = [["a", "b", "c"], ["b", "c", "a"], ["c", "a", "b"]]
+    assert {tuple(_canonical_cycles([r])[0]) for r in rotations} == {("a", "b", "c")}
+
+
+def test_the_order_of_cycles_is_canonical_too(graph_file):
+    """D2: rotating without sorting would leave the *list* order on the traversal."""
+    q = Query(store.load(graph_file))
+    cycles = q.lazy_import_cycles()
+    assert cycles == sorted(cycles, key=lambda c: (len(c), c))
+    assert all(c[0] == min(c) for c in cycles), "each starts at its smallest node"
+    assert len(cycles) == 2, "the fixture carries both a 3-cycle and a 2-cycle"
+
+
+def test_without_canonicalisation_the_rotations_stay_three_answers():
+    """R1-C37: the thing the fix must reject, shown to the check. This is what all three
+    consumers were printing — one cycle, three texts."""
+    raw = [["b", "c", "a"], ["c", "a", "b"], ["a", "b", "c"]]
+    assert len({tuple(c) for c in raw}) == 3, "three renderings of one cycle"
+    assert len({tuple(c) for c in (_canonical_cycles([c])[0] for c in raw)}) == 1
+
+
+# -- the integration guard: across hash seeds, in separate processes ----------------------
+
+def _run(graph_file, seed: int) -> dict:
+    probe = Path(graph_file).parent / "probe.py"
+    probe.write_text(_PROBE)
+    out = subprocess.run([sys.executable, str(probe), str(graph_file)],
+                         capture_output=True, text=True, check=True,
+                         env={"PYTHONHASHSEED": str(seed), "PATH": "/usr/bin:/bin",
+                              "PYTHONPATH": str(Path(__file__).resolve().parents[1])})
+    return json.loads(out.stdout)
+
+
+@pytest.mark.parametrize("surface", ["architecture_md", "architecture_json", "check",
+                                     "dependencies_md", "docs_md", "graph_bytes", "cycles"])
+def test_one_graph_one_rendering_across_hash_seeds(graph_file, surface):
+    """Six surfaces, eight seeds, one answer each. The three that were already stable are
+    in here on purpose: a regression in them must fail too, and leaving them out would make
+    this guard narrower than the claim it defends (README: "deterministic ... diffable").
+    """
+    seen = {_run(graph_file, seed)[surface] for seed in range(8)}
+    assert len(seen) == 1, f"{surface} rendered {len(seen)} different ways across 8 seeds"