import_graph.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/import_graph.py
 
"""
AST import-graph extractor: closures, reverse edges, blind spots.
 
Purpose
-------
Answer "what does this set of modules actually drag in?" with a number
somebody else can reproduce. Built for plan 256, which had to re-derive
the `oc_orchestrator` extraction closure and found that the V0.1
analysis (2026-07-08) was computed by a script left in a session
scratchpad, so none of its numbers could be re-run. This tool is the
permanent fix: it is committed, it takes its seed set and its roots as
arguments rather than hardcoding one question, and it is deterministic,
so a reviewer can re-run it and diff the receipt.
 
It parses with :mod:`ast` and NEVER imports the code it analyses. A
module that raises at import time, or that does not even parse, is
analysed (or listed as a blind spot) rather than crashing the run.
 
Responsibilities
----------------
- :class:`Module` / :class:`Edge` / :class:`BlindSpot` / :class:`Graph` —
  the data model: one node per file, one edge per resolved import, one
  blind spot per import this tool provably cannot resolve.
- :func:`build_graph` — discover modules under the roots and extract
  every edge, resolving relative imports and classifying each target as
  standard library, third party, same package or sibling package.
- :func:`closure` — the transitive closure of same-package edges from a
  seed set, honouring `--cut` edge suppressions.
- :func:`parse_layer` — several named seed sets measured against one
  parsed tree, so a multi-layer question costs one receipt rather than
  one whole-graph copy per layer.
- :func:`reverse_edges` — who imports each in-tree module.
- :func:`receipt` / :func:`render_table` — the JSON receipt and the
  human table.
- :func:`main` — the CLI.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (graph built, closure computed)
    L3 - semantic details (per-module edge counts)
    L4 - deep tracing (per-edge)
 
Contracts
---------
- The code under measurement is never imported, only parsed.
- Determinism is a requirement, not a nicety: two runs over an unchanged
  tree produce byte-identical stdout and byte-identical JSON. The
  receipt therefore carries no clock and no absolute path -- roots
  appear as their directory NAME and module paths are root-relative
  POSIX, so a receipt is machine-independent. The tree the numbers
  belong to is pinned by the caller through ``--label``.
- A lazy (function-body) import is a dependency and is counted as one;
  it is flagged ``deferred`` so a reader can see which couplings are
  cheap to cut. A ``TYPE_CHECKING`` import is likewise counted and
  flagged through ``scope``.
- Known limitation, stated rather than hidden: only the
  ``importlib.import_module`` call shape is recognised as a string
  import. ``__import__``, ``importlib.util.spec_from_file_location`` and
  hand-rolled loaders are invisible to this tool. Grep for them
  separately before trusting a closure to be complete.
- Console output is ASCII only.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
 
from __future__ import annotations
 
import argparse
import ast
import fnmatch
import json
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Iterable, Sequence
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "module", "import graph extractor loaded", 4)
 
#: Receipt schema; bump when a field changes meaning.
SCHEMA_VERSION = "1.0"
 
#: Edge target classifications.
STDLIB = "stdlib"
THIRD_PARTY = "third_party"
SAME_PACKAGE = "same_package"
SIBLING = "sibling_package"
 
#: Edge kinds. ``module`` and ``lazy`` are import statements at module
#: level and inside a function body; ``string`` is an
#: ``importlib.import_module`` call with a literal argument.
KIND_MODULE = "module"
KIND_LAZY = "lazy"
KIND_STRING = "string"
 
#: Edge scopes.
SCOPE_RUNTIME = "runtime"
SCOPE_TYPE_CHECKING = "type_checking"
 
#: Blind-spot reasons.
REASON_NON_LITERAL = "import_module called with a non-literal argument"
REASON_RELATIVE = "relative import escapes the scanned roots"
REASON_UNPARSABLE = "file could not be parsed"
REASON_SHADOWED = "module name already claimed by an earlier root"
 
#: Directory names never walked.
_SKIP_DIRS = frozenset({
    "__pycache__", ".git", ".venv", ".mypy_cache", ".pytest_cache",
    ".ruff_cache", "node_modules", ".formatter_archive",
})
 
 
class ImportGraphError(RuntimeError):
    """A named refusal: an unknown seed, an unreadable root, a bad cut."""
 
 
@dataclass(frozen=True)
class Module:
    """One parsed source file."""
 
    name: str
    path: str
    lines: int
    is_package: bool
 
 
@dataclass(frozen=True)
class Edge:
    """One resolved import, from an in-tree module to some target."""
 
    source: str
    target: str
    line: int
    kind: str
    scope: str
    deferred: bool
    classification: str
 
 
@dataclass(frozen=True)
class BlindSpot:
    """An import this tool provably cannot resolve, named not dropped."""
 
    source: str
    line: int
    reason: str
    snippet: str
 
 
@dataclass(frozen=True)
class Graph:
    """The whole measured tree."""
 
    modules: dict[str, Module]
    edges: tuple[Edge, ...]
    blind_spots: tuple[BlindSpot, ...]
 
 
@dataclass(frozen=True)
class Cut:
    """A suppressed edge class, as ``source_glob->target_glob``."""
 
    source: str
    target: str
 
    def matches(self, edge: Edge) -> bool:
        """True when *edge* is suppressed by this cut."""
        return (
            fnmatch.fnmatchcase(edge.source, self.source)
            and fnmatch.fnmatchcase(edge.target, self.target)
        )
 
    def spec(self) -> str:
        """The round-trippable text form."""
        return f"{self.source}->{self.target}"
 
 
@dataclass(frozen=True)
class Closure:
    """The transitive same-package reach of one seed set."""
 
    name: str
    seeds: tuple[str, ...]
    members: tuple[str, ...]
    package_inits: tuple[str, ...]
    cut_edges: tuple[Edge, ...]
    external: dict[str, tuple[str, ...]]
    lines: int
 
    @property
    def size(self) -> int:
        """Modules in the closure, seeds included."""
        return len(self.members)
 
    @property
    def size_excluding_inits(self) -> int:
        """Modules in the closure that are not package markers."""
        return len(self.members) - len(self.package_inits)
 
 
# ---------------------------------------------------------------------
# Discovery
# ---------------------------------------------------------------------
 
def _module_name(root: Path, path: Path) -> tuple[str, bool]:
    """Dotted name for *path* under *root*, and whether it is a package."""
    parts = list(path.relative_to(root).parts)
    if parts[-1] == "__init__.py":
        return ".".join(parts[:-1]), True
    parts[-1] = parts[-1][: -len(".py")]
    return ".".join(parts), False
 
 
def _excluded(relative: str, excludes: Sequence[str]) -> bool:
    """True when the root-relative POSIX path matches an exclude glob."""
    return any(fnmatch.fnmatchcase(relative, pattern) for pattern in excludes)
 
 
def discover(
    roots: Sequence[Path],
    *,
    excludes: Sequence[str] = (),
) -> tuple[dict[str, Module], dict[str, Path], list[BlindSpot]]:
    """Find every ``*.py`` under *roots*, first root wins on a clash."""
    func = "discover"
    modules: dict[str, Module] = {}
    files: dict[str, Path] = {}
    shadowed: list[BlindSpot] = []
    for root in roots:
        if not root.is_dir():
            raise ImportGraphError(f"root is not a directory: {root.name}")
        for path in sorted(root.rglob("*.py")):
            if any(part in _SKIP_DIRS for part in path.relative_to(root).parts):
                continue
            relative = path.relative_to(root).as_posix()
            if _excluded(relative, excludes):
                continue
            name, is_package = _module_name(root, path)
            if not name:
                continue
            if name in modules:
                shadowed.append(BlindSpot(
                    source=name, line=0, reason=REASON_SHADOWED,
                    snippet=relative,
                ))
                continue
            text = _read(path)
            modules[name] = Module(
                name=name, path=relative, lines=_count_lines(text),
                is_package=is_package,
            )
            files[name] = path
    _dbg("OC_CHAT.MAIN", func, f"{len(modules)} module(s) discovered", 2)
    return modules, files, shadowed
 
 
def _read(path: Path) -> str:
    """Read *path* as UTF-8, tolerating a stray decoding error."""
    return path.read_text(encoding="utf-8", errors="replace")
 
 
def _count_lines(text: str) -> int:
    """Physical line count, counting a final unterminated line."""
    if not text:
        return 0
    return text.count("\n") + (0 if text.endswith("\n") else 1)
 
 
# ---------------------------------------------------------------------
# Classification
# ---------------------------------------------------------------------
 
def classify(target: str, *, package: str, siblings: Sequence[str]) -> str:
    """Classify an import target by its top-level name."""
    top = target.split(".", 1)[0]
    if top == package:
        return SAME_PACKAGE
    if top in siblings:
        return SIBLING
    if top in sys.stdlib_module_names:
        return STDLIB
    return THIRD_PARTY
 
 
# ---------------------------------------------------------------------
# Extraction
# ---------------------------------------------------------------------
 
def _resolve_relative(
    module: str, is_package: bool, level: int, tail: str | None,
) -> str | None:
    """Absolute name for a relative import, or None when it escapes."""
    parts = module.split(".") if module else []
    base = parts if is_package else parts[:-1]
    climb = level - 1
    if climb > len(base):
        return None
    if climb:
        base = base[: len(base) - climb]
    if not base:
        return None
    return ".".join([*base, tail] if tail else base)
 
 
def _importlib_aliases(tree: ast.AST) -> tuple[set[str], set[str]]:
    """Names bound to ``importlib`` and to ``import_module``."""
    modules: set[str] = set()
    functions: set[str] = set()
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                if alias.name == "importlib":
                    modules.add(alias.asname or "importlib")
        elif isinstance(node, ast.ImportFrom) and node.module == "importlib":
            for alias in node.names:
                if alias.name == "import_module":
                    functions.add(alias.asname or "import_module")
    return modules, functions
 
 
def _is_type_checking(test: ast.expr) -> bool:
    """True for ``if TYPE_CHECKING:`` in either spelling."""
    if isinstance(test, ast.Name):
        return test.id == "TYPE_CHECKING"
    if isinstance(test, ast.Attribute):
        return test.attr == "TYPE_CHECKING"
    return False
 
 
class _Extractor(ast.NodeVisitor):
    """Walk one module, recording edges and blind spots.
 
    Tracks two pieces of context the plain visitor does not carry: are we
    inside a function body (the import is deferred), and are we inside an
    ``if TYPE_CHECKING:`` block (the import is typing-only).
    """
 
    def __init__(
        self,
        *,
        module: Module,
        index: Iterable[str],
        package: str,
        siblings: Sequence[str],
        importlib_names: tuple[set[str], set[str]],
        source_lines: Sequence[str],
    ) -> None:
        self.module = module
        self.index = frozenset(index)
        self.package = package
        self.siblings = tuple(siblings)
        self.importlib_modules, self.import_module_names = importlib_names
        self.source_lines = source_lines
        self.edges: list[Edge] = []
        self.blind_spots: list[BlindSpot] = []
        self._deferred = False
        self._type_checking = False
 
    # -- context -----------------------------------------------------
 
    def _visit_function(self, node: ast.AST) -> None:
        """A function body: everything inside it is deferred."""
        previous = self._deferred
        self._deferred = True
        self.generic_visit(node)
        self._deferred = previous
 
    visit_FunctionDef = _visit_function
    visit_AsyncFunctionDef = _visit_function
    visit_Lambda = _visit_function
 
    def visit_If(self, node: ast.If) -> None:
        """``if TYPE_CHECKING:`` marks its body, never its else branch."""
        if _is_type_checking(node.test):
            previous = self._type_checking
            self._type_checking = True
            for statement in node.body:
                self.visit(statement)
            self._type_checking = previous
            for statement in node.orelse:
                self.visit(statement)
            return
        self.generic_visit(node)
 
    # -- emission ----------------------------------------------------
 
    def _scope(self) -> str:
        """The scope tag for an edge found at the current position."""
        return SCOPE_TYPE_CHECKING if self._type_checking else SCOPE_RUNTIME
 
    def _emit(self, target: str, line: int, kind: str, seen: set[str]) -> None:
        """Record *target* plus every in-tree ancestor package of it."""
        names: list[str] = []
        parts = target.split(".")
        for depth in range(1, len(parts) + 1):
            candidate = ".".join(parts[:depth])
            if candidate in self.index:
                names.append(candidate)
        if target not in self.index:
            names.append(target)
        for name in names:
            if name in seen or name == self.module.name:
                continue
            seen.add(name)
            self.edges.append(Edge(
                source=self.module.name, target=name, line=line, kind=kind,
                scope=self._scope(), deferred=self._deferred,
                classification=classify(
                    name, package=self.package, siblings=self.siblings,
                ),
            ))
 
    def _kind(self) -> str:
        """Import-statement kind at the current position."""
        return KIND_LAZY if self._deferred else KIND_MODULE
 
    def _snippet(self, line: int) -> str:
        """The source line, trimmed, for a blind-spot record."""
        if 1 <= line <= len(self.source_lines):
            return self.source_lines[line - 1].strip()[:200]
        return ""
 
    # -- imports -----------------------------------------------------
 
    def visit_Import(self, node: ast.Import) -> None:
        """``import a.b.c`` imports every package on the way down."""
        seen: set[str] = set()
        for alias in node.names:
            self._emit(alias.name, node.lineno, self._kind(), seen)
 
    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
        """``from X import y`` reaches X and, when it exists, ``X.y``."""
        seen: set[str] = set()
        if node.level:
            base = _resolve_relative(
                self.module.name, self.module.is_package, node.level,
                node.module,
            )
            if base is None:
                self.blind_spots.append(BlindSpot(
                    source=self.module.name, line=node.lineno,
                    reason=REASON_RELATIVE,
                    snippet=self._snippet(node.lineno),
                ))
                return
        elif node.module:
            base = node.module
        else:
            return
        self._emit(base, node.lineno, self._kind(), seen)
        for alias in node.names:
            if alias.name == "*":
                continue
            candidate = f"{base}.{alias.name}"
            if candidate in self.index:
                self._emit(candidate, node.lineno, self._kind(), seen)
 
    # -- string imports ----------------------------------------------
 
    def _is_import_module_call(self, node: ast.Call) -> bool:
        """True for the ``importlib.import_module`` call shapes we know."""
        target = node.func
        if isinstance(target, ast.Name):
            return target.id in self.import_module_names
        if isinstance(target, ast.Attribute) and target.attr == "import_module":
            base = target.value
            return isinstance(base, ast.Name) and (
                base.id in self.importlib_modules or base.id == "importlib"
            )
        return False
 
    def visit_Call(self, node: ast.Call) -> None:
        """A string import is an edge; a computed one is a blind spot."""
        if self._is_import_module_call(node):
            first = node.args[0] if node.args else None
            if isinstance(first, ast.Constant) and isinstance(first.value, str):
                self._emit(first.value, node.lineno, KIND_STRING, set())
            else:
                self.blind_spots.append(BlindSpot(
                    source=self.module.name, line=node.lineno,
                    reason=REASON_NON_LITERAL,
                    snippet=self._snippet(node.lineno),
                ))
        self.generic_visit(node)
 
 
def build_graph(
    roots: Sequence[Path | str],
    *,
    package: str,
    siblings: Sequence[str] = (),
    excludes: Sequence[str] = (),
) -> Graph:
    """Discover every module under *roots* and extract its import edges."""
    func = "build_graph"
    resolved = [Path(root) for root in roots]
    modules, files, blind_spots = discover(resolved, excludes=excludes)
    edges: list[Edge] = []
    for name in sorted(modules):
        module = modules[name]
        text = _read(files[name])
        try:
            tree = ast.parse(text, filename=module.path)
        except SyntaxError as exc:
            blind_spots.append(BlindSpot(
                source=name, line=exc.lineno or 0, reason=REASON_UNPARSABLE,
                snippet=str(exc.msg)[:200],
            ))
            continue
        extractor = _Extractor(
            module=module, index=modules, package=package,
            siblings=siblings, importlib_names=_importlib_aliases(tree),
            source_lines=text.splitlines(),
        )
        extractor.visit(tree)
        edges.extend(extractor.edges)
        blind_spots.extend(extractor.blind_spots)
        _dbg("OC_CHAT.MAIN", func, f"{name}: {len(extractor.edges)} edge(s)", 4)
    ordered = tuple(sorted(
        edges,
        key=lambda edge: (edge.source, edge.line, edge.target, edge.kind),
    ))
    spots = tuple(sorted(
        blind_spots, key=lambda spot: (spot.source, spot.line, spot.reason),
    ))
    _dbg(
        "OC_CHAT.MAIN", func,
        f"{len(ordered)} edge(s), {len(spots)} blind spot(s)", 2,
    )
    return Graph(modules=modules, edges=ordered, blind_spots=spots)
 
 
# ---------------------------------------------------------------------
# Closure and reverse edges
# ---------------------------------------------------------------------
 
def parse_layer(spec: str) -> tuple[str, tuple[str, ...]]:
    """Parse ``name=mod1,mod2`` into a named seed set."""
    if "=" not in spec:
        raise ImportGraphError(f"layer needs the name=modules form: {spec}")
    name, joined = spec.split("=", 1)
    seeds = tuple(part.strip() for part in joined.split(",") if part.strip())
    if not name.strip() or not seeds:
        raise ImportGraphError(f"layer has an empty side: {spec}")
    return name.strip(), seeds
 
 
def parse_cut(spec: str) -> Cut:
    """Parse ``source_glob->target_glob`` into a :class:`Cut`."""
    if "->" not in spec:
        raise ImportGraphError(f"cut needs the source->target form: {spec}")
    source, target = spec.split("->", 1)
    if not source.strip() or not target.strip():
        raise ImportGraphError(f"cut has an empty side: {spec}")
    return Cut(source=source.strip(), target=target.strip())
 
 
def closure(
    graph: Graph,
    seeds: Sequence[str],
    *,
    name: str = "closure",
    cuts: Sequence[Cut] = (),
) -> Closure:
    """Transitive same-package reach of *seeds*, honouring *cuts*."""
    func = "closure"
    unknown = [seed for seed in seeds if seed not in graph.modules]
    if unknown:
        raise ImportGraphError(
            "seed not found in the scanned tree: " + ", ".join(sorted(unknown)),
        )
    outgoing: dict[str, list[Edge]] = {}
    for edge in graph.edges:
        outgoing.setdefault(edge.source, []).append(edge)
 
    members: set[str] = set(seeds)
    cut_edges: list[Edge] = []
    pending = list(seeds)
    while pending:
        current = pending.pop()
        for edge in outgoing.get(current, ()):
            if any(cut.matches(edge) for cut in cuts):
                cut_edges.append(edge)
                continue
            if edge.classification != SAME_PACKAGE:
                continue
            if edge.target not in graph.modules or edge.target in members:
                continue
            members.add(edge.target)
            pending.append(edge.target)
 
    ordered = tuple(sorted(members))
    external: dict[str, set[str]] = {
        STDLIB: set(), THIRD_PARTY: set(), SIBLING: set(),
    }
    for edge in graph.edges:
        if edge.source not in members:
            continue
        if any(cut.matches(edge) for cut in cuts):
            continue
        if edge.classification in external:
            external[edge.classification].add(edge.target)
    _dbg("OC_CHAT.MAIN", func, f"{name}: closure of {len(ordered)}", 2)
    return Closure(
        name=name,
        seeds=tuple(sorted(seeds)),
        members=ordered,
        package_inits=tuple(
            member for member in ordered if graph.modules[member].is_package
        ),
        cut_edges=tuple(sorted(
            set(cut_edges),
            key=lambda edge: (edge.source, edge.line, edge.target),
        )),
        external={key: tuple(sorted(value)) for key, value in external.items()},
        lines=sum(graph.modules[member].lines for member in ordered),
    )
 
 
def reverse_edges(graph: Graph) -> dict[str, tuple[str, ...]]:
    """For every in-tree module, the sorted set of modules importing it."""
    importers: dict[str, set[str]] = {}
    for edge in graph.edges:
        if edge.target in graph.modules:
            importers.setdefault(edge.target, set()).add(edge.source)
    return {
        target: tuple(sorted(sources))
        for target, sources in sorted(importers.items())
    }
 
 
# ---------------------------------------------------------------------
# Output
# ---------------------------------------------------------------------
 
def _tally(values: Iterable[str]) -> dict[str, int]:
    """Sorted count-by-value, for the receipt's summary blocks."""
    counts: dict[str, int] = {}
    for value in values:
        counts[value] = counts.get(value, 0) + 1
    return {key: counts[key] for key in sorted(counts)}
 
 
def _closure_payload(result: Closure) -> dict[str, object]:
    """One closure, as receipt JSON."""
    return {
        "name": result.name,
        "seeds": list(result.seeds),
        "size": result.size,
        "size_excluding_inits": result.size_excluding_inits,
        "lines": result.lines,
        "members": list(result.members),
        "package_inits": list(result.package_inits),
        "external": {key: list(value) for key, value in result.external.items()},
        "cut_edges": [_edge_payload(edge) for edge in result.cut_edges],
    }
 
 
def _edge_payload(edge: Edge) -> dict[str, object]:
    """One edge, as receipt JSON."""
    return {
        "source": edge.source, "target": edge.target, "line": edge.line,
        "kind": edge.kind, "scope": edge.scope, "deferred": edge.deferred,
        "classification": edge.classification,
    }
 
 
def receipt(
    graph: Graph,
    closures: Sequence[Closure],
    *,
    label: str,
    params: dict[str, object],
) -> dict[str, object]:
    """Build the JSON receipt: no clock, no absolute path, fully sorted."""
    func = "receipt"
    _dbg("OC_CHAT.MAIN", func, f"receipt for {len(closures)} closure(s)", 3)
    return {
        "schema_version": SCHEMA_VERSION,
        "label": label,
        "params": params,
        "tree": {
            "modules": len(graph.modules),
            "lines": sum(m.lines for m in graph.modules.values()),
            "edges": len(graph.edges),
            "edges_by_kind": _tally(e.kind for e in graph.edges),
            "edges_by_scope": _tally(e.scope for e in graph.edges),
            "edges_by_class": _tally(e.classification for e in graph.edges),
            "deferred_edges": sum(1 for e in graph.edges if e.deferred),
            "blind_spots": len(graph.blind_spots),
        },
        "blind_spots": [
            {
                "source": spot.source, "line": spot.line,
                "reason": spot.reason, "snippet": spot.snippet,
            }
            for spot in graph.blind_spots
        ],
        "closures": [_closure_payload(result) for result in closures],
        "modules": {
            name: {
                "path": module.path, "lines": module.lines,
                "is_package": module.is_package,
            }
            for name, module in sorted(graph.modules.items())
        },
        "edges": [_edge_payload(edge) for edge in graph.edges],
        "reverse_edges": {
            target: list(sources)
            for target, sources in reverse_edges(graph).items()
        },
    }
 
 
def _closure_block(graph: Graph, result: Closure) -> list[str]:
    """The human table for one closure."""
    lines = [
        "",
        f"== closure: {result.name} ==",
        f"seeds ({len(result.seeds)}): {', '.join(result.seeds)}",
        f"size: {result.size} module(s), "
        f"{result.size_excluding_inits} excluding package markers, "
        f"{result.lines} line(s)",
        "",
        "  lines  module",
    ]
    for member in result.members:
        marker = " (pkg)" if graph.modules[member].is_package else ""
        lines.append(f"  {graph.modules[member].lines:5d}  {member}{marker}")
    for key, title in (
        (SIBLING, "sibling"), (THIRD_PARTY, "third party"), (STDLIB, "stdlib"),
    ):
        values = result.external.get(key, ())
        lines.append(f"  {title}: {', '.join(values) if values else 'none'}")
    if result.cut_edges:
        lines.append(f"  cut edges ({len(result.cut_edges)}):")
        for edge in result.cut_edges:
            lines.append(
                f"    {edge.source}:{edge.line} -> {edge.target} "
                f"[{edge.kind}]",
            )
    return lines
 
 
def render_table(
    graph: Graph,
    closures: Sequence[Closure],
    *,
    label: str,
    roots: Sequence[str],
) -> str:
    """The human report. ASCII only, and stable across runs."""
    lines = [
        "== import graph ==",
        f"label: {label}",
        f"roots: {', '.join(roots)}",
        f"modules: {len(graph.modules)}  "
        f"lines: {sum(m.lines for m in graph.modules.values())}  "
        f"edges: {len(graph.edges)}",
        f"by kind: {_tally(e.kind for e in graph.edges)}",
        f"by class: {_tally(e.classification for e in graph.edges)}",
        f"deferred: {sum(1 for e in graph.edges if e.deferred)}  "
        f"type-checking: "
        f"{sum(1 for e in graph.edges if e.scope == SCOPE_TYPE_CHECKING)}",
        f"blind spots: {len(graph.blind_spots)}",
    ]
    for spot in graph.blind_spots:
        lines.append(f"  {spot.source}:{spot.line} {spot.reason}")
        if spot.snippet:
            lines.append(f"    {spot.snippet}")
    for result in closures:
        lines.extend(_closure_block(graph, result))
    return "\n".join(lines) + "\n"
 
 
# ---------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------
 
def build_parser() -> argparse.ArgumentParser:
    """The CLI surface; every question is an argument, none is baked in."""
    parser = argparse.ArgumentParser(
        prog="import_graph",
        description="AST import-graph closures with reproducible receipts.",
    )
    parser.add_argument(
        "--root", action="append", required=True, metavar="DIR",
        help="directory on the import path; repeatable, first wins on clash",
    )
    parser.add_argument(
        "--package", required=True,
        help="top-level package whose edges the closure follows",
    )
    parser.add_argument(
        "--sibling", action="append", default=[], metavar="NAME",
        help="top-level name to classify as a sibling package; repeatable",
    )
    parser.add_argument(
        "--seed", action="append", default=[], metavar="MODULE",
        help="closure seed; repeatable",
    )
    parser.add_argument(
        "--closure-name", default="closure",
        help="name recorded for this closure in the receipt",
    )
    parser.add_argument(
        "--layer", action="append", default=[], metavar="NAME=MODULES",
        help="a named, comma-separated seed set; repeatable, so one run "
             "and one receipt can cover several layers of the same tree",
    )
    parser.add_argument(
        "--cut", action="append", default=[], metavar="SRC->DST",
        help="suppress matching edges; both sides accept glob wildcards. "
             "Cuts are global to the run: a layer with no matching edge is "
             "simply unaffected",
    )
    parser.add_argument(
        "--exclude", action="append", default=[], metavar="GLOB",
        help="skip root-relative POSIX paths matching this glob; repeatable",
    )
    parser.add_argument(
        "--json", metavar="PATH", help="write the JSON receipt here",
    )
    parser.add_argument(
        "--label", default="",
        help="what tree these numbers belong to; recorded verbatim",
    )
    return parser
 
 
def main(argv: Sequence[str] | None = None) -> int:
    """Run one measurement. 0 on success, 1 on a named refusal."""
    func = "main"
    args = build_parser().parse_args(list(argv) if argv is not None else None)
    try:
        cuts = [parse_cut(spec) for spec in args.cut]
        layers: list[tuple[str, Sequence[str]]] = []
        if args.seed:
            layers.append((args.closure_name, args.seed))
        layers.extend(parse_layer(spec) for spec in args.layer)
        graph = build_graph(
            [Path(root) for root in args.root], package=args.package,
            siblings=args.sibling, excludes=args.exclude,
        )
        closures: list[Closure] = []
        for name, seeds in layers:
            closures.append(closure(graph, seeds, name=name))
            if cuts:
                closures.append(closure(
                    graph, seeds, name=f"{name}+cuts", cuts=cuts,
                ))
    except ImportGraphError as exc:
        print(f"import_graph: {exc}", file=sys.stderr)
        return 1
 
    root_names = [Path(root).resolve().name for root in args.root]
    print(render_table(graph, closures, label=args.label, roots=root_names),
          end="")
    if args.json:
        params: dict[str, object] = {
            "roots": root_names,
            "package": args.package,
            "siblings": sorted(args.sibling),
            "excludes": sorted(args.exclude),
            "seeds": sorted(args.seed),
            "cuts": [cut.spec() for cut in cuts],
            "closure_name": args.closure_name,
            "layers": sorted(args.layer),
        }
        document = receipt(graph, closures, label=args.label, params=params)
        text = json.dumps(document, indent=2, sort_keys=True) + "\n"
        Path(args.json).write_text(text, encoding="utf-8", newline="\n")
        _dbg("OC_CHAT.MAIN", func, f"receipt written to {args.json}", 2)
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())