placeholder-photo-migrate 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 1.0.0 - 2026-09-16
+
+- Add local, dependency-free migration CLI with dry-run as the default.
+- Add verified providers for `via.placeholder.com`, `placehold.it`, and conservative legacy `placeholder.com` URLs.
+- Add `--write`, `--check`, `--provider`, and local JSON `--report` support.
+- Add manual-review classification for ambiguous or unsupported URLs.
+- Add source-format filtering, default directory exclusions, `.gitignore` support, binary detection, and symlink containment.
+- Add automated tests and GitHub Actions coverage for supported Node.js releases.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jansma VIP / Placeholder.photo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# Placeholder.photo Migration CLI
+
+The official, local migration tool for moving verified legacy placeholder image URLs to [Placeholder.photo](https://placeholder.photo).
+
+Placeholder.photo is a free URL-first image toolkit operated by Jansma VIP. This CLI finds common dead or legacy placeholder URLs, classifies them against Placeholder.photo's versioned compatibility rules, and can safely update the compatible cases.
+
+## Quick start
+
+Preview a migration without changing files:
+
+```sh
+npx placeholder-photo-migrate .
+```
+
+Apply only verified, safe migrations:
+
+```sh
+npx placeholder-photo-migrate . --write
+```
+
+Fail CI when legacy URLs remain:
+
+```sh
+npx placeholder-photo-migrate . --check
+```
+
+Dry-run is always the default. Source files are changed only when `--write` is explicitly present.
+
+## What it migrates
+
+The CLI has a separate, centrally tested provider for each legacy service:
+
+| Provider | Example | Automatic behavior |
+|---|---|---|
+| `via.placeholder.com` | `https://via.placeholder.com/600/92c952` | Verified classic paths are migrated |
+| `placehold.it` | `http://placehold.it/300x200` | Verified classic paths are migrated |
+| legacy `placeholder.com` | `https://placeholder.com/300x200` | Only an exact, provable image path is migrated |
+
+Example:
+
+```text
+https://via.placeholder.com/300x200/000000/ffffff?text=Hello+World
+https://placeholder.photo/300x200/000000/ffffff?text=Hello+World
+```
+
+Safe migrations retain the dimensions, background and foreground colours, custom text, URL encoding, trailing slash, query string, and verified raster extension exactly. HTTP, HTTPS, and protocol-relative source URLs all become the canonical HTTPS Placeholder.photo URL.
+
+The automatic compatibility subset is deliberately narrow:
+
+- square or `width×height` dimensions within live rendering limits;
+- optional 3- or 6-digit hexadecimal background and text colours;
+- optional `.png`, `.jpg`, `.jpeg`, `.gif`, or `.webp` suffix;
+- one optional, correctly encoded `text` query parameter;
+- the historical `/img/` path alias accepted by Placeholder.photo.
+
+Anything ambiguous is left unchanged and reported as **manual review required**. In particular, the CLI never performs a blind replacement of every `placeholder.com` reference.
+
+See the official [compatibility guide](https://placeholder.photo/compatibility) and [migration CLI documentation](https://placeholder.photo/docs/migration-cli).
+
+## Options
+
+```text
+--write                 Apply safe migrations (default is dry-run)
+--check                 CI check; never writes source files
+--provider <provider>   Limit the scan to one or more providers
+--report <file>         Write a local JSON report inside the project
+-h, --help              Show help
+-v, --version           Show version
+```
+
+Provider names are `via-placeholder`, `placehold-it`, and `placeholder-com`. `--provider` can be repeated or given a comma-separated list.
+
+```sh
+npx placeholder-photo-migrate . --provider via-placeholder
+npx placeholder-photo-migrate . --provider via-placeholder,placehold-it --report migration-report.json
+```
+
+Reports contain file locations and URL-level decisions. They are written locally, are excluded from their own scan, and are never transmitted.
+
+## Supported source files
+
+The scanner handles:
+
+```text
+.html .htm .css .scss .sass .less
+.js .jsx .mjs .cjs .ts .tsx
+.vue .svelte .php .md .mdx
+.json .jsonc .yaml .yml .xml .txt
+```
+
+It skips binary and invalid UTF-8 files, files larger than 10 MiB, symlinks, unsupported extensions, and these directories by default:
+
+```text
+.git node_modules vendor dist build coverage .cache tmp temp
+```
+
+The root `.gitignore` is respected for common ignore patterns. Symlinks are not followed, report files must remain inside the selected project, and writes use same-directory atomic replacement.
+
+## CI
+
+```yaml
+- name: Check legacy placeholder URLs
+  run: npx --yes placeholder-photo-migrate . --check
+```
+
+Exit codes:
+
+| Code | Meaning |
+|---:|---|
+| `0` | No selected legacy URLs were found |
+| `1` | Legacy URLs were found, including manual-review findings |
+| `2` | Usage, filesystem, or runtime error |
+
+A successful `--write` run still returns `1` because legacy URLs were found during that run. Run the command again: a fully migrated project returns `0` unless unresolved manual-review URLs remain.
+
+## Privacy and security
+
+**Your source code is never uploaded to Placeholder.photo.**
+
+The CLI runs entirely on the developer's computer. It contains no telemetry, analytics, source upload, project identifiers, or migration-time network API. After npm installation, normal scanning and migration work offline using local, versioned compatibility rules.
+
+Filenames and contents are treated as untrusted input. The tool does not execute project files or shell commands, follows no symlinks, bounds file size and URL patterns, and refuses writes outside the selected project.
+
+## Requirements and limitations
+
+- Node.js 22 or newer.
+- The tool migrates textual source files, not generated binaries or databases.
+- Only syntax covered by Placeholder.photo's verified compatibility implementation is changed automatically.
+- Font metrics, antialiasing, watermarking, and static GIF behavior may differ from discontinued services; see the [compatibility guide](https://placeholder.photo/compatibility).
+- Unknown parameters, malformed URLs, hostname variants, explicit ports, unsupported formats, and out-of-limit dimensions require manual review.
+
+## Support
+
+- [Placeholder.photo](https://placeholder.photo)
+- [Compatibility documentation](https://placeholder.photo/compatibility)
+- [GitHub Issues](https://github.com/Jansma-VIP/placeholder-photo-migrate/issues)
+
+## Ownership and license
+
+Built and maintained by Jansma VIP / Placeholder.photo. Released under the [MIT License](LICENSE).

package/bin/placeholder-photo-migrate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "placeholder-photo-migrate",
+  "version": "1.0.0",
+  "description": "Safely migrate legacy placeholder image URLs to Placeholder.photo.",
+  "type": "module",
+  "bin": {
+    "placeholder-photo-migrate": "bin/placeholder-photo-migrate.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "lint": "node --check bin/placeholder-photo-migrate.js && node --check src/*.js && node --check src/providers/*.js && node --check test/*.test.js",
+    "prepack": "npm run lint && npm test"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jansma-VIP/placeholder-photo-migrate.git"
+  },
+  "homepage": "https://placeholder.photo",
+  "bugs": {
+    "url": "https://github.com/Jansma-VIP/placeholder-photo-migrate/issues"
+  },
+  "author": {
+    "name": "Jansma VIP / Placeholder.photo",
+    "url": "https://placeholder.photo"
+  },
+  "license": "MIT",
+  "keywords": [
+    "placeholder",
+    "migration",
+    "codemod",
+    "via.placeholder.com",
+    "placehold.it",
+    "placeholder.photo"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,173 @@
+import path from 'node:path';
+import {
+  collectSourceFiles,
+  isGeneratedReport,
+  readTextFile,
+  resolveReportPath,
+  resolveScanTarget,
+  safeWriteTextFile,
+  writeReportFile,
+} from './files.js';
+import { parseOptions } from './options.js';
+import { normalizeProviderIds } from './providers/index.js';
+import { createReport } from './report.js';
+import { applySafeFindings, scanSource } from './scanner.js';
+import { VERSION } from './version.js';
+
+const HELP = `placeholder-photo-migrate ${VERSION}
+
+Safely migrate verified legacy placeholder image URLs to https://placeholder.photo.
+
+Usage:
+  placeholder-photo-migrate [path] [options]
+
+Examples:
+  npx placeholder-photo-migrate .
+  npx placeholder-photo-migrate . --write
+  npx placeholder-photo-migrate . --check
+
+Options:
+  --write                 Apply safe migrations (default is dry-run)
+  --check                 CI check; never writes source files
+  --provider <provider>   Limit to via-placeholder, placehold-it, or placeholder-com
+  --report <file>         Write a local JSON report inside the selected project
+  -h, --help              Show help
+  -v, --version           Show version
+
+Exit codes:
+  0  No legacy URLs found
+  1  Legacy URLs found (including manual-review findings)
+  2  Runtime or usage error
+`;
+
+const MAX_FINDINGS = 100_000;
+const MAX_PENDING_WRITE_BYTES = 128 * 1024 * 1024;
+
+function relativeFile(root, file) {
+  return path.relative(root, file).replaceAll(path.sep, '/') || path.basename(file);
+}
+
+function writeLine(stream, value = '') {
+  stream.write(`${value}\n`);
+}
+
+function safeDisplay(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, (character) => {
+    return `\\u${character.codePointAt(0).toString(16).padStart(4, '0')}`;
+  });
+}
+
+export async function runCli(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+
+  try {
+    const options = parseOptions(argv);
+    if (options.help) {
+      stdout.write(HELP);
+      return 0;
+    }
+    if (options.version) {
+      writeLine(stdout, VERSION);
+      return 0;
+    }
+
+    const selectedProviderIds = normalizeProviderIds(options.providers);
+    const scanTarget = await resolveScanTarget(options.target);
+    const reportPath = options.report ? await resolveReportPath(options.report, scanTarget.root) : null;
+    const excludedPaths = new Set(reportPath ? [reportPath] : []);
+    const collected = await collectSourceFiles(scanTarget, excludedPaths);
+    const findings = [];
+    const pendingWrites = [];
+    let pendingWriteBytes = 0;
+    let filesScanned = 0;
+
+    for (const file of collected.files) {
+      const loaded = await readTextFile(file);
+      if (loaded.kind === 'binary') {
+        collected.skipped.binary += 1;
+        continue;
+      }
+      if (loaded.kind === 'large') {
+        collected.skipped.large += 1;
+        continue;
+      }
+      if (isGeneratedReport(loaded.content)) {
+        collected.skipped.report += 1;
+        continue;
+      }
+
+      filesScanned += 1;
+      const fileFindings = scanSource(loaded.content, selectedProviderIds).map((finding) => ({
+        ...finding,
+        file: relativeFile(scanTarget.root, file),
+      }));
+      findings.push(...fileFindings);
+      if (findings.length > MAX_FINDINGS) {
+        throw new Error(`Scan exceeded the safety limit of ${MAX_FINDINGS} findings.`);
+      }
+
+      if (options.write && fileFindings.some((finding) => finding.status === 'safe')) {
+        const migrated = `${loaded.hasBom ? '\uFEFF' : ''}${applySafeFindings(loaded.content, fileFindings)}`;
+        pendingWriteBytes += Buffer.byteLength(migrated, 'utf8');
+        if (pendingWriteBytes > MAX_PENDING_WRITE_BYTES) {
+          throw new Error('Pending migrations exceed the 128 MiB write safety limit. Migrate a smaller project scope.');
+        }
+        pendingWrites.push({
+          file,
+          content: migrated,
+          mode: loaded.mode,
+        });
+      }
+    }
+
+    for (const finding of findings) {
+      const location = `${safeDisplay(finding.file)}:${finding.line}:${finding.column}`;
+      if (finding.status === 'safe') {
+        writeLine(stdout, `SAFE   ${location}  ${safeDisplay(finding.original)}`);
+        writeLine(stdout, `       -> ${safeDisplay(finding.replacement)}`);
+      } else {
+        writeLine(stdout, `MANUAL ${location}  ${safeDisplay(finding.original)}`);
+        writeLine(stdout, `       ${safeDisplay(finding.reason)}`);
+      }
+    }
+
+    for (const pending of pendingWrites) {
+      await safeWriteTextFile(pending.file, pending.content, scanTarget.root, pending.mode);
+    }
+
+    const safeCount = findings.filter((finding) => finding.status === 'safe').length;
+    const manualCount = findings.length - safeCount;
+    const mode = options.write ? 'write' : options.check ? 'check' : 'dry-run';
+
+    if (reportPath) {
+      const report = createReport({
+        mode,
+        root: scanTarget.root,
+        target: scanTarget.target,
+        filesScanned,
+        filesChanged: pendingWrites.length,
+        findings,
+        skipped: collected.skipped,
+      });
+      await writeReportFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, scanTarget.root);
+      writeLine(stdout, `Report: ${relativeFile(scanTarget.root, reportPath)}`);
+    }
+
+    if (findings.length === 0) {
+      writeLine(stdout, `No legacy placeholder URLs found in ${filesScanned} file${filesScanned === 1 ? '' : 's'}.`);
+      return 0;
+    }
+
+    writeLine(stdout);
+    writeLine(stdout, `${findings.length} legacy URL${findings.length === 1 ? '' : 's'} found: ${safeCount} safe, ${manualCount} manual review.`);
+    if (options.write) writeLine(stdout, `${pendingWrites.length} file${pendingWrites.length === 1 ? '' : 's'} updated. Run again to verify the migrated URLs are gone.`);
+    else if (options.check) writeLine(stdout, 'CI check failed because legacy URLs remain.');
+    else writeLine(stdout, 'Dry run only. Re-run with --write to apply safe migrations.');
+    writeLine(stdout, 'Your source code is never uploaded to Placeholder.photo. No telemetry is collected.');
+    return 1;
+  } catch (error) {
+    writeLine(stderr, `Error: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}

package/src/files.js

@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createGitIgnoreMatcher } from './gitignore.js';
+
+const SOURCE_EXTENSIONS = new Set([
+  '.html', '.htm', '.css', '.scss', '.sass', '.less', '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+  '.vue', '.svelte', '.php', '.md', '.mdx', '.json', '.jsonc', '.yaml', '.yml', '.xml', '.txt',
+]);
+
+const EXCLUDED_DIRECTORIES = new Set([
+  '.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.cache', 'tmp', 'temp',
+]);
+
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+export const MAX_SOURCE_FILES = 100_000;
+
+export function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+export async function resolveScanTarget(inputPath) {
+  const absolute = path.resolve(inputPath);
+  const linkStatus = await lstat(absolute);
+  if (linkStatus.isSymbolicLink()) throw new Error('The selected target cannot be a symbolic link.');
+  if (!linkStatus.isDirectory() && !linkStatus.isFile()) throw new Error('The selected target must be a file or directory.');
+
+  const resolved = await realpath(absolute);
+  return {
+    target: resolved,
+    root: linkStatus.isDirectory() ? resolved : await realpath(path.dirname(resolved)),
+    isFile: linkStatus.isFile(),
+  };
+}
+
+async function rootIgnoreMatcher(root, isFile) {
+  if (isFile) return () => false;
+  try {
+    const contents = await readFile(path.join(root, '.gitignore'), 'utf8');
+    return createGitIgnoreMatcher(contents);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return () => false;
+    throw error;
+  }
+}
+
+export async function collectSourceFiles(scanTarget, excludedAbsolutePaths = new Set()) {
+  const ignored = await rootIgnoreMatcher(scanTarget.root, scanTarget.isFile);
+  const files = [];
+  const skipped = { binary: 0, large: 0, symlink: 0, ignored: 0, unsupported: 0, report: 0 };
+
+  const visit = async (absolute) => {
+    const linkStatus = await lstat(absolute);
+    if (linkStatus.isSymbolicLink()) {
+      skipped.symlink += 1;
+      return;
+    }
+
+    const resolved = await realpath(absolute);
+    if (!isWithin(scanTarget.root, resolved)) {
+      skipped.symlink += 1;
+      return;
+    }
+    if (excludedAbsolutePaths.has(resolved)) {
+      skipped.report += 1;
+      return;
+    }
+
+    const relative = path.relative(scanTarget.root, resolved).replaceAll(path.sep, '/');
+    if (linkStatus.isDirectory()) {
+      if (resolved !== scanTarget.root && (EXCLUDED_DIRECTORIES.has(path.basename(resolved).toLowerCase()) || ignored(relative))) {
+        skipped.ignored += 1;
+        return;
+      }
+      const entries = await readdir(resolved, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) await visit(path.join(resolved, entry.name));
+      return;
+    }
+
+    if (!linkStatus.isFile()) return;
+    if (ignored(relative)) {
+      skipped.ignored += 1;
+      return;
+    }
+    if (!SOURCE_EXTENSIONS.has(path.extname(resolved).toLowerCase())) {
+      skipped.unsupported += 1;
+      return;
+    }
+    if (linkStatus.size > MAX_FILE_BYTES) {
+      skipped.large += 1;
+      return;
+    }
+    files.push(resolved);
+    if (files.length > MAX_SOURCE_FILES) {
+      throw new Error(`Project contains more than the ${MAX_SOURCE_FILES} supported source files.`);
+    }
+  };
+
+  await visit(scanTarget.target);
+  return { files, skipped };
+}
+
+export async function readTextFile(absolute) {
+  const fileStatus = await stat(absolute);
+  if (fileStatus.size > MAX_FILE_BYTES) return { kind: 'large' };
+  const buffer = await readFile(absolute);
+  if (buffer.includes(0)) return { kind: 'binary' };
+
+  try {
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    const hasBom = buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf;
+    return {
+      kind: 'text',
+      content: decoder.decode(hasBom ? buffer.subarray(3) : buffer),
+      hasBom,
+      mode: fileStatus.mode,
+    };
+  } catch {
+    return { kind: 'binary' };
+  }
+}
+
+export function isGeneratedReport(content) {
+  const header = content.slice(0, 4096);
+  return /"tool"\s*:\s*"placeholder-photo-migrate"/.test(header)
+    && /"reportVersion"\s*:\s*1/.test(header);
+}
+
+export async function safeWriteTextFile(absolute, content, root, mode) {
+  const parent = await realpath(path.dirname(absolute));
+  const current = await lstat(absolute);
+  if (current.isSymbolicLink() || !current.isFile()) throw new Error(`Refusing to overwrite unsafe path: ${absolute}`);
+  if (!isWithin(root, parent) || !isWithin(root, await realpath(absolute))) {
+    throw new Error(`Refusing to write outside the selected project: ${absolute}`);
+  }
+
+  const temporary = path.join(parent, `.placeholder-photo-migrate-${process.pid}-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', mode & 0o777);
+    await handle.writeFile(content, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, absolute);
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+export async function resolveReportPath(reportPath, root) {
+  const absolute = path.resolve(reportPath);
+  const parent = path.dirname(absolute);
+  await mkdir(parent, { recursive: false }).catch((error) => {
+    if (error?.code !== 'EEXIST') throw error;
+  });
+  const resolvedParent = await realpath(parent);
+  if (!isWithin(root, resolvedParent)) throw new Error('The report path must stay inside the selected project.');
+  try {
+    const status = await lstat(absolute);
+    if (status.isSymbolicLink() || !status.isFile()) throw new Error('The report path is not a safe regular file.');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  return path.join(resolvedParent, path.basename(absolute));
+}
+
+export async function writeReportFile(absolute, contents, root) {
+  const parent = await realpath(path.dirname(absolute));
+  if (!isWithin(root, parent)) throw new Error('The report path must stay inside the selected project.');
+  try {
+    const current = await lstat(absolute);
+    if (current.isSymbolicLink() || !current.isFile()) throw new Error('Refusing to overwrite an unsafe report path.');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+
+  const temporary = path.join(parent, `.placeholder-photo-migrate-report-${process.pid}-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', 0o600);
+    await handle.writeFile(contents, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, absolute);
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}

package/src/gitignore.js

@@ -0,0 +1,62 @@
+function escapeRegex(character) {
+  return /[|\\{}()[\]^$+?.]/.test(character) ? `\\${character}` : character;
+}
+
+function globSource(pattern) {
+  let source = '';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === '*') {
+      if (pattern[index + 1] === '*') {
+        index += 1;
+        if (pattern[index + 1] === '/') {
+          index += 1;
+          source += '(?:.*/)?';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+    } else if (character === '?') {
+      source += '[^/]';
+    } else {
+      source += escapeRegex(character);
+    }
+  }
+  return source;
+}
+
+function compileLine(rawLine) {
+  let line = rawLine.trim();
+  if (!line || line.startsWith('#')) return null;
+
+  let negated = false;
+  if (line.startsWith('!')) {
+    negated = true;
+    line = line.slice(1);
+  }
+  if (!line) return null;
+
+  const anchored = line.startsWith('/');
+  if (anchored) line = line.slice(1);
+  const directoryOnly = line.endsWith('/');
+  if (directoryOnly) line = line.slice(0, -1);
+  const containsSlash = line.includes('/');
+  const prefix = anchored || containsSlash ? '^' : '(?:^|.*/)';
+  const suffix = directoryOnly ? '(?:/.*)?$' : '(?:$|/.*$)';
+
+  return { negated, regex: new RegExp(`${prefix}${globSource(line)}${suffix}`) };
+}
+
+export function createGitIgnoreMatcher(contents = '') {
+  const rules = contents.split(/\r?\n/).map(compileLine).filter(Boolean);
+  return (relativePath) => {
+    const normalized = relativePath.replaceAll('\\', '/').replace(/^\.\//, '');
+    let ignored = false;
+    for (const rule of rules) {
+      if (rule.regex.test(normalized)) ignored = !rule.negated;
+    }
+    return ignored;
+  };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { runCli } from './cli.js';
+export { providers } from './providers/index.js';
+export { applySafeFindings, scanSource } from './scanner.js';
+export { VERSION } from './version.js';

package/src/options.js

@@ -0,0 +1,47 @@
+export function parseOptions(argv) {
+  const options = {
+    write: false,
+    check: false,
+    help: false,
+    version: false,
+    report: null,
+    providers: [],
+    target: '.',
+  };
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      positional.push(...argv.slice(index + 1));
+      break;
+    }
+    if (argument === '--write') options.write = true;
+    else if (argument === '--check') options.check = true;
+    else if (argument === '--help' || argument === '-h') options.help = true;
+    else if (argument === '--version' || argument === '-v') options.version = true;
+    else if (argument === '--provider') {
+      const value = argv[++index];
+      if (!value || value.startsWith('--')) throw new Error('--provider requires a provider name.');
+      options.providers.push(value);
+    } else if (argument.startsWith('--provider=')) {
+      options.providers.push(argument.slice('--provider='.length));
+    } else if (argument === '--report') {
+      const value = argv[++index];
+      if (!value || value.startsWith('--')) throw new Error('--report requires a file path.');
+      options.report = value;
+    } else if (argument.startsWith('--report=')) {
+      options.report = argument.slice('--report='.length);
+    } else if (argument.startsWith('-')) {
+      throw new Error(`Unknown option: ${argument}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+
+  if (positional.length > 1) throw new Error('Provide exactly one project path.');
+  if (positional.length === 1) options.target = positional[0];
+  if (options.write && options.check) throw new Error('--write and --check cannot be used together.');
+  if (options.report === '') throw new Error('--report requires a file path.');
+  return options;
+}

package/src/providers/common.js

@@ -0,0 +1,126 @@
+const SIZE_PATTERN = /^(\d{1,4})(?:x(\d{1,4}))?(?:\.(svg|png|jpe?g|gif|webp|avif))?$/i;
+const COLOUR_PATTERN = /^([0-9a-f]{3}|[0-9a-f]{6})(?:\.(svg|png|jpe?g|gif|webp|avif))?$/i;
+
+const VERIFIED_FORMATS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp']);
+const MAX_DIMENSION = 4096;
+const MAX_PIXELS = 8_000_000;
+const MAX_TEXT_BYTES = 720;
+const MAX_TEXT_CHARACTERS = 180;
+
+function manual(reason) {
+  return {
+    status: 'manual',
+    confidence: 'review',
+    reason,
+    replacement: null,
+  };
+}
+
+function safelyDecode(value) {
+  try {
+    return decodeURIComponent(value.replace(/\+/g, ' '));
+  } catch {
+    return null;
+  }
+}
+
+function validateQuery(rawQuery) {
+  if (rawQuery === '' || rawQuery === '?') {
+    return null;
+  }
+
+  const parts = rawQuery.slice(1).split('&');
+  if (parts.length !== 1) {
+    return 'Only the verified text query parameter can be migrated automatically.';
+  }
+
+  const separator = parts[0].indexOf('=');
+  const rawKey = separator === -1 ? parts[0] : parts[0].slice(0, separator);
+  const rawValue = separator === -1 ? '' : parts[0].slice(separator + 1);
+  const key = safelyDecode(rawKey);
+  const value = safelyDecode(rawValue);
+
+  if (key !== 'text') {
+    return 'The query string is outside the verified legacy compatibility subset.';
+  }
+  if (value === null) {
+    return 'The text query contains malformed percent-encoding.';
+  }
+  if (value.includes('\0')) {
+    return 'The text query contains a null byte.';
+  }
+  if ([...value].length > MAX_TEXT_CHARACTERS || Buffer.byteLength(value, 'utf8') > MAX_TEXT_BYTES) {
+    return 'The text query exceeds Placeholder.photo compatibility limits.';
+  }
+  return null;
+}
+
+function parsePath(rawPath) {
+  if (!rawPath || rawPath === '/') {
+    return manual('No legacy placeholder image dimensions were found in the path.');
+  }
+  if (rawPath.includes('%') || rawPath.includes('\\') || rawPath.includes('//')) {
+    return manual('Encoded or non-canonical path separators require manual review.');
+  }
+
+  const trimmed = rawPath.replace(/^\//, '').replace(/\/$/, '');
+  const segments = trimmed.split('/');
+  if (segments[0]?.toLowerCase() === 'img') {
+    segments.shift();
+  }
+  if (segments.length < 1 || segments.length > 3) {
+    return manual('The path is not a verified classic placeholder pattern.');
+  }
+
+  const size = SIZE_PATTERN.exec(segments[0]);
+  if (!size) {
+    return manual('The dimension segment is malformed or unsupported.');
+  }
+
+  const width = Number.parseInt(size[1], 10);
+  const height = size[2] ? Number.parseInt(size[2], 10) : width;
+  if (width < 1 || height < 1 || width > MAX_DIMENSION || height > MAX_DIMENSION || width * height > MAX_PIXELS) {
+    return manual('The dimensions exceed Placeholder.photo compatibility limits.');
+  }
+
+  const extensions = [];
+  if (size[3]) extensions.push(size[3].toLowerCase());
+  for (const colourSegment of segments.slice(1)) {
+    const colour = COLOUR_PATTERN.exec(colourSegment);
+    if (!colour) {
+      return manual('A colour segment is outside the verified 3- or 6-digit hexadecimal syntax.');
+    }
+    if (colour[2]) extensions.push(colour[2].toLowerCase());
+  }
+
+  if (extensions.length > 1) {
+    return manual('Multiple format suffixes are ambiguous and require manual review.');
+  }
+  if (extensions.length === 1 && !VERIFIED_FORMATS.has(extensions[0])) {
+    return manual('This format is supported elsewhere by Placeholder.photo but is not in the verified legacy migration matrix.');
+  }
+
+  return null;
+}
+
+export function analyseClassicCandidate(candidate, { exactHost = true } = {}) {
+  if (!exactHost) {
+    return manual('This hostname variant is not covered by the verified compatibility rules.');
+  }
+  if (candidate.port) {
+    return manual('URLs with an explicit port require manual review.');
+  }
+
+  const pathProblem = parsePath(candidate.path);
+  if (pathProblem) return pathProblem;
+
+  const queryProblem = validateQuery(candidate.query);
+  if (queryProblem) return manual(queryProblem);
+
+  return {
+    status: 'safe',
+    confidence: 'verified',
+    reason: null,
+    replacement: `https://placeholder.photo${candidate.suffix}`,
+  };
+}

package/src/providers/index.js

@@ -0,0 +1,32 @@
+import { placeholdItProvider } from './placehold-it.js';
+import { placeholderComProvider } from './placeholder-com.js';
+import { viaPlaceholderProvider } from './via-placeholder.js';
+
+export const providers = [viaPlaceholderProvider, placeholdItProvider, placeholderComProvider];
+
+export const providerAliases = new Map([
+  ['via-placeholder', 'via-placeholder'],
+  ['via.placeholder.com', 'via-placeholder'],
+  ['placehold-it', 'placehold-it'],
+  ['placehold.it', 'placehold-it'],
+  ['placeholder-com', 'placeholder-com'],
+  ['placeholder.com', 'placeholder-com'],
+]);
+
+export function normalizeProviderIds(values) {
+  if (values.length === 0) return new Set(providers.map((provider) => provider.id));
+
+  const selected = new Set();
+  for (const value of values.flatMap((item) => item.split(','))) {
+    const normalized = providerAliases.get(value.trim().toLowerCase());
+    if (!normalized) {
+      throw new Error(`Unknown provider: ${value}. Use via-placeholder, placehold-it, or placeholder-com.`);
+    }
+    selected.add(normalized);
+  }
+  return selected;
+}
+
+export function providerForHostname(hostname) {
+  return providers.find((provider) => provider.hosts.has(hostname.toLowerCase())) ?? null;
+}

package/src/providers/placehold-it.js

@@ -0,0 +1,10 @@
+import { analyseClassicCandidate } from './common.js';
+
+export const placeholdItProvider = {
+  id: 'placehold-it',
+  label: 'placehold.it',
+  hosts: new Set(['placehold.it', 'www.placehold.it']),
+  analyse(candidate) {
+    return analyseClassicCandidate(candidate, { exactHost: candidate.hostname === 'placehold.it' });
+  },
+};

package/src/providers/placeholder-com.js

@@ -0,0 +1,10 @@
+import { analyseClassicCandidate } from './common.js';
+
+export const placeholderComProvider = {
+  id: 'placeholder-com',
+  label: 'legacy placeholder.com',
+  hosts: new Set(['placeholder.com', 'www.placeholder.com']),
+  analyse(candidate) {
+    return analyseClassicCandidate(candidate, { exactHost: candidate.hostname === 'placeholder.com' });
+  },
+};

package/src/providers/via-placeholder.js

@@ -0,0 +1,10 @@
+import { analyseClassicCandidate } from './common.js';
+
+export const viaPlaceholderProvider = {
+  id: 'via-placeholder',
+  label: 'via.placeholder.com',
+  hosts: new Set(['via.placeholder.com']),
+  analyse(candidate) {
+    return analyseClassicCandidate(candidate);
+  },
+};

package/src/report.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { VERSION } from './version.js';
+
+export function createReport({ mode, root, target, filesScanned, filesChanged, findings, skipped }) {
+  const safe = findings.filter((finding) => finding.status === 'safe').length;
+  const manual = findings.length - safe;
+  return {
+    tool: 'placeholder-photo-migrate',
+    reportVersion: 1,
+    version: VERSION,
+    generatedAt: new Date().toISOString(),
+    mode,
+    target: path.relative(root, target).replaceAll(path.sep, '/') || '.',
+    privacy: 'Local-only scan. No source code or telemetry was transmitted.',
+    summary: {
+      filesScanned,
+      filesChanged,
+      legacyUrls: findings.length,
+      safeMigrations: safe,
+      manualReview: manual,
+      skipped,
+    },
+    findings: findings.map((finding) => ({
+      file: finding.file,
+      line: finding.line,
+      column: finding.column,
+      provider: finding.provider,
+      status: finding.status,
+      confidence: finding.confidence,
+      original: finding.original,
+      replacement: finding.replacement,
+      reason: finding.reason,
+    })),
+  };
+}

package/src/scanner.js

@@ -0,0 +1,84 @@
+import { providerForHostname } from './providers/index.js';
+
+const LEGACY_URL_PATTERN = /(?:(?<![A-Za-z0-9_+.-])https?:\/\/|(?<![A-Za-z0-9_+./:-])\/\/)(?:via\.placeholder\.com|placehold\.it|www\.placehold\.it|placeholder\.com|www\.placeholder\.com)(?::\d{1,5})?(?![A-Za-z0-9._:-])(?:[/?#][^\s"'<>`\\)\]}]*)?/giu;
+const CANDIDATE_PATTERN = /^(?:(https?):)?\/\/([^/?#:]+)(?::(\d{1,5}))?(.*)$/iu;
+
+function lineStartsFor(content) {
+  const starts = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content.charCodeAt(index) === 10) starts.push(index + 1);
+  }
+  return starts;
+}
+
+function sourcePosition(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    if (lineStarts[middle] <= offset) low = middle + 1;
+    else high = middle - 1;
+  }
+  return { line: high + 1, column: offset - lineStarts[high] + 1 };
+}
+
+function parseCandidate(raw) {
+  const match = CANDIDATE_PATTERN.exec(raw);
+  if (!match) return null;
+
+  const suffix = match[4] || '';
+  const fragmentAt = suffix.indexOf('#');
+  const beforeFragment = fragmentAt === -1 ? suffix : suffix.slice(0, fragmentAt);
+  const queryAt = beforeFragment.indexOf('?');
+  const path = queryAt === -1 ? beforeFragment : beforeFragment.slice(0, queryAt);
+  const query = queryAt === -1 ? '' : beforeFragment.slice(queryAt);
+
+  return {
+    raw,
+    protocol: match[1]?.toLowerCase() ?? null,
+    hostname: match[2].toLowerCase(),
+    port: match[3] ?? null,
+    suffix,
+    path,
+    query,
+  };
+}
+
+export function scanSource(content, selectedProviderIds) {
+  const lineStarts = lineStartsFor(content);
+  const findings = [];
+  LEGACY_URL_PATTERN.lastIndex = 0;
+
+  for (const match of content.matchAll(LEGACY_URL_PATTERN)) {
+    const candidate = parseCandidate(match[0]);
+    if (!candidate) continue;
+    const provider = providerForHostname(candidate.hostname);
+    if (!provider || !selectedProviderIds.has(provider.id)) continue;
+
+    const result = provider.analyse(candidate);
+    const position = sourcePosition(lineStarts, match.index);
+    findings.push({
+      provider: provider.id,
+      providerLabel: provider.label,
+      status: result.status,
+      confidence: result.confidence,
+      reason: result.reason,
+      original: match[0],
+      replacement: result.replacement,
+      start: match.index,
+      end: match.index + match[0].length,
+      ...position,
+    });
+  }
+
+  return findings;
+}
+
+export function applySafeFindings(content, findings) {
+  const safe = findings.filter((finding) => finding.status === 'safe').sort((a, b) => b.start - a.start);
+  let migrated = content;
+  for (const finding of safe) {
+    migrated = `${migrated.slice(0, finding.start)}${finding.replacement}${migrated.slice(finding.end)}`;
+  }
+  return migrated;
+}

package/src/version.js

@@ -0,0 +1 @@
+export const VERSION = '1.0.0';