CLI — отчёт об использовании

npx vue-image-kit scan обходит весь проект и показывает, как используется vue-image-kit: откуда берётся каждое изображение, какие пропсы VImage задействованы и что стоит исправить — нет alt, нет размеров, нет плейсхолдера, файл не существует.

npx vue-image-kit scan

Ничего, кроме самого vue, не требуется — .vue-файлы разбираются собственным vue/compiler-sfc проекта.

Что находит команда

• <VImage> в шаблонах — как VImage или v-image, либо под локальным алиасом импорта (import { VImage as Img } from '@macrulez/vue-image-kit'). VImage, импортированный из другой библиотеки, игнорируется.
• <VImage> в JSX/TSX и в render-функциях h(VImage, …).
• Директивы v-lazy-img, в том числе переименованные локально.
• Вызовы useImage() и useBackgroundImage(). Одноимённый composable из другого пакета (например, useImage из VueUse) игнорируется; вызов вообще без импорта (автоимпорты Nuxt) учитывается.

Каждый проп записывается со значением, если его можно определить статически — строковый или числовой литерал, const из того же файла, импортированный файл, — а иначе как исходное выражение.

Источники изображений

Каждое использование получает один тип источника:

• public — абсолютный путь вроде /images/hero.jpg, раздаваемый из public/. Файл ищется на диске.
• local-import — изображение, импортированное в компонент (import hero from '@/assets/hero.jpg'). Алиасы берутся из paths в tsconfig, resolve.alias в vite.config и умолчаний Vue/Nuxt (@ → src; ~/@ → исходная папка Nuxt).
• cdn:<провайдер> — URL на одном из CDN, которые распознаёт autoLoader(), например cdn:cloudinary.
• remote — любой другой URL http(s)://.
• vik — метаданные сборки: :image, привязанный к импорту ?vik или к записи манифеста из generate.
• server — путь, отдаваемый через self-hosted сервер (loader="server").
• data-uri — встроенный URL data:.
• dynamic — значение, известное только во время выполнения, например item.src внутри v-for.

Объект SrcSet ({ avif, webp, fallback }) классифицируется по его fallback.

Отчёт

[vue-image-kit] scan — 8 usages in 1 file (2 scanned)

By source
  Source        Usages  VImage  w/ size  w/ placeholder  eager
  ────────────  ──────  ──────  ───────  ──────────────  ─────
  public             5       5        2               1      0
  dynamic            1       1        0               0      0
  local-import       1       1        0               0      0
  remote             1       1        0               0      0

Files
  File         Usages  VImage  v-lazy-img  composables
  ───────────  ──────  ──────  ──────────  ───────────
  src/App.vue       8       8           0            0

VImage props
  alt 8 · src 8 · height 2 · width 2 · blurhash 1 · sizes 1

Warnings
     6 × no-dimensions — no width/height — the browser cannot reserve space (layout shift)
         src/App.vue:10
         src/App.vue:16
         src/App.vue:17
         … 3 more (use --details)
     7 × no-placeholder — no placeholder (hazehash/blurhash/thumbhash/placeholder/placeholderColor)
         …
     1 × missing-file — referenced file does not exist
         src/App.vue:21

  5 usages without a placeholder can be filled in by `vue-image-kit placeholders`.
  1 usage has a source that can't be resolved statically (shown as "dynamic").

• By source — использования по типу источника; для VImage — сколько из них с размерами (width + height или image), с плейсхолдером и с немедленной загрузкой (priority или :lazy="false").
• Files — файлы с наибольшим числом использований (количество задаёт --top).
• VImage props — как часто используется каждый проп VImage; обычные атрибуты вроде class или key не учитываются.
• Warnings — предупреждения, сгруппированные по коду, с первыми местами для каждого.

Предупреждения

• missing-alt — VImage без alt.
• empty-alt — alt="", допустимо только для чисто декоративных изображений.
• no-dimensions — нет ни width/height, ни image (и это не layout="fill"), поэтому браузер не может заранее зарезервировать место.
• no-placeholder — нет ни hazehash, ни blurhash, ни thumbhash, ни placeholder, ни placeholderColor, ни image, ни placeholderMode="color"/"shimmer".
• missing-file — путь из public/ или локальный импорт указывает на несуществующий файл.
• multiple-priority — больше одного изображения с priority в одном файле.
• widths-without-sizes — widths без sizes и без width, поэтому браузер считает, что изображение занимает всю ширину экрана.
• local-without-vik — локальное изображение импортировано без ?vik; Vite-плагин дал бы ему размеры и плейсхолдер на этапе сборки.

Использование, которое передаёт пропсы через spread (v-bind="attrs"), пропускает проверки по пропсам — их нельзя определить статически.

Опции

• --root <dir> · по умолчанию: текущая папка. Корень проекта для сканирования.
• --include <globs> · по умолчанию: **/*.{vue,js,jsx,ts,tsx,mjs,mts,cjs,cts}. Glob-шаблоны файлов через запятую.
• --exclude <globs> — дополнительные glob-шаблоны для пропуска через запятую. node_modules, dist, .nuxt, .output, coverage, *.d.ts и тестовые файлы (*.test.*, *.spec.*) пропускаются всегда.
• --public-dir <dir> · по умолчанию: public. Где искать пути вида /….
• --alias <key=path> — алиас пути, можно указывать несколько раз (--alias @=src). Добавляется к алиасам из tsconfig и vite.config.
• --package <name> — дополнительное имя пакета, которое считать vue-image-kit; можно указывать несколько раз — для проекта, импортирующего пакет через собственный алиас.
• --no-vite-config — не загружать vite.config для чтения resolve.alias.
• --details — дополнительно вывести каждое использование и все места для каждого предупреждения.
• --top <n> · по умолчанию: 10. Сколько файлов показывать в таблице файлов.
• --format <fmt> · по умолчанию: table. table, json, md или csv.
• --out <file> — записать отчёт в файл вместо терминала.
• --fail-on <codes> — завершиться с кодом 1, если найдено хотя бы одно из этих предупреждений; коды через запятую или any.

Пример — отчёт в Markdown и проверка в CI:

npx vue-image-kit scan --details --format md --out image-report.md
npx vue-image-kit scan --fail-on missing-alt,missing-file

--format json записывает сводку, все предупреждения и каждое использование с пропсами и источником; --format csv — по одной строке на использование.

Файл конфигурации

Те же настройки можно задать в секции scan файла vue-image-kit.config.js:

// vue-image-kit.config.js
export default {
  scan: {
    include: ['src/**/*.{vue,ts}'],
    exclude: ['src/legacy/**'],
    publicDir: 'static',
    aliases: { '#img': './src/assets/images' },
    packageNames: ['image-kit'],
    viteConfig: false,
  },
}