flowgraph 0.1.2__py3-none-any.whl

flowgraph/application/workflow_history.py

@@ -0,0 +1,93 @@
+"""Snapshot-based undo and redo support for editable workflow graphs."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class WorkflowHistoryEntry:
+    """One reversible workflow edit represented by complete graph snapshots.
+
+    Parameters
+    ----------
+    label:
+        Short user-facing description of the recorded edit.
+    before:
+        JSON-compatible workflow state before the edit.
+    after:
+        JSON-compatible workflow state after the edit.
+    """
+
+    label: str
+    before: dict[str, Any]
+    after: dict[str, Any]
+
+
+class WorkflowHistory:
+    """Maintain a bounded linear undo/redo history for workflow snapshots."""
+
+    MAX_ENTRIES = 50
+
+    def __init__(self) -> None:
+        self._entries: list[WorkflowHistoryEntry] = []
+        self._index = 0
+
+    @property
+    def can_undo(self) -> bool:
+        """Return whether an earlier workflow state can be restored."""
+        return self._index > 0
+
+    @property
+    def can_redo(self) -> bool:
+        """Return whether an undone workflow state can be reapplied."""
+        return self._index < len(self._entries)
+
+    def clear(self) -> None:
+        """Discard all recorded states."""
+        self._entries.clear()
+        self._index = 0
+
+    def record(self, label: str, before: dict[str, Any], after: dict[str, Any]) -> bool:
+        """Record a changed workflow state and discard its obsolete redo branch.
+
+        Parameters
+        ----------
+        label:
+            Short description of the edit.
+        before:
+            JSON-compatible workflow state before the edit.
+        after:
+            JSON-compatible workflow state after the edit.
+
+        Returns
+        -------
+        bool
+            ``True`` when the states differed and an entry was recorded.
+        """
+        if before == after:
+            return False
+        self._entries[self._index :] = []
+        self._entries.append(WorkflowHistoryEntry(label, deepcopy(before), deepcopy(after)))
+        self._index += 1
+        if len(self._entries) > self.MAX_ENTRIES:
+            del self._entries[0]
+            self._index -= 1
+        return True
+
+    def undo(self) -> WorkflowHistoryEntry | None:
+        """Step backward and return the entry whose previous state should be restored."""
+        if not self.can_undo:
+            return None
+        self._index -= 1
+        return self._entries[self._index]
+
+    def redo(self) -> WorkflowHistoryEntry | None:
+        """Step forward and return the entry whose next state should be restored."""
+        if not self.can_redo:
+            return None
+        entry = self._entries[self._index]
+        self._index += 1
+        return entry

flowgraph/application/workflow_io.py

@@ -0,0 +1,393 @@
+"""Versioned JSON persistence and headless execution for FlowGraph workflows."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from flowgraph.application.workflow_core import (
+    NodeInstance,
+    NodeRegistry,
+    PortDirection,
+    WorkflowEdge,
+    WorkflowExecutor,
+    WorkflowGraph,
+    WorkflowPort,
+    WorkflowRunResult,
+    WorkflowValidationError,
+)
+from flowgraph.resources import package_resource_path
+
+WORKFLOW_FORMAT = "flowgraph-workflow"
+WORKFLOW_FORMAT_VERSION = 2
+LEGACY_WORKFLOW_FORMAT_VERSION = 1
+
+
+class WorkflowPersistenceError(ValueError):
+    """Raised when a workflow cannot be serialized or reconstructed safely."""
+
+
+def workflow_to_dict(workflow: WorkflowGraph) -> dict[str, Any]:
+    """Return the authoritative graph as a versioned JSON-compatible mapping."""
+    return _workflow_to_dict(workflow, set())
+
+
+def _workflow_to_dict(workflow: WorkflowGraph, ancestors: set[int]) -> dict[str, Any]:
+    """Serialize one workflow and its owned child workflows recursively."""
+    if id(workflow) in ancestors:
+        raise WorkflowPersistenceError("Workflow contains a recursive nested workflow")
+    ancestors = {*ancestors, id(workflow)}
+    testdata_root = package_resource_path("testdata").resolve()
+    payload = {
+        "format": WORKFLOW_FORMAT,
+        "version": WORKFLOW_FORMAT_VERSION,
+        "nodes": [
+            {
+                "id": node.id,
+                "definition_id": node.definition_id,
+                "parameters": {
+                    name: _serialize_testdata_value(value, testdata_root)
+                    for name, value in node.parameters.items()
+                },
+                "position": {"x": node.x, "y": node.y},
+                **(
+                    {"subworkflow": _workflow_to_dict(node.subworkflow, ancestors)}
+                    if node.subworkflow is not None
+                    else {}
+                ),
+            }
+            for node in workflow.nodes
+        ],
+        "inputs": [
+            {"name": p.name, "node_id": p.node_id, "node_port": p.node_port}
+            for p in workflow.inputs
+        ],
+        "outputs": [
+            {"name": p.name, "node_id": p.node_id, "node_port": p.node_port}
+            for p in workflow.outputs
+        ],
+        "edges": [
+            {
+                "source_node": edge.source_node,
+                "source_port": edge.source_port,
+                "target_node": edge.target_node,
+                "target_port": edge.target_port,
+            }
+            for edge in workflow.edges
+        ],
+    }
+    try:
+        json.dumps(payload)
+    except (TypeError, ValueError) as error:
+        raise WorkflowPersistenceError(
+            f"Workflow contains parameters that cannot be represented as JSON: {error}"
+        ) from error
+    return payload
+
+
+def workflow_from_dict(payload: Mapping[str, Any], registry: NodeRegistry) -> WorkflowGraph:
+    """Validate and reconstruct an authoritative graph from persisted data."""
+    if not isinstance(payload, Mapping):
+        raise WorkflowPersistenceError("Workflow JSON root must be an object")
+    if payload.get("format") != WORKFLOW_FORMAT:
+        raise WorkflowPersistenceError(
+            f"Unsupported workflow format {payload.get('format')!r}; expected {WORKFLOW_FORMAT!r}"
+        )
+    version = payload.get("version")
+    if version not in {LEGACY_WORKFLOW_FORMAT_VERSION, WORKFLOW_FORMAT_VERSION}:
+        raise WorkflowPersistenceError(
+            f"Unsupported workflow version {payload.get('version')!r}; "
+            f"expected {LEGACY_WORKFLOW_FORMAT_VERSION} or {WORKFLOW_FORMAT_VERSION}"
+        )
+
+    nodes_payload = payload.get("nodes")
+    edges_payload = payload.get("edges")
+    if not isinstance(nodes_payload, list):
+        raise WorkflowPersistenceError("Workflow 'nodes' must be an array")
+    if not isinstance(edges_payload, list):
+        raise WorkflowPersistenceError("Workflow 'edges' must be an array")
+
+    payload = _resolve_testdata_paths(payload)
+    nodes_payload = payload["nodes"]
+    graph = WorkflowGraph()
+    for index, raw_node in enumerate(nodes_payload):
+        node = _parse_node(raw_node, index, registry, version=version)
+        try:
+            graph.add_node(node)
+        except ValueError as error:
+            raise WorkflowPersistenceError(str(error)) from error
+
+    for index, raw_edge in enumerate(edges_payload):
+        edge = _parse_edge(raw_edge, index)
+        try:
+            graph.add_edge(edge, registry)
+        except WorkflowValidationError as error:
+            raise WorkflowPersistenceError(f"Invalid edge at index {index}: {error}") from error
+    for index, raw_port in enumerate(payload.get("inputs", [])):
+        port = _parse_workflow_port(raw_port, index, graph, registry, "input")
+        try:
+            graph.export_input(port.name, port.node_id, port.node_port, registry, label=port.label)
+        except (ValueError, WorkflowValidationError) as error:
+            raise WorkflowPersistenceError(
+                f"Invalid workflow input at index {index}: {error}"
+            ) from error
+    for index, raw_port in enumerate(payload.get("outputs", [])):
+        port = _parse_workflow_port(raw_port, index, graph, registry, "output")
+        try:
+            graph.export_output(port.name, port.node_id, port.node_port, registry, label=port.label)
+        except (ValueError, WorkflowValidationError) as error:
+            raise WorkflowPersistenceError(
+                f"Invalid workflow output at index {index}: {error}"
+            ) from error
+    try:
+        graph.sync_boundary_nodes(registry)
+    except (ValueError, WorkflowValidationError) as error:
+        raise WorkflowPersistenceError(f"Invalid workflow boundary node: {error}") from error
+    return graph
+
+
+def save_workflow(workflow: WorkflowGraph, path: str | Path) -> Path:
+    """Write a workflow to deterministic, human-readable JSON."""
+    destination = Path(path).expanduser()
+    if not destination.parent.is_dir():
+        raise WorkflowPersistenceError(
+            f"Workflow output directory does not exist: {destination.parent}"
+        )
+    payload = workflow_to_dict(workflow)
+    try:
+        destination.write_text(
+            json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+    except OSError as error:
+        raise WorkflowPersistenceError(
+            f"Could not save workflow to '{destination}': {error}"
+        ) from error
+    return destination.resolve()
+
+
+def load_workflow(path: str | Path, registry: NodeRegistry) -> WorkflowGraph:
+    """Load and validate a workflow JSON file against the available node registry."""
+    source = Path(path).expanduser()
+    try:
+        content = source.read_text(encoding="utf-8")
+    except OSError as error:
+        raise WorkflowPersistenceError(
+            f"Could not read workflow from '{source}': {error}"
+        ) from error
+    return workflow_from_json(content, registry, source_name=str(source))
+
+
+def workflow_from_json(
+    content: str, registry: NodeRegistry, *, source_name: str = "workflow"
+) -> WorkflowGraph:
+    """Parse and validate workflow JSON received without a filesystem path."""
+    if not isinstance(content, str):
+        raise WorkflowPersistenceError("Workflow JSON content must be text")
+    try:
+        payload = json.loads(content)
+    except json.JSONDecodeError as error:
+        raise WorkflowPersistenceError(
+            f"Workflow file '{source_name}' is not valid JSON: {error}"
+        ) from error
+    return workflow_from_dict(payload, registry)
+
+
+def execute_workflow_file(
+    path: str | Path,
+    parameter_overrides: Mapping[str, Mapping[str, Any]] | None = None,
+    *,
+    registry: NodeRegistry | None = None,
+) -> WorkflowRunResult:
+    """Load and execute a workflow, optionally overriding parameters by node ID."""
+    if registry is None:
+        from flowgraph.application.node_registry import create_node_registry
+
+        registry = create_node_registry()
+    workflow = load_workflow(path, registry)
+    _apply_parameter_overrides(workflow, parameter_overrides or {})
+    return WorkflowExecutor(registry).run(workflow)
+
+
+def execute_workflow(
+    workflow: WorkflowGraph,
+    registry: NodeRegistry,
+    parameter_overrides: Mapping[str, Mapping[str, Any]] | None = None,
+) -> WorkflowRunResult:
+    """execute a workflow, optionally overriding parameters by node ID."""
+    _apply_parameter_overrides(workflow, parameter_overrides or {})
+    return WorkflowExecutor(registry).run(workflow)
+
+
+def _parse_node(
+    raw_node: object,
+    index: int,
+    registry: NodeRegistry,
+    *,
+    version: object,
+) -> NodeInstance:
+    if not isinstance(raw_node, Mapping):
+        raise WorkflowPersistenceError(f"Node at index {index} must be an object")
+    node_id = _required_string(raw_node, "id", f"node at index {index}")
+    definition_id = _required_string(raw_node, "definition_id", f"node {node_id!r}")
+    if registry.get(definition_id) is None:
+        raise WorkflowPersistenceError(
+            f"Node {node_id!r} uses unknown definition {definition_id!r}"
+        )
+    parameters = raw_node.get("parameters", {})
+    if not isinstance(parameters, Mapping) or not all(isinstance(name, str) for name in parameters):
+        raise WorkflowPersistenceError(
+            f"Parameters for node {node_id!r} must be an object with string keys"
+        )
+    position = raw_node.get("position", {})
+    if not isinstance(position, Mapping):
+        raise WorkflowPersistenceError(f"Position for node {node_id!r} must be an object")
+    x = _coordinate(position.get("x", 0), node_id, "x")
+    y = _coordinate(position.get("y", 0), node_id, "y")
+    subworkflow_payload = raw_node.get("subworkflow")
+    subworkflow: WorkflowGraph | None = None
+    if subworkflow_payload is not None:
+        if not isinstance(subworkflow_payload, Mapping):
+            raise WorkflowPersistenceError(f"Subworkflow for node {node_id!r} must be an object")
+        subworkflow = workflow_from_dict(subworkflow_payload, registry)
+    elif definition_id == "run-workflow" and version == LEGACY_WORKFLOW_FORMAT_VERSION:
+        legacy_content = parameters.get("workflow")
+        if isinstance(legacy_content, str) and legacy_content.strip():
+            subworkflow = workflow_from_json(
+                legacy_content,
+                registry,
+                source_name=f"legacy nested workflow in node {node_id!r}",
+            )
+        parameters = {name: value for name, value in parameters.items() if name != "workflow"}
+    elif (definition := registry.get(definition_id)) is not None and definition.subworkflow_factory:
+        subworkflow = definition.subworkflow_factory()
+    return NodeInstance(node_id, definition_id, deepcopy(dict(parameters)), x, y, subworkflow)
+
+
+def _resolve_testdata_paths(payload: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Resolve the portable ``{testdata}`` token in persisted string values.
+
+    The token is intentionally expanded while loading rather than while saving:
+    workflow JSON remains portable and can still be edited or shared, while
+    packaged demo workflows refer to the test data installed with FlowGraph.
+    """
+    testdata_root = package_resource_path("testdata")
+    resolved = deepcopy(dict(payload))
+    nodes = resolved.get("nodes")
+    if not isinstance(nodes, list):
+        return resolved
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        parameters = node.get("parameters")
+        if isinstance(parameters, dict):
+            node["parameters"] = {
+                name: _resolve_testdata_value(value, testdata_root)
+                for name, value in parameters.items()
+            }
+        subworkflow = node.get("subworkflow")
+        if isinstance(subworkflow, Mapping):
+            node["subworkflow"] = _resolve_testdata_paths(subworkflow)
+    return resolved
+
+
+def _resolve_testdata_value(value: Any, testdata_root: Path) -> Any:
+    """Recursively resolve ``{testdata}`` in JSON-compatible parameter values."""
+    if isinstance(value, str) and value.startswith("{testdata}"):
+        suffix = value[len("{testdata}") :].lstrip("/\\")
+        return str(testdata_root / Path(suffix))
+    if isinstance(value, list):
+        return [_resolve_testdata_value(item, testdata_root) for item in value]
+    if isinstance(value, dict):
+        return {key: _resolve_testdata_value(item, testdata_root) for key, item in value.items()}
+    return value
+
+
+def _serialize_testdata_value(value: Any, testdata_root: Path) -> Any:
+    """Replace packaged testdata paths with the portable ``{testdata}`` token."""
+    if isinstance(value, str):
+        path = Path(value).expanduser()
+        try:
+            relative = path.resolve().relative_to(testdata_root)
+        except (OSError, ValueError):
+            return value
+        return "{testdata}/" + relative.as_posix()
+    if isinstance(value, list):
+        return [_serialize_testdata_value(item, testdata_root) for item in value]
+    if isinstance(value, dict):
+        return {key: _serialize_testdata_value(item, testdata_root) for key, item in value.items()}
+    return value
+
+
+def _parse_workflow_port(
+    raw_port: object, index: int, graph: WorkflowGraph, registry: NodeRegistry, direction: str
+) -> WorkflowPort:
+    if not isinstance(raw_port, Mapping):
+        raise WorkflowPersistenceError(f"Workflow {direction} at index {index} must be an object")
+    name = _required_string(raw_port, "name", f"workflow {direction} at index {index}")
+    node_id = _required_string(raw_port, "node_id", f"workflow {direction} {name!r}")
+    node_port = _required_string(raw_port, "node_port", f"workflow {direction} {name!r}")
+    node = graph.require_node(node_id)
+    definition = registry.require(node.definition_id)
+    port = (
+        definition.input_for_instance(node_port, node)
+        if direction == "input"
+        else definition.output_for_instance(node_port, node)
+    )
+    if port is None:
+        raise WorkflowPersistenceError(
+            f"Workflow {direction} {name!r} references unknown port {node_id!r}.{node_port!r}"
+        )
+    workflow_direction = PortDirection.INPUT if direction == "input" else PortDirection.OUTPUT
+    return WorkflowPort(
+        name, node_id, node_port, workflow_direction, port.data_type, None, port.is_param
+    )
+
+
+def _parse_edge(raw_edge: object, index: int) -> WorkflowEdge:
+    if not isinstance(raw_edge, Mapping):
+        raise WorkflowPersistenceError(f"Edge at index {index} must be an object")
+    context = f"edge at index {index}"
+    return WorkflowEdge(
+        _required_string(raw_edge, "source_node", context),
+        _required_string(raw_edge, "source_port", context),
+        _required_string(raw_edge, "target_node", context),
+        _required_string(raw_edge, "target_port", context),
+    )
+
+
+def _required_string(payload: Mapping[str, Any], key: str, context: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value:
+        raise WorkflowPersistenceError(f"{context.capitalize()} requires non-empty string {key!r}")
+    return value
+
+
+def _coordinate(value: object, node_id: str, axis: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise WorkflowPersistenceError(f"Position {axis!r} for node {node_id!r} must be a number")
+    return value
+
+
+def _apply_parameter_overrides(
+    workflow: WorkflowGraph, overrides: Mapping[str, Mapping[str, Any]]
+) -> None:
+    if not isinstance(overrides, Mapping):
+        raise WorkflowPersistenceError("Parameter overrides must be a mapping by node ID")
+    for node_id, parameters in overrides.items():
+        if not isinstance(node_id, str):
+            raise WorkflowPersistenceError("Parameter override node IDs must be strings")
+        node = workflow.get_node(node_id)
+        if node is None:
+            raise WorkflowPersistenceError(
+                f"Parameter overrides reference unknown node {node_id!r}"
+            )
+        if not isinstance(parameters, Mapping) or not all(
+            isinstance(name, str) for name in parameters
+        ):
+            raise WorkflowPersistenceError(
+                f"Parameter overrides for node {node_id!r} must be a mapping with string keys"
+            )
+        node.parameters.update(deepcopy(dict(parameters)))

flowgraph/application/workflow_layout.py

@@ -0,0 +1,170 @@
+"""Deterministic layout helpers for directed workflow graphs."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from flowgraph.application.workflow_core import WorkflowGraph
+
+WORKFLOW_LAYER_SPACING = 360.0
+"""Horizontal distance between successive dependency layers in pixels."""
+
+WORKFLOW_NODE_SPACING = 180.0
+"""Vertical distance between nodes in one dependency layer in pixels."""
+
+
+def organize_workflow_nodes(
+    workflow: WorkflowGraph,
+    *,
+    layer_spacing: float = WORKFLOW_LAYER_SPACING,
+    node_spacing: float = WORKFLOW_NODE_SPACING,
+) -> dict[str, tuple[float, float]]:
+    """Return stable left-to-right positions for every node in a workflow.
+
+    Nodes occupy a layer one greater than the deepest upstream dependency. The
+    layout explicitly detects crossing edges and deterministically swaps pairs
+    of nodes in one layer when a permutation reduces the total crossing count.
+    Every layer starts at the same vertical origin, producing a regular grid.
+
+    Parameters
+    ----------
+    workflow:
+        Authoritative workflow graph to arrange.
+    layer_spacing:
+        Horizontal distance in pixels between dependency layers.
+    node_spacing:
+        Vertical distance in pixels between sibling nodes.
+
+    Returns
+    -------
+    dict[str, tuple[float, float]]
+        Positions keyed by node ID. An empty graph produces an empty mapping.
+    """
+    if layer_spacing <= 0 or node_spacing <= 0:
+        raise ValueError("Workflow layout spacing must be positive")
+
+    node_ids = sorted(node.id for node in workflow.nodes)
+    predecessors: dict[str, set[str]] = {node_id: set() for node_id in node_ids}
+    successors: dict[str, set[str]] = {node_id: set() for node_id in node_ids}
+    for edge in workflow.edges:
+        predecessors[edge.target_node].add(edge.source_node)
+        successors[edge.source_node].add(edge.target_node)
+
+    remaining_predecessors = {node_id: set(values) for node_id, values in predecessors.items()}
+    ready = sorted(node_id for node_id, values in remaining_predecessors.items() if not values)
+    layers: dict[str, int] = {node_id: 0 for node_id in ready}
+    ordered_node_ids: list[str] = []
+    while ready:
+        node_id = ready.pop(0)
+        ordered_node_ids.append(node_id)
+        for successor_id in sorted(successors[node_id]):
+            layers[successor_id] = max(layers.get(successor_id, 0), layers[node_id] + 1)
+            remaining_predecessors[successor_id].discard(node_id)
+            if not remaining_predecessors[successor_id]:
+                ready.append(successor_id)
+        ready.sort()
+
+    if len(ordered_node_ids) != len(node_ids):
+        raise ValueError("Workflow layout requires an acyclic graph")
+
+    nodes_by_layer: dict[int, list[str]] = defaultdict(list)
+    for node_id in ordered_node_ids:
+        nodes_by_layer[layers[node_id]].append(node_id)
+
+    for layer_node_ids in nodes_by_layer.values():
+        layer_node_ids.sort()
+    _reduce_edge_crossings(nodes_by_layer, workflow)
+
+    positions: dict[str, tuple[float, float]] = {}
+    for layer, layer_node_ids in nodes_by_layer.items():
+        for index, node_id in enumerate(layer_node_ids):
+            positions[node_id] = (layer * layer_spacing, index * node_spacing)
+    return positions
+
+
+def _reduce_edge_crossings(
+    nodes_by_layer: dict[int, list[str]],
+    workflow: WorkflowGraph,
+) -> None:
+    """Swap layer-node pairs whenever the permutation reduces edge crossings."""
+    if len(nodes_by_layer) < 2:
+        return
+    crossing_count = _crossing_count(nodes_by_layer, workflow)
+    improved = True
+    while improved:
+        improved = False
+        for layer in sorted(nodes_by_layer):
+            node_ids = nodes_by_layer[layer]
+            for first_index in range(len(node_ids) - 1):
+                for second_index in range(first_index + 1, len(node_ids)):
+                    node_ids[first_index], node_ids[second_index] = (
+                        node_ids[second_index],
+                        node_ids[first_index],
+                    )
+                    candidate_count = _crossing_count(nodes_by_layer, workflow)
+                    if candidate_count < crossing_count:
+                        crossing_count = candidate_count
+                        improved = True
+                        break
+                    node_ids[first_index], node_ids[second_index] = (
+                        node_ids[second_index],
+                        node_ids[first_index],
+                    )
+                if improved:
+                    break
+            if improved:
+                break
+
+
+def _crossing_count(nodes_by_layer: dict[int, list[str]], workflow: WorkflowGraph) -> int:
+    """Return the number of geometric crossings among the workflow's directed edges."""
+    positions = {
+        node_id: (float(layer), float(index))
+        for layer, node_ids in nodes_by_layer.items()
+        for index, node_id in enumerate(node_ids)
+    }
+    crossings = 0
+    for first_index, first_edge in enumerate(workflow.edges):
+        for second_edge in workflow.edges[first_index + 1 :]:
+            if {
+                first_edge.source_node,
+                first_edge.target_node,
+            }.intersection((second_edge.source_node, second_edge.target_node)):
+                continue
+            if _edges_cross(
+                first_edge.source_node,
+                first_edge.target_node,
+                second_edge.source_node,
+                second_edge.target_node,
+                positions,
+            ):
+                crossings += 1
+    return crossings
+
+
+def _edges_cross(
+    first_source: str,
+    first_target: str,
+    second_source: str,
+    second_target: str,
+    positions: dict[str, tuple[float, float]],
+) -> bool:
+    """Return whether two directed edge segments strictly intersect on the canvas."""
+    first_start, first_end = positions[first_source], positions[first_target]
+    second_start, second_end = positions[second_source], positions[second_target]
+    overlap_start = max(first_start[0], second_start[0])
+    overlap_end = min(first_end[0], second_end[0])
+    if overlap_start >= overlap_end:
+        return False
+    first_difference_at_start = _edge_y(first_start, first_end, overlap_start) - _edge_y(
+        second_start, second_end, overlap_start
+    )
+    first_difference_at_end = _edge_y(first_start, first_end, overlap_end) - _edge_y(
+        second_start, second_end, overlap_end
+    )
+    return first_difference_at_start * first_difference_at_end < 0
+
+
+def _edge_y(start: tuple[float, float], end: tuple[float, float], x: float) -> float:
+    """Return the vertical coordinate for a point on an edge at horizontal coordinate ``x``."""
+    return start[1] + (end[1] - start[1]) * (x - start[0]) / (end[0] - start[0])