From e888281b73e0f15dd2d9b99d10496fdf943a554f Mon Sep 17 00:00:00 2001 From: Fritz Kunstler <36011164+dfkunstler@users.noreply.github.com> Date: Tue, 17 Nov 2026 06:40:12 -0500 Subject: [PATCH] feat!: add error category classes and the limit property Add OscalDocumentTypeMismatchError (a subclass of OscalParseError) for the typed parsers, and OscalUnknownElementTypeError for validate_element. Add OscalParseError.limit, which names the documented limit that stopped a parse (ERR-009, ERR-010). The conformance runner now reads the error class only. BREAKING CHANGE: validate_element raises OscalUnknownElementTypeError, not OscalParseError, for an element type that the library does not recognize. Closes #60 --- .agents/summary/components.md | 4 +- .agents/summary/interfaces.md | 4 +- .agents/summary/review_notes.md | 2 +- .agents/summary/workflows.md | 4 +- AGENTS.md | 4 +- README.md | 20 ++-- .../.openspec.yaml | 2 + .../design.md | 101 ++++++++++++++++++ .../proposal.md | 57 ++++++++++ .../specs/error-tests/spec.md | 93 ++++++++++++++++ .../tasks.md | 69 ++++++++++++ openspec/specs/error-tests/spec.md | 92 ++++++++++++++++ openspec/traceability.json | 4 +- src/oscal_bindings/parser.py | 2 + src/oscal_bindings/v1/__init__.py | 4 + src/oscal_bindings/v1/extensions/__init__.py | 2 + .../v1/extensions/_yaml_loader.py | 17 ++- .../v1/extensions/validate_element.py | 12 ++- src/oscal_bindings/v1/parser.py | 50 +++++++-- tests/support/version_package.py | 2 + tests/test_conformance.py | 24 +++-- tests/test_parser.py | 61 +++++++++++ tests/test_prop_validate_element.py | 6 +- tests/test_validate_element.py | 10 +- tests/test_yaml_io.py | 31 ++++++ 25 files changed, 627 insertions(+), 50 deletions(-) create mode 100644 openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/design.md create mode 100644 openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/proposal.md create mode 100644 openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/specs/error-tests/spec.md create mode 100644 openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/tasks.md create mode 100644 openspec/specs/error-tests/spec.md diff --git a/.agents/summary/components.md b/.agents/summary/components.md index 87788a6..b160740 100644 --- a/.agents/summary/components.md +++ b/.agents/summary/components.md @@ -69,6 +69,8 @@ graph LR - `assessment_period() -> (date|None, date|None)` — defined only for Assessment Plan (walks `tasks[].timing`, including nested subtasks: `on-date`, `within-date-range`; `at-frequency` contributes nothing) and Assessment Results (aggregates `results[].start`/`.end`). Earliest start / latest end win. Raises `OscalAccessError` on other types. - Type unions `OscalBody` and `OscalWrapper` (each an 8-way union), and the module-private `_WRAPPER_TO_BODY_ATTR` dispatch map. - `OscalAccessError` — raised when a typed accessor is used on the wrong document type. +- `OscalUnknownElementTypeError` — raised by `validate_element` for an unrecognized element type; a category of its own, outside the parse errors. +- `OscalDocumentTypeMismatchError` (in `parser.py`) — a subclass of `OscalParseError` that the typed parsers raise for a document of another type. `OscalParseError.limit` names the documented limit that stopped a parse, else `None`. ## 4. `v1/extensions/builders.py` — back-matter builders @@ -88,7 +90,7 @@ graph LR - `_build_element_map()` — introspects `oscal_bindings.v1.models` for each manifest type by its run-time form (a `BaseModel` subclass, an `Enum` subclass, or a `types.UnionType` alias that `models` defines), building `{kebab-name: type}`; result cached in module-level `_ELEMENT_MAP`. The set is pinned by the `element-types/all` corpus case. - `validate_element` calls `model_validate(element)` for a model, and a `TypeAdapter` (made on first use, cached in `_ADAPTERS`) for an enum or a union; dict input stays alias-only from the models' defaults. - `get_supported_element_types() -> list[str]` — sorted kebab names. -- `validate_element(element: Any, element_type: str) -> ElementValidationResult` — raises `OscalParseError` for unknown types; otherwise returns a result with `valid` and a list of `ValidationError(path, message)`. +- `validate_element(element: Any, element_type: str) -> ElementValidationResult` — raises `OscalUnknownElementTypeError` for an unrecognized type; otherwise returns a result with `valid` and a list of `ValidationError(path, message)`. - Dataclasses `ElementValidationResult` and `ValidationError` (re-exported as `ElementValidationError`). ## 6. `v1/__init__.py` — version package surface diff --git a/.agents/summary/interfaces.md b/.agents/summary/interfaces.md index 4f586d7..a6d3f88 100644 --- a/.agents/summary/interfaces.md +++ b/.agents/summary/interfaces.md @@ -123,10 +123,10 @@ sequenceDiagram | Invalid JSON / invalid UTF-8 bytes | `OscalParseError` (from `parse_oscal`) | | Schema validation failure | `OscalParseError` with `.errors` = Pydantic error dicts | | File missing | `FileNotFoundError` (from `parse_oscal_file`, includes path) | -| Typed parser, wrong document type | `OscalParseError("Document is not a …")` | +| Typed parser, wrong document type | `OscalDocumentTypeMismatchError("Document is not a …")` (subclass of `OscalParseError`) | | `assessment_period()` on non-AP/AR | `OscalAccessError` | | `OscalDoc(...)` with unrelated object | `TypeError` | -| `validate_element` unknown element type | `OscalParseError` | +| `validate_element` unrecognized element type | `OscalUnknownElementTypeError` (outside the parse errors) | | Builders with invalid input | `pydantic.ValidationError` | | `validate_oscal` on invalid input | returns `False` (never raises) | diff --git a/.agents/summary/review_notes.md b/.agents/summary/review_notes.md index ac5b117..c6c35e3 100644 --- a/.agents/summary/review_notes.md +++ b/.agents/summary/review_notes.md @@ -17,7 +17,7 @@ Cross-document facts were verified against the source files (`v1/parser.py`, `v1 | Top level is a pure re-export; `__all__` derived from `v1.__all__` | ✅ | codebase_info, architecture, components, interfaces, index agree; asserted by `tests/test_oscal_bindings.py` | | Active schema release `1.2.3` / `__oscal_schema_version__` | ✅ | index, codebase_info, architecture, data_models, workflows, dependencies agree; tests assert it against the release of the pin and the artifact schema `$id` | | Names come only from `names.json` (hoist + post-processor guards; no naming rule in the binding) | ✅ | architecture, workflows, interfaces, components, data_models, index agree | -| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` | ✅ | Consistent; `validate_element` unknown-type also raises `OscalParseError` | +| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` | ✅ | Consistent; `validate_element` raises `OscalUnknownElementTypeError` for an unrecognized type, a separate category | | `serialize_oscal` defaults (`indent=2`, `by_alias`, `exclude_none`) | ✅ | Matches source | | Two `RootModel`s: `OscalDocument`, `MappingCollectionMappings` | ✅ | architecture, components, data_models, workflows agree | | Single runtime dependency (Pydantic v2) | ✅ | dependencies.md matches `pyproject.toml` | diff --git a/.agents/summary/workflows.md b/.agents/summary/workflows.md index 6077d6f..dacbf21 100644 --- a/.agents/summary/workflows.md +++ b/.agents/summary/workflows.md @@ -99,7 +99,7 @@ flowchart TD E --> F{"typed parser?"} F -->|"parse_catalog etc."| G["hasattr(doc.root, 'catalog')?"] G -->|yes| H["return doc.root (CatalogDocument)"] - G -->|no| I["raise OscalParseError('Document is not a Catalog')"] + G -->|no| I["raise OscalDocumentTypeMismatchError('Document is not a Catalog')"] F -->|no| E ``` @@ -157,7 +157,7 @@ sequenceDiagram ```mermaid flowchart TD A["validate_element(element, 'observation')"] --> B{"element_type in _ELEMENT_MAP?"} - B -->|no| C["raise OscalParseError('Unknown element type')"] + B -->|no| C["raise OscalUnknownElementTypeError('Unknown element type')"] B -->|yes| D["model_class.model_validate(element)"] D -->|ok| E["ElementValidationResult(valid=True)"] D -->|PydanticValidationError| F["ElementValidationResult(valid=False,
errors=[ValidationError(path, message)])"] diff --git a/AGENTS.md b/AGENTS.md index fce0bfe..2b99758 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,10 +94,10 @@ See `.agents/summary/workflows.md` for the flow diagram. ## Repo-Specific Patterns & Gotchas - **Parsers accept `str | bytes`.** Passing `bytes` (from HTTP/S3/file) skips a UTF-8 decode; `parse_oscal_file` reads bytes deliberately. Invalid UTF-8 surfaces as `OscalParseError`, not `UnicodeDecodeError`. -- **Typed parsers return the wrapper, not the body.** `parse_catalog()` returns `CatalogDocument` (access `.catalog.metadata...`). It `hasattr`-checks `doc.root` and raises `OscalParseError("Document is not a Catalog")` on mismatch. +- **Typed parsers return the wrapper, not the body.** `parse_catalog()` returns `CatalogDocument` (access `.catalog.metadata...`). It `hasattr`-checks `doc.root` and raises `OscalDocumentTypeMismatchError("Document is not a Catalog")` (a subclass of `OscalParseError`) on mismatch. - **`OscalDoc` collapses per-type dispatch.** Use it when you don't want to branch on document type — `doc.metadata`, `doc.uuid`, `doc.oscal_version`, `doc.body` work uniformly via the `_WRAPPER_TO_BODY_ATTR` map. `assessment_period()` is defined **only** for Assessment Plan / Assessment Results (raises `OscalAccessError` otherwise). - **Valid OSCAL by default; construct by name, validate by alias.** `OscalBaseModel` (`v1/_base.py`) gives every object model alias keys (`media-type`, `document-ids`) and no `null` on all serialization paths (`model_dump*`, `to_json`, `TypeAdapter`); `exclude_none=False` is a no-op, `by_alias=False` emits names. Constructor kwargs accept field names or aliases (`BackMatterResourceRlink(media_type=...)`), so the builders construct directly. OSCAL input stays alias-only: dict input rejects name keys with `extra_forbidden` at every depth (`extra='forbid'`). **Don't add `validate_by_name`/`populate_by_name` to the base config**, and don't remove `__pydantic_base_init__` from its `__init__`: either makes `model_validate*` accept name-keyed OSCAL (DEVELOPING "Valid OSCAL by default"; tripwire tests guard both). JSON input rejects name keys too, which needs the pydantic ≥2.14.2 floor (2.13.x–2.14.1 silently dropped them, [#6](https://github.com/cairn-proofs/oscal-bindings-python/issues/6)). -- **`validate_element` type names are derived from model class names** (PascalCase → kebab-case, introspected at import), so they follow the manifest names (`back-matter-resource-rlink`). Each manifest type has one, whatever its kind: object/document classes, enums (`hash-algorithm`, validated from the string value), and unions (`parameter`). Use `get_supported_element_types()` for the live list; unknown types raise `OscalParseError`. The corpus case `element-types/all` pins the list. The introspection keeps only `BaseModel` subclasses, `Enum` subclasses, and `types.UnionType` aliases that `models` defines, and skips pydantic parametrizations (`__pydantic_generic_metadata__["origin"]` set): since 2.14, pydantic registers the `RootModel[...]` bases of `OscalDocument` and `MappingCollectionMappings` in `models` under non-identifier names. Module scans in tests skip them the same way. +- **`validate_element` type names are derived from model class names** (PascalCase → kebab-case, introspected at import), so they follow the manifest names (`back-matter-resource-rlink`). Each manifest type has one, whatever its kind: object/document classes, enums (`hash-algorithm`, validated from the string value), and unions (`parameter`). Use `get_supported_element_types()` for the live list; an unrecognized type raises `OscalUnknownElementTypeError`, which is not an `OscalParseError`. The corpus case `element-types/all` pins the list. The introspection keeps only `BaseModel` subclasses, `Enum` subclasses, and `types.UnionType` aliases that `models` defines, and skips pydantic parametrizations (`__pydantic_generic_metadata__["origin"]` set): since 2.14, pydantic registers the `RootModel[...]` bases of `OscalDocument` and `MappingCollectionMappings` in `models` under non-identifier names. Module scans in tests skip them the same way. - **Expected conformance failures are local.** `tests/support/expected_failures.py` (case id → issue URL) drives the strict xfails in `tests/test_conformance.py`; the runner ignores any `known-defects` in the corpus. The spec store holds no binding state, so fixing a listed defect means deleting its entry here, never a store change. - **Closed enums are `Enum` classes.** A closed-enum field holds its enum class (`ParameterSelectionHowMany`) and rejects any other value. An open-enum field is the union of its base datatype alias and its enum class. - **Major-version namespace, single active release.** The implementation lives in `oscal_bindings.v1` — named for the OSCAL **major** version, no minor/patch component — and is generated from exactly one OSCAL release at a time, the release of the spec artifact pin (`__oscal_schema_version__`, currently `1.2.3`). A 1.x refresh regenerates `v1` in place; only OSCAL 2.0 justifies a second version package. Minor-version namespacing (`v1_2`) was considered and rejected — read the "Major-version namespace" and "Strict models" entries under Key Design Decisions in `DEVELOPING.md` before proposing either. diff --git a/README.md b/README.md index f6e7554..98f8705 100644 --- a/README.md +++ b/README.md @@ -265,16 +265,16 @@ An entry for a [resource limit](#resource-limits) has `input` `None`. ### Resource limits -The parse operations apply six documented limits (PRS-010 of the spec store). An input past any of them is an `OscalParseError`, also when the document is otherwise valid, and `validate_oscal` returns `False` for it. The error carries one entry whose `type` names the limit, and no entry holds the input text. +The parse operations apply six documented limits (PRS-010 of the spec store). An input past any of them is an `OscalParseError`, also when the document is otherwise valid, and `validate_oscal` returns `False` for it. The error carries one entry whose `type` names the limit, and no entry holds the input text. The error also has the attribute `limit`, the identifier in the last column of the table. The two alias limits share an entry `type`, and `limit` tells them apart. For each other parse error, `limit` is `None`. Test an `OscalParseError` with `error.limit is not None`, and an error of any class with `getattr(error, "limit", None) is not None`. -| Limit | Value | Measure | Operations | Entry `type` | -|---|---|---|---|---| -| JSON depth | 200 levels | The number of arrays and objects that hold a value in the JSON text. Arrays and objects count the same. | `parse_oscal`, `parse_oscal_file`, the eight typed parsers, `OscalDoc.from_json`, `OscalDoc.from_file`, `validate_oscal` | `json_depth_limit` | -| JSON digits | 4,300 digits | The digits of the integer part of one JSON number, at any location. A sign, a fraction, and an exponent do not count. | The operations of the JSON depth limit, and `parse_oscal_yaml` and `parse_oscal_yaml_file` at each number location | `json_digit_limit` | -| Alias nodes | 100,000 nodes | The scalars, sequences, mappings, and mapping keys that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | -| Alias characters | 1,000,000 characters | The characters of scalar text and key text that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | -| YAML depth | 128 levels | The number of sequences and mappings that hold a node, after alias expansion | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_depth_limit` | -| Line-break placeholders | about 137,000 private-use characters | The free private-use characters that a YAML input with U+0085, U+2028, or U+2029 leaves for them | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_line_break_placeholder` | +| Limit | Value | Measure | Operations | Entry `type` | `limit` | +|---|---|---|---|---|---| +| JSON depth | 200 levels | The number of arrays and objects that hold a value in the JSON text. Arrays and objects count the same. | `parse_oscal`, `parse_oscal_file`, the eight typed parsers, `OscalDoc.from_json`, `OscalDoc.from_file`, `validate_oscal` | `json_depth_limit` | `json_depth` | +| JSON digits | 4,300 digits | The digits of the integer part of one JSON number, at any location. A sign, a fraction, and an exponent do not count. | The operations of the JSON depth limit, and `parse_oscal_yaml` and `parse_oscal_yaml_file` at each number location | `json_digit_limit` | `json_digits` | +| Alias nodes | 100,000 nodes | The scalars, sequences, mappings, and mapping keys that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | `yaml_alias_nodes` | +| Alias characters | 1,000,000 characters | The characters of scalar text and key text that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | `yaml_alias_characters` | +| YAML depth | 128 levels | The number of sequences and mappings that hold a node, after alias expansion | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_depth_limit` | `yaml_depth` | +| Line-break placeholders | about 137,000 private-use characters | The free private-use characters that a YAML input with U+0085, U+2028, or U+2029 leaves for them | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_line_break_placeholder` | `yaml_line_break_placeholders` | pydantic-core's JSON parser sets the two JSON limits, and the binding cannot change them. The YAML depth limit is lower than the JSON depth limit, so deep YAML input always gets the YAML depth error. For a JSON limit, the entry's `line` and `column` give the position in the JSON text, and `column` counts UTF-8 bytes. For a YAML input, they give the position in the YAML source. No limit bounds the input size. See [Performance](#performance) for the memory that a parse uses. @@ -302,6 +302,8 @@ Each OSCAL document type has a dedicated parser: - `parse_plan_of_action_and_milestones(json)` → `PlanOfActionAndMilestonesDocument` - `parse_mapping_collection(json)` → `MappingCollectionDocument` +A typed parser raises `OscalDocumentTypeMismatchError` for a document of another type. It is a subclass of `OscalParseError`, so `except OscalParseError` also catches it. `validate_element` raises `OscalUnknownElementTypeError` for an element type that the library does not recognize. That error is a category of its own, outside the parse errors. Test the category of an error with `isinstance`. + ## Building ```bash diff --git a/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/.openspec.yaml b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/.openspec.yaml new file mode 100644 index 0000000..90080a9 --- /dev/null +++ b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-16 diff --git a/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/design.md b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/design.md new file mode 100644 index 0000000..117ae1d --- /dev/null +++ b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/design.md @@ -0,0 +1,101 @@ +# Design + +## Context + +See [proposal.md - Why](proposal.md#why) for the motivation. These facts constrain the approach. + +1. Each typed parser in `parser.py` raises `OscalParseError("Document is not a ...")` for a document of another type. +2. Six raise sites stop a parse at a documented limit: + 1. `parse_oscal` in `parser.py`, for the JSON depth limit and the JSON digit limit (`_limit_entry`). + 2. `_yaml_loader.py`, through `_fail`, for the YAML depth limit (two sites), the two alias limits + (`_Writer.charge`), and the line-break placeholder limit. + 3. `_yaml_loader.py`, directly, for the JSON digit limit at a YAML number location. +3. `_fail` also raises each YAML failure that is not a limit, such as `yaml_alias_cycle` and `yaml_undefined_alias`. +4. `validate_element` raises `OscalParseError("Unknown element type: ...")`. +5. The conformance runner (`category` in `tests/test_conformance.py`) maps the two message prefixes to the categories. +6. A name in `v1.__all__` must be in the surface snapshot (`tests/support/version_package.py`) and in + `openspec/traceability.json`. + +## Goals / Non-Goals + +**Goals:** + +1. Each category test and the limit test is one Python expression that reads no message text. + +**Non-Goals:** + +1. A change to a message or to an entry of a parse error. +2. The read-error category ([#61]) and the builder-error category ([#62]). + +## Decisions + +### D1: A category is a class, and the tree is the class hierarchy + +ERR-009 says a test for a category is true for the category and for each descendant. `isinstance` behaves the same way +on a class hierarchy. Thus each category is a class (see the spec +[The class of an error is its category](specs/error-tests/spec.md#requirement-the-class-of-an-error-is-its-category)). + +1. `OscalDocumentTypeMismatchError(OscalParseError)` is in `parser.py`, below `OscalParseError`. The eight typed + parsers raise it with the message that they raise now. +2. `OscalUnknownElementTypeError(Exception)` is in `v1/extensions/validate_element.py`. It has no parent category, as + `OscalAccessError` has none. `validate_element` raises it with the message that it raises now. +3. Both classes go through the re-export chain: `extensions/__init__.py` for the second one, then `v1/__init__.py`. + The top level takes them from `v1.__all__`. The legacy alias module `src/oscal_bindings/parser.py` lists each name + explicitly, because `v1.parser` declares no `__all__`. Thus `OscalDocumentTypeMismatchError` also goes into its + import list and its `__all__`. The legacy `extensions` alias star-imports, so it needs no edit. + +Alternative: a `category` attribute with a string value. A caller then needs a table of the tree to test for a parent +category. The binding then keeps the tree in two places, the attribute values and the table. Rejected. + +### D2: The name says "mismatch" + +The name `OscalDocumentTypeError` is shorter. But the entry type `oscal_document_type` marks a different parse error: +an input that names no document type. That error is not a mismatch. The name `OscalDocumentTypeMismatchError` keeps the +two apart. + +### D3: The limit property is an attribute, not a class + +ERR-010 says a property is independent of the category. A mixin class `OscalLimitError` gives a second `isinstance` +test, which a caller can mistake for a category test. An attribute does not. Thus `OscalParseError.__init__` gets the +keyword `limit: str | None = None` and stores it on `self.limit`. + +Only `OscalParseError` and its subclasses have the attribute. `OscalAccessError`, `OscalUnknownElementTypeError`, and +`FileNotFoundError` do not. The test `error.limit is not None` applies to an `OscalParseError`. For an error of any +class, the test is `getattr(error, "limit", None) is not None`. A class attribute `limit = None` on the other binding +classes was rejected: it cannot cover `FileNotFoundError`, so the `getattr` form is needed anyway. + +### D4: Each raise site sets the identifier, and the entry types stay + +The `limit` values are new strings, one for each documented limit (see the spec +[Each documented limit has its own identifier](specs/error-tests/spec.md#requirement-each-documented-limit-has-its-own-identifier)). + +1. The binding does not compute `limit` from the entry type. The two alias limits share the entry type + `yaml_alias_budget`, so the entry type cannot give two values. +2. The binding does not change the entry types. A caller that reads an entry type keeps working. +3. `_LIMIT_PREFIXES` in `parser.py` gets the identifier for each JSON limit. `_fail` gets the keyword `limit`, and only + the five limit calls set it: the line-break placeholder limit, the YAML depth limit at the compose stage, the alias + node limit, the alias character limit, and the YAML depth limit in `emit` after alias expansion. A plain deep input + reaches only the compose-stage depth site. The `emit` depth site is reached only through aliases. The direct + digit-limit raise in `_yaml_loader.py` sets `limit="json_digits"`. + +The identifiers drop the `_limit` and `_budget` suffixes of the entry types. A value of the `limit` attribute is always +a limit, so the suffix adds nothing. + +### D5: The runner reads the class only + +`category` checks `OscalDocumentTypeMismatchError` before `OscalParseError`, and adds `OscalUnknownElementTypeError`. +The two message-prefix checks go away. `test_every_category_is_mapped` builds one instance of each class. + +### D6: Traceability + +1. `OscalParseError`: add ERR-009 and ERR-010. +2. `OscalDocumentTypeMismatchError`: ERR-005 and ERR-009. +3. `OscalUnknownElementTypeError`: ERR-008 and ERR-009. + +## Risks / Trade-offs + +1. [Code that catches `OscalParseError` around `validate_element` does not catch an unknown element type.] → + The proposal marks the break. The docstring of `validate_element` and the README name the new class. + +[#61]: https://github.com/cairn-proofs/oscal-bindings-python/issues/61 +[#62]: https://github.com/cairn-proofs/oscal-bindings-python/issues/62 diff --git a/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/proposal.md b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/proposal.md new file mode 100644 index 0000000..0de3514 --- /dev/null +++ b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/proposal.md @@ -0,0 +1,57 @@ +# Proposal + +## Why + +The store requirements ERR-009 and ERR-010 (cairn-proofs/oscal-bindings-specs#42, PR cairn-proofs/oscal-bindings-specs#54) +make the error categories a tree and add a limit property to an error. A caller must be able to test whether an error is +in a category, and whether an error carries the limit property ([#60]). The binding does not meet either requirement: + +1. The binding has no test for the document-type-mismatch category. The typed parsers raise a plain `OscalParseError`, + and only the message text `Document is not ...` tells the mismatch from other parse errors. +2. The binding has no test for the limit property. A parse error over a documented limit has one entry whose `type` + names the limit. But the entry types of limits and the entry types of other failures are one set, so a caller must + know which types are limits. Also, the alias-node limit and the alias-character limit give the same entry type, + `yaml_alias_budget`. Thus the entry type does not identify each of the six documented limits. +3. `validate_element` raises `OscalParseError` for an element type that the binding does not recognize. ERR-008 puts + this error in the unknown-element-type category, not in the parse-error category. With a category tree, a test for + the parse-error category must be false for this error (ERR-009). + +The pin is at `v0.8.0+oscal.1.2.3` (#70), the release that has ERR-009 and ERR-010. Thus the fix is now possible. + +## What Changes + +1. A new exception `OscalDocumentTypeMismatchError`, a subclass of `OscalParseError`. Each typed parser raises it for a + document of another type. The message stays the same. +2. `OscalParseError` gets the attribute `limit`. Its value is a string that identifies the documented limit that stopped + the parse. Each of the six documented limits has a different value. For each other parse error, the value is `None`. + The entry types do not change. +3. **BREAKING**: a new exception `OscalUnknownElementTypeError`, a subclass of `Exception` and not of `OscalParseError`. + `validate_element` raises it for an element type that the binding does not recognize. Code that catches + `OscalParseError` for this case does not catch the new error. +4. The README table of resource limits shows the `limit` value of each limit. +5. The conformance runner finds the category of an error from its class only. It does not read the message text. + +## Capabilities + +### New Capabilities + +1. `error-tests`: how a caller tests the category of an error and the limit property of an error. + +### Modified Capabilities + +None. + +## Impact + +1. Code: `src/oscal_bindings/v1/parser.py`, `src/oscal_bindings/v1/extensions/_yaml_loader.py`, + `src/oscal_bindings/v1/extensions/validate_element.py`, and the re-exports in + `src/oscal_bindings/v1/extensions/__init__.py`, `src/oscal_bindings/v1/__init__.py`, and the legacy alias module + `src/oscal_bindings/parser.py`. +2. Tests: `tests/test_conformance.py`, `tests/test_validate_element.py`, `tests/test_prop_validate_element.py`, and the + tests of the parser and the YAML limits. +3. Docs: `README.md`, `AGENTS.md`, and `.agents/summary/interfaces.md`, `workflows.md`, `components.md`, and + `review_notes.md`. +4. Public API: two new exception classes, the attribute `OscalParseError.limit`, and the exception that `validate_element` + raises for an unknown element type. + +[#60]: https://github.com/cairn-proofs/oscal-bindings-python/issues/60 diff --git a/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/specs/error-tests/spec.md b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/specs/error-tests/spec.md new file mode 100644 index 0000000..ba6422b --- /dev/null +++ b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/specs/error-tests/spec.md @@ -0,0 +1,93 @@ +# Spec Delta + +## Purpose + +Defines how a caller tests whether an error is in a category of the store's error model. Also defines how a caller +tests whether an error carries the limit property of the store's error model. + +## ADDED Requirements + +### Requirement: The class of an error is its category + +For each category in this list, an error SHALL be in the category exactly when it is an instance of the class: + +1. Parse error: `OscalParseError`. +2. Document-type mismatch: `OscalDocumentTypeMismatchError`, a subclass of `OscalParseError`. +3. Unknown element type: `OscalUnknownElementTypeError`, which is not a subclass of `OscalParseError`. +4. Access error: `OscalAccessError`. +5. Not-found: `FileNotFoundError`. + +A caller tests a category with `isinstance`. + +#### Scenario: A document-type mismatch is also a parse error + +- **WHEN** the caller parses a profile with the catalog parser +- **THEN** the error is an instance of `OscalDocumentTypeMismatchError` and an instance of `OscalParseError` + +#### Scenario: A parse error of another kind is not a document-type mismatch + +- **WHEN** the caller parses input that is not valid JSON +- **THEN** the error is an instance of `OscalParseError` and not an instance of `OscalDocumentTypeMismatchError` + +#### Scenario: An unknown element type is not a parse error + +- **WHEN** the caller validates an element with an element type that the binding does not recognize +- **THEN** the error is an instance of `OscalUnknownElementTypeError` and not an instance of `OscalParseError` + +### Requirement: Each documented limit has its own identifier + +Each documented limit SHALL have the identifier in this list: + +1. JSON depth limit: `json_depth`. +2. JSON digit limit: `json_digits`. +3. YAML alias node limit: `yaml_alias_nodes`. +4. YAML alias character limit: `yaml_alias_characters`. +5. YAML depth limit: `yaml_depth`. +6. YAML line-break placeholder limit: `yaml_line_break_placeholders`. + +No two limits have the same identifier. + +#### Scenario: The two alias limits are told apart + +- **WHEN** the caller compares the identifier of the YAML alias node limit with the identifier of the YAML alias + character limit +- **THEN** the identifiers are `yaml_alias_nodes` and `yaml_alias_characters`, which are different + +### Requirement: A parse error over a documented limit identifies the limit + +The attribute `limit` of an `OscalParseError` SHALL be the limit property of the store's error model: + +1. When a documented limit stopped the parse, `limit` is the identifier of that limit. +2. For each other parse error, `limit` is `None`. + +A caller tests the property of an `OscalParseError` with `error.limit is not None`. Only `OscalParseError` and its +subclasses have the attribute. For an error of any class, the test is `getattr(error, "limit", None) is not None`. + +#### Scenario: A JSON input over the depth limit + +- **WHEN** the caller parses a JSON input that nests deeper than the JSON depth limit +- **THEN** the `limit` of the parse error is `json_depth` + +#### Scenario: A schema failure carries no limit + +- **WHEN** the caller parses a catalog that has no `metadata` +- **THEN** the `limit` of the parse error is `None` + +#### Scenario: A document-type mismatch carries no limit + +- **WHEN** the caller parses a profile with the catalog parser +- **THEN** the `limit` of the error is `None` + +#### Scenario: The two alias limits have different identifiers + +- **WHEN** the caller parses a YAML input whose aliases add more nodes than the node limit +- **AND** the caller parses a second YAML input whose aliases add more characters than the character limit, but fewer + nodes than the node limit +- **THEN** the `limit` of the first parse error is `yaml_alias_nodes` +- **AND** the `limit` of the second parse error is `yaml_alias_characters` + +#### Scenario: A YAML number over the digit limit + +- **WHEN** the caller parses a YAML input with a number of more digits than the digit limit +- **AND** the schema names a number type at the location of the number +- **THEN** the `limit` of the parse error is `json_digits` diff --git a/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/tasks.md b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/tasks.md new file mode 100644 index 0000000..47fbc7c --- /dev/null +++ b/openspec/changes/archive/2026-11-17-add-error-category-tree-and-limit/tasks.md @@ -0,0 +1,69 @@ +# Tasks + +## 1. Baseline before the change + +- [x] 1.1 Run `hatch run python scripts/bench_serialization.py` and `hatch run python scripts/bench_memory.py` on + `main`. Record the medians, GC on and GC off, in the scratchpad. Verify that the record is not empty. + +## 2. Document-type mismatch + +- [x] 2.1 Add `OscalDocumentTypeMismatchError` to `src/oscal_bindings/v1/parser.py`, and make the eight typed parsers + raise it, as [design D1](design.md#d1-a-category-is-a-class-and-the-tree-is-the-class-hierarchy) item 1 states. + Re-export it from `src/oscal_bindings/v1/__init__.py`, and add it to the import list and `__all__` of the legacy + alias module `src/oscal_bindings/parser.py` (design D1 item 3). Add it to `tests/support/version_package.py` and to + `openspec/traceability.json` ([design D6](design.md#d6-traceability)). Verify with new tests in + `tests/test_parser.py`: + 1. A profile through `parse_catalog` raises an error that is an instance of `OscalDocumentTypeMismatchError` and of + `OscalParseError`, with the message that names the catalog. + 2. Input that is not valid JSON raises an `OscalParseError` that is not an instance of + `OscalDocumentTypeMismatchError`. + 3. `from oscal_bindings.parser import OscalDocumentTypeMismatchError` gives the same class as `oscal_bindings.v1`. + +## 3. Unknown element type + +- [x] 3.1 Add `OscalUnknownElementTypeError` to `src/oscal_bindings/v1/extensions/validate_element.py`, and make + `validate_element` raise it, as [design D1](design.md#d1-a-category-is-a-class-and-the-tree-is-the-class-hierarchy) + item 2 states. Update the `Raises` section of the docstring. Re-export the class through `extensions/__init__.py` and + `v1/__init__.py`, and add it to `tests/support/version_package.py` and to `openspec/traceability.json`. Change + `tests/test_validate_element.py` lines 90 and 98 to expect the new class. Change + `tests/test_prop_validate_element.py` line 117 and its module docstring at line 11 to the new class. Verify with a new + test that the error is not an instance of `OscalParseError`. + +## 4. Limit property + +- [x] 4.1 Add the keyword `limit` to `OscalParseError`, and document the attribute in its docstring, as + [design D3](design.md#d3-the-limit-property-is-an-attribute-not-a-class) states. Add ERR-009 and ERR-010 to the + `OscalParseError` entry of `openspec/traceability.json`. +- [x] 4.2 Set `limit` at each of the six raise sites, as + [design D4](design.md#d4-each-raise-site-sets-the-identifier-and-the-entry-types-stay) item 3 states. Verify with new + tests in `tests/test_parser.py` and `tests/test_yaml_io.py`: + 1. Each of the six limits gives its identifier from the spec. + 2. The alias-character test input stays within the alias node limit. + 3. `test_aliases_that_nest_past_the_limit_are_rejected` in `tests/test_yaml_io.py` asserts `limit == "yaml_depth"`, + so the `emit` depth site is covered as well as the compose-stage site. + 4. A schema failure, a document-type mismatch, and a YAML alias cycle each give `limit is None`. +- [x] 4.3 Add a `limit` column to the table in the README section "Resource limits", and add one sentence on the test + `error.limit is not None` for an `OscalParseError` and `getattr(error, "limit", None) is not None` for any error + ([design D3](design.md#d3-the-limit-property-is-an-attribute-not-a-class)). Verify that the table has six rows, each + with the identifier of the spec. + +## 5. Conformance runner and docs + +- [x] 5.1 Change `category` and `test_every_category_is_mapped` in `tests/test_conformance.py`, as + [design D5](design.md#d5-the-runner-reads-the-class-only) states. Verify that `grep -n "startswith"` over + `tests/test_conformance.py` finds no category test, and that `hatch test tests/test_conformance.py` passes. +- [x] 5.2 Update the error text in `README.md`, `AGENTS.md` (the `validate_element` gotcha), and + `.agents/summary/interfaces.md`, `workflows.md`, `components.md`, and `review_notes.md` for the two new classes. + Verify that `grep -rniE "unknown.*OscalParseError|OscalParseError.*unknown" README.md AGENTS.md .agents/summary/` + finds nothing. + +## 6. Final verification + +- [x] 6.1 Repeat task 1.1. Verify that no median moves by more than the run-to-run spread of the two runs. +- [x] 6.2 Run `hatch run release`. Verify that it passes. + +## Workflow follow-up + +- Open the pull request with `Closes #60`. Report the benchmark runs of tasks 1.1 and 6.1 in it, and name the break of + `validate_element` for an unknown element type. +- Archive the change in the pull request, before the merge. diff --git a/openspec/specs/error-tests/spec.md b/openspec/specs/error-tests/spec.md new file mode 100644 index 0000000..0974f2d --- /dev/null +++ b/openspec/specs/error-tests/spec.md @@ -0,0 +1,92 @@ +# error-tests Specification + +## Purpose +Defines how a caller tests whether an error is in a category of the store's error model. Also defines how a caller +tests whether an error carries the limit property of the store's error model. + +## Requirements + +### Requirement: The class of an error is its category + +For each category in this list, an error SHALL be in the category exactly when it is an instance of the class: + +1. Parse error: `OscalParseError`. +2. Document-type mismatch: `OscalDocumentTypeMismatchError`, a subclass of `OscalParseError`. +3. Unknown element type: `OscalUnknownElementTypeError`, which is not a subclass of `OscalParseError`. +4. Access error: `OscalAccessError`. +5. Not-found: `FileNotFoundError`. + +A caller tests a category with `isinstance`. + +#### Scenario: A document-type mismatch is also a parse error + +- **WHEN** the caller parses a profile with the catalog parser +- **THEN** the error is an instance of `OscalDocumentTypeMismatchError` and an instance of `OscalParseError` + +#### Scenario: A parse error of another kind is not a document-type mismatch + +- **WHEN** the caller parses input that is not valid JSON +- **THEN** the error is an instance of `OscalParseError` and not an instance of `OscalDocumentTypeMismatchError` + +#### Scenario: An unknown element type is not a parse error + +- **WHEN** the caller validates an element with an element type that the binding does not recognize +- **THEN** the error is an instance of `OscalUnknownElementTypeError` and not an instance of `OscalParseError` + +### Requirement: Each documented limit has its own identifier + +Each documented limit SHALL have the identifier in this list: + +1. JSON depth limit: `json_depth`. +2. JSON digit limit: `json_digits`. +3. YAML alias node limit: `yaml_alias_nodes`. +4. YAML alias character limit: `yaml_alias_characters`. +5. YAML depth limit: `yaml_depth`. +6. YAML line-break placeholder limit: `yaml_line_break_placeholders`. + +No two limits have the same identifier. + +#### Scenario: The two alias limits are told apart + +- **WHEN** the caller compares the identifier of the YAML alias node limit with the identifier of the YAML alias + character limit +- **THEN** the identifiers are `yaml_alias_nodes` and `yaml_alias_characters`, which are different + +### Requirement: A parse error over a documented limit identifies the limit + +The attribute `limit` of an `OscalParseError` SHALL be the limit property of the store's error model: + +1. When a documented limit stopped the parse, `limit` is the identifier of that limit. +2. For each other parse error, `limit` is `None`. + +A caller tests the property of an `OscalParseError` with `error.limit is not None`. Only `OscalParseError` and its +subclasses have the attribute. For an error of any class, the test is `getattr(error, "limit", None) is not None`. + +#### Scenario: A JSON input over the depth limit + +- **WHEN** the caller parses a JSON input that nests deeper than the JSON depth limit +- **THEN** the `limit` of the parse error is `json_depth` + +#### Scenario: A schema failure carries no limit + +- **WHEN** the caller parses a catalog that has no `metadata` +- **THEN** the `limit` of the parse error is `None` + +#### Scenario: A document-type mismatch carries no limit + +- **WHEN** the caller parses a profile with the catalog parser +- **THEN** the `limit` of the error is `None` + +#### Scenario: The two alias limits have different identifiers + +- **WHEN** the caller parses a YAML input whose aliases add more nodes than the node limit +- **AND** the caller parses a second YAML input whose aliases add more characters than the character limit, but fewer + nodes than the node limit +- **THEN** the `limit` of the first parse error is `yaml_alias_nodes` +- **AND** the `limit` of the second parse error is `yaml_alias_characters` + +#### Scenario: A YAML number over the digit limit + +- **WHEN** the caller parses a YAML input with a number of more digits than the digit limit +- **AND** the schema names a number type at the location of the number +- **THEN** the `limit` of the parse error is `json_digits` diff --git a/openspec/traceability.json b/openspec/traceability.json index 6553155..99a7377 100644 --- a/openspec/traceability.json +++ b/openspec/traceability.json @@ -27,6 +27,8 @@ { "name": "make_hash", "requirements": ["BMB-001"] }, { "name": "make_rlink", "requirements": ["BMB-002"] }, { "name": "make_resource", "requirements": ["BMB-003"] }, - { "name": "OscalParseError", "requirements": ["ERR-001", "ERR-003"] } + { "name": "OscalParseError", "requirements": ["ERR-001", "ERR-003", "ERR-009", "ERR-010"] }, + { "name": "OscalDocumentTypeMismatchError", "requirements": ["ERR-005", "ERR-009"] }, + { "name": "OscalUnknownElementTypeError", "requirements": ["ERR-008", "ERR-009"] } ] } diff --git a/src/oscal_bindings/parser.py b/src/oscal_bindings/parser.py index 5cea774..49d23db 100644 --- a/src/oscal_bindings/parser.py +++ b/src/oscal_bindings/parser.py @@ -20,6 +20,7 @@ ComponentDefinitionDocument, MappingCollectionDocument, OscalDocument, + OscalDocumentTypeMismatchError, OscalParseError, PlanOfActionAndMilestonesDocument, ProfileDocument, @@ -45,6 +46,7 @@ "ComponentDefinitionDocument", "MappingCollectionDocument", "OscalDocument", + "OscalDocumentTypeMismatchError", "OscalParseError", "PlanOfActionAndMilestonesDocument", "ProfileDocument", diff --git a/src/oscal_bindings/v1/__init__.py b/src/oscal_bindings/v1/__init__.py index 9617f78..1bf0815 100644 --- a/src/oscal_bindings/v1/__init__.py +++ b/src/oscal_bindings/v1/__init__.py @@ -40,6 +40,7 @@ OscalAccessError, OscalBody, OscalDoc, + OscalUnknownElementTypeError, OscalWrapper, get_supported_element_types, make_hash, @@ -58,6 +59,7 @@ ComponentDefinitionDocument, MappingCollectionDocument, OscalDocument, + OscalDocumentTypeMismatchError, OscalParseError, PlanOfActionAndMilestonesDocument, ProfileDocument, @@ -99,7 +101,9 @@ "OscalBody", "OscalDoc", "OscalDocument", + "OscalDocumentTypeMismatchError", "OscalParseError", + "OscalUnknownElementTypeError", "OscalWrapper", "PlanOfActionAndMilestonesDocument", "ProfileDocument", diff --git a/src/oscal_bindings/v1/extensions/__init__.py b/src/oscal_bindings/v1/extensions/__init__.py index 44ad3a5..b039a5b 100644 --- a/src/oscal_bindings/v1/extensions/__init__.py +++ b/src/oscal_bindings/v1/extensions/__init__.py @@ -11,6 +11,7 @@ ) from oscal_bindings.v1.extensions.validate_element import ( ElementValidationResult, + OscalUnknownElementTypeError, get_supported_element_types, validate_element, ) @@ -33,6 +34,7 @@ "OscalAccessError", "OscalBody", "OscalDoc", + "OscalUnknownElementTypeError", "OscalWrapper", "get_supported_element_types", "make_hash", diff --git a/src/oscal_bindings/v1/extensions/_yaml_loader.py b/src/oscal_bindings/v1/extensions/_yaml_loader.py index db3e830..21924d9 100644 --- a/src/oscal_bindings/v1/extensions/_yaml_loader.py +++ b/src/oscal_bindings/v1/extensions/_yaml_loader.py @@ -98,18 +98,20 @@ def _brief(text: str) -> str: return f"{text[:_QUOTE_LIMIT]!r}... ({len(text):,} characters)" -def _fail( +def _fail( # noqa: PLR0913 -- one keyword for each field of the entry kind: str, message: str, *, loc: tuple[str | int, ...] = (), at: tuple[int | None, int | None] = (None, None), text: str | None = None, + limit: str | None = None, ) -> NoReturn: """Raise a parse error with one entry in the Pydantic entry shape. ``loc`` is the JSON path, as in a Pydantic entry. ``at`` is the 1-based line - and column in the YAML source. + and column in the YAML source. ``limit`` is the identifier of the documented + limit, for a limit failure only. """ line, column = at entry = { @@ -120,7 +122,7 @@ def _fail( "line": line, "column": column, } - raise OscalParseError(message, errors=[entry]) + raise OscalParseError(message, errors=[entry], limit=limit) # --- Stage 1: YAML 1.1 line-break characters ---------------------------------- @@ -168,6 +170,7 @@ def _shield(text: str) -> tuple[str, dict[int, int] | None]: "line_break_placeholder", "YAML input holds U+0085, U+2028, or U+2029 and leaves no free " "private-use placeholder for it", + limit="yaml_line_break_placeholders", ) forward = {ord(ch): cp for ch, cp in zip(_YAML11_BREAKS, chosen, strict=True)} restore = {cp: ord(ch) for ch, cp in zip(_YAML11_BREAKS, chosen, strict=True)} @@ -266,6 +269,7 @@ def _compose_child( "depth_limit", f"YAML nesting exceeds the depth limit of {DEPTH_LIMIT}", at=at, + limit="yaml_depth", ) if isinstance(event, AliasEvent): target = anchors.get(event.anchor or "") @@ -555,6 +559,7 @@ def charge( f"YAML aliases add more than the limit of {ALIAS_NODE_LIMIT:,} nodes", loc=self.path(slot), at=(line, column), + limit="yaml_alias_nodes", ) if self.alias_chars > ALIAS_CHAR_LIMIT: _fail( @@ -563,6 +568,7 @@ def charge( f"{ALIAS_CHAR_LIMIT:,} characters", loc=self.path(slot), at=(line, column), + limit="yaml_alias_characters", ) def run(self, root: _Node) -> str: @@ -649,6 +655,7 @@ def emit( f"YAML nesting exceeds the depth limit of {DEPTH_LIMIT}", loc=self.path(slot), at=(item.line, item.column), + limit="yaml_depth", ) if node.kind == _SCALAR: if charged: @@ -688,7 +695,9 @@ def scalar(self, node: _Node, schema: Any, slot: str | int | None) -> str: "line": node.line, "column": node.column, } - raise OscalParseError(JSON_DIGIT_LIMIT_MSG, errors=[entry]) + raise OscalParseError( + JSON_DIGIT_LIMIT_MSG, errors=[entry], limit="json_digits" + ) return text _fail( "number_grammar", diff --git a/src/oscal_bindings/v1/extensions/validate_element.py b/src/oscal_bindings/v1/extensions/validate_element.py index 35e6ac1..a6276da 100644 --- a/src/oscal_bindings/v1/extensions/validate_element.py +++ b/src/oscal_bindings/v1/extensions/validate_element.py @@ -10,12 +10,18 @@ from pydantic import ValidationError as PydanticValidationError import oscal_bindings.v1.models as _models -from oscal_bindings.v1.parser import OscalParseError if TYPE_CHECKING: from collections.abc import Callable +class OscalUnknownElementTypeError(Exception): + """Raised when ``validate_element`` gets an unrecognized element type. + + Not a subclass of :class:`OscalParseError`: it is a category of its own. + """ + + @dataclass class ValidationError: path: str @@ -112,10 +118,10 @@ def validate_element(element: Any, element_type: str) -> ElementValidationResult ElementValidationResult with valid=True or valid=False with errors. Raises: - OscalParseError: If element_type is not recognized. + OscalUnknownElementTypeError: If element_type is not recognized. """ if element_type not in _ELEMENT_MAP: - raise OscalParseError( + raise OscalUnknownElementTypeError( f'Unknown element type: "{element_type}". ' "Supported types include: " f"{', '.join(sorted(list(_ELEMENT_MAP.keys())[:10]))}..." diff --git a/src/oscal_bindings/v1/parser.py b/src/oscal_bindings/v1/parser.py index 632096f..b73e587 100644 --- a/src/oscal_bindings/v1/parser.py +++ b/src/oscal_bindings/v1/parser.py @@ -51,6 +51,12 @@ def __reduce__(self) -> tuple[type[_OmittedInput], tuple[()]]: class OscalParseError(Exception): """Raised when an OSCAL document cannot be parsed or validated. + ``limit`` is the identifier of the documented resource limit that stopped the + parse, one of ``json_depth``, ``json_digits``, ``yaml_alias_nodes``, + ``yaml_alias_characters``, ``yaml_depth``, and ``yaml_line_break_placeholders``. + For each other parse error, ``limit`` is ``None``. Test an ``OscalParseError`` + with ``error.limit is not None``. + ``errors`` holds the structured entries, in the Pydantic entry shape. A schema-conformance failure gives one entry for each failing location. The ``input`` of such an entry is the failing value when it is a string, a @@ -71,9 +77,24 @@ class OscalParseError(Exception): #: The ``input`` of an entry whose failing value is an object or an array. OMITTED_INPUT: ClassVar[Any] = _OmittedInput() - def __init__(self, message: str, errors: list[Any] | None = None) -> None: + def __init__( + self, + message: str, + errors: list[Any] | None = None, + *, + limit: str | None = None, + ) -> None: super().__init__(message) self.errors = errors or [] + self.limit = limit + + +class OscalDocumentTypeMismatchError(OscalParseError): + """Raised when a typed parser reads a document of another type. + + A subclass of :class:`OscalParseError`, so ``except OscalParseError`` also + catches it. A parse error of another kind is not an instance of this class. + """ #: The JSON depth limit (PRS-010). A value that more than this many arrays and @@ -97,6 +118,11 @@ def __init__(self, message: str, errors: list[Any] | None = None) -> None: ("recursion limit exceeded", "json_depth_limit", JSON_DEPTH_LIMIT_MSG), ("number out of range", "json_digit_limit", JSON_DIGIT_LIMIT_MSG), ) +# The ``limit`` identifier of each JSON limit entry type (design D4). +_LIMIT_IDENTIFIERS = { + "json_depth_limit": "json_depth", + "json_digit_limit": "json_digits", +} _POSITION = re.compile(r" at line (\d+) column (\d+)$") @@ -180,7 +206,9 @@ def parse_oscal(data: str | bytes) -> OscalDocument: # Raised outside the handler, so that neither __cause__ nor __context__ # holds the ValidationError and its copy of the input. if limit is not None: - raise OscalParseError(limit["msg"], errors=[limit]) + raise OscalParseError( + limit["msg"], errors=[limit], limit=_LIMIT_IDENTIFIERS[limit["type"]] + ) raise OscalParseError( f"Failed to parse OSCAL document: {len(errors)} validation error(s)", errors=errors, @@ -274,7 +302,7 @@ def parse_catalog(data: str | bytes) -> CatalogDocument: """Parse an OSCAL Catalog document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "catalog"): - raise OscalParseError("Document is not a Catalog") + raise OscalDocumentTypeMismatchError("Document is not a Catalog") return cast("CatalogDocument", doc.root) @@ -282,7 +310,7 @@ def parse_profile(data: str | bytes) -> ProfileDocument: """Parse an OSCAL Profile document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "profile"): - raise OscalParseError("Document is not a Profile") + raise OscalDocumentTypeMismatchError("Document is not a Profile") return cast("ProfileDocument", doc.root) @@ -290,7 +318,7 @@ def parse_component_definition(data: str | bytes) -> ComponentDefinitionDocument """Parse an OSCAL Component Definition document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "component_definition"): - raise OscalParseError("Document is not a Component Definition") + raise OscalDocumentTypeMismatchError("Document is not a Component Definition") return cast("ComponentDefinitionDocument", doc.root) @@ -298,7 +326,7 @@ def parse_system_security_plan(data: str | bytes) -> SystemSecurityPlanDocument: """Parse an OSCAL System Security Plan document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "system_security_plan"): - raise OscalParseError("Document is not a System Security Plan") + raise OscalDocumentTypeMismatchError("Document is not a System Security Plan") return cast("SystemSecurityPlanDocument", doc.root) @@ -306,7 +334,7 @@ def parse_assessment_plan(data: str | bytes) -> AssessmentPlanDocument: """Parse an OSCAL Assessment Plan document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "assessment_plan"): - raise OscalParseError("Document is not an Assessment Plan") + raise OscalDocumentTypeMismatchError("Document is not an Assessment Plan") return cast("AssessmentPlanDocument", doc.root) @@ -314,7 +342,7 @@ def parse_assessment_results(data: str | bytes) -> AssessmentResultsDocument: """Parse an OSCAL Assessment Results document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "assessment_results"): - raise OscalParseError("Document is not Assessment Results") + raise OscalDocumentTypeMismatchError("Document is not Assessment Results") return cast("AssessmentResultsDocument", doc.root) @@ -327,7 +355,9 @@ def parse_plan_of_action_and_milestones( """ doc = parse_oscal(data) if not hasattr(doc.root, "plan_of_action_and_milestones"): - raise OscalParseError("Document is not a Plan of Action and Milestones") + raise OscalDocumentTypeMismatchError( + "Document is not a Plan of Action and Milestones" + ) return cast("PlanOfActionAndMilestonesDocument", doc.root) @@ -335,5 +365,5 @@ def parse_mapping_collection(data: str | bytes) -> MappingCollectionDocument: """Parse an OSCAL Mapping Collection document (accepts `str` or `bytes`).""" doc = parse_oscal(data) if not hasattr(doc.root, "mapping_collection"): - raise OscalParseError("Document is not a Mapping Collection") + raise OscalDocumentTypeMismatchError("Document is not a Mapping Collection") return cast("MappingCollectionDocument", doc.root) diff --git a/tests/support/version_package.py b/tests/support/version_package.py index 6daf872..cd8faa8 100644 --- a/tests/support/version_package.py +++ b/tests/support/version_package.py @@ -41,7 +41,9 @@ "OscalBody", "OscalDoc", "OscalDocument", + "OscalDocumentTypeMismatchError", "OscalParseError", + "OscalUnknownElementTypeError", "OscalWrapper", "PlanOfActionAndMilestonesDocument", "ProfileDocument", diff --git a/tests/test_conformance.py b/tests/test_conformance.py index c6a434d..8232488 100644 --- a/tests/test_conformance.py +++ b/tests/test_conformance.py @@ -20,7 +20,13 @@ from support.spec_artifact import corpus_root import oscal_bindings as ob -from oscal_bindings import OscalAccessError, OscalDoc, OscalParseError +from oscal_bindings import ( + OscalAccessError, + OscalDoc, + OscalDocumentTypeMismatchError, + OscalParseError, + OscalUnknownElementTypeError, +) if TYPE_CHECKING: from collections.abc import Callable @@ -41,19 +47,17 @@ def category(error: BaseException) -> str | None: """Map an exception to a corpus error category, or None for any other error. - The library has no typed error for a document-type mismatch or an unknown - element type, so those two categories come from the message prefix. + The class of the error is its category. A subclass comes before its parent. """ if isinstance(error, FileNotFoundError): return "not-found" if isinstance(error, OscalAccessError): return "access-error" + if isinstance(error, OscalUnknownElementTypeError): + return "unknown-element-type" + if isinstance(error, OscalDocumentTypeMismatchError): + return "document-type-mismatch" if isinstance(error, OscalParseError): - message = str(error) - if message.startswith("Document is not"): - return "document-type-mismatch" - if message.startswith("Unknown element type"): - return "unknown-element-type" return "parse-error" return None @@ -231,8 +235,8 @@ def test_every_category_is_mapped() -> None: mapped = { category(FileNotFoundError()), category(OscalAccessError()), - category(OscalParseError("Document is not a Catalog")), - category(OscalParseError("Unknown element type: x")), + category(OscalDocumentTypeMismatchError("Document is not a Catalog")), + category(OscalUnknownElementTypeError("Unknown element type: x")), category(OscalParseError("Failed to parse")), } assert set(index["categories"]) == mapped diff --git a/tests/test_parser.py b/tests/test_parser.py index 6029a3f..830ee6b 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -16,6 +16,7 @@ from oscal_bindings import OscalDoc from oscal_bindings.parser import ( OscalDocument, + OscalDocumentTypeMismatchError, OscalParseError, parse_catalog, parse_component_definition, @@ -329,6 +330,26 @@ def test_parse_catalog_wrong_type(self): with pytest.raises(OscalParseError, match="not a Catalog"): parse_catalog(MINIMAL_PROFILE) + def test_wrong_type_is_a_document_type_mismatch(self): + with pytest.raises( + OscalDocumentTypeMismatchError, match="not a Catalog" + ) as excinfo: + parse_catalog(MINIMAL_PROFILE) + assert isinstance(excinfo.value, OscalParseError) + + def test_invalid_json_is_not_a_document_type_mismatch(self): + with pytest.raises(OscalParseError) as excinfo: + parse_catalog("{not json") + assert not isinstance(excinfo.value, OscalDocumentTypeMismatchError) + + def test_mismatch_error_is_the_same_class_on_both_paths(self): + import oscal_bindings.parser as legacy + from oscal_bindings import v1 + + assert ( + legacy.OscalDocumentTypeMismatchError is v1.OscalDocumentTypeMismatchError + ) + def test_parse_profile_valid(self): result = parse_profile(MINIMAL_PROFILE) assert result.profile.uuid == "f47ac10b-58cc-4372-a567-0e02b2c3d479" @@ -554,6 +575,46 @@ def test_schema_invalid_document_over_the_limit_gets_one_limit_entry( assert entry["type"] == "json_digit_limit" +class TestLimitIdentifier: + """The ``limit`` of an ``OscalParseError`` (spec error-tests).""" + + @staticmethod + def _error( + text: str, parse: Callable[[str], object] = parse_oscal + ) -> OscalParseError: + with pytest.raises(OscalParseError) as info: + parse(text) + return info.value + + def test_json_depth(self) -> None: + assert self._error(_deep_catalog(PAST_DEPTH_LIMIT)).limit == "json_depth" + + def test_json_digits(self) -> None: + assert self._error(_component(PAST_DIGIT_LIMIT)).limit == "json_digits" + + def test_schema_failure_has_no_limit(self) -> None: + text = json.dumps({"catalog": {"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}}) + assert self._error(text).limit is None + + def test_invalid_json_has_no_limit(self) -> None: + assert self._error("{not json").limit is None + + def test_document_type_mismatch_has_no_limit(self) -> None: + error = self._error(MINIMAL_PROFILE, parse_catalog) + assert isinstance(error, OscalDocumentTypeMismatchError) + assert error.limit is None + + def test_a_yaml_alias_cycle_has_no_limit(self) -> None: + from oscal_bindings.v1 import parse_oscal_yaml + + head = ( + "catalog:\n uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479\n" + " metadata:\n title: T\n" + ) + error = self._error(head + " remarks: &a [*a]\n", parse_oscal_yaml) + assert error.limit is None + + class TestJsonLimitErrorShape: @pytest.mark.parametrize( "text", diff --git a/tests/test_prop_validate_element.py b/tests/test_prop_validate_element.py index b2179f1..01a17bc 100644 --- a/tests/test_prop_validate_element.py +++ b/tests/test_prop_validate_element.py @@ -8,7 +8,7 @@ class to `_LEAF_MODELS` below. Property 9 checks that any element type name outside -`get_supported_element_types()` is rejected with `OscalParseError`. +`get_supported_element_types()` is rejected with `OscalUnknownElementTypeError`. Example counts come from the ``ci`` Hypothesis profile registered in ``tests/conftest.py`` (``max_examples=100``); no per-test ``@settings``. @@ -24,7 +24,7 @@ class to `_LEAF_MODELS` below. from strategies import LEAF_ELEMENT_TYPES, leaf_instance_strategy from oscal_bindings.v1 import ( - OscalParseError, + OscalUnknownElementTypeError, get_supported_element_types, validate_element, ) @@ -114,5 +114,5 @@ def test_validate_element_rejects_unknown_types( **Validates: Requirements 9.3** """ - with pytest.raises(OscalParseError): + with pytest.raises(OscalUnknownElementTypeError): validate_element(element, element_type) diff --git a/tests/test_validate_element.py b/tests/test_validate_element.py index 19dc1d5..ff9313b 100644 --- a/tests/test_validate_element.py +++ b/tests/test_validate_element.py @@ -7,6 +7,7 @@ validate_element, ) from oscal_bindings.parser import OscalParseError +from oscal_bindings.v1 import OscalUnknownElementTypeError # Minimal valid observation VALID_OBSERVATION = { @@ -87,7 +88,7 @@ def test_union_rejects_an_unknown_key(self): assert result.errors def test_root_model_is_not_an_element_type(self): - with pytest.raises(OscalParseError, match="Unknown element type"): + with pytest.raises(OscalUnknownElementTypeError, match="Unknown element type"): validate_element({}, "root-model") @@ -95,9 +96,14 @@ class TestValidateElementErrors: """Tests for error handling.""" def test_unknown_element_type_raises(self): - with pytest.raises(OscalParseError, match="Unknown element type"): + with pytest.raises(OscalUnknownElementTypeError, match="Unknown element type"): validate_element({}, "nonexistent-type") + def test_unknown_element_type_is_not_a_parse_error(self): + with pytest.raises(OscalUnknownElementTypeError) as excinfo: + validate_element({}, "nonexistent-type") + assert not isinstance(excinfo.value, OscalParseError) + def test_error_path_populated(self): result = validate_element({}, "observation") assert result.valid is False diff --git a/tests/test_yaml_io.py b/tests/test_yaml_io.py index e3baf79..7100e4f 100644 --- a/tests/test_yaml_io.py +++ b/tests/test_yaml_io.py @@ -558,6 +558,9 @@ def test_no_free_placeholder_is_parse_error(self) -> None: ) entry = _yaml_error(f"# {every}\nb: x\x85y\n") assert entry["type"] == "yaml_line_break_placeholder" + with pytest.raises(OscalParseError) as info: + parse_oscal_yaml(f"# {every}\nb: x\x85y\n") + assert info.value.limit == "yaml_line_break_placeholders" # --- Task 3.1, 3.2: parse operations ------------------------------------------ @@ -779,6 +782,31 @@ def test_content_without_aliases_does_not_charge_the_budget(self) -> None: assert len(md["props"]) == 2_000 +class TestLimitIdentifier: + """The ``limit`` of a YAML limit error (spec error-tests).""" + + @staticmethod + def _limit(text: str) -> str | None: + with pytest.raises(OscalParseError) as info: + parse_oscal_yaml(text) + limit: str | None = info.value.limit + return limit + + def test_alias_node_limit(self) -> None: + assert self._limit(_wide_alias(999, 101)) == "yaml_alias_nodes" + + def test_alias_character_limit_within_the_node_limit(self) -> None: + # 101 aliases charge 101 nodes, far below the node limit. + assert self._limit(_scalar_alias(10_000, 101)) == "yaml_alias_characters" + + def test_depth_limit(self) -> None: + assert self._limit(_nested(DEPTH_LIMIT + 1)) == "yaml_depth" + + def test_a_failure_that_is_not_a_limit_has_no_limit(self) -> None: + text = HEAD + " remarks: &a [*a]\n" + assert self._limit(text) is None + + class TestDepthLimit: def test_input_at_the_depth_limit_is_not_rejected_for_depth(self) -> None: assert json.loads(to_json_text(_nested(DEPTH_LIMIT))) @@ -816,6 +844,8 @@ def test_aliases_that_nest_past_the_limit_are_rejected(self) -> None: entry = info.value.errors[0] assert entry["loc"][:3] == ("catalog", "metadata", "x") assert entry["line"] == 8 + # The expanded depth is checked in `emit`, not at the compose stage. + assert info.value.limit == "yaml_depth" class TestJsonDigitLimit: @@ -839,6 +869,7 @@ def test_number_past_the_limit_names_the_limit_at_its_yaml_location( parse(text) (entry,) = info.value.errors assert entry["type"] == "json_digit_limit" + assert info.value.limit == "json_digits" assert entry["msg"] == str(info.value) == JSON_DIGIT_LIMIT_MSG assert entry["input"] is None assert (entry["line"], entry["column"]) == self._position(text, digits)