quality-graph-github 0.1.7__tar.gz → 0.1.9__tar.gz

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 (22) hide show
  1. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/.gitignore +1 -0
  2. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/PKG-INFO +4 -4
  3. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/pyproject.toml +4 -4
  4. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/artifacts.py +8 -2
  5. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/commands.py +44 -16
  6. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/compiler.py +212 -20
  7. quality_graph_github-0.1.9/src/qg_github/presentation.py +17 -0
  8. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/publication.py +69 -14
  9. quality_graph_github-0.1.9/src/qg_github/required_checks.py +389 -0
  10. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/runtime.py +21 -3
  11. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/README.md +0 -0
  12. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/__init__.py +0 -0
  13. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/annotations.py +0 -0
  14. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/approvals.py +0 -0
  15. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/comments.py +0 -0
  16. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/controls.py +0 -0
  17. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/dashboard.py +0 -0
  18. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/github.py +0 -0
  19. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/labels.py +0 -0
  20. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/provider.py +0 -0
  21. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/py.typed +0 -0
  22. {quality_graph_github-0.1.7 → quality_graph_github-0.1.9}/src/qg_github/reporting.py +0 -0
@@ -1,4 +1,5 @@
1
1
  .venv/
2
+ .env
2
3
  __pycache__/
3
4
  *.py[cod]
4
5
  .pytest_cache/
@@ -1,15 +1,15 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: quality-graph-github
3
- Version: 0.1.7
3
+ Version: 0.1.9
4
4
  Summary: GitHub provider and Action runtime for Quality Graph
5
- Project-URL: Homepage, https://alchemmist.github.io/quality-graph/
6
- Project-URL: Documentation, https://alchemmist.github.io/quality-graph/
5
+ Project-URL: Homepage, https://quality-graph.xyz/
6
+ Project-URL: Documentation, https://quality-graph.xyz/
7
7
  License-Expression: MIT
8
8
  Requires-Python: >=3.12
9
9
  Requires-Dist: httpx>=0.28.1
10
10
  Requires-Dist: jinja2>=3.1.6
11
11
  Requires-Dist: pyyaml>=6.0.2
12
- Requires-Dist: quality-graph-core==0.1.7
12
+ Requires-Dist: quality-graph-core==0.1.9
13
13
  Description-Content-Type: text/markdown
14
14
 
15
15
  # Quality Graph GitHub Provider
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "quality-graph-github"
7
- version = "0.1.7"
7
+ version = "0.1.9"
8
8
  description = "GitHub provider and Action runtime for Quality Graph"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12"
@@ -13,12 +13,12 @@ dependencies = [
13
13
  "httpx>=0.28.1",
14
14
  "jinja2>=3.1.6",
15
15
  "pyyaml>=6.0.2",
16
- "quality-graph-core==0.1.7",
16
+ "quality-graph-core==0.1.9",
17
17
  ]
18
18
 
19
19
  [project.urls]
20
- Homepage = "https://alchemmist.github.io/quality-graph/"
21
- Documentation = "https://alchemmist.github.io/quality-graph/"
20
+ Homepage = "https://quality-graph.xyz/"
21
+ Documentation = "https://quality-graph.xyz/"
22
22
 
23
23
  [project.entry-points."qg.providers"]
24
24
  github = "qg_github:provider"
@@ -7,7 +7,7 @@ import io
7
7
  import re
8
8
  import stat
9
9
  import zipfile
10
- from dataclasses import dataclass
10
+ from dataclasses import dataclass, field
11
11
  from pathlib import PurePosixPath
12
12
  from typing import TYPE_CHECKING
13
13
 
@@ -15,7 +15,7 @@ from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
15
15
  from quality_graph_core.result import JsonValue, Result
16
16
 
17
17
  if TYPE_CHECKING:
18
- from collections.abc import Iterable
18
+ from collections.abc import Iterable, Mapping
19
19
 
20
20
  ARTIFACT_NAME_RE = re.compile(
21
21
  r"^quality-result-(?P<node>[a-z][a-z0-9-]{0,62})-"
@@ -40,6 +40,8 @@ class ArtifactExpectation:
40
40
  workflow_run_id: int
41
41
  graph_digest: str
42
42
  node_ids: frozenset[str]
43
+ flow_id: str | None = None
44
+ operation_ids: Mapping[str, str] = field(default_factory=dict)
43
45
 
44
46
 
45
47
  @dataclass(frozen=True)
@@ -174,6 +176,8 @@ def _validate_result(
174
176
  expectation.workflow_run_id,
175
177
  descriptor.attempt,
176
178
  expectation.graph_digest,
179
+ expectation.flow_id,
180
+ expectation.operation_ids.get(result.node_id),
177
181
  )
178
182
  observed = (
179
183
  provenance.repository,
@@ -182,6 +186,8 @@ def _validate_result(
182
186
  provenance.workflow_run_id,
183
187
  provenance.run_attempt,
184
188
  provenance.graph_digest,
189
+ provenance.flow_id,
190
+ provenance.operation_id,
185
191
  )
186
192
  if result.node_id != descriptor.node_id or observed != expected:
187
193
  message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
@@ -10,9 +10,10 @@ from enum import StrEnum
10
10
 
11
11
  from qg_github.approvals import ApprovalRecord, append_approval_record
12
12
  from qg_github.artifacts import ArtifactExpectation, download_results
13
- from qg_github.compiler import compile_graph, project_graph
13
+ from qg_github.compiler import compile_graph
14
14
  from qg_github.controls import control_states, decode_control_marker
15
15
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
16
+ from qg_github.presentation import pr_presentation_graph
16
17
  from quality_graph_core.graph import Graph
17
18
  from quality_graph_core.policy import ApprovalTarget, effective_graph
18
19
  from quality_graph_core.result import ControlKind, JsonValue
@@ -178,6 +179,20 @@ def handle_command(port: GitHubPort, event_value: JsonValue) -> CommandOutcome:
178
179
  return CommandOutcome(handled=True, authorized=True, changed=True)
179
180
 
180
181
 
182
+ def dispatch_pr_command(port: GitHubPort, event_value: JsonValue) -> CommandOutcome:
183
+ """Dispatch comment events only when the trusted declaration enables PR presentation."""
184
+ request = command_request(event_value)
185
+ if request is None or request.pull_request is None:
186
+ return CommandOutcome(handled=False)
187
+ pull = _object(port.request("GET", f"/pulls/{request.pull_request}"), "pull request")
188
+ base = _object(pull.get("base"), "pull request base")
189
+ base_sha = _string(base.get("sha"), "pull request base SHA")
190
+ graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
191
+ if pr_presentation_graph(graph) is None:
192
+ return CommandOutcome(handled=False)
193
+ return handle_command(port, event_value)
194
+
195
+
181
196
  # pragma: no mutate start
182
197
  def _command_context(port: GitHubPort, number: int) -> CommandContext:
183
198
  pull = _object(port.request("GET", f"/pulls/{number}"), "pull request")
@@ -185,9 +200,13 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
185
200
  base = _object(pull.get("base"), "pull request base")
186
201
  head_sha = _string(head.get("sha"), "pull request head SHA")
187
202
  base_sha = _string(base.get("sha"), "pull request base SHA")
188
- graph = Graph.from_yaml(_repository_file(port, "quality-graph.yml", base_sha))
203
+ graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
189
204
  compiled = compile_graph(graph)
190
- graph = project_graph(graph, "pull-request")
205
+ projected = pr_presentation_graph(graph)
206
+ if projected is None:
207
+ message = "GitHub PR presentation is disabled"
208
+ raise ValueError(message)
209
+ graph = projected
191
210
  run = _latest_run(port, number)
192
211
  run_id = _integer(run.get("id"), "workflow run id")
193
212
  attempt = _integer(run.get("run_attempt", 1), "workflow run attempt")
@@ -198,6 +217,8 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
198
217
  run_id,
199
218
  compiled.graph_digest,
200
219
  frozenset(node.id for node in graph.nodes),
220
+ graph.flow_id,
221
+ {node.id: node.operation_id for node in graph.nodes if node.operation_id is not None},
201
222
  )
202
223
  results = download_results(port, expectation)
203
224
  if any(result.provenance.run_attempt > attempt for result in results.values()):
@@ -208,20 +229,27 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
208
229
 
209
230
 
210
231
  def _latest_run(port: GitHubPort, number: int) -> dict[str, JsonValue]:
211
- path = (
212
- "/actions/workflows/quality-graph.yml/runs?event=pull_request"
213
- f"&per_page={GITHUB_PAGE_SIZE}&page=1"
214
- )
215
- response = _object(port.request("GET", path), "workflow runs")
216
- runs = [
217
- run
218
- for value in _array(response.get("workflow_runs", []), "workflow runs")
219
- for run in (_object(value, "workflow run"),)
220
- if any(
221
- _object(pull, "workflow pull request").get("number") == number
222
- for pull in _array(run.get("pull_requests", []), "workflow pull requests")
232
+ runs: list[dict[str, JsonValue]] = []
233
+ page = 1
234
+ while True:
235
+ path = (
236
+ "/actions/workflows/quality-graph.yml/runs?event=pull_request"
237
+ f"&per_page={GITHUB_PAGE_SIZE}&page={page}"
238
+ )
239
+ response = _object(port.request("GET", path), "workflow runs")
240
+ values = _array(response.get("workflow_runs", []), "workflow runs")
241
+ runs.extend(
242
+ run
243
+ for value in values
244
+ for run in (_object(value, "workflow run"),)
245
+ if any(
246
+ _object(pull, "workflow pull request").get("number") == number
247
+ for pull in _array(run.get("pull_requests", []), "workflow pull requests")
248
+ )
223
249
  )
224
- ]
250
+ if len(values) < GITHUB_PAGE_SIZE:
251
+ break
252
+ page += 1
225
253
  if not runs:
226
254
  message = f"no Quality Graph workflow run found for PR #{number}"
227
255
  raise ValueError(message)
@@ -11,7 +11,16 @@ from typing import TYPE_CHECKING, cast, override
11
11
 
12
12
  import yaml
13
13
 
14
- from quality_graph_core.graph import DependencyPolicy, Graph, LabelSpec, Node, Profile, Step
14
+ from quality_graph_core.graph import (
15
+ DependencyPolicy,
16
+ Flow,
17
+ FlowNode,
18
+ Graph,
19
+ LabelSpec,
20
+ Node,
21
+ Profile,
22
+ Step,
23
+ )
15
24
  from quality_graph_core.provider import GeneratedFile, GeneratedProject
16
25
 
17
26
  if TYPE_CHECKING:
@@ -20,8 +29,7 @@ if TYPE_CHECKING:
20
29
  from quality_graph_core.result import JsonValue
21
30
 
22
31
  GENERATED_NOTICE = (
23
- "Generated by Quality Graph. DO NOT EDIT MANUALLY. "
24
- "Update quality-graph.yml and run qg generate."
32
+ "Generated by Quality Graph. DO NOT EDIT MANUALLY. Update qg.yaml and run qg generate."
25
33
  )
26
34
  GENERATED_HEADER = f"# {GENERATED_NOTICE}\n---\n"
27
35
  EXECUTION_WORKFLOW = PurePosixPath(".github/workflows/quality-graph.yml")
@@ -66,6 +74,7 @@ class _GitHubConfiguration:
66
74
  publisher_action: str
67
75
  upload_artifact_action: str
68
76
  default_branch: str
77
+ merge_required: bool
69
78
 
70
79
 
71
80
  class WorkflowDumper(yaml.SafeDumper):
@@ -86,7 +95,7 @@ def _validate_github_graph(graph: Graph) -> _GitHubConfiguration:
86
95
  if graph.provider.name != "github":
87
96
  message = f"GitHub provider cannot compile provider '{graph.provider.name}'"
88
97
  raise ValueError(message)
89
- unknown = graph.provider.values.keys() - {"default-branch", "runtime"}
98
+ unknown = graph.provider.values.keys() - {"default-branch", "runtime", "merge"}
90
99
  if unknown:
91
100
  message = f"GitHub provider contains unknown configuration: {', '.join(sorted(unknown))}"
92
101
  raise ValueError(message)
@@ -101,24 +110,74 @@ def _validate_github_graph(graph: Graph) -> _GitHubConfiguration:
101
110
  publisher_action = _runtime_action(runtime.get("publisher-action", action), "publisher")
102
111
  upload_artifact_action = _upload_artifact_action(runtime)
103
112
  default_branch = _default_branch(graph.provider.values.get("default-branch"))
113
+ merge_required = _merge_required(graph.provider.values.get("merge", {}))
104
114
  if publisher_action.partition("@")[0] != action.partition("@")[0]:
105
115
  message = "GitHub publisher action must use the runtime action repository"
106
116
  raise ValueError(message)
117
+ _validate_execution_contracts(graph)
118
+ if graph.flows:
119
+ _validate_explicit_flows(graph)
120
+ _validate_merge_presentation(graph, merge_required=merge_required)
121
+ else:
122
+ _event_projections(graph)
123
+ return _GitHubConfiguration(
124
+ action,
125
+ publisher_action,
126
+ upload_artifact_action,
127
+ default_branch,
128
+ merge_required,
129
+ )
130
+
131
+
132
+ def _validate_execution_contracts(graph: Graph) -> None:
133
+ if graph.flow_id is not None:
134
+ message = "compile the original declaration, not a resolved flow"
135
+ raise ValueError(message)
107
136
  for profile in graph.profiles:
108
137
  _validate_permissions(profile)
109
138
  for step in profile.setup:
110
139
  _validate_step(step)
111
140
  for node in graph.nodes:
112
141
  _validate_step(node.step)
142
+ for operation in graph.operations:
143
+ _validate_step(operation.step)
113
144
  titles = [node.title for node in graph.nodes]
114
145
  if len(set(titles)) != len(titles):
115
146
  message = "GitHub dashboard requires unique node titles"
116
147
  raise ValueError(message)
117
- _event_projections(graph)
118
- return _GitHubConfiguration(action, publisher_action, upload_artifact_action, default_branch)
148
+
149
+
150
+ def _validate_merge_presentation(graph: Graph, *, merge_required: bool) -> None:
151
+ if merge_required and not any(flow.presentation == "github-pr" for flow in graph.flows):
152
+ message = "merge.required needs an enabled GitHub PR presentation adapter"
153
+ raise ValueError(message)
154
+
155
+
156
+ def _merge_required(merge: JsonValue) -> bool:
157
+ if not isinstance(merge, dict):
158
+ message = "GitHub merge configuration must be an object"
159
+ raise TypeError(message)
160
+ if merge.keys() - {"required"}:
161
+ message = "GitHub merge configuration contains unknown fields"
162
+ raise ValueError(message)
163
+ merge_required = merge.get("required", False)
164
+ if not isinstance(merge_required, bool):
165
+ message = "GitHub merge required must be a boolean"
166
+ raise TypeError(message)
167
+ return merge_required
119
168
 
120
169
 
121
170
  def _event_projections(graph: Graph) -> tuple[EventProjection, ...]:
171
+ if graph.flows:
172
+ return tuple(
173
+ EventProjection(
174
+ "push" if flow.trigger == "push" else "pull-request",
175
+ graph.for_flow(flow.id).nodes,
176
+ flow.dependencies,
177
+ )
178
+ for flow in graph.flows
179
+ if flow.trigger != "workflow-dispatch"
180
+ )
122
181
  supported = set(SUPPORTED_EVENTS)
123
182
  unknown = set(graph.execution) - supported
124
183
  for node in graph.nodes:
@@ -161,9 +220,31 @@ def event_projection(graph: Graph, event: str) -> EventProjection:
161
220
 
162
221
  def project_graph(graph: Graph, event: str) -> Graph:
163
222
  """Return one dependency-normalized GitHub event graph."""
223
+ if graph.flows:
224
+ for flow in graph.flows:
225
+ if flow.trigger == event:
226
+ return graph.for_flow(flow.id)
227
+ message = f"no flow declares the {event} trigger"
228
+ raise ValueError(message)
164
229
  return replace(graph, nodes=event_projection(graph, event).nodes)
165
230
 
166
231
 
232
+ def _validate_explicit_flows(graph: Graph) -> None:
233
+ for trigger in SUPPORTED_EVENTS:
234
+ selected = [flow for flow in graph.flows if flow.trigger == trigger]
235
+ if len(selected) > 1:
236
+ message = f"GitHub supports one {trigger} flow per declaration"
237
+ raise ValueError(message)
238
+ for flow in graph.flows:
239
+ for branch in flow.branches:
240
+ _default_branch(branch)
241
+ if flow.presentation == "github-pr":
242
+ titles = [node.title for node in graph.for_flow(flow.id).nodes]
243
+ if len(set(titles)) != len(titles):
244
+ message = "GitHub PR presentation requires unique placement titles"
245
+ raise ValueError(message)
246
+
247
+
167
248
  def _default_branch(value: JsonValue) -> str:
168
249
  branch = "main" if value is None else value
169
250
  if not isinstance(branch, str) or not 1 <= len(branch) <= MAX_BRANCH_NAME_LENGTH:
@@ -221,6 +302,8 @@ def _validate_step(step: Step) -> None:
221
302
  def compile_graph(graph: Graph) -> GeneratedProject:
222
303
  """Compile one graph through the public declaration seam."""
223
304
  configuration = _validate_github_graph(graph)
305
+ if graph.flows:
306
+ return _compile_flows(graph, configuration)
224
307
  projections = {item.event: item for item in _event_projections(graph)}
225
308
  manifest = _manifest_value(graph, configuration)
226
309
  digest = hashlib.sha256(_canonical_json(manifest).encode()).hexdigest()
@@ -258,6 +341,84 @@ def compile_graph(graph: Graph) -> GeneratedProject:
258
341
  return GeneratedProject(digest, files)
259
342
 
260
343
 
344
+ def _compile_flows(graph: Graph, configuration: _GitHubConfiguration) -> GeneratedProject:
345
+ manifest = _manifest_value(graph, configuration)
346
+ profiles = graph.expanded_profiles()
347
+ manifest.pop("nodes")
348
+ manifest["manifestVersion"] = 1
349
+ manifest["operations"] = {
350
+ operation.id: {
351
+ **_node_value(
352
+ operation.place(
353
+ FlowNode(operation.id, operation.id),
354
+ DependencyPolicy.GRAPH,
355
+ ),
356
+ profiles[operation.profile],
357
+ ),
358
+ "diffOnly": operation.diff_only,
359
+ }
360
+ for operation in graph.operations
361
+ }
362
+ manifest["flows"] = {flow.id: _flow_value(flow) for flow in graph.flows}
363
+ for contract in cast("dict[str, dict[str, JsonValue]]", manifest["operations"]).values():
364
+ contract.pop("needs")
365
+ digest = hashlib.sha256(_canonical_json(manifest).encode()).hexdigest()
366
+ manifest.update({"graphDigest": digest, "_generated": GENERATED_NOTICE})
367
+ files: list[GeneratedFile] = []
368
+ for flow in graph.flows:
369
+ if flow.trigger == "workflow-dispatch":
370
+ continue
371
+ projection = EventProjection(flow.trigger, graph.for_flow(flow.id).nodes, flow.dependencies)
372
+ workflow = _execution_workflow(graph, projection, configuration, digest, flow=flow)
373
+ if flow.concurrency is not None:
374
+ workflow["concurrency"] = {
375
+ "group": f"quality-graph-{flow.concurrency}",
376
+ "cancel-in-progress": False,
377
+ }
378
+ if flow.trigger == "push":
379
+ workflow["on"] = {"push": {"branches": list(flow.branches)}}
380
+ else:
381
+ workflow["on"] = {"pull_request": {"branches": [configuration.default_branch]}}
382
+ path = EXECUTION_WORKFLOW if flow.trigger == "pull-request" else PUSH_WORKFLOW
383
+ files.append(GeneratedFile(path, _yaml_file(workflow)))
384
+ if any(flow.presentation == "github-pr" for flow in graph.flows):
385
+ files.append(
386
+ GeneratedFile(
387
+ PUBLICATION_WORKFLOW,
388
+ _yaml_file(_publication_workflow(configuration.publisher_action)),
389
+ )
390
+ )
391
+ files.append(GeneratedFile(GRAPH_MANIFEST, _canonical_json(manifest)))
392
+ paths = {item.path for item in files}
393
+ retired = tuple(
394
+ path
395
+ for path in (EXECUTION_WORKFLOW, PUSH_WORKFLOW, PUBLICATION_WORKFLOW)
396
+ if path not in paths
397
+ )
398
+ return GeneratedProject(digest, tuple(files), retired)
399
+
400
+
401
+ def _flow_value(flow: Flow) -> dict[str, JsonValue]:
402
+ return {
403
+ "trigger": flow.trigger,
404
+ "branches": list(flow.branches),
405
+ "inputs": dict(flow.inputs),
406
+ "dependencies": flow.dependencies.value,
407
+ "presentation": flow.presentation,
408
+ "concurrency": flow.concurrency,
409
+ "execution": "design-only" if flow.trigger == "workflow-dispatch" else "github-actions",
410
+ "nodes": [
411
+ {
412
+ "id": node.id,
413
+ "operation": node.operation,
414
+ "needs": list(node.needs),
415
+ "checkpoint": dict(node.checkpoint),
416
+ }
417
+ for node in flow.nodes
418
+ ],
419
+ }
420
+
421
+
261
422
  def _manifest_value(
262
423
  graph: Graph,
263
424
  configuration: _GitHubConfiguration,
@@ -374,6 +535,8 @@ def _execution_workflow(
374
535
  projection: EventProjection,
375
536
  configuration: _GitHubConfiguration,
376
537
  digest: str,
538
+ *,
539
+ flow: Flow | None = None,
377
540
  ) -> dict[str, JsonValue]:
378
541
  profiles = graph.expanded_profiles()
379
542
  jobs: dict[str, JsonValue] = {
@@ -382,6 +545,7 @@ def _execution_workflow(
382
545
  profiles[node.profile],
383
546
  configuration,
384
547
  digest,
548
+ flow=flow,
385
549
  )
386
550
  for node in projection.nodes
387
551
  }
@@ -413,6 +577,8 @@ def _execution_job(
413
577
  profile: Profile,
414
578
  configuration: _GitHubConfiguration,
415
579
  graph_digest: str,
580
+ *,
581
+ flow: Flow | None = None,
416
582
  ) -> dict[str, JsonValue]:
417
583
  runner = cast("str", profile.runner)
418
584
  command = _workflow_step(node.step)
@@ -423,25 +589,13 @@ def _execution_job(
423
589
  "continue-on-error": True,
424
590
  }
425
591
  )
426
- report_path = node.result.path or ""
427
592
  result_path = f"${{{{ runner.temp }}}}/quality-graph/{node.id}.json"
428
593
  collect: dict[str, JsonValue] = {
429
594
  "name": f"Collect {node.title} result",
430
595
  "id": "quality-result",
431
596
  "if": "always()",
432
597
  "uses": configuration.runtime_action,
433
- "with": {
434
- "operation": "collect",
435
- "node-id": node.id,
436
- "title": node.title,
437
- "adapter": node.result.kind.value,
438
- "report-path": report_path,
439
- "command-outcome": "${{ steps.quality-command.outcome }}",
440
- "graph-digest": graph_digest,
441
- "approval-findings": str(node.policy.approvals.findings).lower(),
442
- "approval-files": str(node.policy.approvals.files).lower(),
443
- "approval-node": str(node.policy.approvals.node).lower(),
444
- },
598
+ "with": _collection_inputs(node, graph_digest, flow),
445
599
  }
446
600
  upload: dict[str, JsonValue] = {
447
601
  "name": f"Upload {node.title} result",
@@ -477,6 +631,16 @@ def _execution_job(
477
631
  value["needs"] = list(node.needs)
478
632
  environment = _json_string_mapping(profile.environment)
479
633
  environment.update(_json_string_mapping(node.environment))
634
+ if flow is not None:
635
+ environment.update(
636
+ {
637
+ "QG_FLOW_ID": flow.id,
638
+ "QG_OPERATION_ID": node.operation_id,
639
+ "QG_NODE_ID": node.id,
640
+ "QG_NODE_TITLE": node.title,
641
+ "QG_GRAPH_DIGEST": graph_digest,
642
+ }
643
+ )
480
644
  if environment:
481
645
  value["env"] = environment
482
646
  timeout = node.timeout_minutes or profile.timeout_minutes
@@ -487,6 +651,34 @@ def _execution_job(
487
651
  return value
488
652
 
489
653
 
654
+ def _collection_inputs(node: Node, graph_digest: str, flow: Flow | None) -> dict[str, JsonValue]:
655
+ inputs: dict[str, JsonValue] = {
656
+ "operation": "collect",
657
+ "node-id": node.id,
658
+ "title": node.title,
659
+ "adapter": node.result.kind.value,
660
+ "report-path": node.result.path or "",
661
+ "command-outcome": "${{ steps.quality-command.outcome }}",
662
+ "graph-digest": graph_digest,
663
+ "approval-findings": str(node.policy.approvals.findings).lower(),
664
+ "approval-files": str(node.policy.approvals.files).lower(),
665
+ "approval-node": str(node.policy.approvals.node).lower(),
666
+ }
667
+ if flow is not None:
668
+ inputs.update(
669
+ {
670
+ "flow-id": flow.id,
671
+ "operation-id": node.operation_id,
672
+ "presentation": flow.presentation,
673
+ }
674
+ )
675
+ if flow.presentation != "github-pr":
676
+ inputs.update(
677
+ {"approval-findings": "false", "approval-files": "false", "approval-node": "false"}
678
+ )
679
+ return inputs
680
+
681
+
490
682
  def _workflow_step(step: Step) -> dict[str, JsonValue]:
491
683
  return _step_value(step)
492
684
 
@@ -542,7 +734,7 @@ def _publication_workflow(runtime_action: str) -> dict[str, JsonValue]:
542
734
  "on": {
543
735
  "workflow_run": {
544
736
  "workflows": ["Quality Graph"],
545
- "types": ["requested", "in_progress", "completed"],
737
+ "types": ["requested", "completed"],
546
738
  },
547
739
  "issue_comment": {"types": ["created", "edited"]},
548
740
  },
@@ -0,0 +1,17 @@
1
+ """Select the GitHub PR presentation adapter from trusted flow configuration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ from qg_github.compiler import project_graph
8
+
9
+ if TYPE_CHECKING:
10
+ from quality_graph_core.graph import Graph
11
+
12
+
13
+ def pr_presentation_graph(graph: Graph) -> Graph | None:
14
+ """Return PR adapter input, or disable every PR write for this declaration."""
15
+ if graph.flows and not any(flow.presentation == "github-pr" for flow in graph.flows):
16
+ return None
17
+ return project_graph(graph, "pull-request")
@@ -12,7 +12,7 @@ from typing import TYPE_CHECKING, cast
12
12
  from qg_github.approvals import approval_ledger
13
13
  from qg_github.artifacts import ArtifactError, ArtifactExpectation, download_results
14
14
  from qg_github.comments import find_managed_comment, upsert_managed_comment
15
- from qg_github.compiler import compile_graph, project_graph
15
+ from qg_github.compiler import compile_graph
16
16
  from qg_github.dashboard import (
17
17
  DASHBOARD_MARKER,
18
18
  DashboardModel,
@@ -25,6 +25,7 @@ from qg_github.dashboard import (
25
25
  )
26
26
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
27
27
  from qg_github.labels import parse_label_state, reconcile_labels
28
+ from qg_github.presentation import pr_presentation_graph
28
29
  from quality_graph_core.graph import Graph
29
30
  from quality_graph_core.policy import effective_graph
30
31
  from quality_graph_core.result import JsonValue, ResultStatus
@@ -34,6 +35,8 @@ if TYPE_CHECKING:
34
35
 
35
36
  from quality_graph_core.result import Result
36
37
 
38
+ PUBLISH_POLL_INTERVAL_SECONDS = 30.0
39
+
37
40
 
38
41
  @dataclass(frozen=True)
39
42
  class WorkflowRunEvent:
@@ -108,9 +111,22 @@ def publish_workflow_run(
108
111
  return PublicationOutcome(published=False)
109
112
  if not _is_latest_run(port, event, number):
110
113
  return PublicationOutcome(published=False)
111
- graph = Graph.from_yaml(_repository_file(port, "quality-graph.yml", pull.base_sha))
114
+ graph = Graph.from_yaml(_repository_file(port, "qg.yaml", pull.base_sha))
115
+ return _publish_completed_workflow_run(port, event, number, pull, graph)
116
+
117
+
118
+ def _publish_completed_workflow_run(
119
+ port: GitHubPort,
120
+ event: WorkflowRunEvent,
121
+ number: int,
122
+ pull: PullRequestState,
123
+ graph: Graph,
124
+ ) -> PublicationOutcome:
112
125
  compiled = compile_graph(graph)
113
- graph = project_graph(graph, "pull-request")
126
+ projected = pr_presentation_graph(graph)
127
+ if projected is None:
128
+ return PublicationOutcome(published=False)
129
+ graph = projected
114
130
  run = DashboardRun(event.id, event.attempt, pull.head_sha, event.url)
115
131
  model, effective_results = _completed_dashboard(
116
132
  port,
@@ -140,12 +156,12 @@ def watch_workflow_run(
140
156
  port: GitHubPort,
141
157
  event_value: JsonValue,
142
158
  *,
143
- poll_interval: float = 5.0,
159
+ poll_interval: float = PUBLISH_POLL_INTERVAL_SECONDS,
144
160
  sleep: Callable[[float], None] = time.sleep,
145
161
  ) -> PublicationOutcome:
146
162
  """Serialize live dashboard updates from authoritative GitHub job state."""
147
163
  event = WorkflowRunEvent.from_value(event_value)
148
- if event.event != "pull_request" or event.action not in {"requested", "in_progress"}:
164
+ if event.event != "pull_request" or event.action != "requested":
149
165
  return PublicationOutcome(published=False)
150
166
  number = event.pull_request or _resolve_pull_request(port, event.workflow_head_sha)
151
167
  if number is None:
@@ -155,18 +171,24 @@ def watch_workflow_run(
155
171
  return PublicationOutcome(published=False)
156
172
  if not _is_latest_run(port, event, number):
157
173
  return PublicationOutcome(published=False)
158
- graph = Graph.from_yaml(_repository_file(port, "quality-graph.yml", pull.base_sha))
159
- graph = project_graph(graph, "pull-request")
160
- nodes = tuple(DashboardNode(node.id, node.title) for node in graph.nodes)
174
+ graph = Graph.from_yaml(_repository_file(port, "qg.yaml", pull.base_sha))
175
+ projected = pr_presentation_graph(graph)
176
+ if projected is None:
177
+ return PublicationOutcome(published=False)
178
+ nodes = tuple(DashboardNode(node.id, node.title) for node in projected.nodes)
161
179
  run = DashboardRun(event.id, event.attempt, pull.head_sha, event.url)
162
- _publish_check(port, pending_dashboard(graph, run))
180
+ _publish_check(port, pending_dashboard(projected, run))
163
181
 
164
182
  def is_current() -> bool:
165
183
  return _is_latest_run(port, event, number)
166
184
 
167
185
  while not publish_workflow_jobs(port, number, nodes, run, is_current=is_current):
168
186
  sleep(poll_interval)
169
- return PublicationOutcome(published=True, status=ResultStatus.IN_PROGRESS)
187
+ return (
188
+ _publish_completed_workflow_run(port, event, number, pull, graph)
189
+ if is_current()
190
+ else PublicationOutcome(published=False)
191
+ )
170
192
 
171
193
 
172
194
  def publish_workflow_jobs(
@@ -185,6 +207,8 @@ def publish_workflow_jobs(
185
207
  )
186
208
  if terminal or not is_current():
187
209
  return True
210
+ if len(statuses) < len(nodes) and _workflow_run_completed(port, run.id):
211
+ return True
188
212
  existing = find_managed_comment(port, number, DASHBOARD_MARKER)
189
213
  previous_labels = parse_label_state(existing.body) if existing is not None else frozenset()
190
214
  model = live_dashboard(nodes, statuses, run, managed_labels=tuple(sorted(previous_labels)))
@@ -192,6 +216,11 @@ def publish_workflow_jobs(
192
216
  return terminal
193
217
 
194
218
 
219
+ def _workflow_run_completed(port: GitHubPort, run_id: int) -> bool:
220
+ run = _object(port.request("GET", f"/actions/runs/{run_id}"), "workflow run")
221
+ return _string(run.get("status"), "workflow run status") == "completed"
222
+
223
+
195
224
  def _workflow_jobs(port: GitHubPort, run_id: int) -> tuple[JsonValue, ...]:
196
225
  jobs: list[JsonValue] = []
197
226
  page = 1
@@ -261,6 +290,8 @@ def _completed_dashboard(
261
290
  run.id,
262
291
  graph_digest,
263
292
  frozenset(node.id for node in graph.nodes),
293
+ graph.flow_id,
294
+ {node.id: node.operation_id for node in graph.nodes if node.operation_id is not None},
264
295
  )
265
296
  try:
266
297
  results = download_results(port, expectation)
@@ -319,15 +350,15 @@ def _is_latest_run(port: GitHubPort, event: WorkflowRunEvent, number: int) -> bo
319
350
  )
320
351
  response = _object(port.request("GET", path), "workflow runs")
321
352
  runs = _array(response.get("workflow_runs", []), "workflow runs")
322
- matching_ids = [
323
- run_id
353
+ matching_runs = [
354
+ (run_id, _integer(run.get("run_attempt", 1), "workflow run attempt"))
324
355
  for value in runs
325
356
  for run in (_object(value, "workflow run"),)
326
357
  if _run_has_pull(run, number)
327
358
  for run_id in (_optional_integer(run.get("id"), "workflow run id"),)
328
359
  if run_id is not None
329
360
  ]
330
- return not matching_ids or event.id >= max(matching_ids)
361
+ return not matching_runs or (event.id, event.attempt) >= max(matching_runs)
331
362
 
332
363
 
333
364
  def _run_has_pull(run: Mapping[str, JsonValue], number: int) -> bool:
@@ -354,9 +385,11 @@ def _repository_file(port: GitHubPort, path: str, ref: str) -> str:
354
385
 
355
386
  def _publish_check(port: GitHubPort, model: DashboardModel) -> None:
356
387
  completed = model.status not in {ResultStatus.WAITING, ResultStatus.IN_PROGRESS}
388
+ external_id = f"quality-graph:{model.run_id}:{model.run_attempt}"
357
389
  payload: dict[str, JsonValue] = {
358
390
  "name": "Quality Graph",
359
391
  "head_sha": model.head_sha,
392
+ "external_id": external_id,
360
393
  "status": "completed" if completed else "in_progress",
361
394
  "details_url": next((row.logs_url for row in model.rows), ""),
362
395
  "output": {
@@ -366,7 +399,29 @@ def _publish_check(port: GitHubPort, model: DashboardModel) -> None:
366
399
  }
367
400
  if completed:
368
401
  payload["conclusion"] = "success" if model.status is ResultStatus.PASSED else "failure"
369
- port.request("POST", "/check-runs", payload)
402
+ name = urllib.parse.quote("Quality Graph", safe="")
403
+ response = _object(
404
+ port.request(
405
+ "GET",
406
+ f"/commits/{model.head_sha}/check-runs"
407
+ f"?check_name={name}&filter=all&per_page={GITHUB_PAGE_SIZE}",
408
+ ),
409
+ "check runs",
410
+ )
411
+ check_id = next(
412
+ (
413
+ _optional_integer(check.get("id"), "check run id")
414
+ for value in _array(response.get("check_runs", []), "check runs")
415
+ for check in (_object(value, "check run"),)
416
+ if check.get("external_id") == external_id
417
+ ),
418
+ None,
419
+ )
420
+ if check_id is None:
421
+ port.request("POST", "/check-runs", payload)
422
+ return
423
+ update = {key: value for key, value in payload.items() if key != "head_sha"}
424
+ port.request("PATCH", f"/check-runs/{check_id}", update)
370
425
 
371
426
 
372
427
  def read_event_json(value: str) -> dict[str, JsonValue]:
@@ -0,0 +1,389 @@
1
+ """Synchronize GitHub merge requirements from the graph declaration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import urllib.parse
6
+ from dataclasses import dataclass, replace
7
+ from http import HTTPStatus
8
+ from typing import TYPE_CHECKING, cast
9
+
10
+ from qg_github.compiler import _validate_github_graph
11
+ from qg_github.github import GitHubError
12
+
13
+ if TYPE_CHECKING:
14
+ from qg_github.github import GitHubPort
15
+ from quality_graph_core.graph import Graph
16
+ from quality_graph_core.result import JsonValue
17
+
18
+ QUALITY_GRAPH_CONTEXT = "Quality Graph"
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class RequiredChecksPlan:
23
+ """Describe one deterministic settings mutation before it is applied."""
24
+
25
+ surface: str
26
+ branch: str
27
+ method: str | None
28
+ path: str | None
29
+ payload: JsonValue
30
+ before: tuple[str, ...]
31
+ after: tuple[str, ...]
32
+
33
+ @property
34
+ def changed(self) -> bool:
35
+ """Return whether applying the plan would mutate GitHub."""
36
+ return self.method is not None
37
+
38
+ def render(self) -> str:
39
+ """Render the planned context diff for human confirmation."""
40
+ removed = sorted(set(self.before) - set(self.after))
41
+ added = sorted(set(self.after) - set(self.before))
42
+ changes = [*(f"- {item}" for item in removed), *(f"+ {item}" for item in added)]
43
+ detail = "\n".join(changes) if changes else " unchanged"
44
+ return f"Required checks plan ({self.surface}, {self.branch}):\n{detail}\n"
45
+
46
+
47
+ def plan_required_checks(port: GitHubPort, graph: Graph) -> RequiredChecksPlan:
48
+ """Read effective protection and return a preservation-safe mutation plan."""
49
+ configuration = _validate_github_graph(graph)
50
+ branch = configuration.default_branch
51
+ encoded = urllib.parse.quote(branch, safe="")
52
+ rules = _array(_request(port, "GET", f"/rules/branches/{encoded}"), "branch rules")
53
+ sources = {
54
+ (
55
+ _string(rule.get("ruleset_source_type"), "ruleset source type"),
56
+ _integer(rule.get("ruleset_id"), "ruleset id"),
57
+ )
58
+ for value in rules
59
+ for rule in (_object(value, "branch rule"),)
60
+ }
61
+ required_sources = {
62
+ source
63
+ for value in rules
64
+ for rule in (_object(value, "branch rule"),)
65
+ for source in (
66
+ (
67
+ _string(rule.get("ruleset_source_type"), "ruleset source type"),
68
+ _integer(rule.get("ruleset_id"), "ruleset id"),
69
+ ),
70
+ )
71
+ if rule.get("type") == "required_status_checks"
72
+ }
73
+ required_repository = [source for source in required_sources if source[0] == "Repository"]
74
+ required_organization = [source for source in required_sources if source[0] == "Organization"]
75
+ if required_organization:
76
+ message = (
77
+ "Required checks are controlled by an organization ruleset; "
78
+ "synchronize it with organization Administration write permission"
79
+ )
80
+ raise PermissionError(message)
81
+ classic_path = f"/branches/{encoded}/protection/required_status_checks"
82
+ classic_status = _request(port, "GET", classic_path)
83
+ if required_repository and classic_status is not None:
84
+ message = (
85
+ "Required checks are configured in both classic protection and a repository ruleset"
86
+ )
87
+ raise ValueError(message)
88
+ repository = required_repository or [source for source in sources if source[0] == "Repository"]
89
+ if len(required_repository) == 1:
90
+ return _ruleset_plan(port, branch, repository[0][1], required=configuration.merge_required)
91
+ if classic_status is not None:
92
+ return _classic_plan(
93
+ port,
94
+ branch,
95
+ encoded,
96
+ classic_status,
97
+ required=configuration.merge_required,
98
+ )
99
+ if len(repository) == 1:
100
+ return _ruleset_plan(port, branch, repository[0][1], required=configuration.merge_required)
101
+ if len(repository) > 1:
102
+ message = "Expected exactly one applicable repository ruleset"
103
+ raise ValueError(message)
104
+ return _classic_plan(
105
+ port,
106
+ branch,
107
+ encoded,
108
+ classic_status,
109
+ required=configuration.merge_required,
110
+ )
111
+
112
+
113
+ def apply_required_checks(port: GitHubPort, plan: RequiredChecksPlan) -> None:
114
+ """Apply a previously displayed synchronization plan."""
115
+ if plan.method is not None and plan.path is not None:
116
+ _request(port, plan.method, plan.path, plan.payload)
117
+
118
+
119
+ def _ruleset_plan(
120
+ port: GitHubPort,
121
+ branch: str,
122
+ ruleset_id: int,
123
+ *,
124
+ required: bool,
125
+ ) -> RequiredChecksPlan:
126
+ path = f"/rulesets/{ruleset_id}"
127
+ ruleset = _object(_request(port, "GET", path), "repository ruleset")
128
+ rules = _array(ruleset.get("rules"), "repository ruleset rules")
129
+ index = next(
130
+ (
131
+ position
132
+ for position, value in enumerate(rules)
133
+ if _object(value, "ruleset rule").get("type") == "required_status_checks"
134
+ ),
135
+ None,
136
+ )
137
+ if index is None:
138
+ if not required:
139
+ return RequiredChecksPlan("repository ruleset", branch, None, None, None, (), ())
140
+ desired_rules: list[JsonValue] = list(rules)
141
+ desired_rules.append(
142
+ {
143
+ "type": "required_status_checks",
144
+ "parameters": {
145
+ "do_not_enforce_on_create": False,
146
+ "required_status_checks": [{"context": QUALITY_GRAPH_CONTEXT}],
147
+ "strict_required_status_checks_policy": False,
148
+ },
149
+ }
150
+ )
151
+ plan = RequiredChecksPlan(
152
+ "repository ruleset", branch, None, None, None, (), (QUALITY_GRAPH_CONTEXT,)
153
+ )
154
+ return _ruleset_update(ruleset, desired_rules, path, plan)
155
+ current_rule = _object(rules[index], "required status checks rule")
156
+ parameters = _object(current_rule.get("parameters"), "required status checks parameters")
157
+ checks = _array(parameters.get("required_status_checks"), "required status checks")
158
+ before = tuple(
159
+ _string(_object(value, "required status check").get("context"), "status context")
160
+ for value in checks
161
+ )
162
+ desired_checks = _desired_check_objects(checks, required=required)
163
+ after = tuple(
164
+ _string(_object(value, "required status check").get("context"), "status context")
165
+ for value in desired_checks
166
+ )
167
+ if checks == desired_checks:
168
+ return RequiredChecksPlan("repository ruleset", branch, None, None, None, before, after)
169
+ desired_rules = list(rules)
170
+ if desired_checks:
171
+ desired_rule = current_rule | {
172
+ "parameters": parameters | {"required_status_checks": desired_checks}
173
+ }
174
+ desired_rules[index] = desired_rule
175
+ else:
176
+ desired_rules.pop(index)
177
+ plan = RequiredChecksPlan("repository ruleset", branch, None, None, None, before, after)
178
+ return _ruleset_update(ruleset, desired_rules, path, plan)
179
+
180
+
181
+ def _ruleset_update(
182
+ ruleset: dict[str, JsonValue],
183
+ rules: list[JsonValue],
184
+ path: str,
185
+ plan: RequiredChecksPlan,
186
+ ) -> RequiredChecksPlan:
187
+ payload: dict[str, JsonValue] = {
188
+ key: ruleset[key]
189
+ for key in ("name", "target", "enforcement", "bypass_actors", "conditions")
190
+ if key in ruleset
191
+ }
192
+ payload["rules"] = rules
193
+ return replace(plan, method="PUT", path=path, payload=payload)
194
+
195
+
196
+ def _classic_plan(
197
+ port: GitHubPort,
198
+ branch: str,
199
+ encoded: str,
200
+ status: JsonValue,
201
+ *,
202
+ required: bool,
203
+ ) -> RequiredChecksPlan:
204
+ path = f"/branches/{encoded}/protection/required_status_checks"
205
+ full_protection: dict[str, JsonValue] | None = None
206
+ if status is None:
207
+ if not required:
208
+ return RequiredChecksPlan("classic branch protection", branch, None, None, None, (), ())
209
+ protection = _request(port, "GET", f"/branches/{encoded}/protection")
210
+ if protection is None:
211
+ message = "Default branch has neither branch protection nor an applicable ruleset"
212
+ raise ValueError(message)
213
+ before: tuple[str, ...] = ()
214
+ strict = False
215
+ checks: list[JsonValue] | None = None
216
+ full_protection = _object(protection, "branch protection")
217
+ else:
218
+ value = _object(status, "required status check protection")
219
+ strict = bool(value.get("strict", False))
220
+ raw_checks = value.get("checks")
221
+ checks = None if raw_checks is None else _array(raw_checks, "status checks")
222
+ if checks is None:
223
+ contexts = _array(value.get("contexts", []), "status contexts")
224
+ before = tuple(_string(item, "status context") for item in contexts)
225
+ else:
226
+ before = tuple(
227
+ _string(_object(item, "status check").get("context"), "status context")
228
+ for item in checks
229
+ )
230
+ desired = _desired_contexts(before, required=required)
231
+ if before == desired:
232
+ return RequiredChecksPlan(
233
+ "classic branch protection", branch, None, None, None, before, desired
234
+ )
235
+ if status is None:
236
+ protection_payload = cast("dict[str, JsonValue]", full_protection)
237
+ required_checks: JsonValue = {"strict": strict, "contexts": list(desired)}
238
+ put_payload = _branch_protection_payload(protection_payload, required_checks)
239
+ return RequiredChecksPlan(
240
+ "classic branch protection",
241
+ branch,
242
+ "PUT",
243
+ f"/branches/{encoded}/protection",
244
+ put_payload,
245
+ before,
246
+ desired,
247
+ )
248
+ if checks is None:
249
+ payload: JsonValue = {"strict": strict, "contexts": list(desired)}
250
+ else:
251
+ desired_checks = _desired_check_objects(checks, required=required)
252
+ payload = {"strict": strict, "checks": desired_checks}
253
+ return RequiredChecksPlan(
254
+ "classic branch protection", branch, "PATCH", path, payload, before, desired
255
+ )
256
+
257
+
258
+ def _branch_protection_payload(
259
+ protection: dict[str, JsonValue], required_checks: JsonValue
260
+ ) -> JsonValue:
261
+ payload: dict[str, JsonValue] = {
262
+ "required_status_checks": required_checks,
263
+ "enforce_admins": _enabled_or_none(protection.get("enforce_admins")),
264
+ "required_pull_request_reviews": _pull_request_reviews(
265
+ protection.get("required_pull_request_reviews")
266
+ ),
267
+ "restrictions": _restrictions(protection.get("restrictions")),
268
+ }
269
+ for key in (
270
+ "required_linear_history",
271
+ "allow_force_pushes",
272
+ "allow_deletions",
273
+ "block_creations",
274
+ "required_conversation_resolution",
275
+ "lock_branch",
276
+ "allow_fork_syncing",
277
+ ):
278
+ if key in protection:
279
+ payload[key] = _enabled(protection[key], key)
280
+ return payload
281
+
282
+
283
+ def _pull_request_reviews(value: JsonValue) -> JsonValue:
284
+ if value is None:
285
+ return None
286
+ reviews = _object(value, "pull request review protection")
287
+ payload: dict[str, JsonValue] = {
288
+ key: reviews[key]
289
+ for key in (
290
+ "dismiss_stale_reviews",
291
+ "require_code_owner_reviews",
292
+ "required_approving_review_count",
293
+ "require_last_push_approval",
294
+ )
295
+ if key in reviews
296
+ }
297
+ for key in ("dismissal_restrictions", "bypass_pull_request_allowances"):
298
+ if key in reviews:
299
+ payload[key] = _restrictions(reviews[key])
300
+ return payload
301
+
302
+
303
+ def _restrictions(value: JsonValue) -> JsonValue:
304
+ if value is None:
305
+ return None
306
+ restrictions = _object(value, "branch restrictions")
307
+ return {
308
+ "users": _actor_names(restrictions.get("users", []), "login"),
309
+ "teams": _actor_names(restrictions.get("teams", []), "slug"),
310
+ "apps": _actor_names(restrictions.get("apps", []), "slug"),
311
+ }
312
+
313
+
314
+ def _actor_names(value: JsonValue, field: str) -> list[JsonValue]:
315
+ return [
316
+ _string(_object(actor, "branch restriction actor").get(field), field)
317
+ for actor in _array(value, "branch restriction actors")
318
+ ]
319
+
320
+
321
+ def _enabled_or_none(value: JsonValue) -> JsonValue:
322
+ return None if value is None else _enabled(value, "branch protection")
323
+
324
+
325
+ def _enabled(value: JsonValue, context: str) -> bool:
326
+ enabled = _object(value, context).get("enabled")
327
+ if not isinstance(enabled, bool):
328
+ message = f"{context} enabled must be a boolean"
329
+ raise TypeError(message)
330
+ return enabled
331
+
332
+
333
+ def _desired_check_objects(checks: list[JsonValue], *, required: bool) -> list[JsonValue]:
334
+ managed = [
335
+ item
336
+ for item in checks
337
+ if _object(item, "status check").get("context") == QUALITY_GRAPH_CONTEXT
338
+ ]
339
+ if required and managed:
340
+ return list(checks)
341
+ desired = [item for item in checks if item not in managed]
342
+ if required:
343
+ desired.append({"context": QUALITY_GRAPH_CONTEXT})
344
+ return desired
345
+
346
+
347
+ def _desired_contexts(contexts: tuple[str, ...], *, required: bool) -> tuple[str, ...]:
348
+ if required and QUALITY_GRAPH_CONTEXT in contexts:
349
+ return contexts
350
+ desired = tuple(item for item in contexts if item != QUALITY_GRAPH_CONTEXT)
351
+ return (*desired, QUALITY_GRAPH_CONTEXT) if required else desired
352
+
353
+
354
+ def _request(port: GitHubPort, method: str, path: str, payload: JsonValue = None) -> JsonValue:
355
+ try:
356
+ return port.request(method, path, payload)
357
+ except GitHubError as error:
358
+ if error.status_code == HTTPStatus.FORBIDDEN:
359
+ message = "GitHub token requires repository Administration write permission"
360
+ raise PermissionError(message) from error
361
+ raise
362
+
363
+
364
+ def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
365
+ if not isinstance(value, dict):
366
+ message = f"{context} must be an object"
367
+ raise TypeError(message)
368
+ return value
369
+
370
+
371
+ def _array(value: JsonValue, context: str) -> list[JsonValue]:
372
+ if not isinstance(value, list):
373
+ message = f"{context} must be an array"
374
+ raise TypeError(message)
375
+ return value
376
+
377
+
378
+ def _string(value: JsonValue, context: str) -> str:
379
+ if not isinstance(value, str):
380
+ message = f"{context} must be a string"
381
+ raise TypeError(message)
382
+ return value
383
+
384
+
385
+ def _integer(value: JsonValue, context: str) -> int:
386
+ if not isinstance(value, int) or isinstance(value, bool):
387
+ message = f"{context} must be an integer"
388
+ raise TypeError(message)
389
+ return value
@@ -10,7 +10,7 @@ from pathlib import Path
10
10
  from typing import TYPE_CHECKING, cast
11
11
 
12
12
  from qg_github.annotations import escape_data, publish_annotations
13
- from qg_github.commands import handle_command
13
+ from qg_github.commands import dispatch_pr_command as handle_command
14
14
  from qg_github.github import HttpGitHubPort
15
15
  from qg_github.publication import (
16
16
  publish_workflow_run,
@@ -48,6 +48,7 @@ class CollectionRequest:
48
48
  summary_path: Path | None
49
49
  output_path: Path
50
50
  approval_policy: ApprovalPolicy
51
+ presentation: str = "github-pr"
51
52
 
52
53
  @classmethod
53
54
  def from_environment(
@@ -65,6 +66,10 @@ class CollectionRequest:
65
66
  )
66
67
  summary = environment.get("GITHUB_STEP_SUMMARY")
67
68
  provenance = _provenance(environment, event)
69
+ presentation = environment.get("QG_PRESENTATION") or "github-pr"
70
+ if presentation not in {"github-pr", "none", "release"}:
71
+ message = f"unsupported collection presentation: {presentation}"
72
+ raise ValueError(message)
68
73
  context = AdapterContext(
69
74
  node_id,
70
75
  _required(environment, "QG_TITLE"),
@@ -84,6 +89,7 @@ class CollectionRequest:
84
89
  _boolean(environment, "QG_APPROVAL_FILES"),
85
90
  _boolean(environment, "QG_APPROVAL_NODE"),
86
91
  ),
92
+ presentation,
87
93
  )
88
94
 
89
95
 
@@ -92,9 +98,16 @@ def collect(request: CollectionRequest) -> Result:
92
98
  try:
93
99
  if request.adapter is AdapterKind.EXIT_CODE:
94
100
  state = "passed" if request.context.command_succeeded else "failed"
101
+ output = f"The declared command {state}."
102
+ if request.report_path is not None:
103
+ try:
104
+ output = read_report(request.workspace, request.report_path).decode()
105
+ except UnicodeDecodeError as error:
106
+ message = "Exit-code command output must be UTF-8"
107
+ raise AdapterError(message) from error
95
108
  return _with_policy_controls(
96
109
  request,
97
- adapt_exit(request.context, f"The declared command {state}."),
110
+ adapt_exit(request.context, output),
98
111
  )
99
112
  report = _structured_report(request)
100
113
  if request.adapter is AdapterKind.NATIVE:
@@ -109,6 +122,8 @@ def collect(request: CollectionRequest) -> Result:
109
122
 
110
123
 
111
124
  def _with_policy_controls(request: CollectionRequest, result: Result) -> Result:
125
+ if request.presentation != "github-pr":
126
+ return replace(result, controls=())
112
127
  controls = policy_controls(result.node_id, result.findings, request.approval_policy)
113
128
  return replace(result, controls=controls)
114
129
 
@@ -126,7 +141,8 @@ def publish_collection(request: CollectionRequest, result: Result) -> int:
126
141
  request.result_path.write_text(result.to_json())
127
142
  if request.summary_path is not None:
128
143
  append_job_summary(request.summary_path, result)
129
- publish_annotations(result.annotations)
144
+ if request.presentation == "github-pr":
145
+ publish_annotations(result.annotations)
130
146
  exit_code = _result_exit_code(result)
131
147
  request.output_path.parent.mkdir(parents=True, exist_ok=True)
132
148
  with request.output_path.open("a") as output:
@@ -191,6 +207,8 @@ def _provenance(
191
207
  int(_required(environment, "GITHUB_RUN_ATTEMPT")),
192
208
  _required(environment, "QG_GRAPH_DIGEST"),
193
209
  pull_number,
210
+ environment.get("QG_FLOW_ID") or None,
211
+ environment.get("QG_OPERATION_ID") or None,
194
212
  )
195
213
 
196
214