okstra 0.231.1 → 0.233.0

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 (265) hide show
  1. package/README.md +19 -271
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -0,0 +1,359 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import json
5
+ from pathlib import Path, PurePosixPath
6
+ from typing import Mapping, Sequence, cast
7
+
8
+ from .json_boundary import load_owned_object
9
+ from .qa_procedures import canonical_json_digest, content_digest
10
+ from .qa_commands import QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid
11
+ from .paths import find_asset_root
12
+ from .verification_input_types import FrozenProcedure, FrozenReviewPolicy
13
+
14
+
15
+ def capture_review_policy(
16
+ project: Path, config: Mapping[str, object], *, additional_sources: Sequence[Path] = (),
17
+ ) -> FrozenReviewPolicy:
18
+ architecture = config.get("architecture", {})
19
+ if not isinstance(architecture, dict):
20
+ raise ValueError("review policy: architecture must be an object")
21
+ style = architecture.get("style", "undeclared")
22
+ if style not in ("undeclared", "none", "layered", "hexagonal"):
23
+ raise ValueError("review policy: invalid architecture style")
24
+ declared = config.get("reviewRulePacks", [])
25
+ if not isinstance(declared, list):
26
+ raise ValueError("review policy: reviewRulePacks must be a list")
27
+ paths = [project / name for name in ("AGENTS.md", "CLAUDE.md")
28
+ if (project / name).exists()]
29
+ paths.extend(additional_sources)
30
+ for entry in declared:
31
+ if not isinstance(entry, str) or not entry.strip():
32
+ raise ValueError("review policy: rule path must be a non-blank string")
33
+ path = Path(entry).expanduser()
34
+ if not path.is_absolute():
35
+ raise ValueError("review policy: rule path must be absolute")
36
+ paths.append(path)
37
+ sources: dict[str, FrozenProcedure] = {}
38
+ for path in dict.fromkeys(paths):
39
+ _capture_rule_source(path, sources)
40
+ root = find_asset_root(("prompts", "coding-preflight", "review-rules.json"))
41
+ if root is None:
42
+ raise ValueError("review policy: coding preflight catalog is unavailable")
43
+ pack = root / "prompts" / "coding-preflight"
44
+ for path in sorted(pack.rglob("*.md")):
45
+ _capture_rule_source(path, sources)
46
+ _capture_rule_source(pack / "review-rules.json", sources)
47
+ return {"schemaVersion": "1.0", "architecture": style, "sources": sources}
48
+
49
+
50
+ def _capture_rule_source(path: Path, sources: dict[str, FrozenProcedure]) -> None:
51
+ identity = str(path.absolute())
52
+ if identity in sources:
53
+ return
54
+ try:
55
+ raw = path.read_bytes()
56
+ body = raw.decode("utf-8")
57
+ except (OSError, UnicodeError) as exc:
58
+ raise ValueError(f"review policy: cannot read {path}: {exc}") from exc
59
+ sources[identity] = {"body": body, "digest": content_digest(raw)}
60
+ for reference in re.findall(r"\]\((references/[^)\s#]+\.md)(?:#[^)]*)?\)", body):
61
+ relative = Path(reference)
62
+ if ".." in relative.parts:
63
+ raise ValueError(f"review policy: reference escapes rule directory: {reference}")
64
+ _capture_rule_source(path.parent / relative, sources)
65
+
66
+
67
+ def review_policy_errors(policy: object) -> list[str]:
68
+ required = {"schemaVersion", "architecture", "sources"}
69
+ if (not isinstance(policy, dict) or not required.issubset(policy)
70
+ or set(policy).difference(required | {"authorPolicyDigest"})):
71
+ return ["review policy: invalid fields"]
72
+ if "authorPolicyDigest" in policy and (
73
+ not isinstance(policy["authorPolicyDigest"], str)
74
+ or not QA_SOURCE_DIGEST_PATTERN.fullmatch(policy["authorPolicyDigest"])):
75
+ return ["review policy: invalid author policy digest"]
76
+ if policy["schemaVersion"] != "1.0":
77
+ return ["review policy: unsupported version"]
78
+ if policy["architecture"] not in ("undeclared", "none", "layered", "hexagonal"):
79
+ return ["review policy: invalid architecture style"]
80
+ sources = policy["sources"]
81
+ if not isinstance(sources, dict):
82
+ return ["review policy: sources must be an object"]
83
+ for path, source in sources.items():
84
+ if not isinstance(path, str) or not Path(path).is_absolute():
85
+ return ["review policy: source path must be absolute"]
86
+ if (not isinstance(source, dict) or set(source) != {"body", "digest"}
87
+ or not isinstance(source["body"], str)):
88
+ return ["review policy: invalid source"]
89
+ if content_digest(source["body"].encode("utf-8")) != source["digest"]:
90
+ return [f"review policy: source digest mismatch: {path}"]
91
+ return []
92
+
93
+
94
+ def read_review_policy(path: Path) -> FrozenReviewPolicy:
95
+ return cast(FrozenReviewPolicy, load_owned_object(
96
+ path, artifact="frozen review policy", schema={"type": "object"},
97
+ validate_cross_fields=review_policy_errors,
98
+ ))
99
+
100
+
101
+ def publish_review_policy(
102
+ project: Path, destination: Path, policy: FrozenReviewPolicy,
103
+ ) -> tuple[Path, str]:
104
+ from .verification_inputs import publish_verification_snapshot
105
+
106
+ return publish_verification_snapshot(
107
+ project, destination, capture=lambda: dict(policy), artifact="frozen review policy",
108
+ schema={"type": "object"}, validate_cross_fields=review_policy_errors,
109
+ comparison_key=dict,
110
+ )
111
+
112
+
113
+ def code_review_guidance_paths(policy: FrozenReviewPolicy) -> tuple[str, ...]:
114
+ paths: list[str] = []
115
+ for source in policy["sources"]:
116
+ if source.endswith("/skills/okstra-code-review/SKILL.md"):
117
+ folder = Path(source).parent
118
+ paths.extend(str(path) for path in (
119
+ folder / "SKILL.md", folder / "references/census-rules.md",
120
+ folder / "references/review-calibration.md",
121
+ ) if str(path) in policy["sources"])
122
+ return tuple(paths)
123
+
124
+
125
+ def capture_code_review_policy(
126
+ project: Path, config: Mapping[str, object], *,
127
+ additional_sources: Sequence[Path] = (), policy: FrozenReviewPolicy | None = None,
128
+ ) -> FrozenReviewPolicy:
129
+ root = find_asset_root(("skills", "okstra-code-review", "SKILL.md"))
130
+ skill = ((root / "skills/okstra-code-review") if root
131
+ else Path.home() / ".agents/skills/okstra-code-review")
132
+ sources = (skill / "SKILL.md", skill / "references/census-rules.md",
133
+ skill / "references/review-calibration.md", *additional_sources)
134
+ if policy is None:
135
+ policy = capture_review_policy(project, config)
136
+ errors = review_policy_errors(policy)
137
+ if errors:
138
+ raise ValueError("; ".join(errors))
139
+ captured = {path: dict(source) for path, source in policy["sources"].items()}
140
+ for source in sources:
141
+ _capture_rule_source(source, captured)
142
+ return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
143
+ "sources": captured, "authorPolicyDigest": canonical_json_digest(policy)}
144
+
145
+
146
+ def render_review_rule_catalog(policy: FrozenReviewPolicy) -> str:
147
+ from .code_review_census import render_rule_catalog
148
+
149
+ path = review_policy_catalog_path(policy)
150
+ root = str(path.parent)
151
+ catalog = policy["sources"][str(path)]
152
+ return render_rule_catalog(
153
+ catalog["body"], Path(root),
154
+ include_architecture=root + "/architectures/hexagonal.md" in policy["sources"],
155
+ )
156
+
157
+
158
+ _LANGUAGE_SUFFIXES = {
159
+ ".js": "javascript-typescript", ".jsx": "javascript-typescript",
160
+ ".ts": "javascript-typescript", ".tsx": "javascript-typescript",
161
+ ".mjs": "javascript-typescript", ".cjs": "javascript-typescript",
162
+ ".mts": "javascript-typescript", ".cts": "javascript-typescript",
163
+ ".py": "python", ".rs": "rust", ".java": "java",
164
+ ".kt": "kotlin", ".kts": "kotlin", ".sql": "sql",
165
+ }
166
+ _LANGUAGE_MANIFESTS = {
167
+ "package.json": "javascript-typescript", "pyproject.toml": "python",
168
+ "requirements.txt": "python", "setup.py": "python", "setup.cfg": "python",
169
+ "Cargo.toml": "rust", "pom.xml": "java", "build.gradle": "java",
170
+ "build.gradle.kts": "kotlin",
171
+ }
172
+
173
+
174
+ def review_policy_catalog_path(policy: FrozenReviewPolicy) -> Path:
175
+ paths = [Path(path) for path in policy["sources"]
176
+ if path.endswith("/prompts/coding-preflight/review-rules.json")]
177
+ if len(paths) != 1:
178
+ raise ValueError("required frozen review resource is missing or ambiguous: review-rules.json")
179
+ return paths[0]
180
+
181
+
182
+ def _language_resources(source_paths: Sequence[str]) -> set[str]:
183
+ languages: set[str] = set()
184
+ for source in source_paths:
185
+ path = PurePosixPath(source)
186
+ if not qa_relative_path_valid(source):
187
+ raise ValueError("review source paths must be repository-relative")
188
+ language = _LANGUAGE_SUFFIXES.get(path.suffix) or _LANGUAGE_MANIFESTS.get(path.name)
189
+ if language:
190
+ languages.add(language)
191
+ if ("migration" in source.lower() or path.name == "schema.prisma"):
192
+ languages.add("sql")
193
+ return {f"languages/{language}.md" for language in languages}
194
+
195
+
196
+ def review_policy_context(
197
+ project: Path, head: str, source_paths: Sequence[str], *, base: str = "",
198
+ ) -> tuple[tuple[str, ...], dict[str, str]]:
199
+ paths, manifests, _ = _review_context_side(project, head, source_paths)
200
+ if base:
201
+ previous, old_manifests, commit = _review_context_side(project, base, source_paths)
202
+ paths = tuple(dict.fromkeys((*paths, *previous)))
203
+ for path, body in old_manifests.items():
204
+ if manifests.get(path) != body:
205
+ manifests[f"base:{commit}/{path}"] = body
206
+ return paths, manifests
207
+
208
+
209
+ def _review_context_side(
210
+ project: Path, head: str, source_paths: Sequence[str],
211
+ ) -> tuple[tuple[str, ...], dict[str, str], str]:
212
+ from .review_verdicts import _head_tree
213
+
214
+ _language_resources(source_paths)
215
+ tree = _head_tree(project, head)
216
+ files = tree._git("ls-tree", "-r", "--name-only", tree.commit)
217
+ if files.returncode:
218
+ raise ValueError("cannot read the frozen review project layout")
219
+ paths = tuple(files.stdout.decode("utf-8").splitlines())
220
+ manifests: set[str] = set()
221
+ for source in source_paths:
222
+ directory = PurePosixPath(source).parent
223
+ for parent in (directory, *directory.parents):
224
+ candidate = (parent / "package.json").as_posix()
225
+ if candidate in paths:
226
+ manifests.add(candidate)
227
+ break
228
+ contents: dict[str, str] = {}
229
+ for manifest in sorted(manifests):
230
+ result = tree._git("show", f"{tree.commit}:{manifest}")
231
+ if result.returncode:
232
+ raise ValueError("cannot read the frozen review package manifest")
233
+ contents[manifest] = result.stdout.decode("utf-8")
234
+ return paths, contents, tree.commit
235
+
236
+
237
+ def _node_server_work(source_paths: Sequence[str], manifests: Mapping[str, str]) -> bool:
238
+ if any(PurePosixPath(path).suffix in (".mjs", ".cjs", ".mts", ".cts")
239
+ or PurePosixPath(path).name in ("server.js", "server.ts", "nest-cli.json")
240
+ or any(part in ("server", "api", "controllers", "commands")
241
+ for part in PurePosixPath(path).parts) for path in source_paths):
242
+ return True
243
+ for path, body in manifests.items():
244
+ if PurePosixPath(path).name != "package.json":
245
+ continue
246
+ package = json.loads(body)
247
+ if not isinstance(package, dict):
248
+ raise ValueError("review package manifest must be an object")
249
+ dependencies = package.get("dependencies", {})
250
+ dev_dependencies = package.get("devDependencies", {})
251
+ if not isinstance(dependencies, dict) or not isinstance(dev_dependencies, dict):
252
+ raise ValueError("review package dependencies must be objects")
253
+ dependencies = {**dependencies, **dev_dependencies}
254
+ if any(name in ("express", "fastify", "koa", "hapi") or name.startswith("@nestjs/")
255
+ for name in dependencies):
256
+ return True
257
+ if package.get("bin"):
258
+ return True
259
+ return False
260
+
261
+
262
+ def _hexagonal_work(policy: FrozenReviewPolicy, project_paths: Sequence[str]) -> bool:
263
+ style = policy["architecture"]
264
+ if style != "undeclared":
265
+ return style == "hexagonal"
266
+ parts = {part for path in project_paths for part in PurePosixPath(path).parts}
267
+ return (any(".port." in PurePosixPath(path).name for path in project_paths)
268
+ or {"domain", "ports", "adapters"} <= parts
269
+ or {"core", "infrastructure", "application"} <= parts)
270
+
271
+
272
+ def select_review_policy(
273
+ policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
274
+ project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
275
+ guidance_paths: Sequence[str] = (),
276
+ resources: Sequence[str] = (),
277
+ ) -> FrozenReviewPolicy:
278
+ errors = review_policy_errors(policy)
279
+ if errors:
280
+ raise ValueError("; ".join(errors))
281
+ selected_resources = {"overview.md", "clean-code.md", "review-rules.json"}
282
+ selected_resources.update(_language_resources(source_paths))
283
+ root = str(review_policy_catalog_path(policy).parent)
284
+ for resource in resources:
285
+ if (not qa_relative_path_valid(resource) or root is None
286
+ or root + "/" + resource not in policy["sources"]):
287
+ raise ValueError(f"review resource was not captured in the frozen pack: {resource}")
288
+ if resource == "architectures/hexagonal.md" and policy["architecture"] in ("none", "layered"):
289
+ raise ValueError("review resource conflicts with the declared architecture")
290
+ selected_resources.add(resource)
291
+ if "frameworks/node-server.md" in selected_resources:
292
+ selected_resources.add("languages/javascript-typescript.md")
293
+ if any(name.endswith("javascript-typescript.md") for name in selected_resources):
294
+ if _node_server_work(source_paths, manifest_contents or {}):
295
+ selected_resources.add("frameworks/node-server.md")
296
+ if _hexagonal_work(policy, (*source_paths, *project_paths)):
297
+ selected_resources.add("architectures/hexagonal.md")
298
+ missing = [name for name in sorted(selected_resources)
299
+ if root + "/" + name not in policy["sources"]]
300
+ if missing:
301
+ raise ValueError("required frozen review resources are missing: " + ", ".join(missing))
302
+ selected: dict[str, FrozenProcedure] = {}
303
+ for path, source in policy["sources"].items():
304
+ if path in guidance_paths and not path.endswith("/references/review-calibration.md"):
305
+ continue
306
+ if root and path.startswith(root + "/") and path[len(root) + 1:] not in selected_resources:
307
+ continue
308
+ selected[path] = dict(source)
309
+ return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
310
+ "sources": selected}
311
+
312
+
313
+ def render_review_policy(
314
+ policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
315
+ project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
316
+ guidance_paths: Sequence[str] = (),
317
+ resources: Sequence[str] = (),
318
+ ) -> str:
319
+ selected = select_review_policy(
320
+ policy, source_paths, project_paths=project_paths,
321
+ manifest_contents=manifest_contents, guidance_paths=guidance_paths,
322
+ resources=resources,
323
+ )
324
+ body = render_selected_review_policy(selected)
325
+ omitted = policy["sources"].keys() - selected["sources"].keys()
326
+ if not omitted:
327
+ return body
328
+ rows = [body, "\n### Available archived resources (not loaded)\n\n"]
329
+ rows.extend(f"- {path} ({policy['sources'][path]['digest']})\n" for path in sorted(omitted))
330
+ rows.append("\nUse verification-input --source-path for each changed source file and "
331
+ "--resource for additional applicable pack resources. "
332
+ "Do not treat this inventory as read content.\n")
333
+ return "".join(rows)
334
+
335
+
336
+ def render_selected_review_policy(policy: FrozenReviewPolicy) -> str:
337
+ errors = review_policy_errors(policy)
338
+ if errors:
339
+ raise ValueError("; ".join(errors))
340
+ rows = ["\n## Frozen Review Policy\n\n",
341
+ f"Architecture style: {policy['architecture']}\n"]
342
+ for path, source in policy["sources"].items():
343
+ rows.extend([f"\n### Rule source: {path}\n",
344
+ f"Digest: {source['digest']}\n\n", source["body"], "\n"])
345
+ return "".join(rows)
346
+
347
+
348
+ def read_review_architecture(project: Path, manifest: Mapping[str, object]) -> str:
349
+ from okstra_project.resolver import resolve_architecture
350
+ from .qa_procedures import safe_qa_path
351
+ from .verification_input_ref import VerificationInputReference
352
+ from .verification_inputs import read_verification_inputs
353
+
354
+ reference = VerificationInputReference.from_artifact_fields(manifest)
355
+ if reference is not None:
356
+ inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
357
+ if "reviewPolicy" in inputs:
358
+ return inputs["reviewPolicy"]["architecture"]
359
+ return resolve_architecture(project)
@@ -0,0 +1,291 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import subprocess
5
+ from collections.abc import Sequence
6
+ from dataclasses import dataclass, field
7
+ from pathlib import Path, PurePosixPath
8
+
9
+ from .convergence_provenance import id_occurs_wordbounded
10
+ from .coverage_census import CellVerdicts, split_coverage_verdict_section
11
+
12
+
13
+ @dataclass(frozen=True)
14
+ class ReviewCell:
15
+ target: str
16
+ group: str
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class ReviewCensus:
21
+ rules: dict[str, tuple[str, ...]]
22
+ cells: dict[str, ReviewCell]
23
+ references: dict[str, str]
24
+
25
+
26
+ def _table_fields(line: str) -> list[str]:
27
+ # Markdown writes a literal pipe inside a table cell as `\|`.
28
+ fields = re.split(r"(?<!\\)\|", line.strip().strip("|"))
29
+ return [field.strip().replace("\\|", "|") for field in fields]
30
+
31
+
32
+ def read_review_census(path: Path, *, allow_empty: bool = False) -> ReviewCensus:
33
+ return parse_review_census(path.read_text(encoding="utf-8"), allow_empty=allow_empty)
34
+
35
+
36
+ def parse_review_census(text: str, *, allow_empty: bool = False) -> ReviewCensus:
37
+ rules: dict[str, list[str]] = {}
38
+ cells: dict[str, ReviewCell] = {}
39
+ rule_ids: set[str] = set()
40
+ pairs: set[tuple[str, str]] = set()
41
+ references: set[tuple[str, str]] = set()
42
+ rule_references: dict[str, str] = {}
43
+ section = ""
44
+ for line in text.splitlines():
45
+ if line.startswith("## "):
46
+ section = line.strip()
47
+ if section not in ("## Rules", "## Cells") or not line.strip().startswith("|"):
48
+ continue
49
+ fields = _table_fields(line)
50
+ header = fields[0] in ("Rule", "Cell")
51
+ if header or all(re.fullmatch(r"[-:]+", f) for f in fields):
52
+ continue
53
+ if len(fields) != 3 or not all(fields):
54
+ raise ValueError("malformed grouped census row")
55
+ identity, value, reference = fields
56
+ if section == "## Rules":
57
+ if not re.fullmatch(r"[A-Z][A-Z0-9]*", identity) or identity in rule_ids:
58
+ raise ValueError("invalid or duplicate rule ID")
59
+ if (value, reference) in references:
60
+ raise ValueError("duplicate group and rule reference")
61
+ if value not in ("structural", "semantic", "state-and-tests", "general"):
62
+ raise ValueError("unknown rule group")
63
+ rule_ids.add(identity)
64
+ references.add((value, reference))
65
+ rule_references[identity] = reference
66
+ rules.setdefault(value, []).append(identity)
67
+ else:
68
+ if not re.fullmatch(r"C-CR-[0-9]+", identity) or identity in cells:
69
+ raise ValueError("invalid or duplicate cell ID")
70
+ if (value, reference) in pairs:
71
+ raise ValueError("duplicate target and group")
72
+ target = PurePosixPath(value.partition(":")[0])
73
+ if target.is_absolute() or ".." in target.parts:
74
+ raise ValueError("target must be project-relative")
75
+ pairs.add((value, reference))
76
+ cells[identity] = ReviewCell(value, reference)
77
+ if not rules or (not cells and not allow_empty):
78
+ raise ValueError("census needs Rules and Cells tables")
79
+ if any(cell.group not in rules for cell in cells.values()):
80
+ raise ValueError("cell names an unknown rule group")
81
+ return ReviewCensus(
82
+ {group: tuple(ids) for group, ids in rules.items()}, cells, rule_references,
83
+ )
84
+
85
+
86
+ def _keyed_values(text: str) -> dict[str, str]:
87
+ values: dict[str, str] = {}
88
+ if text == "-":
89
+ return values
90
+ # Reviewers write prose reasons; only a semicolon before the next `RULE=` separates assignments.
91
+ for entry in re.split(r";(?=\s*[A-Z][A-Z0-9]*=)", text):
92
+ key, separator, value = entry.partition("=")
93
+ key, value = key.strip(), value.strip()
94
+ if not separator or not key or not value or key in values:
95
+ raise ValueError(f"empty or duplicate rule assignment: {entry.strip()!r}")
96
+ values[key] = value
97
+ return values
98
+
99
+
100
+ @dataclass
101
+ class _HeadTree:
102
+ """리뷰 대상 커밋이 담은 파일.
103
+
104
+ 프로젝트 루트에는 다른 커밋이 체크아웃돼 있을 수 있다.
105
+ """
106
+
107
+ root: Path
108
+ commit: str
109
+ line_counts: dict[str, int] = field(default_factory=dict)
110
+ base: _HeadTree | None = None
111
+
112
+ def line_count(self, path: str) -> int:
113
+ if path not in self.line_counts:
114
+ self.line_counts[path] = self._read_line_count(path)
115
+ return self.line_counts[path]
116
+
117
+ def _git(self, *args: str) -> subprocess.CompletedProcess[bytes]:
118
+ return subprocess.run(
119
+ ["git", "--literal-pathspecs", "-C", str(self.root), *args],
120
+ capture_output=True, check=False,
121
+ )
122
+
123
+ def _read_line_count(self, path: str) -> int:
124
+ listing = self._git("ls-tree", "-z", self.commit, "--", path)
125
+ if listing.returncode != 0:
126
+ raise ValueError("cannot list the head commit")
127
+ entries = [entry for entry in listing.stdout.split(b"\0") if entry]
128
+ named = (entry.partition(b"\t") for entry in entries)
129
+ matched = [
130
+ meta.split() for meta, _, name in named
131
+ if name.decode("utf-8", "surrogateescape") == path
132
+ ]
133
+ if not matched:
134
+ raise ValueError("source evidence file does not exist at head")
135
+ mode, kind, blob = matched[0]
136
+ if kind != b"blob" or mode == b"120000":
137
+ raise ValueError("source evidence is not a regular file at head")
138
+ content = self._git("cat-file", "blob", blob.decode())
139
+ if content.returncode != 0:
140
+ raise ValueError("cannot read source evidence at head")
141
+ return len(content.stdout.decode("utf-8").splitlines())
142
+
143
+
144
+ def _head_tree(project_root: Path, head: str) -> _HeadTree:
145
+ resolved = subprocess.run(
146
+ ["git", "-C", str(project_root), "rev-parse", "--verify", "--quiet",
147
+ "--end-of-options", f"{head}^{{commit}}"],
148
+ capture_output=True, text=True, check=False,
149
+ )
150
+ if resolved.returncode != 0:
151
+ raise ValueError(f"--head {head!r} is not a commit in {project_root}")
152
+ return _HeadTree(project_root, resolved.stdout.strip())
153
+
154
+
155
+ def _source_evidence(tree: _HeadTree, cell: ReviewCell, evidence: str) -> str:
156
+ source = evidence.strip("`")
157
+ if source.startswith("base:"):
158
+ if tree.base is None:
159
+ raise ValueError("base-side evidence requires --base")
160
+ tree = tree.base
161
+ source = source.removeprefix("base:")
162
+ target = cell.target.partition(":")[0]
163
+ match = re.fullmatch(re.escape(target) + r":(0|[1-9][0-9]*)`?(?:[ \t]+\S.*)?", source)
164
+ if match is None:
165
+ raise ValueError("evidence must cite the target source path:line")
166
+ relative = PurePosixPath(target)
167
+ if relative.is_absolute() or ".." in relative.parts:
168
+ raise ValueError("source evidence escapes project")
169
+ count = tree.line_count(target)
170
+ if int(match[1]) > count or (int(match[1]) == 0 and count != 0):
171
+ raise ValueError("source evidence line does not exist at head")
172
+ return evidence
173
+
174
+
175
+ def _checked_rule_evidence(
176
+ tree: _HeadTree, cell: ReviewCell, checked: Sequence[str], text: str,
177
+ ) -> str:
178
+ anchor, _, raw = text.partition(" :: ")
179
+ _source_evidence(tree, cell, anchor)
180
+ observations = _keyed_values(raw.strip() or "-")
181
+ required = set(checked) & {"G2", "G3", "G5"} if cell.group == "general" else set()
182
+ missing = required - observations.keys()
183
+ if missing:
184
+ raise ValueError("missing clean check evidence: " + ", ".join(sorted(missing)))
185
+ if observations.keys() - set(checked):
186
+ raise ValueError("clean check evidence names an unchecked rule")
187
+ for observation in observations.values():
188
+ match = re.fullmatch(r"(`?.+?:(?:0|[1-9][0-9]*)`?) (.+)", observation)
189
+ if match is None:
190
+ raise ValueError("clean check evidence needs source path:line and an observation")
191
+ if re.fullmatch(r"(?:checked|clean|no issues?|none|n/?a)", match[2], re.I):
192
+ raise ValueError("clean check evidence needs an observation, not a verdict label")
193
+ citation = match[1].strip("`")
194
+ source_cell = ReviewCell(citation.removeprefix("base:").partition(":")[0], cell.group)
195
+ _source_evidence(tree, source_cell, citation)
196
+ return text
197
+
198
+
199
+ def _group_verdict(
200
+ fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
201
+ tree: _HeadTree, references: Sequence[str],
202
+ ) -> tuple[str, str]:
203
+ if len(fields) != 5:
204
+ raise ValueError("expected Cell, Checked, N/A, Findings, Evidence columns")
205
+ checked = [] if fields[1] == "-" else [rule.strip() for rule in fields[1].split(",")]
206
+ excluded = _keyed_values(fields[2])
207
+ findings = _keyed_values(fields[3])
208
+ assigned = checked + list(excluded) + list(findings)
209
+ if len(set(assigned)) != len(assigned):
210
+ raise ValueError("duplicate or conflicting rule verdicts")
211
+ unknown = set(assigned) - set(expected)
212
+ if unknown:
213
+ raise ValueError("unknown rules: " + ", ".join(sorted(unknown)))
214
+ missing = set(expected) - set(assigned)
215
+ if missing:
216
+ raise ValueError("unchecked rules: " + ", ".join(sorted(missing)))
217
+ for reason in excluded.values():
218
+ if re.fullmatch(r"(?:[A-Z][0-9]+|[a-z]+:[0-9]+)", reason):
219
+ raise ValueError("n/a needs an inline applicability reason, not an alias")
220
+ for ids in findings.values():
221
+ for item in ids.split(","):
222
+ item = item.strip()
223
+ if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", item):
224
+ raise ValueError("invalid finding ID")
225
+ if not any(id_occurs_wordbounded(body, item) for body in references):
226
+ raise ValueError(f"finding {item} has no finding body")
227
+ evidence = _checked_rule_evidence(tree, cell, checked, fields[4])
228
+ if findings:
229
+ return "finding", "; ".join(findings.values())
230
+ if checked:
231
+ return "clean", evidence
232
+ return "n/a", "; ".join(excluded.values())
233
+
234
+
235
+ def _group_results(
236
+ body: str, census: ReviewCensus, tree: _HeadTree, references: Sequence[str],
237
+ ) -> CellVerdicts:
238
+ section, _ = split_coverage_verdict_section(body)
239
+ verdicts: dict[str, tuple[str, str]] = {}
240
+ reasons: dict[str, str] = {}
241
+ seen: set[str] = set()
242
+ unknown: list[str] = []
243
+ for line in section:
244
+ if not line.strip().startswith("|"):
245
+ continue
246
+ fields = _table_fields(line)
247
+ identity = fields[0]
248
+ if identity not in census.cells:
249
+ if identity.startswith("C-") and identity not in unknown:
250
+ unknown.append(identity)
251
+ continue
252
+ if identity in seen:
253
+ verdicts.pop(identity, None)
254
+ reasons[identity] = "duplicate cell row"
255
+ continue
256
+ seen.add(identity)
257
+ cell = census.cells[identity]
258
+ try:
259
+ verdicts[identity] = _group_verdict(
260
+ fields, census.rules[cell.group], cell, tree, references,
261
+ )
262
+ except (OSError, ValueError) as exc:
263
+ reasons[identity] = str(exc)
264
+ return CellVerdicts(
265
+ verdicts,
266
+ {key: reasons.get(key, "no grouped verdict row") for key in census.cells if key not in verdicts},
267
+ tuple(unknown),
268
+ )
269
+
270
+
271
+
272
+ def parse_review_verdicts(
273
+ project: Path, census: ReviewCensus, bodies: Sequence[str], head: str, *, base: str = "",
274
+ ) -> CellVerdicts:
275
+ tree = _head_tree(project, head)
276
+ if base:
277
+ tree.base = _head_tree(project, base)
278
+ verdicts: dict[str, tuple[str, str]] = {}
279
+ missing: dict[str, str] = {}
280
+ unknown: list[str] = []
281
+ references = [split_coverage_verdict_section(body)[1] for body in bodies]
282
+ for body in bodies:
283
+ parsed = _group_results(body, census, tree, references)
284
+ unknown.extend(key for key in parsed.unknown if key not in unknown)
285
+ for key, verdict in parsed.verdicts.items():
286
+ verdicts.setdefault(key, verdict)
287
+ missing.update(parsed.missing)
288
+ return CellVerdicts(
289
+ verdicts, {key: missing[key] for key in census.cells if key not in verdicts},
290
+ tuple(unknown),
291
+ )