@nitra/cursor 1.16.1 → 1.17.1

package/rules/test/coverage/coverage.mjs

@@ -0,0 +1,165 @@
+/**
+ * Канонічна команда `n-cursor coverage`: збирає метрики покриття + мутаційного
+ * тестування з усіх провайдерів, чиє правило активне в `.n-cursor.json#rules`,
+ * агрегує та записує COVERAGE.md у корінь проєкту.
+ *
+ * Discovery провайдерів — за `.n-cursor.json#rules`: для кожного `ruleId` зі
+ * списку шукаємо `npm/rules/<ruleId>/coverage/coverage.mjs` і динамічно
+ * імпортуємо. Якщо файлу немає — провайдер для цього правила відсутній (skip
+ * silently, не помилка).
+ *
+ * Лок — прямий виклик `withLock('coverage', steps)`. Один CLI-консумер, один
+ * callsite — спільна точка входу не виноситься (YAGNI, див. C4 у
+ * specs/2026-05-24-coverage-rule-design.md).
+ */
+import { existsSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
+import { withLock } from '../../../scripts/utils/with-lock.mjs'
+
+/** Корінь `npm/rules/` — `<rules>/test/coverage` → `<rules>` */
+const RULES_DIR = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
+
+/**
+ * Сума двох coverage-totals.
+ * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} a перший subtotal
+ * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} b другий subtotal
+ * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} сумарні lines/functions
+ */
+export function addCoverage(a, b) {
+  return {
+    lines: { covered: a.lines.covered + b.lines.covered, total: a.lines.total + b.lines.total },
+    functions: {
+      covered: a.functions.covered + b.functions.covered,
+      total: a.functions.total + b.functions.total
+    }
+  }
+}
+
+/**
+ * Сума двох mutation-counts.
+ * @param {{caught:number,total:number}} a перший subtotal
+ * @param {{caught:number,total:number}} b другий subtotal
+ * @returns {{caught:number,total:number}} сумарні caught/total
+ */
+export function addMutation(a, b) {
+  return { caught: a.caught + b.caught, total: a.total + b.total }
+}
+
+/**
+ * Форматує covered/total як `XX.XX% (covered/total)`.
+ * @param {{covered:number,total:number}} metric метрика lines або functions
+ * @returns {string} відформатований рядок для таблиці COVERAGE.md
+ */
+export function formatCoverage({ covered, total }) {
+  const percent = total === 0 ? '—' : `${((covered / total) * 100).toFixed(2)}%`
+  return `${percent} (${covered}/${total})`
+}
+
+/**
+ * Форматує мутаційний score як `XX.XX%`.
+ * @param {{caught:number,total:number}} metric агрегований mutation score
+ * @returns {string} відформатований score або прочерк
+ */
+export function formatScore({ caught, total }) {
+  return total === 0 ? '—' : `${((caught / total) * 100).toFixed(2)}%`
+}
+
+/**
+ * Рендерить таблицю покриття + мутаційного тестування як Markdown.
+ * Без timestamp, щоб git diff рухався лише при зміні метрик.
+ * @param {Array<{area:string, coverage:{lines:{covered:number,total:number},functions:{covered:number,total:number}}, mutation:{caught:number,total:number}}>} rows рядки провайдерів
+ * @returns {string} Markdown-таблиця з заголовком `# Coverage`
+ */
+export function renderMarkdown(rows) {
+  const lines = [
+    '# Coverage',
+    '',
+    '| Область | Рядки | Функції | Вбито мутацій | Score |',
+    '| --- | --- | --- | --- | --- |'
+  ]
+  for (const row of rows) {
+    lines.push(
+      `| ${row.area} | ${formatCoverage(row.coverage.lines)} | ${formatCoverage(row.coverage.functions)} | ` +
+        `${row.mutation.caught}/${row.mutation.total} | ${formatScore(row.mutation)} |`
+    )
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * Завантажує provider-модуль з `<rulesDir>/<ruleId>/coverage/coverage.mjs`.
+ * Повертає null коли:
+ *   - файлу немає (rule без coverage-провайдера),
+ *   - файл існує, але не експортує `detect` + `collect` як функції (наприклад,
+ *     `rules/test/coverage/coverage.mjs` — сам оркестратор, не провайдер).
+ * @param {string} rulesDir корінь `npm/rules/`
+ * @param {string} ruleId id правила з `.n-cursor.json#rules`
+ * @returns {Promise<{detect:(cwd:string)=>Promise<boolean>, collect:(cwd:string)=>Promise<Array<object>>}|null>} provider-модуль або null
+ */
+async function loadProvider(rulesDir, ruleId) {
+  const providerPath = join(rulesDir, ruleId, 'coverage', 'coverage.mjs')
+  if (!existsSync(providerPath)) return null
+  // eslint-disable-next-line no-unsanitized/method -- providerPath з join(rulesDir, ruleId, …), ruleId з конфігу
+  const mod = await import(pathToFileURL(providerPath).href)
+  if (typeof mod.detect !== 'function' || typeof mod.collect !== 'function') return null
+  return mod
+}
+
+/**
+ * Будує підсумковий рядок «Разом» через сумування всіх coverage/mutation.
+ * @param {Array<{area:string, coverage:object, mutation:object}>} rows рядки провайдерів без totals
+ * @returns {{area:string, coverage:object, mutation:{caught:number,total:number}}} агрегований рядок «Разом»
+ */
+function buildTotalsRow(rows) {
+  let totalCoverage = { lines: { covered: 0, total: 0 }, functions: { covered: 0, total: 0 } }
+  let totalMutation = { caught: 0, total: 0 }
+  for (const row of rows) {
+    totalCoverage = addCoverage(totalCoverage, row.coverage)
+    totalMutation = addMutation(totalMutation, row.mutation)
+  }
+  return { area: '**Разом**', coverage: totalCoverage, mutation: totalMutation }
+}
+
+/**
+ * Виконує coverage-pipeline: discovery провайдерів за `.n-cursor.json#rules`,
+ * detect+collect для кожного, агрегація, запис COVERAGE.md.
+ * @param {{cwd?:string, rulesDir?:string}} [opts] ін'єкція cwd/rulesDir для тестів
+ * @returns {Promise<number>} exit code (0 OK, 1 коли жоден провайдер не дав даних)
+ */
+export async function runCoverageSteps(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const rulesDir = opts.rulesDir ?? RULES_DIR
+  const config = await readNCursorConfigLite(cwd)
+  const rows = []
+
+  for (const ruleId of config.rules) {
+    if (config.disableRules.includes(ruleId)) continue
+    const provider = await loadProvider(rulesDir, ruleId)
+    if (!provider) continue
+    if (!(await provider.detect(cwd))) continue
+    console.log(`→ ${ruleId} coverage…`)
+    rows.push(...(await provider.collect(cwd)))
+  }
+
+  if (rows.length === 0) {
+    console.error('✗ Жодного провайдера покриття не знайдено для активних правил у .n-cursor.json#rules')
+    return 1
+  }
+
+  rows.push(buildTotalsRow(rows))
+  const md = renderMarkdown(rows)
+  await writeFile(join(cwd, 'COVERAGE.md'), md, 'utf8')
+  console.log('✓ COVERAGE.md')
+  return 0
+}
+
+// Один оркестратор, один callsite — `withLock` викликається напряму, без спільної
+// точки входу. Канонічне обмеження «не імпортуй withLock у lint.mjs/fix.mjs напряму»
+// (scripts.mdc § withLock) націлене на дедуплікацію preamble серед багатьох файлів —
+// для одного coverage-консумера не релевантне (див. C4 у
+// specs/2026-05-24-coverage-rule-design.md).
+export const runCoverageCli = () => withLock('coverage', runCoverageSteps)

package/rules/test/fix.mjs

@@ -1,3 +1,4 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
 import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
 
 /**
@@ -10,10 +11,9 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (import.meta.main) {
+if (isRunAsCli()) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  const { runRuleCli } = await import('../../scripts/lib/run-rule-cli.mjs')
-  // eslint-disable-next-line unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/test/js/location.mjs

@@ -18,7 +18,7 @@ const TESTS_DIR_NAME = 'tests'
 /**
  * Чи файл є JS-тестом (`*.test.mjs`).
  * @param {string} absPath абсолютний шлях
- * @returns {boolean}
+ * @returns {boolean} true для шляхів із суфіксом `.test.mjs`
  */
 function isTestFile(absPath) {
   return basename(absPath).endsWith('.test.mjs')

package/rules/test/policy/package_json/package_json.rego

@@ -0,0 +1,17 @@
+# Перевірка `package.json` для правила test (test.mdc).
+#
+# Канон надходить через --data: { "template": { "contains": ... } }
+# Структура --data сформована з template/package.json.contains.json.
+# Перевіряємо substring-вимоги до scripts.coverage:
+# рядок має містити "n-cursor coverage" (локальні розширення дозволені).
+package test.package_json
+
+import rego.v1
+
+deny contains msg if {
+	some script_name, needles in data.template.contains.scripts
+	actual := object.get(object.get(input, "scripts", {}), script_name, "")
+	some needle in needles
+	not contains(actual, needle)
+	msg := sprintf("package.json: scripts.%s має містити %q (test.mdc)", [script_name, needle])
+}

package/rules/test/policy/package_json/target.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": "package.json", "required": true },
+  "missingMessage": "package.json не існує — створи зі scripts.coverage (test.mdc)"
+}

package/rules/test/policy/package_json/template/package.json.contains.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "coverage": ["n-cursor coverage"]
+  }
+}

package/rules/test/test.mdc

@@ -1,6 +1,6 @@
 ---
 description: JS-тести (*.test.mjs) живуть у каталозі tests/ поряд із джерельним файлом, а не безпосередньо в тій же директорії
-version: '1.1'
+version: '1.2'
 alwaysApply: true
 ---
 
@@ -58,3 +58,13 @@ Recursive globs ловлять файли всередині `tests/` так с
 `*_test.rego` перевіркою **не охоплюються** — вони не переміщуються.
 
 Пропускаються: `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv`, шляхи з `.n-cursor.json:ignore`.
+
+## Покриття + мутаційне тестування
+
+Канонічна команда — `n-cursor coverage`: збирає метрики покриття (`bun test --coverage`, `cargo llvm-cov` тощо) і мутаційного тестування (Stryker, `cargo-mutants`) з усіх активних провайдерів у `.n-cursor.json#rules` і пише `COVERAGE.md` у корінь проєкту. Лок і дедуп — `withLock('coverage', ...)`.
+
+Провайдери живуть у `npm/rules/<rule>/coverage/coverage.mjs` (постачаються правилами мови/рантайму: `js-lint`, `rust`, у майбутньому `python` тощо). Оркестратор — у `npm/rules/test/coverage/coverage.mjs`.
+
+У `package.json` (корінь) має бути `scripts.coverage` із викликом `n-cursor coverage`:
+
+Канон `scripts.coverage` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)

package/rules/text/fix.mjs

@@ -1,3 +1,4 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
 import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
 
 /**
@@ -10,10 +11,9 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (import.meta.main) {
+if (isRunAsCli()) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  const { runRuleCli } = await import('../../scripts/lib/run-rule-cli.mjs')
-  // eslint-disable-next-line unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/vue/fix.mjs

@@ -1,3 +1,4 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
 import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
 
 /**
@@ -10,10 +11,9 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (import.meta.main) {
+if (isRunAsCli()) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  const { runRuleCli } = await import('../../scripts/lib/run-rule-cli.mjs')
-  // eslint-disable-next-line unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/scripts/lib/run-rule-cli.mjs

@@ -7,6 +7,7 @@
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.
  */
 import { basename } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 import { isRuleEnabled, readNCursorConfigLite } from './read-n-cursor-config-lite.mjs'
 import { runStandardRule } from './run-standard-rule.mjs'
@@ -14,6 +15,16 @@ import { getOrCreateWalkCache } from '../utils/walk-cache.mjs'
 
 const PACKAGE_NAME = '@nitra/cursor'
 
+/**
+ * Чи поточний модуль запущено як CLI entry-point (`bun rules/<id>/fix.mjs`).
+ * @returns {boolean} true, коли `import.meta.url` збігається з `process.argv[1]`
+ */
+export function isRunAsCli() {
+  const entry = process.argv[1]
+  if (!entry) return false
+  return import.meta.url === pathToFileURL(entry).href
+}
+
 /**
  * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
  * @returns {Promise<number>} 0 — OK або правило не enabled; 1 — порушення

package/scripts/lib/run-standard-rule.mjs

@@ -32,7 +32,7 @@ import { withLock } from '../utils/with-lock.mjs'
  * @param {RuleContext} [ctx] контекст прогону (walkCache тощо)
  * @returns {Promise<number>} 0 OK, 1 violations
  */
-export async function runStandardRule(ruleDir, ctx = {}) {
+export function runStandardRule(ruleDir, ctx = {}) {
   const ruleId = basename(ruleDir)
   const bundledRulesDir = dirname(ruleDir)
   return withLock(`fix-${ruleId}`, async () => {

package/scripts/utils/with-lock.mjs

@@ -3,7 +3,7 @@
  * Алгоритм: mkdirSync-based lock, перевірка живості PID, sha256-dedup з TTL.
  */
 import * as fs from 'node:fs'
-import * as path from 'node:path'
+import { join } from 'node:path'
 import * as os from 'node:os'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { worktreeFingerprint } from './worktree-fingerprint.mjs'
@@ -12,9 +12,14 @@ const DEFAULTS = {
   ttl: 600_000,
   staleThreshold: 1_800_000,
   waitTimeout: 1_200_000,
-  pollInterval: 1_500
+  pollInterval: 1500
 }
 
+/**
+ * Чи процес із заданим PID ще живий на поточному host.
+ * @param {number} pid ідентифікатор процесу з owner.json
+ * @returns {boolean} true, якщо process.kill(pid, 0) не кинув помилку
+ */
 function isAlive(pid) {
   try {
     process.kill(pid, 0)
@@ -24,14 +29,21 @@ function isAlive(pid) {
   }
 }
 
+/**
+ * Повертає функцію, що знімає lock-директорію.
+ * @param {string} lockDir абсолютний шлях до lock-директорії
+ * @returns {() => void} release-колбек для finally/signal handler
+ */
 function makeRelease(lockDir) {
   return () => fs.rmSync(lockDir, { recursive: true, force: true })
 }
 
 /**
- * @param {{exitCode:number, fingerprint:string|null, finishedAt:number}} result
- * @param {string|null} fingerprint
- * @param {number} ttl
+ * Чи можна пропустити повторний прогін за кешованим result.json.
+ * @param {{exitCode:number, fingerprint:string|null, finishedAt:number}} result попередній результат з result.json
+ * @param {string|null} fingerprint поточний fingerprint робочого дерева
+ * @param {number} ttl TTL дедуплікації в мілісекундах
+ * @returns {boolean} true, якщо попередній успішний прогін можна повторно використати
  */
 export function shouldDedup(result, fingerprint, ttl) {
   if (result.exitCode !== 0) return false
@@ -41,27 +53,26 @@ export function shouldDedup(result, fingerprint, ttl) {
 }
 
 /**
- * @param {string} key
- * @param {() => number | Promise<number>} runFn
- * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string, getFingerprint?:() => string | null}} [opts]
- * @returns {Promise<number>}
+ * Серіалізує важку команду через атомарний lock і dedup за fingerprint.
+ * @param {string} key ключ локу (наприклад `lint-ga`, `fix-bun`)
+ * @param {() => number | Promise<number>} runFn основна робота; повертає exit code
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string, getFingerprint?:() => string | null}} [opts] TTL, шлях кешу та override fingerprint
+ * @returns {Promise<number>} exit code виконаної або дедуплікованої команди
  */
 export async function withLock(key, runFn, opts = {}) {
   const { ttl, staleThreshold, waitTimeout, pollInterval } = { ...DEFAULTS, ...opts }
   const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
-  const cacheDir = opts.cacheDir ?? path.join(process.cwd(), 'node_modules/.cache/n-cursor', key)
-  const lockDir = path.join(cacheDir, 'lock')
-  const ownerFile = path.join(lockDir, 'owner.json')
-  const resultFile = path.join(cacheDir, 'result.json')
+  const cacheDir = opts.cacheDir ?? join(process.cwd(), 'node_modules/.cache/n-cursor', key)
+  const lockDir = join(cacheDir, 'lock')
+  const ownerFile = join(lockDir, 'owner.json')
+  const resultFile = join(cacheDir, 'result.json')
   const release = makeRelease(lockDir)
 
   const fingerprint = getFingerprint()
   fs.mkdirSync(cacheDir, { recursive: true })
 
   const loopStart = Date.now()
-  let locked = false
 
-  // eslint-disable-next-line no-constant-condition
   while (true) {
     if (Date.now() - loopStart >= waitTimeout) {
       console.error(`⚠️ ${key}: чекав ${waitTimeout / 60_000} хв — запускаю без локу`)
@@ -73,7 +84,6 @@ export async function withLock(key, runFn, opts = {}) {
         ownerFile,
         JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now(), fingerprint })
       )
-      locked = true
       break
     } catch (error) {
       if (error.code !== 'EEXIST') throw error
@@ -113,6 +123,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
     process.exit(130)
   }
   process.once('SIGINT', onSignal)

package/scripts/utils/worktree-fingerprint.mjs

@@ -1,13 +1,16 @@
-/**
- * Fingerprint поточного стану git-робочого дерева.
- * Повертає sha256-hex (64 символи) або null, якщо не в git-репо.
- * @param {typeof import('child_process').spawnSync} spawn
- */
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 
+/**
+ * Fingerprint поточного стану git-робочого дерева.
+ * @param {typeof import('child_process').spawnSync} [spawn] sync-виклик git (ін'єкція для тестів)
+ * @returns {string|null} sha256-hex (64 символи) або null, якщо не в git-репо
+ */
 export function worktreeFingerprint(spawn = spawnSync) {
-  /** @param {string[]} args */
+  /**
+   * @param {string[]} args аргументи підкоманди git
+   * @returns {string} stdout git-команди
+   */
   function git(args) {
     const r = spawn('git', args, { encoding: 'utf8' })
     if (r.status !== 0 || r.error) throw new Error(`git ${args[0]} failed`)
@@ -21,9 +24,7 @@ export function worktreeFingerprint(spawn = spawnSync) {
     // повертаються у `"..."` формі, і `git hash-object` не знаходить файл → throw → fingerprint=null.
     const untrackedRaw = git(['ls-files', '-z', '--others', '--exclude-standard'])
     const untrackedFiles = untrackedRaw.split('\0').filter(Boolean)
-    const pairs = untrackedFiles
-      .map(f => `${f}:${git(['hash-object', f]).trim()}`)
-      .sort()
+    const pairs = untrackedFiles.map(f => `${f}:${git(['hash-object', f]).trim()}`).toSorted()
     const raw = [commitHash, diffText, ...pairs].join('\n')
     return createHash('sha256').update(raw).digest('hex')
   } catch {