okstra 0.234.0 → 0.235.0
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.
- package/dist/cli-registry.mjs +7 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
- package/dist/commands/implementation-report/implementation-report.mjs +73 -0
- package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
- package/dist/commands/trace/comparison.d.mts +39 -0
- package/dist/commands/trace/comparison.mjs +138 -0
- package/dist/commands/trace/comparison.mjs.map +1 -0
- package/dist/commands/trace/document.d.mts +8 -0
- package/dist/commands/trace/document.mjs +37 -0
- package/dist/commands/trace/document.mjs.map +1 -0
- package/dist/commands/trace/line-counts.d.mts +15 -0
- package/dist/commands/trace/line-counts.mjs +107 -0
- package/dist/commands/trace/line-counts.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +2 -1
- package/dist/commands/trace/model.mjs +13 -1
- package/dist/commands/trace/model.mjs.map +1 -1
- package/dist/commands/trace/progression.mjs +12 -7
- package/dist/commands/trace/progression.mjs.map +1 -1
- package/dist/commands/trace/task-link.d.mts +3 -0
- package/dist/commands/trace/task-link.mjs.map +1 -1
- package/dist/commands/trace/trace.mjs +66 -46
- package/dist/commands/trace/trace.mjs.map +1 -1
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +11 -5
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/types.d.mts +1 -0
- package/docs/architecture/storage-model.md +50 -0
- package/docs/cli.md +31 -15
- package/docs/project-structure-overview.md +6 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-tests-review.json +6 -0
- package/runtime/prompts/duties/test-reviewer.json +32 -0
- package/runtime/prompts/lead/report-writer.md +13 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
- package/runtime/python/okstra_ctl/code_review_census.py +38 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
- package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
- package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
- package/runtime/python/okstra_ctl/code_review_target.py +16 -6
- package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
- package/runtime/python/okstra_ctl/consumers.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +6 -26
- package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
- package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
- package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
- package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
- package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
- package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
- package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
- package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
- package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
- package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
- package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
- package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
- package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
- package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
- package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
- package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
- package/runtime/python/okstra_ctl/json_boundary.py +28 -8
- package/runtime/python/okstra_ctl/paths.py +7 -4
- package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
- package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
- package/runtime/python/okstra_ctl/render.py +4 -0
- package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
- package/runtime/python/okstra_ctl/report_finalize.py +18 -4
- package/runtime/python/okstra_ctl/report_html/render.py +46 -7
- package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
- package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
- package/runtime/python/okstra_ctl/run.py +16 -0
- package/runtime/python/okstra_ctl/stage_done.py +11 -3
- package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
- package/runtime/python/okstra_ctl/stage_map.py +3 -3
- package/runtime/python/okstra_ctl/trace_review.py +1 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
- package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
- package/runtime/python/okstra_ctl/verification_generation.py +3 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
- package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
- package/runtime/skills/okstra-code-review/SKILL.md +1 -1
- package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
- package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +31 -0
- package/runtime/skills/okstra-tdd/SKILL.md +75 -11
- package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
- package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
- package/runtime/templates/reports/html/i18n/en.json +113 -0
- package/runtime/templates/reports/html/i18n/ko.json +113 -0
- package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
- package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
- package/runtime/templates/trace/trace.template.md +2 -0
- package/runtime/validators/validate-report-views.py +4 -36
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
"""Owner-bound baseline publication and read-only resume."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import os
|
|
6
|
+
import tempfile
|
|
7
|
+
from collections.abc import Mapping
|
|
8
|
+
from datetime import datetime, timezone
|
|
9
|
+
from pathlib import Path, PurePosixPath
|
|
10
|
+
from typing import Any, Literal, TypedDict
|
|
11
|
+
|
|
12
|
+
from ..json_boundary import (
|
|
13
|
+
JsonBoundaryError, ReadBudget, load_owned_object_snapshot, write_owned_object_atomic,
|
|
14
|
+
)
|
|
15
|
+
from ..run_context import dir_flock
|
|
16
|
+
from .source import (
|
|
17
|
+
MAX_FILE_READ_BYTES, MAX_GIT_COMMAND_BYTES, MAX_GIT_TOTAL_BYTES, MAX_PATHS,
|
|
18
|
+
MAX_TOTAL_READ_BYTES, collect_source, digest_bytes, read_source_bytes,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
MAX_BASELINE_BYTES = 16 * 1024 * 1024
|
|
22
|
+
MAX_OWNER_BYTES = 8192
|
|
23
|
+
MAX_BASELINE_RESPONSE_BYTES = 64 * 1024
|
|
24
|
+
MAX_LIMITATION_SUMMARY_CHARS = 1024
|
|
25
|
+
OWNER_FIELDS = frozenset({"kind", "path", "taskKey", "runSeq", "stage", "attempt", "createdAt"})
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class ComparisonOwner(TypedDict, total=False):
|
|
29
|
+
kind: Literal["run", "trace", "task"]
|
|
30
|
+
path: str
|
|
31
|
+
taskKey: str
|
|
32
|
+
runSeq: str
|
|
33
|
+
stage: str
|
|
34
|
+
attempt: str
|
|
35
|
+
createdAt: str
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class ComparisonError(ValueError):
|
|
39
|
+
"""Comparison identity or artifact confinement does not match its owner."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def comparison_directory(project_root: Path, owner: ComparisonOwner) -> Path:
|
|
43
|
+
root = Path(project_root).resolve(strict=True)
|
|
44
|
+
if not isinstance(owner, Mapping) or set(owner) - OWNER_FIELDS:
|
|
45
|
+
raise ComparisonError("Comparison owner has unsupported fields")
|
|
46
|
+
if len(json.dumps(dict(owner), ensure_ascii=True).encode()) > MAX_OWNER_BYTES:
|
|
47
|
+
raise ComparisonError("Comparison owner exceeds its byte limit")
|
|
48
|
+
if owner.get("kind") not in {"run", "trace", "task"} or not isinstance(owner.get("path"), str):
|
|
49
|
+
raise ComparisonError("Comparison owner requires kind and path")
|
|
50
|
+
for value in owner.values():
|
|
51
|
+
if not isinstance(value, str) or not value or len(value) > 4096 or "\0" in value:
|
|
52
|
+
raise ComparisonError("Comparison owner fields must be bounded nonempty strings")
|
|
53
|
+
relative = PurePosixPath(owner["path"])
|
|
54
|
+
if relative.is_absolute() or any(part in {"..", "."} for part in relative.parts) or not relative.parts or relative.parts[0] != ".okstra":
|
|
55
|
+
raise ComparisonError("Comparison owner path must be project-relative under .okstra")
|
|
56
|
+
owner_path = root / owner["path"]
|
|
57
|
+
return (
|
|
58
|
+
owner_path.parent / f"{owner_path.stem}.comparison" if owner["kind"] == "trace"
|
|
59
|
+
else owner_path.parent / "implementation-comparison" if owner["kind"] == "task"
|
|
60
|
+
else owner_path.parent.parent / "comparison" / owner_path.stem
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _owner_and_directory(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> tuple[Path, Path, dict[str, Any]]:
|
|
65
|
+
requested_root = Path(project_root).absolute()
|
|
66
|
+
root = requested_root.resolve(strict=True)
|
|
67
|
+
canonical = comparison_directory(root, owner)
|
|
68
|
+
owner_path = root / owner["path"]
|
|
69
|
+
expected = canonical.parent if owner["kind"] == "run" else canonical
|
|
70
|
+
if comparison_dir is None:
|
|
71
|
+
directory = canonical
|
|
72
|
+
else:
|
|
73
|
+
directory = Path(comparison_dir)
|
|
74
|
+
directory = directory if directory.is_absolute() else root / directory
|
|
75
|
+
if directory.is_relative_to(requested_root):
|
|
76
|
+
directory = root / directory.relative_to(requested_root)
|
|
77
|
+
actual = directory.resolve()
|
|
78
|
+
if not actual.is_relative_to(root) or not owner_path.resolve().is_relative_to(root):
|
|
79
|
+
raise ComparisonError("Comparison path escapes its project")
|
|
80
|
+
if owner["kind"] == "run":
|
|
81
|
+
allowed = actual.is_relative_to(expected.resolve()) and actual != expected.resolve()
|
|
82
|
+
else:
|
|
83
|
+
allowed = actual == expected.resolve()
|
|
84
|
+
if not allowed:
|
|
85
|
+
raise ComparisonError("Comparison directory does not belong to its owner")
|
|
86
|
+
for path in (owner_path, directory):
|
|
87
|
+
current = root
|
|
88
|
+
for part in path.relative_to(root).parts:
|
|
89
|
+
current /= part
|
|
90
|
+
if current.is_symlink():
|
|
91
|
+
raise ComparisonError("Comparison paths must not follow symbolic links")
|
|
92
|
+
return root, actual, dict(owner)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _seal(record: dict[str, Any]) -> dict[str, Any]:
|
|
96
|
+
record["recordDigest"] = digest_bytes(json.dumps(record, sort_keys=True, ensure_ascii=True).encode())
|
|
97
|
+
return record
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _response(root: Path, directory: Path, record: dict[str, Any] | None, digest: str | None, reason: str = "", *, record_name: str = "baseline.json") -> dict[str, Any]:
|
|
101
|
+
limitations = [reason] if reason else record.get("limitations", []) if record else []
|
|
102
|
+
response = {
|
|
103
|
+
"status": record["status"] if record else "unavailable",
|
|
104
|
+
"directory": directory.relative_to(root).as_posix(),
|
|
105
|
+
("baselineRef" if record_name == "baseline.json" else "targetRef"): {
|
|
106
|
+
"path": (directory / record_name).relative_to(root).as_posix(), "digest": digest,
|
|
107
|
+
} if record else None,
|
|
108
|
+
"notesPath": (directory / "notes.json").relative_to(root).as_posix(),
|
|
109
|
+
"limitations": [], "limitationsTotal": len(limitations), "limitationsOmitted": False,
|
|
110
|
+
}
|
|
111
|
+
size = len(json.dumps(response, ensure_ascii=True).encode()) + 1
|
|
112
|
+
if size > MAX_BASELINE_RESPONSE_BYTES:
|
|
113
|
+
raise ComparisonError("Comparison response metadata exceeds its byte limit")
|
|
114
|
+
abbreviated = False
|
|
115
|
+
for limitation in limitations:
|
|
116
|
+
summary = limitation[:MAX_LIMITATION_SUMMARY_CHARS]
|
|
117
|
+
if summary != limitation:
|
|
118
|
+
summary += "..."
|
|
119
|
+
abbreviated = True
|
|
120
|
+
addition = len(json.dumps(summary, ensure_ascii=True).encode()) + (2 if response["limitations"] else 0)
|
|
121
|
+
if size + addition > MAX_BASELINE_RESPONSE_BYTES:
|
|
122
|
+
break
|
|
123
|
+
response["limitations"].append(summary)
|
|
124
|
+
size += addition
|
|
125
|
+
response["limitationsOmitted"] = abbreviated or len(response["limitations"]) < len(limitations)
|
|
126
|
+
return response
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def capture_baseline(
|
|
130
|
+
project_root: Path, source_root: Path, comparison_dir: Path | None,
|
|
131
|
+
owner: ComparisonOwner, *, baseline_ref: str = "",
|
|
132
|
+
) -> dict[str, Any]:
|
|
133
|
+
root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
|
|
134
|
+
source = Path(source_root).resolve()
|
|
135
|
+
if not isinstance(baseline_ref, str) or len(baseline_ref) > 4096 or "\0" in baseline_ref:
|
|
136
|
+
raise ComparisonError("Baseline ref is invalid")
|
|
137
|
+
directory.mkdir(parents=True, exist_ok=True)
|
|
138
|
+
with dir_flock(directory, ".comparison.lock"):
|
|
139
|
+
return _capture_source_record(root, source, directory, identity, baseline_ref)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _capture_source_record(
|
|
143
|
+
root: Path, source: Path, directory: Path, identity: dict[str, Any], requested_ref: str,
|
|
144
|
+
*, record_name: str = "baseline.json", metadata: dict[str, Any] | None = None,
|
|
145
|
+
) -> dict[str, Any]:
|
|
146
|
+
label = record_name.removesuffix(".json")
|
|
147
|
+
path = directory / record_name
|
|
148
|
+
if path.exists() or path.is_symlink():
|
|
149
|
+
response, record = _read_capture(root, directory, identity, record_name=record_name)
|
|
150
|
+
if record and (record.get("sourceRoot") != str(source) or record.get("requestedRef") != requested_ref):
|
|
151
|
+
raise ComparisonError(f"{label.capitalize()} source or reference conflicts with its original capture")
|
|
152
|
+
return response
|
|
153
|
+
record: dict[str, Any] = {
|
|
154
|
+
"schemaVersion": "1.0", "owner": identity, "projectRoot": str(root),
|
|
155
|
+
"sourceRoot": str(source), "requestedRef": requested_ref,
|
|
156
|
+
"capturedAt": datetime.now(timezone.utc).isoformat(), "status": "unavailable",
|
|
157
|
+
"limitations": ["Initial capture did not complete; current source will not replace the baseline"],
|
|
158
|
+
"files": [], "git": {}, "state": "capture-started",
|
|
159
|
+
"limits": {"paths": MAX_PATHS, "fileReadBytes": MAX_FILE_READ_BYTES,
|
|
160
|
+
"totalReadBytes": MAX_TOTAL_READ_BYTES, "gitCommandBytes": MAX_GIT_COMMAND_BYTES,
|
|
161
|
+
"gitTotalBytes": MAX_GIT_TOTAL_BYTES},
|
|
162
|
+
}
|
|
163
|
+
record.update(metadata or {})
|
|
164
|
+
write_owned_object_atomic(path, _seal(dict(record)), artifact=f"implementation comparison {label}")
|
|
165
|
+
try:
|
|
166
|
+
with tempfile.TemporaryDirectory(prefix=f".{label}-", dir=directory) as temporary:
|
|
167
|
+
staging = Path(temporary)
|
|
168
|
+
collected = collect_source(root, source, requested_ref, staging)
|
|
169
|
+
for name in ("git", "contents"):
|
|
170
|
+
destination = directory / name
|
|
171
|
+
if destination.exists() or destination.is_symlink():
|
|
172
|
+
raise ComparisonError(f"{label.capitalize()} content destination already exists")
|
|
173
|
+
os.replace(staging / name, destination)
|
|
174
|
+
record.update(collected)
|
|
175
|
+
except (OSError, ValueError) as exc:
|
|
176
|
+
record.update({"status": "unavailable", "limitations": [f"Initial {label} capture failed: {exc}"]})
|
|
177
|
+
record["state"] = "captured"
|
|
178
|
+
write_owned_object_atomic(path, _seal(record), artifact=f"implementation comparison {label}")
|
|
179
|
+
return _read_capture(root, directory, identity, record_name=record_name)[0]
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def read_baseline_status(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> dict[str, Any]:
|
|
183
|
+
root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
|
|
184
|
+
if not (directory / "baseline.json").exists():
|
|
185
|
+
return _response(root, directory, None, None, "Baseline was not captured")
|
|
186
|
+
with dir_flock(directory, ".comparison.lock"):
|
|
187
|
+
return _read_capture(root, directory, identity)[0]
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def _read_capture(
|
|
191
|
+
root: Path, directory: Path, owner: dict[str, Any], *,
|
|
192
|
+
record_name: str = "baseline.json", budget: ReadBudget | None = None,
|
|
193
|
+
) -> tuple[dict[str, Any], dict[str, Any] | None]:
|
|
194
|
+
label = record_name.removesuffix(".json")
|
|
195
|
+
path = directory / record_name
|
|
196
|
+
if not path.exists():
|
|
197
|
+
return _response(root, directory, None, None, f"{label.capitalize()} was not captured", record_name=record_name), None
|
|
198
|
+
try:
|
|
199
|
+
if path.is_symlink():
|
|
200
|
+
raise ValueError("Baseline record is a symbolic link")
|
|
201
|
+
snapshot = load_owned_object_snapshot(path, artifact="implementation comparison baseline", max_bytes=MAX_BASELINE_BYTES, budget=budget)
|
|
202
|
+
record = snapshot.value
|
|
203
|
+
if record.get("owner") != owner or record.get("projectRoot") != str(root):
|
|
204
|
+
raise ComparisonError("Baseline owner conflicts with its original capture")
|
|
205
|
+
unsealed = {key: value for key, value in record.items() if key != "recordDigest"}
|
|
206
|
+
expected = digest_bytes(json.dumps(unsealed, sort_keys=True, ensure_ascii=True).encode())
|
|
207
|
+
if record.get("recordDigest") != expected or record.get("schemaVersion") != "1.0":
|
|
208
|
+
raise ValueError("Baseline record digest or schema is invalid")
|
|
209
|
+
if record.get("status") not in {"complete", "partial", "unavailable"}:
|
|
210
|
+
raise ValueError("Baseline status is invalid")
|
|
211
|
+
_verify_contents(directory, record, budget=budget)
|
|
212
|
+
return _response(root, directory, record, digest_bytes(snapshot.raw_bytes), record_name=record_name), record
|
|
213
|
+
except ComparisonError:
|
|
214
|
+
raise
|
|
215
|
+
except (JsonBoundaryError, OSError, ValueError, KeyError, TypeError) as exc:
|
|
216
|
+
return _response(root, directory, None, None, f"Preserved {label} is unavailable: {exc}", record_name=record_name), None
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _verify_contents(directory: Path, record: dict[str, Any], *, budget: ReadBudget | None = None) -> None:
|
|
220
|
+
files = record.get("files")
|
|
221
|
+
if not isinstance(files, list) or len(files) > MAX_PATHS:
|
|
222
|
+
raise ValueError("Baseline source inventory is invalid")
|
|
223
|
+
source_budget = ReadBudget(MAX_TOTAL_READ_BYTES)
|
|
224
|
+
checked: set[str] = set()
|
|
225
|
+
for row in files:
|
|
226
|
+
relative = row.get("contentPath")
|
|
227
|
+
if relative is None or relative in checked:
|
|
228
|
+
continue
|
|
229
|
+
if not isinstance(relative, str) or relative != f"contents/{row.get('digest')}.txt":
|
|
230
|
+
raise ValueError("Baseline content reference is invalid")
|
|
231
|
+
body, _, problem = read_source_bytes(directory, relative, source_budget, shared_budget=budget)
|
|
232
|
+
if problem or body is None or digest_bytes(body) != row.get("digest"):
|
|
233
|
+
raise ValueError("Preserved source content changed or is incomplete")
|
|
234
|
+
checked.add(relative)
|
|
235
|
+
outputs = record.get("git", {})
|
|
236
|
+
git_bytes = 0
|
|
237
|
+
git_budget = ReadBudget(MAX_GIT_TOTAL_BYTES)
|
|
238
|
+
for output in outputs.values():
|
|
239
|
+
command_bytes = 0
|
|
240
|
+
for name in ("stdout", "stderr"):
|
|
241
|
+
reference = output[name]
|
|
242
|
+
relative = reference["path"]
|
|
243
|
+
if not isinstance(relative, str) or len(PurePosixPath(relative).parts) != 2 or PurePosixPath(relative).parts[0] != "git":
|
|
244
|
+
raise ValueError("Baseline Git content reference is invalid")
|
|
245
|
+
path = directory / relative
|
|
246
|
+
if path.is_symlink() or path.stat().st_size != reference["bytes"]:
|
|
247
|
+
raise ValueError("Preserved Git output changed")
|
|
248
|
+
command_bytes += reference["bytes"]
|
|
249
|
+
git_bytes += reference["bytes"]
|
|
250
|
+
if command_bytes > MAX_GIT_COMMAND_BYTES or git_bytes > MAX_GIT_TOTAL_BYTES:
|
|
251
|
+
raise ValueError("Preserved Git output exceeds its byte budget")
|
|
252
|
+
body, _, problem = read_source_bytes(directory, relative, git_budget, file_limit=MAX_GIT_COMMAND_BYTES, shared_budget=budget)
|
|
253
|
+
if problem or body is None or digest_bytes(body) != reference["storedDigest"]:
|
|
254
|
+
raise ValueError("Preserved Git output changed")
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""Reuse existing explanations only when their stored scope matches preserved bytes."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import base64
|
|
5
|
+
import binascii
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import re
|
|
8
|
+
from typing import Any, Mapping
|
|
9
|
+
|
|
10
|
+
from ..business_flow.contracts import artifact_path, fingerprint, schema_definition
|
|
11
|
+
from ..final_report_schema import validate
|
|
12
|
+
from ..json_boundary import ReadBudget, parse_owned_snapshot
|
|
13
|
+
from .baseline import ComparisonError
|
|
14
|
+
from .inputs import _ChangedInput, _artifact_bytes
|
|
15
|
+
from .model import MAX_RECORDS
|
|
16
|
+
from .source import MAX_FILE_READ_BYTES, MAX_GIT_COMMAND_BYTES, digest_bytes
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _stored_body_matches(encoded: object, expected_digest: str, maximum: int) -> bool:
|
|
20
|
+
if not isinstance(encoded, str) or len(encoded) > 4 * ((maximum + 2) // 3):
|
|
21
|
+
return False
|
|
22
|
+
try:
|
|
23
|
+
body = base64.b64decode(encoded, validate=True)
|
|
24
|
+
except (ValueError, binascii.Error):
|
|
25
|
+
return False
|
|
26
|
+
return len(body) <= maximum and digest_bytes(body) == expected_digest
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _matching_snapshot(capture: Mapping[str, Any] | None, snapshot: Mapping[str, Any]) -> bool:
|
|
30
|
+
if not capture or capture.get("status") != "complete" or not capture.get("completeInventory") or snapshot.get("gaps"):
|
|
31
|
+
return False
|
|
32
|
+
if capture.get("sourceRoot") != snapshot.get("root") or capture.get("head") != snapshot.get("head"):
|
|
33
|
+
return False
|
|
34
|
+
rows = capture.get("files", [])
|
|
35
|
+
if any(row.get("status") != "complete" for row in rows):
|
|
36
|
+
return False
|
|
37
|
+
files = {row["path"]: row.get("digest") for row in rows}
|
|
38
|
+
index = capture.get("git", {}).get("index-before", {})
|
|
39
|
+
digest = index.get("stdout", {}).get("storedDigest")
|
|
40
|
+
if not index.get("complete") or index.get("returncode") != 0 or not digest:
|
|
41
|
+
return False
|
|
42
|
+
if (files != snapshot.get("files") or digest != snapshot.get("indexDigest")
|
|
43
|
+
or snapshot.get("digest") != fingerprint({"head": capture["head"], "files": files, "index": digest})):
|
|
44
|
+
return False
|
|
45
|
+
dirty = snapshot.get("dirty")
|
|
46
|
+
if not isinstance(dirty, Mapping) or any(path not in files for path in dirty):
|
|
47
|
+
return False
|
|
48
|
+
return (_stored_body_matches(snapshot.get("indexPatch"), digest, MAX_GIT_COMMAND_BYTES)
|
|
49
|
+
and all(_stored_body_matches(body, files[path], MAX_FILE_READ_BYTES) for path, body in dirty.items()))
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def read_matching_business_explanations(
|
|
53
|
+
root: Path, source: Mapping[str, Any], captures: Mapping[str, tuple[Path, dict[str, Any] | None]], *,
|
|
54
|
+
budget: ReadBudget, fingerprints: dict[str, str | None],
|
|
55
|
+
) -> tuple[list[dict[str, Any]], list[str]]:
|
|
56
|
+
rows: list[dict[str, Any]] = []
|
|
57
|
+
limitations: list[str] = []
|
|
58
|
+
sidecar = source["path"] + ".business-flow.json"
|
|
59
|
+
try:
|
|
60
|
+
raw = _artifact_bytes(root, sidecar, fingerprints, budget)
|
|
61
|
+
if raw is None:
|
|
62
|
+
return rows, limitations
|
|
63
|
+
links = parse_owned_snapshot(root / sidecar, raw, artifact="business flow taskLink").value
|
|
64
|
+
executions = links.get("executions")
|
|
65
|
+
if not isinstance(executions, list) or len(executions) > MAX_RECORDS:
|
|
66
|
+
raise ComparisonError("Existing business explanation list exceeds its limit or is invalid")
|
|
67
|
+
if validate(links, schema_definition("taskLink")) or links.get("taskKey") != source["owner"].get("taskKey"):
|
|
68
|
+
raise ComparisonError("Existing business explanation links do not match this task")
|
|
69
|
+
seen: set[str] = set()
|
|
70
|
+
for link in executions:
|
|
71
|
+
identifier = link["id"]
|
|
72
|
+
if not identifier or len(identifier) > 128 or re.fullmatch(r"[a-z0-9-]+", identifier) is None:
|
|
73
|
+
limitations.append("Existing business explanation has no valid stored execution identity")
|
|
74
|
+
continue
|
|
75
|
+
if identifier in seen:
|
|
76
|
+
limitations.append("A duplicate existing business explanation reference was ignored")
|
|
77
|
+
continue
|
|
78
|
+
seen.add(identifier)
|
|
79
|
+
path = artifact_path(root, "executions", identifier, "execution.json")
|
|
80
|
+
relative = path.relative_to(root).as_posix()
|
|
81
|
+
body = _artifact_bytes(root, relative, fingerprints, budget)
|
|
82
|
+
if body is None:
|
|
83
|
+
limitations.append("Existing business explanation execution is missing")
|
|
84
|
+
continue
|
|
85
|
+
execution = parse_owned_snapshot(path, body, artifact="business flow execution").value
|
|
86
|
+
projects = execution.get("projects")
|
|
87
|
+
if not isinstance(projects, list) or len(projects) != 1 or validate(execution, schema_definition("execution")):
|
|
88
|
+
limitations.append("Existing business explanation has a different project scope or invalid record")
|
|
89
|
+
continue
|
|
90
|
+
artifact_digests = execution.get("sourceArtifactDigests")
|
|
91
|
+
artifact_digest = artifact_digests.get(str((root / source["path"]).resolve())) if isinstance(artifact_digests, Mapping) else None
|
|
92
|
+
if (execution.get("id") != identifier or execution.get("status") not in {"complete", "partial"}
|
|
93
|
+
or artifact_digest != source["digest"] or execution["request"].get("task_key") != source["owner"].get("taskKey")):
|
|
94
|
+
limitations.append("Existing business explanation is not bound to this report original")
|
|
95
|
+
continue
|
|
96
|
+
matches = [side for side, (_, capture) in captures.items() if _matching_snapshot(capture, projects[0])]
|
|
97
|
+
if not matches:
|
|
98
|
+
limitations.append("Existing business explanation source scope or content digest does not match preserved comparison bytes")
|
|
99
|
+
continue
|
|
100
|
+
result = execution.get("result", {})
|
|
101
|
+
summary = result.get("summary")
|
|
102
|
+
if not isinstance(summary, str) or not summary or len(summary.encode()) > 64 * 1024:
|
|
103
|
+
limitations.append("Existing business explanation summary is missing or exceeds its byte limit")
|
|
104
|
+
continue
|
|
105
|
+
for side in matches:
|
|
106
|
+
if len(rows) >= MAX_RECORDS:
|
|
107
|
+
limitations.append("Additional existing business explanations were omitted at the evidence row limit")
|
|
108
|
+
return rows, limitations
|
|
109
|
+
identity = f"business:{identifier}:{side}"
|
|
110
|
+
rows.append({"id": identity, "recordId": identity, "kind": "document", "origin": "existing-document",
|
|
111
|
+
"support": "partial", "targetBound": False, "side": side, "label": result.get("title", identifier),
|
|
112
|
+
"summary": summary, "recordPath": relative, "recordDigest": digest_bytes(body),
|
|
113
|
+
"limitations": ["Reused stored explanation with matching source scope; its narrative and execution claims were not independently reverified"]})
|
|
114
|
+
except _ChangedInput:
|
|
115
|
+
raise
|
|
116
|
+
except (OSError, ValueError, KeyError, TypeError) as exc:
|
|
117
|
+
limitations.append(f"Existing business explanation was not reused: {exc}")
|
|
118
|
+
return rows, list(dict.fromkeys(limitations))
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Read recorded commit content without reconstructing a working-tree baseline."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
import os
|
|
6
|
+
from pathlib import Path, PurePosixPath
|
|
7
|
+
import re
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from .source import EXCLUDED_PARTS, MAX_FILE_READ_BYTES, MAX_PATHS, GitCollector, digest_bytes
|
|
11
|
+
|
|
12
|
+
_COMMIT_ID = re.compile(r"(?:[a-f0-9]{40}|[a-f0-9]{64})\Z")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class RecordedCommitSource:
|
|
17
|
+
record: dict[str, Any]
|
|
18
|
+
contents: dict[str, bytes]
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def read_recorded_commit_source(root: Path, commit: str, *, git: GitCollector) -> RecordedCommitSource:
|
|
22
|
+
record: dict[str, Any] = {
|
|
23
|
+
"head": None, "baselineCommit": commit, "files": [], "completeInventory": False,
|
|
24
|
+
"status": "unavailable", "reconstruction": "recorded-commit", "dirtyState": "unknown",
|
|
25
|
+
"limitations": ["Reconstructed commit content; original uncommitted state is unknown"],
|
|
26
|
+
"excludedParts": sorted(EXCLUDED_PARTS),
|
|
27
|
+
"scope": {"workingTreeText": "unavailable", "index": "unavailable",
|
|
28
|
+
"commitTree": "full-within-read-limits"},
|
|
29
|
+
}
|
|
30
|
+
contents: dict[str, bytes] = {}
|
|
31
|
+
if not isinstance(commit, str) or not _COMMIT_ID.fullmatch(commit):
|
|
32
|
+
record["limitations"].append("Original recorded commit identity is unavailable")
|
|
33
|
+
return RecordedCommitSource(record, contents)
|
|
34
|
+
resolved = git.run(root, f"recorded-{commit}", "--no-replace-objects", "rev-parse", "--verify", "--end-of-options", f"{commit}^{{commit}}")
|
|
35
|
+
if not resolved.complete or resolved.returncode != 0 or resolved.stdout.strip() != commit.encode():
|
|
36
|
+
record["limitations"].append("Original recorded commit cannot be read")
|
|
37
|
+
return RecordedCommitSource(record, contents)
|
|
38
|
+
record["head"] = commit
|
|
39
|
+
prefix_result = git.run(root, f"prefix-{commit}", "--no-replace-objects", "rev-parse", "--show-prefix")
|
|
40
|
+
if not prefix_result.complete or prefix_result.returncode != 0:
|
|
41
|
+
record["limitations"].append("Original recorded project scope cannot be resolved")
|
|
42
|
+
return RecordedCommitSource(record, contents)
|
|
43
|
+
prefix = os.fsdecode(prefix_result.stdout.removesuffix(b"\n"))
|
|
44
|
+
prefix_path = PurePosixPath(prefix)
|
|
45
|
+
if prefix and (prefix_path.is_absolute() or any(part in {".", ".."} for part in prefix_path.parts)
|
|
46
|
+
or prefix_path.as_posix() + "/" != prefix):
|
|
47
|
+
record["limitations"].append("Original recorded project scope is not a relative directory")
|
|
48
|
+
return RecordedCommitSource(record, contents)
|
|
49
|
+
tree = f"{commit}:{prefix}" if prefix else commit
|
|
50
|
+
listing = git.run(root, f"tree-{commit}", "--no-replace-objects", "ls-tree", "-r", "-l", "-z", "--full-tree", tree)
|
|
51
|
+
if not listing.complete or listing.returncode != 0:
|
|
52
|
+
record["limitations"].append(f"Recorded commit inventory is incomplete: {listing.reason or 'Git tree read failed'}")
|
|
53
|
+
return RecordedCommitSource(record, contents)
|
|
54
|
+
record["completeInventory"] = True
|
|
55
|
+
for raw in listing.stdout.split(b"\0"):
|
|
56
|
+
if not raw:
|
|
57
|
+
continue
|
|
58
|
+
metadata, separator, name = raw.partition(b"\t")
|
|
59
|
+
fields = metadata.split()
|
|
60
|
+
path = os.fsdecode(name)
|
|
61
|
+
parts = PurePosixPath(path).parts
|
|
62
|
+
if not separator or len(fields) != 4 or not parts or PurePosixPath(path).is_absolute() or any(p in {".", ".."} for p in parts):
|
|
63
|
+
record["completeInventory"] = False
|
|
64
|
+
record["limitations"].append("Recorded commit contains an invalid tree entry")
|
|
65
|
+
break
|
|
66
|
+
if any(part in EXCLUDED_PARTS for part in parts):
|
|
67
|
+
continue
|
|
68
|
+
if len(record["files"]) >= MAX_PATHS:
|
|
69
|
+
record["completeInventory"] = False
|
|
70
|
+
record["limitations"].append("Recorded commit source path limit reached")
|
|
71
|
+
break
|
|
72
|
+
mode, kind, object_id, raw_size = fields
|
|
73
|
+
row: dict[str, Any] = {
|
|
74
|
+
"path": path, "tracked": True, "mode": int(mode, 8), "digest": None,
|
|
75
|
+
"contentPath": None, "status": "partial", "object": object_id.decode("ascii"),
|
|
76
|
+
}
|
|
77
|
+
record["files"].append(row)
|
|
78
|
+
if kind != b"blob" or mode not in {b"100644", b"100755"}:
|
|
79
|
+
row.update({"kind": "symlink" if mode == b"120000" else "submodule",
|
|
80
|
+
"reason": "Recorded source is not a regular file; it was not followed"})
|
|
81
|
+
continue
|
|
82
|
+
row["size"] = int(raw_size)
|
|
83
|
+
if row["size"] > MAX_FILE_READ_BYTES:
|
|
84
|
+
row["reason"] = "Recorded source exceeds the file read budget"
|
|
85
|
+
continue
|
|
86
|
+
content = git.run(root, f"blob-{object_id.decode('ascii')}", "--no-replace-objects", "cat-file", "blob", object_id.decode("ascii"))
|
|
87
|
+
if not content.complete or content.returncode != 0 or len(content.stdout) != row["size"]:
|
|
88
|
+
row["reason"] = f"Recorded source content is incomplete: {content.reason or 'Git blob read failed'}"
|
|
89
|
+
continue
|
|
90
|
+
body = content.stdout
|
|
91
|
+
row.update({"digest": digest_bytes(body), "status": "complete"})
|
|
92
|
+
try:
|
|
93
|
+
is_text = "\0" not in body.decode("utf-8")
|
|
94
|
+
except UnicodeDecodeError:
|
|
95
|
+
is_text = False
|
|
96
|
+
row["kind"] = "text" if is_text else "binary"
|
|
97
|
+
if is_text:
|
|
98
|
+
contents[path] = body
|
|
99
|
+
for row in record["files"]:
|
|
100
|
+
if row.get("reason"):
|
|
101
|
+
record["limitations"].append(f"{row['path']}: {row['reason']}")
|
|
102
|
+
record.update({"status": "partial", "bytesPreserved": sum(map(len, contents.values())),
|
|
103
|
+
"gitBytesRead": git.budget.bytes_read})
|
|
104
|
+
return RecordedCommitSource(record, contents)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def recorded_commit_is_ancestor(root: Path, ancestor: str, descendant: str, *, git: GitCollector) -> bool | None:
|
|
108
|
+
if not all(isinstance(value, str) and _COMMIT_ID.fullmatch(value) for value in (ancestor, descendant)):
|
|
109
|
+
return None
|
|
110
|
+
result = git.run(root, f"ancestry-{ancestor}-{descendant}", "--no-replace-objects", "merge-base", "--is-ancestor", ancestor, descendant)
|
|
111
|
+
if not result.complete or result.returncode not in {0, 1}:
|
|
112
|
+
return None
|
|
113
|
+
return result.returncode == 0
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Render validated comparison data as a self-contained reader document."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
from okstra_vendor.jinja2 import Environment, StrictUndefined, select_autoescape
|
|
7
|
+
|
|
8
|
+
from ..i18n import HTML_DICTIONARY_REL, load_dictionary
|
|
9
|
+
from ..paths import find_asset_root
|
|
10
|
+
from ..report_html.filters import paragraphs
|
|
11
|
+
from ..report_template_loader import report_template_loader
|
|
12
|
+
from .baseline import ComparisonError
|
|
13
|
+
from .source import digest_bytes
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def render_comparison_html(data: dict[str, Any]) -> str:
|
|
17
|
+
"""Read packaged assets and render data without publishing or reclassifying it.
|
|
18
|
+
|
|
19
|
+
Fixed labels use Korean for ``ko`` and English otherwise. Authored prose
|
|
20
|
+
retains the source language; the comparison assembler owns its evidence levels.
|
|
21
|
+
"""
|
|
22
|
+
template = ("templates", "reports", "html", "implementation-comparison.template.html")
|
|
23
|
+
root = find_asset_root(template)
|
|
24
|
+
if root is None:
|
|
25
|
+
raise ComparisonError("Comparison HTML templates are unavailable")
|
|
26
|
+
templates = root / "templates" / "reports"
|
|
27
|
+
language = "ko" if data["source"]["language"] == "ko" else "en"
|
|
28
|
+
dictionary = load_dictionary(language, HTML_DICTIONARY_REL)
|
|
29
|
+
environment = Environment(
|
|
30
|
+
loader=report_template_loader(templates),
|
|
31
|
+
autoescape=select_autoescape(("html",)),
|
|
32
|
+
undefined=StrictUndefined,
|
|
33
|
+
)
|
|
34
|
+
environment.filters["paragraphs"] = paragraphs
|
|
35
|
+
changes = data["changes"]
|
|
36
|
+
assets = templates / "html" / "assets"
|
|
37
|
+
return environment.get_template("html/implementation-comparison.template.html").render(
|
|
38
|
+
data=data, language=language, labels=dictionary["comparison"],
|
|
39
|
+
affected=sorted({value for row in changes for value in row.get("affected", [])}),
|
|
40
|
+
stages=sorted({str(value) for row in changes for value in row.get("stages", [])}
|
|
41
|
+
| {str(row["stage"]) for row in data.get("stageCards", [])}),
|
|
42
|
+
changes_by_id={row["id"]: row for row in changes},
|
|
43
|
+
change_anchors={row["id"]: "change-" + digest_bytes(row["id"].encode()) for row in changes},
|
|
44
|
+
evidence_anchors={row["id"]: "evidence-" + digest_bytes(row["id"].encode()) for row in data["evidence"]},
|
|
45
|
+
evidence_by_id={row["id"]: row for row in data["evidence"]},
|
|
46
|
+
css=(assets / "base.css").read_text(encoding="utf-8")
|
|
47
|
+
+ "\n" + (assets / "implementation-comparison.css").read_text(encoding="utf-8"),
|
|
48
|
+
js=(assets / "implementation-comparison.js").read_text(encoding="utf-8"),
|
|
49
|
+
)
|