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.
- package/README.md +3 -3
- package/README.npm.md +3 -3
- package/README.repo.md +26 -3
- package/cli/bin/cli.js +6 -0
- package/cli/bin/commands/skills.mjs +234 -29
- package/cli/engine/browser/injected/index.mjs +56 -6
- package/cli/engine/design-system.mjs +140 -2
- package/cli/engine/detect-antipatterns-browser.js +1174 -694
- package/cli/engine/detect-antipatterns.mjs +1 -0
- package/cli/engine/engines/browser/detect-url.mjs +35 -3
- package/cli/engine/engines/regex/detect-text.mjs +431 -45
- package/cli/engine/engines/static-html/css-cascade.mjs +10 -1
- package/cli/engine/engines/static-html/detect-html.mjs +47 -6
- package/cli/engine/node/file-system.mjs +23 -22
- package/cli/engine/registry/antipatterns.mjs +0 -10
- package/cli/engine/rules/checks.mjs +384 -384
- package/cli/engine/shared/color.mjs +466 -2
- package/cli/lib/download-providers.js +7 -0
- package/cli/lib/impeccable-config.mjs +44 -59
- package/package.json +5 -3
|
@@ -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(...
|
|
1265
|
-
else groupMap.set(el, [...
|
|
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
|
-
|
|
1624
|
-
|
|
1625
|
-
|
|
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
|
|
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 (
|
|
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,
|