@7n/rules-lang-js 0.10.0 → 0.12.0

package/rules/storybook/ci/template/lint-storybook.yml.snippet.yml

@@ -0,0 +1,41 @@
+name: Lint Storybook
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/*.stories.@(js|ts)'
+      - '**/.storybook/**'
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  storybook-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          __STORYBOOK_CI_PACKAGE_DIRS__
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - uses: ./.github/actions/setup-playwright-chromium
+
+      - name: Storybook vitest project (${{ matrix.package }})
+        working-directory: ${{ matrix.package }}
+        run: bunx vitest run --project=storybook

package/rules/storybook/ci/template/setup-playwright-chromium.action.yml

@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-action.json
+
+name: Setup Playwright Chromium
+description: >-
+  Кеш Playwright-браузерів (лише chromium, storybook.mdc ADR Кластер 5) для vitest
+  browser-mode storybook-проєкту. Викликати ПІСЛЯ ./.github/actions/setup-bun-deps
+  (потрібен node_modules/bun.lock для визначення версії).
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve Playwright version (bun.lock)
+      id: playwright-version
+      shell: bash
+      run: |
+        VERSION=$(grep -oE '"playwright(-core)?@[0-9]+\.[0-9]+\.[0-9]+"' bun.lock | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || true)
+        if [ -z "$VERSION" ]; then
+          VERSION=$(node -p "require('playwright-core/package.json').version" 2>/dev/null || echo unknown)
+        fi
+        echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+    - name: Cache Playwright browsers (chromium)
+      id: playwright-cache
+      uses: actions/cache@v5
+      with:
+        path: |
+          ~/.cache/ms-playwright
+          ~/Library/Caches/ms-playwright
+        key: ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}-chromium
+
+    - name: Install Playwright chromium (лише chromium, storybook.mdc)
+      if: steps.playwright-cache.outputs.cache-hit != 'true'
+      shell: bash
+      run: bunx playwright install chromium --with-deps

package/rules/storybook/hygiene/concern.json

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

package/rules/storybook/main.json

@@ -1 +1 @@
-{ "auto": { "glob": ["package.json", "**/*.vue", ".storybook/**"] } }
+{ "auto": { "glob": ["**/package.json", "**/*.vue", "**/.storybook/**"] } }

package/rules/storybook/main.mdc

@@ -1,7 +1,7 @@
 ---
 description: Канонічний Storybook для Vue-компонентних бібліотек — скафолд, vitest/Stryker, гігієна залежностей, рецепти мокання
 version: '1.0'
-globs: ["package.json", "**/*.vue", ".storybook/**"]
+globs: ["**/package.json", "**/*.vue", "**/.storybook/**"]
 alwaysApply: false
 ---
 
@@ -31,18 +31,39 @@ alwaysApply: false
 
 - **Порядок Vite-плагінів фіксований**: `@vitejs/plugin-vue` **перед** `quasar()` — інакше Quasar-плагін не бачить SFC, уже скомпільований `plugin-vue`.
 - **Layout-детекція**: `src/components/` присутній → stories-glob звужується до нього; пласка структура (`src/` без `components/`) — ширший glob по всьому `src/`.
-- **`viteFinal`** зчитує `vite.config` самого пакета (той самий, що й для звичайного білду) і мерджить його плагіни в конфіг Storybook, **знімаючи** `vite-plugin-pages`/`vite-plugin-vue-layouts` — файлова маршрутизація належить додатку-споживачу, не ізольованому рендеру компонента.
+- **`viteFinal`** зчитує `vite.config` самого пакета (той самий, що й для звичайного білду) і мерджить його плагіни в конфіг Storybook, **знімаючи** роутинг-плагіни файлової маршрутизації додатка-споживача (`vite-plugin-pages`, `unplugin-vue-router`, `vite-plugin-vue-layouts`, `vite-plugin-vue-layouts-next`) — вони не мають сенсу в ізольованому рендері компонента. Плагіни `plugins`-масиву можуть бути `Promise`/вкладеними масивами (`VueMacros({ plugins: { vue: Vue() } })` — реальний стек пілотного консюмера повертає `Promise`, що резолвиться в масив плагінів) — фільтр спершу resolve/flatten-ить їх, інакше порівняння імені з `Promise`, що ще не резолвився, мовчки пропускає дублікат `@vitejs/plugin-vue`-трансформу (подвійна SFC-трансформація). Vue-трансформери фільтруються за сімейством імені (`vite:vue`-префікс або підрядок `vue-macros`), не лише буквальним `@vitejs/plugin-vue` — деталі й обґрунтування коментарем у `scaffold/template/main.js`.
+- **`core.builder.options.viteConfigPath` на `.storybook/empty-vite.config.js` — ОБОВ'ЯЗКОВИЙ, не опційний.** Емпірично підтверджено (лише через `storybook build`, `dev --smoke-test` не ловить): без явного `viteConfigPath` `@storybook/builder-vite` сам через `loadConfigFromFile` знаходить `../vite.config.js` пакета ЩЕ ДО виклику `viteFinal` і домерджує його НЕФІЛЬТРОВАНІ плагіни в `storybookConfig` — фільтр у `viteFinal` тоді лише ДОДАЄ ще один `@vitejs/plugin-vue`, а не прибирає вже змерджений builder-vite дублікат (подвійна SFC-трансформація, `storybook build` падає на кожному `.vue`). `empty-vite.config.js` — канонічний порожній `defineConfig({})`-стенд-ін, генерується скафолдом поряд з `main.js`; окрема секція перевірки/adopt-діагностики (не частина `MAIN_JS_MARKERS` — main.js може бути канонічним, а сусідній файл видалено окремо).
 - **`staticDirs`** покриває `.storybook/public` — статичний asset для msw service worker (`preview.js`).
-- **`preview.js`**: повний `Quasar`-install (не тільки окремі компоненти) + `iconSet`+`iconMapFn`-комбо — без цієї пари внутрішні Quasar-компоненти (напр. стрілка `QSelect`) не резолвлять вбудовані іконки поза full CLI build. `msw-storybook-addon` ініціалізується з `onUnhandledRequest`-фільтром: **same-origin GET мовчки пропускається** (Vite HMR/asset-шум), решта — попередження (не білд-помилка — навмисно м'яко для хвилі 1).
+- **`preview.js`**: повний `Quasar`-install (не тільки окремі компоненти) + `iconSet`+`iconMapFn`-комбо — без цієї пари внутрішні Quasar-компоненти (напр. стрілка `QSelect`) не резолвлять вбудовані іконки поза full CLI build. Обидва `iconSet` — підшляховий default-імпорт (`quasar/icon-set/svg-material-icons`, `quasar/icon-set/material-icons`), **НЕ** named-import `iconSet` напряму з пакета `quasar` — quasar 2.18.x не має такого runtime-binding (лише компонент `IconSet` з великої літери), `@quasar/vite-plugin`-transform падає на такому специфікаторі. `msw-storybook-addon` ініціалізується з `onUnhandledRequest`-фільтром: **same-origin GET мовчки пропускається** (Vite HMR/asset-шум), решта — попередження (не білд-помилка — навмисно м'яко для хвилі 1). Мережевий мок підключається через `loaders: [mswLoader]`, **не** `decorators: [mswDecorator]` — `mswDecorator` deprecated у `msw-storybook-addon` 2.x (буде видалений у наступному релізі), `mswLoader` виконується per-story до рендеру.
 - **`.storybook/mocks/gql-sse.js`**: єдиний канонічний хелпер `sseSubscription` для MSW-мокання Apollo-підписок через wire-протокол `graphql-sse` (`event: next\ndata: …`, distinct-connection mode) — переносити цю логіку в кожен пакет окремо заборонено, є одне джерело істини.
 - **`package.json#scripts.storybook`** — уніфікований скрипт, однаковий для всіх пакетів у скоупі (значення — `scaffold/main.mjs`, не дублюється тут).
 
 Перевірка присутності й ключових маркерів канону — `scaffold/main.mjs`; детерміноване відтворення відсутніх файлів із `scaffold/template/` — `scaffold/fix-scaffold.mjs` (fixability: `config` — канонічна форма одна, LLM у ланцюжку фіксу не потрібен).
 
+### knip-виключення для `.storybook/`-артефактів
+
+Кожен adopt цього канону наступає на ту саму knip-проблему: `empty-vite.config.js` (динамічний шлях через `join(dirName, …)` у `main.js` — knip не резолвить `join`-конструйовані шляхи), `mocks/apollo.js` (точковий alias-мок, `mocking.mdc` — не кожен пакет його використовує) і `mocks/gql-sse.js` (helper, статично імпортується лише зі story-файлів, яких у щойно заскафолженому пакеті може ще не бути) регулярно фолсяться knip-ом як orphan-files. Канонічний фікс — **docs-only** сніпет, не автофікс: механізм `js/check` copy-once канону `knip.json` (`n-js.mdc`) свідомо **не ревалідує** вміст після першого створення (консюмер вільно кастомізує), тож програмний patch наявного `knip.json` консюмера конфліктував би з цим дизайн-рішенням і вимагав би нового merge-механізму замість наявного copy-if-missing. Додай вручну в `knip.json` консюмера (root або поряд з першим `.storybook/`):
+
+```json
+{
+  "ignore": ["**/.storybook/empty-vite.config.js", "**/.storybook/mocks/apollo.js", "**/.storybook/mocks/gql-sse.js"]
+}
+```
+
+(домердж у наявний масив `ignore`, не заміна). Звірено з реальним `knip.json` пілотного консюмера.
+
 ## Vitest-конфіг і Stryker-ізоляція (Кластер 5)
 
 Канонічний `test.projects` (`unit`+`storybook`, browser-mode лише chromium) і ізольований `vitest.stryker.config` (той самий unit-набір, без browser-mode — `@stryker-mutator/vitest-runner` крашиться на browser-mode `projects`) — `vitest-config/main.mjs` (перевірка, AST через `oxc-parser`) і `vitest-config/fix-vitest-config.mjs` (точкові insert-only правки наявного конфіга, fixability: `config`). Деталі канону, чому саме chromium і межі автофіксу — `vitest-config/vitest-config.mdc`, не дублюється тут.
 
+### CI: Playwright-кеш і швидкий PR-прогін (Кластер 5, CI-частина)
+
+`ci/main.mjs` + `ci/fix-ci.mjs` (fixability: `config`, `requires.capability: ci:github` — спить у репозиторіях без плагіна `@7n/rules-ci-github`): для кожного репозиторію з бодай одним пакетом у скоупі — канонічний composite action `.github/actions/setup-playwright-chromium/action.yml` (кеш `~/.cache/ms-playwright`/`~/Library/Caches/ms-playwright` за версією playwright з `bun.lock`, install **лише** `chromium --with-deps` при cache miss) і `.github/workflows/lint-storybook.yml` (матриця `strategy.matrix.package` — фактичні пакети у скоупі, `checkout` → `setup-bun-deps` → `setup-playwright-chromium` → `vitest run --project=storybook`). Композитний action і workflow — репо-рівневі файли (не per-package), перевірка й автофікс не per-package.
+
+`workflow.on.push.paths` — **`**/.storybook/**`** (не `.storybook/**` без префіксу): пакет у скоупі майже завжди лежить не в корені репозиторію (`npm/.storybook/**` тощо), а GitHub Actions `paths`-глоб без `**/`-префіксу анкорить збіг до кореня репо й мовчки не спрацьовує на push у вкладений пакет. Той самий анкоринг-баг був і в усіх `concern.json#lint.glob`/`main.json#auto.glob`-патернах цього правила (`package.json`, `.storybook/**`, `vitest.config.*` без префіксу) — виправлено разом, звірено емпірично на пілотному консюмері (`components/.github/workflows/lint-storybook.yml`).
+
+Nightly-only `@7n/test coverage` (mutation testing) — свідомо поза цим concern-ом: ADR розділяє швидкий PR-шлях (`--project=storybook`, цей concern) і nightly mutation-прогін, який лишається окремою інфраструктурою (`test/stryker_config`) і не дублюється тут.
+
 ## Гігієна сторонніх залежностей (Кластер 6)
 
 `hygiene/main.mjs`: (1) undeclared third-party imports у `.vue`-файлах пакета — import стороннього пакета, якого немає в `dependencies`/`peerDependencies` (реальний кейс ADR — зламаний default-export `@vuepic/vue-datepicker` v14, silent breakage без цієї перевірки); (2) наявність `src/css/quasar.variables.{scss,sass}` без відповідного `quasar({ sassVariables: true })` у `.storybook/main.js` — глобальні Quasar SCSS-змінні пакета інакше не резолвляться в ізольованому Storybook-рендері. Docs-only детальний виклад не потрібен — концерн самодостатній, без окремого `.mdc`.

package/rules/storybook/mocking/mocking.mdc

@@ -73,6 +73,30 @@ export const Realtime = {
 }
 ```
 
+### Точковий alias-мок одного модуля
+
+**Скоуп цього рецепта — компонентні бібліотеки, НЕ сторінки.** Рішення «виключно MSW» вище (розділ «Apollo/GraphQL — виключно MSW») стосується сторінок (розширення ADR, `2026-07-20`) — там повний data-flow (query+mutation+subscription, кілька викликів на сторінку), і мок-хендлери мають бути переносними в майбутні vitest/playwright-сценарії. Реальний кейс компонентної бібліотеки (пілот `components/npm`) — інший: один компонент статично імпортує модуль із side-effect на рівні build-у (напр. `@nitra/vite-boot/apollo` — конструює Apollo-клієнт із `VITE_HASURA_HOST`/WS-link env-змінних, яких немає в Storybook), і компонент має 1-2 точкові виклики цього модуля, не повний GraphQL data-flow. Розгортати MSW-стек (`msw-storybook-addon`, worker, handlers) заради одного статичного імпорту — зайві накладні витрати, надто коли `msw` навіть не встановлений у пакеті.
+
+Рецепт — build-time підміна імпорту на рівні Vite-resolve у `viteFinal` `.storybook/main.js` (не мокає мережу, підміняє сам модуль):
+
+```js
+async viteFinal(config) {
+  const { mergeConfig } = await import('vite')
+  return mergeConfig(config, {
+    resolve: {
+      alias: {
+        // NImages.vue статично імпортує apolloClient/gql (не provide/inject) — реальний
+        // модуль конструює Apollo-клієнт з env-змінних, яких немає в Storybook.
+        // Підміна на рівні Vite-resolve замість зміни коду компонента.
+        '@nitra/vite-boot/apollo': join(dirName, 'mocks/apollo.js')
+      }
+    }
+  })
+}
+```
+
+**Критерій вибору:** компонент з 1-2 точковими викликами стороннього модуля (side-effect boot/client-конструктор, не повний query/mutation/subscription-flow) → alias-мок одного модуля. Сторінки, підписки чи повний GraphQL data-flow (кілька query/mutation, стан, error/loading-сценарії) → MSW (розділ вище) — не супереч рішенню розширення ADR, а розмежування скоупу: alias — для компонентних бібліотек із мінімальним мережевим слідом, MSW — для сторінок і повнішого data-flow.
+
 ### Pinia
 
 Справжня `createPinia()` у page-декораторі — **без** `pinia-plugin-persistedstate` (`persist: true` у сторі стає no-op, читання/запис localStorage не потрібні в ізольованому рендері). Наповнення початкового стану — через `parameters.pinia.initialState`, не хардкод у декораторі:

package/rules/storybook/scaffold/concern.json

@@ -1,5 +1,5 @@
 {
   "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
   "fixability": "config",
-  "lint": { "scope": "full", "glob": ["package.json", "**/*.vue", ".storybook/**"] }
+  "lint": { "scope": "full", "glob": ["**/package.json", "**/*.vue", "**/.storybook/**"] }
 }

package/rules/storybook/scaffold/docs/fix-scaffold.md

@@ -3,7 +3,7 @@ type: JS Module
 title: fix-scaffold.mjs
 resource: plugins/lang-js/rules/storybook/scaffold/fix-scaffold.mjs
 docgen:
-  crc: 31a867f5
+  crc: 10336699
   model: openai-codex/gpt-5.4-mini
   score: 90
   issues: internal-name:detectStoriesGlob,judge:inaccurate:0.95

package/rules/storybook/scaffold/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: plugins/lang-js/rules/storybook/scaffold/main.mjs
 docgen:
-  crc: c06a9e15
+  crc: 0505810e
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98

package/rules/storybook/scaffold/fix-scaffold.mjs

@@ -49,6 +49,17 @@ export function renderMocksGqlSse(templateDir = TEMPLATE_DIR) {
   return readFileSync(join(templateDir, 'mocks/gql-sse.js'), 'utf8')
 }
 
+/**
+ * Вміст канонічного `.storybook/empty-vite.config.js` — verbatim з template (порожній
+ * стенд-ін для `core.builder.options.viteConfigPath` у `main.js`, не залежить від пакета).
+ * Експортовано — переюз у `adopt/main.mjs`.
+ * @param {string} [templateDir] каталог template/ (за замовчуванням — цього concern-а)
+ * @returns {string} вміст `empty-vite.config.js`
+ */
+export function renderEmptyViteConfig(templateDir = TEMPLATE_DIR) {
+  return readFileSync(join(templateDir, 'empty-vite.config.js'), 'utf8')
+}
+
 /**
  * Записує файл, створюючи батьківські каталоги й реєструючи запис для rollback.
  * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').FixContext} ctx fix-контекст рунга
@@ -83,6 +94,7 @@ export const patterns = [
 
       const templateDir = join(ctx.concernDir, 'template')
       const mocksTemplate = renderMocksGqlSse(templateDir)
+      const emptyViteConfigTemplate = renderEmptyViteConfig(templateDir)
 
       const touchedFiles = []
       for (const v of targets) {
@@ -98,10 +110,48 @@ export const patterns = [
           writeScaffoldFile(ctx, mocksAbs, mocksTemplate)
           touchedFiles.push(mocksAbs)
         }
+
+        // empty-vite.config.js — main.js посилається на нього напряму (viteConfigPath),
+        // без нього щойно відтворений main.js неробочий; генерується разом (belt-and-suspenders
+        // з окремим 'storybook-scaffold-empty-vite-config' нижче, який покриває випадок, коли
+        // ЛИШЕ цей файл видалено, а main.js лишається канонічним).
+        const emptyViteConfigAbs = join(absPkgDir, '.storybook/empty-vite.config.js')
+        if (!existsSync(emptyViteConfigAbs)) {
+          writeScaffoldFile(ctx, emptyViteConfigAbs, emptyViteConfigTemplate)
+          touchedFiles.push(emptyViteConfigAbs)
+        }
       }
       return { touchedFiles, message: `.storybook/main.js: створено для ${targets.length} пакет(ів)` }
     }
   },
+  {
+    id: 'storybook-scaffold-empty-vite-config',
+    test: violations => violations.some(v => v.reason === 'missing-empty-vite-config'),
+    apply: (violations, ctx) => {
+      const targets = violations.filter(
+        v => v.reason === 'missing-empty-vite-config' && typeof v.data?.rootDir === 'string'
+      )
+      if (targets.length === 0 || !ctx.concernDir) return { touchedFiles: [] }
+
+      const emptyViteConfigTemplate = renderEmptyViteConfig(join(ctx.concernDir, 'template'))
+
+      const touchedFiles = []
+      for (const v of targets) {
+        const absPkgDir = resolvePkgDir(ctx.cwd, v.data.rootDir)
+        const abs = join(absPkgDir, '.storybook/empty-vite.config.js')
+        if (existsSync(abs)) continue
+        writeScaffoldFile(ctx, abs, emptyViteConfigTemplate)
+        touchedFiles.push(abs)
+      }
+      return {
+        touchedFiles,
+        message:
+          touchedFiles.length > 0
+            ? `.storybook/empty-vite.config.js: створено для ${touchedFiles.length} пакет(ів)`
+            : undefined
+      }
+    }
+  },
   {
     id: 'storybook-scaffold-preview-js',
     test: violations => violations.some(v => v.reason === 'missing-preview-js'),

package/rules/storybook/scaffold/main.mjs

@@ -1,5 +1,5 @@
 /** @see ./docs/main.md */
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
@@ -17,7 +17,20 @@ export const MAIN_JS_MARKERS = [
   { token: '@storybook/vue3-vite', hint: 'framework @storybook/vue3-vite' },
   { token: 'viteFinal', hint: 'viteFinal-override vite.config пакета' },
   { token: "'vite-plugin-pages'", hint: 'фільтр vite-plugin-pages у viteFinal' },
-  { token: "'vite-plugin-vue-layouts'", hint: 'фільтр vite-plugin-vue-layouts у viteFinal' }
+  { token: "'vite-plugin-vue-layouts'", hint: 'фільтр vite-plugin-vue-layouts у viteFinal' },
+  { token: "'vite-plugin-vue-layouts-next'", hint: 'фільтр vite-plugin-vue-layouts-next у viteFinal' },
+  {
+    token: 'isVueTransformFamily',
+    hint: 'сімейний фільтр vue-трансформерів (vite:vue/vue-macros) — стійкість до VueMacros-стека'
+  },
+  {
+    token: 'resolvePluginEntry',
+    hint: 'resolve/flatten Promise/масиву плагінів перед фільтрацією (VueMacros повертає Promise)'
+  },
+  {
+    token: 'viteConfigPath',
+    hint: 'core.builder.options.viteConfigPath на empty-vite.config.js (блокує builder-vite autodiscovery vite.config пакета — інакше подвійна SFC-трансформація на storybook build)'
+  }
 ]
 
 /** Маркери канону `.storybook/preview.js`. Експортовано — переюз у `adopt/main.mjs`. */
@@ -26,17 +39,50 @@ export const PREVIEW_JS_MARKERS = [
   { token: 'iconSet', hint: 'iconSet' },
   { token: 'iconMapFn', hint: 'iconMapFn (без нього внутрішні Quasar-іконки недоступні)' },
   { token: 'msw-storybook-addon', hint: 'msw-storybook-addon' },
-  { token: 'onUnhandledRequest', hint: 'onUnhandledRequest-фільтр' }
+  { token: 'onUnhandledRequest', hint: 'onUnhandledRequest-фільтр' },
+  { token: 'mswLoader', hint: 'mswLoader (не mswDecorator — deprecated у msw-storybook-addon 2.x)' }
+]
+
+/**
+ * Маркери канону `.storybook/empty-vite.config.js` (сусідній файл main.js — стенд-ін для
+ * `core.builder.options.viteConfigPath`, блокує autodiscovery `vite.config` пакета
+ * `@storybook/builder-vite`-ом). Експортовано — переюз у `adopt/main.mjs`.
+ */
+export const EMPTY_VITE_CONFIG_MARKERS = [
+  { token: 'defineConfig', hint: 'порожній defineConfig({}) — стенд-ін для viteConfigPath' }
 ]
 
 /**
- * Layout-детекція для stories-glob (ADR Кластер 2): `src/components/` присутній → glob
- * звужується до нього; пласка структура (`src/` без `components/`) — ширший glob по `src/`.
- * Шлях відносний до `.storybook/` (де лежить сам `main.js`), тому з префіксом `../`.
+ * Чи має корінь пакета плоскі `.vue`-файли (flat-root layout — `NDialog.vue`,
+ * `NDialog.stories.js` лежать прямо в КОРЕНІ пакета, `src/` майже порожній чи
+ * відсутній). Реальний кейс пілотного консюмера (components/npm) — component
+ * library без `src/components/`, детекція за самою наявністю `src/` дала б 0
+ * знайдених історій (тихий регрес adopt-діагностики). Перевірка нерекурсивна —
+ * дивиться лише файли безпосередньо в `absPkgDir`.
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @returns {boolean} true — у корені пакета є хоча б один `.vue`-файл
+ */
+function hasFlatRootVueFiles(absPkgDir) {
+  let entries
+  try {
+    entries = readdirSync(absPkgDir, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  return entries.some(e => e.isFile() && e.name.endsWith('.vue'))
+}
+
+/**
+ * Layout-детекція для stories-glob (ADR Кластер 2, розширено пілотом на flat-root):
+ * `.vue`-файли прямо в корені пакета (без `src/`) → flat-root glob по корені;
+ * інакше `src/components/` присутній → glob звужується до нього; інакше — ширший
+ * glob по всьому `src/`. Шлях відносний до `.storybook/` (де лежить сам `main.js`),
+ * тому з префіксом `../`.
  * @param {string} absPkgDir абсолютний шлях кореня пакета
  * @returns {string} glob для `stories` у `.storybook/main.js`
  */
 export function detectStoriesGlob(absPkgDir) {
+  if (hasFlatRootVueFiles(absPkgDir)) return '../*.stories.@(js|ts)'
   return existsSync(join(absPkgDir, 'src/components'))
     ? '../src/components/**/*.stories.@(js|ts)'
     : '../src/**/*.stories.@(js|ts)'
@@ -130,6 +176,22 @@ async function checkPackageScaffold({ rootDir, absDir, pkg }, reporter) {
     reporter
   )
 
+  // empty-vite.config.js — сусідній файл, на який main.js посилається через
+  // core.builder.options.viteConfigPath; без нього посилання в main.js "розбите" навіть
+  // якщо сам main.js канонічний (маркер viteConfigPath присутній), тому перевіряється
+  // окремо, а не лише як частина MAIN_JS_MARKERS.
+  await checkCanonFile(
+    absDir,
+    '.storybook/empty-vite.config.js',
+    EMPTY_VITE_CONFIG_MARKERS,
+    'missing-empty-vite-config',
+    'empty-vite-config-marker-missing',
+    label,
+    rootDir,
+    `${relPrefix}.storybook/empty-vite.config.js`,
+    reporter
+  )
+
   const scriptValue = pkg?.scripts?.storybook
   if (scriptValue !== STORYBOOK_SCRIPT) {
     const pkgJsonRel = `${relPrefix}package.json`

package/rules/storybook/scaffold/template/docs/empty-vite.config.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: empty-vite.config.js
+resource: plugins/lang-js/rules/storybook/scaffold/template/empty-vite.config.js
+docgen:
+  crc: 5c9f8904
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Канонічний порожній `Vite`-конфіг як стенд-ін для `core.builder.options.viteConfigPath` у `.storybook/main.js`. Його відсутність або поломка змушує `@storybook/builder-vite` через `loadConfigFromFile` знайти пакетний `vite.config.js` і додатково змішати нефільтровані плагіни ще до `viteFinal`; `mergeConfig` конкатенує масиви `plugins`, тож фільтр у `viteFinal` не прибирає вже доданий дублікат `@vitejs/plugin-vue`, а лише додає ще один. Без цього файлу `storybook build` падає на кожному `.vue` з `At least one <template> or <script> is required` через подвійну SFC-трансформацію; `dev --smoke-test` цього не виявляє, це підтверджує лише повний `build`. `npx @7n/rules fix storybook` відтворює цей файл, якщо він видалений або зламаний канон.
+
+## Поведінка
+
+1. Файл виступає канонічним порожнім `Vite`-конфігом для `storybook` і використовується як явна точка підключення в `core.builder.options.viteConfigPath`.
+2. Якщо канон пошкоджено або файл зник, `npx @7n/rules fix storybook` відтворює його, щоб зберегти узгоджений режим збірки.
+3. Файл не додає власної поведінки до `Vite`-збірки; його роль — заблокувати неявне підхоплення пакетного `vite.config.js` з боку `@storybook/builder-vite`.
+4. Це прибирає ризик домішування сторонніх `Vite`-плагінів у `storybook build`, які інакше можуть бути обʼєднані до `viteFinal` і спричинити подвійну обробку `Vue`-компонентів.
+5. Завдяки цьому `storybook build` поводиться стабільно на `.vue`-файлах у бібліотеках компонентів; без такого стенд-іну повний build може падати, тоді як `dev --smoke-test` цього не виявляє.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/storybook/scaffold/template/docs/index.md

@@ -4,7 +4,8 @@ title: plugins/lang-js/rules/storybook/scaffold/template
 resource: plugins/lang-js/rules/storybook/scaffold/template/
 ---
 
-| Файл                     | Тип       |
-| ------------------------ | --------- |
-| [main.js](main.md)       | JS Module |
-| [preview.js](preview.md) | JS Module |
+| Файл                                         | Тип       |
+| -------------------------------------------- | --------- |
+| [empty-vite.config.js](empty-vite.config.md) | JS Module |
+| [main.js](main.md)                           | JS Module |
+| [preview.js](preview.md)                     | JS Module |

package/rules/storybook/scaffold/template/docs/main.md

@@ -3,9 +3,8 @@ type: JS Module
 title: main.js
 resource: plugins/lang-js/rules/storybook/scaffold/template/main.js
 docgen:
-  crc: 5b21e6e2
+  crc: 18fbef4b
   model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
   score: 100
   issues: judge:inaccurate:0.96
   judgeModel: openai-codex/gpt-5.4-mini

package/rules/storybook/scaffold/template/docs/preview.md

@@ -3,9 +3,8 @@ type: JS Module
 title: preview.js
 resource: plugins/lang-js/rules/storybook/scaffold/template/preview.js
 docgen:
-  crc: 5590ef55
+  crc: 445c773b
   model: openai-codex/gpt-5.5
-  tier: cloud-avg
   score: 100
   issues: judge:inaccurate:0.96
   judgeModel: openai-codex/gpt-5.4-mini

package/rules/storybook/scaffold/template/empty-vite.config.js

@@ -0,0 +1,18 @@
+/**
+ * Канонічний ПОРОЖНІЙ Vite-конфіг — стенд-ін для `core.builder.options.viteConfigPath` у
+ * `.storybook/main.js` (storybook.mdc, ADR канон-storybook-для-vue-компонентних-бібліотек).
+ * `npx @7n/rules fix storybook` відтворює цей файл, якщо його видалено чи зламано канон.
+ *
+ * Навіщо: `@storybook/builder-vite` без явного `viteConfigPath` сам через
+ * `loadConfigFromFile` знаходить `vite.config.js` ПАКЕТА і домерджує його НЕФІЛЬТРОВАНІ
+ * плагіни (той самий `vue()`, обгорнутий VueMacros/unplugin-auto-import) ще ДО виклику
+ * `viteFinal` у `main.js` — `mergeConfig` конкатенує масиви `plugins`, тож фільтр у
+ * `viteFinal` лише ДОДАЄ ще один `@vitejs/plugin-vue`, а не прибирає вже змерджений
+ * дублікат від builder-vite. Наслідок без цього файлу: `storybook build` (саме `build`,
+ * не `dev`!) падає на кожному `.vue` з "At least one <template> or <script> is required" —
+ * подвійна SFC-трансформація. `dev --smoke-test` цю різницю НЕ ловить (лінива
+ * трансформація), лише повний `build`. Перевірено емпірично на пілотному консюмері.
+ */
+import { defineConfig } from 'vite'
+
+export default defineConfig({})

package/rules/storybook/scaffold/template/main.js

@@ -3,17 +3,69 @@
  * канон-storybook-для-vue-компонентних-бібліотек). Згенеровано правилом `storybook` —
  * `npx @7n/rules fix storybook` відтворює цей файл, якщо його видалено чи зламано канон.
  */
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
 import { loadConfigFromFile, mergeConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
 
+// Абсолютний каталог `.storybook/` (де лежить сам main.js) — потрібен нижче для
+// `core.builder.options.viteConfigPath` (порожній стенд-ін лежить поруч).
+const dirName = dirname(fileURLToPath(import.meta.url))
+
 // Плагіни власного Vite-збирача Storybook — порядок ФІКСОВАНИЙ: @vitejs/plugin-vue
 // ПЕРЕД quasar() (інакше Quasar-плагін не бачить SFC, уже скомпільований plugin-vue).
 const OWN_PLUGINS = [vue({ template: { transformAssetUrls } }), quasar({ sassVariables: true })]
 
 // Плагіни файлової маршрутизації додатка-споживача — не мають сенсу в ізольованому
-// рендері одного компонента, знімаються при обʼєднанні з vite.config пакета.
-const INCOMPATIBLE_PLUGIN_NAMES = new Set(['vite-plugin-pages', 'vite-plugin-vue-layouts'])
+// рендері одного компонента, знімаються при обʼєднанні з vite.config пакета. Обидві
+// версії layouts-пакета (старий і `-next`-форк) та pages-роутери — реальні консюмери
+// мігрують поступово, старий і новий пакет можуть співіснувати в різних vite.config.
+const INCOMPATIBLE_PLUGIN_NAMES = new Set([
+  'vite-plugin-pages',
+  'unplugin-vue-router',
+  'vite-plugin-vue-layouts',
+  'vite-plugin-vue-layouts-next'
+])
+
+/**
+ * Плагін належить до сімейства Vue SFC-трансформерів, які ДУБЛЮЮТЬ `OWN_PLUGINS`'
+ * `vue()`. Реальний стек консюмерів (components/npm/vite.config.js) обгортає
+ * `@vitejs/plugin-vue` через `VueMacros({ plugins: { vue: Vue() } })` — після
+ * резолву цей виклик повертає МАСИВ плагінів: сам `vite:vue` (той самий transform,
+ * що й `OWN_PLUGINS`' `vue()` — дублювання дає ПОДВІЙНУ SFC-трансформацію) плюс
+ * службові `vue-macros-*` (devtools/exclude-dep-optimize). Плагіни macro-синтаксису
+ * (`unplugin-vue-define-props`/`define-emit`/`reactivity-transform` тощо) — НЕ
+ * фільтруються: вони не дублюються `OWN_PLUGINS` і потрібні для macro-фіч пакета;
+ * Vite впорядковує їх через власний `enforce: 'pre'|'post'` незалежно від позиції
+ * в підсумковому масиві `plugins`, тож порядок відносно `OWN_PLUGINS` тут не важливий.
+ * @param {string | undefined} name ім'я плагіна
+ * @returns {boolean} true — плагін дублює `OWN_PLUGINS`' `vue()`
+ */
+function isVueTransformFamily(name) {
+  return typeof name === 'string' && (name.startsWith('vite:vue') || name.includes('vue-macros'))
+}
+
+/**
+ * Резолвить один запис `config.plugins` у плаский масив реальних плагінів. Vite
+ * офіційно підтримує `Plugin | Promise<Plugin> | (Plugin | Promise<Plugin>)[]`
+ * (довільна вкладеність) — `VueMacros(...)` сам повертає `Promise`, що резолвиться
+ * в масив плагінів. `loadConfigFromFile` читає файл конфіга як є й НЕ виконує це
+ * resolve/flatten (це робить лише повний `resolveConfig` пізніше у власному циклі
+ * Vite) — без ручного resolve/flatten тут фільтр порівнював би ім'я з
+ * `Promise`-об'єктом, що ще не резолвився (`undefined`), і пропускав би дублікат далі.
+ * @param {unknown} entry один елемент/Promise/масив із `config.plugins`
+ * @returns {Promise<object[]>} плаский масив плагінів після resolve
+ */
+async function resolvePluginEntry(entry) {
+  const resolved = await entry
+  if (Array.isArray(resolved)) {
+    const nested = await Promise.all(resolved.map(resolvePluginEntry))
+    return nested.flat(Infinity)
+  }
+  return resolved ? [resolved] : []
+}
 
 /** @type {import('@storybook/vue3-vite').StorybookConfig} */
 const config = {
@@ -24,15 +76,33 @@ const config = {
   },
   // Публічний asset для msw service worker, який ініціалізує preview.js.
   staticDirs: ['./public'],
+  core: {
+    builder: {
+      name: '@storybook/builder-vite',
+      // ОБОВ'ЯЗКОВИЙ обхід (емпірично підтверджено — лише через `storybook build`, dev
+      // smoke-test не ловить): без цього `@storybook/builder-vite` сам через
+      // `loadConfigFromFile` знаходить `../vite.config.js` пакета ще ДО виклику
+      // `viteFinal` нижче й домерджує його НЕФІЛЬТРОВАНІ плагіни (VueMacros-обгорнутий
+      // `vue()`, layout-роутинг тощо) у storybookConfig. `mergeConfig` конкатенує масиви
+      // `plugins`, тож фільтр у `viteFinal` лише ДОДАЄ ще один `@vitejs/plugin-vue`, а НЕ
+      // прибирає вже змерджений builder-vite дублікат — подвійна SFC-трансформація,
+      // `storybook build` падає на кожному `.vue` з "At least one <template> or <script>
+      // is required". `viteConfigPath` на порожній стенд-ін (`empty-vite.config.js`,
+      // канонічний сусідній файл цього скафолда) блокує це autodiscovery повністю.
+      options: { viteConfigPath: join(dirName, 'empty-vite.config.js') }
+    }
+  },
   async viteFinal(storybookConfig) {
     const loaded = await loadConfigFromFile({ command: 'serve', mode: 'development' }, undefined, process.cwd())
-    const userPlugins = (loaded?.config?.plugins ?? [])
-      .flat()
+    const rawPlugins = loaded?.config?.plugins ?? []
+    const resolvedNested = await Promise.all(rawPlugins.map(resolvePluginEntry))
+    const userPlugins = resolvedNested
+      .flat(Infinity)
       .filter(Boolean)
       .filter(p => !INCOMPATIBLE_PLUGIN_NAMES.has(p.name))
       // vue()/quasar() пакета замінюємо власними екземплярами у фіксованому порядку вище —
-      // не дублюємо; решта плагінів пакета (auto-import, svg-loader тощо) лишається.
-      .filter(p => p.name !== 'vite:vue' && p.name !== 'quasar')
+      // не дублюємо; решта плагінів пакета (auto-import, VueMacros macro-sugar тощо) лишається.
+      .filter(p => !isVueTransformFamily(p.name) && p.name !== 'quasar')
 
     return mergeConfig(storybookConfig, {
       resolve: loaded?.config?.resolve,