purgetss 7.9.0 → 7.11.1

package/src/core/svg/sync-images.js

@@ -0,0 +1,278 @@
+/**
+ * PurgeTSS - config.cjs sync for SVG-derived dimensions
+ *
+ * Updates `images.files` inside the user's purgetss/config.cjs to reflect the
+ * dimensions resolved from app.tss. Companion to setConfigProperty (which only
+ * handles primitives) — this one knows how to upsert into an array of objects
+ * while preserving the user's formatting, comments, and any manual overrides.
+ *
+ * Policy (see plan):
+ *   - Entry missing      → insert `{ filename, width [, height] }`.
+ *   - Entry present, width < derived → bump width (and height) to derived.
+ *   - Entry present, width >= derived → leave alone. Manual overrides win.
+ *
+ * String-based mutation chosen over `recast` to avoid adding a heavy dep —
+ * config.cjs has a controlled shape since `purgetss init` writes it. If we
+ * can't safely locate the section we no-op and warn, mirroring setConfigProperty.
+ *
+ * @fileoverview Upsert image entries in config.cjs while preserving formatting
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import { projectsConfigJS } from '../../shared/constants.js'
+
+/**
+ * Apply the derived dimensions to `images.files` in the user's config.cjs and
+ * return the effective per-SVG dimensions after the sync (i.e. the max of the
+ * derived value and any pre-existing manual override). Callers should drive
+ * PNG generation from the returned `effective` map so manual overrides — like
+ * pinning a width above what the class cascade resolves — produce PNGs at the
+ * higher resolution.
+ *
+ * @param {Map<string, { widthDp: number, heightDp: number }>} derived
+ *   Keyed by SVG relpath (matches the `filename` field stored in config).
+ * @param {Object} [opts]
+ * @param {Object} [opts.logger] - Logger with `.warning(msg)` / `.info(msg)`.
+ * @param {boolean} [opts.write=true] - When false, computes the effective map
+ *   without mutating config.cjs (for users who keep `images.autoSync: false`
+ *   and prefer to manage `images.files` by hand).
+ * @returns {{
+ *   stats: { updated: number, inserted: number, untouched: number },
+ *   effective: Map<string, { widthDp: number, heightDp: number }>
+ * }}
+ */
+export function syncConfigImages(derived, { logger, write = true } = {}) {
+  const stats = { updated: 0, inserted: 0, untouched: 0 }
+  const effective = new Map()
+  if (!fs.existsSync(projectsConfigJS)) {
+    logger?.warning('config.cjs not found — skipping SVG dimensions sync.')
+    // Without config we still want PNGs generated at the derived size — copy
+    // the derived map through verbatim.
+    for (const [k, v] of derived) effective.set(k, { ...v })
+    return { stats, effective }
+  }
+
+  let source = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  for (const [relPath, { widthDp, heightDp }] of derived) {
+    const filename = toFilename(relPath)
+    const existing = findEntry(source, filename)
+    if (existing) {
+      // autoSync ON (this code path): config mirrors the current run. The
+      // derived numbers already reflect max() across every reference to this
+      // SVG in this run (see derive-dimensions.js) — sync just writes them
+      // through. No second max against the previous run, which would freeze
+      // shrunk classes at their old larger size. Users who want to pin a
+      // value by hand should set images.autoSync: false (write=false), which
+      // skips this file write entirely.
+      const desired = {}
+      if (widthDp != null) desired.width = widthDp
+      if (heightDp != null) desired.height = heightDp
+
+      const widthSame = (existing.width ?? null) === (desired.width ?? null)
+      const heightSame = (existing.height ?? null) === (desired.height ?? null)
+      if (widthSame && heightSame) {
+        stats.untouched++
+      } else {
+        source = replaceEntry(source, existing, filename, desired)
+        stats.updated++
+      }
+      effective.set(relPath, { widthDp: desired.width ?? null, heightDp: desired.height ?? null })
+    } else {
+      const entry = {}
+      if (widthDp != null) entry.width = widthDp
+      if (heightDp != null) entry.height = heightDp
+      const next = insertEntry(source, filename, entry)
+      if (next === null) {
+        logger?.warning(`Could not insert ${filename} into images.files (section missing or unreadable).`)
+        effective.set(relPath, { widthDp, heightDp })
+        continue
+      }
+      source = next
+      stats.inserted++
+      effective.set(relPath, { widthDp, heightDp })
+    }
+  }
+
+  // Only write when we actually mutated `source`. The loop above only mutates
+  // it inside the inserted/updated branches; `untouched` leaves it byte-identical
+  // to disk. Skipping the write avoids touching the mtime, which other parts of
+  // PurgeTSS use to invalidate utilities.tss — gratuitous mtime bumps would
+  // trigger needless rebuilds. Derive + effective + the SVG cache still run
+  // either way, so generation/validation is unaffected.
+  if (write && (stats.inserted > 0 || stats.updated > 0)) {
+    fs.writeFileSync(projectsConfigJS, source, 'utf8')
+  }
+  return { stats, effective }
+}
+
+function toFilename(relPath) {
+  // Stored form mirrors the `purgetss images` convention: `images/<subpath>/<name>.svg`
+  return `images/${relPath.replace(/^\/+/, '')}`
+}
+
+// Locate an entry like `{ filename: 'images/foo.svg', width: 128 }`. Tolerates
+// keys in any order and either quoting style.
+function findEntry(source, filename) {
+  const escaped = filename.replace(/[/.[\]()*+?^$|\\]/g, '\\$&')
+  const re = new RegExp(
+    `\\{[^{}]*?\\bfilename\\s*:\\s*['"\`]${escaped}['"\`][^{}]*?\\}`,
+    'g'
+  )
+  const matches = [...source.matchAll(re)]
+  if (matches.length === 0) return null
+  const match = matches[0]
+  const body = match[0]
+  const width = readNumber(body, 'width')
+  const height = readNumber(body, 'height')
+  return { match: body, index: match.index, width, height }
+}
+
+function readNumber(body, key) {
+  const m = body.match(new RegExp(`\\b${key}\\s*:\\s*(\\d+)`))
+  return m ? Number(m[1]) : null
+}
+
+function replaceEntry(source, existing, filename, desired) {
+  const newEntry = renderEntry(filename, desired)
+  return source.slice(0, existing.index) + newEntry + source.slice(existing.index + existing.match.length)
+}
+
+function renderEntry(filename, { width, height }) {
+  const parts = [`filename: '${filename}'`]
+  if (width != null) parts.push(`width: ${width}`)
+  if (height != null) parts.push(`height: ${height}`)
+  return `{ ${parts.join(', ')} }`
+}
+
+// Insert a new entry into the images.files array. Returns the mutated source
+// string, or null if the array can't be located/created safely.
+function insertEntry(source, filename, entry) {
+  // First pass: make sure the array exists; this may mutate `source` to inject
+  // `files: []` into the `images` section when missing.
+  const ensured = ensureFilesArray(source)
+  if (ensured === null) return null
+  source = ensured
+
+  const filesArr = locateFilesArray(source)
+  if (!filesArr) return null
+
+  const { openIdx, closeIdx, indent } = filesArr
+  const inner = source.slice(openIdx + 1, closeIdx)
+  const newEntry = renderEntry(filename, entry)
+
+  const innerTrimmed = inner.replace(/\s+$/, '')
+  if (innerTrimmed.trim().length === 0) {
+    // Empty array: rewrite as multi-line with one entry.
+    const replacement = `[\n${indent}  ${newEntry}\n${indent}]`
+    return source.slice(0, openIdx) + replacement + source.slice(closeIdx + 1)
+  }
+
+  // Non-empty: ensure the previous entry has a trailing comma and append a
+  // new line with the same indent as siblings (heuristic: 2-space extra).
+  const lines = innerTrimmed.split('\n')
+  const lastIdx = lines.length - 1
+  const lastLine = lines[lastIdx]
+  const stripped = lastLine.replace(/\s+$/, '')
+  if (!stripped.endsWith(',') && !stripped.endsWith('[')) {
+    lines[lastIdx] = stripped + ','
+  }
+  const newInner = lines.join('\n') + `\n${indent}  ${newEntry}\n${indent}`
+  return source.slice(0, openIdx + 1) + newInner + source.slice(closeIdx)
+}
+
+// If `images.files` is missing, inject an empty `files: []` immediately before
+// the section's closing brace, preserving the user's indentation.
+function ensureFilesArray(source) {
+  const section = matchImagesSection(source)
+  if (!section) return null
+  if (/(\n\s*)files\s*:\s*\[/.test(section.body)) return source
+
+  const insertion = `\n${section.indent}  files: []`
+  const closingIdx = section.end - 1 // position of '}'
+  const before = source.slice(0, closingIdx)
+  const after = source.slice(closingIdx)
+  // Drop trailing horizontal whitespace + newlines so the new line lands flush
+  // against the previous sibling line.
+  const trimmed = before.replace(/[ \t]+$/, '').replace(/\n+$/, '')
+  return appendTrailingCommaIfNeeded(trimmed) + insertion + '\n' + section.indent + after
+}
+
+// Ensure the previous property line is followed by a comma so the appended
+// line parses. Honors trailing `// comments` by placing the comma between the
+// value and the comment, never inside the comment itself.
+function appendTrailingCommaIfNeeded(text) {
+  const lastLineStart = text.lastIndexOf('\n') + 1
+  const head = text.slice(0, lastLineStart)
+  const lastLine = text.slice(lastLineStart)
+  // Split off a trailing `// comment` (with optional leading whitespace).
+  const commentMatch = lastLine.match(/^(.*?)(\s*\/\/.*)$/)
+  const valuePart = (commentMatch ? commentMatch[1] : lastLine).replace(/[ \t]+$/, '')
+  const commentPart = commentMatch ? commentMatch[2] : ''
+  if (!valuePart || valuePart.endsWith(',') || valuePart.endsWith('{')) return text
+  return head + valuePart + ',' + commentPart
+}
+
+function matchImagesSection(source) {
+  // Locate the `images:` key, then bracket-balance to its matching `}`.
+  // The previous lazy-regex approach mis-identified the closing brace whenever
+  // `images: { ... }` was written on a single line (no `\n indent }` to anchor
+  // on) — it swallowed sibling sections and dropped `files: []` into whichever
+  // nested block happened to close first. Bracket-balancing works regardless
+  // of formatting, matching what the rest of PurgeTSS expects from config.cjs.
+  const m = source.match(/^([ \t]*)images\s*:\s*\{/m)
+  if (!m) return null
+
+  const openIdx = m.index + m[0].length - 1
+  const closeIdx = matchBracket(source, openIdx, '{', '}')
+  if (closeIdx === -1) return null
+
+  return {
+    start: m.index,
+    end: closeIdx + 1,
+    indent: m[1],
+    body: source.slice(openIdx + 1, closeIdx)
+  }
+}
+
+// Find the `files: [ ... ]` array inside the `images: { ... }` section.
+function locateFilesArray(source) {
+  const section = matchImagesSection(source)
+  if (!section) return null
+
+  const filesMatch = section.body.match(/(\n\s*)files\s*:\s*\[/)
+  if (!filesMatch) return null
+
+  const arrayKeyStart = section.start + section.body.indexOf(filesMatch[0]) + filesMatch[1].length
+  const openIdx = source.indexOf('[', arrayKeyStart)
+  if (openIdx === -1) return null
+  const closeIdx = matchBracket(source, openIdx, '[', ']')
+  if (closeIdx === -1) return null
+
+  const lineStart = source.lastIndexOf('\n', arrayKeyStart) + 1
+  const indent = source.slice(lineStart, arrayKeyStart).match(/^[ \t]*/)[0]
+
+  return { openIdx, closeIdx, indent }
+}
+
+function matchBracket(source, startIdx, open, close) {
+  let depth = 0
+  let inSingle = false
+  let inDouble = false
+  let inBacktick = false
+  for (let i = startIdx; i < source.length; i++) {
+    const c = source[i]
+    if (c === '\'' && !inDouble && !inBacktick) inSingle = !inSingle
+    else if (c === '"' && !inSingle && !inBacktick) inDouble = !inDouble
+    else if (c === '`' && !inSingle && !inDouble) inBacktick = !inBacktick
+    else if (!inSingle && !inDouble && !inBacktick) {
+      if (c === open) depth++
+      else if (c === close) {
+        depth--
+        if (depth === 0) return i
+      }
+    }
+  }
+  return -1
+}

package/src/core/svg/tss-reader.js

@@ -0,0 +1,134 @@
+/**
+ * PurgeTSS - TSS reader for the SVG pipeline
+ *
+ * Lightweight parser for the controlled TSS output PurgeTSS generates. Used by
+ * the SVG image pipeline to resolve final width/height per class after a
+ * regular purge run. NOT a general-purpose TSS parser — only the shapes the
+ * purger emits are recognized.
+ *
+ * Recognized line shape:
+ *   '.classname': { prop: value, prop: value }
+ *
+ * Tag selectors (e.g. 'View': { ... }, 'ImageView[platform=ios]': { ... }) and
+ * '#id': { ... } selectors are skipped — the SVG pipeline resolves only by
+ * class cascade in V1.
+ *
+ * @fileoverview Class → properties map extracted from purged app.tss
+ * @author César Estrada
+ */
+
+const CLASS_LINE = /^\s*'\.([^']+)'\s*:\s*\{([^}]*)\}\s*$/
+
+/**
+ * Parse the controlled TSS string emitted by the purger into a class → props
+ * map. Values are returned in a normalized form:
+ *
+ *   - number             → finite numeric value (e.g. 128)
+ *   - 'auto'             → Ti.UI.SIZE
+ *   - 'fill'             → Ti.UI.FILL
+ *   - 'percent'          → percentage or any other non-resolvable value
+ *
+ * Only the `width` and `height` properties are normalized; other props are
+ * captured verbatim as the raw RHS string (callers don't currently need them).
+ *
+ * @param {string} tssContent - The full purged TSS (in-memory string).
+ * @returns {Map<string, { width?: number|'auto'|'fill'|'percent', height?: number|'auto'|'fill'|'percent', _raw: string }>}
+ */
+export function parseTssMap(tssContent) {
+  const map = new Map()
+  if (typeof tssContent !== 'string' || !tssContent) return map
+
+  const lines = tssContent.split(/\r?\n/)
+  for (const line of lines) {
+    const stripped = stripLineComment(line)
+    const match = stripped.match(CLASS_LINE)
+    if (!match) continue
+
+    const className = match[1]
+    const body = match[2]
+    const props = parsePropBody(body)
+    map.set(className, { ...props, _raw: body.trim() })
+  }
+  return map
+}
+
+// Drop trailing `// comment` so it doesn't break the brace-matching regex.
+function stripLineComment(line) {
+  let inSingle = false
+  let inDouble = false
+  for (let i = 0; i < line.length - 1; i++) {
+    const c = line[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (c === '/' && line[i + 1] === '/' && !inSingle && !inDouble) {
+      return line.slice(0, i)
+    }
+  }
+  return line
+}
+
+function parsePropBody(body) {
+  const out = {}
+  for (const pair of splitTopLevelCommas(body)) {
+    const colon = findTopLevelColon(pair)
+    if (colon === -1) continue
+    const key = pair.slice(0, colon).trim()
+    const value = pair.slice(colon + 1).trim()
+    if (key === 'width' || key === 'height') {
+      out[key] = normalizeDimensionValue(value)
+    }
+  }
+  return out
+}
+
+function splitTopLevelCommas(body) {
+  const out = []
+  let depth = 0
+  let inSingle = false
+  let inDouble = false
+  let last = 0
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (!inSingle && !inDouble) {
+      if (c === '(' || c === '[' || c === '{') depth++
+      else if (c === ')' || c === ']' || c === '}') depth--
+      else if (c === ',' && depth === 0) {
+        out.push(body.slice(last, i))
+        last = i + 1
+      }
+    }
+  }
+  out.push(body.slice(last))
+  return out.filter(s => s.trim().length > 0)
+}
+
+function findTopLevelColon(pair) {
+  let inSingle = false
+  let inDouble = false
+  let depth = 0
+  for (let i = 0; i < pair.length; i++) {
+    const c = pair[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (!inSingle && !inDouble) {
+      if (c === '(' || c === '[' || c === '{') depth++
+      else if (c === ')' || c === ']' || c === '}') depth--
+      else if (c === ':' && depth === 0) return i
+    }
+  }
+  return -1
+}
+
+// Recognize: numeric literals, Ti.UI.SIZE/FILL, quoted percentages or other
+// non-numeric strings. Anything else falls into 'percent' (the catch-all for
+// "this can't be turned into a dp number"). The label is historic — it
+// originally only meant "string with %" — keeping it avoids ripple changes.
+function normalizeDimensionValue(raw) {
+  const trimmed = raw.trim()
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed)
+  if (/^Ti\.UI\.SIZE$/i.test(trimmed)) return 'auto'
+  if (/^Ti\.UI\.FILL$/i.test(trimmed)) return 'fill'
+  return 'percent'
+}

package/src/dev/builders/tailwind-builder.js

@@ -0,0 +1,18 @@
+/**
+ * PurgeTSS - Utilities Builder (Development entry point)
+ *
+ * Thin CLI wrapper invoked by the `build:tailwind` npm script.
+ * Generates: ./dist/utilities.tss
+ *
+ * @author César Estrada
+ */
+
+import { autoBuildUtilitiesTSS } from '../../core/builders/auto-utilities-builder.js'
+
+export function buildTailwind() {
+  autoBuildUtilitiesTSS()
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  buildTailwind()
+}

package/src/shared/config-manager.js

@@ -23,6 +23,7 @@ import {
 } from './constants.js'
 import { logger } from './logger.js'
 import { makeSureFolderExists } from './utils.js'
+import { validateConfig } from './validation/config-validator.js'
 
 // Create require for ESM compatibility
 const require = createRequire(import.meta.url)
@@ -105,6 +106,71 @@ export function migrateConfigIfNeeded() {
   }
 }
 
+// Tracks configs already warned about in this process so the deprecation
+// notice prints once per session even if getConfigFile() is called many times.
+const _warnedLegacyBrand = new Set()
+
+/**
+ * Migrate the flat pre-7cb5890 `brand:` schema (padding as number, iosPadding,
+ * bgColor, darkBgColor, top-level notification/splash) into the grouped
+ * schema downstream code expects. Mutates in place; if both legacy and new
+ * keys coexist, the new key wins. Emits ONE warning per config path per session.
+ */
+function normalizeLegacyBrand(configFile, sourcePath) {
+  const brand = configFile.brand
+  if (!brand || typeof brand !== 'object') return
+
+  const hits = []
+
+  if (brand.padding != null && typeof brand.padding !== 'object') {
+    const value = brand.padding
+    brand.padding = { androidLegacy: value, androidAdaptive: value }
+    hits.push(`brand.padding: ${JSON.stringify(value)} → brand.padding.androidLegacy + brand.padding.androidAdaptive`)
+  }
+
+  if ('iosPadding' in brand) {
+    brand.padding = (brand.padding && typeof brand.padding === 'object') ? brand.padding : {}
+    brand.padding.ios = brand.padding.ios ?? brand.iosPadding
+    hits.push('brand.iosPadding → brand.padding.ios')
+    delete brand.iosPadding
+  }
+
+  if ('bgColor' in brand) {
+    brand.colors = brand.colors ?? {}
+    brand.colors.background = brand.colors.background ?? brand.bgColor
+    hits.push('brand.bgColor → brand.colors.background')
+    delete brand.bgColor
+  }
+
+  if ('darkBgColor' in brand) {
+    brand.ios = brand.ios ?? {}
+    brand.ios.darkBackground = brand.ios.darkBackground ?? brand.darkBgColor
+    hits.push('brand.darkBgColor → brand.ios.darkBackground')
+    delete brand.darkBgColor
+  }
+
+  if ('notification' in brand) {
+    brand.android = brand.android ?? {}
+    brand.android.notification = brand.android.notification ?? brand.notification
+    hits.push('brand.notification → brand.android.notification')
+    delete brand.notification
+  }
+
+  if ('splash' in brand) {
+    brand.android = brand.android ?? {}
+    brand.android.splash = brand.android.splash ?? brand.splash
+    hits.push('brand.splash → brand.android.splash')
+    delete brand.splash
+  }
+
+  if (hits.length > 0 && !_warnedLegacyBrand.has(sourcePath)) {
+    _warnedLegacyBrand.add(sourcePath)
+    logger.warn('Legacy brand: schema detected in purgetss/config.cjs — auto-migrated in memory:')
+    for (const hit of hits) logger.item(`  • ${hit}`)
+    logger.item('  Update purgetss/config.cjs to the new grouped schema to silence this warning.')
+  }
+}
+
 /**
  * Get configuration file with fallback to default template
  * Maintains exact same logic as original getConfigFile()
@@ -113,9 +179,11 @@ export function migrateConfigIfNeeded() {
  */
 export function getConfigFile() {
 
-  const configFile = (fs.existsSync(projectsConfigJS))
-    ? require(projectsConfigJS)
-    : require(srcConfigFile)
+  const sourcePath = fs.existsSync(projectsConfigJS) ? projectsConfigJS : srcConfigFile
+  const configFile = require(sourcePath)
+
+  validateConfig(configFile, sourcePath)
+  normalizeLegacyBrand(configFile, sourcePath)
 
   // Apply default values following template structure
   configFile.purge = configFile.purge ?? {}
@@ -133,6 +201,7 @@ export function getConfigFile() {
   configFile.brand.padding.ios = parsePadding(configFile.brand.padding.ios ?? 4, 'brand.padding.ios')
   configFile.brand.padding.androidLegacy = parsePadding(configFile.brand.padding.androidLegacy ?? 10, 'brand.padding.androidLegacy')
   configFile.brand.padding.androidAdaptive = parsePadding(configFile.brand.padding.androidAdaptive ?? 19, 'brand.padding.androidAdaptive')
+  configFile.brand.padding.featureGraphic = parsePadding(configFile.brand.padding.featureGraphic ?? 12, 'brand.padding.featureGraphic')
   configFile.brand.android = configFile.brand.android ?? {}
   configFile.brand.android.notification = configFile.brand.android.notification ?? false
   configFile.brand.android.splash = configFile.brand.android.splash ?? false

package/src/shared/error-reporter.js

@@ -0,0 +1,117 @@
+/**
+ * Centralized error reporter for syntax errors detected by PurgeTSS.
+ *
+ * Visual format matches the patterns already used by:
+ *   - XML Syntax Error (src/cli/commands/purge.js, "compact" variant)
+ *   - Class Syntax Error (src/cli/utils/unsupported-class-reporter.js)
+ *   - XML Syntax Error with Context (src/cli/commands/purge.js, "context" variant)
+ *
+ * Those call sites are NOT migrated yet — they keep their own inline formatters
+ * to avoid any chance of visual regression. New validators (config-validator)
+ * use this module so the look is consistent going forward.
+ *
+ * Two output paths:
+ *   - formatSyntaxError(opts) → { header, lines } suitable for logger.block(...)
+ *   - throwSyntaxError(opts)  → throws an Error whose .message is the full
+ *                               pre-rendered string (for call sites that
+ *                               propagate errors via catch handlers).
+ */
+
+import chalk from 'chalk'
+import path from 'path'
+import { logger } from './logger.js'
+
+/**
+ * Build the displayable parts of a syntax error.
+ *
+ * @param {Object} opts
+ * @param {string} opts.type      - Short name shown in the header, e.g. 'Config', 'XML', 'Class'.
+ * @param {string} [opts.file]    - File path (will be made relative to cwd).
+ * @param {string|number} [opts.path] - Dotted JSON path (optional, for config errors).
+ * @param {number} [opts.line]    - Line number where the error occurred.
+ * @param {string} [opts.content] - One-line snippet of the offending line.
+ * @param {string[]} [opts.contextLines] - Full file lines (1-based; pass src.split('\n') OK with 0-based,
+ *                                          but `line` must point to a 1-based number; we slice ±2).
+ * @param {string} opts.issue     - Description of what is wrong.
+ * @param {string} opts.fix       - Suggested correction.
+ * @returns {{ header: string, lines: string[] }}
+ */
+export function formatSyntaxError(opts) {
+  const {
+    type,
+    file,
+    path: jsonPath,
+    line,
+    content,
+    contextLines,
+    issue,
+    fix
+  } = opts
+
+  const lines = []
+
+  if (file) {
+    const relative = path.relative(process.cwd(), file) || file
+    lines.push(`File: ${chalk.yellow(`"${relative}"`)}`)
+  }
+  if (jsonPath) {
+    lines.push(`Path: ${chalk.yellow(jsonPath)}`)
+  }
+  if (line != null) {
+    lines.push(`Line: ${chalk.yellow(line)}`)
+  }
+
+  // Context block: ± 2 lines around the offending line.
+  if (Array.isArray(contextLines) && line) {
+    const total = contextLines.length
+    const startLine = Math.max(1, line - 2)
+    const endLine = Math.min(total, line + 2)
+
+    lines.push('')
+    lines.push(chalk.gray('Context:'))
+    for (let i = startLine; i <= endLine; i++) {
+      const isTarget = i === line
+      const prefix = isTarget ? chalk.red('>>>') : chalk.gray('   ')
+      const text = contextLines[i - 1] || ''
+      lines.push(`${prefix} ${chalk.gray(String(i).padStart(3, ' '))}: ${text}`)
+    }
+  } else if (content) {
+    lines.push(`Content: ${chalk.yellow(`"${content}"`)}`)
+  }
+
+  lines.push('')
+  lines.push(chalk.red(`Issue: ${issue}`))
+  lines.push(`${chalk.green('Fix:')} ${fix}`)
+
+  return {
+    header: chalk.red(`${type} Syntax Error`),
+    lines
+  }
+}
+
+/**
+ * Log the syntax error directly via logger.block.
+ * Use when you want the error rendered now and execution to continue
+ * (or stop via a sentinel afterward).
+ */
+export function logSyntaxError(opts) {
+  const { header, lines } = formatSyntaxError(opts)
+  logger.block(header, ...lines)
+}
+
+/**
+ * Throw an Error whose .message is the fully rendered report.
+ * Use when the error must bubble up through a catch handler that prints
+ * `error.message` (e.g. the top-level CLI catch in bin/purgetss).
+ *
+ * The thrown Error includes `isSyntaxError: true` so callers can distinguish
+ * presentation-ready errors from generic runtime failures.
+ */
+export function throwSyntaxError(opts) {
+  const { header, lines } = formatSyntaxError(opts)
+  const text = `\n::PurgeTSS:: ${header}\n` + lines.map(l => '   ' + l).join('\n') + '\n'
+  const err = new Error(text)
+  err.isSyntaxError = true
+  err.syntaxErrorType = opts.type
+  throw err
+}