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/gates.py ADDED
@@ -0,0 +1,348 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ from dataclasses import dataclass
5
+ from functools import cached_property
6
+ from typing import Any, Callable, Sequence
7
+
8
+ from .baselines import links, record_type, select_scope
9
+ from .core import RECORD_TYPES, ConfigError, validate_enforcement
10
+ from .findings import trace_findings
11
+
12
+ Finding = tuple["str | None", str, str]
13
+
14
+ MAX_LISTED = 10
15
+ CHANGE_FINDING = re.compile(
16
+ r"(?:Changed|Added|Removed) since .+ without an approved change request\."
17
+ )
18
+
19
+
20
+ @dataclass
21
+ class Table:
22
+ rows: list[dict[str, str]]
23
+ all_rows: list[dict[str, str]]
24
+ id_column: str
25
+ findings: Sequence[Finding]
26
+
27
+ def rid(self, row: dict[str, str]) -> str:
28
+ return row[self.id_column].strip()
29
+
30
+ @cached_property
31
+ def record_ids(self) -> set[str]:
32
+ return {self.rid(row) for row in self.all_rows}
33
+
34
+ @cached_property
35
+ def leaf_systems(self) -> set[str]:
36
+ systems = [row for row in self.all_rows if record_type(row) == "System"]
37
+ parents = {
38
+ parent for row in systems for parent in links(row.get("Part of", ""))
39
+ }
40
+ return {self.rid(row) for row in systems} - parents
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class Outcome:
45
+ failing: list[str]
46
+ total: int
47
+ global_messages: list[str]
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class Condition:
52
+ """One entry of the check vocabulary: its config rules, the columns it reads, and its per-record test."""
53
+
54
+ key: str
55
+ validate: Callable[[Any, str], None]
56
+ columns: Callable[[Any], list[str]]
57
+ passes: Callable[[Any, dict[str, Any], dict[str, str], Table], bool]
58
+
59
+
60
+ def _validate_column(value: Any, where: str) -> None:
61
+ if not isinstance(value, str) or not value.strip():
62
+ raise ConfigError(f"{where}: must name a column")
63
+
64
+
65
+ def _validate_in(value: Any, where: str) -> None:
66
+ ok = isinstance(value, dict) and len(value) == 1
67
+ if ok:
68
+ ((column, allowed),) = value.items()
69
+ ok = (
70
+ bool(column.strip())
71
+ and isinstance(allowed, list)
72
+ and bool(allowed)
73
+ and all(isinstance(item, str) and item.strip() for item in allowed)
74
+ )
75
+ if not ok:
76
+ raise ConfigError(
77
+ f"{where}: must be an object with one column and a non-empty array of allowed values"
78
+ )
79
+
80
+
81
+ def _validate_true(value: Any, where: str) -> None:
82
+ if value is not True:
83
+ raise ConfigError(f"{where}: must be true")
84
+
85
+
86
+ def _filled(
87
+ column: str, check: dict[str, Any], row: dict[str, str], table: Table
88
+ ) -> bool:
89
+ return bool(row.get(column, "").strip())
90
+
91
+
92
+ def _in(
93
+ value: dict[str, list[str]],
94
+ check: dict[str, Any],
95
+ row: dict[str, str],
96
+ table: Table,
97
+ ) -> bool:
98
+ ((column, allowed),) = value.items()
99
+ cell = links(row.get(column, ""))
100
+ return bool(cell) and all(part in allowed for part in cell)
101
+
102
+
103
+ def _linked(
104
+ column: str, check: dict[str, Any], row: dict[str, str], table: Table
105
+ ) -> bool:
106
+ valid = table.leaf_systems if check.get("leaf") else table.record_ids
107
+ return any(target in valid for target in links(row.get(column, "")))
108
+
109
+
110
+ CONDITIONS: dict[str, Condition] = {
111
+ condition.key: condition
112
+ for condition in (
113
+ Condition("filled", _validate_column, lambda v: [v], _filled),
114
+ Condition("in", _validate_in, lambda v: list(v), _in),
115
+ Condition("linked", _validate_column, lambda v: [v], _linked),
116
+ Condition(
117
+ "no_findings", _validate_true, lambda v: [], lambda v, c, row, t: True
118
+ ),
119
+ Condition(
120
+ "unchanged_since", _validate_true, lambda v: [], lambda v, c, row, t: True
121
+ ),
122
+ )
123
+ }
124
+ WHOLE_RECORD_CONDITIONS = ("no_findings", "unchanged_since")
125
+
126
+ CHECK_KEYS = {"id", "description", "applies_to", "leaf", "enforcement", *CONDITIONS}
127
+
128
+
129
+ def _validate_applies_to(applies: Any, where: str) -> None:
130
+ if not isinstance(applies, dict):
131
+ raise ConfigError(f"{where}.applies_to must be an object")
132
+ for key, value in applies.items():
133
+ values = value if isinstance(value, list) else [value]
134
+ if not key.strip() or not values or not all(isinstance(v, str) for v in values):
135
+ raise ConfigError(
136
+ f"{where}.applies_to.{key} must be a string or a non-empty array of strings"
137
+ )
138
+ unknown = [v for v in values if key == "type" and v not in RECORD_TYPES]
139
+ if unknown:
140
+ raise ConfigError(
141
+ f"{where}.applies_to.type: unknown record type {unknown[0]!r}"
142
+ )
143
+
144
+
145
+ def validate_checks(checks: Any, gate_where: str) -> None:
146
+ if not isinstance(checks, list):
147
+ raise ConfigError(f"{gate_where}.checks must be an array")
148
+ seen: set[str] = set()
149
+ for index, check in enumerate(checks):
150
+ name = check.get("id") if isinstance(check, dict) else None
151
+ where = (
152
+ f"{gate_where}.checks[{name if isinstance(name, str) and name else index}]"
153
+ )
154
+ if not isinstance(check, dict):
155
+ raise ConfigError(f"{where} must be an object")
156
+ for key in ("id", "description"):
157
+ if not isinstance(check.get(key), str) or not check[key].strip():
158
+ raise ConfigError(f"{where}.{key} must be a non-empty string")
159
+ if check["id"] in seen:
160
+ raise ConfigError(f"{where}: duplicate check ID")
161
+ seen.add(check["id"])
162
+ unknown = sorted(set(check) - CHECK_KEYS)
163
+ if unknown:
164
+ raise ConfigError(f"unknown configuration key: {where}.{unknown[0]}")
165
+ used = [key for key in CONDITIONS if key in check]
166
+ if len(used) != 1:
167
+ raise ConfigError(
168
+ f"{where} needs exactly one condition: {', '.join(CONDITIONS)}"
169
+ )
170
+ if "leaf" in check and (
171
+ used[0] != "linked" or not isinstance(check["leaf"], bool)
172
+ ):
173
+ raise ConfigError(
174
+ f"{where}: 'leaf' must be true or false and applies only to 'linked'"
175
+ )
176
+ CONDITIONS[used[0]].validate(check[used[0]], f"{where}.{used[0]}")
177
+ if "applies_to" in check:
178
+ _validate_applies_to(check["applies_to"], where)
179
+ if "enforcement" in check:
180
+ validate_enforcement(check["enforcement"], f"{where}.enforcement")
181
+
182
+
183
+ def _applies(check: dict[str, Any], row: dict[str, str]) -> bool:
184
+ default = (
185
+ {}
186
+ if any(key in check for key in WHOLE_RECORD_CONDITIONS)
187
+ else {"type": "Requirement"}
188
+ )
189
+ for key, wanted in check.get("applies_to", default).items():
190
+ allowed = wanted if isinstance(wanted, list) else [wanted]
191
+ if (
192
+ record_type(row) if key == "type" else row.get(key, "").strip()
193
+ ) not in allowed:
194
+ return False
195
+ return True
196
+
197
+
198
+ def _no_findings(records: list[dict[str, str]], table: Table) -> Outcome:
199
+ flagged = {finding[0] for finding in table.findings if finding[0] is not None}
200
+ failing = [table.rid(row) for row in records if table.rid(row) in flagged]
201
+ messages = [finding[2] for finding in table.findings if finding[0] is None]
202
+ return Outcome(
203
+ failing + ([""] if messages else []), len(records) + bool(messages), messages
204
+ )
205
+
206
+
207
+ def _unchanged_since(
208
+ records: list[dict[str, str]],
209
+ table: Table,
210
+ controls: dict[str, Any] | None,
211
+ system: str | None,
212
+ id_column: str,
213
+ ) -> Outcome:
214
+ removed = [
215
+ record_id
216
+ for record_id in (controls["records"] if controls else {})
217
+ if record_id not in table.record_ids
218
+ ]
219
+ if system and removed:
220
+ gone = [controls["records"][record_id]["row"] for record_id in removed]
221
+ in_scope = {
222
+ table.rid(row)
223
+ for row in select_scope(
224
+ [*table.all_rows, *gone], id_column, system, RECORD_TYPES
225
+ )
226
+ }
227
+ removed = [record_id for record_id in removed if record_id in in_scope]
228
+ counted = {*map(table.rid, records), *removed}
229
+ changed = dict.fromkeys(
230
+ finding[0] for finding in table.findings if CHANGE_FINDING.fullmatch(finding[2])
231
+ )
232
+ return Outcome(
233
+ [record_id for record_id in changed if record_id in counted],
234
+ len(records) + len(removed),
235
+ [],
236
+ )
237
+
238
+
239
+ def evaluate_check(
240
+ check: dict[str, Any],
241
+ rows: Sequence[dict[str, str]],
242
+ headers: Sequence[str],
243
+ id_column: str,
244
+ system: str | None,
245
+ findings: Sequence[Finding],
246
+ controls: dict[str, Any] | None = None,
247
+ ) -> dict[str, Any]:
248
+ result: dict[str, Any] = {
249
+ "id": check["id"],
250
+ "description": check["description"],
251
+ "enforcement": check.get("enforcement", "advisory"),
252
+ "error": None,
253
+ }
254
+ key = next(key for key in CONDITIONS if key in check)
255
+ condition = CONDITIONS[key]
256
+ columns = [
257
+ *(k for k in check.get("applies_to", {}) if k != "type"),
258
+ *condition.columns(check[key]),
259
+ ]
260
+ for column in columns:
261
+ if column not in headers:
262
+ return {**result, "error": f"The table has no “{column}” column."}
263
+ scoped = (
264
+ select_scope(rows, id_column, system, RECORD_TYPES) if system else list(rows)
265
+ )
266
+ table = Table(scoped, list(rows), id_column, findings)
267
+ records = [row for row in scoped if _applies(check, row)]
268
+ if key == "no_findings":
269
+ outcome = _no_findings(records, table)
270
+ elif key == "unchanged_since":
271
+ outcome = _unchanged_since(records, table, controls, system, id_column)
272
+ else:
273
+ failing = [
274
+ table.rid(row)
275
+ for row in records
276
+ if not condition.passes(check[key], check, row, table)
277
+ ]
278
+ outcome = Outcome(failing, len(records), [])
279
+ return {
280
+ **result,
281
+ "total": outcome.total,
282
+ "failing": outcome.failing,
283
+ "global": outcome.global_messages,
284
+ }
285
+
286
+
287
+ def evaluate_gate(
288
+ gate: dict[str, Any],
289
+ rows: Sequence[dict[str, str]],
290
+ headers: Sequence[str],
291
+ id_column: str,
292
+ system: str | None,
293
+ findings: Sequence[Finding],
294
+ controls: dict[str, Any] | None = None,
295
+ ) -> dict[str, Any]:
296
+ checks = [
297
+ evaluate_check(check, rows, headers, id_column, system, findings, controls)
298
+ for check in gate.get("checks", [])
299
+ ]
300
+ failed = [
301
+ check for check in checks if check["error"] is not None or check["failing"]
302
+ ]
303
+ blocking = [check["id"] for check in failed if check["enforcement"] == "strict"]
304
+ return {
305
+ "gate": gate["id"],
306
+ "name": gate.get("name", gate["id"]),
307
+ "system": system,
308
+ "ready": not failed,
309
+ "blocking": blocking,
310
+ "blocked": bool(blocking),
311
+ "checks": checks,
312
+ }
313
+
314
+
315
+ def table_findings(
316
+ rows: Sequence[dict[str, str]],
317
+ headers: Sequence[str],
318
+ id_column: str,
319
+ controls: dict[str, Any] | None = None,
320
+ ) -> list[Finding]:
321
+ return [
322
+ (f.id, f.field, f.message)
323
+ for f in trace_findings(list(rows), list(headers), id_column, controls)
324
+ ]
325
+
326
+
327
+ def format_result(result: dict[str, Any]) -> list[str]:
328
+ scope = f" for {result['system']}" if result["system"] else ""
329
+ blocked = ", blocked" if result["blocked"] else ""
330
+ lines = [
331
+ f"{result['gate']} {result['name']}{scope}: {'ready' if result['ready'] else 'not ready'}{blocked}"
332
+ ]
333
+ for check in result["checks"]:
334
+ level = f"({check['enforcement']})"
335
+ if check["error"]:
336
+ lines.append(f" ERROR {level} {check['id']} {check['error']}")
337
+ elif check["failing"]:
338
+ shown = ", ".join(
339
+ found or "(table)" for found in check["failing"][:MAX_LISTED]
340
+ )
341
+ more = ", …" if len(check["failing"]) > MAX_LISTED else ""
342
+ lines.append(
343
+ f" FAIL {level} {check['id']} {check['description']}: "
344
+ f"{len(check['failing'])} of {check['total']} records: {shown}{more}"
345
+ )
346
+ else:
347
+ lines.append(f" pass {check['id']} {check['description']}")
348
+ return lines
reqtable/glossary.py ADDED
@@ -0,0 +1,162 @@
1
+ """Project glossary matching and inline definitions for traceability reports."""
2
+
3
+ GLOSSARY_COLUMNS = ("Definition", "Aliases", "Auto Link")
4
+
5
+ GLOSSARY_MODEL_JS = r"""
6
+ function glossaryEligible(spelling,allowSingle){
7
+ const words=spelling.split(/[\s-]+/u);
8
+ const acronym=/^[\p{Lu}0-9]+(?:-[\p{Lu}0-9]+)*$/u.test(spelling)
9
+ &&(spelling.match(/\p{Lu}/gu)?.length??0)>=2;
10
+ if(acronym)return true;
11
+ const titleWord=/^\p{Lu}[\p{L}\p{M}\p{N}'’]*$/u;
12
+ const connector=/^(?:a|an|and|for|in|of|on|or|the|to|with)$/u;
13
+ if(words.length===1)return allowSingle&&titleWord.test(spelling);
14
+ return titleWord.test(words[0])&&titleWord.test(words.at(-1))
15
+ &&words.slice(1,-1).every(word=>titleWord.test(word)||connector.test(word));
16
+ }
17
+ function buildGlossary(records,issue){
18
+ const names=new Map(),spellings=new Map();
19
+ for(const record of records){
20
+ if(record.type!=="Term")continue;
21
+ const {id,row}=record,name=row.Name?.trim()??"",definition=row.Definition?.trim()??"";
22
+ if(!name)issue(id,"Name","Enter a glossary term name.");
23
+ if(!definition)issue(id,"Definition","Enter a glossary definition.");
24
+ if(name){
25
+ const key=name.toLowerCase(),group=names.get(key)??[];
26
+ group.push(record);
27
+ names.set(key,group);
28
+ }
29
+ const allowSingle=row["Auto Link"]?.trim().toLowerCase()==="yes";
30
+ for(const [spelling,field] of [[name,"Name"],...traceIds(row.Aliases).map(alias=>[alias,"Aliases"])]){
31
+ if(!spelling)continue;
32
+ const group=spellings.get(spelling)??new Map();
33
+ if(!group.has(id))group.set(id,{record,field,eligible:glossaryEligible(spelling,allowSingle)});
34
+ spellings.set(spelling,group);
35
+ }
36
+ }
37
+ const ambiguousNames=new Set();
38
+ for(const group of names.values()){
39
+ if(group.length<2)continue;
40
+ for(const {id,row} of group){
41
+ issue(id,"Name","Another glossary record uses this term name.");
42
+ ambiguousNames.add(row.Name.trim());
43
+ }
44
+ }
45
+ const lookup=new Map();
46
+ for(const [spelling,group] of spellings){
47
+ const entries=[...group.values()];
48
+ if(entries.length>1){
49
+ for(const {record,field} of entries){
50
+ if(field!=="Name"||!ambiguousNames.has(spelling)){
51
+ issue(record.id,field,`Glossary spelling “${spelling}” is shared by multiple terms.`);
52
+ }
53
+ }
54
+ }
55
+ if(!entries.some(entry=>entry.eligible))continue;
56
+ const {record}=entries[0];
57
+ lookup.set(spelling,group.size===1&&!ambiguousNames.has(spelling)
58
+ &&record.row.Name?.trim()&&record.row.Definition?.trim()?record:null);
59
+ }
60
+ const patterns=[...lookup.keys()].sort((a,b)=>b.length-a.length)
61
+ .map(spelling=>spelling.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"));
62
+ const address=String.raw`(?:[a-zA-Z][a-zA-Z\d+.-]*://|www\.|mailto:)[^\s<>]+|[\p{L}\p{N}._%+-]+@[\p{L}\p{N}.-]+\.[\p{L}]{2,}`;
63
+ const word=String.raw`[\p{L}\p{M}\p{N}_]`;
64
+ const pattern=patterns.length&&new RegExp(
65
+ `(?:${address})|(?<!${word})(${patterns.join("|")})(?!${word})`,"gu");
66
+ return {enabled:Boolean(pattern),matches(text){
67
+ if(!pattern)return [];
68
+ return [...text.matchAll(pattern)].flatMap(match=>{
69
+ const record=lookup.get(match[1]);
70
+ return record?[{record,start:match.index,text:match[0]}]:[];
71
+ });
72
+ }};
73
+ }
74
+ """
75
+
76
+ GLOSSARY_UI_JS = r"""
77
+ function createGlossaryPopover(jump){
78
+ const popup=$("#glossary-definition"),title=$("#glossary-definition-title");
79
+ const content=$("#glossary-definition-content"),sources=$("#glossary-definition-sources");
80
+ const popover=anchoredPopover(popup),close=popover.close;
81
+ function open(button,record){
82
+ popover.open(button,()=>{
83
+ title.textContent=record.row.Name.trim();
84
+ content.innerHTML=renderCommentMarkdown(record.row.Definition.trim());
85
+ sources.replaceChildren();
86
+ const references=record.outgoing.get("Source refs")??[];
87
+ const jumpButton=(id,text)=>{
88
+ const button=document.createElement("button");
89
+ button.type="button";
90
+ button.className="glossary-jump";
91
+ button.textContent=text;
92
+ button.addEventListener("click",()=>{close();jump(id);});
93
+ return button;
94
+ };
95
+ if(references.length){
96
+ sources.append("Sources: ");
97
+ references.forEach(({row,id},i)=>sources.append(...(i?[", "]:[]),jumpButton(id,row.Name?.trim()||id)));
98
+ sources.append(document.createElement("br"));
99
+ }
100
+ sources.append(jumpButton(record.id,"Show in glossary"));
101
+ return title;
102
+ });
103
+ }
104
+ $("#glossary-definition-close").addEventListener("click",()=>close(true));
105
+ return {close,decorate(glossary,rows){
106
+ if(!glossary.enabled)return;
107
+ const columns=["Requirement","Acceptance Criteria","Rationale"];
108
+ for(const cell of [...rows].flatMap(row=>[...row.querySelectorAll("[data-grid-cell]")])){
109
+ if(!columns.includes(cell.dataset.column))continue;
110
+ const wrapper=cell.querySelector(".cell-wrap");
111
+ if(!wrapper)continue;
112
+ const walker=document.createTreeWalker(wrapper,NodeFilter.SHOW_TEXT,{acceptNode(node){
113
+ return node.parentElement.closest("a,code,pre,button,.empty-value,.missing,.pane-label")
114
+ ?NodeFilter.FILTER_REJECT:NodeFilter.FILTER_ACCEPT;
115
+ }});
116
+ const nodes=[];
117
+ while(walker.nextNode())nodes.push(walker.currentNode);
118
+ for(const node of nodes){
119
+ const matches=glossary.matches(node.data);
120
+ if(!matches.length)continue;
121
+ const fragment=document.createDocumentFragment();
122
+ let end=0;
123
+ for(const {record,start,text} of matches){
124
+ fragment.append(node.data.slice(end,start));
125
+ const button=document.createElement("button");
126
+ button.type="button";
127
+ button.className="glossary-link";
128
+ button.textContent=text;
129
+ button.setAttribute("aria-haspopup","dialog");
130
+ button.setAttribute("aria-controls",popup.id);
131
+ button.setAttribute("aria-expanded","false");
132
+ button.addEventListener("click",()=>open(button,record));
133
+ fragment.append(button);
134
+ end=start+text.length;
135
+ }
136
+ fragment.append(node.data.slice(end));
137
+ node.replaceWith(fragment);
138
+ }
139
+ }
140
+ }};
141
+ }
142
+ """
143
+
144
+ GLOSSARY_HTML = """
145
+ <section id="glossary-definition" class="floating-popover" role="dialog" aria-labelledby="glossary-definition-title" hidden>
146
+ <div class="popover-head">
147
+ <h3 id="glossary-definition-title" tabindex="-1"></h3>
148
+ <button type="button" class="popover-close" id="glossary-definition-close" aria-label="Close definition">×</button>
149
+ </div>
150
+ <div class="markdown" id="glossary-definition-content"></div>
151
+ <p id="glossary-definition-sources" class="meta"></p>
152
+ </section>
153
+ """
154
+
155
+ GLOSSARY_CSS = """
156
+ .glossary-link {max-width:100%;padding:0;border:0;border-radius:2px;background:transparent;color:inherit;text-align:inherit;overflow-wrap:anywhere;text-decoration:underline dotted var(--accent);text-underline-offset:.19em}
157
+ .glossary-link:hover,.glossary-link[aria-expanded="true"] {color:var(--accent)}
158
+ #glossary-definition-sources {margin:8px 0 0}
159
+ .glossary-jump {display:inline;width:auto;height:auto;padding:0;border:0;background:none;color:var(--accent);font:inherit;text-decoration:underline;cursor:pointer}
160
+ #glossary-definition-sources:empty {display:none}
161
+ @media print {.glossary-link {text-decoration:none}}
162
+ """