tracker

6.9 KB

1. #!/usr/bin/env node
2. // theme/check-theme.mjs — THE THEME GATE HELPER an app runs: it flags what bypasses the WorldAPI theme in the app's own code.
3. // node theme/check-theme.mjs [appDir] [--ignore <path prefix>]…
4. // 1. HARD-CODED COLOURS: #hex, rgb()/rgba(), hsl()/hsla(), oklch(), and named colours (white, black, red …) in .hl and .css
5. // files. Colours come from the theme's named tokens (shared/tokens.hl, `colorText`, 'var(--color-text)'). A fallback inside
6. // `var(--token, …)` is allowed (the components of components.hybriel carry those so a copy works without the theme).
7. // 2. DECORATIVE BORDERS: any border / borderTop … / borderColor that is not 0 / none. Allowed only where a border MEANS
8. // something (docs/design-rules.md): on a line about details/summary (foldables), drop zones, focus or an invalid field,
9. // or on a line that says so with the comment `// functional: <why>`.
10. // 3. CORNER RADII: every borderRadius / borderTopLeftRadius … (css: border-radius, border-top-left-radius …) is one of the two
11. // theme radii — radiusSmall (5px: buttons, pills, fields, tags, menu items, chips) or radiusLarge (10px: panels, modals,
12. // popovers, dropdowns, tiles/posters), in css 'var(--radius-small)' / 'var(--radius-large)' — or 0, or '50%' for round
13. // things (avatars, check circles). Each corner of a list counts ('radiusLarge + ' ' + radiusLarge + ' 0 0'' is fine).
14. // Never scanned: plugins/ bin/ node_modules/ storage/ .scratch/ .git/ .sessions/ and shared/tokens.hl (the one place for raw
15. // values). More paths to skip (e.g. a vendored component folder whose frames the theme removes): --ignore, or one prefix per
16. // line in `.check-theme-ignore` in the app folder.
17. // Output: one `file:line: problem — text` per finding, then `check-theme: N files, M problems`; exit 1 when M > 0.
18. import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
19. import { join, relative, resolve } from 'node:path';
21. const args = process.argv.slice(2);
22. let dir = '.';
23. const ignore = ['plugins/', 'bin/', 'node_modules/', 'storage/', '.scratch/', '.git/', '.sessions/', 'shared/tokens.hl'];
24. for (let i = 0; i < args.length; i++) {
25. if (args[i] === '--ignore') ignore.push(args[++i]);
26. else dir = args[i];
27. }
28. const APP = resolve(dir);
29. const ignoreFile = join(APP, '.check-theme-ignore');
30. if (existsSync(ignoreFile)) {
31. for (const line of readFileSync(ignoreFile, 'utf8').split('\n')) {
32. const p = line.replace(/#.*/, '').trim();
33. if (p) ignore.push(p);
34. }
35. }
37. function files(d) {
38. const out = [];
39. for (const name of readdirSync(d)) {
40. const full = join(d, name);
41. const rel = relative(APP, full);
42. const st = statSync(full);
43. if (ignore.some(p => rel === p.replace(/\/$/, '') || rel.startsWith(p.endsWith('/') ? p : p + '/') || rel === p)) continue;
44. if (st.isDirectory()) out.push(...files(full));
45. else if (/\.(hl|css)$/.test(name)) out.push(full);
46. }
47. return out;
48. }
50. const NAMED = 'white|black|red|green|blue|gray|grey|yellow|orange|purple|pink|brown|silver|navy|teal|maroon|olive|lime|aqua|fuchsia|cyan|magenta|gold|indigo|violet';
51. const COLOUR = new RegExp(`(#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3}(?:[0-9a-fA-F]{2})?)?|#[0-9a-fA-F]{4})(?![0-9a-zA-Z_-])|\\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\\(`);
52. const NAMED_RE = new RegExp(`[=:]\\s*['"]?[^'";]*\\b(${NAMED})\\b`, 'i');
53. // a css declaration that sets a colour: hl (`color = '…'`, `background = …`) or css (`color: …`)
54. const COLOUR_PROP = /\b(color|background(?:Color|-color)?|fill|stroke|borderColor|border-color|outlineColor|outline-color|boxShadow|box-shadow|accentColor|accent-color|caretColor|caret-color|textDecorationColor)\s*[=:]/i;
55. const BORDER = /\b(border(?:Top|Right|Bottom|Left|Block|Inline)?(?:Start|End)?(?:Color|Width|Style)?|border(?:-(?:top|right|bottom|left|block|inline))?(?:-(?:start|end))?(?:-(?:color|width|style))?)\s*([=:])\s*(?:'([^']*)'|"([^"]*)"|([^;}\s]+))/g;
56. const FUNCTIONAL = /details|summary|drop-zone|dropZone|\.drop|:focus|focus-visible|aria-invalid|\/\/\s*functional/i;
57. const NO_BORDER = /^\s*(0|0px|none|0 none|transparent|inherit|initial|unset)\s*$/i;
58. // a radius: hl `borderRadius = <quoted strings / names joined by +>`, css `border-radius: <value>`
59. const RADIUS_NAME = 'border(?:Top|Bottom|Start|End)?(?:Left|Right|Start|End)?Radius|border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius';
60. const RADIUS_HL = new RegExp(`\\b(${RADIUS_NAME})'?\\s*=\\s*((?:'[^']*'|"[^"]*"|[\\w.$-]+)(?:\\s*\\+\\s*(?:'[^']*'|"[^"]*"|[\\w.$-]+))*)`, 'g');
61. const RADIUS_CSS = new RegExp(`\\b(${RADIUS_NAME})\\s*:\\s*([^;}'"]+)`, 'g');
62. const RADIUS_OK = /^(0|0px|50%|radiusSmall|radiusLarge|var\(--radius-(?:small|large)\)|inherit|initial|unset)$/;
63. // the corner values of one radius that are not the theme's two (a token's fallback `var(--radius-small, 5px)` is fine)
64. function badRadii(value) {
65. const words = value.replace(/var\(\s*--radius-(small|large)\s*(?:,(?:[^()]|\([^()]*\))*)?\)/g, 'var(--radius-$1)').replace(/['"+]/g, ' ').split(/[\s/]+/);
66. return words.filter(w => w && !RADIUS_OK.test(w));
67. }
69. // strip comments (whole-line `//`, trailing ` // …`, /* … */ on one line)
70. function uncomment(line) {
71. const s = line.replace(/\/\*.*?\*\//g, '');
72. if (/^\s*\/\//.test(s)) return '';
73. return s.replace(/\s\/\/\s.*$/, '');
74. }
75. // … and the allowed var(--x, fallback) fallbacks
76. function code(line) {
77. return uncomment(line).replace(/var\(\s*--[\w-]+\s*,\s*(?:[^()]|\([^()]*\))*\)/g, 'var()');
78. }
80. let problems = 0;
81. const list = files(APP);
82. for (const f of list) {
83. const lines = readFileSync(f, 'utf8').split('\n');
84. lines.forEach((raw, i) => {
85. const s = code(raw);
86. if (!s.trim()) return;
87. const where = `${relative(APP, f)}:${i + 1}`;
88. const m = s.match(COLOUR);
89. if (m && !/^\s*import\b/.test(s)) { problems++; console.log(`${where}: hard-coded colour '${m[0]}' — use a theme token — ${raw.trim().slice(0, 140)}`); }
90. else if (COLOUR_PROP.test(s)) {
91. const n = s.match(NAMED_RE);
92. if (n && !/currentColor|transparent/i.test(n[0].slice(-12))) { problems++; console.log(`${where}: named colour '${n[1]}' — use a theme token — ${raw.trim().slice(0, 140)}`); }
93. }
94. for (const b of s.matchAll(BORDER)) {
95. const value = (b[3] ?? b[4] ?? b[5] ?? '').trim();
96. if (b[1].toLowerCase().includes('radius')) continue;
97. if (NO_BORDER.test(value)) continue;
98. if (FUNCTIONAL.test(raw)) continue;
99. problems++;
100. console.log(`${where}: decorative border '${b[1]} ${b[2]} ${value || '…'}' — borderless unless it means something (docs/design-rules.md), else mark it '// functional: why' — ${raw.trim().slice(0, 140)}`);
101. }
102. const plain = uncomment(raw);
103. for (const r of [...plain.matchAll(RADIUS_HL), ...plain.matchAll(RADIUS_CSS)]) {
104. const bad = badRadii(r[2]);
105. if (!bad.length) continue;
106. problems++;
107. console.log(`${where}: corner radius '${r[1]} ${r[2].trim()}' — only radiusSmall (5px, small items), radiusLarge (10px, panels, popups, tiles), '50%' for round things — ${raw.trim().slice(0, 140)}`);
108. }
109. });
110. }
111. console.log(`check-theme: ${list.length} files, ${problems} problems`);
112. process.exit(problems ? 1 : 0);