codmap 0.0.22__tar.gz → 0.0.23__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.22
+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, **1054 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

{codmap-0.0.22 → 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, **1054 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

{codmap-0.0.22 → 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.22 → codmap-0.0.23}/codemap/cli.py

@@ -807,6 +807,12 @@ def _cmd_pack(args) -> int:
     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:
     """Enforce the [architecture] contract → exit 2 on any violation (R1-C3).
 
@@ -820,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:
@@ -1173,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.22 → 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.22 → 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:

{codmap-0.0.22 → codmap-0.0.23}/codemap/extract/griffe_extractor.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import ast
 import multiprocessing
 import os
+import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -29,7 +30,8 @@ from codemap.extract.attrflow import add_attrflow
 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.gsource import (DOTTED_IMPORT_HINT, 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
@@ -322,9 +324,10 @@ def _input_report(graph, pkg_dir: Path, root: Path, walk) -> dict:
     return report
 
 
-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.
+def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str], set[str]]:
+    """``([(target, scope)], eager targets, griffe heads to drop)`` — the imports griffe's
+    module-level map does not carry, the targets it carries correctly, and the entries it
+    carries wrongly.
 
     Two families, one traversal, one parse — griffe records neither, and both used to be
     invisible to the import graph:
@@ -345,6 +348,13 @@ def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
       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``.
+    - **dotted `import a.b.c` at module level** (R1-C68, design ``dotted_imports.md``).
+      griffe records the *bound name*, ``{"a": "a"}``, so the edge went to the root package
+      and a contract banning ``core → analysis`` passed over ``import pkg.analysis.b``. The
+      full name is recorded here, scope ``"module"``; the third value returned is the heads
+      griffe's entry should be dropped for — bound by dotted imports only, never by a plain
+      ``import a`` (D2). Under ``TYPE_CHECKING`` the full name already came out of this
+      pass; the head griffe filed beside it was left behind as an *eager* edge to ``a``.
 
     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
@@ -356,13 +366,13 @@ def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
     try:
         src = module.source
     except Exception:                       # no source (namespace dir, synthetic)
-        return [], set()
-    if not NESTED_IMPORT_HINT.search(src):
-        return [], set()
+        return [], set(), set()
+    if not (NESTED_IMPORT_HINT.search(src) or DOTTED_IMPORT_HINT.search(src)):
+        return [], set(), set()
     try:
         tree = ast.parse(src)
     except (SyntaxError, ValueError):
-        return [], set()                     # unreadable: D2's report owns this file
+        return [], set(), 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"
@@ -376,6 +386,19 @@ def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
 
     out: list[tuple[str, str]] = []
     eager: set[str] = set()   # targets imported at plain module level (griffe has them)
+    # R1-C68/D2: heads griffe records for module-level `import a.b.c` (it files the bound
+    # name), against heads a plain `import a` really binds. Only the difference is dropped.
+    dotted_heads: set[str] = set()
+    plain_heads: set[str] = set()
+
+    def note_heads(names) -> None:
+        for a in names:
+            if a.asname is not None:
+                continue                     # `import a.b as x`: griffe records a.b, correctly
+            if "." in a.name:
+                dotted_heads.add(a.name.split(".", 1)[0])
+            else:
+                plain_heads.add(a.name)
 
     def visit(node, scope: str | None) -> None:
         """``scope`` is None at module level (griffe has those), else
@@ -398,10 +421,16 @@ def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
                 for stmt in child.orelse:
                     visit_stmt(stmt, else_scope if else_scope else scope)
             elif isinstance(child, ast.Import):
+                if scope in (None, "type_checking"):
+                    # griffe's map holds these (TYPE_CHECKING included, as module-level)
+                    note_heads(child.names)
                 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)
+                    # R1-C68: griffe has `a` for `import a.b.c`; the dependency is a.b.c
+                    out.extend((a.name, "module") for a in child.names
+                               if a.asname is None and "." in a.name)
             elif isinstance(child, ast.ImportFrom):
                 target = resolve(child)
                 if not target:
@@ -428,7 +457,7 @@ def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
         visit(holder, scope)
 
     visit(tree, None)
-    return out, eager
+    return out, eager, dotted_heads - plain_heads
 
 
 def _type_checking_branches(node: ast.If) -> tuple[str | None, str | None] | None:
@@ -457,7 +486,7 @@ def _collect(graph, obj, root, target_pkg, walk) -> None:
         # 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)
+        nested, eager, dotted_only = _source_import_targets(obj)
         type_checking = {tgt for tgt, scope in nested if scope == "type_checking"}
         # R1-C56/D1: a `.pyi` is a declaration — Python never executes it, so *none* of
         # its imports run, whatever they look like. Recorded as a fourth scope rather
@@ -465,6 +494,10 @@ def _collect(graph, obj, root, target_pkg, walk) -> None:
         # cycle classes are named by mechanism.
         stub = _is_stub(obj)
         for name, tgt in (obj.imports or {}).items():
+            if name == tgt and tgt in dotted_only:
+                # R1-C68/D2: the bound name of `import a.b.c`, not a dependency on `a`;
+                # the full name came from the AST pass above.
+                continue
             # 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"
@@ -558,6 +591,19 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     )
 
     known_modules = set(module_ids)
+    # R1-C72 (design ``flat_inference_in_packages.md`` D1, revised): the flat inference is for
+    # a directory that is itself on sys.path. The evidence is a bare import that can only be a
+    # sibling — it names a module beside the importer (not the importer itself) and is no
+    # standard-library name. With it, siblings shadow the stdlib too and every bare import is
+    # rewritten; without it, `import warnings` beside `_pytest/warnings.py` is the standard
+    # library and nothing is. A namespace root needs no evidence. Decided from the collected
+    # imports before anything is emitted, so edge order is kept.
+    root_node = graph.nodes.get(target_pkg)
+    flat_ok = (root_node is not None and root_node.file is None) or any(
+        (sib := _flat_sibling(src, t, known_modules)) is not None and sib != src
+        and t.split(".", 1)[0] not in sys.stdlib_module_names
+        for src, t, _scope in imports
+        if not (t == target_pkg or t.startswith(target_pkg + ".")))
     for parent_module, name, target_path, is_public in aliases:
         extras = {"as": name, "public": is_public}
         if not (target_path == target_pkg or target_path.startswith(target_pkg + ".")):
@@ -567,7 +613,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
             # here — so every re-export in such a tree was filed as external and produced
             # no edge at all. Same narrow gate as pass B: only when the head names a
             # module sitting beside the re-exporter, and labelled as the inference it is.
-            if _flat_sibling(parent_module, target_path, known_modules) is None:
+            if not flat_ok or _flat_sibling(parent_module, target_path, known_modules) is None:
                 # R1-C57: `import numpy as np` is not this package's API and stays out.
                 # A **public** alias to an outside definition is the opposite case: it is
                 # exactly what the package exposes, and dropping it made the facade layout
@@ -614,7 +660,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     # sys.path. griffe records the source-literal target, so pass A cannot tell it from
     # `pandas.DataFrame`. Retry it against the importer's own package — and label it, since
     # this is an inference about sys.path, not something the source states.
-    for src_module, target_path, scope in unresolved:
+    for src_module, target_path, scope in (unresolved if flat_ok else ()):  # R1-C72
         tgt_module = _flat_sibling(src_module, target_path, known_modules)
         if tgt_module is None or tgt_module == src_module:
             continue

{codmap-0.0.22 → codmap-0.0.23}/codemap/extract/gsource.py

@@ -29,6 +29,13 @@ from pathlib import Path
 #: on one rule instead of two that can drift apart.
 NESTED_IMPORT_HINT = re.compile(r"^[ \t]+(?:from|import)\s|import\s+\*", re.MULTILINE)
 
+#: R1-C68 (design ``dotted_imports.md`` D3): a top-level ``import`` statement naming a dotted
+#: module. griffe files ``import a.b.c`` under its bound name ``a``, so the import graph has to
+#: read the source for it — but only the import graph: call resolution keeps the gate above,
+#: since ``a`` *is* the name bound. A false positive (``import a.b as x``) costs one parse.
+#: Not seen: a dotted name after a backslash continuation line.
+DOTTED_IMPORT_HINT = re.compile(r"^import\s[^\n#]*\w\.\w", re.MULTILINE)
+
 
 def module_file(obj) -> Path | None:
     """The single source file behind a griffe object, or ``None`` if it has none."""
@@ -98,3 +105,19 @@ def qualify_target(target: str, modpath: str, known_modules) -> str:
     if not target.startswith(pkg) and f"{parent}.{target.split('.', 1)[0]}" in known_modules:
         return f"{parent}.{target}"
     return target
+
+
+def flat_inference_applies(graph, core_pkg: str) -> bool:
+    """Does the flat-layout inference (R1-C21) apply to this core? One predicate, three users.
+
+    True for a namespace root (no file), or when the structural pass emitted at least one
+    ``imports`` edge labelled ``resolution="flat"``. Since R1-C72 that pass emits none in a core
+    that imports itself by package-qualified or relative name: there a bare ``import warnings``
+    is absolute — the standard library — however a module beside the importer is named
+    (design ``flat_inference_in_packages.md``). The import map for calls and attribute access
+    (``module_imports`` / ``qualify_target``, the deep tier's ``_flat_qualify``) and the
+    cross-root gate (``roots.core_is_flat``) all ask this, so they cannot disagree.
+    """
+    root = graph.nodes.get(core_pkg)
+    return (root is not None and root.file is None) or any(
+        e.type == "imports" and e.extras.get("resolution") == "flat" for e in graph.edges)

{codmap-0.0.22 → codmap-0.0.23}/codemap/extract/roots.py

@@ -152,10 +152,8 @@ class _CoreIndex:
         # script cannot be reaching `core/alpha.py` — inferring an edge there would invent
         # one. Both flat shapes satisfy this: a namespace directory (root has no file), or a
         # directory whose own imports needed the flat inference.
-        root = graph.nodes.get(core_pkg)
-        self.core_is_flat = (root is not None and root.file is None) or any(
-            e.type == "imports" and e.extras.get("resolution") == "flat" for e in graph.edges
-        )
+        from codemap.extract.gsource import flat_inference_applies
+        self.core_is_flat = flat_inference_applies(graph, core_pkg)
         self.top_modules = {
             mid.split(".", 1)[1].split(".")[0]
             for mid in self.module_ids

{codmap-0.0.22 → codmap-0.0.23}/codemap/model.py

@@ -103,7 +103,13 @@ SCHEMA_VERSION = "0.13"
 #       uses them — with `coverage.walk` naming the walk (R1-C66,
 #       docs/design/pack_direction.md). Not a separate number: no release ever
 #       answered 2 without it.
-ANSWER_FORMAT = 2
+#   3 — the gate's verdict changed shape twice: an `[architecture]` section that departs from
+#       the schema is refused ("Contract not read — nothing was enforced", exit 2) where it was
+#       read as absent or partly enforced (R1-C69, docs/design/contract_validation.md); and
+#       `check --graph` carries a currency line, and its structured answer a `graph_currency`
+#       block, with a graph behind its source tree failing the gate (R1-C70,
+#       docs/design/check_graph_currency.md).
+ANSWER_FORMAT = 3
 
 # Closed vocabulary of edge types (R1-C7). Node ``kind`` is deliberately an OPEN set
 # (DESIGN §2 — new entity kinds may appear), but edges are TYPED: every relationship