similarbuild 0.1.0

package/templates/skills/sb-review-checks/scripts/tests/test-cross-reference.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// test-cross-reference.mjs — Pure tests for the cross-reference layer. No deps.
+
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const LIB = resolve(here, '..', 'lib', 'cross-reference.mjs')
+const { applyCrossReference, sortByPriority } = await import(LIB)
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+// ─── applyCrossReference ────────────────────────────────────────────────────
+
+test('returns input unchanged when compareDiffs is null/undefined/[]', () => {
+  const input = [{ severity: 'medium', location: 'x', issue: 'y', candidateFix: 'z', group: 'a11y', id: 'foo' }]
+  assert.deepEqual(applyCrossReference(input, null), input)
+  assert.deepEqual(applyCrossReference(input, undefined), input)
+  assert.deepEqual(applyCrossReference(input, []), input)
+})
+
+test('returns input unchanged when no diff is severity high', () => {
+  const violations = [{ severity: 'medium', location: '<button>', issue: 'x', candidateFix: 'y', group: 'a11y', id: 'a' }]
+  const diffs = [{ area: 'button', severity: 'low', issue: 'x', live: 1, build: 2 }]
+  assert.deepEqual(applyCrossReference(violations, diffs), violations)
+})
+
+test('escalates a violation that overlaps a high-severity diff', () => {
+  const violations = [{ severity: 'medium', location: '<button class="cta">', issue: 'x', candidateFix: 'y', group: 'a11y', id: 'a11y-button-type' }]
+  const diffs = [{ area: 'button', severity: 'high', issue: 'background-color drift', deltaPx: null }]
+  const out = applyCrossReference(violations, diffs)
+  assert.equal(out.length, 1)
+  assert.equal(out[0].severity, 'high')
+  assert.ok(out[0].correlatedDiff)
+  assert.equal(out[0].correlatedDiff.area, 'button')
+})
+
+test('does NOT escalate a non-overlapping violation', () => {
+  const violations = [{ severity: 'medium', location: '<img alt="">', issue: 'x', candidateFix: 'y', group: 'a11y', id: 'a11y-img-alt' }]
+  const diffs = [{ area: 'button', severity: 'high', issue: 'color drift' }]
+  const out = applyCrossReference(violations, diffs)
+  assert.equal(out.length, 2) // one synthetic added for uncorrelated diff
+  // Original violation unchanged
+  const orig = out.find((v) => v.id === 'a11y-img-alt')
+  assert.equal(orig.severity, 'medium')
+  assert.ok(!orig.correlatedDiff)
+})
+
+test('synthesizes a violation for uncorrelated high-severity diffs', () => {
+  const violations = []
+  const diffs = [{ area: 'h1', severity: 'high', issue: 'font-size drift', live: '27px', build: '24px', deltaPx: -3 }]
+  const out = applyCrossReference(violations, diffs)
+  assert.equal(out.length, 1)
+  assert.equal(out[0].group, 'visual-diff')
+  assert.equal(out[0].id, 'diff-h1')
+  assert.equal(out[0].severity, 'high')
+  assert.match(out[0].candidateFix, /27px/)
+  assert.match(out[0].candidateFix, /24px/)
+})
+
+test('synthetic fix mentions live and build values', () => {
+  const out = applyCrossReference([], [
+    { area: 'button', severity: 'high', issue: 'bg drift', live: '#d8112a', build: '#d82a11' },
+  ])
+  assert.match(out[0].candidateFix, /#d8112a/)
+  assert.match(out[0].candidateFix, /#d82a11/)
+})
+
+test('one violation can correlate to a high diff and skip the synthetic for that area', () => {
+  const violations = [{ severity: 'medium', location: '<button class="cta">', issue: 'x', candidateFix: 'y', group: 'a11y', id: 'a11y-button-type' }]
+  const diffs = [
+    { area: 'button', severity: 'high', issue: 'bg color drift' },
+    { area: 'h1', severity: 'high', issue: 'size drift', live: '27px', build: '24px', deltaPx: -3 },
+  ]
+  const out = applyCrossReference(violations, diffs)
+  // 1 correlated + 1 synthetic for h1
+  assert.equal(out.length, 2)
+  const correlated = out.find((v) => v.correlatedDiff?.area === 'button')
+  assert.ok(correlated)
+  const synth = out.find((v) => v.group === 'visual-diff' && v.id === 'diff-h1')
+  assert.ok(synth)
+})
+
+test('correlated violations preserve their group and candidateFix', () => {
+  const violations = [{ severity: 'medium', location: '<button class="cta">', issue: 'x', candidateFix: 'add type="button"', group: 'a11y', id: 'a11y-button-type' }]
+  const diffs = [{ area: 'button', severity: 'high', issue: 'bg drift' }]
+  const out = applyCrossReference(violations, diffs)
+  assert.equal(out[0].group, 'a11y')
+  assert.equal(out[0].candidateFix, 'add type="button"')
+})
+
+// ─── sortByPriority ─────────────────────────────────────────────────────────
+
+test('sortByPriority: high before medium before low', () => {
+  const out = sortByPriority([
+    { severity: 'low' }, { severity: 'high' }, { severity: 'medium' },
+  ])
+  assert.deepEqual(out.map((v) => v.severity), ['high', 'medium', 'low'])
+})
+
+test('sortByPriority: correlated comes first within same severity', () => {
+  const out = sortByPriority([
+    { severity: 'high', id: 'a' },
+    { severity: 'high', id: 'b', correlatedDiff: { area: 'button' } },
+    { severity: 'high', id: 'c' },
+  ])
+  assert.equal(out[0].id, 'b')
+})
+
+test('sortByPriority: stable for equal entries', () => {
+  const out = sortByPriority([
+    { severity: 'medium', id: '1' },
+    { severity: 'medium', id: '2' },
+    { severity: 'medium', id: '3' },
+  ])
+  assert.deepEqual(out.map((v) => v.id), ['1', '2', '3'])
+})
+
+test('sortByPriority: returns a new array (no mutation)', () => {
+  const input = [{ severity: 'low' }, { severity: 'high' }]
+  const out = sortByPriority(input)
+  assert.notEqual(out, input)
+  assert.equal(input[0].severity, 'low') // unchanged
+})
+
+// ─── Area-hint coverage ─────────────────────────────────────────────────────
+
+test('locationMatchesArea via h1 hint', () => {
+  const out = applyCrossReference(
+    [{ severity: 'low', location: '<h1> heading', issue: 'x', candidateFix: 'y', group: 'a11y', id: 'foo' }],
+    [{ area: 'h1', severity: 'high', issue: 'size' }],
+  )
+  assert.equal(out[0].severity, 'high')
+})
+
+test('locationMatchesArea via images hint (svg)', () => {
+  const out = applyCrossReference(
+    [{ severity: 'medium', location: '<svg viewBox="0 0 600 600">', issue: 'x', candidateFix: 'y', group: 'anti-pattern', id: '#8' }],
+    [{ area: 'images', severity: 'high', issue: 'count differs' }],
+  )
+  assert.equal(out[0].severity, 'high')
+})
+
+test('locationMatchesArea via geometry hint (hero)', () => {
+  const out = applyCrossReference(
+    [{ severity: 'medium', location: 'hero <img src="x">', issue: 'x', candidateFix: 'y', group: 'performance', id: 'perf-hero-preload' }],
+    [{ area: 'geometry', severity: 'high', issue: 'overflow' }],
+  )
+  assert.equal(out[0].severity, 'high')
+})
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)

package/templates/skills/sb-review-checks/scripts/tests/test-design-quality.mjs

@@ -0,0 +1,493 @@
+#!/usr/bin/env node
+// test-design-quality.mjs — Pure-function tests for the 12 a11y/perf/web checks.
+// All these checks rely on cheerio for HTML parsing — gracefully skipped when
+// cheerio isn't installed.
+
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const LIB = resolve(here, '..', 'lib', 'design-quality.mjs')
+const {
+  checkButtonAria,
+  checkImgAlt,
+  checkHeadingHierarchy,
+  checkButtonType,
+  checkNavSemantic,
+  checkImgLazy,
+  checkHeroPreload,
+  checkFontDisplay,
+  checkFetchpriorityHero,
+  checkSrcsetResponsive,
+  checkModalDialog,
+  checkPreconnectFonts,
+  runDesignQuality,
+  findHeroCssBackgroundImage,
+  findHeroImgWithConfidence,
+} = await import(LIB)
+
+let cheerio = null
+try { cheerio = await import('cheerio') } catch {}
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function skip(name, reason) {
+  process.stdout.write(`ok - ${name} # SKIP ${reason}\n`)
+  passed++
+}
+
+function ctxFromHtml(html, preset = 'wp-elementor') {
+  if (!cheerio) return null
+  return { html, css: '', $: cheerio.load(html), preset, styleBlocks: [] }
+}
+
+function ctxFromHtmlAndCss(html, css, preset = 'wp-elementor') {
+  if (!cheerio) return null
+  return { html, css, $: cheerio.load(html), preset, styleBlocks: [{ css, htmlOffset: 0 }] }
+}
+
+if (!cheerio) {
+  skip('all design-quality tests', 'cheerio not installed')
+  process.stdout.write(`\n${passed} passed (skipped)\n`)
+  process.exit(0)
+}
+
+// ─── a11y-button-aria ───────────────────────────────────────────────────────
+
+test('a11y-button-aria: flags icon-only button without aria-label', () => {
+  const ctx = ctxFromHtml('<button class="menu"><svg></svg></button>')
+  const v = checkButtonAria(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'a11y-button-aria')
+  assert.equal(v[0].severity, 'high')
+  assert.match(v[0].candidateFix, /aria-label="Open menu"/)
+})
+
+test('a11y-button-aria: flags emoji-glyph button (☰)', () => {
+  const ctx = ctxFromHtml('<button>☰</button>')
+  const v = checkButtonAria(ctx)
+  assert.equal(v.length, 1)
+})
+
+test('a11y-button-aria: passes when aria-label present', () => {
+  const ctx = ctxFromHtml('<button aria-label="Open menu"><svg></svg></button>')
+  assert.equal(checkButtonAria(ctx).length, 0)
+})
+
+test('a11y-button-aria: passes for buttons with text', () => {
+  const ctx = ctxFromHtml('<button>Submit</button>')
+  assert.equal(checkButtonAria(ctx).length, 0)
+})
+
+test('a11y-button-aria: passes when inner img has alt', () => {
+  const ctx = ctxFromHtml('<button><img src="x" alt="Cart"></button>')
+  assert.equal(checkButtonAria(ctx).length, 0)
+})
+
+// ─── a11y-img-alt ───────────────────────────────────────────────────────────
+
+test('a11y-img-alt: flags img without alt', () => {
+  const ctx = ctxFromHtml('<img src="hero.jpg">')
+  const v = checkImgAlt(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'a11y-img-alt')
+  assert.equal(v[0].severity, 'high')
+})
+
+test('a11y-img-alt: passes with empty alt', () => {
+  const ctx = ctxFromHtml('<img src="x.jpg" alt="">')
+  assert.equal(checkImgAlt(ctx).length, 0)
+})
+
+test('a11y-img-alt: passes with descriptive alt', () => {
+  const ctx = ctxFromHtml('<img src="x.jpg" alt="Hero product">')
+  assert.equal(checkImgAlt(ctx).length, 0)
+})
+
+// ─── a11y-heading-hierarchy ─────────────────────────────────────────────────
+
+test('a11y-heading-hierarchy: flags multiple h1', () => {
+  const ctx = ctxFromHtml('<h1>A</h1><p>x</p><h1>B</h1>')
+  const v = checkHeadingHierarchy(ctx)
+  assert.ok(v.some((d) => /multiple <h1>/.test(d.issue)))
+})
+
+test('a11y-heading-hierarchy: flags level skip h2 → h4', () => {
+  const ctx = ctxFromHtml('<h2>A</h2><h4>B</h4>')
+  const v = checkHeadingHierarchy(ctx)
+  assert.ok(v.some((d) => /skip/.test(d.issue)))
+})
+
+test('a11y-heading-hierarchy: flags first heading h3 (no h1/h2 above)', () => {
+  const ctx = ctxFromHtml('<h3>Section</h3>')
+  const v = checkHeadingHierarchy(ctx)
+  assert.ok(v.some((d) => /starts at <h3>/.test(d.issue)))
+})
+
+test('a11y-heading-hierarchy: passes for clean h1 → h2 → h3', () => {
+  const ctx = ctxFromHtml('<h1>A</h1><h2>B</h2><h3>C</h3>')
+  assert.equal(checkHeadingHierarchy(ctx).length, 0)
+})
+
+test('a11y-heading-hierarchy: empty doc emits no violation', () => {
+  const ctx = ctxFromHtml('<p>no headings</p>')
+  assert.equal(checkHeadingHierarchy(ctx).length, 0)
+})
+
+// ─── a11y-button-type ───────────────────────────────────────────────────────
+
+test('a11y-button-type: flags button without type', () => {
+  const ctx = ctxFromHtml('<button>Click me</button>')
+  const v = checkButtonType(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'a11y-button-type')
+  assert.match(v[0].candidateFix, /type="button"/)
+})
+
+test('a11y-button-type: passes type=button', () => {
+  const ctx = ctxFromHtml('<button type="button">Click</button>')
+  assert.equal(checkButtonType(ctx).length, 0)
+})
+
+test('a11y-button-type: passes type=submit (intentional)', () => {
+  const ctx = ctxFromHtml('<button type="submit">Submit</button>')
+  assert.equal(checkButtonType(ctx).length, 0)
+})
+
+// ─── a11y-nav-semantic ──────────────────────────────────────────────────────
+
+test('a11y-nav-semantic: flags <div class="nav"> with multiple links', () => {
+  const ctx = ctxFromHtml('<div class="nav"><a href="/">Home</a><a href="/x">X</a></div>')
+  const v = checkNavSemantic(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'a11y-nav-semantic')
+  assert.match(v[0].candidateFix, /<nav class="nav" aria-label="Main">/)
+})
+
+test('a11y-nav-semantic: passes when wrapped in <nav>', () => {
+  const ctx = ctxFromHtml('<nav><div class="nav-inner"><a href="/">A</a><a href="/b">B</a></div></nav>')
+  assert.equal(checkNavSemantic(ctx).length, 0)
+})
+
+test('a11y-nav-semantic: ignores footer nav', () => {
+  const ctx = ctxFromHtml('<div class="footer-nav"><a href="/">A</a><a href="/b">B</a></div>')
+  assert.equal(checkNavSemantic(ctx).length, 0)
+})
+
+// ─── perf-img-lazy ──────────────────────────────────────────────────────────
+
+test('perf-img-lazy: flags non-hero img without loading', () => {
+  // First img is the hero; second should be flagged
+  const ctx = ctxFromHtml('<img src="hero.jpg" alt="hero"><img src="other.jpg" alt="other">')
+  const v = checkImgLazy(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'perf-img-lazy')
+  assert.match(v[0].location, /other\.jpg/)
+})
+
+test('perf-img-lazy: passes when loading=lazy', () => {
+  const ctx = ctxFromHtml('<img src="hero.jpg"><img src="other.jpg" loading="lazy">')
+  assert.equal(checkImgLazy(ctx).length, 0)
+})
+
+test('perf-img-lazy: respects fetchpriority=high as hero indicator', () => {
+  const ctx = ctxFromHtml('<img src="other.jpg" loading="lazy"><img src="hero.jpg" fetchpriority="high">')
+  // Hero is the second one (fetchpriority=high). First is non-hero with lazy → ok.
+  assert.equal(checkImgLazy(ctx).length, 0)
+})
+
+// ─── perf-hero-preload ──────────────────────────────────────────────────────
+
+test('perf-hero-preload: flags missing preload', () => {
+  const ctx = ctxFromHtml('<img src="hero.jpg" alt="hero">')
+  const v = checkHeroPreload(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'perf-hero-preload')
+  assert.match(v[0].candidateFix, /<link rel="preload"/)
+})
+
+test('perf-hero-preload: passes when matching preload exists', () => {
+  const ctx = ctxFromHtml('<link rel="preload" as="image" href="hero.jpg"><img src="hero.jpg">')
+  assert.equal(checkHeroPreload(ctx).length, 0)
+})
+
+// Pattern #25 — CSS background-image hero detection.
+
+test('perf-hero-preload: flags hero CSS background-image without preload', () => {
+  const html = '<div class="ai-hero"><img src="logo.png" alt="brand logo"></div>'
+  const css = '.ai-hero { background-image: url("photo.jpg"); height: 480px; }'
+  const ctx = ctxFromHtmlAndCss(html, css)
+  const v = checkHeroPreload(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'perf-hero-preload')
+  assert.match(v[0].location, /background-image/)
+  assert.match(v[0].candidateFix, /preload" as="image" href="photo\.jpg"/)
+})
+
+test('perf-hero-preload: passes when hero CSS bg has matching preload', () => {
+  const html = '<link rel="preload" as="image" href="photo.jpg"><div class="ai-hero"><img src="logo.png" alt="logo"></div>'
+  const css = '.ai-hero { background-image: url("photo.jpg"); }'
+  const ctx = ctxFromHtmlAndCss(html, css)
+  assert.equal(checkHeroPreload(ctx).length, 0)
+})
+
+test('perf-hero-preload: hero CSS-bg + LOGO <img> wide → flag bg only, NOT logo', () => {
+  const html = '<div class="ai-hero"><img src="logo.png" alt="brand" width="1200"></div>'
+  const css = '.ai-hero { background-image: url("hero-photo.jpg"); }'
+  const ctx = ctxFromHtmlAndCss(html, css)
+  const v = checkHeroPreload(ctx)
+  assert.equal(v.length, 1)
+  assert.match(v[0].location, /background-image/)
+  // Make sure the candidateFix names the bg URL, not the logo
+  assert.match(v[0].candidateFix, /hero-photo\.jpg/)
+  assert.doesNotMatch(v[0].candidateFix, /logo\.png/)
+})
+
+test('perf-hero-preload: skips bare first <img> when no signal (logo case)', () => {
+  // No CSS bg, no fetchpriority, no "hero"-named class/src/alt, no width
+  // → treated as fallback tier and skipped (Pattern #25 prevents flagging logos)
+  const ctx = ctxFromHtml('<img src="brand.png" alt="brand">')
+  assert.equal(checkHeroPreload(ctx).length, 0)
+})
+
+test('perf-hero-preload: <img> ≥800px width without preload → flag (original case)', () => {
+  const ctx = ctxFromHtml('<img src="banner.jpg" alt="brand" width="1200">')
+  const v = checkHeroPreload(ctx)
+  assert.equal(v.length, 1)
+  assert.match(v[0].candidateFix, /banner\.jpg/)
+})
+
+test('perf-hero-preload: BEM modifier rule (.foo__bar) is NOT mistaken for hero scope', () => {
+  // BEM-modifier element with bg-image is NOT the root scope. Fall through
+  // to <img>; the lone logo with no signal lands in fallback tier → skip.
+  const html = '<img src="logo.png" alt="logo">'
+  const css = '.ai-hero__overlay { background-image: url("texture.png"); }'
+  const ctx = ctxFromHtmlAndCss(html, css)
+  assert.equal(checkHeroPreload(ctx).length, 0)
+})
+
+test('perf-hero-preload: descendant selector (.foo .bar) is NOT mistaken for hero scope', () => {
+  const html = '<img src="logo.png" alt="logo">'
+  const css = '.ai-hero .inner { background-image: url("inner.jpg"); }'
+  const ctx = ctxFromHtmlAndCss(html, css)
+  assert.equal(checkHeroPreload(ctx).length, 0)
+})
+
+// findHeroCssBackgroundImage helper — direct unit tests.
+
+test('findHeroCssBackgroundImage: detects single root-class rule with bg URL', () => {
+  const r = findHeroCssBackgroundImage('.hero { background-image: url("a.jpg"); }')
+  assert.deepEqual(r, { selector: '.hero', url: 'a.jpg' })
+})
+
+test('findHeroCssBackgroundImage: handles double-quoted, single-quoted, unquoted URLs', () => {
+  assert.equal(findHeroCssBackgroundImage(`.h { background-image: url('x.jpg'); }`).url, 'x.jpg')
+  assert.equal(findHeroCssBackgroundImage(`.h { background-image: url(x.jpg); }`).url, 'x.jpg')
+  assert.equal(findHeroCssBackgroundImage(`.h { background: url("x.jpg") center/cover; }`).url, 'x.jpg')
+})
+
+test('findHeroCssBackgroundImage: rejects descendant combinator', () => {
+  assert.equal(findHeroCssBackgroundImage('.hero .child { background-image: url("a.jpg"); }'), null)
+})
+
+test('findHeroCssBackgroundImage: rejects __ BEM modifier', () => {
+  assert.equal(findHeroCssBackgroundImage('.hero__overlay { background-image: url("a.jpg"); }'), null)
+})
+
+test('findHeroCssBackgroundImage: rejects @media wrapper rules', () => {
+  // The simple regex doesn't open into @media — still returns null gracefully
+  const css = '@media (min-width: 600px) { .hero { background-image: url("a.jpg"); } }'
+  // The naive matcher might match, but the inner selector is fine — at-rule
+  // wrapper has braces around it. The first matched block has selector
+  // "@media (min-width: 600px)" and body containing ".hero { ... }". Skipped
+  // by the @-rule guard. Then the body is left as-is and re-scanned — but
+  // the regex stops after first non-overlapping matches. Behavior: skip.
+  // Confirm we don't blow up; inside-bracket bg may or may not be picked up
+  // depending on regex quirks. Acceptable as long as we don't crash.
+  const r = findHeroCssBackgroundImage(css)
+  // It MAY pick up the inner .hero rule; either way, output must be null or
+  // an object with `.hero` selector — never crash.
+  assert.ok(r === null || (r && typeof r.selector === 'string'))
+})
+
+test('findHeroCssBackgroundImage: returns null when no bg URL present', () => {
+  assert.equal(findHeroCssBackgroundImage('.hero { color: red; }'), null)
+})
+
+test('findHeroCssBackgroundImage: comma-separated selectors — uses first selector', () => {
+  const r = findHeroCssBackgroundImage('.hero, .banner { background-image: url("a.jpg"); }')
+  assert.deepEqual(r, { selector: '.hero', url: 'a.jpg' })
+})
+
+test('findHeroCssBackgroundImage: pseudo-class on root scope is allowed', () => {
+  const r = findHeroCssBackgroundImage('.hero:hover { background-image: url("a.jpg"); }')
+  assert.deepEqual(r, { selector: '.hero:hover', url: 'a.jpg' })
+})
+
+// findHeroImgWithConfidence — confidence tiering.
+
+test('findHeroImgWithConfidence: explicit fetchpriority="high"', () => {
+  const $ = cheerio.load('<img src="a.jpg"><img src="b.jpg" fetchpriority="high">')
+  const r = findHeroImgWithConfidence($)
+  assert.equal(r.confidence, 'explicit')
+  assert.equal(r.el.attr('src'), 'b.jpg')
+})
+
+test('findHeroImgWithConfidence: hero-ancestor class', () => {
+  const $ = cheerio.load('<img src="a.png"><div class="hero"><img src="b.jpg"></div>')
+  const r = findHeroImgWithConfidence($)
+  assert.equal(r.confidence, 'hero-ancestor')
+  assert.equal(r.el.attr('src'), 'b.jpg')
+})
+
+test('findHeroImgWithConfidence: src/alt name-match (hero|banner|cover)', () => {
+  const $ = cheerio.load('<img src="logo.png"><img src="banner.jpg" alt="x">')
+  const r = findHeroImgWithConfidence($)
+  assert.equal(r.confidence, 'name-match')
+  assert.equal(r.el.attr('src'), 'banner.jpg')
+})
+
+test('findHeroImgWithConfidence: declared width >= 800', () => {
+  const $ = cheerio.load('<img src="a.png"><img src="b.jpg" width="1200">')
+  const r = findHeroImgWithConfidence($)
+  assert.equal(r.confidence, 'wide')
+  assert.equal(r.el.attr('src'), 'b.jpg')
+})
+
+test('findHeroImgWithConfidence: bare first <img> falls back', () => {
+  const $ = cheerio.load('<img src="a.png">')
+  const r = findHeroImgWithConfidence($)
+  assert.equal(r.confidence, 'fallback')
+})
+
+// ─── perf-font-display ──────────────────────────────────────────────────────
+
+test('perf-font-display: flags Google Fonts without display=swap', () => {
+  const ctx = ctxFromHtml('<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter">')
+  const v = checkFontDisplay(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'perf-font-display')
+  assert.match(v[0].candidateFix, /&display=swap/)
+})
+
+test('perf-font-display: passes when display=swap present', () => {
+  const ctx = ctxFromHtml('<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter&display=swap">')
+  assert.equal(checkFontDisplay(ctx).length, 0)
+})
+
+// ─── perf-fetchpriority-hero (shopify only) ─────────────────────────────────
+
+test('perf-fetchpriority-hero: flags hero without fetchpriority on shopify', () => {
+  const ctx = ctxFromHtml('<img src="hero.jpg" alt="hero">', 'shopify-section')
+  const v = checkFetchpriorityHero(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'perf-fetchpriority-hero')
+})
+
+test('perf-fetchpriority-hero: silent on wp-elementor preset', () => {
+  const ctx = ctxFromHtml('<img src="hero.jpg" alt="hero">', 'wp-elementor')
+  assert.equal(checkFetchpriorityHero(ctx).length, 0)
+})
+
+// ─── web-srcset-responsive ──────────────────────────────────────────────────
+
+test('web-srcset-responsive: flags wide img without srcset', () => {
+  const ctx = ctxFromHtml('<img src="big.jpg" width="1200">')
+  const v = checkSrcsetResponsive(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'web-srcset-responsive')
+})
+
+test('web-srcset-responsive: passes when srcset present', () => {
+  const ctx = ctxFromHtml('<img src="big.jpg" width="1200" srcset="big.jpg 1x, big2x.jpg 2x">')
+  assert.equal(checkSrcsetResponsive(ctx).length, 0)
+})
+
+test('web-srcset-responsive: ignores narrow img', () => {
+  const ctx = ctxFromHtml('<img src="thumb.jpg" width="200">')
+  assert.equal(checkSrcsetResponsive(ctx).length, 0)
+})
+
+test('web-srcset-responsive: ignores img without explicit width', () => {
+  const ctx = ctxFromHtml('<img src="x.jpg">')
+  assert.equal(checkSrcsetResponsive(ctx).length, 0)
+})
+
+// ─── web-modal-dialog ───────────────────────────────────────────────────────
+
+test('web-modal-dialog: flags <div class="modal">', () => {
+  const ctx = ctxFromHtml('<div class="modal">Hi</div>')
+  const v = checkModalDialog(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'web-modal-dialog')
+  assert.match(v[0].candidateFix, /<dialog/)
+})
+
+test('web-modal-dialog: flags <div role="dialog">', () => {
+  const ctx = ctxFromHtml('<div role="dialog">x</div>')
+  assert.equal(checkModalDialog(ctx).length, 1)
+})
+
+test('web-modal-dialog: passes <dialog>', () => {
+  const ctx = ctxFromHtml('<dialog class="modal-x">x</dialog>')
+  assert.equal(checkModalDialog(ctx).length, 0)
+})
+
+// ─── web-preconnect-fonts ───────────────────────────────────────────────────
+
+test('web-preconnect-fonts: flags Google Fonts without preconnect', () => {
+  const ctx = ctxFromHtml('<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter&display=swap">')
+  const v = checkPreconnectFonts(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, 'web-preconnect-fonts')
+  assert.match(v[0].candidateFix, /preconnect/)
+})
+
+test('web-preconnect-fonts: passes when both preconnects exist', () => {
+  const ctx = ctxFromHtml(
+    '<link rel="preconnect" href="https://fonts.googleapis.com">' +
+    '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>' +
+    '<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter&display=swap">',
+  )
+  assert.equal(checkPreconnectFonts(ctx).length, 0)
+})
+
+test('web-preconnect-fonts: silent when no Google Fonts loaded', () => {
+  const ctx = ctxFromHtml('<link rel="stylesheet" href="local.css">')
+  assert.equal(checkPreconnectFonts(ctx).length, 0)
+})
+
+// ─── runDesignQuality: aggregator ───────────────────────────────────────────
+
+test('runDesignQuality: aggregates and sorts by severity', () => {
+  const ctx = ctxFromHtml(`
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter">
+    <button class="menu"><svg></svg></button>
+    <img src="hero.jpg">
+    <img src="other.jpg">
+  `)
+  const v = runDesignQuality(ctx)
+  assert.ok(v.length >= 4, `expected >=4 violations, got ${v.length}`)
+  // High-severity first (img-alt + button-aria are both high)
+  assert.equal(v[0].severity, 'high')
+})
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)