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/documents.py ADDED
@@ -0,0 +1,415 @@
1
+ """Read-only structural validation of the fixed development-document layout."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import re
9
+ import stat
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path, PureWindowsPath
12
+ from typing import Any
13
+ from urllib.parse import unquote, urlsplit
14
+
15
+ from markdown_it import MarkdownIt
16
+ from markdown_it.token import Token
17
+
18
+ from opdev.config import Project
19
+ from opdev.document_catalog import DOCUMENT_LAYOUT, DOCUMENTS, DocumentSpec
20
+ from opdev.errors import OpDevError
21
+ from opdev.files import read_regular, regular_path
22
+
23
+ MAX_ENTRIES = 1024
24
+ MAX_BYTES = 16 * 1_048_576
25
+ LIMITATION = (
26
+ "Structural checks only; content adequacy, consistency, approval, external URLs and "
27
+ "renderer-specific anchors are not verified. No project commands ran or files changed. "
28
+ "The input identity describes inspected bytes, not an atomic or reusable qualification."
29
+ )
30
+ _PLACEHOLDER = re.compile(
31
+ r"(?:(?:todo|tbd|fixme|placeholder|to be (?:determined|decided|written)|"
32
+ r"not yet (?:specified|decided|documented)|\.\.\.|…)(?:\s*[:.!-].*)?|"
33
+ r"(?:n/?a|not applicable)[.!]?)",
34
+ re.IGNORECASE | re.DOTALL,
35
+ )
36
+
37
+
38
+ @dataclass
39
+ class Entry:
40
+ kind: str
41
+ raw: bytes | None = None
42
+ error: str | None = None
43
+
44
+
45
+ @dataclass
46
+ class Inspection:
47
+ entries: dict[str, Entry] = field(default_factory=dict)
48
+ findings: list[dict[str, Any]] = field(default_factory=list)
49
+ complete: bool = True
50
+
51
+
52
+ def _finding(
53
+ code: str, path: str, message: str, remedy: str, line: int | None = None
54
+ ) -> dict[str, Any]:
55
+ # Authored headings and URLs can be large; keep findings usable in bounded snapshots.
56
+ if len(message) > 4096:
57
+ message = message[:4093] + "..."
58
+ return {"code": code, "path": path, "line": line, "message": message, "remedy": remedy}
59
+
60
+
61
+ def validate(project: Project) -> dict[str, Any]:
62
+ """Inspect current files without executing commands, following links or writing state."""
63
+ inspection = _scan(project.root)
64
+ findings = inspection.findings
65
+ findings.extend(_namespace_findings(inspection.entries))
66
+ records = []
67
+ for spec in DOCUMENTS.values():
68
+ selected = spec.required or spec.role in project.documents
69
+ entry = inspection.entries.get(spec.path)
70
+ records.append(
71
+ {
72
+ "role": spec.role,
73
+ "path": spec.path,
74
+ "required": spec.required,
75
+ "headings": list(spec.headings),
76
+ "selected": selected,
77
+ "present": entry is not None,
78
+ "sha256": hashlib.sha256(entry.raw).hexdigest()
79
+ if entry is not None and entry.raw is not None
80
+ else None,
81
+ }
82
+ )
83
+ findings.extend(_document_findings(project.root, spec, selected, entry))
84
+ return {
85
+ "operation": "documents validate",
86
+ "status": "invalid" if findings else "valid",
87
+ "scope": "documents",
88
+ "document_layout": DOCUMENT_LAYOUT,
89
+ "records": records,
90
+ "findings": sorted(findings, key=lambda f: (f["path"], f["line"] or 0, f["code"])),
91
+ "input_sha256": _identity(project, inspection),
92
+ "inspection_complete": inspection.complete,
93
+ "detail": LIMITATION,
94
+ "limitations": [LIMITATION],
95
+ }
96
+
97
+
98
+ def _runtime_file(path: str) -> bool:
99
+ return path == ".opdev/requirements.json.lock" or bool(
100
+ re.fullmatch(r"\.opdev/\.opdev-[a-z0-9_]{8}", path)
101
+ )
102
+
103
+
104
+ def _safe_error(exc: Exception) -> str:
105
+ if isinstance(exc, FileNotFoundError):
106
+ return "The path does not exist."
107
+ if isinstance(exc, PermissionError):
108
+ return "Permission to inspect the path was denied."
109
+ if isinstance(exc, (ValueError, UnicodeError)):
110
+ return "The path or URL is malformed."
111
+ return "The input is linked, unreadable, unsupported or exceeds inspection limits."
112
+
113
+
114
+ def _read_entry(path: Path, relative: str, remaining: int) -> Entry:
115
+ regular_path(path)
116
+ mode = path.lstat().st_mode
117
+ if stat.S_ISDIR(mode):
118
+ return Entry("directory")
119
+ if not stat.S_ISREG(mode):
120
+ raise OpDevError("Expected a regular file or directory.")
121
+ if _runtime_file(relative):
122
+ return Entry("runtime")
123
+ return Entry("file", read_regular(path, limit=min(1_048_576, remaining)))
124
+
125
+
126
+ def _scan(root: Path) -> Inspection:
127
+ inspection = Inspection()
128
+ pending = [root / ".opdev"]
129
+ total_bytes = 0
130
+ while pending:
131
+ path = pending.pop()
132
+ relative = path.relative_to(root).as_posix()
133
+ try:
134
+ entry = _read_entry(path, relative, MAX_BYTES - total_bytes)
135
+ inspection.entries[relative] = entry
136
+ if entry.raw is not None:
137
+ total_bytes += len(entry.raw)
138
+ if entry.kind == "directory":
139
+ pending.extend(_children(path, len(inspection.entries) + len(pending)))
140
+ except (OSError, OpDevError) as exc:
141
+ if isinstance(exc, FileNotFoundError) and _runtime_file(relative):
142
+ continue
143
+ inspection.complete = False
144
+ error = _safe_error(exc)
145
+ inspection.entries[relative] = Entry("unreadable", error=error)
146
+ inspection.findings.append(
147
+ _finding(
148
+ "document_input_unreadable",
149
+ relative,
150
+ f"Cannot inspect managed input: {error}",
151
+ "Restore a readable regular path without links and within input limits.",
152
+ )
153
+ )
154
+ return inspection
155
+
156
+
157
+ def _children(path: Path, observed: int) -> list[Path]:
158
+ children: list[Path] = []
159
+ with os.scandir(path) as entries:
160
+ for entry in entries:
161
+ if observed + len(children) >= MAX_ENTRIES:
162
+ raise OpDevError(f"Document inventory exceeds {MAX_ENTRIES} paths.")
163
+ children.append(path / entry.name)
164
+ return sorted(children, reverse=True)
165
+
166
+
167
+ def _namespace_findings(entries: dict[str, Entry]) -> list[dict[str, Any]]:
168
+ allowed_files = {spec.path for spec in DOCUMENTS.values()} | {
169
+ ".opdev/project.yaml",
170
+ ".opdev/requirements.json",
171
+ ".opdev/requirements.json.lock",
172
+ }
173
+ findings = []
174
+ for path, entry in entries.items():
175
+ if path in {".opdev", ".opdev/technical"}:
176
+ allowed = entry.kind in {"directory", "unreadable"}
177
+ else:
178
+ known = path in allowed_files or _runtime_file(path)
179
+ allowed = bool(known) and entry.kind in {"file", "runtime", "unreadable"}
180
+ if not allowed:
181
+ findings.append(
182
+ _finding(
183
+ "document_path_unexpected",
184
+ path,
185
+ "This path or file type is outside the fixed .opdev layout.",
186
+ "Keep only catalog documents and OpDev-managed files here; move other material "
187
+ "to its appropriate owner after reviewing its contents.",
188
+ )
189
+ )
190
+ return findings
191
+
192
+
193
+ def _identity(project: Project, inspection: Inspection) -> str:
194
+ entries = {
195
+ path: {
196
+ "kind": entry.kind,
197
+ "sha256": hashlib.sha256(entry.raw).hexdigest() if entry.raw is not None else None,
198
+ "error": entry.error,
199
+ }
200
+ for path, entry in inspection.entries.items()
201
+ if not _runtime_file(path)
202
+ }
203
+ payload = {"layout": DOCUMENT_LAYOUT, "documents": project.documents, "entries": entries}
204
+ return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
205
+
206
+
207
+ def _document_findings(
208
+ root: Path, spec: DocumentSpec, selected: bool, entry: Entry | None
209
+ ) -> list[dict[str, Any]]:
210
+ if selected and entry is None:
211
+ return [
212
+ _finding(
213
+ "document_missing",
214
+ spec.path,
215
+ f"The selected {spec.role} document is missing.",
216
+ "Create the canonical document with its required headings and substantive content.",
217
+ )
218
+ ]
219
+ if entry is not None and not selected:
220
+ return [
221
+ _finding(
222
+ "document_unselected",
223
+ spec.path,
224
+ f"Optional role {spec.role} exists but is not selected.",
225
+ "Select the role in project.yaml, or review and remove the unused file.",
226
+ )
227
+ ]
228
+ if entry is None or entry.raw is None:
229
+ return []
230
+ try:
231
+ text = entry.raw.decode("utf-8")
232
+ except UnicodeError:
233
+ return [
234
+ _finding(
235
+ "document_encoding",
236
+ spec.path,
237
+ "Document is not valid UTF-8.",
238
+ "Save the document as UTF-8 without losing its decisions.",
239
+ )
240
+ ]
241
+ tokens = MarkdownIt("commonmark").parse(text)
242
+ return _structure_findings(spec, tokens) + _link_findings(root, spec.path, tokens)
243
+
244
+
245
+ def _line(token: Token) -> int | None:
246
+ return token.map[0] + 1 if token.map is not None else None
247
+
248
+
249
+ def _heading_text(token: Token) -> str:
250
+ return " ".join(
251
+ "".join(
252
+ child.content for child in token.children or [] if child.type in {"text", "code_inline"}
253
+ ).split()
254
+ )
255
+
256
+
257
+ def _structure_findings(spec: DocumentSpec, tokens: list[Token]) -> list[dict[str, Any]]:
258
+ headings = [
259
+ (index, token, _heading_text(tokens[index + 1]))
260
+ for index, token in enumerate(tokens)
261
+ if token.type == "heading_open" and token.level == 0 and token.tag in {"h1", "h2"}
262
+ ]
263
+ findings = []
264
+ titles = [token for _, token, _ in headings if token.tag == "h1"]
265
+ if len(titles) != 1:
266
+ findings.append(
267
+ _finding(
268
+ "document_title_count",
269
+ spec.path,
270
+ f"Expected one H1 title; found {len(titles)}.",
271
+ "Use exactly one top-level Markdown H1 title.",
272
+ _line(titles[1]) if len(titles) > 1 else 1,
273
+ )
274
+ )
275
+ sections = [(index, token, name) for index, token, name in headings if token.tag == "h2"]
276
+ findings.extend(_section_counts(spec, sections))
277
+ for position, (index, token, name) in enumerate(headings):
278
+ if token.tag != "h2" or name not in spec.headings:
279
+ continue
280
+ end = headings[position + 1][0] if position + 1 < len(headings) else len(tokens)
281
+ if not _has_content(tokens[index + 3 : end]):
282
+ findings.append(
283
+ _finding(
284
+ "document_section_empty",
285
+ spec.path,
286
+ f"Section {name!r} contains only empty, placeholder or link-only material.",
287
+ "Write project decisions here; subsections may organize them.",
288
+ _line(token),
289
+ )
290
+ )
291
+ return findings
292
+
293
+
294
+ def _section_counts(
295
+ spec: DocumentSpec, sections: list[tuple[int, Token, str]]
296
+ ) -> list[dict[str, Any]]:
297
+ findings = []
298
+ for name in spec.headings:
299
+ matches = [token for _, token, title in sections if title == name]
300
+ if len(matches) != 1:
301
+ findings.append(
302
+ _finding(
303
+ "document_section_count",
304
+ spec.path,
305
+ f"Expected H2 {name!r} exactly once; found {len(matches)}.",
306
+ "Use each required H2 once; organize further under H3 or deeper.",
307
+ _line(matches[1]) if len(matches) > 1 else None,
308
+ )
309
+ )
310
+ for _, token, name in sections:
311
+ if name not in spec.headings:
312
+ findings.append(
313
+ _finding(
314
+ "document_section_unexpected",
315
+ spec.path,
316
+ f"Unexpected H2 section {name!r}.",
317
+ "Place this material under its fixed H2; use H3 or deeper as needed.",
318
+ _line(token),
319
+ )
320
+ )
321
+ return findings
322
+
323
+
324
+ def _prose(children: list[Token]) -> str:
325
+ pieces = []
326
+ in_link = False
327
+ for child in children:
328
+ if child.type in {"link_open", "link_close"}:
329
+ in_link = child.type == "link_open"
330
+ elif not in_link and child.type in {"text", "code_inline", "softbreak", "hardbreak"}:
331
+ pieces.append(child.content if child.type in {"text", "code_inline"} else "\n")
332
+ return "".join(pieces)
333
+
334
+
335
+ def _substantive(text: str) -> bool:
336
+ text = re.sub(r"https?://\S+", "", text).strip()
337
+ return any(
338
+ re.search(r"[^\W_]", line) is not None
339
+ and _PLACEHOLDER.fullmatch(line.strip().strip("[]{}<>")) is None
340
+ for line in text.splitlines()
341
+ )
342
+
343
+
344
+ def _has_content(tokens: list[Token]) -> bool:
345
+ for index, token in enumerate(tokens):
346
+ if token.type in {"fence", "code_block"} and _substantive(token.content):
347
+ return True
348
+ if token.type == "inline" and (index == 0 or tokens[index - 1].type != "heading_open"):
349
+ if _substantive(_prose(token.children or [])):
350
+ return True
351
+ return False
352
+
353
+
354
+ def _link_findings(root: Path, path: str, tokens: list[Token]) -> list[dict[str, Any]]:
355
+ findings = []
356
+ for token in tokens:
357
+ if token.type != "inline":
358
+ continue
359
+ line = _line(token)
360
+ for child in token.children or []:
361
+ if child.type in {"softbreak", "hardbreak"} and line is not None:
362
+ line += 1
363
+ target = child.attrGet("href") if child.type == "link_open" else child.attrGet("src")
364
+ if isinstance(target, str):
365
+ error = _link_error(root, path, target)
366
+ if error is not None:
367
+ findings.append(
368
+ _finding(
369
+ "document_link_invalid",
370
+ path,
371
+ f"Local link {target!r}: {error}",
372
+ "Link an existing repository target without symlinks or junctions.",
373
+ line,
374
+ )
375
+ )
376
+ return findings
377
+
378
+
379
+ def _relative_target(target: str) -> str | None:
380
+ parsed = urlsplit(target)
381
+ if parsed.scheme and parsed.scheme.lower() != "file" and len(parsed.scheme) != 1:
382
+ return None
383
+ if parsed.netloc:
384
+ if parsed.scheme.lower() == "file":
385
+ raise OpDevError("absolute file paths are unsupported")
386
+ return None
387
+ decoded = unquote(parsed.path, errors="strict")
388
+ if not decoded:
389
+ return None
390
+ if (
391
+ parsed.scheme
392
+ or "\0" in decoded
393
+ or Path(decoded).is_absolute()
394
+ or PureWindowsPath(decoded).drive
395
+ ):
396
+ raise OpDevError("absolute file paths are unsupported")
397
+ return decoded
398
+
399
+
400
+ def _link_error(root: Path, document: str, target: str) -> str | None:
401
+ try:
402
+ relative = _relative_target(target)
403
+ if relative is None:
404
+ return None
405
+ candidate = root / Path(document).parent / relative
406
+ normalized = Path(os.path.abspath(candidate))
407
+ if not normalized.is_relative_to(root):
408
+ return "target escapes the repository"
409
+ regular_path(candidate)
410
+ mode = candidate.stat().st_mode
411
+ if not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):
412
+ return "target is not a regular file or directory"
413
+ except (OSError, OpDevError, ValueError, UnicodeError) as exc:
414
+ return _safe_error(exc)
415
+ return None
opdev/errors.py ADDED
@@ -0,0 +1,5 @@
1
+ """Errors safe to present to a developer without a traceback."""
2
+
3
+
4
+ class OpDevError(Exception):
5
+ """An actionable input or operation error."""
opdev/files.py ADDED
@@ -0,0 +1,82 @@
1
+ """Narrow filesystem operations for managed project inputs."""
2
+
3
+ import os
4
+ import tempfile
5
+ from pathlib import Path
6
+
7
+ from opdev.errors import OpDevError
8
+
9
+
10
+ def regular_path(path: Path) -> None:
11
+ for component in (path, *path.parents):
12
+ if component.is_symlink() or component.is_junction():
13
+ raise OpDevError(f"Linked path is not supported for managed input: {component}.")
14
+
15
+
16
+ def read_regular(path: Path, *, limit: int = 1_048_576) -> bytes:
17
+ regular_path(path)
18
+ if not path.is_file():
19
+ raise OpDevError(f"Required file is missing or is not a regular file: {path}.")
20
+ with path.open("rb") as handle:
21
+ data = handle.read(limit + 1)
22
+ if len(data) > limit:
23
+ raise OpDevError(f"Managed input exceeds {limit} bytes: {path}.")
24
+ return data
25
+
26
+
27
+ def contained_path(root: Path, relative: str) -> Path:
28
+ candidate = Path(relative)
29
+ if candidate.is_absolute() or candidate.drive or ".." in candidate.parts:
30
+ raise OpDevError(f"Use a contained project-relative path: {relative}.")
31
+ path = root / candidate
32
+ regular_path(path)
33
+ if not path.resolve().is_relative_to(root):
34
+ raise OpDevError(f"Path is outside the project: {relative}.")
35
+ return path
36
+
37
+
38
+ def read_optional(path: Path) -> bytes | None:
39
+ regular_path(path)
40
+ return read_regular(path) if path.exists() else None
41
+
42
+
43
+ def replace_checked(path: Path, expected: bytes | None, content: bytes) -> None:
44
+ """Serialize OpDev writers and replace one file, refusing changed input.
45
+
46
+ The lock is fail-fast, never stolen. Editors not respecting it are outside
47
+ mutual exclusion; a final byte check detects changes observed before replace.
48
+ """
49
+ regular_path(path)
50
+ lock = path.with_name(path.name + ".lock")
51
+ regular_path(lock)
52
+ try:
53
+ handle = lock.open("xb")
54
+ except FileExistsError as exc:
55
+ raise OpDevError(
56
+ f"Another update may be active: {lock}. Nothing written. "
57
+ "If interrupted, confirm no writer remains before removing its lock."
58
+ ) from exc
59
+ temporary: Path | None = None
60
+ try:
61
+ with handle:
62
+ handle.write(f"pid={os.getpid()}\n".encode())
63
+ handle.flush()
64
+ if read_optional(path) != expected:
65
+ raise OpDevError("Requirements changed since inspection; reread before retrying.")
66
+ with tempfile.NamedTemporaryFile(
67
+ dir=path.parent, prefix=".opdev-", delete=False
68
+ ) as out:
69
+ temporary = Path(out.name)
70
+ out.write(content)
71
+ out.flush()
72
+ os.fsync(out.fileno())
73
+ if read_optional(path) != expected:
74
+ raise OpDevError("Requirements changed during update; nothing replaced.")
75
+ os.replace(temporary, path)
76
+ temporary = None
77
+ if read_regular(path) != content:
78
+ raise OpDevError("Requirements changed after replacement; inspect before retrying.")
79
+ finally:
80
+ if temporary is not None:
81
+ temporary.unlink(missing_ok=True)
82
+ lock.unlink()
opdev/init.py ADDED
@@ -0,0 +1,87 @@
1
+ """Create-only setup; initialization is not adoption approval or test execution."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from importlib.resources import files
7
+ from pathlib import Path
8
+
9
+ from opdev.config import CONFIG_PATH, load_project
10
+ from opdev.errors import OpDevError
11
+ from opdev.files import contained_path, regular_path
12
+
13
+
14
+ def initialize(root: Path, config: Path, *, plan: bool = False) -> dict[str, object]:
15
+ project = load_project(root, config)
16
+ templates = files("opdev").joinpath("resources/templates")
17
+ guidance = templates.joinpath("guidance.md").read_bytes()
18
+ proposed = {str(CONFIG_PATH): project.raw, ".opdev/guidance.md": guidance}
19
+ routing_review = []
20
+ for name in ("AGENTS.md", "CLAUDE.md"):
21
+ target = project.root / name
22
+ regular_path(target)
23
+ if target.exists():
24
+ if not target.is_file():
25
+ raise OpDevError(
26
+ f"Existing instruction path is not a file: {name}. Nothing written."
27
+ )
28
+ routing_review.append(name)
29
+ else:
30
+ proposed[name] = templates.joinpath(name).read_bytes()
31
+ for name in proposed:
32
+ if contained_path(project.root, name).exists():
33
+ raise OpDevError(
34
+ f"Managed file already exists: {name}. Review it; nothing overwritten."
35
+ )
36
+ missing_docs = [
37
+ path
38
+ for path in project.documents.values()
39
+ if path not in proposed and not contained_path(project.root, path).is_file()
40
+ ]
41
+ result: dict[str, object] = {
42
+ "operation": "init",
43
+ "status": "planned" if plan else "initialized",
44
+ "files": list(proposed),
45
+ "existing_instructions_to_review": routing_review,
46
+ "missing_documents": missing_docs,
47
+ "adoption_verified": False,
48
+ "detail": "Setup only; review document content and routing. "
49
+ "No commands ran or decisions were approved. "
50
+ "Direct pushes to the integration branch are prohibited. "
51
+ "Provider protection has not been verified; hosted adoption remains incomplete."
52
+ + (
53
+ " Existing host files were preserved. Confirm or add routes to "
54
+ ".opdev/guidance.md and .opdev/project.yaml in the listed host files "
55
+ "before claiming adoption complete. Preserve their other instructions."
56
+ if routing_review
57
+ else ""
58
+ ),
59
+ }
60
+ if plan:
61
+ return result
62
+ if not project.unchanged():
63
+ raise OpDevError("Configuration changed since initialization inspection; nothing written.")
64
+ _write_proposed(project.root, proposed)
65
+ return result
66
+
67
+
68
+ def _write_proposed(root: Path, proposed: dict[str, bytes]) -> None:
69
+ """Create the inspected files, preserving partial-write diagnostics on interruption."""
70
+ created: list[str] = []
71
+ try:
72
+ for name, content in proposed.items():
73
+ target = contained_path(root, name)
74
+ target.parent.mkdir(parents=True, exist_ok=True)
75
+ regular_path(target)
76
+ with target.open("xb") as handle:
77
+ created.append(name)
78
+ handle.write(content)
79
+ handle.flush()
80
+ os.fsync(handle.fileno())
81
+ if target.read_bytes() != content:
82
+ raise OpDevError(f"Readback changed for {name}.")
83
+ except (OSError, OpDevError, KeyboardInterrupt) as exc:
84
+ raise OpDevError(
85
+ f"Initialization incomplete. Files created: {', '.join(created) or 'none'}. "
86
+ "Inspect these paths before retrying; no existing file was overwritten."
87
+ ) from exc
opdev/junit.py ADDED
@@ -0,0 +1,99 @@
1
+ """Bounded JUnit reader. Reported cases, never runner discovery or assertion review."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import Counter
6
+ from dataclasses import dataclass, replace
7
+ from xml.etree.ElementTree import Element, ParseError
8
+
9
+ from defusedxml.common import DefusedXmlException
10
+ from defusedxml.ElementTree import fromstring
11
+
12
+ from opdev.errors import OpDevError
13
+
14
+ MAX_BYTES = 10 * 1024 * 1024
15
+ MAX_CASES = 100_000
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class Case:
20
+ classname: str
21
+ name: str
22
+ status: str
23
+
24
+
25
+ def parse(raw: bytes) -> list[Case]:
26
+ if len(raw) > MAX_BYTES:
27
+ raise OpDevError("JUnit report exceeds 10 MiB; test results not verified.")
28
+ try:
29
+ root = fromstring(raw, forbid_dtd=True)
30
+ except (ParseError, DefusedXmlException, ValueError) as exc:
31
+ raise OpDevError("JUnit report is invalid or uses a forbidden DTD/entity.") from exc
32
+ cases: list[Case] = []
33
+
34
+ _parse_suite(root, cases)
35
+ if not cases:
36
+ raise OpDevError("JUnit report contains no test cases; execution is unverified.")
37
+ identities = Counter((case.classname, case.name) for case in cases)
38
+ return [
39
+ replace(case, status="ambiguous") if identities[case.classname, case.name] > 1 else case
40
+ for case in cases
41
+ ]
42
+
43
+
44
+ def _parse_suite(node: Element, cases: list[Case], depth: int = 0) -> Counter[str]:
45
+ if depth > 32 or node.tag not in {"testsuites", "testsuite"}:
46
+ raise OpDevError("Unsupported JUnit suite structure or nesting beyond 32 levels.")
47
+ counts: Counter[str] = Counter()
48
+ for child in node:
49
+ if child.tag in {"testsuites", "testsuite"}:
50
+ counts.update(_parse_suite(child, cases, depth + 1))
51
+ elif child.tag == "testcase" and node.tag == "testsuite":
52
+ case = _parse_case(child)
53
+ cases.append(case)
54
+ counts[case.status] += 1
55
+ if len(cases) > MAX_CASES:
56
+ raise OpDevError("JUnit report exceeds 100000 cases.")
57
+ elif child.tag not in {"properties", "system-out", "system-err"}:
58
+ raise OpDevError(f"Unsupported JUnit element: {child.tag}.")
59
+ _validate_counts(node, counts)
60
+ return counts
61
+
62
+
63
+ def _parse_case(node: Element) -> Case:
64
+ name, classname = node.get("name", ""), node.get("classname", "")
65
+ if not name.strip() or len(name) > 10000 or len(classname) > 10000:
66
+ raise OpDevError("JUnit cases need a nonempty name and bounded identities.")
67
+ if "status" in node.attrib or "result" in node.attrib:
68
+ raise OpDevError("JUnit status/result attributes are unsupported; no pass inferred.")
69
+ tags = {part.tag for part in node}
70
+ if tags - {"failure", "error", "skipped", "properties", "system-out", "system-err"}:
71
+ raise OpDevError("Unsupported JUnit case outcome, including retry extensions.")
72
+ outcomes = tags & {"failure", "error", "skipped"}
73
+ if len(outcomes) > 1:
74
+ raise OpDevError("JUnit case has conflicting outcomes; no pass inferred.")
75
+ status = {"failure": "failed", "error": "error", "skipped": "skipped"}.get(
76
+ next(iter(outcomes), ""), "passed"
77
+ )
78
+ return Case(classname, name, status)
79
+
80
+
81
+ def _validate_counts(node: Element, counts: Counter[str]) -> None:
82
+ # Detect declared-but-missing cases and inconsistent summaries. Counts never
83
+ # substitute for individual results, and absent optional counters are fine.
84
+ expected = {
85
+ "tests": sum(counts.values()),
86
+ "failures": counts["failed"],
87
+ "errors": counts["error"],
88
+ "skipped": counts["skipped"],
89
+ }
90
+ for field, actual in expected.items():
91
+ if field in node.attrib:
92
+ value = node.attrib[field]
93
+ if (
94
+ len(value) > 10
95
+ or not value.isascii()
96
+ or not value.isdecimal()
97
+ or int(value) != actual
98
+ ):
99
+ raise OpDevError(f"JUnit {field} count disagrees with reported cases.")