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/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """GitHub provider for Quality Graph."""
2
+
3
+ from qg_github.provider import provider
4
+
5
+ __all__ = ["provider"]
@@ -0,0 +1,93 @@
1
+ """Render safe bounded GitHub workflow annotations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from dataclasses import dataclass, replace
7
+ from typing import TYPE_CHECKING
8
+
9
+ from quality_graph_core.result import Annotation, Severity
10
+
11
+ if TYPE_CHECKING:
12
+ from collections.abc import Iterable
13
+ from typing import TextIO
14
+
15
+ MAX_STEP_ANNOTATIONS = 10
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class AnnotationBatch:
20
+ """Carry rendered annotations and the number omitted by GitHub limits."""
21
+
22
+ annotations: tuple[Annotation, ...]
23
+ omitted: int
24
+
25
+
26
+ def grouped_annotations(annotations: Iterable[Annotation]) -> AnnotationBatch:
27
+ """Group duplicate locations and apply the GitHub step limit."""
28
+ grouped: dict[tuple[object, ...], list[Annotation]] = {}
29
+ source = tuple(annotations)
30
+ for annotation in source:
31
+ location = annotation.location
32
+ key = (
33
+ location.path,
34
+ location.start_line,
35
+ location.end_line,
36
+ location.start_column,
37
+ location.end_column,
38
+ annotation.level,
39
+ annotation.title,
40
+ )
41
+ grouped.setdefault(key, []).append(annotation)
42
+ result = tuple(_merge_annotations(items) for items in grouped.values())
43
+ selected = result[:MAX_STEP_ANNOTATIONS]
44
+ return AnnotationBatch(selected, len(result) - len(selected))
45
+
46
+
47
+ def _merge_annotations(annotations: list[Annotation]) -> Annotation:
48
+ first = annotations[0]
49
+ messages = "\n".join(dict.fromkeys(annotation.message for annotation in annotations))
50
+ return replace(first, message=messages)
51
+
52
+
53
+ def workflow_annotation_command(annotation: Annotation) -> str:
54
+ """Render one escaped GitHub workflow command."""
55
+ location = annotation.location
56
+ properties = {
57
+ "file": location.path,
58
+ "line": str(location.start_line),
59
+ "endLine": str(location.end_line),
60
+ }
61
+ if annotation.title is not None:
62
+ properties["title"] = annotation.title
63
+ if location.start_column is not None and location.end_column is not None:
64
+ properties["col"] = str(location.start_column)
65
+ properties["endColumn"] = str(location.end_column)
66
+ encoded = ",".join(f"{key}={escape_property(value)}" for key, value in properties.items())
67
+ command = "error" if annotation.level is Severity.ERROR else annotation.level.value
68
+ return f"::{command} {encoded}::{escape_data(annotation.message)}"
69
+
70
+
71
+ def publish_annotations(
72
+ annotations: Iterable[Annotation],
73
+ *,
74
+ stream: TextIO | None = None,
75
+ ) -> None:
76
+ """Publish grouped annotations and disclose omitted diagnostics."""
77
+ output = stream or sys.stderr
78
+ batch = grouped_annotations(annotations)
79
+ output.writelines(
80
+ f"{workflow_annotation_command(annotation)}\n" for annotation in batch.annotations
81
+ )
82
+ if batch.omitted:
83
+ output.write("::notice::Additional diagnostics are available in the Job Summary.\n")
84
+
85
+
86
+ def escape_property(value: str) -> str:
87
+ """Escape a workflow-command property."""
88
+ return escape_data(value).replace(":", "%3A").replace(",", "%2C")
89
+
90
+
91
+ def escape_data(value: str) -> str:
92
+ """Escape workflow-command data."""
93
+ return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
qg_github/approvals.py ADDED
@@ -0,0 +1,172 @@
1
+ """Persist authorized approval changes as immutable bot-owned comment records."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import json
7
+ import re
8
+ from dataclasses import dataclass
9
+ from typing import TYPE_CHECKING, cast
10
+
11
+ from qg_github.comments import DEFAULT_BOT_LOGIN
12
+ from qg_github.github import GitHubPort, paged
13
+ from quality_graph_core.policy import ApprovalTarget
14
+
15
+ if TYPE_CHECKING:
16
+ from collections.abc import Iterable
17
+
18
+ from quality_graph_core.result import JsonValue
19
+
20
+ LEDGER_RE = re.compile(r"<!-- quality-graph:approval:(?P<payload>[A-Za-z0-9_-]+) -->")
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class ApprovalRecord:
25
+ """Describe one authorized append-only approval change."""
26
+
27
+ add: bool
28
+ targets: tuple[ApprovalTarget, ...]
29
+ actor: str
30
+ source_comment_id: int
31
+
32
+ def __post_init__(self) -> None:
33
+ """Reject empty or duplicate record targets."""
34
+ if not self.targets or len(set(self.targets)) != len(self.targets):
35
+ message = "approval record targets must be non-empty and unique"
36
+ raise ValueError(message)
37
+ if not self.actor:
38
+ message = "approval record actor must not be empty"
39
+ raise ValueError(message)
40
+ if self.source_comment_id < 1:
41
+ message = "approval source comment id must be positive"
42
+ raise ValueError(message)
43
+
44
+ def to_json(self) -> str:
45
+ """Serialize a record canonically for its immutable marker."""
46
+ value: dict[str, JsonValue] = {
47
+ "version": 0,
48
+ "operation": "add" if self.add else "remove",
49
+ "targets": [target.key for target in self.targets],
50
+ "actor": self.actor,
51
+ "sourceCommentId": self.source_comment_id,
52
+ }
53
+ return json.dumps(value, sort_keys=True, separators=(",", ":"))
54
+
55
+ @classmethod
56
+ def from_json(cls, value: str) -> ApprovalRecord:
57
+ """Parse a record from untrusted marker JSON."""
58
+ data = _object(cast("JsonValue", json.loads(value)), "approval record")
59
+ if data.get("version") != 0:
60
+ message = "unsupported approval record version"
61
+ raise ValueError(message)
62
+ operation = _string(data.get("operation"), "approval operation")
63
+ if operation not in {"add", "remove"}:
64
+ message = f"unknown approval operation: {operation}"
65
+ raise ValueError(message)
66
+ targets = tuple(
67
+ ApprovalTarget.from_key(_string(item, "approval target"))
68
+ for item in _array(data.get("targets"), "approval targets")
69
+ )
70
+ return cls(
71
+ operation == "add",
72
+ targets,
73
+ _string(data.get("actor"), "approval actor"),
74
+ _integer(data.get("sourceCommentId"), "approval source comment id"),
75
+ )
76
+
77
+
78
+ def record_marker(record: ApprovalRecord) -> str:
79
+ """Encode one authorization record in a stable hidden marker."""
80
+ encoded = base64.urlsafe_b64encode(record.to_json().encode()).decode().rstrip("=")
81
+ return f"<!-- quality-graph:approval:{encoded} -->"
82
+
83
+
84
+ def decode_record(body: str) -> ApprovalRecord | None:
85
+ """Decode a canonical record marker from one bot comment."""
86
+ match = LEDGER_RE.search(body)
87
+ if match is None:
88
+ return None
89
+ encoded = match.group("payload")
90
+ try:
91
+ value = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)).decode()
92
+ return ApprovalRecord.from_json(value)
93
+ except (ValueError, TypeError, UnicodeDecodeError, json.JSONDecodeError):
94
+ return None
95
+
96
+
97
+ def approval_ledger(
98
+ port: GitHubPort,
99
+ number: int,
100
+ *,
101
+ bot_logins: Iterable[str] = (DEFAULT_BOT_LOGIN,),
102
+ ) -> frozenset[ApprovalTarget]:
103
+ """Replay trusted immutable authorization records in comment order."""
104
+ trusted = set(bot_logins)
105
+ approvals: set[ApprovalTarget] = set()
106
+ comments = sorted(
107
+ paged(port, f"/issues/{number}/comments"),
108
+ key=lambda item: _integer(item.get("id"), "approval comment id"),
109
+ )
110
+ for comment in comments:
111
+ author = comment.get("user")
112
+ login = author.get("login") if isinstance(author, dict) else None
113
+ created = comment.get("created_at")
114
+ updated = comment.get("updated_at")
115
+ body = comment.get("body")
116
+ if login not in trusted or created != updated or not isinstance(body, str):
117
+ continue
118
+ record = decode_record(body)
119
+ if record is None:
120
+ continue
121
+ if record.add:
122
+ approvals.update(record.targets)
123
+ else:
124
+ approvals.difference_update(record.targets)
125
+ return frozenset(approvals)
126
+
127
+
128
+ def append_approval_record(
129
+ port: GitHubPort,
130
+ number: int,
131
+ record: ApprovalRecord,
132
+ ) -> int:
133
+ """Create one transparent bot-owned immutable authorization record."""
134
+ action = "approved" if record.add else "removed approval for"
135
+ targets = ", ".join(f"`{target.key}`" for target in record.targets)
136
+ body = (
137
+ f"Quality Graph recorded that @{record.actor} {action} {targets}.\n\n"
138
+ f"{record_marker(record)}"
139
+ )
140
+ response = _object(
141
+ port.request("POST", f"/issues/{number}/comments", {"body": body}),
142
+ "approval comment",
143
+ )
144
+ return _integer(response.get("id"), "approval comment id")
145
+
146
+
147
+ def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
148
+ if not isinstance(value, dict):
149
+ message = f"{context} must be an object"
150
+ raise TypeError(message)
151
+ return value
152
+
153
+
154
+ def _array(value: JsonValue, context: str) -> list[JsonValue]:
155
+ if not isinstance(value, list):
156
+ message = f"{context} must be an array"
157
+ raise TypeError(message)
158
+ return value
159
+
160
+
161
+ def _string(value: JsonValue, context: str) -> str:
162
+ if not isinstance(value, str):
163
+ message = f"{context} must be a string"
164
+ raise TypeError(message)
165
+ return value
166
+
167
+
168
+ def _integer(value: JsonValue, context: str) -> int:
169
+ if not isinstance(value, int) or isinstance(value, bool):
170
+ message = f"{context} must be an integer"
171
+ raise TypeError(message)
172
+ return value
qg_github/artifacts.py ADDED
@@ -0,0 +1,216 @@
1
+ """Download and validate untrusted portable result artifacts."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import io
7
+ import re
8
+ import stat
9
+ import zipfile
10
+ from dataclasses import dataclass
11
+ from pathlib import PurePosixPath
12
+ from typing import TYPE_CHECKING
13
+
14
+ from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
15
+ from quality_graph_core.result import JsonValue, Result
16
+
17
+ if TYPE_CHECKING:
18
+ from collections.abc import Iterable
19
+
20
+ ARTIFACT_NAME_RE = re.compile(
21
+ r"^quality-result-(?P<node>[a-z][a-z0-9-]{0,62})-"
22
+ r"(?P<attempt>[1-9][0-9]*)$"
23
+ )
24
+ MAX_ARTIFACT_ARCHIVE_BYTES = 20 * 1024 * 1024
25
+ MAX_ARTIFACT_FILES = 100
26
+ MAX_ARTIFACT_CONTENT_BYTES = 50 * 1024 * 1024
27
+
28
+
29
+ class ArtifactError(ValueError):
30
+ """Represent an invalid or incompatible result artifact."""
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class ArtifactExpectation:
35
+ """Describe trusted workflow provenance required from every result."""
36
+
37
+ repository: str
38
+ pull_request: int
39
+ head_sha: str
40
+ workflow_run_id: int
41
+ graph_digest: str
42
+ node_ids: frozenset[str]
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class ArtifactDescriptor:
47
+ """Carry validated GitHub artifact metadata."""
48
+
49
+ id: int
50
+ node_id: str
51
+ attempt: int
52
+ size: int
53
+ digest: str
54
+
55
+
56
+ def download_results(
57
+ port: GitHubPort,
58
+ expectation: ArtifactExpectation,
59
+ ) -> dict[str, Result]:
60
+ """Download the newest valid attempt for every expected node."""
61
+ selected: dict[str, tuple[int, Result]] = {}
62
+ for descriptor in _artifact_descriptors(port, expectation.workflow_run_id):
63
+ if descriptor.node_id not in expectation.node_ids:
64
+ message = f"artifact targets unknown graph node: {descriptor.node_id}"
65
+ raise ArtifactError(message)
66
+ archive = port.download(f"/actions/artifacts/{descriptor.id}/zip")
67
+ result = _result_from_archive(archive, descriptor)
68
+ _validate_result(result, descriptor, expectation)
69
+ current = selected.get(descriptor.node_id)
70
+ if current is None or descriptor.attempt >= current[0]:
71
+ selected[descriptor.node_id] = (descriptor.attempt, result)
72
+ return {node_id: result for node_id, (_, result) in selected.items()}
73
+
74
+
75
+ def _artifact_descriptors(port: GitHubPort, run_id: int) -> tuple[ArtifactDescriptor, ...]:
76
+ descriptors: list[ArtifactDescriptor] = []
77
+ page = 1
78
+ while True:
79
+ path = f"/actions/runs/{run_id}/artifacts?per_page={GITHUB_PAGE_SIZE}&page={page}"
80
+ response = _object(port.request("GET", path), "workflow artifacts")
81
+ artifacts = _array(response.get("artifacts"), "workflow artifacts")
82
+ for value in artifacts:
83
+ descriptor = _artifact_descriptor(_object(value, "workflow artifact"))
84
+ if descriptor is not None:
85
+ descriptors.append(descriptor)
86
+ if len(artifacts) < GITHUB_PAGE_SIZE:
87
+ return tuple(descriptors)
88
+ page += 1
89
+
90
+
91
+ def _artifact_descriptor(data: dict[str, JsonValue]) -> ArtifactDescriptor | None:
92
+ name = _string(data.get("name"), "artifact name")
93
+ match = ARTIFACT_NAME_RE.fullmatch(name)
94
+ if match is None:
95
+ return None
96
+ if data.get("expired") is True:
97
+ message = f"result artifact has expired: {name}"
98
+ raise ArtifactError(message)
99
+ artifact_id = _integer(data.get("id"), "artifact id")
100
+ size = _integer(data.get("size_in_bytes"), "artifact size")
101
+ if not 0 <= size <= MAX_ARTIFACT_ARCHIVE_BYTES:
102
+ message = f"artifact exceeds the archive size limit: {name}"
103
+ raise ArtifactError(message)
104
+ digest = _string(data.get("digest"), "artifact digest")
105
+ if not digest.startswith("sha256:") or len(digest) != len("sha256:") + 64:
106
+ message = f"artifact has an invalid digest: {name}"
107
+ raise ArtifactError(message)
108
+ return ArtifactDescriptor(
109
+ artifact_id,
110
+ match.group("node"),
111
+ int(match.group("attempt")),
112
+ size,
113
+ digest.removeprefix("sha256:"),
114
+ )
115
+
116
+
117
+ def _result_from_archive(archive: bytes, descriptor: ArtifactDescriptor) -> Result:
118
+ if len(archive) > MAX_ARTIFACT_ARCHIVE_BYTES:
119
+ message = f"downloaded artifact exceeds the archive size limit: {descriptor.id}"
120
+ raise ArtifactError(message)
121
+ actual_digest = hashlib.sha256(archive).hexdigest()
122
+ if actual_digest != descriptor.digest:
123
+ message = f"artifact digest does not match metadata: {descriptor.id}"
124
+ raise ArtifactError(message)
125
+ try:
126
+ with zipfile.ZipFile(io.BytesIO(archive)) as bundle:
127
+ files = tuple(info for info in bundle.infolist() if not info.is_dir())
128
+ _validate_archive_files(files)
129
+ if len(files) != 1 or not files[0].filename.endswith(".json"):
130
+ message = "result artifact must contain exactly one JSON file"
131
+ raise ArtifactError(message)
132
+ return Result.from_json(bundle.read(files[0]))
133
+ except zipfile.BadZipFile as error:
134
+ message = f"result artifact is not a valid ZIP archive: {descriptor.id}"
135
+ raise ArtifactError(message) from error
136
+ except (TypeError, ValueError) as error:
137
+ if isinstance(error, ArtifactError):
138
+ raise
139
+ message = f"result artifact contains invalid result JSON: {descriptor.id}"
140
+ raise ArtifactError(message) from error
141
+
142
+
143
+ def _validate_archive_files(files: Iterable[zipfile.ZipInfo]) -> None:
144
+ values = tuple(files)
145
+ if len(values) > MAX_ARTIFACT_FILES:
146
+ message = "result artifact contains too many files"
147
+ raise ArtifactError(message)
148
+ total = 0
149
+ for info in values:
150
+ path = PurePosixPath(info.filename)
151
+ if path.is_absolute() or ".." in path.parts or "\\" in info.filename:
152
+ message = f"result artifact contains an unsafe path: {info.filename}"
153
+ raise ArtifactError(message)
154
+ mode = info.external_attr >> 16
155
+ if stat.S_ISLNK(mode):
156
+ message = f"result artifact contains a symbolic link: {info.filename}"
157
+ raise ArtifactError(message)
158
+ total += info.file_size
159
+ if total > MAX_ARTIFACT_CONTENT_BYTES:
160
+ message = "result artifact exceeds the uncompressed size limit"
161
+ raise ArtifactError(message)
162
+
163
+
164
+ def _validate_result(
165
+ result: Result,
166
+ descriptor: ArtifactDescriptor,
167
+ expectation: ArtifactExpectation,
168
+ ) -> None:
169
+ provenance = result.provenance
170
+ expected = (
171
+ expectation.repository,
172
+ expectation.pull_request,
173
+ expectation.head_sha,
174
+ expectation.workflow_run_id,
175
+ descriptor.attempt,
176
+ expectation.graph_digest,
177
+ )
178
+ observed = (
179
+ provenance.repository,
180
+ provenance.pull_request,
181
+ provenance.head_sha,
182
+ provenance.workflow_run_id,
183
+ provenance.run_attempt,
184
+ provenance.graph_digest,
185
+ )
186
+ if result.node_id != descriptor.node_id or observed != expected:
187
+ message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
188
+ raise ArtifactError(message)
189
+
190
+
191
+ def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
192
+ if not isinstance(value, dict):
193
+ message = f"{context} must be an object"
194
+ raise ArtifactError(message)
195
+ return value
196
+
197
+
198
+ def _array(value: JsonValue, context: str) -> list[JsonValue]:
199
+ if not isinstance(value, list):
200
+ message = f"{context} must be an array"
201
+ raise ArtifactError(message)
202
+ return value
203
+
204
+
205
+ def _string(value: JsonValue, context: str) -> str:
206
+ if not isinstance(value, str):
207
+ message = f"{context} must be a string"
208
+ raise ArtifactError(message)
209
+ return value
210
+
211
+
212
+ def _integer(value: JsonValue, context: str) -> int:
213
+ if not isinstance(value, int) or isinstance(value, bool):
214
+ message = f"{context} must be an integer"
215
+ raise ArtifactError(message)
216
+ return value