impeccable 3.2.0 → 3.3.0

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.
@@ -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) rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++ });
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(rule.selector, root.children || []);
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: rule.selector,
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
- findings.push(finding(f.id, filePath, f.snippet));
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 ? byProvider : applyInlineIgnores(byProvider, html);
244
+ return options?.inlineIgnores === false ? findings : applyInlineIgnores(findings, html);
232
245
  }
233
246
 
234
247
  export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };
@@ -6,7 +6,7 @@ function getAP(id) {
6
6
 
7
7
  function finding(id, filePath, snippet, line = 0) {
8
8
  const ap = getAP(id);
9
- return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
9
+ return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
10
10
  }
11
11
 
12
12
  export { getAP, finding };