@nitra/cursor 1.13.84 → 1.13.85

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.85] - 2026-05-23
+
+### Changed
+
+- **`withLock` розгорнуто на всі важкі CLI-команди:** додано серіалізацію + дедуп у `lint-rego`, `lint-text`, `lint-k8s`, `lint-docker` за тим самим зразком, що `lint-ga` (приватна `runLint<Foo>Steps()` + публічна `runLint<Foo>Cli = () => withLock('lint-<rule>', …)`).
+- **`fix`-лок переїхав у `runStandardRule`:** замість зовнішньої обгортки навколо `runFixCommand` у `bin/n-cursor.js`, `withLock('fix-<ruleId>')` тепер всередині `scripts/utils/run-standard-rule.mjs`. Кожен `rules/<id>/fix.mjs` отримує лок «безкоштовно» через делегацію; `npx @nitra/cursor fix`, прямий `bun rules/<id>/fix.mjs` і `run(ctx)`-композиція проходять через одну точку. Per-rule гранулярність — різні правила паралельно, однакові серіалізуються.
+- **`runLintRego` тепер async** (наслідок обгортки), додано окремий export `runLintRegoSteps(cwd)` для тестів — щоб не дедупувати проти попереднього прогону, який лишив cached result у `node_modules/.cache/n-cursor/lint-rego/`.
+- **`.cursor/rules/scripts.mdc` 1.8 → 1.9:** додано канонічну секцію «Серіалізація важких CLI-команд: `withLock`» з патерном інтеграції, таблицею ключів і red flags.
+
+### Fixed
+
+- Тест `withLock integration > serializes parallel calls` падав через дедуп (обидва виклики бачили однаковий fingerprint і другий пропускав). Тест явно вимикає дедуп через `getFingerprint: () => null` — окремо тестується серіалізація, окремо дедуп.
+- Тест `runLintTextCli` після обгортки повертає Promise; `withIsolatedPath` тепер `await fn()`.
+- JSDoc-тип `withLock` opts розширено `getFingerprint?` (вже використовувався у runtime, але був відсутній у сигнатурі — TS видавав error 2353).
+
 ## [1.13.84] - 2026-05-23
 
 ### Changed

package/bin/n-cursor.js

@@ -978,6 +978,10 @@ function logRemovedManagedItems(title, basePath, names) {
  * перевіряє whitelist (`runRuleCli`) і друкує per-rule summary.
  *
  * Без аргументів — discover з `.cursor/rules/*.mdc` у проекті-споживачі.
+ *
+ * Серіалізація паралельних запусків — per-rule, всередині `runStandardRule` (`withLock('fix-<id>')`).
+ * На рівні `runFixCommand` локу нема: різні набори правил можуть прогресувати незалежно,
+ * а однакові правила серіалізуються в spawn'ах нижче.
  * @param {string[]} requestedRules імена правил; порожній масив — discovery з `.cursor/rules/`
  * @returns {Promise<void>}
  */
@@ -1258,7 +1262,7 @@ try {
     }
     case 'lint-rego': {
       // Канонічний lint-rego: preflight opa/regal → opa check --strict → regal lint → conftest verify (опц.).
-      process.exitCode = runLintRego()
+      process.exitCode = await runLintRego()
 
       break
     }
@@ -1276,7 +1280,7 @@ try {
     }
     case 'lint-text': {
       // Канонічний lint-text: cspell → run-shellcheck → markdownlint-cli2 --fix → run-v8r (text.mdc).
-      process.exitCode = runLintTextCli()
+      process.exitCode = await runLintTextCli()
 
       break
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.84",
+  "version": "1.13.85",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/docker/lint/lint.mjs

@@ -14,6 +14,7 @@ import { lintDockerfileWithHadolint, posixRel } from '../js/lint/docker-hadolint
 import { createCheckReporter } from '../../../scripts/utils/check-reporter.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/utils/load-cursor-config.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
 /**
  * Чи входить файл до набору lint-docker: Dockerfile або *.Dockerfile (*.dockerfile).
@@ -46,11 +47,10 @@ export async function findLintDockerfilePaths(root, ignorePaths = []) {
 }
 
 /**
- * Запуск hadolint по Dockerfile та *.Dockerfile.
- * Експортовано як `runLintDocker` — використовується з `bin/n-cursor.js` як підкоманда `lint-docker`.
+ * Внутрішні кроки `lint-docker` без локу: hadolint по Dockerfile та *.Dockerfile.
  * @returns {Promise<number>} 0 — OK, 1 — зауваження або помилка
  */
-export async function runLintDocker() {
+async function runLintDockerSteps() {
   const reporter = createCheckReporter()
   const { pass, fail } = reporter
 
@@ -80,6 +80,13 @@ export async function runLintDocker() {
   return reporter.getExitCode()
 }
 
+/**
+ * Публічна CLI-форма: серіалізує через `withLock('lint-docker')` + дедуп за станом git-дерева.
+ * Експортовано як `runLintDocker` — використовується з `bin/n-cursor.js` як підкоманда `lint-docker`.
+ * @returns {Promise<number>} код виходу
+ */
+export const runLintDocker = () => withLock('lint-docker', runLintDockerSteps)
+
 if (isRunAsCli()) {
   process.exitCode = await runLintDocker()
 }

package/rules/k8s/lint/lint.mjs

@@ -24,6 +24,7 @@ import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/utils/load-cursor-config.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
 /** Per-project kubescape exceptions file; підмішується через --exceptions, якщо існує в корені. */
 const KUBESCAPE_EXCEPTIONS_FILE = '.kubescape-exceptions.json'
@@ -320,11 +321,10 @@ async function runKubescape(dirs, root) {
 }
 
 /**
- * Головна точка входу: kubeconform + kubescape для усіх знайдених дерев `k8s`.
- * Експортовано як `runLintK8s` — використовується з `bin/n-cursor.js` як підкоманда `lint-k8s`.
+ * Внутрішні кроки `lint-k8s` без локу: kubeconform + kubescape для усіх знайдених дерев `k8s`.
  * @returns {Promise<number>} код виходу для `process.exitCode` (0 — успіх або пропуск)
  */
-export async function runLintK8s() {
+async function runLintK8sSteps() {
   const root = process.cwd()
   const ignorePaths = await loadCursorIgnorePaths(root)
   const dirs = await findK8sRoots(root, ignorePaths)
@@ -344,6 +344,13 @@ export async function runLintK8s() {
   return ks
 }
 
+/**
+ * Публічна CLI-форма: серіалізує через `withLock('lint-k8s')` + дедуп за станом git-дерева.
+ * Експортовано як `runLintK8s` — використовується з `bin/n-cursor.js` як підкоманда `lint-k8s`.
+ * @returns {Promise<number>} код виходу
+ */
+export const runLintK8s = () => withLock('lint-k8s', runLintK8sSteps)
+
 if (isRunAsCli()) {
   process.exitCode = await runLintK8s()
 }

package/rules/rego/lint/lint.mjs

@@ -29,6 +29,7 @@ import { resolve } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
 /** Шляхи з Rego-полісі (відносно cwd). Існують не всі на ранніх стадіях — фільтруємо нижче. */
 const LINT_TARGETS = ['npm/rules']
@@ -89,10 +90,13 @@ function runStep(bin, args, cwd) {
 /**
  * Запускає `opa check --strict` і `regal lint` по існуючих цілях. Якщо жодної цілі немає —
  * пропускає лінт із кодом 0. Якщо хоча б один preflight не пройшов — exit 1 ще до запусків.
+ *
+ * Внутрішня форма без локу — для тестів, які працюють у тимчасових каталогах і мають
+ * можливість запускати fresh без дедуплікації проти попереднього прогону.
  * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
  * @returns {number} 0 — OK або skip; інакше код виходу першого кроку, що впав
  */
-export function runLintRego(cwd = process.cwd()) {
+export function runLintRegoSteps(cwd = process.cwd()) {
   const root = resolve(cwd)
   const opa = resolveCmd('opa')
   const regal = resolveCmd('regal')
@@ -130,6 +134,12 @@ export function runLintRego(cwd = process.cwd()) {
   return runStep(conftest, ['verify', ...targets.flatMap(t => ['-p', t])], root)
 }
 
+/**
+ * Публічна CLI-форма: серіалізує через `withLock('lint-rego')` + дедуп за станом git-дерева.
+ * @returns {Promise<number>} код виходу
+ */
+export const runLintRego = () => withLock('lint-rego', () => runLintRegoSteps())
+
 if (isRunAsCli()) {
-  process.exitCode = runLintRego()
+  process.exitCode = await runLintRego()
 }

package/rules/text/lint/lint.mjs

@@ -18,6 +18,7 @@ import { platform } from 'node:process'
 
 import { runLintStep } from '../../../scripts/utils/run-lint-step.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { withLock } from '../../../scripts/utils/with-lock.mjs'
 import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
@@ -120,10 +121,10 @@ function preflight(dep) {
 }
 
 /**
- * Виконує канонічний `lint-text` з preflight і ланцюжком cspell → shellcheck → dotenv → markdownlint → v8r.
+ * Внутрішні кроки `lint-text` без локу.
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
-export function runLintTextCli() {
+function runLintTextSteps() {
   let preflightOk = true
   for (const dep of [SHELLCHECK_PREFLIGHT, PATCH_PREFLIGHT, DOTENV_LINTER_PREFLIGHT]) {
     if (!preflight(dep)) preflightOk = false
@@ -147,3 +148,9 @@ export function runLintTextCli() {
   console.log('\n▶ v8r (schema-валідація json/json5/yaml/yml/toml)')
   return runV8rWithGlobs()
 }
+
+/**
+ * Публічна CLI-форма: серіалізує через `withLock('lint-text')` + дедуп за станом git-дерева.
+ * @returns {Promise<number>} код виходу
+ */
+export const runLintTextCli = () => withLock('lint-text', () => runLintTextSteps())

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

@@ -3,12 +3,19 @@
  *
  * Інкапсулює: `discoverOneRule` → `runRule(applies → JS → policy → mdc-refs)`.
  * Локальна логіка в правилах заборонена; розширення поведінки — через `ctx`-опції.
+ *
+ * Серіалізація: загортає виконання у `withLock('fix-<ruleId>')` — паралельні запуски
+ * того самого правила (через `npx @nitra/cursor fix`, прямий `bun rules/<id>/fix.mjs`
+ * чи `run(ctx)`-композицію) дедупляться за станом git-дерева; різні правила можуть
+ * виконуватись паралельно. Точка інтеграції — тут, щоб не дублювати лок у кожному
+ * `fix.mjs`.
  */
 import { basename, dirname } from 'node:path'
 
 import { discoverOneRule } from './discover-checkable-rules.mjs'
 import { runRule } from './run-rule.mjs'
 import { getOrCreateWalkCache } from './walk-cache.mjs'
+import { withLock } from './with-lock.mjs'
 
 /**
  * @typedef {object} RuleContext
@@ -28,7 +35,9 @@ import { getOrCreateWalkCache } from './walk-cache.mjs'
 export async function runStandardRule(ruleDir, ctx = {}) {
   const ruleId = basename(ruleDir)
   const bundledRulesDir = dirname(ruleDir)
-  const rule = await discoverOneRule(ruleDir, ruleId)
-  const walkCache = ctx.walkCache ?? getOrCreateWalkCache()
-  return runRule(rule, bundledRulesDir, walkCache)
+  return withLock(`fix-${ruleId}`, async () => {
+    const rule = await discoverOneRule(ruleDir, ruleId)
+    const walkCache = ctx.walkCache ?? getOrCreateWalkCache()
+    return runRule(rule, bundledRulesDir, walkCache)
+  })
 }

package/scripts/utils/with-lock.mjs

@@ -40,8 +40,8 @@ export function shouldDedup(result, fingerprint, ttl) {
 
 /**
  * @param {string} key
- * @param {() => Promise<number>} runFn
- * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string}} [opts]
+ * @param {() => number | Promise<number>} runFn
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string, getFingerprint?:() => string | null}} [opts]
  * @returns {Promise<number>}
  */
 export async function withLock(key, runFn, opts = {}) {