@7n/test 0.9.0 → 0.10.1

package/src/docs/classify-exports.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: classify-exports.mjs
+resource: npm/src/classify-exports.mjs
+docgen:
+  crc: af4ad450
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Classifies named exports from a JS/MJS source file based on test-generation complexity. It directs exports—specifically via `extractExportsWithComplexity` and `NAME`—to appropriate LLMs: trivial/simple exports are sent to the local LLM, while complex ones are routed to the cloud LLM.
+
+## Поведінка
+
+Поведінка
+extractExportsWithComplexity визначає, які імпортовані елементи файлу класифікувати для подальшої обробки, згруповуючи їх за рівнем складності тестування.
+NAME визначає, які імпортовані елементи файлу класифікувати для подальшої обробки, згруповуючи їх за рівнем складності тестування.
+
+## Публічний API
+
+* extractExportsWithComplexity — Вибирає всі іменовані експорти та класифікує їх за складністю тестування.
+* NAME — Описує основну функцію цього файлу.
+
+## Гарантії поведінки
+
+* Read-only: не виконує операцій запису (ФС/БД).

package/src/docs/coverage-fix-extract.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: coverage-fix-extract.mjs
+resource: npm/src/coverage-fix-extract.mjs
+docgen:
+  crc: 1cfadb02
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Реалізує витягування даних про вцілілих мутантів із великого файлу `COVERAGE.md`. Цей компонент адаптує результати покриття коду, надаючи LLM-оркестратору невеликі, цільові порції інформації: або загальний індекс (`index`) для визначення фан-ауту, або контекст (`slice --file <path>`) для аналізу окремого файлу. Операція є виключно **read-only** — вона лише парсить, не виконує жодних змін у файловій системі. Компонент забезпечує високу стійкість, перехоплюючи можливі помилки (fail-safe) та не використовує кешування.
+
+## Поведінка
+
+Поведінка:
+parseSurvivedBlock витягує JSON-масив вцілілих мутантів з тексту `COVERAGE.md` на основі пошуку секції `## Вцілілі мутанти` та відповідного JSON-блоку.
+readSurvived читає вміст файлу `COVERAGE.md` із кореня проєкту та повертає структуровані групи вцілілих.
+buildIndex згортає структуровані групи вцілілих у компактний масив, що містить ім'я файлу та кількість вцілілих мутантів.
+runCoverageFixCli керує командним інтерфейсом, викликаючи відповідні функції для виведення компактного індексу або генерації промпта для одного файлу.
+
+## Публічний API
+
+- parseSurvivedBlock — Зчитує секцію `## Вцілілі мутанти` з `COVERAGE.md`, вибирає вміст першого блоку формату JSON та перетворює його на масив об'єктів.
+- readSurvived — Отримує з кореня проєкту вміст `COVERAGE.md` та структурує дані про вцілілих мутантів.
+- buildIndex — Агрегує структуровані групи вцілілих мутантів у компактний масив, де кожен елемент містить ім'я файлу та список мутантів, що в ньому вижили.
+- runCoverageFixCli — Інструмент командного рядка, який може вивести компактний JSON-масив індексу або, за вказаним шляхом, надати промпт для аналізу даних одного файлу, використовуючи лише `COVERAGE.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/docs/coverage-fix.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: coverage-fix.mjs
+resource: npm/src/coverage-fix.mjs
+docgen:
+  crc: 8b198273
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+При виклику команди `n coverage --fix`, система запускає pi-агента для автоматичного написання тестів, які покривають вцілілі мутанти Stryker. Агент аналізує контекст кожного мутанта, використовуючи спеціалізовані моделі (`CLOUD_MAX` або `N_CURSOR_COVERAGE_FIX_MODEL`), для створення відповідних тест-файлів. Процес ініціюється через публічні функції `fixSurvivedMutants` та `buildFixPrompt`. Дана робота є read-only; вона перехоплює потенційні помилки, використовуючи fail-safe механізми, і не генерує кешованих даних.
+
+## Поведінка
+
+Поведінка
+fixSurvivedMutants запускає pi-агента для генерації тестів, які покривають вцілілі мутанти Stryker, використовуючи наданий список мутантів та кореневий шлях проєкту.
+buildFixPrompt формує детальний промпт для агента, описуючи кожен вцілілий мутант разом із контекстом вихідного файлу.
+
+## Публічний API
+
+fixSurvivedMutants — запускає pi-агента для генерації юніт-тестів на основі вцілілих мутацій.
+buildFixPrompt — створює деталізований запит для агента, який містить список вцілілих мутантів, згрупованих за файлами, разом з контекстом з вихідного коду навколо кожної мутації.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/docs/coverage-per-file.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: coverage-per-file.mjs
+resource: npm/src/coverage-per-file.mjs
+docgen:
+  crc: 54eea127
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл виконує повне вимірювання покриття коду за допомогою Vitest у єдиному проході. Він повертає дані про покриття для кожного файлу, а також список тестів, які не пройшли. Це забезпечує можливість контролю за рівнем тестового покриття окремих частин кодової бази. Додаткові можливості дозволяють виявляти файли вихідного коду та визначати ті, що не відповідають встановленим вимогам покриття. Для коректної роботи коду необхідна конфігурація у файлі test-results.json.
+
+## Поведінка
+
+Поведінка
+measureCoveragePerFile запускає Vitest з генерацією покриття та звітністю у форматі JSON у єдиному проході, повертаючи дані про покриття по файлах та список тестів, що не пройшли. При цьому ігноруються папки та файли, такі як node_modules та .git, і винятки у процесі вимірювання обробляються, не викликаючи збоїв.
+getUncoveredFiles відфільтровує файли, покриття яких нижче заданого порогового значення.
+findSourceFiles рекурсивно знаходить усі файли вихідного коду в заданому каталозі, виключаючи тестові файли та директорії, визначені як ігнорувані.
+
+## Публічний API
+
+- measureCoveragePerFile — Вимірює покриття коду за файлами, збираючи результати покриття Vitest та логуючи провалені тести за один прохід.
+- getUncoveredFiles — Повертає список файлів, які не досягли встановленого порогу покриття.
+- findSourceFiles — Рекурсивно шукає файли вихідного коду в директорії, ігноруючи тестові файли та проігноровані каталоги, використовуючи це для ініціалізації у разі відсутності даних про покриття.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/src/docs/fix-tests.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: fix-tests.mjs
+resource: npm/src/fix-tests.mjs
+docgen:
+  crc: b807d1bc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль виявляє падаючі юніт-тести, запускаючи `vitest run --reporter=json` для збору помилок з конфігураційного файлу `results.json`. Подалі, він ітерує через виявлені файли, використовуючи текстовий режим pi SDK для отримання виправленого коду, який записується напряму, повторюючи спроби до досягнення `MAX_FIX_ATTEMPTS`. Процес реалізований з механізмом перехоплення помилок (`fail-safe`), щоб не кидати винятків.
+
+## Поведінка
+
+Поведінка:
+getFailingTests виявляє падаючі юніт-тести, запускаючи vitest у JSON-режимі та повертаючи список цих файлів разом з повідомленнями про помилки.
+buildFixTestsPrompt створює деталізований текстовий промпт, що містить поточний вміст падаючих тест-файлів та відповідні вихідні файли, для інструмента LLM.
+fixFailingTests ітерує через падаючі тести, отримує виправлення від LLM за допомогою текстового режиму pi SDK та записує оновлений код напряму у відповідні файли, повторюючи спроби до MAX_FIX_ATTEMPTS.
+
+## Публічний API
+
+- getFailingTests — Виконує тестування за допомогою Vitest у форматі JSON і повертає файли тестів з помилками, що не пройшли.
+- buildFixTestsPrompt — Створює спеціальне повідомлення (prompt) для виправлення одного файлу, що не пройшов тест, включаючи вміст поточного файлу.
+- fixFailingTests — Знаходить та виправляє помилкові тести, використовуючи текстовий режим SDK pi та пряме записування файлів.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/docs/gen-tests.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: gen-tests.mjs
+resource: npm/src/gen-tests.mjs
+docgen:
+  crc: f8507a21
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл відповідає за генерацію тестових файлів шляхом застосування стратегії багатоступеневого маршрутизації до кожного публічного експорту. Спочатку він визначає правила тестування та класифікує експорти за складністю, направляючи прості випадки на локальну модель $\text{pi}$ та складні — у хмару. Всі взаємодії з моделями ініціюються через $\text{pi SDK}$, а система використовує механізм захисту від збоїв, повертаючи порожнє значення замість винятків, особливо при відсутності конфігурації локальної моделі.
+
+## Поведінка
+
+findTestRules знаходить конфігурацію правил для тестів, обходячи каталог до 4 рівнів вгору.
+startRe — регулярний вираз для виявлення викликів верхнього рівня, які виконуються як side-effect при завантаженні модуля.
+fetchCalls — функція для перехоплення та виявлення всіх реальних викликів до функції `fetch` у модулі.
+usedHelpers — функція для визначення та збору інформації про внутрішні допоміжні функції, які використовуються у публічних експортах.
+buildGenTestsPrompt генерує зведений опис для генерації тестів, подаючи вміст кількох файлів для аналізу.
+generateTests генерує тестові файли для наданого списку модулів, використовуючи багатоступеневий підхід: спочатку підхід з окремим описом для кожного експорту, задіявши локальну модель, а потім як запасний варіант — генерацію одного файлу.
+
+## Публічний API
+
+* findTestRules — Знаходить набір правил для тестів проєкту, піднімаючись на 4 рівня вище від поточної директорії.
+* startRe — Ініціює процес повторного запуску.
+* fetchCalls — Збирає список викликів.
+* usedHelpers — Перелічує використані допоміжні функції.
+* buildGenTestsPrompt — Формує для відображення стислий опис (використовується у тестах).
+* generateTests — Створює тести для всіх наданих файлів. При наявності локальної LLM використовує маршрутизацію за рівнями експорту, інакше — генерує для кожного файлу окремо.
+
+## Гарантії поведінки
+
+* Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+* За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/src/docs/index.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: index.js
+resource: npm/src/index.js
+docgen:
+  crc: b4a27890
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Я — технічний письменник, і я створю контент, який відповідає вашим вимогам: лаконічний, поведінковий, українською, у чистому Markdown, без сигнатур, типів, параметрів, вступів та висновків, без обгортки в ```.
+
+Оскільки я маю переписати секцію "overview" з чорнетки, враховуючи відомі факти (публічна функція `run`, **немає** кешування) та зауваження редактора, я оновлю текст.
+
+Ось оновлений текст:
+
+Файл забезпечує механізм виконання тестування в заданій директорії. Інтерпретуючи аргументи командного рядка, він визначає цільову область аналізу та керує режимами виконання тестування, включаючи можливість відключення мутаційного тестування. Результати виконання доступні через публічну функцію `run`.
+
+## Поведінка
+
+1. Викликається функція `run`.
+2. Функція визначає наявність прапорців для допомоги або для вимкнення фази мутацій.
+3. Якщо виявлено прапорці для допомоги, виводиться повідомлення про використання інструменту.
+4. Інакше, інструмент визначає директорію для аналізу: або використовується перший позиційний аргумент, або поточна робоча директорія.
+5. Визначається прапорець, що відключає мутаційне тестування.
+6. Ініціюється виконання автоматичного тестування у вказаній директорії з урахуванням прапорця про вимкнення мутацій.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/src/docs/run.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: run.mjs
+resource: npm/src/run.mjs
+docgen:
+  crc: b932be1d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.95
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Main auto-test loop забезпечує автоматизований цикл тестування з метою підвищення покриття коду. У першій фазі відбувається вимірювання покриття коду по файлах через vitest+lcov. Якщо покриття нижче заданого порогу, генеруються тести для відповідних файлів. Процес повторюється, доки покриття не досягне максимуму або не буде досягнуто обмежень ітерацій. Друга фаза включає мутаційне тестування, яке проводиться з використанням існуючих провайдерів покриття, залежність від .n-cursor.json. Після виявлення виживших мутантів, pi agent автоматично їх виправляє. Функція runAutoTest перехоплює можливі помилки, запобігаючи виняткам на виході, але не виконує кешування.
+
+## Поведінка
+
+Поведінка
+
+1. Викликається `runAutoTest` для запуску циклу автоматичного тестування.
+2. У циклі до п'яти ітерацій вимірюється покриття кожної функції у проекті.
+3. Якщо існують падіння тестів, вони автоматично виправляються через агент, і цикл продовжується.
+4. Якщо немає тестів, відбувається запуск процесу Bootstrap: скануються вихідні файли, класифікуються, і для тих, що потребують тестів, генеруються початкові тести.
+5. Обчислюється загальне покриття. Якщо воно досягло встановленого порогу, цикл зупиняється.
+6. Якщо покриття не покращилося порівняно з попередньою ітерацією, цикл зупиняється.
+7. Якщо покриття недостатнє, генеруються тести для некритичних файлів і цикл повторюється.
+8. Після завершення циклу, якщо не вказано інакше, запускається мутаційне тестування, яке залежить від конфігурації в `.n-cursor.json`.
+9. У разі успішного виживання мутантів, виконується повторний запуск покриття для перевірки.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).