@spec diverged_workflows(
  Lightning.Projects.Project.t(),
  Lightning.Projects.Project.t()
) :: [String.t()]

Returns the list of workflow names that have diverged between source and target projects.

A workflow is considered diverged when the target project (parent) has changed since the sandbox was forked. Specifically, a workflow has diverged if the target's current HEAD version is not present in the sandbox's version history.

Arguments can be reversed to get changes in a sandbox against main.

Parameters

• source_project - The sandbox project
• target_project - The target project to compare against

Returns

• List of workflow names (strings) that have diverged
• Empty list if no workflows have diverged

Examples

iex> MergeProjects.diverged_workflows(sandbox, parent)
["Payment Processing", "Data Sync"]

iex> MergeProjects.diverged_workflows(sandbox, parent)
[]

@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).

Pure transformation — returns a merge document without touching the database. Scope is workflow structure only; credentials, collections, and other project-scoped resources are not part of the document.

For sandbox merges use Lightning.Projects.Sandboxes.merge/4, which composes this with Provisioner.import_document/4 and sandbox-specific steps (e.g. collection name sync) inside a single transaction.

Parameters

• source_project - The project with modifications to merge
• target_project - The target project to merge changes onto
• opts - Keyword options:
  • :new_uuid_map - Map of source UUID to target UUID (default: %{})
  • :selected_workflow_ids - List of source workflow IDs to merge. When provided, only those source workflows are processed and no target workflows are marked for deletion. When nil (default), all source workflows are processed and unmatched target workflows are deleted.

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.