@nitra/cursor 1.8.179 → 1.8.184

package/scripts/sync-claude-config.mjs

@@ -28,27 +28,27 @@ const TEMPLATE_DIR_NAME = '.claude-template'
 
 /**
  * @typedef {object} HookEntry
- * @property {string} type
- * @property {string} command
- * @property {number} [timeout]
+ * @property {string} type тип hook'а у форматі Claude Code (зазвичай `'command'`)
+ * @property {string} command команда, яку виконує Claude Code (наш маркер живе саме тут)
+ * @property {number} [timeout] опційний таймаут у секундах
  */
 
 /**
  * @typedef {object} HookGroup
- * @property {string} [matcher]
- * @property {HookEntry[]} hooks
+ * @property {string} [matcher] патерн (наприклад, `'.*'`) для звуження hook'а
+ * @property {HookEntry[]} hooks впорядкований список команд hook-групи
  */
 
 /**
  * @typedef {object} ClaudeSettings
- * @property {{ allow?: string[] }} [permissions]
- * @property {Record<string, HookGroup[]>} [hooks]
+ * @property {{ allow?: string[] }} [permissions] секція `permissions` із .claude/settings.json
+ * @property {Record<string, HookGroup[]>} [hooks] hooks за подіями (`Stop`, `PreToolUse`, ...)
  */
 
 /**
  * Чи hook-група містить лише наші managed-команди (за маркером).
- * @param {HookGroup} group
- * @returns {boolean}
+ * @param {HookGroup} group hook-група з .claude/settings.json
+ * @returns {boolean} `true`, якщо всі hooks мають маркер `MANAGED_HOOK_COMMAND_MARKER`
  */
 function isManagedHookGroup(group) {
   if (!group?.hooks?.length) {
@@ -60,9 +60,9 @@ function isManagedHookGroup(group) {
 /**
  * Зливає список allow-permissions: union існуючого і темплейтного без дублікатів,
  * порядок — спочатку існуючі (щоб не міняти користувацький порядок), потім нові.
- * @param {string[] | undefined} existing
- * @param {string[] | undefined} fromTemplate
- * @returns {string[]}
+ * @param {string[] | undefined} existing існуючий список з `.claude/settings.json` користувача
+ * @param {string[] | undefined} fromTemplate список з темплейту пакета `@nitra/cursor`
+ * @returns {string[]} об'єднаний список без дублікатів (порядок: існуючі, потім нові)
  */
 export function mergeAllowList(existing, fromTemplate) {
   const out = []
@@ -83,9 +83,9 @@ export function mergeAllowList(existing, fromTemplate) {
  * Зливає hooks-секцію: для кожної події в темплейті видаляємо managed-групи
  * з існуючої конфігурації і додаємо актуальні з темплейту. Немені події в
  * темплейті не чіпаються.
- * @param {Record<string, HookGroup[]> | undefined} existing
- * @param {Record<string, HookGroup[]> | undefined} fromTemplate
- * @returns {Record<string, HookGroup[]>}
+ * @param {Record<string, HookGroup[]> | undefined} existing поточна `hooks`-секція з .claude/settings.json
+ * @param {Record<string, HookGroup[]> | undefined} fromTemplate цільова `hooks`-секція з темплейту
+ * @returns {Record<string, HookGroup[]>} результат злиття (порожні події видаляються)
  */
 export function mergeHooks(existing, fromTemplate) {
   /** @type {Record<string, HookGroup[]>} */
@@ -105,9 +105,9 @@ export function mergeHooks(existing, fromTemplate) {
 
 /**
  * Повертає об'єднаний об'єкт settings.json.
- * @param {ClaudeSettings | undefined} existing
- * @param {ClaudeSettings} template
- * @returns {ClaudeSettings}
+ * @param {ClaudeSettings | undefined} existing існуючий вміст `.claude/settings.json` користувача (або undefined, якщо файла нема)
+ * @param {ClaudeSettings} template settings із темплейту пакета `@nitra/cursor`
+ * @returns {ClaudeSettings} результат merge-у (користувацькі поля збережено, наші перевизначено)
  */
 export function mergeSettings(existing, template) {
   /** @type {ClaudeSettings} */
@@ -127,8 +127,8 @@ export function mergeSettings(existing, template) {
 
 /**
  * Читає JSON-файл; якщо файл відсутній або не валідний — повертає `undefined`.
- * @param {string} path
- * @returns {Promise<ClaudeSettings | undefined>}
+ * @param {string} path абсолютний шлях до JSON-файлу
+ * @returns {Promise<ClaudeSettings | undefined>} розпарсений об'єкт або `undefined` (файл відсутній / невалідний)
  */
 async function readJsonOrUndefined(path) {
   if (!existsSync(path)) {
@@ -146,7 +146,7 @@ async function readJsonOrUndefined(path) {
  * користувацьких полів.
  * @param {string} projectRoot корінь проєкту, куди писати
  * @param {string} templateDir каталог `.claude-template/` усередині пакету
- * @returns {Promise<{ written: boolean, path: string }>}
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
 export async function syncClaudeSettings(projectRoot, templateDir) {
   const templatePath = join(templateDir, 'settings.template.json')
@@ -164,9 +164,9 @@ export async function syncClaudeSettings(projectRoot, templateDir) {
 
 /**
  * Копіює `npm/CLAUDE.md` з темплейту, якщо в проєкті є каталог `npm/`.
- * @param {string} projectRoot
- * @param {string} templateDir
- * @returns {Promise<{ written: boolean, path: string }>}
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету `@nitra/cursor`
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
 export async function syncNpmClaudeMd(projectRoot, templateDir) {
   if (!existsSync(join(projectRoot, 'npm'))) {
@@ -185,8 +185,8 @@ export async function syncNpmClaudeMd(projectRoot, templateDir) {
  * Копіює всі slash-команди з `templateDir/commands/` у `.claude/commands/`.
  * Команди ідентифікуються тим, що вони лежать у темплейті — не перетинаються
  * з командами скілів (n-fix, n-lint, ...).
- * @param {string} projectRoot
- * @param {string} templateDir
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету `@nitra/cursor`
  * @returns {Promise<string[]>} масив відносних шляхів записаних файлів
  */
 export async function syncClaudeCommands(projectRoot, templateDir) {
@@ -211,11 +211,11 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
 /**
  * Виконує повну синхронізацію Claude Code-конфігу з темплейту пакету в проєкт.
  * Використовується з `bin/n-cursor.js` після інших синків.
- * @param {object} options
+ * @param {object} options опції синку
  * @param {string} options.projectRoot корінь проєкту-споживача
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
- * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>}
+ * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>} прапорці записів settings/CLAUDE.md та список записаних slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled }) {
   if (!enabled) {

package/scripts/utils/ast-scan-utils.mjs

@@ -118,7 +118,7 @@ export function parseProgramOrNull(content, virtualPath) {
  * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
  * @param {string} content вихідний код
  * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
- * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null}
+ * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null} `program` + список коментарів, або `null` якщо парсер віддав помилки/exception
  */
 export function parseProgramAndCommentsOrNull(content, virtualPath) {
   const lang = langFromPath(virtualPath || 'scan.ts')

package/scripts/utils/bun-sql-scan.mjs

@@ -296,8 +296,7 @@ export function findBunSqlPerRequestConnectionInText(content, virtualPath = 'sca
  * на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
  * лише коли значення контролюється кодом (не user input) і потрібно підставити те, що
  * не можна параметризувати — назву таблиці/колонки або dynamic SQL/DDL. У всіх інших
- * випадках — переробити на tagged template `sql\`...\${value}...\``.
- *
+ * випадках — переробити на tagged template виду `sql` із інтерполяцією значень.
  * Маркер-коментар фіксує причину для ревʼюера й одночасно слугує opt-in: без нього
  * перевірка падає, навіть якщо у `unsafe` лежить статичний рядок без інтерполяції.
  * @param {string} content вихідний код

package/scripts/utils/depcheck-workflow.mjs

@@ -0,0 +1,188 @@
+/**
+ * Аналіз GitHub Actions workflow на правило «depcheck для path-scoped backend-пакета»
+ * (див. секцію в `npm/mdc/js-run.mdc`).
+ *
+ * Алгоритм для одного workspace-пакета (`<rootDir>`):
+ *  1. Шукаємо всі workflow, у яких `on.push.paths` або `on.pull_request.paths` містить
+ *     glob, що починається з `<rootDir>/` — це означає, що workflow обмежено саме цим пакетом
+ *     (повністю або частково).
+ *  2. У кожному такому workflow має бути крок, чий `run` починається з `npx depcheck …`,
+ *     `working-directory` дорівнює `<rootDir>`, а список `--ignores="…"` містить
+ *     щонайменше `graphql` і `bun` (інші значення допустимі).
+ *
+ * Якщо паттерн `paths:` стосується цього пакета, але крок depcheck відсутній / без потрібних
+ * ignores / у неправильному working-directory — фіксується порушення.
+ *
+ * Workflow без `paths:` або з глобальними патернами (`**\/*.js`, `npm/**`) ігноруються —
+ * вони не «належать» жодному окремому пакету і виходять за межі правила.
+ */
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import {
+  flattenWorkflowSteps,
+  getStepRun,
+  parseWorkflowYaml
+} from './gha-workflow.mjs'
+
+const WORKFLOWS_DIR_REL = '.github/workflows'
+const REQUIRED_IGNORES = ['graphql', 'bun']
+const DEPCHECK_RUN_RE = /(?:^|[\s;&|])npx\s+depcheck\b([^\n]*)/u
+const IGNORES_FLAG_RE = /--ignores\s*=?\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))/u
+
+/**
+ * Чи містить workflow.on[event].paths хоча б один patten, що починається з `<pkgRoot>/`.
+ * @param {Record<string, unknown>} root корінь workflow
+ * @param {string} pkgRoot відносний (POSIX) шлях каталогу пакета (наприклад `cron-jobs/refund-loyalty-points`)
+ * @returns {boolean} `true`, якщо знайдено хоча б один підходящий glob
+ */
+export function workflowHasPathsScopedToPackage(root, pkgRoot) {
+  const prefix = `${pkgRoot.replace(/\\/g, '/').replace(/\/+$/, '')}/`
+  const on = root?.on
+  if (!on || typeof on !== 'object') return false
+  for (const event of /** @type {const} */ (['push', 'pull_request'])) {
+    const ev = /** @type {Record<string, unknown>} */ (on)[event]
+    if (!ev || typeof ev !== 'object') continue
+    const paths = /** @type {Record<string, unknown>} */ (ev).paths
+    if (!Array.isArray(paths)) continue
+    if (paths.some(p => typeof p === 'string' && p.startsWith(prefix))) return true
+  }
+  return false
+}
+
+/**
+ * Розбирає `--ignores="a,b,c"` (також `--ignores=a,b`, single-quotes тощо) з аргументів `npx depcheck`.
+ * @param {string} depcheckArgs частина рядка `run` після `npx depcheck`
+ * @returns {string[] | null} масив значень ignores або `null`, якщо прапор відсутній
+ */
+export function parseDepcheckIgnoresArg(depcheckArgs) {
+  const m = IGNORES_FLAG_RE.exec(depcheckArgs)
+  if (!m) return null
+  const raw = m[1] ?? m[2] ?? m[3] ?? ''
+  return raw
+    .split(',')
+    .map(s => s.trim())
+    .filter(s => s.length > 0)
+}
+
+/**
+ * Шукає `npx depcheck` у `run` кроку. Повертає рядок аргументів після `npx depcheck` або `null`.
+ * @param {string} runText значення `run:` (можливо багаторядкове)
+ * @returns {string | null} текст аргументів depcheck або `null`
+ */
+export function extractDepcheckArgs(runText) {
+  if (typeof runText !== 'string' || runText.length === 0) return null
+  const m = DEPCHECK_RUN_RE.exec(runText)
+  return m ? m[1] : null
+}
+
+/**
+ * Чи `working-directory` кроку дорівнює очікуваному pkgRoot (з нормалізацією слешів і хвостових `/`).
+ * @param {Record<string, unknown>} step об'єкт кроку
+ * @param {string} pkgRoot очікуваний шлях
+ * @returns {boolean} `true`, якщо збігаються
+ */
+export function stepWorkingDirectoryEquals(step, pkgRoot) {
+  const wd = step['working-directory']
+  if (typeof wd !== 'string') return false
+  const norm = wd.replace(/\\/g, '/').replace(/\/+$/, '')
+  const expected = pkgRoot.replace(/\\/g, '/').replace(/\/+$/, '')
+  return norm === expected
+}
+
+/**
+ * Перевіряє один workflow на наявність валідного depcheck-кроку для пакета.
+ * @param {Record<string, unknown>} root корінь workflow
+ * @param {string} pkgRoot відносний шлях пакета
+ * @returns {{ kind: 'ok' } | { kind: 'missing' } | { kind: 'wrong-cwd', actual: string } | { kind: 'missing-ignores', missing: string[] }} результат
+ */
+export function evaluateDepcheckStepForPackage(root, pkgRoot) {
+  /** @type {{ args: string, step: Record<string, unknown> }[]} */
+  const depcheckSteps = []
+  for (const { step } of flattenWorkflowSteps(root)) {
+    const args = extractDepcheckArgs(getStepRun(step))
+    if (args !== null) depcheckSteps.push({ args, step })
+  }
+  if (depcheckSteps.length === 0) return { kind: 'missing' }
+
+  // Серед усіх знайдених depcheck-кроків шукаємо хоча б один, що відповідає пакету.
+  const stepsForThisPackage = depcheckSteps.filter(s => stepWorkingDirectoryEquals(s.step, pkgRoot))
+  if (stepsForThisPackage.length === 0) {
+    const actual = depcheckSteps
+      .map(s => /** @type {string} */ (s.step['working-directory'] ?? '<repo root>'))
+      .join(', ')
+    return { kind: 'wrong-cwd', actual }
+  }
+
+  for (const { args } of stepsForThisPackage) {
+    const ignores = parseDepcheckIgnoresArg(args) ?? []
+    const missing = REQUIRED_IGNORES.filter(req => !ignores.includes(req))
+    if (missing.length === 0) return { kind: 'ok' }
+  }
+  // Усі знайдені кроки існують, але жоден не має повного списку обов'язкових ignores —
+  // повертаємо missing з першого, щоб дати конкретний фідбек.
+  const firstMissing = REQUIRED_IGNORES.filter(
+    req => !((parseDepcheckIgnoresArg(stepsForThisPackage[0].args) ?? []).includes(req))
+  )
+  return { kind: 'missing-ignores', missing: firstMissing }
+}
+
+/**
+ * Зчитує всі `.github/workflows/*.yml` (без `*.yaml` — за правилом n-ga) з коренем у `repoRoot`.
+ * @param {string} repoRoot абсолютний корінь репозиторію
+ * @returns {Promise<{ relPath: string, content: string }[]>} список workflow-файлів
+ */
+export async function readAllWorkflowFiles(repoRoot) {
+  const dir = join(repoRoot, WORKFLOWS_DIR_REL)
+  /** @type {{ relPath: string, content: string }[]} */
+  const out = []
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const ent of entries) {
+    if (!ent.isFile() || !ent.name.endsWith('.yml')) continue
+    const abs = join(dir, ent.name)
+    const content = await readFile(abs, 'utf8')
+    out.push({ relPath: relative(repoRoot, abs).split('\\').join('/'), content })
+  }
+  return out
+}
+
+/**
+ * Знаходить порушення правила depcheck для конкретного workspace-пакета.
+ *
+ * Повертає список повідомлень про порушення (порожній — все ok). Для кожного workflow,
+ * чий `paths:` обмежено до цього пакета, перевіряє, що серед кроків є валідний `npx depcheck`
+ * з потрібним `working-directory` та `--ignores`.
+ * @param {{ relPath: string, content: string }[]} workflows список workflow-файлів (з `readAllWorkflowFiles`)
+ * @param {string} pkgRoot відносний шлях workspace-пакета
+ * @returns {string[]} повідомлення про порушення, по одному на workflow
+ */
+export function findDepcheckViolationsForPackage(workflows, pkgRoot) {
+  /** @type {string[]} */
+  const violations = []
+  for (const { relPath, content } of workflows) {
+    const root = parseWorkflowYaml(content)
+    if (!root) continue
+    if (!workflowHasPathsScopedToPackage(root, pkgRoot)) continue
+    const result = evaluateDepcheckStepForPackage(root, pkgRoot)
+    if (result.kind === 'ok') continue
+    if (result.kind === 'missing') {
+      violations.push(
+        `${relPath}: paths обмежено до '${pkgRoot}/**', але немає кроку 'npx depcheck --ignores="graphql,bun"' з working-directory: ${pkgRoot}`
+      )
+    } else if (result.kind === 'wrong-cwd') {
+      violations.push(
+        `${relPath}: 'npx depcheck' знайдено, але working-directory не дорівнює '${pkgRoot}' (фактично: ${result.actual})`
+      )
+    } else {
+      violations.push(
+        `${relPath}: 'npx depcheck' у '${pkgRoot}' має містити --ignores з '${result.missing.join(',')}' (мінімум: graphql,bun)`
+      )
+    }
+  }
+  return violations
+}

package/scripts/utils/find-package-json-paths.mjs

@@ -0,0 +1,30 @@
+/**
+ * Спільна утиліта для check-скриптів: збирає всі `package.json` у дереві (крім пропущених
+ * каталогів у `walkDir`), сортує за відносним шляхом. Винесена з check-js-bun-db / check-js-mssql,
+ * щоб уникнути дублювання (jscpd).
+ */
+import { relative, sep } from 'node:path'
+
+import { walkDir } from './walkDir.mjs'
+
+/**
+ * Знаходить всі `package.json` у репозиторії (крім пропущених директорій у walkDir).
+ * @param {string} repoRoot абсолютний шлях до кореня репозиторію
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<string[]>} абсолютні шляхи, відсортовані за відносним шляхом
+ */
+export async function findAllPackageJsonPaths(repoRoot, ignorePaths) {
+  /** @type {string[]} */
+  const paths = []
+  await walkDir(
+    repoRoot,
+    absPath => {
+      if (absPath.endsWith(`${sep}package.json`)) {
+        paths.push(absPath)
+      }
+    },
+    ignorePaths
+  )
+  paths.sort((a, b) => relative(repoRoot, a).localeCompare(relative(repoRoot, b)))
+  return paths
+}

package/scripts/utils/load-cursor-config.mjs

@@ -20,7 +20,9 @@ const CONFIG_FILE = '.n-cursor.json'
 function toAbsPosix(root, p) {
   const trimmed = String(p).trim()
   const abs = isAbsolute(trimmed) ? trimmed : resolve(root, trimmed)
-  return abs.split(sep).join('/').replace(/\/+$/, '')
+  let posix = abs.split(sep).join('/')
+  while (posix.endsWith('/')) posix = posix.slice(0, -1)
+  return posix
 }
 
 /**

package/scripts/utils/oxlint-canonical.json

@@ -1,17 +1,7 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": [
-    "unicorn",
-    "oxc",
-    "import",
-    "jsdoc",
-    "promise",
-    "node",
-    "vue"
-  ],
-  "jsPlugins": [
-    "@e18e/eslint-plugin"
-  ],
+  "plugins": ["unicorn", "oxc", "import", "jsdoc", "promise", "node", "vue"],
+  "jsPlugins": ["@e18e/eslint-plugin"],
   "categories": {},
   "rules": {
     "e18e/prefer-includes": "error",
@@ -393,8 +383,5 @@
     "builtin": true
   },
   "globals": {},
-  "ignorePatterns": [
-    "**/schema.graphql",
-    "**/auto-imports.d.ts"
-  ]
+  "ignorePatterns": ["**/schema.graphql", "**/auto-imports.d.ts"]
 }

package/scripts/utils/walkDir.mjs

@@ -17,7 +17,9 @@ import { isAbsolute, join, resolve, sep } from 'node:path'
  */
 function toAbsPosix(p) {
   const abs = isAbsolute(p) ? p : resolve(p)
-  return abs.split(sep).join('/').replace(/\/+$/, '')
+  let posix = abs.split(sep).join('/')
+  while (posix.endsWith('/')) posix = posix.slice(0, -1)
+  return posix
 }
 
 /**
@@ -25,7 +27,7 @@ function toAbsPosix(p) {
  * Часткові збіги басенейму не враховуються (postgres-master-test ≠ postgres-master).
  * @param {string} dirAbsPosix абсолютний posix-шлях каталогу
  * @param {string[]} ignorePosix вже нормалізовані ignore-шляхи
- * @returns {boolean}
+ * @returns {boolean} `true`, якщо шлях слід пропустити (точний збіг або префікс з `/`)
  */
 function isIgnoredDir(dirAbsPosix, ignorePosix) {
   for (const ig of ignorePosix) {
@@ -39,20 +41,20 @@ function isIgnoredDir(dirAbsPosix, ignorePosix) {
  * Рекурсивно обходить каталог, пропускає типові артефакти збірки/залежностей та `ignorePaths`.
  * @param {string} dir абсолютний шлях
  * @param {(filePath: string) => void} onFile виклик для кожного файлу
- * @param {string[]} [ignorePaths=[]] шляхи каталогів (відносні від cwd або абсолютні), що повністю виключаються з обходу
- * @returns {Promise<void>}
+ * @param {string[]} [ignorePaths] шляхи каталогів (відносні від cwd або абсолютні), що повністю виключаються з обходу
+ * @returns {Promise<void>} резолвиться по завершенню обходу
  */
 export async function walkDir(dir, onFile, ignorePaths = []) {
-  const ignorePosix = ignorePaths.map(toAbsPosix)
+  const ignorePosix = ignorePaths.map(p => toAbsPosix(p))
   await walkDirInner(dir, onFile, ignorePosix)
 }
 
 /**
  * Внутрішній рекурсор. ignorePosix вже нормалізовано — не нормалізуємо повторно на кожному рівні.
- * @param {string} dir
- * @param {(filePath: string) => void} onFile
- * @param {string[]} ignorePosix
- * @returns {Promise<void>}
+ * @param {string} dir абсолютний шлях каталогу для обходу
+ * @param {(filePath: string) => void} onFile колбек, що викликається для кожного звичайного файлу
+ * @param {string[]} ignorePosix вже нормалізовані абсолютні posix-шляхи ігнорованих каталогів
+ * @returns {Promise<void>} резолвиться по завершенню рекурсії
  */
 async function walkDirInner(dir, onFile, ignorePosix) {
   if (ignorePosix.length > 0 && isIgnoredDir(toAbsPosix(dir), ignorePosix)) return