Guardrails / Collectors

Elixir build

The Mix build in the project directory: the application it declares, the Elixir version it asks for, every application of an umbrella, the dependencies each manifest names with their environments and origins, and the lock file beside them. mix.exs is Elixir rather than a declaration, so what it declares conditionally is not seen and scanned says so.

Facts key	elixir
Version	v1
Script	elixir.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
projectDir	Directory holding the project, relative to the directory the CLI runs in.	.	GUARDRAIL_INPUT_PROJECTDIR

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["elixir"]
}

elixir = guardrail.facts("elixir")

Facts

The document elixir collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
directory	The projectDir input, as the guardrail configured it.
exists	Whether that directory is there. Nothing else is collected when it is not.
manifest	Path of the primary manifest, relative to projectDir, always mix.exs.
sources	Every manifest that was read, in the order they were read.
scanned	Every manifest that is Elixir rather than a declaration and was read by pattern. A dependency added inside a condition or built by a function is not seen, so a guardrail reading dependencies from one of these is reading a floor rather than the whole list.
declared	The Elixir version the project asks for, or null when it asks for none.
declared.version	Constraint exactly as written, such as ~> 1.16.
declared.source	Manifest declaring it, relative to projectDir.
declared.pinned	Whether the constraint names one exact version rather than a range. A ~>, a >= or an or is not pinned.
app	The application name the project function declares, such as widget, or null when the reader could not see one.
version	The version the project function declares, such as 1.2.3, or null.
umbrella	Whether the project declares an apps_path, which makes it an umbrella whose real applications live under that directory.
projects	The root application, followed by every application under the umbrella's apps_path.
projects[].path	Directory of the application, relative to projectDir, . for the project directory itself.
projects[].manifest	That application's mix.exs, relative to projectDir.
projects[].name	Application name it declares, or null when the reader could not see one.
dependencies	What the manifests declare, split by whether the project asks for it itself.
dependencies.direct	Every dependency tuple the reader saw, in the order they appear.
dependencies.direct[].name	Package name, such as phoenix.
dependencies.direct[].version	Requirement exactly as written, such as ~> 1.7.0, or null when the tuple names none because it comes from a path or a git URL.
dependencies.direct[].scopes	Environments the only option names, such as dev and test, or default when the tuple names none and it is compiled in every environment.
dependencies.direct[].source	Manifest declaring it, relative to projectDir.
dependencies.direct[].pinned	Whether the requirement names one exact version. A ~>, a >=, a git URL or a path is not pinned.
dependencies.direct[].origin	Where it comes from: hex, git when the tuple carries a git: or github: option, or path when it carries a path: option.
dependencies.transitive	Always empty. What mix.lock resolves is not read: lockfiles says whether one is committed.
lockfiles	mix.lock when it is committed, relative to projectDir. It carries the checksum of every package, so an application without one resolves and verifies differently on every build.
unparsed	Every manifest the reader could not open, so a guardrail can tell a project that declares nothing from one nobody could read.
unparsed[].path	Path of that manifest, relative to projectDir.
unparsed[].reason	What stopped the reader.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by elixir collector:

{
  "directory": ".",
  "exists": true,
  "manifest": "mix.exs",
  "sources": [
    "mix.exs"
  ],
  "scanned": [
    "mix.exs"
  ],
  "declared": {
    "version": "~> 1.16",
    "source": "mix.exs",
    "pinned": false
  },
  "app": "widget",
  "version": "1.2.3",
  "umbrella": false,
  "projects": [
    {
      "path": ".",
      "manifest": "mix.exs",
      "name": "widget"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "name": "phoenix",
        "version": "~> 1.7.11",
        "scopes": [
          "default"
        ],
        "source": "mix.exs",
        "pinned": false,
        "origin": "hex"
      },
      {
        "name": "jason",
        "version": "1.4.1",
        "scopes": [
          "default"
        ],
        "source": "mix.exs",
        "pinned": true,
        "origin": "hex"
      },
      {
        "name": "credo",
        "version": "~> 1.7",
        "scopes": [
          "dev",
          "test"
        ],
        "source": "mix.exs",
        "pinned": false,
        "origin": "hex"
      },
      {
        "name": "queue",
        "version": null,
        "scopes": [
          "default"
        ],
        "source": "mix.exs",
        "pinned": false,
        "origin": "path"
      }
    ],
    "transitive": []
  },
  "lockfiles": [
    "mix.lock"
  ],
  "unparsed": []
}

Collected for

Guardrail	Category	Inputs
elixir/lockfile-committed	elixir	projectDir
elixir/no-git-dependencies	elixir	projectDir
elixir/version-declared	elixir	projectDir

All collectors