@nitra/cursor 12.11.2 → 12.12.0

package/skills/doc-aggregate/SKILL.md

@@ -37,29 +37,19 @@ npx @nitra/cursor lint-doc-files --git
 
 ## Крок 1: Tier 2 — module-summary
 
-Зібрати список модулів:
+Зібрати список воркспейсів з кореневого `package.json`:
 
 ```bash
-npx @nitra/cursor doc-aggregate modules
+node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log(JSON.stringify(p.workspaces))"
 ```
 
-Команда друкує JSON-масив (усі шляхи абсолютні):
-
-```json
-[
-  {
-    "moduleRoot": "/abs/npm/rules/adr",
-    "relRoot": "npm/rules/adr",
-    "slug": "npm-rules-adr",
-    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
-    "members": ["npm/rules/adr/index.mjs"],
-    "exists": false
-  }
-]
-```
+Для кожного воркспейсу `<ws>`:
+- `relRoot` = `<ws>` (напр. `npm`, `demo`)
+- `docPath` = `<ws>/docs/ARCHITECTURE.md`
+- `members` — кодові файли (`.mjs .ts .vue .py`, крім тестів) у `<ws>/`
 
-module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі
-на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):
+module-summary **завжди регенерується**. Розбий воркспейси на батчі по 5 і диспатч субагентів.
+Промпт кожного (підстав `relRoot`, `docPath`, `members`):
 
 ```
 Напиши module-summary для одного логічного модуля.

package/skills/doc-aggregate/js/docs/index.md

@@ -9,4 +9,3 @@ resource: npm/skills/doc-aggregate/js/
 | Файл                                  | Тип       |
 | ------------------------------------- | --------- |
 | [docgen-ignore.mjs](docgen-ignore.md) | JS Module |
-| [docgen-scan.mjs](docgen-scan.md)     | JS Module |

package/scripts/lib/check-mdc-template-refs.mjs

@@ -1,57 +0,0 @@
-/**
- * Returns list of template/ files that are NOT referenced in <id>.mdc as
- * markdown link targets. Paths returned are relative to ruleDir.
- */
-import { existsSync } from 'node:fs'
-import { readdir, readFile, stat } from 'node:fs/promises'
-import { join, relative } from 'node:path'
-
-/**
- * @param {string} ruleDir абсолютний шлях до каталогу правила
- * @returns {Promise<string[]>} абсолютні шляхи всіх файлів у template/
- */
-async function walkTemplateDirs(ruleDir) {
-  const out = []
-  for (const kind of ['fix', 'policy']) {
-    const kindDir = join(ruleDir, kind)
-    if (!existsSync(kindDir)) continue
-    for (const concern of await readdir(kindDir)) {
-      const tpl = join(kindDir, concern, 'template')
-      if (!existsSync(tpl)) continue
-      const tplStat = await stat(tpl)
-      if (!tplStat.isDirectory()) continue
-      out.push(...(await collectFiles(tpl)))
-    }
-  }
-  return out.map(p => relative(ruleDir, p))
-}
-
-/**
- * @param {string} dir каталог для обходу
- * @returns {Promise<string[]>} абсолютні шляхи знайдених файлів
- */
-async function collectFiles(dir) {
-  const out = []
-  for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name)
-    if (entry.isDirectory()) out.push(...(await collectFiles(full)))
-    else out.push(full)
-  }
-  return out
-}
-
-/**
- * @param {string} ruleDir абсолютний шлях до npm/rules/<id>/
- * @param {string} ruleId basename правила (напр. "security")
- * @returns {Promise<string[]>} відносні шляхи template-файлів без посилань у .mdc
- */
-export async function findMissingMdcRefs(ruleDir) {
-  const mdcPath = join(ruleDir, 'main.mdc')
-  if (!existsSync(mdcPath)) return []
-  const mdc = await readFile(mdcPath, 'utf8')
-  const allFiles = await walkTemplateDirs(ruleDir)
-  return allFiles.filter(rel => {
-    // Match markdown link to ./<rel> or (<rel>) anywhere in the .mdc
-    return !mdc.includes(`./${rel}`) && !mdc.includes(`(${rel})`)
-  })
-}

package/scripts/lib/docs/check-mdc-template-refs.md

@@ -1,22 +0,0 @@
----
-type: JS Module
-title: check-mdc-template-refs.mjs
-resource: npm/scripts/lib/check-mdc-template-refs.mjs
-docgen:
-  crc: c116210e
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
----
-
-Визначає список файлів шаблонів, що знаходяться у каталогах `fix` та `policy`, які не є цільовими посиланнями у файлі `<id>.mdc` як markdown link targets. Це дозволяє ідентифікувати ресурси шаблонів, які не були згадані в контексті правила.
-
-## Поведінка
-
-1. Збирає абсолютні шляхи всіх файлів, що знаходяться у каталогах `template` всередині підкаталогів `fix` та `policy` у вказаному каталозі правила.
-2. Зчитує вміст файлу `main.mdc` у каталозі правила.
-3. Фільтрує зібрані шляхи, залишаючи лише ті, які не з'являються у вмісті `main.mdc` у вигляді посилання Markdown (`./<шлях>` або ``).
-4. Повертає відносні шляхи цих незгаданих шаблонних файлів відносно каталогу правила.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/skills/doc-aggregate/js/docgen-scan.mjs

@@ -1,195 +0,0 @@
-/** @see ./docs/docgen-scan.md */
-import { join, relative, dirname, extname, sep, isAbsolute, resolve } from 'node:path'
-import { existsSync, readdirSync, statSync } from 'node:fs'
-
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { isDocgenIgnored } from './docgen-ignore.mjs'
-
-/** Кодові розширення, для яких генеруємо документацію. */
-const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
-
-/** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
-const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
-
-/**
- * Чи корінь має system-wide docs layout (зарезервований під repo docs/adr тощо).
- * @param {string} root абсолютний корінь обходу
- * @returns {boolean} true — корінь system-wide docs
- */
-function isSystemWideDocsRoot(root) {
-  return existsSync(join(root, 'docs', 'adr')) || existsSync(join(root, 'docs', 'explanation'))
-}
-
-/**
- * Чи є файл кодовим джерелом для документування.
- * @param {string} fileName базове ім'я файлу
- * @returns {boolean} true — документуємо
- */
-export function isSourceFile(fileName) {
-  if (fileName.endsWith('.d.ts')) return false
-  if (TEST_FILE_RE.test(fileName)) return false
-  return SOURCE_EXTENSIONS.has(extname(fileName))
-}
-
-/**
- * Рекурсивно збирає кодові файли проєкту (posix-шляхи від кореня).
- * @param {string} root абсолютний корінь обходу
- * @returns {string[]} sourcePath-и
- */
-export function scanSourceFiles(root) {
-  const results = []
-
-  /** @param {string} dir поточний каталог обходу */
-  function walk(dir) {
-    let entries
-    try {
-      entries = readdirSync(dir, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name)
-      const relPath = relative(root, fullPath)
-      if (entry.isDirectory()) {
-        if (isDocgenIgnored(relPath, 'dir')) continue
-        walk(fullPath)
-      } else if (entry.isFile() && isSourceFile(entry.name)) {
-        if (isSystemWideDocsRoot(root) && dirname(relPath) === '.') continue
-        const sourcePath = relPath.split(sep).join('/')
-        if (isDocgenIgnored(sourcePath)) continue
-        results.push(sourcePath)
-      }
-    }
-  }
-
-  walk(root)
-  return results
-}
-
-/**
- * Стабільний slug модуля з його відносного шляху (для лейблів/логів).
- * @param {string} root абсолютний корінь обходу
- * @param {string} moduleRoot абсолютний корінь модуля
- * @returns {string} slug: `npm/rules/adr` → `npm-rules-adr`, корінь → `root`
- */
-export function slugForModule(root, moduleRoot) {
-  const rel = relative(root, moduleRoot)
-  if (rel === '') return 'root'
-  return rel
-    .split(sep)
-    .join('-')
-    .replaceAll(/[^\w-]+/gu, '-')
-}
-
-/**
- * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
- * @param {string} root абсолютний корінь обходу
- * @returns {string[]} абсолютні шляхи коренів модулів
- */
-export function findModuleRoots(root) {
-  const roots = [root]
-
-  /** @param {string} dir поточний каталог обходу */
-  function walk(dir) {
-    let entries
-    try {
-      entries = readdirSync(dir, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name)
-      const relPath = relative(root, fullPath)
-      if (entry.isDirectory()) {
-        if (isDocgenIgnored(relPath, 'dir')) continue
-        walk(fullPath)
-      } else if (entry.isFile() && entry.name === 'package.json' && dir !== root) {
-        roots.push(dir)
-      }
-    }
-  }
-
-  walk(root)
-  return roots
-}
-
-/**
- * Найближчий модуль-предок для файлу (найдовший збіг шляху).
- * @param {string} filePath абсолютний шлях до файлу
- * @param {string[]} moduleRoots абсолютні корені модулів
- * @returns {string|null} абсолютний корінь модуля або null
- */
-export function nearestModuleRoot(filePath, moduleRoots) {
-  let best = null
-  for (const moduleRoot of moduleRoots) {
-    const rel = relative(moduleRoot, filePath)
-    if (rel.startsWith('..') || isAbsolute(rel)) continue
-    if (best === null || moduleRoot.length > best.length) best = moduleRoot
-  }
-  return best
-}
-
-/**
- * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
- * Модулі без кодових файлів пропускаються.
- * @param {string} root абсолютний корінь обходу
- * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и від root)
- */
-export function scanForModules(root) {
-  const files = scanSourceFiles(root)
-  const moduleRoots = findModuleRoots(root)
-  const byRoot = new Map()
-  for (const sourcePath of files) {
-    const moduleRoot = nearestModuleRoot(join(root, sourcePath), moduleRoots)
-    if (moduleRoot === null) continue
-    if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
-    byRoot.get(moduleRoot).push(sourcePath)
-  }
-
-  const results = []
-  for (const moduleRoot of moduleRoots) {
-    const members = byRoot.get(moduleRoot)
-    if (!members || members.length === 0) continue
-    const docPath = join(moduleRoot, 'docs', 'ARCHITECTURE.md')
-    results.push({
-      moduleRoot,
-      relRoot: relative(root, moduleRoot) || '.',
-      slug: slugForModule(root, moduleRoot),
-      docPath,
-      members: members.toSorted(),
-      exists: existsSync(docPath)
-    })
-  }
-  return results
-}
-
-/**
- * Парсить `--root <dir>`; default — cwd.
- * @param {string[]} argv аргументи після підкоманди
- * @returns {string} абсолютний корінь
- */
-export function resolveRoot(argv) {
-  const i = argv.indexOf('--root')
-  return i !== -1 && argv[i + 1] ? resolve(argv[i + 1]) : process.cwd()
-}
-
-/**
- * `doc-aggregate modules` — сканує модулі і друкує JSON-масив у stdout.
- * @param {string[]} argv аргументи після назви субкоманди
- * @returns {number} exit-код: 0 — успіх, 1 — корінь не існує
- */
-export function runDocAggregateModulesCli(argv) {
-  const root = resolveRoot(argv)
-  if (!existsSync(root) || !statSync(root).isDirectory()) {
-    console.error(`doc-aggregate modules: корінь не існує або не є директорією: ${root}`)
-    return 1
-  }
-  console.log(JSON.stringify(scanForModules(root), null, 2))
-  return 0
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Прямий запуск: `node skills/doc-aggregate/js/docgen-scan.mjs modules --root <dir>`
-  const [sub, ...rest] = process.argv.slice(2)
-  process.exitCode = runDocAggregateModulesCli(sub === 'modules' ? rest : process.argv.slice(2))
-}

package/skills/doc-aggregate/js/docs/docgen-scan.md

@@ -1,76 +0,0 @@
----
-type: JS Module
-title: docgen-scan.mjs
-resource: npm/skills/doc-aggregate/js/docgen-scan.mjs
-docgen:
-  crc: 193dd362
-  score: 100
----
-
-isSourceFile
-Перевіряє, чи є файл коду, який слугує джерелом для документування.
-
-scanSourceFiles
-Рекурсивно збирає кодові файли проєкту за позикс-шляхами від кореня.
-
-slugForModule
-Генерує стабільний slug модуля на основі його відносного шляху.
-
-findModuleRoots
-Знаходить абсолютні шляхи коренів модулів, використовуючи дані з package.json.
-
-nearestModuleRoot
-Визначає найближчий модуль-предок для заданого файлу серед усіх доступних коренів модулів.
-
-scanForModules
-Лістить логічні модулі, збираючи члени-файли та інформацію про наявність документації.
-
-resolveRoot
-Парсить аргументи для визначення абсолютної кореневої директорії.
-
-runDocAggregateModulesCli
-Сканує модулі та виводить масив JSON у stdout.
-
-## Поведінка
-
-isSourceFile
-Перевіряє, чи є файл кодовим джерелом для документування
-
-scanSourceFiles
-Рекурсивно збирає кодові файли проєкту по позикс-шляхах від кореня
-
-slugForModule
-Генерує стабільний slug модуля з його відносним шляхом
-
-findModuleRoots
-Знаходить абсолютні шляхи коренів модулів з файлами package.json
-
-nearestModuleRoot
-Знаходить найближчий модуль-предок для файлу серед наявних коренів модулів
-
-scanForModules
-Лістить логічні модулі, збираючи члени-файли та інформацію про наявність документації
-
-resolveRoot
-Парсить аргументи для визначення абсолютного кореня
-
-runDocAggregateModulesCli
-Сканує модулі та виводить JSON-масив у stdout
-
-## Публічний API
-
-- isSourceFile — визначає, чи є файл коду для документування.
-- scanSourceFiles — рекурсивно збирає файли коду проєкту (від кореня за POSIX-шляхом).
-- slugForModule — генерує стабільний slug модуля з його відносним шляхом (для лейблів/логів).
-- findModuleRoots — знаходить кореневі директорії модулів у `package.json` (корінь — це модуль).
-- nearestModuleRoot — визначає найближчий модуль-предок для файлу (найдовший збіг шляху).
-- scanForModules — лістить логічні модулі проєкту з членами-файлами та `docPath module-summary`. Пропускає модулі без кодових файлів.
-- resolveRoot — парсить аргумент `--root <dir>`; за замовчуванням використовує поточну директорію.
-- runDocAggregateModulesCli — виконує команду `doc-aggregate modules`, скануючи модулі та виводячи JSON-масив у stdout.
-
-## Гарантії поведінки
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.