@7n/rules-lang-js 0.3.1 → 0.4.0

package/rules/js-run/runtime/runtime.mdc

@@ -0,0 +1,184 @@
+## Runtime у `package.json#scripts`
+
+У **backend**-пакетах (без `vite` у `devDependencies`) код запускають через **Bun**, не через бінарник **`node`** у значеннях `scripts`:
+
+- `"start": "node src/index.js"` → `"start": "bun src/index.js"` (або `bun run …`, якщо так прийнято в репо);
+- `node --watch app.js` → `bun --watch app.js`;
+- `NODE_OPTIONS=… node app.js` → `NODE_OPTIONS=… bun app.js`.
+- `env $(cat .env .env.local) bun src/index.js` → `bun --env-file=.env --env-file=.env.local src/index.js` (нативне завантаження env у Bun, без `env`/`cat`).
+
+Заборонено викликати **`node`** у ланцюжках (`&&`, `;`, `|`). Заборонено обгортку **`env $(cat …) bun`** — файли з `cat` перелічуй у **`--env-file=`** (по одному прапорцю на файл, порядок як у `cat`). Допустимо: `bun`, `bunx`, `npx` (див. **bun.mdc**), інші CLI, якщо вони не підміняють рантайм на `node`.
+
+Це **не** стосується поля `engines.node` (мінімальна версія Node для сумісності інструментів) і **не** стосується frontend-пакетів з `vite` у `devDependencies`.
+
+Канон заборонених патернів у `scripts`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json) (`scriptsForbidden`).
+
+## CheckEnv та заборона прямого `process.env`
+
+### CheckEnv
+
+Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми.
+
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const db = new SQL({ url: env.PG_CONN })
+
+```
+
+### process.env
+
+Прямий доступ до `process.env.X` у коді заборонений — його треба замінити на `env`:
+
+> Стосується лише backend-пакетів (див. **Область застосування**). У frontend-пакетах (`vite` у `devDependencies`) — **не змінюй** `process.env.*` і **не додавай** імпорт `node:process`.
+
+- **обов'язкова змінна** — `import { checkEnv, env } from '@nitra/check-env'` плюс `checkEnv(['X'])`
+  у тому ж файлі (приклад див. вище в розділі **CheckEnv**);
+- **опційна змінна** — `import { env } from 'node:process'`:
+
+```javascript title="Опційна змінна — env з node:process"
+import { env } from 'node:process'
+
+console.log(env.OPTIONAL_ENV_VAR)
+```
+
+Тимчасово приглушити перевірку для конкретного рядка можна коментарем
+`// @7n/rules ignore-next-line checkEnv` безпосередньо перед використанням
+(escape-hatch для legacy-коду, не для нових файлів).
+
+Перевірка (JS-сканер): `../lib/check-env-scan.mjs`.
+
+## Внутрішні аліаси для підключень до БД і GraphQL
+
+Якщо в проекті є підключення до баз даних, зовнішніх graphql на кшталт:
+
+```js
+import { SQL } from 'bun'
+
+// або
+
+import sql from 'mssql'
+
+// або
+
+import { GraphQLClient } from '@nitra/graphql-request'
+```
+
+то ці підключення повинні бути винесені в окремий файл, наприклад `/src/conn/pg.mjs`, в package.json повинні бути додано аліас:
+
+```json
+{
+  "imports": {
+    "#conn/*": "./src/conn/*"
+  },
+}
+
+```
+
+так виглядатиме підключення до PostgreSQL в коді:
+
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const db = new SQL({ url: env.PG_CONN })
+
+```
+
+а так до GraphQL:
+
+```js
+import { checkEnv, env } from '@nitra/check-env'
+import { GraphQLClient } from '@nitra/graphql-request'
+
+checkEnv(['QL', 'X_HASURA_ADMIN_SECRET'])
+
+export { gql } from '@nitra/graphql-request'
+
+export const graphQLClientSmart = new GraphQLClient(env.QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+а в коді повинно бути використано:
+
+```js
+import { pool } from '#conn/pg.mjs'
+
+// або
+
+import { gql, graphQLClient } from '@nitra/graphql-request'
+```
+
+### Нейминг файлів у `src/conn/`
+
+Назва файла в `src/conn/` має одразу повідомляти, **до чого** підключаємось і **в якому режимі**:
+
+- **GraphQL** — префікс `ql-`, далі ідентифікатор endpoint:
+  - `src/conn/ql-contract.mjs`
+  - `src/conn/ql-smart.mjs`
+- **PostgreSQL** — префікс `pg-`, далі тип підключення (репліка vs мастер): `read` або `write`:
+  - `src/conn/pg-read.mjs`
+  - `src/conn/pg-write.mjs`
+- **PostgreSQL до кількох БД** — додатково ідентифікатор підключення після типу:
+  - `src/conn/pg-read-smart.mjs`
+  - `src/conn/pg-write-contract.mjs`
+- **MySQL** — префікс `mysql-` за тією ж схемою (`mysql-read.mjs`, `mysql-write-<id>.mjs` тощо).
+- **MSSQL** — префікс `mssql-` за тією ж схемою (`mssql-read.mjs`, `mssql-write-<id>.mjs` тощо). Хоча npm-пакет один (`mssql`), а драйвер MS SQL Server під капотом T-SQL — у файловій назві відрізняємо MS SQL Server від MySQL, бо це різні СУБД, різні діалекти, різні рантаймні залежності. Якщо проєкт історично використовує `mysql-…` для MSSQL-підключень — він валідний і далі (для backward-compat), але новий код пишемо з префіксом `mssql-`.
+
+Підключення до БД **обов'язково** має бути ідентифіковано як `read` (репліка) або `write` (мастер). Якщо з імені змінної оточення (наприклад, `env.PG_CONN`) це не очевидно — визнач режим за операціями в коді: якщо немає операцій зміни даних (`INSERT`/`UPDATE`/`DELETE`/DDL) — це `pg-read.mjs`, інакше `pg-write.mjs`.
+
+### Експорти у файлах `src/conn/`
+
+У файлах підключень **заборонений** `export default`. Експорт має бути **іменований** і збігатися з назвою файла в camelCase.
+
+Приклад — `src/conn/ql-smart.mjs`:
+
+```javascript title="❌ Так не можна"
+export default new GraphQLClient(env.SMART_QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.SMART_X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+```javascript title="✅ Канон: іменований експорт за іменем файла"
+export const qlSmart = new GraphQLClient(env.SMART_QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.SMART_X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+Відповідно: `pg-read.mjs` → `export const pgRead = …`, `pg-write-contract.mjs` → `export const pgWriteContract = …`, `ql-contract.mjs` → `export const qlContract = …`.
+
+Файли `index.*` у conn-каталозі пропускаються як можливий reexport-барель.
+
+Перевірка (JS-сканери): `../lib/conn-file-rules.mjs` (нейминг, експорти), `../lib/conn-imports-scan.mjs` (факторні імпорти поза `src/conn/`); декларація аліаса `imports["#conn/*"]` у `package.json` — `checkConnAliasDeclaration` у `main.mjs`.
+
+## Паузи через setTimeout
+
+Заборонено робити паузи через `await new Promise(resolve => setTimeout(resolve, ms))` — таку обгортку треба замінити на promise-варіант `setTimeout` з `node:timers/promises`:
+
+```javascript title="Замість new Promise + setTimeout"
+import { setTimeout } from 'node:timers/promises'
+
+await setTimeout(500)
+```
+
+Імпорт `setTimeout` з `node:timers/promises` затіняє глобальний таймер у файлі — якщо в тому ж файлі потрібен callback-варіант, імпортуй його під іншим іменем (наприклад, `import { setTimeout as setTimeoutCb } from 'node:timers'`).
+
+Перевірка (JS-сканер): `../lib/promise-settimeout-scan.mjs`.
+
+## Temporal API (заборона у Bun runtime)
+
+У backend/Bun runtime-коді **не використовуй `Temporal`** (`Temporal.Now`, `Temporal.Instant`, імпорти з polyfill тощо). Bun 1.3.x (діапазон версій репозиторію — `bun >= 1.3`) ще не має глобального `Temporal` (`typeof Temporal === "undefined"`), тому агентам треба лишатися на сумісному `Date` API або передавати timestamp у чисті функції через параметр.
+
+Перевірка `npx @7n/rules check` (AST-сканер `../lib/temporal-scan.mjs`) сканує JS/TS-код на identifier `Temporal` у backend workspace-коді.

package/rules/js-run/scope/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js-run/scope/scope.mdc

@@ -0,0 +1,11 @@
+## Область застосування
+
+Правило стосується **виключно backend Node.js workspace-пакетів** (jobs, GraphQL/HTTP-сервери, CLI). **Не застосовується** до frontend-пакетів, які бандляться в браузер: маркер — наявність `vite` у `devDependencies` пакета (`site/`, мобільні Capacitor-пакети, будь-яка Vue/Quasar SPA).
+
+У браузерному середовищі:
+
+- немає `node:process` — імпорт `import { env } from 'node:process'` resolve'иться у `undefined`, і `env.X` падає з `TypeError: Cannot read properties of undefined`;
+- `process.env.X` у джерелах пакета відсутнє в рантаймі — Vite або взагалі не підставляє його, або підставляє лише `process.env.NODE_ENV`;
+- усі змінні оточення для frontend задаються через `VITE_*` і доступні як `import.meta.env.VITE_X` (типобезпечно через `vite-check-env`); режим — `import.meta.env.MODE` / `import.meta.env.PROD`.
+
+Тому **у frontend-пакетах не торкайся `process.env.*`** і **не додавай** `import { env } from 'node:process'`. Якщо натрапив на `process.env.NODE_ENV` у frontend-коді — заміна, якщо взагалі потрібна, лише на `import.meta.env.MODE`.

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

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/npm-module
+resource: plugins/lang-js/rules/npm-module/
+---
+
+# npm/rules/npm-module
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/npm-module/emit_types_config/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": "npm/tsconfig.emit-types.json"
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: fix-emit_types_config.mjs
+resource: plugins/lang-js/rules/npm-module/emit_types_config/fix-emit_types_config.mjs
+docgen:
+  crc: c13c69a5
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`patterns` читає `tsconfig.emit-types.json` як базовий конфіг, щоб перевіряти й підтримувати узгодженість шаблонного правила для emit-types. Це read-only джерело поведінки: воно формує очікування для контракту конфіга без записів у ФС чи БД.
+
+## Поведінка
+
+1. `patterns` визначає набір правил для синхронізації шаблонного конфіга `tsconfig.emit-types.json` у `npm/tsconfig.emit-types.json`.
+2. `patterns` слугує джерелом одного цільового виправлення для підтримки узгодженості між базовим конфігом і npm-варіантом.
+3. `patterns` не виконує запис у файлову систему чи базу даних самостійно; воно лише описує, що саме має бути виправлено.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/emit_types_config/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/npm-module/emit_types_config
+resource: plugins/lang-js/rules/npm-module/emit_types_config/
+---
+
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [fix-emit_types_config.mjs](fix-emit_types_config.md) | JS Module |

package/rules/npm-module/emit_types_config/emit_types_config.mdc

@@ -0,0 +1,43 @@
+## Rego-gate: конфігурація генерації типів `npm/tsconfig.emit-types.json`
+
+Rego-пакет: `npm-module.emit_types_config`
+
+Цільовий файл: `npm/tsconfig.emit-types.json`
+
+### Що перевіряється
+
+Leaf-by-leaf порівняння з канонічним сніпетом (через `--data`): кожне поле всередині `compilerOptions` має точно відповідати очікуваному значенню. Якщо секція `compilerOptions` відсутня або не є обʼєктом — окрема deny-помилка.
+
+Канонічний сніпет: [tsconfig.emit-types.json.snippet.json](./template/tsconfig.emit-types.json.snippet.json)
+
+### Допустимі відхилення
+
+Додаткові поля у `compilerOptions` (наприклад `rootDir`, `baseUrl`) не спричиняють помилку — перевіряється лише наявність і коректність обовʼязкових ключів зі сніпету.
+
+### Приклади
+
+✓ Правильно:
+
+```json
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "skipLibCheck": true
+  }
+}
+```
+
+✗ Неправильно — неправильний `outDir`:
+
+```json
+{ "compilerOptions": { "outDir": "dist" } }
+```
+
+✗ Неправильно — відсутній `compilerOptions`:
+
+```json
+{}
+```

package/rules/npm-module/emit_types_config/emit_types_config.rego

@@ -0,0 +1,28 @@
+# Перевірка `npm/tsconfig.emit-types.json` (npm-module.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/tsconfig.emit-types.json.snippet.json.
+# Snippet — 2-рівнева мапа (section → key → expected). Walker такий самий,
+# як для ga.vscode_settings / bun.bunfig.
+package npm_module.emit_types_config
+
+import rego.v1
+
+# Leaf-by-leaf: коли section присутня й обʼєкт.
+deny contains msg if {
+	some section, expected_inner in data.template.snippet
+	inner := object.get(input, section, {})
+	is_object(inner)
+	some leaf_key, expected_value in expected_inner
+	actual := object.get(inner, leaf_key, null)
+	actual != expected_value
+	msg := sprintf("npm/tsconfig.emit-types.json: %s.%s має бути %v (npm-module.mdc)", [section, leaf_key, expected_value])
+}
+
+# Section відсутня (null) або не обʼєкт.
+deny contains msg if {
+	some section in object.keys(data.template.snippet)
+	raw := object.get(input, section, null)
+	not is_object(raw)
+	msg := sprintf("npm/tsconfig.emit-types.json: відсутній %s (npm-module.mdc)", [section])
+}

package/rules/npm-module/emit_types_config/fix-emit_types_config.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '@7n/rules/scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'npm-module-emit_types_config-template', targetPath: 'npm/tsconfig.emit-types.json' })
+]

package/rules/npm-module/emit_types_config/template/tsconfig.emit-types.json.snippet.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "skipLibCheck": true
+  }
+}

package/rules/npm-module/header_doc_pointer/concern.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": { "scope": "full", "glob": ["npm/rules/**/js/**/*.mjs", "npm/skills/**/js/**/*.mjs"] }
+}

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

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/npm-module/header_doc_pointer/main.mjs
+docgen:
+  crc: 63a40982
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл забезпечує валідацію відповідності конвенціям документації для файлів правил, розташованих у директорії `.cursor/rules/`, та файлів навичок у `.cursor/skills/`. Він сканує кодову базу у директорії `js/` для пошуку файлів документації, перевіряючи, чи не перевищує JSDoc-блок довжину одного рядка для опису поведінки кожного файлу правила або навички.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається `main`.
+2. Створюється репортер.
+3. Для сегментів `npm/rules` та `npm/skills` сканується кожен піддиректорія правил або скілів.
+4. Для кожної піддиректорії перевіряється її каталог `js/`.
+5. У каталозі `js/` скануються всі файли з розширенням `.mjs`, окрім тестів.
+6. Для кожного знайденого файлу:
+   а. Визначається відповідний файл документації у `docs/`, використовуючи ім'я без розширення.
+   б. Якщо такий файл документації існує, аналізується перше заголовочне JSDoc-блоку у коді.
+   в. Якщо JSDoc-блок відсутній, перехід до наступного файлу.
+   г. Якщо JSDoc-блок присутній, рахується кількість непустіших рядків у його тілі, ігноруючи відступ.
+   д. Якщо ця кількість перевищує один, це реєструється як порушення, оскільки документ повинен лише посилатися на поведінку.
+7. Після обробки всіх файлів повертається код виходу репортера.
+
+## Публічний API
+
+main — сканує файли правил у директоріях `npm/rules/*\/js/*.mjs` та `npm/skills/*\/js/*.mjs`, а також керує генерацією документації, посилаючись на існуючі файли `docs/<stem>.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/header_doc_pointer/header_doc_pointer.mdc

@@ -0,0 +1,18 @@
+## Module-level JSDoc як pointer
+
+Якщо поряд із `js/<stem>.mjs` є файл `js/docs/<stem>.md` — module-level JSDoc у `.mjs` має бути **pointer** (не більше одного непорожнього рядка), а не повноцінний наратив.
+
+Логіка перевірки (`header_doc_pointer.mjs`):
+
+- Сканується перший JSDoc-блок (`/** … */`) до першого `import`/`export` у файлі.
+- Підраховуються непорожні рядки тіла (після зрізання `*`-відступу).
+- Якщо їх більше одного — `check` падає з повідомленням про те, що `docs/<stem>.md` вже описує поведінку і module-level JSDoc має залишатись коротким.
+
+**Покриття:** `npm/rules/*/js/*.mjs` і `npm/skills/*/js/*.mjs` (не тестові файли `*.test.mjs`). Якщо `docs/<stem>.md` відсутня — обмежень на довжину JSDoc немає.
+
+**Приклад правильного pointer-JSDoc:**
+
+```js
+/** @see ./docs/package_structure.md */
+import { existsSync } from 'node:fs'
+```

package/rules/npm-module/header_doc_pointer/main.mjs

@@ -0,0 +1,131 @@
+/** Контракт: ./docs/header_doc_pointer.md */
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Перший JSDoc-блок у файлі (не-жадібний). */
+const MODULE_JSDOC_RE = /\/\*\*[\s\S]*?\*\//
+
+/**
+ * `import` або `export` на початку рядка — межа між module-level і body.
+ * Regex, не AST: нас цікавить тільки текстова позиція, не семантика JS.
+ */
+const CODE_START_RE = /^(?:import|export)\b/m
+
+const NON_WHITESPACE_RE = /\S/
+const STAR_INDENT_RE = /^\s*\*\s?/
+
+/**
+ * Кількість непорожніх рядків між `/**` і `*\/` (після зрізання `*`-відступу).
+ * @param {string} block повний текст JSDoc-блоку з обрамленням
+ * @returns {number} кількість непорожніх рядків у тілі
+ */
+function contentLineCount(block) {
+  return block
+    .split('\n')
+    .slice(1, -1)
+    .filter(l => NON_WHITESPACE_RE.test(l.replace(STAR_INDENT_RE, ''))).length
+}
+
+/**
+ * Повертає module-level JSDoc або `null`, якщо його немає.
+ * @param {string} source вміст mjs-файлу
+ * @returns {string|null} текст module-level JSDoc-блоку або null
+ */
+function moduleJsDoc(source) {
+  const codeStart = CODE_START_RE.exec(source)
+  const prefix = codeStart ? source.slice(0, codeStart.index) : source
+  const m = MODULE_JSDOC_RE.exec(prefix)
+  return m ? m[0] : null
+}
+
+/**
+ * Чи `.mjs`-файл, що не є тестом (`*.test.mjs`).
+ * @param {import('node:fs').Dirent} fileEntry запис каталогу
+ * @returns {boolean} true для звичайних source-файлів
+ */
+function isSourceMjs(fileEntry) {
+  return fileEntry.isFile() && fileEntry.name.endsWith('.mjs') && !fileEntry.name.endsWith('.test.mjs')
+}
+
+/**
+ * Перевіряє один source-файл: якщо поряд є `docs/<stem>.md` і module-level JSDoc
+ * містить >1 непорожній рядок — репортить порушення.
+ * @param {string} jsDir каталог `js/`
+ * @param {import('node:fs').Dirent} fileEntry запис файлу
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkSourceFile(jsDir, fileEntry, cwd, reporter) {
+  const stem = basename(fileEntry.name, '.mjs')
+  const docsPath = join(jsDir, 'docs', `${stem}.md`)
+  if (!existsSync(docsPath)) return
+
+  const filePath = join(jsDir, fileEntry.name)
+  const source = await readFile(filePath, 'utf8')
+  const block = moduleJsDoc(source)
+  if (!block) return
+
+  const count = contentLineCount(block)
+  if (count > 1) {
+    reporter.fail(
+      `${filePath.slice(cwd.length + 1)}: docs/${stem}.md вже описує поведінку — module-level JSDoc має бути pointer (≤1 рядок, зараз ${count})`
+    )
+  }
+}
+
+/**
+ * Перевіряє всі source-файли в одному `js/`-каталозі правила/скіла.
+ * @param {string} jsDir каталог `js/`
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkJsDir(jsDir, cwd, reporter) {
+  for (const fileEntry of await readdir(jsDir, { withFileTypes: true })) {
+    if (!isSourceMjs(fileEntry)) continue
+    await checkSourceFile(jsDir, fileEntry, cwd, reporter)
+  }
+}
+
+/**
+ * Перевіряє один base-сегмент (`npm/rules` чи `npm/skills`): обходить піддиректорії
+ * правил/скілів і їхні `js/`-каталоги.
+ * @param {string} absBase абсолютний шлях до base-сегмента
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkBaseSegment(absBase, cwd, reporter) {
+  for (const ruleEntry of await readdir(absBase, { withFileTypes: true })) {
+    if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
+
+    const jsDir = join(absBase, ruleEntry.name, 'js')
+    if (!existsSync(jsDir)) continue
+
+    await checkJsDir(jsDir, cwd, reporter)
+  }
+}
+
+/**
+ * Сканує `npm/rules/*\/js/*.mjs` і `npm/skills/*\/js/*.mjs`.
+ * Якщо поряд існує `docs/<stem>.md` — module-level JSDoc має бути pointer (≤1 рядок),
+ * а не наратив; якщо docs немає — без обмежень.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту (cwd, репортер).
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з pass/fail.
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+
+  for (const baseSegment of ['npm/rules', 'npm/skills']) {
+    const absBase = join(cwd, baseSegment)
+    if (!existsSync(absBase)) continue
+    await checkBaseSegment(absBase, cwd, reporter)
+  }
+
+  return reporter.result()
+}

package/rules/npm-module/main.json

@@ -0,0 +1 @@
+{ "auto": { "glob": "npm/**" } }

package/rules/npm-module/main.mdc

@@ -0,0 +1,36 @@
+---
+description: Оформлення репозиторію для npm модуля
+globs: "npm/**,**/package.json,**/hk.pkl,.github/workflows/npm-publish.yml,**/tsconfig*.json"
+alwaysApply: false
+version: '1.14'
+---
+
+Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
+
+## Версія та CHANGELOG
+
+Версію (`version` у **`npm/package.json`**) і **`npm/CHANGELOG.md`** **не редагуй вручну** — навіть для hotfix. Єдиний артефакт зміни — **change-файл** (`npx @7n/n ch [--bump <major|minor|patch>] [--section <Added|Changed|Fixed|Removed>] [--message "<…>"]`); bump `version` і генерацію секції CHANGELOG робить `n-rules release` у CI на `main`. Будь-який ручний bump `version` поза CI завалює `check changelog` — навіть із change-файлом.
+
+Повна модель (база порівняння, інверсія шляхів, формат CHANGELOG, post-release-інваріант «верхня секція CHANGELOG == `version`») — у **`n-changelog.mdc`** (джерело істини). Це правило їй підпорядковане й власних інструкцій bump/CHANGELOG не дублює.
+
+### Канонічний крок `npm-changelog` у hk.pkl
+
+У v14 команду `check` прибрано (уніфікована поверхня `lint`) — виклик `npx @7n/rules check changelog` у hk.pkl **завалить** кожен коміт з `❌ Невідома команда: check`. Канонічний pre-commit-крок (hk `amends hk@1.42.0`):
+
+```pkl
+["npm-changelog"] {
+    glob = List("npm/**")
+    check_first = false
+    fix = "N_RULES_CHANGELOG_AUTOFIX=1 bun ./npm/bin/n-rules.js lint changelog"
+}
+```
+
+Лише `fix` (без `check`): env-прапорець `N_RULES_CHANGELOG_AUTOFIX=1` вмикає autofix-режим — за відсутності change-файлу правило само створює його (`patch`/`Changed`, subject останнього коміту) і одразу ставить у git-індекс (`git add`) через `writeChange`/`reportOrFixMissingChangeFile`. Тому додатковий `stage = List("npm/.changes/**")` у цьому wiring **не потрібен** — індексація вже всередині JS-кроку. `package_structure` (`npx @7n/rules lint npm-module`) валідує цей крок: fail на застарілий `check changelog` і fail, якщо кроку `npm-changelog` немає взагалі.
+
+## Швидкий gate через conftest
+
+Rego-пакети (запускаються через `npx @7n/rules fix`):
+
+- [package.json.snippet.json](./npm_package_json/template/package.json.snippet.json)
+- [package.json.snippet.json](./root_package_json/template/package.json.snippet.json)
+- [tsconfig.emit-types.json.snippet.json](./emit_types_config/template/tsconfig.emit-types.json.snippet.json)

package/rules/npm-module/npm_package_json/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": "npm/package.json"
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+---
+type: JS Module
+title: fix-npm_package_json.mjs
+resource: plugins/lang-js/rules/npm-module/npm_package_json/fix-npm_package_json.mjs
+docgen:
+  crc: 4c61a5ff
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`patterns` формує узгоджений набір правил для `package.json`, щоб проєктні package-файли лишалися в очікуваному стані за контрактом, який спирається на конфіг з `package.json`. Read-only: не пише у ФС чи БД.
+
+## Поведінка
+
+1. `patterns` визначає набір правил для вирівнювання `npm/package.json` з еталонним шаблоном.
+2. Під час застосування кожне правило бере до уваги конфігурацію з `package.json` і використовує її як основу для корекції цільового файлу.
+3. Мета `patterns` — забезпечити однакову структуру й очікуваний вміст `npm/package.json` у межах проєкту.
+4. Значення `patterns` не виконує записів у файлову систему чи базу даних; воно лише описує, що і як має бути приведено до узгодженого стану.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/npm_package_json/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/npm-module/npm_package_json
+resource: plugins/lang-js/rules/npm-module/npm_package_json/
+---
+
+| Файл                                                | Тип       |
+| --------------------------------------------------- | --------- |
+| [fix-npm_package_json.mjs](fix-npm_package_json.md) | JS Module |

package/rules/npm-module/npm_package_json/fix-npm_package_json.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '@7n/rules/scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'npm-module-npm_package_json-template', targetPath: 'npm/package.json' })
+]