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

package/rules/test/no-relative-fs-path/main.mjs

@@ -0,0 +1,239 @@
+/** @see ./docs/no-relative-fs-path.md */
+import { readFile } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '@7n/rules/scripts/lib/load-cursor-config.mjs'
+import { parseProgramOrNull, walkAstWithAncestors } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+import { walkDir } from '@7n/rules/scripts/utils/walkDir.mjs'
+
+/**
+ * FS-функції з `node:fs` / `node:fs/promises` / sync-API, які приймають path
+ * у фіксованих позиціях. Map: ім'я функції → масив 0-індексованих позицій
+ * path-аргументів (1-й, 2-й, або обидва — як у `copyFile/rename/symlink/link`).
+ */
+const FS_PATH_ARG_POSITIONS = new Map([
+  ['writeFile', [0]],
+  ['writeFileSync', [0]],
+  ['readFile', [0]],
+  ['readFileSync', [0]],
+  ['appendFile', [0]],
+  ['appendFileSync', [0]],
+  ['mkdir', [0]],
+  ['mkdirSync', [0]],
+  ['rmdir', [0]],
+  ['rmdirSync', [0]],
+  ['rm', [0]],
+  ['rmSync', [0]],
+  ['unlink', [0]],
+  ['unlinkSync', [0]],
+  ['access', [0]],
+  ['accessSync', [0]],
+  ['stat', [0]],
+  ['statSync', [0]],
+  ['lstat', [0]],
+  ['lstatSync', [0]],
+  ['chmod', [0]],
+  ['chmodSync', [0]],
+  ['chown', [0]],
+  ['chownSync', [0]],
+  ['truncate', [0]],
+  ['truncateSync', [0]],
+  ['existsSync', [0]],
+  ['readdir', [0]],
+  ['readdirSync', [0]],
+  ['copyFile', [0, 1]],
+  ['copyFileSync', [0, 1]],
+  ['rename', [0, 1]],
+  ['renameSync', [0, 1]],
+  ['symlink', [0, 1]],
+  ['symlinkSync', [0, 1]],
+  ['link', [0, 1]],
+  ['linkSync', [0, 1]],
+  ['cp', [0, 1]],
+  ['cpSync', [0, 1]],
+  // test-helpers абсолютні-only форми (зайвий захист)
+  ['writeJson', [0]],
+  ['ensureDir', [0]]
+])
+
+/**
+ * Префікси абсолютних шляхів або очевидно-обчислених. Якщо literal починається з
+ * одного з них — це OK (тест свідомо передає absolute чи URL).
+ */
+const ABSOLUTE_PREFIXES = ['/', '\\', 'file:', 'http:', 'https:', 'data:']
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/u
+
+/**
+ * Чи string literal — relative path (тобто баг). Перевіряє лише string-літерали
+ * та template literals без виразів. Виклики `join(...)` / `resolve(...)` /
+ * перемінні з ${} — пропускаємо (припускаємо absolute).
+ * @param {object} arg AST node аргументу
+ * @returns {string|null} relative-path значення (для меседжа), або null якщо OK
+ */
+function extractRelativeLiteralPath(arg) {
+  if (!arg) return null
+  if (arg.type === 'Literal' && typeof arg.value === 'string') {
+    return isRelativeString(arg.value) ? arg.value : null
+  }
+  if (arg.type === 'TemplateLiteral' && arg.expressions.length === 0) {
+    const raw = arg.quasis.map(q => q.value.cooked).join('')
+    return isRelativeString(raw) ? raw : null
+  }
+  // Не string-literal — не аналізуємо (припускаємо обчислений absolute через join/resolve).
+  return null
+}
+
+/**
+ * Чи рядок виглядає як relative path. Порожній рядок — false (це не path).
+ * Windows-disk-letter `C:\…` — absolute, бо містить `:` між літерою і `\`.
+ * @param {string} s рядок-шлях
+ * @returns {boolean} true якщо relative
+ */
+function isRelativeString(s) {
+  if (!s) return false
+  for (const prefix of ABSOLUTE_PREFIXES) {
+    if (s.startsWith(prefix)) return false
+  }
+  // Windows drive letter, наприклад `C:\foo` або `C:/foo`.
+  return !WINDOWS_DRIVE_RE.test(s)
+}
+
+/**
+ * Витягує ім'я FS-функції з callee:
+ *   - `writeFile(…)` → "writeFile" (Identifier callee)
+ *   - `fs.writeFile(…)` чи `fsp.writeFile(…)` → "writeFile" (MemberExpression)
+ *   - `await fs.promises.writeFile(…)` → "writeFile"
+ * Повертає null для будь-якого іншого виклику.
+ * @param {object} callee AST callee node
+ * @returns {string|null} ім'я FS-функції або null
+ */
+function extractFsFunctionName(callee) {
+  if (!callee) return null
+  if (callee.type === 'Identifier') {
+    return FS_PATH_ARG_POSITIONS.has(callee.name) ? callee.name : null
+  }
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property?.type === 'Identifier') {
+    const name = callee.property.name
+    return FS_PATH_ARG_POSITIONS.has(name) ? name : null
+  }
+  return null
+}
+
+/**
+ * Чи файл — JS-тест (`*.test.mjs` / `*.test.js`).
+ * @param {string} absPath абсолютний шлях
+ * @returns {boolean} true якщо файл є тестом
+ */
+function isTestFile(absPath) {
+  const name = basename(absPath)
+  return name.endsWith('.test.mjs') || name.endsWith('.test.js')
+}
+
+/**
+ * Знаходить порушення у одному тестовому файлі.
+ * @param {string} body вміст тесту
+ * @returns {Array<{line: number, fn: string, path: string, argPos: number}>} порушення
+ */
+function findOffendersInBody(body) {
+  const program = parseProgramOrNull(body, 'test.mjs')
+  if (!program) return []
+  const offenders = []
+  const lineOffsets = computeLineOffsets(body)
+  walkAstWithAncestors(program, [], node => {
+    if (node?.type !== 'CallExpression') return
+    const fnName = extractFsFunctionName(node.callee)
+    if (!fnName) return
+    const positions = FS_PATH_ARG_POSITIONS.get(fnName)
+    for (const pos of positions) {
+      const arg = node.arguments?.[pos]
+      const relPath = extractRelativeLiteralPath(arg)
+      if (relPath !== null) {
+        const start = arg?.start ?? node.start ?? 0
+        const line = offsetToLineFromCache(lineOffsets, start)
+        offenders.push({ line, fn: fnName, path: relPath, argPos: pos })
+      }
+    }
+  })
+  return offenders
+}
+
+/**
+ * Кешований offset→line: бінарний пошук по newline-offsets.
+ * @param {string} body source
+ * @returns {number[]} offsets newline char positions
+ */
+function computeLineOffsets(body) {
+  const offsets = [0]
+  let pos = 0
+  for (const ch of body) {
+    if (ch === '\n') offsets.push(pos + 1)
+    pos += 1
+  }
+  return offsets
+}
+
+/**
+ * @param {number[]} offsets newline-offsets
+ * @param {number} offset 0-індекс символу
+ * @returns {number} 1-індексований рядок
+ */
+function offsetToLineFromCache(offsets, offset) {
+  let lo = 0
+  let hi = offsets.length - 1
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi + 1) / 2)
+    if (offsets[mid] <= offset) lo = mid
+    else hi = mid - 1
+  }
+  return lo + 1
+}
+
+/**
+ * Перевіряє, що жоден `*.test.{mjs,js}` файл не передає relative-path як 1-й
+ * (або для `copyFile`/`rename`/`symlink`/`link`/`cp` — 1-й і 2-й) аргумент
+ * у FS-функцію з `node:fs` / `node:fs/promises`.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx Контекст лінту (cwd, перелік файлів тощо).
+ * @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 ignorePaths = await loadCursorIgnorePaths(cwd)
+
+  /** @type {string[]} */
+  const testFiles = []
+  await walkDir(
+    cwd,
+    absPath => {
+      if (isTestFile(absPath)) testFiles.push(absPath)
+    },
+    ignorePaths
+  )
+
+  /** @type {Array<{file: string, line: number, fn: string, path: string, argPos: number}>} */
+  const offenders = []
+  for (const absPath of testFiles) {
+    const body = await readFile(absPath, 'utf8')
+    const found = findOffendersInBody(body)
+    for (const o of found) {
+      offenders.push({ file: relative(cwd, absPath), ...o })
+    }
+  }
+
+  if (offenders.length === 0) {
+    pass(`Жоден з ${testFiles.length} тестових файлів не передає relative-path у FS-функції (test.mdc)`)
+    return reporter.result()
+  }
+
+  for (const { file, line, fn, path, argPos } of offenders) {
+    const which = argPos === 0 ? '1-й аргумент' : `${argPos + 1}-й аргумент`
+    fail(
+      `${file}:${line}: ${fn}() — ${which} '${path}' relative; використовуй join(dir, …) (test.mdc, no-relative-fs-path)`
+    )
+  }
+
+  return reporter.result()
+}

package/rules/test/no-relative-fs-path/no-relative-fs-path.mdc

@@ -0,0 +1,22 @@
+## Заборона відносних шляхів у FS-функціях тестів
+
+**`no-relative-fs-path`** (`rules/test/js/no-relative-fs-path.mjs`) — AST-сканер (`oxc-parser`): знаходить виклики FS-функцій із `node:fs`/`node:fs/promises` (`writeFile`, `copyFile`, `mkdir`, `readFile`, `existsSync`, `rename`, `symlink`, `cp`, … включно з `*Sync`-варіантами та `writeJson`/`ensureDir`-хелперами), де path-аргумент — це **string literal** без префікса `/`, `\`, `file:`, `http(s):`, `data:`, чи Windows-disk-letter `C:\`.
+
+Виклики `copyFile`/`rename`/`symlink`/`link`/`cp` перевіряють **обидва** path-аргументи.
+
+Виклики з обчисленим path (`join(dir, …)`, змінна, template-literal з виразом) пропускаються — припускається, що обчислений шлях абсолютний.
+
+**Чому важливо:** відносний path у FS-виклику означає запис/читання відносно `process.cwd()` на момент виклику. У `pool: 'threads'` (дефолт Vitest) паралельні файли ділять процес — cwd може змінитися між тестами. Інцидент `v1.28.0`: `copyFile(src, 'default.conf.template')` у `tests/check-rule-fixtures.test.mjs` записав файл у production tree замість sandbox.
+
+**Канон:** замінювати відносні шляхи на `join(dir, 'filename')`, де `dir` — абсолютний tmpdir із `withTmpDir`.
+
+**Список FS-функцій, що перевіряються:**
+
+| Функція | Перевірювані аргументи |
+|---|---|
+| `writeFile`, `readFile`, `appendFile`, `mkdir`, `rmdir`, `rm`, `unlink` | 1-й |
+| `access`, `stat`, `lstat`, `chmod`, `chown`, `truncate`, `existsSync`, `readdir` | 1-й |
+| `copyFile`, `rename`, `symlink`, `link`, `cp` | 1-й і 2-й |
+| `writeJson`, `ensureDir` (test-helpers) | 1-й |
+
+Усі `*Sync`-варіанти охоплені аналогічно.

package/rules/test/package_json/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": "package.json",
+      "required": true
+    },
+    "missingMessage": "package.json не існує — створи зі scripts.coverage (test.mdc)"
+  }
+}

package/rules/test/package_json/package_json.mdc

@@ -0,0 +1,18 @@
+## Обовʼязкові скрипти в package.json
+
+Rego-пакет: `test.package_json`
+
+Цільовий файл: `package.json` кожного workspace.
+
+Перевіряє substring-відповідність значень у `scripts`:
+
+| Поле | Має містити |
+|---|---|
+| `scripts.coverage` | `@7n/test coverage` |
+| `scripts.test` | `vitest` і `--bun` (напр. `"bun run --bun vitest run"`) |
+
+Substring-семантика: команди-обгортки (наприклад `bun run pre-coverage && npx @7n/test coverage`, `bun run pre-test && bun run --bun vitest run`) дозволені — головне, щоб потрібні рядки були присутні.
+
+**Чому `--bun` для `scripts.test`:** без Bun-рушія (`bun run vitest` без `--bun`, чи vitest під Node) `import { SQL } from 'bun'` та інші Bun-нативні built-in модулі не резолвуються у forked test-процесах — консьюмери змушені тримати exclude-списки для тестів, що їх торкаються. Під `bun run --bun vitest run` forked pool-процеси успадковують Bun-рушій і резолюція працює без жодних exclude.
+
+Канон підтягується через `--data`: [package.json.contains.json](./template/package.json.contains.json)

package/rules/test/package_json/package_json.rego

@@ -0,0 +1,25 @@
+# Перевірка `package.json` для правила test (test.mdc).
+#
+# Канон надходить через --data: { "template": { "contains": ... } }
+# Структура --data сформована з template/package.json.contains.json.
+# Перевіряємо substring-вимоги до scripts.coverage і scripts.test:
+# рядки мають містити відповідно "@7n/test coverage" і "vitest" + "--bun".
+package test.package_json
+
+import rego.v1
+
+deny contains msg if {
+	some script_name, needles in data.template.contains.scripts
+	actual := object.get(object.get(input, "scripts", {}), script_name, "")
+	some needle in needles
+	not contains(actual, needle)
+	msg := sprintf("package.json: scripts.%s має містити %q (test.mdc)%s", [script_name, needle, explain_suffix(needle)])
+}
+
+# --bun пояснюється окремо: без нього forked vitest pool-процеси не успадковують
+# Bun-рушій, і Bun-нативні built-in модулі (напр. `import { SQL } from 'bun'`)
+# не резолвуються у forked test-процесах.
+explain_suffix(needle) := msg if {
+	needle == "--bun"
+	msg := " — без --bun forked vitest pool-процеси не успадковують Bun-рушій, тож Bun-нативні built-in модулі (напр. import { SQL } from 'bun') не резолвуються у forked test-процесах"
+} else := ""

package/rules/test/package_json/template/package.json.contains.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "coverage": ["@7n/test coverage"],
+    "test": ["vitest", "--bun"]
+  }
+}

package/rules/test/sandbox-aware-test/concern.json

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

package/rules/test/sandbox-aware-test/docs/index.md

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

package/rules/test/sandbox-aware-test/docs/main.md

@@ -0,0 +1,55 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/test/sandbox-aware-test/main.mjs
+docgen:
+  crc: e903e8ef
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+  issues: anchor-miss:(test.mdc),judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл сканує репозиторій для пошуку тестових файлів, що відповідають шаблону JS-тесту. Він аналізує глибину імпорту в цих тестах, перевіряючи наявність механізмів ізоляції, таких як `withTmpDir` або `test.skipIf`. Це гарантує, що тести, які глибоко імпортуються у структуру проєкту, будуть належним чином ізольовані. Маркери повідомлень, пов'язані з тестами, відображаються в Поведінці.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається `main`.
+2. Сканується репозиторій для пошуку файлів, що відповідають шаблону JS-тесту.
+3. Для кожного знайденого тестового файлу аналізується його вміст на наявність глибокої навігації за допомогою `import.meta.dirname` або `import.meta.url`, яка вказує на глибину не менше чотирьох рівнів підкаталогів.
+4. Якщо в тестовому файлі виявлено глибоку навігацію, перевіряється, чи цей файл захищений викликом `withTmpDir` або чи містить конструкцію `test.skipIf` для ізоляції у Stryker-sandbox.
+5. Якщо глибока навігація знайдена, а захист відсутній, файлу позначається як порушення.
+6. При відсутності порушень у всіх тестових файлах, процес вважається успішним.
+7. При виявленні порушень, генерується повідомлення з вказівкою виправлення (використання `withTmpDir` або захист через `test.skipIf`), з посиланням на `test.mdc`.
+
+## Публічний API
+
+Task: Rewrite a technical description into concise, behavioral documentation snippets based on provided rules.
+
+Goal: Produce laconic, behavioral documentation in Ukrainian using clean Markdown, focusing on _What_ and _Why_, not _How_.
+
+Constraints:
+
+1. No introductions or conclusions.
+2. Do not wrap in ```-code blocks.
+3. Forbidden: function signatures, types, parameters list, stdlib module descriptions, regex descriptions, or internal private names.
+4. Mandatory Anchors: Mention message markers in Behavior (per `test.mdc`).
+5. Required Format: Concise markers in the format "name — what it does," using your own words (no direct copying), without types or signatures.
+6. Exact Names: Must use the provided names exactly.
+7. Strict Omission: No header, no generic phrases ("applies logic," "checks correctness")—be specific about what is being applied/checked.
+
+Input List to transform:
+
+- main: Перевіряє, що `*.test.{mjs,js}` з глибокою `import.meta`-навігацією (≥4 `..`-рівнів) захищені `withTmpDir` або `test.skipIf`. Без ізоляції Stryker-sandbox (`reports/stryker/.tmp/sandbox-XXX/`) не має `.git/`, тому git-операції у таких тестах падають і мутаційний прогін не стартує. Без заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.
+
+Applying the transformation now.
+
+main — Встановлює захист для тестів з глибокою навігацією `import.meta` (≥4 `..`-рівнів), гарантуючи, що вони працюють у середовищі, де відсутня ізоляція Stryker-sandbox, що запобігає збоям git-операцій і старту процесу мутації.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/test/sandbox-aware-test/main.mjs

@@ -0,0 +1,89 @@
+/** @see ./docs/sandbox-aware-test.md */
+import { readFile } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '@7n/rules/scripts/lib/load-cursor-config.mjs'
+import { walkDir } from '@7n/rules/scripts/utils/walkDir.mjs'
+
+/**
+ * Чи файл — JS-тест (`*.test.mjs` / `*.test.js`).
+ * @param {string} absPath абсолютний шлях
+ * @returns {boolean} `true` для `.test.{mjs,js}` файлів
+ */
+function isTestFile(absPath) {
+  const name = basename(absPath)
+  return name.endsWith('.test.mjs') || name.endsWith('.test.js')
+}
+
+/**
+ * Чи файл містить `import.meta.dirname`/`import.meta.url`-навігацію з ≥4 `..`-рівнів.
+ * Для кожного вживання `import.meta.dirname|url` рахує `'..'`/`".."` у вікні 400 символів.
+ * @param {string} body вміст файлу
+ * @returns {boolean} `true` якщо знайдено глибоку навігацію
+ */
+function hasDeepMetaNavigation(body) {
+  const RE = /import\.meta\.(?:dirname|url)\b/gu
+  let match
+  while ((match = RE.exec(body)) !== null) {
+    const chunk = body.slice(match.index, match.index + 400)
+    const dots = (chunk.match(/'\.\.'|"\.\."/gu) ?? []).length
+    if (dots >= 4) return true
+  }
+  return false
+}
+
+/** Захист через тимчасову пісочницю — `withTmpDir`. */
+const WITH_TMP_DIR_RE = /\bwithTmpDir\b/u
+
+/** Захист через явний skip у Stryker-sandbox (`test.skipIf`). */
+const SKIP_IF_STRYKER_RE = /\btest\.skipIf\s*\(\s*(?:env|process\.env)\.STRYKER_MUTATOR_WORKER\b/u
+
+/**
+ * Перевіряє, що `*.test.{mjs,js}` з глибокою `import.meta`-навігацією (≥4 `..`-рівнів)
+ * захищені `withTmpDir` або `test.skipIf(env.STRYKER_MUTATOR_WORKER)`.
+ * Без ізоляції Stryker-sandbox (`reports/stryker/.tmp/sandbox-XXX/`) не має `.git/`,
+ * тому git-операції у таких тестах падають і мутаційний прогін не стартує.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст lint-прогону.
+ * @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 ignorePaths = await loadCursorIgnorePaths(cwd)
+
+  /** @type {string[]} */
+  const testFiles = []
+  await walkDir(
+    cwd,
+    absPath => {
+      if (isTestFile(absPath)) testFiles.push(absPath)
+    },
+    ignorePaths
+  )
+
+  /** @type {string[]} */
+  const offenders = []
+  for (const absPath of testFiles) {
+    const body = await readFile(absPath, 'utf8')
+    if (!hasDeepMetaNavigation(body)) continue
+    if (WITH_TMP_DIR_RE.test(body) || SKIP_IF_STRYKER_RE.test(body)) continue
+    offenders.push(relative(cwd, absPath))
+  }
+
+  if (offenders.length === 0) {
+    pass(`Усі ${testFiles.length} тестові файли sandbox-aware (test.mdc)`)
+    return reporter.result()
+  }
+
+  for (const file of offenders) {
+    fail(
+      `${file}: import.meta deep navigation (≥4 рівні ..) без ізоляції — ` +
+        `оберни у withTmpDir() або захисти test.skipIf(env.STRYKER_MUTATOR_WORKER) (test.mdc, sandbox-aware-test)`
+    )
+  }
+
+  return reporter.result()
+}

package/rules/test/sandbox-aware-test/sandbox-aware-test.mdc

@@ -0,0 +1,28 @@
+## 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-rules.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)`.

package/rules/test/stryker_config/concern.json

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

package/rules/test/stryker_config/data/stryker_config/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/rules/test/stryker_config/data/stryker_config
+resource: plugins/lang-js/rules/test/stryker_config/data/stryker_config/
+---
+
+# npm/rules/test/stryker_config/data/stryker_config
+
+| Файл                                                              | Тип       |
+| ----------------------------------------------------------------- | --------- |
+| [stryker-vue-macros-ignorer.mjs](stryker-vue-macros-ignorer.md)   | JS Module |
+| [stryker.config.baseline.mjs](stryker.config.baseline.md)         | JS Module |
+| [stryker.config.vue.baseline.mjs](stryker.config.vue.baseline.md) | JS Module |

package/rules/test/stryker_config/data/stryker_config/docs/stryker-vue-macros-ignorer.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: stryker-vue-macros-ignorer.mjs
+resource: plugins/lang-js/rules/test/stryker_config/data/stryker_config/stryker-vue-macros-ignorer.mjs
+docgen:
+  crc: 30a5e9f9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Конфігурує механізм Stryker для ігнорування мутацій, які виникають при викликах макросів Vue (`defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`, `defineOptions`) у середовищі `<script setup>`. Це запобігає падінню `@vue/compiler-sfc`, оскільки мутатори стандартного плагіна Stryker обгортають аргументи макросів у тернарний coverage-вираз, що порушує статичний аналіз. Механізм реалізується шляхом реєстрації плагіна у `strykerPlugins: Plugin[]` у `plugin-loader.js` та активації ігнорування за ім'ям `'vue-macros'` у `stryker.config.mjs`.
+
+## Поведінка
+
+Поведінка:
+shouldIgnore: Позначає виклик макроса Vue `<script setup>` як ігнорований для мутації Stryker.
+strykerPlugins: Визначає набір плагінів для Stryker, включаючи ігнорувальник для макросів Vue.
+
+## Публічний API
+
+shouldIgnore — Встановлює, які мутації викликів Vue `<script setup>`-макросів (`defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`, `defineOptions`) мають бути пропущені аналізом Stryker.
+strykerPlugins — Забезпечує механізм експорту плагінів (`Plugin[]`) для доповнення процесу сканування коду.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/test/stryker_config/data/stryker_config/docs/stryker.config.baseline.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: stryker.config.baseline.mjs
+resource: plugins/lang-js/rules/test/stryker_config/data/stryker_config/stryker.config.baseline.mjs
+docgen:
+  crc: 2c7c9c37
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл забезпечує виконання тестових сценаріїв для виявлення дефектів у коді. Він використовує `vitest` для тестування та інтегрує Stryker для мутаційного тестування. Процес збору та збереження результатів мутацій відбувається відповідно до конфігурацій `mutation.json` та `incremental.json`.
+
+## Поведінка
+
+1. Використовує `vitest` як рушій для виконання тестів.
+2. Визначає конфігураційний файл `vitest.config.mjs` для `vitest`.
+3. При зміні коду Stryker запускає лише ті тести, які покривають змінену лінію, що підвищує швидкість порівняно з запуском всього набору тестів для кожного мутанта.
+4. Встановлює тимчасову директорію для звітів як `reports/stryker/.tmp`.
+5. Виводить результати у форматі JSON та у вигляді чистого тексту.
+6. Зберігає деталі мутацій у файлі `reports/stryker/mutation.json`.
+7. Увімкнено інкрементальний режим, що дозволяє відновлювати результати після збоїв, забезпечуючи значне прискорення при повторних запусках.
+8. Процес роботи спирається на конфігураційні файли `mutation.json` та `incremental.json`.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/rules/test/stryker_config/data/stryker_config/docs/stryker.config.vue.baseline.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: stryker.config.vue.baseline.mjs
+resource: plugins/lang-js/rules/test/stryker_config/data/stryker_config/stryker.config.vue.baseline.mjs
+docgen:
+  crc: 579865c3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Огляд
+Цей файл відповідає за конфігурацію та запуск мутаційного аналізу коду за допомогою Stryker. Він вимірює якість тестування шляхом порівняння покриття вихідного коду тестами. Для налаштування опирається на `mutation.json` та `incremental.json`.
+
+Поведінка
+Тестове середовище налаштовується для використання Vitest відповідно до конфігураційного файлу Vitest. Запуск мутаційного аналізу здійснюється за допомогою Stryker, який обробляє кожен тест окремо для підвищення швидкості порівняно із запуском всього тестового набору. Згенеровані результати зберігаються у текстовому та JSON-форматах, причому JSON-звіт поміщається у `reports/stryker/mutation.json`. Для оптимізації подальших аналізів використовується `reports/stryker/incremental.json` для підтримки стану аналізу. Також реалізовано ігнорування мутацій у Vue-макросах `<script setup>` за допомогою спеціального локального плагіна, що запобігає збоям компіляції SFC.
+
+## Поведінка
+
+1. Визначає середовище виконання тестів як Vitest.
+2. Налаштовує відповідність до файлу конфігурації Vitest.
+3. Запускає Stryker для аналізу коду, обробляючи кожен тест окремо, що підвищує швидкість порівняно з запуском всього тестового набору.
+4. Створює тимчасовий каталог для звітів Stryker.
+5. Збирає результати в текстовий та JSON-формати, зберігаючи JSON-звіт у `reports/stryker/mutation.json`.
+6. Дозволяє відновлення результатів попередніх запусків за допомогою файлу `reports/stryker/incremental.json`, що прискорює повторні запуски.
+7. Використовує спеціальний локальний плагін для ігнорування мутацій у макросах Vue `<script setup>`, щоб уникнути збоїв при компіляції SFC.
+8. Визначає мутації Vue-макросів як ігноровані.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)