impeccable 3.2.1 → 3.3.1
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 +30 -9
- package/cli/bin/commands/ignores.mjs +27 -6
- package/cli/bin/commands/skills.mjs +168 -22
- package/cli/engine/browser/injected/index.mjs +84 -6
- package/cli/engine/cli/main.mjs +143 -26
- package/cli/engine/design-system.mjs +181 -12
- package/cli/engine/detect-antipatterns-browser.js +2877 -138
- package/cli/engine/engines/browser/detect-url.mjs +67 -4
- package/cli/engine/engines/regex/detect-text.mjs +266 -70
- package/cli/engine/engines/static-html/css-cascade.mjs +161 -5
- package/cli/engine/engines/static-html/detect-html.mjs +18 -5
- package/cli/engine/findings.mjs +7 -1
- package/cli/engine/registry/antipatterns.mjs +142 -37
- package/cli/engine/rules/checks.mjs +2706 -127
- package/cli/engine/shared/constants.mjs +11 -0
- package/cli/lib/download-providers.js +2 -0
- package/cli/lib/impeccable-config.mjs +20 -5
- package/package.json +7 -19
|
@@ -2,7 +2,7 @@ import fs from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
|
|
4
4
|
import { profileStep, recordProfileEvent } from '../../profile/profiler.mjs';
|
|
5
|
-
import { parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
|
|
5
|
+
import { collectCssCustomProps, cssLengthToPx, parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
|
|
6
6
|
|
|
7
7
|
// ---------------------------------------------------------------------------
|
|
8
8
|
// jsdom CSS-variable border override map
|
|
@@ -245,6 +245,10 @@ const STATIC_DEFAULT_STYLE = {
|
|
|
245
245
|
outlineColor: 'rgb(0, 0, 0)',
|
|
246
246
|
outlineStyle: 'none',
|
|
247
247
|
boxShadow: 'none',
|
|
248
|
+
// NOT in STATIC_INHERITED_PROPS even though text-shadow inherits in real
|
|
249
|
+
// CSS: the glow check only needs to fire once, on the element that
|
|
250
|
+
// declares the shadow, not on every descendant.
|
|
251
|
+
textShadow: 'none',
|
|
248
252
|
fontFamily: '',
|
|
249
253
|
fontSize: '16px',
|
|
250
254
|
fontStyle: 'normal',
|
|
@@ -302,6 +306,7 @@ const STATIC_PROP_MAP = {
|
|
|
302
306
|
'outline-color': 'outlineColor',
|
|
303
307
|
'outline-style': 'outlineStyle',
|
|
304
308
|
'box-shadow': 'boxShadow',
|
|
309
|
+
'text-shadow': 'textShadow',
|
|
305
310
|
'font-family': 'fontFamily',
|
|
306
311
|
'font-size': 'fontSize',
|
|
307
312
|
'font-style': 'fontStyle',
|
|
@@ -420,6 +425,22 @@ function extractStaticColor(value) {
|
|
|
420
425
|
if (!value) return '';
|
|
421
426
|
const raw = String(value).trim();
|
|
422
427
|
if (/^var\(/i.test(raw)) return raw;
|
|
428
|
+
// color-mix(...) needs balanced-paren capture (its arguments regularly
|
|
429
|
+
// contain nested var()/oklch() calls AND the keyword `transparent`, which
|
|
430
|
+
// the flat regex below would otherwise pluck out of the middle of the
|
|
431
|
+
// expression and report as the whole color).
|
|
432
|
+
const mixStart = raw.search(/color-mix\(/i);
|
|
433
|
+
if (mixStart !== -1) {
|
|
434
|
+
let depth = 0;
|
|
435
|
+
for (let i = raw.indexOf('(', mixStart); i < raw.length; i++) {
|
|
436
|
+
if (raw[i] === '(') depth++;
|
|
437
|
+
else if (raw[i] === ')') {
|
|
438
|
+
depth--;
|
|
439
|
+
if (depth === 0) return raw.slice(mixStart, i + 1);
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
return '';
|
|
443
|
+
}
|
|
423
444
|
const colorLike = raw.match(/(?:rgba?\([^)]+\)|oklch\([^)]+\)|oklab\([^)]+\)|lch\([^)]+\)|lab\([^)]+\)|hsla?\([^)]+\)|hwb\([^)]+\)|#[0-9a-f]{3,8}\b|\b(?:black|white|gray|grey|silver|red|green|blue|transparent)\b)/i);
|
|
424
445
|
if (!colorLike) return '';
|
|
425
446
|
return colorLike[0];
|
|
@@ -532,6 +553,15 @@ function expandStaticDeclaration(prop, value) {
|
|
|
532
553
|
const beforeImage = hasImage ? v.split(/(?:repeating-)?(?:linear|radial|conic)-gradient\(|url\(/i)[0] : v;
|
|
533
554
|
const color = extractStaticColor(hasImage ? beforeImage : v);
|
|
534
555
|
if (color) out.push(['backgroundColor', color]);
|
|
556
|
+
// The `background` shorthand resets every longhand it does not set.
|
|
557
|
+
// Without this, `pre code { background: none }` leaves an earlier
|
|
558
|
+
// `background: var(--surface)` color standing and the contrast checks
|
|
559
|
+
// measure text against a surface the browser never paints. var() values
|
|
560
|
+
// stay untouched: they may resolve to a color later in the pipeline.
|
|
561
|
+
if (!color && !hasImage && !/var\(/i.test(v)) {
|
|
562
|
+
out.push(['backgroundColor', 'rgba(0, 0, 0, 0)']);
|
|
563
|
+
out.push(['backgroundImage', 'none']);
|
|
564
|
+
}
|
|
535
565
|
return out;
|
|
536
566
|
}
|
|
537
567
|
if (p === 'border') {
|
|
@@ -702,7 +732,20 @@ function collectStaticCssRules(cssText, csstree) {
|
|
|
702
732
|
});
|
|
703
733
|
});
|
|
704
734
|
for (const selector of splitCssList(selectorText)) {
|
|
705
|
-
if (selector)
|
|
735
|
+
if (!selector) continue;
|
|
736
|
+
// :hover rules can't be matched statically as-is (no interaction
|
|
737
|
+
// state), but they carry real cascade weight while hovered. Tag
|
|
738
|
+
// them and record a state-stripped selector so the hover pass can
|
|
739
|
+
// find their targets; specificity stays computed from the ORIGINAL
|
|
740
|
+
// selector (per CSS, :hover counts as a class).
|
|
741
|
+
const isHover = /:hover\b/i.test(selector);
|
|
742
|
+
let matchSelector = null;
|
|
743
|
+
if (isHover) {
|
|
744
|
+
matchSelector = selector.replace(/:hover\b/gi, '').trim();
|
|
745
|
+
if (!matchSelector || /[>+~]\s*$/.test(matchSelector)) matchSelector = null;
|
|
746
|
+
else matchSelector = matchSelector.replace(/(^|[\s>+~])(?=$|[\s>+~])/g, '$1*');
|
|
747
|
+
}
|
|
748
|
+
rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++, isHover, matchSelector });
|
|
706
749
|
}
|
|
707
750
|
return;
|
|
708
751
|
}
|
|
@@ -805,6 +848,13 @@ class StaticDocument {
|
|
|
805
848
|
this.domutils = modules.domutils;
|
|
806
849
|
this._wrappers = new WeakMap();
|
|
807
850
|
this._styleMap = new WeakMap();
|
|
851
|
+
this._hoverStyleMap = new WeakMap();
|
|
852
|
+
this._accentDashPseudo = new WeakSet();
|
|
853
|
+
// Elements whose ::before/::after paints a full-cover opaque surface
|
|
854
|
+
// (position absolute/fixed + inset 0 + solid background). The pseudo is
|
|
855
|
+
// the element's visible background for contrast purposes even though it
|
|
856
|
+
// never joins the element cascade.
|
|
857
|
+
this._pseudoSurface = new WeakMap();
|
|
808
858
|
}
|
|
809
859
|
wrap(node) {
|
|
810
860
|
let wrapped = this._wrappers.get(node);
|
|
@@ -841,6 +891,24 @@ class StaticDocument {
|
|
|
841
891
|
getStyle(el) {
|
|
842
892
|
return this._styleMap.get(el.node) || makeStaticStyle();
|
|
843
893
|
}
|
|
894
|
+
setHoverStyle(node, style) {
|
|
895
|
+
this._hoverStyleMap.set(node, style);
|
|
896
|
+
}
|
|
897
|
+
getHoverStyle(el) {
|
|
898
|
+
return this._hoverStyleMap.get(el.node) || null;
|
|
899
|
+
}
|
|
900
|
+
setAccentDashPseudo(node) {
|
|
901
|
+
this._accentDashPseudo.add(node);
|
|
902
|
+
}
|
|
903
|
+
hasAccentDashPseudo(el) {
|
|
904
|
+
return this._accentDashPseudo.has(el.node);
|
|
905
|
+
}
|
|
906
|
+
setPseudoSurface(node, color) {
|
|
907
|
+
this._pseudoSurface.set(node, color);
|
|
908
|
+
}
|
|
909
|
+
getPseudoSurface(el) {
|
|
910
|
+
return this._pseudoSurface.get(el.node) || null;
|
|
911
|
+
}
|
|
844
912
|
}
|
|
845
913
|
|
|
846
914
|
function makeStaticStyle(values = {}) {
|
|
@@ -856,6 +924,9 @@ function buildStaticWindow(staticDoc) {
|
|
|
856
924
|
return {
|
|
857
925
|
document: staticDoc,
|
|
858
926
|
getComputedStyle: (el) => staticDoc.getStyle(el),
|
|
927
|
+
getHoverStyle: (el) => staticDoc.getHoverStyle(el),
|
|
928
|
+
hasAccentDashPseudo: (el) => staticDoc.hasAccentDashPseudo(el),
|
|
929
|
+
getPseudoSurface: (el) => staticDoc.getPseudoSurface(el),
|
|
859
930
|
};
|
|
860
931
|
}
|
|
861
932
|
|
|
@@ -886,6 +957,13 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
|
|
|
886
957
|
|
|
887
958
|
function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePath) {
|
|
888
959
|
const specified = new Map();
|
|
960
|
+
// Declarations from :hover rules, matched via their state-stripped
|
|
961
|
+
// selectors. Merged per-property against the resting cascade in
|
|
962
|
+
// computeNode — a hover declaration only takes effect if it would win
|
|
963
|
+
// the cascade while the element is hovered (all resting rules still
|
|
964
|
+
// apply in that state).
|
|
965
|
+
const hoverSpecified = new Map();
|
|
966
|
+
const rootCustomProps = collectCssCustomProps(cssText);
|
|
889
967
|
const allNodes = modules.selectAll('*', root.children || []);
|
|
890
968
|
const rules = profileStep(profile, {
|
|
891
969
|
engine: 'static-html',
|
|
@@ -901,9 +979,65 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
|
|
901
979
|
target: filePath,
|
|
902
980
|
}, () => {
|
|
903
981
|
for (const rule of rules) {
|
|
982
|
+
// ::before/::after rules can't join the element cascade (pseudo
|
|
983
|
+
// elements aren't DOM nodes), but one shape matters to the eyebrow
|
|
984
|
+
// check: the short chromatic "kicker dash" (content box 8-80px wide,
|
|
985
|
+
// 1-6px tall, accent-colored fill). Mark the base-selector matches
|
|
986
|
+
// so checkElementHeroEyebrow can see the dash.
|
|
987
|
+
if (!rule.isHover) {
|
|
988
|
+
const pm = rule.selector.match(/^(.+?)\s*::?(?:before|after)$/i);
|
|
989
|
+
if (pm) {
|
|
990
|
+
const decls = new Map();
|
|
991
|
+
for (const d of rule.declarations) decls.set(d.prop.toLowerCase(), d.value);
|
|
992
|
+
const w = cssLengthToPx(resolveVarRefs(decls.get('width') || decls.get('inline-size') || '', rootCustomProps));
|
|
993
|
+
const h = cssLengthToPx(resolveVarRefs(decls.get('height') || decls.get('block-size') || '', rootCustomProps));
|
|
994
|
+
if (w != null && h != null && w >= 8 && w <= 80 && h >= 1 && h <= 6) {
|
|
995
|
+
const bgRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
|
|
996
|
+
const token = bgRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
|
|
997
|
+
const c = parseAnyColor(token ? token[0] : bgRaw);
|
|
998
|
+
if (c && (c.a ?? 1) >= 0.1 && Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b) >= 30) {
|
|
999
|
+
try {
|
|
1000
|
+
for (const node of modules.selectAll(pm[1], root.children || [])) {
|
|
1001
|
+
staticDoc.setAccentDashPseudo(node);
|
|
1002
|
+
}
|
|
1003
|
+
} catch { /* unsupported base selector */ }
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
// Full-cover surface pseudo: the CTA construction where the
|
|
1007
|
+
// element itself stays transparent and a ::before/::after with
|
|
1008
|
+
// position absolute/fixed + inset 0 (or all four sides 0, or
|
|
1009
|
+
// 100% width and height) plus an opaque background paints the
|
|
1010
|
+
// visible surface. Mark base-selector matches so the contrast
|
|
1011
|
+
// checks measure text against the surface the browser renders.
|
|
1012
|
+
const pseudoPos = String(decls.get('position') || '').toLowerCase();
|
|
1013
|
+
if (pseudoPos === 'absolute' || pseudoPos === 'fixed') {
|
|
1014
|
+
const zeroLen = v => v != null && /^0(?:px)?$/.test(String(v).trim());
|
|
1015
|
+
const insetRaw = String(decls.get('inset') || '').trim();
|
|
1016
|
+
const coversBox = (insetRaw !== '' && insetRaw.split(/\s+/).every(t => /^0(?:px)?$/.test(t)))
|
|
1017
|
+
|| ['top', 'right', 'bottom', 'left'].every(side => zeroLen(decls.get(side)))
|
|
1018
|
+
|| (String(decls.get('width') || '').trim() === '100%'
|
|
1019
|
+
&& String(decls.get('height') || '').trim() === '100%');
|
|
1020
|
+
if (coversBox && decls.has('content')) {
|
|
1021
|
+
const surfRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
|
|
1022
|
+
const surfToken = surfRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
|
|
1023
|
+
const surf = parseAnyColor(surfToken ? surfToken[0] : surfRaw);
|
|
1024
|
+
if (surf && (surf.a ?? 1) >= 0.9 && !/gradient/i.test(surfRaw)) {
|
|
1025
|
+
try {
|
|
1026
|
+
for (const node of modules.selectAll(pm[1], root.children || [])) {
|
|
1027
|
+
staticDoc.setPseudoSurface(node, surf);
|
|
1028
|
+
}
|
|
1029
|
+
} catch { /* unsupported base selector */ }
|
|
1030
|
+
}
|
|
1031
|
+
}
|
|
1032
|
+
}
|
|
1033
|
+
continue;
|
|
1034
|
+
}
|
|
1035
|
+
}
|
|
1036
|
+
const matchSelector = rule.isHover ? rule.matchSelector : rule.selector;
|
|
1037
|
+
if (!matchSelector) continue;
|
|
904
1038
|
let matched;
|
|
905
1039
|
try {
|
|
906
|
-
matched = modules.selectAll(
|
|
1040
|
+
matched = modules.selectAll(matchSelector, root.children || []);
|
|
907
1041
|
} catch {
|
|
908
1042
|
recordProfileEvent(profile, {
|
|
909
1043
|
engine: 'static-html',
|
|
@@ -912,13 +1046,13 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
|
|
912
1046
|
target: filePath,
|
|
913
1047
|
ms: 0,
|
|
914
1048
|
findings: 0,
|
|
915
|
-
detail:
|
|
1049
|
+
detail: matchSelector,
|
|
916
1050
|
});
|
|
917
1051
|
continue;
|
|
918
1052
|
}
|
|
919
1053
|
for (const node of matched) {
|
|
920
1054
|
for (const decl of rule.declarations) {
|
|
921
|
-
applyStaticDeclaration(specified, node, decl.prop, decl.value, {
|
|
1055
|
+
applyStaticDeclaration(rule.isHover ? hoverSpecified : specified, node, decl.prop, decl.value, {
|
|
922
1056
|
important: decl.important,
|
|
923
1057
|
specificity: rule.specificity,
|
|
924
1058
|
order: rule.order,
|
|
@@ -961,6 +1095,28 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
|
|
961
1095
|
}
|
|
962
1096
|
const style = makeStaticStyle(values);
|
|
963
1097
|
staticDoc.setStyle(node, style);
|
|
1098
|
+
|
|
1099
|
+
// Hover pass: limited to the two properties the hover-contrast check
|
|
1100
|
+
// consumes. A hover declaration wins only if it beats the resting
|
|
1101
|
+
// winner for that property under normal cascade rules (specificity /
|
|
1102
|
+
// order / importance) — exactly what a browser computes while the
|
|
1103
|
+
// element is hovered.
|
|
1104
|
+
const hoverMap = hoverSpecified.get(node);
|
|
1105
|
+
if (hoverMap) {
|
|
1106
|
+
let hoverValues = null;
|
|
1107
|
+
for (const prop of ['color', 'backgroundColor']) {
|
|
1108
|
+
const hoverDecl = hoverMap.get(prop);
|
|
1109
|
+
if (!hoverDecl) continue;
|
|
1110
|
+
const restingDecl = specifiedMap.get(prop);
|
|
1111
|
+
if (!compareStaticPriority(restingDecl, hoverDecl)) continue;
|
|
1112
|
+
const next = normalizeStaticCssValue(prop, hoverDecl.value, customProps, parentStyle, values);
|
|
1113
|
+
if (next === values[prop]) continue;
|
|
1114
|
+
if (!hoverValues) hoverValues = { ...values };
|
|
1115
|
+
hoverValues[prop] = next;
|
|
1116
|
+
}
|
|
1117
|
+
if (hoverValues) staticDoc.setHoverStyle(node, makeStaticStyle(hoverValues));
|
|
1118
|
+
}
|
|
1119
|
+
|
|
964
1120
|
for (const child of node.children || []) {
|
|
965
1121
|
if (child.type === 'tag') computeNode(child, style, customProps);
|
|
966
1122
|
}
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
checkElementGlow,
|
|
19
19
|
checkElementGptBorderShadow,
|
|
20
20
|
checkElementHeroEyebrow,
|
|
21
|
+
checkElementHoverContrast,
|
|
21
22
|
checkElementIconTile,
|
|
22
23
|
checkElementItalicSerif,
|
|
23
24
|
checkElementMotion,
|
|
@@ -25,13 +26,14 @@ import {
|
|
|
25
26
|
checkElementQuality,
|
|
26
27
|
checkCreamPalette,
|
|
27
28
|
checkHtmlPatterns,
|
|
29
|
+
checkNumberedSectionLabelsFromDoc,
|
|
28
30
|
checkPageLayout,
|
|
29
31
|
checkPageQualityFromDoc,
|
|
32
|
+
checkRepeatedContainerTextFromDoc,
|
|
30
33
|
checkRepeatedSectionKickersFromDoc,
|
|
31
34
|
resolveBackground,
|
|
32
35
|
resolveBorderRadiusPx,
|
|
33
36
|
} from '../../rules/checks.mjs';
|
|
34
|
-
import { filterByProviders } from '../../registry/antipatterns.mjs';
|
|
35
37
|
import { detectText, runTextContentAnalyzers } from '../regex/detect-text.mjs';
|
|
36
38
|
import {
|
|
37
39
|
StaticDocument,
|
|
@@ -90,8 +92,9 @@ function checkElementBrokenImage(el) {
|
|
|
90
92
|
}
|
|
91
93
|
|
|
92
94
|
const STATIC_ELEMENT_RULES = [
|
|
93
|
-
{ id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window)) },
|
|
95
|
+
{ id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window), el) },
|
|
94
96
|
{ id: 'color-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementColors(el, style, tag, window, customPropMap, false) },
|
|
97
|
+
{ id: 'hover-color-rules', selector: '*', run: (el, tag, style, window) => checkElementHoverContrast(el, style, tag, window) },
|
|
95
98
|
{ id: 'dark-glow', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap)) },
|
|
96
99
|
{ id: 'motion-rules', selector: '*', run: (el, tag, style) => checkElementMotion(tag, style) },
|
|
97
100
|
{ id: 'icon-tile-stack', selector: 'h1,h2,h3,h4,h5,h6', run: (el, tag, _style, window) => checkElementIconTile(el, tag, window) },
|
|
@@ -200,6 +203,12 @@ async function detectHtml(filePath, options = {}) {
|
|
|
200
203
|
for (const f of runPageCheck('repeated-section-kickers', () => checkRepeatedSectionKickersFromDoc(document, window))) {
|
|
201
204
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
202
205
|
}
|
|
206
|
+
for (const f of runPageCheck('numbered-section-labels', () => checkNumberedSectionLabelsFromDoc(document, window))) {
|
|
207
|
+
findings.push(finding(f.id, filePath, f.snippet));
|
|
208
|
+
}
|
|
209
|
+
for (const f of runPageCheck('repeated-container-text', () => checkRepeatedContainerTextFromDoc(document, window))) {
|
|
210
|
+
findings.push(finding(f.id, filePath, f.snippet));
|
|
211
|
+
}
|
|
203
212
|
for (const f of runPageCheck('layout-rules', () => checkPageLayout(document, window))) {
|
|
204
213
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
205
214
|
}
|
|
@@ -212,7 +221,12 @@ async function detectHtml(filePath, options = {}) {
|
|
|
212
221
|
for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
|
|
213
222
|
item.id !== 'bounce-easing' && item.id !== 'layout-transition'
|
|
214
223
|
))) {
|
|
215
|
-
|
|
224
|
+
const item = finding(f.id, filePath, f.snippet);
|
|
225
|
+
// Position-aware severity promotion: checks may attach a per-finding
|
|
226
|
+
// severity (e.g. a pulsing dot inside a header/nav landmark) that
|
|
227
|
+
// overrides the registry default.
|
|
228
|
+
if (f.severity) item.severity = f.severity;
|
|
229
|
+
findings.push(item);
|
|
216
230
|
}
|
|
217
231
|
// Text-content analyzers (em-dash overuse, marketing buzzwords,
|
|
218
232
|
// numbered section markers, aphoristic cadence) live in the regex
|
|
@@ -224,11 +238,10 @@ async function detectHtml(filePath, options = {}) {
|
|
|
224
238
|
}
|
|
225
239
|
}
|
|
226
240
|
|
|
227
|
-
const byProvider = filterByProviders(findings, options.providers);
|
|
228
241
|
// Static-HTML findings carry no line number, so only whole-file
|
|
229
242
|
// `impeccable-disable` directives apply here — exactly the standalone-document
|
|
230
243
|
// waiver this primitive targets. Bypassed by `--no-config` / `--no-inline-ignores`.
|
|
231
|
-
return options?.inlineIgnores === false ?
|
|
244
|
+
return options?.inlineIgnores === false ? findings : applyInlineIgnores(findings, html);
|
|
232
245
|
}
|
|
233
246
|
|
|
234
247
|
export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };
|
package/cli/engine/findings.mjs
CHANGED
|
@@ -6,7 +6,13 @@ function getAP(id) {
|
|
|
6
6
|
|
|
7
7
|
function finding(id, filePath, snippet, line = 0) {
|
|
8
8
|
const ap = getAP(id);
|
|
9
|
-
|
|
9
|
+
const base = { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
|
|
10
|
+
// Advisory findings are detected but reported separately and never counted as
|
|
11
|
+
// failures. Carry the flag on the finding so every consumer (CLI, JSON, hook)
|
|
12
|
+
// can partition without a registry lookup. Only stamped when true to keep the
|
|
13
|
+
// finding shape stable for the vast majority of rules.
|
|
14
|
+
if (ap.advisory === true) base.advisory = true;
|
|
15
|
+
return base;
|
|
10
16
|
}
|
|
11
17
|
|
|
12
18
|
export { getAP, finding };
|
|
@@ -32,9 +32,9 @@ const ANTIPATTERNS = [
|
|
|
32
32
|
id: 'single-font',
|
|
33
33
|
category: 'slop',
|
|
34
34
|
scopes: ['type'],
|
|
35
|
-
name: 'Single font
|
|
35
|
+
name: 'Single font without hierarchy',
|
|
36
36
|
description:
|
|
37
|
-
'Only one font family is used for the entire page.
|
|
37
|
+
'Only one font family is used for the entire page. A single family can work when weight and size contrast carry the hierarchy; otherwise pair a distinctive display font with a refined body font.',
|
|
38
38
|
skillSection: 'Typography',
|
|
39
39
|
skillGuideline: 'only one font family for the entire page',
|
|
40
40
|
},
|
|
@@ -104,15 +104,60 @@ const ANTIPATTERNS = [
|
|
|
104
104
|
skillSection: 'Motion',
|
|
105
105
|
skillGuideline: 'bounce or elastic easing',
|
|
106
106
|
},
|
|
107
|
+
{
|
|
108
|
+
id: 'pulsing-dot',
|
|
109
|
+
category: 'slop',
|
|
110
|
+
name: 'Pulsing status dot',
|
|
111
|
+
description:
|
|
112
|
+
'Small pulsing status dots simulate liveness decoratively. Reserve pulse animation for indicators tied to genuinely live, changing data; a static indicator with clear labeling is honest and calmer.',
|
|
113
|
+
skillSection: 'Motion',
|
|
114
|
+
skillGuideline: 'decorative pulsing status dot',
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
id: 'blinking-cursor',
|
|
118
|
+
category: 'slop',
|
|
119
|
+
severity: 'advisory',
|
|
120
|
+
name: 'Decorative blinking cursor',
|
|
121
|
+
description:
|
|
122
|
+
'A blinking text cursor animated into a hero or landing section simulates typing where no input exists. It borrows the dev-tool aesthetic as decoration. Real editable fields draw their own caret; anywhere else, let the composition hold attention without a fake prompt.',
|
|
123
|
+
skillSection: 'Motion',
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
id: 'shape-assembled-illustration',
|
|
127
|
+
category: 'slop',
|
|
128
|
+
severity: 'advisory',
|
|
129
|
+
name: 'Shape-assembled illustration',
|
|
130
|
+
description:
|
|
131
|
+
'A large inline SVG that builds a pictorial scene from a pile of primitive shapes reads as placeholder clip art, not illustration. Icons, logos, and data graphics are fine at their scale; a hero-sized visual deserves real artwork, a photograph, or a deliberately drawn graphic.',
|
|
132
|
+
skillSection: 'Imagery',
|
|
133
|
+
},
|
|
107
134
|
{
|
|
108
135
|
id: 'dark-glow',
|
|
109
136
|
category: 'slop',
|
|
110
|
-
name: '
|
|
137
|
+
name: 'Glowing shadow accents',
|
|
111
138
|
description:
|
|
112
|
-
'
|
|
139
|
+
'Colored glow shadows — a zero-offset chromatic halo (box- or text-shadow) on any background, or any colored blurred shadow on a dark background — are the default "cool" look of AI-generated UIs. Use neutral elevation shadows and subtle, purposeful lighting instead.',
|
|
113
140
|
skillSection: 'Color & Contrast',
|
|
114
141
|
skillGuideline: 'dark mode with glowing accents',
|
|
115
142
|
},
|
|
143
|
+
{
|
|
144
|
+
id: 'radial-halo',
|
|
145
|
+
category: 'slop',
|
|
146
|
+
name: 'Radial-gradient background halo',
|
|
147
|
+
description:
|
|
148
|
+
'A chromatic radial-gradient wash — saturated at the center, fading to transparent — used as a decorative background glow on a dark page. Same tell as glowing shadows, drawn with a gradient instead of a shadow. Ground the surface with a solid or subtly shifted background instead.',
|
|
149
|
+
skillSection: 'Color & Contrast',
|
|
150
|
+
skillGuideline: 'dark mode with glowing accents',
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
id: 'marquee',
|
|
154
|
+
category: 'slop',
|
|
155
|
+
name: 'Auto-scrolling marquee',
|
|
156
|
+
description:
|
|
157
|
+
'Continuously auto-scrolling content demands attention it has not earned and hides half its content at any moment. Reserve motion for content that changes; let readers move at their own pace.',
|
|
158
|
+
skillSection: 'Motion',
|
|
159
|
+
skillGuideline: 'auto-scrolling marquee',
|
|
160
|
+
},
|
|
116
161
|
{
|
|
117
162
|
id: 'icon-tile-stack',
|
|
118
163
|
category: 'slop',
|
|
@@ -155,22 +200,27 @@ const ANTIPATTERNS = [
|
|
|
155
200
|
skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
|
|
156
201
|
},
|
|
157
202
|
{
|
|
158
|
-
id: 'numbered-section-
|
|
203
|
+
id: 'numbered-section-labels',
|
|
159
204
|
category: 'slop',
|
|
160
|
-
scopes: ['
|
|
205
|
+
scopes: ['type'],
|
|
161
206
|
severity: 'advisory',
|
|
162
|
-
name: '
|
|
207
|
+
name: 'Tiny numbered section labels',
|
|
163
208
|
description:
|
|
164
|
-
'
|
|
209
|
+
'Small numeric index labels riding next to section headings, repeated section after section, are AI editorial scaffolding — a page numbering its own chapters instead of earning structure. Let hierarchy, content, and rhythm carry the sequence.',
|
|
165
210
|
skillSection: 'Layout & Space',
|
|
166
211
|
skillGuideline: 'numbered section markers',
|
|
167
212
|
},
|
|
168
213
|
{
|
|
169
214
|
id: 'em-dash-overuse',
|
|
170
215
|
category: 'slop',
|
|
216
|
+
// Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
|
|
217
|
+
// rather than a failure. It fires only on the AI saturation pattern, not on
|
|
218
|
+
// ordinary prose. Advisory findings are surfaced separately, never counted
|
|
219
|
+
// as failures, and skipped by the design hook unless a project opts in.
|
|
220
|
+
advisory: true,
|
|
171
221
|
name: 'Em-dash overuse',
|
|
172
222
|
description:
|
|
173
|
-
'
|
|
223
|
+
'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
|
|
174
224
|
skillSection: 'Copy',
|
|
175
225
|
skillGuideline: 'no em dashes',
|
|
176
226
|
},
|
|
@@ -223,6 +273,49 @@ const ANTIPATTERNS = [
|
|
|
223
273
|
},
|
|
224
274
|
|
|
225
275
|
// ── Quality: general design and accessibility issues ──
|
|
276
|
+
{
|
|
277
|
+
id: 'script-error',
|
|
278
|
+
category: 'quality',
|
|
279
|
+
severity: 'error',
|
|
280
|
+
name: 'Uncaught script error on load',
|
|
281
|
+
description:
|
|
282
|
+
'A script threw an uncaught exception or failed to parse while the page loaded. Broken JavaScript silently kills reveals, interactions, and dynamic content, and can leave most of a page invisible. Fix the error before judging anything else.',
|
|
283
|
+
},
|
|
284
|
+
{
|
|
285
|
+
id: 'content-hidden-at-rest',
|
|
286
|
+
category: 'quality',
|
|
287
|
+
severity: 'error',
|
|
288
|
+
scopes: ['layout'],
|
|
289
|
+
name: 'Content invisible at rest',
|
|
290
|
+
description:
|
|
291
|
+
'A large share of the page text sits at opacity 0 or visibility hidden even after every reveal handler had a chance to run. This is the failed-reveal signature: the content shipped but never becomes visible. Make content visible by default and let JavaScript enhance its entrance instead of gating its existence.',
|
|
292
|
+
},
|
|
293
|
+
{
|
|
294
|
+
id: 'edge-flush-cards',
|
|
295
|
+
category: 'quality',
|
|
296
|
+
scopes: ['layout'],
|
|
297
|
+
name: 'Cards flush against the scroller edge',
|
|
298
|
+
description:
|
|
299
|
+
'Cards inside a horizontal scroller or tab panel sit flush against the container edge at rest while keeping a gutter on the other side, so their edges and rounded corners get cut off. Usually the panel is sized wider than its clip box. Keep a consistent inset on both sides.',
|
|
300
|
+
},
|
|
301
|
+
{
|
|
302
|
+
id: 'text-occlusion',
|
|
303
|
+
category: 'quality',
|
|
304
|
+
scopes: ['layout'],
|
|
305
|
+
name: 'Text occluded by an overlapping element',
|
|
306
|
+
description:
|
|
307
|
+
'Text is painted under an opaque element or a second text run, so part of it cannot be read. A decorative box, a stacked layer, or an inline element with leaked padding lands on the words instead of beside them. Give overlapping layers room, or move the text out from under the layer above it.',
|
|
308
|
+
skillSection: 'Layout & Space',
|
|
309
|
+
},
|
|
310
|
+
{
|
|
311
|
+
id: 'first-viewport-column-overflow',
|
|
312
|
+
category: 'quality',
|
|
313
|
+
scopes: ['layout'],
|
|
314
|
+
name: 'One column stretches the first viewport',
|
|
315
|
+
description:
|
|
316
|
+
'A multi-column opening section lets one column run far past the fold while its sibling fits in a single viewport, so the short column floats in dead space and the fold falls deep inside one section. Balance the columns, cap the tall one, or let the long content flow below the opening row.',
|
|
317
|
+
skillSection: 'Layout & Space',
|
|
318
|
+
},
|
|
226
319
|
{
|
|
227
320
|
id: 'gray-on-color',
|
|
228
321
|
category: 'quality',
|
|
@@ -292,6 +385,15 @@ const ANTIPATTERNS = [
|
|
|
292
385
|
description:
|
|
293
386
|
'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
|
|
294
387
|
},
|
|
388
|
+
{
|
|
389
|
+
id: 'heading-rhythm',
|
|
390
|
+
category: 'quality',
|
|
391
|
+
scopes: ['layout', 'type'],
|
|
392
|
+
name: 'Heading crowded against the previous block',
|
|
393
|
+
description:
|
|
394
|
+
'A heading binds to the content it introduces, so the rendered space above it should exceed the space below it. When headings across a page sit as close or closer to the block above than to their own content, every section reads as if it captions the previous one. Open up the space above each heading.',
|
|
395
|
+
skillSection: 'Layout & Space',
|
|
396
|
+
},
|
|
295
397
|
{
|
|
296
398
|
id: 'justified-text',
|
|
297
399
|
category: 'quality',
|
|
@@ -308,6 +410,14 @@ const ANTIPATTERNS = [
|
|
|
308
410
|
description:
|
|
309
411
|
'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
|
|
310
412
|
},
|
|
413
|
+
{
|
|
414
|
+
id: 'undersized-ui-text',
|
|
415
|
+
category: 'quality',
|
|
416
|
+
scopes: ['type'],
|
|
417
|
+
name: 'Undersized functional text',
|
|
418
|
+
description:
|
|
419
|
+
'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
|
|
420
|
+
},
|
|
311
421
|
{
|
|
312
422
|
id: 'all-caps-body',
|
|
313
423
|
category: 'quality',
|
|
@@ -336,6 +446,13 @@ const ANTIPATTERNS = [
|
|
|
336
446
|
skillSection: 'Layout & Space',
|
|
337
447
|
skillGuideline: 'content wider than its container',
|
|
338
448
|
},
|
|
449
|
+
{
|
|
450
|
+
id: 'repeated-container-text',
|
|
451
|
+
category: 'quality',
|
|
452
|
+
name: 'Same text repeated inside one container',
|
|
453
|
+
description:
|
|
454
|
+
'The same literal text rendered three or more times in structurally different spots inside a single card or panel is redundant messaging — usually a status or label wired into every slot of a template. Say it once, in the slot where it matters most.',
|
|
455
|
+
},
|
|
339
456
|
{
|
|
340
457
|
id: 'clipped-overflow-container',
|
|
341
458
|
category: 'quality',
|
|
@@ -388,12 +505,11 @@ const ANTIPATTERNS = [
|
|
|
388
505
|
skillGuideline: 'font size outside the project design system',
|
|
389
506
|
},
|
|
390
507
|
|
|
391
|
-
// ──
|
|
508
|
+
// ── Common generated-UI tells ───────────────────────────────────────────
|
|
392
509
|
{
|
|
393
510
|
id: 'gpt-thin-border-wide-shadow',
|
|
394
511
|
category: 'slop',
|
|
395
512
|
severity: 'advisory',
|
|
396
|
-
gated: 'gpt',
|
|
397
513
|
name: 'Hairline border with wide shadow',
|
|
398
514
|
description:
|
|
399
515
|
'A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.',
|
|
@@ -404,7 +520,6 @@ const ANTIPATTERNS = [
|
|
|
404
520
|
id: 'repeating-stripes-gradient',
|
|
405
521
|
category: 'slop',
|
|
406
522
|
severity: 'advisory',
|
|
407
|
-
gated: 'gpt',
|
|
408
523
|
name: 'Repeating-gradient stripes',
|
|
409
524
|
description:
|
|
410
525
|
'Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain.',
|
|
@@ -415,10 +530,9 @@ const ANTIPATTERNS = [
|
|
|
415
530
|
id: 'codex-grid-background',
|
|
416
531
|
category: 'slop',
|
|
417
532
|
severity: 'advisory',
|
|
418
|
-
gated: 'gpt',
|
|
419
533
|
name: 'Decorative grid-line background',
|
|
420
534
|
description:
|
|
421
|
-
'A
|
|
535
|
+
'A decorative grid or line-field background drawn with hairline linear-gradient layers tiled by a fixed pixel cell is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
|
|
422
536
|
skillSection: 'Visual Details',
|
|
423
537
|
skillGuideline: 'two-axis grid-line gradient background',
|
|
424
538
|
},
|
|
@@ -426,7 +540,6 @@ const ANTIPATTERNS = [
|
|
|
426
540
|
id: 'theater-slop-phrase',
|
|
427
541
|
category: 'slop',
|
|
428
542
|
severity: 'advisory',
|
|
429
|
-
gated: 'gpt',
|
|
430
543
|
name: 'Theater framing copy',
|
|
431
544
|
description:
|
|
432
545
|
'Dismissing something as "theater" is a recurring generated-copy tic. Say plainly what the thing does or does not do.',
|
|
@@ -437,7 +550,6 @@ const ANTIPATTERNS = [
|
|
|
437
550
|
id: 'image-hover-transform',
|
|
438
551
|
category: 'slop',
|
|
439
552
|
severity: 'advisory',
|
|
440
|
-
gated: 'gemini',
|
|
441
553
|
name: 'Image hover transform',
|
|
442
554
|
description:
|
|
443
555
|
'Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction.',
|
|
@@ -457,6 +569,18 @@ function getAntipattern(id) {
|
|
|
457
569
|
return ANTIPATTERNS.find(rule => rule.id === id);
|
|
458
570
|
}
|
|
459
571
|
|
|
572
|
+
// Advisory rules are detected and reported, but never treated as failures:
|
|
573
|
+
// the CLI lists them under a separate "Advisory" section, they do not affect
|
|
574
|
+
// exit codes or the failure count, and the design hook skips them by default.
|
|
575
|
+
// The set is derived from the registry so a rule only needs `advisory: true`.
|
|
576
|
+
const ADVISORY_RULE_IDS = new Set(
|
|
577
|
+
ANTIPATTERNS.filter(rule => rule.advisory === true).map(rule => rule.id),
|
|
578
|
+
);
|
|
579
|
+
|
|
580
|
+
function isAdvisoryRule(id) {
|
|
581
|
+
return ADVISORY_RULE_IDS.has(id);
|
|
582
|
+
}
|
|
583
|
+
|
|
460
584
|
function getRulesForCategory(category) {
|
|
461
585
|
return ANTIPATTERNS.filter(rule => rule.category === category);
|
|
462
586
|
}
|
|
@@ -465,25 +589,6 @@ function getRuleEngineSupport(engine) {
|
|
|
465
589
|
return RULE_ENGINE_SUPPORT[engine] || new Set();
|
|
466
590
|
}
|
|
467
591
|
|
|
468
|
-
// Set of provider tags that gate rules off by default (e.g. 'gpt', 'gemini').
|
|
469
|
-
const GATED_PROVIDERS = new Set(
|
|
470
|
-
ANTIPATTERNS.map(rule => rule.gated).filter(Boolean),
|
|
471
|
-
);
|
|
472
|
-
|
|
473
|
-
// Drop findings for rules gated behind a provider tag unless that provider
|
|
474
|
-
// was explicitly enabled (CLI --gpt / --gemini). Non-gated findings always
|
|
475
|
-
// pass through. `findings` carry the rule id on `.antipattern`.
|
|
476
|
-
function filterByProviders(findings, providers = []) {
|
|
477
|
-
const enabled = new Set(providers || []);
|
|
478
|
-
if (!GATED_PROVIDERS.size) return findings;
|
|
479
|
-
return findings.filter(f => {
|
|
480
|
-
const rule = getAntipattern(f.antipattern);
|
|
481
|
-
if (!rule || !rule.gated) return true;
|
|
482
|
-
return enabled.has(rule.gated);
|
|
483
|
-
});
|
|
484
|
-
}
|
|
485
|
-
|
|
486
|
-
|
|
487
592
|
// Set of scope tags rules can declare (e.g. 'type', 'layout'). Used by the
|
|
488
593
|
// CLI --scope flag to narrow output to one design domain.
|
|
489
594
|
const RULE_SCOPES = new Set(
|
|
@@ -505,10 +610,10 @@ export {
|
|
|
505
610
|
ANTIPATTERNS,
|
|
506
611
|
RULE_SCOPES,
|
|
507
612
|
RULE_ENGINE_SUPPORT,
|
|
508
|
-
|
|
613
|
+
ADVISORY_RULE_IDS,
|
|
509
614
|
getAntipattern,
|
|
510
615
|
getRulesForCategory,
|
|
511
616
|
getRuleEngineSupport,
|
|
512
|
-
|
|
617
|
+
isAdvisoryRule,
|
|
513
618
|
filterByScopes,
|
|
514
619
|
};
|