@7n/rules-lang-js 0.6.0 → 0.7.0

package/rules/test/vitest-api-conventions/docs/main.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/test/vitest-api-conventions/main.mjs
+docgen:
+  crc: 638031f8
+---
+
+## Огляд
+
+Детектор concern-а `vitest-api-conventions`: перевіряє, що жоден тестовий файл проєкту
+не викликає `expect(...).toBe(...)` з об'єктним чи масивним літералом як першим аргументом.
+Така перевірка завжди хибна незалежно від вмісту (reference equality на новоствореному
+значенні) — канонічна заміна для об'єктів/масивів — `toEqual` (deep equality).
+
+## Поведінка
+
+Обходить дерево проєкту (пропускаючи `node_modules` і шляхи з cursor-ignore) і збирає всі
+файли з іменем `*.test.mjs`/`*.test.js`. У кожному файлі шукає виклики `.toBe(`, чий перший
+аргумент — саме об'єктний (`{...}`) чи масивний (`[...]`) літерал: сканує парність дужок
+з урахуванням рядкових і template-літералів усередині, щоб не збитись на дужки в рядках.
+Виклик рахується порушенням лише якщо одразу після закриваючої дужки літерала (з пропуском
+пробілів) іде дужка, що закриває сам виклик, `)` — тобто ланцюжок на кшталт
+`.toBe([...].join('\n'))` не матчиться, бо результат виклику — рядок-примітив, а не
+посилання на масив/обʼєкт.
+
+Для кожного знайденого випадку формує порушення з файлом (відносний шлях від cwd) і
+номером рядка.
+
+## Публічний API
+
+`lint(ctx)` — читає всі тестові файли проєкту (`ctx.cwd`), перевіряє їх на заборонений
+патерн `toBe` з об'єктним/масивним літералом і повертає список порушень
+(`{ file, message, reason }` на кожен знайдений виклик), або порожній результат, якщо
+жоден тестовий файл не порушує конвенцію (test.mdc, vitest-api-conventions).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД) — лише читає файли й повертає порушення.
+- Сканує лише `*.test.mjs`/`*.test.js`; інші файли (в т.ч. `node_modules`) ігноруються.

package/rules/test/vitest-api-conventions/main.mjs

@@ -0,0 +1,153 @@
+/** @see ./docs/main.md */
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { collectTestFileOffenders } from '../lib/collect-test-file-offenders.mjs'
+
+/**
+ * `expect(x).toBe({…})` / `expect(x).toBe([…])` — `toBe` — це `Object.is`
+ * (reference equality); нове об'єктне/масивне літеральне значення завжди має інше
+ * посилання, тож перевірка **завжди false**, незалежно від вмісту. Канон — `toEqual`
+ * (deep equality) для об'єктів і масивів (vitest-api-conventions.mdc, п.4).
+ * Знаходить лише `.toBe(` де аргумент — САМЕ літерал (нічого не приєднано після
+ * закриваючої дужки, окрім опційних пробілів і `)`) — `.toBe([...].join('\n'))`
+ * не матчиться: результат `.join()` — рядок-примітив, а не масив-посилання.
+ */
+const TO_BE_CALL_RE = /\.toBe\(/gu
+/** Whitespace-символ (пробіл/таб/перенос) — для `skipWhitespace`, module scope (oxlint prefer-static-regex). */
+const WS_RE = /\s/u
+/** Рядкові/template-лапки, що відкривають літерал усередині `findMatchingBracketEnd`. */
+const QUOTE_CHARS = new Set(['"', "'", '`'])
+/** Мапа закриваючої дужки на парну дужку, яка її відкриває — для перевірки балансу стеку. */
+const CLOSE_TO_OPEN = { '}': '{', ']': '[' }
+
+/**
+ * Пропускає пробіли/переноси рядків, повертає індекс першого не-whitespace символу.
+ * @param {string} body вміст файлу
+ * @param {number} from стартовий індекс
+ * @returns {number} індекс першого значущого символу (може дорівнювати `body.length`)
+ */
+function skipWhitespace(body, from) {
+  let i = from
+  while (i < body.length && WS_RE.test(body[i])) i++
+  return i
+}
+
+/**
+ * Просуває сканер на один крок усередині рядкового/template-літералу: обробляє
+ * екранування (`\x`) і повідомляє, чи саме на цьому символі рядок закрився.
+ * Виокремлено з `findMatchingBracketEnd`, аби тримати cognitive complexity
+ * головного циклу під порогом лінтера.
+ * @param {string} body вміст файлу
+ * @param {number} i індекс поточного символу (усередині рядка)
+ * @param {string} quote символ лапки, що відкриває поточний рядок
+ * @returns {{next: number, closed: boolean}} нова позиція сканера і прапорець закриття
+ */
+function stepInsideQuote(body, i, quote) {
+  const ch = body[i]
+  if (ch === '\\') return { next: i + 2, closed: false }
+  if (ch === quote) return { next: i + 1, closed: true }
+  return { next: i + 1, closed: false }
+}
+
+/**
+ * Знаходить індекс символу, що йде одразу за парною дужкою, яка закриває
+ * дужку на позиції `openIndex` (`{` чи `[`). Ігнорує дужки всередині
+ * рядкових/template-літералів, аби не збитись на `{ a: '}' }` тощо.
+ * @param {string} body вміст файлу
+ * @param {number} openIndex індекс відкриваючої дужки
+ * @returns {number|null} індекс одразу після закриваючої дужки, або `null` якщо не збалансовано
+ */
+function findMatchingBracketEnd(body, openIndex) {
+  const stack = [body[openIndex]]
+  let i = openIndex + 1
+  let quote = null
+
+  while (i < body.length) {
+    if (quote) {
+      const step = stepInsideQuote(body, i, quote)
+      if (step.closed) quote = null
+      i = step.next
+      continue
+    }
+
+    const ch = body[i]
+
+    if (QUOTE_CHARS.has(ch)) {
+      quote = ch
+      i++
+      continue
+    }
+
+    if (ch === '{' || ch === '[') {
+      stack.push(ch)
+      i++
+      continue
+    }
+
+    if (ch in CLOSE_TO_OPEN) {
+      if (stack.at(-1) !== CLOSE_TO_OPEN[ch]) return null // незбалансовано — здаємось
+      stack.pop()
+      if (stack.length === 0) return i + 1
+      i++
+      continue
+    }
+
+    i++
+  }
+
+  return null
+}
+
+/**
+ * Знаходить усі виклики `.toBe(` де перший аргумент — САМЕ об'єктний/масивний
+ * літерал (не результат ланцюжка викликів на ньому).
+ * @param {string} body вміст файлу
+ * @returns {Array<{line: number}>} знайдені порушення
+ */
+function findOffenders(body) {
+  const offenders = []
+  for (const m of body.matchAll(TO_BE_CALL_RE)) {
+    const argStart = skipWhitespace(body, m.index + m[0].length)
+    const ch = body[argStart]
+    if (ch !== '{' && ch !== '[') continue
+
+    const afterLiteral = findMatchingBracketEnd(body, argStart)
+    if (afterLiteral === null) continue
+
+    const afterWs = skipWhitespace(body, afterLiteral)
+    if (body[afterWs] !== ')') continue // приєднано щось після літерала (напр. .join(...)) — не порушення
+
+    const line = body.slice(0, m.index).split('\n').length
+    offenders.push({ line })
+  }
+  return offenders
+}
+
+/**
+ * Detector: жоден `*.test.{mjs,js}` не викликає `expect(...).toBe(...)` з
+ * об'єктним/масивним літералом — `toBe` (Object.is) на новоствореному
+ * об'єкті/масиві завжди false; канон — `toEqual` (vitest-api-conventions.mdc, п.4).
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з порушеннями.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  const cwd = ctx.cwd
+  const { testFiles, offenders } = await collectTestFileOffenders(cwd, findOffenders)
+
+  if (offenders.length === 0) {
+    pass(`Жоден з ${testFiles.length} тестових файлів не викликає toBe(...) з об'єктним/масивним літералом (test.mdc)`)
+    return reporter.result()
+  }
+
+  for (const { file, line } of offenders) {
+    fail(
+      `${file}:${line}: expect(...).toBe(...) з об'єктним/масивним літералом завжди false ` +
+        `(Object.is на новому посиланні) — використовуй toEqual (test.mdc, vitest-api-conventions)`,
+      { file }
+    )
+  }
+
+  return reporter.result()
+}

package/rules/test/vitest-api-conventions/vitest-api-conventions.mdc

@@ -0,0 +1,129 @@
+## Vitest API — обов'язкові конвенції (для генерації тестів LLM)
+
+Цей розділ адресований генераторам тестів (LLM, local і cloud). Порушення будь-якого пункту — рівнозначне синтаксичній помилці: тест не запуститься або дасть хибно-позитивний результат.
+
+Канон: тести виконуються через **vitest** під Bun-рушієм (`bun run --bun vitest run`, див. `test.package_json`), а не через нативний `bun test` — `import ... from 'bun:test'` заборонено (`no-bun-test-import`). API нижче — саме vitest, не bun:test і не jest.
+
+### 1. Модульна система — лише ESM
+
+`*.test.mjs` завжди ESM; `require()` у `.mjs` кидає `ERR_REQUIRE_ESM`.
+
+✓ `import { foo } from '../foo.mjs'`
+✗ `const { foo } = require('../foo.mjs')`
+
+### 2. `vi.*` замість `jest.*`
+
+Проект використовує Vitest, не Jest. Будь-який `jest.fn()`, `jest.mock()`, `jest.spyOn()` — помилка компіляції або runtime-помилка.
+
+✓ `vi.fn()`, `vi.mock(...)`, `vi.spyOn(...)`
+✗ `jest.fn()`, `jest.mock(...)`, `jest.spyOn(...)`
+
+### 3. Кастинг mock-функцій — лише `vi.mocked()`
+
+✓ `vi.mocked(fetch).mockResolvedValue(res)`
+✗ `(fetch as vi.Mock).mockResolvedValue(res)` — TypeScript у `.mjs` не компілюється
+
+### 4. `toBe` vs `toEqual`
+
+`toBe` (Object.is) — для примітивів (`string`, `number`, `boolean`, `null`, `undefined`).
+`toEqual` (deep equality) — для об'єктів і масивів.
+
+`toBe({…})` для об'єктів **завжди false** (різні посилання) — використовуй `toEqual`.
+
+✓ `expect(count).toBe(3)`
+✓ `expect(result).toEqual({ ok: true })`
+✗ `expect(result).toBe({ ok: true })`
+
+**Перевірка** (`rules/test/vitest-api-conventions/main.mjs`): сканує `**/*.test.{mjs,js}`, шукає `expect(...).toBe(...)` з об'єктним/масивним літералом як першим аргументом — таке порівняння завжди `false` через reference equality, незалежно від вмісту.
+
+### 5. Моки для Date / часу
+
+`vi.spyOn(Date).mockReturnValue(…)` **не працює** з `new Date()` (TypeError: Date is not a constructor при `new`).
+
+✓
+
+```js
+vi.useFakeTimers()
+vi.setSystemTime(new Date('2024-01-01'))
+afterEach(() => vi.useRealTimers())
+```
+
+✗ `vi.spyOn(global, 'Date').mockReturnValue(new Date('2024-01-01'))`
+
+### 6. Моки для `process.env`
+
+`process.env.X = '…'` забруднює глобальний стан; `vi.spyOn(process, 'env')` не дає ізоляції між тестами.
+
+✓
+
+```js
+vi.stubEnv('KEY', 'val')
+afterEach(() => vi.unstubAllEnvs())
+```
+
+✗ `process.env.KEY = 'val'` (без відновлення)
+
+### 7. Модулі з top-level side-effect
+
+Якщо source-модуль читає `process.env` або викликає функцію на рівні модуля — env/моки мають бути встановлені **до** `import`; сам import — dynamic.
+
+✓
+
+```js
+vi.stubEnv('KEY', 'val')
+const { fn } = await import('../index.js')
+```
+
+✗ статичний `import { fn } from '../index.js'` коли source викликає функцію на рівні модуля
+
+### 8. Cleanup у `afterEach` — обов'язковий
+
+Після кожного тест-файлу з mock-ами — відновлення стану:
+
+```js
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  vi.useRealTimers() // лише якщо vi.useFakeTimers() використовувався
+})
+```
+
+Пропуск `afterEach` — витік стану між тестами в одному файлі.
+
+### 9. FormData у Node.js
+
+`formData.get('field')` повертає `Blob | string | null`. Для file-полів — `toBeInstanceOf(Blob)`, НЕ `toBe('filename')`.
+
+✓ `expect(formData.get('file')).toBeInstanceOf(Blob)`
+✗ `expect(formData.get('file')).toBe('photo.jpg')`
+
+---
+
+### Канонічний шаблон тест-файлу
+
+```js
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { myFn } from '../my-module.mjs'
+
+vi.mock('../dep.mjs', () => ({ dep: vi.fn() }))
+
+beforeEach(() => {
+  vi.stubEnv('API_KEY', 'test-key')
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2024-06-01'))
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  vi.useRealTimers()
+})
+
+describe('myFn', () => {
+  it('повертає очікуване значення', async () => {
+    const result = await myFn()
+    expect(result).toEqual({ ok: true })
+  })
+})
+```

package/rules/test/vitest-config-pool-forks/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "full",
+    "glob": ["vitest.config.mjs", "vitest.config.js"]
+  }
+}

package/rules/test/vitest-config-pool-forks/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/test/vitest-config-pool-forks
+resource: plugins/lang-js/rules/test/vitest-config-pool-forks/
+---
+
+# npm/rules/test/vitest-config-pool-forks
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/test/vitest-config-pool-forks/docs/main.md

@@ -0,0 +1,42 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/test/vitest-config-pool-forks/main.mjs
+docgen:
+  crc: 3d6d8777
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Огляд:
+Перевіряє конфігураційний файл Vitest для валідації наявності ізоляції тестів через режим `forks`. Це забезпечує відсутність гонок даних при паралельному виконанні тестів.
+
+Поведінка:
+
+1. Викликається публічна функція `main` для аналізу конфігураційного файлу Vitest.
+2. Перевірка пропущена, якщо файли `vitest.config.mjs` або `vitest.config.js` відсутні.
+3. При знаходженні файлу його вміст зчитується.
+4. Перевірка успішна, якщо вміст файлу містить шаблон `pool: 'forks'` (test.mdc).
+5. Перевірка провалена, якщо вміст файлу не містить шаблон `pool: 'forks'` (test.mdc), оскільки це обов'язковий захист від гонок даних у паралельних тестах.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається `main` для перевірки конфігураційного файлу Vitest.
+2. Якщо файл `vitest.config.mjs` або `vitest.config.js` відсутній, перевірка пропущена.
+3. Якщо конфігураційний файл знайдено, його вміст читається.
+4. Якщо вміст файлу містить шаблон `pool: 'forks'`, перевірка успішна (test.mdc).
+5. Якщо вміст файлу не містить шаблон `pool: 'forks'`, перевірка провалена (test.mdc), оскільки це необхідна оборонна міра проти гонки даних у паралельних файлах тестів.
+
+## Публічний API
+
+main — Вимагає налаштування `vitest.config` на використання ізольованих процесів (`pool: 'forks'`).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/test/vitest-config-pool-forks/main.mjs

@@ -0,0 +1,41 @@
+/** @see ./docs/vitest-config-pool-forks.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Subтring-pattern: `pool: 'forks'` або `pool: "forks"` (з опційним whitespace). */
+const POOL_FORKS_RE = /pool\s*:\s*['"]forks['"]/u
+
+// Канонічна назва — `.mjs` (нові файли, js.mdc), але legacy `.js` лишається
+// валідним. Перший знайдений виграє: `.mjs` пріоритетніший.
+const VITEST_CONFIG_NAMES = ['vitest.config.mjs', 'vitest.config.js']
+
+/**
+ * Перевіряє, що `vitest.config.{mjs,js}` (якщо існує) містить `pool: 'forks'`.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінт-прогону.
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки наявності `pool: 'forks'`.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  const cwdParam = ctx.cwd
+  const configName = VITEST_CONFIG_NAMES.find(name => existsSync(join(cwdParam, name)))
+  if (!configName) {
+    pass('vitest.config.mjs/.js відсутній — pool-перевірку пропущено')
+    return reporter.result()
+  }
+
+  const body = await readFile(join(cwdParam, configName), 'utf8')
+  if (POOL_FORKS_RE.test(body)) {
+    pass(`${configName} містить pool: 'forks' (test.mdc)`)
+  } else {
+    fail(
+      `${configName} має містити pool: 'forks' — defense-in-depth для race у process.cwd() між паралельними test files (test.mdc)`
+    )
+  }
+
+  return reporter.result()
+}

package/rules/test/vitest-config-pool-forks/vitest-config-pool-forks.mdc

@@ -0,0 +1,34 @@
+## Vitest: `pool: 'forks'` як захист від race у `process.cwd()`
+
+**`vitest-config-pool-forks`** (`rules/test/js/vitest-config-pool-forks.mjs`) — substring-перевірка `pool: 'forks'` у `vitest.config.mjs` (або legacy `vitest.config.js`; `.mjs` пріоритетніший).
+
+**Чому:** Defense-in-depth проти race у `process.cwd()` між паралельними test файлами. Навіть якщо хтось пропустить заборону `process.chdir`, fork-ізоляція не дасть race у production tree — кожен test-файл отримує власний процес зі своїм `cwd`.
+
+Якщо `vitest.config.mjs` / `vitest.config.js` відсутній — перевірка пропускається (pass без помилки).
+
+**Canonical `vitest.config.mjs`** (для довідки — `pool: 'forks'` + `include` + `coverage`) — у `rules/test/js/data/vitest_config/vitest.config.baseline.js`:
+
+- `environment: 'node'`
+- `coverage.provider: 'v8'` з lcov+text-summary репортами
+- `include: ['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}']` — підхоплює тести у `tests/`-піддиректоріях і top-level integration suites у `<root>/tests/`
+
+У `package.json#scripts` має бути `"test": "bun run --bun vitest run"` (substring `vitest` + `--bun`; допустимі локальні розширення-обгортки) та опційно `"test:watch": "vitest"`.
+
+**Frontend-варіант (Vue/Vite + happy-dom):**
+
+Для проєктів зі своїм `vite.config.js` `vitest.config.mjs` має повторно використовувати vite-плагіни та aliases і перемкнути `environment` на `'happy-dom'` (або `'jsdom'`):
+
+```js
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config.js'
+
+export default mergeConfig(viteConfig, defineConfig({
+  test: {
+    include: ['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}'],
+    environment: 'happy-dom',
+    coverage: { provider: 'v8', reporter: ['lcov', 'text-summary'] }
+  }
+}))
+```
+
+Концерн ставить node-варіант baseline; перехід на frontend — ручна модифікація, після якої концерн уже не перетирає (idempotent).