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.
@@ -0,0 +1,789 @@
1
+ """The GUI's workbook mapping builder: what each kind of table can fill in, and the pure code that turns a form into
2
+ the ``xlsx.sources`` mapping documented in docs/excel.md. Only ``preview_mapping`` and ``save_mapping`` touch the disk."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ from collections import Counter
8
+ from dataclasses import asdict, dataclass
9
+ from pathlib import Path
10
+ from typing import Any, Mapping
11
+
12
+ from .core import (
13
+ ConfigError,
14
+ ReqtableError,
15
+ atomic_write_text,
16
+ validate_headings,
17
+ validate_xlsx_sources,
18
+ )
19
+ from .gui import BadRequest, GuiError, guess_id_column
20
+ from .xlsx import SourceStats, XlsxSelection, import_workbook
21
+
22
+ ID_COLUMN = "ID"
23
+ FIELD_COLUMN = "Field"
24
+ SEPARATORS = ((",", "Comma"), (";", "Semicolon"), ("newline", "New line"))
25
+ LIST_SEPARATOR = ","
26
+ DEFAULT_CATEGORY = "Category"
27
+ KEEP, MAP, EXCLUDE = "keep", "map", "exclude"
28
+ FIELD_CHOICES = (
29
+ ("Priority", "Priority"),
30
+ ("Verification Method", "Verification Method"),
31
+ ("Verification Level", "Verification Level (verification stages)"),
32
+ ("Execution", "Execution (manual or automated)"),
33
+ ("Compliance", "Compliance"),
34
+ ("Result", "Result"),
35
+ )
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Target:
40
+ """An output column a role offers. `hints` are other header names that should be matched to it automatically."""
41
+
42
+ column: str
43
+ label: str
44
+ list_separator: bool = False
45
+ hints: tuple[str, ...] = ()
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class Role:
50
+ id: str
51
+ label: str
52
+ help: str
53
+ type: str | None
54
+ targets: tuple[Target, ...]
55
+ id_prefix: str = ""
56
+ needs_field: bool = False
57
+ merge: bool = False
58
+ headings: bool = False
59
+
60
+
61
+ def _id(label: str = "ID") -> Target:
62
+ return Target(ID_COLUMN, label, hints=("id",))
63
+
64
+
65
+ NAME = Target("Name", "Name", hints=("title",))
66
+ REFERENCE = Target("Reference", "Link or citation", hints=("url", "link"))
67
+ METHOD = Target("Verification Method", "Verification Method", True, ("method",))
68
+ LEVEL = Target(
69
+ "Verification Level",
70
+ "Verification Level (verification stages)",
71
+ True,
72
+ ("level", "stage"),
73
+ )
74
+
75
+ ROLES: tuple[Role, ...] = (
76
+ Role(
77
+ "requirements",
78
+ "Requirements",
79
+ "The requirements themselves. Each row keeps its own Type.",
80
+ None,
81
+ (
82
+ _id("ID"),
83
+ Target("Name", "Short title", hints=("title",)),
84
+ Target(
85
+ "Requirement",
86
+ "Requirement text",
87
+ hints=("text", "description", "shall"),
88
+ ),
89
+ Target("Priority", "Priority"),
90
+ METHOD,
91
+ LEVEL,
92
+ Target("Verified by", "Tests that verify it", True, ("tests",)),
93
+ Target("Allocated to", "Systems it is allocated to", True),
94
+ Target("Derived from", "Parent requirements", True, ("parent",)),
95
+ Target("Source refs", "Needs and sources", True, ("sources",)),
96
+ Target("Owner", "Owning system"),
97
+ Target("Rationale", "Rationale"),
98
+ Target("Compliance", "Compliance (is it met?)"),
99
+ Target("Type", "Record type", hints=("kind",)),
100
+ ),
101
+ headings=True,
102
+ ),
103
+ Role(
104
+ "glossary",
105
+ "Glossary terms",
106
+ "Words and abbreviations the project defines. Each row becomes a Term.",
107
+ "Term",
108
+ (
109
+ _id("ID"),
110
+ Target("Name", "Term", hints=("name", "word")),
111
+ Target("Definition", "Meaning", hints=("meaning", "description")),
112
+ Target(
113
+ "Aliases",
114
+ "Other spellings",
115
+ True,
116
+ ("abbreviation", "synonyms", "alias"),
117
+ ),
118
+ Target("Auto Link", "Link automatically in text", hints=("autolink",)),
119
+ REFERENCE,
120
+ ),
121
+ id_prefix="TERM-",
122
+ ),
123
+ Role(
124
+ "values",
125
+ "Allowed values",
126
+ "The values a column may hold, such as Must and Should for Priority, or Unit and System for Verification Level.",
127
+ "Value",
128
+ (
129
+ _id("ID"),
130
+ Target(FIELD_COLUMN, "Column the value belongs to", hints=("column",)),
131
+ Target("Name", "Allowed value", hints=("value",)),
132
+ Target("Definition", "Meaning", hints=("meaning", "description")),
133
+ Target("Aliases", "Old spellings", True, ("synonyms", "alias")),
134
+ REFERENCE,
135
+ ),
136
+ id_prefix="VAL-",
137
+ needs_field=True,
138
+ ),
139
+ Role(
140
+ "tests",
141
+ "Tests",
142
+ "Tests, scripts or checklists that verify requirements. The description lands in the Requirement column.",
143
+ "Test",
144
+ (
145
+ _id("ID"),
146
+ Target("Name", "Test title", hints=("title", "name")),
147
+ Target(
148
+ "Requirement", "Description", hints=("description", "text", "steps")
149
+ ),
150
+ Target("Test plan", "Test plan", hints=("plan",)),
151
+ METHOD,
152
+ LEVEL,
153
+ Target("Execution", "How it is run (Manual or Automated)"),
154
+ Target("Result", "Result", hints=("status",)),
155
+ Target("Reference", "Link to the test", hints=("url", "link")),
156
+ ),
157
+ id_prefix="TEST-",
158
+ ),
159
+ Role(
160
+ "plans",
161
+ "Test plans",
162
+ "Groups of tests. The description lands in the Requirement column.",
163
+ "Test plan",
164
+ (
165
+ _id("ID"),
166
+ Target("Name", "Plan title", hints=("title",)),
167
+ Target("Requirement", "Description", hints=("description", "text")),
168
+ REFERENCE,
169
+ ),
170
+ id_prefix="PLAN-",
171
+ ),
172
+ Role(
173
+ "systems",
174
+ "Systems",
175
+ "The systems and subsystems the requirements are allocated to.",
176
+ "System",
177
+ (
178
+ _id("ID"),
179
+ NAME,
180
+ Target("Part of", "Parent system", hints=("parent",)),
181
+ REFERENCE,
182
+ ),
183
+ id_prefix="SYS-",
184
+ ),
185
+ Role(
186
+ "needs",
187
+ "Needs",
188
+ "Stakeholder needs that requirements trace back to. The description lands in the Requirement column.",
189
+ "Need",
190
+ (
191
+ _id("ID"),
192
+ NAME,
193
+ Target("Requirement", "Description", hints=("description", "text")),
194
+ Target("Source refs", "Sources", True, ("sources",)),
195
+ REFERENCE,
196
+ ),
197
+ id_prefix="NEED-",
198
+ ),
199
+ Role(
200
+ "sources",
201
+ "Sources",
202
+ "Documents, standards or people that needs and requirements cite.",
203
+ "Source",
204
+ (_id("ID"), NAME, REFERENCE),
205
+ id_prefix="SRC-",
206
+ ),
207
+ )
208
+ ROLES += (
209
+ Role(
210
+ "merge",
211
+ "Details for existing requirements (matched by ID)",
212
+ "Fills in cells of requirements that are already imported, matching each row by ID. Use it for a verification "
213
+ "matrix sheet, or add a tests table a second time here to link its tests to the requirements they verify.",
214
+ None,
215
+ (
216
+ Target(
217
+ ID_COLUMN,
218
+ "Requirement ID (which requirement this row is about)",
219
+ True,
220
+ (
221
+ "requirement",
222
+ "requirements",
223
+ "requirement id",
224
+ "req",
225
+ "req id",
226
+ "verifies",
227
+ ),
228
+ ),
229
+ LEVEL,
230
+ METHOD,
231
+ Target(
232
+ "Verified by",
233
+ "Tests that verify it",
234
+ True,
235
+ ("test", "tests", "test id"),
236
+ ),
237
+ Target("Priority", "Priority"),
238
+ Target("Rationale", "Rationale"),
239
+ ),
240
+ merge=True,
241
+ ),
242
+ )
243
+ ROLES_BY_ID = {role.id: role for role in ROLES}
244
+
245
+
246
+ def role_named(role_id: str) -> Role:
247
+ try:
248
+ return ROLES_BY_ID[role_id]
249
+ except KeyError:
250
+ raise BadRequest(f"unknown role {role_id!r}") from None
251
+
252
+
253
+ def role_for_type(record_type: str | None) -> Role | None:
254
+ return next((role for role in ROLES if role.type == record_type), None)
255
+
256
+
257
+ def mapping_json() -> dict[str, Any]:
258
+ return {
259
+ "roles": [asdict(role) for role in ROLES],
260
+ "separators": [{"value": value, "label": label} for value, label in SEPARATORS],
261
+ "fields": [{"value": value, "label": label} for value, label in FIELD_CHOICES],
262
+ "id_column": ID_COLUMN,
263
+ }
264
+
265
+
266
+ def suggest_columns(role: Role, headers: list[str]) -> dict[str, Any]:
267
+ """Prefill: each header goes to the role target it is named after. Any other header is kept as it is, except in a
268
+ merge source, where a kept column would be added to every requirement."""
269
+ guessed_id = guess_id_column(headers)
270
+ taken: set[str] = set()
271
+ columns = []
272
+ for header in headers:
273
+ name = header.strip().casefold()
274
+ target = None
275
+ for candidate in role.targets:
276
+ if candidate.column in taken:
277
+ continue
278
+ if candidate.column == ID_COLUMN and not role.merge:
279
+ hit = header == guessed_id and bool(guessed_id)
280
+ else:
281
+ hit = name in {
282
+ candidate.column.casefold(),
283
+ candidate.label.casefold(),
284
+ *candidate.hints,
285
+ }
286
+ if hit:
287
+ target = candidate
288
+ break
289
+ if target is None:
290
+ columns.append(
291
+ {
292
+ "header": header,
293
+ "action": EXCLUDE if role.merge else KEEP,
294
+ "to": "",
295
+ "separator": "",
296
+ }
297
+ )
298
+ continue
299
+ taken.add(target.column)
300
+ columns.append(
301
+ {
302
+ "header": header,
303
+ "action": MAP,
304
+ "to": target.column,
305
+ "separator": LIST_SEPARATOR if target.list_separator else "",
306
+ }
307
+ )
308
+ if role.merge and ID_COLUMN not in taken and guessed_id:
309
+ # A merge key is the requirement a row points to; a header that only looks like an ID is the fallback.
310
+ fallback = next(c for c in columns if c["header"] == guessed_id)
311
+ if fallback["action"] != MAP:
312
+ fallback.update(action=MAP, to=ID_COLUMN, separator=LIST_SEPARATOR)
313
+ taken.add(ID_COLUMN)
314
+ has_id = ID_COLUMN in taken
315
+ return {
316
+ "columns": columns,
317
+ "id_prefix": "" if has_id or role.merge else role.id_prefix,
318
+ }
319
+
320
+
321
+ @dataclass(frozen=True)
322
+ class ColumnDraft:
323
+ header: str
324
+ action: str
325
+ to: str
326
+ separator: str
327
+
328
+ @property
329
+ def output(self) -> str:
330
+ return self.to if self.action == MAP else self.header
331
+
332
+
333
+ @dataclass(frozen=True)
334
+ class HeadingRows:
335
+ """Rows whose `column` cell holds one of `values` are category names; the requirements below one get its text in `into`."""
336
+
337
+ column: str
338
+ values: tuple[str, ...]
339
+ text: str
340
+ into: str = DEFAULT_CATEGORY
341
+
342
+ def to_json(self) -> dict[str, Any]:
343
+ return {
344
+ "column": self.column,
345
+ "values": list(self.values),
346
+ **({"text": self.text} if self.text else {}),
347
+ "into": self.into,
348
+ }
349
+
350
+ @classmethod
351
+ def from_json(cls, headings: Mapping[str, Any]) -> HeadingRows:
352
+ return cls(
353
+ headings["column"],
354
+ tuple(headings["values"]),
355
+ headings.get("text", ""),
356
+ headings["into"],
357
+ )
358
+
359
+
360
+ @dataclass(frozen=True)
361
+ class SourceDraft:
362
+ kind: str
363
+ name: str
364
+ header_row: int | None
365
+ role: Role | None
366
+ field: str
367
+ id_prefix: str
368
+ columns: tuple[ColumnDraft, ...]
369
+ extra: Mapping[str, Any]
370
+ raw: Mapping[str, Any] | None = None
371
+ headings: HeadingRows | None = None
372
+
373
+ @property
374
+ def where(self) -> str:
375
+ return f"{self.kind} {self.name!r}"
376
+
377
+
378
+ def _text(value: object, where: str) -> str:
379
+ if value is None:
380
+ return ""
381
+ if not isinstance(value, str):
382
+ raise BadRequest(f"{where} must be text")
383
+ return value.strip()
384
+
385
+
386
+ def _parse_column(item: object, where: str) -> ColumnDraft:
387
+ if not isinstance(item, Mapping):
388
+ raise BadRequest(f"{where} must be an object")
389
+ action = _text(item.get("action", KEEP), f"{where}.action")
390
+ if action not in (KEEP, MAP, EXCLUDE):
391
+ raise BadRequest(f"{where}.action must be keep, map or exclude")
392
+ return ColumnDraft(
393
+ _text(item.get("header"), f"{where}.header"),
394
+ action,
395
+ _text(item.get("to"), f"{where}.to"),
396
+ _text(item.get("separator"), f"{where}.separator"),
397
+ )
398
+
399
+
400
+ def _parse_headings(item: object, where: str) -> HeadingRows | None:
401
+ if item is None:
402
+ return None
403
+ if not isinstance(item, Mapping):
404
+ raise BadRequest(f"{where} must be an object")
405
+ values = item.get("values", [])
406
+ if not isinstance(values, list):
407
+ raise BadRequest(f"{where}.values must be a list")
408
+ return HeadingRows(
409
+ _text(item.get("column"), f"{where}.column"),
410
+ tuple(v for v in (_text(v, f"{where}.values") for v in values) if v),
411
+ _text(item.get("text"), f"{where}.text"),
412
+ _text(item.get("into"), f"{where}.into"),
413
+ )
414
+
415
+
416
+ def _parse_source(item: object, index: int) -> SourceDraft:
417
+ where = f"sources[{index}]"
418
+ if not isinstance(item, Mapping):
419
+ raise BadRequest(f"{where} must be an object")
420
+ kind = _text(item.get("kind"), f"{where}.kind")
421
+ if kind not in ("table", "sheet"):
422
+ raise BadRequest(f"{where}.kind must be table or sheet")
423
+ name = _text(item.get("name"), f"{where}.name")
424
+ if not name:
425
+ raise BadRequest(f"{where}.name is required")
426
+ if isinstance(item.get("raw"), Mapping):
427
+ return SourceDraft(kind, name, None, None, "", "", (), {}, item["raw"])
428
+ row = item.get("header_row")
429
+ header_row = None if row in (None, "") else row
430
+ if header_row is not None and (
431
+ isinstance(header_row, bool) or not isinstance(header_row, int)
432
+ ):
433
+ try:
434
+ header_row = int(str(header_row))
435
+ except ValueError:
436
+ raise BadRequest(f"{where}.header_row must be a number") from None
437
+ role_id = _text(item.get("role"), f"{where}.role")
438
+ columns = item.get("columns", [])
439
+ extra = item.get("extra", {})
440
+ if not isinstance(columns, list) or not isinstance(extra, Mapping):
441
+ raise BadRequest(f"{where} has columns or extra of the wrong shape")
442
+ return SourceDraft(
443
+ kind,
444
+ name,
445
+ header_row,
446
+ role_named(role_id) if role_id else None,
447
+ _text(item.get("field"), f"{where}.field"),
448
+ _text(item.get("id_prefix"), f"{where}.id_prefix"),
449
+ tuple(
450
+ _parse_column(column, f"{where}.columns[{i}]")
451
+ for i, column in enumerate(columns)
452
+ ),
453
+ extra,
454
+ headings=_parse_headings(item.get("headings"), f"{where}.headings"),
455
+ )
456
+
457
+
458
+ def _build_headings(draft: SourceDraft) -> dict[str, Any]:
459
+ headings = draft.headings
460
+ assert headings is not None
461
+ if not headings.column:
462
+ raise GuiError(f"{draft.where}: choose which column marks a heading row")
463
+ if not headings.values:
464
+ raise GuiError(
465
+ f"{draft.where}: say which value in {headings.column!r} marks a heading row, such as Heading"
466
+ )
467
+ if not headings.into:
468
+ raise GuiError(f"{draft.where}: say which column receives the category")
469
+ return headings.to_json()
470
+
471
+
472
+ def build_source(draft: SourceDraft, id_column: str) -> dict[str, Any]:
473
+ if draft.raw is not None:
474
+ return dict(draft.raw)
475
+ assert draft.role is not None
476
+ role = draft.role
477
+ if draft.headings and not role.headings:
478
+ raise BadRequest(f"{draft.where}: {role.label} cannot have heading rows")
479
+ source: dict[str, Any] = {draft.kind: draft.name}
480
+ if draft.kind == "sheet" and draft.header_row is not None:
481
+ source["header_row"] = draft.header_row
482
+ if role.type:
483
+ source["type"] = role.type
484
+ if role.merge:
485
+ source["merge"] = True
486
+ if not any(c.action == MAP and c.to == ID_COLUMN for c in draft.columns):
487
+ raise GuiError(
488
+ f"{draft.where}: choose which column holds the requirement ID, so each row finds its requirement"
489
+ )
490
+ empty = [c.header for c in draft.columns if c.action == MAP and not c.to]
491
+ if empty:
492
+ raise GuiError(
493
+ f"{draft.where}: choose where {empty[0]!r} goes, keep it as it is, or leave it out"
494
+ )
495
+ columns = {
496
+ c.header: out
497
+ for c in draft.columns
498
+ if c.action == MAP
499
+ and (out := id_column if c.to == ID_COLUMN else c.to) != c.header
500
+ }
501
+ outputs = [c.output for c in draft.columns if c.action != EXCLUDE]
502
+ for output, count in Counter(outputs).items():
503
+ if count > 1:
504
+ raise GuiError(f"{draft.where}: more than one column goes to {output!r}")
505
+ if columns:
506
+ source["columns"] = columns
507
+ exclude = [c.header for c in draft.columns if c.action == EXCLUDE]
508
+ if exclude:
509
+ source["exclude"] = exclude
510
+ lists = {
511
+ (id_column if c.output == ID_COLUMN else c.output): c.separator
512
+ for c in draft.columns
513
+ if c.action != EXCLUDE and c.separator
514
+ }
515
+ if lists:
516
+ source["lists"] = lists
517
+ constants = dict(draft.extra.get("set", {}))
518
+ if role.needs_field and FIELD_COLUMN not in outputs:
519
+ if not draft.field:
520
+ raise GuiError(
521
+ f"{draft.where}: say which column these values are for, or map a column to {FIELD_COLUMN!r}"
522
+ )
523
+ constants[FIELD_COLUMN] = draft.field
524
+ if constants:
525
+ source["set"] = constants
526
+ if draft.id_prefix and not role.merge:
527
+ source["id_prefix"] = draft.id_prefix
528
+ if draft.headings:
529
+ source["headings"] = _build_headings(draft)
530
+ return {
531
+ **source,
532
+ **{k: v for k, v in draft.extra.items() if k not in source and k != "set"},
533
+ }
534
+
535
+
536
+ def build_mapping(form: Mapping[str, Any]) -> dict[str, Any]:
537
+ """The JSON configuration a form describes, validated the way the importer validates it."""
538
+ if not isinstance(form, Mapping) or not isinstance(form.get("sources"), list):
539
+ raise BadRequest("expected {sources: [...]}")
540
+ id_column = _text(form.get("id_column"), "id_column") or ID_COLUMN
541
+ extra = form.get("extra", {})
542
+ xlsx_extra = form.get("xlsx_extra", {})
543
+ if not isinstance(extra, Mapping) or not isinstance(xlsx_extra, Mapping):
544
+ raise BadRequest("extra must be an object")
545
+ drafts = [_parse_source(item, i) for i, item in enumerate(form["sources"])]
546
+ chosen = [d for d in drafts if d.raw is not None or d.role is not None]
547
+ if not chosen:
548
+ raise GuiError(
549
+ "Choose at least one table or sheet to import, and say what it holds."
550
+ )
551
+ sources = [build_source(draft, id_column) for draft in chosen]
552
+ mapping = {
553
+ "id_column": id_column,
554
+ "traceability": True,
555
+ **{
556
+ k: v
557
+ for k, v in extra.items()
558
+ if k not in ("id_column", "traceability", "xlsx")
559
+ },
560
+ "xlsx": {
561
+ **{k: v for k, v in xlsx_extra.items() if k != "sources"},
562
+ "sources": sources,
563
+ },
564
+ }
565
+ try:
566
+ validate_xlsx_sources(sources)
567
+ except ConfigError as exc:
568
+ raise GuiError(str(exc)) from exc
569
+ return mapping
570
+
571
+
572
+ def form_from_mapping(mapping: object) -> tuple[dict[str, Any], list[str]]:
573
+ """Best effort inverse of build_mapping. Anything the form cannot show is kept untouched and listed in the notes."""
574
+ if not isinstance(mapping, Mapping):
575
+ raise GuiError(
576
+ "That file is not a reqtable settings file: its top level must be a JSON object."
577
+ )
578
+ xlsx = mapping.get("xlsx")
579
+ sources = xlsx.get("sources") if isinstance(xlsx, Mapping) else None
580
+ if not isinstance(sources, list) or not sources:
581
+ raise GuiError(
582
+ "That settings file has no xlsx.sources, so there is no workbook mapping to edit."
583
+ )
584
+ notes: list[str] = []
585
+ extra = {
586
+ k: v
587
+ for k, v in mapping.items()
588
+ if k not in ("id_column", "traceability", "xlsx")
589
+ }
590
+ xlsx_extra = {k: v for k, v in xlsx.items() if k != "sources"} # type: ignore[union-attr]
591
+ for key in extra:
592
+ notes.append(f"Kept as it is, not editable here: {key}")
593
+ for key in xlsx_extra:
594
+ notes.append(f"Kept as it is, not editable here: xlsx.{key}")
595
+ if mapping.get("traceability") is False:
596
+ notes.append(
597
+ "The file turns traceability off. Sources with a record type need it, so it is switched on."
598
+ )
599
+ id_column = mapping.get("id_column") or ID_COLUMN
600
+ form_sources = [
601
+ _source_form(source, index, notes, id_column)
602
+ for index, source in enumerate(sources)
603
+ ]
604
+ return {
605
+ "id_column": mapping.get("id_column") or ID_COLUMN,
606
+ "sources": form_sources,
607
+ "extra": extra,
608
+ "xlsx_extra": xlsx_extra,
609
+ }, notes
610
+
611
+
612
+ def _loadable_headings(headings: object) -> HeadingRows | None:
613
+ try:
614
+ validate_headings(headings, "headings")
615
+ except ConfigError:
616
+ return None
617
+ return HeadingRows.from_json(headings) # type: ignore[arg-type]
618
+
619
+
620
+ def _source_form(
621
+ source: object, index: int, notes: list[str], id_column: str
622
+ ) -> dict[str, Any]:
623
+ if not isinstance(source, Mapping) or ("table" in source) == ("sheet" in source):
624
+ raise GuiError(
625
+ f"xlsx.sources[{index}] needs exactly one of 'table' or 'sheet'."
626
+ )
627
+ kind = "table" if "table" in source else "sheet"
628
+ name = str(source[kind])
629
+ constants = (
630
+ dict(source.get("set", {})) if isinstance(source.get("set"), Mapping) else {}
631
+ )
632
+ type_name = source.get("type") or constants.get("Type")
633
+ role = (
634
+ role_for_type(type_name)
635
+ if type_name != "Requirement"
636
+ else ROLES_BY_ID["requirements"]
637
+ )
638
+ if source.get("merge") is True:
639
+ role = ROLES_BY_ID["merge"] if not type_name else None
640
+ if role is None or ("type" in source and "Type" in constants):
641
+ notes.append(
642
+ f"{kind.capitalize()} {name!r} has a record type this form cannot edit, so it is kept exactly as it is."
643
+ )
644
+ return {"kind": kind, "name": name, "raw": dict(source)}
645
+ headings = _loadable_headings(source.get("headings")) if role.headings else None
646
+ handled = {
647
+ kind,
648
+ "header_row",
649
+ "columns",
650
+ "exclude",
651
+ "lists",
652
+ "id_prefix",
653
+ "set",
654
+ "type",
655
+ "merge",
656
+ *(("headings",) if headings else ()),
657
+ }
658
+ extra = {k: v for k, v in source.items() if k not in handled}
659
+ if type_name == "Requirement":
660
+ extra["type"] = "Requirement"
661
+ constants.pop("Type", None)
662
+ field = constants.pop(FIELD_COLUMN, "") if role.needs_field else ""
663
+ if constants:
664
+ extra["set"] = {**extra.get("set", {}), **constants}
665
+ for key in extra:
666
+ notes.append(
667
+ f"{kind.capitalize()} {name!r}: kept as it is, not editable here: {key}"
668
+ )
669
+ columns: dict[str, dict[str, Any]] = {}
670
+ for header, to in (source.get("columns") or {}).items():
671
+ columns[header] = {
672
+ "header": header,
673
+ "action": MAP,
674
+ "to": ID_COLUMN if to == id_column else to,
675
+ "separator": "",
676
+ }
677
+ for header in source.get("exclude") or []:
678
+ columns[header] = {
679
+ "header": header,
680
+ "action": EXCLUDE,
681
+ "to": "",
682
+ "separator": "",
683
+ }
684
+ for output, separator in (
685
+ (ID_COLUMN if k == id_column else k, v)
686
+ for k, v in (source.get("lists") or {}).items()
687
+ ):
688
+ match = next(
689
+ (c for c in columns.values() if c["action"] == MAP and c["to"] == output),
690
+ None,
691
+ ) or columns.setdefault(
692
+ output, {"header": output, "action": KEEP, "to": "", "separator": ""}
693
+ )
694
+ match["separator"] = separator
695
+ if (
696
+ role.needs_field
697
+ and not field
698
+ and FIELD_COLUMN
699
+ not in {
700
+ c["to"] if c["action"] == MAP else c["header"] for c in columns.values()
701
+ }
702
+ ):
703
+ columns[FIELD_COLUMN] = {
704
+ "header": FIELD_COLUMN,
705
+ "action": KEEP,
706
+ "to": "",
707
+ "separator": "",
708
+ }
709
+ return {
710
+ "kind": kind,
711
+ "name": name,
712
+ "header_row": source.get("header_row"),
713
+ "role": role.id,
714
+ "field": field,
715
+ "id_prefix": source.get("id_prefix", ""),
716
+ "columns": list(columns.values()),
717
+ "extra": extra,
718
+ "headings": headings.to_json() if headings else None,
719
+ }
720
+
721
+
722
+ def _heading_summary(headings: Mapping[str, Any], stats: SourceStats) -> dict[str, Any]:
723
+ found = Counter(stats.categories)
724
+ return {
725
+ "removed": stats.headings_removed,
726
+ "categories": [
727
+ {"name": name, "count": count} for name, count in found.items() if name
728
+ ],
729
+ "uncategorised": found.get("", 0),
730
+ "warning": None
731
+ if stats.headings_removed
732
+ else f"No row in {headings['column']!r} says {' or '.join(headings['values'])}.",
733
+ }
734
+
735
+
736
+ def preview_mapping(workbook: Path, mapping: Mapping[str, Any]) -> dict[str, Any]:
737
+ """Run the importer on the draft once: rows per source, record types and warnings, or the error the CLI would give."""
738
+ sources = mapping["xlsx"]["sources"]
739
+ try:
740
+ imported = import_workbook(
741
+ workbook, XlsxSelection(), sources, mapping["id_column"], True, False
742
+ )
743
+ except (ReqtableError, OSError) as exc:
744
+ return {"error": str(exc)}
745
+ counts = []
746
+ for source, stats in zip(sources, imported.sources):
747
+ entry: dict[str, Any] = {"name": stats.name, "rows": stats.rows}
748
+ if "headings" in source:
749
+ entry["headings"] = _heading_summary(source["headings"], stats)
750
+ counts.append(entry)
751
+ rows = imported.block.rows
752
+ type_at = rows[0].index("Type") if "Type" in rows[0] else None
753
+ types = Counter(
754
+ (row[type_at].strip() if type_at is not None else "") or "Requirement"
755
+ for row in rows[1:]
756
+ )
757
+ return {
758
+ "sources": counts,
759
+ "types": dict(types),
760
+ "total": len(rows) - 1,
761
+ "warnings": list(imported.warnings),
762
+ }
763
+
764
+
765
+ def save_mapping(
766
+ workdir: Path, path: str, mapping: Mapping[str, Any], overwrite: bool
767
+ ) -> dict[str, Any]:
768
+ if not path.strip():
769
+ raise GuiError("Choose where to save the mapping.")
770
+ target = workdir / path
771
+ if target.suffix.lower() != ".json":
772
+ raise GuiError("The mapping file name must end in .json.")
773
+ if target.exists() and not overwrite:
774
+ return {"exists": True, "path": str(target)}
775
+ atomic_write_text(str(target), json.dumps(mapping, indent=2) + "\n")
776
+ return {"saved": str(target)}
777
+
778
+
779
+ def load_mapping(workdir: Path, path: str) -> dict[str, Any]:
780
+ if not path.strip():
781
+ raise GuiError("Choose a mapping file to load.")
782
+ try:
783
+ mapping = json.loads((workdir / path).read_text(encoding="utf-8"))
784
+ except OSError as exc:
785
+ raise GuiError(f"Cannot read {path}: {exc.strerror or exc}") from exc
786
+ except ValueError as exc:
787
+ raise GuiError(f"{path} is not valid JSON: {exc}") from exc
788
+ form, notes = form_from_mapping(mapping)
789
+ return {"form": form, "notes": notes}