@bastani/atomic 0.9.0-alpha.3 → 0.9.0

package/dist/builtin/workflows/skills/impeccable/scripts/critique-storage.mjs

@@ -28,7 +28,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getCritiqueDir } from './impeccable-paths.mjs';
+import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 const SLUG_MAX = 50;
 

package/dist/builtin/workflows/skills/impeccable/scripts/detector/browser/injected/index.mjs

@@ -660,6 +660,7 @@ if (IS_BROWSER) {
       if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
       if (el.closest('[id^="impeccable-live-"]')) continue;
       if (el === document.body || el === document.documentElement) continue;
+      if (!isRenderedForBrowserRule(el)) continue;
 
       const tag = el.tagName.toLowerCase();
       const style = getComputedStyle(el);
@@ -1091,6 +1092,7 @@ if (IS_BROWSER) {
       return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'stale selector' };
     }
     if (!el) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing element' };
+    if (!isRenderedForBrowserRule(el)) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'hidden element' };
 
     const blockingReason = (candidate.reasons || []).find(reason =>
       reason === 'background-clip text' ||
@@ -1222,6 +1224,7 @@ if (IS_BROWSER) {
           category: ap ? ap.category : 'quality',
           severity: ap?.severity || 'warning',
           detail: f.detail || f.snippet,
+          ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
           description: ap ? ap.description : '',
         };
@@ -1258,10 +1261,203 @@ if (IS_BROWSER) {
     return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
   }
 
+  const DESIGN_COLOR_TOLERANCE = 6;
+  const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
+  const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
+
+  function normalizeBrowserFontName(value) {
+    return String(value || '')
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .replace(/\+/g, ' ')
+      .replace(/\s+/g, ' ')
+      .toLowerCase();
+  }
+
+  function browserPrimaryFont(stack) {
+    if (!stack || /var\(/i.test(stack)) return '';
+    return String(stack)
+      .split(',')
+      .map(normalizeBrowserFontName)
+      .find(font => font && !GENERIC_FONTS.has(font)) || '';
+  }
+
+  function browserDesignSystemConfig() {
+    const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
+    if (!raw?.present) return null;
+    const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
+    const allowedColors = (raw.allowedColors || [])
+      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
+      .map(color => ({ r: color.r, g: color.g, b: color.b }));
+    const allowedRadii = (raw.allowedRadii || [])
+      .map(Number)
+      .filter(px => Number.isFinite(px));
+    return {
+      present: true,
+      hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
+      allowedFonts,
+      hasColors: raw.hasColors === true && allowedColors.length > 0,
+      allowedColors,
+      hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
+      allowedRadii,
+      hasPillRadius: raw.hasPillRadius === true,
+    };
+  }
+
+  function browserColorsClose(a, b) {
+    if (!a || !b) return false;
+    return Math.max(
+      Math.abs(a.r - b.r),
+      Math.abs(a.g - b.g),
+      Math.abs(a.b - b.b),
+    ) <= DESIGN_COLOR_TOLERANCE;
+  }
+
+  function isBrowserDesignColorAllowed(raw, designSystem) {
+    if (!designSystem?.hasColors) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
+    if (text.includes('var(')) return true;
+    const parsed = parseAnyColor(text);
+    if (!parsed) return true;
+    if ((parsed.a ?? 1) <= 0.05) return true;
+    return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
+  }
+
+  function isBrowserTransparentCss(value) {
+    const text = String(value || '').trim().toLowerCase();
+    if (!text || text === 'transparent') return true;
+    const parsed = parseAnyColor(text);
+    return parsed ? (parsed.a ?? 1) <= 0.05 : false;
+  }
+
+  function isBrowserDesignRadiusAllowed(raw, designSystem) {
+    if (!designSystem?.hasRadii) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
+    if (text.includes('var(') || text.includes('%')) return true;
+    const px = resolveLengthPx(text, 16);
+    if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
+    if (designSystem.hasPillRadius && px >= 99) return true;
+    return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
+  }
+
+  function browserRadiusTokens(value) {
+    return String(value || '')
+      .replace(/\s*\/\s*/g, ' ')
+      .split(/\s+/)
+      .map(token => token.trim())
+      .filter(Boolean);
+  }
+
+  function browserHasDirectText(el) {
+    return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
+  }
+
+  function browserSampleText(el) {
+    const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
+    return text ? ` "${text.slice(0, 40)}"` : '';
+  }
+
+  function shouldSkipDesignElement(el) {
+    const tag = el.tagName?.toLowerCase?.() || '';
+    return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
+  }
+
+  function checkElementDesignSystemDOM(el, designSystem, seen) {
+    if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
+    const findings = [];
+    const tag = el.tagName?.toLowerCase?.() || 'unknown';
+    const style = getComputedStyle(el);
+
+    if (designSystem.hasFonts && browserHasDirectText(el)) {
+      const font = browserPrimaryFont(style.fontFamily || '');
+      if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
+          ignoreValue: font,
+        });
+      }
+    }
+
+    if (designSystem.hasColors) {
+      const colorChecks = [];
+      if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
+      if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
+      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
+          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
+        }
+      }
+      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
+
+      for (const [kind, raw] of colorChecks) {
+        const label = String(raw || '').trim().replace(/\s+/g, ' ');
+        if (isBrowserDesignColorAllowed(label, designSystem)) continue;
+        const key = `${kind}:${label}`;
+        if (seen.colors.has(key)) continue;
+        seen.colors.add(key);
+        findings.push({
+          type: 'design-system-color',
+          detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
+          ignoreValue: label,
+        });
+      }
+    }
+
+    if (designSystem.hasRadii) {
+      for (const token of browserRadiusTokens(style.borderRadius || '')) {
+        if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
+        if (seen.radii.has(token)) continue;
+        seen.radii.add(token);
+        findings.push({
+          type: 'design-system-radius',
+          detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
+          ignoreValue: token,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  function decodeBrowserGoogleFamily(value) {
+    const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
+    try {
+      return decodeURIComponent(family);
+    } catch {
+      return family;
+    }
+  }
+
+  function checkBrowserDesignSystemSources(designSystem, seen) {
+    if (!designSystem?.hasFonts) return [];
+    const findings = [];
+    for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
+      const href = link.getAttribute('href') || '';
+      for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
+        const display = decodeBrowserGoogleFamily(match[1]);
+        const font = normalizeBrowserFontName(display);
+        if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
+          ignoreValue: display,
+        });
+      }
+    }
+    return findings;
+  }
+
   function collectBrowserFindings() {
     const groupMap = new Map();
     const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
     const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
+    const designSystem = browserDesignSystemConfig();
+    const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
     // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
     // real browser env (detector page, live overlay, extension) running every
     // check is free, so we always surface them; the gating is purely a CLI
@@ -1292,6 +1488,7 @@ if (IS_BROWSER) {
         ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementDesignSystemDOM(el, designSystem, designSeen),
       ].filter(f => _ruleOk(f.type));
 
       addBrowserFindings(groupMap, el, findings);
@@ -1308,6 +1505,13 @@ if (IS_BROWSER) {
 
     const pageLevelFindings = [];
 
+    const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
+      .filter(f => _ruleOk(f.type));
+    if (designSourceFindings.length > 0) {
+      pageLevelFindings.push(...designSourceFindings);
+      addBrowserFindings(groupMap, document.body, designSourceFindings);
+    }
+
     const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
     if (typoFindings.length > 0) {
       pageLevelFindings.push(...typoFindings);
@@ -1437,13 +1641,20 @@ if (IS_BROWSER) {
     return true;
   }
 
-  function postSerializedFindings(groupMap) {
+  function scanResultMeta(options = {}) {
+    const scanId = options.scanId;
+    if (typeof scanId !== 'string' && typeof scanId !== 'number') return {};
+    return { scanId: String(scanId) };
+  }
+
+  function postSerializedFindings(groupMap, options = {}) {
     if (!EXTENSION_MODE) return;
     const allFindings = browserFindingsFromMap(groupMap);
     window.postMessage({
       source: 'impeccable-results',
       findings: serializeFindings(allFindings),
       count: allFindings.length,
+      ...scanResultMeta(options),
     }, '*');
   }
 
@@ -1497,7 +1708,7 @@ if (IS_BROWSER) {
             rememberVisualContrastAnalysis(result);
             const added = addVisualContrastResult(groupMap, result, { decorate: true });
             if (added) {
-              postSerializedFindings(groupMap);
+              postSerializedFindings(groupMap, options);
               window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-resolved', {
                 detail: {
                   selector: result.selector,
@@ -1565,7 +1776,7 @@ if (IS_BROWSER) {
     overlayIndex = 0;
   }
 
-  function renderBrowserFindings(collected) {
+  function renderBrowserFindings(collected, options = {}) {
     const { allFindings, pageLevelFindings } = collected;
 
     for (const { el, findings } of allFindings) {
@@ -1585,6 +1796,7 @@ if (IS_BROWSER) {
         source: 'impeccable-results',
         findings: serializeFindings(allFindings),
         count: allFindings.length,
+        ...scanResultMeta(options),
       }, '*');
     }
 
@@ -1599,11 +1811,11 @@ if (IS_BROWSER) {
     clearOverlays();
     const generation = scanGeneration;
     const collected = collectBrowserFindings();
-    const allFindings = renderBrowserFindings(collected);
+    const allFindings = renderBrowserFindings(collected, options);
     if (shouldRunVisualContrast(options)) {
       addVisualContrastFindings(collected.groupMap, options, { decorate: true, generation })
         .then(() => {
-          if (generation === scanGeneration) postSerializedFindings(collected.groupMap);
+          if (generation === scanGeneration) postSerializedFindings(collected.groupMap, options);
         })
         .catch(err => {
           reportVisualContrastError(err);
@@ -1618,10 +1830,10 @@ if (IS_BROWSER) {
     if (shouldRunVisualContrast(options)) {
       const collected = await collectBrowserFindingsAsync(options, { generation, scheduleLazy: true });
       if (generation !== scanGeneration) return [];
-      return renderBrowserFindings(collected);
+      return renderBrowserFindings(collected, options);
     }
     lastVisualContrastAnalyses = [];
-    return renderBrowserFindings(collectBrowserFindings());
+    return renderBrowserFindings(collectBrowserFindings(), options);
   };
 
   const detect = function(options = {}) {

package/dist/builtin/workflows/skills/impeccable/scripts/detector/cli/main.mjs

@@ -1,9 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { loadDesignSystemForCwd } from '../design-system.mjs';
 import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
 import { detectHtml } from '../engines/static-html/detect-html.mjs';
 import { detectText } from '../engines/regex/detect-text.mjs';
+import {
+  filterDetectionFindings,
+  readDetectionConfig,
+  shouldIgnoreDetectionFile,
+} from '../../lib/impeccable-config.mjs';
 import {
   HTML_EXTENSIONS,
   buildImportGraph,
@@ -16,6 +22,10 @@ import {
 // Output formatting
 // ---------------------------------------------------------------------------
 
+function formatFindingSummary(count) {
+  return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
+}
+
 function formatFindings(findings, jsonMode) {
   if (jsonMode) return JSON.stringify(findings, null, 2);
 
@@ -33,7 +43,7 @@ function formatFindings(findings, jsonMode) {
       out.push(`    → ${item.description}`);
     }
   }
-  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found.`);
+  out.push(`\n${formatFindingSummary(findings.length)}`);
   return out.join('\n');
 }
 
@@ -79,10 +89,28 @@ function printUsage() {
 Scan files or URLs for UI anti-patterns and design quality issues.
 
 Options:
-  --json    Output results as JSON
-  --gpt     Also report GPT-specific provider tells (off by default)
-  --gemini  Also report Gemini-specific provider tells (off by default)
-  --help    Show this help message
+  --json              Output results as JSON
+  --quiet             In text mode, only print the final findings count
+  --gpt               Also report GPT-specific provider tells (off by default)
+  --gemini            Also report Gemini-specific provider tells (off by default)
+  --no-config         Do not apply project config, detector ignores, inline
+                      ignore comments, or DESIGN.md
+  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
+  --no-design-system  Do not load local DESIGN.md / .impeccable/design.json context
+  --help              Show this help message
+
+Project config:
+  Respects .impeccable/config.json and .impeccable/config.local.json detector
+  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
+  and detector.designSystem.enabled.
+
+Inline ignores:
+  In-file comments waive a finding where it lives and travel with the file:
+    <!-- impeccable-disable overused-font -- exported brand doc -->
+    .brand { font-family: Inter } /* impeccable-disable-line overused-font */
+    // impeccable-disable-next-line bounce-easing: intentional bounce
+  impeccable-disable applies to the whole file; -line / -next-line are scoped.
+  List one or more rule ids (comma-separated), or omit them / use * for all.
 
 Detection modes:
   HTML files     Static HTML/CSS analysis (default, catches linked CSS)
@@ -93,7 +121,8 @@ Examples:
   impeccable detect src/
   impeccable detect index.html
   impeccable detect https://example.com
-  impeccable detect --json .`);
+  impeccable detect --json .
+  impeccable detect --no-config src/`);
 }
 
 async function detectCli() {
@@ -104,6 +133,7 @@ async function detectCli() {
   });
   if (args[0] === 'detect') args = args.slice(1);
   const jsonMode = args.includes('--json');
+  const quietMode = args.includes('--quiet');
   const helpMode = args.includes('--help');
   // --fast (regex-only) is deprecated: since the jsdom removal, the static
   // HTML/CSS analysis is fast and covers every rule, so the regex-only path
@@ -114,10 +144,21 @@ async function detectCli() {
       'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
     );
   }
+  const configEnabled = !args.includes('--no-config');
+  const detectionConfig = configEnabled
+    ? readDetectionConfig(process.cwd())
+    : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
   const providers = [];
   if (args.includes('--gpt')) providers.push('gpt');
   if (args.includes('--gemini')) providers.push('gemini');
-  const scanOptions = { providers };
+  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
+  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
+  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
+  // apply by default. `--no-config` (raw scan) and the dedicated
+  // `--no-inline-ignores` both turn them off.
+  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
+  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
+  if (designSystem) scanOptions.designSystem = designSystem;
   const targets = args.filter(a => !a.startsWith('--'));
 
   if (helpMode) { printUsage(); process.exit(0); }
@@ -149,8 +190,8 @@ async function detectCli() {
         catch { process.stderr.write(`Warning: cannot access ${target}\n`); continue; }
 
         if (stat.isDirectory()) {
-          // Check for framework dev server config (skip in JSON mode to avoid polluting output)
-          if (!jsonMode) {
+          // Check for framework dev server config (skip in JSON/quiet modes to avoid polluting output)
+          if (!jsonMode && !quietMode) {
             const fwConfig = detectFrameworkConfig(resolved);
             if (fwConfig) {
               const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint);
@@ -175,11 +216,12 @@ async function detectCli() {
             }
           }
 
-          const files = walkDir(resolved);
+          const files = walkDir(resolved)
+            .filter(file => !shouldIgnoreDetectionFile(file, process.cwd(), detectionConfig));
           const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;
 
           // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
-          if (files.length > 50 && process.stdin.isTTY && !jsonMode) {
+          if (files.length > 50 && process.stdin.isTTY && !jsonMode && !quietMode) {
             process.stderr.write(
               `\nFound ${files.length} files (${htmlCount} HTML) in ${target}.\n` +
               `Scanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\n` +
@@ -219,6 +261,7 @@ async function detectCli() {
             allFindings.push(...fileFindings);
           }
         } else if (stat.isFile()) {
+          if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
           const ext = path.extname(resolved).toLowerCase();
           if (HTML_EXTENSIONS.has(ext)) {
             allFindings.push(...await detectHtml(resolved, scanOptions));
@@ -232,8 +275,11 @@ async function detectCli() {
     }
   }
 
+  allFindings = filterDetectionFindings(allFindings, detectionConfig);
+
   if (allFindings.length > 0) {
     if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
+    else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
     else process.stderr.write(formatFindings(allFindings, false) + '\n');
     process.exit(2);
   }