@nitra/cursor 12.11.1 → 12.11.3

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`) замість генерування винятку чи паніки.
-- Не звертається до мережі.