@7n/test 0.8.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

@@ -1,10 +1,10 @@
 /**
- * Main auto-test loop: coverage → assess → gen-tests → loop until max → mutation + fix.
+ * Main auto-test loop: coverage → gen-tests → loop until max → mutation + fix.
  *
  * Phase 1 (loop, max 5 iterations):
  *   1. Measure per-file line coverage via vitest+lcov.
- *   2. pi CLI assesses which uncovered files actually need tests.
- *   3. pi agent generates tests for those files.
+ *   2. Generate tests for all files below threshold — coverage % is the signal.
+ *   3. Bootstrap: when no tests exist, scan sources and quickClassify locally.
  *   4. Repeat until coverage maxes out or no improvement.
  *
  * Phase 2:
@@ -12,11 +12,13 @@
  *   6. Auto-fix survived mutants via pi agent.
  */
 import { measureCoveragePerFile, getUncoveredFiles, findSourceFiles } from './coverage-per-file.mjs'
-import { assessNeed } from './assess-need.mjs'
+import { quickClassify } from './assess-need.mjs'
 import { generateTests } from './gen-tests.mjs'
 import { fixFailingTests } from './fix-tests.mjs'
 import { runCoverageSteps } from './coverage/coverage.mjs'
 import { withLock } from './scripts/utils/with-lock.mjs'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 const MAX_ITERATIONS = 5
 const COVERAGE_THRESHOLD = 80
@@ -53,17 +55,28 @@ export async function runAutoTest(dir, opts = {}) {
         console.log('⚠ Vitest coverage не повернула даних — перевір налаштування vitest.')
         break
       }
-      console.log(`\n── Bootstrap: ${sourceFiles.length} файлів без тестів — оцінюю потребу ──\n`)
-      const bootstrapFiles = sourceFiles.map(f => ({ file: f, pct: 0 }))
-      const assessed = await assessNeed(bootstrapFiles, dir)
-      const needsTests = assessed.filter(f => f.needsTests)
-      if (needsTests.length === 0) {
-        console.log('✓ LLM вирішила: жоден файл не потребує unit-тестів.')
+      console.log(`\n── Bootstrap: ${sourceFiles.length} джерел — класифікую локально ──\n`)
+
+      const bootstrapFiles = sourceFiles
+        .map(f => {
+          try {
+            const q = quickClassify(readFileSync(join(dir, f), 'utf8'))
+            if (q?.needsTests === false) return null
+          } catch {
+            /* include on read error */
+          }
+          return { file: f, pct: 0 }
+        })
+        .filter(Boolean)
+
+      if (bootstrapFiles.length === 0) {
+        console.log('✓ Жоден файл не потребує unit-тестів (реекспорти/типи).')
         break
       }
-      console.log(`\n→ Bootstrap-тести для (${needsTests.length}):`)
-      for (const f of needsTests) console.log(`  • ${f.file} — ${f.reason}`)
-      await generateTests(needsTests, dir)
+
+      console.log(`\n→ Bootstrap-тести для (${bootstrapFiles.length}):`)
+      for (const f of bootstrapFiles) console.log(`  • ${f.file}`)
+      await generateTests(bootstrapFiles, dir)
       continue
     }
 
@@ -84,21 +97,12 @@ export async function runAutoTest(dir, opts = {}) {
     }
     prevUncoveredCount = uncovered.length
 
-    console.log(`\n── Оцінюю ${uncovered.length} непокритих файлів (LLM) ──\n`)
-    const assessed = await assessNeed(uncovered, dir)
-    const needsTests = assessed.filter(f => f.needsTests)
-
-    if (needsTests.length === 0) {
-      console.log('✓ LLM вирішила: жоден непокритий файл не потребує unit-тестів.')
-      break
-    }
-
-    console.log(`\n→ Потребують тестів (${needsTests.length}):`)
-    for (const f of needsTests) {
-      console.log(`  • ${f.file} (${f.pct.toFixed(1)}%) — ${f.reason}`)
+    console.log(`\n→ Генерую тести для ${uncovered.length} файлів:`)
+    for (const f of uncovered) {
+      console.log(`  • ${f.file} (${f.pct.toFixed(1)}%)`)
     }
 
-    await generateTests(needsTests, dir)
+    await generateTests(uncovered, dir)
   }
 
   if (opts.noMutation) {

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: не виконує операцій запису (ФС/БД).