Ancora.Config (ancora v1.0.0)

Copy Markdown View Source

Loader and schema for .spec/config.yml.

Allowed top-level keys: default_base, test_paths, lib_paths, severities, and overrides. severities: is one map whose keys are validated against Ancora.Finding. Unknown top-level keys and unknown codes in severities: produce config/unknown_key. Bad values produce config/invalid_value. Both codes are non-tunable.

Each overrides: entry carries subject, code, severity, and a required non-empty reason. An override applies only to findings of that code attributed to that subject. An entry naming an unknown subject or code, or missing reason, produces config/invalid_value and is ignored. spec.status labels a subject with an applied override acknowledged (see subject_status/2).

Malformed YAML degrades to defaults with a [CONFIG] diagnostic on stderr and nothing on stdout.

ANCORA_SHOW_INFO is the only environment variable this module reads.

.spec/config.yml and the ancora version in mix.lock travel together in git. A new finding code is configured in the same PR that bumps the dependency — they are co-versioned, never advertised as independently forward-compatible.

Summary

Types

t()

Functions

defaults()

Default configuration with no findings.

load(root, opts \\ [])

Loads .spec/config.yml relative to root.

severity_for(config, code, subject)

Config-layer severity for code attributed to subject.

show_info?()

True when ANCORA_SHOW_INFO=1. This is the only environment variable ancora reads.

subject_status(config, subject)

:acknowledged when subject has at least one applied override, otherwise nil. Consumed by spec.status.

Types

t()

@type t() :: %Ancora.Config{
  default_base: String.t(),
  findings: [Ancora.Finding.t()],
  lib_paths: [String.t()] | nil,
  overrides: [Ancora.Config.Override.t()],
  severities: %{optional(String.t()) => Ancora.Severity.severity()},
  test_paths: [String.t()]
}

Functions

defaults()

@spec defaults() :: t()

Default configuration with no findings.

load(root, opts \\ [])

@spec load(
  String.t(),
  keyword()
) :: t()

Loads .spec/config.yml relative to root.

Options:

  • :path — override the config file path
  • :known_subjects — enumerable of subject ids; when given, an override naming a subject not in the set fires config/invalid_value and is ignored. When omitted, subject existence is not checked (the gate supplies the corpus once the index exists).

severity_for(config, code, subject)

@spec severity_for(t(), String.t(), String.t() | nil) ::
  Ancora.Severity.severity() | nil

Config-layer severity for code attributed to subject.

A matching applied override wins over the severities: map. Returns nil when neither names the code.

show_info?()

@spec show_info?() :: boolean()

True when ANCORA_SHOW_INFO=1. This is the only environment variable ancora reads.

subject_status(config, subject)

@spec subject_status(t(), String.t()) :: :acknowledged | nil

:acknowledged when subject has at least one applied override, otherwise nil. Consumed by spec.status.