Cerbero.Finding (cerbero v0.1.0)

Copy Markdown View Source

One judged fact: mechanism + scale + provenance, with source location.

The metadata contract

metadata records as data what the message says in prose. It is serialized verbatim into --format json output through the canonical encoder, so every value must be JSON-encodable: maps (atom or string keys), lists, strings, atoms (encoded as strings), numbers, booleans — never tuples, PIDs, refs, functions, or structs. A non-encodable value raises at render time instead of the CLI's usual exit-2 error path, so third-party checks (extra_checks) must respect this.

Reserved keys, written by the runner/CLI machinery — set them only with their documented meaning:

  • :lock — the lock mode a rule judged (Cerbero.DDL.Effect lock atom); the lock-timeout attestation keys on it.

  • :skipped — %{via: [:migration_attribute | :config, ...]} in application order, plus :reason for @cerbero_skip; written by the runner when a finding is demoted.

  • :direction — :down on --down findings.
  • :no_snapshot — true in structural (no-snapshot) mode.

Summary

Types

severity()
t()

Functions

at_least?(severity, threshold)
most_severe(severities)
stable_sort(findings)

The stable ordering contract for machine output: file, then line, then check name, with global findings (nil file/line) first. Both the JSON and SARIF formatters depend on this exact ordering — their outputs are golden-tested byte-for-byte, so the key lives here, once.

Types

severity()

@type severity() :: :error | :warning | :info

t()

@type t() :: %Cerbero.Finding{
  check: term(),
  engine: term(),
  file: term(),
  line: term(),
  message: term(),
  metadata: term(),
  relations: term(),
  severity: term()
}

Functions

at_least?(severity, threshold)

@spec at_least?(severity(), severity()) :: boolean()

most_severe(severities)

@spec most_severe([severity() | :none]) :: severity() | :none

stable_sort(findings)

@spec stable_sort([t()]) :: [t()]

The stable ordering contract for machine output: file, then line, then check name, with global findings (nil file/line) first. Both the JSON and SARIF formatters depend on this exact ordering — their outputs are golden-tested byte-for-byte, so the key lives here, once.