codmap 0.0.7__tar.gz → 0.0.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.7
+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, **734 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.7 → 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, **734 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.7 → codmap-0.0.9}/codemap/cli.py

@@ -104,7 +104,7 @@ def _cmd_build(args) -> int:
         # roots come from extract_repo in this same call; never inherited from a graph
         # loaded off disk, which is how a stale scope would sneak into a fresh build.
         roots=graph.provenance.get("roots") if (args.consumer or args.docs) else None,
-        inputs=graph.provenance.get("inputs"))
+        inputs=_inputs_with_membership(graph, scope, args))
     # R1-C21: a well-formed but vacuous graph must announce itself — silence is what
     # lets an unparsed layout read as a clean bill of health downstream.
     for d in diagnostics(graph):
@@ -132,6 +132,27 @@ def _cmd_build(args) -> int:
     return 0
 
 
+def _inputs_with_membership(graph, scope, args):
+    """The extractor's ``inputs`` block plus the manifest membership result (R1-C41).
+
+    Computed here because it is the one place that holds both sides: the graph and the
+    scope manifest that claims to describe its input. The *result* travels in the graph
+    (beside ``skipped``, which carries the same kind of fact) because build-time stderr
+    never reaches whoever reads the artifact an hour later, possibly without the sidecar.
+
+    Omitted entirely when no manifest resolved — that is "could not compare", and writing
+    a zero there would turn an unknown into a clean bill of health.
+    """
+    inputs = dict(graph.provenance.get("inputs") or {})
+    if not scope:
+        return inputs or None
+    from codemap.scope import unlisted_files
+    base = roots_base(args.path, tuple(args.consumer or ()), tuple(args.docs or ()))
+    inputs["unlisted"] = unlisted_files(
+        (n.file for n in graph.nodes.values() if n.file), scope, base=base)
+    return inputs
+
+
 def _resolve_scope_quietly(args):
     """The input scope manifest, or None. Never fatal — a build must not fail on it."""
     from codemap.scope import resolve_scope
@@ -726,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.7 → codmap-0.0.9}/codemap/diagnostics.py

@@ -21,6 +21,8 @@ NO_CROSS_ROOT_EDGES = "no_cross_root_edges"
 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.
@@ -189,6 +191,74 @@ 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).
+
+    Sibling of the conservation law above, and it catches what that one provably cannot:
+    the count compares the *extractor's* walk against the graph, so when both agree and
+    only the **manifest** disagrees — an untracked or gitignored module, a file leaked in
+    from outside the target — it stays silent, correctly. Reported by the second real
+    target (issue #15), who found a sidecar listing 47 files with a hash on each beside a
+    graph built from 48.
+
+    Derived from ``provenance.inputs.unlisted``, which the build records because the
+    comparison needs the scope manifest and a consumer may hold only the graph. Absent
+    field means the build could not compare (no manifest resolved) — that is *unknown*,
+    not zero, so it is not reported as a clean result.
+    """
+    unlisted = ((graph.provenance or {}).get("inputs") or {}).get("unlisted") or {}
+    count = unlisted.get("count") or 0
+    if not count:
+        return None
+    sample = ", ".join(unlisted.get("sample") or [])
+    where = (" (at least one lies outside the scope root entirely)"
+             if unlisted.get("outside_root") else "")
+    return {
+        "code": SCOPE_MEMBERSHIP,
+        "severity": WARNING,
+        "unlisted": count,
+        "consequence": ("The manifest and `scope_id` describe a different input than this "
+                        "graph was built from, so read the input identity as **unknown** — "
+                        "and with it `--incremental` and `watch`, which key off that value."),
+        "message": (
+            f"{count} file(s) in this graph are not listed in the input manifest{where}: "
+            f"{sample}" + (" …" if count > len(unlisted.get("sample") or []) else "")
+        ),
+    }
+
+
 def module_count_diagnostic(graph) -> dict | None:
     """Conservation law over the build: modules cannot outnumber the files that define
     them, nor silently fall short of them (R1-C23 / design D6).
@@ -236,7 +306,8 @@ def diagnostics(graph) -> list[dict]:
     """Every diagnostic that applies to ``graph`` (empty list when it looks sound)."""
     checks = (import_graph_diagnostic(graph), namespace_target_diagnostic(graph),
               cross_root_diagnostic(graph), schema_diagnostic(graph),
-              unread_inputs_diagnostic(graph), module_count_diagnostic(graph))
+              unread_inputs_diagnostic(graph), module_count_diagnostic(graph),
+              scope_membership_diagnostic(graph), deep_tier_diagnostic(graph))
     return [d for d in checks if d is not None]
 
 

{codmap-0.0.7 → 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.7 → codmap-0.0.9}/codemap/scope.py

@@ -90,8 +90,17 @@ def _pick_root(core: Path, consumers, docs) -> tuple[Path, str]:
     return base, "fs"
 
 
-def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str], dict]:
-    """git ls-files over the scope pathspecs → (rel paths, {path: git_blob})."""
+def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str], dict, set[str]]:
+    """git ls-files over the scope pathspecs → (rel paths, {path: git_blob}, untracked).
+
+    Two calls, because "the input" is not "the commit" (R1-C41). The tracked set is what
+    ``git ls-files`` knows; ``--others --exclude-standard`` adds exactly what ``git add .``
+    would stage — a module that exists and has not been added yet is read by the extractor
+    like any other, so leaving it out made the manifest describe a different input than the
+    graph was built from, without moving ``scope_id``. Ignored files stay out on purpose:
+    if ``.gitignore`` says a file is not part of the tree, the manifest does not get to
+    decide otherwise — the membership check names them instead (design §1.7 D2).
+    """
     specs = [rp for rp, _ in roots if rp]
     out = _git(root, "ls-files", "-s", "--", *specs) or ""
     paths, blobs = [], {}
@@ -104,7 +113,9 @@ def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str],
         if len(cols) >= 2:
             blobs[path] = cols[1]
         paths.append(path)
-    return paths, blobs
+    others = _git(root, "ls-files", "--others", "--exclude-standard", "--", *specs) or ""
+    untracked = {p for p in others.splitlines() if p}
+    return paths + sorted(untracked), blobs, untracked
 
 
 def _enumerate_fs(root: Path, roots, include, exclude_dirs) -> list[str]:
@@ -138,10 +149,10 @@ def resolve_scope(
     roots = _roots_spec(root, core, consumers, docs)
 
     if mode == "git":
-        rels, blobs = _enumerate_git(root, roots)
+        rels, blobs, untracked = _enumerate_git(root, roots)
         rels = [r for r in rels if _match_include(Path(r).name, include)]
     else:
-        rels, blobs = _enumerate_fs(root, roots, include, exclude_dirs), {}
+        rels, blobs, untracked = _enumerate_fs(root, roots, include, exclude_dirs), {}, set()
 
     files = []
     for rel in sorted(set(rels)):
@@ -155,6 +166,11 @@ def resolve_scope(
                "loc": data.count(b"\n") + (1 if data and not data.endswith(b"\n") else 0)}
         if rel in blobs:
             rec["git_blob"] = blobs[rel]
+        if mode == "git":
+            # Always stated, never inferred from a missing key — absence is ambiguous
+            # (R1-C28's rule, applied to the manifest). fs mode omits it: there is no
+            # index to be tracked in, so the question does not arise.
+            rec["tracked"] = rel not in untracked
         files.append(rec)
 
     scope_id = "sha256:" + hashlib.sha256(
@@ -201,6 +217,51 @@ def _git_block(root: Path, roots: list[tuple[str, str]], mode: str) -> dict:
             "dirty": bool(dirty_files), "dirty_files": dirty_files}
 
 
+def unlisted_files(node_files, scope: dict, *, base: str | Path | None = None,
+                   sample: int = 5) -> dict:
+    """Files the graph was built from that the manifest does not list (R1-C41).
+
+    The manifest is the artifact a consumer reads to answer *"what exactly was
+    analyzed"*, and until this check existed it could answer wrong in silence: the
+    graph carried a module whose file the sidecar never mentioned, and ``scope_id`` —
+    the same value ``--incremental`` and ``watch`` key off — did not move.
+
+    **The two sides do not share an origin**, which is the whole difficulty. Node paths
+    are relative to the graph's own base (R1-C31: the parent of the package, or the
+    common ancestor of the roots), manifest paths are relative to the scope root (the
+    git top-level). On a ``src/`` layout those differ by a segment, and a naive string
+    comparison called both files of a healthy build unlisted — measured, 2 of 2. So the
+    node path is joined onto ``base`` and re-expressed against the scope root before it
+    is looked up; lexically, never through ``resolve()``, so a symlinked checkout does
+    not silently rewrite the answer.
+
+    Returns ``{count, sample, outside_root}`` — always, including ``count: 0``, because
+    a missing field is not the same statement as "nothing was unlisted". Paths outside
+    the scope root are reduced to a bare name: they are absolute (the D5 symptom of a
+    file the build should never have read), and the provenance block this ends up in
+    refuses absolute paths by contract.
+    """
+    root = Path(scope.get("root") or ".")
+    listed = {f["path"] for f in scope.get("files") or ()}
+    unlisted: set[str] = set()
+    outside = False
+    for raw in node_files:
+        if not raw:
+            continue
+        p = Path(raw)
+        absolute = p if p.is_absolute() else Path(os.path.normpath(Path(base or root) / p))
+        try:
+            rel = absolute.relative_to(root).as_posix()
+        except ValueError:
+            outside = True
+            unlisted.add(p.name)
+            continue
+        if rel not in listed:
+            unlisted.add(rel)
+    return {"count": len(unlisted), "sample": sorted(unlisted)[:sample],
+            "outside_root": outside}
+
+
 def diff_scopes(a: dict, b: dict) -> dict:
     """Added / removed / changed files between two scope manifests (by path+sha256)."""
     am = {f["path"]: f["sha256"] for f in a.get("files", [])}

{codmap-0.0.7 → 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.7 → codmap-0.0.9/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.7
+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, **734 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.7 → codmap-0.0.9}/codmap.egg-info/SOURCES.txt

@@ -108,6 +108,8 @@ tests/test_r1c37_rule_mutation.py
 tests/test_r1c38_tool_drift.py
 tests/test_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
+tests/test_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.7 → 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.7"
+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_r1c41_scope_membership.py

@@ -0,0 +1,213 @@
+"""R1-C41 — the manifest must describe the input the graph was actually built from.
+
+Raised by the second real target (issue #15): their sidecar listed 47 files with a
+`git_blob` and a `sha256` on each while the graph carried 48, and the artifact a
+consumer reads to answer *"what exactly was analyzed"* answered wrong in silence.
+
+Measuring it made the defect wider than the report — no decoy directory is needed. In
+git mode the manifest enumerated the *tracked* set while the extractor walked the
+*filesystem*, so an untracked module (one that exists and has not been `git add`ed) or a
+gitignored one was in the graph, absent from `scope.files`, and moved `scope_id` not at
+all. Since `scope_id` is the cache key for `--incremental` and the `watch` probe, that is
+a correctness defect and not a reporting one: `--incremental` printed
+`unchanged: 0 module(s) recomputed` over a file that had just grown a new symbol.
+
+Every test here drives the real CLI over a real git repo. The point is not the arithmetic
+of a comparison — it is whether the condition can arise at all, which is the lesson 0.0.6
+paid for.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from codemap import cli
+from codemap.diagnostics import SCOPE_MEMBERSHIP, scope_membership_diagnostic
+from codemap.provenance import build_provenance
+from codemap.scope import resolve_scope, unlisted_files
+
+
+def _git(base: Path, *args: str) -> None:
+    subprocess.run(("git", "-C", str(base), *args), check=True,
+                   capture_output=True, text=True)
+
+
+@pytest.fixture
+def repo(tmp_path) -> Path:
+    """A git repo whose .gitignore excludes a *source* file the extractor still reads."""
+    if not shutil.which("git"):
+        pytest.skip("git not available")
+    (tmp_path / "pkg").mkdir()
+    (tmp_path / "pkg" / "__init__.py").write_text("")
+    (tmp_path / "pkg" / "core.py").write_text("def a():\n    return 1\n")
+    (tmp_path / ".gitignore").write_text("pkg/generated_*.py\n")
+    _git(tmp_path, "init", "-q")
+    _git(tmp_path, "config", "user.email", "t@t")
+    _git(tmp_path, "config", "user.name", "t")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-qm", "init")
+    return tmp_path
+
+
+def _build(repo: Path, out: Path, *extra: str) -> tuple[dict, dict]:
+    assert cli.main(["build", str(repo / "pkg"), "-o", str(out), *extra]) == 0
+    graph = json.loads(out.read_text(encoding="utf-8"))
+    meta = json.loads(Path(str(out) + ".meta.json").read_text(encoding="utf-8"))
+    return graph, meta
+
+
+def _files(meta: dict) -> dict[str, dict]:
+    return {f["path"]: f for f in meta["scope"]["files"]}
+
+
+# -- D1: enumerate what will be read, not what the commit remembers ------------
+
+def test_an_untracked_module_enters_the_manifest_and_moves_the_identity(repo, tmp_path):
+    before, meta_before = _build(repo, tmp_path / "a.json")
+    (repo / "pkg" / "untracked.py").write_text("def brand_new():\n    return 42\n")
+    after, meta_after = _build(repo, tmp_path / "b.json")
+
+    assert "pkg/untracked.py" not in _files(meta_before)
+    assert "pkg/untracked.py" in _files(meta_after), (
+        "a module that exists and has not been `git add`ed is read by the extractor; "
+        "leaving it out of the manifest describes a different input than the graph")
+    # …and the identity has to move, or every cache keyed on it is wrong (below).
+    assert before["provenance"]["scope_id"] != after["provenance"]["scope_id"]
+
+
+def test_incremental_recomputes_an_untracked_edit(repo, tmp_path):
+    out = tmp_path / "inc.json"
+    (repo / "pkg" / "untracked.py").write_text("def brand_new():\n    return 42\n")
+    _build(repo, out)
+    (repo / "pkg" / "untracked.py").write_text(
+        "def brand_new():\n    return 42\n\n\ndef added_later():\n    return 7\n")
+    graph, _ = _build(repo, out, "--incremental")
+    assert any(n["id"].endswith("added_later") for n in graph["nodes"]), (
+        "scope_id is the incremental cache key: if an untracked edit does not move it, "
+        "the rebuild reports `unchanged` and serves a stale graph as current")
+
+
+def test_git_mode_states_tracked_on_every_record_and_fs_mode_omits_it(repo):
+    scope = resolve_scope(repo / "pkg")
+    (repo / "pkg" / "untracked.py").write_text("x = 1\n")
+    scope2 = resolve_scope(repo / "pkg")
+    recs = {f["path"]: f for f in scope2["files"]}
+
+    # stated on every record, never inferred from a missing key (R1-C28's rule)
+    assert all("tracked" in f for f in scope["files"])
+    assert recs["pkg/core.py"]["tracked"] is True
+    assert recs["pkg/untracked.py"]["tracked"] is False
+    assert "git_blob" not in recs["pkg/untracked.py"]  # there is none to record
+    assert "git_blob" in recs["pkg/core.py"]
+
+    # fs mode has no index, so the question does not arise and nothing is claimed
+    fs = resolve_scope(repo / "pkg", use_git=False)
+    assert fs["files"] and all("tracked" not in f for f in fs["files"])
+
+
+# -- D2: membership named, not adopted ----------------------------------------
+
+def test_a_gitignored_module_is_named_and_not_quietly_adopted(repo, tmp_path, capsys):
+    (repo / "pkg" / "generated_version.py").write_text('def v():\n    return "1.2.3"\n')
+    graph, meta = _build(repo, tmp_path / "g.json")
+
+    # the repo says this file is not part of the tree; the manifest does not overrule it
+    assert "pkg/generated_version.py" not in _files(meta)
+    # …and the graph says so out loud instead of leaving a hole
+    unlisted = graph["provenance"]["inputs"]["unlisted"]
+    assert unlisted["count"] == 1
+    assert unlisted["sample"] == ["pkg/generated_version.py"]
+    assert "not listed in the input manifest" in capsys.readouterr().err
+
+
+def test_the_count_check_stays_silent_on_exactly_this_state(repo, tmp_path):
+    """The conservation law cannot catch it, which is why this check exists."""
+    (repo / "pkg" / "generated_version.py").write_text('def v():\n    return "1.2.3"\n')
+    graph, _ = _build(repo, tmp_path / "g.json")
+    from codemap.diagnostics import module_count_diagnostic
+    from codemap.store import load
+
+    g = load(str(tmp_path / "g.json"))
+    modules = sum(1 for n in g.nodes.values() if n.kind == "module")
+    assert modules == graph["provenance"]["inputs"]["python_files"] == 3
+    assert module_count_diagnostic(g) is None       # right to be silent: it agrees
+    assert scope_membership_diagnostic(g)["code"] == SCOPE_MEMBERSHIP
+
+
+# -- the trap: the two sides do not share an origin ----------------------------
+
+def test_a_src_layout_is_not_a_violation(tmp_path):
+    """Node paths are root-relative to the graph's base, manifest paths to the repo.
+
+    On `src/pkg` those differ by a segment, and comparing the strings as they stand
+    called both files of a healthy build unlisted — 2 of 2, measured before the fix.
+    """
+    if not shutil.which("git"):
+        pytest.skip("git not available")
+    (tmp_path / "src" / "pkg").mkdir(parents=True)
+    (tmp_path / "src" / "pkg" / "__init__.py").write_text("")
+    (tmp_path / "src" / "pkg" / "core.py").write_text("def a():\n    return 1\n")
+    (tmp_path / "tests").mkdir()
+    (tmp_path / "tests" / "test_core.py").write_text("from pkg.core import a\n")
+    _git(tmp_path, "init", "-q")
+    _git(tmp_path, "config", "user.email", "t@t")
+    _git(tmp_path, "config", "user.name", "t")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-qm", "init")
+
+    out = tmp_path / "s.json"
+    assert cli.main(["build", str(tmp_path / "src" / "pkg"), "-o", str(out)]) == 0
+    core_only = json.loads(out.read_text(encoding="utf-8"))
+    assert cli.main(["build", str(tmp_path / "src" / "pkg"), "--consumer",
+                     str(tmp_path / "tests"), "-o", str(out)]) == 0
+    repo_scoped = json.loads(out.read_text(encoding="utf-8"))
+
+    assert core_only["provenance"]["inputs"]["unlisted"]["count"] == 0
+    assert repo_scoped["provenance"]["inputs"]["unlisted"]["count"] == 0
+
+
+def test_a_file_outside_the_root_is_reduced_to_a_bare_name(tmp_path):
+    """The files this check catches are the ones most likely to be absolute — and the
+    provenance block refuses an absolute path by contract, so a naive record would turn
+    the diagnostic into a build crash."""
+    scope = {"root": str(tmp_path), "files": [{"path": "pkg/core.py"}]}
+    result = unlisted_files(["pkg/core.py", "/elsewhere/decoy/impostor.py"], scope)
+
+    assert result["count"] == 1
+    assert result["sample"] == ["impostor.py"]      # not the absolute path
+    assert result["outside_root"] is True
+    # the contract that would have been violated (build_provenance raises on absolutes)
+    block = build_provenance(tier="fast", inputs={"python_files": 1, "unlisted": result})
+    assert block["inputs"]["unlisted"]["outside_root"] is True
+
+
+# -- zero is a statement; unknown is an omission -------------------------------
+
+def test_zero_is_stated_and_no_manifest_is_left_unstated(repo, tmp_path, monkeypatch):
+    graph, _ = _build(repo, tmp_path / "clean.json")
+    assert graph["provenance"]["inputs"]["unlisted"] == {
+        "count": 0, "sample": [], "outside_root": False}
+
+    from codemap import cli as cli_mod
+    monkeypatch.setattr(cli_mod, "_resolve_scope_quietly", lambda args: None)
+    out = tmp_path / "noscope.json"
+    assert cli.main(["build", str(repo / "pkg"), "-o", str(out)]) == 0
+    unresolved = json.loads(out.read_text(encoding="utf-8"))
+    assert "unlisted" not in unresolved["provenance"]["inputs"], (
+        "no manifest means the build could not compare — writing a zero there would "
+        "turn an unknown into a clean bill of health")
+
+
+def test_the_diagnostic_reports_nothing_when_there_is_nothing_to_report():
+    class _G:
+        provenance = {"inputs": {"unlisted": {"count": 0, "sample": [],
+                                              "outside_root": False}}}
+
+    assert scope_membership_diagnostic(_G()) is None
+    _G.provenance = {"inputs": {}}                  # pre-R1-C41 graph
+    assert scope_membership_diagnostic(_G()) is None

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"