1#!/usr/bin/env node
2/**
3 * validate-asset.cjs
4 *
5 * Validates marketing assets against brand guidelines.
6 * Checks: file naming, dimensions, file size, metadata.
7 *
8 * Usage:
9 *   node validate-asset.cjs <asset-path>
10 *   node validate-asset.cjs <asset-path> --json
11 *   node validate-asset.cjs <asset-path> --fix
12 *
13 * For color validation of images, use with extract-colors.cjs
14 */
15 
16const fs = require("fs");
17const path = require("path");
18 
19// Validation rules
20const RULES = {
21  naming: {
22    pattern: /^[a-z]+_[a-z0-9-]+_[a-z0-9-]+_\d{8}(_[a-z0-9-]+)?\.[a-z]+$/,
23    description:
24      "{type}_{campaign}_{description}_{timestamp}_{variant}.{ext}",
25    examples: [
26      "banner_claude-launch_hero-image_20251209.png",
27      "logo_brand-refresh_horizontal_20251209_dark.svg",
28    ],
29  },
30  dimensions: {
31    banner: { minWidth: 600, minHeight: 300 },
32    logo: { minWidth: 100, minHeight: 100 },
33    design: { minWidth: 800, minHeight: 600 },
34    video: { minWidth: 640, minHeight: 480 },
35    default: { minWidth: 100, minHeight: 100 },
36  },
37  fileSize: {
38    image: { max: 5 * 1024 * 1024, recommended: 1 * 1024 * 1024 },
39    video: { max: 100 * 1024 * 1024, recommended: 50 * 1024 * 1024 },
40    svg: { max: 500 * 1024, recommended: 100 * 1024 },
41  },
42  formats: {
43    image: ["png", "jpg", "jpeg", "webp", "gif"],
44    vector: ["svg"],
45    video: ["mp4", "mov", "webm"],
46    document: ["pdf", "psd", "ai", "fig"],
47  },
48};
49 
50/**
51 * Parse asset filename
52 */
53function parseFilename(filename) {
54  const parts = filename.replace(/\.[^.]+$/, "").split("_");
55 
56  if (parts.length < 4) {
57    return null;
58  }
59 
60  return {
61    type: parts[0],
62    campaign: parts[1],
63    description: parts[2],
64    timestamp: parts[3],
65    variant: parts.length > 4 ? parts[4] : null,
66    extension: path.extname(filename).slice(1).toLowerCase(),
67  };
68}
69 
70/**
71 * Validate filename convention
72 */
73function validateFilename(filename) {
74  const issues = [];
75  const suggestions = [];
76 
77  // Check pattern match
78  if (!RULES.naming.pattern.test(filename)) {
79    issues.push("Filename does not match naming convention");
80    suggestions.push(`Expected format: ${RULES.naming.description}`);
81    suggestions.push(`Examples: ${RULES.naming.examples.join(", ")}`);
82  }
83 
84  // Parse and check components
85  const parsed = parseFilename(filename);
86  if (parsed) {
87    // Check timestamp format
88    if (!/^\d{8}$/.test(parsed.timestamp)) {
89      issues.push("Timestamp should be YYYYMMDD format");
90    }
91 
92    // Check kebab-case for campaign and description
93    if (parsed.campaign && !/^[a-z0-9-]+$/.test(parsed.campaign)) {
94      issues.push("Campaign name should be kebab-case");
95    }
96 
97    if (parsed.description && !/^[a-z0-9-]+$/.test(parsed.description)) {
98      issues.push("Description should be kebab-case");
99    }
100 
101    // Check valid type
102    const validTypes = [
103      "banner",
104      "logo",
105      "design",
106      "video",
107      "infographic",
108      "icon",
109      "photo",
110    ];
111    if (!validTypes.includes(parsed.type)) {
112      suggestions.push(`Consider using type: ${validTypes.join(", ")}`);
113    }
114  }
115 
116  return { valid: issues.length === 0, issues, suggestions, parsed };
117}
118 
119/**
120 * Validate file size
121 */
122function validateFileSize(filepath, extension) {
123  const issues = [];
124  const warnings = [];
125 
126  const stats = fs.statSync(filepath);
127  const size = stats.size;
128 
129  let limits;
130  if (RULES.formats.video.includes(extension)) {
131    limits = RULES.fileSize.video;
132  } else if (extension === "svg") {
133    limits = RULES.fileSize.svg;
134  } else {
135    limits = RULES.fileSize.image;
136  }
137 
138  if (size > limits.max) {
139    issues.push(
140      `File size (${formatBytes(size)}) exceeds maximum (${formatBytes(
141        limits.max
142      )})`
143    );
144  } else if (size > limits.recommended) {
145    warnings.push(
146      `File size (${formatBytes(size)}) exceeds recommended (${formatBytes(
147        limits.recommended
148      )})`
149    );
150  }
151 
152  return { valid: issues.length === 0, issues, warnings, size };
153}
154 
155/**
156 * Validate file format
157 */
158function validateFormat(extension) {
159  const issues = [];
160  const info = { category: null };
161 
162  const allFormats = [
163    ...RULES.formats.image,
164    ...RULES.formats.vector,
165    ...RULES.formats.video,
166    ...RULES.formats.document,
167  ];
168 
169  if (!allFormats.includes(extension)) {
170    issues.push(`Unsupported file format: .${extension}`);
171    return { valid: false, issues, info };
172  }
173 
174  // Determine category
175  if (RULES.formats.image.includes(extension)) info.category = "image";
176  else if (RULES.formats.vector.includes(extension)) info.category = "vector";
177  else if (RULES.formats.video.includes(extension)) info.category = "video";
178  else if (RULES.formats.document.includes(extension))
179    info.category = "document";
180 
181  return { valid: true, issues, info };
182}
183 
184/**
185 * Check if asset exists in manifest
186 */
187function checkManifest(filepath) {
188  const manifestPath = path.join(process.cwd(), ".assets", "manifest.json");
189 
190  if (!fs.existsSync(manifestPath)) {
191    return { registered: false, message: "Manifest not found" };
192  }
193 
194  try {
195    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
196    const relativePath = path.relative(process.cwd(), filepath);
197    const found = manifest.assets?.find(
198      (a) => a.path === relativePath || a.path === filepath
199    );
200 
201    return {
202      registered: !!found,
203      message: found ? "Asset registered in manifest" : "Asset not in manifest",
204      asset: found,
205    };
206  } catch {
207    return { registered: false, message: "Error reading manifest" };
208  }
209}
210 
211/**
212 * Generate suggested filename
213 */
214function suggestFilename(original, parsed) {
215  if (!parsed) return null;
216 
217  const today = new Date().toISOString().slice(0, 10).replace(/-/g, "");
218  const type = parsed.type || "asset";
219  const campaign = parsed.campaign || "general";
220  const description = parsed.description || "untitled";
221  const ext = parsed.extension || "png";
222 
223  return `${type}_${campaign}_${description}_${today}.${ext}`;
224}
225 
226/**
227 * Format bytes to human readable
228 */
229function formatBytes(bytes) {
230  if (bytes === 0) return "0 Bytes";
231  const k = 1024;
232  const sizes = ["Bytes", "KB", "MB", "GB"];
233  const i = Math.floor(Math.log(bytes) / Math.log(k));
234  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
235}
236 
237/**
238 * Main validation function
239 */
240function validateAsset(assetPath) {
241  const results = {
242    path: assetPath,
243    filename: path.basename(assetPath),
244    valid: true,
245    issues: [],
246    warnings: [],
247    suggestions: [],
248    checks: {},
249  };
250 
251  // Check file exists
252  if (!fs.existsSync(assetPath)) {
253    results.valid = false;
254    results.issues.push(`File not found: ${assetPath}`);
255    return results;
256  }
257 
258  const filename = path.basename(assetPath);
259  const extension = path.extname(filename).slice(1).toLowerCase();
260 
261  // 1. Validate filename
262  const filenameResult = validateFilename(filename);
263  results.checks.filename = filenameResult;
264  if (!filenameResult.valid) {
265    results.issues.push(...filenameResult.issues);
266    results.suggestions.push(...filenameResult.suggestions);
267  }
268 
269  // 2. Validate format
270  const formatResult = validateFormat(extension);
271  results.checks.format = formatResult;
272  if (!formatResult.valid) {
273    results.issues.push(...formatResult.issues);
274  }
275 
276  // 3. Validate file size
277  const sizeResult = validateFileSize(assetPath, extension);
278  results.checks.fileSize = sizeResult;
279  if (!sizeResult.valid) {
280    results.issues.push(...sizeResult.issues);
281  }
282  results.warnings.push(...sizeResult.warnings);
283 
284  // 4. Check manifest registration
285  const manifestResult = checkManifest(assetPath);
286  results.checks.manifest = manifestResult;
287  if (!manifestResult.registered) {
288    results.warnings.push("Asset not registered in manifest.json");
289    results.suggestions.push(
290      "Register asset in .assets/manifest.json for tracking"
291    );
292  }
293 
294  // 5. Suggest corrected filename if needed
295  if (!filenameResult.valid && filenameResult.parsed) {
296    const suggested = suggestFilename(filename, filenameResult.parsed);
297    if (suggested) {
298      results.suggestions.push(`Suggested filename: ${suggested}`);
299    }
300  }
301 
302  // Overall validity
303  results.valid = results.issues.length === 0;
304 
305  return results;
306}
307 
308/**
309 * Format output for console
310 */
311function formatOutput(results) {
312  const lines = [];
313 
314  lines.push("\n" + "=".repeat(60));
315  lines.push(`ASSET VALIDATION: ${results.filename}`);
316  lines.push("=".repeat(60));
317 
318  lines.push(`\nStatus: ${results.valid ? "PASS" : "FAIL"}`);
319  lines.push(`Path: ${results.path}`);
320 
321  if (results.issues.length > 0) {
322    lines.push("\nISSUES:");
323    results.issues.forEach((issue) => lines.push(`  - ${issue}`));
324  }
325 
326  if (results.warnings.length > 0) {
327    lines.push("\nWARNINGS:");
328    results.warnings.forEach((warning) => lines.push(`  - ${warning}`));
329  }
330 
331  if (results.suggestions.length > 0) {
332    lines.push("\nSUGGESTIONS:");
333    results.suggestions.forEach((suggestion) =>
334      lines.push(`  - ${suggestion}`)
335    );
336  }
337 
338  // File size info
339  if (results.checks.fileSize?.size) {
340    lines.push(`\nFile Size: ${formatBytes(results.checks.fileSize.size)}`);
341  }
342 
343  lines.push("\n" + "=".repeat(60));
344 
345  return lines.join("\n");
346}
347 
348/**
349 * Main
350 */
351function main() {
352  const args = process.argv.slice(2);
353  const jsonOutput = args.includes("--json");
354  const assetPath = args.find((a) => !a.startsWith("--"));
355 
356  if (!assetPath) {
357    console.error("Usage: node validate-asset.cjs <asset-path> [--json]");
358    console.error("\nExamples:");
359    console.error(
360      "  node validate-asset.cjs assets/banners/social-media/banner_launch_hero_20251209.png"
361    );
362    console.error(
363      "  node validate-asset.cjs assets/logos/icon-only/logo-icon.svg --json"
364    );
365    process.exit(1);
366  }
367 
368  // Resolve path
369  const resolvedPath = path.isAbsolute(assetPath)
370    ? assetPath
371    : path.join(process.cwd(), assetPath);
372 
373  // Validate
374  const results = validateAsset(resolvedPath);
375 
376  // Output
377  if (jsonOutput) {
378    console.log(JSON.stringify(results, null, 2));
379  } else {
380    console.log(formatOutput(results));
381  }
382 
383  // Exit with appropriate code
384  process.exit(results.valid ? 0 : 1);
385}
386 
387main();
388