@7n/rules 1.32.1 → 1.33.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.33.0] - 2026-07-20
+
+### Added
+
+- Per-категорійний автодетект плагінів: явний непорожній plugins (лише з @7n/rules-`category`-*) домішує автодетектом категорії, яких у ньому немає
+
+## [1.32.2] - 2026-07-20
+
+### Changed
+
+- doc-files: згенеровано файлові доки для `k8s/dremio_logging/main.mjs` і `skills/taze/js/migration-cache.mjs`, що доти ламали tree-wide doc-files/check; вручну виправлено фабрикації локальної моделі (розбиті backtick-маркери, невірні твердження про fail-safe/scope кешу міграцій)
+
 ## [1.32.1] - 2026-07-20
 
 ### Changed

package/bin/n-rules.js

@@ -365,9 +365,11 @@ async function readConfig(paths = {}) {
     }
   }
 
-  // Плагіни: явне поле plugins конфігу або автодетект; sync-контекст — з установкою devDep.
-  // Результат детекту записуємо у конфіг (нижче), щоб hook/lint не залежали від детекту й мережі.
-  const detectedPlugins = Array.isArray(rawConfig?.plugins) ? null : resolvePluginList(cwd(), rawConfig)
+  // Плагіни: явне поле plugins конфігу (з per-категорійним backfill автодетекту — ADR
+  // 260719-2154) або повний автодетект, коли поля нема; sync-контекст — з установкою devDep.
+  // Результат записуємо у конфіг (нижче), щоб hook/lint не залежали від детекту й мережі.
+  const declaredPlugins = Array.isArray(rawConfig?.plugins) ? rawConfig.plugins : null
+  const resolvedPlugins = resolvePluginList(cwd(), rawConfig)
   const rulesDirs = resolveRulesDirs(cwd(), rawConfig, bundledRulesDir).map(d => d.rulesDir)
   const { names: availableRules } = await aggregateRuleSources(rulesDirs)
   const availableSkills = await discoverBundledSkillNames(bundledSkillsDir)
@@ -442,9 +444,17 @@ async function readConfig(paths = {}) {
     if (merged['disable-skills']?.length) {
       normalized['disable-skills'] = merged['disable-skills']
     }
-    if (!('plugins' in parsedConfig) && detectedPlugins && detectedPlugins.length > 0) {
-      normalized.plugins = detectedPlugins
-      console.log(`🔌 Автодетект плагінів: ${detectedPlugins.join(', ')} — записано у ${CONFIG_FILE}\n`)
+    if (!('plugins' in parsedConfig)) {
+      if (resolvedPlugins.length > 0) {
+        normalized.plugins = resolvedPlugins
+        console.log(`🔌 Автодетект плагінів: ${resolvedPlugins.join(', ')} — записано у ${CONFIG_FILE}\n`)
+      }
+    } else if (declaredPlugins && JSON.stringify(resolvedPlugins) !== JSON.stringify(declaredPlugins)) {
+      // per-категорійний backfill (resolvePluginList, ADR 260719-2154) додав плагін
+      // категорії, відсутньої в явному plugins — фіксуємо результат у конфізі.
+      normalized.plugins = resolvedPlugins
+      const added = resolvedPlugins.filter(p => !declaredPlugins.includes(p))
+      console.log(`🔌 Доповнено plugins у ${CONFIG_FILE} (${added.join(', ')}) — категорія не була задекларована\n`)
     }
     return sortConfigIdArrays(normalized)
   }
@@ -465,7 +475,7 @@ async function readConfig(paths = {}) {
       $schema: CONFIG_SCHEMA_URL,
       rules: autoDetectedRules.rules,
       skills: autoDetectedSkills.skills,
-      ...(detectedPlugins && detectedPlugins.length > 0 && { plugins: detectedPlugins })
+      ...(resolvedPlugins.length > 0 && { plugins: resolvedPlugins })
     })
     await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8')
     console.log(

package/package.json

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

package/rules/k8s/dremio_logging/docs/main.md

@@ -7,23 +7,23 @@ docgen:
   model: openai-codex/gpt-5.4-mini
   tier: cloud-min
   score: 95
-  issues: anchor-miss:(k8s.mdc),judge:inaccurate:0.99
+  issues: anchor-miss:(k8s.mdc),judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-`zkLogbackRootLevelViolation` перевіряє повідомлення, пов’язані з надто гучним `root` у `k8s.mdc`, а `lint` збирає ці перевірки в один pass і повертає результат без зупинки процесу. Поведінка read-only: правило не пише у ФС чи БД, працює fail-safe й не кидає винятків назовні.
+Перевіряє `zookeeper.yaml` на надто гучний `root level` у вбудованому `logback.xml` і формує звіт про порушення з маркером `zk-logback-root-level`. `zkLogbackRootLevelViolation` і `lint` працюють як read-only, не змінюють ФС чи БД, і поводяться fail-safe: помилки перехоплюються, назовні винятки не виходять.
 
 ## Поведінка
 
-- `zkLogbackRootLevelViolation` — перевіряє, чи вбудований `logback.xml` у ZooKeeper-templated файлі не тримає `root` на надто гучному рівні; повертає текст порушення з міткою `` або `null`, якщо перевірка не потрібна або рівень уже прийнятний.
-- `lint` — проходить по вказаних файлах у read-only режимі, збирає порушення для `k8s.dremio_logging` і не виводить помилки назовні; пропускає файли, які не вдалося прочитати, та позначає знайдені проблеми міткою ``.
+- `zkLogbackRootLevelViolation` — перевіряє, чи вбудований `logback.xml` у `zookeeper.yaml` має допустимий `root level` (`warn`, `error`, `off`); якщо блоку немає — не чіпає файл, якщо рівень надто гучний або відсутній — повертає текст порушення з посиланням на `k8s.mdc`.
+- `lint` — проходить по вказаних файлах, безпечно читає їх як `zookeeper.yaml`-кандидати, фіксує порушення для `k8s.dremio_logging` і не перериває перевірку на помилках читання; для кожного знайденого випадку додає повідомлення з маркером `zk-logback-root-level`.
 
 ## Публічний API
 
-- zkLogbackRootLevelViolation — позначає ZooKeeper Helm-темплейт, якщо вбудований `logback.xml` має занадто гучний `root`-рівень (`info`, `debug`, `trace`) або взагалі не задає `root`; не чіпає файли, де `root` уже `warn`, `error` чи `off`.
-- lint — запускає `k8s.dremio_logging` для ZooKeeper-темплейтів у межах одного файлу, лише для читання.
+- zkLogbackRootLevelViolation — знаходить у Helm-темплейті ZooKeeper вбудований `logback.xml`, де `root` заданий занадто гучно або взагалі відсутній; пропускає, якщо рівень уже `warn`, `error` чи `off`
+- lint — запускає `k8s.dremio_logging` для ZooKeeper-темплейту на рівні окремого файла, без змін у вмісті
 
 ## Гарантії поведінки
 

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

@@ -3,7 +3,7 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: fb58860d
+  crc: 2bac9b49
 ---
 
 Резолв плагінів @7n/rules: визначає, які пакети-плагіни активні у проєкті, де їхні `rules/`-каталоги, які capabilities вони надають і які handlers надають.

package/scripts/lib/resolve-plugins.mjs

@@ -2,10 +2,16 @@
  * Резолв плагінів `@7n/rules`: які пакети-плагіни активні у проєкті, де їхні `rules/`,
  * які capabilities вони дають і які handlers надають.
  *
- * Джерело правди — поле `plugins: string[]` у `.n-rules.json` (завжди перекриває автодетект;
- * явний `[]` = «плагіни вимкнено»). Якщо поля немає — `detectPluginsFromRepo`: файлові сигнали
- * (`.github/workflows/*.yml` → `@7n/rules-ci-github`; `azure-pipelines.yml` → `@7n/rules-ci-azure`),
- * а без них — fallback за `repository.url` кореневого package.json (`github.com` / `dev.azure.com`).
+ * Джерело правди — поле `plugins: string[]` у `.n-rules.json`. Явний `[]` = «плагіни
+ * вимкнено» (автодетект не застосовується). Якщо поля немає взагалі — повний автодетект
+ * (`detectPluginsFromRepo`). Якщо `plugins` непорожній і складається **виключно** з пакетів
+ * за конвенцією `@7n/rules-<category>-<name>` (напр. `ci`, `lang`) — автодетект домішує
+ * лише ті категорії, яких у списку немає (ADR `260719-2154-per-category-автодетект-плагінів`);
+ * будь-який сторонній (не `@7n/rules-*`) пакет у списку вимикає backfill повністю — змішаний
+ * чи повністю кастомний список означає ручне керування, без сюрпризів. Файлові сигнали
+ * автодетекту: `.github/workflows/*.yml` → `@7n/rules-ci-github`; `azure-pipelines.yml` →
+ * `@7n/rules-ci-azure`, а без них — fallback за `repository.url` кореневого package.json
+ * (`github.com` / `dev.azure.com`).
  *
  * Установка: `ensurePluginInstalled` — плагін стає devDependency через `bun add -d` (bun сам
  * резолвить актуальну версію; зміна видима у diff package.json). Фейл установки (offline,
@@ -153,18 +159,91 @@ export function detectPluginsFromRepo(projectRoot) {
   return out
 }
 
+/** Naming convention плагінів, які розпізнає автодетект: `@7n/rules-<category>-<name>`. */
+const PLUGIN_CATEGORY_RE = /^@7n\/rules-([a-z0-9]+)-/u
+
+/**
+ * Категорія плагіна за naming convention `@7n/rules-<category>-<name>` (напр. `ci`, `lang`).
+ * `null` — пакет поза цією конвенцією (сторонній/кастомний плагін); такий пакет ніколи не
+ * зʼявляється сам через автодетект і, якщо присутній у явному `config.plugins`, вимикає
+ * per-категорійний backfill для всього списку (див. `resolvePluginList`).
+ * @param {string} pkg npm-ім'я плагіна
+ * @returns {string | null} категорія або null
+ */
+export function pluginCategory(pkg) {
+  const m = PLUGIN_CATEGORY_RE.exec(pkg)
+  return m ? m[1] : null
+}
+
+/** Усі категорії, які реально може повернути `detectPluginsFromRepo` — для short-circuit коли declared вже покриває все. */
+const ALL_KNOWN_CATEGORIES = new Set(
+  [...Object.values(KNOWN_CI_PLUGINS), ...Object.values(KNOWN_LANG_PLUGINS).map(l => l.pkg)]
+    .map(pkg => pluginCategory(pkg))
+    .filter(c => c !== null)
+)
+
+/** Кеш `resolvePluginList` на процес: `root::declared-json` → результат (щоб не дублювати warning). */
+const PLUGIN_LIST_CACHE = new Map()
+
 /**
- * Список плагінів проєкту: явний `config.plugins` (включно з порожнім = вимкнено) або автодетект.
+ * Список плагінів проєкту: явний `config.plugins` або автодетект.
+ *
+ * Явний `plugins` непорожній і складається **виключно** з пакетів `@7n/rules-<category>-*` —
+ * автодетект домішує лише категорії, відсутні в списку (ADR
+ * `260719-2154-per-category-автодетект-плагінів`); категорія, присутня хоч одним пакетом,
+ * лишається зафіксованою користувачем. Якщо `plugins` містить хоча б один сторонній
+ * (не `@7n/rules-*`) пакет — це сигнал ручного керування, backfill вимикається повністю
+ * (як і раніше: список повертається як є). Явний `[]` — «плагіни вимкнено», без backfill.
+ * Поле відсутнє взагалі — повний автодетект.
+ *
+ * Результат кешується на процес за `(projectRoot, declared)` — виклик з `resolvePlugins`
+ * (через `resolveRulesDirs` тощо) і прямий виклик у sync-CLI інакше дублювали б і файловий
+ * скан, і warning про backfill.
  * @param {string} projectRoot корінь репозиторію
  * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json` (може бути відсутній)
+ * @param {{ quiet?: boolean }} [options] `quiet:true` — без warning-у про плагін, доданий автодетектом (hot-path);
+ *   ігнорується при cache hit — warning друкується щонайбільше раз на `(root, declared)` за процес
  * @returns {string[]} npm-імена плагінів
  */
-export function resolvePluginList(projectRoot, config) {
+export function resolvePluginList(projectRoot, config, options = {}) {
+  const root = resolve(projectRoot)
   const declared = config?.plugins
-  if (Array.isArray(declared)) {
-    return declared.filter(p => typeof p === 'string' && p.trim() !== '')
+  const cacheKey = `${root}::${Array.isArray(declared) ? JSON.stringify(declared) : '∅'}`
+  const cached = PLUGIN_LIST_CACHE.get(cacheKey)
+  if (cached) return cached
+
+  const result = computePluginList(root, declared, options)
+  PLUGIN_LIST_CACHE.set(cacheKey, result)
+  return result
+}
+
+/**
+ * Обчислення `resolvePluginList` без кешу (винесено окремо, щоб кеш-обгортка лишалась тонкою).
+ * @param {string} root абсолютний корінь репозиторію (вже пройшов через `resolve()`)
+ * @param {unknown} declared сире значення `config.plugins`
+ * @param {{ quiet?: boolean }} options прокинуті опції виклику
+ * @returns {string[]} npm-імена плагінів
+ */
+function computePluginList(root, declared, options) {
+  if (!Array.isArray(declared)) return detectPluginsFromRepo(root)
+
+  const names = declared.filter(p => typeof p === 'string' && p.trim() !== '')
+  if (names.length === 0) return names
+
+  const declaredCategories = new Set(names.map(pkg => pluginCategory(pkg)))
+  // Хоч один сторонній пакет у списку — не вгадуємо намір, повертаємо як є.
+  if (declaredCategories.has(null)) return names
+  // Усі відомі категорії вже покриті явним списком — не марнуємо файлові сигнали.
+  if ([...ALL_KNOWN_CATEGORIES].every(c => declaredCategories.has(c))) return names
+
+  const missing = detectPluginsFromRepo(root).filter(pkg => !declaredCategories.has(pluginCategory(pkg)))
+  if (missing.length > 0 && options.quiet !== true) {
+    const word = missing.length > 1 ? 'плагіни' : 'плагін'
+    console.warn(
+      `⚠️  Додано автодетектом ${word} ${missing.join(', ')} — категорія не задекларована явно в .n-rules.json\n`
+    )
   }
-  return detectPluginsFromRepo(projectRoot)
+  return [...names, ...missing]
 }
 
 /**
@@ -240,7 +319,7 @@ function readPluginManifest(packageRoot) {
  */
 export function resolvePlugins(projectRoot, config, options = {}) {
   const root = resolve(projectRoot)
-  const names = resolvePluginList(root, config)
+  const names = resolvePluginList(root, config, { quiet: options.quiet })
   const cacheKey = `${root}${names.join(',')}${options.allowInstall !== false}`
   const cached = RESOLVE_CACHE.get(cacheKey)
   if (cached) return cached
@@ -341,4 +420,5 @@ export function getHandlers(projectRoot, config, point) {
 /** Скидає кеш резолву (для тестів). */
 export function clearPluginResolveCache() {
   RESOLVE_CACHE.clear()
+  PLUGIN_LIST_CACHE.clear()
 }

package/skills/taze/js/docs/migration-cache.md

@@ -13,26 +13,25 @@ docgen:
 
 ## Огляд
 
-Модуль надає `DEFAULT_CACHE_DIR`, `migrationCacheKey`, `readMigrationCache`, `writeMigrationCache` і `withKnownMigrationNotes` для роботи з локальним кешем відомих результатів аналізу міграцій у межах прогону. Він зберігає та повторно читає вже відомі записи, а `withKnownMigrationNotes` підставляє їх у промпт, щоб не повторювати дослідження там, де результат уже є. Модуль fail-safe: не кидає винятків назовні й за окремих помилок повертає порожнє значення, зокрема `null`.
+Модуль керує кешем уже відомих міграцій на диску (`~/.cache/n-rules/taze-migrations` за замовчуванням) — кеш персистентний і спільний для всіх repo/worktree на машині, не обмежений одним прогоном. `migrationCacheKey` формує ключ для запису, `readMigrationCache` і `writeMigrationCache` працюють із кешованими даними, а `withKnownMigrationNotes` підставляє вже відомі відомості там, де це доречно. Читання fail-safe (`readMigrationCache` перехоплює помилки й повертає `null` замість винятку); запис (`writeMigrationCache`) винятків не перехоплює.
 
 ## Поведінка
 
-- `DEFAULT_CACHE_DIR` — стандартний спільний каталог для кешу міграцій на цій машині, щоб різні репозиторії могли повторно використовувати вже відомі результати.
-- `migrationCacheKey` — перетворює назву пакета і діапазон версій на стабільний безпечний ключ для кешу.
-- `readMigrationCache` — читає кешований запис міграції для потрібної пари версій; якщо запису немає або він пошкоджений, мовчки повертає `null`.
-- `writeMigrationCache` — зберігає результат аналізу міграції в кеш, щоб наступні запуски на цій машині могли його повторити без нового дослідження.
-- `withKnownMigrationNotes` — додає до промпта підсумок уже відомої міграції з кешу й підказує пропустити повторне дослідження та перейти до перевірки використання в поточному проєкті.
+- `DEFAULT_CACHE_DIR` — задає спільний каталог кешу міграцій для всіх репозиторіїв на цій машині.
+- `migrationCacheKey` — перетворює пару версій пакета на безпечний крос-репо ключ кешу.
+- `readMigrationCache` — читає кешований запис міграції для конкретної пари версій; якщо запису немає або він пошкоджений, повертає `null` без помилки.
+- `writeMigrationCache` — зберігає запис про вже проаналізовану міграцію в кеш, щоб не повторювати той самий аналіз у наступних прогонових середовищах.
+- `withKnownMigrationNotes` — додає до промпта підсумок відомої міграції з кешу й підказує пропустити повторне дослідження та перейти до перевірки в поточному проєкті.
 
 ## Публічний API
 
-- DEFAULT_CACHE_DIR — Спільний каталог кешу міграцій для всіх репозиторіїв на цій машині; не прив’язаний до конкретного worktree.
-- migrationCacheKey — Перетворює `` на безпечне ім’я файлу для спільного кешу між репо.
-- readMigrationCache — Повертає збережений запис міграції для ``, якщо його вже обробляли в іншому repo/worktree; відсутній або пошкоджений запис дає `null`.
-- writeMigrationCache — Записує результат LLM-обробки для ``, щоб не повторювати дослідження changelog для такого ж bump-а.
-- withKnownMigrationNotes — Додає до prompt короткий підсумок знайденої міграції і, якщо є кеш, пропускає дослідження changelog/diff на користь пошуку використання в поточному проєкті.
+- DEFAULT_CACHE_DIR — Спільний каталог для кешу міграцій на цій машині, незалежний від конкретного repo чи worktree.
+- migrationCacheKey — Перетворює `pkg`, `from` і `to` на безпечну назву файла для спільного кешу.
+- readMigrationCache — Повертає збережені дані про вже відому міграцію для тієї самої пари версій, або `null`, якщо запису немає чи він пошкоджений.
+- writeMigrationCache — Записує результат вже розібраної міграції в кеш, щоб наступний repo з тим самим оновленням не починав дослідження заново.
+- withKnownMigrationNotes — Додає до prompt короткий підсумок знайденої міграції і пропускає початковий етап з пошуком у CHANGELOG та diff.
 
 ## Гарантії поведінки
 
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
-- Кешує результати в межах одного прогону.
+- `readMigrationCache` перехоплює помилки читання/парсингу й повертає `null` замість винятку (fail-safe); `writeMigrationCache` винятків не перехоплює.
+- Кеш персистентний на диску і спільний для всіх repo/worktree на машині — не обмежений одним прогоном.