@7n/rules 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.2.2] - 2026-07-14
+
+### Changed
+
+- release: @7n/llm-lib@2.6.1, @7n/rules@1.1.0
+
+## [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.2",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/abie/clean_merged_ignore_branches/fix-clean_merged_ignore_branches.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'abie-clean_merged_ignore_branches-template', targetPath: '.github/workflows/clean-merged-branch.yml' })]

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/docker/lint_docker_yml/fix-lint_docker_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'docker-lint_docker_yml-template', targetPath: '.github/workflows/lint-docker.yml' })]

package/rules/ga/clean_ga_workflows/fix-clean_ga_workflows.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-clean_ga_workflows-template', targetPath: '.github/workflows/clean-ga-workflows.yml' })]

package/rules/ga/clean_merged_branch/fix-clean_merged_branch.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-clean_merged_branch-template', targetPath: '.github/workflows/clean-merged-branch.yml' })]

package/rules/ga/git_ai/fix-git_ai.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-git_ai-template', targetPath: '.github/workflows/git-ai.yml' })]

package/rules/ga/lint_ga/fix-lint_ga.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-lint_ga-template', targetPath: '.github/workflows/lint-ga.yml' })]

package/rules/ga/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/ga/zizmor_yml/fix-zizmor_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-zizmor_yml-template', targetPath: '.github/zizmor.yml' })]

package/rules/js/jscpd_config/fix-jscpd_config.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'js-jscpd_config-template', targetPath: '.jscpd.json' })]

package/rules/js/lint_js_yml/fix-lint_js_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'js-lint_js_yml-template', targetPath: '.github/workflows/lint-js.yml' })
+]

package/rules/js/package_json/fix-package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'js-package_json-template', targetPath: 'package.json' })]

package/rules/k8s/lint_k8s_yml/fix-lint_k8s_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'k8s-lint_k8s_yml-template', targetPath: '.github/workflows/lint-k8s.yml' })]

package/rules/npm-module/emit_types_config/fix-emit_types_config.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-emit_types_config-template', targetPath: 'npm/tsconfig.emit-types.json' })]

package/rules/npm-module/npm_package_json/fix-npm_package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-npm_package_json-template', targetPath: 'npm/package.json' })]

package/rules/npm-module/npm_publish_yml/fix-npm_publish_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'npm-module-npm_publish_yml-template', targetPath: '.github/workflows/npm-publish.yml' })
+]

package/rules/npm-module/root_package_json/fix-root_package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-root_package_json-template', targetPath: 'package.json' })]

package/rules/php/lint_php_yml/fix-lint_php_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'php-lint_php_yml-template', targetPath: '.github/workflows/lint-php.yml' })]

package/rules/python/lint_python_yml/fix-lint_python_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'python-lint_python_yml-template', targetPath: '.github/workflows/lint-python.yml' })]

package/rules/rego/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'rego-vscode_settings-template', targetPath: '.vscode/settings.json' })]

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/rust/lint_rust_yml/fix-lint_rust_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'rust-lint_rust_yml-template', targetPath: '.github/workflows/lint-rust.yml' })
+]

package/rules/security/lint_security_yml/fix-lint_security_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'security-lint_security_yml-template', targetPath: '.github/workflows/lint-security.yml' })]

package/rules/style/lint_style_yml/fix-lint_style_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-lint_style_yml-template', targetPath: '.github/workflows/lint-style.yml' })]

package/rules/style/package_json/fix-package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-package_json-template', targetPath: 'package.json' })]

package/rules/style/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/text/lint_text/fix-lint_text.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'text-lint_text-template', targetPath: '.github/workflows/lint-text.yml' })
+]

package/rules/text/oxfmtrc/fix-oxfmtrc.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'text-oxfmtrc-template', targetPath: '.oxfmtrc.json' })]

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/rules/text/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'text-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/worktree/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'worktree-vscode_settings-template', targetPath: '.vscode/settings.json' })
+]

package/rules/worktree/zed_settings/fix-zed_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'worktree-zed_settings-template', targetPath: '.zed/settings.json' })]

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/lib/fix/template-deep-merge.mjs

@@ -0,0 +1,182 @@
+/**
+ * Спільний T0-autofix writer для policy-концернів "один target-файл + один канонічний
+ * `template/*.snippet.{json,jsonc,yml,yaml}`" (`engine:"template"` і `engine:"rego"`
+ * з тим самим snippet-шаблоном). Deep-merge snippet → target: об'єкти мерджаться по
+ * ключах, масиви — union за структурним підмножинним збігом (`checkSnippet`-семантика,
+ * як у детекторі — жодного окремого визначення "збігу"), листя — перезаписується
+ * канонічним значенням. Файл відсутній → копіюється сам snippet (без merge).
+ *
+ * JSON/JSONC — plain-object merge + `JSON.stringify`. YAML — `yaml` Document API
+ * (`setIn`/`addIn`/`hasIn`), щоб зберегти коментарі й форматування наявного файлу;
+ * створюється лише те, чого бракує.
+ *
+ * Кожен викличний concern передає лише `{ id, targetPath }` — сам writer резолвить
+ * snippet-файл у `template/` свого concern-а через `ctx.concernDir` (той самий
+ * механізм, що й `vscode-ext-add.mjs`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+
+import { checkSnippet } from '../template.mjs'
+
+const SNIPPET_EXTS = ['yml', 'yaml', 'json', 'jsonc']
+
+/**
+ * Чи `needle` структурно вже присутній у якомусь елементі `actualArray`
+ * (та сама subset-семантика, що й у детекторі — жодного окремого визначення "збігу").
+ * @param {unknown[]} actualArray наявний масив
+ * @param {unknown} needle елемент снippета, наявність якого перевіряємо
+ * @returns {boolean} true — вже присутній структурно
+ */
+function containedIn(actualArray, needle) {
+  return actualArray.some(a => checkSnippet(a, needle, { targetPath: '', source: '' }).length === 0)
+}
+
+/**
+ * Шукає `<basename>.snippet.<ext>` у `template/` concern-а (перебір відомих розширень).
+ * @param {string} templateDir абсолютний шлях до `template/` concern-а
+ * @param {string} targetBasename basename цільового файлу (напр. `npm-publish.yml`)
+ * @returns {string|null} абсолютний шлях до snippet-файлу або null
+ */
+function findSnippetFile(templateDir, targetBasename) {
+  if (!existsSync(templateDir)) return null
+  for (const ext of SNIPPET_EXTS) {
+    const p = join(templateDir, `${targetBasename}.snippet.${ext}`)
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+/**
+ * Рекурсивний deep-merge snippet у plain JS-значення (JSON/JSONC-гілка).
+ * @param {unknown} actual наявне значення (або undefined)
+ * @param {unknown} snippet канонічний фрагмент
+ * @returns {unknown} злите значення
+ */
+function mergeJsonValue(actual, snippet) {
+  if (Array.isArray(snippet)) {
+    const arr = Array.isArray(actual) ? [...actual] : []
+    for (const needle of snippet) {
+      if (!containedIn(arr, needle)) arr.push(needle)
+    }
+    return arr
+  }
+  if (snippet !== null && typeof snippet === 'object') {
+    const obj = actual !== null && typeof actual === 'object' && !Array.isArray(actual) ? { ...actual } : {}
+    for (const [k, v] of Object.entries(snippet)) obj[k] = mergeJsonValue(obj[k], v)
+    return obj
+  }
+  return snippet // leaf — перезаписуємо канонічним значенням
+}
+
+/**
+ * Deep-merge snippet у YAML `Document` за шляхом (мутує `doc`). Масиви — `addIn` лише
+ * відсутніх (структурно) елементів; об'єкти — рекурсія по ключах (`setIn` створює
+ * проміжні мапи автоматично); листя — `setIn`.
+ * @param {import('yaml').Document} doc YAML-документ (мутується)
+ * @param {unknown} snippet канонічний фрагмент на цьому шляху
+ * @param {Array<string|number>} path шлях у документі
+ * @returns {void}
+ */
+function mergeYamlDoc(doc, snippet, path) {
+  if (Array.isArray(snippet)) {
+    // `doc.createNode([])` — примусово YAMLSeq-вузол; голий `setIn(path, [])` іноді
+    // лишає сирий JS-масив (коли батьківська мапа вже існує), і подальший `addIn` кидає
+    // `Expected YAML collection at …` — createNode гарантує коректний тип вузла завжди.
+    if (!doc.hasIn(path)) doc.setIn(path, doc.createNode([]))
+    const existing = doc.getIn(path)
+    const existingJs = existing && typeof existing.toJS === 'function' ? existing.toJS(doc) : []
+    for (const needle of snippet) {
+      if (!containedIn(existingJs, needle)) doc.addIn(path, needle)
+    }
+    return
+  }
+  if (snippet !== null && typeof snippet === 'object') {
+    for (const [k, v] of Object.entries(snippet)) mergeYamlDoc(doc, v, [...path, k])
+    return
+  }
+  doc.setIn(path, snippet) // leaf — перезаписуємо канонічним значенням
+}
+
+/**
+ * Створює T0-патерн, що приводить `targetPath` у відповідність `template/*.snippet.*`
+ * свого concern-а (deep-merge, idempotent). Один writer — для будь-якого single-target
+ * snippet-концерну (`engine:"template"` чи `engine:"rego"` з тим самим snippet-шаблоном).
+ * @param {{ id: string, targetPath: string }} opts `id` — унікальний id T0-патерну; `targetPath` — posix-relative шлях цільового файлу від cwd
+ * @returns {import('../lint-surface/types.mjs').T0Pattern} T0-патерн для `fix-<concern>.mjs`
+ */
+export function createTemplateFixPattern({ id, targetPath }) {
+  return {
+    id,
+    test: violations => violations.some(v => v.file === targetPath),
+    apply: async (violations, ctx) => {
+      if (!violations.some(v => v.file === targetPath)) return { touchedFiles: [] }
+      if (!ctx.concernDir) return { touchedFiles: [] }
+
+      const snippetPath = findSnippetFile(join(ctx.concernDir, 'template'), basename(targetPath))
+      if (!snippetPath) return { touchedFiles: [] }
+
+      const absTarget = join(ctx.cwd, targetPath)
+      const ext = extname(snippetPath).toLowerCase()
+      const isJson = ext === '.json' || ext === '.jsonc'
+
+      const prevText = existsSync(absTarget) ? readFileSync(absTarget, 'utf8') : null
+
+      // Файл відсутній → копіюємо snippet як є (без merge — немає з чим мерджити).
+      if (prevText === null) {
+        const rawSnippet = readFileSync(snippetPath, 'utf8')
+        ctx.recordWrite?.(absTarget)
+        mkdirSync(dirname(absTarget), { recursive: true })
+        writeFileSync(absTarget, rawSnippet, 'utf8')
+        return { touchedFiles: [absTarget], message: `${targetPath}: створено зі snippet` }
+      }
+
+      let nextText
+      if (isJson) {
+        let snippet
+        let actual
+        try {
+          snippet = JSON.parse(readFileSync(snippetPath, 'utf8'))
+          actual = JSON.parse(prevText)
+        } catch {
+          return { touchedFiles: [] } // невалідний JSON — не чіпаємо детермінованим фіксом
+        }
+        // Уже відповідає snippet-у (та сама перевірка, що й детектор) → не чіпаємо файл
+        // взагалі: без цієї гейтки JSON.stringify переформатував би вже коректний файл
+        // (напр. компактний однорядковий snippet → pretty-print) без жодної реальної зміни.
+        if (checkSnippet(actual, snippet, { targetPath: '', source: '' }).length === 0) {
+          return { touchedFiles: [] }
+        }
+        const merged = mergeJsonValue(actual, snippet)
+        nextText = JSON.stringify(merged, null, 2) + '\n'
+      } else {
+        const { parse, parseDocument } = await import('yaml')
+        let snippet
+        let actualPlain
+        try {
+          snippet = parse(readFileSync(snippetPath, 'utf8'))
+          actualPlain = parse(prevText)
+        } catch {
+          return { touchedFiles: [] } // невалідний YAML — не чіпаємо детермінованим фіксом
+        }
+        // Уже відповідає snippet-у (та сама перевірка, що й детектор) → не чіпаємо файл
+        // взагалі: Document.toString() не завжди byte-identical на вже коректному вмісті
+        // (напр. folded block scalars переформатовуються при round-trip без потреби).
+        if (checkSnippet(actualPlain, snippet, { targetPath: '', source: '' }).length === 0) {
+          return { touchedFiles: [] }
+        }
+        const doc = parseDocument(prevText)
+        if (doc.errors.length > 0) return { touchedFiles: [] }
+        if (snippet !== null && typeof snippet === 'object' && !Array.isArray(snippet)) {
+          for (const [k, v] of Object.entries(snippet)) mergeYamlDoc(doc, v, [k])
+        }
+        nextText = doc.toString()
+      }
+
+      if (nextText === prevText) return { touchedFiles: [] }
+      ctx.recordWrite?.(absTarget)
+      writeFileSync(absTarget, nextText, 'utf8')
+      return { touchedFiles: [absTarget], message: `${targetPath}: приведено у відповідність snippet` }
+    }
+  }
+}

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
 }