Coverage for src/governed_harness/application/forges.py: 97%

63 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""``harness pr publish``, ``harness pr create`` and ``harness pr status`` on any forge (#56). 

2 

3The application layer resolves the forge (CLI options, ``delivery.forge``, the ``origin`` 

4remote), builds the decision brief of the run and calls the provider. Nothing is decided on the 

5forge: a comment, a report and a commit status inform the reviewers.""" 

6 

7from __future__ import annotations 

8 

9from typing import TYPE_CHECKING, Any 

10 

11from governed_harness.configuration.engineering import ForgeConfig 

12from governed_harness.delivery.publisher import render_brief_markdown 

13from governed_harness.domain.errors import ConfigurationError 

14from governed_harness.domain.models import Execution, Finding, GateEvaluation, Task 

15from governed_harness.forges import ( 

16 ResolvedForge, 

17 Transport, 

18 open_forge, 

19 pull_request_body, 

20 read_template, 

21 render_code_quality, 

22 resolve_forge, 

23 status_for, 

24) 

25from governed_harness.reporting import TraceReporter 

26 

27from .exceptions import brief_exceptions 

28from .review import build_brief 

29 

30if TYPE_CHECKING: 

31 from governed_harness.orchestration.engine import EngineServices 

32 

33 

34def forge_settings(services: EngineServices) -> ForgeConfig: 

35 return services.resolved.project.delivery_settings.forge or ForgeConfig() 

36 

37 

38def _resolved( 

39 services: EngineServices, 

40 *, 

41 kind: str | None, 

42 repository: str | None, 

43 transport: str | None, 

44) -> ResolvedForge: 

45 return resolve_forge( 

46 services.paths.workspace, 

47 forge_settings(services), 

48 kind=kind, 

49 repository=repository, 

50 transport=transport, 

51 ) 

52 

53 

54def _brief(services: EngineServices, run_id: str) -> dict[str, Any]: 

55 execution = services.state.get("execution", run_id, Execution) 

56 return build_brief(services, run_id, exceptions=brief_exceptions(services, execution)) 

57 

58 

59def publish_on_forge( 

60 services: EngineServices, 

61 run_id: str, 

62 *, 

63 pull_request: int, 

64 kind: str | None = None, 

65 repository: str | None = None, 

66 transport: str | None = None, 

67 reports: bool | None = None, 

68 commit_sha: str | None = None, 

69 transport_override: Transport | None = None, 

70) -> dict[str, Any]: 

71 """The decision brief as a comment and the findings as the forge's quality report.""" 

72 resolved = _resolved(services, kind=kind, repository=repository, transport=transport) 

73 settings = forge_settings(services) 

74 forge = open_forge(resolved, transport_override) 

75 comment = forge.upsert_comment( 

76 pull_request, run_id, render_brief_markdown(_brief(services, run_id)) 

77 ) 

78 findings = services.state.list("finding", Finding, execution_id=run_id) 

79 send = reports if reports is not None else True 

80 if send: 80 ↛ 89line 80 didn't jump to line 89 because the condition on line 80 was always true

81 code_quality = render_code_quality(findings) if settings.code_quality is not False else None 

82 upload = forge.upload_reports( 

83 pull_request, 

84 sarif=TraceReporter().render_sarif(findings), 

85 code_quality=code_quality, 

86 commit_sha=commit_sha, 

87 ) 

88 else: 

89 upload = {"status": "SKIPPED", "reason": "report upload disabled"} 

90 return { 

91 "publisher": resolved.location.kind, 

92 "forge": resolved.as_dict(), 

93 "repository": resolved.location.repository, 

94 "pullRequest": pull_request, 

95 "runId": run_id, 

96 "comment": comment, 

97 "reports": upload, 

98 } 

99 

100 

101def create_on_forge( 

102 services: EngineServices, 

103 run_id: str, 

104 *, 

105 head: str | None = None, 

106 base: str | None = None, 

107 title: str | None = None, 

108 labels: tuple[str, ...] = (), 

109 draft: bool | None = None, 

110 kind: str | None = None, 

111 repository: str | None = None, 

112 transport: str | None = None, 

113 transport_override: Transport | None = None, 

114) -> dict[str, Any]: 

115 """A pull or merge request from the run's closure branch, with the template and the 

116 brief as its description and the configured labels.""" 

117 execution = services.state.get("execution", run_id, Execution) 

118 task = services.state.get("task", execution.task_id, Task) 

119 project = services.resolved.project 

120 settings = forge_settings(services) 

121 delivery = project.delivery_settings 

122 branch = head or delivery.branch_template.replace("{runId}", run_id).replace( 

123 "{taskId}", execution.task_id 

124 ) 

125 target = base or settings.base_branch 

126 if not target: 

127 raise ConfigurationError("no base branch: pass --base or set delivery.forge.baseBranch") 

128 resolved = _resolved(services, kind=kind, repository=repository, transport=transport) 

129 template, template_source = read_template( 

130 services.paths.workspace, resolved.location.kind, settings.template 

131 ) 

132 body = pull_request_body(render_brief_markdown(_brief(services, run_id)), template) 

133 forge = open_forge(resolved, transport_override) 

134 all_labels = tuple(dict.fromkeys((*(settings.labels or ()), *labels))) 

135 created = forge.create_pull_request( 

136 head=branch, 

137 base=target, 

138 title=title or task.title, 

139 body=body, 

140 labels=all_labels, 

141 draft=bool(draft if draft is not None else settings.draft), 

142 ) 

143 services.events.append( 

144 run_id, 

145 "delivery.pull-request.created", 

146 { 

147 "forge": resolved.location.kind, 

148 "repository": resolved.location.repository, 

149 "head": branch, 

150 "base": target, 

151 "number": created.get("number"), 

152 "url": created.get("url"), 

153 "host": resolved.location.host, 

154 "labels": list(all_labels), 

155 "template": template_source, 

156 }, 

157 ) 

158 return { 

159 "forge": resolved.as_dict(), 

160 "head": branch, 

161 "base": target, 

162 "labels": list(all_labels), 

163 "template": template_source, 

164 "pullRequest": created, 

165 } 

166 

167 

168def status_on_forge( 

169 services: EngineServices, 

170 run_id: str, 

171 *, 

172 commit_sha: str, 

173 target_url: str | None = None, 

174 kind: str | None = None, 

175 repository: str | None = None, 

176 transport: str | None = None, 

177 transport_override: Transport | None = None, 

178) -> dict[str, Any]: 

179 """A commit status from the run: success once closed, pending while a person decides, 

180 failure otherwise.""" 

181 execution = services.state.get("execution", run_id, Execution) 

182 gate = ( 

183 services.state.get("gate", execution.gate_evaluation_id, GateEvaluation) 

184 if execution.gate_evaluation_id 

185 else None 

186 ) 

187 state = status_for( 

188 execution.status.value, 

189 execution.current_phase.value, 

190 gate.status.value if gate else None, 

191 ) 

192 description = { 

193 "success": f"Run {run_id} approved and closed", 

194 "pending": f"Run {run_id} waits for a human decision", 

195 "failure": f"Run {run_id}: {execution.status.value} in {execution.current_phase.value}", 

196 }[state] 

197 resolved = _resolved(services, kind=kind, repository=repository, transport=transport) 

198 result = open_forge(resolved, transport_override).set_status( 

199 commit_sha=commit_sha, state=state, description=description, target_url=target_url 

200 ) 

201 return {"forge": resolved.as_dict(), "commitSha": commit_sha, "state": state, **result} 

202 

203 

204def forge_report(services: EngineServices) -> dict[str, Any]: 

205 """The forge the workspace resolves to (no network).""" 

206 settings = forge_settings(services) 

207 try: 

208 resolved = resolve_forge(services.paths.workspace, settings) 

209 except ConfigurationError as error: 

210 return {"status": "UNKNOWN", "reason": str(error)} 

211 return {"status": "DETECTED", **resolved.as_dict()} 

212 

213 

214__all__ = [ 

215 "create_on_forge", 

216 "forge_report", 

217 "forge_settings", 

218 "publish_on_forge", 

219 "status_on_forge", 

220]