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

package/rules/storybook/scope/main.mjs

@@ -0,0 +1,202 @@
+/** @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 { loadCursorIgnorePaths } from '@7n/rules/scripts/lib/load-cursor-config.mjs'
+import { walkDir } from '@7n/rules/scripts/utils/walkDir.mjs'
+import { getMonorepoPackageRootDirs } from '@7n/rules/scripts/lib/workspaces.mjs'
+import { isVueComponentLibraryPkg } from '../../vue/packages/main.mjs'
+
+const CONFIG_FILE = '.n-rules.json'
+const LEGACY_CONFIG_FILE = '.n-cursor.json'
+const VITE_CONFIG_FILES = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs']
+
+/** Поріг кількості `.vue`-файлів для скоупу канону Storybook (ADR Кластер 1). */
+export const VUE_FILE_THRESHOLD = 3
+
+/**
+ * @typedef {object} InScopePackage
+ * @property {string} rootDir відносний (posix) корінь пакета, `.` для кореня монорепо
+ * @property {string} absDir абсолютний шлях кореня пакета
+ * @property {Record<string, unknown>} pkg розпарсений `package.json` пакета
+ * @property {number} vueFileCount кількість знайдених `.vue`-файлів
+ */
+
+/**
+ * Читає `storybook.optOut` з `.n-rules.json` (fallback — legacy `.n-cursor.json`). Толерантно до
+ * відсутнього файлу/поля/невалідного JSON — повертає порожній масив (open-by-default, як
+ * `read-n-rules-config-lite.mjs`). Значення — root dir пакетів (`.` для кореня, `packages/ui` тощо),
+ * той самий формат, що повертає `getMonorepoPackageRootDirs`.
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @returns {Promise<string[]>} перелік opt-out root dir-ів
+ */
+export async function readStorybookOptOut(cwd) {
+  let file = join(cwd, CONFIG_FILE)
+  if (!existsSync(file)) file = join(cwd, LEGACY_CONFIG_FILE)
+  if (!existsSync(file)) return []
+  let raw
+  try {
+    raw = JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return []
+  }
+  const list = raw?.storybook?.optOut
+  if (!Array.isArray(list)) return []
+  return list.filter(v => typeof v === 'string' && v.trim().length > 0)
+}
+
+/**
+ * Читає прапорець хвилі 2 `storybook.detectApps` з `.n-rules.json`. За замовчуванням `false` —
+ * детекція app-проєктів (`vue` у dependencies + `src/pages/`) лишається відкритим питанням ADR
+ * і не впливає на скоуп, доки консюмер-репо не увімкне прапорець явно.
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @returns {Promise<boolean>} true, якщо app-проєкти теж треба зібрати у скоуп
+ */
+export async function readDetectAppsFlag(cwd) {
+  let file = join(cwd, CONFIG_FILE)
+  if (!existsSync(file)) file = join(cwd, LEGACY_CONFIG_FILE)
+  if (!existsSync(file)) return false
+  let raw
+  try {
+    raw = JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return false
+  }
+  return raw?.storybook?.detectApps === true
+}
+
+/**
+ * Рахує `.vue`-файли в дереві пакета (поважає `.gitignore` й `ignore` з `.n-rules.json` через
+ * `walkDir`/`ignorePaths` — той самий обхід, що й `vue/packages`).
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @param {string[]} ignorePaths абсолютні шляхи, повністю виключені з обходу
+ * @returns {Promise<number>} кількість `.vue`-файлів
+ */
+export async function countVueFiles(absPkgDir, ignorePaths) {
+  let count = 0
+  await walkDir(
+    absPkgDir,
+    absPath => {
+      if (absPath.endsWith('.vue')) count += 1
+    },
+    ignorePaths
+  )
+  return count
+}
+
+/**
+ * Чи має пакет "стандартний" build — розпізнаваний `vite.config.{js,ts,mjs}` у корені пакета.
+ * Канонічний `.storybook/main.js` спирається саме на цей файл (`viteFinal` мерджить його
+ * плагіни) — без нього автоматичний скафолд неможливий, і пакет пропускається мовчки
+ * (ADR Кластер 1: "skip пакетів із нестандартним build").
+ * @param {string} absPkgDir абсолютний шлях кореня пакета
+ * @returns {boolean} true, якщо знайдено відомий `vite.config.*`
+ */
+export function hasStandardBuild(absPkgDir) {
+  return VITE_CONFIG_FILES.some(f => existsSync(join(absPkgDir, f)))
+}
+
+/**
+ * Чи є пакет app-проєктом (не бібліотекою) для хвилі 2: `vue` у `dependencies` (не лише
+ * `peerDependencies`) і не бібліотека компонентів. Реалізовано зараз (щоб не переписувати
+ * модуль пізніше), але результат впливає на скоуп лише за прапорця `storybook.detectApps`.
+ * @param {{ dependencies?: Record<string, unknown>, peerDependencies?: Record<string, unknown> }} pkg розпарсений package.json
+ * @returns {boolean} true — app-проєкт (кандидат хвилі 2)
+ */
+export function isVueAppPkg(pkg) {
+  return Boolean(pkg?.dependencies?.vue) && !isVueComponentLibraryPkg(pkg)
+}
+
+/**
+ * Перевіряє один workspace-корінь на відповідність предикату скоупу (бібліотека чи app) і,
+ * за успіху, повертає його `InScopePackage`-запис.
+ * @param {string} rootDir відносний корінь пакета
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @param {(pkg: Record<string, unknown>) => boolean} matches предикат скоупу (бібліотека/app)
+ * @param {string[]} ignorePaths абсолютні шляхи, повністю виключені з обходу
+ * @returns {Promise<InScopePackage|null>} запис пакета або `null`, якщо поза скоупом
+ */
+async function evaluateCandidate(rootDir, cwd, matches, ignorePaths) {
+  const absDir = rootDir === '.' ? cwd : join(cwd, rootDir)
+  const pkgPath = join(absDir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  let pkg
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+  } catch {
+    return null
+  }
+  if (!matches(pkg)) return null
+  if (!hasStandardBuild(absDir)) return null
+  const vueFileCount = await countVueFiles(absDir, ignorePaths)
+  if (vueFileCount < VUE_FILE_THRESHOLD) return null
+  return { rootDir, absDir, pkg, vueFileCount }
+}
+
+/**
+ * Збирає workspace-пакети у скоупі канону Storybook хвилі 1: Vue-компонентна бібліотека
+ * (`vue` у `peerDependencies`, маркер `isVueComponentLibraryPkg` — той самий, що й `vue.mdc`)
+ * з не менше {@link VUE_FILE_THRESHOLD} `.vue`-файлами, без `storybook.optOut`, зі
+ * стандартним build (`vite.config.*`). Хвиля 2 (app-проєкти) додається лише за явного
+ * прапорця `storybook.detectApps` у `.n-rules.json`.
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @returns {Promise<InScopePackage[]>} пакети у скоупі
+ */
+export async function collectInScopeVuePackages(cwd) {
+  const roots = await getMonorepoPackageRootDirs(cwd)
+  const ignorePaths = await loadCursorIgnorePaths(cwd)
+  const optOut = new Set(await readStorybookOptOut(cwd))
+  const candidateRoots = roots.filter(r => !optOut.has(r))
+
+  /** @type {InScopePackage[]} */
+  const result = []
+  for (const rootDir of candidateRoots) {
+    const found = await evaluateCandidate(rootDir, cwd, isVueComponentLibraryPkg, ignorePaths)
+    if (found) result.push(found)
+  }
+
+  if (await readDetectAppsFlag(cwd)) {
+    for (const rootDir of candidateRoots) {
+      if (result.some(r => r.rootDir === rootDir)) continue
+      const absDir = rootDir === '.' ? cwd : join(cwd, rootDir)
+      if (!existsSync(join(absDir, 'src/pages'))) continue
+      const found = await evaluateCandidate(rootDir, cwd, isVueAppPkg, ignorePaths)
+      if (found) result.push(found)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Self-check конфігурації: `.n-rules.json` → `storybook.optOut` не має посилатись на
+ * неіснуючі workspace-пакети (застаріле налаштування — пакет перейменували/видалили, а
+ * opt-out лишився). Сама детекція скоупу (поріг, build, app-проєкти) — pure-функції вище,
+ * покриті тестами напряму; тут лише конфіг-гігієна.
+ * @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 optOut = await readStorybookOptOut(cwd)
+  if (optOut.length === 0) {
+    reporter.pass('storybook: storybook.optOut порожній або не заданий')
+    return reporter.result()
+  }
+
+  const roots = new Set(await getMonorepoPackageRootDirs(cwd))
+  for (const rootDir of optOut) {
+    if (!roots.has(rootDir)) {
+      reporter.fail(
+        `.n-rules.json storybook.optOut містить '${rootDir}' — такого workspace-пакета немає (застаріле opt-out, storybook.mdc)`,
+        'stale-opt-out'
+      )
+    }
+  }
+
+  return reporter.result()
+}

package/rules/storybook/vitest-config/concern.json

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

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: fix-vitest-config.mjs
+resource: plugins/lang-js/rules/storybook/vitest-config/fix-vitest-config.mjs
+docgen:
+  crc: b3961bc2
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл детерміновано приводить `vitest.config.mjs` у Vue-компонентних пакетах із Storybook до канону `test.projects`: окремі проєкти `unit` і `storybook`, а browser-mode обмежує лише `chromium`. Для Stryker він генерує ізольований `vitest.stryker.config.*` у межах того ж пакета, згідно з підходом з `ADR Кластер 5`.
+
+Для вже наявного `vitest.config.mjs` зміни вносяться точковими `string-splice`-ами лише на вставку, щоб не переписувати решту форматування й коментарів; після цього конфіг повторно парситься, і зміни відкочуються, якщо результат невалідний. Логіка побудови покладена на `buildFreshVitestConfig`, `buildStrykerConfig` і `patterns`, а читання й аналіз виконуються через `oxc-parser`. Детектор `main.mjs` працює read-only, тоді як запис зосереджений у `fix-stryker_config.mjs`.
+
+## Поведінка
+
+- `buildFreshVitestConfig` — створює новий `vitest.config.mjs` для пакета з канонічним `test.projects` для `unit` і `storybook`, підставляє шлях до локального Vite-конфіга та сторінковий glob для Storybook.
+- `buildStrykerConfig` — генерує ізольований `vitest.stryker.config.*` на основі canonical baseline-шаблону для того самого пакета, підставляючи шлях до локального Vite-конфіга.
+- `patterns` — описує autofix-сценарій, який реагує на відсутній або неканонічний vitest-конфіг, доповнює наявний файл без переписування зайвого форматування та створює `vitest.stryker.config.*` у відповідному package root.
+
+## Публічний API
+
+- buildFreshVitestConfig — Генерує повністю новий `vitest.config.mjs` (unit+storybook projects) для
+пакета без жодного наявного vitest-конфіга. Експортовано — переюз у
+`adopt/main.mjs` (генерація лише для повністю відсутніх файлів).
+- buildStrykerConfig — Генерує ізольований `vitest.stryker.config.*` (той самий basename/ext що
+й основний vitest-конфіг пакета) з canonical baseline-шаблону. Експортовано —
+переюз у `adopt/main.mjs`.
+- patterns — повертає набір шаблонів, які використовуються для зіставлення й обробки відповідних випадків у коді
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

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

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

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

@@ -0,0 +1,72 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/storybook/vitest-config/main.mjs
+docgen:
+  crc: f5db98b8
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  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).