purgetss 7.7.1 → 7.11.1

package/src/shared/logger.js

@@ -77,6 +77,14 @@ export const logger = {
     _emit(chalk.yellow(args.join(' ')) + ' file created!')
   },
 
+  /**
+   * Log success messages in green
+   * @param {...any} args - Arguments to log
+   */
+  success: function(...args) {
+    _emit(chalk.green(args.join(' ')))
+  },
+
   /**
    * Enable section mode. The next info/warn/error/file call becomes the
    * ::PurgeTSS:: header; subsequent calls print indented without prefix.
@@ -122,6 +130,10 @@ export const logger = {
   }
 }
 
+// Aliases: long-form `warning` matches the semantic of `warn`. Multiple
+// callsites across branding/images/svg flows expect this name.
+logger.warning = logger.warn
+
 /**
  * Get current debug mode status
  * @returns {boolean} Current debug status

package/src/shared/semantic-helpers.js

@@ -0,0 +1,143 @@
+/**
+ * PurgeTSS - Semantic Colors Helpers
+ *
+ * Auto-derivation of semantic color keys with applied alpha for opacity
+ * modifiers (e.g. `bg-surface/65`). Mutates `semantic.colors.json` idempotently
+ * by adding `<originalKey>_<alphaPercent>` entries with `{ color, alpha }` for
+ * `light` and `dark`.
+ *
+ * Lifecycle:
+ *   - Names of semantic colors are tracked via `registerSemanticName()` while
+ *     the utilities builder expands `theme.extend.colors`.
+ *   - Hooks in `tailwind-purger` and `compileApplyDirectives` call
+ *     `deriveAlphaKey()` before falling back to warn/throw on missing hex.
+ *   - CLI commands flush the cached JSON to disk via `flushSemanticColors()`
+ *     at the end of their run.
+ *
+ * @fileoverview Semantic color auto-derivation for opacity modifiers
+ * @since 7.9.0
+ */
+
+import fs from 'fs'
+import { getSemanticColorsPath } from '../cli/utils/project-detection.js'
+
+const _semanticNames = new Set()
+let _cache = null
+let _dirty = false
+let _lastMtime = 0
+let _lastPath = null
+
+/**
+ * Reset all in-memory state. Intended for tests; not part of the public API.
+ */
+export function _resetSemanticHelpersState() {
+  _semanticNames.clear()
+  _cache = null
+  _dirty = false
+  _lastMtime = 0
+  _lastPath = null
+}
+
+/**
+ * Track a name that resolves to a semantic color (string, non-hex). Called by
+ * the utilities builder while expanding `theme.extend.colors`.
+ *
+ * @param {string} name
+ */
+export function registerSemanticName(name) {
+  if (typeof name === 'string' && name.length > 0) _semanticNames.add(name)
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isSemanticColorName(name) {
+  return _semanticNames.has(name)
+}
+
+/**
+ * Load `semantic.colors.json` for the current project. Cached by mtime so
+ * repeated calls in the same build are cheap. The cache is invalidated when
+ * the file mtime changes on disk (relevant for watch-mode cycles where the
+ * JSON gets rewritten between runs).
+ *
+ * @returns {Object} parsed JSON, or `{}` when the file doesn't exist
+ */
+export function loadSemanticColors() {
+  const p = getSemanticColorsPath()
+  if (!fs.existsSync(p)) {
+    _cache = {}
+    _lastMtime = 0
+    _lastPath = p
+    return _cache
+  }
+  const mtime = fs.statSync(p).mtimeMs
+  if (_cache && _lastPath === p && mtime === _lastMtime) return _cache
+  _cache = JSON.parse(fs.readFileSync(p, 'utf8'))
+  _lastMtime = mtime
+  _lastPath = p
+  return _cache
+}
+
+/**
+ * Derive a semantic key with the requested alpha applied. Idempotent: if the
+ * derived key already exists with matching values it's reused; if it exists
+ * with conflicting values an Error is thrown so manual edits aren't silently
+ * overwritten.
+ *
+ * @param {string} baseKey - The original semantic key (e.g. `surfaceColor`).
+ * @param {number|string} alphaPercent - Integer 0..100 (e.g. 65).
+ * @returns {string|null} The derived key, or `null` if `baseKey` isn't in the JSON.
+ */
+export function deriveAlphaKey(baseKey, alphaPercent) {
+  const semantic = loadSemanticColors()
+  const base = semantic[baseKey]
+  if (!base) return null
+
+  const alphaStr = String(alphaPercent)
+  const newKey = `${baseKey}_${alphaStr}`
+
+  const lightHex = typeof base.light === 'string' ? base.light : base.light?.color
+  const darkHex = typeof base.dark === 'string' ? base.dark : base.dark?.color
+
+  if (semantic[newKey]) {
+    const existing = semantic[newKey]
+    const existingLightHex = typeof existing.light === 'string' ? existing.light : existing.light?.color
+    const existingDarkHex = typeof existing.dark === 'string' ? existing.dark : existing.dark?.color
+    const existingLightAlpha = typeof existing.light === 'string' ? null : existing.light?.alpha
+    const existingDarkAlpha = typeof existing.dark === 'string' ? null : existing.dark?.alpha
+
+    if (
+      existingLightHex !== lightHex ||
+      existingDarkHex !== darkHex ||
+      existingLightAlpha !== alphaStr ||
+      existingDarkAlpha !== alphaStr
+    ) {
+      throw new Error(
+        `Conflict: "${newKey}" already exists in semantic.colors.json with different values. Manual edit detected — resolve before continuing.`
+      )
+    }
+    return newKey
+  }
+
+  semantic[newKey] = {
+    light: { color: lightHex, alpha: alphaStr },
+    dark: { color: darkHex, alpha: alphaStr }
+  }
+  _dirty = true
+  return newKey
+}
+
+/**
+ * Persist any pending derivations back to `semantic.colors.json`. No-op when
+ * nothing changed. Writes a trailing newline for clean git diffs.
+ */
+export function flushSemanticColors() {
+  if (!_dirty) return
+  const p = getSemanticColorsPath()
+  fs.writeFileSync(p, JSON.stringify(_cache, null, 2) + '\n')
+  _dirty = false
+  _lastMtime = fs.statSync(p).mtimeMs
+  _lastPath = p
+}

package/src/shared/validation/config-validator.js

@@ -0,0 +1,167 @@
+/**
+ * Config validator for purgetss/config.cjs.
+ *
+ * Validates known fields in the user's config and, on type mismatch, throws an
+ * error formatted via the shared error-reporter so that File / Path / Line /
+ * Context / Issue / Fix are obvious instead of crashing downstream with
+ * cryptic messages like `rule.startsWith is not a function`.
+ *
+ * Currently validates:
+ *   - theme.fontFamily.* and theme.extend.fontFamily.*
+ *       Expected: string. Detects Tailwind-style arrays (`['Inter', 'sans-serif']`)
+ *       and reports with a fix snippet.
+ *
+ * Extend by adding entries to FIELD_RULES below. Each rule names the JSON
+ * path, the expected JS type, and a tip explaining the fix.
+ */
+
+import fs from 'fs'
+import * as acorn from 'acorn'
+import chalk from 'chalk'
+import { throwSyntaxError } from '../error-reporter.js'
+
+// ─── Field rules ────────────────────────────────────────────────────────────
+const FIELD_RULES = [
+  {
+    parent: 'theme.fontFamily',
+    expected: 'string',
+    tipFor: (key, value) => buildFontFamilyTip(key, value)
+  },
+  {
+    parent: 'theme.extend.fontFamily',
+    expected: 'string',
+    tipFor: (key, value) => buildFontFamilyTip(key, value)
+  }
+]
+
+function buildFontFamilyTip(key, value) {
+  if (Array.isArray(value)) {
+    const first = value.length > 0 ? value[0] : 'FontName'
+    return `Use a string instead of an array. Tailwind-style fallback fonts are not supported — Titanium accepts a single font family per element. Change to: ${chalk.green(`${quoteKey(key)}: '${first}'`)}`
+  }
+  return `Expected a string. Change to: ${chalk.green(`${quoteKey(key)}: 'FontName'`)}`
+}
+
+function quoteKey(key) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `'${key}'`
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate the loaded config object against FIELD_RULES.
+ * Throws a formatted Error (via error-reporter) on the first mismatch found.
+ *
+ * @param {Object} configObject - The required()'d config object.
+ * @param {string} configPath - Absolute path to the config.cjs file.
+ */
+export function validateConfig(configObject, configPath) {
+  for (const rule of FIELD_RULES) {
+    const parent = getByPath(configObject, rule.parent)
+    if (!parent || typeof parent !== 'object') continue
+
+    for (const key of Object.keys(parent)) {
+      const value = parent[key]
+      if (typeof value === rule.expected) continue
+
+      const jsonPath = `${rule.parent}.${key}`
+      const source = safeReadFile(configPath)
+      const contextLines = source ? source.split('\n') : null
+      const line = contextLines ? findPropertyLine(source, jsonPath) : null
+
+      throwSyntaxError({
+        type: 'Config',
+        file: configPath,
+        path: jsonPath,
+        line,
+        contextLines,
+        issue: `Expected ${rule.expected}, got ${describeType(value)} (${previewValue(value)})`,
+        fix: rule.tipFor(key, value)
+      })
+    }
+  }
+}
+
+// ─── AST scan to find the line where a dotted-path property is declared ─────
+
+function findPropertyLine(source, dottedPath) {
+  let ast
+  try {
+    ast = acorn.parse(source, { ecmaVersion: 'latest', locations: true })
+  } catch (_e) {
+    return null
+  }
+
+  let found = null
+
+  function walk(node, currentPath) {
+    if (found || !node || typeof node !== 'object') return
+
+    if (node.type === 'ObjectExpression') {
+      for (const prop of node.properties) {
+        if (prop.type !== 'Property') continue
+        const keyName = prop.key.name || prop.key.value
+        if (keyName == null) continue
+        const nextPath = currentPath ? `${currentPath}.${keyName}` : keyName
+
+        if (nextPath === dottedPath && prop.loc) {
+          found = prop.loc.start.line
+          return
+        }
+        walk(prop.value, nextPath)
+        if (found) return
+      }
+      return
+    }
+
+    if (node.type === 'AssignmentExpression') {
+      walk(node.right, currentPath)
+      return
+    }
+
+    for (const key of Object.keys(node)) {
+      if (key === 'loc' || key === 'start' || key === 'end' || key === 'range') continue
+      const child = node[key]
+      if (Array.isArray(child)) {
+        for (const c of child) {
+          walk(c, currentPath)
+          if (found) return
+        }
+      } else if (child && typeof child === 'object') {
+        walk(child, currentPath)
+      }
+    }
+  }
+
+  walk(ast, '')
+  return found
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function describeType(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'Array'
+  return typeof value
+}
+
+function previewValue(value) {
+  try {
+    const json = JSON.stringify(value)
+    return json && json.length > 60 ? json.slice(0, 57) + '...' : json
+  } catch (_e) {
+    return String(value)
+  }
+}
+
+function getByPath(obj, dottedPath) {
+  return dottedPath.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), obj)
+}
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8')
+  } catch (_e) {
+    return null
+  }
+}