Module metric_catalog 

Canonical metric catalog: offender sub-metric ids with their long-form sentences, metric_catalog::Direction and metric_catalog::Scale, plus the family view rendered by bca list-metrics and the metric-selector resolver (metric_catalog::resolve_selector). Single source of truth shared by the library’s offender formatters, the CLI’s threshold engine (which pins its extractor ids to metric_catalog::METRICS via a parity test), and the metric selections of bca metrics --metrics and the Python metrics=. metric_catalog::Threshold is the validated limit that answers breach, severity, soft-tier, change and drift questions in the metric’s own direction and scale. Single source of truth for the metric catalog.

Before this module existed, the same set of offender metric ids was hand-maintained in three places — output::sarif’s rule descriptions, the CLI’s threshold extractor table, and a third copy inside a “does every extractor have a description” test — plus a fourth, differently-shaped table powering bca list-metrics. Those tables drifted: ten of twenty-one rule-description keys once failed to match any real offender id and went unnoticed for two model versions.

METRICS is now the canonical list of offender sub-metric ids (halstead.volume, mi.original, …) together with their long-form sentences and Direction. FAMILIES is the canonical view that bca list-metrics renders. The library’s offender formatters (output::sarif, output::code_climate) read METRICS; the CLI’s threshold engine keys its extractor table off the same ids and a parity test pins the two id-sets together, so a new metric cannot ship with a half-updated catalog.

Each entry also records its Scale: ratio for the counts, interval for the Maintainability Index family, whose zero is arbitrary and whose values go negative. Threshold builds on direction and scale together. It is a validated limit that answers every value question a gate asks: whether a value breaches, by how much, how two breaches rank, where the soft tier sits, and how far a value has moved from its baseline. Those answers then mean the same thing on every surface (#1621).

resolve_selector reads both tables to turn a selector — a name saying what to compute — into the Metric family that computes it. bca metrics --metrics and the Python bindings’ metrics= both resolve through it, so a name copied from bca list-metrics or bca check --threshold works in either or neither (#1614).

Structs

Checked

A successfully validated Threshold, together with any advisory the limit raised.

MetricFamily

A top-level metric family as surfaced by bca list-metrics.

MetricInfo

Catalog entry for one offender-emitting sub-metric id.

MetricRow

A bca list-metrics row: the bare name printed in names mode and the one-line summary printed in descriptions mode.

Threshold

A metric limit that has been checked against the metric’s Scale: the metric id is known, the limit is finite, and a ratio-scale limit is non-negative.

UnknownSelectorError

Error returned by resolve_selector for a name that is no metric selector.

Enums

Change

How a value has moved relative to its baseline record, oriented so a positive number means worse. Returned by Threshold::change.

Direction

Which direction of a metric’s value is unhealthy.

LimitError

Why a limit was rejected by Threshold::check or a soft ratio by Threshold::soft_limit.

LimitWarning

An advisory raised by a limit Threshold::check accepted.

MetricScope

The space kind a metric’s threshold is meaningful on (issue #969).

Scale

The measurement scale of a metric’s value: which arithmetic on it means anything (issue #1621).

Constants

FAMILIES

Canonical bca list-metrics view. Family summaries moved here verbatim from the CLI’s former hand-maintained catalog. Declaration order is the list-metrics print order.

METRICS

Canonical offender sub-metric catalog. Long-form sentences and the mi.* lower-is-worse direction moved here verbatim from the former output::rule_descriptions table.

Functions

lookup

Catalog entry for a known offender id, or None. Callers pick their own fallback for unknown ids (SARIF emits the raw id; Code Climate falls through to its default message).

lower_is_worseDeprecated

Whether a lower value of the metric id is the unhealthy direction (the mi.* Maintainability Index family). An id the catalog does not know defaults to higher-is-worse (#698).

resolve_selector

Resolve a metric selector to the Metric family that computes it.

scale

The Scale of metric id (issue #1621), or None for an id the catalog does not know. The free-function twin of scope.

scope

The MetricScope of metric id — the space kind its threshold gates (issue #969). None for an id the catalog does not know; both front-ends treat an unknown id as a usage error before reaching here, so the None arm is only a defensive fallback.

selector_names

The names resolve_selector advertises: every family name (loc, halstead, …) and every bca list-metrics row name (sloc, dloc, …), sorted and deduplicated.