impeccable 3.4.0 → 3.6.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.
@@ -683,6 +683,10 @@ if (IS_BROWSER) {
683
683
 
684
684
  const reasons = collectVisualContrastReasons(el, style);
685
685
  if (reasons.length === 0) continue;
686
+ // Image-only mode filters here, inside the cap: gradient/opacity/filter
687
+ // candidates earlier in DOM order must not consume the budget and
688
+ // starve the url()-backed texts this mode exists to sample.
689
+ if (options.imageOnly && !reasons.includes('image background')) continue;
686
690
 
687
691
  const textColor = parseRgb(style.color);
688
692
  const fontSize = parseFloat(style.fontSize) || 16;
@@ -1175,6 +1179,7 @@ if (IS_BROWSER) {
1175
1179
  }
1176
1180
 
1177
1181
  async function analyzeVisualContrast(options = {}) {
1182
+ // imageOnly is enforced inside the collector, before the candidate cap.
1178
1183
  const candidates = collectVisualContrastCandidates(options);
1179
1184
  const results = [];
1180
1185
  const shouldScrollOffscreen = options.scrollOffscreen === true;
@@ -1260,9 +1265,16 @@ if (IS_BROWSER) {
1260
1265
 
1261
1266
  function addBrowserFindings(groupMap, el, findings) {
1262
1267
  if (!findings || findings.length === 0) return;
1268
+ // Element-scoped waivers: a data-impeccable-ignore ancestor suppresses
1269
+ // matching findings for its whole subtree. Applied at this choke point so
1270
+ // every per-element attribution (checks, layout, occlusion, rhythm)
1271
+ // honors it; page-level findings attributed to <body> pass through
1272
+ // untouched, since body has no ignoring ancestor.
1273
+ const kept = findings.filter(f => !scopedIgnoreActive(el, f.type));
1274
+ if (kept.length === 0) return;
1263
1275
  const existing = groupMap.get(el);
1264
- if (existing) existing.push(...findings);
1265
- else groupMap.set(el, [...findings]);
1276
+ if (existing) existing.push(...kept);
1277
+ else groupMap.set(el, [...kept]);
1266
1278
  }
1267
1279
 
1268
1280
  function browserFindingsFromMap(groupMap) {
@@ -1620,9 +1632,27 @@ if (IS_BROWSER) {
1620
1632
  for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
1621
1633
  node.remove();
1622
1634
  }
1623
- const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
1624
- if (htmlPatternFindings.length > 0) {
1625
- const mapped = htmlPatternFindings.map(f => {
1635
+ // Regex findings that name a live selector resolve against the real DOM:
1636
+ // pseudo-element/class segments are stripped (the host element is the
1637
+ // anchor), a selector that matches nothing on this page drops the finding
1638
+ // (the CSS ships here, but the pattern never renders — the live DOM is
1639
+ // ground truth in the browser), and a match under a data-impeccable-ignore
1640
+ // ancestor is waived. Selector-less findings stay page-level.
1641
+ const scopedHtmlFindings = checkHtmlPatterns(docClone.outerHTML).filter(f => {
1642
+ if (!f.selector) return true;
1643
+ const query = String(f.selector).replace(/::?[a-zA-Z-]+(\([^)]*\))?/g, '').trim().replace(/,\s*(?=,|$)/g, '');
1644
+ if (!query || /^[,\s]*$/.test(query)) return true;
1645
+ let matches;
1646
+ try {
1647
+ matches = document.querySelectorAll(query);
1648
+ } catch {
1649
+ return true;
1650
+ }
1651
+ if (matches.length === 0) return false;
1652
+ return [...matches].some(el => !scopedIgnoreActive(el, f.id));
1653
+ });
1654
+ if (scopedHtmlFindings.length > 0) {
1655
+ const mapped = scopedHtmlFindings.map(f => {
1626
1656
  const item = { type: f.id, detail: f.snippet };
1627
1657
  if (f.severity) {
1628
1658
  item.severity = f.severity;
@@ -1652,8 +1682,27 @@ if (IS_BROWSER) {
1652
1682
  };
1653
1683
  }
1654
1684
 
1685
+ // Visual contrast has three modes. Explicit true runs the full sampled
1686
+ // pass; explicit false disables it entirely (the deterministic-only mode
1687
+ // the test suites use). Unset — the default overlay run — samples ONLY
1688
+ // image-backed text: the one class the analytic walk deliberately skips,
1689
+ // because a url() layer's pixels are unknowable without looking. In-page
1690
+ // sampling draws the source image alone to a canvas (glyph ink never
1691
+ // pollutes it), and a cross-origin image without CORS reports unresolved
1692
+ // instead of guessing.
1693
+ function visualContrastMode(options = {}) {
1694
+ const explicit = typeof options.visualContrast === 'boolean'
1695
+ ? options.visualContrast
1696
+ : typeof window.__IMPECCABLE_CONFIG__?.visualContrast === 'boolean'
1697
+ ? window.__IMPECCABLE_CONFIG__.visualContrast
1698
+ : null;
1699
+ if (explicit === true) return 'full';
1700
+ if (explicit === false) return false;
1701
+ return 'image-only';
1702
+ }
1703
+
1655
1704
  function shouldRunVisualContrast(options = {}) {
1656
- return options.visualContrast === true || window.__IMPECCABLE_CONFIG__?.visualContrast === true;
1705
+ return visualContrastMode(options) !== false;
1657
1706
  }
1658
1707
 
1659
1708
  function visualContrastOptions(options = {}) {
@@ -1830,6 +1879,7 @@ if (IS_BROWSER) {
1830
1879
  return [];
1831
1880
  }
1832
1881
  const resolvedOptions = visualContrastOptions(options);
1882
+ if (visualContrastMode(options) === 'image-only') resolvedOptions.imageOnly = true;
1833
1883
  const analyses = await analyzeVisualContrast(resolvedOptions);
1834
1884
  if (runtime.generation && runtime.generation !== scanGeneration) return analyses;
1835
1885
  lastVisualContrastAnalyses = analyses;
@@ -14,6 +14,10 @@ const FALLBACK_DIRS = ['.agents/context', 'docs'];
14
14
  // boundaries; `.impeccable` is our own project marker.
15
15
  const PROJECT_ROOT_MARKERS = ['.git', 'package.json', '.impeccable'];
16
16
  const COLOR_CHANNEL_TOLERANCE = 6;
17
+ // Shadow blacks at different alphas are different tokens (0.28 vs 0.55 is the
18
+ // difference between a documented shadow and drift), so shadow matching cannot
19
+ // reuse the r/g/b-only channel tolerance.
20
+ const SHADOW_ALPHA_TOLERANCE = 0.02;
17
21
  const RADIUS_TOLERANCE_PX = 0.5;
18
22
  const FONT_SIZE_TOLERANCE_PX = 0.5;
19
23
  const FONT_SIZE_LITERAL_RE = /^-?[\d.]+(?:px|rem)$/;
@@ -142,10 +146,73 @@ function stripInlineYamlComment(s) {
142
146
  return s;
143
147
  }
144
148
 
149
+ // YAML double-quoted scalars process backslash escapes. Stripping the outer
150
+ // quotes without unescaping leaves them in place, so a nested font family like
151
+ // fontFamily: "\"IBM Plex Sans\", system-ui, sans-serif"
152
+ // reaches allowedFonts as '\"ibm plex sans' and never matches the same family
153
+ // declared in CSS. Scanner instead of a regex: the escape set is small and the
154
+ // backslash handling stays readable.
155
+ // The full YAML 1.2 double-quote escape set (spec section 5.7).
156
+ const YAML_SIMPLE_ESCAPES = {
157
+ '0': '\0',
158
+ a: '\x07',
159
+ b: '\b',
160
+ t: '\t',
161
+ n: '\n',
162
+ v: '\v',
163
+ f: '\f',
164
+ r: '\r',
165
+ e: '\x1b',
166
+ ' ': ' ',
167
+ '"': '"',
168
+ '/': '/',
169
+ '\\': '\\',
170
+ N: '\u0085',
171
+ _: '\u00a0',
172
+ L: '\u2028',
173
+ P: '\u2029',
174
+ };
175
+ const YAML_HEX_ESCAPE_LENGTHS = { x: 2, u: 4, U: 8 };
176
+
177
+ function unescapeYamlDoubleQuoted(body) {
178
+ let out = '';
179
+ for (let i = 0; i < body.length; i++) {
180
+ const ch = body[i];
181
+ if (ch !== '\\' || i === body.length - 1) {
182
+ out += ch;
183
+ continue;
184
+ }
185
+ const next = body[i + 1];
186
+ if (Object.prototype.hasOwnProperty.call(YAML_SIMPLE_ESCAPES, next)) {
187
+ out += YAML_SIMPLE_ESCAPES[next];
188
+ i++;
189
+ continue;
190
+ }
191
+ // \xNN, \uNNNN, \UNNNNNNNN. Malformed or out-of-range sequences stay
192
+ // literal rather than corrupting the rest of the scalar.
193
+ const hexLen = YAML_HEX_ESCAPE_LENGTHS[next];
194
+ if (hexLen) {
195
+ const hex = body.slice(i + 2, i + 2 + hexLen);
196
+ const codePoint = hex.length === hexLen && /^[0-9a-fA-F]+$/.test(hex) ? parseInt(hex, 16) : -1;
197
+ if (codePoint >= 0 && codePoint <= 0x10ffff) {
198
+ out += String.fromCodePoint(codePoint);
199
+ i += 1 + hexLen;
200
+ continue;
201
+ }
202
+ }
203
+ out += ch;
204
+ }
205
+ return out;
206
+ }
207
+
145
208
  function parseScalar(raw) {
146
209
  const s = raw.trim();
147
- if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
148
- return s.slice(1, -1);
210
+ if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
211
+ return unescapeYamlDoubleQuoted(s.slice(1, -1));
212
+ }
213
+ // Single-quoted YAML escapes only the quote itself, by doubling it.
214
+ if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) {
215
+ return s.slice(1, -1).split("''").join("'");
149
216
  }
150
217
  if (s === 'true') return true;
151
218
  if (s === 'false') return false;
@@ -411,6 +478,25 @@ function addSidecarRadii(out, sidecar) {
411
478
  }
412
479
  }
413
480
 
481
+ // Sidecar `extensions.shadows` entries ({ name, value, purpose }) carry the
482
+ // documented shadow vocabulary that Stitch's frontmatter schema can't hold.
483
+ // Their colors go into a separate allowlist — NOT allowedColorKeys — because a
484
+ // shadow black is only documented *as a shadow*: feeding it into the general
485
+ // color allowlist would legalize #000 as a page ground (alpha is dropped from
486
+ // colorKey), which is the hole issue #547 warns against.
487
+ function addSidecarShadows(out, sidecar) {
488
+ const shadows = sidecar?.extensions?.shadows;
489
+ if (!Array.isArray(shadows)) return;
490
+
491
+ for (const entry of shadows) {
492
+ if (typeof entry?.value !== 'string') continue;
493
+ for (const match of entry.value.matchAll(CSS_COLOR_RE)) {
494
+ const parsed = parseDesignColor(match[0]);
495
+ if (parsed) out.allowedShadowColors.push({ color: parsed });
496
+ }
497
+ }
498
+ }
499
+
414
500
  function normalizeDesignSystem(input = {}) {
415
501
  const frontmatter = input.frontmatter || {};
416
502
  const sidecar = input.sidecar || null;
@@ -423,6 +509,7 @@ function normalizeDesignSystem(input = {}) {
423
509
  allowedColorKeys: new Map(),
424
510
  allowedRadii: [],
425
511
  allowedFontSizes: [],
512
+ allowedShadowColors: [],
426
513
  hasPillRadius: false,
427
514
  };
428
515
 
@@ -432,6 +519,7 @@ function normalizeDesignSystem(input = {}) {
432
519
  addSidecarColors(out, sidecar);
433
520
  addRoundedScale(out, frontmatter.rounded);
434
521
  addSidecarRadii(out, sidecar);
522
+ addSidecarShadows(out, sidecar);
435
523
 
436
524
  out.hasFonts = out.allowedFonts.size > 0;
437
525
  out.hasColors = out.allowedColorKeys.size > 0;
@@ -551,6 +639,20 @@ function isAllowedColorRaw(raw, designSystem) {
551
639
  return false;
552
640
  }
553
641
 
642
+ // A color is a documented shadow color only when both the r/g/b channels AND
643
+ // the alpha match a sidecar shadow token's color. Alpha has to be compared
644
+ // here because colorKey()/colorsClose() drop it, and a match on r/g/b alone
645
+ // would let every black at every alpha through.
646
+ function isAllowedShadowColorRaw(raw, designSystem) {
647
+ if (!designSystem?.allowedShadowColors?.length) return false;
648
+ const parsed = parseDesignColor(String(raw || '').trim().toLowerCase());
649
+ if (!parsed) return false;
650
+ return designSystem.allowedShadowColors.some(entry =>
651
+ colorsClose(parsed, entry.color) &&
652
+ Math.abs((parsed.a ?? 1) - (entry.color.a ?? 1)) <= SHADOW_ALPHA_TOLERANCE,
653
+ );
654
+ }
655
+
554
656
  function isAllowedRadiusRaw(raw, designSystem) {
555
657
  if (!designSystem?.hasRadii) return true;
556
658
  const text = String(raw || '').trim().toLowerCase();
@@ -628,6 +730,40 @@ function isProbablyColorLiteral(line, match) {
628
730
  return styleContext || cssFunctionContext || jsColorKeyContext;
629
731
  }
630
732
 
733
+ // One complete `${...}` template interpolation. Its content may carry paired
734
+ // quoted strings (function arguments, ternary branches) and one level of
735
+ // braces (an object-literal argument, itself allowing paired quotes). Deeper
736
+ // nesting would need a parser, so the regex deliberately fails safe there:
737
+ // the context check misses and the finding fires — a false positive a waiver
738
+ // can silence, never a leak.
739
+ const QUOTED_STRING_SRC = `"[^"]*"|'[^']*'`;
740
+ const INTERPOLATION_SRC =
741
+ `\\$\\{(?:${QUOTED_STRING_SRC}|\\{(?:${QUOTED_STRING_SRC}|[^{}"'\`])*\\}|[^{}"'\`])*\\}`;
742
+ // The two shadow-context tails. Unlike jsColorKeyContext, the JS tail admits
743
+ // commas: a multi-layer shadow string is comma-separated, and a later
744
+ // property on the same line is still blocked because it sits past the
745
+ // string's closing quote. Both tails admit complete interpolations; a bare
746
+ // `}`, quote, or `;` still ends the context.
747
+ const SHADOW_CSS_CONTEXT_RE = new RegExp(
748
+ `(?:^|[{\\s;"'\`(,])(?:box-shadow|text-shadow)\\s*:\\s*(?:${INTERPOLATION_SRC}|[^;{}"'\`])*$`, 'i',
749
+ );
750
+ const SHADOW_JS_CONTEXT_RE = new RegExp(
751
+ `(?:^|[,{]\\s*)(?:boxShadow|textShadow)\\s*[:=]\\s*["'\`]?(?:${INTERPOLATION_SRC}|[^"'\`}])*$`, 'i',
752
+ );
753
+
754
+ // True when the color literal sits inside a box-shadow / text-shadow value —
755
+ // the only contexts where a documented shadow color is legal. Anchored to the
756
+ // end of `before` (no ; } { or quote in between) so a shadow property earlier
757
+ // on the line can't leak the allowance into a later declaration. Kept separate
758
+ // from isProbablyColorLiteral(), which stays a boolean for its existing call
759
+ // sites and deliberately discards which property matched.
760
+ function isShadowPropertyContext(line, match) {
761
+ const index = match.index ?? -1;
762
+ if (index < 0) return false;
763
+ const before = line.slice(0, index);
764
+ return SHADOW_CSS_CONTEXT_RE.test(before) || SHADOW_JS_CONTEXT_RE.test(before);
765
+ }
766
+
631
767
  function isInsideCssAttributeSelector(line, index) {
632
768
  if (index < 0) return false;
633
769
  const before = line.slice(0, index);
@@ -761,6 +897,7 @@ function checkSourceDesignSystem(content, filePath, options = {}) {
761
897
  if (!isProbablyColorLiteral(line, match)) continue;
762
898
  const raw = cssColorLabel(match[0]);
763
899
  if (isAllowedColorRaw(raw, designSystem)) continue;
900
+ if (isShadowPropertyContext(line, match) && isAllowedShadowColorRaw(raw, designSystem)) continue;
764
901
  findings.push(makeDesignFinding(
765
902
  'design-system-color',
766
903
  filePath,
@@ -975,6 +1112,7 @@ export {
975
1112
  loadDesignSystemForCwd,
976
1113
  isAllowedFont,
977
1114
  isAllowedColorRaw,
1115
+ isAllowedShadowColorRaw,
978
1116
  isAllowedRadiusRaw,
979
1117
  isAllowedFontSizeRaw,
980
1118
  checkSourceDesignSystem,