stackthread 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev3__py3-none-any.whl

stackthread/lang/python/extract.py

@@ -1,494 +1,494 @@
-"""Facts from one Python file (design §7.2). Pure: text in, JSON-ready dict out. Never raises on bad code.
-
-The facts are deliberately framework-neutral. Decorators, module-level assignments and calls are recorded with
-their arguments summarised as values, and detectors interpret them later with the whole project in view.
-"""
-
-from __future__ import annotations
-
-import ast
-import copy
-import re
-from typing import Any
-
-Value = dict[str, Any]
-MAX_LIST = 300
-MAX_EXPR = 120
-
-
-def module_name(rel_path: str) -> tuple[str, bool]:
-    """`los/applications/engine.py` -> (`los.applications.engine`, False); `pkg/__init__.py` -> (`pkg`, True)."""
-    parts = rel_path.removesuffix(".py").split("/")
-    package = parts[-1] == "__init__"
-    if package:
-        parts = parts[:-1]
-    return ".".join(parts), package
-
-
-def _session_get(call: ast.Call) -> str | None:
-    """SQLAlchemy `session.get(Task, task_id)` returns a Task, so `task.done = True` is a write to Task."""
-    if not (isinstance(call.func, ast.Attribute) and call.func.attr in ("get", "get_one") and len(call.args) >= 2):
-        return None
-    name = dotted(call.args[0]) or ""
-    last = name.rsplit(".", 1)[-1]
-    return f"{name}()" if last[:1].isupper() and not last.isupper() else None
-
-
-def dotted(node: ast.AST | None) -> str | None:
-    """A readable callee path: `self.repo.get`, `Order.objects.filter().update`, `db[orders].find`, `super().save`."""
-    if node is None:
-        return None
-    if isinstance(node, ast.Name):
-        return node.id
-    if isinstance(node, ast.Attribute):
-        base = dotted(node.value)
-        return f"{base}.{node.attr}" if base else f"?.{node.attr}"
-    if isinstance(node, ast.Call):
-        base = dotted(node.func)
-        return f"{base}()" if base else None
-    if isinstance(node, ast.Subscript):
-        base = dotted(node.value)
-        if base is None:
-            return None
-        key = node.slice
-        if isinstance(key, ast.Constant) and isinstance(key.value, str):
-            return f"{base}[{key.value}]"
-        return f"{base}[]"
-    return None
-
-
-def value(node: ast.AST | None, depth: int = 0) -> Value | None:
-    """Summarise an expression for detectors: literals stay literals, names stay names, calls keep their arguments."""
-    if node is None:
-        return None
-    if depth > 4:
-        return {"t": "expr", "v": _short(node)}
-    if isinstance(node, ast.Constant):
-        if isinstance(node.value, str | int | float | bool) or node.value is None:
-            return {"t": "lit", "v": node.value}
-        return {"t": "expr", "v": _short(node)}
-    if isinstance(node, ast.Name | ast.Attribute):
-        name = dotted(node)
-        return {"t": "name", "v": name} if name else {"t": "expr", "v": _short(node)}
-    if isinstance(node, ast.Call):
-        return {
-            "t": "call",
-            "f": dotted(node.func) or _short(node.func),
-            "args": [value(a, depth + 1) for a in node.args[:8]],
-            "kw": {k.arg: value(k.value, depth + 1) for k in node.keywords if k.arg},
-            "line": node.lineno,
-        }
-    if isinstance(node, ast.List | ast.Tuple | ast.Set):
-        return {"t": "list", "v": [value(e, depth + 1) for e in node.elts[:MAX_LIST]]}
-    if isinstance(node, ast.Dict):
-        out: dict[str, Any] = {}
-        for k, v in zip(node.keys, node.values, strict=False):
-            if isinstance(k, ast.Constant) and isinstance(k.value, str):
-                out[k.value] = value(v, depth + 1)
-        return {"t": "dict", "v": out}
-    if isinstance(node, ast.JoinedStr):
-        parts = []
-        for part in node.values:
-            if isinstance(part, ast.Constant) and isinstance(part.value, str):
-                parts.append(part.value)
-            else:
-                parts.append("{}")
-        return {"t": "lit", "v": "".join(parts), "approx": True}
-    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
-        left, right = value(node.left, depth + 1), value(node.right, depth + 1)
-        if (
-            left
-            and right
-            and left["t"] == right["t"] == "lit"
-            and isinstance(left["v"], str)
-            and isinstance(right["v"], str)
-        ):
-            return {"t": "lit", "v": left["v"] + right["v"]}
-        return {"t": "concat", "v": [left, right]}
-    if isinstance(node, ast.Starred):
-        return {"t": "star", "v": value(node.value, depth + 1)}
-    if isinstance(node, ast.Lambda):
-        return {"t": "lambda"}
-    return {"t": "expr", "v": _short(node)}
-
-
-def _short(node: ast.AST) -> str:
-    try:
-        text = ast.unparse(node)
-    except Exception:  # unparse can fail on odd nodes; a placeholder is fine for display
-        return "…"
-    return text if len(text) <= MAX_EXPR else text[: MAX_EXPR - 1] + "…"
-
-
-def _names(node: ast.AST | None) -> list[str]:
-    """Dotted names referenced by an annotation: `Annotated[Session, Depends(get_db)]` -> Annotated, Session, ..."""
-    if node is None:
-        return []
-    out: list[str] = []
-    for sub in ast.walk(node):
-        if isinstance(sub, ast.Name | ast.Attribute):
-            name = dotted(sub)
-            if name and not name.startswith("?") and name not in out:
-                out.append(name)
-    return out
-
-
-def _doc(node: ast.AST) -> str:
-    try:
-        doc = ast.get_docstring(node)  # type: ignore[arg-type]
-    except TypeError:
-        return ""
-    return doc.strip().split("\n")[0][:200] if doc else ""
-
-
-class _Visitor(ast.NodeVisitor):
-    def __init__(self, module: str, package: bool) -> None:
-        self.module = module
-        self.package = package
-        self.imports: list[dict[str, Any]] = []
-        self.defs: list[dict[str, Any]] = []
-        self.top_calls: list[dict[str, Any]] = []
-        self.assigns: list[dict[str, Any]] = []
-        self.consts: dict[str, Any] = {}
-        self.stack: list[dict[str, Any]] = []
-
-    # ---- scope helpers ----
-
-    @property
-    def scope(self) -> dict[str, Any] | None:
-        return self.stack[-1] if self.stack else None
-
-    def _enclosing_class(self) -> dict[str, Any] | None:
-        return next((fact for fact in reversed(self.stack) if fact["kind"] == "class"), None)
-
-    def _qual(self, name: str) -> str:
-        return f"{self.stack[-1]['q']}.{name}" if self.stack else name
-
-    # ---- imports ----
-
-    def _absolute(self, module: str | None, level: int) -> str:
-        if level == 0:
-            return module or ""
-        parts = self.module.split(".") if self.module else []
-        keep = len(parts) - level + (1 if self.package else 0)
-        base = parts[: max(keep, 0)]
-        return ".".join([*base, module] if module else base)
-
-    def visit_Import(self, node: ast.Import) -> None:
-        for alias in node.names:
-            local = alias.asname or alias.name.split(".")[0]
-            target = alias.name if alias.asname else alias.name.split(".")[0]
-            self.imports.append(
-                {
-                    "local": local,
-                    "module": target,
-                    "name": None,
-                    "line": node.lineno,
-                    "full": alias.name,
-                    "lazy": bool(self.stack),
-                }
-            )
-
-    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
-        module = self._absolute(node.module, node.level)
-        for alias in node.names:
-            if alias.name == "*":
-                self.imports.append(
-                    {"local": "*", "module": module, "name": "*", "line": node.lineno, "lazy": bool(self.stack)}
-                )
-                continue
-            self.imports.append(
-                {
-                    "local": alias.asname or alias.name,
-                    "module": module,
-                    "name": alias.name,
-                    "line": node.lineno,
-                    "lazy": bool(self.stack),
-                }
-            )
-
-    # ---- definitions ----
-
-    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
-        cls = self.scope if self.scope and self.scope["kind"] == "class" else None
-        args = []
-        all_args = [*node.args.posonlyargs, *node.args.args]
-        defaults: list[ast.expr | None] = [None] * (len(all_args) - len(node.args.defaults)) + list(node.args.defaults)
-        pairs = list(zip(all_args, defaults, strict=False))
-        pairs += list(zip(node.args.kwonlyargs, node.args.kw_defaults, strict=False))
-        for arg, default in pairs:
-            args.append(
-                {
-                    "name": arg.arg,
-                    "ann": _names(arg.annotation),
-                    "default": value(default),
-                    "ann_value": value(arg.annotation) if arg.annotation is not None else None,
-                }
-            )
-        fact: dict[str, Any] = {
-            "q": self._qual(node.name),
-            "kind": "method" if cls else "function",
-            "name": node.name,
-            "line": node.lineno,
-            "end": node.end_lineno or node.lineno,
-            "col": node.col_offset + 1,
-            "parent": self.scope["q"] if self.scope else None,
-            "async": isinstance(node, ast.AsyncFunctionDef),
-            "doc": _doc(node),
-            "decorators": [self._decorator(d) for d in node.decorator_list],
-            "args": args,
-            "returns": _names(node.returns),
-            "calls": [],
-            "locals": {},
-        }
-        for arg in all_args + node.args.kwonlyargs:
-            if arg.annotation is not None:
-                ann = dotted(arg.annotation)
-                if ann:
-                    fact["locals"][arg.arg] = ann
-        self.defs.append(fact)
-        self.stack.append(fact)
-        for stmt in node.body:
-            self.visit(stmt)
-        self.stack.pop()
-
-    visit_FunctionDef = _function
-    visit_AsyncFunctionDef = _function
-
-    def visit_ClassDef(self, node: ast.ClassDef) -> None:
-        fact: dict[str, Any] = {
-            "q": self._qual(node.name),
-            "kind": "class",
-            "name": node.name,
-            "line": node.lineno,
-            "end": node.end_lineno or node.lineno,
-            "col": node.col_offset + 1,
-            "parent": self.scope["q"] if self.scope else None,
-            "doc": _doc(node),
-            "decorators": [self._decorator(d) for d in node.decorator_list],
-            "bases": [b for b in (dotted(x) for x in node.bases) if b],
-            "kw": {k.arg: value(k.value) for k in node.keywords if k.arg},
-            "attrs": {},
-            "self_attrs": {},
-            "calls": [],
-        }
-        self.defs.append(fact)
-        self.stack.append(fact)
-        for stmt in node.body:
-            self.visit(stmt)
-        self.stack.pop()
-
-    def _decorator(self, node: ast.expr) -> dict[str, Any]:
-        if isinstance(node, ast.Call):
-            return {
-                "f": dotted(node.func) or _short(node.func),
-                "args": [value(a) for a in node.args],
-                "kw": {k.arg: value(k.value) for k in node.keywords if k.arg},
-                "line": node.lineno,
-            }
-        return {"f": dotted(node) or _short(node), "args": [], "kw": {}, "line": node.lineno, "bare": True}
-
-    # ---- calls ----
-
-    def visit_Raise(self, node: ast.Raise) -> None:
-        if isinstance(node.exc, ast.Call):
-            self._raising = node.exc
-        self.generic_visit(node)
-        self._raising = None
-
-    _raising: ast.Call | None = None
-
-    def visit_Call(self, node: ast.Call) -> None:
-        spec: dict[str, Any] = {
-            "f": dotted(node.func) or "?",
-            "line": node.lineno,
-            "col": node.col_offset + 1,
-            "args": [value(a, 2) for a in node.args[:6]],
-            "kw": {k.arg: value(k.value, 2) for k in node.keywords if k.arg},
-        }
-        if node is self._raising:
-            spec["raise"] = True
-        if self.scope is None:
-            self.top_calls.append(spec)
-        else:
-            self.scope["calls"].append(spec)
-        self.generic_visit(node)
-
-    # ---- assignments ----
-
-    def _record_assign(
-        self, target: ast.expr, val: ast.expr | None, line: int, aug: bool = False, annotation: ast.expr | None = None
-    ) -> None:
-        scope = self.scope
-        if scope is None:
-            if isinstance(target, ast.Name):
-                summary = value(val) if val is not None else None
-                self.assigns.append({"name": target.id, "line": line, "value": summary, "aug": aug})
-                if summary and summary["t"] == "lit" and not aug:
-                    self.consts[target.id] = summary["v"]
-            return
-        if scope["kind"] == "class":
-            if isinstance(target, ast.Name):
-                scope["attrs"][target.id] = value(val) if val is not None else None
-                if annotation is not None and (ann := dotted(annotation)):
-                    scope["self_attrs"].setdefault(target.id, ann)
-                elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
-                    scope["self_attrs"].setdefault(target.id, f"{callee}()")
-            return
-        # inside a function
-        if isinstance(target, ast.Name):
-            hint = None
-            if annotation is not None:
-                hint = dotted(annotation)
-            elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
-                hint = _session_get(val) or f"{callee}()"
-            if hint:
-                scope["locals"][target.id] = hint
-        elif isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id != "self":
-            scope.setdefault("sets", []).append({"f": dotted(target), "line": line})
-        elif isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id == "self":
-            cls = self._enclosing_class()
-            if cls is None:
-                return
-            hint = None
-            if annotation is not None:
-                hint = dotted(annotation)
-            elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
-                hint = f"{callee}()"
-            if hint:
-                cls["self_attrs"].setdefault(target.attr, hint)
-
-    def visit_Assign(self, node: ast.Assign) -> None:
-        for target in node.targets:
-            self._record_assign(target, node.value, node.lineno)
-        self.visit(node.value)
-
-    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
-        self._record_assign(node.target, node.value, node.lineno, annotation=node.annotation)
-        if node.value is not None:
-            self.visit(node.value)
-
-    def visit_AugAssign(self, node: ast.AugAssign) -> None:
-        if isinstance(node.op, ast.Add):
-            self._record_assign(node.target, node.value, node.lineno, aug=True)
-        self.visit(node.value)
-
-    def visit_With(self, node: ast.With | ast.AsyncWith) -> None:
-        scope = self.scope
-        for item in node.items:
-            if (
-                scope is not None
-                and scope["kind"] != "class"
-                and isinstance(item.optional_vars, ast.Name)
-                and isinstance(item.context_expr, ast.Call)
-                and (callee := dotted(item.context_expr.func))
-            ):
-                scope["locals"][item.optional_vars.id] = f"{callee}()"
-        self.generic_visit(node)
-
-    visit_AsyncWith = visit_With
-
-    def visit_For(self, node: ast.For | ast.AsyncFor) -> None:
-        scope = self.scope
-        if (
-            scope is not None
-            and scope["kind"] != "class"
-            and isinstance(node.target, ast.Name)
-            and isinstance(node.iter, ast.Call)
-            and (callee := dotted(node.iter.func))
-        ):
-            scope["locals"][node.target.id] = f"{callee}()[]"
-        # `for r in (a, b, c): api.add_router("", r)` registers a, b and c. Unroll short loops over literal
-        # names so the calls in the body carry the real arguments.
-        if (
-            isinstance(node.target, ast.Name)
-            and isinstance(node.iter, ast.Tuple | ast.List)
-            and 0 < len(node.iter.elts) <= 50
-            and all(isinstance(e, ast.Name | ast.Attribute | ast.Constant) for e in node.iter.elts)
-        ):
-            for element in node.iter.elts:
-                for stmt in node.body:
-                    self.visit(_Substitute(node.target.id, element).visit(copy.deepcopy(stmt)))
-            for stmt in node.orelse:
-                self.visit(stmt)
-            return
-        self.generic_visit(node)
-
-    visit_AsyncFor = visit_For
-
-
-class _Substitute(ast.NodeTransformer):
-    """Replace loads of one name with an expression, keeping line numbers of the original statement."""
-
-    def __init__(self, name: str, replacement: ast.expr) -> None:
-        self.name = name
-        self.replacement = replacement
-
-    def visit_Name(self, node: ast.Name) -> ast.AST:
-        if node.id == self.name and isinstance(node.ctx, ast.Load):
-            return ast.copy_location(copy.deepcopy(self.replacement), node)
-        return node
-
-
-_BARE_EXCEPT_TUPLE = re.compile(r"^(\s*except\*?\s+)(?!\()([^:\n#]*,[^:\n#]*?)(\s*:)", re.MULTILINE)
-
-
-def _parse(text: str, file: str) -> ast.Module:
-    """Parse with the running interpreter. Code written for Python 3.14 may use `except A, B:` (PEP 758), which
-    older interpreters reject; that one construct is rewritten in place, keeping every line number."""
-    try:
-        return ast.parse(text, filename=file)
-    except SyntaxError as first:
-        if "parenthesized" not in str(first.msg):
-            raise
-
-        def wrap(m: re.Match[str]) -> str:
-            body = m.group(2)
-            if " as " in body:
-                return m.group(0)
-            return f"{m.group(1)[:-1]}({body}){m.group(3)}" if m.group(1).endswith(" ") else m.group(0)
-
-        rewritten = _BARE_EXCEPT_TUPLE.sub(wrap, text)
-        if rewritten == text:
-            raise
-        return ast.parse(rewritten, filename=file)
-
-
-def extract(text: str, rel_path: str, file: str) -> dict[str, Any]:
-    """Facts for one file. `rel_path` is relative to the source root (gives the module name); `file` is relative to
-    the project root (used in the model)."""
-    module, package = module_name(rel_path)
-    facts: dict[str, Any] = {
-        "lang": "python",
-        "file": file,
-        "module": module,
-        "package": package,
-        "lines": text.count("\n") + 1,
-        "doc": "",
-        "imports": [],
-        "defs": [],
-        "calls": [],
-        "assigns": [],
-        "consts": {},
-        "errors": [],
-    }
-    try:
-        tree = _parse(text, file)
-    except SyntaxError as e:
-        facts["errors"].append({"line": e.lineno or 0, "message": f"cannot parse: {e.msg}"})
-        return facts
-    except ValueError as e:  # null bytes and similar
-        facts["errors"].append({"line": 0, "message": f"cannot parse: {e}"})
-        return facts
-    visitor = _Visitor(module, package)
-    for stmt in tree.body:
-        visitor.visit(stmt)
-    facts.update(
-        doc=_doc(tree),
-        imports=visitor.imports,
-        defs=visitor.defs,
-        calls=visitor.top_calls,
-        assigns=visitor.assigns,
-        consts=visitor.consts,
-    )
-    return facts
+"""Facts from one Python file (design §7.2). Pure: text in, JSON-ready dict out. Never raises on bad code.
+
+The facts are deliberately framework-neutral. Decorators, module-level assignments and calls are recorded with
+their arguments summarised as values, and detectors interpret them later with the whole project in view.
+"""
+
+from __future__ import annotations
+
+import ast
+import copy
+import re
+from typing import Any
+
+Value = dict[str, Any]
+MAX_LIST = 300
+MAX_EXPR = 120
+
+
+def module_name(rel_path: str) -> tuple[str, bool]:
+    """`shop/orders/service.py` -> (`shop.orders.service`, False); `pkg/__init__.py` -> (`pkg`, True)."""
+    parts = rel_path.removesuffix(".py").split("/")
+    package = parts[-1] == "__init__"
+    if package:
+        parts = parts[:-1]
+    return ".".join(parts), package
+
+
+def _session_get(call: ast.Call) -> str | None:
+    """SQLAlchemy `session.get(Task, task_id)` returns a Task, so `task.done = True` is a write to Task."""
+    if not (isinstance(call.func, ast.Attribute) and call.func.attr in ("get", "get_one") and len(call.args) >= 2):
+        return None
+    name = dotted(call.args[0]) or ""
+    last = name.rsplit(".", 1)[-1]
+    return f"{name}()" if last[:1].isupper() and not last.isupper() else None
+
+
+def dotted(node: ast.AST | None) -> str | None:
+    """A readable callee path: `self.repo.get`, `Order.objects.filter().update`, `db[orders].find`, `super().save`."""
+    if node is None:
+        return None
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = dotted(node.value)
+        return f"{base}.{node.attr}" if base else f"?.{node.attr}"
+    if isinstance(node, ast.Call):
+        base = dotted(node.func)
+        return f"{base}()" if base else None
+    if isinstance(node, ast.Subscript):
+        base = dotted(node.value)
+        if base is None:
+            return None
+        key = node.slice
+        if isinstance(key, ast.Constant) and isinstance(key.value, str):
+            return f"{base}[{key.value}]"
+        return f"{base}[]"
+    return None
+
+
+def value(node: ast.AST | None, depth: int = 0) -> Value | None:
+    """Summarise an expression for detectors: literals stay literals, names stay names, calls keep their arguments."""
+    if node is None:
+        return None
+    if depth > 4:
+        return {"t": "expr", "v": _short(node)}
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, str | int | float | bool) or node.value is None:
+            return {"t": "lit", "v": node.value}
+        return {"t": "expr", "v": _short(node)}
+    if isinstance(node, ast.Name | ast.Attribute):
+        name = dotted(node)
+        return {"t": "name", "v": name} if name else {"t": "expr", "v": _short(node)}
+    if isinstance(node, ast.Call):
+        return {
+            "t": "call",
+            "f": dotted(node.func) or _short(node.func),
+            "args": [value(a, depth + 1) for a in node.args[:8]],
+            "kw": {k.arg: value(k.value, depth + 1) for k in node.keywords if k.arg},
+            "line": node.lineno,
+        }
+    if isinstance(node, ast.List | ast.Tuple | ast.Set):
+        return {"t": "list", "v": [value(e, depth + 1) for e in node.elts[:MAX_LIST]]}
+    if isinstance(node, ast.Dict):
+        out: dict[str, Any] = {}
+        for k, v in zip(node.keys, node.values, strict=False):
+            if isinstance(k, ast.Constant) and isinstance(k.value, str):
+                out[k.value] = value(v, depth + 1)
+        return {"t": "dict", "v": out}
+    if isinstance(node, ast.JoinedStr):
+        parts = []
+        for part in node.values:
+            if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                parts.append(part.value)
+            else:
+                parts.append("{}")
+        return {"t": "lit", "v": "".join(parts), "approx": True}
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        left, right = value(node.left, depth + 1), value(node.right, depth + 1)
+        if (
+            left
+            and right
+            and left["t"] == right["t"] == "lit"
+            and isinstance(left["v"], str)
+            and isinstance(right["v"], str)
+        ):
+            return {"t": "lit", "v": left["v"] + right["v"]}
+        return {"t": "concat", "v": [left, right]}
+    if isinstance(node, ast.Starred):
+        return {"t": "star", "v": value(node.value, depth + 1)}
+    if isinstance(node, ast.Lambda):
+        return {"t": "lambda"}
+    return {"t": "expr", "v": _short(node)}
+
+
+def _short(node: ast.AST) -> str:
+    try:
+        text = ast.unparse(node)
+    except Exception:  # unparse can fail on odd nodes; a placeholder is fine for display
+        return "…"
+    return text if len(text) <= MAX_EXPR else text[: MAX_EXPR - 1] + "…"
+
+
+def _names(node: ast.AST | None) -> list[str]:
+    """Dotted names referenced by an annotation: `Annotated[Session, Depends(get_db)]` -> Annotated, Session, ..."""
+    if node is None:
+        return []
+    out: list[str] = []
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Name | ast.Attribute):
+            name = dotted(sub)
+            if name and not name.startswith("?") and name not in out:
+                out.append(name)
+    return out
+
+
+def _doc(node: ast.AST) -> str:
+    try:
+        doc = ast.get_docstring(node)  # type: ignore[arg-type]
+    except TypeError:
+        return ""
+    return doc.strip().split("\n")[0][:200] if doc else ""
+
+
+class _Visitor(ast.NodeVisitor):
+    def __init__(self, module: str, package: bool) -> None:
+        self.module = module
+        self.package = package
+        self.imports: list[dict[str, Any]] = []
+        self.defs: list[dict[str, Any]] = []
+        self.top_calls: list[dict[str, Any]] = []
+        self.assigns: list[dict[str, Any]] = []
+        self.consts: dict[str, Any] = {}
+        self.stack: list[dict[str, Any]] = []
+
+    # ---- scope helpers ----
+
+    @property
+    def scope(self) -> dict[str, Any] | None:
+        return self.stack[-1] if self.stack else None
+
+    def _enclosing_class(self) -> dict[str, Any] | None:
+        return next((fact for fact in reversed(self.stack) if fact["kind"] == "class"), None)
+
+    def _qual(self, name: str) -> str:
+        return f"{self.stack[-1]['q']}.{name}" if self.stack else name
+
+    # ---- imports ----
+
+    def _absolute(self, module: str | None, level: int) -> str:
+        if level == 0:
+            return module or ""
+        parts = self.module.split(".") if self.module else []
+        keep = len(parts) - level + (1 if self.package else 0)
+        base = parts[: max(keep, 0)]
+        return ".".join([*base, module] if module else base)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            local = alias.asname or alias.name.split(".")[0]
+            target = alias.name if alias.asname else alias.name.split(".")[0]
+            self.imports.append(
+                {
+                    "local": local,
+                    "module": target,
+                    "name": None,
+                    "line": node.lineno,
+                    "full": alias.name,
+                    "lazy": bool(self.stack),
+                }
+            )
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        module = self._absolute(node.module, node.level)
+        for alias in node.names:
+            if alias.name == "*":
+                self.imports.append(
+                    {"local": "*", "module": module, "name": "*", "line": node.lineno, "lazy": bool(self.stack)}
+                )
+                continue
+            self.imports.append(
+                {
+                    "local": alias.asname or alias.name,
+                    "module": module,
+                    "name": alias.name,
+                    "line": node.lineno,
+                    "lazy": bool(self.stack),
+                }
+            )
+
+    # ---- definitions ----
+
+    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        cls = self.scope if self.scope and self.scope["kind"] == "class" else None
+        args = []
+        all_args = [*node.args.posonlyargs, *node.args.args]
+        defaults: list[ast.expr | None] = [None] * (len(all_args) - len(node.args.defaults)) + list(node.args.defaults)
+        pairs = list(zip(all_args, defaults, strict=False))
+        pairs += list(zip(node.args.kwonlyargs, node.args.kw_defaults, strict=False))
+        for arg, default in pairs:
+            args.append(
+                {
+                    "name": arg.arg,
+                    "ann": _names(arg.annotation),
+                    "default": value(default),
+                    "ann_value": value(arg.annotation) if arg.annotation is not None else None,
+                }
+            )
+        fact: dict[str, Any] = {
+            "q": self._qual(node.name),
+            "kind": "method" if cls else "function",
+            "name": node.name,
+            "line": node.lineno,
+            "end": node.end_lineno or node.lineno,
+            "col": node.col_offset + 1,
+            "parent": self.scope["q"] if self.scope else None,
+            "async": isinstance(node, ast.AsyncFunctionDef),
+            "doc": _doc(node),
+            "decorators": [self._decorator(d) for d in node.decorator_list],
+            "args": args,
+            "returns": _names(node.returns),
+            "calls": [],
+            "locals": {},
+        }
+        for arg in all_args + node.args.kwonlyargs:
+            if arg.annotation is not None:
+                ann = dotted(arg.annotation)
+                if ann:
+                    fact["locals"][arg.arg] = ann
+        self.defs.append(fact)
+        self.stack.append(fact)
+        for stmt in node.body:
+            self.visit(stmt)
+        self.stack.pop()
+
+    visit_FunctionDef = _function
+    visit_AsyncFunctionDef = _function
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        fact: dict[str, Any] = {
+            "q": self._qual(node.name),
+            "kind": "class",
+            "name": node.name,
+            "line": node.lineno,
+            "end": node.end_lineno or node.lineno,
+            "col": node.col_offset + 1,
+            "parent": self.scope["q"] if self.scope else None,
+            "doc": _doc(node),
+            "decorators": [self._decorator(d) for d in node.decorator_list],
+            "bases": [b for b in (dotted(x) for x in node.bases) if b],
+            "kw": {k.arg: value(k.value) for k in node.keywords if k.arg},
+            "attrs": {},
+            "self_attrs": {},
+            "calls": [],
+        }
+        self.defs.append(fact)
+        self.stack.append(fact)
+        for stmt in node.body:
+            self.visit(stmt)
+        self.stack.pop()
+
+    def _decorator(self, node: ast.expr) -> dict[str, Any]:
+        if isinstance(node, ast.Call):
+            return {
+                "f": dotted(node.func) or _short(node.func),
+                "args": [value(a) for a in node.args],
+                "kw": {k.arg: value(k.value) for k in node.keywords if k.arg},
+                "line": node.lineno,
+            }
+        return {"f": dotted(node) or _short(node), "args": [], "kw": {}, "line": node.lineno, "bare": True}
+
+    # ---- calls ----
+
+    def visit_Raise(self, node: ast.Raise) -> None:
+        if isinstance(node.exc, ast.Call):
+            self._raising = node.exc
+        self.generic_visit(node)
+        self._raising = None
+
+    _raising: ast.Call | None = None
+
+    def visit_Call(self, node: ast.Call) -> None:
+        spec: dict[str, Any] = {
+            "f": dotted(node.func) or "?",
+            "line": node.lineno,
+            "col": node.col_offset + 1,
+            "args": [value(a, 2) for a in node.args[:6]],
+            "kw": {k.arg: value(k.value, 2) for k in node.keywords if k.arg},
+        }
+        if node is self._raising:
+            spec["raise"] = True
+        if self.scope is None:
+            self.top_calls.append(spec)
+        else:
+            self.scope["calls"].append(spec)
+        self.generic_visit(node)
+
+    # ---- assignments ----
+
+    def _record_assign(
+        self, target: ast.expr, val: ast.expr | None, line: int, aug: bool = False, annotation: ast.expr | None = None
+    ) -> None:
+        scope = self.scope
+        if scope is None:
+            if isinstance(target, ast.Name):
+                summary = value(val) if val is not None else None
+                self.assigns.append({"name": target.id, "line": line, "value": summary, "aug": aug})
+                if summary and summary["t"] == "lit" and not aug:
+                    self.consts[target.id] = summary["v"]
+            return
+        if scope["kind"] == "class":
+            if isinstance(target, ast.Name):
+                scope["attrs"][target.id] = value(val) if val is not None else None
+                if annotation is not None and (ann := dotted(annotation)):
+                    scope["self_attrs"].setdefault(target.id, ann)
+                elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
+                    scope["self_attrs"].setdefault(target.id, f"{callee}()")
+            return
+        # inside a function
+        if isinstance(target, ast.Name):
+            hint = None
+            if annotation is not None:
+                hint = dotted(annotation)
+            elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
+                hint = _session_get(val) or f"{callee}()"
+            if hint:
+                scope["locals"][target.id] = hint
+        elif isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id != "self":
+            scope.setdefault("sets", []).append({"f": dotted(target), "line": line})
+        elif isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id == "self":
+            cls = self._enclosing_class()
+            if cls is None:
+                return
+            hint = None
+            if annotation is not None:
+                hint = dotted(annotation)
+            elif isinstance(val, ast.Call) and (callee := dotted(val.func)):
+                hint = f"{callee}()"
+            if hint:
+                cls["self_attrs"].setdefault(target.attr, hint)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        for target in node.targets:
+            self._record_assign(target, node.value, node.lineno)
+        self.visit(node.value)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        self._record_assign(node.target, node.value, node.lineno, annotation=node.annotation)
+        if node.value is not None:
+            self.visit(node.value)
+
+    def visit_AugAssign(self, node: ast.AugAssign) -> None:
+        if isinstance(node.op, ast.Add):
+            self._record_assign(node.target, node.value, node.lineno, aug=True)
+        self.visit(node.value)
+
+    def visit_With(self, node: ast.With | ast.AsyncWith) -> None:
+        scope = self.scope
+        for item in node.items:
+            if (
+                scope is not None
+                and scope["kind"] != "class"
+                and isinstance(item.optional_vars, ast.Name)
+                and isinstance(item.context_expr, ast.Call)
+                and (callee := dotted(item.context_expr.func))
+            ):
+                scope["locals"][item.optional_vars.id] = f"{callee}()"
+        self.generic_visit(node)
+
+    visit_AsyncWith = visit_With
+
+    def visit_For(self, node: ast.For | ast.AsyncFor) -> None:
+        scope = self.scope
+        if (
+            scope is not None
+            and scope["kind"] != "class"
+            and isinstance(node.target, ast.Name)
+            and isinstance(node.iter, ast.Call)
+            and (callee := dotted(node.iter.func))
+        ):
+            scope["locals"][node.target.id] = f"{callee}()[]"
+        # `for r in (a, b, c): api.add_router("", r)` registers a, b and c. Unroll short loops over literal
+        # names so the calls in the body carry the real arguments.
+        if (
+            isinstance(node.target, ast.Name)
+            and isinstance(node.iter, ast.Tuple | ast.List)
+            and 0 < len(node.iter.elts) <= 50
+            and all(isinstance(e, ast.Name | ast.Attribute | ast.Constant) for e in node.iter.elts)
+        ):
+            for element in node.iter.elts:
+                for stmt in node.body:
+                    self.visit(_Substitute(node.target.id, element).visit(copy.deepcopy(stmt)))
+            for stmt in node.orelse:
+                self.visit(stmt)
+            return
+        self.generic_visit(node)
+
+    visit_AsyncFor = visit_For
+
+
+class _Substitute(ast.NodeTransformer):
+    """Replace loads of one name with an expression, keeping line numbers of the original statement."""
+
+    def __init__(self, name: str, replacement: ast.expr) -> None:
+        self.name = name
+        self.replacement = replacement
+
+    def visit_Name(self, node: ast.Name) -> ast.AST:
+        if node.id == self.name and isinstance(node.ctx, ast.Load):
+            return ast.copy_location(copy.deepcopy(self.replacement), node)
+        return node
+
+
+_BARE_EXCEPT_TUPLE = re.compile(r"^(\s*except\*?\s+)(?!\()([^:\n#]*,[^:\n#]*?)(\s*:)", re.MULTILINE)
+
+
+def _parse(text: str, file: str) -> ast.Module:
+    """Parse with the running interpreter. Code written for Python 3.14 may use `except A, B:` (PEP 758), which
+    older interpreters reject; that one construct is rewritten in place, keeping every line number."""
+    try:
+        return ast.parse(text, filename=file)
+    except SyntaxError as first:
+        if "parenthesized" not in str(first.msg):
+            raise
+
+        def wrap(m: re.Match[str]) -> str:
+            body = m.group(2)
+            if " as " in body:
+                return m.group(0)
+            return f"{m.group(1)[:-1]}({body}){m.group(3)}" if m.group(1).endswith(" ") else m.group(0)
+
+        rewritten = _BARE_EXCEPT_TUPLE.sub(wrap, text)
+        if rewritten == text:
+            raise
+        return ast.parse(rewritten, filename=file)
+
+
+def extract(text: str, rel_path: str, file: str) -> dict[str, Any]:
+    """Facts for one file. `rel_path` is relative to the source root (gives the module name); `file` is relative to
+    the project root (used in the model)."""
+    module, package = module_name(rel_path)
+    facts: dict[str, Any] = {
+        "lang": "python",
+        "file": file,
+        "module": module,
+        "package": package,
+        "lines": text.count("\n") + 1,
+        "doc": "",
+        "imports": [],
+        "defs": [],
+        "calls": [],
+        "assigns": [],
+        "consts": {},
+        "errors": [],
+    }
+    try:
+        tree = _parse(text, file)
+    except SyntaxError as e:
+        facts["errors"].append({"line": e.lineno or 0, "message": f"cannot parse: {e.msg}"})
+        return facts
+    except ValueError as e:  # null bytes and similar
+        facts["errors"].append({"line": 0, "message": f"cannot parse: {e}"})
+        return facts
+    visitor = _Visitor(module, package)
+    for stmt in tree.body:
+        visitor.visit(stmt)
+    facts.update(
+        doc=_doc(tree),
+        imports=visitor.imports,
+        defs=visitor.defs,
+        calls=visitor.top_calls,
+        assigns=visitor.assigns,
+        consts=visitor.consts,
+    )
+    return facts