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.
@@ -0,0 +1,588 @@
1
+ """Reconcile trusted GitLab merge-request publication from admitted evidence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import html
6
+ import json
7
+ import os
8
+ import re
9
+ import sys
10
+ import urllib.parse
11
+ from dataclasses import dataclass
12
+ from typing import TYPE_CHECKING
13
+
14
+ from qg_gitlab.admission import BOOTSTRAP_KEY, Expectation, NodeEvidence, admit
15
+ from qg_gitlab.api import GitLabError, HttpGitLab, integer, object_value, string
16
+ from qg_gitlab.compiler import configuration, execution_graphs, graph_digest, publishes_mr
17
+ from qg_gitlab.markers import execution_marker, gate_marker
18
+ from quality_graph_core.graph import Graph, LabelSpec
19
+ from quality_graph_core.policy import ApprovalTarget, effective_graph
20
+ from quality_graph_core.result import ControlKind, ResultStatus
21
+
22
+ if TYPE_CHECKING:
23
+ from collections.abc import Mapping
24
+
25
+ from quality_graph_core.result import JsonValue, Result
26
+
27
+ SUMMARY_MARKER = "<!-- quality-graph:gitlab:summary -->"
28
+ RECORD_RE = re.compile(r"<!-- quality-graph:gitlab:record:(\{[^\n]+\}) -->")
29
+ COMMAND_RE = re.compile(
30
+ r"^/qg(?:\s+(help|status|ignore|remove-ignore|ignore-file|remove-ignore-file)(?:\s+(\S+))?)?$"
31
+ )
32
+ STATUS_NAME = "Quality Graph"
33
+ MAINTAINER_ACCESS = 40
34
+ OWNER_ACCESS = 50
35
+ DEVELOPER_ACCESS = 30
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Publication:
40
+ """Report one reconciled merge-request outcome."""
41
+
42
+ project: int
43
+ merge_request: int
44
+ pipeline: int
45
+ state: str
46
+ changed: bool
47
+
48
+
49
+ def _notes(api: HttpGitLab, project: int, mr: int) -> tuple[dict[str, JsonValue], ...]:
50
+ return tuple(api.pages(f"/projects/{project}/merge_requests/{mr}/notes"))
51
+
52
+
53
+ def _owned(note: Mapping[str, JsonValue], actor: int) -> bool:
54
+ author = note.get("author")
55
+ return isinstance(author, dict) and author.get("id") == actor
56
+
57
+
58
+ def _ledger(
59
+ notes: tuple[dict[str, JsonValue], ...], actor: int, expected: Expectation
60
+ ) -> tuple[set[ApprovalTarget], set[int]]:
61
+ approvals: set[ApprovalTarget] = set()
62
+ processed: set[int] = set()
63
+ for note in sorted(notes, key=lambda value: integer(value.get("id"), "note ID")):
64
+ body = note.get("body")
65
+ if (
66
+ not _owned(note, actor)
67
+ or note.get("created_at") != note.get("updated_at")
68
+ or not isinstance(body, str)
69
+ ):
70
+ continue
71
+ match = RECORD_RE.search(body)
72
+ if match is None:
73
+ continue
74
+ try:
75
+ record = object_value(json.loads(match.group(1)), "approval record")
76
+ if (
77
+ integer(record.get("version"), "record version") != 1
78
+ or integer(record.get("projectId"), "record project") != expected.target_project_id
79
+ or integer(record.get("mergeRequest"), "record MR") != expected.merge_request
80
+ ):
81
+ continue
82
+ note_id = integer(record.get("sourceNoteId"), "source note ID")
83
+ integer(record.get("actorId"), "approval actor ID")
84
+ if note_id in processed:
85
+ continue
86
+ targets = record.get("targets", [])
87
+ if not isinstance(targets, list) or not all(
88
+ isinstance(target, str) for target in targets
89
+ ):
90
+ continue
91
+ parsed = {
92
+ ApprovalTarget.from_key(string(target, "approval target")) for target in targets
93
+ }
94
+ if record.get("operation") == "add":
95
+ approvals.update(parsed)
96
+ elif record.get("operation") == "remove":
97
+ approvals.difference_update(parsed)
98
+ processed.add(note_id)
99
+ except (TypeError, ValueError):
100
+ continue
101
+ return approvals, processed
102
+
103
+
104
+ @dataclass(frozen=True)
105
+ class ApprovalAction:
106
+ """Carry an authenticated command decision for the immutable ledger."""
107
+
108
+ note_id: int
109
+ actor: int
110
+ operation: str
111
+ targets: set[ApprovalTarget]
112
+ message: str
113
+
114
+
115
+ def _record(api: HttpGitLab, expected: Expectation, action: ApprovalAction) -> None:
116
+ record: dict[str, JsonValue] = {
117
+ "version": 1,
118
+ "projectId": expected.target_project_id,
119
+ "mergeRequest": expected.merge_request,
120
+ "sourceNoteId": action.note_id,
121
+ "actorId": action.actor,
122
+ "operation": action.operation,
123
+ "targets": [str(target) for target in sorted(t.key for t in action.targets)],
124
+ }
125
+ marker = (
126
+ "<!-- quality-graph:gitlab:record:"
127
+ + json.dumps(record, sort_keys=True, separators=(",", ":"))
128
+ + " -->"
129
+ )
130
+ api.request(
131
+ "POST",
132
+ f"/projects/{expected.target_project_id}/merge_requests/{expected.merge_request}/notes",
133
+ {
134
+ "body": f"{action.message}\n\n{marker}",
135
+ },
136
+ )
137
+
138
+
139
+ def _authorized(api: HttpGitLab, project: int, actor: int, graph: Graph) -> bool:
140
+ try:
141
+ membership = object_value(
142
+ api.request("GET", f"/projects/{project}/members/all/{actor}"), "member"
143
+ )
144
+ except GitLabError as error:
145
+ if error.status in {403, 404}:
146
+ return False
147
+ raise
148
+ minimum = min(
149
+ {"admin": OWNER_ACCESS, "maintain": MAINTAINER_ACCESS, "write": DEVELOPER_ACCESS}[role]
150
+ for role in graph.administrator_roles
151
+ )
152
+ access = membership.get("access_level")
153
+ return isinstance(access, int) and not isinstance(access, bool) and access >= minimum
154
+
155
+
156
+ def _command_targets(
157
+ command: str, arguments: str | None, available: frozenset[ApprovalTarget]
158
+ ) -> set[ApprovalTarget]:
159
+ if arguments is None:
160
+ return set()
161
+ selected: set[ApprovalTarget] = set()
162
+ for argument in arguments.split(","):
163
+ matches = {
164
+ target
165
+ for target in available
166
+ if target.target == argument
167
+ and (
168
+ target.kind is ControlKind.FILE
169
+ if command.endswith("file")
170
+ else target.kind in {ControlKind.FINDING, ControlKind.NODE}
171
+ )
172
+ }
173
+ if not matches:
174
+ return set()
175
+ selected.update(matches)
176
+ return selected
177
+
178
+
179
+ def _commands(
180
+ api: HttpGitLab,
181
+ expected: Expectation,
182
+ evidence: Mapping[str, NodeEvidence],
183
+ bot: int,
184
+ notes: tuple[dict[str, JsonValue], ...],
185
+ ) -> set[ApprovalTarget]:
186
+ approvals, processed = _ledger(notes, bot, expected)
187
+ results = {key: item.result for key, item in evidence.items() if item.result is not None}
188
+ available = effective_graph(expected.graph, results, approvals).targets
189
+ for note in sorted(notes, key=lambda item: integer(item.get("id"), "note ID")):
190
+ note_id = integer(note.get("id"), "note ID")
191
+ body = note.get("body")
192
+ if note_id in processed or _owned(note, bot) or not isinstance(body, str):
193
+ continue
194
+ match = COMMAND_RE.fullmatch(body.strip())
195
+ if match is None:
196
+ continue
197
+ fresh = object_value(
198
+ api.request(
199
+ "GET",
200
+ f"/projects/{expected.target_project_id}/merge_requests/{expected.merge_request}/notes/{note_id}",
201
+ ),
202
+ "command note",
203
+ )
204
+ if fresh.get("body") != body or fresh.get("created_at") != fresh.get("updated_at"):
205
+ continue
206
+ actor = integer(object_value(fresh.get("author"), "command author").get("id"), "author ID")
207
+ command = match.group(1) or "status"
208
+ if command in {"help", "status"}:
209
+ message = (
210
+ "Quality Graph uses the managed summary for current results. "
211
+ "Use `/qg ignore <target>` or `/qg remove-ignore <target>` "
212
+ "for reversible approvals."
213
+ )
214
+ _record(api, expected, ApprovalAction(note_id, actor, "ack", set(), message))
215
+ continue
216
+ if not _authorized(api, expected.target_project_id, actor, expected.graph):
217
+ _record(
218
+ api,
219
+ expected,
220
+ ApprovalAction(
221
+ note_id,
222
+ actor,
223
+ "ack",
224
+ set(),
225
+ "This command requires a configured Quality Graph administrator role.",
226
+ ),
227
+ )
228
+ continue
229
+ targets = _command_targets(command, match.group(2), available)
230
+ if not targets:
231
+ _record(
232
+ api,
233
+ expected,
234
+ ApprovalAction(
235
+ note_id,
236
+ actor,
237
+ "ack",
238
+ set(),
239
+ "No matching approvable targets exist in the current admitted results.",
240
+ ),
241
+ )
242
+ continue
243
+ remove = command.startswith("remove-")
244
+ operation = "remove" if remove else "add"
245
+ _record(
246
+ api,
247
+ expected,
248
+ ApprovalAction(
249
+ note_id,
250
+ actor,
251
+ operation,
252
+ targets,
253
+ f"Quality Graph recorded approval operation `{operation}` from user {actor}.",
254
+ ),
255
+ )
256
+ if remove:
257
+ approvals.difference_update(targets)
258
+ else:
259
+ approvals.update(targets)
260
+ return approvals
261
+
262
+
263
+ def _state(
264
+ graph: Graph, evidence: Mapping[str, NodeEvidence], results: Mapping[str, Result]
265
+ ) -> str:
266
+ bootstrap = evidence.get(BOOTSTRAP_KEY)
267
+ if bootstrap is None or bootstrap.status is ResultStatus.FAILED:
268
+ return "failed"
269
+ if any(
270
+ item.status in {ResultStatus.IN_PROGRESS, ResultStatus.WAITING}
271
+ for item in evidence.values()
272
+ ):
273
+ return "pending"
274
+ canceled = any(item.status is ResultStatus.CANCELLED for item in evidence.values())
275
+ for node in graph.nodes:
276
+ item = evidence[node.id]
277
+ if item.status is ResultStatus.CANCELLED:
278
+ continue
279
+ if canceled and item.status is ResultStatus.SKIPPED:
280
+ continue
281
+ effective = results.get(node.id)
282
+ if effective is None or (
283
+ node.policy.blocking
284
+ and effective.status not in {ResultStatus.PASSED, ResultStatus.SKIPPED}
285
+ ):
286
+ return "failed"
287
+ return "canceled" if canceled else "success"
288
+
289
+
290
+ def _summary(
291
+ expected: Expectation,
292
+ evidence: Mapping[str, NodeEvidence],
293
+ results: Mapping[str, Result],
294
+ state: str,
295
+ ) -> str:
296
+ digest = graph_digest(expected.declaration)
297
+ lines = [
298
+ SUMMARY_MARKER,
299
+ gate_marker(expected.project_id, expected.pipeline_id, expected.flow_id, digest),
300
+ *(
301
+ execution_marker(expected.project_id, expected.pipeline_id, item.job_id, digest)
302
+ for item in evidence.values()
303
+ if item.job_id is not None
304
+ ),
305
+ "## Quality Graph",
306
+ "",
307
+ f"Pipeline **{expected.pipeline_id}**: **{state}**",
308
+ "",
309
+ "| Check | Execution | Effective result |",
310
+ "| --- | --- | --- |",
311
+ ]
312
+ details: list[str] = []
313
+ bootstrap = evidence.get(BOOTSTRAP_KEY)
314
+ if bootstrap is not None and bootstrap.reason:
315
+ details.extend(("", f"**Publisher admission:** {html.escape(bootstrap.reason)}"))
316
+ for node in expected.graph.nodes:
317
+ item = evidence[node.id]
318
+ result = results.get(node.id)
319
+ label = html.escape(node.title).replace("|", "\\|")
320
+ effective = result.status.value if result is not None else item.status.value
321
+ lines.append(f"| {label} | {item.native_status or item.status.value} | {effective} |")
322
+ if item.reason:
323
+ details.extend(("", f"**{label}:** {html.escape(item.reason)}"))
324
+ if result is not None:
325
+ for finding in result.findings[:100]:
326
+ details.extend(("", f"- `{finding.id}`: {html.escape(finding.message)}"))
327
+ if item.job_url:
328
+ details.extend(("", f"[Job logs: {label}]({item.job_url})"))
329
+ lines.extend(details)
330
+ lines.extend(("", "Use new `/qg` comments to approve or revoke findings, files and nodes."))
331
+ return "\n".join(lines)[:900_000]
332
+
333
+
334
+ def _still_current(api: HttpGitLab, expected: Expectation) -> bool:
335
+ mr = object_value(
336
+ api.request(
337
+ "GET", f"/projects/{expected.target_project_id}/merge_requests/{expected.merge_request}"
338
+ ),
339
+ "merge request",
340
+ )
341
+ head = mr.get("head_pipeline")
342
+ return (
343
+ mr.get("state") == "opened"
344
+ and mr.get("sha") == expected.head_sha
345
+ and isinstance(head, dict)
346
+ and head.get("id") == expected.pipeline_id
347
+ )
348
+
349
+
350
+ def _status_identity(value: Mapping[str, JsonValue], expected: Expectation, bot: int) -> bool:
351
+ if value.get("name") != STATUS_NAME:
352
+ return False
353
+ if (
354
+ integer(value.get("pipeline_id"), "status pipeline") != expected.pipeline_id
355
+ or value.get("sha") != expected.head_sha
356
+ ):
357
+ return False
358
+ author = object_value(value.get("author"), "status author")
359
+ if integer(author.get("id"), "status author ID") != bot:
360
+ message = "The Quality Graph status is owned by another GitLab actor"
361
+ raise ValueError(message)
362
+ return True
363
+
364
+
365
+ def _status(api: HttpGitLab, expected: Expectation, state: str, bot: int) -> bool:
366
+ path = (
367
+ f"/projects/{expected.project_id}/repository/commits/{expected.head_sha}/statuses"
368
+ f"?pipeline_id={expected.pipeline_id}"
369
+ )
370
+ matches = [value for value in api.pages(path) if _status_identity(value, expected, bot)]
371
+ if len(matches) > 1:
372
+ message = "GitLab returned ambiguous current Quality Graph statuses"
373
+ raise ValueError(message)
374
+ if matches and matches[0].get("status") == state:
375
+ return False
376
+ created = object_value(
377
+ api.request(
378
+ "POST",
379
+ f"/projects/{expected.project_id}/statuses/{expected.head_sha}",
380
+ {
381
+ "state": state,
382
+ "name": STATUS_NAME,
383
+ "pipeline_id": expected.pipeline_id,
384
+ "description": "Quality Graph admitted result policy",
385
+ },
386
+ ),
387
+ "created status",
388
+ )
389
+ if not _status_identity(created, expected, bot) or created.get("status") != state:
390
+ message = "GitLab did not confirm the requested pipeline status"
391
+ raise ValueError(message)
392
+ return True
393
+
394
+
395
+ def _upsert(
396
+ api: HttpGitLab,
397
+ expected: Expectation,
398
+ body: str,
399
+ notes: tuple[dict[str, JsonValue], ...],
400
+ bot: int,
401
+ ) -> bool:
402
+ managed = [
403
+ note
404
+ for note in notes
405
+ if _owned(note, bot)
406
+ and isinstance(note.get("body"), str)
407
+ and SUMMARY_MARKER in str(note["body"])
408
+ ]
409
+ if len(managed) > 1:
410
+ message = "GitLab has ambiguous publisher-owned summary notes"
411
+ raise ValueError(message)
412
+ endpoint = (
413
+ f"/projects/{expected.target_project_id}/merge_requests/{expected.merge_request}/notes"
414
+ )
415
+ if managed:
416
+ if managed[0].get("body") == body:
417
+ return False
418
+ api.request("PUT", f"{endpoint}/{integer(managed[0].get('id'), 'note ID')}", {"body": body})
419
+ else:
420
+ api.request("POST", endpoint, {"body": body})
421
+ return True
422
+
423
+
424
+ def _labels(
425
+ api: HttpGitLab, expected: Expectation, results: Mapping[str, Result], state: str
426
+ ) -> None:
427
+ selected: dict[str, tuple[LabelSpec, bool]] = {}
428
+ if expected.graph.labels.enabled and expected.graph.labels.failing is not None:
429
+ spec = expected.graph.labels.failing
430
+ selected[spec.name] = (spec, state == "failed")
431
+ for node in expected.graph.nodes:
432
+ if isinstance(node.failing_label, LabelSpec):
433
+ result = results.get(node.id)
434
+ selected[node.failing_label.name] = (
435
+ node.failing_label,
436
+ result is not None and result.status is ResultStatus.FAILED,
437
+ )
438
+ if not selected:
439
+ return
440
+ project = expected.target_project_id
441
+ existing = {
442
+ label.get("name")
443
+ for label in api.pages(f"/projects/{project}/labels")
444
+ if isinstance(label.get("name"), str)
445
+ }
446
+ for name, (spec, _enabled) in selected.items():
447
+ if name not in existing:
448
+ api.request(
449
+ "POST",
450
+ f"/projects/{project}/labels",
451
+ {"name": name, "color": f"#{spec.color}", "description": spec.description},
452
+ )
453
+ mr = object_value(
454
+ api.request("GET", f"/projects/{project}/merge_requests/{expected.merge_request}"),
455
+ "merge request",
456
+ )
457
+ current = mr.get("labels", [])
458
+ if not isinstance(current, list):
459
+ message = "GitLab labels must be an array"
460
+ raise TypeError(message)
461
+ add = [name for name, (_spec, enabled) in selected.items() if enabled and name not in current]
462
+ remove = [
463
+ name for name, (_spec, enabled) in selected.items() if not enabled and name in current
464
+ ]
465
+ if add or remove:
466
+ api.request(
467
+ "PUT",
468
+ f"/projects/{project}/merge_requests/{expected.merge_request}",
469
+ {"add_labels": ",".join(add), "remove_labels": ",".join(remove)},
470
+ )
471
+
472
+
473
+ def expectation(api: HttpGitLab, project: int, mr_id: int) -> Expectation | None:
474
+ """Resolve governance from the target branch and execution from current MR metadata."""
475
+ mr = object_value(
476
+ api.request("GET", f"/projects/{project}/merge_requests/{mr_id}"), "merge request"
477
+ )
478
+ head = mr.get("head_pipeline")
479
+ if mr.get("state") != "opened" or not isinstance(head, dict):
480
+ return None
481
+ execution_project = integer(head.get("project_id", project), "pipeline project")
482
+ pipeline_id = integer(head.get("id"), "pipeline ID")
483
+ pipeline = object_value(
484
+ api.request("GET", f"/projects/{execution_project}/pipelines/{pipeline_id}"), "MR pipeline"
485
+ )
486
+ if pipeline.get("source") != "merge_request_event":
487
+ return None
488
+ if (
489
+ pipeline.get("sha") != mr.get("sha")
490
+ or pipeline.get("project_id") != execution_project
491
+ or pipeline.get("id") != pipeline_id
492
+ ):
493
+ message = "GitLab MR pipeline metadata is stale or mismatched"
494
+ raise ValueError(message)
495
+ branch = urllib.parse.quote(string(mr.get("target_branch"), "target branch"), safe="")
496
+ target = object_value(
497
+ api.request("GET", f"/projects/{project}/repository/branches/{branch}"), "target branch"
498
+ )
499
+ if target.get("protected") is not True:
500
+ message = "GitLab publication requires a protected MR target branch"
501
+ raise ValueError(message)
502
+ target_sha = string(object_value(target.get("commit"), "target commit").get("id"), "target SHA")
503
+ source = api.download(f"/projects/{project}/repository/files/qg.yaml/raw?ref={target_sha}")
504
+ graph = Graph.from_yaml(source.decode())
505
+ if configuration(graph)["server-url"] != api.server_url:
506
+ message = "GitLab declaration targets another server instance"
507
+ raise ValueError(message)
508
+ if configuration(graph)["default-branch"] != mr.get("target_branch"):
509
+ return None
510
+ for flow_id, event, projected in execution_graphs(graph):
511
+ if event == "pull-request" and publishes_mr(graph, flow_id):
512
+ return Expectation(
513
+ execution_project,
514
+ project,
515
+ mr_id,
516
+ pipeline_id,
517
+ string(mr.get("sha"), "MR SHA"),
518
+ flow_id,
519
+ graph,
520
+ projected,
521
+ )
522
+ return None
523
+
524
+
525
+ def publish_merge_request(api: HttpGitLab, project: int, mr_id: int) -> Publication | None:
526
+ """Publish one current MR snapshot after authenticating all evidence and commands."""
527
+ expected = expectation(api, project, mr_id)
528
+ if expected is None:
529
+ return None
530
+ bot = integer(
531
+ object_value(api.request("GET", "/user"), "publisher user").get("id"), "publisher user ID"
532
+ )
533
+ if configuration(expected.declaration).get("publisher-user-id") != bot:
534
+ message = "GitLab publisher identity does not match trusted configuration"
535
+ raise ValueError(message)
536
+ notes = _notes(api, project, mr_id)
537
+ evidence = admit(api, expected)
538
+ if not _still_current(api, expected):
539
+ return None
540
+ approvals = _commands(api, expected, evidence, bot, notes)
541
+ admitted = {key: item.result for key, item in evidence.items() if item.result is not None}
542
+ effective = effective_graph(expected.graph, admitted, approvals)
543
+ state = _state(expected.graph, evidence, effective.results)
544
+ if not _still_current(api, expected):
545
+ return None
546
+ changed = _status(api, expected, state, bot)
547
+ if not _still_current(api, expected):
548
+ return None
549
+ changed = (
550
+ _upsert(api, expected, _summary(expected, evidence, effective.results, state), notes, bot)
551
+ or changed
552
+ )
553
+ _labels(api, expected, effective.results, state)
554
+ return Publication(project, mr_id, expected.pipeline_id, state, changed)
555
+
556
+
557
+ def publish_from_environment() -> int:
558
+ """Reconcile only projects explicitly allowed by trusted publisher configuration."""
559
+ projects = json.loads(os.environ["QG_GITLAB_PROJECTS"])
560
+ if not isinstance(projects, list) or not projects:
561
+ message = "QG_GITLAB_PROJECTS must be a nonempty array of project IDs"
562
+ raise ValueError(message)
563
+ failures = 0
564
+ server = os.environ.get("QG_GITLAB_SERVER_URL", os.environ.get("CI_SERVER_URL", ""))
565
+ endpoint = os.environ.get("QG_GITLAB_API_URL")
566
+ if endpoint is None and "QG_GITLAB_SERVER_URL" not in os.environ:
567
+ endpoint = os.environ.get("CI_API_V4_URL")
568
+ with HttpGitLab(
569
+ server,
570
+ os.environ["QG_GITLAB_TOKEN"],
571
+ api_url=endpoint,
572
+ ) as api:
573
+ for project in projects:
574
+ project_id = integer(project, "allowed project ID")
575
+ for mr in api.pages(f"/projects/{project_id}/merge_requests?state=opened"):
576
+ try:
577
+ outcome = publish_merge_request(
578
+ api, project_id, integer(mr.get("iid"), "MR IID")
579
+ )
580
+ if outcome is not None:
581
+ sys.stdout.write(
582
+ f"project={outcome.project} mr={outcome.merge_request} "
583
+ f"pipeline={outcome.pipeline} state={outcome.state}\n"
584
+ )
585
+ except (GitLabError, OSError, TypeError, ValueError) as error:
586
+ failures += 1
587
+ sys.stderr.write(f"GitLab publication failed: {error}\n")
588
+ return int(failures != 0)
qg_gitlab/py.typed ADDED
File without changes