Forecastle.Build (forecastle v1.0.0)

Reads application builds and compares their modules.

A build is the library directory from a compiled project or assembled release. The module reads application versions, BEAM files, .app inventories, behaviours and exports for mix castle.appup and mix castle.appup.gen.

Invalid library paths, incomplete application directories and broken entries are errors. An application absent from one valid build remains a meaningful add or remove result.

Module fingerprints combine :beam_lib.md5/1 with persisted attributes. This ignores changes caused only by BEAM stripping or documentation while retaining explicit @vsn and other persisted-attribute changes.

Summary

Types

fingerprint()

A module's BEAM md5 and persisted attributes, which the md5 does not cover.

side()

One application in one build.

t()

A build's library directory, read once.

Functions

app_resource!(file, app)

Reads an application's version and module inventory from its .app file.

behaviours(side, module)

Returns OTP behaviours declared in a module's persisted attributes.

build(describe, lib_dir)

Reads a build library directory.

current!()

Compiles and reads the current project's library directory.

ebin(build, app)

Returns an application's ebin directory, or nil when it is absent.

exports?(side, module, name, arity)

Returns whether a module exports a function.

moved(old, new)

Returns sorted lists of changed, added and removed modules.

resolve!(spec, level)

Resolves a baseline and reads its library directory at the requested level.

side!(ebin, app)

Reads one application side of a comparison.

Types

fingerprint()

@type fingerprint() :: {binary(), keyword()}

A module's BEAM md5 and persisted attributes, which the md5 does not cover.

side()

@type side() :: %{
  vsn: binary(),
  inventory: MapSet.t(module()),
  listed?: boolean(),
  modules: %{required(module()) => fingerprint()},
  exports: %{required(module()) => MapSet.t({atom(), arity()})},
  ebin: binary(),
  resource: binary()
}

One application in one build.

vsn and inventory come from the .app resource; modules comes from the BEAM files in ebin. The BEAM files show what changed, and the inventory is what :systools can resolve.

t()

@type t() :: %{describe: binary(), lib_dir: binary(), entries: [binary()]}

A build's library directory, read once.

describe names the build in diagnostics and entries lists lib_dir. See build/2.

Functions

app_resource!(file, app)

@spec app_resource!(binary(), atom()) :: {binary(), MapSet.t(module()), boolean()}

Reads an application's version and module inventory from its .app file.

The boolean result records whether the inventory is a valid list of atoms. A missing or malformed inventory becomes empty so coverage checks fail safely; relup generation remains responsible for full .app validation.

behaviours(side, module)

@spec behaviours(side(), module()) :: [atom()]

Returns OTP behaviours declared in a module's persisted attributes.

Both behaviour and behavior attribute spellings are recognised. Missing modules or attributes return an empty list.

build(describe, lib_dir)

@spec build(binary(), binary()) :: t()

Reads a build library directory.

Raises unless the path contains at least one application directory with an ebin subdirectory. describe is used in diagnostics.

current!()

@spec current!() :: t()

Compiles and reads the current project's library directory.

ebin(build, app)

@spec ebin(t(), atom()) :: binary() | nil

Returns an application's ebin directory, or nil when it is absent.

The function supports Mix and release layouts, verifies the .app resource, and rejects ambiguous or incomplete application entries.

exports?(side, module, name, arity)

@spec exports?(side(), module(), atom(), arity()) :: boolean()

Returns whether a module exports a function.

This supports draft warnings about missing callbacks; behaviour attributes, not exports, determine the drafted instruction.

moved(old, new)

@spec moved(%{required(module()) => fingerprint()}, %{
  required(module()) => fingerprint()
}) ::
  {[module()], [module()], [module()]}

Returns sorted lists of changed, added and removed modules.

resolve!(spec, level)

@spec resolve!(binary(), Forecastle.Baseline.level()) :: t()

Resolves a baseline and reads its library directory at the requested level.

side!(ebin, app)

@spec side!(binary(), atom()) :: side()

Reads one application side of a comparison.

The result includes the application version, .app module inventory, BEAM fingerprints, exports, and source paths.