code-node-graph 0.2.0__tar.gz → 0.4.0__tar.gz

{code_node_graph-0.2.0 → code_node_graph-0.4.0}/CHANGELOG.md

@@ -4,6 +4,37 @@ Every change a user would notice, newest first ([Keep a Changelog](https://keepa
 follow [Semantic Versioning](https://semver.org/); before 1.0, a minor version may change what a command does.
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-20
+
+### Fixed
+
+- Modules beside the entry point's file are read as its own code when it imports them by their own names, as a
+  Lambda function's folder does (`from helpers import x` in `src/app/handler.py`). They were taken for installed
+  libraries, so their functions, AWS calls and environment variables were missing, even when the folder is also a
+  package from the project's root.
+
+### Added
+
+- A box's "+12 calls not drawn" line opens them: click it and the graph starts from that function, with every call it
+  makes, a path above it back up to the whole graph, and the browser's Back button to return. **All** in the graph's
+  bar draws every function at once, for up to 150. This needs JavaScript; without it the page works as before.
+- A box's code panel closes when you click anywhere outside it, or press Escape, as well as with its ×. Clicking
+  another box still opens that one's code.
+
+### Changed
+
+- The graph says why functions are left out: too many to draw at once, or too deep, instead of always "too deep or
+  too many".
+
+## [0.3.0] - 2026-10-20
+
+### Changed
+
+- Step by step's list folds like a tree: the arrow beside a function, loop or branch hides the steps under it and
+  shows how many it hid. The tab also moves more: a new step's card comes in a line at a time, the lit row and its
+  number ease in, a dot pings when its step is reached, the code fades in when the walk goes into another function,
+  and the lit line glows as it lands. None of it moves for readers who ask for less motion.
+
 ## [0.2.0] - 2026-10-20
 
 ### Changed
@@ -162,6 +193,8 @@ follow [Semantic Versioning](https://semver.org/); before 1.0, a minor version m
 - `--platform NAME` runs a platform's checks whatever the entry point is; `--lambda` is short for
   `--platform lambda`. `EntryPoint.is_lambda` and `PageOptions.is_lambda` are now `platform` (`"lambda"` or `""`).
 
-[Unreleased]: https://github.com/utkarsh5026/code-node/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/utkarsh5026/code-node/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/utkarsh5026/code-node/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/utkarsh5026/code-node/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/utkarsh5026/code-node/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/utkarsh5026/code-node/releases/tag/v0.1.0

{code_node_graph-0.2.0 → code_node_graph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-node-graph
-Version: 0.2.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.2.0 → code_node_graph-0.4.0}/src/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.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "CodeGraph",

{code_node_graph-0.2.0 → code_node_graph-0.4.0}/src/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_graph-0.2.0 → code_node_graph-0.4.0}/src/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_graph-0.2.0 → code_node_graph-0.4.0}/src/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(),