@7n/rules 1.22.0 → 1.23.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.23.1] - 2026-07-18
+
+### Changed
+
+- Оновлено peer-версію @earendil-works/pi-coding-agent/pi-ai до ~0.80.10 — підтримка gpt-5.6-sol через openai-codex backend
+
+## [1.23.0] - 2026-07-18
+
+### Changed
+
+- Фаза 4a spec lang-plugins-extraction: doc-files отримав мовний extension-point — розширення (`.rs` → 'Rust Module', `.py` → 'Python Module') декларуються в маніфесті плагіна (`contributes.docFiles.extensions`, синхронно для hot-path hook), екстрактори фактів/юнітів — handler-модулем (`contributes.handlers['doc-files']`, вантажиться лише на шляху генерації). Rust-екстрактори (extractFactsRust + units-rs) виїхали в `@7n/rules-lang-rust`; ядро документує js/mjs/ts/vue вбудовано, .rs/.py — за активним lang-плагіном
+
 ## [1.22.0] - 2026-07-18
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",
@@ -86,8 +86,8 @@
   },
   "optionalDependencies": {
     "@agentclientprotocol/claude-agent-acp": "^0.59.0",
-    "@earendil-works/pi-ai": "0.80.2",
-    "@earendil-works/pi-coding-agent": "0.80.2"
+    "@earendil-works/pi-ai": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10"
   },
   "engines": {
     "bun": ">=1.3",

package/rules/doc-files/check/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/check/main.mjs
 docgen:
-  crc: 715702d3
+  crc: 2af6c6b9
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/check/main.mjs

@@ -25,7 +25,7 @@ function sourceForDoc(cwd, docRel) {
     return null
   }
   for (const e of entries) {
-    if (!e.isFile() || !isSourceFile(e.name)) continue
+    if (!e.isFile() || !isSourceFile(e.name, cwd)) continue
     if (basename(e.name, extname(e.name)) !== stem) continue
     const rel = srcDir === '.' ? e.name : `${srcDir}/${e.name}`
     if (isDocCandidate(cwd, rel)) return rel

package/rules/doc-files/docgen-crc/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-crc/main.mjs
 docgen:
-  crc: bc1835c9
+  crc: c10183ef
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-crc/main.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { basename, extname } from 'node:path'
 import { crc32 as zlibCrc32 } from 'node:zlib'
 import { env } from 'node:process'
+import { pluginDocFilesExtensions } from '../docgen-scan/lang-extensions.mjs'
 
 /** Поріг degraded: дока зі `score` нижче вважається неякісною. */
 export const QUALITY_THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? 70) || 70
@@ -66,24 +67,24 @@ export function parseDocFrontmatter(md) {
 /** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
 const MAX_ISSUE_CODES = 8
 
-/** OKF type для розширення файлу. */
+/** OKF type для вбудованих розширень; мовні (`.rs`, `.py`) декларують lang-плагіни. */
 const EXT_TYPES = {
   '.js': 'JS Module',
   '.mjs': 'JS Module',
   '.cjs': 'JS Module',
   '.ts': 'TS Module',
-  '.vue': 'Vue Component',
-  '.py': 'Python Module',
-  '.rs': 'Rust Module'
+  '.vue': 'Vue Component'
 }
 
 /**
- * OKF `type` для файлу-джерела за розширенням.
+ * OKF `type` для файлу-джерела за розширенням (вбудовані + декларації
+ * активних lang-плагінів).
  * @param {string} sourcePath відносний шлях джерела
  * @returns {string} тип концепту
  */
 function typeForSource(sourcePath) {
-  return EXT_TYPES[extname(sourcePath).toLowerCase()] ?? 'Source File'
+  const ext = extname(sourcePath).toLowerCase()
+  return EXT_TYPES[ext] ?? pluginDocFilesExtensions(process.cwd())[ext] ?? 'Source File'
 }
 
 /**

package/rules/doc-files/docgen-extract/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-extract/main.mjs
 docgen:
-  crc: 39c43eb9
+  crc: a9332a80
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-extract/main.mjs

@@ -241,201 +241,6 @@ function extractMarkers(src) {
     skips: [...skips]
   }
 }
-
-// ── Rust-екстрактор ──────────────────────────────────────────────────────────
-
-// pub fn / pub struct / pub enum / pub trait (та fn із exposure-атрибутом)
-// матчаться у два кроки по trim-нутому рядку — прості регекспи без бектрекінгу:
-// спершу опційний pub(...)-префікс, потім сама декларація
-const RS_PUB_PREFIX_RE = /^pub(?:\([^)]*\))?\s+/
-const RS_ITEM_DECL_RE = /^(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
-
-// fn-декларація у trim-нутому рядку одразу після exposure-атрибута
-const RS_FN_AFTER_ATTR_RE = /^(?:pub\s+)?(?:async\s+)?(?:unsafe\s+)?fn\s+/
-
-// Будь-яка fn-декларація без pub (для приватних localSymbols)
-const RS_PRIVATE_FN_RE = /^[ \t]*(?:async\s+)?(?:unsafe\s+)?fn\s+(\w+)/
-
-// Exposure-атрибути (#[tauri::command] тощо)
-const RS_EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/gm
-
-// use crate::module::{A, B}  або  use std::..;
-const RS_USE_RE = /^[ \t]*use\s+([\w:]+(?:::\{[^}]+\})?(?:::\*)?(?:::\w+)?)\s*;/gm
-
-// Файловий запис: fs::write / File::create / remove_file / create_dir / write_all
-const RS_WRITE_RE = /fs::write|File::create|remove_file|create_dir|BufWriter::new|OpenOptions[^;]*\.write\s*\(\s*true/
-
-// Raw-SQL запис через sqlx-подібні макро/виклики (query!/query/execute) — DML-
-// keyword одразу після відкриваючої лапки рядкового літералу (той самий
-// мінімальний тег+вміст сигнал, що й для JS tagged-template, SQL_TAGGED_MUTATION_RE)
-const RS_SQL_WRITE_RE = /\b(?:query!?|execute)\s*\(\s*"\s*(?:UPDATE|INSERT|MERGE\s+INTO|DELETE\s+FROM|UPSERT)\b/i
-
-// Обробка помилок (але не просто `?`): прості маркери; випадок
-// «match … з Err(-гілкою» — віконним обходом рядків у rsHasMatchWithErrArm
-const RS_CATCH_SIMPLE_RES = [/\.unwrap_or(?:_else|_default)?/, /if\s+let\s+Err\s*\(/, /\.map_err\s*\(/, /\.ok\s*\(\)/]
-const RS_MATCH_KW_RE = /\bmatch\s/
-const RS_ERR_ARM_RE = /\bErr\s*\(/
-
-// Функції, що повертають Result або Option
-const RS_RESULT_RE = /->\s*(?:Result|Option)\s*</
-
-// Мережа
-const RS_NETWORK_RE = /reqwest|hyper::|TcpStream|UdpSocket|tokio::net/
-
-// Кешування
-const RS_CACHE_RE = /\bcache\b|\bCache\b|lazy_static!|OnceCell|OnceLock|DashMap/i
-
-/**
- * Чи містить джерело `match`-вираз із `Err(`-гілкою неподалік (вікно 12 рядків).
- * Замінює бектрекінг-вразливу регулярку детермінованим обходом рядків.
- * @param {string[]} srcLines рядки файлу
- * @returns {boolean} true, якщо за `match` слідує `Err(`
- */
-function rsHasMatchWithErrArm(srcLines) {
-  for (let i = 0; i < srcLines.length; i++) {
-    if (!RS_MATCH_KW_RE.test(srcLines[i])) continue
-    const end = Math.min(i + 12, srcLines.length)
-    for (let j = i; j < end; j++) if (RS_ERR_ARM_RE.test(srcLines[j])) return true
-  }
-  return false
-}
-
-/**
- * Видобуває `///` doc-рядки перед рядком `lineIdx` (назад через `#[...]` та пусті рядки).
- * @param {string[]} lines рядки файлу
- * @param {number} lineIdx індекс рядка декларації
- * @returns {string} опис або ''
- */
-function rsDocBefore(lines, lineIdx) {
-  const doc = []
-  for (let i = lineIdx - 1; i >= 0; i--) {
-    const t = lines[i].trim()
-    if (t.startsWith('///')) doc.unshift(t.slice(3).trim())
-    else if (t.startsWith('#[') || t.startsWith('#![') || t === '') {
-      /* skip */
-    } else break
-  }
-  return doc.join(' ').trim()
-}
-
-/**
- * Витягує module-level doc (`//!`) із голови `.rs` файлу.
- * @param {string} src вміст файлу
- * @returns {string} злитий header-текст
- */
-function rsExtractHeader(src) {
-  const headerLines = []
-  for (const line of src.split('\n')) {
-    const t = line.trim()
-    if (t.startsWith('//!')) headerLines.push(t.slice(3).trim())
-    else if (t === '' || t.startsWith('//')) continue
-    else break
-  }
-  return headerLines.join(' ').trim()
-}
-
-/**
- * Обчислює номери рядків із `fn`, які стають фактично `pub` через exposure-атрибути.
- * @param {string} src вміст файлу
- * @param {string[]} srcLines рядки файлу
- * @returns {Set<number>} індекси exposure-exposed fn-рядків
- */
-function rsExposedLineSet(src, srcLines) {
-  const exposedLineSet = new Set()
-  for (const m of src.matchAll(RS_EXPOSURE_ATTR_RE)) {
-    // Знаходимо, який рядок містить цей атрибут
-    let pos = 0
-    for (let li = 0; li < srcLines.length; li++) {
-      if (pos + srcLines[li].length >= m.index) {
-        // Шукаємо наступний не-атрибутний рядок з fn
-        for (let nli = li + 1; nli < Math.min(li + 5, srcLines.length); nli++) {
-          const t = srcLines[nli].trim()
-          if (t.startsWith('#[') || t === '') continue
-          if (RS_FN_AFTER_ATTR_RE.test(t)) exposedLineSet.add(nli)
-          break
-        }
-        break
-      }
-      pos += srcLines[li].length + 1
-    }
-  }
-  return exposedLineSet
-}
-
-/**
- * Збирає публічні items (`pub` + exposure-exposed) `.rs` файлу.
- * @param {string[]} srcLines рядки файлу
- * @param {Set<number>} exposedLineSet індекси exposure-exposed fn-рядків
- * @returns {Array<{name:string, kind:string, desc:string}>} перелік exports
- */
-function rsCollectExports(srcLines, exposedLineSet) {
-  const exports = []
-  for (let li = 0; li < srcLines.length; li++) {
-    const trimmed = srcLines[li].trimStart()
-    const pubM = trimmed.match(RS_PUB_PREFIX_RE)
-    const m = (pubM ? trimmed.slice(pubM[0].length) : trimmed).match(RS_ITEM_DECL_RE)
-    if (m) {
-      const isPub = Boolean(pubM) || exposedLineSet.has(li)
-      if (isPub) {
-        const desc = rsDocBefore(srcLines, li)
-        exports.push({ name: m[2], kind: m[1], desc })
-      }
-    }
-  }
-  return exports
-}
-
-/**
- * Класифікує `use`-рядки `.rs` файлу на std / external / internal.
- * @param {string} src вміст файлу
- * @returns {{stdlib:string[], external:string[], internal:string[]}} згруповані imports
- */
-function rsExtractImports(src) {
-  const stdlib = new Set()
-  const external = new Set()
-  for (const m of src.matchAll(RS_USE_RE)) {
-    const path = m[1]
-    const root = path.split('::', 1)[0]
-    if (root === 'std' || root === 'core' || root === 'alloc') stdlib.add(path)
-    else external.add(path)
-  }
-  return { stdlib: [...stdlib], external: [...external], internal: [] }
-}
-
-/**
- * Витягує факт-лист для `.rs` файлу.
- * @param {string} src вміст файлу
- * @param {string} relPath відносний шлях
- * @returns {object} факт-лист без `unsupported`
- */
-function extractFactsRust(src, relPath) {
-  const header = rsExtractHeader(src)
-  const srcLines = src.split('\n')
-  const exposedLineSet = rsExposedLineSet(src, srcLines)
-  const exports = rsCollectExports(srcLines, exposedLineSet)
-
-  // localSymbols — приватні fn (не pub і не exposed) — не документуємо як публічний API
-  const localSymbols = []
-  for (const line of srcLines) {
-    const m = line.match(RS_PRIVATE_FN_RE)
-    if (m && exports.every(e => e.name !== m[1])) localSymbols.push(m[1])
-  }
-
-  const imports = rsExtractImports(src)
-
-  // markers
-  const markers = {
-    readOnly: !RS_WRITE_RE.test(src) && !RS_SQL_WRITE_RE.test(src),
-    catchesErrors: RS_CATCH_SIMPLE_RES.some(re => re.test(src)) || rsHasMatchWithErrArm(srcLines),
-    returnsFalsyOnFail: RS_RESULT_RE.test(src),
-    network: RS_NETWORK_RE.test(src),
-    caches: RS_CACHE_RE.test(src),
-    skips: []
-  }
-
-  return { relPath, lang: 'rs', header, exports, imports, internalSymbols: [], localSymbols, markers }
-}
-
 /**
  * Головний екстрактор: код файлу → факт-лист.
  * @param {string} src вміст файлу
@@ -444,7 +249,6 @@ function extractFactsRust(src, relPath) {
  */
 export function extractFacts(src, relPath) {
   const lang = relPath.split('.').pop()
-  if (lang === 'rs') return extractFactsRust(src, relPath)
   if (!['js', 'mjs', 'ts'].includes(lang)) {
     return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
   }

package/rules/doc-files/docgen-gen/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: 344e711f
+  crc: 358294dc
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/rules/doc-files/docgen-gen/main.mjs

@@ -7,6 +7,7 @@ import { runOneShot } from '@7n/llm-lib/one-shot'
 import { startChain } from '@7n/llm-lib/chain'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from '../docgen-scan/main.mjs'
+import { loadDocFilesExtractors } from '../docgen-scan/lang-extensions.mjs'
 import { extractFacts } from '../docgen-extract/main.mjs'
 import { extractAnchors, anchorTokens } from '../docgen-extract-anchors/main.mjs'
 import { QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
@@ -506,7 +507,11 @@ export async function generateDoc(
       `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
     )
   }
-  const facts = extractFacts(src, file)
+  // Мовний екстрактор з lang-плагіна (напр. `.rs` у @7n/rules-lang-rust) має
+  // пріоритет; вбудований extractFacts покриває JS-екосистему, решта — whole-file.
+  const langExtractors = await loadDocFilesExtractors(process.cwd())
+  const ext = `.${file.split('.').pop()}`.toLowerCase()
+  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? extractFacts(src, file)
   const t0 = Date.now()
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })

package/rules/doc-files/docgen-scan/docs/index.md

@@ -0,0 +1,10 @@
+---
+type: Directory Index
+title: npm/rules/doc-files/docgen-scan
+resource: npm/rules/doc-files/docgen-scan/
+---
+
+| Файл                                      | Тип       |
+| ----------------------------------------- | --------- |
+| [lang-extensions.mjs](lang-extensions.md) | JS Module |
+| [main.mjs](main.md)                       | JS Module |

package/rules/doc-files/docgen-scan/docs/lang-extensions.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: lang-extensions.mjs
+resource: npm/rules/doc-files/docgen-scan/lang-extensions.mjs
+docgen:
+  crc: 3c5bc28b
+  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 і мовні екстрактори для них, щоб інші частини системи могли підготувати обробку файла за доступними плагінними можливостями. `pluginDocFilesExtensions` формує перелік підтримуваних doc-files розширень, `loadDocFilesExtractors` підтягує екстрактори мов із плагінів, а `clearDocFilesLangCache` скидає кеш у межах прогону. Спирається на `.n-rules.json` і `.n-cursor.json` як джерело конфігурації активних плагінів та їхніх правил. Працює fail-safe: биті handler-модулі мовчки пропускає, не кидає винятків назовні, кешує стан у межах прогону.
+
+## Поведінка
+
+- `pluginDocFilesExtensions` — повертає мапу розширень doc-files, які декларують активні плагіни в репозиторії, з урахуванням кешу для поточного прогону.
+- `loadDocFilesExtractors` — завантажує мовні екстрактори з handler-модулів плагінів для doc-files і повертає їх за розширеннями; биті модулі мовчки пропускає, тож для таких файлів далі можливий whole-file шлях.
+- `clearDocFilesLangCache` — скидає внутрішній кеш мовних розширень і екстракторів, щоб наступний прогін прочитав актуальний стан заново.
+
+## Публічний API
+
+- pluginDocFilesExtensions — збирає з активних плагінів карту розширень для doc-files і тримає її в процесному кеші; порожній результат означає, що жоден плагін не оголосив підтримку.
+- loadDocFilesExtractors — підвантажує мовні extractors із plugin handler-модулів для extension-point `doc-files`; якщо модуль зламаний, його тихо пропускає і далі обробляє файл цілком.
+- clearDocFilesLangCache — очищає кеші, щоб тести починали з чистого стану.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.

package/rules/doc-files/docgen-scan/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-scan/main.mjs
 docgen:
-  crc: 6b2177db
+  crc: 66000db2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-scan/lang-extensions.mjs

@@ -0,0 +1,89 @@
+/** @see ./docs/lang-extensions.md */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { getDocFilesExtensions, getHandlers } from '../../../scripts/lib/resolve-plugins.mjs'
+
+/**
+ * Мовні розширення doc-files від плагінів (фаза 4 spec lang-plugins-extraction).
+ *
+ * Розширення (`.rs` → 'Rust Module') декларуються в МАНІФЕСТІ плагіна
+ * (`n-rules.contributes.docFiles.extensions`) — hot-path (hook на кожен файл)
+ * читає їх синхронно без динамічного import. Екстрактори фактів/юнітів —
+ * у handler-модулі (`contributes.handlers['doc-files']`), вантажаться лише
+ * на асинхронному шляху генерації.
+ */
+
+/** Кеш ініціалізації на процес: cwd → мапа розширення → тип-мітка. */
+const EXT_CACHE = new Map()
+/** Кеш завантажених екстракторів: cwd → мапа розширення → модуль-екстрактор. */
+const EXTRACTOR_CACHE = new Map()
+
+/**
+ * Синхронно читає `plugins` з `.n-rules.json` (легка версія: лише це поле,
+ * без merge/схем — той самий контракт, що `readNRulesConfigLite`, але sync
+ * для hot-path).
+ * @param {string} cwd корінь репозиторію
+ * @returns {{ plugins?: string[] }} конфіг-стаб для resolvePlugins
+ */
+function readPluginsConfigSync(cwd) {
+  for (const name of ['.n-rules.json', '.n-cursor.json']) {
+    const p = join(cwd, name)
+    if (!existsSync(p)) continue
+    try {
+      const parsed = JSON.parse(readFileSync(p, 'utf8'))
+      return { plugins: parsed.plugins }
+    } catch {
+      return {}
+    }
+  }
+  return {}
+}
+
+/**
+ * Мапа doc-files-розширень від плагінів для репо (`.rs` → 'Rust Module', …),
+ * з кешем на процес. Порожня мапа — жодний активний плагін їх не декларує.
+ * @param {string} cwd корінь репозиторію
+ * @returns {Record<string, string>} розширення → тип-мітка
+ */
+export function pluginDocFilesExtensions(cwd) {
+  const cached = EXT_CACHE.get(cwd)
+  if (cached) return cached
+  const out = getDocFilesExtensions(cwd, readPluginsConfigSync(cwd))
+  EXT_CACHE.set(cwd, out)
+  return out
+}
+
+/**
+ * Асинхронно вантажить мовні екстрактори з handler-модулів плагінів
+ * (extension-point `doc-files`): default-експорт
+ * `{ id, extensions: string[], extractFacts?, extractUnits? }`.
+ * Битий модуль — мовчазний пропуск (генерація тоді йде whole-file шляхом).
+ * @param {string} cwd корінь репозиторію
+ * @returns {Promise<Map<string, { id: string, extractFacts?: (src: string, relPath: string) => object, extractUnits?: (src: string, relPath: string) => Array<object>|null }>>} розширення → екстрактор
+ */
+export async function loadDocFilesExtractors(cwd) {
+  const cached = EXTRACTOR_CACHE.get(cwd)
+  if (cached) return cached
+  const map = new Map()
+  for (const handler of getHandlers(cwd, readPluginsConfigSync(cwd), 'doc-files')) {
+    try {
+      // eslint-disable-next-line no-unsanitized/method
+      const mod = await import(pathToFileURL(handler.modulePath).href)
+      const extractor = mod.default
+      if (!extractor || typeof extractor !== 'object' || !Array.isArray(extractor.extensions)) continue
+      for (const ext of extractor.extensions) map.set(ext, extractor)
+    } catch {
+      /* битий handler — пропускаємо, доки згенеруються whole-file шляхом */
+    }
+  }
+  EXTRACTOR_CACHE.set(cwd, map)
+  return map
+}
+
+/** Скидає кеші (для тестів). */
+export function clearDocFilesLangCache() {
+  EXT_CACHE.clear()
+  EXTRACTOR_CACHE.clear()
+}

package/rules/doc-files/docgen-scan/main.mjs

@@ -5,9 +5,14 @@ import { execFileSync } from 'node:child_process'
 
 import { isDocgenIgnored } from '../docgen-ignore/main.mjs'
 import { parseDocFrontmatter, readDocCrc, staleness } from '../docgen-crc/main.mjs'
+import { pluginDocFilesExtensions } from './lang-extensions.mjs'
 
-/** Кодові розширення, для яких генеруємо документацію. */
-const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py', '.rs'])
+/**
+ * Вбудовані кодові розширення, для яких генеруємо документацію. Мовні
+ * розширення поза JS-екосистемою (`.rs`, `.py`) декларують lang-плагіни
+ * (`n-rules.contributes.docFiles.extensions`) — див. lang-extensions.mjs.
+ */
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue'])
 
 /** `*.test.*`, `*.spec.*`, `*.stories.*` — тести й Storybook CSF-файли, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec|stories)\.[^.]+$/u
@@ -24,14 +29,18 @@ function isSystemWideDocsRoot(root) {
 }
 
 /**
- * Чи є файл кодовим джерелом для документування.
+ * Чи є файл кодовим джерелом для документування. З `root` — враховує і
+ * розширення активних lang-плагінів; без нього — лише вбудовані JS-екосистемні.
  * @param {string} fileName базове ім'я файлу
+ * @param {string} [root] корінь репозиторію (для плагінних розширень)
  * @returns {boolean} true — документуємо; false — пропускаємо
  */
-export function isSourceFile(fileName) {
+export function isSourceFile(fileName, root) {
   if (fileName.endsWith('.d.ts')) return false
   if (TEST_FILE_RE.test(fileName)) return false
-  return SOURCE_EXTENSIONS.has(extname(fileName))
+  const ext = extname(fileName)
+  if (SOURCE_EXTENSIONS.has(ext)) return true
+  return root !== undefined && ext in pluginDocFilesExtensions(root)
 }
 
 /**
@@ -55,7 +64,7 @@ export function docPathForSource(sourcePath) {
  */
 export function isDocCandidate(root, relPath) {
   const fileName = posix.basename(relPath)
-  if (!isSourceFile(fileName)) return false
+  if (!isSourceFile(fileName, root)) return false
   if (isSystemWideDocsRoot(root) && posix.dirname(relPath) === '.') return false
   return !isDocgenIgnored(relPath)
 }
@@ -203,7 +212,7 @@ export function scanForDocFiles(root) {
       if (entry.isDirectory()) {
         if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
-      } else if (entry.isFile() && isSourceFile(entry.name)) {
+      } else if (entry.isFile() && isSourceFile(entry.name, root)) {
         if (isSystemWideDocsRoot(root) && dirname(relPath) === '.') continue
         const sourcePath = relPath.split(sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue

package/rules/doc-files/units/docs/main.md

@@ -3,9 +3,8 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/units/main.mjs
 docgen:
-  crc: b304d152
+  crc: 8acdefc1
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
   score: 100
   issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini

package/rules/doc-files/units/main.mjs

@@ -1,13 +1,13 @@
 /** @see ./docs/units.md */
 
 import { extractUnitsJs } from '../units-js/main.mjs'
-import { extractUnitsRs } from '../units-rs/main.mjs'
 
 const JS_EXT = new Set(['js', 'mjs', 'ts', 'jsx', 'tsx', 'cts', 'mts'])
 
 /**
  * Мовно-агностичний фасад юніт-шару. Диспатчить за розширенням:
- * js/mjs/ts → oxc AST; rs → regex+brace-counting; vue/py → null (whole-file шлях).
+ * js/mjs/ts → oxc AST; інші мови (rs — lang-плагін, extension-point
+ * `doc-files`.extractUnits; vue/py) → null (whole-file шлях).
  * @param {string} src вміст файлу
  * @param {string} relPath шлях файлу
  * @returns {Array<object>|null} юніти або null, якщо мова ще не підтримана / файл не парситься
@@ -15,6 +15,5 @@ const JS_EXT = new Set(['js', 'mjs', 'ts', 'jsx', 'tsx', 'cts', 'mts'])
 export function extractUnits(src, relPath) {
   const ext = (relPath.split('.').pop() || '').toLowerCase()
   if (JS_EXT.has(ext)) return extractUnitsJs(src, relPath)
-  if (ext === 'rs') return extractUnitsRs(src, relPath)
   return null
 }

package/scripts/lib/docs/resolve-plugins.md

@@ -3,7 +3,7 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: 17248373
+  crc: 0d197e39
 ---
 
 Резолв плагінів @7n/rules: визначає, які пакети-плагіни активні у проєкті, де їхні `rules/`-каталоги, які capabilities вони надають і які handlers надають.

package/scripts/lib/resolve-plugins.mjs

@@ -56,7 +56,7 @@ function hasLangSignal(projectRoot, signal, maxDepth) {
   let level = [projectRoot]
   for (let depth = 0; depth <= maxDepth && level.length > 0; depth++) {
     if (level.some(dir => existsSync(join(dir, signal)))) return true
-    if (depth < maxDepth) level = level.flatMap(listScannableSubdirs)
+    if (depth < maxDepth) level = level.flatMap(dir => listScannableSubdirs(dir))
   }
   return false
 }
@@ -192,7 +192,7 @@ export function ensurePluginInstalled(projectRoot, packageName) {
  * @property {string} name npm-ім'я пакета (`@7n/rules` для ядра)
  * @property {string} packageRoot абсолютний корінь пакета
  * @property {string} rulesDir абсолютний шлях до `rules/` пакета
- * @property {{ capabilities: string[], contributes: { rules?: boolean, handlers?: Record<string, string> } }} manifest нормалізований блок `n-rules` з package.json плагіна
+ * @property {{ capabilities: string[], contributes: { rules?: boolean, handlers?: Record<string, string>, docFilesExtensions?: Record<string, string> } }} manifest нормалізований блок `n-rules` з package.json плагіна
  */
 
 /**
@@ -202,7 +202,7 @@ export function ensurePluginInstalled(projectRoot, packageName) {
  */
 function readPluginManifest(packageRoot) {
   /** @type {ResolvedPlugin['manifest']} */
-  const fallback = { capabilities: [], contributes: { rules: true, handlers: {} } }
+  const fallback = { capabilities: [], contributes: { rules: true, handlers: {}, docFilesExtensions: {} } }
   try {
     const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
     const raw = pkg?.['n-rules']
@@ -213,7 +213,17 @@ function readPluginManifest(packageRoot) {
       contributes.handlers && typeof contributes.handlers === 'object' && !Array.isArray(contributes.handlers)
         ? Object.fromEntries(Object.entries(contributes.handlers).filter(([, v]) => typeof v === 'string'))
         : {}
-    return { capabilities, contributes: { rules: contributes.rules !== false, handlers } }
+    // Декларативні doc-files-розширення (`docFiles.extensions`: '.rs' → 'Rust Module') —
+    // саме в маніфесті, а не в handler-модулі, щоб hot-path (hook per-file) читав їх
+    // синхронно без динамічного import.
+    const rawDocFiles = contributes.docFiles && typeof contributes.docFiles === 'object' ? contributes.docFiles : {}
+    const docFilesExtensions =
+      rawDocFiles.extensions && typeof rawDocFiles.extensions === 'object' && !Array.isArray(rawDocFiles.extensions)
+        ? Object.fromEntries(
+            Object.entries(rawDocFiles.extensions).filter(([k, v]) => k.startsWith('.') && typeof v === 'string')
+          )
+        : {}
+    return { capabilities, contributes: { rules: contributes.rules !== false, handlers, docFilesExtensions } }
   } catch {
     return fallback
   }
@@ -295,6 +305,22 @@ export function getActiveCapabilities(projectRoot, config, options = {}) {
   return caps
 }
 
+/**
+ * Агреговані doc-files-розширення активних плагінів: '.rs' → 'Rust Module' тощо.
+ * Синхронно і без установки (hot-path hook) — лише вже встановлені плагіни.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @returns {Record<string, string>} мапа розширення → тип-мітка доки
+ */
+export function getDocFilesExtensions(projectRoot, config) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  for (const p of resolvePlugins(projectRoot, config, { allowInstall: false, quiet: true })) {
+    Object.assign(out, p.manifest.contributes.docFilesExtensions)
+  }
+  return out
+}
+
 /**
  * Handlers для extension-point правила ядра (v1 — лише API; перший споживач — v2).
  * @param {string} projectRoot корінь репозиторію

package/skills/doc-files/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: doc-files
 description: >-
-  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue вбудовано; rs/py — через lang-плагіни) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
 version: '1.0'
 ---
 

package/rules/doc-files/units-rs/concern.json

@@ -1,3 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
-}

package/rules/doc-files/units-rs/docs/main.md

@@ -1,36 +0,0 @@
----
-type: JS Module
-title: main.mjs
-resource: npm/rules/doc-files/units-rs/main.mjs
-docgen:
-  crc: 45adb1a4
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Огляд:
-Цей файл відповідає за аналіз коду з метою вилучення інформації про публічно доступні елементи, зокрема, про структуру та методи. Він ідентифікує відображені елементи на підставі їхніх атрибутів або публічності, збираючи повні описи та тіла їхніх декларацій. Зокрема, функція `extractUnitsRs` забезпечує можливість автоматично генерувати технічну документацію, детально описуючи призначення кожного публічного елемента.
-
-## Поведінка
-
-Поведінка:
-
-1. Функція `extractUnitsRs` аналізує вміст файлу з кодом.
-2. Функція визначає всі визначені верхнерівневі та методи в блоках `impl`.
-3. Визначення відображеності (exported) елементів відбувається на основі атрибутів, таких як `tauri::command`, або якщо функція звичайного виклику є вказана як публічна.
-4. Для кожного знайденого елемента видобувається повний текстовий опис, що йде безпосередньо перед його декларацією.
-5. Для функції, структури, перерахування, трейту або типу видобувається повний вміст тіла декларації.
-6. Визначається, до якого блоку `impl` належить елемент, якщо він не є верхнерівневим.
-7. Для вилучених елементів ідентифікуються внутрішні виклики до інших юнітів у межах того ж файлу.
-
-## Публічний API
-
-extractUnitsRs — витягує основні та реалізовані методи з файлів Rust.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/units-rs/main.mjs

@@ -1,311 +0,0 @@
-/** @see ./docs/units-rs.md */
-
-/**
- * Пропускає рядковий літерал `"..."` (з escape-послідовностями).
- * @param {string} src вміст файлу
- * @param {number} i позиція відкриваючого `"`
- * @returns {number} позиція ПІСЛЯ закриваючого `"`
- */
-function skipString(src, i) {
-  i++ // відкриваючий "
-  while (i < src.length) {
-    if (src[i] === '\\') {
-      i += 2
-      continue
-    }
-    if (src[i] === '"') return i + 1
-    i++
-  }
-  return i
-}
-
-/**
- * Пропускає рядковий (`//`) чи блочний коментар на позиції `i`.
- * @param {string} src вміст файлу
- * @param {number} i позиція `/` початку коментаря
- * @returns {number} позиція ПІСЛЯ коментаря, або `-1` якщо на `i` не коментар
- */
-function skipComment(src, i) {
-  if (src[i] !== '/') return -1
-  if (src[i + 1] === '/') {
-    const nl = src.indexOf('\n', i)
-    return nl === -1 ? src.length : nl + 1
-  }
-  if (src[i + 1] === '*') {
-    const end = src.indexOf('*/', i + 2)
-    return end === -1 ? src.length : end + 2
-  }
-  return -1
-}
-
-/**
- * Знаходить індекс закриваючої `}` для відкриваючої `{` на позиції `start`.
- * Правильно пропускає рядки/блочні коментарі та рядкові літерали.
- * @param {string} src вміст файлу
- * @param {number} start позиція відкриваючої `{`
- * @returns {number} індекс `}` або -1, якщо не знайдено
- */
-function findClosingBrace(src, start) {
-  let depth = 0
-  let i = start
-  while (i < src.length) {
-    const ch = src[i]
-    const afterComment = skipComment(src, i)
-    if (afterComment !== -1) {
-      i = afterComment
-      continue
-    }
-    if (ch === '"') {
-      i = skipString(src, i)
-      continue
-    }
-    if (ch === '{') {
-      depth++
-      i++
-      continue
-    }
-    if (ch === '}') {
-      depth--
-      if (depth === 0) return i
-      i++
-      continue
-    }
-    i++
-  }
-  return -1
-}
-
-/**
- * Видобуває `///` doc-рядки безпосередньо перед рядком `lineIdx`.
- * Сканує назад через `///`, `#[...]` та пусті рядки.
- * @param {string[]} lines рядки файлу
- * @param {number} lineIdx рядок декларації
- * @returns {string} склеєний опис або ''
- */
-function docBefore(lines, lineIdx) {
-  const doc = []
-  for (let i = lineIdx - 1; i >= 0; i--) {
-    const t = lines[i].trim()
-    if (t.startsWith('///')) {
-      doc.unshift(t.slice(3).trim())
-    } else if (t.startsWith('#[') || t.startsWith('#![') || t === '') {
-      // пропустити атрибути та пусті рядки
-    } else {
-      break
-    }
-  }
-  return doc.join(' ').trim()
-}
-
-// Pub-items матчаться у два кроки по trim-нутому рядку (прості регекспи без
-// бектрекінгу): спершу опційний pub(...)-префікс, потім сама декларація.
-// Також ловить fn без pub (для localSymbols і impl-методів)
-const PUB_PREFIX_RE = /^pub(?:\([^)]*\))?\s+/
-const ITEM_DECL_RE = /^(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
-
-// impl Type { або impl<T> Trait for Type { — теж двокроково: голова `impl<...>`,
-// далі тип після `for` (trait-impl) або перше слово (inherent impl)
-const IMPL_HEAD_RE = /^impl(?:<[^>]*>)?\s+/
-const IMPL_FOR_TYPE_RE = /\bfor\s+(\w+)/
-const TYPE_NAME_RE = /^(\w+)/
-
-// Підозрілі exposure-атрибути, що роблять непуб-fn фактично публічними
-const EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/
-
-// Базовий виклик fn-імені (для call-graph всередині юніта)
-const CALL_RE = /\b([a-z_]\w*)\s*\(/g
-
-/**
- * Рахує дельту глибини `{}` в рядку, пропускаючи `//`-коментарі й рядкові літерали.
- * @param {string} line рядок коду
- * @returns {number} приріст глибини (додатний — відкрито більше, ніж закрито)
- */
-function braceDeltaInLine(line) {
-  let delta = 0
-  let j = 0
-  while (j < line.length) {
-    const ch = line[j]
-    if (ch === '/' && line[j + 1] === '/') break
-    if (ch === '"') {
-      j++
-      while (j < line.length && line[j] !== '"') {
-        if (line[j] === '\\') j++
-        j++
-      }
-      j++
-      continue
-    }
-    if (ch === '{') delta++
-    else if (ch === '}') delta--
-    j++
-  }
-  return delta
-}
-
-/**
- * Оновлює impl-стек за поточним рядком: прибирає закриті impl і, якщо рядок — impl-
- * декларація на глибині ≤1, додає новий запис.
- * @param {Array<{typeName:string, openDepth:number}>} implStack стек відкритих impl (мутується)
- * @param {string} line сирий рядок
- * @param {string} trimmed рядок без лідируючих пробілів
- * @param {number} depth глибина ПІСЛЯ обробки рядка
- * @param {number} depthAtStart глибина ДО обробки рядка
- * @returns {void}
- */
-function updateImplStack(implStack, line, trimmed, depth, depthAtStart) {
-  while (implStack.length > 0 && implStack.at(-1).openDepth > depth) {
-    implStack.pop()
-  }
-  if (depthAtStart <= 1) {
-    const headM = trimmed.match(IMPL_HEAD_RE)
-    if (headM && line.includes('{')) {
-      const rest = trimmed.slice(headM[0].length)
-      const typeM = rest.match(IMPL_FOR_TYPE_RE) ?? rest.match(TYPE_NAME_RE)
-      if (typeM) implStack.push({ typeName: typeM[1], openDepth: depth })
-    }
-  }
-}
-
-/**
- * Витягує тіло item-а (fn/struct/enum/trait) через `findClosingBrace`.
- * @param {string} src вміст файлу
- * @param {string[]} lines рядки файлу
- * @param {number} li індекс рядка декларації
- * @param {number} lineOffset зсув початку рядка в `src`
- * @param {string} kind вид item-а
- * @returns {{body:string, itemEnd:number}} тіло та зсув кінця item-а
- */
-function extractItemBody(src, lines, li, lineOffset, kind) {
-  let body = ''
-  let itemEnd = lineOffset + lines[li].length
-  if (kind !== 'type') {
-    const openBraceIdx = src.indexOf('{', lineOffset)
-    // Шукаємо `{` не далі ніж через 3 рядки від початку декларації
-    const threeLines = lines.slice(li, li + 3).join('\n').length
-    if (openBraceIdx !== -1 && openBraceIdx - lineOffset <= threeLines) {
-      const closeIdx = findClosingBrace(src, openBraceIdx)
-      if (closeIdx !== -1) {
-        itemEnd = closeIdx + 1
-        body = src.slice(lineOffset, itemEnd)
-      }
-    }
-  }
-  return { body, itemEnd }
-}
-
-/**
- * Заповнює `calls` кожного юніта викликами інших юнітів цього ж файлу.
- * @param {Array<{name:string, body:string, calls:string[]}>} units юніти файлу (мутуються)
- * @returns {void}
- */
-function fillCallGraph(units) {
-  const unitNames = new Set(units.map(u => u.name))
-  for (const u of units) {
-    if (!u.body) continue
-    const calls = new Set()
-    let cm
-    const re = new RegExp(CALL_RE.source, 'g')
-    while ((cm = re.exec(u.body)) !== null) {
-      if (unitNames.has(cm[1]) && cm[1] !== u.name) calls.add(cm[1])
-    }
-    u.calls = [...calls]
-  }
-}
-
-/**
- * Обробляє рядок на глибині ≤1: якщо це декларація item-а — додає юніт у `units`;
- * інакше скидає exposure-флаг на не-атрибутних рядках. Повертає новий стан флага.
- * @param {object} p параметри
- * @param {string} p.src вміст файлу
- * @param {string[]} p.lines рядки файлу
- * @param {number} p.li індекс рядка
- * @param {number} p.lineOffset зсув початку рядка в `src`
- * @param {number} p.depthAtStart глибина ДО обробки рядка
- * @param {string|null} p.currentImpl тип поточного impl або `null`
- * @param {boolean} p.nextFnExposed чи наступний fn exposure-exposed
- * @param {Array<object>} p.units акумулятор юнітів (мутується)
- * @returns {boolean} новий стан `nextFnExposed`
- */
-function processItemLine({ src, lines, li, lineOffset, depthAtStart, currentImpl, nextFnExposed, units }) {
-  const line = lines[li]
-  const trimmed = line.trimStart()
-  const pubM = trimmed.match(PUB_PREFIX_RE)
-  const m = (pubM ? trimmed.slice(pubM[0].length) : trimmed).match(ITEM_DECL_RE)
-  if (!m) {
-    // Рядок не є item — скидаємо exposure-флаг якщо не атрибут
-    const t = line.trim()
-    if (!t.startsWith('#[') && !t.startsWith('#![') && !t.startsWith('///') && t !== '') return false
-    return nextFnExposed
-  }
-  const kind = m[1]
-  const isPub = Boolean(pubM) || (kind === 'fn' && nextFnExposed)
-  const doc = docBefore(lines, li)
-  // Витягуємо тіло через findClosingBrace для fn/struct/enum/trait
-  const { body, itemEnd } = extractItemBody(src, lines, li, lineOffset, kind)
-  units.push({
-    name: m[2],
-    kind,
-    exported: isPub,
-    implName: depthAtStart === 1 ? currentImpl : null,
-    span: { start: lineOffset, end: itemEnd },
-    body,
-    calls: [],
-    doc
-  })
-  return kind === 'fn' ? false : nextFnExposed
-}
-
-/**
- * Юніт-екстрактор для `.rs` файлів.
- * Визначає top-level і impl-методи через підрахунок дужок по рядках.
- * Відомі обмеження: рядкові літерали з `{`/`}` всередині `{}` можуть дати
- * хибну глибину (рідкісно в реальному Rust-коді з rustfmt).
- * @param {string} src вміст файлу
- * @param {string} [_relPath] резервний (не використовується)
- * @returns {Array<{name:string, kind:string, exported:boolean, implName:string|null, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти файлу (fn та impl-методи) або `null`, якщо юнітів не знайдено
- */
-export function extractUnitsRs(src, _relPath) {
-  const lines = src.split('\n')
-  const units = []
-  let depth = 0
-  let lineOffset = 0
-  // Стек відкритих impl: { typeName, openDepth }
-  const implStack = []
-  // Флаг: наступний fn отримує exposure (через #[tauri::command] тощо)
-  let nextFnExposed = false
-
-  for (let li = 0; li < lines.length; li++) {
-    const line = lines[li]
-    const depthAtStart = depth
-    depth += braceDeltaInLine(line)
-
-    updateImplStack(implStack, line, line.trimStart(), depth, depthAtStart)
-    const currentImpl = implStack.at(-1)?.typeName ?? null
-
-    // Перевіряємо exposure-атрибути
-    if (EXPOSURE_ATTR_RE.test(line)) {
-      nextFnExposed = true
-    }
-
-    // Елементи на глибині 0 (top-level) і 1 (всередині impl)
-    if (depthAtStart <= 1) {
-      nextFnExposed = processItemLine({
-        src,
-        lines,
-        li,
-        lineOffset,
-        depthAtStart,
-        currentImpl,
-        nextFnExposed,
-        units
-      })
-    }
-
-    lineOffset += line.length + 1 // +1 для '\n'
-  }
-
-  // Базовий call-graph: виклики інших юнітів цього файлу
-  fillCallGraph(units)
-
-  return units.length > 0 ? units : null
-}