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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.10.0] - 2026-07-21
+
+### Added
+
+- storybook: канон Storybook хвилі 1 для Vue-компонентних бібліотек — детекція скоупу (isVueComponentLibraryPkg, поріг ≥3 .vue, opt-out), канонічний скафолд .storybook/main.js+preview.js+mocks/gql-sse.js, package.json#scripts.storybook (ADR канон-storybook-для-vue-компонентних-бібліотек)
+- npm-module/bun: governance-виняток канону Storybook (кластер 7 ADR канон-storybook-для-vue-компонентних-бібліотек) — npm_package_json.rego дозволяє канонічні Storybook-devDeps (storybook, @storybook/vue3-vite, @storybook/vue3, msw, msw-storybook-addon) у npm/package.json із зафіксованою точною версією (deny на неканонічний пакет або неканонічну версію); bun/package_json.rego розширює root-only test peers на @vitest/browser + playwright (browser-mode provider для named vitest project "storybook", лише chromium) та @storybook/addon-vitest (storybookTest-плагін того самого vitest-конфіга) — Storybook-identity-пакети у корінь свідомо не додаються
+- storybook: vitest-config-концерн хвилі 1 (ADR Кластер 5) — canonical test.projects unit+storybook (browser-mode, лише chromium, stories-glob) дописується поверх наявного vitest-конфіга, ізольований vitest.stryker.config генерується поруч (Stryker крашиться на browser-mode projects)
+- storybook: концерни mocking (docs-only рецепти router/tfm/Apollo-MSW/Pinia/page-story) і hygiene (undeclared third-party imports у .vue, auto-detect sassVariables) — ADR Кластер 3/6
+
+### Fixed
+
+- storybook: підключено concern-и scope/scaffold/vitest-config до unified lint-рушія (lint-блок у concern.json — check:true без lint мовчки ігнорувався run-detectors.mjs), додано --adopt-режим (adopt/main.mjs) і скіл n-storybook
+
 ## [0.9.0] - 2026-07-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules-lang-js",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Плагін @7n/rules: JS/npm/bun-екосистема — lint-правила (js/bun/vue/js-run/npm-module/db), taze-провайдер (package.json, bunx taze) і doc-files-екстрактори (oxc AST)",
   "keywords": [
     "javascript",

package/rules/bun/package_json/package_json.mdc

@@ -9,6 +9,8 @@ Rego-пакет: `bun.package_json`
 Gate виносить два класи deny:
 
 1. **Заборонені top-level поля** — будь-яке поле з `package.json.deny.json` присутнє у файлі (навіть із порожнім значенням `{}`).
-2. **devDependencies не з білого списку** — дозволені лише `@nitra/*`/`@7n/*` та root-only тестові peer/tools (`vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`, `@playwright/test`). Будь-який інший пакет → deny. CLI-тули, які `n-rules lint` спавнить через `bunx` (oxlint, jscpd, v8r, github-actionlint тощо), у root не пінуються — вони приїжджають як `dependencies` пакета `@7n/rules` (npm-module.mdc).
+2. **devDependencies не з білого списку** — дозволені лише `@nitra/*`/`@7n/*` та root-only тестові peer/tools (`vitest`, `@vitest/coverage-v8`, `@vitest/browser`, `@stryker-mutator/vitest-runner`, `@stryker-mutator/core`, `@playwright/test`, `playwright`, `@storybook/addon-vitest`, `@7n/test`). Будь-який інший пакет → deny. CLI-тули, які `n-rules lint` спавнить через `bunx` (oxlint, jscpd, v8r, github-actionlint тощо), у root не пінуються — вони приїжджають як `dependencies` пакета `@7n/rules` (npm-module.mdc).
+
+`@vitest/browser`/`playwright`/`@storybook/addon-vitest` — додані для named vitest project "storybook" (канон Storybook, кластер 5: browser-mode, лише chromium) — той самий root vitest.config, що й `unit`-проект; `@storybook/addon-vitest` постачає `storybookTest`-плагін для цього vitest-конфіга (канонічний template правила `storybook`). **Межа з `npm-module.mdc`**: Storybook-специфічні identity-пакети (`storybook`, `@storybook/vue3-vite`, `@storybook/vue3`, `msw`, `msw-storybook-addon`) у цей allowlist **не** додаються — вони живуть у `npm/package.json` консюмер-пакета (канон Storybook, кластер 7 Governance), бо `isStorybookRoot()` у `@7n/test` детектує Storybook-скоуп саме за тим файлом, не кореневим. `@storybook/addon-vitest` — виняток із цієї межі: він test-tooling (vitest-плагін), а не identity-маркер, тож root, як і решта vitest-peer'ів.
 
 Перевірки, що потребують FS або cross-file контексту (наприклад наявність `yarn.lock`), лишаються у JS-шарі.

package/rules/bun/package_json/package_json.rego

@@ -8,6 +8,15 @@
 #  - `devDependencies` лише `@nitra/*` + root-only тестові peer/tools для `@7n/test coverage`
 #    (правило `test` enabled завжди — див. `test/auto.md`; published workspace-и не мають
 #     `devDependencies` за `npm-module.mdc`)
+#  - `@vitest/browser`/`playwright`/`@storybook/addon-vitest` (browser-mode provider +
+#    `storybookTest`-плагін для named vitest project "storybook", лише chromium — канон
+#    Storybook кластер 5) теж root-only test peers: той самий vitest.config, що й
+#    `unit`-проект, живе в корені монорепо-споживача. Storybook-специфічні
+#    identity-пакети (`storybook`, `@storybook/vue3*`, `msw*`) НЕ сюди — вони живуть у
+#    `npm/package.json` (канон Storybook кластер 7, `npm-module.mdc`), бо
+#    `isStorybookRoot()` @7n/test читає саме той файл, не кореневий package.json.
+#    `@storybook/addon-vitest` — виняток із цього правила: це test-tooling (плагін
+#    vitest-конфіга), а не Storybook-identity-маркер, тож root, а не npm/package.json.
 #
 # Перевірки, які потребують FS / cross-file контексту, лишаються у JS.
 package bun.package_json
@@ -50,7 +59,27 @@ deny contains msg if {
 # @stryker-mutator/core — обов'язковий exact-pin peer vitest-runner@9+ (раніше тягнувся транзитивно)
 # @7n/test — оркестратор `coverage` (npx @7n/test coverage); devDependency, щоб npx резолвив
 # локально без мережевого fetch щоразу.
-allowed_root_test_deps := {"vitest", "@vitest/coverage-v8", "@stryker-mutator/vitest-runner", "@stryker-mutator/core", "@playwright/test", "@7n/test"}
+# @vitest/browser + playwright — провайдер browser-mode для named vitest project
+# "storybook" (канон Storybook кластер 5: лише chromium, PR — швидкий
+# --project=storybook). `playwright` (не `@playwright/test`) — сирий driver, який
+# @vitest/browser використовує як provider; `@playwright/test` лишається окремо для
+# змістовних E2E-сценаріїв (n-vue.mdc).
+# @storybook/addon-vitest — постачає `storybookTest` для vitest-плагіна в канонічному
+# vitest.config named-проекту "storybook" (той самий канон Storybook кластер 5); версія
+# з лінійки Storybook 9.x (узгоджена з `storybook`@9.1.10, запіненим у
+# npm_package_json.rego) — allowlist тут за іменем, точний пінінг версії root-tooling
+# не робимо (на відміну від Storybook-identity-пакетів у npm/package.json).
+allowed_root_test_deps := {
+	"vitest",
+	"@vitest/coverage-v8",
+	"@vitest/browser",
+	"@stryker-mutator/vitest-runner",
+	"@stryker-mutator/core",
+	"@playwright/test",
+	"playwright",
+	"@storybook/addon-vitest",
+	"@7n/test",
+}
 
 allowed_root_dev_dependency(name) if {
 	startswith(name, "@nitra/")

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

@@ -16,10 +16,13 @@ Rego-пакет: `npm-module.npm_package_json`
 - Обовʼязкове, має бути непорожнім масивом.
 - Subset-of перевірка: кожне значення з канонічного сніпету має бути присутнє у `files`. За замовчуванням — `"types"` обовʼязковий.
 
-**Поле `devDependencies`** (inverse-pattern, логіка в rego):
+**Поле `devDependencies`** (inverse-pattern + Storybook-виняток, логіка в rego):
 
 - Не публікуються користувачам пакета — має бути відсутнє або порожнє `{}`.
-- Наявність будь-яких devDeps → deny з переліком залежностей. Dev-інструментарій переноситься у кореневий `package.json`; CLI-тули, які пакет спавнить через `bunx` у репозиторіях-споживачах (пінінг версій), — у `dependencies` (кореневе bun-правило `package_json` такі пакети в root devDeps не пускає).
+- **Виняток — канонічні Storybook-пакети** (канон Storybook, кластер 7 Governance: `docs/adr/канон-storybook-для-vue-компонентних-бібліотек.md`): `storybook`, `@storybook/vue3-vite`, `@storybook/vue3`, `msw`, `msw-storybook-addon` дозволені як devDeps саме тут, у `npm/package.json` консюмер-пакета — **не** в кореневому `package.json`. Обґрунтування: майбутній `isStorybookRoot()` у `@7n/test` читає саме цей файл, щоб визначити Storybook-скоуп workspace-пакета, тож маркер-пакети мають бути видимі тут, а не в кореневих tooling-deps. Версія кожного канонічного пакета зафіксована точно (map `storybook_canon_dev_deps` у rego) — присутність пакета з іншою версією теж deny (окреме повідомлення, не плутати з allowlist-забороною).
+- Будь-який інший devDep (не з канонічного Storybook-списку) → deny з переліком імен. Dev-інструментарій переноситься у кореневий `package.json`; CLI-тули, які пакет спавнить через `bunx` у репозиторіях-споживачах (пінінг версій), — у `dependencies` (кореневе bun-правило `package_json` такі пакети в root devDeps не пускає).
+
+Канон Storybook-devDeps та їхні версії — static map у `npm_package_json.rego` (не template-driven: це опційний allowlist, а не mandatory-presence дані, тож генеричний T0-fix-writer цього concern-а їх у кожен `package.json` не мерджить — див. коментар на початку rego-файлу).
 
 Канонічний сніпет `files`: [package.json.snippet.json](./template/package.json.snippet.json)
 
@@ -50,8 +53,20 @@ FS-перевірки (наявність файлу зі шляху `types`, с
 { "files": ["bin", "mdc"] }
 ```
 
-✗ Неправильно — наявні `devDependencies`:
+✗ Неправильно — наявні `devDependencies`, не з канонічного Storybook-списку:
 
 ```json
 { "devDependencies": { "@7n/rules": "^1.0.0" } }
 ```
+
+✓ Правильно — канонічний Storybook-devDep із зафіксованою версією (канон Storybook):
+
+```json
+{ "devDependencies": { "storybook": "9.1.10" } }
+```
+
+✗ Неправильно — Storybook-devDep присутній, але версія не збігається з каноном:
+
+```json
+{ "devDependencies": { "storybook": "8.0.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()
+}