similarbuild 0.1.0

package/templates/skills/sb-tweak/scripts/lib/intent-parser.mjs

@@ -0,0 +1,324 @@
+// intent-parser.mjs — Parse a natural-language tweak request (PT or EN) into a
+// structured `{action, target, property, value, confidence, language}` object.
+//
+// Pure function, no I/O, no deps. Tested in isolation.
+//
+// The parser is intentionally conservative: when it can't confidently identify
+// every required field (action + target + value-when-needed), it returns a
+// `confidence` below 0.7 so the CLI can exit with code 4 and ask the user to
+// rephrase. It never guesses with high confidence.
+//
+// See ../../references/tweak-patterns.md for the canonical catalog of supported
+// requests. The dictionaries below are derived from that catalog.
+
+// ─── Dictionaries ────────────────────────────────────────────────────────────
+//
+// Each list is pre-sorted longest-first so multi-word phrases beat single-word
+// ones (e.g. "cor de fundo" must match before "cor"). Word boundaries are
+// applied at match time so "principal" doesn't accidentally match "main" inside
+// "domain".
+
+const ACTION_VERBS = [
+  // increase
+  { match: /\b(aumenta(?:r)?|aumente|maior|cresce(?:r)?|cresça|increase|enlarge|grow|bigger|larger)\b/i, action: 'increase', lang: 'pt-or-en' },
+  // decrease
+  { match: /\b(diminui(?:r)?|diminua|menor|encolhe(?:r)?|reduz(?:ir)?|reduza|decrease|reduce|shrink|smaller)\b/i, action: 'decrease', lang: 'pt-or-en' },
+  // set / change / replace (broadest — checked AFTER add/remove because "muda" is generic)
+  { match: /\b(muda(?:r)?|mude|troca(?:r)?|troque|altera(?:r)?|altere|seta(?:r)?|define(?:r)?|defina|set|change|replace|update|swap)\b/i, action: 'set', lang: 'pt-or-en' },
+  // add
+  { match: /\b(adiciona(?:r)?|adicione|coloca(?:r)?|coloque|p[oõ]e(?:r)?|insere(?:r)?|insira|add|insert|put)\b/i, action: 'add', lang: 'pt-or-en' },
+  // remove
+  { match: /\b(remove(?:r)?|remova|tira(?:r)?|tire|apaga(?:r)?|apague|deleta(?:r)?|delete|drop)\b/i, action: 'remove', lang: 'pt-or-en' },
+]
+
+// Order matters: longer / more specific words first. We use Unicode-aware
+// boundaries `(?<![\p{L}\p{N}])` / `(?![\p{L}\p{N}])` with the `u` flag so
+// accented words like "ícone", "último", "rodapé" match at start-of-word
+// (`\b` only sees ASCII word chars and would miss those).
+const TARGET_TYPES = [
+  { match: /(?<![\p{L}\p{N}])(subt[ií]tulo|subtitle|subheading)(?![\p{L}\p{N}])/iu, type: 'subheading' },
+  { match: /(?<![\p{L}\p{N}])(t[ií]tulo|titulo|title|heading|headline|h1|h2|h3)(?![\p{L}\p{N}])/iu, type: 'heading' },
+  { match: /(?<![\p{L}\p{N}])(imagem|image|picture|photo|foto|<?img>?)(?![\p{L}\p{N}])/iu, type: 'image' },
+  { match: /(?<![\p{L}\p{N}])(bot[aã]o|botao|button|btn|cta)(?![\p{L}\p{N}])/iu, type: 'button' },
+  { match: /(?<![\p{L}\p{N}])(par[aá]grafo|paragrafo|paragraph|copy|description|descri[cç][aã]o)(?![\p{L}\p{N}])/iu, type: 'text' },
+  { match: /(?<![\p{L}\p{N}])(link|anchor|[aâ]ncora)(?![\p{L}\p{N}])/iu, type: 'link' },
+  { match: /(?<![\p{L}\p{N}])([ií]cone|icone|icon)(?![\p{L}\p{N}])/iu, type: 'icon' },
+  { match: /(?<![\p{L}\p{N}])(fundo|background|bg)(?![\p{L}\p{N}])/iu, type: 'background' },
+  { match: /(?<![\p{L}\p{N}])(se[cç][aã]o|secao|section)(?![\p{L}\p{N}])/iu, type: 'section' },
+  { match: /(?<![\p{L}\p{N}])texto(?![\p{L}\p{N}])/iu, type: 'text' },
+  { match: /(?<![\p{L}\p{N}])text(?![\p{L}\p{N}])/iu, type: 'text' },
+]
+
+const QUALIFIERS = [
+  { match: /\b(hero|principal|main)\b/i, qualifier: 'hero' },
+  { match: /\b(footer|rodap[eé])\b/i, qualifier: 'footer' },
+  { match: /\b(header|topo|cabe[cç]alho|cabecalho)\b/i, qualifier: 'header' },
+  // Worded ordinals first (use \b for word boundaries)
+  { match: /\b(primeir[oa]|first|1st)\b/i, qualifier: 'first' },
+  { match: /\b(segund[oa]|second|2nd)\b/i, qualifier: 'second' },
+  { match: /\b(terceir[oa]|third|3rd)\b/i, qualifier: 'third' },
+  { match: /\b([uú]ltim[oa]|last|final)\b/i, qualifier: 'last' },
+  // Numeric ordinals with non-word suffix chars (º, °, o, a) — \b doesn't work
+  // around these so we use explicit boundaries.
+  { match: /(?:^|[^\w])1\s*[º°oa](?=$|[^\w])/i, qualifier: 'first' },
+  { match: /(?:^|[^\w])2\s*[º°oa](?=$|[^\w])/i, qualifier: 'second' },
+  { match: /(?:^|[^\w])3\s*[º°oa](?=$|[^\w])/i, qualifier: 'third' },
+]
+
+// Property phrases — checked from most-specific to most-generic so that
+// "cor de fundo" beats "cor" and "background-color" beats "background".
+const PROPERTY_PHRASES = [
+  { match: /\b(cor\s+(?:de|do)\s+fundo|background\s*[- ]?\s*color|bg\s*[- ]?\s*color)\b/i, property: 'background-color' },
+  { match: /\b(cor\s+do\s+texto|text\s*[- ]?\s*color)\b/i, property: 'color' },
+  { match: /\b(font\s*[- ]?\s*size|tamanho\s+(?:da\s+)?fonte)\b/i, property: 'font-size' },
+  { match: /\b(font\s*[- ]?\s*weight|peso\s+(?:da\s+)?fonte)\b/i, property: 'font-weight' },
+  { match: /\bfundo\b/i, property: 'background-color' }, // "muda o fundo do hero"
+  { match: /\bbackground\b/i, property: 'background-color' },
+  { match: /\bcor\b/i, property: 'color' },
+  { match: /\bcolor\b/i, property: 'color' },
+  { match: /\b(altura|height)\b/i, property: 'height' },
+  { match: /\b(largura|width)\b/i, property: 'width' },
+  { match: /\b(espa[cç]amento|padding)\b/i, property: 'padding' },
+  { match: /\b(margem|margin)\b/i, property: 'margin' },
+  { match: /\bweight\b/i, property: 'font-weight' },
+  { match: /\bsize\b/i, property: 'font-size' },
+  { match: /\b(tamanho|size)\b/i, property: 'font-size' },
+  { match: /\balt\b/i, property: 'alt' },
+  { match: /\bsrc\b/i, property: 'src' },
+  { match: /\bhref\b/i, property: 'href' },
+  { match: /\b(texto|text|content|conte[uú]do)\b/i, property: 'text' },
+]
+
+const COLOR_NAMES = new Set([
+  'red', 'blue', 'green', 'white', 'black', 'gray', 'grey', 'yellow', 'orange',
+  'purple', 'pink', 'brown', 'cyan', 'magenta', 'lime', 'navy', 'teal',
+  'maroon', 'olive', 'silver', 'gold', 'transparent',
+  // PT
+  'vermelho', 'azul', 'verde', 'branco', 'preto', 'cinza', 'amarelo', 'laranja',
+  'roxo', 'rosa', 'marrom', 'ouro', 'prata', 'transparente',
+])
+
+// Indicator words that confirm the language. The dictionaries are deliberately
+// language-exclusive — words that appear in both languages (hero, footer,
+// header, color, image when stripped of context, etc.) are dropped to keep
+// the signal sharp. Coarse heuristic: count hits per language and pick the
+// majority.
+const PT_MARKERS = /\b(de|da|do|para|pra|na|no|nas|nos|uma|com|que|essa|esse|aquele|este|esta|aquela|t[ií]tulo|titulo|imagem|bot[aã]o|botao|fundo|cor|tamanho|peso|altura|largura|primeir|segund|terceir|[uú]ltim|principal|rodap|cabe[cç]alho|cabecalho|pra)\b/i
+const EN_MARKERS = /\b(the|to|of|on|in|with|that|this|those|these|title|button|background|color|size|weight|height|width|first|second|third|last|hero|footer|header|alt|src|href|change|increase|decrease|set|add|remove)\b/i
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function parseIntent(rawRequest) {
+  const request = String(rawRequest || '').trim()
+  if (!request) {
+    return zero('empty-request')
+  }
+
+  const language = detectLanguage(request)
+  if (language === 'unknown') {
+    return {
+      action: null, target: null, property: null, value: null,
+      confidence: 0.1,
+      language: 'unknown',
+      reason: 'language-unsupported',
+      raw: request,
+    }
+  }
+
+  const action = matchFirst(ACTION_VERBS, request, 'action')
+  const targetType = matchFirst(TARGET_TYPES, request, 'type')
+  const qualifier = matchFirst(QUALIFIERS, request, 'qualifier')
+  const property = matchFirst(PROPERTY_PHRASES, request, 'property')
+  const value = extractValue(request)
+
+  const target = targetType ? { type: targetType } : null
+  if (target && qualifier) target.qualifier = qualifier
+
+  // Property defaulting: when a target type is identified but no explicit
+  // property phrase is found, derive a sensible default from action + value.
+  let resolvedProperty = property
+  if (target && !resolvedProperty) {
+    resolvedProperty = defaultProperty({ action, target, value })
+  }
+
+  // Compute confidence.
+  let confidence = 0
+  if (action) confidence += 0.3
+  if (target) confidence += 0.3
+  if (resolvedProperty) confidence += 0.15
+  if (qualifier || target?.qualifier) confidence += 0.05
+  // Value scoring: 'remove' doesn't need a value; 'set'/'add'/'increase'/
+  // 'decrease' do. When action is missing entirely, we award no value bonus
+  // — the request is too underspecified to call confident.
+  const needsValue = action && action !== 'remove'
+  if (action && !needsValue) confidence += 0.2
+  else if (action && value) confidence += 0.2
+
+  // Language penalty: weak language signal slightly reduces confidence.
+  if (language === 'mixed') confidence -= 0.05
+
+  // Sanity caps.
+  if (confidence > 1) confidence = 1
+  if (confidence < 0) confidence = 0
+
+  // Reason for low confidence (helps the user fix the rephrasing).
+  let reason = null
+  if (!action) reason = 'no-action-verb'
+  else if (!target) reason = 'no-target-type'
+  else if (needsValue && !value) reason = 'no-value'
+
+  return {
+    action: action || null,
+    target,
+    property: resolvedProperty || null,
+    value,
+    confidence: Number(confidence.toFixed(2)),
+    language,
+    reason,
+    raw: request,
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function zero(reason) {
+  return {
+    action: null, target: null, property: null, value: null,
+    confidence: 0, language: 'unknown', reason, raw: '',
+  }
+}
+
+function matchFirst(table, str, key) {
+  for (const entry of table) {
+    if (entry.match.test(str)) return entry[key]
+  }
+  return null
+}
+
+function detectLanguage(str) {
+  const ptCount = countMatches(str, PT_MARKERS)
+  const enCount = countMatches(str, EN_MARKERS)
+  if (ptCount === 0 && enCount === 0) {
+    // Fallback: if any unique action verb is present, lean that way.
+    if (/\b(aumenta|diminui|muda|troca|adiciona|tira|aumentar|diminuir|mudar|trocar|adicionar|remover|tirar)\b/i.test(str)) return 'pt'
+    if (/\b(increase|decrease|change|replace|enlarge|shrink|reduce)\b/i.test(str)) return 'en'
+    return 'unknown'
+  }
+  if (ptCount > enCount) return 'pt'
+  if (enCount > ptCount) return 'en'
+  return 'mixed' // tied — caller treats as low-confidence-leaning
+}
+
+function countMatches(str, re) {
+  // Make a global flag clone so we can iterate.
+  const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g')
+  let n = 0
+  while (g.exec(str) !== null) n++
+  return n
+}
+
+// extractValue — returns one of:
+//   {kind: 'pixels', raw, parsed: number}
+//   {kind: 'length', raw, parsed: {value: number, unit: string}}
+//   {kind: 'color',  raw, parsed: string}
+//   {kind: 'text',   raw, parsed: string}     // quoted strings only
+//   {kind: 'url',    raw, parsed: string}
+//   {kind: 'number', raw, parsed: number}
+//   null
+//
+// Order matters: we check the most specific patterns first so a quoted hex
+// (`"#fff"`) is parsed as text, while a bare hex is parsed as color.
+export function extractValue(request) {
+  // 1. URL
+  const urlMatch = request.match(/https?:\/\/[^\s)'"]+/i)
+  if (urlMatch) return { kind: 'url', raw: urlMatch[0], parsed: urlMatch[0] }
+
+  // 2. Quoted text (single or double) — captures the inner content.
+  const quoted = request.match(/(?:'([^']+)')|(?:"([^"]+)")/)
+  if (quoted) {
+    const inner = quoted[1] ?? quoted[2]
+    return { kind: 'text', raw: quoted[0], parsed: inner }
+  }
+
+  // 3. Pixel value
+  const pxMatch = request.match(/(\d+(?:\.\d+)?)\s*px\b/i)
+  if (pxMatch) return { kind: 'pixels', raw: pxMatch[0], parsed: parseFloat(pxMatch[1]) }
+
+  // 4. Other length units (rem, em, %, vw, vh). `\b` doesn't fire after `%`
+  // (non-word) so we use a non-letter lookahead to terminate the match.
+  const lenMatch = request.match(/(\d+(?:\.\d+)?)\s*(rem|em|vw|vh|%)(?![a-zA-Z0-9])/i)
+  if (lenMatch) {
+    return {
+      kind: 'length',
+      raw: lenMatch[0],
+      parsed: { value: parseFloat(lenMatch[1]), unit: lenMatch[2].toLowerCase() },
+    }
+  }
+
+  // 5. Hex color
+  const hexMatch = request.match(/#[0-9a-f]{3,8}\b/i)
+  if (hexMatch) return { kind: 'color', raw: hexMatch[0], parsed: hexMatch[0] }
+
+  // 6. rgb/rgba/hsl
+  const fnColor = request.match(/(rgba?|hsla?)\s*\([^)]+\)/i)
+  if (fnColor) return { kind: 'color', raw: fnColor[0], parsed: fnColor[0] }
+
+  // 7. Color name — only on word boundaries
+  for (const name of COLOR_NAMES) {
+    const re = new RegExp(`\\b${name}\\b`, 'i')
+    if (re.test(request)) {
+      return { kind: 'color', raw: name, parsed: name }
+    }
+  }
+
+  // 8. Bare number — only useful when the action verb implies a numeric value.
+  const numMatch = request.match(/\b(\d+(?:\.\d+)?)\b/)
+  if (numMatch) return { kind: 'number', raw: numMatch[0], parsed: parseFloat(numMatch[1]) }
+
+  return null
+}
+
+// defaultProperty — when no explicit property phrase was found, pick a sensible
+// default based on the action, target, and value kind. Returning null means
+// "couldn't infer", which lowers confidence.
+export function defaultProperty({ action, target, value }) {
+  if (!target) return null
+  const t = target.type
+
+  // Sizing actions imply font-size for typographic targets.
+  if (action === 'increase' || action === 'decrease') {
+    if (t === 'heading' || t === 'subheading' || t === 'text' || t === 'button' || t === 'link') return 'font-size'
+    if (t === 'image' || t === 'icon') return 'width'
+    return 'font-size'
+  }
+
+  // Remove rarely needs a property — it removes the element wholesale.
+  if (action === 'remove') return null
+
+  // Set / add: infer from value kind.
+  if (value) {
+    if (value.kind === 'color') {
+      // For 'background' target, default to background-color; for buttons,
+      // default to background-color too (common ask). For text-bearing
+      // elements, default to color.
+      if (t === 'background' || t === 'button' || t === 'section') return 'background-color'
+      return 'color'
+    }
+    if (value.kind === 'pixels' || value.kind === 'length' || value.kind === 'number') {
+      if (t === 'image' || t === 'icon') return 'width'
+      return 'font-size'
+    }
+    if (value.kind === 'url') {
+      if (t === 'link') return 'href'
+      return 'src'
+    }
+    if (value.kind === 'text') {
+      // Text values default to text content unless the target is image/icon
+      // (then alt is the right default).
+      if (t === 'image' || t === 'icon') return 'alt'
+      return 'text'
+    }
+  }
+
+  return null
+}

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

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// test-diff-summarizer.mjs — Unit tests for lib/diff-summarizer.mjs.
+// Covers: summarizeChanges, formatLine per scope, diffLines, computeLineFromOffset.
+
+import { strict as assert } from 'node:assert'
+import {
+  summarizeChanges,
+  formatLine,
+  diffLines,
+  computeLineFromOffset,
+} from '../lib/diff-summarizer.mjs'
+
+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++
+  }
+}
+
+// ─── summarizeChanges ─────────────────────────────────────────────────────────
+
+test('summarizeChanges: empty array → idempotent sentinel', () => {
+  assert.equal(summarizeChanges([]), 'no changes (already applied)')
+})
+
+test('summarizeChanges: null → idempotent sentinel', () => {
+  assert.equal(summarizeChanges(null), 'no changes (already applied)')
+})
+
+test('summarizeChanges: undefined → idempotent sentinel', () => {
+  assert.equal(summarizeChanges(undefined), 'no changes (already applied)')
+})
+
+test('summarizeChanges: single change', () => {
+  const out = summarizeChanges([
+    { selector: '.hero__title', property: 'font-size', before: '27px', after: '32px', scope: 'css-rule', line: 87 },
+  ])
+  assert.match(out, /Changed/)
+  assert.match(out, /font-size/)
+  assert.match(out, /27px/)
+  assert.match(out, /32px/)
+  assert.match(out, /line 87/)
+})
+
+test('summarizeChanges: multiple changes joined by newline', () => {
+  const out = summarizeChanges([
+    { selector: '.a', property: 'color', before: 'red', after: 'blue', scope: 'css-rule', line: 1 },
+    { selector: '.b', property: 'alt', before: null, after: 'logo', scope: 'attr', line: 2 },
+  ])
+  assert.equal(out.split('\n').length, 2)
+})
+
+// ─── formatLine per scope ─────────────────────────────────────────────────────
+
+test('formatLine: css-rule', () => {
+  const line = formatLine({
+    selector: '.hero__title', property: 'font-size', before: '27px', after: '32px', scope: 'css-rule', line: 87,
+  })
+  assert.match(line, /Changed `\.hero__title` font-size/)
+  assert.match(line, /27px/)
+  assert.match(line, /32px/)
+  assert.match(line, /line 87/)
+})
+
+test('formatLine: inline-style add (no before)', () => {
+  const line = formatLine({
+    selector: 'h1.title', property: 'color', before: null, after: 'red', scope: 'inline-style',
+  })
+  assert.match(line, /Added inline color/)
+  assert.match(line, /red/)
+})
+
+test('formatLine: inline-style change (with before)', () => {
+  const line = formatLine({
+    selector: 'h1', property: 'color', before: 'red', after: 'blue', scope: 'inline-style',
+  })
+  assert.match(line, /Changed inline color/)
+  assert.match(line, /red/)
+  assert.match(line, /blue/)
+})
+
+test('formatLine: attr add', () => {
+  const line = formatLine({
+    selector: 'img.hero', property: 'alt', before: null, after: 'Hero shot', scope: 'attr',
+  })
+  assert.match(line, /Added alt=/)
+  assert.match(line, /Hero shot/)
+})
+
+test('formatLine: attr remove', () => {
+  const line = formatLine({
+    selector: 'img.hero', property: 'alt', before: 'old', after: null, scope: 'attr',
+  })
+  assert.match(line, /Removed alt/)
+})
+
+test('formatLine: attr change', () => {
+  const line = formatLine({
+    selector: 'a.link', property: 'href', before: 'https://a', after: 'https://b', scope: 'attr',
+  })
+  assert.match(line, /Changed href/)
+  assert.match(line, /https:\/\/a/)
+  assert.match(line, /https:\/\/b/)
+})
+
+test('formatLine: text', () => {
+  const line = formatLine({
+    selector: 'h1.hero__title', property: 'text', before: 'Welcome', after: 'Hello', scope: 'text',
+  })
+  assert.match(line, /Changed text of/)
+  assert.match(line, /Welcome/)
+  assert.match(line, /Hello/)
+})
+
+test('formatLine: remove-element', () => {
+  const line = formatLine({
+    selector: 'button.cta', property: 'element', before: '<button>Buy</button>', after: null, scope: 'remove-element',
+  })
+  assert.match(line, /Removed element/)
+})
+
+test('formatLine: includes line number when provided', () => {
+  const line = formatLine({
+    selector: '.x', property: 'y', before: 'a', after: 'b', scope: 'css-rule', line: 42,
+  })
+  assert.match(line, /line 42/)
+})
+
+test('formatLine: omits line number when missing', () => {
+  const line = formatLine({
+    selector: '.x', property: 'y', before: 'a', after: 'b', scope: 'css-rule',
+  })
+  assert.doesNotMatch(line, /line/)
+})
+
+test('formatLine: null change returns empty string', () => {
+  assert.equal(formatLine(null), '')
+})
+
+test('formatLine: handles null before/after gracefully', () => {
+  // `∅` is the canonical empty-value marker
+  const line = formatLine({
+    selector: '.x', property: 'color', before: null, after: 'red', scope: 'css-rule',
+  })
+  assert.match(line, /∅|null/)
+  assert.match(line, /red/)
+})
+
+test('formatLine: unknown scope falls back to generic', () => {
+  const line = formatLine({
+    selector: '.x', property: 'foo', before: 'a', after: 'b', scope: 'mystery',
+  })
+  // generic path still produces something
+  assert.match(line, /Changed foo|Updated/)
+})
+
+test('formatLine: idempotent quoting (already-quoted strings preserved)', () => {
+  const line = formatLine({
+    selector: '.x', property: 'color', before: '`red`', after: '`blue`', scope: 'css-rule',
+  })
+  // Backticks not double-wrapped
+  assert.equal(line.match(/`red`/g).length, 1)
+})
+
+// ─── diffLines ───────────────────────────────────────────────────────────────
+
+test('diffLines: identical input returns empty', () => {
+  const out = diffLines('a\nb\nc', 'a\nb\nc')
+  assert.equal(out, '')
+})
+
+test('diffLines: single line change', () => {
+  const out = diffLines('a\nold\nc', 'a\nnew\nc')
+  assert.match(out, /-\s*old/)
+  assert.match(out, /\+\s*new/)
+})
+
+test('diffLines: line addition', () => {
+  const out = diffLines('a\nb', 'a\nb\nc')
+  assert.match(out, /\+\s*c/)
+})
+
+test('diffLines: line removal', () => {
+  const out = diffLines('a\nb\nc', 'a\nb')
+  assert.match(out, /-\s*c/)
+})
+
+test('diffLines: truncates long diffs', () => {
+  const before = Array.from({ length: 100 }, (_, i) => `line${i}`).join('\n')
+  const after = Array.from({ length: 100 }, (_, i) => `line${i + 1}`).join('\n')
+  const out = diffLines(before, after, { maxLines: 5 })
+  assert.match(out, /truncated/)
+})
+
+test('diffLines: handles null/undefined input', () => {
+  // Should not throw
+  const out = diffLines(null, 'x\ny')
+  assert.match(out, /\+\s*x/)
+})
+
+test('diffLines: includes a hunk marker', () => {
+  const out = diffLines('a\nold\nc', 'a\nnew\nc')
+  assert.match(out, /@@/)
+})
+
+// ─── computeLineFromOffset ────────────────────────────────────────────────────
+
+test('computeLineFromOffset: zero offset → line 1', () => {
+  assert.equal(computeLineFromOffset('hello', 0), 1)
+})
+
+test('computeLineFromOffset: counts newlines', () => {
+  assert.equal(computeLineFromOffset('line1\nline2\nline3', 12), 3)
+})
+
+test('computeLineFromOffset: offset at exact newline', () => {
+  // 'a\nb' — offset 1 is on the newline char itself; line should still be 1
+  // (we count 1-based; the `\n` belongs to line 1)
+  assert.equal(computeLineFromOffset('a\nb', 1), 1)
+})
+
+test('computeLineFromOffset: null source → 0', () => {
+  assert.equal(computeLineFromOffset(null, 5), 0)
+})
+
+test('computeLineFromOffset: null offset → 0', () => {
+  assert.equal(computeLineFromOffset('a\nb', null), 0)
+})
+
+test('computeLineFromOffset: offset past EOF clamps gracefully', () => {
+  assert.equal(computeLineFromOffset('a\nb', 9999), 2)
+})
+
+test('computeLineFromOffset: offset negative → 0', () => {
+  assert.equal(computeLineFromOffset('a\nb', -5), 0)
+})
+
+// ─── Done ─────────────────────────────────────────────────────────────────────
+
+process.stdout.write(`\n1..${passed + failed}\n# passed ${passed}, failed ${failed}\n`)
+process.exit(failed === 0 ? 0 : 1)