Resolves references and expands recipes into one flat, acyclic, de-duplicated step list for Composer.Runner.

Resolving a step reference

A bare string in a recipe names a step:

0. In a recipe, a cookbook part that is one of the recipe's own aliases is first replaced by the real cookbook name ("lab:auth/passkeys" with lab: "composer_lab" is "composer_lab:auth/passkeys"); errors show the reference as written, with the alias noted. Aliases never apply inside an included recipe, nor to references given on the command line. An alias that is the name of an installed cookbook is an error.
1. "cookbook:path" is looked up exactly. An unknown cookbook is an error that suggests adding the package that ships it.
2. An unqualified "path" is looked up first in the referring recipe's own cookbook (on the command line, the current project's cookbook).
3. Otherwise every cookbook is searched. Exactly one match resolves to it; more than one is an :ambiguous error listing every candidate. No match, for a name without a /, is the Hex package of that name ("oban" is "hex:oban") - unless the name is very close to an existing step id, which is reported as a likely typo instead.
4. "hex:pkg" (or "hex:org.pkg" for a private repo) adds the package to mix.exs and runs its own installer, if it ships one. Its @ source ("hex:pkg@path:../pkg", see Composer.Ref) and the entry's options (argv, only, runtime, a source and git options) are carried into one {:install, package, opts} step, whose opts are canonical (see Composer.Runner). An unqualified name that falls back to Hex keeps its options; one that names a step must not have package options ({:dep_opts_on_step, ...}).

A step in the referring cookbook wins over a Hex package of the same name, so an unqualified name is never ambiguous with hex:.

{:use, ref} names a recipe, "cookbook:group/name". An unqualified name without a / ({:use, "base"}) is the recipe of that name in the same group as the referring recipe; nothing outside the group can match it. Any other reference is resolved like a step reference, except that local is searched too and there is no Hex fallback.

Entries

Every leaf becomes an entry:

%{ref: "core:setup/credo", label: "core:setup/credo",
  step: {:module, Composer.Core.Steps.Setup.Credo},
  origin: "local:phx/app", gates: [:dev_tools], if: nil, meta: %Composer.Step.Meta{}}

origin is the recipe the step came from, gates the if: flags of the includes it was reached through, and if its own flag. step is the internal form the runner applies. An install's ref is always "hex:pkg", whatever its source, so requires: ["hex:pkg"] matches it by name; its label shows the source and installer argv ("hex:my_lib (path ../my_lib)"). alias is the cookbook alias the reference was written with ("lab"), or nil; ref and label always use the real cookbook name.

The result also lists the recipes visited, root first, as %Composer.Recipe{} structs; declared_flags/1 collects their flags.

Rules

• Include-once. A recipe is expanded at most once per resolution; later includes of it are no-ops. A diamond is not a cycle.
• No cycles. Re-entering a recipe that is still being expanded is a {:cycle, path} error, with the full cookbook:path chain.
• De-duplication. A step equal to an earlier one is dropped (first occurrence wins) and reported in duplicates. Equality uses the resolved step, so "setup/credo" and "core:setup/credo" are duplicates. Steps that differ only in their if: are distinct.
• One install per package. Installs of one package with different options (argv, source or dep options, or none against some) are a {:conflicting_install, package, [{origin, label}, ...]} error, whatever their if: flags: the runner adds one dependency per package. Identical ones are de-duplicated as above.

Flags

flags: :all (the default) follows every gated include, for validation, listing and building the flag schema. flags: keyword follows a gated include only when its flag is true; a skipped include is not marked as expanded, so a later ungated include of it still expands. Leaf if: flags are applied by active/2.