@descryy/adapter-python 0.1.0

package/src/extract.py

@@ -0,0 +1,1319 @@
+"""Descry's Python-side extractor — DEC-062.
+
+Shipped as a file and invoked by path, never assembled by string concatenation
+in Node. It reads a JSON request on stdin and writes one JSON document to
+stdout; nothing is printed anywhere else, because stdout is the protocol.
+
+## What it does and, more importantly, what it does not
+
+It walks `ast` and reports **what the source says**. It resolves nothing across
+files, decides no edges and makes no claim about which declaration a name refers
+to — all of that is the Node side's job, where the resolution level is tracked
+and the IR boundary lives. This file's output is deliberately closer to a parse
+tree than to IR.
+
+The split matters for one reason: everything here is R0. A fact this file states
+is a fact about one file's text, and a fact that needs two files is not its to
+state.
+
+## Isolation
+
+A file that fails to parse is recorded in `errors` with a typed reason and does
+not stop the run. A Python file with a syntax error cannot be imported or
+executed by anyone, so it is broken for the repository too — but "we could not
+read seven of your files" and "we read them and found nothing" are different
+statements, and only the ledger keeps them apart.
+
+Requires nothing outside the standard library, so it runs against a repository
+with no dependencies installed. That is the R0 contract.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+import sys
+
+# --- DEC-069: which module-level assignments are type aliases ----------------
+#
+# Python has no dedicated alias syntax before 3.12, so `X = Literal["a"]` and
+# `MAX = 5` are the same grammar and telling them apart is a judgement call.
+# Precision over recall decides it: this is a *closed* list of syntactically
+# unambiguous type expressions, and anything not on it stays unmodelled.
+
+#: Modules that provide type constructors. `collections.abc` belongs here and
+#: leaving it out was a measured defect — PEP 585 deprecated `typing.Callable`
+#: in favour of `collections.abc.Callable` in 3.9, and on the repository this
+#: was sized against 5 of 9 `Callable` imports already take the modern form.
+#: Admitting only `typing` rejected 12 of 31 aliases.
+TYPING_MODULES = frozenset({"typing", "typing_extensions", "collections.abc"})
+
+#: Subscriptable constructors that only ever appear in a type expression.
+TYPING_CONSTRUCTORS = frozenset(
+    {
+        "Annotated", "Callable", "Literal", "Optional", "Union", "Sequence", "Mapping",
+        "MutableMapping", "MutableSequence", "Iterable", "Iterator", "AsyncIterator",
+        "AsyncIterable", "Awaitable", "Coroutine", "Generator", "AsyncGenerator",
+        "Dict", "List", "Set", "FrozenSet", "Tuple", "Type", "DefaultDict", "Deque",
+        "Final", "ClassVar", "Concatenate", "Required", "NotRequired", "Unpack",
+    }
+)
+
+#: Builtins whose subscripted form is a type expression and never a value.
+BUILTIN_CONTAINERS = frozenset({"list", "dict", "set", "tuple", "frozenset", "type"})
+
+#: Calls that *are* the declaration of a type.
+DECLARING_CALLS = frozenset({"TypeVar", "NewType", "ParamSpec", "TypeVarTuple"})
+
+#: Names that are types but never nodes, so never constituents of an alias edge.
+BUILTIN_TYPES = frozenset(
+    {"str", "int", "float", "bool", "bytes", "object", "complex", "bytearray", "None", "Any"}
+) | BUILTIN_CONTAINERS
+
+
+def _range(node: ast.AST) -> dict[str, int]:
+    start = getattr(node, "lineno", 1)
+    return {"startLine": start, "endLine": getattr(node, "end_lineno", None) or start}
+
+
+def _annotation(node: ast.AST | None) -> str | None:
+    """An annotation as written, not as evaluated.
+
+    `ast.unparse` gives back source text — `Optional[str]`, `str | None`,
+    `list[Order]` — which is exactly what the Node side needs to decide
+    nullability and to find the type names a declaration depends on. Evaluating
+    it would mean importing the repository's modules, which is arbitrary code
+    execution on cloned customer code.
+    """
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:  # pragma: no cover - unparse is total in practice
+        return None
+
+
+#: A value was written and this reader cannot state what it is. Distinct from
+#: "not written", and the distinction is load-bearing: `nullable=True` and
+#: `nullable=FLAG` are both written, and reading the second as absent would let a
+#: framework default answer a question the source has already answered.
+_OPAQUE = object()
+
+
+def _literal(node: ast.AST | None):
+    """A written constant, or `_OPAQUE` where the value is computed."""
+    if isinstance(node, ast.Constant) and (
+        node.value is None or isinstance(node.value, (str, bool, int, float))
+    ):
+        return node.value
+    return _OPAQUE
+
+
+def _attribute(target: ast.Name, value: ast.AST | None, annotation: ast.AST | None, line: int) -> dict:
+    """One assignment in a class body, recorded by syntactic form.
+
+    No ORM is named here and none is recognised. `id = Column(String,
+    nullable=True)`, `total = models.IntegerField()` and `__tablename__ =
+    "orders"` are all just an assignment with a callee, some keywords and a
+    literal — deciding which of them is a persistence mapping is the Node side's
+    job, and keeping that decision out of this file is what lets a framework be
+    added or withdrawn without touching the parser.
+    """
+    callee = None
+    args: list[str] = []
+    keywords: dict[str, object] = {}
+    opaque: list[str] = []
+    literal = _OPAQUE
+
+    if isinstance(value, ast.Call):
+        callee = _annotation(value.func)
+        args = [_annotation(argument) or "" for argument in value.args]
+        for keyword in value.keywords:
+            if keyword.arg is None:
+                continue
+            read = _literal(keyword.value)
+            if read is _OPAQUE:
+                opaque.append(keyword.arg)
+            else:
+                keywords[keyword.arg] = read
+    elif value is not None:
+        literal = _literal(value)
+
+    return {
+        "name": target.id,
+        "annotation": _annotation(annotation),
+        "callee": callee,
+        "args": args,
+        "keywords": keywords,
+        "opaqueKeywords": opaque,
+        "literal": None if literal is _OPAQUE else literal,
+        "hasLiteral": literal is not _OPAQUE,
+        "line": line,
+    }
+
+
+def _call_record(node: ast.Call, line: int, scope: list[str] | None = None) -> dict:
+    """One call, recorded by syntactic form, naming no framework.
+
+    `@router.get("/items/{id}")`, `api.include_router(x, prefix="/p")` and
+    `path("admin/", admin.site.urls)` are all just a receiver, an attribute, some
+    positional arguments and some keywords here. Deciding which of them declares
+    an HTTP route is the Node side's job, exactly as `_attribute` leaves the ORM
+    decision there.
+
+    **A positional argument is recorded three ways on purpose.** `literals`
+    carries the written constant where there is one, `names` carries the bare
+    identifier where the argument is a plain `Name`, and `args` carries the
+    source text unconditionally. A route path built at runtime and a route path
+    written as a string must stay distinguishable after serialisation, because
+    emitting a route for the first joins a caller to a path that does not exist
+    — and nothing downstream can tell that from a correct edge.
+    """
+    receiver = None
+    attribute = None
+    func = node.func
+    if isinstance(func, ast.Attribute):
+        attribute = func.attr
+        if isinstance(func.value, ast.Name):
+            receiver = func.value.id
+    elif isinstance(func, ast.Name):
+        attribute = func.id
+
+    literals: list[object] = []
+    names: list[object] = []
+    arg_calls: list[object] = []
+    for argument in node.args:
+        read = _literal(argument)
+        literals.append(None if read is _OPAQUE else read)
+        names.append(argument.id if isinstance(argument, ast.Name) else None)
+        # One level of nesting, no more. `path("api/", include("app.urls"))`
+        # states a prefix and the module it applies to in one expression, and
+        # flattening it would lose which prefix governs which module. Deeper
+        # nesting is not recorded because nothing measured needs it, and an
+        # unbounded walk here is how this document grew to 284 MB once already.
+        arg_calls.append(
+            _call_record(argument, argument.lineno) if isinstance(argument, ast.Call) else None
+        )
+
+    keywords: dict[str, object] = {}
+    keywordNames: dict[str, str] = {}
+    keywordText: dict[str, str] = {}
+    keywordLists: dict[str, list] = {}
+    opaque: list[str] = []
+    for keyword in node.keywords:
+        if keyword.arg is None:
+            continue
+        read = _literal(keyword.value)
+        if read is _OPAQUE:
+            # A list or tuple of written constants is still written down.
+            # `methods=["GET", "POST"]` is the source stating the verbs outright,
+            # and reading it as opaque would make a declared method look absent.
+            if isinstance(keyword.value, (ast.List, ast.Tuple)):
+                items = [_literal(element) for element in keyword.value.elts]
+                if items and all(item is not _OPAQUE for item in items):
+                    keywordLists[keyword.arg] = items
+                else:
+                    opaque.append(keyword.arg)
+            else:
+                opaque.append(keyword.arg)
+        else:
+            keywords[keyword.arg] = read
+        if isinstance(keyword.value, ast.Name):
+            keywordNames[keyword.arg] = keyword.value.id
+        # The source text unconditionally. `response_model=OrderRead` is a bare
+        # name and `response_model=list[OrderRead]` is not, and both name the
+        # same type — a reader restricted to bare names sees only the first.
+        text = _annotation(keyword.value)
+        if text is not None:
+            keywordText[keyword.arg] = text
+
+    return {
+        "callee": _annotation(func),
+        "receiver": receiver,
+        "attribute": attribute,
+        "args": [_annotation(argument) or "" for argument in node.args],
+        "literals": literals,
+        "argNames": names,
+        "argCalls": arg_calls,
+        "hasLiterals": [_literal(argument) is not _OPAQUE for argument in node.args],
+        "keywords": keywords,
+        "keywordNames": keywordNames,
+        "keywordText": keywordText,
+        "keywordLists": keywordLists,
+        "opaqueKeywords": opaque,
+        "scope": list(scope or []),
+        "line": line,
+    }
+
+
+def _class_attributes(node: ast.ClassDef) -> list[dict]:
+    """Every assignment directly in a class body, annotated or not.
+
+    `fields` above collects only `AnnAssign`, which is right for a dataclass and
+    blind to SQLAlchemy 1.x and to Django, where a mapped column is a plain
+    `Assign` with a call on the right.
+    """
+    collected: list[dict] = []
+    for stmt in _docstring_free(node.body):
+        if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+            collected.append(_attribute(stmt.target, stmt.value, stmt.annotation, stmt.lineno))
+        elif (
+            isinstance(stmt, ast.Assign)
+            and len(stmt.targets) == 1
+            and isinstance(stmt.targets[0], ast.Name)
+        ):
+            collected.append(_attribute(stmt.targets[0], stmt.value, None, stmt.lineno))
+    return collected
+
+
+def _docstring_free(body: list[ast.stmt]) -> list[ast.stmt]:
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+        if isinstance(body[0].value.value, str):
+            return body[1:]
+    return body
+
+
+class Collector(ast.NodeVisitor):
+    """One pass, gathering declarations, references and imports per file."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self.declarations: list[dict] = []
+        self.imports: list[dict] = []
+        self.references: list[dict] = []
+        # The declaration a reference is attributed to: a dotted path such as
+        # ["OrderService", "calculate_total"]. Nested functions push onto this,
+        # so a reference inside a closure is still attributed to the top-level
+        # declaration that contains it.
+        self._scope: list[str] = []
+        # Module-level `name = ClassName()`, which is the only inference this
+        # file performs and the only one it can perform without a checker.
+        self.instantiations: list[dict] = []
+        # Module-level assignments that *might* be type aliases. Classified in
+        # `collect()` rather than here, because rule 4 asks where a constructor
+        # was imported from and the import table is only complete once the whole
+        # file has been walked. The AST value is kept and never serialised.
+        self.alias_candidates: list[dict] = []
+        # DEC-072: a class referenced as a *value* rather than named in a type.
+        # Recorded by syntactic form so the Node side can decide, and so a form
+        # that turns out to be wrong can be removed without touching the rest.
+        # Deliberately an inclusion list, not "everything that is not excluded":
+        # every form here was counted on real code before it was admitted.
+        self.value_refs: list[dict] = []
+        # Module-scope calls with their arguments, by syntactic form. Route
+        # declarations and router mounts are written here in every framework
+        # surveyed; naming any of them is the Node side's job.
+        self.calls: list[dict] = []
+        # `name = Call(...)` at module scope or one level in, dotted callees
+        # included. Feeds the route extractor's router table.
+        self.constructions: list[dict] = []
+        # Module-scope `NAME = "literal"`. The one thing needed to resolve the
+        # base of `requests.get(f"{BASE}/orders")`, which is how a Python
+        # service actually writes a call to another service: across five
+        # reference repositories not one module-level HTTP verb takes a
+        # repository-relative literal, and 78 of them take an f-string whose
+        # first element is exactly this kind of name.
+        self.constants: list[dict] = []
+        # Set by `collect()` when this file imports a package the caller named.
+        self.deep_calls: bool = False
+        # `url = f"{BASE}/orders"` inside a function, in a file that imports a
+        # client package. The largest named bucket in the caller ledger: 12 of
+        # 22 rows on the small corpora and 96 of 224 on posthog pass a local
+        # assembled a few lines above the call.
+        self.local_strings: list[dict] = []
+
+    # --- declarations ------------------------------------------------------
+
+    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        path = [*self._scope, node.name]
+        self.declarations.append(
+            {
+                "kind": "function",
+                "path": path,
+                "name": ".".join(path),
+                "range": _range(node),
+                "returns": _annotation(node.returns),
+                "params": [
+                    {"name": arg.arg, "annotation": _annotation(arg.annotation)}
+                    for arg in [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
+                    # `self` and `cls` carry no annotation and name no type.
+                    if arg.arg not in ("self", "cls")
+                ],
+                "decorators": [_annotation(d) for d in node.decorator_list],
+                "decoratorCalls": [
+                    # The scope a decorator is *evaluated* in is the one
+                    # containing the declaration, not the declaration's own.
+                    # `@app.route(...)` on a function nested in a test resolves
+                    # `app` in that test's scope.
+                    _call_record(d, d.lineno, self._scope)
+                    for d in node.decorator_list
+                    if isinstance(d, ast.Call)
+                ],
+            }
+        )
+        self._scope.append(node.name)
+        # Attributed to the declaration being decorated, for the same reason the
+        # defaults below are: the dependency belongs to `handle`, and filing it
+        # at module level leaves it with no declaration to hang on.
+        self._decorator_refs(node)
+        # Attributed to the function being declared, not to the scope Python
+        # evaluates the default in. The dependency belongs to `create_app`, and
+        # filing it at module level leaves it with no declaration to hang on.
+        for default in [*node.args.defaults, *node.args.kw_defaults]:
+            self._value_ref(default, "default")
+        for child in node.body:
+            self.visit(child)
+        self._scope.pop()
+
+    visit_FunctionDef = _function
+    visit_AsyncFunctionDef = _function
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        path = [*self._scope, node.name]
+        fields = [
+            {
+                "name": stmt.target.id,
+                "annotation": _annotation(stmt.annotation),
+                "hasDefault": stmt.value is not None,
+            }
+            for stmt in _docstring_free(node.body)
+            if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name)
+        ]
+        self.declarations.append(
+            {
+                "kind": "class",
+                "path": path,
+                "name": ".".join(path),
+                "range": _range(node),
+                "bases": [_annotation(b) for b in node.bases],
+                "fields": fields,
+                "attributes": _class_attributes(node),
+                "decorators": [_annotation(d) for d in node.decorator_list],
+                "decoratorCalls": [
+                    # The scope a decorator is *evaluated* in is the one
+                    # containing the declaration, not the declaration's own.
+                    # `@app.route(...)` on a function nested in a test resolves
+                    # `app` in that test's scope.
+                    _call_record(d, d.lineno, self._scope)
+                    for d in node.decorator_list
+                    if isinstance(d, ast.Call)
+                ],
+            }
+        )
+        self._scope.append(node.name)
+        self._decorator_refs(node)
+        for child in node.body:
+            self.visit(child)
+        self._scope.pop()
+
+    # --- imports -----------------------------------------------------------
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            self.imports.append(
+                {
+                    "kind": "absolute",
+                    "level": 0,
+                    "module": alias.name,
+                    "name": None,
+                    "local": alias.asname or alias.name.split(".")[0],
+                    "line": node.lineno,
+                }
+            )
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        for alias in node.names:
+            self.imports.append(
+                {
+                    # `level` is the number of leading dots and is the whole of
+                    # relative-import resolution. `from . import x` is level 1
+                    # with no module, which is the re-export hop pattern 3 turns
+                    # on, and it is not recoverable from the text alone.
+                    "kind": "relative" if node.level else "absolute",
+                    "level": node.level,
+                    "module": node.module,
+                    "name": alias.name,
+                    "local": alias.asname or alias.name,
+                    "line": node.lineno,
+                }
+            )
+
+    # --- references --------------------------------------------------------
+
+    def visit_Call(self, node: ast.Call) -> None:
+        # Arguments first, so `isinstance(x, Foo)` and `f(response_model=Foo)`
+        # are recorded whatever the callee turns out to be. The callee itself is
+        # a constructor call and is already covered (DEC-068).
+        for argument in node.args:
+            self._value_ref(argument, "argument")
+        for keyword in node.keywords:
+            self._value_ref(keyword.value, "argument")
+
+        func = node.func
+        if isinstance(func, ast.Name):
+            self._reference("call", func.id, None, func.lineno)
+        elif isinstance(func, ast.Attribute):
+            base = func.value
+            # `service.calculate_total(...)` — the receiver is reported as
+            # written. Deciding what `service` is belongs to the Node side.
+            receiver = base.id if isinstance(base, ast.Name) else None
+            if isinstance(base, ast.Name) and base.id == "self":
+                receiver = "self"
+            self._reference("method", func.attr, receiver, func.lineno)
+
+        # Calls at module scope **and one level in**, with their arguments.
+        #
+        # "Module scope only" was the first rule and it was wrong, measured on
+        # the second repository rather than reasoned about. The application
+        # factory — `def get_app(): app = FastAPI(); app.include_router(...)` —
+        # is a documented idiom in both Flask and FastAPI, and it put the entire
+        # mount chain one level below where this was looking. On sherpa-backend
+        # that cost **47 of 49 routes**, disclosed as "router never mounted",
+        # which is a true sentence about what this file recorded and a false one
+        # about the repository.
+        #
+        # Depth 1 and no deeper: it covers a top-level function or class body,
+        # which is where declarative configuration is written, and it leaves the
+        # payload bounded. The 284 MB overflow that forced line-delimited output
+        # is the standing reminder that this document has a size budget.
+        if len(self._scope) <= 1:
+            self.calls.append(_call_record(node, node.lineno, self._scope))
+        elif self.deep_calls and isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+            # Depth 1 is right for declarative configuration and wrong for the
+            # caller half: an HTTP call lives in a method, which is depth 2.
+            # Measured on `dispatch` — the text holds 14 module-level
+            # `requests`/`httpx` verb calls and this reader saw **4**, so ten
+            # were neither an edge nor a ledger row.
+            #
+            # Widened along two axes at once, deliberately, because the 284 MB
+            # overflow that forced line-delimited output is what a general
+            # widening here costs: only in a file that imports one of the
+            # packages the Node side named, and only for `name.attr(...)`, which
+            # is the exact shape the client reader consumes. Everything else at
+            # depth 2 and below stays unrecorded.
+            self.calls.append(_call_record(node, node.lineno, self._scope))
+
+        # A test case is a call, so it is recognised here rather than in a
+        # second walk over the same tree.
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        if isinstance(node.value, ast.Name):
+            # Load or Store. `resp.total = x` writes; `order.total_amount` reads,
+            # and calling both a read would put a WRITES relationship in the
+            # graph under the READS label — a false claim about direction, which
+            # data propagation is built on.
+            kind = "attribute_write" if isinstance(node.ctx, ast.Store) else "attribute"
+            self._reference(kind, node.attr, node.value.id, node.lineno)
+        self.generic_visit(node)
+
+    def _constant(self, target: ast.expr, value: ast.expr, line: int) -> None:
+        """Record `NAME = "literal"` at module scope, and nothing cleverer.
+
+        A string built by concatenation, `os.environ.get`, or a call is *not*
+        recorded: an unresolved base becomes a named refusal on the Node side,
+        and a base guessed from half its expression is an endpoint nobody
+        serves. Same asymmetry as everywhere else — a missing constant is a
+        disclosed gap, a wrong one is a wrong edge.
+        """
+        if len(self._scope) != 0 or not isinstance(target, ast.Name):
+            return
+        if not isinstance(value, ast.Constant) or not isinstance(value.value, str):
+            return
+        self.constants.append({"name": target.id, "value": value.value, "line": line})
+
+    def _local_string(self, target: ast.expr, value: ast.expr, line: int) -> None:
+        """`name = "literal"` or `name = f"..."` inside a function.
+
+        Recorded only in a file that imports a client package, and only below
+        module scope — the module-level case is already `constants`. The value
+        is kept as **source text** rather than a parsed template, because the
+        Node side owns every rule about what a path may look like and this file
+        owns none of them.
+        """
+        if not self.deep_calls or len(self._scope) == 0:
+            return
+        if not isinstance(target, ast.Name):
+            return
+        if not isinstance(value, (ast.Constant, ast.JoinedStr)):
+            return
+        if isinstance(value, ast.Constant) and not isinstance(value.value, str):
+            return
+        unparse = getattr(ast, "unparse", None)
+        if unparse is None:
+            # 3.8 and older. A disclosed gap: this reader simply records
+            # nothing, rather than reconstructing source badly.
+            return
+        self.local_strings.append(
+            {
+                "name": target.id,
+                "value": unparse(value),
+                "scope": list(self._scope),
+                "line": line,
+            }
+        )
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        if len(node.targets) == 1:
+            self._constant(node.targets[0], node.value, node.lineno)
+            self._local_string(node.targets[0], node.value, node.lineno)
+
+        # Every assignment whose right-hand side is a call, dotted callee
+        # included. `instantiations` below deliberately takes only a bare
+        # `Name` constructor, because it feeds receiver typing where a dotted
+        # name resolves to nothing useful — but `app = flask.Flask(__name__)`
+        # and `app = fastapi.FastAPI()` are the same declaration written the
+        # other legal way, and a reader that only sees the bare form misses
+        # them silently. Recorded separately rather than by widening
+        # `instantiations`, so no existing pass changes behaviour.
+        if (
+            isinstance(node.value, ast.Call)
+            and len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and len(self._scope) <= 1
+        ):
+            self.constructions.append(
+                {
+                    "local": node.targets[0].id,
+                    "callee": _annotation(node.value.func),
+                    "scope": list(self._scope),
+                    "line": node.lineno,
+                }
+            )
+
+        # The one inference: `service = OrderService()`. Recorded only where the
+        # right-hand side is a bare constructor call, because anything else
+        # needs a type checker and guessing is what precision-over-recall
+        # forbids.
+        if (
+            isinstance(node.value, ast.Call)
+            and isinstance(node.value.func, ast.Name)
+            and len(node.targets) == 1
+        ):
+            target = node.targets[0]
+            if isinstance(target, ast.Name):
+                self.instantiations.append(
+                    {
+                        "local": target.id,
+                        "typeName": node.value.func.id,
+                        "scope": list(self._scope),
+                        "line": node.lineno,
+                    }
+                )
+        # A module-level binding only. An indented assignment is a field or a
+        # local, and neither is importable, so neither can be an alias anything
+        # else refers to by name.
+        if not self._scope and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            self.alias_candidates.append(
+                {
+                    "name": node.targets[0].id,
+                    "range": _range(node),
+                    "annotation": None,
+                    "value": node.value,
+                    "pep695": False,
+                }
+            )
+        self.generic_visit(node)
+
+    def _with(self, node: ast.With | ast.AsyncWith) -> None:
+        """`with X() as name:` / `async with X() as name:` bind `name` to a
+        constructor call the same way `visit_Assign` binds an assignment
+        target — but a with-item is not an `Assign`, so without this the
+        binding was invisible to `constructions` entirely.
+
+        This is aiohttp's canonical idiom: `async with aiohttp.ClientSession()
+        as session:` never assigns `session`, and `requests`/`httpx` support
+        the identical shape (`with requests.Session() as s:`). Both left
+        `clientLocalsIn` (the Node side) with no local to resolve a later
+        `session.get(...)` receiver against — the call itself was already
+        walked and recorded via `generic_visit`, only the binding was missing.
+
+        Same depth rule as `visit_Assign`'s construction recording (`scope <=
+        1`), for the same reason: a match here has to be one function's own
+        client, not two functions' guesses merged into one local name.
+        """
+        if len(self._scope) <= 1:
+            for item in node.items:
+                value = item.context_expr
+                target = item.optional_vars
+                if isinstance(value, ast.Call) and isinstance(target, ast.Name):
+                    self.constructions.append(
+                        {
+                            "local": target.id,
+                            "callee": _annotation(value.func),
+                            "scope": list(self._scope),
+                            "line": value.lineno,
+                        }
+                    )
+        self.generic_visit(node)
+
+    visit_With = _with
+    visit_AsyncWith = _with
+
+    def visit_TypeAlias(self, node: ast.AST) -> None:
+        """PEP 695 `type X = …`, Python 3.12+. Unambiguous by construction."""
+        target = getattr(node, "name", None)
+        if isinstance(target, ast.Name):
+            self.alias_candidates.append(
+                {
+                    "name": target.id,
+                    "range": _range(node),
+                    "annotation": None,
+                    "value": getattr(node, "value", None),
+                    "pep695": True,
+                }
+            )
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        # Folded in here rather than given its own visitor: a second
+        # `visit_AnnAssign` on this class would silently override the first,
+        # and the one that lost would be whichever was defined earlier.
+        if node.value is not None:
+            self._constant(node.target, node.value, node.lineno)
+        if isinstance(node.target, ast.Name) and node.annotation is not None:
+            self.references.append(
+                {
+                    "kind": "annotation",
+                    "name": _annotation(node.annotation),
+                    "receiver": None,
+                    "scope": list(self._scope),
+                    "line": node.lineno,
+                }
+            )
+            if not self._scope and node.value is not None:
+                self.alias_candidates.append(
+                    {
+                        "name": node.target.id,
+                        "range": _range(node),
+                        "annotation": _annotation(node.annotation),
+                        "value": node.value,
+                        "pep695": False,
+                    }
+                )
+        self.generic_visit(node)
+
+    def _value_ref(self, node: ast.AST | None, form: str) -> None:
+        """Record a bare name loaded as a value. Anything else is ignored."""
+        if isinstance(node, ast.Name):
+            self.value_refs.append(
+                {"name": node.id, "form": form, "scope": list(self._scope), "line": node.lineno}
+            )
+        elif isinstance(node, (ast.Tuple, ast.List)):
+            # `except (A, B):` and `isinstance(x, (A, B))` — the tuple is the
+            # syntax, the elements are the dependency.
+            for element in node.elts:
+                self._value_ref(element, form)
+
+    def visit_Return(self, node: ast.Return) -> None:
+        self._value_ref(node.value, "return")
+        self.generic_visit(node)
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
+        # `except SeedError:` depends on the exception class as surely as a call
+        # does. It had no form of its own until the AST was walked to find out.
+        self._value_ref(node.type, "except")
+        self.generic_visit(node)
+
+    def visit_MatchClass(self, node: ast.AST) -> None:
+        # PEP 634 `case BillExtraction(vendor_data=data):`. The class is the whole
+        # of the pattern, and on the repository this was measured against it
+        # carries the entire extraction dispatch.
+        self._value_ref(getattr(node, "cls", None), "match")
+        self.generic_visit(node)
+
+    def visit_comprehension(self, node: ast.comprehension) -> None:
+        # `{stage.value for stage in Stage}` — iterating an enum class.
+        self._value_ref(node.iter, "iterate")
+        self.generic_visit(node)
+
+    def _collection(self, node: ast.AST) -> None:
+        for element in getattr(node, "elts", []):
+            self._value_ref(element, "collection")
+        for value in getattr(node, "values", []):
+            self._value_ref(value, "collection")
+        self.generic_visit(node)
+
+    visit_List = _collection
+    visit_Set = _collection
+    visit_Dict = _collection
+
+    def visit_For(self, node: ast.For) -> None:
+        self._value_ref(node.iter, "iterate")
+        self.generic_visit(node)
+
+    def _decorator_refs(self, node: ast.AST) -> None:
+        """`@no_translations` — a decorator names a real dependency.
+
+        Measured at zero for classes when DEC-072 drew its form list, and at 2
+        edges for functions on `django/core`. Small, and admitted for a reason
+        the count does not carry: a decorator *wraps* the declaration, so it is
+        one of the few dependencies that can change a function's behaviour
+        without appearing anywhere in its body. `@decorator(arg)` is a call and
+        its arguments are already collected by `visit_Call`; only the bare form
+        needs handling here.
+        """
+        for decorator in getattr(node, "decorator_list", []):
+            self._value_ref(decorator, "decorator")
+
+    def _reference(self, kind: str, name: str, receiver: str | None, line: int) -> None:
+        self.references.append(
+            {
+                "kind": kind,
+                "name": name,
+                "receiver": receiver,
+                "scope": list(self._scope),
+                "line": line,
+            }
+        )
+
+
+def _root_name(node: ast.AST) -> str | None:
+    """The name an expression is rooted at. `DocumentType.VENDOR_BILL` -> `DocumentType`."""
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def _constituents(value: ast.AST | None) -> list[str]:
+    """Type names an alias body mentions, minus the machinery that built it.
+
+    A constructor is not a constituent — `Callable[[Alpha], Beta]` depends on
+    `Alpha` and `Beta`, not on `Callable`, and an edge to the latter would point
+    outside the analysed set at something no change can break.
+    """
+    if value is None:
+        return []
+    found: list[str] = []
+    for node in ast.walk(value):
+        name = None
+        if isinstance(node, ast.Attribute):
+            name = _root_name(node)
+        elif isinstance(node, ast.Name):
+            name = node.id
+        if name is None or name in found:
+            continue
+        if name in TYPING_CONSTRUCTORS or name in DECLARING_CALLS or name in BUILTIN_TYPES:
+            continue
+        found.append(name)
+    return found
+
+
+def _env_reads(tree: ast.Module, imports: list[dict]) -> tuple[list[dict], int]:
+    """`attrs.envReads` (DEC-120, carried on `MODULE` per DEC-124).
+
+    DEC-121: a read asserts *requirement* only when the accessor itself fails
+    on absence — a subscript, which raises `KeyError`, or a config-accessor
+    call with no `default=` keyword, which raises. `os.environ.get`/
+    `os.getenv` both yield `None` and never fail; they are recorded as reads
+    but never as required, however the result is used afterwards — deciding
+    that needs dataflow this level does not have (DEC-121's own withdrawn
+    first rule).
+
+    Two accessor shapes read a variable through a `default=`-or-raise call:
+    `decouple.config`, imported directly, and Starlette's `Config` (also
+    FastAPI's, which re-exports it) — instantiated once as `config =
+    Config(".env")` and then called like a function. Both are recognised only
+    from a *verified* import, never from the bare name `config` —
+    "if the framework will tell you, never infer it" applies to an accessor's
+    identity as much as to a route's. `config = Config(".env")` was the case
+    that made this two shapes instead of one: dispatch reads five required
+    variables through it and none through `decouple`.
+
+    There is no scope tracking at this level, so a name used as a function
+    PARAMETER anywhere in the file is dropped from consideration entirely,
+    for every accessor shape — a local shadow calling itself is not this
+    file's real accessor, and ambiguous counts as incorrect (DEC-057).
+    """
+    decouple_names = {r["local"] for r in imports if r["module"] == "decouple" and r["name"] == "config"}
+    decouple_modules = {r["local"] for r in imports if r["module"] == "decouple" and r["name"] is None}
+    config_class_names = {
+        r["local"]
+        for r in imports
+        if r["module"] in ("starlette.config", "fastapi.datastructures") and r["name"] == "Config"
+    }
+
+    # `X = Config(".env")` — the ONE assignment shape that DEFINES an accessor
+    # rather than shadowing one, so it runs before the parameter-shadow guard
+    # below rather than being caught by it.
+    config_instances: set[str] = set()
+    for node in ast.walk(tree):
+        if not (isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name)):
+            continue
+        value = node.value
+        if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id in config_class_names:
+            config_instances.add(node.targets[0].id)
+
+    param_shadowed: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            for arg in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs):
+                param_shadowed.add(arg.arg)
+    decouple_names -= param_shadowed
+    decouple_modules -= param_shadowed
+    config_instances -= param_shadowed
+
+    reads: dict[str, dict] = {}
+    dynamic = 0
+
+    def add(name: str, required: bool, line: int) -> None:
+        existing = reads.get(name)
+        if existing is None:
+            reads[name] = {"name": name, "required": required, "line": line}
+        elif required and not existing["required"]:
+            existing["required"] = True
+
+    def is_os_environ(node: ast.AST) -> bool:
+        return (
+            isinstance(node, ast.Attribute)
+            and node.attr == "environ"
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "os"
+        )
+
+    def is_os_getenv(node: ast.AST) -> bool:
+        return (
+            isinstance(node, ast.Attribute)
+            and node.attr == "getenv"
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "os"
+        )
+
+    def is_environ_get(node: ast.AST) -> bool:
+        return isinstance(node, ast.Attribute) and node.attr == "get" and is_os_environ(node.value)
+
+    def string_key(node: ast.AST | None) -> str | None:
+        return node.value if isinstance(node, ast.Constant) and isinstance(node.value, str) else None
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Subscript) and is_os_environ(node.value):
+            # `os.environ["X"] = "…"` writes; only a read can raise on absence.
+            if not isinstance(node.ctx, ast.Load):
+                continue
+            key = string_key(node.slice)
+            if key is None:
+                dynamic += 1
+            else:
+                add(key, True, node.lineno)
+            continue
+
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+
+        if is_os_getenv(func) or is_environ_get(func):
+            key = string_key(node.args[0]) if node.args else None
+            if key is None:
+                dynamic += 1
+            else:
+                add(key, False, node.lineno)
+            continue
+
+        is_config_call = (
+            (isinstance(func, ast.Name) and (func.id in decouple_names or func.id in config_instances))
+            or (
+                isinstance(func, ast.Attribute)
+                and func.attr == "config"
+                and isinstance(func.value, ast.Name)
+                and func.value.id in decouple_modules
+            )
+        )
+        if is_config_call:
+            key = string_key(node.args[0]) if node.args else None
+            has_default = any(kw.arg == "default" for kw in node.keywords)
+            if key is None:
+                dynamic += 1
+            else:
+                add(key, not has_default, node.lineno)
+
+    return list(reads.values()), dynamic
+
+
+def _migration_ops(tree: ast.Module, imports: list[dict]) -> list[dict]:
+    """`attrs.migrationOps` (DEC-122, carried on `MODULE` per DEC-124).
+
+    Alembic-shaped: a call on a name VERIFIED as `from alembic import op`.
+    `section` comes from which top-level function enclosed the call —
+    Alembic's actual `def upgrade()`/`def downgrade()` split, the real
+    forward/reverse mechanism, not the comment-directive shape the SQL-format
+    half of this check matches (`migrations.ts`'s docstring is about a
+    DIFFERENT input). A call in neither is `unknown` and dropped downstream
+    by the check itself (DEC-122: unknown is not a synonym for forward).
+
+    Only the operations DEC-122 scoped in: `drop_table`, `drop_column`,
+    `rename_table`, and `alter_column(..., new_column_name=...)` — which is
+    a rename ONLY when that keyword is present; without it, `alter_column`
+    changes a type or nullability, not a name. `drop_index`/`drop_constraint`
+    are excluded on purpose — both recoverable, DEC-122's own scope fence.
+    No Alembic construct in this reference set guards a drop the way
+    `DROP … IF EXISTS` does in raw DDL, so `guarded` is always `False` here —
+    stated rather than silently defaulted, so a future guarded form is a
+    change to this line, not a silent gap.
+    """
+    op_names = {r["local"] for r in imports if r["module"] == "alembic" and r["name"] == "op"}
+
+    param_shadowed: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            for arg in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs):
+                param_shadowed.add(arg.arg)
+    op_names -= param_shadowed
+
+    def string_arg(node: ast.AST | None) -> str | None:
+        return node.value if isinstance(node, ast.Constant) and isinstance(node.value, str) else None
+
+    def section_of(function_name: str) -> str:
+        if function_name == "upgrade":
+            return "forward"
+        if function_name == "downgrade":
+            return "reverse"
+        return "unknown"
+
+    ops: list[dict] = []
+    for top in tree.body:
+        if not isinstance(top, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        section = section_of(top.name)
+
+        for node in ast.walk(top):
+            if not isinstance(node, ast.Call):
+                continue
+            func = node.func
+            if not (isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name) and func.value.id in op_names):
+                continue
+            method = func.attr
+            args = node.args
+            kwargs = {kw.arg: kw.value for kw in node.keywords if kw.arg is not None}
+
+            if method == "drop_table":
+                target = string_arg(args[0]) if args else None
+                if target is not None:
+                    ops.append({"kind": "DROP_TABLE", "target": target, "line": node.lineno, "section": section, "guarded": False})
+            elif method == "drop_column":
+                table = string_arg(args[0]) if len(args) > 0 else None
+                column = string_arg(args[1]) if len(args) > 1 else None
+                if table is not None and column is not None:
+                    ops.append(
+                        {"kind": "DROP_COLUMN", "target": f"{table}.{column}", "line": node.lineno, "section": section, "guarded": False}
+                    )
+            elif method == "rename_table":
+                old = string_arg(args[0]) if args else None
+                if old is not None:
+                    ops.append({"kind": "RENAME", "target": old, "line": node.lineno, "section": section, "guarded": False})
+            elif method == "alter_column" and "new_column_name" in kwargs:
+                table = string_arg(args[0]) if len(args) > 0 else None
+                column = string_arg(args[1]) if len(args) > 1 else None
+                if table is not None and column is not None:
+                    ops.append(
+                        {"kind": "RENAME", "target": f"{table}.{column}", "line": node.lineno, "section": section, "guarded": False}
+                    )
+
+    ops.extend(_django_migration_ops(tree, imports))
+    return ops
+
+
+#: Django's own destructive/rename operations — the four DEC-122 admits,
+#: named the way Django names them rather than the way Alembic does.
+#: `AlterField` is deliberately excluded: it changes a field's type or
+#: nullability, never its name, the same exclusion `alter_column` earns
+#: above when `new_column_name` is absent. `RemoveIndex`/`RemoveConstraint`
+#: are excluded for the same reason `drop_index`/`drop_constraint` are —
+#: both recoverable, DEC-122's own scope fence.
+_DJANGO_MIGRATION_CLASSES = ("DeleteModel", "RemoveField", "RenameModel", "RenameField")
+
+
+def _django_migration_op_callees(imports: list[dict]) -> dict[str, set[str]]:
+    """Every callee text, in THIS file, that names one of the four classes.
+
+    Two independent import shapes name the same class: `from django.db import
+    migrations` then `migrations.DeleteModel(...)`, or `from
+    django.db.migrations import DeleteModel` then `DeleteModel(...)` directly
+    — same asymmetry `_migration_ops`'s Alembic half does not have to handle,
+    because Alembic's `op` is always a namespace, never a class imported by
+    name.
+    """
+    migrations_locals = {
+        r["local"] for r in imports if r["module"] == "django.db" and r["name"] == "migrations"
+    }
+    callees: dict[str, set[str]] = {name: set() for name in _DJANGO_MIGRATION_CLASSES}
+    for local in migrations_locals:
+        for name in callees:
+            callees[name].add(f"{local}.{name}")
+    for record in imports:
+        if (
+            record["module"] in ("django.db.migrations", "django.db.migrations.operations")
+            and record["name"] in callees
+        ):
+            callees[record["name"]].add(record["local"])
+    return callees
+
+
+def _django_migration_ops(tree: ast.Module, imports: list[dict]) -> list[dict]:
+    """Django writes migrations as Python, not as `upgrade()`/`downgrade()`
+    calls on a namespace — a `class Migration(migrations.Migration):
+    operations = [DeleteModel(...), RemoveField(...), ...]`.
+
+    All `forward`: Django computes a migration's reverse from each
+    operation's own `database_backwards()` rather than from a second
+    written section, so there is no reverse text this reader could read
+    even in principle — `section: "unknown"` would be the wrong signal
+    (DEC-122: unknown is not a synonym for forward, but this is not an
+    unattributable call either, it is a call this format never writes a
+    reverse form of).
+    """
+
+    def string_arg(node: ast.AST | None) -> str | None:
+        return node.value if isinstance(node, ast.Constant) and isinstance(node.value, str) else None
+
+    callees = _django_migration_op_callees(imports)
+    if not any(callees.values()):
+        return []
+
+    ops: list[dict] = []
+    for node in ast.walk(tree):
+        if not (
+            isinstance(node, ast.Assign)
+            and len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and node.targets[0].id == "operations"
+            and isinstance(node.value, ast.List)
+        ):
+            continue
+
+        for element in node.value.elts:
+            if not isinstance(element, ast.Call):
+                continue
+            callee_text = _annotation(element.func)
+            if callee_text is None:
+                continue
+            kwargs = {kw.arg: kw.value for kw in element.keywords if kw.arg is not None}
+
+            def positional_or_kw(index: int, name: str) -> str | None:
+                if index < len(element.args):
+                    return string_arg(element.args[index])
+                return string_arg(kwargs.get(name))
+
+            if callee_text in callees["DeleteModel"]:
+                target = positional_or_kw(0, "name")
+                if target is not None:
+                    ops.append({"kind": "DROP_TABLE", "target": target, "line": element.lineno, "section": "forward", "guarded": False})
+            elif callee_text in callees["RemoveField"]:
+                model = positional_or_kw(0, "model_name")
+                field = positional_or_kw(1, "name")
+                if model is not None and field is not None:
+                    ops.append(
+                        {"kind": "DROP_COLUMN", "target": f"{model}.{field}", "line": element.lineno, "section": "forward", "guarded": False}
+                    )
+            elif callee_text in callees["RenameModel"]:
+                old = positional_or_kw(0, "old_name")
+                if old is not None:
+                    ops.append({"kind": "RENAME", "target": old, "line": element.lineno, "section": "forward", "guarded": False})
+            elif callee_text in callees["RenameField"]:
+                model = positional_or_kw(0, "model_name")
+                old = positional_or_kw(1, "old_name")
+                if model is not None and old is not None:
+                    ops.append(
+                        {"kind": "RENAME", "target": f"{model}.{old}", "line": element.lineno, "section": "forward", "guarded": False}
+                    )
+
+    return ops
+
+
+def _classify_alias(candidate: dict, typing_names: set[str], bound: set[str]) -> str | None:
+    """DEC-069's closed admission list, in order. Returns the rule, or None.
+
+    `bound` is every name resolvable in this file, used only by rule 6 to check
+    that a `|` union's operands are types rather than values.
+    """
+    value = candidate["value"]
+    if candidate["pep695"]:
+        return "2-pep695"
+    annotation = candidate["annotation"]
+    if annotation is not None and "TypeAlias" in re.findall(r"[A-Za-z_][A-Za-z0-9_]*", annotation):
+        return "1-explicit"
+    if value is None:
+        return None
+
+    if isinstance(value, ast.Call) and isinstance(value.func, ast.Name):
+        if value.func.id in DECLARING_CALLS:
+            return f"3-{value.func.id}"
+
+    if isinstance(value, ast.Subscript) and isinstance(value.value, ast.Name):
+        head = value.value.id
+        # The import check is the precision control. Matching the bare name
+        # would classify a local class called `Literal` as a type constructor.
+        if head in TYPING_CONSTRUCTORS and head in typing_names:
+            return f"4-{head}"
+        if head in BUILTIN_CONTAINERS:
+            return f"5-{head}"
+        return None
+
+    if isinstance(value, ast.BinOp) and isinstance(value.op, ast.BitOr):
+        operands: list[ast.AST] = []
+        stack = [value]
+        while stack:
+            current = stack.pop()
+            if isinstance(current, ast.BinOp) and isinstance(current.op, ast.BitOr):
+                stack.extend([current.left, current.right])
+            else:
+                operands.append(current)
+        for operand in operands:
+            if isinstance(operand, ast.Constant) and operand.value is None:
+                continue
+            if isinstance(operand, ast.Subscript):
+                head = _root_name(operand.value)
+                if head in BUILTIN_CONTAINERS or (head in TYPING_CONSTRUCTORS and head in typing_names):
+                    continue
+                return None
+            name = _root_name(operand)
+            if name is None:
+                return None
+            if name in BUILTIN_TYPES or name in typing_names or name in bound:
+                continue
+            return None
+        return "6-union"
+
+    # `X = SomeName` is deliberately rejected. It is often an alias and is
+    # indistinguishable from a constant holding a class object, and under
+    # precision over recall an indistinguishable case is omitted. TypeScript's
+    # `type Chain = Pair` has no such ambiguity because the keyword marks it —
+    # the divergence is between the two languages, not between the adapters.
+    return None
+
+
+def collect(path: str, source: str, deep_call_modules: frozenset[str] = frozenset()) -> dict:
+    tree = ast.parse(source, filename=path)
+    collector = Collector(path)
+    # Imports are only complete after the walk, and this decision has to be made
+    # before it — so the import statements are read first, in their own pass.
+    if deep_call_modules:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                names = [alias.name for alias in node.names]
+            elif isinstance(node, ast.ImportFrom):
+                names = [node.module or ""]
+            else:
+                continue
+            if any(name.split(".")[0] in deep_call_modules for name in names):
+                collector.deep_calls = True
+                break
+    for statement in tree.body:
+        collector.visit(statement)
+
+    # --- DEC-069: type aliases, classified now that imports are complete ------
+    typing_names = {
+        record["local"]
+        for record in collector.imports
+        if record["module"] in TYPING_MODULES and record["name"] is not None
+    }
+    declared_names = {
+        declaration["path"][0]
+        for declaration in collector.declarations
+        if len(declaration["path"]) == 1
+    }
+    bound = declared_names | {record["local"] for record in collector.imports}
+    aliases: list[dict] = []
+    claimed: set[str] = set(declared_names)
+    for candidate in collector.alias_candidates:
+        # A `def`/`class` of the same name owns it. Rebinding a declared name at
+        # module level is legal and rare, and the declaration is the better node.
+        if candidate["name"] in claimed:
+            continue
+        rule = _classify_alias(candidate, typing_names, bound)
+        if rule is None:
+            continue
+        claimed.add(candidate["name"])
+        aliases.append(
+            {
+                "name": candidate["name"],
+                "range": candidate["range"],
+                "rule": rule,
+                "constituents": _constituents(candidate["value"]),
+            }
+        )
+
+    env_reads, env_dynamic_reads = _env_reads(tree, collector.imports)
+    migration_ops = _migration_ops(tree, collector.imports)
+
+    return {
+        "declarations": collector.declarations,
+        "imports": collector.imports,
+        "references": collector.references,
+        "instantiations": collector.instantiations,
+        "valueRefs": collector.value_refs,
+        "aliases": aliases,
+        "calls": collector.calls,
+        "constructions": collector.constructions,
+        "constants": collector.constants,
+        "localStrings": collector.local_strings,
+        "envReads": env_reads,
+        "envDynamicReads": env_dynamic_reads,
+        "migrationOps": migration_ops,
+    }
+
+
+def main() -> int:
+    request = json.load(sys.stdin)
+    root = request["root"]
+    files: list[str] = request["files"]
+    # Which imports make a file worth walking to full depth. Supplied by the
+    # Node side rather than decided here: *that* a package is interesting is
+    # framework knowledge and belongs above this file; *how* to record a call is
+    # syntax and belongs in it.
+    deep_call_modules = frozenset(request.get("deepCallModules") or ())
+
+    parsed: dict[str, dict] = {}
+    errors: dict[str, str] = {}
+
+    for relative in files:
+        absolute = f"{root}/{relative}"
+        try:
+            with open(absolute, encoding="utf8") as handle:
+                source = handle.read()
+        except OSError as error:
+            errors[relative] = f"unreadable: {error.strerror or type(error).__name__}"
+            continue
+        try:
+            parsed[relative] = collect(relative, source, deep_call_modules)
+        except SyntaxError as error:
+            # Disclosed, never silent. This interpreter's grammar is the one in
+            # force, so a repository using newer syntax lands here too — which
+            # is a real limit of DEC-062 and belongs in the report.
+            errors[relative] = f"syntax error at line {error.lineno}: {error.msg}"
+        except (ValueError, RecursionError) as error:
+            errors[relative] = f"{type(error).__name__}: {error}"
+
+    # **Line-delimited, not one object.** A single `json.dump` of a large
+    # repository produced 284.4 MB for home-assistant-core, which overflowed the
+    # reader's buffer; the reader then reported a successful R0 run with an empty
+    # graph. Streaming a line per file removes the wall rather than moving it:
+    # neither side ever holds the whole payload as one string, and a truncated
+    # stream is detectable because the trailer is missing.
+    out = sys.stdout
+    out.write(
+        json.dumps(
+            {
+                "kind": "header",
+                "pythonVersion": ".".join(str(part) for part in sys.version_info[:3]),
+                "fileCount": len(files),
+            }
+        )
+    )
+    out.write("\n")
+    for relative, record in parsed.items():
+        out.write(json.dumps({"kind": "file", "file": relative, "parsed": record}))
+        out.write("\n")
+    for relative, message in errors.items():
+        out.write(json.dumps({"kind": "error", "file": relative, "error": message}))
+        out.write("\n")
+    # The trailer is the completeness proof. Without it the reader cannot tell a
+    # truncated stream from a short one, which is exactly the ambiguity that let
+    # an empty result be reported as a success.
+    out.write(json.dumps({"kind": "trailer", "files": len(parsed), "errors": len(errors)}))
+    out.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())