coltrace 0.1.0.dev4__py3-none-any.whl

coltrace/exporters.py

@@ -0,0 +1,676 @@
+"""Validated JSON snapshots and self-contained, offline graph exports."""
+
+from __future__ import annotations
+
+import ast
+import html
+import json
+import textwrap
+import types
+import warnings
+from dataclasses import asdict, fields, is_dataclass
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal, get_args, get_origin, get_type_hints
+
+import networkx as nx
+
+from .graph import LineageGraph
+from .lineage_models import LineageReport
+from .models import Location
+from .visual_layout import layout_history
+
+
+def _decode(expected: Any, value: Any, where: str) -> Any:
+    origin = get_origin(expected)
+    if origin is Literal:
+        if value not in get_args(expected) or not isinstance(value, str):
+            raise ValueError(f"{where}: invalid enum value")
+        return value
+    if origin is types.UnionType:
+        for alternative in get_args(expected):
+            try:
+                return _decode(alternative, value, where)
+            except ValueError:
+                pass
+        raise ValueError(f"{where}: invalid value type")
+    if origin is tuple:
+        if not isinstance(value, list):
+            raise ValueError(f"{where}: expected an array")
+        item_type = get_args(expected)[0]
+        return tuple(_decode(item_type, item, f"{where}[{i}]") for i, item in enumerate(value))
+    if isinstance(expected, type) and is_dataclass(expected):
+        if not isinstance(value, dict):
+            raise ValueError(f"{where}: expected an object")
+        names = {field.name for field in fields(expected)}
+        if set(value) != names:
+            raise ValueError(f"{where}: missing or unexpected fields")
+        hints = get_type_hints(expected)
+        return expected(
+            **{key: _decode(hints[key], item, f"{where}.{key}") for key, item in value.items()}
+        )
+    if type(value) is not expected:
+        raise ValueError(f"{where}: expected {expected.__name__}")
+    return value
+
+
+def _relative_path(value: str) -> None:
+    if (
+        not value
+        or "\\" in value
+        or ":" in value
+        or "\x00" in value
+        or PurePosixPath(value).is_absolute()
+        or ".." in PurePosixPath(value).parts
+    ):
+        raise ValueError(f"Invalid project-relative path: {value!r}")
+
+
+def _location(value: Location) -> None:
+    _relative_path(value.path)
+    if value.line < 1 or value.column < 0:
+        raise ValueError("Invalid source location")
+    if value.end_line is not None and value.end_line < value.line:
+        raise ValueError("Invalid source end line")
+    if value.end_column is not None and value.end_column < 0:
+        raise ValueError("Invalid source end column")
+    if (value.end_line is None) != (value.end_column is None):
+        raise ValueError("Source end line and column must be supplied together")
+    if value.end_line == value.line and value.end_column is not None:
+        if value.end_column < value.column:
+            raise ValueError("Source end precedes source start")
+
+
+def _unique_ids(items: tuple[Any, ...], kind: str) -> set[str]:
+    ids = [item.id for item in items]
+    if any(not item or "\x00" in item for item in ids) or len(set(ids)) != len(ids):
+        raise ValueError(f"Empty or duplicate {kind} IDs")
+    return set(ids)
+
+
+def load_report(path: str | Path) -> LineageReport:
+    """Read a full snapshot, rejecting malformed facts and dangling edges.
+
+    This loads plain data only. Query exports deliberately have another
+    ``report_kind`` and cannot be mistaken for a complete project snapshot.
+    """
+    try:
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnicodeError) as error:
+        raise ValueError(f"Invalid JSON snapshot: {error}") from error
+    if not isinstance(data, dict):
+        raise ValueError("Snapshot must be an object")
+    if data.get("report_kind") != "column_lineage" or data.get("schema_version") not in {
+        "0.2",
+        "0.3",
+    }:
+        raise ValueError("Expected a column_lineage snapshot with schema_version 0.2 or 0.3")
+    legacy = data["schema_version"] == "0.2"
+    if legacy:
+        expected_fields = {field.name for field in fields(LineageReport)} - {"history"}
+        if set(data) != expected_fields:
+            raise ValueError("snapshot: missing or unexpected legacy fields")
+        data = {**data, "schema_version": "0.3", "history": []}
+        warnings.warn(
+            "Snapshot schema 0.2 has no recorded column history. Re-scan the project "
+            "to include sources, transformation steps, and uses.",
+            UserWarning,
+            stacklevel=2,
+        )
+    report: LineageReport = _decode(LineageReport, data, "snapshot")
+    frames = _unique_ids(report.dataframes, "DataFrame")
+    columns = _unique_ids(report.columns, "column")
+    operations = _unique_ids(report.operations, "operation")
+    history = _unique_ids(report.history, "history event")
+    if (
+        columns & operations
+        or frames & (columns | operations)
+        or history & (frames | columns | operations)
+    ):
+        raise ValueError("Node IDs must be unique across record types")
+    for file in report.files:
+        _relative_path(file.path)
+        if file.sha256 is not None and (
+            len(file.sha256) != 64 or any(char not in "0123456789abcdef" for char in file.sha256)
+        ):
+            raise ValueError("Invalid source sha256")
+    identities: set[tuple[str, str, int]] = set()
+    for column in report.columns:
+        if column.dataframe_id not in frames:
+            raise ValueError("Column references an unknown DataFrame")
+        if column.version < 0:
+            raise ValueError("Column version must be non-negative")
+        identity = (column.dataframe_id, column.name, column.version)
+        if identity in identities:
+            raise ValueError("Duplicate column version identity")
+        identities.add(identity)
+    for edge in report.edges:
+        if edge.kind == "read":
+            valid = edge.source in columns and edge.target in operations
+        else:
+            valid = edge.source in operations and edge.target in columns
+        if not valid:
+            raise ValueError("Invalid or dangling graph edge")
+    for consumption in report.consumptions:
+        if consumption.column_id not in columns:
+            raise ValueError("Consumption references an unknown column")
+    events = {event.id: event for event in report.history}
+    sequences: set[int] = set()
+    for event in report.history:
+        if event.sequence < 0 or event.sequence in sequences:
+            raise ValueError("History event sequence must be non-negative and unique")
+        sequences.add(event.sequence)
+        if any(frame not in frames for frame in event.dataframe_ids):
+            raise ValueError("History event references an unknown DataFrame")
+        if any(column not in columns for column in (*event.inputs, *event.outputs)):
+            raise ValueError("History event references an unknown column")
+        if any(parent not in history for parent in event.parents):
+            raise ValueError("History event references an unknown parent")
+        if any(events[parent].sequence >= event.sequence for parent in event.parents):
+            raise ValueError("History parents must precede their child events")
+    locations = (
+        [item.location for item in report.functions]
+        + [item.location for item in report.dataframes]
+        + [item.location for item in report.columns]
+        + [item.location for item in report.operations]
+        + [item.location for item in report.consumptions]
+        + [item.location for item in report.diagnostics]
+        + [item.location for item in report.history]
+    )
+    for location in locations:
+        _location(location)
+    return report
+
+
+def _destination(path: str | Path) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def export_json(
+    report: LineageReport,
+    path: str | Path,
+    *,
+    column_id: str | None = None,
+    direction: str = "both",
+    depth: int | None = None,
+    relation: str | None = None,
+    evidence: str = "all",
+) -> Path:
+    """Export a full snapshot, or an explicitly identified column query."""
+    if column_id is None:
+        if direction != "both" or depth is not None or relation is not None or evidence != "all":
+            raise ValueError("JSON query filters require a selected column")
+        content = report.to_json()
+    else:
+        query = LineageGraph(report).trace(
+            column_id, direction=direction, depth=depth, relation=relation, evidence=evidence
+        )
+        query.update(
+            report_kind="lineage_query",
+            schema_version=report.schema_version,
+            tool_version=report.tool_version,
+        )
+        content = json.dumps(query, ensure_ascii=False, sort_keys=True, indent=2)
+    target = _destination(path)
+    target.write_text(content + "\n", encoding="utf-8")
+    return target
+
+
+def export_html(
+    report: LineageReport,
+    path: str | Path,
+    *,
+    column_id: str | None = None,
+    direction: str = "both",
+    depth: int | None = None,
+    relation: str | None = None,
+    evidence: str = "all",
+    operations: bool = False,
+    view: str = "history",
+) -> Path:
+    """Render an offline graph. Install ``coltrace[viz]`` for this export."""
+    try:
+        from pyvis.network import Network  # type: ignore[import-untyped]
+    except ImportError as error:
+        raise ValueError("HTML export requires the extra: pip install 'coltrace[viz]'") from error
+    if view not in {"history", "columns"}:
+        raise ValueError("HTML view must be 'history' or 'columns'")
+    lineage = LineageGraph(report)
+    graph = lineage._filtered(relation, evidence)
+    query: dict[str, Any] | None = None
+    if column_id is None:
+        if depth is not None or direction != "both":
+            raise ValueError("Depth and direction require a selected column")
+        included = set(lineage.by_id)
+        diagnostics = [asdict(item) for item in report.diagnostics]
+    else:
+        query = lineage.trace(
+            column_id, direction=direction, depth=depth, relation=relation, evidence=evidence
+        )
+        diagnostics = query["diagnostics"]
+        included = {column_id}
+        for side in ("upstream", "downstream"):
+            for group in ("direct", "transitive"):
+                included.update(item["id"] for item in query[side][group])
+    projected = [
+        (source, target, data)
+        for source, target, data in graph.edges(data=True)
+        if source in included and target in included
+    ]
+    net = Network(height="100%", width="100%", directed=True, cdn_resources="in_line")
+    history = query.get("history", {}) if query is not None else {}
+    journey = query.get("journey", {}) if query is not None else {}
+    history_mode = bool(history.get("recorded") and view == "history" and not operations)
+    history_notice = ""
+    if column_id is not None and view == "history" and not operations and not history_mode:
+        history_notice = (
+            "This snapshot has no recorded column history. Re-scan the project to include "
+            "source expressions and transformation steps. Showing identified dependencies."
+        )
+    stages: list[dict[str, Any]] = []
+    if history_mode:
+        primary = {**history, "stages": journey.get("steps", history.get("stages", []))}
+        stages = _history_nodes(net, primary, column_id)
+        options = {
+            "interaction": {
+                "hover": True,
+                "keyboard": {"enabled": True, "bindToWindow": False},
+                "zoomSpeed": 0.7,
+            },
+            "layout": {"hierarchical": {"enabled": False}},
+            "physics": {"enabled": False},
+            "edges": {
+                "smooth": {"enabled": True, "type": "cubicBezier", "forceDirection": "vertical"},
+                "color": {"color": "#94a3b8", "highlight": "#0f766e"},
+                "width": 1.6,
+            },
+        }
+        return _write_html(
+            net,
+            report,
+            path,
+            diagnostics,
+            column_id,
+            options,
+            history_mode=True,
+            stages=stages,
+            history_notice="",
+            journey=journey,
+            creation_stages=history.get("stages", []),
+        )
+    for column in report.columns:
+        if column.id not in included:
+            continue
+        details = json.dumps(asdict(column), ensure_ascii=False, indent=2)
+        net.add_node(
+            column.id,
+            label=f"{column.name} · v{column.version}",
+            shape="box",
+            title=html.escape(f"{column.location.path}:{column.location.line} · {column.scope}"),
+            details=details,
+            color="#e2e8f0",
+            selected=column.id == column_id,
+        )
+    if operations:
+        operation_ids = {data["operation_id"] for _, _, data in projected}
+        visible_edges = set()
+        for source, target, data in projected:
+            visible_edges.add((source, data["operation_id"], "read"))
+            visible_edges.add((data["operation_id"], target, "write"))
+        by_operation = {operation.id: operation for operation in report.operations}
+        operations_with_reads = {edge.target for edge in report.edges if edge.kind == "read"}
+        # Only actual input-free writes lack a projection. Including all writes
+        # here would reintroduce relations excluded by confidence filters.
+        for edge in report.edges:
+            if edge.kind != "write" or edge.target not in included:
+                continue
+            if edge.source in operations_with_reads:
+                continue
+            operation = by_operation[edge.source]
+            kind = operation.kind if operation.kind in {"rename", "pass"} else "derive"
+            confirmed = all(
+                value == "confirmed"
+                for value in (
+                    edge.evidence,
+                    operation.evidence,
+                    lineage.by_id[edge.target].evidence,
+                )
+            )
+            if (relation is None or relation == kind) and (evidence == "all" or confirmed):
+                operation_ids.add(operation.id)
+                visible_edges.add((edge.source, edge.target, edge.kind))
+        for operation in report.operations:
+            if operation.id in operation_ids:
+                net.add_node(
+                    operation.id,
+                    label=operation.kind,
+                    shape="diamond",
+                    color="#cbd5e1",
+                    title=html.escape(
+                        f"{operation.location.path}:{operation.location.line} · {operation.scope}"
+                    ),
+                    details=json.dumps(asdict(operation), ensure_ascii=False, indent=2),
+                )
+        for edge in report.edges:
+            if (edge.source, edge.target, edge.kind) in visible_edges:
+                operation_id = edge.target if edge.kind == "read" else edge.source
+                endpoint = edge.source if edge.kind == "read" else edge.target
+                confirmed = all(
+                    value == "confirmed"
+                    for value in (
+                        edge.evidence,
+                        by_operation[operation_id].evidence,
+                        lineage.by_id[endpoint].evidence,
+                    )
+                )
+                net.add_edge(
+                    edge.source,
+                    edge.target,
+                    label=edge.kind,
+                    dashes=not confirmed,
+                    arrows="to",
+                )
+    else:
+        for source, target, data in projected:
+            net.add_edge(
+                source,
+                target,
+                label=data["kind"],
+                arrows="to",
+                title=html.escape(
+                    f"{data['location']['path']}:{data['location']['line']} · "
+                    f"{data['evidence']} · {data['completeness']}"
+                ),
+                dashes=data["evidence"] != "confirmed",
+            )
+    options = {
+        "interaction": {
+            "hover": True,
+            "keyboard": {"enabled": True, "bindToWindow": False},
+            "zoomSpeed": 0.7,
+        },
+        "layout": {"hierarchical": {"enabled": False}},
+        "physics": {"enabled": False},
+        "edges": {"smooth": {"enabled": True, "type": "cubicBezier", "forceDirection": "vertical"}},
+    }
+    return _write_html(
+        net,
+        report,
+        path,
+        diagnostics,
+        column_id,
+        options,
+        history_mode=False,
+        stages=stages,
+        history_notice=history_notice,
+        journey=journey,
+        creation_stages=[],
+    )
+
+
+def _callback_title(stage: dict[str, Any]) -> str:
+    """Keep argument-heavy expressions in the sidebar rather than the canvas."""
+    label = str(stage["label"])
+    if label.startswith("Type guard;"):
+        return "Validate input type"
+    if label.startswith("Return component"):
+        return f"{stage['label']}: {stage['expression']}"
+    target = label.partition(" = ")[0]
+    try:
+        expression = str(stage["expression"])
+        if len(expression) > 4096:
+            return target
+        root = ast.parse(expression, mode="eval")
+    except (SyntaxError, RecursionError):
+        return target
+    calls: list[str] = []
+
+    def visit(node: ast.AST) -> None:
+        for child in ast.iter_child_nodes(node):
+            visit(child)
+        if isinstance(node, ast.Call):
+            function = node.func
+            if isinstance(function, ast.Name):
+                calls.append(function.id)
+            elif isinstance(function, ast.Attribute):
+                owner = f"{function.value.id}." if isinstance(function.value, ast.Name) else ""
+                calls.append(owner + function.attr)
+
+    try:
+        visit(root)
+    except RecursionError:
+        return target
+    summary = " → ".join(dict.fromkeys(calls))
+    return f"{target}\n{summary}" if summary else label
+
+
+def _stage_title(stage: dict[str, Any], outputs: list[str]) -> str:
+    kind = stage["kind"]
+    label = str(stage["label"])
+    if stage.get("continuity") == "unresolved":
+        return "Later export\nColumn survival unverified"
+    if kind.startswith("callback_"):
+        return _callback_title(stage)
+    if kind == "source":
+        return label.removeprefix("Create DataFrame with ")
+    if kind == "external":
+        return "Input: " + ", ".join(outputs)
+    if kind == "bind":
+        return "Bind DataFrame: " + label.partition(" <- ")[0]
+    if kind == "call":
+        function = label.rsplit(".", 1)[-1]
+        return (
+            "Function template\n" if label.startswith("Analyze function") else "Call: "
+        ) + function
+    if kind == "return":
+        return "Return DataFrame" if stage["dataframe_ids"] else "Return values"
+    if kind in {"filter", "dropna", "projection"}:
+        if stage.get("relationship") == "projection_exclusion":
+            return "Exclude column from\nresulting DataFrame"
+        if stage.get("relationship") == "direct_read":
+            return "Read column\nto select rows"
+        if stage.get("relationship") == "frame_pass":
+            return "Carry column into\nresulting DataFrame"
+        return "Select columns" if kind == "projection" else "Filter rows\nPreserve retained values"
+    if kind in {"derive", "apply", "overwrite", "rename", "source"} and outputs:
+        verb = {"rename": "Rename", "overwrite": "Overwrite"}.get(kind, "Write")
+        return verb + ": " + ", ".join(outputs)
+    if kind == "boundary":
+        return (
+            "Unresolved origin: " + ", ".join(outputs)
+            if outputs
+            else "Lineage gap\nUnknown call or mutation"
+        )
+    if kind == "sink":
+        return "Export DataFrame"
+    return label
+
+
+def _history_nodes(
+    net: Any, history: dict[str, Any], column_id: str | None
+) -> list[dict[str, Any]]:
+    """Show recorded steps; raw column versions remain in the JSON facts."""
+    nodes = history.get("nodes", [])
+    names = {
+        node["id"]: f"{node['name']} · v{node['version']}"
+        for node in nodes
+        if node.get("node_type") == "column"
+    }
+    plain_names = {node["id"]: node["name"] for node in nodes if node.get("node_type") == "column"}
+    palette = {
+        "source": {"background": "#eff6ff", "border": "#90b3df"},
+        "transform": {"background": "#ffffff", "border": "#b8afd5"},
+        "use": {"background": "#eef8f4", "border": "#8cbfab"},
+        "boundary": {"background": "#fff8e8", "border": "#d7ae57"},
+        "frame": {"background": "#f0f6f9", "border": "#9fb5c5"},
+        "derivation": {"background": "#f5efff", "border": "#aa8bca"},
+        "control": {"background": "#f3f5f7", "border": "#a7b3bf"},
+        "configuration": {"background": "#f7f4ef", "border": "#beaf96"},
+        "context": {"background": "#f3f5f7", "border": "#a7b3bf"},
+    }
+    stages: list[dict[str, Any]] = []
+    remap: dict[str, str] = {}
+    for stage in history.get("stages", []):
+        for event_id in stage.get("event_ids", [stage["id"]]):
+            remap[event_id] = stage["id"]
+        for output in stage["outputs"]:
+            remap[output] = stage["id"]
+        inputs = list(dict.fromkeys(names[key] for key in stage["inputs"] if key in names))
+        outputs = list(dict.fromkeys(names[key] for key in stage["outputs"] if key in names))
+        flow = ""
+        if inputs or outputs:
+            flow = f"Columns: {', '.join(inputs) or '(source)'} → {', '.join(outputs) or '(use)'}"
+        stages.append({**stage, "column_flow": flow})
+        location = stage["location"]
+        category = stage["category"]
+        title = _stage_title(
+            stage, [plain_names[key] for key in stage["outputs"] if key in plain_names]
+        )
+        title_lines = [
+            line for part in title.splitlines() for line in textwrap.wrap(part, width=30)
+        ]
+        if len(title_lines) > 3:
+            title_lines = title_lines[:3]
+            title_lines[-1] = title_lines[-1][:27] + "..."
+        number = len(stages)
+        role = str(stage.get("relationship", category)).replace("_", " ")
+        label = f"{number:02d} · {role.upper()}\n" + "\n".join(title_lines)
+        label += f"\n{location['path'].rsplit('/', 1)[-1]}:{location['line']}"
+        details = (
+            f"{stage['label']}\n{location['path']}:{location['line']}\n"
+            f"{stage['module']}::{stage['scope']}\n\n{stage['expression']}\n\n{flow}\n"
+            f"{stage.get('explanation', '')}\n"
+            f"Evidence: {stage['evidence']}\nCompleteness: {stage['completeness']}"
+        )
+        color = (
+            palette["boundary"]
+            if stage.get("continuity") == "unresolved"
+            else palette.get(category, palette["context"])
+        )
+        net.add_node(
+            stage["id"],
+            label=label,
+            shape="box",
+            color={
+                **color,
+                "highlight": {"background": color["background"], "border": "#087f8c"},
+                "hover": {"background": color["background"], "border": "#087f8c"},
+            },
+            details=details,
+            category=category,
+            stage_number=number,
+            widthConstraint={"minimum": 280, "maximum": 280},
+            heightConstraint={"minimum": 110},
+            margin={"top": 20, "right": 22, "bottom": 20, "left": 22},
+            font={"size": 16, "face": "Segoe UI", "color": "#26354b", "align": "left"},
+            borderWidth=1.5,
+            borderWidthSelected=3,
+            shapeProperties={
+                "borderRadius": 8,
+                "borderDashes": category == "boundary" or stage.get("continuity") == "unresolved",
+            },
+            title=html.escape(f"{location['path']}:{location['line']} · {stage['scope']}"),
+            selected=column_id in stage["outputs"],
+        )
+    graph: nx.DiGraph[str] = nx.DiGraph()
+    visible_ids = {stage["id"] for stage in stages}
+    isolated = {stage["id"] for stage in stages if stage.get("continuity") == "unresolved"}
+    graph.add_nodes_from(visible_ids)
+    recorded: nx.DiGraph[str] = nx.DiGraph()
+    for edge in history.get("edges", []):
+        source = remap.get(edge["source"], edge["source"])
+        target = remap.get(edge["target"], edge["target"])
+        if source != target and source not in isolated and target not in isolated:
+            recorded.add_edge(source, target, **edge)
+    # Hidden callback preparation stays available in creation context. Compress
+    # its recorded causal paths; never connect blocks merely by source order.
+    for source in sorted(visible_ids - isolated):
+        pending = [(source, "confirmed", "step")]
+        visited = {source}
+        confidence_rank = {"confirmed": 0, "inferred": 1, "unresolved": 2}
+        while pending:
+            current, confidence, kind = pending.pop()
+            if current not in recorded:
+                continue
+            for target, attributes in recorded[current].items():
+                evidence = attributes.get("evidence", "confirmed")
+                combined = max(
+                    (confidence, evidence), key=lambda value: confidence_rank.get(value, 2)
+                )
+                edge_kind = attributes.get("kind", kind)
+                if target in visible_ids:
+                    if target != source:
+                        graph.add_edge(source, target, evidence=combined, kind=edge_kind)
+                elif target not in visited:
+                    visited.add(target)
+                    pending.append((target, combined, edge_kind))
+    # Remove visual shortcuts already explained by recorded step chains. No
+    # causal edge is inferred merely from the order of statements or lines.
+    visible = nx.transitive_reduction(graph) if nx.is_directed_acyclic_graph(graph) else graph
+    for source, target in visible.edges:
+        edge = graph[source][target]
+        net.add_edge(
+            source,
+            target,
+            arrows="to",
+            dashes=edge.get("evidence") != "confirmed" or edge.get("kind") == "supersedes",
+            title=html.escape(str(edge.get("kind", ""))),
+            label="supersedes (history only)" if edge.get("kind") == "supersedes" else "",
+        )
+    return stages
+
+
+def _write_html(
+    net: Any,
+    report: LineageReport,
+    path: str | Path,
+    diagnostics: list[dict[str, Any]],
+    column_id: str | None,
+    options: dict[str, Any],
+    *,
+    history_mode: bool,
+    stages: list[dict[str, Any]],
+    history_notice: str,
+    journey: dict[str, Any],
+    creation_stages: list[dict[str, Any]],
+) -> Path:
+    selected = next((column for column in report.columns if column.id == column_id), None)
+    selected_label = f"{selected.name} · {selected.module}::{selected.scope}" if selected else ""
+    positions = layout_history(net.nodes, net.edges)
+    for node in net.nodes:
+        node.update(positions[node["id"]])
+    net.set_options(json.dumps(options))
+    net.templateEnv.globals.update(
+        diagnostics=diagnostics,
+        filtered=column_id is not None,
+        history_mode=history_mode,
+        stages=stages,
+        journey=journey,
+        creation_stages=creation_stages,
+        history_notice=history_notice,
+        selected_label=selected_label,
+        selected_name=selected.name if selected else "Project dependencies",
+        selected_scope=f"{selected.module}::{selected.scope}"
+        if selected
+        else "All identified columns",
+        tool_version=report.tool_version,
+        column_notice=(
+            "Column provenance is unresolved. DataFrame source metadata is context, "
+            "not proof of this column's origin."
+        )
+        if selected is not None
+        and (
+            selected.origin == "opaque"
+            or selected.evidence == "unresolved"
+            or selected.completeness == "unresolved"
+        )
+        else "",
+    )
+    template = files("coltrace").joinpath("templates/graph.html").read_text(encoding="utf-8")
+    net.template = net.templateEnv.from_string(template)
+    content: str = net.generate_html(notebook=True)
+    output_path = _destination(path)
+    output_path.write_text(content, encoding="utf-8")
+    return output_path