@nitra/cursor 1.8.192 → 1.8.197

package/scripts/check-image-compress.mjs

@@ -0,0 +1,216 @@
+/**
+ * Перевіряє відповідність репозиторію правилу `image-compress.mdc`: канонічний скрипт
+ * `lint-image` для оптимізації raster/SVG через `@nitra/minify-image` ≥ 3.2.0 (локально).
+ *
+ * Очікування:
+ * - у кореневому `package.json` є скрипт `lint-image`, який викликає `npx @nitra/minify-image`
+ *   з обовʼязковими `--src=.` і `--write`. Прапорець `--avif` у `lint-image` заборонений —
+ *   AVIF-генерацію виконує окреме правило `image-avif` (інакше `bun run lint` плодив би `.avif`
+ *   для зображень, що ніде не вживаються);
+ * - якщо в `package.json` є агрегований скрипт `lint`, він викликає `bun run lint-image`
+ *   (симетрично до `lint-text`, `lint-js`, `lint-ga`);
+ * - `@nitra/minify-image` не оголошений у `dependencies`/`devDependencies` —
+ *   CLI запускається лише через `npx` (як `markdownlint-cli2` у `text.mdc`);
+ * - `.n-minify-image.tsv` (committed source of truth з sha1/originalSize/size) НЕ
+ *   в `.gitignore` — він має бути в git. Локальний mtime-кеш у
+ *   `node_modules/.cache/@nitra/minify-image/mtime.tsv` авто-gitignored через `node_modules/`,
+ *   окремої перевірки не вимагає;
+ * - застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений з кореня — інакше
+ *   проєкт лишається у напівпереміщеному стані.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+
+/** Імʼя CLI-пакета: рядок у `lint-image` і заборонений у залежностях. */
+const MINIFY_PACKAGE_NAME = '@nitra/minify-image'
+
+/** Імʼя committed-кешу (sha1 + originalSize + size) у `@nitra/minify-image` ≥ 3.2.0. */
+const HASH_CACHE_FILENAME = '.n-minify-image.tsv'
+
+/** Імʼя застарілого 4-колонкового кешу (`@nitra/minify-image` < 3.2). Має бути видалений після міграції. */
+const LEGACY_CACHE_FILENAME = '.minify-image-cache.tsv'
+
+/**
+ * Перевіряє скрипт `lint-image` у `package.json`.
+ *
+ * Має містити виклик `npx @nitra/minify-image` з обовʼязковими прапорцями `--src=.`
+ * і `--write` (авто-оптимізація на місці). Прапорець `--avif` у `lint-image`
+ * заборонений — AVIF-генерацію виконує `check image-avif`, інакше `bun run lint` плодить
+ * `.avif` для зображень, що ніде не вживаються.
+ * @param {string|undefined} lintImage значення `scripts['lint-image']`
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkLintImageScript(lintImage, pass, fail) {
+  const canonical = `npx ${MINIFY_PACKAGE_NAME} --src=. --write`
+  if (typeof lintImage !== 'string' || !lintImage.trim()) {
+    fail(`package.json: додай скрипт "lint-image" з \`${canonical}\` (image-compress.mdc)`)
+    return
+  }
+  if (!lintImage.includes(`npx ${MINIFY_PACKAGE_NAME}`)) {
+    fail(`package.json: lint-image має викликати \`npx ${MINIFY_PACKAGE_NAME}\` (image-compress.mdc)`)
+    return
+  }
+  /** @type {{ flag: string, variants: string[], hint: string }[]} */
+  const requiredFlags = [
+    { flag: '--src=.', variants: ['--src=.', '--src .'], hint: '`--src=.`' },
+    { flag: '--write', variants: ['--write'], hint: '`--write` (авто-оптимізація на місці)' }
+  ]
+  const missing = requiredFlags.filter(f => !f.variants.some(v => lintImage.includes(v)))
+  if (missing.length > 0) {
+    fail(
+      `package.json: lint-image має містити ${missing.map(f => f.hint).join(', ')} — канонічний виклик: \`${canonical}\` (image-compress.mdc)`
+    )
+    return
+  }
+  if (lintImage.includes('--avif')) {
+    fail(
+      `package.json: прибери \`--avif\` з lint-image — AVIF-генерацію виконує \`npx @nitra/cursor check image-avif\` (image-compress.mdc). Канонічний виклик: \`${canonical}\``
+    )
+    return
+  }
+  pass(`package.json: lint-image викликає \`${canonical}\``)
+}
+
+/**
+ * Перевіряє, що агрегований `lint` (якщо є) кличе `bun run lint-image` —
+ * симетрично до `lint-text`, `lint-js`, `lint-ga`.
+ * @param {string|undefined} lintAggregate значення `scripts.lint`
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkLintAggregateIncludesImage(lintAggregate, pass, fail) {
+  if (typeof lintAggregate !== 'string' || !lintAggregate.trim()) {
+    return
+  }
+  if (lintAggregate.includes('bun run lint-image')) {
+    pass('package.json: агрегований `lint` викликає `bun run lint-image`')
+  } else {
+    fail(
+      'package.json: у `lint` додай `bun run lint-image` (image-compress.mdc, симетрично до lint-text / lint-js / lint-ga)'
+    )
+  }
+}
+
+/**
+ * Забороняє `@nitra/minify-image` у `dependencies` чи `devDependencies` —
+ * CLI завжди запускається через `npx` (як `markdownlint-cli2` у `text.mdc`).
+ * @param {{ dependencies?: Record<string, unknown>, devDependencies?: Record<string, unknown> }} pkg розібраний package.json
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkMinifyImageNotInDeps(pkg, pass, fail) {
+  const inDeps = Boolean(pkg.dependencies && MINIFY_PACKAGE_NAME in pkg.dependencies)
+  const inDevDeps = Boolean(pkg.devDependencies && MINIFY_PACKAGE_NAME in pkg.devDependencies)
+  if (inDeps || inDevDeps) {
+    fail(
+      `package.json: ${MINIFY_PACKAGE_NAME} не додавай у dependencies/devDependencies — лише через \`npx\` (image-compress.mdc)`
+    )
+  } else {
+    pass(`package.json: ${MINIFY_PACKAGE_NAME} не оголошено в dependencies/devDependencies`)
+  }
+}
+
+/**
+ * Зчитує всі змістовні рядки `.gitignore` (без коментарів і порожніх). Якщо файла нема — `null`.
+ * @returns {Promise<string[] | null>} список trim-нутих рядків або `null`
+ */
+async function readGitignoreLines() {
+  if (!existsSync('.gitignore')) return null
+  const raw = await readFile('.gitignore', 'utf8')
+  return raw
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l.length > 0 && !l.startsWith('#'))
+}
+
+/**
+ * Перевіряє, що `.n-minify-image.tsv` НЕ в `.gitignore` — він має бути в git
+ * (split-cache 3.2.0: source of truth для slow-path і lifetime savings).
+ *
+ * Сам факт існування файла НЕ вимагається — на свіжому проєкті без обробки
+ * зображень його ще нема, це нормально.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkHashCacheNotIgnored(pass, fail) {
+  const lines = await readGitignoreLines()
+  if (lines && lines.includes(HASH_CACHE_FILENAME)) {
+    fail(
+      `.gitignore: прибери рядок \`${HASH_CACHE_FILENAME}\` — це закомічений source of truth split-cache 3.2.0 (image-compress.mdc)`
+    )
+  } else {
+    pass(`${HASH_CACHE_FILENAME} не в .gitignore (має бути в git)`)
+  }
+}
+
+/**
+ * Перевіряє, що застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений
+ * з кореня. Якщо лежить — користувач не завершив міграцію на split-cache, що
+ * залишає файл як орфана у git-історії.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkLegacyCacheRemoved(pass, fail) {
+  if (existsSync(LEGACY_CACHE_FILENAME)) {
+    fail(
+      `${LEGACY_CACHE_FILENAME} застарілий (split-cache 3.2.0) — видали: ` +
+        `\`git rm --cached ${LEGACY_CACHE_FILENAME} 2>/dev/null || true && rm -f ${LEGACY_CACHE_FILENAME}\` ` +
+        '(також прибери відповідний рядок з .gitignore, якщо є)'
+    )
+    return
+  }
+  const lines = await readGitignoreLines()
+  if (lines && lines.includes(LEGACY_CACHE_FILENAME)) {
+    fail(`.gitignore: прибери застарілий рядок \`${LEGACY_CACHE_FILENAME}\` — split-cache 3.2.0 його не використовує`)
+    return
+  }
+  pass(`${LEGACY_CACHE_FILENAME} відсутній (міграція на split-cache завершена)`)
+}
+
+/**
+ * Перевіряє кореневий `package.json`: скрипти, заборонені залежності, агрегований `lint`.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<boolean>} `true`, якщо `package.json` знайдено й оброблено; `false` — нема
+ */
+async function checkPackageJsonImage(pass, fail) {
+  if (!existsSync('package.json')) {
+    fail('package.json не знайдено в корені — додай (image-compress.mdc)')
+    return false
+  }
+  const pkg = JSON.parse(await readFile('package.json', 'utf8'))
+  const scripts = /** @type {Record<string, unknown>} */ (pkg.scripts || {})
+  checkLintImageScript(typeof scripts['lint-image'] === 'string' ? scripts['lint-image'] : undefined, pass, fail)
+  checkLintAggregateIncludesImage(typeof scripts.lint === 'string' ? scripts.lint : undefined, pass, fail)
+  checkMinifyImageNotInDeps(pkg, pass, fail)
+  return true
+}
+
+/**
+ * Перевіряє відповідність проєкту правилу `image-compress.mdc`: канонічний `lint-image`
+ * (через `npx @nitra/minify-image --src=. --write`, без `--avif`!), агрегований `lint`,
+ * `@nitra/minify-image` не у залежностях, `.n-minify-image.tsv` НЕ в `.gitignore`,
+ * застарілий `.minify-image-cache.tsv` видалений. CI-workflow для image не вимагається —
+ * лінт зображень виконується лише локально.
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  const pkgFound = await checkPackageJsonImage(pass, fail)
+  if (pkgFound) {
+    await checkHashCacheNotIgnored(pass, fail)
+    await checkLegacyCacheRemoved(pass, fail)
+  }
+
+  return reporter.getExitCode()
+}

package/scripts/check-js-run.mjs

@@ -358,7 +358,7 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
  */
 function checkDepcheckInWorkflows(rootDir, workflows, label, fail, passFn) {
   if (workflows.length === 0) return
-  const violations = findDepcheckViolationsForPackage(workflows, rootDir.replace(/\\/g, '/'))
+  const violations = findDepcheckViolationsForPackage(workflows, rootDir.replaceAll('\\', '/'))
   if (violations.length === 0) {
     passFn(`${label}depcheck у path-scoped workflow налаштовано (або відсутній path-scoped workflow для пакета)`)
     return

package/scripts/utils/depcheck-workflow.mjs

@@ -37,7 +37,7 @@ const IGNORES_FLAG_RE = /--ignores\s*=?\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))/u
  * @returns {boolean} `true`, якщо знайдено хоча б один підходящий glob
  */
 export function workflowHasPathsScopedToPackage(root, pkgRoot) {
-  const prefix = `${pkgRoot.replace(/\\/g, '/').replace(/\/+$/, '')}/`
+  const prefix = `${pkgRoot.replaceAll('\\', '/').replace(/\/+$/, '')}/`
   const on = root?.on
   if (!on || typeof on !== 'object') return false
   for (const event of /** @type {const} */ (['push', 'pull_request'])) {
@@ -85,8 +85,8 @@ export function extractDepcheckArgs(runText) {
 export function stepWorkingDirectoryEquals(step, pkgRoot) {
   const wd = step['working-directory']
   if (typeof wd !== 'string') return false
-  const norm = wd.replace(/\\/g, '/').replace(/\/+$/, '')
-  const expected = pkgRoot.replace(/\\/g, '/').replace(/\/+$/, '')
+  const norm = wd.replaceAll('\\', '/').replace(/\/+$/, '')
+  const expected = pkgRoot.replaceAll('\\', '/').replace(/\/+$/, '')
   return norm === expected
 }
 

package/mdc/image.mdc

@@ -1,96 +0,0 @@
----
-description: Оптимізація зображень через @nitra/minify-image у локальному lint
-alwaysApply: true
-version: '1.5'
----
-
-CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (≥ **3.2.0**) запускається через `npx` (як `markdownlint-cli2` у text.mdc) і **не** додається в `dependencies` / `devDependencies`. Канонічний `lint-image` — авто-оптимізація з прапорцем `--write`: стискає raster/SVG на місці. **AVIF-генерація (`--avif`) у `lint-image` заборонена** — її виконує лише `npx @nitra/cursor check image`, який заодно прибирає AVIF-сироти (див. секцію «AVIF-імпорти у `.vue`»). Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
-
-Перевірка лише локальна — у CI `lint-image` не запускаємо (sharp/svgo тягнуть бінарні залежності, цінність на ubuntu-runner-ах нижча за час прогону). Окремий workflow `lint-image.yml` створювати не треба.
-
-## `package.json`
-
-```json title="package.json"
-{
-  "scripts": {
-    "lint": "bun run lint-js && bun run lint-text && bun run lint-ga && bun run lint-image && oxfmt .",
-    "lint-image": "npx @nitra/minify-image --src=. --write"
-  }
-}
-```
-
-Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення.
-
-## Split-cache
-
-Починаючи з `@nitra/minify-image` **3.2.0** кеш розбитий на два файли з різною семантикою:
-
-### `.n-minify-image.tsv` — source of truth у git
-
-У корені сканованого каталогу. Формат: `<rel-path>\t<sha1-hex>\t<originalSize>\t<size>`.
-
-Slow-path і джерело даних для `Project lifetime savings`. **Має бути в git** — після `git clone` чи `git checkout` (mtime скидається на час checkout-у) CLI читає файл, рахує SHA-1 і порівнює зі збереженим у TSV хешем; на match локальний mtime-кеш зігрівається без reprocess. Рядки відсортовані алфавітно, hash і size змінюються лише при реальній зміні контенту — diff чистий.
-
-### `node_modules/.cache/@nitra/minify-image/mtime.tsv` — локальний fast-path
-
-Формат: `<rel-path>\t<mtime>\t<size>`. При збігу `(size, mtime)` CLI пропускає файл без читання — константа per-file.
-
-Лежить під `node_modules/`, тож **авто-gitignored** за конвенцією JS-tooling-у (так кешуються ESLint, Babel, webpack, Turbo). Окремий рядок у `.gitignore` не потрібен. `rm -rf node_modules` зносить — наступний запуск відновлює його через slow-path проти `.n-minify-image.tsv`, без reprocess.
-
-### Міграція з versions < 3.2
-
-Старий єдиний `.minify-image-cache.tsv` (4 колонки `path\tmtime\toriginalSize\tsize`, зазвичай у `.gitignore`) автоматично читається при першому запуску для seed-у `originalSize` у `.n-minify-image.tsv` (lifetime savings не скидається). Після цього старий файл видаляють вручну:
-
-```bash
-git rm --cached .minify-image-cache.tsv 2>/dev/null || true
-rm -f .minify-image-cache.tsv
-# прибери відповідний рядок з .gitignore, якщо був
-```
-
-AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).
-
-## AVIF-імпорти у `.vue`
-
-AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor check image` — у `lint-image` прапорець `--avif` заборонений (інакше `bun run lint` плодить непотрібні `.avif` для зображень, що ніде не використовуються). Перевірка робить три кроки в порядку:
-
-1. Запускає `npx @nitra/minify-image --src=. --write --avif` — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF.
-2. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
-   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
-   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
-3. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости».
-
-```vue title="App.vue (після check image)"
-<script setup>
-import welcomeImage from './assets/welcome.png.avif'
-</script>
-
-<template>
-  <img :src="welcomeImage" alt="Welcome" />
-</template>
-```
-
-Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
-
-Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image` падає з помилкою на конкретний файл, як раніше.
-
-### Опт-аут для конкретного пакета
-
-У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл, де AVIF-підтримка не гарантована), додай у `package.json` цього пакета:
-
-```json title="apps/mobile/package.json"
-{
-  "@nitra/minify-image": {
-    "disable-avif": true
-  }
-}
-```
-
-Тоді перевірка пропускає `.vue` файли цього пакета. У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
-
-## Заборонені залежності
-
-`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
-
-## Перевірка
-
-`npx @nitra/cursor check image` (охоплює `lint-image` з обовʼязковими `--src=.`, `--write` і **забороненим** `--avif`; агрегований `lint`; `.n-minify-image.tsv` НЕ в `.gitignore` — має бути в git; відсутність застарілого `.minify-image-cache.tsv` у корені; запуск AVIF-генерації + авто-заміна raster-посилань на `.avif` у `.vue`/`.html` кожного workspace-пакета + прибирання AVIF-сиріт).