@icjia/contrastcap 0.1.0

package/src/tools/checkElementContrast.js

@@ -0,0 +1,99 @@
+import { CONFIG } from '../config.js';
+import { validateUrl } from '../utils/urlValidate.js';
+import { withPage } from '../browser.js';
+import { sampleBackgroundColor } from '../engine/pixelSampler.js';
+import {
+  contrastRatio,
+  requiredRatio,
+  parseRgbString,
+  rgbToHex,
+} from '../engine/contrastCalc.js';
+import { suggestFix } from '../engine/colorSuggest.js';
+import { isLargeText } from '../utils/largeText.js';
+import { formatElementResult } from '../utils/formatResults.js';
+import { withAuditTimeout } from './auditPage.js';
+
+function rgbStringToHex(rgbStr) {
+  const { r, g, b } = parseRgbString(rgbStr);
+  return rgbToHex(r, g, b);
+}
+
+export async function checkElementContrast(params) {
+  const level = params.level || CONFIG.DEFAULT_LEVEL;
+  const selector = params.selector;
+  if (typeof selector !== 'string' || selector.length === 0 || selector.length > CONFIG.SELECTOR_MAX_LEN) {
+    throw new Error('Invalid selector');
+  }
+
+  const validated = await validateUrl(params.url);
+
+  return withAuditTimeout(withPage(async (page) => {
+    await page.goto(validated, {
+      timeout: CONFIG.NAV_TIMEOUT,
+      waitUntil: 'networkidle',
+    }).catch(async (err) => {
+      if (/Timeout/i.test(err.message || '')) {
+        await page.goto(validated, { timeout: CONFIG.NAV_TIMEOUT, waitUntil: 'load' });
+      } else {
+        throw err;
+      }
+    });
+
+    await validateUrl(page.url()); // post-redirect re-check
+
+    const element = await page.$(selector);
+    if (!element) throw new Error('Element not found');
+
+    try {
+      await element.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => {});
+      const box = await element.boundingBox();
+      if (!box || box.width * box.height < 4) {
+        throw new Error('Element has zero size');
+      }
+
+      const meta = await element.evaluate((el) => {
+        const cs = getComputedStyle(el);
+        return {
+          color:      cs.color,
+          fontSize:   cs.fontSize,
+          fontWeight: cs.fontWeight,
+          text:       (el.textContent || '').trim(),
+        };
+      });
+
+      const fgPx = parseFloat(meta.fontSize);
+      const large = isLargeText(fgPx, meta.fontWeight);
+      const required = requiredRatio(large, level);
+
+      const fgHex = rgbStringToHex(meta.color);
+      const bg = await sampleBackgroundColor(page, element, box, meta.color);
+      const ratio = contrastRatio(fgHex, bg.hex);
+      const pass = ratio >= required;
+
+      const entry = {
+        selector,
+        text:        meta.text,
+        ratio,
+        required,
+        pass,
+        fontSize:    meta.fontSize,
+        fontWeight:  meta.fontWeight,
+        isLargeText: large,
+        foreground:  fgHex,
+        background:  bg.hex,
+        backgroundSource: bg.source,
+      };
+      if (!pass) entry.suggestion = suggestFix(fgHex, bg.hex, large, level);
+      if (pass && (ratio < required + CONFIG.MARGINAL_DELTA)) {
+        entry.note = `Ratio within ${CONFIG.MARGINAL_DELTA} of threshold — marginal.`;
+      }
+      if (bg.highVariance && !entry.note) {
+        entry.note = 'Background sampled from gradient or image — may vary at other positions.';
+      }
+
+      return formatElementResult({ url: page.url(), wcagLevel: level, entry });
+    } finally {
+      await element.dispose().catch(() => {});
+    }
+  }));
+}

package/src/tools/checkPageContrast.js

@@ -0,0 +1,26 @@
+import { CONFIG } from '../config.js';
+import { auditPage, withAuditTimeout } from './auditPage.js';
+import { formatPageResult } from '../utils/formatResults.js';
+
+export async function checkPageContrast(params) {
+  const level = params.level || CONFIG.DEFAULT_LEVEL;
+
+  const {
+    finalUrl,
+    axePassCount,
+    resolvedPassCount,
+    failures,
+    warnings,
+    skippedCount,
+  } = await withAuditTimeout(auditPage(params.url, level));
+
+  return formatPageResult({
+    url: finalUrl,
+    wcagLevel: level,
+    axePassCount,
+    resolvedPassCount,
+    failures,
+    warnings,
+    skippedCount,
+  });
+}

package/src/tools/getContrastSummary.js

@@ -0,0 +1,26 @@
+import { CONFIG } from '../config.js';
+import { auditPage, withAuditTimeout } from './auditPage.js';
+import { formatSummaryResult } from '../utils/formatResults.js';
+
+export async function getContrastSummary(params) {
+  const level = params.level || CONFIG.DEFAULT_LEVEL;
+
+  const {
+    finalUrl,
+    axePassCount,
+    resolvedPassCount,
+    failures,
+    warnings,
+    skippedCount,
+  } = await withAuditTimeout(auditPage(params.url, level));
+
+  return formatSummaryResult({
+    url: finalUrl,
+    wcagLevel: level,
+    axePassCount,
+    resolvedPassCount,
+    failCount: failures.length,
+    warningCount: warnings.length,
+    skippedCount,
+  });
+}

package/src/utils/formatResults.js

@@ -0,0 +1,106 @@
+function truncate(str, max) {
+  if (typeof str !== 'string') return str;
+  return str.length > max ? str.slice(0, max - 1) + '…' : str;
+}
+
+function round(n, decimals = 2) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return n;
+  const f = 10 ** decimals;
+  return Math.round(n * f) / f;
+}
+
+function shapeEntry(item) {
+  const entry = {
+    selector:         truncate(item.selector, 120),
+    text:             truncate(item.text || '', 40),
+    ratio:            round(item.ratio, 2),
+    required:         item.required,
+    level:            item.level,
+    fontSize:         item.fontSize,
+    fontWeight:       item.fontWeight,
+    isLargeText:      !!item.isLargeText,
+    foreground:       item.foreground,
+    background:       item.background,
+    backgroundSource: item.backgroundSource || 'computed',
+  };
+  if (item.suggestion) entry.suggestion = item.suggestion;
+  if (item.note) entry.note = item.note;
+  return entry;
+}
+
+export function formatPageResult({
+  url,
+  wcagLevel,
+  axePassCount,
+  resolvedPassCount,
+  skippedCount,
+  failures,
+  warnings,
+}) {
+  const pass = axePassCount + resolvedPassCount;
+  const total = pass + failures.length + warnings.length + skippedCount;
+
+  return {
+    url,
+    timestamp: new Date().toISOString(),
+    wcag_level: wcagLevel,
+    summary: {
+      total,
+      pass,
+      fail: failures.length,
+      warning: warnings.length,
+      skipped: skippedCount,
+    },
+    failures: failures.map(shapeEntry),
+    warnings: warnings.map(shapeEntry),
+  };
+}
+
+export function formatSummaryResult({
+  url,
+  wcagLevel,
+  axePassCount,
+  resolvedPassCount,
+  failCount,
+  warningCount,
+  skippedCount,
+}) {
+  const pass = axePassCount + resolvedPassCount;
+  const total = pass + failCount + warningCount + skippedCount;
+  return {
+    url,
+    timestamp: new Date().toISOString(),
+    wcag_level: wcagLevel,
+    counts: {
+      total_elements_checked: total,
+      pass,
+      fail: failCount,
+      warning: warningCount,
+      skipped: skippedCount,
+    },
+  };
+}
+
+export function formatElementResult({ url, wcagLevel, entry }) {
+  const out = {
+    url,
+    timestamp: new Date().toISOString(),
+    wcag_level: wcagLevel,
+    selector: entry.selector,
+    text: truncate(entry.text || '', 40),
+    ratio: round(entry.ratio, 2),
+    required: entry.required,
+    pass: entry.pass,
+    fontSize: entry.fontSize,
+    fontWeight: entry.fontWeight,
+    isLargeText: !!entry.isLargeText,
+    foreground: entry.foreground,
+    background: entry.background,
+    backgroundSource: entry.backgroundSource || 'computed',
+  };
+  if (entry.suggestion) out.suggestion = entry.suggestion;
+  if (entry.note) out.note = entry.note;
+  return out;
+}
+
+export const _test = { truncate, round, shapeEntry };

package/src/utils/largeText.js

@@ -0,0 +1,14 @@
+/**
+ * Large-text classification per WCAG 2.1.
+ *
+ * `fontSizePx` MUST be a resolved px value — read via
+ * `getComputedStyle(el).fontSize` in the browser. Do not try to parse em/rem/pt
+ * server-side: em is relative to the parent's computed size and cannot be
+ * resolved without the element context.
+ */
+export function isLargeText(fontSizePx, fontWeight) {
+  const px = typeof fontSizePx === 'number' ? fontSizePx : parseFloat(fontSizePx);
+  const weight = parseInt(fontWeight, 10) || 400;
+  if (!Number.isFinite(px)) return false;
+  return px >= 24 || (px >= 18.66 && weight >= 700);
+}

package/src/utils/sanitizeError.js

@@ -0,0 +1,37 @@
+import { log } from '../config.js';
+
+const KNOWN = [
+  'Blocked URL scheme',
+  'Blocked URL',
+  'Invalid URL',
+  'Element not found',
+  'Element has zero size',
+  'Audit timed out',
+  'Audit queue full',
+  'Page navigation timed out',
+];
+
+export function sanitizeError(err) {
+  const msg = err?.message || 'Unknown error';
+
+  if (KNOWN.some(k => msg.startsWith(k))) return msg;
+
+  if (msg.includes('ECONNREFUSED') || msg.includes('ERR_CONNECTION_REFUSED')) {
+    return 'Could not connect to URL';
+  }
+  if (msg.includes('ETIMEDOUT') || msg.includes('ETIMEOUT') || msg.includes('ERR_TIMED_OUT')) {
+    return 'Connection timed out';
+  }
+  if (msg.includes('ERR_NAME_NOT_RESOLVED') || msg.includes('ENOTFOUND')) {
+    return 'Could not resolve hostname';
+  }
+  if (msg.includes('net::ERR_')) {
+    return 'Network error';
+  }
+  if (msg.toLowerCase().startsWith('invalid url')) {
+    return 'Invalid URL';
+  }
+
+  log('error', `Unhandled error: ${msg}`);
+  return 'Audit failed';
+}

package/src/utils/urlValidate.js

@@ -0,0 +1,35 @@
+import { lookup } from 'dns/promises';
+import { CONFIG } from '../config.js';
+
+async function isBlockedIp(hostname) {
+  if (CONFIG.LOCALHOST_HOSTS.includes(hostname)) return false;
+  try {
+    const { address } = await lookup(hostname);
+    const normalized = address.startsWith('::ffff:') ? address.slice(7) : address;
+    return CONFIG.BLOCKED_IP_PREFIXES.some(p => normalized.startsWith(p));
+  } catch {
+    return true; // DNS failure → fail closed
+  }
+}
+
+export async function validateUrl(url) {
+  if (typeof url !== 'string' || url.length === 0 || url.length > CONFIG.MAX_URL_LENGTH) {
+    throw new Error('Invalid URL');
+  }
+
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new Error('Invalid URL'); }
+
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('Blocked URL scheme');
+  }
+  if (CONFIG.BLOCKED_HOSTNAMES.includes(parsed.hostname)) {
+    throw new Error('Blocked URL');
+  }
+  if (await isBlockedIp(parsed.hostname)) {
+    throw new Error('Blocked URL');
+  }
+  return parsed.href;
+}
+
+export const _test = { isBlockedIp };