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
« 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).
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."""
7from __future__ import annotations
9from typing import TYPE_CHECKING, Any
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
27from .exceptions import brief_exceptions
28from .review import build_brief
30if TYPE_CHECKING:
31 from governed_harness.orchestration.engine import EngineServices
34def forge_settings(services: EngineServices) -> ForgeConfig:
35 return services.resolved.project.delivery_settings.forge or ForgeConfig()
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 )
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))
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 }
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 }
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}
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()}
214__all__ = [
215 "create_on_forge",
216 "forge_report",
217 "forge_settings",
218 "publish_on_forge",
219 "status_on_forge",
220]