@7n/rules 1.45.0 → 1.46.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.46.0] - 2026-07-23
+
+### Added
+
+- концерн coverage правила test: гейт покриття/мутаційки як lint-детектор (--no-fix = CI-гейт), CoverageProvider порт у plugin-api (spec 2026-07-22 absorb-7n-test)
+- coverage: спільні lib manifest-roots/lcov, подовжений full-таймаут для мутаційного тестування (×4), пілот classify (0.7) у цьому репо
+
+### Changed
+
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header/export JSDoc у конфігах demo
+- doc_comments rollout: header-JSDoc у vitest.config
+
 ## [1.45.0] - 2026-07-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/test/coverage/lib/manifest-roots.mjs

@@ -0,0 +1,49 @@
+/**
+ * Мовно-агностичний пошук коренів екосистеми за маніфестом (спільна lib
+ * концерну coverage): каталоги з одним із маніфест-файлів у корені проєкту та
+ * на першому рівні вкладеності (типові розкладки: крейт/пакет у корені,
+ * `src-tauri/`, side-пакет у монорепо). Глибші члени workspace не повертаються
+ * — тулзи (`cargo llvm-cov`, `pytest`) покривають їх із кореня самі.
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Службові теки, де маніфести першого рівня не шукаються. */
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'target',
+  'coverage',
+  'docs',
+  '.git',
+  '.claude',
+  '.worktrees',
+  '.cursor',
+  '.github'
+])
+
+/**
+ * Корені під `cwd`, що мають хоча б один із `manifestNames`.
+ * @param {string} cwd корінь проєкту
+ * @param {string[]} manifestNames імена маніфестів (напр. `['Cargo.toml']`, `['pyproject.toml', 'setup.py']`)
+ * @returns {Promise<string[]>} абсолютні шляхи каталогів-коренів
+ */
+export async function findManifestRoots(cwd, manifestNames) {
+  const hasManifest = dir => manifestNames.some(name => existsSync(join(dir, name)))
+  const roots = []
+  if (hasManifest(cwd)) roots.push(cwd)
+  let entries
+  try {
+    entries = await readdir(cwd, { withFileTypes: true })
+  } catch {
+    return roots
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || IGNORE_DIRS.has(entry.name)) continue
+    const dir = join(cwd, entry.name)
+    if (hasManifest(dir)) roots.push(dir)
+  }
+  return roots
+}

package/schemas/n-rules.json

@@ -82,6 +82,11 @@
           "type": "number",
           "description": "Мінімальний mutation score у відсотках (лише повний вимір: lint --full / lint test).",
           "default": 80
+        },
+        "classifyConfidenceThreshold": {
+          "type": "number",
+          "description": "Confidence-поріг LLM-класифікації survived-мутантів (allowed gaps). ≤1 — увімкнено; дефолт 1.1 = вимкнено (rollout-mode).",
+          "default": 1.1
         }
       }
     },

package/scripts/lib/lint-surface/docs/lint-lock.md

@@ -3,45 +3,54 @@ type: JS Module
 title: lint-lock.mjs
 resource: npm/scripts/lib/lint-surface/lint-lock.mjs
 docgen:
-  crc: 23bf1b2c
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
-  score: 100
-  issues: judge:inaccurate:0.98
+  crc: c1100ba8
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 90
+  issues: internal-name:withLock,judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл серіалізує лише довгі machine-wide запуски `n-rules lint --full`, щоб на машині одночасно виконувався щонайбільше один full-прогін. Delta, scoped і `--no-fix` запуски не беруть глобальний лок і не стають у цю чергу.
+Спільний машинний стан для `n-rules lint --full`: через `withLock` блокується лише `--full`, а scoped, delta та `--no-fix` запуски йдуть без черги. Це серіалізує довгі whole-tree прогони на одній машині, дає видимість позиції в черзі й показує живий прогрес активного запуску.
 
-Активний full-прогін записує власника лока в `owner.json` і публікує живий стан у `progress.json`, щоб процеси в очікуванні бачили поточного виконавця та прогрес. Процеси в черзі реєструються у `queue/<enqueuedAt>-<pid>.json`, що дає видимий список очікування й позицію кожного запуску.
+`GLOBAL_CACHE_DIR` лежить в `os.tmpdir` і працює machine-wide. У ньому зберігаються `lock/owner.json` для власника лока, `queue/<enqueuedAt>-<pid>.json` для черги процесів і `progress.json` для знімка активного прогресу.
 
-Дедуплікація спирається на fingerprint і TTL у механіці лока, а не на файли стану. За неможливості безпечно дочекатися черги запуск завершується fail-closed, щоб не допустити мовчазного паралельного full-прогону.
+`lintLockFingerprint` домішує варіант виклику до знімка дерева, щоб scoped-успіх не хибно перекривав ширший прогін. `staleThreshold` піднято до 6 год, `waitTimeout` — 45 хв; після цього очікування завершується fail-closed, а не мовчазним паралельним запуском.
+
+`createProgressPublisher` оновлює `progress.json`, `renderWaitLine` відображає чергу й прогрес, а `withGlobalLintLock` є спільною точкою доступу до цього режиму.
 
 ## Поведінка
 
-- `GLOBAL_CACHE_DIR` задає спільне machine-wide місце стану для черги full-лінту, включно з `owner.json` і `progress.json`.
+`GLOBAL_CACHE_DIR` — спільний машинний кеш для всіх full-запусків lint: тут зберігаються власник лока, черга очікування і живий прогрес активного прогону. Саме цей стан робить чергу видимою між процесами та дозволяє не запускати кілька повних прогонів паралельно.
 
-- `lintLockFingerprint` формує ключ дедуплікації для full-лінту з урахуванням стану дерева й варіанта запуску; повертає порожнє значення, коли безпечно дедуплікувати неможливо.
+`lintLockFingerprint` визначає, чи можна безпечно застосувати TTL-дедуплікацію для конкретного варіанта lint. Якщо знімок дерева недоступний або виклик не відповідає поточному робочому дереву, дедуплікація вимикається і запуск іде далі по черзі. Інакше fingerprint враховує і стан дерева, і варіант виклику, щоб короткий scoped-успіх не підміняв ширший full-прогін.
 
-- `createProgressPublisher` публікує throttled-знімки прогресу активного full-прогону в `progress.json`, щоб процеси в черзі бачили живий стан без зайвого навантаження на диск.
+`withGlobalLintLock` — точка входу для повного запуску: non-full варіанти проходять одразу, а full-прогони стають у глобальну чергу, чекають звільнення лока й виконуються по одному. Після входу в лок активний запуск публікує свій прогрес у `progress.json`, а процеси в черзі читають його та показують актуальний стан очікування. Якщо запуск уже був успішно дедуплікований, результат повертається без повторного виконання.
 
-- `renderWaitLine` створює однорядковий статус очікування з позицією в черзі, поточним власником лока з `owner.json`, прогресом із `progress.json` і рештою очікувачів.
+`createProgressPublisher` пов’язує репортер прогресу активного прогону зі спільним станом: нові знімки потрапляють у файл прогресу з обмеженням частоти оновлення, щоб черга бачила живий, але стабільний стан. Це джерело правди для всіх очікувальних процесів.
 
-- `withGlobalLintLock` серіалізує лише `--full` запуски лінту через глобальну чергу, а короткі дельта/scoped/`--no-fix` запуски пропускає одразу; при timeout завершується fail-closed, щоб не допустити паралельний full-прогін.
+`renderWaitLine` збирає однорядковий статус очікування з трьох джерел: поточного власника лока, живої черги і знімка прогресу активного прогону. У результаті процес у черзі бачить, хто зараз працює, яка в нього стадія, і яке місце займає сам у загальному порядку.
 
 ## Публічний API
 
-- GLOBAL_CACHE_DIR — зберігає спільний machine-wide стан лока й черги для всіх repo та worktree; спирається на owner.json і progress.json.
-- lintLockFingerprint — формує ключ для TTL-дедуплікації за станом робочого дерева та режимом запуску lint; повертає null поза git-repo або коли --cwd відрізняється від process cwd, щоб не прив’язати прогін до чужого дерева.
-- createProgressPublisher — публікує прогрес активного lint-прогону в progress.json, щоб процеси в черзі бачили актуальний progress bar власника лока.
-- renderWaitLine — показує стан очікування в черзі: позицію процесу, поточного власника з pid і текою, його прогрес та інші queued процеси.
-- withGlobalLintLock — запускає full lint під глобальним локом і чергою; delta, scoped та --no-fix прогони стартують одразу без очікування.
+- GLOBAL_CACHE_DIR — Machine-wide директорія стану лока/черги — спільна для всіх репо й worktree.
+- lintLockFingerprint — Fingerprint для TTL-дедуплікації: стан робочого дерева + варіант виклику lint.
+null (→ дедуплікація вимкнена, черга працює) коли:
+  - не в git-репо (worktreeFingerprint дасть null);
+  - `--cwd` вказує не на процесний cwd — git-команди fingerprint-а виконуються
+    у `process.cwd()`, тож знімок відповідав би не тому дереву, що лінтиться.
+- createProgressPublisher — Publisher прогресу активного прогону: приймає знімки від
+`createProgressReporter({ onUpdate })` і (throttled) пише їх у стан-файл,
+звідки процеси в черзі читають прогрес-бар активного прогону.
+- renderWaitLine — Рядок стану черги для процесу, що стоїть у черзі: позиція, хто працює (pid + тека),
+прогрес-бар власника і перелік решти черги.
+- withGlobalLintLock — Виконує `runFn` під глобальним локом full-прогонів. Не-full варіанти
+(дельта/scoped/`--no-fix`) виконуються одразу, без лока й черги.
 
 ## Гарантії поведінки
 
-- У кожен момент на машині виконується щонайбільше один `lint --full`; запуски в черзі стартують у порядку постановки.
-- Файлові операції стану (реєстрація в черзі, публікація прогресу, читання чужих записів) — best-effort: їх збій не валить прогін, лише зменшує видимість; записи мертвих PID прибираються при читанні списку.
-- Таймаут очікування черги — виняток (fail-closed), а не мовчазний паралельний запуск.
-- Ідентичний повторний `--full` на незміненому дереві дедуплікується за fingerprint у межах TTL (exit 0 без повторної роботи); поза git-репо чи при `--cwd` не на процесний cwd дедуплікація вимикається, черга лишається.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати в межах одного прогону.

package/scripts/lib/lint-surface/lint-lock.mjs

@@ -46,6 +46,14 @@ const PROGRESS_FILE = join(GLOBAL_CACHE_DIR, 'progress.json')
 /** Дедлайн очікування в черзі: full-прогони довгі, 20 хв дефолту withLock замало. */
 const WAIT_TIMEOUT_MS = 45 * 60_000
 
+/**
+ * Дедлайн, коли активний/очікуваний прогін включає концерн coverage правила
+ * `test` (spec absorb-7n-test, ризик 3.4): повне мутаційне тестування
+ * (Stryker/cargo-mutants) на великому проєкті не вкладається у 45 хв —
+ * інженерний запас ×4 замість вгадування точної тривалості.
+ */
+const WAIT_TIMEOUT_WITH_COVERAGE_MS = 4 * WAIT_TIMEOUT_MS
+
 /** Поріг time-based staleness (див. модульний коментар). */
 const STALE_THRESHOLD_MS = 6 * 3_600_000
 
@@ -235,10 +243,13 @@ export function withGlobalLintLock(variant, runFn, opts = {}) {
   if (!variant.full) return Promise.resolve(runFn())
   const { isTTY, log, queueDir, progressFile, ...lockOpts } = opts
   const ui = createWaitUi({ isTTY, log, queueDir, progressFile })
+  // Full-прогін завжди включає концерн coverage (мутаційне тестування) —
+  // черга чекає з покриттєвим запасом; scoped `lint test` під лок не йде
+  // (variant.full=false), тож окремої осі для нього не треба.
   return withLock('lint-full', runFn, {
     cacheDir: GLOBAL_CACHE_DIR,
     staleThreshold: STALE_THRESHOLD_MS,
-    waitTimeout: WAIT_TIMEOUT_MS,
+    waitTimeout: WAIT_TIMEOUT_WITH_COVERAGE_MS,
     onWaitTimeout: 'fail',
     getFingerprint: () => lintLockFingerprint(variant),
     ...ui,