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/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
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.")
|