@macrulez/devtoolz 0.2.1 → 0.3.0

package/README.md

@@ -127,7 +127,24 @@ looking for is never touched.
   `.vue` files get an isolated per-file check (same technique as
   `readme-check`'s own virtual-file typechecking) — a plain
   `ts.Program` can't include `.vue` in a whole-project run at all.
-- **`full-check`** — runs all twelve other commands in one sweep, each in
+- **`image-hash`** — generates [blurhash](https://blurha.sh) and/or
+  [thumbhash](https://evanw.github.io/thumbhash/) placeholders for raster
+  images (jpg, png, webp, gif, avif, tiff). Takes files and/or
+  directories — several of each, comma-separated too — and `-r` walks
+  subdirectories. Prints to stdout by default; `-o <file>` collects
+  everything into one file, `--per-file` / `--out-dir <dir>` writes a
+  file per image (`photo.jpg` → `photo.jpg.blurhash.txt`, with
+  `--suffix` and `--out-ext` to rename). Formats: `json`, `plain` (just
+  the hash text, no newline), `csv`, and `ts`/`js` modules you can import
+  straight into the app. Besides the two hashes it can produce the
+  dominant color and a tiny PNG preview (`-t all`), accepts `http(s)`
+  URLs and path lists from a file or stdin, and can keep an output file in
+  sync: `--cache` skips unchanged images, `--update --prune` merges into
+  the existing file, `--check` fails with exit code 1 when it is stale
+  (made for CI). `--dry-run` writes nothing and shows the result as a
+  table instead. Uses the native `sharp` library, which devtoolz
+  offers to install on first use — see Requirements.
+- **`full-check`** — runs all thirteen other commands in one sweep, each in
   its own safe read-only mode — the three that can write to disk
   (`strip-comments`/`console-strip`/`case-check`) are always called as a
   preview, `-y`/`--fix` are never passed. One summary table: which
@@ -145,22 +162,42 @@ only previews, `-y`/`--yes` is required to actually write anything,
 `unused-deps`, `circular-imports`, `exports-doctor`, `readme-check`,
 `empty-catch`, `todo-report`, `scripts-check`, `orphan-tests`,
 `stale-ts-ignore`, and `full-check` are all read-only — none of them ever
-write anything, there's nothing to preview or apply. Every command
-supports `--json` for machine-readable output.
+write anything, there's nothing to preview or apply. `image-hash` writes
+files only when you name an output (`-o`, `--per-file`, `--out-dir`) and
+prints to stdout otherwise. Every command supports `--json` for
+machine-readable output.
 
 ## Tone
 
 Not dead silent, not relentlessly jokey either — a small banner and some
 personality when everything comes back clean, nothing cute mixed into the
-actual findings list, which stays in aligned, colored columns (file in
-white, count/tag in dim grey) for quick scanning. Auto-disables (banner,
-color, celebration copy) the moment output isn't a real interactive
-terminal — piped, `CI` set, `NO_COLOR` set — on top of the explicit
-`--quiet`/`--plain` flags.
+actual findings list, which stays in aligned columns for quick scanning.
+
+Output is colored with one palette across every command: file paths in
+cyan with their `:line:column` dimmed, names and kinds in yellow, the
+"N problems found" heading in bold red, what a command would do in bold
+yellow and what it did in bold green, hints dimmed with the flags they
+mention (`-y`, `--dry-run`) picked out in cyan, `✔`/`✖` in the
+`full-check` table in green/red, and the diffs red/green as before.
+
+Color turns itself off the moment output isn't a real interactive
+terminal — piped, `CI` set, `NO_COLOR` set, `TERM=dumb`. `--color` (or
+`FORCE_COLOR=1`) turns it back on anyway, which is what you want for
+`devtoolz … --color | less -R` or a CI log that renders ANSI; `--plain`
+turns color, the banner and the celebration copy all off, and `--quiet`
+only drops the banner and clean-run output. The text is identical with
+and without color — only escape codes are added.
 
 ## Requirements
 
 - Node.js 20+
+- `image-hash` only: the [`sharp`](https://sharp.pixelplumbing.com)
+  image library. It ships prebuilt binaries for the common platforms and
+  is not installed with devtoolz — the first `image-hash` run offers to
+  install it into `~/.devtoolz/deps` (`-y` / `--yes` agrees up front, which
+  is also what you want in CI; without a terminal and without `--yes` the
+  command stops and says so). A `sharp` you already have installed
+  alongside devtoolz is used as-is.
 
 ## Installation
 
@@ -210,6 +247,14 @@ devtoolz orphan-tests src                      # test files whose source disappe
 
 devtoolz stale-ts-ignore                       # find @ts-ignore comments suppressing nothing
 
+devtoolz image-hash public/img                 # blurhash + thumbhash of every image, as JSON on stdout
+devtoolz image-hash a.jpg,b.png,photos -r -t blurhash -f csv -o hashes.csv
+devtoolz image-hash public/img -r -f plain --per-file   # photo.jpg.blurhash.txt + photo.jpg.thumbhash.txt
+devtoolz image-hash public/img -r -f ts -t thumbhash -o src/placeholders.ts --name placeholders
+devtoolz image-hash public/img -r --dry-run        # write nothing, show a table of the hashes
+devtoolz image-hash public/img -r -t all --components auto -o hashes.json --cache --update --prune
+devtoolz image-hash public/img -r -o hashes.json --check   # CI: exit 1 if hashes.json is stale
+
 devtoolz full-check                            # run every command, one summary table
 devtoolz full-check --skip stale-ts-ignore     # same, minus the expensive one
 ```
@@ -416,6 +461,50 @@ problems scattered across it:
 9 clean, 4 found something — see `devtoolz <command> --help` for full detail on any of them.
 ```
 
+`devtoolz image-hash public/img -r -f plain --per-file` writing a text file
+per hash next to each image:
+
+```
+🧰 devtoolz
+
+Hashed 2 images.
+
+Wrote 4 files:
+  public/img/hero.jpg.blurhash.txt
+  public/img/hero.jpg.thumbhash.txt
+  public/img/logo.png.blurhash.txt
+  public/img/logo.png.thumbhash.txt
+```
+
+`devtoolz image-hash hero.jpg -t blurhash` printing JSON to stdout, ready to
+pipe or paste:
+
+```json
+{
+  "hero.jpg": {
+    "width": 1600,
+    "height": 900,
+    "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
+  }
+}
+```
+
+`devtoolz image-hash public/img -r -t blurhash --dry-run` shows what would be
+generated as a table and writes nothing:
+
+```
+┌─────────────────────┬─────────┬──────────────────────────────┐
+│ File                │    Size │ BlurHash                     │
+├─────────────────────┼─────────┼──────────────────────────────┤
+│ public/img/blue.png │ 120×300 │ L704c9gSfQgSf:fRfQfRfQfQfQfQ │
+│ public/img/red.jpg  │ 200×100 │ L6T9R{,YfQ,Y|cjtfQjtfQfQfQfQ │
+└─────────────────────┴─────────┴──────────────────────────────┘
+
+Hashed 2 images.
+
+(dry run — nothing written)
+```
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { runStripComments } from './commands/strip-comments/run.js';
@@ -31,6 +32,10 @@ import { runStaleTsIgnore } from './commands/stale-ts-ignore/run.js';
 import { renderStaleTsIgnoreReport } from './commands/stale-ts-ignore/report.js';
 import { runFullCheck, FULL_CHECK_COMMAND_NAMES, SLOW_FULL_CHECK_COMMAND, } from './commands/full-check/run.js';
 import { renderFullCheckReport } from './commands/full-check/report.js';
+import { runImageHash } from './commands/image-hash/run.js';
+import { renderImageHashReport } from './commands/image-hash/report.js';
+import { DEFAULT_CACHE_FILE, DEFAULT_IMAGE_EXTENSIONS, ImageHashUsageError, OUTPUT_FORMATS, parseComponents, parseExtensions, parseFileList, parseFormat, parseMaxPixels, parseSampleSize, parseTypes, } from './commands/image-hash/core.js';
+import { createStyle } from './format/style.js';
 function wrapText(text, width) {
     const words = text.split(' ');
     const lines = [];
@@ -156,6 +161,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runStripComments({
         paths,
@@ -175,6 +181,7 @@ program
         const text = renderStripCommentsReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
             dryRun: options.dryRun,
         });
         if (text)
@@ -198,6 +205,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runConsoleStrip({
         paths,
@@ -218,6 +226,7 @@ program
         const text = renderConsoleStripReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -238,6 +247,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runDeadExports({
         paths,
@@ -253,7 +263,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderDeadExportsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderDeadExportsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -271,6 +285,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runCircularImports({
         paths,
@@ -287,6 +302,7 @@ program
         const text = renderCircularImportsReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -305,6 +321,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runUnusedDeps({
         dir: resolve(dir),
@@ -318,7 +335,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderUnusedDepsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderUnusedDepsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -340,6 +361,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runCaseCheck({
         paths,
@@ -357,7 +379,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderCaseCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderCaseCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -370,13 +396,18 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runExportsDoctor({ dir: resolve(dir) });
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderExportsDoctorReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderExportsDoctorReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -392,6 +423,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runReadmeCheck({
         dir: resolve(dir),
@@ -403,7 +435,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderReadmeCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderReadmeCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -420,6 +456,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runEmptyCatch({
         paths,
@@ -432,7 +469,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderEmptyCatchReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderEmptyCatchReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -451,6 +492,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runTodoReport({
         paths,
@@ -465,7 +507,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderTodoReportReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderTodoReportReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -479,6 +525,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runScriptsCheck({ dir: resolve(dir), files: options.file });
     if (options.json) {
@@ -488,6 +535,7 @@ program
         const text = renderScriptsCheckReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
@@ -509,6 +557,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((paths, options) => {
     const report = runOrphanTests({
         paths,
@@ -525,7 +574,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderOrphanTestsReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderOrphanTestsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }
@@ -541,6 +594,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action((dir, options) => {
     const report = runStaleTsIgnore({
         dir: resolve(dir),
@@ -556,12 +610,129 @@ program
         const text = renderStaleTsIgnoreReport(report, {
             quiet: options.quiet,
             plain: options.plain,
+            color: options.color,
         });
         if (text)
             console.log(text);
     }
     process.exitCode = report.exitCode;
 });
+program
+    .command('image-hash')
+    .description('Generate blurhash/thumbhash placeholders (and dominant color, tiny preview) for raster images — to stdout, one file, or a file per image')
+    .argument('[paths...]', 'image files, directories and http(s) URLs (several allowed, comma-separated too)', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('-r, --recursive', 'also walk subdirectories of every given directory', false)
+    .option('--files-from <file>', 'read more paths/URLs from a file, one per line (- = stdin, # starts a comment)')
+    .option('--ext <list>', 'comma-separated image extensions to pick up from directories', DEFAULT_IMAGE_EXTENSIONS.join(','))
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('-t, --type <list>', 'what to generate, comma-separated: blurhash, thumbhash, color (dominant), preview (tiny PNG data URI); both = blurhash+thumbhash, all = everything', 'both')
+    .option('--components <XxY|auto>', 'blurhash components, each side 1-9, or auto to pick them by aspect ratio', '4x3')
+    .option('--size <px>', 'longest side the image is scaled down to before hashing (1-100)', '100')
+    .option('--max-pixels <n>', 'refuse images with more pixels than this (0 = no limit; default: sharp limit, ~268 million)')
+    .option('-f, --format <format>', `format of the generated hashes: ${OUTPUT_FORMATS.join(', ')} (plain = just the hash text); --json prints the full report instead`, 'json')
+    .option('--name <identifier>', 'exported constant name for --format ts/js', 'imageHashes')
+    .option('--key-base <dir>', 'make the file keys in the output relative to this directory')
+    .option('--key-prefix <text>', 'text put in front of every file key, e.g. / for URL-style keys')
+    .option('-o, --out <file>', 'write everything into one file instead of stdout')
+    .option('--update', 'merge into the existing -o file instead of replacing it', false)
+    .option('--prune', 'with --update, drop entries whose image no longer exists', false)
+    .option('--per-file', 'write one file per image, next to the image', false)
+    .option('--out-dir <dir>', 'write the per-image files into this directory (implies --per-file)')
+    .option('--suffix <text>', 'per-image file name suffix after the image file name, {type} = blurhash/thumbhash/hash (default: .{type})')
+    .option('--out-ext <ext>', 'per-image file extension (default: by --format, plain = .txt)')
+    .option('--check', 'write nothing; exit 1 if the output files are missing or differ from the images', false)
+    .option('--cache [file]', `skip images that did not change since the last run, remembered in this file (default: ${DEFAULT_CACHE_FILE})`)
+    .option('--concurrency <n>', 'images processed in parallel', '4')
+    .option('--dry-run', 'write nothing — show the result as a table instead', false)
+    .option('-y, --yes', 'install the missing "sharp" image library without asking', false)
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
+    .action(async (paths, options) => {
+    const style = createStyle({ plain: options.plain, color: options.color });
+    const showProgress = !options.json && !options.quiet && Boolean(process.stderr.isTTY) && !options.plain;
+    let progressShown = false;
+    try {
+        const listed = options.filesFrom !== undefined
+            ? parseFileList(readFileSync(options.filesFrom === '-' ? 0 : options.filesFrom, 'utf8'))
+            : [];
+        const report = await runImageHash({
+            paths: [...paths, ...listed],
+            cwd: resolve(options.cwd),
+            types: parseTypes(options.type),
+            recursive: options.recursive,
+            extensions: parseExtensions(options.ext),
+            ignoreGlobs: options.ignore,
+            respectGitignore: options.respectGitignore,
+            components: parseComponents(options.components),
+            size: parseSampleSize(options.size),
+            ...(options.maxPixels !== undefined
+                ? { maxPixels: parseMaxPixels(options.maxPixels) }
+                : {}),
+            format: parseFormat(options.format),
+            exportName: options.name,
+            ...(options.keyBase !== undefined ? { keyBase: options.keyBase } : {}),
+            ...(options.keyPrefix !== undefined ? { keyPrefix: options.keyPrefix } : {}),
+            ...(options.out !== undefined ? { out: options.out } : {}),
+            update: options.update,
+            prune: options.prune,
+            perFile: options.perFile,
+            ...(options.outDir !== undefined ? { outDir: options.outDir } : {}),
+            ...(options.suffix !== undefined ? { suffix: options.suffix } : {}),
+            ...(options.outExt !== undefined ? { outExtension: options.outExt } : {}),
+            check: options.check,
+            ...(options.cache !== undefined
+                ? { cache: options.cache === true ? DEFAULT_CACHE_FILE : String(options.cache) }
+                : {}),
+            concurrency: Math.max(1, Number.parseInt(options.concurrency, 10) || 4),
+            assumeYes: options.yes,
+            dryRun: options.dryRun,
+            ...(showProgress
+                ? {
+                    onProgress: ({ done, total }) => {
+                        if (total < 2)
+                            return;
+                        progressShown = true;
+                        process.stderr.write(`\r${style.info(`Hashing ${done}/${total}`)}`);
+                    },
+                }
+                : {}),
+        });
+        if (progressShown)
+            process.stderr.write('\r\x1b[K');
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else if (report.stdout !== null) {
+            process.stdout.write(report.stdout);
+            for (const error of report.errors)
+                console.error(`${error.file} — ${error.message}`);
+        }
+        else {
+            const text = renderImageHashReport(report, {
+                quiet: options.quiet,
+                plain: options.plain,
+                color: options.color,
+            });
+            if (text)
+                console.log(text);
+        }
+        process.exitCode = report.exitCode;
+    }
+    catch (error) {
+        if (progressShown)
+            process.stderr.write('\r\x1b[K');
+        if (error instanceof ImageHashUsageError) {
+            console.error(`error: ${error.message}`);
+            process.exitCode = 2;
+            return;
+        }
+        throw error;
+    }
+});
 // Only `full-check` ever prompts — every other command here is a single,
 // fast, non-interactive check. `stale-ts-ignore` is the one command a
 // bare `full-check` can turn into a genuinely slow run, so this asks
@@ -606,6 +777,7 @@ program
     .option('--json', 'machine-readable output', false)
     .option('--quiet', 'suppress output when there is nothing to report', false)
     .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .option('--color', 'force colored output even when piped or in CI', false)
     .action(async (dir, options) => {
     const skip = new Set(options.skip);
     const shouldPrompt = options.prompt &&
@@ -634,7 +806,11 @@ program
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        const text = renderFullCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        const text = renderFullCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+            color: options.color,
+        });
         if (text)
             console.log(text);
     }