@7n/test 0.9.0 → 0.10.0

package/src/lib/runtime-probe.mjs

@@ -0,0 +1,390 @@
+/**
+ * Runtime probing of exported functions.
+ *
+ * Three probe strategies — all best-effort (return {} on any failure):
+ *
+ * 1. probeModule  — calls each export with edge-case primitives, returns actual outputs.
+ * 2. probeFetchCalls — intercepts globalThis.fetch to capture real URL/init per export.
+ * 3. probeTimeVariants — runs each export at hours [0,9,14,22], reports time-sensitive ones.
+ * 4. probeHelpers — extracts non-exported helper functions from source and calls them
+ *    with generic param combos to reveal their actual output shapes.
+ */
+import { readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+const PROBE_TIMEOUT_MS = 10_000
+
+/** Generic argument combos to try when probing async/fetch functions. */
+const FETCH_ARG_COMBOS = [
+  ['test text'],
+  ['test text', {}],
+  ['test text', { id: 'test_id' }],
+  ['test text', { chat_id: 'test_id' }],
+  ['test', 'test_id'],
+  [null]
+]
+
+/** Hours sampled for time-variant detection. */
+const PROBE_HOURS = [0, 9, 14, 22]
+
+/** Generic param combos for internal helper introspection. */
+const HELPER_PARAM_COMBOS = [
+  {},
+  { id: 'test_id' },
+  { chat_id: 'custom' },
+  { silent: true },
+  { parse_mode: 'HTML' },
+  { chat_id: 'custom', parse_mode: 'MarkdownV2', silent: true }
+]
+
+/**
+ * Edge-case inputs used for all function probes.
+ * Each entry: [jsLiteral, displayRepr]
+ */
+const PROBE_INPUTS = [
+  ['null', 'null'],
+  ['undefined', 'undefined'],
+  ['""', '""'],
+  ['"*"', '"*"'],
+  ['"_"', '"_"'],
+  ['"["', '"["'],
+  ['"]"', '"]"'],
+  ['"("', '"("'],
+  ['")"', '")"'],
+  ['"~"', '"~"'],
+  ['"`"', '"`"'],
+  ['">"', '">"'],
+  ['"#"', '"#"'],
+  ['"+"', '"+"'],
+  ['"-"', '"-"'],
+  ['"="', '"="'],
+  ['"|"', '"|"'],
+  ['"{"', '"{"'],
+  ['"}"', '"}"'],
+  ['"."', '"."'],
+  ['"!"', '"!"'],
+  [String.raw`"\\"`, String.raw`"\\"`],
+  ['"hello"', '"hello"'],
+  ['"hello world"', '"hello world"'],
+  ['0', '0'],
+  ['42', '42']
+]
+
+/**
+ * Пробує експорти модуля у дочірньому процесі й повертає фактичні виходи.
+ * @param {string} absFilePath абсолютний шлях до джерела модуля
+ * @param {string[]} exportedNames назви експортів для probing
+ * @param {string[]} [envKeys] ключі env, які треба підставити test-значеннями; за замовчуванням порожній список
+ * @returns {Record<string, Array<{input: string, output: string}> | {constant: string}>} фактичні probe-результати для кожного export
+ */
+export function probeModule(absFilePath, exportedNames, envKeys = []) {
+  const envStubs = envKeys.map(k => `process.env[${JSON.stringify(k)}] = '__probe__'`).join('\n')
+
+  const script = `
+import { createRequire } from 'node:module'
+${envStubs}
+globalThis.fetch = async () => ({ status: 200, json: async () => ({}) })
+
+const probeInputs = ${JSON.stringify(PROBE_INPUTS)}
+const names = ${JSON.stringify(exportedNames)}
+const filePath = ${JSON.stringify(absFilePath)}
+
+let mod
+try {
+  mod = await import(filePath)
+} catch (e) {
+  process.stdout.write(JSON.stringify({ __importError: e.message }))
+  process.exit(0)
+}
+
+const results = {}
+for (const name of names) {
+  const val = mod[name]
+  if (typeof val === 'function') {
+    results[name] = []
+    for (const [inputLiteral, repr] of probeInputs) {
+      let input
+      // safe eval of primitive literals
+      try { input = new Function('return ' + inputLiteral)() } catch { continue }
+      try {
+        const out = await Promise.resolve(val(input))
+        if (out !== undefined) {
+          results[name].push({ input: repr, output: JSON.stringify(out) })
+        }
+      } catch {
+        // skip — function threw on this input
+      }
+    }
+  } else if (val !== undefined) {
+    try { results[name] = { constant: JSON.stringify(val) } } catch { /* skip non-serializable */ }
+  }
+}
+process.stdout.write(JSON.stringify(results))
+`
+
+  const proc = spawnSync('node', ['--input-type=module'], {
+    input: script,
+    encoding: 'utf8',
+    timeout: PROBE_TIMEOUT_MS,
+    env: { ...process.env }
+  })
+
+  if (!proc.stdout) return {}
+  try {
+    const parsed = JSON.parse(proc.stdout)
+    if (parsed.__importError) return {}
+    return parsed
+  } catch {
+    return {}
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: run an isolated node ESM script and parse JSON stdout
+// ---------------------------------------------------------------------------
+
+/**
+ * Запускає ізольований node ESM script і парсить JSON зі stdout.
+ * @param {string} script код для виконання
+ * @param {number} [timeout] ліміт очікування в мс; за замовчуванням `PROBE_TIMEOUT_MS`
+ * @returns {Record<string, unknown> | null} розпарсений JSON або `null` при помилці
+ */
+function runProbeScript(script, timeout = PROBE_TIMEOUT_MS) {
+  const proc = spawnSync('node', ['--input-type=module'], {
+    input: script,
+    encoding: 'utf8',
+    timeout,
+    env: { ...process.env }
+  })
+  if (!proc.stdout) return null
+  try {
+    const parsed = JSON.parse(proc.stdout)
+    return parsed.__importError ? null : parsed
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Probe 2: fetch-capture
+// ---------------------------------------------------------------------------
+
+/**
+ * Перехоплює `fetch` і збирає реальні URL/init, які будує кожен export.
+ * @param {string} absFilePath абсолютний шлях до джерела модуля
+ * @param {string[]} exportedNames назви експортів для probing
+ * @param {string[]} [envKeys] env-ключі, які треба підмінити `test_value`; за замовчуванням порожній список
+ * @returns {Record<string, Array<{args: string, url: string, init: unknown}>>} зібрані fetch-виклики по export
+ */
+export function probeFetchCalls(absFilePath, exportedNames, envKeys = []) {
+  const envStubs = envKeys.map(k => `process.env[${JSON.stringify(k)}] = 'test_value'`).join('\n')
+
+  const script = `
+${envStubs}
+const __calls = []
+globalThis.fetch = async (url, init) => {
+  __calls.push({ url: String(url), init: init ?? null })
+  return { status: 200, json: async () => ({}) }
+}
+
+let mod
+try { mod = await import(${JSON.stringify(absFilePath)}) }
+catch (e) { process.stdout.write(JSON.stringify({ __importError: e.message })); process.exit(0) }
+
+const argCombos = ${JSON.stringify(FETCH_ARG_COMBOS)}
+const results = {}
+
+for (const name of ${JSON.stringify(exportedNames)}) {
+  const fn = mod[name]
+  if (typeof fn !== 'function') continue
+  for (const args of argCombos) {
+    __calls.length = 0
+    try { await Promise.resolve(fn(...args)) } catch { /* ignore */ }
+    if (__calls.length > 0) {
+      results[name] = __calls.map(c => ({ args: JSON.stringify(args), url: c.url, init: c.init }))
+      break
+    }
+  }
+}
+process.stdout.write(JSON.stringify(results))
+`
+  return runProbeScript(script) ?? {}
+}
+
+// ---------------------------------------------------------------------------
+// Probe 3: time-variant detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Запускає кожен export у кількох годинах доби й повертає time-sensitive варіанти.
+ * @param {string} absFilePath абсолютний шлях до джерела модуля
+ * @param {string[]} exportedNames назви експортів для probing
+ * @param {string[]} [envKeys] env-ключі, які треба підмінити `test_value`; за замовчуванням порожній список
+ * @returns {Record<string, Record<number, string>>} лише exports, чий вихід змінюється залежно від години
+ */
+export function probeTimeVariants(absFilePath, exportedNames, envKeys = []) {
+  const envStubs = envKeys.map(k => `process.env[${JSON.stringify(k)}] = 'test_value'`).join('\n')
+
+  // Use generic arg combos (same as fetch probe) to get meaningful calls
+  const script = `
+${envStubs}
+
+let mod
+try { mod = await import(${JSON.stringify(absFilePath)}) }
+catch (e) { process.stdout.write(JSON.stringify({ __importError: e.message })); process.exit(0) }
+
+const hours = ${JSON.stringify(PROBE_HOURS)}
+const argCombos = ${JSON.stringify(FETCH_ARG_COMBOS)}
+const results = {}
+
+for (const name of ${JSON.stringify(exportedNames)}) {
+  const fn = mod[name]
+  if (typeof fn !== 'function') continue
+  const byHour = {}
+  for (const h of hours) {
+    const fixedMs = new Date('2024-01-15T00:00:00').setHours(h, 0, 0, 0)
+    const Orig = globalThis.Date
+    globalThis.Date = class FakeDate extends Orig {
+      constructor(...a) { super(...(a.length ? a : [fixedMs])) }
+      static now() { return fixedMs }
+    }
+    Object.setPrototypeOf(globalThis.Date, Orig)
+    // Capture fetch URL (more informative than return value for side-effectful fns)
+    let captured = null
+    globalThis.fetch = async (url) => { captured = String(url); return { status: 200, json: async () => ({}) } }
+    try {
+      for (const args of argCombos) {
+        captured = null
+        try { await Promise.resolve(fn(...args)) } catch { /* ignore */ }
+        if (captured) break
+      }
+      byHour[h] = captured ?? '__no_fetch__'
+    } catch {
+      byHour[h] = '__error__'
+    } finally {
+      globalThis.Date = Orig
+    }
+  }
+  // Report only functions where fetch URL changes across hours
+  const fetched = Object.values(byHour).filter(v => v !== '__no_fetch__' && v !== '__error__')
+  if (fetched.length > 0 && new Set(fetched).size > 1) results[name] = byHour
+}
+process.stdout.write(JSON.stringify(results))
+`
+  return runProbeScript(script) ?? {}
+}
+
+// ---------------------------------------------------------------------------
+// Probe 4: internal helper introspection
+// ---------------------------------------------------------------------------
+
+/**
+ * Знаходить початок top-level declaration для helper-а в source.
+ * @param {string} source текст модуля
+ * @param {string} name назва helper-а
+ * @returns {number} індекс початку або `-1`, якщо declaration не знайдено
+ */
+function findDeclarationStart(source, name) {
+  const prefixes = [`const ${name} =`, `let ${name} =`, `var ${name} =`, `function ${name}(`, `async function ${name}(`]
+  let start = -1
+  for (const prefix of prefixes) {
+    const direct = source.indexOf(prefix)
+    if (direct !== -1 && (start === -1 || direct < start)) start = direct
+    const lineStart = source.indexOf(`\n${prefix}`)
+    if (lineStart !== -1) {
+      const candidate = lineStart + 1
+      if (start === -1 || candidate < start) start = candidate
+    }
+  }
+  return start
+}
+
+/**
+ * Знаходить межу до наступної top-level declaration.
+ * @param {string} sourceTail текст після declaration
+ * @returns {number} індекс межі або `-1`, якщо наступної declaration немає
+ */
+function findNextDeclarationEnd(sourceTail) {
+  const markers = ['\nconst ', '\nlet ', '\nvar ', '\nfunction ', '\nasync function ', '\nexport ']
+  let end = -1
+  for (const marker of markers) {
+    const idx = sourceTail.indexOf(marker)
+    if (idx !== -1 && (end === -1 || idx < end)) end = idx
+  }
+  return end
+}
+
+/**
+ * Витягує top-level declaration helper-а з source.
+ * @param {string} source текст модуля
+ * @param {string} name назва helper-а
+ * @param {number} [maxLength] максимальна довжина fallback-сніпета; за замовчуванням `800`
+ * @returns {string|null} сніпет helper-а або `null`, якщо declaration не знайдено
+ */
+function extractHelperSource(source, name, maxLength = 800) {
+  const start = findDeclarationStart(source, name)
+  if (start === -1) return null
+  const after = source.slice(start)
+  const next = findNextDeclarationEnd(after)
+  return after.slice(0, next === -1 ? Math.min(after.length, maxLength) : next)
+}
+
+/**
+ * Витягує неекспортовані helper-и з source та проганяє їх крізь generic param combos.
+ * Best-effort: повертає `{}` при будь-якій помилці.
+ * @param {string} absFilePath абсолютний шлях до source-модуля
+ * @param {string[]} helperNames назви internal (non-exported) helper-ів
+ * @param {string[]} [envKeys] env-ключі, які треба підмінити `test_value`; за замовчуванням порожній список
+ * @returns {Record<string, Array<{params: Record<string, unknown>, result: unknown}>>} результати probe для кожного helper-а
+ */
+export function probeHelpers(absFilePath, helperNames, envKeys = []) {
+  if (!helperNames.length) return {}
+
+  let source
+  try {
+    source = readFileSync(absFilePath, 'utf8')
+  } catch {
+    return {}
+  }
+
+  const extracted = {}
+  for (const name of helperNames) {
+    const snippet = extractHelperSource(source, name)
+    if (snippet) extracted[name] = snippet
+  }
+
+  if (Object.keys(extracted).length === 0) return {}
+
+  const envStubs = envKeys.map(k => `process.env[${JSON.stringify(k)}] = 'test_value'`).join('\n')
+  const helperDefs = Object.values(extracted).join('\n\n')
+  const combos = JSON.stringify(HELPER_PARAM_COMBOS)
+  const names = JSON.stringify(Object.keys(extracted))
+
+  const script = `
+import { env } from 'node:process'
+${envStubs}
+
+${helperDefs}
+
+const combos = ${combos}
+const results = {}
+for (const name of ${names}) {
+  const fns = { ${Object.keys(extracted)
+    .map(n => `${n}: typeof ${n} !== 'undefined' ? ${n} : null`)
+    .join(', ')} }
+  const fn = fns[name]
+  if (typeof fn !== 'function') continue
+  results[name] = []
+  for (const params of combos) {
+    try {
+      const r = fn(params)
+      results[name].push({ params, result: JSON.parse(JSON.stringify(r)) })
+    } catch {
+      // helper threw on this combo — skip
+    }
+  }
+}
+process.stdout.write(JSON.stringify(results))
+`
+  return runProbeScript(script) ?? {}
+}

package/src/lib/vitest-shim.mjs

@@ -0,0 +1,73 @@
+/**
+ * Shared bundled-vitest utilities.
+ *
+ * Target projects do NOT need vitest installed — we use the vitest bundled
+ * with `@7n/test` as a fallback, with a shim config so the run works even
+ * without a vitest.config.js in the target project. When the target DOES
+ * have vitest installed locally, its own binary is preferred instead: that
+ * resolves the target's `vitest.config.*` (setupFiles, environment, plugins,
+ * nested per-package configs) and third-party environment providers (e.g.
+ * `happy-dom`) from the target's own `node_modules`, which the bundled copy
+ * cannot see.
+ */
+import { createRequire } from 'node:module'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const _require = createRequire(import.meta.url)
+const _bundledVitestPkg = _require.resolve('vitest/package.json')
+const _bundledVitestDir = dirname(_bundledVitestPkg)
+
+/** Absolute path to the bundled vitest CLI (fallback when the target has no local vitest). */
+export const VITEST_BIN = join(_bundledVitestDir, 'vitest.mjs')
+
+/** Absolute path to the bundled vitest/config entry (for use in shim import). */
+const VITEST_CONFIG_ENTRY = join(_bundledVitestDir, 'dist', 'config.js')
+
+/**
+ * Minimal vitest config written to OS temp, imported by the bundled vitest.
+ * Using file:// URL so the import resolves from 7n-test's node_modules,
+ * not from the target project's (possibly absent) vitest installation.
+ */
+export const VITEST_SHIM_CONFIG = join(tmpdir(), '7n-vitest-shim', 'vitest.config.mjs')
+
+let _shimWritten = false
+
+/** Ensures the bundled-vitest shim config file exists (idempotent). */
+export function ensureVitestShim() {
+  if (_shimWritten) return
+  mkdirSync(dirname(VITEST_SHIM_CONFIG), { recursive: true })
+  writeFileSync(
+    VITEST_SHIM_CONFIG,
+    `import { defineConfig } from ${JSON.stringify('file://' + VITEST_CONFIG_ENTRY)}\n` +
+      `export default defineConfig({\n` +
+      `  test: { environment: 'node' },\n` +
+      `  coverage: {\n` +
+      `    provider: 'v8',\n` +
+      // Exclude test files that use non-vitest runners (bun:test, jest) from
+      // the coverage scan so they don't cause import errors or skewed data.
+      `    exclude: ['**/node_modules/**'],\n` +
+      `  },\n` +
+      `})\n`
+  )
+  _shimWritten = true
+}
+
+/**
+ * Resolves which vitest binary and extra CLI args to run for a target project.
+ * Prefers the target's own locally-installed vitest (native config discovery,
+ * dependencies resolved from its own node_modules); falls back to the bundled
+ * vitest + shim config when the target has no local vitest installed.
+ * @param {string} dir target project root
+ * @returns {{ bin: string, configArgs: string[] }} vitest bin path and `--config` args to prepend
+ */
+export function resolveVitestRun(dir) {
+  try {
+    const localPkg = _require.resolve('vitest/package.json', { paths: [dir] })
+    return { bin: join(dirname(localPkg), 'vitest.mjs'), configArgs: [] }
+  } catch {
+    ensureVitestShim()
+    return { bin: VITEST_BIN, configArgs: ['--config', VITEST_SHIM_CONFIG] }
+  }
+}

package/src/run.mjs

@@ -62,7 +62,9 @@ export async function runAutoTest(dir, opts = {}) {
           try {
             const q = quickClassify(readFileSync(join(dir, f), 'utf8'))
             if (q?.needsTests === false) return null
-          } catch { /* include on read error */ }
+          } catch {
+            /* include on read error */
+          }
           return { file: f, pct: 0 }
         })
         .filter(Boolean)

package/src/scripts/lib/changed-files.mjs

@@ -1,7 +1,7 @@
 /**
  * Збір змінених файлів для quick-режиму lint-оркестратора.
  *
- * Quick лінтить лише те, що змінено в робочому дереві: tracked-modified + staged
+ * Quick перевіряє лише те, що змінено в робочому дереві: tracked-modified + staged
  * (`git diff HEAD`) і нові untracked (`git ls-files --others --exclude-standard`).
  * Видалені файли не повертаються. Поза git-репо або при помилці git — порожній список.
  */
@@ -49,12 +49,12 @@ export function resolveChangedBase(cwd = process.cwd()) {
 }
 
 /**
- * Список змінених + untracked файлів **відносно базового комміту**.
+ * Список змінених + untracked файлів **відносно базового коміту**.
  *
  * `git diff <base>` (без `..`/`...`, без `HEAD`) порівнює base-комміт із поточним
- * **робочим деревом** — тобто однаково ловить і закомічене від base, і staged, і
+ * **робочим деревом** — тобто однаково ловить і зафіксоване від base, і staged, і
  * незакомічені модифікації. Це гарантує однакову поведінку незалежно від того, чи
- * зміни вже закомічені у worktree. Без `base` — fallback на `collectChangedFiles`
+ * зміни вже зафіксовані у worktree. Без `base` — fallback на `collectChangedFiles`
  * (робоче дерево vs HEAD).
  * @param {string|null} [base] базовий комміт
  * @param {string} [cwd] корінь репо
@@ -64,7 +64,7 @@ export function collectChangedFilesSince(base, cwd = process.cwd()) {
   if (!base) return collectChangedFiles(cwd)
   // Fail-closed: недосяжний base (rebase/force-update/shallow prune) інакше дав би `git diff`
   // exit 128 → порожній список → gate мовчки пройшов би без перевірки. Краще явна помилка.
-  const verify = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd, encoding: 'utf8' })
+  const verify = spawnSync('git', ['rev-parse', '--verify', '--quiet', base + '^{commit}'], { cwd, encoding: 'utf8' })
   if (verify.status !== 0 || verify.error) {
     throw new Error(
       `collectChangedFilesSince: base-комміт «${base}» недосяжний у ${cwd} ` +

package/src/scripts/lib/docs/changed-files.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: changed-files.mjs
+resource: npm/src/scripts/lib/changed-files.mjs
+docgen:
+  crc: 55da635c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл відповідає за збір списків шляхів до файлів, що були змінені або додані у робочому дереві. Він забезпечує механізм для quick-режиму lint-оркестратора, ідентифікуючи змінений контент відносно останнього коміту (`HEAD`) (tracked-modified + staged) та нових невідстежених файлів (`git ls-files --others --exclude-standard`). Видалені файли не повертаються. У випадку роботи поза Git-репозиторієм або при помилці Git, повертається порожній список.
+
+## Поведінка
+
+Поведінка
+collectChangedFiles збирає унікальний список шляхів до файлів, які були змінені або додані у робочому дереві відносно `HEAD`, включаючи нові відстежувані та невідстежувані файли.
+resolveChangedBase визначає базовий коміт для обмежених перевірок, шукаючи `main` або `origin/main` як точку відліку.
+collectChangedFilesSince збирає унікальний список шляхів до файлів, які змінилися або були додані порівняно з заданим базовим комітом, або викликає `collectChangedFiles` у випадку відсутності базового коміту.
+
+## Публічний API
+
+collectChangedFiles — надає список файлів, які були змінені або додані в робоче дерево.
+resolveChangedBase — визначає точку відліку для порівняння змін, пріоритезуючи `main` локальної гілки, потім `origin/main`; якщо вони відсутні, порівнює робоче дерево з поточним HEAD.
+collectChangedFilesSince — надає список файлів, які відрізняються від зазначеного базового коміту.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -0,0 +1,39 @@
+---
+type: JS Module
+title: read-n-cursor-config-lite.mjs
+resource: npm/src/scripts/lib/read-n-cursor-config-lite.mjs
+docgen:
+  crc: a38ac2f4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Модуль забезпечує мінімалістичний, read-only доступ до конфігурації `.n-cursor.json`. Він дозволяє зовнішнім інструментам (наприклад, для debug-тестування) зчитувати стан набору правил, не ініціалізуючи повний CLI. Відсутність `.n-cursor.json` трактується як режим "open by default", активуючи всі правила. Якщо файл присутній, правила можуть бути активні лише у списку `rules`, але їхня активація анулюється, якщо правило міститься у списку `disable-rules`. Функції надають значення `rules` та `disableRules` з конфігу.
+
+## Поведінка
+
+readNCursorConfigLite читає вміст файлу .n-cursor.json у вказаному каталозі, якщо такий файл існує; повертає об'єкт, що описує, чи існує конфігурація, які правила явно включені в `rules` та які правила вимкнено у `disableRules`.
+isRuleEnabled визначає, чи активне певне правило на основі прочитаного конфігу; якщо файл .n-cursor.json відсутній, правило вважається активним.
+
+## Публічний API
+
+I understand. As a technical writer, I will generate concise behavioral documentation in Ukrainian, adhering strictly to the specified constraints: clean Markdown, focusing on _What_ and _Why_ (not _How_), no introductions or conclusions, no code blocks, and excluding signatures, types, parameters, `stdlib` modules, regex descriptions, or private internal names.
+
+I must use the exact names provided for the functions in the bulleted list, transforming them into short, intent-driven descriptions.
+
+Here is the required output format:
+
+- `readNCursorConfigLite` — [Concise description of the file's purpose/action]
+- `isRuleEnabled` — [Concise description based on the configuration logic provided]
+
+I will ensure the anchors point to `.n-cursor.json` and avoid generic filler phrases.
+
+Please provide the code or context you want me to document.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/scripts/utils/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/src/scripts/utils
+resource: npm/src/scripts/utils/
+---
+
+# npm/src/scripts/utils
+
+| Файл                                                | Тип       |
+| --------------------------------------------------- | --------- |
+| [lock-cache-dir.mjs](lock-cache-dir.md)             | JS Module |
+| [with-lock.mjs](with-lock.md)                       | JS Module |
+| [worktree-fingerprint.mjs](worktree-fingerprint.md) | JS Module |

package/src/scripts/utils/docs/lock-cache-dir.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: lock-cache-dir.mjs
+resource: npm/src/scripts/utils/lock-cache-dir.mjs
+docgen:
+  crc: 76c84505
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль визначає уніфікований, спільний шлях для кешування лок-станів (`owner.json`, `result.json`) у всіх git-worktree. При наявності git-репозиторію, лок-стан розміщується у спільному каталозі `<git-common-dir>/n-cursor/<key>` (всередині `.git`), що забезпечує, щоб ресурсомісткі команди, запущені в різних worktree (наприклад, eslint), серіалізувалися та уникнули паралельного перевантаження CPU/диск на macOS. У разі відсутності git-репозиторію, використовується історичний fallback у per-checkout `node_modules/.cache/n-cursor/<key>`.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається функція resolveLockCacheDir з ключем локу.
+2. Функція з'ясовує робочу директорію.
+3. Виконується команда `git rev-parse --git-common-dir` у робочій директорії для визначення спільної директорії git-репозиторію.
+4. Якщо команда Git не спрацювала або не повернула шлях, функція повертає шлях до локального кешу (`node_modules/.cache/n-cursor/<key>`) у поточній робочій директорії.
+5. Якщо спірна директорія була знайдена, функція обчислює та повертає абсолютний шлях до кешу (`<git-common-dir>/n-cursor/<key>`) у корені репозиторію.
+6. Функція не модифікує файлову систему; вона лише обчислює шлях для кешування лок-станів (таких як `owner.json` та `result.json`) для забезпечення серіалізації важких команд між різними git-worktree.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/src/scripts/utils/docs/with-lock.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: with-lock.mjs
+resource: npm/src/scripts/utils/with-lock.mjs
+docgen:
+  crc: f6c6a780
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл реалізує механізм гарантування атомарності та уникнення повторного виконання (dedup) для ресурсомістких операцій. Він забезпечує, щоб важкі команди виконувалися лише один раз протягом встановленого терміну дії, якщо їхній результат збережений. Система спирається на конфігурації `owner.json` та `result.json` для керування станом блокування та кешу.
+
+Цей файл забезпечує атомарне виконання складних команд. Це досягається за допомогою механізму блокування, що базується на створенні директорії (`mkdirSync-based lock`), та валідації живості PID. Для уникнення повторних викликів використовується deduplication на основі хешу SHA256 з обмеженим часом життя (TTL), що дозволяє використовувати кешований результат.
+
+## Поведінка
+
+shouldDedup перевіряє, чи можна повторно використати збережений результат, порівнюючи його з поточним відбитком робочого дерева та перевіряючи термін дії кешу.
+
+withLock виконує важку команду, гарантуючи її атомарність за допомогою механізму блокування. Перед виконанням він перевіряє кеш, а після завершення зберігає результат для майбутньої дедуплікації.
+
+## Публічний API
+
+Зрозумів. Я буду діяти як технічний письменник, створюючи лаконічну поведінкову документацію на українській мові у чистому Markdown. Я дотримуватимуся всіх обмежень: лише "ЩО" і "НАВІЩО", без вступів/висновків, без ```-блоків, без сигнатур/типів/параметрів/stdlib-модулів/regex/приватних імен.
+
+Я інтегрую прив'язку до конфігів `owner.json` та `result.json`.
+
+Для наданого списку я перетворю його на стислі маркери у форматі «назва — що робить», використовуючи власні слова, без типів і сигнатур, та використовуючи надані назви:
+
+- shouldDedup — Визначає, чи можна ігнорувати повторне виконання, якщо результат вже є у кешованому `result.json`.
+- withLock — Гарантує послідовне виконання ресурсомісткої операції за допомогою атомарної блокировки, а також усуває дублікати за унікальним ідентифікатором (fingerprint).
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.