Syntropy.Receipts.Execution (syntropy v0.3.0)

Copy Markdown

Executes one project check as a supervised OS process.

The check runs through an Erlang port (:spawn_executable, no shell) in the repository's working directory with a scrubbed environment, so a nested mix test or cargo test does not inherit this runtime's MIX_ENV, ERL_*, or RELEASE_* variables.

Output handling never fails a check for being verbose: every chunk streams through a SHA-256 (output_digest covers the full output) while only a bounded tail is retained for the receipt. On timeout the OS process is killed explicitly — closing the port alone would orphan a running suite. Exit statuses above 128 are reported as-is and classified as signal deaths by the receipt builder.

Summary

Types

outcome()

Functions

run_check(check, run_id, repo_path, opts \\ [])

Runs check (an available check from Syntropy.Receipts.Detect) inside repo_path, registering its OS pid under run_id for cancellation.

tool_version(executable)

Best-effort tool version: the first line of <tool> --version (or the tool's own version subcommand), truncated; nil when unreadable.

Types

outcome()

@type outcome() :: %{
  exit_code: integer() | nil,
  timed_out: boolean(),
  duration_ms: non_neg_integer() | nil,
  output_digest: String.t(),
  output_tail: String.t(),
  tool_version: String.t() | nil
}

Functions

run_check(check, run_id, repo_path, opts \\ [])

@spec run_check(map(), String.t(), String.t(), keyword()) ::
  {:ok, outcome()} | :cancelled | {:error, map()}

Runs check (an available check from Syntropy.Receipts.Detect) inside repo_path, registering its OS pid under run_id for cancellation.

Returns {:ok, outcome}, :cancelled when the run was aborted, or {:error, reason} when the process could not be spawned.

tool_version(executable)

@spec tool_version(String.t()) :: String.t() | nil

Best-effort tool version: the first line of <tool> --version (or the tool's own version subcommand), truncated; nil when unreadable.

Bounded to two seconds — a tool that hangs on --version (or a custom check script that ignores its arguments) costs at most the bound, at the price of briefly orphaning the probe process.