1import fs from 'node:fs';
2import path from 'node:path';
3import { fileURLToPath } from 'node:url';
4 
5import { finding } from '../../findings.mjs';
6import { filterByProviders } from '../../registry/antipatterns.mjs';
7import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
8import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
9 
10function serializeDesignSystemForBrowser(designSystem) {
11  if (!designSystem?.present) return null;
12  return {
13    present: true,
14    hasFonts: designSystem.hasFonts === true,
15    allowedFonts: Array.from(designSystem.allowedFonts || []),
16    hasColors: designSystem.hasColors === true,
17    allowedColors: Array.from(designSystem.allowedColorKeys?.values?.() || [])
18      .map(entry => entry?.color)
19      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
20      .map(color => ({ r: color.r, g: color.g, b: color.b })),
21    hasRadii: designSystem.hasRadii === true,
22    allowedRadii: (designSystem.allowedRadii || [])
23      .map(entry => Number(entry?.px))
24      .filter(px => Number.isFinite(px)),
25    hasPillRadius: designSystem.hasPillRadius === true,
26  };
27}
28 
29async function runVisualContrastFallback(page, serializedGroups, options, profile, target) {
30  if (options?.visualContrast === false) return [];
31  const maxCandidates = Number.isFinite(options?.visualContrastMaxCandidates)
32    ? options.visualContrastMaxCandidates
33    : 12;
34  const scrollOffscreen = options?.visualContrastScrollOffscreen !== false;
35  const existingLowContrastSelectors = new Set(
36    serializedGroups
37      .filter(group => group.findings?.some(f => f.type === 'low-contrast'))
38      .map(group => group.selector)
39      .filter(Boolean)
40  );
41 
42  let browserAnalyses = [];
43  const findings = [];
44  if (options?.visualContrastBrowser !== false) {
45    const browserFindings = await profileFindingsAsync(profile, {
46      engine: 'browser',
47      phase: 'visual-contrast',
48      ruleId: 'browser-fallback',
49      target,
50    }, async () => {
51      browserAnalyses = await page.evaluate(async ({ maxCandidates, scrollOffscreen }) => {
52        if (typeof window.impeccableAnalyzeVisualContrast !== 'function') return [];
53        return window.impeccableAnalyzeVisualContrast({ maxCandidates, scrollOffscreen });
54      }, { maxCandidates, scrollOffscreen });
55      return browserAnalyses
56        .filter(result => result.finding && !existingLowContrastSelectors.has(result.selector))
57        .map(result => result.finding);
58    });
59    findings.push(...browserFindings);
60  }
61 
62  let candidates = browserAnalyses.length > 0 ? browserAnalyses : [];
63  if (candidates.length === 0) {
64    candidates = await profileStepAsync(profile, {
65      engine: 'browser',
66      phase: 'visual-contrast',
67      ruleId: 'collect-candidates',
68      target,
69    }, () => page.evaluate(({ maxCandidates }) => {
70      if (typeof window.impeccableCollectVisualContrastCandidates !== 'function') return [];
71      return window.impeccableCollectVisualContrastCandidates({ maxCandidates });
72    }, { maxCandidates }));
73  }
74 
75  const viewport = options?.viewport || { width: 1280, height: 800 };
76  const browserResolvedSelectors = new Set(
77    browserAnalyses
78      .filter(result => result.status === 'fail' || result.status === 'pass')
79      .map(result => result.selector)
80      .filter(Boolean)
81  );
82  const filtered = candidates.filter(candidate =>
83    !existingLowContrastSelectors.has(candidate.selector) &&
84    !browserResolvedSelectors.has(candidate.selector)
85  );
86  if (options?.visualContrastPixel === false) return findings;
87  for (const candidate of filtered) {
88    const result = await profileFindingsAsync(profile, {
89      engine: 'browser',
90      phase: 'visual-contrast',
91      ruleId: 'pixel-diff',
92      target,
93    }, async () => {
94      const finding = await captureVisualContrastCandidate(page, candidate, viewport);
95      return finding ? [finding] : [];
96    });
97    findings.push(...result);
98  }
99  return findings;
100}
101 
102// ---------------------------------------------------------------------------
103// Puppeteer detection (for URLs)
104// ---------------------------------------------------------------------------
105 
106async function detectUrl(url, options = {}) {
107  const profile = options?.profile;
108  const waitUntil = options?.waitUntil || 'networkidle0';
109  const settleMs = Number.isFinite(options?.settleMs) ? options.settleMs : 0;
110  const viewport = options?.viewport || { width: 1280, height: 800 };
111  const externalBrowser = options?.browser || null;
112  let puppeteer;
113  if (!externalBrowser) {
114    try {
115      puppeteer = await profileStepAsync(profile, {
116        engine: 'browser',
117        phase: 'setup',
118        ruleId: 'import-puppeteer',
119        target: url,
120      }, () => import('puppeteer'));
121    } catch {
122      throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
123    }
124  }
125 
126  // Read the browser detection script — reuse it instead of reimplementing
127  const browserScriptPath = path.resolve(
128    path.dirname(fileURLToPath(import.meta.url)),
129    '..',
130    '..',
131    'detect-antipatterns-browser.js'
132  );
133  let browserScript;
134  try {
135    browserScript = profileStep(profile, {
136      engine: 'browser',
137      phase: 'setup',
138      ruleId: 'read-browser-script',
139      target: url,
140    }, () => fs.readFileSync(browserScriptPath, 'utf-8'));
141  } catch {
142    throw new Error(`Browser script not found at ${browserScriptPath}`);
143  }
144 
145  // CI runners (GitHub Actions Ubuntu) block unprivileged user namespaces, so
146  // Chrome can't initialize its sandbox there. Disable the sandbox only when
147  // running in CI; local users keep the default hardened launch.
148  const launchArgs = process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : [];
149  const browser = externalBrowser || await profileStepAsync(profile, {
150    engine: 'browser',
151    phase: 'load',
152    ruleId: 'launch-browser',
153    target: url,
154  }, () => puppeteer.default.launch({ headless: true, args: launchArgs }));
155  const page = await profileStepAsync(profile, {
156    engine: 'browser',
157    phase: 'load',
158    ruleId: 'new-page',
159    target: url,
160  }, () => browser.newPage());
161  let results = [];
162  try {
163    await profileStepAsync(profile, {
164      engine: 'browser',
165      phase: 'load',
166      ruleId: 'set-viewport',
167      target: url,
168    }, () => page.setViewport(viewport));
169    await profileStepAsync(profile, {
170      engine: 'browser',
171      phase: 'load',
172      ruleId: `goto:${waitUntil}`,
173      target: url,
174    }, () => page.goto(url, { waitUntil, timeout: 30000 }));
175    if (settleMs > 0) {
176      await profileStepAsync(profile, {
177        engine: 'browser',
178        phase: 'load',
179        ruleId: 'settle',
180        target: url,
181      }, () => new Promise(resolve => setTimeout(resolve, settleMs)));
182    }
183 
184    // Inject the browser detection script and collect results
185    const browserDesignSystem = serializeDesignSystemForBrowser(options?.designSystem);
186    await profileStepAsync(profile, {
187      engine: 'browser',
188      phase: 'scan',
189      ruleId: 'configure-pure-detect',
190      target: url,
191    }, () => page.evaluate((designSystem) => {
192      window.__IMPECCABLE_CONFIG__ = {
193        ...(window.__IMPECCABLE_CONFIG__ || {}),
194        autoScan: false,
195        ...(designSystem ? { designSystem } : {}),
196      };
197    }, browserDesignSystem));
198    await profileStepAsync(profile, {
199      engine: 'browser',
200      phase: 'scan',
201      ruleId: 'inject-browser-script',
202      target: url,
203    }, () => page.evaluate(browserScript));
204    let serializedGroups = [];
205    results = await profileFindingsAsync(profile, {
206      engine: 'browser',
207      phase: 'scan',
208      ruleId: 'browser-scan',
209      target: url,
210    }, async () => {
211      serializedGroups = await page.evaluate(() => {
212        if (!window.impeccableDetect) return [];
213        return window.impeccableDetect({ decorate: false, serialize: true });
214      });
215      return serializedGroups.flatMap(({ findings }) =>
216        findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '' }))
217      );
218    });
219    const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
220    results.push(...visualFindings);
221  } finally {
222    await profileStepAsync(profile, {
223      engine: 'browser',
224      phase: 'load',
225      ruleId: 'close-page',
226      target: url,
227    }, () => page.close().catch(() => {}));
228    if (!externalBrowser) {
229      await profileStepAsync(profile, {
230        engine: 'browser',
231        phase: 'load',
232        ruleId: 'close-browser',
233        target: url,
234      }, () => browser.close());
235    }
236  }
237  return filterByProviders(results.map(f => {
238    const item = finding(f.id, url, f.snippet);
239    if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
240    return item;
241  }), options.providers);
242}
243 
244async function createBrowserDetector(options = {}) {
245  let puppeteer;
246  try {
247    puppeteer = await import('puppeteer');
248  } catch {
249    throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
250  }
251  const launchArgs = options.launchArgs || (process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : []);
252  const browser = options.browser || await puppeteer.default.launch({
253    headless: options.headless ?? true,
254    args: launchArgs,
255  });
256  const ownsBrowser = !options.browser;
257  const defaults = {
258    waitUntil: options.waitUntil || 'load',
259    settleMs: Number.isFinite(options.settleMs) ? options.settleMs : 100,
260    viewport: options.viewport || { width: 1280, height: 800 },
261  };
262  return {
263    browser,
264    async detectUrl(url, scanOptions = {}) {
265      return detectUrl(url, {
266        ...defaults,
267        ...scanOptions,
268        browser,
269      });
270    },
271    async close() {
272      if (ownsBrowser) await browser.close().catch(() => {});
273    },
274  };
275}
276 
277export { runVisualContrastFallback, detectUrl, createBrowserDetector };
278