lake-cimg 1.0.0 → 1.0.1

package/bin/cimg.js

@@ -217,6 +217,20 @@ program
     }
   });
 
+function collectString(val, memo) {
+  const arr = memo ?? [];
+  arr.push(val);
+  return arr;
+}
+
+function parseAliasPair(val) {
+  const i = val.indexOf("=");
+  if (i <= 0) {
+    throw new Error("格式须为 key=相对路径，例如 @=src 或 @assets=src/assets");
+  }
+  return [val.slice(0, i).trim(), val.slice(i + 1).trim()];
+}
+
 program
   .command("scan-code [path]")
   .description(
@@ -231,17 +245,46 @@ program
     500
   )
   .option("--issues-only", "仅输出含 issues 的条目")
+  .option(
+    "--project-root <dir>",
+    "解析 /images/...、@/... 时的工程根目录（默认当前工作目录）"
+  )
+  .option(
+    "--public-dir <dir>",
+    "根路径下静态目录，可重复；用于解析以 / 开头的 URL 路径（默认 public、static）",
+    collectString
+  )
+  .option(
+    "--alias <pair>",
+    "路径别名 key=相对工程根的路径，可重复；默认 @=src。例: --alias @aaa=packages/aaa",
+    (v, prev) => {
+      const pair = parseAliasPair(v);
+      return [...(prev ?? []), pair];
+    },
+    []
+  )
   .action(async (pathArg, opts) => {
     const raw =
       pathArg != null && typeof pathArg === "string" ? pathArg.trim() : "";
     const root = resolveUserPath(raw !== "" ? raw : ".");
     const limit = Number.isNaN(opts.limit) ? 500 : opts.limit;
+    const aliasList = opts.alias ?? [];
+    const aliases =
+      aliasList.length > 0 ? Object.fromEntries(aliasList) : undefined;
+    const publicDirs = opts.publicDir;
     try {
       const result = await scanCodeReferences(root, {
         recursive: opts.recursive !== false,
         cwd: process.cwd(),
         limit,
         issuesOnly: !!opts.issuesOnly,
+        ...(opts.projectRoot != null && String(opts.projectRoot).trim() !== ""
+          ? { projectRoot: String(opts.projectRoot).trim() }
+          : {}),
+        ...(aliases != null ? { aliases } : {}),
+        ...(publicDirs != null && publicDirs.length > 0
+          ? { publicDirs }
+          : {}),
       });
       console.log(JSON.stringify(result, null, 2));
       process.exit(0);

package/lib/compress.js

@@ -9,9 +9,13 @@ import sharp from "sharp";
 import {
   SUPPORTED_EXT,
   DEFAULT_QUALITY,
-  DEFAULT_EFFORT,
   supportedFormatsLabel,
 } from "./constants.js";
+import {
+  applyResizeInside,
+  encodeWebpBuffer,
+  encodeJpegBuffer,
+} from "./sharpHelpers.js";
 
 /** Max concurrent tasks for processing images */
 const MAX_CONCURRENCY = Math.max(1, cpus().length);
@@ -59,23 +63,6 @@ function isSupported(filePath) {
   return SUPPORTED_EXT.includes(extname(filePath).toLowerCase());
 }
 
-/**
- * Encode pipeline to WebP buffer with shared sharp options.
- * @param {import("sharp").Sharp} pipeline
- * @param {number} quality
- * @param {{ lossless?: boolean }} [options]
- */
-async function encodeWebpBuffer(pipeline, quality, { lossless = false } = {}) {
-  return pipeline
-    .webp({
-      quality,
-      effort: DEFAULT_EFFORT,
-      smartSubsample: true,
-      lossless,
-    })
-    .toBuffer();
-}
-
 /**
  * Recursively collect image paths under dir (or return [dir] if dir is a file).
  * @param {string} inputPath - Absolute path to file or directory
@@ -135,15 +122,7 @@ export async function processOne(inputPath, options = {}) {
   let pipeline = sharp(inputBuffer, { animated: true });
   const inputMeta = await pipeline.metadata();
 
-  if (size != null && size > 0) {
-    pipeline = pipeline.resize({
-      width: size,
-      height: size,
-      fit: "inside",
-      withoutEnlargement: true,
-      background: { r: 0, g: 0, b: 0, alpha: 0 },
-    });
-  }
+  pipeline = applyResizeInside(pipeline, size);
 
   const outputBuffer = toWebp
     ? await encodeWebpBuffer(pipeline, quality, { lossless: false })
@@ -172,7 +151,7 @@ async function toFormatBuffer(pipeline, ext, quality) {
   switch (ext) {
     case ".jpg":
     case ".jpeg":
-      return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+      return encodeJpegBuffer(pipeline, quality);
     case ".png":
       return pipeline.png({ compressionLevel: 9 }).toBuffer();
     case ".webp":

package/lib/pictureStack.js

@@ -5,10 +5,13 @@
 import { readFile, writeFile, mkdir, stat } from "fs/promises";
 import { dirname, join, resolve, basename, extname } from "path";
 import sharp from "sharp";
-import { DEFAULT_QUALITY, DEFAULT_EFFORT } from "./constants.js";
-
-/** AVIF effort 0–9 (higher = slower, often smaller) */
-const DEFAULT_AVIF_EFFORT = 4;
+import { DEFAULT_QUALITY } from "./constants.js";
+import {
+  applyResizeInside,
+  encodeAvifBuffer,
+  encodeWebpBuffer,
+  encodeJpegBuffer,
+} from "./sharpHelpers.js";
 
 /**
  * @param {import("sharp").Sharp} pipeline - Configured pipeline (e.g. after resize)
@@ -16,22 +19,9 @@ const DEFAULT_AVIF_EFFORT = 4;
  */
 async function encodeTriple(pipeline, q) {
   const [avifBuf, webpBuf, jpegBuf] = await Promise.all([
-    pipeline
-      .clone()
-      .avif({ quality: q.avifQuality, effort: DEFAULT_AVIF_EFFORT })
-      .toBuffer(),
-    pipeline
-      .clone()
-      .webp({
-        quality: q.quality,
-        effort: DEFAULT_EFFORT,
-        smartSubsample: true,
-      })
-      .toBuffer(),
-    pipeline
-      .clone()
-      .jpeg({ quality: q.jpegQuality, mozjpeg: true })
-      .toBuffer(),
+    encodeAvifBuffer(pipeline.clone(), q.avifQuality),
+    encodeWebpBuffer(pipeline.clone(), q.quality),
+    encodeJpegBuffer(pipeline.clone(), q.jpegQuality),
   ]);
   return { avifBuf, webpBuf, jpegBuf };
 }
@@ -85,16 +75,10 @@ export async function processPictureStack(inputPath, options) {
   const inputBuffer = await readFile(absoluteIn);
   const sizeBefore = inputBuffer.length;
 
-  let pipeline = sharp(inputBuffer, { animated: false });
-  if (size != null && size > 0) {
-    pipeline = pipeline.resize({
-      width: size,
-      height: size,
-      fit: "inside",
-      withoutEnlargement: true,
-      background: { r: 0, g: 0, b: 0, alpha: 0 },
-    });
-  }
+  let pipeline = applyResizeInside(
+    sharp(inputBuffer, { animated: false }),
+    size
+  );
 
   const { avifBuf, webpBuf, jpegBuf } = await encodeTriple(pipeline, {
     quality,

package/lib/scanCodeReferences.js

@@ -40,6 +40,40 @@ const DEFAULT_EXCLUDE_DIRS = new Set([
 /** Relative ratio difference threshold (1% = 0.01) */
 const DEFAULT_RATIO_TOLERANCE = 0.01;
 
+/** Try these folders under projectRoot for URL paths like `/images/a.png` (public 静态资源) */
+const DEFAULT_PUBLIC_DIRS = ["public", "static"];
+
+/**
+ * @param {string} ref
+ * @param {Record<string, string>} aliases
+ * @returns {object | null}
+ */
+function matchAliasRef(ref, aliases) {
+  const keys = Object.keys(aliases)
+    .filter((k) => k !== "~")
+    .sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    const prefix = `${key}/`;
+    if (ref.startsWith(prefix)) {
+      return { key, rest: ref.slice(prefix.length) };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} abs
+ * @returns {Promise<boolean>}
+ */
+async function isExistingFile(abs) {
+  try {
+    const s = await stat(abs);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {string} text
  * @param {number} index
@@ -313,11 +347,17 @@ function extractPugImgRefs(content) {
 
 /**
  * @param {string} ref
- * @param {string} hostDir
- * @returns {{ status: 'ok', path: string } | { status: 'skip', reason: string }}
+ * @param {string} hostDir - 源码文件所在目录（相对路径 ./ ../ 以此为基准）
+ * @param {{
+ *   projectRoot: string,
+ *   aliases: Record<string, string>,
+ *   publicDirs: string[],
+ * }} opts
+ * @returns {Promise<{ status: 'ok', path: string } | { status: 'skip', reason: string }>}
  */
-function resolveLocalImageRef(ref, hostDir) {
-  const trimmed = ref.trim();
+async function resolveLocalImageRef(ref, hostDir, opts) {
+  const { projectRoot, aliases, publicDirs } = opts;
+  let trimmed = ref.trim();
   if (!trimmed) return { status: "skip", reason: "empty" };
   if (/^https?:\/\//i.test(trimmed)) {
     return { status: "skip", reason: "remote_url" };
@@ -325,14 +365,57 @@ function resolveLocalImageRef(ref, hostDir) {
   if (trimmed.startsWith("data:")) {
     return { status: "skip", reason: "data_uri" };
   }
-  if (trimmed.startsWith("@/") || trimmed.startsWith("~/") || trimmed.startsWith("~@/")) {
-    return { status: "skip", reason: "alias_path" };
+
+  if (trimmed.startsWith("~@/")) {
+    trimmed = `@/${trimmed.slice(3)}`;
   }
+
+  if (trimmed.startsWith("/") && !trimmed.startsWith("//")) {
+    const relFromWebRoot = trimmed.replace(/^\/+/, "");
+    for (const pd of publicDirs) {
+      const candidate = resolve(projectRoot, pd, relFromWebRoot);
+      if (await isExistingFile(candidate)) {
+        return { status: "ok", path: candidate };
+      }
+    }
+    return { status: "skip", reason: "public_path_not_found" };
+  }
+
+  if (trimmed.startsWith("~/")) {
+    const tildeBase = aliases["~"];
+    if (tildeBase == null || tildeBase === "") {
+      return { status: "skip", reason: "alias_path" };
+    }
+    const rest = trimmed.slice(2);
+    const candidate = resolve(projectRoot, tildeBase, rest);
+    if (await isExistingFile(candidate)) {
+      return { status: "ok", path: candidate };
+    }
+    return { status: "skip", reason: "alias_target_not_found" };
+  }
+
+  const aliasHit = matchAliasRef(trimmed, aliases);
+  if (aliasHit) {
+    const baseRel = aliases[aliasHit.key];
+    if (baseRel == null || baseRel === "") {
+      return { status: "skip", reason: "unknown_alias" };
+    }
+    const candidate = resolve(projectRoot, baseRel, aliasHit.rest);
+    if (await isExistingFile(candidate)) {
+      return { status: "ok", path: candidate };
+    }
+    return { status: "skip", reason: "alias_target_not_found" };
+  }
+
+  if (trimmed.startsWith("@") && trimmed.includes("/")) {
+    return { status: "skip", reason: "unknown_alias" };
+  }
+
   if (!IMG_EXT_RE.test(trimmed)) {
     return { status: "skip", reason: "not_image_extension" };
   }
-  const path = resolve(hostDir, trimmed);
-  return { status: "ok", path };
+  const pathAbs = resolve(hostDir, trimmed);
+  return { status: "ok", path: pathAbs };
 }
 
 /**
@@ -515,6 +598,9 @@ async function runPool(tasks, concurrency) {
  *   issuesOnly?: boolean,
  *   ratioTolerance?: number,
  *   metadataConcurrency?: number,
+ *   projectRoot?: string,
+ *   aliases?: Record<string, string>,
+ *   publicDirs?: string[],
  * }} [options]
  */
 export async function scanCodeReferences(rootDir, options = {}) {
@@ -525,8 +611,22 @@ export async function scanCodeReferences(rootDir, options = {}) {
     issuesOnly = false,
     ratioTolerance = DEFAULT_RATIO_TOLERANCE,
     metadataConcurrency = 8,
+    projectRoot: projectRootOpt,
+    aliases: aliasesOpt,
+    publicDirs: publicDirsOpt,
   } = options;
 
+  const projectRoot = resolve(cwd, projectRootOpt != null ? projectRootOpt : ".");
+  const aliases = {
+    "@": "src",
+    ...(aliasesOpt && typeof aliasesOpt === "object" ? aliasesOpt : {}),
+  };
+  const publicDirs =
+    Array.isArray(publicDirsOpt) && publicDirsOpt.length > 0
+      ? publicDirsOpt
+      : DEFAULT_PUBLIC_DIRS;
+  const resolveOpts = { projectRoot, aliases, publicDirs };
+
   const sourceExts =
     options.sourceExts != null
       ? new Set(
@@ -602,7 +702,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
   for (const { absHost, ref } of staged) {
     if (ref.parse?.dynamic || ref.parse?.missingSrc) continue;
     if (!ref.rawRef) continue;
-    const res = resolveLocalImageRef(ref.rawRef, absHost);
+    const res = await resolveLocalImageRef(ref.rawRef, absHost, resolveOpts);
     if (res.status === "ok") uniquePaths.add(res.path);
   }
 
@@ -691,7 +791,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
       continue;
     }
 
-    const resolved = resolveLocalImageRef(r.rawRef, absHost);
+    const resolved = await resolveLocalImageRef(r.rawRef, absHost, resolveOpts);
     if (resolved.status === "skip") {
       const row = {
         file,

package/lib/sharpHelpers.js

@@ -0,0 +1,67 @@
+/**
+ * Shared Sharp pipeline helpers (resize + encode) for compress and picture stack.
+ */
+import { DEFAULT_EFFORT } from "./constants.js";
+
+const RESIZE_BACKGROUND = { r: 0, g: 0, b: 0, alpha: 0 };
+
+/** AVIF effort 0–9 (higher = slower, often smaller) */
+export const DEFAULT_AVIF_EFFORT = 4;
+
+/**
+ * Apply "fit inside" square resize when size > 0; otherwise return pipeline unchanged.
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number | null | undefined} size
+ * @returns {import("sharp").Sharp}
+ */
+export function applyResizeInside(pipeline, size) {
+  if (size == null || size <= 0) return pipeline;
+  return pipeline.resize({
+    width: size,
+    height: size,
+    fit: "inside",
+    withoutEnlargement: true,
+    background: RESIZE_BACKGROUND,
+  });
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ * @param {{ lossless?: boolean }} [options]
+ */
+export async function encodeWebpBuffer(
+  pipeline,
+  quality,
+  { lossless = false } = {}
+) {
+  return pipeline
+    .webp({
+      quality,
+      effort: DEFAULT_EFFORT,
+      smartSubsample: true,
+      lossless,
+    })
+    .toBuffer();
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ */
+export async function encodeJpegBuffer(pipeline, quality) {
+  return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ * @param {number} [effort]
+ */
+export async function encodeAvifBuffer(
+  pipeline,
+  quality,
+  effort = DEFAULT_AVIF_EFFORT
+) {
+  return pipeline.avif({ quality, effort }).toBuffer();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lake-cimg",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Batch image compression to WebP — CLI plus Agent Skills for frontend image audit (scan-code, picture stack)",
   "keywords": [
     "image",

package/skills/cimg-audit/SKILL.md

@@ -38,14 +38,14 @@ More flags: `npx lake-cimg@latest scan-code --help` (e.g. `--limit`, `--issues-o
 ## Workflow
 
 - [ ] **1. Scan (read-only):** `npx lake-cimg@latest scan-code [path]` — see **Invoke `scan-code`** above.
-- [ ] **2. Triage:** Prefer **`hints`** for what to change; use **`issues`** codes to group or filter. Common codes: `missing_dimensions`, `aspect_ratio_mismatch`, `suggest_modern_format` (consider AVIF/WebP + `<picture>` — match product/browser support), `needs_manual_review`, `missing_src`, `cannot_resolve`, `cannot_read_metadata`.
-- [ ] **3. Fix then optimize:** Apply markup fixes using [reference.md](reference.md) templates (`<img>`, `<picture>`). For **all** raster refs that need format or responsive delivery, not only one hero row. Then run compression / stacks: `npx lake-cimg@latest <path> [options]`; for AVIF + WebP + JPEG from one source: `npx lake-cimg@latest picture <input> -O <outDir>` (details: package [README.md](../../README.md)).
+- [ ] **2. Triage:** Prefer **`hints`** for what to change; use **`issues`** codes to group or filter. Common codes: `missing_dimensions`, `aspect_ratio_mismatch`, `suggest_modern_format` (default: **single WebP** — point `src` / `srcset` at `.webp` after exporting; use **`<picture>`** with AVIF/WebP + legacy fallback **only if the user explicitly asks** for multi-format markup or old-browser JPEG/PNG fallback), `needs_manual_review`, `missing_src`, `cannot_resolve`, `cannot_read_metadata`.
+- [ ] **3. Fix then optimize:** Apply markup using [reference.md](reference.md) (`<img>` first; `<picture>` only when the user requires it). For **all** raster refs that need format or responsive delivery, not only one hero row. Compress / emit WebP: `npx lake-cimg@latest <path> [options]`. **Optional** full stack for `<picture>` when requested: `npx lake-cimg@latest picture <input> -O <outDir>` (details: package [README.md](../../README.md)).
 
 ## Rules of thumb
 
 - **Aspect ratio:** Match display ratio to intrinsic (w÷h), or use **`object-fit`** + explicit box / `aspect-ratio` for crop/letterbox.
 - **CLS:** Add `width` and `height` to `<img>`, or use CSS `aspect-ratio`. For `missing_dimensions`, fill in the exact `intrinsicWidth` / `intrinsicHeight`.
-- **Responsive:** `<picture>` and/or **`srcset` + `sizes`**; each `<source type="…">` must match the real file type; Generate width variants with `picture … -s <px>` or separate exports.
+- **Responsive:** **`srcset` + `sizes`** on `<img>` (works with a single WebP). **`<picture>`** only when the user wants multiple formats in HTML; each `<source type="…">` must match the real file type. Width variants: separate files or `picture … -s <px>` when building a stack.
 - **LCP:** At most one hero per view: **`fetchPriority="high"`**, **`loading="eager"`**; lazy-load the rest.
 - **Alt:** Describe content and purpose; no keyword stuffing; **`alt=""`** only for decorative images.
 
@@ -60,4 +60,4 @@ If **`hints`** mention alias skip: use **`rawRef`** and map the alias via Vite/w
 | Command | Role |
 | --- | --- |
 | `npx lake-cimg@latest <path>` | Compress / WebP — see `npx lake-cimg@latest --help` (`-o`, `-s`, `-q`, `-r`). |
-| `npx lake-cimg@latest picture <input> -O <outDir>` | One raster → AVIF + WebP + JPEG for `<picture>`. |
+| `npx lake-cimg@latest picture <input> -O <outDir>` | One raster → AVIF + WebP + JPEG **when the user wants `<picture>` / multi-format**; not the default if single WebP is enough. |

package/skills/cimg-audit/reference.md

@@ -8,12 +8,15 @@ Supplement for [SKILL.md](SKILL.md). Copy-paste starting points; adjust paths, d
 
 ```html
 <img
-  src="photo.jpg"
-  width="1200"
-  height="800"
-  alt="Describe subject and purpose on this page"
-  loading="lazy"
-  decoding="async">
+  srcset="
+    maine-coon-nap-320w.webp 320w,
+    maine-coon-nap-480w.webp 480w,
+    maine-coon-nap-800w.webp 800w
+  "
+  sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
+  src="maine-coon-nap-800w.webp"
+  alt="A watercolor illustration of a maine coon napping leisurely in front of a fireplace"
+/>
 ```
 
 ## `<picture>` + `srcset` + `sizes`
@@ -24,26 +27,23 @@ Supplement for [SKILL.md](SKILL.md). Copy-paste starting points; adjust paths, d
 <picture>
   <source
     type="image/avif"
-    srcset="hero-400.avif 400w,
-            hero-800.avif 800w,
-            hero-1200.avif 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw">
+    srcset="hero-400.avif 400w, hero-800.avif 800w, hero-1200.avif 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw"
+  />
   <source
     type="image/webp"
-    srcset="hero-400.webp 400w,
-            hero-800.webp 800w,
-            hero-1200.webp 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw">
+    srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw"
+  />
   <img
     src="hero-800.jpg"
-    srcset="hero-400.jpg 400w,
-            hero-800.jpg 800w,
-            hero-1200.jpg 1200w"
+    srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w"
     sizes="(max-width: 600px) 100vw, 50vw"
     width="1200"
     height="600"
     alt="Describe subject and purpose on this page"
     loading="lazy"
-    decoding="async">
+    decoding="async"
+  />
 </picture>
 ```