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

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,164 @@
+/** @see ./docs/main.md */
+import { existsSync } 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' }
+]
+
+/** Маркери канону `.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-фільтр' }
+]
+
+/**
+ * Layout-детекція для stories-glob (ADR Кластер 2): `src/components/` присутній → glob
+ * звужується до нього; пласка структура (`src/` без `components/`) — ширший glob по `src/`.
+ * Шлях відносний до `.storybook/` (де лежить сам `main.js`), тому з префіксом `../`.
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @returns {string} glob для `stories` у `.storybook/main.js`
+ */
+export function detectStoriesGlob(absPkgDir) {
+  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,30 @@
+---
+type: JS Module
+title: main.js
+resource: plugins/lang-js/rules/storybook/scaffold/template/main.js
+docgen:
+  crc: 5b21e6e2
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  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: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,46 @@
+---
+type: JS Module
+title: preview.js
+resource: plugins/lang-js/rules/storybook/scaffold/template/preview.js
+docgen:
+  crc: 5590ef55
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл задає канонічний preview для Vue-компонентних бібліотек відповідно до `storybook.mdc` та ADR `канон-storybook-для-vue-компонентних-бібліотек`. Він існує, щоб Storybook мав відтворювану базову конфігурацію для перегляду компонентів у бібліотеках.
+
+Файл згенеровано правилом `storybook`: команда `npx @7n/rules fix storybook` відтворює його, якщо файл видалено або зламано канон.
+
+Файл є read-only: не пише у ФС чи БД.
+
+## Поведінка
+
+1. Готує Storybook як канонічне середовище для Vue-компонентних бібліотек, щоб stories працювали наближено до реального застосунку-споживача.
+
+2. Підключає базові стилі Quasar, щоб компоненти відображалися з очікуваним виглядом у Storybook.
+
+3. Вмикає перехоплення мережевих запитів у Storybook, щоб компоненти могли працювати з контрольованими mock-відповідями.
+
+4. Ігнорує очікувані same-origin GET-запити dev-сервера, зокрема для HMR і статичних файлів, щоб вони не створювали зайвого шуму.
+
+5. Позначає інші мережеві запити, які не підпадають під тихий пропуск, попередженням, а не помилкою збірки, щоб дати м’який сигнал без блокування роботи Storybook.
+
+6. Встановлює Quasar у Storybook повністю, щоб бібліотечні компоненти мали доступ до глобальних Quasar-примітивів так само, як у реальному застосунку.
+
+7. Додає Quasar-плагіни для повідомлень і діалогів, щоб stories могли відтворювати сценарії з користувацькими сповіщеннями та модальними взаємодіями.
+
+8. Налаштовує набір іконок Quasar, щоб компоненти коректно показували матеріальні SVG-іконки поза повним Quasar CLI-середовищем.
+
+9. Передає Storybook декоратор для mock service worker, щоб мережеве оточення застосовувалося до stories централізовано.
+
+10. Налаштовує автоматичне розпізнавання controls-панелі Storybook для кольорів і дат, щоб інтерфейс керування props був зручнішим для перегляду компонентів.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,45 @@
+/**
+ * Канонічний конфіг Storybook для Vue-компонентних бібліотек (storybook.mdc, ADR
+ * канон-storybook-для-vue-компонентних-бібліотек). Згенеровано правилом `storybook` —
+ * `npx @7n/rules fix storybook` відтворює цей файл, якщо його видалено чи зламано канон.
+ */
+import { loadConfigFromFile, mergeConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
+
+// Плагіни власного 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'])
+
+/** @type {import('@storybook/vue3-vite').StorybookConfig} */
+const config = {
+  stories: ['__STORYBOOK_STORIES_GLOB__'],
+  framework: {
+    name: '@storybook/vue3-vite',
+    options: {}
+  },
+  // Публічний asset для msw service worker, який ініціалізує preview.js.
+  staticDirs: ['./public'],
+  async viteFinal(storybookConfig) {
+    const loaded = await loadConfigFromFile({ command: 'serve', mode: 'development' }, undefined, process.cwd())
+    const userPlugins = (loaded?.config?.plugins ?? [])
+      .flat()
+      .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')
+
+    return mergeConfig(storybookConfig, {
+      resolve: loaded?.config?.resolve,
+      css: loaded?.config?.css,
+      plugins: [...OWN_PLUGINS, ...userPlugins]
+    })
+  }
+}
+
+export default config

package/rules/storybook/scaffold/template/mocks/docs/gql-sse.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: gql-sse.js
+resource: plugins/lang-js/rules/storybook/scaffold/template/mocks/gql-sse.js
+docgen:
+  crc: fe63fba2
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Надає єдиний MSW-хелпер `sseSubscription` для мокання Apollo GraphQL-підписок у Storybook через `graphql-sse`. Кожна подія виконання підписки надсилається як окремий SSE `next`-запис у distinct-connection режимі: `event: next\ndata: <JSON>\n\n`, щоб пакети не дублювали формат цього wire-протоколу.
+
+## Поведінка
+
+1. `sseSubscription` приймає послідовність готових GraphQL execution-result повідомлень для однієї підписки.
+
+2. Для кожного повідомлення створює окрему SSE-подію типу `next`, сумісну з wire-протоколом `graphql-sse` у distinct-connection режимі.
+
+3. Повертає потік тіла відповіді, який MSW-хендлер може використати для мокання Apollo GraphQL-підписки у Storybook.
+
+4. Завершує потік після надсилання всіх повідомлень, щоб сценарій підписки мав детермінований кінець.
+
+5. Централізує формат тестових subscription-подій, щоб пакети не дублювали власну реалізацію цього протоколу.
+
+## Публічний API
+
+- sseSubscription — Формує SSE-стрім тіла відповіді для MSW-хендлера підписки graphql-sse.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: plugins/lang-js/rules/storybook/scaffold/template/mocks
+resource: plugins/lang-js/rules/storybook/scaffold/template/mocks/
+---
+
+| Файл                     | Тип       |
+| ------------------------ | --------- |
+| [gql-sse.js](gql-sse.md) | JS Module |

package/rules/storybook/scaffold/template/mocks/gql-sse.js

@@ -0,0 +1,25 @@
+/**
+ * Канонічний MSW-хелпер для мокання Apollo GraphQL-підписок через `graphql-sse` (storybook.mdc,
+ * ADR канон-storybook-для-vue-компонентних-бібліотек, Кластер 3). Wire-протокол
+ * `graphql-sse` у distinct-connection режимі — кожна подія виконання підписки надсилається
+ * як окремий SSE `next`-запис: `event: next\ndata: <JSON>\n\n`. Одне джерело істини для цього
+ * протоколу — не переносити копію логіки в кожен пакет окремо.
+ */
+
+/**
+ * Формує SSE-стрім тіла відповіді для MSW-хендлера підписки graphql-sse.
+ * @param {Array<object>} payloads послідовність GraphQL execution-result payload-ів — кожен
+ *   елемент те, що `graphql-sse` надіслав би як окрему `next`-подію одного виконання підписки
+ * @returns {ReadableStream<Uint8Array>} SSE body-стрім для MSW-response (`HttpResponse` body)
+ */
+export function sseSubscription(payloads) {
+  const encoder = new TextEncoder()
+  return new ReadableStream({
+    start(controller) {
+      for (const payload of payloads) {
+        controller.enqueue(encoder.encode(`event: next\ndata: ${JSON.stringify(payload)}\n\n`))
+      }
+      controller.close()
+    }
+  })
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Канонічний preview для Vue-компонентних бібліотек (storybook.mdc, ADR
+ * канон-storybook-для-vue-компонентних-бібліотек). Згенеровано правилом `storybook` —
+ * `npx @7n/rules fix storybook` відтворює цей файл, якщо його видалено чи зламано канон.
+ */
+import { setup } from '@storybook/vue3'
+import { Dialog, iconSet as quasarBuiltinIconSet, Notify, Quasar } from 'quasar'
+import iconSet from 'quasar/icon-set/svg-material-icons'
+import { initialize, mswDecorator } from 'msw-storybook-addon'
+
+import 'quasar/dist/quasar.css'
+
+// msw-storybook-addon: перехоплює мережеві запити компонентів у Storybook. Same-origin GET
+// (Vite HMR, статичні файли dev-сервера) — очікуваний шум, мовчки пропускаємо; усе інше —
+// warn (не білд-помилка навмисно, хвиля 1 — м'який сигнал, не гейт).
+initialize({
+  onUnhandledRequest(request, print) {
+    const url = new URL(request.url)
+    if (request.method === 'GET' && url.origin === globalThis.location?.origin) return
+    print.warning()
+  }
+})
+
+setup(app => {
+  // Повний install Quasar (не окремі компоненти) — бібліотека компонентів очікує
+  // глобально зареєстровані Quasar-примітиви (QBtn, QCard тощо) так само, як у реальному
+  // додатку-споживачі.
+  app.use(Quasar, {
+    plugins: { Notify, Dialog },
+    iconSet,
+    // iconMapFn — без нього внутрішні Quasar-компоненти (напр. стрілка QSelect) не
+    // резолвлять власні вбудовані іконки поза full Quasar CLI build.
+    iconMapFn(iconName) {
+      return quasarBuiltinIconSet.iconMapFn?.(iconName)
+    }
+  })
+})
+
+/** @type {import('@storybook/vue3').Preview} */
+const preview = {
+  decorators: [mswDecorator],
+  parameters: {
+    controls: { matchers: { color: /(background|color)$/iu, date: /Date$/u } }
+  }
+}
+
+export default preview

package/rules/storybook/scope/concern.json

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

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

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

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

@@ -0,0 +1,62 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/scope/main.mjs
+docgen:
+  crc: 04c71162
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 90
+  issues: internal-name:isVueComponentLibraryPkg,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл визначає, які workspace-пакети мають потрапити в скоуп Storybook: спирається на `.n-rules.json`, `.n-cursor.json` і `package.json`, враховує opt-out, поріг Vue-файлів, стандартний build та окремий прапорець для app-проєктів. Також він fail-safe перевіряє, що `storybook.optOut` не містить посилань на неіснуючі пакети.
+
+## Поведінка
+
+- `VUE_FILE_THRESHOLD` задає мінімальну кількість Vue-файлів, після якої пакет може потрапити в скоуп Storybook.
+- `readStorybookOptOut` читає з `.n-rules.json` або legacy `.n-cursor.json` перелік workspace-пакетів, які свідомо виключені зі скоупу Storybook; за відсутності або пошкодженості конфіга повертає порожній перелік.
+- `readDetectAppsFlag` читає з `.n-rules.json` або legacy `.n-cursor.json` явний прапорець включення app-проєктів у детекцію Storybook; за замовчуванням лишає їх поза скоупом.
+- `countVueFiles` рахує Vue-файли в дереві пакета з урахуванням шляхів, виключених конфігурацією і правилами ігнорування.
+- `hasStandardBuild` визначає, чи має пакет підтримуваний Vite build-конфіг у корені, потрібний для канонічного Storybook setup.
+- `isVueAppPkg` визначає, чи виглядає `package.json` як Vue app-проєкт, а не компонентна бібліотека.
+- `collectInScopeVuePackages` збирає workspace-пакети зі стандартним build, достатньою кількістю Vue-файлів і без `storybook.optOut`; app-проєкти додає лише після явного увімкнення відповідного прапорця.
+- `lint` перевіряє гігієну `storybook.optOut`: кожен запис має посилатися на наявний workspace-пакет, інакше звітує про застаріле налаштування.
+
+## Публічний API
+
+- VUE_FILE_THRESHOLD — Поріг кількості `.vue`-файлів для скоупу канону Storybook (ADR Кластер 1).
+- readStorybookOptOut — Читає `storybook.optOut` з `.n-rules.json` (fallback — legacy `.n-cursor.json`). Толерантно до
+відсутнього файлу/поля/невалідного JSON — повертає порожній масив (open-by-default, як
+`read-n-rules-config-lite.mjs`). Значення — root dir пакетів (`.` для кореня, `packages/ui` тощо),
+той самий формат, що повертає `getMonorepoPackageRootDirs`.
+- readDetectAppsFlag — Читає прапорець хвилі 2 `storybook.detectApps` з `.n-rules.json`. За замовчуванням `false` —
+детекція app-проєктів (`vue` у dependencies + `src/pages/`) лишається відкритим питанням ADR
+і не впливає на скоуп, доки консюмер-репо не увімкне прапорець явно.
+- countVueFiles — Рахує `.vue`-файли в дереві пакета (поважає `.gitignore` й `ignore` з `.n-rules.json` через
+`walkDir`/`ignorePaths` — той самий обхід, що й `vue/packages`).
+- hasStandardBuild — Чи має пакет "стандартний" build — розпізнаваний `vite.config.{js,ts,mjs}` у корені пакета.
+Канонічний `.storybook/main.js` спирається саме на цей файл (`viteFinal` мерджить його
+плагіни) — без нього автоматичний скафолд неможливий, і пакет пропускається мовчки
+(ADR Кластер 1: "skip пакетів із нестандартним build").
+- isVueAppPkg — Чи є пакет app-проєктом (не бібліотекою) для хвилі 2: `vue` у `dependencies` (не лише
+`peerDependencies`) і не бібліотека компонентів. Реалізовано зараз (щоб не переписувати
+модуль пізніше), але результат впливає на скоуп лише за прапорця `storybook.detectApps`.
+- collectInScopeVuePackages — Збирає workspace-пакети у скоупі канону Storybook хвилі 1: Vue-компонентна бібліотека
+(`vue` у `peerDependencies`, маркер `isVueComponentLibraryPkg` — той самий, що й `vue.mdc`)
+з не менше {@link VUE_FILE_THRESHOLD} `.vue`-файлами, без `storybook.optOut`, зі
+стандартним build (`vite.config.*`). Хвиля 2 (app-проєкти) додається лише за явного
+прапорця `storybook.detectApps` у `.n-rules.json`.
+- lint — Self-check конфігурації: `.n-rules.json` → `storybook.optOut` не має посилатись на
+неіснуючі workspace-пакети (застаріле налаштування — пакет перейменували/видалили, а
+opt-out лишився). Сама детекція скоупу (поріг, build, app-проєкти) — pure-функції вище,
+покриті тестами напряму; тут лише конфіг-гігієна.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.