quality-graph-github 0.1.8__tar.gz → 0.1.10__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 (23) hide show
  1. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/.gitignore +1 -0
  2. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/PKG-INFO +4 -4
  3. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/pyproject.toml +4 -4
  4. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/artifacts.py +20 -4
  5. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/commands.py +26 -4
  6. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/compiler.py +315 -29
  7. quality_graph_github-0.1.10/src/qg_github/declarations.py +69 -0
  8. quality_graph_github-0.1.10/src/qg_github/presentation.py +17 -0
  9. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/publication.py +19 -8
  10. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/runtime.py +13 -2
  11. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/README.md +0 -0
  12. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/__init__.py +0 -0
  13. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/annotations.py +0 -0
  14. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/approvals.py +0 -0
  15. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/comments.py +0 -0
  16. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/controls.py +0 -0
  17. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/dashboard.py +0 -0
  18. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/github.py +0 -0
  19. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/labels.py +0 -0
  20. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/provider.py +0 -0
  21. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/py.typed +0 -0
  22. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/reporting.py +0 -0
  23. {quality_graph_github-0.1.8 → quality_graph_github-0.1.10}/src/qg_github/required_checks.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.8
3
+ Version: 0.1.10
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.8
12
+ Requires-Dist: quality-graph-core==0.1.10
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.8"
7
+ version = "0.1.10"
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.8",
16
+ "quality-graph-core==0.1.10",
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})-"
@@ -30,16 +30,22 @@ class ArtifactError(ValueError):
30
30
  """Represent an invalid or incompatible result artifact."""
31
31
 
32
32
 
33
+ class DeclarationMismatchError(ArtifactError):
34
+ """Identify a different declaration after workflow identity has been verified."""
35
+
36
+
33
37
  @dataclass(frozen=True)
34
38
  class ArtifactExpectation:
35
39
  """Describe trusted workflow provenance required from every result."""
36
40
 
37
41
  repository: str
38
- pull_request: int
42
+ pull_request: int | None
39
43
  head_sha: str
40
44
  workflow_run_id: int
41
45
  graph_digest: str
42
46
  node_ids: frozenset[str]
47
+ flow_id: str | None = None
48
+ operation_ids: Mapping[str, str] = field(default_factory=dict)
43
49
 
44
50
 
45
51
  @dataclass(frozen=True)
@@ -174,6 +180,8 @@ def _validate_result(
174
180
  expectation.workflow_run_id,
175
181
  descriptor.attempt,
176
182
  expectation.graph_digest,
183
+ expectation.flow_id,
184
+ expectation.operation_ids.get(result.node_id),
177
185
  )
178
186
  observed = (
179
187
  provenance.repository,
@@ -182,8 +190,16 @@ def _validate_result(
182
190
  provenance.workflow_run_id,
183
191
  provenance.run_attempt,
184
192
  provenance.graph_digest,
193
+ provenance.flow_id,
194
+ provenance.operation_id,
185
195
  )
186
- if result.node_id != descriptor.node_id or observed != expected:
196
+ if result.node_id != descriptor.node_id or observed[:5] != expected[:5]:
197
+ message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
198
+ raise ArtifactError(message)
199
+ if provenance.graph_digest != expectation.graph_digest:
200
+ message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
201
+ raise DeclarationMismatchError(message)
202
+ if observed[5:] != expected[5:]:
187
203
  message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
188
204
  raise ArtifactError(message)
189
205
 
@@ -9,10 +9,12 @@ from dataclasses import dataclass
9
9
  from enum import StrEnum
10
10
 
11
11
  from qg_github.approvals import ApprovalRecord, append_approval_record
12
- from qg_github.artifacts import ArtifactExpectation, download_results
13
- from qg_github.compiler import compile_graph, project_graph
12
+ from qg_github.artifacts import ArtifactExpectation
13
+ from qg_github.compiler import compile_graph
14
14
  from qg_github.controls import control_states, decode_control_marker
15
+ from qg_github.declarations import read_pr_results
15
16
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
17
+ from qg_github.presentation import pr_presentation_graph
16
18
  from quality_graph_core.graph import Graph
17
19
  from quality_graph_core.policy import ApprovalTarget, effective_graph
18
20
  from quality_graph_core.result import ControlKind, JsonValue
@@ -178,6 +180,20 @@ def handle_command(port: GitHubPort, event_value: JsonValue) -> CommandOutcome:
178
180
  return CommandOutcome(handled=True, authorized=True, changed=True)
179
181
 
180
182
 
183
+ def dispatch_pr_command(port: GitHubPort, event_value: JsonValue) -> CommandOutcome:
184
+ """Dispatch comment events only when the trusted declaration enables PR presentation."""
185
+ request = command_request(event_value)
186
+ if request is None or request.pull_request is None:
187
+ return CommandOutcome(handled=False)
188
+ pull = _object(port.request("GET", f"/pulls/{request.pull_request}"), "pull request")
189
+ base = _object(pull.get("base"), "pull request base")
190
+ base_sha = _string(base.get("sha"), "pull request base SHA")
191
+ graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
192
+ if pr_presentation_graph(graph) is None:
193
+ return CommandOutcome(handled=False)
194
+ return handle_command(port, event_value)
195
+
196
+
181
197
  # pragma: no mutate start
182
198
  def _command_context(port: GitHubPort, number: int) -> CommandContext:
183
199
  pull = _object(port.request("GET", f"/pulls/{number}"), "pull request")
@@ -187,7 +203,11 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
187
203
  base_sha = _string(base.get("sha"), "pull request base SHA")
188
204
  graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
189
205
  compiled = compile_graph(graph)
190
- graph = project_graph(graph, "pull-request")
206
+ projected = pr_presentation_graph(graph)
207
+ if projected is None:
208
+ message = "GitHub PR presentation is disabled"
209
+ raise ValueError(message)
210
+ graph = projected
191
211
  run = _latest_run(port, number)
192
212
  run_id = _integer(run.get("id"), "workflow run id")
193
213
  attempt = _integer(run.get("run_attempt", 1), "workflow run attempt")
@@ -198,8 +218,10 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
198
218
  run_id,
199
219
  compiled.graph_digest,
200
220
  frozenset(node.id for node in graph.nodes),
221
+ graph.flow_id,
222
+ {node.id: node.operation_id for node in graph.nodes if node.operation_id is not None},
201
223
  )
202
- results = download_results(port, expectation)
224
+ graph, results = read_pr_results(port, graph, expectation)
203
225
  if any(result.provenance.run_attempt > attempt for result in results.values()):
204
226
  message = "result artifact attempt exceeds the latest workflow attempt"
205
227
  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:
@@ -26,8 +35,10 @@ GENERATED_HEADER = f"# {GENERATED_NOTICE}\n---\n"
26
35
  EXECUTION_WORKFLOW = PurePosixPath(".github/workflows/quality-graph.yml")
27
36
  PUSH_WORKFLOW = PurePosixPath(".github/workflows/quality-graph-push.yml")
28
37
  PUBLICATION_WORKFLOW = PurePosixPath(".github/workflows/quality-graph-publish.yml")
38
+ RELEASE_WORKFLOW = PurePosixPath(".github/workflows/release.yml")
29
39
  GRAPH_MANIFEST = PurePosixPath(".quality-graph/manifest.json")
30
40
  DEFAULT_UPLOAD_ARTIFACT_ACTION = "actions/upload-artifact@v7"
41
+ RELEASE_UPLOAD_ARTIFACT_ACTION = "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a"
31
42
  ACTION_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?@[A-Za-z0-9_.:/-]+$")
32
43
  RUNTIME_ACTION_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[0-9a-f]{40}$")
33
44
  PERMISSION_NAMES = {
@@ -105,24 +116,47 @@ def _validate_github_graph(graph: Graph) -> _GitHubConfiguration:
105
116
  if publisher_action.partition("@")[0] != action.partition("@")[0]:
106
117
  message = "GitHub publisher action must use the runtime action repository"
107
118
  raise ValueError(message)
119
+ _validate_execution_contracts(graph)
120
+ if graph.flows:
121
+ _validate_explicit_flows(graph)
122
+ _validate_merge_presentation(graph, merge_required=merge_required)
123
+ else:
124
+ _event_projections(graph)
125
+ return _GitHubConfiguration(
126
+ action,
127
+ publisher_action,
128
+ upload_artifact_action,
129
+ default_branch,
130
+ merge_required,
131
+ )
132
+
133
+
134
+ def _validate_execution_contracts(graph: Graph) -> None:
135
+ if graph.flow_id is not None:
136
+ message = "compile the original declaration, not a resolved flow"
137
+ raise ValueError(message)
108
138
  for profile in graph.profiles:
109
- _validate_permissions(profile)
139
+ _validate_permissions(profile, allow_write=bool(graph.flows))
110
140
  for step in profile.setup:
111
141
  _validate_step(step)
112
142
  for node in graph.nodes:
113
- _validate_step(node.step)
143
+ _validate_node_contract(node, graph.expanded_profiles()[node.profile], allow_write=False)
144
+ for operation in graph.operations:
145
+ _validate_node_contract(
146
+ operation.place(FlowNode(operation.id, operation.id), DependencyPolicy.GRAPH),
147
+ graph.expanded_profiles()[operation.profile],
148
+ allow_write=True,
149
+ )
114
150
  titles = [node.title for node in graph.nodes]
115
151
  if len(set(titles)) != len(titles):
116
152
  message = "GitHub dashboard requires unique node titles"
117
153
  raise ValueError(message)
118
- _event_projections(graph)
119
- return _GitHubConfiguration(
120
- action,
121
- publisher_action,
122
- upload_artifact_action,
123
- default_branch,
124
- merge_required,
125
- )
154
+
155
+
156
+ def _validate_merge_presentation(graph: Graph, *, merge_required: bool) -> None:
157
+ if merge_required and not any(flow.presentation == "github-pr" for flow in graph.flows):
158
+ message = "merge.required needs an enabled GitHub PR presentation adapter"
159
+ raise ValueError(message)
126
160
 
127
161
 
128
162
  def _merge_required(merge: JsonValue) -> bool:
@@ -140,6 +174,16 @@ def _merge_required(merge: JsonValue) -> bool:
140
174
 
141
175
 
142
176
  def _event_projections(graph: Graph) -> tuple[EventProjection, ...]:
177
+ if graph.flows:
178
+ return tuple(
179
+ EventProjection(
180
+ "push" if flow.trigger == "push" else "pull-request",
181
+ graph.for_flow(flow.id).nodes,
182
+ flow.dependencies,
183
+ )
184
+ for flow in graph.flows
185
+ if not flow.is_release
186
+ )
143
187
  supported = set(SUPPORTED_EVENTS)
144
188
  unknown = set(graph.execution) - supported
145
189
  for node in graph.nodes:
@@ -182,9 +226,80 @@ def event_projection(graph: Graph, event: str) -> EventProjection:
182
226
 
183
227
  def project_graph(graph: Graph, event: str) -> Graph:
184
228
  """Return one dependency-normalized GitHub event graph."""
229
+ if graph.flows:
230
+ for flow in graph.flows:
231
+ if flow.trigger == event and not flow.is_release:
232
+ return graph.for_flow(flow.id)
233
+ message = f"no flow declares the {event} trigger"
234
+ raise ValueError(message)
185
235
  return replace(graph, nodes=event_projection(graph, event).nodes)
186
236
 
187
237
 
238
+ def _validate_explicit_flows(graph: Graph) -> None:
239
+ for trigger in SUPPORTED_EVENTS:
240
+ selected = [flow for flow in graph.flows if flow.trigger == trigger and not flow.is_release]
241
+ if len(selected) > 1:
242
+ message = f"GitHub supports one {trigger} flow per declaration"
243
+ raise ValueError(message)
244
+ releases = [
245
+ flow for flow in graph.flows if flow.is_release and flow.execution_mode == "github-actions"
246
+ ]
247
+ if len(releases) > 1:
248
+ message = "GitHub supports one executable release flow per declaration"
249
+ raise ValueError(message)
250
+ for flow in graph.flows:
251
+ for branch in flow.branches:
252
+ _default_branch(branch)
253
+ _validate_release_contract(graph, flow)
254
+ for node in graph.for_flow(flow.id).nodes:
255
+ _validate_node_contract(
256
+ node, graph.expanded_profiles()[node.profile], allow_write=flow.is_release
257
+ )
258
+ if flow.presentation == "github-pr":
259
+ titles = [node.title for node in graph.for_flow(flow.id).nodes]
260
+ if len(set(titles)) != len(titles):
261
+ message = "GitHub PR presentation requires unique placement titles"
262
+ raise ValueError(message)
263
+
264
+
265
+ def _validate_node_contract(node: Node, profile: Profile, *, allow_write: bool) -> None:
266
+ effective = (
267
+ replace(profile, permissions=node.permissions) if node.permissions is not None else profile
268
+ )
269
+ _validate_permissions(effective, allow_write=allow_write)
270
+ if node.deployment_environment and not allow_write:
271
+ message = "deployment environments are only allowed in release flows"
272
+ raise ValueError(message)
273
+ for step in node.steps or (node.step,):
274
+ _validate_step(step)
275
+
276
+
277
+ def _validate_release_contract(graph: Graph, flow: Flow) -> None:
278
+ for pattern in flow.tags:
279
+ if (
280
+ pattern.startswith("!")
281
+ or "${{" in pattern
282
+ or re.search(r"[\x00-\x20\x7f]", pattern)
283
+ or len(pattern) > MAX_BRANCH_NAME_LENGTH
284
+ ):
285
+ message = "release tag patterns must be literal nonnegative filters without whitespace"
286
+ raise ValueError(message)
287
+ if not flow.is_release or flow.execution_mode != "github-actions":
288
+ return
289
+ if any(node.checkpoint for node in flow.nodes):
290
+ message = (
291
+ "executable release checkpoints require a resumable provider; use design-only mode"
292
+ )
293
+ raise ValueError(message)
294
+ profiles = graph.expanded_profiles()
295
+ for node in graph.for_flow(flow.id).nodes:
296
+ profile = profiles[node.profile]
297
+ for step in (*profile.setup, *(node.steps or (node.step,))):
298
+ if step.uses is not None and re.fullmatch(r"[^@]+@[0-9a-f]{40}", step.uses) is None:
299
+ message = "executable release actions must be pinned to a 40-character commit"
300
+ raise ValueError(message)
301
+
302
+
188
303
  def _default_branch(value: JsonValue) -> str:
189
304
  branch = "main" if value is None else value
190
305
  if not isinstance(branch, str) or not 1 <= len(branch) <= MAX_BRANCH_NAME_LENGTH:
@@ -220,12 +335,12 @@ def _upload_artifact_action(runtime: Mapping[str, JsonValue]) -> str:
220
335
  return _runtime_action(runtime["upload-artifact-action"], "upload artifact")
221
336
 
222
337
 
223
- def _validate_permissions(profile: Profile) -> None:
338
+ def _validate_permissions(profile: Profile, *, allow_write: bool = False) -> None:
224
339
  for permission, access in profile.permissions.items():
225
340
  if permission not in PERMISSION_NAMES:
226
341
  message = f"unknown GitHub permission: {permission}"
227
342
  raise ValueError(message)
228
- if access not in {"none", "read"}:
343
+ if access not in ({"none", "read", "write"} if allow_write else {"none", "read"}):
229
344
  message = f"GitHub execution permission must be none or read: {permission}={access}"
230
345
  raise ValueError(message)
231
346
 
@@ -242,6 +357,8 @@ def _validate_step(step: Step) -> None:
242
357
  def compile_graph(graph: Graph) -> GeneratedProject:
243
358
  """Compile one graph through the public declaration seam."""
244
359
  configuration = _validate_github_graph(graph)
360
+ if graph.flows:
361
+ return _compile_flows(graph, configuration)
245
362
  projections = {item.event: item for item in _event_projections(graph)}
246
363
  manifest = _manifest_value(graph, configuration)
247
364
  digest = hashlib.sha256(_canonical_json(manifest).encode()).hexdigest()
@@ -279,6 +396,112 @@ def compile_graph(graph: Graph) -> GeneratedProject:
279
396
  return GeneratedProject(digest, files)
280
397
 
281
398
 
399
+ def _compile_flows(graph: Graph, configuration: _GitHubConfiguration) -> GeneratedProject:
400
+ manifest = _manifest_value(graph, configuration)
401
+ profiles = graph.expanded_profiles()
402
+ manifest.pop("nodes")
403
+ manifest["manifestVersion"] = 1
404
+ manifest["operations"] = {
405
+ operation.id: {
406
+ **_node_value(
407
+ operation.place(
408
+ FlowNode(operation.id, operation.id),
409
+ DependencyPolicy.GRAPH,
410
+ ),
411
+ profiles[operation.profile],
412
+ ),
413
+ "diffOnly": operation.diff_only,
414
+ }
415
+ for operation in graph.operations
416
+ }
417
+ manifest["flows"] = {flow.id: _flow_value(flow) for flow in graph.flows}
418
+ for contract in cast("dict[str, dict[str, JsonValue]]", manifest["operations"]).values():
419
+ contract.pop("needs")
420
+ digest = hashlib.sha256(_canonical_json(manifest).encode()).hexdigest()
421
+ manifest.update({"graphDigest": digest, "_generated": GENERATED_NOTICE})
422
+ files: list[GeneratedFile] = []
423
+ for flow in graph.flows:
424
+ if flow.execution_mode == "design-only":
425
+ continue
426
+ projection = EventProjection(flow.trigger, graph.for_flow(flow.id).nodes, flow.dependencies)
427
+ flow_configuration = configuration
428
+ if (
429
+ flow.is_release
430
+ and configuration.upload_artifact_action == DEFAULT_UPLOAD_ARTIFACT_ACTION
431
+ ):
432
+ flow_configuration = replace(
433
+ configuration, upload_artifact_action=RELEASE_UPLOAD_ARTIFACT_ACTION
434
+ )
435
+ workflow = _execution_workflow(graph, projection, flow_configuration, digest, flow=flow)
436
+ if flow.concurrency is not None:
437
+ workflow["concurrency"] = {
438
+ "group": f"quality-graph-{flow.concurrency}",
439
+ "cancel-in-progress": False,
440
+ }
441
+ if flow.is_release:
442
+ workflow["name"] = "Release"
443
+ workflow["on"] = (
444
+ {"push": {"tags": list(flow.tags)}}
445
+ if flow.tags
446
+ else {"workflow_dispatch": {"inputs": dict(flow.inputs)}}
447
+ )
448
+ elif flow.trigger == "push":
449
+ workflow["on"] = {"push": {"branches": list(flow.branches)}}
450
+ else:
451
+ workflow["on"] = {"pull_request": {"branches": [configuration.default_branch]}}
452
+ path = (
453
+ RELEASE_WORKFLOW
454
+ if flow.is_release
455
+ else EXECUTION_WORKFLOW
456
+ if flow.trigger == "pull-request"
457
+ else PUSH_WORKFLOW
458
+ )
459
+ files.append(
460
+ GeneratedFile(path, _yaml_file(workflow, width=80 if flow.is_release else 1_000))
461
+ )
462
+ if any(flow.presentation == "github-pr" for flow in graph.flows):
463
+ files.append(
464
+ GeneratedFile(
465
+ PUBLICATION_WORKFLOW,
466
+ _yaml_file(_publication_workflow(configuration.publisher_action)),
467
+ )
468
+ )
469
+ files.append(GeneratedFile(GRAPH_MANIFEST, _canonical_json(manifest)))
470
+ paths = {item.path for item in files}
471
+ retired = tuple(
472
+ path
473
+ for path in (EXECUTION_WORKFLOW, PUSH_WORKFLOW, PUBLICATION_WORKFLOW)
474
+ if path not in paths
475
+ )
476
+ return GeneratedProject(
477
+ digest, tuple(files), retired, () if RELEASE_WORKFLOW in paths else (RELEASE_WORKFLOW,)
478
+ )
479
+
480
+
481
+ def _flow_value(flow: Flow) -> dict[str, JsonValue]:
482
+ value: dict[str, JsonValue] = {
483
+ "trigger": flow.trigger,
484
+ "branches": list(flow.branches),
485
+ "inputs": dict(flow.inputs),
486
+ "dependencies": flow.dependencies.value,
487
+ "presentation": flow.presentation,
488
+ "concurrency": flow.concurrency,
489
+ "execution": flow.execution_mode,
490
+ "nodes": [
491
+ {
492
+ "id": node.id,
493
+ "operation": node.operation,
494
+ "needs": list(node.needs),
495
+ "checkpoint": dict(node.checkpoint),
496
+ }
497
+ for node in flow.nodes
498
+ ],
499
+ }
500
+ if flow.tags:
501
+ value["tags"] = list(flow.tags)
502
+ return value
503
+
504
+
282
505
  def _manifest_value(
283
506
  graph: Graph,
284
507
  configuration: _GitHubConfiguration,
@@ -353,6 +576,13 @@ def _node_value(node: Node, profile: Profile) -> dict[str, JsonValue]:
353
576
  "env": {**profile.environment, **node.environment},
354
577
  }
355
578
  _put_optional(value, "timeoutMinutes", node.timeout_minutes or profile.timeout_minutes)
579
+ if node.steps:
580
+ value.pop("step")
581
+ value["steps"] = [_step_value(step) for step in node.steps]
582
+ if node.permissions is not None:
583
+ value["permissions"] = dict(node.permissions)
584
+ if node.deployment_environment:
585
+ value["environment"] = dict(node.deployment_environment)
356
586
  if isinstance(node.failing_label, LabelSpec):
357
587
  value["failingLabel"] = _label_value(node.failing_label)
358
588
  elif node.failing_label is False:
@@ -381,6 +611,23 @@ def _labels_value(graph: Graph) -> dict[str, JsonValue]:
381
611
  return value
382
612
 
383
613
 
614
+ def pr_contract(graph: Graph) -> dict[str, JsonValue]:
615
+ """Describe effective PR checks and governance independently of pin revisions."""
616
+ profiles = graph.expanded_profiles()
617
+ configuration = dict(graph.provider.values)
618
+ runtime = cast("dict[str, JsonValue]", configuration.pop("runtime"))
619
+ return {
620
+ "provider": graph.provider.name,
621
+ "configuration": configuration,
622
+ "runtimeRepository": _runtime_action(runtime.get("action"), "runtime").partition("@")[0],
623
+ "uploadArtifactRepository": _upload_artifact_action(runtime).partition("@")[0],
624
+ "nodes": [_node_value(node, profiles[node.profile]) for node in graph.nodes],
625
+ "profiles": {node.profile: _profile_value(profiles[node.profile]) for node in graph.nodes},
626
+ "labels": _labels_value(graph),
627
+ "administration": list(graph.administrator_roles),
628
+ }
629
+
630
+
384
631
  def _label_value(label: LabelSpec) -> dict[str, JsonValue]:
385
632
  return {
386
633
  "name": label.name,
@@ -395,6 +642,8 @@ def _execution_workflow(
395
642
  projection: EventProjection,
396
643
  configuration: _GitHubConfiguration,
397
644
  digest: str,
645
+ *,
646
+ flow: Flow | None = None,
398
647
  ) -> dict[str, JsonValue]:
399
648
  profiles = graph.expanded_profiles()
400
649
  jobs: dict[str, JsonValue] = {
@@ -403,6 +652,7 @@ def _execution_workflow(
403
652
  profiles[node.profile],
404
653
  configuration,
405
654
  digest,
655
+ flow=flow,
406
656
  )
407
657
  for node in projection.nodes
408
658
  }
@@ -434,6 +684,8 @@ def _execution_job(
434
684
  profile: Profile,
435
685
  configuration: _GitHubConfiguration,
436
686
  graph_digest: str,
687
+ *,
688
+ flow: Flow | None = None,
437
689
  ) -> dict[str, JsonValue]:
438
690
  runner = cast("str", profile.runner)
439
691
  command = _workflow_step(node.step)
@@ -444,25 +696,13 @@ def _execution_job(
444
696
  "continue-on-error": True,
445
697
  }
446
698
  )
447
- report_path = node.result.path or ""
448
699
  result_path = f"${{{{ runner.temp }}}}/quality-graph/{node.id}.json"
449
700
  collect: dict[str, JsonValue] = {
450
701
  "name": f"Collect {node.title} result",
451
702
  "id": "quality-result",
452
703
  "if": "always()",
453
704
  "uses": configuration.runtime_action,
454
- "with": {
455
- "operation": "collect",
456
- "node-id": node.id,
457
- "title": node.title,
458
- "adapter": node.result.kind.value,
459
- "report-path": report_path,
460
- "command-outcome": "${{ steps.quality-command.outcome }}",
461
- "graph-digest": graph_digest,
462
- "approval-findings": str(node.policy.approvals.findings).lower(),
463
- "approval-files": str(node.policy.approvals.files).lower(),
464
- "approval-node": str(node.policy.approvals.node).lower(),
465
- },
705
+ "with": _collection_inputs(node, graph_digest, flow),
466
706
  }
467
707
  upload: dict[str, JsonValue] = {
468
708
  "name": f"Upload {node.title} result",
@@ -488,7 +728,7 @@ def _execution_job(
488
728
  "permissions": dict(profile.permissions),
489
729
  "steps": [
490
730
  *(_workflow_step(step) for step in profile.setup),
491
- command,
731
+ *([_workflow_step(step) for step in node.steps] if node.steps else [command]),
492
732
  collect,
493
733
  upload,
494
734
  enforce,
@@ -496,8 +736,24 @@ def _execution_job(
496
736
  }
497
737
  if node.needs:
498
738
  value["needs"] = list(node.needs)
739
+ if node.permissions is not None:
740
+ value["permissions"] = dict(node.permissions)
741
+ if node.deployment_environment:
742
+ value["environment"] = dict(node.deployment_environment)
743
+ if flow is not None and flow.is_release:
744
+ value["if"] = "startsWith(github.ref, 'refs/tags/')"
499
745
  environment = _json_string_mapping(profile.environment)
500
746
  environment.update(_json_string_mapping(node.environment))
747
+ if flow is not None:
748
+ environment.update(
749
+ {
750
+ "QG_FLOW_ID": flow.id,
751
+ "QG_OPERATION_ID": node.operation_id,
752
+ "QG_NODE_ID": node.id,
753
+ "QG_NODE_TITLE": node.title,
754
+ "QG_GRAPH_DIGEST": graph_digest,
755
+ }
756
+ )
501
757
  if environment:
502
758
  value["env"] = environment
503
759
  timeout = node.timeout_minutes or profile.timeout_minutes
@@ -508,6 +764,36 @@ def _execution_job(
508
764
  return value
509
765
 
510
766
 
767
+ def _collection_inputs(node: Node, graph_digest: str, flow: Flow | None) -> dict[str, JsonValue]:
768
+ inputs: dict[str, JsonValue] = {
769
+ "operation": "collect",
770
+ "node-id": node.id,
771
+ "title": node.title,
772
+ "adapter": node.result.kind.value,
773
+ "report-path": node.result.path or "",
774
+ "command-outcome": "${{ steps.quality-command.outcome }}",
775
+ "graph-digest": graph_digest,
776
+ "approval-findings": str(node.policy.approvals.findings).lower(),
777
+ "approval-files": str(node.policy.approvals.files).lower(),
778
+ "approval-node": str(node.policy.approvals.node).lower(),
779
+ }
780
+ if node.steps:
781
+ inputs["command-outcome"] = "${{ job.status }}"
782
+ if flow is not None:
783
+ inputs.update(
784
+ {
785
+ "flow-id": flow.id,
786
+ "operation-id": node.operation_id,
787
+ "presentation": flow.presentation,
788
+ }
789
+ )
790
+ if flow.presentation != "github-pr":
791
+ inputs.update(
792
+ {"approval-findings": "false", "approval-files": "false", "approval-node": "false"}
793
+ )
794
+ return inputs
795
+
796
+
511
797
  def _workflow_step(step: Step) -> dict[str, JsonValue]:
512
798
  return _step_value(step)
513
799
 
@@ -579,13 +865,13 @@ def _publication_workflow(runtime_action: str) -> dict[str, JsonValue]:
579
865
  }
580
866
 
581
867
 
582
- def _yaml_file(value: Mapping[str, JsonValue]) -> str:
868
+ def _yaml_file(value: Mapping[str, JsonValue], *, width: int = 1_000) -> str:
583
869
  body = yaml.dump(
584
870
  dict(value),
585
871
  Dumper=WorkflowDumper,
586
872
  default_flow_style=False,
587
873
  sort_keys=False,
588
- width=1_000,
874
+ width=width,
589
875
  )
590
876
  return GENERATED_HEADER + body
591
877
 
@@ -0,0 +1,69 @@
1
+ """Accept declaration migrations only when the trusted PR contract is unchanged."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ from dataclasses import replace
7
+ from typing import TYPE_CHECKING
8
+ from urllib.parse import quote
9
+
10
+ from qg_github.artifacts import DeclarationMismatchError, download_results
11
+ from qg_github.compiler import compile_graph, pr_contract
12
+ from qg_github.github import GitHubError
13
+ from qg_github.presentation import pr_presentation_graph
14
+ from quality_graph_core.graph import Graph
15
+
16
+ if TYPE_CHECKING:
17
+ from qg_github.artifacts import ArtifactExpectation
18
+ from qg_github.github import GitHubPort
19
+ from quality_graph_core.result import Result
20
+
21
+ MAX_DECLARATION_BYTES = 1_048_576
22
+
23
+
24
+ def read_pr_results(
25
+ port: GitHubPort, graph: Graph, expectation: ArtifactExpectation
26
+ ) -> tuple[Graph, dict[str, Result]]:
27
+ """Verify run provenance and allow only semantically identical PR declaration migrations."""
28
+ try:
29
+ return graph, download_results(port, expectation)
30
+ except DeclarationMismatchError as mismatch:
31
+ try:
32
+ head = _head_declaration(port, expectation.head_sha)
33
+ compiled = compile_graph(head)
34
+ projected = pr_presentation_graph(head)
35
+ except (GitHubError, ValueError, TypeError) as error:
36
+ raise mismatch from error
37
+ if (
38
+ projected is None
39
+ or compiled.graph_digest == expectation.graph_digest
40
+ or pr_contract(projected) != pr_contract(graph)
41
+ ):
42
+ raise
43
+ current = replace(
44
+ expectation,
45
+ graph_digest=compiled.graph_digest,
46
+ flow_id=projected.flow_id,
47
+ operation_ids={
48
+ node.id: node.operation_id
49
+ for node in projected.nodes
50
+ if node.operation_id is not None
51
+ },
52
+ )
53
+ return projected, download_results(port, current)
54
+
55
+
56
+ def _head_declaration(port: GitHubPort, sha: str) -> Graph:
57
+ value = port.request("GET", f"/contents/qg.yaml?ref={quote(sha, safe='')}")
58
+ if not isinstance(value, dict):
59
+ message = "head declaration response must be an object"
60
+ raise TypeError(message)
61
+ content = value.get("content")
62
+ if not isinstance(content, str):
63
+ message = "head declaration must be text"
64
+ raise TypeError(message)
65
+ decoded = base64.b64decode("".join(content.split()), validate=True)
66
+ if len(decoded) > MAX_DECLARATION_BYTES:
67
+ message = "head declaration exceeds the size limit"
68
+ raise ValueError(message)
69
+ return Graph.from_yaml(decoded.decode())
@@ -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")
@@ -10,9 +10,9 @@ from dataclasses import dataclass, replace
10
10
  from typing import TYPE_CHECKING, cast
11
11
 
12
12
  from qg_github.approvals import approval_ledger
13
- from qg_github.artifacts import ArtifactError, ArtifactExpectation, download_results
13
+ from qg_github.artifacts import ArtifactError, ArtifactExpectation
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,
@@ -23,8 +23,10 @@ from qg_github.dashboard import (
23
23
  pending_dashboard,
24
24
  render_dashboard,
25
25
  )
26
+ from qg_github.declarations import read_pr_results
26
27
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
27
28
  from qg_github.labels import parse_label_state, reconcile_labels
29
+ from qg_github.presentation import pr_presentation_graph
28
30
  from quality_graph_core.graph import Graph
29
31
  from quality_graph_core.policy import effective_graph
30
32
  from quality_graph_core.result import JsonValue, ResultStatus
@@ -122,7 +124,10 @@ def _publish_completed_workflow_run(
122
124
  graph: Graph,
123
125
  ) -> PublicationOutcome:
124
126
  compiled = compile_graph(graph)
125
- graph = project_graph(graph, "pull-request")
127
+ projected = pr_presentation_graph(graph)
128
+ if projected is None:
129
+ return PublicationOutcome(published=False)
130
+ graph = projected
126
131
  run = DashboardRun(event.id, event.attempt, pull.head_sha, event.url)
127
132
  model, effective_results = _completed_dashboard(
128
133
  port,
@@ -168,7 +173,9 @@ def watch_workflow_run(
168
173
  if not _is_latest_run(port, event, number):
169
174
  return PublicationOutcome(published=False)
170
175
  graph = Graph.from_yaml(_repository_file(port, "qg.yaml", pull.base_sha))
171
- projected = project_graph(graph, "pull-request")
176
+ projected = pr_presentation_graph(graph)
177
+ if projected is None:
178
+ return PublicationOutcome(published=False)
172
179
  nodes = tuple(DashboardNode(node.id, node.title) for node in projected.nodes)
173
180
  run = DashboardRun(event.id, event.attempt, pull.head_sha, event.url)
174
181
  _publish_check(port, pending_dashboard(projected, run))
@@ -178,9 +185,11 @@ def watch_workflow_run(
178
185
 
179
186
  while not publish_workflow_jobs(port, number, nodes, run, is_current=is_current):
180
187
  sleep(poll_interval)
181
- if not is_current():
182
- return PublicationOutcome(published=False)
183
- return _publish_completed_workflow_run(port, event, number, pull, graph)
188
+ return (
189
+ _publish_completed_workflow_run(port, event, number, pull, graph)
190
+ if is_current()
191
+ else PublicationOutcome(published=False)
192
+ )
184
193
 
185
194
 
186
195
  def publish_workflow_jobs(
@@ -282,9 +291,11 @@ def _completed_dashboard(
282
291
  run.id,
283
292
  graph_digest,
284
293
  frozenset(node.id for node in graph.nodes),
294
+ graph.flow_id,
295
+ {node.id: node.operation_id for node in graph.nodes if node.operation_id is not None},
285
296
  )
286
297
  try:
287
- results = download_results(port, expectation)
298
+ graph, results = read_pr_results(port, graph, expectation)
288
299
  except ArtifactError as error:
289
300
  nodes = tuple(DashboardNode(node.id, node.title) for node in graph.nodes)
290
301
  statuses = _workflow_node_statuses(port, nodes, run.id)
@@ -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
 
@@ -116,6 +122,8 @@ def collect(request: CollectionRequest) -> Result:
116
122
 
117
123
 
118
124
  def _with_policy_controls(request: CollectionRequest, result: Result) -> Result:
125
+ if request.presentation != "github-pr":
126
+ return replace(result, controls=())
119
127
  controls = policy_controls(result.node_id, result.findings, request.approval_policy)
120
128
  return replace(result, controls=controls)
121
129
 
@@ -133,7 +141,8 @@ def publish_collection(request: CollectionRequest, result: Result) -> int:
133
141
  request.result_path.write_text(result.to_json())
134
142
  if request.summary_path is not None:
135
143
  append_job_summary(request.summary_path, result)
136
- publish_annotations(result.annotations)
144
+ if request.presentation == "github-pr":
145
+ publish_annotations(result.annotations)
137
146
  exit_code = _result_exit_code(result)
138
147
  request.output_path.parent.mkdir(parents=True, exist_ok=True)
139
148
  with request.output_path.open("a") as output:
@@ -198,6 +207,8 @@ def _provenance(
198
207
  int(_required(environment, "GITHUB_RUN_ATTEMPT")),
199
208
  _required(environment, "QG_GRAPH_DIGEST"),
200
209
  pull_number,
210
+ environment.get("QG_FLOW_ID") or None,
211
+ environment.get("QG_OPERATION_ID") or None,
201
212
  )
202
213
 
203
214