@7n/rules 1.40.1 → 1.42.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.42.0] - 2026-07-22
+
+### Added
+
+- warnAboutRulesWithoutConcerns: попередження, якщо rule-id з .n-rules.json#rules не знайдено в жодному rulesDir (ядро+плагіни) — ловить дрейф конфігу після переїзду concern-ів у плагін
+
+## [1.41.0] - 2026-07-22
+
+### Fixed
+
+- doc-files: прибрано безумовний T0 CRC-штамп для crc-mismatch (fix-check.mjs) — свіжий CRC поверх застарілого тексту назавжди маскував дрейф доки; тепер застаріла дока завжди регенерується fix-worker-ом (docgen). Guardrail: detectRefusalFiller ловить нові живі refusal-фрази локальної моделі («мені потрібен сам код», «щоб написати точну документацію», «I need the code»)
+
 ## [1.40.1] - 2026-07-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.40.1",
+  "version": "1.42.0",
   "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: 27e4dca1
+  crc: 452ab360
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -13,6 +13,8 @@ docgen:
 
 Файл забезпечує генерацію застарілих або відсутніх файлових доків за допомогою docgen-pipeline (локальна/хмарна модель) через функцію fixWorker. Кожна згенерована дока реєструється як durable-write (самодостатній кінцевий стан зі свіжим CRC), тому rollback провального rung-а її не стирає, а великий беклог сходиться за кілька прогонів (issue nitra/cursor#16). Видалення сирітських доків лишається під звичайним rollback.
 
+Інваріант конвеєра: `crc-mismatch` не закривається детермінованим T0-штампом CRC (fix-check.mjs для check свідомо відсутній) — свіжий CRC поверх старого тексту назавжди маскував би дрейф доки. Застаріла дока завжди йде через регенерацію тут; свіжий CRC зʼявляється лише разом зі щойно згенерованим вмістом (stampDoc усередині runGenerationBatch).
+
 ## Поведінка
 
 1. Викликається `fixWorker`.
@@ -26,3 +28,4 @@ docgen:
 ## Гарантії поведінки
 
 - Кожна записана дока — валідний фінальний стан (свіжий CRC; degraded теж валідна) — часткова робота не втрачається при таймауті/провалі rung-а.
+- CRC у frontmatter ніколи не оновлюється без регенерації вмісту — дрейф доки не маскується.

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

@@ -8,6 +8,12 @@
  * тож rollback провального rung-а її не стирає, і великий беклог сходиться
  * крок за кроком за кілька прогонів. Видалення сирітських док лишається під
  * звичайним rollback (ctx.recordWrite).
+ *
+ * Інваріант: `crc-mismatch` НЕ закривається детермінованим T0-штампом CRC
+ * (fix-check.mjs для check свідомо відсутній). Свіжий CRC поверх старого тексту
+ * назавжди маскує дрейф — CRC-гейт вважає доку актуальною і вона більше ніколи
+ * не регенерується. Свіжий CRC зʼявляється лише разом зі щойно згенерованим
+ * вмістом (stampDoc усередині runGenerationBatch).
  * @typedef {import('../../../scripts/lib/lint-surface/types.mjs').FixWorkerFn} FixWorkerFn
  */
 import { join } from 'node:path'

package/rules/doc-files/docgen-judge/docs/main.md

@@ -3,13 +3,13 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-judge/main.mjs
 docgen:
-  crc: ac56c24b
+  crc: 47127362
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
 ## Огляд
 
-Огляд: Цей файл визначає інтерфейс для механізму семантичного судження якості згенерованої технічної документації за допомогою мовної моделі. Він конфігурує параметри (`JUDGE_MODEL`, `JUDGE_ENABLED`, `JUDGE_CONFIDENCE`) та надає read-only функції для ініціації судження та інтерпретації його результатів. Додатково містить детермінований пре-гейт `detectRefusalFiller` (0 токенів): курований список refusal/чат-філер фраз моделі («Я готовий писати…», «Надайте мені код…»), які структурний скорер і суддя пропускали (живий кейс: score=95 на доці з суцільним філером).
+Огляд: Цей файл визначає інтерфейс для механізму семантичного судження якості згенерованої технічної документації за допомогою мовної моделі. Він конфігурує параметри (`JUDGE_MODEL`, `JUDGE_ENABLED`, `JUDGE_CONFIDENCE`) та надає read-only функції для ініціації судження та інтерпретації його результатів. Додатково містить детермінований пре-гейт `detectRefusalFiller` (0 токенів): курований список refusal/чат-філер фраз моделі («Я готовий писати…», «Надайте мені код…», «мені/нам потрібен сам код/файл/вміст», «щоб написати точну документацію», «I need the code»), які структурний скорер і суддя пропускали (живі кейси: score=95 на доці з суцільним філером; 2026-07-21 — «Щоб написати точну документацію, мені потрібен сам код…» злите прямо в тіло доки).
 
 Поведінка:
 JUDGE_MODEL — конфігурує LLM, яка використовується для семантичного судження якості документації.

package/rules/doc-files/docgen-judge/main.mjs

@@ -35,9 +35,11 @@ const VERDICTS = new Set(['accurate', 'generic', 'inaccurate'])
  * Детермінований пре-гейт (0 токенів) ПЕРЕД LLM-суддею: чат-філер/refusal локальної
  * моделі замість документації. Живий кейс: дока зі score=95, де секції — суцільне
  * «Я готовий писати поведінкову документацію… Надайте мені код» (gemma) — судді
- * структура здалась валідною. Курований безпечний список (перша особа/імператив до
- * користувача не трапляються у нормальній поведінковій доці); без `\b` — кирилиця
- * не ASCII-`\w`, JS-межі слова не спрацьовують.
+ * структура здалась валідною. Другий живий кейс (2026-07-21, робота над storybook):
+ * модель злила «Щоб написати точну документацію, мені потрібен сам код…» прямо в
+ * тіло доки — жоден зі старих патернів не збігався. Курований безпечний список
+ * (перша особа/імператив до користувача не трапляються у нормальній поведінковій
+ * доці); без `\b` — кирилиця не ASCII-`\w`, JS-межі слова не спрацьовують.
  */
 const REFUSAL_FILLER_RES = [
   /я готов(?:ий|а)/iu,
@@ -47,8 +49,12 @@ const REFUSAL_FILLER_RES = [
   /не можу\s+(?:згенерувати|створити|написати)/iu,
   /чекаю на\s+(?:код|файл|вміст)/iu,
   /давайте почнемо/iu,
+  // живий кейс 2026-07-21: «Щоб написати точну документацію, мені потрібен сам код…»
+  /(?:мені|нам)\s+(?:потрібен|потрібно|потрібна|потрібні)\s+(?:сам(?:ий|е)?\s+)?(?:код|файл|вміст|джерел)/iu,
+  /щоб написати\s+(?:точну|повну|якісну|детальну)\s+документацію/iu,
   /as an ai(?: language)? model/iu,
   /i(?:['’]m| am)\s+(?:ready to|unable to)/iu,
+  /i need\s+(?:the\s+)?(?:source\s+)?(?:code|file)/iu,
   /please provide(?: the| me)?\s+(?:code|file|source)/iu
 ]
 

package/rules/doc-files/main.mdc

@@ -30,8 +30,12 @@ unified lint surface (spec `docs/specs/2026-06-29-unified-lint-surface.md`) і
 
 Алгоритм детекту (кандидати, ignore-дерево, CRC, реверс-мапінг доки→джерело) — у
 `docgen-scan/main.mjs` / `docgen-crc/main.mjs` / `docgen-ignore/main.mjs`, детектор — у
-`check/main.mjs` (`lint(ctx)`), fix — у `check/fix-check.mjs` (T0) і `check/fix-worker.mjs`
-(LLM); тут — лише людинозрозумілий контракт, без дублювання логіки.
+`check/main.mjs` (`lint(ctx)`), fix — лише `check/fix-worker.mjs` (LLM-регенерація); тут —
+лише людинозрозумілий контракт, без дублювання логіки.
+
+T0-штампу CRC для `crc-mismatch` **немає навмисно**: свіжий CRC поверх старого тексту
+назавжди маскує дрейф (CRC-гейт вважає доку актуальною і вона більше не регенерується).
+Свіжий CRC пише лише генерація разом із новим вмістом.
 
 ## Hook'и
 

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: run-detectors.mjs
 resource: npm/scripts/lib/lint-surface/run-detectors.mjs
 docgen:
-  crc: 128fe3b7
+  crc: a0f45fc3
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -40,3 +40,5 @@ detectAll виконує прохід лінтера у режим детекц
 **Multi-dir (плагіни):** `effectiveRulesDirs` додає rules-каталоги плагінів з `.n-rules.json` (hot-path: без install, quiet); `readLintConcernsByRuleMulti` зливає концерни за іменем (перший власник виграє) — плагін може додавати концерни до правила ядра (mixin).
 
 **Capability-гейт:** `filterByCapabilities` відкидає концерни з незадоволеним `requires.capability` (capabilities надають встановлені плагіни через маніфест `n-rules.capabilities`; явний `opts.capabilities` у тестах перекриває резолв).
+
+**Warning про rule-id без concern-ів:** якщо rule-id з `.n-rules.json#rules` не має жодного concern-а серед усіх `rulesDirs` (ядро + плагіни) — `console.error` попереджає про можливий дрейф конфігу (типово: правило переїхало в плагін, якого консюмер не підключив у `plugins[]`). Rule-id з існуючим каталогом, але без `concern.json` (документаційні правила на кшталт `feedback`), warning не тригерить.

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -152,15 +152,70 @@ async function readLintConcernsByRuleMulti(rulesDirs) {
   return merged
 }
 
+/**
+ * Імена ВСІХ каталогів верхнього рівня під `rulesDirs` — незалежно від того, чи знайшлись
+ * у них concern-и. Потрібно, щоб відрізнити «каталог є, просто без lint-поверхні» (легітимно
+ * для суто-документаційних правил на кшталт `feedback`/`local-ai`) від «каталогу немає
+ * взагалі ні в ядрі, ні в жодному підключеному плагіні» (ознака дрейфу конфігу — типово
+ * правило переїхало в плагін, якого консюмер не підключив).
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни).
+ * @returns {Promise<Set<string>>} унікальні імена каталогів-правил.
+ */
+async function discoverAllRuleDirNames(rulesDirs) {
+  const { readdir } = await import('node:fs/promises')
+  /** @type {Set<string>} */
+  const names = new Set()
+  for (const dir of rulesDirs) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith('.')) names.add(e.name)
+    }
+  }
+  return names
+}
+
+/**
+ * Попереджає про rule-id з `.n-rules.json#rules`, яких немає ЖОДНИМ каталогом ні в ядрі, ні
+ * в підключених плагінах (не плутати з «каталог є, але без concern-ів» — легітимний випадок
+ * для суто-документаційних правил). Типова причина: правило переїхало в окремий плагін
+ * (напр. `js` → `@7n/rules-lang-js` з фази 5c), а `plugins[]` консюмера про це не знає —
+ * тоді перевірки для цього правила мовчки НЕ виконуються (0 знайдених concern-ів виглядає
+ * як «усе чисто», хоча насправді нічого не перевірялось).
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id (з усіх rulesDirs).
+ * @param {import('../read-n-rules-config-lite.mjs').LiteConfig} config розпарсений .n-rules.json.
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни), для перевірки «каталог є, але порожній».
+ * @returns {Promise<void>}
+ */
+async function warnAboutRulesWithoutConcerns(byRule, config, rulesDirs) {
+  const missing = config.rules.filter(id => !(id in byRule))
+  if (missing.length === 0) return
+  const allDirNames = await discoverAllRuleDirNames(rulesDirs)
+  for (const ruleId of missing) {
+    if (allDirNames.has(ruleId)) continue // каталог є, просто без lint-поверхні — легітимно
+    console.error(
+      `⚠️  .n-rules.json: правило "${ruleId}" не знайдено НІ В ОДНОМУ з rulesDirs (ні в ядрі, ні в ` +
+        `підключених плагінах "plugins") — перевірки для нього НЕ виконуються. Якщо правило нещодавно ` +
+        `переїхало в окремий плагін, додай відповідний пакет у "plugins" (і в devDependencies).`
+    )
+  }
+}
+
 /**
  * Активні rule-id з `.n-rules.json` (для delta/full режимів).
  * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
  * @param {string} cwd робоча директорія прогону.
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни) — для warning про відсутні правила.
  * @returns {Promise<string[]>} перелік активних rule-id.
  */
-async function enabledRuleIds(byRule, cwd) {
+async function enabledRuleIds(byRule, cwd, rulesDirs) {
   const config = await readNRulesConfigLite(cwd)
   if (!config.exists) return []
+  await warnAboutRulesWithoutConcerns(byRule, config, rulesDirs)
   return Object.keys(byRule).filter(id => isRuleEnabled(config, id))
 }
 
@@ -189,7 +244,8 @@ function sortEntries(entries) {
  * @returns {Promise<PlanItem[]>} впорядкований план прогону.
  */
 export async function buildDetectPlan(opts) {
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
   return buildPlan({
     byRule,
     full: opts.full === true,
@@ -198,7 +254,8 @@ export async function buildDetectPlan(opts) {
     pathMode: opts.pathMode === true,
     repoWide: opts.repoWide === true,
     baseRef: typeof opts.baseRef === 'string' ? opts.baseRef : null,
-    cwd: opts.cwd
+    cwd: opts.cwd,
+    rulesDirs
   })
 }
 
@@ -209,8 +266,9 @@ export async function buildDetectPlan(opts) {
  * @returns {Promise<{ byRule: Record<string, ConcernMeta[]>, enabledSet: Set<string> }>} concerns і активні правила.
  */
 export async function loadEnabledLintRules(opts) {
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
-  const enabledSet = new Set(await enabledRuleIds(byRule, opts.cwd))
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
+  const enabledSet = new Set(await enabledRuleIds(byRule, opts.cwd, rulesDirs))
   return { byRule, enabledSet }
 }
 
@@ -378,6 +436,7 @@ export function computeActiveDomains(byRule, enabledSet, changed) {
  * @param {boolean} [args.repoWide] `--repo-wide`: лише full-scope concerns, whole-repo.
  * @param {string|null} [args.baseRef] явна база дельти (`--base <ref>`) замість каскаду main→origin/main.
  * @param {string} args.cwd робоча директорія прогону.
+ * @param {string[]} [args.rulesDirs] rules-каталоги (ядро + плагіни) — для warning про відсутні правила.
  * @returns {Promise<PlanItem[]>} впорядкований план прогону.
  */
 async function buildPlan({
@@ -388,14 +447,15 @@ async function buildPlan({
   pathMode = false,
   repoWide = false,
   baseRef = null,
-  cwd
+  cwd,
+  rulesDirs = []
 }) {
   // scoped + --path: per-file concerns названих правил × перетин path ∩ дельта
   if (rules.length > 0 && explicitFiles !== null) return buildScopedDeltaPlan(byRule, rules, explicitFiles)
   // scoped: усі lint-concerns названих правил, whole-repo
   if (rules.length > 0) return buildScopedPlan(byRule, rules)
 
-  const enabled = await enabledRuleIds(byRule, cwd)
+  const enabled = await enabledRuleIds(byRule, cwd, rulesDirs)
   const enabledSet = new Set(enabled)
 
   // repo-wide: лише full-scope concerns (окремий CI-workflow, не гейтить деплой)
@@ -557,7 +617,8 @@ export async function detectAll(opts) {
   const verbose = opts.verbose === true
   const baseLog = opts.log ?? (s => process.stdout.write(s))
 
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
   const plan = await buildPlan({
     byRule,
     full,
@@ -566,7 +627,8 @@ export async function detectAll(opts) {
     pathMode: opts.pathMode === true,
     repoWide: opts.repoWide === true,
     baseRef: typeof opts.baseRef === 'string' ? opts.baseRef : null,
-    cwd
+    cwd,
+    rulesDirs
   })
 
   // Detect-only бар — ЛИШЕ в TTY (без тикера «виправлено»). У не-TTY (hooks, CI-gate,

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

@@ -1,28 +0,0 @@
----
-type: JS Module
-title: fix-check.mjs
-resource: npm/rules/doc-files/check/fix-check.mjs
-docgen:
-  crc: 9a1d9107
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
-  score: 100
-  issues: judge:inaccurate:0.97
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Файл реалізує детерміноване оновлення CRC-штампів у документації, що спрацьовує після виявлення розбіжності `crc-mismatch`. Механізм автоматично оновлює метадані документації, щоб фіксувати відповідність між зміненими джерелами та вже існуючим, незміненим контентом. Це забезпечує точну валідацію метаданих системи.
-
-## Поведінка
-
-1.  Перевіряється наявність вказівок на розбіжність CRC у документації.
-2.  Для документації, яка відповідає критеріям розбіжності CRC, але є цілісною, виконується детерміноване оновлення CRC в метаданих.
-3.  Операція включає аналіз якості документації, ініційована з використанням відповідних моделей.
-4.  Оновлена документація записується у файл, ідентифікований шляхом до документації, що відповідає розбіжності.
-5.  Повертається булеве значення, що вказує на те, чи було внесено зміни у документацію.
-
-## Гарантії поведінки
-
-- (специфічних машинно-виведених гарантій немає)

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

@@ -1,45 +0,0 @@
-/**
- * T0-autofix doc-files/check — детермінований CRC-stamp для `crc-mismatch` доків
- * (джерело змінилось, але дока актуальна → лише оновити CRC у frontmatter, без LLM).
- * `missing`/`degraded`/`orphaned-doc` лишаються worker-у (генерація/очистка).
- *
- * Unified lint surface: structured violations; запускається ПЕРЕД fix-worker-ом.
- */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-
-/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
-export const patterns = [
-  {
-    id: 'doc-files-stamp-crc',
-    test: violations => violations.some(v => v.reason === 'crc-mismatch'),
-    apply: async (violations, ctx) => {
-      const { scanForDocFiles } = await import('../docgen-scan/main.mjs')
-      const { crc32, readDocModel, readDocQuality, stampDoc } = await import('../docgen-crc/main.mjs')
-      const { cwd } = ctx
-      /** @type {string[]} */
-      const touchedFiles = []
-
-      const staleFiles = scanForDocFiles(cwd).filter(f => f.stale && f.reason === 'crc-mismatch')
-      for (const file of staleFiles) {
-        const sourceAbs = join(cwd, file.sourcePath)
-        const docAbs = join(cwd, file.docPath)
-        if (!existsSync(docAbs)) continue // missing → worker, не T0
-        const { score, issues, judgeModel } = readDocQuality(docAbs)
-        const quality = score === null ? null : { score, issues, judge: judgeModel ? { model: judgeModel } : undefined }
-        const crc = crc32(readFileSync(sourceAbs))
-        ctx.recordWrite?.(docAbs)
-        mkdirSync(dirname(docAbs), { recursive: true })
-        writeFileSync(
-          docAbs,
-          stampDoc(readFileSync(docAbs, 'utf8'), file.sourcePath, crc, quality, readDocModel(docAbs))
-        )
-        touchedFiles.push(docAbs)
-      }
-
-      return touchedFiles.length > 0
-        ? { touchedFiles, message: `stamped CRC: ${touchedFiles.length} доки(ів)` }
-        : { touchedFiles: [] }
-    }
-  }
-]