poops-images 1.0.0

package/lib/analyze.js

@@ -0,0 +1,177 @@
+import path from 'node:path'
+import sharp from 'sharp'
+import exifReader from 'exif-reader'
+import { hasTransparency } from './formats.js'
+import { dmsToDecimal, formatDms } from './utils/format.js'
+import log from './utils/log.js'
+
+function formatExposure(value) {
+  if (value >= 1) return `${value}s`
+  return `1/${Math.round(1 / value)}`
+}
+
+export function extractExif(raw) {
+  if (!raw) return null
+
+  const image = raw.Image || {}
+  const photo = raw.Photo || {}
+  const gps = raw.GPSInfo || {}
+
+  const result = {
+    make: image.Make || null,
+    model: image.Model || null,
+    orientation: image.Orientation || null,
+    resolution: (image.XResolution || image.YResolution)
+      ? { x: image.XResolution, y: image.YResolution }
+      : null,
+    dateTime: image.DateTime || null,
+    offsetTime: photo.OffsetTime || null,
+    fNumber: photo.FNumber || null,
+    exposure: photo.ExposureTime != null
+      ? { value: photo.ExposureTime, formatted: formatExposure(photo.ExposureTime) }
+      : null,
+    iso: photo.ISOSpeedRatings || null,
+    focalLength: photo.FocalLength || null,
+    focalLength35mm: photo.FocalLengthIn35mmFilm || null,
+    flash: photo.Flash != null ? !!(photo.Flash & 1) : null,
+    lensModel: photo.LensModel || null,
+    software: image.Software || null,
+    gps: null,
+  }
+
+  if (gps.GPSLatitude && gps.GPSLongitude) {
+    const latDecimal = dmsToDecimal(gps.GPSLatitude, gps.GPSLatitudeRef)
+    const lonDecimal = dmsToDecimal(gps.GPSLongitude, gps.GPSLongitudeRef)
+
+    result.gps = {
+      latitude: {
+        degrees: gps.GPSLatitude,
+        ref: gps.GPSLatitudeRef,
+        decimal: latDecimal,
+        formatted: formatDms(gps.GPSLatitude, gps.GPSLatitudeRef),
+      },
+      longitude: {
+        degrees: gps.GPSLongitude,
+        ref: gps.GPSLongitudeRef,
+        decimal: lonDecimal,
+        formatted: formatDms(gps.GPSLongitude, gps.GPSLongitudeRef),
+      },
+      altitude: gps.GPSAltitude != null
+        ? { value: Math.round(gps.GPSAltitude * 100) / 100, ref: gps.GPSAltitudeRef }
+        : null,
+      direction: gps.GPSImgDirection != null
+        ? Math.round(gps.GPSImgDirection * 100) / 100
+        : null,
+      speed: gps.GPSSpeed != null
+        ? { value: Math.round(gps.GPSSpeed * 100) / 100, unit: gps.GPSSpeedRef === 'K' ? 'km/h' : gps.GPSSpeedRef === 'M' ? 'mph' : 'knots' }
+        : null,
+      dateTime: null,
+      googleMapsUrl: `https://www.google.com/maps?q=${latDecimal},${lonDecimal}`,
+    }
+
+    if (gps.GPSDateStamp && gps.GPSTimeStamp) {
+      const [year, month, day] = gps.GPSDateStamp.split(':')
+      const [hours, minutes, seconds] = gps.GPSTimeStamp
+      const h = String(Math.floor(hours)).padStart(2, '0')
+      const m = String(Math.floor(minutes)).padStart(2, '0')
+      const s = String(Math.floor(seconds)).padStart(2, '0')
+      result.gps.dateTime = `${year}-${month}-${day}T${h}:${m}:${s}Z`
+    }
+  }
+
+  return result
+}
+
+export async function analyzeImage(inputPath, config, stat) {
+  const relativePath = path.relative(config.in, inputPath)
+  const parsed = path.parse(relativePath)
+  const originalExt = parsed.ext.replace('.', '').toLowerCase()
+
+  // Read metadata
+  let metadata
+  try {
+    metadata = await sharp(inputPath).metadata()
+  } catch (err) {
+    log({ tag: 'error', text: `Failed to read metadata: ${err.message}`, link: relativePath })
+    return null
+  }
+
+  // Parse EXIF data if available — extract only important fields
+  let exif = null
+  if (metadata.exif) {
+    try {
+      exif = extractExif(exifReader(metadata.exif))
+    } catch {
+      // Malformed EXIF — ignore
+    }
+  }
+
+  // Normalize base format for web output
+  const normalizedExt = { jpeg: 'jpg', tif: 'tiff' }[originalExt] || originalExt
+  let outputExt = normalizedExt
+  let transparent = false
+
+  // Formats that support alpha and need transparency detection
+  const alphaFormats = new Set(['png', 'tiff', 'heic', 'heif', 'gif'])
+
+  // Check transparency for alpha-capable formats (needed for default + smart modes)
+  const formatIncludesSmart = config.format === 'smart' ||
+    (Array.isArray(config.format) && config.format.includes('smart'))
+
+  const needsTransparencyCheck =
+    alphaFormats.has(normalizedExt) &&
+    (config.format === false || formatIncludesSmart)
+
+  if (needsTransparencyCheck) {
+    transparent = await hasTransparency(sharp(inputPath))
+  }
+
+  // Formats that aren't web-native and need normalization to jpg/png
+  const nonWebFormats = new Set(['tiff', 'heic', 'heif', 'gif'])
+
+  // Default mode: normalize non-web formats
+  if (config.format === false) {
+    if (originalExt === 'png' && !transparent) {
+      outputExt = 'jpg'
+      log({ tag: 'image', text: 'Opaque PNG \u2192 JPEG:', link: relativePath })
+    } else if (nonWebFormats.has(normalizedExt)) {
+      const label = normalizedExt.toUpperCase()
+      if (transparent) {
+        outputExt = 'png'
+        log({ tag: 'image', text: `Transparent ${label} \u2192 PNG:`, link: relativePath })
+      } else {
+        outputExt = 'jpg'
+        log({ tag: 'image', text: `${label} \u2192 JPEG:`, link: relativePath })
+      }
+    }
+  }
+
+  // Build effective sizes list — include original unless skipOriginal
+  let effectiveSizes = config.sizes
+  if (!config.skipOriginal) {
+    const hasPassthrough = effectiveSizes.some(s => s.width === 0 && s.height === 0)
+    if (!hasPassthrough) {
+      effectiveSizes = [{ name: '', width: 0, height: 0, crop: false }, ...effectiveSizes]
+    }
+  }
+
+  // EXIF orientations 5-8 swap width/height
+  const swapped = metadata.orientation >= 5
+  const sourceWidth = swapped ? metadata.height : metadata.width
+  const sourceHeight = swapped ? metadata.width : metadata.height
+
+  return {
+    inputPath,
+    relativePath,
+    parsed,
+    originalExt,
+    outputExt,
+    transparent,
+    sourceWidth,
+    sourceHeight,
+    exif,
+    mtime: stat.mtimeMs,
+    fileSize: stat.size,
+    effectiveSizes
+  }
+}

package/lib/cache.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const CACHE_FILENAME = '.poops-images-cache.json'
+
+export default class Cache {
+  constructor(outputDir, cacheOption = true) {
+    this.outputDir = outputDir
+    this.disabled = cacheOption === false
+
+    if (this.disabled) {
+      this.cachePath = null
+    } else if (typeof cacheOption === 'string') {
+      this.cachePath = path.isAbsolute(cacheOption)
+        ? cacheOption
+        : path.join(outputDir, cacheOption)
+    } else {
+      this.cachePath = path.join(outputDir, CACHE_FILENAME)
+    }
+
+    this.data = { configHash: null, entries: {} }
+  }
+
+  load() {
+    if (this.disabled) return
+    try {
+      if (fs.existsSync(this.cachePath)) {
+        this.data = JSON.parse(fs.readFileSync(this.cachePath, 'utf-8'))
+      }
+    } catch {
+      this.data = { configHash: null, entries: {} }
+    }
+  }
+
+  save() {
+    if (this.disabled) return
+    fs.mkdirSync(path.dirname(this.cachePath), { recursive: true })
+    fs.writeFileSync(this.cachePath, JSON.stringify(this.data, null, 2))
+  }
+
+  getConfigHash() {
+    return this.data.configHash
+  }
+
+  setConfigHash(hash) {
+    this.data.configHash = hash
+  }
+
+  invalidateAll() {
+    // Mark all entries stale (mtime = -1) so shouldSkip returns false,
+    // but preserve outputs for stale file cleanup
+    for (const key of Object.keys(this.data.entries)) {
+      this.data.entries[key].mtime = -1
+    }
+  }
+
+  getEntry(relativePath) {
+    return this.data.entries[relativePath] || null
+  }
+
+  setEntry(relativePath, entry) {
+    this.data.entries[relativePath] = entry
+  }
+
+  removeEntry(relativePath) {
+    delete this.data.entries[relativePath]
+  }
+
+  shouldSkip(relativePath, mtime, size) {
+    if (this.disabled) return false
+    const entry = this.getEntry(relativePath)
+    if (!entry) return false
+
+    if (entry.mtime !== mtime || entry.size !== size) return false
+
+    // Check all outputs still exist on disk
+    if (entry.outputs && Array.isArray(entry.outputs)) {
+      for (const output of entry.outputs) {
+        const outputPath = typeof output === 'string' ? output : output.path
+        if (!fs.existsSync(path.join(this.outputDir, outputPath))) return false
+      }
+    }
+
+    return true
+  }
+
+  getOutputs(relativePath) {
+    const entry = this.getEntry(relativePath)
+    return entry?.outputs || []
+  }
+}

package/lib/config.js

@@ -0,0 +1,159 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { validateSize } from './sizes.js'
+
+// Output formats only — tiff/tif/heic/heif/gif are input formats normalized to jpg/png during processing
+const SUPPORTED_FORMATS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif'])
+
+const DEFAULTS = {
+  in: '.',
+  out: '.',
+  sizes: [],
+  quality: {
+    jpg: 82,
+    webp: 80,
+    avif: 60,
+    png: 90
+  },
+  include: '**/*.{jpg,jpeg,png,tiff,tif,webp,heic,heif}',
+  exclude: [],
+  concurrency: 4,
+  format: false,
+  skipOriginal: false,
+  cache: true
+}
+
+export function loadConfig(configPath) {
+  const cwd = process.cwd()
+
+  let raw = null
+  let resolvedPath = null
+
+  if (configPath) {
+    resolvedPath = path.resolve(cwd, configPath)
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`Config file not found: ${resolvedPath}`)
+    }
+    raw = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'))
+  } else {
+    // Try poops-images.json first
+    resolvedPath = path.resolve(cwd, 'poops-images.json')
+    if (fs.existsSync(resolvedPath)) {
+      raw = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'))
+    } else {
+      // Fallback: read images key from poops.json
+      resolvedPath = path.resolve(cwd, 'poops.json')
+      if (fs.existsSync(resolvedPath)) {
+        const poopsConfig = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'))
+        if (poopsConfig.images) {
+          raw = poopsConfig.images
+        }
+      }
+
+      if (!raw) {
+        // Try 💩.json as last fallback
+        resolvedPath = path.resolve(cwd, '💩.json')
+        if (fs.existsSync(resolvedPath)) {
+          const poopsConfig = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'))
+          if (poopsConfig.images) {
+            raw = poopsConfig.images
+          }
+        }
+      }
+
+      if (!raw) {
+        throw new Error('No config found. Create poops-images.json or add "images" key to poops.json')
+      }
+    }
+  }
+
+  return validateConfig(raw)
+}
+
+export function validateConfig(raw) {
+  const config = { ...DEFAULTS, ...raw }
+
+  if (typeof config.in !== 'string') {
+    throw new Error('Config "in" must be a string path')
+  }
+
+  if (typeof config.out !== 'string') {
+    throw new Error('Config "out" must be a string path')
+  }
+
+  if (!Array.isArray(config.sizes)) {
+    throw new Error('Config "sizes" must be an array')
+  }
+
+  // Empty sizes = conversion-only mode (no resize, just format convert)
+  if (config.sizes.length === 0) {
+    config.sizes = [{ width: 0, height: 0 }]
+  }
+
+  config.sizes = config.sizes.map(validateSize)
+
+  if (typeof config.quality === 'number') {
+    const q = config.quality
+    if (q < 1 || q > 100) {
+      throw new Error('Config "quality" must be between 1 and 100')
+    }
+    config.quality = { jpg: q, webp: q, avif: q, png: q }
+  } else if (typeof config.quality !== 'object') {
+    throw new Error('Config "quality" must be a number or an object')
+  } else {
+    config.quality = { ...DEFAULTS.quality, ...config.quality }
+    for (const [key, val] of Object.entries(config.quality)) {
+      if (typeof val !== 'number' || val < 1 || val > 100) {
+        throw new Error(`Config "quality.${key}" must be a number between 1 and 100`)
+      }
+    }
+  }
+
+  if (typeof config.include !== 'string') {
+    throw new Error('Config "include" must be a string glob pattern')
+  }
+
+  if (!Array.isArray(config.exclude)) {
+    config.exclude = config.exclude ? [config.exclude] : []
+  }
+
+  if (typeof config.concurrency !== 'number' || config.concurrency < 1) {
+    config.concurrency = DEFAULTS.concurrency
+  }
+
+  config.skipOriginal = !!config.skipOriginal
+
+  if (config.cache !== false && config.cache !== true && typeof config.cache !== 'string') {
+    throw new Error('Config "cache" must be false, true, or a string path')
+  }
+
+  if (config.format !== false) {
+    const fmts = Array.isArray(config.format)
+      ? config.format
+      : typeof config.format === 'string'
+        ? [config.format]
+        : null
+    if (fmts === null) {
+      throw new Error('Config "format" must be false, a format string, or an array of format strings')
+    }
+    for (const f of fmts) {
+      if (f === 'smart') continue
+      if (!SUPPORTED_FORMATS.has(f)) {
+        throw new Error(`Unsupported format: "${f}"`)
+      }
+    }
+  }
+
+  return config
+}
+
+export function configHash(config) {
+  const hashable = {
+    sizes: config.sizes,
+    format: config.format,
+    quality: config.quality,
+    skipOriginal: config.skipOriginal
+  }
+  return crypto.createHash('md5').update(JSON.stringify(hashable)).digest('hex')
+}

package/lib/discover.js

@@ -0,0 +1,34 @@
+import { glob } from 'glob'
+import path from 'node:path'
+
+export async function discoverSources(config) {
+  const pattern = path.join(config.in, config.include)
+  const ignore = [
+    ...config.exclude.map(e => path.join(config.in, e)),
+    // SVG and GIF have dedicated pipelines — exclude from raster discovery
+    path.join(config.in, '**/*.svg'),
+    path.join(config.in, '**/*.gif')
+  ]
+  return glob(pattern, { ignore, nodir: true })
+}
+
+export async function discoverSvgs(config) {
+  const pattern = path.join(config.in, '**/*.svg')
+  const ignore = config.exclude.map(e => path.join(config.in, e))
+  return glob(pattern, { ignore, nodir: true })
+}
+
+export async function discoverGifs(config) {
+  const pattern = path.join(config.in, '**/*.gif')
+  const ignore = config.exclude.map(e => path.join(config.in, e))
+  return glob(pattern, { ignore, nodir: true })
+}
+
+export async function discoverAll(config) {
+  const [raster, svg, gif] = await Promise.all([
+    discoverSources(config),
+    discoverSvgs(config),
+    discoverGifs(config)
+  ])
+  return { raster, svg, gif }
+}

package/lib/formats.js

@@ -0,0 +1,107 @@
+import sharp from 'sharp'
+
+const FORMAT_MAP = {
+  jpg: 'jpeg',
+  jpeg: 'jpeg',
+  png: 'png',
+  webp: 'webp',
+  avif: 'avif',
+  gif: 'gif',
+  tiff: 'tiff',
+  tif: 'tiff',
+  heic: 'heif',
+  heif: 'heif'
+}
+
+const EXT_MAP = {
+  jpeg: 'jpg',
+  jpg: 'jpg',
+  png: 'png',
+  webp: 'webp',
+  avif: 'avif',
+  gif: 'gif',
+  tiff: 'tiff',
+  tif: 'tif',
+  heic: 'heic',
+  heif: 'heif'
+}
+
+export function toSharpFormat(ext) {
+  return FORMAT_MAP[ext.toLowerCase()] || ext.toLowerCase()
+}
+
+export function toFileExt(format) {
+  return EXT_MAP[format.toLowerCase()] || format.toLowerCase()
+}
+
+export function getQuality(format, qualityConfig) {
+  const ext = toFileExt(format)
+  return qualityConfig[ext] || qualityConfig[format] || 80
+}
+
+export async function hasTransparency(sharpInstance) {
+  const { channels, hasAlpha } = await sharpInstance.metadata()
+  if (!hasAlpha || channels < 4) return false
+
+  const { channels: channelStats } = await sharpInstance.stats()
+  // Alpha is the last channel — if its min is 255, every pixel is fully opaque
+  const alphaStats = channelStats[channels - 1]
+  return alphaStats.min < 255
+}
+
+export async function convertFormat(sharpInstance, targetFormat, qualityConfig) {
+  const fmt = toSharpFormat(targetFormat)
+  const quality = getQuality(targetFormat, qualityConfig)
+
+  const opts = { quality }
+  if (fmt === 'png') {
+    opts.compressionLevel = Math.round((100 - quality) / 100 * 9)
+    delete opts.quality
+  }
+
+  const buffer = await sharpInstance.clone().toFormat(fmt, opts).toBuffer()
+  return buffer
+}
+
+export async function resolveTargetFormats(outputExt, transparent, rawData, formatConfig, qualityConfig) {
+  const preEncoded = new Map()
+
+  // Default: just the normalized base format
+  if (formatConfig === false) return { formats: [outputExt], preEncoded }
+
+  // Expand format config to array
+  const fmts = typeof formatConfig === 'string' ? [formatConfig] : [...formatConfig]
+
+  // Resolve 'smart' entries
+  const hasSmart = fmts.includes('smart')
+  const result = fmts.filter(f => f !== 'smart')
+
+  if (hasSmart) {
+    if (transparent) {
+      result.push('webp')
+    } else {
+      // Compare jpg vs webp, pick smaller — keep the winner buffer to avoid re-encoding
+      const [jpgBuf, webpBuf] = await Promise.all([
+        sharp(rawData)
+          .toFormat('jpeg', { quality: getQuality('jpg', qualityConfig) })
+          .toBuffer(),
+        sharp(rawData)
+          .toFormat('webp', { quality: getQuality('webp', qualityConfig) })
+          .toBuffer()
+      ])
+      if (webpBuf.length < jpgBuf.length) {
+        result.push('webp')
+        preEncoded.set('webp', webpBuf)
+      } else {
+        result.push('jpg')
+        preEncoded.set('jpg', jpgBuf)
+      }
+    }
+  }
+
+  // Normalize jpeg → jpg and dedupe
+  return {
+    formats: [...new Set(result.map(f => f === 'jpeg' ? 'jpg' : f))],
+    preEncoded
+  }
+}