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.
- opdev/__init__.py +1 -0
- opdev/__main__.py +3 -0
- opdev/checks.py +300 -0
- opdev/cli.py +459 -0
- opdev/commands.py +76 -0
- opdev/config.py +278 -0
- opdev/document_catalog.py +107 -0
- opdev/document_review.py +115 -0
- opdev/documents.py +415 -0
- opdev/errors.py +5 -0
- opdev/files.py +82 -0
- opdev/init.py +87 -0
- opdev/junit.py +99 -0
- opdev/output.py +141 -0
- opdev/process.py +145 -0
- opdev/providers/__init__.py +1 -0
- opdev/providers/gitlab.py +374 -0
- opdev/publication.py +209 -0
- opdev/reports.py +512 -0
- opdev/requirements.py +642 -0
- opdev/resources/reports/report.css +158 -0
- opdev/resources/reports/report.html +27 -0
- opdev/resources/reports/report.js +110 -0
- opdev/resources/skills/opdev/SKILL.md +190 -0
- opdev/resources/skills/opdev/references/adoption.md +144 -0
- opdev/resources/skills/opdev/references/design.md +141 -0
- opdev/resources/skills/opdev/references/development.md +294 -0
- opdev/resources/skills/opdev/references/engineering.md +206 -0
- opdev/resources/skills/opdev/references/planning.md +101 -0
- opdev/resources/skills/opdev/references/publication.md +34 -0
- opdev/resources/templates/AGENTS.md +7 -0
- opdev/resources/templates/CLAUDE.md +6 -0
- opdev/resources/templates/guidance.md +36 -0
- opdev/snapshot.py +484 -0
- opdev/tracking.py +224 -0
- opdev/verification.py +234 -0
- opdev/version.py +45 -0
- opdev-0.7.0a2.dist-info/METADATA +99 -0
- opdev-0.7.0a2.dist-info/RECORD +42 -0
- opdev-0.7.0a2.dist-info/WHEEL +4 -0
- opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
- 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
|