impeccable 3.3.0 → 3.4.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.
@@ -1,8 +1,8 @@
1
- import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
1
+ import { GENERIC_FONTS, OVERUSED_FONTS, EM_DASH_FLOOR, EM_DASH_CHARS_PER_DASH } from '../../shared/constants.mjs';
2
2
  import { isNeutralColor } from '../../shared/color.mjs';
3
3
  import { extractGoogleFontFamilies } from '../../shared/fonts.mjs';
4
4
  import { checkSourceDesignSystem } from '../../design-system.mjs';
5
- import { scanCssTextForGlow, scanCssTextForGridBackground, scanCssTextForMarquee, scanCssTextForRadialHalo } from '../../rules/checks.mjs';
5
+ import { scanCssTextForGlow, scanCssTextForGridBackground, scanCssTextForMarquee, scanCssTextForPseudoStripe, scanCssTextForRadialHalo } from '../../rules/checks.mjs';
6
6
  import { isFullPage } from '../../shared/page.mjs';
7
7
  import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
8
8
  import { finding } from '../../findings.mjs';
@@ -16,6 +16,7 @@ const hasRounded = (line) => /\brounded(?:-\w+)?\b/.test(line);
16
16
  const hasBorderRadius = (line) => /border-radius/i.test(line);
17
17
  const isSafeElement = (line) => /<(?:blockquote|nav[\s>]|pre[\s>]|code[\s>]|a\s|input[\s>]|span[\s>])/i.test(line);
18
18
 
19
+
19
20
  /** Strip HTML to plain text — drops script/style/comments/tags so
20
21
  * content-text analyzers don't false-positive on code or CSS. */
21
22
  function stripHtmlToText(html) {
@@ -306,15 +307,34 @@ const REGEX_ANALYZERS = [
306
307
  const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
307
308
  return [finding('monotonous-spacing', filePath, `~${dominant}px used ${maxCount}/${rounded.length} times (${Math.round(pct * 100)}%)`)];
308
309
  },
309
- // Em-dash overuse: 5+ em-dashes or "--" in body text content
310
- // (occasional em-dash use in prose is fine; the pattern fires only
311
- // when count crosses into AI-cadence territory).
310
+ // Em-dash overuse (ADVISORY): the AI cadence tell is em-dash *saturation*,
311
+ // not the occasional dash. Humans use em-dashes legitimately, so this rule is
312
+ // advisory (surfaced separately, never a failure, hook-skipped by default) and
313
+ // its threshold is deliberately conservative. Two gates must both hold:
314
+ // 1. Absolute floor of EM_DASH_FLOOR (8) dashes — a page with a handful
315
+ // never fires, no matter how short.
316
+ // 2. Density: at least one dash per EM_DASH_CHARS_PER_DASH (500) characters
317
+ // of body text, so a long article that uses eight across several thousand
318
+ // words is left alone while a short, dash-per-clause landing page is not.
319
+ // Raised from the old flat 5-dash floor, which fired on ordinary long prose.
320
+ //
321
+ // stripHtmlToText drops tags but leaves character-entity escapes intact, so
322
+ // a model that writes `&mdash;`, `&#8212;`, or `&#x2014;` renders an em-dash
323
+ // the counter never saw. Decode the em-dash entities (named, zero-padded
324
+ // decimal, upper/lower hex) to the literal glyph first. En-dash entities are
325
+ // deliberately left alone: the rule counts em-dashes, and the literal `–`
326
+ // was never counted either.
312
327
  (content, filePath) => {
313
- const text = stripHtmlToText(content);
328
+ const text = stripHtmlToText(content)
329
+ .replace(/&mdash;|&#0*8212;|&#x0*2014;/gi, '—');
314
330
  let count = 0;
315
331
  const re = /[—]|--(?=\S)/g;
316
332
  while (re.exec(text) !== null) count++;
317
- if (count < 5) return [];
333
+ if (count < EM_DASH_FLOOR) return [];
334
+ // Saturation gate: dashes must be dense in the prose, not sprinkled through
335
+ // a long document. textLength <= count * chars-per-dash means the density is
336
+ // at or above the threshold.
337
+ if (text.length > count * EM_DASH_CHARS_PER_DASH) return [];
318
338
  return [finding('em-dash-overuse', filePath, `${count} em-dashes in body text`)];
319
339
  },
320
340
  // Marketing buzzwords: SaaS phrase list
@@ -633,7 +653,21 @@ function detectText(content, filePath, options = {}) {
633
653
  profile,
634
654
  phase: 'source',
635
655
  }));
636
- if (cssLike.has(ext)) findings.push(...scanInsetStripeCss(content, filePath));
656
+ // Pseudo-element stripes (::before/::after absolute bars) carry the same
657
+ // side-tab silhouette without any border token, so the line matchers can't
658
+ // see them (issue #394). The shared scanner already runs on full HTML pages
659
+ // via checkHtmlPatterns; give standalone stylesheets, component style
660
+ // blocks, and CSS-in-JS templates the same coverage. Each hit carries the
661
+ // rule's source offset, so the finding gets a real line and line-scoped
662
+ // inline ignores keep working.
663
+ const pseudoStripeFindings = (text, lineOffset) =>
664
+ scanCssTextForPseudoStripe(text).map(hit =>
665
+ finding(hit.id, filePath, hit.snippet, lineOffset + text.slice(0, hit.index).split('\n').length));
666
+
667
+ if (cssLike.has(ext)) {
668
+ findings.push(...scanInsetStripeCss(content, filePath));
669
+ findings.push(...pseudoStripeFindings(content, 0));
670
+ }
637
671
 
638
672
  // Block-level CSS checks that need multiple declarations must run over the
639
673
  // complete source, not line-by-line. This covers standalone stylesheets,
@@ -670,6 +704,7 @@ function detectText(content, filePath, options = {}) {
670
704
  // reported every selector one line low. runRegexMatchers keeps startLine - 1
671
705
  // because it indexes its split lines from zero.
672
706
  findings.push(...scanInsetStripeCss(block.content, filePath, block.startLine - 2));
707
+ findings.push(...pseudoStripeFindings(block.content, block.startLine - 2));
673
708
  }
674
709
 
675
710
  // Extract and scan CSS-in-JS template literals
@@ -688,6 +723,7 @@ function detectText(content, filePath, options = {}) {
688
723
  phase: 'css-in-js',
689
724
  }));
690
725
  findings.push(...scanInsetStripeCss(block.content, filePath, block.startLine - 1));
726
+ findings.push(...pseudoStripeFindings(block.content, block.startLine - 1));
691
727
  }
692
728
 
693
729
  if (options?.designSystem) {
@@ -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 { collectCssCustomProps, cssLengthToPx, parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
5
+ import { CSS_NAMED_COLORS, collectCssCustomProps, cssLengthToPx, parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
6
6
 
7
7
  // ---------------------------------------------------------------------------
8
8
  // jsdom CSS-variable border override map
@@ -223,7 +223,7 @@ function unwrapCssAtLayer(source) {
223
223
  // ---------------------------------------------------------------------------
224
224
 
225
225
  const STATIC_INHERITED_PROPS = new Set([
226
- 'color', 'fontFamily', 'fontSize', 'fontStyle', 'fontWeight',
226
+ 'color', 'fontFamily', 'fontSize', 'fontStyle', 'fontWeight', 'fontVariant',
227
227
  'lineHeight', 'letterSpacing', 'textTransform', 'textAlign', 'hyphens',
228
228
  'webkitHyphens',
229
229
  ]);
@@ -252,6 +252,7 @@ const STATIC_DEFAULT_STYLE = {
252
252
  fontFamily: '',
253
253
  fontSize: '16px',
254
254
  fontStyle: 'normal',
255
+ fontVariant: 'normal',
255
256
  fontWeight: '400',
256
257
  lineHeight: 'normal',
257
258
  letterSpacing: 'normal',
@@ -344,18 +345,29 @@ const STATIC_PROP_MAP = {
344
345
  'overflow-y': 'overflowY',
345
346
  };
346
347
 
348
+ // parseStaticColor tries parseAnyColor first, which already resolves every
349
+ // name in the shared CSS_NAMED_COLORS table. This fallback only carries the
350
+ // keywords parseAnyColor deliberately returns null for: the cascade needs
351
+ // `transparent` to read as an actual zero-alpha color.
347
352
  const STATIC_NAMED_COLORS = {
348
- black: { r: 0, g: 0, b: 0, a: 1 },
349
- white: { r: 255, g: 255, b: 255, a: 1 },
350
353
  transparent: { r: 0, g: 0, b: 0, a: 0 },
351
- gray: { r: 128, g: 128, b: 128, a: 1 },
352
- grey: { r: 128, g: 128, b: 128, a: 1 },
353
- silver: { r: 192, g: 192, b: 192, a: 1 },
354
- red: { r: 255, g: 0, b: 0, a: 1 },
355
- green: { r: 0, g: 128, b: 0, a: 1 },
356
- blue: { r: 0, g: 0, b: 255, a: 1 },
357
354
  };
358
355
 
356
+ // Named-color alternation for plucking a color token out of shorthand values
357
+ // (issue #359: a hardcoded 9-name list here silently dropped `purple`,
358
+ // `crimson`, `teal`, ... from border shorthands, so the side defaulted to
359
+ // neutral black and side-tab never fired on .html files). Derived from the
360
+ // same table parseAnyColor resolves against, so extraction and parsing can't
361
+ // drift apart. Longest-first so names containing other names as substrings
362
+ // (rebeccapurple) are matched whole.
363
+ const NAMED_COLOR_TOKENS = [...Object.keys(CSS_NAMED_COLORS), ...Object.keys(STATIC_NAMED_COLORS)]
364
+ .sort((a, b) => b.length - a.length)
365
+ .join('|');
366
+ const STATIC_COLOR_TOKEN_RE = new RegExp(
367
+ `(?:rgba?\\([^)]+\\)|oklch\\([^)]+\\)|oklab\\([^)]+\\)|lch\\([^)]+\\)|lab\\([^)]+\\)|hsla?\\([^)]+\\)|hwb\\([^)]+\\)|#[0-9a-f]{3,8}\\b|\\b(?:${NAMED_COLOR_TOKENS})\\b)`,
368
+ 'i'
369
+ );
370
+
359
371
  function splitCssList(value) {
360
372
  const parts = [];
361
373
  let depth = 0, quote = '', start = 0;
@@ -441,7 +453,7 @@ function extractStaticColor(value) {
441
453
  }
442
454
  return '';
443
455
  }
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);
456
+ const colorLike = raw.match(STATIC_COLOR_TOKEN_RE);
445
457
  if (!colorLike) return '';
446
458
  return colorLike[0];
447
459
  }
@@ -24,13 +24,14 @@ import {
24
24
  checkElementMotion,
25
25
  checkElementOversizedH1,
26
26
  checkElementQuality,
27
+ checkElementRadialSpotlight,
27
28
  checkCreamPalette,
28
29
  checkHtmlPatterns,
30
+ checkKickerAboveHeadingFromDoc,
29
31
  checkNumberedSectionLabelsFromDoc,
30
32
  checkPageLayout,
31
33
  checkPageQualityFromDoc,
32
34
  checkRepeatedContainerTextFromDoc,
33
- checkRepeatedSectionKickersFromDoc,
34
35
  resolveBackground,
35
36
  resolveBorderRadiusPx,
36
37
  } from '../../rules/checks.mjs';
@@ -105,6 +106,7 @@ const STATIC_ELEMENT_RULES = [
105
106
  { id: 'oversized-h1', selector: 'h1', run: (el, tag, style, window) => checkElementOversizedH1(el, style, tag, window) },
106
107
  { id: 'clipped-overflow-container', selector: '*', run: (el, tag, style, window) => checkElementClippedOverflow(el, style, tag, window) },
107
108
  { id: 'gpt-thin-border-wide-shadow', selector: '*', run: (el, tag, style) => checkElementGptBorderShadow(el, style) },
109
+ { id: 'radial-spotlight-glow', selector: '*', run: (el, tag, style, window) => checkElementRadialSpotlight(el, style, tag, window) },
108
110
  ];
109
111
 
110
112
  async function detectHtml(filePath, options = {}) {
@@ -200,7 +202,7 @@ async function detectHtml(filePath, options = {}) {
200
202
  for (const f of runPageCheck('typography-rules', () => checkStaticPageTypography(document, window))) {
201
203
  findings.push(finding(f.id, filePath, f.snippet));
202
204
  }
203
- for (const f of runPageCheck('repeated-section-kickers', () => checkRepeatedSectionKickersFromDoc(document, window))) {
205
+ for (const f of runPageCheck('kicker-above-heading', () => checkKickerAboveHeadingFromDoc(document, window))) {
204
206
  findings.push(finding(f.id, filePath, f.snippet));
205
207
  }
206
208
  for (const f of runPageCheck('numbered-section-labels', () => checkNumberedSectionLabelsFromDoc(document, window))) {
@@ -6,7 +6,13 @@ 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', category: ap.category || null, file: filePath, line, snippet };
9
+ const base = { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
10
+ // Advisory findings are detected but reported separately and never counted as
11
+ // failures. Carry the flag on the finding so every consumer (CLI, JSON, hook)
12
+ // can partition without a registry lookup. Only stamped when true to keep the
13
+ // finding shape stable for the vast majority of rules.
14
+ if (ap.advisory === true) base.advisory = true;
15
+ return base;
10
16
  }
11
17
 
12
18
  export { getAP, finding };
@@ -5,11 +5,24 @@ import path from 'node:path';
5
5
  // File walker
6
6
  // ---------------------------------------------------------------------------
7
7
 
8
+ // Hidden directories are skipped wholesale during recursion (below), which
9
+ // covers .git / .next / .nuxt / .svelte-kit / .turbo / .vercel and — the
10
+ // issue #303 class — every vendored AI-harness install (.claude, .cursor,
11
+ // .codex, .agents, .impeccable, ...) whose bundled detector source would
12
+ // otherwise be reported as findings on a root scan. Only the non-hidden
13
+ // build/dependency dirs need naming. An explicitly passed hidden target
14
+ // still scans: walkDir name-checks children, never the root it's given.
8
15
  const SKIP_DIRS = new Set([
9
- 'node_modules', '.git', 'dist', 'build', '.next', '.nuxt', '.output',
10
- '.svelte-kit', '__pycache__', '.turbo', '.vercel',
16
+ 'node_modules', 'dist', 'build', '__pycache__',
11
17
  ]);
12
18
 
19
+ // The exceptions to the hidden-dir rule: hidden directories that
20
+ // conventionally hold real UI source rather than tooling or vendored code.
21
+ // VitePress and VuePress keep custom theme components in
22
+ // .vitepress/theme/*.vue / .vuepress/theme/, and Storybook keeps preview
23
+ // decorators/styles in .storybook/.
24
+ const HIDDEN_SOURCE_DIRS = new Set(['.vitepress', '.vuepress', '.storybook']);
25
+
13
26
  const SCANNABLE_EXTENSIONS = new Set([
14
27
  '.html', '.htm', '.css', '.scss', '.sass', '.less',
15
28
  '.jsx', '.tsx', '.js', '.ts',
@@ -24,6 +37,7 @@ function walkDir(dir) {
24
37
  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return files; }
25
38
  for (const entry of entries) {
26
39
  if (SKIP_DIRS.has(entry.name)) continue;
40
+ if (entry.isDirectory() && entry.name.startsWith('.') && !HIDDEN_SOURCE_DIRS.has(entry.name)) continue;
27
41
  const full = path.join(dir, entry.name);
28
42
  if (entry.isDirectory()) files.push(...walkDir(full));
29
43
  else if (SCANNABLE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) files.push(full);
@@ -149,6 +149,15 @@ const ANTIPATTERNS = [
149
149
  skillSection: 'Color & Contrast',
150
150
  skillGuideline: 'dark mode with glowing accents',
151
151
  },
152
+ {
153
+ id: 'radial-spotlight-glow',
154
+ category: 'slop',
155
+ name: 'Decorative radial spotlight glow',
156
+ description:
157
+ 'A soft, low-opacity accent-colored radial gradient fading to transparent, dropped behind a hero or section as a "spotlight." It is a reflex AI decoration — the translucent cousin of the saturated radial halo. Let the surface stand on its own, or light the composition with a deliberate material accent rather than a floating colored haze.',
158
+ skillSection: 'Color & Contrast',
159
+ skillGuideline: 'dark mode with glowing accents',
160
+ },
152
161
  {
153
162
  id: 'marquee',
154
163
  category: 'slop',
@@ -189,15 +198,14 @@ const ANTIPATTERNS = [
189
198
  skillGuideline: 'tiny uppercase tracked label above the hero headline',
190
199
  },
191
200
  {
192
- id: 'repeated-section-kickers',
201
+ id: 'kicker-above-heading',
193
202
  category: 'slop',
194
203
  scopes: ['type'],
195
- severity: 'advisory',
196
- name: 'Repeated section kicker labels',
204
+ name: 'Kicker / eyebrow label above heading',
197
205
  description:
198
- 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.',
206
+ 'A tiny tracked uppercase or small-caps label sitting as its own block directly above a heading is banned outright, repeated or not. Generated kickers never earn their place: the heading carries its own weight. Delete the label and let the heading speak; if the words matter, work them into the heading or the body.',
199
207
  skillSection: 'Typography',
200
- skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
208
+ skillGuideline: 'kicker or eyebrow labels above headings',
201
209
  },
202
210
  {
203
211
  id: 'numbered-section-labels',
@@ -213,9 +221,14 @@ const ANTIPATTERNS = [
213
221
  {
214
222
  id: 'em-dash-overuse',
215
223
  category: 'slop',
224
+ // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
225
+ // rather than a failure. It fires only on the AI saturation pattern, not on
226
+ // ordinary prose. Advisory findings are surfaced separately, never counted
227
+ // as failures, and skipped by the design hook unless a project opts in.
228
+ advisory: true,
216
229
  name: 'Em-dash overuse',
217
230
  description:
218
- 'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
231
+ 'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
219
232
  skillSection: 'Copy',
220
233
  skillGuideline: 'no em dashes',
221
234
  },
@@ -405,6 +418,14 @@ const ANTIPATTERNS = [
405
418
  description:
406
419
  'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
407
420
  },
421
+ {
422
+ id: 'undersized-ui-text',
423
+ category: 'quality',
424
+ scopes: ['type'],
425
+ name: 'Undersized functional text',
426
+ description:
427
+ 'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
428
+ },
408
429
  {
409
430
  id: 'all-caps-body',
410
431
  category: 'quality',
@@ -556,6 +577,18 @@ function getAntipattern(id) {
556
577
  return ANTIPATTERNS.find(rule => rule.id === id);
557
578
  }
558
579
 
580
+ // Advisory rules are detected and reported, but never treated as failures:
581
+ // the CLI lists them under a separate "Advisory" section, they do not affect
582
+ // exit codes or the failure count, and the design hook skips them by default.
583
+ // The set is derived from the registry so a rule only needs `advisory: true`.
584
+ const ADVISORY_RULE_IDS = new Set(
585
+ ANTIPATTERNS.filter(rule => rule.advisory === true).map(rule => rule.id),
586
+ );
587
+
588
+ function isAdvisoryRule(id) {
589
+ return ADVISORY_RULE_IDS.has(id);
590
+ }
591
+
559
592
  function getRulesForCategory(category) {
560
593
  return ANTIPATTERNS.filter(rule => rule.category === category);
561
594
  }
@@ -585,8 +618,10 @@ export {
585
618
  ANTIPATTERNS,
586
619
  RULE_SCOPES,
587
620
  RULE_ENGINE_SUPPORT,
621
+ ADVISORY_RULE_IDS,
588
622
  getAntipattern,
589
623
  getRulesForCategory,
590
624
  getRuleEngineSupport,
625
+ isAdvisoryRule,
591
626
  filterByScopes,
592
627
  };