@7n/rules 1.49.24 → 1.49.26

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.49.26] - 2026-07-27
+
+### Fixed
+
+- gate incompatible plugin API version and pin first-party plugin installs to a compatible semver range
+
+## [1.49.25] - 2026-07-27
+
+### Fixed
+
+- Збережено --path scope у doc-files fixer
+
 ## [1.49.24] - 2026-07-27
 
 ### Changed

package/package.json

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

package/rules/doc-files/check/docs/fix-worker.md

@@ -3,7 +3,7 @@ type: JS Module
 title: fix-worker.mjs
 resource: npm/rules/doc-files/check/fix-worker.mjs
 docgen:
-  crc: 452ab360
+  crc: 444c817d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -18,7 +18,7 @@ docgen:
 ## Поведінка
 
 1. Викликається `fixWorker`.
-2. Скануються файли для визначення застарілих документів (рукописні доки без docgen-frontmatter — не цілі).
+2. З порушень, знайдених detector-ом, відновлюються повні цілі застарілих документів; fixer не робить нового повного обходу checkout. Тому hook і `lint doc-files --path` генерують docs лише для власного explicit scope (рукописні доки без docgen-frontmatter — не цілі).
 3. Якщо знайдені застарілі документи, кожна цільова дока реєструється durable через `ctx.recordDurableWrite` (fallback — `ctx.recordWrite`), а потім запускається генерація батчу через `runGenerationBatch`.
 4. Батч отримує м'який дедлайн — 80% від `ctx.timeoutMs` рунга: генерація сама зупиняється до backstop-таймауту, повертає частковий прогрес штатно й не лишає фонового батчу поверх наступного rung-а. Дедлайн діє і всередині файлу: `generateDoc` ріже per-call LLM-таймаути під залишок бюджету, тож навіть перший файл, що не вкладається у рунг, обривається сам (transient), а не по backstop-таймеру runner-а.
 5. Фільтруються порушення, що стосуються сирітських документів (вихідні файли видалені); pre-image кожного реєструється у `ctx.recordWrite`.

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

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/check/main.mjs
 docgen:
-  crc: dd3f8c2a
+  crc: b5921123
 ---
 
 ## Огляд
@@ -12,7 +12,7 @@ Lint-детектор doc-files: знаходить застарілі файл
 
 ## Поведінка
 
-`lint(ctx)` збирає застарілі доки через `collectStale` (для конкретного набору змінених файлів або, якщо файлів не передано, повним скануванням дерева) і додає для кожної окреме порушення з причиною (`missing`/`crc-mismatch`/`degraded`) та шляхом джерела. Окремо сканує `docs/`-теки на сирітські доки (`scanOrphanedDocs`) — джерело яких більше не існує.
+`lint(ctx)` збирає застарілі доки через `collectStale` (для конкретного набору змінених файлів або, якщо файлів не передано, повним скануванням дерева) і додає для кожної окреме порушення з причиною (`missing`/`crc-mismatch`/`degraded`) та шляхом джерела. Сирітські доки (`scanOrphanedDocs`) перевіряються лише за повного repo-wide скану: explicit files від hook або `--path` не мають безпечної межі для такого обходу, тому не можуть зачіпати docs поза своїм scope.
 
 Реверс-мапінг: якщо серед змінених файлів трапляється сама `.md`-дока (а не її джерело), `sourceForDoc` шукає відповідний вихідний файл поруч (той самий basename, легальне розширення) і саме його передає далі в перевірку застарілості — так зміна доки теж тригерить звірку CRC її джерела.
 

package/rules/doc-files/check/fix-worker.mjs

@@ -24,16 +24,19 @@ const DEADLINE_FRACTION = 0.8
 /** @type {FixWorkerFn} */
 export async function fixWorker(violations, ctx) {
   const { cwd } = ctx
-  const { scanForDocFiles } = await import('../docgen-scan/main.mjs')
+  const { describeFile } = await import('../docgen-scan/main.mjs')
   const { runGenerationBatch, purgeOrphanedDocs } = await import('../docgen-files-batch/main.mjs')
 
   /** @type {string[]} */
   const touchedFiles = []
   const recordDoc = ctx.recordDurableWrite ?? ctx.recordWrite
 
-  // Re-scan дає повні target-обʼєкти {sourcePath, docPath, reason, …}, що їх потребує
-  // runGenerationBatch (violation несе лише file+docPath).
-  const stale = scanForDocFiles(cwd).filter(f => f.stale)
+  // Відновлюємо повні target-обʼєкти лише для порушень detector-а. Повний re-scan
+  // тут ігнорував би explicit files від hook/`lint --path` і генерував би docs
+  // для всього checkout.
+  const stale = [...new Set(violations.filter(v => v.reason !== 'orphaned-doc' && v.file).map(v => v.file))]
+    .map(sourcePath => describeFile(cwd, sourcePath))
+    .filter(f => f.stale)
   if (stale.length > 0) {
     for (const f of stale) {
       const docAbs = join(cwd, f.docPath)

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

@@ -86,14 +86,19 @@ export function lint(ctx) {
       })
     )
   }
-  for (const orphan of scanOrphanedDocs(cwd)) {
-    violations.push(
-      /** @type {Partial<import('../../../scripts/lib/lint-surface/types.mjs').LintViolation>} */ ({
-        reason: 'orphaned-doc',
-        message: `сирітський док (source видалено): ${orphan}`,
-        file: orphan
-      })
-    )
+  // Явний files-набір (hook/--path) не містить межі дерева для безпечного
+  // orphan-скану. Повний скан тут порушив би scope і міг би видалити доки поза
+  // сервісом, тому orphan-cleanup лишається лише repo-wide прогоном.
+  if (files === undefined) {
+    for (const orphan of scanOrphanedDocs(cwd)) {
+      violations.push(
+        /** @type {Partial<import('../../../scripts/lib/lint-surface/types.mjs').LintViolation>} */ ({
+          reason: 'orphaned-doc',
+          message: `сирітський док (source видалено): ${orphan}`,
+          file: orphan
+        })
+      )
+    }
   }
 
   const unavailable = unavailableDocFilesPlugins(cwd)

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

@@ -3,71 +3,35 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  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
+  crc: e7eaf408
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 90
+  issues: surzhik,judge-refine:kept-original,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Огляд: Цей файл забезпечує пошук сигналів-маркерів у файловій системі для визначення активності плагінів. Він використовує BFS-обхід для пошуку цих сигналів, визначає доступні `capabilities`, розв'язує список плагінів з конфігурації, гарантує встановлення необхідних пакетів, обробляє маніфести плагінів та надає інструменти для роботи з їхніми обробниками (`handlers`).
+Файл визначає, які плагіни `@7n/rules` активні для проєкту, щоб core міг підключити правильні каталоги правил, capabilities, документаційні розширення та handlers. Джерело правди — поле `plugins: string[]` у `.n-rules.json`: явний `[]` вимикає плагіни й автодетект, а відсутнє поле запускає повний `detectPluginsFromRepo`.
 
-## Поведінка
-
-Перевіряє наявність файлу-сигналу у корені або підтеках до `maxDepth` рівнів. Використовує BFS-обхід, який пропускає приховані директорії, `node_modules`, та `target`, для забезпечення ефективного виклику на hot-path. Повертає `true` при знаходженні сигналу. Викликає `listScannableSubdirs`.
-
-### listScannableSubdirs
-Отримує видимі підтеки для неглибокого скану, ігноруючи приховані та службові директорії. Повертає масив абсолютних шляхів підтеків (порожній, якщо директорія нечитабельна).
-
-### readRepositoryUrl
-Отримує `repository.url` з кореневого `package.json` (як рядок або об'єкт). Повертає `null`, якщо URL відсутній або файл нечитабельний.
-
-### hasGithubWorkflows
-Перевіряє наявність файлів у директорії `.github/workflows/` будь-якого YAML/YML файлу. Повертає `true` при наявності.
-
-### detectCiPlugins
-Автоматично визначає CI-плагіни за станом репозиторію. Пріоритет надається файловим сигналам. Якщо файлових сигналів немає, використовується `repository.url` з кореневого `package.json`. Якщо обидва сигнали присутні, обидва плагіни повертаються. Якщо немає жодного сигналу, повертається порожній масив. Викликає `hasGithubWorkflows` та `readRepositoryUrl`.
+Якщо `plugins` непорожній і містить лише пакети за конвенцією `@7n/rules-<category>-<name>`, автодетект домішує тільки відсутні категорії. Будь-який сторонній пакет у списку вимикає backfill повністю, щоб змішана або користувацька конфігурація залишалась ручною й передбачуваною.
 
-### detectPluginsFromRepo
-Автоматично визначає плагіни за станом репозиторію. Використовує файлові сигнали як пріоритет, з fallback на `repository.url` лише для CI-плагінів, коли файлових сигналів немає. Для Rust використовується перевірка до трьох рівнів підтек. Викликає `detectCiPlugins` та `hasLangSignal`.
+Автодетект спирається на файлові сигнали `.github/workflows/*.yml` і `azure-pipelines.yml`, а за їх відсутності — на `repository.url` з ознаками `github.com` або `dev.azure.com`. Резолв працює fail-safe: недоступні, не встановлені або несумісні плагіни не зривають lint/sync, а пропускаються; для несумісного `requiresPluginApi > PLUGIN_API_VERSION` видається warning, крім режиму `quiet:true`, де пропуск тихий. Результати кешуються в межах прогону.
 
-### 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
-Отримує шляхи до каталогів для всіх поверхонь ядра. Ядро має пріоритет. Надає масив об'єктів, що містять ім'я плагіна, шлях до його директорії та шлях до його кореня пакета.
+`resolvePluginList` бере список із `.n-rules.json`: відсутнє поле запускає повний автодетект через `detectPluginsFromRepo`, явний порожній список вимикає плагіни, а непорожній список може доповнюватися лише відсутніми категоріями. `pluginCategory` визначає ці категорії; якщо у списку є сторонній пакет, backfill не застосовується.
 
-### getActiveCapabilities
-Отримує набір capability-рядків з усіх доступних плагінів, що використовуються для визначення `requires.capability` у `concern.json`.
+`detectPluginsFromRepo` зіставляє файлові сигнали з `KNOWN_CI_PLUGINS` і `KNOWN_LANG_PLUGINS`. Для CI файлові сигнали мають пріоритет, а fallback за URL з кореневого `package.json` використовується лише коли CI-конфігів немає. Для мов працюють тільки файлові сигнали; під час неглибокого скану службові й приховані каталоги на кшталт `.github`, `.git` і `node_modules` не обходяться.
 
-### getDocFilesExtensions
-Агрегує розширення файлів, що використовуються для генерації мапи від розширення до типу-мітка. Повертає мапу `extension -> type-мітка`.
+`resolvePlugins` перетворює обрані імена на доступні плагіни: за потреби делегує встановлення в `ensurePluginInstalled`, читає маніфест, відкидає несумісні плагіни й не зриває виконання через недоступний пакет. `KNOWN_PLUGIN_RANGES` обмежує версії first-party плагінів під час автоматичного встановлення, щоб core і плагіни лишалися сумісними.
 
-### getUnavailableDeclaredPlugins
-Повертає список плагінів, які задекларовані у `config.plugins`, але відсутні у `node_modules`. Нічого не встановлює і нічого не друкує — чистий предикат для explicit CLI-діагностики.
+Результати резолву кешуються в межах процесу, щоб повторні виклики з тих самих даних не дублювали сканування, встановлення та попередження. `clearPluginResolveCache` скидає цей спільний стан для ізольованих перевірок.
 
-### getHandlers
-Отримує шляхи до модулів-обробників для певного extension-point правила ядра.
+`resolveRulesDirs` використовує `resolvePlugins`, щоб зібрати джерела правил: core іде першим, далі активні плагіни у визначеному порядку. `getActiveCapabilities` агрегує capabilities з маніфестів; ці значення використовуються для гейтів у `concern.json`.
 
-### clearPluginResolveCache
-Скидає кеш, призначений для тестів.
+`getDocFilesExtensions` і `getHandlers` читають внесок активних плагінів для документаційних розширень та extension-points. `getUnavailableDeclaredPlugins` окремо перевіряє саме явно задекларовані, але недоступні пакети, щоб CLI міг показати діагностику без автоматичного встановлення.
 
 ## Публічний API
 
@@ -98,8 +62,17 @@ per-категорійний backfill для всього списку (див.
 (через `resolveRulesDirs` тощо) і прямий виклик у sync-CLI інакше дублювали б і файловий
 скан, і warning про backfill.
   ігнорується при cache hit — warning друкується щонайбільше раз на `(root, declared)` за процес
+- KNOWN_PLUGIN_RANGES — Сумісний semver-range для first-party плагінів: обмежує автоматичну інсталяцію (`ensurePluginInstalled`)
+поточною core-сумісною лінією, щоб майбутній несумісний major/minor плагіна не встановився
+мовчки поверх старого core (Фаза 0, spec 2026-07-27-universal-plugin-slots-lang-php-extraction.md
+§10). Для `0.x`-пакетів — caret на поточний minor (`^0.22`, а не голий `^0`, який під caret-
+семантикою розгортається у весь діапазон `0.x`); для `>=1` — caret на поточний major (`^1`).
+Невідомий (сторонній, не з цієї таблиці) пакет інсталюється без обмеження версії — як і раніше.
 - ensurePluginInstalled — Гарантує, що плагін встановлений: якщо `node_modules/<pkg>` нема — `bun add -d <pkg>`
-(дописує devDependency і ставить). Фейл — warning + false, без винятку.
+(дописує devDependency і ставить). Для first-party пакетів з `KNOWN_PLUGIN_RANGES` версія
+обмежується сумісним range (`<pkg>@^<major>` або `@^<major>.<minor>` для `0.x`); сторонні
+пакети встановлюються без обмеження, bun сам резолвить latest. Фейл — warning + false, без
+винятку.
 - resolvePlugins — Повний резолв плагінів проєкту (з кешем на процес).
   лише вже встановлені пакети, без `bun add`; `quiet` — без warning-ів (hook на кожен файл)
 - resolveRulesDirs — Rules-каталоги для всіх поверхонь ядра: ядро першим (його правила/концерни виграють

package/scripts/lib/resolve-plugins.mjs

@@ -23,10 +23,17 @@
  * `{ "capabilities": ["ci:github"], "contributes": { "rules": true, "handlers": { "<point>": "./mod.mjs" } } }`.
  * `capabilities` живлять гейт концернів (`concern.json` → `requires.capability`);
  * `handlers` — іменовані extension-points правил ядра (v1: лише API, споживачі — v2).
+ *
+ * Сумісність plugin API (Фаза 0, spec 2026-07-27-universal-plugin-slots-lang-php-extraction.md
+ * §10): маніфест може декларувати число `requiresPluginApi`. Якщо воно більше за
+ * `PLUGIN_API_VERSION` цього core — плагін несумісний і пропускається у `resolvePlugins()` із
+ * warning (окрім `quiet:true`, де пропуск тихий). Відсутнє або нечислове поле — сумісний, як і
+ * всі чинні на сьогодні маніфести (жоден з них поля ще не декларує).
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
 import { join, resolve } from 'node:path'
+import { PLUGIN_API_VERSION } from './plugin-api.mjs'
 
 /** Відомі CI-плагіни для автовизначення: сигнал у дереві репо → npm-пакет. */
 export const KNOWN_CI_PLUGINS = Object.freeze({
@@ -246,19 +253,41 @@ function computePluginList(root, declared, options) {
   return [...names, ...missing]
 }
 
+/**
+ * Сумісний semver-range для first-party плагінів: обмежує автоматичну інсталяцію (`ensurePluginInstalled`)
+ * поточною core-сумісною лінією, щоб майбутній несумісний major/minor плагіна не встановився
+ * мовчки поверх старого core (Фаза 0, spec 2026-07-27-universal-plugin-slots-lang-php-extraction.md
+ * §10). Для `0.x`-пакетів — caret на поточний minor (`^0.22`, а не голий `^0`, який під caret-
+ * семантикою розгортається у весь діапазон `0.x`); для `>=1` — caret на поточний major (`^1`).
+ * Невідомий (сторонній, не з цієї таблиці) пакет інсталюється без обмеження версії — як і раніше.
+ */
+export const KNOWN_PLUGIN_RANGES = Object.freeze({
+  '@7n/rules-ci-github': '^1',
+  '@7n/rules-ci-azure': '^1',
+  '@7n/rules-lang-js': '^0.22',
+  '@7n/rules-lang-python': '^0.10',
+  '@7n/rules-lang-rust': '^0.13'
+})
+
 /**
  * Гарантує, що плагін встановлений: якщо `node_modules/<pkg>` нема — `bun add -d <pkg>`
- * (дописує devDependency і ставить). Фейл — warning + false, без винятку.
+ * (дописує devDependency і ставить). Для first-party пакетів з `KNOWN_PLUGIN_RANGES` версія
+ * обмежується сумісним range (`<pkg>@^<major>` або `@^<major>.<minor>` для `0.x`); сторонні
+ * пакети встановлюються без обмеження, bun сам резолвить latest. Фейл — warning + false, без
+ * винятку.
  * @param {string} projectRoot корінь репозиторію
  * @param {string} packageName npm-ім'я плагіна
+ * @param {typeof import('node:child_process').spawnSync} [spawnFn] інжект для тестів (типово — реальний `spawnSync`)
  * @returns {boolean} true — пакет доступний у node_modules після виклику
  */
-export function ensurePluginInstalled(projectRoot, packageName) {
+export function ensurePluginInstalled(projectRoot, packageName, spawnFn = spawnSync) {
   const installed = join(projectRoot, 'node_modules', packageName, 'package.json')
   if (existsSync(installed)) return true
   if (!existsSync(join(projectRoot, 'package.json'))) return false
 
-  const r = spawnSync('bun', ['add', '-d', packageName], { cwd: projectRoot, encoding: 'utf8', shell: false })
+  const range = KNOWN_PLUGIN_RANGES[packageName]
+  const spec = range ? `${packageName}@${range}` : packageName
+  const r = spawnFn('bun', ['add', '-d', spec], { cwd: projectRoot, encoding: 'utf8', shell: false })
   if (r.error || r.status !== 0) {
     const reason = r.error ? r.error.message : `bun add exit ${r.status}`
     console.warn(`⚠️  Плагін ${packageName} не встановився (${reason}) — пропускаю\n`)
@@ -272,22 +301,30 @@ export function ensurePluginInstalled(projectRoot, packageName) {
  * @property {string} name npm-ім'я пакета (`@7n/rules` для ядра)
  * @property {string} packageRoot абсолютний корінь пакета
  * @property {string} rulesDir абсолютний шлях до `rules/` пакета
- * @property {{ capabilities: string[], contributes: { rules?: boolean, handlers?: Record<string, string>, docFilesExtensions?: Record<string, string> } }} manifest нормалізований блок `n-rules` з package.json плагіна
+ * @property {{ capabilities: string[], requiresPluginApi: number | null, contributes: { rules?: boolean, handlers?: Record<string, string>, docFilesExtensions?: Record<string, string> } }} manifest нормалізований блок `n-rules` з package.json плагіна
  */
 
 /**
  * Маніфест плагіна з блоку `"n-rules"` його package.json (з дефолтами).
+ * `requiresPluginApi` — необов'язкове число; нечислове/відсутнє значення нормалізується у
+ * `null` (сумісний за замовчуванням — сумісність перевіряє `resolvePlugins()`).
  * @param {string} packageRoot корінь пакета
  * @returns {ResolvedPlugin['manifest']} нормалізований маніфест
  */
 function readPluginManifest(packageRoot) {
   /** @type {ResolvedPlugin['manifest']} */
-  const fallback = { capabilities: [], contributes: { rules: true, handlers: {}, docFilesExtensions: {} } }
+  const fallback = {
+    capabilities: [],
+    requiresPluginApi: null,
+    contributes: { rules: true, handlers: {}, docFilesExtensions: {} }
+  }
   try {
     const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
     const raw = pkg?.['n-rules']
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return fallback
     const capabilities = Array.isArray(raw.capabilities) ? raw.capabilities.filter(c => typeof c === 'string') : []
+    const requiresPluginApi =
+      typeof raw.requiresPluginApi === 'number' && Number.isFinite(raw.requiresPluginApi) ? raw.requiresPluginApi : null
     const contributes = raw.contributes && typeof raw.contributes === 'object' ? raw.contributes : {}
     const handlers =
       contributes.handlers && typeof contributes.handlers === 'object' && !Array.isArray(contributes.handlers)
@@ -303,12 +340,38 @@ function readPluginManifest(packageRoot) {
             Object.entries(rawDocFiles.extensions).filter(([k, v]) => k.startsWith('.') && typeof v === 'string')
           )
         : {}
-    return { capabilities, contributes: { rules: contributes.rules !== false, handlers, docFilesExtensions } }
+    return {
+      capabilities,
+      requiresPluginApi,
+      contributes: { rules: contributes.rules !== false, handlers, docFilesExtensions }
+    }
   } catch {
     return fallback
   }
 }
 
+/**
+ * Чи декларує маніфест plugin API, несумісний із цією core-лінією (Фаза 0 передумова повної
+ * slots-міграції: `requiresPluginApi > PLUGIN_API_VERSION`). Друкує warning (окрім
+ * `quiet:true`) — виносить умову й побічний ефект з `resolvePlugins()`, щоб не роздувати її
+ * cognitive complexity.
+ * @param {string} name npm-ім'я плагіна (для повідомлення)
+ * @param {ResolvedPlugin['manifest']} manifest нормалізований маніфест плагіна
+ * @param {boolean} quiet без warning-у
+ * @returns {boolean} true — плагін несумісний, пропускаємо
+ */
+function isIncompatiblePluginApi(name, manifest, quiet) {
+  if (manifest.requiresPluginApi === null || manifest.requiresPluginApi <= PLUGIN_API_VERSION) return false
+  // Плагін декларує plugin API, несумісний із цією core-лінією — пропускаємо, а не
+  // завантажуємо його як rules-only з мовчазною втратою handlers/doc-files/fragments.
+  if (!quiet) {
+    console.warn(
+      `⚠️  Плагін ${name} потребує plugin API v${manifest.requiresPluginApi}, ця core-лінія підтримує v${PLUGIN_API_VERSION} — пропускаю, онови @7n/rules\n`
+    )
+  }
+  return true
+}
+
 /**
  * Повний резолв плагінів проєкту (з кешем на процес).
  * @param {string} projectRoot корінь репозиторію
@@ -338,6 +401,7 @@ export function resolvePlugins(projectRoot, config, options = {}) {
       continue
     }
     const manifest = readPluginManifest(packageRoot)
+    if (isIncompatiblePluginApi(name, manifest, options.quiet === true)) continue
     const rulesDir = join(packageRoot, 'rules')
     if (manifest.contributes.rules && !existsSync(rulesDir)) {
       // Плагін ДЕКЛАРУЄ правила (rules !== false), але каталогу нема — битий пакет.