repoimage 0.2.0

package/shared/src/role-guess.ts

@@ -0,0 +1,103 @@
+import { ROLES } from './schema';
+import type { ImageRole } from './types';
+
+const PATH_THUMB_WORD =
+  /\b(thumb|thumbnail|thumbs)\b|\/thumb\/|[-_.]thumb[-_.]/i;
+const PATH_HERO = /\b(hero|banner|splash)\b|\/hero\/|[-_.]hero[-_.]/i;
+const PATH_CONTENT = /\b(content|article|inline|screenshot|figures?)\b/i;
+
+const SMALL_DIM_SUFFIX = /[-_.](\d{2,3})x(\d{2,3})(?:[-_.]|\.|$)/gi;
+const SMALL_DIM_TOKEN = /\b(\d{2,3})x(\d{2,3})\b/gi;
+const WIDTH_ONLY_THUMB_SUFFIX = /[-_.](\d{2,3})x(?:\.|[-_]|$)/gi;
+const SMALL_DIM_MAX = 256;
+
+export const THUMB_MAX_DIMENSION = 200;
+export const HERO_MIN_WIDTH = 1200;
+export const HERO_MIN_ASPECT = 1.5;
+
+function pathHasSmallDimensionHint(lowerPath: string): boolean {
+  for (const re of [SMALL_DIM_SUFFIX, SMALL_DIM_TOKEN]) {
+    re.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(lowerPath)) !== null) {
+      const w = Number(match[1]);
+      const h = Number(match[2]);
+      if (w > 0 && h > 0 && w <= SMALL_DIM_MAX && h <= SMALL_DIM_MAX) {
+        return true;
+      }
+    }
+  }
+
+  WIDTH_ONLY_THUMB_SUFFIX.lastIndex = 0;
+  let widthOnly: RegExpExecArray | null;
+  while ((widthOnly = WIDTH_ONLY_THUMB_SUFFIX.exec(lowerPath)) !== null) {
+    const w = Number(widthOnly[1]);
+    if (w > 0 && w <= SMALL_DIM_MAX) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function finiteDimension(value: unknown): number | null {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export interface GuessRoleInput {
+  path?: string;
+  width?: number | null;
+  height?: number | null;
+  size?: number;
+}
+
+export interface GuessRoleResult {
+  roleGuess: ImageRole;
+  roleGuessReason?: string;
+}
+
+export function guessRole(entry: GuessRoleInput): GuessRoleResult {
+  const filePath = String(entry.path ?? '').replace(/\\/g, '/');
+  const lower = filePath.toLowerCase();
+  const width = finiteDimension(entry.width);
+  const height = finiteDimension(entry.height);
+  const maxDim = width != null && height != null ? Math.max(width, height) : null;
+  const aspect = width != null && height != null ? width / height : null;
+
+  if (PATH_THUMB_WORD.test(lower) || pathHasSmallDimensionHint(lower)) {
+    return { roleGuess: 'thumbnail', roleGuessReason: 'path suggests thumbnail' };
+  }
+  if (PATH_HERO.test(lower)) {
+    return { roleGuess: 'hero', roleGuessReason: 'path suggests hero or banner' };
+  }
+  if (PATH_CONTENT.test(lower)) {
+    return { roleGuess: 'content', roleGuessReason: 'path suggests inline content' };
+  }
+
+  if (maxDim != null && maxDim <= THUMB_MAX_DIMENSION) {
+    return {
+      roleGuess: 'thumbnail',
+      roleGuessReason: `max dimension ≤ ${THUMB_MAX_DIMENSION}px`
+    };
+  }
+
+  if (
+    width != null &&
+    height != null &&
+    width >= HERO_MIN_WIDTH &&
+    aspect != null &&
+    aspect >= HERO_MIN_ASPECT
+  ) {
+    return {
+      roleGuess: 'hero',
+      roleGuessReason: `wide image (≥${HERO_MIN_WIDTH}px wide, aspect ≥${HERO_MIN_ASPECT})`
+    };
+  }
+
+  return { roleGuess: 'unknown' };
+}
+
+export function isKnownRoleGuess(roleGuess: unknown): roleGuess is ImageRole {
+  return typeof roleGuess === 'string' && (ROLES as readonly string[]).includes(roleGuess);
+}

package/shared/src/schema.ts

@@ -0,0 +1,18 @@
+import type { ImageRole } from './types';
+
+export const CONFIG_FILENAME = '.repoimage.json';
+export const CONFIG_VERSION = 1;
+
+export const ROLES: readonly ImageRole[] = Object.freeze([
+  'hero',
+  'content',
+  'thumbnail',
+  'unknown'
+]);
+
+export const REPOIMAGE_GENERATOR =
+  'Roles confirmed with RepoImage — https://github.com/geroconnell/repoimage';
+
+export function isValidRole(role: unknown): role is ImageRole {
+  return typeof role === 'string' && (ROLES as readonly string[]).includes(role);
+}

package/shared/src/types.ts

@@ -0,0 +1,36 @@
+export type ImageRole = 'hero' | 'content' | 'thumbnail' | 'unknown';
+
+export interface ScanIssue {
+  code: string;
+  path: string;
+  message: string;
+}
+
+export interface ImageRow {
+  path: string;
+  size: number;
+  width: number | null;
+  height: number | null;
+  uncompressedSize: number | null;
+  compressionRatio: string | null;
+  role: ImageRole | null;
+  roleGuess: ImageRole;
+  roleGuessReason?: string;
+}
+
+export interface RawImageEntry {
+  path: string;
+  size: number;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface FsListEntry {
+  name: string;
+  path: string;
+  type: 'directory' | 'file' | 'symlink' | 'other';
+}
+
+export type FsListResult =
+  | { path: string; entries: FsListEntry[] }
+  | { error: string; message: string };

package/shared/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/test/cli.test.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const CLI_JS = path.join(__dirname, '..', 'server', 'dist', 'cli.js');
+
+const MINI_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64'
+);
+
+function tempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'repoimage-cli-'));
+}
+
+test('CLI --json returns images envelope', () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, 'one.png'), MINI_PNG);
+
+  const out = execFileSync(process.execPath, [CLI_JS, '--json', dir], { encoding: 'utf8' });
+  const data = JSON.parse(out.trim());
+
+  assert.ok(Array.isArray(data.images));
+  assert.ok(Array.isArray(data.issues));
+  assert.equal(data.images.length, 1);
+  assert.equal(data.images[0].path, 'one.png');
+});
+
+test('CLI --json --sort-by-score still returns valid JSON', () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, 'a.png'), MINI_PNG);
+  fs.writeFileSync(path.join(dir, 'b.png'), MINI_PNG);
+
+  const out = execFileSync(process.execPath, [CLI_JS, '--json', '--sort-by-score', dir], {
+    encoding: 'utf8'
+  });
+  const data = JSON.parse(out.trim());
+
+  assert.equal(data.images.length, 2);
+});
+
+test('CLI exits 1 with usage when no folders', () => {
+  assert.throws(
+    () =>
+      execFileSync(process.execPath, [CLI_JS, '--json'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }),
+    /Command failed/
+  );
+});

package/test/fs-list.test.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { listDirectory } = require('../server/dist/fs-list');
+
+function tempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'repoimage-fs-'));
+}
+
+test('listDirectory returns entries for a folder', () => {
+  const dir = tempDir();
+  fs.mkdirSync(path.join(dir, 'sub'));
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'x');
+
+  const out = listDirectory(dir);
+  assert.ok(!('error' in out));
+  assert.equal(out.path, dir.split(path.sep).join('/'));
+  const names = out.entries.map(e => e.name).sort();
+  assert.deepEqual(names, ['a.txt', 'sub']);
+  const sub = out.entries.find(e => e.name === 'sub');
+  assert.equal(sub.type, 'directory');
+});
+
+test('listDirectory ENOENT for missing path', () => {
+  const out = listDirectory(path.join(os.tmpdir(), 'repoimage-missing-' + Date.now()));
+  assert.equal(out.error, 'ENOENT');
+});
+
+test('listDirectory ENOTDIR for file path', () => {
+  const f = path.join(tempDir(), 'f.txt');
+  fs.writeFileSync(f, 'hi');
+  const out = listDirectory(f);
+  assert.equal(out.error, 'ENOTDIR');
+});

package/test/role-guess.test.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { guessRole, isKnownRoleGuess } = require('../shared/dist/role-guess');
+const { ROLES, isValidRole } = require('../shared/dist/schema');
+
+/** @type {Array<{ name: string, entry: object, roleGuess: string, reason?: boolean }>} */
+const FIXTURES = [
+  { name: 'thumb segment', entry: { path: 'assets/thumbs/preview.png', width: 800, height: 600 }, roleGuess: 'thumbnail', reason: true },
+  { name: 'thumbnail in name', entry: { path: 'img/thumbnail.jpg', width: 400, height: 300 }, roleGuess: 'thumbnail', reason: true },
+  { name: 'hero path', entry: { path: 'public/hero-banner.jpg', width: 400, height: 300 }, roleGuess: 'hero', reason: true },
+  { name: 'banner path', entry: { path: 'images/banner.png', width: 200, height: 200 }, roleGuess: 'hero', reason: true },
+  { name: '150x suffix', entry: { path: 'icons/close-150x.png', width: 450, height: 450 }, roleGuess: 'thumbnail', reason: true },
+  { name: '150x150 token', entry: { path: 'sprites/150x150.png', width: 450, height: 450 }, roleGuess: 'thumbnail', reason: true },
+  { name: 'wide hero dimensions', entry: { path: 'assets/photo.jpg', width: 1600, height: 900 }, roleGuess: 'hero', reason: true },
+  { name: 'content path', entry: { path: 'docs/article-screenshot.png', width: 900, height: 600 }, roleGuess: 'content', reason: true },
+  { name: 'ambiguous generic', entry: { path: 'assets/photo.jpg', width: 800, height: 600 }, roleGuess: 'unknown' },
+  { name: 'ambiguous no dimensions', entry: { path: 'misc/file.png' }, roleGuess: 'unknown' },
+  { name: 'small dimensions only', entry: { path: 'ui/icon.png', width: 64, height: 64 }, roleGuess: 'thumbnail', reason: true },
+  { name: 'large 800x600 in path not thumb', entry: { path: 'export/slide-800x600.png', width: 800, height: 600 }, roleGuess: 'unknown' }
+];
+
+for (const fixture of FIXTURES) {
+  test(`guessRole: ${fixture.name}`, () => {
+    const result = guessRole(fixture.entry);
+    assert.equal(result.roleGuess, fixture.roleGuess);
+    assert.ok(isKnownRoleGuess(result.roleGuess));
+    if (fixture.reason) {
+      assert.ok(typeof result.roleGuessReason === 'string' && result.roleGuessReason.length > 0);
+    } else if (fixture.roleGuess === 'unknown') {
+      assert.equal(result.roleGuessReason, undefined);
+    }
+  });
+}
+
+test('guessRole returns only valid roles', () => {
+  for (const entry of FIXTURES.map(f => f.entry)) {
+    const { roleGuess } = guessRole(entry);
+    assert.ok(ROLES.includes(roleGuess));
+    assert.ok(isValidRole(roleGuess));
+  }
+});
+
+test('schema isValidRole rejects invalid values', () => {
+  assert.ok(isValidRole('hero'));
+  assert.ok(!isValidRole('banner'));
+  assert.ok(!isValidRole(null));
+});

package/test/scan.test.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  findImagesInFolders,
+  sortByCompressionScore,
+  enrichImageEntry
+} = require('../server/dist/scan');
+const { ROLES } = require('../shared/dist/schema');
+
+const MINI_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64'
+);
+
+function tempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'repoimage-test-'));
+}
+
+test('findImagesInFolders finds a PNG and reports dimensions', () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, 'pixel.png'), MINI_PNG);
+
+  const { images, issues } = findImagesInFolders([dir], { verbose: false });
+
+  assert.equal(issues.length, 0);
+  assert.equal(images.length, 1);
+  assert.equal(images[0].path, 'pixel.png');
+  assert.equal(images[0].width, 1);
+  assert.equal(images[0].height, 1);
+  assert.ok(typeof images[0].size === 'number' && images[0].size > 0);
+  assert.ok(images[0].uncompressedSize != null);
+  assert.ok(Number.isFinite(parseFloat(images[0].compressionRatio)));
+  assert.ok(ROLES.includes(images[0].roleGuess));
+  assert.equal(images[0].role, null);
+});
+
+test('findImagesInFolders walks nested directories', () => {
+  const dir = tempDir();
+  const nested = path.join(dir, 'a', 'b');
+  fs.mkdirSync(nested, { recursive: true });
+  fs.writeFileSync(path.join(nested, 'deep.png'), MINI_PNG);
+
+  const { images, issues } = findImagesInFolders([dir], { verbose: false });
+
+  assert.equal(issues.length, 0);
+  assert.equal(images.length, 1);
+  assert.equal(images[0].path, 'a/b/deep.png');
+});
+
+test('findImagesInFolders records missing folders in issues', () => {
+  const bad = path.join(os.tmpdir(), 'repoimage-nonexistent-' + Date.now());
+  const { images, issues } = findImagesInFolders([bad], { verbose: false });
+
+  assert.equal(images.length, 0);
+  assert.equal(issues.length, 1);
+  assert.equal(issues[0].code, 'MISSING_FOLDER');
+});
+
+test('enrichImageEntry builds row from path and dimensions', () => {
+  const row = enrichImageEntry({
+    path: 'assets/x.png',
+    size: 100,
+    width: 10,
+    height: 10
+  });
+  assert.ok(row);
+  assert.equal(row.path, 'assets/x.png');
+  assert.equal(row.width, 10);
+  assert.ok(row.uncompressedSize != null);
+  assert.ok(row.compressionRatio != null);
+  assert.equal(row.role, null);
+  assert.ok(ROLES.includes(row.roleGuess));
+});
+
+test('enrichImageEntry adds roleGuess for hero path', () => {
+  const row = enrichImageEntry({
+    path: 'assets/hero.jpg',
+    size: 5000,
+    width: 400,
+    height: 300
+  });
+  assert.ok(row);
+  assert.equal(row.roleGuess, 'hero');
+  assert.ok(row.roleGuessReason);
+  assert.equal(row.role, null);
+});
+
+test('enrichImageEntry omits roleGuessReason when unknown', () => {
+  const row = enrichImageEntry({
+    path: 'misc/photo.png',
+    size: 1000,
+    width: 800,
+    height: 600
+  });
+  assert.ok(row);
+  assert.equal(row.roleGuess, 'unknown');
+  assert.equal(row.roleGuessReason, undefined);
+});
+
+test('enrichImageEntry rejects path traversal', () => {
+  assert.equal(enrichImageEntry({ path: '../x.png', size: 1, width: 1, height: 1 }), null);
+});
+
+test('sortByCompressionScore orders by score descending', () => {
+  const a = { path: 'a.png', compressionRatio: '1.0', size: 1 };
+  const b = { path: 'b.png', compressionRatio: '5.0', size: 1 };
+  const c = { path: 'c.png', compressionRatio: null, size: 1 };
+  const sorted = sortByCompressionScore([a, b, c]);
+  assert.deepEqual(sorted.map(x => x.path), ['b.png', 'a.png', 'c.png']);
+});
+
+test('findImagesInFolders excludes common folders when enabled', () => {
+  const dir = tempDir();
+  const nodeModulesDir = path.join(dir, 'node_modules');
+  const assetsDir = path.join(dir, 'assets');
+  fs.mkdirSync(nodeModulesDir, { recursive: true });
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  fs.writeFileSync(path.join(nodeModulesDir, 'img.png'), MINI_PNG);
+  fs.writeFileSync(path.join(assetsDir, 'logo.png'), MINI_PNG);
+
+  const { images: withoutExclude } = findImagesInFolders([dir], { verbose: false, excludeCommon: false });
+  const { images: withExclude } = findImagesInFolders([dir], { verbose: false, excludeCommon: true });
+
+  assert.equal(withoutExclude.length, 2);
+  assert.equal(withExclude.length, 1);
+  assert.equal(withExclude[0].path, 'assets/logo.png');
+});
+
+test('findImagesInFolders excludes multiple common folders', () => {
+  const dir = tempDir();
+  fs.mkdirSync(path.join(dir, 'node_modules'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'dist'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+
+  fs.writeFileSync(path.join(dir, 'node_modules', 'a.png'), MINI_PNG);
+  fs.writeFileSync(path.join(dir, 'dist', 'b.png'), MINI_PNG);
+  fs.writeFileSync(path.join(dir, 'src', 'c.png'), MINI_PNG);
+
+  const { images } = findImagesInFolders([dir], { verbose: false, excludeCommon: true });
+
+  assert.equal(images.length, 1);
+  assert.equal(images[0].path, 'src/c.png');
+});