quality-graph-gitlab 0.2.0__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.
@@ -0,0 +1,22 @@
1
+ .venv/
2
+ .env
3
+ __pycache__/
4
+ *.py[cod]
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+ .coverage
9
+ coverage.json
10
+ coverage.xml
11
+ htmlcov/
12
+ coverage-report/
13
+ dist/
14
+ build/
15
+ *.egg-info/
16
+ .mutmut-cache/
17
+ mutants/
18
+ reports/
19
+ site/
20
+ .tools/
21
+ node_modules/
22
+ .DS_Store
@@ -0,0 +1,31 @@
1
+ Metadata-Version: 2.4
2
+ Name: quality-graph-gitlab
3
+ Version: 0.2.0
4
+ Summary: GitLab provider and CI runtime for Quality Graph
5
+ Project-URL: Homepage, https://quality-graph.xyz/
6
+ Project-URL: Documentation, https://quality-graph.xyz/
7
+ License-Expression: MIT
8
+ Requires-Python: >=3.12
9
+ Requires-Dist: anyio>=4.0
10
+ Requires-Dist: httpx>=0.28.1
11
+ Requires-Dist: pyyaml>=6.0.2
12
+ Requires-Dist: quality-graph-core==0.2.0
13
+ Description-Content-Type: text/markdown
14
+
15
+ # Quality Graph GitLab
16
+
17
+ The independently installed GitLab provider and CI runtime for Quality Graph.
18
+ Install the CLI and this provider at the same exact release version:
19
+
20
+ ```sh
21
+ uv tool install quality-graph-cli==X.Y.Z --with quality-graph-gitlab==X.Y.Z
22
+ qg init --provider gitlab
23
+ qg generate
24
+ qg validate
25
+ ```
26
+
27
+ Consumer checks execute as native GitLab jobs. A separate trusted GitLab project
28
+ publishes admitted results and handles authorized merge-request commands.
29
+
30
+ GitLab provenance identifies the instance, project, pipeline and exact job;
31
+ GitHub workflow attempts are not used. GitHub is not a runtime dependency.
@@ -0,0 +1,17 @@
1
+ # Quality Graph GitLab
2
+
3
+ The independently installed GitLab provider and CI runtime for Quality Graph.
4
+ Install the CLI and this provider at the same exact release version:
5
+
6
+ ```sh
7
+ uv tool install quality-graph-cli==X.Y.Z --with quality-graph-gitlab==X.Y.Z
8
+ qg init --provider gitlab
9
+ qg generate
10
+ qg validate
11
+ ```
12
+
13
+ Consumer checks execute as native GitLab jobs. A separate trusted GitLab project
14
+ publishes admitted results and handles authorized merge-request commands.
15
+
16
+ GitLab provenance identifies the instance, project, pipeline and exact job;
17
+ GitHub workflow attempts are not used. GitHub is not a runtime dependency.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["hatchling==1.27.0"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "quality-graph-gitlab"
7
+ version = "0.2.0"
8
+ description = "GitLab provider and CI runtime for Quality Graph"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "MIT"
12
+ dependencies = [
13
+ "anyio>=4.0",
14
+ "httpx>=0.28.1",
15
+ "pyyaml>=6.0.2",
16
+ "quality-graph-core==0.2.0",
17
+ ]
18
+
19
+ [project.urls]
20
+ Homepage = "https://quality-graph.xyz/"
21
+ Documentation = "https://quality-graph.xyz/"
22
+
23
+ [project.entry-points."qg.providers"]
24
+ gitlab = "qg_gitlab:provider"
25
+
26
+ [project.scripts]
27
+ qg-gitlab = "qg_gitlab.runtime:main"
28
+
29
+ [tool.uv.sources]
30
+ quality-graph-core = { workspace = true }
31
+
32
+ [tool.hatch.build.targets.wheel]
33
+ packages = ["src/qg_gitlab"]
@@ -0,0 +1,25 @@
1
+ """Expose the independently installed GitLab provider."""
2
+
3
+ from qg_gitlab.compiler import compile_graph, starter
4
+ from quality_graph_core.graph import Graph
5
+ from quality_graph_core.provider import GeneratedProject
6
+
7
+
8
+ class GitLabProvider:
9
+ """Own GitLab compilation and provider-native initialization."""
10
+
11
+ name = "gitlab"
12
+
13
+ def generate(self, graph: Graph) -> GeneratedProject:
14
+ """Return the complete deterministic GitLab project."""
15
+ return compile_graph(graph)
16
+
17
+ def starter_configuration(self, default_branch: str, preset: str) -> str:
18
+ """Return a GitLab starter for either supported repository preset."""
19
+ if preset not in {"oss", "internal"}:
20
+ message = f"unsupported GitLab preset: {preset}"
21
+ raise ValueError(message)
22
+ return starter(default_branch)
23
+
24
+
25
+ provider = GitLabProvider()
@@ -0,0 +1,231 @@
1
+ """Admit results only from authoritative current GitLab job executions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import io
6
+ import stat
7
+ import zipfile
8
+ from dataclasses import dataclass, replace
9
+ from pathlib import PurePosixPath
10
+ from typing import TYPE_CHECKING
11
+
12
+ from qg_gitlab.api import GitLabError, HttpGitLab, integer, object_value
13
+ from qg_gitlab.compiler import admission_job_name, graph_digest, job_name
14
+ from quality_graph_core.result import FailureKind, GitLabProvenance, Result, ResultStatus
15
+
16
+ if TYPE_CHECKING:
17
+ from collections.abc import Mapping
18
+
19
+ from quality_graph_core.graph import Graph, Node
20
+ from quality_graph_core.result import JsonValue
21
+
22
+ MAX_ARCHIVE_FILES = 100
23
+ BOOTSTRAP_KEY = "__admission__"
24
+ MAX_EXPANDED_BYTES = 50 * 1024 * 1024
25
+ ACTIVE_STATES = {"created", "pending", "preparing", "running", "scheduled", "waiting_for_resource"}
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class Expectation:
30
+ """Carry API-verified MR and pipeline identities plus trusted configuration."""
31
+
32
+ project_id: int
33
+ target_project_id: int
34
+ merge_request: int
35
+ pipeline_id: int
36
+ head_sha: str
37
+ flow_id: str
38
+ declaration: Graph
39
+ graph: Graph
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class NodeEvidence:
44
+ """Keep native execution state separate from admitted portable results."""
45
+
46
+ node_id: str
47
+ status: ResultStatus
48
+ job_id: int | None = None
49
+ job_url: str = ""
50
+ result: Result | None = None
51
+ reason: str = ""
52
+ native_status: str = ""
53
+
54
+
55
+ def archive_result(payload: bytes, path: str) -> Result:
56
+ """Validate the entire archive before parsing its exact declared result."""
57
+ with zipfile.ZipFile(io.BytesIO(payload)) as archive:
58
+ entries = archive.infolist()
59
+ if len(entries) > MAX_ARCHIVE_FILES:
60
+ message = "GitLab artifact has too many archive entries"
61
+ raise ValueError(message)
62
+ total = 0
63
+ candidates: list[bytes] = []
64
+ for entry in entries:
65
+ name = PurePosixPath(entry.filename)
66
+ mode = entry.external_attr >> 16
67
+ if (
68
+ name.is_absolute()
69
+ or ".." in name.parts
70
+ or "\\" in entry.filename
71
+ or stat.S_ISLNK(mode)
72
+ ):
73
+ message = "GitLab artifact contains an unsafe archive entry"
74
+ raise ValueError(message)
75
+ total += entry.file_size
76
+ if total > MAX_EXPANDED_BYTES:
77
+ message = "GitLab artifact exceeds the expanded size limit"
78
+ raise ValueError(message)
79
+ if entry.filename == path:
80
+ candidates.append(archive.read(entry))
81
+ if not candidates:
82
+ message = "GitLab job artifact does not contain the declared result"
83
+ raise ValueError(message)
84
+ if any(value != candidates[0] for value in candidates[1:]):
85
+ message = "GitLab artifact contains conflicting duplicate results"
86
+ raise ValueError(message)
87
+ return Result.from_json(candidates[0])
88
+
89
+
90
+ def admit(api: HttpGitLab, expectation: Expectation) -> dict[str, NodeEvidence]:
91
+ """Resolve the current execution of each job before downloading any result."""
92
+ endpoint = f"/projects/{expectation.project_id}/pipelines/{expectation.pipeline_id}/jobs"
93
+ jobs = tuple(api.pages(f"{endpoint}?include_retried=false"))
94
+ output: dict[str, NodeEvidence] = {BOOTSTRAP_KEY: _bootstrap(expectation, jobs)}
95
+ for node in expectation.graph.nodes:
96
+ matches = tuple(
97
+ job for job in jobs if job.get("name") == job_name(expectation.flow_id, node.id)
98
+ )
99
+ if len(matches) != 1:
100
+ output[node.id] = NodeEvidence(
101
+ node.id, ResultStatus.FAILED, reason="Missing or ambiguous current job evidence"
102
+ )
103
+ continue
104
+ try:
105
+ output[node.id] = _admit_job(api, expectation, node, matches[0])
106
+ except (GitLabError, OSError, TypeError, ValueError, zipfile.BadZipFile) as error:
107
+ identity = matches[0].get("id")
108
+ url = matches[0].get("web_url")
109
+ output[node.id] = NodeEvidence(
110
+ node.id,
111
+ ResultStatus.FAILED,
112
+ identity
113
+ if isinstance(identity, int) and not isinstance(identity, bool) and identity > 0
114
+ else None,
115
+ url if isinstance(url, str) else "",
116
+ reason=str(error),
117
+ )
118
+ status = matches[0].get("status")
119
+ output[node.id] = replace(
120
+ output[node.id], native_status=status if isinstance(status, str) else "unknown"
121
+ )
122
+ return output
123
+
124
+
125
+ def _bootstrap(expected: Expectation, jobs: tuple[dict[str, JsonValue], ...]) -> NodeEvidence:
126
+ matches = [job for job in jobs if job.get("name") == admission_job_name(expected.flow_id)]
127
+ if len(matches) != 1:
128
+ return NodeEvidence(
129
+ BOOTSTRAP_KEY,
130
+ ResultStatus.FAILED,
131
+ reason="Missing or ambiguous publisher admission job",
132
+ )
133
+ job = matches[0]
134
+ identity: int | None = None
135
+ try:
136
+ identity = integer(job.get("id"), "admission job ID")
137
+ pipeline = object_value(job.get("pipeline"), "admission pipeline")
138
+ valid = (
139
+ integer(pipeline.get("id"), "admission pipeline ID") == expected.pipeline_id
140
+ and integer(pipeline.get("project_id"), "admission project") == expected.project_id
141
+ and pipeline.get("sha") == expected.head_sha
142
+ )
143
+ except (TypeError, ValueError):
144
+ valid = False
145
+ identity = None
146
+ status = job.get("status")
147
+ state = ResultStatus.FAILED
148
+ if valid and isinstance(status, str):
149
+ if status in ACTIVE_STATES:
150
+ state = ResultStatus.IN_PROGRESS
151
+ elif status == "success":
152
+ state = ResultStatus.PASSED
153
+ elif status in {"canceled", "canceling"}:
154
+ state = ResultStatus.CANCELLED
155
+ url = job.get("web_url")
156
+ return NodeEvidence(
157
+ BOOTSTRAP_KEY,
158
+ state,
159
+ identity,
160
+ url if isinstance(url, str) else "",
161
+ reason=""
162
+ if state is ResultStatus.PASSED
163
+ else "Publisher admission has not completed successfully",
164
+ native_status=status if isinstance(status, str) else "unknown",
165
+ )
166
+
167
+
168
+ def _admit_job(
169
+ api: HttpGitLab, expected: Expectation, node: Node, job: Mapping[str, JsonValue]
170
+ ) -> NodeEvidence:
171
+ identity = integer(job.get("id"), "job ID")
172
+ pipeline = object_value(job.get("pipeline"), "job pipeline")
173
+ if (
174
+ integer(pipeline.get("id"), "job pipeline ID") != expected.pipeline_id
175
+ or integer(pipeline.get("project_id"), "job pipeline project") != expected.project_id
176
+ or pipeline.get("sha") != expected.head_sha
177
+ ):
178
+ message = "GitLab job belongs to another pipeline, project or commit"
179
+ raise ValueError(message)
180
+ url = job.get("web_url")
181
+ job_url = url if isinstance(url, str) else ""
182
+ status = job.get("status")
183
+ if isinstance(status, str) and status in ACTIVE_STATES:
184
+ return NodeEvidence(node.id, ResultStatus.IN_PROGRESS, identity, job_url)
185
+ if status in {"canceled", "canceling"}:
186
+ return NodeEvidence(
187
+ node.id,
188
+ ResultStatus.CANCELLED,
189
+ identity,
190
+ job_url,
191
+ reason="GitLab canceled this execution",
192
+ )
193
+ if status == "skipped":
194
+ return NodeEvidence(
195
+ node.id, ResultStatus.SKIPPED, identity, job_url, reason="GitLab skipped this execution"
196
+ )
197
+ if status not in {"success", "failed"}:
198
+ message = "GitLab job is not a recognized terminal execution"
199
+ raise ValueError(message)
200
+ path = f".qg/results/{expected.flow_id}/{node.id}.json"
201
+ result = archive_result(
202
+ api.download(f"/projects/{expected.project_id}/jobs/{identity}/artifacts"), path
203
+ )
204
+ provenance = GitLabProvenance(
205
+ api.server_url,
206
+ expected.project_id,
207
+ expected.head_sha,
208
+ expected.pipeline_id,
209
+ identity,
210
+ graph_digest(expected.declaration),
211
+ expected.target_project_id,
212
+ expected.merge_request,
213
+ expected.flow_id,
214
+ node.operation_id or node.id,
215
+ )
216
+ if result.provenance != provenance or result.node_id != node.id or result.title != node.title:
217
+ message = "GitLab result provenance does not match the current declared job"
218
+ raise ValueError(message)
219
+ if status == "failed" and (
220
+ result.failure_kind is not FailureKind.QUALITY or job.get("allow_failure") is not True
221
+ ):
222
+ if result.failure_kind in {None, FailureKind.QUALITY}:
223
+ message = "Passed GitLab result contradicts failed native execution"
224
+ raise ValueError(message)
225
+ return NodeEvidence(
226
+ node.id, ResultStatus.FAILED, identity, job_url, result, "Native execution failed"
227
+ )
228
+ if status == "success" and result.status not in {ResultStatus.PASSED, ResultStatus.SKIPPED}:
229
+ message = "GitLab result contradicts successful native execution"
230
+ raise ValueError(message)
231
+ return NodeEvidence(node.id, result.status, identity, job_url, result)
@@ -0,0 +1,223 @@
1
+ """Communicate with GitLab through a bounded, instance-scoped HTTP interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ipaddress
6
+ import json
7
+ import os
8
+ import time
9
+ import urllib.parse
10
+ from http import HTTPStatus
11
+ from typing import TYPE_CHECKING, Self, cast
12
+
13
+ import httpx
14
+
15
+ if TYPE_CHECKING:
16
+ from collections.abc import Iterator, Mapping
17
+ from types import TracebackType
18
+
19
+ from quality_graph_core.result import JsonValue
20
+
21
+ PAGE_SIZE = 100
22
+ MAX_PAGES = 1_000
23
+ MAX_RESPONSE_BYTES = 50 * 1024 * 1024
24
+ RETRY_STATUSES = {409, 429, 502, 503, 504}
25
+
26
+
27
+ def object_value(value: JsonValue, context: str) -> dict[str, JsonValue]:
28
+ """Require a JSON object at an external interface."""
29
+ if not isinstance(value, dict):
30
+ message = f"{context} must be an object"
31
+ raise TypeError(message)
32
+ return value
33
+
34
+
35
+ def integer(value: JsonValue, context: str) -> int:
36
+ """Require a positive integer identity without coercion."""
37
+ if not isinstance(value, int) or isinstance(value, bool):
38
+ message = f"{context} must be an integer"
39
+ raise TypeError(message)
40
+ if value < 1:
41
+ message = f"{context} must be positive"
42
+ raise ValueError(message)
43
+ return value
44
+
45
+
46
+ def string(value: JsonValue, context: str) -> str:
47
+ """Require a nonempty string at an external interface."""
48
+ if not isinstance(value, str):
49
+ message = f"{context} must be a string"
50
+ raise TypeError(message)
51
+ if not value:
52
+ message = f"{context} must not be empty"
53
+ raise ValueError(message)
54
+ return value
55
+
56
+
57
+ def server_url(value: str) -> str:
58
+ """Validate an explicitly configured instance or API URL."""
59
+ parsed = urllib.parse.urlsplit(value)
60
+ if (
61
+ parsed.scheme not in {"http", "https"}
62
+ or not parsed.hostname
63
+ or parsed.username is not None
64
+ or parsed.password is not None
65
+ or parsed.query
66
+ or parsed.fragment
67
+ ):
68
+ message = "GitLab URL must be an absolute HTTP(S) URL without credentials"
69
+ raise ValueError(message)
70
+ return value.rstrip("/")
71
+
72
+
73
+ class GitLabError(RuntimeError):
74
+ """Expose a bounded HTTP failure without credentials or response bodies."""
75
+
76
+ def __init__(self, status: int, path: str) -> None:
77
+ """Capture the status and path safe for user-facing diagnostics."""
78
+ self.status = status
79
+ super().__init__(f"GitLab API returned HTTP {status} for {path.split('?', 1)[0]}")
80
+
81
+
82
+ class HttpGitLab:
83
+ """Own transport, pagination and bounded artifact downloads for one instance."""
84
+
85
+ def __init__(
86
+ self,
87
+ url: str,
88
+ token: str,
89
+ *,
90
+ api_url: str | None = None,
91
+ job_token: bool = False,
92
+ transport: httpx.BaseTransport | None = None,
93
+ ) -> None:
94
+ """Construct an explicitly scoped client with no ambient credentials."""
95
+ self.transport = transport
96
+ self.server_url = server_url(url)
97
+ self.api_url = server_url(api_url or f"{self.server_url}/api/v4")
98
+ parsed = urllib.parse.urlsplit(self.api_url)
99
+ host = parsed.hostname or ""
100
+ try:
101
+ loopback = ipaddress.ip_address(host).is_loopback
102
+ except ValueError:
103
+ loopback = host == "localhost"
104
+ if (
105
+ parsed.scheme == "http"
106
+ and not loopback
107
+ and host != os.environ.get("QG_GITLAB_INSECURE_HTTP_HOST")
108
+ ):
109
+ message = (
110
+ "GitLab API requires HTTPS outside loopback; use TLS or explicitly trust a lab host"
111
+ )
112
+ raise ValueError(message)
113
+ self.client = httpx.Client(
114
+ base_url=self.api_url,
115
+ headers={"JOB-TOKEN" if job_token else "PRIVATE-TOKEN": token},
116
+ timeout=30,
117
+ follow_redirects=False,
118
+ transport=transport,
119
+ )
120
+
121
+ def __enter__(self) -> Self:
122
+ """Return the transport owned by this context."""
123
+ return self
124
+
125
+ def __exit__(
126
+ self,
127
+ _kind: type[BaseException] | None,
128
+ _error: BaseException | None,
129
+ _traceback: TracebackType | None,
130
+ ) -> None:
131
+ """Close connection pools on every exit."""
132
+ self.client.close()
133
+
134
+ def request(
135
+ self,
136
+ method: str,
137
+ path: str,
138
+ data: Mapping[str, JsonValue] | None = None,
139
+ ) -> JsonValue:
140
+ """Make one bounded JSON request, retrying safe transient reads only."""
141
+ self._path(path)
142
+ attempts = 3 if method == "GET" else 1
143
+ attempt = 0
144
+ while True:
145
+ with self.client.stream(method, path, json=data) as response:
146
+ if response.status_code in RETRY_STATUSES and attempt + 1 < attempts:
147
+ time.sleep(min(2**attempt, 4))
148
+ attempt += 1
149
+ continue
150
+ if not response.is_success:
151
+ raise GitLabError(response.status_code, path)
152
+ payload = self._body(response)
153
+ return (
154
+ None
155
+ if response.status_code == HTTPStatus.NO_CONTENT
156
+ else cast("JsonValue", json.loads(payload))
157
+ )
158
+
159
+ def pages(self, path: str) -> Iterator[dict[str, JsonValue]]:
160
+ """Read every page without following server-supplied credential targets."""
161
+ separator = "&" if "?" in path else "?"
162
+ for page in range(1, MAX_PAGES + 1):
163
+ value = self.request("GET", f"{path}{separator}per_page={PAGE_SIZE}&page={page}")
164
+ if not isinstance(value, list):
165
+ message = "GitLab list response must be an array"
166
+ raise TypeError(message)
167
+ for item in value:
168
+ yield object_value(item, "GitLab list item")
169
+ if len(value) < PAGE_SIZE:
170
+ return
171
+ message = "GitLab pagination exceeded its page limit"
172
+ raise ValueError(message)
173
+
174
+ def download(self, path: str) -> bytes:
175
+ """Download an artifact without forwarding credentials through redirects."""
176
+ self._path(path)
177
+ with self.client.stream("GET", path) as response:
178
+ if response.is_success:
179
+ return self._body(response)
180
+ if not response.is_redirect or "location" not in response.headers:
181
+ raise GitLabError(response.status_code, path)
182
+ target = urllib.parse.urljoin(str(response.url), response.headers["location"])
183
+ with httpx.Client(timeout=30, follow_redirects=False, transport=self.transport) as external:
184
+ for _attempt in range(3):
185
+ normalized = server_url(target.split("?", 1)[0])
186
+ if self.api_url.startswith("https:") and not normalized.startswith("https:"):
187
+ message = "GitLab artifact redirect would downgrade transport security"
188
+ raise ValueError(message)
189
+ with external.stream("GET", target) as response:
190
+ if response.is_success:
191
+ return self._body(response)
192
+ if not response.is_redirect or "location" not in response.headers:
193
+ raise GitLabError(response.status_code, path)
194
+ target = urllib.parse.urljoin(str(response.url), response.headers["location"])
195
+ message = "GitLab artifact redirect limit exceeded"
196
+ raise ValueError(message)
197
+
198
+ @staticmethod
199
+ def _body(response: httpx.Response) -> bytes:
200
+ chunks: list[bytes] = []
201
+ size = 0
202
+ for chunk in response.iter_bytes():
203
+ size += len(chunk)
204
+ if size > MAX_RESPONSE_BYTES:
205
+ message = "GitLab response exceeds the size limit"
206
+ raise ValueError(message)
207
+ chunks.append(chunk)
208
+ return b"".join(chunks)
209
+
210
+ @staticmethod
211
+ def project_path(project: int | str) -> str:
212
+ """Encode a project ID or complete nested namespace as one path segment."""
213
+ return f"/projects/{urllib.parse.quote(str(project), safe='')}"
214
+
215
+ @staticmethod
216
+ def _path(path: str) -> None:
217
+ if (
218
+ not path.startswith("/")
219
+ or path.startswith("//")
220
+ or ".." in urllib.parse.unquote(path.split("?", 1)[0]).split("/")
221
+ ):
222
+ message = "GitLab request path must remain within the configured API"
223
+ raise ValueError(message)