claims-cli 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. claims/__init__.py +132 -0
  2. claims/__main__.py +5 -0
  3. claims/adapters/__init__.py +6 -0
  4. claims/adapters/array.py +212 -0
  5. claims/adapters/base.py +75 -0
  6. claims/adapters/cells.py +94 -0
  7. claims/adapters/columnar.py +188 -0
  8. claims/adapters/prose.py +261 -0
  9. claims/adapters/reads.py +47 -0
  10. claims/adapters/rows.py +116 -0
  11. claims/adapters/sheet.py +149 -0
  12. claims/adapters/sqlite.py +73 -0
  13. claims/adapters/table.py +135 -0
  14. claims/adapters/tree.py +163 -0
  15. claims/checks.py +511 -0
  16. claims/cli.py +1103 -0
  17. claims/core/__init__.py +9 -0
  18. claims/core/artifacts.py +121 -0
  19. claims/core/checks.py +132 -0
  20. claims/core/claims.py +100 -0
  21. claims/core/evidence.py +708 -0
  22. claims/core/manifest.py +349 -0
  23. claims/core/numbers.py +146 -0
  24. claims/core/outcomes.py +410 -0
  25. claims/core/report.py +503 -0
  26. claims/corpus.py +344 -0
  27. claims/exceptions.py +106 -0
  28. claims/export/__init__.py +23 -0
  29. claims/export/rocrate.py +787 -0
  30. claims/export/sarif.py +401 -0
  31. claims/manifest.py +59 -0
  32. claims/models.py +222 -0
  33. claims/numbers.py +453 -0
  34. claims/origins.py +303 -0
  35. claims/policy.py +369 -0
  36. claims/provenance.py +42 -0
  37. claims/record.py +1099 -0
  38. claims/regression.py +171 -0
  39. claims/renderers/__init__.py +10 -0
  40. claims/renderers/sarif.py +294 -0
  41. claims/reruns.py +111 -0
  42. claims/resolve.py +116 -0
  43. claims/stale.py +333 -0
  44. claims/starter.py +432 -0
  45. claims/toolchain.py +120 -0
  46. claims/verify.py +1371 -0
  47. claims/why.py +398 -0
  48. claims_cli-0.6.0.dist-info/METADATA +139 -0
  49. claims_cli-0.6.0.dist-info/RECORD +51 -0
  50. claims_cli-0.6.0.dist-info/WHEEL +4 -0
  51. claims_cli-0.6.0.dist-info/entry_points.txt +2 -0
claims/core/report.py ADDED
@@ -0,0 +1,503 @@
1
+ """What a verification run produced."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import enum
6
+ from typing import Literal
7
+
8
+ from pydantic import BaseModel, ConfigDict, Field, model_serializer
9
+
10
+ from claims.core.checks import CheckedAssertion, RecordSetAside, RecordState
11
+ from claims.core.claims import Availability, Registration
12
+ from claims.core.evidence import Conversion, Statistic
13
+ from claims.core.manifest import RegenerationState
14
+ from claims.core.outcomes import (
15
+ Decision,
16
+ Ordering,
17
+ OrderingReason,
18
+ Outcome,
19
+ Reason,
20
+ RegistrationAuthority,
21
+ Tie,
22
+ Validity,
23
+ Warning_,
24
+ )
25
+
26
+ SCHEMA_VERSION = "repro/1"
27
+
28
+ _SHA256_HEX = r"^[a-f0-9]{64}$"
29
+
30
+
31
+ # ------------------------------------------------------------------------------------ report
32
+
33
+
34
+ class ArtifactState(BaseModel):
35
+ """What was found at each artifact's path, before any evidence was read."""
36
+
37
+ model_config = ConfigDict(frozen=True, extra="forbid")
38
+
39
+ artifact_id: str
40
+ validity: Validity
41
+ expected: str | None = None
42
+ actual: str | None = None
43
+ exists: bool = True
44
+ detail: str = ""
45
+ """Why, where the state needs one -- a path that exists and cannot be read."""
46
+
47
+
48
+ class ClaimAssessment(BaseModel):
49
+ """One claim's availability, and the decisions on the evidence it offered."""
50
+
51
+ model_config = ConfigDict(frozen=True, extra="forbid")
52
+
53
+ claim_id: str
54
+ claim_digest: str
55
+ confirmatory: bool = False
56
+ registration: Registration = Registration.EXPLORATORY
57
+ registration_note: str = ""
58
+ availability: Availability
59
+ ordering: Ordering = Ordering.NOT_APPLICABLE
60
+ ordering_reason: OrderingReason = OrderingReason.NOT_CONFIRMATORY
61
+ ordering_detail: str = ""
62
+ registration_authority: RegistrationAuthority | None = None
63
+ """The weakest authority among the runs that produced this claim's evidence, or None
64
+ where no run applies."""
65
+ decisions: tuple[Decision, ...] = ()
66
+
67
+ @property
68
+ def outcomes(self) -> tuple[Outcome, ...]:
69
+ if self.availability is Availability.NOT_OFFERED:
70
+ return (Outcome.NOT_OFFERED,)
71
+ return tuple(d.outcome for d in self.decisions)
72
+
73
+
74
+ class VerificationReport(BaseModel):
75
+ """Facts about what was checked. Frozen, and carries no verdict.
76
+
77
+ Whether a project passes is a policy question -- a missing optional citation may be
78
+ acceptable where an unchecked confirmatory result is not -- so the engine reports what
79
+ happened and `claims.policy` decides what it means.
80
+ """
81
+
82
+ model_config = ConfigDict(frozen=True, extra="forbid")
83
+
84
+ schema_version: str = SCHEMA_VERSION
85
+ project: str = ""
86
+ manifest_digest: str = ""
87
+ artifacts: tuple[ArtifactState, ...] = ()
88
+ claims: tuple[ClaimAssessment, ...] = ()
89
+
90
+ @property
91
+ def decisions(self) -> tuple[Decision, ...]:
92
+ return tuple(d for c in self.claims for d in c.decisions)
93
+
94
+ @property
95
+ def counts(self) -> dict[str, int]:
96
+ tally: dict[str, int] = {}
97
+ for claim in self.claims:
98
+ for outcome in claim.outcomes:
99
+ tally[outcome.value] = tally.get(outcome.value, 0) + 1
100
+ return tally
101
+
102
+ def artifacts_with(self, validity: Validity) -> tuple[str, ...]:
103
+ return tuple(a.artifact_id for a in self.artifacts if a.validity is validity)
104
+
105
+
106
+ # ------------------------------------------------------------------------------ reproduction
107
+
108
+
109
+ class Environment(BaseModel):
110
+ """Where a re-run happened, as far as the tool can observe it.
111
+
112
+ Nothing here names a person or a machine: no hostname, no user, no absolute path. These
113
+ records are committed to repositories that become public.
114
+ """
115
+
116
+ model_config = ConfigDict(frozen=True, extra="forbid")
117
+
118
+ system: str = ""
119
+ release: str = ""
120
+ machine: str = ""
121
+ processor: str = ""
122
+ python: str = ""
123
+ lockfile: str = ""
124
+ """Name of the lockfile found at the top of the project, if any."""
125
+ lockfile_digest: str = ""
126
+ gpus: tuple[str, ...] = ()
127
+ """Model and driver per device, as `nvidia-smi` reports them. Empty where it is absent."""
128
+ variables: dict[str, str] = {}
129
+ """The environment variables that bear on determinism, where set."""
130
+
131
+
132
+ class Witness(BaseModel):
133
+ """Where a re-run happened, as the process's environment said.
134
+
135
+ The fields are the variables a GitHub Actions runner sets, copied as they were given.
136
+ Nothing here was checked: no request is made to the service, and a process started with
137
+ these variables set by hand records the same thing. What a reader checks the record
138
+ against is the run's own page and log, at
139
+ `https://github.com/<repository>/actions/runs/<run_id>`. No URL is stored, since those
140
+ two fields are all one holds.
141
+
142
+ A variable the process was not given is left out of the record, and never written as
143
+ null or as an empty string.
144
+ """
145
+
146
+ model_config = ConfigDict(frozen=True, extra="forbid")
147
+
148
+ kind: Literal["github_actions"]
149
+ repository: str | None = None
150
+ """`GITHUB_REPOSITORY`: owner and name."""
151
+ workflow: str | None = None
152
+ """`GITHUB_WORKFLOW`: the workflow's name."""
153
+ run_id: str | None = None
154
+ """`GITHUB_RUN_ID`."""
155
+ run_attempt: str | None = None
156
+ """`GITHUB_RUN_ATTEMPT`: 1 for a first run, more for a re-run of the same run."""
157
+ sha: str | None = None
158
+ """`GITHUB_SHA`: the commit the workflow ran on."""
159
+ ref: str | None = None
160
+ """`GITHUB_REF`."""
161
+ runner_os: str | None = None
162
+ """`RUNNER_OS`."""
163
+
164
+ @model_serializer(mode="wrap")
165
+ def _omit_what_was_not_given(self, handler):
166
+ return {name: value for name, value in handler(self).items() if value is not None}
167
+
168
+ @property
169
+ def said(self) -> str:
170
+ """Where it ran, as a clause: `in GitHub Actions run 123456 of owner/repo`."""
171
+ return (
172
+ "in GitHub Actions"
173
+ + (f" run {self.run_id}" if self.run_id else "")
174
+ + (f" of {self.repository}" if self.repository else "")
175
+ )
176
+
177
+
178
+ class ReproductionReport(BaseModel):
179
+ """What one `repro reproduce` invocation ran and found. Frozen, and carries no verdict."""
180
+
181
+ model_config = ConfigDict(frozen=True, extra="forbid")
182
+
183
+ schema_version: str = SCHEMA_VERSION
184
+ project: str = ""
185
+ manifest_digest: str = ""
186
+ tool_version: str = ""
187
+ started_at: str = ""
188
+ ended_at: str = ""
189
+ environment: Environment = Environment()
190
+ witness: Witness | None = None
191
+ """Where the re-run happened, where the environment said. None for a run that was given
192
+ no such variables, which is every run on an author's machine."""
193
+ regenerations: tuple[RegenerationState, ...] = ()
194
+
195
+ @model_serializer(mode="wrap")
196
+ def _omit_no_witness(self, handler):
197
+ """Leave the field out where there is none, so an entry for a local run is the entry
198
+ it was before the field existed."""
199
+ dumped = handler(self)
200
+ if self.witness is None:
201
+ dumped.pop("witness", None)
202
+ return dumped
203
+
204
+ @property
205
+ def counts(self) -> dict[str, int]:
206
+ tally: dict[str, int] = {}
207
+ for state in self.regenerations:
208
+ tally[state.state.value] = tally.get(state.state.value, 0) + 1
209
+ return tally
210
+
211
+
212
+ # --------------------------------------------------------------------------------- staleness
213
+
214
+
215
+ class Freshness(enum.StrEnum):
216
+ """Whether a file is still what a recorded re-run produced.
217
+
218
+ Relative to the record of re-runs, never to the digests a manifest carries for its own
219
+ regenerations: a manifest rebuilt from the files on disk agrees with them whether or not
220
+ any command ran. A pin that no longer matches its file is `Validity.BROKEN_PIN`, a
221
+ different fact that `repro verify` reports.
222
+ """
223
+
224
+ CURRENT = "current"
225
+ """A recorded re-run of the producing command read the inputs now on disk and its output is
226
+ the one now on disk, and the same holds for every producer upstream. Consistent with a
227
+ recorded re-run; nothing was executed to establish it."""
228
+ STALE = "stale"
229
+ """Re-runs are recorded and none matches the files now on disk, here or upstream."""
230
+ NEVER_RERUN = "never_rerun"
231
+ """A command produces the file and the record holds no re-run of it that reproduced."""
232
+ NO_PRODUCER = "no_producer"
233
+ """No declared command writes the file, so there is nothing upstream to compare."""
234
+ UNDETERMINED = "undetermined"
235
+ """A file the comparison needs is missing, or the producers form a cycle."""
236
+ PARTLY_OUTSIDE = "partly_outside_the_record"
237
+ """Of an assertion or a claim only: some of what it reads is current, and the rest has no
238
+ producer."""
239
+
240
+
241
+ class StaleCause(enum.StrEnum):
242
+ """Why a regeneration is not current."""
243
+
244
+ INPUT_CHANGED = "input_changed"
245
+ COMMAND_CHANGED = "command_changed"
246
+ OUTPUT_CHANGED = "output_changed"
247
+ UPSTREAM_STALE = "upstream_stale"
248
+ INPUT_MISSING = "input_missing"
249
+ OUTPUT_MISSING = "output_missing"
250
+ CYCLE = "cycle"
251
+ LATER_RERUN_DID_NOT_REPRODUCE = "later_rerun_did_not_reproduce"
252
+
253
+
254
+ class StaleFinding(BaseModel):
255
+ """One difference between a regeneration's latest recorded re-run and the files on disk.
256
+
257
+ Stated once per regeneration and file, where the difference is, however many records and
258
+ claims lie downstream of it.
259
+ """
260
+
261
+ model_config = ConfigDict(frozen=True, extra="forbid")
262
+
263
+ cause: StaleCause
264
+ regeneration: str
265
+ artifact: str
266
+ observed: str | None = None
267
+ """The digest the re-run recorded for the file."""
268
+ on_disk: str | None = None
269
+ rerun_at: str | None = None
270
+ """When the re-run compared against started."""
271
+ witness: Witness | None = None
272
+ """Where that re-run happened, where its entry says. None where it does not."""
273
+
274
+
275
+ class PinDisagreement(BaseModel):
276
+ """A regeneration whose recorded digest for an input is not that artifact's pin."""
277
+
278
+ model_config = ConfigDict(frozen=True, extra="forbid")
279
+
280
+ regeneration: str
281
+ artifact: str
282
+ recorded: str
283
+ pinned: str
284
+
285
+
286
+ class RegenerationNode(BaseModel):
287
+ model_config = ConfigDict(frozen=True, extra="forbid")
288
+
289
+ id: str
290
+ artifact: str
291
+ state: Freshness
292
+ causes: tuple[StaleCause, ...] = ()
293
+ upstream: str | None = None
294
+ """The nearest upstream producer in this state, where the state comes from upstream."""
295
+ distance: int | None = None
296
+ """How many producers lie between this record and `upstream`, counting `upstream`."""
297
+ rerun_at: str | None = None
298
+ """When the re-run compared against started. None where no re-run is recorded."""
299
+ witness: Witness | None = None
300
+ """Where that re-run happened, where its entry says. None where it does not."""
301
+
302
+
303
+ class ArtifactNode(BaseModel):
304
+ model_config = ConfigDict(frozen=True, extra="forbid")
305
+
306
+ id: str
307
+ path: str = ""
308
+ state: Freshness
309
+ producer: str | None = None
310
+ on_disk: str | None = None
311
+
312
+
313
+ class AssertionNode(BaseModel):
314
+ model_config = ConfigDict(frozen=True, extra="forbid")
315
+
316
+ kind: str
317
+ artifacts: tuple[str, ...] = ()
318
+ state: Freshness
319
+
320
+
321
+ class ClaimNode(BaseModel):
322
+ model_config = ConfigDict(frozen=True, extra="forbid")
323
+
324
+ id: str
325
+ state: Freshness
326
+ assertions: tuple[AssertionNode, ...] = ()
327
+
328
+
329
+ class Edge(BaseModel):
330
+ """`reads` runs from a claim to an artifact, `produced_by` from an artifact to its
331
+ regeneration, and `consumes` from a regeneration to an input."""
332
+
333
+ model_config = ConfigDict(frozen=True, extra="forbid")
334
+
335
+ kind: Literal["reads", "produced_by", "consumes"]
336
+ source: str
337
+ target: str
338
+ recorded: str | None = None
339
+ """The digest the manifest's regeneration record names."""
340
+ observed: str | None = None
341
+ """The digest the re-run compared against recorded."""
342
+ on_disk: str | None = None
343
+
344
+
345
+ class StalenessReport(BaseModel):
346
+ """What `repro stale` found, as the graph it walked. Frozen, and carries no verdict."""
347
+
348
+ model_config = ConfigDict(frozen=True, extra="forbid")
349
+
350
+ schema_version: str = SCHEMA_VERSION
351
+ project: str = ""
352
+ manifest_digest: str = ""
353
+ reruns: int = 0
354
+ """How many invocations the record of re-runs holds."""
355
+ claims: tuple[ClaimNode, ...] = ()
356
+ artifacts: tuple[ArtifactNode, ...] = ()
357
+ regenerations: tuple[RegenerationNode, ...] = ()
358
+ edges: tuple[Edge, ...] = ()
359
+ findings: tuple[StaleFinding, ...] = ()
360
+ record_disagrees_with_pin: tuple[PinDisagreement, ...] = ()
361
+
362
+
363
+ # --------------------------------------------------------------------------------- one claim
364
+
365
+
366
+ class FileRead(BaseModel):
367
+ """One file an assertion reads: its pin, and what sits at the declared address."""
368
+
369
+ model_config = ConfigDict(frozen=True, extra="forbid")
370
+
371
+ artifact: str
372
+ path: str = ""
373
+ side: str = ""
374
+ """Which side of a `correspondence` this is, in the author's word for it."""
375
+ validity: Validity | None = None
376
+ """None where the manifest declares no such artifact."""
377
+ pinned: str | None = None
378
+ on_disk: str | None = None
379
+ address: str = ""
380
+ """Where the assertion looks. Empty for a quotation, which addresses no value."""
381
+ stored: str | None = None
382
+ """The value at the address, as stored. None where none was read."""
383
+ conversion: Conversion | None = None
384
+ """The conversion the assertion declares for this value, or None."""
385
+ converted: str | None = None
386
+ """`stored` under `conversion`, which is the value compared. None where no conversion is
387
+ declared, or where no number was read to convert."""
388
+
389
+
390
+ class AssertionAccount(BaseModel):
391
+ """One assertion of a claim, as `repro verify` evaluates it now."""
392
+
393
+ model_config = ConfigDict(frozen=True, extra="forbid")
394
+
395
+ kind: str
396
+ name: str = ""
397
+ printed: str | None = None
398
+ """The value as the manuscript prints it, or the passage a quotation asserts."""
399
+ reads: tuple[FileRead, ...] = ()
400
+ places: int | None = None
401
+ """How many decimal places the assertion declares the manuscript reports the value to."""
402
+ tie: Tie | None = None
403
+ """Set where the compared value lay exactly halfway between two printed values."""
404
+ statistic: Statistic | None = None
405
+ """What an `aggregate` computes over the values it reads. None for every other kind."""
406
+ computed: str | None = None
407
+ """That statistic of the stored values. None where one of them held no number."""
408
+ outcome: Outcome
409
+ reason: Reason
410
+ detail: str = ""
411
+ state: Freshness
412
+ warnings: tuple[Warning_, ...] = ()
413
+ """The warnings on the decision, as `repro verify` lists them beside the assertion. A
414
+ warning qualifies an outcome and is not one: a `verified` assertion may carry any."""
415
+ history: tuple[CheckedAssertion, ...] = ()
416
+ """Each way the record of checks holds this assertion, oldest first: what it declared,
417
+ the digest of each file read and the outcome, with when a check first found it so. Empty
418
+ where no check of it is recorded."""
419
+ now: CheckedAssertion | None = None
420
+ """The assertion as evaluated now, where that is not the last entry of `history`: it was
421
+ edited, or a file it reads was, and no recorded check has seen it since. None where the
422
+ record's last entry is how it stands, and where nothing is recorded."""
423
+ formerly: tuple[CheckedAssertion, ...] = ()
424
+ """The last recorded state of an assertion of a claim the manifest no longer declares,
425
+ where that state was not `verified` and it read the same artifacts at the same address
426
+ as this one. Nothing else is compared, and a quotation, which has no address, is never
427
+ listed."""
428
+
429
+
430
+ class ChainNode(BaseModel):
431
+ """One file a claim rests on: a file it reads, or a file upstream of one."""
432
+
433
+ model_config = ConfigDict(frozen=True, extra="forbid")
434
+
435
+ artifact: str
436
+ path: str = ""
437
+ steps: int
438
+ """How many commands lie between the claim and this file. 0 for a file the claim reads."""
439
+ validity: Validity | None = None
440
+ state: Freshness
441
+ command: tuple[str, ...] = ()
442
+ volatile: tuple[str, ...] = ()
443
+ """The fields the record leaves out of the comparison of its output."""
444
+ regeneration: RegenerationNode | None = None
445
+ """The record that writes the file. None where no command is recorded for it."""
446
+
447
+
448
+ class NotEstablishedKind(enum.StrEnum):
449
+ """What a line under `not established` is about."""
450
+
451
+ NO_PRODUCER = "no_producer"
452
+ NEVER_RERUN = "never_rerun"
453
+ ABSENT = "absent"
454
+ BROKEN_PIN = "broken_pin"
455
+ CYCLE = "cycle"
456
+ UNCHECKED = "unchecked"
457
+ NOT_FOUND = "not_found"
458
+ ERROR = "error"
459
+ NO_EVIDENCE = "no_evidence"
460
+ UNDECLARED_INPUTS = "undeclared_inputs"
461
+ ADDRESS = "address"
462
+ COMPARISON = "comparison"
463
+
464
+
465
+ class NotEstablished(BaseModel):
466
+ model_config = ConfigDict(frozen=True, extra="forbid")
467
+
468
+ kind: NotEstablishedKind
469
+ subject: str = ""
470
+ """The file, record or assertion the line names. Empty for the lines that hold of the
471
+ design."""
472
+ said: str
473
+
474
+
475
+ class ClaimAccount(BaseModel):
476
+ """What `repro why` found for one claim. Frozen, and carries no verdict."""
477
+
478
+ model_config = ConfigDict(frozen=True, extra="forbid")
479
+
480
+ schema_version: str = SCHEMA_VERSION
481
+ project: str = ""
482
+ manifest_digest: str = ""
483
+ claim_id: str
484
+ text: str = ""
485
+ where: str | None = None
486
+ assertions: tuple[AssertionAccount, ...] = ()
487
+ chain: tuple[ChainNode, ...] = ()
488
+ """Every file the claim rests on, nearest first."""
489
+ edges: tuple[Edge, ...] = ()
490
+ """The edges of the staleness graph that lie on the chain."""
491
+ findings: tuple[StaleFinding, ...] = ()
492
+ not_established: tuple[NotEstablished, ...] = ()
493
+ outcomes: dict[Outcome, int] = Field(default_factory=dict)
494
+ """How many of the claim's assertions have each outcome, in the order `Outcome` declares
495
+ them. An outcome no assertion has is left out."""
496
+ states: dict[Freshness, int] = Field(default_factory=dict)
497
+ """How many of the claim's assertions are in each state against the record of re-runs."""
498
+ records: tuple[RecordState, ...] = ()
499
+ """Each record of checks found for the project: the local one, then the tracked one."""
500
+ set_aside: tuple[RecordSetAside, ...] = ()
501
+ """Each record the records now kept say was set aside, oldest first."""
502
+ no_local_record: str = ""
503
+ """Why no local record of checks is kept here. Empty where one is, or would be."""