@7n/rules 1.21.0 → 1.23.0

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/skills/taze/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/skills/taze/js/orchestrate.mjs
 docgen:
-  crc: b675f6e7
+  crc: bce1f492
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98

package/skills/taze/js/orchestrate.mjs

@@ -1,8 +1,8 @@
 /** @see ./docs/orchestrate.md */
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
-import { copyFile, rm } from 'node:fs/promises'
-import { join } from 'node:path'
+import { copyFile, mkdir, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { assertEcosystemProvider } from '../../../scripts/lib/plugin-api.mjs'
@@ -81,28 +81,122 @@ export async function callRunner(runner, prompt, cwd, deps = {}) {
 }
 
 /**
- * Перевіряє, що `cwd` — ізольований worktree (`main.json.worktree: true`,
- * той самий контракт, що й для інших worktree-only скілів). Раніше цю
- * гарантію тримав агент, читаючи SKILL.md-preflight як частину промпту;
- * оркестратор більше НЕ годує SKILL.md жодному викликові, тож без цієї
- * перевірки `bunx taze -w -r latest`/`bun install` мовчки виконались би
- * прямо в основному дереві виклику. Кидає, якщо `git rev-parse --show-toplevel`
- * не містить `.worktrees` як сегмент шляху (покриває і `npx \@7n/mt worktree
- * create`-конвенцію `.worktrees/`, і сесійну `.claude/worktrees/`).
+ * Гарантує, що подальші кроки оркестратора виконуються в ізольованому
+ * worktree (`main.json.worktree: true`, той самий контракт, що й для інших
+ * worktree-only скілів). Оркестратор не годує SKILL.md жодному агенту, тож
+ * замість покладатись на агента, що читає SKILL.md-preflight, сам детерміновано
+ * створює worktree конвенцією `<current-branch>-taze` (`npx \@7n/mt worktree
+ * create`) і ставить залежності — щоб `bunx taze -w -r latest`/`bun install`
+ * ніколи не виконались прямо в основному дереві виклику. `autoCreated: true`
+ * сигналить викликачеві, що після завершення прогону варто перенести зміни
+ * назад (`bringChangesBackToOriginal`) і прибрати worktree
+ * (`removeAutoCreatedWorktree`) — а не лишати сирітське дерево.
  * @param {string} cwd каталог для перевірки
  * @param {typeof spawnSync} spawnFn інжект для тестів
- * @returns {void}
+ * @param {(line: string) => void} log колбек прогресу
+ * @returns {{ cwd: string, autoCreated: boolean, branchArg: string|null }} `autoCreated: false` — `cwd` без змін
+ *   (вже worktree); `autoCreated: true` — `cwd` щойно створеного worktree і `branchArg`, з яким його створено
  */
-function assertRunningInWorktree(cwd, spawnFn) {
-  const result = spawnFn('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
-  const toplevel = result.status === 0 ? result.stdout.trim() : ''
+function ensureRunningInWorktree(cwd, spawnFn, log) {
+  const toplevelResult = spawnFn('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
+  const toplevel = toplevelResult.status === 0 ? toplevelResult.stdout.trim() : ''
   const segments = new Set(toplevel.replaceAll('\\', '/').split('/'))
-  if (!segments.has('.worktrees')) {
+  if (segments.has('.worktrees')) return { cwd, autoCreated: false, branchArg: null }
+
+  const branchResult = spawnFn('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' })
+  const currentBranch = branchResult.status === 0 ? branchResult.stdout.trim() : ''
+  if (!currentBranch) {
     throw new Error(
-      `taze: "${cwd}" не в ізольованому worktree (git toplevel: "${toplevel || '?'}"). ` +
-        'main.json.worktree=true вимагає окремого дерева — створи його спершу (див. SKILL.md preflight), не запускай taze в основному дереві.'
+      `taze: "${cwd}" не в ізольованому worktree (git toplevel: "${toplevel || '?'}"), і поточну гілку визначити не вдалось ` +
+        '(detached HEAD?) — автоматичне створення worktree за конвенцією `<current-branch>-taze` неможливе. Перейди на гілку вручну.'
     )
   }
+
+  const branchArg = `${currentBranch}-taze`
+  const pathSegment = branchArg.replaceAll('/', '-')
+  log(`⚠️ "${cwd}" не в ізольованому worktree — створюю ".worktrees/${pathSegment}"...`)
+  runCommand('npx', ['@7n/mt', 'worktree', 'create', branchArg, 'n-taze: worktree-only skill'], cwd, spawnFn)
+
+  const newCwd = join(cwd, '.worktrees', pathSegment)
+  log('📥 bun install (bootstrap нового дерева)...')
+  runCommand('bun', ['install'], newCwd, spawnFn)
+  return { cwd: newCwd, autoCreated: true, branchArg }
+}
+
+/**
+ * Переносить зміни з автоствореного worktree назад у вихідне дерево як
+ * **untracked/незакомічені** правки (просте копіювання файлів, без git
+ * merge/cherry-pick) — так само, як їх бачив би користувач, якби сам
+ * працював у вихідному дереві. Джерело істини — `git status --porcelain`
+ * у worktree: для кожного шляху копіює файл, якщо він існує (модифікація/
+ * додавання), або видаляє його у вихідному дереві, якщо existsSync каже,
+ * що в worktree його вже нема (видалення). Перейменування (`old -> new` у
+ * porcelain) переносять лише нову назву — стара лишається як була, це
+ * прийнятний компроміс: taze не перейменовує файли сам, ефект можливий
+ * лише як побічний результат LLM-рефакторингу.
+ * @param {string} worktreeCwd автостворений worktree, з якого переносимо
+ * @param {string} originalCwd вихідне дерево, куди переносимо
+ * @param {typeof spawnSync} spawnFn інжект для тестів
+ * @param {(line: string) => void} log колбек прогресу
+ * @param {{ copyFile?: (src: string, dest: string) => Promise<void>, rm?: (path: string, opts?: object) => Promise<void>, mkdir?: (path: string, opts?: object) => Promise<void> }} [deps] інжекти для тестів
+ * @returns {Promise<string[]>} відносні шляхи перенесених файлів
+ */
+export async function bringChangesBackToOriginal(worktreeCwd, originalCwd, spawnFn, log, deps = {}) {
+  const copy = deps.copyFile ?? copyFile
+  const removeFile = deps.rm ?? rm
+  const makeDir = deps.mkdir ?? mkdir
+
+  const statusResult = spawnFn('git', ['status', '--porcelain'], { cwd: worktreeCwd, encoding: 'utf8' })
+  if (statusResult.status !== 0) {
+    log(
+      `⚠️ Не вдалось прочитати git status у "${worktreeCwd}" — зміни НЕ перенесені назад, worktree лишиться для ручного розбору.`
+    )
+    return []
+  }
+
+  const lines = statusResult.stdout.split('\n').filter(Boolean)
+  if (lines.length === 0) {
+    log('ℹ️ Worktree без змін — нічого переносити назад.')
+    return []
+  }
+
+  const brought = []
+  for (const line of lines) {
+    const rest = line.slice(3)
+    const relPath = rest.includes(' -> ') ? rest.split(' -> ', 2)[1] : rest
+    const srcPath = join(worktreeCwd, relPath)
+    const destPath = join(originalCwd, relPath)
+    if (existsSync(srcPath)) {
+      await makeDir(dirname(destPath), { recursive: true })
+      await copy(srcPath, destPath)
+    } else {
+      await removeFile(destPath, { force: true })
+    }
+    brought.push(relPath)
+  }
+  log(`📤 Перенесено назад у "${originalCwd}" як untracked: ${brought.join(', ')}`)
+  return brought
+}
+
+/**
+ * Прибирає автостворений worktree разом з його ефемерною git-гілкою
+ * (`npx \@7n/mt worktree remove <branch>`) — викликати лише ПІСЛЯ
+ * `bringChangesBackToOriginal`, інакше зміни згорять разом з деревом.
+ * Не кидає при провалі — це прибирання, а не крок, від якого залежить
+ * результат прогону; провал лише логується, worktree лишається для
+ * ручного розбору.
+ * @param {string} branchArg гілка, з якою worktree був створений (з `ensureRunningInWorktree`)
+ * @param {string} originalCwd вихідне дерево, звідки виконати `npx \@7n/mt worktree remove`
+ * @param {typeof spawnSync} spawnFn інжект для тестів
+ * @param {(line: string) => void} log колбек прогресу
+ * @returns {void}
+ */
+export function removeAutoCreatedWorktree(branchArg, originalCwd, spawnFn, log) {
+  log(`🧹 Прибираю автостворений worktree "${branchArg}"...`)
+  const result = spawnFn('npx', ['@7n/mt', 'worktree', 'remove', branchArg], { cwd: originalCwd, encoding: 'utf8' })
+  if (result.status !== 0) {
+    log(`⚠️ Не вдалось прибрати worktree "${branchArg}" — приберіть вручну (${result.stderr || result.stdout})`)
+  }
 }
 
 /**
@@ -329,62 +423,79 @@ export function formatReport({ minorPatch, totalChanged, results, ecosystems = [
  * @returns {Promise<{ ok: boolean, report: string, results: Array<object>, ecosystems: Array<object> }>} результат
  */
 export async function runTazeOrchestrator(options = {}) {
-  const cwd = options.cwd ?? process.cwd()
   const runner = options.runner ?? 'pi'
   const log = options.log ?? (line => console.log(line))
   const deps = options.deps ?? {}
   const spawnFn = deps.spawnFn ?? spawnSync
   const call = deps.callRunner ?? callRunner
 
-  assertRunningInWorktree(cwd, spawnFn)
-
-  // npm/bun-гілка активна лише за кореневим package.json — на чисто-Python/Rust
-  // репо `bun install` падає з exit 1, і без цього гейта весь прогін гинув би
-  // до екосистемних провайдерів. Той самий принцип «тиші», що й для мовних
-  // екосистем: немає сигналу — немає ані кроків, ані згадки у звіті.
-  const npmPresent = existsSync(join(cwd, 'package.json'))
-  let diff = { major: [], minorPatch: 0, totalChanged: 0 }
-  const results = []
-  if (npmPresent) {
-    log('📦 Бекап package.json...')
-    const backedUpWorkspaces = await backupWorkspacePackageFiles(cwd, deps)
-
-    log('⬆️  bunx taze -w -r latest...')
-    runCommand('bunx', ['taze', '-w', '-r', 'latest'], cwd, spawnFn)
-    log('📥 bun install...')
-    runCommand('bun', ['install'], cwd, spawnFn)
-
-    const collectDiff = deps.collectTazeDiff ?? collectTazeDiff
-    diff = await collectDiff(cwd)
-    log(`🔍 diff: ${diff.major.length} major, ${diff.minorPatch} minor/patch`)
+  const originalCwd = options.cwd ?? process.cwd()
+  const worktree = ensureRunningInWorktree(originalCwd, spawnFn, log)
+  const cwd = worktree.cwd
 
-    for (const entry of diff.major) {
-      log(`🔧 ${entry.pkg} (${entry.workspace}): ${entry.from} → ${entry.to}...`)
-      const outcome = await call(runner, buildDependencyPrompt(entry), cwd, deps)
-      results.push({ ...entry, ...outcome })
-      log(outcome.ok ? `  ✅ ${entry.pkg}` : `  ❌ ${entry.pkg}: ${outcome.error}`)
+  try {
+    // npm/bun-гілка активна лише за кореневим package.json — на чисто-Python/Rust
+    // репо `bun install` падає з exit 1, і без цього гейта весь прогін гинув би
+    // до екосистемних провайдерів. Той самий принцип «тиші», що й для мовних
+    // екосистем: немає сигналу — немає ані кроків, ані згадки у звіті.
+    const npmPresent = existsSync(join(cwd, 'package.json'))
+    let diff = { major: [], minorPatch: 0, totalChanged: 0 }
+    const results = []
+    if (npmPresent) {
+      log('📦 Бекап package.json...')
+      const backedUpWorkspaces = await backupWorkspacePackageFiles(cwd, deps)
+
+      log('⬆️  bunx taze -w -r latest...')
+      runCommand('bunx', ['taze', '-w', '-r', 'latest'], cwd, spawnFn)
+      log('📥 bun install...')
+      runCommand('bun', ['install'], cwd, spawnFn)
+
+      const collectDiff = deps.collectTazeDiff ?? collectTazeDiff
+      diff = await collectDiff(cwd)
+      log(`🔍 diff: ${diff.major.length} major, ${diff.minorPatch} minor/patch`)
+
+      for (const entry of diff.major) {
+        log(`🔧 ${entry.pkg} (${entry.workspace}): ${entry.from} → ${entry.to}...`)
+        const outcome = await call(runner, buildDependencyPrompt(entry), cwd, deps)
+        results.push({ ...entry, ...outcome })
+        log(outcome.ok ? `  ✅ ${entry.pkg}` : `  ❌ ${entry.pkg}: ${outcome.error}`)
+      }
+
+      await cleanupBackups(cwd, backedUpWorkspaces, deps)
+    } else {
+      log('⏭ npm/bun: кореневого package.json немає — гілка пропущена')
     }
 
-    await cleanupBackups(cwd, backedUpWorkspaces, deps)
-  } else {
-    log('⏭ npm/bun: кореневого package.json немає — гілка пропущена')
-  }
+    const providers = deps.ecosystemProviders ?? (await loadPluginTazeProviders(cwd, log, deps))
+    const ecosystems = []
+    for (const provider of providers) {
+      ecosystems.push(await runEcosystem(provider, { cwd, runner, log, deps, spawnFn, call }))
+    }
 
-  const providers = deps.ecosystemProviders ?? (await loadPluginTazeProviders(cwd, log, deps))
-  const ecosystems = []
-  for (const provider of providers) {
-    ecosystems.push(await runEcosystem(provider, { cwd, runner, log, deps, spawnFn, call }))
+    const report = formatReport({
+      minorPatch: diff.minorPatch,
+      totalChanged: diff.totalChanged,
+      results,
+      ecosystems,
+      npmPresent
+    })
+    log(report)
+
+    const ecosystemsOk = ecosystems.every(eco => eco.error === null && eco.results.every(r => r.ok))
+    return { ok: results.every(r => r.ok) && ecosystemsOk, report, results, ecosystems }
+  } finally {
+    // Лише для АВТОстворених worktree — якщо викликач уже сидів у своєму
+    // worktree (worktree.autoCreated === false), це не наш worktree і не
+    // нам його чіпати/прибирати. `finally` — щоб зміни поверталися і
+    // сирітський worktree прибирався навіть при кинутому винятку всередині
+    // try (падіння bunx/diff/провайдера), а не лише при успішному прогоні.
+    if (worktree.autoCreated) {
+      try {
+        await bringChangesBackToOriginal(cwd, originalCwd, spawnFn, log, deps)
+      } catch (error) {
+        log(`⚠️ Перенесення змін назад провалилось: ${error instanceof Error ? error.message : String(error)}`)
+      }
+      removeAutoCreatedWorktree(worktree.branchArg, originalCwd, spawnFn, log)
+    }
   }
-
-  const report = formatReport({
-    minorPatch: diff.minorPatch,
-    totalChanged: diff.totalChanged,
-    results,
-    ecosystems,
-    npmPresent
-  })
-  log(report)
-
-  const ecosystemsOk = ecosystems.every(eco => eco.error === null && eco.results.every(r => r.ok))
-  return { ok: results.every(r => r.ok) && ecosystemsOk, report, results, ecosystems }
 }

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: не виконує операцій запису (ФС/БД).