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

package/rules/storybook/hygiene/main.mjs

@@ -0,0 +1,254 @@
+/** @see ./docs/main.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import { parseSync } from 'oxc-parser'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '@7n/rules/scripts/lib/load-cursor-config.mjs'
+import { walkDir } from '@7n/rules/scripts/utils/walkDir.mjs'
+import {
+  dynamicImportModule,
+  langFromPath,
+  requireCallModule,
+  walkAstWithAncestors
+} from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+import { contentForVueImportScan } from '@7n/rules/scripts/lib/js-source-signals.mjs'
+import { isNodeBuiltinSpecifier } from '../../vue/lib/vue-forbidden-imports.mjs'
+import { collectInScopeVuePackages } from '../scope/main.mjs'
+
+const VUE_EXT_RE = /\.vue$/u
+
+// Quasar CLI-конвенція за замовчуванням (quasar.dev/style/sass-scss-variables): плагін шукає
+// саме цей файл, якщо `sassVariables` не задає власний шлях — .scss першим, .sass fallback-ом.
+const SASS_VARIABLES_CANDIDATES = ['src/css/quasar.variables.scss', 'src/css/quasar.variables.sass']
+
+// quasar({ sassVariables: true }) або quasar({ sassVariables: 'шлях' }) — обидві форми вмикають
+// підключення SCSS-змінних; boolean false/відсутність поля — ні.
+const SASS_VARIABLES_MARKER_RE = /sassVariables\s*:\s*(?:true|['"])/u
+
+/**
+ * Віртуальний шлях для oxc-парсера: `.vue` розбирається як `.ts` (після витягу `<script>`-блоку),
+ * решта — за власним розширенням.
+ * @param {string} relPath шлях файлу (posix, відносно пакета)
+ * @returns {string} шлях для вибору `lang` парсером
+ */
+function virtualPathForParse(relPath) {
+  return relPath.endsWith('.vue') ? relPath.replace(VUE_EXT_RE, '.ts') : relPath
+}
+
+/**
+ * Витягає import-specifier'и з `.vue` SFC (лише `<script>`-блоки) чи звичайного JS/TS-файлу:
+ * static import + dynamic `import()` + `require()`. Той самий oxc-parser pipeline, що й
+ * `js/dep-policy` і `vue/lib/vue-forbidden-imports.mjs` — лише для довільного specifier-а,
+ * не для конкретного заборонного списку.
+ * @param {string} content сирий вміст файлу
+ * @param {string} relPath шлях файлу (для вибору мови/віртуального шляху парсера)
+ * @returns {string[]} список import-specifier'ів (можуть повторюватись)
+ */
+function extractImportSpecifiers(content, relPath) {
+  const scan = contentForVueImportScan(content, relPath)
+  const virtualPath = virtualPathForParse(relPath)
+  let parsed
+  try {
+    parsed = parseSync(virtualPath, scan, { lang: langFromPath(virtualPath), sourceType: 'module' })
+  } catch {
+    return []
+  }
+  if (parsed.errors?.length) return []
+
+  const out = []
+  for (const imp of parsed.module?.staticImports ?? []) {
+    if (typeof imp?.moduleRequest?.value === 'string') out.push(imp.moduleRequest.value)
+  }
+  const program = parsed.program
+  if (program && typeof program === 'object') {
+    walkAstWithAncestors(program, [], node => {
+      const dyn = dynamicImportModule(node)
+      if (dyn !== null) out.push(dyn)
+      const req = requireCallModule(node)
+      if (req !== null) out.push(req)
+    })
+  }
+  return out
+}
+
+/**
+ * Чи є specifier відносним імпортом чи псевдонімом шляху (не сторонній пакет): `./x`, `../x`,
+ * абсолютний шлях, чи типові Vite-аліаси `@/...`/`~/...` на `src/`. Автоімпорт-глобали
+ * (`ref`, `computed`, Quasar-композаблі через `unplugin-auto-import`) сюди не потрапляють —
+ * вони не є import-специфікаторами взагалі, AST їх не бачить.
+ * @param {string} spec значення `moduleRequest.value`
+ * @returns {boolean} `true`, якщо це не сторонній пакет
+ */
+function isRelativeOrAliasSpecifier(spec) {
+  return spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('~/') || spec.startsWith('@/')
+}
+
+/**
+ * Ім'я пакета верхнього рівня зі specifier-а: враховує scoped-пакети (`@scope/name`) і
+ * subpath-імпорти (`pkg/sub/path` → `pkg`, `@scope/name/sub` → `@scope/name`).
+ * @param {string} spec сторонній import-specifier
+ * @returns {string} ім'я пакета для звірки з package.json deps
+ */
+function topLevelPackageName(spec) {
+  if (spec.startsWith('@')) {
+    const parts = spec.split('/')
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : spec
+  }
+  const idx = spec.indexOf('/')
+  return idx === -1 ? spec : spec.slice(0, idx)
+}
+
+/**
+ * Множина задекларованих пакетів (`dependencies` + `peerDependencies`) — workspace-пакети
+ * (`@nitra/*`, `@7n/*`) не потребують окремої обробки: вони так само оголошуються тут
+ * (workspace-протокол), як і звичайні npm-залежності.
+ * @param {Record<string, unknown>} pkg розпарсений package.json пакета
+ * @returns {Set<string>} імена задекларованих пакетів
+ */
+function collectDeclaredDeps(pkg) {
+  const names = new Set()
+  for (const field of ['dependencies', 'peerDependencies']) {
+    const obj = pkg?.[field]
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+      for (const name of Object.keys(obj)) names.add(name)
+    }
+  }
+  return names
+}
+
+/**
+ * Збирає абсолютні шляхи всіх `.vue`-файлів у дереві пакета.
+ * @param {string} absDir абсолютний шлях кореня пакета
+ * @param {string[]} ignorePaths абсолютні шляхи, повністю виключені з обходу
+ * @returns {Promise<string[]>} відсортовані абсолютні шляхи `.vue`-файлів
+ */
+async function collectVueFiles(absDir, ignorePaths) {
+  const files = []
+  await walkDir(
+    absDir,
+    p => {
+      if (p.endsWith('.vue')) files.push(p)
+    },
+    ignorePaths
+  )
+  return files
+}
+
+/**
+ * Будує posix-relative шлях від `cwd` для violation.file — `entry.rootDir` уже relative до `cwd`
+ * (`.` для кореня монорепо), `relFromPkg` — relative до `entry.absDir`.
+ * @param {import('../scope/main.mjs').InScopePackage} entry пакет у скоупі
+ * @param {string} relFromPkg posix-relative шлях від кореня пакета
+ * @returns {string} posix-relative шлях від `cwd`
+ */
+function fileRelFromCwd(entry, relFromPkg) {
+  return entry.rootDir === '.' ? relFromPkg : `${entry.rootDir}/${relFromPkg}`
+}
+
+/**
+ * Перевіряє один пакет на undeclared third-party imports у `.vue`-файлах: import стороннього
+ * пакета, якого немає в `dependencies`/`peerDependencies` package.json цього ж пакета (реальний
+ * кейс ADR — зламаний default-export `@vuepic/vue-datepicker` v14, silent breakage без цієї
+ * перевірки). Відносні імпорти, аліаси (`@/`, `~/`), Node-builtin і auto-import глобали
+ * пропускаються.
+ * @param {import('../scope/main.mjs').InScopePackage} entry пакет у скоупі
+ * @param {string[]} ignorePaths абсолютні шляхи, виключені з обходу
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер порушень
+ * @returns {Promise<void>}
+ */
+async function checkUndeclaredImportsForPackage(entry, ignorePaths, reporter) {
+  const declared = collectDeclaredDeps(entry.pkg)
+  const vueFiles = await collectVueFiles(entry.absDir, ignorePaths)
+
+  for (const absFile of vueFiles) {
+    const content = await readFile(absFile, 'utf8')
+    const relFromPkg = relative(entry.absDir, absFile).split('\\').join('/')
+    const specifiers = extractImportSpecifiers(content, relFromPkg)
+
+    const reportedForFile = new Set()
+    for (const spec of specifiers) {
+      if (isRelativeOrAliasSpecifier(spec) || isNodeBuiltinSpecifier(spec)) continue
+      const pkgName = topLevelPackageName(spec)
+      if (declared.has(pkgName) || reportedForFile.has(pkgName)) continue
+      reportedForFile.add(pkgName)
+
+      const fileRel = fileRelFromCwd(entry, relFromPkg)
+      reporter.fail(
+        `[undeclared-import] ${fileRel}: import '${spec}' — пакет '${pkgName}' відсутній у dependencies/peerDependencies ${entry.rootDir === '.' ? 'кореня монорепо' : entry.rootDir} (storybook.mdc hygiene)`,
+        {
+          reason: 'undeclared-import',
+          file: fileRel,
+          data: { rootDir: entry.rootDir, package: pkgName, specifier: spec }
+        }
+      )
+    }
+  }
+}
+
+/**
+ * Чи має пакет глобальні Quasar SCSS-змінні — canonical шлях за замовчуванням
+ * (quasar.dev/style/sass-scss-variables): `src/css/quasar.variables.scss` (fallback `.sass`).
+ * @param {string} absDir абсолютний шлях кореня пакета
+ * @returns {boolean} `true`, якщо знайдено файл глобальних SCSS-змінних
+ */
+function hasGlobalSassVariables(absDir) {
+  return SASS_VARIABLES_CANDIDATES.some(f => existsSync(join(absDir, f)))
+}
+
+/**
+ * Перевіряє один пакет на auto-detect глобальних SCSS-змінних: якщо в пакеті є
+ * `quasar.variables.scss`/`.sass`, а `.storybook/main.js` не вмикає `sassVariables` у
+ * `quasar()`-плагіні, глобальні SCSS-змінні недоступні у Storybook (тихий розсинхрон зі
+ * звичайним build). Рівень — `warn` (м'який сигнал, не гейт хвилі 1, аналогічно
+ * `onUnhandledRequest` у `preview.js`). Відсутність самого `.storybook/main.js` вже покриває
+ * `storybook/scaffold` — тут не дублюється.
+ * @param {import('../scope/main.mjs').InScopePackage} entry пакет у скоупі
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер порушень
+ * @returns {Promise<void>}
+ */
+async function checkSassVariablesForPackage(entry, reporter) {
+  if (!hasGlobalSassVariables(entry.absDir)) return
+
+  const mainJsPath = join(entry.absDir, '.storybook/main.js')
+  if (!existsSync(mainJsPath)) return
+
+  const content = await readFile(mainJsPath, 'utf8')
+  if (SASS_VARIABLES_MARKER_RE.test(content)) return
+
+  const fileRel = fileRelFromCwd(entry, '.storybook/main.js')
+  reporter.fail(
+    `[sass-variables] ${fileRel}: пакет має глобальні Quasar SCSS-змінні (${SASS_VARIABLES_CANDIDATES.join(' | ')}), але quasar({ sassVariables }) не задано в .storybook/main.js (storybook.mdc hygiene)`,
+    { reason: 'missing-sass-variables', file: fileRel, severity: 'warn', data: { rootDir: entry.rootDir } }
+  )
+}
+
+/**
+ * Detector concern-а `storybook/hygiene`: для кожного Vue component library пакета у скоупі
+ * канону Storybook (`collectInScopeVuePackages`) — undeclared third-party imports у `.vue` та
+ * auto-detect глобальних Quasar SCSS-змінних без `sassVariables` у `.storybook/main.js`
+ * (storybook.mdc, ADR Кластер 6). Breaking-change guard при мажорному апгрейді
+ * third-party-пакетів свідомо не автоматизується — людський пункт, hygiene.mdc.
+ * @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 cwd = ctx.cwd
+
+  const pkgs = await collectInScopeVuePackages(cwd)
+  if (pkgs.length === 0) {
+    reporter.pass('storybook hygiene: немає Vue component library пакетів у скоупі (storybook.mdc)')
+    return reporter.result()
+  }
+
+  const ignorePaths = await loadCursorIgnorePaths(cwd)
+  for (const entry of pkgs) {
+    await checkUndeclaredImportsForPackage(entry, ignorePaths, reporter)
+    await checkSassVariablesForPackage(entry, reporter)
+  }
+
+  return reporter.result()
+}

package/rules/storybook/main.json

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

package/rules/storybook/main.mdc

@@ -0,0 +1,60 @@
+---
+description: Канонічний Storybook для Vue-компонентних бібліотек — скафолд, vitest/Stryker, гігієна залежностей, рецепти мокання
+version: '1.0'
+globs: ["package.json", "**/*.vue", ".storybook/**"]
+alwaysApply: false
+---
+
+# Канон Storybook для Vue-компонентних бібліотек — хвиля 1
+
+Джерело рішення: `docs/adr/канон-storybook-для-vue-компонентних-бібліотек.md`. Storybook впроваджувався вручну двічі в різних nitra-репо в одній сесії — обидва рази з тими самими невидимими заздалегідь проблемами (конфлікт `@vitejs/plugin-vue`/`quasar()`, недоступні внутрішні Quasar-іконки без `iconSet`+`iconMapFn`, ручне мокання мережі) і одним реальним merge-конфліктом між двома паралельними ручними реалізаціями тієї самої фічі. Це правило робить канонічний скафолд стандартом, а не одноразовим рішенням кожного агента.
+
+**Хвильовий rollout:** `alwaysApply: false` — правило не гейтить CI, доки не ввімкнене явно в `.n-rules.json` консюмер-репо (`rules: ["storybook"]`). Хвиля 1 (це правило) покриває детекцію скоупу, канонічний скафолд `.storybook/`, vitest/Stryker-конфіг (Кластер 5), гігієну сторонніх залежностей (Кластер 6), рецепти мокання (docs-only, Кластер 3) і `--adopt`-режим rollout-у для вже впроваджених вручну пакетів (Кластер 8); **LLM-генерація args для stories — хвиля 2**, свідомо відкладена (ADR: ризик одночасного org-wide CI-блоку на необкатаному generation pipeline, на відміну від production-proven doc-files).
+
+Усі concern-и хвилі 1 (`scope`/`scaffold`/`vitest-config`/`hygiene`) мають `lint`-поверхню в `concern.json` і виконуються під `npx @7n/rules lint storybook` — `scope`/`scaffold`/`vitest-config` раніше декларували лише `check: true` без `lint`-блоку і тому мовчки не підхоплювались unified lint-рушієм (`run-detectors.mjs` виконує лише concern-и з явним `lint` чи `policy` блоком); виправлено разом із введенням `adopt`-режиму.
+
+## Скоуп
+
+Тільки Vue-компонентні бібліотеки — пакет із `vue` у `peerDependencies` (маркер `isVueComponentLibraryPkg`, той самий що й у `vue.mdc`, не дублюється) і не менше **3** `.vue`-файлів. Поріг відсікає пакети з одним-двома допоміжними компонентами, для яких повний Storybook-скафолд — зайві накладні витрати. Пакети без розпізнаваного `vite.config.{js,ts,mjs}` (нестандартний build) пропускаються мовчки — автоматичний скафолд спирається на `viteConfigPath` пакета.
+
+Опційно (вимкнено за замовчуванням) — app-проєкти (`vue` у `dependencies`, не бібліотека, + `src/pages/`). Детекція реалізована в `scope/main.mjs`, але не викликається доки в `.n-rules.json` не задано прапорець хвилі 2 — рішення розширювати скоуп на app-проєкти залишається відкритим питанням ADR.
+
+**Opt-out:** окремий пакет можна виключити зі скоупу через `.n-rules.json` → `storybook.optOut: string[]` (root dir пакета, той самий формат що й у виводі workspace-роутингу — `.` для кореня, `packages/ui` тощо). Виняток — намір, не помилка: якщо в `optOut` вказано неіснуючий workspace-пакет, `scope`-концерн репортує це як застаріле налаштування.
+
+Логіка детекції (поріг, opt-out, нестандартний build, app-проєкти) — у `scope/main.mjs`, не дублюється тут.
+
+## Канонічний скафолд
+
+Для кожного пакета в скоупі обов'язкові: `.storybook/main.js`, `.storybook/preview.js`, `package.json#scripts.storybook`. Канонічні шаблони — `scaffold/template/`.
+
+Фіксовані рішення (деталі — ADR, Кластер 2):
+
+- **Порядок 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` — файлова маршрутизація належить додатку-споживачу, не ізольованому рендеру компонента.
+- **`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).
+- **`.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 у ланцюжку фіксу не потрібен).
+
+## 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`, не дублюється тут.
+
+## Гігієна сторонніх залежностей (Кластер 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`.
+
+## Мокання (Кластер 3, docs-only)
+
+Рецепти router/`@nitra/tfm`/Apollo-GraphQL(MSW)/Pinia/сторінкових stories — `mocking/mocking.mdc`. Свідомо без механічної перевірки (`concern.json` без `check`/`policy`/`lint`-блоку, як і решта чисто-документаційних concern-ів репозиторію) — кожен пакет мокає свій набір залежностей по-своєму, детермінований чек дав би або хибні спрацювання, або нульове покриття.
+
+## Adopt-режим і скіл `n-storybook` (Кластер 8)
+
+Скіл `npm/skills/storybook/` (`.cursor/skills/n-storybook/` після синку) — тонка обгортка запуску: звичайний режим — `npx @7n/rules lint storybook`; `--adopt` — окремий діагностичний JS-модуль `adopt/main.mjs` для пакетів, де ВЖЕ є ручний `.storybook/`, що не збігається з каноном. Adopt діагностує diff по секціях проти `template/` (main.js/preview.js/mocks/gql-sse.js/package.json#scripts.storybook/vitest test.projects/vitest.stryker.config) — статус `match`/`differ`/`missing` на секцію, **без сліпого перезапису** розбіжних файлів; автофікс (`--fix-missing`) генерує лише секції зі статусом `missing`. Circuit breaker: збій діагностики одного пакета деградує до `status: 'broken'` для нього, решта пакетів прогону обробляються далі. Викликається напряму (`bun node_modules/@7n/rules-lang-js/rules/storybook/adopt/main.mjs`), без окремого CLI-прапорця в ядрі `n-rules.js` — деталі й приклади звіту в `SKILL.md` скіла.
+
+## Що свідомо поза хвилею 1
+
+LLM-генерація `args` для stories з `defineProps`/`defineEmits`/slots (Кластер 4 ADR) — хвиля 2, свідомо відкладена. Governance-винятки в `n-npm-module.mdc`/`n-bun.mdc` (Кластер 7 — Storybook-devDeps у `npm/package.json`, canonical version pin, review-гейт лише для нових stories) — окремий трек, не в обсязі цього правила.

package/rules/storybook/mocking/concern.json

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

package/rules/storybook/mocking/mocking.mdc

@@ -0,0 +1,108 @@
+## Мокання зовнішніх залежностей у 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' }
+          })
+        )
+      ]
+    }
+  }
+}
+```
+
+### 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: c06a9e15
+  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: не виконує операцій запису (ФС/БД).