1#!/usr/bin/env node
2/**
3 * Validate token usage in codebase
4 * Finds hardcoded values that should use design tokens
5 *
6 * Usage:
7 *   node validate-tokens.cjs --dir src/
8 *   node validate-tokens.cjs --dir src/ --fix
9 */
10 
11const fs = require('fs');
12const path = require('path');
13 
14/**
15 * Parse command line arguments
16 */
17function parseArgs() {
18  const args = process.argv.slice(2);
19  const options = {
20    dir: null,
21    fix: false,
22    ignore: ['node_modules', '.git', 'dist', 'build', '.next']
23  };
24 
25  for (let i = 0; i < args.length; i++) {
26    if (args[i] === '--dir' || args[i] === '-d') {
27      options.dir = args[++i];
28    } else if (args[i] === '--fix') {
29      options.fix = true;
30    } else if (args[i] === '--ignore' || args[i] === '-i') {
31      options.ignore.push(args[++i]);
32    } else if (args[i] === '--help' || args[i] === '-h') {
33      console.log(`
34Usage: node validate-tokens.cjs [options]
35 
36Options:
37  -d, --dir <path>      Directory to scan (required)
38  --fix                 Show suggested fixes (no auto-fix)
39  -i, --ignore <dir>    Additional directories to ignore
40  -h, --help            Show this help
41 
42Checks for:
43  - Hardcoded hex colors (#RGB, #RRGGBB)
44  - Hardcoded pixel values (except 0, 1px)
45  - Hardcoded rem values in CSS
46      `);
47      process.exit(0);
48    }
49  }
50 
51  return options;
52}
53 
54/**
55 * Patterns to detect hardcoded values
56 */
57const patterns = {
58  hexColor: {
59    regex: /#([0-9A-Fa-f]{3}){1,2}\b/g,
60    message: 'Hardcoded hex color',
61    suggestion: 'Use var(--color-*) token'
62  },
63  rgbColor: {
64    regex: /rgb\s*\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)/gi,
65    message: 'Hardcoded RGB color',
66    suggestion: 'Use var(--color-*) token'
67  },
68  pixelValue: {
69    regex: /:\s*(\d{2,})px/g, // 2+ digit px values
70    message: 'Hardcoded pixel value',
71    suggestion: 'Use var(--space-*) or var(--radius-*) token'
72  },
73  remValue: {
74    regex: /:\s*\d+\.?\d*rem(?![^{]*\$value)/g, // rem not in token definition
75    message: 'Hardcoded rem value',
76    suggestion: 'Use var(--space-*) or var(--font-size-*) token'
77  }
78};
79 
80/**
81 * File extensions to scan
82 */
83const extensions = ['.css', '.scss', '.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte'];
84 
85/**
86 * Files/patterns to skip
87 */
88const skipPatterns = [
89  /\.min\.(css|js)$/,
90  /tailwind\.config/,
91  /globals\.css/, // Token definitions
92  /tokens\.(css|json)/
93];
94 
95/**
96 * Get all files recursively
97 */
98function getFiles(dir, ignore, files = []) {
99  const entries = fs.readdirSync(dir, { withFileTypes: true });
100 
101  for (const entry of entries) {
102    const fullPath = path.join(dir, entry.name);
103 
104    if (entry.isDirectory()) {
105      if (!ignore.includes(entry.name)) {
106        getFiles(fullPath, ignore, files);
107      }
108    } else if (entry.isFile()) {
109      const ext = path.extname(entry.name);
110      if (extensions.includes(ext)) {
111        files.push(fullPath);
112      }
113    }
114  }
115 
116  return files;
117}
118 
119/**
120 * Check if file should be skipped
121 */
122function shouldSkip(filePath) {
123  return skipPatterns.some(pattern => pattern.test(filePath));
124}
125 
126/**
127 * Scan file for violations
128 */
129function scanFile(filePath) {
130  const content = fs.readFileSync(filePath, 'utf-8');
131  const lines = content.split('\n');
132  const violations = [];
133 
134  lines.forEach((line, index) => {
135    // Skip comments
136    if (line.trim().startsWith('//') || line.trim().startsWith('/*')) {
137      return;
138    }
139 
140    // Skip lines that already use CSS variables
141    if (line.includes('var(--')) {
142      return;
143    }
144 
145    for (const [name, pattern] of Object.entries(patterns)) {
146      const matches = line.match(pattern.regex);
147      if (matches) {
148        matches.forEach(match => {
149          // Skip common exceptions
150          if (name === 'hexColor' && ['#000', '#fff', '#FFF', '#000000', '#FFFFFF'].includes(match.toUpperCase())) {
151            return; // Skip black/white, often intentional
152          }
153 
154          violations.push({
155            file: filePath,
156            line: index + 1,
157            column: line.indexOf(match) + 1,
158            value: match,
159            type: name,
160            message: pattern.message,
161            suggestion: pattern.suggestion,
162            context: line.trim().substring(0, 80)
163          });
164        });
165      }
166    }
167  });
168 
169  return violations;
170}
171 
172/**
173 * Format violation report
174 */
175function formatReport(violations) {
176  if (violations.length === 0) {
177    return '✅ No token violations found';
178  }
179 
180  let report = `⚠️  Found ${violations.length} potential token violations:\n\n`;
181 
182  // Group by file
183  const byFile = {};
184  violations.forEach(v => {
185    if (!byFile[v.file]) byFile[v.file] = [];
186    byFile[v.file].push(v);
187  });
188 
189  for (const [file, fileViolations] of Object.entries(byFile)) {
190    report += `📁 ${file}\n`;
191    fileViolations.forEach(v => {
192      report += `   Line ${v.line}: ${v.message}\n`;
193      report += `   Found: ${v.value}\n`;
194      report += `   Suggestion: ${v.suggestion}\n`;
195      report += `   Context: ${v.context}\n\n`;
196    });
197  }
198 
199  // Summary
200  const byType = {};
201  violations.forEach(v => {
202    byType[v.type] = (byType[v.type] || 0) + 1;
203  });
204 
205  report += `\n📊 Summary:\n`;
206  for (const [type, count] of Object.entries(byType)) {
207    report += `   ${patterns[type].message}: ${count}\n`;
208  }
209 
210  return report;
211}
212 
213/**
214 * Main
215 */
216function main() {
217  const options = parseArgs();
218 
219  if (!options.dir) {
220    console.error('Error: --dir is required');
221    process.exit(1);
222  }
223 
224  const dirPath = path.resolve(process.cwd(), options.dir);
225 
226  if (!fs.existsSync(dirPath)) {
227    console.error(`Error: Directory not found: ${dirPath}`);
228    process.exit(1);
229  }
230 
231  console.log(`Scanning ${dirPath} for token violations...\n`);
232 
233  const files = getFiles(dirPath, options.ignore);
234  const allViolations = [];
235 
236  for (const file of files) {
237    if (shouldSkip(file)) continue;
238 
239    const violations = scanFile(file);
240    allViolations.push(...violations);
241  }
242 
243  console.log(formatReport(allViolations));
244 
245  // Exit with error code if violations found
246  if (allViolations.length > 0) {
247    process.exit(1);
248  }
249}
250 
251main();
252