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.
Files changed (42) hide show
  1. opdev/__init__.py +1 -0
  2. opdev/__main__.py +3 -0
  3. opdev/checks.py +300 -0
  4. opdev/cli.py +459 -0
  5. opdev/commands.py +76 -0
  6. opdev/config.py +278 -0
  7. opdev/document_catalog.py +107 -0
  8. opdev/document_review.py +115 -0
  9. opdev/documents.py +415 -0
  10. opdev/errors.py +5 -0
  11. opdev/files.py +82 -0
  12. opdev/init.py +87 -0
  13. opdev/junit.py +99 -0
  14. opdev/output.py +141 -0
  15. opdev/process.py +145 -0
  16. opdev/providers/__init__.py +1 -0
  17. opdev/providers/gitlab.py +374 -0
  18. opdev/publication.py +209 -0
  19. opdev/reports.py +512 -0
  20. opdev/requirements.py +642 -0
  21. opdev/resources/reports/report.css +158 -0
  22. opdev/resources/reports/report.html +27 -0
  23. opdev/resources/reports/report.js +110 -0
  24. opdev/resources/skills/opdev/SKILL.md +190 -0
  25. opdev/resources/skills/opdev/references/adoption.md +144 -0
  26. opdev/resources/skills/opdev/references/design.md +141 -0
  27. opdev/resources/skills/opdev/references/development.md +294 -0
  28. opdev/resources/skills/opdev/references/engineering.md +206 -0
  29. opdev/resources/skills/opdev/references/planning.md +101 -0
  30. opdev/resources/skills/opdev/references/publication.md +34 -0
  31. opdev/resources/templates/AGENTS.md +7 -0
  32. opdev/resources/templates/CLAUDE.md +6 -0
  33. opdev/resources/templates/guidance.md +36 -0
  34. opdev/snapshot.py +484 -0
  35. opdev/tracking.py +224 -0
  36. opdev/verification.py +234 -0
  37. opdev/version.py +45 -0
  38. opdev-0.7.0a2.dist-info/METADATA +99 -0
  39. opdev-0.7.0a2.dist-info/RECORD +42 -0
  40. opdev-0.7.0a2.dist-info/WHEEL +4 -0
  41. opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
  42. 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