@spec all_packages() :: [package_spec()]

Returns every explicitly classified package project.

@spec audit_release_deps(
  keyword(),
  MapSet.t(String.t())
) :: {[String.t()], [String.t()]}

Compares the dependencies a project declares against the ones it publishes.

Audit the source config, never the publish config. Auditing the publish config is circular: a dependency dropped by an env conditional in mix.exs is missing from the publish config and from the tarball, so the two agree and nothing is reported.

A public-train dependency that fails to reach the tarball is an error. A pre-alpha one is an intentional drop, but it still changes what Hex consumers get, so it is surfaced as a warning rather than as silence.

@spec public_packages() :: [package_spec()]

Returns the public Hex release train in publish order.

@spec release_deps(keyword()) :: [{atom(), String.t() | nil, keyword()}]

Returns the Raxol package dependencies relevant to a Hex publish.

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

Resolves the scratch directory the Hex builds unpack into.

build_root is deleted recursively, so it is confined under the project root and may be neither the root itself nor an existing directory this checker did not create. Without those gates run(build_root: ".") deletes the working tree. The path is always interpreted relative to root; an absolute request is jailed under it rather than honoured.

@spec run(keyword()) :: {:ok, report()} | {:error, report()}

Runs the metadata, provenance, and Hex build checks.

Not safe to run concurrently with anything else in the same VM. Loading a child project goes through Mix.Project.in_project/4, which changes the working directory of the whole OS process, and the HEX_BUILD toggling around it mutates the process environment. Both are global. Tests covering this module are async: false for that reason.

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

Selects packages according to the release checker options.

:only accepts atoms or strings. Strings are matched against known package names rather than converted, so a typo cannot mint an atom from argv.

@spec untracked_package_files(String.t(), String.t(), keyword()) ::
  {:ok, [String.t()]} | :unavailable

Lists the files a package would ship that git does not track, relative to root.

mix hex.build packages the working tree, not the commit, so a green check on a dirty tree says nothing about what a publish actually ships. Returns :unavailable when git cannot answer, which the run reports as a warning rather than treating as a clean result.

@spec validate_catalog(String.t()) :: [String.t()]

Checks that every project under packages/ is classified in this module.

A package that exists on disk but appears in neither train is unclassified; a classified package with no project on disk is missing. Either one means the release train no longer describes the repo.

@spec validate_order([map()], [package_spec()]) :: [String.t()]

Checks that no package is published before a dependency it needs.

package_reports need only carry :app and :deps; the publish order is the position of each package in release_train.

@spec validate_project_config(package_spec(), keyword(), String.t(), [package_spec()]) ::
  {[String.t()], [String.t()]}

Validates one loaded Mix project config against a package spec.