@7n/rules 1.0.0

package/scripts/utils/ast-scan-utils.mjs

@@ -0,0 +1,206 @@
+/**
+ * Спільні утиліти для AST-сканерів JS/TS на oxc-parser:
+ * вибір мови за розширенням, переклад зміщення в номер рядка, стиснення сніпета,
+ * обхід AST з предками, парсинг програми з безпечним поверненням `null`,
+ * розпізнавання типових вузлів (функцій, `*.join(...)`),
+ * робота з `TemplateLiteral` (текст quasis, контекст SQL-списку).
+ *
+ * Використовується сканерами у `rules/<rule>/js/...` (наприклад,
+ * `rules/js-bun-db/js/safety/bun-sql-scan.mjs`, `rules/js-mssql/js/deps/mssql-pool-scan.mjs`,
+ * `rules/js-run/js/runtime/*-scan.mjs`) для уникнення дублювання boilerplate.
+ */
+import { parseSync } from 'oxc-parser'
+
+const SQL_LIST_CONTEXT_RE = /\b(in|values)\b\s*\(/iu
+
+/**
+ * Мова для Oxc за шляхом файлу (розширення).
+ * @param {string} filePath віртуальний або реальний шлях до файлу
+ * @returns {'js' | 'jsx' | 'ts' | 'tsx'} значення опції `lang` для `parseSync`
+ */
+export function langFromPath(filePath) {
+  const lower = filePath.toLowerCase()
+  if (lower.endsWith('.tsx')) return 'tsx'
+  if (lower.endsWith('.ts') || lower.endsWith('.mts') || lower.endsWith('.cts')) return 'ts'
+  if (lower.endsWith('.jsx')) return 'jsx'
+  return 'js'
+}
+
+/**
+ * Номер рядка (1-based) за зміщенням у буфері.
+ * @param {string} content повний текст файлу
+ * @param {number} offset байтове зміщення початку фрагмента
+ * @returns {number} номер рядка від 1
+ */
+export function offsetToLine(content, offset) {
+  let line = 1
+  const n = Math.min(offset, content.length)
+  for (let i = 0; i < n; i++) {
+    if (content.codePointAt(i) === 10) line++
+  }
+  return line
+}
+
+/**
+ * Стискає пробіли для повідомлення про порушення.
+ * @param {string} s фрагмент коду
+ * @returns {string} скорочений однорядковий рядок
+ */
+export function normalizeSnippet(s) {
+  return s.replaceAll(/\s+/gu, ' ').trim().slice(0, 180)
+}
+
+/**
+ * Чи є вузол функцією.
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це будь-який вузол-функція
+ */
+export function isFunctionNode(node) {
+  return (
+    !!node &&
+    typeof node === 'object' &&
+    typeof node.type === 'string' &&
+    (node.type === 'FunctionDeclaration' ||
+      node.type === 'FunctionExpression' ||
+      node.type === 'ArrowFunctionExpression')
+  )
+}
+
+/**
+ * Рекурсивний обхід AST з предками, щоб визначати контекст (всередині функції чи ні).
+ * @param {unknown} node поточний вузол
+ * @param {unknown[]} ancestors масив предків від кореня до parent
+ * @param {(n: Record<string, unknown>, ancestors: unknown[]) => void} visit відвідувач для вузлів з `type`
+ * @returns {void}
+ */
+export function walkAstWithAncestors(node, ancestors, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkAstWithAncestors(item, ancestors, visit)
+    return
+  }
+
+  const rec = /** @type {Record<string, unknown>} */ (node)
+  if (typeof rec.type === 'string') {
+    visit(rec, ancestors)
+    ancestors = [...ancestors, rec]
+  }
+
+  for (const key of Object.keys(node)) {
+    if (key === 'parent') continue
+    const v = rec[key]
+    if (v && typeof v === 'object') {
+      walkAstWithAncestors(v, ancestors, visit)
+    }
+  }
+}
+
+/**
+ * Парсить файл і повертає `program` або null, якщо є синтаксичні помилки чи виняток.
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
+ * @returns {unknown | null} `result.program` або null, якщо парсинг не вдався
+ */
+export function parseProgramOrNull(content, virtualPath) {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return null
+  }
+  if (result.errors?.length) return null
+  return result.program
+}
+
+/**
+ * Парсить файл і повертає `{ program, comments }` або null. Окремий вхід для перевірок,
+ * яким потрібні коментарі (наприклад, маркер `// allow-unsafe: ...` біля виклику) —
+ * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
+ * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null} `program` + список коментарів, або `null` якщо парсер віддав помилки/exception
+ */
+export function parseProgramAndCommentsOrNull(content, virtualPath) {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return null
+  }
+  if (result.errors?.length) return null
+  return {
+    program: result.program,
+    comments: Array.isArray(result.comments) ? result.comments : []
+  }
+}
+
+/**
+ * Чи це `.join(...)` виклик (типово для динамічних списків у SQL).
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це CallExpression `*.join(...)`
+ */
+export function isJoinCall(node) {
+  if (!node || node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return false
+  const prop = callee.property
+  return !!prop && prop.type === 'Identifier' && prop.name === 'join'
+}
+
+/**
+ * Текст quasis у TemplateLiteral (без expressions).
+ * @param {unknown} template TemplateLiteral
+ * @returns {string} обʼєднаний raw-текст
+ */
+export function templateQuasisText(template) {
+  if (!template || template.type !== 'TemplateLiteral') return ''
+  const quasis = template.quasis
+  if (!Array.isArray(quasis) || quasis.length === 0) return ''
+  let out = ''
+  for (const q of quasis) {
+    if (!q || typeof q !== 'object') continue
+    const value = q.value
+    if (!value || typeof value !== 'object') continue
+    if (typeof value.raw === 'string') out += value.raw
+  }
+  return out
+}
+
+/**
+ * Чи виглядає TemplateLiteral як SQL-контекст зі списком (IN/VALUES (...)).
+ * @param {unknown} template TemplateLiteral
+ * @returns {boolean} true, якщо текст містить `IN (` або `VALUES (`
+ */
+export function isSqlListContextTemplate(template) {
+  return SQL_LIST_CONTEXT_RE.test(templateQuasisText(template))
+}
+
+/**
+ * Перевіряє, чи це виклик `require('<module>')` з рядковим аргументом.
+ * Спільне для сканерів імпортів (`bunyan-imports`, `redis-imports`, ...).
+ * @param {Record<string, unknown> | null | undefined} node вузол AST
+ * @returns {string | null} ім'я модуля з аргументу, інакше `null`
+ */
+export function requireCallModule(node) {
+  if (!node || node.type !== 'CallExpression') return null
+  const callee = node.callee
+  if (!callee || callee.type !== 'Identifier' || callee.name !== 'require') return null
+  const arg = node.arguments?.[0]
+  if (!arg || arg.type !== 'Literal' || typeof arg.value !== 'string') return null
+  return arg.value
+}
+
+/**
+ * Перевіряє, чи це динамічний `import('<module>')` з рядковим аргументом.
+ * Спільне для сканерів імпортів.
+ * @param {Record<string, unknown> | null | undefined} node вузол AST
+ * @returns {string | null} ім'я модуля, інакше `null`
+ */
+export function dynamicImportModule(node) {
+  if (!node || node.type !== 'ImportExpression') return null
+  const src = node.source
+  if (!src || src.type !== 'Literal' || typeof src.value !== 'string') return null
+  return src.value
+}

package/scripts/utils/docs/apply-to-files.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: apply-to-files.mjs
+resource: npm/scripts/utils/apply-to-files.mjs
+docgen:
+  crc: 8b930c27
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: best-of-2:retry-won,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей `fix-*.mjs` є спільним helper для T0-фіксерів. Він застосовує текстовий трансформер до унікальних файлів, що містять перелічені порушення (violations). Мета — усунути дублювання логіки, раніше присутньої в `rust/toolchain_cache`, `tauri/linux_deps` та `ga/workflows`. Механізм працює з використанням кешування протягом одного прогону та забезпечує fail-safe перехоплення помилок, не дозволяючи виняткам виходити за межі модуля. При виявленні зміненого вмісту, він записує зміни до відповідного файлу.
+
+## Поведінка
+
+1. Збирає унікальний список файлів з наданого переліку порушень.
+2. Для кожного файлу:
+    а. Зчитує вміст файлу.
+    б. Якщо зчитування не вдалося, пропускає файл.
+    в. Викликає функцію-трансформер, надаючи їй вміст файлу, щоб отримати потенційно змінений вміст.
+    г. Якщо трансформер повернув новий вміст, відмінний від оригінального, виконує наступне:
+        а. Фіксує запис про зміну у контексті лінту.
+        б. Записує новий вміст у файл, перезаписуючи старий.
+        в. Додає абсолютний шлях файлу до списку змінених файлів.
+3. Повертає список абсолютної шляхів усіх файлів, у яких були внесені зміни.
+
+## Публічний API
+
+applyToFiles — створює інструмент для обробки файлів, який надає доступ до даних, специфічних для кожного файлу.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.

package/scripts/utils/docs/ast-extract.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: ast-extract.mjs
+resource: npm/scripts/utils/ast-extract.mjs
+docgen:
+  crc: 08ce9aec
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль аналізує вихідний код, витягуючи ключові структурні елементи. Він дозволяє отримати інформацію про імпорти, експорти та назви верхнерівневих функцій, використовуючи функції `f`, `extractContextFromSource` та `extractContext`. Функціонал працює з кодом, наданим безпосередньо або шляхом до файлу. Процес аналізу реалізований з механізмом перехоплення помилок (fail-safe), гарантуючи, що винятки не будуть викинуті назовні.
+
+## Поведінка
+
+f: витягує структурований зріз коду, включаючи імпорти, експорти та назви верхнерівневих функцій.
+extractContextFromSource: витягує структурований зріз коду з наданого вмісту, визначуючи імпорти, експорти та назви верхнерівневих функцій.
+extractContext: читає вміст файлу за вказаним шляхом і витягує з нього структуровані факти коду, обробляючи помилки під час читання.
+
+## Публічний API
+
+- f — основна логіка модуля
+- extractContextFromSource — аналізує структуру коду, наданого як текст, для отримання його граматичного представлення, не звертаючись до файлової системи
+- extractContext — читає вміст файлу та аналізує його структуру, повертаючи помилку читання замість помилки виконання
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/utils/docs/ast-scan-utils.md

@@ -0,0 +1,54 @@
+---
+type: JS Module
+title: ast-scan-utils.mjs
+resource: npm/scripts/utils/ast-scan-utils.mjs
+docgen:
+  crc: 0f9b4a21
+---
+
+Цей файл містить утиліти для AST-сканерів JavaScript та TypeScript, що використовуються для аналізу коду та виявлення потенційних проблем. Він надає інструменти для обробки AST, перетворення даних та взаємодії з різними типами вузлів, забезпечуючи основу для створення правил безпеки та аналізу коду. Ці утиліти спрощують розробку сканерів, усуваючи необхідність повторного написання boilerplate-коду.
+
+## Поведінка
+
+langFromPath: Визначає мову (js, jsx, ts, tsx) на основі розширення файлу.
+offsetToLine: Перетворює байтове зміщення в номер рядка для текстового файлу.
+normalizeSnippet: Стискає текстовий фрагмент до 180 символів, видаляючи пробіли.
+isFunctionNode: Визначає, чи є вузол AST функцією (FunctionDeclaration, FunctionExpression, ArrowFunctionExpression).
+walkAstWithAncestors: Рекурсивно обходить AST, збираючи предки вузла.
+parseProgramOrNull: Парсує файл JS/TS та повертає програму або null, якщо є помилки.
+parseProgramAndCommentsOrNull: Парсує файл JS/TS та повертає програму та список коментарів, або null, якщо є помилки.
+isJoinCall: Визначає, чи є виклик `join` у TemplateLiteral.
+templateQuasisText: Збирає текст quasis з TemplateLiteral.
+isSqlListContextTemplate: Визначає, чи є TemplateLiteral контекстом SQL-списку (IN/VALUES).
+requireCallModule: Витягує ім'я модуля з аргументу виклику `require`.
+dynamicImportModule: Витягує ім'я модуля з аргументу виклику `import`.
+
+## Публічний API
+
+- langFromPath — Визначає мову Oxc на основі розширення файлу.
+- offsetToLine — Перетворює зміщення в буфер на номер рядка.
+- normalizeSnippet — Форматує текст повідомлення про порушення, видаляючи зайві пробіли.
+- isFunctionNode — Визначає, чи є вузол у абстрактному синтаксичному дереві (AST) функцією.
+- walkAstWithAncestors — Рекурсивно обходить AST, враховуючи контекст (чи знаходиться вузол всередині функції).
+- parseProgramOrNull — Парсить файл та повертає AST, якщо успішно, або `null` у разі помилки.
+- parseProgramAndCommentsOrNull — Парсить файл та повертає об'єкт з AST та коментарями, або `null` у разі помилки.
+- isJoinCall — Визначає, чи є виклик `.join` (для динамічних списків SQL).
+- templateQuasisText — Витягує текст з `quasis` у `TemplateLiteral`, ігноруючи вирази.
+- isSqlListContextTemplate — Визначає, чи є `TemplateLiteral` контекстом SQL-списку (наприклад, `IN` або `VALUES`).
+- requireCallModule — Перевіряє, чи є виклик `require` з рядковим ім'ям.
+
+## Гарантії поведінки
+
+- `langFromPath` повертає назву мови JavaScript або TypeScript на основі розширення файлу.
+- `langFromPath` повертає `null`, якщо розширення файлу не підтримується.
+- `offsetToLine` перетворює зміщення в коді на номер рядка.
+- `offsetToLine` повертає `null`, якщо зміщення недійсне.
+- `normalizeSnippet` стискає текст сніпета.
+- `normalizeSnippet` повертає `null`, якщо не вдалося стиснути сніпет.
+- `isFunctionNode` визначає, чи є вузол AST функцією.
+- `isFunctionNode` повертає `true` якщо вузол є функцією, інакше `false`.
+- `walkAstWithAncestors` обходить AST, враховуючи предки вузлів.
+- `walkAstWithAncestors` не повертає значень.
+- `parseProgramOrNull` парсує програму та повертає її як AST або `null`, якщо парсинг не вдається.
+- `parseProgramOrNull` повертає `null`, якщо програма не може бути успішно розпарсена.
+- `parseProgramAndCommentsOrNull` парсує програму

package/scripts/utils/docs/ensure-gitignore-entries.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: ensure-gitignore-entries.mjs
+resource: npm/scripts/utils/ensure-gitignore-entries.mjs
+docgen:
+  crc: 35e65c1b
+---
+
+Цей модуль відповідає за оновлення файлу `.gitignore` у корені проєкту. Він забезпечує idempotent додавання нових правил ігнорування, перевіряючи їхню наявність перед доповненням. Це необхідно для підтримки консистентності правил ігнорування в проєкті та інтеграції з інструментами тестування, такими як Stryker.
+
+## Поведінка
+
+1.  Отримує вхідні дані: каталог проєкту, список шаблонів для `.gitignore`, такий же заголовок для коментаря.
+2.  Перевіряє наявність `.gitignore` у вказаному каталозі.
+3.  Якщо `.gitignore` відсутній, створює новий файл з порожнім вмістом.
+4.  Зчитує вміст `.gitignore` (якщо він існує).
+5.  Розбиває вміст `.gitignore` на окремі рядки, видаляє пробіли на початку та в кінці кожного рядка.
+6.  Перетворює отримані рядки у набір (Set) для швидкої перевірки на наявність.
+7.  Визначає список шаблонів, яких немає у `.gitignore`.
+8.  Якщо список шаблонів, яких немає, порожній, повертає порожній масив доданих шаблонів.
+9.  Формує новий рядок для додавання у `.gitignore`. Рядок починається з заголовка, потім додає шаблони з порожнього списку, і завершується символом нового рядка.
+10. Додає сформований рядок до вмісту `.gitignore`.
+11. Записує змінений вміст `.gitignore` назад у файл.
+12. Повертає список шаблонів, які були додані до `.gitignore`.
+
+## Гарантії поведінки
+
+- Якщо файл `.gitignore` існує, то записи додаються лише якщо вони відсутні.
+- Якщо файл `.gitignore` не існує, то створюється новий файл `.gitignore` з доданими записами та header-коментарем.
+- Записи додаються лише після видалення будь-яких пробілів з початку та кінця кожного запису.
+- Якщо запис вже присутній у файлі `.gitignore`, то він не буде доданий повторно.
+- Кеш не використовується.

package/scripts/utils/docs/find-package-json-paths.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: find-package-json-paths.mjs
+resource: npm/scripts/utils/find-package-json-paths.mjs
+docgen:
+  crc: 06c208de
+---
+
+Цей файл забезпечує спільну утиліту для збору всіх файлів `package.json` у дереві проєкту, ігноруючи вказані каталоги. Він сортує знайдені шляхи пакетів за відносним розташуванням, що полегшує їх подальше використання в скриптах перевірки. Це дозволяє уникнути дублювання коду з інших інструментів перевірки та спрощує процес збору інформації про залежності.
+
+## Поведінка
+
+1.  Отримує абсолютний шлях до кореня репозиторію та список абсолютних шляхів каталогів, які потрібно ігнорувати.
+2.  Ініціалізує порожній масив для зберігання шляхів до файлів `package.json`.
+3.  Використовує обхід каталогу, починаючи з кореня репозиторію, для пошуку файлів `package.json`.
+4.  Для кожного файлу `package.json` у каталозі, перевіряє, чи він відповідає критеріям включення (не знаходиться в ігнорованих каталогах).
+5.  Якщо файл відповідає критеріям, додає його абсолютний шлях до масиву шляхів.
+6.  Після завершення обходу каталогу, сортує масив шляхів до файлів `package.json` за відносним шляхом відносно кореня репозиторію.
+7.  Повертає відсортований масив абсолютних шляхів до файлів `package.json`.
+
+## Публічний API
+
+- findAllPackageJsonPaths — Знаходить всі файли `package.json` в каталозі та підкаталогах.
+
+## Гарантії поведінки
+
+- Функція повертає масив рядків, що представляють відносні шляхи до всіх `package.json` файлів, знайдених у дереві.
+- Функція ігнорує каталоги, перелічені в аргументі `walkDir`.
+- Функція не гарантує, що `package.json` файли будуть доступні.
+- Функція не використовує кешування.

package/scripts/utils/docs/index.md

@@ -0,0 +1,23 @@
+---
+type: Directory Index
+title: npm/scripts/utils
+resource: npm/scripts/utils/
+---
+
+| Файл                                                        | Тип       |
+| ----------------------------------------------------------- | --------- |
+| [apply-to-files.mjs](apply-to-files.md)                     | JS Module |
+| [ast-extract.mjs](ast-extract.md)                           | JS Module |
+| [ast-scan-utils.mjs](ast-scan-utils.md)                     | JS Module |
+| [ensure-gitignore-entries.mjs](ensure-gitignore-entries.md) | JS Module |
+| [find-package-json-paths.mjs](find-package-json-paths.md)   | JS Module |
+| [lock-cache-dir.mjs](lock-cache-dir.md)                     | JS Module |
+| [pass.mjs](pass.md)                                         | JS Module |
+| [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md)     | JS Module |
+| [resolve-cmd.mjs](resolve-cmd.md)                           | JS Module |
+| [resolve-js-root.mjs](resolve-js-root.md)                   | JS Module |
+| [test-helpers.mjs](test-helpers.md)                         | JS Module |
+| [walk-cache.mjs](walk-cache.md)                             | JS Module |
+| [walkDir.mjs](walkDir.md)                                   | JS Module |
+| [with-lock.mjs](with-lock.md)                               | JS Module |
+| [worktree-fingerprint.mjs](worktree-fingerprint.md)         | JS Module |

package/scripts/utils/docs/lock-cache-dir.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: lock-cache-dir.mjs
+resource: npm/scripts/utils/lock-cache-dir.mjs
+docgen:
+  crc: fd0d0041
+---
+
+Цей файл визначає структуру каталогу кешування блоків для git-worktree, забезпечуючи унікальний стан локу для кожного головного checkout та пов'язаних worktree. Він використовується для серіалізації запуску інструментів аналізу коду в різних worktree, запобігаючи конфліктам та забезпечуючи ефективну роботу. Створена структура кешування гарантує, що всі worktree мають доступ до одного і того ж стану локу, що необхідно для коректної серіалізації процесів аналізу.
+
+## Поведінка
+
+1.  Визначається ключ локу, що представляє конкретну задачу або конфігурацію.
+2.  Визначається робоча директорія, яка використовується для виконання операцій.
+3.  Використовується команда `git rev-parse --git-common-dir` для визначення спільного каталогу `.git`. Якщо команда успішна, отримується абсолютний шлях до каталогу `.git`. Якщо команда не вдалася, то цей шлях не визначено.
+4.  Якщо спільний каталог `.git` визначено, то обчислюється шлях до директорії стану локу, використовуючи спільний каталог, назву ключа та префікс `n-rules`.
+5.  Якщо спільний каталог `.git` не визначено, то обчислюється шлях до директорії стану локу, використовуючи робочу директорію та префікс `node_modules/.cache/n-rules`.
+6.  Повертається обчислений абсолютний шлях до директорії стану локу.
+
+## Гарантії поведінки
+
+- Спільний лок-стан для всіх git-worktree визначається шляхом `<git-common-dir>/n-rules/<key>`.
+- Якщо git недоступний, використовується кеш `node_modules/.cache/n-rules/<key>`.
+- Кеш використовується для збереження стану протягом одного прогону.
+- Стан локу (`lock/owner.json`, `result.json`) є унікальним для кожного головного checkout та всіх linked-worktree.
+- Унікальний стан локу запобігає паралельній роботі інструментів серіалізації.
+- Унікальний стан локу гарантує, що кожен worktree має власний `node_modules/.cache/`.
+- Кеш не відстежується git.
+- Кеш не впливає на стан локу.

package/scripts/utils/docs/pass.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: pass.mjs
+resource: npm/scripts/utils/pass.mjs
+docgen:
+  crc: 0f69dfba
+---
+
+Цей файл містить функцію для виведення повідомлень про успіх у консоль. Функція використовується в скриптах перевірки для інформування користувача про успішне завершення операцій. Вона забезпечує чіткий візуальний сигнал про успіх, що полегшує інтерпретацію результатів перевірки.
+
+## Поведінка
+
+1.  Викликається функція `pass`.
+2.  Функція `pass` друкує рядок у консоль.
+3.  Рядок починається з символу галочки (✅).
+4.  Після символу галочки друкується переданий текст повідомлення.
+5.  Функція не має жодного впливу на стан системи.
+6.  Функція не взаємодіє з будь-якими зовнішніми ресурсами.
+
+## Публічний API
+
+- pass: Допоміжна функція для скриптів перевірки.
+  Друкує в консоль рядок успіху з галочкою (✅).
+
+## Гарантії поведінки
+
+- Виводить у консоль рядок із символом ✅.
+- Не виконує жодних операцій.
+- Не використовує жодного кешу.

package/scripts/utils/docs/resolve-cargo-manifest.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: resolve-cargo-manifest.mjs
+resource: npm/scripts/utils/resolve-cargo-manifest.mjs
+docgen:
+  crc: af1efa42
+---
+
+Цей файл визначає шлях до файлу Cargo.toml проєкту, незалежно від того, чи це кореневий Cargo.toml або один з підкаталогів workspace-у, особливо з урахуванням Tauri-патерну. Він служить утилітою для coverage-провайдера та test-концерну cargo_mutants_config, повертаючи `null` у разі невдачі для обробки ситуації без виключень. Це забезпечує гнучкий спосіб доступу до конфігурації проєкту Cargo.
+
+## Поведінка
+
+resolveCargoManifest: Повертає абсолютний шлях до Cargo.toml у проєкті, починаючи з кореня, або в підкаталозі `src-tauri` якщо він існує. Повертає `null`, якщо Cargo.toml не знайдено.
+resolveAllCargoManifests: Повертає масив абсолютних шляхів до всіх знайдених Cargo.toml у проєкті, пріоритет надається `src-tauri` підкаталогам, а потім загальним Cargo.toml. Повертає порожній масив, якщо жодного Cargo.toml не знайдено.
+
+## Публічний API
+
+- resolveCargoManifest: Отримує інформацію про маніфест Cargo.toml з конкретного каталогу.
+- resolveAllCargoManifests: Знаходить всі файли Cargo.toml в проєкті, починаючи з кореневого каталогу та підкаталогів workspace, повертаючи їх вміст.
+
+## Гарантії поведінки
+
+- Функція повертає `null` у разі невдачі.
+- Функція не викидає винятки.
+- Функція не використовує кешування.
+- Функція обробляє шляхи до `Cargo.toml` у каталогах `cwd/Cargo.toml` та підкаталогах workspace (`<workspace>/src-tauri/`).
+- Функція не повертає жодного значення, якщо всі шляхи до `Cargo.toml` успішно оброблені.

package/scripts/utils/docs/resolve-cmd.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: resolve-cmd.mjs
+resource: npm/scripts/utils/resolve-cmd.mjs
+docgen:
+  crc: 4f119131
+---
+
+Цей файл надає функцію `resolveCmd` для отримання абсолютного шляху до виконуваного файлу, який відповідає заданій команді. Це дозволяє викликати зовнішні інструменти, використовуючи повний шлях до файлу, а не команду з змінної PATH. Це корисно для забезпечення чіткої та однозначної ідентифікації виконуваного файлу.
+
+## Поведінка
+
+1.  Перевіряє, чи існує команда в змінній PATH системи.
+2.  Визначає інструмент для пошуку команди: `where` на Windows та `which` на інших платформах.
+3.  Запускає визначений інструмент з командою для пошуку.
+4.  Перевіряє код повернення інструменту. Якщо код не 0 або є помилка, команда не знайдена, повертає `null`.
+5.  Якщо команда знайдена, витягує перший рядок результату.
+6.  Видаляє пробіли з рядка.
+7.  Повертає витягнутий рядок як абсолютний шлях до команди. Якщо рядок порожній, повертає `null`.
+
+## Публічний API
+
+resolveCmd — Знаходить шлях до виконуваного файлу команди в системному PATH та повертає його. Якщо команда не знайдена, повертає null.
+
+## Гарантії поведінки
+
+- Функція повертає абсолютний шлях до команди, якщо вона знайдена в змінних середовища PATH.
+- Якщо команда не знайдена в PATH, функція повертає `null`.
+- Функція не викидає винятки у разі невдачі.
+- Функція не використовує жодного кешу.
+- Функція не гарантує, що команда доступна.
+- Функція не гарантує, що команда працює.
+- Функція не гарантує, що команда безпечна для використання.

package/scripts/utils/docs/resolve-js-root.md

@@ -0,0 +1,26 @@
+---
+type: JS Module
+title: resolve-js-root.mjs
+resource: npm/scripts/utils/resolve-js-root.mjs
+docgen:
+  crc: 5202013e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Визначає корінь JS-коду в проєкті, відповідно до логіки для workspace-projects (перший workspace з підтримкою glob-патернів `cf/*`) або single-package (корінь cwd). Ця утиліта є спільною для coverage-провайдера JS та test-концерну `stryker_config` (DRY). Публічні функції дозволяють отримати один або повний список шляхів до всіх JS-коренів, при цьому свідомо виключаються каталоги `.git` та `node_modules`. Код спирається на конфігураційні файли `package.json` та `.n-rules.json`.
+
+## Поведінка
+
+resolveJsRoot повертає абсолютний шлях до першого JS-кореня проєкту. Якщо кореневий `package.json` відсутній, повертає null.
+resolveAllJsRoots повертає масив абсолютних шляхів до всіх JS-коренів проєкту. Ігнорує каталоги `.git` та `node_modules`.
+
+## Публічний API
+
+resolveJsRoot — знаходить кореневий каталог JavaScript-проєкту.
+resolveAllJsRoots — повертає всі каталоги JavaScript-проєктів у робочому просторі.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/scripts/utils/docs/test-helpers.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: test-helpers.mjs
+resource: npm/scripts/utils/test-helpers.mjs
+docgen:
+  crc: 9af8ee18
+---
+
+## Огляд
+
+Допоміжні функції для тестів скриптів пакета `@7n/rules`: ізольовані тимчасові каталоги, запис JSON за абсолютним шляхом і керування видимістю зовнішніх бінарників через `PATH`. Жодна з функцій не мутує `process.cwd()` — тест явно будує шляхи через `join(dir, …)` і передає `cwd` дочірнім процесам (контракт перевіряється правилом `no-process-chdir`).
+
+## Публічний API
+
+- `withTmpDir(fn)` — створює тимчасовий каталог, передає його абсолютний шлях у `fn`, після завершення видаляє каталог (з повторами на випадок гонки з паралельними git-hook-записами всередині каталогу).
+- `writeJson(path, data)` — записує JSON з відступами й завершальним переносом рядка; шлях має бути абсолютним, інакше кидає помилку.
+- `ensureDir(path)` — створює вкладені каталоги за абсолютним шляхом; відносний шлях — помилка.
+- `withBinStubInPath(bin, fn)` — створює тимчасовий каталог зі стабом `<bin>` (`<bin>.exe` на Windows), що завершується з кодом 0, додає каталог на початок `PATH` на час `fn`, потім відновлює `PATH` і прибирає стаб. Реальний бінарник не запускається: і машини без інструмента, і повільні мережево-залежні інструменти (наприклад, `kubescape`, який на старті тягне артефакти з хмарних API десятки секунд) отримують детермінований швидкий прогін.
+- `withShellcheckStubInPath(fn)` — спеціалізація `withBinStubInPath` для `shellcheck` (перевірки `check ga` на машинах без реального shellcheck).
+- `withBinRemovedFromPath(bin, fn)` — виконує `fn` із `PATH`, з якого прибрані всі каталоги з виконуваним `<bin>`; решта `PATH` (git, bun) лишається. На час `fn` виставляє `N_CURSOR_NO_AUTO_INSTALL=1`, щоб `ensureTool` не запускав реальний brew/scoop/curl-install. Для негативних тестів «fail, коли інструмента нема».
+
+## Гарантії поведінки
+
+- `PATH` і `N_CURSOR_NO_AUTO_INSTALL` завжди відновлюються до початкових значень навіть при винятку в `fn` (`finally`).
+- Тимчасові каталоги (`withTmpDir`, стаби) прибираються після завершення `fn`.
+- Функції запису (`writeJson`, `ensureDir`) відхиляють відносні шляхи — захист від залежності тестів від `process.cwd()`.
+
+## Де використовується
+
+Інтеграційні тести `npm/tests/*` та тести правил (`rules/ga/workflows`, `rules/k8s` тощо), що спавнять зовнішні інструменти або працюють із тимчасовими деревами.