Firebreak.Finding (Firebreak v0.1.0)

Copy Markdown View Source

A single issue surfaced by an analysis pass. Findings carry a stable check id (so they can be allowlisted in CI), a severity, and the source location they point at.

Summary

Types

confidence()

How much to trust the finding

severity()
t()
tier()

Report grouping: :primary = high-signal coupling/correctness; :secondary = structural/advisory.

Functions

rank(severity)

Numeric rank for a severity (lower = more severe).

signature(f)

A stable identity for a finding, used to allowlist it in .firebreak.exs or to diff a run against a committed baseline.

sort(findings)

Sort findings by severity (high first), then by module/line.

tier(check)

Which report tier a check belongs to. :primary is the high-signal coupling and correctness set the report leads with; :secondary is the structural/advisory set (blast-radius strategies, orphan heuristics, intensity advice) — real, but more often by-design or lower-confidence, so it's grouped afterwards.

Types

confidence()

@type confidence() :: :exact | :best_effort

How much to trust the finding:

  • :exact — derived from the runtime supervision tree (Mod.init/1).
  • :best_effort — derived from static source parsing, which may miss dynamically-assembled structure or rest on a heuristic.

severity()

@type severity() :: :high | :medium | :low | :info

t()

@type t() :: %Firebreak.Finding{
  check: atom(),
  confidence: confidence(),
  details: map(),
  file: String.t() | nil,
  line: non_neg_integer() | nil,
  message: String.t(),
  module: module() | nil,
  severity: severity()
}

tier()

@type tier() :: :primary | :secondary

Report grouping: :primary = high-signal coupling/correctness; :secondary = structural/advisory.

Functions

rank(severity)

Numeric rank for a severity (lower = more severe).

signature(f)

@spec signature(t()) :: String.t()

A stable identity for a finding, used to allowlist it in .firebreak.exs or to diff a run against a committed baseline.

Deliberately excludes volatile data — line numbers, caller counts, message wording — so a finding keeps the same signature as the surrounding code shifts. The optional discriminator distinguishes multiple findings of the same check on the same module (e.g. a boot-order pair is keyed by its callee).

"cross_tree_coupling:MyApp.Sup"
"boot_order_dependency:MyApp.Early/MyApp.Late"

sort(findings)

Sort findings by severity (high first), then by module/line.

tier(check)

@spec tier(atom()) :: tier()

Which report tier a check belongs to. :primary is the high-signal coupling and correctness set the report leads with; :secondary is the structural/advisory set (blast-radius strategies, orphan heuristics, intensity advice) — real, but more often by-design or lower-confidence, so it's grouped afterwards.