@nitra/cursor 1.35.5 → 1.36.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.36.0] - 2026-05-31
+
+### Added
+
+- test rule v2.7: канони Console mocking (vi.spyOn), Sandbox-aware тестів (withTmpDir+git init як default, skipIf STRYKER_MUTATOR_WORKER як виняток для smoke-аудиту) і явний {cwd:dir} у child_process
+
+### Changed
+
+- withLock: стан локу спільний для всіх git-worktree через resolveLockCacheDir (git-common-dir) — серіалізація важких команд між worktree, не лише в одному checkout
+
 ## [1.35.5] - 2026-05-30
 
 ### Changed

package/package.json

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

package/rules/release/release.mjs

@@ -117,11 +117,12 @@ export async function release(opts = {}) {
 
 /**
  * @param {string[]} _args аргументи CLI (наразі без опцій)
+ * @param {import('./release.mjs').ReleaseOpts} [opts] опції для тестів (cwd, date, runGit)
  * @returns {Promise<number>} exit-код
  */
-export async function runReleaseCli(_args) {
+export async function runReleaseCli(_args, opts = {}) {
   try {
-    const released = await release()
+    const released = await release(opts)
     if (released.length === 0) {
       console.log('release: немає змін для релізу')
     } else {

package/rules/test/test.mdc

@@ -1,6 +1,6 @@
 ---
 description: JS-тести (*.test.mjs) живуть у tests/. Правило `test` керує stryker.config.mjs + vitest.config.js (якщо js-lint enabled) і .cargo/mutants.toml (якщо rust enabled).
-version: '2.6'
+version: '2.7'
 globs: "**/{.n-cursor.json,package.json,Cargo.toml,stryker.config.mjs,vitest.config.js,.cargo/mutants.toml},**/*.test.mjs"
 alwaysApply: false
 ---
@@ -81,6 +81,51 @@ Recursive globs ловлять файли всередині `tests/` так с
 
 Canonical `vitest.config.js` (для довідки — `pool: 'forks'` + `include` + `coverage`) — у `rules/test/js/data/vitest_config/vitest.config.baseline.js` (концерн `stryker_config` копіює його у кожен JS-root).
 
+## Console mocking у тестах
+
+`console.log` / `console.error` / `console.warn` — **process-wide** мутації, рівно як `process.cwd()`. Якщо тест перехоплює їх через `const orig = console.log; console.log = (...) => …; try { … } finally { console.log = orig }`, паралельний test файл у `pool: 'forks'` (різний процес) ізольований, але в межах **одного** процесу всі тести у файлі ділять єдиний `console`-об'єкт. Якщо try/finally не виконається (наприклад, асинхронний помилка повз `await`), restore не спрацює і наступні тести втрачають вивід.
+
+Тому:
+
+- **Канон**: `vi.spyOn(console, 'log').mockReturnValue()` (та аналоги для `error`/`warn`/`info`) + `afterEach(() => vi.restoreAllMocks())`. Vitest сам слідкує за scope mock-у і гарантовано відновлює оригінал між тестами, навіть якщо тест кинув виняток.
+- **Заборонено**: ручний store/restore (`const orig = console.log; console.log = stub`). Виняток — коли тест **необхідно** перехопити вивід **до** того, як завантажиться модуль із top-level-логуванням; у цьому випадку фіксуй pattern explicit-коментарем.
+- Якщо потрібен лог зі stub-ом — `const logs = []; vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')))`.
+
+Перевірка — концерн `no-console-store-restore` (`rules/test/js/no-console-store-restore.mjs`): AST-сканер, який ловить присвоєння `console.<method> = …` у `*.test.{js,mjs}`.
+
+## Sandbox-aware тести (Stryker)
+
+Stryker за замовчуванням копіює репо у sandbox-каталог (`reports/stryker/.tmp/sandbox-XXX/`), щоб AST-патчити мутантів без зачеплення робочого дерева. У sandbox **немає `.git/`**, і будь-який тест, що звертається до **реального** git-дерева через `import.meta.url + N≥3 рівнів вгору` (типу `const REPO_ROOT = join(import.meta.dirname, '..', '..', '..', '..', '..')`) фактично адресує sandbox-корінь, а не справжній репо. Це ламає `git rev-parse`/`git ls-files`/перевірки `.n-cursor.json`/CHANGELOG-співставлення — Stryker dry-run падає, мутаційний прогон не стартує, `mutation.json` лишається stale.
+
+**Канон**: тест не повинен залежати від реального git-дерева через `import.meta.url + N≥3 рівнів вгору`. Якщо тест перевіряє git-логіку — ізолюй **повністю**:
+
+```js
+await withTmpDir(async dir => {
+  execFileSync('git', ['init', '-q', '--initial-branch=main'], { cwd: dir })
+  await writeFile(join(dir, 'a.sh'), '#!/bin/sh\n', 'utf8')
+  execFileSync('git', ['add', '-A'], { cwd: dir })
+  expect(listShellScriptPaths(dir)).toEqual(['a.sh'])
+})
+```
+
+Приклад у репо: `rules/text/lint/tests/run-shellcheck.test.mjs` — тест `listShellScriptPaths всередині git-репо`.
+
+**Виняток** — top-level smoke-аудит тести, що **за визначенням** перевіряють інваріанти **живого** репо (структура файлів, узгодженість CHANGELOG з `package.json`, кожне правило має fixture). Приклади: `tests/integration-repo-checks.test.mjs`, `tests/check-rule-fixtures.test.mjs`. Такі тести **не дають додаткового coverage у unit-сенсі** — концерни, які вони перевіряють, уже покриті per-rule unit-тестами (`rules/<rule>/js/tests/`). Захищаємо їх `test.skipIf(env.STRYKER_MUTATOR_WORKER)` від запуску всередині Stryker-sandbox:
+
+```js
+import { env } from 'node:process'
+
+test.skipIf(env.STRYKER_MUTATOR_WORKER)('узгоджені з поточним деревом', async () => {
+  // …перевірки на REPO_ROOT
+})
+```
+
+Перевірка — концерн `sandbox-aware-test` (`rules/test/js/sandbox-aware-test.mjs`): сканер `*.test.{js,mjs}`, який знаходить тести з `import.meta.url`-deep-relative навігацією (4+ `..`-рівнів) і вимагає або `withTmpDir` у їхніх `test`-блоках, або `test.skipIf(env.STRYKER_MUTATOR_WORKER)`.
+
+## `child_process` у тестах: явний `cwd`
+
+Уже зазначено в `## Заборона process.chdir у тестах`. Підсилення: **кожен** виклик `execFile`/`execFileSync`/`spawn`/`spawnSync` у `*.test.{js,mjs}` приймає або **явний `{ cwd: dir }`** (де `dir` — змінна, не `process.cwd()`), або працює з **абсолютними шляхами** до бінарників/fixture-файлів (наприклад `spawnSync('node', [absoluteFixturePath])`). Це гарантує, що мутаційний test-flow у `pool: 'forks'` не страждає від implicit-`process.cwd()`-stride між тестами в одному воркері.
+
 ## Покриття + мутаційне тестування
 
 Канонічна команда — `n-cursor coverage`: збирає метрики покриття (`vitest run --coverage`, `cargo llvm-cov` тощо) і мутаційного тестування (Stryker з vitest-runner + `coverageAnalysis: 'perTest'`, `cargo-mutants`) з усіх активних провайдерів у `.n-cursor.json#rules` і пише `COVERAGE.md` у корінь проєкту. Лок і дедуп — `withLock('coverage', ...)`.

package/scripts/utils/lock-cache-dir.mjs

@@ -0,0 +1,37 @@
+/**
+ * Обчислення директорії стану `withLock` (lock + dedup), СПІЛЬНОЇ для всіх git-worktree.
+ *
+ * Лок-стан (`lock/owner.json`, `result.json`) має бути один на головний checkout
+ * і всі linked-worktree. Інакше важкі команди (eslint/oxlint/jscpd, conftest,
+ * hadolint, per-rule fix), запущені в різних worktree, НЕ серіалізуються —
+ * кожен worktree має власний `node_modules/.cache/`, локи одне одного не бачать,
+ * і паралельний eslint перевантажує CPU/диск на macOS.
+ *
+ * `git rev-parse --git-common-dir` повертає той самий `.git` головного репо з
+ * будь-якого worktree, тож стан кладемо під `<git-common-dir>/n-cursor/<key>`
+ * (всередині `.git` — спільне, ніколи не трекається, переживає `bun i`).
+ * Поза git-репо (git недоступний / каталог не репо) — fallback на per-checkout
+ * `node_modules/.cache/n-cursor/<key>`, як було історично.
+ */
+import { spawnSync } from 'node:child_process'
+import { join, resolve } from 'node:path'
+
+/**
+ * @param {string} key ключ локу (`lint-ga`, `fix-bun`, …)
+ * @param {{cwd?:string, spawn?:typeof import('child_process').spawnSync}} [opts] робоча директорія та sync-виклик git (ін'єкція для тестів)
+ * @returns {string} абсолютний шлях до директорії стану локу для цього ключа
+ */
+export function resolveLockCacheDir(key, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const spawn = opts.spawn ?? spawnSync
+
+  const r = spawn('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8' })
+  const commonDir = r.status === 0 && !r.error ? r.stdout.trim() : ''
+
+  if (commonDir === '') {
+    return join(cwd, 'node_modules/.cache/n-cursor', key)
+  }
+  // commonDir буває відносним (`.git` з кореня) або абсолютним (linked-worktree):
+  // resolve проти cwd дає однаковий абсолютний `<main>/.git` в обох випадках.
+  return join(resolve(cwd, commonDir), 'n-cursor', key)
+}

package/scripts/utils/with-lock.mjs

@@ -6,6 +6,7 @@ import * as fs from 'node:fs'
 import { join } from 'node:path'
 import * as os from 'node:os'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { resolveLockCacheDir } from './lock-cache-dir.mjs'
 import { worktreeFingerprint } from './worktree-fingerprint.mjs'
 
 const DEFAULTS = {
@@ -62,7 +63,7 @@ export function shouldDedup(result, fingerprint, ttl) {
 export async function withLock(key, runFn, opts = {}) {
   const { ttl, staleThreshold, waitTimeout, pollInterval } = { ...DEFAULTS, ...opts }
   const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
-  const cacheDir = opts.cacheDir ?? join(process.cwd(), 'node_modules/.cache/n-cursor', key)
+  const cacheDir = opts.cacheDir ?? resolveLockCacheDir(key)
   const lockDir = join(cacheDir, 'lock')
   const ownerFile = join(lockDir, 'owner.json')
   const resultFile = join(cacheDir, 'result.json')