lake-cimg 0.0.2 → 1.0.0

package/README.md

@@ -103,24 +103,24 @@ npx lake-cimg@latest picture <input> -O <outDir> [选项]
 
 ### 子命令：`scan-code`（源码中的图片引用）
 
-在 **html / htm / vue / js / mjs / cjs / ts / tsx / jsx** 中查找图片引用（`<img>`、`import … from '…png'`、`new URL('…', import.meta.url)`、`url(…)` 等），将**可解析的本地路径**与 **sharp 读出的真实宽高**对比，只读输出 JSON（默认），用于：
+在 **html / htm / vue / pug / js / mjs / cjs / ts / tsx / jsx** 中查找图片引用（`<img>`、Pug `img(src=…)`、`import … from '…png'`、`new URL('…', import.meta.url)`、`url(…)` 等），将**可解析的本地路径**与 **sharp 读出的真实宽高**对比，只读输出 JSON（默认），用于：
 
 - **CLS**：缺少 `width`/`height` 且无 `aspect-ratio` 等占位
 - **比例**：声明的宽高比与素材像素比不一致（未使用 `object-fit: cover|contain|fill` 等时标为问题）
 - **格式**：对 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

@@ -218,9 +218,9 @@ program
   });
 
 program
-  .command("scan-code <dir>")
+  .command("scan-code [path]")
   .description(
-    "扫描源码中的图片引用（html/vue/js/ts/tsx/jsx），结合像素尺寸给出 CLS / 比例 / 格式建议（只读）"
+    "扫描源码图片引用并输出 JSON 建议（CLS/比例/格式）。path 可为目录或源码文件，省略时为当前目录"
   )
   .option("-r, --recursive", "递归扫描子目录", true)
   .option("--no-recursive", "不递归子目录")
@@ -231,13 +231,10 @@ 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);
+  .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;
     try {
       const result = await scanCodeReferences(root, {
@@ -246,16 +243,7 @@ program
         limit,
         issuesOnly: !!opts.issuesOnly,
       });
-      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/scanCodeReferences.js

@@ -1,5 +1,5 @@
 /**
- * Scan JS/HTML/Vue/TS/TSX/JSX for local image references, join sharp metadata,
+ * Scan JS/HTML/Vue/Pug/TS/TSX/JSX for local image references, join sharp metadata,
  * and flag CLS / aspect ratio / modern-format hints (read-only).
  */
 import { readdir, readFile, stat } from "fs/promises";
@@ -20,6 +20,7 @@ const DEFAULT_SOURCE_EXTS = new Set([
   ".ts",
   ".tsx",
   ".jsx",
+  ".pug",
 ]);
 
 const DEFAULT_EXCLUDE_DIRS = new Set([
@@ -51,6 +52,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
@@ -146,6 +184,133 @@ function parseImgTag(tag) {
   return { srcRaw, srcKind, width, height, style };
 }
 
+/**
+ * Parse Pug `img(src=… width=… height=…)` (one call block).
+ * @param {string} block - e.g. `img(src='a.png' width=300 height=100)`
+ */
+function parsePugImgBlock(block) {
+  let srcRaw = null;
+  let srcKind = null;
+  const srcQuoted = block.match(/\bsrc\s*=\s*["']([^"']*)["']/i);
+  const srcUnquoted = block.match(
+    /\bsrc\s*=\s*([\w./$-]+\.(?:jpg|jpeg|png|webp|gif))\b/i
+  );
+  if (srcQuoted) {
+    const val = srcQuoted[1].trim();
+    if (
+      IMG_EXT_RE.test(val) ||
+      val.startsWith("./") ||
+      val.startsWith("../") ||
+      val.startsWith("/")
+    ) {
+      srcRaw = val.split("?")[0];
+      srcKind = "static";
+    } else {
+      srcKind = "dynamic";
+    }
+  } else if (srcUnquoted) {
+    srcRaw = srcUnquoted[1].split("?")[0];
+    srcKind = "static";
+  } else if (/\bsrc\s*=/i.test(block)) {
+    srcKind = "dynamic";
+  }
+
+  const w1 = block.match(/\bwidth\s*=\s*["']?(\d+)["']?/i);
+  const h1 = block.match(/\bheight\s*=\s*["']?(\d+)["']?/i);
+  const width = w1 ? parseInt(w1[1], 10) : null;
+  const height = h1 ? parseInt(h1[1], 10) : null;
+  const styleMatch = block.match(/\bstyle\s*=\s*["']([^"']*)["']/i);
+  const style = styleMatch ? styleMatch[1] : null;
+
+  return { srcRaw, srcKind, width, height, style };
+}
+
+/**
+ * @param {string} content
+ * @returns {Array<{ index: number, line: number, column: number, rawRef: string, kind: string, context: string, parse: object }>}
+ */
+function extractPugImgRefs(content) {
+  /** @type {Array<{ index: number, line: number, column: number, rawRef: string, kind: string, context: string, parse: object }>} */
+  const refs = [];
+  const re = /\bimg\s*\(/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const startParen = m.index + m[0].length - 1;
+    let depth = 1;
+    let i = startParen + 1;
+    while (i < content.length && depth > 0) {
+      const c = content[i];
+      if (c === "(") {
+        depth++;
+        i++;
+        continue;
+      }
+      if (c === ")") {
+        depth--;
+        i++;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === "`") {
+        const q = c;
+        i++;
+        while (i < content.length) {
+          if (content[i] === "\\") {
+            i += 2;
+            continue;
+          }
+          if (content[i] === q) {
+            i++;
+            break;
+          }
+          i++;
+        }
+        continue;
+      }
+      i++;
+    }
+    const block = content.slice(m.index, i);
+    const index = m.index;
+    const { line, column } = lineColAt(content, index);
+    const parsed = parsePugImgBlock(block);
+
+    if (parsed.srcKind === "dynamic") {
+      refs.push({
+        index,
+        line,
+        column,
+        rawRef: "",
+        kind: "img",
+        context: block.slice(0, 200),
+        parse: { ...parsed, dynamic: true },
+      });
+      continue;
+    }
+    if (!parsed.srcRaw) {
+      refs.push({
+        index,
+        line,
+        column,
+        rawRef: "",
+        kind: "img",
+        context: block.slice(0, 200),
+        parse: { ...parsed, missingSrc: true },
+      });
+      continue;
+    }
+
+    refs.push({
+      index,
+      line,
+      column,
+      rawRef: parsed.srcRaw,
+      kind: "img",
+      context: block.slice(0, 200),
+      parse: parsed,
+    });
+  }
+  return refs;
+}
+
 /**
  * @param {string} ref
  * @param {string} hostDir
@@ -177,12 +342,22 @@ function resolveLocalImageRef(ref, hostDir) {
 /**
  * @param {string} content
  * @param {string} hostDir
+ * @param {string} [sourceExt] - lowercase extension e.g. `.pug` to run Pug `img()` extraction
  * @returns {RawRef[]}
  */
-function extractFromContent(content, hostDir) {
+function extractFromContent(content, hostDir, sourceExt = "") {
   /** @type {RawRef[]} */
   const refs = [];
 
+  if (sourceExt === ".pug") {
+    const pugRefs = extractPugImgRefs(content);
+    for (const r of pugRefs) {
+      refs.push(r);
+    }
+  }
+
+  const pictureModernIntervals = collectPictureModernIntervals(content);
+
   const imgRe = /<img\b[^>]*>/gis;
   let m;
   while ((m = imgRe.exec(content)) !== null) {
@@ -190,6 +365,11 @@ function extractFromContent(content, hostDir) {
     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({
@@ -199,7 +379,11 @@ function extractFromContent(content, hostDir) {
         rawRef: "",
         kind: "img",
         context: tag.slice(0, 200),
-        parse: { ...parsed, dynamic: true },
+        parse: {
+          ...parsed,
+          dynamic: true,
+          ...(pictureHasModernSources ? { pictureHasModernSources: true } : {}),
+        },
       });
       continue;
     }
@@ -211,7 +395,11 @@ function extractFromContent(content, hostDir) {
         rawRef: "",
         kind: "img",
         context: tag.slice(0, 200),
-        parse: { ...parsed, missingSrc: true },
+        parse: {
+          ...parsed,
+          missingSrc: true,
+          ...(pictureHasModernSources ? { pictureHasModernSources: true } : {}),
+        },
       });
       continue;
     }
@@ -223,7 +411,9 @@ function extractFromContent(content, hostDir) {
       rawRef: parsed.srcRaw,
       kind: "img",
       context: tag.slice(0, 200),
-      parse: parsed,
+      parse: pictureHasModernSources
+        ? { ...parsed, pictureHasModernSources: true }
+        : parsed,
     });
   }
 
@@ -315,7 +505,7 @@ async function runPool(tasks, concurrency) {
 }
 
 /**
- * @param {string} rootDir
+ * @param {string} rootDir 扫描根路径：可为**目录**（递归枚举源码）或**单个源码文件**（仅扫描该文件）。传 `.` 表示当前工作目录。
  * @param {{
  *   recursive?: boolean,
  *   cwd?: string,
@@ -364,17 +554,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 = [];
 
@@ -389,7 +588,8 @@ export async function scanCodeReferences(rootDir, options = {}) {
     const relFile = relative(cwd, absPath);
     const displayFile =
       relFile && !relFile.startsWith("..") ? relFile : absPath;
-    const rawRefs = extractFromContent(content, hostDir);
+    const sourceExt = extname(absPath).toLowerCase();
+    const rawRefs = extractFromContent(content, hostDir, sourceExt);
     for (const ref of rawRefs) {
       staged.push({ file: displayFile, absHost: hostDir, ref });
     }
@@ -451,7 +651,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
 
     if (r.parse?.dynamic) {
       issues.push("needs_manual_review");
-      hints.push("Vue/React 动态 :src 或绑定，需人工确认资源与尺寸");
+      hints.push("Vue/React/Pug 动态 src 或绑定，需人工确认资源与尺寸");
       items.push({
         file,
         line: r.line,
@@ -505,7 +705,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);
@@ -564,7 +764,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}`
         );
       }
 
@@ -587,6 +787,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
     }
 
     if (
+      !(r.kind === "img" && r.parse?.pictureHasModernSources) &&
       (ext === ".jpg" ||
         ext === ".jpeg" ||
         ext === ".png" ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lake-cimg",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "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/README.md

@@ -4,7 +4,7 @@ This directory follows the layout expected by **[Skills CLI](https://www.npmjs.c
 
 | Skill | Summary |
 | --- | --- |
-| [cimg-audit](./cimg-audit/SKILL.md) | Audit `<img>` / imports / `url()` for CLS, aspect ratio, and format hints via `npx lake-cimg@latest scan-code` |
+| [cimg-audit](./cimg-audit/SKILL.md) | Audit `<img>` / Pug `img()` / imports / `url()` for CLS, aspect ratio, and format hints via `npx lake-cimg@latest scan-code` |
 
 ### When to use
 

package/skills/cimg-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cimg-audit
 description: >-
-  Audits HTML, Vue, JS, TS, TSX, and JSX image references against intrinsic
+  Audits HTML, Vue, Pug, JS, TS, TSX, and JSX image references against intrinsic
   dimensions for CLS risk, aspect-ratio mismatches, and modern-format hints.
   Use when optimizing images, fixing layout shift, LCP heroes, picture/srcset,
   or running lake-cimg scan-code via npx lake-cimg@latest.
@@ -9,49 +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. More: [reference.md](reference.md#alt-text).
+**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` (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)).
 
-## 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:** `<picture>` and/or **`srcset` + `sizes`**; each `<source type="…">` must match the real file type; Generate width variants with `picture … -s <px>` or separate exports.
+- **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.
 
-- 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 for `<picture>`. |

package/skills/cimg-audit/reference.md

@@ -1,48 +1,39 @@
-# 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
+  src="photo.jpg"
+  width="1200"
+  height="800"
+  alt="Describe subject and purpose on this page"
+  loading="lazy"
+  decoding="async">
+```
 
-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 -->
   <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 -->
   <img
     src="hero-800.jpg"
     srcset="hero-400.jpg 400w,
@@ -51,45 +42,8 @@ Decorative visuals: **`alt=""`** and ensure they’re not the only way to convey
     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">
 </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.