@nitra/cursor 11.4.0 → 12.0.0

package/scripts/utils/docs/ast-scan-utils.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: ast-scan-utils.mjs
+resource: npm/scripts/utils/ast-scan-utils.mjs
 docgen:
-  source: npm/scripts/utils/ast-scan-utils.mjs
   crc: 0f9b4a21
 ---
 
-# ast-scan-utils.mjs
-
-## Огляд
-
 Цей файл містить утиліти для AST-сканерів JavaScript та TypeScript, що використовуються для аналізу коду та виявлення потенційних проблем. Він надає інструменти для обробки AST, перетворення даних та взаємодії з різними типами вузлів, забезпечуючи основу для створення правил безпеки та аналізу коду. Ці утиліти спрощують розробку сканерів, усуваючи необхідність повторного написання boilerplate-коду.
 
 ## Поведінка

package/scripts/utils/docs/ensure-gitignore-entries.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: ensure-gitignore-entries.mjs
+resource: npm/scripts/utils/ensure-gitignore-entries.mjs
 docgen:
-  source: npm/scripts/utils/ensure-gitignore-entries.mjs
   crc: 35e65c1b
 ---
 
-# ensure-gitignore-entries.mjs
-
-## Огляд
-
 Цей модуль відповідає за оновлення файлу `.gitignore` у корені проєкту. Він забезпечує idempotent додавання нових правил ігнорування, перевіряючи їхню наявність перед доповненням. Це необхідно для підтримки консистентності правил ігнорування в проєкті та інтеграції з інструментами тестування, такими як Stryker.
 
 ## Поведінка

package/scripts/utils/docs/find-package-json-paths.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: find-package-json-paths.mjs
+resource: npm/scripts/utils/find-package-json-paths.mjs
 docgen:
-  source: npm/scripts/utils/find-package-json-paths.mjs
   crc: 06c208de
 ---
 
-# find-package-json-paths.mjs
-
-## Огляд
-
 Цей файл забезпечує спільну утиліту для збору всіх файлів `package.json` у дереві проєкту, ігноруючи вказані каталоги. Він сортує знайдені шляхи пакетів за відносним розташуванням, що полегшує їх подальше використання в скриптах перевірки. Це дозволяє уникнути дублювання коду з інших інструментів перевірки та спрощує процес збору інформації про залежності.
 
 ## Поведінка

package/scripts/utils/docs/index.md

@@ -0,0 +1,23 @@
+---
+type: Directory Index
+title: npm/scripts/utils
+resource: npm/scripts/utils/
+---
+
+# npm/scripts/utils
+
+| Файл | Тип |
+|---|---|
+| [ast-scan-utils.mjs](ast-scan-utils.md) | JS Module |
+| [ensure-gitignore-entries.mjs](ensure-gitignore-entries.md) | JS Module |
+| [find-package-json-paths.mjs](find-package-json-paths.md) | JS Module |
+| [lock-cache-dir.mjs](lock-cache-dir.md) | JS Module |
+| [pass.mjs](pass.md) | JS Module |
+| [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md) | JS Module |
+| [resolve-cmd.mjs](resolve-cmd.md) | JS Module |
+| [resolve-js-root.mjs](resolve-js-root.md) | JS Module |
+| [test-helpers.mjs](test-helpers.md) | JS Module |
+| [walk-cache.mjs](walk-cache.md) | JS Module |
+| [walkDir.mjs](walkDir.md) | JS Module |
+| [with-lock.mjs](with-lock.md) | JS Module |
+| [worktree-fingerprint.mjs](worktree-fingerprint.md) | JS Module |

package/scripts/utils/docs/lock-cache-dir.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: lock-cache-dir.mjs
+resource: npm/scripts/utils/lock-cache-dir.mjs
 docgen:
-  source: npm/scripts/utils/lock-cache-dir.mjs
   crc: 3b63d4b1
 ---
 
-# lock-cache-dir.mjs
-
-## Огляд
-
 Цей файл визначає структуру каталогу кешування блоків для git-worktree, забезпечуючи унікальний стан локу для кожного головного checkout та пов'язаних worktree. Він використовується для серіалізації запуску інструментів аналізу коду в різних worktree, запобігаючи конфліктам та забезпечуючи ефективну роботу. Створена структура кешування гарантує, що всі worktree мають доступ до одного і того ж стану локу, що необхідно для коректної серіалізації процесів аналізу.
 
 ## Поведінка

package/scripts/utils/docs/pass.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: pass.mjs
+resource: npm/scripts/utils/pass.mjs
 docgen:
-  source: npm/scripts/utils/pass.mjs
   crc: 0f69dfba
 ---
 
-# pass.mjs
-
-## Огляд
-
 Цей файл містить функцію для виведення повідомлень про успіх у консоль. Функція використовується в скриптах перевірки для інформування користувача про успішне завершення операцій. Вона забезпечує чіткий візуальний сигнал про успіх, що полегшує інтерпретацію результатів перевірки.
 
 ## Поведінка

package/scripts/utils/docs/resolve-cargo-manifest.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: resolve-cargo-manifest.mjs
+resource: npm/scripts/utils/resolve-cargo-manifest.mjs
 docgen:
-  source: npm/scripts/utils/resolve-cargo-manifest.mjs
   crc: af1efa42
 ---
 
-# resolve-cargo-manifest.mjs
-
-## Огляд
-
 Цей файл визначає шлях до файлу Cargo.toml проєкту, незалежно від того, чи це кореневий Cargo.toml або один з підкаталогів workspace-у, особливо з урахуванням Tauri-патерну. Він служить утилітою для coverage-провайдера та test-концерну cargo_mutants_config, повертаючи `null` у разі невдачі для обробки ситуації без виключень. Це забезпечує гнучкий спосіб доступу до конфігурації проєкту Cargo.
 
 ## Поведінка

package/scripts/utils/docs/resolve-cmd.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: resolve-cmd.mjs
+resource: npm/scripts/utils/resolve-cmd.mjs
 docgen:
-  source: npm/scripts/utils/resolve-cmd.mjs
   crc: 31c290fc
 ---
 
-# resolve-cmd.mjs
-
-## Огляд
-
 Цей файл надає функцію `resolveCmd` для отримання абсолютного шляху до виконуваного файлу, який відповідає заданій команді. Це дозволяє викликати зовнішні інструменти, використовуючи повний шлях до файлу, а не команду з змінної PATH. Це корисно для забезпечення чіткої та однозначної ідентифікації виконуваного файлу.
 
 ## Поведінка

package/scripts/utils/docs/resolve-js-root.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: resolve-js-root.mjs
+resource: npm/scripts/utils/resolve-js-root.mjs
 docgen:
-  source: npm/scripts/utils/resolve-js-root.mjs
   crc: 2c2b9f11
 ---
 
-# resolve-js-root.mjs
-
-## Огляд
-
 Цей файл визначає кореневий JavaScript-файл проєкту, необхідний для запуску інструментів аналізу коду. Він використовується як у великих проєктах з декількома workspace-ами, так і в окремих пакетах, забезпечуючи єдине місце для визначення кореневого розташування. Це спрощує інтеграцію з інструментами coverage та тестування.
 
 ## Поведінка

package/scripts/utils/docs/test-helpers.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: test-helpers.mjs
+resource: npm/scripts/utils/test-helpers.mjs
 docgen:
-  source: npm/scripts/utils/test-helpers.mjs
   crc: 0e4357fe
 ---
 
-# test-helpers.mjs
-
-## Огляд
-
 Цей файл надає допоміжні функції для тестування скриптів пакета `@nitra/cursor`. Він забезпечує створення тимчасових каталогів та запис JSON-файлів у абсолютний шлях, гарантуючи ізольованість тестів та запобігаючи мутації глобального контексту процесу. Ці функції використовуються для створення безпечного середовища для тестування, особливо при використанні git-операцій та інших файлових операцій.
 
 ## Поведінка

package/scripts/utils/docs/walk-cache.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: walk-cache.mjs
+resource: npm/scripts/utils/walk-cache.mjs
 docgen:
-  source: npm/scripts/utils/walk-cache.mjs
   crc: 82798fa2
 ---
 
-# walk-cache.mjs
-
-## Огляд
-
 Файл забезпечує спільний кеш результатів обходу файлової системи для всіх операцій перевірки. Він зберігає список файлів, що відповідають заданим шаблонам, щоб уникнути повторних обходів. Це підвищує ефективність процесу перевірки, особливо при великій кількості файлів та шаблонів.
 
 ## Поведінка

package/scripts/utils/docs/walkDir.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: walkDir.mjs
+resource: npm/scripts/utils/walkDir.mjs
 docgen:
-  source: npm/scripts/utils/walkDir.mjs
   crc: 5e5fec27
 ---
 
-# walkDir.mjs
-
-## Огляд
-
 Файл `n-cursor.js` забезпечує рекурсивний обхід каталогів для скриптів перевірки, дозволяючи виконувати callback-функцію для кожного звичайного файлу. Він обходить дерево каталогів від заданого кореня, ігноруючи певні директорії (наприклад, `.git`, `node_modules`) та шляхи, вказані в `ignorePaths`. Це дозволяє автоматизувати процес аналізу конфігураційних файлів та інших ресурсів у проєкті.
 
 ## Поведінка

package/scripts/utils/docs/with-lock.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: with-lock.mjs
+resource: npm/scripts/utils/with-lock.mjs
 docgen:
-  source: npm/scripts/utils/with-lock.mjs
   crc: 21848085
   score: 95
 ---
 
-# with-lock.mjs
-
-## Огляд
-
 Файл реалізує механізм захисту важких команд через атомарне блокування та унікалізацію результатів. Функції дозволяють перевіряти можливість повторного використання результату з кешу та виконувати команду через серіалізований механізм. Механізм використовує `mkdirSync-based lock` та `sha256-dedup` з TTL.
 
 ## Поведінка

package/scripts/utils/docs/worktree-fingerprint.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: worktree-fingerprint.mjs
+resource: npm/scripts/utils/worktree-fingerprint.mjs
 docgen:
-  source: npm/scripts/utils/worktree-fingerprint.mjs
   crc: df297382
 ---
 
-# worktree-fingerprint.mjs
-
-## Огляд
-
 Файл надає унікальний відбиток робочої директорії. Цей відбиток використовується для ідентифікації та порівняння робочих директорій, забезпечуючи їх унікальність у системі. Він слугує базовим інструментом для відстеження та управління версіями.
 
 ## Поведінка

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

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: docgen-ignore.mjs
+resource: npm/skills/doc-aggregate/js/docgen-ignore.mjs
 docgen:
-  source: npm/skills/doc-aggregate/js/docgen-ignore.mjs
   crc: 5faaffd0
 ---
 
-# docgen-ignore
-
-## Огляд
-
 Re-export спільного списку ignore-глобів зі скіла doc-files: обидва скіли документації (пофайлові доки й агрегати) мусять бачити однакове дерево кодових файлів, інакше агрегат посилатиметься на файли без док або навпаки.
 
 ## Поведінка

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

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: docgen-scan.mjs
+resource: npm/skills/doc-aggregate/js/docgen-scan.mjs
 docgen:
-  source: npm/skills/doc-aggregate/js/docgen-scan.mjs
   crc: 193dd362
   score: 100
 ---
 
-# docgen-scan.mjs
-
-## Огляд
-
 isSourceFile
 Перевіряє, чи є файл коду, який слугує джерелом для документування.
 

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

@@ -0,0 +1,12 @@
+---
+type: Directory Index
+title: npm/skills/doc-aggregate/js
+resource: npm/skills/doc-aggregate/js/
+---
+
+# npm/skills/doc-aggregate/js
+
+| Файл | Тип |
+|---|---|
+| [docgen-ignore.mjs](docgen-ignore.md) | JS Module |
+| [docgen-scan.mjs](docgen-scan.md) | JS Module |

package/skills/start-check/js/docs/check.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: check.mjs
+resource: npm/skills/start-check/js/check.mjs
 docgen:
-  source: npm/skills/start-check/js/check.mjs
   crc: 1f8fb2f0
   score: 95
 ---
 
-# check.mjs
-
-## Огляд
-
 Файл надає інструменти для класифікації типів процесу, сканування конфігурації воркспейсів, парсингу логів та запуску скриптів.
 
 ## Поведінка

package/skills/start-check/js/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/skills/start-check/js
+resource: npm/skills/start-check/js/
+---
+
+# npm/skills/start-check/js
+
+| Файл | Тип |
+|---|---|
+| [check.mjs](check.md) | JS Module |

package/skills/taze/js/docs/diff.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: diff.mjs
+resource: npm/skills/taze/js/diff.mjs
 docgen:
-  source: npm/skills/taze/js/diff.mjs
   crc: fe4d76ce
   score: 100
 ---
 
-# diff.mjs
-
-## Огляд
-
 parseVersion
 Парсить версію з specifier.
 

package/skills/taze/js/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/skills/taze/js
+resource: npm/skills/taze/js/
+---
+
+# npm/skills/taze/js
+
+| Файл | Тип |
+|---|---|
+| [diff.mjs](diff.md) | JS Module |

package/scripts/lib/worktree.mjs

@@ -1,126 +0,0 @@
-/**
- * Чиста логіка worktree-tool `n-cursor worktree` (без git/fs side-effects).
- *
- * Тут — детерміновані, тестовані без git функції:
- *  - `sanitizeBranch` — імʼя гілки → безпечне імʼя каталогу/файла (слеш та інші
- *    небезпечні для шляху символи → дефіс), щоб структура `.worktrees/` лишалась пласкою;
- *  - `worktreePaths` — шляхи checkout і файла-опису поруч;
- *  - `buildDescription` — текст інвентарного `.worktrees/<name>.md` за конвенцією worktree.mdc;
- *  - `findOrphanDescFiles` — `.md`-описи без зареєстрованого worktree (для `prune`).
- *
- * Оркестрація (виклики git, запис файлів, argv) — у `npm/scripts/worktree-cli.mjs`.
- */
-import { basename, join } from 'node:path'
-
-/** Символи, безпечні для імені каталогу/файла; решта → дефіс. */
-const UNSAFE_PATH_CHARS_RE = /[^a-zA-Z0-9._-]+/gu
-const MD_EXTENSION_RE = /\.md$/u
-
-/**
- * Перетворює імʼя git-гілки на безпечне імʼя каталогу/файла для `.worktrees/`.
- * @param {string} branch імʼя git-гілки (наприклад `feat/skill-meta`)
- * @returns {string} пласке імʼя (наприклад `feat-skill-meta`)
- */
-export function sanitizeBranch(branch) {
-  if (typeof branch !== 'string' || branch.trim() === '') {
-    throw new Error('worktree: імʼя гілки обовʼязкове')
-  }
-  const sanitized = branch
-    .trim()
-    .replace(UNSAFE_PATH_CHARS_RE, '-')
-    .replaceAll(/^-{1,80}|-{1,80}$/gu, '')
-  if (sanitized === '') {
-    throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
-  }
-  return sanitized
-}
-
-/**
- * Перша вільна назва гілки за конвенцією `base`, `base2`, `base3`, … —
- * суфікс просто число без розділювача (як `main-fix` → `main-fix2`).
- * Дає змогу `worktree add` спершу перевірити зайнятість і обрати назву,
- * що спрацює, замість падіння на `fatal: a branch named '…' already exists`.
- * @param {string} branch бажане імʼя гілки
- * @param {(candidate: string) => boolean} isTaken чи зайнята назва (гілка/worktree вже існують)
- * @param {number} [limit] стеля кількості спроб (захист від нескінченного циклу)
- * @returns {string} перша вільна назва (= `branch`, якщо вона вільна)
- */
-export function firstFreeBranch(branch, isTaken, limit = 1000) {
-  if (typeof branch !== 'string' || branch.trim() === '') {
-    throw new Error('worktree: імʼя гілки обовʼязкове')
-  }
-  const base = branch.trim()
-  if (!isTaken(base)) return base
-  for (let n = 2; n <= limit; n++) {
-    const candidate = `${base}${n}`
-    if (!isTaken(candidate)) return candidate
-  }
-  throw new Error(`worktree: не знайдено вільної назви для "${base}" за ${limit} спроб`)
-}
-
-/**
- * Детерміновані шляхи checkout і файла-опису для гілки.
- * @param {string} repoRoot абсолютний корінь репозиторію
- * @param {string} branch імʼя git-гілки
- * @returns {{ checkout: string, descFile: string }} абсолютні шляхи
- */
-export function worktreePaths(repoRoot, branch) {
-  const name = sanitizeBranch(branch)
-  const dir = join(repoRoot, '.worktrees')
-  return { checkout: join(dir, name), descFile: join(dir, `${name}.md`) }
-}
-
-/**
- * Текст інвентарного файла-опису worktree.
- * @param {{ branch: string, task: string, baseCommit: string, date: string }} params поля опису
- * @returns {string} markdown-вміст `.worktrees/<name>.md`
- */
-export function buildDescription({ branch, task, baseCommit, date }) {
-  return [
-    `# ${branch}`,
-    '',
-    `**Задача:** ${task}`,
-    `**Дата:** ${date}`,
-    `**База (коміт):** ${baseCommit}`,
-    '',
-    `Прибрати: \`npx @nitra/cursor worktree remove ${branch}\``,
-    ''
-  ].join('\n')
-}
-
-/** Поріг переліку файлів у нагадуванні: понад нього показуємо лише кількість. */
-const DIRTY_LIST_LIMIT = 10
-
-/**
- * Нагадування про незакомічені зміни основного дерева, які **не** потрапляють
- * у новий worktree (він створюється від HEAD, без брудного стану). До
- * `limit` файлів — перелік шляхів; більше — лише підсумкова кількість, щоб не
- * залити екран. Призначене для виводу одразу після `worktree add`.
- * @param {string} porcelain вивід `git status --porcelain` основного дерева
- * @param {number} [limit] поріг переліку (понад нього — лише кількість)
- * @returns {string | null} текст нагадування або `null`, якщо дерево чисте
- */
-export function buildDirtyNotice(porcelain, limit = DIRTY_LIST_LIMIT) {
-  // Порядок: XY + пробіл (3 символи) + шлях; для перейменування — `orig -> dest`.
-  const files = String(porcelain ?? '')
-    .split('\n')
-    .map(line => line.slice(3).trim())
-    .filter(Boolean)
-  if (files.length === 0) return null
-  const head = `⚠️  Основне дерево має ${files.length} незакомічених змін — вони НЕ потрапили в цей worktree (створено від HEAD).`
-  const tail = '   Закоміть потрібні файли, якщо worktree-скіл має їх бачити.'
-  if (files.length > limit) return `${head}\n${tail}`
-  const list = files.map(f => `   - ${f}`).join('\n')
-  return `${head}\n${list}\n${tail}`
-}
-
-/**
- * `.md`-описи без відповідного зареєстрованого worktree-checkout.
- * @param {string[]} descFiles абсолютні шляхи `.worktrees/*.md`
- * @param {string[]} registeredCheckouts абсолютні шляхи зареєстрованих worktree-checkout
- * @returns {string[]} осиротілі `.md` (підмножина `descFiles`)
- */
-export function findOrphanDescFiles(descFiles, registeredCheckouts) {
-  const checkoutBasenames = new Set(registeredCheckouts.map(c => basename(c)))
-  return descFiles.filter(md => !checkoutBasenames.has(basename(md).replace(MD_EXTENSION_RE, '')))
-}