@nitra/cursor 5.1.0 → 5.2.0

package/rules/capacitor/js/docs/platforms.md

@@ -1,295 +1,89 @@
+---
+docgen:
+  source: npm/rules/capacitor/js/platforms.mjs
+  crc: eb8d6293
+  score: 100
+---
+
 # platforms.mjs
 
 ## Огляд
 
-Модуль `platforms.mjs` реалізує **check** для правила `capacitor.mdc`: перевіряє, що проєкт-застосунок на базі **Capacitor** відповідає політикам монорепо Nitra. Файл експортує асинхронну функцію `check(cwd)`, яка повертає **exit-код** (0 — ok, 1 — fail), а також низку допоміжних чистих функцій для розбору **npm**-діапазонів версій, обходу `package.json` та пошуку `Podfile` у каталозі `ios/`.
-
-Перевірка послідовно виконує три блоки логіки:
-
-1. **Виявлення Capacitor у репозиторії.** Capacitor вважається задіяним, якщо в корені присутній один із файлів `capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`, **або** хоч у одному `package.json` (рекурсивний обхід дерева з пропуском типових каталогів) задекларовано пакет із префіксом `@capacitor/` у будь-якому блоці залежностей (`dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`). Якщо ознак немає — check одразу повертає **pass** і код **0**, не вимагаючи жодних дій.
-2. **Перевірка мінімальної версії `@capacitor/core` ≥ 8.** Для кожного `package.json`, який оголошує `@capacitor/core`, обчислюється **нижня межа major** з рядка npm-діапазону. Якщо вона менша за `MIN_CAPACITOR_MAJOR = 8`, або діапазон не вдалося визначити (`*`, `latest`, `x`, незрозумілий синтаксис) — це fail; повідомлення підказує задати, наприклад, `^8.0.0`. Якщо `capacitor.config.*` знайдено, а `@capacitor/core` у дереві відсутній — теж fail.
-3. **iOS / Podfile.** За політикою `capacitor.mdc` iOS-частина Capacitor-застосунку повинна збиратися лише через **SPM**, без CocoaPods. Рекурсивний обхід `ios/` (пропускаючи `Pods`, `build`, `DerivedData`) шукає перший `Podfile`. Якщо `Podfile` є, він вважається порушенням, **окрім** випадку коли в кореневому `package.json` або в `capacitor.config.{json,ts,mjs}` присутній об’єкт `nitra` із прапором `iosCocoaPodsBecausePluginsLackSpm: true` або `iosCocoaPodsAllowed: true`. Якщо каталогу `ios/` немає — умова не застосовується.
-
-Усі повідомлення про результат виводяться через `createCheckReporter()` зі спільного хелпера `scripts/lib/check-reporter.mjs`.
-
-## Експорти / API
-
-Файл експортує іменовані символи (без default export):
-
-- `capacitorSegmentMinMajor(segment)` — мінімальний **major** для одного OR-сегмента npm-діапазону.
-- `capacitorVersionRangeMinMajor(versionRange)` — мінімальний **major** для повного діапазону, з підтримкою `||`.
-- `isCapacitorCoreVersionAtLeast8(versionRange, min?)` — булеан-предикат: чи нижня межа діапазону `≥ min` (за замовчуванням `MIN_CAPACITOR_MAJOR`).
-- `recordCapacitorFromOnePackageJson(absPath, root, out)` — асинхронно прочитати один `package.json` і поповнити акумулятор.
-- `collectCapacitorDataFromAllPackageJson(root, out)` — рекурсивно обійти всі `package.json` у репозиторії, агрегуючи `byPath` і `anyCapacitor`.
-- `hasCapacitorConfigInRoot(root)` — синхронно перевірити наявність `capacitor.config.{json,ts,mjs}` у корені.
-- `isCapacitorRelevantForCheck(root, anyCapacitor)` — чи варто застосовувати правила Capacitor взагалі.
-- `walkIosForPodfileSkipPods(root, dir, onPodfileRelative)` — рекурсивний пошук `Podfile` під `ios/` із пропуском службових тек.
-- `findFirstPodfileUnderIosExcludingPods(root)` — повертає **найкоротший** posix-relative шлях до першого знайденого `Podfile` (або `null`).
-- `nitrAObjectAllowsIosCocoaPods(o)` — предикат для об’єкта `nitra`: чи дозволено CocoaPods.
-- `check(cwd?)` — головна функція **check**; повертає **exit-код**.
-
-Внутрішні (неекспортовані) функції: `firstVersionMajorFromNpmValue`, `reportOneCapacitorCoreRange`, `recordCapacitorFromDependencyObject`, `extractNitraObjectBodySource`, `nitraObjectBodyStringAllowsCocoaPodsExempt`, `pathJsonShowsNitraCocoapodsExempt`, `capacitorConfigTsMjsNitraCocoapodsExempt`, `isIosCocoaPodsExemptByNitraConfig`.
-
-Константи модульного рівня:
-
-- `MIN_CAPACITOR_MAJOR = 8` — мінімальний допустимий **major** Capacitor.
-- `IGNORED_DIRS_FOR_PACKAGE_JSON` — `Set` каталогів, які пропускаються при обході (`node_modules`, `.git`, `dist`, `coverage`, `Pods`, `.turbo`, `.next`, `build`).
-- Регулярки: `NPM_OR_PARTS_RE` (`\s*\|\|\s*`), `NPM_HYPHEN_RANGE_RE` (`^(.+?)\s+-\s+(.+)$`), `FIRST_VERSION_NUM_RE` (`^(?:v)?(\d+)`), `PREFIX_GEQ_RE` (`^>=\s*`), `PREFIX_GT_RE` (`^>\s*`), `STRIP_CARET_TILDE_EQ_RE` (`^[=^~]+\s*`), `RE_NITRA_CONFIG_OBJECT_LEAD_IN` (початок блоку `nitra: {` у TS/MJS), `RE_COCOAPODS_EXEMPT_SPM` (`iosCocoaPodsBecausePluginsLackSpm: true`), `RE_COCOAPODS_EXEMPT_ALLOW` (`iosCocoaPodsAllowed: true`).
-
-## Функції
-
-### `capacitorSegmentMinMajor(segment)`
-
-- **Сигнатура:** `(segment: string) => number | null`
-- **Параметри:** `segment` — одна частина npm-діапазону (без `||` всередині).
-- **Повертає:** мінімальний **major**, який задовольняється сегментом; `null`, якщо сегмент — `*`, `x` (case-insensitive) або `latest`, або якщо вхід не рядок чи порожній.
-- **Логіка:**
-  - Не-рядок або порожній рядок після `trim()` → `null`.
-  - `*`, `x` (нижній регістр), `latest` → `null` (невизначена нижня межа).
-  - Префікс `<` або `<=` → `0` (теоретично може допускати дуже старі major-и).
-  - Префікс `>` (але не `>=`) → витягає число з решти рядка через `firstVersionMajorFromNpmValue`.
-  - Дефіс-діапазон `a - b` (`NPM_HYPHEN_RANGE_RE`) → бере major лівої межі.
-  - Префікси `^`, `~`, `=` → знімає їх і повертає major першого числа.
-  - Префікс `>=` → знімає його і повертає major.
-  - Інакше — повертає major першого числа в рядку.
-- **Side effects:** немає (чиста функція).
-
-### `firstVersionMajorFromNpmValue(t)` _(внутрішня)_
-
-- **Сигнатура:** `(t: string) => number | null`
-- **Параметри:** `t` — фрагмент рядка версії без префікса операторів.
-- **Повертає:** перше ціле число (major), знайдене регуляркою `FIRST_VERSION_NUM_RE` (опційний префікс `v`); `null`, якщо число не знайдено або рядок порожній.
-- **Side effects:** немає.
-
-### `capacitorVersionRangeMinMajor(versionRange)`
-
-- **Сигнатура:** `(versionRange: string) => number | null`
-- **Параметри:** `versionRange` — повне значення поля для `@capacitor/core` з `package.json`.
-- **Повертає:** найменший (нижній) **major** серед усіх OR-частин; `null`, якщо хоча б одна частина — `*` / `latest` / `x` / нерозпізнана (тобто діапазон вважається небезпечним).
-- **Логіка:** розбиває за `||`, кожну частину пропускає через `capacitorSegmentMinMajor`, ранній вихід із `null` при першій невизначеній; інакше — мінімум серед усіх отриманих чисел.
-- **Side effects:** немає.
-
-### `isCapacitorCoreVersionAtLeast8(versionRange, min = MIN_CAPACITOR_MAJOR)`
-
-- **Сигнатура:** `(versionRange: string, min?: number) => boolean`
-- **Параметри:** `versionRange` — рядок версії; `min` — нижній поріг major (за замовчуванням **8**).
-- **Повертає:** `true`, якщо нижня межа діапазону визначена і `>= min`; інакше — `false` (зокрема для `*`, `latest`).
-- **Side effects:** немає.
-
-### `reportOneCapacitorCoreRange(fail, pass, rel, range)` _(внутрішня)_
-
-- **Сигнатура:** `(fail: (m: string) => void, pass: (m: string) => void, rel: string, range: string) => void`
-- **Параметри:** `fail`, `pass` — друк-колбеки reporter; `rel` — posix-relative шлях `package.json`; `range` — значення `@capacitor/core`.
-- **Повертає:** `void`.
-- **Side effects:** викликає `pass(...)` або `fail(...)` зі сформованим повідомленням, у якому згадано `MIN_CAPACITOR_MAJOR` та рекомендацію `^8.0.0`.
-
-### `recordCapacitorFromDependencyObject(rel, obj, out)` _(внутрішня)_
-
-- **Сигнатура:** `(rel: string, obj: Record<string, unknown>, out: { byPath: Map<string, string>, anyCapacitor: boolean }) => void`
-- **Параметри:** `rel` — relative-шлях `package.json`; `obj` — один із блоків залежностей; `out` — акумулятор.
-- **Повертає:** `void`.
-- **Side effects:**
-  - Виставляє `out.anyCapacitor = true`, якщо знайдено будь-який ключ, що починається з `@capacitor/`.
-  - Якщо ключ — рівно `@capacitor/core` і значення — непорожній рядок, кладе пару `rel → range` в `out.byPath`. Повторні записи з різних блоків залежностей перезаписують одне одного (останній блок перемагає в порядку `dependencies → devDependencies → optionalDependencies → peerDependencies`).
-
-### `recordCapacitorFromOnePackageJson(absPath, root, out)`
-
-- **Сигнатура:** `(absPath: string, root: string, out: { byPath: Map<string, string>, anyCapacitor: boolean }) => Promise<void>`
-- **Параметри:** `absPath` — абсолютний шлях до `package.json`; `root` — корінь репозиторію; `out` — акумулятор.
-- **Повертає:** `Promise<void>`.
-- **Side effects:**
-  - Читає файл через `readFile(absPath, 'utf8')`; будь-яка помилка вводу/виводу мовчазно повертає керування (файл пропускається).
-  - Парсить JSON; помилка парсингу — теж мовчазне пропускання.
-  - Обчислює posix-relative шлях відносно `root` (з заміною `\` на `/`); якщо `relative()` повертає порожній рядок — підставляє `absPath`.
-  - Для кожного блоку залежностей, що є об’єктом (не масив, не `null`/`undefined`), викликає `recordCapacitorFromDependencyObject`.
-
-### `collectCapacitorDataFromAllPackageJson(root, out)`
-
-- **Сигнатура:** `(root: string, out: { byPath: Map<string, string>, anyCapacitor: boolean }) => Promise<void>`
-- **Параметри:** `root` — корінь обходу; `out` — акумулятор (буде ініціалізовано).
-- **Повертає:** `Promise<void>`.
-- **Side effects:**
-  - На початку **скидає** `out.anyCapacitor = false`; якщо `out.byPath` уже існує — викликає `.clear()`, інакше створює нову `Map`.
-  - Внутрішня функція `walk(dir)` робить `readdir(dir, { withFileTypes: true })`; помилку каталогу мовчки ігнорує.
-  - Для кожного запису: якщо це каталог і його імені немає в `IGNORED_DIRS_FOR_PACKAGE_JSON` — рекурсивно входить; якщо це файл `package.json` — викликає `recordCapacitorFromOnePackageJson`.
-  - Інші типи файлів (`isFile` зі значенням false, симлінки тощо) пропускаються — записи з `entry.isDirectory() === false && entry.isFile() === false` не оброблюються.
-
-### `hasCapacitorConfigInRoot(root)`
-
-- **Сигнатура:** `(root: string) => boolean`
-- **Параметри:** `root` — корінь репозиторію.
-- **Повертає:** `true`, якщо хоча б один із файлів `capacitor.config.json`, `capacitor.config.ts`, `capacitor.config.mjs` існує в корені.
-- **Side effects:** виконує `existsSync` (синхронний доступ до файлової системи).
-
-### `isCapacitorRelevantForCheck(root, anyCapacitor)`
-
-- **Сигнатура:** `(root: string, anyCapacitor: boolean) => boolean`
-- **Параметри:** `root` — корінь; `anyCapacitor` — чи зустрічався `@capacitor/` у `package.json`.
-- **Повертає:** `true`, якщо є capacitor-конфіг у корені **або** `anyCapacitor === true`.
-- **Side effects:** виклик `hasCapacitorConfigInRoot` (`existsSync`).
-
-### `walkIosForPodfileSkipPods(root, dir, onPodfileRelative)`
-
-- **Сигнатура:** `(root: string, dir: string, onPodfileRelative: (rel: string) => void) => Promise<boolean>`
-- **Параметри:** `root` — корінь репозиторію; `dir` — поточний каталог обходу; `onPodfileRelative` — колбек із posix-relative шляхом знайденого `Podfile`.
-- **Повертає:** `Promise<boolean>` — `true`, якщо в дереві знайдено принаймні один `Podfile` (повернення відбувається при **першому** знайденому всередині поточного `dir` або в його підкаталогах).
-- **Логіка:**
-  - `readdir(dir, { withFileTypes: true })`; помилка → `false`.
-  - Пропускає підкаталоги/файли з іменами `Pods`, `build`, `DerivedData` (порівняння за іменем).
-  - Якщо запис — файл із іменем `Podfile`: викликає колбек із posix-relative шляхом і повертає `true` (ранній вихід — інші записи поточного каталогу не оглядаються).
-  - Якщо запис — каталог: рекурсивно входить; якщо нащадок повернув `true`, передається ланцюжком назовні.
-- **Side effects:** дисковий I/O (`readdir`), виклики `onPodfileRelative`.
-
-### `findFirstPodfileUnderIosExcludingPods(root)`
-
-- **Сигнатура:** `(root: string) => Promise<string | null>`
-- **Параметри:** `root` — корінь репозиторію.
-- **Повертає:** posix-relative шлях до першого виявленого `Podfile` під `ios/` (а саме — **найкоротший** із тих, що були передані в колбек у межах того самого виклику обходу) або `null`, якщо `ios/` немає чи в ньому не знайдено `Podfile` поза `Pods/`.
-- **Логіка:** перевіряє існування `ios/` через `existsSync`. Викликає `walkIosForPodfileSkipPods` з колбеком, який утримує лише шлях із мінімальною довжиною рядка (`rel.length < first.length`). Через ранній вихід `walkIosForPodfileSkipPods` зазвичай колбек спрацьовує один раз; вибір «найкоротшого» — захист на випадок зміни поведінки обходу.
-- **Side effects:** дисковий I/O.
-
-### `nitrAObjectAllowsIosCocoaPods(o)`
-
-- **Сигнатура:** `(o: unknown) => boolean`
-- **Параметри:** `o` — кандидат у об’єкт `nitra`.
-- **Повертає:** `true`, якщо `o` — звичайний об’єкт (не `null`, не масив) і містить `iosCocoaPodsBecausePluginsLackSpm === true` або `iosCocoaPodsAllowed === true`; інакше — `false`.
-- **Side effects:** немає.
-- **Зауваження:** назва функції написана з нестандартною капіталізацією `nitrA` — використовується саме так на місці виклику.
-
-### `extractNitraObjectBodySource(source)` _(внутрішня)_
-
-- **Сигнатура:** `(source: string) => string | null`
-- **Параметри:** `source` — текст файлу `capacitor.config.ts` або `capacitor.config.mjs`.
-- **Повертає:** підрядок `{ ... }`, що відповідає тілу об’єкта після `nitra:` / `"nitra":` / `'nitra':` (перше входження), збалансованому за фігурними дужками; `null`, якщо вхід не знайдено або не вдалося збалансувати дужки.
-- **Логіка:** `RE_NITRA_CONFIG_OBJECT_LEAD_IN.exec(source)` знаходить початок; далі вручну лічильник `d` балансу `{`/`}` від першої `{` до зустрічної `}` на нульовому рівні.
-- **Side effects:** немає.
-- **Обмеження:** не парсить TS/MJS повноцінно; ігнорує можливі `{` / `}` усередині рядків чи коментарів, що теоретично може дати хибний баланс на нетипових вхідних даних. Для штатних `capacitor.config.*` цього достатньо.
-
-### `nitraObjectBodyStringAllowsCocoaPodsExempt(objectBody)` _(внутрішня)_
-
-- **Сигнатура:** `(objectBody: string) => boolean`
-- **Параметри:** `objectBody` — текст тіла об’єкта `nitra`.
-- **Повертає:** `true`, якщо в підрядку є `iosCocoaPodsBecausePluginsLackSpm: true` або `iosCocoaPodsAllowed: true` (регулярки `RE_COCOAPODS_EXEMPT_SPM`, `RE_COCOAPODS_EXEMPT_ALLOW`).
-- **Side effects:** немає.
-
-### `pathJsonShowsNitraCocoapodsExempt(absPath)` _(внутрішня)_
-
-- **Сигнатура:** `(absPath: string) => Promise<boolean>`
-- **Параметри:** `absPath` — повний шлях до JSON-файла (`package.json` або `capacitor.config.json`).
-- **Повертає:** `true`, якщо файл існує, валідно парситься як JSON, і його ключ `nitra` задовольняє `nitrAObjectAllowsIosCocoaPods`.
-- **Логіка:** `existsSync` → `readFile` → `JSON.parse`. Будь-яка помилка читання/парсингу повертає `false`.
-- **Side effects:** дисковий I/O.
-
-### `capacitorConfigTsMjsNitraCocoapodsExempt(root)` _(внутрішня)_
-
-- **Сигнатура:** `(root: string) => Promise<boolean>`
-- **Параметри:** `root` — корінь репозиторію.
-- **Повертає:** `true`, якщо `capacitor.config.ts` або `capacitor.config.mjs` (у такій послідовності) існує та містить блок `nitra: { ... }` з прапором винятку.
-- **Логіка:** для кожного імені викликає `existsSync`, читає вміст, через `extractNitraObjectBodySource` дістає тіло і перевіряє `nitraObjectBodyStringAllowsCocoaPodsExempt`. Знайдено → `true`; інакше після обох — `false`.
-- **Side effects:** дисковий I/O. Винятки `readFile` не перехоплюються, тому пошкоджений файл може кинути помилку наверх (єдина функція в файлі, що не загортає `readFile` у `try/catch`).
-
-### `isIosCocoaPodsExemptByNitraConfig(root)` _(внутрішня)_
-
-- **Сигнатура:** `(root: string) => Promise<boolean>`
-- **Параметри:** `root` — корінь репозиторію.
-- **Повертає:** `true`, якщо знайдено валідний виняток `nitra` у `package.json`, або в `capacitor.config.json`, або в `capacitor.config.{ts,mjs}` (перевіряється в такому порядку, з раннім виходом).
-- **Side effects:** дисковий I/O.
+Модуль інспектує та збирає дані конфігурацій Capacitor для оцінки сумісності версій. Він використовується для перевірки наявності та відповідності версій Capacitor, необхідних для коректної роботи з iOS-проєктами. Функції, такі як `collectCapacitorDataFromAllPackageJson`, забезпечують збір необхідної інформації. Модуль спирається на конфігурації, визначені у файлі `.config.json`. Функція `check` та `isCapacitorRelevantForCheck` застосовуються для визначення релевантності конфігурації. (capacitor.mdc)
 
-### `check(cwd = process.cwd())`
+## Поведінка
 
-- **Сигнатура:** `(cwd?: string) => Promise<number>`
-- **Параметри:** `cwd` — корінь репозиторію для перевірки; за замовчуванням `process.cwd()`.
-- **Повертає:** exit-код від `reporter.getExitCode()`: **0** — усі повідомлення лише `pass`; **1** — було щонайменше одне `fail`.
-- **Side effects:**
-  - Створює reporter через `createCheckReporter()` і викликає `pass(...)` / `fail(...)` для друку повідомлень користувачу.
-  - Викликає `collectCapacitorDataFromAllPackageJson(root, acc)` — рекурсивний дисковий обхід усіх `package.json`.
-  - Викликає `findFirstPodfileUnderIosExcludingPods(root)` — обхід `ios/`.
-  - Викликає `isIosCocoaPodsExemptByNitraConfig(root)` лише якщо `podfileRel !== null` (мінімізує читання конфігів).
-- **Шлях виконання:**
-  1. `acc = { byPath: new Map(), anyCapacitor: false }`; зібрати дані з усіх `package.json`.
-  2. Якщо `isCapacitorRelevantForCheck(root, anyCapacitor) === false` — `pass('Capacitor не виявлено …')` і вихід **0**.
-  3. Інакше `pass('Проєкт з ознаками Capacitor — застосовую capacitor.mdc')`.
-  4. Якщо `byPath.size === 0` (є конфіг, але немає `@capacitor/core` у дереві) — `fail` з підказкою додати `^8.0.0`. Інакше — для кожної пари `[rel, range]` викликати `reportOneCapacitorCoreRange`.
-  5. Подія iOS:
-     - Якщо `findFirstPodfileUnderIosExcludingPods(root)` повернув `null` і `ios/` існує — `pass('ios/ без Podfile поза Pods/ …')`.
-     - Якщо `ios/` не існує — `pass('каталог ios/ не знайдено …')`.
-     - Якщо `Podfile` знайдено і `isIosCocoaPodsExemptByNitraConfig(root) === true` — `pass(... — дозволено виняток ...)`.
-     - Інакше — `fail(... використовуй лише SPM ...)`.
-  6. Повернути `getExitCode()`.
+capacitorSegmentMinMajor
+Витягує мінімальний мажорний номер з частини діапазону npm версій
 
-## Залежності
+capacitorVersionRangeMinMajor
+Обчислює мінімальний мажорний номер для повного діапазону npm версій з урахуванням `||`
 
-**Стандартна бібліотека Node.js:**
+isCapacitorCoreVersionAtLeast8
+Перевіряє, чи нижня межа версії Capacitor є більшою або дорівнює заданому мінімуму
 
-- `node:fs` — `existsSync` (синхронна перевірка існування файлу/каталогу).
-- `node:fs/promises` — `readdir` (з `withFileTypes: true`), `readFile` (utf-8).
-- `node:path` — `join`, `relative`.
+recordCapacitorFromOnePackageJson
+Записує інформацію про залежності Capacitor у накопичувач
 
-**Локальні модулі:**
+collectCapacitorDataFromAllPackageJson
+Рекурсивно шукає та збирає інформацію про залежності Capacitor з усіх `package.json` у репозиторії
 
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter` (фабрика об’єкта з `pass`, `fail`, `getExitCode`; формує консольний звіт і веде стан коду виходу).
+hasCapacitorConfigInRoot
+Перевіряє наявність конфігураційних файлів Capacitor у корені репозиторію
 
-**Зовнішні npm-пакети:** немає.
+isCapacitorRelevantForCheck
+Визначає, чи потрібно застосовувати перевірку Capacitor на основі наявності конфігурації або залежностей
 
-**Системні припущення:**
+walkIosForPodfileSkipPods
+Рекурсивно шукає файли `Podfile` у каталозі `ios`, ігноруючи папки `Pods`, `build` та `DerivedData`
 
-- Виклик відбувається з кореня репозиторію (або `cwd` передано явно).
-- Файлова система — POSIX-сумісна або Windows (всі шляхи нормалізуються через `replaceAll('\\', '/')` до posix-форми у звітах).
+findFirstPodfileUnderIosExcludingPods
+Шукає перший знайдений `Podfile` у каталозі `ios`, ухиляючись від кешу CocoaPods
 
-## Потік виконання / Використання
+nitrAObjectAllowsIosCocoaPods
+Перевіряє, чи дозволяє об'єкт `nitra` використання `Podfile` на iOS через спеціальні прапори
 
-Файл призначений для виклику як check-функція в межах CLI чи runner правил `npm/rules/capacitor`. Типовий сценарій:
+extractNitraObjectBodySource
+Витягує текст тіла об'єкта `{...}` після маркера `nitra:` у конфігураційному файлі
 
-1. Зовнішній runner імпортує `check` із `platforms.mjs`.
-2. Викликає `await check()` або `await check(repoRoot)`.
-3. Під час виконання у консоль друкуються рядки звіту через `createCheckReporter()` (pass/fail).
-4. Повернений Promise розв’язується числом `0` або `1`, яке runner передає в `process.exit(...)`.
+nitraObjectBodyStringAllowsCocoaPodsExempt
+Перевіряє, чи містить витягнутий текст виняток, який дозволяє пропуск аналізу SPM
 
-Приклад фактичного виклику (наприклад, у CLI-обгортці):
+pathJsonShowsNitraCocoapodsExempt
+Перевіряє, чи містить об'єкт `nitra` у JSON-файлі виняток, який дозволяє пропуск аналізу SPM
 
-```js
-import { check } from './platforms.mjs'
+capacitorConfigTsMjsNitraCocoapodsExempt
+Перевіряє, чи містить конфігураційні файли `.ts` або `.mjs` виняток, який дозволяє пропуск аналізу SPM
 
-const exitCode = await check(process.cwd())
-process.exit(exitCode)
-```
+isIosCocoaPodsExemptByNitraConfig
+Перевіряє, чи дозволяє конфігурація `nitra` використання `Podfile` на iOS
 
-Окремі експортовані функції зручні для модульних тестів і для повторного використання в інших правилах:
+check
+Виконує повну перевірку конфігурації Capacitor, включаючи перевірку залежностей та налаштувань iOS
 
-- `capacitorVersionRangeMinMajor`, `isCapacitorCoreVersionAtLeast8`, `capacitorSegmentMinMajor` — суто строкові утиліти без I/O; тести подають синтетичні діапазони.
-- `recordCapacitorFromOnePackageJson` і `collectCapacitorDataFromAllPackageJson` — інтеграційні утиліти над `package.json`; вимагають реальної або змодельованої файлової системи (через тимчасові теки тощо).
-- `walkIosForPodfileSkipPods`, `findFirstPodfileUnderIosExcludingPods` — обхід `ios/`.
-- `nitrAObjectAllowsIosCocoaPods` — чистий предикат для об’єкта `nitra`.
-- `hasCapacitorConfigInRoot`, `isCapacitorRelevantForCheck` — швидкі синхронні перевірки наявності конфігів.
+Повертає помилку, якщо не знайдено необхідної залежності `@capacitor/core` з версією, сумісною з `MIN_CAPACITOR_MAJOR`
 
-**Поведінкові інваріанти:**
+Повертає помилку, якщо знайдено `Podfile` на iOS, який не дозволяє використання CocoaPods без винятку `nitra`
 
-- Жоден `package.json`, який не валідується як JSON, не призводить до помилки `check`; такі файли мовчки пропускаються.
-- Каталоги з `IGNORED_DIRS_FOR_PACKAGE_JSON` ніколи не оглядаються, у тому числі `node_modules` — тобто аналізуються лише власні `package.json` репозиторію та воркспейсів, але не вкладені пакети залежностей.
-- Обхід `ios/` ніколи не входить у `Pods`, `build`, `DerivedData` — це принципово для коректної політики (SPM-only): артефакти CocoaPods, що могли залишитися від попередніх збірок, не повинні впливати на result.
-- Рішення «диапазон допустимий» приймається консервативно: будь-яка невизначеність (`*`, `latest`, неможливість витягти число) трактується як **не** допустимо.
-- Виняток для CocoaPods читається з трьох джерел у строгому порядку: `package.json` → `capacitor.config.json` → `capacitor.config.{ts,mjs}` (з раннім `true`).
+## Публічний API
 
-## Rebuild Test
+capacitorSegmentMinMajor — визначає нижню межу для однієї частини діапазону npm.
+capacitorVersionRangeMinMajor — визначає мінімальну можливу (нижню) major-версію для повного діапазону npm, включаючи `||`.
+isCapacitorCoreVersionAtLeast8 — перевіряє, чи відповідає версія ядру Capacitor мінімальному рівню 8.
+recordCapacitorFromOnePackageJson — записує дані Capacitor з одного файлу `package.json`.
+collectCapacitorDataFromAllPackageJson — збирає дані Capacitor з усіх `package.json` у дереві, накопичуючи `byPath` та `anyCapacitor`.
+hasCapacitorConfigInRoot — перевіряє наявність конфігурації Capacitor у кореневому файлі.
+isCapacitorRelevantForCheck — визначає, чи слід застосовувати правила, залежно від наявності конфігу або `@capacitor/` у залежностях.
+walkIosForPodfileSkipPods — рекурсивно шукає `Podfile` у директорії `ios/`, ігноруючи директорії `Pods` (кеш CocoaPods) та типові build-каталоги.
+findFirstPodfileUnderIosExcludingPods — знаходить перший `Podfile` у директорії `ios/`, пропуская директорії `Pods`.
+nitrAObjectAllowsIosCocoaPods — перевіряє, чи дозволяє об’єкт `nitra` використовувати `Podfile` (CocoaPods) на iOS (див. (capacitor.mdc); `@nitra/SPM` не аналізується).
+check — виконує загальну перевірку.
 
-Зібрані з цього документа ключові факти, достатні для відтворення поведінки:
+## Гарантії поведінки
 
-- Експортується `check(cwd?)` із поверненням `Promise<number>` (0/1) на основі `createCheckReporter`.
-- Capacitor вважається релевантним, якщо в корені є `capacitor.config.{json,ts,mjs}` **АБО** у будь-якому `package.json` (рекурсивно, ігноруючи `node_modules`, `.git`, `dist`, `coverage`, `Pods`, `.turbo`, `.next`, `build`) є залежність з префіксом `@capacitor/` у `dependencies` / `devDependencies` / `optionalDependencies` / `peerDependencies`.
-- Мінімальний допустимий major Capacitor — **8** (`MIN_CAPACITOR_MAJOR`).
-- Алгоритм обчислення мінімального major npm-діапазону:
-  - Розбити за `\s*\|\|\s*` на сегменти.
-  - У сегменті: `*` / `x` (low) / `latest` → невизначено (`null`), що означає fail для всього діапазону.
-  - `<` / `<=` → 0.
-  - `>` (не `>=`) → major першого числа після оператора.
-  - `a - b` (з `\s+-\s+`) → major лівої межі.
-  - `^`, `~`, `=` → major першого числа після префікса.
-  - `>=` → major першого числа після префікса.
-  - Інакше — major першого числа в сегменті.
-  - Регулярка для першого числа: `^(?:v)?(\d+)` (опційний `v`).
-  - Результат для діапазону — мінімум серед сегментів; якщо будь-який сегмент дав `null`, повертається `null`.
-- `isCapacitorCoreVersionAtLeast8(range)` ⇔ `capacitorVersionRangeMinMajor(range) >= 8`.
-- iOS-перевірка: знайти перший `Podfile` під `ios/`, пропускаючи `Pods`, `build`, `DerivedData`. Якщо знайдено — fail, **окрім** випадку, коли `package.json.nitra` або `capacitor.config.json.nitra` (як JSON-об’єкт) має `iosCocoaPodsBecausePluginsLackSpm === true` або `iosCocoaPodsAllowed === true`, **або** в `capacitor.config.ts` / `capacitor.config.mjs` фрагмент тіла об’єкта `nitra: { ... }` містить `iosCocoaPodsBecausePluginsLackSpm: true` чи `iosCocoaPodsAllowed: true`.
-- Якщо `ios/` немає — iOS-блок повністю пропускається (`pass` із поясненням).
-- Якщо capacitor-конфіг є, а `@capacitor/core` не знайдено в жодному `package.json` — fail (треба додати залежність з версією `^8.0.0`).
-- Помилки I/O і JSON у `package.json` / JSON-конфігах не падають check, а трактуються як «нічого не знайдено» в цій точці.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.
+- Не звертається до мережі.

package/rules/changelog/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/changelog/fix.mjs
+  crc: 12fc1644
+---
+
 # fix.mjs — точка входу правила `changelog`
 
 ## Огляд

package/rules/changelog/lib/docs/package-manifest.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/changelog/lib/package-manifest.mjs
+  crc: ced8ad49
+---
+
 # package-manifest.mjs
 
 ## Огляд

package/rules/ci4/docs/fix.md

@@ -1,179 +1,37 @@
-# fix.mjs — точка входу правила `ci4` (library + standalone CLI)
+---
+docgen:
+  source: npm/rules/ci4/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/ci4/fix.mjs` — це тонкий точка входу (entry-point) для правила з ідентифікатором `ci4`. Він не містить власної прикладної логіки перевірки/виправлення: уся робота делегується утиліті `runStandardRule`, яка реалізує стандартний послідовний конвеєр прогону правила:
-
-1. `applies` — перевірка, чи правило взагалі застосовне до поточного робочого дерева/конфігурації;
-2. `JS-concerns` — перевірки/виправлення, специфічні для JS/TS-аспектів правила;
-3. `policy` — політики (declarative rules), які описують стан, що має бути дотриманий;
-4. `mdc-refs` — перевірка відповідності правила супровідній `.mdc`-документації (посилання та узгодженість).
-
-Файл одночасно виконує дві ролі:
-
-- **library mode** — інші модулі (зокрема CLI-оркестратор `@nitra/cursor`) імпортують named-export `run(ctx)` і викликають його з готовим контекстом (наприклад, із `walkCache`, щоб не повторювати обхід дерева між правилами);
-- **standalone mode** — файл можна запустити напряму через `bun rules/ci4/fix.mjs`. У такому разі застосовується повноцінний CLI-обв'яз (`runRuleCli`): завантаження конфігурації, whitelist, підсумкова таблиця — фактично еквівалент команди `npx @nitra/cursor fix ci4`.
-
-Сам файл містить лише делегування й сторожовий блок для standalone-запуску, тому всі побічні ефекти (виведення в stdout, читання конфігів, мутації файлів проекту) ховаються всередині `runStandardRule` та `runRuleCli`.
-
-## Експорти / API
-
-| Експорт | Тип                                               | Призначення                                                                      |
-| ------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `run`   | named export, функція `(ctx?) => Promise<number>` | Library-entry для виклику правила `ci4` з оркестратора. Повертає exit-код (0/1). |
-
-Default export відсутній. CLI-режим не експортує нічого — він активується сайд-ефектом на top-level, коли модуль є точкою входу процесу.
-
-## Функції
-
-### `run(ctx)`
-
-**Сигнатура.**
-
-```js
-export function run(ctx)
-```
-
-**Параметри.**
-
-- `ctx` — `RuleContext` (опціональний). Тип посилається на `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Це контекст прогону правила: пере-використовувані ресурси, які оркестратор хоче поділити між правилами в межах одного запуску (наприклад, `walkCache` — закешований обхід файлової системи проекту, щоб уникнути повторного `fs.readdir`).
-- Параметр опціональний: якщо `ctx` не передано, `runStandardRule` створить/працюватиме без зовнішнього кешу.
-
-**Повертає.**
-
-- `Promise<number>` — exit-код прогону правила:
-  - `0` — правило не знайшло порушень або всі порушення були автоматично виправлені;
-  - `1` — є порушення, які залишилися після спроби виправлення (тобто правило вважається проваленим).
-
-**Що робить.**
-
-- Викликає `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент `import.meta.dirname` — абсолютний шлях до директорії правила (`npm/rules/ci4`); це використовується `runStandardRule`, щоб знайти супутні файли правила (наприклад, `check-*.mjs`, `mdc`-документацію, ID правила тощо).
-- Усі реальні дії (обхід проекту, читання/запис файлів, друк summary) виконуються всередині `runStandardRule` — у самому `run` побічних ефектів немає.
-
-**Side effects.**
-
-- Безпосередньо в коді функції — немає. Усі побічні ефекти (I/O, мутації файлів, лог у stdout) залежать від реалізації `runStandardRule` і застосованих check-ів правила `ci4`.
+# fix.mjs
 
-### Top-level standalone-блок (без імені)
-
-**Сигнатура (умовно).**
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-**Що робить.**
-
-- `isRunAsCli(import.meta.url)` визначає, чи модуль запущено напряму (а не імпортовано з іншого модуля). Реалізація — у `npm/scripts/lib/run-rule-cli.mjs`.
-- Якщо так — викликає `runRuleCli(import.meta.dirname)`, що дає той самий ефект, що й `npx @nitra/cursor fix ci4`: завантажує конфігурацію проекту, застосовує whitelist, друкує summary та повертає exit-код.
-- Результат передається в `process.exit(...)` — щоб CI/IDE отримали коректний код завершення.
-
-**Параметри / повертає.**
-
-- Не функція як така — це топ-рівневий `await` із умовою. Повертає невизначене значення в сенсі модуля, але впливає на процес через `process.exit`.
-
-**Side effects.**
-
-- Завершує Node/Bun-процес із кодом, який повернув `runRuleCli`.
-- Випуск `console.log`/`console.error` усередині `runRuleCli` (за реалізацією).
-- Можливі мутації файлів проекту, якщо правило підтримує auto-fix.
-
-**Лінт-винятки в коді.**
-
-- Рядок із `process.exit` вимкнено для двох правил ESLint:
-  - `n/no-process-exit` (плагін `eslint-plugin-n`) — забороняє прямий виклик `process.exit` у бібліотечному коді;
-  - `unicorn/no-process-exit` (плагін `eslint-plugin-unicorn`) — те саме застереження.
-- Причина (вказана в коментарі): standalone entry-point має повертати exit-code для CI/IDE — без `process.exit` Bun/Node міг би завершитися з ненульовим/нульовим кодом непослідовно.
-
-## Залежності
-
-### Внутрішні (відносні імпорти)
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - `isRunAsCli(importMetaUrl)` — детектор «модуль запущено напряму»;
-  - `runRuleCli(ruleDir)` — повний CLI-обв'яз для одного правила (config + whitelist + summary).
-- `../../scripts/lib/run-standard-rule.mjs`
-  - `runStandardRule(ruleDir, ctx?)` — стандартна послідовність `applies → JS-concerns → policy → mdc-refs`;
-  - JSDoc-тип `RuleContext` — структура контексту, який передається в `run`.
-
-### Зовнішні
-
-- Прямих зовнішніх npm-залежностей немає. Усі залежності — внутрішні модулі пакета `@nitra/cursor` (`npm/scripts/lib/...`).
-
-### Платформа
-
-- Очікується середовище Node.js/Bun з підтримкою:
-  - ESM-модулів (`import`/`export`, `import.meta.dirname`, `import.meta.url`);
-  - top-level `await` (для рядка `await runRuleCli(...)`);
-  - `process.exit` (Node/Bun).
-- `import.meta.dirname` потребує сучасних версій Node.js (≥ 20.11 / 21.2) або Bun, де ця властивість підтримується.
-
-## Потік виконання / Використання
-
-### Library mode (виклик з оркестратора)
+## Огляд
 
-1. Інший модуль (CLI-агрегатор правил, наприклад, диспетчер `@nitra/cursor fix`) імпортує named-export:
-   ```js
-   import { run } from '@nitra/cursor/rules/ci4/fix.mjs'
-   ```
-2. Підготовляє спільний контекст `ctx` (наприклад, спільний `walkCache`).
-3. Викликає:
-   ```js
-   const exitCode = await run(ctx)
-   ```
-4. `run` делегує виклик у `runStandardRule(ruleDir, ctx)`, який послідовно:
-   - перевіряє `applies` (чи правило застосовне);
-   - якщо так — виконує JS-concerns, policy, mdc-refs;
-   - агрегує результат і повертає 0/1.
-5. Оркестратор накопичує exit-коди по всіх правилах і визначає підсумковий статус прогону.
+Модуль виконує бізнес-процес трансформації даних. Використовується для перетворення вхідних даних відповідно до визначеного контракту. Функція run ініціює цей процес, який здійснює маппінг та трансформацію даних, повертаючи структуровану відповідь.
 
-### Standalone mode (CLI)
+## Поведінка
 
-1. Користувач/CI запускає файл напряму:
-   ```bash
-   bun npm/rules/ci4/fix.mjs
-   ```
-2. `isRunAsCli(import.meta.url)` повертає `true`, оскільки модуль є entry-point процесу.
-3. Викликається `runRuleCli(import.meta.dirname)`:
-   - завантажується конфігурація проекту;
-   - застосовується whitelist (які файли/директорії обходити);
-   - усередині використовується той самий `runStandardRule`, що й у library-режимі;
-   - друкується підсумкова таблиця (summary).
-4. Результат (0/1) передається в `process.exit(...)` — процес завершується відповідним кодом.
+1. Виклик функції run передає контекст прогону для виконання правила.
 
-Цей режим є повним функціональним еквівалентом команди:
+2. Виконання правила відбувається через стандартний механізм перевірки.
 
-```bash
-npx @nitra/cursor fix ci4
-```
+3. У режимі бібліотеки функція викликає основну логіку перевірки, яка включає застосування правил, перевірку конфігурації та формування посилань.
 
-### Інваріанти й типові помилки
+4. Якщо виконання відбувається у режимі командного рядка, функція виконує повний еквівалент інструментального прогону.
 
-- Файл свідомо порожній від прикладної логіки: будь-яка зміна поведінки правила `ci4` має робитися в супутніх файлах (`check-*.mjs`, `applies.mjs`, тощо) — а не тут.
-- Дві ролі (library + standalone) реалізовано в одному файлі навмисно — щоб уникнути дублікатів і щоб CLI-режим завжди узгоджувався з library-режимом.
-- Якщо файл імпортують як модуль (не як entry-point), `isRunAsCli` повертає `false` і блок `process.exit` не виконується — це дозволяє безпечно тестувати `run(ctx)` із юніт-тестів без зриву процесу.
+5. У режимі командного рядка функція виконує команду, яка включає завантаження конфігурації, перевірку дозволених елементів та формування зведення.
 
-## Rebuild Test
+6. У режимі командного рядка результат виконання передається для негайного завершення процесу, що використовується для інструментальних середовищ.
 
-Якщо файл відновлювати «з нуля» за цією документацією, мінімальна реалізація має містити:
+## Публічний API
 
-1. Імпорт `isRunAsCli, runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`.
-2. Імпорт `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-3. Named-export `run(ctx)`, який повертає `runStandardRule(import.meta.dirname, ctx)`.
-4. JSDoc для `run` з типом `ctx` (`RuleContext` із `run-standard-rule.mjs`) і `@returns {Promise<number>}`.
-5. Сторожовий блок:
-   ```js
-   if (isRunAsCli(import.meta.url)) {
-     process.exit(await runRuleCli(import.meta.dirname))
-   }
-   ```
-6. ESLint-disable коментар над `process.exit` для правил `n/no-process-exit` та `unicorn/no-process-exit` із поясненням, що standalone entry-point має повертати exit-code для CI/IDE.
+run — Запускає послідовність перевірок: applies до mdc-refs через policy та JS-concerns.
+Library mode — Викликається через CLI оркестрацію за допомогою імпорту та функції run.
 
-Поведінкові інваріанти, які мають бути збережені:
+## Гарантії поведінки
 
-- Імпорт модуля без запуску не повинен викликати `process.exit`.
-- `run()` без аргументів має працювати (опціональний `ctx`).
-- `run(ctx)` повертає саме те значення, яке повернув `runStandardRule`, без додаткової обробки.
-- Standalone-запуск має повертати той самий exit-код, що й `runRuleCli(...)`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.