codmap 0.0.21__tar.gz → 0.0.23__tar.gz

{codmap-0.0.21/codmap.egg-info → codmap-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.21
+Version: 0.0.23
 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, **990 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1115 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 &
@@ -107,18 +107,24 @@ answer.
 
 That sentence used to end at "None answers these", and a second pass over the 68k-star tool made it
 narrower: its *importable library* does carry a cycle finder, reachable from neither its CLI nor its MCP
-tools and called nowhere in its own source. Measured on the same tree it reports **136 cycles**; codemap
-reports **1**. Scoring both against the truth set — every intra-package import, function-local ones
-included — is less flattering than that sounds:
+tools and called nowhere in its own source. Measured on the same tree (its 1.6.0) it reported **136
+cycles**; codemap reported **1**. Scoring both against the truth set — every intra-package import,
+function-local ones included — is less flattering than that sounds:
 
-| | reported | of the 41 real ones | precision | recall |
+| | reported | of the 45 real ones | precision | recall |
 |---|---:|---:|---:|---:|
-| codemap, that morning | 1 | 1 | 100% | **2.4%** |
-| the peer's library API | 136 | 13 | 10% | 32% |
-| codemap, after R1-C29 | 41 | 41 | 100% | 100% |
-
-Theirs over-reports because it walks name-resolved call edges — a `dict.get` becomes a call into an
-unrelated class. **Ours under-reported because its import map was module-level only**, and it phrased
+| codemap, before R1-C29 | 1 | 1 | 100% | **2.2%** |
+| the peer's library API, 1.6.0 | 136 | 13 | 10% | 29% |
+| the peer's library API, **1.6.2** (re-measured 2026-10-15) | 25 | 16 | **64%** | 36% |
+| codemap, after R1-C29 (0.0.4) | 45 | 45 | 100% | 100% |
+
+*Corrected 2026-10-15.* This table first said **41** real cycles, recall 32% and 2.4%. The 41 were counted
+on a later commit of the same repository than the one both tools were measured on; on the measured tree
+there are 45 ([re-measure](research/codegraph_remeasure.md) §7, C3). The peer fixed the call edges we
+reported and its 1.6.2 row is the current one.
+
+Theirs over-reported because it walks name-resolved call edges — a `dict.get` became a call into an
+unrelated class (fixed upstream in 1.6.1). **Ours under-reported because its import map was module-level only**, and it phrased
 that as *"import graph is acyclic"* — a property claim over a partial map, which is the worse of the two
 errors even though it was the smaller one. Both halves of that came from
 [#11](https://github.com/kogriv/codemap/issues/11), filed off a different target and fixed the same day
@@ -221,8 +227,14 @@ codemap serve --graph graph.json --watch
 - **Dataflow** — producers/consumers of a string-keyed DataFrame column.
 - **Semantic search** (opt-in) — a concept query routed to an external adapter, with each fuzzy hit
   resolved to the exact codemap symbol at its location (`codemap semantic`). See [docs/integrations.md](docs/integrations.md).
-- **Context pack** — the most relevant slice of the graph under a token budget, ranked by importance or
-  by relevance to seed symbols (`codemap pack --budget N [--seed X]`). See [docs/pack.md](docs/pack.md).
+- **Context pack** — the highest-ranked modules, classes and functions under a token budget, by
+  importance or by relevance to seed symbols (`codemap pack --budget N [--seed X]`). With a seed it
+  walks both ways — what the seed uses and what uses it (`--direction uses` for one way) — documents are
+  never in it, the answer says which walk it took, and a seed that resolves to nothing is refused rather
+  than silently answered globally. Deterministic and budget-tested. Against git history, seeded with a
+  changed file, it puts 42 % and 60 % of the co-changed files in its first ten on two repositories —
+  ahead of `impact` and of grep by names, though on one of the two not beyond the noise; grep still
+  finds tests best. **Whether it helps an agent is not measured.** See [docs/pack.md](docs/pack.md).
 - **Interop** — export the graph as a [SCIP](https://scip-code.org/) index (definitions + symbol
   info + inherits/implements relationships) so Sourcegraph, Glean and other SCIP consumers can drive
   go-to-definition, symbol search and type hierarchy over it. See [docs/export.md](docs/export.md).
@@ -266,6 +278,13 @@ 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.
 
+**A deep build does not check jedi.** With jedi answering nothing, a deep build still exits 0 and
+declares `tier: deep` — and its call edges equal the fast tier's. `codemap doctor` asks griffe and jedi
+one question each with a known answer and exits 1 when one is absent or answers wrongly
+([accuracy.md](docs/accuracy.md#what-this-means-for-trust)); rebuilding over the previous graph of the
+same tree (`build -o` on the existing file) names the classes of edges that shrank
+([provenance.md](docs/provenance.md#fewer-edges-on-the-same-input-is-named)).
+
 **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

{codmap-0.0.21 → codmap-0.0.23}/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, **990 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1115 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 &
@@ -71,18 +71,24 @@ answer.
 
 That sentence used to end at "None answers these", and a second pass over the 68k-star tool made it
 narrower: its *importable library* does carry a cycle finder, reachable from neither its CLI nor its MCP
-tools and called nowhere in its own source. Measured on the same tree it reports **136 cycles**; codemap
-reports **1**. Scoring both against the truth set — every intra-package import, function-local ones
-included — is less flattering than that sounds:
+tools and called nowhere in its own source. Measured on the same tree (its 1.6.0) it reported **136
+cycles**; codemap reported **1**. Scoring both against the truth set — every intra-package import,
+function-local ones included — is less flattering than that sounds:
 
-| | reported | of the 41 real ones | precision | recall |
+| | reported | of the 45 real ones | precision | recall |
 |---|---:|---:|---:|---:|
-| codemap, that morning | 1 | 1 | 100% | **2.4%** |
-| the peer's library API | 136 | 13 | 10% | 32% |
-| codemap, after R1-C29 | 41 | 41 | 100% | 100% |
-
-Theirs over-reports because it walks name-resolved call edges — a `dict.get` becomes a call into an
-unrelated class. **Ours under-reported because its import map was module-level only**, and it phrased
+| codemap, before R1-C29 | 1 | 1 | 100% | **2.2%** |
+| the peer's library API, 1.6.0 | 136 | 13 | 10% | 29% |
+| the peer's library API, **1.6.2** (re-measured 2026-10-15) | 25 | 16 | **64%** | 36% |
+| codemap, after R1-C29 (0.0.4) | 45 | 45 | 100% | 100% |
+
+*Corrected 2026-10-15.* This table first said **41** real cycles, recall 32% and 2.4%. The 41 were counted
+on a later commit of the same repository than the one both tools were measured on; on the measured tree
+there are 45 ([re-measure](research/codegraph_remeasure.md) §7, C3). The peer fixed the call edges we
+reported and its 1.6.2 row is the current one.
+
+Theirs over-reported because it walks name-resolved call edges — a `dict.get` became a call into an
+unrelated class (fixed upstream in 1.6.1). **Ours under-reported because its import map was module-level only**, and it phrased
 that as *"import graph is acyclic"* — a property claim over a partial map, which is the worse of the two
 errors even though it was the smaller one. Both halves of that came from
 [#11](https://github.com/kogriv/codemap/issues/11), filed off a different target and fixed the same day
@@ -185,8 +191,14 @@ codemap serve --graph graph.json --watch
 - **Dataflow** — producers/consumers of a string-keyed DataFrame column.
 - **Semantic search** (opt-in) — a concept query routed to an external adapter, with each fuzzy hit
   resolved to the exact codemap symbol at its location (`codemap semantic`). See [docs/integrations.md](docs/integrations.md).
-- **Context pack** — the most relevant slice of the graph under a token budget, ranked by importance or
-  by relevance to seed symbols (`codemap pack --budget N [--seed X]`). See [docs/pack.md](docs/pack.md).
+- **Context pack** — the highest-ranked modules, classes and functions under a token budget, by
+  importance or by relevance to seed symbols (`codemap pack --budget N [--seed X]`). With a seed it
+  walks both ways — what the seed uses and what uses it (`--direction uses` for one way) — documents are
+  never in it, the answer says which walk it took, and a seed that resolves to nothing is refused rather
+  than silently answered globally. Deterministic and budget-tested. Against git history, seeded with a
+  changed file, it puts 42 % and 60 % of the co-changed files in its first ten on two repositories —
+  ahead of `impact` and of grep by names, though on one of the two not beyond the noise; grep still
+  finds tests best. **Whether it helps an agent is not measured.** See [docs/pack.md](docs/pack.md).
 - **Interop** — export the graph as a [SCIP](https://scip-code.org/) index (definitions + symbol
   info + inherits/implements relationships) so Sourcegraph, Glean and other SCIP consumers can drive
   go-to-definition, symbol search and type hierarchy over it. See [docs/export.md](docs/export.md).
@@ -230,6 +242,13 @@ 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.
 
+**A deep build does not check jedi.** With jedi answering nothing, a deep build still exits 0 and
+declares `tier: deep` — and its call edges equal the fast tier's. `codemap doctor` asks griffe and jedi
+one question each with a known answer and exits 1 when one is absent or answers wrongly
+([accuracy.md](docs/accuracy.md#what-this-means-for-trust)); rebuilding over the previous graph of the
+same tree (`build -o` on the existing file) names the classes of edges that shrank
+([provenance.md](docs/provenance.md#fewer-edges-on-the-same-input-is-named)).
+
 **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

{codmap-0.0.21 → codmap-0.0.23}/codemap/arch.py

@@ -104,8 +104,83 @@ def load_contract(root: str | Path = ".") -> ArchitectureContract:
     return replace(parse_contract(data.get("architecture", {})), path=str(path))
 
 
+#: R1-C69: the closed schema of ``[architecture]``. A key outside it is an error, not a skip.
+_FLAGS = ("no_cycles", "no_lazy_cycles", "no_type_only_cycles", "exhaustive", "no_phantom_rules")
+_KNOWN_KEYS = ("layers", "independent", "forbidden") + _FLAGS
+
+
+def _is_str_list(v) -> bool:
+    return isinstance(v, list) and all(isinstance(x, str) for x in v)
+
+
+def contract_problems(section) -> list[str]:
+    """Every way ``section`` departs from the ``[architecture]`` schema, in reading order (R1-C69).
+
+    Empty when the section is valid. Design ``docs/design/contract_validation.md`` D1: unknown
+    keys (with the nearest known one suggested), values of the wrong type — `"false"` is a
+    string and used to switch a rule *on* — and malformed items, each named by key and index.
+    Names that do not exist in the graph are not a schema question (D3, R1-C62).
+    """
+    import difflib
+
+    if not isinstance(section, dict):
+        return [f"`[architecture]` must be a table, got {type(section).__name__}"]
+    problems: list[str] = []
+    for key in section:
+        if key not in _KNOWN_KEYS:
+            near = difflib.get_close_matches(key, _KNOWN_KEYS, n=1, cutoff=0.6)
+            hint = f" (did you mean `{near[0]}`?)" if near else ""
+            problems.append(f"unknown key `{key}`{hint}; known keys: {', '.join(_KNOWN_KEYS)}")
+    if "layers" in section and not _is_str_list(section["layers"]):
+        problems.append("`layers` must be a list of strings")
+    if "independent" in section:
+        groups = section["independent"]
+        if not isinstance(groups, list):
+            problems.append("`independent` must be a list of lists of strings")
+        else:
+            for i, grp in enumerate(groups):
+                if not _is_str_list(grp) or len(grp) < 2:
+                    problems.append(f"`independent[{i}]` must be a list of at least 2 strings")
+    if "forbidden" in section:
+        items = section["forbidden"]
+        if not isinstance(items, list):
+            problems.append("`forbidden` must be a list of `{ from = \"…\", to = \"…\" }` tables")
+        else:
+            for i, item in enumerate(items):
+                if not isinstance(item, dict):
+                    problems.append(f"`forbidden[{i}]` must be a table `{{ from = \"…\", to = \"…\" }}`")
+                    continue
+                extra = sorted(set(item) - {"from", "to"})
+                missing = [k for k in ("from", "to") if k not in item]
+                wrong = [k for k in ("from", "to") if k in item and not isinstance(item[k], str)]
+                if extra:
+                    problems.append(f"`forbidden[{i}]` has unknown key(s) "
+                                    + ", ".join(f"`{k}`" for k in extra))
+                if missing:
+                    problems.append(f"`forbidden[{i}]` is missing " + ", ".join(f"`{k}`" for k in missing))
+                if wrong:
+                    problems.append(f"`forbidden[{i}]`: " + ", ".join(f"`{k}`" for k in wrong)
+                                    + " must be a string")
+    for flag in _FLAGS:
+        if flag in section and not isinstance(section[flag], bool):
+            problems.append(f"`{flag}` must be true or false, got {type(section[flag]).__name__} "
+                            f"`{section[flag]!r}`")
+    return problems
+
+
 def parse_contract(section: dict) -> ArchitectureContract:
-    """Build a contract from the parsed ``[architecture]`` table (validated leniently)."""
+    """Build a contract from the parsed ``[architecture]`` table.
+
+    R1-C69: validated against a closed schema first. A section with any problem is **not
+    enforced at all** — it comes back as an ``error`` contract, the R1-C27 path, so the CLI
+    exits 2 and MCP answers ``ok: false`` naming every problem. Enforcing the valid half used
+    to be the silent part: ``forbiden = [...]`` beside ``no_cycles = true`` printed a green
+    tick over a rule the gate never ran.
+    """
+    problems = contract_problems(section)
+    if problems:
+        return ArchitectureContract(
+            error="`[architecture]` is not a valid contract: " + "; ".join(problems))
     forbidden = []
     for item in section.get("forbidden", []) or []:
         if isinstance(item, dict) and "from" in item and "to" in item:

{codmap-0.0.21 → codmap-0.0.23}/codemap/cli.py

@@ -2,6 +2,8 @@
 
     codemap build  <path> [-o graph.json] [--deep]
                    [--consumer PATH ...] [--docs PATH ...] [--mode thin|full]
+    codemap doctor [--json]
+        probe griffe and jedi with a question whose answer is known (R1-C64)
     codemap scope  <path> [--consumer PATH ...] [--docs PATH ...] [--no-git] [--json]
                    | --diff A.meta.json B.meta.json   → input scope manifest (M19.A)
     codemap query  <name> (--graph g.json | --build <path>) [--format json|text]
@@ -30,7 +32,7 @@
         codemap.toml [integrations].enabled + the tool installed)
     codemap semantic <query> (--graph g.json | --build <path>) [--root DIR] [--limit N]
         semantic search via an opt-in adapter, enriched to codemap symbols (R1-C16)
-    codemap pack (--graph g.json | --build <path>) [--budget N] [--seed X …]
+    codemap pack (--graph g.json | --build <path>) [--budget N] [--seed X …] [--direction both|uses]
         token-budgeted context pack: most relevant graph slice under N tokens (R1-C6)
 """
 
@@ -155,6 +157,7 @@ def _cmd_build(args) -> int:
         text = " ".join(p for p in (d["message"], d.get("consequence")) if p)
         print(f"[{d.get('severity', 'warning')}] {text}", file=sys.stderr)
     if args.out:
+        _report_completeness_drop(args.out, graph)
         store.save(graph, args.out)
         # M18: record the build recipe beside the graph so `codemap refresh` can
         # rebuild it, and so the graph's age is meaningful to `serve`/stats.
@@ -175,6 +178,36 @@ def _cmd_build(args) -> int:
     return 0
 
 
+def _report_completeness_drop(out: str, graph) -> None:
+    """Compare a fresh build with the graph it is about to overwrite (R1-C59).
+
+    The one moment both builds of an input are in hand without anyone asking: the previous
+    graph is still on disk at ``-o``. Read it before the write and say when an edge class
+    shrank on the **same** input — on one input that is the builder (tool, dependency,
+    sampling), never the code. A warning, not a refusal: rebuilding with a new tool is
+    legitimate, and the build still succeeds.
+
+    A file that exists and cannot be read is not a file that is absent (R1-C27), so it is
+    named; a missing file is the first build, and there is nothing to say.
+    """
+    from codemap.provenance import completeness_drops, describe_drops
+    if not Path(out).exists():
+        return
+    try:
+        previous = store.load(out)
+    except Exception as exc:  # any unreadable previous graph — never fatal to a build
+        print(f"[note] the graph already at {out} could not be read "
+              f"({type(exc).__name__}); completeness against it not compared",
+              file=sys.stderr)
+        return
+    drops = completeness_drops(previous, graph)
+    if drops:
+        print(f"[warning] {describe_drops(drops)} — against the graph this build replaces. "
+              "Same input, fewer edges: the difference is the builder (the tool, a "
+              "dependency, or the deep tier's sampling), not the code; whatever reads "
+              "those edges now answers from less than before.", file=sys.stderr)
+
+
 def _inputs_with_membership(graph, scope, args):
     """The extractor's ``inputs`` block plus the manifest membership result (R1-C41).
 
@@ -333,6 +366,22 @@ def _cmd_watch(args) -> int:
     return 0
 
 
+def _cmd_doctor(args) -> int:
+    """Probe each dependency with a question whose answer is known (R1-C64).
+
+    Exit 0 when every probe answers as expected, 1 otherwise. A dependency that imports
+    and answers wrongly is the case this exists for: it never breaks a build, it makes the
+    graph poorer while the graph still declares its tier.
+    """
+    from codemap.extract.probe import render, run_probes
+    report = run_probes()
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True, ensure_ascii=False))
+    else:
+        print(render(report), end="")
+    return 0 if report["ok"] else 1
+
+
 def _cmd_scope(args) -> int:
     """Resolve/print the input scope manifest, or diff two (M19.A)."""
     from codemap.scope import resolve_scope, diff_scopes
@@ -741,15 +790,27 @@ def _cmd_semantic(args) -> int:
 
 def _cmd_pack(args) -> int:
     """Token-budgeted context pack — most relevant graph slice under N tokens (R1-C6)."""
-    from codemap.serve.pack import build_pack, render_pack
-    q = Query(_graph_from(args))
+    from codemap.serve.pack import build_pack, render_payload
     seeds = tuple(args.seed or ())
+    if args.direction and not seeds:  # before any build: a usage error costs nothing
+        print("codemap pack: --direction needs --seed — the global rank walks from no "
+              "seed", file=sys.stderr)
+        return 2
+    q = Query(_graph_from(args))
+    p = build_pack(q, budget=args.budget, seeds=seeds, direction=args.direction)
     if args.format == "json":
-        print(json.dumps(build_pack(q, budget=args.budget, seeds=seeds),
-                         ensure_ascii=False, indent=2, sort_keys=True))
+        print(json.dumps(p, ensure_ascii=False, indent=2, sort_keys=True))
     else:
-        print(render_pack(q, budget=args.budget, seeds=seeds), end="")
-    return 0
+        print(render_payload(p, target=q.graph.target, seeds=seeds), end="")
+    # No seed resolved → a refusal, not an empty pack: exit 1, as `query` does on an
+    # unknown name (pack honesty).
+    return 1 if "error" in p else 0
+
+
+def _check_exit(violations, currency: dict | None, allow_stale: bool) -> int:
+    """2 on a violation, or on a graph behind its source unless ``--allow-stale`` (R1-C70)."""
+    behind = currency is not None and currency.get("status") == "behind"
+    return 2 if (violations or (behind and not allow_stale)) else 0
 
 
 def _cmd_check(args) -> int:
@@ -765,21 +826,28 @@ def _cmd_check(args) -> int:
     from codemap.serve.check import render_check
     q = Query(_graph_from(args))
     contract = load_contract(args.root)
+    # R1-C70: a graph read from disk may be behind the tree it is about to be judged as.
+    currency = None
+    if getattr(args, "graph", None) and not getattr(args, "build", None):
+        from codemap.serve.currency import graph_currency
+        currency = graph_currency(args.graph, (q.graph.provenance or {}).get("scope_id"))
+    allow_stale = getattr(args, "allow_stale", False)
     # R1-C27: check `error` before anything else. A malformed codemap.toml used to be
     # indistinguishable from an absent one, so removing a single `]` turned a gate that
     # reported 14 violations into exit 0. Exit 2 — the same code as a violation, not a new
     # one: the status answers "may the pipeline proceed?" (no, either way), and a new code
     # would sort an unreadable contract into the success branch of every `if rc == 2` that
     # already exists in someone's pipeline.
+    kw = {"currency": currency, "allow_stale": allow_stale}
     if contract.error:
-        _emit_answer(render_check(q, contract, []))
+        _emit_answer(render_check(q, contract, [], **kw))
         return 2
     if contract.is_empty() and args.require_contract:
-        _emit_answer(render_check(q, contract, []))
+        _emit_answer(render_check(q, contract, [], **kw))
         raise SystemExit("error: no [architecture] contract found (--require-contract)")
     violations = check_contract(q, contract)
-    _emit_answer(render_check(q, contract, violations))
-    return 2 if violations else 0
+    _emit_answer(render_check(q, contract, violations, **kw))
+    return _check_exit(violations, currency, allow_stale)
 
 
 def _cmd_diff(args) -> int:
@@ -795,7 +863,7 @@ def _cmd_diff(args) -> int:
     # R1-C25/D4: two graphs built by different tools are a before/after of the *tool*,
     # not of the code. Never a refusal — comparing across an upgrade is legitimate; what
     # was missing is being told, since a clean "no breaking changes" reads as proof.
-    cmp = comparability(old.provenance, new.provenance)
+    cmp = comparability(old.provenance, new.provenance, old_graph=old, new_graph=new)
     if not cmp["comparable"]:
         for line in cmp["differences"]:
             print(f"[warning] {line}", file=sys.stderr)
@@ -947,6 +1015,11 @@ def build_parser() -> argparse.ArgumentParser:
                         "of the chain: a different N restarts it from a full build.")
     b.set_defaults(func=_cmd_build)
 
+    dr = sub.add_parser("doctor", help="Probe griffe and jedi with a question whose answer is "
+                                       "known; exit 1 if one is absent or answers wrongly.")
+    dr.add_argument("--json", action="store_true", help="Structured report instead of text.")
+    dr.set_defaults(func=_cmd_doctor)
+
     sc = sub.add_parser("scope", help="Resolve the input scope manifest (scope_id + profile), or --diff two.")
     sc.add_argument("path", nargs="?", help="Package/dir to scope (like build's path).")
     sc.add_argument("--consumer", action="append", metavar="PATH",
@@ -1094,6 +1167,9 @@ def build_parser() -> argparse.ArgumentParser:
     pk.add_argument("--seed", action="append", metavar="X",
                     help="Bias relevance to this symbol / file (repeatable). "
                          "Omit for global importance.")
+    pk.add_argument("--direction", choices=["both", "uses"],
+                    help="Which way a seeded walk runs: both (default) — what the seeds "
+                         "use and what uses them; uses — only what they use.")
     pk.add_argument("--format", choices=["markdown", "json"], default="markdown")
     pk.set_defaults(func=_cmd_pack)
 
@@ -1110,6 +1186,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="Dir with codemap.toml holding [architecture] (default: cwd).")
     ck.add_argument("--require-contract", action="store_true",
                     help="Fail if no [architecture] contract is present (default: no-op success).")
+    ck.add_argument("--allow-stale", action="store_true",
+                    help="With --graph: do not fail when the graph is behind its source tree "
+                         "(R1-C70); the 'behind' line is still printed.")
     ck.set_defaults(func=_cmd_check)
 
     return p

{codmap-0.0.21 → codmap-0.0.23}/codemap/extract/attrflow.py

@@ -50,7 +50,7 @@ from codemap.extract.behavior import (
     _node_id,
     _own_nodes,
 )
-from codemap.extract.gsource import module_file, module_imports
+from codemap.extract.gsource import flat_inference_applies, module_file, module_imports
 from codemap.model import Edge
 
 
@@ -66,7 +66,8 @@ def add_attrflow(graph, griffe_root, target_pkg: str, *, deep: bool = False,
     (R1-C9), mirroring :func:`add_behavior`.
     """
     modules = _index_modules(griffe_root)
-    known_modules = set(modules)  # R1-C21: flat-layout sibling lookup
+    # R1-C21 sibling lookup, gated like behavior's (R1-C72).
+    known_modules = set(modules) if flat_inference_applies(graph, target_pkg) else frozenset()
     project = _jedi_project(search_path) if deep else None
     pkg = target_pkg + "."
     # (func_id, attr_id, access, resolution) — dedup collapses repeated sites.

{codmap-0.0.21 → codmap-0.0.23}/codemap/extract/behavior.py

@@ -27,8 +27,8 @@ import ast
 import math
 from pathlib import Path
 
-from codemap.extract.gsource import (NESTED_IMPORT_HINT, module_file, module_imports,
-                                     qualify_target)
+from codemap.extract.gsource import (NESTED_IMPORT_HINT, flat_inference_applies, module_file,
+                                     module_imports, qualify_target)
 from codemap.model import Edge
 
 _BUILTINS = set(vars(__import__("builtins")))
@@ -51,7 +51,9 @@ def add_behavior(graph, griffe_root, target_pkg: str, *, deep: bool = False,
     modules left out. When ``None`` (default) every module is processed.
     """
     modules = _index_modules(griffe_root)
-    known_modules = set(modules)  # R1-C21: flat-layout sibling lookup
+    # R1-C21 flat-layout sibling lookup — empty, so it never fires, in a core that imports
+    # itself by name (R1-C72): there `import warnings` is the standard library.
+    known_modules = set(modules) if flat_inference_applies(graph, target_pkg) else frozenset()
     project = _jedi_project(search_path) if deep else None
     # R1-C30-f1: a call to a re-exported name points at a name that is not a definition.
     # The structural pass already recorded where each re-export really leads.
@@ -588,16 +590,33 @@ def _arg_contract(shapes: list[tuple]) -> dict:
     return contract
 
 
+def _is_internal(target: str, modpath: str) -> bool:
+    """R1-C71/D3: the package root is inside the package. ``startswith(pkg + ".")`` alone
+    filed ``import pkg; pkg.f()`` — and the bound name of ``import pkg.a.b`` — as external."""
+    root = modpath.split(".")[0]
+    return target == root or target.startswith(root + ".")
+
+
+def _attr_chain(node) -> tuple[str, list[str]] | None:
+    """``a.b.c`` → ``("a", ["b", "c"])`` when the chain bottoms out in a plain name."""
+    parts = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if not isinstance(node, ast.Name):
+        return None
+    return node.id, parts[::-1]
+
+
 def _resolve(call, modpath, class_prefix, imports, modmembers, members, reexports=None,
              nodes=frozenset()):
     """Return (target_id, resolution). Only module/self/imported become edges."""
-    pkg = modpath.split(".")[0] + "."
     f = call.func
     if isinstance(f, ast.Name):
         name = f.id
         if name in imports:
             tgt = imports[name]
-            if tgt.startswith(pkg):
+            if _is_internal(tgt, modpath):
                 return _follow_reexport(tgt, reexports or {}, nodes), "imported"
             return tgt, "external"
         if name in modmembers:
@@ -613,13 +632,27 @@ def _resolve(call, modpath, class_prefix, imports, modmembers, members, reexport
                 # method call on self — resolve to the class that actually defines
                 # the member (own or a base), never a phantom same-class id.
                 return f"{members[attr]}.{attr}", "self"
-            if recv.id in imports:
-                tgt = imports[recv.id]
-                if tgt.startswith(pkg):
-                    return _follow_reexport(f"{tgt}.{attr}", reexports or {}, nodes), "imported"
-                return f"{tgt}.{attr}", "external"
-            if recv.id in modmembers:
+            if recv.id in modmembers and recv.id not in imports:
                 return f"{modpath}.{recv.id}.{attr}", "module"
+        # R1-C71 (design ``attribute_chain_calls.md``): a callee rooted at an imported name,
+        # at any depth. Internal: follow it hop by hop, each hop through a re-export when the
+        # name is no node (D1) — the depth-1 case is the one-hop instance and answers as it
+        # always did; the soundness guard downstream still refuses a target that is no node,
+        # so `b.registry.get()` stays unresolved. External: external at any depth (D2) —
+        # `np.random.rand()` is no more unknown than `np.zeros()`.
+        chain = _attr_chain(f)
+        if chain is not None and chain[0] in imports:
+            head, parts = chain
+            tgt = imports[head]
+            if not _is_internal(tgt, modpath):
+                return f"{tgt}.{'.'.join(parts)}", "external"
+            cur = tgt
+            for part in parts:
+                cur = _follow_reexport(f"{cur}.{part}", reexports or {}, nodes)
+            if len(parts) == 1 or cur in nodes:
+                return cur, "imported"
+            # a deeper chain that lands on no definition (`b.registry.get("k")`) keeps the
+            # answer it had before R1-C71: string-keyed dispatch, else unresolved
         # X.method('literal', ...) — dynamic string-keyed dispatch (registry/dict)
         if call.args and isinstance(call.args[0], ast.Constant) \
                 and isinstance(call.args[0].value, str) and attr in ("create", "get", "register"):
@@ -868,10 +901,9 @@ def _module_level_nodes(tree):
 def _resolve_name(name, modpath, imports, modmembers, reexports=None, nodes=frozenset()):
     """(target_id, resolution) for a bare name used as a value — the `_resolve` rules for
     ``ast.Name`` minus the call. Only module/imported become edges."""
-    pkg = modpath.split(".")[0] + "."
     if name in imports:
         tgt = imports[name]
-        if tgt.startswith(pkg):
+        if _is_internal(tgt, modpath):
             return _follow_reexport(tgt, reexports or {}, nodes), "imported"
         return tgt, "external"
     if name in modmembers: