asecli 0.6.2__py3-none-any.whl

asecli/core/layout_audit.py

@@ -0,0 +1,237 @@
+"""Versioned quality report for meticulous ASE graph layout."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Mapping
+
+from .comment_bounds import comment_containment_issues
+from .comment_metrics import WHITESPACE_ERROR, comment_layout_metrics, positioned_bounds
+from .local_vars import GET_LOCAL_VAR_TYPE, REGISTER_LOCAL_VAR_TYPE
+from .layout_graph import immediate_comment_owners
+from .layout_audit_geometry import (
+    balance_errors, branch_side_balance, horizontal_edge_ratio, node_overlaps,
+    sibling_order_violations, spine_horizontal_errors, stage_gap_violations,
+    stage_right_alignment, subtree_overlaps, wire_crossings,
+    wire_through_comment_titles, wire_through_nodes,
+)
+from .layout_audit_repeated import repeated_module_mismatches
+from .commentary import inspect_comment_groups
+from .meticulous_layout import Geometry, MeticulousLayoutPlan
+from .model import AseGraph
+from .wire_router import logical_wires, routed_wire_paths
+
+REPORT_SCHEMA = "asecli.graph-layout.v2"
+
+
+def audit_meticulous_layout(
+    graph: AseGraph,
+    geometry: Mapping[str, Geometry],
+    plan: MeticulousLayoutPlan,
+    *,
+    moved: int,
+    comment_purpose: list[dict] | None = None,
+) -> dict:
+    positions = plan.positions
+    _refresh_subtree_bounds(plan, geometry)
+    rects = {
+        node_id: (x, y, x + geometry[node_id].width, y + geometry[node_id].height)
+        for node_id, (x, y) in positions.items()
+        if node_id in geometry
+    }
+    node_overlap_items = node_overlaps(rects)
+    subtree_overlap_items = subtree_overlaps(plan)
+    balance = balance_errors(graph, plan, geometry)
+    stage_alignment = stage_right_alignment(graph, plan, geometry)
+    spine_alignment = spine_horizontal_errors(graph, plan, geometry)
+    side_balance = branch_side_balance(plan)
+    horizontal_ratio = horizontal_edge_ratio(graph, plan, geometry)
+    gap_violations = stage_gap_violations(graph, plan, geometry)
+    sibling_order = sibling_order_violations(graph, plan)
+    paths = routed_wire_paths(graph, geometry, positions, plan.wire_route_changes)
+    wire_through = wire_through_nodes(paths, rects)
+    wire_through += wire_through_comment_titles(graph, paths)
+    crossing_items = wire_crossings(paths)
+    live_bounds = positioned_bounds(geometry, positions)
+    comment_issues = comment_containment_issues(graph, live_bounds)
+    whitespace, outliers = comment_layout_metrics(graph, geometry, positions)
+    register_distance, get_distance = _local_var_distances(graph, rects)
+    remote_direct = _remote_direct_wires(graph, plan)
+    repeated = repeated_module_mismatches(graph, plan)
+    comment_preservation = _comment_preservation(graph, plan)
+    purpose = (
+        comment_purpose
+        if comment_purpose is not None
+        else _existing_comment_purpose(graph)
+    )
+
+    containment = [item for item in comment_issues if item["code"] == "COMMENT_MEMBER_OUTSIDE_FRAME"]
+    comment_overlap = [item for item in comment_issues if item["code"] == "COMMENT_GROUP_OVERLAP"]
+    hard_failures = []
+    hard_failures += _failure_codes("NODE_OVERLAP", node_overlap_items)
+    hard_failures += _failure_codes("SUBTREE_OVERLAP", subtree_overlap_items)
+    hard_failures += _failure_codes("STAGE_RIGHT_ALIGNMENT", stage_alignment)
+    hard_failures += _failure_codes("SPINE_HORIZONTAL", spine_alignment)
+    hard_failures += _failure_codes(
+        "BRANCH_SIDE_BALANCE", [item for item in side_balance if item["count_difference"] > 1],
+    )
+    hard_failures += _failure_codes("STAGE_GAP", gap_violations)
+    hard_failures += _failure_codes("SIBLING_ORDER", sibling_order)
+    hard_failures += _failure_codes("WIRE_THROUGH_NODE", wire_through)
+    hard_failures += _failure_codes("COMMENT_CONTAINMENT", containment)
+    hard_failures += _failure_codes("COMMENT_OVERLAP", comment_overlap)
+    hard_failures += _failure_codes(
+        "COMMENT_WHITESPACE", [item for item in whitespace if item["ratio"] > WHITESPACE_ERROR],
+    )
+    hard_failures += _failure_codes("COMMENT_PRESERVATION", comment_preservation["issues"])
+    hard_failures += _failure_codes(
+        "COMMENT_PURPOSE_UNRESOLVED", [item for item in purpose if item["status"] == "unresolved"],
+    )
+    report = {
+        "schema": REPORT_SCHEMA,
+        "status": "failed" if hard_failures else "passed",
+        "node_overlaps": node_overlap_items,
+        "subtree_balance_error": balance,
+        "stage_right_alignment": stage_alignment,
+        "spine_horizontal_error": spine_alignment,
+        "branch_side_balance": side_balance,
+        "horizontal_edge_ratio": horizontal_ratio,
+        "stage_gap_violations": gap_violations,
+        "sibling_order_violations": sibling_order,
+        "subtree_overlaps": subtree_overlap_items,
+        "wire_through_nodes": wire_through,
+        "wire_wire_crossings": {"count": len(crossing_items), "pairs": crossing_items[:100]},
+        "residual_wire_crossings": {"count": len(crossing_items), "pairs": crossing_items[:100]},
+        "comment_containment": containment,
+        "comment_overlap": comment_overlap,
+        "comment_whitespace_ratio": whitespace,
+        "comment_preservation": comment_preservation,
+        "comment_purpose": purpose,
+        "outlier_members": outliers,
+        "register_distance": register_distance,
+        "get_consumer_distance": get_distance,
+        "remote_direct_wires": remote_direct,
+        "repeated_module_mismatches": repeated,
+        "wire_route_changes": list(plan.wire_route_changes),
+        "layout_stability": {
+            "moved_nodes": moved,
+            "fingerprint": _fingerprint(positions),
+            "deterministic": True,
+        },
+        "hard_failures": hard_failures,
+        "visual_validation": "requires_editor_review" if not hard_failures else "blocked",
+    }
+    return report
+
+
+def _local_var_distances(graph, rects) -> tuple[list[dict], list[dict]]:
+    types = {node.node_id: node.type_name for node in graph.nodes}
+    register, get = [], []
+    for item in logical_wires(graph):
+        wire = item.wire
+        if wire.out_node not in rects or wire.in_node not in rects:
+            continue
+        distance = round(max(0.0, rects[wire.in_node][0] - rects[wire.out_node][2]), 3)
+        item = {"from": wire.out_node, "to": wire.in_node, "distance": distance,
+                "status": "passed" if 64.0 <= distance <= 160.0 else "warning"}
+        if types.get(wire.in_node) == REGISTER_LOCAL_VAR_TYPE:
+            register.append(item)
+        if types.get(wire.out_node) == GET_LOCAL_VAR_TYPE:
+            get.append(item)
+    return register, get
+
+
+def _refresh_subtree_bounds(plan, geometry) -> None:
+    for node_id in plan.children:
+        members, stack = {node_id}, list(plan.children.get(node_id, ()))
+        while stack:
+            child = stack.pop()
+            if child not in members:
+                members.add(child)
+                stack.extend(plan.children.get(child, ()))
+        rects = [
+            (
+                plan.positions[member][0], plan.positions[member][1],
+                plan.positions[member][0] + geometry[member].width,
+                plan.positions[member][1] + geometry[member].height,
+            )
+            for member in members if member in plan.positions and member in geometry
+        ]
+        plan.subtree_bounds[node_id] = (
+            min(rect[0] for rect in rects), min(rect[1] for rect in rects),
+            max(rect[2] for rect in rects), max(rect[3] for rect in rects),
+        )
+
+
+def _remote_direct_wires(graph, plan) -> list[dict]:
+    types = {node.node_id: node.type_name for node in graph.nodes}
+    owners = immediate_comment_owners(graph)
+    direct_wires = [
+        item.wire for item in logical_wires(graph)
+        if types.get(item.wire.out_node) != GET_LOCAL_VAR_TYPE
+        and types.get(item.wire.in_node) != REGISTER_LOCAL_VAR_TYPE
+    ]
+    consumer_groups: dict[str, set[str]] = {}
+    for wire in direct_wires:
+        owner = owners.get(wire.in_node)
+        if owner is not None:
+            consumer_groups.setdefault(wire.out_node, set()).add(owner)
+
+    result = []
+    for wire in direct_wires:
+        groups = consumer_groups.get(wire.out_node, set())
+        consumer_group = owners.get(wire.in_node)
+        producer_group = owners.get(wire.out_node)
+        if len(groups) < 2 or consumer_group is None:
+            continue
+        # Once two or more algorithm groups consume the source, it is a module
+        # interface. Local uses inside the producer's own group may stay direct;
+        # every other known group must consume it through a nearby Get.
+        if producer_group is not None and consumer_group == producer_group:
+            continue
+        result.append({
+            "from": wire.out_node,
+            "to": wire.in_node,
+            "stage_span": plan.depths.get(wire.out_node, 0) - plan.depths.get(wire.in_node, 0),
+            "producer_group": producer_group,
+            "consumer_group": consumer_group,
+            "consumer_groups": sorted(groups),
+            "reason": "consumed_by_multiple_groups",
+        })
+    return result
+
+
+def _comment_preservation(graph, plan) -> dict:
+    current = tuple(sorted(
+        (group["node_id"], tuple(group["members"]), group["color"])
+        for group in inspect_comment_groups(graph)
+    ))
+    expected = plan.comment_snapshot
+    issues = []
+    expected_by_id = {item[0]: item for item in expected}
+    current_by_id = {item[0]: item for item in current}
+    for comment_id in sorted(set(expected_by_id) | set(current_by_id)):
+        if comment_id not in current_by_id:
+            issues.append({"comment_id": comment_id, "code": "deleted"})
+        elif comment_id not in expected_by_id:
+            issues.append({"comment_id": comment_id, "code": "added"})
+        elif current_by_id[comment_id][1:] != expected_by_id[comment_id][1:]:
+            issues.append({"comment_id": comment_id, "code": "membership_or_color_changed"})
+    return {"status": "passed" if not issues else "failed", "issues": issues}
+
+
+def _existing_comment_purpose(graph) -> list[dict]:
+    return [
+        {"comment_id": group["node_id"], "status": "existing", "title": group["title"]}
+        for group in inspect_comment_groups(graph)
+    ]
+
+
+def _failure_codes(code: str, items: list) -> list[dict]:
+    return [{"code": code, "count": len(items)}] if items else []
+
+
+def _fingerprint(positions) -> str:
+    payload = json.dumps(sorted(positions.items()), separators=(",", ":"))
+    return hashlib.sha256(payload.encode()).hexdigest()

asecli/core/layout_audit_geometry.py

@@ -0,0 +1,247 @@
+"""Geometric hard gates for meticulous layout reports."""
+
+from __future__ import annotations
+
+from .commentary import _rect_overlap, inspect_comment_groups
+from .layout_graph import id_key, port_key
+from .wire_geometry import path_hits_rect, paths_cross, segment_hits_rect
+from .wire_router import logical_wires
+
+GRID_SIZE = 256.0
+
+
+def node_overlaps(rects) -> list[dict]:
+    issues = []
+    ids = sorted(rects, key=id_key)
+    for index, left in enumerate(ids):
+        for right in ids[index + 1:]:
+            overlap = _rect_overlap(rects[left], rects[right])
+            if overlap is not None:
+                issues.append({"node_ids": [left, right], "overlap": overlap})
+    return issues
+
+
+def subtree_overlaps(plan) -> list[dict]:
+    issues = []
+    for parent, children in plan.children.items():
+        for index, left in enumerate(children):
+            for right in children[index + 1:]:
+                overlap = _rect_overlap(plan.subtree_bounds[left], plan.subtree_bounds[right])
+                if overlap is not None:
+                    issues.append({"parent_id": parent, "child_ids": [left, right], "overlap": overlap})
+    return issues
+
+
+def balance_errors(graph, plan, geometry) -> list[dict]:
+    result = []
+    for parent, children in plan.children.items():
+        if not children:
+            continue
+        spine = plan.spine_child[parent]
+        index = children.index(spine)
+        upper = children[:index]
+        lower = children[index + 1:]
+        axis = _edge_y(graph, plan, geometry, spine, parent)[1]
+        upper_height = 0.0 if not upper else axis - min(plan.subtree_bounds[item][1] for item in upper)
+        lower_height = 0.0 if not lower else max(plan.subtree_bounds[item][3] for item in lower) - axis
+        result.append({
+            "node_id": parent,
+            "spine_child": spine,
+            "upper_height": round(max(0.0, upper_height), 3),
+            "lower_height": round(max(0.0, lower_height), 3),
+            "error": round(abs(upper_height - lower_height), 3),
+        })
+    return result
+
+
+def stage_right_alignment(graph, plan, geometry, *, tolerance: float = 8.0) -> list[dict]:
+    result = []
+    for parent, children in sorted(plan.children.items(), key=lambda item: id_key(item[0])):
+        if not children:
+            continue
+        expected = plan.stage_output_x[children[0]]
+        deviations = []
+        for child in children:
+            wire = _primary_wire(graph, child, parent)
+            actual = plan.positions[child][0] + geometry[child].output_ports[wire.out_port][0]
+            error = abs(actual - expected)
+            if error > tolerance:
+                deviations.append({"node_id": child, "error": round(error, 3)})
+        if deviations:
+            result.append({"parent_id": parent, "expected_x": expected, "nodes": deviations})
+    return result
+
+
+def spine_horizontal_errors(graph, plan, geometry, *, tolerance: float = 8.0) -> list[dict]:
+    issues = []
+    for child, out_port, parent, in_port in plan.horizontal_edges:
+        source_y = plan.positions[child][1] + geometry[child].output_ports[out_port][1]
+        target_y = plan.positions[parent][1] + geometry[parent].input_ports[in_port][1]
+        error = abs(source_y - target_y)
+        if error > tolerance:
+            issues.append({
+                "from": child, "to": parent,
+                "out_port": out_port, "in_port": in_port,
+                "error": round(error, 3),
+            })
+    return issues
+
+
+def branch_side_balance(plan) -> list[dict]:
+    result = []
+    for parent, children in plan.children.items():
+        if not children:
+            continue
+        spine = plan.spine_child[parent]
+        index = children.index(spine)
+        result.append({
+            "node_id": parent,
+            "spine_child": spine,
+            "upper_count": index,
+            "lower_count": len(children) - index - 1,
+            "count_difference": abs(index - (len(children) - index - 1)),
+        })
+    return result
+
+
+def horizontal_edge_ratio(graph, plan, geometry, *, tolerance: float = 8.0) -> dict:
+    total = horizontal = 0
+    for child, parent in plan.primary_parent.items():
+        wire = _primary_wire(graph, child, parent)
+        source_y, target_y = _edge_y(graph, plan, geometry, child, parent, wire=wire)
+        total += 1
+        horizontal += abs(source_y - target_y) <= tolerance
+    return {
+        "horizontal": horizontal,
+        "total": total,
+        "ratio": 1.0 if total == 0 else round(horizontal / total, 4),
+    }
+
+
+def stage_gap_violations(graph, plan, geometry, *, minimum: float = 64.0, maximum: float = 160.0) -> list[dict]:
+    issues = []
+    for child, parent in plan.primary_parent.items():
+        source_right = plan.positions[child][0] + geometry[child].width
+        target_left = plan.positions[parent][0]
+        gap = target_left - source_right
+        if gap < minimum or gap > maximum:
+            issues.append({
+                "from": child, "to": parent, "gap": round(gap, 3),
+                "minimum": minimum, "maximum": maximum,
+            })
+    return issues
+
+
+def sibling_order_violations(graph, plan) -> list[dict]:
+    wire_port = _wire_ports(graph)
+    issues = []
+    for parent, children in plan.children.items():
+        expected = sorted(children, key=lambda child: (port_key(wire_port[(child, parent)]), id_key(child)))
+        actual = sorted(children, key=lambda child: plan.subtree_bounds[child][1])
+        if expected != actual:
+            issues.append({"parent_id": parent, "expected": expected, "actual": actual})
+    return issues
+
+
+def wire_through_nodes(paths, rects) -> list[dict]:
+    issues = []
+    grid = {}
+    for node_id, rect in rects.items():
+        for cell in _rect_cells(rect):
+            grid.setdefault(cell, set()).add(node_id)
+    for wire, path in paths:
+        hit = set()
+        for left, right in zip(path, path[1:]):
+            segment_box = (min(left[0], right[0]), min(left[1], right[1]),
+                           max(left[0], right[0]), max(left[1], right[1]))
+            candidates = set()
+            for cell in _rect_cells(segment_box):
+                candidates.update(grid.get(cell, ()))
+            for node_id in candidates - hit - {wire.out_node, wire.in_node}:
+                if segment_hits_rect(left, right, rects[node_id]):
+                    hit.add(node_id)
+        issues.extend({"wire": wire_key(wire), "node_id": node_id} for node_id in sorted(hit, key=id_key))
+    return issues
+
+
+def wire_through_comment_titles(graph, paths) -> list[dict]:
+    issues = []
+    groups = {group["node_id"]: group for group in inspect_comment_groups(graph)}
+    related: dict[str, set[str]] = {}
+
+    def members(group_id):
+        if group_id not in related:
+            values = set(groups[group_id]["members"])
+            for member_id in tuple(values):
+                if member_id in groups:
+                    values.update(members(member_id))
+            related[group_id] = values
+        return related[group_id]
+
+    for group in groups.values():
+        x, y = group["position"]["x"], group["position"]["y"]
+        title_rect = (x, y, x + group["width"], y + 48.0)
+        for wire, path in paths:
+            if {wire.out_node, wire.in_node} & members(group["node_id"]):
+                continue
+            if _bounds_intersect(_path_bounds(path), title_rect) and path_hits_rect(path, title_rect):
+                issues.append({"wire": wire_key(wire), "comment_id": group["node_id"], "area": "title"})
+    return issues
+
+
+def wire_crossings(paths) -> list[list[str]]:
+    issues = []
+    boxed = [(wire, path, _path_bounds(path)) for wire, path in paths]
+    for index, (left_wire, left_path, left_box) in enumerate(boxed):
+        left_nodes = {left_wire.out_node, left_wire.in_node}
+        for right_wire, right_path, right_box in boxed[index + 1:]:
+            if (not left_nodes & {right_wire.out_node, right_wire.in_node}
+                    and _bounds_intersect(left_box, right_box)
+                    and paths_cross(left_path, right_path)):
+                issues.append([wire_key(left_wire), wire_key(right_wire)])
+    return issues
+
+
+def _wire_ports(graph):
+    result = {}
+    for wire in graph.wires:
+        key = (wire.out_node, wire.in_node)
+        if key not in result or port_key(wire.in_port) < port_key(result[key]):
+            result[key] = wire.in_port
+    return result
+
+
+def _primary_wire(graph, child, parent):
+    choices = [
+        item.wire for item in logical_wires(graph)
+        if item.wire.out_node == child and item.wire.in_node == parent
+    ]
+    if not choices:
+        raise ValueError(f"primary layout edge {child}->{parent} is missing")
+    return min(choices, key=lambda wire: (port_key(wire.in_port), port_key(wire.out_port)))
+
+
+def _edge_y(graph, plan, geometry, child, parent, *, wire=None):
+    wire = wire or _primary_wire(graph, child, parent)
+    return (
+        plan.positions[child][1] + geometry[child].output_ports[wire.out_port][1],
+        plan.positions[parent][1] + geometry[parent].input_ports[wire.in_port][1],
+    )
+
+
+def wire_key(wire) -> str:
+    return f"{wire.out_node}:{wire.out_port}->{wire.in_node}:{wire.in_port}"
+def _path_bounds(path):
+    return (
+        min(point[0] for point in path), min(point[1] for point in path),
+        max(point[0] for point in path), max(point[1] for point in path),
+    )
+
+
+def _bounds_intersect(left, right):
+    return not (left[2] < right[0] or right[2] < left[0] or left[3] < right[1] or right[3] < left[1])
+
+
+def _rect_cells(rect):
+    left, top, right, bottom = (int(value // GRID_SIZE) for value in rect)
+    return ((x, y) for x in range(left, right + 1) for y in range(top, bottom + 1))

asecli/core/layout_audit_repeated.py

@@ -0,0 +1,44 @@
+"""Repeated-subtree consistency diagnostics for meticulous layout."""
+
+TEMPLATE_TOLERANCE = 8.0
+
+
+def repeated_module_mismatches(graph, plan) -> list[dict]:
+    types = {node.node_id: node.type_name for node in graph.nodes}
+    signatures: dict[tuple, list[str]] = {}
+    for parent, children in plan.children.items():
+        if children:
+            signature = _tree_signature(parent, plan, types)
+            signatures.setdefault(signature, []).append(parent)
+    issues = []
+    for parents in signatures.values():
+        if len(parents) < 2:
+            continue
+        baseline = _relative_profile(parents[0], plan)
+        for parent in parents[1:]:
+            profile = _relative_profile(parent, plan)
+            if len(profile) != len(baseline) or any(
+                abs(a - b) > TEMPLATE_TOLERANCE for a, b in zip(profile, baseline)
+            ):
+                issues.append({"baseline": parents[0], "node_id": parent})
+    return issues
+
+
+def _relative_profile(parent, plan) -> tuple[float, ...]:
+    origin_x, origin_y = plan.positions[parent]
+    values = []
+    stack = [parent]
+    while stack:
+        node_id = stack.pop()
+        if node_id != parent:
+            x, y = plan.positions[node_id]
+            values.extend((round(x - origin_x, 3), round(y - origin_y, 3)))
+        stack.extend(reversed(plan.children[node_id]))
+    return tuple(values)
+
+
+def _tree_signature(node_id, plan, types):
+    return (
+        types[node_id],
+        tuple(_tree_signature(child, plan, types) for child in plan.children[node_id]),
+    )

asecli/core/layout_graph.py

@@ -0,0 +1,113 @@
+"""Shared graph and geometry helpers for meticulous layout."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from .commentary import inspect_comment_groups
+from .layout import MASTER_TYPES
+from .model import AseGraph, WireLine
+
+
+def graph_depths(ids: set[str], outgoing: Mapping[str, list[WireLine]]) -> dict[str, int]:
+    memo: dict[str, int] = {}
+    def visit(node_id: str) -> int:
+        if node_id not in memo:
+            consumers = [wire.in_node for wire in outgoing.get(node_id, [])]
+            memo[node_id] = 0 if not consumers else 1 + max(visit(item) for item in consumers)
+        return memo[node_id]
+    for node_id in sorted(ids, key=id_key):
+        visit(node_id)
+    return memo
+
+
+def reject_cycles(ids: set[str], outgoing: Mapping[str, list[WireLine]]) -> None:
+    state: dict[str, int] = {}
+    def visit(node_id: str) -> None:
+        if state.get(node_id) == 1:
+            raise ValueError(f"data-flow cycle detected at node {node_id}")
+        if state.get(node_id) == 2:
+            return
+        state[node_id] = 1
+        for wire in outgoing.get(node_id, []):
+            visit(wire.in_node)
+        state[node_id] = 2
+    for node_id in sorted(ids, key=id_key):
+        visit(node_id)
+
+
+def require_connected_ports(graph: AseGraph, geometry, ids: set[str]) -> None:
+    for wire in graph.wires:
+        if wire.out_node not in ids or wire.in_node not in ids:
+            continue
+        if wire.out_port not in geometry[wire.out_node].output_ports:
+            raise ValueError(f"editor geometry missing output port {wire.out_node}:{wire.out_port}")
+        if wire.in_port not in geometry[wire.in_node].input_ports:
+            raise ValueError(f"editor geometry missing input port {wire.in_node}:{wire.in_port}")
+
+
+def immediate_comment_owners(graph: AseGraph) -> dict[str, str]:
+    return {member: group["node_id"] for group in inspect_comment_groups(graph) for member in group["members"]}
+
+
+def sibling_gap(left: str, right: str, owners: Mapping[str, str], normal: float, module: float) -> float:
+    crosses_group = owners.get(left) != owners.get(right) and (owners.get(left) or owners.get(right))
+    return module if crosses_group else normal
+
+
+def alignment_offset(node_id, branch, primary_wire, geometry) -> float:
+    offsets = [geometry[node_id].input_ports[primary_wire[(child, node_id)].in_port][1] for child in branch]
+    return (min(offsets) + max(offsets)) / 2.0 if offsets else geometry[node_id].height / 2.0
+
+
+def descendants(node_id: str, children: Mapping[str, tuple[str, ...]]) -> set[str]:
+    result, stack = {node_id}, list(children[node_id])
+    while stack:
+        child = stack.pop()
+        if child not in result:
+            result.add(child)
+            stack.extend(children[child])
+    return result
+
+
+def node_rect(node_id: str, positions, geometry) -> tuple[float, float, float, float]:
+    x, y = positions[node_id]
+    return x, y, x + geometry[node_id].width, y + geometry[node_id].height
+
+
+def overlaps_with_gap(left, right, gap: float) -> bool:
+    return not (left[2] + gap <= right[0] or right[2] + gap <= left[0]
+                or left[3] + gap <= right[1] or right[3] + gap <= left[1])
+
+
+def node_position(node) -> tuple[float, float]:
+    if node is None:
+        raise ValueError("layout node not found")
+    try:
+        return tuple(float(value) for value in node.raw_fields[3].split(","))  # type: ignore[return-value]
+    except (IndexError, ValueError) as exc:
+        raise ValueError(f"node {node.node_id} has invalid x,y position") from exc
+
+
+def is_master(graph: AseGraph, node_id: str) -> bool:
+    node = graph.node_by_id(node_id)
+    return node is not None and node.type_name in MASTER_TYPES
+
+
+def has_incoming(graph: AseGraph, node_id: str) -> bool:
+    return any(wire.in_node == node_id for wire in graph.wires)
+
+
+def port_key(value: str) -> tuple[int, float | str]:
+    try:
+        return 0, float(value)
+    except ValueError:
+        return 1, value
+
+
+def id_key(value: str) -> tuple[int, int | str]:
+    return (0, int(value)) if value.lstrip("-").isdigit() else (1, value)
+
+
+def round_coord(value: float) -> float:
+    return round(value, 1)