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

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

@@ -4,6 +4,15 @@ 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.2.0] - 2026-10-20
+
+### Changed
+
+- Pointing at a box in the graph shows a card instead of the browser's plain tooltip: what kind of box it is and
+  its name, a function's `def` as written in colour with its docstring, a service's operations and the permissions
+  they need set as code, and its warnings in a block of their own. It sits under the box, over it or beside it,
+  wherever it fits, and zooms with the graph.
+
 ## [0.1.0] - 2026-10-20
 
 ### Added
@@ -153,5 +162,6 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/utkarsh5026/code-node/compare/v0.2.0...HEAD
+[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.1.0 → code_node_graph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-node-graph
-Version: 0.1.0
+Version: 0.2.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.1.0 → code_node_graph-0.2.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.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "CodeGraph",

{code_node_graph-0.1.0 → code_node_graph-0.2.0}/src/code_node/report/graph.py

@@ -13,8 +13,8 @@ from typing import Any, Callable
 
 from ..kit.blocks import _Report, _draws
 from ..kit.fmt import _plural
-from ..kit.highlight import _python_lines
-from ..kit.render import _prose
+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
@@ -1081,7 +1081,7 @@ def _node_svg(
         )
     classes = " ".join(["cn", f"k-{n.kind}", f"n-{n.id}", *(f"a-{m}" for m in neighbours)]) + (" warn" if warn else "")
     return (
-        f'<g class="{_esc(classes)}" transform="translate({x:.1f},{y:.1f})"><title>{_esc(n.tip or n.label)}</title>'
+        f'<g class="{_esc(classes)}" transform="translate({x:.1f},{y:.1f})">'
         f'<rect class="bg" width="{w:.0f}" height="{h:.0f}" rx="11"/>'
         f'<rect class="fg" x=".5" y=".5" width="{w - 1:.0f}" height="{h - 1:.0f}" rx="10.5"/>{"".join(parts)}</g>'
     )
@@ -1175,6 +1175,153 @@ def _g_panel(n: GraphNode, lines_of: Callable[[str], list[str]], editor: str = "
     )
 
 
+_G_TIP_W = 420  # a box's hover card, wide
+
+_G_TIP_SIGNATURE = 6  # lines of a def its hover card shows, at most
+
+_G_TIP_WARNING = "A warning is about it: "
+
+# a name in the card's sentences worth setting as code: a dotted or keyed path (Records[].s3.bucket.name,
+# book:{book_id}, s3:GetObject, orders/handler.py) or a variable in capitals (DB_HOST)
+_G_CODE_RE = re.compile(
+    r"(?<![\w.\-/])([A-Za-z_][\w\-]*(?:[.:/]+[\w{}\-]+|\[\]|\{\w*\})+|[A-Z][A-Z0-9]*_[A-Z0-9_]*[A-Z0-9])(?![\w{])"
+)
+
+
+def _g_tip_text(text: str) -> str:
+    """
+    One of the card's sentences as HTML, its calls coloured as Python and its names set as code, every piece escaped.
+    """
+    out = []
+    for i, piece in enumerate(_CALL_RE.split(text)):
+        if i % 2:
+            out.append(f'<code class="ctk">{_python_html(piece)}</code>')
+            continue
+        for k, part in enumerate(_G_CODE_RE.split(piece)):
+            out.append(f'<code class="ctk ctn">{_esc(part)}</code>' if k % 2 else _esc(part))
+    return "".join(out)
+
+
+def _g_tip_item(item: str) -> str:
+    """
+    One thing a service box lists, for its card: 'PutItem (dynamodb:PutItem)' as the operation in code and what it
+    needs beside it.
+    """
+    m = re.fullmatch(r"(.+?) \((.+)\)", item)
+    if not m:
+        return f'<li><code class="ctk ctn">{_esc(item)}</code></li>'
+    return (
+        f'<li><code class="ctk ctn">{_esc(m.group(1))}</code> <span class="ctm">{_g_tip_text(m.group(2))}</span></li>'
+    )
+
+
+def _g_tip_signature(n: GraphNode, lines_of: Callable[[str], list[str]]) -> list[str]:
+    """
+    A function's def as it's written, in colour: its decorators and the lines up to the colon that opens its body.
+    [] when its file wasn't read.
+    """
+    if not n.code:
+        return []
+    span = n.code[0]
+    lines = lines_of(span.file)
+    if not lines or span.start > len(lines):
+        return []
+    start = span.start
+    while start > 1 and lines[start - 2].lstrip().startswith("@"):
+        start -= 1
+    shown = []
+    for k in range(start, min(len(lines), span.end, start + _G_TIP_SIGNATURE - 1) + 1):
+        shown.append(lines[k - 1])
+        if k >= span.start and re.sub(r"<[^>]*>", "", lines[k - 1]).rstrip().endswith(":"):
+            break
+    indent = min((len(line) - len(line.lstrip(" ")) for line in shown if line.strip()), default=0)
+    return [line[indent:] for line in shown]
+
+
+def _g_tip(n: GraphNode, lines_of: Callable[[str], list[str]], opens: bool) -> tuple[str, float]:
+    """
+    What a box says on hover, as a card: what kind of box it is and its name, a function's def in colour and its
+    docstring, then the rest of its words with the code in them set as code, its warnings apart, and when it has a
+    panel (opens), that a click shows its code. With how tall it is likely to be, to pick whether it goes under the
+    box or over it.
+    """
+    said = [line for line in (n.tip or n.label).split("\n") if line]
+    warnings = [w for line in said if line.startswith(_G_TIP_WARNING) for w in line[len(_G_TIP_WARNING) :].split("; ")]
+    said = [line for line in said if not line.startswith(_G_TIP_WARNING)]
+    mono = n.kind in ("handler", "function")
+    body, tall, sub = [], 80.0 + (20 if n.sub else 0), n.sub
+    if mono and said and _CALL_RE.match(said[0]) and " in " in said[0]:  # 'name(args) in file, 3 lines: its doc'
+        head = said.pop(0)
+        signature = _g_tip_signature(n, lines_of) or [_python_html(head.split(" in ", 1)[0])]
+        body.append(f'<pre class="ctc">{chr(10).join(signature)}</pre>')
+        tall += 21 * len(signature) + 34
+        lines = re.search(r", (\d+ lines?)", head)
+        sub = f"{n.sub} · {lines.group(1)}" if lines and n.sub else sub
+        if n.lines and n.lines[0]:
+            body.append(f'<p class="ctd">{_g_tip_text(n.lines[0])}</p>')
+            tall += 23 * math.ceil(len(n.lines[0]) / 42) + 10
+    for line in said:
+        lead, _, rest = line.partition(": ")
+        if rest and lead == n.label:  # 'S3: GetObject (s3:GetObject), PutObject (s3:PutObject)': a list
+            items = rest.split(", ")
+            body.append(f'<ul class="ctl">{"".join(_g_tip_item(item) for item in items)}</ul>')
+            tall += 30 * len(items) + 8
+        else:
+            body.append(f'<p class="ctp">{_g_tip_text(line)}</p>')
+            tall += 23 * math.ceil(len(line) / 42) + 10
+    if warnings:
+        body.append(
+            '<div class="ctw"><b>Warning</b><ul>'
+            + "".join(f"<li>{_g_tip_text(w)}</li>" for w in warnings)
+            + "</ul></div>"
+        )
+        tall += 50 + sum(23 * math.ceil(len(w) / 36) + 4 for w in warnings)
+    kind = _G_PANEL_KINDS.get(n.kind, n.kind)
+    name = _python_html(n.label) if mono else _esc(n.label)
+    card = (
+        f'<div class="ctt k-{_esc(n.kind)}{" warn" if warnings else ""}"><div class="cth">'
+        f'<span class="ctkd">{_esc(kind)}</span><b class="ctn{" mono" if mono else ""}">{name}</b>'
+        + (f'<span class="cts{" mono" if mono else ""}">{_esc(sub)}</span>' if sub else "")
+        + f"</div>{''.join(body)}"
+        + ('<div class="cto">Click it to read its code</div>' if opens else "")
+        + "</div>"
+    )
+    return card, tall + (40 if opens else 0)
+
+
+def _g_tip_svg(
+    n: GraphNode,
+    box: tuple[float, float, float, float],
+    width: float,
+    tall: float,
+    lines_of: Callable[[str], list[str]],
+    opens: bool,
+) -> str:
+    """
+    A box's hover card, in the graph so it zooms with it: under the box when it fits there, else over it, else beside
+    it, and inside the graph from left to right. Hidden until the box is pointed at.
+    """
+    card, high = _g_tip(n, lines_of, opens)
+    x, y, w, h = box
+    card_w = min(_G_TIP_W, max(width - 16, 220))
+    left = max(8.0, min(x, width - card_w - 8))
+    below, above = tall - (y + h + 10) - 8, y - 10 - 8
+    if high <= below:
+        top, room, side = y + h + 10, below, "dn"
+    elif high <= above:
+        top, room, side = 8.0, above, "up"
+    else:  # beside the box, as high up as keeps all of it in the graph; over the box only when there's no room beside
+        if width - (x + w + 12) - 8 >= card_w:
+            left = x + w + 12
+        elif x - 12 - 8 >= card_w:
+            left = x - 12 - card_w
+        top, room, side = max(8.0, min(y, tall - high - 8)), high, "dn"
+    return (
+        f'<foreignObject class="ctip tp-{_esc(n.id)} {side}" x="{left:.0f}" y="{top:.0f}" width="{card_w:.0f}" '
+        f'height="{room:.0f}" aria-hidden="true"><div class="ctx">{card}</div></foreignObject>'
+    )
+
+
 def _g_captions(graph: CodeGraph, xs: dict[int, float], widths: dict[int, float], column_of: dict[str, int]) -> str:
     """
     The words over the columns: COMES IN, HANDLER, CALLS, REACHES, each over the columns it covers.
@@ -1256,6 +1403,7 @@ def _graph_html(block: _Graph, report: _Report) -> str:
     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}}")
+        report.rules.add(f".{root} .cg:has(.n-{n.id}:hover) .tp-{n.id}{{display:inline}}")
         report.rules.add(
             f".{root} .cg:has(.n-{n.id}:hover) :is(.s-{n.id},.t-{n.id}) .ln{{stroke-width:2.4;stroke-opacity:1}}"
         )
@@ -1307,6 +1455,7 @@ def _graph_html(block: _Graph, report: _Report) -> str:
         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])]
     )
+    tips = "".join(_g_tip_svg(n, boxes[n.id], width, tall, lines_of, bool(panels.get(n.id))) 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):
@@ -1362,7 +1511,7 @@ def _graph_html(block: _Graph, report: _Report) -> str:
         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}</svg></div>"
+        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>'
     )
 

{code_node_graph-0.1.0 → code_node_graph-0.2.0}/src/code_node/report/style.py

@@ -95,12 +95,12 @@ _EXTRA_CSS = """\
 .cnd .flow .oq{font-style:italic}
 .cnd .flow .os{display:inline-flex;flex-wrap:wrap;gap:3px 5px}
 .cnd .flow .ob{margin-left:22px}
-.cnd :is(.flow,.cside,.walk) .pk{color:var(--jp-mirror-editor-keyword-color,light-dark(#7c3aed,#c792ea))}
-.cnd :is(.flow,.cside,.walk) .pf{color:var(--jp-mirror-editor-def-color,light-dark(#2563eb,#82aaff))}
-.cnd :is(.flow,.cside,.walk) :is(.js,.jk){color:var(--jp-mirror-editor-string-color,light-dark(#047857,#a5d6a7))}
-.cnd :is(.flow,.cside,.walk) :is(.jn,.jl){color:var(--jp-mirror-editor-number-color,light-dark(#c2410c,#f78c6c))}
-.cnd :is(.flow,.cside,.walk) .pa{font-style:italic}
-.cnd :is(.flow,.cside,.walk) .pc{opacity:.6;font-style:italic}
+.cnd :is(.flow,.cside,.walk,.ctip) .pk{color:var(--jp-mirror-editor-keyword-color,light-dark(#7c3aed,#c792ea))}
+.cnd :is(.flow,.cside,.walk,.ctip) .pf{color:var(--jp-mirror-editor-def-color,light-dark(#2563eb,#82aaff))}
+.cnd :is(.flow,.cside,.walk,.ctip) :is(.js,.jk){color:var(--jp-mirror-editor-string-color,light-dark(#047857,#a5d6a7))}
+.cnd :is(.flow,.cside,.walk,.ctip) :is(.jn,.jl){color:var(--jp-mirror-editor-number-color,light-dark(#c2410c,#f78c6c))}
+.cnd :is(.flow,.cside,.walk,.ctip) .pa{font-style:italic}
+.cnd :is(.flow,.cside,.walk,.ctip) .pc{opacity:.6;font-style:italic}
 .cnd .cgb{width:fit-content;max-width:min(100%,1180px)}
 .cnd .cg{border:1px solid rgba(127,127,127,.2);border-radius:14px;margin:6px 0 8px;overflow:auto;background-color:rgba(127,127,127,.035);background-attachment:local;background-size:18px 18px;
  background-image:radial-gradient(circle at 1px 1px,rgba(127,127,127,.3) 1px,transparent 0);background-position:9px 9px}
@@ -221,6 +221,34 @@ _EXTRA_CSS = """\
 .cnd .cgk .kl path{fill:none;stroke:currentColor;stroke-opacity:.8;stroke-width:2.1;stroke-linecap:round;stroke-linejoin:round}
 .cnd .cg a.cl{cursor:pointer;outline:none}
 .cnd .cg a.cl:focus-visible .fg{stroke:light-dark(#2563eb,#60a5fa);stroke-opacity:1;stroke-width:2}
+.cnd .cg .ctip{display:none;overflow:visible;pointer-events:none}
+.cnd .cg .ctip .ctx{display:flex;flex-direction:column;height:100%}
+.cnd .cg .ctip.up .ctx{justify-content:flex-end}
+.cnd .cg .ctt{position:relative;box-sizing:border-box;padding:16px 18px;border:1px solid rgba(127,127,127,.3);border-radius:12px;background:var(--jp-layout-color0,var(--vscode-editor-background,Canvas));color:CanvasText;box-shadow:0 2px 6px rgba(15,23,42,.08),0 14px 34px rgba(15,23,42,.18);font-size:14px;line-height:1.6;text-align:left;animation:cnTip .14s ease-out .18s both}
+@keyframes cnTip{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}
+@media (prefers-reduced-motion:reduce){.cnd .cg .ctt{animation:none}}
+.cnd .cg .ctt.k-function,.cnd .cg .ctt.k-handler{--c:light-dark(#2563eb,#82aaff)}
+.cnd .cg .cth{display:flex;flex-direction:column;gap:3px;margin:0 0 14px}
+.cnd .cg .ctkd{font-size:10.5px;font-weight:650;letter-spacing:.08em;text-transform:uppercase;color:var(--c,currentColor);opacity:.9}
+.cnd .cg .ctt b.ctn{font-size:16px;font-weight:650;overflow-wrap:anywhere}
+.cnd .cg .ctt b.ctn.mono{font:650 15px var(--mono)}
+.cnd .cg .cts{font-size:12.5px;opacity:.65;overflow-wrap:anywhere}
+.cnd .cg .cts.mono{font-family:var(--mono)}
+.cnd .cg .ctt pre.ctc{margin:0 0 12px;padding:10px 12px;border:1px solid rgba(127,127,127,.2);border-radius:8px;background:rgba(127,127,127,.06);font:13px/1.55 var(--mono);white-space:pre-wrap;overflow-wrap:anywhere}
+.cnd .cg .cto{margin:16px -18px -16px;padding:9px 18px;border-top:1px solid rgba(127,127,127,.16);border-radius:0 0 12px 12px;background:rgba(127,127,127,.05);font-size:12px;opacity:.7}
+.cnd .cg .ctt p{margin:0 0 10px;overflow-wrap:anywhere}
+.cnd .cg .ctt p:last-child{margin-bottom:0}
+.cnd .cg .ctt p.ctd{font-style:italic;opacity:.85}
+.cnd .cg .ctt p.ctp{opacity:.88}
+.cnd .cg .ctt code.ctk{font:12.5px var(--mono);padding:1px 5px;border-radius:4px;background:rgba(127,127,127,.12);overflow-wrap:anywhere}
+.cnd .cg .ctt code.ctn{color:light-dark(#0f766e,#7dd3c0)}
+.cnd .cg .ctt ul{margin:0;padding:0;list-style:none}
+.cnd .cg .ctt ul.ctl li{display:flex;flex-wrap:wrap;align-items:baseline;gap:2px 10px;padding:6px 0;border-top:1px solid rgba(127,127,127,.14)}
+.cnd .cg .ctt ul.ctl li:first-child{border-top:none}
+.cnd .cg .ctt .ctm{font-size:12px;opacity:.7}
+.cnd .cg .ctt .ctw{margin:12px 0 0;padding:10px 14px;border-radius:8px;background:rgba(245,158,11,.12);border-left:3px solid #f59e0b}
+.cnd .cg .ctt .ctw b{display:block;margin:0 0 4px;font-size:10.5px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;color:light-dark(#b45309,#fbbf24)}
+.cnd .cg .ctt .ctw li{margin:4px 0 0;overflow-wrap:anywhere}
 .cnd .cside{position:fixed;top:0;right:0;bottom:0;z-index:30;box-sizing:border-box;width:min(660px,94vw);overflow:auto;padding:0 20px 28px;background:var(--jp-layout-color0,var(--vscode-editor-background,Canvas));color:CanvasText;border-left:1px solid rgba(127,127,127,.3);box-shadow:-14px 0 36px rgba(15,23,42,.14);transform:translateX(104%);visibility:hidden;transition:transform .22s ease,visibility 0s linear .22s}
 .cnd .cside:target{transform:none;visibility:visible;transition:transform .22s ease}
 .cnd .cside .csh{display:flex;align-items:flex-start;gap:12px;position:sticky;top:0;z-index:1;margin:0 -20px 12px;padding:16px 20px 12px;background:var(--jp-layout-color0,var(--vscode-editor-background,Canvas));border-bottom:1px solid rgba(127,127,127,.2)}

{code_node_graph-0.1.0 → code_node_graph-0.2.0}/tests/test_code_node.py

@@ -5,6 +5,7 @@ code-node end to end on small folders written into tmp_path: entry points found,
 from __future__ import annotations
 
 import os
+import re
 from pathlib import Path
 
 import pytest
@@ -525,6 +526,19 @@ def test_arrows_from_one_box_run_together_and_the_graph_zooms(tmp_path: Path) ->
     assert 'class="cgs cgfs" id="cn-graph0-full"' in page and ">Full screen<" in page and "<script" not in page
 
 
+def test_a_box_says_what_it_is_in_a_card_on_hover(tmp_path: Path) -> None:
+    write(tmp_path / "code", {"app.py": HANDLER})
+    out = tmp_path / "page.html"
+    assert main([str(tmp_path / "code"), "--no-open", "-o", str(out)]) == 0
+    page = out.read_text()
+    assert '<g class="cn ' in page and not re.search(r'<g class="cn [^>]*><title>', page)  # not the plain tooltip
+    assert '<foreignObject class="ctip tp-f0' in page and ":hover) .tp-f0{display:inline}" in page
+    # its def as written, in colour
+    assert (
+        '<pre class="ctc"><span class="pk">def</span> <span class="pf">lambda_handler</span>(event, context):' in page
+    )
+
+
 def test_line_links_open_the_editor(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     from code_node.report.editor import editor_link, open_at