assertions-mate 0.2.0__tar.gz → 0.4.0__tar.gz

assertions_mate-0.4.0/.env

@@ -0,0 +1 @@
+TASK_X_REMOTE_TASKFILES=1

{assertions_mate-0.2.0 → assertions_mate-0.4.0}/.gitignore

@@ -6,4 +6,6 @@ docs/diagrams/out
 openapi_bundled.yaml
 *.pyc
 schema.yaml
-src/assertions_mate/__pycache__
+src/assertions_mate/__pycache__
+.task
+.vscode

{assertions_mate-0.2.0 → assertions_mate-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertions-mate
-Version: 0.2.0
+Version: 0.4.0
 Project-URL: Documentation, https://github.com/Terradue/assertions-mate#README.md
 Project-URL: Issues, https://github.com/Terradue/assertions-mate/issues
 Project-URL: Source, https://github.com/Terradue/assertions-mate
@@ -42,6 +42,12 @@ It adds policy and rule checks on top of CWL typing by supporting:
 
 Documentation site: https://terradue.github.io/assertions-mate/
 
+Documentation follows the Diataxis framework:
+- Tutorials: learning-oriented walkthroughs
+- How-to guides: task-focused recipes
+- Reference: technical contracts and interfaces
+- Explanation: design rationale and concepts
+
 ## Why Use It
 
 When a CWL workflow needs stricter runtime checks (business rules, policy constraints, geospatial conditions), `assertions-mate` lets you define them as workflow hints and evaluate them against an input payload before execution.

{assertions_mate-0.2.0 → assertions_mate-0.4.0}/README.md

@@ -9,6 +9,12 @@ It adds policy and rule checks on top of CWL typing by supporting:
 
 Documentation site: https://terradue.github.io/assertions-mate/
 
+Documentation follows the Diataxis framework:
+- Tutorials: learning-oriented walkthroughs
+- How-to guides: task-focused recipes
+- Reference: technical contracts and interfaces
+- Explanation: design rationale and concepts
+
 ## Why Use It
 
 When a CWL workflow needs stricter runtime checks (business rules, policy constraints, geospatial conditions), `assertions-mate` lets you define them as workflow hints and evaluate them against an input payload before execution.

assertions_mate-0.4.0/Taskfile.yaml

@@ -0,0 +1,46 @@
+# Copyright 2026 Terradue
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+version: '3'
+
+includes:
+  quality: https://raw.githubusercontent.com/Terradue/taskfile-utils/refs/heads/main/quality.yaml
+
+tasks:
+
+  default:
+    cmds:
+    - task: quality:test
+    - task: quality:check
+
+  generate_schema_doc:
+    cmds:
+    - |
+      uv run \
+      --no-cache \
+      --no-project \
+      --with schema-salad \
+      schema-salad-doc \
+      --only 'http://oeap.github.io/schema#JSONSchemaHint' \
+      --only 'http://oeap.github.io/schema#RegoPolicyHint' \
+      --only 'http://oeap.github.io/schema#Cql2Query' \
+      --only 'http://oeap.github.io/schema#Cql2FilterHint' \
+      ./schemas/hints.yaml > ./docs/reference/hints_schema.html
+
+  docs:serve:
+    desc: "Serve MkDocs site using hatch docs environment"
+    cmds:
+      - |
+        set -euo pipefail
+        HATCH_DATA_DIR="$PWD/.task/hatch" hatch run docs:serve

assertions_mate-0.4.0/docs/explanation/architecture.md

@@ -0,0 +1,66 @@
+# Architecture and Design
+
+`assertions-mate` is built around hint-driven validation for CWL workflows.
+
+## Why Hints
+
+CWL input typing can enforce structure, but many operational constraints are semantic:
+- policy constraints
+- domain rules
+- geospatial relationships
+
+Hints let these constraints travel with workflow definitions and be checked consistently before runtime.
+
+## Validation Flow
+
+1. Load CWL workflow document(s).
+2. Read `workflow.hints`.
+3. Map supported `eoap:*` hint classes to typed hint models.
+4. Build validator objects from hints.
+5. Run each validator against provided inputs.
+6. Aggregate and log violations.
+
+## Execution Semantics
+
+`assertions-mate` follows a best-effort setup model:
+
+- each hint is mapped and initialized independently
+- setup failures for one hint do not prevent other hints from running
+- validation output is therefore partial if one validator fails to initialize
+
+This model favors operational continuity and progressive validation.
+
+## Validator Model
+
+Each hint type is responsible for producing a validator via `.validator()`.
+
+This keeps:
+- hint parsing and serialization concerns in hint models
+- runtime validation behavior in validator classes
+
+## Input Shape and Key Resolution
+
+Validators operate on the loaded input mapping as-is.
+
+Implications:
+- input keys must match workflow input names exactly
+- object wrappers such as `value` must be handled explicitly in rules (for example in Rego)
+- inconsistent shape across workflows can produce false negatives if rules target the wrong path
+
+## Supported Rule Languages
+
+- JSON Schema: structural constraints over payload shape and values
+- Rego: policy-oriented queries and rich rule composition
+- CQL2: declarative predicate checks, including geospatial expressions
+
+## Reliability Tradeoffs
+
+- Strength: multi-validator execution can still produce useful checks when one hint fails setup.
+- Tradeoff: setup errors and runtime backend constraints may reduce total coverage for a given run.
+- Practical guidance: treat logs as part of the contract and monitor setup failures explicitly in CI.
+
+## Known Gaps and Improvement Areas
+
+- Runtime-specific parser differences can affect CWL load behavior and Rego syntax support.
+- Some CQL2 features require explicit coercion helpers (`ensure_spatial`, `ensure_bbox`).
+- Strict fail-fast exit semantics for reported violations are not yet guaranteed in all execution paths.

assertions_mate-0.4.0/docs/explanation/compatibility-and-limitations.md

@@ -0,0 +1,40 @@
+# Compatibility and Limitations
+
+This page explains where runtime behavior depends on parser and backend versions.
+
+## Rego Runtime Coupling
+
+Rego syntax support is runtime-dependent.
+
+Stable pattern in current examples:
+
+```rego
+deny[msg] {
+  condition
+  msg := "..."
+}
+```
+
+Depending on runtime, newer syntax forms can fail with parser errors such as `Invalid literal`.
+
+## CQL2 Backend Constraints
+
+CQL2 spatial predicates operate reliably when payloads are coerced with helper functions:
+
+- `ensure_spatial(...)` for GeoJSON geometry objects
+
+Without coercion, backend exceptions can occur because predicates receive non-geometry objects.
+
+## External CWL Type References
+
+External schema refs (for example EOAP `#DateTime`, `#Polygon`) may require online resolution and parser compatibility.
+
+Operational impact:
+- local/offline environments may fail to resolve external refs
+- integration tests should allow offline skip behavior
+
+## JSON CQL2 From YAML
+
+YAML-native scalar wrappers can affect CQL2 JSON evaluation if not normalized.
+
+Current validator behavior includes normalization to builtin Python values before parsing CQL2 JSON, improving reliability.

assertions_mate-0.4.0/docs/explanation/testing-and-reliability.md

@@ -0,0 +1,32 @@
+# Testing and Reliability
+
+This project benefits from a split testing strategy.
+
+## Unit Tests
+
+Focus on deterministic behavior with local types and direct validator logic.
+
+Examples:
+- hint extraction and mapping tests
+- CQL2 text/json predicate tests
+- JSON schema validation tests
+
+## Integration-Oriented Tests
+
+Use real example workflows and external type references.
+
+Because these can require network and parser compatibility, they should:
+- skip when offline
+- be isolated from core deterministic tests
+
+## Reliability Patterns for CI
+
+- treat hint setup errors as first-class signals
+- include at least one valid and one invalid case per how-to example
+- prefer stable syntax subsets for Rego and CQL2 in production pipelines
+
+## Practical Guardrails
+
+- keep payload key names aligned with workflow inputs
+- document scalar vs wrapped object shapes (`value`) and test both where applicable
+- reuse proven example expressions to avoid backend incompatibilities

assertions_mate-0.4.0/docs/how-to/add-cql2-polygon-area-function.md

@@ -0,0 +1,57 @@
+# How-to: Add `polygon_area(...)` to the CQL2 Evaluator
+
+This guide shows how to extend `assertions-mate` so CQL2 rules can compare polygon area against a fixed threshold.
+
+## Goal
+
+Enable expressions like:
+
+```text
+polygon_area(aoi) < 1000
+```
+
+## 1. Define the new function in a CQL2 hint
+
+In your workflow hints, plug the suggested implementation:
+
+```yaml
+hints:
+  - class: eoap:Cql2FilterHint
+    custom_functions: |
+        from shapely import geometry
+        from typing import Any, List, Mapping, Union
+
+        def polygon_area(input: Union[Mapping[str, Any], List[Any]]):
+            """Return area for a GeoJSON Polygon payload or raw coordinates list."""
+            if isinstance(input, dict):
+                geo_type = input.get("type")
+                coords = input.get("coordinates")
+                if geo_type != "Polygon" or not coords:
+                    raise ValueError("Input must be a GeoJSON Polygon with coordinates")
+                geom = geometry.Polygon(coords[0])
+                return geom.area
+
+            if isinstance(input, list):
+                geom = geometry.Polygon(input[0] if input and isinstance(input[0], list) else input)
+                return geom.area
+
+            raise ValueError(f"Unsupported polygon input type: {type(input)}")
+    queries:
+      - id: aoi-area-limit
+        cql2: "polygon_area(aoi) < 1000"
+        message: "AOI area must be smaller than 1000"
+```
+
+## 2. Validate with CLI
+
+```bash
+assertions-mate path/to/workflow.cwl --inputs path/to/inputs.yaml
+```
+
+## Notes on units
+
+If AOI coordinates are lon/lat (EPSG:4326), `polygon_area` from Shapely returns degree-squared values, not square meters.
+
+For metric thresholds, either:
+- reproject geometry before computing area
+- or compute geodesic area with a dedicated geodesic approach

assertions_mate-0.4.0/docs/how-to/author-cql2-json-encoding.md

@@ -0,0 +1,46 @@
+# How-to: Author CQL2 Rules in JSON Encoding
+
+You can provide `cql2` as JSON, not only text.
+
+## 1. Define the input
+
+```yaml
+inputs:
+  mode:
+    type: string
+```
+
+## 2. Add CQL2 JSON rule
+
+```yaml
+hints:
+  - class: eoap:Cql2FilterHint
+    queries:
+      - id: mode-is-strict
+        cql2:
+          op: "="
+          args:
+            - property: mode
+            - "strict"
+        message: "mode must be strict"
+```
+
+## 3. Validate with sample values
+
+Valid:
+
+```yaml
+mode: "strict"
+```
+
+Run:
+
+```bash
+assertions-mate workflow.cwl --inputs inputs-valid.yaml
+```
+
+## Ready-to-run example in this repository
+
+- `examples/cql2-json-validation/workflow.cwl`
+- `examples/cql2-json-validation/inputs-valid.yaml`
+- `examples/cql2-json-validation/inputs-invalid.yaml`

assertions_mate-0.4.0/docs/how-to/combine-multiple-hints.md

@@ -0,0 +1,57 @@
+# How-to: Combine Multiple Hints in One Workflow
+
+Use `JSONSchemaHint`, `RegoPolicyHint`, and `Cql2FilterHint` together to enforce structure, policy, and spatial predicates.
+
+## 1. Define the inputs
+
+```yaml
+inputs:
+  count:
+    type: int
+  aoi:
+    type: https://raw.githubusercontent.com/eoap/schemas/main/geojson.yaml#Polygon
+  candidate:
+    type: https://raw.githubusercontent.com/eoap/schemas/main/geojson.yaml#Polygon
+```
+
+## 2. Add multiple hints
+
+```yaml
+hints:
+  - class: eoap:JSONSchemaHint
+    json_schema:
+      type: object
+      required: [count, aoi, candidate]
+      properties:
+        count:
+          type: integer
+          minimum: 1
+  - class: eoap:RegoPolicyHint
+    module: |
+      package workflow
+      deny[msg] {
+        input["count"] > 10
+        msg := "count must be <= 10"
+      }
+    queries:
+      - data.workflow.deny[_]
+  - class: eoap:Cql2FilterHint
+    queries:
+      - id: spatial-check
+        cql2: "s_intersects(ensure_spatial(candidate), ensure_spatial(aoi))"
+        message: "candidate must intersect aoi"
+```
+
+## 3. Validate with sample values
+
+Run:
+
+```bash
+assertions-mate workflow.cwl --inputs inputs-valid.yaml
+```
+
+## Ready-to-run example in this repository
+
+- `examples/multi-hint-validation/workflow.cwl`
+- `examples/multi-hint-validation/inputs-valid.yaml`
+- `examples/multi-hint-validation/inputs-invalid.yaml`

assertions_mate-0.4.0/docs/how-to/create-reusable-rego-snippets.md

@@ -0,0 +1,52 @@
+# How-to: Create Reusable Rego Snippets
+
+Keep common checks reusable by copying a shared module block between workflows.
+
+## 1. Define the inputs
+
+```yaml
+inputs:
+  start-date:
+    type: string
+  end-date:
+    type: string
+```
+
+## 2. Add reusable Rego helper
+
+```rego
+package workflow
+
+is_rfc3339_utc(s) {
+  regex.match("^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$", s)
+}
+```
+
+Then reuse in multiple deny rules.
+
+## 3. Add hint using the helper
+
+```yaml
+hints:
+  - class: eoap:RegoPolicyHint
+    module: |
+      package workflow
+
+      is_rfc3339_utc(s) {
+        regex.match("^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$", s)
+      }
+
+      deny[msg] {
+        s := input["start-date"]
+        not is_rfc3339_utc(s)
+        msg := "start-date format is invalid"
+      }
+    queries:
+      - data.workflow.deny[_]
+```
+
+## Ready-to-run example in this repository
+
+- `examples/reusable-rego-snippets/workflow.cwl`
+- `examples/reusable-rego-snippets/inputs-valid.yaml`
+- `examples/reusable-rego-snippets/inputs-invalid.yaml`

assertions_mate-0.4.0/docs/how-to/test-hints-with-pytest.md

@@ -0,0 +1,27 @@
+# How-to: Test Hints With pytest
+
+Use direct validator classes in unit tests for quick feedback.
+
+## 1. Create a validator test
+
+```python
+from assertions_mate import Cql2Query
+from assertions_mate.cql2_validator import Cql2Validator
+
+def test_rule_fails_when_count_not_positive():
+    validator = Cql2Validator(
+        queries=[Cql2Query(id="q", cql2="count > 0", message="count must be positive")]
+    )
+    result = validator.validate_inputs({"count": 0})
+    assert result is not None
+```
+
+## 2. Run the test
+
+```bash
+hatch run test:test-q examples/pytest-validation/test_validators_example.py
+```
+
+## Ready-to-run example in this repository
+
+- `examples/pytest-validation/test_validators_example.py`

assertions_mate-0.4.0/docs/how-to/troubleshoot-cwl-loader-errors.md

@@ -0,0 +1,19 @@
+# How-to: Troubleshoot CWL Loader Errors
+
+When validation fails before hints execute, the CWL document may be rejected by `cwl_utils`.
+
+## Common symptom
+
+- `schema_salad.exceptions.ValidationException`
+- messages around invalid `requirements` field shape
+
+## Checklist
+
+1. Start with a minimal single-workflow document (`class: Workflow`, `cwlVersion: v1.2`).
+2. Add one input at a time and re-run.
+3. If failures appear after adding `requirements`, temporarily remove that section to isolate parser compatibility.
+4. Keep examples runnable first; reintroduce advanced schema refs after parser behavior is confirmed.
+
+## Tip
+
+Different environments can parse the same CWL differently depending on exact `cwl_utils` and schema-salad versions.

assertions_mate-0.4.0/docs/how-to/troubleshoot-rego-invalid-literal.md

@@ -0,0 +1,32 @@
+# How-to: Troubleshoot Rego "Invalid literal" Errors
+
+If you see errors around `deny contains ... if { ... }`, your runtime is parsing classic Rego syntax.
+
+## Symptoms
+
+- `Invalid literal`
+- `wellformed_error`
+- validator setup fails for `RegoPolicyHint`
+
+## Fix
+
+Use classic syntax:
+
+```rego
+deny[msg] {
+  input["x"] == null
+  msg := "x is required"
+}
+```
+
+instead of:
+
+```rego
+deny contains "x is required" if {
+  input["x"] == null
+}
+```
+
+## Verify
+
+Run your workflow and ensure `Setting up validator for RegoPolicyHint...` completes without parser errors.

assertions_mate-0.4.0/docs/how-to/use-packed-vs-single-cwl.md

@@ -0,0 +1,28 @@
+# How-to: Use Packed CWL vs Single Workflow CWL
+
+## Single workflow
+
+Best for local examples and fast validation loops.
+
+```yaml
+cwlVersion: v1.2
+class: Workflow
+id: my-workflow
+...
+```
+
+## Packed workflow (`$graph`)
+
+Useful when distributing multiple process definitions in one file.
+
+```yaml
+cwlVersion: v1.2
+$graph:
+  - class: Workflow
+    id: my-workflow
+    ...
+```
+
+## Recommendation
+
+Start with single-workflow CWL for validator docs/examples, then move to packed CWL once parser compatibility is confirmed in your target runtime.

assertions_mate-0.4.0/docs/how-to/validate-array-cardinality-jsonschema.md

@@ -0,0 +1,48 @@
+# How-to: Validate Array Cardinality (JSON Schema)
+
+Require `items` array length between 1 and 3.
+
+## 1. Define the input
+
+```yaml
+inputs:
+  items:
+    type: string[]
+```
+
+## 2. Add JSON Schema hint
+
+```yaml
+hints:
+  - class: eoap:JSONSchemaHint
+    json_schema:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          minItems: 1
+          maxItems: 3
+          items:
+            type: string
+```
+
+## 3. Validate with sample values
+
+Valid:
+
+```yaml
+items: ["a", "b"]
+```
+
+Run:
+
+```bash
+assertions-mate workflow.cwl --inputs inputs-valid.yaml
+```
+
+## Ready-to-run example in this repository
+
+- `examples/array-cardinality-validation/workflow.cwl`
+- `examples/array-cardinality-validation/inputs-valid.yaml`
+- `examples/array-cardinality-validation/inputs-invalid.yaml`

assertions_mate-0.4.0/docs/how-to/validate-bbox-overlap-cql2.md

@@ -0,0 +1,53 @@
+# How-to: Validate BBOX Overlap (CQL2)
+
+## 1. Define the inputs
+
+```yaml
+inputs:
+  bbox_1:
+    type: string
+  bbox_2:
+    type: string
+```
+
+## 2. Add CQL2 check
+
+```yaml
+hints:
+  - class: eoap:Cql2FilterHint
+    custom_functions: |
+      from shapely import geometry
+      from typing import Any, List, Mapping, Union
+
+      def ensure_bbox(input: Union[Mapping[str, Any], List[float], str]):
+          value = []
+
+          if isinstance(input, dict):
+              value = input["bbox"]
+              if not value:
+                  raise ValueError(f"Input {input} doesn't have a 'bbox' property")
+          elif isinstance(input, str):
+              value = [float(x) for x in str(input).split(",")]
+          else:
+              value = input
+
+          return geometry.box(*value)
+    queries:
+      - id: bbox-overlap
+        cql2: "s_intersects(ensure_bbox(bbox_1), ensure_bbox(bbox_2))"
+        message: "bbox_1 must overlap bbox_2"
+```
+
+## 3. Validate with sample values
+
+Run:
+
+```bash
+assertions-mate workflow.cwl --inputs inputs-valid.yaml
+```
+
+## Ready-to-run example in this repository
+
+- `examples/bbox-overlap-validation/workflow.cwl`
+- `examples/bbox-overlap-validation/inputs-valid.yaml`
+- `examples/bbox-overlap-validation/inputs-invalid.yaml`