@7n/rules 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.1] - 2026-07-14
+
+### Fixed
+
+- Bun-сумісність тестового прогону: namespace-імпорт zod (фантомний __esModule на ESM-неймспейсах ламає vitest-interop), явний env: process.env у spawnSync skills-cli (Bun дає дітям snapshot оточення), чистка bun-node-* shim-тек з PATH для дочірнього v8r (node-shebang під --bun резолвився в bun і падав на node:sea); тест run-v8r приведено до контракту verbose-виводу (#44); root scripts.test → bun run --bun vitest run
+- package-manifest: VALID_MAX_BUMPS → Set (oxlint prefer-set-has), дока maxBump освіжена
+
 ## [1.2.0] - 2026-07-14
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/changelog/lib/docs/package-manifest.md

@@ -3,7 +3,7 @@ type: JS Module
 title: package-manifest.mjs
 resource: npm/rules/changelog/lib/package-manifest.mjs
 docgen:
-  crc: ced8ad49
+  crc: 10bad2ce
 ---
 
 Модуль `package-manifest.mjs` реалізує **уніфіковану абстракцію маніфесту пакета** для перевірок changelog у багатомовному монорепо. Він приховує відмінності між двома типами маніфестів:
@@ -17,7 +17,7 @@ docgen:
 2. **Читання маніфесту воркспейсу** в єдиній структурі `PackageManifest` (з пріоритетом `package.json` над `pyproject.toml`).
 3. **Виявлення коренів усіх пакетів монорепо**: npm-воркспейси через скрипт `workspaces.mjs` + автоматичний пошук Python-проєктів за `pyproject.toml`.
 
-Базова мета — дати правилам категорії `changelog` єдину модель «пакет = (kind, ws, name, version, registryPublishable)», незалежно від мови.
+Базова мета — дати правилам категорії `changelog` єдину модель «пакет = (kind, ws, name, version, registryPublishable, maxBump)», незалежно від мови.
 
 ## Експорти / API
 
@@ -44,12 +44,14 @@ docgen:
  * @property {string | null} version      semver-рядок
  * @property {boolean} registryPublishable чи застосовується режим порівняння з реєстром
  * @property {string[] | null} [npmFiles] лише npm: 'files' з package.json
+ * @property {'major' | 'minor' | 'patch' | null} maxBump стеля для 'n-rules release' (з 'package.json#release.maxBump'); null — без обмеження
  */
 ```
 
 ### Константи модуля
 
 - `PYPROJECT_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**']` — патерни, що **виключаються** під час сканування `pyproject.toml` глобом, щоб не зачіпати чужі залежності та віртуальні середовища.
+- `VALID_MAX_BUMPS` — `Set` дозволених значень `release.maxBump` (`'major' | 'minor' | 'patch'`); будь-яке інше значення тихо ігнорується (`maxBump: null`).
 
 ## Функції
 
@@ -93,14 +95,14 @@ docgen:
      - Читає текст через `readFile(pkgPath, 'utf8')` і парсить як JSON.
      - Якщо JSON — не об'єкт (null, масив, примітив), повертає `null`.
      - Обчислює `registryPublishable = name є непорожнім рядком && private !== true && files є масивом`. Тобто пакет вважається «публікованим у реєстр», тільки якщо в `package.json` явно вказано непорожній `name`, не зведено `private: true`, і визначено поле `files` (whitelist того, що публікується).
-     - Повертає об'єкт із `kind: 'npm'`, `manifestRel: 'package.json'`, з `name`/`version` (тільки якщо вони — рядки, інакше `null`), `registryPublishable`, `npmFiles = pkg.files` або `null`.
+     - Повертає об'єкт із `kind: 'npm'`, `manifestRel: 'package.json'`, з `name`/`version` (тільки якщо вони — рядки, інакше `null`), `registryPublishable`, `npmFiles = pkg.files` або `null`, а також `maxBump` — валідне значення `package.json#release.maxBump` (`major`/`minor`/`patch`) або `null`, якщо поле відсутнє, не рядок чи поза дозволеним списком.
      - Будь-яка помилка читання/парсингу JSON у блоці `try` → повертає `null` (catch без логування).
   2. **Гілка Python:**
      - Складає шлях `cwd/ws/pyproject.toml`.
      - `existsSync` → якщо файлу немає, повертає `null`.
      - Читає файл і викликає `parsePyprojectFields`.
      - `registryPublishable = Boolean(name && version)` — для Python публікація в PyPI потребує лише валідних `name` і `version` (PyPI не має аналога `files` whitelist).
-     - Повертає об'єкт із `kind: 'python'`, `manifestRel: 'pyproject.toml'`, `npmFiles: null`.
+     - Повертає об'єкт із `kind: 'python'`, `manifestRel: 'pyproject.toml'`, `npmFiles: null`, `maxBump: null` (стеля бампа підтримується лише для npm-маніфестів).
 - **Side effects:**
   - Синхронний `existsSync` (двічі: на `package.json` і `pyproject.toml`).
   - Асинхронне читання файлу через `fs/promises.readFile`.

package/rules/changelog/lib/package-manifest.mjs

@@ -27,7 +27,7 @@ import { getMonorepoPackageRootDirs, isIgnoredWorkspaceRoot } from '../../../scr
  */
 
 const PYPROJECT_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**']
-const VALID_MAX_BUMPS = ['major', 'minor', 'patch']
+const VALID_MAX_BUMPS = new Set(['major', 'minor', 'patch'])
 
 /**
  * @param {Record<string, unknown>} pkg розпарсений package.json
@@ -37,7 +37,7 @@ function maxBumpFromPackageJson(pkg) {
   const release = pkg.release
   if (!release || typeof release !== 'object' || Array.isArray(release)) return null
   const value = /** @type {Record<string, unknown>} */ (release).maxBump
-  return typeof value === 'string' && VALID_MAX_BUMPS.includes(value)
+  return typeof value === 'string' && VALID_MAX_BUMPS.has(value)
     ? /** @type {'major' | 'minor' | 'patch'} */ (value)
     : null
 }

package/rules/release/docs/release.md

@@ -3,9 +3,7 @@ type: JS Module
 title: release.mjs
 resource: npm/rules/release/release.mjs
 docgen:
-  crc: 475bce65
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  crc: 3ac9ee4c
 ---
 
 Файл автоматизує процес випуску версій. Він агрегує зміна-файли для всіх робочих просторів у `version-bump` та `CHANGELOG`, комітить зміни, ставить тег `<name>@<version>` та видаляє використані зміна-файли. Цей процес виконується у CI на гілці `main` (n-rules-release-design, варіант A). Публічні функції, що надає модуль, — `release` та `runReleaseCli`.
@@ -13,6 +11,9 @@ docgen:
 ## Поведінка
 
 release агрегує change-файли для всіх робочих просторів, оновлює версії в маніфестах, додає секції до `CHANGELOG.md`, видаляє використані change-файли, створює коміт та анотовані теги для всіх зібраних релізів, а потім намагається пушити їх у апстрім з повторними спробами.
+
+Обчислений bump обрізається зверху стелею `package.json#release.maxBump` робочого простору: наприклад, `major`-change-файл при стелі `minor` дає лише minor-реліз. Коли стеля реально спрацювала, у консоль друкується попередження з початковим bump, стелею та фінальною версією.
+
 runReleaseCli виконує процес релізу, викликаючи функцію release, та виводить відповідний статус у консоль.
 
 ## Публічний API

package/rules/release/lib/docs/aggregate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: aggregate.mjs
 resource: npm/rules/release/lib/aggregate.mjs
 docgen:
-  crc: 1f78a0fe
+  crc: ff9ff216
 ---
 
 Модуль `aggregate.mjs` забезпечує **агрегацію change-файлів одного workspace** у дві основні сутності:
@@ -23,7 +23,8 @@ docgen:
 | `maxBump(bumps)`                                            | функція | Найвищий пріоритет бампа у списку (`major` > `minor` > `patch`)                  |
 | `renderChangelogSection(version, date, entries)`            | функція | Рендер однієї версійної секції у markdown                                        |
 | `prependChangelogSection(existingText, sectionBlock)`       | функція | Вставка нової секції зверху наявного `CHANGELOG.md`                              |
-| `aggregateWorkspace({ currentVersion, changeFiles, date })` | функція | Високорівневе об’єднання change-файлів workspace у `newVersion` + `sectionBlock` |
+| `capBump(bump, cap)`                                        | функція | Обрізає bump зверху стелею `release.maxBump` (`major` → `minor` тощо)            |
+| `aggregateWorkspace({ currentVersion, changeFiles, date, maxBumpCap })` | функція | Високорівневе об’єднання change-файлів workspace у `newVersion` + `sectionBlock` |
 
 Усі експорти — **іменовані** (`export function …`). Default-export відсутній.
 
@@ -76,6 +77,14 @@ docgen:
 - `maxBump(['patch'])` → `'patch'`
 - `maxBump([])` → `'patch'` (через fallback `?? 'patch'`)
 
+### `capBump(bump, cap)`
+
+**Сигнатура:** `capBump(bump: string, cap?: string | null): string`
+
+Обмежує обчислений bump **зверху** стелею з `package.json#release.maxBump`: якщо `bump` суворіший за `cap` (наприклад, `major` при `cap: 'minor'`), повертається `cap`; інакше — `bump` без змін. `cap` у `null`/`undefined` вимикає обмеження. Так пакет може заборонити автоматичну зміну власної major-версії, навіть якщо change-файл явно поставив `major`.
+
+**Side effects:** немає.
+
 ### `renderChangelogSection(version, date, entries)`
 
 **Сигнатура:** `renderChangelogSection(version: string, date: string, entries: Array<{ section: string, description: string }>): string`
@@ -152,7 +161,7 @@ docgen:
 - `existingText = 'тут нічого корисного'`:
   - вихід: `# Changelog\n\n<sectionBlock>` (попередній вміст відкидається).
 
-### `aggregateWorkspace({ currentVersion, changeFiles, date })`
+### `aggregateWorkspace({ currentVersion, changeFiles, date, maxBumpCap })`
 
 **Сигнатура:**
 
@@ -161,6 +170,7 @@ aggregateWorkspace({
   currentVersion: string,
   changeFiles: Array<{ file: string, entry: { bump: string, section: string, description: string } }>,
   date: string,
+  maxBumpCap?: string | null,
 }): { newVersion: string, sectionBlock: string, consumedFiles: string[] } | null
 ```
 
@@ -169,12 +179,13 @@ aggregateWorkspace({
 - `currentVersion` — поточна версія маніфесту workspace (`x.y.z`).
 - `changeFiles` — масив об’єктів, що відповідає виходу `readChangeFiles` з `change-file.mjs`. Кожен елемент має `file` (ім’я файлу `.md`) та `entry` (розпарсений frontmatter + опис).
 - `date` — рядок дати `YYYY-MM-DD` для секції CHANGELOG.
+- `maxBumpCap` — стеля bump з `package.json#release.maxBump` (`'major' | 'minor' | 'patch'`); `null`/відсутній — без обмеження.
 
 **Повертає:**
 
 - `null`, якщо `changeFiles.length === 0` (явна ознака «нема чого релізити»).
 - Інакше — об’єкт:
-  - `newVersion` — результат `bumpVersion(currentVersion, maxBump(<усі bumps>))`.
+  - `newVersion` — результат `bumpVersion(currentVersion, capBump(maxBump(<усі bumps>), maxBumpCap))`.
   - `sectionBlock` — результат `renderChangelogSection(newVersion, date, <усі entries>)`.
   - `consumedFiles` — імена change-файлів (`c.file`), які мають бути видалені викликачем після успішного запису маніфесту й `CHANGELOG.md`.
 
@@ -211,7 +222,7 @@ aggregateWorkspace({
 1. **Збір change-файлів.** Викликач звертається до `readChangeFiles(ws, cwd)` з `change-file.mjs`, отримуючи `Array<{ file, entry }>` — усі `.md` із `<ws>/.changes/`, відсортовані за іменем (тобто де-факто за `timestamp`).
 2. **Отримання поточної версії.** Викликач читає `package.json` (або інший маніфест) і дістає `currentVersion`.
 3. **Дата.** Викликач формує `date = new Date().toISOString().slice(0, 10)` або еквівалент.
-4. **Агрегація.** Виклик `aggregateWorkspace({ currentVersion, changeFiles, date })`:
+4. **Агрегація.** Виклик `aggregateWorkspace({ currentVersion, changeFiles, date, maxBumpCap })`:
    - Якщо повертає `null` — викликач пропускає workspace (нема `change-файлів`).
    - Якщо повертає об’єкт — отримуємо `newVersion`, `sectionBlock`, `consumedFiles`.
 5. **Оновлення `CHANGELOG.md`.** Викликач читає поточний `CHANGELOG.md` (або порожній рядок, якщо файлу нема), застосовує `prependChangelogSection(existingText, sectionBlock)` і записує результат на диск.
@@ -244,7 +255,7 @@ aggregateWorkspace({
 5. Експортує функцію `prependChangelogSection(existingText, sectionBlock)`, яка:
    - Якщо `existingText.trimStart()` не починається з `# Changelog`, повертає `# Changelog\n\n<sectionBlock>`.
    - Інакше відокремлює перший рядок (`head`) і решту (`rest`, із `trimStart`) і повертає `head + '\n\n' + sectionBlock + '\n' + rest`.
-6. Експортує функцію `aggregateWorkspace({ currentVersion, changeFiles, date })`, яка:
+6. Експортує функцію `aggregateWorkspace({ currentVersion, changeFiles, date, maxBumpCap })`, яка:
    - Повертає `null`, якщо `changeFiles` порожній.
-   - Інакше повертає `{ newVersion, sectionBlock, consumedFiles }`, де `newVersion = bumpVersion(currentVersion, maxBump(<усі c.entry.bump>))`, `sectionBlock = renderChangelogSection(newVersion, date, <усі c.entry>)`, `consumedFiles = <усі c.file>`.
+   - Інакше повертає `{ newVersion, sectionBlock, consumedFiles }`, де `newVersion = bumpVersion(currentVersion, capBump(maxBump(<усі c.entry.bump>), maxBumpCap))`, `sectionBlock = renderChangelogSection(newVersion, date, <усі c.entry>)`, `consumedFiles = <усі c.file>`.
 7. Не виконує жодного I/O й не залежить від `node:*`.

package/rules/text/run-v8r/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/text/run-v8r/main.mjs
 docgen:
-  crc: f6f78d26
+  crc: 804dce1c
 ---
 
 ## Огляд
@@ -23,6 +23,7 @@ docgen:
 - `runV8rWithGlobs(globs?)` — послідовно запускає `v8r` для кожного glob-у з `V8R_CONFIG_FILE`, вказаним на резольвнутий конфіг; при коді 0/98 вивід приховано, інакше друкується й повертається код першого невдалого прогону.
 - `runV8rWithFiles(files)` — delta-режим: один запуск `v8r` по конкретних існуючих шляхах (код 98 неможливий), порожній список — одразу 0.
 - `warnAboutRemoteSchemaFallback(stderrText)` — парсить stderr `v8r` і на кожен файл, чию схему знайдено мережевим fallback-ом (schemastore, не customCatalog), друкує в stdout пораду додати схему в каталог.
+- `stripBunNodeShimDirs(pathValue)` — прибирає з PATH shim-теки `bun-node-*`, які `bun run --bun` додає з підміненим `node`: дочірній `v8r` (node-shebang) інакше виконувався б під bun і падав на непідтримуваному `node:sea`. Дочірній процес `v8r` завжди отримує очищений PATH.
 - `lint(ctx)` — detector `text/run-v8r`: `ctx.files` → delta по відфільтрованих розширеннях, без `ctx.files` → full за `DEFAULT_V8R_GLOBS`.
 
 ## Публічний API
@@ -32,6 +33,7 @@ docgen:
 - `writeResolvedV8rConfig()` — матеріалізація тимчасового конфігу, повертає його шлях.
 - `runV8rWithGlobs(globs?)`, `runV8rWithFiles(files)` — точки входу перевірки (full/delta).
 - `warnAboutRemoteSchemaFallback(stderrText)` — попередження про мережевий fallback схем.
+- `stripBunNodeShimDirs(pathValue)` — PATH без shim-тек `bun-node-*` (для дочірнього v8r).
 - `lint(ctx)` — інтеграція в lint-пайплайн.
 
 ## Гарантії поведінки

package/rules/text/run-v8r/main.mjs

@@ -47,7 +47,8 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, isAbsolute, join } from 'node:path'
+import { basename, delimiter, dirname, isAbsolute, join } from 'node:path'
+import { env } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
@@ -150,6 +151,21 @@ export function warnAboutRemoteSchemaFallback(stderrText) {
   }
 }
 
+/**
+ * Прибирає з PATH shim-теки `bun-node-*`: їх додає `bun run --bun`, підміняючи `node` через
+ * symlink на bun. `bun x v8r` поважає node-shebang і бере `node` з PATH — під shim v8r виконується bun-ом
+ * і падає на непідтримуваному `node:sea`, тому дочірній v8r має бачити справжній node.
+ * @param {string | undefined} pathValue значення PATH батьківського процесу
+ * @returns {string | undefined} PATH без shim-тек (undefined — якщо PATH не задано)
+ */
+export function stripBunNodeShimDirs(pathValue) {
+  if (!pathValue) return pathValue
+  return pathValue
+    .split(delimiter)
+    .filter(entry => !basename(entry).startsWith('bun-node-'))
+    .join(delimiter)
+}
+
 /**
  * Один виклик `bun x v8r <targets...>` з підготовленим `customCatalog`-конфігом.
  * @param {string[]} targets glob-и або конкретні шляхи файлів
@@ -165,7 +181,7 @@ function runOneV8rInvocation(targets, configPath, verbose = false) {
     maxBuffer: 50 * 1024 * 1024,
     shell: false,
     stdio: ['ignore', 'pipe', 'pipe'],
-    env: { ...process.env, V8R_CONFIG_FILE: configPath }
+    env: { ...env, PATH: stripBunNodeShimDirs(env.PATH), V8R_CONFIG_FILE: configPath }
   })
 
   if (result.error) {

package/scripts/docs/skills-cli.md

@@ -3,7 +3,7 @@ type: JS Module
 title: skills-cli.mjs
 resource: npm/scripts/skills-cli.mjs
 docgen:
-  crc: 3a6aab39
+  crc: 30b6209c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -3,7 +3,7 @@ type: JS Module
 title: normalize-pipeline.mjs
 resource: npm/scripts/lib/adr/normalize-pipeline.mjs
 docgen:
-  crc: 9c2cbb81
+  crc: f8bd18e2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/scripts/lib/adr/normalize-pipeline.mjs

@@ -23,7 +23,9 @@
  *
  * Повертає той самий operations[]-контракт, що й single-shot — apply-логіка спільна.
  */
-import { z } from 'zod'
+// Namespace-імпорт замість `import { z }`: Bun показує фантомний `__esModule` на ESM-неймспейсах,
+// через що interop у vitest приймає default-експорт zod за CJS-обгортку і губить named-експорт `z`.
+import * as z from 'zod'
 import { runOneShot } from '@7n/llm-lib/one-shot'
 import { startChain } from '@7n/llm-lib/chain'
 import { CLOUD_MIN, resolveModel } from '@7n/llm-lib/model-tiers'

package/scripts/skills-cli.mjs

@@ -55,7 +55,9 @@ const USAGE_LINES = [
  * @returns {boolean} чи знайдено бінарник у PATH
  */
 function isBinaryInPath(name) {
-  const probe = spawnSync('command', ['-v', name], { shell: true, encoding: 'utf8' })
+  // Явний `env: process.env` — Bun без нього дає дітям snapshot оточення зі старту процесу
+  // і не бачить runtime-змін `process.env.PATH` (та сама причина, що в resolve-cmd.mjs).
+  const probe = spawnSync('command', ['-v', name], { shell: true, encoding: 'utf8', env: process.env })
   return probe.status === 0
 }
 
@@ -196,7 +198,8 @@ function runLlmCli(kind, prompt, projectDir, logError) {
     input: prompt,
     cwd: projectDir,
     stdio: ['pipe', 'inherit', 'inherit'],
-    encoding: 'utf8'
+    encoding: 'utf8',
+    env: process.env
   })
   return result.status ?? 1
 }