opdev 0.7.0a2__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.
Files changed (42) hide show
  1. opdev/__init__.py +1 -0
  2. opdev/__main__.py +3 -0
  3. opdev/checks.py +300 -0
  4. opdev/cli.py +459 -0
  5. opdev/commands.py +76 -0
  6. opdev/config.py +278 -0
  7. opdev/document_catalog.py +107 -0
  8. opdev/document_review.py +115 -0
  9. opdev/documents.py +415 -0
  10. opdev/errors.py +5 -0
  11. opdev/files.py +82 -0
  12. opdev/init.py +87 -0
  13. opdev/junit.py +99 -0
  14. opdev/output.py +141 -0
  15. opdev/process.py +145 -0
  16. opdev/providers/__init__.py +1 -0
  17. opdev/providers/gitlab.py +374 -0
  18. opdev/publication.py +209 -0
  19. opdev/reports.py +512 -0
  20. opdev/requirements.py +642 -0
  21. opdev/resources/reports/report.css +158 -0
  22. opdev/resources/reports/report.html +27 -0
  23. opdev/resources/reports/report.js +110 -0
  24. opdev/resources/skills/opdev/SKILL.md +190 -0
  25. opdev/resources/skills/opdev/references/adoption.md +144 -0
  26. opdev/resources/skills/opdev/references/design.md +141 -0
  27. opdev/resources/skills/opdev/references/development.md +294 -0
  28. opdev/resources/skills/opdev/references/engineering.md +206 -0
  29. opdev/resources/skills/opdev/references/planning.md +101 -0
  30. opdev/resources/skills/opdev/references/publication.md +34 -0
  31. opdev/resources/templates/AGENTS.md +7 -0
  32. opdev/resources/templates/CLAUDE.md +6 -0
  33. opdev/resources/templates/guidance.md +36 -0
  34. opdev/snapshot.py +484 -0
  35. opdev/tracking.py +224 -0
  36. opdev/verification.py +234 -0
  37. opdev/version.py +45 -0
  38. opdev-0.7.0a2.dist-info/METADATA +99 -0
  39. opdev-0.7.0a2.dist-info/RECORD +42 -0
  40. opdev-0.7.0a2.dist-info/WHEEL +4 -0
  41. opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
  42. opdev-0.7.0a2.dist-info/licenses/LICENSE +201 -0
opdev/output.py ADDED
@@ -0,0 +1,141 @@
1
+ """Presentation only; feature operations determine result meaning."""
2
+
3
+ import json
4
+ from collections import Counter
5
+ from typing import Any
6
+
7
+
8
+ def print_result(result: dict[str, Any], output_format: str) -> None:
9
+ if output_format == "json":
10
+ print(json.dumps(result, ensure_ascii=True))
11
+ return
12
+ print(f"{result['operation']}: {result['status']} ({result.get('scope', 'setup')})")
13
+ _print_documents(result)
14
+ _print_verification(result)
15
+ _print_records(result)
16
+ _print_commands(result)
17
+ _print_requirements(result)
18
+ if result.get("operation") == "documents review":
19
+ print(f" Base commit: {result['base_commit']}")
20
+ print(" Selected document owners: " + json.dumps(result["selected_roles"]))
21
+ for item in result["unexpected_documents"]:
22
+ print(f" REVIEW {item['path']}: owner {item['role']} is outside selected scope")
23
+ for item in result["decision_documents"]:
24
+ print(f" DECISION {item['path']}: technical decision review remains required")
25
+ for field in ("files", "missing_documents", "existing_instructions_to_review"):
26
+ if result.get(field):
27
+ print(f" {field}: {', '.join(result[field])}")
28
+ _print_publication(result)
29
+ if "source" in result:
30
+ print(" input snapshot: " + json.dumps(result["source"]))
31
+ print(result["detail"])
32
+ if result.get("operation") == "check":
33
+ print(
34
+ f"Full configured check passed: {str(result.get('full_check_passed', False)).lower()}"
35
+ )
36
+
37
+
38
+ def _print_verification(result: dict[str, Any]) -> None:
39
+ if verification := result.get("verification"):
40
+ print(
41
+ f" Active requirement verification: {verification['status']}; "
42
+ f"{verification['passed']}/{verification['active']} passed; "
43
+ f"{verification['incomplete']} incomplete"
44
+ )
45
+ if result.get("scope") not in {"full", "publication"}:
46
+ print(" Partial feedback only; full verification was not performed.")
47
+ for finding in verification["findings"]:
48
+ identifiers = " / ".join(
49
+ f"{label} {finding[key]}"
50
+ for key, label in (
51
+ ("requirement", "requirement"),
52
+ ("test", "test"),
53
+ ("command", "check"),
54
+ )
55
+ if finding[key]
56
+ )
57
+ print(f" BLOCKER {identifiers or 'catalog'} [{finding['code']}]: {finding['detail']}")
58
+
59
+
60
+ def _print_records(result: dict[str, Any]) -> None:
61
+ if "revision" in result:
62
+ print(f" revision: {result['revision']}")
63
+ for field in ("implementation", "version", "workflow_sha256"):
64
+ if field in result:
65
+ print(f" {field}: {result[field]}")
66
+ for record in result.get("records", []):
67
+ print(" " + json.dumps(record, ensure_ascii=True))
68
+ for kind in ("phases", "milestones", "issues"):
69
+ if kind in result:
70
+ print(f" {kind}:")
71
+ for record in result[kind]:
72
+ print(" " + json.dumps(record, ensure_ascii=True))
73
+ if "total" in result:
74
+ print(f" matching records: {result['total']}; next offset: {result['next_offset']}")
75
+ if "id" in result:
76
+ print(f" id: {result['id']}")
77
+
78
+
79
+ def _print_commands(result: dict[str, Any]) -> None:
80
+ for item in result.get("checks", result.get("commands", [])):
81
+ print(f" {item['id']}: {item['status']}")
82
+ if result["status"] == "planned":
83
+ print(
84
+ f" argv={json.dumps(item['argv'])}; cwd={item['cwd']}; "
85
+ f"timeout={item['timeout_seconds']}s"
86
+ )
87
+ if item["detail"]:
88
+ print(f" {item['detail']}")
89
+ if (tests := item.get("test_results")) is not None:
90
+ _print_test_results(tests)
91
+
92
+
93
+ def _print_requirements(result: dict[str, Any]) -> None:
94
+ requirements = result.get("requirements", [])
95
+ if requirements:
96
+ passed = [r["id"] for r in requirements if r["status"] == "mapped_tests_passed"]
97
+ print(" Direct test results across all catalog states (not the active verdict):")
98
+ if passed:
99
+ print(" mapped_tests_passed: " + ", ".join(passed))
100
+ print(" Use --format json for each requirement's direct test outcomes.")
101
+
102
+
103
+ def _print_publication(result: dict[str, Any]) -> None:
104
+ if "publisher" in result:
105
+ publisher = result["publisher"]
106
+ print(f" publisher {publisher['id']}: {publisher['status']}")
107
+ if result["status"] == "planned":
108
+ print(
109
+ f" argv={json.dumps(publisher['argv'])}; cwd={publisher['cwd']}; "
110
+ f"timeout={publisher['timeout_seconds']}s; inputs={result['inputs']}"
111
+ )
112
+ print(f" publication outcome: {result['publication_outcome']}")
113
+
114
+
115
+ def _print_test_results(tests: dict[str, Any]) -> None:
116
+ print(f" JUnit results: {tests['status']}")
117
+ counts = Counter(case["status"] for case in tests["cases"])
118
+ print(
119
+ " cases: " + ", ".join(f"{count} {status}" for status, count in sorted(counts.items()))
120
+ )
121
+ for case in tests["cases"]:
122
+ if case["status"] != "passed":
123
+ print(f" {case['classname']}::{case['name']}: {case['status']}")
124
+ for mapping in tests["mappings"]:
125
+ print(f" mapped test {mapping['id']}: {mapping['status']}")
126
+ print(f" {tests['detail']}")
127
+
128
+
129
+ def _print_documents(result: dict[str, Any]) -> None:
130
+ document = (
131
+ result if result.get("operation") == "documents validate" else result.get("documents")
132
+ )
133
+ if document is None:
134
+ return
135
+ print(f" Document structure: {document['status']} (approval not assessed)")
136
+ for finding in document["findings"]:
137
+ location = finding["path"]
138
+ if finding["line"] is not None:
139
+ location += f":{finding['line']}"
140
+ print(f" {location} [{finding['code']}]: {finding['message']}")
141
+ print(f" {finding['remedy']}")
opdev/process.py ADDED
@@ -0,0 +1,145 @@
1
+ """Bounded direct child execution; child output goes to stderr, not JSON stdout."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import shutil
7
+ import signal
8
+ import subprocess
9
+ import sys
10
+ import time
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+
14
+ import psutil
15
+
16
+ from opdev.errors import OpDevError
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class ProcessResult:
21
+ status: str
22
+ exit_code: int | None
23
+ duration_seconds: float
24
+ detail: str | None = None
25
+
26
+
27
+ def stop_tree(process: subprocess.Popen[bytes]) -> None:
28
+ """Cancel our process group/tree, not unrelated processes or host services."""
29
+ if sys.platform != "win32":
30
+ try:
31
+ os.killpg(process.pid, signal.SIGKILL)
32
+ except ProcessLookupError:
33
+ pass
34
+ process.wait(timeout=5)
35
+ return
36
+ try:
37
+ parent = psutil.Process(process.pid)
38
+ parent.suspend()
39
+ members, cleanup_failed = _kill_windows_members(parent)
40
+ _, alive = psutil.wait_procs([*members, parent], timeout=5)
41
+ if alive or cleanup_failed:
42
+ raise OpDevError(
43
+ "Could not confirm termination of the timed-out command's process tree."
44
+ )
45
+ except psutil.NoSuchProcess:
46
+ pass
47
+ except psutil.Error as exc:
48
+ # Do not leave a parent suspended if enumeration or another cleanup step fails.
49
+ if process.poll() is None:
50
+ process.kill()
51
+ process.wait(timeout=5)
52
+ raise OpDevError(
53
+ "Process cleanup failed; inspect the command's remaining processes."
54
+ ) from exc
55
+ process.wait(timeout=5)
56
+
57
+
58
+ def _kill_windows_members(parent: psutil.Process) -> tuple[list[psutil.Process], bool]:
59
+ """Quiesce descendants, rescan, then kill children before the suspended parent."""
60
+ children = parent.children(recursive=True)
61
+ cleanup_failed = False
62
+ for child in children:
63
+ try:
64
+ child.suspend()
65
+ except psutil.NoSuchProcess:
66
+ pass
67
+ except psutil.Error:
68
+ cleanup_failed = True
69
+ # Rescan after suspension to include children spawned during enumeration.
70
+ members = list({p.pid: p for p in [*children, *parent.children(recursive=True)]}.values())
71
+ for child in [*reversed(members), parent]:
72
+ try:
73
+ child.kill()
74
+ except psutil.NoSuchProcess:
75
+ pass
76
+ except psutil.Error:
77
+ cleanup_failed = True
78
+ return members, cleanup_failed
79
+
80
+
81
+ def execute(
82
+ argv: tuple[str, ...], cwd: Path, timeout: int | None, *, interactive: bool = False
83
+ ) -> ProcessResult:
84
+ started = time.monotonic()
85
+ executable: str | None
86
+ if Path(argv[0]).is_absolute() or "/" in argv[0] or "\\" in argv[0]:
87
+ # Preserve venv/interpreter symlinks: resolving them changes Python's environment.
88
+ executable = str((cwd / argv[0]).absolute())
89
+ else:
90
+ executable = shutil.which(argv[0])
91
+ if executable is None:
92
+ return ProcessResult(
93
+ "error",
94
+ None,
95
+ 0.0,
96
+ f"Executable not found: {argv[0]}. Check the project environment.",
97
+ )
98
+ if os.name == "nt" and Path(executable).suffix.lower() in {".cmd", ".bat"}:
99
+ return ProcessResult(
100
+ "error",
101
+ None,
102
+ 0.0,
103
+ "Use a native executable or an explicit reviewed shell command; "
104
+ "implicit batch launch is refused.",
105
+ )
106
+ creationflags = 0
107
+ if sys.platform == "win32":
108
+ creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
109
+ try:
110
+ process = subprocess.Popen(
111
+ (executable, *argv[1:]),
112
+ cwd=cwd,
113
+ stdin=None if interactive else subprocess.DEVNULL,
114
+ stdout=sys.stderr,
115
+ stderr=sys.stderr,
116
+ shell=False,
117
+ start_new_session=os.name != "nt",
118
+ creationflags=creationflags,
119
+ )
120
+ except OSError as exc:
121
+ return ProcessResult(
122
+ "error",
123
+ None,
124
+ round(time.monotonic() - started, 3),
125
+ f"Could not start command: {exc}",
126
+ )
127
+ try:
128
+ code = process.wait(timeout=timeout)
129
+ except (subprocess.TimeoutExpired, KeyboardInterrupt) as exc:
130
+ try:
131
+ stop_tree(process)
132
+ except (OpDevError, OSError, subprocess.TimeoutExpired) as cleanup_error:
133
+ return ProcessResult(
134
+ "error", None, round(time.monotonic() - started, 3), str(cleanup_error)
135
+ )
136
+ status = "interrupted" if isinstance(exc, KeyboardInterrupt) else "timed_out"
137
+ return ProcessResult(
138
+ status,
139
+ None,
140
+ round(time.monotonic() - started, 3),
141
+ "Command stopped; remaining commands did not run.",
142
+ )
143
+ return ProcessResult(
144
+ "passed" if code == 0 else "failed", code, round(time.monotonic() - started, 3)
145
+ )
@@ -0,0 +1 @@
1
+ """Native work-store adapters. No dynamically loaded plugin framework."""
@@ -0,0 +1,374 @@
1
+ """GitLab native IDs and authenticated glab transport, confined to one project."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import re
9
+ import shutil
10
+ import subprocess
11
+ import sys
12
+ from pathlib import Path
13
+ from tempfile import TemporaryFile
14
+ from typing import Any
15
+ from urllib.parse import quote
16
+
17
+ from opdev.config import TrackingConfig
18
+ from opdev.errors import OpDevError
19
+ from opdev.process import stop_tree
20
+ from opdev.tracking import WorkItem
21
+
22
+ MAX_RESPONSE = 8 * 1024 * 1024
23
+ PHASE_LABEL = "opdev:phase"
24
+ MARKER = "<!-- opdev\n"
25
+
26
+
27
+ def metadata(description: str, kind: str) -> tuple[str, dict[str, Any]]:
28
+ """One trailing provider-owned block; the preceding user prose is preserved."""
29
+ if "<!-- opdev" not in description:
30
+ return description, {}
31
+ prose, separator, block = description.partition("\n\n" + MARKER)
32
+ if not separator or "<!-- opdev" in prose or not block.endswith("\n-->"):
33
+ raise OpDevError("Malformed OpDev tracker metadata; inspect the native description.")
34
+ try:
35
+ data = json.loads(block[:-4], object_pairs_hook=unique_metadata)
36
+ except (ValueError, RecursionError) as exc:
37
+ raise OpDevError("Malformed OpDev tracker metadata JSON.") from exc
38
+ _validate_metadata(data, kind)
39
+ return prose, data
40
+
41
+
42
+ def _validate_metadata(data: Any, kind: str) -> None:
43
+ """Validate the provider-owned fields independently of the prose envelope."""
44
+ allowed = (
45
+ {"key"}
46
+ | ({"phase"} if kind == "milestone" else set())
47
+ | ({"requirements"} if kind == "issue" else set())
48
+ )
49
+ if not isinstance(data, dict) or not set(data) <= allowed:
50
+ raise OpDevError("Unsupported OpDev tracker metadata fields.")
51
+ if "key" in data and (
52
+ not isinstance(data["key"], str)
53
+ or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", data["key"])
54
+ ):
55
+ raise OpDevError("Invalid tracker create key.")
56
+ if "phase" in data:
57
+ if not isinstance(data["phase"], str):
58
+ raise OpDevError("Invalid phase reference.")
59
+ display_id(data["phase"])
60
+ if "requirements" in data:
61
+ refs = data["requirements"]
62
+ if not isinstance(refs, list) or any(not isinstance(r, str) or not r for r in refs):
63
+ raise OpDevError("Invalid tracker requirement references.")
64
+ if len(refs) != len(set(refs)):
65
+ raise OpDevError("Duplicate tracker requirement references.")
66
+
67
+
68
+ def _milestone_membership(kind: str, raw: dict[str, Any], project_id: int | None) -> str | None:
69
+ """Resolve only project-local issue membership; phases cannot be milestone children."""
70
+ parent = raw.get("milestone")
71
+ milestone = None
72
+ if kind == "phase" and parent is not None:
73
+ raise OpDevError("A phase planning issue cannot itself belong to a milestone.")
74
+ if kind == "issue" and parent is not None:
75
+ if not isinstance(parent, dict) or parent.get("project_id") != project_id:
76
+ raise OpDevError("OpDev does not support group or cross-project milestone membership.")
77
+ milestone = str(positive_id(parent.get("iid")))
78
+ return milestone
79
+
80
+
81
+ def unique_metadata(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
82
+ data: dict[str, Any] = {}
83
+ for key, value in pairs:
84
+ if key in data:
85
+ raise OpDevError("Duplicate OpDev tracker metadata key.")
86
+ data[key] = value
87
+ return data
88
+
89
+
90
+ def description_with_metadata(prose: str, fields: dict[str, object]) -> str:
91
+ if "<!-- opdev" in prose:
92
+ raise OpDevError("Description contains reserved OpDev metadata; provide user prose only.")
93
+ data = {
94
+ k: v for k, v in fields.items() if k in {"key", "phase", "requirements"} and v is not None
95
+ }
96
+ return prose + ("\n\n" + MARKER + json.dumps(data, sort_keys=True) + "\n-->" if data else "")
97
+
98
+
99
+ def collection(kind: str) -> str:
100
+ if kind not in {"phase", "milestone", "issue"}:
101
+ raise OpDevError("Unsupported GitLab work kind.")
102
+ return "milestones" if kind == "milestone" else "issues"
103
+
104
+
105
+ def glab_request(
106
+ host: str,
107
+ cwd: Path,
108
+ endpoint: str,
109
+ method: str = "GET",
110
+ payload: dict[str, object] | None = None,
111
+ ) -> Any:
112
+ executable = shutil.which("glab")
113
+ if executable is None or Path(executable).suffix.lower() in {".bat", ".cmd"}:
114
+ raise OpDevError(
115
+ "GitLab tracking needs the authenticated native glab executable on PATH; "
116
+ "nothing installed."
117
+ )
118
+ # Use ephemeral files rather than unbounded in-memory subprocess output.
119
+ # Never forward raw stderr: authentication/debug messages may contain secrets.
120
+ with TemporaryFile() as incoming, TemporaryFile() as out, TemporaryFile() as err:
121
+ argv = [executable, "api", endpoint, "--hostname", host, "--method", method]
122
+ if payload is not None:
123
+ incoming.write(json.dumps(payload).encode())
124
+ incoming.seek(0)
125
+ argv.extend(["--header", "Content-Type: application/json", "--input", "-"])
126
+ environment = dict(os.environ)
127
+ environment.pop("GLAB_DEBUG_HTTP", None)
128
+ creationflags = 0
129
+ if sys.platform == "win32":
130
+ creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
131
+ process = subprocess.Popen(
132
+ argv,
133
+ cwd=cwd,
134
+ stdin=incoming if payload is not None else subprocess.DEVNULL,
135
+ stdout=out,
136
+ stderr=err,
137
+ env=environment,
138
+ start_new_session=os.name != "nt",
139
+ creationflags=creationflags,
140
+ )
141
+ try:
142
+ code = process.wait(timeout=60)
143
+ except (subprocess.TimeoutExpired, KeyboardInterrupt) as exc:
144
+ stop_tree(process)
145
+ if isinstance(exc, KeyboardInterrupt):
146
+ raise
147
+ detail = (
148
+ "no remote writes were requested"
149
+ if method == "GET"
150
+ else "remote outcome is unknown; reconcile before retrying"
151
+ )
152
+ raise OpDevError(f"GitLab request timed out; {detail}.") from exc
153
+ if code != 0:
154
+ raise OpDevError(
155
+ f"GitLab request failed (glab exit {code}). Check glab authentication, host, "
156
+ "project and access. "
157
+ + (
158
+ "No writes requested."
159
+ if method == "GET"
160
+ else "Remote outcome is unknown; reconcile before retrying."
161
+ )
162
+ )
163
+ out.seek(0)
164
+ raw = out.read(MAX_RESPONSE + 1)
165
+ if len(raw) > MAX_RESPONSE:
166
+ raise OpDevError(
167
+ "GitLab response exceeds 8 MiB; result unverified. Reconcile any write before retrying."
168
+ )
169
+ try:
170
+ return json.loads(raw.decode("utf-8"))
171
+ except (ValueError, UnicodeError, RecursionError) as exc:
172
+ raise OpDevError(
173
+ "GitLab returned invalid JSON; result unverified. Reconcile any write before retrying."
174
+ ) from exc
175
+
176
+
177
+ def positive_id(value: Any) -> int:
178
+ if type(value) is not int or value <= 0:
179
+ raise OpDevError("GitLab returned an invalid native ID.")
180
+ return value
181
+
182
+
183
+ def display_id(value: str) -> str:
184
+ if not re.fullmatch(r"[1-9][0-9]*", value):
185
+ raise OpDevError("Use the positive project-local ID shown in the tracker URL.")
186
+ return value
187
+
188
+
189
+ class GitLab:
190
+ def __init__(self, config: TrackingConfig, root: Path) -> None:
191
+ self.config = config
192
+ self.root = root
193
+ self.project_id: int | None = None
194
+
195
+ def request(
196
+ self, endpoint: str, method: str = "GET", payload: dict[str, object] | None = None
197
+ ) -> Any:
198
+ return glab_request(self.config.host, self.root, endpoint, method, payload)
199
+
200
+ def base(self) -> str:
201
+ if self.project_id is None:
202
+ data = self.request(f"projects/{quote(self.config.project, safe='')}")
203
+ if not isinstance(data, dict):
204
+ raise OpDevError("GitLab project response is not an object.")
205
+ found = positive_id(data.get("id"))
206
+ if self.config.project.isdigit():
207
+ valid = found == int(self.config.project)
208
+ else:
209
+ valid = data.get("path_with_namespace") == self.config.project
210
+ if not valid:
211
+ raise OpDevError(
212
+ "GitLab project identity differs from configuration; inspect before continuing."
213
+ )
214
+ self.project_id = found
215
+ return f"projects/{self.project_id}"
216
+
217
+ def record(self, kind: str, raw: Any) -> WorkItem:
218
+ if not isinstance(raw, dict) or raw.get("project_id") != self.project_id:
219
+ raise OpDevError("GitLab record belongs to a different or unknown project.")
220
+ iid, native = positive_id(raw.get("iid")), positive_id(raw.get("id"))
221
+ title, description, url = raw.get("title"), raw.get("description"), raw.get("web_url")
222
+ if description is None:
223
+ description = ""
224
+ if (
225
+ not isinstance(title, str)
226
+ or not isinstance(description, str)
227
+ or not isinstance(url, str)
228
+ ):
229
+ raise OpDevError("GitLab record has invalid title, description or URL.")
230
+ if kind != "milestone":
231
+ labels = raw.get("labels", [])
232
+ if not isinstance(labels, list) or any(not isinstance(v, str) for v in labels):
233
+ raise OpDevError("GitLab returned invalid issue labels.")
234
+ if (PHASE_LABEL in labels) != (kind == "phase"):
235
+ raise OpDevError("Requested work kind differs from the issue's phase marker.")
236
+ description, extra = metadata(description, kind)
237
+ states = {"active" if kind == "milestone" else "opened": "open", "closed": "closed"}
238
+ state = raw.get("state")
239
+ if not isinstance(state, str) or state not in states:
240
+ raise OpDevError("GitLab record has an unsupported state.")
241
+ milestone = _milestone_membership(kind, raw, self.project_id)
242
+ revision = hashlib.sha256(json.dumps(raw, sort_keys=True).encode()).hexdigest()
243
+ return WorkItem(
244
+ kind,
245
+ str(iid),
246
+ native,
247
+ title,
248
+ description,
249
+ states[state],
250
+ url,
251
+ revision,
252
+ milestone,
253
+ extra.get("phase"),
254
+ tuple(extra.get("requirements", [])),
255
+ extra.get("key"),
256
+ )
257
+
258
+ def list(self, kind: str) -> list[WorkItem]:
259
+ resource = collection(kind)
260
+ base = self.base()
261
+ result: dict[str, WorkItem] = {}
262
+ for page in range(1, 101):
263
+ ordering = (
264
+ "sort=created_asc"
265
+ if kind == "milestone"
266
+ else "state=all&order_by=created_at&sort=asc"
267
+ )
268
+ data = self.request(f"{base}/{resource}?per_page=100&page={page}&{ordering}")
269
+ if not isinstance(data, list):
270
+ raise OpDevError("GitLab listing is not an array; no complete result available.")
271
+ for raw in data:
272
+ actual = kind
273
+ if kind != "milestone" and isinstance(raw, dict):
274
+ labels = raw.get("labels", [])
275
+ if not isinstance(labels, list):
276
+ raise OpDevError("GitLab returned invalid issue labels.")
277
+ actual = "phase" if PHASE_LABEL in labels else "issue"
278
+ item = self.record(actual, raw)
279
+ if item.id in result:
280
+ raise OpDevError(
281
+ "GitLab pagination repeated a record; retry the changed listing."
282
+ )
283
+ result[item.id] = item
284
+ if len(data) < 100:
285
+ return sorted(
286
+ (i for i in result.values() if i.kind == kind), key=lambda i: int(i.id)
287
+ )
288
+ raise OpDevError("GitLab listing exceeds 100 pages; no complete result available.")
289
+
290
+ def get(self, kind: str, item_id: str) -> WorkItem:
291
+ display_id(item_id)
292
+ base = self.base()
293
+ if kind in {"issue", "phase"}:
294
+ result = self.record(kind, self.request(f"{base}/issues/{item_id}"))
295
+ elif kind == "milestone":
296
+ # GitLab's milestone detail endpoint takes a global ID, not the URL's IID.
297
+ data = self.request(f"{base}/milestones?iids[]={item_id}")
298
+ if not isinstance(data, list) or len(data) != 1:
299
+ raise OpDevError(f"Expected exactly one project milestone {item_id}.")
300
+ result = self.record(kind, data[0])
301
+ else:
302
+ raise OpDevError("Unsupported GitLab work kind.")
303
+ if result.id != item_id:
304
+ raise OpDevError("GitLab returned a different work item than requested.")
305
+ return result
306
+
307
+ def create(self, kind: str, fields: dict[str, object]) -> WorkItem:
308
+ body: dict[str, object] = {
309
+ "title": fields["title"],
310
+ "description": description_with_metadata(str(fields["description"]), fields),
311
+ }
312
+ if kind == "phase":
313
+ body["labels"] = PHASE_LABEL
314
+ if "milestone" in fields:
315
+ body["milestone_id"] = self.get("milestone", str(fields["milestone"])).native_id
316
+ endpoint = f"{self.base()}/{collection(kind)}"
317
+ try:
318
+ result = self.record(kind, self.request(endpoint, "POST", body))
319
+ return self.get(kind, result.id)
320
+ except (OpDevError, OSError) as exc:
321
+ raise OpDevError(
322
+ "Create attempted; outcome/readback unverified. Reconcile the create key "
323
+ "before retrying. " + str(exc)
324
+ ) from exc
325
+
326
+ def update(self, item: WorkItem, fields: dict[str, object]) -> WorkItem:
327
+ current = self.get(item.kind, item.id)
328
+ if current.revision != item.revision:
329
+ raise OpDevError("Tracker record changed since inspection; no update sent.")
330
+ if not fields or not set(fields) <= {
331
+ "title",
332
+ "description",
333
+ "state",
334
+ "milestone",
335
+ "phase",
336
+ "requirements",
337
+ }:
338
+ raise OpDevError("Select supported tracker fields to update.")
339
+ body = {
340
+ k: v for k, v in fields.items() if k not in {"description", "phase", "requirements"}
341
+ }
342
+ if set(fields) & {"description", "phase", "requirements"}:
343
+ extra: dict[str, object] = {"key": current.key, "phase": current.phase}
344
+ if item.kind == "issue":
345
+ extra["requirements"] = current.requirements
346
+ extra.update(fields)
347
+ body["description"] = description_with_metadata(
348
+ str(fields.get("description", current.description)), extra
349
+ )
350
+ if "state" in body:
351
+ state = body.pop("state")
352
+ if state not in {"open", "closed"}:
353
+ raise OpDevError("Unsupported tracker state.")
354
+ body["state_event"] = (
355
+ "close"
356
+ if state == "closed"
357
+ else ("activate" if item.kind == "milestone" else "reopen")
358
+ )
359
+ if "milestone" in body:
360
+ parent = body.pop("milestone")
361
+ if item.kind != "issue" or not isinstance(parent, str):
362
+ raise OpDevError("Use an existing project milestone for issue membership.")
363
+ body["milestone_id"] = self.get("milestone", parent).native_id
364
+ native_id = str(item.native_id) if item.kind == "milestone" else item.id
365
+ # Send only requested fields; labels, assignees and other native fields stay untouched.
366
+ endpoint = f"{self.base()}/{collection(item.kind)}/{native_id}"
367
+ try:
368
+ self.request(endpoint, "PUT", body)
369
+ return self.get(item.kind, item.id)
370
+ except (OpDevError, OSError) as exc:
371
+ raise OpDevError(
372
+ "Update attempted; outcome/readback unverified. Inspect the current record "
373
+ "before retrying. " + str(exc)
374
+ ) from exc