@nitra/cursor 5.3.4 → 5.4.0

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

@@ -0,0 +1,54 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-scan.mjs
+  crc: 46f11827
+  score: 100
+---
+
+# docgen-scan.mjs
+
+## Огляд
+
+isSourceFile перевіряє, чи є файл кодовим джерелом.
+docPathForSource обчислює шлях md-документа для кодового файлу.
+isDocCandidate перевіряє, чи підлягає файл документуванню.
+describeFile описує кодовий файл, включаючи шлях доки та стан застарілості.
+scanForDocFiles рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
+resolveRoot парсить аргументи, щоб визначити абсолютний корінь.
+runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+runDocFilesCheckCli детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+
+## Поведінка
+
+isSourceFile Обчислює, чи є файл кодовим джерелом.
+docPathForSource Обчислює шлях md-документа для кодового файлу.
+isDocCandidate Перевіряє, чи підлягає файл документуванню.
+describeFile Описує кодовий файл, включаючи шлях доки та стан застарілості.
+scanForDocFiles Рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
+resolveRoot Парсить аргументи, щоб визначити абсолютний корінь.
+runDocFilesScanCli Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+runDocFilesCheckCli Детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+
+## Публічний 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, якщо дані свіжі або пройдено перевищення порогу.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -0,0 +1,36 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/lint.mjs
+  crc: f25a3bbe
+  score: 100
+---
+
+# lint.mjs
+
+## Огляд
+
+Адаптер правила doc-files до агрегатора `n-cursor lint`. Дає агрегатору відповідь на одне
+питання: чи має кожен дотичний кодовий файл актуальну файлову документацію поряд із собою.
+
+## Поведінка
+
+У quick-фазі отримує список змінених файлів і зводить його до набору джерел для перевірки в
+**обидва** боки: змінене джерело перевіряється проти своєї доки, а змінена або видалена дока
+(`<dir>/docs/<stem>.md`) повертається до відповідного джерела з тим самим іменем у каталозі над
+`docs/`. У ci-фазі (списку немає) обходить усе дерево.
+
+Порушенням вважається відсутня дока (`missing`) або розбіжність контрольної суми джерела з тією,
+що записана у frontmatter доки (`crc-mismatch`). Документ із низькою якістю, але свіжою сумою —
+не порушення.
+
+## Публічний API
+
+`lint` — перевіряє документацію для переданого набору змінених файлів (або всього репозиторію,
+якщо набір не задано); повертає код виходу `1`, якщо є застарілі чи відсутні доки, інакше `0`.
+Список проблемних файлів друкується у stderr із підказкою регенерувати.
+
+## Гарантії поведінки
+
+- Детермінованість: жодного виклику мовної моделі, рішення лише за контрольною сумою.
+- Реверс-мапінг доки до джерела перебирає лише кодові розширення і повертає наявний файл-кандидат.
+- Порожній набір змінених файлів дає код `0` без обходу дерева.

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

@@ -0,0 +1,31 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/units-js.mjs
+  crc: 58b898cc
+  score: 100
+---
+
+# units-js.mjs
+
+## Огляд
+
+Файл парсить програму, ітеруючи по її елементах для збору юнітів. Для кожної декларації визначається опис. Для функцій та класів збираються виклики інших юнітів через ребра викликів.
+
+## Поведінка
+
+1. Парсинг програми.
+2. Ітерація по тілу програми.
+3. Збір юнітів.
+4. Для кожної декларації визначається опис.
+5. Для функцій та класів збираються виклики інших юнітів.
+6. Вибираються виклики інших юнітів з ребрами викликів.
+
+## Публічний API
+
+extractUnitsJs — Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc, прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/rules/doc-files/js/docs/units-rs.md

@@ -0,0 +1,35 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/units-rs.mjs
+  crc: 114e9a0b
+  score: 100
+---
+
+# units-rs.mjs
+
+## Огляд
+
+Файл аналізує структуру коду для вилучення інформації про юніти. Процес включає сканування рядків, ітерацію для визначення глибини блоків та позиції закриваючих лапок. Обробляються рядкові літерали для визначення межі блоків та підраховуються глибини блоків для визначення видимості. Обробляються декларації для визначення публічності. Витягується тіло функцій, структур, перерахувань або трейтів. Визначається експонування функцій через атрибути. Збирається документація перед декларацією. Формується об'єкт юніту з назвою, типом, публічністю, ім'я impl та діапазон. Визначається область видимості тіла за допомогою пошуку закриваючої фігу. Збираються виклики інших юнітів у тілі функції.
+
+## Поведінка
+
+1. Скан файлу по рядках.
+2. Ітерація по рядках для визначення глибини блоків.
+3. Обробка рядкових літералів для визначення позиції закриваючого лапки.
+4. Підрахунок глибини блоків для визначення видимості.
+5. Обробка декларацій для визначення публічності.
+6. Витягнення тіла функції, структури, перерахування або трейта.
+7. Визначення експонування функції через атрибути.
+8. Збір документації перед декларацією.
+9. Формування об'єкта юніту з назвою, типом, публічністю, ім'ям impl та діапазоном.
+10. Визначення області видимості тіла за допомогою пошуку закриваючої фігу.
+11. Збір викликів інших юнітів у тілі функції.
+
+## Публічний API
+
+extractUnitsRs — Визначає top-level і impl-методи через підрахунок дужок по рядках. Обмеження: рядкові літерали з `{`/`}` всередині `{}` можуть дати хибну глибину.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/units.mjs
+  crc: af91bd0d
+  score: 100
+---
+
+# units.mjs
+
+## Огляд
+
+Файл витягує одиниці з вмісту файлу залежно від розширення шляху. Якщо розширення належить до набору JS_EXT, використовується extractUnitsJs. Якщо розширення дорівнює 'rs', використовується extractUnitsRs. В інших випадках функція повертає null.
+
+## Поведінка
+
+1.  extractUnits приймає вміст файлу та шлях файлу.
+2.  Перевіряє розширення шляху.
+3.  Якщо розширення знаходиться у наборі JS_EXT, викликає extractUnitsJs.
+4.  Якщо розширення дорівнює 'rs', викликає extractUnitsRs.
+5.  У інших випадках повертає null.
+
+## Публічний API
+
+extractUnits — Визначає тип парсингу залежно від розширення файлу: js/mjs/ts використовує oxc AST, rs використовує regex+brace-counting, vue/py повертає null (повний шлях).
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/rules/doc-files/js/lint.mjs

@@ -0,0 +1,96 @@
+/**
+ * Адаптер агрегатора `n-cursor lint` для правила doc-files.
+ *
+ * Quick-фаза отримує список змінених файлів і мапить їх у пари в **обидва** боки:
+ *  - змінене **джерело** (`.js/.mjs/.ts/.vue/.py/.rs`) → перевірка його доки `<dir>/docs/<stem>.md`;
+ *  - змінена/видалена **дока** (`<dir>/docs/<stem>.md`) → перевірка відповідного джерела
+ *    (той самий stem у каталозі над текою `docs`).
+ * Ci-фаза (files === undefined) проганяє повний скан дерева.
+ *
+ * Порушення — `missing` ∪ `crc-mismatch` (детермінований CRC-детект, 0 LLM-токенів);
+ * degraded не блокує. Exit 1 — є stale; 0 — все свіже (конвенція агрегатора).
+ */
+import { join, dirname, basename, extname } from 'node:path'
+import { existsSync, readdirSync } from 'node:fs'
+
+import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles } from './docgen-scan.mjs'
+
+/** Дока живе у `<dir>/docs/<stem>.md`; повертає `<dir>/<stem>` для реверс-мапінгу. */
+const DOC_MD_RE = /(?:^|\/)docs\/[^/]+\.md$/u
+
+/**
+ * Реверс-мапінг доки → джерело: для `<dir>/docs/<stem>.md` шукає у `<dir>` файл
+ * `<stem>.<ext>` із кодовим розширенням, що існує і є кандидатом на доку.
+ * @param {string} cwd корінь репо
+ * @param {string} docRel posix-шлях доки від кореня
+ * @returns {string|null} posix-шлях джерела або null
+ */
+function sourceForDoc(cwd, docRel) {
+  const docsDir = dirname(docRel) // `<dir>/docs`
+  const srcDir = dirname(docsDir) // `<dir>`
+  const stem = basename(docRel, '.md')
+  let entries
+  try {
+    entries = readdirSync(join(cwd, srcDir), { withFileTypes: true })
+  } catch {
+    return null
+  }
+  for (const e of entries) {
+    if (!e.isFile() || !isSourceFile(e.name)) continue
+    if (basename(e.name, extname(e.name)) !== stem) continue
+    const rel = srcDir === '.' ? e.name : `${srcDir}/${e.name}`
+    if (isDocCandidate(cwd, rel)) return rel
+  }
+  return null
+}
+
+/**
+ * Зводить список змінених файлів у множину джерел-кандидатів для перевірки доки.
+ * @param {string[]} files змінені шляхи (posix або нативні)
+ * @param {string} cwd корінь репо
+ * @returns {string[]} унікальні posix-шляхи джерел
+ */
+function sourcesFromChanged(files, cwd) {
+  const out = new Set()
+  for (const raw of files) {
+    const rel = raw.split('\\').join('/')
+    if (DOC_MD_RE.test(rel)) {
+      const src = sourceForDoc(cwd, rel)
+      if (src) out.add(src)
+    } else if (isDocCandidate(cwd, rel) && existsSync(join(cwd, rel))) {
+      out.add(rel)
+    }
+  }
+  return [...out]
+}
+
+/**
+ * Друкує список stale і повертає exit-код.
+ * @param {Array<{sourcePath:string, reason:string|null}>} stale застарілі описи
+ * @returns {number} 1 — є stale; 0 — немає
+ */
+function reportStale(stale) {
+  if (stale.length === 0) return 0
+  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+  process.stderr.write(
+    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: npx @nitra/cursor fix-doc-files\n`
+  )
+  return 1
+}
+
+/**
+ * Крок агрегатора lint для doc-files.
+ * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
+ * @param {string} [cwd] корінь репо
+ * @returns {Promise<number>} 0 — OK, 1 — є застарілі доки
+ */
+export function lint(files, cwd = process.cwd()) {
+  if (files === undefined) {
+    const stale = scanForDocFiles(cwd).filter(f => f.stale)
+    return Promise.resolve(reportStale(stale))
+  }
+  const sources = sourcesFromChanged(files, cwd)
+  if (sources.length === 0) return Promise.resolve(0)
+  const stale = sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
+  return Promise.resolve(reportStale(stale))
+}

package/{skills → rules}/doc-files/js/units-rs.mjs

@@ -9,7 +9,10 @@
 function skipString(src, i) {
   i++ // відкриваючий "
   while (i < src.length) {
-    if (src[i] === '\\') { i += 2; continue }
+    if (src[i] === '\\') {
+      i += 2
+      continue
+    }
     if (src[i] === '"') return i + 1
     i++
   }
@@ -38,8 +41,15 @@ function findClosingBrace(src, start) {
       i = end === -1 ? src.length : end + 2
       continue
     }
-    if (ch === '"') { i = skipString(src, i); continue }
-    if (ch === '{') { depth++; i++; continue }
+    if (ch === '"') {
+      i = skipString(src, i)
+      continue
+    }
+    if (ch === '{') {
+      depth++
+      i++
+      continue
+    }
     if (ch === '}') {
       depth--
       if (depth === 0) return i
@@ -73,12 +83,17 @@ function docBefore(lines, lineIdx) {
   return doc.join(' ').trim()
 }
 
-// Pub-items: pub fn / pub struct / pub enum / pub trait / pub type
+// Pub-items матчаться у два кроки по trim-нутому рядку (прості регекспи без
+// бектрекінгу): спершу опційний pub(...)-префікс, потім сама декларація.
 // Також ловить fn без pub (для localSymbols і impl-методів)
-const ITEM_RE = /^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
+const PUB_PREFIX_RE = /^pub(?:\([^)]*\))?\s+/
+const ITEM_DECL_RE = /^(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
 
-// impl Type { або impl<T> Trait for Type {
-const IMPL_RE = /^[ \t]*(?:pub\s+)?impl(?:<[^>]*>)?\s+(?:(?:\w[\w:<>, ]*\s+for\s+))?(\w+)/
+// impl Type { або impl<T> Trait for Type { — теж двокроково: голова `impl<...>`,
+// далі тип після `for` (trait-impl) або перше слово (inherent impl)
+const IMPL_HEAD_RE = /^impl(?:<[^>]*>)?\s+/
+const IMPL_FOR_TYPE_RE = /\bfor\s+(\w+)/
+const TYPE_NAME_RE = /^(\w+)/
 
 // Підозрілі exposure-атрибути, що роблять непуб-fn фактично публічними
 const EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/
@@ -93,7 +108,7 @@ const CALL_RE = /\b([a-z_]\w*)\s*\(/g
  * хибну глибину (рідкісно в реальному Rust-коді з rustfmt).
  * @param {string} src вміст файлу
  * @param {string} [_relPath] резервний (не використовується)
- * @returns {Array<{name:string, kind:string, exported:boolean, implName:string|null, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null}
+ * @returns {Array<{name:string, kind:string, exported:boolean, implName:string|null, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти файлу (fn та impl-методи) або `null`, якщо юнітів не знайдено
  */
 export function extractUnitsRs(src, _relPath) {
   const lines = src.split('\n')
@@ -129,7 +144,7 @@ export function extractUnitsRs(src, _relPath) {
     }
 
     // Закриті impl-блоки прибираємо зі стека
-    while (implStack.length > 0 && implStack[implStack.length - 1].openDepth > depth) {
+    while (implStack.length > 0 && implStack.at(-1).openDepth > depth) {
       implStack.pop()
     }
 
@@ -140,22 +155,27 @@ export function extractUnitsRs(src, _relPath) {
       nextFnExposed = true
     }
 
+    const trimmed = line.trimStart()
+
     // Impl-декларація (зазвичай глибина 0, але може бути в mod)
     if (depthAtStart <= 1) {
-      const implM = line.match(IMPL_RE)
-      if (implM && line.includes('{')) {
-        implStack.push({ typeName: implM[1], openDepth: depth })
+      const headM = trimmed.match(IMPL_HEAD_RE)
+      if (headM && line.includes('{')) {
+        const rest = trimmed.slice(headM[0].length)
+        const typeM = rest.match(IMPL_FOR_TYPE_RE) ?? rest.match(TYPE_NAME_RE)
+        if (typeM) implStack.push({ typeName: typeM[1], openDepth: depth })
       }
     }
 
     // Елементи на глибині 0 (top-level) і 1 (всередині impl)
     if (depthAtStart <= 1) {
-      const m = line.match(ITEM_RE)
+      const pubM = trimmed.match(PUB_PREFIX_RE)
+      const m = (pubM ? trimmed.slice(pubM[0].length) : trimmed).match(ITEM_DECL_RE)
       if (m) {
-        const isPub = Boolean(m[1]) || (m[2] === 'fn' && nextFnExposed)
-        if (m[2] === 'fn') nextFnExposed = false
-        const kind = m[2]
-        const name = m[3]
+        const isPub = Boolean(pubM) || (m[1] === 'fn' && nextFnExposed)
+        if (m[1] === 'fn') nextFnExposed = false
+        const kind = m[1]
+        const name = m[2]
         const doc = docBefore(lines, li)
 
         // Витягуємо тіло через findClosingBrace для fn/struct/enum/trait

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

@@ -0,0 +1,37 @@
+---
+docgen:
+  source: npm/rules/doc-files/lint/lint.mjs
+  crc: a30dd81f
+  score: 100
+---
+
+# lint.mjs
+
+## Огляд
+
+CLI-команда `lint-doc-files` — детермінований детектор застарілості файлових док. Працює без
+мовної моделі скрізь: локально, в hook'ах і в CI.
+
+## Поведінка
+
+Без прапорців або з переліком шляхів робить повний чи точковий детект і повертає код `1`, якщо є
+застарілі/відсутні доки. `--missing-only` звужує до самих відсутніх. `--json` друкує машинний
+лістинг усіх кандидатів зі станом і завершується кодом `0`. Режими `--hook`, `--git` і
+`--degraded` делегуються детектору hook-протоколу (PostToolUse за одним файлом зі stdin, Stop-гейт
+за зміненими у задачі джерелами з порогом, інформаційний звіт про доки нижчої якості).
+
+Повний прогін серіалізується спільним локом під ключем, виведеним зі шляху каталогу, тож паралельні
+запуски не накладаються; hook-форми навмисно виконуються без локу заради завжди-свіжого вердикту.
+
+## Публічний API
+
+`runLintDocFilesCli` — точка входу команди: маршрутизує між делегатом hook-протоколу, JSON-лістингом
+і повним/точковим детектом; повертає код виходу.
+`runLintDocFilesSteps` — сама робота повного чи точкового детекту, придатна для прямого виклику з
+тестів без локу; повертає `1` за наявності застарілих док, інакше `0`.
+
+## Гарантії поведінки
+
+- Неіснуючий корінь дає зрозумілу помилку і код `1`.
+- Повний прогін — код `1` (конвенція `lint-*`); hook/git — код `2` (blocking feedback для Claude Code).
+- Жодних викликів мовної моделі.

package/rules/doc-files/lint/lint.mjs

@@ -0,0 +1,105 @@
+/**
+ * CLI-обгортка канонічного `lint-doc-files` (doc-files.mdc): детермінований детектор
+ * застарілості файлових док (`<dir>/docs/<stem>.md`) — 0 викликів LLM, працює будь-де.
+ *
+ * Режими (мапа команд у doc-files.mdc / спеці 2026-06-12):
+ *  - (без прапорців) / `[paths…]` — повний або точковий детект; **exit 1**, якщо є stale.
+ *  - `--missing-only`             — звужує до `missing` (без `crc-mismatch`); exit 1.
+ *  - `--json`                     — JSON-лістинг усіх кандидатів зі станом (= старий `scan`); exit 0.
+ *  - `--hook` / `--git` / `--degraded` — делегат у `runDocFilesCheckCli` (hook-протокол: exit 2/0).
+ *
+ * Серіалізація: повний прогін — через `runStandardLint` (ключ `lint-doc-files`,
+ * виводиться зі шляху каталогу). Hook/git/degraded форми — **без локу** (швидкі точкові
+ * перевірки в hook-протоколі потребують завжди-свіжого вердикту) — канон scripts.mdc.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { join, relative, resolve, sep, isAbsolute } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import {
+  describeFile,
+  isDocCandidate,
+  resolveRoot,
+  runDocFilesCheckCli,
+  runDocFilesScanCli,
+  scanForDocFiles
+} from '../js/docgen-scan.mjs'
+
+/**
+ * Нормалізує шлях-кандидат до posix-шляху від кореня (null поза деревом).
+ * @param {string} root абсолютний корінь
+ * @param {string} candidate шлях-кандидат
+ * @returns {string|null} posix-шлях від кореня або null
+ */
+function toRelSource(root, candidate) {
+  const rel = relative(root, resolve(root, candidate))
+  if (rel.startsWith('..') || isAbsolute(rel)) return null
+  return rel.split(sep).join('/')
+}
+
+/**
+ * Витягує позиційні шляхи з argv (не прапорці й не значення `--root`).
+ * @param {string[]} argv аргументи
+ * @returns {string[]} позиційні шляхи
+ */
+function positionalPaths(argv) {
+  const rootIdx = argv.indexOf('--root')
+  const skip = rootIdx !== -1 ? rootIdx + 1 : -1
+  return argv.filter((a, i) => !a.startsWith('--') && i !== skip)
+}
+
+/**
+ * Реальна робота повного / точкового детекту. Exit 1 — є stale, 0 — все свіже.
+ * @param {string[]} argv аргументи після назви команди
+ * @returns {number} exit-код
+ */
+export function runLintDocFilesSteps(argv) {
+  const root = resolveRoot(argv)
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`lint-doc-files: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+  const missingOnly = argv.includes('--missing-only')
+  const paths = positionalPaths(argv)
+
+  const described = paths.length
+    ? paths
+        .map(p => toRelSource(root, p))
+        .filter(rel => rel && isDocCandidate(root, rel) && existsSync(join(root, rel)))
+        .map(rel => describeFile(root, /** @type {string} */ (rel)))
+    : scanForDocFiles(root)
+
+  let stale = described.filter(f => f.stale)
+  if (missingOnly) stale = stale.filter(f => f.reason === 'missing')
+
+  if (stale.length === 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
+}
+
+/**
+ * Публічна CLI-форма `lint-doc-files`. Hook/git/degraded — делегат без локу; `--json` —
+ * scan; решта — повний/точковий детект під `runStandardLint` (ключ `lint-doc-files`).
+ * @param {string[]} [argv] аргументи після назви команди
+ * @returns {Promise<number>} exit-код
+ */
+export function runLintDocFilesCli(argv = process.argv.slice(3)) {
+  if (argv.includes('--hook') || argv.includes('--git') || argv.includes('--degraded')) {
+    return runDocFilesCheckCli(argv)
+  }
+  if (argv.includes('--json')) {
+    return Promise.resolve(runDocFilesScanCli(argv))
+  }
+  return runStandardLint(import.meta.dirname, () => runLintDocFilesSteps(argv))
+}
+
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = await runLintDocFilesCli(process.argv.slice(2))
+}

package/rules/doc-files/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "lint": "quick" }