Ancora.Severity (ancora v1.0.0-rc.1)

Per-finding severity resolver.

Precedence (highest to lowest), with one exception:

config off > Spec-Ack: trailer downgrade > config severity > registry default

off in config (the severities: map or a per-subject override) is absorbing: a trailer cannot re-noise a code the repo silenced. A finding resolved to off is not emitted and is not counted.

Trailer values apply only as a downgrade: never higher than the config-resolved severity (the config value if present, else the registry default). Attempts to raise emit a [CONFIG] line on stderr and are ignored.

config/unknown_key and config/invalid_value are non-tunable: they stay at the registry default regardless of config or trailer.

Resolved findings carry severity_source as :config, :trailer, or :default.

Summary

Types

severity()

source()

Functions

blocking?(atom)

True when a finding at severity fails a strict gate.

known?(value)

True when value is a recognized severity.

known_severities()

Known severity atoms.

resolve(code, opts, per_code_default)

Resolves severity for code (see resolve_with_source/3).

resolve_all(findings, opts \\ [])

Resolves each finding, drops those at off, and sets severity / severity_source on the rest.

resolve_with_source(code, opts, per_code_default)

Resolves severity together with the layer that supplied it.

show_info?(opts \\ [])

Whether info findings should be shown.

summarize(findings, opts \\ [])

Partitions resolved findings for display.

Types

severity()

@type severity() :: Ancora.Finding.severity()

source()

@type source() :: Ancora.Finding.source()

Functions

blocking?(atom)

@spec blocking?(severity()) :: boolean()

True when a finding at severity fails a strict gate.

error and warning block; info and off never do.

known?(value)

@spec known?(term()) :: boolean()

True when value is a recognized severity.

known_severities()

@spec known_severities() :: [severity()]

Known severity atoms.

resolve(code, opts, per_code_default)

@spec resolve(Ancora.Finding.code(), keyword() | map(), severity()) :: severity()

Resolves severity for code (see resolve_with_source/3).

resolve_all(findings, opts \\ [])

@spec resolve_all([Ancora.Finding.t()], keyword() | map()) :: [Ancora.Finding.t()]

Resolves each finding, drops those at off, and sets severity / severity_source on the rest.

resolve_with_source(code, opts, per_code_default)

@spec resolve_with_source(Ancora.Finding.code(), keyword() | map(), severity()) ::
  {severity(), source()}

Resolves severity together with the layer that supplied it.

Options:

:config — %Ancora.Config{} (severities + per-subject overrides)
:config_severities — code => severity map, used when :config is absent
:subject — subject id, used to match overrides:
:trailer_override — code => severity from Ancora.Trailer

show_info?(opts \\ [])

@spec show_info?(keyword() | map()) :: boolean()

Whether info findings should be shown.

When :show_info is passed, that value wins. Otherwise true when opts[:verbose] is true or Ancora.Config.show_info?/0 reports ANCORA_SHOW_INFO=1.

summarize(findings, opts \\ [])

@spec summarize([Ancora.Finding.t()], keyword() | map()) :: %{
  visible: [Ancora.Finding.t()],
  errors: non_neg_integer(),
  warnings: non_neg_integer(),
  hidden_info: non_neg_integer(),
  blocking?: boolean()
}

Partitions resolved findings for display.

Info findings are omitted from :visible unless show_info?/1 is true, and never increment :errors or :warnings. :hidden_info is the count of info findings suppressed this way. :blocking? is true when any visible finding is error or warning.