dotfiles bugabingas dorkfiles
owned by bugabinga
README Source History Refs Compare Notes Search test(quickshell): require decision comments
145a888d66165df527d703f947eb2e9c4f8df1ca
Oliver Jan Krylow <oliver@bugabinga.net > · 17 Jun 2026
unsigned
Browse files Compare 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
56 56 documented_components=29
59 60 documented_external_commands=25
71 72 PASS nugu quickshell audit
73 74 documented_components=29
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 20 20 qml_files = sorted(config_dir.glob(
"*.qml" ))
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" )
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)}" )