impeccable 3.0.1 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1224,6 +1224,7 @@ if (IS_BROWSER) {
1224
1224
  category: ap ? ap.category : 'quality',
1225
1225
  severity: ap?.severity || 'warning',
1226
1226
  detail: f.detail || f.snippet,
1227
+ ignoreValue: f.ignoreValue || f.value || '',
1227
1228
  name: ap ? ap.name : (f.type || f.id),
1228
1229
  description: ap ? ap.description : '',
1229
1230
  };
@@ -1260,10 +1261,203 @@ if (IS_BROWSER) {
1260
1261
  return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
1261
1262
  }
1262
1263
 
1264
+ const DESIGN_COLOR_TOLERANCE = 6;
1265
+ const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
1266
+ const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
1267
+
1268
+ function normalizeBrowserFontName(value) {
1269
+ return String(value || '')
1270
+ .trim()
1271
+ .replace(/^["']|["']$/g, '')
1272
+ .replace(/\+/g, ' ')
1273
+ .replace(/\s+/g, ' ')
1274
+ .toLowerCase();
1275
+ }
1276
+
1277
+ function browserPrimaryFont(stack) {
1278
+ if (!stack || /var\(/i.test(stack)) return '';
1279
+ return String(stack || '')
1280
+ .split(',')
1281
+ .map(normalizeBrowserFontName)
1282
+ .find(font => font && !GENERIC_FONTS.has(font)) || '';
1283
+ }
1284
+
1285
+ function browserDesignSystemConfig() {
1286
+ const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
1287
+ if (!raw?.present) return null;
1288
+ const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
1289
+ const allowedColors = (raw.allowedColors || [])
1290
+ .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
1291
+ .map(color => ({ r: color.r, g: color.g, b: color.b }));
1292
+ const allowedRadii = (raw.allowedRadii || [])
1293
+ .map(Number)
1294
+ .filter(px => Number.isFinite(px));
1295
+ return {
1296
+ present: true,
1297
+ hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
1298
+ allowedFonts,
1299
+ hasColors: raw.hasColors === true && allowedColors.length > 0,
1300
+ allowedColors,
1301
+ hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
1302
+ allowedRadii,
1303
+ hasPillRadius: raw.hasPillRadius === true,
1304
+ };
1305
+ }
1306
+
1307
+ function browserColorsClose(a, b) {
1308
+ if (!a || !b) return false;
1309
+ return Math.max(
1310
+ Math.abs(a.r - b.r),
1311
+ Math.abs(a.g - b.g),
1312
+ Math.abs(a.b - b.b),
1313
+ ) <= DESIGN_COLOR_TOLERANCE;
1314
+ }
1315
+
1316
+ function isBrowserDesignColorAllowed(raw, designSystem) {
1317
+ if (!designSystem?.hasColors) return true;
1318
+ const text = String(raw || '').trim().toLowerCase();
1319
+ if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
1320
+ if (text.includes('var(')) return true;
1321
+ const parsed = parseAnyColor(text);
1322
+ if (!parsed) return true;
1323
+ if ((parsed.a ?? 1) <= 0.05) return true;
1324
+ return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
1325
+ }
1326
+
1327
+ function isBrowserTransparentCss(value) {
1328
+ const text = String(value || '').trim().toLowerCase();
1329
+ if (!text || text === 'transparent') return true;
1330
+ const parsed = parseAnyColor(text);
1331
+ return parsed ? (parsed.a ?? 1) <= 0.05 : false;
1332
+ }
1333
+
1334
+ function isBrowserDesignRadiusAllowed(raw, designSystem) {
1335
+ if (!designSystem?.hasRadii) return true;
1336
+ const text = String(raw || '').trim().toLowerCase();
1337
+ if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
1338
+ if (text.includes('var(') || text.includes('%')) return true;
1339
+ const px = resolveLengthPx(text, 16);
1340
+ if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
1341
+ if (designSystem.hasPillRadius && px >= 99) return true;
1342
+ return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
1343
+ }
1344
+
1345
+ function browserRadiusTokens(value) {
1346
+ return String(value || '')
1347
+ .replace(/\s*\/\s*/g, ' ')
1348
+ .split(/\s+/)
1349
+ .map(token => token.trim())
1350
+ .filter(Boolean);
1351
+ }
1352
+
1353
+ function browserHasDirectText(el) {
1354
+ return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
1355
+ }
1356
+
1357
+ function browserSampleText(el) {
1358
+ const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
1359
+ return text ? ` "${text.slice(0, 40)}"` : '';
1360
+ }
1361
+
1362
+ function shouldSkipDesignElement(el) {
1363
+ const tag = el.tagName?.toLowerCase?.() || '';
1364
+ return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
1365
+ }
1366
+
1367
+ function checkElementDesignSystemDOM(el, designSystem, seen) {
1368
+ if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
1369
+ const findings = [];
1370
+ const tag = el.tagName?.toLowerCase?.() || 'unknown';
1371
+ const style = getComputedStyle(el);
1372
+
1373
+ if (designSystem.hasFonts && browserHasDirectText(el)) {
1374
+ const font = browserPrimaryFont(style.fontFamily || '');
1375
+ if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
1376
+ seen.fonts.add(font);
1377
+ findings.push({
1378
+ type: 'design-system-font',
1379
+ detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
1380
+ ignoreValue: font,
1381
+ });
1382
+ }
1383
+ }
1384
+
1385
+ if (designSystem.hasColors) {
1386
+ const colorChecks = [];
1387
+ if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
1388
+ if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
1389
+ for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
1390
+ if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
1391
+ colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
1392
+ }
1393
+ }
1394
+ if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
1395
+
1396
+ for (const [kind, raw] of colorChecks) {
1397
+ const label = String(raw || '').trim().replace(/\s+/g, ' ');
1398
+ if (isBrowserDesignColorAllowed(label, designSystem)) continue;
1399
+ const key = `${kind}:${label}`;
1400
+ if (seen.colors.has(key)) continue;
1401
+ seen.colors.add(key);
1402
+ findings.push({
1403
+ type: 'design-system-color',
1404
+ detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
1405
+ ignoreValue: label,
1406
+ });
1407
+ }
1408
+ }
1409
+
1410
+ if (designSystem.hasRadii) {
1411
+ for (const token of browserRadiusTokens(style.borderRadius || '')) {
1412
+ if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
1413
+ if (seen.radii.has(token)) continue;
1414
+ seen.radii.add(token);
1415
+ findings.push({
1416
+ type: 'design-system-radius',
1417
+ detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
1418
+ ignoreValue: token,
1419
+ });
1420
+ }
1421
+ }
1422
+
1423
+ return findings;
1424
+ }
1425
+
1426
+ function decodeBrowserGoogleFamily(value) {
1427
+ const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
1428
+ try {
1429
+ return decodeURIComponent(family);
1430
+ } catch {
1431
+ return family;
1432
+ }
1433
+ }
1434
+
1435
+ function checkBrowserDesignSystemSources(designSystem, seen) {
1436
+ if (!designSystem?.hasFonts) return [];
1437
+ const findings = [];
1438
+ for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
1439
+ const href = link.getAttribute('href') || '';
1440
+ for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
1441
+ const display = decodeBrowserGoogleFamily(match[1]);
1442
+ const font = normalizeBrowserFontName(display);
1443
+ if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
1444
+ seen.fonts.add(font);
1445
+ findings.push({
1446
+ type: 'design-system-font',
1447
+ detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
1448
+ ignoreValue: display,
1449
+ });
1450
+ }
1451
+ }
1452
+ return findings;
1453
+ }
1454
+
1263
1455
  function collectBrowserFindings() {
1264
1456
  const groupMap = new Map();
1265
1457
  const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
1266
1458
  const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
1459
+ const designSystem = browserDesignSystemConfig();
1460
+ const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
1267
1461
  // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
1268
1462
  // real browser env (detector page, live overlay, extension) running every
1269
1463
  // check is free, so we always surface them; the gating is purely a CLI
@@ -1294,6 +1488,7 @@ if (IS_BROWSER) {
1294
1488
  ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1295
1489
  ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1296
1490
  ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1491
+ ...checkElementDesignSystemDOM(el, designSystem, designSeen),
1297
1492
  ].filter(f => _ruleOk(f.type));
1298
1493
 
1299
1494
  addBrowserFindings(groupMap, el, findings);
@@ -1310,6 +1505,13 @@ if (IS_BROWSER) {
1310
1505
 
1311
1506
  const pageLevelFindings = [];
1312
1507
 
1508
+ const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
1509
+ .filter(f => _ruleOk(f.type));
1510
+ if (designSourceFindings.length > 0) {
1511
+ pageLevelFindings.push(...designSourceFindings);
1512
+ addBrowserFindings(groupMap, document.body, designSourceFindings);
1513
+ }
1514
+
1313
1515
  const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
1314
1516
  if (typoFindings.length > 0) {
1315
1517
  pageLevelFindings.push(...typoFindings);
@@ -1,9 +1,15 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
+ import { loadDesignSystemForCwd } from '../design-system.mjs';
4
5
  import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
5
6
  import { detectHtml } from '../engines/static-html/detect-html.mjs';
6
7
  import { detectText } from '../engines/regex/detect-text.mjs';
8
+ import {
9
+ filterDetectionFindings,
10
+ readDetectionConfig,
11
+ shouldIgnoreDetectionFile,
12
+ } from '../../lib/impeccable-config.mjs';
7
13
  import {
8
14
  HTML_EXTENSIONS,
9
15
  buildImportGraph,
@@ -79,10 +85,17 @@ function printUsage() {
79
85
  Scan files or URLs for UI anti-patterns and design quality issues.
80
86
 
81
87
  Options:
82
- --json Output results as JSON
83
- --gpt Also report GPT-specific provider tells (off by default)
84
- --gemini Also report Gemini-specific provider tells (off by default)
85
- --help Show this help message
88
+ --json Output results as JSON
89
+ --gpt Also report GPT-specific provider tells (off by default)
90
+ --gemini Also report Gemini-specific provider tells (off by default)
91
+ --no-config Do not apply project config, detector ignores, or DESIGN.md
92
+ --no-design-system Do not load local DESIGN.md / .impeccable/design.json context
93
+ --help Show this help message
94
+
95
+ Project config:
96
+ Respects .impeccable/config.json and .impeccable/config.local.json detector
97
+ settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
98
+ and detector.designSystem.enabled.
86
99
 
87
100
  Detection modes:
88
101
  HTML files Static HTML/CSS analysis (default, catches linked CSS)
@@ -93,7 +106,8 @@ Examples:
93
106
  impeccable detect src/
94
107
  impeccable detect index.html
95
108
  impeccable detect https://example.com
96
- impeccable detect --json .`);
109
+ impeccable detect --json .
110
+ impeccable detect --no-config src/`);
97
111
  }
98
112
 
99
113
  async function detectCli() {
@@ -114,10 +128,16 @@ async function detectCli() {
114
128
  'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
115
129
  );
116
130
  }
131
+ const configEnabled = !args.includes('--no-config');
132
+ const detectionConfig = configEnabled
133
+ ? readDetectionConfig(process.cwd())
134
+ : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
117
135
  const providers = [];
118
136
  if (args.includes('--gpt')) providers.push('gpt');
119
137
  if (args.includes('--gemini')) providers.push('gemini');
120
- const scanOptions = { providers };
138
+ const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
139
+ const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
140
+ const scanOptions = designSystem ? { providers, designSystem } : { providers };
121
141
  const targets = args.filter(a => !a.startsWith('--'));
122
142
 
123
143
  if (helpMode) { printUsage(); process.exit(0); }
@@ -175,7 +195,8 @@ async function detectCli() {
175
195
  }
176
196
  }
177
197
 
178
- const files = walkDir(resolved);
198
+ const files = walkDir(resolved)
199
+ .filter(file => !shouldIgnoreDetectionFile(file, process.cwd(), detectionConfig));
179
200
  const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;
180
201
 
181
202
  // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
@@ -219,6 +240,7 @@ async function detectCli() {
219
240
  allFindings.push(...fileFindings);
220
241
  }
221
242
  } else if (stat.isFile()) {
243
+ if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
222
244
  const ext = path.extname(resolved).toLowerCase();
223
245
  if (HTML_EXTENSIONS.has(ext)) {
224
246
  allFindings.push(...await detectHtml(resolved, scanOptions));
@@ -232,6 +254,8 @@ async function detectCli() {
232
254
  }
233
255
  }
234
256
 
257
+ allFindings = filterDetectionFindings(allFindings, detectionConfig);
258
+
235
259
  if (allFindings.length > 0) {
236
260
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
237
261
  else process.stderr.write(formatFindings(allFindings, false) + '\n');