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

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+
+- doc-files: Vue SFC-екстрактор (`.vue` через optional peer `vue/compiler-sfc`) — props/emits/exposed як псевдо-експорти, слоти з `@slot`-коментарів шаблону, юніти зі зміщеними у файл офсетами
+
+### Fixed
+
+- doc-files: JSDoc-атрибуція експортів/юнітів через реальні AST-коментарі парсера (не regex по сирому тексту) — усуває false positive, коли '/**'-подібний текст трапляється всередині // -коментаря чи рядкового літералу
+
 ## [0.8.0] - 2026-07-20
 
 ### Added

package/doc-files/docs/extractors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: extractors.mjs
 resource: plugins/lang-js/doc-files/extractors.mjs
 docgen:
-  crc: 0519b5be
+  crc: ec2c4b59
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98

package/doc-files/docs/index.md

@@ -7,5 +7,6 @@ resource: plugins/lang-js/doc-files/
 | Файл                            | Тип       |
 | ------------------------------- | --------- |
 | [extractors.mjs](extractors.md) | JS Module |
+| [js-facts.mjs](js-facts.md)     | JS Module |
 | [units-js.mjs](units-js.md)     | JS Module |
 | [vue.mjs](vue.md)               | JS Module |

package/doc-files/docs/js-facts.md

@@ -0,0 +1,47 @@
+---
+type: JS Module
+title: js-facts.mjs
+resource: plugins/lang-js/doc-files/js-facts.mjs
+docgen:
+  crc: c0e84691
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Модуль формує поведінковий профіль для `parseJsDoc`, `extractFileHeader`, `precedingJsDoc`, `extractExports`, `extractImports`, `extractInternalSymbols`, `extractLocalSymbols` і `extractMarkers`: зчитує JSDoc, заголовок файлу, імпорти, експорти, локальні та внутрішні символи, щоб описувати публічну поверхню й службові частини коду. Під час обходу свідомо пропускає `.github`, `.git`, `node_modules`, `base/`, `ua/` і `.firebase`. Модуль звертається до мережі, використовує кешування в межах одного прогону та за окремих помилок повертає порожнє значення, зокрема `null`, замість винятку.
+
+## Поведінка
+
+- parseJsDoc — розбирає JSDoc у читабельний опис, окремо виділяє параметри й текст повернення.
+- extractFileHeader — бере провідний блок-коментар файлу як намір, якщо він стоїть на початку до будь-якого коду чи import.
+- precedingJsDoc — знаходить найближчий JSDoc-блок, що стоїть впритул перед потрібною позицією.
+- extractExports — збирає експортовані оголошення разом із пов’язаним JSDoc, щоб описати публічну поверхню модуля.
+- extractImports — розкладає імпорти на stdlib, npm та internal; внутрішні шляхи не змішує з зовнішніми.
+- extractInternalSymbols — витягує імена символів із внутрішніх імпортів, щоб їх не подавати як зовнішній API.
+- extractLocalSymbols — знаходить неекспортовані top-level функції й класи як службові елементи модуля.
+- extractMarkers — визначає поведінкові ознаки коду, зокрема мережеві звернення, кешування, обробку помилок, читання-only та свідомі пропуски шляхів `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.
+
+## Публічний API
+
+- parseJsDoc — Опис (без @-тегів) + параметри з `@param` як «name — опис».
+- extractFileHeader — Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом.
+- precedingJsDoc — Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
+`(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
+найближчий блок — без жадібного «перестрибування» через імпорти/код.
+- extractExports — Експорти + JSDoc, що безпосередньо передує кожному.
+- extractImports — Імпорти, класифіковані на stdlib / npm / internal.
+- extractInternalSymbols — Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати.
+- extractLocalSymbols — Імена top-level функцій/класів, які НЕ експортуються (службові помічники).
+Модель не має подавати їх як «публічні функції» у Поведінці/API (R6).
+Const-стрілки свідомо не ловимо — менше false-positive на змістовних константах.
+- extractMarkers — Поведінкові маркери — евристики регулярками.
+
+## Гарантії поведінки
+
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

package/doc-files/docs/units-js.md

@@ -3,9 +3,8 @@ type: JS Module
 title: units-js.mjs
 resource: plugins/lang-js/doc-files/units-js.mjs
 docgen:
-  crc: 9a13a64e
+  crc: d6ca02fb
   model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
   score: 100
   issues: judge:inaccurate:0.94
   judgeModel: openai-codex/gpt-5.4-mini

package/doc-files/extractors.mjs

@@ -1,6 +1,8 @@
 /** @see ./docs/extractors.md */
+import { parseProgramAndCommentsOrNull } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
 import { extractUnitsJs } from './units-js.mjs'
 import { extractFactsVue, extractUnitsVue } from './vue.mjs'
+import { jsDocCommentBefore } from './js-facts.mjs'
 
 /**
  * Мовний doc-files-екстрактор JS-екосистеми для конвеєра `@7n/rules`
@@ -36,8 +38,14 @@ const JSDOC_CLOSE_RE = /\*\/\s*$/
 const STAR_PREFIX_RE = /^\s*\*?\s?/
 const PARAM_LINE_RE = /^@param[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?\[?([\w.]{1,80})\]?[ \t]{0,8}(.{0,400})$/
 const RETURNS_LINE_RE = /^@returns?[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?(.{0,400})$/
-const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
-const PRECEDING_JSDOC_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+// `(?!\/)` одразу після відкриття — без нього glob-рядок на кшталт `'src/**/linux.rs'`
+// (символи `/`,`*`,`*`,`/`) читається як порожній коментар-відкриття `/**/`, і жадібний
+// пошук найближчого `*/` «протікає» аж до наступного РЕАЛЬНОГО закриття JSDoc, змішуючи
+// код між ними у `desc`. Справжній JSDoc ніколи не має `/` одразу після `/**`. Regex-фолбек
+// для випадків без `comments` від парсера (див. `jsDocCommentBefore` — надійніший шлях,
+// коли парсинг вдався, бо AST уже коректно розрізняє справжні коментарі й `//`-текст).
+const FILE_HEADER_RE = /^\s*\/\*\*(?!\/)([\s\S]*?)\*\//
+const PRECEDING_JSDOC_RE = /\/\*\*(?!\/)(?:(?!\*\/)[\s\S])*\*\/\s*$/
 const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+(\w+)/g
 // Top-level function/class декларації (колонка 0) — для R6: службові функції,
 // які не експортуються, не мають протікати у Поведінку/API як «публічні».
@@ -102,6 +110,63 @@ function cleanJsDoc(raw) {
     .trim()
 }
 
+// Заголовок `\@param`/`\@returns` із незакритим на тому ж рядку типом (`\@param {{`
+// на початку багаторядкового object-type). `.*` без `s`-прапора — навмисно: `l`
+// уже без `\n` (рядки з `text.split('\n')`), тож `.` природно зупиняється на межі рядка.
+const TAG_HEAD_RE = /^@(param|returns?)\b[ \t]*(\{.*)?$/
+
+/**
+ * @param {string} s текст
+ * @param {string} ch односимвольний рядок для підрахунку
+ * @returns {number} кількість входжень `ch` у `s`
+ */
+function countOccurrences(s, ch) {
+  return s.split(ch).length - 1
+}
+
+/**
+ * Просуває стан пропуску багаторядкового object-type (`\@param {{ ... }}`) на один
+ * рядок: рахує баланс дужок, і коли він сходиться в 0 — домальовує рядок як
+ * звичайний `\@param name опис`/`\@returns опис` (текст після останньої `}`).
+ * @param {{tag:'param'|'returns', depth:number}} braceSkip стан пропуску (мутується)
+ * @param {string} l поточний рядок
+ * @returns {{line:string|null}} `line:null` — рядок ще всередині типу (пропустити); інакше — реконструйований рядок
+ */
+function advanceBraceSkip(braceSkip, l) {
+  braceSkip.depth += countOccurrences(l, '{') - countOccurrences(l, '}')
+  if (braceSkip.depth > 0) return { line: null }
+  return { line: `@${braceSkip.tag} ${l.slice(l.lastIndexOf('}') + 1).trim()}` }
+}
+
+/**
+ * Виявляє старт багаторядкового `\@param {{`/`\@returns {{` (тип не закрився на
+ * цьому ж рядку — більше `{`, ніж `}`).
+ * @param {string} l поточний рядок
+ * @returns {{tag:'param'|'returns', depth:number}|null} стан пропуску або null, якщо не старт
+ */
+function detectMultilineTagStart(l) {
+  const tagHead = l.match(TAG_HEAD_RE)
+  if (!tagHead?.[2]) return null
+  const opens = countOccurrences(tagHead[2], '{')
+  const closes = countOccurrences(tagHead[2], '}')
+  if (opens <= closes) return null
+  return { tag: tagHead[1].startsWith('return') ? 'returns' : 'param', depth: opens - closes }
+}
+
+/**
+ * Дописує continuation-рядок (обгорнутий хвіст) до відповідного \@param/\@returns.
+ * @param {'returns'|{kind:'param', idx:number}} continuation активний тег
+ * @param {Array<{name:string, desc:string}>} params накопичені параметри (мутуються)
+ * @param {string} ret поточний текст `@returns`
+ * @param {string} tail новий текст для дописування
+ * @returns {string} оновлений `ret` (для `returns`; для `param` — вхідний `ret` без змін)
+ */
+function appendContinuation(continuation, params, ret, tail) {
+  if (continuation === 'returns') return `${ret} ${tail}`.trim()
+  params[continuation.idx].desc = `${params[continuation.idx].desc} ${tail}`.trim()
+  return ret
+}
+
 /**
  * Опис (без @-тегів) + параметри з `@param` як «name — опис».
  * @param {string} raw сирий JSDoc-блок
@@ -113,20 +178,52 @@ function parseJsDoc(raw) {
   const descLines = []
   const params = []
   let ret = ''
-  for (const l of lines) {
+  // Рядок без `@` на початку — це або (до першого тегу) частина `desc`, або (після
+  // @param/@returns) обгорнутий на новий рядок «хвіст» ЦЬОГО тегу. Без відстеження
+  // continuation такий хвіст мовчки падав у `descLines`, змішуючи текст @returns/
+  // @param у загальний опис (напр. довге `@returns` на 2 рядки).
+  let continuation = null // null | 'desc' | 'returns' | { kind: 'param', idx: number }
+  // Багаторядковий `@param {{ ... }}`/`@returns {{ ... }}` (складний object-type,
+  // не закритий на тому ж рядку): тіло типу пропускаємо (не тягнемо в desc/params/ret),
+  // рахуючи баланс дужок по рядках через `advanceBraceSkip`.
+  let braceSkip = null // null | { tag: 'param'|'returns', depth: number }
+  for (const rawLine of lines) {
+    let l = rawLine
+    if (braceSkip) {
+      const advanced = advanceBraceSkip(braceSkip, l)
+      if (advanced.line === null) continue
+      l = advanced.line
+      braceSkip = null
+    }
     const pm = l.match(PARAM_LINE_RE)
     if (pm) {
       const desc = pm[2].trim()
       // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
       params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
+      continuation = { kind: 'param', idx: params.length - 1 }
       continue
     }
     const rm = l.match(RETURNS_LINE_RE)
     if (rm) {
       ret = rm[1].trim()
+      continuation = 'returns'
+      continue
+    }
+    const multilineStart = detectMultilineTagStart(l)
+    if (multilineStart) {
+      braceSkip = multilineStart
+      continuation = null
+      continue
+    }
+    if (l.startsWith('@')) {
+      continuation = null // невідомий/непідтримуваний тег — не продовжуємо в нього
       continue
     }
-    if (l.startsWith('@')) continue
+    if (continuation && continuation !== 'desc' && l.trim()) {
+      ret = appendContinuation(continuation, params, ret, l.trim())
+      continue
+    }
+    continuation = 'desc'
     descLines.push(l)
   }
   return { desc: descLines.join('\n').trim(), params, ret }
@@ -134,10 +231,22 @@ function parseJsDoc(raw) {
 
 /**
  * Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом.
+ * `comments` (з парсера, `parseProgramAndCommentsOrNull`) — точний шлях: перший
+ * коментар файлу має бути саме ним. Без `comments` (парсинг не вдався, або
+ * виклик над фрагментом без AST — напр. Vue script-блок через `VUE_HELPERS`)
+ * — regex-фолбек на сирому тексті.
  * @param {string} src вміст файлу
+ * @param {Array<{type:string, value:string, start:number, end:number}>|null} [comments] список коментарів парсера або null
  * @returns {string} текст header-коментаря або порожній рядок
  */
-function extractFileHeader(src) {
+function extractFileHeader(src, comments = null) {
+  if (comments) {
+    const first = comments[0]
+    const isLeadingJsDoc = first?.type === 'Block' && first.value.startsWith('*')
+    if (isLeadingJsDoc && src.slice(0, first.start).trim() === '')
+      return parseJsDoc(src.slice(first.start, first.end)).desc
+    return ''
+  }
   const m = src.match(FILE_HEADER_RE)
   if (!m) return ''
   // має бути на самому початку (до import/код)
@@ -147,8 +256,11 @@ function extractFileHeader(src) {
 
 /**
  * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
- * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
- * найближчий блок — без жадібного «перестрибування» через імпорти/код.
+ * Regex-фолбек для випадків без `comments` від парсера (див. `jsDocCommentBefore`
+ * — надійніший AST-based шлях, коли парсинг вдався). `(?:(?!\*​/)[\s\S])*` гарантує,
+ * що тіло не містить `*​/`, тож захоплюється рівно один найближчий блок — без
+ * жадібного «перестрибування» через імпорти/код (окрім залишкового класу false
+ * positive усередині `//`-коментарів, який і закриває `jsDocCommentBefore`).
  * @param {string} prefix вміст файлу до позиції експорту
  * @returns {string|null} JSDoc-блок або null якщо немає
  */
@@ -158,15 +270,18 @@ function precedingJsDoc(prefix) {
 }
 
 /**
- * Експорти + JSDoc, що безпосередньо передує кожному.
+ * Експорти + JSDoc, що безпосередньо передує кожному. З `comments` (парсер) —
+ * точна AST-based атрибуція (`jsDocCommentBefore`); без них (парсинг не вдався,
+ * або виклик над фрагментом без AST) — regex-фолбек (`precedingJsDoc`).
  * @param {string} src вміст файлу
+ * @param {Array<{type:string, value:string, start:number, end:number}>|null} [comments] список коментарів парсера або null
  * @returns {Array<object>} список експортів із метаданими
  */
-function extractExports(src) {
+function extractExports(src, comments = null) {
   const out = []
   for (const m of src.matchAll(EXPORT_DECL_RE)) {
     const [, kind, name] = m
-    const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
+    const jsdocRaw = comments ? jsDocCommentBefore(comments, src, m.index) : precedingJsDoc(src.slice(0, m.index))
     out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
   }
   return out
@@ -263,6 +378,12 @@ const VUE_HELPERS = {
 
 /**
  * Головний екстрактор: код файлу → факт-лист.
+ * Коментарі беруться з реального AST-парсера (`parseProgramAndCommentsOrNull`),
+ * не regex по сирому тексту — усуває клас false positive, де "/**"-подібний
+ * текст усередині `//`-коментаря чи рядкового літералу (напр. glob-патерн)
+ * помилково читається як відкриття JSDoc. Парсинг не вдався (синтаксична
+ * помилка) → `comments: null`, `extractFileHeader`/`extractExports` падають
+ * назад на свій regex-шлях (той самий, що й до цієї зміни).
  * @param {string} src вміст файлу
  * @param {string} relPath шлях (для контексту/мови екстрактора)
  * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}} структура фактів про файл
@@ -273,11 +394,13 @@ export function extractFacts(src, relPath) {
   if (!['js', 'mjs', 'ts'].includes(lang)) {
     return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
   }
+  const parsed = parseProgramAndCommentsOrNull(src, relPath)
+  const comments = parsed?.comments ?? null
   return {
     relPath,
     lang,
-    header: extractFileHeader(src),
-    exports: extractExports(src),
+    header: extractFileHeader(src, comments),
+    exports: extractExports(src, comments),
     imports: extractImports(src),
     internalSymbols: extractInternalSymbols(src),
     localSymbols: extractLocalSymbols(src),

package/doc-files/js-facts.mjs

@@ -0,0 +1,28 @@
+/** @see ./docs/js-facts.md */
+
+/**
+ * JSDoc-коментар (Block, `/** ... *​/`), що стоїть ВПРИТУЛ перед позицією (лише
+ * пробіли між ними) — з реального списку коментарів парсера (`comments` від
+ * `parseProgramAndCommentsOrNull`), не regex по сирому тексту. Спільна для
+ * `extractors.mjs` (експорти js/mjs/ts) і `units-js.mjs` (юніти) — усуває клас
+ * false positive, де "/**"-подібний текст трапляється всередині `//`-коментаря
+ * чи рядкового літералу (напр. glob `'src/**​/x.rs'` чи `// приклад: /** ... *​/`)
+ * — токенізатор там уже коректно визначив межі справжніх коментарів, а
+ * regex-сканер такого тексту не бачить окремо і жадібно «протікає» до
+ * наступного реального `*​/`, змішуючи проміжний код в опис. Винесена в окремий
+ * модуль (без залежностей на `extractors.mjs`/`units-js.mjs`), щоб обидва могли
+ * її імпортувати без циклічного імпорту між собою.
+ * @param {Array<{type:string, value:string, start:number, end:number}>} comments список коментарів парсера (у порядку файлу)
+ * @param {string} src вміст файлу (для перевірки, що проміжок — лише пробіли)
+ * @param {number} pos позиція, перед якою шукаємо коментар
+ * @returns {string|null} дослівний `/** ... *​/`-текст або null, якщо немає
+ */
+export function jsDocCommentBefore(comments, src, pos) {
+  let best = null
+  for (const c of comments) {
+    if (c.type !== 'Block' || !c.value.startsWith('*') || c.end > pos) continue
+    if (!best || c.end > best.end) best = c
+  }
+  if (!best || src.slice(best.end, pos).trim() !== '') return null
+  return src.slice(best.start, best.end)
+}

package/doc-files/units-js.mjs

@@ -1,9 +1,15 @@
 /** @see ./docs/units-js.md */
 
-import { parseProgramOrNull, walkAstWithAncestors } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+import { parseProgramAndCommentsOrNull, walkAstWithAncestors } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+import { jsDocCommentBefore } from './js-facts.mjs'
 
-// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
-const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+// Regex-фолбек для випадків без `comments` від парсера (парсинг не вдався —
+// не мало б статися тут, бо `extractUnitsJs` і так вимагає успішний `program`,
+// але `parsed.comments` теоретично може бути порожнім масивом на дивному вході).
+// `(?!\/)` одразу після відкриття — без нього glob-рядок `'src/**/linux.rs'`
+// читається як порожній `/**/`, і жадібний пошук найближчого `*/` протікає до
+// наступного реального закриття JSDoc, змішуючи проміжний код у витягнутий опис.
+const JSDOC_BEFORE_RE = /\/\*\*(?!\/)(?:(?!\*\/)[\s\S])*\*\/\s*$/
 const JSDOC_OPEN_RE = /^\s*\/\*\*?/
 const JSDOC_CLOSE_RE = /\*\/\s*$/
 const STAR_PREFIX_RE = /^\s*\*?\s?/
@@ -25,12 +31,19 @@ function cleanDoc(raw) {
 }
 
 /**
- * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
+ * JSDoc, що передує позиції `start` у джерелі (або порожній рядок). З `comments`
+ * (реальний список від парсера) — точна AST-based атрибуція через
+ * `jsDocCommentBefore` (js-facts.mjs): усуває клас false positive, де
+ * "/**"-подібний текст усередині `//`-коментаря чи рядкового літералу (напр.
+ * glob-патерн) помилково читається regex-ом як відкриття JSDoc. Порожній
+ * `comments` (немає жодного коментаря в файлі) — фолбек на `JSDOC_BEFORE_RE`.
  * @param {string} src вміст файлу
  * @param {number} start зміщення початку декларації
+ * @param {Array<{type:string, value:string, start:number, end:number}>} comments список коментарів парсера
  * @returns {string} очищений опис
  */
-function precedingDoc(src, start) {
+function precedingDoc(src, start, comments) {
+  if (comments.length) return cleanDoc(jsDocCommentBefore(comments, src, start))
   const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
   return cleanDoc(m ? m[0] : '')
 }
@@ -75,11 +88,12 @@ function collectCalls(node) {
  * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
  * @param {string} src вміст файлу
  * @param {Array<object>} units акумулятор
+ * @param {Array<{type:string, value:string, start:number, end:number}>} comments список коментарів парсера
  * @returns {void}
  */
-function pushUnits(decl, exported, docStart, src, units) {
+function pushUnits(decl, exported, docStart, src, units, comments) {
   if (!decl || typeof decl !== 'object') return
-  const doc = precedingDoc(src, docStart)
+  const doc = precedingDoc(src, docStart, comments)
   if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
     const name = decl.id?.name
     if (!name) return
@@ -120,17 +134,19 @@ function pushUnits(decl, exported, docStart, src, units) {
  * @returns {Array<{name:string, kind:string, exported:boolean, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти або null, якщо файл не парситься
  */
 export function extractUnitsJs(src, relPath = 'scan.ts') {
-  const program = parseProgramOrNull(src, relPath)
+  const parsed = parseProgramAndCommentsOrNull(src, relPath)
+  const program = parsed?.program
   if (!program || !Array.isArray(program.body)) return null
+  const comments = parsed.comments
 
   const units = []
   for (const node of program.body) {
     const isExport =
       (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') && node.declaration
     if (isExport) {
-      pushUnits(node.declaration, true, node.start, src, units)
+      pushUnits(node.declaration, true, node.start, src, units, comments)
     } else {
-      pushUnits(node, false, node.start, src, units)
+      pushUnits(node, false, node.start, src, units, comments)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules-lang-js",
-  "version": "0.8.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" } }
+```