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

package/rules/storybook/vitest-config/docs/main.md

@@ -0,0 +1,71 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/vitest-config/main.mjs
+docgen:
+  crc: 543716c9
+  model: openai-codex/gpt-5.4-mini
+  score: 85
+  issues: internal-name:detectStoriesGlob,anchor-miss:(vitest-config.mdc),judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Описує поведінку, за якою визначаються канонічні `vitest.config.*`, пов’язаний Stryker-конфіг, а також наявність і придатність `unit` та `storybook`-проєктів у пакеті. Для цього використовуються експортовані константи-рядки `REASON_VITEST_CONFIG_MISSING="vitest-config-missing"`, `REASON_STRYKER_CONFIG_MISSING="stryker-config-missing"`, `REASON_CONFIG_UNRESOLVABLE="vitest-config-unresolvable"`, `REASON_PROJECTS_DYNAMIC="projects-dynamic"`, `REASON_UNIT_PROJECT_MISSING="unit-project-missing"`, `REASON_STORYBOOK_PROJECT_MISSING="storybook-project-missing"`, `REASON_STORYBOOK_PROJECT_MARKER_MISSING="storybook-project-marker-missing"`, а повідомлення про такі стани передаються через маркери `vitest-config.mdc`.
+
+## Поведінка
+
+- `VITEST_CONFIG_NAMES` — задає канонічний пріоритет імен `vitest.config.*` для пошуку конфіга.
+- `STORYBOOK_TEST_IMPORT` — містить обов’язковий import для резолву `storybookTest`.
+- `REASON_VITEST_CONFIG_MISSING` — причина, коли в пакеті немає `vitest.config.*`.
+- `REASON_STRYKER_CONFIG_MISSING` — причина, коли відсутній ізольований `vitest.stryker.config.*`.
+- `REASON_CONFIG_UNRESOLVABLE` — причина, коли vitest-конфіг не вдається розпарсити або знайти в ньому `test`-блок.
+- `REASON_PROJECTS_DYNAMIC` — причина, коли `test.projects` не є статичним масивом.
+- `REASON_UNIT_PROJECT_MISSING` — причина, коли в `test.projects` немає `unit`.
+- `REASON_STORYBOOK_PROJECT_MISSING` — причина, коли в `test.projects` немає `storybook`.
+- `REASON_STORYBOOK_PROJECT_MARKER_MISSING` — причина, коли `storybook`-проєкт не має канонічних маркерів.
+- `CHROMIUM_RE` — маркує наявність chromium-інстансу в `storybook`-проєкті.
+- `BROWSER_KEY_RE` — маркує browser-mode в `storybook`-проєкті.
+- `STORIES_RE` — маркує stories-glob у `storybook`-проєкті.
+- `WHITESPACE_ONLY_RE` — визначає рядок, що складається лише з whitespace.
+- `LEADING_COMMA_RE` — визначає фрагмент, що починається з коми з можливим whitespace.
+- `resolveVitestConfigPath` — знаходить наявний `vitest.config.*` у корені пакета або повертає `null`.
+- `resolveViteConfigName` — повертає ім’я доступного `vite.config.*` для пакета, а якщо його немає — `vite.config.js`.
+- `strykerConfigPathFor` — будує шлях до поруч розташованого `vitest.stryker.config.*` з тим самим розширенням.
+- `storiesGlobForVitestConfig` — повертає stories-glob у вигляді, придатному для vitest-конфіга в корені пакета.
+- `parseModule` — парсить JS/TS модуль і повертає AST з діагностикою.
+- `findTestObject` — знаходить у дереві AST `test`-об’єкт незалежно від обгорток конфігурації.
+- `findProperty` — знаходить у об’єкті property за іменем.
+- `classifyProjects` — визначає, чи є в `test.projects` `unit`, і витягає зріз `storybook`-запису для перевірки маркерів.
+- `lint` — перевіряє всі пакети у скоупі на канонічний vitest-конфіг для `unit+storybook` і наявність ізольованого `vitest.stryker.config.*`, повідомляючи про порушення через маркери `vitest-config.mdc`.
+
+## Публічний API
+
+- STORYBOOK_TEST_IMPORT — Import, який має бути присутній у файлі, щоб `storybookTest(...)` резолвився.
+- resolveVitestConfigPath — Резолвить абсолютний шлях наявного `vitest.config.*` пакета (перший знайдений
+за пріоритетом {@link VITEST_CONFIG_NAMES}), або `null` якщо жодного немає.
+- resolveViteConfigName — Резолвить ім'я `vite.config.*` пакета для import-шляху в baseline-шаблонах
+(той самий файл, що й `viteFinal` у `.storybook/main.js`). Пакет у скоупі
+гарантовано має один із них (`scope/main.mjs#hasStandardBuild`).
+- strykerConfigPathFor — Шлях до ізольованого `vitest.stryker.config.*` — той самий каталог і
+розширення, що й основний vitest-конфіг пакета.
+- storiesGlobForVitestConfig — Stories-glob для vitest-конфіга пакета (на відміну від `detectStoriesGlob`
+scaffold-концерна — той повертає шлях відносно `.storybook/`, тут vitest-конфіг
+лежить у корені пакета, тож префікс `../` треба зняти).
+- parseModule — Парсить JS/TS файл через oxc-parser з обраним lang за розширенням.
+- findTestObject — Шукає перший `ObjectExpression` у дереві AST, що має property `test` зі
+значенням-`ObjectExpression` — незалежно від того, чи огорнутий він у
+`defineConfig(...)`/`mergeConfig(...)`, чи це простий об'єкт (стійко до
+варіацій testing.mdc-канону).
+- findProperty — Шукає property `name` у `ObjectExpression`.
+- classifyProjects — Класифікує елементи масиву `test.projects`: чи є `unit`-проєкт, і
+source-зріз елемента `storybook`-проєкту (для marker-перевірки).
+- lint — Перевіряє канонічний vitest-конфіг (unit+storybook projects) і наявність
+ізольованого `vitest.stryker.config` для всіх пакетів у скоупі Storybook.
+Надішли, будь ласка, файл або вміст коду, до якого треба написати документацію.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/storybook/vitest-config/fix-vitest-config.mjs

@@ -0,0 +1,356 @@
+/**
+ * T0-autofix для concern-а `storybook/vitest-config`: детерміноване приведення
+ * vitest-конфіга Vue-компонентної бібліотеки у скоупі Storybook до канону
+ * `test.projects` (`unit`+`storybook`, browser-mode лише chromium) і генерація
+ * ізольованого `vitest.stryker.config.*` (ADR Кластер 5).
+ *
+ * Стратегія — та сама, що й `test/stryker_config/fix-stryker_config.mjs`:
+ * читання/аналіз (oxc-parser) і запис лише тут; detector (`main.mjs`)
+ * read-only. Для вже наявного vitest-конфіга — точкові string-splice-и
+ * (insert-only), щоб НЕ переписати форматування/коментарі решти файлу;
+ * після splice — повторний parse і відкат при невалідному результаті.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  classifyProjects,
+  findProperty,
+  findTestObject,
+  LEADING_COMMA_RE,
+  parseModule,
+  PLAYWRIGHT_PROVIDER_IMPORT,
+  REASON_STORYBOOK_PROJECT_MISSING,
+  REASON_STRYKER_CONFIG_MISSING,
+  REASON_UNIT_PROJECT_MISSING,
+  REASON_VITEST_CONFIG_MISSING,
+  resolveViteConfigName,
+  resolveVitestConfigPath,
+  storiesGlobForVitestConfig,
+  STORYBOOK_TEST_IMPORT,
+  strykerConfigPathFor,
+  WHITESPACE_ONLY_RE
+} from './main.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = join(HERE, 'template')
+const STORIES_GLOB_TOKEN = '__STORYBOOK_STORIES_GLOB__'
+const VITE_CONFIG_IMPORT_TOKEN = '__VITE_CONFIG_IMPORT__'
+
+const TRIGGER_REASONS = new Set([
+  REASON_VITEST_CONFIG_MISSING,
+  REASON_STRYKER_CONFIG_MISSING,
+  REASON_UNIT_PROJECT_MISSING,
+  REASON_STORYBOOK_PROJECT_MISSING
+])
+
+/**
+ * Витягує вміст `export default {...}` із template-модуля (сам файл — валідний
+ * модуль лише для JS-лінту цього репо; тут потрібен саме літерал об'єкта).
+ * @param {string} absTemplatePath абсолютний шлях template-файлу
+ * @returns {Promise<string>} текст `ObjectExpression` (без `export default`)
+ */
+async function readTemplateExportedObject(absTemplatePath) {
+  const src = await readFile(absTemplatePath, 'utf8')
+  const parsed = parseModule(absTemplatePath, src)
+  const exportDecl = parsed.program.body.find(n => n.type === 'ExportDefaultDeclaration')
+  const decl = exportDecl?.declaration
+  if (!decl) throw new Error(`template без export default: ${absTemplatePath}`)
+  return src.slice(decl.start, decl.end)
+}
+
+/**
+ * Відступ properties/elements за рядком останнього — дефолт 2 пробіли.
+ * @param {string} src вихідний текст
+ * @param {Array<{start: number}>} items properties/elements контейнера
+ * @param {string} [fallback] дефолтний відступ
+ * @returns {string} рядок-відступ
+ */
+function detectIndent(src, items, fallback = '  ') {
+  if (items.length > 0) {
+    const start = items.at(-1).start
+    const lineStart = src.lastIndexOf('\n', start - 1) + 1
+    const ws = src.slice(lineStart, start)
+    if (WHITESPACE_ONLY_RE.test(ws)) return ws
+  }
+  return fallback
+}
+
+/**
+ * Відступає всі рядки, крім першого (перший отримує відступ ззовні, при
+ * розміщенні у вставці).
+ * @param {string} text багаторядковий текст (перший рядок — база нульового відступу)
+ * @param {string} indent відступ для рядків 2..N
+ * @returns {string} відступлений текст
+ */
+function indentBlock(text, indent) {
+  return text
+    .split('\n')
+    .map((line, i) => (i === 0 ? line : `${indent}${line}`))
+    .join('\n')
+}
+
+/**
+ * Застосовує точкові вставки до тексту (сортує за спаданням `pos`, щоб раніші
+ * offsets лишались валідними після вставок справа).
+ * @param {string} src вихідний текст
+ * @param {Array<{pos: number, text: string}>} edits вставки
+ * @returns {string} новий текст
+ */
+function applyEdits(src, edits) {
+  let out = src
+  for (const e of edits.toSorted((a, b) => b.pos - a.pos)) {
+    out = out.slice(0, e.pos) + e.text + out.slice(e.pos)
+  }
+  return out
+}
+
+/**
+ * Вставка нової property (`projects: [...]`) в об'єкт-літерал перед `}`.
+ * Поважає trailing comma останньої property, коректно обробляє порожній об'єкт.
+ * @param {string} src вихідний текст
+ * @param {object} obj ObjectExpression node (`test`-блок)
+ * @param {string} indent відступ properties
+ * @param {string} propLine рядок нової property (без відступу й коми)
+ * @returns {{pos: number, text: string}} одна точкова вставка
+ */
+function newPropertyEdit(src, obj, indent, propLine) {
+  const props = obj.properties
+  if (props.length === 0) {
+    return { pos: obj.start + 1, text: `\n${indent}${propLine}\n` }
+  }
+  const lastProp = props.at(-1)
+  const tail = src.slice(lastProp.end, obj.end - 1)
+  const commaMatch = tail.match(LEADING_COMMA_RE)
+  if (commaMatch) {
+    return { pos: lastProp.end + commaMatch[0].length, text: `\n${indent}${propLine}` }
+  }
+  return { pos: lastProp.end, text: `,\n${indent}${propLine}` }
+}
+
+/**
+ * Вставка елементів перед закривальною `]` масиву — універсально для порожнього
+ * й непорожнього масиву (комою керує наявність елементів).
+ * @param {object} arr ArrayExpression node
+ * @param {string} indent відступ рядка масиву (властивості, що його містить)
+ * @param {string[]} entries нові елементи (кожен — багаторядковий об'єкт-літерал)
+ * @returns {{pos: number, text: string}} одна точкова вставка
+ */
+function arrayInsertBeforeClose(arr, indent, entries) {
+  const itemIndent = `${indent}  `
+  const body = entries.map(e => indentBlock(e, itemIndent)).join(`,\n${itemIndent}`)
+  const prefix = arr.elements.length > 0 ? ',\n' : '\n'
+  return { pos: arr.end - 1, text: `${prefix}${itemIndent}${body}\n${indent}` }
+}
+
+/**
+ * Гарантує наявність import-у на самому початку файлу — ESM толерантний до
+ * порядку import-ів, тож prepend завжди синтаксично коректний незалежно від
+ * наявних import-ів.
+ * @param {string} src вихідний текст
+ * @param {string} marker підрядок, наявність якого означає "import уже є"
+ * @param {string} importLine рядок import-у (з `\n` наприкінці), що вставляється, якщо `marker` відсутній
+ * @returns {string} текст з гарантованим import-ом
+ */
+function ensureImport(src, marker, importLine) {
+  return src.includes(marker) ? src : `${importLine}${src}`
+}
+
+/**
+ * Гарантує наявність обох import-ів, потрібних новому storybook-запису
+ * `test.projects`: `storybookTest` (`@storybook/addon-vitest/vitest-plugin`) і
+ * `playwright`-provider factory (`@vitest/browser-playwright`, vitest@^4 —
+ * рядкове API `provider: 'playwright'` застаріле).
+ * @param {string} src вихідний текст
+ * @returns {string} текст з гарантованими import-ами
+ */
+function ensureStorybookEntryImports(src) {
+  const withStorybookTest = ensureImport(src, '@storybook/addon-vitest/vitest-plugin', STORYBOOK_TEST_IMPORT)
+  return ensureImport(withStorybookTest, '@vitest/browser-playwright', PLAYWRIGHT_PROVIDER_IMPORT)
+}
+
+/**
+ * Будує рядок нової property `projects: [<unit>, <storybook>]` для вставки в
+ * порожній test-блок (де `projects` ще немає взагалі).
+ * @param {string} indent відступ properties test-блоку
+ * @param {string} unitEntry текст unit-проєкту (`ObjectExpression`, база нульового відступу)
+ * @param {string} storybookEntry текст storybook-проєкту (те саме)
+ * @returns {string} рядок `projects: [...]` (без завершальної коми)
+ */
+function buildProjectsPropertyLine(indent, unitEntry, storybookEntry) {
+  const itemIndent = `${indent}  `
+  return `projects: [\n${itemIndent}${indentBlock(unitEntry, itemIndent)},\n${itemIndent}${indentBlock(storybookEntry, itemIndent)}\n${indent}]`
+}
+
+/**
+ * Обчислює план правки для наявного `test.projects` (нова property, або
+ * відсутні unit/storybook-записи в наявний масив). `null` — augment
+ * неможливий/не потрібен (dynamic-масив або вже канонічно).
+ * @param {string} src вихідний текст vitest-конфіга
+ * @param {object} testObj `test`-ObjectExpression node
+ * @param {string} unitEntry текст unit-проєкту
+ * @param {string} storybookEntry текст storybook-проєкту
+ * @returns {{edit: {pos: number, text: string}, needsImport: boolean} | null} план правки
+ */
+function planProjectsEdit(src, testObj, unitEntry, storybookEntry) {
+  const indent = detectIndent(src, testObj.properties)
+  const projectsProp = findProperty(testObj, 'projects')
+
+  if (projectsProp) {
+    if (projectsProp.value?.type !== 'ArrayExpression') return null // dynamic — projects-dynamic вже у детекторі
+    const { hasUnit, storybookSlice } = classifyProjects(src, projectsProp.value)
+    const missing = []
+    if (!hasUnit) missing.push(unitEntry)
+    let needsImport = false
+    if (!storybookSlice) {
+      missing.push(storybookEntry)
+      needsImport = true
+    }
+    if (missing.length === 0) return null
+    return { edit: arrayInsertBeforeClose(projectsProp.value, indent, missing), needsImport }
+  }
+
+  const propLine = buildProjectsPropertyLine(indent, unitEntry, storybookEntry)
+  return { edit: newPropertyEdit(src, testObj, indent, propLine), needsImport: true }
+}
+
+/**
+ * Обчислює новий вміст наявного vitest-конфіга: дописує `projects`
+ * (нову property або відсутні unit/storybook-записи в наявний масив).
+ * `null` — правку застосовувати не треба (усе вже канонічно).
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @param {string} vitestConfigPath абсолютний шлях vitest-конфіга
+ * @returns {Promise<string | null>} новий вміст файлу або null
+ */
+async function computeVitestConfigAugment(absPkgDir, vitestConfigPath) {
+  const src = await readFile(vitestConfigPath, 'utf8')
+  const parsed = parseModule(vitestConfigPath, src)
+  if (parsed.errors?.length) return null
+  const testObj = findTestObject(parsed.program)
+  if (!testObj) return null
+
+  const storiesGlob = storiesGlobForVitestConfig(absPkgDir)
+  const unitEntry = await readTemplateExportedObject(join(TEMPLATE_DIR, 'unit-project-entry.js'))
+  const storybookEntryRaw = await readTemplateExportedObject(join(TEMPLATE_DIR, 'storybook-project-entry.js'))
+  const storybookEntry = storybookEntryRaw.split(STORIES_GLOB_TOKEN).join(storiesGlob)
+
+  const plan = planProjectsEdit(src, testObj, unitEntry, storybookEntry)
+  if (!plan) return null
+
+  let next = applyEdits(src, [plan.edit])
+  if (plan.needsImport) next = ensureStorybookEntryImports(next)
+
+  // Safety: результат має компілюватися; інакше не пишемо (fail-closed, як у test/stryker_config).
+  let recheck
+  try {
+    recheck = parseModule(vitestConfigPath, next)
+  } catch {
+    return null
+  }
+  if (recheck.errors?.length) return null
+
+  return next === src ? null : next
+}
+
+/**
+ * Генерує повністю новий `vitest.config.mjs` (unit+storybook projects) для
+ * пакета без жодного наявного vitest-конфіга. Експортовано — переюз у
+ * `adopt/main.mjs` (генерація лише для повністю відсутніх файлів).
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @returns {Promise<{ path: string, content: string }>} шлях і вміст нового файлу
+ */
+export async function buildFreshVitestConfig(absPkgDir) {
+  const template = await readFile(join(TEMPLATE_DIR, 'vitest.config.baseline.mjs'), 'utf8')
+  const storiesGlob = storiesGlobForVitestConfig(absPkgDir)
+  const viteConfigName = resolveViteConfigName(absPkgDir)
+  const content = template
+    .split(STORIES_GLOB_TOKEN)
+    .join(storiesGlob)
+    .split(VITE_CONFIG_IMPORT_TOKEN)
+    .join(viteConfigName)
+  return { path: join(absPkgDir, 'vitest.config.mjs'), content }
+}
+
+/**
+ * Генерує ізольований `vitest.stryker.config.*` (той самий basename/ext що
+ * й основний vitest-конфіг пакета) з canonical baseline-шаблону. Експортовано —
+ * переюз у `adopt/main.mjs`.
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @returns {Promise<string>} вміст нового файлу
+ */
+export async function buildStrykerConfig(absPkgDir) {
+  const template = await readFile(join(TEMPLATE_DIR, 'vitest.stryker.config.baseline.mjs'), 'utf8')
+  const viteConfigName = resolveViteConfigName(absPkgDir)
+  return template.split(VITE_CONFIG_IMPORT_TOKEN).join(viteConfigName)
+}
+
+/**
+ * Обробляє один пакет (rootDir) — обчислює й пише всі потрібні зміни:
+ * fresh vitest.config.mjs (якщо був відсутній), augment наявного конфіга,
+ * генерацію ізольованого vitest.stryker.config.*.
+ * @param {string} rootDir root dir пакета
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').FixContext} ctx fix-контекст
+ * @returns {Promise<string[]>} абсолютні шляхи змінених файлів
+ */
+async function fixOnePackage(rootDir, absPkgDir, ctx) {
+  const touchedFiles = []
+  const existingVitestConfigPath = resolveVitestConfigPath(absPkgDir)
+  let vitestConfigPath = existingVitestConfigPath
+
+  if (existingVitestConfigPath) {
+    const augmented = await computeVitestConfigAugment(absPkgDir, existingVitestConfigPath)
+    if (augmented !== null) {
+      ctx.recordWrite?.(existingVitestConfigPath)
+      await writeFile(existingVitestConfigPath, augmented, 'utf8')
+      touchedFiles.push(existingVitestConfigPath)
+    }
+  } else {
+    const fresh = await buildFreshVitestConfig(absPkgDir)
+    ctx.recordWrite?.(fresh.path)
+    await writeFile(fresh.path, fresh.content, 'utf8')
+    touchedFiles.push(fresh.path)
+    vitestConfigPath = fresh.path
+  }
+
+  const strykerPath = strykerConfigPathFor(vitestConfigPath)
+  if (!existsSync(strykerPath)) {
+    const content = await buildStrykerConfig(absPkgDir)
+    ctx.recordWrite?.(strykerPath)
+    await writeFile(strykerPath, content, 'utf8')
+    touchedFiles.push(strykerPath)
+  }
+
+  return touchedFiles
+}
+
+/** @type {import('@7n/rules/scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'storybook-vitest-config-fix',
+    test: violations => violations.some(v => TRIGGER_REASONS.has(v.reason)),
+    apply: async (violations, ctx) => {
+      const rootDirs = new Map()
+      for (const v of violations) {
+        if (!TRIGGER_REASONS.has(v.reason)) continue
+        const rootDir = v.data?.rootDir
+        if (typeof rootDir !== 'string') continue
+        if (!rootDirs.has(rootDir)) {
+          rootDirs.set(rootDir, rootDir === '.' ? ctx.cwd : join(ctx.cwd, rootDir))
+        }
+      }
+
+      const touchedFiles = []
+      for (const [rootDir, absPkgDir] of rootDirs) {
+        const files = await fixOnePackage(rootDir, absPkgDir, ctx)
+        touchedFiles.push(...files)
+      }
+
+      return touchedFiles.length > 0
+        ? { touchedFiles, message: `vitest-config storybook-канон: ${touchedFiles.join(', ')}` }
+        : { touchedFiles: [] }
+    }
+  }
+]