similarbuild 0.1.0

package/templates/skills/sb-review-checks/scripts/review-checks.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// review-checks.mjs — Audit a built fragment (HTML or Liquid) against three
+// independent groups of checks and emit a prioritized list of violations whose
+// `candidateFix` strings are specific enough for sb-build-{wp,shopify} to
+// apply programmatically as `fixHints`. This script is the engine of the
+// auto-correct loop.
+//
+// Determinism only — no chromium, no network. cheerio is lazy-imported so
+// --help and arg validation work without it installed.
+//
+// Outputs JSON to stdout AND writes report.json into --output-dir.
+// Exit codes: 0=ok, 1=script error, 2=invalid args, 3=violations (med/high).
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runAntiPatterns } from './lib/anti-patterns.mjs'
+import { runDesignQuality } from './lib/design-quality.mjs'
+import { applyCrossReference, sortByPriority } from './lib/cross-reference.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SKILL_ROOT = resolve(HERE, '..')
+
+const HELP = `
+review-checks.mjs — Audit an HTML/Liquid fragment for anti-patterns, design
+quality, and visual-diff correlations. Emits a prioritized fix list.
+
+Required:
+  --file <path>             HTML or Liquid file to audit.
+  --preset <name>           wp-elementor | shopify-section
+  --output-dir <dir>        Directory for report.json.
+
+Optional:
+  --compare-diffs <path>    JSON from sb-compare-visual (cross-reference layer).
+  --memory-dir <dir>        Override <plugin>/memory location. Auto-detects
+                            \`~/.claude/similarbuild-memory\` and the bundled
+                            references/ fallback otherwise.
+  --help                    Show this message.
+
+Exit codes: 0=ok (zero or only-low violations), 1=script error,
+2=invalid args, 3=violations found (medium/high severity).
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-review-checks] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(msg) {
+  process.stderr.write(`[sb-review-checks] ${msg}\n`)
+}
+
+const { values } = parseArgs({
+  options: {
+    file: { type: 'string' },
+    preset: { type: 'string' },
+    'output-dir': { type: 'string' },
+    'compare-diffs': { type: 'string' },
+    'memory-dir': { type: 'string' },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+if (!values.file) fail('missing --file')
+if (!values.preset) fail('missing --preset')
+if (!values['output-dir']) fail('missing --output-dir')
+
+const VALID_PRESETS = new Set(['wp-elementor', 'shopify-section'])
+if (!VALID_PRESETS.has(values.preset)) {
+  fail(`--preset must be one of: ${[...VALID_PRESETS].join(', ')} (got "${values.preset}")`)
+}
+
+const FILE = resolve(values.file)
+const PRESET = values.preset
+const OUTPUT_DIR = resolve(values['output-dir'])
+const COMPARE_DIFFS = values['compare-diffs'] ? resolve(values['compare-diffs']) : null
+const MEMORY_DIR = values['memory-dir'] ? resolve(values['memory-dir']) : null
+
+async function exists(path) {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Extract every <style>…</style> block. Liquid files often embed them inside
+// `{% style %}` or `{% stylesheet %}` tags too — capture both. Returned objects
+// keep the original substring so line numbers reported by checks point at the
+// CSS-block-relative line, which is more actionable than file-relative.
+function extractStyleBlocks(source) {
+  const blocks = []
+  const patterns = [
+    /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi,
+    /\{%\s*style\s*%\}([\s\S]*?)\{%\s*endstyle\s*%\}/gi,
+    /\{%\s*stylesheet\s*%\}([\s\S]*?)\{%\s*endstylesheet\s*%\}/gi,
+  ]
+  for (const re of patterns) {
+    let m
+    while ((m = re.exec(source)) !== null) {
+      blocks.push({ css: m[1], htmlOffset: m.index })
+    }
+  }
+  return blocks
+}
+
+// Liquid → HTML-ish: cheerio parses HTML; Liquid expressions like {{ x }} and
+// {% if %}…{% endif %} are foreign syntax that confuses no-op-tolerant parsers.
+// We strip Liquid expressions to whitespace before parsing so cheerio sees
+// well-formed HTML structure. The CSS path uses the raw source so {% style %}
+// blocks are still picked up by extractStyleBlocks above.
+function liquidToHtmlish(source) {
+  return source
+    .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+    .replace(/\{%[\s\S]*?%\}/g, ' ')
+}
+
+async function loadComparisonDiffs(path) {
+  if (!path) return null
+  if (!(await exists(path))) {
+    log(`--compare-diffs not found: ${path} — skipping cross-reference`)
+    return null
+  }
+  try {
+    const raw = await readFile(path, 'utf8')
+    const json = JSON.parse(raw)
+    if (Array.isArray(json)) return json
+    if (Array.isArray(json.structuredDiffs)) return json.structuredDiffs
+    log(`--compare-diffs JSON has no structuredDiffs[] — skipping cross-reference`)
+    return null
+  } catch (err) {
+    log(`could not parse --compare-diffs: ${err.message} — skipping cross-reference`)
+    return null
+  }
+}
+
+// Resolve which memory directory to consult. Order:
+//   1. --memory-dir flag
+//   2. ~/.claude/similarbuild-memory
+//   3. <skill-root>/references (always exists; bundled fallback)
+async function resolveMemoryDir() {
+  if (MEMORY_DIR) return { dir: MEMORY_DIR, source: 'flag' }
+  const home = process.env.HOME || process.env.USERPROFILE
+  if (home) {
+    const candidate = join(home, '.claude', 'similarbuild-memory')
+    if (await exists(candidate)) return { dir: candidate, source: 'home' }
+  }
+  return { dir: join(SKILL_ROOT, 'references'), source: 'bundled' }
+}
+
+function counts(violations) {
+  const c = { high: 0, medium: 0, low: 0 }
+  for (const v of violations) c[v.severity] = (c[v.severity] || 0) + 1
+  return c
+}
+
+async function main() {
+  if (!(await exists(FILE))) fail(`--file not found: ${FILE}`)
+  await mkdir(OUTPUT_DIR, { recursive: true })
+
+  const reportPath = join(OUTPUT_DIR, 'report.json')
+
+  let cheerio
+  try {
+    cheerio = await import('cheerio')
+  } catch (err) {
+    process.stderr.write(
+      `[sb-review-checks] missing dependency 'cheerio': ${err?.message || err}\n` +
+        `Install with: npm i cheerio\n`,
+    )
+    process.exit(1)
+  }
+
+  log(`reading ${FILE} (preset=${PRESET})`)
+  const source = await readFile(FILE, 'utf8')
+  const looksLikeLiquid = /(\{%|\{\{)/.test(source)
+  const htmlForParse = looksLikeLiquid ? liquidToHtmlish(source) : source
+
+  const $ = cheerio.load(htmlForParse, { decodeEntities: false })
+  const styleBlocks = extractStyleBlocks(source)
+  const css = styleBlocks.map((b) => b.css).join('\n')
+
+  log(`parsed: ${$('*').length} elements, ${styleBlocks.length} style blocks, ${css.length} chars CSS`)
+
+  const memoryInfo = await resolveMemoryDir()
+  log(`memory dir: ${memoryInfo.dir} (${memoryInfo.source})`)
+
+  const ctx = {
+    html: source,
+    css,
+    $,
+    preset: PRESET,
+    styleBlocks,
+    memoryDir: memoryInfo.dir,
+    memorySource: memoryInfo.source,
+  }
+
+  const antiPatternViolations = runAntiPatterns(ctx)
+  const designQualityViolations = runDesignQuality(ctx)
+  log(`group 1 (anti-patterns): ${antiPatternViolations.length}`)
+  log(`group 2 (design quality): ${designQualityViolations.length}`)
+
+  const compareDiffs = await loadComparisonDiffs(COMPARE_DIFFS)
+  let allViolations = [...antiPatternViolations, ...designQualityViolations]
+  if (compareDiffs) {
+    allViolations = applyCrossReference(allViolations, compareDiffs)
+    log(`group 3 (cross-reference): ${compareDiffs.length} diff(s) considered`)
+  }
+  allViolations = sortByPriority(allViolations)
+
+  const c = counts(allViolations)
+  const passed = c.high === 0 && c.medium === 0
+  const result = {
+    passed,
+    file: FILE,
+    preset: PRESET,
+    violationCount: c,
+    violations: allViolations,
+    inputs: {
+      file: FILE,
+      preset: PRESET,
+      compareDiffs: COMPARE_DIFFS,
+      memoryDir: memoryInfo.dir,
+      memorySource: memoryInfo.source,
+    },
+    report: reportPath,
+  }
+
+  await writeFile(reportPath, JSON.stringify(result, null, 2), 'utf8')
+  process.stdout.write(JSON.stringify(result))
+  process.stdout.write('\n')
+
+  // Exit 3 when there's anything medium or high — that's what the orchestrator
+  // branches on to decide "re-roll the build" vs "ship it." Low-only is OK
+  // because low-severity is "nice to fix later," not a blocker.
+  process.exit(passed ? 0 : 3)
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sb-review-checks] fatal: ${err?.stack || err}\n`)
+  process.exit(1)
+})

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

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+// test-anti-patterns.mjs — Pure-function tests for the 8 anti-pattern checks.
+// CSS-only checks need no deps; HTML-shape checks need cheerio (skipped when
+// missing). No chromium gating, so coverage can go deep.
+
+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', 'anti-patterns.mjs')
+const {
+  check100vh,
+  checkImgHeight100Hero,
+  checkRoundOpacity,
+  checkAnchorColorInherit,
+  checkButtonNoChain,
+  checkImportantNoAncestor,
+  checkOverlapBoxInWrapper,
+  checkSvgRasterImpostor,
+  runAntiPatterns,
+  walkRules,
+  lineOf,
+  sortBySeverity,
+} = 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++
+}
+
+// Build a ctx without cheerio (CSS-only checks).
+function cssCtx({ css = '', preset = 'wp-elementor' } = {}) {
+  return {
+    html: `<style>${css}</style>`,
+    css,
+    $: cheerio ? cheerio.load('<div></div>') : null,
+    preset,
+    styleBlocks: [{ css, htmlOffset: 0 }],
+  }
+}
+
+// Build a ctx with cheerio for HTML-shape checks.
+function htmlCtx({ html = '', css = '', preset = 'wp-elementor' } = {}) {
+  if (!cheerio) return null
+  return {
+    html: `${html}<style>${css}</style>`,
+    css,
+    $: cheerio.load(html),
+    preset,
+    styleBlocks: [{ css, htmlOffset: 0 }],
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+test('walkRules: parses a simple rule', () => {
+  const rules = walkRules('.x { color: red; }')
+  assert.equal(rules.length, 1)
+  assert.equal(rules[0].selector, '.x')
+  assert.match(rules[0].body, /color\s*:\s*red/)
+})
+
+test('walkRules: parses multiple rules', () => {
+  const rules = walkRules('.a { color: red; } .b { color: blue; }')
+  assert.equal(rules.length, 2)
+  assert.equal(rules[0].selector, '.a')
+  assert.equal(rules[1].selector, '.b')
+})
+
+test('walkRules: skips comments', () => {
+  const rules = walkRules('/* comment */ .x { color: red; }')
+  assert.equal(rules.length, 1)
+})
+
+test('walkRules: handles @media at-rule', () => {
+  const rules = walkRules('@media (min-width: 1000px) { .x { color: red; } }')
+  assert.equal(rules.length, 1)
+  assert.equal(rules[0].selector, '.x')
+})
+
+test('walkRules: handles @import statement', () => {
+  const rules = walkRules('@import url("x.css"); .x { color: red; }')
+  assert.equal(rules.length, 1)
+})
+
+test('lineOf: 1-based line numbers', () => {
+  assert.equal(lineOf('a\nb\nc', 0), 1)
+  assert.equal(lineOf('a\nb\nc', 2), 2)
+  assert.equal(lineOf('a\nb\nc', 4), 3)
+})
+
+test('sortBySeverity: high → medium → low', () => {
+  const sorted = sortBySeverity([
+    { severity: 'low' }, { severity: 'high' }, { severity: 'medium' }, { severity: 'high' },
+  ])
+  assert.deepEqual(sorted.map((v) => v.severity), ['high', 'high', 'medium', 'low'])
+})
+
+// ─── #1 — 100vh ─────────────────────────────────────────────────────────────
+
+test('#1: detects 100vh in wp-elementor preset', () => {
+  const ctx = cssCtx({ css: '.hero { height: 100vh; }', preset: 'wp-elementor' })
+  const v = check100vh(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#1')
+  assert.equal(v[0].severity, 'high')
+  assert.match(v[0].candidateFix, /aspect-ratio/)
+})
+
+test('#1: ignores 100vh in shopify preset', () => {
+  const ctx = cssCtx({ css: '.hero { height: 100vh; }', preset: 'shopify-section' })
+  assert.equal(check100vh(ctx).length, 0)
+})
+
+test('#1: zero violations on clean CSS', () => {
+  const ctx = cssCtx({ css: '.hero { aspect-ratio: 9 / 16; max-height: 700px; }' })
+  assert.equal(check100vh(ctx).length, 0)
+})
+
+// ─── #2 — img height 100% in hero (cheerio-gated) ──────────────────────────
+
+if (!cheerio) {
+  skip('#2: detects <img> with height:100% in hero', 'cheerio not installed')
+  skip('#2: ignores <img> outside hero', 'cheerio not installed')
+} else {
+  test('#2: detects <img> with height:100% in hero', () => {
+    const ctx = htmlCtx({
+      html: '<section class="hero"><img src="x.jpg" style="height: 100%; width: 100%"></section>',
+    })
+    const v = checkImgHeight100Hero(ctx)
+    assert.equal(v.length, 1)
+    assert.equal(v[0].id, '#2')
+    assert.equal(v[0].severity, 'high')
+    assert.match(v[0].candidateFix, /background-image/)
+  })
+
+  test('#2: ignores <img> outside hero', () => {
+    const ctx = htmlCtx({
+      html: '<section class="other"><img src="x.jpg" style="height: 100%"></section>',
+    })
+    assert.equal(checkImgHeight100Hero(ctx).length, 0)
+  })
+
+  test('#2: ignores hero img without height:100%', () => {
+    const ctx = htmlCtx({
+      html: '<section class="hero"><img src="x.jpg" style="width: 100%"></section>',
+    })
+    assert.equal(checkImgHeight100Hero(ctx).length, 0)
+  })
+}
+
+// ─── #3 — Round opacity ─────────────────────────────────────────────────────
+
+test('#3: flags opacity 0.5', () => {
+  const ctx = cssCtx({ css: '.x { opacity: 0.5; }' })
+  const v = checkRoundOpacity(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#3')
+  assert.equal(v[0].severity, 'low')
+})
+
+test('#3: flags 0.3 and 0.7', () => {
+  const ctx = cssCtx({ css: '.a { opacity: 0.3; } .b { opacity: 0.7; }' })
+  const v = checkRoundOpacity(ctx)
+  assert.equal(v.length, 2)
+})
+
+test('#3: ignores measured 0.42', () => {
+  const ctx = cssCtx({ css: '.x { opacity: 0.42; }' })
+  assert.equal(checkRoundOpacity(ctx).length, 0)
+})
+
+test('#3: ignores fully opaque/transparent', () => {
+  const ctx = cssCtx({ css: '.a { opacity: 1; } .b { opacity: 0; }' })
+  assert.equal(checkRoundOpacity(ctx).length, 0)
+})
+
+// ─── #4 — color: inherit on <a> ─────────────────────────────────────────────
+
+test('#4: flags `a { color: inherit }`', () => {
+  const ctx = cssCtx({ css: '.scope a { color: inherit; }' })
+  const v = checkAnchorColorInherit(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#4')
+  assert.equal(v[0].severity, 'medium')
+})
+
+test('#4: ignores explicit color', () => {
+  const ctx = cssCtx({ css: '.scope a { color: #d8112a; }' })
+  assert.equal(checkAnchorColorInherit(ctx).length, 0)
+})
+
+test('#4: ignores div { color: inherit }', () => {
+  const ctx = cssCtx({ css: '.scope div { color: inherit; }' })
+  assert.equal(checkAnchorColorInherit(ctx).length, 0)
+})
+
+// ─── #5 — button without chain ──────────────────────────────────────────────
+
+test('#5: flags single-class button selector with bg/color', () => {
+  const ctx = cssCtx({ css: '.cta { background: red; color: white; }' })
+  const v = checkButtonNoChain(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#5')
+  assert.equal(v[0].severity, 'high')
+})
+
+test('#5: passes when scope is ancestor', () => {
+  const ctx = cssCtx({ css: '.scope .cta { background: red; }' })
+  assert.equal(checkButtonNoChain(ctx).length, 0)
+})
+
+test('#5: passes with doubled class chain', () => {
+  const ctx = cssCtx({ css: '.cta.cta { background: red; }' })
+  assert.equal(checkButtonNoChain(ctx).length, 0)
+})
+
+test('#5: ignores non-button selectors', () => {
+  const ctx = cssCtx({ css: '.title { background: red; }' })
+  assert.equal(checkButtonNoChain(ctx).length, 0)
+})
+
+// ─── #5b — !important without ancestor ──────────────────────────────────────
+
+test('#5b: flags single-class !important', () => {
+  const ctx = cssCtx({ css: '.title { font-size: 24px !important; }' })
+  const v = checkImportantNoAncestor(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#5b')
+  assert.equal(v[0].severity, 'high')
+  assert.match(v[0].candidateFix, /\.\{scope\}/)
+})
+
+test('#5b: passes with ancestor descendant combinator', () => {
+  const ctx = cssCtx({ css: '.scope .title { font-size: 24px !important; }' })
+  assert.equal(checkImportantNoAncestor(ctx).length, 0)
+})
+
+test('#5b: ignores rules without !important', () => {
+  const ctx = cssCtx({ css: '.title { font-size: 24px; }' })
+  assert.equal(checkImportantNoAncestor(ctx).length, 0)
+})
+
+// ─── #6 — overlap box on wrapper ────────────────────────────────────────────
+
+test('#6: flags ::before on wrapper class with absolute', () => {
+  const ctx = cssCtx({
+    css: '.story__wrapper::before { content: ""; position: absolute; inset: 30% 0 0 0; background: #f4eee8; }',
+  })
+  const v = checkOverlapBoxInWrapper(ctx)
+  assert.equal(v.length, 1)
+  assert.equal(v[0].id, '#6')
+  assert.match(v[0].candidateFix, /move the/)
+})
+
+test('#6: passes when ::before is on the section', () => {
+  const ctx = cssCtx({
+    css: '.story::before { content: ""; position: absolute; inset: 30% 0 0 0; }',
+  })
+  assert.equal(checkOverlapBoxInWrapper(ctx).length, 0)
+})
+
+test('#6: ignores ::before without position absolute', () => {
+  const ctx = cssCtx({
+    css: '.story__wrapper::before { content: ""; display: block; }',
+  })
+  assert.equal(checkOverlapBoxInWrapper(ctx).length, 0)
+})
+
+// ─── #8 — SVG raster impostor (cheerio-gated) ───────────────────────────────
+
+if (!cheerio) {
+  skip('#8: flags large SVG in product context', 'cheerio not installed')
+  skip('#8: ignores small icon SVG', 'cheerio not installed')
+} else {
+  test('#8: flags large SVG in product context', () => {
+    const ctx = htmlCtx({
+      html: `<div class="product"><svg viewBox="0 0 600 600"><path d="M0 0h600"/><path d="M0 600h600"/></svg></div>`,
+    })
+    const v = checkSvgRasterImpostor(ctx)
+    assert.equal(v.length, 1)
+    assert.equal(v[0].id, '#8')
+    assert.match(v[0].candidateFix, /<img src=/)
+  })
+
+  test('#8: ignores small icon SVG', () => {
+    const ctx = htmlCtx({
+      html: `<div class="icon"><svg viewBox="0 0 24 24"><path d="M0 0h24"/></svg></div>`,
+    })
+    assert.equal(checkSvgRasterImpostor(ctx).length, 0)
+  })
+
+  test('#8: ignores large SVG outside product context', () => {
+    const ctx = htmlCtx({
+      html: `<div class="logo"><svg viewBox="0 0 600 600"><path d="M0 0h600"/><path d="M0 600h600"/></svg></div>`,
+    })
+    assert.equal(checkSvgRasterImpostor(ctx).length, 0)
+  })
+}
+
+// ─── runAntiPatterns: aggregator ────────────────────────────────────────────
+
+if (!cheerio) {
+  skip('runAntiPatterns: aggregates across checks and sorts', 'cheerio not installed')
+} else {
+  test('runAntiPatterns: aggregates across checks and sorts', () => {
+    const ctx = htmlCtx({
+      preset: 'wp-elementor',
+      html: '<section class="hero"><img src="x" style="height: 100%"></section>',
+      css: '.title { font-size: 24px !important; } .hero { height: 100vh; } .x { opacity: 0.5; }',
+    })
+    const v = runAntiPatterns(ctx)
+    // 100vh + img-height + !important + opacity = at least 4
+    assert.ok(v.length >= 4, `expected >=4 violations, got ${v.length}`)
+    // First entries should be high severity
+    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)