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

package/rules/js-run/lib/conn-file-rules.mjs

@@ -0,0 +1,214 @@
+/**
+ * Перевірки для файлів-підключень у каталозі `#conn` (js-run.mdc → «Нейминг файлів у `src/conn/`»
+ * та «Експорти у файлах `src/conn/`»).
+ *
+ * Канонічна назва файла:
+ *  - GraphQL: `ql-<id>.{js|mjs|cjs|ts|mts|cts}` (id — kebab-case ідентифікатор endpoint);
+ *  - PostgreSQL: `pg-{read|write}.{ext}` або `pg-{read|write}-<id>.{ext}` (id — для multi-БД);
+ *  - MySQL: `mysql-{read|write}.{ext}` або `mysql-{read|write}-<id>.{ext}`;
+ *  - MSSQL: `mssql-{read|write}.{ext}` або `mssql-{read|write}-<id>.{ext}`.
+ *
+ * Канонічний експорт — іменований, без `export default`. Імʼя константи має дорівнювати
+ * camelCase від basename файла (`pg-write-contract` → `pgWriteContract`).
+ *
+ * Парсимо через oxc-parser; коли файл не парситься — повертаємо порожні результати, щоб
+ * не змішувати помилки синтаксису з порушеннями цього правила.
+ */
+import { parseProgramOrNull } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+
+/**
+ * Канонічний шаблон імені GraphQL-файла: `ql-<id>.<ext>`.
+ * `<id>` — kebab без leading/trailing-`-`, починається/закінчується на `[a-z0-9]`.
+ */
+const CONN_FILENAME_QL_RE = /^ql-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.[cm]?[jt]sx?$/u
+/**
+ * Канонічний шаблон імені файла БД-підключення: `(pg|mysql|mssql)-(read|write)(-<id>)?.<ext>`.
+ * `<id>` — за тими ж правилами, що й для `ql-`. Розділили з GraphQL-формою, щоб
+ * не множити комплексність regex (sonarjs/regex-complexity).
+ */
+const CONN_FILENAME_DB_RE = /^(?:pg|mysql|mssql)-(?:read|write)(?:-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)?\.[cm]?[jt]sx?$/u
+
+/**
+ * Чи це файл, який сканується правилом «conn-file» (JS/TS-сімʼя, без `.d.ts`).
+ * @param {string} relativePathPosix відносний posix-шлях
+ * @returns {boolean} true, якщо потрібно перевіряти
+ */
+export function isConnFileRulesSourceFile(relativePathPosix) {
+  return SOURCE_FILE_RE.test(relativePathPosix) && !relativePathPosix.endsWith('.d.ts')
+}
+
+/**
+ * Витягує basename файла без розширення.
+ * @param {string} relativePathPosix відносний шлях у posix-форматі
+ * @returns {string} basename без розширення (наприклад, `pg-write-contract`)
+ */
+function basenameNoExt(relativePathPosix) {
+  const last = relativePathPosix.lastIndexOf('/')
+  const base = last === -1 ? relativePathPosix : relativePathPosix.slice(last + 1)
+  const dot = base.lastIndexOf('.')
+  return dot > 0 ? base.slice(0, dot) : base
+}
+
+/**
+ * Перетворює kebab-case ідентифікатор у camelCase.
+ * @param {string} kebab kebab-case рядок (`pg-write-contract`)
+ * @returns {string} camelCase (`pgWriteContract`)
+ */
+export function kebabToCamel(kebab) {
+  return kebab.replaceAll(/-([a-z0-9])/gu, (_m, c) => c.toUpperCase())
+}
+
+/**
+ * Чи відповідає назва файла канонічному шаблону для каталогу conn.
+ * @param {string} relativePathPosix відносний posix-шлях файла
+ * @returns {boolean} true, якщо basename + ext збігається зі схемою
+ */
+export function isConnFileNameValid(relativePathPosix) {
+  const last = relativePathPosix.lastIndexOf('/')
+  const base = last === -1 ? relativePathPosix : relativePathPosix.slice(last + 1)
+  return CONN_FILENAME_QL_RE.test(base) || CONN_FILENAME_DB_RE.test(base)
+}
+
+/**
+ * Витягує імена з `export const/let/var X = …` (включно з кількома declarators у одному `export const a, b`).
+ * @param {Record<string, unknown>} decl AST `VariableDeclaration`
+ * @returns {string[]} імена змінних
+ */
+function namesFromVariableDeclaration(decl) {
+  if (!Array.isArray(decl.declarations)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const d of decl.declarations) {
+    const id = /** @type {Record<string, unknown> | null} */ (d?.id ?? null)
+    if (id && id.type === 'Identifier' && typeof id.name === 'string') out.push(id.name)
+  }
+  return out
+}
+
+/**
+ * Витягує імʼя з `export function X` / `export class X`.
+ * @param {Record<string, unknown>} decl AST `FunctionDeclaration` або `ClassDeclaration`
+ * @returns {string | null} імʼя або `null`, якщо id-вузол анонімний
+ */
+function nameFromFnOrClassDeclaration(decl) {
+  if (decl.type !== 'FunctionDeclaration' && decl.type !== 'ClassDeclaration') return null
+  const id = /** @type {Record<string, unknown> | null} */ (decl.id ?? null)
+  if (!id || typeof id !== 'object') return null
+  return typeof id.name === 'string' ? id.name : null
+}
+
+/**
+ * Витягує експортоване імʼя з одного `ExportSpecifier` (`export { X }` / `export { X as Y }`).
+ * @param {Record<string, unknown> | null | undefined} specifier AST `ExportSpecifier`
+ * @returns {string | null} імʼя або `null`
+ */
+function nameFromExportSpecifier(specifier) {
+  const exported = /** @type {Record<string, unknown> | null} */ (specifier?.exported ?? null)
+  if (!exported) return null
+  if (exported.type === 'Identifier' && typeof exported.name === 'string') return exported.name
+  if (typeof exported.value === 'string') return exported.value
+  return null
+}
+
+/**
+ * Імена з одного `ExportNamedDeclaration` — або з вкладеного `declaration`, або зі списку `specifiers`.
+ * @param {Record<string, unknown>} rec AST `ExportNamedDeclaration`
+ * @returns {string[]} імена цього експортного вузла
+ */
+function namesFromNamedExport(rec) {
+  const decl = /** @type {Record<string, unknown> | null} */ (rec.declaration ?? null)
+  if (decl) {
+    if (decl.type === 'VariableDeclaration') return namesFromVariableDeclaration(decl)
+    const fnOrClass = nameFromFnOrClassDeclaration(decl)
+    return fnOrClass ? [fnOrClass] : []
+  }
+  if (!Array.isArray(rec.specifiers)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const s of rec.specifiers) {
+    const name = nameFromExportSpecifier(/** @type {Record<string, unknown> | null} */ (s ?? null))
+    if (name) out.push(name)
+  }
+  return out
+}
+
+/**
+ * Збирає всі імена named-експортів у програмі.
+ *
+ * Покриває: `export const/let/var X`, `export function X`, `export class X`,
+ * `export { X }`, `export { X as Y }` (повертає `Y`). `export *` ігнорується
+ * (немає конкретного імені для звірки), `export default` обробляється окремо.
+ * @param {unknown} program AST root
+ * @returns {string[]} список експортованих імен
+ */
+function collectNamedExportNames(program) {
+  /** @type {string[]} */
+  const out = []
+  if (!program || typeof program !== 'object') return out
+  const body = /** @type {Record<string, unknown>} */ (program).body
+  if (!Array.isArray(body)) return out
+  for (const node of body) {
+    if (!node || typeof node !== 'object') continue
+    const rec = /** @type {Record<string, unknown>} */ (node)
+    if (rec.type !== 'ExportNamedDeclaration') continue
+    out.push(...namesFromNamedExport(rec))
+  }
+  return out
+}
+
+/**
+ * Чи є в програмі `export default ...`.
+ * @param {unknown} program AST root
+ * @returns {boolean} true, якщо знайдено будь-який ExportDefaultDeclaration
+ */
+function hasDefaultExport(program) {
+  if (!program || typeof program !== 'object') return false
+  const body = /** @type {Record<string, unknown>} */ (program).body
+  if (!Array.isArray(body)) return false
+  for (const node of body) {
+    if (
+      node &&
+      typeof node === 'object' &&
+      /** @type {Record<string, unknown>} */ (node).type === 'ExportDefaultDeclaration'
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Знаходить порушення правил для одного файла з каталогу conn.
+ *
+ * Якщо AST не парситься — повертає порожній масив (синтаксис падає в інших перевірках,
+ * не дублюємо).
+ * @param {string} content вихідний код файла
+ * @param {string} relativePathPosix відносний posix-шлях файла (від кореня пакета)
+ * @returns {{ kind: 'name' | 'default-export' | 'export-name', expectedName?: string, foundNames?: string[] }[]} список порушень
+ */
+export function findConnFileRuleViolations(content, relativePathPosix) {
+  /** @type {{ kind: 'name' | 'default-export' | 'export-name', expectedName?: string, foundNames?: string[] }[]} */
+  const out = []
+  if (!isConnFileNameValid(relativePathPosix)) {
+    out.push({ kind: 'name' })
+    // якщо назва нестандартна — далі звірку імені експорту не робимо (camelCase двозначний)
+  }
+
+  const program = parseProgramOrNull(content, relativePathPosix)
+  if (!program) return out
+
+  if (hasDefaultExport(program)) {
+    out.push({ kind: 'default-export' })
+  }
+
+  if (out.some(v => v.kind === 'name')) return out
+
+  const expected = kebabToCamel(basenameNoExt(relativePathPosix.slice(relativePathPosix.lastIndexOf('/') + 1)))
+  const names = collectNamedExportNames(program)
+  if (!names.includes(expected)) {
+    out.push({ kind: 'export-name', expectedName: expected, foundNames: names })
+  }
+  return out
+}

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 '@7n/rules/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: plugins/lang-js/rules/js-run/lib/bunyan-imports.mjs
+docgen:
+  crc: 2494f203
+---
+
+Модуль `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` не вловлюються — це навмисна вузька семантика правила.