Metadata-Version: 2.4
Name: compipar-validator
Version: 0.1.1
Summary: Validate Compi parameter files against parameters.metadata.json
Author: Danny Zimmer
License-Expression: MIT
Keywords: compi,pipeline,validation,parameters
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# compipar-validator

Small, dependency-free validator for Compi test parameter files.

It reads `compi.parameters` and the optional
`parameters.metadata.json` file used by Compi pipelines, evaluates
cross-parameter validation rules, and reports warnings or strict errors.

The package has no GUI dependencies and can be used from Python or from the
`compipar-validate` command line.

## Installation

```bash
pip install .
```

For development:

```bash
pip install -e ".[dev]"
```

## Supported rules

The top-level `validations` array in `parameters.metadata.json` accepts:

```json
{
  "schema_version": 1,
  "parameters": {},
  "validations": [
    {
      "id": "one-of-input",
      "type": "exactly_one",
      "parameters": ["targetFasta", "targetDir"],
      "strict": true
    },
    {
      "id": "optional-mutual-exclusion",
      "type": "at_most_one",
      "parameters": ["modeA", "modeB"]
    },
    {
      "id": "custom-db",
      "type": "requires",
      "when": "useCustomDb",
      "require": ["dbPath", "dbVersion"],
      "message": "When useCustomDb is active, dbPath and dbVersion are required."
    }
  ]
}
```

Rule types:

- `exactly_one`: exactly one parameter in the group must be active.
- `at_most_one`: zero or one parameter in the group may be active.
- `requires`: when `when` is active, every parameter in `require` must be
  active.

A parameter is active when:

- it is a flag and it is present;
- or its value is non-empty and is not one of
  `FALSE`, `0`, `0.0`, `NO`, `OFF`, `NONE`, `NULL`.

Las reglas no estrictas producen advertencias. Las reglas estrictas hacen que el resultado sea inválido.

## Python API

```python
from pathlib import Path

from compipar_validator import validate_files

result = validate_files(
    Path("parameters.metadata.json"),
    Path("compi.parameters"),
)

if result.valid:
    print("Parameters are valid")
else:
    for violation in result.strict_violations:
        print(f"ERROR [{violation.constraint_id}]: {violation.message}")
```

Lower-level API:

```python
from compipar_validator import (
    evaluate_constraints,
    load_metadata,
    parse_parameters,
    validate_values,
)

document = load_metadata("parameters.metadata.json")
values = parse_parameters("compi.parameters")
result = validate_values(values, document)
```

`load_metadata` also exposes metadata problems through
`document.metadata_issues`. Invalid validation rules are reported and ignored;
the rest of the rules are still evaluated.

## CLI

```bash
compipar-validate \
  --metadata parameters.metadata.json \
  --params compi.parameters
```

Options:

```text
--metadata PATH   parameters.metadata.json
--params PATH     compi.parameters
--json            Machine-readable output on stdout
--quiet           Suppress non-strict warnings
--version         Show the package version
```

Exit codes:

| Code | Meaning |
|---:|---|
| 0 | Valid, or only non-strict warnings |
| 1 | At least one strict violation |
| 2 | Invalid inputs or arguments |
| 3 | Internal error |

Example JSON output:

```json
{
  "valid": false,
  "violations": [
    {
      "id": "one-of-input",
      "message": "Debes declarar exactamente uno de: targetFasta, targetDir.",
      "strict": true
    }
  ],
  "metadata_issues": []
}
```

## Development

```bash
ruff check src tests
mypy src
pytest
python -m build
```

## License

MIT
