Metadata-Version: 2.4
Name: assertions-mate
Version: 0.2.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
Author-email: Terradue srl <info@terradue.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: cwl-utils
Requires-Dist: cwl2ogc>=0.10.0
Requires-Dist: jsonschema
Requires-Dist: loguru
Requires-Dist: pydantic
Requires-Dist: pygeofilter
Requires-Dist: pygeofilter[backend-native]
Requires-Dist: pystac-client
Requires-Dist: regopy==0.4.6
Requires-Dist: shapely
Description-Content-Type: text/markdown

# Assertions Mate

`assertions-mate` validates CWL workflow inputs against assertion hints embedded in the workflow definition.

It adds policy and rule checks on top of CWL typing by supporting:
- JSON Schema validation
- Rego policy validation (OPA)
- CQL2 expression validation

Documentation site: https://terradue.github.io/assertions-mate/

## 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.

## Installation

### From source (recommended for development)

```bash
git clone https://github.com/Terradue/assertions-mate.git
cd assertions-mate
pip install -e .
```

### Runtime requirements

- Python `>= 3.10`
- Dependencies are managed in `pyproject.toml`

## Command Line Usage

After installation, run:

```bash
assertions-mate path/to/workflow.cwl --inputs path/to/inputs.yaml
```

What happens:
1. The CWL document is loaded.
2. Assertion hints are discovered from `workflow.hints`.
3. Matching validators are built and executed against the input mapping.
4. Validation issues are reported with pointer and detail messages.

## Supported Assertion Hints

The tool maps `eoap:` hint classes to internal validators:

- `eoap:JSONSchemaHint`
- `eoap:RegoPolicyHint`
- `eoap:Cql2FilterHint`

### Example `hints` snippet

```yaml
hints:
  - class: eoap:JSONSchemaHint
    json_schema:
      type: object
      required: [count]
      properties:
        count:
          type: integer
          minimum: 1

  - class: eoap:RegoPolicyHint
    module: |
      package workflow
      deny contains "count must be <= 10" if {
        input.count > 10
      }
    queries:
      - data.workflow.deny[_]

  - class: eoap:Cql2FilterHint
    queries:
      - id: cql-rule-1
        cql2: "count > 0"
        message: "count must be greater than zero"
```

## Development

This project uses Hatch environments and pytest.

```bash
# Run tests
hatch run test:test-q

# Run formatting check
hatch run dev:lint

# Run lint checks with fixes
hatch run dev:check
```

If you use Taskfile:

```bash
task test
task lint
task check
```

## Project Layout

- `src/assertions_mate/` core package and CLI
- `tests/` unit tests
- `schemas/` CWL hint schema definitions
- `docs/` notebooks and documentation sources

## License

Apache License 2.0. See `LICENSE`.
