@7n/rules 1.46.0 → 1.47.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.47.1] - 2026-07-23
+
+### Fixed
+
+- doc-files: явна діагностика замість тихого 0 кандидатів, коли задекларований плагін (.n-rules.json) не встановлений у node_modules
+
+## [1.47.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.46.0] - 2026-07-23
 
 ### Added

package/package.json

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

package/rules/doc-files/check/docs/main.md

@@ -3,30 +3,27 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/check/main.mjs
 docgen:
-  crc: 2af6c6b9
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: dd3f8c2a
 ---
 
 ## Огляд
 
-Lint-детектор concern-а `doc-files/check`: виявляє застарілі файлові доки (CRC-mismatch, відсутність, деградація) та «сирітські» доки, чиє джерело видалено. Виключно read-only детект — генерація й очистка живуть у `fix-worker.mjs` (docgen), не тут.
+Lint-детектор doc-files: знаходить застарілі файлові доки (CRC-mismatch/missing/degraded) і сирітські доки, чиє джерело видалено. Read-only — саму генерацію/очистку виконує `fix-worker.mjs`.
 
 ## Поведінка
 
-1. `lint(ctx)`: у delta-режимі (`ctx.files` задано) змінені шляхи зводяться до множини вихідних кодових файлів — для зміненої `docs/*.md`-доки reverse-map-ом знаходиться її джерело у батьківській теці; без `ctx.files` — повний скан репо.
-2. Для кожного джерела перевіряється актуальність його доки (`describeFile`/`scanForDocFiles`); застаріла/відсутня дока → порушення з причиною (`reason`) і шляхом джерела.
-3. Окремо скануються «сирітські» доки (`scanOrphanedDocs`) — `docs/*.md`, чиє джерело видалено; кожна — порушення `orphaned-doc`.
-4. Повертається `LintResult` зі списком порушень — без жодних мутацій.
+`lint(ctx)` збирає застарілі доки через `collectStale` (для конкретного набору змінених файлів або, якщо файлів не передано, повним скануванням дерева) і додає для кожної окреме порушення з причиною (`missing`/`crc-mismatch`/`degraded`) та шляхом джерела. Окремо сканує `docs/`-теки на сирітські доки (`scanOrphanedDocs`) — джерело яких більше не існує.
+
+Реверс-мапінг: якщо серед змінених файлів трапляється сама `.md`-дока (а не її джерело), `sourceForDoc` шукає відповідний вихідний файл поруч (той самий basename, легальне розширення) і саме його передає далі в перевірку застарілості — так зміна доки теж тригерить звірку CRC її джерела.
+
+Якщо мапа doc-files-розширень від активних плагінів порожня, а хоча б один плагін явно задекларований у `.n-rules.json`, але не встановлений у `node_modules` — детектор додає `diagnostics`-запис (`level: 'warn'`) з підказкою запустити `bun install`. Це відрізняє "плагін не встановлено" від "усі доки актуальні": без нього обидва випадки виглядають як 0 порушень.
 
 ## Публічний API
 
-collectStale — перелік застарілих доків: для `files` (delta) або всього репо (undefined);
-lint — детектор застарілих і сирітських файлових доків, повертає `{ violations }`.
+- `lint(ctx)` — детектор concern-а `doc-files/check`: повертає `{ violations, diagnostics? }`.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
-- Fail-safe: помилка читання теки джерела дає `null`-reverse-map (джерело пропускається), не виняток.
+- Read-only: не пише і не видаляє жодних файлів.
+- Перехоплює помилки читання файлової системи (напр. нечитабельна тека) — не пропускає винятків назовні.
+- Diagnostics-попередження про невстановлений плагін рендериться лише при `--verbose` на explicit CLI-виклику (`lint doc-files --no-fix --verbose`) — у PostToolUse-хуку (без `verbose`) обчислюється, але ніколи не друкується.

package/rules/doc-files/check/main.mjs

@@ -5,6 +5,7 @@ import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
 
 import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
+import { unavailableDocFilesPlugins } from '../docgen-scan/lang-extensions.mjs'
 
 const DOC_MD_RE = /(?:^|\/)docs\/[^/]+\.md$/u
 
@@ -95,5 +96,11 @@ export function lint(ctx) {
     )
   }
 
-  return { violations }
+  const unavailable = unavailableDocFilesPlugins(cwd)
+  if (unavailable.length === 0) return { violations }
+
+  const word = unavailable.length > 1 ? 'плагіни' : 'плагін'
+  const verb = unavailable.length > 1 ? 'не встановлені' : 'не встановлений'
+  const message = `doc-files: 0 кандидатів через недоступні плагіни — ${word} ${unavailable.join(', ')} ${verb} у node_modules — запусти bun install`
+  return { violations, diagnostics: [{ level: 'warn', message }] }
 }

package/rules/doc-files/docgen-scan/docs/lang-extensions.md

@@ -3,32 +3,40 @@ type: JS Module
 title: lang-extensions.mjs
 resource: npm/rules/doc-files/docgen-scan/lang-extensions.mjs
 docgen:
-  crc: 3c5bc28b
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: 14b28432
+  model: omlx/gemma-4-e2b-it-4bit
+  tier: local-min
+  score: 95
 ---
 
 ## Огляд
 
-Збирає з активних плагінів у репозиторії мапу розширень doc-files і мовні екстрактори для них, щоб інші частини системи могли підготувати обробку файла за доступними плагінними можливостями. `pluginDocFilesExtensions` формує перелік підтримуваних doc-files розширень, `loadDocFilesExtractors` підтягує екстрактори мов із плагінів, а `clearDocFilesLangCache` скидає кеш у межах прогону. Спирається на `.n-rules.json` і `.n-cursor.json` як джерело конфігурації активних плагінів та їхніх правил. Працює fail-safe: биті handler-модулі мовчки пропускає, не кидає винятків назовні, кешує стан у межах прогону.
+Огляд: Модуль керує завантаженням та очищенням документів та логіки для перевірок. Забезпечує функціональний потік, який включає отримання мапи розширень, завантаження екстракторів та очищення кешу для тестування.
 
 ## Поведінка
 
-- `pluginDocFilesExtensions` — повертає мапу розширень doc-files, які декларують активні плагіни в репозиторії, з урахуванням кешу для поточного прогону.
-- `loadDocFilesExtractors` — завантажує мовні екстрактори з handler-модулів плагінів для doc-files і повертає їх за розширеннями; биті модулі мовчки пропускає, тож для таких файлів далі можливий whole-file шлях.
-- `clearDocFilesLangCache` — скидає внутрішній кеш мовних розширень і екстракторів, щоб наступний прогін прочитав актуальний стан заново.
+Поведінка крос-функціональний потік
+pluginDocFilesExtensions повертає мапу розширень задекларованих у конфігах
+loadDocFilesExtractors вантажує мовні екстрактори з handler-модулів
+unavailableDocFilesPlugins повертає список плагінів, які не встановлені
+clearDocFilesLangCache скидає кеші для тестування
 
 ## Публічний API
 
-- pluginDocFilesExtensions — збирає з активних плагінів карту розширень для doc-files і тримає її в процесному кеші; порожній результат означає, що жоден плагін не оголосив підтримку.
-- loadDocFilesExtractors — підвантажує мовні extractors із plugin handler-модулів для extension-point `doc-files`; якщо модуль зламаний, його тихо пропускає і далі обробляє файл цілком.
-- clearDocFilesLangCache — очищає кеші, щоб тести починали з чистого стану.
+- pluginDocFilesExtensions — Мапа doc-files-розширень від плагінів для репо (`.rs` → 'Rust Module', …),
+з кешем на процес. Порожня мапа — жодний активний плагін їх не декларує.
+- loadDocFilesExtractors — Асинхронно вантажить мовні екстрактори з handler-модулів плагінів
+(extension-point `doc-files`): default-експорт
+`{ id, extensions: string[], extractFacts?, extractUnits? }`.
+Битий модуль — мовчазний пропуск (генерація тоді йде whole-file шляхом).
+- unavailableDocFilesPlugins — Задекларовані у `.n-rules.json` плагіни, недоступні в `node_modules` — рахується лише
+коли мапа doc-files-розширень порожня (інакше принаймні один плагін реально доступний,
+шукати "недоступні" немає сенсу — не hot-path concern, рахується лише в рідкісному
+порожньому випадку).
+- clearDocFilesLangCache — Скидає кеші (для тестів).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
 - Кешує результати в межах одного прогону.

package/rules/doc-files/docgen-scan/lang-extensions.mjs

@@ -3,7 +3,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
-import { getDocFilesExtensions, getHandlers } from '../../../scripts/lib/resolve-plugins.mjs'
+import {
+  getDocFilesExtensions,
+  getHandlers,
+  getUnavailableDeclaredPlugins
+} from '../../../scripts/lib/resolve-plugins.mjs'
 
 /**
  * Мовні розширення doc-files від плагінів (фаза 4 spec lang-plugins-extraction).
@@ -82,6 +86,19 @@ export async function loadDocFilesExtractors(cwd) {
   return map
 }
 
+/**
+ * Задекларовані у `.n-rules.json` плагіни, недоступні в `node_modules` — рахується лише
+ * коли мапа doc-files-розширень порожня (інакше принаймні один плагін реально доступний,
+ * шукати "недоступні" немає сенсу — не hot-path concern, рахується лише в рідкісному
+ * порожньому випадку).
+ * @param {string} cwd корінь репозиторію
+ * @returns {string[]} npm-імена задекларованих, але не встановлених плагінів (порожньо — усе гаразд)
+ */
+export function unavailableDocFilesPlugins(cwd) {
+  if (Object.keys(pluginDocFilesExtensions(cwd)).length > 0) return []
+  return getUnavailableDeclaredPlugins(cwd, readPluginsConfigSync(cwd))
+}
+
 /** Скидає кеші (для тестів). */
 export function clearDocFilesLangCache() {
   EXT_CACHE.clear()

package/scripts/lib/docs/resolve-plugins.md

@@ -3,15 +3,122 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: 2bac9b49
+  crc: 52b1765f
+  model: omlx/gemma-4-e2b-it-4bit
+  tier: local-min
+  score: 40
+  issues: internal-name:hasLangSignal,internal-name:listScannableSubdirs,internal-name:readRepositoryUrl,internal-name:hasGithubWorkflows,internal-name:detectCiPlugins,surzhik,best-of-2:retry-error
 ---
 
-Резолв плагінів @7n/rules: визначає, які пакети-плагіни активні у проєкті, де їхні `rules/`-каталоги, які capabilities вони надають і які handlers надають.
+## Огляд
 
-Джерело правди — поле `plugins: string[]` у `.n-rules.json`; воно завжди перекриває автодетект, а явний порожній масив означає «плагіни вимкнено». Якщо поля немає, `detectPluginsFromRepo` шукає файлові сигнали: наявність yml у `.github/workflows/` дає `@7n/rules-ci-github`, файл `azure-pipelines.yml` у корені — `@7n/rules-ci-azure` (реєстр `KNOWN_CI_PLUGINS`). Лише коли файлових CI-сигналів немає, вмикається fallback за `repository.url` кореневого package.json (`github.com` → github, `dev.azure.com`/`visualstudio.com` → azure). Обидва сигнали дають обидва плагіни, жодного — порожній список. Окремо від CI детектяться мовні плагіни (реєстр `KNOWN_LANG_PLUGINS`, лише файлові сигнали, без URL-fallback): кореневий `pyproject.toml` → `@7n/rules-lang-python`.
+Огляд: Цей файл забезпечує пошук сигналів-маркерів у файловій системі для визначення активності плагінів. Він використовує BFS-обхід для пошуку цих сигналів, визначає доступні `capabilities`, розв'язує список плагінів з конфігурації, гарантує встановлення необхідних пакетів, обробляє маніфести плагінів та надає інструменти для роботи з їхніми обробниками (`handlers`).
 
-`ensurePluginInstalled` ставить відсутній плагін через `bun add -d` (пакет стає devDependency — зміна видима у diff). Будь-який фейл установки (offline, пакет не опублікований) — warning і graceful skip, ніколи не hard-fail: лінт і синк мають працювати без мережі.
+## Поведінка
 
-`resolvePlugins(projectRoot, config, options)` — головна функція: повертає масив `{name, packageRoot, rulesDir, manifest}` доступних плагінів з кешем на процес. `options.allowInstall: false` — hot-path режим (hook, lint): лише вже встановлені пакети, без `bun add`; `options.quiet: true` глушить warning-и (hook викликається на кожен файл). Плагін, що декларує правила (`contributes.rules !== false`), але не має каталогу `rules/`, пропускається як битий; плагін із явним `contributes.rules: false` (лише handlers, як `lang-*`) — легальний, `resolveRulesDirs` його просто не включає у джерела правил.
+Перевіряє наявність файлу-сигналу у корені або підтеках до `maxDepth` рівнів. Використовує BFS-обхід, який пропускає приховані директорії, `node_modules`, та `target`, для забезпечення ефективного виклику на hot-path. Повертає `true` при знаходженні сигналу. Викликає `listScannableSubdirs`.
 
-Маніфест — блок `"n-rules"` у package.json плагіна: `capabilities` (масив рядків на кшталт `ci:github`, живлять гейт концернів `requires.capability`) і `contributes.handlers` (мапа extension-point → відносний шлях модуля). `getActiveCapabilities` агрегує capabilities усіх плагінів у Set; `getHandlers(point)` повертає абсолютні шляхи модулів-обробників (перший реальний споживач — taze-оркестратор, extension-point `taze`). `resolveRulesDirs` віддає впорядковані джерела правил: ядро завжди перше (його правила й концерни виграють колізії), далі плагіни у порядку списку. `clearPluginResolveCache` скидає кеш (для тестів).
+### listScannableSubdirs
+Отримує видимі підтеки для неглибокого скану, ігноруючи приховані та службові директорії. Повертає масив абсолютних шляхів підтеків (порожній, якщо директорія нечитабельна).
+
+### readRepositoryUrl
+Отримує `repository.url` з кореневого `package.json` (як рядок або об'єкт). Повертає `null`, якщо URL відсутній або файл нечитабельний.
+
+### hasGithubWorkflows
+Перевіряє наявність файлів у директорії `.github/workflows/` будь-якого YAML/YML файлу. Повертає `true` при наявності.
+
+### detectCiPlugins
+Автоматично визначає CI-плагіни за станом репозиторію. Пріоритет надається файловим сигналам. Якщо файлових сигналів немає, використовується `repository.url` з кореневого `package.json`. Якщо обидва сигнали присутні, обидва плагіни повертаються. Якщо немає жодного сигналу, повертається порожній масив. Викликає `hasGithubWorkflows` та `readRepositoryUrl`.
+
+### detectPluginsFromRepo
+Автоматично визначає плагіни за станом репозиторію. Використовує файлові сигнали як пріоритет, з fallback на `repository.url` лише для CI-плагінів, коли файлових сигналів немає. Для Rust використовується перевірка до трьох рівнів підтек. Викликає `detectCiPlugins` та `hasLangSignal`.
+
+### pluginCategory
+Визначає категорію плагіна на основі naming convention `@7n/rules-<category>-<name>`. Повертає `null` для пакетів, що не відповідають цій конвенції (сторонні/кастомні плагіни) — такий пакет ніколи не з'являється сам через автодетект, а якщо присутній у явному `config.plugins`, вимикає backfill категорій для всього списку.
+
+### resolvePluginList
+Обчислює список плагінів проєкту. Використовує явне поле `config.plugins` з `.n-rules.json` або автоматичний автодетект. Явний пустий масив означає "плагіни вимкнено". Якщо `config.plugins` містить сторонній пакет, який не є `@7n/rules-*`, то backfill для заповнення списку вимикається повністю.
+
+### computePluginList
+Обчислює список плагінів без кешу. Використовує сире значення `config.plugins` з `.n-rules.json`. Повертає список плагінів. Викликає `detectPluginsFromRepo` та `pluginCategory`.
+
+### ensurePluginInstalled
+Гарантує наявність пакета: якщо він відсутній у `node_modules`, виконує `bun add -d <pkg>` для додання його як `devDependency`. Фейл повертає `false` з попередженням.
+
+### readPluginManifest
+Отримує нормалізований маніфест плагіна з його `package.json` з блоку `"n-rules"`.
+
+### resolvePlugins
+Виконує повне визначення доступних плагінів проєкту з використанням кешу. Дозволяє встановити вже встановлені пакети через `allowInstall: false` (для hot-path хука), ігнорує `bun add`, ігнорує `quiet` для уникнення попереджень при виклику на кожному файлі. Повертає масив доступних плагінів.
+
+### resolveRulesDirs
+Отримує шляхи до каталогів для всіх поверхонь ядра. Ядро має пріоритет. Надає масив об'єктів, що містять ім'я плагіна, шлях до його директорії та шлях до його кореня пакета.
+
+### getActiveCapabilities
+Отримує набір capability-рядків з усіх доступних плагінів, що використовуються для визначення `requires.capability` у `concern.json`.
+
+### getDocFilesExtensions
+Агрегує розширення файлів, що використовуються для генерації мапи від розширення до типу-мітка. Повертає мапу `extension -> type-мітка`.
+
+### getUnavailableDeclaredPlugins
+Повертає список плагінів, які задекларовані у `config.plugins`, але відсутні у `node_modules`. Нічого не встановлює і нічого не друкує — чистий предикат для explicit CLI-діагностики.
+
+### getHandlers
+Отримує шляхи до модулів-обробників для певного extension-point правила ядра.
+
+### clearPluginResolveCache
+Скидає кеш, призначений для тестів.
+
+## Публічний API
+
+- KNOWN_CI_PLUGINS — Відомі CI-плагіни для автовизначення: сигнал у дереві репо → npm-пакет.
+- KNOWN_LANG_PLUGINS — Відомі мовні плагіни: файловий сигнал екосистеми → npm-пакет. `maxDepth` —
+до якої глибини шукати сигнал: python — лише корінь (uv-провайдер v1
+обробляє тільки кореневий pyproject.toml; js — кореневий package.json); rust — до 3 рівнів, бо в
+монорепо Cargo.toml часто вкладений (Tauri `app/src-tauri/Cargo.toml`),
+а провайдер обробляє всі знайдені маніфести.
+- detectPluginsFromRepo — Автодетект плагінів за станом репозиторію: CI-плагіни (файлові сигнали з
+fallback на `repository.url`) + мовні плагіни (лише файлові сигнали —
+маніфест екосистеми в корені або, для rust, у підтеках до 3 рівнів; URL-fallback для мов безглуздий).
+- pluginCategory — Категорія плагіна за naming convention `@7n/rules-<category>-<name>` (напр. `ci`, `lang`).
+`null` — пакет поза цією конвенцією (сторонній/кастомний плагін); такий пакет ніколи не
+зʼявляється сам через автодетект і, якщо присутній у явному `config.plugins`, вимикає
+per-категорійний backfill для всього списку (див. `resolvePluginList`).
+- resolvePluginList — Список плагінів проєкту: явний `config.plugins` або автодетект.
+
+Явний `plugins` непорожній і складається **виключно** з пакетів `@7n/rules-<category>-*` —
+автодетект домішує лише категорії, відсутні в списку (ADR
+`260719-2154-per-category-автодетект-плагінів`); категорія, присутня хоч одним пакетом,
+лишається зафіксованою користувачем. Якщо `plugins` містить хоча б один сторонній
+(не `@7n/rules-*`) пакет — це сигнал ручного керування, backfill вимикається повністю
+(як і раніше: список повертається як є). Явний `[]` — «плагіни вимкнено», без backfill.
+Поле відсутнє взагалі — повний автодетект.
+
+Результат кешується на процес за `(projectRoot, declared)` — виклик з `resolvePlugins`
+(через `resolveRulesDirs` тощо) і прямий виклик у sync-CLI інакше дублювали б і файловий
+скан, і warning про backfill.
+  ігнорується при cache hit — warning друкується щонайбільше раз на `(root, declared)` за процес
+- ensurePluginInstalled — Гарантує, що плагін встановлений: якщо `node_modules/<pkg>` нема — `bun add -d <pkg>`
+(дописує devDependency і ставить). Фейл — warning + false, без винятку.
+- resolvePlugins — Повний резолв плагінів проєкту (з кешем на процес).
+  лише вже встановлені пакети, без `bun add`; `quiet` — без warning-ів (hook на кожен файл)
+- resolveRulesDirs — Rules-каталоги для всіх поверхонь ядра: ядро першим (його правила/концерни виграють
+колізії), далі плагіни у порядку списку.
+- getActiveCapabilities — Активні capabilities від усіх доступних плагінів (для гейта `requires.capability` у concern.json).
+- getDocFilesExtensions — Агреговані doc-files-розширення активних плагінів: '.rs' → 'Rust Module' тощо.
+Синхронно і без установки (hot-path hook) — лише вже встановлені плагіни.
+- getUnavailableDeclaredPlugins — Задекларовані у `config.plugins` пакети, недоступні в `node_modules` (не встановлені).
+Не встановлює нічого (`allowInstall: false`) і не друкує — чистий предикат для
+explicit CLI-діагностики (напр. doc-files: 0 кандидатів через невстановлений плагін),
+яка сама вирішує, коли й де показати попередження. Автодетектовані (не задекларовані
+явно) плагіни тут не враховуються — сигнал стосується саме явного `.n-rules.json`.
+- getHandlers — Handlers для extension-point правила ядра (v1 — лише API; перший споживач — v2).
+- clearPluginResolveCache — Скидає кеш резолву (для тестів).
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`.

package/scripts/lib/resolve-plugins.mjs

@@ -401,6 +401,26 @@ export function getDocFilesExtensions(projectRoot, config) {
   return out
 }
 
+/**
+ * Задекларовані у `config.plugins` пакети, недоступні в `node_modules` (не встановлені).
+ * Не встановлює нічого (`allowInstall: false`) і не друкує — чистий предикат для
+ * explicit CLI-діагностики (напр. doc-files: 0 кандидатів через невстановлений плагін),
+ * яка сама вирішує, коли й де показати попередження. Автодетектовані (не задекларовані
+ * явно) плагіни тут не враховуються — сигнал стосується саме явного `.n-rules.json`.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @returns {string[]} npm-імена задекларованих, але не встановлених плагінів (порожньо — усе гаразд)
+ */
+export function getUnavailableDeclaredPlugins(projectRoot, config) {
+  const declared = Array.isArray(config?.plugins)
+    ? config.plugins.filter(p => typeof p === 'string' && p.trim() !== '')
+    : []
+  if (declared.length === 0) return []
+  const root = resolve(projectRoot)
+  const availableNames = new Set(resolvePlugins(root, config, { allowInstall: false, quiet: true }).map(p => p.name))
+  return declared.filter(name => !availableNames.has(name))
+}
+
 /**
  * Handlers для extension-point правила ядра (v1 — лише API; перший споживач — v2).
  * @param {string} projectRoot корінь репозиторію