repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

test(quickshell): require decision comments

145a888d66165df527d703f947eb2e9c4f8df1ca

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

docs/super/inventory/2026-06-17-quickshell-self-contained-audit.md

Modified
20 20 - future service rollout is documented in `SERVICE.md`; `hypr/systemd/quickshell.service` must start `qs -c nugu`, and `x230.symlinks` must link both config and service.
21 21 - replacement scope is documented in `PARITY.md`, including old companion retirement targets and human approval.
22 22 - QML imports are limited to Qt, Quickshell, and local `import "."`.
23 -- every QML component has an early decision comment.
23 +- every QML component has an early decision/why comment, not just a generic file description.
24 24 - QML comments do not contain unresolved TODO/stub/placeholder markers; rollout status belongs in inventories.
25 25 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
26 26 - live/repo path markers such as `../`, `~/.config`, and `~/.local` fail the audit.
54 54 PASS nugu quickshell audit
55 55 qml_files=29
56 56 documented_components=29
57 +decision_comments=29
57 58 ipc_methods=58
58 59 documented_ipc=58
59 60 documented_external_commands=25
71 72 PASS nugu quickshell audit
72 73 qml_files=29
73 74 documented_components=29
75 +decision_comments=29
74 76 ipc_methods=58
75 77 documented_ipc=58
76 78 documented_external_commands=25

quickshell/nugu/README.md

Modified
33 33 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
34 34 and retirement gates. The audit checks that required named-config files are present, every QML component and IPC method
35 35 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
36 -early decision comment, QML has no unresolved TODO/stub comments, local resources
36 +early decision/why comment, QML has no unresolved TODO/stub comments, local resources
37 37 are audited, the bundled palette matches
38 38 `hypr/generated/nugu.json`, critical Nugu foreground/background pairs keep at
39 39 least 4.5 contrast, external commands are documented without stale rows, the

quickshell/nugu/audit.sh

Modified
19 19 warnings = []
20 20 qml_files = sorted(config_dir.glob("*.qml"))
21 21 code_by_file = {}
22 +decision_comment_files = set()
22 23 required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh")
24 25 for name in required_files:
104 105 errors.append(f"{rel}:{number}: non-self-contained import {target}")
106 107 early = lines[:40]
107 - if not any(line.strip().startswith("//") for line in early):
108 + early_comments = [line.strip()[2:].strip() for line in early if line.strip().startswith("//")]
109 + early_comment_text = " ".join(early_comments)
110 + if not early_comments:
108 111 errors.append(f"{rel}: missing early decision comment")
112 + elif not re.search(r"\b(because|so|until|instead|avoid|avoids|deliberately|intentionally|replace|replaces|preserve|preserves|keep|keeps|match|matches|current|future|parity|retire|authoritative|hidden|phase|fight|controlled)\b", early_comment_text, re.I):
113 + errors.append(f"{rel}: early comment must explain a decision/why, not just describe the file")
114 + else:
115 + decision_comment_files.add(rel.name)
110 117 for number, line in enumerate(lines, 1):
111 118 comment = line.split("//", 1)[1] if "//" in line else ""
298 305 print("PASS nugu quickshell audit")
299 306 print(f"qml_files={len(qml_files)}")
300 307 print(f"documented_components={len(documented)}")
308 +print(f"decision_comments={len(decision_comment_files)}")
301 309 print(f"ipc_methods={len(ipc_methods)}")
302 310 print(f"documented_ipc={len(documented_ipc)}")
303 311 print(f"documented_external_commands={len(external_commands)}")