@nitra/cursor 1.13.84 → 1.13.87

package/CHANGELOG.md

@@ -4,6 +4,38 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.87] - 2026-05-23
+
+### Added
+
+- **`scripts/utils/run-standard-lint.mjs`** — спільна точка входу для всіх `lint-<rule>` підкоманд, дзеркально до `runStandardRule` для `fix-<id>`. Виводить ключ локу зі шляху (`basename(dirname(lintDir))`) і прокидає `opts` у `withLock`. Місце для майбутніх крос-cutting розширень (телеметрія, env-toggle вимкнення локу, common preflight-логування) — патчиш одне місце, не 5 файлів.
+
+### Changed
+
+- **5 `rules/<rule>/lint/lint.mjs` (ga, rego, text, k8s, docker)** більше не імпортують `withLock` напряму — використовують `runStandardLint(import.meta.dirname, runLint<Foo>Steps)`. Ім'я правила в одному місці — у каталозі.
+- **`.cursor/rules/scripts.mdc` 1.9 → 1.10:** канон патерну переписано на `runStandardLint` (а не прямий `withLock`); додано явну заборону імпортувати `withLock` у `rules/<rule>/lint/lint.mjs`. У кожному з 5 lint.mjs у top-JSDoc додано посилання «Канон патерну `lint-*` — `.cursor/rules/scripts.mdc`».
+
+## [1.13.86] - 2026-05-23
+
+### Fixed
+
+- **`worktreeFingerprint` повертав `null` при untracked-файлах з не-ASCII іменами:** `git ls-files --others --exclude-standard` без `-z` повертає такі шляхи у C-escape виді (`"docs/adr/20260523-...кирилиця..."` з `\321\201`-послідовностями), і наступний `git hash-object <escaped>` не знаходить файл — увесь fingerprint падав у `null`, через що дедуп ніколи не спрацьовував у репах з кирилицею в untracked-іменах. Перехід на `-z` + `\0`-розбиття дає сирий байтовий шлях.
+
+## [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.87",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/docker/lint/lint.mjs

@@ -6,6 +6,9 @@
  * Dockerfile та варіанти виду app.Dockerfile (регістр суфікса не важливий).
  *
  * Виклик hadolint — через ../js/lint/docker-hadolint.mjs (PATH або docker run).
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { basename } from 'node:path'
 
@@ -14,6 +17,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 { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /**
  * Чи входить файл до набору lint-docker: Dockerfile або *.Dockerfile (*.dockerfile).
@@ -46,11 +50,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 +83,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 = () => runStandardLint(import.meta.dirname, runLintDockerSteps)
+
 if (isRunAsCli()) {
   process.exitCode = await runLintDocker()
 }

package/rules/ga/lint/lint.mjs

@@ -23,13 +23,16 @@
  * локально це виглядало як мовчазний exit 1.
  *
  * Експортовано окремо `runLintGaCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-ga`.
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { platform } from 'node:process'
 
 import { check as checkGa } from '../js/workflows/check.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runLintStep } from '../../../scripts/utils/run-lint-step.mjs'
-import { withLock } from '../../../scripts/utils/with-lock.mjs'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /**
  * Опис залежності preflight-ом: бінарник, для чого потрібен, і команди встановлення.
@@ -165,4 +168,4 @@ async function runLintGaSteps() {
   return await checkGa()
 }
 
-export const runLintGaCli = () => withLock('lint-ga', runLintGaSteps)
+export const runLintGaCli = () => runStandardLint(import.meta.dirname, runLintGaSteps)

package/rules/k8s/lint/lint.mjs

@@ -11,6 +11,9 @@
  *
  * Версія `-kubernetes-version` для kubeconform узгоджена з PIN yannh у rules/k8s/fix.mjs / k8s.mdc.
  * Kubescape не має аналога цього прапорця; орієнтир цільового кластера — та сама лінія релізу (див. k8s.mdc).
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -24,6 +27,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 { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /** Per-project kubescape exceptions file; підмішується через --exceptions, якщо існує в корені. */
 const KUBESCAPE_EXCEPTIONS_FILE = '.kubescape-exceptions.json'
@@ -320,11 +324,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 +347,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 = () => runStandardLint(import.meta.dirname, runLintK8sSteps)
+
 if (isRunAsCli()) {
   process.exitCode = await runLintK8s()
 }

package/rules/rego/lint/lint.mjs

@@ -22,6 +22,9 @@
  * `npm/rules/<id>/policy/<concern>/`). Усі три інструменти приймають один шлях
  * і самі рекурсивно знаходять `.rego` (ігноруючи інші розширення на кшталт
  * `target.json` чи template-фіх).
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
@@ -29,6 +32,7 @@ import { resolve } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /** Шляхи з Rego-полісі (відносно cwd). Існують не всі на ранніх стадіях — фільтруємо нижче. */
 const LINT_TARGETS = ['npm/rules']
@@ -89,10 +93,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 +137,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 = () => runStandardLint(import.meta.dirname, () => runLintRegoSteps())
+
 if (isRunAsCli()) {
-  process.exitCode = runLintRego()
+  process.exitCode = await runLintRego()
 }

package/rules/text/lint/lint.mjs

@@ -13,11 +13,15 @@
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
  * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { platform } from 'node:process'
 
 import { runLintStep } from '../../../scripts/utils/run-lint-step.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
@@ -120,10 +124,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 +151,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 = () => runStandardLint(import.meta.dirname, () => runLintTextSteps())

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

@@ -0,0 +1,35 @@
+/**
+ * Спільна точка входу для канонічних `lint-<rule>` підкоманд `@nitra/cursor`.
+ *
+ * Дзеркально до `runStandardRule` для `fix-<id>`: усі `lint-*` проходять через одну функцію,
+ * щоб майбутні крос-cutting концерни (телеметрія, env-toggle вимкнення локу для дебагу,
+ * dry-run-режим, common preflight-логування тощо) додавались **в одному** місці, а не
+ * патчилися в кожному `rules/<rule>/lint/lint.mjs`.
+ *
+ * Зараз робить рівно одне: серіалізує + дедуплікує запуски через `withLock('lint-<ruleId>')`.
+ * `ruleId` виводиться зі шляху: `import.meta.dirname` у `rules/<id>/lint/lint.mjs` → `<id>`.
+ *
+ * Інтеграція з боку правила:
+ *
+ * ```js
+ * import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
+ *
+ * async function runLintFooSteps() { ... }
+ *
+ * export const runLintFooCli = () => runStandardLint(import.meta.dirname, runLintFooSteps)
+ * ```
+ */
+import { basename, dirname } from 'node:path'
+
+import { withLock } from './with-lock.mjs'
+
+/**
+ * @param {string} lintDir абсолютний шлях до `rules/<id>/lint/` (передавай `import.meta.dirname`)
+ * @param {() => number | Promise<number>} stepsFn реальна робота лінту; повертає код виходу
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string, getFingerprint?:() => string | null}} [opts] прокидаються у `withLock`
+ * @returns {Promise<number>} код виходу
+ */
+export function runStandardLint(lintDir, stepsFn, opts) {
+  const ruleId = basename(dirname(lintDir))
+  return withLock(`lint-${ruleId}`, stepsFn, opts)
+}

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 = {}) {

package/scripts/utils/worktree-fingerprint.mjs

@@ -17,8 +17,10 @@ export function worktreeFingerprint(spawn = spawnSync) {
   try {
     const commitHash = git(['rev-parse', 'HEAD']).trim()
     const diffText = git(['diff', 'HEAD'])
-    const untrackedRaw = git(['ls-files', '--others', '--exclude-standard'])
-    const untrackedFiles = untrackedRaw.split('\n').filter(Boolean)
+    // -z: NUL-розділення без C-екранування. Без нього імена з не-ASCII символами
+    // повертаються у `"..."` формі, і `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()