quality-graph-gitlab 0.2.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_gitlab/compiler.py ADDED
@@ -0,0 +1,349 @@
1
+ """Compile declared checks into deterministic native GitLab pipelines."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ from dataclasses import asdict, replace
8
+ from importlib.metadata import version
9
+ from pathlib import PurePosixPath
10
+ from typing import TYPE_CHECKING
11
+
12
+ import yaml
13
+
14
+ from qg_gitlab.api import integer, server_url, string
15
+ from quality_graph_core.graph import DependencyPolicy, Graph
16
+ from quality_graph_core.provider import GeneratedFile, GeneratedProject
17
+
18
+ if TYPE_CHECKING:
19
+ from quality_graph_core.graph import Node, Profile
20
+ from quality_graph_core.result import JsonValue
21
+
22
+ RUNTIME_VERSION = version("quality-graph-gitlab")
23
+ GENERATED_HEADER = "# Generated by Quality Graph. DO NOT EDIT MANUALLY.\n"
24
+ QUALITY_EXIT_CODE = 10
25
+ DEFAULT_IMAGE = "python:3.12-slim"
26
+ INSTALL_RUNTIME = (
27
+ f"python -m pip install --disable-pip-version-check quality-graph-gitlab=={RUNTIME_VERSION}"
28
+ )
29
+
30
+
31
+ def configuration(graph: Graph) -> dict[str, JsonValue]:
32
+ """Validate GitLab settings independently of every other provider."""
33
+ if graph.provider.name != "gitlab":
34
+ message = f"GitLab cannot compile provider {graph.provider.name}"
35
+ raise ValueError(message)
36
+ values = dict(graph.provider.values)
37
+ unknown = values.keys() - {
38
+ "default-branch",
39
+ "server-url",
40
+ "api-url",
41
+ "runtime-version",
42
+ "runner-tags",
43
+ "publisher-user-id",
44
+ "publisher-tags",
45
+ "image",
46
+ "ci-path",
47
+ }
48
+ if unknown:
49
+ message = f"unknown GitLab configuration: {', '.join(sorted(unknown))}"
50
+ raise ValueError(message)
51
+ branch = string(values.get("default-branch", "main"), "default branch")
52
+ if any(character in branch for character in ('"', "\\", "\n", "\r", "$")):
53
+ message = "GitLab default branch contains unsupported expression characters"
54
+ raise ValueError(message)
55
+ values["default-branch"] = branch
56
+ values["server-url"] = server_url(
57
+ string(values.get("server-url", "https://gitlab.com"), "server URL")
58
+ )
59
+ if "api-url" in values:
60
+ values["api-url"] = server_url(string(values["api-url"], "API URL"))
61
+ runtime = string(values.get("runtime-version", RUNTIME_VERSION), "runtime version")
62
+ if runtime != RUNTIME_VERSION:
63
+ message = "GitLab runtime version must match the installed provider version"
64
+ raise ValueError(message)
65
+ values["runtime-version"] = runtime
66
+ if "publisher-user-id" in values:
67
+ integer(values["publisher-user-id"], "publisher user ID")
68
+ for name, default in (("runner-tags", ["qg-execution"]), ("publisher-tags", ["qg-publisher"])):
69
+ tags = values.get(name, default)
70
+ if (
71
+ not isinstance(tags, list)
72
+ or not tags
73
+ or any(not isinstance(tag, str) or not tag for tag in tags)
74
+ ):
75
+ message = f"{name} must be a nonempty string array"
76
+ raise ValueError(message)
77
+ values[name] = [string(tag, name) for tag in tags]
78
+ values["image"] = string(values.get("image", DEFAULT_IMAGE), "execution image")
79
+ path = values.get("ci-path", ".gitlab-ci.yml")
80
+ if path not in {".gitlab-ci.yml", ".qg/gitlab-ci.yml"}:
81
+ message = "GitLab ci-path must be .gitlab-ci.yml or .qg/gitlab-ci.yml"
82
+ raise ValueError(message)
83
+ values["ci-path"] = path
84
+ return values
85
+
86
+
87
+ def execution_graphs(graph: Graph) -> tuple[tuple[str, str, Graph], ...]:
88
+ """Project the supported MR and push executions with explicit membership."""
89
+ if graph.flows:
90
+ result: list[tuple[str, str, Graph]] = []
91
+ events: set[str] = set()
92
+ for flow in graph.flows:
93
+ if flow.is_release:
94
+ if flow.execution == "design-only":
95
+ continue
96
+ message = "GitLab executable release flows are not supported"
97
+ raise ValueError(message)
98
+ if flow.trigger not in {"pull-request", "push"} or flow.trigger in events:
99
+ message = "GitLab supports at most one MR flow and one branch flow"
100
+ raise ValueError(message)
101
+ if flow.presentation not in {"none", "gitlab-mr"}:
102
+ message = "GitLab flows require none or gitlab-mr presentation"
103
+ raise ValueError(message)
104
+ if flow.concurrency is not None or flow.execution != "design-only":
105
+ message = (
106
+ "GitLab quality flows do not support custom concurrency "
107
+ "or release execution overrides"
108
+ )
109
+ raise ValueError(message)
110
+ events.add(flow.trigger)
111
+ result.append((flow.id, flow.trigger, graph.for_flow(flow.id)))
112
+ return tuple(result)
113
+ result = []
114
+ for event, flow_id in (("pull-request", "mr"), ("push", "push")):
115
+ selected = tuple(node for node in graph.nodes if not node.events or event in node.events)
116
+ membership = {node.id for node in selected}
117
+ dependencies = graph.execution.get(event, DependencyPolicy.GRAPH)
118
+ selected = tuple(
119
+ replace(
120
+ node,
121
+ needs=tuple(need for need in node.needs if need in membership)
122
+ if dependencies is DependencyPolicy.GRAPH
123
+ else (),
124
+ )
125
+ for node in selected
126
+ )
127
+ if selected:
128
+ result.append((flow_id, event, replace(graph, nodes=selected)))
129
+ return tuple(result)
130
+
131
+
132
+ def job_name(flow_id: str, node_id: str) -> str:
133
+ """Return the compiler-owned stable native job name."""
134
+ return f"qg:{flow_id}:{node_id}"
135
+
136
+
137
+ def admission_job_name(flow_id: str) -> str:
138
+ """Reserve an internal job namespace that cannot collide with user nodes."""
139
+ return f"qg-internal:admission:{flow_id}"
140
+
141
+
142
+ def publishes_mr(graph: Graph, flow_id: str) -> bool:
143
+ """Respect explicit presentation opt-out while retaining legacy MR publication."""
144
+ return not graph.flows or any(
145
+ flow.id == flow_id and flow.presentation == "gitlab-mr" for flow in graph.flows
146
+ )
147
+
148
+
149
+ def graph_digest(graph: Graph) -> str:
150
+ """Bind execution and policy to a canonical complete declaration."""
151
+ encoded = json.dumps(asdict(graph), sort_keys=True, separators=(",", ":"))
152
+ return hashlib.sha256(encoded.encode()).hexdigest()
153
+
154
+
155
+ def _validate_node(node: Node, profile: Profile) -> None:
156
+ for step in (*profile.setup, *(node.steps or (node.step,))):
157
+ if step.uses is not None or step.arguments:
158
+ message = "GitLab steps must use repository commands, not GitHub Actions"
159
+ raise ValueError(message)
160
+ if step.shell not in {None, "sh", "bash"}:
161
+ message = "GitLab steps support sh or bash"
162
+ raise ValueError(message)
163
+ if node.deployment_environment or node.permissions is not None or profile.services:
164
+ message = (
165
+ "GitLab quality jobs do not accept deployment permissions or service escape hatches"
166
+ )
167
+ raise ValueError(message)
168
+ if profile.permissions not in ({}, {"contents": "read"}):
169
+ message = "GitHub permissions cannot be applied to GitLab quality jobs"
170
+ raise ValueError(message)
171
+ if profile.runner not in {None, "ubuntu-latest"}:
172
+ message = "Configure GitLab runner-tags instead of a GitHub profile runner"
173
+ raise ValueError(message)
174
+
175
+
176
+ def _execution_job(
177
+ node: Node, profile: Profile, flow_id: str, event: str, rule: str
178
+ ) -> dict[str, JsonValue]:
179
+ """Render one native execution job with its failure policy."""
180
+ item: dict[str, JsonValue] = {
181
+ "stage": "quality",
182
+ "rules": [{"if": rule}],
183
+ "needs": [job_name(flow_id, need) for need in node.needs],
184
+ "script": [f"qg-gitlab execute --flow {flow_id} --node {node.id}"],
185
+ "artifacts": {
186
+ "when": "always",
187
+ "paths": [f".qg/results/{flow_id}/{node.id}.json"],
188
+ "expire_in": "7 days",
189
+ },
190
+ "interruptible": True,
191
+ }
192
+ if profile.container:
193
+ item["image"] = profile.container
194
+ timeout = node.timeout_minutes or profile.timeout_minutes
195
+ if timeout:
196
+ item["timeout"] = f"{timeout} minutes"
197
+ environment = {**profile.environment, **node.environment}
198
+ if environment:
199
+ item["variables"] = dict(environment)
200
+ if not node.policy.blocking:
201
+ item["allow_failure"] = True
202
+ elif event == "pull-request":
203
+ item["allow_failure"] = {"exit_codes": [QUALITY_EXIT_CODE]}
204
+ return item
205
+
206
+
207
+ def compile_graph(graph: Graph) -> GeneratedProject:
208
+ """Generate CI, its execution manifest and a trusted publisher template."""
209
+ settings = configuration(graph)
210
+ digest = graph_digest(graph)
211
+ profiles = graph.expanded_profiles()
212
+ flows = execution_graphs(graph)
213
+ if not flows:
214
+ message = "GitLab requires at least one executable MR or branch flow"
215
+ raise ValueError(message)
216
+ if "publisher-user-id" not in settings and any(
217
+ event == "pull-request" and publishes_mr(graph, name) for name, event, _ in flows
218
+ ):
219
+ message = "GitLab MR publication requires a declared publisher-user-id"
220
+ raise ValueError(message)
221
+ workflow: dict[str, JsonValue] = {
222
+ "workflow": {
223
+ "auto_cancel": {"on_new_commit": "interruptible"},
224
+ "rules": [
225
+ {"if": '$CI_PIPELINE_SOURCE == "merge_request_event"'},
226
+ {
227
+ "if": (
228
+ '$CI_PIPELINE_SOURCE == "push" && '
229
+ "$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS"
230
+ ),
231
+ "when": "never",
232
+ },
233
+ {"if": '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'},
234
+ {"when": "never"},
235
+ ],
236
+ },
237
+ "stages": ["quality"],
238
+ "default": {
239
+ "image": settings["image"],
240
+ "tags": settings["runner-tags"],
241
+ "before_script": [INSTALL_RUNTIME],
242
+ },
243
+ }
244
+ manifests: list[JsonValue] = []
245
+ for flow_id, event, projected in flows:
246
+ rule = (
247
+ '$CI_PIPELINE_SOURCE == "merge_request_event"'
248
+ if event == "pull-request"
249
+ else '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
250
+ )
251
+ if event == "pull-request":
252
+ target_branch = json.dumps(settings["default-branch"])
253
+ rule += f" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == {target_branch}"
254
+ if graph.flows and event == "push":
255
+ declared = next(flow for flow in graph.flows if flow.id == flow_id)
256
+ if declared.branches:
257
+ choices = " || ".join(
258
+ f"$CI_COMMIT_BRANCH == {json.dumps(branch)}" for branch in declared.branches
259
+ )
260
+ rule = f"({rule}) && ({choices})"
261
+ for node in projected.nodes:
262
+ profile = profiles[node.profile]
263
+ _validate_node(node, profile)
264
+ identifier = job_name(flow_id, node.id)
265
+ mode = event if publishes_mr(graph, flow_id) else "none"
266
+ workflow[identifier] = _execution_job(node, profile, flow_id, mode, rule)
267
+ if event == "pull-request" and publishes_mr(graph, flow_id):
268
+ workflow[admission_job_name(flow_id)] = {
269
+ "stage": "quality",
270
+ "rules": [{"if": rule}],
271
+ "needs": [],
272
+ "script": [f"qg-gitlab gate --flow {flow_id}"],
273
+ "timeout": "5 minutes",
274
+ "interruptible": True,
275
+ }
276
+ manifests.append(
277
+ {
278
+ "id": flow_id,
279
+ "event": event,
280
+ "nodes": [
281
+ {
282
+ "id": node.id,
283
+ "job": job_name(flow_id, node.id),
284
+ "operation": node.operation_id,
285
+ }
286
+ for node in projected.nodes
287
+ ],
288
+ }
289
+ )
290
+ manifest: dict[str, JsonValue] = {"version": 1, "graphDigest": digest, "flows": manifests}
291
+ publisher: dict[str, JsonValue] = {
292
+ "workflow": {
293
+ "rules": [
294
+ {
295
+ "if": (
296
+ '$CI_COMMIT_REF_PROTECTED == "true" && '
297
+ "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && ("
298
+ '$CI_PIPELINE_SOURCE == "trigger" || '
299
+ '$CI_PIPELINE_SOURCE == "schedule" || $CI_PIPELINE_SOURCE == "web")'
300
+ )
301
+ },
302
+ {"when": "never"},
303
+ ]
304
+ },
305
+ "publish": {
306
+ "image": DEFAULT_IMAGE,
307
+ "tags": settings["publisher-tags"],
308
+ "variables": {"GIT_STRATEGY": "none"},
309
+ "resource_group": "quality-graph-publication",
310
+ "before_script": [INSTALL_RUNTIME],
311
+ "script": ["qg-gitlab publish"],
312
+ "timeout": "10 minutes",
313
+ },
314
+ }
315
+ files = (
316
+ GeneratedFile(
317
+ PurePosixPath(string(settings["ci-path"], "CI path")),
318
+ GENERATED_HEADER
319
+ + yaml.safe_dump(workflow, sort_keys=False, width=80, explicit_start=True),
320
+ ),
321
+ GeneratedFile(
322
+ PurePosixPath(".qg/gitlab.json"), json.dumps(manifest, indent=2, sort_keys=True) + "\n"
323
+ ),
324
+ GeneratedFile(
325
+ PurePosixPath(".qg/gitlab-publisher.yml"),
326
+ GENERATED_HEADER
327
+ + yaml.safe_dump(publisher, sort_keys=False, width=80, explicit_start=True),
328
+ ),
329
+ )
330
+ return GeneratedProject(digest, files)
331
+
332
+
333
+ def starter(default_branch: str) -> str:
334
+ """Create a provider-native starter without requiring GitHub Actions."""
335
+ value: dict[str, JsonValue] = {
336
+ "version": 0,
337
+ "provider": {
338
+ "name": "gitlab",
339
+ "configuration": {
340
+ "default-branch": default_branch,
341
+ "server-url": "https://gitlab.com",
342
+ "runtime-version": RUNTIME_VERSION,
343
+ },
344
+ },
345
+ "profiles": {"default": {"container": DEFAULT_IMAGE}},
346
+ "administration": {"roles": ["maintain", "admin"]},
347
+ "nodes": {"quality": {"title": "Quality", "run": "make check"}},
348
+ }
349
+ return yaml.safe_dump(value, sort_keys=False)
qg_gitlab/markers.py ADDED
@@ -0,0 +1,11 @@
1
+ """Encode acknowledgements of installed trusted pipeline statuses."""
2
+
3
+
4
+ def gate_marker(project: int, pipeline: int, flow: str, digest: str) -> str:
5
+ """Bind initial pipeline admission to one declaration and flow."""
6
+ return f"<!-- qg:gitlab:gate:{project}:{pipeline}:{flow}:{digest} -->"
7
+
8
+
9
+ def execution_marker(project: int, pipeline: int, job: int, digest: str) -> str:
10
+ """Require a new publisher acknowledgement for every retried job."""
11
+ return f"<!-- qg:gitlab:job:{project}:{pipeline}:{job}:{digest} -->"