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.
- claims/__init__.py +132 -0
- claims/__main__.py +5 -0
- claims/adapters/__init__.py +6 -0
- claims/adapters/array.py +212 -0
- claims/adapters/base.py +75 -0
- claims/adapters/cells.py +94 -0
- claims/adapters/columnar.py +188 -0
- claims/adapters/prose.py +261 -0
- claims/adapters/reads.py +47 -0
- claims/adapters/rows.py +116 -0
- claims/adapters/sheet.py +149 -0
- claims/adapters/sqlite.py +73 -0
- claims/adapters/table.py +135 -0
- claims/adapters/tree.py +163 -0
- claims/checks.py +511 -0
- claims/cli.py +1103 -0
- claims/core/__init__.py +9 -0
- claims/core/artifacts.py +121 -0
- claims/core/checks.py +132 -0
- claims/core/claims.py +100 -0
- claims/core/evidence.py +708 -0
- claims/core/manifest.py +349 -0
- claims/core/numbers.py +146 -0
- claims/core/outcomes.py +410 -0
- claims/core/report.py +503 -0
- claims/corpus.py +344 -0
- claims/exceptions.py +106 -0
- claims/export/__init__.py +23 -0
- claims/export/rocrate.py +787 -0
- claims/export/sarif.py +401 -0
- claims/manifest.py +59 -0
- claims/models.py +222 -0
- claims/numbers.py +453 -0
- claims/origins.py +303 -0
- claims/policy.py +369 -0
- claims/provenance.py +42 -0
- claims/record.py +1099 -0
- claims/regression.py +171 -0
- claims/renderers/__init__.py +10 -0
- claims/renderers/sarif.py +294 -0
- claims/reruns.py +111 -0
- claims/resolve.py +116 -0
- claims/stale.py +333 -0
- claims/starter.py +432 -0
- claims/toolchain.py +120 -0
- claims/verify.py +1371 -0
- claims/why.py +398 -0
- claims_cli-0.6.0.dist-info/METADATA +139 -0
- claims_cli-0.6.0.dist-info/RECORD +51 -0
- claims_cli-0.6.0.dist-info/WHEEL +4 -0
- claims_cli-0.6.0.dist-info/entry_points.txt +2 -0
claims/export/rocrate.py
ADDED
|
@@ -0,0 +1,787 @@
|
|
|
1
|
+
"""The check records as an RO-Crate metadata document.
|
|
2
|
+
|
|
3
|
+
RO-Crate 1.3 describes files, the software that made them and the runs of that software, and
|
|
4
|
+
the Process Run Crate profile says how one run is written down. Neither has a term for what a
|
|
5
|
+
check record states: that the value at an address in a file was compared with a value a
|
|
6
|
+
manuscript prints. This writes the files, the commands and their recorded re-runs in the terms
|
|
7
|
+
those two already have, and the checks in a small profile of this tool's own,
|
|
8
|
+
`https://reproducible.science/ro-crate/claim-check/0.1/`, which adds what is missing and
|
|
9
|
+
nothing else. Experimental, like the record it projects.
|
|
10
|
+
|
|
11
|
+
The projection is of `claims.record.ExportRecord` and of nothing beside it. `from_ro_crate`
|
|
12
|
+
reads the records back, and for a record this version understands the two are inverse, so
|
|
13
|
+
what a record holds a crate holds. A file no record names is not in the crate: an artifact
|
|
14
|
+
the manifest declares that no assertion reads, and that no command upstream of one reads or
|
|
15
|
+
writes, appears in no record.
|
|
16
|
+
|
|
17
|
+
Nothing here is evaluated, and no time is taken: every date in the document is one a record
|
|
18
|
+
carries, so the same records give the same bytes.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import json
|
|
24
|
+
import pathlib
|
|
25
|
+
import shlex
|
|
26
|
+
import urllib.parse
|
|
27
|
+
from collections.abc import Sequence
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
from claims.exceptions import ReproError
|
|
31
|
+
from claims.models import Origin, Regeneration
|
|
32
|
+
from claims.record import (
|
|
33
|
+
CheckType,
|
|
34
|
+
Command,
|
|
35
|
+
ExportRecord,
|
|
36
|
+
FileState,
|
|
37
|
+
NormalizedOutcome,
|
|
38
|
+
read_outcome,
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
METADATA_FILE = "ro-crate-metadata.json"
|
|
42
|
+
|
|
43
|
+
RO_CRATE = "https://w3id.org/ro/crate/1.3"
|
|
44
|
+
RO_CRATE_CONTEXT = "https://w3id.org/ro/crate/1.3/context"
|
|
45
|
+
PROCESS_RUN_CRATE = "https://w3id.org/ro/wfrun/process/0.6"
|
|
46
|
+
PROFILE = "https://reproducible.science/ro-crate/claim-check/0.1/"
|
|
47
|
+
PROFILE_VERSION = "0.1-experimental"
|
|
48
|
+
|
|
49
|
+
#: The terms the profile adds, each defined under its own anchor on the profile's page. A term
|
|
50
|
+
#: is here only where schema.org, as the RO-Crate context carries it, has none that says the
|
|
51
|
+
#: same thing.
|
|
52
|
+
TERMS = (
|
|
53
|
+
"ClaimCheck",
|
|
54
|
+
"DeclaredCommand",
|
|
55
|
+
"FileRead",
|
|
56
|
+
"addressKind",
|
|
57
|
+
"argv",
|
|
58
|
+
"assertionIndex",
|
|
59
|
+
"assertionKind",
|
|
60
|
+
"assertionName",
|
|
61
|
+
"assertionPosition",
|
|
62
|
+
"backend",
|
|
63
|
+
"backendVersion",
|
|
64
|
+
"canonicalAddress",
|
|
65
|
+
"checkType",
|
|
66
|
+
"checkWarning",
|
|
67
|
+
"checkerVersion",
|
|
68
|
+
"claimDigest",
|
|
69
|
+
"comparisonMode",
|
|
70
|
+
"comparisonStage",
|
|
71
|
+
"computedValue",
|
|
72
|
+
"conversion",
|
|
73
|
+
"convertedValue",
|
|
74
|
+
"declaredInput",
|
|
75
|
+
"declaredOutput",
|
|
76
|
+
"declaredPlaces",
|
|
77
|
+
"durationSeconds",
|
|
78
|
+
"executionStage",
|
|
79
|
+
"exitCode",
|
|
80
|
+
"extractionDigest",
|
|
81
|
+
"extractionStage",
|
|
82
|
+
"extractionTool",
|
|
83
|
+
"extractionToolVersion",
|
|
84
|
+
"fileRead",
|
|
85
|
+
"freshness",
|
|
86
|
+
"historyLastChangedAt",
|
|
87
|
+
"historyStates",
|
|
88
|
+
"lastRerun",
|
|
89
|
+
"manifest",
|
|
90
|
+
"manifestLine",
|
|
91
|
+
"memberCount",
|
|
92
|
+
"nativeOutcome",
|
|
93
|
+
"nativeReason",
|
|
94
|
+
"outcome",
|
|
95
|
+
"outputDigest",
|
|
96
|
+
"passageLine",
|
|
97
|
+
"pinnedDigest",
|
|
98
|
+
"printedValue",
|
|
99
|
+
"readsFile",
|
|
100
|
+
"recordVersion",
|
|
101
|
+
"rerunReason",
|
|
102
|
+
"rerunState",
|
|
103
|
+
"side",
|
|
104
|
+
"staleCause",
|
|
105
|
+
"statistic",
|
|
106
|
+
"tieLower",
|
|
107
|
+
"tiePrinted",
|
|
108
|
+
"tieUpper",
|
|
109
|
+
"tolerance",
|
|
110
|
+
"upstream",
|
|
111
|
+
"validity",
|
|
112
|
+
"whereStated",
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
#: What each outcome and check type is, as the crate's own entity for the term says it.
|
|
116
|
+
_OUTCOMES = {
|
|
117
|
+
NormalizedOutcome.MATCH: "The file was read, the address resolved, a comparison ran, and "
|
|
118
|
+
"the two agreed.",
|
|
119
|
+
NormalizedOutcome.MISMATCH: "The file was read, the address resolved, a comparison ran, "
|
|
120
|
+
"and the two differed.",
|
|
121
|
+
NormalizedOutcome.NOT_FOUND: "The file was readable and the address did not resolve to "
|
|
122
|
+
"exactly one value of the kind the assertion needs. Nothing was compared.",
|
|
123
|
+
NormalizedOutcome.NOT_CHECKED: "No comparison occurred, because something it needed was "
|
|
124
|
+
"absent or was skipped.",
|
|
125
|
+
NormalizedOutcome.ERROR: "The tool failed.",
|
|
126
|
+
}
|
|
127
|
+
_CHECK_TYPES = {
|
|
128
|
+
CheckType.VALUE_COMPARISON: "A value the manuscript prints, against the value at an "
|
|
129
|
+
"address in a file.",
|
|
130
|
+
CheckType.PASSAGE_PRESENCE: "A passage occurs in a file.",
|
|
131
|
+
CheckType.CORRESPONDENCE: "The values at two addresses, in two files, agree.",
|
|
132
|
+
CheckType.AGGREGATE_COMPARISON: "A value the manuscript prints, against a statistic "
|
|
133
|
+
"computed over the values at several addresses.",
|
|
134
|
+
CheckType.ARTIFACT_IDENTITY: "A file's bytes are the bytes that were recorded.",
|
|
135
|
+
CheckType.LINEAGE_CHECK: "A file was produced by a recorded process from recorded inputs.",
|
|
136
|
+
CheckType.RERUN_COMPARISON: "What a command wrote when run again, against what it wrote "
|
|
137
|
+
"before.",
|
|
138
|
+
CheckType.COVERAGE_CHECK: "Whether something the manuscript states has a claim declared "
|
|
139
|
+
"for it.",
|
|
140
|
+
CheckType.OTHER: "A proposition none of the other check types names.",
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
#: A command that ran to its end completed, whatever its output then held. Only one that did
|
|
144
|
+
#: not finish, or finished and wrote nothing, failed.
|
|
145
|
+
_FAILED = "http://schema.org/FailedActionStatus"
|
|
146
|
+
_COMPLETED = "http://schema.org/CompletedActionStatus"
|
|
147
|
+
|
|
148
|
+
#: RO-Crate requires a root data entity to say how the crate may be used, and a record does
|
|
149
|
+
#: not know. The property is therefore a statement that nothing is stated, which the
|
|
150
|
+
#: specification allows as text, and never a guess at a license.
|
|
151
|
+
LICENSE_NOT_STATED = (
|
|
152
|
+
"Not stated. The check records this crate is written from carry no license, and the "
|
|
153
|
+
"terms of each file are those of the project it belongs to."
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
Entity = dict[str, Any]
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
class NothingToExportError(ReproError):
|
|
160
|
+
"""No assertion was checked, so there is no record for a crate to describe."""
|
|
161
|
+
|
|
162
|
+
def __init__(self) -> None:
|
|
163
|
+
super().__init__(
|
|
164
|
+
"no assertion was checked, so there is nothing for an RO-Crate to describe"
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class ConflictingRecordsError(ReproError):
|
|
169
|
+
"""Two records say different things about what one identifier names."""
|
|
170
|
+
|
|
171
|
+
def __init__(self, identifier: str) -> None:
|
|
172
|
+
self.identifier = identifier
|
|
173
|
+
super().__init__(
|
|
174
|
+
f"the records disagree about {identifier!r}; one crate describes one run of the "
|
|
175
|
+
f"checker over one manifest"
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class NotAClaimCheckCrateError(ReproError):
|
|
180
|
+
"""A document is not one this module wrote."""
|
|
181
|
+
|
|
182
|
+
def __init__(self, detail: str) -> None:
|
|
183
|
+
super().__init__(f"not a claim-check crate: {detail}")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def _ref(identifier: str) -> dict[str, str]:
|
|
187
|
+
return {"@id": identifier}
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def _local(kind: str, *parts: str | int) -> str:
|
|
191
|
+
return f"#{kind}/" + "/".join(urllib.parse.quote(str(part), safe="") for part in parts)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _packed(values: Sequence[Any]) -> Any:
|
|
195
|
+
"""RO-Crate JSON-LD is compacted: one value stands alone, several are an array."""
|
|
196
|
+
return values[0] if len(values) == 1 else list(values)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _unpacked(value: Any) -> list[Any]:
|
|
200
|
+
if value is None:
|
|
201
|
+
return []
|
|
202
|
+
return value if isinstance(value, list) else [value]
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _present(entity: Entity) -> Entity:
|
|
206
|
+
return {key: value for key, value in entity.items() if value is not None}
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
class _Graph:
|
|
210
|
+
"""The entities of one crate, each stated once."""
|
|
211
|
+
|
|
212
|
+
def __init__(self) -> None:
|
|
213
|
+
self.entities: dict[str, Entity] = {}
|
|
214
|
+
self.files: dict[str, str] = {}
|
|
215
|
+
"""`@id` by artifact id."""
|
|
216
|
+
|
|
217
|
+
def add(self, entity: Entity) -> str:
|
|
218
|
+
identifier = entity["@id"]
|
|
219
|
+
held = self.entities.setdefault(identifier, entity)
|
|
220
|
+
if held != entity:
|
|
221
|
+
raise ConflictingRecordsError(identifier)
|
|
222
|
+
return identifier
|
|
223
|
+
|
|
224
|
+
def file(self, state: FileState) -> str:
|
|
225
|
+
"""The entity for one declared file, by the path it has in the crate.
|
|
226
|
+
|
|
227
|
+
A file that is on disk under a path inside the project is a data entity at that path.
|
|
228
|
+
One that is absent, undeclared, outside the project, or at a path another artifact
|
|
229
|
+
already has is described under a local identifier, which RO-Crate keeps for a file
|
|
230
|
+
that is not in the crate.
|
|
231
|
+
"""
|
|
232
|
+
path = pathlib.PurePosixPath(state.path)
|
|
233
|
+
inside = bool(state.path) and not path.is_absolute() and ".." not in path.parts
|
|
234
|
+
identifier = urllib.parse.quote(state.path)
|
|
235
|
+
taken = identifier in self.entities and self.files.get(state.artifact) != identifier
|
|
236
|
+
if not inside or state.on_disk is None or taken:
|
|
237
|
+
identifier = _local("artifact", state.artifact)
|
|
238
|
+
self.files[state.artifact] = identifier
|
|
239
|
+
return self.add(
|
|
240
|
+
_present(
|
|
241
|
+
{
|
|
242
|
+
"@id": identifier,
|
|
243
|
+
"@type": "File",
|
|
244
|
+
"name": state.path or state.artifact,
|
|
245
|
+
"identifier": state.artifact,
|
|
246
|
+
"alternateName": state.path
|
|
247
|
+
if state.path and identifier != state.path
|
|
248
|
+
else None,
|
|
249
|
+
"encodingFormat": state.media_type or None,
|
|
250
|
+
"sha256": state.on_disk,
|
|
251
|
+
"pinnedDigest": state.pinned,
|
|
252
|
+
"validity": state.validity.value if state.validity else None,
|
|
253
|
+
"isBasedOn": _ref(self.origin(state.artifact, state.origin))
|
|
254
|
+
if state.origin
|
|
255
|
+
else None,
|
|
256
|
+
}
|
|
257
|
+
)
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
def origin(self, artifact: str, origin: Origin) -> str:
|
|
261
|
+
"""The file an artifact's bytes were copied from: its path, as `name`, at a commit, as
|
|
262
|
+
`version`, of a repository it `isPartOf`. RO-Crate 1.3 names no property for a copy,
|
|
263
|
+
so the file entity points at this with schema.org's `isBasedOn`."""
|
|
264
|
+
repository = self.add(
|
|
265
|
+
{
|
|
266
|
+
"@id": _local("repository", origin.repository),
|
|
267
|
+
"@type": "SoftwareSourceCode",
|
|
268
|
+
"name": origin.repository,
|
|
269
|
+
"codeRepository": origin.repository,
|
|
270
|
+
}
|
|
271
|
+
)
|
|
272
|
+
return self.add(
|
|
273
|
+
{
|
|
274
|
+
"@id": _local("origin", artifact),
|
|
275
|
+
"@type": "CreativeWork",
|
|
276
|
+
"name": origin.path,
|
|
277
|
+
"version": origin.commit,
|
|
278
|
+
"isPartOf": _ref(repository),
|
|
279
|
+
}
|
|
280
|
+
)
|
|
281
|
+
|
|
282
|
+
def term(self, word: str, said: str) -> dict[str, str]:
|
|
283
|
+
return _ref(
|
|
284
|
+
self.add(
|
|
285
|
+
{
|
|
286
|
+
"@id": f"{PROFILE}#{word}",
|
|
287
|
+
"@type": "DefinedTerm",
|
|
288
|
+
"name": word,
|
|
289
|
+
"termCode": word,
|
|
290
|
+
"description": said,
|
|
291
|
+
}
|
|
292
|
+
)
|
|
293
|
+
)
|
|
294
|
+
|
|
295
|
+
def command(self, command: Command) -> str:
|
|
296
|
+
"""A declared command as the tool Process Run Crate asks for, and its latest recorded
|
|
297
|
+
re-run as the run of that tool."""
|
|
298
|
+
identifier = _local("command", command.id)
|
|
299
|
+
inputs = [_ref(self.file(wanted)) for wanted in command.inputs]
|
|
300
|
+
output = _ref(self.file(command.output))
|
|
301
|
+
rerun = command.last_rerun
|
|
302
|
+
if rerun is not None:
|
|
303
|
+
failed = rerun.state is Regeneration.FAILED
|
|
304
|
+
self.add(
|
|
305
|
+
_present(
|
|
306
|
+
{
|
|
307
|
+
"@id": _local("rerun", command.id),
|
|
308
|
+
"@type": "CreateAction",
|
|
309
|
+
"name": f"Re-run of {command.id}",
|
|
310
|
+
"description": shlex.join(command.command),
|
|
311
|
+
"instrument": _ref(identifier),
|
|
312
|
+
"object": _packed(inputs) if inputs else None,
|
|
313
|
+
"result": output,
|
|
314
|
+
"startTime": rerun.started_at or None,
|
|
315
|
+
"endTime": rerun.ended_at or None,
|
|
316
|
+
"actionStatus": _ref(
|
|
317
|
+
self.add(
|
|
318
|
+
{
|
|
319
|
+
"@id": _FAILED if failed else _COMPLETED,
|
|
320
|
+
"@type": "ActionStatusType",
|
|
321
|
+
"name": "failed" if failed else "completed",
|
|
322
|
+
}
|
|
323
|
+
)
|
|
324
|
+
),
|
|
325
|
+
"error": (rerun.reason or None) if failed else None,
|
|
326
|
+
"rerunState": rerun.state.value,
|
|
327
|
+
"rerunReason": rerun.reason,
|
|
328
|
+
"checkerVersion": rerun.checker_version or None,
|
|
329
|
+
"exitCode": rerun.exit_code,
|
|
330
|
+
"durationSeconds": rerun.duration_seconds,
|
|
331
|
+
"outputDigest": rerun.output_digest,
|
|
332
|
+
}
|
|
333
|
+
)
|
|
334
|
+
)
|
|
335
|
+
return self.add(
|
|
336
|
+
_present(
|
|
337
|
+
{
|
|
338
|
+
"@id": identifier,
|
|
339
|
+
# Process Run Crate says a tool SHOULD be a SoftwareApplication, a
|
|
340
|
+
# SoftwareSourceCode or a ComputationalWorkflow. RO-Crate 1.3 requires the
|
|
341
|
+
# first to have a `url` and a `version` and the other two to be files, and
|
|
342
|
+
# a declared command is an argv with none of those. `HowTo` is the type
|
|
343
|
+
# the specification itself offers for a shell command.
|
|
344
|
+
"@type": ["HowTo", "DeclaredCommand"],
|
|
345
|
+
"name": command.id,
|
|
346
|
+
"identifier": command.id,
|
|
347
|
+
"description": shlex.join(command.command),
|
|
348
|
+
"argv": json.dumps(list(command.command), ensure_ascii=False),
|
|
349
|
+
"declaredInput": _packed(inputs) if inputs else None,
|
|
350
|
+
"declaredOutput": output,
|
|
351
|
+
"freshness": command.state.value,
|
|
352
|
+
"staleCause": _packed(list(command.causes)) if command.causes else None,
|
|
353
|
+
"lastRerun": _ref(_local("rerun", command.id)) if rerun else None,
|
|
354
|
+
}
|
|
355
|
+
)
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def _check(record: ExportRecord, graph: _Graph) -> str:
|
|
360
|
+
claim, assertion = record.claim, record.assertion
|
|
361
|
+
identifier = _local("check", claim.id, assertion.index)
|
|
362
|
+
passage = next((p for p in claim.passages if p.assertion == assertion.index), None)
|
|
363
|
+
|
|
364
|
+
manifest = None
|
|
365
|
+
if record.manifest.path:
|
|
366
|
+
name = pathlib.PurePosixPath(record.manifest.path).name
|
|
367
|
+
manifest = graph.add(
|
|
368
|
+
_present(
|
|
369
|
+
{
|
|
370
|
+
"@id": urllib.parse.quote(name),
|
|
371
|
+
"@type": "File",
|
|
372
|
+
"name": name,
|
|
373
|
+
"alternateName": record.manifest.path if record.manifest.path != name else None,
|
|
374
|
+
"description": "The manifest the assertions were read from.",
|
|
375
|
+
"encodingFormat": "application/yaml",
|
|
376
|
+
"sha256": record.manifest.digest,
|
|
377
|
+
}
|
|
378
|
+
)
|
|
379
|
+
)
|
|
380
|
+
checker = graph.add(
|
|
381
|
+
{
|
|
382
|
+
"@id": _local("checker", record.checker.name, record.checker.version),
|
|
383
|
+
"@type": "SoftwareApplication",
|
|
384
|
+
"name": record.checker.name,
|
|
385
|
+
"version": record.checker.version,
|
|
386
|
+
**({"url": record.checker.url} if record.checker.url else {}),
|
|
387
|
+
}
|
|
388
|
+
)
|
|
389
|
+
stated = graph.add(
|
|
390
|
+
_present(
|
|
391
|
+
{
|
|
392
|
+
"@id": _local("claim", claim.id),
|
|
393
|
+
"@type": "Claim",
|
|
394
|
+
"name": claim.id,
|
|
395
|
+
"identifier": claim.id,
|
|
396
|
+
"text": claim.text,
|
|
397
|
+
"whereStated": claim.where,
|
|
398
|
+
"claimDigest": claim.digest,
|
|
399
|
+
"manifestLine": claim.line,
|
|
400
|
+
}
|
|
401
|
+
)
|
|
402
|
+
)
|
|
403
|
+
reads = []
|
|
404
|
+
for position, read in enumerate(record.reads):
|
|
405
|
+
address = read.address.model_dump(mode="json") if read.address else None
|
|
406
|
+
reads.append(
|
|
407
|
+
_ref(
|
|
408
|
+
graph.add(
|
|
409
|
+
_present(
|
|
410
|
+
{
|
|
411
|
+
"@id": f"{identifier}/read/{position}",
|
|
412
|
+
"@type": ["PropertyValue", "FileRead"],
|
|
413
|
+
"name": f"{read.artifact} as read for {claim.id}",
|
|
414
|
+
"readsFile": _ref(graph.file(read)),
|
|
415
|
+
"side": read.side or None,
|
|
416
|
+
"addressKind": address["kind"] if address else None,
|
|
417
|
+
"canonicalAddress": json.dumps(
|
|
418
|
+
address, sort_keys=True, separators=(",", ":"), ensure_ascii=False
|
|
419
|
+
)
|
|
420
|
+
if address
|
|
421
|
+
else None,
|
|
422
|
+
"value": read.stored,
|
|
423
|
+
"convertedValue": read.converted,
|
|
424
|
+
}
|
|
425
|
+
)
|
|
426
|
+
)
|
|
427
|
+
)
|
|
428
|
+
)
|
|
429
|
+
execution = record.execution
|
|
430
|
+
upstream = [_ref(graph.command(command)) for command in execution.commands] if execution else []
|
|
431
|
+
stages, reader, comparison = record.stages, record.reader, record.comparison
|
|
432
|
+
tie = comparison.tie if comparison else None
|
|
433
|
+
return graph.add(
|
|
434
|
+
_present(
|
|
435
|
+
{
|
|
436
|
+
"@id": identifier,
|
|
437
|
+
"@type": ["CheckAction", "ClaimCheck"],
|
|
438
|
+
"name": " ".join(
|
|
439
|
+
part for part in (claim.id, assertion.kind, assertion.name) if part
|
|
440
|
+
),
|
|
441
|
+
"description": record.detail or None,
|
|
442
|
+
"recordVersion": record.record,
|
|
443
|
+
"instrument": _ref(checker),
|
|
444
|
+
"endTime": record.checked_at.isoformat(),
|
|
445
|
+
"manifest": _ref(manifest) if manifest else None,
|
|
446
|
+
"object": _ref(stated),
|
|
447
|
+
"assertionKind": assertion.kind,
|
|
448
|
+
"assertionName": assertion.name or None,
|
|
449
|
+
"assertionIndex": assertion.index,
|
|
450
|
+
"assertionPosition": assertion.position,
|
|
451
|
+
"manifestLine": assertion.line,
|
|
452
|
+
"passageLine": passage.line if passage else None,
|
|
453
|
+
"checkType": graph.term(record.check_type.value, _CHECK_TYPES[record.check_type]),
|
|
454
|
+
"fileRead": _packed(reads) if reads else None,
|
|
455
|
+
"printedValue": record.printed,
|
|
456
|
+
"comparisonMode": comparison.mode.value if comparison else None,
|
|
457
|
+
"tolerance": comparison.tolerance if comparison else None,
|
|
458
|
+
"declaredPlaces": comparison.places if comparison else None,
|
|
459
|
+
"conversion": comparison.conversion if comparison else None,
|
|
460
|
+
"statistic": comparison.statistic if comparison else None,
|
|
461
|
+
"memberCount": comparison.count if comparison else None,
|
|
462
|
+
"computedValue": comparison.computed if comparison else None,
|
|
463
|
+
"tieLower": tie.lower if tie else None,
|
|
464
|
+
"tieUpper": tie.upper if tie else None,
|
|
465
|
+
"tiePrinted": tie.printed if tie else None,
|
|
466
|
+
# Through `read_outcome`: a match this version does not understand leaves here
|
|
467
|
+
# as not-checked, as it leaves every exporter.
|
|
468
|
+
"outcome": graph.term(read_outcome(record).value, _OUTCOMES[read_outcome(record)]),
|
|
469
|
+
"nativeOutcome": record.native_outcome,
|
|
470
|
+
"nativeReason": record.native_reason,
|
|
471
|
+
"executionStage": stages.execution.value if stages else None,
|
|
472
|
+
"extractionStage": stages.extraction.value if stages else None,
|
|
473
|
+
"comparisonStage": stages.comparison.value if stages else None,
|
|
474
|
+
"backend": reader.backend or None,
|
|
475
|
+
"backendVersion": reader.backend_version or None,
|
|
476
|
+
"extractionTool": reader.tool or None,
|
|
477
|
+
"extractionToolVersion": reader.tool_version or None,
|
|
478
|
+
"extractionDigest": reader.extraction_digest or None,
|
|
479
|
+
"checkWarning": _packed(list(record.warnings)) if record.warnings else None,
|
|
480
|
+
"freshness": execution.state.value if execution else None,
|
|
481
|
+
"upstream": _packed(upstream) if upstream else None,
|
|
482
|
+
"historyStates": record.history.states if record.history else None,
|
|
483
|
+
"historyLastChangedAt": record.history.last_changed_at if record.history else None,
|
|
484
|
+
}
|
|
485
|
+
)
|
|
486
|
+
)
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
def to_ro_crate(records: Sequence[ExportRecord]) -> str:
|
|
490
|
+
"""The text of an `ro-crate-metadata.json` describing these records.
|
|
491
|
+
|
|
492
|
+
The crate's root is the directory the manifest is in, so a file's `@id` is the path the
|
|
493
|
+
manifest declares for it. Conformance to Process Run Crate is declared only where the
|
|
494
|
+
records hold a recorded re-run, since that profile is about runs.
|
|
495
|
+
"""
|
|
496
|
+
if not records:
|
|
497
|
+
raise NothingToExportError()
|
|
498
|
+
graph = _Graph()
|
|
499
|
+
checks = [_check(record, graph) for record in records]
|
|
500
|
+
entities = graph.entities
|
|
501
|
+
reruns = [name for name, entity in entities.items() if entity["@type"] == "CreateAction"]
|
|
502
|
+
files = [name for name, entity in entities.items() if entity["@type"] == "File"]
|
|
503
|
+
|
|
504
|
+
profiles: list[Entity] = [
|
|
505
|
+
{
|
|
506
|
+
"@id": PROFILE,
|
|
507
|
+
"@type": ["CreativeWork", "Profile"],
|
|
508
|
+
"name": "Claim check crate (experimental)",
|
|
509
|
+
"version": PROFILE_VERSION,
|
|
510
|
+
}
|
|
511
|
+
]
|
|
512
|
+
if reruns:
|
|
513
|
+
profiles.append(
|
|
514
|
+
{
|
|
515
|
+
"@id": PROCESS_RUN_CRATE,
|
|
516
|
+
"@type": ["CreativeWork", "Profile"],
|
|
517
|
+
"name": "Process Run Crate",
|
|
518
|
+
"version": "0.6",
|
|
519
|
+
}
|
|
520
|
+
)
|
|
521
|
+
manifests = sorted({record.manifest.path for record in records if record.manifest.path})
|
|
522
|
+
root = {
|
|
523
|
+
"@id": "./",
|
|
524
|
+
"@type": "Dataset",
|
|
525
|
+
"name": f"Claim checks of {', '.join(manifests) or 'a manifest held in memory'}",
|
|
526
|
+
"description": (
|
|
527
|
+
f"{len(records)} assertion(s) about pinned files, each as it was checked: the "
|
|
528
|
+
"file read, the address, the value stored there, the value reported and the "
|
|
529
|
+
"outcome. A record of comparisons, not a verdict on the claims."
|
|
530
|
+
),
|
|
531
|
+
"datePublished": max(record.checked_at for record in records).isoformat(),
|
|
532
|
+
"license": LICENSE_NOT_STATED,
|
|
533
|
+
"conformsTo": _packed([_ref(profile["@id"]) for profile in profiles]),
|
|
534
|
+
"hasPart": _packed([_ref(name) for name in sorted(files)]),
|
|
535
|
+
"mentions": _packed([_ref(name) for name in (*checks, *sorted(reruns))]),
|
|
536
|
+
}
|
|
537
|
+
descriptor = {
|
|
538
|
+
"@id": METADATA_FILE,
|
|
539
|
+
"@type": "CreativeWork",
|
|
540
|
+
"conformsTo": _ref(RO_CRATE),
|
|
541
|
+
"about": _ref("./"),
|
|
542
|
+
}
|
|
543
|
+
document = {
|
|
544
|
+
"@context": [RO_CRATE_CONTEXT, {term: f"{PROFILE}#{term}" for term in TERMS}],
|
|
545
|
+
"@graph": [descriptor, root, *profiles, *(entities[name] for name in sorted(entities))],
|
|
546
|
+
}
|
|
547
|
+
return json.dumps(document, indent=2, ensure_ascii=False) + "\n"
|
|
548
|
+
|
|
549
|
+
|
|
550
|
+
# ----------------------------------------------------------------------------- reading back
|
|
551
|
+
|
|
552
|
+
|
|
553
|
+
def _file_state(entity: Entity, entities: dict[str, Entity]) -> dict[str, Any]:
|
|
554
|
+
identifier = entity["@id"]
|
|
555
|
+
origin = entities[entity["isBasedOn"]["@id"]] if "isBasedOn" in entity else None
|
|
556
|
+
return {
|
|
557
|
+
"artifact": entity["identifier"],
|
|
558
|
+
"path": entity.get("alternateName")
|
|
559
|
+
or ("" if identifier.startswith("#") else urllib.parse.unquote(identifier)),
|
|
560
|
+
"media_type": entity.get("encodingFormat", ""),
|
|
561
|
+
"validity": entity.get("validity"),
|
|
562
|
+
"pinned": entity.get("pinnedDigest"),
|
|
563
|
+
"on_disk": entity.get("sha256"),
|
|
564
|
+
"origin": {
|
|
565
|
+
"repository": entities[origin["isPartOf"]["@id"]]["codeRepository"],
|
|
566
|
+
"commit": origin["version"],
|
|
567
|
+
"path": origin["name"],
|
|
568
|
+
}
|
|
569
|
+
if origin
|
|
570
|
+
else None,
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
def _fragment(reference: dict[str, str]) -> str:
|
|
575
|
+
return reference["@id"].removeprefix(f"{PROFILE}#")
|
|
576
|
+
|
|
577
|
+
|
|
578
|
+
def _commands(
|
|
579
|
+
check: Entity, read_artifacts: list[str], entities: dict[str, Entity]
|
|
580
|
+
) -> list[dict[str, Any]]:
|
|
581
|
+
"""The commands a check names, with how far each is from what the check reads.
|
|
582
|
+
|
|
583
|
+
A crate states the distance nowhere, because it follows from the graph: a command that
|
|
584
|
+
writes a file the check reads is at 0, and one that writes an input of a command at `n` is
|
|
585
|
+
at `n + 1`.
|
|
586
|
+
"""
|
|
587
|
+
named = [entities[ref["@id"]] for ref in _unpacked(check.get("upstream"))]
|
|
588
|
+
artifact = {
|
|
589
|
+
name: entity["identifier"] for name, entity in entities.items() if entity.get("identifier")
|
|
590
|
+
}
|
|
591
|
+
producers = {artifact[c["declaredOutput"]["@id"]]: c for c in named}
|
|
592
|
+
steps: dict[str, int] = {}
|
|
593
|
+
pending = [(producers[name], 0) for name in read_artifacts if name in producers]
|
|
594
|
+
while pending:
|
|
595
|
+
command, distance = pending.pop(0)
|
|
596
|
+
if steps.get(command["@id"], distance + 1) <= distance:
|
|
597
|
+
continue
|
|
598
|
+
steps[command["@id"]] = distance
|
|
599
|
+
for wanted in _unpacked(command.get("declaredInput")):
|
|
600
|
+
if artifact[wanted["@id"]] in producers:
|
|
601
|
+
pending.append((producers[artifact[wanted["@id"]]], distance + 1))
|
|
602
|
+
|
|
603
|
+
commands = []
|
|
604
|
+
for command in named:
|
|
605
|
+
rerun = entities[command["lastRerun"]["@id"]] if "lastRerun" in command else None
|
|
606
|
+
commands.append(
|
|
607
|
+
{
|
|
608
|
+
"id": command["identifier"],
|
|
609
|
+
"command": json.loads(command["argv"]),
|
|
610
|
+
"steps": steps[command["@id"]],
|
|
611
|
+
"output": _file_state(entities[command["declaredOutput"]["@id"]], entities),
|
|
612
|
+
"inputs": [
|
|
613
|
+
_file_state(entities[ref["@id"]], entities)
|
|
614
|
+
for ref in _unpacked(command.get("declaredInput"))
|
|
615
|
+
],
|
|
616
|
+
"state": command["freshness"],
|
|
617
|
+
"causes": _unpacked(command.get("staleCause")),
|
|
618
|
+
"last_rerun": {
|
|
619
|
+
"started_at": rerun.get("startTime", ""),
|
|
620
|
+
"ended_at": rerun.get("endTime", ""),
|
|
621
|
+
"state": rerun["rerunState"],
|
|
622
|
+
"reason": rerun["rerunReason"],
|
|
623
|
+
"checker_version": rerun.get("checkerVersion", ""),
|
|
624
|
+
"exit_code": rerun.get("exitCode"),
|
|
625
|
+
"duration_seconds": rerun.get("durationSeconds"),
|
|
626
|
+
"output_digest": rerun.get("outputDigest"),
|
|
627
|
+
}
|
|
628
|
+
if rerun
|
|
629
|
+
else None,
|
|
630
|
+
}
|
|
631
|
+
)
|
|
632
|
+
return commands
|
|
633
|
+
|
|
634
|
+
|
|
635
|
+
def from_ro_crate(text: str) -> tuple[ExportRecord, ...]:
|
|
636
|
+
"""The check records a crate written by `to_ro_crate` holds, in the order it lists them.
|
|
637
|
+
|
|
638
|
+
For a record this version understands, the inverse of `to_ro_crate`. Reads a document this
|
|
639
|
+
module wrote and makes no attempt at one written elsewhere, expanded or reshaped.
|
|
640
|
+
"""
|
|
641
|
+
try:
|
|
642
|
+
entities = {entity["@id"]: entity for entity in json.loads(text)["@graph"]}
|
|
643
|
+
root = entities["./"]
|
|
644
|
+
except (ValueError, KeyError, TypeError) as e:
|
|
645
|
+
raise NotAClaimCheckCrateError(f"no flattened graph with a root data entity: {e}") from e
|
|
646
|
+
if PROFILE not in [ref["@id"] for ref in _unpacked(root.get("conformsTo"))]:
|
|
647
|
+
raise NotAClaimCheckCrateError(f"the root data entity does not conform to {PROFILE}")
|
|
648
|
+
|
|
649
|
+
checks = [
|
|
650
|
+
entities[ref["@id"]]
|
|
651
|
+
for ref in _unpacked(root.get("mentions"))
|
|
652
|
+
if "ClaimCheck" in _unpacked(entities[ref["@id"]]["@type"])
|
|
653
|
+
]
|
|
654
|
+
passages: dict[str, list[dict[str, Any]]] = {}
|
|
655
|
+
for check in checks:
|
|
656
|
+
if check["assertionKind"] == "quote":
|
|
657
|
+
read = entities[_unpacked(check["fileRead"])[0]["@id"]]
|
|
658
|
+
file = _file_state(entities[read["readsFile"]["@id"]], entities)
|
|
659
|
+
passages.setdefault(check["object"]["@id"], []).append(
|
|
660
|
+
{
|
|
661
|
+
"assertion": check["assertionIndex"],
|
|
662
|
+
"artifact": file["artifact"],
|
|
663
|
+
"path": file["path"],
|
|
664
|
+
"text": check["printedValue"],
|
|
665
|
+
"line": check.get("passageLine"),
|
|
666
|
+
}
|
|
667
|
+
)
|
|
668
|
+
|
|
669
|
+
records = []
|
|
670
|
+
for check in checks:
|
|
671
|
+
claim, checker = entities[check["object"]["@id"]], entities[check["instrument"]["@id"]]
|
|
672
|
+
manifest = entities[check["manifest"]["@id"]] if "manifest" in check else None
|
|
673
|
+
reads: list[dict[str, Any]] = []
|
|
674
|
+
for ref in _unpacked(check.get("fileRead")):
|
|
675
|
+
read = entities[ref["@id"]]
|
|
676
|
+
reads.append(
|
|
677
|
+
{
|
|
678
|
+
**_file_state(entities[read["readsFile"]["@id"]], entities),
|
|
679
|
+
"side": read.get("side", ""),
|
|
680
|
+
"address": json.loads(read["canonicalAddress"])
|
|
681
|
+
if "canonicalAddress" in read
|
|
682
|
+
else None,
|
|
683
|
+
"stored": read.get("value"),
|
|
684
|
+
"converted": read.get("convertedValue"),
|
|
685
|
+
}
|
|
686
|
+
)
|
|
687
|
+
commands = _commands(check, [read["artifact"] for read in reads], entities)
|
|
688
|
+
records.append(
|
|
689
|
+
ExportRecord.model_validate(
|
|
690
|
+
{
|
|
691
|
+
"record": check["recordVersion"],
|
|
692
|
+
"checker": {
|
|
693
|
+
"name": checker["name"],
|
|
694
|
+
"version": checker["version"],
|
|
695
|
+
"url": checker.get("url", ""),
|
|
696
|
+
},
|
|
697
|
+
"checked_at": check["endTime"],
|
|
698
|
+
"manifest": {
|
|
699
|
+
"path": manifest.get("alternateName")
|
|
700
|
+
or urllib.parse.unquote(manifest["@id"]),
|
|
701
|
+
"digest": manifest.get("sha256"),
|
|
702
|
+
}
|
|
703
|
+
if manifest
|
|
704
|
+
else {},
|
|
705
|
+
"claim": {
|
|
706
|
+
"id": claim["identifier"],
|
|
707
|
+
"text": claim["text"],
|
|
708
|
+
"where": claim.get("whereStated"),
|
|
709
|
+
"digest": claim["claimDigest"],
|
|
710
|
+
"line": claim.get("manifestLine"),
|
|
711
|
+
"passages": passages.get(claim["@id"], []),
|
|
712
|
+
},
|
|
713
|
+
"assertion": {
|
|
714
|
+
"kind": check["assertionKind"],
|
|
715
|
+
"name": check.get("assertionName", ""),
|
|
716
|
+
"index": check["assertionIndex"],
|
|
717
|
+
"position": check["assertionPosition"],
|
|
718
|
+
"line": check.get("manifestLine"),
|
|
719
|
+
},
|
|
720
|
+
"check_type": _fragment(check["checkType"]),
|
|
721
|
+
"reads": reads,
|
|
722
|
+
"printed": check.get("printedValue"),
|
|
723
|
+
"comparison": {
|
|
724
|
+
"mode": check["comparisonMode"],
|
|
725
|
+
"tolerance": check["tolerance"],
|
|
726
|
+
"places": check.get("declaredPlaces"),
|
|
727
|
+
"conversion": check.get("conversion"),
|
|
728
|
+
"statistic": check.get("statistic"),
|
|
729
|
+
"count": check.get("memberCount"),
|
|
730
|
+
"computed": check.get("computedValue"),
|
|
731
|
+
"tie": {
|
|
732
|
+
"lower": check["tieLower"],
|
|
733
|
+
"upper": check["tieUpper"],
|
|
734
|
+
"printed": check["tiePrinted"],
|
|
735
|
+
}
|
|
736
|
+
if "tieLower" in check
|
|
737
|
+
else None,
|
|
738
|
+
}
|
|
739
|
+
if "comparisonMode" in check
|
|
740
|
+
else None,
|
|
741
|
+
"outcome": _fragment(check["outcome"]),
|
|
742
|
+
"native_outcome": check["nativeOutcome"],
|
|
743
|
+
"native_reason": check["nativeReason"],
|
|
744
|
+
"detail": check.get("description", ""),
|
|
745
|
+
"stages": {
|
|
746
|
+
"execution": check["executionStage"],
|
|
747
|
+
"extraction": check["extractionStage"],
|
|
748
|
+
"comparison": check["comparisonStage"],
|
|
749
|
+
}
|
|
750
|
+
if "executionStage" in check
|
|
751
|
+
else None,
|
|
752
|
+
"reader": {
|
|
753
|
+
"backend": check.get("backend", ""),
|
|
754
|
+
"backend_version": check.get("backendVersion", ""),
|
|
755
|
+
"tool": check.get("extractionTool", ""),
|
|
756
|
+
"tool_version": check.get("extractionToolVersion", ""),
|
|
757
|
+
"extraction_digest": check.get("extractionDigest", ""),
|
|
758
|
+
},
|
|
759
|
+
"warnings": _unpacked(check.get("checkWarning")),
|
|
760
|
+
"execution": {"state": check["freshness"], "commands": commands}
|
|
761
|
+
if commands
|
|
762
|
+
else None,
|
|
763
|
+
"history": {
|
|
764
|
+
"states": check["historyStates"],
|
|
765
|
+
"last_changed_at": check.get("historyLastChangedAt"),
|
|
766
|
+
}
|
|
767
|
+
if "historyStates" in check
|
|
768
|
+
else None,
|
|
769
|
+
}
|
|
770
|
+
)
|
|
771
|
+
)
|
|
772
|
+
return tuple(records)
|
|
773
|
+
|
|
774
|
+
|
|
775
|
+
__all__ = [
|
|
776
|
+
"METADATA_FILE",
|
|
777
|
+
"PROCESS_RUN_CRATE",
|
|
778
|
+
"PROFILE",
|
|
779
|
+
"PROFILE_VERSION",
|
|
780
|
+
"RO_CRATE",
|
|
781
|
+
"TERMS",
|
|
782
|
+
"ConflictingRecordsError",
|
|
783
|
+
"NotAClaimCheckCrateError",
|
|
784
|
+
"NothingToExportError",
|
|
785
|
+
"from_ro_crate",
|
|
786
|
+
"to_ro_crate",
|
|
787
|
+
]
|