code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/corpus/manifest.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+import os
+from pathlib import Path
+import re
+import stat
+import tomllib
+from typing import TypeIs
+
+from sarj_standards.libs.filesystem import is_link_like
+
+
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_REVISION = re.compile(r"^[0-9a-f]{40}$")
+
+
+class CorpusKind(StrEnum):
+    LOCAL = "local"
+    GIT = "git"
+
+
+class CorpusVisibility(StrEnum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class CorpusSource:
+    name: str = field(repr=False)
+    root: Path = field(repr=False)
+    kind: CorpusKind
+    digest: str
+    include: tuple[str, ...]
+    exclude: tuple[str, ...] = ()
+    revision: str | None = None
+    visibility: CorpusVisibility = CorpusVisibility.PUBLIC
+
+    def __repr__(self) -> str:
+        if self.visibility is CorpusVisibility.PRIVATE:
+            return f"CorpusSource(name='<private-corpus>', kind={self.kind!r}, visibility={self.visibility!r})"
+        return (
+            f"CorpusSource(name={self.name!r}, root={self.root!r}, kind={self.kind!r}, "
+            f"digest={self.digest!r}, include={self.include!r}, exclude={self.exclude!r}, "
+            f"revision={self.revision!r}, visibility={self.visibility!r})"
+        )
+
+    def __post_init__(self) -> None:
+        if not self.name or not self.name.replace("-", "").isalnum() or self.name != self.name.lower():
+            msg = "corpus name must be non-empty lowercase kebab-case"
+            raise ValueError(msg)
+        if not _DIGEST.fullmatch(self.digest):
+            msg = f"corpus {self.report_name} requires a sha256 content digest"
+            raise ValueError(msg)
+        if not self.include or any(not pattern.strip() for pattern in (*self.include, *self.exclude)):
+            msg = f"corpus {self.report_name} requires non-empty include patterns"
+            raise ValueError(msg)
+        if self.kind is CorpusKind.GIT and (self.revision is None or not _REVISION.fullmatch(self.revision)):
+            msg = f"git corpus {self.report_name} requires a full lowercase 40-character revision"
+            raise ValueError(msg)
+        if self.kind is CorpusKind.LOCAL and self.revision is not None:
+            msg = f"local corpus {self.report_name} cannot declare a Git revision"
+            raise ValueError(msg)
+
+    @property
+    def report_name(self) -> str:
+        return self.name if self.visibility is CorpusVisibility.PUBLIC else "<private-corpus>"
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusManifest:
+    origin: Path = field(repr=False)
+    sources: tuple[CorpusSource, ...]
+    private: bool = False
+    schema: int = 1
+
+    def __post_init__(self) -> None:
+        if self.schema != 1:
+            msg = f"unsupported corpus manifest schema: {self.schema}"
+            raise ValueError(msg)
+        names = [source.name for source in self.sources]
+        if len(names) != len(set(names)):
+            msg = "corpus names must be unique"
+            raise ValueError(msg)
+
+
+def _is_object_list(value: object) -> TypeIs[list[object]]:
+    return isinstance(value, list)
+
+
+def load_manifest(path: Path) -> CorpusManifest:
+    return _load(path, expect_private=False)
+
+
+def load_private_overlay(path: Path) -> CorpusManifest:
+    if os.name == "nt":
+        msg = "private corpus overlays require POSIX owner-only permission semantics"
+        raise OSError(msg)
+    if is_link_like(path) or not path.is_file():
+        msg = "private corpus overlay must be a regular non-symlink file"
+        raise ValueError(msg)
+    mode = stat.S_IMODE(path.stat().st_mode)
+    if mode & 0o077:
+        msg = "private corpus overlay must be owner-readable only (chmod 600)"
+        raise PermissionError(msg)
+    return _load(path, expect_private=True)
+
+
+def _load(path: Path, *, expect_private: bool) -> CorpusManifest:
+    try:
+        parsed: object = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        label = "<private-corpus-overlay>" if expect_private else str(path)
+        msg = f"could not read corpus manifest {label}"
+        if not expect_private:
+            msg = f"{msg}: {exc}"
+        raise ValueError(msg) from (None if expect_private else exc)
+    root = _table(parsed, label="corpus manifest")
+    schema = root.get("schema", 1)
+    private = root.get("private", False)
+    if not isinstance(schema, int) or not isinstance(private, bool):
+        msg = "corpus manifest schema/private fields have invalid types"
+        raise TypeError(msg)
+    if private is not expect_private:
+        expected = "private overlay" if expect_private else "public manifest"
+        msg = f"expected a {expected}"
+        raise ValueError(msg)
+    raw_sources = root.get("corpus", [])
+    if not _is_object_list(raw_sources):
+        msg = "corpus must be an array of tables"
+        raise TypeError(msg)
+    visibility = CorpusVisibility.PRIVATE if private else CorpusVisibility.PUBLIC
+    sources = tuple(_source(_table(item, label="corpus entry"), path, visibility) for item in raw_sources)
+    return CorpusManifest(path.resolve(), sources, private, schema)
+
+
+def _table(value: object, *, label: str) -> dict[str, object]:
+    if not _is_object_dict(value):
+        msg = f"{label} must be a table"
+        raise TypeError(msg)
+    table: dict[str, object] = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            msg = f"{label} contains a non-string key"
+            raise TypeError(msg)
+        table[key] = item
+    return table
+
+
+def _is_object_dict(value: object) -> TypeIs[dict[object, object]]:
+    return isinstance(value, dict)
+
+
+def _source(values: dict[str, object], origin: Path, visibility: CorpusVisibility) -> CorpusSource:
+    required = {"name", "root", "kind", "digest", "include"}
+    missing = sorted(required - values.keys())
+    if missing:
+        msg = f"corpus entry is missing: {', '.join(missing)}"
+        raise ValueError(msg)
+    name, root, kind, digest = (values[key] for key in ("name", "root", "kind", "digest"))
+    revision = values.get("revision")
+    if (
+        not isinstance(name, str)
+        or not isinstance(root, str)
+        or not isinstance(kind, str)
+        or not isinstance(digest, str)
+    ):
+        msg = "corpus name/root/kind/digest must be strings"
+        raise TypeError(msg)
+    if revision is not None and not isinstance(revision, str):
+        msg = "corpus revision must be a string"
+        raise TypeError(msg)
+    resolved = Path(root)
+    if visibility is CorpusVisibility.PUBLIC and resolved.is_absolute():
+        msg = "public corpus roots must be relative to the manifest"
+        raise ValueError(msg)
+    if not resolved.is_absolute():
+        if visibility is CorpusVisibility.PUBLIC and ".." in resolved.parts:
+            msg = "public corpus roots must stay below the manifest directory"
+            raise ValueError(msg)
+        resolved = (origin.parent / resolved).resolve()
+    return CorpusSource(
+        name,
+        resolved,
+        CorpusKind(kind),
+        digest,
+        _strings(values["include"], label="corpus include"),
+        _strings(values.get("exclude", []), label="corpus exclude"),
+        revision,
+        visibility,
+    )
+
+
+def _strings(value: object, *, label: str) -> tuple[str, ...]:
+    if not _is_object_list(value) or not all(isinstance(item, str) for item in value):
+        msg = f"{label} must be an array of strings"
+        raise TypeError(msg)
+    return tuple(item for item in value if isinstance(item, str))
+
+
+def merge_manifests(public: CorpusManifest, private: CorpusManifest | None = None) -> CorpusManifest:
+    if public.private:
+        msg = "base corpus manifest must be public"
+        raise ValueError(msg)
+    if private is None:
+        return public
+    if not private.private:
+        msg = "corpus overlay must be private"
+        raise ValueError(msg)
+    return CorpusManifest(public.origin, (*public.sources, *private.sources))

sarj_standards/libs/corpus/snapshot.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+import hashlib
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- local, fixed-argument Git verification only.
+from typing import Final, NamedTuple
+
+from sarj_standards.libs.filesystem import is_link_like
+
+from .manifest import CorpusKind, CorpusSource
+
+
+_GIT_REVISION_OUTPUT_LINES = 2
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_REVISION = re.compile(r"^[0-9a-f]{40}$")
+_GIT_SAFE_ENV: Final = frozenset(
+    {"HOME", "LANG", "LC_ALL", "LC_CTYPE", "PATH", "SYSTEMDRIVE", "SYSTEMROOT", "TMPDIR", "XDG_CONFIG_HOME"}
+)
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class CorpusSnapshot:
+    name: str
+    digest: str
+    files: int
+    bytes: int
+    revision: str | None = None
+    private: bool = field(default=False, repr=False, compare=False)
+    verified: bool = field(default=False, init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not self.name or not _DIGEST.fullmatch(self.digest):
+            msg = "corpus snapshot requires a name and sha256 digest"
+            raise ValueError(msg)
+        if self.files <= 0 or self.bytes < 0:
+            msg = "corpus snapshot counts must contain files and non-negative bytes"
+            raise ValueError(msg)
+        if self.revision is not None and not _REVISION.fullmatch(self.revision):
+            msg = "corpus snapshot revision must be a full lowercase Git revision"
+            raise ValueError(msg)
+
+    def __repr__(self) -> str:
+        if self.private:
+            return f"CorpusSnapshot(name={self.name!r}, files={self.files!r}, bytes={self.bytes!r})"
+        return (
+            f"CorpusSnapshot(name={self.name!r}, digest={self.digest!r}, files={self.files!r}, "
+            f"bytes={self.bytes!r}, revision={self.revision!r})"
+        )
+
+
+class VerifiedInventory(NamedTuple):
+    snapshot: CorpusSnapshot
+    files: tuple[Path, ...]
+
+
+def snapshot(source: CorpusSource) -> CorpusSnapshot:
+    return snapshot_inventory(source, selected_files(source))
+
+
+def snapshot_inventory(source: CorpusSource, files: tuple[Path, ...]) -> CorpusSnapshot:
+    initial_revision = _git_revision(source) if source.kind is CorpusKind.GIT else None
+    digest = hashlib.sha256()
+    total = 0
+    if not files:
+        msg = f"corpus {source.report_name} selected no files"
+        raise ValueError(msg)
+    for path in files:
+        relative = path.relative_to(source.root).as_posix().encode()
+        before = path.stat()
+        size = before.st_size
+        digest.update(len(relative).to_bytes(8, "big"))
+        digest.update(relative)
+        digest.update(size.to_bytes(8, "big"))
+        read = 0
+        with path.open("rb") as stream:
+            while chunk := stream.read(1024 * 1024):
+                digest.update(chunk)
+                read += len(chunk)
+        after = path.stat()
+        if read != size or (after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns) != (
+            before.st_dev,
+            before.st_ino,
+            before.st_size,
+            before.st_mtime_ns,
+        ):
+            relative_name = "<private-file>" if source.visibility.value == "private" else path.relative_to(source.root)
+            msg = f"corpus file changed while hashing: {relative_name}"
+            raise ValueError(msg)
+        total += read
+    revision = _git_revision(source) if source.kind is CorpusKind.GIT else None
+    if revision != initial_revision:
+        msg = f"corpus {source.report_name} revision changed while hashing"
+        raise ValueError(msg)
+    return CorpusSnapshot(
+        source.report_name,
+        f"sha256:{digest.hexdigest()}",
+        len(files),
+        total,
+        revision,
+        private=source.visibility.value == "private",
+    )
+
+
+def selected_files(source: CorpusSource) -> tuple[Path, ...]:
+    if not source.root.is_dir():
+        root = "<private-corpus-root>" if source.visibility.value == "private" else source.root
+        msg = f"corpus root is not a directory: {root}"
+        raise ValueError(msg)
+    candidates = _git_tracked_files(source) if source.kind is CorpusKind.GIT else source.root.rglob("*")
+    files: list[Path] = []
+    for path in candidates:
+        if is_link_like(path) or not path.is_file():
+            continue
+        relative = path.relative_to(source.root).as_posix()
+        if _matches(relative, source.include) and not _matches(relative, source.exclude):
+            files.append(path)
+    return tuple(sorted(files, key=lambda path: path.relative_to(source.root).as_posix()))
+
+
+def _matches(path: str, patterns: tuple[str, ...]) -> bool:
+    return any(
+        fnmatch(path, pattern) or (pattern.startswith("**/") and fnmatch(path, pattern[3:])) for pattern in patterns
+    )
+
+
+def verify(source: CorpusSource) -> CorpusSnapshot:
+    verified, _files = verify_inventory(source)
+    return verified
+
+
+def verify_inventory(source: CorpusSource) -> VerifiedInventory:
+    files = selected_files(source)
+    actual = snapshot_inventory(source, files)
+    if actual.digest != source.digest:
+        if actual.private:
+            msg = f"corpus {source.report_name} digest drifted"
+        else:
+            msg = f"corpus {source.report_name} digest drifted: expected {source.digest}, found {actual.digest}"
+        raise ValueError(msg)
+    if source.kind is CorpusKind.GIT and actual.revision != source.revision:
+        if actual.private:
+            msg = f"corpus {source.report_name} revision drifted"
+        else:
+            msg = f"corpus {source.report_name} revision drifted: expected {source.revision}, found {actual.revision}"
+        raise ValueError(msg)
+    verified = CorpusSnapshot(
+        actual.name,
+        actual.digest,
+        actual.files,
+        actual.bytes,
+        actual.revision,
+        private=actual.private,
+    )
+    object.__setattr__(verified, "verified", True)  # ruff: ignore[unnecessary-dunder-call] -- frozen evidence token.
+    return VerifiedInventory(verified, files)
+
+
+def _git_revision(source: CorpusSource) -> str:
+    executable = shutil.which("git")
+    if executable is None:
+        msg = "git is required to verify a pinned corpus"
+        raise OSError(msg)
+    environment = _git_environment()
+    completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed local Git query.
+        (executable, "rev-parse", "--show-toplevel", "HEAD"),
+        cwd=source.root,
+        check=False,
+        capture_output=True,
+        env=environment,
+        shell=False,
+        text=True,
+    )
+    lines = completed.stdout.splitlines()
+    if completed.returncode or len(lines) != _GIT_REVISION_OUTPUT_LINES:
+        msg = f"could not read Git revision for corpus {source.report_name}"
+        raise ValueError(msg)
+    top_level, revision = lines
+    if Path(top_level).resolve() != source.root.resolve():
+        msg = f"Git repository root does not match corpus {source.report_name} root"
+        raise ValueError(msg)
+    return revision
+
+
+def _git_tracked_files(source: CorpusSource) -> tuple[Path, ...]:
+    executable = shutil.which("git")
+    if executable is None:
+        msg = "git is required to select tracked corpus files"
+        raise OSError(msg)
+    completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed local Git query.
+        (executable, "ls-files", "-z"),
+        cwd=source.root,
+        check=False,
+        capture_output=True,
+        env=_git_environment(),
+        shell=False,
+        text=True,
+    )
+    if completed.returncode:
+        msg = f"could not list tracked files for corpus {source.report_name}"
+        raise ValueError(msg)
+    return tuple(source.root / relative for relative in completed.stdout.split("\0") if relative)
+
+
+def _git_environment() -> dict[str, str]:
+    environment = {
+        name: value
+        for name, value in os.environ.items()  # ruff: ignore[banned-api] -- discard hook-local repository routing.
+        if name in _GIT_SAFE_ENV
+    }
+    environment.update(
+        {
+            "GIT_CONFIG_GLOBAL": os.devnull,
+            "GIT_CONFIG_NOSYSTEM": "1",
+            "GIT_CONFIG_SYSTEM": os.devnull,
+        }
+    )
+    return environment

sarj_standards/libs/diagnostics/__init__.py

@@ -0,0 +1,65 @@
+from .models import (
+    ANALYSIS_SCHEMA,
+    FINGERPRINT_VERSION,
+    SCHEMA_URI,
+    SCHEMA_VERSION,
+    AnalysisReport,
+    AnalyzerId,
+    CacheStatus,
+    Completion,
+    Conclusion,
+    CoverageDisposition,
+    CoverageNotice,
+    Diagnostic,
+    ExecutionIssue,
+    Fix,
+    FixSafety,
+    InvocationId,
+    Location,
+    Position,
+    Region,
+    RelatedLocation,
+    RuleDescriptor,
+    Severity,
+    TextEdit,
+    ToolReport,
+    TrustMode,
+    diagnostic_fingerprint,
+)
+from .serialize import to_github, to_json, to_sarif, to_text
+from .source import SourceDocument
+
+
+__all__ = [
+    "ANALYSIS_SCHEMA",
+    "FINGERPRINT_VERSION",
+    "SCHEMA_URI",
+    "SCHEMA_VERSION",
+    "AnalysisReport",
+    "AnalyzerId",
+    "CacheStatus",
+    "Completion",
+    "Conclusion",
+    "CoverageDisposition",
+    "CoverageNotice",
+    "Diagnostic",
+    "ExecutionIssue",
+    "Fix",
+    "FixSafety",
+    "InvocationId",
+    "Location",
+    "Position",
+    "Region",
+    "RelatedLocation",
+    "RuleDescriptor",
+    "Severity",
+    "SourceDocument",
+    "TextEdit",
+    "ToolReport",
+    "TrustMode",
+    "diagnostic_fingerprint",
+    "to_github",
+    "to_json",
+    "to_sarif",
+    "to_text",
+]

sarj_standards/libs/diagnostics/analysis.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://standards.sarj.ai/schemas/analysis/v1",
+  "title": "Sarj Standards analysis report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "root", "completion", "conclusion", "exitCode", "rules", "diagnostics", "issues", "tools", "coverage"],
+  "properties": {
+    "$schema": { "const": "https://standards.sarj.ai/schemas/analysis/v1" },
+    "schemaVersion": { "const": 1 },
+    "root": { "const": "." },
+    "completion": { "enum": ["complete", "partial", "failed"] },
+    "conclusion": { "enum": ["passed", "findings", "inconclusive"] },
+    "exitCode": { "enum": [0, 1, 2] },
+    "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" } },
+    "diagnostics": { "type": "array", "items": { "$ref": "#/$defs/diagnostic" } },
+    "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } },
+    "tools": { "type": "array", "items": { "$ref": "#/$defs/tool" } },
+    "coverage": { "type": "array", "items": { "$ref": "#/$defs/coverage" } }
+  },
+  "$defs": {
+    "position": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["line", "character"],
+      "properties": {
+        "line": { "type": "integer", "minimum": 0 },
+        "character": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "range": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start", "end"],
+      "properties": {
+        "start": { "$ref": "#/$defs/position" },
+        "end": { "$ref": "#/$defs/position" }
+      }
+    },
+    "location": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "position": { "$ref": "#/$defs/position" },
+        "range": { "$ref": "#/$defs/range" }
+      },
+      "not": { "required": ["position", "range"] }
+    },
+    "relatedLocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "location"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "location": { "$ref": "#/$defs/location" }
+      }
+    },
+    "edit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["location", "replacement"],
+      "properties": {
+        "location": { "$ref": "#/$defs/location" },
+        "replacement": { "type": "string" },
+        "expectedTextHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "fix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "safety", "edits"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "safety": { "enum": ["safe", "unsafe"] },
+        "edits": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/edit" } }
+      }
+    },
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "name", "summary"],
+      "properties": {
+        "key": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "helpUrl": { "type": "string", "pattern": "^https://" },
+        "tags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+      }
+    },
+    "fingerprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": { "const": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "ruleKey", "message", "severity", "source", "location"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "ruleId": { "type": "string", "minLength": 1 },
+        "ruleKey": { "type": "string", "minLength": 1 },
+        "message": { "type": "string" },
+        "severity": { "enum": ["error", "warning", "info"] },
+        "source": { "type": "string", "minLength": 1 },
+        "location": { "$ref": "#/$defs/location" },
+        "help": { "type": "string" },
+        "helpUrl": { "type": "string", "pattern": "^https://" },
+        "relatedLocations": { "type": "array", "items": { "$ref": "#/$defs/relatedLocation" } },
+        "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "fixes": { "type": "array", "items": { "$ref": "#/$defs/fix" } },
+        "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "fingerprint": { "$ref": "#/$defs/fingerprint" }
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "kind", "message"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "kind": { "type": "string", "minLength": 1 },
+        "message": { "type": "string" },
+        "exitCode": { "type": "integer" }
+      }
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "completion", "diagnosticCount", "issueCount", "analyzerId", "invocationId", "cache"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "completion": { "enum": ["complete", "partial", "failed"] },
+        "diagnosticCount": { "type": "integer", "minimum": 0 },
+        "issueCount": { "type": "integer", "minimum": 0 },
+        "analyzerId": { "type": "string", "minLength": 1 },
+        "invocationId": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "fileCount": { "type": "integer", "minimum": 0 },
+        "cache": { "enum": ["disabled", "hit", "miss"] }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "reason", "fileCount", "disposition"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "fileCount": { "type": "integer", "minimum": 1 },
+        "disposition": { "enum": ["failed", "unsupported", "excluded", "not-requested"] }
+      }
+    }
+  }
+}