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

package/rules/vue/structure/structure.mdc

@@ -0,0 +1,101 @@
+## Структура папок
+
+```javascript
+const folderStructure = `
+  src/
+  components/
+  composables/
+  views/
+  router/
+  store/
+  assets/
+  public/
+  App.vue
+  main.mjs
+`
+```
+
+### Найменування файлів
+
+- **SFC:** імена файлів компонентів у **PascalCase** починаючи з букви N(`NMyWidget.vue`).
+- **Інші JS-модулі:** узгоджено **kebab-case** (`date-utils.mjs`).
+
+### Модулі та архітектура
+
+- **ES modules** (`import`/`export`), один модуль — одна відповідальність, уникай **circular dependencies**.
+- **Composition** замість успадкування; логіку для повторного використання винось у **composables** (замість зайвих HOC, де це доречно).
+
+### Code splitting
+
+- **Route-based:** lazy-імпорти в маршрутах (`() => import('...')`) і async components.
+
+## Додаткові вказівки
+
+```javascript
+const additionalInstructions = `
+1. Використовуй JavaScript
+2. Коректно оголошуй props, emits, defineModel
+3. За потреби використовуй компонент Teleport у Vue 3
+4. Застосовуй Suspense для async components
+5. Реалізуй належний error handling
+6. Дотримуйся Vue 3 style guide і naming conventions
+7. Використовуй Vite для швидкої розробки та збірки
+`
+```
+
+### Детальні вказівки
+
+1. **Vue router**: Завжди використовуй Vue router для маршрутизації в проекті версії 5 та його file-based routing.
+2. **Компонент Teleport**: Використовуй Teleport у Vue 3, коли потрібно рендерити поза поточною ієрархією DOM.
+3. **Suspense для async components**: Застосовуй Suspense для асинхронних компонентів і кращого UX.
+4. **Error handling**: Реалізуй глобальний error handling механізмами Vue 3, щоб коректно перехоплювати та обробляти помилки.
+5. **Style guide і naming**: Дотримуйся офіційного Vue 3 style guide і naming conventions для узгодженості кодової бази.
+6. **Vue macros**: Використовуй Vue macros для більш ефективного розробки компонентів.
+7. **Vue Reactivity Transform**: Використовуй Vue Reactivity Transform для змінних в компонентах.
+
+## Коментарі в `<template>`
+
+Додавай коментарі в `<template>` відповідно до логічного призначення блоку. Коментарі допомагають швидко орієнтуватися в розмітці.
+
+```vue
+<template>
+  <q-page>
+    <!-- ФІЛЬТРИ В ШАПЦІ -->
+    <teleport v-if="mounted" to="#header-filters">...</teleport>
+
+    <!-- ТАБЛИЦЯ -->
+    <q-table ... />
+
+    <!-- ДІАЛОГ РЕДАГУВАННЯ -->
+    <n-dialog v-model="editDialog">...</n-dialog>
+  </q-page>
+</template>
+```
+
+## Pinia store для стану сторінки
+
+Зберігай у Pinia store:
+
+- вибрані значення фільтрів
+- вибрані для відображення колонки (`NTableColumns`)
+- кількість записів на сторінці (pagination)
+
+Називай store за назвою сторінки або компонента — `customerPageStore`, `routePageStore` тощо. На сторінці звертайся до нього через змінну `pageStore`.
+
+```javascript
+// store/customerPage.mjs
+export const useCustomerPageStore = defineStore('customerPage', {
+  state: () => ({
+    filterName: '',
+    filterStatus: [],
+    columns: [],
+    rowsPerPage: 20
+  })
+})
+```
+
+```vue
+<script setup>
+const pageStore = useCustomerPageStore()
+</script>
+```

package/rules/vue/testing/concern.json

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

package/rules/vue/testing/testing.mdc

@@ -0,0 +1,40 @@
+## Тестування Vue-компонентів
+
+### Unit + Component / DOM
+
+**Vitest** (`vitest`) + **Vue Test Utils** з **happy-dom** як DOM-середовищем. Це канон, узгоджений з `test.mdc` (Stryker з vitest-runner + `perTest`-аналіз покриття). `vitest.config.mjs` повторно використовує `vite.config.js` через `mergeConfig` і перемикає `environment` на `'happy-dom'`:
+
+```js title="vitest.config.mjs"
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config.js'
+
+export default mergeConfig(viteConfig, defineConfig({
+  test: {
+    include: ['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}'],
+    environment: 'happy-dom',
+    coverage: { provider: 'v8', reporter: ['lcov', 'text-summary'] }
+  }
+}))
+```
+
+`jsdom` не використовуй — happy-dom швидший і достатній для типових Vue-компонентних тестів.
+
+У `package.json#scripts` тримай `"test": "vitest run"`; vitest devDeps (`vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`) — у кореневому `devDependencies` (npm-module rule забороняє devDeps у published workspace-у).
+
+### Чому цей файл — docs-only
+
+Вимога `scripts.test === "vitest run"` і `environment: 'happy-dom'` у `vitest.config` стосується Vue-пакетів, які **вже мають** компонентні тести. Не кожен workspace-пакет з `vue` у `dependencies` зобов'язаний мати компонентні тести на цьому етапі (наприклад, sandbox/demo-пакет для ручного прогону Vite-конфігурації без жодного `*.test.*` файлу) — механічна перевірка `scripts.test`/`vitest.config` для **усіх** таких пакетів дає хибні спрацювання там, де тестів свідомо ще немає. Тому концерн лишається docs-only.
+
+Суміжні вимоги вже перевіряються іншими concern-ами: кореневий `devDependencies` з `vitest`/`@vitest/coverage-v8`/`@stryker-mutator/vitest-runner` — концерн `packages` (`checkRootVitestDevDeps`); заборона `jsdom`/`vitest` у самому Vue-пакеті — Rego-концерн `package_json`.
+
+### E2E
+
+**Playwright** — змістовні сценарії користувацьких потоків.
+
+Проекту повинен бути покритий тестами E2E за допомогою Playwright.
+
+Вимога E2E-покриття Playwright не перевіряється механічно (немає детермінованого способу оцінити «повноту» покриття користувацьких сценаріїв) — залишається на розсуд ревʼю.
+
+### CI/CD
+
+У pipeline: **install**, **lint**, **test**, **vite build**; артефакти з продакшен-режиму.

package/rules/vue/tfm-translations/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "per-file",
+    "glob": ["**/*.vue"]
+  }
+}

package/rules/vue/tfm-translations/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/vue/tfm-translations/main.mjs
+docgen:
+  crc: 84fe5390
+---
+
+## Огляд
+
+Модуль перевіряє конвенцію `@nitra/tfm` з `vue.mdc` (розділ tfm-translations): якщо `.vue`-файл іменовано імпортує `tf` з `@nitra/tfm`, у тому ж файлі має бути оголошена функція `getTr`, що повертає обʼєкт перекладів.
+
+## Поведінка
+
+Per-file lint по змінених `.vue`-файлах (`ctx.files`). Для кожного файлу:
+
+- шукає іменований імпорт з `@nitra/tfm`, у списку якого є специфікатор `tf` (з опційним `as <alias>`);
+- якщо такий імпорт знайдено — перевіряє наявність у файлі оголошення `getTr` (`function getTr(...)` або `const/let getTr = ...`); відсутність — порушення.
+
+Файли без імпорту `tf` з `@nitra/tfm` (включно з імпортом лише інших експортів модуля, напр. `lang`) не перевіряються. Без `ctx.files` (delta відсутня) перевірка нічого не робить.
+
+## Публічний API
+
+`lint(ctx)` — detector-функція lint-поверхні: приймає контекст лінту (`cwd`, `files`), повертає список порушень.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перевіряє лише файли з розширенням `.vue`; інші файли зі списку `ctx.files` ігноруються.

package/rules/vue/tfm-translations/main.mjs

@@ -0,0 +1,55 @@
+/** @see ./docs/main.md */
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Іменований імпорт з `@nitra/tfm` — захоплює список імен усередині `{ ... }`. */
+const TFM_IMPORT_RE = /import\s*\{([^}]*)\}\s*from\s*['"]@nitra\/tfm['"]/
+
+/** Один запис іменованого імпорту `tf` (з опційним `as <alias>`). */
+const TF_SPECIFIER_RE = /^tf(?:\s+as\s+\w+)?$/
+
+/** Оголошення функції `getTr` — `function getTr(...)` або `const/let getTr = (...)`. */
+const GET_TR_DECL_RE = /(?:function\s+getTr\s*\(|(?:const|let|var)\s+getTr\s*=)/
+
+/**
+ * Чи імпортує вміст файлу `tf` (можливо з `as <alias>`) саме з `@nitra/tfm`.
+ * @param {string} content вихідний текст файлу
+ * @returns {boolean} `true`, якщо знайдено іменований імпорт `tf` з `@nitra/tfm`
+ */
+function importsTfFromTfm(content) {
+  const m = TFM_IMPORT_RE.exec(content)
+  if (!m) return false
+  return m[1].split(',').some(entry => TF_SPECIFIER_RE.test(entry.trim()))
+}
+
+/**
+ * Detector concern-а `tfm-translations`: якщо `.vue`-файл імпортує `tf` з `@nitra/tfm`,
+ * у цьому ж файлі має бути оголошена функція `getTr()` з перекладами (vue.mdc tfm-translations).
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту (`ctx.files` — delta-файли).
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат з порушеннями.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { fail } = reporter
+
+  if (ctx.files === undefined || ctx.files.length === 0) return reporter.result()
+
+  const { readFile } = await import('node:fs/promises')
+  const { join } = await import('node:path')
+  const { existsSync } = await import('node:fs')
+
+  for (const file of ctx.files) {
+    if (!file.endsWith('.vue')) continue
+    const absPath = join(ctx.cwd, file)
+    if (!existsSync(absPath)) continue
+    const content = await readFile(absPath, 'utf8')
+    if (!importsTfFromTfm(content)) continue
+    if (GET_TR_DECL_RE.test(content)) continue
+    fail(
+      `${file}: імпортує 'tf' з '@nitra/tfm', але не оголошує функцію getTr() з перекладами ` +
+        `(vue.mdc tfm-translations)`,
+      { file }
+    )
+  }
+
+  return reporter.result()
+}

package/rules/vue/tfm-translations/tfm-translations.mdc

@@ -0,0 +1,32 @@
+## @nitra/tfm — переклади
+
+Використовуй `@nitra/tfm` для всіх текстів. Переклади для всіх мов проекту оголошуй наприкінці `<script setup>` у функції `getTr()`. Змінна `lang` із `@nitra/tfm` — для визначення або зміни поточної мови застосунку.
+
+```vue
+<template>
+  {{ lang }}
+  {{ t`Анкеты` }}
+  {{ subtitle }}
+</template>
+<script setup>
+import { lang, tf as tfm } from '@nitra/tfm'
+const t = tfm.bind({ tr: getTr() })
+const subtitle = $computed(() => t`Анкеты`)
+
+/**
+ * LOCALIZATION
+ * @returns {object} translations
+ */
+function getTr() {
+  return {
+    Анкеты: { en: 'Surveys', ro: 'Sondaje', tr: 'Anketler' }
+  }
+}
+</script>
+```
+
+### Перевірка
+
+Якщо `.vue`-файл іменовано імпортує `tf` (з опційним `as <alias>`) саме з `@nitra/tfm`, у тому ж файлі має бути оголошена функція `getTr` (`function getTr(...)` або `const/let getTr = ...`). Файли, які не імпортують `tf` з `@nitra/tfm`, не перевіряються.
+
+Це лише синтаксична перевірка структури (наявність `getTr` поряд з імпортом `tf`) — вона **не** оцінює повноту чи коректність самих перекладів (усі мови проекту, актуальність рядків тощо), це залишається на розсуд ревʼю.

package/rules/vue/vite-config/concern.json

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

package/rules/vue/vite-config/vite-config.mdc

@@ -0,0 +1,153 @@
+## Vite-конфігурація: VueMacros, AutoImport, Layouts
+
+Потрібно використовувати **Vite версії 8.1 та вище** для frontend проекту на Vue.
+
+Потрібно використовувати **`unplugin-auto-import`** для автоматичного імпортування компонентів, composables, utils та інших функцій і прибирати з файлів усередині Vite проектів відповідні ручні імпорти, зокрема рядки виду `import { … } from 'vue'` — API Vue (`ref`, `computed`, `watch` тощо) мають підставлятися через auto-import, а не дублюватися явним імпортом з модуля `vue`.
+
+**Виняток — бібліотеки компонентів (`vue` у `peerDependencies`).** Увесь стек auto-import застосовується лише коли `vue` підключено як звичайну `dependencies`. Якщо ж пакет оголошує `vue` у `peerDependencies` — це проєкт-бібліотека компонентів: його джерела споживаються Vite-додатками і **не** проходять через `unplugin-auto-import` споживача. Тому до таких пакетів **не** застосовуються: заборона явних `import { ref, computed, … } from 'vue'` (вони обовʼязкові), вимога `'vue'` у `AutoImport.imports`, а також вимоги наявності `VueMacros` / `AutoImport` у `vite.config`. Решта перевірок (заборона `esbuild`, `process.env.npm_lifecycle_event` тощо) лишаються. Тригер винятку — `isVueComponentLibraryPkg` у `npm/rules/vue/packages/main.mjs`.
+
+Потрібно використовувати **`vite-plugin-vue-layouts-next`** для автоматичного імпортування layout компонентів.
+
+### Це вже перевіряється автоматично
+
+Увесь зміст цього файлу — вже реалізовані, а не лише документовані, перевірки:
+
+- **Обов'язкові залежності** (`vite` мажор ≥ 8 і мінор ≥ 1, `@vitejs/plugin-vue`, `vue-macros`, `unplugin-auto-import`, `vite-plugin-vue-layouts-next`) і **заборона** `esbuild`/`vitest`/`jsdom` у `package.json` — Rego-пакет `vue.package_json` (`npm/rules/vue/package_json/package_json.rego`, концерн `package_json`).
+- **`vite.config.{js,ts,mjs}`**: наявність `VueMacros`, `AutoImport` (і `'vue'` у його `imports`, якщо застосовний), `css: { transformer: 'lightningcss' }`, заборона `esbuild`, заборона `process.env.npm_lifecycle_event` (Bun-сумісність) — JS-концерн `packages` (`npm/rules/vue/packages/main.mjs`, функція `checkViteConfig`).
+- **`.vscode/extensions.json`** з рекомендацією `Vue.volar` — той самий концерн `packages` (`checkVueVolarRecommendation`).
+
+Цей concern (`vite-config`) залишається **docs-only** — він не додає нової перевірки, а лише зберігає розгорнутий еталонний приклад `vite.config.js`/`package.json` і пояснення для людини; фактичний gate — вище.
+
+### Еталонний `vite.config.js`
+
+```javascript title="vite.config.js"
+import Vue from '@vitejs/plugin-vue'
+import VueMacros from 'vue-macros/vite'
+import { defineConfig } from 'vite'
+import AutoImport from 'unplugin-auto-import/vite'
+import Layouts from 'vite-plugin-vue-layouts-next'
+
+export default defineConfig({
+  plugins: [
+    AutoImport({
+      imports: [
+        // presets
+        'vue',
+        'vue-router',
+        'quasar',
+        'pinia',
+        // custom
+        {
+          '@nitra/vite-boot/apollo': [
+            // named imports
+            'gql',
+            'useQuery',
+            'useMutation',
+            'useSubscription'
+          ],
+          '@nitra/consola': [
+            // named imports
+            'createLogger' // import { createLogger } from '@nitra/consola'
+          ]
+        }
+      ]
+    }),
+    VueMacros({
+      plugins: {
+        vue: Vue()
+      }
+    }),
+    Layouts()
+  ]
+})
+```
+
+### `npm_lifecycle_event` (Bun-сумісність)
+
+У більшості проектів у файлі `vite.config.js` є конструкція виду:
+
+```javascript
+switch (process.env.npm_lifecycle_event) {
+  case 'start-remote-tr': {
+```
+
+Вона перестала працювати з новим Bun. Тепер її треба обрамити у функцію і передавати `mode`:
+
+```javascript title="vite.config.js"
+function getProxy(mode) {
+  const proxy = {}
+
+  switch (mode) {
+    case 'remote-tr': {
+      proxy['^/auth/.*'] = 'https://tr.efes.cloud'
+      proxy['/file-link/'] = 'https://tr.efes.cloud'
+      break
+    }
+    default: {
+      proxy['^/auth/.*'] = 'https://dev.efes.cloud'
+      proxy['/file-link/'] = 'https://dev.efes.cloud'
+    }
+  }
+  return proxy
+}
+```
+
+```javascript title="vite.config.js"
+export default defineConfig(({ mode, command }) => {
+  // ...
+  server: {
+    proxy: getProxy(mode)
+  }
+})
+```
+
+### CSS-трансформер: lightningcss (обов'язково)
+
+У `vite.config` має бути `css: { transformer: 'lightningcss' }`:
+
+```javascript title="vite.config.js"
+export default defineConfig({
+  css: {
+    transformer: 'lightningcss'
+  },
+  // ...
+})
+```
+
+Lightningcss ~18% швидше за sass-трансформер на типовому Vue+Quasar-проєкті. Потрібний `lightningcss` у `devDependencies`.
+
+**Виняток:** бібліотеки компонентів (`vue` у `peerDependencies`) від цієї вимоги звільнені — вони не збираються напряму.
+
+### esbuild заборонено
+
+У проєкті не має бути залежності `esbuild` і згадок `esbuild` у конфігах/коді. Якщо десь є налаштування або інструкції під `esbuild` — заміни на **rolldown**.
+
+### Еталонний `package.json`
+
+мінімальний повний `package.json` для Vite + Vue + `vue-macros` (версії підлаштуй під проєкт):
+
+```json title="package.json"
+{
+  "name": "my-vue-app",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vue": "^3.6.12"
+  },
+  "devDependencies": {
+    "vite": "^8.1.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "vue-macros": "^3.1.2"
+  }
+}
+```
+
+### VS Code розширення
+
+У файлі `.vscode/extensions.json` потрібна рекомендація для Vue:
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["Vue.volar"]
+}
+```

package/rules/vue/vite-env/concern.json

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

package/rules/vue/vite-env/vite-env.mdc

@@ -0,0 +1,61 @@
+## Vite client types (Volar, імпорти асетів)
+
+Без типів **Vite** редактор (Volar / TypeScript) не знає, що імпорт статичного файлу (`import url from './hero.avif'`, `*.png`, `*.svg` тощо) відповідає модулю з `string` URL. Тоді у `.vue` з'являється помилка на кшталт **Cannot find module '…' or its corresponding type declarations**.
+
+У **кожному** workspace-пакеті з **Vue + Vite** обов'язково:
+
+1. **`src/vite-env.d.ts`** — рівно з посиланням на клієнтські типи Vite (одного рядка достатньо):
+
+```ts title="src/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+Так підтягуються декларації з `vite/client.d.ts` (`declare module '*.avif'`, `*.png`, …).
+
+2. **Корінь пакета:** **`jsconfig.json`** із **`include`**, що охоплює `src` (наприклад `"include": ["src/**/*"]`), щоб мова служби бачила `vite-env.d.ts` і SFC.
+
+Мінімальний приклад для JS-пакета:
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowJs": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Не** звужуй без потреби **`compilerOptions.types`** до `["vite/client"]`: це може відрізати інші пакети з `@types` і зламати інші підказки. Достатньо `/// <reference types="vite/client" />` у `vite-env.d.ts` і коректного `include`.
+
+### Ця частина вже перевіряється автоматично
+
+Наявність `src/vite-env.d.ts` з коректним `/// <reference types="vite/client" />` і наявність `jsconfig.json` у корені пакета — вже реалізований JS-концерн `packages` (`npm/rules/vue/packages/main.mjs`, функція `checkViteClientEnvAndEditorConfig`). Цей concern (`vite-env`) не дублює перевірку — лишається docs-only довідкою з еталонним прикладом.
+
+## Статичні файли — BASE_URL
+
+Для підключення статичних файлів не використовуй відносні шляхи. Завжди будуй URL через `import.meta.env.BASE_URL`:
+
+```vue
+<!-- Погано -->
+<img src="/logo.png" />
+<img src="./assets/logo.png" />
+
+<!-- Добре -->
+<img :src="baseUrl + 'logo.png'" />
+```
+
+```javascript
+const baseUrl = import.meta.env.BASE_URL
+```
+
+Ця вимога **не** перевіряється механічно: рядок-специфікатор `src` може легітимно вказувати на зовнішній URL, дата-URI чи інший валідний шлях, і однозначно відрізнити «статичний асет проекту» від інших випадків без хибних спрацювань неможливо — залишається на розсуд ревʼю.