@7n/rules 1.0.0

package/rules/js-run/lib/conn-imports-scan.mjs

@@ -0,0 +1,154 @@
+/**
+ * AST-сканер для правила «Внутрішні аліаси» (js-run.mdc).
+ *
+ * Імпорти, які створюють підключення до БД / зовнішнього GraphQL, мають жити в окремому
+ * файлі (за замовчуванням — `src/conn/`), а решта коду повинна споживати їх через
+ * pkg-import `#conn/...`. Ловимо такі імпорти в файлах поза каталогом «conn»:
+ *  - `import { SQL } from 'bun'` (named специфікатор `SQL`);
+ *  - `import sql from 'mssql'` або будь-який `import ... from 'mssql'`;
+ *  - `import { GraphQLClient } from '@nitra/graphql-request'` (named `GraphQLClient`).
+ *
+ * Каталог «conn» визначається з поля `package.json#imports['#conn/*']` (якщо є —
+ * відрізаємо `*` і нормалізуємо), інакше дефолт — `src/conn`. Ключ `imports` у
+ * package.json — нативний для Node.js, той самий, що й у документі правила.
+ *
+ * Семантика береться з **oxc-parser** (`module.staticImports`); regex по тілу файлу не
+ * використовується. Якщо файл не парситься — повертаємо порожній результат, спочатку
+ * треба полагодити синтаксис.
+ */
+import { langFromPath, normalizeSnippet, offsetToLine } from '../../../scripts/utils/ast-scan-utils.mjs'
+import { parseSync } from 'oxc-parser'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+
+/**
+ * Прибирає хвостові `/` зі шляху без використання regex (щоб не тригерити slow-regex попередження).
+ * @param {string} s рядок зі шляхом
+ * @returns {string} `s` без хвостових `/`
+ */
+function stripTrailingSlashes(s) {
+  let end = s.length
+  while (end > 0 && s.codePointAt(end - 1) === 47) end--
+  return end === s.length ? s : s.slice(0, end)
+}
+
+/**
+ * Нормалізує шлях до posix без хвостових слешів.
+ * @param {string} p вхідний шлях (можливо з `./` або зворотними слешами)
+ * @returns {string} нормалізований posix-шлях без хвостового `/`
+ */
+function toPosixDir(p) {
+  let s = String(p).replaceAll('\\', '/').trim()
+  if (s.startsWith('./')) s = s.slice(2)
+  return stripTrailingSlashes(s)
+}
+
+/**
+ * Визначає каталог «conn» за `package.json#imports['#conn/*']`. Дефолт — `src/conn`.
+ * @param {unknown} pkgJson розпарсений package.json (або null)
+ * @returns {string} відносний posix-шлях до каталогу conn (без хвостового `/`)
+ */
+export function resolveConnDirFromPackageJson(pkgJson) {
+  const fallback = 'src/conn'
+  if (!pkgJson || typeof pkgJson !== 'object') return fallback
+  const imports = /** @type {Record<string, unknown>} */ (pkgJson).imports
+  if (!imports || typeof imports !== 'object') return fallback
+  const target = /** @type {Record<string, unknown>} */ (imports)['#conn/*']
+  /** @type {string | null} */
+  let raw = null
+  if (typeof target === 'string') raw = target
+  else if (target && typeof target === 'object') {
+    // умовний експорт: { default: '...', import: '...' }
+    const obj = /** @type {Record<string, unknown>} */ (target)
+    if (typeof obj.default === 'string') raw = obj.default
+    else if (typeof obj.import === 'string') raw = obj.import
+  }
+  if (!raw) return fallback
+  // Прибираємо хвіст `*`, потім слеші
+  let s = toPosixDir(raw)
+  if (s.endsWith('/*')) s = s.slice(0, -2)
+  return stripTrailingSlashes(s) || fallback
+}
+
+/**
+ * Чи перебуває файл у каталозі conn (точно або вкладено).
+ * @param {string} relPosix відносний posix-шлях до файлу
+ * @param {string} connDir posix-шлях каталогу conn (без хвостового `/`)
+ * @returns {boolean} true, якщо файл у каталозі conn
+ */
+export function isInsideConnDir(relPosix, connDir) {
+  if (!connDir) return false
+  return relPosix === connDir || relPosix.startsWith(`${connDir}/`)
+}
+
+/**
+ * Чи це порушення правила «Внутрішні аліаси» — імпорт зі стороннього модуля, що створює
+ * підключення (`bun` зі специфікатором `SQL`, будь-який імпорт з `mssql`, або
+ * `@nitra/graphql-request` зі специфікатором `GraphQLClient`).
+ * @param {Record<string, unknown>} staticImport елемент `module.staticImports` з oxc-parser
+ * @returns {{ module: string, specifier: string } | null} опис порушення або null
+ */
+function classifyConnImport(staticImport) {
+  const mod = staticImport.moduleRequest?.value
+  if (typeof mod !== 'string') return null
+  const entries = Array.isArray(staticImport.entries) ? staticImport.entries : []
+
+  if (mod === 'bun') {
+    for (const e of entries) {
+      const name = e?.importName?.name
+      if (name === 'SQL') return { module: mod, specifier: 'SQL' }
+    }
+    return null
+  }
+  if (mod === 'mssql') {
+    return { module: mod, specifier: '*' }
+  }
+  if (mod === '@nitra/graphql-request') {
+    for (const e of entries) {
+      const name = e?.importName?.name
+      if (name === 'GraphQLClient') return { module: mod, specifier: 'GraphQLClient' }
+    }
+    return null
+  }
+  return null
+}
+
+/**
+ * Знаходить імпорти-«фабрики підключень» у тексті файлу.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/index.ts`)
+ * @returns {{ line: number, snippet: string, module: string, specifier: string }[]} список порушень
+ */
+export function findConnFactoryImportsInText(content, virtualPath = 'scan.ts') {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return []
+  }
+  if (result.errors?.length) return []
+
+  /** @type {{ line: number, snippet: string, module: string, specifier: string }[]} */
+  const out = []
+  for (const imp of result.module?.staticImports ?? []) {
+    const hit = classifyConnImport(imp)
+    if (!hit) continue
+    out.push({
+      line: offsetToLine(content, imp.start),
+      snippet: normalizeSnippet(content.slice(imp.start, imp.end)),
+      module: hit.module,
+      specifier: hit.specifier
+    })
+  }
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, без `.d.ts`).
+ * @param {string} relativePathPosix відносний шлях (posix)
+ * @returns {boolean} true, якщо розширення підходить для AST-скану
+ */
+export function isConnImportsScanSourceFile(relativePathPosix) {
+  return SOURCE_FILE_RE.test(relativePathPosix) && !relativePathPosix.endsWith('.d.ts')
+}

package/rules/js-run/lib/docs/bunyan-imports.md

@@ -0,0 +1,121 @@
+---
+type: JS Module
+title: bunyan-imports.mjs
+resource: npm/rules/js-run/lib/bunyan-imports.mjs
+docgen:
+  crc: 5f403a53
+---
+
+Модуль `bunyan-imports.mjs` — це AST-сканер, який знаходить у вихідних файлах JavaScript / TypeScript заборонені імпорти й виклики модулів `@nitra/bunyan` та застарілого `bunyan`. Згідно з правилом `js-run.mdc` уся логіка структурованого логування у проєкті переведена на `@nitra/pino`, тому будь-яке згадування `bunyan`/`@nitra/bunyan` має бути замінене на `@nitra/pino`.
+
+Ключові властивості:
+
+- Семантика береться з **oxc-parser** (`module.staticImports`) — без regex по тілу файлу; це робить сканер стійким до коментарів, рядкових літералів та форматувань.
+- На додачу до статичних `import`-ів сканер обходить AST програми і ловить:
+  - `require('@nitra/bunyan')` / `require('bunyan')` — для CommonJS;
+  - динамічний `import('@nitra/bunyan')` / `import('bunyan')` — для випадків асинхронного підключення в межах одного файлу.
+- Сканер не вимагає, щоб файл компілювався: при синтаксичних помилках парсера повертається **порожній** результат — спершу слід полагодити синтаксис, потім перезапустити перевірку.
+- Декларації типів (`*.d.ts`) виключені з обходу через окремий хелпер.
+
+Файл є частиною бібліотеки правила `js-run` й використовується чек-скриптами цього правила для сигналізації про порушення.
+
+## Експорти / API
+
+Модуль експортує три іменовані функції:
+
+| Експорт                                          | Призначення                                                 |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| `findBunyanImportsInText(content, virtualPath?)` | Основний AST-сканер тексту файлу — повертає масив порушень. |
+| `isBunyanScanSourceFile(relativePath)`           | Фільтр за розширенням файлу (JS/TS-сім'я).                  |
+| `shouldSkipFileForBunyanScan(relativePosix)`     | Виключення декларацій типів (`*.d.ts`).                     |
+
+Внутрішні (не експортовані) константи:
+
+- `SOURCE_FILE_RE` — `/\.([cm]?[jt]sx?)$/u` — регулярний вираз для розширень `.js`, `.cjs`, `.mjs`, `.jsx`, `.ts`, `.cts`, `.mts`, `.tsx`.
+- `FORBIDDEN_MODULES` — `Set` з двох імен модулів: `'@nitra/bunyan'` і `'bunyan'`.
+
+## Функції
+
+### `findBunyanImportsInText(content, virtualPath = 'scan.ts')`
+
+Основний сканер. Парсить переданий текст як модуль JS/TS і збирає всі місця, де згадуються заборонені модулі через статичний `import`, `require(...)` або динамічний `import(...)`.
+
+- Сигнатура: `findBunyanImportsInText(content: string, virtualPath?: string) => { line: number, snippet: string, module: string }[]`
+- Параметри:
+  - `content` (`string`) — повний вихідний код, який треба перевірити.
+  - `virtualPath` (`string`, опційно, за замовчуванням `'scan.ts'`) — віртуальний шлях, який передається в парсер; використовується тільки для вибору `lang` (TS/JS/JSX/TSX) через `langFromPath(...)`. Реальний файл на диску не читається.
+- Повертає: масив об'єктів-порушень. Кожен елемент:
+  - `line` — номер рядка (1-індекс) місця початку конструкції (`offsetToLine`).
+  - `snippet` — нормалізований текстовий зріз `content.slice(start, end)` через `normalizeSnippet` (стискання пробілів/обрізання).
+  - `module` — рядок самого імпортованого імені (`'@nitra/bunyan'` або `'bunyan'`).
+- Порядок результату: спершу всі статичні `import`-и в порядку їх появи в `module.staticImports`, далі — `require`/`import(...)` у порядку обходу AST через `walkAstWithAncestors`.
+- Side effects: відсутні. Функція суто функціональна: жодних I/O, мутацій вхідних параметрів чи логів. Виняткова поведінка `parseSync` поглинається `try/catch`, помилки парсера в `result.errors` трактуються як «нічого не знайдено» — повертається `[]`.
+- Граничні випадки:
+  - `virtualPath` falsy (порожній рядок, `undefined`) — використовується запасне значення `'scan.ts'`.
+  - Якщо `parseSync` кинув виняток або у `result.errors` є записи — повертається `[]`.
+  - Якщо `result.module` відсутній (наприклад, скрипт CJS), цикл по `module.staticImports` пропускається через `?? []`, AST-обхід усе одно виконується.
+  - Для `require`/динамічного `import` модулі з не-літеральним аргументом (`require(name)`) хелпери з `ast-scan-utils` повернуть `null` і вузол буде проігноровано.
+
+### `isBunyanScanSourceFile(relativePath)`
+
+Швидкий фільтр за розширенням — чи має сенс взагалі парсити цей файл.
+
+- Сигнатура: `isBunyanScanSourceFile(relativePath: string) => boolean`
+- Параметри:
+  - `relativePath` (`string`) — відносний шлях до файлу (формат розділювача не важливий, перевіряється тільки суфікс).
+- Повертає: `true`, якщо розширення входить у JS/TS-сім'ю (`.js`, `.cjs`, `.mjs`, `.jsx`, `.ts`, `.cts`, `.mts`, `.tsx`); інакше `false`.
+- Side effects: відсутні; чиста перевірка регулярним виразом `SOURCE_FILE_RE`.
+
+### `shouldSkipFileForBunyanScan(relativePosix)`
+
+Виключення для декларацій типів TypeScript.
+
+- Сигнатура: `shouldSkipFileForBunyanScan(relativePosix: string) => boolean`
+- Параметри:
+  - `relativePosix` (`string`) — шлях у posix-форматі (з `/`).
+- Повертає: `true`, якщо шлях завершується на `.d.ts` — такий файл містить лише типи й не повинен сканеритися; інакше `false`.
+- Side effects: відсутні.
+- Примітка: цей хелпер логічно йде паралельно до `isBunyanScanSourceFile`. Файл `*.d.ts` теж задовольнить `SOURCE_FILE_RE`, тож обхідник пакета має застосовувати **обидва** хелпери: спочатку відсіяти за розширенням, потім додатково пропустити `.d.ts`.
+
+## Залежності
+
+Зовнішні (`node_modules`):
+
+- `oxc-parser` — парсер JS/TS, експортує `parseSync`. Сканер користується вузлами `module.staticImports` (метадані статичних `import`-декларацій) та повним AST програми (`result.program`).
+
+Внутрішні (відносний імпорт з `../../../scripts/utils/ast-scan-utils.mjs`):
+
+- `dynamicImportModule(node)` — повертає рядок-аргумент динамічного `import('...')` або `null`.
+- `langFromPath(path)` — визначає `lang` (`'ts'`, `'tsx'`, `'js'`, `'jsx'`, …) за розширенням шляху для `parseSync`.
+- `normalizeSnippet(text)` — нормалізує сирий шматок коду перед збереженням у результат (типово стискає пробіли / обрізає).
+- `offsetToLine(content, offset)` — перетворює числовий offset у тексті на 1-індексований номер рядка.
+- `requireCallModule(node)` — повертає рядок-аргумент виклику `require('...')` або `null`.
+- `walkAstWithAncestors(program, ancestors, visitor)` — обхід AST з accumulator-предків (тут передається порожній масив; колбек дивиться лише на поточний `node`).
+
+Очікувані виклики (хто використовує цей модуль): чек-скрипти правила `js-run` (наприклад, `npm/rules/js-run/check-*.mjs`), які отримують вміст файлів пакета й передають їх у `findBunyanImportsInText`, після чого формують повідомлення про порушення з `line` / `snippet` / `module`. Обхідник файлів пакета використовує `isBunyanScanSourceFile` для фільтра кандидатів і `shouldSkipFileForBunyanScan` для виключень.
+
+## Потік виконання / Використання
+
+Типовий сценарій інтеграції в чек-правила:
+
+1. Обхідник перебирає всі файли пакета та конвертує шляхи у posix-формат.
+2. Для кожного `relativePosix` викликається `isBunyanScanSourceFile(relativePosix)`. Якщо `false` — файл пропускається.
+3. Якщо `shouldSkipFileForBunyanScan(relativePosix)` повертає `true` (тобто `*.d.ts`) — файл також пропускається.
+4. Інакше файл читається з диска (зовнішнім кодом), а його вміст подається у `findBunyanImportsInText(content, relativePosix)`.
+5. Усередині `findBunyanImportsInText`:
+   1. Обчислюється `lang` через `langFromPath(virtualPath)`.
+   2. Викликається `parseSync(virtualPath, content, { lang, sourceType: 'module' })` всередині `try/catch`.
+   3. Якщо парсер кинув виняток або в `result.errors` є записи — повертається `[]`.
+   4. Інакше перебираються `result.module?.staticImports ?? []`; для кожного `import`, де `moduleRequest.value` входить у `FORBIDDEN_MODULES`, до результату додається запис `{ line, snippet, module }`.
+   5. Далі `walkAstWithAncestors(result.program, [], visitor)` проходить по AST. У відвідувача:
+      - `requireCallModule(node)` повертає не-`null` для `require('...')` — якщо модуль заборонений, додаємо запис; інакше пропускаємо.
+      - `dynamicImportModule(node)` — те саме для динамічного `import('...')`.
+6. Викликач отримує плаский масив порушень і формує звіт (наприклад, друкує `path:line` та `snippet`).
+
+Гарантії та особливості:
+
+- Чисто синхронний прохід — жодного I/O всередині модуля.
+- Якщо файл містить синтаксичні помилки, результат `[]` означає **не «все добре»**, а «парсер не зрозумів файл» — це усвідомлене дизайн-рішення: спершу виправити синтаксис, потім перезапустити перевірку.
+- Регулярка `SOURCE_FILE_RE` не покриває нестандартні розширення (наприклад, `.vue`, `.svelte`). Якщо для них потрібен власний пайплайн (з вилученням `<script>` блоку), його треба будувати окремо.
+- Між списком `module.staticImports` і обходом AST вузли `import` не дублюються: статичні `import`-декларації обходяться лише через `module.staticImports`, а у візиторі перевіряються тільки `require` та динамічний `import(...)`.
+- Перелік заборонених модулів суворо обмежений `FORBIDDEN_MODULES` (рівність рядків). Підшляхи на кшталт `@nitra/bunyan/foo` не вловлюються — це навмисна вузька семантика правила.