purgetss 7.5.2 → 7.6.1

package/src/core/analyzers/class-extractor.js

@@ -14,6 +14,7 @@ import _ from 'lodash'
 import chalk from 'chalk'
 import convert from 'xml-js'
 import traverse from 'traverse'
+import * as acorn from 'acorn'
 
 /**
  * Get unique classes from all XML and controller files - COPIED exactly from original getUniqueClasses() function
@@ -98,7 +99,7 @@ export function extractClassesOnly(currentText, currentFile) {
  * @param {string} line - Line of code from controller file
  * @returns {Array} Array of class names found in line
  */
-function extractWordsFromLine(line) {
+function extractWordsFromLineRegex(line) {
   const patterns = [
     {
       // apply: 'classes'
@@ -155,12 +156,12 @@ function extractWordsFromLine(line) {
  * @param {string} data - Controller file content
  * @returns {Array} Array of class names found in controller
  */
-function processControllers(data) {
+function processControllersRegex(data) {
   const allWords = []
   const lines = data.split(/\r?\n/)
 
   lines.forEach(line => {
-    const words = extractWordsFromLine(line)
+    const words = extractWordsFromLineRegex(line)
     if (words.length > 0) {
       allWords.push(...words)
     }
@@ -169,6 +170,112 @@ function processControllers(data) {
   return allWords
 }
 
+const AST_META_KEYS = new Set(['type', 'loc', 'range', 'start', 'end', 'sourceType', 'comments'])
+
+function collectLiterals(node, out) {
+  if (!node || typeof node !== 'object' || !node.type) return
+
+  switch (node.type) {
+    case 'Literal':
+      if (typeof node.value === 'string') {
+        node.value.split(/\s+/).forEach(token => { if (token) out.push(token) })
+      }
+      return
+
+    case 'TemplateLiteral':
+      if (node.expressions.length === 0 && node.quasis.length > 0) {
+        const cooked = node.quasis[0].value.cooked
+        if (typeof cooked === 'string') {
+          cooked.split(/\s+/).forEach(token => { if (token) out.push(token) })
+        }
+      }
+      return
+
+    case 'ArrayExpression':
+      for (const element of node.elements) {
+        if (element && element.type !== 'SpreadElement') collectLiterals(element, out)
+      }
+      return
+
+    case 'ConditionalExpression':
+      collectLiterals(node.consequent, out)
+      collectLiterals(node.alternate, out)
+      return
+
+    default:
+      return
+  }
+}
+
+function walkAST(node, out) {
+  if (!node || typeof node !== 'object') return
+
+  if (Array.isArray(node)) {
+    for (const child of node) walkAST(child, out)
+    return
+  }
+
+  if (!node.type) return
+
+  if (node.type === 'Property' && !node.computed && !node.shorthand && node.key) {
+    const keyName = node.key.type === 'Identifier'
+      ? node.key.name
+      : (node.key.type === 'Literal' ? node.key.value : undefined)
+    if (keyName === 'classes' || keyName === 'apply') {
+      collectLiterals(node.value, out)
+    }
+  }
+
+  if (node.type === 'CallExpression' && node.callee && node.arguments.length >= 2) {
+    const callee = node.callee
+    let match = false
+    if (
+      callee.type === 'MemberExpression' &&
+      !callee.computed &&
+      callee.property &&
+      callee.property.type === 'Identifier' &&
+      /Class$/.test(callee.property.name)
+    ) {
+      match = true
+    } else if (callee.type === 'Identifier' && callee.name === 'resetClass') {
+      match = true
+    }
+    if (match) collectLiterals(node.arguments[1], out)
+  }
+
+  for (const key of Object.keys(node)) {
+    if (AST_META_KEYS.has(key)) continue
+    walkAST(node[key], out)
+  }
+}
+
+/**
+ * Process a controller file's source and return utility classes referenced by
+ * the whitelisted expression shapes (`classes:`, `apply:`, `.xxxClass(target, value)`,
+ * `resetClass(target, value)`). Falls back to the per-line regex scanner when
+ * the parser rejects the source.
+ *
+ * @param {string} data - Controller file content
+ * @returns {Array} Array of class name tokens
+ */
+export function processControllers(data) {
+  try {
+    const ast = acorn.parse(data, {
+      ecmaVersion: 'latest',
+      sourceType: 'script',
+      allowReturnOutsideFunction: true,
+      allowAwaitOutsideFunction: true,
+      allowImportExportEverywhere: true,
+      allowHashBang: true
+    })
+    const out = []
+    walkAST(ast, out)
+    return out
+  } catch {
+    return processControllersRegex(data)
+  }
+}
+
 /**
  * Encode HTML entities - COPIED exactly from original encodeHTML() function
  * NO CHANGES to logic, preserving 100% of original functionality

package/src/core/branding/brand-config.js

@@ -0,0 +1,111 @@
+/**
+ * PurgeTSS - Brand command config resolver
+ *
+ * Merges three sources of configuration, in this precedence order:
+ *   1. CLI flags (highest priority)
+ *   2. `brand: { ... }` section from purgetss/config.cjs
+ *   3. Built-in defaults (lowest priority)
+ *
+ * Also auto-discovers logo images inside `./purgetss/brand/` following the
+ * project convention:
+ *   logo.{svg,png}          → required (main logo)
+ *   logo-mono.{svg,png}     → optional (monochrome layer + notifications)
+ *   logo-dark.{svg,png}     → optional (iOS 18+ dark variant)
+ *   logo-tinted.{svg,png}   → optional (iOS 18+ tinted variant)
+ *
+ * CLI --monochrome-logo / --dark-logo / --tinted-logo always override
+ * discovery, and the positional argument overrides the main logo.
+ *
+ * @fileoverview Brand config + logo discovery
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { getConfigFile } from '../../shared/config-manager.js'
+
+const BRAND_DIR = 'purgetss/brand'
+const SUPPORTED_EXTS = ['svg', 'png']
+
+/**
+ * Find the first existing file matching <baseName>.<ext> for each supported ext.
+ * @param {string} baseDir - Absolute path to the search directory
+ * @param {string} baseName - Filename without extension (e.g. 'logo-mono')
+ * @returns {string|null} Absolute path to the first match, or null
+ */
+function findLogoFile(baseDir, baseName) {
+  for (const ext of SUPPORTED_EXTS) {
+    const candidate = path.join(baseDir, `${baseName}.${ext}`)
+    if (fs.existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/**
+ * Build the final opts object for runBranding().
+ *
+ * @param {Object} cliOptions - Raw options from Commander
+ * @param {string|undefined} cliLogo - Positional logo arg from Commander
+ * @param {string} projectRoot - Absolute project root
+ * @returns {Object} Resolved options
+ */
+export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
+  const brandConfig = loadBrandSection()
+  const brandDir = path.join(projectRoot, BRAND_DIR)
+
+  const resolved = {
+    logo: pickLogo(cliLogo, brandConfig.logo, brandDir, 'logo', projectRoot),
+    monochromeLogo: pickLogo(cliOptions.monochromeLogo, brandConfig.monochromeLogo, brandDir, 'logo-mono', projectRoot),
+    darkLogo: pickLogo(cliOptions.darkLogo, brandConfig.darkLogo, brandDir, 'logo-dark', projectRoot),
+    tintedLogo: pickLogo(cliOptions.tintedLogo, brandConfig.tintedLogo, brandDir, 'logo-tinted', projectRoot),
+
+    bgColor: cliOptions.bgColor ?? brandConfig.bgColor ?? '#FFFFFF',
+    bgColorExplicit: Boolean(cliOptions.bgColor ?? brandConfig.bgColor),
+    darkBgColor: cliOptions.darkBgColor ?? brandConfig.darkBgColor ?? null,
+    padding: cliOptions.padding ?? brandConfig.padding ?? 15,
+    iosPadding: cliOptions.iosPadding ?? brandConfig.iosPadding ?? 4,
+
+    // Kitchen-sink defaults: adaptive + marketplace are always generated; only
+    // notification and splash are opt-in. Config can pre-enable them.
+    notification: Boolean(cliOptions.notification ?? brandConfig.notification ?? false),
+    splash: Boolean(cliOptions.splash ?? brandConfig.splash ?? false),
+
+    withDark: cliOptions.dark !== false && (brandConfig.dark ?? true),
+    withTinted: cliOptions.tinted !== false && (brandConfig.tinted ?? true),
+
+    cleanupLegacy: Boolean(cliOptions.cleanupLegacy),
+    aggressive: Boolean(cliOptions.aggressive),
+    projectRoot,
+    output: cliOptions.output || null,
+    dryRun: Boolean(cliOptions.dryRun),
+    notes: Boolean(cliOptions.notes),
+    confirmOverwrites: brandConfig.confirmOverwrites !== false
+  }
+
+  return resolved
+}
+
+/**
+ * @returns {Object} The `brand` section of the resolved config, or {} if missing/invalid.
+ */
+function loadBrandSection() {
+  try {
+    const cfg = getConfigFile()
+    if (cfg && typeof cfg === 'object' && cfg.brand && typeof cfg.brand === 'object') {
+      return cfg.brand
+    }
+  } catch {
+    // Config file missing or invalid — fall back to empty defaults.
+  }
+  return {}
+}
+
+/**
+ * Resolve a logo path with proper precedence.
+ * Config-relative paths are resolved against projectRoot.
+ */
+function pickLogo(cliValue, configValue, brandDir, baseName, projectRoot) {
+  if (cliValue) return path.resolve(cliValue)
+  if (configValue) return path.isAbsolute(configValue) ? configValue : path.resolve(projectRoot, configValue)
+  return findLogoFile(brandDir, baseName)
+}

package/src/core/branding/branding-logger.js

@@ -0,0 +1,40 @@
+/**
+ * PurgeTSS - Branding Logger
+ *
+ * Chalk-based presentation helpers used exclusively by the branding pipeline.
+ * Separate from the main PurgeTSS logger because the branding output style
+ * (sections, bullets, property rows) is much richer than the one-line logging
+ * used elsewhere in the tool.
+ *
+ * @fileoverview Logger helpers for the branding pipeline
+ * @author César Estrada
+ */
+
+import chalk from 'chalk'
+
+let debugMode = false
+
+export const logger = {
+  setDebugMode(enabled) { debugMode = enabled },
+
+  info(message) { console.log(chalk.blue(message)) },
+
+  section(name) {
+    console.log()
+    console.log(chalk.cyan(`▸ ${name}`))
+  },
+
+  bullet(message) { console.log(`  ${chalk.cyan('•')} ${message}`) },
+
+  property(label, value) { console.log(`${chalk.blue(label)}${value}`) },
+
+  success(message) { console.log(chalk.green(message)) },
+
+  warning(message) { console.log(chalk.yellow(message)) },
+
+  error(message) { console.error(chalk.red(message)) },
+
+  debug(message) {
+    if (debugMode) console.log(chalk.cyan(message))
+  }
+}

package/src/core/branding/cleanup-legacy.js

@@ -0,0 +1,220 @@
+/**
+ * PurgeTSS - cleanup-legacy
+ *
+ * Context-aware removal of legacy branding artifacts.
+ *
+ * Reads tiapp.xml via tiapp-reader and categorizes targets into:
+ *
+ *   SAFE          always deleted — universally obsolete (dead qualifiers)
+ *   CONDITIONAL   deleted only when project config guarantees they're unused
+ *                 (e.g. iOS legacy launch images when storyboard is enabled)
+ *   AGGRESSIVE    behind --aggressive — strongly defensible but some edge
+ *                 cases (e.g. ldpi drawables on <1% of devices)
+ *
+ * Always prints the plan before acting. Respects dryRun.
+ *
+ * @fileoverview Legacy-artifact cleanup for Titanium branding
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { logger } from './branding-logger.js'
+import { readTiapp, hasAdaptiveIcons } from './tiapp-reader.js'
+
+export async function cleanupLegacy({ projectRoot, projectType, aggressive = false, dryRun = false }) {
+  const tiappPath = path.join(projectRoot, 'tiapp.xml')
+  const tiapp = readTiapp(tiappPath)
+  const adaptive = hasAdaptiveIcons(projectRoot)
+
+  const layout = getLayoutPaths(projectRoot, projectType)
+
+  const safe = []
+  const conditional = []
+  const aggressiveTargets = []
+
+  // ---- SAFE -----------------------------------------------------------
+  if (layout.androidImages && fs.existsSync(layout.androidImages)) {
+    const reason = 'Android long/notlong qualifier (dead since Android 3.0, 2011)'
+    for (const entry of listChildDirs(layout.androidImages, /^res-(long|notlong)-/)) {
+      safe.push({ path: entry, reason })
+    }
+  }
+
+  // ---- CONDITIONAL ----------------------------------------------------
+  if (tiapp.storyboardEnabled && layout.iphoneDir && fs.existsSync(layout.iphoneDir)) {
+    const reason = 'iOS legacy launch image (storyboard enabled → not consulted)'
+    for (const entry of listChildFiles(layout.iphoneDir, /^Default(-.+)?(@2x)?\.png$/)) {
+      conditional.push({ path: entry, reason })
+    }
+  }
+
+  if (tiapp.portraitOnly && layout.androidImages && fs.existsSync(layout.androidImages)) {
+    const reason = 'Landscape variant (app is portrait-only)'
+    for (const entry of listChildDirs(layout.androidImages, /(^res-.+-land-|^res-land-)/)) {
+      conditional.push({ path: entry, reason })
+    }
+  }
+
+  if (adaptive && layout.androidAssets) {
+    const defaultPng = path.join(layout.androidAssets, 'default.png')
+    if (fs.existsSync(defaultPng)) {
+      conditional.push({
+        path: defaultPng,
+        reason: 'Legacy Android splash PNG (adaptive launcher handles splash now)'
+      })
+    }
+    const appicon = path.join(layout.androidAssets, 'appicon.png')
+    if (fs.existsSync(appicon)) {
+      conditional.push({
+        path: appicon,
+        reason: 'Legacy appicon.png (adaptive launcher takes precedence)'
+      })
+    }
+  }
+
+  // ---- AGGRESSIVE -----------------------------------------------------
+  if (aggressive) {
+    const reason = 'ldpi density (<1% global market)'
+    if (layout.androidImages && fs.existsSync(layout.androidImages)) {
+      for (const entry of listChildDirs(layout.androidImages, /(^res-ldpi$|^res-.+-ldpi$)/)) {
+        aggressiveTargets.push({ path: entry, reason })
+      }
+    }
+    const ldpiDirs = [
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'drawable-ldpi'),
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'values-ldpi'),
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'mipmap-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'drawable-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'values-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'mipmap-ldpi')
+    ]
+    for (const d of ldpiDirs) {
+      if (fs.existsSync(d)) {
+        aggressiveTargets.push({ path: d, reason: 'ldpi resource folder (<1% global market)' })
+      }
+    }
+  }
+
+  printPlan({
+    projectRoot, projectType, tiapp, adaptive, aggressive,
+    safe, conditional, aggressiveTargets
+  })
+
+  const total = safe.length + conditional.length + aggressiveTargets.length
+  if (total === 0) {
+    logger.success('No legacy artifacts detected. Project is already clean.')
+    return { removed: 0, bytes: 0 }
+  }
+
+  if (dryRun) {
+    logger.info('Dry-run mode — nothing deleted. Re-run without --dry-run to apply.')
+    return { removed: 0, bytes: 0 }
+  }
+
+  let removed = 0
+  let bytes = 0
+  for (const bucket of [safe, conditional, aggressiveTargets]) {
+    for (const { path: target } of bucket) {
+      const size = getSizeBytes(target)
+      fs.rmSync(target, { recursive: true, force: true })
+      bytes += size
+      removed += 1
+      logger.success(`Removed ${path.relative(projectRoot, target)}`)
+    }
+  }
+  return { removed, bytes }
+}
+
+function getLayoutPaths(projectRoot, projectType) {
+  if (projectType === 'alloy') {
+    return {
+      androidImages: path.join(projectRoot, 'app', 'assets', 'android', 'images'),
+      iphoneDir: path.join(projectRoot, 'app', 'assets', 'iphone'),
+      androidAssets: path.join(projectRoot, 'app', 'assets', 'android')
+    }
+  }
+  if (projectType === 'classic') {
+    return {
+      androidImages: path.join(projectRoot, 'Resources', 'android', 'images'),
+      iphoneDir: path.join(projectRoot, 'Resources', 'iphone'),
+      androidAssets: path.join(projectRoot, 'Resources', 'android')
+    }
+  }
+  return { androidImages: null, iphoneDir: null, androidAssets: null }
+}
+
+function listChildDirs(parent, regex) {
+  if (!fs.existsSync(parent)) return []
+  return fs.readdirSync(parent)
+    .filter((name) => regex.test(name))
+    .map((name) => path.join(parent, name))
+    .filter((p) => fs.statSync(p).isDirectory())
+}
+
+function listChildFiles(parent, regex) {
+  if (!fs.existsSync(parent)) return []
+  return fs.readdirSync(parent)
+    .filter((name) => regex.test(name))
+    .map((name) => path.join(parent, name))
+    .filter((p) => fs.statSync(p).isFile())
+}
+
+function getSizeBytes(target) {
+  try {
+    const stat = fs.statSync(target)
+    if (stat.isFile()) return stat.size
+    let total = 0
+    for (const name of fs.readdirSync(target)) {
+      total += getSizeBytes(path.join(target, name))
+    }
+    return total
+  } catch {
+    return 0
+  }
+}
+
+function formatKb(bytes) {
+  return `${Math.round(bytes / 1024)}K`
+}
+
+function printPlan({ projectRoot, projectType, tiapp, adaptive, aggressive, safe, conditional, aggressiveTargets }) {
+  console.log()
+  logger.warning('⚠  WARNING — --cleanup-legacy deletes files permanently.')
+  logger.warning('   Recommended: commit your project with git before running without --dry-run.')
+  console.log()
+  console.log('Cleanup plan')
+  console.log(`  Project:            ${projectRoot} (${projectType})`)
+  console.log(`  Storyboard:         ${tiapp.storyboardEnabled ? 'enabled' : 'disabled'}`)
+  console.log(`  Orientation:        ${tiapp.portraitOnly ? 'portrait-only' : 'landscape allowed'}`)
+  console.log(`  Adaptive icons:     ${adaptive ? 'present' : 'not detected'}`)
+  console.log(`  Aggressive mode:    ${aggressive ? 'on (includes ldpi)' : 'off'}`)
+
+  if (safe.length) {
+    console.log()
+    logger.success('SAFE — universally obsolete')
+    for (const { path: p, reason } of safe) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  if (conditional.length) {
+    console.log()
+    logger.warning('CONDITIONAL — safe given your project config')
+    for (const { path: p, reason } of conditional) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  if (aggressiveTargets.length) {
+    console.log()
+    logger.error('AGGRESSIVE — --aggressive enabled')
+    for (const { path: p, reason } of aggressiveTargets) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  const total = safe.length + conditional.length + aggressiveTargets.length
+  console.log()
+  console.log(`  Total: ${total} item(s) to remove`)
+}

package/src/core/branding/ensure-brand-section.js

@@ -0,0 +1,80 @@
+/**
+ * PurgeTSS - Ensure `brand:` section exists in purgetss/config.cjs
+ *
+ * When a project was initialized before `brand` was introduced, its
+ * config.cjs won't have a `brand:` section. On first invocation of
+ * `purgetss brand`, we patch the file to insert the default block
+ * between `purge:` and `theme:`. The user's existing keys are untouched.
+ *
+ * Rationale:
+ * - Keeps the config self-documenting — the user sees the defaults in
+ *   their own file rather than having to look them up in docs.
+ * - Mirrors how `ensureConfig()` creates the file from the template when
+ *   it's missing altogether.
+ * - Non-destructive: only adds if absent, never overwrites existing values.
+ *
+ * @fileoverview Auto-injects the `brand:` section on first brand run
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { projectsConfigJS, projectsPurge_TSS_Brand_Folder } from '../../shared/constants.js'
+import { logger } from './branding-logger.js'
+
+const BRAND_BLOCK = `  brand: {
+    splash: false,           // also generate splash_icon.png × 5
+    padding: '15%',          // Android safe-zone. Range: 12% tight (mature logos) — 20% conservative. Spec floor 19.44%.
+    iosPadding: '4%',        // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
+    darkBgColor: null,       // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
+    bgColor: '#FFFFFF',      // Android adaptive bg + iOS/marketplace flatten
+    notification: false,     // also generate ic_stat_notify.png × 5
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
+`
+
+/**
+ * If the project's config.cjs exists but has no `brand:` key, inject the
+ * default block between `purge:` and `theme:`. Prints a notice when it does.
+ *
+ * Silently skips if:
+ *   - config.cjs doesn't exist (will be created by ensureConfig() elsewhere)
+ *   - `brand:` is already present
+ *   - file can't be patched safely (structure doesn't match expectation)
+ */
+export function ensureBrandSection() {
+  // Always make sure the logos folder exists — mirrors how init creates
+  // `purgetss/fonts/` empty so the user can see where assets go.
+  if (!fs.existsSync(projectsPurge_TSS_Brand_Folder)) {
+    fs.mkdirSync(projectsPurge_TSS_Brand_Folder, { recursive: true })
+  }
+
+  if (!fs.existsSync(projectsConfigJS)) return
+
+  const original = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  // Already present — nothing to do.
+  if (/^\s*brand\s*:/m.test(original)) return
+
+  // Insert before the `theme:` key. Regex captures the indentation so we
+  // preserve whatever the user's style is (2-space, 4-space, etc.).
+  const match = original.match(/(^\s*)theme\s*:/m)
+  if (!match) {
+    // Non-standard layout — don't risk corrupting it. User can add manually.
+    return
+  }
+
+  const patched = original.replace(match[0], `${BRAND_BLOCK}${match[0]}`)
+
+  try {
+    fs.writeFileSync(projectsConfigJS, patched, 'utf8')
+    console.log()
+    logger.success(`Added ${chalk.cyan('brand:')} section to ${chalk.cyan('./purgetss/config.cjs')} with default values.`)
+    console.log('  Edit that block to customize brand defaults (bgColor, padding, etc.).')
+    console.log('  CLI flags always win over config values.')
+    console.log()
+  } catch (err) {
+    logger.warning(`Could not auto-add brand: section to config.cjs (${err.message}).`)
+    logger.warning('The command will still run using built-in defaults.')
+  }
+}