@nitra/cursor 4.1.0 → 4.1.1

package/scripts/graph/lib/state.mjs

@@ -0,0 +1,110 @@
+/**
+ * Визначення стану вузла за наявністю файлів (O(1), без читання вмісту).
+ * Пріоритет: invalidated > resolved > pending-audit > stalled > running > waiting/blocked > failed > needs-plan
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @typedef {'needs-plan'|'waiting'|'blocked'|'running'|'stalled'|'pending-audit'|'resolved'|'failed'|'invalidated'} NodeState
+ */
+
+/**
+ * Визначає стан атомарного вузла за файлами у директорії.
+ * @param {string} dir абсолютний шлях до директорії вузла
+ * @param {{ depsResolved: boolean }} opts
+ * @returns {NodeState}
+ */
+export function deriveAtomicState(dir, { depsResolved = true } = {}) {
+  if (existsSync(join(dir, 'invalidated'))) return 'invalidated'
+
+  const files = listFiles(dir)
+
+  if (hasFact(files) && !files.includes('invalidated')) return 'resolved'
+
+  const pendingNNN = findPendingAudit(files)
+  if (pendingNNN !== null) return 'pending-audit'
+
+  const runningUntil = findRunningUntil(files)
+  if (runningUntil !== null) {
+    const ts = Number(runningUntil)
+    const now = Math.floor(Date.now() / 1000)
+    return ts > now ? 'running' : 'stalled'
+  }
+
+  const hasPlan = files.some(f => /^plan_\d{3}\.md$/u.test(f))
+  const hasRun = files.some(f => /^run_\d{3}\.md$/u.test(f))
+
+  if (!hasPlan) return 'needs-plan'
+  if (hasRun && !hasFact(files)) return 'failed'
+  if (hasPlan && !depsResolved) return 'blocked'
+  return 'waiting'
+}
+
+/**
+ * Визначає стан composite вузла за станами дітей.
+ * @param {string} dir
+ * @param {NodeState[]} childStates
+ * @returns {NodeState}
+ */
+export function deriveCompositeState(dir, childStates) {
+  if (existsSync(join(dir, 'invalidated'))) return 'invalidated'
+
+  if (childStates.length === 0) return 'needs-plan'
+  if (childStates.every(s => s === 'resolved')) return 'resolved'
+  if (childStates.some(s => s === 'running' || s === 'pending-audit')) return 'running'
+  if (childStates.some(s => s === 'stalled')) return 'stalled'
+  if (childStates.some(s => s === 'failed') && !childStates.some(s => s === 'running')) return 'failed'
+  return 'waiting'
+}
+
+/**
+ * Перевіряє наявність orphan worktree для вузла (resolved + worktree exists).
+ * @param {string} dir
+ * @param {string} worktreesDir
+ * @returns {boolean}
+ */
+export function hasOrphanWorktree(dir, worktreesDir) {
+  const nodeName = dir.split('/').at(-1)
+  try {
+    return readdirSync(worktreesDir).some(d => d.startsWith(nodeName))
+  } catch {
+    return false
+  }
+}
+
+// --- helpers ---
+
+/** @param {string} dir @returns {string[]} */
+function listFiles(dir) {
+  try { return readdirSync(dir) } catch { return [] }
+}
+
+/** @param {string[]} files @returns {boolean} */
+function hasFact(files) {
+  return files.some(f => /^fact_\d{3}\.md$/u.test(f))
+}
+
+/**
+ * Знаходить перший pending-audit_NNN без audit-result_NNN.
+ * @param {string[]} files
+ * @returns {string | null} NNN або null
+ */
+function findPendingAudit(files) {
+  const pending = files.filter(f => /^pending-audit_\d{3}\.md$/u.test(f)).sort()
+  for (const p of pending) {
+    const nnn = p.replace('pending-audit_', '').replace('.md', '')
+    if (!files.includes(`audit-result_${nnn}.md`)) return nnn
+  }
+  return null
+}
+
+/**
+ * Знаходить `running_until_<ts>` файл і повертає ts як рядок.
+ * @param {string[]} files
+ * @returns {string | null}
+ */
+function findRunningUntil(files) {
+  const f = files.find(f => /^running_until_\d+$/u.test(f))
+  return f ? f.replace('running_until_', '') : null
+}

package/scripts/graph/scan.mjs

@@ -0,0 +1,64 @@
+/**
+ * `graph scan` — повне сканування граф: відновлює стан з файлів, виводить результат.
+ * exit 0 — граф чистий; exit 1 — є вузли у стані failed.
+ */
+import { resolve } from 'node:path'
+import { cwd } from 'node:process'
+
+import { loadConfig } from './lib/config.mjs'
+import { buildDag } from './lib/dag.mjs'
+
+/**
+ * @param {string[]} args
+ * @param {{ json?: boolean }} opts
+ */
+export async function runScan(args, opts = {}) {
+  const root = cwd()
+  const config = loadConfig(root)
+  const tasksDir = resolve(root, config.tasks_dir)
+  const worktreesDir = resolve(root, config.worktrees_dir)
+
+  const nodes = buildDag(tasksDir, worktreesDir)
+
+  if (opts.json) {
+    const out = {}
+    for (const [id, node] of nodes) out[id] = { state: node.state, deps: node.deps }
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n')
+  } else {
+    printScanTable(nodes)
+  }
+
+  const hasFailed = [...nodes.values()].some(n => n.state === 'failed')
+  return hasFailed ? 1 : 0
+}
+
+/** @param {Map<string, import('./lib/dag.mjs').GraphNode>} nodes */
+function printScanTable(nodes) {
+  const STATE_ICON = {
+    'needs-plan': '⏳',
+    waiting: '○',
+    blocked: '○',
+    running: '◉',
+    stalled: '⚠',
+    'pending-audit': '🔍',
+    resolved: '✓',
+    failed: '✗',
+    invalidated: '⊘',
+  }
+
+  const counts = {}
+  for (const { state } of nodes.values()) counts[state] = (counts[state] ?? 0) + 1
+
+  const summary = Object.entries(counts).map(([s, n]) => `${s}:${n}`).join(' ')
+  console.log(`graph — ${summary}\n`)
+
+  for (const [id, node] of nodes) {
+    const icon = STATE_ICON[node.state] ?? '?'
+    let detail = ''
+    if (node.state === 'needs-plan') detail = `run: graph plan tasks/${id}/`
+    else if (node.state === 'blocked') detail = `blocked: ${node.deps.join(', ')}`
+    else if (node.state === 'stalled') detail = 'stalled — deadline passed'
+    const suffix = detail ? ` [${detail}]` : ''
+    console.log(`  ${icon} ${id.padEnd(30)} [${node.state}]${suffix}`)
+  }
+}

package/scripts/graph/status.mjs

@@ -0,0 +1,86 @@
+/**
+ * `graph status [path]` — стан одного вузла або всього графу.
+ */
+import { resolve } from 'node:path'
+import { cwd } from 'node:process'
+
+import { loadConfig } from './lib/config.mjs'
+import { buildDag } from './lib/dag.mjs'
+
+/**
+ * @param {string | undefined} path відносний шлях до вузла або undefined для всього графу
+ * @param {{ json?: boolean }} opts
+ */
+export async function runStatus(path, opts = {}) {
+  const root = cwd()
+  const config = loadConfig(root)
+  const tasksDir = resolve(root, config.tasks_dir)
+  const worktreesDir = resolve(root, config.worktrees_dir)
+
+  const nodes = buildDag(tasksDir, worktreesDir)
+
+  if (path) {
+    // Normalize: tasks/foo → foo, tasks/foo/ → foo
+    const id = path.replace(/^tasks\//u, '').replace(/\/$/u, '')
+    const node = nodes.get(id)
+    if (!node) {
+      console.error(`Node not found: ${id}`)
+      return 1
+    }
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ id, ...node }, null, 2) + '\n')
+    } else {
+      printNode(id, node, nodes)
+    }
+    return 0
+  }
+
+  // Full graph
+  if (opts.json) {
+    const out = {}
+    for (const [id, node] of nodes) {
+      out[id] = { state: node.state, deps: node.deps, mode: node.mode, executor: node.executor }
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n')
+  } else {
+    // Print as tree
+    const roots = [...nodes.values()].filter(n => !n.parentId)
+    const counts = {}
+    for (const { state } of nodes.values()) counts[state] = (counts[state] ?? 0) + 1
+    const summary = Object.entries(counts).map(([s, n]) => `${s}:${n}`).join(' ')
+    console.log(`graph — ${summary}\n`)
+    for (const root of roots) printTree(root.id, nodes, 0)
+  }
+  return 0
+}
+
+const ICON = {
+  'needs-plan': '⏳', waiting: '○', blocked: '○', running: '◉',
+  stalled: '⚠', 'pending-audit': '🔍', resolved: '✓', failed: '✗', invalidated: '⊘',
+}
+
+/** @param {string} id @param {Map<string, import('./lib/dag.mjs').GraphNode>} nodes @param {number} depth */
+function printTree(id, nodes, depth) {
+  const node = nodes.get(id)
+  if (!node) return
+  const icon = ICON[node.state] ?? '?'
+  const indent = '  '.repeat(depth)
+  let detail = ''
+  if (node.state === 'needs-plan') detail = ` run: graph plan tasks/${id}/`
+  else if (node.state === 'blocked') detail = ` blocked: ${node.deps.join(', ')}`
+  console.log(`${indent}${icon} ${id}  [${node.state}]${detail}`)
+  for (const child of node.children) printTree(child, nodes, depth + 1)
+}
+
+/**
+ * @param {string} id
+ * @param {import('./lib/dag.mjs').GraphNode} node
+ * @param {Map<string, import('./lib/dag.mjs').GraphNode>} nodes
+ */
+function printNode(id, node, nodes) {
+  const icon = ICON[node.state] ?? '?'
+  console.log(`${icon} ${id}  [${node.state}]`)
+  if (node.deps.length) console.log(`  deps: ${node.deps.join(', ')}`)
+  if (node.children.length) console.log(`  children: ${node.children.join(', ')}`)
+  console.log(`  mode: ${node.mode}  executor: ${node.executor.type}/${node.executor.model_tier}`)
+}

package/scripts/lib/docs/load-cursor-config.md

@@ -101,6 +101,9 @@ const ignored = await loadCursorIgnorePaths(root)
 // ignored: ['/abs/path/.worktrees', '/abs/path/node_modules', ...]
 
 // Далі при обході файлів пропускаємо ті, що під будь-яким із ignored:
+/**
+ *
+ */
 function isIgnored(absPosixPath) {
   return ignored.some(ig => absPosixPath === ig || absPosixPath.startsWith(ig + '/'))
 }

package/scripts/lib/root-notice.mjs

@@ -40,6 +40,8 @@ git rev-parse --show-toplevel
 /** Канонічний блок root-інструкції (з маркерами). */
 const BLOCK = `${ROOT_START}\n${NOTICE_BODY}\n${ROOT_END}`
 
+const LEADING_NEWLINES_RE = /^\n+/u
+
 /**
  * Вставляє / оновлює / видаляє root-guard блок у вмісті `SKILL.md`.
  * @param {string} content вміст `SKILL.md`
@@ -57,8 +59,8 @@ export function injectRootNotice(content, enabled) {
   const fm = withoutBlock.match(FRONTMATTER_RE)
   if (fm) {
     const head = fm[1]
-    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
+    const rest = withoutBlock.slice(head.length).replace(LEADING_NEWLINES_RE, '')
     return `${head}\n${BLOCK}\n\n${rest}`
   }
-  return `${BLOCK}\n\n${withoutBlock.replace(/^\n+/u, '')}`
+  return `${BLOCK}\n\n${withoutBlock.replace(LEADING_NEWLINES_RE, '')}`
 }

package/scripts/lib/rule-predicates.mjs

@@ -133,7 +133,7 @@ export const RULE_PREDICATES = {
    * @param {{ hasBunSqlImport: boolean }} facts факти
    * @returns {Promise<boolean>} true, якщо deps pg/pg-format/mysql2 або import sql з bun
    */
-  async jsBunDbSignal(cwd, facts) {
+  jsBunDbSignal(cwd, facts) {
     if (facts.hasBunSqlImport === true) return true
     return anyDepInTree(cwd, ['pg', 'pg-format', 'mysql2'])
   },

package/scripts/lib/worktree-notice.mjs

@@ -36,6 +36,13 @@ const NAME_RE = /^name:\s*["']?([^"'\n]+)["']?\s*$/mu
 /** Перший H1 як fallback, якщо frontmatter не містить `name`. */
 const H1_RE = /^#\s+(.+)$/mu
 
+const N_PREFIX_RE = /^n-/u
+const COMBINING_DIACRITICS_RE = /[̀-ͯ]/gu
+const NON_ALPHANUM_RE = /[^a-z0-9]+/gu
+const TRAILING_DASHES_RE = /^-+|-+$/gu
+const TRAILING_DASH_RE = /-+$/u
+const LEADING_NEWLINES_RE = /^\n+/u
+
 const CYRILLIC_TRANSLIT = new Map(
   Object.entries({
     а: 'a',
@@ -96,13 +103,13 @@ function deriveSuffix(content) {
   const raw = content.match(NAME_RE)?.[1] ?? content.match(H1_RE)?.[1] ?? FALLBACK_SUFFIX
   const slug = transliterate(raw)
     .trim()
-    .replace(/^n-/u, '')
+    .replace(N_PREFIX_RE, '')
     .normalize('NFKD')
-    .replaceAll(/[\u0300-\u036F]/gu, '')
-    .replaceAll(/[^a-z0-9]+/gu, '-')
-    .replaceAll(/^-+|-+$/gu, '')
+    .replaceAll(COMBINING_DIACRITICS_RE, '')
+    .replaceAll(NON_ALPHANUM_RE, '-')
+    .replaceAll(TRAILING_DASHES_RE, '')
 
-  return (slug || FALLBACK_SUFFIX).slice(0, 10).replace(/-+$/u, '') || FALLBACK_SUFFIX
+  return (slug || FALLBACK_SUFFIX).slice(0, 10).replace(TRAILING_DASH_RE, '') || FALLBACK_SUFFIX
 }
 
 /**
@@ -202,8 +209,8 @@ export function injectWorktreeNotice(content, enabled) {
   const fm = withoutBlock.match(FRONTMATTER_RE)
   if (fm) {
     const head = fm[1]
-    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
+    const rest = withoutBlock.slice(head.length).replace(LEADING_NEWLINES_RE, '')
     return `${head}\n${block}\n\n${rest}`
   }
-  return `${block}\n\n${withoutBlock.replace(/^\n+/u, '')}`
+  return `${block}\n\n${withoutBlock.replace(LEADING_NEWLINES_RE, '')}`
 }

package/scripts/lib/worktree.mjs

@@ -14,6 +14,7 @@ import { basename, join } from 'node:path'
 
 /** Символи, безпечні для імені каталогу/файла; решта → дефіс. */
 const UNSAFE_PATH_CHARS_RE = /[^a-zA-Z0-9._-]+/gu
+const MD_EXTENSION_RE = /\.md$/u
 
 /**
  * Перетворює імʼя git-гілки на безпечне імʼя каталогу/файла для `.worktrees/`.
@@ -82,7 +83,7 @@ export function buildDescription({ branch, task, baseCommit, date }) {
     `**Дата:** ${date}`,
     `**База (коміт):** ${baseCommit}`,
     '',
-    'Прибрати: ' + '`' + `npx @nitra/cursor worktree remove ${branch}` + '`',
+    `Прибрати: \`npx @nitra/cursor worktree remove ${branch}\``,
     ''
   ].join('\n')
 }
@@ -121,5 +122,5 @@ export function buildDirtyNotice(porcelain, limit = DIRTY_LIST_LIMIT) {
  */
 export function findOrphanDescFiles(descFiles, registeredCheckouts) {
   const checkoutBasenames = new Set(registeredCheckouts.map(c => basename(c)))
-  return descFiles.filter(md => !checkoutBasenames.has(basename(md).replace(/\.md$/u, '')))
+  return descFiles.filter(md => !checkoutBasenames.has(basename(md).replace(MD_EXTENSION_RE, '')))
 }

package/scripts/utils/resolve-js-root.mjs

@@ -8,6 +8,7 @@ import { glob, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 const WORKSPACE_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**']
+const PACKAGE_JSON_SUFFIX_RE = /[/\\]package\.json$/
 
 /**
  * Розгортає один workspace-патерн у список абсолютних шляхів каталогів з package.json.
@@ -23,7 +24,7 @@ async function expandWorkspacePattern(cwd, pattern) {
   }
   const results = []
   for await (const rel of glob(`${pattern}/package.json`, { cwd, exclude: WORKSPACE_GLOB_IGNORE })) {
-    const wsRel = rel.replace(/[/\\]package\.json$/, '')
+    const wsRel = rel.replace(PACKAGE_JSON_SUFFIX_RE, '')
     results.push(join(cwd, wsRel))
   }
   return results.sort()

package/scripts/utils/with-lock.mjs

@@ -128,7 +128,7 @@ export async function withLock(key, runFn, opts = {}) {
 
   const onSignal = () => {
     release()
-    // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- SIGINT/SIGTERM мають завершити процес із кодом 130
+    // eslint-disable-next-line n/no-process-exit -- SIGINT/SIGTERM мають завершити процес із кодом 130
     process.exit(130)
   }
   process.once('SIGINT', onSignal)

package/skills/docgen/js/docgen-batch.mjs

@@ -20,8 +20,8 @@ const missing = allFiles.filter(x => !x.exists)
 console.log(`\n📋 Файлів для генерації: ${missing.length}`)
 
 // 2. Розкласти по тирах
-const local = [],
-  cloud = []
+const cloud = [],
+  local = []
 for (const f of missing) {
   try {
     const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
@@ -51,10 +51,10 @@ for (const f of cloud) {
     stats.ok++
     stats.cloudOk++
     console.log(`  ✓ ${f.sourcePath} (sym=${f.sym}, ${Math.round((Date.now() - t0) / 1000)}s)`)
-  } catch (e) {
+  } catch (error) {
     stats.err++
     stats.errors.push(f.sourcePath)
-    console.error(`  ✗ ${f.sourcePath}: ${e.message}`)
+    console.error(`  ✗ ${f.sourcePath}: ${error.message}`)
   }
 }
 
@@ -77,10 +77,10 @@ for (const f of local) {
     stats.ok++
     stats.localOk++
     process.stdout.write(`✓ ${Math.round((Date.now() - t0) / 1000)}s score=${result.score ?? '?'}\n`)
-  } catch (e) {
+  } catch (error) {
     stats.err++
     stats.errors.push(f.sourcePath)
-    process.stdout.write(`✗ ${e.message}\n`)
+    process.stdout.write(`✗ ${error.message}\n`)
   }
 }
 
@@ -91,5 +91,5 @@ console.log(`  💻 Local (gemma3:4b): ${stats.localOk} файлів`)
 console.log(`  ☁️  Cloud (Claude/pi): ${stats.cloudOk} файлів`)
 if (stats.errors.length > 0) {
   console.log('Помилки:')
-  stats.errors.forEach(e => console.log(`  - ${e}`))
+  for (const e of stats.errors) console.log(`  - ${e}`)
 }

package/skills/docgen/js/docgen-extract.mjs

@@ -1,5 +1,8 @@
 /** @see ./docs/docgen-extract.md */
 
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { readFileSync } from 'node:fs'
+
 const BUILTIN_MODULES = new Set([
   'fs',
   'path',
@@ -19,18 +22,45 @@ const BUILTIN_MODULES = new Set([
   'readline'
 ])
 
-/** Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками. */
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+const JSDOC_CLOSE_RE = /\*\/\s*$/
+const STAR_PREFIX_RE = /^\s*\*?\s?/
+const PARAM_LINE_RE = /^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/
+const RETURNS_LINE_RE = /^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/
+const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
+const PRECEDING_JSDOC_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
+const IMPORT_FROM_RE = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
+const NODE_PREFIX_RE = /^node:/
+const INTERNAL_IMPORT_RE = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
+const IMPORT_AS_RE = /\s+as\s+.*/
+const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
+const CATCH_RE = /catch\s*\(/
+const TRY_RE = /\btry\s*\{/
+const FALSY_RETURN_RE = /return\s+(false|null|''|"")/
+const NETWORK_RE = /\bfetch\(|https?\.|axios|got\(/
+const CACHE_RE = /new Map\(\)|Cache|cache/
+
+/**
+ * Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками.
+ * @param {string} raw сирий JSDoc-блок з обрамленням
+ * @returns {string} очищений текст без обрамлення й префіксів
+ */
 function cleanJsDoc(raw) {
   return raw
-    .replace(/^\s*\/\*\*?/, '')
-    .replace(/\*\/\s*$/, '')
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
     .split('\n')
-    .map(l => l.replace(/^\s*\*?\s?/, '').trimEnd())
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
     .join('\n')
     .trim()
 }
 
-/** Опис (без @-тегів) + параметри з @param як «name — опис». */
+/**
+ * Опис (без @-тегів) + параметри з @param як «name — опис».
+ * @param {string} raw сирий JSDoc-блок
+ * @returns {{desc:string, params:Array<{name:string, desc:string}>, ret:string}} розпарсений опис, параметри й опис повернення
+ */
 function parseJsDoc(raw) {
   const text = cleanJsDoc(raw)
   const lines = text.split('\n')
@@ -38,8 +68,8 @@ function parseJsDoc(raw) {
   const params = []
   let ret = ''
   for (const l of lines) {
-    const pm = l.match(/^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/)
-    const rm = l.match(/^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/)
+    const pm = l.match(PARAM_LINE_RE)
+    const rm = l.match(RETURNS_LINE_RE)
     if (pm) {
       const desc = pm[2].trim()
       // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
@@ -56,9 +86,13 @@ function parseJsDoc(raw) {
   return { desc: descLines.join('\n').trim(), params, ret }
 }
 
-/** Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом. */
+/**
+ * Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом.
+ * @param {string} src вміст файлу
+ * @returns {string} текст header-коментаря або порожній рядок
+ */
 function extractFileHeader(src) {
-  const m = src.match(/^\s*\/\*\*([\s\S]*?)\*\//)
+  const m = src.match(FILE_HEADER_RE)
   if (!m) return ''
   // має бути на самому початку (до import/код)
   if (src.slice(0, m.index).trim() !== '') return ''
@@ -69,18 +103,22 @@ function extractFileHeader(src) {
  * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
  * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
  * найближчий блок — без жадібного «перестрибування» через імпорти/код.
+ * @param {string} prefix вміст файлу до позиції експорту
+ * @returns {string|null} JSDoc-блок або null якщо немає
  */
 function precedingJsDoc(prefix) {
-  const m = prefix.match(/\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/)
+  const m = prefix.match(PRECEDING_JSDOC_RE)
   return m ? m[0] : null
 }
 
-/** Експорти + JSDoc, що безпосередньо передує кожному. */
+/**
+ * Експорти + JSDoc, що безпосередньо передує кожному.
+ * @param {string} src вміст файлу
+ * @returns {Array<object>} список експортів із метаданими
+ */
 function extractExports(src) {
   const out = []
-  const re = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
-  let m
-  while ((m = re.exec(src))) {
+  for (const m of src.matchAll(EXPORT_DECL_RE)) {
     const [, kind, name] = m
     const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
     out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
@@ -88,39 +126,47 @@ function extractExports(src) {
   return out
 }
 
-/** Імпорти, класифіковані на stdlib / npm / internal. */
+/**
+ * Імпорти, класифіковані на stdlib / npm / internal.
+ * @param {string} src вміст файлу
+ * @returns {{stdlib:Array<string>, npm:Array<string>, internal:Array<string>}} розкласифіковані шляхи імпортів
+ */
 function extractImports(src) {
-  const stdlib = new Set(),
+  const internal = new Set(),
     npm = new Set(),
-    internal = new Set()
-  const re = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
-  let m
-  while ((m = re.exec(src))) {
+    stdlib = new Set()
+  for (const m of src.matchAll(IMPORT_FROM_RE)) {
     const s = m[1]
-    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/')[0])) stdlib.add(s.replace(/^node:/, ''))
+    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/')[0])) stdlib.add(s.replace(NODE_PREFIX_RE, ''))
     else if (s.startsWith('.') || s.startsWith('/')) internal.add(s)
     else npm.add(s)
   }
   return { stdlib: [...stdlib], npm: [...npm], internal: [...internal] }
 }
 
-/** Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати. */
+/**
+ * Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати.
+ * @param {string} src вміст файлу
+ * @returns {Array<string>} список імен внутрішніх символів
+ */
 function extractInternalSymbols(src) {
   const out = new Set()
-  const re = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
-  let m
-  while ((m = re.exec(src))) {
+  for (const m of src.matchAll(INTERNAL_IMPORT_RE)) {
     if (m[1]) out.add(m[1].trim())
     if (m[2])
       for (const n of m[2].split(',')) {
-        const name = n.replace(/\s+as\s+.*/, '').trim()
+        const name = n.replace(IMPORT_AS_RE, '').trim()
         if (name) out.add(name)
       }
   }
   return [...out]
 }
 
-/** Поведінкові маркери — евристики регулярками. */
+/**
+ * Поведінкові маркери — евристики регулярками.
+ * @param {string} src вміст файлу
+ * @returns {object} набір прапорців-евристик
+ */
 function extractMarkers(src) {
   // помітні «пропуски»: dir/segment-літерали у фільтрах
   const skips = new Set()
@@ -128,11 +174,11 @@ function extractMarkers(src) {
     if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
   }
   return {
-    readOnly: !/\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/.test(src),
-    catchesErrors: /catch\s*\(/.test(src) || /\btry\s*\{/.test(src),
-    returnsFalsyOnFail: /return\s+(false|null|''|"")/.test(src),
-    network: /\bfetch\(|https?\.|axios|got\(/.test(src),
-    caches: /new Map\(\)|Cache|cache/.test(src),
+    readOnly: !WRITE_FS_RE.test(src),
+    catchesErrors: CATCH_RE.test(src) || TRY_RE.test(src),
+    returnsFalsyOnFail: FALSY_RETURN_RE.test(src),
+    network: NETWORK_RE.test(src),
+    caches: CACHE_RE.test(src),
     skips: [...skips]
   }
 }
@@ -141,7 +187,7 @@ function extractMarkers(src) {
  * Головний екстрактор: код файлу → факт-лист.
  * @param {string} src вміст файлу
  * @param {string} relPath шлях (для контексту/мови екстрактора)
- * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}}
+ * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}} структура фактів про файл
  */
 export function extractFacts(src, relPath) {
   const lang = relPath.split('.').pop()
@@ -160,13 +206,10 @@ export function extractFacts(src, relPath) {
 }
 
 // CLI для інспекції: node docgen-extract.mjs <file>
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { readFileSync } from 'node:fs'
 if (isRunAsCli(import.meta.url)) {
   const file = process.argv[2]
   if (!file) {
-    console.error('Usage: node docgen-extract.mjs <file>')
-    process.exit(1)
+    throw new Error('Usage: node docgen-extract.mjs <file>')
   }
   const facts = extractFacts(readFileSync(file, 'utf8'), file)
   console.log(JSON.stringify(facts, null, 2))

package/skills/docgen/js/docgen-ignore.mjs

@@ -36,7 +36,7 @@ function toPosixRelPath(relPath) {
  * Для `kind = 'dir'` це працює і на піддерево каталогу, тож glob на кшталт
  * `**\\/demo/**` спрацьовує на `demo/x` під час рекурсивного обходу.
  * @param {string} relPath відносний шлях від кореня проєкту
- * @param {'path'|'dir'} [kind='path'] тип перевірки
+ * @param {'path'|'dir'} [kind] тип перевірки (за замовчуванням `'path'`)
  * @returns {boolean} `true`, якщо шлях ігнорується
  */
 export function isDocgenIgnored(relPath, kind = 'path') {