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/requirements.py
ADDED
|
@@ -0,0 +1,642 @@
|
|
|
1
|
+
"""Owned requirement/test mappings; no execution evidence or tracker state."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import re
|
|
8
|
+
from collections.abc import Mapping
|
|
9
|
+
from dataclasses import asdict, dataclass, replace
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from opdev.config import NON_CHECK_PURPOSES, Project
|
|
13
|
+
from opdev.errors import OpDevError
|
|
14
|
+
from opdev.files import contained_path, read_optional, replace_checked
|
|
15
|
+
|
|
16
|
+
SCHEMA = "opdev-requirements/2"
|
|
17
|
+
STORE = ".opdev/requirements.json"
|
|
18
|
+
STATES = ("proposed", "active", "retired")
|
|
19
|
+
LIMITATION = (
|
|
20
|
+
"Mappings only. No checks ran in this operation; it does not verify named-test execution "
|
|
21
|
+
"or assertion adequacy."
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True)
|
|
26
|
+
class Requirement:
|
|
27
|
+
statement: str
|
|
28
|
+
state: str = "proposed"
|
|
29
|
+
sources: tuple[str, ...] = ()
|
|
30
|
+
tests: tuple[str, ...] = ()
|
|
31
|
+
parent: str | None = None
|
|
32
|
+
rationale: str = ""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class Test:
|
|
37
|
+
check: str
|
|
38
|
+
location: str
|
|
39
|
+
verifies: str
|
|
40
|
+
result: dict[str, str] | None = None
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass
|
|
44
|
+
class Database:
|
|
45
|
+
requirements: dict[str, Requirement]
|
|
46
|
+
tests: dict[str, Test]
|
|
47
|
+
|
|
48
|
+
def encode(self) -> bytes:
|
|
49
|
+
return (
|
|
50
|
+
json.dumps({"schema": SCHEMA, **asdict(self)}, indent=2, sort_keys=True) + "\n"
|
|
51
|
+
).encode()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def revision(raw: bytes | None) -> str:
|
|
55
|
+
return "absent" if raw is None else hashlib.sha256(raw).hexdigest()
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def identifier(value: str) -> str:
|
|
59
|
+
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", value):
|
|
60
|
+
raise OpDevError(
|
|
61
|
+
f"Invalid record ID: {value!r}; use 1-128 letters, digits, dots, '_' or '-'."
|
|
62
|
+
)
|
|
63
|
+
return value
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def text(value: Any, name: str) -> str:
|
|
67
|
+
if not isinstance(value, str) or not value.strip() or "\0" in value or len(value) > 10000:
|
|
68
|
+
raise OpDevError(f"{name} must be nonempty text of at most 10000 characters, without NUL.")
|
|
69
|
+
return value
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def strings(value: Any, name: str) -> tuple[str, ...]:
|
|
73
|
+
if not isinstance(value, list):
|
|
74
|
+
raise OpDevError(f"{name} must be an array of unique strings.")
|
|
75
|
+
result = tuple(text(item, name) for item in value)
|
|
76
|
+
if len(set(result)) != len(result):
|
|
77
|
+
raise OpDevError(f"{name} contains duplicate values.")
|
|
78
|
+
return result
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def object_fields(value: Any, fields: set[str], name: str) -> dict[str, Any]:
|
|
82
|
+
if not isinstance(value, dict) or set(value) != fields:
|
|
83
|
+
raise OpDevError(f"{name} needs exactly these fields: {', '.join(sorted(fields))}.")
|
|
84
|
+
return value
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
|
88
|
+
result: dict[str, Any] = {}
|
|
89
|
+
for key, value in pairs:
|
|
90
|
+
if key in result:
|
|
91
|
+
raise OpDevError(f"Duplicate JSON key: {key}.")
|
|
92
|
+
result[key] = value
|
|
93
|
+
return result
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def invalid_constant(value: str) -> None:
|
|
97
|
+
raise OpDevError(f"Unsupported JSON constant: {value}.")
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def decode(raw: bytes | None, project: Project) -> Database:
|
|
101
|
+
if raw is None:
|
|
102
|
+
return Database({}, {})
|
|
103
|
+
try:
|
|
104
|
+
data = json.loads(
|
|
105
|
+
raw.decode("utf-8"), object_pairs_hook=unique_object, parse_constant=invalid_constant
|
|
106
|
+
)
|
|
107
|
+
except (ValueError, UnicodeError, RecursionError) as exc:
|
|
108
|
+
raise OpDevError("Requirements must be valid UTF-8 JSON; nothing changed.") from exc
|
|
109
|
+
data = object_fields(data, {"schema", "requirements", "tests"}, "Requirements database")
|
|
110
|
+
if data["schema"] != SCHEMA:
|
|
111
|
+
raise OpDevError(
|
|
112
|
+
f"Unsupported requirements schema; expected {SCHEMA}. "
|
|
113
|
+
"Review a manual format update; no existing records changed."
|
|
114
|
+
)
|
|
115
|
+
if not isinstance(data["requirements"], dict) or not isinstance(data["tests"], dict):
|
|
116
|
+
raise OpDevError("requirements and tests must be objects keyed by stable IDs.")
|
|
117
|
+
tests = {}
|
|
118
|
+
for key, value in data["tests"].items():
|
|
119
|
+
tests[identifier(key)] = _decode_test(key, value, project)
|
|
120
|
+
requirements = {}
|
|
121
|
+
for key, value in data["requirements"].items():
|
|
122
|
+
requirements[identifier(key)] = _decode_requirement(key, value, tests)
|
|
123
|
+
validate_hierarchy(requirements)
|
|
124
|
+
return Database(requirements, tests)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _decode_test(key: str, value: Any, project: Project) -> Test:
|
|
128
|
+
fields = {"check", "location", "verifies"}
|
|
129
|
+
if isinstance(value, dict) and "result" in value:
|
|
130
|
+
fields.add("result")
|
|
131
|
+
item = object_fields(value, fields, f"Test {key}")
|
|
132
|
+
check = text(item["check"], "check")
|
|
133
|
+
if check not in project.commands:
|
|
134
|
+
raise OpDevError(f"Test {key} references undeclared command {check}.")
|
|
135
|
+
if project.publication and check == project.publication.command:
|
|
136
|
+
raise OpDevError(f"Test {key} references the publisher, not a verification command.")
|
|
137
|
+
if project.commands[check].purpose in NON_CHECK_PURPOSES:
|
|
138
|
+
raise OpDevError(f"Test {key} needs a verification command, not run or format.")
|
|
139
|
+
selector = item.get("result")
|
|
140
|
+
if selector is not None:
|
|
141
|
+
selector = object_fields(selector, {"classname", "name"}, f"Test {key} result")
|
|
142
|
+
text(selector["name"], "result name")
|
|
143
|
+
# An absent JUnit classname has the exact identity "".
|
|
144
|
+
classname = selector["classname"]
|
|
145
|
+
if not isinstance(classname, str) or "\0" in classname or len(classname) > 10000:
|
|
146
|
+
raise OpDevError("Result classname must be text of at most 10000 characters.")
|
|
147
|
+
if project.commands[check].results != "junit":
|
|
148
|
+
raise OpDevError(f"Test {key} result selector needs a JUnit-enabled command.")
|
|
149
|
+
return Test(
|
|
150
|
+
check, text(item["location"], "location"), text(item["verifies"], "verifies"), selector
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _decode_requirement(key: str, value: Any, tests: dict[str, Test]) -> Requirement:
|
|
155
|
+
item = object_fields(
|
|
156
|
+
value,
|
|
157
|
+
{"statement", "state", "sources", "tests", "parent", "rationale"},
|
|
158
|
+
f"Requirement {key}",
|
|
159
|
+
)
|
|
160
|
+
state = text(item["state"], "state")
|
|
161
|
+
if state not in STATES:
|
|
162
|
+
raise OpDevError(f"Requirement {key} state must be one of {', '.join(STATES)}.")
|
|
163
|
+
links = strings(item["tests"], "tests")
|
|
164
|
+
if any(link not in tests for link in links):
|
|
165
|
+
raise OpDevError(f"Requirement {key} references an unknown test; repair its mapping.")
|
|
166
|
+
parent = item["parent"]
|
|
167
|
+
if parent is not None:
|
|
168
|
+
identifier(text(parent, "parent"))
|
|
169
|
+
rationale = item["rationale"]
|
|
170
|
+
if rationale != "":
|
|
171
|
+
text(rationale, "rationale")
|
|
172
|
+
return Requirement(
|
|
173
|
+
text(item["statement"], "statement"),
|
|
174
|
+
state,
|
|
175
|
+
strings(item["sources"], "sources"),
|
|
176
|
+
links,
|
|
177
|
+
parent,
|
|
178
|
+
rationale,
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def validate_hierarchy(requirements: Mapping[str, Requirement]) -> None:
|
|
183
|
+
"""Validate the single-parent forest iteratively, including deep input."""
|
|
184
|
+
for key, item in requirements.items():
|
|
185
|
+
if item.parent is not None:
|
|
186
|
+
if item.parent not in requirements:
|
|
187
|
+
raise OpDevError(f"Requirement {key} references missing parent {item.parent}.")
|
|
188
|
+
if item.state == "active" and requirements[item.parent].state == "retired":
|
|
189
|
+
raise OpDevError(f"Active requirement {key} needs a non-retired parent.")
|
|
190
|
+
done: set[str] = set()
|
|
191
|
+
for key in requirements:
|
|
192
|
+
trail: set[str] = set()
|
|
193
|
+
current: str | None = key
|
|
194
|
+
while current is not None and current not in done:
|
|
195
|
+
if current in trail:
|
|
196
|
+
raise OpDevError(f"Requirement hierarchy contains a cycle at {current}.")
|
|
197
|
+
trail.add(current)
|
|
198
|
+
current = requirements[current].parent
|
|
199
|
+
done.update(trail)
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def load(project: Project) -> tuple[Database, bytes | None]:
|
|
203
|
+
raw = read_optional(contained_path(project.root, STORE))
|
|
204
|
+
return decode(raw, project), raw
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def mutate(
|
|
208
|
+
project: Project,
|
|
209
|
+
kind: str,
|
|
210
|
+
action: str,
|
|
211
|
+
record_id: str,
|
|
212
|
+
*,
|
|
213
|
+
statement: str | None = None,
|
|
214
|
+
state: str | None = None,
|
|
215
|
+
sources: list[str] | None = None,
|
|
216
|
+
parent: str | None = None,
|
|
217
|
+
clear_parent: bool = False,
|
|
218
|
+
rationale: str | None = None,
|
|
219
|
+
check: str | None = None,
|
|
220
|
+
location: str | None = None,
|
|
221
|
+
verifies: str | None = None,
|
|
222
|
+
result_classname: str | None = None,
|
|
223
|
+
result_name: str | None = None,
|
|
224
|
+
clear_result: bool = False,
|
|
225
|
+
test_id: str | None = None,
|
|
226
|
+
if_match: str | None = None,
|
|
227
|
+
plan: bool = False,
|
|
228
|
+
) -> dict[str, object]:
|
|
229
|
+
database, raw = load(project)
|
|
230
|
+
identifier(record_id)
|
|
231
|
+
if if_match is not None and if_match != revision(raw):
|
|
232
|
+
raise OpDevError("Requirements revision does not match --if-match; reread before retrying.")
|
|
233
|
+
_validate_mutation(
|
|
234
|
+
database,
|
|
235
|
+
kind,
|
|
236
|
+
action,
|
|
237
|
+
record_id,
|
|
238
|
+
parent=parent,
|
|
239
|
+
clear_parent=clear_parent,
|
|
240
|
+
result_classname=result_classname,
|
|
241
|
+
result_name=result_name,
|
|
242
|
+
clear_result=clear_result,
|
|
243
|
+
changed_fields=(
|
|
244
|
+
statement,
|
|
245
|
+
state,
|
|
246
|
+
sources,
|
|
247
|
+
parent,
|
|
248
|
+
rationale,
|
|
249
|
+
check,
|
|
250
|
+
location,
|
|
251
|
+
verifies,
|
|
252
|
+
result_name,
|
|
253
|
+
),
|
|
254
|
+
)
|
|
255
|
+
if action == "delete":
|
|
256
|
+
_delete_record(database, kind, record_id)
|
|
257
|
+
elif action in {"link", "unlink"}:
|
|
258
|
+
_change_link(database, kind, action, record_id, test_id)
|
|
259
|
+
elif kind == "requirement":
|
|
260
|
+
prior = database.requirements.get(record_id, Requirement(""))
|
|
261
|
+
database.requirements[record_id] = replace(
|
|
262
|
+
prior,
|
|
263
|
+
statement=statement if statement is not None else prior.statement,
|
|
264
|
+
state=state if state is not None else prior.state,
|
|
265
|
+
sources=tuple(sources) if sources is not None else prior.sources,
|
|
266
|
+
parent=None if clear_parent else parent if parent is not None else prior.parent,
|
|
267
|
+
rationale=rationale if rationale is not None else prior.rationale,
|
|
268
|
+
)
|
|
269
|
+
else:
|
|
270
|
+
prior_test = database.tests.get(record_id, Test("", "", ""))
|
|
271
|
+
database.tests[record_id] = Test(
|
|
272
|
+
check if check is not None else prior_test.check,
|
|
273
|
+
location if location is not None else prior_test.location,
|
|
274
|
+
verifies if verifies is not None else prior_test.verifies,
|
|
275
|
+
None
|
|
276
|
+
if clear_result
|
|
277
|
+
else (
|
|
278
|
+
{"classname": result_classname, "name": result_name}
|
|
279
|
+
if result_classname is not None and result_name is not None
|
|
280
|
+
else prior_test.result
|
|
281
|
+
),
|
|
282
|
+
)
|
|
283
|
+
content = database.encode()
|
|
284
|
+
decode(content, project) # Validate all references before writing any bytes.
|
|
285
|
+
if len(content) > 1_048_576:
|
|
286
|
+
raise OpDevError("Requirements exceed the 1048576-byte store limit; nothing written.")
|
|
287
|
+
if not project.unchanged():
|
|
288
|
+
raise OpDevError("Project configuration changed; reload before updating requirements.")
|
|
289
|
+
if not plan:
|
|
290
|
+
replace_checked(contained_path(project.root, STORE), raw, content)
|
|
291
|
+
return {
|
|
292
|
+
"operation": f"{'requirement test' if kind == 'test' else kind} {action}",
|
|
293
|
+
"status": "planned" if plan else "saved",
|
|
294
|
+
"id": record_id,
|
|
295
|
+
"revision": revision(raw) if plan else revision(content),
|
|
296
|
+
"previous_revision": revision(raw),
|
|
297
|
+
"detail": LIMITATION
|
|
298
|
+
+ " For feedback, descriptive-only edits do not require rerunning unchanged tests. "
|
|
299
|
+
"Inspect the updated mapping; a saved report still describes its captured catalog. "
|
|
300
|
+
"Required integration/publication checks still run."
|
|
301
|
+
+ (
|
|
302
|
+
" A test record alone does not link a requirement, even when IDs match. "
|
|
303
|
+
"Use opdev requirement link REQUIREMENT TEST, then "
|
|
304
|
+
"opdev requirement show REQUIREMENT --tests to inspect the mapping."
|
|
305
|
+
if kind == "test" and action == "add"
|
|
306
|
+
else ""
|
|
307
|
+
),
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
def _validate_mutation(
|
|
312
|
+
database: Database,
|
|
313
|
+
kind: str,
|
|
314
|
+
action: str,
|
|
315
|
+
record_id: str,
|
|
316
|
+
*,
|
|
317
|
+
parent: str | None,
|
|
318
|
+
clear_parent: bool,
|
|
319
|
+
result_classname: str | None,
|
|
320
|
+
result_name: str | None,
|
|
321
|
+
clear_result: bool,
|
|
322
|
+
changed_fields: tuple[object, ...],
|
|
323
|
+
) -> None:
|
|
324
|
+
if kind not in {"requirement", "test"} or action not in {
|
|
325
|
+
"add",
|
|
326
|
+
"update",
|
|
327
|
+
"delete",
|
|
328
|
+
"link",
|
|
329
|
+
"unlink",
|
|
330
|
+
}:
|
|
331
|
+
raise OpDevError("Unsupported requirements operation.")
|
|
332
|
+
existing = (database.requirements if kind == "requirement" else database.tests).get(record_id)
|
|
333
|
+
if action == "add" and existing is not None:
|
|
334
|
+
raise OpDevError(f"{kind} {record_id} already exists; use update.")
|
|
335
|
+
if action != "add" and existing is None:
|
|
336
|
+
raise OpDevError(f"Unknown {kind}: {record_id}.")
|
|
337
|
+
if parent is not None and clear_parent:
|
|
338
|
+
raise OpDevError("Choose a parent or clear it, not both.")
|
|
339
|
+
if (result_classname is None) != (result_name is None) or (
|
|
340
|
+
clear_result and result_name is not None
|
|
341
|
+
):
|
|
342
|
+
raise OpDevError("Supply both --result-classname and --result-name, or --clear-result.")
|
|
343
|
+
if (
|
|
344
|
+
action == "update"
|
|
345
|
+
and not clear_parent
|
|
346
|
+
and not clear_result
|
|
347
|
+
and all(value is None for value in changed_fields)
|
|
348
|
+
):
|
|
349
|
+
raise OpDevError("An update needs at least one changed field.")
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
def _delete_record(database: Database, kind: str, record_id: str) -> None:
|
|
353
|
+
if kind == "requirement":
|
|
354
|
+
if any(r.parent == record_id for r in database.requirements.values()):
|
|
355
|
+
raise OpDevError("Reparent or remove the children before deleting this requirement.")
|
|
356
|
+
if database.requirements[record_id].tests:
|
|
357
|
+
raise OpDevError("Unlink this requirement's tests before deleting it, or retire it.")
|
|
358
|
+
del database.requirements[record_id]
|
|
359
|
+
else:
|
|
360
|
+
if any(record_id in r.tests for r in database.requirements.values()):
|
|
361
|
+
raise OpDevError("Unlink this test from its requirements before deleting it.")
|
|
362
|
+
del database.tests[record_id]
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
def _change_link(
|
|
366
|
+
database: Database, kind: str, action: str, record_id: str, test_id: str | None
|
|
367
|
+
) -> None:
|
|
368
|
+
if kind != "requirement" or test_id not in database.tests:
|
|
369
|
+
raise OpDevError(f"Unknown test: {test_id}.")
|
|
370
|
+
requirement = database.requirements[record_id]
|
|
371
|
+
links = set(requirement.tests)
|
|
372
|
+
if action == "link":
|
|
373
|
+
links.add(test_id)
|
|
374
|
+
else:
|
|
375
|
+
links.discard(test_id)
|
|
376
|
+
database.requirements[record_id] = replace(requirement, tests=tuple(sorted(links)))
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
def query(
|
|
380
|
+
project: Project,
|
|
381
|
+
kind: str,
|
|
382
|
+
record_id: str | None = None,
|
|
383
|
+
*,
|
|
384
|
+
test_id: str | None = None,
|
|
385
|
+
check: str | None = None,
|
|
386
|
+
state: str | None = None,
|
|
387
|
+
search: str | None = None,
|
|
388
|
+
fields: list[str] | None = None,
|
|
389
|
+
limit: int = 50,
|
|
390
|
+
offset: int = 0,
|
|
391
|
+
parent: str | None = None,
|
|
392
|
+
roots: bool = False,
|
|
393
|
+
tree: bool = False,
|
|
394
|
+
include_tests: bool = False,
|
|
395
|
+
include_requirements: bool = False,
|
|
396
|
+
gaps: bool = False,
|
|
397
|
+
) -> dict[str, object]:
|
|
398
|
+
database, raw = load(project)
|
|
399
|
+
_validate_query_filters(
|
|
400
|
+
project,
|
|
401
|
+
database,
|
|
402
|
+
kind,
|
|
403
|
+
test_id=test_id,
|
|
404
|
+
check=check,
|
|
405
|
+
state=state,
|
|
406
|
+
parent=parent,
|
|
407
|
+
limit=limit,
|
|
408
|
+
offset=offset,
|
|
409
|
+
)
|
|
410
|
+
_validate_query_expansions(
|
|
411
|
+
kind,
|
|
412
|
+
record_id,
|
|
413
|
+
parent=parent,
|
|
414
|
+
roots=roots,
|
|
415
|
+
tree=tree,
|
|
416
|
+
gaps=gaps,
|
|
417
|
+
include_tests=include_tests,
|
|
418
|
+
include_requirements=include_requirements,
|
|
419
|
+
fields=fields,
|
|
420
|
+
)
|
|
421
|
+
records: list[dict[str, Any]] = []
|
|
422
|
+
source: Mapping[str, Requirement | Test] = (
|
|
423
|
+
database.requirements if kind == "requirement" else database.tests
|
|
424
|
+
)
|
|
425
|
+
if record_id is not None and record_id not in source:
|
|
426
|
+
raise OpDevError(f"Unknown {kind}: {record_id}.")
|
|
427
|
+
children: dict[str | None, list[str]] = {}
|
|
428
|
+
for key, requirement in sorted(database.requirements.items()):
|
|
429
|
+
children.setdefault(requirement.parent, []).append(key)
|
|
430
|
+
ordered = _ordered_records(source, children, record_id, tree)
|
|
431
|
+
for key, depth in ordered:
|
|
432
|
+
item = source[key]
|
|
433
|
+
if isinstance(item, Requirement):
|
|
434
|
+
if not _matches_requirement(
|
|
435
|
+
item,
|
|
436
|
+
database,
|
|
437
|
+
parent=parent,
|
|
438
|
+
roots=roots,
|
|
439
|
+
state=state,
|
|
440
|
+
gaps=gaps,
|
|
441
|
+
test_id=test_id,
|
|
442
|
+
check=check,
|
|
443
|
+
):
|
|
444
|
+
continue
|
|
445
|
+
record = _requirement_record(
|
|
446
|
+
key,
|
|
447
|
+
item,
|
|
448
|
+
database,
|
|
449
|
+
project,
|
|
450
|
+
children,
|
|
451
|
+
depth=depth,
|
|
452
|
+
tree=tree,
|
|
453
|
+
gaps=gaps,
|
|
454
|
+
include_tests=include_tests,
|
|
455
|
+
)
|
|
456
|
+
if record is None:
|
|
457
|
+
continue
|
|
458
|
+
else:
|
|
459
|
+
if check is not None and item.check != check:
|
|
460
|
+
continue
|
|
461
|
+
record = _test_record(key, item, database, include_requirements)
|
|
462
|
+
if (
|
|
463
|
+
search is not None
|
|
464
|
+
and search.casefold() not in json.dumps(record, ensure_ascii=False).casefold()
|
|
465
|
+
):
|
|
466
|
+
continue
|
|
467
|
+
records.append(record)
|
|
468
|
+
selected = records[offset : offset + limit]
|
|
469
|
+
if fields is not None:
|
|
470
|
+
selected = [{f: record[f] for f in fields} for record in selected]
|
|
471
|
+
return {
|
|
472
|
+
"operation": f"{'requirement test' if kind == 'test' else kind} "
|
|
473
|
+
+ ("gaps" if gaps else "query"),
|
|
474
|
+
"status": "read",
|
|
475
|
+
"scope": "mappings",
|
|
476
|
+
"revision": revision(raw),
|
|
477
|
+
"store_exists": raw is not None,
|
|
478
|
+
"records": selected,
|
|
479
|
+
"total": len(records),
|
|
480
|
+
"next_offset": offset + limit if offset + limit < len(records) else None,
|
|
481
|
+
"detail": LIMITATION
|
|
482
|
+
+ (
|
|
483
|
+
" Gaps describe direct mappings only, not test adequacy or delivery readiness. "
|
|
484
|
+
"Children do not verify parents; optional checks may be deliberate."
|
|
485
|
+
if gaps
|
|
486
|
+
else ""
|
|
487
|
+
),
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
|
|
491
|
+
def _validate_query_filters(
|
|
492
|
+
project: Project,
|
|
493
|
+
database: Database,
|
|
494
|
+
kind: str,
|
|
495
|
+
*,
|
|
496
|
+
test_id: str | None,
|
|
497
|
+
check: str | None,
|
|
498
|
+
state: str | None,
|
|
499
|
+
parent: str | None,
|
|
500
|
+
limit: int,
|
|
501
|
+
offset: int,
|
|
502
|
+
) -> None:
|
|
503
|
+
if kind not in {"requirement", "test"}:
|
|
504
|
+
raise OpDevError("Unsupported record kind.")
|
|
505
|
+
if not 1 <= limit <= 1000 or offset < 0:
|
|
506
|
+
raise OpDevError("Use a limit from 1 to 1000 and a nonnegative offset.")
|
|
507
|
+
if test_id is not None and test_id not in database.tests:
|
|
508
|
+
raise OpDevError(f"Unknown test: {test_id}.")
|
|
509
|
+
if check is not None and check not in project.commands:
|
|
510
|
+
raise OpDevError(f"Unknown configured command: {check}.")
|
|
511
|
+
if state is not None and state not in STATES:
|
|
512
|
+
raise OpDevError(f"Unknown requirement state: {state}.")
|
|
513
|
+
if parent is not None and parent not in database.requirements:
|
|
514
|
+
raise OpDevError(f"Unknown parent requirement: {parent}.")
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
def _validate_query_expansions(
|
|
518
|
+
kind: str,
|
|
519
|
+
record_id: str | None,
|
|
520
|
+
*,
|
|
521
|
+
parent: str | None,
|
|
522
|
+
roots: bool,
|
|
523
|
+
tree: bool,
|
|
524
|
+
gaps: bool,
|
|
525
|
+
include_tests: bool,
|
|
526
|
+
include_requirements: bool,
|
|
527
|
+
fields: list[str] | None,
|
|
528
|
+
) -> None:
|
|
529
|
+
if parent is not None and roots:
|
|
530
|
+
raise OpDevError("Select a parent or roots, not both.")
|
|
531
|
+
if kind != "requirement" and (tree or gaps or include_tests or parent is not None or roots):
|
|
532
|
+
raise OpDevError("Hierarchy, gaps and test expansion apply to requirements only.")
|
|
533
|
+
if include_requirements and kind != "test":
|
|
534
|
+
raise OpDevError("Reverse requirement expansion applies to tests only.")
|
|
535
|
+
if tree and (record_id is None or gaps or parent is not None or roots):
|
|
536
|
+
raise OpDevError("Select one root requirement for a tree query.")
|
|
537
|
+
available = (
|
|
538
|
+
{"id", "statement", "state", "sources", "tests", "parent", "rationale"}
|
|
539
|
+
if kind == "requirement"
|
|
540
|
+
else {"id", "check", "location", "verifies", "result"}
|
|
541
|
+
)
|
|
542
|
+
if tree:
|
|
543
|
+
available.update({"depth", "children"})
|
|
544
|
+
if include_tests:
|
|
545
|
+
available.add("test_details")
|
|
546
|
+
if include_requirements:
|
|
547
|
+
available.add("requirements")
|
|
548
|
+
if gaps:
|
|
549
|
+
available.update({"mapping_gaps", "children"})
|
|
550
|
+
if fields is not None and (not fields or not set(fields) <= available):
|
|
551
|
+
raise OpDevError(f"Select fields from: {', '.join(sorted(available))}.")
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
def _ordered_records(
|
|
555
|
+
source: Mapping[str, Requirement | Test],
|
|
556
|
+
children: dict[str | None, list[str]],
|
|
557
|
+
record_id: str | None,
|
|
558
|
+
tree: bool,
|
|
559
|
+
) -> list[tuple[str, int]]:
|
|
560
|
+
if not tree:
|
|
561
|
+
return [(record_id, 0)] if record_id is not None else [(key, 0) for key in sorted(source)]
|
|
562
|
+
assert record_id is not None
|
|
563
|
+
ordered = []
|
|
564
|
+
pending = [(record_id, 0)]
|
|
565
|
+
while pending:
|
|
566
|
+
key, depth = pending.pop()
|
|
567
|
+
ordered.append((key, depth))
|
|
568
|
+
pending.extend((child, depth + 1) for child in reversed(children.get(key, [])))
|
|
569
|
+
return ordered
|
|
570
|
+
|
|
571
|
+
|
|
572
|
+
def _matches_requirement(
|
|
573
|
+
item: Requirement,
|
|
574
|
+
database: Database,
|
|
575
|
+
*,
|
|
576
|
+
parent: str | None,
|
|
577
|
+
roots: bool,
|
|
578
|
+
state: str | None,
|
|
579
|
+
gaps: bool,
|
|
580
|
+
test_id: str | None,
|
|
581
|
+
check: str | None,
|
|
582
|
+
) -> bool:
|
|
583
|
+
if (parent is not None and item.parent != parent) or (roots and item.parent is not None):
|
|
584
|
+
return False
|
|
585
|
+
if state is not None and state != item.state:
|
|
586
|
+
return False
|
|
587
|
+
if gaps and state is None and item.state == "retired":
|
|
588
|
+
return False
|
|
589
|
+
if test_id is not None and test_id not in item.tests:
|
|
590
|
+
return False
|
|
591
|
+
if check is not None and not any(database.tests[t].check == check for t in item.tests):
|
|
592
|
+
return False
|
|
593
|
+
return True
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
def _requirement_record(
|
|
597
|
+
key: str,
|
|
598
|
+
item: Requirement,
|
|
599
|
+
database: Database,
|
|
600
|
+
project: Project,
|
|
601
|
+
children: dict[str | None, list[str]],
|
|
602
|
+
*,
|
|
603
|
+
depth: int,
|
|
604
|
+
tree: bool,
|
|
605
|
+
gaps: bool,
|
|
606
|
+
include_tests: bool,
|
|
607
|
+
) -> dict[str, Any] | None:
|
|
608
|
+
record = {"id": key, **asdict(item)}
|
|
609
|
+
if tree:
|
|
610
|
+
record.update(depth=depth, children=children.get(key, []))
|
|
611
|
+
if gaps:
|
|
612
|
+
reasons = []
|
|
613
|
+
if not item.tests:
|
|
614
|
+
reasons.append("no_direct_test_mapping")
|
|
615
|
+
elif not any(database.tests[t].check in project.checks for t in item.tests):
|
|
616
|
+
reasons.append("direct_tests_outside_required_checks")
|
|
617
|
+
if not reasons:
|
|
618
|
+
return None
|
|
619
|
+
record.update(mapping_gaps=reasons, children=children.get(key, []))
|
|
620
|
+
if include_tests:
|
|
621
|
+
record["test_details"] = [
|
|
622
|
+
{
|
|
623
|
+
"id": t,
|
|
624
|
+
**asdict(database.tests[t]),
|
|
625
|
+
"required_check": database.tests[t].check in project.checks,
|
|
626
|
+
}
|
|
627
|
+
for t in item.tests
|
|
628
|
+
]
|
|
629
|
+
return record
|
|
630
|
+
|
|
631
|
+
|
|
632
|
+
def _test_record(
|
|
633
|
+
key: str, item: Test, database: Database, include_requirements: bool
|
|
634
|
+
) -> dict[str, Any]:
|
|
635
|
+
record = {"id": key, **asdict(item)}
|
|
636
|
+
if include_requirements:
|
|
637
|
+
record["requirements"] = [
|
|
638
|
+
{"id": r, "statement": req.statement, "state": req.state}
|
|
639
|
+
for r, req in sorted(database.requirements.items())
|
|
640
|
+
if key in req.tests
|
|
641
|
+
]
|
|
642
|
+
return record
|