diffcone 0.1.0__py3-none-any.whl

diffcone/indexer/__init__.py

@@ -0,0 +1,48 @@
+"""Source index and dependency resolver.
+
+Parses every Python module of a snapshot, assigns stable symbol identities,
+hashes bodies and definitions, and resolves the statically resolvable subset
+of references into explicit dependency edges. Everything that cannot be
+resolved is recorded as an :class:`UnresolvedReference`, never dropped.
+
+Supported subset (see internal/design.md):
+
+* module-level functions, classes, methods (and nested classes) as symbols;
+* bare names and dotted attribute chains rooted at a module-level definition,
+  an import alias, ``self``/``cls`` inside a method, or a star import;
+* ``import``/``from ... import`` (absolute and relative) within source roots;
+* ``importlib.import_module`` / ``getattr`` with literal arguments (a
+  literal table's keys, values or elements included: ``D[k]``, ``D.values()``,
+  ``for k, v in D.items()``), with parameters whose call sites pass literals,
+  and with instance attributes that ``__init__`` binds to such values
+  (``getattr(x, self.name)``);
+* attribute lookup on classes through their in-scope MRO (``self.m`` for an
+  inherited ``m``, ``Sub.m``, ``super().m``).
+
+Deliberately unsupported: type inference, dynamic dispatch on unknown
+receivers, instance attributes written outside ``__init__`` or reflectively,
+decorators that rewrite call targets.
+"""
+
+from diffcone.indexer.core import Indexer, build_index
+from diffcone.indexer.scopes import resolve_relative_module
+from diffcone.indexer.syntax import (
+    DEF_NODES,
+    FUNC_NODES,
+    decode_source,
+    hash_nodes,
+    hash_scope_body,
+    iter_scope_statements,
+)
+
+__all__ = [
+    "DEF_NODES",
+    "FUNC_NODES",
+    "Indexer",
+    "build_index",
+    "decode_source",
+    "hash_nodes",
+    "hash_scope_body",
+    "iter_scope_statements",
+    "resolve_relative_module",
+]

diffcone/indexer/core.py

@@ -0,0 +1,286 @@
+"""The indexer: parses a snapshot's modules (pass 1, cacheable per module),
+then resolves references into edges (pass 2). The work is layered, each
+layer a subclass of the one below: state, symbols (pass 1), resolver
+(pass 2), dynamics (bounds after pass 2), and here the pipeline."""
+
+from __future__ import annotations
+
+import ast
+import json
+from collections import defaultdict
+
+from diffcone.indexer.dynamics import DynamicBounds
+from diffcone.indexer.facts import (
+    _facts_to_dict,
+    _Output,
+    _output_from_dict,
+    _output_to_dict,
+    _tuples,
+)
+from diffcone.indexer.literals import INDEXED
+from diffcone.indexer.scopes import ClassScope, ImportBinding, ModuleScope
+from diffcone.indexer.syntax import _digest, decode_source
+from diffcone.model import REFERENCES, Edge, SourceIndex, Symbol
+from diffcone.snapshot import Snapshot, child_modules, module_name_for
+
+
+class Indexer(DynamicBounds):
+    """Builds a SourceIndex from a snapshot: ``Indexer(snapshot).build()``."""
+
+    def build(self) -> SourceIndex:
+        cache = self.module_cache
+        facts: dict[str, dict | None] = {}
+        candidates = [
+            (path, module)
+            for path in sorted(self.snapshot.files)
+            if (module := module_name_for(path, self.snapshot.source_roots)) is not None
+        ]
+        # Submodule names per package: a top-level binding of that name gets
+        # a distinct identity (member_symbol_id).
+        self._children = child_modules(self.snapshot)
+        keys: dict[str, str] = {}  # path -> cache key; every record is loaded in one query
+        if cache is not None:
+            keys = {p: cache.key(m, p, self.snapshot.files[p]) for p, m in candidates}
+        loaded = cache.load_facts(list(keys.values())) if cache is not None else {}
+        for path, module in candidates:
+            if module in self.scopes:
+                other = self.scopes[module].path
+                self._error(path, f"module {module!r} is also defined by {other}")
+                continue
+            record = loaded.get(keys[path]) if path in keys else None
+            if record is None:
+                tree = self._parse(path, module)
+                if tree is None:
+                    continue
+            else:
+                tree = None
+            scope = ModuleScope(
+                name=module, path=path, is_package=path.endswith("__init__.py"), tree=tree
+            )
+            scope.cache_key = keys.get(path)
+            self.scopes[module] = scope
+            self.index.modules.add(module)
+            facts[module] = record
+        new_facts: dict[str, dict] = {}
+        new_resolved: dict[str, dict] = {}
+        for module in self.index.modules:
+            parts = module.split(".")
+            for i in range(1, len(parts) + 1):
+                self._module_prefixes.add(".".join(parts[:i]))
+        for module in sorted(self.scopes):
+            scope = self.scopes[module]
+            record = facts[module]
+            if record is not None:
+                # A record whose symbols collide with an earlier module's (an
+                # error either way) is not applied, so the errors come out
+                # exactly as without a cache; a malformed record is a miss.
+                try:
+                    applied = self._apply_facts(scope, record)
+                except (KeyError, TypeError, ValueError, AttributeError):
+                    applied = False
+                if applied:
+                    continue
+                scope.tree = self._parse(scope.path, module)
+                if scope.tree is None:  # pragma: no cover - same content parsed before
+                    del self.scopes[module]
+                    self.index.modules.discard(module)
+                    continue
+            self._added_symbols, self._added_classes, self._collided = [], [], False
+            self.out = _Output()
+            try:
+                self._index_module(scope)
+            finally:
+                captured, self.out = self.out, self._global
+            self._global.merge(captured)
+            if cache is not None:
+                record = _facts_to_dict(
+                    scope, self._added_symbols, self._added_classes, captured.edges
+                )
+                scope.env_digest = record["env"]
+                if not self._collided and scope.cache_key is not None:
+                    new_facts[scope.cache_key] = record
+        self._unbind_mutated_variables()
+        for class_id in sorted(self.class_scopes):
+            self._ensure_bases(class_id)
+        self._bases_final = True  # MROs may be memoised from here on
+        self._build_descendants()
+        self._external_callers()
+        fingerprint = self._environment_fingerprint() if cache is not None else ""
+        loaded = cache.load_resolved(list(keys.values()), fingerprint) if cache else {}
+        for module in sorted(self.scopes):
+            scope = self.scopes[module]
+            key = scope.cache_key
+            out: _Output | None = None
+            if key is not None and key in loaded:
+                try:
+                    out = _output_from_dict(loaded[key], self.scopes)
+                except (KeyError, TypeError, ValueError, AttributeError):
+                    out = None  # malformed record: resolve as on a miss
+            if out is None:
+                if scope.tree is None:
+                    self._load_tree(scope)
+                self.out = _Output()
+                try:
+                    self._resolve_module(scope)
+                finally:
+                    out, self.out = self.out, self._global
+                if key is not None:
+                    new_resolved[key] = _output_to_dict(out)
+            self._global.merge(out)
+        self._resolve_param_dynamics()
+        self._registrations()
+        # Classes whose instances (or the class itself) are handed to someone
+        # else: whoever holds one may read any attribute off it by a name
+        # nothing resolves, so holding it depends on its members.
+        returns = self._global.returns
+        self.index.escaped_classes = {
+            cls
+            for sites in self._global.call_sites.values()
+            for site in sites
+            for cls in [
+                *site.positional_classes,
+                *site.keyword_classes.values(),
+                # A factory's class counts as handed on too: every return of
+                # that function yields it, so that is what the callee holds.
+                *(c for f in site.positional_sources if f for c in returns.get(f, ())),
+                *(c for f in site.keyword_sources.values() if f for c in returns.get(f, ())),
+            ]
+            if cls is not None
+        }
+        if cache is not None and (new_facts or new_resolved):
+            cache.store(new_facts, new_resolved, fingerprint, list(keys.values()))
+        return self.index
+
+    def _registrations(self) -> None:
+        """Edges to code a decorator or a base class may keep and call later:
+        from the decorator's receiver (``show`` holds what
+        ``@show.register(int)`` registers, ``app`` what ``@app.command``
+        does), from each variable a decorator function writes into (the
+        ``REG`` a ``@register`` fills), and from a base class whose
+        ``__init_subclass__`` runs for its in-scope subclasses. Computed over
+        the whole index on every build, as the class model's other global
+        edges are."""
+        writers: dict[str, set[str]] = defaultdict(set)
+        for e in self.index.edges:
+            if e.detail == "mutated_by":
+                writers[e.target].add(e.source)
+        for decorated, decorator, receiver in sorted(self._global.decorations):
+            if receiver:
+                self.index.edges.add(Edge(receiver, decorated, REFERENCES, "registers"))
+            for variable in sorted(writers.get(decorator, ())):
+                self.index.edges.add(Edge(variable, decorated, REFERENCES, "registers"))
+        for cls, bases in sorted(self.index.class_bases.items()):
+            stack, seen = list(bases), set(bases)
+            while stack:
+                base = stack.pop()
+                if f"{base}.__init_subclass__" in self.index.symbols:
+                    self.index.edges.add(Edge(base, cls, REFERENCES, "registers"))
+                for up in self.index.class_bases.get(base, ()):
+                    if up not in seen:
+                        seen.add(up)
+                        stack.append(up)
+
+    def _parse(self, path: str, module: str) -> ast.Module | None:
+        try:
+            source = decode_source(self.snapshot.files[path])
+            return ast.parse(source, filename=path)
+        except (SyntaxError, UnicodeDecodeError, ValueError) as exc:
+            self._error(path, f"cannot parse: {exc}")
+            self.index.failed_modules.add(module)
+            return None
+
+    def _load_tree(self, scope: ModuleScope) -> None:
+        """Parse a module whose facts came from the cache but which must be
+        resolved again (its file or the environment changed)."""
+        tree = self._parse(scope.path, scope.name)
+        if tree is None:  # pragma: no cover - the same content parsed before
+            tree = ast.Module(body=[], type_ignores=[])
+        scope.tree = tree
+        _, _, variable_stmts = self._module_statements(scope, register_imports=False)
+        scope.variable_stmts = {n: s for n, s in variable_stmts.items() if n in scope.variables}
+
+    def _apply_facts(self, scope: ModuleScope, record: dict) -> bool:
+        """Install a cached facts record. Everything is built before anything
+        is stored, so a malformed record (which raises) or one whose symbols
+        collide with an earlier module's (returns False) leaves no trace."""
+        imports = {k: ImportBinding(m, a) for k, (m, a) in record["imports"].items()}
+        alt_imports = {
+            k: [ImportBinding(m, a) for m, a in v] for k, v in record["alt_imports"].items()
+        }
+        star_imports = list(record["star_imports"])
+        bindings = set(record["bindings"])
+        members = dict(record["members"])
+        variables = dict(record["variables"])
+        literal_names = {k: _tuples(v) for k, v in record["literal_names"].items()}
+        mutations = frozenset(record["mutations"])
+        env_digest = str(record["env"])
+        symbols: list[Symbol] = []
+        for data in record["symbols"]:
+            data = dict(data)
+            data["line_ranges"] = tuple(tuple(r) for r in data["line_ranges"])
+            data["imports"] = tuple(data["imports"])
+            data["import_layout"] = tuple(data["import_layout"])
+            symbols.append(Symbol(**data))
+        classes: dict[str, ClassScope] = {}
+        for data in record["classes"]:
+            enclosing = classes[data["enclosing"]] if data["enclosing"] else None
+            classes[data["id"]] = ClassScope(
+                id=str(data["id"]),
+                module=scope,
+                enclosing=enclosing,
+                members=dict(data["members"]),
+                bindings=set(data["bindings"]),
+                base_chains=[list(c) if c is not None else None for c in data["base_chains"]],
+                base_names=[list(c) if c is not None else None for c in data["base_names"]],
+                plain=bool(data["plain"]),
+            )
+        edges = {Edge(*e) for e in record["edges"]}
+        if any(s.id in self.index.symbols for s in symbols):
+            return False
+        # Top-level identities depend on which submodules exist: a record
+        # made before a shadowed submodule was added (or removed) is stale.
+        for name, symbol_id in [*members.items(), *variables.items()]:
+            if symbol_id != self._member_id(scope.name, name):
+                return False
+        scope.imports, scope.star_imports, scope.bindings = imports, star_imports, bindings
+        scope.alt_imports = alt_imports
+        scope.members, scope.variables, scope.literal_names = members, variables, literal_names
+        scope.mutations = mutations
+        scope.env_digest = env_digest
+        for symbol in symbols:
+            self._add_symbol(symbol)
+        self.class_scopes.update(classes)
+        self.out.edges |= edges
+        return True
+
+    def _unbind_mutated_variables(self) -> None:
+        """A module-level container that any module mutates in place is not
+        the literal it was assigned: unbind it everywhere (its own module and
+        the modules that import it), so names drawn from it stay dynamic."""
+        mutated: set[tuple[str, str]] = set()
+        for scope in self.scopes.values():
+            for name in scope.mutations:
+                if name in scope.variables:
+                    mutated.add((scope.name, name))
+                binding = scope.imports.get(name)
+                if binding is not None and binding.attr is not None:
+                    mutated.add((binding.module, binding.attr))
+        for module, name in mutated:
+            target = self.scopes.get(module)
+            if target is not None and name in target.literal_names:
+                target.literal_names[name] = target.literal_names[name + INDEXED] = None
+
+    def _environment_fingerprint(self) -> str:
+        """Digest of everything a module's resolution reads from other
+        modules: their observable facts plus every class's resolved bases,
+        and the root specs (whether ``__name__`` is a module's runtime name)."""
+        material = [
+            sorted(self.snapshot.source_roots),
+            [[m, self.scopes[m].env_digest] for m in sorted(self.scopes)],
+            [[c, cs.bases, cs.complete] for c, cs in sorted(self.class_scopes.items())],
+        ]
+        return _digest(json.dumps(material))
+
+
+def build_index(snapshot: Snapshot, module_cache=None) -> SourceIndex:
+    return Indexer(snapshot, module_cache=module_cache).build()

diffcone/indexer/definitions.py

@@ -0,0 +1,292 @@
+"""Facts about definitions the indexer hashes and classifies: line spans,
+decorators, class attributes, variable statements, inert definitions."""
+
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+
+from diffcone.indexer.literals import _collect_store_names
+from diffcone.indexer.scopes import ModuleScope, VariableStatement, _absolute_module
+from diffcone.indexer.syntax import DEF_NODES, _digest, iter_scope_statements
+from diffcone.model import CLASS_STATEMENT, OPAQUE_ATTRIBUTE
+
+
+def _canonical_imports(scope: ModuleScope) -> set[str]:
+    """One string per imported binding, independent of statement grouping or
+    order: adding a name to ``from m import (a, b)`` adds one entry."""
+    out: set[str] = set()
+    for node in scope.import_nodes:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                out.add(f"import {alias.name}" + (f" as {alias.asname}" if alias.asname else ""))
+        elif isinstance(node, ast.ImportFrom):
+            base = _absolute_module(scope, node.module, node.level)
+            for alias in node.names:
+                entry = f"from {base} import {alias.name}"
+                out.add(entry + (f" as {alias.asname}" if alias.asname else ""))
+    return out
+
+
+def _import_layout(scope: ModuleScope) -> tuple[str, ...]:
+    """Each module-level import binding, in source order, prefixed with the
+    blocks it sits in (``if <test>``, ``try``, ``except``, ``else``, ...):
+    what runs at import depends on where an import is, not only on which
+    names are bound."""
+    assert scope.tree is not None
+    out: list[str] = []
+
+    def walk(body: list[ast.stmt], context: str) -> None:
+        # Ordinary statements before an import in its block: an import moved
+        # across ``os.environ[...] = ...`` or ``sys.path.insert`` changes what
+        # it runs with. Counted, not hashed: editing them is a body change.
+        before = 0
+        for stmt in body:
+            if isinstance(stmt, DEF_NODES):
+                continue
+            if isinstance(stmt, (ast.Import, ast.ImportFrom)):
+                for entry in _import_entries(scope, stmt):
+                    out.append(f"{context}#{before}|{entry}")
+                continue
+            before += 1
+            label = type(stmt).__name__
+            if isinstance(stmt, (ast.If, ast.While)):
+                label += f"({ast.unparse(stmt.test)})"
+            elif isinstance(stmt, (ast.With, ast.AsyncWith)):
+                label += f"({', '.join(ast.unparse(i) for i in stmt.items)})"
+            elif isinstance(stmt, (ast.For, ast.AsyncFor)):
+                label += f"({ast.unparse(stmt.target)} in {ast.unparse(stmt.iter)})"
+            elif isinstance(stmt, ast.Match):
+                label += f"({ast.unparse(stmt.subject)})"
+            for attr in ("body", "orelse", "finalbody"):
+                child = getattr(stmt, attr, None)
+                if isinstance(child, list) and child:
+                    walk(child, f"{context}/{label}.{attr}")
+            for i, handler in enumerate(getattr(stmt, "handlers", []) or []):
+                walk(handler.body, f"{context}/{label}.except{i}")
+            for i, case in enumerate(getattr(stmt, "cases", []) or []):
+                walk(case.body, f"{context}/{label}.case{i}")
+
+    walk(scope.tree.body, "")
+    return tuple(out)
+
+
+def _import_entries(scope: ModuleScope, node: ast.Import | ast.ImportFrom) -> list[str]:
+    if isinstance(node, ast.Import):
+        return [f"import {a.name}" + (f" as {a.asname}" if a.asname else "") for a in node.names]
+    base = _absolute_module(scope, node.module, node.level)
+    return [
+        f"from {base} import {a.name}" + (f" as {a.asname}" if a.asname else "") for a in node.names
+    ]
+
+
+def _class_attributes(node: ast.ClassDef) -> dict[str, str]:
+    """Each name a class body binds by plain assignment, with a hash of the
+    statements binding it; every other non-definition statement (a loop, a
+    call, a ``del``, a conditional binding) is hashed under OPAQUE_ATTRIBUTE,
+    and the class statement itself (bases, keywords, decorators) under
+    CLASS_STATEMENT.
+    The docstring is not an attribute here: it has its own hash."""
+    parts: dict[str, list[str]] = defaultdict(list)
+    body = node.body
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+        if isinstance(body[0].value.value, str):
+            body = body[1:]
+    for stmt in body:
+        if isinstance(stmt, DEF_NODES):
+            continue
+        dumped = ast.dump(stmt)
+        names: list[str] = []
+        if isinstance(stmt, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+            targets = stmt.targets if isinstance(stmt, ast.Assign) else [stmt.target]
+            for target in targets:
+                elements = target.elts if isinstance(target, (ast.Tuple, ast.List)) else [target]
+                plain = [e.id for e in elements if isinstance(e, ast.Name)]
+                if len(plain) != len(elements):
+                    names = []
+                    break
+                names += plain
+        for name in names or [OPAQUE_ATTRIBUTE]:
+            parts[name].append(dumped)
+    parts[CLASS_STATEMENT] = [
+        ast.dump(n) for n in [*node.bases, *node.keywords, *node.decorator_list]
+    ]
+    return {name: _digest("\n".join(dumps)) for name, dumps in sorted(parts.items())}
+
+
+def _start_line(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> int:
+    """First line of a definition including its decorators, which belong to
+    the definition (they are part of its definition hash)."""
+    return min([node.lineno, *(d.lineno for d in node.decorator_list)])
+
+
+def _variable_statements(scope: ModuleScope, body: list[ast.stmt]) -> dict[str, VariableStatement]:
+    """Top-level ``NAME = <expr>`` / ``NAME: T = <expr>`` statements whose name
+    is bound exactly once in the module: candidates for variable symbols.
+    Names bound any other way too (in a loop, by unpacking, inside a block)
+    stay on the module symbol."""
+    assert scope.tree is not None
+    simple: dict[str, list[VariableStatement]] = defaultdict(list)
+    for stmt in body:
+        if isinstance(stmt, ast.Assign) and len(stmt.targets) == 1:
+            target = stmt.targets[0]
+        elif isinstance(stmt, ast.AnnAssign) and stmt.value is not None:
+            target = stmt.target
+        else:
+            continue
+        if isinstance(target, ast.Name):
+            simple[target.id].append(stmt)
+    simple_stmts = {id(s) for stmts in simple.values() for s in stmts}
+    other_bound: set[str] = set()
+    for stmt in iter_scope_statements(scope.tree.body):
+        if isinstance(stmt, DEF_NODES + (ast.Import, ast.ImportFrom)):
+            continue
+        if id(stmt) in simple_stmts:
+            continue
+        other_bound |= _collect_store_names(stmt)
+    return {
+        name: stmts[0]
+        for name, stmts in simple.items()
+        if len(stmts) == 1 and name not in other_bound and name not in scope.imports
+    }
+
+
+def _end_line(node: ast.stmt | ast.Module) -> int:
+    """Last source line of a definition; a Module has no position of its own."""
+    if isinstance(node, ast.Module):
+        return node.body[-1].end_lineno or 1 if node.body else 1
+    return node.end_lineno or node.lineno
+
+
+def _has_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef, name: str) -> bool:
+    for dec in node.decorator_list:
+        if isinstance(dec, ast.Name) and dec.id == name:
+            return True
+        if isinstance(dec, ast.Attribute) and dec.attr == name:
+            return True
+    return False
+
+
+# Bases outside the source roots that only add structure and never call
+# a subclass's methods.
+_STRUCTURAL_BASES = frozenset(
+    {
+        "abc.ABC",
+        "typing.Generic",
+        "typing.Protocol",
+        "typing.NamedTuple",
+        "typing.TypedDict",
+        "typing_extensions.Generic",
+        "typing_extensions.Protocol",
+        "typing_extensions.NamedTuple",
+        "typing_extensions.TypedDict",
+    }
+)
+
+
+# Reached explicitly: construction and class creation record their own edges.
+_EXPLICIT_SPECIAL_METHODS = frozenset({"__init__", "__new__", "__init_subclass__"})
+
+
+def _is_special_method(name: str) -> bool:
+    return (
+        len(name) > 4
+        and name.startswith("__")
+        and name.endswith("__")
+        and name not in _EXPLICIT_SPECIAL_METHODS
+    )
+
+
+def _annotated_args(args: ast.arguments) -> list[ast.arg]:
+    """The parameters that carry an annotation, in signature order."""
+    params = [*args.posonlyargs, *args.args, *args.kwonlyargs, args.vararg, args.kwarg]
+    return [a for a in params if a is not None and a.annotation is not None]
+
+
+# Decorators that run no code with the function beyond returning it (or
+# recording it in typing's overload registry), by canonical name.
+_INERT_DECORATORS = frozenset(
+    f"{module}.{name}"
+    for module in ("typing", "typing_extensions")
+    for name in ("overload", "override", "final")
+)
+
+
+def _is_inert_decorator(node: ast.expr, scope: ModuleScope) -> bool:
+    """Only the ``typing``/``typing_extensions`` decorators, resolved through
+    the module's imports: a project decorator named ``final`` may do anything."""
+    parts = _flatten_chain(node)
+    if parts is None:
+        return False
+    binding = scope.imports.get(parts[0])
+    if binding is None:
+        return False
+    base = binding.module if binding.attr is None else f"{binding.module}.{binding.attr}"
+    return ".".join([base, *parts[1:]]) in _INERT_DECORATORS
+
+
+def _is_literal(node: ast.expr) -> bool:
+    if isinstance(node, ast.Constant):
+        return True
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
+        return _is_literal(node.operand)
+    if isinstance(node, (ast.Tuple, ast.List, ast.Set)):
+        return all(_is_literal(e) for e in node.elts)
+    if isinstance(node, ast.Dict):
+        return all(k is not None and _is_literal(k) for k in node.keys) and all(
+            _is_literal(v) for v in node.values
+        )
+    return False
+
+
+def _inert_def(node: ast.FunctionDef | ast.AsyncFunctionDef, scope: ModuleScope) -> bool:
+    """Whether executing the ``def`` runs no code beyond binding the name:
+    inert decorators and literal defaults (annotations are checked apart)."""
+    defaults = [*node.args.defaults, *(d for d in node.args.kw_defaults if d is not None)]
+    return all(_is_inert_decorator(d, scope) for d in node.decorator_list) and all(
+        _is_literal(d) for d in defaults
+    )
+
+
+def _has_annotations(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return node.returns is not None or any(
+        isinstance(a, ast.arg) and a.annotation is not None for a in ast.walk(node.args)
+    )
+
+
+def _future_annotations(scope: ModuleScope) -> bool:
+    binding = scope.imports.get("annotations")
+    return binding is not None and binding.module == "__future__"
+
+
+def _is_staticmethod(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return _has_decorator(node, "staticmethod")
+
+
+# Defining one of these changes what ``self.<attr>`` reads or writes.
+_ATTRIBUTE_HOOKS = frozenset({"__setattr__", "__delattr__", "__getattr__", "__getattribute__"})
+
+
+def _rebound_names(node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    """Every name the function's body (nested scopes included, which only
+    over-approximates) binds, deletes or imports."""
+    names: set[str] = set()
+    for inner in ast.walk(node):
+        if isinstance(inner, ast.Name) and not isinstance(inner.ctx, ast.Load):
+            names.add(inner.id)
+        elif isinstance(inner, (ast.ExceptHandler, ast.MatchAs, ast.MatchStar)) and inner.name:
+            names.add(inner.name)
+        elif isinstance(inner, (ast.Import, ast.ImportFrom)):
+            names |= {(a.asname or a.name).split(".")[0] for a in inner.names}
+    return names
+
+
+def _flatten_chain(node: ast.expr) -> list[str] | None:
+    parts: list[str] = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+        return list(reversed(parts))
+    return None