stackthread 0.1.0.dev2__py3-none-any.whl

stackthread/lineage.py

@@ -0,0 +1,965 @@
+"""Lineage: from a clicked element, or any code location, to every definition it reaches (design §10).
+
+A selection arrives from the browser:
+
+    {"url": "/orders/7",
+     "target": {"loc": "web/src/Order.tsx:41:9", "tag": "button", "text": "Pay"},
+     "chain": [{"loc": ..., "tag": ...}, ...],          # stamped DOM ancestors, nearest first, target included
+     "owners": [{"name": "OrderPage", "loc": "web/src/routes.tsx:12:20"}, ...],   # components, nearest first
+     "attrs": [{"name": "data-param", "value": "x", "loc": ...}]}
+
+The answer is a list of layers (screen, client, network, server, data, plus concept and adapter layers), each a
+list of rows. Every row names a real definition with file and line, or says plainly that it is outside the code.
+
+Rows carry a role. `action` rows are what the element does when used: its event handlers and everything they call,
+followed deeply to the database. `reads` rows are the data it shows or an action reads (state, props, conditions,
+the requests that load them), followed shallowly so they inform without drowning the action.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from stackthread.model import CONFIDENCE_RANK, Graph, Node
+
+if TYPE_CHECKING:
+    from stackthread.lang.js.build import JsBuild
+    from stackthread.project import Project, Snapshot
+
+DEPTH = {"action": 4, "reads": 2}
+SERVER_DEPTH = {"action": 6, "reads": 1}
+SERVER_ROWS = {"action": 60, "reads": 8}
+MAX_MENTIONS = 40
+SKIP_ATTRS = frozenset({"key", "className", "class", "style", "id", "htmlFor", "role", "type", "ref", "tabIndex"})
+
+LAYER_TITLES = {
+    "screen": ("On screen", "what drew the thing you clicked"),
+    "client": ("In the browser", "handlers, state, props and helpers"),
+    "network": ("Over the wire", "requests"),
+    "server": ("On the server", "endpoint, then the functions it calls"),
+    "data": ("Data", "models and stores read or written"),
+}
+BINDING_WORDS = {
+    "prop": "prop",
+    "state": "state",
+    "setter": "state setter",
+    "memo": "computed value",
+    "callback": "callback",
+    "function": "local function",
+    "hook": "hook result",
+    "ref": "ref",
+    "context": "context value",
+    "reducer": "reducer state",
+    "local": "local value",
+    "param": "parameter",
+    "lazy": "lazy component",
+}
+
+
+@dataclass
+class Row:
+    label: str
+    kind: str
+    reason: str = ""
+    file: str = ""
+    line: int = 0
+    end: int = 0
+    node: str = ""
+    confidence: str = "exact"
+    depth: int = 0
+    external: bool = False
+    loc: str = ""  # a stamp location the UI can highlight in the page
+    role: str = ""  # action | reads
+
+    def to_json(self) -> dict[str, Any]:
+        data = {
+            "label": self.label,
+            "kind": self.kind,
+            "reason": self.reason,
+            "file": self.file,
+            "line": self.line,
+            "end": self.end,
+            "node": self.node,
+            "confidence": self.confidence,
+            "depth": self.depth,
+            "external": self.external,
+            "loc": self.loc,
+            "role": self.role,
+        }
+        return {k: v for k, v in data.items() if v not in ("", 0, False) or k in ("label", "kind")}
+
+
+@dataclass
+class Layer:
+    id: str
+    title: str
+    note: str
+    rows: list[Row] = field(default_factory=list)
+    _seen: set[str] = field(default_factory=set)
+
+    def add(self, row: Row) -> bool:
+        key = row.node or f"{row.kind}:{row.file}:{row.line}:{row.label}"
+        if key in self._seen:
+            return False
+        self._seen.add(key)
+        self.rows.append(row)
+        return True
+
+    def ordered(self) -> list[Row]:
+        """Action rows first, keeping the order they were found in; the rest after."""
+        return [r for r in self.rows if r.role != "reads"] + [r for r in self.rows if r.role == "reads"]
+
+    def to_json(self) -> dict[str, Any]:
+        return {"id": self.id, "title": self.title, "note": self.note, "rows": [r.to_json() for r in self.ordered()]}
+
+
+@dataclass(frozen=True)
+class Seed:
+    name: str  # a reference (`cell.can_act`) or a callee (`calls.save`)
+    how: str
+    kind: str  # ref | call
+    role: str  # action | reads
+
+
+def _loc(loc: str) -> tuple[str, int, int]:
+    m = re.match(r"^(.*?):(\d+)(?::(\d+))?$", loc or "")
+    if not m:
+        return loc or "", 0, 0
+    return m.group(1), int(m.group(2)), int(m.group(3) or 0)
+
+
+def _fn_label(node: Node) -> str:
+    if node.kind in ("component", "function", "method", "hook"):
+        return f"{node.qualname or node.name}()" if node.lang == "js" else f"{node.name}()"
+    return node.name
+
+
+def page_for(graph: Graph, url: str) -> Node | None:
+    """The page whose route pattern matches a URL path, preferring the most literal match."""
+    path = (url or "/").split("?")[0].split("#")[0].rstrip("/") or "/"
+    parts = [p for p in path.split("/") if p]
+    best: tuple[int, Node] | None = None
+    for page in graph.of_kind("page"):
+        pattern = [p for p in page.attrs.get("path", "").split("/") if p]
+        compare = parts
+        if pattern and pattern[-1] in ("*", "$"):
+            pattern = pattern[:-1]
+            if len(parts) < len(pattern):
+                continue
+            compare = parts[: len(pattern)]
+        elif len(pattern) != len(parts):
+            continue
+        score, ok = 0, True
+        for want, got in zip(pattern, compare, strict=True):
+            if want == got:
+                score += 2
+            elif want.startswith((":", "$", "{")):
+                score += 1
+            else:
+                ok = False
+                break
+        if ok and (best is None or score > best[0]):
+            best = (score, page)
+    return best[1] if best else None
+
+
+class Lineage:
+    def __init__(self, project: Project, snapshot: Snapshot) -> None:
+        self.project = project
+        self.s = snapshot
+        self.g = snapshot.graph
+        self.layers = {k: Layer(k, *LAYER_TITLES[k]) for k in LAYER_TITLES}
+        self.extra: list[Layer] = []
+        self.reached: dict[str, str] = {}  # frontend function node -> role it was reached in
+        self.server_nodes: dict[str, str] = {}  # backend node -> role
+        self.strings: list[str] = []
+
+    def _result(self, header: dict[str, Any], started: float) -> dict[str, Any]:
+        layers = [layer.to_json() for layer in [*self.layers.values(), *self.extra] if layer.rows]
+        return {
+            "target": header,
+            "layers": layers,
+            "rev": self.s.rev,
+            "ms": round((time.perf_counter() - started) * 1000, 1),
+        }
+
+    # ------------------------------------------------------------------ entry points
+
+    def selection(self, sel: dict[str, Any]) -> dict[str, Any]:
+        started = time.perf_counter()
+        target = sel.get("target") or {}
+        loc = target.get("loc", "")
+        found = self.s.element(loc)
+        owners = sel.get("owners") or []
+        chain = sel.get("chain") or []
+        header: dict[str, Any] = {"loc": loc, "tag": target.get("tag", ""), "text": target.get("text", "")}
+        if found is None:
+            file, line, _ = _loc(loc)
+            header.update(file=file, line=line, known=False)
+            self._screen_owners(owners)
+        else:
+            build, el = found
+            header.update(file=el["file"], line=el["line"], known=True, element=el["tag"], component=el.get("fn", ""))
+            self._screen(build, el, chain, owners)
+            self._client(build, el, owners, chain)
+        page = page_for(self.g, sel.get("url", ""))
+        if page is not None:
+            self._page_row(page)
+            header["page"] = page.attrs.get("path")
+        self._network_and_server()
+        self._concepts(sel.get("attrs") or [])
+        result = self._result(header, started)
+        from stackthread import adapters
+
+        adapters.lineage(self.project, sel, result["layers"])
+        return result
+
+    def location(self, loc: str) -> dict[str, Any]:
+        """Lineage for a code location: an element if one starts there, otherwise the definition around it."""
+        started = time.perf_counter()
+        file, line, col = _loc(loc)
+        for build in self.s.js.values():
+            for el in build.elements.values():
+                if el["file"] == file and el["line"] == line and (not col or el["col"] == col):
+                    return self.selection({"target": {"loc": f"{file}:{line}:{el['col']}"}})
+        node = self.g.at(file, line)
+        if node is None:
+            return {"target": {"loc": loc, "known": False}, "layers": [], "rev": self.s.rev}
+        self._node(node)
+        header = {
+            "loc": loc,
+            "node": node.id,
+            "label": _fn_label(node),
+            "file": node.file,
+            "line": node.line,
+            "known": True,
+        }
+        return self._result(header, started)
+
+    # ------------------------------------------------------------------ screen
+
+    def _screen(
+        self, build: JsBuild, el: dict[str, Any], chain: list[dict[str, Any]], owners: list[dict[str, Any]]
+    ) -> None:
+        screen = self.layers["screen"]
+        text = f' "{el["text"]}"' if el.get("text") else ""
+        written_in = el.get("fn") or el["file"].rsplit("/", 1)[-1]
+        screen.add(
+            Row(
+                f"<{el['tag']}>{text}",
+                "element",
+                f"written in {written_in}",
+                el["file"],
+                el["line"],
+                loc=f"{el['file']}:{el['line']}:{el['col']}",
+            )
+        )
+        for link in chain[1:6]:
+            file, line, col = _loc(link.get("loc", ""))
+            if not file or file == el["file"]:
+                continue
+            found = self.s.element(f"{file}:{line}:{col}")
+            where = (found[1].get("fn") if found else None) or file.rsplit("/", 1)[-1]
+            screen.add(
+                Row(
+                    f"<{link.get('tag', '?')}>",
+                    "element",
+                    f"placed inside {where}",
+                    file,
+                    line,
+                    loc=f"{file}:{line}:{col}",
+                )
+            )
+            break
+        if el.get("fn"):
+            node = self.g.nodes.get(f"js:{build.source.name}:{el['file']}#{el['fn']}")
+            if node is not None:
+                screen.add(
+                    Row(
+                        _fn_label(node),
+                        node.kind,
+                        "the component it is written in",
+                        node.file,
+                        node.line,
+                        node.end,
+                        node.id,
+                    )
+                )
+        self._screen_owners(owners)
+
+    def _screen_owners(self, owners: list[dict[str, Any]]) -> None:
+        screen = self.layers["screen"]
+        skipped = 0
+        for owner in owners:
+            node = self._owner_node(owner)
+            if node is None:
+                skipped += 1
+                continue
+            file, line, _ = _loc(owner.get("loc", ""))
+            reason = f"rendered at {file.rsplit('/', 1)[-1]}:{line}" if file else "rendered by the app"
+            screen.add(
+                Row(
+                    _fn_label(node),
+                    node.kind,
+                    reason,
+                    node.file,
+                    node.line,
+                    node.end,
+                    node.id,
+                    loc=owner.get("loc") or "",
+                )
+            )
+        if skipped:
+            screen.rows.append(
+                Row(
+                    f"{skipped} library component{'s' * (skipped > 1)}",
+                    "external",
+                    "outside your code: router, UI kit, providers",
+                    external=True,
+                )
+            )
+
+    def _owner_node(self, owner: dict[str, Any]) -> Node | None:
+        """The component node for a fiber owner: through its call-site stamp, else a unique name."""
+        loc = owner.get("loc")
+        if loc:
+            found = self.s.element(loc)
+            if found:
+                build, el = found
+                target = build.component_for(el["file"], el["tag"])
+                if target and target in self.g.nodes:
+                    return self.g.nodes[target]
+        name = owner.get("name") or ""
+        matches = [n for n in self.g.of_kind("component") if n.name == name]
+        return matches[0] if len(matches) == 1 else None
+
+    def _page_row(self, page: Node) -> None:
+        comp = self.g.nodes.get(page.attrs.get("component", ""))
+        reason = f"route for {comp.name}" if comp else "route"
+        self.layers["screen"].add(
+            Row(page.attrs.get("path", page.name), "page", reason, page.file, page.line, node=page.id)
+        )
+
+    # ------------------------------------------------------------------ client
+
+    def _client(
+        self, build: JsBuild, el: dict[str, Any], owners: list[dict[str, Any]], chain: list[dict[str, Any]]
+    ) -> None:
+        fn = build.fn_index.get(el["file"], {}).get(el.get("fn") or "")
+        actions: list[Seed] = []
+        reads: list[Seed] = []
+        for a in el["attrs"]:
+            if a.get("handler"):
+                self.strings += a.get("strings", [])
+                how = f"{a['name']} handler"
+                actions += [Seed(c, how, "call", "action") for c in a.get("calls", [])]
+                actions += [Seed(r, how, "ref", "action") for r in a.get("refs", [])]
+            elif a["name"] not in SKIP_ATTRS:
+                how = f"sets {a['name']}"
+                reads += [Seed(c, how, "call", "reads") for c in a.get("calls", [])]
+                reads += [Seed(r, how, "ref", "reads") for r in a.get("refs", [])]
+        if not actions and el["tag"].lower() in ("button", "input"):
+            actions += self._form_submit(chain or self._written_chain(el))
+        reads = [Seed(r, "decides whether it shows", "ref", "reads") for r in el.get("conds", [])] + reads
+        reads += [Seed(r, "shown as text", "ref", "reads") for r in el.get("refs", [])]
+        reads += [Seed(c, "shown as text", "call", "reads") for c in el.get("calls", [])]
+        if el.get("each"):
+            reads.append(Seed(el["each"], "one per item of", "ref", "reads"))
+        self._follow(build, el["file"], fn, actions + reads, owners, 0, set())
+
+    def _written_chain(self, el: dict[str, Any]) -> list[dict[str, Any]]:
+        """Ancestors written in the same file, for a selection that arrives without the live DOM chain."""
+        out = [{"loc": f"{el['file']}:{el['line']}:{el['col']}"}]
+        parent = el.get("parent")
+        while parent and len(out) < 12:
+            loc = f"{el['file']}:{parent}"
+            found = self.s.element(loc)
+            if found is None:
+                break
+            out.append({"loc": loc})
+            parent = found[1].get("parent")
+        return out
+
+    def _form_submit(self, chain: list[dict[str, Any]]) -> list[Seed]:
+        for link in chain[1:]:
+            found = self.s.element(link.get("loc", ""))
+            if found and found[1]["tag"] in ("form", "Form"):
+                out = []
+                for a in found[1]["attrs"]:
+                    if a.get("handler") and a["name"] in ("onSubmit", "action"):
+                        self.strings += a.get("strings", [])
+                        out += [Seed(c, "submits the form", "call", "action") for c in a.get("calls", [])]
+                        out += [Seed(r, "submits the form", "ref", "action") for r in a.get("refs", [])]
+                return out
+        return []
+
+    def _follow(
+        self,
+        build: JsBuild,
+        file: str,
+        fn: dict[str, Any] | None,
+        seeds: list[Seed],
+        owners: list[dict[str, Any]],
+        depth: int,
+        seen: set[str],
+    ) -> None:
+        client = self.layers["client"]
+        bindings = fn.get("bindings", {}) if fn else {}
+        for seed in seeds:
+            if depth > DEPTH[seed.role]:
+                continue
+            root = seed.name.split(".")[0].split("[")[0].split("(")[0]
+            key = f"{file}#{fn['id'] if fn else ''}:{root}:{seed.kind}:{seed.role}"
+            if not root or key in seen:
+                continue
+            seen.add(key)
+            if root in bindings:
+                b = bindings[root]
+                called = any(c["callee"].split(".")[0].split("(")[0] == root for c in (fn or {}).get("calls", []))
+                value_read = (
+                    seed.kind == "ref"
+                    and b["kind"] not in ("function", "callback", "setter")
+                    and not (b["kind"] == "prop" and called)
+                )
+                method_on_value = seed.kind == "call" and "." in seed.name and b["kind"] in ("state", "reducer", "memo")
+                if seed.role == "action" and depth > 0 and (value_read or method_on_value):
+                    seed = Seed(seed.name, seed.how, seed.kind, "reads")  # a value the action reads, like title.trim()
+                self._binding(build, file, fn, root, b, seed, owners, depth, seen)
+                continue
+            target, confidence = build.resolve_callee(file, fn, seed.name if seed.kind == "call" else root)
+            if target is None and seed.kind == "ref":
+                target = build.resolve_name(file, root)
+            node = self.g.nodes.get(target or "")
+            if node is None or node.kind not in ("component", "function", "hook", "method"):
+                continue
+            client.add(
+                Row(
+                    _fn_label(node),
+                    node.kind,
+                    seed.how,
+                    node.file,
+                    node.line,
+                    node.end,
+                    node.id,
+                    confidence,
+                    depth=depth,
+                    role=seed.role,
+                )
+            )
+            self._walk_client(node, depth + 1, seed.role)
+
+    def _binding(
+        self,
+        build: JsBuild,
+        file: str,
+        fn: dict[str, Any] | None,
+        root: str,
+        b: dict[str, Any],
+        seed: Seed,
+        owners: list[dict[str, Any]],
+        depth: int,
+        seen: set[str],
+    ) -> None:
+        label = f"{root}()" if b["kind"] in ("function", "callback") else root
+        word = BINDING_WORDS.get(b["kind"], b["kind"])
+        detail = f" from {b['init']}()" if b.get("init") and b["kind"] in ("state", "setter", "hook", "memo") else ""
+        self.layers["client"].add(
+            Row(label, "binding", f"{word}{detail}; {seed.how}", file, b["line"], depth=depth, role=seed.role)
+        )
+        if b["kind"] == "prop" and depth < 3:
+            self._prop(build, file, fn, root, b, owners, depth, seed.role)
+        inner = [Seed(b["init"], f"creates {root}", "call", seed.role)] if b.get("init") else []
+        inner += [Seed(c, f"used by {root}", "call", seed.role) for c in b.get("calls", [])]
+        inner += [Seed(r, f"used by {root}", "ref", seed.role) for r in b.get("refs", []) if r.split(".")[0] != root]
+        self._follow(build, file, fn, inner, owners, depth + 1, seen)
+        for call in (fn or {}).get("calls", []):  # `calls[kind](...)`: follow the member the click chose
+            callee = call["callee"]
+            if "[]" in callee and call.get("in") == root:
+                self._computed_member(build, file, fn, callee.split("[")[0], depth + 1, seed.role)
+
+    def _computed_member(
+        self, build: JsBuild, file: str, fn: dict[str, Any] | None, base: str, depth: int, role: str
+    ) -> None:
+        """`calls[kind](...)`: when the element passed a string such as 'complete', follow that member."""
+        b = (fn or {}).get("bindings", {}).get(base)
+        if not b:
+            return
+        for inner in b.get("calls", []) + ([b["init"]] if b.get("init") else []):
+            owner, _ = build.resolve_callee(file, None, inner)
+            if not owner:
+                continue
+            for s in dict.fromkeys(self.strings):
+                target = build.member(owner, s)
+                node = self.g.nodes.get(target or "")
+                if node is not None:
+                    self.layers["client"].add(
+                        Row(
+                            _fn_label(node),
+                            node.kind,
+                            f"chosen by '{s}'",
+                            node.file,
+                            node.line,
+                            node.end,
+                            node.id,
+                            "inferred",
+                            depth=depth,
+                            role=role,
+                        )
+                    )
+                    self._walk_client(node, depth + 1, role)
+
+    def _prop(
+        self,
+        build: JsBuild,
+        file: str,
+        fn: dict[str, Any] | None,
+        local: str,
+        b: dict[str, Any],
+        owners: list[dict[str, Any]],
+        depth: int,
+        role: str,
+    ) -> None:
+        """Follow a prop to the JSX that passed it, in the parent that rendered this component."""
+        if fn is None:
+            return
+        prop = b.get("prop") if b.get("prop") not in (None, "*", "...") else local
+        sites: list[dict[str, Any]] = []
+        for owner in owners:
+            if owner.get("name") == fn["name"] and owner.get("loc"):
+                found = self.s.element(owner["loc"])
+                if found:
+                    sites.append(found[1])
+                break
+        if not sites:  # no live selection: every place that renders this component
+            node_id = f"js:{build.source.name}:{file}#{fn['id']}"
+            for edge in self.g.into(node_id, "renders")[:3]:
+                if edge.site:
+                    sites += [
+                        el
+                        for el in build.elements.values()
+                        if el["file"] == edge.site.file
+                        and el["line"] == edge.site.line
+                        and el["tag"].split(".")[-1] == fn["name"]
+                    ][:1]
+        for parent_el in sites:
+            attr = next((a for a in parent_el["attrs"] if a["name"] == prop), None)
+            if attr is None:
+                continue
+            parent_fn = build.fn_index.get(parent_el["file"], {}).get(parent_el.get("fn") or "")
+            summary = attr.get("literal") or ", ".join([*attr.get("calls", []), *attr.get("refs", [])][:4]) or "…"
+            self.layers["client"].add(
+                Row(
+                    f"{prop}={{…}}",
+                    "prop",
+                    f"passed by {parent_el.get('fn', 'parent')}: {summary}",
+                    parent_el["file"],
+                    parent_el["line"],
+                    depth=depth + 1,
+                    role=role,
+                    loc=f"{parent_el['file']}:{parent_el['line']}:{parent_el['col']}",
+                )
+            )
+            self.strings += attr.get("strings", [])
+            seeds = [Seed(c, f"in {prop} from the parent", "call", role) for c in attr.get("calls", [])]
+            seeds += [Seed(r, f"in {prop} from the parent", "ref", role) for r in attr.get("refs", [])]
+            self._follow(build, parent_el["file"], parent_fn, seeds, owners, depth + 2, set())
+
+    def _walk_client(self, start: Node, depth: int, role: str) -> None:
+        """Frontend call graph below a function, breadth first, remembering functions that send requests."""
+        if start.id in self.reached and (self.reached[start.id] == "action" or role == "reads"):
+            return
+        self.reached[start.id] = role
+        limit = DEPTH[role] + 2
+        queue = deque([(start, depth)])
+        while queue:
+            node, d = queue.popleft()
+            if d > limit:
+                continue
+            for edge in self.g.out(node.id, "calls"):
+                target = self.g.nodes[edge.dst]
+                if target.lang != "js" or target.kind == "component":
+                    continue
+                if target.id in self.reached and (self.reached[target.id] == "action" or role == "reads"):
+                    continue
+                self.reached[target.id] = role
+                self.layers["client"].add(
+                    Row(
+                        _fn_label(target),
+                        target.kind,
+                        f"called by {node.name}",
+                        target.file,
+                        target.line,
+                        target.end,
+                        target.id,
+                        edge.confidence,
+                        depth=min(d, 6),
+                        role=role,
+                    )
+                )
+                queue.append((target, d + 1))
+
+    # ------------------------------------------------------------------ network, server, data
+
+    def _network_and_server(self) -> None:
+        network = self.layers["network"]
+        endpoints: list[tuple[Node, str, str]] = []
+        for fn_id, role in self.reached.items():
+            node = self.g.nodes[fn_id]
+            when = "on use" if role == "action" else "loads data it reads"
+            for edge in self.g.out(fn_id, "http"):
+                ep = self.g.nodes[edge.dst]
+                site = edge.site
+                network.add(
+                    Row(
+                        edge.label or ep.name,
+                        "request",
+                        f"{when}; sent by {node.qualname or node.name}",
+                        site.file if site else node.file,
+                        site.line if site else node.line,
+                        confidence=edge.confidence,
+                        role=role,
+                    )
+                )
+                endpoints.append((ep, edge.confidence, role))
+            for req in node.attrs.get("requests", []):
+                if not req.get("matched"):
+                    network.add(
+                        Row(
+                            f"{req['method']} {req['url']}",
+                            "request",
+                            f"{when}; sent by {node.name}; no backend endpoint matches",
+                            node.file,
+                            req["line"],
+                            confidence="heuristic",
+                            role=role,
+                        )
+                    )
+        endpoints.sort(key=lambda e: e[2] != "action")
+        done: set[str] = set()
+        for ep, confidence, role in endpoints:
+            if ep.id not in done:
+                done.add(ep.id)
+                self._server_from_endpoint(ep, confidence, role)
+        self._data()
+
+    def _server_from_endpoint(self, ep: Node, confidence: str, role: str) -> None:
+        server = self.layers["server"]
+        note = ep.attrs.get("note", "")
+        server.add(
+            Row(
+                ep.name,
+                "endpoint",
+                f"{ep.attrs.get('framework', '')} endpoint{'; ' + note if note else ''}",
+                ep.file,
+                ep.line,
+                node=ep.id,
+                confidence=confidence,
+                role=role,
+            )
+        )
+        count = 0
+        for handler in (self.g.nodes[e.dst] for e in self.g.out(ep.id, "routes")):
+            server.add(
+                Row(
+                    _fn_label(handler),
+                    handler.kind,
+                    f"handles {ep.name}",
+                    handler.file,
+                    handler.line,
+                    handler.end,
+                    handler.id,
+                    depth=1,
+                    role=role,
+                )
+            )
+            self._mark_server(handler.id, role)
+            queue = deque([(handler, 2)])
+            visited = {handler.id}
+            while queue and count < SERVER_ROWS[role]:
+                node, depth = queue.popleft()
+                if depth > SERVER_DEPTH[role] + 1:
+                    continue
+                for edge in sorted(self.g.out(node.id, "calls", "uses"), key=lambda e: e.site.line if e.site else 0):
+                    target = self.g.nodes[edge.dst]
+                    if (
+                        target.id in visited
+                        or "test" in target.tags
+                        or target.lang != "python"
+                        or target.kind not in ("function", "method", "class")
+                    ):
+                        continue
+                    visited.add(target.id)
+                    how = _how(edge, node)
+                    server.add(
+                        Row(
+                            _fn_label(target),
+                            target.kind,
+                            how,
+                            target.file,
+                            target.line,
+                            target.end,
+                            target.id,
+                            edge.confidence,
+                            depth=min(depth, 6),
+                            role=role,
+                        )
+                    )
+                    self._mark_server(target.id, role)
+                    count += 1
+                    if count >= SERVER_ROWS[role]:
+                        break
+                    if edge.label != "raises":
+                        queue.append((target, depth + 1))
+
+    def _mark_server(self, node_id: str, role: str) -> None:
+        if self.server_nodes.get(node_id) != "action":
+            self.server_nodes[node_id] = role
+
+    def _data(self) -> None:
+        touches: dict[str, dict[str, Any]] = {}
+        for node_id, role in self.server_nodes.items():
+            for edge in self.g.out(node_id, "reads", "writes"):
+                entry = touches.setdefault(edge.dst, {"reads": [], "writes": [], "conf": "exact", "role": "reads"})
+                name = self.g.nodes[node_id].name
+                if name not in entry[edge.kind]:
+                    entry[edge.kind].append(name)
+                if CONFIDENCE_RANK[edge.confidence] > CONFIDENCE_RANK[entry["conf"]]:
+                    entry["conf"] = edge.confidence
+                if role == "action":
+                    entry["role"] = "action"
+        for target_id, entry in sorted(
+            touches.items(), key=lambda kv: (kv[1]["role"] != "action", not kv[1]["writes"])
+        ):
+            target = self.g.nodes[target_id]
+            parts = []
+            if entry["writes"]:
+                parts.append("written by " + ", ".join(entry["writes"][:4]))
+            if entry["reads"]:
+                parts.append("read by " + ", ".join(entry["reads"][:4]))
+            table = target.attrs.get("table") or target.attrs.get("collection")
+            label = f"{target.name} ({table})" if table else target.name
+            self.layers["data"].add(
+                Row(
+                    label,
+                    target.kind,
+                    "; ".join(parts),
+                    target.file,
+                    target.line,
+                    target.end,
+                    target.id,
+                    entry["conf"],
+                    role=entry["role"],
+                )
+            )
+
+    # ------------------------------------------------------------------ concepts
+
+    def _concepts(self, attrs: list[dict[str, Any]]) -> None:
+        concepts = self.project.config.concepts
+        if not concepts or not attrs:
+            return
+        root = self.project.config.root
+        for concept in concepts:
+            value = next((a.get("value") for a in attrs if a.get("name") == concept.attribute and a.get("value")), None)
+            if not value:
+                continue
+            layer = Layer(
+                f"concept:{concept.attribute}", concept.label.replace("{value}", value), f"from {concept.attribute}"
+            )
+            for find in concept.find:
+                pattern = find.pattern.replace("{value}", value)
+                for line_no, text in _lines(root / find.file):
+                    if pattern in text:
+                        layer.add(Row(text.strip()[:90], "definition", f"defined in {find.file}", find.file, line_no))
+                        break
+            if concept.mentions:
+                word = re.compile(rf"(?<![\w]){re.escape(value)}(?![\w])")
+                count = 0
+                for files in self.s.facts.values():
+                    for file in files:
+                        for line_no, text in _lines(root / file):
+                            if word.search(text) and count < MAX_MENTIONS:
+                                layer.add(Row(text.strip()[:90], "mention", "mentions it", file, line_no))
+                                count += 1
+            if layer.rows:
+                self.extra.append(layer)
+
+    # ------------------------------------------------------------------ code locations
+
+    def _node(self, node: Node) -> None:
+        """Lineage of a definition: who reaches it (screen, client) and what it reaches (server, data)."""
+        if node.lang == "js":
+            layer = "screen" if node.kind == "component" else "client"
+            self.layers[layer].add(
+                Row(
+                    _fn_label(node),
+                    node.kind,
+                    "this definition",
+                    node.file,
+                    node.line,
+                    node.end,
+                    node.id,
+                    role="action",
+                )
+            )
+            self._renderers(node, 0, set())
+            self._walk_client(node, 1, "action")
+            self._network_and_server()
+            return
+        self.layers["server"].add(
+            Row(_fn_label(node), node.kind, "this definition", node.file, node.line, node.end, node.id, role="action")
+        )
+        self._mark_server(node.id, "action")
+        for ep in self._endpoints_reaching(node.id):
+            self.layers["server"].add(Row(ep.name, "endpoint", "reaches this definition", ep.file, ep.line, node=ep.id))
+            for edge in self.g.into(ep.id, "http"):
+                caller = self.g.nodes[edge.src]
+                site = edge.site
+                self.layers["network"].add(
+                    Row(
+                        edge.label or ep.name,
+                        "request",
+                        f"sent by {caller.qualname or caller.name}",
+                        site.file if site else caller.file,
+                        site.line if site else caller.line,
+                        confidence=edge.confidence,
+                    )
+                )
+                self.layers["client"].add(
+                    Row(
+                        _fn_label(caller),
+                        caller.kind,
+                        f"calls {ep.name}",
+                        caller.file,
+                        caller.line,
+                        caller.end,
+                        caller.id,
+                    )
+                )
+                self._renderers(caller, 0, set())
+        queue = deque([(node, 1)])
+        visited = {node.id}
+        while queue:
+            current, depth = queue.popleft()
+            if depth > SERVER_DEPTH["action"]:
+                continue
+            for edge in self.g.out(current.id, "calls", "uses"):
+                target = self.g.nodes[edge.dst]
+                if target.id in visited or target.lang != "python" or "test" in target.tags:
+                    continue
+                visited.add(target.id)
+                self.layers["server"].add(
+                    Row(
+                        _fn_label(target),
+                        target.kind,
+                        _how(edge, current),
+                        target.file,
+                        target.line,
+                        target.end,
+                        target.id,
+                        edge.confidence,
+                        depth=min(depth, 6),
+                        role="action",
+                    )
+                )
+                self._mark_server(target.id, "action")
+                if edge.label != "raises":
+                    queue.append((target, depth + 1))
+        self._data()
+
+    def _endpoints_reaching(self, node_id: str) -> list[Node]:
+        out: list[Node] = []
+        queue = deque([node_id])
+        seen = {node_id}
+        while queue:
+            current = queue.popleft()
+            for edge in self.g.into(current, "routes"):
+                ep = self.g.nodes[edge.src]
+                if ep.kind == "endpoint" and ep not in out:
+                    out.append(ep)
+            for edge in self.g.into(current, "calls", "uses"):
+                if edge.src not in seen and len(seen) < 400:
+                    seen.add(edge.src)
+                    queue.append(edge.src)
+        return out
+
+    def _renderers(self, node: Node, depth: int, seen: set[str]) -> None:
+        """Components and functions that reach this one, up to the pages that route to them."""
+        if depth > 5 or node.id in seen:
+            return
+        seen.add(node.id)
+        for edge in self.g.into(node.id, "renders", "calls", "routes"):
+            src = self.g.nodes[edge.src]
+            if src.kind == "page":
+                self.layers["screen"].add(
+                    Row(
+                        src.attrs.get("path", src.name),
+                        "page",
+                        f"route for {node.name}",
+                        src.file,
+                        src.line,
+                        node=src.id,
+                    )
+                )
+            elif src.kind == "component":
+                verb = "renders" if edge.kind == "renders" else "calls"
+                line = edge.site.line if edge.site else src.line
+                self.layers["screen"].add(
+                    Row(
+                        _fn_label(src),
+                        "component",
+                        f"{verb} {node.name} at line {line}",
+                        src.file,
+                        src.line,
+                        src.end,
+                        src.id,
+                        depth=depth,
+                    )
+                )
+                self._renderers(src, depth + 1, seen)
+            elif src.kind in ("hook", "function", "method") and src.lang == "js":
+                self.layers["client"].add(
+                    Row(
+                        _fn_label(src), src.kind, f"calls {node.name}", src.file, src.line, src.end, src.id, depth=depth
+                    )
+                )
+                self._renderers(src, depth + 1, seen)
+
+
+USES_WORDS = {
+    "Depends": "injected into {} (Depends)",
+    "Security": "injected into {} (Security)",
+    "response": "response model of {}",
+    "type": "parameter type of {}",
+    "returns": "return type of {}",
+    "decorator": "decorates {}",
+    "passes": "passed as a callback by {}",
+}
+
+
+def _how(edge: Any, caller: Node) -> str:
+    if edge.label == "raises":
+        return f"raised by {caller.name}"
+    if edge.kind == "uses":
+        return USES_WORDS.get(edge.label, "used by {}").format(caller.name)
+    return f"called by {caller.name}"
+
+
+def _lines(path: Path) -> list[tuple[int, str]]:
+    try:
+        return list(enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1))
+    except OSError:
+        return []
+
+
+def for_selection(project: Project, snapshot: Snapshot, selection: dict[str, Any]) -> dict[str, Any]:
+    return Lineage(project, snapshot).selection(selection)
+
+
+def for_location(project: Project, snapshot: Snapshot, loc: str) -> dict[str, Any]:
+    return Lineage(project, snapshot).location(loc)