From 9092fec999331a8dc2b58cdf7baaccc20b608175 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Sun, 15 Nov 2026 13:27:34 +0100 Subject: [PATCH 1/5] feat(registry): register the bilateral_reading_unavailable Search warning Search raises bilateral_reading_unavailable on a DAC2a total-ODA part with no provider axis when the bilateral reading cannot apply (the destination population is unavailable, the composite does not cover the window, or it cannot serve a bound slot), so the part reads total ODA and says so. Registered for search.resolve on the raw_text, parsed and dataset_resubmit doors in registries/codes.json and its package mirror. --- python/spec-kit/CHANGELOG.md | 8 ++++++++ .../src/dfo_spec_kit/registry/codes.json | 20 +++++++++++++++++++ registries/codes.json | 20 +++++++++++++++++++ 3 files changed, 48 insertions(+) diff --git a/python/spec-kit/CHANGELOG.md b/python/spec-kit/CHANGELOG.md index 8759c6c..fb81011 100644 --- a/python/spec-kit/CHANGELOG.md +++ b/python/spec-kit/CHANGELOG.md @@ -8,6 +8,14 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and + its bundled mirror: a `search.resolve` warning on the raw_text, parsed and + dataset_resubmit doors. It flags a part reading DAC2a total ODA, such as top + recipients over every donor, whose bilateral-destinations reading cannot + serve it, so its figures include donors' core contributions to multilateral + agencies. Its params name why (`why`): `destination_unclassified`, + `option_not_covered`, `scope_undecided`, or the slot the bilateral composite + cannot serve. - The limit-name registry: `registries/limit-names.json`, its schema `schemas/registry/limit-name-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.LIMIT_NAMES` (a mapping of `LimitName` entries keyed diff --git a/python/spec-kit/src/dfo_spec_kit/registry/codes.json b/python/spec-kit/src/dfo_spec_kit/registry/codes.json index 6b2e802..0d573da 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/codes.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/codes.json @@ -194,6 +194,26 @@ ], "lifecycle": "retired" }, + { + "code": "bilateral_reading_unavailable", + "classification": "warning", + "definition": "A part reading DAC2a total ODA with no provider axis, such as top recipients over every donor, would read its bilateral destinations alone, and that reading cannot serve it, so the figures are total ODA and include donors' core contributions to multilateral agencies. The params name why (why): destination_unclassified where the data holds a destination no side declaration places, option_not_covered where the bilateral reading does not cover every year of the answer, the slot the bilateral composite cannot serve, or scope_undecided where the part's scope could not be decided, so it states no scope.", + "owning_contract": "search", + "owner": "platform", + "introduced_in": "v1", + "mappings": [ + { + "endpoint": "search.resolve", + "doors": [ + "raw_text", + "parsed", + "dataset_resubmit" + ], + "channel": "diagnostics_warning" + } + ], + "lifecycle": "active" + }, { "code": "binding_folded", "classification": "warning", diff --git a/registries/codes.json b/registries/codes.json index 6b2e802..0d573da 100644 --- a/registries/codes.json +++ b/registries/codes.json @@ -194,6 +194,26 @@ ], "lifecycle": "retired" }, + { + "code": "bilateral_reading_unavailable", + "classification": "warning", + "definition": "A part reading DAC2a total ODA with no provider axis, such as top recipients over every donor, would read its bilateral destinations alone, and that reading cannot serve it, so the figures are total ODA and include donors' core contributions to multilateral agencies. The params name why (why): destination_unclassified where the data holds a destination no side declaration places, option_not_covered where the bilateral reading does not cover every year of the answer, the slot the bilateral composite cannot serve, or scope_undecided where the part's scope could not be decided, so it states no scope.", + "owning_contract": "search", + "owner": "platform", + "introduced_in": "v1", + "mappings": [ + { + "endpoint": "search.resolve", + "doors": [ + "raw_text", + "parsed", + "dataset_resubmit" + ], + "channel": "diagnostics_warning" + } + ], + "lifecycle": "active" + }, { "code": "binding_folded", "classification": "warning", From afbf59f466d558665ea91c4d82f01bb64bdbb76e Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Sun, 15 Nov 2026 19:22:39 +0100 Subject: [PATCH 2/5] fix(registry): define bilateral_reading_unavailable without listing its reasons The definition is published once a release carries it, so it states the meaning in client terms and leaves the list of params.why values to the Search API conformance document. It covers a reading as well as an answer, and the undecided case. --- python/spec-kit/CHANGELOG.md | 9 +-------- python/spec-kit/src/dfo_spec_kit/registry/codes.json | 2 +- registries/codes.json | 2 +- 3 files changed, 3 insertions(+), 10 deletions(-) diff --git a/python/spec-kit/CHANGELOG.md b/python/spec-kit/CHANGELOG.md index fb81011..1a86961 100644 --- a/python/spec-kit/CHANGELOG.md +++ b/python/spec-kit/CHANGELOG.md @@ -8,14 +8,7 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and - its bundled mirror: a `search.resolve` warning on the raw_text, parsed and - dataset_resubmit doors. It flags a part reading DAC2a total ODA, such as top - recipients over every donor, whose bilateral-destinations reading cannot - serve it, so its figures include donors' core contributions to multilateral - agencies. Its params name why (`why`): `destination_unclassified`, - `option_not_covered`, `scope_undecided`, or the slot the bilateral composite - cannot serve. +- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason from the values the Search API conformance document lists. - The limit-name registry: `registries/limit-names.json`, its schema `schemas/registry/limit-name-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.LIMIT_NAMES` (a mapping of `LimitName` entries keyed diff --git a/python/spec-kit/src/dfo_spec_kit/registry/codes.json b/python/spec-kit/src/dfo_spec_kit/registry/codes.json index 0d573da..b134ed7 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/codes.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "A part reading DAC2a total ODA with no provider axis, such as top recipients over every donor, would read its bilateral destinations alone, and that reading cannot serve it, so the figures are total ODA and include donors' core contributions to multilateral agencies. The params name why (why): destination_unclassified where the data holds a destination no side declaration places, option_not_covered where the bilateral reading does not cover every year of the answer, the slot the bilateral composite cannot serve, or scope_undecided where the part's scope could not be decided, so it states no scope.", + "definition": "A DAC2a total ODA answer or reading counts every recipient, so its figures include donors' core contributions to multilateral agencies, because its bilateral reading, the bilateral flows to developing countries, is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason from the values the Search API conformance document lists.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", diff --git a/registries/codes.json b/registries/codes.json index 0d573da..b134ed7 100644 --- a/registries/codes.json +++ b/registries/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "A part reading DAC2a total ODA with no provider axis, such as top recipients over every donor, would read its bilateral destinations alone, and that reading cannot serve it, so the figures are total ODA and include donors' core contributions to multilateral agencies. The params name why (why): destination_unclassified where the data holds a destination no side declaration places, option_not_covered where the bilateral reading does not cover every year of the answer, the slot the bilateral composite cannot serve, or scope_undecided where the part's scope could not be decided, so it states no scope.", + "definition": "A DAC2a total ODA answer or reading counts every recipient, so its figures include donors' core contributions to multilateral agencies, because its bilateral reading, the bilateral flows to developing countries, is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason from the values the Search API conformance document lists.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", From b45b9c0c17d177fe27b417bfdbfb195bdba14cfc Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Sun, 15 Nov 2026 19:37:03 +0100 Subject: [PATCH 3/5] feat(registry): list the reasons a warning carries in params.why Add registries/warning-reasons.json with its schema, validator, bundled mirror and the dfo_spec_kit.registry.WARNING_REASONS accessor. It lists the five params.why reasons of bilateral_reading_unavailable: destination_unclassified, option_not_covered, read_window_not_covered, scope_undecided and slot_not_served. The warning's definition now names the provider-axis condition and points at the registry for its reasons. --- .github/workflows/ci.yml | 3 + python/spec-kit/CHANGELOG.md | 3 +- python/spec-kit/EXPORTS.md | 22 ++++ python/spec-kit/pyproject.toml | 1 + .../src/dfo_spec_kit/registry/__init__.py | 37 ++++++ .../src/dfo_spec_kit/registry/codes.json | 2 +- .../registry/warning-reasons.json | 30 +++++ python/spec-kit/tests/test_registry.py | 22 ++++ registries/README.md | 2 + registries/codes.json | 2 +- registries/warning-reasons.json | 30 +++++ schemas/registry/README.md | 4 + .../warning-reason-registry.schema.json | 53 ++++++++ tools/README.md | 6 + tools/validate_warning_reasons.py | 113 ++++++++++++++++++ 15 files changed, 327 insertions(+), 3 deletions(-) create mode 100644 python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json create mode 100644 registries/warning-reasons.json create mode 100644 schemas/registry/warning-reason-registry.schema.json create mode 100644 tools/validate_warning_reasons.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e7db657..36bdc02 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -130,6 +130,9 @@ jobs: - name: Validate limit-name registry run: uv run tools/validate_limit_registry.py + - name: Validate warning-reason registry + run: uv run tools/validate_warning_reasons.py + - name: Test the registry validator run: uv run --with jsonschema --with pyarrow --with pytest pytest tools/tests -q diff --git a/python/spec-kit/CHANGELOG.md b/python/spec-kit/CHANGELOG.md index 1a86961..a242c73 100644 --- a/python/spec-kit/CHANGELOG.md +++ b/python/spec-kit/CHANGELOG.md @@ -8,7 +8,8 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason from the values the Search API conformance document lists. +- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason, one of the values `registries/warning-reasons.json` lists for this code. +- The warning-reason registry: `registries/warning-reasons.json`, its schema `schemas/registry/warning-reason-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.WARNING_REASONS` (a mapping of `WarningReason` entries keyed by code, then reason). It lists the values a warning carries in `params.why`, starting with the five reasons of `bilateral_reading_unavailable`. `tools/validate_warning_reasons.py` checks the file, that each code is registered, and its mirror. - The limit-name registry: `registries/limit-names.json`, its schema `schemas/registry/limit-name-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.LIMIT_NAMES` (a mapping of `LimitName` entries keyed diff --git a/python/spec-kit/EXPORTS.md b/python/spec-kit/EXPORTS.md index b58ce8f..0b98588 100644 --- a/python/spec-kit/EXPORTS.md +++ b/python/spec-kit/EXPORTS.md @@ -243,6 +243,28 @@ kind = "function" stability = "provisional" reason = "bundled-data" +[[export]] +name = "WARNING_REASONS" +module = "dfo_spec_kit.registry" +kind = "constant" +stability = "provisional" +policy = "contents track registries/warning-reasons.json; a reason is added, never redefined" +reason = "bundled-data" + +[[export]] +name = "WarningReason" +module = "dfo_spec_kit.registry" +kind = "model" +stability = "provisional" +reason = "bundled-data" + +[[export]] +name = "load_warning_reasons" +module = "dfo_spec_kit.registry" +kind = "function" +stability = "provisional" +reason = "bundled-data" + # --- dfo_spec_kit.currency --------------------------------------------- # The currency-code shape test, in a module that reads no data file. [[export]] diff --git a/python/spec-kit/pyproject.toml b/python/spec-kit/pyproject.toml index cc7b639..b54554d 100644 --- a/python/spec-kit/pyproject.toml +++ b/python/spec-kit/pyproject.toml @@ -30,6 +30,7 @@ build-backend = "uv_build" source-include = [ "src/dfo_spec_kit/registry/codes.json", "src/dfo_spec_kit/registry/limit-names.json", + "src/dfo_spec_kit/registry/warning-reasons.json", "src/dfo_spec_kit/units/units.json", ] diff --git a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py index 2d77273..2908d27 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py +++ b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py @@ -19,6 +19,11 @@ and checked by `tools/validate_limit_registry.py`) lists the values a `resource_exhausted` problem body carries in `limit_name`. `LIMIT_NAMES` is that registry, keyed by name. + +The warning-reason registry (`registries/warning-reasons.json`, mirrored the +same way and checked by `tools/validate_warning_reasons.py`) lists the values +a warning carries in `params.why`. `WARNING_REASONS` is that registry, keyed +by code and then by reason. """ from __future__ import annotations @@ -169,15 +174,47 @@ def load_limit_names() -> Mapping[str, LimitName]: LIMIT_NAMES: Mapping[str, LimitName] = load_limit_names() + +@dataclass(frozen=True, slots=True) +class WarningReason: + """One reason a warning of `code` can name in `params.why`.""" + + code: str + reason: str + definition: str + + +def load_warning_reasons() -> Mapping[str, Mapping[str, WarningReason]]: + """Load and parse the packaged warning-reason mirror + (`registry/warning-reasons.json`), keyed by code and then by reason.""" + raw_text = ( + resources.files("dfo_spec_kit.registry") + .joinpath("warning-reasons.json") + .read_text(encoding="utf-8") + ) + by_code: dict[str, dict[str, WarningReason]] = {} + for raw in json.loads(raw_text)["entries"]: + entry = WarningReason(**raw) + by_code.setdefault(entry.code, {})[entry.reason] = entry + return MappingProxyType( + {code: MappingProxyType(reasons) for code, reasons in by_code.items()} + ) + + +WARNING_REASONS: Mapping[str, Mapping[str, WarningReason]] = load_warning_reasons() + __all__ = [ "LIMIT_NAMES", "REGISTRY", + "WARNING_REASONS", "Classification", "CodeEntry", "CodeMapping", "CodeRegistry", "Lifecycle", "LimitName", + "WarningReason", "load_limit_names", "load_registry", + "load_warning_reasons", ] diff --git a/python/spec-kit/src/dfo_spec_kit/registry/codes.json b/python/spec-kit/src/dfo_spec_kit/registry/codes.json index b134ed7..1d140a3 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/codes.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "A DAC2a total ODA answer or reading counts every recipient, so its figures include donors' core contributions to multilateral agencies, because its bilateral reading, the bilateral flows to developing countries, is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason from the values the Search API conformance document lists.", + "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the values registries/warning-reasons.json lists for this code.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", diff --git a/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json new file mode 100644 index 0000000..722f6d4 --- /dev/null +++ b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json @@ -0,0 +1,30 @@ +{ + "format_version": 1, + "entries": [ + { + "code": "bilateral_reading_unavailable", + "reason": "destination_unclassified", + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "option_not_covered", + "definition": "The bilateral reading does not cover every year the answer holds." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "read_window_not_covered", + "definition": "The bilateral reading covers the years the answer shows but not every year the request reads." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "scope_undecided", + "definition": "Search could not decide the answer's scope; the condition is transient, and the same request may be retried." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "slot_not_served", + "definition": "The bilateral reading does not serve a slot the answer binds, and params.slot names that slot's property." + } + ] +} diff --git a/python/spec-kit/tests/test_registry.py b/python/spec-kit/tests/test_registry.py index c7182d2..3a16076 100644 --- a/python/spec-kit/tests/test_registry.py +++ b/python/spec-kit/tests/test_registry.py @@ -13,6 +13,7 @@ from dfo_spec_kit.registry import ( LIMIT_NAMES, REGISTRY, + WARNING_REASONS, CodeEntry, CodeMapping, load_registry, @@ -136,3 +137,24 @@ def test_limit_names_are_keyed_by_name() -> None: assert entry.name == "MAX_TABLE_ROWS" assert entry.owning_contract == "presentation" assert all(key == value.name for key, value in LIMIT_NAMES.items()) + + +def test_warning_reasons_mirror_is_byte_identical_to_canonical_registry() -> None: + name = "warning-reasons.json" + assert (_MIRROR_PATH.parent / name).read_bytes() == ( + _REPO_ROOT / "registries" / name + ).read_bytes() + + +def test_warning_reasons_are_keyed_by_code_then_reason() -> None: + entry = WARNING_REASONS["bilateral_reading_unavailable"]["scope_undecided"] + assert (entry.code, entry.reason) == ( + "bilateral_reading_unavailable", + "scope_undecided", + ) + assert all( + code == value.code and reason == value.reason + for code, reasons in WARNING_REASONS.items() + for reason, value in reasons.items() + ) + assert set(WARNING_REASONS) <= REGISTRY.codes diff --git a/registries/README.md b/registries/README.md index e493e06..89d5aee 100644 --- a/registries/README.md +++ b/registries/README.md @@ -6,4 +6,6 @@ This file is the canonical copy. `python/spec-kit/src/dfo_spec_kit/registry/code `limit-names.json` lists the values a `resource_exhausted` problem body carries in `limit_name`, each the name of the limit the request crossed, sorted by name. An entry holds `name`, a one-sentence `definition` and `owning_contract`. `schemas/registry/limit-name-registry.schema.json` validates the file, and `uv run tools/validate_limit_registry.py` also checks the sort order, uniqueness and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/limit-names.json`, read as `dfo_spec_kit.registry.LIMIT_NAMES`; edit this file and copy it there. A name keeps its meaning once published, and a new meaning takes a new name. +`warning-reasons.json` lists the values a warning carries in `params.why`, each the reason the warning of one code fired, sorted by `code` then `reason`. An entry holds `code` (a code in `codes.json`), `reason` (lower snake case, unique within its code) and a one-sentence `definition`. `schemas/registry/warning-reason-registry.schema.json` validates the file, and `uv run tools/validate_warning_reasons.py` also checks the sort order, uniqueness, that each code is registered and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`, read as `dfo_spec_kit.registry.WARNING_REASONS`; edit this file and copy it there. A reason keeps its meaning once published, and a new meaning takes a new reason. + `units.json` declares how unit refs read as typed units, for `dfo_spec_kit.units`. `currency_prefixes` lists the prefixes (`""` and `Currency`) that, followed by a currency code, make a ref money in that currency with prices unstated. After `Currency` a code is any three upper-case ASCII letters. After the empty prefix the code must be one of `currency_codes`, the ISO 4217 active codes without `XTS` (testing) and `XXX` (no currency), plus the withdrawn `ANG`, `BGN` and `ZWL`, which Data Commons still types as `Currency` for older series, so a bare `TEU` or `PPM` reads as other. `units` lists every other typed ref, sorted by `ref`. Money rows carry `currency`, `prices` (`current`, `constant`, or `null` when the ref leaves them unstated) and `evidence`; a row with stated prices also carries `base_year` (`null` when unstated, always `null` for current prices) and `chained` (`true` for a chain-linked series, which only constant prices can be). Percent and count rows carry `ref`, `kind` and `evidence` only. Rate rows state a value per a count of something: `count_base` is that count (`1000` for "per 1,000 people"), and `counted` is what it counts as a plural noun phrase (`people`, `live births`), `null` when the ref states none. The graph holds neither as a field, so each rate row declares them from the ref and its label. `evidence` says where the reading comes from. A ref that scales its values (`SDG_CU_USD_M`, `SDG_NUM_TH`, `PeopleInThousands`) has no row and reads as other, as does any ref that matches no prefix and no row. No row may also match a prefix rule. `schemas/registry/unit-registry.schema.json` validates the file, and `uv run tools/validate_unit_registry.py` also checks the sort order, uniqueness, the prefix rule and the package mirror `python/spec-kit/src/dfo_spec_kit/units/units.json`; edit this file and copy it there. diff --git a/registries/codes.json b/registries/codes.json index b134ed7..1d140a3 100644 --- a/registries/codes.json +++ b/registries/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "A DAC2a total ODA answer or reading counts every recipient, so its figures include donors' core contributions to multilateral agencies, because its bilateral reading, the bilateral flows to developing countries, is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason from the values the Search API conformance document lists.", + "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the values registries/warning-reasons.json lists for this code.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", diff --git a/registries/warning-reasons.json b/registries/warning-reasons.json new file mode 100644 index 0000000..722f6d4 --- /dev/null +++ b/registries/warning-reasons.json @@ -0,0 +1,30 @@ +{ + "format_version": 1, + "entries": [ + { + "code": "bilateral_reading_unavailable", + "reason": "destination_unclassified", + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "option_not_covered", + "definition": "The bilateral reading does not cover every year the answer holds." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "read_window_not_covered", + "definition": "The bilateral reading covers the years the answer shows but not every year the request reads." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "scope_undecided", + "definition": "Search could not decide the answer's scope; the condition is transient, and the same request may be retried." + }, + { + "code": "bilateral_reading_unavailable", + "reason": "slot_not_served", + "definition": "The bilateral reading does not serve a slot the answer binds, and params.slot names that slot's property." + } + ] +} diff --git a/schemas/registry/README.md b/schemas/registry/README.md index 99e3d8b..2fcdc58 100644 --- a/schemas/registry/README.md +++ b/schemas/registry/README.md @@ -112,3 +112,7 @@ The registry has no severity or message template. Each occurrence supplies them ## Limit-name registry `limit-name-registry.schema.json` (draft 2020-12) validates `registries/limit-names.json`, the names a `resource_exhausted` problem body carries in `limit_name`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `name`, and each entry is closed to `name` (upper snake case, unique), `definition` (one sentence) and `owning_contract` (spelled as in the code registry). `uv run tools/validate_limit_registry.py` checks the schema, the sort order, uniqueness and the package mirror. + +## Warning-reason registry + +`warning-reason-registry.schema.json` (draft 2020-12) validates `registries/warning-reasons.json`, the values a warning carries in `params.why`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `code` then `reason`, and each entry is closed to `code` (a code registered in `registries/codes.json`), `reason` (lower snake case, unique within its code) and `definition` (one sentence). `uv run tools/validate_warning_reasons.py` checks the schema, the sort order, uniqueness, that each code is registered and the package mirror. diff --git a/schemas/registry/warning-reason-registry.schema.json b/schemas/registry/warning-reason-registry.schema.json new file mode 100644 index 0000000..a53c913 --- /dev/null +++ b/schemas/registry/warning-reason-registry.schema.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/DevelopmentFinanceObservatory/spec-kit/main/schemas/registry/warning-reason-registry.schema.json", + "title": "Warning-reason registry", + "description": "The values a warning carries in params.why, each the reason the warning of one code fired. See schemas/registry/README.md. tools/validate_warning_reasons.py checks sort order, uniqueness, that each code is registered and the package mirror, which this schema cannot express.", + "type": "object", + "additionalProperties": false, + "required": [ + "format_version", + "entries" + ], + "properties": { + "format_version": { + "description": "The registry format's own version, pinned to the version this schema validates.", + "const": 1 + }, + "entries": { + "description": "Every reason, sorted by code and then reason.", + "type": "array", + "items": { + "$ref": "#/$defs/entry" + } + } + }, + "$defs": { + "entry": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "reason", + "definition" + ], + "properties": { + "code": { + "description": "The warning code in registries/codes.json whose params.why carries the reason.", + "type": "string", + "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" + }, + "reason": { + "description": "The lower-snake-case spelling clients match on, unique within its code.", + "type": "string", + "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" + }, + "definition": { + "description": "One sentence saying what the reason means.", + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/tools/README.md b/tools/README.md index 3f0b572..34d3f8d 100644 --- a/tools/README.md +++ b/tools/README.md @@ -14,6 +14,12 @@ uv run tools/validate_registry.py uv run tools/validate_limit_registry.py ``` +`validate_warning_reasons.py` validates `registries/warning-reasons.json` against `schemas/registry/warning-reason-registry.schema.json` and checks what the schema cannot express: entries sorted by `code` then `reason` with each pair once, every `code` registered in `registries/codes.json`, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: + +```bash +uv run tools/validate_warning_reasons.py +``` + `validate_unit_registry.py` validates `registries/units.json` against `schemas/registry/unit-registry.schema.json` (closed rows per kind, member types and the `format_version` pin) and checks what the schema cannot express: rows sorted by `ref` with each `ref` once, `currency_codes` sorted, no row that also matches a currency prefix rule, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: ```bash diff --git a/tools/validate_warning_reasons.py b/tools/validate_warning_reasons.py new file mode 100644 index 0000000..b7f5c31 --- /dev/null +++ b/tools/validate_warning_reasons.py @@ -0,0 +1,113 @@ +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# "jsonschema>=4.23", +# ] +# /// +"""Validate registries/warning-reasons.json against +schemas/registry/warning-reason-registry.schema.json. + +Run with: uv run tools/validate_warning_reasons.py + +Beyond schema conformance, this checks what the schema cannot express: +entries are sorted by (`code`, `reason`), each `reason` appears once within +its `code`, every `code` is registered in registries/codes.json, and the +packaged mirror (`python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`) +is byte-identical to the canonical file. It does not import `dfo_spec_kit`. +""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path +from typing import Any + +import jsonschema + +REPO_ROOT = Path(__file__).resolve().parent.parent +SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "warning-reason-registry.schema.json" +REGISTRY_PATH = REPO_ROOT / "registries" / "warning-reasons.json" +CODES_PATH = REPO_ROOT / "registries" / "codes.json" +MIRROR_PATH = ( + REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json" +) + + +def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + keys = [key for key, _ in pairs] + duplicates = sorted({key for key in keys if keys.count(key) > 1}) + if duplicates: + raise ValueError(f"duplicate keys {duplicates}") + return dict(pairs) + + +def load_json(path: Path) -> Any: + return json.loads( + path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys + ) + + +def check_schema(registry: Any, schema: Any) -> list[str]: + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator(schema) + return [ + f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " + f"{error.message}" + for error in sorted( + validator.iter_errors(registry), key=lambda e: list(e.absolute_path) + ) + ] + + +def check_entries(registry: dict[str, Any], codes: set[str]) -> list[str]: + """The rules a schema-valid registry must also meet.""" + keys = [(entry["code"], entry["reason"]) for entry in registry["entries"]] + problems: list[str] = [] + if keys != sorted(keys): + problems.append("entries is not sorted by code and reason") + problems.extend( + f"reason declared twice for {code!r}: {reason!r}" + for code, reason in sorted({key for key in keys if keys.count(key) > 1}) + ) + problems.extend( + f"code is not in registries/codes.json: {code!r}" + for code in sorted({code for code, _ in keys} - codes) + ) + return problems + + +def check_mirror() -> list[str]: + if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): + mirror = MIRROR_PATH.relative_to(REPO_ROOT) + canonical = REGISTRY_PATH.relative_to(REPO_ROOT) + return [f"{mirror} is not byte-identical to {canonical}"] + return [] + + +def validate() -> list[str]: + try: + schema = load_json(SCHEMA_PATH) + registry = load_json(REGISTRY_PATH) + codes = {entry["code"] for entry in load_json(CODES_PATH)["entries"]} + except ValueError as exc: + return [f"not valid JSON: {exc}"] + problems = check_schema(registry, schema) + if problems: + return problems + return check_entries(registry, codes) + check_mirror() + + +def main() -> int: + problems = validate() + for problem in problems: + print(f"FAIL: {problem}", file=sys.stderr) + if problems: + return 1 + count = len(load_json(REGISTRY_PATH)["entries"]) + print(f"OK: {count} warning reasons validated") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From 55409dd1284b054038fe03c4d5e4382f692f3d35 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Sun, 15 Nov 2026 20:16:48 +0100 Subject: [PATCH 4/5] fix(registry): enforce published warning reasons and share validator helpers Warning reasons gain a lifecycle and optional params, and tools/validate_warning_reasons.py refuses a reason under a refusal or retired code and, against the latest release tag, a removed or redefined reason. tools/registry_checks.py holds the helpers the registry validators share, and each failure names its file. scope_undecided no longer promises a retry, option_not_covered and read_window_not_covered now differ in what they state, and the code definition names the registry without a repo path. --- CONTRIBUTING.md | 4 +- python/spec-kit/CHANGELOG.md | 4 +- python/spec-kit/EXPORTS.md | 2 +- .../src/dfo_spec_kit/registry/__init__.py | 49 ++++- .../src/dfo_spec_kit/registry/codes.json | 2 +- .../registry/warning-reasons.json | 18 +- python/spec-kit/tests/test_registry.py | 42 ++++- registries/README.md | 2 +- registries/codes.json | 2 +- registries/warning-reasons.json | 18 +- schemas/registry/README.md | 2 +- .../warning-reason-registry.schema.json | 29 ++- tools/README.md | 4 +- tools/registry_checks.py | 142 +++++++++++++++ tools/tests/test_validate_warning_reasons.py | 128 ++++++++++++++ tools/validate_limit_registry.py | 67 ++----- tools/validate_registry.py | 34 +--- tools/validate_unit_registry.py | 68 ++----- tools/validate_warning_reasons.py | 167 ++++++++++++------ 19 files changed, 570 insertions(+), 214 deletions(-) create mode 100644 tools/registry_checks.py create mode 100644 tools/tests/test_validate_warning_reasons.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5468804..b39028f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,8 @@ The validators under `tools/` check the registries and vector suites without imp ```bash uv run tools/validate_registry.py uv run tools/validate_unit_registry.py +uv run tools/validate_limit_registry.py +uv run tools/validate_warning_reasons.py uv run tools/validate_vectors.py uv run tools/validate_frame_vectors.py uv run tools/validate_unit_vectors.py @@ -46,7 +48,7 @@ uv run --with jsonschema --with pyarrow --with pytest pytest tools/tests -q The last command tests the validators themselves. [tools/README.md](tools/README.md) says what each validator checks. Each package's tests drive its implementation against the same vectors or fixtures, and `uv run pytest` runs them. -A change to `registries/codes.json` or `registries/units.json` also needs the packaged mirror under `python/spec-kit/src/dfo_spec_kit/` to match byte for byte. The validators fail if the two differ. Edit the file under `registries/` and copy it to the mirror. [registries/README.md](registries/README.md) has the format. +A change to `registries/codes.json`, `registries/units.json`, `registries/limit-names.json` or `registries/warning-reasons.json` also needs the packaged mirror under `python/spec-kit/src/dfo_spec_kit/` to match byte for byte. The validators fail if the two differ. Edit the file under `registries/` and copy it to the mirror. [registries/README.md](registries/README.md) has the format. ## Branches and commits diff --git a/python/spec-kit/CHANGELOG.md b/python/spec-kit/CHANGELOG.md index a242c73..1b8a23a 100644 --- a/python/spec-kit/CHANGELOG.md +++ b/python/spec-kit/CHANGELOG.md @@ -8,8 +8,8 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason, one of the values `registries/warning-reasons.json` lists for this code. -- The warning-reason registry: `registries/warning-reasons.json`, its schema `schemas/registry/warning-reason-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.WARNING_REASONS` (a mapping of `WarningReason` entries keyed by code, then reason). It lists the values a warning carries in `params.why`, starting with the five reasons of `bilateral_reading_unavailable`. `tools/validate_warning_reasons.py` checks the file, that each code is registered, and its mirror. +- Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason, one of the reasons the warning-reason registry lists for this code, which may add params of its own. +- The warning-reason registry: `registries/warning-reasons.json`, its schema `schemas/registry/warning-reason-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.WARNING_REASONS` (a mapping of `WarningReason` entries keyed by code, then reason). It lists the values a warning carries in `params.why`, starting with the five reasons of `bilateral_reading_unavailable`. Each entry has a `lifecycle` and, where the reason adds params beside `why`, a `params` mapping of param name to definition, read as `WarningReason.params`. `load_warning_reasons` raises `ValueError` on an unknown `format_version` or a reason listed twice for a code. `tools/validate_warning_reasons.py` checks the file, that each code is an active warning for an active reason, that a reason published at the latest release tag keeps its definition and params, and its mirror. The registry validators share `tools/registry_checks.py`, so each FAIL line names the file at fault. - The limit-name registry: `registries/limit-names.json`, its schema `schemas/registry/limit-name-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.LIMIT_NAMES` (a mapping of `LimitName` entries keyed diff --git a/python/spec-kit/EXPORTS.md b/python/spec-kit/EXPORTS.md index 0b98588..7875959 100644 --- a/python/spec-kit/EXPORTS.md +++ b/python/spec-kit/EXPORTS.md @@ -248,7 +248,7 @@ name = "WARNING_REASONS" module = "dfo_spec_kit.registry" kind = "constant" stability = "provisional" -policy = "contents track registries/warning-reasons.json; a reason is added, never redefined" +policy = "contents track registries/warning-reasons.json; a reason is added or retired, never redefined or removed" reason = "bundled-data" [[export]] diff --git a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py index 2908d27..452e430 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py +++ b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py @@ -30,7 +30,7 @@ import json from collections.abc import Mapping -from dataclasses import dataclass +from dataclasses import dataclass, field from importlib import resources from types import MappingProxyType from typing import Any, Literal @@ -177,25 +177,62 @@ def load_limit_names() -> Mapping[str, LimitName]: @dataclass(frozen=True, slots=True) class WarningReason: - """One reason a warning of `code` can name in `params.why`.""" + """One reason a warning of `code` can name in `params.why`. + + `params` maps each param the warning carries beside `why` for this + reason to its one-sentence definition, and is empty when the reason adds + none. + """ code: str reason: str definition: str + lifecycle: Lifecycle + params: Mapping[str, str] = field(default_factory=lambda: MappingProxyType({})) + + +_WARNING_REASONS_FORMAT_VERSION = 1 def load_warning_reasons() -> Mapping[str, Mapping[str, WarningReason]]: """Load and parse the packaged warning-reason mirror - (`registry/warning-reasons.json`), keyed by code and then by reason.""" + (`registry/warning-reasons.json`), keyed by code and then by reason. + + Raises: + ValueError: The file's `format_version` is not the one this loader + reads, or it lists one reason twice for a code. + """ raw_text = ( resources.files("dfo_spec_kit.registry") .joinpath("warning-reasons.json") .read_text(encoding="utf-8") ) + return _warning_reasons_from_json(json.loads(raw_text)) + + +def _warning_reasons_from_json( + data: dict[str, Any], +) -> Mapping[str, Mapping[str, WarningReason]]: + if data["format_version"] != _WARNING_REASONS_FORMAT_VERSION: + raise ValueError( + f"warning-reasons.json has format_version {data['format_version']!r}; " + f"this loader reads {_WARNING_REASONS_FORMAT_VERSION}" + ) by_code: dict[str, dict[str, WarningReason]] = {} - for raw in json.loads(raw_text)["entries"]: - entry = WarningReason(**raw) - by_code.setdefault(entry.code, {})[entry.reason] = entry + for raw in data["entries"]: + entry = WarningReason( + code=raw["code"], + reason=raw["reason"], + definition=raw["definition"], + lifecycle=raw["lifecycle"], + params=MappingProxyType(dict(raw.get("params", {}))), + ) + reasons = by_code.setdefault(entry.code, {}) + if entry.reason in reasons: + raise ValueError( + f"warning-reasons.json lists {entry.code}/{entry.reason} twice" + ) + reasons[entry.reason] = entry return MappingProxyType( {code: MappingProxyType(reasons) for code, reasons in by_code.items()} ) diff --git a/python/spec-kit/src/dfo_spec_kit/registry/codes.json b/python/spec-kit/src/dfo_spec_kit/registry/codes.json index 1d140a3..73ce9ca 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/codes.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the values registries/warning-reasons.json lists for this code.", + "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the reasons spec-kit's warning-reason registry lists for this code, which may add params of its own.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", diff --git a/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json index 722f6d4..537c594 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json @@ -4,27 +4,35 @@ { "code": "bilateral_reading_unavailable", "reason": "destination_unclassified", - "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "option_not_covered", - "definition": "The bilateral reading does not cover every year the answer holds." + "definition": "The bilateral reading lacks a year the answer shows.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "read_window_not_covered", - "definition": "The bilateral reading covers the years the answer shows but not every year the request reads." + "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "scope_undecided", - "definition": "Search could not decide the answer's scope; the condition is transient, and the same request may be retried." + "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "slot_not_served", - "definition": "The bilateral reading does not serve a slot the answer binds, and params.slot names that slot's property." + "definition": "The bilateral reading does not serve a slot the answer binds.", + "params": { + "slot": "The property of the slot the bilateral reading does not serve." + }, + "lifecycle": "active" } ] } diff --git a/python/spec-kit/tests/test_registry.py b/python/spec-kit/tests/test_registry.py index 3a16076..861e634 100644 --- a/python/spec-kit/tests/test_registry.py +++ b/python/spec-kit/tests/test_registry.py @@ -9,6 +9,9 @@ from __future__ import annotations from pathlib import Path +from typing import Any + +import pytest from dfo_spec_kit.registry import ( LIMIT_NAMES, @@ -16,9 +19,17 @@ WARNING_REASONS, CodeEntry, CodeMapping, + _warning_reasons_from_json, load_registry, ) +_REASON = { + "code": "bilateral_reading_unavailable", + "reason": "scope_undecided", + "definition": "A reason.", + "lifecycle": "active", +} + # Repo root is four levels up from this file (tests/ -> spec-kit -> python -> # repo root); the canonical registry is always present in-repo. _REPO_ROOT = Path(__file__).resolve().parents[3] @@ -147,14 +158,37 @@ def test_warning_reasons_mirror_is_byte_identical_to_canonical_registry() -> Non def test_warning_reasons_are_keyed_by_code_then_reason() -> None: - entry = WARNING_REASONS["bilateral_reading_unavailable"]["scope_undecided"] - assert (entry.code, entry.reason) == ( + entry = WARNING_REASONS["bilateral_reading_unavailable"]["slot_not_served"] + assert (entry.code, entry.reason, entry.lifecycle) == ( "bilateral_reading_unavailable", - "scope_undecided", + "slot_not_served", + "active", ) + assert set(entry.params) == {"slot"} assert all( code == value.code and reason == value.reason for code, reasons in WARNING_REASONS.items() for reason, value in reasons.items() ) - assert set(WARNING_REASONS) <= REGISTRY.codes + + +def test_every_warning_reason_names_a_registered_warning() -> None: + for code, reasons in WARNING_REASONS.items(): + entry = REGISTRY[code] + assert entry.classification == "warning", code + if any(reason.lifecycle == "active" for reason in reasons.values()): + assert entry.lifecycle == "active", code + + +@pytest.mark.parametrize( + "data", + [ + pytest.param({"format_version": 2, "entries": []}, id="format-version"), + pytest.param( + {"format_version": 1, "entries": [_REASON, _REASON]}, id="duplicate" + ), + ], +) +def test_warning_reasons_loader_refuses(data: dict[str, Any]) -> None: + with pytest.raises(ValueError): + _warning_reasons_from_json(data) diff --git a/registries/README.md b/registries/README.md index 89d5aee..e35790f 100644 --- a/registries/README.md +++ b/registries/README.md @@ -6,6 +6,6 @@ This file is the canonical copy. `python/spec-kit/src/dfo_spec_kit/registry/code `limit-names.json` lists the values a `resource_exhausted` problem body carries in `limit_name`, each the name of the limit the request crossed, sorted by name. An entry holds `name`, a one-sentence `definition` and `owning_contract`. `schemas/registry/limit-name-registry.schema.json` validates the file, and `uv run tools/validate_limit_registry.py` also checks the sort order, uniqueness and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/limit-names.json`, read as `dfo_spec_kit.registry.LIMIT_NAMES`; edit this file and copy it there. A name keeps its meaning once published, and a new meaning takes a new name. -`warning-reasons.json` lists the values a warning carries in `params.why`, each the reason the warning of one code fired, sorted by `code` then `reason`. An entry holds `code` (a code in `codes.json`), `reason` (lower snake case, unique within its code) and a one-sentence `definition`. `schemas/registry/warning-reason-registry.schema.json` validates the file, and `uv run tools/validate_warning_reasons.py` also checks the sort order, uniqueness, that each code is registered and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`, read as `dfo_spec_kit.registry.WARNING_REASONS`; edit this file and copy it there. A reason keeps its meaning once published, and a new meaning takes a new reason. +`warning-reasons.json` lists the values a warning carries in `params.why`, each the reason the warning of one code fired, sorted by `code` then `reason`. An entry holds `code` (a warning in `codes.json`), `reason` (lower snake case, unique within its code), a one-sentence `definition`, `lifecycle` (`active` or `retired`) and, when the reason makes the warning carry more params beside `why`, `params`, each param name mapped to a one-sentence definition. `schemas/registry/warning-reason-registry.schema.json` validates the file, and `uv run tools/validate_warning_reasons.py` also checks the sort order, uniqueness, that each code is a registered warning and active for an active reason, that a reason published at the latest release tag keeps its definition and params, and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`, read as `dfo_spec_kit.registry.WARNING_REASONS`; edit this file and copy it there. A reason keeps its meaning once published: it may retire, which keeps its spelling reserved, and a new meaning takes a new reason. `units.json` declares how unit refs read as typed units, for `dfo_spec_kit.units`. `currency_prefixes` lists the prefixes (`""` and `Currency`) that, followed by a currency code, make a ref money in that currency with prices unstated. After `Currency` a code is any three upper-case ASCII letters. After the empty prefix the code must be one of `currency_codes`, the ISO 4217 active codes without `XTS` (testing) and `XXX` (no currency), plus the withdrawn `ANG`, `BGN` and `ZWL`, which Data Commons still types as `Currency` for older series, so a bare `TEU` or `PPM` reads as other. `units` lists every other typed ref, sorted by `ref`. Money rows carry `currency`, `prices` (`current`, `constant`, or `null` when the ref leaves them unstated) and `evidence`; a row with stated prices also carries `base_year` (`null` when unstated, always `null` for current prices) and `chained` (`true` for a chain-linked series, which only constant prices can be). Percent and count rows carry `ref`, `kind` and `evidence` only. Rate rows state a value per a count of something: `count_base` is that count (`1000` for "per 1,000 people"), and `counted` is what it counts as a plural noun phrase (`people`, `live births`), `null` when the ref states none. The graph holds neither as a field, so each rate row declares them from the ref and its label. `evidence` says where the reading comes from. A ref that scales its values (`SDG_CU_USD_M`, `SDG_NUM_TH`, `PeopleInThousands`) has no row and reads as other, as does any ref that matches no prefix and no row. No row may also match a prefix rule. `schemas/registry/unit-registry.schema.json` validates the file, and `uv run tools/validate_unit_registry.py` also checks the sort order, uniqueness, the prefix rule and the package mirror `python/spec-kit/src/dfo_spec_kit/units/units.json`; edit this file and copy it there. diff --git a/registries/codes.json b/registries/codes.json index 1d140a3..73ce9ca 100644 --- a/registries/codes.json +++ b/registries/codes.json @@ -197,7 +197,7 @@ { "code": "bilateral_reading_unavailable", "classification": "warning", - "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the values registries/warning-reasons.json lists for this code.", + "definition": "An answer or reading of a published total ODA table, on a part with no provider axis and no provider entry asking for total ODA, reads total ODA, which includes donors' core contributions to multilateral agencies, because its bilateral reading is unavailable or undecided for it. The warning carries the spec_id of the reading it concerns, and params.why names the reason, one of the reasons spec-kit's warning-reason registry lists for this code, which may add params of its own.", "owning_contract": "search", "owner": "platform", "introduced_in": "v1", diff --git a/registries/warning-reasons.json b/registries/warning-reasons.json index 722f6d4..537c594 100644 --- a/registries/warning-reasons.json +++ b/registries/warning-reasons.json @@ -4,27 +4,35 @@ { "code": "bilateral_reading_unavailable", "reason": "destination_unclassified", - "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "option_not_covered", - "definition": "The bilateral reading does not cover every year the answer holds." + "definition": "The bilateral reading lacks a year the answer shows.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "read_window_not_covered", - "definition": "The bilateral reading covers the years the answer shows but not every year the request reads." + "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "scope_undecided", - "definition": "Search could not decide the answer's scope; the condition is transient, and the same request may be retried." + "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA.", + "lifecycle": "active" }, { "code": "bilateral_reading_unavailable", "reason": "slot_not_served", - "definition": "The bilateral reading does not serve a slot the answer binds, and params.slot names that slot's property." + "definition": "The bilateral reading does not serve a slot the answer binds.", + "params": { + "slot": "The property of the slot the bilateral reading does not serve." + }, + "lifecycle": "active" } ] } diff --git a/schemas/registry/README.md b/schemas/registry/README.md index 2fcdc58..31913b3 100644 --- a/schemas/registry/README.md +++ b/schemas/registry/README.md @@ -115,4 +115,4 @@ The registry has no severity or message template. Each occurrence supplies them ## Warning-reason registry -`warning-reason-registry.schema.json` (draft 2020-12) validates `registries/warning-reasons.json`, the values a warning carries in `params.why`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `code` then `reason`, and each entry is closed to `code` (a code registered in `registries/codes.json`), `reason` (lower snake case, unique within its code) and `definition` (one sentence). `uv run tools/validate_warning_reasons.py` checks the schema, the sort order, uniqueness, that each code is registered and the package mirror. +`warning-reason-registry.schema.json` (draft 2020-12) validates `registries/warning-reasons.json`, the values a warning carries in `params.why`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `code` then `reason`, and each entry is closed to `code` (a warning registered in `registries/codes.json`), `reason` (lower snake case, unique within its code), `definition` (one sentence), `lifecycle` (`active` or `retired`) and an optional `params` object mapping each param the warning carries beside `why` for this reason to a one-sentence definition. `params` names no `why` and holds at least one param when present. `uv run tools/validate_warning_reasons.py` checks the schema, the sort order, uniqueness, that each code is a registered warning and active for an active reason, and the package mirror. Once a release tag exists, a reason published there must still be present with the same `definition` and `params`; it may retire, and retired is terminal. diff --git a/schemas/registry/warning-reason-registry.schema.json b/schemas/registry/warning-reason-registry.schema.json index a53c913..3c7c887 100644 --- a/schemas/registry/warning-reason-registry.schema.json +++ b/schemas/registry/warning-reason-registry.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/DevelopmentFinanceObservatory/spec-kit/main/schemas/registry/warning-reason-registry.schema.json", "title": "Warning-reason registry", - "description": "The values a warning carries in params.why, each the reason the warning of one code fired. See schemas/registry/README.md. tools/validate_warning_reasons.py checks sort order, uniqueness, that each code is registered and the package mirror, which this schema cannot express.", + "description": "The values a warning carries in params.why, each the reason the warning of one code fired. See schemas/registry/README.md. tools/validate_warning_reasons.py checks sort order, uniqueness, that each code is a registered warning, that a published reason keeps its definition and params, and the package mirror, which this schema cannot express.", "type": "object", "additionalProperties": false, "required": [ @@ -29,11 +29,12 @@ "required": [ "code", "reason", - "definition" + "definition", + "lifecycle" ], "properties": { "code": { - "description": "The warning code in registries/codes.json whose params.why carries the reason.", + "description": "The warning code in registries/codes.json whose params.why carries the reason. An active reason needs an active code.", "type": "string", "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" }, @@ -46,6 +47,28 @@ "description": "One sentence saying what the reason means.", "type": "string", "minLength": 1 + }, + "params": { + "description": "The params the warning carries beside why when it names this reason, each param name mapped to a one-sentence definition. Omitted when the reason adds none.", + "type": "object", + "minProperties": 1, + "propertyNames": { + "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$", + "not": { + "const": "why" + } + }, + "additionalProperties": { + "type": "string", + "minLength": 1 + } + }, + "lifecycle": { + "description": "active while the warning can carry the reason; retired once it no longer does, which keeps the spelling and its meaning reserved. A published reason is never removed.", + "enum": [ + "active", + "retired" + ] } } } diff --git a/tools/README.md b/tools/README.md index 34d3f8d..067eed9 100644 --- a/tools/README.md +++ b/tools/README.md @@ -14,12 +14,14 @@ uv run tools/validate_registry.py uv run tools/validate_limit_registry.py ``` -`validate_warning_reasons.py` validates `registries/warning-reasons.json` against `schemas/registry/warning-reason-registry.schema.json` and checks what the schema cannot express: entries sorted by `code` then `reason` with each pair once, every `code` registered in `registries/codes.json`, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: +`validate_warning_reasons.py` validates `registries/warning-reasons.json` against `schemas/registry/warning-reason-registry.schema.json` and checks what the schema cannot express: entries sorted by `code` then `reason` with each pair once, every `code` a warning in `registries/codes.json` and an active code for each active reason, and byte-identity with the packaged mirror. Once a release tag is reachable from HEAD, it compares the file with the copy at that tag: a reason published there must keep its `definition` and `params`, may move to `lifecycle: retired`, and may not leave it, while new reasons pass. With no tag it prints the notice `validate_registry.py` prints and skips the comparison. It does not import `dfo_spec_kit`. Also a PEP 723 script: ```bash uv run tools/validate_warning_reasons.py ``` +`registry_checks.py` holds what these registry validators share: JSON loading that refuses a repeated key, schema checking, the mirror comparison, reading a file at the latest release tag, and the NOTE, FAIL and OK lines they print. Every FAIL line names the file at fault. + `validate_unit_registry.py` validates `registries/units.json` against `schemas/registry/unit-registry.schema.json` (closed rows per kind, member types and the `format_version` pin) and checks what the schema cannot express: rows sorted by `ref` with each `ref` once, `currency_codes` sorted, no row that also matches a currency prefix rule, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: ```bash diff --git a/tools/registry_checks.py b/tools/registry_checks.py new file mode 100644 index 0000000..1185294 --- /dev/null +++ b/tools/registry_checks.py @@ -0,0 +1,142 @@ +"""Checks the registry validators share: strict JSON loading, schema +conformance, mirror byte-identity, reading a file at the latest release tag, +and reporting. + +`validate_limit_registry.py`, `validate_unit_registry.py` and +`validate_warning_reasons.py` import this module, and `validate_registry.py` +takes its release-tag helpers from it. A PEP 723 script's own directory is on +`sys.path`, so `uv run tools/.py` finds it, and +`tools/tests/conftest.py` puts `tools/` on the path for the tests. +""" + +from __future__ import annotations + +import json +import subprocess +import sys +from collections import Counter +from collections.abc import Hashable, Iterable +from pathlib import Path +from typing import Any + +import jsonschema + +REPO_ROOT = Path(__file__).resolve().parent.parent + + +class RegistryFileError(Exception): + """A file a validator reads is missing or is not strict JSON. The message + names the file.""" + + +def relative(path: Path) -> str: + """`path` relative to the repo root when it lies inside it.""" + return ( + str(path.relative_to(REPO_ROOT)) + if path.is_relative_to(REPO_ROOT) + else str(path) + ) + + +def duplicates[T: Hashable](values: Iterable[T]) -> list[T]: + """Every value that appears more than once in `values`, sorted.""" + return sorted(value for value, count in Counter(values).items() if count > 1) + + +def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + repeated = duplicates(key for key, _ in pairs) + if repeated: + raise ValueError(f"duplicate keys {repeated}") + return dict(pairs) + + +def parse_json(text: str) -> Any: + """Parse `text`, refusing an object that repeats a key. Raises `ValueError`.""" + return json.loads(text, object_pairs_hook=_reject_duplicate_keys) + + +def load_json(path: Path) -> Any: + """Read and parse `path` once, refusing an object that repeats a key. + + Raises `RegistryFileError` naming the file when it is missing, is not + JSON, or repeats a key. + """ + try: + text = path.read_text(encoding="utf-8") + except FileNotFoundError as exc: + raise RegistryFileError(f"{relative(path)} does not exist") from exc + try: + return parse_json(text) + except ValueError as exc: + raise RegistryFileError(f"{relative(path)} is not valid JSON: {exc}") from exc + + +def check_schema(registry: Any, schema: Any) -> list[str]: + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator(schema) + return [ + f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " + f"{error.message}" + for error in sorted( + validator.iter_errors(registry), key=lambda e: list(e.absolute_path) + ) + ] + + +def check_mirror(canonical: Path, mirror: Path) -> list[str]: + """The package mirror must be byte-identical to the canonical file.""" + for path in (canonical, mirror): + if not path.is_file(): + return [f"{relative(path)} does not exist"] + if mirror.read_bytes() != canonical.read_bytes(): + return [f"{relative(mirror)} is not byte-identical to {relative(canonical)}"] + return [] + + +def latest_release_tag() -> str | None: + """Return the most recent tag reachable from HEAD, or None if there isn't one.""" + try: + result = subprocess.run( + ["git", "describe", "--tags", "--abbrev=0"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=False, + ) + except OSError: + return None + if result.returncode != 0: + return None + tag = result.stdout.strip() + return tag or None + + +def json_at_tag(tag: str, relative_path: str) -> Any | None: + """Return the parsed file at `relative_path` as it existed at `tag`, or + None when the file is absent at the tag or unreadable.""" + result = subprocess.run( + ["git", "show", f"{tag}:{relative_path}"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + return None + try: + return json.loads(result.stdout) + except json.JSONDecodeError: + return None + + +def report(problems: list[str], *, ok: str, notices: Iterable[str] = ()) -> int: + """Print each notice as a NOTE line and each problem as a FAIL line, or + `ok` when there are none, and return the exit status.""" + for notice in notices: + print(f"NOTE: {notice}") + for problem in problems: + print(f"FAIL: {problem}", file=sys.stderr) + if problems: + return 1 + print(f"OK: {ok}") + return 0 diff --git a/tools/tests/test_validate_warning_reasons.py b/tools/tests/test_validate_warning_reasons.py new file mode 100644 index 0000000..bdb5e93 --- /dev/null +++ b/tools/tests/test_validate_warning_reasons.py @@ -0,0 +1,128 @@ +"""Tests for tools/validate_warning_reasons.py: each mutation of the real +registry is one rule the schema, the entry checks or the published-reason +check must refuse. + +Run with: uv run --with jsonschema --with pyarrow --with pytest pytest tools/tests -q +""" + +from __future__ import annotations + +import copy +import importlib.util +import sys +from collections.abc import Callable +from pathlib import Path +from typing import Any + +import pytest + +_MODULE_PATH = Path(__file__).resolve().parent.parent / "validate_warning_reasons.py" +_spec = importlib.util.spec_from_file_location("validate_warning_reasons", _MODULE_PATH) +validate_warning_reasons = importlib.util.module_from_spec(_spec) +sys.modules["validate_warning_reasons"] = validate_warning_reasons +_spec.loader.exec_module(validate_warning_reasons) + +_SCHEMA = validate_warning_reasons.load_json(validate_warning_reasons.SCHEMA_PATH) +_REGISTRY = validate_warning_reasons.load_json(validate_warning_reasons.REGISTRY_PATH) +_CODES, _CODE_PROBLEMS = validate_warning_reasons.read_codes( + validate_warning_reasons.load_json(validate_warning_reasons.CODES_PATH) +) +_CODE = _REGISTRY["entries"][0]["code"] + + +def _problems(registry: dict[str, Any], codes: dict[str, Any]) -> list[str]: + return validate_warning_reasons.check_schema( + registry, _SCHEMA + ) or validate_warning_reasons.check_entries(registry, codes) + + +def _with_code(**changes: str) -> dict[str, Any]: + codes = copy.deepcopy(_CODES) + codes[_CODE].update(changes) + return codes + + +def test_committed_registry_is_valid() -> None: + assert _CODE_PROBLEMS == [] + assert _problems(_REGISTRY, _CODES) == [] + assert validate_warning_reasons.check_mirror() == [] + + +@pytest.mark.parametrize( + ("mutate", "codes"), + [ + pytest.param(lambda r: r["entries"].reverse(), _CODES, id="unsorted"), + pytest.param( + lambda r: r["entries"].insert(0, copy.deepcopy(r["entries"][0])), + _CODES, + id="duplicate-reason", + ), + pytest.param( + lambda r: None, + {k: v for k, v in _CODES.items() if k != _CODE}, + id="unregistered-code", + ), + pytest.param( + lambda r: None, _with_code(classification="refusal"), id="refusal-code" + ), + pytest.param( + lambda r: None, _with_code(lifecycle="retired"), id="retired-code" + ), + pytest.param( + lambda r: r["entries"][0].update(reason="Destination_unclassified"), + _CODES, + id="upper-case-reason", + ), + pytest.param( + lambda r: r["entries"][0].update(extra=1), _CODES, id="extra-member" + ), + ], +) +def test_refuses( + mutate: Callable[[dict[str, Any]], None], codes: dict[str, Any] +) -> None: + registry = copy.deepcopy(_REGISTRY) + mutate(registry) + assert _problems(registry, codes) + + +def _changed_since_tag( + mutate: Callable[[list[dict[str, Any]]], None], +) -> list[str]: + entries = copy.deepcopy(_REGISTRY["entries"]) + mutate(entries) + return validate_warning_reasons.check_published( + entries, _REGISTRY["entries"], "v9.9.9" + ) + + +@pytest.mark.parametrize( + "mutate", + [ + pytest.param(lambda e: e.pop(0), id="removed-reason"), + pytest.param( + lambda e: e[0].update(definition="A different meaning."), + id="redefined-reason", + ), + pytest.param( + lambda e: next(x for x in e if "params" in x)["params"].update( + other="Another param." + ), + id="params-changed", + ), + ], +) +def test_refuses_against_tag(mutate: Callable[[list[dict[str, Any]]], None]) -> None: + assert _changed_since_tag(mutate) + + +def test_retiring_a_published_reason_passes() -> None: + assert _changed_since_tag(lambda e: e[0].update(lifecycle="retired")) == [] + + +def test_refuses_reactivating_a_retired_reason() -> None: + published = copy.deepcopy(_REGISTRY["entries"]) + published[0]["lifecycle"] = "retired" + assert validate_warning_reasons.check_published( + _REGISTRY["entries"], published, "v9.9.9" + ) diff --git a/tools/validate_limit_registry.py b/tools/validate_limit_registry.py index 463d814..e388e34 100644 --- a/tools/validate_limit_registry.py +++ b/tools/validate_limit_registry.py @@ -17,12 +17,18 @@ from __future__ import annotations -import json import sys from pathlib import Path from typing import Any -import jsonschema +import registry_checks +from registry_checks import ( + RegistryFileError, + check_schema, + duplicates, + load_json, + report, +) REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "limit-name-registry.schema.json" @@ -30,32 +36,6 @@ MIRROR_PATH = REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/registry/limit-names.json" -def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: - keys = [key for key, _ in pairs] - duplicates = sorted({key for key in keys if keys.count(key) > 1}) - if duplicates: - raise ValueError(f"duplicate keys {duplicates}") - return dict(pairs) - - -def load_json(path: Path) -> Any: - return json.loads( - path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys - ) - - -def check_schema(registry: Any, schema: Any) -> list[str]: - jsonschema.Draft202012Validator.check_schema(schema) - validator = jsonschema.Draft202012Validator(schema) - return [ - f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " - f"{error.message}" - for error in sorted( - validator.iter_errors(registry), key=lambda e: list(e.absolute_path) - ) - ] - - def check_entries(registry: dict[str, Any]) -> list[str]: """The rules a schema-valid registry must also meet.""" names = [entry["name"] for entry in registry["entries"]] @@ -63,41 +43,32 @@ def check_entries(registry: dict[str, Any]) -> list[str]: if names != sorted(names): problems.append("entries is not sorted by name") problems.extend( - f"limit name declared twice: {name!r}" - for name in sorted({name for name in names if names.count(name) > 1}) + f"limit name declared twice: {name!r}" for name in duplicates(names) ) return problems def check_mirror() -> list[str]: - if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): - mirror = MIRROR_PATH.relative_to(REPO_ROOT) - canonical = REGISTRY_PATH.relative_to(REPO_ROOT) - return [f"{mirror} is not byte-identical to {canonical}"] - return [] + return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) -def validate() -> list[str]: +def validate() -> tuple[list[str], Any]: + """The problems found, and the parsed registry (None when unreadable).""" try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - except ValueError as exc: - return [f"not valid JSON: {exc}"] + except RegistryFileError as exc: + return [str(exc)], None problems = check_schema(registry, schema) if problems: - return problems - return check_entries(registry) + check_mirror() + return problems, registry + return check_entries(registry) + check_mirror(), registry def main() -> int: - problems = validate() - for problem in problems: - print(f"FAIL: {problem}", file=sys.stderr) - if problems: - return 1 - count = len(load_json(REGISTRY_PATH)["entries"]) - print(f"OK: {count} limit names validated") - return 0 + problems, registry = validate() + count = 0 if problems else len(registry["entries"]) + return report(problems, ok=f"{count} limit names validated") if __name__ == "__main__": diff --git a/tools/validate_registry.py b/tools/validate_registry.py index 041aea8..7c889c8 100644 --- a/tools/validate_registry.py +++ b/tools/validate_registry.py @@ -22,12 +22,12 @@ from __future__ import annotations import json -import subprocess import sys from pathlib import Path from typing import Any import jsonschema +from registry_checks import json_at_tag, latest_release_tag REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "code-registry.schema.json" @@ -203,39 +203,9 @@ def check_mirror() -> list[str]: return [] -def latest_release_tag() -> str | None: - """Return the most recent tag reachable from HEAD, or None if there isn't one.""" - try: - result = subprocess.run( - ["git", "describe", "--tags", "--abbrev=0"], - cwd=REPO_ROOT, - capture_output=True, - text=True, - check=False, - ) - except OSError: - return None - if result.returncode != 0: - return None - tag = result.stdout.strip() - return tag or None - - def registry_at_tag(tag: str) -> Any | None: """Return the parsed registry as it existed at `tag`, or None if unreadable.""" - result = subprocess.run( - ["git", "show", f"{tag}:{REGISTRY_RELATIVE_PATH}"], - cwd=REPO_ROOT, - capture_output=True, - text=True, - check=False, - ) - if result.returncode != 0: - return None - try: - return json.loads(result.stdout) - except json.JSONDecodeError: - return None + return json_at_tag(tag, REGISTRY_RELATIVE_PATH) def _doors_set(mapping: dict[str, Any]) -> frozenset[str] | None: diff --git a/tools/validate_unit_registry.py b/tools/validate_unit_registry.py index bc2d6ce..48a458f 100644 --- a/tools/validate_unit_registry.py +++ b/tools/validate_unit_registry.py @@ -18,12 +18,18 @@ from __future__ import annotations -import json import sys from pathlib import Path from typing import Any -import jsonschema +import registry_checks +from registry_checks import ( + RegistryFileError, + check_schema, + duplicates, + load_json, + report, +) REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "unit-registry.schema.json" @@ -31,32 +37,6 @@ MIRROR_PATH = REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/units/units.json" -def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: - keys = [key for key, _ in pairs] - duplicates = sorted({key for key in keys if keys.count(key) > 1}) - if duplicates: - raise ValueError(f"duplicate keys {duplicates}") - return dict(pairs) - - -def load_json(path: Path) -> Any: - return json.loads( - path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys - ) - - -def check_schema(registry: Any, schema: Any) -> list[str]: - jsonschema.Draft202012Validator.check_schema(schema) - validator = jsonschema.Draft202012Validator(schema) - return [ - f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " - f"{error.message}" - for error in sorted( - validator.iter_errors(registry), key=lambda e: list(e.absolute_path) - ) - ] - - def _is_code_shape(value: str) -> bool: return len(value) == 3 and value.isascii() and value.isalpha() and value.isupper() @@ -85,10 +65,7 @@ def check_rows(registry: dict[str, Any]) -> list[str]: refs = [row["ref"] for row in registry["units"]] if refs != sorted(refs): problems.append("units is not sorted by ref") - problems.extend( - f"unit ref declared twice: {ref!r}" - for ref in sorted({ref for ref in refs if refs.count(ref) > 1}) - ) + problems.extend(f"unit ref declared twice: {ref!r}" for ref in duplicates(refs)) code_set = frozenset(codes) problems.extend( f"unit ref {ref!r} is declared and matches a prefix rule" @@ -99,33 +76,26 @@ def check_rows(registry: dict[str, Any]) -> list[str]: def check_mirror() -> list[str]: - if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): - mirror = MIRROR_PATH.relative_to(REPO_ROOT) - canonical = REGISTRY_PATH.relative_to(REPO_ROOT) - return [f"{mirror} is not byte-identical to {canonical}"] - return [] + return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) -def validate() -> list[str]: +def validate() -> tuple[list[str], Any]: + """The problems found, and the parsed registry (None when unreadable).""" try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - except ValueError as exc: - return [f"not valid JSON: {exc}"] + except RegistryFileError as exc: + return [str(exc)], None problems = check_schema(registry, schema) if problems: - return problems - return check_rows(registry) + check_mirror() + return problems, registry + return check_rows(registry) + check_mirror(), registry def main() -> int: - problems = validate() - for problem in problems: - print(f"FAIL: {problem}", file=sys.stderr) - if problems: - return 1 - print(f"OK: {len(load_json(REGISTRY_PATH)['units'])} unit registry rows validated") - return 0 + problems, registry = validate() + count = 0 if problems else len(registry["units"]) + return report(problems, ok=f"{count} unit registry rows validated") if __name__ == "__main__": diff --git a/tools/validate_warning_reasons.py b/tools/validate_warning_reasons.py index b7f5c31..1dfc3b3 100644 --- a/tools/validate_warning_reasons.py +++ b/tools/validate_warning_reasons.py @@ -11,19 +11,32 @@ Beyond schema conformance, this checks what the schema cannot express: entries are sorted by (`code`, `reason`), each `reason` appears once within -its `code`, every `code` is registered in registries/codes.json, and the -packaged mirror (`python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`) -is byte-identical to the canonical file. It does not import `dfo_spec_kit`. +its `code`, every `code` is a warning in registries/codes.json (an active +code for an active reason), and the packaged mirror +(`python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`) is +byte-identical to the canonical file. Once a release tag is reachable from +HEAD, a reason published at that tag must still be present with the same +definition and params; it may move to `lifecycle: retired`, and retired is +terminal. It does not import `dfo_spec_kit`. """ from __future__ import annotations -import json import sys from pathlib import Path from typing import Any -import jsonschema +import registry_checks +from registry_checks import ( + RegistryFileError, + check_schema, + duplicates, + json_at_tag, + latest_release_tag, + load_json, + relative, + report, +) REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "warning-reason-registry.schema.json" @@ -33,34 +46,35 @@ REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json" ) - -def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: - keys = [key for key, _ in pairs] - duplicates = sorted({key for key in keys if keys.count(key) > 1}) - if duplicates: - raise ValueError(f"duplicate keys {duplicates}") - return dict(pairs) +# Each registered code mapped to its codes.json entry. +type Codes = dict[str, dict[str, Any]] -def load_json(path: Path) -> Any: - return json.loads( - path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys +def read_codes(codes_registry: Any) -> tuple[Codes, list[str]]: + """Each code in a parsed codes.json, and a problem naming the file for + every entry that lacks the members this validator reads.""" + where = relative(CODES_PATH) + entries = ( + codes_registry.get("entries") if isinstance(codes_registry, dict) else None ) - - -def check_schema(registry: Any, schema: Any) -> list[str]: - jsonschema.Draft202012Validator.check_schema(schema) - validator = jsonschema.Draft202012Validator(schema) - return [ - f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " - f"{error.message}" - for error in sorted( - validator.iter_errors(registry), key=lambda e: list(e.absolute_path) - ) - ] - - -def check_entries(registry: dict[str, Any], codes: set[str]) -> list[str]: + if not isinstance(entries, list): + return {}, [f"{where}: has no entries list"] + codes: Codes = {} + problems: list[str] = [] + for index, entry in enumerate(entries): + missing = [ + key + for key in ("code", "classification", "lifecycle") + if not isinstance(entry, dict) or key not in entry + ] + if missing: + problems.append(f"{where}: entries/{index} lacks {missing}") + else: + codes[entry["code"]] = entry + return codes, problems + + +def check_entries(registry: dict[str, Any], codes: Codes) -> list[str]: """The rules a schema-valid registry must also meet.""" keys = [(entry["code"], entry["reason"]) for entry in registry["entries"]] problems: list[str] = [] @@ -68,45 +82,92 @@ def check_entries(registry: dict[str, Any], codes: set[str]) -> list[str]: problems.append("entries is not sorted by code and reason") problems.extend( f"reason declared twice for {code!r}: {reason!r}" - for code, reason in sorted({key for key in keys if keys.count(key) > 1}) + for code, reason in duplicates(keys) ) + for code in sorted({code for code, _ in keys}): + code_entry = codes.get(code) + if code_entry is None: + problems.append(f"code is not in registries/codes.json: {code!r}") + elif code_entry["classification"] != "warning": + problems.append(f"code is not a warning: {code!r}") problems.extend( - f"code is not in registries/codes.json: {code!r}" - for code in sorted({code for code, _ in keys} - codes) + f"active reason {entry['reason']!r} names retired code {entry['code']!r}" + for entry in registry["entries"] + if entry["lifecycle"] == "active" + and codes.get(entry["code"], {}).get("lifecycle") == "retired" ) return problems +def check_published( + entries: list[dict[str, Any]], published: list[dict[str, Any]], tag: str +) -> list[str]: + """Every reason in `published` (the entries at `tag`) is still present with + the same definition and params, and a retired one stays retired.""" + current = {(entry["code"], entry["reason"]): entry for entry in entries} + problems: list[str] = [] + for old in published: + label = f"{old['code']}/{old['reason']}" + new = current.get((old["code"], old["reason"])) + if new is None: + problems.append( + f"{label}: published reason was removed (present at tag {tag!r})" + ) + continue + problems.extend( + f"{label}: {member} changed since tag {tag!r}" + for member in ("definition", "params") + if old.get(member) != new.get(member) + ) + if old.get("lifecycle") == "retired" and new["lifecycle"] != "retired": + problems.append(f"{label}: lifecycle left retired, which is terminal") + return problems + + +def check_immutability( + entries: list[dict[str, Any]], +) -> tuple[str | None, list[str]]: + """Compare `entries` with the registry at the latest release tag. + + Returns (notice, problems). The notice, printed on stdout, says why the + comparison was skipped; it is never a failure. + """ + tag = latest_release_tag() + if tag is None: + return "no release tag yet; immutability check skipped", [] + path = relative(REGISTRY_PATH) + published = json_at_tag(tag, path) + if published is None: + return f"could not read {path} at tag {tag!r}; immutability check skipped", [] + return None, check_published(entries, published.get("entries", []), tag) + + def check_mirror() -> list[str]: - if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): - mirror = MIRROR_PATH.relative_to(REPO_ROOT) - canonical = REGISTRY_PATH.relative_to(REPO_ROOT) - return [f"{mirror} is not byte-identical to {canonical}"] - return [] + return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) -def validate() -> list[str]: +def validate() -> tuple[list[str], list[str], Any]: + """The problems found, the notices to print, and the parsed registry (None + when unreadable).""" try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - codes = {entry["code"] for entry in load_json(CODES_PATH)["entries"]} - except ValueError as exc: - return [f"not valid JSON: {exc}"] - problems = check_schema(registry, schema) + codes_registry = load_json(CODES_PATH) + except RegistryFileError as exc: + return [str(exc)], [], None + codes, problems = read_codes(codes_registry) + problems += check_schema(registry, schema) if problems: - return problems - return check_entries(registry, codes) + check_mirror() + return problems, [], registry + notice, published_problems = check_immutability(registry["entries"]) + problems = check_entries(registry, codes) + check_mirror() + published_problems + return problems, [notice] if notice else [], registry def main() -> int: - problems = validate() - for problem in problems: - print(f"FAIL: {problem}", file=sys.stderr) - if problems: - return 1 - count = len(load_json(REGISTRY_PATH)["entries"]) - print(f"OK: {count} warning reasons validated") - return 0 + problems, notices, registry = validate() + count = 0 if problems else len(registry["entries"]) + return report(problems, ok=f"{count} warning reasons validated", notices=notices) if __name__ == "__main__": From 7c4593567f5365e613cbdb6621b277c0cab0fbb9 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Sun, 15 Nov 2026 20:36:35 +0100 Subject: [PATCH 5/5] refactor(registry): keep the warning-reason registry to the limit-name pattern The warning-reason validator checks what the limit-name validator checks, plus that each code is an active warning, and the three older validators are as on dev. Reasons carry no lifecycle, and WarningReason holds its params as sorted pairs so it is hashable. --- python/spec-kit/CHANGELOG.md | 2 +- python/spec-kit/EXPORTS.md | 2 +- .../src/dfo_spec_kit/registry/__init__.py | 14 +- .../registry/warning-reasons.json | 15 +- python/spec-kit/tests/test_registry.py | 26 +-- registries/README.md | 2 +- registries/warning-reasons.json | 15 +- schemas/registry/README.md | 2 +- .../warning-reason-registry.schema.json | 14 +- tools/README.md | 4 +- tools/registry_checks.py | 142 -------------- tools/tests/test_validate_warning_reasons.py | 85 ++------ tools/validate_limit_registry.py | 67 +++++-- tools/validate_registry.py | 34 +++- tools/validate_unit_registry.py | 68 +++++-- tools/validate_warning_reasons.py | 181 +++++++----------- 16 files changed, 246 insertions(+), 427 deletions(-) delete mode 100644 tools/registry_checks.py diff --git a/python/spec-kit/CHANGELOG.md b/python/spec-kit/CHANGELOG.md index 1b8a23a..79620d9 100644 --- a/python/spec-kit/CHANGELOG.md +++ b/python/spec-kit/CHANGELOG.md @@ -9,7 +9,7 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Warning code `bilateral_reading_unavailable` in `registries/codes.json` and its bundled mirror: a `search.resolve` warning on the raw_text, parsed and dataset_resubmit doors. It marks a DAC2a total ODA answer or reading whose bilateral reading is unavailable or undecided, so its figures include donors' core contributions to multilateral agencies. It carries the reading's spec_id, and `params.why` names the reason, one of the reasons the warning-reason registry lists for this code, which may add params of its own. -- The warning-reason registry: `registries/warning-reasons.json`, its schema `schemas/registry/warning-reason-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.WARNING_REASONS` (a mapping of `WarningReason` entries keyed by code, then reason). It lists the values a warning carries in `params.why`, starting with the five reasons of `bilateral_reading_unavailable`. Each entry has a `lifecycle` and, where the reason adds params beside `why`, a `params` mapping of param name to definition, read as `WarningReason.params`. `load_warning_reasons` raises `ValueError` on an unknown `format_version` or a reason listed twice for a code. `tools/validate_warning_reasons.py` checks the file, that each code is an active warning for an active reason, that a reason published at the latest release tag keeps its definition and params, and its mirror. The registry validators share `tools/registry_checks.py`, so each FAIL line names the file at fault. +- The warning-reason registry: `registries/warning-reasons.json`, its schema `schemas/registry/warning-reason-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.WARNING_REASONS` (a mapping of `WarningReason` entries keyed by code, then reason). It lists the values a warning carries in `params.why`, starting with the five reasons of `bilateral_reading_unavailable`. Where a reason adds params beside `why`, `WarningReason.params` holds them as (name, definition) pairs sorted by name. `load_warning_reasons` raises `ValueError` on an unknown `format_version` or a reason listed twice for a code. `tools/validate_warning_reasons.py` checks the file, that each code is an active warning, and its mirror. - The limit-name registry: `registries/limit-names.json`, its schema `schemas/registry/limit-name-registry.schema.json`, a bundled mirror, and `dfo_spec_kit.registry.LIMIT_NAMES` (a mapping of `LimitName` entries keyed diff --git a/python/spec-kit/EXPORTS.md b/python/spec-kit/EXPORTS.md index 7875959..0b98588 100644 --- a/python/spec-kit/EXPORTS.md +++ b/python/spec-kit/EXPORTS.md @@ -248,7 +248,7 @@ name = "WARNING_REASONS" module = "dfo_spec_kit.registry" kind = "constant" stability = "provisional" -policy = "contents track registries/warning-reasons.json; a reason is added or retired, never redefined or removed" +policy = "contents track registries/warning-reasons.json; a reason is added, never redefined" reason = "bundled-data" [[export]] diff --git a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py index 452e430..27cc998 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/__init__.py +++ b/python/spec-kit/src/dfo_spec_kit/registry/__init__.py @@ -30,7 +30,7 @@ import json from collections.abc import Mapping -from dataclasses import dataclass, field +from dataclasses import dataclass from importlib import resources from types import MappingProxyType from typing import Any, Literal @@ -179,16 +179,15 @@ def load_limit_names() -> Mapping[str, LimitName]: class WarningReason: """One reason a warning of `code` can name in `params.why`. - `params` maps each param the warning carries beside `why` for this - reason to its one-sentence definition, and is empty when the reason adds - none. + `params` lists each param the warning carries beside `why` for this + reason as a (name, definition) pair, sorted by name, and is empty when + the reason adds none. """ code: str reason: str definition: str - lifecycle: Lifecycle - params: Mapping[str, str] = field(default_factory=lambda: MappingProxyType({})) + params: tuple[tuple[str, str], ...] = () _WARNING_REASONS_FORMAT_VERSION = 1 @@ -224,8 +223,7 @@ def _warning_reasons_from_json( code=raw["code"], reason=raw["reason"], definition=raw["definition"], - lifecycle=raw["lifecycle"], - params=MappingProxyType(dict(raw.get("params", {}))), + params=tuple(sorted(raw.get("params", {}).items())), ) reasons = by_code.setdefault(entry.code, {}) if entry.reason in reasons: diff --git a/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json index 537c594..32a5e7d 100644 --- a/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json +++ b/python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json @@ -4,26 +4,22 @@ { "code": "bilateral_reading_unavailable", "reason": "destination_unclassified", - "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest.", - "lifecycle": "active" + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." }, { "code": "bilateral_reading_unavailable", "reason": "option_not_covered", - "definition": "The bilateral reading lacks a year the answer shows.", - "lifecycle": "active" + "definition": "The bilateral reading lacks a year the answer shows." }, { "code": "bilateral_reading_unavailable", "reason": "read_window_not_covered", - "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them.", - "lifecycle": "active" + "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them." }, { "code": "bilateral_reading_unavailable", "reason": "scope_undecided", - "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA.", - "lifecycle": "active" + "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA." }, { "code": "bilateral_reading_unavailable", @@ -31,8 +27,7 @@ "definition": "The bilateral reading does not serve a slot the answer binds.", "params": { "slot": "The property of the slot the bilateral reading does not serve." - }, - "lifecycle": "active" + } } ] } diff --git a/python/spec-kit/tests/test_registry.py b/python/spec-kit/tests/test_registry.py index 861e634..b4be8d7 100644 --- a/python/spec-kit/tests/test_registry.py +++ b/python/spec-kit/tests/test_registry.py @@ -27,7 +27,6 @@ "code": "bilateral_reading_unavailable", "reason": "scope_undecided", "definition": "A reason.", - "lifecycle": "active", } # Repo root is four levels up from this file (tests/ -> spec-kit -> python -> @@ -136,8 +135,8 @@ def test_entries_are_sorted_by_code() -> None: assert codes == sorted(codes) -def test_limit_names_mirror_is_byte_identical_to_canonical_registry() -> None: - name = "limit-names.json" +@pytest.mark.parametrize("name", ["limit-names.json", "warning-reasons.json"]) +def test_mirror_is_byte_identical_to_canonical_registry_file(name: str) -> None: assert (_MIRROR_PATH.parent / name).read_bytes() == ( _REPO_ROOT / "registries" / name ).read_bytes() @@ -150,21 +149,13 @@ def test_limit_names_are_keyed_by_name() -> None: assert all(key == value.name for key, value in LIMIT_NAMES.items()) -def test_warning_reasons_mirror_is_byte_identical_to_canonical_registry() -> None: - name = "warning-reasons.json" - assert (_MIRROR_PATH.parent / name).read_bytes() == ( - _REPO_ROOT / "registries" / name - ).read_bytes() - - def test_warning_reasons_are_keyed_by_code_then_reason() -> None: entry = WARNING_REASONS["bilateral_reading_unavailable"]["slot_not_served"] - assert (entry.code, entry.reason, entry.lifecycle) == ( + assert (entry.code, entry.reason) == ( "bilateral_reading_unavailable", "slot_not_served", - "active", ) - assert set(entry.params) == {"slot"} + assert [name for name, _ in entry.params] == ["slot"] assert all( code == value.code and reason == value.reason for code, reasons in WARNING_REASONS.items() @@ -172,12 +163,9 @@ def test_warning_reasons_are_keyed_by_code_then_reason() -> None: ) -def test_every_warning_reason_names_a_registered_warning() -> None: - for code, reasons in WARNING_REASONS.items(): - entry = REGISTRY[code] - assert entry.classification == "warning", code - if any(reason.lifecycle == "active" for reason in reasons.values()): - assert entry.lifecycle == "active", code +def test_warning_reasons_are_hashable() -> None: + entry = WARNING_REASONS["bilateral_reading_unavailable"]["slot_not_served"] + assert hash(entry) == hash(entry) @pytest.mark.parametrize( diff --git a/registries/README.md b/registries/README.md index e35790f..50f5225 100644 --- a/registries/README.md +++ b/registries/README.md @@ -6,6 +6,6 @@ This file is the canonical copy. `python/spec-kit/src/dfo_spec_kit/registry/code `limit-names.json` lists the values a `resource_exhausted` problem body carries in `limit_name`, each the name of the limit the request crossed, sorted by name. An entry holds `name`, a one-sentence `definition` and `owning_contract`. `schemas/registry/limit-name-registry.schema.json` validates the file, and `uv run tools/validate_limit_registry.py` also checks the sort order, uniqueness and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/limit-names.json`, read as `dfo_spec_kit.registry.LIMIT_NAMES`; edit this file and copy it there. A name keeps its meaning once published, and a new meaning takes a new name. -`warning-reasons.json` lists the values a warning carries in `params.why`, each the reason the warning of one code fired, sorted by `code` then `reason`. An entry holds `code` (a warning in `codes.json`), `reason` (lower snake case, unique within its code), a one-sentence `definition`, `lifecycle` (`active` or `retired`) and, when the reason makes the warning carry more params beside `why`, `params`, each param name mapped to a one-sentence definition. `schemas/registry/warning-reason-registry.schema.json` validates the file, and `uv run tools/validate_warning_reasons.py` also checks the sort order, uniqueness, that each code is a registered warning and active for an active reason, that a reason published at the latest release tag keeps its definition and params, and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`, read as `dfo_spec_kit.registry.WARNING_REASONS`; edit this file and copy it there. A reason keeps its meaning once published: it may retire, which keeps its spelling reserved, and a new meaning takes a new reason. +`warning-reasons.json` lists the values a warning carries in `params.why`, each the reason the warning of one code fired, sorted by `code` then `reason`. An entry holds `code` (an active warning in `codes.json`), `reason` (lower snake case, unique within its code), a one-sentence `definition` and, when the reason makes the warning carry more params beside `why`, `params`, each param name mapped to a one-sentence definition. `schemas/registry/warning-reason-registry.schema.json` validates the file, and `uv run tools/validate_warning_reasons.py` also checks the sort order, uniqueness, that each code is an active warning and the package mirror `python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`, read as `dfo_spec_kit.registry.WARNING_REASONS`; edit this file and copy it there. A reason keeps its meaning once published, and a new meaning takes a new reason. `units.json` declares how unit refs read as typed units, for `dfo_spec_kit.units`. `currency_prefixes` lists the prefixes (`""` and `Currency`) that, followed by a currency code, make a ref money in that currency with prices unstated. After `Currency` a code is any three upper-case ASCII letters. After the empty prefix the code must be one of `currency_codes`, the ISO 4217 active codes without `XTS` (testing) and `XXX` (no currency), plus the withdrawn `ANG`, `BGN` and `ZWL`, which Data Commons still types as `Currency` for older series, so a bare `TEU` or `PPM` reads as other. `units` lists every other typed ref, sorted by `ref`. Money rows carry `currency`, `prices` (`current`, `constant`, or `null` when the ref leaves them unstated) and `evidence`; a row with stated prices also carries `base_year` (`null` when unstated, always `null` for current prices) and `chained` (`true` for a chain-linked series, which only constant prices can be). Percent and count rows carry `ref`, `kind` and `evidence` only. Rate rows state a value per a count of something: `count_base` is that count (`1000` for "per 1,000 people"), and `counted` is what it counts as a plural noun phrase (`people`, `live births`), `null` when the ref states none. The graph holds neither as a field, so each rate row declares them from the ref and its label. `evidence` says where the reading comes from. A ref that scales its values (`SDG_CU_USD_M`, `SDG_NUM_TH`, `PeopleInThousands`) has no row and reads as other, as does any ref that matches no prefix and no row. No row may also match a prefix rule. `schemas/registry/unit-registry.schema.json` validates the file, and `uv run tools/validate_unit_registry.py` also checks the sort order, uniqueness, the prefix rule and the package mirror `python/spec-kit/src/dfo_spec_kit/units/units.json`; edit this file and copy it there. diff --git a/registries/warning-reasons.json b/registries/warning-reasons.json index 537c594..32a5e7d 100644 --- a/registries/warning-reasons.json +++ b/registries/warning-reasons.json @@ -4,26 +4,22 @@ { "code": "bilateral_reading_unavailable", "reason": "destination_unclassified", - "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest.", - "lifecycle": "active" + "definition": "The data holds a destination that no side declaration places, so the bilateral destinations cannot be told apart from the rest." }, { "code": "bilateral_reading_unavailable", "reason": "option_not_covered", - "definition": "The bilateral reading lacks a year the answer shows.", - "lifecycle": "active" + "definition": "The bilateral reading lacks a year the answer shows." }, { "code": "bilateral_reading_unavailable", "reason": "read_window_not_covered", - "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them.", - "lifecycle": "active" + "definition": "The bilateral reading holds every year the answer shows but lacks a year the request reads beyond them." }, { "code": "bilateral_reading_unavailable", "reason": "scope_undecided", - "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA.", - "lifecycle": "active" + "definition": "Search could not decide which reading the answer uses, so the answer reads total ODA." }, { "code": "bilateral_reading_unavailable", @@ -31,8 +27,7 @@ "definition": "The bilateral reading does not serve a slot the answer binds.", "params": { "slot": "The property of the slot the bilateral reading does not serve." - }, - "lifecycle": "active" + } } ] } diff --git a/schemas/registry/README.md b/schemas/registry/README.md index 31913b3..24c3408 100644 --- a/schemas/registry/README.md +++ b/schemas/registry/README.md @@ -115,4 +115,4 @@ The registry has no severity or message template. Each occurrence supplies them ## Warning-reason registry -`warning-reason-registry.schema.json` (draft 2020-12) validates `registries/warning-reasons.json`, the values a warning carries in `params.why`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `code` then `reason`, and each entry is closed to `code` (a warning registered in `registries/codes.json`), `reason` (lower snake case, unique within its code), `definition` (one sentence), `lifecycle` (`active` or `retired`) and an optional `params` object mapping each param the warning carries beside `why` for this reason to a one-sentence definition. `params` names no `why` and holds at least one param when present. `uv run tools/validate_warning_reasons.py` checks the schema, the sort order, uniqueness, that each code is a registered warning and active for an active reason, and the package mirror. Once a release tag exists, a reason published there must still be present with the same `definition` and `params`; it may retire, and retired is terminal. +`warning-reason-registry.schema.json` (draft 2020-12) validates `registries/warning-reasons.json`, the values a warning carries in `params.why`. Clients match on these values. The file is `{"format_version": 1, "entries": [...]}` with entries sorted by `code` then `reason`, and each entry is closed to `code` (an active warning registered in `registries/codes.json`), `reason` (lower snake case, unique within its code), `definition` (one sentence) and an optional `params` object mapping each param the warning carries beside `why` for this reason to a one-sentence definition. `params` names no `why` and holds at least one param when present. `uv run tools/validate_warning_reasons.py` checks the schema, the sort order, uniqueness, that each code is an active warning and the package mirror. diff --git a/schemas/registry/warning-reason-registry.schema.json b/schemas/registry/warning-reason-registry.schema.json index 3c7c887..e8dc868 100644 --- a/schemas/registry/warning-reason-registry.schema.json +++ b/schemas/registry/warning-reason-registry.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/DevelopmentFinanceObservatory/spec-kit/main/schemas/registry/warning-reason-registry.schema.json", "title": "Warning-reason registry", - "description": "The values a warning carries in params.why, each the reason the warning of one code fired. See schemas/registry/README.md. tools/validate_warning_reasons.py checks sort order, uniqueness, that each code is a registered warning, that a published reason keeps its definition and params, and the package mirror, which this schema cannot express.", + "description": "The values a warning carries in params.why, each the reason the warning of one code fired. See schemas/registry/README.md. tools/validate_warning_reasons.py checks sort order, uniqueness, that each code is an active warning, and the package mirror, which this schema cannot express.", "type": "object", "additionalProperties": false, "required": [ @@ -29,12 +29,11 @@ "required": [ "code", "reason", - "definition", - "lifecycle" + "definition" ], "properties": { "code": { - "description": "The warning code in registries/codes.json whose params.why carries the reason. An active reason needs an active code.", + "description": "The warning code in registries/codes.json whose params.why carries the reason. The code must be an active warning.", "type": "string", "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" }, @@ -62,13 +61,6 @@ "type": "string", "minLength": 1 } - }, - "lifecycle": { - "description": "active while the warning can carry the reason; retired once it no longer does, which keeps the spelling and its meaning reserved. A published reason is never removed.", - "enum": [ - "active", - "retired" - ] } } } diff --git a/tools/README.md b/tools/README.md index 067eed9..d60c6a9 100644 --- a/tools/README.md +++ b/tools/README.md @@ -14,14 +14,12 @@ uv run tools/validate_registry.py uv run tools/validate_limit_registry.py ``` -`validate_warning_reasons.py` validates `registries/warning-reasons.json` against `schemas/registry/warning-reason-registry.schema.json` and checks what the schema cannot express: entries sorted by `code` then `reason` with each pair once, every `code` a warning in `registries/codes.json` and an active code for each active reason, and byte-identity with the packaged mirror. Once a release tag is reachable from HEAD, it compares the file with the copy at that tag: a reason published there must keep its `definition` and `params`, may move to `lifecycle: retired`, and may not leave it, while new reasons pass. With no tag it prints the notice `validate_registry.py` prints and skips the comparison. It does not import `dfo_spec_kit`. Also a PEP 723 script: +`validate_warning_reasons.py` validates `registries/warning-reasons.json` against `schemas/registry/warning-reason-registry.schema.json` and checks what the schema cannot express: entries sorted by `code` then `reason` with each pair once, every `code` an active warning in `registries/codes.json`, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: ```bash uv run tools/validate_warning_reasons.py ``` -`registry_checks.py` holds what these registry validators share: JSON loading that refuses a repeated key, schema checking, the mirror comparison, reading a file at the latest release tag, and the NOTE, FAIL and OK lines they print. Every FAIL line names the file at fault. - `validate_unit_registry.py` validates `registries/units.json` against `schemas/registry/unit-registry.schema.json` (closed rows per kind, member types and the `format_version` pin) and checks what the schema cannot express: rows sorted by `ref` with each `ref` once, `currency_codes` sorted, no row that also matches a currency prefix rule, and byte-identity with the packaged mirror. It does not import `dfo_spec_kit`. Also a PEP 723 script: ```bash diff --git a/tools/registry_checks.py b/tools/registry_checks.py deleted file mode 100644 index 1185294..0000000 --- a/tools/registry_checks.py +++ /dev/null @@ -1,142 +0,0 @@ -"""Checks the registry validators share: strict JSON loading, schema -conformance, mirror byte-identity, reading a file at the latest release tag, -and reporting. - -`validate_limit_registry.py`, `validate_unit_registry.py` and -`validate_warning_reasons.py` import this module, and `validate_registry.py` -takes its release-tag helpers from it. A PEP 723 script's own directory is on -`sys.path`, so `uv run tools/.py` finds it, and -`tools/tests/conftest.py` puts `tools/` on the path for the tests. -""" - -from __future__ import annotations - -import json -import subprocess -import sys -from collections import Counter -from collections.abc import Hashable, Iterable -from pathlib import Path -from typing import Any - -import jsonschema - -REPO_ROOT = Path(__file__).resolve().parent.parent - - -class RegistryFileError(Exception): - """A file a validator reads is missing or is not strict JSON. The message - names the file.""" - - -def relative(path: Path) -> str: - """`path` relative to the repo root when it lies inside it.""" - return ( - str(path.relative_to(REPO_ROOT)) - if path.is_relative_to(REPO_ROOT) - else str(path) - ) - - -def duplicates[T: Hashable](values: Iterable[T]) -> list[T]: - """Every value that appears more than once in `values`, sorted.""" - return sorted(value for value, count in Counter(values).items() if count > 1) - - -def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: - repeated = duplicates(key for key, _ in pairs) - if repeated: - raise ValueError(f"duplicate keys {repeated}") - return dict(pairs) - - -def parse_json(text: str) -> Any: - """Parse `text`, refusing an object that repeats a key. Raises `ValueError`.""" - return json.loads(text, object_pairs_hook=_reject_duplicate_keys) - - -def load_json(path: Path) -> Any: - """Read and parse `path` once, refusing an object that repeats a key. - - Raises `RegistryFileError` naming the file when it is missing, is not - JSON, or repeats a key. - """ - try: - text = path.read_text(encoding="utf-8") - except FileNotFoundError as exc: - raise RegistryFileError(f"{relative(path)} does not exist") from exc - try: - return parse_json(text) - except ValueError as exc: - raise RegistryFileError(f"{relative(path)} is not valid JSON: {exc}") from exc - - -def check_schema(registry: Any, schema: Any) -> list[str]: - jsonschema.Draft202012Validator.check_schema(schema) - validator = jsonschema.Draft202012Validator(schema) - return [ - f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " - f"{error.message}" - for error in sorted( - validator.iter_errors(registry), key=lambda e: list(e.absolute_path) - ) - ] - - -def check_mirror(canonical: Path, mirror: Path) -> list[str]: - """The package mirror must be byte-identical to the canonical file.""" - for path in (canonical, mirror): - if not path.is_file(): - return [f"{relative(path)} does not exist"] - if mirror.read_bytes() != canonical.read_bytes(): - return [f"{relative(mirror)} is not byte-identical to {relative(canonical)}"] - return [] - - -def latest_release_tag() -> str | None: - """Return the most recent tag reachable from HEAD, or None if there isn't one.""" - try: - result = subprocess.run( - ["git", "describe", "--tags", "--abbrev=0"], - cwd=REPO_ROOT, - capture_output=True, - text=True, - check=False, - ) - except OSError: - return None - if result.returncode != 0: - return None - tag = result.stdout.strip() - return tag or None - - -def json_at_tag(tag: str, relative_path: str) -> Any | None: - """Return the parsed file at `relative_path` as it existed at `tag`, or - None when the file is absent at the tag or unreadable.""" - result = subprocess.run( - ["git", "show", f"{tag}:{relative_path}"], - cwd=REPO_ROOT, - capture_output=True, - text=True, - check=False, - ) - if result.returncode != 0: - return None - try: - return json.loads(result.stdout) - except json.JSONDecodeError: - return None - - -def report(problems: list[str], *, ok: str, notices: Iterable[str] = ()) -> int: - """Print each notice as a NOTE line and each problem as a FAIL line, or - `ok` when there are none, and return the exit status.""" - for notice in notices: - print(f"NOTE: {notice}") - for problem in problems: - print(f"FAIL: {problem}", file=sys.stderr) - if problems: - return 1 - print(f"OK: {ok}") - return 0 diff --git a/tools/tests/test_validate_warning_reasons.py b/tools/tests/test_validate_warning_reasons.py index bdb5e93..e585c18 100644 --- a/tools/tests/test_validate_warning_reasons.py +++ b/tools/tests/test_validate_warning_reasons.py @@ -1,6 +1,5 @@ """Tests for tools/validate_warning_reasons.py: each mutation of the real -registry is one rule the schema, the entry checks or the published-reason -check must refuse. +registry is one rule the schema or the entry checks must refuse. Run with: uv run --with jsonschema --with pyarrow --with pytest pytest tools/tests -q """ @@ -24,105 +23,63 @@ _SCHEMA = validate_warning_reasons.load_json(validate_warning_reasons.SCHEMA_PATH) _REGISTRY = validate_warning_reasons.load_json(validate_warning_reasons.REGISTRY_PATH) -_CODES, _CODE_PROBLEMS = validate_warning_reasons.read_codes( - validate_warning_reasons.load_json(validate_warning_reasons.CODES_PATH) -) +_CODES = validate_warning_reasons.load_json(validate_warning_reasons.CODES_PATH) _CODE = _REGISTRY["entries"][0]["code"] -def _problems(registry: dict[str, Any], codes: dict[str, Any]) -> list[str]: +def _problems(registry: dict[str, Any], codes: dict[str, Any] = _CODES) -> list[str]: return validate_warning_reasons.check_schema( registry, _SCHEMA ) or validate_warning_reasons.check_entries(registry, codes) -def _with_code(**changes: str) -> dict[str, Any]: +def _codes_with(**changes: str) -> dict[str, Any]: codes = copy.deepcopy(_CODES) - codes[_CODE].update(changes) + next(e for e in codes["entries"] if e["code"] == _CODE).update(changes) return codes def test_committed_registry_is_valid() -> None: - assert _CODE_PROBLEMS == [] - assert _problems(_REGISTRY, _CODES) == [] + assert _problems(_REGISTRY) == [] assert validate_warning_reasons.check_mirror() == [] @pytest.mark.parametrize( - ("mutate", "codes"), + "mutate", [ - pytest.param(lambda r: r["entries"].reverse(), _CODES, id="unsorted"), + pytest.param(lambda r: r["entries"].reverse(), id="unsorted"), pytest.param( lambda r: r["entries"].insert(0, copy.deepcopy(r["entries"][0])), - _CODES, id="duplicate-reason", ), - pytest.param( - lambda r: None, - {k: v for k, v in _CODES.items() if k != _CODE}, - id="unregistered-code", - ), - pytest.param( - lambda r: None, _with_code(classification="refusal"), id="refusal-code" - ), - pytest.param( - lambda r: None, _with_code(lifecycle="retired"), id="retired-code" - ), pytest.param( lambda r: r["entries"][0].update(reason="Destination_unclassified"), - _CODES, id="upper-case-reason", ), + pytest.param(lambda r: r["entries"][0].update(extra=1), id="extra-member"), pytest.param( - lambda r: r["entries"][0].update(extra=1), _CODES, id="extra-member" + lambda r: r["entries"][0].update(params={"why": "Reserved."}), + id="why-param", ), + pytest.param(lambda r: r["entries"][0].update(params={}), id="empty-params"), ], ) -def test_refuses( - mutate: Callable[[dict[str, Any]], None], codes: dict[str, Any] -) -> None: +def test_refuses(mutate: Callable[[dict[str, Any]], None]) -> None: registry = copy.deepcopy(_REGISTRY) mutate(registry) - assert _problems(registry, codes) - - -def _changed_since_tag( - mutate: Callable[[list[dict[str, Any]]], None], -) -> list[str]: - entries = copy.deepcopy(_REGISTRY["entries"]) - mutate(entries) - return validate_warning_reasons.check_published( - entries, _REGISTRY["entries"], "v9.9.9" - ) + assert _problems(registry) @pytest.mark.parametrize( - "mutate", + "codes", [ - pytest.param(lambda e: e.pop(0), id="removed-reason"), pytest.param( - lambda e: e[0].update(definition="A different meaning."), - id="redefined-reason", - ), - pytest.param( - lambda e: next(x for x in e if "params" in x)["params"].update( - other="Another param." - ), - id="params-changed", + {"entries": [e for e in _CODES["entries"] if e["code"] != _CODE]}, + id="unregistered-code", ), + pytest.param(_codes_with(classification="refusal"), id="refusal-code"), + pytest.param(_codes_with(lifecycle="retired"), id="retired-code"), ], ) -def test_refuses_against_tag(mutate: Callable[[list[dict[str, Any]]], None]) -> None: - assert _changed_since_tag(mutate) - - -def test_retiring_a_published_reason_passes() -> None: - assert _changed_since_tag(lambda e: e[0].update(lifecycle="retired")) == [] - - -def test_refuses_reactivating_a_retired_reason() -> None: - published = copy.deepcopy(_REGISTRY["entries"]) - published[0]["lifecycle"] = "retired" - assert validate_warning_reasons.check_published( - _REGISTRY["entries"], published, "v9.9.9" - ) +def test_refuses_a_code_that_is_not_an_active_warning(codes: dict[str, Any]) -> None: + assert _problems(_REGISTRY, codes) diff --git a/tools/validate_limit_registry.py b/tools/validate_limit_registry.py index e388e34..463d814 100644 --- a/tools/validate_limit_registry.py +++ b/tools/validate_limit_registry.py @@ -17,18 +17,12 @@ from __future__ import annotations +import json import sys from pathlib import Path from typing import Any -import registry_checks -from registry_checks import ( - RegistryFileError, - check_schema, - duplicates, - load_json, - report, -) +import jsonschema REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "limit-name-registry.schema.json" @@ -36,6 +30,32 @@ MIRROR_PATH = REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/registry/limit-names.json" +def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + keys = [key for key, _ in pairs] + duplicates = sorted({key for key in keys if keys.count(key) > 1}) + if duplicates: + raise ValueError(f"duplicate keys {duplicates}") + return dict(pairs) + + +def load_json(path: Path) -> Any: + return json.loads( + path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys + ) + + +def check_schema(registry: Any, schema: Any) -> list[str]: + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator(schema) + return [ + f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " + f"{error.message}" + for error in sorted( + validator.iter_errors(registry), key=lambda e: list(e.absolute_path) + ) + ] + + def check_entries(registry: dict[str, Any]) -> list[str]: """The rules a schema-valid registry must also meet.""" names = [entry["name"] for entry in registry["entries"]] @@ -43,32 +63,41 @@ def check_entries(registry: dict[str, Any]) -> list[str]: if names != sorted(names): problems.append("entries is not sorted by name") problems.extend( - f"limit name declared twice: {name!r}" for name in duplicates(names) + f"limit name declared twice: {name!r}" + for name in sorted({name for name in names if names.count(name) > 1}) ) return problems def check_mirror() -> list[str]: - return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) + if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): + mirror = MIRROR_PATH.relative_to(REPO_ROOT) + canonical = REGISTRY_PATH.relative_to(REPO_ROOT) + return [f"{mirror} is not byte-identical to {canonical}"] + return [] -def validate() -> tuple[list[str], Any]: - """The problems found, and the parsed registry (None when unreadable).""" +def validate() -> list[str]: try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - except RegistryFileError as exc: - return [str(exc)], None + except ValueError as exc: + return [f"not valid JSON: {exc}"] problems = check_schema(registry, schema) if problems: - return problems, registry - return check_entries(registry) + check_mirror(), registry + return problems + return check_entries(registry) + check_mirror() def main() -> int: - problems, registry = validate() - count = 0 if problems else len(registry["entries"]) - return report(problems, ok=f"{count} limit names validated") + problems = validate() + for problem in problems: + print(f"FAIL: {problem}", file=sys.stderr) + if problems: + return 1 + count = len(load_json(REGISTRY_PATH)["entries"]) + print(f"OK: {count} limit names validated") + return 0 if __name__ == "__main__": diff --git a/tools/validate_registry.py b/tools/validate_registry.py index 7c889c8..041aea8 100644 --- a/tools/validate_registry.py +++ b/tools/validate_registry.py @@ -22,12 +22,12 @@ from __future__ import annotations import json +import subprocess import sys from pathlib import Path from typing import Any import jsonschema -from registry_checks import json_at_tag, latest_release_tag REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "code-registry.schema.json" @@ -203,9 +203,39 @@ def check_mirror() -> list[str]: return [] +def latest_release_tag() -> str | None: + """Return the most recent tag reachable from HEAD, or None if there isn't one.""" + try: + result = subprocess.run( + ["git", "describe", "--tags", "--abbrev=0"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=False, + ) + except OSError: + return None + if result.returncode != 0: + return None + tag = result.stdout.strip() + return tag or None + + def registry_at_tag(tag: str) -> Any | None: """Return the parsed registry as it existed at `tag`, or None if unreadable.""" - return json_at_tag(tag, REGISTRY_RELATIVE_PATH) + result = subprocess.run( + ["git", "show", f"{tag}:{REGISTRY_RELATIVE_PATH}"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + return None + try: + return json.loads(result.stdout) + except json.JSONDecodeError: + return None def _doors_set(mapping: dict[str, Any]) -> frozenset[str] | None: diff --git a/tools/validate_unit_registry.py b/tools/validate_unit_registry.py index 48a458f..bc2d6ce 100644 --- a/tools/validate_unit_registry.py +++ b/tools/validate_unit_registry.py @@ -18,18 +18,12 @@ from __future__ import annotations +import json import sys from pathlib import Path from typing import Any -import registry_checks -from registry_checks import ( - RegistryFileError, - check_schema, - duplicates, - load_json, - report, -) +import jsonschema REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "unit-registry.schema.json" @@ -37,6 +31,32 @@ MIRROR_PATH = REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/units/units.json" +def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + keys = [key for key, _ in pairs] + duplicates = sorted({key for key in keys if keys.count(key) > 1}) + if duplicates: + raise ValueError(f"duplicate keys {duplicates}") + return dict(pairs) + + +def load_json(path: Path) -> Any: + return json.loads( + path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys + ) + + +def check_schema(registry: Any, schema: Any) -> list[str]: + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator(schema) + return [ + f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " + f"{error.message}" + for error in sorted( + validator.iter_errors(registry), key=lambda e: list(e.absolute_path) + ) + ] + + def _is_code_shape(value: str) -> bool: return len(value) == 3 and value.isascii() and value.isalpha() and value.isupper() @@ -65,7 +85,10 @@ def check_rows(registry: dict[str, Any]) -> list[str]: refs = [row["ref"] for row in registry["units"]] if refs != sorted(refs): problems.append("units is not sorted by ref") - problems.extend(f"unit ref declared twice: {ref!r}" for ref in duplicates(refs)) + problems.extend( + f"unit ref declared twice: {ref!r}" + for ref in sorted({ref for ref in refs if refs.count(ref) > 1}) + ) code_set = frozenset(codes) problems.extend( f"unit ref {ref!r} is declared and matches a prefix rule" @@ -76,26 +99,33 @@ def check_rows(registry: dict[str, Any]) -> list[str]: def check_mirror() -> list[str]: - return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) + if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): + mirror = MIRROR_PATH.relative_to(REPO_ROOT) + canonical = REGISTRY_PATH.relative_to(REPO_ROOT) + return [f"{mirror} is not byte-identical to {canonical}"] + return [] -def validate() -> tuple[list[str], Any]: - """The problems found, and the parsed registry (None when unreadable).""" +def validate() -> list[str]: try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - except RegistryFileError as exc: - return [str(exc)], None + except ValueError as exc: + return [f"not valid JSON: {exc}"] problems = check_schema(registry, schema) if problems: - return problems, registry - return check_rows(registry) + check_mirror(), registry + return problems + return check_rows(registry) + check_mirror() def main() -> int: - problems, registry = validate() - count = 0 if problems else len(registry["units"]) - return report(problems, ok=f"{count} unit registry rows validated") + problems = validate() + for problem in problems: + print(f"FAIL: {problem}", file=sys.stderr) + if problems: + return 1 + print(f"OK: {len(load_json(REGISTRY_PATH)['units'])} unit registry rows validated") + return 0 if __name__ == "__main__": diff --git a/tools/validate_warning_reasons.py b/tools/validate_warning_reasons.py index 1dfc3b3..4351cb0 100644 --- a/tools/validate_warning_reasons.py +++ b/tools/validate_warning_reasons.py @@ -10,33 +10,21 @@ Run with: uv run tools/validate_warning_reasons.py Beyond schema conformance, this checks what the schema cannot express: -entries are sorted by (`code`, `reason`), each `reason` appears once within -its `code`, every `code` is a warning in registries/codes.json (an active -code for an active reason), and the packaged mirror -(`python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`) is -byte-identical to the canonical file. Once a release tag is reachable from -HEAD, a reason published at that tag must still be present with the same -definition and params; it may move to `lifecycle: retired`, and retired is -terminal. It does not import `dfo_spec_kit`. +entries are sorted by (`code`, `reason`), each (`code`, `reason`) pair appears +once, every `code` is an active warning in registries/codes.json, and the +packaged mirror (`python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json`) +is byte-identical to the canonical file. It does not import `dfo_spec_kit`. """ from __future__ import annotations +import json import sys +from collections import Counter from pathlib import Path from typing import Any -import registry_checks -from registry_checks import ( - RegistryFileError, - check_schema, - duplicates, - json_at_tag, - latest_release_tag, - load_json, - relative, - report, -) +import jsonschema REPO_ROOT = Path(__file__).resolve().parent.parent SCHEMA_PATH = REPO_ROOT / "schemas" / "registry" / "warning-reason-registry.schema.json" @@ -46,128 +34,89 @@ REPO_ROOT / "python/spec-kit/src/dfo_spec_kit/registry/warning-reasons.json" ) -# Each registered code mapped to its codes.json entry. -type Codes = dict[str, dict[str, Any]] + +def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + counts = Counter(key for key, _ in pairs) + duplicates = sorted(key for key, count in counts.items() if count > 1) + if duplicates: + raise ValueError(f"duplicate keys {duplicates}") + return dict(pairs) -def read_codes(codes_registry: Any) -> tuple[Codes, list[str]]: - """Each code in a parsed codes.json, and a problem naming the file for - every entry that lacks the members this validator reads.""" - where = relative(CODES_PATH) - entries = ( - codes_registry.get("entries") if isinstance(codes_registry, dict) else None +def load_json(path: Path) -> Any: + return json.loads( + path.read_text(encoding="utf-8"), object_pairs_hook=_reject_duplicate_keys ) - if not isinstance(entries, list): - return {}, [f"{where}: has no entries list"] - codes: Codes = {} - problems: list[str] = [] - for index, entry in enumerate(entries): - missing = [ - key - for key in ("code", "classification", "lifecycle") - if not isinstance(entry, dict) or key not in entry - ] - if missing: - problems.append(f"{where}: entries/{index} lacks {missing}") - else: - codes[entry["code"]] = entry - return codes, problems - - -def check_entries(registry: dict[str, Any], codes: Codes) -> list[str]: - """The rules a schema-valid registry must also meet.""" + + +def check_schema(registry: Any, schema: Any) -> list[str]: + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator(schema) + return [ + f"schema: {'/'.join(str(p) for p in error.absolute_path) or ''}: " + f"{error.message}" + for error in sorted( + validator.iter_errors(registry), key=lambda e: list(e.absolute_path) + ) + ] + + +def check_entries(registry: dict[str, Any], codes: dict[str, Any]) -> list[str]: + """The rules a schema-valid registry must also meet. `codes` is the parsed + registries/codes.json.""" keys = [(entry["code"], entry["reason"]) for entry in registry["entries"]] problems: list[str] = [] if keys != sorted(keys): problems.append("entries is not sorted by code and reason") + counts = Counter(keys) problems.extend( f"reason declared twice for {code!r}: {reason!r}" - for code, reason in duplicates(keys) + for (code, reason), count in sorted(counts.items()) + if count > 1 ) - for code in sorted({code for code, _ in keys}): - code_entry = codes.get(code) - if code_entry is None: - problems.append(f"code is not in registries/codes.json: {code!r}") - elif code_entry["classification"] != "warning": - problems.append(f"code is not a warning: {code!r}") + active_warnings = { + entry["code"] + for entry in codes["entries"] + if entry["classification"] == "warning" and entry["lifecycle"] == "active" + } problems.extend( - f"active reason {entry['reason']!r} names retired code {entry['code']!r}" - for entry in registry["entries"] - if entry["lifecycle"] == "active" - and codes.get(entry["code"], {}).get("lifecycle") == "retired" + f"code is not an active warning in registries/codes.json: {code!r}" + for code in sorted({code for code, _ in keys} - active_warnings) ) return problems -def check_published( - entries: list[dict[str, Any]], published: list[dict[str, Any]], tag: str -) -> list[str]: - """Every reason in `published` (the entries at `tag`) is still present with - the same definition and params, and a retired one stays retired.""" - current = {(entry["code"], entry["reason"]): entry for entry in entries} - problems: list[str] = [] - for old in published: - label = f"{old['code']}/{old['reason']}" - new = current.get((old["code"], old["reason"])) - if new is None: - problems.append( - f"{label}: published reason was removed (present at tag {tag!r})" - ) - continue - problems.extend( - f"{label}: {member} changed since tag {tag!r}" - for member in ("definition", "params") - if old.get(member) != new.get(member) - ) - if old.get("lifecycle") == "retired" and new["lifecycle"] != "retired": - problems.append(f"{label}: lifecycle left retired, which is terminal") - return problems - - -def check_immutability( - entries: list[dict[str, Any]], -) -> tuple[str | None, list[str]]: - """Compare `entries` with the registry at the latest release tag. - - Returns (notice, problems). The notice, printed on stdout, says why the - comparison was skipped; it is never a failure. - """ - tag = latest_release_tag() - if tag is None: - return "no release tag yet; immutability check skipped", [] - path = relative(REGISTRY_PATH) - published = json_at_tag(tag, path) - if published is None: - return f"could not read {path} at tag {tag!r}; immutability check skipped", [] - return None, check_published(entries, published.get("entries", []), tag) - - def check_mirror() -> list[str]: - return registry_checks.check_mirror(REGISTRY_PATH, MIRROR_PATH) + if MIRROR_PATH.read_bytes() != REGISTRY_PATH.read_bytes(): + mirror = MIRROR_PATH.relative_to(REPO_ROOT) + canonical = REGISTRY_PATH.relative_to(REPO_ROOT) + return [f"{mirror} is not byte-identical to {canonical}"] + return [] -def validate() -> tuple[list[str], list[str], Any]: - """The problems found, the notices to print, and the parsed registry (None - when unreadable).""" +def validate() -> tuple[list[str], int]: + """The problems found and the number of entries checked.""" try: schema = load_json(SCHEMA_PATH) registry = load_json(REGISTRY_PATH) - codes_registry = load_json(CODES_PATH) - except RegistryFileError as exc: - return [str(exc)], [], None - codes, problems = read_codes(codes_registry) - problems += check_schema(registry, schema) + codes = load_json(CODES_PATH) + except ValueError as exc: + return [f"not valid JSON: {exc}"], 0 + problems = check_schema(registry, schema) if problems: - return problems, [], registry - notice, published_problems = check_immutability(registry["entries"]) - problems = check_entries(registry, codes) + check_mirror() + published_problems - return problems, [notice] if notice else [], registry + return problems, 0 + problems = check_entries(registry, codes) + check_mirror() + return problems, len(registry["entries"]) def main() -> int: - problems, notices, registry = validate() - count = 0 if problems else len(registry["entries"]) - return report(problems, ok=f"{count} warning reasons validated", notices=notices) + problems, count = validate() + for problem in problems: + print(f"FAIL: {problem}", file=sys.stderr) + if problems: + return 1 + print(f"OK: {count} warning reasons validated") + return 0 if __name__ == "__main__":