Module calibration 

Corpus-calibration artifact: per-language quantile breakpoints for raw per-function metrics, plus the interpolation lookup that turns a metric value into a corpus-relative percentile (“your cyclomatic complexity sits at P74 versus the reference corpus”).

The artifact

A CalibrationArtifact is a versioned, compact JSON container. For each Tier-1 language it holds a LanguageTable whose (v1: single) Stratum carries one MetricQuantiles per raw metric. Each metric stores a QUANTILE_POINTS-long, non-decreasing vector: element i is the value at quantile i / (QUANTILE_POINTS - 1), so index 750 is the corpus q0.750 breakpoint. Storing breakpoints (not raw observations) keeps the embedded world artifact small while still supporting interpolated lookups.

Lookup

percentile binary-searches a metric’s breakpoint vector and linearly interpolates between the two neighbours. Values below the corpus minimum floor to p = 0.0; values above the maximum saturate to p = 1.0 and set CorpusPercentile::beyond_corpus. A language whose pooled sample is below MIN_LANG_SAMPLE — too thin to trust — is treated as absent, as is an unknown language or metric; those all return None.

conditional_tail_percentile is the companion lookup for pools dominated by trivial (zero-complexity) functions: it conditions the percentile on the non-trivial tail so a real file’s complexity does not saturate the top of a mostly-zero distribution.

Building

build_from_observations pools raw per-function metric values per language and reduces each pool to a breakpoint vector. The generated_at timestamp is injected by the caller (the CLI passes the wall clock; determinism tests pass a constant) so the same observations always produce byte-identical output.

merge blends two artifacts by sample-count-weighted interpolation of their quantile vectors. This is an approximation — see its own docs.

Structs

CalibrationArtifact

A versioned corpus-calibration artifact: per-language quantile breakpoints for raw per-function metrics.

CorpusManifest

A corpus build manifest: the set of pinned repos the calibrate command ingests and pools per-function metrics from.

CorpusPercentile

The result of a corpus-percentile lookup.

CorpusRepo

One pinned repo in a CorpusManifest.

LangObservations

Raw per-function metric observations, pooled per (language, metric) before reduction to breakpoint vectors by build_from_observations.

LanguageTable

Per-language breakpoints. language is a [Tier1Language] name (crate::complexity::language::Tier1Language::as_str).

MetricQuantiles

Quantile breakpoints for one raw metric ("cyclomatic", "cognitive", "sloc", "nargs", "max_nesting"). quantiles has length QUANTILE_POINTS and is non-decreasing.

RepoMetrics

Repo-level metric pools: one observation per corpus repo. Absent on artifacts built before this section existed — absent = no lens.

Stratum

A SLOC-bounded stratum of metric breakpoints. v1: bounds are 0..=u64::MAX.

Constants

CALIBRATION_FORMAT_VERSION

Artifact schema version. A loaded artifact whose format_version differs is rejected with a hard error — an explicitly passed --calibration file that cannot be used is a configuration mistake, not a degradable state.

MIN_LANG_SAMPLE

Minimum pooled function count for a language to be trusted. Below this the language is treated as absent (its breakpoints are too noisy to compare against).

QUANTILE_POINTS

Length of every quantile-breakpoint vector: q0.000 … q1.000 inclusive at a 0.001 step.

Functions

active_vintage

Vintage string of the calibration artifact active for opts. A thin wrapper over load_active_artifact — the one place the resolution precedence lives — so the provenance stamp and the corpus lens never drift apart.

attach_repo_metrics

Attach repo-level metric pools to a calibration artifact.

build_from_observations

Build a calibration artifact from pooled raw observations.

conditional_tail_percentile

Percentile of value within the corpus’s non-trivial tail for (language, metric) — the conditional lookup the anchored hotspot score uses in place of percentile.

embedded_world

The embedded world artifact, lazily parsed once.

language_sample_functions

Pooled per-function sample size behind language’s breakpoints — the honest n for a Wilson confidence interval on a per-function corpus percentile.

load

Load and validate a calibration artifact from a JSON file.

load_active_artifact

The single home for the active-artifact resolution precedence, shared by the corpus-percentile lens and the provenance vintage stamp:

load_manifest

Parse and return a CorpusManifest from a TOML file.

merge

Blend two artifacts by sample-count-weighted interpolation of their quantile vectors, summing sample counts.

percentile

Corpus-relative percentile of value for (language, metric).

raw_percentile

Midpoint-rank percentile of value among sorted (ascending).