@nitra/cursor 1.13.85 → 1.13.87

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 Формат — [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.85",
+  "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,7 +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 { withLock } from '../../../scripts/utils/with-lock.mjs'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /**
  * Чи входить файл до набору lint-docker: Dockerfile або *.Dockerfile (*.dockerfile).
@@ -85,7 +88,7 @@ async function runLintDockerSteps() {
  * Експортовано як `runLintDocker` — використовується з `bin/n-cursor.js` як підкоманда `lint-docker`.
  * @returns {Promise<number>} код виходу
  */
-export const runLintDocker = () => withLock('lint-docker', runLintDockerSteps)
+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,7 +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 { withLock } from '../../../scripts/utils/with-lock.mjs'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /** Per-project kubescape exceptions file; підмішується через --exceptions, якщо існує в корені. */
 const KUBESCAPE_EXCEPTIONS_FILE = '.kubescape-exceptions.json'
@@ -349,7 +352,7 @@ async function runLintK8sSteps() {
  * Експортовано як `runLintK8s` — використовується з `bin/n-cursor.js` як підкоманда `lint-k8s`.
  * @returns {Promise<number>} код виходу
  */
-export const runLintK8s = () => withLock('lint-k8s', runLintK8sSteps)
+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,7 +32,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'
+import { runStandardLint } from '../../../scripts/utils/run-standard-lint.mjs'
 
 /** Шляхи з Rego-полісі (відносно cwd). Існують не всі на ранніх стадіях — фільтруємо нижче. */
 const LINT_TARGETS = ['npm/rules']
@@ -138,7 +141,7 @@ export function runLintRegoSteps(cwd = process.cwd()) {
  * Публічна CLI-форма: серіалізує через `withLock('lint-rego')` + дедуп за станом git-дерева.
  * @returns {Promise<number>} код виходу
  */
-export const runLintRego = () => withLock('lint-rego', () => runLintRegoSteps())
+export const runLintRego = () => runStandardLint(import.meta.dirname, () => runLintRegoSteps())
 
 if (isRunAsCli()) {
   process.exitCode = await runLintRego()

package/rules/text/lint/lint.mjs

@@ -13,12 +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 { withLock } from '../../../scripts/utils/with-lock.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'
@@ -153,4 +156,4 @@ function runLintTextSteps() {
  * Публічна CLI-форма: серіалізує через `withLock('lint-text')` + дедуп за станом git-дерева.
  * @returns {Promise<number>} код виходу
  */
-export const runLintTextCli = () => withLock('lint-text', () => runLintTextSteps())
+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/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()