@7n/rules-lang-js 0.9.0 → 0.11.0

package/rules/storybook/mocking/mocking.mdc

@@ -0,0 +1,132 @@
+## Мокання зовнішніх залежностей у Storybook
+
+Джерело рішень: `docs/adr/канон-storybook-для-vue-компонентних-бібліотек.md`, Кластер 3 і розділ «Розширення (2026-07-20): сторінки — route.params + Apollo subscription + Pinia» (прототип-верифікація на реальному кейсі `gt`). Це docs-only концерн — рецепти для агента, що впроваджує/підтримує Storybook у консюмер-репо; механічної перевірки немає (кожен пакет мокає свій набір залежностей по-своєму, детермінований чек дав би або хибні спрацювання, або нульове покриття).
+
+### Router
+
+Детекція: компонент використовує `useRoute`/`useRouter` (composition API з `vue-router`). Базовий рецепт — `createMemoryHistory()` з одним catch-all-маршрутом, без реальних params:
+
+```js
+import { createMemoryHistory, createRouter } from 'vue-router'
+
+const router = createRouter({
+  history: createMemoryHistory(),
+  routes: [{ path: '/:pathMatch(.*)*', component: { render: () => null } }]
+})
+```
+
+Для сторінок (хвиля 2, app-проєкти з `src/pages/`) — реальний параметризований маршрут замість catch-all, `router.push` перед mount і `await router.isReady()` у Storybook `loaders` (не в декораторі — `loaders` виконується per-story до рендеру, прибирає перший рендер без `route.params`):
+
+```js
+const router = createRouter({
+  history: createMemoryHistory(),
+  routes: [{ path: '/task/:id', component: TaskPage }]
+})
+
+export const pageLoader = ({ args }) => async () => {
+  await router.push(`/task/${args.taskId}`)
+  await router.isReady()
+  return { router }
+}
+```
+
+### `@nitra/tfm`
+
+No-op. `@nitra/tfm` (`tf`/`lang`/`getTr`) не потребує мокання — компонент рендериться з реальним модулем, переклади вже статичні дані в самому файлі (`vue/tfm-translations.mdc`). Задокументуй це явно в story-файлі коментарем (`// @nitra/tfm — no-op, реальний модуль`), щоб наступний агент не витрачав час на пошук неіснуючого моку.
+
+### Apollo/GraphQL — виключно MSW
+
+**Рішення ADR-розширення:** мокання GraphQL (query/mutation/subscription) — тільки на мережевому рівні через `msw-storybook-addon`, **без** `resolve.alias`-підмін app-коду (`boot/apollo.js` чи еквівалент лишається повністю справжнім). Facilitator у сесії розширення рекомендував лінк-рівневий alias-мок (справжні хуки `@vue3-apollo/core` + фейковий termination `ApolloLink`), а після вибору MSW — гібрид MSW+alias для side-effect boot-модулів; обрано чистий MSW, бо app-код (включно з link-split http/sse) не розходиться з production-поведінкою, а мок-хендлери переносні в майбутні vitest/playwright.
+
+Query/mutation — стандартний `graphql.query`/`graphql.mutation` handler, сценарії через `parameters.msw`:
+
+```js
+import { graphql, HttpResponse } from 'msw'
+
+export const Default = {
+  parameters: {
+    msw: {
+      handlers: [graphql.query('GetTask', () => HttpResponse.json({ data: { task: taskFixture } }))]
+    }
+  }
+}
+```
+
+Підписки — `msw-storybook-addon` не має готового `graphql.subscription()`-хендлера; wire-протокол `graphql-sse` (`event: next\ndata: …`, distinct-connection mode) мокається вручну через канонічний хелпер `sseSubscription` з `.storybook/mocks/gql-sse.js` (генерується скафолдом, `scaffold/template/mocks/gql-sse.js` — не копіювати логіку в кожен пакет, одне джерело істини для протоколу):
+
+```js
+import { http, HttpResponse } from 'msw'
+import { sseSubscription } from '../../.storybook/mocks/gql-sse.js'
+
+export const Realtime = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.post('/graphql/stream', () =>
+          new HttpResponse(sseSubscription([{ data: { taskUpdated: frame1 } }, { data: { taskUpdated: frame2 } }]), {
+            headers: { 'Content-Type': 'text/event-stream' }
+          })
+        )
+      ]
+    }
+  }
+}
+```
+
+### Точковий 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`, не хардкод у декораторі:
+
+```js
+import { createPinia } from 'pinia'
+
+export function pageDecorator({ route, pinia } = {}) {
+  return (story, ctx) => {
+    const app = createPinia()
+    if (ctx.parameters.pinia?.initialState) {
+      for (const [id, state] of Object.entries(ctx.parameters.pinia.initialState)) {
+        app.state.value[id] = state
+      }
+    }
+    // ...install router/pinia у app instance, повернути wrapped story
+  }
+}
+```
+
+**Не** `@pinia/testing` (`createTestingPinia`) — вона за замовчуванням підміняє actions заглушками, а сторінка в Storybook має жити зі справжньою бізнес-логікою стору, не з заглушкою.
+
+### Патерн story для сторінки
+
+- Одна фабрика-декоратор `pageDecorator({ route, pinia })` на весь повторюваний код (router + pinia + Quasar layout) — не дублювати в кожному story-файлі.
+- **`QLayout`/`QPageContainer`-wrapper обов'язковий**: `q-page` кидає виняток без layout-предка. Quasar SFC-transform (auto-реєстрація компонентів через build-time трансформ) **не працює** в runtime-шаблонах декораторів — `QLayout`/`QPageContainer`/`QPage` реєструються явно (`app.component('QLayout', QLayout)` тощо), інакше рендер падає з незрозумілою помилкою про невідомий тег.
+- Фікстури — окремим модулем `.storybook/fixtures/<page>.js`, не inline в story-файлі (переюз між `Default`/`Loading`/`Error`/`Realtime`).
+- **Smoke-мінімум**: одна story «рендериться без помилок» на кожну сторінку — обов'язковий нижній рівень покриття, навіть без окремих stories для кожного стану.
+- Окремі stories для `Loading`/`Error`/`Realtime` (сценарій з кількома SSE-кадрами через `sseSubscription`) — де застосовно, поверх smoke-мінімуму.
+
+### Мережеві side-effect компоненти без моку
+
+Компонент робить мережеві виклики (analytics-трекер, session-boot тощо), для яких мокання поки не покрите канонічним рецептом — постав у story коментар-маркер `// n-storybook: лише display-стан, мережеві side-effects без моку`, щоб було видно свідоме рішення, а не забутий пропуск.

package/rules/storybook/scaffold/concern.json

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

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: fix-scaffold.mjs
+resource: plugins/lang-js/rules/storybook/scaffold/fix-scaffold.mjs
+docgen:
+  crc: 31a867f5
+  model: openai-codex/gpt-5.4-mini
+  score: 90
+  issues: internal-name:detectStoriesGlob,judge:inaccurate:0.95
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл відновлює канонічні Storybook-артефакти для concern-а `storybook/scaffold`: створює відсутні `.storybook/main.js`, `.storybook/preview.js`, `.storybook/mocks/gql-sse.js` і синхронізує `package.json#scripts.storybook` за шаблоном concern-а. `main.js` відновлюється з однією заміною для конкретного пакета — stories-glob за layout-детекцією (`detectStoriesGlob`, `main.mjs`); `preview.js` і `.storybook/mocks/gql-sse.js` відновлюються як verbatim-копії, однакові для всіх пакетів. Це потрібно, щоб привести пакет до канонічного Storybook-стану concern-а. Код працює fail-safe і не кидає винятків назовні; конфіги, на які спирається код: package.json
+
+## Поведінка
+
+1. `patterns` запускає два окремі відновлювальні сценарії для Storybook: один для відсутніх `.storybook/main.js` і `.storybook/preview.js`, інший — для відсутнього `scripts.storybook` у `package.json`.
+2. Для кожного пакета з проблемою `missing-main-js` створює `.storybook/main.js` за шаблоном concern-а, підставляючи пакетний stories glob відповідно до layout-перевірки.
+3. Для того ж пакета за потреби створює `.storybook/mocks/gql-sse.js` як канонічну копію з шаблону; якщо файл уже є, не перезаписує його.
+4. Для кожного пакета з проблемою `missing-preview-js` створює `.storybook/preview.js` як канонічну копію з шаблону concern-а.
+5. Для кожного `package.json` з проблемою `missing-storybook-script` додає або оновлює `scripts.storybook` до канонічного значення; якщо JSON не читається, запис пропускається без падіння.
+6. Усі зміни застосовуються лише там, де доступний корінь concern-а або шлях до файлу, тож autofix працює fail-safe і не зупиняє весь прогін через одну некоректну ціль.
+7. Орієнтується на `package.json` як на конфігураційне джерело для скрипта Storybook.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -0,0 +1,10 @@
+---
+type: Directory Index
+title: plugins/lang-js/rules/storybook/scaffold
+resource: plugins/lang-js/rules/storybook/scaffold/
+---
+
+| Файл                                | Тип       |
+| ----------------------------------- | --------- |
+| [fix-scaffold.mjs](fix-scaffold.md) | JS Module |
+| [main.mjs](main.md)                 | JS Module |

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

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/scaffold/main.mjs
+docgen:
+  crc: 2cad0405
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл підтримує Storybook-скафолд для Vue-пакетів і орієнтується на `package.json`, щоб узгодити сценарій запуску з проєктним конфігом. Експортована константа-рядок `STORYBOOK_SCRIPT="storybook dev -p 6006 --no-open"` задає стандартний Storybook-запуск без відкриття браузера. `detectStoriesGlob` визначає межі пошуку stories для пакета. `lint` перевіряє наявність очікуваних файлів і канонічних маркерів та підказує `npx @7n/rules fix storybook` у разі проблем.
+
+## Поведінка
+
+- STORYBOOK_SCRIPT — канонічне значення `package.json#scripts.storybook`: `storybook dev -p 6006 --no-open`.
+- detectStoriesGlob — визначає glob для Storybook stories залежно від структури пакета: для `src/components/` звужує пошук до цієї теки, інакше бере ширший glob по `src/`; шлях формується відносно `.storybook/`.
+- lint — перевіряє для всіх Vue-пакетів у скоупі канонічний Storybook-скафолд: `.storybook/main.js`, `.storybook/preview.js` і `package.json#scripts.storybook`; якщо файлу або потрібних маркерів бракує, повідомляє порушення з підказкою на `npx @7n/rules fix storybook`.
+
+Changelog: pending
+
+## Публічний API
+
+- STORYBOOK_SCRIPT — Канонічне значення `package.json#scripts.storybook` (storybook.mdc).
+- detectStoriesGlob — Layout-детекція для stories-glob (ADR Кластер 2): `src/components/` присутній → glob
+звужується до нього; пласка структура (`src/` без `components/`) — ширший glob по `src/`.
+Шлях відносний до `.storybook/` (де лежить сам `main.js`), тому з префіксом `../`.
+- lint — Перевіряє канонічний Storybook-скафолд (`.storybook/main.js`, `.storybook/preview.js`,
+`package.json#scripts.storybook`) для всіх пакетів у скоупі (`scope/main.mjs`).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,150 @@
+/**
+ * T0-autofix для concern-а `storybook/scaffold`: відтворює канонічні `.storybook/main.js`,
+ * `.storybook/preview.js`, `.storybook/mocks/gql-sse.js` і `package.json#scripts.storybook`
+ * з `template/` цього concern-а. `main.js` має одну заміну на пакет — stories-glob за
+ * layout-детекцією (`detectStoriesGlob`, `main.mjs`); `preview.js`/`mocks/gql-sse.js` —
+ * verbatim-копія (Quasar/msw-налаштування не залежать від конкретного пакета).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { detectStoriesGlob, STORYBOOK_SCRIPT } from './main.mjs'
+
+const STORIES_GLOB_TOKEN = '__STORYBOOK_STORIES_GLOB__'
+
+/** Каталог `template/` цього concern-а. Експортовано — переюз у `adopt/main.mjs`. */
+export const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'template')
+
+/**
+ * Рендерить канонічний `.storybook/main.js` для конкретного пакета (єдина заміна —
+ * stories-glob за layout-детекцією). Експортовано — той самий рендер переюзає
+ * `adopt/main.mjs` для генерації повністю відсутнього файлу (не дублювати шаблонування).
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @param {string} [templateDir] каталог template/ (за замовчуванням — цього concern-а)
+ * @returns {string} готовий вміст `main.js`
+ */
+export function renderMainJs(absPkgDir, templateDir = TEMPLATE_DIR) {
+  const mainTemplate = readFileSync(join(templateDir, 'main.js'), 'utf8')
+  return mainTemplate.split(STORIES_GLOB_TOKEN).join(detectStoriesGlob(absPkgDir))
+}
+
+/**
+ * Вміст канонічного `.storybook/preview.js` — verbatim з template (не залежить від пакета).
+ * Експортовано — переюз у `adopt/main.mjs`.
+ * @param {string} [templateDir] каталог template/ (за замовчуванням — цього concern-а)
+ * @returns {string} вміст `preview.js`
+ */
+export function renderPreviewJs(templateDir = TEMPLATE_DIR) {
+  return readFileSync(join(templateDir, 'preview.js'), 'utf8')
+}
+
+/**
+ * Вміст канонічного `.storybook/mocks/gql-sse.js` — verbatim з template. Експортовано —
+ * переюз у `adopt/main.mjs`.
+ * @param {string} [templateDir] каталог template/ (за замовчуванням — цього concern-а)
+ * @returns {string} вміст `mocks/gql-sse.js`
+ */
+export function renderMocksGqlSse(templateDir = TEMPLATE_DIR) {
+  return readFileSync(join(templateDir, 'mocks/gql-sse.js'), 'utf8')
+}
+
+/**
+ * Записує файл, створюючи батьківські каталоги й реєструючи запис для rollback.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').FixContext} ctx fix-контекст рунга
+ * @param {string} absPath абсолютний шлях цільового файлу
+ * @param {string} content вміст файлу
+ * @returns {void}
+ */
+function writeScaffoldFile(ctx, absPath, content) {
+  mkdirSync(dirname(absPath), { recursive: true })
+  ctx.recordWrite?.(absPath)
+  writeFileSync(absPath, content, 'utf8')
+}
+
+/**
+ * Резолвить абсолютний корінь пакета з `rootDir` violation.data (`.` — корінь репозиторію).
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @param {string} rootDir posix-relative корінь пакета
+ * @returns {string} абсолютний шлях кореня пакета
+ */
+function resolvePkgDir(cwd, rootDir) {
+  return rootDir === '.' ? cwd : join(cwd, rootDir)
+}
+
+/** @type {import('@7n/rules/scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'storybook-scaffold-main-js',
+    test: violations => violations.some(v => v.reason === 'missing-main-js'),
+    apply: (violations, ctx) => {
+      const targets = violations.filter(v => v.reason === 'missing-main-js' && typeof v.data?.rootDir === 'string')
+      if (targets.length === 0 || !ctx.concernDir) return { touchedFiles: [] }
+
+      const templateDir = join(ctx.concernDir, 'template')
+      const mocksTemplate = renderMocksGqlSse(templateDir)
+
+      const touchedFiles = []
+      for (const v of targets) {
+        const absPkgDir = resolvePkgDir(ctx.cwd, v.data.rootDir)
+        const rendered = renderMainJs(absPkgDir, templateDir)
+
+        const mainAbs = join(absPkgDir, '.storybook/main.js')
+        writeScaffoldFile(ctx, mainAbs, rendered)
+        touchedFiles.push(mainAbs)
+
+        const mocksAbs = join(absPkgDir, '.storybook/mocks/gql-sse.js')
+        if (!existsSync(mocksAbs)) {
+          writeScaffoldFile(ctx, mocksAbs, mocksTemplate)
+          touchedFiles.push(mocksAbs)
+        }
+      }
+      return { touchedFiles, message: `.storybook/main.js: створено для ${targets.length} пакет(ів)` }
+    }
+  },
+  {
+    id: 'storybook-scaffold-preview-js',
+    test: violations => violations.some(v => v.reason === 'missing-preview-js'),
+    apply: (violations, ctx) => {
+      const targets = violations.filter(v => v.reason === 'missing-preview-js' && typeof v.data?.rootDir === 'string')
+      if (targets.length === 0 || !ctx.concernDir) return { touchedFiles: [] }
+
+      const previewTemplate = renderPreviewJs(join(ctx.concernDir, 'template'))
+
+      const touchedFiles = []
+      for (const v of targets) {
+        const absPkgDir = resolvePkgDir(ctx.cwd, v.data.rootDir)
+        const previewAbs = join(absPkgDir, '.storybook/preview.js')
+        writeScaffoldFile(ctx, previewAbs, previewTemplate)
+        touchedFiles.push(previewAbs)
+      }
+      return { touchedFiles, message: `.storybook/preview.js: створено для ${targets.length} пакет(ів)` }
+    }
+  },
+  {
+    id: 'storybook-scaffold-package-script',
+    test: violations => violations.some(v => v.reason === 'missing-storybook-script'),
+    apply: (violations, ctx) => {
+      const targets = violations.filter(v => v.reason === 'missing-storybook-script' && v.file)
+      const touchedFiles = []
+      for (const v of targets) {
+        const abs = join(ctx.cwd, v.file)
+        let pkg
+        try {
+          pkg = JSON.parse(readFileSync(abs, 'utf8'))
+        } catch {
+          continue
+        }
+        pkg.scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {}
+        if (pkg.scripts.storybook === STORYBOOK_SCRIPT) continue
+        pkg.scripts.storybook = STORYBOOK_SCRIPT
+        ctx.recordWrite?.(abs)
+        writeFileSync(abs, `${JSON.stringify(pkg, null, 2)}\n`)
+        touchedFiles.push(abs)
+      }
+      return touchedFiles.length > 0
+        ? { touchedFiles, message: `scripts.storybook: встановлено у ${touchedFiles.length} package.json` }
+        : { touchedFiles: [] }
+    }
+  }
+]

package/rules/storybook/scaffold/main.mjs

@@ -0,0 +1,196 @@
+/** @see ./docs/main.md */
+import { existsSync, readdirSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { collectInScopeVuePackages } from '../scope/main.mjs'
+
+/** Канонічне значення `package.json#scripts.storybook` (storybook.mdc). */
+export const STORYBOOK_SCRIPT = 'storybook dev -p 6006 --no-open'
+
+/**
+ * Маркери канону `.storybook/main.js`, перевірені текстовим пошуком (без AST — рядки стабільні).
+ * Експортовано — той самий список переюзає `adopt/main.mjs` для diff-діагностики (не дублювати).
+ */
+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-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)'
+  }
+]
+
+/** Маркери канону `.storybook/preview.js`. Експортовано — переюз у `adopt/main.mjs`. */
+export const PREVIEW_JS_MARKERS = [
+  { token: 'Quasar', hint: 'повний install Quasar' },
+  { token: 'iconSet', hint: 'iconSet' },
+  { token: 'iconMapFn', hint: 'iconMapFn (без нього внутрішні Quasar-іконки недоступні)' },
+  { token: 'msw-storybook-addon', hint: 'msw-storybook-addon' },
+  { token: 'onUnhandledRequest', hint: 'onUnhandledRequest-фільтр' }
+]
+
+/**
+ * Чи має корінь пакета плоскі `.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)'
+}
+
+/**
+ * @param {string} content вміст файлу
+ * @param {{ token: string, hint: string }[]} markers очікувані канонічні маркери
+ * @returns {{ token: string, hint: string }[]} маркери, яких бракує
+ */
+export function missingMarkers(content, markers) {
+  return markers.filter(m => !content.includes(m.token))
+}
+
+/**
+ * Перевіряє один канонічний файл скафолду (`.storybook/main.js` або `.storybook/preview.js`):
+ * відсутність → `missingReason`-порушення з посиланням на `npx \@7n/rules fix storybook`;
+ * присутність без якогось канонічного маркера → `markerReason`-порушення на маркер.
+ * @param {string} absDir абсолютний корінь пакета
+ * @param {string} relFile posix-relative шлях файлу від кореня пакета (`.storybook/main.js`)
+ * @param {{ token: string, hint: string }[]} markers канонічні маркери файлу
+ * @param {string} missingReason reason для порушення "файл відсутній"
+ * @param {string} markerReason reason для порушення "маркер відсутній"
+ * @param {string} label людський підпис пакета для повідомлень
+ * @param {string} rootDir root dir пакета (для violation.data)
+ * @param {string} fileRel posix-relative шлях файлу від кореня репозиторію (для violation.file)
+ * @param {ReturnType<typeof createViolationReporter>} reporter reporter поточного лінту
+ * @returns {Promise<void>}
+ */
+async function checkCanonFile(
+  absDir,
+  relFile,
+  markers,
+  missingReason,
+  markerReason,
+  label,
+  rootDir,
+  fileRel,
+  reporter
+) {
+  const abs = join(absDir, relFile)
+  if (existsSync(abs)) {
+    const content = await readFile(abs, 'utf8')
+    for (const m of missingMarkers(content, markers)) {
+      reporter.fail(`[${label}] ${relFile} не відповідає канону — бракує: ${m.hint} (storybook.mdc)`, {
+        reason: markerReason,
+        file: fileRel
+      })
+    }
+    return
+  }
+  reporter.fail(`[${label}] відсутній ${relFile} — канонічний скафолд: npx @7n/rules fix storybook (storybook.mdc)`, {
+    reason: missingReason,
+    file: fileRel,
+    data: { rootDir }
+  })
+}
+
+/**
+ * Перевіряє один в-скоупі пакет: `.storybook/main.js`, `.storybook/preview.js`,
+ * `package.json#scripts.storybook`.
+ * @param {import('../scope/main.mjs').InScopePackage} pkgEntry пакет у скоупі
+ * @param {ReturnType<typeof createViolationReporter>} reporter reporter поточного лінту
+ * @returns {Promise<void>}
+ */
+async function checkPackageScaffold({ rootDir, absDir, pkg }, reporter) {
+  const label = rootDir === '.' ? 'корінь' : rootDir
+  const relPrefix = rootDir === '.' ? '' : `${rootDir}/`
+
+  await checkCanonFile(
+    absDir,
+    '.storybook/main.js',
+    MAIN_JS_MARKERS,
+    'missing-main-js',
+    'main-js-marker-missing',
+    label,
+    rootDir,
+    `${relPrefix}.storybook/main.js`,
+    reporter
+  )
+
+  await checkCanonFile(
+    absDir,
+    '.storybook/preview.js',
+    PREVIEW_JS_MARKERS,
+    'missing-preview-js',
+    'preview-js-marker-missing',
+    label,
+    rootDir,
+    `${relPrefix}.storybook/preview.js`,
+    reporter
+  )
+
+  const scriptValue = pkg?.scripts?.storybook
+  if (scriptValue !== STORYBOOK_SCRIPT) {
+    const pkgJsonRel = `${relPrefix}package.json`
+    const current = scriptValue ? `'${scriptValue}'` : 'відсутній'
+    reporter.fail(
+      `[${label}] package.json#scripts.storybook має бути '${STORYBOOK_SCRIPT}' (зараз: ${current}) — storybook.mdc`,
+      { reason: 'missing-storybook-script', file: pkgJsonRel, data: { rootDir } }
+    )
+  }
+}
+
+/**
+ * Перевіряє канонічний Storybook-скафолд (`.storybook/main.js`, `.storybook/preview.js`,
+ * `package.json#scripts.storybook`) для всіх пакетів у скоупі (`scope/main.mjs`).
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат лінту
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const pkgs = await collectInScopeVuePackages(ctx.cwd)
+
+  if (pkgs.length === 0) {
+    reporter.pass('storybook: немає Vue component library пакетів у скоупі (storybook.mdc)')
+    return reporter.result()
+  }
+
+  for (const entry of pkgs) {
+    await checkPackageScaffold(entry, reporter)
+  }
+
+  return reporter.result()
+}

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

@@ -0,0 +1,10 @@
+---
+type: Directory Index
+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 |

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.js
+resource: plugins/lang-js/rules/storybook/scaffold/template/main.js
+docgen:
+  crc: 74cf3397
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл задає канонічний Storybook-конфіг для Vue-компонентних бібліотек, які дотримуються правила `storybook` і ADR `канон-storybook-для-vue-компонентних-бібліотек`, щоб спільний формат прев’ю був відтворюваним у всіх таких пакетах. Він фіксує налаштування, потрібні для Storybook-перегляду Vue-компонентів, і зберігає лише ті ресурси та плагіни, без яких прев’ю не працює як очікується.
+
+## Поведінка
+
+1. Формує канонічний Storybook-конфіг для Vue-компонентної бібліотеки, щоб ізольований перегляд компонентів працював однаково в усіх пакетах, які дотримуються цього правила.
+2. Підтягує базові налаштування застосунку-споживача й зливає їх із Storybook-налаштуваннями, щоб зберегти спільні параметри рендерингу, шляхів і CSS.
+3. Вилучає плагіни, які залежать від повної маршрутизації або layout-інфраструктури застосунку, бо в Storybook вони не дають користі для одного компонента.
+4. Замінює Vue- і Quasar-інтеграцію на власні екземпляри у фіксованому порядку, щоб шаблони компонентів і Quasar-стилі оброблялися передбачувано.
+5. Залишає інші корисні плагіни пакета, щоб у Storybook зберігалися допоміжні можливості на кшталт auto-import чи SVG-підтримки.
+6. Підключає публічні assets із теки `public`, щоб preview міг ініціалізувати service worker для `msw`.
+7. Якщо канонічний файл пошкоджено або видалено, відтворюється правилом `storybook` через `npx @7n/rules fix storybook`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).