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/publication.py ADDED
@@ -0,0 +1,209 @@
1
+ """Fresh same-invocation verification of clean Git source and prebuilt inputs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import shutil
9
+ import subprocess
10
+ from dataclasses import asdict
11
+ from pathlib import Path
12
+ from tempfile import TemporaryFile
13
+
14
+ from opdev.checks import CheckResult, run_checks
15
+ from opdev.config import Project
16
+ from opdev.errors import OpDevError
17
+ from opdev.files import contained_path, regular_path
18
+ from opdev.process import execute
19
+
20
+
21
+ def git(root: Path, *args: str) -> bytes:
22
+ executable = shutil.which("git")
23
+ if not executable or Path(executable).suffix.lower() in {".cmd", ".bat"}:
24
+ raise OpDevError("Publication needs a native Git executable; nothing installed.")
25
+ if any(
26
+ os.environ.get(k)
27
+ for k in (
28
+ "GIT_DIR",
29
+ "GIT_WORK_TREE",
30
+ "GIT_INDEX_FILE",
31
+ "GIT_COMMON_DIR",
32
+ "GIT_OBJECT_DIRECTORY",
33
+ "GIT_ALTERNATE_OBJECT_DIRECTORIES",
34
+ )
35
+ ):
36
+ raise OpDevError(
37
+ "Publication refuses Git directory/index overrides; use the selected checkout."
38
+ )
39
+ with TemporaryFile() as out:
40
+ try:
41
+ result = subprocess.run(
42
+ [
43
+ executable,
44
+ "--no-optional-locks",
45
+ "-c",
46
+ "core.fsmonitor=false",
47
+ "-C",
48
+ str(root),
49
+ *args,
50
+ ],
51
+ stdin=subprocess.DEVNULL,
52
+ stdout=out,
53
+ stderr=subprocess.DEVNULL,
54
+ timeout=15,
55
+ check=False,
56
+ )
57
+ except subprocess.TimeoutExpired as exc:
58
+ raise OpDevError("Git inspection timed out; publisher not started.") from exc
59
+ if result.returncode:
60
+ raise OpDevError(
61
+ "Git inspection failed; publication needs an accessible committed checkout."
62
+ )
63
+ out.seek(0)
64
+ data = out.read(16 * 1024 * 1024 + 1)
65
+ if len(data) > 16 * 1024 * 1024:
66
+ raise OpDevError("Git inventory exceeds 16 MiB; publication not verified.")
67
+ return data
68
+
69
+
70
+ def fingerprint(path: Path) -> dict[str, str | int]:
71
+ regular_path(path)
72
+ if not path.is_file():
73
+ raise OpDevError(f"Publication input is not a regular prebuilt file: {path}.")
74
+ before = path.stat()
75
+ digest = hashlib.sha256()
76
+ with path.open("rb") as handle:
77
+ while block := handle.read(1024 * 1024):
78
+ digest.update(block)
79
+ after = path.stat()
80
+ identity = ("st_dev", "st_ino", "st_size", "st_mode", "st_mtime_ns", "st_ctime_ns")
81
+ if any(getattr(before, name) != getattr(after, name) for name in identity):
82
+ raise OpDevError("Publication input changed while being fingerprinted.")
83
+ return {"sha256": digest.hexdigest(), "size": after.st_size, "mode": after.st_mode}
84
+
85
+
86
+ def snapshot(project: Project) -> dict[str, object]:
87
+ assert project.publication is not None
88
+ root = project.root
89
+ if Path(os.fsdecode(git(root, "rev-parse", "--show-toplevel")).strip()).resolve() != root:
90
+ raise OpDevError("Publication root must be the Git checkout root, not a nested project.")
91
+ commit = git(root, "rev-parse", "--verify", "HEAD").strip().decode("ascii")
92
+ if git(root, "status", "--porcelain=v1", "--untracked-files=all"):
93
+ raise OpDevError(
94
+ "Publication needs a clean checkout; commit or resolve changes yourself. "
95
+ "Nothing stashed."
96
+ )
97
+ flags = git(root, "ls-files", "-v", "-z").split(b"\0")
98
+ if any(f and (f[:1].islower() or f[:1] == b"S") for f in flags):
99
+ raise OpDevError(
100
+ "Publication refuses assume-unchanged/skip-worktree entries; inspect Git flags."
101
+ )
102
+ source = hashlib.sha256()
103
+ names = set()
104
+ for entry in git(root, "ls-files", "--stage", "-z").split(b"\0"):
105
+ if not entry:
106
+ continue
107
+ header, name = entry.split(b"\t", 1)
108
+ mode, _, stage = header.split()
109
+ if mode not in {b"100644", b"100755"} or stage != b"0":
110
+ raise OpDevError(
111
+ "Publication requires regular tracked files; "
112
+ "submodules, links and conflicts are unsupported."
113
+ )
114
+ relative = os.fsdecode(name)
115
+ names.add(relative)
116
+ path = contained_path(root, relative)
117
+ source.update(name + b"\0" + mode + b"\0")
118
+ source.update(json.dumps(fingerprint(path), sort_keys=True).encode() + b"\0")
119
+ if project.path.relative_to(root).as_posix() not in names:
120
+ raise OpDevError("Publication configuration must be tracked in this checkout.")
121
+ inputs = {name: fingerprint(contained_path(root, name)) for name in project.publication.inputs}
122
+ if (
123
+ git(root, "rev-parse", "HEAD").strip().decode("ascii") != commit
124
+ or git(root, "status", "--porcelain=v1", "--untracked-files=all")
125
+ or not project.unchanged()
126
+ ):
127
+ raise OpDevError("Source or configuration changed during publication inspection.")
128
+ return {
129
+ "commit": commit,
130
+ "source_sha256": source.hexdigest(),
131
+ "config_sha256": project.digest,
132
+ "inputs": inputs,
133
+ }
134
+
135
+
136
+ def publish(project: Project, *, plan: bool = False) -> tuple[dict[str, object], int]:
137
+ settings = project.publication
138
+ if settings is None:
139
+ raise OpDevError("Publication is not configured; no checks or publisher ran.")
140
+ command = project.commands[settings.command]
141
+ publisher = CheckResult(settings.command, command.argv, command.cwd, command.timeout_seconds)
142
+ selected = tuple(dict.fromkeys((*project.checks, *settings.prerequisites)))
143
+ report = run_checks(project, selected, "publication", plan=True)
144
+ result: dict[str, object] = {
145
+ **report.to_dict(),
146
+ "operation": "publish",
147
+ "publisher": asdict(publisher),
148
+ "publication_outcome": "not_attempted",
149
+ "verification_passed": False,
150
+ "detail": "Plan only; no commands ran. Publication needs explicit developer authority.",
151
+ }
152
+ # Planning remains useful before committing/building: it does not claim readiness.
153
+ if plan:
154
+ result["inputs"] = list(settings.inputs)
155
+ return result, 0
156
+ try:
157
+ baseline = snapshot(project)
158
+ result["source"] = baseline
159
+
160
+ report = run_checks(project, selected, "publication")
161
+ result.update(report.to_dict())
162
+ result["operation"] = "publish"
163
+ result["detail"] = "Required publication checks did not pass; publisher not started."
164
+ if report.status != "passed":
165
+ return result, report.exit_code
166
+ if snapshot(project) != baseline:
167
+ raise OpDevError(
168
+ "Publication inputs changed since verification started; publisher not started."
169
+ )
170
+ result["verification_passed"] = True
171
+ result["publication_outcome"] = "unknown"
172
+ publisher.status = "running"
173
+ result["publisher"] = asdict(publisher)
174
+ outcome = execute(
175
+ publisher.argv, contained_path(project.root, publisher.cwd), publisher.timeout_seconds
176
+ )
177
+ publisher.status, publisher.exit_code = outcome.status, outcome.exit_code
178
+ publisher.duration_seconds, publisher.detail = outcome.duration_seconds, outcome.detail
179
+ result["publisher"] = asdict(publisher)
180
+ result["status"] = outcome.status
181
+ if outcome.status == "passed":
182
+ result["publication_outcome"] = "command_succeeded"
183
+ result["detail"] = (
184
+ "Publisher command succeeded; external delivery is not independently verified. "
185
+ "No automatic retry."
186
+ )
187
+ return result, 0
188
+ result["detail"] = (
189
+ "Publisher did not complete successfully; external outcome may be partial or unknown. "
190
+ "Inspect it before any retry."
191
+ )
192
+ return result, 130 if outcome.status == "interrupted" else (
193
+ 2 if outcome.status == "error" else 1
194
+ )
195
+ except (OpDevError, OSError) as exc:
196
+ if publisher.status == "running":
197
+ publisher.status, publisher.detail = "error", str(exc)
198
+ result["publisher"] = asdict(publisher)
199
+ result.update(status="error", detail=str(exc))
200
+ return result, 2
201
+ except KeyboardInterrupt:
202
+ if publisher.status == "running":
203
+ publisher.status = "interrupted"
204
+ result["publisher"] = asdict(publisher)
205
+ result.update(
206
+ status="interrupted",
207
+ detail="Publication interrupted; inspect attempted external effects before retrying.",
208
+ )
209
+ return result, 130