similarbuild 0.1.0

package/templates/skills/sb-tweak/scripts/lib/diff-summarizer.mjs

@@ -0,0 +1,140 @@
+// diff-summarizer.mjs — Turn a list of structured `changes` into a short,
+// human-readable diff suitable for surfacing to the user. Also supports
+// fallback line-level diffs when no structured change is provided (e.g. raw
+// text replace via cheerio that doesn't lend itself to a property summary).
+//
+// Pure module, no I/O. Tested in isolation.
+
+// ─── summarizeChanges ────────────────────────────────────────────────────────
+//
+// `changes` shape (each entry):
+//   {
+//     selector: string,            // CSS selector / element identifier
+//     property: string,             // 'font-size' | 'text' | 'alt' | ...
+//     before: string | null,        // current value (null for additive ops)
+//     after:  string | null,        // new value (null for removals)
+//     scope:  'css-rule' | 'attr' | 'text' | 'inline-style' | 'remove-element',
+//     line?:  number,               // 1-based line where the change applies
+//   }
+//
+// Returns a single string with one line per change, formatted for terminal
+// output. Produces stable, idempotent text — running twice on the same input
+// yields the same output. When `changes` is empty, returns the canonical
+// "no changes (already applied)" sentinel.
+
+export function summarizeChanges(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return 'no changes (already applied)'
+  }
+  return changes.map(formatLine).join('\n')
+}
+
+// ─── formatLine ──────────────────────────────────────────────────────────────
+
+export function formatLine(change) {
+  if (!change) return ''
+  const { selector, property, before, after, scope, line } = change
+  const where = line ? ` (line ${line})` : ''
+  const sel = quote(selector)
+
+  switch (scope) {
+    case 'css-rule':
+      return `Changed ${sel} ${property}: ${quote(before)} → ${quote(after)}${where}`
+    case 'inline-style':
+      if (before == null) {
+        return `Added inline ${property}: ${quote(after)} on ${sel}${where}`
+      }
+      return `Changed inline ${property}: ${quote(before)} → ${quote(after)} on ${sel}${where}`
+    case 'attr':
+      if (before == null) {
+        return `Added ${property}=${quote(after)} on ${sel}${where}`
+      }
+      if (after == null) {
+        return `Removed ${property} from ${sel}${where}`
+      }
+      return `Changed ${property} on ${sel}: ${quote(before)} → ${quote(after)}${where}`
+    case 'text':
+      return `Changed text of ${sel}: ${quote(before)} → ${quote(after)}${where}`
+    case 'remove-element':
+      return `Removed element ${sel}${where}`
+    default:
+      // Generic fallback — best-effort.
+      if (before == null && after != null) {
+        return `Set ${property} on ${sel} to ${quote(after)}${where}`
+      }
+      if (before != null && after != null) {
+        return `Changed ${property} on ${sel}: ${quote(before)} → ${quote(after)}${where}`
+      }
+      return `Updated ${sel}${where}`
+  }
+}
+
+function quote(s) {
+  if (s == null) return '∅'
+  const str = String(s)
+  // If already wrapped in backticks/quotes, leave it. Otherwise wrap in
+  // backticks so values with spaces / colons read well.
+  if (/^[`'"].*[`'"]$/.test(str)) return str
+  return '`' + str + '`'
+}
+
+// ─── diffLines ───────────────────────────────────────────────────────────────
+//
+// Last-resort diff for ad-hoc changes that don't carry structured metadata.
+// Returns a small unified-diff-like string with `-` / `+` markers. Truncates
+// long results so the JSON output stays human-readable. Used by the CLI when
+// the change is best described by raw text rather than a property summary.
+
+export function diffLines(beforeText, afterText, opts = {}) {
+  const maxLines = opts.maxLines ?? 20
+  const aLines = String(beforeText ?? '').split('\n')
+  const bLines = String(afterText ?? '').split('\n')
+
+  // Find the first and last differing lines so we don't print 10k unchanged
+  // lines around a 1-line edit.
+  let head = 0
+  while (head < aLines.length && head < bLines.length && aLines[head] === bLines[head]) head++
+  let tailA = aLines.length - 1
+  let tailB = bLines.length - 1
+  while (tailA > head && tailB > head && aLines[tailA] === bLines[tailB]) {
+    tailA--
+    tailB--
+  }
+  if (head > aLines.length - 1 && head > bLines.length - 1) {
+    return '' // identical
+  }
+
+  const out = []
+  out.push(`@@ around line ${head + 1} @@`)
+  for (let i = head; i <= tailA; i++) {
+    if (out.length >= maxLines + 1) {
+      out.push('… (truncated)')
+      return out.join('\n')
+    }
+    out.push(`- ${aLines[i]}`)
+  }
+  for (let i = head; i <= tailB; i++) {
+    if (out.length >= maxLines + 1) {
+      out.push('… (truncated)')
+      return out.join('\n')
+    }
+    out.push(`+ ${bLines[i]}`)
+  }
+  return out.join('\n')
+}
+
+// ─── computeLineFromOffset ───────────────────────────────────────────────────
+//
+// Tiny helper exported so the CLI can resolve byte-offset → 1-based line for
+// CSS-rule edits without duplicating logic. (The element locator already
+// computes lines for DOM elements; this handles the CSS-rule case.)
+
+export function computeLineFromOffset(source, offset) {
+  if (!source || offset == null || offset < 0) return 0
+  let line = 1
+  const limit = Math.min(offset, source.length)
+  for (let i = 0; i < limit; i++) {
+    if (source.charCodeAt(i) === 10) line++
+  }
+  return line
+}

package/templates/skills/sb-tweak/scripts/lib/element-locator.mjs

@@ -0,0 +1,507 @@
+// element-locator.mjs — Given a parsed intent and a cheerio-loaded HTML
+// document, return scored candidate elements ordered best-first. Each candidate
+// names a CSS selector, a snippet for human review, and the *application
+// scope* — where the change should land (text content, attribute, CSS rule, or
+// inline style).
+//
+// Pure module: cheerio is passed in by the caller, not imported here. No I/O.
+// All public functions are testable in isolation.
+
+const TYPE_TO_SELECTOR = {
+  heading: 'h1, h2, h3, h4, h5, h6',
+  subheading: 'h2, h3, h4, h5, h6',
+  image: 'img',
+  button: 'button, [role=button], a.btn, .btn, .cta, .button',
+  text: 'p, .description, .copy',
+  link: 'a[href]',
+  icon: 'svg, i.icon, .icon',
+  background: 'section, .section, [class*="hero"], [class*="bg"]',
+  section: 'section, .section, [class*="hero"], [class*="footer"], [class*="header"]',
+}
+
+const QUALIFIER_HINTS = {
+  hero: ['hero'],
+  footer: ['footer'],
+  header: ['header'],
+  // Ordinal qualifiers don't have class hints — they pick by position.
+}
+
+const ORDINAL_QUALIFIERS = new Set(['first', 'second', 'third', 'last'])
+
+// ─── locateCandidates ────────────────────────────────────────────────────────
+//
+// `intent` shape (from intent-parser.mjs):
+//   { action, target: {type, qualifier?}, property, value, ... }
+// `$` is a cheerio API.
+// `source` is the raw file source (used for line numbers and CSS extraction).
+//
+// Returns an array of candidates, sorted by score (descending):
+//   [{
+//     selector: string,        // CSS selector that uniquely picks the element
+//     snippet: string,         // first ~80 chars of the element's outer HTML
+//     score: number,           // 0..1
+//     line: number,            // 1-based line in the source file
+//     applyTo: 'text' | 'attr' | 'css-rule' | 'inline-style' | 'remove-element',
+//     attrName?: string,       // when applyTo === 'attr'
+//     css?: { selector, ruleStart, ruleEnd, declStart, declEnd, currentValue, blockOffset } // when applyTo === 'css-rule'
+//   }]
+
+export function locateCandidates(intent, $, source) {
+  if (!intent || !intent.target?.type) return []
+  const { target, action, property, value } = intent
+
+  // 1. Find DOM candidates by target.type.
+  const domCands = collectDomCandidates($, target, source)
+  if (domCands.length === 0) return []
+
+  // 2. Score each candidate by:
+  //    - exact qualifier-class hit (e.g. element class contains 'hero'): +0.5
+  //    - ancestor qualifier hit:                                          +0.3
+  //    - ordinal position match:                                          +0.4
+  //    - default (no qualifier needed):                                    +0.2
+  //    - text relevance (if intent.target has a text snippet):             +0.1
+  let scored = scoreCandidates(domCands, target, $)
+
+  // 3. Determine application scope per candidate. Properties like font-size
+  //    prefer CSS-rule edits; alt/src prefer attributes; text changes touch
+  //    the text content; remove drops the element.
+  scored = scored.map((c) =>
+    annotateApplyTo(c, { action, property, value, source }),
+  )
+
+  // 4. For ordinal qualifiers, keep only the matching position(s) and zero
+  //    out the rest.
+  if (target.qualifier && ORDINAL_QUALIFIERS.has(target.qualifier)) {
+    scored = pickByOrdinal(scored, target.qualifier)
+  }
+
+  // 5. Sort: highest score first; stable beyond that.
+  scored.sort((a, b) => b.score - a.score)
+  return scored
+}
+
+// ─── isAmbiguous ──────────────────────────────────────────────────────────────
+//
+// Returns true when the top two candidates are within `threshold` of each
+// other in score AND both are above 0.3 — meaning we have two equally good
+// guesses. This is the signal for "ask the user to pick" (exit code 4).
+
+export function isAmbiguous(candidates, threshold = 0.15) {
+  if (!Array.isArray(candidates) || candidates.length < 2) return false
+  const [a, b] = candidates
+  if (a.score < 0.3) return false
+  return Math.abs(a.score - b.score) <= threshold
+}
+
+// ─── findCssRule ─────────────────────────────────────────────────────────────
+//
+// Scan a CSS source string for a rule whose selector targets the given DOM
+// element (by class chain) and contains a declaration for `property`. Returns
+// the byte offsets of the rule, the declaration, and the current value — so
+// the caller can splice in a new value while preserving the rest of the file.
+//
+// Strategy: walk top-level rules; for each, check if the selector "matches"
+// the element's class set / tag; if so, look for the property declaration.
+// Match is deliberately loose: any class in the selector must be in the
+// element's class set, OR the selector must include the element's tag name.
+
+export function findCssRule(css, classList, tag, property, blockOffset = 0) {
+  if (!css || !property) return null
+  const rules = walkTopLevelRules(css)
+  // Iterate in reverse — later rules have the same or higher specificity
+  // (cascade-wise the last one wins on ties). We want the one whose value
+  // would actually be applied.
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i]
+    if (!selectorMatches(rule.selector, classList, tag)) continue
+    const decl = findDeclaration(rule.body, rule.bodyStart, property)
+    if (decl) {
+      return {
+        selector: rule.selector,
+        ruleStart: blockOffset + rule.start,
+        ruleEnd: blockOffset + rule.end,
+        declStart: blockOffset + decl.start,
+        declEnd: blockOffset + decl.end,
+        currentValue: decl.value,
+        blockOffset,
+      }
+    }
+  }
+  return null
+}
+
+// Find a declaration of `property` inside a rule body. Returns null when not
+// present. Tolerates `!important`. Returned offsets are absolute (i.e. include
+// `bodyStart`) and bracket EXACTLY the value text — no leading whitespace,
+// no trailing terminator.
+export function findDeclaration(body, bodyStart, property) {
+  const re = new RegExp(
+    `(^|[\\s;{])${escapeRegex(property)}\\s*:\\s*([^;}]+?)(\\s*!important)?\\s*([;}])`,
+    'gi',
+  )
+  let m
+  while ((m = re.exec(body)) !== null) {
+    // Compute the offset of m[2] (the value capture) within m[0]. We can't
+    // rely on indexOf because m[2] may equal a substring that appears earlier
+    // in m[0] — instead, walk past the colon and any whitespace.
+    const colonIdx = m[0].indexOf(':')
+    let off = colonIdx + 1
+    while (off < m[0].length && /\s/.test(m[0][off])) off++
+    const valueStart = m.index + off
+    const valueEnd = valueStart + m[2].length
+    return {
+      value: m[2].trim(),
+      important: !!m[3],
+      start: bodyStart + valueStart,
+      end: bodyStart + valueEnd,
+    }
+  }
+  return null
+}
+
+// Walk CSS to collect top-level (non-at-rule) rules. Recurses into at-rules so
+// rules inside `@media` are picked up too. Returns objects with absolute
+// `start` / `end` offsets into the source string and an absolute `bodyStart`
+// that points to the byte AFTER the opening brace.
+export function walkTopLevelRules(css) {
+  const rules = []
+  walk(css, 0, css.length, rules)
+  return rules
+
+  function walk(src, start, end, out) {
+    let i = start
+    while (i < end) {
+      // Skip whitespace and comments
+      if (src[i] === '/' && src[i + 1] === '*') {
+        const close = src.indexOf('*/', i + 2)
+        if (close === -1) return
+        i = close + 2
+        continue
+      }
+      if (/\s/.test(src[i])) { i++; continue }
+
+      // At-rule: recurse into its body if it has one (e.g. @media)
+      if (src[i] === '@') {
+        const stmt = findStmtEnd(src, i, end)
+        if (stmt.kind === 'block') {
+          walk(src, stmt.bodyStart + 1, stmt.bodyEnd, out)
+          i = stmt.bodyEnd + 1
+        } else {
+          i = stmt.semiIndex + 1
+        }
+        continue
+      }
+
+      // Plain 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,
+        start: i,
+        end: close + 1,
+        bodyStart: open + 1,
+      })
+      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
+  }
+  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 }
+}
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// ─── selectorMatches ─────────────────────────────────────────────────────────
+//
+// Loose match: a selector matches an element when at least one of the
+// selector's class tokens is in the element's class list, OR the selector
+// contains the element's tag name. Multi-selector lists (separated by `,`)
+// are handled by splitting and OR-ing.
+
+export function selectorMatches(selector, classList = [], tag = null) {
+  const parts = String(selector || '').split(',').map((s) => s.trim()).filter(Boolean)
+  for (const part of parts) {
+    if (singleSelectorMatches(part, classList, tag)) return true
+  }
+  return false
+}
+
+function singleSelectorMatches(sel, classList, tag) {
+  // Pull class tokens from the selector (.foo, .foo.bar, .foo .bar)
+  const classTokens = []
+  const classRe = /\.([\w-]+)/g
+  let m
+  while ((m = classRe.exec(sel)) !== null) classTokens.push(m[1])
+
+  // If selector has any class tokens, require at least one to be in classList.
+  if (classTokens.length > 0) {
+    const set = new Set(classList)
+    if (classTokens.some((c) => set.has(c))) return true
+    // No class hit — fall through to tag check (covers `h1.title` where the
+    // element has the tag but not the class).
+  }
+
+  // Pull tag name(s) — tokens at start that are bare alpha.
+  const tagRe = /(?:^|\s|>)([a-z][a-z0-9]*)/gi
+  const tags = []
+  let t
+  while ((t = tagRe.exec(sel)) !== null) tags.push(t[1].toLowerCase())
+  if (tag && tags.includes(String(tag).toLowerCase())) return true
+
+  return false
+}
+
+// ─── DOM scanning helpers ─────────────────────────────────────────────────────
+
+function collectDomCandidates($, target, source) {
+  const sel = TYPE_TO_SELECTOR[target.type]
+  if (!sel) return []
+  const out = []
+  $(sel).each((idx, el) => {
+    const $el = $(el)
+    const tag = (el.tagName || el.name || '').toLowerCase()
+    const classes = String($el.attr('class') || '').split(/\s+/).filter(Boolean)
+    const id = $el.attr('id') || null
+    const outerHtml = $.html($el)
+    const snippet = outerHtml.length > 120 ? outerHtml.slice(0, 117) + '...' : outerHtml
+
+    const elementSelector = buildElementSelector(tag, id, classes)
+    const line = lineOfSnippet(source, outerHtml)
+
+    out.push({
+      tag,
+      classes,
+      id,
+      idx,
+      $el,
+      snippet,
+      selector: elementSelector,
+      line,
+      _raw: outerHtml,
+    })
+  })
+  return out
+}
+
+function buildElementSelector(tag, id, classes) {
+  if (id) return `#${id}`
+  if (classes.length > 0) {
+    // Pick a characteristic class — prefer ones that look BEM-y or are longer
+    // (specificity heuristic).
+    const sorted = [...classes].sort((a, b) => b.length - a.length)
+    return `${tag}.${sorted[0]}`
+  }
+  return tag
+}
+
+function lineOfSnippet(source, snippet) {
+  if (!source || !snippet) return 0
+  const head = snippet.slice(0, Math.min(80, snippet.length))
+  const i = source.indexOf(head)
+  if (i < 0) return 0
+  let line = 1
+  for (let j = 0; j < i; j++) {
+    if (source.charCodeAt(j) === 10) line++
+  }
+  return line
+}
+
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+
+function scoreCandidates(candidates, target, $) {
+  const qualifier = target.qualifier
+  const isOrdinal = qualifier && ORDINAL_QUALIFIERS.has(qualifier)
+  const hints = (qualifier && QUALIFIER_HINTS[qualifier]) || null
+
+  return candidates.map((c) => {
+    let score = 0.2 // base — type match alone
+
+    if (hints) {
+      const direct = c.classes.some((cls) =>
+        hints.some((h) => cls.toLowerCase().includes(h)),
+      )
+      if (direct) {
+        score += 0.5
+      } else if (hasAncestorMatchingHint($, c.$el, hints)) {
+        score += 0.3
+      }
+    } else if (isOrdinal) {
+      // Ordinal scoring is handled in pickByOrdinal; here we just make sure
+      // every candidate is in play by bumping score slightly so `isAmbiguous`
+      // isn't tripped before pickByOrdinal narrows.
+      score += 0.4
+    } else {
+      // No qualifier — small bonus when there's only a single match (handled
+      // outside, but we precompute by tagging a uniqueness bump later).
+      score += 0.0
+    }
+
+    // Heading hierarchy bonus: when target.type is 'heading', prefer h1 over
+    // h2/h3 unless qualifier overrides.
+    if (target.type === 'heading' && !qualifier) {
+      if (c.tag === 'h1') score += 0.1
+    }
+
+    return { ...c, score }
+  })
+}
+
+function hasAncestorMatchingHint($, $el, hints) {
+  let cur = $el.parent()
+  for (let i = 0; i < 8 && cur && cur.length; i++) {
+    const cls = String(cur.attr('class') || '').toLowerCase()
+    const tag = String((cur[0] && (cur[0].tagName || cur[0].name)) || '').toLowerCase()
+    for (const h of hints) {
+      if (cls.includes(h) || tag === h) return true
+    }
+    cur = cur.parent()
+  }
+  return false
+}
+
+function pickByOrdinal(scored, qualifier) {
+  if (scored.length === 0) return scored
+  const positions = {
+    first: 0,
+    second: 1,
+    third: 2,
+    last: scored.length - 1,
+  }
+  const idx = positions[qualifier]
+  if (idx === undefined) return scored
+  if (idx < 0 || idx >= scored.length) return scored
+  return scored.map((c, i) => ({
+    ...c,
+    score: i === idx ? Math.min(c.score + 0.4, 1) : 0.05,
+  }))
+}
+
+// ─── annotateApplyTo ─────────────────────────────────────────────────────────
+//
+// Decides where the edit should land for this candidate, given the requested
+// property + action. Adds an `applyTo` field and (when relevant) per-scope
+// metadata. Pure inspection — no edits applied here.
+
+function annotateApplyTo(candidate, ctx) {
+  const { action, property, value, source } = ctx
+
+  // Whole-element removal
+  if (action === 'remove') {
+    return { ...candidate, applyTo: 'remove-element' }
+  }
+
+  // Attribute edits (alt, src, href, id, class, etc.)
+  if (property === 'alt' || property === 'src' || property === 'href' || property === 'id' || property === 'class') {
+    return { ...candidate, applyTo: 'attr', attrName: property }
+  }
+
+  // Text-content edits
+  if (property === 'text') {
+    return { ...candidate, applyTo: 'text' }
+  }
+
+  // CSS property edits (font-size, color, background-color, ...)
+  if (property) {
+    // Prefer modifying an existing CSS rule. The CLI passes the merged CSS
+    // (joined from all <style> blocks) along with per-block offsets so we can
+    // splice the right block.
+    const css = ctx.cssBlocks ? joinBlocks(ctx.cssBlocks) : extractAllCss(source || '')
+    const cssBlocks = ctx.cssBlocks || splitStyleBlocks(source || '')
+    const cssMatch = findCssRuleAcrossBlocks(cssBlocks, candidate.classes, candidate.tag, property)
+    if (cssMatch) {
+      return { ...candidate, applyTo: 'css-rule', css: cssMatch }
+    }
+    return { ...candidate, applyTo: 'inline-style', cssProperty: property }
+  }
+
+  // Fallback: no property — assume text edit when value is text-ish.
+  if (value && value.kind === 'text') {
+    return { ...candidate, applyTo: 'text' }
+  }
+  return { ...candidate, applyTo: 'inline-style', cssProperty: property || 'font-size' }
+}
+
+// joinBlocks / splitStyleBlocks / extractAllCss are helpers to unify the
+// "multiple <style> blocks" reality with the rule-walker. Each block has its
+// own offset relative to the source file.
+
+export function splitStyleBlocks(source) {
+  const blocks = []
+  if (!source) return 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) {
+      // Offset of the inner CSS within the source file
+      const innerStart = m.index + m[0].indexOf(m[1])
+      blocks.push({ css: m[1], offset: innerStart })
+    }
+  }
+  return blocks.sort((a, b) => a.offset - b.offset)
+}
+
+function extractAllCss(source) {
+  return splitStyleBlocks(source).map((b) => b.css).join('\n')
+}
+
+function joinBlocks(blocks) {
+  return blocks.map((b) => b.css).join('\n')
+}
+
+// Try each style block in order; first match wins. The blocks are passed to
+// findCssRule with their absolute offset so the returned rule offsets are
+// relative to the source file (not the block).
+export function findCssRuleAcrossBlocks(blocks, classList, tag, property) {
+  // Prefer the LAST matching rule across all blocks (cascade winner).
+  let best = null
+  for (const block of blocks) {
+    const match = findCssRule(block.css, classList, tag, property, block.offset)
+    if (match) best = match // keep updating to find the latest match
+  }
+  return best
+}