@7n/rules-lang-js 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.2.0] - 2026-07-19
+
+### Added
+
+- Перший реліз: EcosystemProvider npm/bun для taze-оркестратора `@7n/rules` (extension-point `taze`, контракт `@7n/rules/plugin-api`) — фаза 5a spec lang-plugins-extraction: JS-екосистема стала таким самим плагіном, як Rust/Python, ядро — двигун без мовної специфіки. Бекап package.json воркспейсів, bump через `bunx taze -w -r latest` + `bun install`, детермінований `collectTazeDiff` (semver caret-класифікація), CLI `n-rules taze diff` — через handler плагіна. Автодетект — за кореневим `package.json`
+
+All notable changes to this project will be documented in this file.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@7n/rules-lang-js",
+  "version": "0.2.0",
+  "description": "Плагін @7n/rules: JS/npm/bun-екосистема — taze-провайдер (package.json, bunx taze)",
+  "keywords": [
+    "javascript",
+    "bun",
+    "taze",
+    "n-rules-plugin"
+  ],
+  "homepage": "https://github.com/nitra/7n-rules#readme",
+  "bugs": {
+    "url": "https://github.com/nitra/7n-rules/issues"
+  },
+  "license": "ISC",
+  "author": "v@nitra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/7n-rules.git",
+    "directory": "plugins/lang-js"
+  },
+  "type": "module",
+  "files": [
+    "taze",
+    "skills",
+    "CHANGELOG.md",
+    "!**/*.test.mjs",
+    "!**/*_test.rego",
+    "!**/fixtures/**",
+    "!**/tests/**"
+  ],
+  "n-rules": {
+    "capabilities": [
+      "lang:js"
+    ],
+    "contributes": {
+      "rules": false,
+      "handlers": {
+        "taze": "./taze/provider.mjs"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@7n/rules": ">=1.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/skills/taze/SKILL.fragment.md

@@ -0,0 +1,67 @@
+## npm/bun-гілка (`@7n/rules-lang-js`)
+
+Екосистемна гілка JavaScript/npm/bun для taze — виконує кроки 1–8 скелета.
+
+### Детекція і передумови
+
+Кореневий `package.json`. Потрібні `bun` і `bunx`; чисте робоче дерево (без незакомічених змін у `package.json` / `bun.lock` / `node_modules`).
+
+### Крок 1 — стартовий стан
+
+```bash
+cp package.json package.json.taze-bak
+cp bun.lock bun.lock.taze-bak
+```
+
+(У monorepo — також усі `*/package.json` воркспейсів. Файли тимчасові, видаляються в кінці.)
+
+### Крок 2 — оновлення
+
+```bash
+bunx taze -w -r latest
+bun install
+```
+
+- `-w` — записати нові версії у `package.json`.
+- `-r` — рекурсивно по всіх воркспейсах.
+- `latest` — піднімати навіть major.
+
+### Крок 3 — major-оновлення
+
+> **Не порівнюй `package.json` вручну.** Класифікацію semver несе CLI — детерміновано, по всіх воркспейсах.
+
+```bash
+n-rules taze diff
+```
+
+Друкує компактний JSON: `{ "major": [{workspace, pkg, from, to}], "minorPatch": <N>, "totalChanged": <N> }`. `major` — залежності зі зміною найлівішої ненульової компоненти semver (`1.x→2.x`, `0.4.x→0.5.x`, `0.0.3→0.0.4`); саме вони йдуть у кроки 4–6. Покриває **прямі** залежності `package.json` (root + воркспейси); транзитивні (`bun.lock`) — за потреби окремо.
+
+### Крок 4 — breaking changes
+
+CHANGELOG/Releases репозиторію модуля (поле `repository` у `node_modules/<name>/package.json`); якщо неінформативно — `diff -r` між кешованою старою версією (`~/.bun/install/cache/<name>@<old-version>/`) і новою (`node_modules/<name>/`) по `dist/` / `*.d.ts` / entry-points з `exports`.
+
+### Крок 5 — сумісність з кодом
+
+```bash
+rg -n "<імпорт|функція|опція>" --type ts --type js --type vue
+```
+
+### Крок 6 — перевірки після правок
+
+```bash
+npx @7n/rules lint
+bun run typecheck   # якщо є
+bun test            # якщо є
+```
+
+### Крок 7 — прибирання
+
+```bash
+rm package.json.taze-bak bun.lock.taze-bak
+```
+
+(І решту бекапів воркспейсів, якщо створювались.)
+
+### Крок 8 — звіт
+
+Окрема секція **npm/bun-пакети** (оновлено / major / зрефакторено / потребує ручного втручання), у **Стан перевірок** — `lint` / `typecheck` / `test`.

package/taze/diff.mjs

@@ -0,0 +1,110 @@
+/** @see ./docs/diff.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { isBreaking, parseVersion } from '@7n/rules/plugin-api'
+import { getMonorepoPackageRootDirs } from '@7n/rules/scripts/lib/workspaces.mjs'
+
+/** Поля package.json із залежностями, які порівнюємо. */
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
+
+/** Дефолтний суфікс бекапу, який створює крок 1 скіла (`cp package.json package.json.taze-bak`). */
+const DEFAULT_BACKUP_SUFFIX = '.taze-bak'
+
+/**
+ * Порівнює два package.json-обʼєкти й повертає зміни залежностей.
+ * @param {object} oldPkg розпарсений старий package.json (бекап)
+ * @param {object} newPkg розпарсений новий package.json
+ * @param {string} workspace мітка воркспейсу (`.` для кореня)
+ * @returns {{major: Array<{workspace:string, pkg:string, from:string, to:string}>, minorPatch:number}} зміни
+ */
+export function diffPackageJson(oldPkg, newPkg, workspace) {
+  const major = []
+  let minorPatch = 0
+  for (const field of DEP_FIELDS) {
+    const oldDeps = oldPkg?.[field]
+    const newDeps = newPkg?.[field]
+    if (!oldDeps || !newDeps) continue
+    for (const [pkg, from] of Object.entries(oldDeps)) {
+      const to = newDeps[pkg]
+      if (to === undefined || to === from) continue
+      const fromV = parseVersion(from)
+      const toV = parseVersion(to)
+      if (fromV && toV && isBreaking(fromV, toV)) {
+        major.push({ workspace, pkg, from, to })
+      } else {
+        minorPatch += 1
+      }
+    }
+  }
+  return { major, minorPatch }
+}
+
+/**
+ * Читає JSON-файл або повертає null, якщо файл відсутній / невалідний.
+ * @param {string} path абсолютний шлях
+ * @returns {Promise<object|null>} розпарсений обʼєкт або null
+ */
+async function readJsonOrNull(path) {
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Збирає diff по всьому монорепо: для кожного воркспейсу порівнює
+ * `<ws>/package.json` з `<ws>/package.json<backupSuffix>`.
+ * @param {string} cwd корінь репозиторію
+ * @param {string} [backupSuffix] суфікс бекап-файлу
+ * @returns {Promise<{major: Array<{workspace:string, pkg:string, from:string, to:string}>, minorPatch:number, totalChanged:number, comparedWorkspaces:number}>} агрегований diff
+ */
+export async function collectTazeDiff(cwd, backupSuffix = DEFAULT_BACKUP_SUFFIX) {
+  const roots = await getMonorepoPackageRootDirs(cwd)
+  const major = []
+  let minorPatch = 0
+  let comparedWorkspaces = 0
+  for (const ws of roots) {
+    const dir = join(cwd, ws)
+    const oldPkg = await readJsonOrNull(join(dir, `package.json${backupSuffix}`))
+    const newPkg = await readJsonOrNull(join(dir, 'package.json'))
+    if (!oldPkg || !newPkg) continue
+    comparedWorkspaces += 1
+    const res = diffPackageJson(oldPkg, newPkg, ws)
+    major.push(...res.major)
+    minorPatch += res.minorPatch
+  }
+  return { major, minorPatch, totalChanged: major.length + minorPatch, comparedWorkspaces }
+}
+
+const USAGE = 'Usage: n-rules taze diff [--backup-suffix <suffix>]'
+
+/**
+ * CLI: `n-rules taze diff` друкує компактний JSON зі списком major-оновлень і
+ * лічбою minor/patch. Read-only.
+ * @param {string[]} args аргументи після `taze`
+ * @param {string} [cwd] корінь репозиторію (ін'єкція для тестів)
+ * @returns {Promise<number>} exit code
+ */
+export async function runTazeCli(args, cwd = process.cwd()) {
+  if (args[0] !== 'diff') {
+    console.error(USAGE)
+    return 1
+  }
+  const flagAt = args.indexOf('--backup-suffix')
+  const backupSuffix = flagAt === -1 ? DEFAULT_BACKUP_SUFFIX : args[flagAt + 1]
+  if (!backupSuffix) {
+    console.error(USAGE)
+    return 1
+  }
+  const diff = await collectTazeDiff(cwd, backupSuffix)
+  if (diff.comparedWorkspaces === 0) {
+    console.error(`✗ Не знайдено жодного package.json${backupSuffix} — спершу зроби бекап (крок 1 скіла).`)
+    return 1
+  }
+  process.stdout.write(`${JSON.stringify(diff)}\n`)
+  return 0
+}

package/taze/docs/diff.md

@@ -0,0 +1,22 @@
+---
+type: JS Module
+title: diff.mjs
+resource: plugins/lang-js/taze/diff.mjs
+docgen:
+  crc: e9789318
+---
+
+## Огляд
+
+Детермінований semver-diff npm/bun-гілки taze: порівнює package.json кожного воркспейсу з `.taze-bak`-бекапом і класифікує зміни залежностей на major vs minor/patch за caret-правилом (`isBreaking`/`parseVersion` з `@7n/rules/plugin-api`).
+
+## Поведінка
+
+- **diffPackageJson** — порівнює два розпарсені package.json по dependencies/devDependencies/peerDependencies/optionalDependencies; не-semver специфікатори (workspace:*, git-url) ігноруються.
+- **collectTazeDiff** — агрегує diff по root + воркспейсах монорепо (`getMonorepoPackageRootDirs` ядра); воркспейс без бекапу пропускається.
+- **runTazeCli** — CLI-обгортка (`n-rules taze diff`): друкує компактний JSON `{ major, minorPatch, totalChanged }`.
+
+## Гарантії поведінки
+
+- Read-only: лише читає файли, нічого не пише.
+- Відсутній або невалідний бекап/маніфест — пропуск без винятку.

package/taze/docs/provider.md

@@ -0,0 +1,22 @@
+---
+type: JS Module
+title: provider.mjs
+resource: plugins/lang-js/taze/provider.mjs
+docgen:
+  crc: 8749ccfb
+---
+
+## Огляд
+
+EcosystemProvider npm/bun для taze-оркестратора ядра (фаза 5a spec lang-plugins-extraction: ядро — двигун без мовної специфіки, JS-екосистема — такий самий плагін, як Rust/Python). Контракт `@7n/rules/plugin-api`, реєструється маніфестом `n-rules.contributes.handlers.taze`. Реекспортує `runTazeCli` для CLI `n-rules taze diff` ядра.
+
+## Поведінка
+
+- **buildDependencyPrompt** — промпт ОДНОГО ізольованого виклику раннера для одного major-запису (кроки 4-6 SKILL.md; без кроків 1-3/7/8 — їх виконує оркестратор).
+- **backupWorkspacePackageFiles** / **cleanupWorkspaceBackups** — бекап і прибирання package.json кожного воркспейсу монорепо (`.taze-bak`).
+- **jsProvider** — detect за кореневим package.json; available перевіряє bun; bump — `bunx taze -w -r latest` + `bun install` (провал кидає з exit-кодом і stderr); diff — `collectTazeDiff` з мапінгом workspace → manifest (контракт порту); cleanup — прибирання бекапів воркспейсів.
+
+## Гарантії поведінки
+
+- Виконує файлові операції (бекапи) і запускає зовнішні команди (`bunx`, `bun`) — НЕ read-only.
+- Без кореневого package.json detect повертає порожньо — тиша у звіті.

package/taze/provider.mjs

@@ -0,0 +1,130 @@
+/** @see ./docs/provider.md */
+import { existsSync } from 'node:fs'
+import { copyFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { getMonorepoPackageRootDirs } from '@7n/rules/scripts/lib/workspaces.mjs'
+
+import { collectTazeDiff } from './diff.mjs'
+
+// CLI `n-rules taze diff` ядра резолвить цей handler-модуль і кличе runTazeCli.
+export { runTazeCli } from './diff.mjs'
+
+/** Суфікс бекапу — той самий, що й у `diff.mjs`/кроці 1 SKILL.md. */
+const BACKUP_SUFFIX = '.taze-bak'
+
+/**
+ * Промпт ОДНОГО ітеративного виклику для npm/bun-пакета (кроки 4-6 SKILL.md)
+ * для ОДНОГО major-запису. Кроки 1-3/7/8 виконує оркестратор ядра
+ * детерміновано, без LLM.
+ * @param {{manifest: string, pkg: string, from: string, to: string}} entry запис major-diff (з `collectTazeDiff`, workspace → manifest)
+ * @returns {string} готовий промпт
+ */
+export function buildDependencyPrompt({ manifest, pkg, from, to }) {
+  return [
+    '# Major-оновлення одного пакета: перевірка сумісності й рефакторинг',
+    '',
+    `Пакет \`${pkg}\` у воркспейсі \`${manifest}\`: **${from} → ${to}** — вже застосовано в package.json/bun.lock (кроки 1-3 виконано детерміновано, без тебе). Твоя задача — лише breaking-changes-перевірка й, за потреби, рефакторинг.`,
+    '',
+    '## Кроки',
+    `1. Зібрати breaking changes цього оновлення: CHANGELOG/Releases репозиторію модуля (поле \`repository\` у \`node_modules/${pkg}/package.json\`), або git/diff між закешованою старою версією (\`~/.bun/install/cache/${pkg}@<стара-версія>/\`) і новою (\`node_modules/${pkg}/\`).`,
+    `2. Знайти використання зачепленого API в коді проєкту (\`rg -n\` по імпортах/викликах \`${pkg}\`).`,
+    '3. Сумісно — нічого не робити. Несумісно — застосувати міграцію (перейменувати імпорт, оновити сигнатуру виклику, замінити видалену опцію еквівалентом).',
+    '4. Якщо були правки — запусти `npx @7n/rules lint`, typecheck/test якщо є в проєкті.',
+    '5. Нетривіальна/неоднозначна міграція — не вгадуй, залиш TODO-коментар із посиланням на CHANGELOG.',
+    '',
+    'У відповіді одним абзацом підсумуй: сумісно / зрефакторено (які файли) / TODO (чому).'
+  ].join('\n')
+}
+
+/**
+ * Бекапить package.json кожного воркспейсу (крок 1 SKILL.md) — потрібно для
+ * класифікації major/minor через `collectTazeDiff` після bump-у.
+ * @param {string} cwd корінь репо
+ * @param {{ getMonorepoPackageRootDirs?: (cwd: string) => Promise<string[]>, copyFile?: (src: string, dest: string) => Promise<void> }} [deps] інжекти
+ * @returns {Promise<string[]>} відносні шляхи воркспейсів, що мали package.json
+ */
+export async function backupWorkspacePackageFiles(cwd, deps = {}) {
+  const getRoots = deps.getMonorepoPackageRootDirs ?? getMonorepoPackageRootDirs
+  const copy = deps.copyFile ?? copyFile
+  const roots = await getRoots(cwd)
+  const backedUp = []
+  for (const ws of roots) {
+    const pkgPath = join(cwd, ws, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    await copy(pkgPath, `${pkgPath}${BACKUP_SUFFIX}`)
+    backedUp.push(ws)
+  }
+  return backedUp
+}
+
+/**
+ * Прибирає бекапи package.json усіх воркспейсів (крок 7 SKILL.md).
+ * @param {string} cwd корінь репо
+ * @param {{ getMonorepoPackageRootDirs?: (cwd: string) => Promise<string[]>, rm?: (path: string, opts?: object) => Promise<void> }} [deps] інжекти
+ * @returns {Promise<void>}
+ */
+export async function cleanupWorkspaceBackups(cwd, deps = {}) {
+  const getRoots = deps.getMonorepoPackageRootDirs ?? getMonorepoPackageRootDirs
+  const remove = deps.rm ?? rm
+  for (const ws of await getRoots(cwd)) {
+    await remove(join(cwd, ws, `package.json${BACKUP_SUFFIX}`), { force: true })
+  }
+}
+
+/**
+ * Виконує детерміновану команду npm-гілки, кидає з exit-кодом+stderr при провалі.
+ * @param {string} cmd бінарник
+ * @param {string[]} args аргументи
+ * @param {string} cwd робочий каталог
+ * @param {import('@7n/rules/plugin-api').SpawnFn} spawnFn spawnSync-сумісний виклик
+ * @returns {void}
+ */
+function runCommand(cmd, args, cwd, spawnFn) {
+  const result = spawnFn(cmd, args, { cwd, encoding: 'utf8' })
+  if (result.status !== 0) {
+    throw new Error(`${cmd} ${args.join(' ')} → exit ${result.status}: ${result.stderr || result.stdout}`)
+  }
+}
+
+/**
+ * EcosystemProvider npm/bun для taze-оркестратора ядра (фаза 5a spec
+ * lang-plugins-extraction: ядро — двигун без мовної специфіки, JS-екосистема —
+ * такий самий плагін, як Rust/Python). Контракт `@7n/rules/plugin-api`,
+ * реєструється маніфестом (`n-rules.contributes.handlers.taze`).
+ * `diff.major` записи мапляться workspace → manifest (контракт порту).
+ * @type {import('@7n/rules/plugin-api').EcosystemProvider}
+ */
+export const jsProvider = {
+  id: 'js-bun',
+  title: 'npm/bun-пакети',
+  manifestNoun: 'package.json',
+  skillSection: 'npm/bun-гілкою SKILL.md',
+  detect: cwd => (existsSync(join(cwd, 'package.json')) ? ['package.json'] : []),
+  available: spawnFn =>
+    spawnFn('bun', ['--version'], { encoding: 'utf8' }).status === 0
+      ? { ok: true, reason: null }
+      : { ok: false, reason: '`bun` не встановлено (https://bun.sh) — npm/bun-гілка потребує bun/bunx' },
+  backup: async (cwd, manifests, deps) => {
+    await backupWorkspacePackageFiles(cwd, deps)
+  },
+  bump: (cwd, manifests, { spawnFn, log }) => {
+    log('⬆️  bunx taze -w -r latest...')
+    runCommand('bunx', ['taze', '-w', '-r', 'latest'], cwd, spawnFn)
+    log('📥 bun install...')
+    runCommand('bun', ['install'], cwd, spawnFn)
+    return Promise.resolve()
+  },
+  diff: async cwd => {
+    const diff = await collectTazeDiff(cwd)
+    return {
+      major: diff.major.map(({ workspace, pkg, from, to }) => ({ manifest: workspace, pkg, from, to })),
+      minorPatch: diff.minorPatch,
+      totalChanged: diff.totalChanged
+    }
+  },
+  promptFor: buildDependencyPrompt,
+  cleanup: (cwd, manifests, deps) => cleanupWorkspaceBackups(cwd, deps)
+}
+
+export default jsProvider