codmap 0.0.11__tar.gz → 0.0.13__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.11
+Version: 0.0.13
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -85,7 +85,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5
@@ -161,7 +161,7 @@ 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
@@ -271,8 +271,10 @@ unstable among 13 675). So one build misses such an edge about 1 time in 4, two
 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).
+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).

{codmap-0.0.11 → codmap-0.0.13}/README.md

@@ -49,7 +49,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5
@@ -125,7 +125,7 @@ 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
@@ -235,8 +235,10 @@ unstable among 13 675). So one build misses such an edge about 1 time in 4, two
 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).
+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).

{codmap-0.0.11 → codmap-0.0.13}/codemap/arch.py

@@ -207,7 +207,8 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
             worst = sorted(lazy, key=lambda c: (len(c), c))
             violations.append(Violation(
                 "no_lazy_cycles",
-                f"{len(lazy)} dependency cycle(s) closed only by a function-local import",
+                f"{len(lazy)} dependency cycle(s) closed only by a non-eager import "
+                f"(function-local, or under `if TYPE_CHECKING:`)",
                 modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
             ))
 

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

@@ -85,10 +85,9 @@ 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.
+    # 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
@@ -96,12 +95,13 @@ def _cmd_build(args) -> int:
         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:
+        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 ()),
@@ -201,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]:
@@ -219,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 ():
@@ -261,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()
@@ -891,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).")
@@ -904,14 +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. Not combinable with --incremental.")
+                        "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.")
@@ -1015,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.11 → codmap-0.0.13}/codemap/extract/griffe_extractor.py

@@ -140,15 +140,22 @@ def add_behavioral_layer(graph, root, module_name, search_path, *, deep: bool,
                  only=attr_only)
 
 
-def _sample_worker(package_path: str, deep: bool) -> dict:
-    """One full extraction in a child interpreter; returns the graph as a dict (R1-C45)."""
+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)
+    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) -> list[Graph]:
+                    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
@@ -161,7 +168,8 @@ def collect_samples(package_path, *, deep: bool, runs: int,
     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)
+        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)
@@ -257,8 +265,9 @@ def _input_report(graph, pkg_dir: Path, root: Path, walk) -> dict:
     return report
 
 
-def _source_import_targets(module) -> list[tuple[str, str]]:
-    """``(target, scope)`` for the imports griffe's module-level map does not carry.
+def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
+    """``([(target, scope)], eager targets)`` — the imports griffe's module-level map does
+    not carry, and the targets it carries correctly.
 
     Two families, one traversal, one parse — griffe records neither, and both used to be
     invisible to the import graph:
@@ -274,6 +283,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     - **imports written in a class body** → scope ``"module"``. They run at
       class-definition time, i.e. at import time, so they are ordinary eager dependencies
       and *can* close a real import cycle. griffe does not record them either (measured).
+    - **imports under `if TYPE_CHECKING:`** (R1-C48 / issue #18) → scope
+      ``"type_checking"``. griffe *does* record these, as module-level — it has no notion
+      of a condition that is always false at run time — so the second value returned is
+      the set of targets imported at plain module level: the caller demotes griffe's entry
+      for a target that appears only under ``TYPE_CHECKING``.
 
     Cost discipline, and it is not theoretical: the first version of this walked every
     function's subtree separately, which is quadratic in nesting and cost the dogfood
@@ -285,13 +299,13 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     try:
         src = module.source
     except Exception:                       # no source (namespace dir, synthetic)
-        return []
+        return [], set()
     if not NESTED_IMPORT_HINT.search(src):
-        return []
+        return [], set()
     try:
         tree = ast.parse(src)
     except (SyntaxError, ValueError):
-        return []                            # unreadable: D2's report owns this file
+        return [], set()                     # unreadable: D2's report owns this file
     modpath = module.canonical_path
     f = module_file(module)
     is_pkg = f is not None and f.name == "__init__.py"
@@ -304,9 +318,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
         return node.module or ""
 
     out: list[tuple[str, str]] = []
+    eager: set[str] = set()   # targets imported at plain module level (griffe has them)
 
     def visit(node, scope: str | None) -> None:
-        """``scope`` is None at module level (griffe has those), else module|function."""
+        """``scope`` is None at module level (griffe has those), else
+        module|function|type_checking."""
         for child in ast.iter_child_nodes(node):
             if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 visit(child, "function")
@@ -314,9 +330,21 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 # A class body runs at import time — unless we are already inside a
                 # function, in which case the whole thing does not.
                 visit(child, "function" if scope == "function" else "module")
+            elif isinstance(child, ast.If) and scope in (None, "type_checking") \
+                    and (tc := _type_checking_branches(child)) is not None:
+                # R1-C48 (issue #18): `if TYPE_CHECKING:` never runs. Its body is a third
+                # scope; its `else` is ordinary module level. Inside a function the whole
+                # `if` is function-local already and is not looked at.
+                body_scope, else_scope = tc
+                for stmt in child.body:
+                    visit_stmt(stmt, body_scope if body_scope else scope)
+                for stmt in child.orelse:
+                    visit_stmt(stmt, else_scope if else_scope else scope)
             elif isinstance(child, ast.Import):
                 if scope is not None:
                     out.extend((a.name, scope) for a in child.names)
+                else:
+                    eager.update(a.name for a in child.names)
             elif isinstance(child, ast.ImportFrom):
                 target = resolve(child)
                 if not target:
@@ -325,6 +353,8 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 if scope is None:
                     if star:                 # the D3 case: griffe records nothing
                         out.append((target, "module"))
+                    eager.add(target)
+                    eager.update(f"{target}.{a.name}" for a in child.names if a.name != "*")
                     continue
                 # `from pkg.mod import name` → keep the member paths so the resolver walks
                 # down to the containing module exactly as it does for the module-level
@@ -335,19 +365,49 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
             else:
                 visit(child, scope)
 
+    def visit_stmt(stmt, scope: str | None) -> None:
+        """Route one statement through ``visit`` as if it were the only child."""
+        holder = ast.Module(body=[stmt], type_ignores=[])
+        visit(holder, scope)
+
     visit(tree, None)
-    return out
+    return out, eager
+
+
+def _type_checking_branches(node: ast.If) -> tuple[str | None, str | None] | None:
+    """``(scope of body, scope of else)`` for a recognised ``TYPE_CHECKING`` test, else None.
+
+    Recognised, narrowly (design D3): the bare name ``TYPE_CHECKING``, any attribute named
+    ``TYPE_CHECKING`` (``typing.TYPE_CHECKING``, ``t.TYPE_CHECKING``), and ``not`` of either,
+    which swaps the branches. A compound test (``TYPE_CHECKING or X``) is *not* recognised
+    and stays eager: a condition the tool cannot read is judged strictly, never leniently.
+    ``None`` in a slot means "the enclosing scope" (module level).
+    """
+    test, negated = node.test, False
+    if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
+        test, negated = test.operand, True
+    is_tc = ((isinstance(test, ast.Name) and test.id == "TYPE_CHECKING")
+             or (isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"))
+    if not is_tc:
+        return None
+    return (None, "type_checking") if negated else ("type_checking", None)
 
 
 def _collect(graph, obj, root, target_pkg, walk) -> None:
     if obj.kind.value == "module":
         _claim(obj, walk)  # the root claims its own path before any member is walked
         _add_node(graph, obj, root)
+        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports) +
+        # R1-C48 (`if TYPE_CHECKING:`): everything griffe's module-level map does not
+        # carry, or carries under the wrong scope, in one parse.
+        nested, eager = _source_import_targets(obj)
+        type_checking = {tgt for tgt, scope in nested if scope == "type_checking"}
         for name, tgt in (obj.imports or {}).items():
-            walk.imports.append((obj.canonical_path, tgt, "module"))
-        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports):
-        # everything griffe's module-level map does not carry, in one parse.
-        for tgt, scope in _source_import_targets(obj):
+            # griffe files an import under `if TYPE_CHECKING:` as module-level; it never
+            # runs. Demote it unless the same target is also imported eagerly (D2).
+            scope = "type_checking" if tgt in type_checking and tgt not in eager else "module"
+            walk.imports.append((obj.canonical_path, tgt, scope))
+        for tgt, scope in nested:
             walk.imports.append((obj.canonical_path, tgt, scope))
     for name, member in obj.members.items():
         if member.is_alias:
@@ -421,6 +481,13 @@ def _emit_decorated_by(graph, obj) -> None:
 
 # -- pass 2: resolve export + import edges against known nodes ----------------
 
+#: How early an import scope reaches its target: an edge carries the earliest (R1-C29 D2,
+#: R1-C48 D2). ``module`` runs at import time, ``type_checking`` never, ``function`` when
+#: the function runs — the middle one is ordered before ``function`` only so the label
+#: names the construct actually written at module level.
+_SCOPE_RANK = {"module": 0, "type_checking": 1, "function": 2}
+
+
 def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     module_ids = sorted(
         (n.id for n in graph.nodes.values() if n.kind == "module"), key=len, reverse=True
@@ -449,7 +516,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     # the eager import it is. `scope` only ever *weakens* to "function" for a pair that
     # has no module-level import at all — the edge says how the dependency is reached at
     # its earliest, never how it happens to appear last in the walk.
-    ordered = sorted(imports, key=lambda t: t[2] == "function")
+    ordered = sorted(imports, key=lambda t: _SCOPE_RANK.get(t[2], 0))
 
     # pass A — package-qualified targets. Exact, and run first so that a pair reachable
     # both ways is recorded as exact rather than inferred.
@@ -464,7 +531,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
         if key in seen:
             continue
         seen.add(key)
-        extras = {"scope": "function"} if scope == "function" else {}
+        extras = {"scope": scope} if scope != "module" else {}
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
     # pass B — flat layout (R1-C21): sibling modules importing each other by bare name
@@ -481,8 +548,8 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
             continue
         seen.add(key)
         extras = {"resolution": "flat"}
-        if scope == "function":
-            extras["scope"] = "function"
+        if scope != "module":
+            extras["scope"] = scope
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
 

{codmap-0.0.11 → codmap-0.0.13}/codemap/extract/union.py

@@ -36,7 +36,10 @@ An edge seen in fewer than N runs carries ``extras.seen: k``; nothing is written
 ``k == N``, so a single-sample build's edges are byte-identical to what they were. Node
 counters (``calls`` / ``attr_access``) count *sites*, which dedupe into edges — the
 measured node had three counter variants behind one flapping edge — so per node the
-variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: first run).
+variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: the serialized
+counter). Every choice between variants of one key is a **total order** over the candidates
+(:func:`_rank`, :func:`_counter_rank`): the merged graph is a function of the set of
+samples, and the same samples in any order produce the same bytes.
 
 **Every sample is a fresh process.** The share above was measured across processes —
 the consumer's 175 builds and the eight here. Repeating the behavioural layer *inside*
@@ -74,20 +77,30 @@ def _identity(e: Edge) -> tuple:
             json.dumps(e.extras, sort_keys=True, ensure_ascii=False))
 
 
-def _deeper(new: Edge, current: Edge) -> bool:
-    return (new.extras.get("resolution") == "deep"
-            and current.extras.get("resolution") != "deep")
+def _rank(e: Edge) -> tuple:
+    """Total order among the variants of one identity key: ``deep`` beats any other
+    resolution, more call sites beat fewer, and the serialized ``extras`` break what is
+    left — so the winner is a function of the *set* of samples, never of the order they
+    arrived in. The consumer's hint on codemap#17: where two candidates are equally
+    legitimate, 'first one wins' is a dependence on arrival order, and one that a probe
+    permuting the *output* can never see."""
+    ex = e.extras
+    return (ex.get("resolution") == "deep", ex.get("callsites", 0),
+            json.dumps(ex, sort_keys=True, ensure_ascii=False))
+
+
+def _counter_rank(c: dict) -> tuple:
+    return (-c.get("unresolved", 0), c.get("resolved", 0), json.dumps(c, sort_keys=True))
 
 
 def _better_counter(a: dict | None, b: dict | None) -> dict | None:
-    """The counter variant that resolved more sites (``None`` never beats a value)."""
+    """The counter variant that resolved more sites (``None`` never beats a value);
+    a tie is broken by the serialized counter, not by which sample came first."""
     if a is None:
         return b
     if b is None:
         return a
-    ka = (-a.get("unresolved", 0), a.get("resolved", 0))
-    kb = (-b.get("unresolved", 0), b.get("resolved", 0))
-    return b if kb > ka else a
+    return b if _counter_rank(b) > _counter_rank(a) else a
 
 
 def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
@@ -116,7 +129,7 @@ def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
             else:
                 if key not in seen_this_run:
                     entry[0] += 1
-                if _deeper(e, entry[1]):
+                if _rank(e) > _rank(entry[1]):
                     entry[1] = e
             seen_this_run.add(key)
 

{codmap-0.0.11 → codmap-0.0.13}/codemap/incremental.py

@@ -54,10 +54,10 @@ import copy
 from pathlib import Path
 
 from codemap.extract.griffe_extractor import (
-    add_behavioral_layer, build_structural, extract,
+    add_behavioral_layer, build_structural, collect_samples, extract,
 )
-from codemap.extract.union import BEHAVIOR_CALL_RES
-from codemap.model import Graph
+from codemap.extract.union import BEHAVIOR_CALL_RES, merge_samples
+from codemap.model import SPLICED_EDGE_TYPES, Graph
 from codemap.provenance import build_provenance, tool_identity
 from codemap.scope import diff_scopes
 
@@ -75,8 +75,9 @@ _BEHAVIOR_REF_RES = frozenset({"name", "annotation"})
 # it — or the fast tier's byte-identity to a full build (R1-C9) breaks on it.
 _BEHAVIORAL_EXTRAS = ("calls", "control", "complexity", "attr_access", "shadows")
 # Old edge types whose target landing in a changed/removed module makes the source
-# module stale (it must re-resolve). Only the spliced passes matter here.
-_DEP_EDGE_TYPES = frozenset({"calls", "accesses", "references"})
+# module stale (it must re-resolve). Only the spliced passes matter here — and the serve
+# layer reads the same set to know which ops answer from a spliced class (R1-C44).
+_DEP_EDGE_TYPES = SPLICED_EDGE_TYPES
 
 # Above this fraction of modules affected, a full rebuild is cheaper (and trivially
 # correct) — no point splicing most of the graph.
@@ -159,21 +160,38 @@ def _splice_unaffected(new_graph, old_graph, unaffected, module_of) -> None:
                     node.extras[k] = copy.deepcopy(old_extras[k])
 
 
-def _same_builder(provenance: dict, tier: str) -> bool:
-    """Was the old graph produced by *this* codemap, on this tier? (R1-C25)
+def _same_builder(provenance: dict, tier: str, repeat: int = 1) -> str | None:
+    """Why the old graph is *not* from this builder — ``None`` when it is (R1-C25).
 
     A graph with no provenance (pre-0.12) cannot answer, so it is treated as a
     different builder — the conservative direction: a needless full rebuild costs a
     minute, a silently stale graph costs a wrong answer.
+
+    R1-C47: the sample count is part of the builder. ``extras.seen`` on a spliced edge
+    means "k of N", and it can only mean that if N is the same N the chain has used all
+    along — a request with a different N starts a new chain from a full build.
     """
     if not provenance:
-        return False
-    return (provenance.get("tool") == tool_identity()
-            and provenance.get("tier") == tier)
+        return "builder-changed"
+    if (provenance.get("tool") != tool_identity()
+            or provenance.get("tier") != tier):
+        return "builder-changed"
+    if ((provenance.get("samples") or {}).get("runs", 1)) != repeat:
+        return "samples-changed"
+    return None
+
+
+def _full(package_path, *, deep: bool, repeat: int) -> Graph:
+    """A full build with the chain's sample count (R1-C47 / D2)."""
+    return extract(package_path, deep=deep, repeat=repeat)
+
+
+def _count_seen(graph: Graph) -> int:
+    return sum(1 for e in graph.edges if "seen" in e.extras)
 
 
 def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dict,
-                 *, deep: bool = False) -> tuple[Graph, dict]:
+                 *, deep: bool = False, repeat: int = 1) -> tuple[Graph, dict]:
     """Incrementally rebuild ``old_graph`` for the current source tree.
 
     Returns ``(graph, info)`` where ``info`` records the decision (``mode``:
@@ -186,16 +204,25 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
     (R1-C42): the spliced regions carry the *previous* build's sample, and the splice
     is self-perpetuating — see the module docstring (R1-C43). Such a graph is stamped
     ``provenance.incremental: true``.
+
+    ``repeat=N`` (R1-C47) makes every place this path samples — the fallback full build
+    and the recompute of the affected modules — take N samples in fresh interpreters,
+    merged as a full ``--repeat`` build would be. Measured on twenty real commits: the
+    chain's misses come from single samples, not from age, so this is the remedy and a
+    periodic full rebuild is not. N must equal the old graph's ``samples.runs`` or the
+    chain restarts from a full build (``reason: samples-changed``).
     """
     target_pkg = old_graph.target
     tier = "deep" if deep else "fast"
     # R1-C25: the input is not the only thing that can change. `unchanged` below decides
     # from the source tree alone, so an upgraded codemap over an untouched tree used to
     # return yesterday's graph built by yesterday's extractor — the exact confusion the
-    # provenance block exists to name. A different tool or tier is a full rebuild.
-    if not _same_builder(old_graph.provenance, tier):
-        graph = extract(package_path, deep=deep)
-        return graph, {"mode": "full", "affected": [], "reason": "builder-changed"}
+    # provenance block exists to name. A different tool, tier or sample count is a full
+    # rebuild.
+    reason = _same_builder(old_graph.provenance, tier, repeat)
+    if reason is not None:
+        return _full(package_path, deep=deep, repeat=repeat), \
+            {"mode": "full", "affected": [], "reason": reason}
 
     d = diff_scopes(old_scope, new_scope)
     changed = {m for p in d["changed"] if (m := _path_to_module(p, target_pkg))}
@@ -218,14 +245,32 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
                                  module_of) & module_ids
 
     if not module_ids or len(affected) >= _FULL_FALLBACK_FRACTION * len(module_ids):
+        if repeat > 1:
+            # R1-C47: the fallback used to be the chain's weakest point — a 63-module
+            # commit reset a --repeat 3 chain to one sample on the replay's third tick.
+            return _full(package_path, deep=deep, repeat=repeat), \
+                {"mode": "full", "affected": sorted(affected)}
         add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
         graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"))
         return graph, {"mode": "full", "affected": sorted(affected)}
 
-    add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
-                         behavior_only=affected, attr_only=affected)
+    if repeat > 1:
+        # R1-C47 / D2: N fresh interpreters, each restricted to the affected modules;
+        # the structural base is rebuilt in each (deterministic, ~4 s) so the merge
+        # sees identical nodes. The spliced part keeps its own `seen` — same N (D1).
+        graph, stats = merge_samples(collect_samples(package_path, deep=deep,
+                                                     runs=repeat, only=affected))
+        graph.loaded_schema = None
+    else:
+        add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
+                             behavior_only=affected, attr_only=affected)
+        stats = {"runs": 1}
     unaffected = module_ids - affected
     _splice_unaffected(graph, old_graph, unaffected, module_of)
+    if repeat > 1:
+        # `unstable` describes the artifact a reader holds, not the part this tick
+        # touched: recount over recomputed and spliced edges alike.
+        stats = {"runs": repeat, "unstable": _count_seen(graph)}
     graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"),
-                                        incremental=True)
+                                        incremental=True, samples=stats)
     return graph, {"mode": "incremental", "affected": sorted(affected)}

{codmap-0.0.11 → codmap-0.0.13}/codemap/model.py

@@ -97,6 +97,13 @@ EDGE_TYPES = frozenset({
     "accesses",       # function → attribute node it reads/writes (extras.access, R1-C20)
 })
 
+# The subset of EDGE_TYPES an incremental build splices from the old graph for modules
+# it did not recompute (``incremental.py``) — and therefore the classes a deep+incremental
+# graph answers from an *earlier* build's jedi sample (R1-C43). Lives with the vocabulary
+# because two layers that may not import each other need it: the extractor's union
+# (R1-C45) and the serve layer, which derives from it which ops must say so (R1-C44 / D4).
+SPLICED_EDGE_TYPES = frozenset({"calls", "accesses", "references"})
+
 
 @dataclass
 class Node: