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/baselines.py ADDED
@@ -0,0 +1,920 @@
1
+ from __future__ import annotations
2
+
3
+ import getpass
4
+ import hashlib
5
+ import json
6
+ import os
7
+ import re
8
+ import shutil
9
+ import subprocess
10
+ import sys
11
+ import tempfile
12
+ from abc import ABC, abstractmethod
13
+ from dataclasses import asdict, dataclass
14
+ from functools import cached_property
15
+ from pathlib import Path
16
+ from typing import Any, Callable, Iterable, Sequence
17
+
18
+ from .core import (
19
+ ConfigError,
20
+ ReqtableError,
21
+ CsvSource,
22
+ CsvTable,
23
+ InputError,
24
+ OutputError,
25
+ atomic_write_text,
26
+ generation_time,
27
+ prepare_trace_table,
28
+ read_csv_source,
29
+ )
30
+ from .signoff import CheckedSignOff, SignOff, approval_status, slug
31
+ from .waivers import Waiver
32
+ from .xlsx import block_to_csv, is_xlsx
33
+
34
+ HASH_FORMAT = "reqtable-baseline/1"
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Gate:
39
+ id: str
40
+ name: str
41
+ produces: str
42
+ scope: str
43
+ includes: tuple[str, ...]
44
+ captures_status: bool
45
+
46
+ @classmethod
47
+ def from_config(cls, gate: dict[str, Any]) -> Gate:
48
+ return cls(
49
+ id=gate["id"],
50
+ name=gate.get("name", gate["id"]),
51
+ produces=gate.get("produces", ""),
52
+ scope=gate.get("scope", "table"),
53
+ includes=tuple(gate.get("includes", ("Requirement", "System"))),
54
+ captures_status=gate.get("captures_status", False),
55
+ )
56
+
57
+
58
+ def links(cell: str) -> list[str]:
59
+ return [part.strip() for part in cell.split(";") if part.strip()]
60
+
61
+
62
+ def record_type(row: dict[str, str]) -> str:
63
+ return row.get("Type", "").strip() or "Requirement"
64
+
65
+
66
+ def _subtree(rows: Sequence[dict[str, str]], id_column: str, system: str) -> set[str]:
67
+ children: dict[str, list[str]] = {}
68
+ for row in rows:
69
+ if record_type(row) == "System":
70
+ for parent in links(row.get("Part of", "")):
71
+ children.setdefault(parent, []).append(row[id_column].strip())
72
+ found, pending = {system}, [system]
73
+ while pending:
74
+ for child in children.get(pending.pop(), []):
75
+ if child not in found:
76
+ found.add(child)
77
+ pending.append(child)
78
+ return found
79
+
80
+
81
+ def select_scope(
82
+ rows: Sequence[dict[str, str]],
83
+ id_column: str,
84
+ system: str | None,
85
+ includes: Iterable[str],
86
+ ) -> list[dict[str, str]]:
87
+ wanted = set(includes)
88
+ included = [row for row in rows if record_type(row) in wanted]
89
+ if system is None:
90
+ return included
91
+ subtree = _subtree(rows, id_column, system)
92
+ requirements = [
93
+ row
94
+ for row in included
95
+ if record_type(row) == "Requirement"
96
+ and subtree.intersection(links(row.get("Allocated to", "")))
97
+ ]
98
+ tests = {test for row in requirements for test in links(row.get("Verified by", ""))}
99
+ chosen_tests = [
100
+ row
101
+ for row in included
102
+ if record_type(row) == "Test" and row[id_column].strip() in tests
103
+ ]
104
+ plans = {plan for row in chosen_tests for plan in links(row.get("Test plan", ""))}
105
+ kept = {id(row) for row in requirements + chosen_tests}
106
+
107
+ def keep(row: dict[str, str]) -> bool:
108
+ kind = record_type(row)
109
+ if kind == "System":
110
+ return row[id_column].strip() in subtree
111
+ if kind == "Test plan":
112
+ return row[id_column].strip() in plans
113
+ if kind in {"Requirement", "Test"}:
114
+ return id(row) in kept
115
+ return True
116
+
117
+ return [row for row in included if keep(row)]
118
+
119
+
120
+ def content_hash(
121
+ headers: Sequence[str],
122
+ rows_in_scope: Iterable[dict[str, str]],
123
+ system: str | None,
124
+ includes: Iterable[str],
125
+ captures_status: bool,
126
+ status_columns: Iterable[str],
127
+ ) -> str:
128
+ skipped = set() if captures_status else set(status_columns)
129
+ hashed = [header for header in headers if header not in skipped]
130
+ payload = [
131
+ HASH_FORMAT,
132
+ {
133
+ "system": system or None,
134
+ "includes": sorted(includes),
135
+ "status": captures_status,
136
+ },
137
+ hashed,
138
+ [
139
+ [
140
+ row.get(header, "").replace("\r\n", "\n").replace("\r", "\n")
141
+ for header in hashed
142
+ ]
143
+ for row in rows_in_scope
144
+ ],
145
+ ]
146
+ text = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
147
+ return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
148
+
149
+
150
+ def find_gate(config: dict[str, Any], gate_id: str) -> Gate:
151
+ for gate in config["gates"]:
152
+ if gate["id"] == gate_id:
153
+ return Gate.from_config(gate)
154
+ known = ", ".join(gate["id"] for gate in config["gates"]) or "none"
155
+ raise ConfigError(f"unknown gate {gate_id!r}; configured gates: {known}")
156
+
157
+
158
+ @dataclass(frozen=True)
159
+ class BaselineName:
160
+ """number None means 'the latest' and only occurs in a requested name."""
161
+
162
+ gate: str
163
+ number: int | None = 1
164
+ system: str | None = None
165
+
166
+ @classmethod
167
+ def parse(cls, text: str) -> BaselineName:
168
+ head, _, system = text.partition("/")
169
+ match = re.fullmatch(r"(.+?)(?:-(\d+))?", head)
170
+ if not match:
171
+ raise InputError(f"invalid baseline name {text!r}")
172
+ number = int(match.group(2)) if match.group(2) else None
173
+ return cls(match.group(1), number, system or None)
174
+
175
+ def __str__(self) -> str:
176
+ assert self.number is not None
177
+ gate = self.gate if self.number == 1 else f"{self.gate}-{self.number}"
178
+ return f"{gate}/{self.system}" if self.system else gate
179
+
180
+
181
+ _MANIFEST_TYPES: dict[str, Any] = {
182
+ "format": str,
183
+ "name": str,
184
+ "gate": str,
185
+ "supersedes": (str, type(None)),
186
+ "system": (str, type(None)),
187
+ "includes": list,
188
+ "captures_status": bool,
189
+ "status_columns": list,
190
+ "content_hash": str,
191
+ "source": str,
192
+ "created": str,
193
+ "created_by": str,
194
+ }
195
+
196
+
197
+ @dataclass(frozen=True)
198
+ class Manifest:
199
+ name: str
200
+ gate: str
201
+ supersedes: str | None
202
+ system: str | None
203
+ includes: list[str]
204
+ captures_status: bool
205
+ status_columns: list[str]
206
+ content_hash: str
207
+ source: str
208
+ created: str
209
+ created_by: str
210
+ waivers: tuple[Waiver, ...] = ()
211
+ format: str = HASH_FORMAT
212
+
213
+ @property
214
+ def number(self) -> int:
215
+ parsed = BaselineName.parse(self.name).number
216
+ return 1 if parsed is None else parsed
217
+
218
+ def to_dict(self) -> dict[str, Any]:
219
+ fields = asdict(self)
220
+ return {
221
+ **{key: fields[key] for key in _MANIFEST_TYPES},
222
+ "waivers": [waiver.to_dict() for waiver in self.waivers],
223
+ }
224
+
225
+ @classmethod
226
+ def from_dict(cls, data: Any) -> Manifest:
227
+ if not isinstance(data, dict) or set(data) - {"waivers"} != set(
228
+ _MANIFEST_TYPES
229
+ ):
230
+ raise ValueError("manifest has the wrong keys")
231
+ waivers = data.get("waivers", [])
232
+ if not isinstance(waivers, list):
233
+ raise ValueError("manifest waivers must be a list")
234
+ for key, kind in _MANIFEST_TYPES.items():
235
+ if not isinstance(data[key], kind):
236
+ raise ValueError(f"manifest {key} has the wrong type")
237
+ if data["format"] != HASH_FORMAT:
238
+ raise ValueError(f"unsupported manifest format {data['format']!r}")
239
+ for key in ("includes", "status_columns"):
240
+ if not all(isinstance(item, str) for item in data[key]):
241
+ raise ValueError(f"manifest {key} must hold strings")
242
+ parsed = BaselineName.parse(data["name"])
243
+ if (
244
+ parsed.gate != data["gate"]
245
+ or parsed.system != data["system"]
246
+ or parsed.number == 0
247
+ ):
248
+ raise ValueError("manifest name does not match its gate and system")
249
+ return cls(
250
+ **{key: data[key] for key in _MANIFEST_TYPES},
251
+ waivers=tuple(Waiver.from_dict(item) for item in waivers),
252
+ )
253
+
254
+
255
+ def next_name(
256
+ existing: Iterable[Manifest], gate: str, system: str | None
257
+ ) -> tuple[BaselineName, str | None]:
258
+ siblings = [m for m in existing if m.gate == gate and m.system == system]
259
+ if not siblings:
260
+ return BaselineName(gate, 1, system), None
261
+ latest = max(siblings, key=lambda m: m.number)
262
+ return BaselineName(gate, latest.number + 1, system), latest.name
263
+
264
+
265
+ def resolve(requested: str, manifests: Sequence[Manifest]) -> Manifest:
266
+ wanted = BaselineName.parse(requested)
267
+ candidates = [
268
+ m for m in manifests if m.gate == wanted.gate and m.system == wanted.system
269
+ ]
270
+ if wanted.number is not None:
271
+ candidates = [m for m in candidates if m.number == wanted.number]
272
+ if not candidates:
273
+ known = ", ".join(m.name for m in manifests) or "none"
274
+ raise InputError(f"unknown baseline {requested!r}; existing baselines: {known}")
275
+ return max(candidates, key=lambda m: m.number)
276
+
277
+
278
+ def sort_manifests(
279
+ manifests: Iterable[Manifest], config: dict[str, Any]
280
+ ) -> list[Manifest]:
281
+ order = {gate["id"]: index for index, gate in enumerate(config["gates"])}
282
+ return sorted(
283
+ manifests,
284
+ key=lambda m: (order.get(m.gate, len(order)), m.gate, m.system or "", m.number),
285
+ )
286
+
287
+
288
+ def run_git(directory: Path, *args: str) -> bytes:
289
+ try:
290
+ completed = subprocess.run(
291
+ ["git", "-C", str(directory), *args], capture_output=True
292
+ )
293
+ except OSError as exc:
294
+ raise InputError(f"cannot run git: {exc}") from exc
295
+ if completed.returncode != 0:
296
+ detail = completed.stderr.decode("utf-8", "replace").strip()
297
+ raise InputError(f"git {args[0]} failed: {detail}")
298
+ return completed.stdout
299
+
300
+
301
+ def current_user(directory: Path) -> str:
302
+ try:
303
+ name = (
304
+ run_git(directory, "config", "user.name").decode("utf-8", "replace").strip()
305
+ )
306
+ except InputError:
307
+ name = ""
308
+ return name or getpass.getuser()
309
+
310
+
311
+ def _print_warning(message: str) -> None:
312
+ print(f"warning: {message}", file=sys.stderr)
313
+
314
+
315
+ TableReader = Callable[[Path], CsvTable]
316
+
317
+ SIGNOFF_PREFIX = "signoff/"
318
+
319
+
320
+ def _tag_number(ref: str) -> int:
321
+ match = re.search(r"-(\d+)$", ref)
322
+ return int(match.group(1)) if match else 1
323
+
324
+
325
+ def classify_verification(returncode: int, output: str) -> str:
326
+ if returncode == 0:
327
+ return "good"
328
+ text = output.lower()
329
+ if "no signature" in text:
330
+ return "unsigned"
331
+ if re.search(r"bad signature|incorrect signature|invalid signature", text):
332
+ return "bad"
333
+ return "unverifiable"
334
+
335
+
336
+ class BaselineStore(ABC):
337
+ """Where gate baselines live. Both stores keep the same manifest and the same frozen table."""
338
+
339
+ source: str
340
+
341
+ def __init__(
342
+ self,
343
+ input_path: Path,
344
+ config: dict[str, Any],
345
+ read_file: TableReader,
346
+ warn: Callable[[str], None],
347
+ ):
348
+ self.input_path = input_path
349
+ self.config = config
350
+ self.read_file = read_file
351
+ self.warn = warn
352
+
353
+ @abstractmethod
354
+ def current(self) -> CsvTable:
355
+ """The table a new baseline would freeze."""
356
+
357
+ @abstractmethod
358
+ def list(self) -> list[Manifest]: ...
359
+
360
+ @abstractmethod
361
+ def write(self, manifest: Manifest, table: CsvTable) -> None: ...
362
+
363
+ @abstractmethod
364
+ def read(self, manifest: Manifest) -> CsvTable: ...
365
+
366
+ @abstractmethod
367
+ def where(self, manifest: Manifest) -> str:
368
+ """Phrase for the creation message, such as 'as tag baseline/SRR'."""
369
+
370
+ @abstractmethod
371
+ def add_signoff(self, manifest: Manifest, record: SignOff) -> str:
372
+ """Record a sign-off beside the baseline and return the phrase for where it went."""
373
+
374
+ @abstractmethod
375
+ def signoffs(self, manifest: Manifest) -> list[CheckedSignOff]:
376
+ """The baseline's sign-offs, oldest first, each checked the way this store can check it."""
377
+
378
+
379
+ class GitStore(BaselineStore):
380
+ def __init__(
381
+ self,
382
+ input_path: Path,
383
+ config: dict[str, Any],
384
+ read_file: TableReader,
385
+ warn: Callable[[str], None],
386
+ ):
387
+ super().__init__(input_path, config, read_file, warn)
388
+ self.prefix = config["baselines"]["git"]["tag_prefix"]
389
+
390
+ @cached_property
391
+ def root(self) -> Path:
392
+ directory = self.input_path.resolve().parent
393
+ try:
394
+ return Path(
395
+ run_git(directory, "rev-parse", "--show-toplevel")
396
+ .decode("utf-8")
397
+ .strip()
398
+ )
399
+ except InputError as exc:
400
+ raise InputError(
401
+ f"{self.input_path} is not inside a git work tree: {exc}"
402
+ ) from exc
403
+
404
+ @cached_property
405
+ def source(self) -> str: # type: ignore[override]
406
+ tracked = run_git(
407
+ self.root, "ls-files", "--full-name", "--", str(self.input_path.resolve())
408
+ ).decode("utf-8")
409
+ paths = [line for line in tracked.splitlines() if line]
410
+ if not paths:
411
+ raise InputError(
412
+ f"{self.input_path} is not tracked by git; commit it before creating a baseline"
413
+ )
414
+ return paths[0]
415
+
416
+ def current(self) -> CsvTable:
417
+ if run_git(self.root, "status", "--porcelain", "--", self.source).strip():
418
+ raise InputError(
419
+ f"{self.input_path} has uncommitted changes; commit them before creating a baseline"
420
+ )
421
+ return self._read_at("HEAD", self.source)
422
+
423
+ def _read_at(self, rev: str, source: str) -> CsvTable:
424
+ name = Path(source).name
425
+ spec = f"{rev}:{source}"
426
+ if is_xlsx(name):
427
+ blob = run_git(self.root, "cat-file", "blob", spec)
428
+ with tempfile.TemporaryDirectory() as folder:
429
+ copy = Path(folder) / name
430
+ copy.write_bytes(blob)
431
+ return self.read_file(copy)
432
+ encoding = self.config["csv"]["encoding"]
433
+ label = f"{name} @ {rev}"
434
+ try:
435
+ text = run_git(self.root, "cat-file", "--filters", spec).decode(encoding)
436
+ except (UnicodeError, LookupError) as exc:
437
+ raise InputError(f"{label}: cannot decode as {encoding}: {exc}") from exc
438
+ return read_csv_source(CsvSource(label, text, Path(source)), self.config)
439
+
440
+ def _ref(self, manifest: Manifest) -> str:
441
+ return f"{self.prefix}{manifest.name}"
442
+
443
+ def list(self) -> list[Manifest]:
444
+ listing = run_git(
445
+ self.root,
446
+ "for-each-ref",
447
+ "--format=%(refname)%00%(objecttype)%00%(contents)%01",
448
+ f"refs/tags/{self.prefix}",
449
+ ).decode("utf-8", "replace")
450
+ found = []
451
+ for record in listing.split("\x01"):
452
+ if not record.strip():
453
+ continue
454
+ ref, kind, contents = record.lstrip("\n").split("\x00", 2)
455
+ try:
456
+ if kind != "tag":
457
+ raise ValueError("not an annotated tag")
458
+ _, _, body = contents.partition("\n\n")
459
+ manifest = Manifest.from_dict(
460
+ json.JSONDecoder().raw_decode(body.lstrip())[0]
461
+ )
462
+ if ref != f"refs/tags/{self._ref(manifest)}":
463
+ raise ValueError("tag name does not match its manifest")
464
+ except (ValueError, InputError) as exc:
465
+ self.warn(f"ignoring tag {ref.removeprefix('refs/tags/')}: {exc}")
466
+ continue
467
+ found.append(manifest)
468
+ return found
469
+
470
+ def write(self, manifest: Manifest, table: CsvTable) -> None:
471
+ message = f"ReqTable baseline {manifest.name}\n\n{json.dumps(manifest.to_dict(), indent=2, ensure_ascii=False)}\n"
472
+ with tempfile.TemporaryDirectory() as folder:
473
+ message_file = Path(folder) / "message"
474
+ message_file.write_text(message, encoding="utf-8")
475
+ run_git(
476
+ self.root,
477
+ "tag",
478
+ "-a",
479
+ self._ref(manifest),
480
+ "-F",
481
+ str(message_file),
482
+ "HEAD",
483
+ )
484
+
485
+ def read(self, manifest: Manifest) -> CsvTable:
486
+ return self._read_at(
487
+ f"refs/tags/{self._ref(manifest)}^{{commit}}", manifest.source
488
+ )
489
+
490
+ def where(self, manifest: Manifest) -> str:
491
+ return f"as tag {self._ref(manifest)}"
492
+
493
+ def add_signoff(self, manifest: Manifest, record: SignOff) -> str:
494
+ stem = f"{SIGNOFF_PREFIX}{manifest.name}/{slug(record.role)}/"
495
+ if not slug(record.role) or not slug(record.user):
496
+ raise InputError(
497
+ "a sign-off needs a role and a user that contain letters or digits"
498
+ )
499
+ taken = set(
500
+ run_git(
501
+ self.root,
502
+ "for-each-ref",
503
+ "--format=%(refname:short)",
504
+ f"refs/tags/{stem}",
505
+ )
506
+ .decode()
507
+ .split()
508
+ )
509
+ base = f"{stem}{slug(record.user)}"
510
+ name, number = base, 1
511
+ while name in taken:
512
+ number += 1
513
+ name = f"{base}-{number}"
514
+ commit = (
515
+ run_git(
516
+ self.root, "rev-parse", f"refs/tags/{self._ref(manifest)}^{{commit}}"
517
+ )
518
+ .decode()
519
+ .strip()
520
+ )
521
+ message = (
522
+ f"ReqTable sign-off {record.baseline} {record.role} {record.decision}\n\n"
523
+ f"{json.dumps(record.to_dict(), indent=2, ensure_ascii=False)}\n"
524
+ )
525
+ with tempfile.TemporaryDirectory() as folder:
526
+ message_file = Path(folder) / "message"
527
+ message_file.write_text(message, encoding="utf-8")
528
+ try:
529
+ run_git(self.root, "tag", "-s", name, "-F", str(message_file), commit)
530
+ except InputError as exc:
531
+ raise InputError(
532
+ f"{exc}\nSign-off tags must be signed. Configure a signing key for git, either GPG "
533
+ "(user.signingkey) or SSH (gpg.format ssh and user.signingkey), then try again."
534
+ ) from exc
535
+ return f"as tag {name}"
536
+
537
+ def signoffs(self, manifest: Manifest) -> list[CheckedSignOff]:
538
+ commit = (
539
+ run_git(
540
+ self.root, "rev-parse", f"refs/tags/{self._ref(manifest)}^{{commit}}"
541
+ )
542
+ .decode()
543
+ .strip()
544
+ )
545
+ listing = run_git(
546
+ self.root,
547
+ "for-each-ref",
548
+ "--format=%(refname)%00%(objecttype)%00%(*objectname)%00%(contents)%01",
549
+ f"refs/tags/{SIGNOFF_PREFIX}{manifest.name}/",
550
+ ).decode("utf-8", "replace")
551
+ found = []
552
+ for entry in listing.split("\x01"):
553
+ if not entry.strip():
554
+ continue
555
+ ref, kind, target, contents = entry.lstrip("\n").split("\x00", 3)
556
+ try:
557
+ if kind != "tag":
558
+ raise ValueError("not an annotated tag")
559
+ _, _, body = contents.partition("\n\n")
560
+ record = SignOff.from_dict(
561
+ json.JSONDecoder().raw_decode(body.lstrip())[0]
562
+ )
563
+ except ValueError as exc:
564
+ self.warn(f"ignoring tag {ref.removeprefix('refs/tags/')}: {exc}")
565
+ continue
566
+ if record.baseline != manifest.name:
567
+ continue
568
+ verification, detail = self._verify_tag(ref)
569
+ problems = []
570
+ if target != commit:
571
+ problems.append("the tag does not point at the baseline commit")
572
+ if record.content_hash != manifest.content_hash:
573
+ problems.append("its content hash differs from the baseline's")
574
+ counts = verification == "good" and not problems
575
+ reason = "; ".join(problems)
576
+ found.append(
577
+ (
578
+ record,
579
+ ref,
580
+ CheckedSignOff(
581
+ record,
582
+ verification,
583
+ "; ".join(filter(None, (reason, detail))),
584
+ counts,
585
+ ),
586
+ )
587
+ )
588
+ found.sort(key=lambda item: (item[0].moment, _tag_number(item[1]), item[1]))
589
+ return [checked for _, _, checked in found]
590
+
591
+ def _verify_tag(self, ref: str) -> tuple[str, str]:
592
+ try:
593
+ completed = subprocess.run(
594
+ ["git", "-C", str(self.root), "verify-tag", ref], capture_output=True
595
+ )
596
+ except OSError as exc:
597
+ raise InputError(f"cannot run git: {exc}") from exc
598
+ detail = completed.stderr.decode("utf-8", "replace").strip()
599
+ return classify_verification(completed.returncode, detail), detail
600
+
601
+
602
+ class FileStore(BaselineStore):
603
+ def __init__(
604
+ self,
605
+ input_path: Path,
606
+ config: dict[str, Any],
607
+ read_file: TableReader,
608
+ warn: Callable[[str], None],
609
+ ):
610
+ super().__init__(input_path, config, read_file, warn)
611
+ self.directory = input_path.parent / config["baselines"]["files"]["directory"]
612
+ self.source = input_path.name
613
+
614
+ def current(self) -> CsvTable:
615
+ return self.read_file(self.input_path)
616
+
617
+ def _folder(self, manifest: Manifest) -> Path:
618
+ return self.directory / manifest.name
619
+
620
+ def list(self) -> list[Manifest]:
621
+ found = []
622
+ if not self.directory.is_dir():
623
+ return found
624
+ for path in sorted(self.directory.rglob("manifest.json")):
625
+ relative = path.parent.relative_to(self.directory)
626
+ if any(part.startswith(".") for part in relative.parts):
627
+ continue
628
+ try:
629
+ stored = json.loads(path.read_text(encoding="utf-8"))
630
+ if isinstance(stored, dict):
631
+ stored.pop("signoffs", None)
632
+ manifest = Manifest.from_dict(stored)
633
+ if manifest.name != relative.as_posix():
634
+ raise ValueError("folder name does not match its manifest")
635
+ except (OSError, ValueError, InputError) as exc:
636
+ self.warn(f"ignoring {path}: {exc}")
637
+ continue
638
+ found.append(manifest)
639
+ return found
640
+
641
+ def write(self, manifest: Manifest, table: CsvTable) -> None:
642
+ target = self._folder(manifest)
643
+ if not target.resolve().is_relative_to(self.directory.resolve()):
644
+ raise InputError(
645
+ f"baseline name {manifest.name!r} would leave {self.directory}"
646
+ )
647
+ if target.exists():
648
+ raise InputError(
649
+ f"baseline folder {target} already exists; baselines are never overwritten"
650
+ )
651
+ staging = target.parent / f".{target.name}.staging"
652
+ try:
653
+ target.parent.mkdir(parents=True, exist_ok=True)
654
+ shutil.rmtree(staging, ignore_errors=True)
655
+ staging.mkdir()
656
+ records = [
657
+ table.headers,
658
+ *([row[header] for header in table.headers] for row in table.rows),
659
+ ]
660
+ csv_text = block_to_csv(records, self.config["csv"]["delimiter"])
661
+ (staging / "requirements.csv").write_bytes(
662
+ ("\ufeff" + csv_text).encode("utf-8")
663
+ )
664
+ shutil.copy2(self.input_path, staging / f"source{self.input_path.suffix}")
665
+ (staging / "manifest.json").write_text(
666
+ json.dumps(manifest.to_dict(), indent=2, ensure_ascii=False) + "\n",
667
+ encoding="utf-8",
668
+ )
669
+ os.rename(staging, target)
670
+ except OSError as exc:
671
+ shutil.rmtree(staging, ignore_errors=True)
672
+ raise OutputError(f"cannot write baseline folder {target}: {exc}") from exc
673
+
674
+ def read(self, manifest: Manifest) -> CsvTable:
675
+ path = self._folder(manifest) / "requirements.csv"
676
+ config = {**self.config, "csv": {**self.config["csv"], "encoding": "utf-8-sig"}}
677
+ return read_csv_source(
678
+ CsvSource(f"{manifest.name} requirements.csv", None, path), config
679
+ )
680
+
681
+ def where(self, manifest: Manifest) -> str:
682
+ return f"in {self._folder(manifest)}"
683
+
684
+ def _manifest_path(self, manifest: Manifest) -> Path:
685
+ return self._folder(manifest) / "manifest.json"
686
+
687
+ def add_signoff(self, manifest: Manifest, record: SignOff) -> str:
688
+ path = self._manifest_path(manifest)
689
+ try:
690
+ data = json.loads(path.read_text(encoding="utf-8"))
691
+ except (OSError, ValueError) as exc:
692
+ raise InputError(f"cannot read {path}: {exc}") from exc
693
+ data["signoffs"] = [*data.get("signoffs", []), record.to_dict()]
694
+ atomic_write_text(
695
+ str(path), json.dumps(data, indent=2, ensure_ascii=False) + "\n"
696
+ )
697
+ return f"in {path}"
698
+
699
+ def signoffs(self, manifest: Manifest) -> list[CheckedSignOff]:
700
+ path = self._manifest_path(manifest)
701
+ try:
702
+ entries = json.loads(path.read_text(encoding="utf-8")).get("signoffs", [])
703
+ except (OSError, ValueError) as exc:
704
+ raise InputError(f"cannot read {path}: {exc}") from exc
705
+ found = []
706
+ for index, entry in enumerate(entries):
707
+ try:
708
+ record = SignOff.from_dict(entry)
709
+ except ValueError as exc:
710
+ self.warn(f"ignoring sign-off {index + 1} in {path}: {exc}")
711
+ continue
712
+ found.append(
713
+ CheckedSignOff(
714
+ record, "recorded", self._evidence_detail(manifest, record), True
715
+ )
716
+ )
717
+ return found
718
+
719
+ def _evidence_detail(self, manifest: Manifest, record: SignOff) -> str:
720
+ evidence = record.evidence
721
+ if not evidence or "://" in evidence or Path(evidence).is_absolute():
722
+ return ""
723
+ found = (self._folder(manifest) / evidence).exists()
724
+ return f"evidence {evidence} {'found' if found else 'not found'} in the baseline folder"
725
+
726
+
727
+ def open_store(
728
+ input_path: str | Path,
729
+ config: dict[str, Any],
730
+ read_file: TableReader,
731
+ warn: Callable[[str], None] = _print_warning,
732
+ ) -> BaselineStore:
733
+ store = GitStore if config["baselines"]["store"] == "git" else FileStore
734
+ return store(Path(input_path), config, read_file, warn)
735
+
736
+
737
+ def require_scope_args(gate: Gate, system: str | None, config: dict[str, Any]) -> None:
738
+ if gate.scope == "system":
739
+ if not system:
740
+ raise ConfigError(
741
+ f"gate {gate.id} is system-scoped; give --system with a System ID"
742
+ )
743
+ if not config["traceability"]:
744
+ raise ConfigError("system-scoped baselines need --traceability")
745
+ elif system:
746
+ raise ConfigError(
747
+ f"gate {gate.id} covers the whole table; --system applies only to system-scoped gates"
748
+ )
749
+
750
+
751
+ def require_system_record(table: CsvTable, system: str | None) -> None:
752
+ if system is None:
753
+ return
754
+ record = table.by_id.get(system)
755
+ if record is None or record_type(record) != "System":
756
+ raise InputError(f"{system!r} is not a System record in {table.label}")
757
+
758
+
759
+ def create_baseline(
760
+ store: BaselineStore,
761
+ config: dict[str, Any],
762
+ gate_id: str,
763
+ system: str | None,
764
+ waivers: Sequence[Waiver] = (),
765
+ ) -> Manifest:
766
+ gate = find_gate(config, gate_id)
767
+ require_scope_args(gate, system, config)
768
+ table = store.current()
769
+ id_column = config["id_column"]
770
+ require_system_record(table, system)
771
+ status_columns = config["baselines"]["status_columns"]
772
+ digest = content_hash(
773
+ table.headers,
774
+ select_scope(table.rows, id_column, system, gate.includes),
775
+ system,
776
+ gate.includes,
777
+ gate.captures_status,
778
+ status_columns,
779
+ )
780
+ name, supersedes = next_name(store.list(), gate.id, system)
781
+ manifest = Manifest(
782
+ name=str(name),
783
+ gate=gate.id,
784
+ supersedes=supersedes,
785
+ system=system,
786
+ includes=list(gate.includes),
787
+ captures_status=gate.captures_status,
788
+ status_columns=list(status_columns),
789
+ content_hash=digest,
790
+ source=store.source,
791
+ created=generation_time(),
792
+ created_by=current_user(store.input_path.resolve().parent),
793
+ waivers=tuple(waivers),
794
+ )
795
+ store.write(manifest, table)
796
+ return manifest
797
+
798
+
799
+ def gate_roles(config: dict[str, Any], gate_id: str) -> list[dict[str, Any]]:
800
+ for gate in config["gates"]:
801
+ if gate["id"] == gate_id:
802
+ return list(gate.get("signoff", []))
803
+ return []
804
+
805
+
806
+ def recompute_hash(
807
+ store: BaselineStore, id_column: str, manifest: Manifest
808
+ ) -> tuple[CsvTable, list[dict[str, str]], str]:
809
+ table = store.read(manifest)
810
+ rows = select_scope(table.rows, id_column, manifest.system, manifest.includes)
811
+ digest = content_hash(
812
+ table.headers,
813
+ rows,
814
+ manifest.system,
815
+ manifest.includes,
816
+ manifest.captures_status,
817
+ manifest.status_columns,
818
+ )
819
+ return table, rows, digest
820
+
821
+
822
+ def load_baselines(
823
+ store: BaselineStore,
824
+ config: dict[str, Any],
825
+ requested: Iterable[str],
826
+ warn: Callable[[str], None] = _print_warning,
827
+ ) -> list[dict[str, Any]]:
828
+ manifests = store.list()
829
+ gates = {gate["id"]: Gate.from_config(gate) for gate in config["gates"]}
830
+ id_column = config["id_column"]
831
+ chosen: dict[str, Manifest] = {}
832
+ for name in requested:
833
+ found = resolve(name, manifests)
834
+ chosen.setdefault(found.name, found)
835
+ entries = []
836
+ for found in chosen.values():
837
+ table, rows, digest = recompute_hash(store, id_column, found)
838
+ hash_ok = digest == found.content_hash
839
+ if not hash_ok:
840
+ warn(f"baseline {found.name} does not match its recorded hash")
841
+ gate = gates.get(found.gate)
842
+ checked = store.signoffs(found)
843
+ entries.append(
844
+ {
845
+ "name": found.name,
846
+ "gate": found.gate,
847
+ "gateName": gate.name if gate else found.gate,
848
+ "produces": gate.produces if gate else "",
849
+ "system": found.system,
850
+ "created": found.created,
851
+ "createdBy": found.created_by,
852
+ "hash": found.content_hash,
853
+ "hashOk": hash_ok,
854
+ "includes": found.includes,
855
+ "capturesStatus": found.captures_status,
856
+ "statusColumns": found.status_columns,
857
+ "source": found.source,
858
+ "headers": table.headers,
859
+ "rows": rows,
860
+ "signoffs": [item.to_dict() for item in checked],
861
+ "approval": approval_status(gate_roles(config, found.gate), checked),
862
+ "waivers": [waiver.to_dict() for waiver in found.waivers],
863
+ }
864
+ )
865
+ return entries
866
+
867
+
868
+ def build_controls(
869
+ store: BaselineStore, config: dict[str, Any]
870
+ ) -> dict[str, Any] | None:
871
+ """The controlling baseline row of every baselined record, or None when there is nothing to control.
872
+
873
+ A record's controlling baseline is the latest created one whose scope holds it. Among baselines created at
874
+ the same moment the later gate, then the higher number, controls, and the list puts it first because the
875
+ report's checkChanges keeps the first of equal creation times.
876
+ """
877
+ if not config["baselines"]["change_control"]:
878
+ return None
879
+ try:
880
+ manifests = store.list()
881
+ except ReqtableError:
882
+ return None
883
+ if not manifests:
884
+ return None
885
+ order = {gate["id"]: index for index, gate in enumerate(config["gates"])}
886
+ manifests.sort(
887
+ key=lambda m: (m.created, -order.get(m.gate, len(order)), -m.number, m.name)
888
+ )
889
+ id_column = config["id_column"]
890
+ records: dict[str, dict[str, Any]] = {}
891
+ created: dict[str, str] = {}
892
+ try:
893
+ for manifest in manifests:
894
+ table = store.read(manifest)
895
+ if config["traceability"]:
896
+ table, _ = prepare_trace_table(table, config)
897
+ for row in select_scope(
898
+ table.rows, id_column, manifest.system, manifest.includes
899
+ ):
900
+ record_id = row[id_column].strip()
901
+ if record_id not in records or manifest.created > created[record_id]:
902
+ records[record_id] = {"baseline": manifest.name, "row": row}
903
+ created[record_id] = manifest.created
904
+ except ReqtableError as exc:
905
+ store.warn(f"change control is off: {exc}")
906
+ return None
907
+ return {
908
+ "baselines": [
909
+ {
910
+ "name": m.name,
911
+ "created": m.created,
912
+ "system": m.system,
913
+ "includes": m.includes,
914
+ "capturesStatus": m.captures_status,
915
+ "statusColumns": m.status_columns,
916
+ }
917
+ for m in manifests
918
+ ],
919
+ "records": records,
920
+ }