@nitra/cursor 3.21.1 → 3.23.0

package/scripts/docs/ensure-nitra-cursor-dev-dependencies.md

@@ -0,0 +1,189 @@
+# ensure-nitra-cursor-dev-dependencies.mjs
+
+## Огляд
+
+Модуль `ensure-nitra-cursor-dev-dependencies.mjs` забезпечує, що пакет `@nitra/cursor` буде оголошений у `devDependencies` workspace-root `package.json` проєкту, в якому виконується CLI `n-cursor`. Якщо запис відсутній і в `devDependencies`, і в `dependencies`, модуль дописує його з діапазоном `^<version>`, узятим з поля `version` з `package.json` фактично завантаженого пакету `@nitra/cursor`.
+
+Призначення: коли користувач викликає `npx @nitra/cursor` (зокрема команду `check`), node-кеш npx містить пакет, але після наступного `bun install` / `npm install` цей кеш може не відтворити пакет у проєкті. Дописавши пакет у `devDependencies` workspace-root, модуль гарантує, що `n-cursor` і його допоміжні скрипти з `node_modules/@nitra/cursor/scripts/` стануть відтвореною частиною проєкту й не залежатимуть від кешу npx.
+
+Workspace-root визначається мінімалістично: береться `package.json` поруч зі стартовою директорією (зазвичай `process.cwd()`) і вважається workspace-root, якщо в ньому є поле `workspaces`. Підйом по дереву директорій не виконується.
+
+Модуль написаний як ESM (`.mjs`), використовує лише стандартну бібліотеку Node.js, не має сторонніх залежностей і виконує синхронні файлові операції лише для перевірки існування (`existsSync`). Решта IO — асинхронна через `node:fs/promises`.
+
+## Експорти / API
+
+Модуль експортує дві асинхронні функції:
+
+- `readBundledPackageVersion()` — повертає версію встановленого пакету `@nitra/cursor` або `null`.
+- `ensureNitraCursorInRootDevDependencies(root, options?)` — головна точка входу: перевіряє стан проєкту й, за потреби, мутує його `package.json`. Повертає булеве значення про факт запису на диск.
+
+Внутрішні (не експортовані) функції модуля:
+
+- `readJsonObject(path)` — м’який парсер JSON-обʼєкта з диска.
+- `readAdjacentWorkspaceRootPackageJson(startDir)` — читання `package.json` поряд зі стартовою директорією за умови, що це workspace-root.
+
+Константа модульного рівня:
+
+- `PACKAGE_NAME` (`'@nitra/cursor'`) — імʼя пакету, який забезпечується у `devDependencies`.
+
+Внутрішній стан модуля (обчислюється один раз під час імпорту):
+
+- `scriptDir` — абсолютна директорія, в якій лежить сам файл (отримана з `import.meta.url`).
+- `bundledPkgPath` — обчислений шлях до `package.json` пакету `@nitra/cursor`: на один рівень вище `scriptDir`, бо файл лежить у каталозі `scripts/` всередині пакету.
+
+## Функції
+
+### `readBundledPackageVersion()`
+
+Сигнатура: `readBundledPackageVersion(): Promise<string | null>` (експортується).
+
+Параметри: відсутні.
+
+Поведінка:
+
+1. Перевіряє існування файлу `bundledPkgPath` через `existsSync`. Якщо файлу немає — повертає `null` без подальшої роботи.
+2. Читає вміст файлу як UTF-8 через `readFile`.
+3. Парсить вміст як JSON.
+4. Якщо поле `version` у розпарсеному обʼєкті є рядком — повертає його; інакше — повертає `null`.
+5. Будь-яка помилка читання чи парсингу глушиться `try/catch` і дає `null`.
+
+Повертає: `Promise<string | null>` — текстова версія (наприклад, `'1.11.14'`) або `null` за відсутності файлу / некоректного JSON / нерядкового `version`.
+
+Side effects: лише read-IO (один read від диска). Нічого не пише й не логує.
+
+### `readJsonObject(path)`
+
+Сигнатура: `readJsonObject(path: string): Promise<Record<string, unknown> | null>` (внутрішня).
+
+Параметри:
+
+- `path` — абсолютний шлях до JSON-файлу.
+
+Поведінка:
+
+1. Намагається прочитати файл як UTF-8. Помилка читання повертає `null`.
+2. Намагається розпарсити вміст як JSON. Помилка парсингу повертає `null`.
+3. Перевіряє, що розпарсене значення — це не `null`, типу `object`, і не масив. Якщо умова не виконана — повертає `null`. Інакше повертає сам обʼєкт.
+
+Повертає: `Promise<Record<string, unknown> | null>` — JSON-обʼєкт або `null`.
+
+Side effects: read-IO.
+
+### `readAdjacentWorkspaceRootPackageJson(startDir)`
+
+Сигнатура: `readAdjacentWorkspaceRootPackageJson(startDir: string): Promise<{ path: string, pkg: Record<string, unknown> } | null>` (внутрішня).
+
+Параметри:
+
+- `startDir` — директорія, від якої починається пошук (зазвичай `process.cwd()` процесу CLI).
+
+Поведінка:
+
+1. Будує `pkgPath = join(startDir, 'package.json')`.
+2. Через `existsSync` перевіряє наявність файлу. Якщо файлу немає — повертає `null`.
+3. Викликає `readJsonObject(pkgPath)`. Якщо результат — не обʼєкт, повертає `null`.
+4. Через `Object.hasOwn(pkg, 'workspaces')` перевіряє наявність поля `workspaces` (саме власне поле, а не з прототипа). Якщо поле є — повертає `{ path, pkg }`; інакше — `null`.
+
+Повертає: `Promise<{ path, pkg } | null>` — пара «шлях/обʼєкт» для workspace-root або `null` для не-workspace-root.
+
+Side effects: read-IO. Жодних мутацій диска / логів.
+
+### `ensureNitraCursorInRootDevDependencies(root, options?)`
+
+Сигнатура: `ensureNitraCursorInRootDevDependencies(root: string, options?: { bundledVersion?: string | null, silent?: boolean }): Promise<boolean>` (експортується).
+
+Параметри:
+
+- `root` — стартова директорія проєкту, зазвичай `process.cwd()` процесу CLI `n-cursor`.
+- `options` — необовʼязковий обʼєкт:
+  - `bundledVersion` — попередньо задана версія для тестів; якщо передано — використовується замість виклику `readBundledPackageVersion()`. `null` тут інтерпретується як «викликати fallback» через оператор `??`.
+  - `silent` — якщо `true`, не друкувати повідомлення про оновлення у `stdout`.
+
+Алгоритм:
+
+1. Викликає `readAdjacentWorkspaceRootPackageJson(root)`. Якщо результат `null` (немає workspace-root) — повертає `false`.
+2. Деструктурує `{ path: pkgPath, pkg }`.
+3. Якщо в `pkg.devDependencies` (за умови, що це обʼєкт) присутній ключ `PACKAGE_NAME` — повертає `false` (вже є).
+4. Якщо в `pkg.dependencies` (за умови, що це обʼєкт) присутній ключ `PACKAGE_NAME` — повертає `false` (вже є в runtime deps; додавати дубль до dev не потрібно).
+5. Визначає версію: `options.bundledVersion ?? await readBundledPackageVersion()`. Якщо результат фолсі (`null`, порожній рядок) — повертає `false`.
+6. Гарантує, що `pkg.devDependencies` — це валідний обʼєкт. Якщо там відсутнє поле, `null`, не-обʼєкт або масив — перезаписує його на `{}`.
+7. Записує `pkg.devDependencies[PACKAGE_NAME] = ` `^<ver>`.
+8. Серіалізує `pkg` з відступом 2 пробіли через `JSON.stringify(pkg, null, 2)`, додає завершальний перевід рядка `\n`, пише через `writeFile` у `pkgPath` у UTF-8.
+9. Якщо `options.silent` не встановлено — друкує `📝 Додано <PACKAGE_NAME>@^<ver> у devDependencies у package.json\n` у `stdout` через `console.log`.
+10. Повертає `true`.
+
+Повертає: `Promise<boolean>` — `true`, якщо `package.json` дійсно змінено на диску; `false` у всіх no-op-ситуаціях (немає workspace-root, пакет вже задекларовано, версія недоступна).
+
+Side effects:
+
+- Читання `package.json` workspace-root.
+- Можливий запис `package.json` workspace-root (мутація вмісту).
+- Можливий запис у `stdout` через `console.log` (можна заглушити через `options.silent`).
+
+Особливості:
+
+- Перевірка «вже є в deps» поблажлива: якщо `devDependencies` / `dependencies` присутнє, але не є обʼєктом (некоректний `package.json`), модуль трактує це як «нема» і йде далі.
+- Перезапис `pkg.devDependencies` на `{}` у випадку, коли поле не є обʼєктом, спрямований на корекцію некоректного стану `package.json`. Це означає, що нечитабельне поле буде втрачено.
+- Серіалізація використовує `JSON.stringify` із відступом 2 і завершальним `\n`. Будь-яке стилістичне форматування з оригіналу (наприклад, табуляції чи tab-width=4) буде нормалізоване до 2 пробілів.
+
+## Залежності
+
+Зовнішніх npm-залежностей немає. Використовуються лише вбудовані модулі Node.js:
+
+- `node:fs`
+  - `existsSync` — синхронна перевірка існування файлу.
+- `node:fs/promises`
+  - `readFile` — асинхронне читання файлу як UTF-8.
+  - `writeFile` — асинхронний запис файлу як UTF-8.
+- `node:path`
+  - `dirname` — отримати директорію з шляху.
+  - `join` — побудувати шлях.
+- `node:url`
+  - `fileURLToPath` — конвертувати `file://`-URL у файловий шлях.
+
+Зовнішні споживачі модуля:
+
+- CLI `@nitra/cursor` (`bin`), що викликає `ensureNitraCursorInRootDevDependencies(process.cwd())` під час кожного запуску (зокрема перед `check`), щоб довести стан `package.json` проєкту до бажаного.
+- Тестовий код може передавати `bundledVersion` у `options`, щоб не залежати від реальної версії з диска.
+
+## Потік виконання / Використання
+
+Типовий потік під час `npx @nitra/cursor check` у workspace-root:
+
+1. CLI імпортує модуль і викликає `await ensureNitraCursorInRootDevDependencies(process.cwd())`.
+2. Модуль читає `<cwd>/package.json`. Якщо там немає поля `workspaces` — це не workspace-root, повертається `false`, файл не змінюється.
+3. Якщо `package.json` має `workspaces` і вже містить `@nitra/cursor` у `devDependencies` або `dependencies` — повертається `false`, файл не змінюється.
+4. Інакше модуль читає `version` з `package.json` встановленого пакету `@nitra/cursor` (на рівень вище за `scripts/`), формує діапазон `^<version>` і записує його в `pkg.devDependencies['@nitra/cursor']`.
+5. Серіалізований JSON записується назад у `<cwd>/package.json`.
+6. У `stdout` логується повідомлення про додавання (якщо не задано `silent: true`).
+7. Повертається `true`.
+
+Приклад використання:
+
+```js
+import { ensureNitraCursorInRootDevDependencies } from '@nitra/cursor/scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+
+const changed = await ensureNitraCursorInRootDevDependencies(process.cwd())
+if (changed) {
+  // package.json було оновлено — можна підказати користувачу зробити bun install
+}
+```
+
+Приклад використання з тестового сетапу:
+
+```js
+import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+
+await ensureNitraCursorInRootDevDependencies(tmpDir, {
+  bundledVersion: '9.9.9',
+  silent: true
+})
+```
+
+Передумови, на які покладається модуль:
+
+- Файл `ensure-nitra-cursor-dev-dependencies.mjs` лежить у `<package>/scripts/`, а `package.json` пакету `@nitra/cursor` — у `<package>/package.json`. Якщо структуру переміщено, шлях `bundledPkgPath` стане некоректним.
+- Робоче дерево, передане як `root`, має містити `package.json` із полем `workspaces`. Якщо CLI стартовано всередині workspace-пакету (а не в корені) — модуль нічого не зробить (`false`).
+- Поле `version` у `package.json` пакету `@nitra/cursor` має бути рядком; інакше додавання не відбудеться.
+
+Інваріант: повторні виклики модуля у тому самому проєкті стають no-op (другий виклик бачить `@nitra/cursor` у `devDependencies` і повертає `false`).

package/scripts/lib/changed-files.mjs

@@ -15,7 +15,10 @@ import { spawnSync } from 'node:child_process'
 function gitLines(args, cwd) {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
   if (r.status !== 0 || r.error) return []
-  return r.stdout.split('\n').map(s => s.trim()).filter(Boolean)
+  return r.stdout
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
 }
 
 /**

package/scripts/lib/diff-added-lines.mjs

@@ -0,0 +1,85 @@
+/**
+ * Додані/змінені рядки на файл (vs HEAD) — для класифікації lint-findings на
+ * introduced (рядок у diff) vs pre-existing (поза diff), беклог #6.
+ *
+ * Парсимо `git diff --unified=0 HEAD -- <files>`: hunk-заголовок `@@ -a,b +c,d @@`
+ * дає додані рядки c..c+d-1. Untracked (нові, поза HEAD) — усі рядки introduced (маркер `ALL`).
+ */
+import { spawnSync } from 'node:child_process'
+
+/** Маркер «усі рядки файлу introduced» (новий untracked-файл). */
+export const ALL_LINES = 'ALL'
+
+/** Шлях цільового файлу у рядку `+++ b/path` (або `/dev/null`). */
+const PLUS_FILE_RE = /^\+\+\+ (?:b\/)?(.*)$/u
+/** Діапазон доданих рядків у hunk-заголовку `@@ -a,b +c,d @@`. */
+const HUNK_ADD_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/u
+
+/**
+ * Парсить вивід `git diff --unified=0` у мапу доданих рядків на файл.
+ * @param {string} diffText сирий вивід git diff
+ * @returns {Map<string, Set<number>>} файл → множина доданих рядків
+ */
+export function parseAddedLines(diffText) {
+  const byFile = new Map()
+  let current = null
+  for (const line of String(diffText).split('\n')) {
+    const fileMatch = PLUS_FILE_RE.exec(line)
+    if (fileMatch) {
+      current = fileMatch[1] === '/dev/null' ? null : fileMatch[1]
+      if (current && !byFile.has(current)) byFile.set(current, new Set())
+      continue
+    }
+    const hunk = current && HUNK_ADD_RE.exec(line)
+    if (hunk) {
+      const start = Number(hunk[1])
+      const count = hunk[2] === undefined ? 1 : Number(hunk[2])
+      for (let i = 0; i < count; i++) byFile.get(current).add(start + i)
+    }
+  }
+  return byFile
+}
+
+/**
+ * Тихий git → stdout або `''`.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {string} stdout
+ */
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return r.status === 0 ? (r.stdout ?? '') : ''
+}
+
+/**
+ * Додані рядки на файл (vs HEAD) для заданих файлів. Tracked → з diff;
+ * untracked (нові) → маркер `ALL_LINES`.
+ * @param {string[]} files відносні шляхи (від cwd)
+ * @param {string} [cwd] корінь репо
+ * @param {{ git?: (args: string[], cwd: string) => string }} [deps] ін'єкція git (тести)
+ * @returns {Map<string, Set<number> | typeof ALL_LINES>} файл → додані рядки / `ALL`
+ */
+export function addedLinesByFile(files, cwd = process.cwd(), deps = {}) {
+  if (!files || files.length === 0) return new Map()
+  const run = deps.git ?? git
+  const map = parseAddedLines(run(['diff', '--unified=0', 'HEAD', '--', ...files], cwd))
+  const untracked = run(['ls-files', '--others', '--exclude-standard', '--', ...files], cwd)
+  for (const f of untracked.split('\n').filter(Boolean)) {
+    map.set(f, ALL_LINES)
+  }
+  return map
+}
+
+/**
+ * Чи рядок `line` у файлі `file` — доданий (introduced).
+ * @param {Map<string, Set<number> | typeof ALL_LINES>} addedLines результат `addedLinesByFile`
+ * @param {string} file відносний шлях
+ * @param {number} line номер рядка
+ * @returns {boolean} результат
+ */
+export function isIntroducedLine(addedLines, file, line) {
+  const entry = addedLines.get(file)
+  if (entry === undefined) return false
+  if (entry === ALL_LINES) return true
+  return entry.has(line)
+}

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

@@ -0,0 +1,149 @@
+# changed-files.mjs
+
+## Огляд
+
+Модуль `changed-files.mjs` — допоміжна бібліотека для збору переліку змінених файлів у робочому дереві git-репозиторію. Використовується lint-оркестратором у quick-режимі та `coverage --changed` для визначення scope-у файлів, на яких потрібно прогнати перевірки.
+
+Логіка модуля:
+
+- збирає tracked-modified та staged файли через `git diff` (з `--diff-filter=ACMR`, тобто Added/Copied/Modified/Renamed — без Deleted);
+- додає untracked файли через `git ls-files --others --exclude-standard` (з повагою до `.gitignore`);
+- дедуплікує об'єднаний список через `Set`;
+- повертає relative-posix шляхи відносно `cwd`;
+- поза git-репо або при помилці git мовчки повертає порожній список (для `gitLines`);
+- для режиму "since base" — fail-closed: якщо базовий комміт недосяжний, кидає явну помилку, щоб gate не пройшов мовчки.
+
+Видалені файли свідомо не включаються — лінтити неіснуючий файл немає сенсу.
+
+## Експорти / API
+
+Модуль експортує дві функції:
+
+| Експорт                    | Тип                                                | Призначення                                                                                                                  |
+| -------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `collectChangedFiles`      | `(cwd?: string) => string[]`                       | Список змінених + untracked файлів робочого дерева відносно `HEAD`.                                                          |
+| `collectChangedFilesSince` | `(base: string \| null, cwd?: string) => string[]` | Список змінених + untracked файлів **відносно довільного базового комміту**. Без `base` — fallback на `collectChangedFiles`. |
+
+Внутрішня (неекспортована) функція:
+
+| Внутрішнє  | Тип                                         | Призначення                                                                                    |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `gitLines` | `(args: string[], cwd: string) => string[]` | Виконує `git <args>` у `cwd` і повертає непорожні trim-нуті рядки stdout або `[]` при помилці. |
+
+## Функції
+
+### `gitLines(args, cwd)` (internal)
+
+Виклик git-команди з парсингом stdout у масив рядків.
+
+- **Сигнатура:** `function gitLines(args: string[], cwd: string): string[]`
+- **Параметри:**
+  - `args` — масив аргументів для `git` (наприклад `['diff', 'HEAD', '--name-only']`).
+  - `cwd` — робоча директорія для процесу `git`.
+- **Повертає:** масив непорожніх рядків stdout (після `trim`). Якщо `r.status !== 0` або є `r.error` — повертає `[]`.
+- **Side effects:**
+  - Синхронно спавнить процес `git` через `spawnSync` з `node:child_process`;
+  - не пише в stdout/stderr батьківського процесу (всі потоки збираються через `encoding: 'utf8'`);
+  - не кидає винятків — fail-silent.
+
+### `collectChangedFiles(cwd?)`
+
+Збирає список змінених + untracked файлів робочого дерева відносно `HEAD`.
+
+- **Сигнатура:** `function collectChangedFiles(cwd?: string): string[]`
+- **Параметри:**
+  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
+- **Алгоритм:**
+  1. `git diff HEAD --name-only --diff-filter=ACMR` — повертає всі tracked файли, які відрізняються від `HEAD` (staged + unstaged), фільтр `ACMR` відсікає Deleted.
+  2. `git ls-files --others --exclude-standard` — повертає untracked файли, які не ігноруються `.gitignore`.
+  3. Об'єднання обох списків через `new Set([...modified, ...untracked])` для дедуплікації.
+- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
+- **Поведінка поза git-репо / при помилці:** `gitLines` мовчки повертає `[]` для обох викликів, тож результат — порожній масив.
+
+### `collectChangedFilesSince(base, cwd?)`
+
+Збирає список змінених + untracked файлів відносно довільного базового комміту. Призначено для сценаріїв, де базовий комміт зафіксовано у стані flow-турнікета (executor комітить кожен крок, тож потрібно ловити зміни «від base», а не «від HEAD»).
+
+- **Сигнатура:** `function collectChangedFilesSince(base: string | null, cwd?: string): string[]`
+- **Параметри:**
+  - `base` — SHA/ref базового комміту (типово `metadata.base_commit` зі стану flow). Якщо `null`/`undefined`/порожній — fallback на `collectChangedFiles(cwd)`.
+  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
+- **Алгоритм:**
+  1. Якщо `base` falsy — повертає результат `collectChangedFiles(cwd)`.
+  2. Перевіряє досяжність base через `git rev-parse --verify --quiet <base>^{commit}`.
+  3. Якщо verify не успішний (`status !== 0` або `error`) — **кидає `Error`** з повідомленням: `collectChangedFilesSince: base-комміт «<base>» недосяжний у <cwd> (rebase/force-update?) — coverage --changed не може визначити scope`.
+  4. `git diff <base> --name-only --diff-filter=ACMR` — **без** `..`/`...`, **без** `HEAD`. Така форма порівнює base-комміт із поточним **робочим деревом**, тобто ловить одночасно: закомічене від base, staged та незакомічені модифікації.
+  5. `git ls-files --others --exclude-standard` — untracked файли (як у `collectChangedFiles`).
+  6. Дедуплікація через `Set`.
+- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
+- **Контракт fail-closed:** на відміну від `collectChangedFiles`, ця функція **навмисно** не маскує помилку недосяжного base. Інакше `git diff` повернув би exit 128, `gitLines` дав би `[]`, і gate мовчки пройшов би без перевірки — це порушує безпеку coverage-перевірки.
+- **Side effects:**
+  - спавнить два-три git-процеси (один verify + два data-збори, або один fallback);
+  - може кинути `Error` (єдина точка throw у модулі).
+
+## Залежності
+
+### Зовнішні (built-in Node.js)
+
+- `node:child_process` — імпорт `spawnSync` для синхронного виклику git-команд із захопленням stdout.
+
+### Системні (runtime)
+
+- `git` — має бути доступний у `PATH` процесу. За відсутності `gitLines` поверне `[]` (через `r.error`/ненульовий статус).
+
+### Внутрішні модулі
+
+Файл не імпортує жодного локального модуля проєкту (zero-dependency бібліотечний листок).
+
+## Потік виконання / Використання
+
+### Quick-lint (lint-оркестратор)
+
+```js
+import { collectChangedFiles } from './changed-files.mjs'
+
+const files = collectChangedFiles()
+// → лінт тільки цих файлів, замість обходу всього монорепо
+```
+
+Quick-режим прагне мінімізувати IO: лінтить лише те, що користувач щойно змінив у дереві (modified + staged + untracked), ігноруючи решту репо.
+
+### Coverage / flow-турнікет
+
+```js
+import { collectChangedFilesSince } from './changed-files.mjs'
+
+const base = metadata.base_commit // SHA, зафіксований при старті flow-кроку
+const scope = collectChangedFilesSince(base, repoRoot)
+// → файли, які змінилися з моменту base, незалежно від того,
+//   чи їх вже закомічено в проміжних кроках executor-а
+```
+
+Чому саме `git diff <base>` без `..`/`...`:
+
+- `git diff A..B` — порівнює дерева A та B, **ігнорує** робоче дерево;
+- `git diff A...B` — порівнює B з merge-base(A,B), теж ігнорує робоче дерево;
+- `git diff <base>` (один аргумент) — порівнює `<base>` із **робочим деревом** (включно з unstaged змінами).
+
+Це критично для flow-турнікета, де executor може як комітити проміжні зміни, так і залишати їх unstaged — gate повинен побачити всі зміни від `base` однаково.
+
+### Поведінка при недосяжному base
+
+Якщо у репозиторії стався rebase, force-push або shallow clone обрізав історію — `<base>` може стати недосяжним. У такому разі:
+
+- `collectChangedFiles` (без base) — поведінка незмінна, працює від `HEAD`;
+- `collectChangedFilesSince(base, cwd)` — **кидає Error** до того, як викликати `git diff`, щоб coverage-gate явно впав, а не пройшов на порожньому scope.
+
+### Формат шляхів
+
+Усі повернені шляхи — POSIX-style relative до `cwd` (як їх віддає git за замовчуванням). На Windows git також віддає forward slashes, тож додаткової нормалізації немає.
+
+### Точки помилок (summary)
+
+| Сценарій                                      | Поведінка                                                                                                                          |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Поза git-репо                                 | `collectChangedFiles` → `[]`; `collectChangedFilesSince(null)` → `[]`; `collectChangedFilesSince('SHA')` → `Error` (verify впаде). |
+| `git` відсутній у PATH                        | Усі виклики `gitLines` → `[]`; `collectChangedFilesSince` із `base` → `Error` (verify впаде).                                      |
+| `base` досяжний                               | `collectChangedFilesSince` повертає список (можливо порожній).                                                                     |
+| `base` недосяжний (rebase/force-push/shallow) | `collectChangedFilesSince` кидає `Error`.                                                                                          |
+| `base` falsy (`null`/`undefined`/`''`/`0`)    | `collectChangedFilesSince` → результат `collectChangedFiles(cwd)`.                                                                 |