@nitra/cursor 1.8.184 → 1.8.188

package/CHANGELOG.md

@@ -4,6 +4,42 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.188] - 2026-05-07
+
+### Changed
+
+- `vue` (mdc v1.6 → v1.7): для Volar/асетів канонічно лише **`jsconfig.json`** у корені пакета — прибрано альтернативу з `tsconfig.json`. `check-vue.mjs`: перевіряється лише наявність `jsconfig.json`.
+
+## [1.8.187] - 2026-05-07
+
+### Added
+
+- `check-vue.mjs`: перевірка `src/vite-env.d.ts` з `/// <reference types="vite/client" />` та наявності `jsconfig.json` або `tsconfig.json` у корені кожного Vue-пакета (типи для імпортів асетів у `.vue`).
+
+### Changed
+
+- `vue` (mdc v1.5 → v1.6): секція **«Vite client types (Volar, імпорти асетів)»** — обов’язкові `vite-env.d.ts`, jsconfig/tsconfig; застереження щодо вузького `compilerOptions.types`. Оновлено блок **«Перевірка»**.
+
+## [1.8.186] - 2026-05-07
+
+### Added
+
+- `check-js-run.mjs` + `scripts/utils/promise-settimeout-scan.mjs`: програмна перевірка нової секції js-run «Паузи через setTimeout». AST-сканер на `oxc-parser` ловить `new Promise(resolve => setTimeout(resolve, ms))` (з `await` чи без, arrow та function expression, concise та block body, тривіально загорнутий callback `() => resolve()`). Паттерни з передачею значення (`r => setTimeout(() => r(value), ms)`), іншим callback-ом замість resolve, або з додатковими стейтментами в блоці — поза правилом (це не «чиста» пауза).
+- `tests/promise-settimeout-scan.test.mjs`: 13 модульних тестів (await/без, block-body, function expression, обгорнутий callback, false-positive guards, multiline номер рядка, кілька входжень, фільтр розширень).
+- `tests/check-js-run-fixture.test.mjs`: 2 інтеграційні кейси на `check()` — fail при `await new Promise(r => setTimeout(r, ms))` у workspace-пакеті, pass при `await setTimeout(ms)` з `node:timers/promises`.
+
+### Changed
+
+- `js-run` (mdc v1.3 → v1.4): додано секцію **«Паузи через setTimeout»** — заборонено `await new Promise(resolve => setTimeout(resolve, ms))`, замість цього треба `await setTimeout(ms)` з `node:timers/promises`. Зауваження про затінення глобального `setTimeout` у тому ж файлі (за потреби callback-варіант імпортувати під іншим іменем, наприклад `setTimeoutCb` з `node:timers`).
+
+## [1.8.185] - 2026-05-06
+
+### Changed
+
+- `image` (mdc v1.4 → v1.5): прапорець `--avif` у `lint-image` тепер **заборонений** (інакше `bun run lint` плодив би `.avif` для зображень, що ніде не вживаються); канонічний `lint-image` — `npx @nitra/minify-image --src=. --write`. AVIF-генерацію виконує **виключно** `npx @nitra/cursor check image`. Секцію «AVIF-імпорти у `.vue`» переписано: тепер вона документує триетапну логіку `check image` — (1) запуск `npx @nitra/minify-image --src=. --write --avif`, (2) авто-заміна raster-посилань у `.vue`/`.html` на `.avif` у кожному workspace-пакеті, (3) прибирання AVIF-сиріт (файли `.avif` без жодного посилання у `.vue`/`.html` видаляються — AVIF лишається лише там, де заміна реально вдалася).
+- `check-image.mjs`: `checkLintImageScript` більше не вимагає `--avif`, натомість фейлить за його наявністю; додано `runAvifGeneration` (best-effort `npx ... --avif`, опт-аут через `NITRA_CURSOR_NO_AVIF_RUN=1` для тестів), `cleanupOrphanAvifs` (видаляє `<...>.avif` без живого посилання), `hasAnyRasterImage`, `resolveImagePath`. `checkVueAvifImportsInPackage` тепер не лише валідує, а й переписує raster-посилання на `.avif` (коли AVIF-двійник реально існує на диску); якщо `.avif` нема — фейл, як раніше. Сканування поширено на `.html` файли (раніше було тільки `.vue`).
+- `tests/check-image.test.mjs`: `CANONICAL_LINT_IMAGE` без `--avif`; кейс «без `--avif`» перейменовано/перекинуто на «з забороненим `--avif`»; додано тести на orphan-cleanup (`.avif` без посилань видаляється) та авто-заміну raster-імпорту, коли `.avif`-сусід реально існує.
+
 ## [1.8.184] - 2026-05-06
 
 ### Added

package/mdc/image.mdc

@@ -1,10 +1,10 @@
 ---
 description: Оптимізація зображень через @nitra/minify-image у локальному lint
 alwaysApply: true
-version: '1.4'
+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 --avif`: стискає raster/SVG на місці й створює AVIF-двійники (`<name>.<ext>.avif`) поряд з кожним PNG/JPEG/GIF. Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
+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` створювати не треба.
 
@@ -14,12 +14,12 @@ CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (
 {
   "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 --avif"
+    "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`, перед фіксацією одразу бачить, чи зросли зображення, і отримує свіжі AVIF-двійники.
+Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення.
 
 ## Split-cache
 
@@ -47,13 +47,19 @@ rm -f .minify-image-cache.tsv
 # прибери відповідний рядок з .gitignore, якщо був
 ```
 
-AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від `--avif` втрачається на чистому checkout-і).
+AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).
 
 ## AVIF-імпорти у `.vue`
 
-Раз `--avif` гарантує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF, у `.vue` файлах потрібно посилатись саме на AVIF-двійник, а не на оригінал:
+AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor check image` — у `lint-image` прапорець `--avif` заборонений (інакше `bun run lint` плодить непотрібні `.avif` для зображень, що ніде не використовуються). Перевірка робить три кроки в порядку:
 
-```vue title="App.vue (правильно)"
+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>
@@ -63,19 +69,10 @@ import welcomeImage from './assets/welcome.png.avif'
 </template>
 ```
 
-```vue title="App.vue (неправильно — втрачає AVIF)"
-<script setup>
-import welcomeImage from './assets/welcome.png'
-</script>
-```
-
-Перевірка `check image` сканує `.vue` файли в кожному workspace-пакеті (root + workspaces) і вимагає AVIF-двійник для двох форм:
-
-1. **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні).
-2. **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
-
 Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
 
+Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image` падає з помилкою на конкретний файл, як раніше.
+
 ### Опт-аут для конкретного пакета
 
 У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл, де AVIF-підтримка не гарантована), додай у `package.json` цього пакета:
@@ -92,8 +89,8 @@ import welcomeImage from './assets/welcome.png'
 
 ## Заборонені залежності
 
-`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write --avif`).
+`@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-імпорти у `.vue` файлах кожного workspace-пакета).
+`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-сиріт).

package/mdc/js-run.mdc

@@ -1,7 +1,7 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.3'
+version: '1.4'
 ---
 
 ## Область застосування
@@ -136,6 +136,18 @@ console.log(env.OPTIONAL_ENV_VAR)
 `// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
 (escape-hatch для legacy-коду, не для нових файлів).
 
+## Паузи через setTimeout
+
+Заборонено робити паузи через `await new Promise(resolve => setTimeout(resolve, ms))` — таку обгортку треба замінити на promise-варіант `setTimeout` з `node:timers/promises`:
+
+```javascript title="Замість new Promise + setTimeout"
+import { setTimeout } from 'node:timers/promises'
+
+await setTimeout(500)
+```
+
+Імпорт `setTimeout` з `node:timers/promises` затіняє глобальний таймер у файлі — якщо в тому ж файлі потрібен callback-варіант, імпортуй його під іншим іменем (наприклад, `import { setTimeout as setTimeoutCb } from 'node:timers'`).
+
 ## depcheck у GitHub Actions з path-фільтром
 
 Якщо в `.github/workflows/*.yml` є тригер з `paths:`, який обмежує запуск workflow змінами в каталозі конкретного backend-пакета, в job цього workflow має бути крок `npx depcheck` з `working-directory`, який вказує на той самий каталог пакета. Це гарантує, що декларація залежностей у `package.json` пакета відповідає реальним імпортам — інакше можна випадково зламати білд після видалення «зайвої» залежності, яка насправді використовується через побічний імпорт.

package/mdc/vue.mdc

@@ -1,7 +1,7 @@
 ---
 description: Vue
 alwaysApply: true
-version: '1.5'
+version: '1.7'
 ---
 
 # Vue 3 Composition API — правила для .cursorrules
@@ -208,6 +208,45 @@ export default defineConfig({
 })
 ```
 
+## Vite client types (Volar, імпорти асетів)
+
+Без типів **Vite** редактор (Volar / TypeScript) не знає, що імпорт статичного файлу (`import url from './hero.avif'`, `*.png`, `*.svg` тощо) відповідає модулю з `string` URL. Тоді у `.vue` з’являється помилка на кшталт **Cannot find module '…' or its corresponding type declarations**.
+
+У **кожному** workspace-пакеті з **Vue + Vite** обов’язково:
+
+1. **`src/vite-env.d.ts`** — рівно з посиланням на клієнтські типи Vite (одного рядка достатньо):
+
+```ts title="src/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+Так підтягуються декларації з `vite/client.d.ts` (`declare module '*.avif'`, `*.png`, …).
+
+2. **Корінь пакета:** **`jsconfig.json`** із **`include`**, що охоплює `src` (наприклад `"include": ["src/**/*"]`), щоб мова служби бачила `vite-env.d.ts` і SFC.
+
+Мінімальний приклад для JS-пакета:
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowJs": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Не** звужуй без потреби **`compilerOptions.types`** до `["vite/client"]`: це може відрізати інші пакети з `@types` і зламати інші підказки. Достатньо `/// <reference types="vite/client" />` у `vite-env.d.ts` і коректного `include`.
+
 ## Тести
 
 Проекту повинен бути покритий тестами E2E за допомогою Playwright.
@@ -287,4 +326,4 @@ import path from 'node:path'
 
 ## Перевірка
 
-`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, а також обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/scripts/utils/vue-forbidden-imports.mjs`).
+`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/scripts/utils/vue-forbidden-imports.mjs`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.184",
+  "version": "1.8.188",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/check-image.mjs

@@ -4,7 +4,9 @@
  *
  * Очікування:
  * - у кореневому `package.json` є скрипт `lint-image`, який викликає `npx @nitra/minify-image`
- *   з обовʼязковими `--src=.`, `--write` і `--avif` (авто-оптимізація з AVIF-двійниками);
+ *   з обовʼязковими `--src=.` і `--write`. Прапорець `--avif` у `lint-image` заборонений —
+ *   AVIF-генерацію виконує `check image` (інакше `bun run lint` плодив би `.avif` для
+ *   зображень, що ніде не вживаються);
  * - якщо в `package.json` є агрегований скрипт `lint`, він викликає `bun run lint-image`
  *   (симетрично до `lint-text`, `lint-js`, `lint-ga`);
  * - `@nitra/minify-image` не оголошений у `dependencies`/`devDependencies` —
@@ -14,15 +16,25 @@
  *   `node_modules/.cache/@nitra/minify-image/mtime.tsv` авто-gitignored через `node_modules/`,
  *   окремої перевірки не вимагає;
  * - застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений з кореня — інакше
- *   проєкт лишається у напівпереміщеному стані;
- * - у `.vue` файлах raster-імпорти (`.png` / `.jpg` / `.jpeg` / `.gif`) посилаються на
- *   AVIF-двійники (`...png.avif` тощо), оскільки `--avif` гарантує їх наявність поряд із
- *   оригіналами. Можна вимкнути на рівні воркспейс-пакета через `"@nitra/minify-image": {
- *   "disable-avif": true }` у його `package.json`.
+ *   проєкт лишається у напівпереміщеному стані.
+ *
+ * Дії під час `check image` (на додачу до валідацій):
+ * 1. `npx @nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
+ * 2. У кожному workspace-пакеті переписує raster-посилання у `.vue`/`.html` на `.avif`
+ *    (де AVIF-двійник реально існує на диску). Pakety з `"@nitra/minify-image": {
+ *    "disable-avif": true }` у `package.json` пропускаються.
+ * 3. Прибирає AVIF-сироти — `<name>.<ext>.avif`, на які не лишилось жодного посилання
+ *    у `.vue`/`.html` репозиторію, видаляються (умова правила: «AVIF лишається лише
+ *    там, де заміна вдалася»).
+ *
+ * Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу
+ * нема на диску → `.avif` теж не згенерувався) — фейл на конкретний файл, як раніше.
  */
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readFile, unlink, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { env } from 'node:process'
 
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
@@ -58,19 +70,28 @@ const VUE_RASTER_IMPORT_RE = /import\s+\w[\w$]*\s+from\s+['"]([^'"\n]+\.(?:png|j
  */
 const VUE_RASTER_STATIC_SRC_RE = /(?<![:\-_.])\bsrc\s*=\s*['"]([^'"\s]+\.(?:png|jpe?g|gif))['"]/giu
 
+/**
+ * Регексп для готових AVIF-посилань у `.vue`/`.html` (як `import x from '...png.avif'`,
+ * так і `<img src="....png.avif" />`). Потрібен лише для збору множини «живих» AVIF —
+ * щоб після авто-заміни знати, які `<...>.avif` файли ще на щось посилаються, а які
+ * є сиротами і підлягають видаленню.
+ */
+const VUE_AVIF_REF_RE = /['"]([^'"\s]+\.(?:png|jpe?g|gif)\.avif)['"]/giu
+
 /**
  * Перевіряє скрипт `lint-image` у `package.json`.
  *
- * Має містити виклик `npx @nitra/minify-image` з обовʼязковими прапорцями `--src=.`,
- * `--write` (авто-оптимізація на місці) і `--avif` (AVIF-двійники для PNG/JPEG/GIF).
- * Без `--write`/`--avif` лінт лише оцінює економію — для проєктних коммітів цього мало.
+ * Має містити виклик `npx @nitra/minify-image` з обовʼязковими прапорцями `--src=.`
+ * і `--write` (авто-оптимізація на місці). Прапорець `--avif` у `lint-image`
+ * заборонений — AVIF-генерацію виконує `check image`, інакше `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 --avif`
+  const canonical = `npx ${MINIFY_PACKAGE_NAME} --src=. --write`
   if (typeof lintImage !== 'string' || !lintImage.trim()) {
     fail(`package.json: додай скрипт "lint-image" з \`${canonical}\` (image.mdc)`)
     return
@@ -82,8 +103,7 @@ function checkLintImageScript(lintImage, pass, fail) {
   /** @type {{ flag: string, variants: string[], hint: string }[]} */
   const requiredFlags = [
     { flag: '--src=.', variants: ['--src=.', '--src .'], hint: '`--src=.`' },
-    { flag: '--write', variants: ['--write'], hint: '`--write` (авто-оптимізація на місці)' },
-    { flag: '--avif', variants: ['--avif'], hint: '`--avif` (AVIF-двійники для PNG/JPEG/GIF)' }
+    { flag: '--write', variants: ['--write'], hint: '`--write` (авто-оптимізація на місці)' }
   ]
   const missing = requiredFlags.filter(f => !f.variants.some(v => lintImage.includes(v)))
   if (missing.length > 0) {
@@ -92,6 +112,12 @@ function checkLintImageScript(lintImage, pass, fail) {
     )
     return
   }
+  if (lintImage.includes('--avif')) {
+    fail(
+      `package.json: прибери \`--avif\` з lint-image — AVIF-генерацію виконує \`npx @nitra/cursor check image\` (image.mdc). Канонічний виклик: \`${canonical}\``
+    )
+    return
+  }
   pass(`package.json: lint-image викликає \`${canonical}\``)
 }
 
@@ -207,56 +233,111 @@ function packageHasAvifDisabled(pkg) {
 }
 
 /**
- * Сканує `.vue` файли одного workspace-пакета на raster-імпорти, що ще не використовують `.avif`.
+ * Резолвить шлях зображення з імпорта/атрибуту відносно файла, що його містить, до абсолютного
+ * шляху файла на диску. Шляхи, що не починаються з `.` чи `/`, не резолвимо (alias-resolver
+ * Vite/тощо невідомий тут — залишаємо такі посилання як є).
+ * @param {string} importPath шлях у `import x from '...'` або `src="..."`
+ * @param {string} sourceAbsPath абсолютний шлях файла з посиланням
+ * @returns {string|null} абсолютний шлях зображення або `null`, якщо резолвити не можемо
+ */
+function resolveImagePath(importPath, sourceAbsPath) {
+  if (importPath.startsWith('.')) {
+    return join(sourceAbsPath, '..', importPath)
+  }
+  if (importPath.startsWith('/')) {
+    return join(process.cwd(), importPath)
+  }
+  return null
+}
+
+/**
+ * Сканує `.vue` і `.html` файли одного workspace-пакета: де можемо, переписує raster-посилання
+ * на `<path>.avif`, де не можемо — фейлимо. Повертає множину `.avif`-двійників, на які
+ * лишилось живе посилання після проходу — потрібно для подальшого прибирання сиріт.
+ *
+ * Заміна виконується ТІЛЬКИ якщо AVIF-двійник реально існує на диску. Якщо AVIF немає
+ * (наприклад, оригіналу теж немає, тож `--avif` його не згенерував) — фейл, як раніше.
  *
  * Файли, що належать іншим workspace-пакетам, ігноруються — кожен пакет перевіряється рівно
  * один раз (інакше при обході кореня `.` ми б повторно зайшли в `demo/` і подвоїли звіти).
  * @param {string} packageRoot відносний шлях до кореня пакета (наприклад `'.'` або `'demo'`)
  * @param {string[]} otherRootsAbs абсолютні шляхи інших workspace-коренів — їх піддерева пропускаємо
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`, що мають
+ * хоч одне посилання у `.vue`/`.html` (доповнюється у цій функції)
  * @param {(msg: string) => void} pass callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<void>} резолвиться по завершенню перевірки одного пакета
  */
-async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, pass, fail) {
+async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, usedAvifAbs, pass, fail) {
   const absRoot = join(process.cwd(), packageRoot)
   const label = packageRoot === '.' ? 'корінь' : packageRoot
   /** @type {string[]} */
-  const vueFiles = []
+  const targetFiles = []
   await walkDir(
     absRoot,
     absPath => {
-      if (!absPath.endsWith('.vue')) return
+      if (!absPath.endsWith('.vue') && !absPath.endsWith('.html')) return
       if (otherRootsAbs.some(other => absPath.startsWith(`${other}/`))) return
-      vueFiles.push(absPath)
+      targetFiles.push(absPath)
     },
     ignorePaths
   )
-  if (vueFiles.length === 0) return
+  if (targetFiles.length === 0) return
 
   let violations = 0
-  for (const absPath of vueFiles) {
+  let replacements = 0
+  for (const absPath of targetFiles) {
     const rel = relative(process.cwd(), absPath).split('\\').join('/')
-    const content = await readFile(absPath, 'utf8')
-    for (const match of content.matchAll(VUE_RASTER_IMPORT_RE)) {
-      violations++
-      const importPath = match[1]
-      fail(
-        `[${label}] ${rel}: import з '${importPath}' має посилатись на AVIF-двійник '${importPath}.avif' ` +
-          `(lint-image --avif створює його поряд). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
-      )
+    const original = await readFile(absPath, 'utf8')
+    let updated = original
+
+    /**
+     * @param {RegExp} regex з групою 1 = шлях до зображення
+     * @param {(srcPath: string) => string} renderFailure повідомлення помилки
+     */
+    const processMatches = (regex, renderFailure) => {
+      updated = updated.replaceAll(regex, (full, importPath) => {
+        const newImportPath = `${importPath}.avif`
+        const replaced = full.replace(importPath, newImportPath)
+        const imageAbs = resolveImagePath(importPath, absPath)
+        if (imageAbs && existsSync(`${imageAbs}.avif`)) {
+          replacements++
+          usedAvifAbs.add(`${imageAbs}.avif`)
+          return replaced
+        }
+        violations++
+        fail(renderFailure(importPath))
+        return full
+      })
     }
-    for (const match of content.matchAll(VUE_RASTER_STATIC_SRC_RE)) {
-      violations++
-      const srcPath = match[1]
-      fail(
+
+    processMatches(
+      VUE_RASTER_IMPORT_RE,
+      importPath =>
+        `[${label}] ${rel}: import з '${importPath}' має посилатись на AVIF-двійник '${importPath}.avif' ` +
+        `(\`npx @nitra/cursor check image\` створює його поряд, якщо оригінал є на диску). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+    )
+    processMatches(
+      VUE_RASTER_STATIC_SRC_RE,
+      srcPath =>
         `[${label}] ${rel}: пряме \`src="${srcPath}"\` у шаблоні має використовувати AVIF-двійник \`src="${srcPath}.avif"\` ` +
-          `(або винеси у import + \`:src="..."\`). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
-      )
+        `(або винеси у import + \`:src="..."\`). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+    )
+
+    for (const match of updated.matchAll(VUE_AVIF_REF_RE)) {
+      const avifPath = match[1]
+      const avifAbs = resolveImagePath(avifPath, absPath)
+      if (avifAbs) usedAvifAbs.add(avifAbs)
+    }
+
+    if (updated !== original) {
+      await writeFile(absPath, updated, 'utf8')
     }
   }
   if (violations === 0) {
-    pass(`[${label}] усі raster-посилання у .vue вже на .avif (або відсутні)`)
+    const summary = replacements > 0 ? `усі raster-посилання у .vue/.html переписано на .avif (замін: ${replacements})` : 'усі raster-посилання у .vue/.html вже на .avif (або відсутні)'
+    pass(`[${label}] ${summary}`)
   }
 }
 
@@ -265,11 +346,13 @@ async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePa
  * перевірку Vue-imports. Перевірка пропускається, якщо в репозиторії немає workspaces
  * або немає `.vue`-файлів — тоді `image` правило не для цього проєкту.
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`-двійників,
+ * на які лишилось хоча б одне посилання у `.vue`/`.html` (заповнюється у викликаних функціях)
  * @param {(msg: string) => void} pass callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<void>} резолвиться по завершенню перевірки всіх workspace-пакетів
  */
-async function checkVueAvifImports(ignorePaths, pass, fail) {
+async function checkVueAvifImports(ignorePaths, usedAvifAbs, pass, fail) {
   const roots = await getMonorepoPackageRootDirs()
   const absRootsByRel = new Map(roots.map(r => [r, join(process.cwd(), r)]))
   for (const root of roots) {
@@ -283,7 +366,85 @@ async function checkVueAvifImports(ignorePaths, pass, fail) {
       continue
     }
     const otherRootsAbs = roots.filter(r => r !== root && r !== '.').map(r => absRootsByRel.get(r) ?? '')
-    await checkVueAvifImportsInPackage(root, otherRootsAbs, ignorePaths, pass, fail)
+    await checkVueAvifImportsInPackage(root, otherRootsAbs, ignorePaths, usedAvifAbs, pass, fail)
+  }
+}
+
+/**
+ * Чи є в репозиторії хоч один raster-файл, який мав би сенс конвертувати у AVIF.
+ * Якщо немає — `npx @nitra/minify-image` нема що робити, тож зайвий запуск пропускаємо
+ * (важливо у тестах: фікстурні `.png`-імпорти посилаються на неіснуючі файли, тож
+ * minify-image все одно нічого не згенерує — а зайвий npx-спавн повільний і робить шум).
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<boolean>} `true`, якщо знайдено принаймні один `.png/.jpe?g/.gif`
+ */
+async function hasAnyRasterImage(ignorePaths) {
+  let found = false
+  await walkDir(
+    process.cwd(),
+    absPath => {
+      if (found) return
+      if (/\.(?:png|jpe?g|gif)$/iu.test(absPath)) found = true
+    },
+    ignorePaths
+  )
+  return found
+}
+
+/**
+ * Запускає `npx @nitra/minify-image --src=. --write --avif` для генерації AVIF-двійників.
+ *
+ * Виклик best-effort: якщо мережа/кеш недоступні чи бінарника нема — лог-варн без падіння
+ * перевірки (валідації package.json і vue-refs все одно прогоняться, vue-refs на
+ * відсутні `.avif` фейлять окремо). У тестах та інших ізольованих середовищах npx
+ * можна вимкнути через `NITRA_CURSOR_NO_AVIF_RUN=1` — тоді ця функція no-op.
+ * @returns {void}
+ */
+function runAvifGeneration() {
+  if (env.NITRA_CURSOR_NO_AVIF_RUN === '1') return
+  const result = spawnSync('npx', [MINIFY_PACKAGE_NAME, '--src=.', '--write', '--avif'], {
+    stdio: 'inherit',
+    env
+  })
+  if (result.error) {
+    console.log(
+      `  ⚠️  не вдалося запустити \`npx ${MINIFY_PACKAGE_NAME} --avif\`: ${result.error.message} — vue/html-перевірка покаже файли, для яких не вистачає .avif`
+    )
+    return
+  }
+  if (typeof result.status === 'number' && result.status !== 0) {
+    console.log(
+      `  ⚠️  \`npx ${MINIFY_PACKAGE_NAME} --avif\` завершився з кодом ${result.status} — vue/html-перевірка покаже файли, для яких не вистачає .avif`
+    )
+  }
+}
+
+/**
+ * Видаляє AVIF-сироти — `<...>.avif` файли, на які не лишилось жодного посилання
+ * у `.vue`/`.html` репозиторію. Реалізує умову правила: «AVIF лишається лише там,
+ * де заміна реально вдалася».
+ * @param {Set<string>} usedAvifAbs абсолютні шляхи `.avif`, що мають живі посилання
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @returns {Promise<void>} резолвиться після видалення всіх сиріт
+ */
+async function cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass) {
+  /** @type {string[]} */
+  const orphans = []
+  await walkDir(
+    process.cwd(),
+    absPath => {
+      if (!absPath.endsWith('.avif')) return
+      if (usedAvifAbs.has(absPath)) return
+      orphans.push(absPath)
+    },
+    ignorePaths
+  )
+  for (const absPath of orphans) {
+    await unlink(absPath)
+  }
+  if (orphans.length > 0) {
+    pass(`видалено AVIF-сиріт без посилань у .vue/.html: ${orphans.length}`)
   }
 }
 
@@ -308,9 +469,10 @@ async function checkPackageJsonImage(pass, fail) {
 
 /**
  * Перевіряє відповідність проєкту правилам `image.mdc` (split-cache 3.2.0):
- * `lint-image` через `npx @nitra/minify-image --src=. --write --avif`, агрегований `lint`,
+ * `lint-image` через `npx @nitra/minify-image --src=. --write` (без `--avif`!), агрегований `lint`,
  * `.n-minify-image.tsv` НЕ в `.gitignore` (committed source of truth), застарілий
- * `.minify-image-cache.tsv` видалений, AVIF-імпорти у `.vue` файлах. CI-workflow
+ * `.minify-image-cache.tsv` видалений. Окремо виконуються дії: запуск AVIF-генерації,
+ * авто-заміна raster-посилань у `.vue`/`.html`, видалення AVIF-сиріт. CI-workflow
  * для image не вимагається — лінт зображень виконується лише локально.
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
  */
@@ -324,7 +486,15 @@ export async function check() {
     await checkLegacyCacheRemoved(pass, fail)
   }
   const ignorePaths = await loadCursorIgnorePaths(process.cwd())
-  await checkVueAvifImports(ignorePaths, pass, fail)
+
+  if (await hasAnyRasterImage(ignorePaths)) {
+    runAvifGeneration()
+  }
+
+  /** @type {Set<string>} */
+  const usedAvifAbs = new Set()
+  await checkVueAvifImports(ignorePaths, usedAvifAbs, pass, fail)
+  await cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass)
 
   return reporter.getExitCode()
 }

package/scripts/check-js-run.mjs

@@ -21,7 +21,10 @@
  *  - «depcheck у GitHub Actions з path-фільтром»: для кожного workflow з `paths:`,
  *    обмеженим каталогом цього пакета (`<rootDir>/...`), має бути крок
  *    `npx depcheck --ignores="graphql,bun"` (плюс інші, за потреби) з
- *    `working-directory: <rootDir>` (див. `utils/depcheck-workflow.mjs`).
+ *    `working-directory: <rootDir>` (див. `utils/depcheck-workflow.mjs`);
+ *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
+ *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
+ *    (див. `utils/promise-settimeout-scan.mjs`).
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -42,6 +45,10 @@ import {
   resolveConnDirFromPackageJson
 } from './utils/conn-imports-scan.mjs'
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
+import {
+  findPromiseSetTimeoutInText,
+  isPromiseSetTimeoutScanSourceFile
+} from './utils/promise-settimeout-scan.mjs'
 import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
@@ -162,6 +169,30 @@ async function checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail) {
   return violations
 }
 
+/**
+ * Сканує джерела пакета на паттерн `new Promise(resolve => setTimeout(resolve, ms))`.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, fail) {
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!isPromiseSetTimeoutScanSourceFile(rel)) continue
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findPromiseSetTimeoutInText(content, rel)) {
+      violations++
+      fail(
+        `${label}${rel}:${v.line} — заміни 'new Promise(r => setTimeout(r, ms))' на 'await setTimeout(ms)' з 'node:timers/promises': ${v.snippet}`
+      )
+    }
+  }
+  return violations
+}
+
 /**
  * Перевіряє відповідність правилам js-run.mdc для одного workspace-пакета.
  * @param {string} rootDir відносний шлях workspace (не `'.'`)
@@ -205,6 +236,11 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
     )
   }
 
+  const pauseViolations = await checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, fail)
+  if (pauseViolations === 0) {
+    passFn(`${label}немає 'new Promise(r => setTimeout(r, ms))' — паузи через 'node:timers/promises'`)
+  }
+
   await checkOtelConfigmap(rootDir, label, fail, passFn)
 
   checkDepcheckInWorkflows(rootDir, workflows, label, fail, passFn)

package/scripts/check-vue.mjs

@@ -4,6 +4,9 @@
  * Версії Vite та плагінів, vue-macros, auto-import, layouts, вміст `vite.config`;
  * у репозиторії — рекомендацію розширення Vue.volar.
  *
+ * У кожному Vue+Vite-пакеті очікується `src/vite-env.d.ts` з `/// <reference types="vite/client" />`
+ * та `jsconfig.json` у корені пакета (типи для імпортів асетів у `.vue`).
+ *
  * У `vite.config.*` заборонено використовувати `process.env.npm_lifecycle_event` (Bun не підставляє його як npm),
  * натомість використовуй `mode` з `defineConfig(({ mode }) => ...)`.
  *
@@ -32,6 +35,9 @@ import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 const MAJOR_VERSION_RE = /(\d+)/
 const ESBUILD_RE = /\besbuild\b/
 
+/** Регулярний вираз для triple-slash `reference types="vite/client"` у `src/vite-env.d.ts`. */
+const VITE_CLIENT_REFERENCE_RE = /\/\/\/\s*<reference\s+types\s*=\s*["']vite\/client["']\s*\/>/
+
 /**
  * Визначає, чи можна сканувати файл як текст на згадки `esbuild`.
  * @param {string} relPosix відносний шлях у posix-форматі
@@ -202,6 +208,43 @@ function checkRequiredDep(deps, name, prefix, passFn, fail, hint = `${name} ві
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  */
+/**
+ * Перевіряє `src/vite-env.d.ts` і наявність `jsconfig.json` для підтягування типів асетів Vite у IDE.
+ * @param {string} rootDir відносний шлях до кореня пакета
+ * @param {string} prefix префікс повідомлень
+ * @param {(msg: string) => void} passFn успіх
+ * @param {(msg: string) => void} fail помилка
+ * @returns {Promise<void>}
+ */
+async function checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail) {
+  const envRel = join(rootDir, 'src/vite-env.d.ts')
+  if (!existsSync(envRel)) {
+    fail(
+      `${prefix}немає src/vite-env.d.ts — додай файл з рядком /// <reference types="vite/client" /> ` +
+        `(інакше TS/Volar не бачать типів для імпортів асетів: png, avif, css як URL).`
+    )
+    return
+  }
+  const envContent = await readFile(envRel, 'utf8')
+  if (!VITE_CLIENT_REFERENCE_RE.test(envContent)) {
+    fail(
+      `${prefix}src/vite-env.d.ts має містити /// <reference types="vite/client" /> ` +
+        `(без цього імпорти статичних файлів у .vue дають «Cannot find module … type declarations»).`
+    )
+    return
+  }
+  passFn(`${prefix}src/vite-env.d.ts посилається на vite/client`)
+
+  if (!existsSync(join(rootDir, 'jsconfig.json'))) {
+    fail(
+      `${prefix}немає jsconfig.json у корені пакета — додай файл з "include": ["src/**/*"] тощо, ` +
+        `щоб IDE підхопила vite-env.d.ts і .vue.`
+    )
+    return
+  }
+  passFn(`${prefix}jsconfig.json присутній`)
+}
+
 function checkViteVersion(devDeps, prefix, passFn, fail) {
   const v = devDeps.vite
   if (!v) {
@@ -442,6 +485,8 @@ async function checkVuePackage(rootDir, ignorePaths, fail, passFn) {
     'vite-plugin-vue-layouts-next відсутній — bun add -d vite-plugin-vue-layouts-next'
   )
 
+  await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail)
+
   const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail)
   await checkVueImportViolations(
     rootDir,

package/scripts/utils/promise-settimeout-scan.mjs

@@ -0,0 +1,129 @@
+/**
+ * Знаходить паттерн `new Promise(resolve => setTimeout(resolve, ms))` (з `await` чи без)
+ * у джерелах — таку обгортку треба замінити на `setTimeout` з `node:timers/promises`
+ * згідно з js-run.mdc, секція «Паузи через setTimeout».
+ *
+ * Семантика — структурна (без regex по тілу): `NewExpression` з ідентифікатор-callee `Promise`
+ * і єдиним аргументом-функцією, тіло якої — виклик `setTimeout(<resolve>, ms)`. Перший
+ * аргумент `setTimeout` має передавати `resolve` напряму або тривіально загорнутим у
+ * безпараметричну функцію `() => resolve()` / `function () { resolve() }` без жодних
+ * аргументів — інакше це не «чиста пауза», і паттерн не вмикається.
+ *
+ * Сканер не вимагає, щоб файл компілювався: при синтаксичних помилках повертається
+ * порожній результат (як інші сканери — спочатку треба полагодити синтаксис).
+ */
+import { normalizeSnippet, offsetToLine, parseProgramOrNull } from './ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/
+
+/**
+ * Чи аргумент, який передають у `setTimeout`, — це «голий» виклик `resolve`
+ * (тобто сам ідентифікатор або `() => resolve()` без аргументів).
+ * @param {Record<string, unknown> | null | undefined} arg AST-вузол першого аргументу `setTimeout`
+ * @param {string} paramName ім'я параметра-resolve у тіла-функції Promise
+ * @returns {boolean} `true`, якщо це чиста передача resolve без значення
+ */
+function isBareResolveCallback(arg, paramName) {
+  if (!arg || typeof arg !== 'object') return false
+  if (arg.type === 'Identifier' && arg.name === paramName) return true
+  if (arg.type !== 'ArrowFunctionExpression' && arg.type !== 'FunctionExpression') return false
+  if ((arg.params?.length ?? 0) !== 0) return false
+  const callExpr = extractSingleCallExpression(arg.body)
+  if (!callExpr) return false
+  if (callExpr.callee?.type !== 'Identifier' || callExpr.callee.name !== paramName) return false
+  return !Array.isArray(callExpr.arguments) || callExpr.arguments.length === 0
+}
+
+/**
+ * Якщо тіло функції — рівно один `CallExpression` (концизне `() => foo()` або
+ * `{ foo() }` без інших стейтментів), повертає його. Інакше — `null`.
+ * @param {unknown} body тіло функції з AST
+ * @returns {Record<string, unknown> | null} AST-вузол `CallExpression` або `null`
+ */
+function extractSingleCallExpression(body) {
+  if (!body || typeof body !== 'object') return null
+  if (body.type === 'CallExpression') return body
+  if (body.type !== 'BlockStatement') return null
+  if (!Array.isArray(body.body) || body.body.length !== 1) return null
+  const stmt = body.body[0]
+  if (!stmt || stmt.type !== 'ExpressionStatement') return null
+  const expr = stmt.expression
+  return expr?.type === 'CallExpression' ? expr : null
+}
+
+/**
+ * Чи це `NewExpression` виду `new Promise(<resolve> => setTimeout(<resolve>, ms))`.
+ * Параметр-resolve має бути простим Identifier; setTimeout — глобальним викликом
+ * за іменем (з будь-якого джерела — node:timers, global, тощо: значення для нас має
+ * лише структурний паттерн).
+ * @param {Record<string, unknown> | null | undefined} node AST-вузол
+ * @returns {boolean} `true`, якщо це проблемний паттерн «обгортки таймера у Promise»
+ */
+function isPromiseSetTimeoutDelay(node) {
+  if (!node || node.type !== 'NewExpression') return false
+  if (node.callee?.type !== 'Identifier' || node.callee.name !== 'Promise') return false
+  if (!Array.isArray(node.arguments) || node.arguments.length !== 1) return false
+  const fn = node.arguments[0]
+  if (!fn || (fn.type !== 'ArrowFunctionExpression' && fn.type !== 'FunctionExpression')) return false
+  if (!Array.isArray(fn.params) || fn.params.length === 0) return false
+  const firstParam = fn.params[0]
+  if (!firstParam || firstParam.type !== 'Identifier') return false
+  const setTimeoutCall = extractSingleCallExpression(fn.body)
+  if (!setTimeoutCall) return false
+  if (setTimeoutCall.callee?.type !== 'Identifier' || setTimeoutCall.callee.name !== 'setTimeout') return false
+  if (!Array.isArray(setTimeoutCall.arguments) || setTimeoutCall.arguments.length < 1) return false
+  return isBareResolveCallback(setTimeoutCall.arguments[0], firstParam.name)
+}
+
+/**
+ * Простий рекурсивний обхід AST: заходимо в усі об'єкти/масиви, щоб знайти `NewExpression`.
+ * @param {unknown} node корінь або під-вузол AST
+ * @param {(n: Record<string, unknown>) => void} visit виклик для кожного об'єкта-вузла з `type`
+ * @returns {void}
+ */
+function walkAst(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkAst(item, visit)
+    return
+  }
+  if (typeof node.type === 'string') {
+    visit(node)
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'parent') continue
+    const v = node[key]
+    if (v && typeof v === 'object') walkAst(v, visit)
+  }
+}
+
+/**
+ * Знаходить усі `new Promise(resolve => setTimeout(resolve, ms))` у тексті.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/foo.ts`)
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findPromiseSetTimeoutInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAst(program, node => {
+    if (!isPromiseSetTimeoutDelay(node)) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`).
+ * @param {string} relativePath відносний шлях до файлу
+ * @returns {boolean} `true`, якщо розширення підходить для сканування
+ */
+export function isPromiseSetTimeoutScanSourceFile(relativePath) {
+  if (!SOURCE_FILE_RE.test(relativePath)) return false
+  return !relativePath.endsWith('.d.ts')
+}