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

package/rules/npm-module/npm_package_json/npm_package_json.rego

@@ -6,7 +6,17 @@
 #
 # Логіка, що ЛИШАЄТЬСЯ у rego (inverse-patterns, не виносяться у template):
 #  - форма поля `types` (regex pattern: `./types/index.d.ts` або `./types/<…>.d.ts|.d.mts`);
-#  - `devDependencies` мають бути відсутні або порожні (inverse-pattern — заборона будь-яких).
+#  - `devDependencies` мають бути відсутні/порожні АБО належати канонічному
+#    Storybook-allowlist із зафіксованою точною версією (канон Storybook, кластер 7
+#    Governance: `docs/adr/канон-storybook-для-vue-компонентних-бібліотек.md`).
+#    Storybook-devDeps живуть саме у `npm/package.json` консюмер-пакета
+#    (а не в кореневому package.json), бо майбутній `isStorybookRoot()` у
+#    `@7n/test` читає саме цей файл, щоб визначити Storybook-скоуп пакета.
+#    Канон — static map (той самий підхід, що й `allowed_root_test_deps` у
+#    `bun.package_json`), НЕ template: це не mandatory-presence дані (більшість
+#    npm-пакетів Storybook не має), тож генеричний T0-fix-writer цього
+#    concern-а (`createTemplateFixPattern`, deep-merge усього `template.snippet`
+#    у target) канонічні devDeps у кожен package.json не домерджує.
 #
 # FS-перевірки (наявність файлу зі шляху `types`, скан tarball на тест-патерни) — у JS.
 package npm_module.npm_package_json
@@ -20,10 +30,27 @@ types_field_template := concat(" ", [
 
 dev_deps_template := concat(" ", [
 	"npm/package.json: \"devDependencies\" не публікуються користувачам пакета —",
+	"дозволені лише канонічні Storybook-пакети (isStorybookRoot(), канон Storybook);",
 	"dev-інструментарій перенеси у кореневий package.json, а CLI-тули, які пакет",
 	"спавнить через bunx у споживачів, — у \"dependencies\": %v (npm-module.mdc)",
 ])
 
+storybook_version_template := concat(" ", [
+	"npm/package.json: devDependencies.%v = %q не відповідає зафіксованій версії",
+	"Storybook-канону %q — вирівняй версію пакета до канону (npm-module.mdc, канон Storybook)",
+])
+
+# Канонічні Storybook-devDeps (isStorybookRoot()-маркери, канон Storybook кластер 7):
+# зафіксована точна версія — єдина дозволена версія для кожного пакета. Оновлення —
+# ручна правка цієї map.
+storybook_canon_dev_deps := {
+	"storybook": "9.1.10",
+	"@storybook/vue3-vite": "9.1.10",
+	"@storybook/vue3": "9.1.10",
+	"msw": "2.11.3",
+	"msw-storybook-addon": "2.0.5",
+}
+
 # ── deny: types (regex — лишається в rego) ───────────────────────────────
 
 deny contains msg if {
@@ -57,13 +84,23 @@ deny contains msg if {
 	msg := sprintf("npm/package.json: масив \"%s\" має містити %q (npm-module.mdc)", [field, required])
 }
 
-# ── deny: devDependencies (inverse-pattern, лишається в rego) ────────────
+# ── deny: devDependencies (inverse-pattern + Storybook-allowlist виняток) ─
+
+deny contains msg if {
+	dev := object.get(input, "devDependencies", {})
+	forbidden_names := [n | some n, _ in dev; not n in object.keys(storybook_canon_dev_deps)]
+	count(forbidden_names) > 0
+	msg := sprintf(dev_deps_template, [concat(", ", sort(forbidden_names))])
+}
+
+# ── deny: Storybook-devDep присутній, але версія розходиться з каноном ──
 
 deny contains msg if {
 	dev := object.get(input, "devDependencies", {})
-	count(dev) > 0
-	names := concat(", ", sort([n | some n, _ in dev]))
-	msg := sprintf(dev_deps_template, [names])
+	some name, version in dev
+	canonical := storybook_canon_dev_deps[name]
+	version != canonical
+	msg := sprintf(storybook_version_template, [name, version, canonical])
 }
 
 # ── helpers ────────────────────────────────────────────────────────────────

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

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

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

@@ -0,0 +1,46 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/adopt/main.mjs
+docgen:
+  crc: 640409c7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 90
+  issues: anchor-miss:(mocking.mdc),anchor-miss:(vitest-config.mdc),judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Режим adopt для канону Storybook у Vue-бібліотеках: звіряє пакети з канонічними секціями `main.js`, `preview.js`, `mocks/gql-sse.js`, `package.json#scripts.storybook`, `vitest test.projects` і `vitest.stryker.config`, а для вже наявних ручних `.storybook/` без сліпого перезапису показує діагностику diff по секціях. Автофікс (`--fix-missing`) додає лише повністю відсутні секції, з тим самим рендером, що й T0-фікс concern-ів `scaffold`/`vitest-config`, без втручання в наявні розбіжні файли. Дає CLI-звіт по кожному пакету зі станом `status` і секціями `SECTION`, окремо фіксуючи `diagnosePackage`, `fixMissingSections`, `runAdopt` і `formatReport`; помилки перехоплює fail-safe, тому збій або діагностики, або фіксу для одного пакета переводить лише його в `status: 'broken'`, а решта пакетів продовжують оброблятися.
+## Поведінка
+
+- `STATUS` — задає фіксовані стани діагностики секцій Storybook: збіг, розбіжність або відсутність.
+- `SECTION` — задає стабільні назви секцій звіту, щоб adopt-перевірка й `--fix-missing` узгоджено посилалися на ті самі частини конфігурації.
+- `diagnosePackage` — перевіряє пакет по секціях і повертає підсумок: канонічний, з відсутніми файлами або з відмінностями; помилки окремих секцій не валять увесь пакет.
+- `fixMissingSections` — створює лише ті канонічні секції, яких у пакеті немає взагалі, і не перезаписує наявні розбіжні файли.
+- `runAdopt` — проганяє adopt-перевірку по всіх або вибраних пакетах у скоупі, із fail-safe поведінкою: збій одного пакета переходить у `broken`, але інші обробляються далі.
+- `formatReport` — перетворює результати adopt-прогону на лаконічний український звіт для CLI, включно з переліком згенерованого або повідомленням про відсутність пакетів у скоупі.
+
+## Публічний API
+
+- STATUS — Статуси однієї секції діагностики (діагностика ≠ lint-violation — тут завжди 4 значення).
+- SECTION — Канонічні назви секцій (стабільні — на них зав'язаний `--fix-missing`-switch).
+- diagnosePackage — Діагностика одного пакета в скоупі по секціях. Ніколи не кидає — збій окремої
+секції (парсинг/IO) відображається як секція `differ`, а не виняток, що впав
+би на весь пакет; лишається на розсуд `diagnosePackage` (circuit breaker рівня
+пакета — тут не потрібен, бо секції вже ізольовані одна від одної).
+- fixMissingSections — Генерує канонічний вміст лише для секцій зі статусом `missing` одного пакета
+(adopt-автофікс НІКОЛИ не чіпає секції зі статусом `differ` — інструкція
+для агента/людини, не сліпий перезапис). Кожна секція фіксується незалежно;
+збій однієї не блокує решту (той самий circuit-breaker принцип, лише на дрібнішому рівні).
+- runAdopt — Adopt-прогін усіх (чи обраних) пакетів у скоупі. Circuit breaker (ADR Кластер 8):
+збій діагностики/фіксу ОДНОГО пакета деградує до `status: 'broken'` для нього —
+решта пакетів обробляються далі, весь прогін ніколи не падає через один зламаний.
+  відсутні секції; `rootDirs` — звузити прогін до цих коренів пакетів (порожньо/відсутнє → усі в скоупі)
+- formatReport — Форматує людський звіт по результатах `runAdopt` (українською, для виводу скіла в CLI).
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/storybook/adopt/main.mjs

@@ -0,0 +1,379 @@
+/**
+ * Adopt-режим канону Storybook (ADR канон-storybook-для-vue-компонентних-бібліотек,
+ * Кластер 8; main.mdc). Для пакетів, де ВЖЕ є ручний `.storybook/`, що не збігається з
+ * каноном, — діагностика diff по секціях проти канонічних `template/` (main.js,
+ * preview.js, mocks/gql-sse.js, package.json#scripts.storybook, vitest test.projects,
+ * vitest.stryker.config), БЕЗ сліпого перезапису розбіжних файлів. Автофікс
+ * (`--fix-missing`) — лише для секцій, яких немає ВЗАГАЛІ (той самий рендер, що й
+ * T0-фікс concern-ів `scaffold`/`vitest-config` — переюз, не дублювання шаблонування).
+ *
+ * Circuit breaker (ADR): збій діагностики чи фіксу одного пакета деградує до
+ * `status: 'broken'` для ЦЬОГО пакета — решта пакетів прогону обробляються далі,
+ * увесь прогін ніколи не падає через один зламаний пакет.
+ *
+ * Викликається зі скіла (`npm/skills/storybook/SKILL.md`, `--adopt`):
+ *   bun node_modules/@7n/rules-lang-js/rules/storybook/adopt/main.mjs [--fix-missing] [--cwd <path>] [rootDir...]
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { isRunAsCli } from '@7n/rules/scripts/cli-entry.mjs'
+
+import { collectInScopeVuePackages } from '../scope/main.mjs'
+import { MAIN_JS_MARKERS, missingMarkers, PREVIEW_JS_MARKERS, STORYBOOK_SCRIPT } from '../scaffold/main.mjs'
+import { renderMainJs, renderMocksGqlSse, renderPreviewJs } from '../scaffold/fix-scaffold.mjs'
+import { buildFreshVitestConfig, buildStrykerConfig } from '../vitest-config/fix-vitest-config.mjs'
+import {
+  BROWSER_KEY_RE,
+  CHROMIUM_RE,
+  classifyProjects,
+  findProperty,
+  findTestObject,
+  parseModule,
+  resolveVitestConfigPath,
+  STORIES_RE,
+  strykerConfigPathFor
+} from '../vitest-config/main.mjs'
+
+/** Статуси однієї секції діагностики (діагностика ≠ lint-violation — тут завжди 4 значення). */
+export const STATUS = Object.freeze({ MATCH: 'match', DIFFER: 'differ', MISSING: 'missing' })
+
+/** Канонічні назви секцій (стабільні — на них зав'язаний `--fix-missing`-switch). */
+export const SECTION = Object.freeze({
+  MAIN_JS: 'main.js',
+  PREVIEW_JS: 'preview.js',
+  MOCKS_GQL_SSE: 'mocks/gql-sse.js',
+  PACKAGE_SCRIPT: 'package.json#scripts.storybook',
+  VITEST_PROJECTS: 'vitest test.projects (unit+storybook)',
+  STRYKER_CONFIG: 'vitest.stryker.config'
+})
+
+/**
+ * posix-relative шлях файлу пакета від кореня репозиторію (для звіту/сообщений).
+ * @param {{ rootDir: string }} entry запис пакета
+ * @param {string} suffix шлях файлу відносно кореня пакета
+ * @returns {string} відносний шлях від кореня репозиторію
+ */
+function relFileFor(entry, suffix) {
+  return entry.rootDir === '.' ? suffix : `${entry.rootDir}/${suffix}`
+}
+
+/**
+ * Діагностика файлу, канон якого перевіряється текстовими маркерами (main.js/preview.js).
+ * @param {{ absDir: string, rootDir: string }} entry запис пакета
+ * @param {string} relPath шлях файлу відносно кореня пакета (`.storybook/main.js`)
+ * @param {string} sectionName ім'я секції звіту
+ * @param {{ token: string, hint: string }[]} markers канонічні маркери файлу
+ * @returns {{ name: string, file: string, status: string, detail?: string }} одна секція діагностики
+ */
+function diagnoseMarkerFile(entry, relPath, sectionName, markers) {
+  const file = relFileFor(entry, relPath)
+  const abs = join(entry.absDir, relPath)
+  if (!existsSync(abs)) return { name: sectionName, file, status: STATUS.MISSING }
+  const content = readFileSync(abs, 'utf8')
+  const missing = missingMarkers(content, markers)
+  if (missing.length === 0) return { name: sectionName, file, status: STATUS.MATCH }
+  return {
+    name: sectionName,
+    file,
+    status: STATUS.DIFFER,
+    detail: `бракує: ${missing.map(m => m.hint).join(', ')}`
+  }
+}
+
+/**
+ * Діагностика `.storybook/mocks/gql-sse.js` — verbatim-порівняння з канонічним helper-ом
+ * (одне джерело істини протоколу graphql-sse, mocking.mdc — не переносити копію в пакет).
+ * @param {{ absDir: string, rootDir: string }} entry запис пакета
+ * @returns {{ name: string, file: string, status: string, detail?: string }} секція діагностики
+ */
+function diagnoseMocksSection(entry) {
+  const relPath = '.storybook/mocks/gql-sse.js'
+  const file = relFileFor(entry, relPath)
+  const abs = join(entry.absDir, relPath)
+  if (!existsSync(abs)) return { name: SECTION.MOCKS_GQL_SSE, file, status: STATUS.MISSING }
+  const actual = readFileSync(abs, 'utf8')
+  const canonical = renderMocksGqlSse()
+  if (actual === canonical) return { name: SECTION.MOCKS_GQL_SSE, file, status: STATUS.MATCH }
+  return {
+    name: SECTION.MOCKS_GQL_SSE,
+    file,
+    status: STATUS.DIFFER,
+    detail: 'вміст відрізняється від канонічного helper-а (mocking.mdc) — одне джерело істини, не дублюй логіку вручну'
+  }
+}
+
+/**
+ * Діагностика `package.json#scripts.storybook`.
+ * @param {{ pkg: Record<string, unknown>, rootDir: string }} entry запис пакета
+ * @returns {{ name: string, file: string, status: string, detail?: string }} секція діагностики
+ */
+function diagnoseScriptSection(entry) {
+  const file = relFileFor(entry, 'package.json')
+  const current = /** @type {{ scripts?: Record<string, unknown> }} */ (entry.pkg)?.scripts?.storybook
+  if (current === undefined) return { name: SECTION.PACKAGE_SCRIPT, file, status: STATUS.MISSING }
+  if (current === STORYBOOK_SCRIPT) return { name: SECTION.PACKAGE_SCRIPT, file, status: STATUS.MATCH }
+  return {
+    name: SECTION.PACKAGE_SCRIPT,
+    file,
+    status: STATUS.DIFFER,
+    detail: `зараз '${current}', канон '${STORYBOOK_SCRIPT}'`
+  }
+}
+
+/**
+ * Діагностика `test.projects` наявного vitest-конфіга (unit+storybook, browser-mode маркери).
+ * @param {{ absDir: string, rootDir: string }} entry запис пакета
+ * @returns {{ name: string, file: string, status: string, detail?: string }} секція діагностики
+ */
+function diagnoseVitestProjectsSection(entry) {
+  const name = SECTION.VITEST_PROJECTS
+  const vitestConfigPath = resolveVitestConfigPath(entry.absDir)
+  if (!vitestConfigPath) {
+    return { name, file: relFileFor(entry, 'vitest.config.mjs'), status: STATUS.MISSING }
+  }
+  const file = relFileFor(entry, vitestConfigPath.slice(entry.absDir.length + 1))
+  const src = readFileSync(vitestConfigPath, 'utf8')
+
+  let parsed
+  try {
+    parsed = parseModule(vitestConfigPath, src)
+  } catch (error) {
+    return { name, file, status: STATUS.DIFFER, detail: `не парситься (${error.message}) — перевір вручну` }
+  }
+  if (parsed.errors?.length) {
+    return { name, file, status: STATUS.DIFFER, detail: 'syntax error — перевір вручну' }
+  }
+
+  const testObj = findTestObject(parsed.program)
+  if (!testObj) {
+    return { name, file, status: STATUS.DIFFER, detail: 'немає test-блоку (defineConfig({ test: {...} }))' }
+  }
+
+  const projectsProp = findProperty(testObj, 'projects')
+  if (!projectsProp) {
+    return { name, file, status: STATUS.MISSING, detail: 'test.projects відсутній' }
+  }
+  if (projectsProp.value?.type !== 'ArrayExpression') {
+    return { name, file, status: STATUS.DIFFER, detail: 'test.projects не статичний масив (spread/змінна)' }
+  }
+
+  const { hasUnit, storybookSlice } = classifyProjects(src, projectsProp.value)
+  if (!hasUnit || !storybookSlice) {
+    const missingParts = [hasUnit ? null : "'unit'", storybookSlice ? null : "'storybook'"].filter(Boolean)
+    return { name, file, status: STATUS.DIFFER, detail: `бракує ${missingParts.join(' і ')} у test.projects` }
+  }
+
+  const missingHints = []
+  if (!CHROMIUM_RE.test(storybookSlice)) missingHints.push('chromium-інстанс')
+  if (!BROWSER_KEY_RE.test(storybookSlice)) missingHints.push('browser-mode')
+  if (!STORIES_RE.test(storybookSlice)) missingHints.push('stories-glob')
+  if (missingHints.length > 0) {
+    return { name, file, status: STATUS.DIFFER, detail: `storybook-project без: ${missingHints.join(', ')}` }
+  }
+
+  return { name, file, status: STATUS.MATCH }
+}
+
+/**
+ * Діагностика ізольованого `vitest.stryker.config.*` — байтове порівняння з канонічним
+ * baseline-рендером (fix-vitest-config.mjs, той самий генератор).
+ * @param {{ absDir: string, rootDir: string }} entry запис пакета
+ * @returns {Promise<{ name: string, file: string, status: string, detail?: string }>} секція діагностики
+ */
+async function diagnoseStrykerSection(entry) {
+  const name = SECTION.STRYKER_CONFIG
+  const vitestConfigPath = resolveVitestConfigPath(entry.absDir)
+  if (!vitestConfigPath) {
+    return { name, file: relFileFor(entry, 'vitest.stryker.config.mjs'), status: STATUS.MISSING }
+  }
+  const strykerPath = strykerConfigPathFor(vitestConfigPath)
+  const file = relFileFor(entry, strykerPath.slice(entry.absDir.length + 1))
+  if (!existsSync(strykerPath)) {
+    return { name, file, status: STATUS.MISSING }
+  }
+  const actual = readFileSync(strykerPath, 'utf8')
+  const canonical = await buildStrykerConfig(entry.absDir)
+  if (actual === canonical) return { name, file, status: STATUS.MATCH }
+  return {
+    name,
+    file,
+    status: STATUS.DIFFER,
+    detail:
+      'вміст відрізняється від канонічного baseline (vitest-config.mdc) — @stryker-mutator/vitest-runner крашиться на browser-mode projects, перевір вручну'
+  }
+}
+
+/**
+ * Діагностика одного пакета в скоупі по секціях. Ніколи не кидає — збій окремої
+ * секції (парсинг/IO) відображається як секція `differ`, а не виняток, що впав
+ * би на весь пакет; лишається на розсуд `diagnosePackage` (circuit breaker рівня
+ * пакета — тут не потрібен, бо секції вже ізольовані одна від одної).
+ * @param {import('../scope/main.mjs').InScopePackage} entry пакет у скоупі
+ * @returns {Promise<{ rootDir: string, status: 'canonical'|'missing-files'|'differs', sections: object[] }>} діагностика пакета
+ */
+export async function diagnosePackage(entry) {
+  const sections = [
+    diagnoseMarkerFile(entry, '.storybook/main.js', SECTION.MAIN_JS, MAIN_JS_MARKERS),
+    diagnoseMarkerFile(entry, '.storybook/preview.js', SECTION.PREVIEW_JS, PREVIEW_JS_MARKERS),
+    diagnoseMocksSection(entry),
+    diagnoseScriptSection(entry),
+    diagnoseVitestProjectsSection(entry),
+    await diagnoseStrykerSection(entry)
+  ]
+  let status = 'canonical'
+  if (sections.some(s => s.status === STATUS.DIFFER)) status = 'differs'
+  else if (sections.some(s => s.status === STATUS.MISSING)) status = 'missing-files'
+  return { rootDir: entry.rootDir, status, sections }
+}
+
+/**
+ * Генерує канонічний вміст лише для секцій зі статусом `missing` одного пакета
+ * (adopt-автофікс НІКОЛИ не чіпає секції зі статусом `differ` — інструкція
+ * для агента/людини, не сліпий перезапис). Кожна секція фіксується незалежно;
+ * збій однієї не блокує решту (той самий circuit-breaker принцип, лише на дрібнішому рівні).
+ * @param {import('../scope/main.mjs').InScopePackage} entry пакет у скоупі
+ * @param {object[]} sections секції діагностики пакета (`diagnosePackage().sections`)
+ * @returns {Promise<string[]>} абсолютні шляхи записаних файлів
+ */
+export async function fixMissingSections(entry, sections) {
+  const written = []
+  const writeFileEnsureDir = (absPath, content) => {
+    mkdirSync(dirname(absPath), { recursive: true })
+    writeFileSync(absPath, content, 'utf8')
+    written.push(absPath)
+  }
+
+  const byName = new Map(sections.map(s => [s.name, s]))
+
+  if (byName.get(SECTION.MAIN_JS)?.status === STATUS.MISSING) {
+    writeFileEnsureDir(join(entry.absDir, '.storybook/main.js'), renderMainJs(entry.absDir))
+  }
+  if (byName.get(SECTION.PREVIEW_JS)?.status === STATUS.MISSING) {
+    writeFileEnsureDir(join(entry.absDir, '.storybook/preview.js'), renderPreviewJs())
+  }
+  if (byName.get(SECTION.MOCKS_GQL_SSE)?.status === STATUS.MISSING) {
+    writeFileEnsureDir(join(entry.absDir, '.storybook/mocks/gql-sse.js'), renderMocksGqlSse())
+  }
+  if (byName.get(SECTION.PACKAGE_SCRIPT)?.status === STATUS.MISSING) {
+    const pkgPath = join(entry.absDir, 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    pkg.scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {}
+    pkg.scripts.storybook = STORYBOOK_SCRIPT
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    written.push(pkgPath)
+  }
+  if (byName.get(SECTION.VITEST_PROJECTS)?.status === STATUS.MISSING && !resolveVitestConfigPath(entry.absDir)) {
+    // test.projects відсутній ЛИШЕ через відсутність усього vitest-конфіга — augment
+    // наявного (без відсутнього test-блоку) свідомо поза adopt-автофіксом: секція вже
+    // позначена `differ` (не `missing`) для такого випадку, сюди він не потрапляє.
+    const fresh = await buildFreshVitestConfig(entry.absDir)
+    writeFileEnsureDir(fresh.path, fresh.content)
+  }
+  if (byName.get(SECTION.STRYKER_CONFIG)?.status === STATUS.MISSING) {
+    const vitestConfigPath = resolveVitestConfigPath(entry.absDir) ?? join(entry.absDir, 'vitest.config.mjs')
+    const strykerPath = strykerConfigPathFor(vitestConfigPath)
+    writeFileEnsureDir(strykerPath, await buildStrykerConfig(entry.absDir))
+  }
+
+  return written
+}
+
+/**
+ * Adopt-прогін усіх (чи обраних) пакетів у скоупі. Circuit breaker (ADR Кластер 8):
+ * збій діагностики/фіксу ОДНОГО пакета деградує до `status: 'broken'` для нього —
+ * решта пакетів обробляються далі, весь прогін ніколи не падає через один зламаний.
+ * @param {string} cwd абсолютний корінь консюмер-репо
+ * @param {{ fixMissing?: boolean, rootDirs?: string[] }} [opts] `fixMissing` — генерувати
+ *   відсутні секції; `rootDirs` — звузити прогін до цих коренів пакетів (порожньо/відсутнє → усі в скоупі)
+ * @returns {Promise<{ rootDir: string, status: string, sections?: object[], written?: string[], error?: string }[]>} результати за пакетами
+ */
+export async function runAdopt(cwd, opts = {}) {
+  const fixMissing = opts.fixMissing === true
+  const wantedRoots = Array.isArray(opts.rootDirs) && opts.rootDirs.length > 0 ? new Set(opts.rootDirs) : null
+
+  const allPkgs = await collectInScopeVuePackages(cwd)
+  const pkgs = wantedRoots ? allPkgs.filter(p => wantedRoots.has(p.rootDir)) : allPkgs
+
+  const results = []
+  for (const entry of pkgs) {
+    try {
+      const diagnosis = await diagnosePackage(entry)
+      const written = fixMissing ? await fixMissingSections(entry, diagnosis.sections) : []
+      results.push({ ...diagnosis, written })
+    } catch (error) {
+      results.push({
+        rootDir: entry.rootDir,
+        status: 'broken',
+        error: error instanceof Error ? error.message : String(error)
+      })
+    }
+  }
+  return results
+}
+
+/** Іконка статусу пакета (`package.status`) для рядка звіту. */
+const PACKAGE_STATUS_ICONS = Object.freeze({ canonical: '✅', 'missing-files': '➕' })
+/** Іконка статусу секції (`STATUS.*`) для рядка звіту. */
+const SECTION_STATUS_ICONS = Object.freeze({ [STATUS.MATCH]: '  ✓', [STATUS.MISSING]: '  +' })
+
+/**
+ * Рядки звіту одного НЕ зламаного пакета (статус + секції + перелік згенерованого).
+ * @param {{ rootDir: string, status: string, sections: object[], written?: string[] }} r результат одного пакета
+ * @returns {string[]} рядки звіту
+ */
+function formatPackageLines(r) {
+  const label = r.rootDir === '.' ? 'корінь' : r.rootDir
+  const lines = [`${PACKAGE_STATUS_ICONS[r.status] ?? '⚠️ '} [${label}] ${r.status}`]
+  for (const s of r.sections) {
+    const sIcon = SECTION_STATUS_ICONS[s.status] ?? '  ✗'
+    const suffix = s.detail ? ` — ${s.detail}` : ''
+    lines.push(`${sIcon} ${s.name} (${s.file}): ${s.status}${suffix}`)
+  }
+  if (r.written && r.written.length > 0) {
+    lines.push(`  згенеровано: ${r.written.join(', ')}`)
+  }
+  return lines
+}
+
+/**
+ * Форматує людський звіт по результатах `runAdopt` (українською, для виводу скіла в CLI).
+ * @param {Awaited<ReturnType<typeof runAdopt>>} results результати `runAdopt`
+ * @returns {string} багаторядковий текстовий звіт
+ */
+export function formatReport(results) {
+  if (results.length === 0) {
+    return 'storybook adopt: немає Vue component library пакетів у скоупі (storybook.mdc → scope/main.mjs)'
+  }
+  const lines = []
+  for (const r of results) {
+    if (r.status === 'broken') {
+      const label = r.rootDir === '.' ? 'корінь' : r.rootDir
+      lines.push(`⚠️  [${label}] діагностика впала (circuit breaker, пропущено): ${r.error}`)
+      continue
+    }
+    lines.push(...formatPackageLines(r))
+  }
+  return lines.join('\n')
+}
+
+/**
+ * CLI-вхід: `bun .../storybook/adopt/main.mjs [--fix-missing] [--cwd <path>] [rootDir...]`.
+ * @returns {Promise<void>} завершення прогону (друкує звіт, exit-код — кількість `differs`/`broken`)
+ */
+async function runCli() {
+  const args = process.argv.slice(2)
+  const fixMissing = args.includes('--fix-missing')
+  const cwdIdx = args.indexOf('--cwd')
+  const cwd = cwdIdx !== -1 && args[cwdIdx + 1] ? args[cwdIdx + 1] : process.cwd()
+  const rootDirs = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--cwd')
+
+  const results = await runAdopt(cwd, { fixMissing, rootDirs })
+  console.log(formatReport(results))
+  const hasIssues = results.some(r => r.status === 'differs' || r.status === 'broken')
+  process.exitCode = hasIssues ? 1 : 0
+}
+
+if (isRunAsCli(import.meta.url)) {
+  await runCli()
+}

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).