Module defect_calibration 

Own-repo defect calibration: the fix-commit oracle, the AG-SZZ linkage engine, and the defects.calib.json artifact model.

This module answers does the health score actually predict where defects land in THIS repository? by mining a repo’s own fix history (AG-SZZ), validating code-health predictions against it, and — when the evidence clears an honesty floor — tuning the eight smell weights. Everything here is opt-in and vintage-stamped so default behavior stays byte-reproducible without the feature.

Unit A — the fix-commit oracle

DefectOracle is a dedicated, pure fix-commit classifier — deliberately separate from the kamei fix regex (kamei::enrich_fix), which stays untouched: it is a JIT-SDP feature input whose broad issue|error|patch alternation is a documented SZZ precision trap. This oracle uses a narrower, word-boundary-anchored vocabulary intended specifically for linking fixes to the defects they resolve.

Unit B — the AG-SZZ linkage engine

szz traces each fix commit’s deleted pre-image lines back to the commit that last introduced them, behind a pluggable szz::LineOriginSource seam — the roadmap’s “pluggable SZZ”. This module has no production git-subprocess implementation; that lives CLI-side, shelling git blame --porcelain and parsing it with szz::parse_blame_porcelain.

Unit C — the historical band scan + validation report

validate::band_history recomputes code-health bands at ≤12 evenly spaced historical revisions (the same at-rev machinery health_trend uses, but with full path coverage — no top-50 cap). validate::validate matches each defect-introducing commit to the nearest band sample at-or-before its date and reports the headline band table plus AUC / precision@k of HEAD’s structural_risk against the defect-implicated file labels.

Unit D — constrained weight tuning

validate::tune_weights runs a deterministic coordinate-descent search over the eight smell weights and only adopts a tuned set when the evidence clears the honesty floor and the acceptance margin — see that function’s rustdoc for the full design decision (biomarker-intensity capture + the Rust-side risk-scoring formula it re-scores candidates with).

Unit E — the artifact

DefectArtifact is a versioned, compact JSON container (mirroring calibration::CalibrationArtifact’s serde style and write idiom). It records the oracle configuration used, mining stats, validation metrics, the (possibly tuned) smell weights, and the tuning decision. save / load round-trip it; check_repo_identity guards against applying an artifact mined from a different repository.

Modules

szz

The AG-SZZ linkage engine: traces each fix commit’s deleted pre-image lines back to the commit that last introduced them, behind a pluggable LineOriginSource seam (the roadmap’s “pluggable SZZ” — this is the first rung; Neural-SZZ/SmartCommit can slot in later without churn).

validate

Historical band scan, validation report, and constrained weight tuning — Units C and D of the own-repo defect-calibration design.

Structs

DefectArtifact

A versioned own-repo defect-calibration artifact (defects.calib.json).

DefectOracle

A pure fix-commit classifier over a commit message.

MiningStats

Mining-phase tallies recorded on every built artifact, whether or not any fixes were found (an empty-linkage artifact is never an error — see the spec’s Error handling section).

OracleConfig

Configuration for DefectOracle. extra_patterns are additional regexes OR’d in alongside the built-in classifiers — for teams with tracker-id conventions (e.g. "JIRA-\\d+"). Defaults to no extra patterns.

ValidationMetrics

Validation-report metrics: does HEAD’s structural risk predict where the mined defects landed? Presentation follows the project’s honesty framing — association, not causation; every number carries its n.

Enums

TuningDecision

The tuning decision recorded on every artifact — which branch of the honesty floor / acceptance test fired, and both AUCs so a reader can judge the outcome even when defaults were kept.

Constants

DEFECT_FORMAT_VERSION

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

Functions

active_vintage

Vintage string of the defect-calibration artifact active for opts. A thin wrapper over active_weights — the one place resolution, the identity guard, and shape validation live — so the provenance stamp and the weight substitution never drift apart (mirrors calibration::active_vintage).

active_weights

Resolve the smell weights active for opts: Some((weights, vintage)) when a --defect-calibration artifact is configured and passes both the repo-identity guard and shape validation; None when no artifact is configured.

check_repo_identity

Guard against applying an artifact mined from a different repository.

load

Read and validate a defect-calibration artifact from path.

repo_identity

SHA-256 hex (all 64 chars) identifying the repository at repo_path — used both to stamp a freshly-mined artifact’s repo_identity and, via check_repo_identity, to verify one before applying it.

save

Serialize artifact as compact JSON and write it to path, creating parent directories as needed.

Type Aliases

WeightsAndVintage

The smell-weight table and artifact vintage resolved by active_weights.