purgetss 7.7.1 → 7.11.1

package/README.md

@@ -377,6 +377,34 @@ Button: {
 
 ## Recent changes
 
+### v7.11.0
+
+- **SVG-aware compile-time image pipeline as a post-step of `purgetss`.** When views or controllers reference `image="/images/<sub>/<name>.svg"` (or `backgroundImage="..."`) alongside utility classes that resolve to numeric width/height (`w-32`, `w-(300)`, `h-auto`, …), purge now compiles those SVGs into the 8 Titanium density variants (5 Android + 3 iPhone PNGs) using dimensions resolved from `app.tss` after the regular purge finishes. Titanium loads the generated `.png` automatically at runtime when the XML/Controller references `.svg`. Cache lives at `purgetss/.cache/svg-images.json` (add to `.gitignore`). The SVG attribute stays untouched in your source — never rewritten.
+- **`images.files` array in `config.cjs` as per-file override.** Pin width/height for individual files in `purgetss/images/`: `[{ filename: 'images/logos/logo.png', width: 128, height: 52 }, ...]`. When `purgetss images` runs, entries override the source's natural dimensions; CLI `--width` still wins over both. For SVGs detected by the purge SVG pipeline, entries populate automatically (subject to `images.autoSync`). Raster entries you add by hand survive subsequent runs untouched.
+- **`images.autoSync` boolean (default `true`).** Opt-out for devs who manage `images.files` by hand — when `false`, purge still computes dimensions and generates PNGs, but never writes back to `config.cjs`.
+- **Quality warning when a raster source is too small for its declared width.** Sources smaller than `width × 4` (the xxxhdpi/@4x requirement) trigger a non-blocking warning with exact numbers. SVGs are exempt (vector, no upscale penalty).
+
+### The 4× source convention
+
+Both `purgetss images` and `purgetss brand` treat each source file as the **xxxhdpi/@4x master**: your file's pixel dimensions ARE the largest density, and smaller densities derive at 1/4, 1.5/4, 2/4, 3/4. A 256 px PNG produces a 64 px `@1x/mdpi`. If you want 64 dp at `@1x`, drop a 256 px source.
+
+Override per file via `images.files` in `config.cjs` (or the brand-specific fields under `brand.logos`/`brand.padding`). The convention is the default fallback — entries override it on a per-file basis. CLI flags like `--width` always win over both.
+
+### v7.10.0
+
+- **`MarketplaceArtworkFeature.png` (Google Play Feature Graphic) auto-generated by `purgetss brand`.** Every brand run now writes a 1024×500 banner to the project root alongside the existing `iTunesConnect.png` and `MarketplaceArtwork.png` submission assets. Master logo centered both axes inside the rectangular canvas with 12% vertical padding default, flattened on `brand.colors.background`. Override paths: CLI `--feature-graphic-padding <n>`, config `brand.padding.featureGraphic`, and optional `purgetss/brand/logo-feature.{svg,png}` (or CLI `--feature-logo` / `brand.logos.featureGraphic`) for a dedicated source. Submission artwork only — file goes to the project root for upload to the Play Console, not bundled into the APK.
+- **`--opacity <n>`, `--padding <n>`, and `--output <relpath>` flags for `purgetss images`.** Three CLI-only per-asset transformations. `--opacity` multiplies the alpha channel of every generated density (0–100, integer). `--padding` shrinks the rendered image inside each density canvas with symmetric transparent borders (0–40%). `--output` overrides basename + subpath relative to the images output root (single-file source only; no extension, no absolute paths, no `..`). All three preserve the multi-density plural-output convention. Combines naturally for placeholder images: `purgetss images purgetss/brand/logo.svg --opacity 30 --padding 15 --output 'logos/default' --format png`.
+- **`brand --padding <n>` shortcut bug fix.** Pre-existing bug: help text and docs described `--padding` as a shortcut that "sets BOTH Android paddings to the same value", but only `androidAdaptivePadding` read the shortcut from the fallback chain — `androidLegacyPadding` skipped it. `purgetss brand --padding 17` actually produced `androidAdaptive=17, androidLegacy=10` silently. Fix adds the missing fallback so `--padding` now sets both Android paddings to the same value as documented.
+- **`purgetss images --format png` now writes truecolor RGBA, not palette-quantized PNG-8.** Passing `quality` to Sharp's `.png()` was silently triggering palette mode, banding subtle gradients in logos, placeholders, and any image with smooth color transitions. Drop of one parameter (`quality` is meaningless for PNG anyway — only `compressionLevel` matters, and that stays at 9 lossless). Brand outputs (icons, splash, marketplace) were never affected because their generators don't pass `quality` to `.png()`.
+
+### v7.8.0
+
+- **`--width <n>` flag for `images`.** Pin Android `mdpi` / iPhone `@1x` to a specific width in pixels (e.g. `purgetss images logo.svg --width 256`); larger scales derive at ×1.5, ×2, ×3, ×4 with height staying proportional. Recommended when the source is an SVG export from Affinity / Illustrator with a disproportionate viewBox — the legacy 4× master convention produces unpredictable sizes there, and the new flag pins the result exactly. When you pass an SVG without `--width`, `images` now prints a one-time hint suggesting the flag, then falls back to the legacy behavior.
+- **Class syntax pre-validation.** `purgetss` now halts with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known authoring mistakes in your class names: inverted negative sign (`top-(-10)` → `-top-(10)`), square brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`).
+- All offenders are reported in a single run, so you can fix them in one pass.
+- Generic unknown classes (typos, vendor utilities not enabled, custom classes not yet declared) are NOT flagged by the validator — they continue to flow silently into the `// Unused or unsupported classes` block in `app.tss`, exactly as in previous versions.
+- **Arbitrary-value parser no longer crashes on negative values inside parentheses.** Classes like `top-(-10)`, `mt-(-5)`, or `origin-(-10,-20)` used to trigger a `Cannot read properties of null (reading 'pop')` exception. The parser was rewritten to extract the `(...)` portion first, so a `-` inside the value never breaks the split — and the new pre-validator catches the inverted-sign form before it gets that far.
+
 ### v7.7.0
 
 - `brand` now uses grouped config sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`.

package/bin/purgetss

@@ -76,6 +76,7 @@ program
       }
     } catch (error) {
       console.error(chalk.red('Error running command:'), error.message)
+      if (process.env.PURGETSS_DEBUG) console.error(error.stack)
       process.exit(1)
     }
   })
@@ -267,6 +268,7 @@ Logos auto-discovered from ${chalk.cyan('purgetss/brand/')}:
   ${chalk.yellow('logo-dark.{svg,png}')}     optional — iOS 18+ dark variant
   ${chalk.yellow('logo-tinted.{svg,png}')}   optional — iOS 18+ tinted variant
   ${chalk.yellow('logo-splash.{svg,png}')}   optional — Android 12+ splash icon override
+  ${chalk.yellow('logo-feature.{svg,png}')}  optional — Google Play Feature Graphic override
 
 Defaults come from the ${chalk.cyan('brand:')} section in ${chalk.cyan('purgetss/config.cjs')}.
 The recommended workflow is: put files in ${chalk.cyan('purgetss/brand/')}, then only use config/CLI for overrides.
@@ -276,6 +278,7 @@ Generates:
   ${chalk.yellow('DefaultIcon.png')}/${chalk.yellow('DefaultIcon-ios.png')}                          Root icons (alpha + flattened)
   ${chalk.yellow('DefaultIcon-Dark.png')}/${chalk.yellow('DefaultIcon-Tinted.png')}                  iOS 18+ variants (Apple HIG specs)
   ${chalk.yellow('iTunesConnect.png')}/${chalk.yellow('MarketplaceArtwork.png')}                     App Store + Play Store artwork
+  ${chalk.yellow('MarketplaceArtworkFeature.png')}                              Google Play Feature Graphic (1024×500)
   ${chalk.yellow('mipmap-*/ic_launcher_{foreground,background,monochrome}.png')}  Android adaptive × 5
   ${chalk.yellow('mipmap-*/ic_launcher.png')}                                     Android legacy × 5
   ${chalk.yellow('mipmap-anydpi-v26/ic_launcher.xml')}                            Adaptive icon binder
@@ -298,6 +301,8 @@ Examples:
   ${chalk.cyan('purgetss brand')} --bg-color "#0B1326"                      # override config bg
   ${chalk.cyan('purgetss brand')} --android-adaptive-padding 22             # more breathing room for adaptive icons
   ${chalk.cyan('purgetss brand')} --icon-logo app-icon.svg                  # separate square Android icon
+  ${chalk.cyan('purgetss brand')} --feature-logo banner.svg                 # custom Feature Graphic logo
+  ${chalk.cyan('purgetss brand')} --feature-graphic-padding 15              # more breathing room on Feature Graphic
   ${chalk.cyan('purgetss brand')} --dark-bg-color "#1C1C1E" --no-tinted     # customize dark, skip tinted
   ${chalk.cyan('purgetss brand')} --dry-run                                 # preview without writing
   ${chalk.cyan('purgetss brand')} --cleanup-legacy --dry-run                # preview legacy cleanup
@@ -307,11 +312,13 @@ Examples:
   .option('--android-adaptive-padding <n>', 'Adaptive icon safe-zone % (default: 19)', (v) => parseInt(v, 10))
   .option('--android-legacy-padding <n>', 'Legacy ic_launcher.png padding % (default: 10)', (v) => parseInt(v, 10))
   .option('--ios-padding <n>', 'iOS aesthetic % (typical 2-6, default: 4)', (v) => parseInt(v, 10))
+  .option('--feature-graphic-padding <n>', 'Feature Graphic vertical % (default: 12)', (v) => parseInt(v, 10))
   .option('--notification', 'Also generate ic_stat_notify.png × 5 densities')
   .option('--splash', 'Also generate Android 12+ splash_icon.png × 5 densities')
   .option('--icon-logo <path>', 'Override the Android launcher icon logo (otherwise purgetss/brand/logo-icon.{svg,png})')
   .option('--monochrome-logo <path>', 'Override the monochrome logo (otherwise purgetss/brand/logo-mono.{svg,png})')
   .option('--splash-logo <path>', 'Override the Android 12+ splash icon logo (otherwise purgetss/brand/logo-splash.{svg,png})')
+  .option('--feature-logo <path>', 'Override the Feature Graphic logo (otherwise purgetss/brand/logo-feature.{svg,png})')
   .option('--dark-bg-color <hex>', 'Opt into opaque dark bg for DefaultIcon-Dark.png (default: transparent per Apple HIG)')
   .option('--dark-logo <path>', 'Override the dark logo (otherwise purgetss/brand/logo-dark.{svg,png})')
   .option('--tinted-logo <path>', 'Override the tinted logo (otherwise purgetss/brand/logo-tinted.{svg,png})')
@@ -353,6 +360,13 @@ Writes directly to the project (auto-detects Alloy vs Classic):
 Defaults come from the ${chalk.cyan('images:')} section in ${chalk.cyan('purgetss/config.cjs')}.
 CLI flags always win over config values.
 
+Sizing:
+  By default, sources are treated as 4× masters (xxxhdpi/@4x); all other
+  scales derive at 1/4, 1.5/4, 2/4, 3/4 of the source's natural pixels.
+  Pass ${chalk.cyan('--width <n>')} to pin Android mdpi (= iPhone @1x) to a specific width;
+  larger scales derive as ×1.5, ×2, ×3, ×4 (height stays proportional).
+  Recommended for SVGs from vector editors with oversized viewBoxes.
+
 Examples:
   ${chalk.cyan('purgetss images')}                                  # uses purgetss/images/ + config
   ${chalk.cyan('purgetss images')} ./docs/screenshots               # scope to one folder
@@ -361,12 +375,21 @@ Examples:
   ${chalk.cyan('purgetss images')} --ios                            # iPhone scales only
   ${chalk.cyan('purgetss images')} --format webp                    # convert all outputs to WebP
   ${chalk.cyan('purgetss images')} --format png --quality 95
+  ${chalk.cyan('purgetss images')} logo.svg --width 256             # pin @1x/mdpi to 256 px wide
+  ${chalk.cyan('purgetss images')} banner.svg --width 512 --format webp
+  ${chalk.cyan('purgetss images')} logo.svg --opacity 50 --format png  # semi-transparent placeholder, all densities
+  ${chalk.cyan('purgetss images')} purgetss/brand/logo.svg --opacity 40 --output 'logos/loading' --format png
+  ${chalk.cyan('purgetss images')} purgetss/brand/logo.png --opacity 30 --padding 15 --output 'logos/default' --format png
   ${chalk.cyan('purgetss images')} --dry-run
 `)
   .option('--android', 'Generate only Android density variants (skip iPhone)')
   .option('--ios', 'Generate only iPhone scale variants (skip Android)')
   .option('--format <ext>', 'Convert all outputs to this format: webp|jpeg|png|avif|gif|tiff')
   .option('--quality <n>', 'JPEG/WebP/AVIF quality 0-100 (default: 85)', (v) => parseInt(v, 10))
+  .option('--width <n>', 'Target width in px for @1x/mdpi (other scales derive: ×1.5, ×2, ×3, ×4)', (v) => parseInt(v, 10))
+  .option('--opacity <n>', 'Apply alpha 0-100 to all generated densities (e.g. 50 = 50% transparent)', (v) => parseInt(v, 10))
+  .option('--padding <n>', 'Symmetric padding 0-40% inside each density canvas (shrinks the logo, adds transparent borders)', (v) => parseInt(v, 10))
+  .option('--output <relpath>', 'Override basename + subfolder relative to images/ (single source only, no extension; --format decides ext)')
   .option('--project <path>', 'Project root (default: cwd)')
   .option('--dry-run', 'Preview without writing any files')
   .option('-y, --yes', 'Skip the overwrite confirmation prompt')

package/dist/purgetss.ui.js

@@ -1,4 +1,4 @@
-// PurgeTSS v7.7.1
+// PurgeTSS v7.11.1
 // Created by César Estrada
 // https://purgetss.com
 

package/lib/templates/create/index.xml

@@ -3,7 +3,7 @@
     <ScrollView class="vertical mx-4">
       <!-- Header -->
       <Label class="text-center text-3xl font-bold text-white">Welcome to PurgeTSS</Label>
-      <Label class="text-center text-sm text-white">Tailwind-inspired utility classes for Titanium/Alloy</Label>
+      <Label class="text-center text-sm text-white">Utility-first styling for Titanium/Alloy</Label>
 
       <!-- Typography Examples -->
       <Label class="mt-4 text-center text-xl font-semibold text-white">Typography</Label>

package/lib/templates/purgetss.config.js.cjs

@@ -36,7 +36,9 @@ module.exports = {
   images: {
     quality: 85,             // JPEG/WebP/AVIF quality (0-100)
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
-    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
+    confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+    files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
   },
   theme: {
     extend: {}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.7.1",
+  "version": "7.11.1",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"
@@ -17,7 +17,7 @@
     "dist/*.tss",
     "dist/configs/",
     "assets/fonts/",
-    "experimental/completions2.js"
+    "src/core/builders/auto-utilities-builder.js"
   ],
   "publishConfig": {
     "access": "public"

package/src/cli/commands/build.js

@@ -14,6 +14,7 @@ import { alloyProject } from '../../shared/utils.js'
 import { ensureConfig } from '../../shared/config-manager.js'
 import { buildTailwindBasedOnConfigOptions } from '../../core/builders/tailwind-builder.js'
 import { createDefinitionsFile } from './init.js'
+import { flushSemanticColors } from '../../shared/semantic-helpers.js'
 
 // Import FontAwesome functions from their new modular location
 import { buildFontAwesome, buildFontAwesomeJS } from '../../dev/builders/fontawesome-builder.js'
@@ -28,10 +29,14 @@ import { buildFontAwesome, buildFontAwesomeJS } from '../../dev/builders/fontawe
 export function build(options) {
   if (alloyProject()) {
     ensureConfig()
-    buildTailwindBasedOnConfigOptions(options)
-    buildFontAwesome()
-    buildFontAwesomeJS()
-    createDefinitionsFile()
+    try {
+      buildTailwindBasedOnConfigOptions(options)
+      buildFontAwesome()
+      buildFontAwesomeJS()
+      createDefinitionsFile()
+    } finally {
+      flushSemanticColors()
+    }
     return true
   }
   return false

package/src/cli/commands/images.js

@@ -37,6 +37,48 @@ export async function images(cliSource, options = {}) {
     process.exit(1)
   }
 
+  if (options.width !== undefined) {
+    if (!Number.isFinite(options.width) || !Number.isInteger(options.width) || options.width < 1 || options.width > 8192) {
+      logger.error(`Invalid --width '${options.width}'. Must be an integer between 1 and 8192.`)
+      process.exit(1)
+    }
+  }
+
+  let opacity = null
+  if (options.opacity !== undefined) {
+    if (!Number.isFinite(options.opacity) || !Number.isInteger(options.opacity) || options.opacity < 0 || options.opacity > 100) {
+      logger.error(`Invalid --opacity '${options.opacity}'. Must be an integer between 0 and 100.`)
+      process.exit(1)
+    }
+    opacity = options.opacity
+  }
+
+  let padding = null
+  if (options.padding !== undefined) {
+    if (!Number.isFinite(options.padding) || !Number.isInteger(options.padding) || options.padding < 0 || options.padding > 40) {
+      logger.error(`Invalid --padding '${options.padding}'. Must be an integer between 0 and 40.`)
+      process.exit(1)
+    }
+    padding = options.padding
+  }
+
+  let outputRelpath = null
+  if (options.output !== undefined && options.output !== null && options.output !== '') {
+    const raw = String(options.output)
+    if (path.isAbsolute(raw)) {
+      logger.error(`Invalid --output '${raw}'. Must be a relative path inside the project images folder, not absolute.`)
+      process.exit(1)
+    }
+    const segments = raw.split(/[\\/]/)
+    if (segments.includes('..')) {
+      logger.error(`Invalid --output '${raw}'. '..' segments are not allowed (must stay inside the project images folder).`)
+      process.exit(1)
+    }
+    // Strip any trailing extension — --format (or source ext) decides actual extension.
+    const parsed = path.parse(raw)
+    outputRelpath = parsed.dir ? path.join(parsed.dir, parsed.name) : parsed.name
+  }
+
   const format = options.format ?? cfg.format ?? null
   if (format && !VALID_FORMATS.has(format.toLowerCase())) {
     logger.error(`Invalid --format '${format}'. Valid: ${[...VALID_FORMATS].join(', ')}`)
@@ -57,9 +99,14 @@ export async function images(cliSource, options = {}) {
       iphoneOnly: Boolean(options.ios),
       format: format ? format.toLowerCase() : null,
       quality: options.quality ?? cfg.quality ?? 85,
+      baseWidth: options.width ?? null,
+      opacity,
+      padding,
+      outputRelpath,
       dryRun: Boolean(options.dryRun),
       yes: Boolean(options.yes),
-      confirmOverwrites: cfg.confirmOverwrites !== false
+      confirmOverwrites: cfg.confirmOverwrites !== false,
+      filesOverrides: Array.isArray(cfg.files) ? cfg.files : []
     })
   } catch (err) {
     logger.error(err.message)
@@ -105,7 +152,7 @@ function printMissingSourceHelp(projectRoot) {
   logger.error('No source images found.')
   console.log()
   console.log(`  Expected images inside ${chalk.cyan(rel(imagesDir) + '/')}.`)
-  console.log(`  The folder already exists — drop your images into it (subdirectories are preserved):`)
+  console.log('  The folder already exists — drop your images into it (subdirectories are preserved):')
   console.log(`     ${chalk.cyan('cp my-ui-asset.png ' + rel(imagesDir) + '/')}`)
   console.log()
   console.log('  Alternatives:')

package/src/cli/commands/purge.js

@@ -32,7 +32,9 @@ import { getConfigOptions, getConfigFile, ensureConfig } from '../../shared/conf
 
 // Import purger functions from core modules
 import { processControllers } from '../../core/analyzers/class-extractor.js'
+import { runSvgPipeline } from '../../core/svg/index.js'
 import { purgeTailwind } from '../../core/purger/tailwind-purger.js'
+import { flushSemanticColors } from '../../shared/semantic-helpers.js'
 import {
   purgeFontAwesome,
   purgeMaterialIcons,
@@ -40,6 +42,7 @@ import {
   purgeFramework7
 } from '../../core/purger/icon-purger.js'
 import { purgeFonts } from '../../core/purger/fonts-purger.js'
+import { validateClassSyntax } from '../utils/unsupported-class-reporter.js'
 
 // Global variables (EXACT copies from original src/index.js)
 let configOptions = {}
@@ -665,7 +668,7 @@ function saveFile(file, data) {
  * @param {Object} options - Command options
  * @returns {boolean} - Success status
  */
-export function purgeClasses(options) {
+export async function purgeClasses(options) {
   // Initialize configOptions first (includes auto-migration)
   configOptions = getConfigOptions()
 
@@ -674,6 +677,9 @@ export function purgeClasses(options) {
   }
 
   purgingDebug = options.debug
+  // Propagate to the logger module so localFinish (cli-helpers.js) sees it.
+  // The local `purgingDebug` is still needed for the purger callees below.
+  setDebugMode(options.debug)
 
   const recentlyCreated = makeSureFileExists(projectsAppTSS)
 
@@ -693,10 +699,21 @@ export function purgeClasses(options) {
 
       try {
         uniqueClasses = getUniqueClasses()
+
+        // Pre-validate class syntax. Halts on inverted negatives, square
+        // brackets, empty parens, etc. — but NOT on generic unknown classes
+        // (those fall through silently to "// Unused or unsupported classes").
+        validateClassSyntax({
+          classes: uniqueClasses,
+          viewPaths: getViewPaths(),
+          controllerPaths: getControllerPaths()
+        })
       } catch (error) {
-        // Handle pre-validation errors (XML syntax errors detected before parsing)
-        if (error.isPreValidationError) {
-          // Error already printed by preValidateXML, exit cleanly
+        // Handle pre-validation errors (XML syntax errors detected before
+        // parsing) and class-syntax errors (authoring mistakes detected
+        // before purging). In both cases the error block was already
+        // printed; just exit cleanly.
+        if (error.isPreValidationError || error.isClassSyntaxError) {
           // eslint-disable-next-line n/no-process-exit
           process.exit(1)
         }
@@ -726,8 +743,18 @@ export function purgeClasses(options) {
 
       logger.file('app.tss')
 
+      // Post-step: compile SVG references found in views/controllers into
+      // multi-density PNGs sized from the just-resolved app.tss classes.
+      await runSvgPipeline({
+        tssContent: tempPurged,
+        viewPaths: getViewPaths(),
+        controllerPaths: getControllerPaths(),
+        logger
+      })
+
       finish()
     } finally {
+      flushSemanticColors()
       logger.endSection()
     }
 

package/src/cli/commands/shades.js

@@ -329,8 +329,8 @@ export function buildSemanticPalette(family, kebabName, alpha) {
     const mirror = sorted[sorted.length - 1 - i]
     const key = `${camelName}${shade.number}`
     semanticEntries[key] = {
-      light: wrapValue(mirror.hexcode, alpha),
-      dark: wrapValue(shade.hexcode, alpha)
+      light: wrapValue(shade.hexcode, alpha),
+      dark: wrapValue(mirror.hexcode, alpha)
     }
     configMapping[shade.number] = key
   })

package/src/cli/utils/cli-helpers.js

@@ -45,15 +45,25 @@ export function localStart() {
 }
 
 /**
- * Finish local timer and log execution time (only in debug mode)
- * Maintains exact same logic as original localFinish() function
+ * Finish local timer and log execution time (only in debug mode).
  *
- * @param {string} customMessage - Custom message to display
+ * Pass an empty string to print only the timing (without re-emitting the
+ * label) — useful when the caller already showed the section title via
+ * `logger.info` before calling `localStart()`. Anything else is printed
+ * verbatim with the timing appended.
+ *
+ * @param {string} customMessage - Label to print alongside the timing, or
+ *   `''` for timing-only mode.
  */
 export function localFinish(customMessage = 'Finished purging in') {
   const localEndTime = new Date(new Date() - localStartTime)
-  if (getDebugMode()) {
-    logger.info(customMessage, chalk.green(`${localEndTime.getSeconds()}s ${localEndTime.getMilliseconds()}ms`))
+  if (!getDebugMode()) return
+  const timing = chalk.green(`${localEndTime.getSeconds()}s ${localEndTime.getMilliseconds()}ms`)
+  if (customMessage === '') {
+    // Timing-only mode: caller already printed the label.
+    logger.info(timing)
+  } else {
+    logger.info(customMessage, timing)
   }
 }
 

package/src/cli/utils/unsupported-class-reporter.js

@@ -0,0 +1,209 @@
+/**
+ * PurgeTSS - Class Syntax Validator
+ *
+ * Pre-validation helper that runs BEFORE the purge starts. Scans every unique
+ * class name pulled from XML views (and JS controllers) for well-known
+ * authoring mistakes:
+ *
+ *   - Inverted negative sign:  top-(-10)   → -top-(10)
+ *   - Square brackets:         top-[10px]  → top-(10px)
+ *   - Empty parentheses:       wh-()       → wh-(<value>)
+ *   - Whitespace in parens:    wh-( 200 )  → wh-(200)
+ *   - Redundant px units:      top-(10px)  → top-(10)
+ *
+ * On any match the validator collects every offender, prints one block per
+ * offender (file + line + fix, mirroring throwPreValidationError) and throws
+ * an `isClassSyntaxError` so the CLI exits cleanly without running the purge.
+ *
+ * Generic unknown classes (typos, vendor utilities not enabled, custom
+ * classes not yet defined) are intentionally left alone — they are still
+ * captured silently in the "// Unused or unsupported classes" section of
+ * app.tss, but never trigger warnings or halts. That's the only way to keep
+ * the workflow usable on projects with dozens of in-progress class names.
+ *
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { logger } from '../../shared/logger.js'
+
+const cwd = process.cwd()
+
+/**
+ * Pattern detectors. Each detector receives the className and returns
+ * { issue, suggestion } when it recognises the problem, or null otherwise.
+ * Order matters: more specific detectors first.
+ */
+const detectors = [
+  // top-(-10) → -top-(10)
+  function detectInvertedNegative(className) {
+    const m = className.match(/^([a-zA-Z][\w-]*?)-\(-([^()]+)\)$/)
+    if (!m) return null
+    return {
+      issue: 'Negative sign is inside the parentheses',
+      suggestion: `Use ${chalk.green(`"-${m[1]}-(${m[2]})"`)} — PurgeTSS expects the "-" prefix BEFORE the rule, not inside the value`
+    }
+  },
+
+  // top-[10px] → top-(10)
+  function detectSquareBrackets(className) {
+    if (!className.includes('[') && !className.includes(']')) return null
+    const fixed = className.replace(/\[/g, '(').replace(/\]/g, ')')
+    return {
+      issue: 'Square brackets "[ ]" are not supported',
+      suggestion: `Use parentheses instead: ${chalk.green(`"${fixed}"`)}`
+    }
+  },
+
+  // wh-() → "Add a value"
+  function detectEmptyParens(className) {
+    const m = className.match(/^([\w-]+)-\(\s*\)$/)
+    if (!m) return null
+    return {
+      issue: 'Empty value inside parentheses',
+      suggestion: `Add a value, e.g. ${chalk.green(`"${m[1]}-(10)"`)}`
+    }
+  },
+
+  // wh-( 200 ) → wh-(200)
+  function detectSpacesInParens(className) {
+    const m = className.match(/^([\w-]+)-\(\s+([^()]*?)\s*\)$|^([\w-]+)-\(([^()]*?)\s+\)$/)
+    if (!m) return null
+    const rule = m[1] || m[3]
+    const value = (m[2] || m[4] || '').trim()
+    if (!value) return null
+    return {
+      issue: 'Whitespace inside parentheses',
+      suggestion: `Remove the spaces: ${chalk.green(`"${rule}-(${value})"`)}`
+    }
+  },
+
+  // top-(10px) — units inside parens that PurgeTSS would strip anyway.
+  // Only flag when value is purely numeric+unit; never blanket-flag because
+  // some properties (durations, percentages) accept units.
+  function detectRedundantUnits(className) {
+    const m = className.match(/^([\w-]+)-\((-?\d+(?:\.\d+)?)px\)$/)
+    if (!m) return null
+    return {
+      issue: 'Explicit "px" unit is redundant',
+      suggestion: `PurgeTSS treats unit-less values as pixels: ${chalk.green(`"${m[1]}-(${m[2]})"`)}`
+    }
+  }
+]
+
+function detectIssue(className) {
+  for (const detector of detectors) {
+    const result = detector(className)
+    if (result) return result
+  }
+  return null
+}
+
+/**
+ * Find every (file, line) where `className` appears as a whole token inside a
+ * class="..." attribute. Uses an attribute-then-split strategy (rather than
+ * matching the class name directly) so arbitrary-value class names like
+ * "top-(-10)" — which contain regex-special characters — do not need escaping
+ * and cannot false-match a partial substring.
+ */
+function findLocations(className, paths) {
+  const locations = []
+  const attrRe = /class\s*=\s*["']([^"']*)["']/g
+
+  for (const filePath of paths) {
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const lines = content.split(/\r?\n/)
+    for (let i = 0; i < lines.length; i++) {
+      attrRe.lastIndex = 0
+      let match
+      while ((match = attrRe.exec(lines[i])) !== null) {
+        const tokens = match[1].split(/\s+/).filter(Boolean)
+        if (tokens.includes(className)) {
+          locations.push({
+            filePath,
+            lineNumber: i + 1,
+            lineContent: lines[i].trim()
+          })
+          break
+        }
+      }
+    }
+  }
+  return locations
+}
+
+function relativePath(filePath) {
+  return filePath.startsWith(cwd + '/') ? filePath.slice(cwd.length + 1) : filePath
+}
+
+/**
+ * Pre-validate every unique class against the syntax detectors. Collects all
+ * offenders (so the dev sees the full list in a single run instead of
+ * one-fix-per-attempt), prints a block per offender, then throws.
+ *
+ * Generic unknown classes are NOT flagged — they fall through silently to
+ * the "// Unused or unsupported classes" comment block in app.tss.
+ *
+ * @param {Object} args
+ * @param {string[]} args.classes           Unique classes pulled from views/controllers.
+ * @param {string[]} args.viewPaths         Absolute paths to XML view files.
+ * @param {string[]} [args.controllerPaths] Absolute paths to JS controller files.
+ * @throws {Error} with `isClassSyntaxError === true` if any class matches a detector.
+ */
+export function validateClassSyntax({ classes, viewPaths, controllerPaths = [] }) {
+  if (!classes || classes.length === 0) return
+
+  const allPaths = [...viewPaths, ...controllerPaths]
+  const offenders = []
+
+  for (const className of classes) {
+    const issue = detectIssue(className)
+    if (!issue) continue
+    offenders.push({
+      className,
+      issue,
+      locations: findLocations(className, allPaths)
+    })
+  }
+
+  if (offenders.length === 0) return
+
+  for (const offender of offenders) {
+    const lines = []
+    lines.push(`Class: ${chalk.yellow(`"${offender.className}"`)}`)
+
+    if (offender.locations.length > 0) {
+      const first = offender.locations[0]
+      lines.push(`File: ${chalk.yellow(`"${relativePath(first.filePath)}"`)}`)
+      lines.push(`Line: ${chalk.yellow(first.lineNumber)}`)
+      lines.push(`Content: ${chalk.gray(first.lineContent)}`)
+      if (offender.locations.length > 1) {
+        const more = offender.locations.length - 1
+        lines.push(chalk.gray(`(also used in ${more} other location${more === 1 ? '' : 's'})`))
+      }
+    } else {
+      lines.push(chalk.gray('Location: not found in views — likely from a controller or safelist'))
+    }
+
+    lines.push('')
+    lines.push(chalk.red(`Issue: ${offender.issue.issue}`))
+    lines.push(`${chalk.green('Fix:')} ${offender.issue.suggestion}`)
+
+    logger.block(chalk.red('Class Syntax Error'), ...lines)
+  }
+
+  const word = offenders.length === 1 ? 'class syntax error' : 'class syntax errors'
+  logger.block(
+    chalk.red(`Found ${offenders.length} ${word} — fix the ${offenders.length === 1 ? 'class' : 'classes'} above and re-run purgetss`)
+  )
+
+  const error = new Error('Class syntax errors detected')
+  error.isClassSyntaxError = true
+  throw error
+}