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 +5 -0
- qg_github/annotations.py +93 -0
- qg_github/approvals.py +172 -0
- qg_github/artifacts.py +216 -0
- qg_github/commands.py +333 -0
- qg_github/comments.py +104 -0
- qg_github/compiler.py +398 -0
- qg_github/controls.py +67 -0
- qg_github/dashboard.py +267 -0
- qg_github/github.py +183 -0
- qg_github/labels.py +133 -0
- qg_github/provider.py +20 -0
- qg_github/publication.py +303 -0
- qg_github/py.typed +1 -0
- qg_github/reporting.py +97 -0
- qg_github/runtime.py +195 -0
- quality_graph_github-0.1.0.dist-info/METADATA +19 -0
- quality_graph_github-0.1.0.dist-info/RECORD +20 -0
- quality_graph_github-0.1.0.dist-info/WHEEL +4 -0
- quality_graph_github-0.1.0.dist-info/entry_points.txt +2 -0
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} -->"
|