codmap 0.0.9__tar.gz → 0.0.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.9
+Version: 0.0.11
 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, **752 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 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 &
@@ -167,6 +167,9 @@ codemap build ./yourpkg -o graph.json
 # repo-scoped: add consumers (tests/examples) + docs for blast-radius/impact
 codemap build ./yourpkg --deep --mode full --consumer ./tests --docs ./docs -o graph.json
 
+# deep tier: union N independent samples (one build misses a real edge ~1 time in 4)
+codemap build ./yourpkg --deep --repeat 3 -o graph.json
+
 # ask about a symbol (JSON by default; --format text for humans)
 codemap query analyze_zones --graph graph.json
 
@@ -262,7 +265,17 @@ build says so in its own diagnostics, and `codemap diff` says so when both sides
 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).
+**How many times to build.** A consumer measured 175 full deep builds of one tree and found a real
+edge present in **75 %** of them; eight builds here agreed (5 of 8, the same edge, and nothing else
+unstable among 13 675). So one build misses such an edge about 1 time in 4, two builds 1 in 16, three
+1 in 64. `codemap build --deep --repeat N` builds N samples — each in a fresh interpreter, the
+regime the share was measured in; in-process repeats come in correlated streaks — and unions them: an edge seen in fewer
+than N runs carries `extras.seen`, `provenance.samples` records N and how many edges varied, and the
+note on the graph says both. Refused out loud on the fast tier (byte-stable already) and together with
+`--incremental` (a spliced graph cannot be resampled).
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md),
+[gaps/deep_tier_union_by_repeat_2026-09-04.md](gaps/deep_tier_union_by_repeat_2026-09-04.md).
 
 ## Dogfooding
 

{codmap-0.0.9 → codmap-0.0.11}/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, **752 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 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 &
@@ -131,6 +131,9 @@ codemap build ./yourpkg -o graph.json
 # repo-scoped: add consumers (tests/examples) + docs for blast-radius/impact
 codemap build ./yourpkg --deep --mode full --consumer ./tests --docs ./docs -o graph.json
 
+# deep tier: union N independent samples (one build misses a real edge ~1 time in 4)
+codemap build ./yourpkg --deep --repeat 3 -o graph.json
+
 # ask about a symbol (JSON by default; --format text for humans)
 codemap query analyze_zones --graph graph.json
 
@@ -226,7 +229,17 @@ build says so in its own diagnostics, and `codemap diff` says so when both sides
 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).
+**How many times to build.** A consumer measured 175 full deep builds of one tree and found a real
+edge present in **75 %** of them; eight builds here agreed (5 of 8, the same edge, and nothing else
+unstable among 13 675). So one build misses such an edge about 1 time in 4, two builds 1 in 16, three
+1 in 64. `codemap build --deep --repeat N` builds N samples — each in a fresh interpreter, the
+regime the share was measured in; in-process repeats come in correlated streaks — and unions them: an edge seen in fewer
+than N runs carries `extras.seen`, `provenance.samples` records N and how many edges varied, and the
+note on the graph says both. Refused out loud on the fast tier (byte-stable already) and together with
+`--incremental` (a spliced graph cannot be resampled).
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md),
+[gaps/deep_tier_union_by_repeat_2026-09-04.md](gaps/deep_tier_union_by_repeat_2026-09-04.md).
 
 ## Dogfooding
 

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

@@ -83,6 +83,24 @@ def _graph_from(args):
 
 def _cmd_build(args) -> int:
     incr_info = None
+    repeat = getattr(args, "repeat", None)
+    repeat = 1 if repeat is None else repeat
+    # R1-C45 / D7–D8: refused out loud, never swallowed. The fast tier is byte-stable and
+    # CI pins it, so N runs there buy nothing and cost N minutes; and an incremental graph's
+    # spliced part is an earlier build's sample by definition (R1-C43), so resampling only
+    # the affected modules would leave `seen` relative to different N on neighbouring edges.
+    if repeat < 1:
+        print("error: --repeat must be >= 1", file=sys.stderr)
+        return 2
+    if repeat > 1 and not args.deep:
+        print(f"error: --repeat {repeat} needs --deep — the fast tier is byte-stable, so "
+              "repeating it unions identical samples", file=sys.stderr)
+        return 2
+    if repeat > 1 and getattr(args, "incremental", False):
+        print(f"error: --repeat {repeat} cannot be combined with --incremental — the spliced "
+              "part of an incremental graph is an earlier build's sample and cannot be "
+              "resampled; run a full build", file=sys.stderr)
+        return 2
     if args.consumer or args.docs:
         graph = extract_repo(
             args.path,
@@ -90,11 +108,12 @@ def _cmd_build(args) -> int:
             docs=tuple(args.docs or ()),
             mode=args.mode,
             deep=args.deep,
+            repeat=repeat,
         )
     elif getattr(args, "incremental", False) and args.out:
         graph, incr_info = _incremental_build(args)
     else:
-        graph = extract(args.path, deep=args.deep)
+        graph = extract(args.path, deep=args.deep, repeat=repeat)
     # R1-C25: stamp the input's identity into the graph itself. The scope manifest is
     # resolved here once and reused for the sidecar below — the graph gets the part that
     # must travel with it (scope_id, source commit), the sidecar keeps the rebuild recipe.
@@ -104,7 +123,14 @@ 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=_inputs_with_membership(graph, scope, args))
+        inputs=_inputs_with_membership(graph, scope, args),
+        # R1-C43: this call *overwrites* whatever update_graph stamped, so the flag has
+        # to be re-derived here or it is lost. `unchanged` counts as carried over too —
+        # nothing in that graph was recomputed by this build at all.
+        incremental=(incr_info or {}).get("mode") in ("incremental", "unchanged"),
+        # R1-C45: same trap — the extractor stamped the sample count; carry it, or a
+        # `--repeat 3` graph leaves here saying `runs: 1`.
+        samples=graph.provenance.get("samples"))
     # 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):
@@ -880,6 +906,12 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Reuse an existing --out graph + its scope sidecar: recompute "
                         "only changed modules (R1-C9). Identical to a full build; much "
                         "faster on --deep. Single-package only (no --consumer/--docs).")
+    b.add_argument("--repeat", type=int, default=1, metavar="N",
+                   help="--deep only: run the jedi layer N times and union the samples. "
+                        "One deep build is one sample (a real edge was present in 75%% "
+                        "of single builds, measured); an edge seen in fewer than N runs "
+                        "carries extras.seen, provenance.samples records N. Costs N× the "
+                        "jedi time. Not combinable with --incremental.")
     b.set_defaults(func=_cmd_build)
 
     sc = sub.add_parser("scope", help="Resolve the input scope manifest (scope_id + profile), or --diff two.")

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

@@ -23,6 +23,7 @@ UNREAD_INPUTS = "unread_inputs"
 MODULE_COUNT_MISMATCH = "module_count_mismatch"
 SCOPE_MEMBERSHIP = "scope_membership"
 DEEP_TIER_UNSTABLE = "deep_tier_unstable"
+INCREMENTAL_DEEP_SPLICE = "incremental_deep_splice"
 
 #: 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.
@@ -206,19 +207,86 @@ def deep_tier_diagnostic(graph) -> dict | None:
     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":
+    prov = graph.provenance or {}
+    if prov.get("tier") != "deep":
         return None
+    # R1-C45: a reader deciding whether to trust an *absence* needs the per-edge share and
+    # what N does to it — "roughly one run in three" named the noise and not its remedy.
+    # The 75 % is stated as measured on one tree for one edge (126 of 168 full builds,
+    # issue #16; 5 of 8 here), never as a property of the tier: the consumer's own batches
+    # ranged from 1 of 7 to 7 of 7, and eight builds cannot see a 95 % edge at all.
+    samples = prov.get("samples") or {}
+    runs = samples.get("runs") or 1
+    if runs >= 2:
+        unstable = samples.get("unstable", 0)
+        residual = 0.25 ** runs
+        return {
+            "code": DEEP_TIER_UNSTABLE,
+            "severity": NOTE,
+            "tier": "deep",
+            "samples": runs,
+            "unstable": unstable,
+            "consequence": ("Edges carrying `extras.seen` are the ones the tier is unsure "
+                            "about; everything else was present in every run."),
+            "message": (
+                f"union of {runs} deep (jedi) samples of one tree: {unstable} edge(s) "
+                f"were seen in fewer than {runs} runs and carry `extras.seen`. At the "
+                f"measured per-run rate (a real edge present in 75 % of single builds) "
+                f"an edge missed by all {runs} runs has probability about "
+                f"{residual * 100:.2g} %."
+            ),
+        }
     return {
         "code": DEEP_TIER_UNSTABLE,
         "severity": NOTE,
         "tier": "deep",
+        "samples": 1,
         "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."),
+                        "of a few jedi-resolved edges between two deep graphs as tool "
+                        "noise rather than a change in the code, and do not read a "
+                        "missing call or attribute edge in one build as absence."),
         "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."
+            "built on the deep (jedi) tier, which is not byte-stable — one build is one "
+            "sample. Measured on an 88-module tree, a real `accesses` edge was present in "
+            "126 of 168 full builds (75 %): one build misses such an edge about 1 time in "
+            "4, two builds 1 in 16, three 1 in 64. `build --repeat N` unions N samples "
+            "and marks what varied."
+        ),
+    }
+
+
+def incremental_splice_diagnostic(graph) -> dict | None:
+    """Say when a deep graph carries regions this build did not recompute (R1-C43).
+
+    Sibling of :func:`deep_tier_diagnostic`, and the reason it is a separate code: that
+    one says *this graph is one sample*, which a reader can act on by building again.
+    This one says the sample is **frozen** — building again incrementally returns it
+    unchanged, so the standard remedy silently does nothing.
+
+    Measured on an 88-module package: from a graph missing one real `accesses` edge,
+    five consecutive incremental builds recovered it **0 times** while full builds of
+    the very same tree recovered it **5 of 5**. And the miss defends itself — the
+    invalidation rule that would have recomputed the writer reads the old graph, where
+    the edge is exactly what is absent (gaps/incremental_noise_persistence_2026-09-02.md).
+
+    Fast tier is excluded on purpose: there the splice is exact and byte-identity to a
+    full build is pinned by the suite, so there is no sample to freeze.
+    """
+    prov = graph.provenance or {}
+    if prov.get("tier") != "deep" or not prov.get("incremental"):
+        return None
+    return {
+        "code": INCREMENTAL_DEEP_SPLICE,
+        "severity": NOTE,
+        "tier": "deep",
+        "consequence": ("Do not read a missing call or attribute edge here as evidence "
+                        "that nothing depends on a symbol, and do not test that by "
+                        "rebuilding incrementally — only a full rebuild resamples."),
+        "message": (
+            "parts of this deep graph were spliced from an earlier build rather than "
+            "recomputed: on this tier that carries the earlier build's jedi sample "
+            "forward, including anything it missed — measured at 0 recoveries in 5 "
+            "incremental builds against 5 of 5 full builds of the same tree."
         ),
     }
 
@@ -307,7 +375,8 @@ 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), deep_tier_diagnostic(graph))
+              scope_membership_diagnostic(graph), deep_tier_diagnostic(graph),
+              incremental_splice_diagnostic(graph))
     return [d for d in checks if d is not None]
 
 

{codmap-0.0.9 → codmap-0.0.11}/codemap/extract/behavior.py

@@ -78,6 +78,9 @@ def add_behavior(graph, griffe_root, target_pkg: str, *, deep: bool = False,
         modmembers = set(mod.members.keys())
         script = _jedi_script(source, fp, project) if deep else None
         nested: dict[tuple[str, str], dict] = {}
+        # R1-C46: the surviving definition says which earlier bodies it replaced. Stamped
+        # here because this pass holds the AST; the walkers below skip those bodies.
+        _stamp_shadows(graph, tree, modpath)
         for fnode, class_stack, scope in _named_functions_scoped(tree):
             node_id = _node_id(modpath, class_stack, fnode.name)
             local = local_imports.get(id(fnode))
@@ -349,17 +352,105 @@ def _class_members(mod, class_stack, modules) -> dict:
 
 # -- ast scope walking -------------------------------------------------------
 
+_DEF_NODES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+# Decorators that make a repeated binding of one name legitimate (R1-C46 / D2): an
+# `@overload` *before* the implementation, a property accessor or a singledispatch
+# registration *after* the first binding. Matched on the decorator's last dotted segment
+# with any call stripped, so `typing.overload` and `@f.register(int)` both count.
+_EXEMPT_EARLIER = frozenset({"overload"})
+_EXEMPT_LATER = frozenset({"setter", "getter", "deleter", "register"})
+
+
+def _decorator_tails(node) -> list[str]:
+    out = []
+    for d in node.decorator_list:
+        text = ast.unparse(d).split("(", 1)[0]
+        out.append(text.rsplit(".", 1)[-1])
+    return out
+
+
+def _rebinding_is_legitimate(earlier, later) -> bool:
+    if later.name == "_":
+        return True  # singledispatch convention
+    if any(t in _EXEMPT_EARLIER for t in _decorator_tails(earlier)):
+        return True
+    return any(t in _EXEMPT_LATER for t in _decorator_tails(later))
+
+
+def _shadow_map(tree) -> tuple[set[int], dict, list[tuple[int, int]]]:
+    """Definitions that a later definition of the same name in the same body replaces.
+
+    R1-C46: griffe keeps the **last** body of a name defined twice and drops the first
+    without a word; the AST walkers here used to visit *both* and attribute both bodies'
+    calls to the one surviving node — an edge from code that can never run. So every
+    walker skips the shadowed subtree, and the surviving node records what it shadowed.
+
+    Only a *direct* statement of a module, class or function body shadows or is
+    shadowed. A definition under ``if`` / ``try`` / ``with`` is conditional on either
+    side (``if TYPE_CHECKING:``, an ``except ImportError`` fallback): it neither replaces
+    nor is replaced, and both bodies keep being walked — the honest over-approximation.
+
+    Returns ``(ids of AST nodes to skip, records, dead line ranges)``; ``records`` maps
+    ``(scope chain, name) -> {"linenos": [...], "node": bool}`` where ``node`` says the
+    chain is classes only, i.e. the survivor is a definition node the graph holds.
+    """
+    skip: set[int] = set()
+    records: dict[tuple[tuple[str, ...], str], dict] = {}
+    ranges: list[tuple[int, int]] = []
+
+    def walk(node, scope: list[str], kinds: list[str]) -> None:
+        if isinstance(node, (ast.Module, *_DEF_NODES)):
+            last: dict[str, ast.AST] = {}
+            for stmt in node.body:
+                if not isinstance(stmt, _DEF_NODES):
+                    continue
+                prev = last.get(stmt.name)
+                if prev is not None and not _rebinding_is_legitimate(prev, stmt):
+                    skip.add(id(prev))
+                    ranges.append((prev.lineno, getattr(prev, "end_lineno", prev.lineno)))
+                    rec = records.setdefault((tuple(scope), stmt.name),
+                                             {"linenos": [], "node": all(k == "c" for k in kinds)})
+                    rec["linenos"].append(prev.lineno)
+                last[stmt.name] = stmt
+        for child in ast.iter_child_nodes(node):
+            if id(child) in skip:
+                continue
+            if isinstance(child, ast.ClassDef):
+                walk(child, scope + [child.name], kinds + ["c"])
+            elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                walk(child, scope + [child.name], kinds + ["f"])
+            else:
+                walk(child, scope, kinds)
+
+    walk(tree, [], [])
+    return skip, records, ranges
+
+
+def _stamp_shadows(graph, tree, prefix: str) -> None:
+    """Write ``extras.shadows`` on every surviving definition node under ``prefix``."""
+    for (scope, name), rec in _shadow_map(tree)[1].items():
+        if not rec["node"]:
+            continue
+        nid = ".".join([prefix, *scope, name])
+        if nid in graph.nodes:
+            graph.nodes[nid].extras["shadows"] = sorted(rec["linenos"])
+
+
 def _named_functions(tree):
     """Yield (FunctionDef, [class names]) for functions reachable as definitions.
 
     Tracks the class nesting so we can rebuild canonical ids. Functions nested
     inside other functions are still yielded but filtered out by the caller
-    (their id won't match a graph node).
+    (their id won't match a graph node). A definition shadowed by a later one of
+    the same name in the same body is not yielded (R1-C46, :func:`_shadow_map`).
     """
     results = []
+    skip = _shadow_map(tree)[0]
 
     def visit(node, class_stack):
         for child in ast.iter_child_nodes(node):
+            if id(child) in skip:
+                continue
             if isinstance(child, ast.ClassDef):
                 visit(child, class_stack + [child.name])
             elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -845,9 +936,12 @@ def _named_functions_scoped(tree):
     because `dataflow`/`dispatch`/`attrflow` unpack the two-tuple.
     """
     results = []
+    skip = _shadow_map(tree)[0]  # R1-C46: a shadowed body is not walked
 
     def visit(node, class_stack, scope):
         for child in ast.iter_child_nodes(node):
+            if id(child) in skip:
+                continue
             if isinstance(child, ast.ClassDef):
                 visit(child, class_stack + [child.name], scope + [child.name])
             elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):

{codmap-0.0.9 → codmap-0.0.11}/codemap/extract/griffe_extractor.py

@@ -18,6 +18,7 @@ Emits (M0 + M1 + M1.5):
 from __future__ import annotations
 
 import ast
+import multiprocessing
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -29,6 +30,7 @@ from codemap.extract.behavior import add_behavior
 from codemap.extract.dataflow import add_dataflow
 from codemap.extract.dispatch import add_dispatch, add_family_links
 from codemap.extract.gsource import NESTED_IMPORT_HINT, module_file, module_identity
+from codemap.extract.union import merge_samples
 from codemap.provenance import build_provenance
 from codemap.model import Edge, Graph, Node
 
@@ -138,20 +140,61 @@ def add_behavioral_layer(graph, root, module_name, search_path, *, deep: bool,
                  only=attr_only)
 
 
-def extract(package_path: str | Path, *, deep: bool = False) -> Graph:
+def _sample_worker(package_path: str, deep: bool) -> dict:
+    """One full extraction in a child interpreter; returns the graph as a dict (R1-C45)."""
+    graph, root, module_name, search_path = build_structural(package_path)
+    add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
+    return graph.to_dict()
+
+
+def collect_samples(package_path, *, deep: bool, runs: int,
+                    workers: int | None = None) -> list[Graph]:
+    """``runs`` independent samples of ``package_path``, each in a fresh interpreter.
+
+    Lives here, beside the two functions the worker calls, so ``extract/union.py`` stays
+    a pure merge and the import graph stays acyclic — codemap's own ``no_lazy_cycles``
+    contract caught the first draft, which reached back from ``union`` with a
+    function-local import. ``workers`` bounds concurrency (default: the machine's core
+    count, capped at ``runs``). Spawn, not fork: a forked child would inherit exactly the
+    state that makes an in-process repeat correlate with the pass before it.
+    """
+    ctx = multiprocessing.get_context("spawn")
+    procs = max(1, min(runs, workers or os.cpu_count() or 1))
+    with ctx.Pool(processes=procs) as pool:
+        dicts = pool.starmap(_sample_worker, [(str(package_path), deep)] * runs)
+    samples = []
+    for d in dicts:
+        g = Graph.from_dict(d)
+        g.loaded_schema = None  # a fresh build, not a file — keep schema_diagnostic quiet
+        samples.append(g)
+    return samples
+
+
+def extract(package_path: str | Path, *, deep: bool = False, repeat: int = 1) -> Graph:
     """Build a code graph from a Python package directory.
 
     ``deep=True`` runs the jedi-backed call resolver (M5) — richer call-graph
     (local-variable type inference) at ~1 min build cost; default is the fast
     ast tier (sub-second). See ``extract/behavior.py``.
+
+    ``repeat=N`` (R1-C45) builds N samples — **each in a fresh interpreter**, the
+    regime whose recovery share was measured; in-process repeats come in correlated
+    streaks (see ``extract/union.py``) — and unions them: a deep build is one sample
+    of jedi's bounded inference, and an edge seen in fewer than N runs carries
+    ``extras.seen``.
     """
-    graph, root, module_name, search_path = build_structural(package_path)
-    add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
+    if repeat > 1:
+        graph, stats = merge_samples(collect_samples(package_path, deep=deep, runs=repeat))
+    else:
+        graph, root, module_name, search_path = build_structural(package_path)
+        add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
+        stats = {"runs": 1}
     # R1-C25: even a library-built graph says which tool and which tier made it. The
     # input identity (scope_id, source commit) is added by whoever resolved the scope —
     # `extract` deliberately does not hash the tree a second time.
     graph.provenance = build_provenance(tier="deep" if deep else "fast",
-                                        inputs=graph.provenance.get("inputs"))
+                                        inputs=graph.provenance.get("inputs"),
+                                        samples=stats)
     return graph
 
 

{codmap-0.0.9 → codmap-0.0.11}/codemap/extract/roots.py

@@ -32,7 +32,7 @@ import os
 import re
 from pathlib import Path
 
-from codemap.extract.behavior import _arg_contract, _arg_shape
+from codemap.extract.behavior import _arg_contract, _arg_shape, _shadow_map
 from codemap.extract.griffe_extractor import extract
 from codemap.provenance import canonicalize
 from codemap.model import Edge, Graph, Node
@@ -78,18 +78,20 @@ def extract_repo(
     docs: tuple[str | Path, ...] = (),
     mode: str = "thin",
     deep: bool = False,
+    repeat: int = 1,
 ) -> Graph:
     """Build a repo-scoped graph: core package + consumer roots + doc roots.
 
     ``core`` is analysed exactly as the single-package extractor (griffe, plus the
-    behavioral pass when ``deep``). ``consumers`` and ``docs`` are extra root
-    directories scanned for references into the core. ``mode`` is ``"thin"`` or
+    behavioral pass when ``deep``, unioned over ``repeat`` samples — R1-C45).
+    ``consumers`` and ``docs`` are extra root directories scanned for references into
+    the core; those scans are deterministic and run once. ``mode`` is ``"thin"`` or
     ``"full"`` (see module docstring).
     """
     if mode not in ("thin", "full"):
         raise ValueError(f"mode must be 'thin' or 'full', got {mode!r}")
 
-    graph = extract(core, deep=deep)
+    graph = extract(core, deep=deep, repeat=repeat)
     core_pkg = graph.target
     for node in graph.nodes.values():
         node.extras.setdefault("root", "core")
@@ -266,8 +268,14 @@ def _scan_consumer_module(graph, py, base, label, tree, index, mode, origin=None
         if isinstance(n, ast.Attribute) and isinstance(n.value, ast.Attribute)
     }
     func_ranges = _func_ranges(tree) if mode == "full" else []
+    # R1-C46: a use inside a body that a later definition replaced is not a use — it
+    # would attribute a reference (or a call) to code that never runs, in either mode.
+    dead = _shadow_map(tree)[2]
 
     for node in ast.walk(tree):
+        line = getattr(node, "lineno", None)
+        if line is not None and any(a <= line <= b for a, b in dead):
+            continue
         target = None
         use_node = node
         if isinstance(node, ast.Name) and node.id in symbol_map:
@@ -375,14 +383,28 @@ def _materialize_defs(graph, tree, mod_id, label, file: str | None = None) -> No
                             extras={"root": label}))
         parent = ".".join([mod_id, *class_stack]) if class_stack else mod_id
         graph.add_edge(Edge("contains", parent, node_id))
+    # R1-C46: one node and one `contains` per definition that can run (issue #16 found
+    # the record twice); the survivor says which earlier bodies it replaced.
+    for (scope, name), rec in _shadow_map(tree)[1].items():
+        if rec["node"]:
+            nid = ".".join([mod_id, *scope, name])
+            if nid in graph.nodes:
+                graph.nodes[nid].extras["shadows"] = sorted(rec["linenos"])
 
 
 def _defs(tree):
-    """Yield (def-node, [enclosing class/def names]) for top-level & nested defs."""
+    """Yield (def-node, [enclosing class/def names]) for top-level & nested defs.
+
+    A body shadowed by a later definition of the same name in the same scope is not
+    yielded (R1-C46, :func:`_shadow_map`).
+    """
     results = []
+    skip = _shadow_map(tree)[0]
 
     def visit(node, stack):
         for child in ast.iter_child_nodes(node):
+            if id(child) in skip:
+                continue
             if isinstance(child, ast.ClassDef):
                 results.append((child, list(stack)))
                 visit(child, stack + [child.name])
@@ -399,9 +421,12 @@ def _defs(tree):
 def _func_ranges(tree):
     """(start, end, node_id) for each def, longest-first, to place a use by line."""
     ranges = []
+    skip = _shadow_map(tree)[0]  # R1-C46: a shadowed body owns no uses
 
     def visit(node, mod_stack):
         for child in ast.iter_child_nodes(node):
+            if id(child) in skip:
+                continue
             if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
                 nid = ".".join([*mod_stack, child.name])
                 end = getattr(child, "end_lineno", child.lineno)