impeccable 3.5.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.
@@ -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,