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,6 +2,7 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { loadDesignSystemForCwd } from '../design-system.mjs';
5
+ import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
5
6
  import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
6
7
  import { detectHtml } from '../engines/static-html/detect-html.mjs';
7
8
  import { detectText } from '../engines/regex/detect-text.mjs';
@@ -91,8 +92,10 @@ Scan files or URLs for UI anti-patterns and design quality issues.
91
92
  Options:
92
93
  --json Output results as JSON
93
94
  --quiet In text mode, only print the final findings count
94
- --gpt Also report GPT-specific provider tells (off by default)
95
- --gemini Also report Gemini-specific provider tells (off by default)
95
+ --scope <name> Only report rules in the given design domain
96
+ (type, layout). Comma-separated.
97
+ --viewport <WxH> Browser viewport for URL scans (default 1280x800),
98
+ e.g. --viewport 390x844 for a mobile-width pass
96
99
  --no-config Do not apply project config, detector ignores, inline
97
100
  ignore comments, or DESIGN.md
98
101
  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
@@ -115,7 +118,8 @@ Inline ignores:
115
118
  Detection modes:
116
119
  HTML files Static HTML/CSS analysis (default, catches linked CSS)
117
120
  Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
118
- URLs Puppeteer full browser rendering (auto-detected)
121
+ URLs Puppeteer full browser rendering (auto-detected;
122
+ http(s):// and file:// URLs)
119
123
 
120
124
  Examples:
121
125
  impeccable detect src/
@@ -144,21 +148,65 @@ async function detectCli() {
144
148
  'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
145
149
  );
146
150
  }
151
+ if (args.includes('--gpt') || args.includes('--gemini')) {
152
+ process.stderr.write(
153
+ 'Note: --gpt and --gemini are deprecated and ignored. Generated-UI tells now run by default.\n',
154
+ );
155
+ }
147
156
  const configEnabled = !args.includes('--no-config');
148
157
  const detectionConfig = configEnabled
149
158
  ? readDetectionConfig(process.cwd())
150
159
  : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
151
- const providers = [];
152
- if (args.includes('--gpt')) providers.push('gpt');
153
- if (args.includes('--gemini')) providers.push('gemini');
160
+ const scopes = [];
161
+ for (let i = 0; i < args.length; i++) {
162
+ if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
163
+ const inline = args[i].startsWith('--scope=');
164
+ const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
165
+ const parsed = (value && !value.startsWith('--'))
166
+ ? value.split(',').map(s => s.trim()).filter(Boolean)
167
+ : [];
168
+ // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
169
+ // fail loudly so a mistyped pre-scan never runs the wrong rule set.
170
+ if (parsed.length === 0) {
171
+ process.stderr.write(
172
+ `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
173
+ );
174
+ process.exit(1);
175
+ }
176
+ scopes.push(...parsed);
177
+ args.splice(i, inline ? 1 : 2);
178
+ i -= 1;
179
+ }
180
+ let viewport = null;
181
+ for (let i = 0; i < args.length; i++) {
182
+ if (args[i] !== '--viewport' && !args[i].startsWith('--viewport=')) continue;
183
+ const inline = args[i].startsWith('--viewport=');
184
+ const value = inline ? args[i].slice('--viewport='.length) : args[i + 1];
185
+ const match = /^(\d{2,5})x(\d{2,5})$/i.exec(value || '');
186
+ if (!match) {
187
+ process.stderr.write('Error: --viewport requires a WxH value, e.g. --viewport 390x844\n');
188
+ process.exit(1);
189
+ }
190
+ viewport = { width: Number(match[1]), height: Number(match[2]) };
191
+ args.splice(i, inline ? 1 : 2);
192
+ i -= 1;
193
+ }
194
+ const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
195
+ if (unknownScopes.length > 0) {
196
+ process.stderr.write(
197
+ `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
198
+ );
199
+ process.exit(1);
200
+ }
154
201
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
155
202
  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
156
203
  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
157
204
  // apply by default. `--no-config` (raw scan) and the dedicated
158
205
  // `--no-inline-ignores` both turn them off.
159
206
  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
160
- const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
207
+ const scanOptions = { inlineIgnores: inlineIgnoresEnabled };
161
208
  if (designSystem) scanOptions.designSystem = designSystem;
209
+ if (viewport) scanOptions.viewport = viewport;
162
210
  const targets = args.filter(a => !a.startsWith('--'));
163
211
 
164
212
  if (helpMode) { printUsage(); process.exit(0); }
@@ -169,12 +217,17 @@ async function detectCli() {
169
217
  allFindings = await handleStdin(scanOptions);
170
218
  } else {
171
219
  const paths = targets.length > 0 ? targets : [process.cwd()];
172
- const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
220
+ // file:// URLs get the same Puppeteer-rendered pass as http(s) — the
221
+ // real cascade, real computed styles, real layout. Callers that want a
222
+ // browser-grade scan of a local artifact can pass file:///abs/path.html
223
+ // instead of the bare path (which stays on the static engine).
224
+ const urlRe = /^(?:https?|file):\/\//i;
225
+ const urlTargetCount = paths.filter(target => urlRe.test(target)).length;
173
226
  const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;
174
227
 
175
228
  try {
176
229
  for (const target of paths) {
177
- if (/^https?:\/\//i.test(target)) {
230
+ if (urlRe.test(target)) {
178
231
  try {
179
232
  const scanner = browserDetector
180
233
  ? (url) => browserDetector.detectUrl(url, scanOptions)
@@ -276,6 +329,7 @@ async function detectCli() {
276
329
  }
277
330
 
278
331
  allFindings = filterDetectionFindings(allFindings, detectionConfig);
332
+ allFindings = filterByScopes(allFindings, scopes);
279
333
 
280
334
  if (allFindings.length > 0) {
281
335
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
@@ -9,6 +9,8 @@ const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
9
9
  const FALLBACK_DIRS = ['.agents/context', 'docs'];
10
10
  const COLOR_CHANNEL_TOLERANCE = 6;
11
11
  const RADIUS_TOLERANCE_PX = 0.5;
12
+ const FONT_SIZE_TOLERANCE_PX = 0.5;
13
+ const FONT_SIZE_LITERAL_RE = /^-?[\d.]+(?:px|rem)$/;
12
14
 
13
15
  const CSS_COLOR_RE = /#[0-9a-f]{3,8}\b|rgba?\([^)]+\)|oklch\([^)]+\)|hsla?\([^)]+\)/gi;
14
16
  const FONT_DECL_RE = /font-family\s*:\s*([^;}\n]+)/gi;
@@ -16,6 +18,9 @@ const FONT_JS_RE = /fontFamily\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
16
18
  const GOOGLE_FONT_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
17
19
  const BORDER_RADIUS_RE = /border-radius\s*:\s*([^;}\n]+)/gi;
18
20
  const BORDER_RADIUS_JS_RE = /borderRadius\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
21
+ const FONT_SIZE_DECL_RE = /font-size\s*:\s*([^;}\n]+)/gi;
22
+ const FONT_SIZE_JS_RE = /fontSize\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
23
+ const TAILWIND_FONT_SIZE_RE = /\btext-\[(-?[\d.]+(?:px|rem))\]/g;
19
24
  const STATIC_DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
20
25
 
21
26
  function firstExisting(dir, names) {
@@ -283,6 +288,77 @@ function addTypographyFonts(out, typography) {
283
288
  }
284
289
  }
285
290
 
291
+ function addFontSizeStep(out, raw, { fluid = false } = {}) {
292
+ const text = String(raw ?? '').trim().toLowerCase();
293
+ if (!FONT_SIZE_LITERAL_RE.test(text)) return;
294
+ const px = resolveLengthPx(text, 16);
295
+ if (px == null || !Number.isFinite(px) || px <= 0) return;
296
+ out.allowedFontSizes.push({ value: text, px, fluid });
297
+ }
298
+
299
+ // Split a fluid value into its three terms, or null when it is not a
300
+ // well-formed clamp(). Used both to read DESIGN.md's fluid roles and to
301
+ // validate fluid values in source, so the two stay symmetric.
302
+ function parseClampArgs(raw) {
303
+ const match = /^clamp\(\s*([\s\S]+)\s*\)$/i.exec(String(raw ?? '').trim());
304
+ if (!match) return null;
305
+ const args = splitTopLevelArgs(match[1]);
306
+ return args.length === 3 ? args : null;
307
+ }
308
+
309
+ // A fluid role declares its two fixed endpoints and interpolates between them
310
+ // with a viewport unit. Both endpoints are documented sizes, so they belong in
311
+ // the allowlist; the middle term is viewport-relative and never a fixed step.
312
+ // Endpoints are marked `fluid` because they do not *enumerate* a ramp: see
313
+ // `hasFontSizes` below for why that distinction has to survive.
314
+ function addClampEndpoints(out, raw) {
315
+ const args = parseClampArgs(raw);
316
+ if (!args) return false;
317
+ addFontSizeStep(out, args[0], { fluid: true });
318
+ addFontSizeStep(out, args[2], { fluid: true });
319
+ return true;
320
+ }
321
+
322
+ function splitTopLevelArgs(s) {
323
+ const args = [];
324
+ let depth = 0;
325
+ let current = '';
326
+ for (const ch of String(s)) {
327
+ if (ch === '(') depth++;
328
+ else if (ch === ')') depth--;
329
+ if (ch === ',' && depth === 0) {
330
+ args.push(current.trim());
331
+ current = '';
332
+ continue;
333
+ }
334
+ current += ch;
335
+ }
336
+ if (current.trim()) args.push(current.trim());
337
+ return args;
338
+ }
339
+
340
+ function addTypographySizes(out, typography) {
341
+ if (!typography || typeof typography !== 'object') return;
342
+
343
+ // `scale` is the enumerated ramp: a name -> size map, since the frontmatter
344
+ // parser has no list support. It sits alongside the named roles.
345
+ const scale = typography.scale;
346
+ if (scale && typeof scale === 'object') {
347
+ for (const value of Object.values(scale)) {
348
+ if (typeof value !== 'string' && typeof value !== 'number') continue;
349
+ addFontSizeStep(out, value);
350
+ }
351
+ }
352
+
353
+ for (const [name, role] of Object.entries(typography)) {
354
+ if (name === 'scale') continue;
355
+ if (!role || typeof role !== 'object') continue;
356
+ const raw = String(role.fontSize ?? '').trim().toLowerCase();
357
+ if (addClampEndpoints(out, raw)) continue;
358
+ addFontSizeStep(out, raw);
359
+ }
360
+ }
361
+
286
362
  function addRoundedScale(out, rounded) {
287
363
  if (!rounded || typeof rounded !== 'object') return;
288
364
  for (const [rawName, value] of Object.entries(rounded)) {
@@ -340,10 +416,12 @@ function normalizeDesignSystem(input = {}) {
340
416
  allowedFonts: new Set(),
341
417
  allowedColorKeys: new Map(),
342
418
  allowedRadii: [],
419
+ allowedFontSizes: [],
343
420
  hasPillRadius: false,
344
421
  };
345
422
 
346
423
  addTypographyFonts(out, frontmatter.typography);
424
+ addTypographySizes(out, frontmatter.typography);
347
425
  addColorObject(out, frontmatter.colors);
348
426
  addSidecarColors(out, sidecar);
349
427
  addRoundedScale(out, frontmatter.rounded);
@@ -352,6 +430,10 @@ function normalizeDesignSystem(input = {}) {
352
430
  out.hasFonts = out.allowedFonts.size > 0;
353
431
  out.hasColors = out.allowedColorKeys.size > 0;
354
432
  out.hasRadii = out.allowedRadii.length > 0;
433
+ // Gate on *enumerated* steps only. A fully fluid system declares clamp
434
+ // endpoints but no discrete ramp, so treating those endpoints as the whole
435
+ // allowlist would flag every intermediate size. Abstain instead.
436
+ out.hasFontSizes = out.allowedFontSizes.some(entry => !entry.fluid);
355
437
  return out;
356
438
  }
357
439
 
@@ -418,6 +500,43 @@ function isAllowedRadiusRaw(raw, designSystem) {
418
500
  return designSystem.allowedRadii.some(entry => Math.abs(entry.px - px) <= RADIUS_TOLERANCE_PX);
419
501
  }
420
502
 
503
+ // One term of a font-size value. `unjudgeable` covers var(), calc(), percentages
504
+ // and units the ramp cannot resolve (em is parent-relative, not root-relative);
505
+ // those abstain rather than guess.
506
+ function fontSizeStepStatus(raw, designSystem) {
507
+ const text = String(raw || '').trim().toLowerCase();
508
+ if (!FONT_SIZE_LITERAL_RE.test(text)) return 'unjudgeable';
509
+ const px = resolveLengthPx(text, 16);
510
+ if (px == null || !Number.isFinite(px) || px <= 0) return 'unjudgeable';
511
+ return designSystem.allowedFontSizes.some(
512
+ entry => Math.abs(entry.px - px) <= FONT_SIZE_TOLERANCE_PX,
513
+ ) ? 'on-ramp' : 'off-ramp';
514
+ }
515
+
516
+ // The off-ramp endpoints of a fluid value, or null when `raw` is not a fluid
517
+ // value at all. Only the min and max are judged: the viewport term interpolates
518
+ // between them and is never a fixed step.
519
+ //
520
+ // Reading clamp endpoints as documented steps without also checking them in
521
+ // usage would let `clamp(99rem, 1vw, 200rem)` through, which is how a fluid
522
+ // declaration stayed invisible until someone measured computed styles.
523
+ export function offRampClampEndpoints(raw, designSystem) {
524
+ if (!designSystem?.hasFontSizes) return null;
525
+ const args = parseClampArgs(String(raw || '').trim().replace(/\s*!important\s*$/i, ''));
526
+ if (!args) return null;
527
+ return [args[0], args[2]].filter(
528
+ endpoint => fontSizeStepStatus(endpoint, designSystem) === 'off-ramp',
529
+ );
530
+ }
531
+
532
+ function isAllowedFontSizeRaw(raw, designSystem) {
533
+ if (!designSystem?.hasFontSizes) return true;
534
+ const text = String(raw || '').trim().toLowerCase().replace(/\s*!important\s*$/, '');
535
+ const offRampEndpoints = offRampClampEndpoints(text, designSystem);
536
+ if (offRampEndpoints) return offRampEndpoints.length === 0;
537
+ return fontSizeStepStatus(text, designSystem) !== 'off-ramp';
538
+ }
539
+
421
540
  function lineLooksCommented(line) {
422
541
  const trimmed = String(line || '').trim();
423
542
  return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('<!--');
@@ -509,6 +628,37 @@ function checkRadiusValue(value, filePath, line, designSystem, context) {
509
628
  return findings;
510
629
  }
511
630
 
631
+ function checkFontSizeValue(value, filePath, line, designSystem, context) {
632
+ const token = String(value || '').trim();
633
+ if (isAllowedFontSizeRaw(token, designSystem)) return [];
634
+
635
+ // Name the offending endpoint on a fluid value; the whole clamp() string is
636
+ // not actionable on its own, and it makes a poor ignore-value.
637
+ const offRampEndpoints = offRampClampEndpoints(token, designSystem) || [];
638
+ if (offRampEndpoints.length > 0) {
639
+ const plural = offRampEndpoints.length > 1 ? 's' : '';
640
+ return [makeDesignFinding(
641
+ 'design-system-font-size',
642
+ filePath,
643
+ `${context}: ${token} has fluid endpoint${plural} ${offRampEndpoints.join(' and ')} off the DESIGN.md type ramp`,
644
+ line,
645
+ { ignoreValue: offRampEndpoints[0] },
646
+ )];
647
+ }
648
+
649
+ // The snippet shows the declaration as authored, but the ignoreValue has to
650
+ // be what a `hooks ignore-value` waiver can match, so the priority marker is
651
+ // stripped. Otherwise the same size needs two different waivers depending on
652
+ // whether it carries !important. font-family already behaves this way.
653
+ return [makeDesignFinding(
654
+ 'design-system-font-size',
655
+ filePath,
656
+ `${context}: ${token} is off the DESIGN.md type ramp`,
657
+ line,
658
+ { ignoreValue: token.replace(/\s*!important\s*$/i, '').trim() },
659
+ )];
660
+ }
661
+
512
662
  function checkSourceDesignSystem(content, filePath, options = {}) {
513
663
  const designSystem = options.designSystem;
514
664
  if (!designSystem?.present) return [];
@@ -567,6 +717,18 @@ function checkSourceDesignSystem(content, filePath, options = {}) {
567
717
  findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'borderRadius'));
568
718
  }
569
719
  }
720
+
721
+ if (designSystem.hasFontSizes) {
722
+ for (const match of line.matchAll(FONT_SIZE_DECL_RE)) {
723
+ findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'font-size'));
724
+ }
725
+ for (const match of line.matchAll(FONT_SIZE_JS_RE)) {
726
+ findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'fontSize'));
727
+ }
728
+ for (const match of line.matchAll(TAILWIND_FONT_SIZE_RE)) {
729
+ findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'text-[…] class'));
730
+ }
731
+ }
570
732
  }
571
733
 
572
734
  return dedupeDesignFindings(findings);
@@ -581,6 +743,8 @@ function sampleText(el) {
581
743
  return text ? ` "${text.slice(0, 40)}"` : '';
582
744
  }
583
745
 
746
+ // Font-size design-system checks are source-scan-only (see checkSourceDesignSystem).
747
+ // Computed font-size cascades and clamp() ramps resolve to off-ramp px in the browser.
584
748
  function collectStaticDesignSystemFindings(document, window, filePath, designSystem) {
585
749
  if (!designSystem?.present) return [];
586
750
  const findings = [];
@@ -698,6 +862,12 @@ function canonicalDesignFindingKey(item) {
698
862
  const label = String(value || '').trim().toLowerCase();
699
863
  return label ? `${item.antipattern}:radius:${label}` : null;
700
864
  }
865
+ if (item.antipattern === 'design-system-font-size') {
866
+ const px = resolveLengthPx(String(value || '').trim(), 16);
867
+ if (px != null && Number.isFinite(px)) return `${item.antipattern}:font-size:${Math.round(px * 100) / 100}`;
868
+ const label = String(value || '').trim().toLowerCase();
869
+ return label ? `${item.antipattern}:font-size:${label}` : null;
870
+ }
701
871
  return null;
702
872
  }
703
873
 
@@ -744,6 +914,7 @@ export {
744
914
  isAllowedFont,
745
915
  isAllowedColorRaw,
746
916
  isAllowedRadiusRaw,
917
+ isAllowedFontSizeRaw,
747
918
  checkSourceDesignSystem,
748
919
  collectStaticDesignSystemFindings,
749
920
  mergeDesignSystemFindings,