@7n/rules 1.43.1 → 1.44.1

package/scripts/lib/plugin-api.mjs

@@ -78,6 +78,52 @@ export const PLUGIN_API_VERSION = 1
 const REQUIRED_PROVIDER_FUNCTIONS = ['detect', 'available', 'backup', 'bump', 'diff', 'promptFor', 'cleanup']
 const REQUIRED_PROVIDER_STRINGS = ['id', 'title', 'manifestNoun', 'skillSection']
 
+/**
+ * @typedef {object} CoverageRow
+ * Агрегований вимір однієї області (`JS`, `Vue (Storybook)`, `Rust`, …).
+ * @property {string} area назва рядка звіту
+ * @property {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} coverage line/function coverage
+ * @property {{caught:number, total:number}} mutation вбиті/всі мутанти (0/0 — мутаційне тестування не вимірювалось)
+ * @property {Array<{file:string, mutants:Array<object>, exampleTest?:object|null, recommendationText?:string|null}>} survived вцілілі мутанти по файлах (шляхи relative до cwd)
+ */
+
+/**
+ * @typedef {object} CoverageProvider
+ * Порт мовної екосистеми для концерну `coverage` правила `test` (spec
+ * 2026-07-22 absorb-7n-test). Ядро викликає: `detect` → повний вимір
+ * `collect` (full/`lint test`) АБО делта-вимір `collectPerFile` (делта-lint,
+ * без мутаційного тестування). Реєстрація — `contributes.handlers.coverage`
+ * у маніфесті плагіна, default-експорт handler-модуля.
+ * @property {string} id стабільний ідентифікатор екосистеми (напр. `js`)
+ * @property {string} title заголовок для звітів/повідомлень
+ * @property {(cwd: string) => Promise<boolean>} detect чи застосовний вимір у проєкті (false → тихий skip виміру)
+ * @property {(cwd: string, opts?: {changedFiles?: string[], base?: string|null, runner?: object}) => Promise<CoverageRow[]>} collect повний вимір: coverage + мутаційне тестування по всіх workspaces
+ * @property {(cwd: string, opts: {files: string[], runner?: object}) => Promise<Array<{file:string, pct:number, linesFound:number, linesCovered:number, reason?:string}>>} collectPerFile легкий делта-вимір per-file line coverage змінених файлів (без мутаційного тестування)
+ */
+
+const REQUIRED_COVERAGE_FUNCTIONS = ['detect', 'collect', 'collectPerFile']
+const REQUIRED_COVERAGE_STRINGS = ['id', 'title']
+
+/**
+ * Валідує форму coverage-провайдера з модуля плагіна.
+ * @param {unknown} candidate default-експорт handler-модуля плагіна
+ * @param {string} source ім'я плагіна/шлях модуля для повідомлення
+ * @returns {CoverageProvider} той самий обʼєкт, якщо валідний
+ */
+export function assertCoverageProvider(candidate, source) {
+  if (!candidate || typeof candidate !== 'object') {
+    throw new TypeError(`plugin-api: ${source} — default-експорт не є обʼєктом CoverageProvider`)
+  }
+  const missing = [
+    ...REQUIRED_COVERAGE_STRINGS.filter(k => typeof candidate[k] !== 'string' || candidate[k] === ''),
+    ...REQUIRED_COVERAGE_FUNCTIONS.filter(k => typeof candidate[k] !== 'function')
+  ]
+  if (missing.length > 0) {
+    throw new TypeError(`plugin-api: ${source} — CoverageProvider без обовʼязкових полів: ${missing.join(', ')}`)
+  }
+  return /** @type {CoverageProvider} */ (candidate)
+}
+
 /**
  * Валідує форму провайдера з модуля плагіна — зрозуміла помилка замість
  * «undefined is not a function» глибоко в оркестраторі.

package/scripts/lib/worktree-notice.mjs

@@ -133,7 +133,9 @@ git branch --show-current
 
 **Root-assert.** Якщо \`pwd\` **не** збігається з виводом \`git rev-parse --show-toplevel\` — ти в **піддиректорії** робочого дерева (worktree-шляхи нижче відносні до кореня репо). Спершу перейди в корінь: \`cd <toplevel>\` (literal-шлях із виводу), і лише тоді продовжуй preflight. Не створюй worktree з піддиректорії — \`cd .worktrees/<…>\` звідти впаде.
 
-Якщо \`git rev-parse --show-toplevel\` показав, що ти **не** в \`.worktrees/\`, візьми вивід \`git branch --show-current\` як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
+**Вже ізольований — нічого не створюй.** Якщо \`git rev-parse --show-toplevel\` містить сегмент \`.worktrees/<…>\` (репо-конвенція) **або** \`.claude/worktrees/<…>\` (worktree харнесу Claude Code — туди \`npx @7n/mt worktree create\` класти заборонено, \`n-worktree.mdc\`) — ти вже виконуєшся в окремому git-worktree. Preflight пройдено: нічого не створюй, нікого не питай про назву гілки — переходь одразу до Кроку 0.1.
+
+Інакше, якщо toplevel не містить жодного з цих сегментів, візьми вивід \`git branch --show-current\` як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
 
 \`\`\`bash
 npx @7n/mt worktree create "feature/x-${suffix}" "n-${suffix}: worktree-only skill"
@@ -142,10 +144,10 @@ cd ".worktrees/feature-x-${suffix}"
 
 Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.
 
-**Крок 0.1 — bootstrap у новому дереві (після \`cd\`).** Дерево щойно створене й **без** \`node_modules\`. Постав залежності локально — тоді \`npx @7n/rules <cmd>\` бере локальну копію без походу в реєстр:
+**Крок 0.1 — bootstrap (якщо в дереві ще нема \`node_modules\`).** Свіжостворений worktree (Крок 0) точно без \`node_modules\`; вже ізольований harness-worktree може мати їх або ні — постав локально, тоді \`npx @7n/rules <cmd>\` бере локальну копію без походу в реєстр:
 
 \`\`\`bash
-bun install
+test -d node_modules || bun install
 \`\`\``
 }
 

package/scripts/utils/docs/walkDir.md

@@ -3,31 +3,42 @@ type: JS Module
 title: walkDir.mjs
 resource: npm/scripts/utils/walkDir.mjs
 docgen:
-  crc: 6f26e08f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 1bbc24bc
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Публічна функція `walkDir` здійснює рекурсивний пошук файлів у вказаному каталозі. Вона обходить файлову систему, ігноруючи каталоги `.git`, `node_modules` та worktree-чекаути (`.worktrees/`, `.claude/worktrees/` — повні копії репо від сесійних git-worktree Claude/агентів). Знаходячи кожен файл, вона передає його повний шлях у колбек для подальшої обробки. Компонент є read-only, тобто не виконує записів у файлову систему чи бази даних. При роботі з файловою системою він перехоплює помилки, забезпечуючи безпечну роботу без викидання винятків.
+## Огляд
+
+Файл описує правила пропуску службових і агентських шляхів під час читання репозиторію. `WORKTREE_CHECKOUT_GLOBS` задає шаблони агентських worktree-копій, `ALWAYS_IGNORE` фіксує завжди ігноровані `.git` і `node_modules`.
+
+`isWorktreeCheckoutPath` перевіряє вже відомий відносний шлях на належність до агентського worktree. `walkDir` виконує fail-safe обхід файлового дерева: перехоплює помилки читання і не передає винятки назовні.
 
 ## Поведінка
 
-1. Викликається функція walkDir для початку рекурсивного обходу каталогу.
-2. Система розшифровує вхідний шлях до кореня обходу.
-3. Система формує додаткові правила ігнорування на основі наданих шляхів.
-4. Система завжди ігнорує каталоги .git, node_modules і worktree-чекаути (.worktrees/, .claude/worktrees/) на будь-якій глибині.
-5. Система виконує пошук усіх файлів у каталозі, застосовуючи правила ігнорування, включаючи ті, що визначені в .gitignore.
-6. У разі виникнення помилки під час пошуку, процес обходу припиняється без генерації винятку.
-7. Для кожного знайденого файлу система викликає наданий колбек, передаючи йому повний абсолютний шлях до цього файлу.
+`WORKTREE_CHECKOUT_GLOBS` задає спільне правило безпеки для агентських worktree-копій, щоб обхід не сприймав дублікати репозиторію як робочий код.
+
+`ALWAYS_IGNORE` розширює це правило постійними пропусками `.git` і `node_modules`; ці винятки застосовуються під час повного обходу незалежно від налаштувань репозиторію.
+
+`walkDir` приймає корінь обходу, додає до спільних правил додаткові локальні винятки, читає файлове дерево з урахуванням `.gitignore` і передає знайдені файли далі як абсолютні шляхи. Якщо обхід неможливий, він завершується без помилки назовні, щоб перевірки залишались fail-safe.
+
+`isWorktreeCheckoutPath` використовує те саме смислове правило пропуску worktree-чекаутів для уже наявних відносних шляхів, які не проходять через `walkDir`, наприклад зі списків git.
 
 ## Публічний API
 
-- walkDir — рекурсивно переглядає файли та папки, ігноруючи ті, що вказані у файлі `.gitignore`.
-- isWorktreeCheckoutPath — предикат для відносного posix-шляху: чи лежить він усередині worktree-чекаута (`.worktrees/` або `.claude/worktrees/`). Для фільтрації git-списків, що не проходять через walkDir (наприклад, delta-список змінених файлів).
-- ALWAYS_IGNORE, WORKTREE_CHECKOUT_GLOBS — експортовані glob-константи безумовних пропусків обходу.
+- WORKTREE_CHECKOUT_GLOBS — Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
+Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
+lint-обхід бачив би дубль усього дерева.
+- ALWAYS_IGNORE — .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
+node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+- isWorktreeCheckoutPath — Чи лежить відносний posix-шлях усередині worktree-чекаута (`.worktrees/` або
+`.claude/worktrees/`). Для фільтрації git-списків, що не проходять через walkDir.
+- walkDir — Рекурсивно обходить каталог, поважаючи .gitignore (включно з вкладеними).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- Свідомо пропускає шляхи: `.git`, `node_modules`, `.worktrees/`, `.claude/worktrees/`.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

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

@@ -3,29 +3,30 @@ type: JS Module
 title: worktree-fingerprint.mjs
 resource: npm/scripts/utils/worktree-fingerprint.mjs
 docgen:
-  crc: df297382
+  crc: 38831a93
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Файл надає унікальний відбиток робочої директорії. Цей відбиток використовується для ідентифікації та порівняння робочих директорій, забезпечуючи їх унікальність у системі. Він слугує базовим інструментом для відстеження та управління версіями.
+## Огляд
+
+`worktreeFingerprint` формує стабільний fingerprint git-робочого дерева з `HEAD`, diff і `untracked`-файлів. Це потрібно, щоб розпізнавати той самий стан дерева й дедуплікувати повторні `lint --full` прогони без змін.
 
 ## Поведінка
 
-1.  Отримує поточний SHA256 хеш коміту, який знаходиться в гілці HEAD.
-2.  Отримує текст зміни між комітом HEAD та робочим каталогом.
-3.  Отримує список не відстежених файлів у робочому каталозі, не включаючи стандартні файли, що ігноруються.
-4.  Для кожного не відстеженого файлу отримує його SHA256 хеш.
-5.  Об'єднує SHA256 хеш коміту, текст зміни та пари "файл:хеш" не відстежених файлів, розділяючи їх новими рядками.
-6.  Обчислює SHA256 хеш отриманого текстового рядка.
-7.  Повертає отриманий SHA256 хеш у форматі 64-значної шестнадцяткової строки.
-8.  Якщо виникає помилка під час виконання будь-якої з операцій, повертає `null`.
+1. worktreeFingerprint визначає, чи поточне git-робоче дерево вже має унікальний стан для повторного повного lint-прогону.
+2. Якщо дерево не належить git-репо або перевірку неможливо виконати, повертає `null`.
+3. Інакше бере базовий стан з `HEAD`, додає різницю від `HEAD` і враховує всі untracked-файли, щоб зміна вмісту або набору нових файлів впливала на результат.
+4. Для untracked-файлів формує впорядковану сукупність «шлях + вміст», щоб однаковий набір файлів давав той самий fingerprint незалежно від порядку їх виявлення.
+5. На основі цього зводить весь стан дерева в один SHA-256 fingerprint у вигляді hex-рядка.
+6. Використовується як стабільний маркер незміненого дерева для відсікання повторних повних lint-прогонів.
 
 ## Публічний API
 
-worktreeFingerprint — генерує унікальний відбиток поточного стану репозиторію Git.
+- worktreeFingerprint — Fingerprint поточного стану git-робочого дерева.
 
 ## Гарантії поведінки
 
-- Функція повертає `true`, якщо відбиток дерева робіт успішно обчислено.
-- Функція повертає `null`, якщо обчислення відбитка дерева робіт не вдалося.
-- Функція не викликає винятків.
-- Функція не використовує кеш.
+- (специфічних машинно-виведених гарантій немає)

package/scripts/utils/walkDir.mjs

@@ -2,13 +2,17 @@
 import { join, relative, resolve, sep } from 'node:path'
 import { globby } from 'globby'
 
-// Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
-// Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
-// lint-обхід бачив би дубль усього дерева.
+/**
+ * Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
+ * Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
+ * lint-обхід бачив би дубль усього дерева.
+ */
 export const WORKTREE_CHECKOUT_GLOBS = ['**/.worktrees/**', '**/.claude/worktrees/**']
 
-// .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
-// node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+/**
+ * .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
+ * node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+ */
 export const ALWAYS_IGNORE = ['.git/**', 'node_modules/**', ...WORKTREE_CHECKOUT_GLOBS]
 
 const WORKTREE_CHECKOUT_RE = /(?:^|\/)(?:\.worktrees|\.claude\/worktrees)\//u

package/scripts/utils/worktree-fingerprint.mjs

@@ -1,3 +1,8 @@
+/**
+ * Fingerprint git-робочого дерева (HEAD + diff + untracked-файли) —
+ * використовується для дедуплікації повторних lint --full прогонів на
+ * незміненому дереві.
+ */
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 

package/skills/storybook/SKILL.md

@@ -12,7 +12,7 @@ version: '1.0'
 
 Джерело рішення: `docs/adr/канон-storybook-для-vue-компонентних-бібліотек.md`. Уся логіка канону
 (скоуп, скафолд, vitest-конфіг, гігієна залежностей, adopt-діагностика) живе в правилі `storybook`
-пакета `@7n/rules-lang-js` (`node_modules/@7n/rules-lang-js/rules/storybook/`) — цей скіл лише
+пакета `@7n/rules-lang-js` (`node_modules/@7n/rules-lang-js/rules/test/`) — цей скіл лише
 тонка обгортка запуску, за зразком `doc-files`.
 
 ## Передумови
@@ -50,14 +50,14 @@ npx @7n/rules lint storybook
 
 ```bash
 # Діагностика всіх пакетів у скоупі (без запису)
-bun node_modules/@7n/rules-lang-js/rules/storybook/adopt/main.mjs
+bun node_modules/@7n/rules-lang-js/rules/test/storybook-adopt/main.mjs
 
 # + генерація повністю відсутніх секцій (main.js/preview.js/mocks/scripts/vitest-конфіги
 # лишаються недоторканими, якщо вже існують хоч у якомусь вигляді)
-bun node_modules/@7n/rules-lang-js/rules/storybook/adopt/main.mjs --fix-missing
+bun node_modules/@7n/rules-lang-js/rules/test/storybook-adopt/main.mjs --fix-missing
 
 # Звузити діагностику до конкретних пакетів (root dir, той самий формат що storybook.optOut)
-bun node_modules/@7n/rules-lang-js/rules/storybook/adopt/main.mjs --fix-missing packages/ui packages/legacy-ui
+bun node_modules/@7n/rules-lang-js/rules/test/storybook-adopt/main.mjs --fix-missing packages/ui packages/legacy-ui
 ```
 
 Прогін через прямий виклик скрипта плагіна (`node_modules/@7n/rules-lang-js/...`) — CLI-плюмбінг

package/skills/taze/js/migration-cache.mjs

@@ -69,7 +69,7 @@ export async function writeMigrationCache(pkg, from, to, entry, deps = {}) {
 
 /**
  * Дописує до промпта `provider.promptFor(entry)` підсумок відомої міграції,
- * якщо кеш її знайшов — каже раннеру пропустити крок 1 (CHANGELOG/diff-
+ * якщо кеш її знайшов — каже runner-у пропустити крок 1 (CHANGELOG/diff-
  * дослідження) і одразу шукати використання в поточному проєкті.
  * @param {string} prompt базовий промпт з `provider.promptFor(entry)`
  * @param {{notes: string, sourceRepo: string}} cached кешований запис