Coverage for src/governed_harness/application/engineering.py: 96%
86 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Application side of the wave 6 settings (#56): standards, architecture, project detection.
3Read-only reports (``harness standards show``, ``harness architecture show``,
4``harness project show``) and the architecture decision of a person (digest-bound)."""
6from __future__ import annotations
8from pathlib import Path
9from typing import TYPE_CHECKING, Any
11from governed_harness.configuration.engineering import StandardsConfig
12from governed_harness.domain.actors import require_human_actor
13from governed_harness.domain.enums import ActorType, DecisionKind
14from governed_harness.domain.models import Actor
15from governed_harness.intake.project_kind import detect_project_kind
16from governed_harness.orchestration.architecture import (
17 ADR_FILE,
18 SURVEY_FILE,
19 effective_rules,
20 read_state,
21 source_layout,
22)
23from governed_harness.orchestration.architecture_catalogue import (
24 ORGANIZATION_FILE,
25 RECOMMENDATION_FILE,
26)
27from governed_harness.orchestration.engineering import detect_testing
28from governed_harness.orchestration.reverse_engineering import DIRECTORY
29from governed_harness.standards import (
30 BUILTIN_PACKS,
31 describe_pack,
32 project_standards,
33 select_cards,
34 tool_validators,
35)
37if TYPE_CHECKING:
38 from governed_harness.orchestration.engine import EngineServices
41def standards_report(
42 workspace: Path,
43 config: StandardsConfig | None,
44 technologies: tuple[str, ...],
45 existing_validators: list[str],
46 *,
47 pack: str | None = None,
48 files: tuple[str, ...] = (),
49) -> dict[str, Any]:
50 """The effective packs of a workspace (or one pack), the cards for some files and the
51 tools the repository configures."""
52 settings = config or StandardsConfig()
53 packs = (pack,) if pack else settings.packs
54 standards = project_standards(
55 workspace,
56 packs=packs,
57 overrides=settings.overrides_path,
58 disabled=settings.disabled or (),
59 technologies=technologies,
60 )
61 report: dict[str, Any] = {
62 "configured": config is not None,
63 "detected": list(standards.detected),
64 "packs": [describe_pack(item, include_cards=bool(pack)) for item in standards.packs],
65 "digest": standards.digest,
66 "available": list(BUILTIN_PACKS),
67 "toolValidators": [
68 {"pack": pack_id, "tool": tool.tool_id, "validatorId": definition.validator_id}
69 for pack_id, tool, definition in tool_validators(
70 standards, workspace, existing_validators
71 )
72 ],
73 }
74 if files:
75 report["selection"] = {
76 "files": list(files),
77 "implement": [
78 item.compact() for item in select_cards(standards, files, settings.card_limit)
79 ],
80 "reviewChecklist": [
81 item.card_id
82 for item in select_cards(standards, files, settings.card_limit, review_only=True)
83 ],
84 }
85 return report
88def architecture_report(services: EngineServices) -> dict[str, Any]:
89 project = services.resolved.project
90 harness_dir = services.paths.harness_dir
91 rules = effective_rules(project.architecture, harness_dir)
92 state = read_state(harness_dir)
93 survey = harness_dir / SURVEY_FILE
94 adr = harness_dir / ADR_FILE
95 return {
96 "configured": project.architecture.model_dump(mode="json", by_alias=True)
97 if project.architecture
98 else None,
99 "projectKind": detect_project_kind(services.paths.workspace).as_dict(),
100 "state": state,
101 "rules": rules.as_dict() if rules else None,
102 "forbiddenImports": [
103 {"from": source, "to": target} for source, target in rules.forbidden_pairs()
104 ]
105 if rules
106 else [],
107 "layout": source_layout(services.paths.workspace),
108 "survey": survey.read_text(encoding="utf-8") if survey.is_file() else None,
109 "adr": adr.read_text(encoding="utf-8") if adr.is_file() else None,
110 "recommendation": _read_text(harness_dir / RECOMMENDATION_FILE),
111 "organization": _read_text(harness_dir / ORGANIZATION_FILE),
112 "reverseEngineering": _documents(harness_dir, state),
113 }
116def _read_text(path: Path) -> str | None:
117 return path.read_text(encoding="utf-8") if path.is_file() else None
120def _documents(harness_dir: Path, state: dict[str, Any] | None) -> dict[str, Any] | None:
121 """The reverse engineering documents of an existing project (#97): where they are, their
122 digests (the record the survey made) and whether each file is still in the project."""
123 record = (state or {}).get("documentation")
124 if not isinstance(record, dict):
125 return None
126 return {
127 "directory": record.get("directory"),
128 "digest": record.get("digest"),
129 "files": {
130 name: {"digest": digest, "present": (harness_dir / DIRECTORY / name).is_file()}
131 for name, digest in (record.get("files") or {}).items()
132 },
133 }
136def decide_architecture(
137 services: EngineServices,
138 execution_id: str,
139 *,
140 digest: str,
141 actor_id: str,
142 rationale: str,
143 decision: DecisionKind | None,
144 option: str | None,
145 continue_after: bool,
146 style: str | None = None,
147) -> dict[str, Any]:
148 """A person approves or rejects the inferred rules, or chooses an option (an ADR)."""
149 from governed_harness.orchestration.engine import RunEngine
151 require_human_actor(actor_id, "decide the architecture")
152 engine = RunEngine(services)
153 state = engine.results.architecture.decide(
154 engine.get_execution(execution_id),
155 actor=Actor(actor_type=ActorType.HUMAN, actor_id=actor_id),
156 digest=digest,
157 rationale=rationale,
158 decision=decision,
159 option=option,
160 style=style,
161 )
162 result: dict[str, Any] = {"executionId": execution_id, "architecture": state}
163 if continue_after: 163 ↛ 168line 163 didn't jump to line 168 because the condition on line 163 was always true
164 result["execution"] = engine.continue_execution(execution_id).model_dump(
165 mode="json", by_alias=True
166 )
167 else:
168 engine.anchor_chain(execution_id)
169 return result
172def refresh_architecture(services: EngineServices) -> dict[str, Any]:
173 from governed_harness.orchestration.engine import RunEngine
175 return RunEngine(services).results.architecture.refresh()
178def project_report(services: EngineServices) -> dict[str, Any]:
179 """What the harness detects about the project, deterministically and without a call."""
180 from governed_harness.application.forges import forge_report
181 from governed_harness.orchestration.engine import RunEngine
183 engine = RunEngine(services)
184 workspace = services.paths.workspace
185 technologies = tuple(item.technology for item in services.resolved.profiles)
186 project = services.resolved.project
187 standards = engine.results.engineering.standards()
188 strategy = (
189 engine.results.engineering.strategy(project.project_id)
190 if engine.results.engineering.configured
191 else detect_testing(workspace, technologies)
192 )
193 rules = effective_rules(project.architecture, services.paths.harness_dir)
194 return {
195 "projectKind": detect_project_kind(workspace).as_dict(),
196 "profiles": [item.profile_id for item in services.resolved.profiles],
197 "standards": {
198 "packs": [item.pack_id for item in standards.packs] if standards else None,
199 "detected": list(standards.detected)
200 if standards
201 else list(
202 project_standards(
203 workspace, packs=None, overrides=None, technologies=technologies
204 ).detected
205 ),
206 },
207 "testing": strategy.as_dict(),
208 "architecture": {
209 "status": (read_state(services.paths.harness_dir) or {}).get("status"),
210 "layers": [item.name for item in rules.layers] if rules else [],
211 },
212 "projectSetup": engine.results.engineering.setup_record(project.project_id) or None,
213 "forge": forge_report(services),
214 }
217def _effective_packs(
218 standards: Any, workspace: Path, technologies: tuple[str, ...]
219) -> list[str] | None:
220 if standards is None:
221 return None
222 return [
223 item.pack_id
224 for item in project_standards(
225 workspace,
226 packs=standards.packs,
227 overrides=standards.overrides_path,
228 disabled=standards.disabled or (),
229 technologies=technologies,
230 ).packs
231 ]
234def _testing_strategy(testing: Any, workspace: Path, technologies: tuple[str, ...]) -> str:
235 """The configured strategy; ``auto`` (or none) detects it; without ``testing``, off."""
236 if not testing:
237 return "off"
238 if testing.strategy not in {None, "auto"}: 238 ↛ 239line 238 didn't jump to line 239 because the condition on line 238 was never true
239 return str(testing.strategy)
240 return detect_testing(workspace, technologies).strategy
243def _standards_summary(
244 standards: Any, workspace: Path, technologies: tuple[str, ...]
245) -> dict[str, Any]:
246 """The ``standards`` block of :func:`engineering_summary`."""
247 return {
248 "cards": standards.cards if standards else "off",
249 "tools": standards.tools if standards else "off",
250 "packs": _effective_packs(standards, workspace, technologies),
251 }
254def _architecture_summary(architecture: Any) -> dict[str, Any]:
255 """The ``architecture`` block of :func:`engineering_summary`."""
256 if not architecture:
257 return {
258 "mode": "off",
259 "style": None,
260 "layers": 0,
261 "layerCheck": "full",
262 "baselineConflicts": "enforce",
263 "catalogue": "off",
264 "documentation": "off",
265 }
266 return {
267 "mode": architecture.mode,
268 "style": architecture.style,
269 "layers": len(architecture.layers or ()),
270 "layerCheck": architecture.layer_check or "full",
271 "baselineConflicts": architecture.baseline_conflicts or "enforce",
272 "catalogue": architecture.catalogue or "off",
273 "documentation": architecture.documentation or "off",
274 }
277def engineering_summary(resolved: Any) -> dict[str, Any]:
278 """Effective wave 6 settings for ``harness config validate`` (absent: 1.0.0 behaviour)."""
279 project = resolved.project
280 workspace = resolved.workspace_root
281 technologies = tuple(item.technology for item in resolved.profiles)
282 standards = project.standards
283 principles = project.verification.principles if project.verification else None
284 architecture = project.architecture
285 forge = project.delivery_settings.forge
286 return {
287 "projectKind": detect_project_kind(workspace).kind,
288 "standards": _standards_summary(standards, workspace, technologies),
289 "principles": principles.mode if principles else "off",
290 "testing": {"strategy": _testing_strategy(project.testing, workspace, technologies)},
291 "architecture": _architecture_summary(architecture),
292 "projectSetup": project.intake.project_setup if project.intake else None,
293 "forge": forge.kind if forge and forge.kind else "auto",
294 }
297__all__ = [
298 "architecture_report",
299 "decide_architecture",
300 "engineering_summary",
301 "project_report",
302 "refresh_architecture",
303 "standards_report",
304]