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.
- package/README.md +2 -2
- package/README.npm.md +2 -2
- package/README.repo.md +16 -6
- package/cli/bin/cli.js +5 -0
- package/cli/bin/commands/ignores.mjs +330 -0
- package/cli/bin/commands/skills.mjs +36 -4
- package/cli/engine/browser/injected/index.mjs +202 -0
- package/cli/engine/cli/main.mjs +31 -7
- package/cli/engine/design-system.mjs +750 -0
- package/cli/engine/detect-antipatterns-browser.js +231 -0
- package/cli/engine/detect-antipatterns.mjs +7 -0
- package/cli/engine/engines/browser/detect-url.mjs +29 -4
- package/cli/engine/engines/regex/detect-text.mjs +10 -0
- package/cli/engine/engines/static-html/css-cascade.mjs +2 -0
- package/cli/engine/engines/static-html/detect-html.mjs +21 -0
- package/cli/engine/registry/antipatterns.mjs +29 -0
- package/cli/lib/impeccable-config.mjs +524 -5
- package/package.json +2 -2
|
@@ -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);
|
package/cli/engine/cli/main.mjs
CHANGED
|
@@ -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
|
|
83
|
-
--gpt
|
|
84
|
-
--gemini
|
|
85
|
-
--
|
|
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
|
|
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');
|