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
opdev/config.py
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
"""Load the current format once; reject ambiguity before executing anything."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import re
|
|
7
|
+
from collections.abc import Hashable
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
import yaml
|
|
13
|
+
|
|
14
|
+
from opdev.document_catalog import DOCUMENT_LAYOUT, DOCUMENTS
|
|
15
|
+
from opdev.errors import OpDevError
|
|
16
|
+
from opdev.files import contained_path, read_regular, regular_path
|
|
17
|
+
|
|
18
|
+
SCHEMA = "opdev-mvp/1"
|
|
19
|
+
CONFIG_PATH = Path(".opdev/project.yaml")
|
|
20
|
+
PURPOSES = ("check", "build", "test", "run", "lint", "format", "format-check")
|
|
21
|
+
NON_CHECK_PURPOSES = {"run", "format"}
|
|
22
|
+
JUNIT_PATH = "{opdev.junit}"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class UniqueSafeLoader(yaml.SafeLoader):
|
|
26
|
+
def compose_node(self, parent: Any, index: Any) -> yaml.Node | None:
|
|
27
|
+
if self.check_event(yaml.AliasEvent):
|
|
28
|
+
raise OpDevError(
|
|
29
|
+
"YAML aliases are unsupported; declare each command once and use its ID."
|
|
30
|
+
)
|
|
31
|
+
return super().compose_node(parent, index)
|
|
32
|
+
|
|
33
|
+
def construct_mapping(self, node: yaml.Node, deep: bool = False) -> dict[Hashable, Any]:
|
|
34
|
+
if not isinstance(node, yaml.MappingNode):
|
|
35
|
+
raise OpDevError("Expected a YAML mapping.")
|
|
36
|
+
result: dict[Hashable, Any] = {}
|
|
37
|
+
for key_node, value_node in node.value:
|
|
38
|
+
key = self.construct_object(key_node, deep=deep)
|
|
39
|
+
if not isinstance(key, str):
|
|
40
|
+
raise OpDevError("Configuration keys must be strings.")
|
|
41
|
+
if key in result:
|
|
42
|
+
raise OpDevError(f"Duplicate configuration key: {key}.")
|
|
43
|
+
result[key] = self.construct_object(value_node, deep=deep)
|
|
44
|
+
return result
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class Command:
|
|
49
|
+
argv: tuple[str, ...]
|
|
50
|
+
cwd: str
|
|
51
|
+
timeout_seconds: int | None
|
|
52
|
+
purpose: str = "check"
|
|
53
|
+
results: str | None = None
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@dataclass(frozen=True)
|
|
57
|
+
class TrackingConfig:
|
|
58
|
+
provider: str
|
|
59
|
+
host: str
|
|
60
|
+
project: str
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass(frozen=True)
|
|
64
|
+
class Publication:
|
|
65
|
+
command: str
|
|
66
|
+
prerequisites: tuple[str, ...]
|
|
67
|
+
inputs: tuple[str, ...]
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True)
|
|
71
|
+
class Project:
|
|
72
|
+
root: Path
|
|
73
|
+
path: Path
|
|
74
|
+
raw: bytes
|
|
75
|
+
commands: dict[str, Command]
|
|
76
|
+
checks: tuple[str, ...]
|
|
77
|
+
documents: dict[str, str]
|
|
78
|
+
tracking: TrackingConfig | None = None
|
|
79
|
+
publication: Publication | None = None
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def digest(self) -> str:
|
|
83
|
+
return hashlib.sha256(self.raw).hexdigest()
|
|
84
|
+
|
|
85
|
+
def unchanged(self) -> bool:
|
|
86
|
+
return read_regular(self.path) == self.raw
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def mapping(value: Any, name: str, allowed: set[str] | None = None) -> dict[str, Any]:
|
|
90
|
+
if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
|
|
91
|
+
raise OpDevError(f"{name} must be a mapping with string keys.")
|
|
92
|
+
if allowed is not None and (unknown := set(value) - allowed):
|
|
93
|
+
raise OpDevError(f"Unknown {name} field(s): {', '.join(sorted(unknown))}.")
|
|
94
|
+
return dict(value)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def load_project(root: Path, path: Path | None = None) -> Project:
|
|
98
|
+
root = root.absolute()
|
|
99
|
+
regular_path(root)
|
|
100
|
+
root = root.resolve()
|
|
101
|
+
if not root.is_dir():
|
|
102
|
+
raise OpDevError(f"Project directory does not exist: {root}.")
|
|
103
|
+
path = path.absolute() if path is not None else root / CONFIG_PATH
|
|
104
|
+
raw = read_regular(path)
|
|
105
|
+
try:
|
|
106
|
+
data = mapping(
|
|
107
|
+
yaml.load(raw.decode("utf-8"), Loader=UniqueSafeLoader),
|
|
108
|
+
"project",
|
|
109
|
+
{"schema", "commands", "checks", "documents", "tracking", "publication"},
|
|
110
|
+
)
|
|
111
|
+
except (UnicodeError, yaml.YAMLError, RecursionError) as exc:
|
|
112
|
+
raise OpDevError("Configuration is not valid supported UTF-8 YAML.") from exc
|
|
113
|
+
if data.get("schema") != SCHEMA:
|
|
114
|
+
raise OpDevError(f"Unsupported project schema; expected {SCHEMA}. No commands ran.")
|
|
115
|
+
commands = {
|
|
116
|
+
name: _parse_command(root, name, value)
|
|
117
|
+
for name, value in mapping(data.get("commands"), "commands").items()
|
|
118
|
+
}
|
|
119
|
+
checks = _parse_checks(data.get("checks"), commands)
|
|
120
|
+
documents = _parse_documents(data.get("documents", {}))
|
|
121
|
+
tracking = _parse_tracking(data["tracking"]) if "tracking" in data else None
|
|
122
|
+
publication = (
|
|
123
|
+
_parse_publication(root, data["publication"], commands, checks)
|
|
124
|
+
if "publication" in data
|
|
125
|
+
else None
|
|
126
|
+
)
|
|
127
|
+
return Project(root, path, raw, commands, checks, documents, tracking, publication)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _parse_command(root: Path, name: str, value: Any) -> Command:
|
|
131
|
+
if not re.fullmatch(r"[a-z][a-z0-9_-]{0,63}", name):
|
|
132
|
+
raise OpDevError(f"Invalid command ID: {name}.")
|
|
133
|
+
item = mapping(
|
|
134
|
+
value, f"command {name}", {"argv", "cwd", "timeout_seconds", "purpose", "results"}
|
|
135
|
+
)
|
|
136
|
+
purpose = item.get("purpose", "check")
|
|
137
|
+
if not isinstance(purpose, str) or purpose not in PURPOSES:
|
|
138
|
+
raise OpDevError(f"Command {name} purpose must be one of {', '.join(PURPOSES)}.")
|
|
139
|
+
argv = item.get("argv")
|
|
140
|
+
if (
|
|
141
|
+
not isinstance(argv, list)
|
|
142
|
+
or not argv
|
|
143
|
+
or any(not isinstance(arg, str) or "\0" in arg for arg in argv)
|
|
144
|
+
or not argv[0].strip()
|
|
145
|
+
):
|
|
146
|
+
raise OpDevError(f"Command {name} needs a nonempty argv array of strings.")
|
|
147
|
+
cwd = item.get("cwd", ".")
|
|
148
|
+
timeout = item.get("timeout_seconds", None if purpose == "run" else 300)
|
|
149
|
+
if not isinstance(cwd, str) or not cwd or "\0" in cwd:
|
|
150
|
+
raise OpDevError(f"Command {name} needs a project-relative cwd.")
|
|
151
|
+
if not contained_path(root, cwd).is_dir():
|
|
152
|
+
raise OpDevError(f"Command {name} working directory does not exist: {cwd}.")
|
|
153
|
+
if not (purpose == "run" and timeout is None) and (
|
|
154
|
+
type(timeout) is not int or not 1 <= timeout <= 86400
|
|
155
|
+
):
|
|
156
|
+
raise OpDevError(f"Command {name} timeout_seconds must be an integer from 1 to 86400.")
|
|
157
|
+
results = item.get("results")
|
|
158
|
+
if "results" in item and results != "junit":
|
|
159
|
+
raise OpDevError(f"Command {name} results must be 'junit' when declared.")
|
|
160
|
+
tokens = sum(arg.count(JUNIT_PATH) for arg in argv)
|
|
161
|
+
if (
|
|
162
|
+
(results == "junit" and (tokens != 1 or purpose in NON_CHECK_PURPOSES))
|
|
163
|
+
or (results is None and tokens)
|
|
164
|
+
or JUNIT_PATH in argv[0]
|
|
165
|
+
):
|
|
166
|
+
raise OpDevError(
|
|
167
|
+
f"Command {name}: JUnit verification needs results: junit and exactly one "
|
|
168
|
+
"{opdev.junit} token in a non-executable argument; run/format are unsupported."
|
|
169
|
+
)
|
|
170
|
+
return Command(tuple(argv), cwd, timeout, purpose, results)
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _parse_checks(value: Any, commands: dict[str, Command]) -> tuple[str, ...]:
|
|
174
|
+
checks = value
|
|
175
|
+
if (
|
|
176
|
+
not isinstance(checks, list)
|
|
177
|
+
or not checks
|
|
178
|
+
or any(not isinstance(name, str) for name in checks)
|
|
179
|
+
):
|
|
180
|
+
raise OpDevError(
|
|
181
|
+
"checks must be a nonempty array of command IDs; empty checks cannot pass."
|
|
182
|
+
)
|
|
183
|
+
if len(set(checks)) != len(checks) or any(name not in commands for name in checks):
|
|
184
|
+
raise OpDevError("checks must contain unique, declared command IDs.")
|
|
185
|
+
if any(commands[name].purpose in NON_CHECK_PURPOSES for name in checks):
|
|
186
|
+
raise OpDevError("Run targets and formatting edits cannot be required checks.")
|
|
187
|
+
return tuple(checks)
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def _parse_documents(value: Any) -> dict[str, str]:
|
|
191
|
+
if isinstance(value, dict) and set(value) & {"design", "interface", "tech_stack"}:
|
|
192
|
+
raise OpDevError(
|
|
193
|
+
"Legacy document routes need a reviewed migration to the fixed document layout. "
|
|
194
|
+
"Preserve accepted decisions; no documents were moved or rewritten."
|
|
195
|
+
)
|
|
196
|
+
item = mapping(value, "documents", {"layout", "optional"})
|
|
197
|
+
if item.get("layout", DOCUMENT_LAYOUT) != DOCUMENT_LAYOUT:
|
|
198
|
+
raise OpDevError(f"Unsupported document layout; expected {DOCUMENT_LAYOUT}.")
|
|
199
|
+
optional = item.get("optional", [])
|
|
200
|
+
choices = {role for role, spec in DOCUMENTS.items() if not spec.required}
|
|
201
|
+
if (
|
|
202
|
+
not isinstance(optional, list)
|
|
203
|
+
or any(not isinstance(role, str) or role not in choices for role in optional)
|
|
204
|
+
or len(set(optional)) != len(optional)
|
|
205
|
+
):
|
|
206
|
+
raise OpDevError(
|
|
207
|
+
"documents.optional needs unique known topics: " + ", ".join(sorted(choices)) + "."
|
|
208
|
+
)
|
|
209
|
+
return {
|
|
210
|
+
role: spec.path for role, spec in DOCUMENTS.items() if spec.required or role in optional
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def _parse_tracking(value: Any) -> TrackingConfig:
|
|
215
|
+
item = mapping(value, "tracking", {"provider", "host", "project"})
|
|
216
|
+
if item.get("provider") != "gitlab":
|
|
217
|
+
raise OpDevError("Unsupported tracking provider; OpDev currently supports GitLab.")
|
|
218
|
+
host = item.get("host")
|
|
219
|
+
target = item.get("project")
|
|
220
|
+
if not isinstance(host, str) or not re.fullmatch(
|
|
221
|
+
r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::[0-9]{1,5})?", host
|
|
222
|
+
):
|
|
223
|
+
raise OpDevError(
|
|
224
|
+
"tracking.host must be an explicit hostname, optionally with a port; "
|
|
225
|
+
"no URL or credentials."
|
|
226
|
+
)
|
|
227
|
+
if type(target) is int and target > 0:
|
|
228
|
+
target = str(target)
|
|
229
|
+
if (
|
|
230
|
+
not isinstance(target, str)
|
|
231
|
+
or not re.fullmatch(
|
|
232
|
+
r"[1-9][0-9]*|[A-Za-z0-9_-]+(?:[.][A-Za-z0-9_-]+)*(?:/[A-Za-z0-9_.-]+)+", target
|
|
233
|
+
)
|
|
234
|
+
or any(part in {".", ".."} for part in target.split("/"))
|
|
235
|
+
):
|
|
236
|
+
raise OpDevError(
|
|
237
|
+
"tracking.project must be a positive project ID or namespace/project path."
|
|
238
|
+
)
|
|
239
|
+
return TrackingConfig("gitlab", host, target)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def _parse_publication(
|
|
243
|
+
root: Path, value: Any, commands: dict[str, Command], checks: tuple[str, ...]
|
|
244
|
+
) -> Publication:
|
|
245
|
+
item = mapping(value, "publication", {"command", "prerequisites", "inputs"})
|
|
246
|
+
publisher = item.get("command")
|
|
247
|
+
prerequisites = item.get("prerequisites", [])
|
|
248
|
+
inputs = item.get("inputs")
|
|
249
|
+
if not isinstance(publisher, str) or publisher not in commands or publisher in checks:
|
|
250
|
+
raise OpDevError("publication.command must name a declared command outside checks.")
|
|
251
|
+
if commands[publisher].purpose != "check":
|
|
252
|
+
raise OpDevError(
|
|
253
|
+
"The publisher must retain the default purpose 'check'; "
|
|
254
|
+
"it cannot also be a build, test, run, lint or formatting target."
|
|
255
|
+
)
|
|
256
|
+
if commands[publisher].results is not None:
|
|
257
|
+
raise OpDevError("The publisher cannot declare test results; use a prerequisite.")
|
|
258
|
+
if (
|
|
259
|
+
not isinstance(prerequisites, list)
|
|
260
|
+
or any(not isinstance(p, str) or p not in commands or p == publisher for p in prerequisites)
|
|
261
|
+
or len(prerequisites) != len(set(prerequisites))
|
|
262
|
+
):
|
|
263
|
+
raise OpDevError(
|
|
264
|
+
"Publication prerequisites need unique declared non-publisher command IDs."
|
|
265
|
+
)
|
|
266
|
+
if not isinstance(inputs, list) or any(
|
|
267
|
+
not isinstance(p, str) or not p or "\0" in p for p in inputs
|
|
268
|
+
):
|
|
269
|
+
raise OpDevError(
|
|
270
|
+
"publication.inputs must explicitly list prebuilt files; "
|
|
271
|
+
"use [] for source-only publication."
|
|
272
|
+
)
|
|
273
|
+
if any(commands[name].purpose in NON_CHECK_PURPOSES for name in prerequisites):
|
|
274
|
+
raise OpDevError("Publication prerequisites cannot run applications or edit formatting.")
|
|
275
|
+
paths = [contained_path(root, p).resolve() for p in inputs]
|
|
276
|
+
if len(paths) != len(set(paths)) or any(p.is_relative_to(root / ".git") for p in paths):
|
|
277
|
+
raise OpDevError("Publication inputs must be distinct project files outside .git.")
|
|
278
|
+
return Publication(publisher, tuple(prerequisites), tuple(inputs))
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"""The fixed, packaged catalog of development-document roles."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
|
|
5
|
+
DOCUMENT_LAYOUT = "opdev-documents/1"
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@dataclass(frozen=True)
|
|
9
|
+
class DocumentSpec:
|
|
10
|
+
role: str
|
|
11
|
+
path: str
|
|
12
|
+
required: bool
|
|
13
|
+
headings: tuple[str, ...]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
DOCUMENTS = {
|
|
17
|
+
spec.role: spec
|
|
18
|
+
for spec in (
|
|
19
|
+
DocumentSpec("guidance", ".opdev/guidance.md", True, ("Workflow", "Project routes")),
|
|
20
|
+
DocumentSpec(
|
|
21
|
+
"design",
|
|
22
|
+
".opdev/design.md",
|
|
23
|
+
True,
|
|
24
|
+
("Problem and users", "Outcomes", "Scope and exclusions"),
|
|
25
|
+
),
|
|
26
|
+
DocumentSpec(
|
|
27
|
+
"interface",
|
|
28
|
+
".opdev/interface.md",
|
|
29
|
+
True,
|
|
30
|
+
("Interactions", "Inputs and outputs", "Failures and compatibility"),
|
|
31
|
+
),
|
|
32
|
+
DocumentSpec(
|
|
33
|
+
"stack",
|
|
34
|
+
".opdev/technical/stack.md",
|
|
35
|
+
True,
|
|
36
|
+
("Languages and runtimes", "Dependencies and tools", "Platform constraints"),
|
|
37
|
+
),
|
|
38
|
+
DocumentSpec(
|
|
39
|
+
"architecture",
|
|
40
|
+
".opdev/technical/architecture.md",
|
|
41
|
+
True,
|
|
42
|
+
(
|
|
43
|
+
"Responsibilities",
|
|
44
|
+
"Source organization",
|
|
45
|
+
"Interfaces and dependencies",
|
|
46
|
+
"State and effects",
|
|
47
|
+
),
|
|
48
|
+
),
|
|
49
|
+
DocumentSpec(
|
|
50
|
+
"standards",
|
|
51
|
+
".opdev/technical/standards.md",
|
|
52
|
+
True,
|
|
53
|
+
(
|
|
54
|
+
"Language conventions",
|
|
55
|
+
"Error handling",
|
|
56
|
+
"Complexity policy",
|
|
57
|
+
"Automated enforcement",
|
|
58
|
+
),
|
|
59
|
+
),
|
|
60
|
+
DocumentSpec(
|
|
61
|
+
"verification",
|
|
62
|
+
".opdev/technical/verification.md",
|
|
63
|
+
True,
|
|
64
|
+
(
|
|
65
|
+
"Test strategy",
|
|
66
|
+
"Requirement verification",
|
|
67
|
+
"Focused checks and integration CI",
|
|
68
|
+
"Limitations",
|
|
69
|
+
),
|
|
70
|
+
),
|
|
71
|
+
DocumentSpec(
|
|
72
|
+
"data",
|
|
73
|
+
".opdev/technical/data.md",
|
|
74
|
+
False,
|
|
75
|
+
("Data ownership", "Representations and invariants", "Migration and recovery"),
|
|
76
|
+
),
|
|
77
|
+
DocumentSpec(
|
|
78
|
+
"security",
|
|
79
|
+
".opdev/technical/security.md",
|
|
80
|
+
False,
|
|
81
|
+
("Trust boundaries", "Access and sensitive data", "Controls and limitations"),
|
|
82
|
+
),
|
|
83
|
+
DocumentSpec(
|
|
84
|
+
"operations",
|
|
85
|
+
".opdev/technical/operations.md",
|
|
86
|
+
False,
|
|
87
|
+
("Deployment", "Observability", "Recovery", "Maintenance"),
|
|
88
|
+
),
|
|
89
|
+
DocumentSpec(
|
|
90
|
+
"performance",
|
|
91
|
+
".opdev/technical/performance.md",
|
|
92
|
+
False,
|
|
93
|
+
("Workloads and budgets", "Measurement", "Design constraints"),
|
|
94
|
+
),
|
|
95
|
+
DocumentSpec(
|
|
96
|
+
"evaluation",
|
|
97
|
+
".opdev/technical/evaluation.md",
|
|
98
|
+
False,
|
|
99
|
+
(
|
|
100
|
+
"Evaluation scope",
|
|
101
|
+
"Inputs and oracles",
|
|
102
|
+
"Execution procedure",
|
|
103
|
+
"Interpretation and limitations",
|
|
104
|
+
),
|
|
105
|
+
),
|
|
106
|
+
)
|
|
107
|
+
}
|
opdev/document_review.py
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
"""Read-only change inventory; selected document owners are not authenticated consent."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import subprocess
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from opdev.config import Project
|
|
10
|
+
from opdev.document_catalog import DOCUMENTS
|
|
11
|
+
from opdev.errors import OpDevError
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _git(root: Path, *args: str) -> bytes:
|
|
15
|
+
try:
|
|
16
|
+
result = subprocess.run(
|
|
17
|
+
["git", "--no-optional-locks", "-c", "core.fsmonitor=false", "-C", str(root), *args],
|
|
18
|
+
capture_output=True,
|
|
19
|
+
timeout=30,
|
|
20
|
+
env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
|
|
21
|
+
)
|
|
22
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
23
|
+
raise OpDevError("Document review needs an available local Git checkout.") from exc
|
|
24
|
+
if result.returncode:
|
|
25
|
+
raise OpDevError(
|
|
26
|
+
"Cannot inspect the selected Git checkout or base commit. "
|
|
27
|
+
"Use an existing local commit; no files changed or checks ran."
|
|
28
|
+
)
|
|
29
|
+
return result.stdout
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def review(project: Project, base: str, allowed: list[str]) -> dict[str, object]:
|
|
33
|
+
"""Compare the entire current checkout to a resolved commit, including untracked paths."""
|
|
34
|
+
if not base or set(allowed) - DOCUMENTS.keys():
|
|
35
|
+
raise OpDevError("Select an existing base commit and known document roles.")
|
|
36
|
+
root = project.root.resolve()
|
|
37
|
+
git_root = Path(os.fsdecode(_git(root, "rev-parse", "--show-toplevel")).strip()).resolve()
|
|
38
|
+
if git_root != root:
|
|
39
|
+
raise OpDevError("Document review requires the project root to be the Git checkout root.")
|
|
40
|
+
try:
|
|
41
|
+
commit = _git(root, "rev-parse", "--verify", "--end-of-options", base + "^{commit}")
|
|
42
|
+
except OpDevError as exc:
|
|
43
|
+
raise OpDevError(
|
|
44
|
+
f"Cannot resolve selected base commit {base!r}. The project Git checkout was found. "
|
|
45
|
+
"Check for a transcription error against the original recorded commit and retry "
|
|
46
|
+
"that exact value. No alternative base was substituted; no files changed or checks ran."
|
|
47
|
+
) from exc
|
|
48
|
+
revision = commit.decode("ascii").strip()
|
|
49
|
+
tracked = _git(
|
|
50
|
+
root,
|
|
51
|
+
"diff",
|
|
52
|
+
"--no-ext-diff",
|
|
53
|
+
"--no-textconv",
|
|
54
|
+
"--no-renames",
|
|
55
|
+
"--name-only",
|
|
56
|
+
"-z",
|
|
57
|
+
revision,
|
|
58
|
+
"--",
|
|
59
|
+
)
|
|
60
|
+
staged = _git(
|
|
61
|
+
root,
|
|
62
|
+
"diff",
|
|
63
|
+
"--cached",
|
|
64
|
+
"--no-ext-diff",
|
|
65
|
+
"--no-textconv",
|
|
66
|
+
"--no-renames",
|
|
67
|
+
"--name-only",
|
|
68
|
+
"-z",
|
|
69
|
+
revision,
|
|
70
|
+
"--",
|
|
71
|
+
)
|
|
72
|
+
untracked = _git(root, "ls-files", "--others", "--exclude-standard", "-z")
|
|
73
|
+
paths = sorted(
|
|
74
|
+
{os.fsdecode(path) for path in (tracked + staged + untracked).split(b"\0") if path}
|
|
75
|
+
)
|
|
76
|
+
owners = {spec.path: role for role, spec in DOCUMENTS.items()}
|
|
77
|
+
changed_documents = [{"path": path, "role": owners[path]} for path in paths if path in owners]
|
|
78
|
+
unexpected = [item for item in changed_documents if item["role"] not in allowed]
|
|
79
|
+
decisions = [item for item in changed_documents if item["path"].startswith(".opdev/technical/")]
|
|
80
|
+
status = "within_selected_scope"
|
|
81
|
+
if decisions:
|
|
82
|
+
status = "decision_review_required"
|
|
83
|
+
if unexpected:
|
|
84
|
+
status = "needs_review"
|
|
85
|
+
return {
|
|
86
|
+
"operation": "documents review",
|
|
87
|
+
"scope": "document_changes",
|
|
88
|
+
"status": status,
|
|
89
|
+
"base_commit": revision,
|
|
90
|
+
"selected_roles": sorted(set(allowed)),
|
|
91
|
+
"files": paths,
|
|
92
|
+
"changed_documents": changed_documents,
|
|
93
|
+
"unexpected_documents": unexpected,
|
|
94
|
+
"decision_documents": decisions,
|
|
95
|
+
"detail": (
|
|
96
|
+
"Changed paths only; selected roles are not approval. "
|
|
97
|
+
+ (
|
|
98
|
+
"Technical documents changed. Selecting their owners cannot clear decision review. "
|
|
99
|
+
"Feature behavior, individual test details and delivery timing do not authorize "
|
|
100
|
+
"technical-policy edits. Restore those incidental changes. To retain a technical "
|
|
101
|
+
"diff, quote the actual developer instruction authorizing that specific technical "
|
|
102
|
+
"decision change or document repair/migration and explain how the diff matches it. "
|
|
103
|
+
"Broad implementation approval, 'update affected designs', an owner flag or an "
|
|
104
|
+
"agent-written 'accepted' label is not that instruction. Report this grounding "
|
|
105
|
+
"separately; it does not turn the checkpoint into a pass. "
|
|
106
|
+
if decisions
|
|
107
|
+
else ""
|
|
108
|
+
)
|
|
109
|
+
+ "Inspect the diff against "
|
|
110
|
+
"the accepted change brief and preserve preexisting edits. No files changed or "
|
|
111
|
+
"project checks ran. Structure, meaning, test adequacy, integration and release "
|
|
112
|
+
"are not verified. Ignored untracked paths are excluded; use documents validate "
|
|
113
|
+
"for the complete catalog. This observation is not atomic or reusable qualification."
|
|
114
|
+
),
|
|
115
|
+
}
|