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

package/rules/storybook/ci/main.mjs

@@ -0,0 +1,112 @@
+/** @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'
+import { missingMarkers } from '../scaffold/main.mjs'
+
+/** Repo-relative шлях канонічного composite action (не per-package — один на репозиторій). */
+export const PLAYWRIGHT_ACTION_REL = '.github/actions/setup-playwright-chromium/action.yml'
+
+/** Repo-relative шлях канонічного workflow, що запускає `vitest --project=storybook`. */
+export const STORYBOOK_WORKFLOW_REL = '.github/workflows/lint-storybook.yml'
+
+/**
+ * Маркери канону composite action `setup-playwright-chromium` (ADR Кластер 5): кеш
+ * `ms-playwright` через `actions/cache`, ключ від версії playwright, install лише chromium.
+ * Текстовий пошук — той самий підхід, що й `MAIN_JS_MARKERS`/`PREVIEW_JS_MARKERS` у `scaffold`.
+ */
+export const PLAYWRIGHT_ACTION_MARKERS = [
+  { token: 'ms-playwright', hint: 'кеш каталогу ms-playwright' },
+  { token: 'actions/cache@', hint: 'actions/cache для Playwright-браузерів' },
+  { token: 'playwright install chromium', hint: 'install лише chromium (не всі браузери)' }
+]
+
+/**
+ * Маркери канону `.github/workflows/lint-storybook.yml`: композитний Playwright-кеш ПІСЛЯ
+ * setup-bun-deps, і швидкий `vitest --project=storybook` (ADR Кластер 5 — nightly-only
+ * `@7n/test coverage`/mutation-testing на PR не запускається, лише цей швидкий шлях).
+ */
+export const STORYBOOK_WORKFLOW_MARKERS = [
+  { token: './.github/actions/setup-bun-deps', hint: 'setup-bun-deps перед Playwright-кроком' },
+  { token: './.github/actions/setup-playwright-chromium', hint: 'композитний Playwright-кеш' },
+  { token: '--project=storybook', hint: 'швидкий прогін лише storybook-проєкту (не повний coverage)' }
+]
+
+/**
+ * Перевіряє один репо-рівневий канонічний файл (composite action чи workflow): відсутність →
+ * `missingReason`-порушення з посиланням на `npx \@7n/rules fix storybook`; присутність без
+ * якогось маркера → `markerReason`-порушення на конкретний маркер. Той самий патерн, що й
+ * `checkCanonFile` у `scaffold/main.mjs`, але без per-package `rootDir` — файл один на репо.
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @param {string} relFile posix-relative шлях файлу від кореня репозиторію
+ * @param {{ token: string, hint: string }[]} markers канонічні маркери файлу
+ * @param {string} missingReason reason для порушення "файл відсутній"
+ * @param {string} markerReason reason для порушення "маркер відсутній"
+ * @param {ReturnType<typeof createViolationReporter>} reporter reporter поточного лінту
+ * @returns {Promise<void>}
+ */
+async function checkRepoCanonFile(cwd, relFile, markers, missingReason, markerReason, reporter) {
+  const abs = join(cwd, relFile)
+  if (existsSync(abs)) {
+    const content = await readFile(abs, 'utf8')
+    for (const m of missingMarkers(content, markers)) {
+      reporter.fail(`${relFile} не відповідає канону — бракує: ${m.hint} (storybook.mdc, ADR Кластер 5)`, {
+        reason: markerReason,
+        file: relFile
+      })
+    }
+    return
+  }
+  reporter.fail(
+    `Відсутній ${relFile} — канонічний Playwright-кеш для vitest storybook-проєкту: npx @7n/rules fix storybook (storybook.mdc, ADR Кластер 5)`,
+    { reason: missingReason, file: relFile }
+  )
+}
+
+/**
+ * Detector concern-а `storybook/ci` (ADR Кластер 5, CI-частина): для репозиторіїв з бодай
+ * одним Vue component library пакетом у скоупі Storybook (`collectInScopeVuePackages`) —
+ * канонічний composite action `setup-playwright-chromium` (кеш Playwright-браузерів, лише
+ * chromium) і канонічний `.github/workflows/lint-storybook.yml`, що запускає швидкий
+ * `vitest --project=storybook` на PR. Гейтований `requires.capability: ci:github` — спить
+ * у репозиторіях без плагіна `@7n/rules-ci-github` (немає `.github/workflows`).
+ *
+ * Nightly-only `@7n/test coverage` (mutation testing) — поза обсягом цього concern-а: ADR
+ * Кластер 5 явно розділяє швидкий PR-шлях (цей concern) і nightly mutation-прогін, який
+ * лишається окремою інфраструктурою `test/stryker_config`.
+ * @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/ci: немає Vue component library пакетів у скоупі (storybook.mdc)')
+    return reporter.result()
+  }
+
+  await checkRepoCanonFile(
+    cwd,
+    PLAYWRIGHT_ACTION_REL,
+    PLAYWRIGHT_ACTION_MARKERS,
+    'missing-playwright-action',
+    'playwright-action-marker-missing',
+    reporter
+  )
+
+  await checkRepoCanonFile(
+    cwd,
+    STORYBOOK_WORKFLOW_REL,
+    STORYBOOK_WORKFLOW_MARKERS,
+    'missing-storybook-workflow',
+    'storybook-workflow-marker-missing',
+    reporter
+  )
+
+  return reporter.result()
+}

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

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

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

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

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

@@ -0,0 +1,45 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/hygiene/main.mjs
+docgen:
+  crc: 9e36e1a2
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 85
+  issues: internal-name:collectInScopeVuePackages,anchor-miss:(storybook.mdc),judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл описує read-only lint-перевірку `lint` для Storybook-правил, що спираються на `package.json`. Перевірка потрібна, щоб виявляти порушення конфігурації без змін у файловій системі чи БД; помилки перехоплюються fail-safe і не виходять назовні як винятки.
+
+## Поведінка
+
+1. `lint` визначає Vue component library пакети, для яких діє Storybook-канон. Якщо таких пакетів немає, повертає успішний результат із повідомленням.
+
+2. Для кожного знайденого пакета читає його `package.json` і формує перелік дозволених third-party залежностей із `dependencies` та `peerDependencies`.
+
+3. Переглядає `.vue` файли пакета з урахуванням ignore-конфігурації та знаходить імпорти сторонніх пакетів. Відносні шляхи, alias-шляхи, Node builtin модулі та auto-import глобали не вважаються порушеннями.
+
+4. Якщо `.vue` файл імпортує сторонній пакет, якого немає в `package.json` поточного пакета, додає порушення `undeclared-import`. Для одного файлу один і той самий пакет повідомляється лише один раз.
+
+5. Перевіряє, чи має пакет глобальні Quasar SCSS-змінні. Якщо вони є, але `.storybook/main.js` не вмикає їх для Storybook, додає попередження `missing-sass-variables`.
+
+6. Не змінює файлову систему або зовнішній стан: перевірка працює read-only і лише повертає результат лінту.
+
+7. Некоректні або нерозбірні файли не зупиняють перевірку назовні: такі випадки обробляються fail-safe, щоб лінт міг продовжити роботу.
+
+## Публічний API
+
+- lint — 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.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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,66 @@
+---
+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`, `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`.
+- **`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`, не дублюється тут.
+
+### 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.
+
+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`.
+
+## Мокання (Кластер 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"
+}