codmap 0.0.20__tar.gz → 0.0.22__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.20
+Version: 0.0.22
 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, **972 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1054 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 &
@@ -221,8 +221,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 +272,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.20 → codmap-0.0.22}/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, **972 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1054 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 &
@@ -185,8 +185,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 +236,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.20 → codmap-0.0.22}/codemap/arch.py

@@ -57,6 +57,11 @@ class ArchitectureContract:
     no_lazy_cycles: bool = False
     no_type_only_cycles: bool = False
     exhaustive: bool = False
+    # R1-C62: the mirror of `exhaustive`. That one asks "is every layer of the code
+    # declared?"; this asks "does every declared name exist?". Opt-in, because a contract
+    # written ahead of the code is a documented, legitimate use (see the module docstring)
+    # and failing on it by default would turn that practice red on somebody else's tree.
+    no_phantom_rules: bool = False
     error: str | None = None
     # R1-C35: the file this contract was looked for in. "No contract found" is only
     # actionable next to *where* we looked — a reader in the wrong directory cannot tell
@@ -66,7 +71,8 @@ class ArchitectureContract:
     def is_empty(self) -> bool:
         return not (self.layers or self.independent or self.forbidden
                     or self.no_cycles or self.no_lazy_cycles
-                    or self.no_type_only_cycles or self.exhaustive)
+                    or self.no_type_only_cycles or self.exhaustive
+                    or self.no_phantom_rules)
 
 
 @dataclass(frozen=True)
@@ -117,9 +123,46 @@ def parse_contract(section: dict) -> ArchitectureContract:
         no_lazy_cycles=bool(section.get("no_lazy_cycles", False)),
         no_type_only_cycles=bool(section.get("no_type_only_cycles", False)),
         exhaustive=bool(section.get("exhaustive", False)),
+        no_phantom_rules=bool(section.get("no_phantom_rules", False)),
     )
 
 
+def _graph_layers(query) -> set[str]:
+    """Layer names that exist in the core import graph."""
+    return {query._layer_of(m) for m in query.import_graph.nodes
+            if query.root_of(m) == "core"}
+
+
+def applicability(query, contract: ArchitectureContract) -> dict:
+    """Per-rule *declared* vs *applicable* counts, plus the names that do not exist (R1-C62).
+
+    A rule naming a layer the graph does not contain is **inert by design** — no module, no
+    edge, nothing to break — which is what lets a contract be written ahead of the code. The
+    defect that made this function necessary is not the inertness: it is that the gate
+    counted such a rule as *enforced*, so a renamed layer left a green tick over a rule that
+    could no longer fire.
+
+    Applicability is presence of the **name**, nothing cleverer: `layers` needs the layer,
+    `independent` needs at least two members of the group (one cannot import itself), and
+    `forbidden` needs both ends. Whether a violation is even possible between two existing
+    layers is not asked, and should not be.
+    """
+    present = _graph_layers(query)
+    named = set(contract.layers) | {m for grp in contract.independent for m in grp}
+    named |= {n for pair in contract.forbidden for n in pair}
+    return {
+        "layers": {"declared": len(contract.layers),
+                   "applicable": sum(1 for x in contract.layers if x in present)},
+        "independent": {"declared": len(contract.independent),
+                        "applicable": sum(1 for g in contract.independent
+                                          if len([x for x in g if x in present]) >= 2)},
+        "forbidden": {"declared": len(contract.forbidden),
+                      "applicable": sum(1 for (a, b) in contract.forbidden
+                                        if a in present and b in present)},
+        "absent_names": tuple(sorted(n for n in named if n not in present)),
+    }
+
+
 def _core_layer_edges(query) -> list[tuple[str, str, str, str]]:
     """Cross-layer core→core import edges as (importer, imported, layer_i, layer_j)."""
     ig = query.import_graph
@@ -266,4 +309,18 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 modules=tuple(undeclared),
             ))
 
+    # -- no_phantom_rules: every name the contract mentions must exist -----------
+    # R1-C62, the mirror of `exhaustive`. Off by default on purpose: inert rules are how a
+    # contract gets written ahead of the code. On, it catches the drift the count alone
+    # only *discloses* — a layer renamed while the contract kept guarding the old name.
+    if contract.no_phantom_rules:
+        absent = applicability(query, contract)["absent_names"]
+        if absent:
+            violations.append(Violation(
+                "no_phantom_rules",
+                f"{len(absent)} name(s) in the contract are absent from the graph, "
+                "so the rules naming them cannot apply",
+                modules=absent,
+            ))
+
     return violations

{codmap-0.0.20 → codmap-0.0.22}/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)
 """
 
@@ -73,6 +75,23 @@ _REPORTS = {
 _REPORT_KINDS = sorted(_REPORTS) + ["impact", "communities", "flows"]  # extra args
 
 
+def _emit_answer(text: str) -> None:
+    """Print a markdown answer with the answer-format trailer (R1-C63).
+
+    One seam rather than a line in every renderer: the renderers stay pure functions of the
+    graph, and there is one place to forget rather than nine. The trailer is what a consumer
+    diffing our output sees when the *shape* of an answer changes deliberately — 0.0.20
+    changed the gate's lines while the graph stayed byte-identical, and on a text diff that
+    looked exactly like the #20 defect, where the text moved between runs of one version. The
+    only thing that told them apart was a message written by hand.
+    """
+    from codemap.model import ANSWER_FORMAT, SCHEMA_VERSION
+    print(text, end="")
+    if not text.endswith("\n"):
+        print()
+    print(f"_answer format {ANSWER_FORMAT} · schema {SCHEMA_VERSION}_")
+
+
 def _graph_from(args):
     if getattr(args, "build", None):
         return extract(args.build, deep=getattr(args, "deep", False))
@@ -138,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.
@@ -158,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).
 
@@ -316,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
@@ -507,28 +573,28 @@ def _cmd_report(args) -> int:
     if args.kind == "impact":
         if not args.symbol:
             raise SystemExit("error: report impact needs --symbol <name>")
-        print(render_impact(Query(graph), args.symbol, depth=args.depth,
-                            flow_depth=args.flow_depth), end="")
+        _emit_answer(render_impact(Query(graph), args.symbol, depth=args.depth,
+                        flow_depth=args.flow_depth))
         return 0
     if args.kind in ("communities", "flows"):
         from codemap.serve.subsystems import render_communities, render_flows
         q = Query(graph)
         out = (render_communities(q) if args.kind == "communities"
                else render_flows(q, args.symbol, depth=args.depth))
-        print(out, end="")
+        _emit_answer(out)
         return 0
     if args.kind == "dead-code":
         from codemap.serve.audit import load_dead_code_whitelist
         root = getattr(args, "source_root", None) or os.getcwd()
         whitelist, wl_error = load_dead_code_whitelist(root)
-        print(render_dead_code(Query(graph),
+        _emit_answer(render_dead_code(Query(graph),
                                whitelist=whitelist,
                                min_confidence=args.min_confidence,
-                               whitelist_error=wl_error), end="")
+                               whitelist_error=wl_error))
         return 0
     renderer = _REPORTS[args.kind]
     payload = renderer(graph) if args.kind == "api-surface" else renderer(Query(graph))
-    print(payload, end="")
+    _emit_answer(payload)
     return 0
 
 
@@ -724,15 +790,21 @@ 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 _cmd_check(args) -> int:
@@ -755,13 +827,13 @@ def _cmd_check(args) -> int:
     # would sort an unreadable contract into the success branch of every `if rc == 2` that
     # already exists in someone's pipeline.
     if contract.error:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         return 2
     if contract.is_empty() and args.require_contract:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         raise SystemExit("error: no [architecture] contract found (--require-contract)")
     violations = check_contract(q, contract)
-    print(render_check(q, contract, violations), end="")
+    _emit_answer(render_check(q, contract, violations))
     return 2 if violations else 0
 
 
@@ -778,7 +850,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)
@@ -930,6 +1002,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",
@@ -1077,6 +1154,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)
 

codmap-0.0.22/codemap/extract/probe.py

@@ -0,0 +1,152 @@
+"""Does each dependency still answer a known question correctly? (R1-C64)
+
+griffe and jedi do work codemap never re-checks: griffe resolves re-export aliases into the
+structure, jedi types a local variable into a call target. Both are hard dependencies, so the
+only "check" they ever got was that ``import`` did not fail. That is the wrong check for the
+failure that matters: a jedi that stopped resolving after an upgrade does not break a build —
+``_resolve_jedi`` reads any exception as ``unresolved`` — it turns every deep call into a
+fast-tier one, and the graph is simply poorer. Measured: with ``jedi.Script`` answering
+nothing, a deep build of a real 89-module tree exited 0 with ``calls`` equal to the fast tier's
+to the edge, while still declaring ``tier: deep``.
+
+The probe is the shape `jg doctor` uses (research/tools/jevgrep.md, S2): a synthetic input
+whose correct answer is known, and a backend that answers it wrongly is refused rather than
+counted as present. One fact per dependency, through the real pipeline — not a benchmark,
+which would be noisy and get switched off.
+
+Design: ``docs/design/dependency_probe.md``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import tempfile
+from pathlib import Path
+
+PROBE_PACKAGE = "codemap_probe"
+
+#: The probe tree. ``engine.run()`` needs a local variable's type (jedi only — the fast tier
+#: does not build that edge); ``ph()`` goes through a re-export alias whose target griffe
+#: resolves (``Alias.target_path``), which is where the ``export`` edge comes from.
+PROBE_FILES = {
+    "__init__.py": f"from {PROBE_PACKAGE}.core import helper as public_helper\n",
+    "core.py": ("class Engine:\n"
+                "    def run(self):\n"
+                "        return 1\n\n\n"
+                "def helper():\n"
+                "    return 2\n"),
+    "app.py": (f"from {PROBE_PACKAGE} import public_helper as ph\n"
+               f"from {PROBE_PACKAGE}.core import Engine\n\n\n"
+               "def main():\n"
+               "    engine = Engine()\n"
+               "    engine.run()\n"
+               "    return ph()\n"),
+}
+
+#: Outcomes. ``wrong`` is the case this module exists for: present, answering, mistaken.
+OK, WRONG, ABSENT, ERROR, NOT_RUN = "ok", "wrong", "absent", "error", "not-run"
+
+#: dependency → (edge type, source, target, resolution or None, what the fact means)
+EXPECTED = {
+    "griffe": ("export", PROBE_PACKAGE, f"{PROBE_PACKAGE}.core.helper", None,
+               f"the re-export `{PROBE_PACKAGE}.public_helper` resolves to "
+               f"`{PROBE_PACKAGE}.core.helper`"),
+    "jedi": ("calls", f"{PROBE_PACKAGE}.app.main", f"{PROBE_PACKAGE}.core.Engine.run", "deep",
+             f"`engine.run()` on a local `Engine()` resolves to "
+             f"`{PROBE_PACKAGE}.core.Engine.run`"),
+}
+
+
+def write_probe(directory: str | Path) -> Path:
+    """Write the probe package under ``directory`` and return its path."""
+    pkg = Path(directory) / PROBE_PACKAGE
+    pkg.mkdir(parents=True, exist_ok=True)
+    for name, body in PROBE_FILES.items():
+        (pkg / name).write_text(body, encoding="utf-8")
+    return pkg
+
+
+def _version(name: str) -> str | None:
+    from importlib.metadata import PackageNotFoundError, version
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return None
+
+
+def holds(graph, dependency: str) -> bool:
+    """Is the dependency's fact an edge of ``graph``?"""
+    etype, source, target, resolution, _ = EXPECTED[dependency]
+    return any(e.type == etype and e.source == source and e.target == target
+               and (resolution is None or e.extras.get("resolution") == resolution)
+               for e in graph.edges)
+
+
+def _expected_str(dependency: str) -> str:
+    etype, source, target, resolution, _ = EXPECTED[dependency]
+    return f"{etype} {source} → {target}" + (f" ({resolution})" if resolution else "")
+
+
+def _row(dependency: str, status: str, detail: str) -> dict:
+    return {"dependency": dependency, "version": _version(dependency), "status": status,
+            "fact": EXPECTED[dependency][4], "expected": _expected_str(dependency),
+            "detail": detail}
+
+
+def _importable(name: str) -> str | None:
+    """``None`` when ``name`` imports; otherwise why it does not."""
+    try:
+        importlib.import_module(name)
+    except Exception as exc:  # ImportError, or a broken install raising anything else
+        return f"not importable ({type(exc).__name__}: {exc})"
+    return None
+
+
+def _check(dependency: str, build) -> tuple[dict, bool]:
+    """Run one probe. Returns the row and whether its build produced a graph at all."""
+    why = _importable(dependency)
+    if why:
+        return _row(dependency, ABSENT, why), False
+    try:
+        graph = build()
+    except Exception as exc:
+        return _row(dependency, ERROR, f"the probe build raised {type(exc).__name__}: {exc}"), False
+    if holds(graph, dependency):
+        return _row(dependency, OK, "answered as expected"), True
+    return _row(dependency, WRONG, f"expected edge `{_expected_str(dependency)}` is not in "
+                                   "the graph — the dependency imports and answers, and the "
+                                   "answer is wrong"), True
+
+
+def run_probes() -> dict:
+    """Build the probe twice (fast for griffe, deep for jedi) and grade each dependency.
+
+    jedi's probe stands on griffe's structure: when the fast build already failed, a deep
+    result would mean nothing, so jedi is ``not-run`` — unknown, not wrong.
+    """
+    from codemap.extract import extract
+    with tempfile.TemporaryDirectory(prefix="codemap-probe-") as tmp:
+        pkg = write_probe(tmp)
+        griffe_row, built = _check("griffe", lambda: extract(str(pkg)))
+        if not built:
+            jedi_row = _row("jedi", NOT_RUN, "not run: the structural pass it stands on "
+                                             f"did not produce a graph ({griffe_row['status']})")
+        else:
+            jedi_row, _ = _check("jedi", lambda: extract(str(pkg), deep=True))
+    rows = [griffe_row, jedi_row]
+    return {"ok": all(r["status"] == OK for r in rows), "probes": rows}
+
+
+def render(report: dict) -> str:
+    """Plain text, one line per dependency, then a verdict line."""
+    lines = ["codemap doctor — does each dependency still answer a known question correctly?", ""]
+    for r in report["probes"]:
+        name = f"{r['dependency']} {r['version'] or '(version unknown)'}"
+        lines.append(f"{name:<22} {r['status'].upper():<8} {r['fact']}")
+        if r["status"] != OK:
+            lines.append(f"{'':<22} {'':<8} {r['detail']}")
+    lines.append("")
+    lines.append("✅ every probe answered as expected." if report["ok"] else
+                 "❌ at least one dependency is absent or answers wrongly — a graph built "
+                 "here may be poorer than its tier declares.")
+    return "\n".join(lines) + "\n"

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

@@ -77,6 +77,34 @@ from typing import Any
 #       (they had ``lineno`` alone, so `search` answered a line number with no file).
 SCHEMA_VERSION = "0.13"
 
+# R1-C63: the *answer* has a shape too, and consumers diff it. `SCHEMA_VERSION` versions the
+# artifact; 0.0.20 left the graph byte-identical and changed the architecture report and the
+# gate's lines completely (a cycle answer became a tangle), which on a text diff is
+# indistinguishable from the #20 defect — where the text moved between runs of one version,
+# without anyone deciding it. The only thing that told the consumer apart was a message I
+# wrote by hand.
+#
+# Bump on a change to the **structure a consumer sees**: a block appears or vanishes, a
+# counted unit changes meaning, a verdict or heading changes shape, a field in a structured
+# answer changes type or semantics. Do **not** bump for wording, typos or added prose inside
+# an existing note — a version that ticks on whitespace stops being read, which is worse than
+# not having one. Independent of SCHEMA_VERSION by design: the graph can be identical while
+# this moves, and that is the case it exists for.
+#
+# Starts at 1 with 0.0.21 and makes no claim about earlier releases: the answer format changed
+# many times before it, and numbering that retroactively would be inventing a history.
+#
+# History:
+#   1 — 0.0.21: first numbered format.
+#   2 — pack honesty: `pack` carries `seeds`, `unreachable_from_seeds` and `coverage`
+#       blocks, and a seed set that resolves to nothing is a refusal instead of the
+#       global pack (docs/design/pack_honesty.md). Before 2 was released, a seeded
+#       pack also began walking both ways by default — what the seeds use and what
+#       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
+
 # 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
 # codemap emits is one of these, each with a fixed meaning. This is the machine-