feat(regression): stabilise committed-bundle bytes, fix docs & lint coverage

[lewisjared]

Description

Three orthogonal core/tooling improvements surfaced while doing the ILAMB cmip6 baseline work (handoff from #743). Each is cross-cutting — it affects every provider's regression bundle — so they are grouped here as one small PR with separate commits. None re-runs or re-mints any baselines.

1. Committed-bundle float quantisation (feat). Committed series.json / diagnostic.json stored full-precision float64 whose least-significant digits are platform-dependent (CPU, BLAS, library versions), so they churned byte-for-byte between a local run and a CI mint even when numerically identical. Floats are now rounded to 7 significant figures at write time, in core, so it applies to all providers and to both run and mint. Seven figures is deliberately one digit finer than the rtol=1e-6 regression compare, so the rounding error stays an order of magnitude under tolerance and can never flip a gate verdict. output.json is float-free and left untouched; native blobs and their content-addressed digests are never touched. This is non-breaking without a re-mint: the gate compares values at rtol=1e-6, so 7-s.f. output still matches the existing full-precision baselines — a one-time re-mint to refresh the stored bytes can follow separately whenever convenient.

2. Documentation fixes (docs). Corrected inaccuracies in testing-diagnostics.md (a non-existent TestCase.datasets attribute and three-level resolution priority; the size-flagging attribution, which is ref test-cases run --size-threshold, not a pre-commit hook; and the execution_regression factory + check() example), and filled gaps in regression-baselines.md (the manifest schema field, the check-store verb, CMIP7Request and the cmip7-converted cache, and a note on the new committed-bundle float precision).

3. Pre-commit exclude fix (ci). The .*/regression/.* exclude — intended to skip the committed baseline data — also matched the regression source package (climate_ref_core/regression/) and its unit tests, so ruff never linted them (CI runs only make pre-commit). The pattern is narrowed to data under test-data/ locations so the source is linted like any other code while the baseline bundles stay excluded; zero pre-existing errors surfaced.

Verification

38 new + 191 existing regression unit tests pass; ruff, ruff format and mypy are clean; the full make pre-commit run is green and modifies no files.

Checklist

Please confirm that this pull request has done the following:

• Tests added
• Documentation added (where applicable)
• Changelog item added to changelog/

Summary by CodeRabbit

• New Features

  • Regression baseline outputs now deterministically round floating-point values to 7 significant figures, producing stable committed bundle bytes and matching digests across environments.

• Bug Fixes

  • Committed regression digests now correspond to the rounded JSON bytes to prevent digest mismatches.

• Documentation

  • Updated regression baseline and diagnostic testing guides with clarified schemas, new check-store lifecycle guidance, dataset resolution workflow changes, and float precision details.

• Chores

  • Refined pre-commit exclusions to skip only committed regression baseline data under test-data/, and enabled linting for the regression source and tests.

• Tests

  • Added unit tests covering float quantisation and rounded committed bundle output.

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ef-core/src/climate_ref_core/regression/capture.py	85.71%	1 Missing and 1 partial ⚠️

Flag	Coverage Δ
core	92.60% <92.85%> (+0.02%)	⬆️
providers	91.82% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...-core/src/climate_ref_core/regression/_quantise.py	100.00% <100.00%> (ø)
...ef-core/src/climate_ref_core/regression/capture.py	95.83% <85.71%> (+1.71%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[lewisjared]

@coderabbitai

[coderabbitai]

@lewisjared: Sure! I'll review the changes in this PR.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b7b28b62-844f-4c73-9e6e-5ef90f4eea5f

📥 Commits

Reviewing files that changed from the base of the PR and between d242079 and 6529884.

📒 Files selected for processing (4)

• docs/background/regression-baselines.md
• docs/how-to-guides/testing-diagnostics.md
• packages/climate-ref-core/src/climate_ref_core/regression/_quantise.py
• packages/climate-ref-core/src/climate_ref_core/regression/capture.py

✅ Files skipped from review due to trivial changes (1)

• docs/background/regression-baselines.md

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/climate-ref-core/src/climate_ref_core/regression/_quantise.py
• packages/climate-ref-core/src/climate_ref_core/regression/capture.py
• docs/how-to-guides/testing-diagnostics.md

---

📝 Walkthrough

Walkthrough

Adds a new _quantise.py module with a round_floats utility that recursively rounds floats to 7 significant figures. capture.py is updated to apply this rounding to series.json and diagnostic.json before computing committed-bundle digests. The pre-commit exclude regex is narrowed to target only committed baseline data under test-data/. Documentation and changelogs are updated accordingly.

Changes

Float quantisation for stable committed regression bundle bytes

Layer / File(s)	Summary
round_floats utility module packages/climate-ref-core/src/climate_ref_core/regression/_quantise.py, packages/climate-ref-core/tests/unit/regression/test_quantise.py	New _quantise.py defines DEFAULT_SIG_FIGS = 7 and round_floats, which recursively rounds floats to a configurable number of significant figures whilst preserving booleans, leaving non-float scalars unchanged, and converting tuples to lists. Parametrised unit tests cover rounding, idempotence, passthrough for ints/booleans/strings/None, recursive dict and list traversal, tuple-to-list conversion, custom sig_figs, and numeric stability against the regression comparison tolerance.
Capture integration: round floats before committed-bundle digest packages/climate-ref-core/src/climate_ref_core/regression/capture.py, packages/climate-ref-core/tests/unit/regression/test_capture.py	Adds _COMMITTED_FLOAT_JSON_KWARGS for deterministic JSON serialisation and _round_committed_floats, which reads series.json and diagnostic.json, applies round_floats, and conditionally rewrites the files before write_committed_bundle computes digests. Tests seed both JSON files, call write_committed_bundle, and assert all floats satisfy the 7-sig-fig constraint and that specific fields equal expected rounded values.
Pre-commit exclude regex, docs, and changelogs .pre-commit-config.yaml, docs/background/regression-baselines.md, docs/how-to-guides/testing-diagnostics.md, changelog/744.*.md	Narrows the pre-commit exclude pattern so climate_ref_core.regression source and tests are now linted, with only test-data/ paths excluded. Regression baselines docs gain schema field description, check-store command, CMIP7 test data, and 7-sig-fig float-precision notes. Testing diagnostics guide is updated with revised TestCase attributes, dataset resolution explanation, size-enforcement details, and execution_regression factory fixture usage. Changelogs record all three change categories.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the three main changes: float quantisation in regression bundles, documentation fixes, and pre-commit linting coverage expansion.
Description check	✅ Passed	The description comprehensively covers all required sections: detailed explanations of three improvements, verification details, and a complete checklist with all items marked as done.
Docstring Coverage	✅ Passed	Docstring coverage is 84.21% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/regression-bundle-stability

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ff6d2c9d-82fb-4974-b0f5-cd5ee48aa2f0

📥 Commits

Reviewing files that changed from the base of the PR and between 82aff55 and d242079.

📒 Files selected for processing (10)

• .pre-commit-config.yaml
• changelog/744.docs.md
• changelog/744.improvement.md
• changelog/744.trivial.md
• docs/background/regression-baselines.md
• docs/how-to-guides/testing-diagnostics.md
• packages/climate-ref-core/src/climate_ref_core/regression/_quantise.py
• packages/climate-ref-core/src/climate_ref_core/regression/capture.py
• packages/climate-ref-core/tests/unit/regression/test_capture.py
• packages/climate-ref-core/tests/unit/regression/test_quantise.py