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

1"""Application side of the wave 6 settings (#56): standards, architecture, project detection. 

2 

3Read-only reports (``harness standards show``, ``harness architecture show``, 

4``harness project show``) and the architecture decision of a person (digest-bound).""" 

5 

6from __future__ import annotations 

7 

8from pathlib import Path 

9from typing import TYPE_CHECKING, Any 

10 

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) 

36 

37if TYPE_CHECKING: 

38 from governed_harness.orchestration.engine import EngineServices 

39 

40 

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 

86 

87 

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 } 

114 

115 

116def _read_text(path: Path) -> str | None: 

117 return path.read_text(encoding="utf-8") if path.is_file() else None 

118 

119 

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 } 

134 

135 

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 

150 

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 

170 

171 

172def refresh_architecture(services: EngineServices) -> dict[str, Any]: 

173 from governed_harness.orchestration.engine import RunEngine 

174 

175 return RunEngine(services).results.architecture.refresh() 

176 

177 

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 

182 

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 } 

215 

216 

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 ] 

232 

233 

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 

241 

242 

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 } 

252 

253 

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 } 

275 

276 

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 } 

295 

296 

297__all__ = [ 

298 "architecture_report", 

299 "decide_architecture", 

300 "engineering_summary", 

301 "project_report", 

302 "refresh_architecture", 

303 "standards_report", 

304]