@7n/rules 1.0.0

package/scripts/utils/docs/walk-cache.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: walk-cache.mjs
+resource: npm/scripts/utils/walk-cache.mjs
+docgen:
+  crc: 82798fa2
+---
+
+Файл забезпечує спільний кеш результатів обходу файлової системи для всіх операцій перевірки. Він зберігає список файлів, що відповідають заданим шаблонам, щоб уникнути повторних обходів. Це підвищує ефективність процесу перевірки, особливо при великій кількості файлів та шаблонів.
+
+## Поведінка
+
+getOrCreateWalkCache: Створює або повертає кеш.
+resetWalkCache: Скидає кеш.
+
+## Публічний API
+
+- getOrCreateWalkCache — Створює або повертає cache, ініціалізує його при першому використанні.
+- resetWalkCache — Очищає cache.
+
+## Гарантії поведінки
+
+- Кеш існує лише в межах одного процесу.
+- Кеш скидається при виклику `resetWalkCache`.
+- Кеш зберігає список файлів, отриманий в результаті прогону.
+- Значення кешу – `Promise<string[]>`.
+- Кеш використовується для обробки glob/regex дескрипторів.
+- Кеш не використовується для взаємодії з мережею.
+- Кеш зберігає дані лише протягом одного прогону.
+- Кеш не гарантує наявності файлів, що відповідають дескрипторам.
+- Кеш не гарантує порядку файлів у списку.

package/scripts/utils/docs/walkDir.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: walkDir.mjs
+resource: npm/scripts/utils/walkDir.mjs
+docgen:
+  crc: f205f003
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Публічна функція `walkDir` здійснює рекурсивний пошук файлів у вказаному каталозі. Вона обходить файлову систему, ігноруючи каталоги `.git` та `node_modules`. Знаходячи кожен файл, вона передає його повний шлях у колбек для подальшої обробки. Компонент є read-only, тобто не виконує записів у файлову систему чи бази даних. При роботі з файловою системою він перехоплює помилки, забезпечуючи безпечну роботу без викидання винятків.
+
+## Поведінка
+
+1. Викликається функція walkDir для початку рекурсивного обходу каталогу.
+2. Система розшифровує вхідний шлях до кореня обходу.
+3. Система формує додаткові правила ігнорування на основі наданих шляхів.
+4. Система завжди ігнорує каталоги .git та node_modules.
+5. Система виконує пошук усіх файлів у каталозі, застосовуючи правила ігнорування, включаючи ті, що визначені в .gitignore.
+6. У разі виникнення помилки під час пошуку, процес обходу припиняється без генерації винятку.
+7. Для кожного знайденого файлу система викликає наданий колбек, передаючи йому повний абсолютний шлях до цього файлу.
+
+## Публічний API
+
+walkDir — рекурсивно переглядає файли та папки, ігноруючи ті, що вказані у файлі `.gitignore`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/scripts/utils/docs/with-lock.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: with-lock.mjs
+resource: npm/scripts/utils/with-lock.mjs
+docgen:
+  crc: 45df57fc
+  score: 95
+---
+
+Файл реалізує механізм захисту важких команд через атомарне блокування та унікалізацію результатів. Функції дозволяють перевіряти можливість повторного використання результату з кешу та виконувати команду через серіалізований механізм. Механізм використовує `mkdirSync-based lock` та `sha256-dedup` з TTL.
+
+## Поведінка
+
+shouldDedup
+Перевіряє можливість повторного використання результату з кешу.
+
+withLock
+Серіалізує важку команду через атомарний lock та dedup.
+
+## Публічний API
+
+shouldDedup — Чи можна пропустити повторний прогін за кешованим result.json.
+withLock — Серіалізує важку команду через атомарний lock і dedup за fingerprint.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/utils/docs/worktree-fingerprint.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: worktree-fingerprint.mjs
+resource: npm/scripts/utils/worktree-fingerprint.mjs
+docgen:
+  crc: df297382
+---
+
+Файл надає унікальний відбиток робочої директорії. Цей відбиток використовується для ідентифікації та порівняння робочих директорій, забезпечуючи їх унікальність у системі. Він слугує базовим інструментом для відстеження та управління версіями.
+
+## Поведінка
+
+1.  Отримує поточний SHA256 хеш коміту, який знаходиться в гілці HEAD.
+2.  Отримує текст зміни між комітом HEAD та робочим каталогом.
+3.  Отримує список не відстежених файлів у робочому каталозі, не включаючи стандартні файли, що ігноруються.
+4.  Для кожного не відстеженого файлу отримує його SHA256 хеш.
+5.  Об'єднує SHA256 хеш коміту, текст зміни та пари "файл:хеш" не відстежених файлів, розділяючи їх новими рядками.
+6.  Обчислює SHA256 хеш отриманого текстового рядка.
+7.  Повертає отриманий SHA256 хеш у форматі 64-значної шестнадцяткової строки.
+8.  Якщо виникає помилка під час виконання будь-якої з операцій, повертає `null`.
+
+## Публічний API
+
+worktreeFingerprint — генерує унікальний відбиток поточного стану репозиторію Git.
+
+## Гарантії поведінки
+
+- Функція повертає `true`, якщо відбиток дерева робіт успішно обчислено.
+- Функція повертає `null`, якщо обчислення відбитка дерева робіт не вдалося.
+- Функція не викликає винятків.
+- Функція не використовує кеш.

package/scripts/utils/ensure-gitignore-entries.mjs

@@ -0,0 +1,30 @@
+/**
+ * Idempotent append-only модуль оновлення `.gitignore` у корені проєкту. Перевіряє,
+ * чи задані entries уже присутні (точне співпадіння рядка після `trim`); відсутні
+ * дописує під header-коментар, не порушуючи решту файлу. Якщо `.gitignore` немає —
+ * створюється з заданими entries + header.
+ *
+ * Викликається з test-концерну `stryker_config` (gitignore Stryker temp dirs).
+ */
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * @param {string} cwd корінь репо (де знаходиться `.gitignore`)
+ * @param {string[]} entries патерни для .gitignore (порядок збережено)
+ * @param {string} sectionLabel header-коментар над секцією (без `#`-префікса)
+ * @returns {Promise<{added: string[]}>} перелік патернів, що були дописані
+ */
+export async function ensureGitignoreEntries(cwd, entries, sectionLabel) {
+  const gitignorePath = join(cwd, '.gitignore')
+  const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, 'utf8') : ''
+  const existingLines = new Set(existing.split('\n').map(line => line.trim()))
+  const missing = entries.filter(entry => !existingLines.has(entry))
+  if (missing.length === 0) return { added: [] }
+
+  const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n'
+  const block = `${prefix}\n# ${sectionLabel}\n${missing.join('\n')}\n`
+  await writeFile(gitignorePath, existing + block)
+  return { added: missing }
+}

package/scripts/utils/find-package-json-paths.mjs

@@ -0,0 +1,30 @@
+/**
+ * Спільна утиліта для check-скриптів: збирає всі `package.json` у дереві (крім пропущених
+ * каталогів у `walkDir`), сортує за відносним шляхом. Винесена з check-js-bun-db / check-js-mssql,
+ * щоб уникнути дублювання (jscpd).
+ */
+import { relative, sep } from 'node:path'
+
+import { walkDir } from './walkDir.mjs'
+
+/**
+ * Знаходить всі `package.json` у репозиторії (крім пропущених директорій у walkDir).
+ * @param {string} repoRoot абсолютний шлях до кореня репозиторію
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<string[]>} абсолютні шляхи, відсортовані за відносним шляхом
+ */
+export async function findAllPackageJsonPaths(repoRoot, ignorePaths) {
+  /** @type {string[]} */
+  const paths = []
+  await walkDir(
+    repoRoot,
+    absPath => {
+      if (absPath.endsWith(`${sep}package.json`)) {
+        paths.push(absPath)
+      }
+    },
+    ignorePaths
+  )
+  paths.sort((a, b) => relative(repoRoot, a).localeCompare(relative(repoRoot, b)))
+  return paths
+}

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-rules/<key>`
+ * (всередині `.git` — спільне, ніколи не трекається, переживає `bun i`).
+ * Поза git-репо (git недоступний / каталог не репо) — fallback на per-checkout
+ * `node_modules/.cache/n-rules/<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-rules', key)
+  }
+  // commonDir буває відносним (`.git` з кореня) або абсолютним (linked-worktree):
+  // resolve проти cwd дає однаковий абсолютний `<main>/.git` в обох випадках.
+  return join(resolve(cwd, commonDir), 'n-rules', key)
+}

package/scripts/utils/pass.mjs

@@ -0,0 +1,9 @@
+/**
+ * Допоміжна функція для скриптів перевірки.
+ *
+ * Друкує в консоль рядок успіху з галочкою (✅).
+ * @param {string} msg текст повідомлення
+ */
+export function pass(msg) {
+  console.log(`  ✅ ${msg}`)
+}

package/scripts/utils/resolve-cargo-manifest.mjs

@@ -0,0 +1,62 @@
+/**
+ * Резолвить шлях до Cargo.toml у проєкті: cwd/Cargo.toml або в одному з
+ * workspace-підкаталогів (з підтримкою Tauri-патерну `<workspace>/src-tauri/`).
+ * Спільна утиліта для coverage-провайдера rust і test-концерну cargo_mutants_config.
+ * Повертає null (а не throw) щоб callsite-и могли gracefully skip-пропустити.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<string|null>} абсолютний шлях до Cargo.toml або null
+ */
+export async function resolveCargoManifest(cwd) {
+  const rootManifest = join(cwd, 'Cargo.toml')
+  if (existsSync(rootManifest)) return rootManifest
+
+  const rootPkgPath = join(cwd, 'package.json')
+  if (existsSync(rootPkgPath)) {
+    const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
+    const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
+    for (const ws of workspaces) {
+      const tauri = join(cwd, ws, 'src-tauri', 'Cargo.toml')
+      if (existsSync(tauri)) return tauri
+      const flat = join(cwd, ws, 'Cargo.toml')
+      if (existsSync(flat)) return flat
+    }
+  }
+  return null
+}
+
+/**
+ * Plural-варіант: повертає всі Cargo.toml-маніфести в проєкті — корінь
+ * (`cwd/Cargo.toml`) і у workspace-підкаталогах (`<ws>/src-tauri/Cargo.toml`
+ * пріоритетніше за `<ws>/Cargo.toml`). Порожній масив якщо нічого не знайдено.
+ * Використовується test-концерном `cargo_mutants_config` для per-manifest
+ * baseline-копіювання.
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<string[]>} абсолютні шляхи до знайдених Cargo.toml
+ */
+export async function resolveAllCargoManifests(cwd) {
+  const manifests = []
+  const rootManifest = join(cwd, 'Cargo.toml')
+  if (existsSync(rootManifest)) manifests.push(rootManifest)
+
+  const rootPkgPath = join(cwd, 'package.json')
+  if (existsSync(rootPkgPath)) {
+    const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
+    const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
+    for (const ws of workspaces) {
+      const tauri = join(cwd, ws, 'src-tauri', 'Cargo.toml')
+      if (existsSync(tauri)) {
+        manifests.push(tauri)
+        continue
+      }
+      const flat = join(cwd, ws, 'Cargo.toml')
+      if (existsSync(flat)) manifests.push(flat)
+    }
+  }
+  return manifests
+}

package/scripts/utils/resolve-cmd.mjs

@@ -0,0 +1,25 @@
+/**
+ * Утиліта для розв'язання абсолютного шляху до команди в PATH.
+ *
+ * Використовується для виклику зовнішніх інструментів через абсолютний шлях
+ * замість команди з PATH (sonarjs/no-os-command-from-path).
+ */
+import { spawnSync } from 'node:child_process'
+import { platform } from 'node:process'
+
+/**
+ * Повертає абсолютний шлях до команди в PATH або null, якщо команда не знайдена.
+ * @param {string} cmd ім'я команди без шляху
+ * @returns {string | null} абсолютний шлях або null
+ */
+export function resolveCmd(cmd) {
+  const whichCmd = platform === 'win32' ? 'where' : 'which'
+  // Явно передаємо `process.env`, інакше Bun вмикає snapshot оточення на старті процесу
+  // і не бачить змін `process.env.PATH` у runtime (типова ситуація — підстановка стабів у тестах).
+  const result = spawnSync(whichCmd, [cmd], { encoding: 'utf8', env: process.env })
+  if (result.status !== 0 || result.error) {
+    return null
+  }
+  const line = result.stdout.trim().split('\n', 1)[0].trim()
+  return line || null
+}

package/scripts/utils/resolve-js-root.mjs

@@ -0,0 +1,61 @@
+/**
+ * Резолвить корінь JS-коду в проєкті: для workspace-projects — перший workspace
+ * (з підтримкою glob-патернів типу `cf/*`), для single-package — корінь cwd.
+ * Спільна утиліта для coverage-провайдера js і test-концерну stryker_config (DRY).
+ */
+import { existsSync } from 'node:fs'
+import { glob, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const WORKSPACE_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**']
+const PACKAGE_JSON_SUFFIX_RE = /[/\\]package\.json$/
+
+/**
+ * Розгортає один workspace-патерн у список абсолютних шляхів каталогів з package.json.
+ * Літеральні патерни перевіряються через existsSync; glob-патерни — через node:fs/promises#glob.
+ * @param {string} cwd корінь проєкту
+ * @param {string} pattern workspace-патерн з package.json (наприклад, `app` або `cf/*`)
+ * @returns {Promise<string[]>} абсолютні шляхи до workspace-каталогів
+ */
+async function expandWorkspacePattern(cwd, pattern) {
+  if (!pattern.includes('*')) {
+    const wsPath = join(cwd, pattern)
+    return existsSync(join(wsPath, 'package.json')) ? [wsPath] : []
+  }
+  const results = []
+  for await (const rel of glob(`${pattern}/package.json`, { cwd, exclude: WORKSPACE_GLOB_IGNORE })) {
+    const wsRel = rel.replace(PACKAGE_JSON_SUFFIX_RE, '')
+    results.push(join(cwd, wsRel))
+  }
+  return results.toSorted()
+}
+
+/**
+ * @param {string} cwd корінь проєкту (де `.n-rules.json` і кореневий package.json)
+ * @returns {Promise<string|null>} абсолютний шлях до JS-root або null без кореневого package.json
+ */
+export async function resolveJsRoot(cwd) {
+  const roots = await resolveAllJsRoots(cwd)
+  if (roots.length === 0) return null
+  return roots[0]
+}
+
+/**
+ * Plural-варіант: повертає всі JS-roots проєкту. Для workspace-projects — кожен
+ * workspace з власним `package.json` (з розгортанням glob-патернів); для
+ * single-package — `[cwd]`. Порожній масив без кореневого package.json.
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<string[]>} абсолютні шляхи до всіх JS-roots
+ */
+export async function resolveAllJsRoots(cwd) {
+  const rootPkgPath = join(cwd, 'package.json')
+  if (!existsSync(rootPkgPath)) return []
+  const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
+  const patterns = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
+  if (patterns.length === 0) return [cwd]
+  const roots = []
+  for (const pattern of patterns) {
+    roots.push(...(await expandWorkspacePattern(cwd, pattern)))
+  }
+  return roots.length > 0 ? roots : [cwd]
+}

package/scripts/utils/walk-cache.mjs

@@ -0,0 +1,24 @@
+/**
+ * Module-singleton FS-walk cache, спільний для всіх concerns одного `check`-прогону.
+ * Ключі — рядкові glob/regex дескриптори; значення — `Promise<string[]>` зі списком файлів.
+ * Кеш живий у межах одного процесу (Node/Bun module-instance). Тести скидають через `resetWalkCache()`.
+ */
+
+/** @type {Map<string, Promise<string[]>> | null} */
+let cache = null
+
+/**
+ * Повертає поточний cache; lazy-ініціалізує при першому виклику.
+ * @returns {Map<string, Promise<string[]>>} module-singleton walk cache
+ */
+export function getOrCreateWalkCache() {
+  if (cache === null) cache = new Map()
+  return cache
+}
+
+/**
+ * Скидає cache (для тестів між кейсами).
+ */
+export function resetWalkCache() {
+  cache = new Map()
+}

package/scripts/utils/walkDir.mjs

@@ -0,0 +1,55 @@
+/** @see ./docs/walkDir.md */
+import { join, relative, resolve, sep } from 'node:path'
+import { globby } from 'globby'
+
+// .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
+// node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+export const ALWAYS_IGNORE = ['.git/**', 'node_modules/**']
+
+/**
+ * Прибирає всі кінцеві `/` без regex-бектрекінгу.
+ * @param {string} p вхідний шлях.
+ * @returns {string} шлях без кінцевих слешів.
+ */
+function stripTrailingSlashes(p) {
+  let end = p.length
+  while (end > 0 && p[end - 1] === '/') end -= 1
+  return p.slice(0, end)
+}
+
+/**
+ * Рекурсивно обходить каталог, поважаючи .gitignore (включно з вкладеними).
+ * @param {string} dir абсолютний або відносний шлях до кореня обходу
+ * @param {(filePath: string) => void} onFile колбек для кожного файлу (абсолютний шлях)
+ * @param {string[]} [ignorePaths] додаткові шляхи для пропуску (абсолютні або відносні від cwd)
+ * @returns {Promise<void>}
+ */
+export async function walkDir(dir, onFile, ignorePaths = []) {
+  const absDir = resolve(dir)
+
+  const extraIgnore = ignorePaths
+    .map(p => {
+      const abs = resolve(stripTrailingSlashes(p))
+      const rel = relative(absDir, abs).split(sep).join('/')
+      if (rel.startsWith('..') || rel === '') return null
+      return `${rel}/**`
+    })
+    .filter(Boolean)
+
+  let files
+  try {
+    files = await globby('**/*', {
+      cwd: absDir,
+      gitignore: true,
+      dot: true,
+      onlyFiles: true,
+      ignore: [...ALWAYS_IGNORE, ...extraIgnore]
+    })
+  } catch {
+    return
+  }
+
+  for (const rel of files) {
+    onFile(join(absDir, rel))
+  }
+}

package/scripts/utils/with-lock.mjs

@@ -0,0 +1,190 @@
+/**
+ * Guard-механізм: атомарний lock + dedup для важких команд.
+ * Алгоритм: mkdirSync-based lock, перевірка живості PID, sha256-dedup з TTL.
+ */
+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 = {
+  ttl: 600_000,
+  staleThreshold: 1_800_000,
+  waitTimeout: 1_200_000,
+  pollInterval: 1500,
+  onWaitTimeout: 'run-unlocked'
+}
+
+/**
+ * Чи процес із заданим PID ще живий на поточному host.
+ * @param {number} pid ідентифікатор процесу з owner.json
+ * @returns {boolean} true, якщо process.kill(pid, 0) не кинув помилку
+ */
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Повертає функцію, що знімає lock-директорію.
+ * @param {string} lockDir абсолютний шлях до lock-директорії
+ * @returns {() => void} release-колбек для finally/signal handler
+ */
+function makeRelease(lockDir) {
+  return () => fs.rmSync(lockDir, { recursive: true, force: true })
+}
+
+/**
+ * Чи можна пропустити повторний прогін за кешованим result.json.
+ * @param {{exitCode:number, fingerprint:string|null, finishedAt:number}} result попередній результат з result.json
+ * @param {string|null} fingerprint поточний fingerprint робочого дерева
+ * @param {number} ttl TTL дедуплікації в мілісекундах
+ * @returns {boolean} true, якщо попередній успішний прогін можна повторно використати
+ */
+export function shouldDedup(result, fingerprint, ttl) {
+  if (result.exitCode !== 0) return false
+  if (fingerprint === null || result.fingerprint !== fingerprint) return false
+  return Date.now() - result.finishedAt < ttl
+}
+
+/**
+ * Один крок узяття лока: пробує `mkdirSync`. При `EEXIST` перевіряє, чи власник
+ * ще живий і чи не протермінований TTL (stale) — якщо так, очищає лок і просить
+ * повторити спробу негайно; інакше повертає owner для wait-хуків виклику.
+ * @param {string} key ключ локу (для console.error-повідомлень).
+ * @param {string} lockDir абсолютний шлях до lock-директорії.
+ * @param {string} ownerFile шлях до owner.json усередині lockDir.
+ * @param {string|null} fingerprint поточний fingerprint робочого дерева (пишеться в owner.json).
+ * @param {number} staleThreshold поріг (мс), понад який лок вважається застарілим незалежно від PID.
+ * @returns {{status:'acquired'}|{status:'retry'}|{status:'busy', owner:object}} результат однієї спроби
+ */
+function tryAcquireOnce(key, lockDir, ownerFile, fingerprint, staleThreshold) {
+  try {
+    fs.mkdirSync(lockDir)
+    fs.writeFileSync(
+      ownerFile,
+      // cwd — для UI черги (lint-lock.mjs показує, звідки запущений власник лока)
+      JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now(), fingerprint, cwd: process.cwd() })
+    )
+    return { status: 'acquired' }
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+  }
+  let owner
+  try {
+    owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'))
+  } catch {
+    fs.rmSync(lockDir, { recursive: true, force: true })
+    return { status: 'retry' }
+  }
+  const stale =
+    Date.now() - owner.startedAt > staleThreshold || (os.hostname() === owner.host && !isPidAlive(owner.pid))
+  if (!stale) return { status: 'busy', owner }
+  console.error(`🧹 ${key}: знайдено застарілий лок — очищаю`)
+  fs.rmSync(lockDir, { recursive: true, force: true })
+  return { status: 'retry' }
+}
+
+/**
+ * Серіалізує важку команду через атомарний lock і dedup за fingerprint.
+ *
+ * Хуки очікування (усі опційні; кастомний UI черги — див. `lint-lock.mjs`):
+ * `onWaitStart(owner)` — один раз, коли лок виявився зайнятим живим власником;
+ * `onWaitTick(owner)` — кожен poll-цикл очікування (заміняє дефолтний
+ * `⏳ …: чекаю` console.error-рядок); `onWaitEnd()` — по виходу з очікування
+ * (лок взято, таймаут або stale-очистка) — викликається лише якщо був `onWaitStart`.
+ * @param {string} key ключ локу (наприклад `lint-ga`, `fix-bun`)
+ * @param {() => number | Promise<number>} runFn основна робота; повертає exit code
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, onWaitTimeout?:'run-unlocked'|'fail', cacheDir?:string, getFingerprint?:() => string | null, onWaitStart?:(owner:object)=>void, onWaitTick?:(owner:object)=>void, onWaitEnd?:()=>void}} [opts] TTL, шлях кешу, поведінка на таймаут (default `run-unlocked`; `fail` = fail-closed), override fingerprint та хуки очікування
+ * @returns {Promise<number>} exit code виконаної або дедуплікованої команди
+ */
+export async function withLock(key, runFn, opts = {}) {
+  const { ttl, staleThreshold, waitTimeout, pollInterval, onWaitTimeout } = { ...DEFAULTS, ...opts }
+  const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
+  const cacheDir = opts.cacheDir ?? resolveLockCacheDir(key)
+  const lockDir = join(cacheDir, 'lock')
+  const ownerFile = join(lockDir, 'owner.json')
+  const resultFile = join(cacheDir, 'result.json')
+  const release = makeRelease(lockDir)
+
+  const fingerprint = getFingerprint()
+  fs.mkdirSync(cacheDir, { recursive: true })
+
+  const loopStart = Date.now()
+  let waiting = false
+  /** Викликає `onWaitEnd` один раз, якщо очікування взагалі починалось. */
+  const endWait = () => {
+    if (!waiting) return
+    waiting = false
+    opts.onWaitEnd?.()
+  }
+
+  while (true) {
+    if (Date.now() - loopStart >= waitTimeout) {
+      endWait()
+      if (onWaitTimeout === 'fail') {
+        throw new Error(`${key}: не вдалося взяти лок за ${waitTimeout / 60_000} хв — fail-closed`)
+      }
+      console.error(`⚠️ ${key}: чекав ${waitTimeout / 60_000} хв — запускаю без локу`)
+      return await runFn()
+    }
+    const attempt = tryAcquireOnce(key, lockDir, ownerFile, fingerprint, staleThreshold)
+    if (attempt.status === 'acquired') {
+      endWait()
+      break
+    }
+    if (attempt.status === 'retry') continue
+    if (!waiting) {
+      waiting = true
+      opts.onWaitStart?.(attempt.owner)
+    }
+    if (opts.onWaitTick) {
+      opts.onWaitTick(attempt.owner)
+    } else {
+      console.error(`⏳ ${key}: чекаю, лок тримає pid ${attempt.owner.pid}…`)
+    }
+    await sleep(pollInterval)
+  }
+
+  console.error(`🔒 ${key}: лок взято`)
+
+  try {
+    const raw = fs.readFileSync(resultFile, 'utf8')
+    const result = JSON.parse(raw)
+    if (shouldDedup(result, fingerprint, ttl)) {
+      const elapsed = Math.round((Date.now() - result.finishedAt) / 1000)
+      console.error(`♻️ ${key}: те саме дерево, ${elapsed}с тому — пропускаю`)
+      release()
+      return 0
+    }
+  } catch {
+    /* result.json не існує або пошкоджений */
+  }
+
+  // Після release лок ре-рейзиться той самий сигнал: `once` вже зняв обробник,
+  // тож процес завершується дефолтною дією з коректним кодом (130/143)
+  const onSignal = signal => {
+    release()
+    process.kill(process.pid, signal)
+  }
+  process.once('SIGINT', onSignal)
+  process.once('SIGTERM', onSignal)
+
+  let code
+  try {
+    code = await runFn()
+    fs.writeFileSync(resultFile, JSON.stringify({ finishedAt: Date.now(), exitCode: code, fingerprint }))
+  } finally {
+    process.off('SIGINT', onSignal)
+    process.off('SIGTERM', onSignal)
+    release()
+  }
+
+  return code
+}