@nitra/cursor 12.6.0 → 12.7.0

package/rules/changelog/docs/main.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/changelog/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль відповідає за виконання політики, використовуючи дані з meta.json. Він забезпечує перевірку та застосування логіки, визначеної в конфігурації. Виклик функції run ініціює процес виконання правила, включаючи кешування даних у межах одного прогону.
+
+## Поведінка
+
+1. Викликається для перевірки. Виконує застосування політики, перевірку JS-зацікавленостей та посилання на MDC.
+2. Якщо код виконується як окрема програма (CLI), запускається повний процес виконання правила, включаючи завантаження конфігурацій та підсумок.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки до коду, аналізує відповідність політикам та посиланням на метадані.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/changelog/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/ci4/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/ci4/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/ci4/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/ci4/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль валідує дані відповідно до правил, використовуючи конфігурацію, визначену в meta.json. Він застосовує білий список та виконує логіку перевірки. При запуску як окрема програма, він повертає код виходу, що інформує про успіх чи виявлені порушення. Модуль є Read-only, тобто не здійснює записів у файлову систему чи бази даних. Кешування даних відбувається у межах одного прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання `run` застосовує логіку правила, включаючи обробку JS-запитань, політику та посилання на MDC.
+3. Якщо код виконується як окрема програма (CLI), ініціюється повний запуск правила.
+4. Повний запуск правила зчитує конфігурацію з `meta.json`, застосовує білий список та надає зведену інформацію.
+5. Результат виконання визначає код виходу процесу: 0 для успіху або 1 для виявлення порушень.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, обробляє JS-залежності, застосовує політику та посилання MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/ci4/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/doc-files/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/doc-files/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/main.mjs
+docgen:
+  crc: 64f215a5
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль перевіряє відповідність коду та документації, спираючись на конфігурацію `meta.json`. Функція `run` перевіряє консистентність між кодом та документацією. Функція `lint` перевіряє застарілі описи документації.
+
+## Поведінка
+
+run виконує перевірку консистентності між кодом та документацією.
+
+lint перевіряє, чи не застаріли описи документації, і може автоматично їх оновлювати, якщо це дозволено конфігурацією `meta.json`.
+
+## Публічний API
+
+run — виконує основну перевірку, яка включає аналіз JS-задач, застосування політик та посилання на MDC.
+lint — сканує файли документації на наявність застарілих елементів, з можливістю автоматичного виправлення за умови активації LLM.
+llmFix — виконує добровільну генерацію виправлень за допомогою LLM, якщо це дозволено в конфігурації.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -1,12 +1,12 @@
 /** @see ./docs/docgen-files-batch.md */
-import { readFileSync, readdirSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { classifyOmlxError, preflightLocalModel } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
 import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
-import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
+import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from './docgen-scan.mjs'
 
 /**
  * Парсить `--limit N` / `--from N` / прапори режимів для дозапуску великого прогону.
@@ -215,6 +215,42 @@ function reportStats(stats) {
   }
 }
 
+/**
+ * Видаляє сирітські доки (source-файл не існує) і оновлює/прибирає index.md.
+ * Якщо після видалення в docs/-директорії лишились тільки index.md або нічого — очищує її.
+ * @param {string} root абсолютний корінь
+ * @returns {number} кількість видалених doc-файлів
+ */
+export function purgeOrphanedDocs(root) {
+  const orphans = scanOrphanedDocs(root)
+  if (orphans.length === 0) return 0
+  let deleted = 0
+  const docsDirs = new Set()
+  for (const docRel of orphans) {
+    try {
+      unlinkSync(join(root, docRel))
+      docsDirs.add(dirname(join(root, docRel)))
+      deleted++
+    } catch {
+      // race condition або вже видалено — ігноруємо
+    }
+  }
+  for (const docsAbsDir of docsDirs) {
+    if (!existsSync(docsAbsDir)) continue
+    const remaining = readdirSync(docsAbsDir)
+    const docFiles = remaining.filter(f => f.endsWith('.md') && f !== 'index.md')
+    if (docFiles.length === 0) {
+      // Лише index.md або порожня директорія — прибираємо повністю
+      const indexPath = join(docsAbsDir, 'index.md')
+      if (existsSync(indexPath)) unlinkSync(indexPath)
+      try { rmdirSync(docsAbsDir) } catch { /* не порожня — пропускаємо */ }
+    } else {
+      generateDirIndex(docsAbsDir, root)
+    }
+  }
+  return deleted
+}
+
 /**
  * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
  * @param {string[]} argv аргументи після назви субкоманди
@@ -224,11 +260,19 @@ export async function runDocFilesGenCli(argv) {
   const root = resolveRoot(argv)
   const { from, limit, overwrite } = parseGenArgs(argv)
 
+  // Видаляємо orphan-доки до генерації (незалежно від наявності stale)
+  const deleted = purgeOrphanedDocs(root)
+  if (deleted > 0) {
+    console.log(`🗑 doc-files: видалено ${deleted} сирітських доки(ів)`)
+  }
+
   const all = scanForDocFiles(root)
   const targets = selectTargets(root, all, { overwrite }).slice(from, from + limit)
 
   if (targets.length === 0) {
-    console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
+    if (deleted === 0) {
+      console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
+    }
     return 0
   }
 

package/rules/doc-files/js/docgen-scan.mjs

@@ -1,13 +1,13 @@
 /** @see ./docs/docgen-scan.md */
 import { join, dirname, basename, extname, relative, resolve, sep, isAbsolute, posix } from 'node:path'
-import { existsSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
 import { once } from 'node:events'
 import { env } from 'node:process'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { isDocgenIgnored } from './docgen-ignore.mjs'
-import { QUALITY_THRESHOLD, readDocQuality, staleness } from './docgen-crc.mjs'
+import { QUALITY_THRESHOLD, parseDocFrontmatter, readDocQuality, staleness } from './docgen-crc.mjs'
 
 /** Кодові розширення, для яких генеруємо документацію. */
 const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py', '.rs'])
@@ -78,6 +78,70 @@ export function describeFile(root, sourcePath) {
   return { sourcePath, docPath, stale, reason }
 }
 
+/**
+ * Знаходить "сирітські" доки: `docs/<stem>.md` із `resource:` + `docgen.crc` у frontmatter,
+ * у яких відповідний source-файл (resource:) вже не існує. Перевіряє лише файли,
+ * згенеровані `fix-doc-files` (наявність `docgen.crc` у frontmatter). Directory Index
+ * (resource із `/` на кінці) та ручні доки без `resource:` або без CRC — ігноруються.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {string[]} posix-шляхи сирітських doc-файлів від кореня
+ */
+export function scanOrphanedDocs(root) {
+  const orphans = []
+
+  /** @param {string} docsAbsDir абсолютний шлях docs/-директорії */
+  function scanDocsDir(docsAbsDir) {
+    let entries
+    try {
+      entries = readdirSync(docsAbsDir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+      const fullPath = join(docsAbsDir, entry.name)
+      let content
+      try {
+        content = readFileSync(fullPath, 'utf8')
+      } catch {
+        continue
+      }
+      const { data } = parseDocFrontmatter(content)
+      // Пропускаємо: Directory Index (resource з `/`), ручні доки (немає resource або CRC)
+      if (!data?.source || data.source.endsWith('/') || !data.crc) continue
+      if (!existsSync(join(root, data.source))) {
+        orphans.push(relative(root, fullPath).split(sep).join('/'))
+      }
+    }
+  }
+
+  /** Обходить дерево, шукаючи docs/-директорії для orphan-перевірки.
+   *  docs/ — входимо завжди (батьківська пройшла ignore-перевірку);
+   *  інші — перевіряємо через isDocgenIgnored. */
+  function walk(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const fullPath = join(dir, entry.name)
+      if (entry.name === 'docs') {
+        scanDocsDir(fullPath)
+      } else {
+        const relPath = relative(root, fullPath).split(sep).join('/')
+        if (isDocgenIgnored(relPath, 'dir')) continue
+        walk(fullPath)
+      }
+    }
+  }
+
+  walk(root)
+  return orphans
+}
+
 /**
  * Підмножина шляхів, які git вважає ігнорованими (`.gitignore` + global excludes).
  * Один батч-виклик `git check-ignore --stdin`. Tracked-файли git не репортить як
@@ -307,20 +371,36 @@ export async function runDocFilesCheckCli(argv) {
   }
 
   const stale = sources.map(src => describeFile(root, src)).filter(f => f.stale)
-  if (stale.length === 0) return 0
+  // В git-режимі (Stop-гейт) додатково шукаємо сирітські доки без source-файлу
+  const orphans = gitMode ? scanOrphanedDocs(root) : []
 
-  // Великий прогін: Stop-гейт не блокує, лише попереджає (захист від нескінченного блоку).
+  if (stale.length === 0 && orphans.length === 0) return 0
+
+  // Великий прогін stale: Stop-гейт не блокує, але orphan-check продовжуємо
   if (gitMode && stale.length > gateMax) {
     console.error(
       `⚠ doc-files: застарілих док ${stale.length} (> ${gateMax}) — гейт не блокує. Запусти масовий прогін:\n  npx @nitra/cursor fix-doc-files`
     )
-    return 0
+    if (orphans.length === 0) return 0
+    const oList = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${oList}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+    return 2
   }
 
-  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
-  console.error(
-    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
-  )
+  if (stale.length > 0) {
+    const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+    console.error(
+      `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
+    )
+  }
+  if (orphans.length > 0) {
+    const oList = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${oList}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+  }
   return 2
 }
 

package/rules/doc-files/js/docs/docgen-files-batch.md

@@ -3,31 +3,31 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: 18c96a58
-  score: 95
+  crc: f68c0832
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-runDocFilesGenCli
-Запускає генерацію документації для застарілих або відсутніх файлів.
+## Огляд
 
-runDocFilesStampCli
-Перештампує frontmatter джерело та CRC у наявних документах без виклику LLM.
+Модуль керує життєвим циклом документації. Він вибирає цільові документи для оновлення, видаляє непов'язані документи та виконує пакетну генерацію. Модуль забезпечує стійкість роботи, перехоплюючи помилки та не кидаючи винятків назовні. Він також детерміновано оновлює метадані існуючих документів.
 
 ## Поведінка
 
-runDocFilesGenCli
-Запускає генерацію документації для застарілих/відсутніх док.
-
-runDocFilesStampCli
-Перештампує frontmatter source+crc у наявних доках без виклику LLM.
+selectTargets фільтрує знайдені файли, вибираючи ті, що застарілі або мають низьку якість і не були спробовані раніше.
+purgeOrphanedDocs видаляє доки, для яких не існує відповідного джерела, і оновлює індекси директорій.
+runDocFilesGenCli ініціює генерацію документації, видаляючи сирітських доків, вибираючи цілі та запускаючи пакетну генерацію.
+runGenerationBatch виконує послідовний прогін цільових файлів, генеруючи документацію та керуючи цим процесом через механізм захисту від збоїв.
+runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих доків, додаючи CRC та зберігаючи якість, без виклику LLM.
 
 ## Публічний API
 
-- runDocFilesGenCli — згенерувати документацію для застарілих/відсутніх док.
-- runDocFilesStampCli — детерміновано (пере)штампувати frontmatter `source`+`crc` у наявних доках без виклику LLM. Для міграції док, які ще не мають CRC. Поля якості (`score`/`issues`) зберігаються з наявного frontmatter.
+selectTargets — Визначає цілі для генерації: застарілі або погіршені документи, які ще не пройшли перевірку CRC, або всі документи при використанні прапора перезапису.
+purgeOrphanedDocs — Видаляє документи, для яких відсутній вихідний файл, та оновлює/очищає файл `index.md` у відповідній директорії.
+runDocFilesGenCli — Генерує документацію для застарілих або відсутніх документів.
+runGenerationBatch — Виконує послідовну генерацію документів: перевіряє локальний бекенд, обробляє цілі генерації з механізмом захисту від збоїв, і надає фінальний звіт.
+runDocFilesStampCli — Додає або оновлює метадані `source` та `crc` до існуючих документів без залучення великих мовних моделей, використовуючи наявні дані про модель та якість.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.

package/rules/doc-files/js/docs/docgen-scan.md

@@ -3,50 +3,50 @@ type: JS Module
 title: docgen-scan.mjs
 resource: npm/rules/doc-files/js/docgen-scan.mjs
 docgen:
-  crc: 4c17838f
+  crc: f01465d8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-isSourceFile перевіряє, чи є файл кодовим джерелом.
-docPathForSource обчислює шлях md-документа для кодового файлу.
-isDocCandidate перевіряє, чи підлягає файл документуванню.
-describeFile описує кодовий файл, включаючи шлях доки та стан застарілості.
-scanForDocFiles рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
-resolveRoot парсить аргументи, щоб визначити абсолютний корінь.
-runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
-runDocFilesCheckCli детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+## Огляд
+
+Модуль аналізує кодову базу та пов'язану з нею документацію. Він визначає, які файли є джерелами за допомогою `isSourceFile` та знаходить відповідні шляхи документації за допомогою `docPathForSource`. Модуль перевіряє, чи не залишилися без зв'язку (сиротами) документи, використовуючи `scanOrphanedDocs`, та сканує файли документації за допомогою `scanForDocFiles`. Для роботи з кореневими каталогами використовується `resolveRoot`. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), при цьому при певних збоях повертається `null` замість викидання винятків.
 
 ## Поведінка
 
-isSourceFile Обчислює, чи є файл кодовим джерелом.
-docPathForSource Обчислює шлях md-документа для кодового файлу.
-isDocCandidate Перевіряє, чи підлягає файл документуванню.
-describeFile Описує кодовий файл, включаючи шлях доки та стан застарілості.
-scanForDocFiles Рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
-resolveRoot Парсить аргументи, щоб визначити абсолютний корінь.
-runDocFilesScanCli Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
-runDocFilesCheckCli Детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+isSourceFile визначає, чи є ім'я файлу кодовим джерелом для документування.
+docPathForSource обчислює шлях до відповідного MD-документа для заданого кодового файлу.
+isDocCandidate визначає, чи підлягає певний файл документуванню, враховуючи розширення, статус тесту та ігнорування.
+describeFile описує кодовий файл, надаючи його шлях, шлях до документації та стан застарілості.
+scanOrphanedDocs знаходить MD-документи, які посилаються на кодові файли, що більше не існують.
+scanForDocFiles рекурсивно обходить дерево і повертає список кодових файлів із їхнім станом застарілості, відфільтрований за ігноруванням Git.
+resolveRoot парсить аргументи для визначення абсолютного кореня обходу, використовуючи поточну робочу директорію за замовчуванням.
+runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+runDocFilesCheckCli виконує перевірку застарілості, підтримуючи режими для перевірки одного файлу, Git-гейту або звітів про знижену якість.
 
 ## Публічний API
 
-isSourceFile — перевіряє, чи є файл коду для документування.
-docPathForSource — обчислює шлях до документа для кодового файлу, розміщуючи його в теці `docs/` поруч із джерелом. Якщо шлях відносний, документ також відносний; якщо абсолютний, документ залишається абсолютним.
-isDocCandidate — визначає, чи підлягає кодовий файл документуванню: має правильне розширення, не є тестом, не знаходиться в ігнорованому списку, і не є кореневим системним документуванням.
-describeFile — надає опис кодового файлу: шлях до джерела, шлях до документа та стан застарілості за CRC.
-scanForDocFiles — рекурсивно переглядає дерево від заданого кореня і повертає кодові файли разом зі станом застарілості.
-resolveRoot — парсить аргумент `--root <dir>` з командного рядка; за замовчуванням використовує поточну робочу директорію.
-runDocFilesScanCli — сканує дерево і виводить JSON-масив усіх кодових файлів із зазначенням їхнього стану застарілості.
-runDocFilesCheckCli — виконує перевірку застарілості для хуків та командного рядка через інструмент `doc-files check`.
-Режими — це способи виконання:
---hook — бере шлях до файлу з вводу JSON і перевіряє один файл.
---git — перевіряє різницю в Git (`git diff --name-only HEAD`) з урахуванням порогу `--max` (за замовчуванням 50); якщо застарілості більше, не блокує (виходить з кодом 0 з попередженням).
---degraded — генерує інформаційний звіт про документи, які мають оцінку нижче встановленого порогу (виходить з кодом 0).
-<paths…> — використовується для визначення явних шляхів до джерел.
-Exit 2 — повертається, якщо знайдено застарілі дані; повертається 0, якщо дані свіжі або пройдено перевищення порогу.
+isSourceFile — визначає, чи є файл кодовим джерелом для створення документації.
+docPathForSource — визначає шлях до відповідного MD-документа, розміщений у теці `docs/` відносно коду.
+isDocCandidate — вирішує, чи повинен кодовий файл бути документований: має правильне розширення, не є тестом, не ігнорується та не є системним документом.
+describeFile — надає опис кодового файлу, включаючи його шлях, шлях до документації та статус застарілості.
+scanOrphanedDocs — шукає документи, які посилаються на кодові файли, що більше не існують, перевіряючи лише згенеровані файли.
+scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, визначаючи їхній статус застарілості, і відсіюючи ті, що ігноруються через `.gitignore`.
+resolveRoot — встановлює кореневу директорію для сканування, використовуючи аргумент командного рядка або поточну робочу директорію.
+runDocFilesScanCli — сканує дерево та виводить JSON-масив усіх кодових файлів зі статусом застарілості, дозволяючи фільтрувати лише застарілі або всі файли.
+runDocFilesCheckCli — виконує перевірку застарілості для використання у хуках та командному інтерфейсі.
+
+Режими:
+--hook — перевіряє один файл, отриманий з JSON через стандартний ввід.
+--git — порівнює файли у `git diff` та блокує процес, якщо знайдено більше за встановлений поріг застарілих файлів.
+--degraded — виводить звіт про документи з низьким показником якості.
+<paths…> — обробляє лише вказані шляхи-джерела.
+
+Вихідний код 2 — вказує на знаходження застарілих файлів (для блокування хука).
+Вихідний код 0 — вказує на відсутність застарілих файлів або проходження перевірки згідно з порогом.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/doc-files/js/docs/index.md

@@ -19,6 +19,7 @@ resource: npm/rules/doc-files/js/
 | [docgen-prompts.mjs](docgen-prompts.md) | JS Module |
 | [docgen-scan.mjs](docgen-scan.md) | JS Module |
 | [lint.mjs](lint.md) | JS Module |
+| [run-lint.mjs](run-lint.md) | JS Module |
 | [units-js.mjs](units-js.md) | JS Module |
 | [units-rs.mjs](units-rs.md) | JS Module |
 | [units.mjs](units.md) | JS Module |

package/rules/doc-files/js/docs/run-lint.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: run-lint.mjs
+resource: npm/rules/doc-files/js/run-lint.mjs
+docgen:
+  crc: ba329b37
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 80
+---
+
+## Огляд
+
+Цей модуль надає CLI-обгортку для канонічного `lint-doc-files` (doc-files.mdc): детермінованого детектора застарілості файлових док (`<dir>/docs/<stem>.md`). При відсутності прапорців або при вказанні шляхів (`[paths…]`) виконується повний або точковий детекст застарілості. Якщо знайдено застарілі файли, повертається код виходу 1. Можливі режими: `--missing-only` звужує перевірку до відсутніх файлів. Прапорець `--json` виводить JSON-лістинг усіх кандидатів. Режими `--hook`, `--git` та `--degraded` делегують перевірку через `runDocFilesCheckCli` (hook-протокол: exit 2/0). Повний прогін здійснюється через `runStandardLint` (ключ `lint-doc-files`), тоді як хук/git/degraded форми використовують канон scripts.mdc, не генеруючи логів. Поведінка описується у (doc-files.mdc).
+
+## Поведінка
+
+runLintDocFilesSteps виконує повний або точковий детект застарілості файлової документації (doc-files.mdc), повертаючи код виходу 1, якщо знайдено застарілі файли, або 0, якщо всі актуальні.
+runLintDocFilesCli керує викликом лінтера doc-files.mdc: виконує повний/точковий детект, якщо не вказано `--json`, або повертає JSON-лістинг кандидатів, якщо вказано `--json`, або делегує перевірку через протоколи `--hook`, `--git`, `--degraded`.
+
+## Публічний API
+
+runLintDocFilesSteps — Виконує повний або точковий пошук неактуальних (stale) файлів документації. Повертає код виходу 1, якщо знайдено неактуальні файли, і 0, якщо всі файли актуальні.
+runLintDocFilesCli — Виконує перевірку файлів документації через інтерфейс командного рядка. У режимах hook/git/degraded виконує делегацію без логування. З опцією `--json` виконує сканування. В інших режимах виконує повний або точковий пошук, використовуючи логіку `runStandardLint` для ключа `lint-doc-files`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/{lint/lint.mjs → js/run-lint.mjs}

@@ -23,8 +23,9 @@ import {
   resolveRoot,
   runDocFilesCheckCli,
   runDocFilesScanCli,
-  scanForDocFiles
-} from '../js/docgen-scan.mjs'
+  scanForDocFiles,
+  scanOrphanedDocs
+} from './docgen-scan.mjs'
 
 /**
  * Нормалізує шлях-кандидат до posix-шляху від кореня (null поза деревом).
@@ -73,15 +74,28 @@ export function runLintDocFilesSteps(argv) {
   let stale = described.filter(f => f.stale)
   if (missingOnly) stale = stale.filter(f => f.reason === 'missing')
 
-  if (stale.length === 0) {
+  // Orphan-детект лише при повному скані (без явних шляхів); точковий — не релевантно
+  const orphans = paths.length === 0 ? scanOrphanedDocs(root) : []
+
+  let exitCode = 0
+  if (stale.length > 0) {
+    const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+    console.error(
+      `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: npx @nitra/cursor fix-doc-files`
+    )
+    exitCode = 1
+  }
+  if (orphans.length > 0) {
+    const list = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${list}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+    exitCode = 1
+  }
+  if (exitCode === 0) {
     console.log('✓ doc-files: усі файлові доки актуальні.')
-    return 0
   }
-  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
-  console.error(
-    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: npx @nitra/cursor fix-doc-files`
-  )
-  return 1
+  return exitCode
 }
 
 /**