codmap 0.0.10__tar.gz → 0.0.12__tar.gz

{codmap-0.0.10/codmap.egg-info → codmap-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.10
+Version: 0.0.12
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -161,12 +161,15 @@ Optional extras: `mcp` (Model Context Protocol server), `scip` (protobuf, for SC
 ## Quickstart
 
 ```bash
-# build the canonical graph of a package
+# build the canonical graph of a package (its directory name is the package name every id starts with)
 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,19 @@ 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). With `--incremental`
+and `watch`, N becomes a property of the chain and every place the chain samples — base, fallback, each
+tick's recompute — samples N times; measured on twenty real commits, that is what removes the chain's misses,
+and a periodic full rebuild does not.
+
+**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.10 → codmap-0.0.12}/README.md

@@ -125,12 +125,15 @@ Optional extras: `mcp` (Model Context Protocol server), `scip` (protobuf, for SC
 ## Quickstart
 
 ```bash
-# build the canonical graph of a package
+# build the canonical graph of a package (its directory name is the package name every id starts with)
 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,19 @@ 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). With `--incremental`
+and `watch`, N becomes a property of the chain and every place the chain samples — base, fallback, each
+tick's recompute — samples N times; measured on twenty real commits, that is what removes the chain's misses,
+and a periodic full rebuild does not.
+
+**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.10 → codmap-0.0.12}/codemap/cli.py

@@ -83,18 +83,37 @@ 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: 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. With --incremental the flag
+    # is allowed since R1-C47: N is a property of the chain, and a different N restarts it.
+    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 args.consumer or args.docs:
+        if getattr(args, "incremental", False):
+            # R1-C44 / D6: the flag used to be swallowed here without a word. Not an
+            # error — a stated boundary: the incremental path is single-package.
+            print("[note] --incremental was not applied: --consumer/--docs make this a "
+                  "repo-scoped build, which is always full (the incremental path is "
+                  "single-package only)", file=sys.stderr)
         graph = extract_repo(
             args.path,
             consumers=tuple(args.consumer or ()),
             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.
@@ -108,7 +127,10 @@ def _cmd_build(args) -> int:
         # 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"))
+        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):
@@ -179,12 +201,15 @@ def _incremental_build(args):
     old_meta = read_meta(args.out)
     old_scope = (old_meta or {}).get("scope")
     if not (Path(args.out).exists() and old_scope):
-        return extract(args.path, deep=args.deep), {"mode": "full", "affected": []}
+        return extract(args.path, deep=args.deep, repeat=getattr(args, "repeat", None) or 1), \
+            {"mode": "full", "affected": []}
     old_graph = store.load(args.out)
     new_scope = resolve_scope(args.path)
+    repeat = getattr(args, "repeat", None) or 1
     if old_graph.target != Path(args.path).resolve().name:
-        return extract(args.path, deep=args.deep), {"mode": "full", "affected": []}
-    return update_graph(old_graph, args.path, old_scope, new_scope, deep=args.deep)
+        return extract(args.path, deep=args.deep, repeat=repeat), {"mode": "full", "affected": []}
+    return update_graph(old_graph, args.path, old_scope, new_scope, deep=args.deep,
+                        repeat=repeat)
 
 
 def _watch_build_argv(args) -> list[str]:
@@ -197,6 +222,8 @@ def _watch_build_argv(args) -> list[str]:
     argv = ["build", args.path, "-o", args.out, "--incremental"]
     if args.deep:
         argv.append("--deep")
+    if (getattr(args, "repeat", None) or 1) > 1:
+        argv += ["--repeat", str(args.repeat)]  # R1-C47: N is a property of the chain
     for c in args.consumer or ():
         argv += ["--consumer", c]
     for d in args.docs or ():
@@ -239,6 +266,7 @@ def _cmd_watch(args) -> int:
     build_args = _argparse.Namespace(
         path=args.path, out=args.out, deep=args.deep, consumer=args.consumer,
         docs=args.docs, mode=args.mode, incremental=True,
+        repeat=getattr(args, "repeat", None) or 1,
         _argv=_watch_build_argv(args))
 
     reported: set[str] = set()
@@ -869,7 +897,9 @@ def build_parser() -> argparse.ArgumentParser:
     sub = p.add_subparsers(dest="command", required=True)
 
     b = sub.add_parser("build", help="Build the canonical graph from a package path.")
-    b.add_argument("path", help="Path to the package directory (holds __init__.py).")
+    b.add_argument("path", help="Path to the package directory (holds __init__.py). Its "
+                                "directory name is the package name every node id starts "
+                                "with — a copy under another name answers to that name.")
     b.add_argument("-o", "--out", help="Write graph.json here (default: stdout JSON).")
     b.add_argument("--deep", action="store_true",
                    help="Deep call resolution via jedi (richer, ~1 min; default fast).")
@@ -882,8 +912,17 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Consumer granularity: thin=per-file (default), full=per-function.")
     b.add_argument("--incremental", action="store_true",
                    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).")
+                        "only changed modules (R1-C9). Byte-identical to a full build on "
+                        "the fast tier; on --deep it carries the earlier build's jedi "
+                        "sample forward (docs/incremental.md). 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, in parallel. With --incremental N becomes a property "
+                        "of the chain: a different N restarts it from a full build.")
     b.set_defaults(func=_cmd_build)
 
     sc = sub.add_parser("scope", help="Resolve the input scope manifest (scope_id + profile), or --diff two.")
@@ -987,6 +1026,11 @@ def build_parser() -> argparse.ArgumentParser:
     w.add_argument("--docs", action="append", metavar="PATH", help="Docs root. Repeatable.")
     w.add_argument("--mode", choices=["thin", "full"], default="thin",
                    help="Consumer granularity (as for `build`).")
+    w.add_argument("--repeat", type=int, default=1, metavar="N",
+                   help="--deep only: sample the jedi layer N times on every build this "
+                        "loop makes — base, fallback and each tick's recompute (R1-C47). "
+                        "Measured: an incremental chain's misses come from single samples, "
+                        "not from age.")
     w.add_argument("--cycles", type=int, default=None,
                    help="Stop after N polls instead of running forever (CI / testing).")
     _add_poll_options(

{codmap-0.0.10 → codmap-0.0.12}/codemap/diagnostics.py

@@ -207,20 +207,50 @@ 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 jedi-resolved edges between two deep graphs as tool "
-                        "noise rather than a change in the code."),
+                        "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 jedi-resolved edges — measured at roughly "
-            "one run in three on two trees: two per-symbol call counters on one, one "
-            "`accesses` edge of 12190 on the other."
+            "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."
         ),
     }
 

{codmap-0.0.10 → codmap-0.0.12}/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.10 → codmap-0.0.12}/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,69 @@ 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, only=None) -> dict:
+    """One extraction in a child interpreter; returns the graph as a dict (R1-C45).
+
+    ``only`` (a set of module paths) restricts the two jedi passes to those modules —
+    the incremental hook (R1-C9), so a chain can resample just what a tick touched
+    (R1-C47). The structural base is rebuilt in every worker regardless: cheap,
+    deterministic, and cheaper than shipping it across processes.
+    """
+    graph, root, module_name, search_path = build_structural(package_path)
+    add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
+                         behavior_only=only, attr_only=only)
+    return graph.to_dict()
+
+
+def collect_samples(package_path, *, deep: bool, runs: int,
+                    workers: int | None = None, only=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, set(only) if only else None)] * 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.10 → codmap-0.0.12}/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)