@7n/rules-lang-js 0.3.1 → 0.4.1

package/rules/js-run/lib/docs/promise-settimeout-scan.md

@@ -0,0 +1,334 @@
+---
+type: JS Module
+title: promise-settimeout-scan.mjs
+resource: plugins/lang-js/rules/js-run/lib/promise-settimeout-scan.mjs
+docgen:
+  crc: 83b41b33
+---
+
+Модуль `promise-settimeout-scan.mjs` — це AST-сканер, який виявляє у вихідному коді JavaScript/TypeScript антипаттерн «обгортка `setTimeout` у `new Promise`» виду:
+
+```js
+new Promise(resolve => setTimeout(resolve, ms))
+// або
+await new Promise(resolve => setTimeout(resolve, ms))
+```
+
+Згідно з правилом `js-run.mdc` (секція «Паузи через `setTimeout`») такий код потрібно замінити на ідіоматичний імпорт із `node:timers/promises`:
+
+```js
+import { setTimeout as sleep } from 'node:timers/promises'
+
+await sleep(ms)
+```
+
+Сканер працює **структурно** (по AST), без regex-у по тілу: шукає `NewExpression`, у якого callee — Identifier `Promise`, а єдиний аргумент — функція з одним параметром-resolve, тіло якої — єдиний виклик `setTimeout(<resolve>, ms)`. Перший аргумент `setTimeout` мусить бути «голим» resolve — або сам ідентифікатор, або тривіальна безпараметрична обгортка `() => resolve()` / `function () { resolve() }` без жодних переданих аргументів. Якщо у виклик `resolve` передається значення — це вже не «чиста пауза», і паттерн **не** вмикається.
+
+Сканер **толерантний до синтаксичних помилок**: якщо файл не парситься, повертається порожній список (узгоджено з рештою AST-сканерів проєкту — спочатку треба полагодити синтаксис, а вже потім ловити структурні порушення).
+
+## Експорти / API
+
+| Експорт                             | Тип        | Призначення                                                                        |
+| ----------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
+| `findPromiseSetTimeoutInText`       | `function` | Знаходить усі входження антипаттерну в тексті, повертає масив `{ line, snippet }`. |
+| `isPromiseSetTimeoutScanSourceFile` | `function` | Фільтр по відносному шляху: чи варто взагалі сканувати цей файл (за розширенням).  |
+
+Внутрішні (не експортовані) хелпери, які формують ядро аналізу:
+
+- `isBareResolveCallback(arg, paramName)` — перевірка «чистоти» першого аргументу `setTimeout`.
+- `extractSingleCallExpression(body)` — витягнення єдиного `CallExpression` з тіла функції.
+- `isPromiseSetTimeoutDelay(node)` — головний предикат паттерну на рівні `NewExpression`.
+- `walkAst(node, visit)` — простий рекурсивний обхід AST.
+
+Константа модульного рівня:
+
+- `SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/` — regex розширень JS/TS-сім'ї (`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.jsx`, `.tsx`).
+
+## Функції
+
+### `findPromiseSetTimeoutInText(content, virtualPath = 'scan.ts')`
+
+**Призначення.** Публічна точка входу: парсить вихідний код, обходить AST і збирає всі позиції, де знайдено антипаттерн «`new Promise(... setTimeout ...)`».
+
+**Сигнатура.**
+
+```js
+export function findPromiseSetTimeoutInText(
+  content: string,
+  virtualPath?: string
+): { line: number, snippet: string }[]
+```
+
+**Параметри.**
+
+- `content: string` — повний текст файлу для сканування.
+- `virtualPath: string` (за замовчуванням `'scan.ts'`) — віртуальний шлях, який передається у `parseProgramOrNull` для вибору мови парсера (TS/JSX тощо). Не використовується для read/write-у на диск; впливає лише на режим парсингу.
+
+**Повертає.** Масив об'єктів `{ line: number, snippet: string }` — по одному запису на кожне виявлене порушення:
+
+- `line` — 1-based номер рядка, де починається `NewExpression` (через `offsetToLine`).
+- `snippet` — нормалізований текст самого `new Promise(...)`-виразу (через `normalizeSnippet`).
+
+Якщо AST не побудувався (синтаксична помилка), повертає порожній масив `[]`.
+
+**Side effects.** Чиста функція — жодного I/O, читання env, мутацій глобального стану. Усі дані повертаються через return value.
+
+---
+
+### `isPromiseSetTimeoutScanSourceFile(relativePath)`
+
+**Призначення.** Фільтр для зовнішнього раннера/обхідника файлів: чи варто взагалі парсити цей файл.
+
+**Сигнатура.**
+
+```js
+export function isPromiseSetTimeoutScanSourceFile(
+  relativePath: string
+): boolean
+```
+
+**Параметри.**
+
+- `relativePath: string` — відносний шлях до файлу (наприклад, `src/utils/sleep.ts`).
+
+**Повертає.** `true`, якщо:
+
+1. Розширення збігається з `SOURCE_FILE_RE` (JS/TS-сім'я), **та**
+2. Шлях **не** закінчується на `.d.ts` (декларації типів пропускаються).
+
+Інакше — `false`.
+
+**Side effects.** Немає.
+
+---
+
+### `isBareResolveCallback(arg, paramName)` (внутрішня)
+
+**Призначення.** Перевіряє, що перший аргумент `setTimeout` — це або сам ідентифікатор `resolve`, або тривіальна безпараметрична обгортка, яка викликає `resolve()` без значення.
+
+**Сигнатура.**
+
+```js
+function isBareResolveCallback(
+  arg: Record<string, unknown> | null | undefined,
+  paramName: string
+): boolean
+```
+
+**Параметри.**
+
+- `arg` — AST-вузол першого аргументу виклику `setTimeout`.
+- `paramName` — ім'я параметра-resolve у тіла-функції `Promise` (зазвичай `'resolve'`, але приймається будь-яке ім'я-Identifier).
+
+**Повертає.** `true`, якщо аргумент — це:
+
+- `Identifier` з іменем `paramName` (наприклад, `setTimeout(resolve, ms)`); **або**
+- `ArrowFunctionExpression` / `FunctionExpression` без параметрів, тіло якого — рівно один `CallExpression`, callee — `Identifier paramName`, а список аргументів виклику — порожній (наприклад, `() => resolve()` або `function () { resolve() }`).
+
+В інших випадках — `false`. Зокрема, якщо у виклик `resolve(x)` передається значення — це **не** «чиста пауза» (бо результат `await` був би `x`, а не `undefined`), і антипаттерн **не** фіксується.
+
+**Side effects.** Немає.
+
+---
+
+### `extractSingleCallExpression(body)` (внутрішня)
+
+**Призначення.** Витягує єдиний `CallExpression` з тіла функції — як у концизній стрілковій формі (`() => foo()`), так і в блоковій з рівно одним стейтментом (`() => { foo() }`).
+
+**Сигнатура.**
+
+```js
+function extractSingleCallExpression(
+  body: unknown
+): Record<string, unknown> | null
+```
+
+**Параметри.**
+
+- `body` — AST-вузол тіла функції (може бути `CallExpression`, `BlockStatement` або щось інше).
+
+**Повертає.** AST-вузол `CallExpression`, якщо:
+
+- `body.type === 'CallExpression'` — повертає сам body; **або**
+- `body.type === 'BlockStatement'`, масив `body.body` містить рівно один елемент, цей елемент — `ExpressionStatement`, а його `expression.type === 'CallExpression'` — повертає цей `expression`.
+
+Інакше — `null`.
+
+**Side effects.** Немає.
+
+---
+
+### `isPromiseSetTimeoutDelay(node)` (внутрішня)
+
+**Призначення.** Головний предикат паттерну: чи це `NewExpression` виду `new Promise(<resolve> => setTimeout(<resolve>, ms))`.
+
+**Сигнатура.**
+
+```js
+function isPromiseSetTimeoutDelay(
+  node: Record<string, unknown> | null | undefined
+): boolean
+```
+
+**Параметри.**
+
+- `node` — довільний AST-вузол (під час обходу через `walkAst`).
+
+**Повертає.** `true`, якщо всі наступні умови виконані:
+
+1. `node.type === 'NewExpression'`;
+2. `node.callee` — `Identifier` з іменем `'Promise'` (саме глобальний/локальний ідентифікатор, без member-доступу `foo.Promise`);
+3. `node.arguments.length === 1`;
+4. Цей єдиний аргумент — `ArrowFunctionExpression` або `FunctionExpression` з мінімум одним параметром;
+5. Перший параметр — `Identifier` (запам'ятовується його `name` як ім'я resolve);
+6. Тіло функції містить рівно один `CallExpression` (через `extractSingleCallExpression`);
+7. Callee цього виклику — `Identifier` з іменем `'setTimeout'` (джерело — глобальне, з `node:timers`, з `globalThis` — для сканера не важливо);
+8. У виклику `setTimeout` хоча б один аргумент;
+9. Перший аргумент `setTimeout` — «голий» resolve (через `isBareResolveCallback`).
+
+Якщо будь-яка умова порушена — повертає `false`.
+
+**Side effects.** Немає.
+
+---
+
+### `walkAst(node, visit)` (внутрішня)
+
+**Призначення.** Простий generic-обхід AST: рекурсивно спускається по всіх властивостях і елементах масивів, викликаючи `visit` для кожного об'єкта-вузла, який має поле `type` (тобто справжнього AST-вузла, а не службового мета-обʼєкта).
+
+**Сигнатура.**
+
+```js
+function walkAst(
+  node: unknown,
+  visit: (n: Record<string, unknown>) => void
+): void
+```
+
+**Параметри.**
+
+- `node` — корінь або під-вузол (Program, окремий вузол, масив, скаляр — все підтримується).
+- `visit` — колбек, який отримує кожен AST-вузол із полем `type`. Викликається **до** спуску в дочірні поля (pre-order).
+
+**Поведінка.**
+
+- `null`/примітиви — пропускаються;
+- Масиви — обходяться поелементно;
+- Об'єкти з `typeof node.type === 'string'` — спершу передаються у `visit`, потім обходяться їхні поля;
+- Поле з ключем `'parent'` пропускається (захист від циклів у деяких AST-моделях, де є зворотні посилання);
+- Інші поля-об'єкти — рекурсивно обходяться.
+
+**Повертає.** `undefined`.
+
+**Side effects.** Викликає `visit` зовнішнього коду — single side effect виноситься назовні через колбек.
+
+## Залежності
+
+### Зовнішні (relative imports)
+
+Із `../../../scripts/utils/ast-scan-utils.mjs`:
+
+- `parseProgramOrNull(content, virtualPath)` — парсить вихідний код у Program-вузол AST з урахуванням мови (вибір TS/JS/JSX за розширенням у `virtualPath`); повертає `null` при синтаксичних помилках.
+- `offsetToLine(content, offset)` — перетворює byte/char offset у 1-based номер рядка.
+- `normalizeSnippet(text)` — нормалізує текст сніпета (стискання пробілів/переносів) для зручного виводу у звітах.
+
+### Глобальні
+
+- `RegExp` (`SOURCE_FILE_RE`), `Array.isArray`, `Object.keys`, `String.prototype.endsWith`, `String.prototype.slice`, `Array.prototype.push` — стандартні API ES.
+
+### Без рантайм-залежностей
+
+Жодних `node:`-вбудованих модулів, жодних npm-пакетів, жодних звернень до файлової системи, env або мережі.
+
+## Потік виконання / Використання
+
+### Типовий сценарій (з раннера/перевіряча)
+
+```js
+import { findPromiseSetTimeoutInText, isPromiseSetTimeoutScanSourceFile } from './promise-settimeout-scan.mjs'
+import { readFile } from 'node:fs/promises'
+
+/**
+ *
+ */
+async function scanRepo(files) {
+  const violations = []
+  for (const relPath of files) {
+    if (!isPromiseSetTimeoutScanSourceFile(relPath)) continue
+    const content = await readFile(relPath, 'utf8')
+    const hits = findPromiseSetTimeoutInText(content, relPath)
+    for (const hit of hits) {
+      violations.push({ file: relPath, line: hit.line, snippet: hit.snippet })
+    }
+  }
+  return violations
+}
+```
+
+### Алгоритм всередині `findPromiseSetTimeoutInText`
+
+1. **Парсинг.** `parseProgramOrNull(content, virtualPath)` → якщо `null` (синтаксична помилка), функція одразу повертає `[]`.
+2. **Ініціалізація.** Створюється порожній масив `out` для накопичення знахідок.
+3. **Обхід AST.** `walkAst(program, visit)` рекурсивно проходить весь Program-вузол.
+4. **Перевірка паттерну.** Для кожного AST-вузла з полем `type` викликається `visit`, який:
+   - Перевіряє `isPromiseSetTimeoutDelay(node)`;
+   - Якщо `true` — пушить у `out` об'єкт `{ line, snippet }`, де `line` обчислюється з `node.start` через `offsetToLine`, а `snippet` — з `content.slice(node.start, node.end)` через `normalizeSnippet`.
+5. **Повернення.** Масив `out` повертається як результат (може бути порожнім, якщо порушень немає).
+
+### Що сканер ловить (приклади позитивних спрацювань)
+
+```js
+new Promise(resolve => setTimeout(resolve, 1000))
+await new Promise(r => setTimeout(r, ms))
+new Promise(resolve => setTimeout(() => resolve(), 500))
+new Promise(function (resolve) {
+  setTimeout(resolve, 200)
+})
+new Promise(resolve => {
+  setTimeout(function () {
+    resolve()
+  }, 100)
+})
+```
+
+### Що сканер свідомо **не** ловить (негативні приклади)
+
+- `new Promise(resolve => setTimeout(() => resolve(value), ms))` — у `resolve` передається значення; це не «чиста пауза».
+- `new Promise((resolve, reject) => setTimeout(() => doStuff().then(resolve, reject), ms))` — у тілі більше ніж один call або інший callee.
+- `new MyPromise(resolve => setTimeout(resolve, ms))` — callee — не `Promise`.
+- `globalThis.Promise` як callee (MemberExpression) — не Identifier.
+- Файли з синтаксичними помилками — `parseProgramOrNull` повертає `null`, сканер віддає `[]`.
+- Файли з розширенням `.d.ts` — фільтруються `isPromiseSetTimeoutScanSourceFile`.
+
+### Інтеграція з правилом `js-run.mdc`
+
+Цей сканер — частина перевірок правила js-run, секція «Паузи через `setTimeout`». Він використовується check-скриптом правила для збору списку порушень, які потім виводяться користувачу зі вказівкою замінити обгортку на `setTimeout` із `node:timers/promises`. Сам файл `promise-settimeout-scan.mjs` не виконує жодних дій з виправлення — лише детектує.
+
+## Rebuild Test
+
+Перевірка контрактів модуля (умоглядно, без запуску):
+
+1. **`isPromiseSetTimeoutScanSourceFile`:**
+   - `'src/a.ts'` → `true`; `'src/a.tsx'` → `true`; `'src/a.mjs'` → `true`; `'src/a.cjs'` → `true`.
+   - `'src/a.d.ts'` → `false` (декларації пропускаються).
+   - `'src/a.md'` / `'src/a.json'` → `false` (інше розширення).
+
+2. **`findPromiseSetTimeoutInText` — позитивний кейс:**
+   - Вхід: `const s = new Promise(r => setTimeout(r, 100))`.
+   - Очікувано: масив з одним записом, `line === 1`, `snippet` містить нормалізований текст `new Promise(r => setTimeout(r, 100))`.
+
+3. **`findPromiseSetTimeoutInText` — негативний кейс (передача значення):**
+   - Вхід: `new Promise(r => setTimeout(() => r(42), 10))`.
+   - Очікувано: `[]` (бо `isBareResolveCallback` відсіває виклики з аргументами).
+
+4. **`findPromiseSetTimeoutInText` — синтаксична помилка:**
+   - Вхід: `const x = (` (незакритий вираз).
+   - Очікувано: `[]` (бо `parseProgramOrNull` повертає `null`).
+
+5. **`findPromiseSetTimeoutInText` — інший callee:**
+   - Вхід: `new MyPromise(r => setTimeout(r, 1))`.
+   - Очікувано: `[]` (бо `node.callee.name !== 'Promise'`).
+
+6. **`isPromiseSetTimeoutDelay` — більше одного стейтменту в блоці:**
+   - Тіло Promise-функції: `{ doSomething(); setTimeout(resolve, 10) }`.
+   - Очікувано: `false` (бо `extractSingleCallExpression` вимагає рівно один стейтмент).

package/rules/js-run/lib/docs/temporal-scan.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: temporal-scan.mjs
+resource: plugins/lang-js/rules/js-run/lib/temporal-scan.mjs
+docgen:
+  crc: 37bae946
+---
+
+Цей файл є частиною системи, яка сканує код Bun workspace на наявність використання ключового слова `Temporal`. Він запобігає використанню `Temporal` у backend-коді, оскільки Bun 1.3.x ще не має глобального `Temporal`, та охоплює сценарії з імпортом та polyfill. Це забезпечує відповідність коду поточним вимогам Bun runtime щодо обробки часу.
+
+## Поведінка
+
+Знаходить використання identifier `Temporal` у тексті. Повертає список рядків та фрагментів коду, де зустрічається `Temporal`.
+Чи сканувати файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`). Повертає `true`, якщо файл має відповідне розширення, і не є файлом `.d.ts`.
+
+## Публічний API
+
+- findTemporalUsageInText — Знаходить згадки про `Temporal` у тексті.
+- isTemporalScanSourceFile — Визначає, чи потрібно сканувати файл за розширенням (JavaScript/TypeScript або `.d.ts`).
+
+## Гарантії поведінки
+
+- Функція `findTemporalUsageInText` повертає `true` лише якщо знайде identifier `Temporal` у наданому тексті.
+- Функція `findTemporalUsageInText` повертає `false` якщо identifier `Temporal` не знайдено.
+- Функція `isTemporalScanSourceFile` повертає `true` якщо у файлі є identifier `Temporal`.
+- Функція `isTemporalScanSourceFile` повертає `false` якщо у файлі немає identifier `Temporal`.
+- Результат роботи `findTemporalUsageInText` не гарантує, що identifier `Temporal` використовується правильно.
+- Результат роботи `isTemporalScanSourceFile` не гарантує, що використання `Temporal` є допустимим.
+- Кеш не використовується.

package/rules/js-run/lib/promise-settimeout-scan.mjs

@@ -0,0 +1,128 @@
+/**
+ * Знаходить паттерн `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 '@7n/rules/scripts/utils/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, v] of Object.entries(node)) {
+    if (key === 'parent') continue
+    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')
+}

package/rules/js-run/lib/temporal-scan.mjs

@@ -0,0 +1,52 @@
+/**
+ * AST-сканер заборони `Temporal` у Bun runtime-коді.
+ *
+ * Bun 1.3.x ще не має глобального `Temporal`, тому правило js-run забороняє
+ * будь-який identifier `Temporal` у backend workspace-коді. Заборона свідомо
+ * охоплює polyfill/import-сценарії: у цьому репозиторії канон для часу лишається
+ * через `Date` або ін'єкцію timestamp у чисті функції.
+ */
+import {
+  normalizeSnippet,
+  offsetToLine,
+  parseProgramOrNull,
+  walkAstWithAncestors
+} from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+
+/**
+ * Знаходить використання identifier `Temporal` у тексті.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/foo.ts`)
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findTemporalUsageInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  /** @type {Set<string>} */
+  const seen = new Set()
+  walkAstWithAncestors(program, [], node => {
+    if (node.type !== 'Identifier' || node.name !== 'Temporal') return
+    const key = `${node.start}:${node.end}`
+    if (seen.has(key)) return
+    seen.add(key)
+    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 isTemporalScanSourceFile(relativePath) {
+  if (!SOURCE_FILE_RE.test(relativePath)) return false
+  return !relativePath.endsWith('.d.ts')
+}

package/rules/js-run/main.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "nestedPackageWithoutVite" } }

package/rules/js-run/main.mdc

@@ -0,0 +1,16 @@
+---
+description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
+globs: "**/package.json,**/jsconfig.json,**/src/**/*.{js,mjs,cjs,ts,tsx}"
+alwaysApply: false
+version: '1.12'
+---
+
+Правило охоплює backend Node.js workspace-пакети (jobs, GraphQL/HTTP-сервери, CLI) — визначення меж застосування, вимоги до runtime, структуру проекту, конфігурацію, логування, підключення до БД/GraphQL і безпечне використання env-змінних.
+
+## Швидкий gate через conftest
+
+Rego-пакети, які запускає `npx @7n/rules fix js-run` / `npx @7n/rules check`:
+
+- [jsconfig.json.snippet.json](./jsconfig/template/jsconfig.json.snippet.json)
+- [configmap.yaml.contains.yml](./configmap/template/configmap.yaml.contains.yml)
+- [package.json.deny.json](./package_json/template/package.json.deny.json)

package/rules/js-run/package_json/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "walkGlob": "**/package.json"
+    }
+  }
+}

package/rules/js-run/package_json/package_json.mdc

@@ -0,0 +1,44 @@
+## Rego-gate: package.json (залежності та scripts)
+
+Rego-пакет: `js-run.package_json`
+
+**Цільові файли:** `package.json` у backend workspace-пакетах (без `vite` у `devDependencies`)
+
+Перевіряє три класи порушень за deny-списком із template:
+
+Канон deny-списку: [package.json.deny.json](./template/package.json.deny.json)
+
+**1. Заборонені залежності** (`dependencies` / `devDependencies`)
+
+| Пакет | Причина |
+|-------|---------|
+| `bunyan` | використовуй стандартні логери |
+| `@nitra/bunyan` | використовуй стандартні логери |
+
+**2. Заборонений рантайм у `scripts`** (лише backend-пакети без `vite`)
+
+- Патерн `\bnode(\s|$)` — заміни `node` на `bun`
+- Патерн `\benv\s+\$\(cat\s+[^)]+\)\s+bun\b` — заміни `env $(cat A B) bun` на `bun --env-file=A --env-file=B`
+
+**✓ Правильно**
+
+```json
+{ "scripts": { "start": "bun src/index.js" } }
+{ "scripts": { "start": "bun --env-file=.env src/index.js" } }
+```
+
+**✗ Неправильно**
+
+```json
+{ "scripts": { "start": "node src/index.js" } }
+{ "scripts": { "start": "env $(cat .env .env.local) bun src/index.js" } }
+{ "dependencies": { "bunyan": "^1.0.0" } }
+```
+
+Пакети з `vite` у `devDependencies` — frontend, поза областю js-run, перевірка scripts не застосовується.
+
+## Використання @nitra/pino для логування
+
+Проект використовує @nitra/pino для логування. Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
+
+Заборона `bunyan` / `@nitra/bunyan` у `dependencies` / `devDependencies` — rego-gate вище (канон: [package.json.deny.json](./template/package.json.deny.json)). Заборонені імпорти в коді (AST-сканер): `../lib/bunyan-imports.mjs` (перевірка запускається з `../runtime/main.mjs`).

package/rules/js-run/package_json/package_json.rego

@@ -0,0 +1,37 @@
+# Перевірка `package.json` (js-run.mdc).
+#
+# Канон надходить через --data: { "template": { "deny": ... } }
+# Структура --data сформована з template/package.json.deny.json.
+# AST-скан коду (`bunyan`/`process.env`/`#conn/*`) — у JS.
+package js_run.package_json
+
+import rego.v1
+
+deny contains msg if {
+	some pkg, reason in data.template.deny.dependencies
+	pkg in object.keys(object.get(input, "dependencies", {}))
+	msg := sprintf("dependencies.%s — %s", [pkg, reason])
+}
+
+deny contains msg if {
+	some pkg, reason in data.template.deny.devDependencies
+	pkg in object.keys(object.get(input, "devDependencies", {}))
+	msg := sprintf("devDependencies.%s — %s", [pkg, reason])
+}
+
+# ── deny: `node` як рантайм у `scripts` (backend-пакети без vite) ─────────
+
+deny contains msg if {
+	js_run_backend_package
+	is_object(input.scripts)
+	some script_name, script_value in input.scripts
+	is_string(script_value)
+	some rule in object.get(data.template.deny, "scriptsForbidden", [])
+	regex.match(rule.pattern, script_value)
+	msg := sprintf("package.json: scripts.%s — %s", [script_name, rule.message])
+}
+
+# Frontend-пакети (`vite` у devDependencies) — поза js-run (див. js-run.mdc).
+js_run_backend_package if {
+	not "vite" in object.keys(object.get(input, "devDependencies", {}))
+}