Composer.Facets (composer v0.2.0)

Copy Markdown View Source

The controlled facet vocabulary that steps declare with use Composer.Step.

Facets describe a step instead of encoding meaning in its module path:

  • action - what the step does: [:add, :remove, :gen, :config, :patch]
  • frameworks - the frameworks it targets
  • capability - the capabilities it adds
  • phase - an advisory position in a run (list order still decides)
  • stability - how settled the step is

An unknown facet value is a compile-time warning, never an error, so a cookbook can run ahead of composer's vocabulary. A value of the wrong type (for example tags: "x") is an error.

requires entries are checked before a run:

  • "cookbook:path" - another step that should run earlier
  • {:executable, "bun"} - an executable on PATH
  • {:package, :phoenix, "~> 1.8"} - a version requirement on a dependency the target app declares

Summary

Types

requirement()

A requires entry.

Functions

known()

Every option use Composer.Step accepts.

phases()

The order of the phase facet, earliest first.

requirement?(ref)

True for a well-formed requires entry.

validate(opts)

Validates and normalizes step options.

values(facet)

Returns the values known for facet.

vocabulary()

Returns the seed vocabulary as %{facet => [value]}.

Types

requirement()

@type requirement() ::
  String.t() | {:executable, String.t()} | {:package, atom(), String.t()}

A requires entry.

Functions

known()

@spec known() :: [atom()]

Every option use Composer.Step accepts.

phases()

@spec phases() :: [atom()]

The order of the phase facet, earliest first.

requirement?(ref)

@spec requirement?(term()) :: boolean()

True for a well-formed requires entry.

validate(opts)

@spec validate(keyword()) :: {:ok, map(), [String.t()]} | {:error, String.t()}

Validates and normalizes step options.

Returns {:ok, normalized, warnings}, where normalized is a map with every known key (list facets default to [], single facets to nil), or {:error, message} for an unknown option or a value of the wrong type. Warnings are strings naming each unknown facet value.

values(facet)

@spec values(atom()) :: [atom()]

Returns the values known for facet.

vocabulary()

@spec vocabulary() :: %{required(atom()) => [atom()]}

Returns the seed vocabulary as %{facet => [value]}.