@7n/rules-lang-js 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.3.1] - 2026-07-19
+
+### Fixed
+
+- extractors.test.mjs: імпорт з ../extractors.mjs замість неіснуючого ../main.mjs (хвіст перейменування фази 5b; knip unresolved)
+
+## [0.3.0] - 2026-07-19
+
+### Added
+
+- doc-files-екстрактори JS-екосистеми (фаза 5b spec lang-plugins-extraction): маніфест декларує розширення js/mjs/ts/vue з OKF-типами (contributes.docFiles.extensions) і handler doc-files; extractFacts (факт-лист js/mjs/ts, .vue → whole-file) та extractUnits (oxc AST юніт-шар) переїхали з ядра — генерація док для JS-файлів тепер вмикається цим плагіном
+
+### Fixed
+
+- knip duplicates `jsProvider|default`: провайдер тепер експортується лише як default (як у lang-rust/lang-python), named-експорт `jsProvider` прибрано
+
 ## [0.2.0] - 2026-07-19
 
 ### Added

package/doc-files/docs/extractors.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: extractors.mjs
+resource: plugins/lang-js/doc-files/extractors.mjs
+docgen:
+  crc: 5ba406e8
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Мовний doc-files-екстрактор JS-екосистеми (extension-point `doc-files`, фаза 5b spec lang-plugins-extraction): перетворює вміст js/mjs/ts-файлу на структурований факт-лист для генерації поведінкової документації. Default-експорт — обʼєкт екстрактора `{ id: 'js', extensions: ['.js','.mjs','.ts','.vue'], extractFacts, extractUnits }`, який ядро вантажить динамічно з маніфеста плагіна (`contributes.handlers['doc-files']`) лише на шляху генерації.
+
+## Поведінка
+
+- `extractFacts(src, relPath)` для `js`/`mjs`/`ts` збирає: провідний файловий JSDoc-коментар (намір модуля), експортовані декларації з їхніми JSDoc-описами (`@param`/`@returns` парсяться у структуру), імпорти класифіковані на stdlib/npm/internal, імена внутрішніх імпортованих символів та неекспортованих top-level функцій/класів (щоб модель не подавала їх як публічний API), і поведінкові маркери-евристики.
+- Інші розширення (включно з `.vue`) → факт-лист із `unsupported: true` — генерація йде whole-file шляхом.
+- Маркери навмисно консервативні («фабрикація гірша за мовчання»): `readOnly` — немає ні ФС-запису, ні DB-мутацій (включно з raw-SQL tagged-template з DML-ключовим словом на початку шаблону); `catchesErrors`/`returnsFalsyOnFail` — лише якщо модуль ніде не кидає; `network` свідомо over-detect (хибна гарантія «без мережі» небезпечніша); `caches` — лише за іменованим cache/memo-маркером, а не будь-яким `new Map()`; `skips` — помічені літерали пропущених тек.
+- `extractUnits` — делегує `extractUnitsJs` з `units-js.mjs` (oxc AST, юніт-шар).
+
+## Публічний API
+
+- default — обʼєкт екстрактора для handler-модуля extension-point `doc-files`.
+- extractFacts — код файлу → факт-лист (`{relPath, lang, header, exports, imports, internalSymbols, localSymbols, markers}` або `{unsupported: true}`).
+
+## Гарантії поведінки
+
+- Read-only: не пише у ФС, не запускає команд, не ходить у мережу.
+- Не кидає на довільному тексті — розширення без підтримки дає `unsupported`, а не виняток.
+- Регекс-евристики без бектрекінг-вразливих патернів (обмежені квантифікатори).

package/doc-files/docs/index.md

@@ -0,0 +1,10 @@
+---
+type: Directory Index
+title: plugins/lang-js/doc-files
+resource: plugins/lang-js/doc-files/
+---
+
+| Файл                            | Тип       |
+| ------------------------------- | --------- |
+| [extractors.mjs](extractors.md) | JS Module |
+| [units-js.mjs](units-js.md)     | JS Module |

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

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: units-js.mjs
+resource: plugins/lang-js/doc-files/units-js.mjs
+docgen:
+  crc: 9a13a64e
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.94
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`extractUnitsJs` виділяє одиниці верхнього рівня з JS/MJS/TS-файлу та повертає їх у структурованому вигляді для подальшої обробки. Це потрібно, щоб окремо працювати з публічними частинами модуля без ручного розбору всього файлу.
+
+## Поведінка
+
+1. Розбирає вміст JS/MJS/TS-файлу в структуру програми (oxc-парсер із ядра, `@7n/rules/scripts/utils/ast-scan-utils.mjs`); якщо файл не парситься — повертає `null` (сигнал для whole-file шляху генерації).
+2. Збирає лише top-level юніти: `function`, `class` і `const`-присвоєння, де значенням є function body.
+3. Для експортованих декларацій позначає юніт як exported; для звичайних декларацій лишає його без позначки експорту.
+4. Для кожного юніта фіксує межі в джерелі, текст тіла, опис, що стоїть безпосередньо перед декларацією, та список викликів, знайдених у тілі.
+5. У списку викликів лишає тільки імена інших внутрішніх юнітів цього самого файлу; виклики самого себе відкидає.
+6. Повертає зібраний набір юнітів для подальшого аналізу залежностей і документації.
+
+## Публічний API
+
+- extractUnitsJs — виділяє юніти верхнього рівня в js/mjs/ts: функції, класи й const-функції з тілом, JSDoc, позначку експорту та зв’язки викликів до інших юнітів у тілі
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/doc-files/extractors.mjs

@@ -0,0 +1,288 @@
+/** @see ./docs/extractors.md */
+import { extractUnitsJs } from './units-js.mjs'
+
+/**
+ * Мовний doc-files-екстрактор JS-екосистеми для конвеєра `@7n/rules`
+ * (extension-point `doc-files`, фаза 5b spec lang-plugins-extraction: ядро —
+ * двигун без мовної специфіки): факт-лист (`extractFacts`) для js/mjs/ts і
+ * юніти (`extractUnits`) через oxc AST. Розширення `.js`/`.mjs`/`.ts`/`.vue`
+ * та їхні OKF-типи декларуються маніфестом плагіна
+ * (`contributes.docFiles.extensions`) — hot-path ядра читає їх синхронно;
+ * цей модуль вантажиться лише на шляху генерації.
+ */
+
+const BUILTIN_MODULES = new Set([
+  'fs',
+  'path',
+  'crypto',
+  'os',
+  'util',
+  'stream',
+  'events',
+  'http',
+  'https',
+  'url',
+  'child_process',
+  'process',
+  'assert',
+  'buffer',
+  'zlib',
+  'readline'
+])
+
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+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*$/
+const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+(\w+)/g
+// Top-level function/class декларації (колонка 0) — для R6: службові функції,
+// які не експортуються, не мають протікати у Поведінку/API як «публічні».
+const TOP_FN_DECL_RE = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class)\s+(\w+)/gm
+const IMPORT_FROM_RE = /^import[ \t]{1,8}[\s\S]{0,300}?from\s{1,8}['"]([^'"]+)['"]/gm
+const NODE_PREFIX_RE = /^node:/
+const INTERNAL_IMPORT_RE = /import[ \t]{1,8}([^'"]{0,300}?)from[ \t]{1,8}['"]\.[^'"]{1,300}['"]/g
+const NAMED_BRACES_RE = /\{([^}]{1,400})\}/
+const IDENT_RE = /^[\w$]{1,80}$/
+const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
+const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
+const CATCH_RE = /catch\s*\(/
+const TRY_RE = /\btry\s*\{/
+// Falsy-return як «fail-safe» — лише коли воно в catch/error-гілці (інакше це
+// звичайний guard `if (!x) return null`, не обробка помилки). Уникає over-claim.
+const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
+// Мережа: окрім явного fetch/http, ловимо абстраговані клієнти (graphql/db/rpc/
+// octokit/.request/.query). Хибний false-negative тут = небезпечна гарантія
+// «без мережі», тож свідомо схиляємось до over-detection (м'якший бік помилки).
+const NETWORK_RE =
+  /\bfetch\(|https?:\/\/|\bhttps?\.|axios|\bgot\(|graphql|\.request\(|\.query\(|\.mutate\(|octokit|node-fetch|undici|\bgrpc\b|websocket/i
+// Будь-який `throw` назовні → НЕ можна гарантувати «fail-safe / без винятків».
+const THROW_RE = /\bthrow\s/
+// Запис у БД / зовнішню мутацію → НЕ read-only (навіть якщо нема ФС-запису).
+// Розбито на кілька простіших патернів (та сама семантика через OR у `isMutation`),
+// щоб уникнути надмірної складності одного великого regex.
+const MUTATION_CALL_RE = /\b(insert|update|delete|upsert|drop|destroy|save)[A-Za-z]*\s*[(,]/
+const MUTATION_NAME_RE = /[Mm]utation\b|\bmut[A-Z]\w*/
+const MUTATION_METHOD_RE = /\.(save|create|update|delete|insert|destroy|mutate)\(/
+// Raw-SQL tagged-template виклики (напр. `pgWrite\`UPDATE ...\``) — DML-ключове
+// слово стоїть на початку тіла шаблону, не перед `(`, тож JS-орієнтовані
+// патерни вище його не ловлять. Сигнал мінімальний, але навмисний: тег-функція
+// (ідентифікатор впритул перед `` ` ``) + DML-keyword одразу після відкриття —
+// уникає false positive на звичайних рядках/коментарях, де немає теg-виклику.
+const SQL_TAGGED_MUTATION_RE = /\b\w+`\s*(?:UPDATE|INSERT|MERGE\s+INTO|DELETE\s+FROM|UPSERT)\b/i
+/**
+ * @param {string} src вміст файлу
+ * @returns {boolean} чи є ознаки мутації БД / зовнішнього стану
+ */
+const isMutation = src =>
+  MUTATION_CALL_RE.test(src) ||
+  MUTATION_NAME_RE.test(src) ||
+  MUTATION_METHOD_RE.test(src) ||
+  SQL_TAGGED_MUTATION_RE.test(src)
+// Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
+// `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
+// «Кешує результати» гірша за пропуск (фабрикація > мовчання).
+const CACHE_RE = /cache|memoi[sz]e/i
+
+/**
+ * Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками.
+ * @param {string} raw сирий JSDoc-блок з обрамленням
+ * @returns {string} очищений текст без обрамлення й префіксів
+ */
+function cleanJsDoc(raw) {
+  return raw
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
+    .split('\n')
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/**
+ * Опис (без @-тегів) + параметри з `@param` як «name — опис».
+ * @param {string} raw сирий JSDoc-блок
+ * @returns {{desc:string, params:Array<{name:string, desc:string}>, ret:string}} розпарсений опис, параметри й опис повернення
+ */
+function parseJsDoc(raw) {
+  const text = cleanJsDoc(raw)
+  const lines = text.split('\n')
+  const descLines = []
+  const params = []
+  let ret = ''
+  for (const l of lines) {
+    const pm = l.match(PARAM_LINE_RE)
+    if (pm) {
+      const desc = pm[2].trim()
+      // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
+      params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
+      continue
+    }
+    const rm = l.match(RETURNS_LINE_RE)
+    if (rm) {
+      ret = rm[1].trim()
+      continue
+    }
+    if (l.startsWith('@')) continue
+    descLines.push(l)
+  }
+  return { desc: descLines.join('\n').trim(), params, ret }
+}
+
+/**
+ * Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом.
+ * @param {string} src вміст файлу
+ * @returns {string} текст header-коментаря або порожній рядок
+ */
+function extractFileHeader(src) {
+  const m = src.match(FILE_HEADER_RE)
+  if (!m) return ''
+  // має бути на самому початку (до import/код)
+  if (src.slice(0, m.index).trim() !== '') return ''
+  return parseJsDoc(m[0]).desc
+}
+
+/**
+ * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
+ * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
+ * найближчий блок — без жадібного «перестрибування» через імпорти/код.
+ * @param {string} prefix вміст файлу до позиції експорту
+ * @returns {string|null} JSDoc-блок або null якщо немає
+ */
+function precedingJsDoc(prefix) {
+  const m = prefix.match(PRECEDING_JSDOC_RE)
+  return m ? m[0] : null
+}
+
+/**
+ * Експорти + JSDoc, що безпосередньо передує кожному.
+ * @param {string} src вміст файлу
+ * @returns {Array<object>} список експортів із метаданими
+ */
+function extractExports(src) {
+  const out = []
+  for (const m of src.matchAll(EXPORT_DECL_RE)) {
+    const [, kind, name] = m
+    const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
+    out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
+  }
+  return out
+}
+
+/**
+ * Імпорти, класифіковані на stdlib / npm / internal.
+ * @param {string} src вміст файлу
+ * @returns {{stdlib:Array<string>, npm:Array<string>, internal:Array<string>}} розкласифіковані шляхи імпортів
+ */
+function extractImports(src) {
+  const internal = new Set(),
+    npm = new Set(),
+    stdlib = new Set()
+  for (const m of src.matchAll(IMPORT_FROM_RE)) {
+    const s = m[1]
+    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/', 1)[0])) stdlib.add(s.replace(NODE_PREFIX_RE, ''))
+    else if (s.startsWith('.') || s.startsWith('/')) internal.add(s)
+    else npm.add(s)
+  }
+  return { stdlib: [...stdlib], npm: [...npm], internal: [...internal] }
+}
+
+/**
+ * Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати.
+ * @param {string} src вміст файлу
+ * @returns {Array<string>} список імен внутрішніх символів
+ */
+function extractInternalSymbols(src) {
+  const out = new Set()
+  for (const m of src.matchAll(INTERNAL_IMPORT_RE)) {
+    const clause = m[1]
+    const named = clause.match(NAMED_BRACES_RE)
+    if (named) {
+      for (const n of named[1].split(',')) {
+        const name = n.replace(IMPORT_AS_RE, '').trim()
+        if (name) out.add(name)
+      }
+    }
+    const defName = clause.replace(NAMED_BRACES_RE, '').replaceAll(',', ' ').trim().split(' ', 1)[0]
+    if (defName && IDENT_RE.test(defName)) out.add(defName)
+  }
+  return [...out]
+}
+
+/**
+ * Імена top-level функцій/класів, які НЕ експортуються (службові помічники).
+ * Модель не має подавати їх як «публічні функції» у Поведінці/API (R6).
+ * Const-стрілки свідомо не ловимо — менше false-positive на змістовних константах.
+ * @param {string} src вміст файлу
+ * @returns {Array<string>} список імен неекспортованих функцій/класів
+ */
+function extractLocalSymbols(src) {
+  const exported = new Set(Array.from(src.matchAll(EXPORT_DECL_RE), m => m[2]))
+  const out = new Set()
+  for (const m of src.matchAll(TOP_FN_DECL_RE)) {
+    if (!exported.has(m[1])) out.add(m[1])
+  }
+  return [...out]
+}
+
+/**
+ * Поведінкові маркери — евристики регулярками.
+ * @param {string} src вміст файлу
+ * @returns {object} набір прапорців-евристик
+ */
+function extractMarkers(src) {
+  // помітні «пропуски»: dir/segment-літерали у фільтрах
+  const skips = new Set()
+  for (const lit of ['.github', '.git', 'node_modules', 'base/', 'ua/', '.firebase']) {
+    if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
+  }
+  return {
+    // «Фабрикація > мовчання»: прапорець true лише за high-confidence; інакше
+    // guaranteesFromMarkers/factsSummary його ОПУСКАЮТЬ (не стверджують протилежне).
+    readOnly: !WRITE_FS_RE.test(src) && !isMutation(src), // ні ФС-запису, ні DB-мутацій
+    catchesErrors: (CATCH_RE.test(src) || TRY_RE.test(src)) && !THROW_RE.test(src), // fail-safe лише якщо НЕ кидає
+    returnsFalsyOnFail: FALSY_RETURN_RE.test(src) && !THROW_RE.test(src),
+    network: NETWORK_RE.test(src),
+    caches: CACHE_RE.test(src),
+    skips: [...skips]
+  }
+}
+/**
+ * Головний екстрактор: код файлу → факт-лист.
+ * @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 (!['js', 'mjs', 'ts'].includes(lang)) {
+    return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
+  }
+  return {
+    relPath,
+    lang,
+    header: extractFileHeader(src),
+    exports: extractExports(src),
+    imports: extractImports(src),
+    internalSymbols: extractInternalSymbols(src),
+    localSymbols: extractLocalSymbols(src),
+    markers: extractMarkers(src)
+  }
+}
+
+/**
+ * Default-експорт для handler-модуля extension-point `doc-files`.
+ * `.vue` у списку розширень (файл — кандидат на доку), але `extractFacts` для нього
+ * повертає `unsupported` — генерація йде whole-file шляхом, як і до винесення.
+ * @type {{ id: string, extensions: string[], extractFacts: typeof extractFacts, extractUnits: typeof extractUnitsJs }}
+ */
+const jsDocFilesExtractor = {
+  id: 'js',
+  extensions: ['.js', '.mjs', '.ts', '.vue'],
+  extractFacts,
+  extractUnits: extractUnitsJs
+}
+
+export default jsDocFilesExtractor

package/doc-files/units-js.mjs

@@ -0,0 +1,141 @@
+/** @see ./docs/units-js.md */
+
+import { parseProgramOrNull, walkAstWithAncestors } from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+
+// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
+const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+const JSDOC_CLOSE_RE = /\*\/\s*$/
+const STAR_PREFIX_RE = /^\s*\*?\s?/
+
+/**
+ * Очищає JSDoc від обрамлення `/** *​/` і `*`-префіксів.
+ * @param {string} raw сирий блок або порожній рядок
+ * @returns {string} текст опису без тегів-обрамлення
+ */
+function cleanDoc(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
+    .split('\n')
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/**
+ * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
+ * @param {string} src вміст файлу
+ * @param {number} start зміщення початку декларації
+ * @returns {string} очищений опис
+ */
+function precedingDoc(src, start) {
+  const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
+  return cleanDoc(m ? m[0] : '')
+}
+
+/**
+ * Імʼя функції, що викликається (проста Identifier або `obj.method`).
+ * @param {Record<string, unknown>} node CallExpression
+ * @returns {string|null} імʼя callee або null
+ */
+function calleeName(node) {
+  const c = node.callee
+  if (!c || typeof c !== 'object') return null
+  if (c.type === 'Identifier') return c.name
+  if (c.type === 'MemberExpression' && !c.computed && c.property?.type === 'Identifier') return c.property.name
+  return null
+}
+
+/**
+ * Множина імен, що викликаються у тілі вузла (сирі callee — фільтрація на ребра
+ * call-graph робиться у `extractUnitsJs` після збору всіх імен юнітів).
+ * @param {unknown} node AST-вузол юніта
+ * @returns {Set<string>} імена викликів
+ */
+function collectCalls(node) {
+  const names = new Set()
+  walkAstWithAncestors(node, [], n => {
+    if (n.type !== 'CallExpression') {
+      return
+    }
+
+    const name = calleeName(n)
+    if (name) names.add(name)
+  })
+  return names
+}
+
+/**
+ * Будує юніт із декларації, додає у `units`. Розпізнає function/class та
+ * const-функції (`const x = () => {}` / `function expression`).
+ * @param {Record<string, unknown>} decl декларація (function/class/variable)
+ * @param {boolean} exported чи експортується
+ * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
+ * @param {string} src вміст файлу
+ * @param {Array<object>} units акумулятор
+ * @returns {void}
+ */
+function pushUnits(decl, exported, docStart, src, units) {
+  if (!decl || typeof decl !== 'object') return
+  const doc = precedingDoc(src, docStart)
+  if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+    const name = decl.id?.name
+    if (!name) return
+    units.push({
+      name,
+      kind: decl.type === 'ClassDeclaration' ? 'class' : 'function',
+      exported,
+      span: { start: decl.start, end: decl.end },
+      body: src.slice(decl.start, decl.end),
+      calls: collectCalls(decl),
+      doc
+    })
+    return
+  }
+  if (decl.type === 'VariableDeclaration') {
+    for (const d of decl.declarations ?? []) {
+      const init = d.init
+      const isFn = init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')
+      if (!isFn || d.id?.type !== 'Identifier') continue
+      units.push({
+        name: d.id.name,
+        kind: 'const',
+        exported,
+        span: { start: init.start, end: init.end },
+        body: src.slice(init.start, init.end),
+        calls: collectCalls(init),
+        doc
+      })
+    }
+  }
+}
+
+/**
+ * Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc,
+ * прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
+ * @param {string} src вміст файлу
+ * @param {string} [relPath] шлях (для вибору мови oxc)
+ * @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)
+  if (!program || !Array.isArray(program.body)) return null
+
+  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)
+    } else {
+      pushUnits(node, false, node.start, src, units)
+    }
+  }
+
+  // Ребра call-graph: лишаємо тільки виклики інших внутрішніх юнітів
+  const names = new Set(units.map(u => u.name))
+  for (const u of units) u.calls = [...u.calls].filter(n => names.has(n) && n !== u.name)
+  return units
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7n/rules-lang-js",
-  "version": "0.2.0",
-  "description": "Плагін @7n/rules: JS/npm/bun-екосистема — taze-провайдер (package.json, bunx taze)",
+  "version": "0.3.1",
+  "description": "Плагін @7n/rules: JS/npm/bun-екосистема — taze-провайдер (package.json, bunx taze) і doc-files-екстрактори (oxc AST)",
   "keywords": [
     "javascript",
     "bun",
@@ -21,6 +21,7 @@
   },
   "type": "module",
   "files": [
+    "doc-files",
     "taze",
     "skills",
     "CHANGELOG.md",
@@ -36,7 +37,16 @@
     "contributes": {
       "rules": false,
       "handlers": {
-        "taze": "./taze/provider.mjs"
+        "taze": "./taze/provider.mjs",
+        "doc-files": "./doc-files/extractors.mjs"
+      },
+      "docFiles": {
+        "extensions": {
+          ".js": "JS Module",
+          ".mjs": "JS Module",
+          ".ts": "TS Module",
+          ".vue": "Vue Component"
+        }
       }
     }
   },

package/taze/docs/provider.md

@@ -3,7 +3,7 @@ type: JS Module
 title: provider.mjs
 resource: plugins/lang-js/taze/provider.mjs
 docgen:
-  crc: 8749ccfb
+  crc: 821a4e37
 ---
 
 ## Огляд

package/taze/provider.mjs

@@ -95,7 +95,7 @@ function runCommand(cmd, args, cwd, spawnFn) {
  * `diff.major` записи мапляться workspace → manifest (контракт порту).
  * @type {import('@7n/rules/plugin-api').EcosystemProvider}
  */
-export const jsProvider = {
+const jsProvider = {
   id: 'js-bun',
   title: 'npm/bun-пакети',
   manifestNoun: 'package.json',