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/reports.py ADDED
@@ -0,0 +1,512 @@
1
+ """Two views of one validated snapshot. Rendering performs no project operations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import hashlib
7
+ import html
8
+ import re
9
+ from importlib.resources import files
10
+ from string import Template
11
+ from typing import Any
12
+
13
+ from opdev.requirements import Database, Test
14
+ from opdev.verification import (
15
+ RequirementResult,
16
+ TestResults,
17
+ assess,
18
+ mapped_outcomes,
19
+ requirement_results,
20
+ )
21
+
22
+ LIMITS = (
23
+ "Reported tests support review; they do not prove assertion adequacy, complete coverage, "
24
+ "hidden retry history or approval. Source content was not captured. This is an unsigned "
25
+ "record of one run, not current verification or release authorization."
26
+ )
27
+ LABELS = {
28
+ "mapped_tests_passed": "Mapped tests passed",
29
+ "incomplete": "Verification gaps",
30
+ "not_run": "Not run",
31
+ "not_selected": "Not selected",
32
+ "unverified": "Unverified",
33
+ "command_failed": "Case passed; command did not",
34
+ "timed_out": "Timed out",
35
+ }
36
+
37
+
38
+ def label(value: str) -> str:
39
+ return LABELS.get(value, value.replace("_", " ").capitalize())
40
+
41
+
42
+ def esc(value: object) -> str:
43
+ return html.escape(str(value), quote=True)
44
+
45
+
46
+ def md(value: object) -> str:
47
+ # Authored content is text, never executable HTML, Markdown links or images.
48
+ return re.sub(
49
+ r"([\\`*_{}\[\]()#+.!|>-])", r"\\\1", html.escape(str(value), quote=False)
50
+ ).replace("\n", " ")
51
+
52
+
53
+ def results(
54
+ database: Database, outcomes: dict[str, tuple[str, TestResults | None]], unchanged: bool
55
+ ) -> list[RequirementResult]:
56
+ return requirement_results(database, outcomes if unchanged else {}, include_all=True)
57
+
58
+
59
+ def scope_text(data: dict[str, Any]) -> str:
60
+ if data["schema"] == "opdev-report/1":
61
+ return (
62
+ "Legacy snapshot: its full-check flag describes commands only, "
63
+ "not the active-requirement gate."
64
+ )
65
+ if data["full_check_passed"]:
66
+ return (
67
+ "Document structure, required checks and directly mapped active tests "
68
+ "passed in this run."
69
+ if data["schema"] == "opdev-report/3"
70
+ else "All required checks and directly mapped active tests passed in this run. "
71
+ "Document structure was not captured by this snapshot format."
72
+ )
73
+ if data["scope"] == "full":
74
+ return (
75
+ "Full verification did not pass. "
76
+ "Inspect document findings, command outcomes and active requirement blockers below."
77
+ )
78
+ return "Selected commands only; full verification was not performed."
79
+
80
+
81
+ def requirement_status(item: RequirementResult, database: Database, unchanged: bool) -> str:
82
+ if not unchanged:
83
+ return "Input changed; verification withheld"
84
+ if not database.requirements[item.id].tests:
85
+ return "No mapped tests"
86
+ return label(item.status)
87
+
88
+
89
+ def metadata(data: dict[str, Any]) -> list[tuple[str, str]]:
90
+ return [
91
+ ("Run", data["run_id"]),
92
+ ("Started", data["started_at"]),
93
+ ("Finished", data["finished_at"]),
94
+ ("Tool", f"OpDev {data['tool']['version']} ({data['tool']['implementation']})"),
95
+ ("Configuration SHA-256", data["config_sha256"]),
96
+ ("Requirements revision", data["requirements_revision"]),
97
+ ("Workflow SHA-256", data["tool"]["workflow_sha256"]),
98
+ ("Source binding", "Not captured"),
99
+ ]
100
+
101
+
102
+ def test_identity(test: Test) -> str:
103
+ return (
104
+ f"{test.result['classname']} / {test.result['name']}"
105
+ if test.result
106
+ else ("No named-test result selector. Command success cannot verify this test.")
107
+ )
108
+
109
+
110
+ def no_cases_text(command: dict[str, Any]) -> str:
111
+ if command["status"] in {"not_selected", "not_run"}:
112
+ return "This command did not run; no test results were observed."
113
+ if command["results"] is None:
114
+ return "Named-test reporting is not configured; command success cannot verify tests."
115
+ return "No usable cases observed. Check the original command logs for diagnosis."
116
+
117
+
118
+ def markdown(
119
+ data: dict[str, Any], database: Database, rows: list[RequirementResult], tests: dict[str, str]
120
+ ) -> str:
121
+ lines = [
122
+ "# OpDev verification report",
123
+ "",
124
+ f"**Verification outcome: {label(data['verdict'])}.**",
125
+ f"Active requirement verification: {label(data['assessment'].status)}.",
126
+ f"Run outcome: {label(data['status'])}.",
127
+ f"{data['operation']} · {data['scope']}. {scope_text(data)}",
128
+ "",
129
+ LIMITS,
130
+ "",
131
+ ]
132
+ assessment = data["assessment"]
133
+ lines += [
134
+ f"**{assessment.passed}/{assessment.active} active requirements passed; "
135
+ f"{assessment.incomplete} incomplete.**",
136
+ "",
137
+ ]
138
+ if assessment.findings:
139
+ lines += ["## Verification blockers", ""]
140
+ for finding in assessment.findings:
141
+ identity = " / ".join(
142
+ v for v in (finding.requirement, finding.test, finding.command) if v
143
+ )
144
+ lines += [
145
+ f"- **{md(identity or 'catalog')} [{md(finding.code)}]**: {md(finding.detail)}"
146
+ ]
147
+ lines += [""]
148
+ lines += _markdown_documents(data)
149
+ if not data["inputs_unchanged"]:
150
+ lines += [
151
+ "**Configuration, document inputs or mappings changed during the "
152
+ "run. Requirement verification is withheld.**",
153
+ "",
154
+ ]
155
+ lines += [
156
+ "## Requirements",
157
+ "",
158
+ "Each result uses only directly mapped tests. Parent "
159
+ "requirements do not inherit child results. Proposed "
160
+ "and retired obligations remain separate from active "
161
+ "work.",
162
+ "",
163
+ ]
164
+ lines += _markdown_requirements(database, rows, data["inputs_unchanged"])
165
+ lines += [
166
+ "## Commands",
167
+ "",
168
+ "All declared commands are listed; only selected commands were requested.",
169
+ "",
170
+ "| Command | Purpose | Required | Selected | Outcome | Exit | Seconds |",
171
+ "| --- | --- | --- | --- | --- | --- | --- |",
172
+ ]
173
+ for command in data["commands"]:
174
+ lines.append(
175
+ "| "
176
+ + " | ".join(
177
+ md(v)
178
+ for v in (
179
+ command["id"],
180
+ command["purpose"],
181
+ "yes" if command["required"] else "no",
182
+ "yes" if command["selected"] else "no",
183
+ label(command["status"]),
184
+ command["exit_code"] if command["exit_code"] is not None else "—",
185
+ f"{command['duration_seconds']:.3f}",
186
+ )
187
+ )
188
+ + " |"
189
+ )
190
+ for command in data["commands"]:
191
+ observed = command["test_results"]
192
+ if observed or any(test.check == command["id"] for test in database.tests.values()):
193
+ lines += [
194
+ "",
195
+ f"### Reported cases: {md(command['id'])}",
196
+ "",
197
+ (
198
+ f"JUnit observation: {label(observed['status'])}. "
199
+ f"SHA-256: {observed['sha256'] or 'not captured'}."
200
+ if observed
201
+ else "No test results observed for this command."
202
+ ),
203
+ "",
204
+ ]
205
+ lines += ["Expected mapped tests (including tests without requirement links):", ""]
206
+ lines += [
207
+ f"- {md(key)} — {label(tests[key])}; {md(test_identity(test))}. "
208
+ f"Intent: {md(test.verifies)}"
209
+ for key, test in database.tests.items()
210
+ if test.check == command["id"]
211
+ ]
212
+ lines += ["", "Reported cases:", ""]
213
+ lines += [
214
+ f"- {md(c['classname'])} / {md(c['name'])} — {label(c['status'])}."
215
+ for c in (observed["cases"] if observed else [])
216
+ ]
217
+ if not observed or not observed["cases"]:
218
+ lines += [no_cases_text(command)]
219
+ lines += ["", "## Run details", ""]
220
+ lines += [f"- {key}: {md(value)}" for key, value in metadata(data)]
221
+ lines += [
222
+ "",
223
+ "Fingerprints identify inputs; they do not authenticate this record. "
224
+ "Source links and absolute test locations are omitted.",
225
+ ]
226
+ return "\n".join(lines) + "\n"
227
+
228
+
229
+ def _markdown_requirements(
230
+ database: Database, rows: list[RequirementResult], unchanged: bool
231
+ ) -> list[str]:
232
+ """Render direct requirement results without conflating command or run status."""
233
+ lines: list[str] = []
234
+ if not rows:
235
+ lines += ["No requirements were recorded for this run.", ""]
236
+ for item in rows:
237
+ req = database.requirements[item.id]
238
+ lines += [
239
+ f"### {md(item.id)}",
240
+ "",
241
+ md(req.statement),
242
+ "",
243
+ f"**{label(req.state)} · {requirement_status(item, database, unchanged)}**",
244
+ "",
245
+ ]
246
+ if req.parent:
247
+ lines += [f"Parent: {md(req.parent)}. No inherited result.", ""]
248
+ if req.rationale:
249
+ lines += [f"Rationale: {md(req.rationale)}", ""]
250
+ for test in item.tests:
251
+ mapped = database.tests[test.id]
252
+ status = label(test.status) if unchanged else "Unverified: inputs changed"
253
+ lines += [
254
+ f"- **{md(test.id)} — {status}**; command: {md(mapped.check)}.",
255
+ f" Intent: {md(mapped.verifies)}",
256
+ f" Location: {md(mapped.location)}",
257
+ ]
258
+ lines += [
259
+ f" JUnit identity: {md(mapped.result['classname'])} / {md(mapped.result['name'])}."
260
+ if mapped.result
261
+ else " No named-test result selector; command success cannot verify this test."
262
+ ]
263
+ lines += [""]
264
+ return lines
265
+
266
+
267
+ def badge(status: str) -> str:
268
+ tone = "pass" if status in {"passed", "mapped_tests_passed"} else "gap"
269
+ return f'<span class="badge {tone}">{esc(label(status))}</span>'
270
+
271
+
272
+ def requirement_tree(
273
+ data: dict[str, Any], database: Database, rows: list[RequirementResult]
274
+ ) -> str:
275
+ """Render the complete explicit-parent tree; JavaScript only enhances reading."""
276
+ by_id = {item.id: item for item in rows}
277
+ dom_ids = {item.id: f"requirement-{index}" for index, item in enumerate(rows)}
278
+ children: dict[str | None, list[str]] = {}
279
+ for key in sorted(by_id):
280
+ children.setdefault(database.requirements[key].parent, []).append(key)
281
+ pending = [(key, 0) for key in reversed(children.get(None, []))]
282
+ rendered = []
283
+ # Iterative traversal also handles valid deeply nested catalogs.
284
+ while pending:
285
+ key, depth = pending.pop()
286
+ item = by_id[key]
287
+ pending.extend((child, depth + 1) for child in reversed(children.get(key, [])))
288
+ req = database.requirements[item.id]
289
+ status = requirement_status(item, database, data["inputs_unchanged"])
290
+ tests = []
291
+ for test in item.tests:
292
+ mapped = database.tests[test.id]
293
+ identity = test_identity(mapped)
294
+ tests.append(
295
+ f'<li><div class="test-heading"><strong>{esc(test.id)}</strong> '
296
+ f"{badge(test.status if data['inputs_unchanged'] else 'unverified')}</div>"
297
+ f"<p>{esc(mapped.verifies)}</p><dl><dt>Command</dt><dd>{esc(mapped.check)}</dd>"
298
+ f"<dt>Location</dt><dd>{esc(mapped.location)}</dd>"
299
+ f"<dt>JUnit identity</dt><dd>{esc(identity)}</dd></dl></li>"
300
+ )
301
+ parent = (
302
+ f"<p>Parent: <strong>{esc(req.parent)}</strong>. No inherited result.</p>"
303
+ if req.parent
304
+ else ""
305
+ )
306
+ rationale = (
307
+ f"<p><strong>Rationale:</strong> {esc(req.rationale)}</p>" if req.rationale else ""
308
+ )
309
+ gap = item.status != "mapped_tests_passed" or not data["inputs_unchanged"]
310
+ toggle = (
311
+ f'<button type="button" class="branch" aria-expanded="true" '
312
+ f'aria-label="Collapse {esc(item.id)} descendants" hidden>▾</button>'
313
+ if children.get(key)
314
+ else '<span class="leaf" aria-hidden="true"></span>'
315
+ )
316
+ passed = sum(test.status == "passed" for test in item.tests)
317
+ direct = (
318
+ f"{passed} / {len(item.tests)}"
319
+ if data["inputs_unchanged"] and item.tests
320
+ else ("Withheld" if not data["inputs_unchanged"] else "—")
321
+ )
322
+ rendered.append(
323
+ f'<tr class="requirement{" root" if not req.parent else ""}" '
324
+ f'id="{dom_ids[key]}" data-key="{esc(key)}" '
325
+ f'data-parent="{dom_ids[req.parent] if req.parent else ""}" '
326
+ f'data-state="{req.state}" data-gap="{str(gap).lower()}">'
327
+ f'<td class="id-cell"><div class="id-content" style="--depth:{depth}">'
328
+ f'{toggle}<span class="req-id">{esc(key)}</span></div></td>'
329
+ f'<td class="obligation"><details><summary title="{esc(req.statement)}" '
330
+ f'aria-label="Inspect {esc(key)}: {esc(req.statement)}">'
331
+ f'<span class="statement">{esc(req.statement)}</span>'
332
+ '<span class="context-label">Parent context</span></summary>'
333
+ f'<div class="req-body"><p class="full-statement">{esc(req.statement)}</p>'
334
+ f"{parent}{rationale}<h3>Direct test mappings</h3>"
335
+ + (
336
+ f'<ul class="tests">{"".join(tests)}</ul>'
337
+ if tests
338
+ else "<p>No tests mapped. This obligation is unverified.</p>"
339
+ )
340
+ + f'</div></details></td><td class="direct-count">{direct}</td>'
341
+ f'<td><span class="result {"gap" if gap else "pass"}">{esc(status)}</span></td>'
342
+ f'<td class="lifecycle">{label(req.state)}</td></tr>'
343
+ )
344
+ return "".join(rendered)
345
+
346
+
347
+ def web(
348
+ data: dict[str, Any],
349
+ database: Database,
350
+ rows: list[RequirementResult],
351
+ test_outcomes: dict[str, str],
352
+ ) -> str:
353
+ resource = files("opdev").joinpath("resources/reports")
354
+ css = resource.joinpath("report.css").read_text(encoding="utf-8")
355
+ js = resource.joinpath("report.js").read_text(encoding="utf-8")
356
+ digest = base64.b64encode(hashlib.sha256(js.encode()).digest()).decode()
357
+ commands = []
358
+ cases = []
359
+ for c in data["commands"]:
360
+ commands.append(
361
+ "<tr>"
362
+ + "".join(
363
+ f"<td>{v}</td>"
364
+ for v in (
365
+ f"<strong>{esc(c['id'])}</strong>",
366
+ esc(c["purpose"]),
367
+ "Yes" if c["required"] else "No",
368
+ "Yes" if c["selected"] else "No",
369
+ badge(c["status"]),
370
+ esc(c["exit_code"] if c["exit_code"] is not None else "—"),
371
+ f"{c['duration_seconds']:.3f}",
372
+ )
373
+ )
374
+ + "</tr>"
375
+ )
376
+ observed = c["test_results"]
377
+ if observed or any(test.check == c["id"] for test in database.tests.values()):
378
+ expected = "".join(
379
+ f"<li><strong>{esc(key)}</strong> {badge(test_outcomes[key])}"
380
+ f"<p>{esc(test_identity(test))}</p><p>{esc(test.verifies)}</p></li>"
381
+ for key, test in database.tests.items()
382
+ if test.check == c["id"]
383
+ )
384
+ entries = "".join(
385
+ f"<li><code>{esc(case['classname'])} / {esc(case['name'])}</code> "
386
+ f"{badge(case['status'])}</li>"
387
+ for case in (observed["cases"] if observed else [])
388
+ )
389
+ cases.append(
390
+ f'<details class="cases"><summary>{esc(c["id"])}: '
391
+ f"{len(observed['cases']) if observed else 0} reported cases — "
392
+ f"{label(observed['status']) if observed else 'Not observed'}</summary>"
393
+ "<p>JUnit SHA-256: <code>"
394
+ f"{esc((observed['sha256'] if observed else None) or 'not captured')}</code></p>"
395
+ "<h3>Expected mapped tests</h3><p>Includes tests without requirement links.</p>"
396
+ + (f"<ul>{expected}</ul>" if expected else "<p>No expected test mappings.</p>")
397
+ + "<h3>Reported cases</h3>"
398
+ + (f"<ul>{entries}</ul>" if entries else f"<p>{esc(no_cases_text(c))}</p>")
399
+ + "</details>"
400
+ )
401
+ details = "".join(f"<dt>{esc(k)}</dt><dd>{esc(v)}</dd>" for k, v in metadata(data))
402
+ assessment = data["assessment"]
403
+ blockers = (
404
+ '<section id="blockers" aria-labelledby="blockers-heading">'
405
+ '<h2 id="blockers-heading">Verification blockers</h2><ul>'
406
+ + "".join(
407
+ "<li><strong>"
408
+ + esc(" / ".join(v for v in (f.requirement, f.test, f.command) if v) or "catalog")
409
+ + f" [{esc(f.code)}]</strong>: {esc(f.detail)}</li>"
410
+ for f in assessment.findings
411
+ )
412
+ + "</ul></section>"
413
+ if assessment.findings
414
+ else ""
415
+ )
416
+ document = data.get("documents")
417
+ if document:
418
+ blockers += '<section aria-label="Document structure"><h2>Document structure</h2>'
419
+ blockers += f"<p>{esc(label(document['status']))}. Approval not assessed.</p>"
420
+ blockers += (
421
+ "<ul>"
422
+ + "".join(
423
+ f"<li>{esc(f['path'])} [{esc(f['code'])}]: "
424
+ f"{esc(f['message'])} {esc(f['remedy'])}</li>"
425
+ for f in document["findings"]
426
+ )
427
+ + "</ul></section>"
428
+ )
429
+ warning = (
430
+ '<p class="warning" role="note">Configuration, document inputs or '
431
+ "mappings changed during the run. Requirement verification "
432
+ "is withheld.</p>"
433
+ if not data["inputs_unchanged"]
434
+ else ""
435
+ )
436
+ template = Template(resource.joinpath("report.html").read_text(encoding="utf-8"))
437
+ return template.substitute(
438
+ digest=digest,
439
+ run_id=esc(data["run_id"]),
440
+ css=css,
441
+ outcome=badge(data["verdict"]),
442
+ blockers=blockers,
443
+ run_outcome=esc(label(data["status"])),
444
+ operation=esc(data["operation"]),
445
+ scope=esc(data["scope"]),
446
+ scope_text=scope_text(data),
447
+ warning=warning,
448
+ limits=LIMITS,
449
+ total=len(rows),
450
+ passed=assessment.passed,
451
+ active=assessment.active,
452
+ incomplete=assessment.incomplete,
453
+ required_passed=sum(c["required"] and c["status"] == "passed" for c in data["commands"]),
454
+ required_total=sum(c["required"] for c in data["commands"]),
455
+ finished=esc(data["finished_at"]),
456
+ tree=requirement_tree(data, database, rows),
457
+ empty_hidden="" if not rows else "hidden",
458
+ empty_text="No requirements were recorded for this run."
459
+ if not rows
460
+ else "No requirements match these filters. Clear the filters to see all requirements.",
461
+ commands="".join(commands),
462
+ cases="".join(cases),
463
+ details=details,
464
+ js=js,
465
+ )
466
+
467
+
468
+ def render(
469
+ data: dict[str, Any],
470
+ database: Database,
471
+ outcomes: dict[str, tuple[str, TestResults | None]],
472
+ *,
473
+ format: str,
474
+ ) -> str:
475
+ data = {
476
+ **data,
477
+ "assessment": assess(
478
+ database,
479
+ outcomes,
480
+ catalog_present=data["requirements_revision"] != "absent",
481
+ inputs_unchanged=data["inputs_unchanged"],
482
+ ),
483
+ }
484
+ data["verdict"] = (
485
+ data["assessment"].status if data["status"] in {"passed", "incomplete"} else data["status"]
486
+ )
487
+ rows = results(database, outcomes, data["inputs_unchanged"])
488
+ tests = (
489
+ mapped_outcomes(database, outcomes)
490
+ if data["inputs_unchanged"]
491
+ else {key: "unverified" for key in database.tests}
492
+ )
493
+ return (
494
+ web(data, database, rows, tests)
495
+ if format == "html"
496
+ else markdown(data, database, rows, tests)
497
+ )
498
+
499
+
500
+ def _markdown_documents(data: dict[str, Any]) -> list[str]:
501
+ lines: list[str] = []
502
+ document = data.get("documents")
503
+ if document:
504
+ lines += ["", f"Document structure: **{md(document['status'])}**. Approval not assessed."]
505
+ if document["findings"]:
506
+ lines.append("")
507
+ for finding in document["findings"]:
508
+ lines.append(
509
+ f"- {md(finding['path'])} [{md(finding['code'])}]: "
510
+ f"{md(finding['message'])} {md(finding['remedy'])}"
511
+ )
512
+ return lines