@nitra/cursor 1.8.207 → 1.8.208

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.208] - 2026-05-08
+
+### Added
+
+- `mdc/js-run.mdc` (1.6, з 1.5): новий розділ «Нейминг файлів у `src/conn/`» — префікси `ql-` (GraphQL endpoint), `pg-`/`mysql-` з обовʼязковим `read`/`write` режимом і опційним ідентифікатором підключення для multi-БД (`pg-read-smart.js`, `pg-write-contract.js`); якщо режим не очевидний з імені env — визначати за наявністю операцій зміни даних. Також правило про експорти в `src/conn/`: заборонено `export default`, лише іменований експорт у camelCase від назви файла (`ql-smart.js` → `export const qlSmart`, `pg-write-contract.js` → `export const pgWriteContract`).
+- `scripts/utils/conn-file-rules.mjs` + інтеграція в `scripts/check-js-run.mjs` — для кожного файла всередині `#conn/` каталогу пакета перевіряє: (а) basename відповідає канону `ql-<id>` / `(pg|mysql)-(read|write)[-<id>]` (kebab-case `[a-z0-9-]`); (б) відсутній `export default`; (в) серед іменованих експортів є рівно `<camelCase(basename)>` (`pg-write-contract.js` → `pgWriteContract`). `index.*` пропускається як reexport-барель. Розпізнає `export const/let/var`, `export function`, `export class` і `export { x as Y }` через AST на oxc-parser.
+
 ## [1.8.207] - 2026-05-08
 
 ### Added

package/mdc/js-run.mdc

@@ -1,7 +1,7 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.5'
+version: '1.6'
 ---
 
 ## Область застосування
@@ -121,6 +121,47 @@ import { pool } from '#conn/pg.js'
 import { gql, graphQLClient } from '@nitra/graphql-request'
 ```
 
+### Нейминг файлів у `src/conn/`
+
+Назва файла в `src/conn/` має одразу повідомляти, **до чого** підключаємось і **в якому режимі**:
+
+- **GraphQL** — префікс `ql-`, далі ідентифікатор endpoint:
+  - `src/conn/ql-contract.js`
+  - `src/conn/ql-smart.js`
+- **PostgreSQL** — префікс `pg-`, далі тип підключення (репліка vs мастер): `read` або `write`:
+  - `src/conn/pg-read.js`
+  - `src/conn/pg-write.js`
+- **PostgreSQL до кількох БД** — додатково ідентифікатор підключення після типу:
+  - `src/conn/pg-read-smart.js`
+  - `src/conn/pg-write-contract.js`
+- **MySQL / MSSQL** — префікс `mysql-` за тією ж схемою (`mysql-read.js`, `mysql-write-<id>.js` тощо).
+
+Підключення до БД **обов'язково** має бути ідентифіковано як `read` (репліка) або `write` (мастер). Якщо з імені змінної оточення (наприклад, `env.PG_CONN`) це не очевидно — визнач режим за операціями в коді: якщо немає операцій зміни даних (`INSERT`/`UPDATE`/`DELETE`/DDL) — це `pg-read.js`, інакше `pg-write.js`.
+
+### Експорти у файлах `src/conn/`
+
+У файлах підключень **заборонений** `export default`. Експорт має бути **іменований** і збігатися з назвою файла в camelCase.
+
+Приклад — `src/conn/ql-smart.js`:
+
+```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.js` → `export const pgRead = …`, `pg-write-contract.js` → `export const pgWriteContract = …`, `ql-contract.js` → `export const qlContract = …`.
+
 ## CheckEnv
 
 Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми.
@@ -189,4 +230,10 @@ on:
 
 ## Перевірка
 
-`npx @nitra/cursor check js-run` — зокрема для кожного backend workspace-пакета з каталогом **`src/`** перевіряє наявність **`jsconfig.json`** і збіг вмісту з каноном вище.
+`npx @nitra/cursor check js-run` — зокрема для кожного backend workspace-пакета з каталогом **`src/`** перевіряє наявність **`jsconfig.json`** і збіг вмісту з каноном вище. Додатково для файлів у каталозі `#conn/` (за замовчуванням `src/conn/`) перевіряється:
+
+- **basename файла** відповідає канону: `ql-<id>` (GraphQL) / `(pg|mysql)-(read|write)[-<id>]` (БД), kebab-case `[a-z0-9-]`;
+- **відсутній `export default`** — лише іменований експорт;
+- **імʼя експорту** дорівнює camelCase від basename (`pg-write-contract.js` → `export const pgWriteContract`).
+
+Файли `index.*` у conn-каталозі пропускаються як можливий reexport-барель.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.207",
+  "version": "1.8.208",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/check-js-run.mjs

@@ -12,6 +12,11 @@
  *    дозволені лише у каталозі conn (за замовчуванням `src/conn/`; за наявності
  *    `package.json#imports['#conn/*']` — у його цільовому каталозі); поза ним — порушення
  *    (див. `utils/conn-imports-scan.mjs`);
+ *  - «Нейминг та експорти у `#conn/`»: всередині conn-каталогу basename файла має відповідати
+ *    канону `ql-<id>` / `(pg|mysql)-(read|write)[-<id>]`; `export default` заборонений; має бути
+ *    іменований експорт з імʼям, що дорівнює camelCase від basename файла (`pg-write-contract.js`
+ *    → `export const pgWriteContract`); `index.*` як reexport-барель пропускаємо
+ *    (див. `utils/conn-file-rules.mjs`);
  *  - «process.env / CheckEnv»: пряме `process.env.X` має бути замінено на `env` —
  *    з `@nitra/check-env` (для обов'язкових змінних, із `checkEnv([...])`) або з
  *    `node:process` (для опційних). Коли `env` імпортовано з `@nitra/check-env`,
@@ -40,6 +45,7 @@ import {
 import { findUncheckedProcessEnvInText, isCheckEnvScanSourceFile } from './utils/check-env-scan.mjs'
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import { findDepcheckViolationsForPackage, readAllWorkflowFiles } from './utils/depcheck-workflow.mjs'
+import { findConnFileRuleViolations, isConnFileRulesSourceFile } from './utils/conn-file-rules.mjs'
 import {
   findConnFactoryImportsInText,
   isConnImportsScanSourceFile,
@@ -51,48 +57,6 @@ import { findPromiseSetTimeoutInText, isPromiseSetTimeoutScanSourceFile } from '
 import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
-/** Канонічний `jsconfig.json` для backend workspace-пакетів із каталогом `src/` (js-run.mdc). */
-const CANONICAL_BACKEND_JSCONFIG = Object.freeze({
-  compilerOptions: Object.freeze({
-    lib: Object.freeze(['esnext']),
-    module: 'NodeNext',
-    moduleResolution: 'NodeNext',
-    target: 'esnext',
-    checkJs: false
-  }),
-  include: Object.freeze(['src/**/*'])
-})
-
-/**
- * Глибока рівність для JSON-подібних значень (масиви — порядок важливий).
- * @param {unknown} a перше значення
- * @param {unknown} b друге значення
- * @returns {boolean} true, якщо значення структурно ідентичні
- */
-function deepEqualJson(a, b) {
-  if (a === b) return true
-  if (a === null || b === null || typeof a !== typeof b) return false
-  if (typeof a !== 'object') return false
-  if (Array.isArray(a) !== Array.isArray(b)) return false
-  if (Array.isArray(a)) {
-    if (a.length !== b.length) return false
-    for (const [i, v] of a.entries()) {
-      if (!deepEqualJson(v, b[i])) return false
-    }
-    return true
-  }
-  const ao = /** @type {Record<string, unknown>} */ (a)
-  const bo = /** @type {Record<string, unknown>} */ (b)
-  const keysA = Object.keys(ao).toSorted()
-  const keysB = Object.keys(bo).toSorted()
-  if (keysA.length !== keysB.length) return false
-  for (const [i, k] of keysA.entries()) {
-    if (k !== keysB[i]) return false
-    if (!deepEqualJson(ao[k], bo[k])) return false
-  }
-  return true
-}
-
 /**
  * Чи існує непорожній за змістом маркер каталогу `src/` (рекомендована структура js-run).
  * @param {string} absPackageRoot абсолютний корінь пакета
@@ -108,40 +72,29 @@ function backendPackageHasSrcDir(absPackageRoot) {
 }
 
 /**
- * Перевіряє `jsconfig.json` для backend-пакетів із `src/`.
+ * FS-existence для `jsconfig.json` у backend-пакеті з каталогом `src/` (cross-file:
+ * наявність каталогу + файла). Структуру самого `jsconfig.json` (canonical
+ * compilerOptions і include) валідує `npm/policy/js_run/jsconfig/`; її прогоняє
+ * `bun run lint-conftest`.
  * @param {string} rootDir відносний шлях workspace
  * @param {string} absPackageRoot абсолютний корінь пакета
  * @param {string} label префікс `[pkg] `
  * @param {(msg: string) => void} fail callback для повідомлень про порушення
  * @param {(msg: string) => void} passFn callback для повідомлень про успішну перевірку
- * @returns {Promise<void>}
+ * @returns {void}
  */
-async function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn) {
+function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn) {
   if (!backendPackageHasSrcDir(absPackageRoot)) return
 
   const jcPath = join(rootDir, 'jsconfig.json')
-  if (!existsSync(jcPath)) {
+  if (existsSync(jcPath)) {
+    passFn(`${label}jsconfig.json є (структуру перевіряє bun run lint-conftest → js_run.jsconfig)`)
+  } else {
     fail(
       `${label}є каталог src/, але немає jsconfig.json — додай канонічний файл з js-run.mdc ` +
         `(NodeNext, include: src/**/*).`
     )
-    return
-  }
-  let parsed
-  try {
-    parsed = JSON.parse(await readFile(jcPath, 'utf8'))
-  } catch {
-    fail(`${label}jsconfig.json не вдалося розпарсити як JSON`)
-    return
-  }
-  if (!deepEqualJson(parsed, CANONICAL_BACKEND_JSCONFIG)) {
-    fail(
-      `${label}jsconfig.json не збігається з каноном js-run.mdc — заміни на шаблон з правила ` +
-        `(compilerOptions: lib esnext, module/moduleResolution NodeNext, target esnext, checkJs false; include: src/**/*).`
-    )
-    return
   }
-  passFn(`${label}jsconfig.json узгоджено з js-run (пакет з src/)`)
 }
 
 /**
@@ -236,6 +189,52 @@ async function checkConnImports(absPackageRoot, sourcePaths, pkgJson, label, fai
   return violations
 }
 
+/**
+ * Перевіряє правила нейминга та експортів для файлів усередині `#conn/`.
+ *
+ * Канон імені: `ql-<id>` для GraphQL, `(pg|mysql)-(read|write)[-<id>]` для БД (js-run.mdc,
+ * розділ «Нейминг файлів у `src/conn/`»). Експорт у файлі — лише іменований, з імʼям, що
+ * дорівнює camelCase від basename файла (`pg-write-contract.js` → `export const pgWriteContract`).
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів пакета
+ * @param {unknown} pkgJson розпарсений package.json пакета (або null)
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkConnFileNamingAndExports(absPackageRoot, sourcePaths, pkgJson, label, fail) {
+  const connDir = resolveConnDirFromPackageJson(pkgJson)
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!isInsideConnDir(rel, connDir)) continue
+    if (!isConnFileRulesSourceFile(rel)) continue
+    // пропускаємо реекспортний барель `index.*` (якщо знадобиться) і прихований .d.ts
+    const base = rel.slice(rel.lastIndexOf('/') + 1)
+    if (base.startsWith('index.')) continue
+
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findConnFileRuleViolations(content, rel)) {
+      violations++
+      if (v.kind === 'name') {
+        fail(
+          `${label}${rel} — назва файла в '${connDir}/' не відповідає канону js-run: ` +
+            `'ql-<id>', 'pg-{read|write}[-<id>]' або 'mysql-{read|write}[-<id>]' (kebab-case, [a-z0-9-])`
+        )
+      } else if (v.kind === 'default-export') {
+        fail(`${label}${rel} — 'export default' заборонений у '${connDir}/'; зроби іменований експорт`)
+      } else {
+        const found = v.foundNames?.length ? v.foundNames.join(', ') : '—'
+        fail(
+          `${label}${rel} — очікується іменований експорт 'export const ${v.expectedName} = …' ` +
+            `(camelCase від назви файла); знайдено: ${found}`
+        )
+      }
+    }
+  }
+  return violations
+}
+
 /**
  * Перевіряє правило «CheckEnv» для пакета.
  * @param {string} absPackageRoot абсолютний корінь пакета
@@ -323,6 +322,14 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
     passFn(`${label}імпорти підключень (bun#SQL / mssql / @nitra/graphql-request#GraphQLClient) лише в '${connDir}/'`)
   }
 
+  const connFileViolations = await checkConnFileNamingAndExports(absPackageRoot, sourcePaths, pkgJson, label, fail)
+  if (connFileViolations === 0) {
+    const connDir = resolveConnDirFromPackageJson(pkgJson)
+    passFn(
+      `${label}файли в '${connDir}/' дотримують канону js-run: нейминг (ql-/pg-/mysql-…) і іменований експорт у camelCase від basename`
+    )
+  }
+
   const envViolations = await checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail)
   if (envViolations === 0) {
     passFn(
@@ -390,15 +397,11 @@ async function loadPackageJsonAndCheckBunyanDeps(rootDir, label, fail) {
   const pkgPath = join(rootDir, 'package.json')
   if (!existsSync(pkgPath)) return null
   const pkgJson = JSON.parse(await readFile(pkgPath, 'utf8'))
-  const deps = /** @type {Record<string, unknown>} */ (pkgJson).dependencies
-  const devDeps = /** @type {Record<string, unknown>} */ (pkgJson).devDependencies
-  const allDeps = { ...deps, ...devDeps }
-  if (allDeps['@nitra/bunyan']) {
-    fail(`${label}@nitra/bunyan знайдено — замінити на @nitra/pino`)
-  }
-  if (allDeps.bunyan) {
-    fail(`${label}bunyan знайдено — замінити на @nitra/pino`)
-  }
+  // Заборону `@nitra/bunyan` / `bunyan` у dependencies/devDependencies перенесено
+  // в Rego (`npm/policy/js_run/package_json/`); `bun run lint-conftest` запускає
+  // її по всіх workspace `package.json`. Тут лишилася лише AST-перевірка імпортів.
+  void label
+  void fail
   return pkgJson
 }
 
@@ -411,20 +414,15 @@ async function loadPackageJsonAndCheckBunyanDeps(rootDir, label, fail) {
  * @param {(msg: string) => void} passFn успішне повідомлення
  * @returns {Promise<void>} завершується після перевірки configmap
  */
-async function checkOtelConfigmap(rootDir, label, fail, passFn) {
+function checkOtelConfigmap(rootDir, label, fail, passFn) {
   const configmapPath = join(rootDir, 'k8s', 'base', 'configmap.yaml')
   if (!existsSync(configmapPath)) return
-  const content = await readFile(configmapPath, 'utf8')
-  if (!content.includes('OTEL_RESOURCE_ATTRIBUTES')) {
-    fail(`${label}k8s/base/configmap.yaml не містить OTEL_RESOURCE_ATTRIBUTES`)
-    return
-  }
-  passFn(`${label}k8s/base/configmap.yaml містить OTEL_RESOURCE_ATTRIBUTES`)
-  if (content.includes('service.name=') && content.includes('service.namespace=')) {
-    passFn(`${label}OTEL_RESOURCE_ATTRIBUTES містить service.name та service.namespace`)
-  } else {
-    fail(`${label}OTEL_RESOURCE_ATTRIBUTES має містити service.name=<name>,service.namespace=<namespace>`)
-  }
+  // Перевірку `OTEL_RESOURCE_ATTRIBUTES` має містити `service.name=` /
+  // `service.namespace=` перенесено в Rego (`npm/policy/js_run/configmap/`);
+  // `bun run lint-conftest` запускає її на всіх `k8s/base/configmap.yaml`.
+  void label
+  void fail
+  passFn(`${rootDir}/k8s/base/configmap.yaml є (OTEL — bun run lint-conftest → js_run.configmap)`)
 }
 
 /**

package/scripts/utils/conn-file-rules.mjs

@@ -0,0 +1,170 @@
+/**
+ * Перевірки для файлів-підключень у каталозі `#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/MSSQL: `mysql-{read|write}.{ext}` або `mysql-{read|write}-<id>.{ext}`.
+ *
+ * Канонічний експорт — іменований, без `export default`. Імʼя константи має дорівнювати
+ * camelCase від basename файла (`pg-write-contract` → `pgWriteContract`).
+ *
+ * Парсимо через oxc-parser; коли файл не парситься — повертаємо порожні результати, щоб
+ * не змішувати помилки синтаксису з порушеннями цього правила.
+ */
+import { parseProgramOrNull } from './ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+
+/**
+ * Канонічний шаблон імені файла в каталозі conn.
+ *  - `ql-<id>` для GraphQL;
+ *  - `(pg|mysql)-(read|write)(-<id>)?` для БД.
+ * `<id>` — починається з [a-z0-9], далі [a-z0-9-]*.
+ */
+const CONN_FILENAME_RE =
+  /^(?:ql-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|(?:pg|mysql)-(?: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 >= 0 ? relativePathPosix.slice(last + 1) : relativePathPosix
+  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 >= 0 ? relativePathPosix.slice(last + 1) : relativePathPosix
+  return CONN_FILENAME_RE.test(base)
+}
+
+/**
+ * Збирає всі імена 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
+    const decl = /** @type {Record<string, unknown> | null} */ (rec.declaration ?? null)
+    if (decl) {
+      // export const X = ... / export let / export var
+      if (decl.type === 'VariableDeclaration' && Array.isArray(decl.declarations)) {
+        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)
+        }
+      }
+      // export function X / export class X
+      if (
+        (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') &&
+        decl.id &&
+        typeof decl.id === 'object' &&
+        typeof /** @type {Record<string, unknown>} */ (decl.id).name === 'string'
+      ) {
+        out.push(/** @type {string} */ (/** @type {Record<string, unknown>} */ (decl.id).name))
+      }
+    } else if (Array.isArray(rec.specifiers)) {
+      // export { X } / export { X as Y }
+      for (const s of rec.specifiers) {
+        const exported = /** @type {Record<string, unknown> | null} */ (s?.exported ?? null)
+        if (!exported) continue
+        // ESTree: Identifier (name) або Literal (value), залежно від спеки
+        if (exported.type === 'Identifier' && typeof exported.name === 'string') out.push(exported.name)
+        else if (typeof exported.value === 'string') out.push(exported.value)
+      }
+    }
+  }
+  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
+}