@nitra/cursor 1.17.0 → 1.17.1

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,7 +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 {