claims-cli 0.6.0__py3-none-any.whl

claims/core/__init__.py

@@ -0,0 +1,9 @@
+"""The evidence contract, one module per concept.
+
+Split out of a single 1,000-line `models.py` that held five unrelated groups: the artifacts a
+manifest declares, the evidence a claim offers, the verdict vocabulary, the manifest itself,
+and what a run reports. Each is now its own module.
+
+Nothing is re-exported here. `claims.models` is the public path and names every type; importing
+`claims.core.outcomes` directly is for code inside this package that wants one group.
+"""

claims/core/artifacts.py

@@ -0,0 +1,121 @@
+"""Content addresses, and the files a manifest declares."""
+
+from __future__ import annotations
+
+import hashlib
+import pathlib
+import re
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_serializer
+
+SCHEMA_VERSION = "repro/1"
+
+_SHA256_HEX = r"^[a-f0-9]{64}$"
+
+_COMMIT_HEX = re.compile(r"[a-f0-9]{40}")
+
+
+# --------------------------------------------------------------------------------- artifacts
+
+
+class Digest(BaseModel):
+    """A content address."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    algorithm: Literal["sha256"] = "sha256"
+    value: Annotated[str, Field(pattern=_SHA256_HEX)]
+    """Lowercase hex. The pattern is enforced because a truncated or uppercase digest compares
+    unequal to a correct one and reads, in a report, as a tampered file."""
+
+    def __str__(self) -> str:
+        return f"{self.algorithm}:{self.value}"
+
+    @classmethod
+    def of_file(cls, path: pathlib.Path) -> Digest:
+        h = hashlib.sha256()
+        with path.open("rb") as fh:
+            for block in iter(lambda: fh.read(1 << 20), b""):
+                h.update(block)
+        return cls(value=h.hexdigest())
+
+    @classmethod
+    def of_text(cls, text: str) -> Digest:
+        return cls(value=hashlib.sha256(text.encode("utf-8")).hexdigest())
+
+
+class Origin(BaseModel):
+    """The place an artifact's bytes were copied from: one file, at one commit, of one
+    repository.
+
+    An origin names immutable bytes or it names nothing. A branch moves and a short id can
+    come to name two commits, so `commit` is the full 40-character id and nothing else. The
+    origin is a statement about where the bytes came from; `claims origins` is what checks it,
+    and `claims verify` never reads it.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    repository: str = Field(min_length=1)
+    """A URL (https or ssh) or a local path. A relative path is read from the manifest's
+    directory."""
+
+    commit: str
+    """The full commit id, 40 lowercase hex characters."""
+
+    path: str
+    """POSIX, relative to the root of that repository."""
+
+    @field_validator("commit")
+    @classmethod
+    def _names_a_commit(cls, value: str) -> str:
+        if not _COMMIT_HEX.fullmatch(value):
+            raise ValueError(
+                f"{value!r} is not a full commit id: an origin names one commit by its 40 "
+                "lowercase hex characters, and a branch, a tag or a short id can come to name "
+                "other bytes"
+            )
+        return value
+
+    @field_validator("path")
+    @classmethod
+    def _inside_the_repository(cls, value: str) -> str:
+        parts = pathlib.PurePosixPath(value).parts
+        if not value or "\\" in value or value.startswith("/") or ".." in parts:
+            raise ValueError(
+                f"{value!r} is not a path inside a repository: it is written with `/`, "
+                "relative to the repository's root, and has no `..`"
+            )
+        return value
+
+
+class ArtifactRef(BaseModel):
+    """A file a manifest names, whether or not it has been pinned.
+
+    Separate from `PinnedArtifact` because "identified by content" and "may carry no digest"
+    cannot both be true of one type. An unpinned reference is a legitimate thing to write down
+    and an illegitimate thing to verify against, and the type says which it is.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    path: pathlib.Path
+    digest: Digest | None = None
+    media_type: str = "application/octet-stream"
+    origin: Origin | None = None
+    """Where the bytes were copied from, where the manifest says."""
+
+    @model_serializer(mode="wrap")
+    def _omit_no_origin(self, handler):
+        """Leave the field out where there is none, so a manifest that declares no origin
+        dumps, and so digests, as it did before the field existed."""
+        dumped = handler(self)
+        if self.origin is None:
+            dumped.pop("origin", None)
+        return dumped
+
+    @property
+    def is_pinned(self) -> bool:
+        return self.digest is not None

claims/core/checks.py

@@ -0,0 +1,132 @@
+"""What an assertion said each time it was checked."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from claims.core.outcomes import Outcome, Reason
+
+SCHEMA_VERSION = "repro/1"
+
+
+class CheckedAssertion(BaseModel):
+    """One assertion as `repro verify` found it: what it declared, the bytes it was checked
+    against, and the outcome.
+
+    An assertion is the same assertion across edits where `claim_id`, `kind`, `name` and
+    `position` are the same. A claim given another id, an assertion given another name, and
+    two assertions of one kind and name that trade places each start a new history.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: str
+    kind: str
+    name: str = ""
+    position: int = 0
+    """Which of the claim's assertions of this kind and name it is, from 0. A `quote` has no
+    name, so two quotations in one claim are told apart by this alone."""
+
+    claim_digest: str
+    """`Claim.digest`: the claim's id, text and `where` as they were."""
+    printed: str | None = None
+    """The `reported` value, or the passage a quotation asserts."""
+    address: str = ""
+    """Where the assertion looked. Both sides of a `correspondence`, each with its name."""
+    conversion: str = ""
+    """The conversion declared between the stored value and the printed one, where there is
+    one. Each side's, with its name, for a `correspondence`."""
+    digests: dict[str, str | None] = {}
+    """Per artifact the assertion read, the digest of the bytes read. None where nothing was
+    at the declared path."""
+    outcome: Outcome
+    reason: Reason
+
+    checked_at: str = ""
+    """When the check that first found the assertion like this appended it. Read from the
+    entry that holds it and not stored on the assertion."""
+    verifiable: bool = True
+    """False where the record this was read from does not verify at or before the entry
+    holding it. The entry is shown as it reads; the chain no longer vouches for it."""
+
+    @property
+    def identity(self) -> tuple[str, str, str, int]:
+        return self.claim_id, self.kind, self.name, self.position
+
+    def same_as(self, other: CheckedAssertion) -> bool:
+        """Whether two checks found the assertion saying the same thing with the same outcome,
+        whenever they ran."""
+        unset = {"checked_at": "", "verifiable": True}
+        return self.model_copy(update=unset) == other.model_copy(update=unset)
+
+
+class RecordSetAside(BaseModel):
+    """A record of checks that was moved aside, as the entry that follows it says.
+
+    Written by `repro verify --set-aside-record` and by nothing else, as the first entry of
+    the chain that replaces a local record, so the break stays on the record.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["local", "tracked"]
+    kept_as: str
+    """The name the record now has, beside where it was. Its head file is kept the same way."""
+    entries: int
+    """How many entries it held."""
+    head: str
+    """The SHA-256 of its last entry the chain still vouched for, as stored. The digest that
+    addresses nothing where it vouched for none."""
+    status: str
+    """What its chain was reported as: the `results` ledger's word."""
+    problems: tuple[str, ...] = ()
+    """Each fault found in it, as `repro why` listed them."""
+    at: str = ""
+    """When it was set aside. Read from the entry that says so and not stored in it."""
+
+
+class CheckRecord(BaseModel):
+    """One entry of a record of checks: the assertions one `repro verify` found different from
+    the last time each was recorded.
+
+    The last three fields are the chain's, under the names the `results` ledger gives them:
+    the entry's position from 0, when it was appended, and the SHA-256 of the entry before it
+    as stored, or of nothing for the first.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: str = SCHEMA_VERSION
+    assertions: tuple[CheckedAssertion, ...]
+    set_aside: RecordSetAside | None = None
+    """On an entry `repro verify --set-aside-record` wrote, and on no other, where the key is
+    absent: the record that was moved aside before this entry."""
+    seq: int
+    timestamp: str
+    prev_hash: str
+
+
+class RecordState(BaseModel):
+    """One record of checks as `repro why` found it: where it is and whether its chain holds."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["local", "tracked"]
+    """`local` is the one in the repository's git directory, written by every `repro verify`
+    and never committed. `tracked` is `.repro/checks.jsonl` in the working tree, written
+    where `repro verify --record` asks."""
+    path: str
+    entries: int
+    status: str
+    """The `results` ledger's word for a chain: `intact`, `edited`, `reordered`, `corrupt`,
+    `truncated`, `extended` or `no_anchor`."""
+    problems: tuple[str, ...] = ()
+    """Each fault found, naming its entry by its line in the file, from 1."""
+    unverifiable_from: int | None = None
+    """The first entry the chain does not vouch for. None where every entry present follows
+    from the one before it."""
+    diverges_at: int | None = None
+    """Of the tracked record: the first entry that is not the local record's entry at that
+    position. None where one record is the other's beginning."""

claims/core/claims.py

@@ -0,0 +1,100 @@
+"""A statement a manuscript makes, and whether it was registered before the run."""
+
+from __future__ import annotations
+
+import enum
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from claims.core.artifacts import Digest
+from claims.core.evidence import Evidence
+
+SCHEMA_VERSION = "repro/1"
+
+_SHA256_HEX = r"^[a-f0-9]{64}$"
+
+
+# ------------------------------------------------------------------------------------ claims
+
+
+class Availability(enum.StrEnum):
+    """Whether a claim offers anything to check. A property of the claim, not of a check."""
+
+    OFFERED = "offered"
+    NOT_OFFERED = "not_offered"
+
+
+class Registration(enum.StrEnum):
+    """Whether a plan could have fixed this claim's outcome in advance.
+
+    Three states, because two conflate different things. A descriptive measurement that was
+    never registered and an exhaustive count that nothing could have registered look identical
+    under a boolean and are not the same claim.
+    """
+
+    CONFIRMATORY = "confirmatory"
+    """Reports a preregistered outcome. The ordering check applies."""
+    EXPLORATORY = "exploratory"
+    """An outcome that a plan could have fixed and did not. The default: a claim that says
+    nothing about registration is exploratory, never inapplicable."""
+    NOT_APPLICABLE = "not_applicable"
+    """No outcome was selected, so registration has nothing to bind -- an exhaustive
+    deterministic measurement reports whatever it finds. Must carry a reason: this state is
+    asserted, never assumed, or it is a way for any claim to opt out of being graded."""
+
+
+class Claim(BaseModel):
+    """A statement made in a manuscript, and the evidence offered for it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    text: str
+    where: str | None = None
+    registration: Registration = Registration.EXPLORATORY
+    registration_note: str = ""
+    """Why registration does not apply. Required when `registration` is `not_applicable`, and
+    the same convention a preregistration uses for an inapplicable heading: N/A with a reason,
+    never a blank."""
+
+    evidence: tuple[Evidence, ...] = ()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_confirmatory_flag(cls, data):
+        """`confirmatory: true|false` still parses, so manifests written against the boolean
+        keep working. `false` becomes `exploratory` and not `not_applicable`: a boolean never
+        carried the distinction, so reading one in cannot invent it."""
+        if isinstance(data, dict) and "confirmatory" in data:
+            data = dict(data)
+            flag = data.pop("confirmatory")
+            data.setdefault(
+                "registration", Registration.CONFIRMATORY if flag else Registration.EXPLORATORY
+            )
+        return data
+
+    @model_validator(mode="after")
+    def _not_applicable_needs_a_reason(self):
+        if self.registration is Registration.NOT_APPLICABLE and not self.registration_note:
+            raise ValueError(
+                f"claim {self.id!r}: registration 'not_applicable' needs a registration_note "
+                f"saying why no plan could have fixed this outcome"
+            )
+        return self
+
+    @property
+    def confirmatory(self) -> bool:
+        return self.registration is Registration.CONFIRMATORY
+
+    @property
+    def availability(self) -> Availability:
+        return Availability.OFFERED if self.evidence else Availability.NOT_OFFERED
+
+    @property
+    def digest(self) -> Digest:
+        """Content address of the claim as evaluated.
+
+        A decision names this so it cannot silently remain attached to text that has since
+        been edited.
+        """
+        return Digest.of_text(f"{self.id}\x00{self.text}\x00{self.where or ''}")