reqtable 0.1.0__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.
reqtable/review.py ADDED
@@ -0,0 +1,318 @@
1
+ from __future__ import annotations
2
+
3
+ from .waivers import records
4
+
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from .baselines import (
9
+ BaselineStore,
10
+ Manifest,
11
+ current_user,
12
+ gate_roles,
13
+ load_baselines,
14
+ recompute_hash,
15
+ resolve,
16
+ )
17
+ from .core import (
18
+ ConfigError,
19
+ CsvTable,
20
+ InputError,
21
+ build_report_data,
22
+ extract_report_json,
23
+ generation_time,
24
+ )
25
+ from .signoff import (
26
+ DECISIONS,
27
+ SignOff,
28
+ approval_status,
29
+ match_decision,
30
+ match_role,
31
+ parse_date,
32
+ )
33
+
34
+
35
+ def resolve_baseline(store: BaselineStore, requested: str) -> Manifest:
36
+ return resolve(requested, store.list())
37
+
38
+
39
+ def record_signoff(
40
+ store: BaselineStore,
41
+ config: dict[str, Any],
42
+ manifest: Manifest,
43
+ role: str,
44
+ decision: str,
45
+ user: str,
46
+ note: str = "",
47
+ evidence: str | None = None,
48
+ via: str = "cli",
49
+ date: str | None = None,
50
+ ) -> tuple[SignOff, str]:
51
+ roles = gate_roles(config, manifest.gate)
52
+ record = SignOff(
53
+ baseline=manifest.name,
54
+ role=match_role(roles, role, manifest.gate),
55
+ user=user.strip(),
56
+ decision=match_decision(decision),
57
+ date=date or generation_time(),
58
+ content_hash=manifest.content_hash,
59
+ note=note,
60
+ evidence=evidence,
61
+ via=via,
62
+ recorded_by=current_user(store.input_path.resolve().parent),
63
+ )
64
+ if not record.user:
65
+ raise ConfigError("the sign-off needs a user name")
66
+ return record, store.add_signoff(manifest, record)
67
+
68
+
69
+ def require_intact(
70
+ store: BaselineStore, config: dict[str, Any], manifest: Manifest
71
+ ) -> None:
72
+ _, _, digest = recompute_hash(store, config["id_column"], manifest)
73
+ if digest != manifest.content_hash:
74
+ raise InputError(
75
+ f"baseline {manifest.name} does not match its recorded hash; refusing to record against it"
76
+ )
77
+
78
+
79
+ def sign_off(
80
+ store: BaselineStore,
81
+ config: dict[str, Any],
82
+ requested: str,
83
+ role: str,
84
+ decision: str,
85
+ user: str | None,
86
+ note: str,
87
+ evidence: str | None,
88
+ ) -> str:
89
+ manifest = resolve_baseline(store, requested)
90
+ require_intact(store, config, manifest)
91
+ who = user or current_user(store.input_path.resolve().parent)
92
+ record, where = record_signoff(
93
+ store, config, manifest, role, decision, who, note, evidence
94
+ )
95
+ return f"Recorded {record.decision} by {record.user} as {record.role} for {manifest.name} {where}"
96
+
97
+
98
+ def _first_line(text: str) -> str:
99
+ return text.splitlines()[0] if text else ""
100
+
101
+
102
+ def verify_baseline(
103
+ store: BaselineStore, config: dict[str, Any], requested: str
104
+ ) -> tuple[list[str], bool]:
105
+ manifest = resolve_baseline(store, requested)
106
+ _, _, digest = recompute_hash(store, config["id_column"], manifest)
107
+ hash_ok = digest == manifest.content_hash
108
+ lines = [
109
+ f"{manifest.name} {manifest.content_hash} "
110
+ + (
111
+ "content hash matches"
112
+ if hash_ok
113
+ else f"content hash DOES NOT MATCH (stored content hashes to {digest})"
114
+ )
115
+ ]
116
+ for waiver in manifest.waivers:
117
+ lines.append(
118
+ f"waived {waiver.check} by {waiver.user} on {waiver.date}: {waiver.reason} ({records(len(waiver.failing))})"
119
+ )
120
+ checked = store.signoffs(manifest)
121
+ for item in checked:
122
+ record = item.record
123
+ verdict = "counts" if item.counts else "does not count"
124
+ explained = item.detail and (not item.counts or item.verification == "recorded")
125
+ why = f" ({_first_line(item.detail)})" if explained else ""
126
+ lines.append(
127
+ f" {record.role} {record.user} {record.decision} {record.date} {item.verification} {verdict}{why}"
128
+ )
129
+ if not checked:
130
+ lines.append(" no sign-offs")
131
+ status = approval_status(gate_roles(config, manifest.gate), checked)
132
+ for entry in status["roles"]:
133
+ have = len(entry["positive"])
134
+ state = "complete" if have >= entry["min"] else "incomplete"
135
+ names = f" ({', '.join(entry['positive'])})" if entry["positive"] else ""
136
+ against = (
137
+ f"; against: {', '.join(entry['negative'])}" if entry["negative"] else ""
138
+ )
139
+ lines.append(
140
+ f"{entry['role']}: {have} of {entry['min']} needed, {state}{names}{against}"
141
+ )
142
+ if not status["roles"]:
143
+ lines.append(f"gate {manifest.gate} has no sign-off roles configured")
144
+ approved = hash_ok and status["approved"]
145
+ lines.append("approved" if approved else "not approved")
146
+ return lines, approved
147
+
148
+
149
+ def previous_baseline(
150
+ manifests: list[Manifest], config: dict[str, Any], manifest: Manifest
151
+ ) -> Manifest | None:
152
+ order = [gate["id"] for gate in config["gates"]]
153
+ if manifest.gate not in order:
154
+ return None
155
+ for gate_id in reversed(order[: order.index(manifest.gate)]):
156
+ siblings = [
157
+ m for m in manifests if m.gate == gate_id and m.system == manifest.system
158
+ ]
159
+ if siblings:
160
+ return max(siblings, key=lambda m: m.number)
161
+ return None
162
+
163
+
164
+ def build_package(
165
+ store: BaselineStore, config: dict[str, Any], requested: str, output_name: str
166
+ ) -> dict[str, Any]:
167
+ manifests = store.list()
168
+ manifest = resolve(requested, manifests)
169
+ id_column = config["id_column"]
170
+ table, rows, digest = recompute_hash(store, id_column, manifest)
171
+ hash_ok = digest == manifest.content_hash
172
+ if not hash_ok:
173
+ store.warn(f"baseline {manifest.name} does not match its recorded hash")
174
+ gate = next(
175
+ (entry for entry in config["gates"] if entry["id"] == manifest.gate), None
176
+ )
177
+ if gate is None:
178
+ raise ConfigError(
179
+ f"gate {manifest.gate} of baseline {manifest.name} is not configured"
180
+ )
181
+ frozen = CsvTable(
182
+ f"{manifest.name} (frozen)",
183
+ manifest.source,
184
+ table.headers,
185
+ rows,
186
+ [row[id_column].strip() for row in rows],
187
+ {row[id_column].strip(): row for row in rows},
188
+ )
189
+ checks = {check["id"]: check["description"] for check in gate.get("checks", [])}
190
+ previous = previous_baseline(manifests, config, manifest)
191
+ embedded = (
192
+ load_baselines(store, config, [previous.name], store.warn) if previous else []
193
+ )
194
+ gate_name = gate.get("name", gate["id"])
195
+ package_config = {
196
+ **config,
197
+ "title": f"{gate_name} gate package: {manifest.name}",
198
+ "document_mode": "review",
199
+ "gates": [gate],
200
+ }
201
+ data = build_report_data(frozen, package_config, output_name, baselines=embedded)
202
+ checked = store.signoffs(manifest)
203
+ roles = gate_roles(config, manifest.gate)
204
+ if previous:
205
+ data["options"]["initialCompareWith"] = f"baseline:{previous.name}"
206
+ data["decisions"] = []
207
+ data["package"] = {
208
+ "gate": {
209
+ "id": gate["id"],
210
+ "name": gate_name,
211
+ "produces": gate.get("produces", ""),
212
+ "scope": gate.get("scope", "table"),
213
+ },
214
+ "baseline": {
215
+ "name": manifest.name,
216
+ "gate": manifest.gate,
217
+ "system": manifest.system,
218
+ "created": manifest.created,
219
+ "createdBy": manifest.created_by,
220
+ "hash": manifest.content_hash,
221
+ "hashOk": hash_ok,
222
+ "source": manifest.source,
223
+ },
224
+ "previous": previous.name if previous else None,
225
+ "roles": roles,
226
+ "signoffs": [item.to_dict() for item in checked],
227
+ "approval": approval_status(roles, checked),
228
+ "waivers": [
229
+ {**waiver.to_dict(), "description": checks.get(waiver.check)}
230
+ for waiver in manifest.waivers
231
+ ],
232
+ "decisionOptions": list(DECISIONS),
233
+ }
234
+ return data
235
+
236
+
237
+ def _package_decisions(
238
+ path: str, data: dict[str, Any]
239
+ ) -> tuple[str, str, list[dict[str, Any]]]:
240
+ package = data.get("package")
241
+ baseline = package.get("baseline") if isinstance(package, dict) else None
242
+ if (
243
+ not isinstance(baseline, dict)
244
+ or not isinstance(baseline.get("name"), str)
245
+ or not isinstance(baseline.get("hash"), str)
246
+ ):
247
+ raise InputError(
248
+ f"{path}: not a gate package; generate one with --gate-package"
249
+ )
250
+ decisions = data.get("decisions", [])
251
+ if not isinstance(decisions, list):
252
+ raise InputError(f"{path}: decisions must be a list")
253
+ return baseline["name"], baseline["hash"], decisions
254
+
255
+
256
+ def import_decisions(
257
+ store: BaselineStore, config: dict[str, Any], path: str
258
+ ) -> list[str]:
259
+ data = extract_report_json(path)
260
+ name, digest, decisions = _package_decisions(path, data)
261
+ manifest = next((m for m in store.list() if m.name == name), None)
262
+ if manifest is None:
263
+ raise InputError(f"{path}: baseline {name!r} does not exist in this store")
264
+ if manifest.content_hash != digest:
265
+ raise InputError(
266
+ f"{path}: package was made for a different {name} (hash {digest}); this store has {manifest.content_hash}"
267
+ )
268
+ require_intact(store, config, manifest)
269
+ roles = gate_roles(config, manifest.gate)
270
+ pending = []
271
+ for index, entry in enumerate(decisions, start=1):
272
+ where = f"{path}: decision {index}"
273
+ if not isinstance(entry, dict) or not all(
274
+ isinstance(entry.get(key), str)
275
+ for key in ("role", "user", "decision", "date")
276
+ ):
277
+ raise InputError(f"{where} needs role, user, decision and date")
278
+ note = entry.get("note", "")
279
+ if not isinstance(note, str):
280
+ raise InputError(f"{where}: note must be text")
281
+ try:
282
+ pending.append(
283
+ (
284
+ match_role(roles, entry["role"], manifest.gate),
285
+ match_decision(entry["decision"]),
286
+ entry,
287
+ note,
288
+ )
289
+ )
290
+ except ConfigError as exc:
291
+ raise InputError(f"{where}: {exc}") from exc
292
+ parse_date(entry["date"])
293
+ seen = {item.record.key() for item in store.signoffs(manifest)}
294
+ lines = []
295
+ for role, decision, entry, note in pending:
296
+ user, date = entry["user"].strip(), parse_date(entry["date"]).isoformat()
297
+ label = f"{decision} by {user} as {role} on {date}"
298
+ probe = SignOff(
299
+ manifest.name, role, user, decision, date, manifest.content_hash
300
+ )
301
+ if probe.key() in seen:
302
+ lines.append(f"skipped {label}: already recorded")
303
+ continue
304
+ _, where = record_signoff(
305
+ store,
306
+ config,
307
+ manifest,
308
+ role,
309
+ decision,
310
+ user,
311
+ note,
312
+ Path(path).name,
313
+ via="package",
314
+ date=date,
315
+ )
316
+ seen.add(probe.key())
317
+ lines.append(f"imported {label} {where}")
318
+ return lines or [f"no decisions in {path}"]
reqtable/signoff.py ADDED
@@ -0,0 +1,179 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ from dataclasses import asdict, dataclass
5
+ from datetime import datetime
6
+ from typing import Any, Iterable, Sequence
7
+
8
+ from .core import ConfigError, InputError
9
+
10
+ SIGNOFF_FORMAT = "reqtable-signoff/1"
11
+ DECISIONS = ("Reviewed", "Changes requested", "Approved", "Rejected")
12
+ POSITIVE = frozenset({"Reviewed", "Approved"})
13
+ VIAS = ("cli", "package")
14
+ VERIFICATIONS = ("good", "unsigned", "bad", "unverifiable", "recorded")
15
+
16
+ _RECORD_TYPES: dict[str, Any] = {
17
+ "format": str,
18
+ "baseline": str,
19
+ "role": str,
20
+ "user": str,
21
+ "decision": str,
22
+ "date": str,
23
+ "content_hash": str,
24
+ "note": str,
25
+ "evidence": (str, type(None)),
26
+ "via": str,
27
+ "recorded_by": str,
28
+ }
29
+
30
+
31
+ def validate_roles(roles: Any, where: str) -> None:
32
+ if not isinstance(roles, list):
33
+ raise ConfigError(f"{where}.signoff must be an array")
34
+ seen: set[str] = set()
35
+ for index, entry in enumerate(roles):
36
+ spot = f"{where}.signoff[{index}]"
37
+ if not isinstance(entry, dict) or set(entry) != {"role", "min"}:
38
+ raise ConfigError(f"{spot} must be an object with 'role' and 'min'")
39
+ role, minimum = entry["role"], entry["min"]
40
+ if not isinstance(role, str) or not role.strip():
41
+ raise ConfigError(f"{spot}.role must be a non-empty string")
42
+ if not isinstance(minimum, int) or isinstance(minimum, bool) or minimum < 1:
43
+ raise ConfigError(f"{spot}.min must be a whole number of at least 1")
44
+ if role.strip().casefold() in seen:
45
+ raise ConfigError(f"{spot}: duplicate role {role!r}")
46
+ seen.add(role.strip().casefold())
47
+
48
+
49
+ def parse_date(text: str) -> datetime:
50
+ try:
51
+ moment = datetime.fromisoformat(text.strip().replace("Z", "+00:00"))
52
+ except ValueError as exc:
53
+ raise InputError(
54
+ f"invalid sign-off date {text!r}: expected an ISO date with offset"
55
+ ) from exc
56
+ return moment if moment.tzinfo else moment.astimezone()
57
+
58
+
59
+ def slug(text: str) -> str:
60
+ return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class SignOff:
65
+ baseline: str
66
+ role: str
67
+ user: str
68
+ decision: str
69
+ date: str
70
+ content_hash: str
71
+ note: str = ""
72
+ evidence: str | None = None
73
+ via: str = "cli"
74
+ recorded_by: str = ""
75
+ format: str = SIGNOFF_FORMAT
76
+
77
+ def to_dict(self) -> dict[str, Any]:
78
+ fields = asdict(self)
79
+ return {key: fields[key] for key in _RECORD_TYPES}
80
+
81
+ @classmethod
82
+ def from_dict(cls, data: Any) -> SignOff:
83
+ if not isinstance(data, dict) or set(data) != set(_RECORD_TYPES):
84
+ raise ValueError("sign-off has the wrong keys")
85
+ for key, kind in _RECORD_TYPES.items():
86
+ if not isinstance(data[key], kind):
87
+ raise ValueError(f"sign-off {key} has the wrong type")
88
+ if data["format"] != SIGNOFF_FORMAT:
89
+ raise ValueError(f"unsupported sign-off format {data['format']!r}")
90
+ if data["decision"] not in DECISIONS:
91
+ raise ValueError(f"unknown decision {data['decision']!r}")
92
+ if data["via"] not in VIAS:
93
+ raise ValueError(f"unknown via {data['via']!r}")
94
+ if not data["role"].strip() or not data["user"].strip():
95
+ raise ValueError("sign-off needs a role and a user")
96
+ try:
97
+ parse_date(data["date"])
98
+ except InputError as exc:
99
+ raise ValueError(str(exc)) from exc
100
+ return cls(**data)
101
+
102
+ @property
103
+ def moment(self) -> datetime:
104
+ return parse_date(self.date)
105
+
106
+ def key(self) -> tuple[str, str, str, str, datetime]:
107
+ return (
108
+ self.baseline,
109
+ self.role.casefold(),
110
+ self.user.casefold(),
111
+ self.decision,
112
+ self.moment,
113
+ )
114
+
115
+
116
+ @dataclass(frozen=True)
117
+ class CheckedSignOff:
118
+ """A sign-off with what its store could establish about it. Only counting ones feed approval."""
119
+
120
+ record: SignOff
121
+ verification: str
122
+ detail: str
123
+ counts: bool
124
+
125
+ def to_dict(self) -> dict[str, Any]:
126
+ return {
127
+ **self.record.to_dict(),
128
+ "verification": self.verification,
129
+ "detail": self.detail,
130
+ "counts": self.counts,
131
+ }
132
+
133
+
134
+ def approval_status(
135
+ roles: Sequence[dict[str, Any]], signoffs: Iterable[CheckedSignOff]
136
+ ) -> dict[str, Any]:
137
+ """Each user's latest counting decision decides; a role is complete at `min` distinct positive users."""
138
+ latest: dict[str, dict[str, SignOff]] = {}
139
+ ordered = sorted(
140
+ enumerate(s for s in signoffs if s.counts),
141
+ key=lambda pair: (pair[1].record.moment, pair[0]),
142
+ )
143
+ for _, checked in ordered:
144
+ record = checked.record
145
+ latest.setdefault(record.role.casefold(), {})[record.user.casefold()] = record
146
+ statuses = []
147
+ for entry in roles:
148
+ decided = latest.get(entry["role"].casefold(), {}).values()
149
+ statuses.append(
150
+ {
151
+ "role": entry["role"],
152
+ "min": entry["min"],
153
+ "positive": [r.user for r in decided if r.decision in POSITIVE],
154
+ "negative": [r.user for r in decided if r.decision not in POSITIVE],
155
+ }
156
+ )
157
+ approved = bool(statuses) and all(
158
+ len(status["positive"]) >= status["min"] for status in statuses
159
+ )
160
+ return {"approved": approved, "roles": statuses}
161
+
162
+
163
+ def match_role(roles: Sequence[dict[str, Any]], requested: str, gate: str) -> str:
164
+ for entry in roles:
165
+ if entry["role"].casefold() == requested.strip().casefold():
166
+ return entry["role"]
167
+ known = ", ".join(entry["role"] for entry in roles) or "none"
168
+ raise ConfigError(
169
+ f"gate {gate} has no sign-off role {requested!r}; its roles: {known}"
170
+ )
171
+
172
+
173
+ def match_decision(requested: str) -> str:
174
+ for decision in DECISIONS:
175
+ if decision.casefold() == requested.strip().casefold():
176
+ return decision
177
+ raise ConfigError(
178
+ f"unknown decision {requested!r}; use one of: {', '.join(DECISIONS)}"
179
+ )