similarbuild 0.1.0

package/templates/skills/sb-review-checks/scripts/lib/anti-patterns.mjs

@@ -0,0 +1,379 @@
+// anti-patterns.mjs — Pure detection functions for the canon visual anti-patterns
+// from `<plugin>/memory/anti-patterns.md` (the "bootstrap" list). Each check is
+// a pure function `(ctx) => violations[]` with no I/O and no global state, so
+// every rule is unit-testable in isolation.
+//
+// `ctx` shape:
+//   { html: string, css: string, $: cheerio.CheerioAPI, preset: 'wp-elementor'|'shopify-section', styleBlocks: [{ css, htmlOffset }] }
+//
+// Each violation:
+//   { group: 'anti-pattern', id: '#1', location: '...', issue: '...',
+//     candidateFix: '...', severity: 'high'|'medium'|'low' }
+//
+// The candidateFix string is the contract with sb-build-{wp,shopify}: it must be
+// specific enough to apply programmatically. A generic "improve specificity" is
+// useless — a builder can't act on it. Every fix names the selector, attribute,
+// or property it wants changed.
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 }
+
+export function sortBySeverity(violations) {
+  return [...violations].sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    return sa - sb
+  })
+}
+
+// Find which line `index` falls on in `source`. 1-based.
+export function lineOf(source, index) {
+  if (index < 0) return 0
+  let line = 1
+  for (let i = 0; i < index && i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) line++
+  }
+  return line
+}
+
+// Walk all CSS rule blocks `selector { ...decls... }` from the combined CSS.
+// Returns { selector, body, openIndex } per rule (open brace index in source).
+// Skips at-rules' own bodies but recurses into them so nested rules are visited.
+export function walkRules(css) {
+  const rules = []
+  walk(css, 0, css.length, rules)
+  return rules
+
+  function walk(src, start, end, out) {
+    let i = start
+    while (i < end) {
+      // Comment
+      if (src[i] === '/' && src[i + 1] === '*') {
+        const close = src.indexOf('*/', i + 2)
+        if (close === -1) return
+        i = close + 2
+        continue
+      }
+      // Whitespace
+      if (/\s/.test(src[i])) { i++; continue }
+      // At-rule
+      if (src[i] === '@') {
+        const semi = findStmtEnd(src, i, end)
+        if (semi.kind === 'block') {
+          // recurse into the at-rule body so nested rules are picked up
+          walk(src, semi.bodyStart + 1, semi.bodyEnd, out)
+          i = semi.bodyEnd + 1
+        } else {
+          i = semi.semiIndex + 1
+        }
+        continue
+      }
+      // Rule
+      const open = findOpenBrace(src, i, end)
+      if (open === -1) return
+      const close = findMatchingBrace(src, open)
+      if (close === -1) return
+      const selector = src.slice(i, open).trim()
+      const body = src.slice(open + 1, close)
+      out.push({ selector, body, openIndex: open })
+      i = close + 1
+    }
+  }
+}
+
+function findOpenBrace(src, start, end) {
+  for (let i = start; i < end; i++) {
+    if (src[i] === '{') return i
+    if (src[i] === ';') return -1 // declaration-without-rule (shouldn't happen at this level)
+  }
+  return -1
+}
+
+function findMatchingBrace(src, openIndex) {
+  let depth = 1
+  for (let i = openIndex + 1; i < src.length; i++) {
+    if (src[i] === '/' && src[i + 1] === '*') {
+      const close = src.indexOf('*/', i + 2)
+      if (close === -1) return -1
+      i = close + 1
+      continue
+    }
+    if (src[i] === '{') depth++
+    else if (src[i] === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return -1
+}
+
+function findStmtEnd(src, start, end) {
+  for (let i = start; i < end; i++) {
+    if (src[i] === '{') {
+      const close = findMatchingBrace(src, i)
+      return { kind: 'block', bodyStart: i, bodyEnd: close }
+    }
+    if (src[i] === ';') return { kind: 'stmt', semiIndex: i }
+  }
+  return { kind: 'stmt', semiIndex: end - 1 }
+}
+
+// ─── #1 — 100vh in WP/Elementor (clips on mobile) ───────────────────────────
+export function check100vh(ctx) {
+  if (ctx.preset !== 'wp-elementor') return []
+  const violations = []
+  for (const block of ctx.styleBlocks) {
+    let m
+    const re = /\b100vh\b/g
+    while ((m = re.exec(block.css)) !== null) {
+      violations.push({
+        group: 'anti-pattern',
+        id: '#1',
+        location: `style block line ${lineOf(block.css, m.index)}`,
+        issue: '100vh inside Elementor clips on mobile (browser chrome eats viewport)',
+        candidateFix: 'replace `100vh` with `aspect-ratio: 9 / 16; max-height: 700px` on the hero container',
+        severity: 'high',
+      })
+    }
+  }
+  return violations
+}
+
+// ─── #2 — <img> with height: 100% in hero (theme overrides win) ────────────
+// Heuristic: any `<img>` element under a class containing "hero" with an
+// inline `style` declaring `height: 100%` (or `height:100%`). Catches the
+// most common variant where the build tries to fill a hero box with <img>.
+export function checkImgHeight100Hero(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('img[style]').each((_, el) => {
+    const $el = $(el)
+    const style = String($el.attr('style') || '')
+    if (!/height\s*:\s*100\s*%/i.test(style)) return
+    if (!hasHeroAncestor($, $el)) return
+    const cls = $el.attr('class') || ''
+    violations.push({
+      group: 'anti-pattern',
+      id: '#2',
+      location: cls ? `<img class="${cls}">` : '<img> with inline height:100%',
+      issue: '<img> with height:100% in hero — Elementor injects `img { height: auto !important }` and clobbers it',
+      candidateFix: 'replace the <img> hero with a `background-image` on the hero container; keep alt text on a sibling visually-hidden <img> if needed',
+      severity: 'high',
+    })
+  })
+  return violations
+}
+
+function hasHeroAncestor($, $el) {
+  let cur = $el
+  for (let i = 0; i < 8 && cur.length; i++) {
+    const cls = String(cur.attr('class') || '').toLowerCase()
+    if (/(^|[\s_-])hero([\s_-]|$)/.test(cls)) return true
+    cur = cur.parent()
+  }
+  return false
+}
+
+// ─── #3 — Round-number opacity (likely guessed, not measured) ───────────────
+// Flags `opacity: 0.3 | 0.5 | 0.7` (the round eyeballs). Other values are
+// probably real readings or token-derived. Severity low — this is a nudge.
+export function checkRoundOpacity(ctx) {
+  const violations = []
+  for (const block of ctx.styleBlocks) {
+    const re = /opacity\s*:\s*(0?\.[357])\b/g
+    let m
+    while ((m = re.exec(block.css)) !== null) {
+      violations.push({
+        group: 'anti-pattern',
+        id: '#3',
+        location: `style block line ${lineOf(block.css, m.index)}`,
+        issue: `opacity: ${m[1]} looks eyeballed — round values rarely match the source`,
+        candidateFix: `verify the exact alpha against inspection.tokens; if measured, leave a comment \`/* alpha from inspection */\` so the next reviewer doesn't re-flag it`,
+        severity: 'low',
+      })
+    }
+  }
+  return violations
+}
+
+// ─── #4 — `a { color: inherit }` in scoped CSS ──────────────────────────────
+// Inherits whatever ancestor color leaked through. Specifically problematic
+// when the ancestor is themed (button color via parent, link color via theme).
+export function checkAnchorColorInherit(ctx) {
+  const violations = []
+  for (const rule of walkRules(ctx.css)) {
+    const sel = rule.selector
+    // Match selectors that target <a> as the rightmost simple selector
+    if (!/(?:^|[\s>+~])a(?:[.:#\[][^,\s]*)?\s*$/.test(sel)) continue
+    if (!/color\s*:\s*inherit\b/i.test(rule.body)) continue
+    violations.push({
+      group: 'anti-pattern',
+      id: '#4',
+      location: `selector \`${sel}\``,
+      issue: '`a { color: inherit }` clobbers brand color when the ancestor is themed',
+      candidateFix: `replace \`color: inherit\` in \`${sel}\` with a literal hex from inspection.tokens (e.g. \`color: #d8112a\`)`,
+      severity: 'medium',
+    })
+  }
+  return violations
+}
+
+// ─── #5 — <button> decorative without defensive specificity ─────────────────
+// Heuristic: a rule whose selector ends in `.{token}` (single class) and styles
+// background/color/font on a button-shaped pattern (selector contains "button"
+// or "btn" or "cta"). Real defensive specificity is ancestor-chained, e.g.
+// `.scope .scope__cta.scope__cta`.
+export function checkButtonNoChain(ctx) {
+  const violations = []
+  for (const rule of walkRules(ctx.css)) {
+    const sel = rule.selector
+    if (!/(button|btn|cta)/i.test(sel)) continue
+    // Defensive specificity = ancestor present (descendant combinator) OR class chain
+    const looksDefensive = /\s/.test(sel.trim()) || /\.[\w-]+\.[\w-]+/.test(sel)
+    if (looksDefensive) continue
+    // Must actually style something theme will fight over
+    if (!/(background|color|font-)/i.test(rule.body)) continue
+    violations.push({
+      group: 'anti-pattern',
+      id: '#5',
+      location: `selector \`${sel}\``,
+      issue: 'button-like selector without ancestor scope or class-chain — theme `.elementor *` rules will win',
+      candidateFix: `chain the scope as ancestor: rewrite \`${sel}\` as \`.{scope} ${sel}${sel}\` (double the modifier class to raise specificity past .elementor *)`,
+      severity: 'high',
+    })
+  }
+  return violations
+}
+
+// ─── #5b — `!important` without ancestor prefix ─────────────────────────────
+// Useless on its own — theme rules carry both ancestor specificity AND
+// !important. The build needs both too.
+export function checkImportantNoAncestor(ctx) {
+  const violations = []
+  for (const rule of walkRules(ctx.css)) {
+    const body = rule.body
+    if (!/!\s*important/i.test(body)) continue
+    const sel = rule.selector
+    // Ancestor present means: there's whitespace combinator inside the selector
+    // (excluding child/+/~ — those still satisfy "has ancestor" if anything is
+    // before the rightmost simple selector). Concretely: split on ',' and check
+    // each branch has an internal combinator.
+    const branches = splitTopLevel(sel, ',').map((s) => s.trim()).filter(Boolean)
+    const allHaveAncestor = branches.every((b) => /[\s>+~]/.test(b.replace(/^[.#:\[\w-]+/, '')))
+    if (allHaveAncestor) continue
+    violations.push({
+      group: 'anti-pattern',
+      id: '#5b',
+      location: `selector \`${sel}\``,
+      issue: '`!important` without an ancestor in the selector — theme has both ancestor + !important so this loses anyway',
+      candidateFix: `prefix \`${sel}\` with the scope as ancestor: rewrite as \`.{scope} ${sel}\` so the chained-scope specificity matches the theme's ancestor-prefixed !important rules`,
+      severity: 'high',
+    })
+  }
+  return violations
+}
+
+function splitTopLevel(str, ch) {
+  const out = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i]
+    if (c === '(' || c === '[') depth++
+    else if (c === ')' || c === ']') depth--
+    else if (c === ch && depth === 0) {
+      out.push(str.slice(start, i))
+      start = i + 1
+    }
+  }
+  out.push(str.slice(start))
+  return out
+}
+
+// ─── #6 — Overlap-image modeled as a sibling box on the wrapper ─────────────
+// Should be a `::before` on the SECTION. Heuristic: a `::before` rule whose
+// selector targets a wrapper class (matches /wrap|wrapper|container/) AND the
+// declaration uses `position: absolute` with edge insets that look full-bleed.
+export function checkOverlapBoxInWrapper(ctx) {
+  const violations = []
+  for (const rule of walkRules(ctx.css)) {
+    if (!/::before\b/.test(rule.selector)) continue
+    if (!/(wrap|wrapper|container|inner)/i.test(rule.selector)) continue
+    if (!/position\s*:\s*absolute/i.test(rule.body)) continue
+    if (!/(inset|top|right|bottom|left)\s*:/i.test(rule.body)) continue
+    violations.push({
+      group: 'anti-pattern',
+      id: '#6',
+      location: `selector \`${rule.selector}\``,
+      issue: '`::before` on a wrapper instead of the section — overlap bands belong to the section so they sit behind the image, not the column',
+      candidateFix: `move the \`::before\` from \`${rule.selector}\` to the section selector (the outermost scope element); set \`position: relative\` on the section and \`z-index: -1\` on the ::before`,
+      severity: 'medium',
+    })
+  }
+  return violations
+}
+
+// ─── #8 — Inline SVG impostor where a raster <img> belongs ─────────────────
+// Heuristic: large viewBox (any dim ≥ 400) + ≥2 `<path>` children + nearby
+// "product" / "photo" / hero context. SVGs that came from the source as icons
+// (small viewBox) are fine — those are the legitimate use case.
+export function checkSvgRasterImpostor(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('svg').each((_, el) => {
+    const $el = $(el)
+    const vb = String($el.attr('viewBox') || '').trim()
+    const m = vb.match(/-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?\s+(-?\d+(?:\.\d+)?)\s+(-?\d+(?:\.\d+)?)/)
+    if (!m) return
+    const w = parseFloat(m[1])
+    const h = parseFloat(m[2])
+    if (Math.max(w, h) < 400) return
+    const paths = $el.find('path').length
+    if (paths < 2) return
+    const ctxLower = (
+      String($el.attr('class') || '') + ' ' +
+      String($el.parent().attr('class') || '') + ' ' +
+      String($el.closest('section,figure,article').attr('class') || '')
+    ).toLowerCase()
+    if (!/(product|photo|hero|image|card|variant)/.test(ctxLower)) return
+    violations.push({
+      group: 'anti-pattern',
+      id: '#8',
+      location: `<svg viewBox="${vb}"> with ${paths} <path> children`,
+      issue: 'inline SVG where a real raster image belongs — SVGs reproduced from photos look "off" and miss real-world detail',
+      candidateFix: `replace this <svg> with an <img src="{assetsMap[originalUrl].localPath}" alt="..." loading="lazy"> using the actual asset from sb-extract-assets`,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// Public registry — orchestrator iterates this so adding a check is one line.
+export const ANTI_PATTERN_CHECKS = [
+  check100vh,
+  checkImgHeight100Hero,
+  checkRoundOpacity,
+  checkAnchorColorInherit,
+  checkButtonNoChain,
+  checkImportantNoAncestor,
+  checkOverlapBoxInWrapper,
+  checkSvgRasterImpostor,
+]
+
+export function runAntiPatterns(ctx) {
+  const out = []
+  for (const fn of ANTI_PATTERN_CHECKS) {
+    try {
+      out.push(...fn(ctx))
+    } catch (err) {
+      out.push({
+        group: 'anti-pattern',
+        id: fn.name || 'unknown',
+        location: 'check',
+        issue: `check threw: ${err.message}`,
+        candidateFix: 'inspect the input file — it may be malformed HTML/CSS',
+        severity: 'low',
+      })
+    }
+  }
+  return sortBySeverity(out)
+}

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

@@ -0,0 +1,115 @@
+// cross-reference.mjs — Optional layer that combines this skill's static
+// violations with `compareDiffs` from sb-compare-visual. The contract:
+//
+//   - When a violation's `area`/`location` overlaps a structuredDiff's `area`,
+//     and that diff is severity high, escalate the violation to high (or keep
+//     it high) and tag it with `correlatedDiff`.
+//   - Add a synthetic violation for each high-severity diff that no static
+//     check caught — the user still needs to know about it.
+//
+// This is what makes sb-review-checks the engine of the auto-correct loop:
+// the orchestrator can take the prioritized output and feed it straight back
+// to sb-build-{wp,shopify} as `fixHints`, ranked by both static rules AND
+// the actual visual delta.
+//
+// Pure function, no I/O. Tested in isolation.
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 }
+
+// Map a structured diff's `area` to substrings we look for in violation
+// locations. Loose, on purpose — better to over-correlate (LLM filters) than
+// miss obvious matches.
+const AREA_HINTS = {
+  h1: ['h1', '<h1'],
+  h2: ['h2', '<h2'],
+  h3: ['h3', '<h3'],
+  body: ['body', 'paragraph'],
+  button: ['button', 'btn', 'cta'],
+  container: ['container', 'wrapper', 'section'],
+  images: ['img', 'image', '<img', 'svg'],
+  geometry: ['hero', 'section', 'overflow', 'height'],
+}
+
+function locationMatchesArea(location, area) {
+  if (!location || !area) return false
+  const hints = AREA_HINTS[area] || [area]
+  const lc = String(location).toLowerCase()
+  return hints.some((h) => lc.includes(h))
+}
+
+function violationKey(v) {
+  return `${v.group}|${v.id}|${v.location}`
+}
+
+export function applyCrossReference(violations, compareDiffs) {
+  if (!Array.isArray(compareDiffs) || compareDiffs.length === 0) {
+    return [...violations]
+  }
+  const highDiffs = compareDiffs.filter((d) => d && d.severity === 'high')
+  if (highDiffs.length === 0) return [...violations]
+
+  const annotated = violations.map((v) => {
+    const matches = highDiffs.filter((d) => locationMatchesArea(v.location, d.area))
+    if (matches.length === 0) return { ...v }
+    return {
+      ...v,
+      severity: 'high',
+      correlatedDiff: {
+        area: matches[0].area,
+        issue: matches[0].issue,
+        deltaPx: matches[0].deltaPx,
+      },
+    }
+  })
+
+  // Diffs that no violation covered → synthesize one. The orchestrator wants
+  // the full picture in one list, not "look at violations AND compareDiffs."
+  const seenAreas = new Set(
+    annotated
+      .filter((v) => v.correlatedDiff)
+      .map((v) => v.correlatedDiff.area),
+  )
+  for (const diff of highDiffs) {
+    if (seenAreas.has(diff.area)) continue
+    annotated.push({
+      group: 'visual-diff',
+      id: `diff-${diff.area}`,
+      location: diff.area,
+      issue: diff.issue,
+      candidateFix: synthesizeFixFromDiff(diff),
+      severity: 'high',
+      correlatedDiff: { area: diff.area, issue: diff.issue, deltaPx: diff.deltaPx },
+    })
+  }
+
+  return annotated
+}
+
+// When a visual diff has no static violation backing it, generate a fix
+// instruction directly from the diff's measured values.
+function synthesizeFixFromDiff(diff) {
+  const { area, live, build, deltaPx } = diff
+  if (live != null && build != null && deltaPx != null) {
+    if (typeof live === 'string' && typeof build === 'string') {
+      return `update \`${area}\` from build value \`${build}\` to live-page value \`${live}\` (delta ${deltaPx}px)`
+    }
+    return `update \`${area}\` from build value ${build}px to live-page value ${live}px (delta ${deltaPx}px)`
+  }
+  if (live != null && build != null) {
+    return `update \`${area}\` from build value \`${build}\` to live-page value \`${live}\``
+  }
+  return `align \`${area}\` with the live-page value — see compareDiffs entry for measurements`
+}
+
+export function sortByPriority(violations) {
+  // High severity first; within severity, correlated-with-diff items rank
+  // ahead of non-correlated. Stable beyond that.
+  return [...violations].sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    if (sa !== sb) return sa - sb
+    const ca = a.correlatedDiff ? 0 : 1
+    const cb = b.correlatedDiff ? 0 : 1
+    return ca - cb
+  })
+}