quality-graph-github 0.1.0__py3-none-any.whl

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.
qg_github/compiler.py ADDED
@@ -0,0 +1,398 @@
1
+ """Compile a validated graph into deterministic GitHub Actions files."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import re
8
+ from pathlib import PurePosixPath
9
+ from typing import TYPE_CHECKING, cast, override
10
+
11
+ import yaml
12
+
13
+ from quality_graph_core.graph import Graph, LabelSpec, Node, Profile, Step
14
+ from quality_graph_core.provider import GeneratedFile, GeneratedProject
15
+
16
+ if TYPE_CHECKING:
17
+ from collections.abc import Mapping
18
+
19
+ from quality_graph_core.result import JsonValue
20
+
21
+ GENERATED_HEADER = "# Generated by Quality Graph. Do not edit.\n---\n"
22
+ EXECUTION_WORKFLOW = PurePosixPath(".github/workflows/quality-graph.yml")
23
+ PUBLICATION_WORKFLOW = PurePosixPath(".github/workflows/quality-graph-publish.yml")
24
+ GRAPH_MANIFEST = PurePosixPath(".quality-graph/manifest.json")
25
+ UPLOAD_ARTIFACT_ACTION = "actions/upload-artifact@v7"
26
+ ACTION_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?@[A-Za-z0-9_.:/-]+$")
27
+ RUNTIME_ACTION_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[0-9a-f]{40}$")
28
+ PERMISSION_NAMES = {
29
+ "actions",
30
+ "checks",
31
+ "contents",
32
+ "deployments",
33
+ "discussions",
34
+ "id-token",
35
+ "issues",
36
+ "packages",
37
+ "pages",
38
+ "pull-requests",
39
+ "repository-projects",
40
+ "security-events",
41
+ "statuses",
42
+ }
43
+
44
+
45
+ class WorkflowDumper(yaml.SafeDumper):
46
+ """Render deterministic YAML without aliases for shared immutable values."""
47
+
48
+ @override
49
+ def ignore_aliases(self, _data: object) -> bool:
50
+ """Keep generated workflows locally readable."""
51
+ return True
52
+
53
+
54
+ def _validate_github_graph(graph: Graph) -> str:
55
+ if graph.provider.name != "github":
56
+ message = f"GitHub provider cannot compile provider '{graph.provider.name}'"
57
+ raise ValueError(message)
58
+ unknown = graph.provider.values.keys() - {"runtime"}
59
+ if unknown:
60
+ message = f"GitHub provider contains unknown configuration: {', '.join(sorted(unknown))}"
61
+ raise ValueError(message)
62
+ runtime = graph.provider.values.get("runtime")
63
+ if not isinstance(runtime, dict):
64
+ message = "GitHub provider requires a runtime object"
65
+ raise TypeError(message)
66
+ if runtime.keys() - {"action"}:
67
+ message = "GitHub runtime contains unknown fields"
68
+ raise ValueError(message)
69
+ action = runtime.get("action")
70
+ if not isinstance(action, str) or RUNTIME_ACTION_RE.fullmatch(action) is None:
71
+ message = "GitHub runtime action must use owner/repository@40-character-commit"
72
+ raise ValueError(message)
73
+ for profile in graph.profiles:
74
+ _validate_permissions(profile)
75
+ for step in profile.setup:
76
+ _validate_step(step)
77
+ for node in graph.nodes:
78
+ _validate_step(node.step)
79
+ return action
80
+
81
+
82
+ def _validate_permissions(profile: Profile) -> None:
83
+ for permission, access in profile.permissions.items():
84
+ if permission not in PERMISSION_NAMES:
85
+ message = f"unknown GitHub permission: {permission}"
86
+ raise ValueError(message)
87
+ if access not in {"none", "read"}:
88
+ message = f"GitHub execution permission must be none or read: {permission}={access}"
89
+ raise ValueError(message)
90
+
91
+
92
+ def _validate_step(step: Step) -> None:
93
+ if step.uses is not None and ACTION_RE.fullmatch(step.uses) is None:
94
+ message = f"GitHub action must include an explicit ref: {step.uses}"
95
+ raise ValueError(message)
96
+ if step.uses is not None and (step.working_directory is not None or step.shell is not None):
97
+ message = "GitHub uses steps cannot define working-directory or shell"
98
+ raise ValueError(message)
99
+
100
+
101
+ def compile_graph(graph: Graph) -> GeneratedProject:
102
+ """Compile one graph through the public declaration seam."""
103
+ runtime_action = _validate_github_graph(graph)
104
+ manifest = _manifest_value(graph, runtime_action)
105
+ digest = hashlib.sha256(_canonical_json(manifest).encode()).hexdigest()
106
+ manifest["graphDigest"] = digest
107
+ files = (
108
+ GeneratedFile(
109
+ EXECUTION_WORKFLOW,
110
+ _yaml_file(_execution_workflow(graph, runtime_action, digest)),
111
+ ),
112
+ GeneratedFile(
113
+ PUBLICATION_WORKFLOW,
114
+ _yaml_file(_publication_workflow(runtime_action)),
115
+ ),
116
+ GeneratedFile(GRAPH_MANIFEST, _canonical_json(manifest)),
117
+ )
118
+ return GeneratedProject(digest, files)
119
+
120
+
121
+ def _manifest_value(graph: Graph, runtime_action: str) -> dict[str, JsonValue]:
122
+ profiles = graph.expanded_profiles()
123
+ return {
124
+ "manifestVersion": 0,
125
+ "graphVersion": graph.version,
126
+ "provider": graph.provider.name,
127
+ "resultSchemaVersion": 0,
128
+ "runtime": {"action": runtime_action},
129
+ "profiles": {name: _profile_value(profile) for name, profile in profiles.items()},
130
+ "nodes": [_node_value(node, profiles[node.profile]) for node in graph.nodes],
131
+ "labels": _labels_value(graph),
132
+ "administration": {"roles": list(graph.administrator_roles)},
133
+ }
134
+
135
+
136
+ def _profile_value(profile: Profile) -> dict[str, JsonValue]:
137
+ value: dict[str, JsonValue] = {
138
+ "runner": profile.runner,
139
+ "setup": [_step_value(step) for step in profile.setup],
140
+ "env": dict(profile.environment),
141
+ "permissions": dict(profile.permissions),
142
+ "services": dict(profile.services),
143
+ }
144
+ _put_optional(value, "timeoutMinutes", profile.timeout_minutes)
145
+ _put_optional(value, "container", profile.container)
146
+ return value
147
+
148
+
149
+ def _node_value(node: Node, profile: Profile) -> dict[str, JsonValue]:
150
+ result_value: dict[str, JsonValue] = {"adapter": node.result.kind.value}
151
+ _put_optional(result_value, "path", node.result.path)
152
+ value: dict[str, JsonValue] = {
153
+ "id": node.id,
154
+ "title": node.title,
155
+ "profile": node.profile,
156
+ "needs": list(node.needs),
157
+ "step": _step_value(node.step),
158
+ "result": result_value,
159
+ "policy": {
160
+ "blocking": node.policy.blocking,
161
+ "blockingSeverities": [severity.value for severity in node.policy.blocking_severities],
162
+ "approvals": {
163
+ "findings": node.policy.approvals.findings,
164
+ "files": node.policy.approvals.files,
165
+ "node": node.policy.approvals.node,
166
+ },
167
+ },
168
+ "env": {**profile.environment, **node.environment},
169
+ }
170
+ _put_optional(value, "timeoutMinutes", node.timeout_minutes or profile.timeout_minutes)
171
+ if isinstance(node.failing_label, LabelSpec):
172
+ value["failingLabel"] = _label_value(node.failing_label)
173
+ elif node.failing_label is False:
174
+ value["failingLabel"] = False
175
+ return value
176
+
177
+
178
+ def _step_value(step: Step) -> dict[str, JsonValue]:
179
+ value: dict[str, JsonValue] = {}
180
+ _put_optional(value, "name", step.name)
181
+ _put_optional(value, "run", step.run)
182
+ _put_optional(value, "uses", step.uses)
183
+ if step.arguments:
184
+ value["with"] = dict(step.arguments)
185
+ if step.environment:
186
+ value["env"] = dict(step.environment)
187
+ _put_optional(value, "working-directory", step.working_directory)
188
+ _put_optional(value, "shell", step.shell)
189
+ return value
190
+
191
+
192
+ def _labels_value(graph: Graph) -> dict[str, JsonValue]:
193
+ value: dict[str, JsonValue] = {"enabled": graph.labels.enabled}
194
+ if graph.labels.failing is not None:
195
+ value["failing"] = _label_value(graph.labels.failing)
196
+ return value
197
+
198
+
199
+ def _label_value(label: LabelSpec) -> dict[str, JsonValue]:
200
+ return {
201
+ "name": label.name,
202
+ "color": label.color.lower(),
203
+ "description": label.description,
204
+ "create": label.create,
205
+ }
206
+
207
+
208
+ def _execution_workflow(
209
+ graph: Graph,
210
+ runtime_action: str,
211
+ digest: str,
212
+ ) -> dict[str, JsonValue]:
213
+ profiles = graph.expanded_profiles()
214
+ jobs: dict[str, JsonValue] = {
215
+ node.id: _execution_job(node, profiles[node.profile], runtime_action, digest)
216
+ for node in graph.nodes
217
+ }
218
+ return {
219
+ "name": "Quality Graph",
220
+ "on": {
221
+ "pull_request": {"branches": ["main"]},
222
+ "push": {"branches": ["main"]},
223
+ "workflow_dispatch": {},
224
+ },
225
+ "permissions": {"contents": "read"},
226
+ "concurrency": {
227
+ "group": "quality-graph-${{ github.workflow }}-${{ github.ref }}",
228
+ "cancel-in-progress": True,
229
+ },
230
+ "jobs": jobs,
231
+ }
232
+
233
+
234
+ def _execution_job(
235
+ node: Node,
236
+ profile: Profile,
237
+ runtime_action: str,
238
+ graph_digest: str,
239
+ ) -> dict[str, JsonValue]:
240
+ runner = cast("str", profile.runner)
241
+ command = _workflow_step(node.step)
242
+ command.update(
243
+ {
244
+ "name": f"Run {node.title}",
245
+ "id": "quality-command",
246
+ "continue-on-error": True,
247
+ }
248
+ )
249
+ report_path = node.result.path or ""
250
+ result_path = f"${{{{ runner.temp }}}}/quality-graph/{node.id}.json"
251
+ collect: dict[str, JsonValue] = {
252
+ "name": f"Collect {node.title} result",
253
+ "id": "quality-result",
254
+ "if": "always()",
255
+ "uses": runtime_action,
256
+ "with": {
257
+ "operation": "collect",
258
+ "node-id": node.id,
259
+ "title": node.title,
260
+ "adapter": node.result.kind.value,
261
+ "report-path": report_path,
262
+ "command-outcome": "${{ steps.quality-command.outcome }}",
263
+ "graph-digest": graph_digest,
264
+ },
265
+ }
266
+ upload: dict[str, JsonValue] = {
267
+ "name": f"Upload {node.title} result",
268
+ "if": "always()",
269
+ "uses": UPLOAD_ARTIFACT_ACTION,
270
+ "with": {
271
+ "name": f"quality-result-{node.id}-${{{{ github.run_attempt }}}}",
272
+ "path": result_path,
273
+ "if-no-files-found": "error",
274
+ "retention-days": 7,
275
+ },
276
+ }
277
+ enforce: dict[str, JsonValue] = {
278
+ "name": f"Enforce {node.title} result",
279
+ "if": "always()",
280
+ "shell": "bash",
281
+ "env": {"EXIT_CODE": "${{ steps.quality-result.outputs.exit-code }}"},
282
+ "run": 'exit "${EXIT_CODE:-2}"',
283
+ }
284
+ value: dict[str, JsonValue] = {
285
+ "name": node.title,
286
+ "runs-on": runner,
287
+ "permissions": dict(profile.permissions),
288
+ "steps": [
289
+ *(_workflow_step(step) for step in profile.setup),
290
+ command,
291
+ collect,
292
+ upload,
293
+ enforce,
294
+ ],
295
+ }
296
+ if node.needs:
297
+ value["needs"] = list(node.needs)
298
+ environment = _json_string_mapping(profile.environment)
299
+ environment.update(_json_string_mapping(node.environment))
300
+ if environment:
301
+ value["env"] = environment
302
+ timeout = node.timeout_minutes or profile.timeout_minutes
303
+ _put_optional(value, "timeout-minutes", timeout)
304
+ _put_optional(value, "container", profile.container)
305
+ if profile.services:
306
+ value["services"] = dict(profile.services)
307
+ return value
308
+
309
+
310
+ def _workflow_step(step: Step) -> dict[str, JsonValue]:
311
+ return _step_value(step)
312
+
313
+
314
+ def _publication_workflow(runtime_action: str) -> dict[str, JsonValue]:
315
+ publish_permissions: dict[str, JsonValue] = {
316
+ "actions": "read",
317
+ "checks": "write",
318
+ "contents": "read",
319
+ "issues": "write",
320
+ "pull-requests": "write",
321
+ }
322
+ publish_job: dict[str, JsonValue] = {
323
+ "name": "Publish Quality Graph",
324
+ "if": (
325
+ "github.event_name == 'workflow_run' "
326
+ "&& github.event.workflow_run.event == 'pull_request'"
327
+ ),
328
+ "runs-on": "ubuntu-latest",
329
+ "permissions": publish_permissions,
330
+ "steps": [
331
+ {
332
+ "name": "Publish trusted Quality Graph state",
333
+ "uses": runtime_action,
334
+ "with": {"operation": "publish"},
335
+ }
336
+ ],
337
+ }
338
+ command_job: dict[str, JsonValue] = {
339
+ "name": "Handle Quality Graph command",
340
+ "if": "github.event_name == 'issue_comment' && github.event.issue.pull_request",
341
+ "runs-on": "ubuntu-latest",
342
+ "permissions": {
343
+ "actions": "write",
344
+ "contents": "read",
345
+ "issues": "write",
346
+ "pull-requests": "write",
347
+ },
348
+ "steps": [
349
+ {
350
+ "name": "Handle trusted Quality Graph command",
351
+ "uses": runtime_action,
352
+ "with": {"operation": "command"},
353
+ }
354
+ ],
355
+ }
356
+ return {
357
+ "name": "Quality Graph Publisher",
358
+ "on": {
359
+ "workflow_run": {
360
+ "workflows": ["Quality Graph"],
361
+ "types": ["requested", "in_progress", "completed"],
362
+ },
363
+ "issue_comment": {"types": ["created", "edited"]},
364
+ },
365
+ "permissions": {},
366
+ "concurrency": {
367
+ "group": (
368
+ "quality-graph-publish-"
369
+ "${{ github.event.workflow_run.id || github.event.issue.number }}"
370
+ ),
371
+ "cancel-in-progress": False,
372
+ },
373
+ "jobs": {"publish": publish_job, "command": command_job},
374
+ }
375
+
376
+
377
+ def _yaml_file(value: Mapping[str, JsonValue]) -> str:
378
+ body = yaml.dump(
379
+ dict(value),
380
+ Dumper=WorkflowDumper,
381
+ default_flow_style=False,
382
+ sort_keys=False,
383
+ width=1_000,
384
+ )
385
+ return GENERATED_HEADER + body
386
+
387
+
388
+ def _canonical_json(value: JsonValue) -> str:
389
+ return json.dumps(value, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
390
+
391
+
392
+ def _json_string_mapping(value: Mapping[str, str]) -> dict[str, JsonValue]:
393
+ return dict(value)
394
+
395
+
396
+ def _put_optional(target: dict[str, JsonValue], key: str, value: JsonValue) -> None:
397
+ if value is not None:
398
+ target[key] = value
qg_github/controls.py ADDED
@@ -0,0 +1,67 @@
1
+ """Encode reversible dashboard controls without granting authority to Markdown."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import html
7
+ import re
8
+
9
+ from quality_graph_core.result import Control, ControlKind
10
+
11
+ CONTROL_RE = re.compile(
12
+ r"^- \[(?P<state>[ xX])] .*?<!-- (?P<marker>quality-graph-control:[A-Za-z0-9_-]+) -->$",
13
+ re.MULTILINE,
14
+ )
15
+ CONTROL_COMMAND_COUNT = 2
16
+
17
+
18
+ def control_commands(control: Control) -> tuple[str, str]:
19
+ """Return canonical apply and reverse commands for one control."""
20
+ if control.kind is ControlKind.FILE:
21
+ apply_name = "ignore-file"
22
+ reverse_name = "remove-ignore-file"
23
+ else:
24
+ apply_name = "ignore"
25
+ reverse_name = "remove-ignore"
26
+ return (
27
+ f"/qg {apply_name} {control.target}",
28
+ f"/qg {reverse_name} {control.target}",
29
+ )
30
+
31
+
32
+ def control_marker(control: Control) -> str:
33
+ """Encode both canonical commands in one stable hidden marker."""
34
+ payload = "\n".join(control_commands(control)).encode()
35
+ encoded = base64.urlsafe_b64encode(payload).decode().rstrip("=")
36
+ return f"quality-graph-control:{encoded}"
37
+
38
+
39
+ def decode_control_marker(value: str) -> tuple[str, str] | None:
40
+ """Decode a marker produced by the canonical renderer."""
41
+ encoded = value.removeprefix("quality-graph-control:")
42
+ try:
43
+ payload = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)).decode()
44
+ except (ValueError, UnicodeDecodeError):
45
+ return None
46
+ commands = payload.splitlines()
47
+ if len(commands) != CONTROL_COMMAND_COUNT or any(
48
+ not command.startswith("/qg ") for command in commands
49
+ ):
50
+ return None
51
+ return commands[0], commands[1]
52
+
53
+
54
+ def control_states(body: str) -> dict[str, bool]:
55
+ """Extract canonical checkbox states keyed by hidden marker."""
56
+ return {
57
+ match.group("marker"): match.group("state").lower() == "x"
58
+ for match in CONTROL_RE.finditer(body)
59
+ }
60
+
61
+
62
+ def render_control(control: Control) -> str:
63
+ """Render one reversible checkbox control."""
64
+ state = "x" if control.checked else " "
65
+ marker = control_marker(control)
66
+ target = html.escape(control.target)
67
+ return f"- [{state}] {control.kind.value}: `{target}` <!-- {marker} -->"