convenience combine

[matt-beanland]

add a combine function which is able to be used in a pipeline, allow it to optionally take a keyword list of title and description and update them.

[matt-beanland]

This was the convenience combine I wrote in livebook and its usage (without ability to optionally alter title and/or description)

require Artefact

defmodule Combine do
  def combine(other, heart) do
    {:ok, bindings} = Artefact.Binding.find(heart, other)
    Artefact.harmonise(heart, other, bindings)
  end
end

me_knowing_combined_artefact = 
  me_knowing_artefact
  |> Combine.combine(me_valuing_artefact)
  |> Combine.combine(me_being_artefact)
  |> Combine.combine(me_knowing_more_artefact)
  |> Combine.combine(me_doing_artefact)

ArtefactKino.new(me_knowing_combined_artefact)

note that combine is no longer heartside to be compatible with pipeline.

[matt-beanland]

me_knowing
|> Artefact.combine(me_valuing)
|> Artefact.combine(me_being)
|> Artefact.combine(me_doing, title: "MeMind", description: "Mind of Me")

It's a defmacro (so the calling module is captured for provenance, matching compose and harmonise), and it delegates to do_combine/4 which:

auto-finds bindings via Artefact.Binding.find/2 (raises MatchError if there are no shared nodes — matching your original livebook helper)
delegates to do_harmonise/5 so :title and :base_label overrides flow through naturally
patches :description onto the result, since harmonise doesn't currently honour :description in opts

Tests — eleven new ones in a describe "Artefact.combine/3" block at the end of artefact_test.exs:

basic combine via shared uuid
default portmanteau base_label
title defaults to base_label, description defaults to nil
title override, description override, both together
pipeline chaining (three artefacts deep)
pipeline applying opts on the final step
:harmonised provenance with the calling module
raises MatchError on no shared nodes

A small combine_artefact/2 helper is defined in the describe block to keep each test compact.