@spec has_diverged?(Lightning.Projects.Project.t(), Lightning.Projects.Project.t()) ::
  boolean()

Checks if the target project has diverged from the source sandbox.

Divergence occurs when any workflow in the target project has a different version hash compared to when the source sandbox was created. This indicates that changes have been made to the target that the sandbox doesn't know about, which could lead to data loss during merge.

Parameters

• source_project - The sandbox project with workflows
• target_project - The target project to check with workflows

Returns

• true if the target has diverged (workflow versions differ)
• false if no divergence detected

@spec merge_project(
  Lightning.Projects.Project.t(),
  Lightning.Projects.Project.t(),
  map()
) :: map()

Merges a source project onto a target project using workflow name matching.

Maps workflows from source to target project based on exact name matching. Uses the existing merge_workflow/2 logic for individual workflow merging. Workflows that don't match are marked for deletion (target) or creation (source).

Parameters

• source_project - The project with modifications to merge
• target_project - The target project to merge changes onto

Returns

A map with the merged project structure ready for import, containing workflow mappings and project data.

@spec merge_workflow(
  Lightning.Workflows.Workflow.t(),
  Lightning.Workflows.Workflow.t(),
  map()
) :: map()

Merges a sandbox workflow back onto its parent workflow using UUID mapping.

Maps nodes and edges from source to target workflow, preserving UUIDs where possible when merging two workflows (likely one is a fork of the other).

The algorithm follows these phases:

1. Direct ID Matching - matches nodes with identical IDs
2. Root Node Mapping - always maps root nodes
3. Structural and Expression Matching - iterative matching using parents, children, and expression
4. Edge Mapping - maps edges based on node mappings

Parameters

• source_workflow - The sandbox workflow with modifications (i.e staging)
• target_workflow - The parent workflow to merge changes onto (i.e main)

Returns

A map with the merged workflow structure ready for import, containing UUID mappings and workflow data.