@nitra/cursor 5.3.4 → 5.4.0

package/rules/npm-module/docs/fix.md

@@ -1,98 +1,36 @@
-# fix.mjs — точка входу правила `npm-module`
+---
+docgen:
+  source: npm/rules/npm-module/fix.mjs
+  crc: 38cf876b
+  score: 100
+---
 
-## Огляд
-
-`fix.mjs` — мінімалістична точка входу (entry-point) для правила з ідентифікатором, що відповідає назві теки, у якій файл розташований (`npm/rules/npm-module/`). Файл виконує дві ролі одночасно:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає оркестратор `npm/scripts/lib/run-standard-rule.mjs` через стандартний імпорт. Це дозволяє іншому коду (наприклад, агрегатору правил `@nitra/cursor`) виконувати правило у складі загального прогону.
-2. **Standalone mode** — якщо файл стартує напряму (наприклад, `bun npm/rules/npm-module/fix.mjs`), він прогорає еквівалент команди `npx @nitra/cursor fix npm-module` через `runRuleCli` із завантаженням конфігу, whitelist та фінальним summary; повертає у процес коректний exit-code для CI/IDE.
-
-Логіки самого правила тут немає — файл лише делегує виконання у стандартний раннер `runStandardRule`, який послідовно проганяє чотири фази правила: `applies` → `JS-concerns` → `policy` → `mdc-refs`.
-
-## Експорти / API
-
-| Назва | Тип                                  | Призначення                                                                                                                                                                                                |
-| ----- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run` | `function (ctx?) => Promise<number>` | Іменований експорт для library-mode. Викликає `runStandardRule` зі шляхом до теки правила та опційним контекстом. Повертає Promise з exit-кодом: `0` — правило не зафіксувало порушень, `1` — є порушення. |
-
-Дефолтних експортів немає. Side-effect верхнього рівня: за умови запуску як CLI, наприкінці модуля викликається `process.exit(...)` з кодом, який повернув `runRuleCli`.
-
-## Функції (сигнатура / параметри / повертає / side effects)
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Параметри**
-  - `ctx` _(опційний)_ — об'єкт типу `RuleContext`, імпортований з `../../scripts/lib/run-standard-rule.mjs`. Може містити, зокрема, `walkCache` (закешований обхід дерева файлів), щоб уникнути повторного walk при паралельному прогоні кількох правил.
-- **Повертає** `Promise<number>`:
-  - `0` — правило не виявило порушень або не застосовується до поточного workspace.
-  - `1` — зафіксовано принаймні одне порушення.
-- **Side effects**
-  - Жодних прямих побічних ефектів у самій `run`. Усі побічні ефекти (читання файлів, друк summary, мутація `walkCache`) — у `runStandardRule` та підлеглих фазах правила.
-- **Реалізація**
-
-  ```js
-  return runStandardRule(import.meta.dirname, ctx)
-  ```
+# fix.mjs
 
-  `import.meta.dirname` дає абсолютний шлях до теки правила (`.../npm/rules/npm-module/`); цей шлях `runStandardRule` використовує як корінь для пошуку фаз правила (`applies.mjs`, `js/`, `policy.mjs`, `mdc-refs.mjs` тощо).
-
-### Standalone-блок (без іменованої функції)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Умова** — `isRunAsCli(import.meta.url)` повертає `true`, якщо модуль є точкою входу процесу (а не імпортується іншим модулем).
-- **Дія** — `await runRuleCli(import.meta.dirname)` виконує повний CLI-цикл (config-loading, whitelist, прогін правила, summary) і повертає exit-код. Цей код передається у `process.exit`.
-- **Коментар у коді** свідомо вимикає правила лінтера `n/no-process-exit` та `unicorn/no-process-exit`, оскільки standalone-entry-point має повертати exit-код для CI/IDE.
-
-## Залежності
-
-Прямі (внутрішні) залежності — два модулі зі спільної бібліотеки скриптів проєкту:
-
-| Шлях імпорту                              | Що бере                                            | Призначення                                                                                                                                                                         |
-| ----------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                         | Допоміжна логіка для роботи у standalone-режимі: визначення, чи модуль є entry-point процесу, і запуск повного CLI-циклу правила, який є еквівалентом `npx @nitra/cursor fix <id>`. |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`, тип `RuleContext` (через JSDoc) | Уніфікований раннер чотирифазного правила (`applies → JS-concerns → policy → mdc-refs`). Через нього прогрівається walk-cache і виконуються фази у фіксованому порядку.             |
-
-Зовнішніх (npm) залежностей файл не має. Він спирається на Node.js / Bun рантайм-можливості:
-
-- `import.meta.url` — для визначення, чи модуль запущений як CLI.
-- `import.meta.dirname` — для отримання абсолютного шляху до теки правила.
-- `process.exit` — для повернення exit-коду у standalone-режимі.
-
-## Потік виконання / Використання
-
-### Сценарій A: Library mode (через оркестратор `@nitra/cursor`)
+## Огляд
 
-1. Оркестратор імпортує модуль: `const mod = await import('npm/rules/npm-module/fix.mjs')`.
-2. `isRunAsCli(import.meta.url)` повертає `false` (модуль не є entry-point) — standalone-блок ігнорується.
-3. Оркестратор викликає `await mod.run(ctx)`, передаючи спільний `RuleContext` (наприклад, з заздалегідь побудованим `walkCache`).
-4. `run` делегує виконання `runStandardRule(import.meta.dirname, ctx)`, який проганяє чотири фази правила і повертає `0` або `1`.
-5. Оркестратор агрегує exit-коди всіх правил у фінальний код процесу.
+Виконує обробку JS-занепокоєних на наданому контексті прогону, застосовує політику [Політика_X] та генерує посилання MDC.
 
-### Сценарій B: Standalone mode
+## Поведінка
 
-1. Користувач запускає `bun npm/rules/npm-module/fix.mjs` (еквівалент `npx @nitra/cursor fix npm-module`).
-2. Модуль завантажується як entry-point — `isRunAsCli(import.meta.url)` повертає `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - завантажується конфіг (`.cursor`/проектні налаштування),
-   - застосовується whitelist (якщо є),
-   - запускається чотирифазне правило,
-   - друкується summary з кількістю порушень.
-4. Повернутий exit-код передається у `process.exit(...)`, що завершує процес. CI/IDE отримує `0` (успіх) або `1` (порушення).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
+2. Виконання у режимі CLI.
+    *   Виконується як автономний скрипт.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Повертає код виходу з процесу.
 
-### Контракт двох ролей
+## Публічний API
 
-Дизайн «library + standalone в одному файлі» є типовим для правил `@nitra/cursor`:
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-- Функція `run` — публічний API для оркестратора; вона **не** викликає `process.exit` і не друкує summary, лише повертає код.
-- Standalone-блок навпаки відповідає за повноцінний CLI-UX: завантаження конфігу, whitelist, summary, exit-code — усе, що очікується від `fix.mjs` правила, який запускається окремо.
+## Гарантії поведінки
 
-Завдяки цьому контракту той самий файл інтегрується і у пакетний прогін правил, і в локальне налагодження одного правила без дублювання логіки.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/npm-module/js/docs/header_doc_pointer.md

@@ -1,32 +1,32 @@
 ---
 docgen:
   source: npm/rules/npm-module/js/header_doc_pointer.mjs
-  crc: 9058c4ea
+  crc: d96a2957
+  score: 100
 ---
 
 # header_doc_pointer.mjs
 
 ## Огляд
 
-Концерн правила `npm-module`, що закріплює контракт між `docs/<stem>.md` і module-level JSDoc у скриптах правил і скілів. Якщо файл вже описано у `docs/<stem>.md` — наратив у заголовному коментарі файлу є дублюванням і заборонений. Якщо `docs` немає — header залишається єдиним джерелом опису поведінки і жодних обмежень немає.
+Файл виконує перевірку документації для модулів. Сканує директорії npm/rules та npm/skills. Перевіряє наявність файлів docs/<stem>.md у піддиректоріях правил/скілів. Перевіряє, чи містить відповідні js-файли не більше одного рядка JSDoc. У разі перевищення ліміту, генерує звіт про порушення.
 
 ## Поведінка
 
-1. Сканує всі `.mjs`-файли (крім `.test.mjs`) у `npm/rules/*/js/` та `npm/skills/*/js/`.
-2. Для кожного файлу перевіряє наявність `docs/<stem>.md` поруч із `js/`.
-3. Якщо `docs/<stem>.md` **відсутній** — пропускає файл: перевірка не застосовується.
-4. Якщо `docs/<stem>.md` **присутній** — знаходить module-level JSDoc (перший `/** ... */` до першого `import`/`export` на початку рядка).
-5. Рахує непорожні змістовні рядки блоку (після зрізання відступу `*`). Більше одного → порушення.
+1. Сканувати директорії npm/rules та npm/skills.
+2. Для кожної директорії перевіряти піддиректорії правил/скілів.
+3. Для кожного знайденого js-файлу перевіряти наявність файлу docs/<stem>.md.
+4. Якщо файл docs/<stem>.md існує, перевіряти, чи містить module-level JSDoc не більше одного непорожного рядка.
+5. У разі перевищення ліміту, зарепортувати порушення.
+6. Повертати код виходу репортера.
 
-Допустимі форми при наявних docs:
+## Публічний API
 
-- відсутній module-level JSDoc (0 рядків)
-- `/** @see ./docs/<stem>.md */` (1 рядок)
-- `/** Контракт: ./docs/<stem>.md */` (1 рядок)
+- check — сканує файли `npm/rules/*/js/*.mjs` та `npm/skills/*/js/*.mjs`.
+  - Якщо існує `docs/<stem>.md`, модуль повинен мати посилання на JSDoc (не наратив).
+  - Якщо `docs` відсутній, обмеження не застосовуються.
 
 ## Гарантії поведінки
 
-- Файли без `docs/`-відповідника повністю ігноруються — перевірка не створює обмежень до того, як docgen запишеться.
-- Якщо у файлі немає жодного module-level JSDoc — перевірка проходить.
-- Тестові файли (`*.test.mjs`) не скануються.
-- Підкаталоги `tests/`, `data/`, `templates/` у `js/` не скануються (discovery бере лише `*.mjs` безпосередньо в `js/`, не рекурсивно).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/npm-module/js/docs/package_structure.md

@@ -1,274 +1,52 @@
+---
+docgen:
+  source: npm/rules/npm-module/js/package_structure.mjs
+  crc: 943e3b76
+  score: 85
+---
+
 # package_structure.mjs
 
 ## Огляд
 
-Модуль `package_structure.mjs` — це checker правила `npm-module.mdc` у пакеті `@nitra/cursor`. Він валідує структуру npm-модуля в монорепо: наявність каталогу `npm/`, файлу `npm/package.json`, конфігурації hk (`hk.pkl` або `.config/hk.pkl`), workflow `npm-publish.yml`, та узгодженість TypeScript-emit (поле `types`, генерація `index.d.ts`, виклик `tsc` у pre-commit hook).
-
-Модуль підтримує два альтернативні layout-и npm-модуля:
-
-1. **`npm/src` + `.js`-файли** — канонічний layout зі згенерованим `npm/types/index.d.ts` через `tsc` з прапорцями `--declaration --allowJs --emitDeclarationOnly --outDir types --skipLibCheck`.
-2. **`npm/tsconfig.emit-types.json`** — коли `.js`-файлів під `npm/src` немає; типи виганяються через `tsc -p tsconfig.emit-types.json`.
-
-Окремо модуль контролює, щоб опублікований пакет (`npm pack`) не містив тестів і фікстур: сканує каталог `npm/` за полем `"files"` з `package.json` (з урахуванням негативних glob-патернів) і відсіює test-style каталоги, імена файлів та AST-імпорти test-фреймворків.
-
-Деякі перевірки (структура `npm/package.json`, валідація `compilerOptions` у `tsconfig.emit-types.json`, валідація полів `npm-publish.yml`) делеговані Rego-полісі у `npm/policy/npm_module/`. У цьому файлі лишається лише cross-file / FS / AST-частина: чи реально існує файл на диску, чи містить опублікований tarball тести, чи має `hk.pkl` правильні підрядки команди `tsc`.
-
-Узгодженість `version`/`CHANGELOG.md` у файлі **не** перевіряється — це робить `changelog/js/consistency.mjs` за моделлю `n-changelog.mdc`.
-
-## Експорти / API
-
-| Експорт                                         | Тип              | Призначення                                                                                                                |
-| ----------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `globToRegex(glob)`                             | `function`       | Перетворює glob-патерн на `RegExp` із якорями `^` / `$`; підтримує `**`, `*`, `?`, `{a,b,c}`.                              |
-| `findTestFrameworkImport(content, virtualPath)` | `async function` | Парсить JS/TS через `oxc-parser` і повертає назву модуля test-фреймворку, якщо знайдено import / require / dynamic import. |
-| `classifyPublishedFileAsTest(relPath, cwd?)`    | `async function` | Класифікує файл як test/fixture за каталогом, basename або AST-імпортом.                                                   |
-| `check(cwd?)`                                   | `async function` | Головна точка входу checker-а правила `npm-module.mdc`; повертає exit-code `0` / `1`.                                      |
-
-Решта функцій (`npmSrcTreeHasJsFile`, `readHkConfig`, `missingHkSrcLayoutFragments`, `missingHkEmitTypesConfigFragments`, `npmTypesFileFromPackageField`, `checkNpmPackageJson`, `checkEmitTypesConfig`, `checkPublishWorkflow`, `collectPublishedFiles`, `checkNoTestsInPublishedFiles`, `checkNpmModuleBasicStructure`) — приватні для модуля.
-
-## Константи
-
-| Константа                | Значення / Опис                                                                                                      |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `EMIT_TYPES_CONFIG`      | `'npm/tsconfig.emit-types.json'` — шлях до TS-config для emit без `src`.                                             |
-| `TEST_DIR_NAMES`         | `Set` з `'tests'`, `'__tests__'`, `'fixtures'`, `'__fixtures__'`, `'spec'`, `'test'`.                                |
-| `TEST_FILE_PATTERNS`     | `[/^.+\.(test                                                                                                        | spec)\.[cm]?[jt]sx?$/iu]` — патерн test-файлів за basename. Rego-файли (`\*\_test.rego`) свідомо не входять (conftest-конвенція). |
-| `JS_LIKE_EXT_RE`         | `/\.[cm]?[jt]sx?$/iu` — розширення, у яких сканується AST на імпорти test-фреймворків.                               |
-| `TEST_FRAMEWORK_MODULES` | `Set` з `'bun:test'`, `'node:test'`, `'vitest'`, `'@jest/globals'`, `'jest'`, `'mocha'`, `'ava'`, `'tap'`, `'tape'`. |
-| `REGEX_SPECIAL_IN_GLOB`  | `Set` спецсимволів regex, які екрануються у glob-сегменті (без `*`/`?`).                                             |
-| `GLOBSTAR_LEADING_RE`    | `/^__GLOBSTAR__\//u` — маркер `**/` на початку.                                                                      |
-| `GLOBSTAR_TRAILING_RE`   | `/\/__GLOBSTAR__$/u` — маркер `/**` у кінці.                                                                         |
-
-## Функції
-
-### `npmSrcTreeHasJsFile(cwd, ignorePaths = [])`
-
-- **Сигнатура:** `async (cwd: string, ignorePaths?: string[]) => Promise<boolean>`
-- **Параметри:**
-  - `cwd` — корінь репозиторію.
-  - `ignorePaths` — абсолютні шляхи каталогів, повністю виключених з обходу (з `loadCursorIgnorePaths`).
-- **Повертає:** `true`, якщо хоча б один `.js` під `npm/src` (рекурсивно); інакше `false`. Якщо `npm/src` не існує — одразу `false`.
-- **Side effects:** жодних (тільки FS-читання).
-
-### `readHkConfig(cwd)`
-
-- **Сигнатура:** `async (cwd: string) => Promise<{ path: string, text: string } | null>`
-- **Параметри:** `cwd` — корінь репозиторію.
-- **Повертає:** обʼєкт із relative-шляхом (`hk.pkl` або `.config/hk.pkl`) і повним текстом файлу; `null`, якщо жоден кандидат не існує.
-- **Side effects:** читання файлу через `readFile`.
-
-### `missingHkSrcLayoutFragments(hkText)`
-
-- **Сигнатура:** `(hkText: string) => string[]`
-- **Параметри:** `hkText` — текст hk-конфігурації.
-- **Повертає:** список фрагментів, яких немає в тексті. Очікувані фрагменти: `["pre-commit"]`, `bunx -p typescript tsc`, `src/**/*.js`, `--declaration`, `--allowJs`, `--emitDeclarationOnly`, `--outDir types`, `--skipLibCheck`.
-- **Side effects:** немає.
-
-### `missingHkEmitTypesConfigFragments(hkText)`
-
-- **Сигнатура:** `(hkText: string) => string[]`
-- **Параметри:** `hkText` — текст hk-конфігурації.
-- **Повертає:** список відсутніх фрагментів для layout-у через `tsconfig.emit-types.json`: `["pre-commit"]`, `bunx -p typescript tsc`, `tsconfig.emit-types.json`.
-- **Side effects:** немає.
-
-### `npmTypesFileFromPackageField(typesField)`
-
-- **Сигнатура:** `(typesField: unknown) => string | null`
-- **Параметри:** `typesField` — значення поля `types` з `npm/package.json`.
-- **Повертає:** posix-шлях `npm/<rel>` (наприклад, `npm/types/bin/x.d.ts`) або `null`, якщо значення не починається з `./types/` чи не є рядком.
-- **Side effects:** немає.
-
-### `checkNpmPackageJson(useSrcJsLayout, passFn, failFn, cwd)`
-
-- **Сигнатура:** `async (useSrcJsLayout: boolean, passFn, failFn, cwd: string) => Promise<void>`
-- **Поведінка:**
-  - Якщо `npm/package.json` відсутній — нічого не робить (вище у потоці це вже відловлено).
-  - Для layout `src+js`: очікує існування `npm/types/index.d.ts`.
-  - Для layout `emit-types`: бере `npm/<types-field>` і перевіряє існування.
-- **Викликає:** `passFn(msg)` при успіху, `failFn(msg)` при помилці.
-- **Side effects:** читає `npm/package.json`.
-
-### `checkEmitTypesConfig(passFn, failFn, cwd)`
-
-- **Сигнатура:** `(passFn, failFn, cwd: string) => void`
-- **Поведінка:** перевіряє лише існування `npm/tsconfig.emit-types.json`. Структуру `compilerOptions` валідує Rego-полісі `npm_module/emit_types_config`.
-
-### `checkPublishWorkflow(passFn, failFn, cwd)`
-
-- **Сигнатура:** `(passFn, failFn, cwd: string) => void`
-- **Поведінка:** перевіряє лише існування `.github/workflows/npm-publish.yml`. Структуру полів workflow валідує Rego-полісі `npm_module/npm_publish_yml`.
-
-### `globToRegex(glob)` (експортована)
-
-- **Сигнатура:** `(glob: string) => RegExp`
-- **Параметри:** `glob` — posix-шлях у glob-нотації.
-- **Повертає:** `RegExp` з якорями `^` / `$` і прапорцем `u`.
-- **Підтримка синтаксису:**
-  - `**` — нуль або більше сегментів (`(?:/.*/|/)` між сегментами, `(?:.*/)?` на початку, `(?:/.*)?` у кінці, `.*` як єдиний токен).
-  - `*` — будь-які символи без `/` (`[^/]*`).
-  - `?` — один символ без `/` (`[^/]`).
-  - `{a,b,c}` — brace-альтернативи (`(?:a|b|c)`).
-- **Не підтримує:** клас `[…]` (для негативних патернів `files` цього достатньо).
-- **Safety:** усі спецсимволи екрануються через `REGEX_SPECIAL_IN_GLOB`; eslint правило `security/detect-non-literal-regexp` явно вимкнено, бо вхід контрольований (поле `files` з `npm/package.json`).
-
-### `collectPublishedFiles(filesField, cwd)`
-
-- **Сигнатура:** `async (filesField: string[], cwd: string) => Promise<string[]>`
-- **Параметри:**
-  - `filesField` — значення поля `files` з `npm/package.json`.
-  - `cwd` — корінь репозиторію.
-- **Алгоритм:**
-  1. Розділяє patterns на позитивні і негативні (за префіксом `!`).
-  2. Для кожного позитивного pattern: якщо це файл — додає до `collected`; якщо директорія — рекурсивно через `walkDir` додає всі знайдені файли (posix-шляхи без `npm/` префікса).
-  3. Фільтрує: викидає файли, які матчать будь-який негативний `globToRegex`.
-  4. Сортує `[].sort()` (лексикографічно) і повертає.
-- **Side effects:** `stat()` для кожного позитивного pattern, `walkDir` для директорій.
-- **Обмеження:** не дублює всю логіку `npm pack` (LICENSE / README / mandatory files); сканує лише простір імен `files`.
-
-### `findTestFrameworkImport(content, virtualPath)` (експортована)
-
-- **Сигнатура:** `(content: string, virtualPath: string) => string | null`
-- **Параметри:**
-  - `content` — повний текст файлу.
-  - `virtualPath` — шлях файлу (для вибору `lang` через `langFromPath`).
-- **Повертає:** ім'я модуля test-фреймворку (з `TEST_FRAMEWORK_MODULES`), якщо знайдено; `null` інакше.
-- **Алгоритм:**
-  1. Парсить через `parseSync` із `oxc-parser`; при помилці парсингу — повертає `null` (це не AST-checker для синтаксису).
-  2. Якщо `result.errors.length` ≠ 0 — повертає `null`.
-  3. Спочатку перевіряє `result.module.staticImports`.
-  4. Якщо в static-import не знайдено — обходить AST через `walkAstWithAncestors` і шукає `require(...)` (через `requireCallModule`) та `import(...)` dynamic (через `dynamicImportModule`).
-- **Side effects:** немає.
-
-### `classifyPublishedFileAsTest(relPath, cwd = process.cwd())` (експортована)
-
-- **Сигнатура:** `async (relPath: string, cwd?: string) => Promise<string | null>`
-- **Параметри:**
-  - `relPath` — posix-шлях відносно `npm/`.
-  - `cwd` — корінь репозиторію (за замовчуванням `process.cwd()`).
-- **Повертає:** рядок-причину порушення або `null`, якщо файл валідний.
-- **Класифікація (за пріоритетом):**
-  1. У path є сегмент із `TEST_DIR_NAMES` → `'test-style каталог "<seg>/"'`.
-  2. Basename матчить `TEST_FILE_PATTERNS` → `"test-style ім'я файлу"`.
-  3. Розширення JS-like і AST містить імпорт test-фреймворку → `'імпорт test-фреймворку "<mod>"'`.
-- **Carve-out:** для `rules/<rule-name>/...` сегмент `<rule-name>` (індекс 1) ігнорується, бо це ім'я правила (наприклад, правило з id `test` саме описує конвенцію тестів і не є fixture-каталогом). Подальші сегменти (`rules/<r>/js/<c>/tests/`) продовжують перевірятись.
-- **Side effects:** для JS-like розширень — `readFile(join(cwd, 'npm', relPath))`.
-
-### `checkNoTestsInPublishedFiles(pass, fail, cwd)`
-
-- **Сигнатура:** `async (pass, fail, cwd: string) => Promise<void>`
-- **Поведінка:**
-  - Якщо `npm/package.json` відсутній або поле `files` не масив — нічого не робить.
-  - Інакше збирає файли через `collectPublishedFiles` і прогонить кожен через `classifyPublishedFileAsTest`.
-  - На порушення викликає `fail(...)` з підказкою додати негативний glob у `files`.
-  - На повну чистоту — `pass(...)` з кількістю перевірених файлів.
-
-### `checkNpmModuleBasicStructure(pass, fail, cwd)`
-
-- **Сигнатура:** `async (pass, fail, cwd: string) => Promise<void>`
-- **Поведінка:** перевіряє наявність `package.json`, директорії `npm/` і `npm/package.json`. Поле `workspaces ∋ "npm"` у кореневому `package.json` валідує Rego.
-
-### `check(cwd = process.cwd())` (експортована, головна)
-
-- **Сигнатура:** `async (cwd?: string) => Promise<number>`
-- **Повертає:** `0` — все OK, `1` — є проблеми (через `reporter.getExitCode()`).
-- **Алгоритм:**
-  1. Створює `createCheckReporter()`, дістає `pass`, `fail`.
-  2. `checkNpmModuleBasicStructure` — `package.json`, `npm/`, `npm/package.json`.
-  3. `checkNoTestsInPublishedFiles` — компактність tarball.
-  4. `loadCursorIgnorePaths(cwd)` для подальшого скану `npm/src`.
-  5. `npmSrcTreeHasJsFile` → визначає `useSrcJsLayout`.
-  6. `checkNpmPackageJson(useSrcJsLayout, ...)` — поле `types` і відповідний файл на диску.
-  7. Якщо НЕ `useSrcJsLayout` — `checkEmitTypesConfig`.
-  8. `readHkConfig` → знайти hk; перевірити pre-commit-фрагменти через `missingHkSrcLayoutFragments` або `missingHkEmitTypesConfigFragments` залежно від layout.
-  9. `.github/workflows/` існує.
-  10. `checkPublishWorkflow` — `npm-publish.yml`.
-  11. `return reporter.getExitCode()`.
-
-## Залежності
-
-### Node.js core
-
-- `node:fs` — `existsSync`.
-- `node:fs/promises` — `readFile`, `stat`.
-- `node:path` — `join`, `sep`.
-
-### Зовнішні npm
-
-- `oxc-parser` — `parseSync` для AST-парсингу JS/TS у `findTestFrameworkImport`.
-
-### Внутрішні (relative)
-
-- `../../../scripts/utils/ast-scan-utils.mjs` — `dynamicImportModule`, `langFromPath`, `requireCallModule`, `walkAstWithAncestors`.
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter` (повертає `{ pass, fail, getExitCode }`).
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths` (читає `.cursorignore`-подібні шляхи).
-- `../../../scripts/utils/walkDir.mjs` — `walkDir(root, callback, ignorePaths?)` для рекурсивного обходу.
-
-## Потік виконання / Використання
-
-### Базовий потік `check(cwd)`
-
-```text
-check(cwd)
-├── createCheckReporter() → { pass, fail, getExitCode }
-├── checkNpmModuleBasicStructure(pass, fail, cwd)
-│     ├── existsSync(cwd/package.json) ? pass : fail
-│     ├── existsSync(cwd/npm) && stat(...).isDirectory() ? pass : fail
-│     └── existsSync(cwd/npm/package.json) ? pass : fail
-├── checkNoTestsInPublishedFiles(pass, fail, cwd)
-│     ├── readFile(npm/package.json) → pkg
-│     ├── if !Array.isArray(pkg.files) → return
-│     ├── files = collectPublishedFiles(pkg.files, cwd)
-│     └── for rel of files: classifyPublishedFileAsTest(rel, cwd)
-├── ignorePaths = loadCursorIgnorePaths(cwd)
-├── useSrcJsLayout = npmSrcTreeHasJsFile(cwd, ignorePaths)
-├── checkNpmPackageJson(useSrcJsLayout, pass, fail, cwd)
-├── if !useSrcJsLayout → checkEmitTypesConfig(pass, fail, cwd)
-├── hk = readHkConfig(cwd)
-│     ├── hk == null → fail (потрібен hk.pkl)
-│     └── inakshe →
-│           missing = useSrcJsLayout
-│             ? missingHkSrcLayoutFragments(hk.text)
-│             : missingHkEmitTypesConfigFragments(hk.text)
-│           missing.length === 0 ? pass : fail
-├── existsSync(.github/workflows/) ? pass : fail
-├── checkPublishWorkflow(pass, fail, cwd)
-└── return reporter.getExitCode()
-```
+globToRegex
+Перетворює glob-патерн у RegExp з якорями `^` та `$`.
 
-### Точка інтеграції
+findTestFrameworkImport
+Знаходить імпорт модуля тест-фреймворку з контенту файлу.
 
-Цей файл — частина пакету `@nitra/cursor` (`npm/rules/npm-module/js/`). Він викликається CLI `npx @nitra/cursor fix` (або `n-cursor`) у режимі checker правила `npm-module`. Експортована функція `check(cwd?)` — стандартний контракт для checker-ів правил у каталозі `npm/rules/<rule>/js/`.
+classifyPublishedFileAsTest
+Класифікує опублікований файл як test/fixture за ознаками.
 
-### Розподіл відповідальностей із Rego
+check
+Перевіряє відповідність проєкту правилам (npm-module.mdc).
 
-- **Цей JS:** FS-existence (чи є файл / директорія), AST-сканування (test-imports), glob-обчислення для `files`, cross-file (`package.json` ↔ файли на диску).
-- **Rego (`npm/policy/npm_module/`):**
-  - `npm_package_json` — структура `npm/package.json` (whitelist `files`, заборона `devDependencies`, тощо).
-  - `emit_types_config` — `compilerOptions` у `npm/tsconfig.emit-types.json`.
-  - `npm_publish_yml` — поля workflow (`on.push.paths`, `branches`, `id-token: write`, кроки JS-DevTools/npm-publish), парсяться після YAML-parse.
-  - `root_package_json` — `workspaces ∋ "npm"` у кореневому `package.json`.
+## Поведінка
 
-### Приклад інтеграції
+globToRegex
+Перетворює glob-патерн у RegExp з якорями `^` / `$`.
 
-```js
-import { check } from '@nitra/cursor/rules/npm-module/js/package_structure.mjs'
+findTestFrameworkImport
+Знаходить імпорт модуля тест-фреймворку з контенту файлу.
 
-const exitCode = await check(process.cwd())
-process.exit(exitCode)
-```
+classifyPublishedFileAsTest
+Класифікує опублікований файл як test/fixture за ознаками.
 
-### Що НЕ робить файл
+check
+Перевіряє відповідність проєкту правилам npm-module.mdc.
 
-- Не перевіряє узгодженість `version` ↔ `CHANGELOG.md` — це `changelog/js/consistency.mjs` (правило `n-changelog.mdc`).
-- Не валідує сам формат AST/синтаксис коду — за помилки парсингу `findTestFrameworkImport` мовчки повертає `null`.
-- Не дублює логіку `npm pack` (LICENSE / README / mandatory files) — сканує лише простір імен `files`.
-- Не перевіряє вміст Rego-полісі — лише дискову наявність / FS / AST.
+## Публічний API
 
-## Rebuild Test
+GlobToRegex — перетворює glob-патерн у RegExp з використанням `^` та `$`. Підтримує globstar, `*`, `?` та brace-альтернативи.
+FindTestFrameworkImport — визначає наявність імпорту/require/dynamic-import модуля тест-фреймворку. Парсинг через oxc-parser повертає `null` у разі помилки.
+ClassifyPublishedFileAsTest — відносить опублікований файл до test/fixture, якщо присутні ознаки: каталог з `TEST_DIR_NAMES`, збіг імені файлу з `TEST_FILE_PATTERNS`, або імпорт тест-фреймворку для JS/TS розширень.
+Carve-out — витягує ім'я правила з шляху `rules/<rule-name>/...` (індекс 1), що позначає ім'я правила. Правило з id `test` або `tests` описує конвенцію розміщення тестів, але не є test-fixture. Подальші сегменти продовжують перевірку.
+Check — перевіряє відповідність проєкту правилам npm-module.mdc.
 
-Файл можна повністю відтворити з опису вище:
+## Гарантії поведінки
 
-- Імпорти: `node:fs` (`existsSync`), `node:fs/promises` (`readFile`, `stat`), `node:path` (`join`, `sep`), `oxc-parser` (`parseSync`), і чотири внутрішні модулі (`ast-scan-utils.mjs`, `check-reporter.mjs`, `load-cursor-config.mjs`, `walkDir.mjs`).
-- Константи: `EMIT_TYPES_CONFIG`, `TEST_DIR_NAMES`, `TEST_FILE_PATTERNS`, `JS_LIKE_EXT_RE`, `TEST_FRAMEWORK_MODULES`, `REGEX_SPECIAL_IN_GLOB`, `GLOBSTAR_LEADING_RE`, `GLOBSTAR_TRAILING_RE`.
-- Експорти: `globToRegex`, `findTestFrameworkImport`, `classifyPublishedFileAsTest`, `check`.
-- Алгоритми описано у секціях "Функції" і "Потік виконання".
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.