feat(validation): add ValidationOutcome type and runner

- Add `app/validation/results.py` (`ValidationOutcome` with valid/invalid/error status, detail/error, serialisation) and `runner.py` wrapping rocrate_validator so both entry points always return an outcome;
- Replaces the ValidationResult|str / isinstance pattern.
Closes #176

Author: alexhambley

app/validation/__init__.py

@@ -0,0 +1 @@
+"""RO-Crate validation: a single outcome type and the runner that produces it."""

app/validation/results.py

@@ -0,0 +1,80 @@
+"""Defines an explicit result type for validation."""
+
+import json
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class ValidationStatus(str, Enum):
+    """The outcome of a validation run."""
+
+    VALID = "valid"
+    INVALID = "invalid"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class ValidationOutcome:
+    """The result of validating a crate or its metadata.
+
+    ``detail`` holds the validator's report for ``valid``/``invalid`` outcomes;
+    ``error`` holds the message for an ``error`` outcome. The two are mutually
+    exclusive.
+    """
+
+    status: ValidationStatus
+    profile: Optional[str] = None
+    detail: Optional[dict] = None
+    error: Optional[str] = None
+    created_at: Optional[str] = None
+
+    @property
+    def is_valid(self) -> bool:
+        return self.status is ValidationStatus.VALID
+
+    def to_dict(self) -> dict:
+        data = {
+            "status": self.status.value,
+            "profile": self.profile,
+            "created_at": self.created_at,
+        }
+        if self.detail is not None:
+            data["detail"] = self.detail
+        if self.error is not None:
+            data["error"] = self.error
+        return data
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_validator_result(
+        cls, result, profile: Optional[str] = None, created_at: Optional[str] = None
+    ) -> "ValidationOutcome":
+        """Build an outcome from a rocrate_validator ``ValidationResult``."""
+        status = (
+            ValidationStatus.INVALID if result.has_issues() else ValidationStatus.VALID
+        )
+        return cls(
+            status=status,
+            profile=profile,
+            detail=json.loads(result.to_json()),
+            created_at=created_at,
+        )
+
+    @classmethod
+    def from_error(
+        cls,
+        message: str,
+        profile: Optional[str] = None,
+        created_at: Optional[str] = None,
+    ) -> "ValidationOutcome":
+        """Build an error outcome from a failure message."""
+        return cls(
+            status=ValidationStatus.ERROR,
+            profile=profile,
+            error=message,
+            created_at=created_at,
+        )

app/validation/runner.py

@@ -0,0 +1,81 @@
+"""Runs rocrate_validator and adapts its output to a ValidationOutcome.
+
+This is the boundary to the external validator. Both entry points always
+return a :class:`ValidationOutcome` - a validator exception becomes an ``error``
+outcome rather than a string, so callers never have to type-check the result.
+"""
+
+import logging
+
+from typing import Optional
+
+from rocrate_validator import services
+
+from app.validation.results import ValidationOutcome
+
+logger = logging.getLogger(__name__)
+
+
+def validate_crate_path(
+    rocrate_uri: str,
+    profile_name: Optional[str] = None,
+    profiles_path: Optional[str] = None,
+    skip_checks: Optional[list] = None,
+    created_at: Optional[str] = None,
+) -> ValidationOutcome:
+    """Validate a crate on disk (a directory or zip) at ``rocrate_uri``."""
+    return _run(
+        {"rocrate_uri": rocrate_uri},
+        profile_name=profile_name,
+        profiles_path=profiles_path,
+        skip_checks=skip_checks,
+        created_at=created_at,
+    )
+
+
+def validate_metadata(
+    metadata: dict,
+    profile_name: Optional[str] = None,
+    profiles_path: Optional[str] = None,
+    skip_checks: Optional[list] = None,
+    created_at: Optional[str] = None,
+) -> ValidationOutcome:
+    """Validate an in-memory RO-Crate metadata graph."""
+    return _run(
+        {"metadata_only": True, "metadata_dict": metadata},
+        profile_name=profile_name,
+        profiles_path=profiles_path,
+        skip_checks=skip_checks,
+        created_at=created_at,
+    )
+
+
+def _run(
+    base_settings: dict,
+    profile_name: Optional[str],
+    profiles_path: Optional[str],
+    skip_checks: Optional[list],
+    created_at: Optional[str],
+) -> ValidationOutcome:
+    options = dict(base_settings)
+    if profile_name:
+        options["profile_identifier"] = profile_name
+    if profiles_path:
+        options["profiles_path"] = profiles_path
+    if skip_checks:
+        options["skip_checks"] = skip_checks
+
+    try:
+        settings = services.ValidationSettings(**options)
+        result = services.validate(settings)
+    except (
+        Exception
+    ) as error:  # noqa: BLE001 - adapt any validator failure to an outcome
+        logger.error("Validation failed: %s", error)
+        return ValidationOutcome.from_error(
+            str(error), profile=profile_name, created_at=created_at
+        )
+
+    return ValidationOutcome.from_validator_result(
+        result, profile=profile_name, created_at=created_at
+    )

tests/test_validation_outcome.py

@@ -0,0 +1,66 @@
+"""Tests for the ValidationOutcome result type."""
+
+import json
+
+from app.validation.results import ValidationOutcome, ValidationStatus
+
+
+class FakeResult:
+    """Stand-in for a rocrate_validator ValidationResult."""
+
+    def __init__(self, has_issues: bool, report: dict):
+        self._has_issues = has_issues
+        self._report = report
+
+    def has_issues(self) -> bool:
+        return self._has_issues
+
+    def to_json(self) -> str:
+        return json.dumps(self._report)
+
+
+def test_from_validator_result_without_issues_is_valid():
+    outcome = ValidationOutcome.from_validator_result(
+        FakeResult(False, {"report": "ok"}), profile="ro-crate"
+    )
+    assert outcome.status is ValidationStatus.VALID
+    assert outcome.is_valid is True
+    assert outcome.profile == "ro-crate"
+    assert outcome.detail == {"report": "ok"}
+    assert outcome.error is None
+
+
+def test_from_validator_result_with_issues_is_invalid():
+    outcome = ValidationOutcome.from_validator_result(FakeResult(True, {"issues": [1]}))
+    assert outcome.status is ValidationStatus.INVALID
+    assert outcome.is_valid is False
+    assert outcome.detail == {"issues": [1]}
+
+
+def test_from_error_records_message_and_has_no_detail():
+    outcome = ValidationOutcome.from_error("boom", profile="ro-crate")
+    assert outcome.status is ValidationStatus.ERROR
+    assert outcome.is_valid is False
+    assert outcome.error == "boom"
+    assert outcome.detail is None
+
+
+def test_to_dict_serialises_status_as_string_and_omits_absent_fields():
+    outcome = ValidationOutcome.from_validator_result(FakeResult(False, {"r": 1}))
+    data = outcome.to_dict()
+    assert data["status"] == "valid"
+    assert data["detail"] == {"r": 1}
+    assert "error" not in data
+
+
+def test_to_json_round_trips():
+    outcome = ValidationOutcome.from_error("nope")
+    parsed = json.loads(outcome.to_json())
+    assert parsed["status"] == "error"
+    assert parsed["error"] == "nope"
+
+
+def test_created_at_is_propagated_when_provided():
+    outcome = ValidationOutcome.from_error("x", created_at="2026-06-16T00:00:00Z")
+    assert outcome.created_at == "2026-06-16T00:00:00Z"
+    assert outcome.to_dict()["created_at"] == "2026-06-16T00:00:00Z"

tests/test_validation_runner.py

@@ -0,0 +1,80 @@
+"""Tests for the validation runner that wraps rocrate_validator."""
+
+import json
+
+import pytest
+
+from app.validation import runner
+from app.validation.results import ValidationStatus
+
+
+class FakeResult:
+    def __init__(self, has_issues: bool):
+        self._has_issues = has_issues
+
+    def has_issues(self) -> bool:
+        return self._has_issues
+
+    def to_json(self) -> str:
+        return json.dumps({"issues": self._has_issues})
+
+
+class FakeServices:
+    """A stand-in for rocrate_validator.services."""
+
+    def __init__(self, result=None, raises=None):
+        self._result = result
+        self._raises = raises
+        self.last_settings = None
+
+    def ValidationSettings(self, **kwargs):  # noqa: N802 - mirrors the real API
+        self.last_settings = kwargs
+        return kwargs
+
+    def validate(self, settings):
+        if self._raises is not None:
+            raise self._raises
+        return self._result
+
+
+def test_validate_metadata_success_is_valid(monkeypatch):
+    fake = FakeServices(result=FakeResult(has_issues=False))
+    monkeypatch.setattr(runner, "services", fake)
+
+    outcome = runner.validate_metadata({"@graph": []}, profile_name="ro-crate")
+
+    assert outcome.status is ValidationStatus.VALID
+    assert outcome.profile == "ro-crate"
+    assert fake.last_settings["metadata_only"] is True
+    assert fake.last_settings["metadata_dict"] == {"@graph": []}
+
+
+def test_validate_metadata_with_issues_is_invalid(monkeypatch):
+    monkeypatch.setattr(runner, "services", FakeServices(result=FakeResult(True)))
+    outcome = runner.validate_metadata({"@graph": []})
+    assert outcome.status is ValidationStatus.INVALID
+
+
+def test_validate_metadata_exception_becomes_error_outcome(monkeypatch):
+    monkeypatch.setattr(runner, "services", FakeServices(raises=RuntimeError("kaboom")))
+    outcome = runner.validate_metadata({"@graph": []}, profile_name="ro-crate")
+    assert outcome.status is ValidationStatus.ERROR
+    assert "kaboom" in outcome.error
+    assert outcome.profile == "ro-crate"
+
+
+def test_validate_crate_path_success(monkeypatch):
+    fake = FakeServices(result=FakeResult(has_issues=False))
+    monkeypatch.setattr(runner, "services", fake)
+
+    outcome = runner.validate_crate_path("/tmp/crate", profile_name="ro-crate")
+
+    assert outcome.status is ValidationStatus.VALID
+    assert fake.last_settings["rocrate_uri"] == "/tmp/crate"
+
+
+def test_validate_crate_path_exception_becomes_error_outcome(monkeypatch):
+    monkeypatch.setattr(runner, "services", FakeServices(raises=ValueError("bad crate")))
+    outcome = runner.validate_crate_path("/tmp/crate")
+    assert outcome.status is ValidationStatus.ERROR
+    assert "bad crate" in outcome.error