@nitra/cursor 1.17.0 → 1.17.1

package/rules/js-lint/coverage/coverage.mjs

@@ -5,6 +5,7 @@
  *
  * Контракт провайдера — у docs/superpowers/specs/2026-05-24-coverage-rule-design.md.
  */
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -12,9 +13,9 @@ import { join } from 'node:path'
 
 /**
  * Резолвить cwd, у якому стоять JS-тести. Workspace-проєкти — перший workspace
- * (mlmail: app/), single-package — корінь.
+ * (наприклад: app/), single-package — корінь.
  * @param {string} cwd корінь проєкту
- * @returns {Promise<string|null>} абсолютний шлях або null якщо package.json відсутній
+ * @returns {Promise<string|null>} абсолютний шлях до JS-root або null без package.json
  */
 async function resolveJsRoot(cwd) {
   const rootPkgPath = join(cwd, 'package.json')
@@ -30,8 +31,8 @@ async function resolveJsRoot(cwd) {
 
 /**
  * Чи `scripts` містить coverage-сумісну команду.
- * @param {Record<string, string> | undefined} scripts
- * @returns {boolean}
+ * @param {Record<string, string> | undefined} scripts секція scripts з package.json
+ * @returns {boolean} true, якщо є test:coverage або test з --coverage
  */
 function hasCoverageScript(scripts) {
   if (!scripts || typeof scripts !== 'object') return false
@@ -42,8 +43,8 @@ function hasCoverageScript(scripts) {
 
 /**
  * Чи провайдер застосовний у поточному cwd.
- * @param {string} cwd
- * @returns {Promise<boolean>}
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<boolean>} true, якщо знайдено coverage-сумісний test-скрипт
  */
 export async function detect(cwd) {
   const jsRoot = await resolveJsRoot(cwd)
@@ -56,8 +57,8 @@ export async function detect(cwd) {
 
 /**
  * Парс lcov.info: сумує LF/LH (рядки) і FNF/FNH (функції) по всіх records.
- * @param {string} text
- * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}}
+ * @param {string} text вміст lcov.info
+ * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} агреговані totals
  */
 function parseLcov(text) {
   const acc = { lines: { covered: 0, total: 0 }, functions: { covered: 0, total: 0 } }
@@ -73,8 +74,8 @@ function parseLcov(text) {
 /**
  * Парс Stryker mutation.json: Killed+Timeout → caught; Survived+NoCoverage → до total.
  * Compile/Runtime errors виключаються з total.
- * @param {{files:Record<string,{mutants:Array<{status:string}>}>}} report
- * @returns {{caught:number,total:number}}
+ * @param {{files:Record<string,{mutants:Array<{status:string}>}>}} report розпарсений mutation.json
+ * @returns {{caught:number,total:number}} агрегований mutation score
  */
 function parseStrykerReport(report) {
   let caught = 0
@@ -93,20 +94,21 @@ function parseStrykerReport(report) {
 }
 
 /**
- * Default runner — спавнить реальні bun-команди. Замінюється у тестах.
+ * Default runner — спавнить реальні bun-команди через `node:child_process.spawnSync`
+ * (працює і в Node-runtime через shebang `n-cursor`, і в Bun). Замінюється у тестах.
  */
 const defaultRunner = {
-  async runJsCoverage({ cwd, lcovDir }) {
-    const proc = Bun.spawn(['bun', 'run', 'test:coverage', '--coverage-reporter=lcov', `--coverage-dir=${lcovDir}`], {
+  runJsCoverage({ cwd, lcovDir }) {
+    const r = spawnSync('bun', ['run', 'test:coverage', '--coverage-reporter=lcov', `--coverage-dir=${lcovDir}`], {
       cwd,
-      stdout: 'inherit',
-      stderr: 'inherit'
+      stdio: 'inherit',
+      env: process.env
     })
-    return proc.exited
+    return r.status ?? 1
   },
-  async runStryker({ cwd }) {
-    const proc = Bun.spawn(['bunx', 'stryker', 'run'], { cwd, stdout: 'inherit', stderr: 'inherit' })
-    return proc.exited
+  runStryker({ cwd }) {
+    const r = spawnSync('bunx', ['stryker', 'run'], { cwd, stdio: 'inherit', env: process.env })
+    return r.status ?? 1
   }
 }
 
@@ -114,7 +116,7 @@ const defaultRunner = {
  * Збирає JS-метрики покриття + мутаційного тестування.
  * @param {string} cwd корінь проєкту
  * @param {{runner?: typeof defaultRunner}} [opts] runner-ін'єкція для тестів
- * @returns {Promise<Array<{area:string, coverage:object, mutation:{caught:number,total:number}}>>}
+ * @returns {Promise<Array<{area:string, coverage:object, mutation:{caught:number,total:number}}>>} рядки для COVERAGE.md
  */
 export async function collect(cwd, opts = {}) {
   const runner = opts.runner ?? defaultRunner

package/rules/js-lint/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/js-mssql/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/js-run/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/k8s/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/nginx-default-tpl/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/npm-module/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/php/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/rego/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/rust/coverage/coverage.mjs

@@ -6,6 +6,7 @@
  *
  * Контракт провайдера — у docs/superpowers/specs/2026-05-24-coverage-rule-design.md.
  */
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -17,17 +18,17 @@ const IGNORED_DIR_NAMES = new Set(['node_modules', '.git', '.next', '.turbo', 't
 
 /**
  * Чи провайдер застосовний у поточному cwd.
- * @param {string} cwd
- * @returns {Promise<boolean>}
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<boolean>} true, якщо знайдено Cargo.toml у cwd або workspace-піддереві
  */
-export async function detect(cwd) {
-  if (existsSync(join(cwd, 'Cargo.toml'))) return true
-  return hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES)
+export function detect(cwd) {
+  if (existsSync(join(cwd, 'Cargo.toml'))) return Promise.resolve(true)
+  return Promise.resolve(hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES))
 }
 
 /**
  * Знайти Cargo.toml: cwd/Cargo.toml або в одному з workspace-підкаталогів.
- * @param {string} cwd
+ * @param {string} cwd корінь проєкту
  * @returns {Promise<string>} абсолютний шлях до Cargo.toml
  */
 async function resolveCargoManifest(cwd) {
@@ -50,29 +51,27 @@ async function resolveCargoManifest(cwd) {
 }
 
 const defaultRunner = {
-  async runLlvmCov({ manifestPath }) {
-    const proc = Bun.spawn(['cargo', 'llvm-cov', '--manifest-path', manifestPath, '--json', '--summary-only'], {
-      stdout: 'pipe',
-      stderr: 'inherit'
+  runLlvmCov({ manifestPath }) {
+    const r = spawnSync('cargo', ['llvm-cov', '--manifest-path', manifestPath, '--json', '--summary-only'], {
+      stdio: ['inherit', 'pipe', 'inherit'],
+      env: process.env
     })
-    const stdout = await new Response(proc.stdout).text()
-    const exitCode = await proc.exited
-    return { exitCode, stdout }
+    return { exitCode: r.status ?? 1, stdout: r.stdout?.toString('utf8') ?? '' }
   },
-  async runCargoMutants({ manifestPath, outDir }) {
-    const proc = Bun.spawn(['cargo', 'mutants', '--in-place', '-o', outDir, '--manifest-path', manifestPath], {
-      stdout: 'inherit',
-      stderr: 'inherit'
+  runCargoMutants({ manifestPath, outDir }) {
+    const r = spawnSync('cargo', ['mutants', '--in-place', '-o', outDir, '--manifest-path', manifestPath], {
+      stdio: 'inherit',
+      env: process.env
     })
-    return proc.exited
+    return r.status ?? 1
   }
 }
 
 /**
  * Збирає Rust-метрики покриття + мутаційного тестування.
  * @param {string} cwd корінь проєкту
- * @param {{runner?: typeof defaultRunner}} [opts]
- * @returns {Promise<Array<{area:string, coverage:object, mutation:{caught:number,total:number}}>>}
+ * @param {{runner?: typeof defaultRunner}} [opts] ін'єкція runner-а для тестів
+ * @returns {Promise<Array<{area:string, coverage:object, mutation:{caught:number,total:number}}>>} рядки для COVERAGE.md
  */
 export async function collect(cwd, opts = {}) {
   const runner = opts.runner ?? defaultRunner

package/rules/rust/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/rust/lib/has-cargo-toml.mjs

@@ -29,9 +29,7 @@ export function hasCargoTomlInTree(root, ignoredDirNames) {
     }
     for (const entry of entries) {
       if (entry.isFile() && entry.name === 'Cargo.toml') return true
-      if (entry.isDirectory() && !ignoredDirNames.has(entry.name)) {
-        if (walk(join(dir, entry.name))) return true
-      }
+      if (entry.isDirectory() && !ignoredDirNames.has(entry.name) && walk(join(dir, entry.name))) return true
     }
     return false
   }

package/rules/security/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/style-lint/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/style-lint/js/tooling.mjs

@@ -25,7 +25,7 @@ import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
  * Альтернатива полю `stylelint` у `package.json` — зовнішній файл конфігу. Якщо
  * поля немає і файлу немає, фейлимося; якщо є хоч щось — пропускаємо. Поле
  * `stylelint.extends == "@nitra/stylelint-config"` сам формат — у Rego.
- * @param {import('../../../../scripts/lib/check-reporter.mjs').CheckReporter} reporter репортер
+ * @param {import('../../../scripts/lib/check-reporter.mjs').CheckReporter} reporter репортер
  */
 async function checkStylelintConfigPresence(reporter) {
   const { pass, fail } = reporter

package/rules/tauri/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/coverage/coverage.mjs

@@ -15,7 +15,7 @@
 import { existsSync } from 'node:fs'
 import { writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+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'
@@ -25,9 +25,9 @@ const RULES_DIR = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
 
 /**
  * Сума двох coverage-totals.
- * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} a
- * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} b
- * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}}
+ * @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 {
@@ -41,9 +41,9 @@ export function addCoverage(a, b) {
 
 /**
  * Сума двох mutation-counts.
- * @param {{caught:number,total:number}} a
- * @param {{caught:number,total:number}} b
- * @returns {{caught:number,total:number}}
+ * @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 }
@@ -51,8 +51,8 @@ export function addMutation(a, b) {
 
 /**
  * Форматує covered/total як `XX.XX% (covered/total)`.
- * @param {{covered:number,total:number}} metric
- * @returns {string}
+ * @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)}%`
@@ -61,8 +61,8 @@ export function formatCoverage({ covered, total }) {
 
 /**
  * Форматує мутаційний score як `XX.XX%`.
- * @param {{caught:number,total:number}} metric
- * @returns {string}
+ * @param {{caught:number,total:number}} metric агрегований mutation score
+ * @returns {string} відформатований score або прочерк
  */
 export function formatScore({ caught, total }) {
   return total === 0 ? '—' : `${((caught / total) * 100).toFixed(2)}%`
@@ -71,8 +71,8 @@ export function formatScore({ caught, total }) {
 /**
  * Рендерить таблицю покриття + мутаційного тестування як 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}
+ * @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 = [
@@ -96,36 +96,38 @@ export function renderMarkdown(rows) {
  *   - файлу немає (rule без coverage-провайдера),
  *   - файл існує, але не експортує `detect` + `collect` як функції (наприклад,
  *     `rules/test/coverage/coverage.mjs` — сам оркестратор, не провайдер).
- * @param {string} rulesDir
- * @param {string} ruleId
- * @returns {Promise<{detect:Function, collect:Function}|null>}
+ * @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
-  const mod = await import(providerPath)
+  // 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
- * @returns {{area:string, coverage:object, mutation:{caught:number,total:number}}}
+ * @param {Array<{area:string, coverage:object, mutation:object}>} rows рядки провайдерів без totals
+ * @returns {{area:string, coverage:object, mutation:{caught:number,total:number}}} агрегований рядок «Разом»
  */
 function buildTotalsRow(rows) {
-  const totalCoverage = rows.reduce((acc, row) => addCoverage(acc, row.coverage), {
-    lines: { covered: 0, total: 0 },
-    functions: { covered: 0, total: 0 }
-  })
-  const totalMutation = rows.reduce((acc, row) => addMutation(acc, row.mutation), { caught: 0, total: 0 })
+  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] ін'єкція для тестів
+ * @param {{cwd?:string, rulesDir?:string}} [opts] ін'єкція cwd/rulesDir для тестів
  * @returns {Promise<number>} exit code (0 OK, 1 коли жоден провайдер не дав даних)
  */
 export async function runCoverageSteps(opts = {}) {

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/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))
 }