code-node-graph 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

code_node/__init__.py

@@ -13,7 +13,7 @@ from .libraries import Library, register_library
 from .platforms import Platform, get_platform, register_platform
 from .project import EntryPoint, Project, entry_points, read_project
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "CodeGraph",

code_node/analysis/graph.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import heapq
 import re
 from collections import defaultdict
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 
 from ..kit.fmt import _plural
 from ..kit.text import _clip
@@ -55,6 +55,7 @@ class GraphNode:
     when: str = ""  # a function called only under an if, everywhere it's called: 'check(order)'
     icon: str = ""  # a service's icon, when its plugin names one: 'database', 'queue', 'spark'; or the entry
     # point's logo, when its platform names one: 'fastapi-icon'
+    name: str = ""  # a function's box: the function, as module.name ('orders.repo.save')
 
 
 @dataclass
@@ -85,6 +86,7 @@ class CodeGraph:
     nodes: list[GraphNode] = field(default_factory=list)
     edges: list[GraphEdge] = field(default_factory=list)
     hidden: int = 0  # functions left out to keep the graph readable (too deep, or too many)
+    too_deep: int = 0  # ...of them, the ones deeper than it draws
 
     def node(self, node_id: str) -> GraphNode | None:
         return next((n for n in self.nodes if n.id == node_id), None)
@@ -256,11 +258,13 @@ def _pick(
     order: dict[str, int],
     room: int,
     max_depth: int,
+    first: bool = False,
 ) -> list[str]:
     """
     The functions the graph draws besides the entry point, at most `room` of them and max_depth calls deep: grown out
     from the entry point (and what runs at import), each time taking the one the drawn boxes call that leads to the
-    most code, so the boxes are the ones that do the work and each is joined to one above it.
+    most code, so the boxes are the ones that do the work and each is joined to one above it. first takes every
+    function the entry point calls before the rest.
     """
 
     def depth(name: str) -> int:
@@ -283,6 +287,14 @@ def _pick(
         if name not in level:
             offer(name)
     picked: list[str] = []
+    if first:
+        for child, _ in children.get(entry, []):
+            if child in by_name and child != entry and child not in picked and depth(child) <= max_depth:
+                picked.append(child)
+        for name in list(picked):
+            for child, _ in children.get(name, []):
+                if child not in picked:
+                    offer(child)
     while queue and len(picked) < room:
         name = heapq.heappop(queue)[3]
         if name in picked:
@@ -294,7 +306,46 @@ def _pick(
     return picked
 
 
-def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_depth: int = _GRAPH_DEPTH) -> CodeGraph:
+def _focused(cmap: CodeMap, focus: str) -> CodeMap:
+    """
+    The map cut down to one of its functions and what it calls, however deep, as if the code started there: its
+    calls in from elsewhere, what runs at import and the entry point's input left out.
+    """
+    children: dict[str, list[str]] = defaultdict(list)
+    for f in cmap.functions:
+        for where in f.called_from:
+            children[where.rpartition(" line ")[0]].append(f.name)
+    scope, todo = {focus}, [focus]
+    while todo:
+        for child in children.get(todo.pop(), []):
+            if child not in scope:
+                scope.add(child)
+                todo.append(child)
+    root = next(f for f in cmap.functions if f.name == focus)
+    functions = []
+    for f in cmap.functions:
+        if f.name in scope:
+            kept = [] if f.name == focus else [w for w in f.called_from if w.rpartition(" line ")[0] in scope]
+            functions.append(replace(f, called_from=kept, when={w: t for w, t in f.when.items() if w in kept}))
+    return replace(
+        cmap,
+        entry=focus,
+        handler_file=root.file,
+        entry_line=root.line,
+        startup=[],
+        event=[],
+        functions=functions,
+        aws=[c for c in cmap.aws if c.function in scope],
+        library_calls=[c for c in cmap.library_calls if c.function in scope],
+        env=[e for e in cmap.env if e.function in scope],
+        spots=[s for s in cmap.spots if s.function in scope and not s.startup],
+        routes=[r for r in cmap.routes if r[2] in scope],
+    )
+
+
+def code_graph(
+    cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_depth: int = _GRAPH_DEPTH, focus: str = ""
+) -> CodeGraph:
     """
     How the code fits together, as boxes and arrows, from a CodeMap: on the left what comes in (the event, with the
     fields it reads, and the environment variables), then the handler, what runs at start-up, and its own functions
@@ -304,10 +355,16 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
     they do is drawn from the nearest box above them that is.
     The functions drawn are grown out from the entry point, each time the one that leads to the most code (and to AWS,
     the web and the environment), so the boxes are the ones that do the work, not the nearest helpers.
+    focus draws the graph from one of its functions instead (module.name): it and what it calls, every call it makes
+    drawn even past max_functions, and nothing from what comes in or what runs at import.
     """
     graph = CodeGraph()
     if cmap.note or cmap.entry is None:
         return graph
+    if focus:
+        if not any(f.name == focus for f in cmap.functions):
+            return graph
+        cmap = _focused(cmap, focus)
     platform = get_platform(cmap.platform)
     entry = cmap.entry
     by_name = {f.name: f for f in cmap.functions}
@@ -342,11 +399,15 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
                 todo.append(child)
     order = {f.name: i for i, f in enumerate(cmap.functions)}
     weight = _weights(cmap, children)
-    picked = _pick(cmap, entry, start_key, children, level, weight, order, max_functions - entry_is_function, max_depth)
+    room = max_functions - entry_is_function
+    if focus:  # a function opened on its own shows every call it makes
+        room = max(room, len({child for child, _ in children.get(entry, [])}))
+    picked = _pick(cmap, entry, start_key, children, level, weight, order, room, max_depth, first=bool(focus))
     shown = ([by_name[entry]] if entry_is_function else []) + sorted(
         (by_name[name] for name in picked), key=lambda f: (level.get(f.name, f.depth + 1), order[f.name])
     )
     graph.hidden = len(cmap.functions) - len(shown)
+    graph.too_deep = sum(1 for f in cmap.functions if level.get(f.name, f.depth + 1) > max_depth)
     ids = {f.name: f"f{i}" for i, f in enumerate(shown)}
     drawn_level = {entry: 0, start_key: 0}  # calls from the entry point through the boxes drawn: each box's column
     todo = [entry, start_key]
@@ -408,7 +469,9 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
             reasons[call.function].append(f"{call.label} isn't allowed: {denied[call.permission]} (line {call.line})")
     for function, why in platform.marks(cmap).items():
         reasons[function] += why
-    handler_reasons = [m.split(":")[0] for level_, m in platform.entry_findings(cmap) if level_ == "warn"]
+    handler_reasons = (
+        [] if focus else [m.split(":")[0] for level_, m in platform.entry_findings(cmap) if level_ == "warn"]
+    )
     unset = platform.unset_env(cmap)
 
     # the lines in each function worth pointing at: where it calls, reads or sends what the graph draws
@@ -455,7 +518,7 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
                     when=_when(f, [where for where in f.called_from if where.rpartition(" line ")[0] == caller]),
                 )
             )
-    has_input = bool(cmap.event) or platform.draws_input
+    has_input = not focus and (bool(cmap.event) or platform.draws_input)
     if has_input:
         edges.insert(0, GraphEdge("event", entry_id, "event", "its input"))
 
@@ -769,7 +832,8 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
                 ],
                 more=more,
                 when=_when(f, f.called_from),
-                icon=platform.entry_icon(cmap) if is_entry else "",
+                icon=platform.entry_icon(cmap) if is_entry and not focus else "",
+                name=f.name,
             )
         )
     out_column = 1 + max([n.column for n in graph.nodes if n.kind in ("handler", "function", "start")] + [1])
@@ -778,3 +842,80 @@ def code_graph(cmap: CodeMap, *, max_functions: int = _GRAPH_FUNCTIONS, max_dept
     graph.nodes += reach
     graph.edges = edges
     return graph
+
+
+_GRAPH_VIEWS = 120  # functions opened on their own, at most: past that a box's calls left out stay in the steps
+
+_GRAPH_EVERYTHING = 150  # functions, at most, for a graph of all of them besides the one drawn
+
+
+@dataclass
+class GraphView:
+    """
+    The graph from one of the functions a graph leaves calls out of: the function and what it calls (`graph`), and the
+    calls from the entry point down to it (`path`, module.name each, the entry point first and the function last).
+    """
+
+    name: str
+    graph: CodeGraph
+    path: list[str] = field(default_factory=list)
+
+
+def _call_path(cmap: CodeMap, name: str) -> list[str]:
+    """
+    The fewest calls from the entry point to a function: [entry, ..., name]. [name] when the entry point isn't above it.
+    """
+    known = {f.name for f in cmap.functions} | {cmap.entry or ""}
+    parents: dict[str, list[str]] = defaultdict(list)
+    for f in cmap.functions:
+        for where in f.called_from:
+            caller = where.rpartition(" line ")[0]
+            if caller in known:
+                parents[f.name].append(caller)
+    came: dict[str, str] = {name: ""}
+    todo = [name]
+    while todo:
+        key = todo.pop(0)
+        if key == cmap.entry:
+            path = [key]
+            while came[path[-1]]:
+                path.append(came[path[-1]])
+            return path
+        for parent in parents.get(key, []):
+            if parent not in came:
+                came[parent] = key
+                todo.append(parent)
+    return [name]
+
+
+def graph_views(
+    cmap: CodeMap,
+    graph: CodeGraph,
+    *,
+    max_functions: int = _GRAPH_FUNCTIONS,
+    max_depth: int = _GRAPH_DEPTH,
+    most: int = _GRAPH_VIEWS,
+) -> list[GraphView]:
+    """
+    A graph from each function whose calls `graph` leaves out, and from each such function in those, so that from any
+    box with calls not drawn, its own graph has them: at most `most`, nearest the entry point first.
+    """
+    views: dict[str, GraphView] = {}
+    todo = [graph]
+    while todo and len(views) < most:
+        for n in todo.pop(0).nodes:
+            if not (n.more and n.name) or n.name in views or len(views) >= most:
+                continue
+            opened = code_graph(cmap, max_functions=max_functions, max_depth=max_depth, focus=n.name)
+            views[n.name] = GraphView(n.name, opened, _call_path(cmap, n.name))
+            todo.append(opened)
+    return list(views.values())
+
+
+def everything_graph(cmap: CodeMap, graph: CodeGraph, most: int = _GRAPH_EVERYTHING) -> CodeGraph | None:
+    """
+    Every function in one graph, when `graph` leaves some out and there are at most `most` of them; else None.
+    """
+    if not graph.hidden or len(cmap.functions) > most:
+        return None
+    return code_graph(cmap, max_functions=len(cmap.functions) + 1, max_depth=len(cmap.functions) + 1)

code_node/analysis/reader.py

@@ -203,6 +203,22 @@ class _CodeReader:
             module = module[: -len(".__init__")] if module.endswith(".__init__") else module
             if module and module != "__init__":
                 self.sources[module] = path
+        here = (cmap.handler_file or "").rpartition("/")[0]
+        here = here + "/" if here else ""
+        if here.startswith(root) and here != root:
+            # the entry point's own folder is on sys.path too, as a script's is and a Lambda function's code is:
+            # `from helpers import x` beside it is its own code, though the folder is also a package from the root
+            beside: set[str] = set()
+            for path in texts:
+                if not path.startswith(here) or not path.endswith(".py") or "site-packages" in path:
+                    continue
+                module = path[len(here) : -3].replace("/", ".")
+                module = module[: -len(".__init__")] if module.endswith(".__init__") else module
+                if module and module != "__init__" and "-" not in module and module not in self.sources:
+                    self.sources[module] = path
+                    beside.add(module.split(".")[0])
+            self.tops |= beside
+            self.libraries = libraries - beside
         self.modules: dict[str, _Module] = {}
         self.defs: dict[str, tuple[str, Any, str | None]] = {}  # key -> (module, node, class key)
         self.classes: dict[str, dict[str, Any]] = {}
@@ -311,8 +327,9 @@ class _CodeReader:
         cmap.event = list(self.event_reads.values())
         cmap.routes = [(method, path, key) for method, path, key, _ in self.routes]
         loaded = [m for m in self.modules.values() if m.tree is not None]
-        cmap.other_files = sum(
-            1 for name, path in self.sources.items() if name not in self.modules and not _JUNK_RE.search(path)
+        read = {path for name, path in self.sources.items() if name in self.modules}  # a file has two names, at most
+        cmap.other_files = len(
+            {path for path in self.sources.values() if path not in read and not _JUNK_RE.search(path)}
         )
         for m in loaded:
             for node in m.tree.body:
@@ -324,7 +341,7 @@ class _CodeReader:
                     if isinstance(f, (ast.FunctionDef, ast.AsyncFunctionDef)) and prefix + f.name not in self.reached
                 )
             self._secrets(m)
-        for name, path in self.sources.items():
+        for path, name in {path: name for name, path in reversed(self.sources.items())}.items():
             for match in _AWS_KEY_RE.finditer(self.texts[path]):
                 line = self.texts[path].count("\n", 0, match.start()) + 1
                 self._spot("secret", path, line, name, "", "an AWS access key", ok=False)

code_node/report/build.py

@@ -10,7 +10,7 @@ from ..kit.blocks import _Note, _Text
 from ..kit.fmt import _plural
 
 from ..analysis.findings import _listed, _short_name
-from ..analysis.graph import CodeGraph, code_graph
+from ..analysis.graph import CodeGraph, code_graph, everything_graph, graph_views
 from ..analysis.model import CodeMap
 from .graph import _Graph
 from .tabs import _Tabs
@@ -34,8 +34,8 @@ def _closing_note(cmap: CodeMap, graph: CodeGraph) -> str:
         said.append(f"Calls to {_listed(services, 4)} are read by code-node's library plugins.")
     if graph.hidden:
         said.append(
-            f"The graph leaves out {_plural(graph.hidden, 'function')} to stay readable: run with --all to "
-            "draw every one."
+            f"The graph leaves out {_plural(graph.hidden, 'function')} to stay readable: a box's line of calls not "
+            "drawn opens them, and --all draws every one."
         )
     if cmap.other_files:
         said.append(
@@ -99,6 +99,8 @@ def page_blocks(
                         "How it fits together: what comes in, who calls whom, and what it reaches",
                         sources=sources or {},
                         editor=editor,
+                        views=graph_views(cmap, graph, max_functions=max_functions, max_depth=max_depth),
+                        everything=everything_graph(cmap, graph),
                     ),
                     _Text(
                         graph.mermaid(),

code_node/report/graph.py

@@ -17,7 +17,8 @@ from ..kit.highlight import _python_html, _python_lines
 from ..kit.render import _CALL_RE, _prose
 from ..kit.text import _esc
 
-from ..analysis.graph import CodeGraph, GraphEdge, GraphNode
+from ..analysis.findings import _short_name
+from ..analysis.graph import CodeGraph, GraphEdge, GraphNode, GraphView
 from .brands import AWS_LOGOS, SERVICE_LOGOS, fills, logo, small_logo
 from .editor import editor_name, open_at
 from .style import _ROOT
@@ -36,6 +37,9 @@ class _Graph:
     empty: str = "(nothing to draw)"
     sources: dict[str, str] = field(default_factory=dict)
     editor: str = ""  # a link to open a line in an editor, from editor_link(): each place in a panel links to it
+    views: list[GraphView] = field(default_factory=list)  # with JavaScript, a box's line of calls not drawn opens the
+    # graph from that function, from these (graph_views())
+    everything: CodeGraph | None = None  # ...and a button in the bar draws every function, this graph
 
 
 _EDGE_WORDS = {
@@ -999,12 +1003,32 @@ def _g_calls(count: int) -> str:
     return f"{count} call" if count == 1 else f"{count} calls"
 
 
+def _g_prose_top(card: _GCard) -> float:
+    """
+    Where a box's prose starts: under its header, its route's pill and its when pill.
+    """
+    return card.head + (_GRAPH_ROUTE if card.route else 0) + (_GRAPH_ROUTE if card.node.when else 0)
+
+
+def _g_more_y(card: _GCard) -> float:
+    """
+    The baseline of a box's line of calls not drawn.
+    """
+    return _g_prose_top(card) + 13 + _GRAPH_PROSE * len(card.prose)
+
+
 def _node_svg(
-    card: _GCard, box: tuple[float, float, float, float], neighbours: list[str], access: dict[str, str]
+    card: _GCard,
+    box: tuple[float, float, float, float],
+    neighbours: list[str],
+    access: dict[str, str],
+    panel: str = "",
+    opens: bool = False,
 ) -> str:
     """
     A box: its badge and name, what's under it, a route's pill, its listed lines (an operation's dot in its arrows'
-    colour, a line a warning is about with its flag) or its docstring, and a warning badge.
+    colour, a line a warning is about with its flag) or its docstring, and a warning badge. panel is the id of its
+    code's panel, and opens says its line of calls not drawn opens a graph of its own (a link drawn over it).
     """
     n = card.node
     x, y, w, h = box
@@ -1071,15 +1095,18 @@ def _node_svg(
             if _g_sans(f"{said}: {names}", 12.5) <= w - 28:
                 said = f"{said}: {names}"
                 break
-        parts.append(
-            f'<text class="pr mo" x="14" y="{top + 13 + _GRAPH_PROSE * len(card.prose):.1f}">{_esc(said)}</text>'
-        )
+        parts.append(f'<text class="pr mo md" x="14" y="{_g_more_y(card):.1f}">{_esc(said)}</text>')
     if warn:
         parts.append(
             f'<g class="wb" transform="translate({w - 21:.0f},{badge_y + _G_BADGE / 2:.0f})"><circle r="8.5"/>'
             '<path d="M0,-4.2V.6M0,3.9V4"/></g>'
         )
-    classes = " ".join(["cn", f"k-{n.kind}", f"n-{n.id}", *(f"a-{m}" for m in neighbours)]) + (" warn" if warn else "")
+    classes = " ".join(
+        ["cn", f"k-{n.kind}", f"n-{n.id}", *(f"a-{m}" for m in neighbours)]
+        + ([f"p-{panel}"] if panel else [])
+        + (["hd"] if opens else [])
+        + (["warn"] if warn else [])
+    )
     return (
         f'<g class="{_esc(classes)}" transform="translate({x:.1f},{y:.1f})">'
         f'<rect class="bg" width="{w:.0f}" height="{h:.0f}" rx="11"/>'
@@ -1114,11 +1141,11 @@ def _g_filled(line: str) -> bool:
     return bool(re.sub(r"<[^>]*>", "", line).strip())
 
 
-def _g_panel(n: GraphNode, lines_of: Callable[[str], list[str]], editor: str = "") -> str:
+def _g_panel(n: GraphNode, lines_of: Callable[[str], list[str]], editor: str = "", panel: str = "") -> str:
     """
-    A box's code, in a panel that slides in from the right when the box is clicked (its id is the link's target, so
-    it's CSS's :target that opens it): what the box is, then each place it's about with its lines numbered, the lines
-    worth pointing at lit. '' when none of its code is in the files read.
+    A box's code, in a panel that slides in from the right when the box is clicked (its id, panel or the box's own, is
+    the link's target, so it's CSS's :target that opens it): what the box is, then each place it's about with its
+    lines numbered, the lines worth pointing at lit. '' when none of its code is in the files read.
     """
     shown, lit_any = [], False
     for span in n.code[:_G_PANEL_SPANS]:
@@ -1157,7 +1184,11 @@ def _g_panel(n: GraphNode, lines_of: Callable[[str], list[str]], editor: str = "
     rest = len(n.code) - _G_PANEL_SPANS
     if rest > 0:
         shown.append(f'<div class="csm">+{_plural(rest, "more place")}: the tables below list them all</div>')
-    said = "".join(f'<p class="csd">{_prose(line)}</p>' for line in (n.tip or "").split("\n") if line)
+    said = "".join(  # not the calls this graph leaves out: a function's panel is the same in every graph it's in
+        f'<p class="csd">{_prose(line)}</p>'
+        for line in (n.tip or "").split("\n")
+        if line and not (n.more and line.startswith("It calls ") and "the graph leaves out" in line)
+    )
     if lit_any:
         said += (
             '<p class="csd csl">The lit lines are where it calls, reads or sends what its arrows show.</p>'
@@ -1166,7 +1197,7 @@ def _g_panel(n: GraphNode, lines_of: Callable[[str], list[str]], editor: str = "
         )
     mono = " mono" if n.kind in ("handler", "function") else ""
     return (
-        f'<aside class="cside" id="{_esc(_g_panel_id(n))}" aria-label="{_esc("The code of " + n.label)}">'
+        f'<aside class="cside" id="{_esc(panel or _g_panel_id(n))}" aria-label="{_esc("The code of " + n.label)}">'
         f'<div class="csh"><div class="cst"><span class="csk">{_esc(_G_PANEL_KINDS.get(n.kind, n.kind))}</span>'
         f'<b class="csn{mono}">{_esc(n.label)}</b>'
         + (f'<span class="css">{_esc(n.sub)}</span>' if n.sub else "")
@@ -1368,12 +1399,87 @@ def _g_swatch(kind: str) -> str:
     )
 
 
-@_draws(_Graph, "html")
-def _graph_html(block: _Graph, report: _Report) -> str:
-    title = f"<h4>{_prose(block.title)}</h4>" if block.title else ""
-    graph = block.graph
-    if not graph.nodes:
-        return title + f'<div class="more">{_esc(block.empty)}</div>'
+_G_SCRIPT = """<script>
+(() => {
+  // A graph's views: a box's line of calls not drawn, the path over a view and the bar's All button link to
+  // #<group>-v<k> (or -all, or -main), and each is a <template> the graph's box, path and key are swapped from.
+  // Any other address (a box's code open, or closed) leaves the view as it is.
+  const parts = ["cgc", "cg", "cgk"];
+  const show = (wrap) => {
+    const group = wrap.dataset.group, id = decodeURIComponent(location.hash.slice(1));
+    const named = id === group + "-main" || id === group + "-all" || id.startsWith(group + "-v");
+    if (id && !named) return;
+    const view = named && id !== group + "-main" ? id : "";
+    if ((wrap.dataset.view || "") === view) return;
+    const from = view ? document.getElementById(view)?.content : wrap.main;
+    if (!from) return;
+    for (const part of parts) {
+      wrap.querySelector(".cgb > ." + part).innerHTML = from.querySelector(".x-" + part).innerHTML;
+    }
+    wrap.dataset.view = view;
+    wrap.querySelector(".cgb").scrollIntoView({block: "nearest"});
+  };
+  for (const wrap of document.querySelectorAll(".cgw[data-group]")) {
+    const main = document.createElement("template");
+    for (const part of parts) {
+      const kept = document.createElement("div");
+      kept.className = "x-" + part;
+      kept.innerHTML = wrap.querySelector(".cgb > ." + part).innerHTML;
+      main.content.append(kept);
+    }
+    wrap.main = main.content;
+    wrap.classList.add("js");
+    show(wrap);
+  }
+  addEventListener("hashchange", () => document.querySelectorAll(".cgw.js").forEach(show));
+  // A box's code: a click anywhere outside its panel closes it, as its × does, and so does Escape. A link (another
+  // box, a view) and the graph's bar do what they do with the panel left to them.
+  const close = () => { if (document.querySelector(".cside:target")) location.hash = "cn-closed"; };
+  document.addEventListener("click", (e) => {
+    const open = document.querySelector(".cside:target");
+    if (open && !open.contains(e.target) && !e.target.closest("a[href], label, input, .cgt")) close();
+  });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape") close(); });
+})();
+</script>"""
+
+
+def _g_hidden(graph: CodeGraph, opens: bool) -> str:
+    """
+    The legend's pill for the functions a graph leaves out, and why: without JavaScript where to find them, with it
+    (when opens) that a box's line of them opens them.
+    """
+    if not graph.hidden:
+        return ""
+    why = (
+        "too deep"
+        if graph.too_deep == graph.hidden
+        else "too many to draw at once"
+        if not graph.too_deep
+        else "too deep or too many"
+    )
+    head = f"<b>+{graph.hidden}</b>{'more function' if graph.hidden == 1 else 'more functions'} not drawn ({why})"
+    pill = f'<span class="kp kh{" nj" if opens else ""}">{head}: the Step by step tab has them all</span>'
+    if opens:
+        pill += f'<span class="kp kh oj">{head}: click a box\'s blue line of calls to open them</span>'
+    return pill
+
+
+def _g_canvas(
+    graph: CodeGraph,
+    block: _Graph,
+    report: _Report,
+    lines_of: Callable[[str], list[str]],
+    panels: dict[str, tuple[str, str]],
+    opens: dict[str, str],
+    prefix: str,
+) -> tuple[str, str]:
+    """
+    One graph drawn: its SVG and its legend. Its boxes' panels go into panels ({a function, or a panel without its
+    id: (its id, the panel)}, one for a function or the same code wherever it's drawn, the first graph's; a new one's
+    id starts with prefix), and a box whose function is in opens ({module.name: a
+    link}) has its line of calls not drawn made that link.
+    """
     cards = _g_cards(graph)
     boxes, routes, width, tall, xs, widths, column_of = _graph_layout(graph, cards)
     ends = _g_anchors(graph, cards, boxes)
@@ -1386,20 +1492,24 @@ def _graph_html(block: _Graph, report: _Report) -> str:
             for name in _g_names(e):
                 access[e.target].setdefault(name, e.kind)
     root = report.root or _ROOT
-    highlighted: dict[str, list[str]] = {}
-
-    def lines_of(file: str) -> list[str]:  # a file's lines in colour, each file coloured once
-        if file not in highlighted:
-            highlighted[file] = _python_lines(block.sources[file]) if file in block.sources else []
-        return highlighted[file]
-
-    panels = {n.id: _g_panel(n, lines_of, block.editor) for n in graph.nodes} if block.sources else {}
-    for n in graph.nodes:
-        if panels.get(n.id):  # the box whose code is open, outlined
-            report.rules.add(
-                f".{root} .cgw:has(#{_g_panel_id(n)}:target) .cg .n-{n.id} .fg"
-                "{stroke:light-dark(#2563eb,#60a5fa);stroke-opacity:1;stroke-width:2}"
-            )
+    panel_of: dict[str, str] = {}  # a box -> its panel's id
+    if block.sources:
+        for n in graph.nodes:
+            same = "\0" + n.name if n.name else ""
+            if same not in panels:
+                html = _g_panel(n, lines_of, block.editor, "\0")
+                if not html:
+                    continue
+                same = same or html
+                if same not in panels:
+                    key = prefix + _g_panel_id(n)
+                    panels[same] = (key, html.replace('id="\0"', f'id="{key}"', 1))
+            panel_of[n.id] = panels[same][0]
+    for key in set(panel_of.values()):  # the box whose code is open, outlined
+        report.rules.add(
+            f".{root} .cgw:has(#{key}:target) .cg .p-{key} .fg"
+            "{stroke:light-dark(#2563eb,#60a5fa);stroke-opacity:1;stroke-width:2}"
+        )
     for n in graph.nodes:  # pointing at a box leaves only it, its arrows and the boxes they join in sight
         report.rules.add(f".{root} .cg:has(.n-{n.id}:hover) .ce:not(.s-{n.id}):not(.t-{n.id}){{opacity:.06}}")
         report.rules.add(f".{root} .cg:has(.n-{n.id}:hover) .cn:not(.n-{n.id}):not(.a-{n.id}){{opacity:.28}}")
@@ -1446,16 +1556,33 @@ def _graph_html(block: _Graph, report: _Report) -> str:
             marked.add((e.source, e.target))
     edges = "".join(body for body, _ in drawn)
     ports = "".join(dots for _, dots in drawn)
+    opened = {n.id: opens[n.name] for n in graph.nodes if n.more and n.name in opens}
     nodes = "".join(
         (
-            f'<a class="cl" href="#{_esc(_g_panel_id(n))}" aria-label="{_esc("Show the code of " + n.label)}">{box}</a>'
-            if panels.get(n.id)
+            f'<a class="cl" href="#{_esc(panel_of[n.id])}" aria-label="{_esc("Show the code of " + n.label)}">{box}</a>'
+            if n.id in panel_of
             else box
         )
         for n in graph.nodes
-        for box in [_node_svg(cards[n.id], boxes[n.id], list(dict.fromkeys(near[n.id])), access[n.id])]
+        for box in [
+            _node_svg(
+                cards[n.id],
+                boxes[n.id],
+                list(dict.fromkeys(near[n.id])),
+                access[n.id],
+                panel_of.get(n.id, ""),
+                n.id in opened,
+            )
+        ]
+    )
+    links = "".join(  # over each line of calls not drawn that opens a graph of its own: drawn with JavaScript only
+        f'<a class="dr" href="#{_esc(link)}" aria-label="{_esc(f"Open the calls {n.label} makes")}">'
+        f'<rect x="{boxes[n.id][0] + 8:.1f}" y="{boxes[n.id][1] + _g_more_y(cards[n.id]) - 14:.1f}" '
+        f'width="{boxes[n.id][2] - 16:.0f}" height="19" rx="5"/></a>'
+        for n in graph.nodes
+        if (link := opened.get(n.id))
     )
-    tips = "".join(_g_tip_svg(n, boxes[n.id], width, tall, lines_of, bool(panels.get(n.id))) for n in graph.nodes)
+    tips = "".join(_g_tip_svg(n, boxes[n.id], width, tall, lines_of, n.id in panel_of) for n in graph.nodes)
     kinds = {e.kind for e in graph.edges}
     pills = [f'<span class="kp">{_g_swatch(k)}{_esc(word)}</span>' for k, word in _G_LEGEND if k in kinds]
     if any(e.guessed for e in graph.edges):
@@ -1474,22 +1601,71 @@ def _graph_html(block: _Graph, report: _Report) -> str:
             f'aria-hidden="true"><circle r="7"/><path transform="scale(.6) translate(-8,-8)" d="{_G_LOOP}"/>'
             "</svg>in a loop: once per item</span>"
         )
-    hidden = (
-        (
-            f'<span class="kp kh"><b>+{graph.hidden}</b>{"more function" if graph.hidden == 1 else "more functions"} '
-            "not drawn (too deep or too many): the Step by step tab has them all</span>"
-        )
-        if graph.hidden
-        else ""
-    )
     hint = (
         '<span class="kt">Point at a box to see only what it\'s joined to'
-        + ("; click it to read its code" if any(panels.values()) else "")
+        + ("; click it to read its code" if panel_of else "")
         + "</span>"
     )
+    svg = (
+        f'<svg viewBox="0 0 {width:.0f} {tall:.0f}" width="{width:.0f}" height="{tall:.0f}" '
+        f'style="--w:{width:.0f}px" role="img" aria-label="{_esc(block.title or "How the code fits together")}">'
+        f"{_g_captions(graph, xs, widths, column_of)}{edges}{nodes}{links}{ports}{tips}</svg>"
+    )
+    return svg, "".join(pills) + _g_hidden(graph, bool(opened)) + hint
+
+
+def _g_path(path: list[str], links: dict[str, str], main: str, last: str = "") -> str:
+    """
+    The calls from the entry point down to a view's function, over its graph: each one that has a view of its own a
+    link to it, and a link back to the whole graph first. last, when given, is said after them in place of the last.
+    """
+    names = [_esc(_short_name(name)) + "()" for name in path]
+    steps = [
+        f'<a href="#{_esc(links[name])}"><code>{said}</code></a>' if name in links else f"<code>{said}</code>"
+        for name, said in zip(path[:-1], names[:-1])
+    ]
+    steps.append(_esc(last) if last else f"<b><code>{names[-1]}</code></b>" if names else "")
+    return f'<a class="cgcb" href="#{_esc(main)}">← The whole graph</a>' + "".join(
+        f'<span class="cgcs">›</span>{step}' for step in steps
+    )
+
+
+@_draws(_Graph, "html")
+def _graph_html(block: _Graph, report: _Report) -> str:
+    title = f"<h4>{_prose(block.title)}</h4>" if block.title else ""
+    graph = block.graph
+    if not graph.nodes:
+        return title + f'<div class="more">{_esc(block.empty)}</div>'
+    highlighted: dict[str, list[str]] = {}
+
+    def lines_of(file: str) -> list[str]:  # a file's lines in colour, each file coloured once
+        if file not in highlighted:
+            highlighted[file] = _python_lines(block.sources[file]) if file in block.sources else []
+        return highlighted[file]
+
     made = report.shared("graphs", lambda: [0])  # graphs drawn so far, so each one's buttons have ids of their own
     group = f"cn-graph{made[0]}"
     made[0] += 1
+    links = {view.name: f"{group}-v{k}" for k, view in enumerate(block.views, 1)}
+    panels: dict[str, tuple[str, str]] = {}
+    svg, legend = _g_canvas(graph, block, report, lines_of, panels, links, "")
+    views = []
+    for k, view in enumerate(block.views, 1):
+        drawn, key = _g_canvas(view.graph, block, report, lines_of, panels, links, f"v{k}-")
+        views.append(
+            f'<template id="{group}-v{k}"><div class="x-cgc">{_g_path(view.path, links, group + "-main")}</div>'
+            f'<div class="x-cg">{drawn}</div><div class="x-cgk">{key}</div></template>'
+        )
+    everything = ""
+    if block.everything is not None and block.everything.nodes:
+        count = sum(1 for n in block.everything.nodes if n.kind in ("handler", "function"))
+        drawn, key = _g_canvas(block.everything, block, report, lines_of, panels, {}, "all-")
+        views.append(
+            f'<template id="{group}-all"><div class="x-cgc">'
+            f"{_g_path([], links, group + '-main', f'Every function, all {count} of them')}</div>"
+            f'<div class="x-cg">{drawn}</div><div class="x-cgk">{key}</div></template>'
+        )
+        everything = f'<a class="cgta oj" href="#{group}-all" title="Every function in one graph">All {count}</a>'
     # its zoom and full screen: inputs before the box they change, so CSS reaches it with ~ (no :has(), no script)
     switches = f'<input type="checkbox" class="cgs cgfs" id="{group}-full">' + "".join(
         f'<input type="radio" class="cgs cgz-{key}" name="{group}-zoom" id="{group}-{key}"'
@@ -1497,7 +1673,7 @@ def _graph_html(block: _Graph, report: _Report) -> str:
         for key, _, _ in _GRAPH_ZOOMS
     )
     bar = (
-        '<div class="cgt"><span class="cgtz" role="group" aria-label="Zoom">'
+        f'<div class="cgt">{everything}<span class="cgtz" role="group" aria-label="Zoom">'
         + "".join(
             f'<label class="zl-{key}" for="{group}-{key}" title="{_esc(tip)}">{_esc(word)}</label>'
             for key, word, tip in _GRAPH_ZOOMS
@@ -1505,14 +1681,18 @@ def _graph_html(block: _Graph, report: _Report) -> str:
         + f'</span><label class="cgtf" for="{group}-full"><span class="on">Full screen</span>'
         '<span class="off">Close full screen</span></label></div>'
     )
+    script = ""
+    if (views or panels) and not report.shared("graph-script", lambda: [False])[0]:
+        report.shared("graph-script", lambda: [False])[0] = True
+        script = _G_SCRIPT
     # in a box of its own with its panels: the :has() rules that outline a box whose code is open look only in here,
     # so a radio button elsewhere (the walk's steps) doesn't make the browser restyle the whole page
+    data = f' data-group="{group}"' if views else ""
     return (
-        f'{title}<div class="cgw">{switches}<div class="cgb">{bar}<div class="cg">'
-        f'<svg viewBox="0 0 {width:.0f} {tall:.0f}" width="{width:.0f}" height="{tall:.0f}" '
-        f'style="--w:{width:.0f}px" role="img" aria-label="{_esc(block.title or "How the code fits together")}">'
-        f"{_g_captions(graph, xs, widths, column_of)}{edges}{nodes}{ports}{tips}</svg></div>"
-        f'<div class="cgk">{"".join(pills)}{hidden}{hint}</div></div>{"".join(panels.values())}</div>'
+        f'{title}<div class="cgw"{data}>{switches}<div class="cgb">{bar}'
+        f'<nav class="cgc" aria-label="Where this graph starts"></nav><div class="cg">{svg}</div>'
+        f'<div class="cgk">{legend}</div></div>{"".join(html for _, html in panels.values())}{"".join(views)}</div>'
+        f"{script}"
     )
 
 

code_node/report/style.py

@@ -125,6 +125,20 @@ _EXTRA_CSS = """\
 .cnd .cgfs:checked~.cgz-fit:checked~.cgb .cg svg{width:100%;height:100%;max-width:none}
 .cnd .cgfs:checked~.cgz-auto:checked~.cgb .cg svg{min-width:0}
 @media (min-width:1100px){.cnd .cgw:has(.cside:target) .cgfs:checked~.cgb{right:min(660px,94vw)}}
+.cnd .cgw:not(.js) :is(.oj,.dr),.cnd .cgw.js .nj{display:none}
+.cnd .cgta{padding:3px 10px;border:1px solid rgba(127,127,127,.28);border-radius:8px;color:inherit;text-decoration:none;opacity:.7}
+.cnd .cgta:hover{opacity:.95;background:rgba(127,127,127,.08)}
+.cnd .cgw[data-view$="-all"] .cgta{opacity:1;font-weight:650;background:rgba(127,127,127,.14)}
+.cnd .cgc{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 7px;margin:0 0 6px;font-size:13px}
+.cnd .cgc:empty{display:none}
+.cnd .cgc a{color:light-dark(#2563eb,#60a5fa);text-decoration:none}
+.cnd .cgc a:hover{text-decoration:underline}
+.cnd .cgc code{font-family:var(--mono);font-size:12.5px}
+.cnd .cgc .cgcs{opacity:.4}
+.cnd .cg .dr rect{fill:transparent;cursor:pointer}
+.cnd .cg .dr:hover rect{fill:rgba(37,99,235,.09)}
+.cnd .cg .dr:focus-visible{outline:2px solid light-dark(#2563eb,#60a5fa)}
+.cnd .cgw.js .cg .hd .md{fill:light-dark(#2563eb,#60a5fa);fill-opacity:1;font-style:normal}
 .cnd .cg .cap{font-size:12px;font-weight:650;letter-spacing:1.2px;fill:currentColor;fill-opacity:.6}
 .cnd .cg .capl{stroke:currentColor;stroke-opacity:.14;stroke-width:1;fill:none}
 .cnd .cg .cn,.cnd .cg .ce{transition:opacity .15s}

code_node/serve.py

@@ -3,8 +3,8 @@ code-node --serve: the page on a local server, made again whenever a .py file (o
 under the folder changes, and the browser told to reload (keeping its scroll position, and the tab and step that were
 open). Standard library only: a polling watcher thread, a threaded HTTP server, and Server-Sent Events for the reload.
 
-The saved pages have no JavaScript; the served one gets a few lines (_LIVE_SCRIPT) to reload and to say when the
-server has stopped.
+The served page gets a few lines more than a saved one (_LIVE_SCRIPT), to reload and to say when the server has
+stopped.
 """
 
 from __future__ import annotations

{code_node_graph-0.3.0.dist-info → code_node_graph-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-node-graph
-Version: 0.3.0
+Version: 0.4.0
 Summary: See how Python code works without running it: a graph of who calls whom from an entry point, and what each path reaches.
 Project-URL: Homepage, https://github.com/utkarsh5026/code-node
 Project-URL: Documentation, https://utkarsh5026.github.io/code-node/

{code_node_graph-0.3.0.dist-info → code_node_graph-0.4.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-code_node/__init__.py,sha256=RGdvFZ4nq5pe5UXLWQMZaZvneTOwgLS-aGK6TqTBTG4,1106
+code_node/__init__.py,sha256=hzITZuWbNbw6NyeHwo4MC9MApmpFcoJwdY43MsPrPQw,1106
 code_node/__main__.py,sha256=0W2bmerF1S96rjlTNJZKVzO4FvVhN6ENzAl451A08sQ,101
 code_node/cli.py,sha256=GI0vZY1t4Pf7qtZI2coTpWZi-ulQEWNREDJPkTtmxG0,12302
 code_node/pages.py,sha256=2UOrHUz3G_vAjPO89phJxhF4652FysVLgrLtJ-Iw6p4,3234
 code_node/project.py,sha256=1s6pBwQ-hiEf9v0YzE8b6TETT9E0XBnzQPWGjYDJsnw,16361
-code_node/serve.py,sha256=T09QSIuO1uR40xe9wD7btCroVFwEScZadfS71KZB_yQ,11468
+code_node/serve.py,sha256=4yvzDaaL1XpsVinLmvlm1W2bM6WJRGe5GI8wG3XuHic,11456
 code_node/analysis/__init__.py,sha256=-KM77rYv9pPutUG29DsU8ZkAUtr2AU9RsqrDPFAjLoQ,103
 code_node/analysis/aws_model.py,sha256=R2sHppdu9PmlsOGDXf6_6JHumbA5PqbiJ0JgnyB9Xcs,6648
 code_node/analysis/findings.py,sha256=S1-VQ1iNi1PkC-2eigNzbJrULa_2Y46avmtwAlV9iqU,19010
-code_node/analysis/graph.py,sha256=obWKdYHXGEe_yL6YZAAWq0BJ1bTG0oPv9TVYAABRkrU,33624
+code_node/analysis/graph.py,sha256=4FCzBo3G0XOkXV-zkshFxaoCalqWqbJfGDGDe-pg8S8,39373
 code_node/analysis/mapping.py,sha256=6wYkUqaQdM-Vio8XGf_Lw8N9dP_90YtbUxauH4IQ8Tg,5102
 code_node/analysis/model.py,sha256=ORGT6BEQFonQjdRGPEbuGVGoyyK54nTEA4Th-7rEGvU,13614
-code_node/analysis/reader.py,sha256=jVm4DSHlM9X7C2Rm1H7GpJ29_cXOSUNpr71Y1xZ35ws,88119
+code_node/analysis/reader.py,sha256=QIqVN2RV477ON69_5YVLXhfnfL3seS8kvP7krpmZPNI,89304
 code_node/analysis/syntax.py,sha256=wyeUr68IDjGp3i9HYYYzcjw8-CvL6a6mmZdWz5LY8j8,7952
 code_node/analysis/terms.py,sha256=ec0f51DkfDRixJSRX1hnyq9Hr5aLRhXuBRHlNJBlZD8,13782
 code_node/deploys/__init__.py,sha256=QEH2oQNPACPekg6QSBpfSbqkuhrdNDpelhn_VaY0RNs,11572
@@ -32,11 +32,11 @@ code_node/platforms/aws_lambda.py,sha256=IoYxJ2IPNkuxXMWSRK5mxaaDtmKQsyq7Q1EkXCp
 code_node/platforms/web.py,sha256=lNjwkz3D0zJkFcJhqD_ShcfTj4uF8miLNqKMtXu-t1U,11762
 code_node/report/__init__.py,sha256=l3dfZFbLEo-7Fl7O_Rk2lvyAElQnyugSZPI_PzHrG_Q,76
 code_node/report/brands.py,sha256=n32BfFz2d02ZVUHvy8L4wPHBtiD_1FCTKzdR4NyvU88,8372
-code_node/report/build.py,sha256=F0wdC0ibu3WSAenUsovUWuKwLC0vVxnNYKJVXtU5jRk,4644
+code_node/report/build.py,sha256=xnPK_6FMTSV2nyS-N6KcApdq3ZNBA_0Hy8AUZDVIea0,4884
 code_node/report/editor.py,sha256=TRUX6BTB-oe-m5Vf3xM9PppnC99sCLL4PObXkYAGKoU,1466
-code_node/report/graph.py,sha256=YbrVWbymYUL8-KOdsDSRhD2RxCMWbGVEhHD0-MSjX1I,66832
+code_node/report/graph.py,sha256=1SEMabLWWL9E0kwhKLYZhRFj0pRzLk4eDpHfLsxuuiQ,75162
 code_node/report/outline.py,sha256=3RRxU4FMUZKBVjFDsscKZkvDlj_W4ZeW4DwUztg4wd0,8539
-code_node/report/style.py,sha256=a5JesVQaDnqLqmqnuh-ZeayA-VZKTlUoDCPDcoUrK3M,35883
+code_node/report/style.py,sha256=YTQXlWjsnVfAZBhTr_Ot0PjdyLRSW83WDR3F02YBm4E,36833
 code_node/report/tabs.py,sha256=K2XR16owfgEL1kfux61PI9nBcRsgjQurTx1ptMM5Mac,3016
 code_node/report/walk.py,sha256=LWJDGJ3efF0fPWlMO4G4HBQqnNVn2RHXgLeuLrC-WnA,29466
 code_node/report/logos/README.md,sha256=8Evw8eApl_56QJrwY7LAtGgJMZE0mp0-HIpRz9bu1ME,613
@@ -171,8 +171,8 @@ code_node/report/logos/small/aws-systems-manager.svg,sha256=9VzzFdTjaRZO9ulR8Ulp
 code_node/report/logos/small/aws-timestream.svg,sha256=yKdKIj7pbooFqDKClEQxW9h7dYV5mnDn0RCHnLUDf8Q,639
 code_node/report/logos/small/aws-waf.svg,sha256=l9ZzBZAl2g8bK1-m6A50ga37l5g1t-9Mj70bxWDykWE,591
 code_node/report/logos/small/aws-xray.svg,sha256=VKg_QtKGZKDCbZvKBRDn7eReuNVbJpduBUVV8MQrZZU,591
-code_node_graph-0.3.0.dist-info/METADATA,sha256=N1ODeR5ZEpH4roWDSuYXxMNjQu_q31V2uCuYsQQyTig,7619
-code_node_graph-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-code_node_graph-0.3.0.dist-info/entry_points.txt,sha256=eEArp-uk7ZzODIWr6l62rI0-mIA0-mLDaqJEyKikPJw,49
-code_node_graph-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-code_node_graph-0.3.0.dist-info/RECORD,,
+code_node_graph-0.4.0.dist-info/METADATA,sha256=7tOOzTXKx0lvUJUZRXK4KfuWwvi_lz3RDPhnpnTn3aE,7619
+code_node_graph-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+code_node_graph-0.4.0.dist-info/entry_points.txt,sha256=eEArp-uk7ZzODIWr6l62rI0-mIA0-mLDaqJEyKikPJw,49
+code_node_graph-0.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+code_node_graph-0.4.0.dist-info/RECORD,,