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

package/rules/js/utils_imports/docs/main.md

@@ -0,0 +1,50 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/js/utils_imports/main.mjs
+docgen:
+  crc: a705c81d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Огляд
+Сканує всі каталоги `utils` у монорепозиторії, виявляючи джерела коду, уникаючи стандартних артефактів. Аналізує кожен рядковий імпорт, витягнутий із коду, порівнюючи його з шаблоном імпорту з батьківського каталогу. При виявленні невідповідностей фіксує помилки, вказуючи відносний шлях до файлу.
+
+Поведінка
+
+1. Ініціалізація перевірки відбувається через виклик функції `main`, яка працює в fail-safe режимі та перехоплює помилки, не викидаючи винятків назовні.
+2. Робочий каталог системи слугує коренем репозиторію.
+3. Конфігураційні шляхи, які мають бути виключені з перевірки (наприклад, `.git`, `node_modules`), завантажуються з файлу .n-rules.json.
+4. Визначаються кореневі каталоги монорепозиторію.
+5. Проводиться пошук усіх каталогів `utils` у всіх пакетах монорепозиторію, при цьому ігноруються каталоги, які є типовими артефактами (наприклад, `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`, `__fixtures__`).
+6. Для кожного знайденого каталогу `utils` збирається повний набір відповідних джерел коду, виходячи за межі підкаталогів `tests/` та `__fixtures__/`.
+7. Вміст кожного зібраного джерела коду зчитується з файлів.
+8. Використовується парсер для аналізу синтаксису з метою витягування всіх рядкових імпортів із коду.
+9. Кожен витягнутий імпорт піддається перевірці на відповідність шаблону, що визначає імпорт з батьківського каталогу.
+10. Якщо імпорт заборонений, фіксується помилка, яка вказує на відносний шлях до файлу, і реєструється обов'язковий маркер повідомлення (js.mdc).
+11. Після завершення перевірки всіх файлів, якщо жодних порушень не знайдено, реєструється успішне завершення (js.mdc).
+
+## Поведінка
+
+1. Викликається функція `main` для ініціалізації перевірки.
+2. Системний робочий каталог використовується для визначення кореня репозиторію.
+3. Завантажуються конфігураційні шляхи, які ігнорують перевірку, з файлу .n-rules.json.
+4. Знаходяться кореневі каталоги монорепозиторію.
+5. Пошукаються всі каталоги з іменем `utils` у всіх пакетах монорепозиторію, при цьому пропускаються типові артефакти (наприклад, node_modules, .git, dist, coverage, .turbo, .next, **fixtures**).
+6. Для кожного знайденого каталогу `utils` збираються всі відповідні джерела коду, виходячи за межі підкаталогів `tests/` та `__fixtures__/`.
+7. Для кожного зібраного джерела коду зчитується вміст файлу.
+8. Витягуються всі рядкові імпорти з коду, використовуючи парсер для аналізу синтаксису.
+9. Кожен витягнутий імпорт перевіряється на відповідність шаблону, що вказує на імпорт з батьківського каталогу.
+10. Якщо імпорт заборонений, фіксується помилка, яка вказує на відносний шлях до файлу.
+11. Після перевірки усіх файлів, якщо порушень не знайдено, реєструється успішне завершення (js.mdc).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/rules/js/utils_imports/main.mjs

@@ -0,0 +1,185 @@
+/** @see ./docs/utils_imports.md */
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+
+import { parseSync } from 'oxc-parser'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '@7n/rules/scripts/lib/load-cursor-config.mjs'
+import { getMonorepoPackageRootDirs } from '@7n/rules/scripts/lib/workspaces.mjs'
+import {
+  dynamicImportModule,
+  langFromPath,
+  requireCallModule,
+  walkAstWithAncestors
+} from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+
+const JS_SOURCE_RE = /\.(?:[cm]?[jt]sx?)$/u
+const TEST_FILE_RE = /\.test\.[cm]?[jt]sx?$/u
+const PARENT_RELATIVE_RE = /^\.\.(?:\/|$)/u
+const SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist', 'coverage', '.turbo', '.next', '__fixtures__'])
+
+/**
+ * Чи каталог `dir` входить у список ignore (точний збіг або префікс).
+ * @param {string} dir абсолютний posix-шлях
+ * @param {string[]} ignorePaths абсолютні posix-шляхи з .n-rules.json
+ * @returns {boolean} true — пропускаємо
+ */
+function isIgnored(dir, ignorePaths) {
+  for (const p of ignorePaths) {
+    if (dir === p || dir.startsWith(`${p}/`)) return true
+  }
+  return false
+}
+
+/**
+ * Рекурсивно знаходить усі каталоги з ім'ям `utils` під `root` (пропускаючи типові артефакти).
+ * @param {string} root корінь
+ * @param {string[]} ignorePosix абс. posix-шляхи з ignore-конфігу
+ * @returns {Promise<string[]>} абсолютні шляхи знайдених `utils/`-каталогів
+ */
+async function findUtilsDirs(root, ignorePosix) {
+  const found = []
+  /**
+   * @param {string} dir поточний каталог обходу
+   */
+  async function walk(dir) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      if (SKIP_DIR_NAMES.has(entry.name)) continue
+      const full = join(dir, entry.name)
+      const posix = full.split(sep).join('/')
+      if (isIgnored(posix, ignorePosix)) continue
+      if (entry.name === 'utils') {
+        found.push(full)
+        continue
+      }
+      await walk(full)
+    }
+  }
+  await walk(root)
+  return found
+}
+
+/**
+ * Збирає всі не-тестові `.[cm]?[jt]sx?` файли під `utilsDir` (включно з підкаталогами,
+ * крім `tests/` і `__fixtures__/`).
+ * @param {string} utilsDir абсолютний шлях `utils/`
+ * @returns {Promise<string[]>} абсолютні шляхи джерел
+ */
+async function collectUtilsSources(utilsDir) {
+  const out = []
+  /**
+   * @param {string} dir поточний каталог
+   */
+  async function walk(dir) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === 'tests' || entry.name === '__fixtures__' || SKIP_DIR_NAMES.has(entry.name)) continue
+        await walk(full)
+        continue
+      }
+      if (entry.isFile() && JS_SOURCE_RE.test(entry.name) && !TEST_FILE_RE.test(entry.name)) {
+        out.push(full)
+      }
+    }
+  }
+  await walk(utilsDir)
+  return out
+}
+
+/**
+ * Витягає з джерела всі рядкові імпорт-source (статичні, динамічні, require). Помилки парсера
+ * не падають — спочатку треба полагодити синтаксис, потім перезапустити концерн.
+ * @param {string} source текст файлу
+ * @param {string} filePath шлях (для вибору мови)
+ * @returns {string[]} список source-рядків, як вони задані в коді
+ */
+function extractImportSources(source, filePath) {
+  /** @type {string[]} */
+  const sources = []
+  let parsed
+  try {
+    parsed = parseSync(filePath, source, { lang: langFromPath(filePath) })
+  } catch {
+    return sources
+  }
+  const staticImports = parsed?.module?.staticImports ?? []
+  for (const imp of staticImports) {
+    if (typeof imp?.moduleRequest?.value === 'string') {
+      sources.push(imp.moduleRequest.value)
+    }
+  }
+  const program = parsed?.program
+  if (program && typeof program === 'object') {
+    walkAstWithAncestors(program, [], node => {
+      const dyn = dynamicImportModule(node)
+      if (dyn !== null) sources.push(dyn)
+      const req = requireCallModule(node)
+      if (req !== null) sources.push(req)
+    })
+  }
+  return sources
+}
+
+/**
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат лінту
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const root = ctx.cwd
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const ignorePosix = ignorePaths.map(p => p.split(sep).join('/'))
+  const packageRoots = await getMonorepoPackageRootDirs(root)
+  /** @type {Set<string>} */
+  const utilsDirSet = new Set()
+  for (const pkgRel of packageRoots) {
+    const pkgAbs = pkgRel === '.' ? root : join(root, pkgRel)
+    for (const utilsDir of await findUtilsDirs(pkgAbs, ignorePosix)) {
+      utilsDirSet.add(utilsDir)
+    }
+  }
+  if (utilsDirSet.size === 0) {
+    reporter.pass('utils-каталогів немає — перевірку пропущено (js.mdc)')
+    return reporter.result()
+  }
+  let violations = 0
+  let checkedFiles = 0
+  for (const utilsDir of utilsDirSet) {
+    const sources = await collectUtilsSources(utilsDir)
+    for (const file of sources) {
+      checkedFiles += 1
+      const content = await readFile(file, 'utf8')
+      const imports = extractImportSources(content, file)
+      for (const src of imports) {
+        if (!PARENT_RELATIVE_RE.test(src)) {
+          continue
+        }
+
+        const rel = relative(root, file)
+        reporter.fail(`${rel}: заборонений імпорт '${src}' — utils/-файли мають бути generic (js.mdc)`)
+        violations += 1
+      }
+    }
+  }
+  if (violations === 0) {
+    reporter.pass(
+      `utils-каталогів: ${utilsDirSet.size}, перевірено ${checkedFiles} файлів — domain-bound імпортів немає (js.mdc)`
+    )
+  }
+  return reporter.result()
+}

package/rules/js/utils_imports/utils_imports.mdc

@@ -0,0 +1,15 @@
+## Структура спільних модулів: `utils/` vs `lib/`
+
+Коли спільні методи виносяться з кількох JS-файлів в окремий каталог — назву каталога обирай за призначенням модулів усередині.
+
+- **`utils/`** — низькорівневі, чисті, generic helpers без бізнес-логіки і без залежностей від домену проєкту. Те, що могло б жити в окремому npm-пакеті. Приклади: `formatDate()`, `chunk(array, size)`, `retry(fn, opts)`, `deepMerge()`, `parseDuration('5m')`, `sleep(ms)`.
+
+- **`lib/`** — внутрішні модулі / підсистеми проєкту, які знають про домен. Більші за `utils/`, часто з власним state, конфігом або side effects. Приклади: `lib/gmail-client.js`, `lib/circuit-breaker.js`, `lib/skill-loader.js`, `lib/safety/dry-run.js`.
+
+Швидкий тест: якщо файл завтра можна опублікувати окремим npm-пакетом без переписування — це `utils/`; якщо він тримає domain-state, читає конфіг проєкту або викликає зовнішні сервіси/файли — це `lib/`. Не плутай із чужими каталогами на кшталт `shared/` чи `common/`: канонічні назви — лише `utils/` і `lib/`.
+
+### Автоматична перевірка імпортів у `utils/`
+
+`npx @7n/rules lint js` (концерн `utils_imports`) обходить кожен `utils/`-каталог у воркспейсах і падає, якщо знаходить relative-імпорт з `..` (вихід за межі каталогу) у будь-якому не-тестовому файлі. Це механічне втілення правила «utils не знає про домен»: тільки same-dir (`./X`), bare-пакети та `node:*` дозволені; cross-rule, конфіги проєкту чи sibling-utils — fail.
+
+Якщо потрібна domain-залежність — перенеси файл у `lib/`.

package/rules/js/vscode_extensions/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".vscode/extensions.json",
+      "required": true
+    },
+    "missingMessage": ".vscode/extensions.json не існує — додай recommendations з js.mdc"
+  }
+}

package/rules/js/vscode_extensions/docs/fix-vscode_extensions.md

@@ -0,0 +1,24 @@
+---
+type: JS Module
+title: fix-vscode_extensions.mjs
+resource: plugins/lang-js/rules/js/vscode_extensions/fix-vscode_extensions.mjs
+docgen:
+  crc: b6cffd44
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл визначає шаблони, які використовуються для корекції компонентів VS Code. Він застосовує ці шаблони для забезпечення відповідності коду вимогам, визначеним у конфігураціях, а також для корекції помилок, описаних в [ANKOR_ISSUE_1] та [ANKOR_ISSUE_2].
+
+## Поведінка
+
+1. Ідентифікує шаблони, необхідні для корекції розширень VS Code.
+2. Застосовує ці шаблони для приведення коду до відповідності стандартам.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js/vscode_extensions/docs/index.md

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

package/rules/js/vscode_extensions/fix-vscode_extensions.mjs

@@ -0,0 +1 @@
+export { patterns } from '@7n/rules/scripts/lib/fix/vscode-ext-add.mjs'

package/rules/js/vscode_extensions/template/extensions.json.snippet.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "oxc.oxc-vscode"
+  ]
+}

package/rules/js/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,11 @@
+## Rego-gate `.vscode/extensions.json`
+
+Rego-пакет: `js_lint.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json`.
+
+Що перевіряється:
+
+- `recommendations` — subset-of: масив має містити всі три канонічні розширення (`dbaeumer.vscode-eslint`, `github.vscode-github-actions`, `oxc.oxc-vscode`)
+
+Канон-snippet: [extensions.json.snippet.json](./template/extensions.json.snippet.json)

package/rules/js/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,12 @@
+# Перевірка `.vscode/extensions.json` для js (js.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+package js.vscode_extensions
+
+import rego.v1
+
+deny contains msg if {
+	some rec in data.template.snippet.recommendations
+	not rec in {r | some r in object.get(input, "recommendations", [])}
+	msg := sprintf(".vscode/extensions.json: recommendations має містити %q (js.mdc)", [rec])
+}

package/rules/js-bun-db/connection/concern.json

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

package/rules/js-bun-db/connection/connection.mdc

@@ -0,0 +1,42 @@
+## Підключення (singleton + env)
+
+Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
+
+Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.mjs` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
+
+```javascript
+// src/conn/db.mjs
+import { SQL } from 'bun'
+
+export const pgWrite = new SQL({
+  url: process.env.DATABASE_URL,
+  max: 20,
+  idleTimeout: 30,
+  connectionTimeout: 10
+})
+
+export const pgRead = new SQL({
+  url: process.env.PG_CONN_READ ?? process.env.DATABASE_URL,
+  max: 10,
+  idleTimeout: 30,
+  connectionTimeout: 10
+})
+```
+
+Connection string обирає адаптер автоматично:
+
+- `postgres://...` / `postgresql://...` → PostgreSQL
+- `mysql://...` / `mysql2://...` → MySQL/MariaDB
+- `sqlite://...` / `file://...` / `:memory:` → SQLite
+
+### Не створювати підключення на кожен запит
+
+```javascript
+// ❌ нове підключення/інстанс на кожен виклик
+function getUser(id) {
+  const pgWrite = new SQL(process.env.DATABASE_URL)
+  return pgWrite`SELECT * FROM users WHERE id = ${id}`
+}
+```
+
+`new SQL(...)` має створюватись **один раз** на рівні модуля. Bun сам тримає пул (`max`, `idleTimeout`, `maxLifetime`) — окремих `Pool`/`Client` як у `pg` не потрібно. Автоматична перевірка (`lib/bun-sql-scan.mjs`, `findBunSqlPerRequestConnectionInText`, підключена з `safety/main.mjs`) фейлить будь-який `new SQL(...)` усередині функції — це єдина частина цієї сторінки, яку лінтер справді перевіряє; сам singleton-паттерн (файл, іменування `pgWrite`/`pgRead`) — рекомендація без автоматичної перевірки.

package/rules/js-bun-db/docs/index.md

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