codmap 0.0.8__tar.gz → 0.0.9__tar.gz

{codmap-0.0.8/codmap.egg-info → codmap-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.8
+Version: 0.0.9
 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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **752 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 &
@@ -58,8 +58,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -247,6 +248,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.9}/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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **752 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 &
@@ -22,8 +22,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -211,6 +212,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.9}/codemap/cli.py

@@ -747,6 +747,8 @@ def _cmd_diff(args) -> int:
             print(f"[warning] {line}", file=sys.stderr)
         print(f"[warning] differences below may be tool changes, not code changes "
               f"(old: {cmp['old']} | new: {cmp['new']})", file=sys.stderr)
+    for caveat in cmp.get("caveats") or ():
+        print(f"[note] {caveat}", file=sys.stderr)
     print(render_apidiff(old, new), end="")
     if args.exit_code and not build_apidiff(old, new)["ok"]:
         return 1

{codmap-0.0.8 → codmap-0.0.9}/codemap/diagnostics.py

@@ -22,6 +22,7 @@ SCHEMA_MISMATCH = "schema_mismatch"
 UNREAD_INPUTS = "unread_inputs"
 MODULE_COUNT_MISMATCH = "module_count_mismatch"
 SCOPE_MEMBERSHIP = "scope_membership"
+DEEP_TIER_UNSTABLE = "deep_tier_unstable"
 
 #: A ``warning`` invalidates the conclusions a surface draws from the graph — read them as
 #: unknown. A ``note`` states a fact about how the graph was built and invalidates nothing.
@@ -190,6 +191,38 @@ def unread_inputs_diagnostic(graph) -> dict | None:
     }
 
 
+def deep_tier_diagnostic(graph) -> dict | None:
+    """State the deep tier's noise floor on the artifact itself (R1-C42).
+
+    A **note**, not a warning: nothing here is wrong, and no finding below is invalid.
+    What was missing is that the tier's instability was known — measured at R1-C9, and
+    the reason the CI determinism job runs the fast tier only — while living exclusively
+    in a comment in a workflow file. A consumer read "deterministic" and built a
+    two-release comparison on it; the difference they saw was the tool, not the code.
+
+    Measured on two trees: ten deep builds of an unchanged tree produced **two** distinct
+    artifacts (7/3), differing in two per-symbol call counters and no edges; on a larger
+    tree one build in seven lost one real call edge of 9524. The cause is jedi's
+    per-script execution budget — an inference that runs out of it returns nothing, and
+    that reads as `unresolved` rather than as an error.
+    """
+    if (graph.provenance or {}).get("tier") != "deep":
+        return None
+    return {
+        "code": DEEP_TIER_UNSTABLE,
+        "severity": NOTE,
+        "tier": "deep",
+        "consequence": ("Everything here is a lower bound as usual; treat a difference "
+                        "of a few call edges between two deep graphs as possible tool "
+                        "noise rather than a change in the code."),
+        "message": (
+            "built on the deep (jedi) tier, which is not byte-stable: two builds of an "
+            "unchanged tree can differ by a few call edges — measured at roughly one run "
+            "in three on a 2133-node tree, by two per-symbol counters and no edges."
+        ),
+    }
+
+
 def scope_membership_diagnostic(graph) -> dict | None:
     """Flag files the graph was built from that the input manifest never listed (R1-C41).
 
@@ -274,7 +307,7 @@ def diagnostics(graph) -> list[dict]:
     checks = (import_graph_diagnostic(graph), namespace_target_diagnostic(graph),
               cross_root_diagnostic(graph), schema_diagnostic(graph),
               unread_inputs_diagnostic(graph), module_count_diagnostic(graph),
-              scope_membership_diagnostic(graph))
+              scope_membership_diagnostic(graph), deep_tier_diagnostic(graph))
     return [d for d in checks if d is not None]
 
 

{codmap-0.0.8 → codmap-0.0.9}/codemap/provenance.py

@@ -253,6 +253,7 @@ def comparability(old: dict | None, new: dict | None) -> dict:
     were dead.
     """
     differences: list[str] = []
+    caveats: list[str] = []
     if not old or not new:
         differences.append("one of the graphs records no provenance "
                            "(built before schema 0.12) — the pair cannot be verified")
@@ -264,9 +265,20 @@ def comparability(old: dict | None, new: dict | None) -> dict:
         old_roots, new_roots = old.get("roots"), new.get("roots")
         if old_roots != new_roots:
             differences.append(f"different scope roots: {old_roots} → {new_roots}")
+        if old.get("tier") == new.get("tier") == "deep":
+            # R1-C42: matching tiers make the pair comparable, and on the deep tier that
+            # is not the same as "every difference here is a code change". Measured on
+            # two trees: builds of an *unchanged* tree differ in roughly one run of
+            # three, by a couple of call classifications — and on the larger tree by one
+            # real call edge in ~9500. A caveat, not a difference: it is the right pair,
+            # the reader just must not read a two-edge delta as a fact about the code.
+            caveats.append("both sides are deep-tier, which is not byte-stable: two "
+                           "builds of an unchanged tree can differ by a few call edges, "
+                           "so read a small call-graph delta as possible tool noise")
     return {
         "comparable": not differences,
         "differences": differences,
+        "caveats": caveats,
         "old": describe(old),
         "new": describe(new),
     }

{codmap-0.0.8 → codmap-0.0.9}/codemap/serve/apidiff.py

@@ -53,6 +53,10 @@ def render_apidiff(old: Graph, new: Graph) -> str:
                    + f". Old: {prov['old']} | new: {prov['new']}. "
                      "Differences below may be tool changes, not code changes.")
         out.append("")
+    # R1-C42: comparable, and still carrying a noise floor the reader has to know about.
+    for caveat in prov.get("caveats") or ():
+        out.append(f"> ℹ️ {caveat}.")
+        out.append("")
 
     removed = d["removed"]
     if removed:

{codmap-0.0.8 → codmap-0.0.9/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.8
+Version: 0.0.9
 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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **752 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 &
@@ -58,8 +58,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -247,6 +248,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.9}/codmap.egg-info/SOURCES.txt

@@ -109,6 +109,7 @@ tests/test_r1c38_tool_drift.py
 tests/test_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
 tests/test_r1c41_scope_membership.py
+tests/test_r1c42_deep_tier_stability.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.8 → codmap-0.0.9}/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.8"
+version = "0.0.9"
 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.9/tests/test_r1c42_deep_tier_stability.py

@@ -0,0 +1,92 @@
+"""R1-C42 — the deep tier is not byte-stable, and the artifact must say so.
+
+Raised by the second real target: seven builds of an unchanged clean tree, and in one
+of them a real `calls` edge (resolved through `getattr`) was gone — 9524 edges against
+9523. They had briefly concluded a regression between two releases from it, which is
+the failure this suite exists to prevent: a consumer reading "deterministic" and
+comparing two deep graphs as if every difference were a change in the code.
+
+The instability itself was **known** — measured at R1-C9, and the reason the CI
+determinism job runs the fast tier only. It lived in a comment in a workflow file,
+while README said "deterministic" unqualified and `provenance.md` said two builds of an
+unchanged tree are byte-identical. So the fix is disclosure in the places a consumer
+actually reads: the graph's own diagnostics, and any comparison of two deep graphs.
+
+Reproduced here on our own tree before the fix: ten deep builds → two distinct
+artifacts (7/3), differing in two per-symbol call counters and no edges. The cause is
+jedi's per-script execution budget: an inference that runs out of it returns nothing,
+and nothing reads as `unresolved`. That is not testable in a unit suite — a build takes
+~40 s and flips about one run in three — so what is pinned here is the disclosure.
+"""
+
+from __future__ import annotations
+
+from codemap.diagnostics import DEEP_TIER_UNSTABLE, NOTE, WARNING, deep_tier_diagnostic, diagnostics
+from codemap.model import Graph
+from codemap.provenance import comparability
+from codemap.serve.apidiff import render_apidiff
+
+
+def _graph(tier: str) -> Graph:
+    g = Graph(target="pkg")
+    g.provenance = {"tier": tier, "tool": {"name": "codemap", "version": "0.0.9"}}
+    return g
+
+
+# -- the note on the artifact --------------------------------------------------
+
+def test_a_fast_graph_says_nothing():
+    assert deep_tier_diagnostic(_graph("fast")) is None
+
+
+def test_a_deep_graph_declares_its_noise_floor():
+    d = deep_tier_diagnostic(_graph("deep"))
+    assert d is not None and d["code"] == DEEP_TIER_UNSTABLE
+    assert "not byte-stable" in d["message"]
+    assert d["consequence"]
+
+
+def test_it_is_a_note_and_not_a_warning():
+    """A warning says the findings below are invalid. Nothing here is invalid — the
+    graph is sound, it is one sample of a slightly fuzzy function (issue #8's rule)."""
+    d = deep_tier_diagnostic(_graph("deep"))
+    assert d["severity"] == NOTE != WARNING
+
+
+def test_it_reaches_the_surface_a_consumer_reads():
+    codes = [d["code"] for d in diagnostics(_graph("deep"))]
+    assert DEEP_TIER_UNSTABLE in codes
+    assert DEEP_TIER_UNSTABLE not in [d["code"] for d in diagnostics(_graph("fast"))]
+
+
+def test_a_pre_provenance_graph_is_not_guessed_about():
+    g = Graph(target="pkg")
+    g.provenance = {}
+    assert deep_tier_diagnostic(g) is None
+
+
+# -- the caveat on a comparison ------------------------------------------------
+
+def test_two_deep_graphs_stay_comparable_and_carry_the_caveat():
+    c = comparability(_graph("deep").provenance, _graph("deep").provenance)
+    assert c["comparable"] is True, "matching tiers are the right pair — never a refusal"
+    assert c["caveats"] and "not byte-stable" in c["caveats"][0]
+
+
+def test_two_fast_graphs_carry_no_caveat():
+    c = comparability(_graph("fast").provenance, _graph("fast").provenance)
+    assert c["caveats"] == []
+
+
+def test_mixed_tiers_are_still_an_incomparability_not_a_caveat():
+    c = comparability(_graph("fast").provenance, _graph("deep").provenance)
+    assert c["comparable"] is False
+    assert any("different tier" in d for d in c["differences"])
+    assert c["caveats"] == [], "a caveat must not soften a genuine incomparability"
+
+
+def test_the_rendered_diff_shows_it_above_the_verdict():
+    out = render_apidiff(_graph("deep"), _graph("deep"))
+    assert "not byte-stable" in out
+    head = out.split("## ")[0]
+    assert "not byte-stable" in head, "a footnote is not a disclosure"