opdev 0.7.0a2__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.
- opdev/__init__.py +1 -0
- opdev/__main__.py +3 -0
- opdev/checks.py +300 -0
- opdev/cli.py +459 -0
- opdev/commands.py +76 -0
- opdev/config.py +278 -0
- opdev/document_catalog.py +107 -0
- opdev/document_review.py +115 -0
- opdev/documents.py +415 -0
- opdev/errors.py +5 -0
- opdev/files.py +82 -0
- opdev/init.py +87 -0
- opdev/junit.py +99 -0
- opdev/output.py +141 -0
- opdev/process.py +145 -0
- opdev/providers/__init__.py +1 -0
- opdev/providers/gitlab.py +374 -0
- opdev/publication.py +209 -0
- opdev/reports.py +512 -0
- opdev/requirements.py +642 -0
- opdev/resources/reports/report.css +158 -0
- opdev/resources/reports/report.html +27 -0
- opdev/resources/reports/report.js +110 -0
- opdev/resources/skills/opdev/SKILL.md +190 -0
- opdev/resources/skills/opdev/references/adoption.md +144 -0
- opdev/resources/skills/opdev/references/design.md +141 -0
- opdev/resources/skills/opdev/references/development.md +294 -0
- opdev/resources/skills/opdev/references/engineering.md +206 -0
- opdev/resources/skills/opdev/references/planning.md +101 -0
- opdev/resources/skills/opdev/references/publication.md +34 -0
- opdev/resources/templates/AGENTS.md +7 -0
- opdev/resources/templates/CLAUDE.md +6 -0
- opdev/resources/templates/guidance.md +36 -0
- opdev/snapshot.py +484 -0
- opdev/tracking.py +224 -0
- opdev/verification.py +234 -0
- opdev/version.py +45 -0
- opdev-0.7.0a2.dist-info/METADATA +99 -0
- opdev-0.7.0a2.dist-info/RECORD +42 -0
- opdev-0.7.0a2.dist-info/WHEEL +4 -0
- opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
- opdev-0.7.0a2.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Plan useful increments and bounded issues
|
|
2
|
+
|
|
3
|
+
Start from the accepted product, interface and technical decisions. Resolve
|
|
4
|
+
consequential open decisions with the developer unless they explicitly delegated
|
|
5
|
+
them. Do not use roadmap approval as a substitute for technical approval.
|
|
6
|
+
|
|
7
|
+
Propose a phased path to the whole accepted outcome. Make an early milestone a
|
|
8
|
+
usable end-to-end MVP, followed by useful increments; avoid plans composed only
|
|
9
|
+
of disconnected technical layers. Every milestone needs an outcome, scope,
|
|
10
|
+
dependencies and a concrete completion demonstration, including later milestones.
|
|
11
|
+
The expected result names an observable product effect, not "implemented and tested".
|
|
12
|
+
The demonstration action is something a user or caller does with the product, not
|
|
13
|
+
the developer's activity of implementing or testing it. Even a later milestone must
|
|
14
|
+
show the input reaching its intended visible destination or result.
|
|
15
|
+
Distinguish accepted later work from optional ideas; don't silently discard or
|
|
16
|
+
promote either. Recommend scope cuts as choices, not decisions already made.
|
|
17
|
+
Later milestones can demonstrate user-visible outcomes without freezing future
|
|
18
|
+
commands, formats or internal APIs. Mark those implementation details as proposed
|
|
19
|
+
or unresolved; an accepted outcome does not approve an unspecified contract.
|
|
20
|
+
When saying a technical detail is approved, name its actual selected value and
|
|
21
|
+
where that decision was accepted. Without both, leave that detail pending. An
|
|
22
|
+
accepted document can explicitly defer decisions; preserve those open choices in
|
|
23
|
+
the proposal instead of treating document acceptance as approval of their answers.
|
|
24
|
+
|
|
25
|
+
Obtain acceptance of the roadmap, reusing genuine prior acceptance. When tracker
|
|
26
|
+
access and writes are authorized, materialize all accepted phases and milestones
|
|
27
|
+
through `opdev phase` and `opdev milestone`. Missing access or a planning-only request
|
|
28
|
+
blocks saving, not issue planning: refer to accepted unsaved milestones by title in
|
|
29
|
+
the proposal. Provider IDs are assigned when saved; do not ask for an ID that does
|
|
30
|
+
not exist. Use observed IDs for existing records and resolve membership before writes.
|
|
31
|
+
Use stable creation keys, inspect existing records, and reconcile uncertain creates
|
|
32
|
+
before retrying. A reset or interrupted tracker setup is not permission to create
|
|
33
|
+
a second roadmap. Keep tracker-native records authoritative, not a repo checklist.
|
|
34
|
+
Use the [tracker identity rules](development.md#tracker-identities) when naming
|
|
35
|
+
existing work or distinguishing proposed renames from current titles.
|
|
36
|
+
|
|
37
|
+
Before starting **each** milestone, lead an issue-planning discussion. Define bounded
|
|
38
|
+
issues with an observable outcome, scope/exclusions, acceptance demonstration,
|
|
39
|
+
relevant requirement IDs and dependencies. An issue should be a reviewable slice,
|
|
40
|
+
not "implement the whole MVP" with all implementation hidden inside it. Plan the
|
|
41
|
+
next milestone's issues in detail when it becomes current; don't freeze every future
|
|
42
|
+
task prematurely. Ask about unresolved design decisions before dependent issues.
|
|
43
|
+
|
|
44
|
+
Build the acceptance demonstration before finalizing an issue's scope. Use this
|
|
45
|
+
small worksheet **inside the issue proposal**, not a new repository document:
|
|
46
|
+
|
|
47
|
+
- **Setup:** exact inputs, empty/seeded state and how every process selects that state.
|
|
48
|
+
- **Action:** the literal command/API call or precise user interaction. Preserve
|
|
49
|
+
argument boundaries: quote multiword arguments or give a literal argument vector.
|
|
50
|
+
- **Observation:** a separate literal read/query/assertion or visible interaction,
|
|
51
|
+
with its expected value. Name the operation, arguments and any schema it uses.
|
|
52
|
+
- **Capability owners:** for each action and observation, name the existing contract,
|
|
53
|
+
this issue's concrete proposed contract, or a declared prerequisite issue's contract.
|
|
54
|
+
Put a proposed signature/schema in this issue's scope before using it in the example.
|
|
55
|
+
Existing means implemented and available now; an accepted but unimplemented
|
|
56
|
+
interface is supplied by this issue or a declared prerequisite, not by approval.
|
|
57
|
+
- **Failure witness:** what this observation shows if the feature is a no-op or loses
|
|
58
|
+
the promised state. A success message/exit code is not evidence of a saved effect.
|
|
59
|
+
|
|
60
|
+
For example, an issue adding `notes save TEXT` could propose `notes(body TEXT)` in
|
|
61
|
+
`notes.sqlite3` under the current directory. Its demonstration starts in a new empty
|
|
62
|
+
directory, runs `notes save "alpha beta"`, then runs a **separate Python process** there:
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
import sqlite3
|
|
66
|
+
|
|
67
|
+
with sqlite3.connect("notes.sqlite3") as connection:
|
|
68
|
+
assert connection.execute("SELECT body FROM notes").fetchall() == [("alpha beta",)]
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Here this issue supplies the save command and table; the selected SQLite/Python
|
|
72
|
+
runtime supplies the query. A no-op save yields no table/row and fails the assertion.
|
|
73
|
+
The later `notes list` command is unnecessary. This is an example of making a
|
|
74
|
+
boundary concrete, not a required technology or permission to change a chosen schema.
|
|
75
|
+
For a UI, specify the exact screen/element and visible value; for an API, its actual
|
|
76
|
+
request and returned value. "Inspect storage", "use the proposed API" or "verify it
|
|
77
|
+
works" leaves the observation unwritten. Replace that placeholder before presenting
|
|
78
|
+
an issue as ready; don't simply add a promise to define it during implementation.
|
|
79
|
+
|
|
80
|
+
Walk the worksheet against the proposed dependency order. Every operation needs its
|
|
81
|
+
named owner available at that boundary; a later issue cannot supply it. Dependencies
|
|
82
|
+
supply capabilities, not leftover data from their examples. Each demonstration
|
|
83
|
+
creates its own state. Keep one bounded outcome per issue, repair missing boundaries
|
|
84
|
+
or reslice dependencies, and keep new interfaces explicitly proposed. A remaining
|
|
85
|
+
consequential decision goes to the developer unless delegated; don't invent approval.
|
|
86
|
+
This is part of constructing the same proposal, not a separate approval stage.
|
|
87
|
+
|
|
88
|
+
Use existing authorization to materialize and execute the accepted plan; don't
|
|
89
|
+
re-request permission for every issue when the developer authorized the milestone.
|
|
90
|
+
Roadmap acceptance alone does not necessarily authorize implementation. When intent
|
|
91
|
+
is unclear, ask once about the scope of execution. Keep implementation plans and
|
|
92
|
+
progress in the configured tracker. Requirements are enduring product promises,
|
|
93
|
+
not copied issue text or milestones masquerading as requirements.
|
|
94
|
+
|
|
95
|
+
After issue planning and authorization, use that issue as the
|
|
96
|
+
[change brief](development.md#change-brief-and-checkpoint) and move to development.
|
|
97
|
+
The brief reuses the accepted scope and demonstrations; it is not another planning artifact.
|
|
98
|
+
When asked "what next?", identify the next unresolved decision or useful milestone
|
|
99
|
+
from the current accepted plan; do not invent a fresh plan or automatically publish.
|
|
100
|
+
For additions or changed direction during implementation, reconcile only affected
|
|
101
|
+
scope through [Changing direction](development.md#changing-direction).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Separately authorized publication
|
|
2
|
+
|
|
3
|
+
Establish the actual requested release scope and destination. Implementation
|
|
4
|
+
completion, green CI, milestone acceptance and an existing publication command
|
|
5
|
+
do not grant authority. Reuse explicit authority already given for this release;
|
|
6
|
+
do not ask again for actions within that scope. Prepare reviewable work before
|
|
7
|
+
asking about a genuinely unresolved release decision. Do not choose a version,
|
|
8
|
+
tag, deploy or migrate consumers as an implied side effect.
|
|
9
|
+
|
|
10
|
+
The protected integration rule also applies to release/version commits and
|
|
11
|
+
publisher automation. Complete those changes through a work branch and merge/pull
|
|
12
|
+
request first. Inspect configured publisher behavior for direct integration-branch
|
|
13
|
+
updates; release approval does not authorize them or weakening branch protections.
|
|
14
|
+
A local-only artifact exercise does not establish a hosted merge gate.
|
|
15
|
+
|
|
16
|
+
Use the project's established build/publishing tools and native services. OpDev
|
|
17
|
+
does not manage user documentation or choose a release platform. Inspect
|
|
18
|
+
`opdev publish --plan`, verify the selected fixed prebuilt inputs and destination,
|
|
19
|
+
and build separately with `opdev build` where configured. Never rebuild artifacts
|
|
20
|
+
inside the publisher after their verification. Do not place credentials in config,
|
|
21
|
+
logs or committed files; use the project's authorized credential mechanism.
|
|
22
|
+
|
|
23
|
+
`opdev publish` requires valid fixed-catalog document structure and clean committed
|
|
24
|
+
Git source, runs fresh required checks and
|
|
25
|
+
publication prerequisites, requires complete active direct-test verification, and refuses changed inputs before invoking the configured
|
|
26
|
+
publisher. It does not authenticate consent or make external effects atomic.
|
|
27
|
+
Never bypass its refusal with a direct publisher merely to obtain success.
|
|
28
|
+
|
|
29
|
+
After publication, inspect the destination through its normal read-only interface.
|
|
30
|
+
A successful command is not independent proof of delivery. On an uncertain,
|
|
31
|
+
interrupted or partial outcome, reconcile the destination before any retry.
|
|
32
|
+
Report precisely what was published and what remains unknown. Record completion in
|
|
33
|
+
the tracker, not a local evidence ledger. Updating a consumer's runtime/plugin or
|
|
34
|
+
changing a managed pin remains within scope only when explicitly authorized.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
<!-- opdev:start -->
|
|
2
|
+
For substantive software work in this initialized project, read `.opdev/guidance.md`
|
|
3
|
+
and `.opdev/project.yaml`, including after a context reset. Use the installed OpDev
|
|
4
|
+
skill and selected runtime; if missing, inform the developer and offer setup.
|
|
5
|
+
Routine pulls, status and dev servers do not activate the workflow. Do not silently
|
|
6
|
+
install, upgrade or replace project decisions.
|
|
7
|
+
<!-- opdev:end -->
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# This project's OpDev entry point
|
|
2
|
+
|
|
3
|
+
## Workflow
|
|
4
|
+
|
|
5
|
+
Use the installed OpDev skill for reusable workflow procedures. After a context
|
|
6
|
+
reset, reload this guide and `.opdev/project.yaml`, then read only the procedure
|
|
7
|
+
and project decisions needed for the current task. Use focused feedback while
|
|
8
|
+
iterating; the selected workflow explains integration and separate publication.
|
|
9
|
+
|
|
10
|
+
Use the developer-selected Python runtime and a matching OpDev plugin. If either
|
|
11
|
+
is absent or incompatible, tell the developer and offer setup or repair. Do not
|
|
12
|
+
silently install, substitute the retired Rust tool or change project decisions.
|
|
13
|
+
Independent discussion can continue while tool-dependent work is blocked.
|
|
14
|
+
|
|
15
|
+
Keep project-specific instructions here. Generic procedures belong in the plugin;
|
|
16
|
+
upgrades do not approve or overwrite this project's decisions.
|
|
17
|
+
|
|
18
|
+
## Project routes
|
|
19
|
+
|
|
20
|
+
The runtime owns the fixed document catalog. Project configuration owns commands,
|
|
21
|
+
optional technical-role selection and tracking. Read only the relevant owners:
|
|
22
|
+
|
|
23
|
+
- Product direction: [design](design.md).
|
|
24
|
+
- Observable behavior: [interface](interface.md).
|
|
25
|
+
- Languages, tools and platform: [stack](technical/stack.md).
|
|
26
|
+
- Architectural decisions and rationale: [architecture](technical/architecture.md).
|
|
27
|
+
- Coding conventions and native enforcement: [standards](technical/standards.md).
|
|
28
|
+
- Test strategy and integration boundaries: [verification](technical/verification.md).
|
|
29
|
+
|
|
30
|
+
Read optional technical roles only when selected in project.yaml and relevant to
|
|
31
|
+
the task. Requirements and their test mappings live in `.opdev/requirements.json`;
|
|
32
|
+
query affected records through the CLI. Work progress lives in the configured
|
|
33
|
+
tracker. User-facing documentation remains developer-owned.
|
|
34
|
+
|
|
35
|
+
Initialization supplies this routing entry point, not substantive accepted project
|
|
36
|
+
decisions. Missing or unresolved designs remain incomplete until reviewed.
|
opdev/snapshot.py
ADDED
|
@@ -0,0 +1,484 @@
|
|
|
1
|
+
"""Explicit, bounded run snapshots. No ledger, test execution or report uploads."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import math
|
|
7
|
+
import re
|
|
8
|
+
from collections import Counter
|
|
9
|
+
from dataclasses import asdict
|
|
10
|
+
from datetime import UTC, datetime
|
|
11
|
+
from pathlib import Path, PurePosixPath, PureWindowsPath
|
|
12
|
+
from typing import TYPE_CHECKING, Any
|
|
13
|
+
from uuid import uuid4
|
|
14
|
+
|
|
15
|
+
from opdev.config import PURPOSES, Command, Project
|
|
16
|
+
from opdev.errors import OpDevError
|
|
17
|
+
from opdev.files import contained_path, read_optional, read_regular, regular_path
|
|
18
|
+
from opdev.junit import Case
|
|
19
|
+
from opdev.requirements import (
|
|
20
|
+
STORE,
|
|
21
|
+
Database,
|
|
22
|
+
decode,
|
|
23
|
+
invalid_constant,
|
|
24
|
+
load,
|
|
25
|
+
object_fields,
|
|
26
|
+
revision,
|
|
27
|
+
unique_object,
|
|
28
|
+
)
|
|
29
|
+
from opdev.verification import TestResults, assess
|
|
30
|
+
from opdev.version import identity
|
|
31
|
+
|
|
32
|
+
if TYPE_CHECKING:
|
|
33
|
+
from opdev.checks import CheckReport
|
|
34
|
+
|
|
35
|
+
SCHEMA = "opdev-report/3"
|
|
36
|
+
PREVIOUS_SCHEMA = "opdev-report/2"
|
|
37
|
+
LEGACY_SCHEMA = "opdev-report/1"
|
|
38
|
+
MAX_BYTES = 20 * 1024 * 1024
|
|
39
|
+
COMMAND_STATES = {
|
|
40
|
+
"passed",
|
|
41
|
+
"failed",
|
|
42
|
+
"error",
|
|
43
|
+
"timed_out",
|
|
44
|
+
"interrupted",
|
|
45
|
+
"not_run",
|
|
46
|
+
"not_selected",
|
|
47
|
+
}
|
|
48
|
+
CASE_STATES = {"passed", "failed", "error", "skipped", "ambiguous"}
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def destination(path: Path) -> Path:
|
|
52
|
+
path = path.absolute()
|
|
53
|
+
regular_path(path)
|
|
54
|
+
if any(part.casefold() in {".git", ".opdev"} for part in path.parts):
|
|
55
|
+
raise OpDevError(
|
|
56
|
+
"Reports belong outside .git and .opdev; choose an artifact/output location."
|
|
57
|
+
)
|
|
58
|
+
if path.exists() or not path.parent.is_dir():
|
|
59
|
+
raise OpDevError(
|
|
60
|
+
"Report output must be a new file in an existing directory; nothing overwritten."
|
|
61
|
+
)
|
|
62
|
+
return path
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def save(path: Path, content: str) -> None:
|
|
66
|
+
data = content.encode("utf-8")
|
|
67
|
+
if len(data) > 64 * 1024 * 1024:
|
|
68
|
+
raise OpDevError("Report output exceeds 64 MiB; no report written.")
|
|
69
|
+
destination(path)
|
|
70
|
+
try:
|
|
71
|
+
with path.open("xb") as stream:
|
|
72
|
+
stream.write(data)
|
|
73
|
+
except (OSError, KeyboardInterrupt) as exc:
|
|
74
|
+
raise OpDevError(
|
|
75
|
+
"Report write did not complete; inspect the destination before retrying. "
|
|
76
|
+
"Any preceding checks may already have run."
|
|
77
|
+
) from exc
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class Capture:
|
|
81
|
+
def __init__(self, project: Project, path: Path):
|
|
82
|
+
self.path = destination(path)
|
|
83
|
+
self.project = project
|
|
84
|
+
self.database, self.raw = load(project)
|
|
85
|
+
self.started = datetime.now(UTC).isoformat()
|
|
86
|
+
self.tool = identity()
|
|
87
|
+
self.run_id = str(uuid4())
|
|
88
|
+
|
|
89
|
+
def finish(self, report: CheckReport) -> None:
|
|
90
|
+
try:
|
|
91
|
+
current = (
|
|
92
|
+
self.project.unchanged()
|
|
93
|
+
and read_optional(contained_path(self.project.root, STORE)) == self.raw
|
|
94
|
+
and report.document_inputs_unchanged
|
|
95
|
+
)
|
|
96
|
+
except (OSError, OpDevError):
|
|
97
|
+
current = False
|
|
98
|
+
if not current:
|
|
99
|
+
report.status, report.full_check_passed = "error", False
|
|
100
|
+
report.requirements = []
|
|
101
|
+
report.verification = assess(
|
|
102
|
+
self.database, {}, catalog_present=self.raw is not None, inputs_unchanged=False
|
|
103
|
+
)
|
|
104
|
+
report.detail = (
|
|
105
|
+
"Configuration, mappings or documents changed; snapshot cannot verify requirements."
|
|
106
|
+
)
|
|
107
|
+
# Retain authored obligations, not machine paths, source URLs or raw diagnostics.
|
|
108
|
+
catalog = json.loads(self.database.encode())
|
|
109
|
+
for req in catalog["requirements"].values():
|
|
110
|
+
req["sources"] = []
|
|
111
|
+
for test in catalog["tests"].values():
|
|
112
|
+
location = test["location"]
|
|
113
|
+
if PurePosixPath(location).is_absolute() or PureWindowsPath(location).anchor:
|
|
114
|
+
test["location"] = "Absolute location omitted"
|
|
115
|
+
ran = {item.id: item for item in report.checks}
|
|
116
|
+
commands = []
|
|
117
|
+
for name, command in self.project.commands.items():
|
|
118
|
+
item = ran.get(name)
|
|
119
|
+
results = asdict(item.test_results) if item and item.test_results else None
|
|
120
|
+
if results is not None:
|
|
121
|
+
results.pop("detail")
|
|
122
|
+
results.pop(
|
|
123
|
+
"mappings"
|
|
124
|
+
) # Derive from the captured catalog, never duplicate judgments.
|
|
125
|
+
commands.append(
|
|
126
|
+
{
|
|
127
|
+
"id": name,
|
|
128
|
+
"purpose": command.purpose,
|
|
129
|
+
"required": name in self.project.checks,
|
|
130
|
+
"selected": item is not None,
|
|
131
|
+
"results": command.results,
|
|
132
|
+
"status": item.status if item else "not_selected",
|
|
133
|
+
"exit_code": item.exit_code if item else None,
|
|
134
|
+
"duration_seconds": item.duration_seconds if item else 0.0,
|
|
135
|
+
"test_results": results,
|
|
136
|
+
}
|
|
137
|
+
)
|
|
138
|
+
data = {
|
|
139
|
+
"schema": SCHEMA,
|
|
140
|
+
"run_id": self.run_id,
|
|
141
|
+
"tool": self.tool,
|
|
142
|
+
"started_at": self.started,
|
|
143
|
+
"finished_at": datetime.now(UTC).isoformat(),
|
|
144
|
+
"operation": report.operation,
|
|
145
|
+
"scope": report.scope,
|
|
146
|
+
"status": report.status,
|
|
147
|
+
"full_check_passed": report.full_check_passed,
|
|
148
|
+
"inputs_unchanged": current,
|
|
149
|
+
"config_sha256": self.project.digest,
|
|
150
|
+
"requirements_revision": revision(self.raw),
|
|
151
|
+
"source_binding": "not_captured",
|
|
152
|
+
"commands": commands,
|
|
153
|
+
"catalog": catalog,
|
|
154
|
+
"documents": {
|
|
155
|
+
"status": report.documents["status"] if report.documents else "not_run",
|
|
156
|
+
"input_sha256": report.documents["input_sha256"] if report.documents else None,
|
|
157
|
+
"findings": report.documents["findings"] if report.documents else [],
|
|
158
|
+
},
|
|
159
|
+
}
|
|
160
|
+
raw = json.dumps(data, ensure_ascii=True, indent=2) + "\n"
|
|
161
|
+
try:
|
|
162
|
+
validate(raw.encode())
|
|
163
|
+
save(self.path, raw)
|
|
164
|
+
except (OpDevError, OSError) as exc:
|
|
165
|
+
raise OpDevError(
|
|
166
|
+
"Snapshot export failed. Checks may already have run; inspect this "
|
|
167
|
+
f"invocation's output and destination before retrying. {exc}"
|
|
168
|
+
) from exc
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def validate(
|
|
172
|
+
raw: bytes,
|
|
173
|
+
) -> tuple[dict[str, Any], Database, dict[str, tuple[str, TestResults | None]]]:
|
|
174
|
+
"""Validate stored observations without reading the checkout or trusting derived claims."""
|
|
175
|
+
if len(raw) > MAX_BYTES:
|
|
176
|
+
raise OpDevError("Snapshot exceeds 20 MiB.")
|
|
177
|
+
try:
|
|
178
|
+
data = json.loads(
|
|
179
|
+
raw.decode("utf-8"), object_pairs_hook=unique_object, parse_constant=invalid_constant
|
|
180
|
+
)
|
|
181
|
+
if not isinstance(data, dict):
|
|
182
|
+
raise ValueError("Report snapshot must be a JSON object")
|
|
183
|
+
data = object_fields(
|
|
184
|
+
data,
|
|
185
|
+
{
|
|
186
|
+
"schema",
|
|
187
|
+
"run_id",
|
|
188
|
+
"tool",
|
|
189
|
+
"started_at",
|
|
190
|
+
"finished_at",
|
|
191
|
+
"operation",
|
|
192
|
+
"scope",
|
|
193
|
+
"status",
|
|
194
|
+
"full_check_passed",
|
|
195
|
+
"inputs_unchanged",
|
|
196
|
+
"config_sha256",
|
|
197
|
+
"requirements_revision",
|
|
198
|
+
"source_binding",
|
|
199
|
+
"commands",
|
|
200
|
+
"catalog",
|
|
201
|
+
*({"documents"} if data.get("schema") == SCHEMA else set()),
|
|
202
|
+
},
|
|
203
|
+
"report snapshot",
|
|
204
|
+
)
|
|
205
|
+
_validate_identity(data)
|
|
206
|
+
_validate_run_context(data)
|
|
207
|
+
_validate_documents(data)
|
|
208
|
+
declared = _decode_inventory(data)
|
|
209
|
+
database = _decode_catalog(data, declared)
|
|
210
|
+
outcomes = _decode_outcomes(data, database)
|
|
211
|
+
_validate_outcomes(data, database, outcomes)
|
|
212
|
+
return data, database, outcomes
|
|
213
|
+
except (TypeError, KeyError, ValueError, RecursionError, UnicodeError, OverflowError) as exc:
|
|
214
|
+
raise OpDevError(
|
|
215
|
+
f"Invalid report snapshot: {exc}. Capture with opdev check --report FILE."
|
|
216
|
+
) from exc
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _validate_identity(data: dict[str, Any]) -> None:
|
|
220
|
+
if (
|
|
221
|
+
data["schema"] not in {SCHEMA, PREVIOUS_SCHEMA, LEGACY_SCHEMA}
|
|
222
|
+
or data["source_binding"] != "not_captured"
|
|
223
|
+
):
|
|
224
|
+
raise ValueError("Unsupported snapshot format or source binding")
|
|
225
|
+
if not isinstance(data["run_id"], str) or not re.fullmatch(r"[a-f0-9-]{36}", data["run_id"]):
|
|
226
|
+
raise ValueError("Invalid run identity")
|
|
227
|
+
tool = object_fields(data["tool"], {"implementation", "version", "workflow_sha256"}, "tool")
|
|
228
|
+
if (
|
|
229
|
+
tool["implementation"] != "python"
|
|
230
|
+
or not isinstance(tool["version"], str)
|
|
231
|
+
or not 1 <= len(tool["version"]) <= 128
|
|
232
|
+
):
|
|
233
|
+
raise ValueError("Invalid tool identity")
|
|
234
|
+
for value in (data["config_sha256"], tool["workflow_sha256"]):
|
|
235
|
+
if not isinstance(value, str) or not re.fullmatch(r"[a-f0-9]{64}", value):
|
|
236
|
+
raise ValueError("Invalid input fingerprint")
|
|
237
|
+
if not isinstance(data["requirements_revision"], str) or not re.fullmatch(
|
|
238
|
+
r"absent|[a-f0-9]{64}", data["requirements_revision"]
|
|
239
|
+
):
|
|
240
|
+
raise ValueError("Invalid requirements revision")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def _validate_run_context(data: dict[str, Any]) -> None:
|
|
244
|
+
times = [datetime.fromisoformat(data[k]) for k in ("started_at", "finished_at")]
|
|
245
|
+
if any(t.tzinfo is None for t in times) or times[1] < times[0]:
|
|
246
|
+
raise ValueError("Invalid run times")
|
|
247
|
+
if data["operation"] not in {"check", "test"} or data["scope"] not in {
|
|
248
|
+
"full",
|
|
249
|
+
"focused",
|
|
250
|
+
"test",
|
|
251
|
+
}:
|
|
252
|
+
raise ValueError("Unsupported operation/scope")
|
|
253
|
+
if (data["operation"] == "test") != (data["scope"] == "test"):
|
|
254
|
+
raise ValueError("Operation/scope disagree")
|
|
255
|
+
if data["status"] not in (COMMAND_STATES - {"not_run", "not_selected"}) | (
|
|
256
|
+
{"incomplete"} if data["schema"] != LEGACY_SCHEMA else set()
|
|
257
|
+
):
|
|
258
|
+
raise ValueError("Invalid run outcome")
|
|
259
|
+
if type(data["inputs_unchanged"]) is not bool or type(data["full_check_passed"]) is not bool:
|
|
260
|
+
raise ValueError("Invalid verification flags")
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def _decode_command(item: Any, declared: dict[str, Command]) -> tuple[str, Command]:
|
|
264
|
+
item = object_fields(
|
|
265
|
+
item,
|
|
266
|
+
{
|
|
267
|
+
"id",
|
|
268
|
+
"purpose",
|
|
269
|
+
"required",
|
|
270
|
+
"selected",
|
|
271
|
+
"results",
|
|
272
|
+
"status",
|
|
273
|
+
"exit_code",
|
|
274
|
+
"duration_seconds",
|
|
275
|
+
"test_results",
|
|
276
|
+
},
|
|
277
|
+
"command",
|
|
278
|
+
)
|
|
279
|
+
key = item["id"]
|
|
280
|
+
if (
|
|
281
|
+
not isinstance(key, str)
|
|
282
|
+
or not re.fullmatch(r"[a-z][a-z0-9_-]{0,63}", key)
|
|
283
|
+
or key in declared
|
|
284
|
+
):
|
|
285
|
+
raise ValueError("Invalid/duplicate command identity")
|
|
286
|
+
if item["purpose"] not in PURPOSES or item["results"] not in {None, "junit"}:
|
|
287
|
+
raise ValueError("Invalid command role/results")
|
|
288
|
+
if any(type(item[k]) is not bool for k in ("required", "selected")):
|
|
289
|
+
raise ValueError("Invalid command selection")
|
|
290
|
+
if (
|
|
291
|
+
item["status"] not in COMMAND_STATES
|
|
292
|
+
or (item["status"] == "not_selected") == item["selected"]
|
|
293
|
+
):
|
|
294
|
+
raise ValueError("Command status/selection disagree")
|
|
295
|
+
if item["exit_code"] is not None and type(item["exit_code"]) is not int:
|
|
296
|
+
raise ValueError("Invalid exit code")
|
|
297
|
+
duration = item["duration_seconds"]
|
|
298
|
+
if type(duration) not in (int, float) or not math.isfinite(duration) or duration < 0:
|
|
299
|
+
raise ValueError("Invalid command duration")
|
|
300
|
+
if item["status"] == "passed" and item["exit_code"] != 0:
|
|
301
|
+
raise ValueError("Passing command needs exit zero")
|
|
302
|
+
if item["status"] in {"not_run", "not_selected"} and (
|
|
303
|
+
item["exit_code"] is not None or duration != 0
|
|
304
|
+
):
|
|
305
|
+
raise ValueError("Unexecuted command cannot have execution observations")
|
|
306
|
+
return key, Command((), ".", 300, item["purpose"], item["results"])
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
def _decode_inventory(data: dict[str, Any]) -> dict[str, Command]:
|
|
310
|
+
if not isinstance(data["commands"], list) or not 1 <= len(data["commands"]) <= 10000:
|
|
311
|
+
raise ValueError("Invalid command inventory")
|
|
312
|
+
declared: dict[str, Command] = {}
|
|
313
|
+
for item in data["commands"]:
|
|
314
|
+
key, command = _decode_command(item, declared)
|
|
315
|
+
declared[key] = command
|
|
316
|
+
return declared
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def _decode_catalog(data: dict[str, Any], declared: dict[str, Command]) -> Database:
|
|
320
|
+
# Reuse the owned mapping validator; this structural Project performs no I/O.
|
|
321
|
+
project = Project(Path("."), Path("."), b"", declared, (), {})
|
|
322
|
+
catalog_raw = json.dumps(data["catalog"]).encode()
|
|
323
|
+
if len(catalog_raw) > 1_048_576:
|
|
324
|
+
raise ValueError("Captured catalog exceeds 1 MiB")
|
|
325
|
+
database = decode(catalog_raw, project)
|
|
326
|
+
if data["requirements_revision"] == "absent" and (database.requirements or database.tests):
|
|
327
|
+
raise ValueError("Absent catalog revision cannot contain records")
|
|
328
|
+
return database
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def _decode_cases(result: dict[str, Any]) -> list[Case]:
|
|
332
|
+
cases = []
|
|
333
|
+
for case in result["cases"]:
|
|
334
|
+
case = object_fields(case, {"classname", "name", "status"}, "case")
|
|
335
|
+
if (
|
|
336
|
+
any(not isinstance(case[k], str) or len(case[k]) > 10000 for k in ("classname", "name"))
|
|
337
|
+
or not case["name"].strip()
|
|
338
|
+
or case["status"] not in CASE_STATES
|
|
339
|
+
):
|
|
340
|
+
raise ValueError("Invalid case identity/outcome")
|
|
341
|
+
cases.append(Case(**case))
|
|
342
|
+
return cases
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def _match_case_results(
|
|
346
|
+
item: dict[str, Any], result: dict[str, Any], cases: list[Case], database: Database
|
|
347
|
+
) -> TestResults:
|
|
348
|
+
parsed = TestResults(status=result["status"], sha256=result["sha256"], cases=cases)
|
|
349
|
+
if result["status"] in {"passed", "failed"}:
|
|
350
|
+
if not cases or result["sha256"] is None:
|
|
351
|
+
raise ValueError("Missing observed cases/fingerprint")
|
|
352
|
+
identities = [(c.classname, c.name) for c in cases]
|
|
353
|
+
counts = Counter(identities)
|
|
354
|
+
if any(counts[c.classname, c.name] > 1 and c.status != "ambiguous" for c in cases):
|
|
355
|
+
raise ValueError("Duplicate cases must be ambiguous")
|
|
356
|
+
parsed.match(item["id"], database)
|
|
357
|
+
if parsed.status != result["status"]:
|
|
358
|
+
raise ValueError("Case outcome contradicts captured mappings")
|
|
359
|
+
elif cases:
|
|
360
|
+
raise ValueError("Unverified results cannot contain qualifying cases")
|
|
361
|
+
return parsed
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
def _decode_test_results(item: dict[str, Any], database: Database) -> TestResults | None:
|
|
365
|
+
result = item["test_results"]
|
|
366
|
+
if result is None:
|
|
367
|
+
return None
|
|
368
|
+
result = object_fields(result, {"format", "status", "sha256", "cases"}, "test results")
|
|
369
|
+
if item["results"] != "junit" or not item["selected"] or result["format"] != "junit":
|
|
370
|
+
raise ValueError("Unexpected case results")
|
|
371
|
+
if result["status"] not in {"passed", "failed", "error", "not_run"}:
|
|
372
|
+
raise ValueError("Invalid case-result status")
|
|
373
|
+
if item["status"] == "not_run" and result["status"] != "not_run":
|
|
374
|
+
raise ValueError("Unexecuted command cannot report test execution")
|
|
375
|
+
if result["status"] == "not_run" and result["sha256"] is not None:
|
|
376
|
+
raise ValueError("Unexecuted results cannot identify an observed report")
|
|
377
|
+
if result["sha256"] is not None and not re.fullmatch(r"[a-f0-9]{64}", result["sha256"]):
|
|
378
|
+
raise ValueError("Invalid report fingerprint")
|
|
379
|
+
if not isinstance(result["cases"], list) or len(result["cases"]) > 100000:
|
|
380
|
+
raise ValueError("Invalid case inventory")
|
|
381
|
+
cases = _decode_cases(result)
|
|
382
|
+
return _match_case_results(item, result, cases, database)
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
def _decode_outcomes(
|
|
386
|
+
data: dict[str, Any], database: Database
|
|
387
|
+
) -> dict[str, tuple[str, TestResults | None]]:
|
|
388
|
+
outcomes: dict[str, tuple[str, TestResults | None]] = {}
|
|
389
|
+
for item in data["commands"]:
|
|
390
|
+
parsed = _decode_test_results(item, database)
|
|
391
|
+
if item["selected"]:
|
|
392
|
+
if item["results"] == "junit" and parsed is None:
|
|
393
|
+
raise ValueError("Selected JUnit command needs explicit result state")
|
|
394
|
+
if item["status"] == "passed" and parsed is not None and parsed.status != "passed":
|
|
395
|
+
raise ValueError("Passing command has non-passing test results")
|
|
396
|
+
outcomes[item["id"]] = (item["status"], parsed)
|
|
397
|
+
return outcomes
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def _validate_outcomes(
|
|
401
|
+
data: dict[str, Any], database: Database, outcomes: dict[str, tuple[str, TestResults | None]]
|
|
402
|
+
) -> None:
|
|
403
|
+
if not outcomes or (
|
|
404
|
+
data["status"] == "passed"
|
|
405
|
+
and (
|
|
406
|
+
not data["inputs_unchanged"]
|
|
407
|
+
or any(status != "passed" for status, _ in outcomes.values())
|
|
408
|
+
)
|
|
409
|
+
):
|
|
410
|
+
raise ValueError("Run outcome contradicts its commands/context")
|
|
411
|
+
if data["scope"] == "full" and any(c["required"] != c["selected"] for c in data["commands"]):
|
|
412
|
+
raise ValueError("Full check must select exactly the required inventory")
|
|
413
|
+
if data["schema"] != LEGACY_SCHEMA:
|
|
414
|
+
assessment = assess(
|
|
415
|
+
database,
|
|
416
|
+
outcomes,
|
|
417
|
+
catalog_present=data["requirements_revision"] != "absent",
|
|
418
|
+
inputs_unchanged=data["inputs_unchanged"],
|
|
419
|
+
)
|
|
420
|
+
if data["status"] == "incomplete" and (
|
|
421
|
+
data["scope"] != "full"
|
|
422
|
+
or not data["inputs_unchanged"]
|
|
423
|
+
or any(status != "passed" for status, _ in outcomes.values())
|
|
424
|
+
or assessment.status == "passed"
|
|
425
|
+
):
|
|
426
|
+
raise ValueError("Incomplete outcome contradicts commands or assessment")
|
|
427
|
+
if data["scope"] == "full" and data["status"] == "passed" and assessment.status != "passed":
|
|
428
|
+
raise ValueError("Passing full check has incomplete active verification")
|
|
429
|
+
full = data["scope"] == "full" and data["status"] == "passed"
|
|
430
|
+
if data["full_check_passed"] != full:
|
|
431
|
+
raise ValueError("Full-check flag contradicts the run")
|
|
432
|
+
|
|
433
|
+
|
|
434
|
+
def read(path: Path) -> tuple[dict[str, Any], Database, dict[str, tuple[str, TestResults | None]]]:
|
|
435
|
+
return validate(read_regular(path, limit=MAX_BYTES))
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
def _validate_documents(data: dict[str, Any]) -> None:
|
|
439
|
+
if data["schema"] != SCHEMA:
|
|
440
|
+
return
|
|
441
|
+
docs = object_fields(data["documents"], {"status", "input_sha256", "findings"}, "documents")
|
|
442
|
+
if docs["status"] not in {"valid", "invalid", "changed", "not_run"}:
|
|
443
|
+
raise ValueError("Invalid document verdict")
|
|
444
|
+
digest = docs["input_sha256"]
|
|
445
|
+
if docs["status"] == "not_run":
|
|
446
|
+
if digest is not None or docs["findings"]:
|
|
447
|
+
raise ValueError("Uninspected documents cannot contain a result")
|
|
448
|
+
elif not isinstance(digest, str) or not re.fullmatch(r"[a-f0-9]{64}", digest):
|
|
449
|
+
raise ValueError("Inspected documents need an input fingerprint")
|
|
450
|
+
if not isinstance(docs["findings"], list) or len(docs["findings"]) > 10000:
|
|
451
|
+
raise ValueError("Invalid document findings")
|
|
452
|
+
for finding in docs["findings"]:
|
|
453
|
+
_validate_document_finding(finding)
|
|
454
|
+
if (docs["status"] in {"invalid", "changed"}) != bool(docs["findings"]):
|
|
455
|
+
raise ValueError("Document verdict contradicts its findings")
|
|
456
|
+
_validate_document_scope(data, docs)
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def _validate_document_scope(data: dict[str, Any], docs: dict[str, Any]) -> None:
|
|
460
|
+
if docs["status"] == "changed" and data["inputs_unchanged"]:
|
|
461
|
+
raise ValueError("Changed documents cannot claim unchanged inputs")
|
|
462
|
+
if data["scope"] == "full" and (
|
|
463
|
+
docs["status"] == "not_run"
|
|
464
|
+
or (data["status"] in {"passed", "incomplete"} and docs["status"] != "valid")
|
|
465
|
+
):
|
|
466
|
+
raise ValueError("Full verification requires valid inspected documents")
|
|
467
|
+
if data["scope"] != "full" and docs["status"] != "not_run":
|
|
468
|
+
raise ValueError("Focused snapshot cannot claim a full document inspection")
|
|
469
|
+
|
|
470
|
+
|
|
471
|
+
def _validate_document_finding(value: Any) -> None:
|
|
472
|
+
item = object_fields(value, {"code", "path", "line", "message", "remedy"}, "document finding")
|
|
473
|
+
for key in ("code", "path", "message", "remedy"):
|
|
474
|
+
if not isinstance(item[key], str) or not item[key] or len(item[key]) > 4096:
|
|
475
|
+
raise ValueError("Invalid document finding text")
|
|
476
|
+
if item["line"] is not None and (type(item["line"]) is not int or item["line"] < 1):
|
|
477
|
+
raise ValueError("Invalid document finding line")
|
|
478
|
+
path = item["path"]
|
|
479
|
+
if (
|
|
480
|
+
PurePosixPath(path).is_absolute()
|
|
481
|
+
or PureWindowsPath(path).anchor
|
|
482
|
+
or ".." in Path(path).parts
|
|
483
|
+
):
|
|
484
|
+
raise ValueError("Document finding path must be project-relative")
|