@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,274 @@
+# 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()
+```
+
+### Точка інтеграції
+
+Цей файл — частина пакету `@nitra/cursor` (`npm/rules/npm-module/js/`). Він викликається CLI `npx @nitra/cursor fix` (або `n-cursor`) у режимі checker правила `npm-module`. Експортована функція `check(cwd?)` — стандартний контракт для checker-ів правил у каталозі `npm/rules/<rule>/js/`.
+
+### Розподіл відповідальностей із Rego
+
+- **Цей 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`.
+
+### Приклад інтеграції
+
+```js
+import { check } from '@nitra/cursor/rules/npm-module/js/package_structure.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Що НЕ робить файл
+
+- Не перевіряє узгодженість `version` ↔ `CHANGELOG.md` — це `changelog/js/consistency.mjs` (правило `n-changelog.mdc`).
+- Не валідує сам формат AST/синтаксис коду — за помилки парсингу `findTestFrameworkImport` мовчки повертає `null`.
+- Не дублює логіку `npm pack` (LICENSE / README / mandatory files) — сканує лише простір імен `files`.
+- Не перевіряє вміст Rego-полісі — лише дискову наявність / FS / AST.
+
+## Rebuild Test
+
+Файл можна повністю відтворити з опису вище:
+
+- Імпорти: `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`.
+- Алгоритми описано у секціях "Функції" і "Потік виконання".

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

@@ -0,0 +1,137 @@
+# rule_meta.mjs
+
+## Огляд
+
+Модуль `rule_meta.mjs` реалізує перевірку метаданих правил пакета `@nitra/cursor`. Він є частиною концерну правила `npm-module` й обслуговує валідацію файлів `npm/rules/<id>/meta.json` у репозиторії пакета.
+
+Логіка перевірки покриває такі інваріанти для кожного підкаталогу `npm/rules/<id>/`:
+
+- наявність валідного `meta.json`;
+- коректність поля `auto`, якщо воно присутнє (розпізнаваність специфікації через `parseRuleAutoSpec`: значення `"завжди"`, масив, `{glob}` або `{predicate}`);
+- для специфікації `{predicate}` — наявність відповідного імені у реєстрі `RULE_PREDICATES`;
+- коректність поля `lint`, якщо воно присутнє (`"quick"` чи `"ci"`), з обовʼязковою наявністю файлу `js/lint.mjs` у каталозі правила;
+- відсутність застарілого `auto.md` поряд із `meta.json` (міграція метаданих у `meta.json` вже завершена).
+
+Перевірка застосовна виключно у репо самого пакета `@nitra/cursor`, де існує каталог `npm/rules/`. У споживацьких репо такого каталогу немає, тож модуль м’яко рапортує `pass` і завершується кодом виходу `0`.
+
+Модуль експортує єдину функцію `check`, яка повертає `Promise<number>` із POSIX-кодом виходу: `0` — порушень немає, `1` — є хоча б одне порушення. Звітування реалізоване через інстанс репортера, отриманий від `createCheckReporter`.
+
+## Експорти / API
+
+| Експорт                                | Тип                          | Призначення                                                                                                |
+| -------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `check(cwd?: string): Promise<number>` | іменований експорт (функція) | Валідує всі `npm/rules/<id>/meta.json` у переданому корені репозиторію та повертає підсумковий код виходу. |
+
+Інших експортів (default, типи, константи) модуль не має.
+
+## Функції
+
+### `check(cwd = process.cwd())`
+
+Валідує всі `meta.json` у `<cwd>/npm/rules/<id>/`.
+
+- **Сигнатура:** `export function check(cwd?: string): Promise<number>`
+- **Параметри:**
+  - `cwd` — рядок із абсолютним або відносним шляхом до кореня репозиторію. Необовʼязковий. Якщо не вказано, використовується `process.cwd()` (поточний робочий каталог процесу Node).
+- **Повертає:** `Promise<number>`, що резолвиться у код виходу від репортера (`reporter.getExitCode()`). Конвенція:
+  - `0` — усі знайдені правила пройшли валідацію, або каталог `npm/rules/` відсутній (у такому випадку додатково логиться `pass`-повідомлення `"npm/rules/ відсутній — немає правил для валідації"`);
+  - `1` — зафіксовано принаймні одне порушення (зокрема: залишковий `auto.md`, відсутній/невалідний `meta.json`, нерозпізнаний `auto`, невідомий `predicate`, нерозпізнаний `lint`, або `lint` без `js/lint.mjs`).
+- **Side effects:**
+  - Виконує синхронне читання файлової системи: `existsSync` для перевірки наявності `npm/rules/`, `npm/rules/<id>/auto.md`, `npm/rules/<id>/js/lint.mjs`; `readdirSync` зі списком підкаталогів `npm/rules/`.
+  - Делегує читання та парсинг `meta.json` у `readRuleMetaRaw` (також синхронне читання файла).
+  - Викликає методи репортера (`reporter.pass`, `reporter.fail`), які за домовленістю виводять статусні повідомлення (зазвичай у stdout/stderr — залежно від реалізації `createCheckReporter`).
+  - Не змінює файли на диску, не запускає дочірніх процесів, не звертається до мережі.
+- **Алгоритм:**
+  1. Створює репортер: `reporter = createCheckReporter()`.
+  2. Обчислює `rulesDir = join(cwd, 'npm', 'rules')`.
+  3. Якщо `rulesDir` не існує — рапортує `pass` і резолвить `Promise.resolve(reporter.getExitCode())` (зазвичай `0`).
+  4. Інакше перебирає вміст `rulesDir` через `readdirSync(rulesDir, { withFileTypes: true })` і для кожного запису:
+     - пропускає, якщо це не каталог (`!entry.isDirectory()`) або імʼя починається з крапки (`entry.name.startsWith('.')`);
+     - встановлює локальний прапор `ruleOk = true`;
+     - якщо знайдено залишковий `auto.md` у каталозі правила — `reporter.fail(...)`, `ruleOk = false`;
+     - читає сирий обʼєкт метаданих через `readRuleMetaRaw(ruleDir)`. Якщо повернуто falsy — `reporter.fail("rules/<id>: відсутній або невалідний meta.json")` і `continue` (наступне правило);
+     - якщо `raw.auto !== undefined` — парсить через `parseRuleAutoSpec(raw.auto)`:
+       - якщо повернуто `null` — `reporter.fail(...)`, `ruleOk = false`;
+       - інакше якщо в `spec` є ключ `'predicate'` і його значення немає у `RULE_PREDICATES` — `reporter.fail(...)`, `ruleOk = false`;
+     - якщо `raw.lint !== undefined` — валідує через `parseRuleLintPhase(raw.lint)`:
+       - якщо повернуто `null` — `reporter.fail(...)`, `ruleOk = false`;
+       - інакше якщо немає файла `<ruleDir>/js/lint.mjs` — `reporter.fail(...)`, `ruleOk = false`;
+     - наприкінці ітерації, якщо `ruleOk` усе ще `true` — `reporter.pass("rules/<id>: meta.json валідний")`.
+  5. Резолвить `Promise.resolve(reporter.getExitCode())` із підсумковим кодом виходу.
+- **Особливості реалізації:**
+  - Усі гілки порушень для одного правила фіксуються незалежно одна від одної (наприклад, у тому ж проході може бути зафіксовано і нерозпізнаний `auto`, і нерозпізнаний `lint`). Виняток — повністю відсутній/невалідний `meta.json`: тоді решта перевірок для цього правила пропускається через `continue`.
+  - Функція синхронно виконує всю роботу, але повертає `Promise<number>` через `Promise.resolve(...)` — для уніфікованої сигнатури з іншими `check`-модулями.
+  - Перевірка `'predicate' in spec` дозволяє валідувати лише гілку `{predicate}`-специфікації; інші форми (`"завжди"`, масив, `{glob}`) уже визнані валідними самим `parseRuleAutoSpec`.
+
+## Залежності
+
+### Зовнішні (Node.js standard library)
+
+- `node:fs` — `existsSync` (перевірка існування файлів і каталогів), `readdirSync` (читання вмісту каталогу `npm/rules/`).
+- `node:path` — `join` (формування шляхів до каталогів і файлів).
+
+### Внутрішні (репо-локальні)
+
+- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter()`. Створює репортер з методами `pass(msg)`, `fail(msg)`, `getExitCode()`; останній використовується для отримання підсумкового коду виходу.
+- `../../../scripts/lib/rule-meta.mjs`:
+  - `readRuleMetaRaw(ruleDir)` — читає та парсить сирий `meta.json` із каталогу правила; повертає обʼєкт або falsy (за відсутності/невалідності файла).
+  - `parseRuleAutoSpec(value)` — парсить значення поля `auto`; повертає валідовану специфікацію або `null` за нерозпізнаним вводом.
+  - `parseRuleLintPhase(value)` — парсить значення поля `lint`; повертає валідовану фазу (`"quick"`/`"ci"`) або `null`.
+- `../../../scripts/lib/rule-predicates.mjs` — `RULE_PREDICATES`: обʼєкт-реєстр відомих імен предикатів; ключі використовуються для перевірки наявності предиката через `Object.hasOwn`.
+
+### Глобальні
+
+- `process.cwd()` — використовується як дефолтний `cwd`.
+
+## Потік виконання / Використання
+
+Модуль є check-функцією конкретного правила і підпорядкований конвенції `check-{id}` (тут — `rule_meta`). Очікуваний сценарій використання:
+
+1. Виклик з вищерівневого скрипта (наприклад, агрегованої перевірки правил пакета):
+
+   ```js
+   import { check } from './npm/rules/npm-module/js/rule_meta.mjs'
+
+   const exit = await check(process.cwd())
+   process.exit(exit)
+   ```
+
+   У такому сценарії функцію викликають із кореня репозиторію пакета `@nitra/cursor`.
+
+2. Запуск у репо-споживачі (де `npm/rules/` відсутній) — функція тихо рапортує `pass` і повертає `0`, не блокуючи pipeline.
+3. Сценарій порушення: будь-який із описаних інваріантів спричиняє `fail`-звіт і код виходу `1`, що сигналізує CI зупинку.
+
+Типові точки інтеграції:
+
+- CI lint-фаза пакета `@nitra/cursor` (виклик в одному з кореневих скриптів `bun run lint` / спеціалізованої перевірки правил).
+- Локальний запуск через CLI з кореня репозиторію.
+
+Файл не має побічних ефектів під час імпорту: експортована функція не виконується самовільно — її викликає консьюмер.
+
+## Rebuild Test
+
+Контрольні питання, чиї відповіді достатні, щоб реконструювати модуль без перегляду коду:
+
+1. Який каталог сканує функція `check`?
+   - `<cwd>/npm/rules/`, де `cwd` — необовʼязковий параметр (дефолт `process.cwd()`).
+2. Як обробляється відсутність цього каталогу?
+   - Рапортується `pass("npm/rules/ відсутній — немає правил для валідації")`, повертається `0`.
+3. Які записи в `npm/rules/` пропускаються?
+   - Не-каталоги та елементи, чиє імʼя починається з `.`.
+4. За наявності якого файла поряд із `meta.json` фіксується порушення?
+   - `auto.md` (повідомлення `"rules/<id>: залишковий auto.md — видали (метадані тепер у meta.json)"`).
+5. Що відбувається, якщо `meta.json` відсутній або невалідний?
+   - `reporter.fail("rules/<id>: відсутній або невалідний meta.json")` і `continue` до наступного правила.
+6. Які гілки валідації поля `auto`?
+   - Якщо `parseRuleAutoSpec` повертає `null` — fail (нерозпізнане).
+   - Якщо специфікація містить ключ `predicate`, але його значення відсутнє в `RULE_PREDICATES` — fail (`невідомий predicate`).
+7. Які гілки валідації поля `lint`?
+   - Якщо `parseRuleLintPhase` повертає `null` — fail (`нерозпізнане, очікується "quick"|"ci"`).
+   - Якщо валідне, але немає `js/lint.mjs` — fail (`lint:"..." але немає js/lint.mjs`).
+8. Як формується підсумковий код виходу?
+   - Через `reporter.getExitCode()`, обгорнутий у `Promise.resolve(...)`.
+9. Чи синхронна реалізація?
+   - Так: усі IO операції — синхронні (`existsSync`, `readdirSync`, `readRuleMetaRaw`); проміс використано лише для уніфікації сигнатури.
+10. Які `pass`-повідомлення можливі?
+    - `"npm/rules/ відсутній — немає правил для валідації"` (за відсутності каталогу).
+    - `"rules/<id>: meta.json валідний"` (за успішної валідації окремого правила).

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

@@ -0,0 +1,190 @@
+# skill_meta.mjs
+
+## Огляд
+
+Модуль `skill_meta.mjs` — перевірка валідності метаданих скілів (`meta.json`) пакета `@nitra/cursor`. Належить до концерну правила `npm-module` (тека `npm/rules/npm-module/js/`).
+
+Перевірка застосовується **виключно в репозиторії пакета**, де є каталог `npm/skills/`. Якщо каталог відсутній (наприклад, у проєктах-споживачах залежності), перевірка пропускається без помилки (повертає `pass`).
+
+Для кожного підкаталогу `npm/skills/<id>/` модуль виконує контракт:
+
+- забороняється залишковий файл `auto.md` (метадані мігровані на `meta.json`);
+- файл `meta.json` має бути присутнім і валідним JSON-об'єктом з очікуваною структурою;
+- поле `worktree` обов'язкове і має бути `boolean`;
+- поле `auto` опціональне, але якщо є — має бути або рядком `"завжди"`, або непорожнім масивом рядків.
+
+Результат акумулюється через `check-reporter` і повертається кодом виходу `0` (OK) або `1` (порушення).
+
+## Експорти / API
+
+| Експорт | Тип        | Призначення                                                                |
+| ------- | ---------- | -------------------------------------------------------------------------- |
+| `check` | `function` | Іменований експорт; функція-перевірка метаданих скілів у вказаному корені. |
+
+Модуль є ESM (`.mjs`), без `default` експорту.
+
+## Функції
+
+### `check(cwd?)`
+
+**Сигнатура:**
+
+```js
+export function check(cwd = process.cwd()): Promise<number>
+```
+
+**Параметри:**
+
+| Параметр | Тип      | Обов'язковий | За замовчуванням | Опис                                                             |
+| -------- | -------- | ------------ | ---------------- | ---------------------------------------------------------------- |
+| `cwd`    | `string` | ні           | `process.cwd()`  | Корінь репозиторію; від нього резолвиться шлях до `npm/skills/`. |
+
+**Повертає:**
+
+`Promise<number>` — код виходу від `reporter.getExitCode()`:
+
+- `0` — усі перевірені скіли валідні (або каталог `npm/skills/` відсутній);
+- `1` — щонайменше одне порушення зафіксовано через `reporter.fail(...)`.
+
+Хоча всередині немає `async`/`await`, функція обертає результат у `Promise.resolve(...)` для однорідного API з іншими `check`-функціями в цьому проєкті.
+
+**Алгоритм:**
+
+1. Створюється локальний звітник: `reporter = createCheckReporter()`.
+2. Будується шлях `skillsDir = join(cwd, 'npm', 'skills')`.
+3. Якщо `skillsDir` не існує (`existsSync(...) === false`):
+   - викликається `reporter.pass('npm/skills/ відсутній — немає скілів для валідації')`;
+   - повертається `Promise.resolve(reporter.getExitCode())` (рання гілка).
+4. Інакше — ітерація `readdirSync(skillsDir, { withFileTypes: true })`:
+   - пропускаються не-директорії та назви, що починаються з крапки (`.` префікс);
+   - для кожного скіла `id = entry.name` будується `skillDir = join(skillsDir, id)` і прапор `skillOk = true`.
+5. Для кожного скіла послідовно перевіряється:
+   - **Залишковий `auto.md`**: якщо `existsSync(join(skillDir, 'auto.md'))`, фіксується
+     `fail("skills/<id>: залишковий auto.md — видали (метадані тепер у meta.json)")` і `skillOk = false`.
+   - **`meta.json` присутній/валідний**: викликається `raw = readSkillMetaRaw(skillDir)`.
+     Якщо `raw` falsy — фіксується `fail("skills/<id>: відсутній або невалідний meta.json ...")` і виконується `continue` (решта перевірок для цього скіла пропускається).
+   - **Тип `worktree`**: якщо `typeof raw.worktree !== 'boolean'` — `fail("skills/<id>: meta.json.worktree має бути boolean")` і `skillOk = false`.
+   - **Розпізнаваність `auto`**: якщо `raw.auto !== undefined` і `parseSkillAutoSpec(raw.auto) === null` — `fail("skills/<id>: meta.json.auto нерозпізнане — очікується \"завжди\" або непорожній масив правил")` і `skillOk = false`.
+6. Якщо після всіх перевірок цього скіла `skillOk === true`, фіксується `pass("skills/<id>: meta.json валідний")`.
+7. Після проходу всіх скілів повертається `Promise.resolve(reporter.getExitCode())`.
+
+**Side effects:**
+
+- читання файлової системи (`existsSync`, `readdirSync`) — синхронне;
+- мутація стану внутрішнього звітника (`createCheckReporter()`) через `pass(...)` / `fail(...)`;
+- запис у `stdout`/`stderr` залежить від реалізації `check-reporter` (зазвичай агрегує повідомлення для подальшого виводу викликачем);
+- **не змінює** жодних файлів і **не** створює директорій.
+
+**Поведінкові інваріанти:**
+
+- Відсутність `npm/skills/` — не помилка, а явний `pass` (модуль працює і в репо-споживачі).
+- Невалідний `meta.json` зупиняє подальші перевірки конкретного скіла (`continue`), але **не зупиняє** обхід інших скілів.
+- Прихований запис (назва починається з `.`) ігнорується, тож `.DS_Store` чи `.tmp` не плутають перевірку.
+- Перевірка детермінована: результат залежить тільки від вмісту `npm/skills/` у `cwd`.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+| Модуль      | Імпортовані символи         | Використання                                                         |
+| ----------- | --------------------------- | -------------------------------------------------------------------- |
+| `node:fs`   | `existsSync`, `readdirSync` | перевірка наявності `npm/skills/`, `auto.md`; читання списку скілів. |
+| `node:path` | `join`                      | побудова крос-платформних шляхів до каталогів і файлів.              |
+
+### Внутрішні модулі проєкту
+
+| Модуль                                    | Імпортовані символи                      | Використання                                                                |
+| ----------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
+| `../../../scripts/lib/check-reporter.mjs` | `createCheckReporter`                    | створення звітника з API `pass(msg)` / `fail(msg)` / `getExitCode()`.       |
+| `../../../scripts/lib/skill-meta.mjs`     | `readSkillMetaRaw`, `parseSkillAutoSpec` | читання сирого `meta.json` зі скіла; парсинг/валідація специфікації `auto`. |
+
+### Контракти зовнішніх модулів (як використовуються в коді)
+
+- `createCheckReporter()` → об'єкт із методами `pass(message: string)`, `fail(message: string)`, `getExitCode(): number` (`0` якщо не було `fail`, `1` якщо хоч раз був).
+- `readSkillMetaRaw(skillDir: string)` → розпарсений об'єкт `meta.json` або falsy (наприклад, `null`) якщо файл відсутній/невалідний.
+- `parseSkillAutoSpec(value)` → нормалізована специфікація `auto` або `null`, якщо значення нерозпізнане. Прийнятні форми: рядок `"завжди"` або непорожній масив рядків.
+
+## Потік виконання / Використання
+
+### Контекст
+
+Модуль викликається з раннера правил концерну `npm-module` (точка входу `npm/rules/npm-module/js/index.mjs` або аналог). У типовому пайплайні `bun run lint` / `n-cursor check` всі `check`-функції правил зібрані в реєстр і виконуються послідовно; результат об'єднується в загальний код виходу процесу.
+
+### Типовий виклик
+
+```js
+import { check } from './skill_meta.mjs'
+
+const exitCode = await check() // використає process.cwd()
+process.exit(exitCode)
+```
+
+Або з явним коренем (тести/інтеграція):
+
+```js
+const exitCode = await check('/abs/path/to/repo-root')
+```
+
+### Сценарій 1: репо самого пакета `@nitra/cursor`
+
+- `npm/skills/` існує, містить кілька скілів (наприклад, `n-docgen/`, `n-fix/`, `mdc-check/`).
+- Для кожного скіла читається `meta.json`, перевіряються `worktree` (boolean) і `auto` (опціонально).
+- Якщо хоч один скіл має `auto.md`, або відсутній/невалідний `meta.json`, або `worktree` не boolean, або `auto` нерозпізнане — функція повертає `1`.
+- Інакше — `0`.
+
+### Сценарій 2: проєкт-споживач `@nitra/cursor`
+
+- `npm/skills/` відсутній (інша файлова структура).
+- Функція фіксує `pass(...)`, повертає `0` і не виконує жодної ітерації.
+- Це дозволяє правилам пакета транзитивно застосовуватися в чужих проєктах без false-negative.
+
+### Сценарій 3: переходова міграція на `meta.json`
+
+- У скілі лишилася стара пам'ятка-метадані `auto.md` поряд з новим `meta.json`.
+- Перевірка явно фейлить такий скіл повідомленням `залишковий auto.md — видали (метадані тепер у meta.json)`.
+- Це примушує закрити технічний борг міграції.
+
+### Очікуваний формат `meta.json`
+
+```json
+{
+  "worktree": true,
+  "auto": "завжди"
+}
+```
+
+або
+
+```json
+{
+  "worktree": false,
+  "auto": ["n-bun", "n-flow"]
+}
+```
+
+або (мінімально):
+
+```json
+{
+  "worktree": false
+}
+```
+
+### Невалідні приклади (будуть зафейлені)
+
+- відсутній файл `meta.json` → `відсутній або невалідний meta.json`;
+- `{"worktree": "yes"}` → `meta.json.worktree має бути boolean`;
+- `{"worktree": true, "auto": []}` або `{"worktree": true, "auto": "always"}` → `meta.json.auto нерозпізнане ...`;
+- наявний `auto.md` поряд → `залишковий auto.md — видали`.
+
+### Rebuild Test
+
+Перевірка інваріантів модуля (можна виконати вручну для регресії):
+
+1. У тимчасовому корені створити порожню директорію без `npm/skills/` → `check(tmp)` має повернути `0` і зафіксувати `pass` про відсутність каталогу.
+2. Створити `npm/skills/foo/meta.json` з валідним вмістом `{"worktree": true}` → `check(tmp)` має повернути `0`.
+3. Замінити `worktree` на рядок (`"true"`) → `check(tmp)` має повернути `1` з повідомленням про boolean.
+4. Додати `npm/skills/foo/auto.md` → `check(tmp)` має повернути `1` з повідомленням про залишковий `auto.md`.
+5. Видалити `meta.json` → `check(tmp)` має повернути `1` з повідомленням про відсутній/невалідний `meta.json`.
+6. Створити `npm/skills/.hidden/` — перевірка має ігнорувати її (повернути `0`, якщо інших скілів немає).
+7. Додати `npm/skills/bar/meta.json` з `{"worktree": false, "auto": "завжди"}` → `pass`; замінити `auto` на `"always"` → `fail` про нерозпізнане `auto`.