lake-cimg 0.0.3 → 1.0.1

package/README.md

@@ -110,17 +110,17 @@ npx lake-cimg@latest picture <input> -O <outDir> [选项]
 - **格式**：对 JPEG/PNG 等提示可考虑 WebP/AVIF 或 `picture` 子命令
 
 ```text
-npx lake-cimg@latest scan-code <dir> [--no-recursive] [--limit <n>] [--issues-only] [--plain]
+npx lake-cimg@latest scan-code [path] [--no-recursive] [--limit <n>] [--issues-only]
 ```
 
-| 选项 | 说明 |
+| 参数 / 选项 | 说明 |
 | --- | --- |
-| `-r, --recursive` | 递归子目录（默认开启） |
+| `path` | 可选。省略时等价于 `.`（当前工作目录，一般在项目根执行）。可为**目录**（递归扫描其下源码）或**单个源码文件**（如某 `.pug` / `.vue`，只扫该文件） |
+| `-r, --recursive` | 递归子目录（默认开启；仅对**目录**扫描有效） |
 | `--limit <n>` | 最多输出多少条引用点（默认 `500`） |
-| `--issues-only` | 仅输出 `issues` 非空的条目 |
-| `--plain` | 简要文本而非 JSON（默认 stdout 为 JSON） |
+| `--issues-only` | 仅输出 `issues` 非空的条目（全绿引用不出现在 `items` 里，JSON 更小、省 token） |
 
-默认会跳过 `node_modules`、`dist`、`.git` 等目录。动态 `src`、远程 URL、别名路径会进入报告但通常无法解析到磁盘文件。
+目录扫描时默认会跳过 `node_modules`、`dist`、`.git` 等子目录。动态 `src`、远程 URL、别名路径会进入报告但通常无法解析到磁盘文件。
 
 ### 前端最佳实践（React / `<picture>`）
 
@@ -130,8 +130,6 @@ npx lake-cimg@latest scan-code <dir> [--no-recursive] [--limit <n>] [--issues-on
 4. **响应式**：若同一图有多套宽度，应为每条 `source`/`img` 提供 **`sizes`** 与多宽度 `srcSet`（需配合构建或 `npx lake-cimg@latest picture` 多次导出不同 `size`）；当前 CLI 一次导出的是单套 URL。
 5. **路径**：把生成文件放到 **`public/`**（如 Next.js）或 CDN，片段里的路径与部署前缀一致。
 
-`--snippet` 输出的是可直接改的模板；生产环境请按设计稿补上准确的 `width`/`height`/`alt`/`sizes`。
-
 ## 支持格式
 
 输入：**jpg / jpeg、png、webp、gif**（gif 含动图，处理时由 sharp 按能力读写）。
@@ -153,7 +151,7 @@ npx lake-cimg@latest scan-code <dir> [--no-recursive] [--limit <n>] [--issues-on
 - `processOne(inputPath, options)` — 单文件
 - `collectFiles(inputPath, recursive)` — 枚举待处理路径
 - `scanAssets(dir, options)` — `lib/scanAssets.js`，按文件体积筛选偏大图片并生成建议（供脚本或自建工具使用）
-- `scanCodeReferences(rootDir, options)` — `lib/scanCodeReferences.js`，扫描源码引用并结合像素尺寸给出 CLS / 比例 / 格式类建议（供 CLI 或脚本使用）
+- `scanCodeReferences(path, options)` — `lib/scanCodeReferences.js`，`path` 为目录或单个支持的源码文件（或 `.`），扫描源码引用并结合像素尺寸给出 CLS / 比例 / 格式类建议（供 CLI 或脚本使用）
 - `processPictureStack(inputPath, options)` — `lib/pictureStack.js`，一次写出 AVIF / WebP / JPEG
 
 适合在构建脚本或 Node 服务中复用同一套逻辑。

package/bin/cimg.js

@@ -217,10 +217,24 @@ 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 <dir>")
+  .command("scan-code [path]")
   .description(
-    "扫描源码中的图片引用（html/vue/pug/js/ts/tsx/jsx），结合像素尺寸给出 CLS / 比例 / 格式建议（只读）"
+    "扫描源码图片引用并输出 JSON 建议（CLS/比例/格式）。path 可为目录或源码文件，省略时为当前目录"
   )
   .option("-r, --recursive", "递归扫描子目录", true)
   .option("--no-recursive", "不递归子目录")
@@ -231,31 +245,48 @@ program
     500
   )
   .option("--issues-only", "仅输出含 issues 的条目")
-  .option("--plain", "纯文本输出（默认 stdout 为 JSON）")
-  .action(async (dir, opts) => {
-    if (!dir || dir.trim() === "") {
-      program.outputHelp();
-      process.exit(1);
-    }
-    const root = resolveUserPath(dir);
+  .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 }
+          : {}),
       });
-      if (!opts.plain) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(result.summary);
-        for (const it of result.items) {
-          console.log(
-            `${it.file}:${it.line} ${it.issues?.join(",") || ""} ${it.rawRef || ""} -> ${it.resolvedPath || "-"}`
-          );
-        }
-      }
+      console.log(JSON.stringify(result, null, 2));
       process.exit(0);
     } catch (err) {
       console.error("错误:", err.message);

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
@@ -52,6 +86,43 @@ function lineColAt(text, index) {
   return { line, column };
 }
 
+/**
+ * Ranges [start, end) of `<picture>...</picture>` blocks that contain at least one
+ * AVIF/WebP `<source>` (MIME type or srcset extension). Non-nested `<picture>` typical case.
+ * @param {string} content
+ * @returns {Array<{ start: number, end: number }>}
+ */
+function collectPictureModernIntervals(content) {
+  const re = /<picture\b[^>]*>([\s\S]*?)<\/picture>/gi;
+  const intervals = [];
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const full = m[0];
+    const start = m.index;
+    const end = start + full.length;
+    const hasModern =
+      /type\s*=\s*["']image\/(?:avif|webp)["']/i.test(full) ||
+      /\bsrcset\s*=\s*["'][^"']*\.(?:avif|webp)\b/i.test(full);
+    if (hasModern) {
+      intervals.push({ start, end });
+    }
+  }
+  return intervals;
+}
+
+/**
+ * @param {number} imgIndex
+ * @param {number} imgTagLen
+ * @param {Array<{ start: number, end: number }>} intervals
+ */
+function imgInsidePictureModern(imgIndex, imgTagLen, intervals) {
+  const imgEnd = imgIndex + imgTagLen;
+  for (const { start, end } of intervals) {
+    if (imgIndex >= start && imgEnd <= end) return true;
+  }
+  return false;
+}
+
 /**
  * @param {string} dir
  * @param {Set<string>} excludeDirs
@@ -276,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" };
@@ -288,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 };
 }
 
 /**
@@ -319,6 +439,8 @@ function extractFromContent(content, hostDir, sourceExt = "") {
     }
   }
 
+  const pictureModernIntervals = collectPictureModernIntervals(content);
+
   const imgRe = /<img\b[^>]*>/gis;
   let m;
   while ((m = imgRe.exec(content)) !== null) {
@@ -326,6 +448,11 @@ function extractFromContent(content, hostDir, sourceExt = "") {
     const index = m.index;
     const { line, column } = lineColAt(content, index);
     const parsed = parseImgTag(tag);
+    const pictureHasModernSources = imgInsidePictureModern(
+      index,
+      tag.length,
+      pictureModernIntervals
+    );
 
     if (parsed.srcKind === "dynamic") {
       refs.push({
@@ -335,7 +462,11 @@ function extractFromContent(content, hostDir, sourceExt = "") {
         rawRef: "",
         kind: "img",
         context: tag.slice(0, 200),
-        parse: { ...parsed, dynamic: true },
+        parse: {
+          ...parsed,
+          dynamic: true,
+          ...(pictureHasModernSources ? { pictureHasModernSources: true } : {}),
+        },
       });
       continue;
     }
@@ -347,7 +478,11 @@ function extractFromContent(content, hostDir, sourceExt = "") {
         rawRef: "",
         kind: "img",
         context: tag.slice(0, 200),
-        parse: { ...parsed, missingSrc: true },
+        parse: {
+          ...parsed,
+          missingSrc: true,
+          ...(pictureHasModernSources ? { pictureHasModernSources: true } : {}),
+        },
       });
       continue;
     }
@@ -359,7 +494,9 @@ function extractFromContent(content, hostDir, sourceExt = "") {
       rawRef: parsed.srcRaw,
       kind: "img",
       context: tag.slice(0, 200),
-      parse: parsed,
+      parse: pictureHasModernSources
+        ? { ...parsed, pictureHasModernSources: true }
+        : parsed,
     });
   }
 
@@ -451,7 +588,7 @@ async function runPool(tasks, concurrency) {
 }
 
 /**
- * @param {string} rootDir
+ * @param {string} rootDir 扫描根路径：可为**目录**（递归枚举源码）或**单个源码文件**（仅扫描该文件）。传 `.` 表示当前工作目录。
  * @param {{
  *   recursive?: boolean,
  *   cwd?: string,
@@ -461,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 = {}) {
@@ -471,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(
@@ -500,17 +654,26 @@ export async function scanCodeReferences(rootDir, options = {}) {
   } catch {
     throw new Error(`路径不存在: ${absoluteRoot}`);
   }
-  if (!st.isDirectory()) {
-    throw new Error(`不是目录: ${absoluteRoot}`);
+  /** @type {string[]} */
+  let sourcePaths;
+  if (st.isFile()) {
+    const ext = extname(absoluteRoot).toLowerCase();
+    if (!sourceExts.has(ext)) {
+      const supported = [...sourceExts].sort().join(", ");
+      throw new Error(`不支持的源码扩展名: ${ext || "(无)"}（支持: ${supported}）`);
+    }
+    sourcePaths = [absoluteRoot];
+  } else if (st.isDirectory()) {
+    sourcePaths = await collectSourceFiles(
+      absoluteRoot,
+      excludeDirs,
+      sourceExts,
+      recursive
+    );
+  } else {
+    throw new Error(`不是文件或目录: ${absoluteRoot}`);
   }
 
-  const sourcePaths = await collectSourceFiles(
-    absoluteRoot,
-    excludeDirs,
-    sourceExts,
-    recursive
-  );
-
   /** @type {Array<{ file: string, absHost: string, ref: RawRef }>} */
   const staged = [];
 
@@ -539,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);
   }
 
@@ -628,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,
@@ -642,7 +805,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
         intrinsicHeight: null,
         intrinsicFormat: null,
         issues: ["cannot_resolve"],
-        hints: [`跳过: ${resolved.reason}`],
+        hints: [`Skipped: ${resolved.reason}`],
         snippet: r.context,
       };
       if (!issuesOnly || row.issues.length) items.push(row);
@@ -701,7 +864,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
       if (!reservesSpace && iw > 0 && ih > 0) {
         issues.push("missing_dimensions");
         hints.push(
-          "补充 width 与 height，或 style 中的 aspect-ratio，以减少 CLS"
+          `missing_dimensions: set width/height or CSS aspect-ratio for CLS; intrinsicWidth=${iw} intrinsicHeight=${ih}`
         );
       }
 
@@ -724,6 +887,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
     }
 
     if (
+      !(r.kind === "img" && r.parse?.pictureHasModernSources) &&
       (ext === ".jpg" ||
         ext === ".jpeg" ||
         ext === ".png" ||

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": "0.0.3",
+  "version": "1.0.1",
   "description": "Batch image compression to WebP — CLI plus Agent Skills for frontend image audit (scan-code, picture stack)",
   "keywords": [
     "image",
@@ -34,7 +34,8 @@
   },
   "scripts": {
     "compress": "node bin/cimg.js",
-    "start": "node bin/cimg.js"
+    "start": "node bin/cimg.js",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "commander": "^12.0.0",

package/skills/cimg-audit/SKILL.md

@@ -9,50 +9,55 @@ description: >-
 
 # cimg image audit
 
-Use **`npx lake-cimg@latest`** from the project root (no global install).
+Run **`npx lake-cimg@latest`** from the **project root** (no global install).
 
-## Workflow
+<a id="invoke-scan-code"></a>
 
-Copy into a task list and tick as you go:
+## Invoke `scan-code`
 
-- [ ] **1. Scan (read-only):** `npx lake-cimg@latest scan-code <dir>` — **stdout is JSON** (default); **`--plain`** for a short text summary. Prefer an **absolute** path for `<dir>`.
-- [ ] **2. Triage `issues`:** Each JSON row has `issues` (string codes) and **`hints`** (human-readable, often Chinese)—use **`hints` first** when choosing a fix; codes are for filtering and grouping. Possible codes: `missing_dimensions`, `aspect_ratio_mismatch`, `suggest_modern_format`, `needs_manual_review`, `missing_src`, `cannot_resolve`, `cannot_read_metadata`.
-- [ ] **3. Fix markup:** add `width`/`height`, CSS `aspect-ratio`, or intentional `object-fit: cover|contain` when the box ratio must differ from the asset.
-- [ ] **4. Optimize assets last:** `npx lake-cimg@latest <path> [options]`; for AVIF+WebP+JPEG stacks: `npx lake-cimg@latest picture <input> -O <outDir>` (see package README).
+Use **one** command starting with `npx` — **not** `cd … && npx …` (PowerShell 5.1 on Windows does not support `&&`).
 
-## Rules of thumb
+| `path` | Behavior |
+| --- | --- |
+| *(omitted)* | Scans **`.`** (current working directory). Run from repo root to cover the tree. |
+| **Directory** | Recursively scans supported sources under that folder (honors `--no-recursive`). |
+| **Single file** | Only that file. Extension must be `.html`, `.htm`, `.vue`, `.pug`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, or `.jsx`. |
 
-- **Aspect ratio:** For undistorted display, match **display ratio** to **intrinsic** (width ÷ height). For crop/letterbox, use **`object-fit`** with explicit size/aspect-ratio.
-- **CLS:** Prefer **`width` and `height`** on `<img>` (or **`aspect-ratio`** when fluid) so space is reserved before paint.
-- **Responsive:** `<picture>` / **`srcset` + `sizes`**; align `type` with AVIF/WebP/JPEG; React uses **`srcSet`**. Use `picture` (and `-s`) to emit multiple width variants if needed.
-- **LCP:** At most one hero: **`fetchPriority="high"`**, **`loading="eager"`**; lazy-load the rest.
-- **Alt:** Describe **what’s in the image** and **how it supports the page** (subject + role in context). **Do not** stack keywords for SEO; empty **`alt=""`** only when the image is decorative.
+**Output:** stdout is **only** pretty-printed JSON: `items[]` with `issues`, `hints`, `snippet`, `intrinsicWidth` / `intrinsicHeight` when metadata was read, plus top-level `summary` and scan metadata. **`--issues-only`** drops rows with empty `issues`. For **`missing_dimensions`**, use **`intrinsicWidth` / `intrinsicHeight`** on the same item and/or the English hint that repeats them.
 
-## Limits
+**Examples:**
 
-Dynamic **`src`** (e.g. `:src` without a static path) → **`needs_manual_review`**. Remote URLs, **`data:`**, and aliases (**`@/`**) → **`cannot_resolve`** until mapped to real paths. The scanner does not fetch network images.
+```bash
+npx lake-cimg@latest scan-code
+npx lake-cimg@latest scan-code /absolute/path/to/src
+npx lake-cimg@latest scan-code /absolute/path/to/about.pug
+```
 
-## CLI
+More flags: `npx lake-cimg@latest scan-code --help` (e.g. `--limit`, `--issues-only`, `--no-recursive`). Prefer an **absolute** `path` if the shell cwd may not be the repo root.
 
-| Command | Role |
-| --- | --- |
-| `npx lake-cimg@latest scan-code <dir>` | Reference audit (JSON default; `--plain` for text) |
-| `npx lake-cimg@latest <path>` | Compress / WebP (`--help` for `-o`, `-s`, `-q`, `-r`) |
-| `npx lake-cimg@latest picture <input> -O <outDir>` | One source → AVIF + WebP + JPEG for `<picture>` |
+## Workflow
 
-`npx lake-cimg@latest --help` — global options. `npx lake-cimg@latest scan-code --help` — `--limit`, `--issues-only`, `--no-recursive`, `--plain`.
+- [ ] **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` (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)).
 
-## Examples
+## Rules of thumb
 
-**Read-only audit (stdout = JSON for parsing):**
+- **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:** **`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.
 
-```bash
-npx lake-cimg@latest scan-code /absolute/path/to/project
-```
+## What the scanner cannot resolve
 
-Use **`--plain`** when you want a short **text** summary in the terminal instead of JSON.
+Dynamic **`src`** without a static path → **`needs_manual_review`**. **`http(s):`**, **`data:`**, and path aliases (**`@/`**, **`~/`**, etc.) → **`cannot_resolve`** (no alias map reads; no network fetch).
 
-## Additional resources
+If **`hints`** mention alias skip: use **`rawRef`** and map the alias via Vite/webpack/tsconfig/Nuxt config. With a **real filesystem path**, run `npx lake-cimg@latest scan <resolved-path>` on assets or re-run **`scan-code`** on markup that uses resolvable relative paths. If unresolved, triage without intrinsic dimensions.
 
-- **Alt text** (decorative `alt=""`, tone, anti-keyword-stuffing): [reference.md — Alt text](reference.md#alt-text)
-- Format choice, responsive `<picture>` patterns, and LCP markup examples: [reference.md](reference.md)
+## Other CLI (after scan-code)
+
+| 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 **when the user wants `<picture>` / multi-format**; not the default if single WebP is enough. |

package/skills/cimg-audit/reference.md

@@ -1,95 +1,49 @@
-# Image optimization reference
+# Image markup templates
 
-Supplement for [SKILL.md](SKILL.md). Browser share figures are **approximate** (global usage trends; check [Can I use](https://caniuse.com/) for current data).
+Supplement for [SKILL.md](SKILL.md). Copy-paste starting points; adjust paths, dimensions, and `sizes` to match your assets and layout.
 
-## Format selection
+## Basic `<img>`
 
-| Format | Use case | Browser support (approx.) |
-| --- | --- | --- |
-| **AVIF** | Photos, best compression | 92%+ |
-| **WebP** | Photos, good fallback | 97%+ |
-| **PNG** | Graphics with transparency | Universal |
-| **SVG** | Icons, logos, illustrations | Universal |
+**When:** Single raster URL; reserve space for CLS. **Check:** `width` / `height` match intrinsic pixels (or use `aspect-ratio` for fluid); meaningful `alt` or `alt=""` if decorative.
 
-Pair with **`lake-cimg`** `picture` subcommand for AVIF + WebP + JPEG from one source when you need stacks; use PNG/SVG where vector or lossless transparency matters.
-
-## Alt text
-
-Write **`alt`** as: **图里是什么 / 与页面主题的关系** — what the image shows and why it belongs on this screen (one concise phrase or sentence).
-
-- **Do:** name the subject, setting, or action that matters; match **language** and **tone** of the page.
-- **Don’t:** repeat the page title, brand slogans, or comma‑separated “SEO” keywords; don’t start with “image of …” unless the medium itself matters (e.g. screenshot vs photo).
+```html
+<img
+  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"
+/>
+```
 
-Decorative visuals: **`alt=""`** and ensure they’re not the only way to convey essential information.
+## `<picture>` + `srcset` + `sizes`
 
-## Responsive images (`<picture>` + `srcset` + `sizes`)
+**When:** AVIF/WebP stack with JPEG (or similar) fallback; responsive widths. **Check:** Each `<source type="…">` matches the real file type; `sizes` matches breakpoints; `<img>` is the final fallback with matching `srcset` / `sizes`.
 
 ```html
 <picture>
-  <!-- AVIF for modern browsers -->
   <source
     type="image/avif"
-    srcset="hero-400.avif 400w,
-            hero-800.avif 800w,
-            hero-1200.avif 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw">
-
-  <!-- WebP fallback -->
+    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">
-
-  <!-- JPEG fallback -->
+    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="Short: what’s shown + why it’s on this page (no keyword stuffing)"
+    alt="Describe subject and purpose on this page"
     loading="lazy"
-    decoding="async">
+    decoding="async"
+  />
 </picture>
 ```
-
-- Match **`sizes`** to real layout breakpoints; generate multiple widths with **`npx lake-cimg@latest picture … -s <px>`** runs or separate exports per width.
-- In **React**, use **`srcSet`** and **`fetchPriority`** (camelCase) on `<img>`.
-
-## LCP image priority
-
-**Above-the-fold LCP candidate** — eager load and high fetch priority:
-
-```html
-<img
-  src="hero.webp"
-  fetchpriority="high"
-  loading="eager"
-  decoding="sync"
-  alt="Hero: subject + role on this page (not SEO keywords)">
-```
-
-**Below-the-fold** — defer work off the critical path:
-
-```html
-<img
-  src="product.webp"
-  loading="lazy"
-  decoding="async"
-  alt="Product: what’s visible + relevance (no keyword list)">
-```
-
-Use **at most one** `fetchpriority="high"` (or `fetchPriority="high"` in React) per route/view for the true LCP image; lazy-load the rest.
-
-## CLI tie-in
-
-| Need | Command |
-| --- | --- |
-| Audit references + intrinsic size vs markup | `npx lake-cimg@latest scan-code <dir>` |
-| One file → AVIF + WebP + JPEG | `npx lake-cimg@latest picture <input> -O <outDir>` |
-
-Full options: repository **README.md** at package root.