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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [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
+
+- doc-files: Vue SFC-екстрактор (`<script setup>`) — extractFactsVue/extractUnitsVue через optional peer vue/compiler-sfc; props/emits/expose/слоти як публічний контракт, юніти зі span-корекцією (ADR 260719-2155)
+
 ## [0.7.1] - 2026-07-20
 
 ### Fixed

package/doc-files/docs/extractors.md

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

package/doc-files/docs/index.md

@@ -7,4 +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/docs/vue.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: vue.mjs
+resource: plugins/lang-js/doc-files/vue.mjs
+docgen:
+  crc: 8651a381
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`vueScriptBlock`, `extractFactsVue` і `extractUnitsVue` працюють із Vue SFC як з джерелом для подальшого витягування фактів і юнітів у координатах оригінального `.vue`. Вони підтримують fail-safe поведінку: перехоплюють помилки, не кидають винятків назовні та за окремих збоїв повертають порожнє значення, зокрема `null`, замість помилки.
+
+## Поведінка
+
+- `vueScriptBlock` — розбирає `.vue` як SFC і повертає `script setup` або `script` блок із дескриптором; якщо peer `vue` відсутній, SFC битий або script-блоку немає, повертає порожній результат замість помилки.
+- `extractFactsVue` — формує факт-лист для Vue SFC на основі `script`-блоку: виділяє публічний контракт компонента через props, emits, expose і slots, а також додає JS-факти з `script`; якщо `vue` недоступний, SFC битий або script-блоку немає, повертає `unsupported`.
+- `extractUnitsVue` — витягує JS/TS-юніти зі `script`-блоку Vue-файла і переносить їхні span-позиції в координати оригінального `.vue`; якщо `vue` недоступний, SFC битий або script-блоку немає, повертає порожній результат.
+
+## Публічний API
+
+- vueScriptBlock — Дістає script-блок із SFC, віддаючи пріоритет `<script setup>`, разом із дескриптором.
+- extractFactsVue — Збирає публічний контракт Vue SFC: props, emits, expose і slots, а також повторно використовує JS-хелпери для header, imports і markers із тексту script-блоку; `<template>` і `<style>` у факти не потрапляють. Без peer `vue` або на битому SFC чи без script-блоку повертає `unsupported` у whole-file режимі, як до впровадження.
+- extractUnitsVue — Будує JS-юніти з script-блоку `.vue` і зсуває span-и на позиції в оригінальному `.vue` файлі, щоб anchors і CRC вказували саме на вихідний SFC, а не на вирізаний фрагмент.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/doc-files/extractors.mjs

@@ -1,5 +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`
@@ -35,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 як «публічні».
@@ -101,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-блок
@@ -112,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 (continuation && continuation !== 'desc' && l.trim()) {
+      ret = appendContinuation(continuation, params, ret, l.trim())
       continue
     }
-    if (l.startsWith('@')) continue
+    continuation = 'desc'
     descLines.push(l)
   }
   return { desc: descLines.join('\n').trim(), params, ret }
@@ -133,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/код)
@@ -146,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 якщо немає
  */
@@ -157,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
@@ -249,22 +365,42 @@ function extractMarkers(src) {
     skips: [...skips]
   }
 }
+/** JS-хелпери, які Vue-екстрактор переюзає над текстом script-блоку SFC. */
+const VUE_HELPERS = {
+  extractFileHeader,
+  extractExports,
+  extractImports,
+  extractInternalSymbols,
+  extractLocalSymbols,
+  extractMarkers,
+  parseJsDoc
+}
+
 /**
  * Головний екстрактор: код файлу → факт-лист.
+ * Коментарі беруться з реального 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}} структура фактів про файл
  */
 export function extractFacts(src, relPath) {
   const lang = relPath.split('.').pop()
+  if (lang === 'vue') return extractFactsVue(src, relPath, VUE_HELPERS)
   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),
@@ -272,17 +408,29 @@ export function extractFacts(src, relPath) {
   }
 }
 
+/**
+ * Юніти: `.vue` — зі script-блоку SFC (span-и в координатах файлу), решта — oxc AST.
+ * @param {string} src вміст файлу
+ * @param {string} relPath шлях (вибір мови)
+ * @returns {Array<object>|null} юніти або null
+ */
+function extractUnits(src, relPath) {
+  if (relPath.toLowerCase().endsWith('.vue')) return extractUnitsVue(src, relPath, extractUnitsJs)
+  return extractUnitsJs(src, relPath)
+}
+
 /**
  * Default-експорт для handler-модуля extension-point `doc-files`.
- * `.vue` у списку розширень (файл — кандидат на доку), але `extractFacts` для нього
- * повертає `unsupported` — генерація йде whole-file шляхом, як і до винесення.
- * @type {{ id: string, extensions: string[], extractFacts: typeof extractFacts, extractUnits: typeof extractUnitsJs }}
+ * `.vue` (SFC зі `<script setup>`) парситься через optional peer `vue/compiler-sfc`
+ * (ADR 260719-2155): props/emits/expose/слоти → факт-лист; без peer чи script-блоку —
+ * fallback `unsupported` (whole-file шлях, як до впровадження).
+ * @type {{ id: string, extensions: string[], extractFacts: typeof extractFacts, extractUnits: typeof extractUnits }}
  */
 const jsDocFilesExtractor = {
   id: 'js',
   extensions: ['.js', '.mjs', '.ts', '.vue'],
   extractFacts,
-  extractUnits: extractUnitsJs
+  extractUnits
 }
 
 export default jsDocFilesExtractor

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/doc-files/vue.mjs

@@ -0,0 +1,215 @@
+/** @see ./docs/vue.md */
+
+// Optional peer `vue`: компілятор резолвиться один раз при завантаженні модуля.
+// Свідомо НЕ статичний import — без установленого peer модуль має лишитися
+// робочим (extractFactsVue → unsupported), а не завалити весь handler lang-js
+// (catch у loadDocFilesExtractors мовчки прибрав би і JS/TS-екстрактор).
+let compilerSfc = null
+try {
+  compilerSfc = await import('vue/compiler-sfc')
+} catch {
+  /* peer `vue` не встановлено — .vue лишається unsupported (whole-file шлях) */
+}
+
+const QUOTED_NAME_RE = /'([^']{1,80})'|"([^"]{1,80})"/g
+// Object-style defineEmits<{ save: [id: number] }> — ключ вимагає tuple-значення
+// (`:\s*[`), щоб не ловити label-и всередині tuple (`[id: number]`) як імена подій.
+const EMIT_OBJECT_KEY_RE = /([\w$-]{1,80})\s*:\s*\[/g
+const EMITS_GENERIC_RE = /defineEmits<([^>]{1,2000})>/
+const EMITS_ARRAY_RE = /defineEmits\(\s*\[([^\]]{0,2000})\]/
+const EXPOSE_CALL_RE = /defineExpose\s*\(\s*\{([^()]{0,2000})\}\s*\)/
+// Провідний ідентифікатор одного елемента defineExpose (`focus`, `...rest`, `b: c`).
+const EXPOSE_ITEM_RE = /^(?:\.{3})?([\w$]{1,80})/
+// HTML-коментар template: [^>] гарантує зупинку на першому `>` (кінець `-->`).
+const HTML_COMMENT_RE = /<!--([^>]{0,300})>/g
+const SLOT_NAME_RE = /^[\w-]{1,80}/
+const SLOT_LEAD_MARK_RE = /^[:—-]{1,3}/
+// Канонічний патерн JSDoc-блоку без зворотного перебору.
+const JSDOC_BLOCK_RE = /\/\*\*[^*]*(?:\*(?!\/)[^*]*)*\*\//g
+const WORD_RE = /[\w$-]{1,80}/g
+// Модифікатори/ключові слова, які стоять між JSDoc-блоком і власне іменем
+// (декларації, `(e: '…'`-префікс сигнатури emit-події).
+const SKIP_WORDS = new Set(['readonly', 'export', 'async', 'function', 'const', 'class', 'e'])
+
+/**
+ * Порожній факт-лист unsupported-фолбеку (peer відсутній / битий SFC / без script).
+ * @param {string} relPath шлях файлу
+ * @returns {object} факт-лист із `unsupported: true`
+ */
+function unsupportedFacts(relPath) {
+  return { relPath, lang: 'vue', unsupported: true, header: '', exports: [], imports: {}, markers: {} }
+}
+
+/**
+ * Розбирає SFC і повертає script-блок (`<script setup>` пріоритетно) з дескриптором.
+ * @param {string} src вміст `.vue` файлу
+ * @param {string} relPath шлях (filename для компілятора)
+ * @returns {{ block: object, descriptor: object }|null} блок+дескриптор або null (нема компілятора / битий SFC / нема script)
+ */
+export function vueScriptBlock(src, relPath) {
+  if (!compilerSfc) return null
+  let descriptor
+  try {
+    ;({ descriptor } = compilerSfc.parse(src, { filename: relPath }))
+  } catch {
+    return null
+  }
+  const block = descriptor.scriptSetup ?? descriptor.script
+  if (!block?.content?.trim()) return null
+  return { block, descriptor }
+}
+
+/**
+ * Мапа «імʼя → JSDoc-опис» для всього script-блоку: кожен JSDoc-блок
+ * привʼязується до першого ідентифікатора одразу після нього (interface-member,
+ * ключ обʼєкта, декларація function/const для defineExpose-shorthand, сигнатура
+ * emit-події). Одна статична регулярка замість динамічних per-name.
+ * @param {string} content текст script-блоку
+ * @param {(raw: string) => {desc: string}} parseJsDoc парсер JSDoc з extractors
+ * @returns {Map<string, string>} імʼя → опис
+ */
+function jsDocMap(content, parseJsDoc) {
+  const map = new Map()
+  for (const m of content.matchAll(JSDOC_BLOCK_RE)) {
+    const after = content.slice(m.index + m[0].length, m.index + m[0].length + 120)
+    for (const w of after.matchAll(WORD_RE)) {
+      if (SKIP_WORDS.has(w[0])) continue
+      if (!map.has(w[0])) map.set(w[0], parseJsDoc(m[0]).desc)
+      break
+    }
+  }
+  return map
+}
+
+/**
+ * Імена props через `compileScript().bindings` — канонічний резолв і обʼєктної
+ * форми, і generic `defineProps<Props>()` з interface у тому ж блоці. Якщо
+ * компіляція впала (битий TS/макрос) — props не витягуються (порожній список).
+ * @param {object} descriptor SFC-дескриптор
+ * @param {string} relPath шлях (id для compileScript)
+ * @returns {string[]} імена props
+ */
+function vuePropNames(descriptor, relPath) {
+  try {
+    const compiled = compilerSfc.compileScript(descriptor, { id: relPath })
+    return Object.entries(compiled.bindings ?? {})
+      .filter(([, type]) => type === 'props')
+      .map(([name]) => name)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Імена подій із defineEmits: масив-форма (`['save']`), function-signature
+ * generic (`(e: 'save'): void`) — лапковані літерали; object-style generic
+ * (`{ save: [id: number] }`) — ключі з tuple-значенням.
+ * @param {string} content текст script-блоку
+ * @returns {string[]} імена подій
+ */
+function vueEmitNames(content) {
+  const m = content.match(EMITS_GENERIC_RE) ?? content.match(EMITS_ARRAY_RE)
+  if (!m) return []
+  const body = m[1]
+  const quoted = Array.from(body.matchAll(QUOTED_NAME_RE), q => q[1] ?? q[2])
+  if (quoted.length) return [...new Set(quoted)]
+  return [...new Set(Array.from(body.matchAll(EMIT_OBJECT_KEY_RE), k => k[1]))]
+}
+
+/**
+ * Імена публічно виставлених через defineExpose полів (обʼєктна форма).
+ * @param {string} content текст script-блоку
+ * @returns {string[]} імена exposed-полів
+ */
+function vueExposeNames(content) {
+  const m = content.match(EXPOSE_CALL_RE)
+  if (!m) return []
+  const names = m[1]
+    .split(',')
+    .map(item => item.trim().match(EXPOSE_ITEM_RE)?.[1])
+    .filter(Boolean)
+  return [...new Set(names)]
+}
+
+/**
+ * Слоти з маркер-коментарів slot у template (імʼя + опційний опис).
+ * Розбір двокроковий: спершу HTML-коментарі однією простою регуляркою,
+ * далі — плоский JS-парсинг тексту (без складних патернів).
+ * @param {string} template текст template-блоку
+ * @returns {Array<{name: string, desc: string}>} слоти
+ */
+function vueSlots(template) {
+  const slots = []
+  for (const m of template.matchAll(HTML_COMMENT_RE)) {
+    // m[1] — вміст до першого `>`, тобто разом із хвостовим `--` від `-->`
+    const text = m[1].endsWith('--') ? m[1].slice(0, -2).trim() : m[1].trim()
+    if (!text.startsWith('@slot')) continue
+    const rest = text.slice('@slot'.length).trim()
+    const name = rest.match(SLOT_NAME_RE)?.[0]
+    if (!name) continue
+    const desc = rest.slice(name.length).trim().replace(SLOT_LEAD_MARK_RE, '').trim()
+    slots.push({ name, desc })
+  }
+  return slots
+}
+
+/**
+ * Факт-лист для Vue SFC (`<script setup>` пріоритетно): props/emits/expose/слоти
+ * як публічний контракт компонента + переюз JS-хелперів (header, imports,
+ * markers) над текстом script-блоку — `<template>`/`<style>` у факти не течуть.
+ * Без peer `vue`, на битому SFC чи без script-блоку — `unsupported` (whole-file
+ * шлях, як до впровадження).
+ * @param {string} src вміст `.vue` файлу
+ * @param {string} relPath шлях файлу
+ * @param {object} h JS-хелпери з extractors (extractFileHeader, extractExports, extractImports, extractInternalSymbols, extractLocalSymbols, extractMarkers, parseJsDoc)
+ * @returns {object} факт-лист (`lang: 'vue'`)
+ */
+export function extractFactsVue(src, relPath, h) {
+  const sb = vueScriptBlock(src, relPath)
+  if (!sb) return unsupportedFacts(relPath)
+  const { block, descriptor } = sb
+  const content = block.content
+  const docs = jsDocMap(content, h.parseJsDoc)
+  const entry = kind => name => ({ name, kind, desc: docs.get(name) ?? '', params: [], ret: '' })
+
+  return {
+    relPath,
+    lang: 'vue',
+    header: h.extractFileHeader(content),
+    exports: [
+      ...vuePropNames(descriptor, relPath).map(entry('prop')),
+      ...vueEmitNames(content).map(entry('emit')),
+      ...vueExposeNames(content).map(entry('expose')),
+      ...h.extractExports(content)
+    ],
+    slots: vueSlots(descriptor.template?.content ?? ''),
+    imports: h.extractImports(content),
+    internalSymbols: h.extractInternalSymbols(content),
+    localSymbols: h.extractLocalSymbols(content),
+    markers: h.extractMarkers(content)
+  }
+}
+
+/**
+ * Юніт-шар для `.vue`: JS-юніти зі script-блоку з корекцією span-ів на offset
+ * блоку в файлі — anchors/CRC мають вказувати на позиції ОРИГІНАЛЬНОГО `.vue`,
+ * а не script-фрагмента.
+ * @param {string} src вміст `.vue` файлу
+ * @param {string} relPath шлях файлу
+ * @param {(src: string, relPath: string) => Array<object>|null} unitsJs екстрактор юнітів js/ts
+ * @returns {Array<object>|null} юніти або null (нема компілятора / script / не парситься)
+ */
+export function extractUnitsVue(src, relPath, unitsJs) {
+  const sb = vueScriptBlock(src, relPath)
+  if (!sb) return null
+  const { block } = sb
+  // relPath завжди закінчується на .vue (диспетчер викликає лише для нього)
+  const pseudoPath = relPath.slice(0, -'.vue'.length) + (block.lang === 'ts' ? '.ts' : '.js')
+  const units = unitsJs(block.content, pseudoPath)
+  if (!units) return null
+  const offset = block.loc.start.offset
+  for (const u of units) {
+    u.span = { start: u.span.start + offset, end: u.span.end + offset }
+  }
+  return units
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules-lang-js",
-  "version": "0.7.1",
+  "version": "0.9.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",
@@ -62,7 +62,8 @@
     "stylelint": "^17.6.0"
   },
   "peerDependencies": {
-    "@7n/rules": ">=1.27.0"
+    "@7n/rules": ">=1.27.0",
+    "vue": "^3.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -70,5 +71,10 @@
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
   }
 }