ois-validator 0.1.0__py3-none-any.whl

ois_validator/__init__.py

@@ -0,0 +1,6 @@
+"""Reference validator for the Open Intent Schema (OIS)."""
+
+from ois_validator.report import Level, Report, Result
+from ois_validator.validator import validate
+
+__all__ = ["Level", "Report", "Result", "validate"]

ois_validator/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from ois_validator.cli import main
+
+sys.exit(main())

ois_validator/cli.py

@@ -0,0 +1,59 @@
+"""Command line interface: ois-validator FILE..."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ois_validator.report import Level, Report, Result
+from ois_validator.validator import validate
+
+EXIT_CONFORMS = 0
+EXIT_VIOLATION = 1
+EXIT_USAGE = 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ois-validator",
+        description="Validate OIS records, bundles and Quality Passports.",
+    )
+    parser.add_argument("files", nargs="+", metavar="FILE", help="JSON file, or - for stdin")
+    parser.add_argument("--format", choices=("text", "json"), default="text")
+    args = parser.parse_args(argv)
+
+    results: dict[str, Result] = {}
+    for name in args.files:
+        try:
+            text = sys.stdin.read() if name == "-" else Path(name).read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as error:
+            print(f"ois-validator: {name}: {error}", file=sys.stderr)
+            return EXIT_USAGE
+        results[name] = _validate_text(text)
+
+    if args.format == "json":
+        out = [
+            {"file": name, "conforms": r.conforms, "reports": [x.as_dict() for x in r.reports]}
+            for name, r in results.items()
+        ]
+        print(json.dumps(out, indent=2))
+    else:
+        for name, result in results.items():
+            if not result.reports:
+                print(f"{name}: conforms")
+            for report in result.reports:
+                print(f"{name}: {report.level} [{report.rule}] {report.path}: {report.message}")
+
+    return EXIT_CONFORMS if all(r.conforms for r in results.values()) else EXIT_VIOLATION
+
+
+def _validate_text(text: str) -> Result:
+    try:
+        document = json.loads(text)
+    except json.JSONDecodeError as error:
+        return Result([Report(Level.VIOLATION, "json", f"not valid JSON: {error}", "$")])
+    return validate(document)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ois_validator/digests.py

@@ -0,0 +1,28 @@
+"""Digests of criteria and intents (spec section 6.4), over their RFC 8785 canonical form."""
+
+import hashlib
+from typing import Any
+
+import rfc8785
+
+Digest = dict[str, str]  # in-toto DigestSet: algorithm -> lowercase hex
+
+CRITERION_FIELDS = ("key", "statement", "notation", "kind", "target", "language")
+
+
+def criterion_sha256(criterion: dict[str, Any]) -> str:
+    """Over the criterion's own key, statement, notation, kind, target and language."""
+    fields = {k: criterion[k] for k in CRITERION_FIELDS if k in criterion}
+    return hashlib.sha256(rfc8785.dumps(fields)).hexdigest()
+
+
+def intent_sha256(intent: dict[str, Any]) -> str:
+    """Over the intent without its top-level digest and status, criterion digests included."""
+    content = {k: v for k, v in intent.items() if k not in ("digest", "status")}
+    return hashlib.sha256(rfc8785.dumps(content)).hexdigest()
+
+
+def equal(a: Digest, b: Digest) -> bool:
+    """Two digest sets name the same content: they share an algorithm and agree on each."""
+    shared = a.keys() & b.keys()
+    return bool(shared) and all(a[name] == b[name] for name in shared)

ois_validator/document.py

@@ -0,0 +1,107 @@
+"""The records of a bundle or passport and how references between them resolve.
+
+Resolution follows the conformance fixtures (fixtures/README.md in the specification repository):
+`<id>@<version>` resolves to the intent or actor with that id and version, `<id>` to a record
+with that id and no version, and `<id>@<version>#<key>` to the intent version (the key is R2's
+concern). Only Ref-typed fields are references.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+from ois_validator.schema import STATEMENT_TYPE
+
+Record = dict[str, Any]
+
+REFERENCE_FIELDS = {
+    "intent": ("producedBy", "supersedes"),
+    "artifact": ("producedBy", "inputs", "context", "contextRecordedBy"),
+    "actor": (),
+    "evidence": ("criterion", "test", "subject", "inputs", "recordedBy"),
+    "decision": ("subject", "decidedBy", "evidence"),
+    "finding": ("criterion", "intent", "subject", "reportedBy", "resolvedBy", "supersedes"),
+}
+PASSPORT_REFERENCE_FIELDS = ("intents", "scope", "issuedBy")
+
+
+@dataclass(frozen=True)
+class Entry:
+    record: Record
+    path: str  # JSONPath of the record in the input document
+
+
+@dataclass(frozen=True)
+class Reference:
+    value: str
+    path: str  # JSONPath of the reference in the input document
+
+
+@dataclass
+class Document:
+    """The records of a single record, a bundle or a passport, after the schema check passed."""
+
+    entries: list[Entry]
+    container: bool = True  # False for a single record: no rules across records apply
+    passport: Record | None = None  # the predicate, for passports
+    subjects: list[dict[str, str]] = field(default_factory=list)  # statement subject digests
+    _by_id: dict[str, list[Entry]] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self) -> None:
+        for entry in self.entries:
+            self._by_id.setdefault(entry.record["id"], []).append(entry)
+
+    @classmethod
+    def of(cls, document: Record) -> "Document":
+        if document.get("_type") == STATEMENT_TYPE:
+            predicate: Record = document["predicate"]
+            # Appendix B covers only the predicate, so the statement's subject is read defensively.
+            subject = document.get("subject")
+            subjects = [
+                s["digest"]
+                for s in (subject if isinstance(subject, list) else [])
+                if isinstance(s, dict) and isinstance(s.get("digest"), dict)
+            ]
+            entries = _entries(predicate["records"], "$.predicate.records")
+            return cls(entries, passport=predicate, subjects=subjects)
+        if document["type"] == "bundle":
+            return cls(_entries(document["records"], "$.records"))
+        return cls([Entry(document, "$")], container=False)
+
+    def resolve(self, reference: str) -> list[Entry]:
+        """Every record a reference names; more than one only for records in several states."""
+        base, _, rest = reference.partition("@")
+        version = rest.partition("#")[0]
+        candidates = self._by_id.get(base, [])
+        if version:
+            return [e for e in candidates if str(e.record.get("version")) == version]
+        return [e for e in candidates if "version" not in e.record]
+
+    def record(self, reference: str) -> Record | None:
+        """The record a reference names, or None if it does not resolve."""
+        found = self.resolve(reference)
+        return found[0].record if found else None
+
+    def of_type(self, kind: str) -> Iterator[Entry]:
+        return (entry for entry in self.entries if entry.record["type"] == kind)
+
+    def references(self) -> Iterator[Reference]:
+        """Every reference in the document, in document order."""
+        for entry in self.entries:
+            yield from _references(entry.record, REFERENCE_FIELDS[entry.record["type"]], entry.path)
+        if self.passport is not None:
+            yield from _references(self.passport, PASSPORT_REFERENCE_FIELDS, "$.predicate")
+
+
+def _entries(records: list[Record], path: str) -> list[Entry]:
+    return [Entry(record, f"{path}[{index}]") for index, record in enumerate(records)]
+
+
+def _references(record: Record, fields: tuple[str, ...], path: str) -> Iterator[Reference]:
+    for name in fields:
+        value = record.get(name)
+        if isinstance(value, str):
+            yield Reference(value, f"{path}.{name}")
+        elif isinstance(value, list):
+            for index, item in enumerate(value):
+                yield Reference(item, f"{path}.{name}[{index}]")

ois_validator/junit.py

@@ -0,0 +1,273 @@
+"""Level 1 adapter: turn JUnit XML reports into an OIS bundle (spec section 11.4).
+
+The bundle holds what the quick start asks for: an actor for this adapter, an actor for the
+existing test suite, one characterization intent in draft with a criterion per test case, an
+artifact per test file and an evidence record per test result with derivedFrom unknown.
+
+JUnit XML comes from the producer's own pipeline. It is parsed with the standard library, whose
+Expat (2.4.1 and later) refuses entity expansion attacks and does not load external entities.
+"""
+
+import hashlib
+import re
+import subprocess
+import xml.etree.ElementTree as ElementTree
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from importlib.metadata import version as package_version
+from pathlib import Path, PurePosixPath
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+Record = dict[str, Any]
+
+RESULTS = ("pass", "skipped", "fail", "error")  # from best to worst
+
+
+@dataclass(frozen=True)
+class JUnitReport:
+    content: bytes
+    written_at: datetime | None = None  # file modification time, for timestamps without offset
+
+
+@dataclass(frozen=True)
+class Options:
+    namespace: str  # URI under the producer's domain, e.g. https://ois.acme.example
+    suite: str  # team or suite name; the test suite actor is named after it
+    repo: Path  # Git working tree that holds the test files
+    location: str | None = None  # defaults to git+<origin>@<HEAD>
+    run: str | None = None  # link to the pipeline run
+    now: datetime | None = None
+
+
+@dataclass(frozen=True)
+class TestCase:
+    classname: str
+    name: str
+    file: str | None
+    result: str
+    observed_at: datetime
+    report: str  # sha256 of the report the case comes from
+
+
+def to_bundle(reports: list[JUnitReport], options: Options) -> Record:
+    """Build the bundle; the caller validates it before passing it on."""
+    now = (options.now or datetime.now(UTC)).astimezone(UTC)
+    ns = options.namespace.rstrip("/")
+    commit = _git(options.repo, "rev-parse", "HEAD")
+    location = options.location or location_of(options.repo)
+    tracked = [path for path in _git(options.repo, "ls-files", "-z").split("\0") if path]
+    cases = _dedupe([case for report in reports for case in _cases(report, now)])
+
+    adapter = _record(
+        "actor",
+        f"{ns}/actors/ois-junit",
+        now,
+        kind="tool",
+        name="ois-junit (JUnit XML adapter)",
+        version=package_version("ois-validator"),
+    )
+    suite = _record(
+        "actor",
+        f"{ns}/actors/{_slug(options.suite)}-tests",
+        now,
+        kind="tool",
+        name=f"{options.suite} test suite",
+        version="unknown",
+    )
+    adapter_ref = f"{adapter['id']}@{adapter['version']}"
+    suite_ref = f"{suite['id']}@{suite['version']}"
+
+    intent = _record(
+        "intent",
+        f"{ns}/intents/{_slug(options.suite)}-characterization",
+        now,
+        version=1,
+        title=f"Characterization of the {options.suite} test suite",
+        status="draft",
+        producedBy=adapter_ref,
+        criteria=[
+            {"key": _key(c), "statement": _statement(c), "notation": "text", "kind": "functional"}
+            for c in cases
+        ],
+    )
+
+    artifacts: dict[str, Record] = {}
+    evidence = []
+    for case in cases:
+        path = _test_file(tracked, case)
+        artifact = _artifact(ns, options.repo, commit, location, path, case, suite_ref, now)
+        artifacts.setdefault(artifact["id"], artifact)
+        record = _record(
+            "evidence",
+            f"{ns}/evidence/{case.report[:12]}-{_key(case)}",
+            now,
+            criterion=f"{intent['id']}@1#{_key(case)}",
+            test=artifact["id"],
+            derivedFrom="unknown",
+            result=case.result,
+            observedAt=_timestamp(case.observed_at),
+            recordedBy=adapter_ref,
+        )
+        if options.run:
+            record["run"] = options.run
+        evidence.append(record)
+
+    combined = hashlib.sha256("".join(c.report for c in cases).encode()).hexdigest()
+    records = [adapter, suite, intent, *artifacts.values(), *evidence]
+    return _record("bundle", f"{ns}/bundles/junit-{combined[:16]}", now, records=records)
+
+
+def location_of(repo: Path) -> str:
+    """git+<origin URL>@<HEAD commit>, without credentials; scp-like remotes become ssh URIs."""
+    remote = _git(repo, "remote", "get-url", "origin")
+    commit = _git(repo, "rev-parse", "HEAD")
+    if "://" not in remote and (scp := re.fullmatch(r"(?:[^@/]+@)?([^:/]+):(.+)", remote)):
+        remote = f"ssh://{scp[1]}/{scp[2]}"
+    parts = urlsplit(remote)
+    if parts.scheme not in ("https", "http", "ssh", "git") or not parts.hostname:
+        raise ValueError(f"cannot turn remote {remote!r} into a location; pass --location")
+    host = parts.hostname + (f":{parts.port}" if parts.port else "")
+    return f"git+{urlunsplit((parts.scheme, host, parts.path, '', ''))}@{commit}"
+
+
+def _cases(report: JUnitReport, now: datetime) -> list[TestCase]:
+    root = ElementTree.fromstring(report.content)
+    digest = hashlib.sha256(report.content).hexdigest()
+    cases = []
+    for suite in root.iter("testsuite"):
+        observed_at = _observed_at(suite.get("timestamp"), report.written_at or now)
+        for case in suite.findall("testcase"):
+            cases.append(
+                TestCase(
+                    classname=case.get("classname", ""),
+                    name=case.get("name", ""),
+                    file=case.get("file"),
+                    result=_result(case),
+                    observed_at=observed_at,
+                    report=digest,
+                )
+            )
+    return cases
+
+
+def _result(case: ElementTree.Element) -> str:
+    if case.find("error") is not None:
+        return "error"
+    if case.find("failure") is not None:
+        return "fail"
+    if case.find("skipped") is not None:
+        return "skipped"
+    return "pass"
+
+
+def _dedupe(cases: list[TestCase]) -> list[TestCase]:
+    """One case per test; a test that ran more than once keeps its worst result."""
+    worst: dict[str, TestCase] = {}
+    for case in cases:
+        known = worst.get(_key(case))
+        if known is None or RESULTS.index(case.result) > RESULTS.index(known.result):
+            worst[_key(case)] = case
+    return list(worst.values())
+
+
+def _observed_at(timestamp: str | None, fallback: datetime) -> datetime:
+    """The suite's timestamp if it names an offset; JUnit often omits it, so otherwise the time
+    the report was written."""
+    if timestamp:
+        parsed = datetime.fromisoformat(timestamp)
+        if parsed.tzinfo is not None:
+            return parsed
+    return fallback
+
+
+def _test_file(tracked: list[str], case: TestCase) -> str | None:
+    """The tracked file a test case comes from: its file attribute, or the longest prefix of its
+    class name that names exactly one file (com.acme.InvoiceTest -> .../com/acme/InvoiceTest.java,
+    tests.test_invoice -> tests/test_invoice.py)."""
+    if case.file and case.file in tracked:
+        return case.file
+    parts = case.classname.split(".")
+    for end in range(len(parts), 0, -1):
+        stem = "/".join(parts[:end])
+        matches = [p for p in tracked if _stem(p) == stem or _stem(p).endswith(f"/{stem}")]
+        if len(matches) == 1:
+            return matches[0]
+    return None
+
+
+def _stem(path: str) -> str:
+    return str(PurePosixPath(path).with_suffix(""))
+
+
+def _artifact(
+    ns: str,
+    repo: Path,
+    commit: str,
+    location: str,
+    path: str | None,
+    case: TestCase,
+    producer: str,
+    now: datetime,
+) -> Record:
+    if path is None:
+        # No file found: the artifact is the repository at that commit (section 6.4 allows
+        # gitCommit alone for artifacts located in Git).
+        anchor = hashlib.sha256(case.classname.encode()).hexdigest()[:8]
+        return _record(
+            "artifact",
+            f"{ns}/artifacts/test-{commit[:12]}-{anchor}",
+            now,
+            kind="test",
+            location=location,
+            digest={"gitCommit": commit},
+            producedBy=producer,
+        )
+    content = subprocess.run(
+        ["git", "-C", str(repo), "show", f"{commit}:{path}"], check=True, capture_output=True
+    ).stdout
+    sha256 = hashlib.sha256(content).hexdigest()
+    # The id follows path and content, so a changed test file is a new artifact (R10).
+    anchor = hashlib.sha256(f"{path}\n{sha256}".encode()).hexdigest()[:16]
+    return _record(
+        "artifact",
+        f"{ns}/artifacts/test-{anchor}",
+        now,
+        kind="test",
+        location=location,
+        path=path,
+        digest={"sha256": sha256, "gitCommit": commit},
+        producedBy=producer,
+    )
+
+
+def _key(case: TestCase) -> str:
+    """Stable and valid for any test name: TC- and a hash of class and test name."""
+    return "TC-" + hashlib.sha256(f"{case.classname}::{case.name}".encode()).hexdigest()[:12]
+
+
+def _statement(case: TestCase) -> str:
+    return f"{case.classname}.{case.name}" if case.classname else case.name
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") or "suite"
+
+
+def _record(type_: str, id_: str, now: datetime, **fields: Any) -> Record:
+    return {"ois": "0.1", "type": type_, "id": id_, "createdAt": _timestamp(now), **fields}
+
+
+def _timestamp(moment: datetime) -> str:
+    return moment.astimezone(UTC).replace(microsecond=0).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _git(repo: Path, *args: str) -> str:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], check=True, capture_output=True, text=True
+        ).stdout.strip()
+    except subprocess.CalledProcessError as error:
+        raise ValueError(
+            f"git {' '.join(args)} failed in {repo}: {error.stderr.strip()}"
+        ) from error

ois_validator/junit_cli.py

@@ -0,0 +1,76 @@
+"""Command line interface: ois-junit REPORT... --namespace URI --suite NAME"""
+
+import argparse
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from xml.etree.ElementTree import ParseError
+
+from ois_validator.junit import JUnitReport, Options, to_bundle
+from ois_validator.validator import validate
+
+EXIT_OK = 0
+EXIT_INVALID = 1
+EXIT_USAGE = 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ois-junit",
+        description="Turn JUnit XML reports into an OIS bundle (Level 1, spec section 11.4).",
+    )
+    parser.add_argument("reports", nargs="+", metavar="REPORT", help="JUnit XML file, or -")
+    parser.add_argument(
+        "--namespace",
+        required=True,
+        help="URI under your domain for record ids, e.g. https://ois.acme.example",
+    )
+    parser.add_argument("--suite", required=True, help="team or suite that owns the tests")
+    parser.add_argument("--repo", type=Path, default=Path("."), help="Git working tree (default .)")
+    parser.add_argument("--location", help="artifact location (default git+<origin>@<HEAD>)")
+    parser.add_argument("--run", help="URI of the pipeline run")
+    parser.add_argument("--output", type=Path, help="write the bundle here instead of stdout")
+    args = parser.parse_args(argv)
+
+    try:
+        reports = [_read(name) for name in args.reports]
+        options = Options(
+            namespace=args.namespace,
+            suite=args.suite,
+            repo=args.repo,
+            location=args.location,
+            run=args.run,
+        )
+        bundle = to_bundle(reports, options)
+    except (OSError, ParseError, ValueError) as error:
+        print(f"ois-junit: {error}", file=sys.stderr)
+        return EXIT_USAGE
+
+    result = validate(bundle)
+    if not result.conforms:
+        for report in result.reports:
+            print(
+                f"ois-junit: {report.level} [{report.rule}] {report.path}: {report.message}",
+                file=sys.stderr,
+            )
+        return EXIT_INVALID
+
+    text = json.dumps(bundle, indent=2, ensure_ascii=False) + "\n"
+    if args.output:
+        args.output.write_text(text, encoding="utf-8")
+    else:
+        sys.stdout.write(text)
+    return EXIT_OK
+
+
+def _read(name: str) -> JUnitReport:
+    if name == "-":
+        return JUnitReport(sys.stdin.buffer.read())
+    path = Path(name)
+    written_at = datetime.fromtimestamp(path.stat().st_mtime, UTC)
+    return JUnitReport(path.read_bytes(), written_at)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ois_validator/report.py

@@ -0,0 +1,30 @@
+"""Validation reports with the three levels of spec section 11.1."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Level(StrEnum):
+    VIOLATION = "violation"  # a MUST is broken; the input does not conform
+    WARNING = "warning"  # a rule asks for a report; the input still conforms
+    INFO = "info"  # a SHOULD is not followed
+
+
+@dataclass(frozen=True)
+class Report:
+    level: Level
+    rule: str  # "schema" for Appendix B, otherwise R1 to R15
+    message: str
+    path: str  # JSONPath into the input document
+
+    def as_dict(self) -> dict[str, str]:
+        return {"level": self.level, "rule": self.rule, "message": self.message, "path": self.path}
+
+
+@dataclass
+class Result:
+    reports: list[Report] = field(default_factory=list)
+
+    @property
+    def conforms(self) -> bool:
+        return not any(r.level is Level.VIOLATION for r in self.reports)