tracker

5.0 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. // Never scanned: plugins/ bin/ node_modules/ storage/ .scratch/ .git/ .sessions/ and shared/tokens.hl (the one place for raw
11. // values). More paths to skip (e.g. a vendored component folder whose frames the theme removes): --ignore, or one prefix per
12. // line in `.check-theme-ignore` in the app folder.
13. // Output: one `file:line: problem — text` per finding, then `check-theme: N files, M problems`; exit 1 when M > 0.
14. import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
15. import { join, relative, resolve } from 'node:path';
17. const args = process.argv.slice(2);
18. let dir = '.';
19. const ignore = ['plugins/', 'bin/', 'node_modules/', 'storage/', '.scratch/', '.git/', '.sessions/', 'shared/tokens.hl'];
20. for (let i = 0; i < args.length; i++) {
21. if (args[i] === '--ignore') ignore.push(args[++i]);
22. else dir = args[i];
23. }
24. const APP = resolve(dir);
25. const ignoreFile = join(APP, '.check-theme-ignore');
26. if (existsSync(ignoreFile)) {
27. for (const line of readFileSync(ignoreFile, 'utf8').split('\n')) {
28. const p = line.replace(/#.*/, '').trim();
29. if (p) ignore.push(p);
30. }
31. }
33. function files(d) {
34. const out = [];
35. for (const name of readdirSync(d)) {
36. const full = join(d, name);
37. const rel = relative(APP, full);
38. const st = statSync(full);
39. if (ignore.some(p => rel === p.replace(/\/$/, '') || rel.startsWith(p.endsWith('/') ? p : p + '/') || rel === p)) continue;
40. if (st.isDirectory()) out.push(...files(full));
41. else if (/\.(hl|css)$/.test(name)) out.push(full);
42. }
43. return out;
44. }
46. 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';
47. 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)\\(`);
48. const NAMED_RE = new RegExp(`[=:]\\s*['"]?[^'";]*\\b(${NAMED})\\b`, 'i');
49. // a css declaration that sets a colour: hl (`color = '…'`, `background = …`) or css (`color: …`)
50. 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;
51. 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;
52. const FUNCTIONAL = /details|summary|drop-zone|dropZone|\.drop|:focus|focus-visible|aria-invalid|\/\/\s*functional/i;
53. const NO_BORDER = /^\s*(0|0px|none|0 none|transparent|inherit|initial|unset)\s*$/i;
55. // strip comments (whole-line `//`, trailing ` // …`, /* … */ on one line) and allowed var(--x, fallback) fallbacks
56. function code(line) {
57. let s = line.replace(/\/\*.*?\*\//g, '');
58. if (/^\s*\/\//.test(s)) return '';
59. s = s.replace(/\s\/\/\s.*$/, '');
60. s = s.replace(/var\(\s*--[\w-]+\s*,\s*(?:[^()]|\([^()]*\))*\)/g, 'var()');
61. return s;
62. }
64. let problems = 0;
65. const list = files(APP);
66. for (const f of list) {
67. const lines = readFileSync(f, 'utf8').split('\n');
68. lines.forEach((raw, i) => {
69. const s = code(raw);
70. if (!s.trim()) return;
71. const where = `${relative(APP, f)}:${i + 1}`;
72. const m = s.match(COLOUR);
73. 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)}`); }
74. else if (COLOUR_PROP.test(s)) {
75. const n = s.match(NAMED_RE);
76. 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)}`); }
77. }
78. for (const b of s.matchAll(BORDER)) {
79. const value = (b[3] ?? b[4] ?? b[5] ?? '').trim();
80. if (b[1].toLowerCase().includes('radius')) continue;
81. if (NO_BORDER.test(value)) continue;
82. if (FUNCTIONAL.test(raw)) continue;
83. problems++;
84. 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)}`);
85. }
86. });
87. }
88. console.log(`check-theme: ${list.length} files, ${problems} problems`);
89. process.exit(problems ? 1 : 0);