@nitra/cursor 1.8.185 → 1.8.188

package/CHANGELOG.md

@@ -4,6 +4,34 @@
 
 Формат — [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

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.185",
+  "version": "1.8.188",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

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')
+}