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/quality.py ADDED
@@ -0,0 +1,422 @@
1
+ """Offline requirement quality rules and report controls."""
2
+
3
+ QUALITY_JS = r"""
4
+ const qualityPanel=$("#quality-panel");
5
+ const quality={checked:false,only:false,revealId:null,activeCell:null,findings:new Map()};
6
+ const qualityHeaders=data.source.new.headers.filter(name=>name!==data.meta.idColumn);
7
+ const escapeRegex=text=>text.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");
8
+ let requirementColumn,qualityColumns,obligation,obligationPattern,disabledQualityRules;
9
+ function configureQuality(){
10
+ const options=state.qualityReview.settings;
11
+ requirementColumn=options.requirement_column
12
+ ??qualityHeaders.find(name=>/^(requirement|requirement text)$/i.test(name.trim()));
13
+ qualityColumns=[...new Set([requirementColumn,...(options.required_columns??[])])]
14
+ .filter(name=>qualityHeaders.includes(name));
15
+ obligation=options.obligation===undefined?"shall":options.obligation;
16
+ obligationPattern=obligation&&new RegExp(
17
+ `(?<![\\p{L}\\p{N}_])${escapeRegex(obligation.trim())}(?![\\p{L}\\p{N}_])`,"giu");
18
+ disabledQualityRules=new Set(options.disabled_rules??[]);
19
+ }
20
+ configureQuality();
21
+ const qualityRules={
22
+ "missing-content":["Missing content","Fill in this field so readers can review and verify the requirement."],
23
+ "placeholder":["Unresolved placeholder","Record what is still open and replace the placeholder when the decision is made."],
24
+ "ambiguous-choice":["Ambiguous alternatives","State which alternatives are permitted and whether both can apply."],
25
+ "ambiguous-condition":["Vague condition","Name the condition that triggers the behavior or defines when it applies."],
26
+ "ambiguous-timing":["Vague timing","Specify the maximum elapsed time and the event it is measured from."],
27
+ "open-ended-list":["Open-ended list","State the complete set or reference a controlled list."],
28
+ "missing-obligation":["Missing obligation keyword","Check the configured obligation keyword for a binding statement."],
29
+ "multiple-obligations":["Possible multiple obligations","Check whether the obligations can be verified independently and should be separate requirements."]
30
+ };
31
+ const qualityPhrases=[
32
+ ["placeholder",/\b(?:TBD|TBR|TODO)\b/gi],
33
+ ["ambiguous-choice",/\band\/or\b/gi],
34
+ ["ambiguous-condition",/\b(?:as appropriate|as needed|when necessary|where applicable)\b/gi],
35
+ ["ambiguous-timing",/\b(?:quickly|promptly|as soon as possible|in a timely manner)\b/gi],
36
+ ["open-ended-list",/\b(?:etc\.|including but not limited to)/gi]
37
+ ];
38
+ function lintRequirementField(value,isStatement){
39
+ if(!value.trim())return disabledQualityRules.has("missing-content")
40
+ ?[]:[{rule:"missing-content",phrase:"",start:0}];
41
+ // Keep source offsets while masking examples and link destinations.
42
+ const prose=value.replace(/```[\s\S]*?```|`[^`\n]*`|\]\([^\n)]*\)|https?:\/\/[^\s<>]+/g,
43
+ match=>match.replace(/[^\r\n]/g," "));
44
+ const findings=[];
45
+ for(const [rule,pattern] of qualityPhrases){
46
+ if(disabledQualityRules.has(rule))continue;
47
+ for(const match of prose.matchAll(pattern)){
48
+ findings.push({rule,phrase:match[0],start:match.index});
49
+ }
50
+ }
51
+ if(isStatement&&obligationPattern){
52
+ const matches=[...prose.matchAll(obligationPattern)];
53
+ if(matches.length===0&&!disabledQualityRules.has("missing-obligation")){
54
+ findings.push({rule:"missing-obligation",phrase:"",start:0});
55
+ }
56
+ if(matches.length>1&&!disabledQualityRules.has("multiple-obligations")){
57
+ findings.push({rule:"multiple-obligations",phrase:matches[1][0],start:matches[1].index});
58
+ }
59
+ }
60
+ return findings;
61
+ }
62
+ function qualityDismissal(id,column,value,issue){
63
+ const keyword=issue.rule.endsWith("-obligation")||issue.rule==="multiple-obligations"?obligation:null;
64
+ return state.qualityReview.dismissals.find(record=>record.id===id&&record.column===column
65
+ &&record.value===value&&record.rule===issue.rule&&record.start===issue.start
66
+ &&record.obligation===keyword);
67
+ }
68
+ let qualityScanVersion=null;
69
+ function scanQuality(){
70
+ if(!quality.checked||qualityScanVersion===dataVersion)return;
71
+ qualityScanVersion=dataVersion;
72
+ configureQuality();
73
+ const findings=new Map();
74
+ quality.dismissed=[];
75
+ for(const row of state.currentRows){
76
+ if(data.options?.traceability&&!trace.isRequirement(row))continue;
77
+ const id=rowId(row),fields=new Map();
78
+ for(const column of qualityColumns){
79
+ const value=String(row[column]??"");
80
+ const issues=[];
81
+ for(const issue of lintRequirementField(value,column===requirementColumn)){
82
+ const dismissal=qualityDismissal(id,column,value,issue);
83
+ if(dismissal)quality.dismissed.push(dismissal);
84
+ else issues.push(issue);
85
+ }
86
+ if(issues.length)fields.set(column,issues);
87
+ }
88
+ if(fields.size)findings.set(id,fields);
89
+ }
90
+ quality.findings=findings;
91
+ }
92
+ function underlineQualityPhrases(wrapper,issues){
93
+ const phrases=[...new Set(issues.map(issue=>issue.phrase).filter(Boolean))];
94
+ if(!phrases.length)return;
95
+ const pattern=new RegExp(`(?<![\\p{L}\\p{N}_])(?:${phrases.map(escapeRegex).join("|")})(?![\\p{L}\\p{N}_])`,"giu");
96
+ const walker=document.createTreeWalker(wrapper,NodeFilter.SHOW_TEXT,{acceptNode(node){
97
+ return node.parentElement.closest("code,pre,button,.quality-phrase")
98
+ ?NodeFilter.FILTER_REJECT:NodeFilter.FILTER_ACCEPT;
99
+ }});
100
+ const nodes=[];
101
+ while(walker.nextNode())nodes.push(walker.currentNode);
102
+ for(const node of nodes){
103
+ const matches=[...node.data.matchAll(pattern)];
104
+ if(!matches.length)continue;
105
+ const fragment=document.createDocumentFragment();
106
+ let offset=0;
107
+ for(const match of matches){
108
+ fragment.append(node.data.slice(offset,match.index));
109
+ const mark=document.createElement("span");
110
+ mark.className="quality-phrase";
111
+ mark.textContent=match[0];
112
+ fragment.append(mark);
113
+ offset=match.index+match[0].length;
114
+ }
115
+ fragment.append(node.data.slice(offset));
116
+ node.replaceWith(fragment);
117
+ }
118
+ }
119
+ function paintQualityMarkers(rows=renderedRows()){
120
+ if(!quality.checked)return;
121
+ const dismissed=new Map();
122
+ for(const record of quality.dismissed??[]){
123
+ const key=`${record.id}\u0000${record.column}`;
124
+ if(!dismissed.has(key))dismissed.set(key,new Set());
125
+ dismissed.get(key).add(record.phrase.toLowerCase());
126
+ }
127
+ for(const row of rows){
128
+ const fields=quality.findings.get(row.dataset.rowId);
129
+ if(!fields)continue;
130
+ for(const cell of row.querySelectorAll("[data-grid-cell]")){
131
+ const column=cell.dataset.column,issues=fields.get(column);
132
+ const wrapper=cell.querySelector(".cell-wrap");
133
+ if(!issues||!wrapper||wrapper.querySelector(".quality-marker"))continue;
134
+ if(!diffActive()){
135
+ const dismissedPhrases=dismissed.get(`${row.dataset.rowId}\u0000${column}`)??new Set();
136
+ // When identical phrases have different review outcomes, the editor
137
+ // can select the exact occurrence using its source offset.
138
+ underlineQualityPhrases(wrapper,issues.filter(issue=>!dismissedPhrases.has(issue.phrase.toLowerCase())));
139
+ }
140
+ const id=row.dataset.rowId;
141
+ const label=`${issues.length} quality ${issues.length===1?"finding":"findings"} for ${id}, ${column}`;
142
+ wrapper.append(findingMarker("quality-marker","⚠",label,marker=>openQualityFindings(marker,id,column)));
143
+ }
144
+ }
145
+ }
146
+ function qualityEvidence({rule,phrase}){
147
+ const name=qualityRules[rule][0];
148
+ return phrase?`${name} · “${phrase}”`:name;
149
+ }
150
+ function openQualityFindings(marker,id,column){
151
+ findingPopover.open(marker,{
152
+ heading:`${id} · ${columnLabel(column)}`,
153
+ findings:(quality.findings.get(id)?.get(column)??[]).map(issue=>({
154
+ name:qualityEvidence(issue),detail:qualityRules[issue.rule][1],
155
+ actions:[{label:"Dismiss…",run:()=>openQualityDismissal(id,column,issue,marker)}]
156
+ })),
157
+ actions:[{label:"Show in quality panel",run:()=>openQuality(id,column)}]
158
+ });
159
+ }
160
+ function qualityCardTitle(card,id,column,text,hidden){
161
+ const title=document.createElement("h3");
162
+ const jump=document.createElement("button");
163
+ jump.type="button";
164
+ jump.className="quality-card-jump";
165
+ jump.textContent=text;
166
+ jump.setAttribute("aria-label",`Go to ${text}`);
167
+ title.append(jump);
168
+ card.append(title);
169
+ card.addEventListener("click",event=>{
170
+ const action=event.target.closest("button");
171
+ if(!action||action===jump)jumpToQualityCell(id,column,hidden);
172
+ });
173
+ }
174
+ function renderQualityPanel(){
175
+ if(qualityPanel.hidden)return;
176
+ const list=$("#quality-findings"),body=list.parentElement,scroll=body.scrollTop;
177
+ const displayed=new Set(grid.display.map(row=>row.id));
178
+ const columns=new Set(visibleColumns().map(column=>column.name));
179
+ let count=0;
180
+ const cards=[];
181
+ for(const [id,fields] of quality.findings){
182
+ for(const [column,issues] of fields){
183
+ const active=quality.activeCell?.id===id&&quality.activeCell.column===column;
184
+ const rowHidden=!displayed.has(id);
185
+ const hidden=rowHidden||!columns.has(column);
186
+ const card=document.createElement("article");
187
+ card.className="comment-card quality-card";
188
+ card.classList.toggle("quality-active",active);
189
+ const label=columnLabel(column);
190
+ qualityCardTitle(card,id,column,`${id} · ${label}`,hidden);
191
+ if(rowHidden){
192
+ const note=document.createElement("p");
193
+ note.className="meta";
194
+ note.textContent="This row is hidden. Revealing it clears the current row filters.";
195
+ card.append(note);
196
+ }
197
+ for(const issue of issues){
198
+ const {rule,phrase}=issue;
199
+ const section=document.createElement("div");
200
+ section.className="quality-issue";
201
+ const text=document.createElement("p");
202
+ const evidence=document.createElement("strong");
203
+ evidence.textContent=qualityEvidence(issue);
204
+ text.append(evidence,document.createElement("br"),qualityRules[rule][1]);
205
+ const actions=document.createElement("div");
206
+ actions.className="comment-actions";
207
+ const edit=document.createElement("button");
208
+ edit.type="button";
209
+ edit.textContent=hidden?"Reveal and edit":phrase?"Edit wording":"Edit field";
210
+ edit.setAttribute("aria-label",`${edit.textContent} for ${id}, ${label}${phrase?` · ${phrase}`:""}`);
211
+ edit.addEventListener("click",()=>jumpToQualityCell(id,column,hidden,issue));
212
+ const dismiss=document.createElement("button");
213
+ dismiss.type="button";
214
+ dismiss.textContent="Dismiss…";
215
+ dismiss.addEventListener("click",()=>openQualityDismissal(id,column,issue,dismiss));
216
+ actions.append(edit,dismiss);
217
+ section.append(text,actions);
218
+ card.append(section);
219
+ count++;
220
+ }
221
+ cards.push(card);
222
+ }
223
+ }
224
+ if($("#quality-show-dismissed").checked){
225
+ for(const record of quality.dismissed??[]){
226
+ const card=document.createElement("article");
227
+ card.className="comment-card quality-dismissed";
228
+ qualityCardTitle(card,record.id,record.column,`${record.id} · ${record.column} · ${qualityEvidence(record)} (dismissed)`,
229
+ !displayed.has(record.id)||!columns.has(record.column));
230
+ const reason=document.createElement("p");
231
+ reason.textContent=record.reason;
232
+ const restore=document.createElement("button");
233
+ restore.type="button";
234
+ restore.textContent="Restore finding";
235
+ restore.addEventListener("click",()=>{
236
+ if(!qualityCanChange())return;
237
+ state.qualityReview.dismissals=state.qualityReview.dismissals.filter(item=>item!==record);
238
+ updateDirty();
239
+ render();
240
+ $("#quality-show-dismissed").focus();
241
+ });
242
+ card.append(reason,restore);
243
+ cards.push(card);
244
+ }
245
+ }
246
+ list.replaceChildren(...cards);
247
+ $("#quality-count").textContent=qualityColumns.length
248
+ ?`${count} ${count===1?"finding":"findings"} across ${quality.findings.size} of ${data.options?.traceability?state.currentRows.filter(trace.isRequirement).length:state.currentRows.length} requirements · ${quality.dismissed?.length??0} dismissed`
249
+ :"Choose a requirement column or required fields in Quality settings.";
250
+ $("#quality-only").checked=quality.only;
251
+ body.scrollTop=scroll;
252
+ }
253
+ function closeQuality(){
254
+ if(qualityPanel.hidden)return;
255
+ qualityPanel.hidden=true;
256
+ renderLayout();
257
+ }
258
+ function openQuality(id,column){
259
+ if(!developMode())return;
260
+ if(!quality.checked){
261
+ quality.checked=true;
262
+ scanQuality();
263
+ paintQualityMarkers();
264
+ }
265
+ closeReview();
266
+ trace?.close();
267
+ quality.activeCell=id===undefined?null:{id,column};
268
+ qualityPanel.hidden=false;
269
+ renderLayout();
270
+ renderQualityPanel();
271
+ const active=qualityPanel.querySelector(".quality-active");
272
+ if(active){
273
+ active.scrollIntoView({block:"nearest"});
274
+ active.querySelector("button").focus({preventScroll:true});
275
+ }else $("#quality-title").focus({preventScroll:true});
276
+ }
277
+ function jumpToQualityCell(id,column,hidden,issue){
278
+ if(state.editingCell){
279
+ $("#quality-count").textContent="Apply or cancel the cell edit before jumping to a finding.";
280
+ return;
281
+ }
282
+ quality.activeCell={id,column};
283
+ if(hidden){
284
+ const rowVisible=displayIndex(id)>=0;
285
+ trace?.reveal(id,column);
286
+ state.hidden.delete(column);
287
+ if(!rowVisible){
288
+ state.filters.clear();
289
+ state.valueFilters.clear();
290
+ state.commentsOnly=false;
291
+ state.statuses=new Set(["added","removed","changed","unchanged"]);
292
+ quality.revealId=id;
293
+ }
294
+ render();
295
+ }else renderQualityPanel();
296
+ if(matchMedia("(max-width:900px)").matches)closeQuality();
297
+ const cell=focusRequirement(id,column);
298
+ if(issue&&cell&&startCellEdit(cell)){
299
+ const textarea=cell.querySelector("textarea");
300
+ if(issue.phrase)textarea.setSelectionRange(issue.start,issue.start+issue.phrase.length);
301
+ else textarea.select();
302
+ }
303
+ }
304
+ $("#check-quality").addEventListener("click",()=>openQuality());
305
+ $("#close-quality").addEventListener("click",()=>{
306
+ closeQuality();
307
+ if(!state.editingCell)restoreSelectedCell();
308
+ else tableBody.querySelector("[data-cell-editor] textarea")?.focus();
309
+ });
310
+ $("#quality-only").addEventListener("change",event=>{
311
+ if(state.editingCell){
312
+ event.target.checked=quality.only;
313
+ $("#quality-count").textContent="Apply or cancel the cell edit before filtering findings.";
314
+ return;
315
+ }
316
+ quality.only=event.target.checked;
317
+ renderBodyOnly();
318
+ });
319
+ function qualityCanChange(){
320
+ if(!state.editingCell)return true;
321
+ $("#quality-count").textContent="Apply or cancel the cell edit before changing quality settings or dismissals.";
322
+ return false;
323
+ }
324
+ const qualitySettings=$("#quality-settings-dialog");
325
+ function openQualitySettings(){
326
+ if(!qualityCanChange())return;
327
+ configureQuality();
328
+ const select=$("#quality-column");
329
+ select.replaceChildren();
330
+ for(const name of ["",...qualityHeaders]){
331
+ const option=document.createElement("option");
332
+ option.value=name;
333
+ option.textContent=name||"No statement column";
334
+ option.selected=name===(requirementColumn??"");
335
+ select.append(option);
336
+ }
337
+ $("#quality-obligation").value=obligation??"";
338
+ const fillCheckboxes=(container,entries,checked)=>{
339
+ container.replaceChildren(...entries.map(([value,text])=>{
340
+ const label=document.createElement("label"),input=document.createElement("input");
341
+ input.type="checkbox";
342
+ input.value=value;
343
+ input.checked=checked(value);
344
+ label.append(input," "+text);
345
+ return label;
346
+ }));
347
+ };
348
+ const required=new Set(state.qualityReview.settings.required_columns??[]);
349
+ fillCheckboxes($("#quality-required-columns"),qualityHeaders.map(name=>[name,name]),name=>required.has(name));
350
+ fillCheckboxes($("#quality-enabled-rules"),Object.entries(qualityRules).map(([rule,[name]])=>[rule,name]),
351
+ rule=>!disabledQualityRules.has(rule));
352
+ qualitySettings.showModal();
353
+ }
354
+ $("#quality-settings").addEventListener("click",openQualitySettings);
355
+ $("#quality-settings-cancel").addEventListener("click",()=>qualitySettings.close());
356
+ qualitySettings.addEventListener("close",()=>$("#quality-settings").focus());
357
+ $("#quality-settings-form").addEventListener("submit",event=>{
358
+ event.preventDefault();
359
+ const checkedValues=selector=>[...document.querySelectorAll(selector)].map(input=>input.value);
360
+ const previous=state.qualityReview.settings;
361
+ const column=$("#quality-column").value;
362
+ const disabled=checkedValues("#quality-enabled-rules input:not(:checked)");
363
+ state.qualityReview.settings={
364
+ ...previous,
365
+ requirement_column:column===(requirementColumn??"")?previous.requirement_column:column,
366
+ obligation:$("#quality-obligation").value.trim()||null,
367
+ required_columns:checkedValues("#quality-required-columns input:checked"),
368
+ ...(disabled.length||previous.disabled_rules?{disabled_rules:disabled}:{})
369
+ };
370
+ quality.checked=true;
371
+ updateDirty();
372
+ render();
373
+ qualitySettings.close();
374
+ });
375
+ const qualityDismissDialog=$("#quality-dismiss-dialog");
376
+ for(const dialog of [qualitySettings,qualityDismissDialog]){
377
+ dialog.addEventListener("keydown",event=>{
378
+ if(event.key==="Escape")event.stopPropagation();
379
+ });
380
+ }
381
+ let pendingQualityDismissal=null,dismissalOpener=null;
382
+ function openQualityDismissal(id,column,issue,opener){
383
+ if(!qualityCanChange())return;
384
+ const row=findCurrentRow(id);
385
+ if(!row)return;
386
+ const keyword=issue.rule.endsWith("-obligation")||issue.rule==="multiple-obligations"?obligation:null;
387
+ pendingQualityDismissal={id,column,value:String(row[column]??""),rule:issue.rule,
388
+ phrase:issue.phrase,start:issue.start,obligation:keyword};
389
+ dismissalOpener=opener;
390
+ $("#quality-dismiss-description").textContent=
391
+ `${id} · ${column} · ${qualityRules[issue.rule][0]}${issue.phrase?` · “${issue.phrase}”`:""}`;
392
+ const reason=$("#quality-dismiss-reason");
393
+ reason.value="";
394
+ reason.setCustomValidity("");
395
+ qualityDismissDialog.showModal();
396
+ reason.focus();
397
+ }
398
+ $("#quality-dismiss-cancel").addEventListener("click",()=>qualityDismissDialog.close());
399
+ qualityDismissDialog.addEventListener("close",()=>{
400
+ pendingQualityDismissal=null;
401
+ if(dismissalOpener?.isConnected)dismissalOpener.focus();
402
+ else if(qualityPanel.hidden)restoreSelectedCell();
403
+ else $("#quality-show-dismissed").focus();
404
+ });
405
+ $("#quality-dismiss-reason").addEventListener("input",event=>event.target.setCustomValidity(""));
406
+ $("#quality-dismiss-form").addEventListener("submit",event=>{
407
+ event.preventDefault();
408
+ const input=$("#quality-dismiss-reason"),reason=input.value.trim();
409
+ if(!reason){
410
+ input.setCustomValidity("Enter a reason for dismissing this finding.");
411
+ input.reportValidity();
412
+ return;
413
+ }
414
+ if(!pendingQualityDismissal)return;
415
+ state.qualityReview.dismissals.push({...pendingQualityDismissal,reason});
416
+ updateDirty();
417
+ render();
418
+ qualityDismissDialog.close();
419
+ });
420
+ $("#quality-show-dismissed").addEventListener("change",renderQualityPanel);
421
+
422
+ """