@sorb/seed 0.2.0 → 0.3.0

package/src/adapt/codemod.js

@@ -0,0 +1,160 @@
+// P3 — codemod: rewrite each `auto` site to `var(--<cssVar>, <original raw>)`,
+// fallback preserved (so the rewritten component renders byte-identical until a
+// token is actually applied). Babel parse → mutate → generate.
+//
+// Safety (spec §6-P3 / AGENTS §5):
+//   - refuses to run on `main` (or whatever the default branch is),
+//   - requires an explicit `--write` flag — without it, dry-run (diff only),
+//   - writes a `.bak` of each changed file + a unified-ish diff under `.sorb/`,
+//   - never mutates source without `--write`.
+import { readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, resolve, dirname } from 'path'
+import { execSync } from 'child_process'
+import { parse } from '@babel/parser'
+import _traverse from '@babel/traverse'
+import _generate from '@babel/generator'
+
+const traverse = /** @type {any} */ (_traverse).default || _traverse
+const generate = /** @type {any} */ (_generate).default || _generate
+
+/** Build the `var(--x, fallback)` replacement string for a raw value. */
+export const varExpr = (cssVar, raw) => `var(${cssVar}, ${raw})`
+
+/** Current git branch for `cwd`, or null if not a repo / git unavailable. */
+export function currentBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim()
+  } catch (e) {
+    return null
+  }
+}
+
+const DEFAULT_BRANCHES = new Set(['main', 'master'])
+
+/**
+ * Rewrite the `auto` sites in a single source string. Returns the new source
+ * (or the original if nothing changed) + the count of edits applied.
+ * Matches sites by {line, column} against AST node locs.
+ * @param {string} source
+ * @param {import('./types.js').AdaptRow[]} fileRows  auto rows for THIS file
+ * @returns {{code: string, edits: number}}
+ */
+export function rewriteSource(source, fileRows) {
+  if (!fileRows.length) return { code: source, edits: 0 }
+  const wanted = new Map() // "line:col" → row
+  for (const r of fileRows) wanted.set(`${r.loc.line}:${r.loc.column}`, r)
+
+  const ast = parse(source, { sourceType: 'unambiguous', plugins: ['jsx', 'typescript'], tokens: false })
+  let edits = 0
+  const keyOf = (node) => node.loc ? `${node.loc.start.line}:${node.loc.start.column}` : null
+  const already = (node) => node._sorbRewritten
+
+  const replaceWith = (node, row) => {
+    if (already(node)) return
+    // Replace the literal node with a string literal carrying the var() expr.
+    // For inline-style JSX/object values this yields  backgroundColor: 'var(--x, #0F65EF)'.
+    const raw = node.type === 'NumericLiteral' ? String(node.value) : node.value
+    node.type = 'StringLiteral'
+    node.value = varExpr(row.cssVar, raw)
+    delete node.extra // drop the original raw quoting so generator re-quotes value
+    node._sorbRewritten = true
+    edits++
+  }
+
+  traverse(ast, {
+    StringLiteral(path) {
+      const k = keyOf(path.node)
+      if (k && wanted.has(k)) replaceWith(path.node, wanted.get(k))
+    },
+    NumericLiteral(path) {
+      const k = keyOf(path.node)
+      if (k && wanted.has(k)) replaceWith(path.node, wanted.get(k))
+    },
+    // Styled-components template quasis: rewrite the literal substring in-place.
+    TemplateElement(path) {
+      const k = keyOf(path.node)
+      if (!k) return
+      // A quasi can host several sites (multiple declarations); match all rows
+      // whose loc points at this quasi.
+      const rows = fileRows.filter((r) => `${r.loc.line}:${r.loc.column}` === k)
+      if (!rows.length) return
+      let cooked = path.node.value.cooked != null ? path.node.value.cooked : path.node.value.raw
+      let raw = path.node.value.raw
+      for (const row of rows) {
+        const replacement = varExpr(row.cssVar, row.raw)
+        // Replace the first verbatim occurrence of the raw value.
+        if (cooked.includes(row.raw)) cooked = cooked.replace(row.raw, replacement)
+        if (raw.includes(row.raw)) raw = raw.replace(row.raw, replacement)
+        edits++
+      }
+      path.node.value = { cooked, raw }
+    },
+  })
+
+  if (!edits) return { code: source, edits: 0 }
+  const out = generate(ast, { retainLines: true, jsescOption: { minimal: true } }, source)
+  return { code: out.code, edits }
+}
+
+/**
+ * Run the codemod over the auto rows. Groups rows by file. Dry-run by default;
+ * writes only with `write: true`. Refuses on default branch.
+ * @param {import('./types.js').AdaptRow[]} rows  full report rows
+ * @param {{cwd: string, write?: boolean, allowBranch?: boolean}} o
+ */
+export async function runCodemod(rows, o) {
+  const { cwd, write = false } = o
+  const branch = currentBranch(cwd)
+  if (!o.allowBranch && branch && DEFAULT_BRANCHES.has(branch)) {
+    return { refused: true, reason: `refusing to codemod on default branch '${branch}' — branch first`, branch }
+  }
+
+  const auto = rows.filter((r) => r.status === 'auto')
+  const byFile = new Map()
+  for (const r of auto) {
+    if (!byFile.has(r.file)) byFile.set(r.file, [])
+    byFile.get(r.file).push(r)
+  }
+
+  const sorbDir = join(cwd, '.sorb')
+  const diffs = []
+  let changedFiles = 0
+  for (const [file, fileRows] of byFile) {
+    const abs = resolve(cwd, file)
+    const source = readFileSync(abs, 'utf-8')
+    const { code, edits } = rewriteSource(source, fileRows)
+    if (!edits || code === source) continue
+    changedFiles++
+    diffs.push(makeDiff(file, source, code))
+    if (write) {
+      // .bak under .sorb/ mirroring the file path, then write the rewrite.
+      const bak = join(sorbDir, 'bak', file + '.bak')
+      mkdirSync(dirname(bak), { recursive: true })
+      writeFileSync(bak, source, 'utf-8')
+      writeFileSync(abs, code, 'utf-8')
+    }
+  }
+
+  const diff = diffs.join('\n')
+  if (write && diff) {
+    mkdirSync(sorbDir, { recursive: true })
+    writeFileSync(join(sorbDir, 'adapt-codemod.diff'), diff + '\n', 'utf-8')
+  }
+  return { refused: false, written: write, changedFiles, diff, branch }
+}
+
+/** A minimal line-level unified-ish diff (no external dep). */
+export function makeDiff(file, before, after) {
+  const a = before.split('\n')
+  const b = after.split('\n')
+  const out = [`--- a/${file}`, `+++ b/${file}`]
+  const max = Math.max(a.length, b.length)
+  for (let i = 0; i < max; i++) {
+    if (a[i] === b[i]) continue
+    if (a[i] !== undefined) out.push(`-${a[i]}`)
+    if (b[i] !== undefined) out.push(`+${b[i]}`)
+  }
+  return out.join('\n')
+}

package/src/adapt/codemod.test.js

@@ -0,0 +1,120 @@
+// P3 acceptance: codemod dry-run produces a diff; --write on a fixture COPY
+// rewrites to var(--x, original) preserving the fallback; re-detecting the
+// rewritten file reports those sites as resolved (var), not hardcoded; and the
+// default-branch refusal is enforced. Operates on temp copies — never tracked
+// source. Run: node --test src/
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, existsSync, rmSync, cpSync } from 'fs'
+import { tmpdir } from 'os'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { buildTokenIndex } from '../annotateTokens.js'
+import { detectHardcoded } from './detectHardcoded.js'
+import { buildReport } from './report.js'
+import { rewriteSource, runCodemod, varExpr, makeDiff } from './codemod.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const RESOLVED = JSON.parse(
+  readFileSync(join(here, '..', '..', '..', 'sorb-demo', '.sorb', 'resolved.json'), 'utf-8'),
+)
+const index = buildTokenIndex(RESOLVED)
+const fixtureSrc = readFileSync(join(here, '__fixtures__', 'Button.legacy.jsx'), 'utf-8')
+
+const autoRows = (file) =>
+  buildReport(detectHardcoded(fixtureSrc, file), index, RESOLVED).filter((r) => r.status === 'auto')
+
+test('varExpr builds var(--x, fallback) with the original literal preserved', () => {
+  assert.equal(varExpr('--button-radius', '4px'), 'var(--button-radius, 4px)')
+})
+
+test('rewriteSource rewrites auto sites to var() and leaves others untouched', () => {
+  const rows = autoRows('Button.legacy.jsx')
+  const { code, edits } = rewriteSource(fixtureSrc, rows)
+  assert.ok(edits >= 2) // at least bg + radius
+  assert.ok(code.includes('var(--button-primary-bg-default'))
+  assert.ok(code.includes('var(--button-radius'))
+  // fallback preserved (byte-identical render until a token applies)
+  assert.ok(code.includes('#0F65EF'))
+})
+
+test('re-detecting the rewritten source reports the auto sites as resolved (not hardcoded)', () => {
+  const rows = autoRows('Button.legacy.jsx')
+  const { code } = rewriteSource(fixtureSrc, rows)
+  const after = detectHardcoded(code, 'rewritten.jsx')
+  // The bg #0F65EF and radius 4/4px sites must no longer be flagged.
+  assert.ok(!after.some((s) => s.role === 'bg' && s.raw === '#0F65EF'))
+  assert.ok(!after.some((s) => s.role === 'radius'))
+})
+
+test('makeDiff produces a reviewable +/- diff', () => {
+  const d = makeDiff('f.jsx', 'a\nb\nc', 'a\nB\nc')
+  assert.ok(d.includes('-b'))
+  assert.ok(d.includes('+B'))
+})
+
+test('runCodemod dry-run (no --write) emits a diff and changes nothing on disk', async () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'sorb-codemod-'))
+  try {
+    const file = 'Button.legacy.jsx'
+    const abs = join(cwd, file)
+    writeFileSync(abs, fixtureSrc, 'utf-8')
+    const rows = autoRows(file)
+    const res = await runCodemod(rows, { cwd, write: false, allowBranch: true })
+    assert.equal(res.refused, false)
+    assert.equal(res.written, false)
+    assert.ok(res.changedFiles >= 1)
+    assert.ok(res.diff.length > 0)
+    // disk untouched
+    assert.equal(readFileSync(abs, 'utf-8'), fixtureSrc)
+  } finally {
+    rmSync(cwd, { recursive: true, force: true })
+  }
+})
+
+test('runCodemod --write rewrites the COPY + writes a .bak; rewritten re-detects clean', async () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'sorb-codemod-'))
+  try {
+    const file = 'Button.legacy.jsx'
+    const abs = join(cwd, file)
+    writeFileSync(abs, fixtureSrc, 'utf-8')
+    const rows = autoRows(file)
+    const res = await runCodemod(rows, { cwd, write: true, allowBranch: true })
+    assert.equal(res.written, true)
+    const rewritten = readFileSync(abs, 'utf-8')
+    assert.notEqual(rewritten, fixtureSrc)
+    assert.ok(rewritten.includes('var(--button-primary-bg-default'))
+    assert.ok(rewritten.includes('#0F65EF')) // fallback preserved
+    // .bak preserves the original
+    const bak = join(cwd, '.sorb', 'bak', file + '.bak')
+    assert.ok(existsSync(bak))
+    assert.equal(readFileSync(bak, 'utf-8'), fixtureSrc)
+    // re-detect: the auto sites now read as var()
+    const after = detectHardcoded(rewritten, file)
+    assert.ok(!after.some((s) => s.role === 'bg' && s.raw === '#0F65EF'))
+    assert.ok(!after.some((s) => s.role === 'radius'))
+  } finally {
+    rmSync(cwd, { recursive: true, force: true })
+  }
+})
+
+test('runCodemod refuses to run on a default branch (main)', async () => {
+  // A temp git repo whose current branch is `main`.
+  const cwd = mkdtempSync(join(tmpdir(), 'sorb-codemod-main-'))
+  try {
+    const { execSync } = await import('child_process')
+    const git = (c) => execSync(c, { cwd, stdio: 'ignore' })
+    git('git init -q')
+    git('git symbolic-ref HEAD refs/heads/main')
+    // An initial commit so `rev-parse --abbrev-ref HEAD` resolves to 'main'
+    // (an unborn branch reports 'HEAD', not the branch name).
+    git('git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init')
+    writeFileSync(join(cwd, 'Button.legacy.jsx'), fixtureSrc, 'utf-8')
+    const rows = autoRows('Button.legacy.jsx')
+    const res = await runCodemod(rows, { cwd, write: true }) // allowBranch NOT set
+    assert.equal(res.refused, true)
+    assert.match(res.reason, /default branch/)
+  } finally {
+    rmSync(cwd, { recursive: true, force: true })
+  }
+})

package/src/adapt/detectHardcoded.js

@@ -0,0 +1,165 @@
+// P0 — detectHardcoded: find hardcoded color/dimension style literals in
+// consumer React source via the Babel AST.
+//
+// Reuses the SAME normalizers as the capture binder (annotateTokens.js) so a
+// value the matcher would bind is exactly a value we flag — no drift.
+//
+// Detects three shapes:
+//   (a) JSX inline  style={{ backgroundColor: '#0F65EF', borderRadius: 4 }}
+//   (b) styled-components / template-literal CSS  styled.button`background:#0F65EF; border-radius:4px;`
+//   (c) CSS-Module-style string literals          const s = { background: '#0F65EF' }  (plain object props)
+//
+// A value already written as `var(--…)` is NOT hardcoded → skipped.
+
+import { parse } from '@babel/parser'
+import _traverse from '@babel/traverse'
+import { normalizeColor, normalizeDimension } from '../annotateTokens.js'
+
+// @babel/traverse ships as CJS with a `.default` interop under ESM.
+const traverse = /** @type {any} */ (_traverse).default || _traverse
+
+/**
+ * Map a CSS/JSX property name → matcher role. Accepts both kebab-case (CSS,
+ * styled-components) and camelCase (JSX inline style). Non-roled props → null
+ * (still detected, matched tier-only).
+ * @param {string} prop
+ * @returns {import('./types.js').AdaptRole}
+ */
+export const propToRole = (prop) => {
+  const p = String(prop).trim().toLowerCase()
+  switch (p) {
+    case 'background':
+    case 'background-color':
+    case 'backgroundcolor':
+      return 'bg'
+    case 'color':
+      return 'text'
+    case 'border-color':
+    case 'bordercolor':
+      return 'border'
+    case 'border-radius':
+    case 'borderradius':
+      return 'radius'
+    default:
+      return null
+  }
+}
+
+// Properties whose values we even bother to inspect. Keep this generous: any
+// prop that can carry a color or a dimension. We still only FLAG values that
+// normalize to a color or dimension, so a non-style prop with a stray string
+// won't false-positive (it won't normalize).
+const STYLE_PROP_RE = /(color|background|border|radius|width|height|margin|padding|gap|top|left|right|bottom|fill|stroke|shadow|outline|size|spacing|inset)/i
+
+const isVarRef = (raw) => /^var\(\s*--/i.test(String(raw).trim())
+
+/**
+ * Is this raw literal a hardcoded color or dimension we should flag?
+ * Returns false for var(--…), non-color/non-dimension strings, etc.
+ * @param {string} raw
+ */
+const isHardcodedValue = (raw) => {
+  if (raw == null) return false
+  const s = String(raw).trim()
+  if (s === '') return false
+  if (isVarRef(s)) return false
+  return normalizeColor(s) != null || normalizeDimension(s) != null
+}
+
+/**
+ * Parse source into a Babel AST. `jsx` + `typescript` plugins so .jsx AND .tsx
+ * both parse (we parse a consumer's TS source; we never emit TS).
+ * @param {string} source
+ */
+export const parseSource = (source) =>
+  parse(source, {
+    sourceType: 'unambiguous',
+    plugins: ['jsx', 'typescript'],
+    errorRecovery: true,
+  })
+
+/**
+ * Pull `{line, column}` from a Babel node, 1-based line / 0-based column.
+ * @param {any} node
+ */
+const locOf = (node) =>
+  node && node.loc
+    ? { line: node.loc.start.line, column: node.loc.start.column }
+    : { line: 0, column: 0 }
+
+/**
+ * Detect hardcoded color/dimension style sites in `source`.
+ * @param {string} source   The file's source text.
+ * @param {string} filename The file path (recorded on each site).
+ * @returns {import('./types.js').AdaptSite[]}
+ */
+export function detectHardcoded(source, filename) {
+  /** @type {import('./types.js').AdaptSite[]} */
+  const sites = []
+  const push = (prop, raw, node) => {
+    if (!isHardcodedValue(raw)) return
+    sites.push({
+      file: filename,
+      loc: locOf(node),
+      prop,
+      raw: String(raw),
+      role: propToRole(prop),
+    })
+  }
+
+  let ast
+  try {
+    ast = parseSource(source)
+  } catch (e) {
+    // A file we can't parse yields no sites rather than throwing — the adapter
+    // is a best-effort detector over a whole codebase. (catch (e), never {}.)
+    return sites
+  }
+
+  traverse(ast, {
+    // (a) JSX inline style={{ ... }} — ObjectProperty inside a JSXAttribute
+    // named "style". We detect object props anywhere named like a style prop,
+    // which also covers (c) plain CSS-Module-style style objects.
+    ObjectProperty(path) {
+      const keyNode = path.node.key
+      const prop =
+        keyNode.type === 'Identifier'
+          ? keyNode.name
+          : keyNode.type === 'StringLiteral'
+            ? keyNode.value
+            : null
+      if (!prop) return
+      if (!STYLE_PROP_RE.test(prop)) return
+      const v = path.node.value
+      if (v.type === 'StringLiteral') push(prop, v.value, v)
+      else if (v.type === 'NumericLiteral') push(prop, String(v.value), v)
+    },
+
+    // (b) styled-components / any tagged or untagged CSS template literal.
+    // Scan the static (quasi) chunks for `prop: value;` declarations and flag
+    // hardcoded color/dimension values. Interpolations (${...}) are skipped —
+    // they're already dynamic.
+    TemplateLiteral(path) {
+      for (const quasi of path.node.quasis) {
+        const text = quasi.value.cooked != null ? quasi.value.cooked : quasi.value.raw
+        if (!text) continue
+        // Match `prop: value` declarations (value up to ; or end of chunk).
+        const declRe = /([-a-zA-Z]+)\s*:\s*([^;{}]+)/g
+        let m
+        while ((m = declRe.exec(text)) !== null) {
+          const prop = m[1].trim()
+          if (!STYLE_PROP_RE.test(prop)) continue
+          // A declaration value can be multi-token (e.g. `1px solid #0F65EF`);
+          // inspect each whitespace-separated token for a color/dimension.
+          const value = m[2].trim()
+          const tokens = value.split(/\s+/)
+          for (const tok of tokens) {
+            if (isHardcodedValue(tok)) push(prop, tok, quasi)
+          }
+        }
+      }
+    },
+  })
+
+  return sites
+}

package/src/adapt/detectHardcoded.test.js

@@ -0,0 +1,62 @@
+// P0 acceptance: detectHardcoded finds all N known hardcoded sites in a legacy
+// fixture (zero false negatives) and 0 sites in a fully-var() file (zero false
+// positives). Run: node --test src/
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { detectHardcoded, propToRole } from './detectHardcoded.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const fixture = (name) => readFileSync(join(here, '__fixtures__', name), 'utf-8')
+
+test('propToRole maps CSS + JSX prop names to matcher roles', () => {
+  assert.equal(propToRole('background'), 'bg')
+  assert.equal(propToRole('background-color'), 'bg')
+  assert.equal(propToRole('backgroundColor'), 'bg')
+  assert.equal(propToRole('color'), 'text')
+  assert.equal(propToRole('border-color'), 'border')
+  assert.equal(propToRole('borderColor'), 'border')
+  assert.equal(propToRole('border-radius'), 'radius')
+  assert.equal(propToRole('borderRadius'), 'radius')
+  assert.equal(propToRole('padding'), null) // non-roled → tier-only
+})
+
+test('detectHardcoded finds all 8 known hardcoded sites in the legacy fixture', () => {
+  const src = fixture('Button.legacy.jsx')
+  const sites = detectHardcoded(src, 'Button.legacy.jsx')
+  assert.equal(sites.length, 8, `expected 8 sites, got ${sites.length}: ` +
+    JSON.stringify(sites.map((s) => `${s.prop}=${s.raw}`)))
+
+  // The specific bindings we depend on downstream.
+  const byRaw = (raw) => sites.filter((s) => s.raw === raw)
+  assert.ok(byRaw('#0F65EF').length >= 1) // inline bg + styled background
+  assert.ok(sites.some((s) => s.prop === 'backgroundColor' && s.role === 'bg'))
+  assert.ok(sites.some((s) => s.prop === 'borderColor' && s.role === 'border'))
+  assert.ok(sites.some((s) => s.prop === 'borderRadius' && s.raw === '4' && s.role === 'radius'))
+  assert.ok(sites.some((s) => s.prop === 'border-radius' && s.raw === '4px' && s.role === 'radius'))
+  assert.ok(sites.some((s) => s.role === 'text')) // white text
+  assert.ok(sites.some((s) => s.prop === 'padding' && s.role === null)) // non-roled
+})
+
+test('detectHardcoded records 1-based line numbers and the file path', () => {
+  const sites = detectHardcoded(fixture('Button.legacy.jsx'), 'X.jsx')
+  for (const s of sites) {
+    assert.equal(s.file, 'X.jsx')
+    assert.ok(s.loc.line > 0)
+    assert.ok(Number.isInteger(s.loc.column))
+  }
+})
+
+test('detectHardcoded finds 0 sites in a fully-var() (.tsx) file — no false positives', () => {
+  const src = fixture('Button.tokenized.tsx')
+  const sites = detectHardcoded(src, 'Button.tokenized.tsx')
+  assert.equal(sites.length, 0, `expected 0, got: ` +
+    JSON.stringify(sites.map((s) => `${s.prop}=${s.raw}`)))
+})
+
+test('detectHardcoded is resilient: unparseable source yields [] (no throw)', () => {
+  const sites = detectHardcoded('const x = (((;;;', 'broken.js')
+  assert.ok(Array.isArray(sites))
+})

package/src/adapt/glob.js

@@ -0,0 +1,87 @@
+// Minimal dependency-free glob for the adapter's --src. Supports `**` (any
+// depth), `*` (one segment), and brace alts `{a,b}`. Enough to resolve patterns
+// like `src/**/*.{jsx,tsx,js,ts}` without pulling in a glob dependency.
+import { readdirSync, statSync, existsSync } from 'fs'
+import { join, sep } from 'path'
+
+const IGNORE = new Set(['node_modules', '.git', '.sorb', 'dist', 'build', '.next'])
+
+/** Expand `{a,b,c}` brace alternatives into multiple patterns. */
+const expandBraces = (pattern) => {
+  const m = pattern.match(/\{([^{}]+)\}/)
+  if (!m) return [pattern]
+  const alts = m[1].split(',')
+  const out = []
+  for (const alt of alts) {
+    out.push(...expandBraces(pattern.replace(m[0], alt)))
+  }
+  return out
+}
+
+/** Compile a single glob (no braces) into a RegExp anchored to the full path. */
+const toRegExp = (pattern) => {
+  let re = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**` → any chars incl. path separators
+        re += '.*'
+        i++
+        if (pattern[i + 1] === '/') i++ // swallow the slash after **
+      } else {
+        re += '[^/]*'
+      }
+    } else if ('.+^${}()|[]\\'.includes(c)) {
+      re += '\\' + c
+    } else if (c === '/') {
+      re += '/'
+    } else {
+      re += c
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+/** Recursively list all files under a root (skipping IGNORE dirs). */
+const walk = (root) => {
+  const out = []
+  const rec = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch (e) {
+      return
+    }
+    for (const ent of entries) {
+      if (IGNORE.has(ent.name)) continue
+      const full = join(dir, ent.name)
+      if (ent.isDirectory()) rec(full)
+      else if (ent.isFile()) out.push(full)
+    }
+  }
+  rec(root)
+  return out
+}
+
+/**
+ * Resolve a glob pattern (relative to cwd) to a list of matching file paths.
+ * Normalizes path separators to `/` for matching. If the pattern names a single
+ * existing file, returns just that file.
+ * @param {string} pattern
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function globFiles(pattern, cwd) {
+  // Direct file?
+  const direct = join(cwd, pattern)
+  if (existsSync(direct) && statSync(direct).isFile()) return [direct]
+
+  const patterns = expandBraces(pattern).map((p) => toRegExp(p))
+  const all = walk(cwd)
+  const norm = (p) => p.slice(cwd.length).replace(/^[/\\]/, '').split(sep).join('/')
+  return all.filter((f) => {
+    const rel = norm(f)
+    return patterns.some((re) => re.test(rel))
+  })
+}