impeccable 3.6.0 → 3.6.1

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.
@@ -42,6 +42,7 @@ function shouldRunPageAnalyzers(content, filePath) {
42
42
  }
43
43
 
44
44
  const JS_SOURCE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
45
+ const STYLESHEET_EXTS = new Set(['.css', '.scss', '.sass', '.less']);
45
46
  const REGEX_PREFIX_KEYWORDS = new Set(['await', 'case', 'default', 'delete', 'do', 'else', 'in', 'instanceof', 'new', 'of', 'return', 'throw', 'typeof', 'void', 'yield']);
46
47
  const BLOCK_BRACE_PREFIX_KEYWORDS = new Set(['do', 'else', 'finally', 'try']);
47
48
 
@@ -256,6 +257,153 @@ function stripCssComments(content) {
256
257
  return content.replace(/\/\*[\s\S]*?\*\//g, comment => comment.replace(/[^\n]/g, ' '));
257
258
  }
258
259
 
260
+ function blankHtmlComments(text) {
261
+ return text.replace(/<!--[\s\S]*?-->/g, comment => comment.replace(/[^\n]/g, ' '));
262
+ }
263
+
264
+ function blankCssLineCommentsInStyleBlocks(text) {
265
+ const re = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
266
+ let output = '';
267
+ let lastIndex = 0;
268
+ let match;
269
+ while ((match = re.exec(text)) !== null) {
270
+ const inner = match[1];
271
+ const openLength = match[0].length - inner.length - '</style>'.length;
272
+ output += text.slice(lastIndex, match.index);
273
+ output += match[0].slice(0, openLength);
274
+ output += blankCssLineComments(inner);
275
+ output += match[0].slice(openLength + inner.length);
276
+ lastIndex = re.lastIndex;
277
+ }
278
+ return output + text.slice(lastIndex);
279
+ }
280
+
281
+ function blankHtmlAndCssCommentsOutsideScripts(text) {
282
+ const re = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
283
+ let output = '';
284
+ let lastIndex = 0;
285
+ let match;
286
+ while ((match = re.exec(text)) !== null) {
287
+ output += blankCssLineCommentsInStyleBlocks(stripCssComments(blankHtmlComments(text.slice(lastIndex, match.index))));
288
+ output += match[0];
289
+ lastIndex = re.lastIndex;
290
+ }
291
+ return output + blankCssLineCommentsInStyleBlocks(stripCssComments(blankHtmlComments(text.slice(lastIndex))));
292
+ }
293
+
294
+ function blankCssLineComments(text) {
295
+ let output = '';
296
+ let state = 'code';
297
+ let urlDepth = 0;
298
+ for (let i = 0; i < text.length; i++) {
299
+ const char = text[i];
300
+ const next = text[i + 1];
301
+ if (state === 'line') {
302
+ if (char === '\n') {
303
+ output += '\n';
304
+ state = 'code';
305
+ } else {
306
+ output += ' ';
307
+ }
308
+ continue;
309
+ }
310
+ if (state === 'single' || state === 'double') {
311
+ output += char;
312
+ if (char === '\\' && next) {
313
+ output += next;
314
+ i++;
315
+ } else if ((state === 'single' && char === "'") || (state === 'double' && char === '"')) {
316
+ state = 'code';
317
+ }
318
+ continue;
319
+ }
320
+ const prev = output.length ? output[output.length - 1] : '';
321
+ if (char === '/' && next === '/' && urlDepth === 0 && prev !== ':' && prev !== '(' && prev !== '\\') {
322
+ output += ' ';
323
+ i++;
324
+ state = 'line';
325
+ continue;
326
+ }
327
+ if (char === "'") state = 'single';
328
+ else if (char === '"') state = 'double';
329
+ if (char === '(') {
330
+ const behind = output.replace(/\s+$/, '');
331
+ if (urlDepth > 0 || /url$/i.test(behind)) urlDepth++;
332
+ } else if (char === ')' && urlDepth) {
333
+ urlDepth--;
334
+ }
335
+ output += char;
336
+ }
337
+ return output;
338
+ }
339
+
340
+ function findAstroFrontmatterClose(text) {
341
+ if (!text.startsWith('---')) return -1;
342
+ let cursor = text.indexOf('\n');
343
+ if (cursor === -1) return -1;
344
+ cursor += 1;
345
+ while (cursor < text.length) {
346
+ if (text[cursor - 1] === '\n' && text.startsWith('---', cursor)) {
347
+ let end = cursor + 3;
348
+ while (text[end] === ' ' || text[end] === '\t') end++;
349
+ if (end >= text.length || text[end] === '\n' || text[end] === '\r') return cursor - 1;
350
+ }
351
+ const char = text[cursor];
352
+ const next = text[cursor + 1];
353
+ if (char === "'" || char === '"') {
354
+ const close = findQuotedStringEnd(text, cursor, char);
355
+ if (close === -1) return -1;
356
+ cursor = close + 1;
357
+ continue;
358
+ }
359
+ if (char === '`') {
360
+ const close = findTemplateLiteralEnd(text, cursor);
361
+ if (close === -1) return -1;
362
+ cursor = close + 1;
363
+ continue;
364
+ }
365
+ if (char === '/' && next === '/') {
366
+ const lineEnd = text.indexOf('\n', cursor);
367
+ if (lineEnd === -1) return -1;
368
+ cursor = lineEnd;
369
+ continue;
370
+ }
371
+ if (char === '/' && next === '*') {
372
+ const commentEnd = text.indexOf('*/', cursor + 2);
373
+ if (commentEnd === -1) return -1;
374
+ cursor = commentEnd + 2;
375
+ continue;
376
+ }
377
+ if (char === '/' && next !== '/' && next !== '*') {
378
+ const close = findRegexLiteralEnd(text, cursor);
379
+ if (close !== -1) {
380
+ cursor = close + 1;
381
+ continue;
382
+ }
383
+ }
384
+ cursor++;
385
+ }
386
+ return -1;
387
+ }
388
+
389
+ function blankAstroFrontmatterComments(text) {
390
+ const close = findAstroFrontmatterClose(text);
391
+ if (close === -1) return text;
392
+ return stripJsComments(text.slice(0, close)) + text.slice(close);
393
+ }
394
+
395
+ function blankCommentsForMatchers(text, ext) {
396
+ if (PAGE_ANALYZER_EXTS.has(ext)) {
397
+ const withFrontmatter = ext === '.astro' ? blankAstroFrontmatterComments(text) : text;
398
+ return blankHtmlAndCssCommentsOutsideScripts(withFrontmatter);
399
+ }
400
+ if (STYLESHEET_EXTS.has(ext)) {
401
+ const withoutBlocks = stripCssComments(text);
402
+ return ext === '.css' ? withoutBlocks : blankCssLineComments(withoutBlocks);
403
+ }
404
+ return text;
405
+ }
406
+
259
407
  function firstOverusedGoogleFont(text) {
260
408
  return extractGoogleFontFamilies(text).find(f => OVERUSED_FONTS.has(f)) || '';
261
409
  }
@@ -1028,14 +1176,13 @@ function detectText(content, filePath, options = {}) {
1028
1176
  const ext = extFromFilePath(filePath);
1029
1177
  const commentStrippedSource = JS_SOURCE_EXTS.has(ext) ? stripJsComments(content, {
1030
1178
  jsx: ext === '.js' || ext === '.jsx' || ext === '.tsx',
1031
- }) : content;
1179
+ }) : blankCommentsForMatchers(content, ext);
1032
1180
  const source = stripCssInJsComments(commentStrippedSource, ext);
1033
1181
  const lines = source.split('\n');
1034
1182
 
1035
1183
  // Run regex matchers on the full file content (catches Tailwind classes, inline styles)
1036
1184
  // Enable block context for CSS files where related properties span multiple lines
1037
- const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
1038
- findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
1185
+ findings.push(...runRegexMatchers(lines, filePath, 0, STYLESHEET_EXTS.has(ext) || null, {
1039
1186
  profile,
1040
1187
  phase: 'source',
1041
1188
  }));
@@ -1050,7 +1197,7 @@ function detectText(content, filePath, options = {}) {
1050
1197
  scanCssTextForPseudoStripe(text).map(hit =>
1051
1198
  finding(hit.id, filePath, hit.snippet, lineOffset + text.slice(0, hit.index).split('\n').length));
1052
1199
 
1053
- if (cssLike.has(ext)) {
1200
+ if (STYLESHEET_EXTS.has(ext)) {
1054
1201
  findings.push(...scanInsetStripeCss(content, filePath));
1055
1202
  findings.push(...pseudoStripeFindings(content, 0));
1056
1203
  }
@@ -1078,7 +1225,8 @@ function detectText(content, filePath, options = {}) {
1078
1225
  }, () => extractStyleBlocks(content, ext))
1079
1226
  : extractStyleBlocks(content, ext);
1080
1227
  for (const block of styleBlocks) {
1081
- const blockLines = block.content.split('\n');
1228
+ const blockContent = blankCssLineComments(stripCssComments(block.content));
1229
+ const blockLines = blockContent.split('\n');
1082
1230
  findings.push(...runRegexMatchers(blockLines, filePath, block.startLine - 1, true, {
1083
1231
  profile,
1084
1232
  phase: 'style-block',
@@ -1089,8 +1237,8 @@ function detectText(content, filePath, options = {}) {
1089
1237
  // 1-based, so the offset is startLine - 2; startLine - 1 double-counted and
1090
1238
  // reported every selector one line low. runRegexMatchers keeps startLine - 1
1091
1239
  // because it indexes its split lines from zero.
1092
- findings.push(...scanInsetStripeCss(block.content, filePath, block.startLine - 2));
1093
- findings.push(...pseudoStripeFindings(block.content, block.startLine - 2));
1240
+ findings.push(...scanInsetStripeCss(blockContent, filePath, block.startLine - 2));
1241
+ findings.push(...pseudoStripeFindings(blockContent, block.startLine - 2));
1094
1242
  }
1095
1243
 
1096
1244
  // Extract and scan CSS-in-JS template literals
@@ -835,10 +835,11 @@ class StaticElement {
835
835
  }
836
836
  }
837
837
  closest(selector) {
838
+ const matcher = this._doc.matcherFor(selector);
838
839
  let cur = this.node;
839
840
  while (cur && cur.type === 'tag') {
840
841
  try {
841
- if (this._doc.is(cur, selector)) return this._doc.wrap(cur);
842
+ if (matcher(cur)) return this._doc.wrap(cur);
842
843
  } catch {
843
844
  return null;
844
845
  }
@@ -862,9 +863,10 @@ class StaticDocument {
862
863
  this.root = root;
863
864
  this.selectAll = modules.selectAll;
864
865
  this.selectOne = modules.selectOne;
865
- this.is = modules.is;
866
+ this.compile = modules.compile;
866
867
  this.domutils = modules.domutils;
867
868
  this._wrappers = new WeakMap();
869
+ this._compiledSelectors = new Map();
868
870
  this._styleMap = new WeakMap();
869
871
  this._hoverStyleMap = new WeakMap();
870
872
  this._accentDashPseudo = new WeakSet();
@@ -882,6 +884,20 @@ class StaticDocument {
882
884
  }
883
885
  return wrapped;
884
886
  }
887
+ matcherFor(selector) {
888
+ let matcher = this._compiledSelectors.get(selector);
889
+ if (!matcher) {
890
+ try {
891
+ matcher = this.compile(selector);
892
+ } catch (err) {
893
+ // Cache the failure as a rethrower so a bad selector still reaches
894
+ // closest()'s catch on every call, first and repeat alike.
895
+ matcher = () => { throw err; };
896
+ }
897
+ this._compiledSelectors.set(selector, matcher);
898
+ }
899
+ return matcher;
900
+ }
885
901
  querySelectorAll(selector) {
886
902
  try {
887
903
  return this.selectAll(selector, this.root.children || []).map(node => this.wrap(node));
@@ -948,8 +964,34 @@ function buildStaticWindow(staticDoc) {
948
964
  };
949
965
  }
950
966
 
967
+ function resolveLinkedCssPath(fileDir, href) {
968
+ const stripped = href.split(/[?#]/)[0];
969
+ const rootRelative = stripped.startsWith('/') && !stripped.startsWith('//');
970
+ if (!rootRelative) return path.resolve(fileDir, stripped);
971
+ // Drop "." and reject ".." so /../outside.css cannot walk out of dir.
972
+ const segments = stripped.replace(/^\/+/, '').split(/[/\\]/).filter(p => p && p !== '.');
973
+ if (segments.some(p => p === '..')) return path.join(fileDir, segments.filter(p => p !== '..').join(path.sep));
974
+ const rel = segments.join(path.sep);
975
+ let dir = fileDir;
976
+ for (;;) {
977
+ const parent = path.dirname(dir);
978
+ if (parent === dir) break; // never use the filesystem root as document root
979
+ try {
980
+ const candidate = path.join(dir, rel);
981
+ if (fs.statSync(candidate).isFile()) return candidate;
982
+ } catch { /* missing or unreadable candidate */ }
983
+ // Stop at the project root so a coincidental ~/static/app.css cannot win.
984
+ try {
985
+ if (fs.existsSync(path.join(dir, 'package.json')) || fs.existsSync(path.join(dir, '.git'))) break;
986
+ } catch { /* unreadable marker */ }
987
+ dir = parent;
988
+ }
989
+ return path.join(fileDir, rel);
990
+ }
991
+
951
992
  function collectStaticCssText(root, fileDir, profile, filePath, modules) {
952
993
  const styleTexts = [];
994
+ const warnedMissingStylesheets = new Set();
953
995
  for (const styleEl of modules.selectAll('style', root.children || [])) {
954
996
  styleTexts.push(modules.domutils.textContent(styleEl));
955
997
  }
@@ -958,10 +1000,10 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
958
1000
  const rel = link.attribs?.rel || '';
959
1001
  const href = link.attribs?.href || '';
960
1002
  if (!/\bstylesheet\b/i.test(rel) || !href || /^(https?:)?\/\//i.test(href)) continue;
961
- // Cache-busting hrefs (styles.css?v=3) resolve to the file, not to a
962
- // literal path with the query in it; a versioned link otherwise made the
963
- // whole stylesheet invisible to every element-level check.
964
- const cssPath = path.resolve(fileDir, href.split(/[?#]/)[0]);
1003
+ // Cache-busting (styles.css?v=3) and root-relative (/static/app.css) hrefs
1004
+ // must not resolve as OS-absolute paths; otherwise the whole stylesheet is
1005
+ // invisible to every element-level check.
1006
+ const cssPath = resolveLinkedCssPath(fileDir, href);
965
1007
  try {
966
1008
  const css = profileStep(profile, {
967
1009
  engine: 'static-html',
@@ -971,7 +1013,14 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
971
1013
  detail: href,
972
1014
  }, () => fs.readFileSync(cssPath, 'utf-8'));
973
1015
  styleTexts.push(css);
974
- } catch { /* skip unreadable */ }
1016
+ } catch {
1017
+ if (!warnedMissingStylesheets.has(cssPath)) {
1018
+ warnedMissingStylesheets.add(cssPath);
1019
+ process.stderr.write(
1020
+ `impeccable detect: could not read linked stylesheet ${href} (resolved to ${cssPath}); color and custom-property rules will be incomplete\n`
1021
+ );
1022
+ }
1023
+ }
975
1024
  }
976
1025
  return styleTexts.join('\n');
977
1026
  }
@@ -1,7 +1,7 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
- import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
4
+ import { OVERUSED_FONTS, primaryFontFace } from '../../shared/constants.mjs';
5
5
  import {
6
6
  checkSourceDesignSystem,
7
7
  collectStaticDesignSystemFindings,
@@ -51,9 +51,7 @@ function checkStaticPageTypography(document, window) {
51
51
  for (const el of document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, td, th, dd, blockquote, figcaption, a, button, label, span, div')) {
52
52
  const hasText = el.childNodes.some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
53
53
  if (!hasText) continue;
54
- const ff = window.getComputedStyle(el).fontFamily || '';
55
- const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
56
- const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
54
+ const primary = primaryFontFace(window.getComputedStyle(el).fontFamily);
57
55
  if (!primary) continue;
58
56
  fonts.add(primary);
59
57
  if (OVERUSED_FONTS.has(primary)) overusedFound.add(primary);
@@ -134,7 +132,7 @@ async function detectHtml(filePath, options = {}) {
134
132
  parseDocument: htmlparser2.parseDocument,
135
133
  selectAll: cssSelect.selectAll,
136
134
  selectOne: cssSelect.selectOne,
137
- is: cssSelect.is,
135
+ compile: cssSelect.compile,
138
136
  csstree,
139
137
  domutils,
140
138
  };
@@ -121,6 +121,24 @@ const ANTIPATTERNS = [
121
121
  'A large inline SVG that builds a pictorial scene from a pile of primitive shapes reads as placeholder clip art, not illustration. Icons, logos, and data graphics are fine at their scale; a hero-sized visual deserves real artwork, a photograph, or a deliberately drawn graphic.',
122
122
  skillSection: 'Imagery',
123
123
  },
124
+ {
125
+ id: 'organic-clip-path',
126
+ category: 'quality',
127
+ name: 'Organic contour drawn as clip-path',
128
+ description:
129
+ 'A clip-path polygon with many arbitrary vertices, or a curved clip-path path(), is CSS approximating a torn edge, blob, or silhouette. It reads as the cheap version of the effect and is usually a produced or photographic material replaced with code. Derive an alpha matte from the real image, or ship the shape as a cut-out raster; keep clip-path for geometry (cut corners, diagonals, hexagons).',
130
+ skillSection: 'Imagery',
131
+ skillGuideline: 'geometric masks standing in for organic contours',
132
+ },
133
+ {
134
+ id: 'buried-raster',
135
+ category: 'quality',
136
+ name: 'Raster buried under a wash or opacity',
137
+ description:
138
+ 'A background image under a near-opaque gradient wash, or a raster on an element at near-zero opacity, never reaches the screen: the page shows the wash, and the produced texture or photo ships as a compliance token. Let the material show (a tint under 0.9 alpha, a blend mode, an opacity you can see) or remove the file.',
139
+ skillSection: 'Imagery',
140
+ skillGuideline: 'a produced material must survive to the screen',
141
+ },
124
142
  {
125
143
  id: 'dark-glow',
126
144
  category: 'slop',