purgetss 7.9.0 → 7.11.1

package/src/core/svg/cache.js

@@ -0,0 +1,96 @@
+/**
+ * PurgeTSS - SVG pipeline cache
+ *
+ * Tracks the last successful generation of each SVG so subsequent runs can
+ * skip work when nothing changed. Cached file: `purgetss/.cache/svg-images.json`.
+ *
+ * An entry is invalidated (regen) when any of these change:
+ *   - The SVG file content (sha1 hash).
+ *   - The resolved widthDp / heightDp.
+ *   - The list of target PNG paths.
+ *   - Any of the target PNGs is missing on disk.
+ *
+ * Stale entries for SVGs no longer referenced are left untouched here — the
+ * planned `purgetss clean` command is responsible for purging orphans.
+ *
+ * @fileoverview Idempotency cache for the SVG pipeline
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+import { projectsPurgeTSSFolder } from '../../shared/constants.js'
+
+const CACHE_DIR = path.join(projectsPurgeTSSFolder, '.cache')
+const CACHE_FILE = path.join(CACHE_DIR, 'svg-images.json')
+
+/**
+ * Load the on-disk cache as a plain object. Returns `{}` if the file is
+ * missing or unreadable — corrupted caches simply force a regen rather than
+ * halting the build.
+ */
+export function loadCache() {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return {}
+    const raw = fs.readFileSync(CACHE_FILE, 'utf8')
+    const parsed = JSON.parse(raw)
+    return (parsed && typeof parsed === 'object') ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Persist the cache to disk, creating `.cache/` if needed.
+ */
+export function saveCache(cache) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true })
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2) + '\n', 'utf8')
+}
+
+/**
+ * Compute the sha1 hash of an SVG file. Reads the bytes verbatim so
+ * whitespace-only edits also bust the cache (desired — they may change rendering).
+ */
+export function hashFile(absPath) {
+  const buf = fs.readFileSync(absPath)
+  return crypto.createHash('sha1').update(buf).digest('hex')
+}
+
+/**
+ * Decide whether the cached entry is still valid for the given resolved inputs.
+ *
+ * @param {Object} cached - Previous cache entry (or undefined).
+ * @param {string} svgHash - sha1 of the current SVG.
+ * @param {number} widthDp - Currently resolved widthDp.
+ * @param {number} heightDp - Currently resolved heightDp.
+ * @param {string[]} targets - Absolute paths the pipeline would emit this run.
+ * @returns {boolean} True if every target PNG is present and inputs match.
+ */
+export function isCacheHit(cached, svgHash, widthDp, heightDp, targets) {
+  if (!cached) return false
+  if (cached.svgHash !== svgHash) return false
+  if (cached.widthDp !== widthDp) return false
+  if (cached.heightDp !== heightDp) return false
+  if (!Array.isArray(cached.targets) || cached.targets.length !== targets.length) return false
+
+  const cachedPaths = new Set(cached.targets.map(t => (typeof t === 'string' ? t : t.path)))
+  for (const t of targets) {
+    if (!cachedPaths.has(t)) return false
+    if (!fs.existsSync(t)) return false
+  }
+  return true
+}
+
+/**
+ * Build the cache entry shape we persist after a successful generation.
+ */
+export function makeCacheEntry(svgHash, widthDp, heightDp, targets) {
+  return {
+    svgHash,
+    widthDp,
+    heightDp,
+    targets: [...targets]
+  }
+}

package/src/core/svg/derive-dimensions.js

@@ -0,0 +1,120 @@
+/**
+ * PurgeTSS - SVG dimension deriver
+ *
+ * Reduces all the references to a single SVG into one final `{ widthDp, heightDp }`
+ * pair that the image generator can consume as the `1×` baseline. Strategy:
+ *
+ *   1. For each reference, resolve the cascade against the purged app.tss
+ *      class→props map.
+ *   2. Collect every numeric width across references; the SVG's width is the
+ *      max (a single view rendered at 800dp can't share PNGs with a view at
+ *      128dp without visible blur).
+ *   3. Resolve height: explicit numeric width wins; otherwise fall back to a
+ *      proportional value derived from the SVG's viewBox aspect ratio.
+ *
+ * Edge cases handled:
+ *   - Every reference resolves to a non-numeric width (`Ti.UI.SIZE`, percentage,
+ *     unknown class, etc.) → SVG is skipped with a warning.
+ *   - SVG file missing in `purgetss/images/` → skipped with a warning.
+ *   - SVG has an invalid/missing viewBox → skipped with an error.
+ *
+ * @fileoverview Per-SVG dimension reducer that feeds the image generator
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { resolveDimensions } from './resolve-classes.js'
+import { readSvgSafely } from '../../shared/svg-utils.js'
+
+// Hard cap on the largest target PNG we are willing to emit, applied at the
+// `xxxhdpi` / `@3x` step downstream. Keeps Sharp from producing absurdly large
+// PNGs when the user accidentally pins a 4K width to a class.
+export const MAX_DIMENSION_PX = 4096
+
+/**
+ * Reduce raw SVG references into per-SVG resolved dimensions.
+ *
+ * @param {Object} args
+ * @param {Map<string, Array<{ classes: string[] }>>} args.refsBySvg - Map keyed by SVG relpath
+ *   (relative to imagesFolder, normalized to forward slashes), values are the list of
+ *   references seen for that SVG.
+ * @param {Map} args.tssMap - Output of parseTssMap().
+ * @param {string} args.imagesFolder - Absolute path to `purgetss/images/`.
+ * @param {Object} args.logger - Logger with `.warning(msg)` and `.info(msg)`.
+ * @returns {Promise<Map<string, { widthDp: number, heightDp: number }>>}
+ *   Resolved entries only; skipped SVGs are omitted (warnings logged inline).
+ */
+export async function deriveDimensions({ refsBySvg, tssMap, imagesFolder, logger }) {
+  const resolved = new Map()
+
+  for (const [relPath, refs] of refsBySvg) {
+    const absPath = path.join(imagesFolder, relPath)
+    if (!fs.existsSync(absPath)) {
+      logger.warning(`⚠  SVG not found: purgetss/images/${relPath} — skipping`)
+      continue
+    }
+
+    const numericWidths = []
+    const numericHeights = []
+    for (const ref of refs) {
+      const { width, height } = resolveDimensions(ref.classes, tssMap)
+      if (typeof width === 'number' && Number.isFinite(width) && width > 0) {
+        numericWidths.push(width)
+      }
+      if (typeof height === 'number' && Number.isFinite(height) && height > 0) {
+        numericHeights.push(height)
+      }
+    }
+
+    if (numericWidths.length === 0 && numericHeights.length === 0) {
+      logger.warning(
+        `⚠  ${relPath}: no class resolved width or height to a number — skipping. ` +
+        'Add a w-* or h-* utility on the view, or pin the size manually in purgetss/config.cjs > images.files.'
+      )
+      continue
+    }
+
+    try {
+      await readViewBox(absPath)
+    } catch (err) {
+      logger.warning(`⚠  ${relPath}: ${err.message} — skipping`)
+      continue
+    }
+
+    // Symmetric materialization: only the dimensions the developer pinned
+    // explicitly land in config.cjs. The other side is derived from the SVG
+    // aspect by gen-scales on every run, so it stays in sync with viewBox
+    // edits and class changes without stale "stuck" values getting cemented
+    // into config the way auto-derived heights used to.
+    const widthDp = numericWidths.length > 0 ? Math.max(...numericWidths) : null
+    const heightDp = numericHeights.length > 0 ? Math.max(...numericHeights) : null
+
+    resolved.set(relPath, { widthDp, heightDp })
+  }
+
+  return resolved
+}
+
+async function readViewBox(absPath) {
+  // Plan: error when the SVG declares neither viewBox nor width+height
+  // attributes. Sharp can infer a bounding box from the rendered content,
+  // but treating that as "valid" hides authoring mistakes (e.g. an export
+  // that lost its viewBox), so we enforce the explicit declaration first.
+  const head = fs.readFileSync(absPath, 'utf8').slice(0, 4096)
+  const svgTag = head.match(/<svg\b[^>]*>/i)?.[0] ?? ''
+  const hasViewBox = /\bviewBox\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  const hasWidth = /\bwidth\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  const hasHeight = /\bheight\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  if (!hasViewBox && !(hasWidth && hasHeight)) {
+    throw new Error('SVG has no viewBox or explicit width/height attribute')
+  }
+
+  const { meta } = await readSvgSafely(absPath, {})
+  const vbW = meta.width
+  const vbH = meta.height
+  if (!Number.isFinite(vbW) || !Number.isFinite(vbH) || vbW <= 0 || vbH <= 0) {
+    throw new Error('SVG has no usable viewBox / width / height')
+  }
+  return { vbW, vbH }
+}

package/src/core/svg/index.js

@@ -0,0 +1,215 @@
+/**
+ * PurgeTSS - SVG image pipeline (orchestrator)
+ *
+ * Post-step of the regular purge. Once `app.tss` is finalized, this module:
+ *
+ *   1. Parses app.tss into a class → props map.
+ *   2. Scans every view (.xml) and controller (.js) for SVG references paired
+ *      with their classes / `class=""` attribute.
+ *   3. Reduces each SVG to a single resolved `{ widthDp, heightDp }` (max of
+ *      every reference; falls back to viewBox aspect for height when `h-*` is
+ *      missing or non-numeric).
+ *   4. Upserts `images.files` in config.cjs (never decreases — manual overrides
+ *      always win).
+ *   5. Generates the iOS @1x/@2x/@3x and Android mdpi…xxxhdpi PNGs from the
+ *      same SVG master, using a hash-based cache to skip unchanged inputs.
+ *
+ * The pipeline never rewrites XML/Controller files. Titanium falls back to the
+ * generated PNGs at runtime when an `image="/.../foo.svg"` reference resolves
+ * against a `.png` with the same basename in the platform assets folder.
+ *
+ * @fileoverview Compile-time SVG → multi-density PNG pipeline for Titanium
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import {
+  cwd,
+  projectsPurge_TSS_Images_Folder  
+} from '../../shared/constants.js'
+import { detectProjectType } from '../branding/tiapp-reader.js'
+import { genAndroidScales, genIphoneScales, ANDROID_SCALES, IPHONE_SCALES } from '../images/gen-scales.js'
+import { parseTssMap } from './tss-reader.js'
+import { deriveDimensions } from './derive-dimensions.js'
+import { syncConfigImages } from './sync-images.js'
+import { loadCache, saveCache, hashFile, isCacheHit, makeCacheEntry } from './cache.js'
+import { extractSvgRefsFromXml } from '../analyzers/class-extractor.js'
+import { extractSvgRefsFromController } from '../analyzers/controller-svg-refs.js'
+import { getConfigFile } from '../../shared/config-manager.js'
+
+/**
+ * Run the SVG image pipeline as a post-step of `purgetss` (purge command).
+ *
+ * Silent (no-op) when no SVG references are found. Logs progress at each step
+ * so the user can trace cache hits, dimension changes, and skipped SVGs.
+ *
+ * @param {Object} args
+ * @param {string} args.tssContent - Final purged TSS string (in memory).
+ * @param {string[]} args.viewPaths - Absolute paths to view .xml files.
+ * @param {string[]} args.controllerPaths - Absolute paths to controller .js files.
+ * @param {Object} args.logger - Logger with `.info/.warning/.success/.file`.
+ * @returns {Promise<void>}
+ */
+export async function runSvgPipeline({ tssContent, viewPaths, controllerPaths, logger }) {
+   
+  const imagesFolder = projectsPurge_TSS_Images_Folder
+  if (!fs.existsSync(imagesFolder)) return
+
+  const refsBySvg = collectRefs({ viewPaths, controllerPaths })
+  if (refsBySvg.size === 0) return
+
+  logger.info('Resolving SVG dimensions from app.tss...')
+  const tssMap = parseTssMap(tssContent)
+  const derived = await deriveDimensions({ refsBySvg, tssMap, imagesFolder, logger })
+  if (derived.size === 0) return
+
+  // Sync config.cjs first so external runs (`purgetss images`) reflect the
+  // current resolution even if the cache short-circuits actual generation.
+  // The returned `effective` map merges derived values with any pre-existing
+  // manual overrides (config wins when its width is higher). The actual file
+  // write is gated by `images.autoSync` so devs who prefer hand-managed config
+  // can opt out.
+  const autoSync = readAutoSyncFlag()
+  const { stats, effective } = syncConfigImages(derived, { logger, write: autoSync })
+  if (autoSync && (stats.inserted || stats.updated)) {
+    logger.info(
+      `config.cjs > images.files: ${stats.inserted} inserted, ${stats.updated} updated, ${stats.untouched} untouched`
+    )
+  } else if (!autoSync && (stats.inserted || stats.updated)) {
+    logger.info(
+      `images.autoSync is off — would have ${stats.inserted ? `inserted ${stats.inserted}` : ''}${stats.inserted && stats.updated ? ', ' : ''}${stats.updated ? `updated ${stats.updated}` : ''} entry/entries in config.cjs > images.files`
+    )
+  }
+
+  await generatePngs({ derived: effective, imagesFolder, logger })
+}
+
+function collectRefs({ viewPaths, controllerPaths }) {
+  const refsBySvg = new Map()
+  const push = (src, classes) => {
+    const relPath = normalizeSvgSrc(src)
+    if (!relPath) return
+    if (!refsBySvg.has(relPath)) refsBySvg.set(relPath, [])
+    refsBySvg.get(relPath).push({ classes })
+  }
+
+  for (const file of viewPaths) {
+    const text = fs.readFileSync(file, 'utf8')
+    if (!text) continue
+    let refs
+    try {
+      refs = extractSvgRefsFromXml(text, file)
+    } catch {
+      // Malformed XML is reported by the regular purge path already; the SVG
+      // pipeline silently skips so we don't double-error on the same file.
+      continue
+    }
+    for (const ref of refs) push(ref.src, ref.classes)
+  }
+
+  for (const file of controllerPaths) {
+    const text = fs.readFileSync(file, 'utf8')
+    if (!text) continue
+    const refs = extractSvgRefsFromController(text)
+    for (const ref of refs) push(ref.src, ref.classes)
+  }
+
+  return refsBySvg
+}
+
+// Map `/images/logos/foo.svg` → `logos/foo.svg`. Anything outside the
+// `/images/` namespace is unknown to this pipeline and returns null.
+function normalizeSvgSrc(src) {
+  if (typeof src !== 'string') return null
+  const stripped = src.replace(/^\/+/, '')
+  if (!stripped.startsWith('images/')) return null
+  return stripped.slice('images/'.length)
+}
+
+async function generatePngs({ derived, imagesFolder, logger }) {
+  const projectType = detectProjectType(cwd)
+  const { androidBaseDir, iphoneBaseDir } = resolveOutputDirs(cwd, projectType)
+  const cache = loadCache()
+  let generated = 0
+  let cached = 0
+
+  // The SVG pipeline always emits PNG, even if `images.format` is set to
+  // 'webp' / 'jpeg' / etc. for the standalone `purgetss images` command.
+  // Verified empirically: Titanium's `image="/.../foo.svg"` runtime fallback
+  // resolves to `.png` only — `.webp` and other formats are not picked up.
+  // Honoring images.format here would silently generate files Titanium can't
+  // load. The standalone command keeps respecting format for raster sources
+  // (where the reference uses the actual extension).
+  for (const [relPath, { widthDp, heightDp }] of derived) {
+    const absSvg = path.join(imagesFolder, relPath)
+    const relForOutput = swapExt(relPath, '.png')
+    const targets = enumerateTargets({ relForOutput, androidBaseDir, iphoneBaseDir })
+
+    const svgHash = hashFile(absSvg)
+    if (isCacheHit(cache[relPath], svgHash, widthDp, heightDp, targets)) {
+      cached++
+      continue
+    }
+
+    try {
+      await genAndroidScales(absSvg, relPath, androidBaseDir, { baseWidth: widthDp, baseHeight: heightDp })
+      await genIphoneScales(absSvg, relPath, iphoneBaseDir, { baseWidth: widthDp, baseHeight: heightDp })
+    } catch (err) {
+      logger.warning(`✗ ${relPath}: ${err.message}`)
+      continue
+    }
+
+    cache[relPath] = makeCacheEntry(svgHash, widthDp, heightDp, targets)
+    generated++
+    logger.info(`✓ ${relPath} → ${widthDp}×${heightDp}dp`)
+  }
+
+  saveCache(cache)
+  if (generated || cached) {
+    logger.info(`SVG pipeline: ${generated} generated, ${cached} cached.`)
+  }
+}
+
+function resolveOutputDirs(projectRoot, projectType) {
+  if (projectType === 'classic') {
+    return {
+      androidBaseDir: path.join(projectRoot, 'Resources', 'android', 'images'),
+      iphoneBaseDir: path.join(projectRoot, 'Resources', 'iphone', 'images')
+    }
+  }
+  return {
+    androidBaseDir: path.join(projectRoot, 'app', 'assets', 'android', 'images'),
+    iphoneBaseDir: path.join(projectRoot, 'app', 'assets', 'iphone', 'images')
+  }
+}
+
+function enumerateTargets({ relForOutput, androidBaseDir, iphoneBaseDir }) {
+  const out = []
+  const parsed = path.parse(relForOutput)
+  for (const { name } of ANDROID_SCALES) {
+    out.push(path.join(androidBaseDir, name, relForOutput))
+  }
+  for (const { suffix } of IPHONE_SCALES) {
+    out.push(path.join(iphoneBaseDir, parsed.dir, `${parsed.name}${suffix}${parsed.ext}`))
+  }
+  return out
+}
+
+function swapExt(relPath, newExt) {
+  const parsed = path.parse(relPath)
+  return path.join(parsed.dir, parsed.name + newExt)
+}
+
+// Read `images.autoSync` from config; defaults to true. The SVG pipeline
+// ignores `images.format` / `images.quality` on purpose — see the comment in
+// generatePngs about Titanium's .svg → .png-only fallback.
+function readAutoSyncFlag() {
+  try {
+    const cfg = getConfigFile()
+    if (cfg && typeof cfg.images === 'object' && cfg.images.autoSync === false) {
+      return false
+    }
+  } catch { /* fall through to default */ }
+  return true
+}

package/src/core/svg/resolve-classes.js

@@ -0,0 +1,46 @@
+/**
+ * PurgeTSS - Class cascade resolver for the SVG pipeline
+ *
+ * Given an ordered list of classes (as they appear in `class=""` / `classes:`)
+ * and the class→props map produced by tss-reader, apply later-wins cascading
+ * to return the final width and height.
+ *
+ * V1 limitations (out of scope, see plan):
+ *   - Tag selectors (`'View': { ... }`) not applied
+ *   - ID selectors (`'#foo': { ... }`) not applied
+ *   - Platform/device modifiers (`'[platform=ios]'`) not applied
+ *
+ * If a project needs any of these, add the SVG to `images.files` manually.
+ *
+ * @fileoverview Cascade resolver: classes[] + tssMap → { width, height }
+ * @author César Estrada
+ */
+
+/**
+ * Resolve width/height for a list of classes by applying later-wins cascading.
+ * Classes that don't exist in the map are skipped silently — they may be
+ * unknown utilities, typos, or classes registered via tag/ID selectors that
+ * V1 doesn't see.
+ *
+ * Returned value shape per dimension:
+ *   - number    → resolved to a finite dp value
+ *   - 'auto'    → resolved to Ti.UI.SIZE
+ *   - 'fill'    → resolved to Ti.UI.FILL
+ *   - 'percent' → resolved to a percentage / non-numeric (can't size a PNG)
+ *   - null      → no class in the list set this dimension
+ *
+ * @param {string[]} classes - Class tokens in source order.
+ * @param {Map} tssMap - Output of parseTssMap().
+ * @returns {{ width: number|'auto'|'fill'|'percent'|null, height: number|'auto'|'fill'|'percent'|null }}
+ */
+export function resolveDimensions(classes, tssMap) {
+  let width = null
+  let height = null
+  for (const cls of classes) {
+    const entry = tssMap.get(cls)
+    if (!entry) continue
+    if (entry.width !== undefined) width = entry.width
+    if (entry.height !== undefined) height = entry.height
+  }
+  return { width, height }
+}