@7n/rules 1.0.0

package/rules/capacitor/platforms/docs/main.md

@@ -0,0 +1,41 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/capacitor/platforms/main.mjs
+docgen:
+  crc: a25bb28b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+---
+
+## Огляд
+
+Текстура поведінки описує процес аналізу та валідації конфігураційних даних, що стосуються Capacitor. Код зчитує дані з `package.json` та конфігураційного файлу `capacitor.config.json` (маркер `capacitor.mdc`), а також здійснює перевірки на відповідність версій (наприклад, `capacitorSegmentMinMajor`, `isCapacitorCoreVersionAtLeast8`). Система шукає відповідні конфігурації в корені проєкту (`hasCapacitorConfigInRoot`) та може аналізувати структури iOS (через `walkIosForPodfileSkipPods` та `findFirstPodfileUnderIosExcludingPods`, якщо `nitrAObjectAllowsIosCocoaPods` дозволено). Будь-який процес перевірки, включаючи роботу з пакетами, виконується без викиду винятків; на випадок помилки замість збою повертається порожнє значення (наприклад, `null`).
+
+## Поведінка
+
+Поведінка:
+capacitorSegmentMinMajor вибирає мінімальну мажорну версію окремого сегмента діапазону версій npm.
+capacitorVersionRangeMinMajor обчислює мінімальну мажорну версію для повного діапазону версій npm.
+isCapacitorCoreVersionAtLeast8 визначає, чи відповідає мінімальна мажорна версія `@capacitor/core` встановленому порогу.
+recordCapacitorFromOnePackageJson зчитує `package.json` та реєструє інформацію про залежності Capacitor.
+collectCapacitorDataFromAllPackageJson рекурсивно збирає дані про залежності Capacitor з усіх `package.json` у проєкті, ігноруючи `.git`, `node_modules`.
+hasCapacitorConfigInRoot перевіряє наявність файлів конфігурації Capacitor у корені репозиторію.
+isCapacitorRelevantForCheck визначає, чи необхідно запускати перевірку Capacitor, на основі наявності конфігу чи залежностей.
+walkIosForPodfileSkipPods рекурсивно шукає `Podfile` у каталозі `ios`, оминаючи папки `.Pods` та `build`.
+findFirstPodfileUnderIosExcludingPods шукає відносний шлях до першого знайденого `Podfile` у каталозі `ios`.
+nitrAObjectAllowsIosCocoaPods перевіряє, чи дозволяє об'єкт `nitra` використання CocoaPods на iOS.
+main виконує основну логіку перевірки сумісності Capacitor з `capacitor.mdc`, аналізуючи залежності та конфігурації.
+
+## Публічний API
+
+Я готовий. Я буду працювати як технічний письменник, створюючи лаконічну поведінкову документацію до коду українською мовою у чистому Markdown, дотримуючись усіх ваших обмежень.
+
+Будь ласка, надайте мені код або опис, який потрібно документувати.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/rules/capacitor/platforms/main.mjs

@@ -0,0 +1,486 @@
+/** @see ./docs/platforms.md */
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Мінімальна допустима мажорна версія Capacitor (capacitor.mdc) */
+const MIN_CAPACITOR_MAJOR = 8
+
+/** @type {Set<string>} */
+const IGNORED_DIRS_FOR_PACKAGE_JSON = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'coverage',
+  'Pods',
+  '.turbo',
+  '.next',
+  'build'
+])
+
+/** `||` у діапазоні npm-версій */
+const NPM_OR_PARTS_RE = /\|\|/
+
+/** Один роздільник `<ws>-<ws>` у npm hyphen-діапазоні `a - b` (лінійний пошук). */
+const NPM_HYPHEN_SEPARATOR_RE = /\s-\s/
+
+/** Один whitespace-символ (для розширення меж hyphen-діапазону). */
+const WHITESPACE_RE = /\s/
+
+/**
+ * Ліва межа npm hyphen-діапазону `low - high`.
+ * Роздільник — `\s+-\s+`; знаходимо його першу появу лінійно (без backtracking),
+ * потім розширюємо на суміжні пробіли з обох боків, як робив `\s+`.
+ * @param {string} s рядок сегмента
+ * @returns {string | null} ліва частина (`low`) або `null`, якщо не hyphen-діапазон
+ */
+function npmHyphenRangeLeft(s) {
+  const m = NPM_HYPHEN_SEPARATOR_RE.exec(s)
+  if (!m) {
+    return null
+  }
+  let start = m.index
+  while (start > 0 && WHITESPACE_RE.test(s[start - 1])) {
+    start -= 1
+  }
+  let end = m.index + m[0].length
+  while (end < s.length && WHITESPACE_RE.test(s[end])) {
+    end += 1
+  }
+  const left = s.slice(0, start)
+  const right = s.slice(end)
+  if (!left || !right) {
+    return null
+  }
+  return left
+}
+
+const FIRST_VERSION_NUM_RE = /^(?:v)?(\d+)/i
+
+const PREFIX_GEQ_RE = /^>=\s*/u
+const PREFIX_GT_RE = /^>\s*/u
+const STRIP_CARET_TILDE_EQ_RE = /^[=^~]+\s*/u
+
+/**
+ * Початок блока **nitra: {** у **.ts** / **.mjs** (**capacitor.config**; ключ **nitra**).
+ */
+const RE_NITRA_CONFIG_OBJECT_LEAD_IN = /\bnitra\b\s*:\s*\{|[\u{27}"]nitra[\u{27}"]\s*:\s*\{/u
+
+const RE_COCOAPODS_EXEMPT_SPM = /\biosCocoaPodsBecausePluginsLackSpm\s*:\s*true\b/
+const RE_COCOAPODS_EXEMPT_ALLOW = /\biosCocoaPodsAllowed\s*:\s*true\b/
+
+/**
+ * Мінімальний **major** (нижня межа) для **однієї** OR-частини діапазону npm (без `||` всередині).
+ * @param {string} segment одна частина після `||` або весь рядок
+ * @returns {number | null} null, якщо **`*` / `x` / `latest`**, або **major** **нижньої** межі
+ */
+export function capacitorSegmentMinMajor(segment) {
+  if (typeof segment !== 'string') {
+    return null
+  }
+  const s0 = segment.trim()
+  if (!s0) {
+    return null
+  }
+  const low = s0.toLowerCase()
+  if (s0 === '*' || low === 'x' || low === 'latest') {
+    return null
+  }
+  if (s0.startsWith('<') || s0.startsWith('<=')) {
+    return 0
+  }
+  if (s0.startsWith('>') && !s0.startsWith('>=')) {
+    return firstVersionMajorFromNpmValue(s0.replace(PREFIX_GT_RE, ''))
+  }
+  const hyphenLeft = npmHyphenRangeLeft(s0)
+  if (hyphenLeft !== null) {
+    return firstVersionMajorFromNpmValue(hyphenLeft.trim())
+  }
+  if (s0.startsWith('^') || s0.startsWith('~') || s0.startsWith('=')) {
+    return firstVersionMajorFromNpmValue(s0.replace(STRIP_CARET_TILDE_EQ_RE, ''))
+  }
+  if (s0.startsWith('>=')) {
+    return firstVersionMajorFromNpmValue(s0.replace(PREFIX_GEQ_RE, ''))
+  }
+  return firstVersionMajorFromNpmValue(s0)
+}
+
+/**
+ * Витягує **major** з першого числа у вигляді **X** або **X.Y** / **X.Y.Z** (опційно **v**).
+ * @param {string} t рядок ділянки **версії** (без префікса **операторів**)
+ * @returns {number | null} перше **ціле** (major) або **null**
+ */
+function firstVersionMajorFromNpmValue(t) {
+  const s = t.trim()
+  if (!s) {
+    return null
+  }
+  const m = s.match(FIRST_VERSION_NUM_RE)
+  if (!m) {
+    return null
+  }
+  return Number(m[1])
+}
+
+/**
+ * Мінімальна можлива (нижня) **major**-версія для повного діапазону npm, у т. ч. з `||`.
+ * @param {string} versionRange повне поле `package.json` для **@capacitor/core**
+ * @returns {number | null} **null** якщо **`*` / latest** в одній з частин
+ */
+export function capacitorVersionRangeMinMajor(versionRange) {
+  if (typeof versionRange !== 'string') {
+    return null
+  }
+  const parts = versionRange.split(NPM_OR_PARTS_RE)
+  let overallMin = /** @type {number | null} */ (null)
+  for (const p of parts) {
+    const m = capacitorSegmentMinMajor(p)
+    if (m === null) {
+      return null
+    }
+    if (overallMin === null || m < overallMin) {
+      overallMin = m
+    }
+  }
+  return overallMin
+}
+
+/**
+ * @param {string} versionRange рядок **версії** з `package.json`
+ * @param {number} [min] мінімальний **major** (за замовчуванням `MIN_CAPACITOR_MAJOR`)
+ * @returns {boolean} **true**, якщо нижня межа **≥** **min**
+ */
+export function isCapacitorCoreVersionAtLeast8(versionRange, min = MIN_CAPACITOR_MAJOR) {
+  const low = capacitorVersionRangeMinMajor(versionRange)
+  if (low === null) {
+    return false
+  }
+  return low >= min
+}
+
+/**
+ * @param {(m: string) => void} fail друк помилки
+ * @param {(m: string) => void} pass друк успіху
+ * @param {string} rel відносний **posix**-шлях `package.json`
+ * @param {string} range поле `version` для **@capacitor/core**
+ * @returns {void}
+ */
+function reportOneCapacitorCoreRange(fail, pass, rel, range) {
+  if (isCapacitorCoreVersionAtLeast8(range)) {
+    pass(`«${rel}»: @capacitor/core — діапазон сумісний з ${MIN_CAPACITOR_MAJOR}+`)
+  } else {
+    fail(
+      `«${rel}»: @capacitor/core «${range}» — мінімальна допустима мажорна версія Capacitor ${MIN_CAPACITOR_MAJOR} (capacitor.mdc). Вкажи, наприклад, ^${MIN_CAPACITOR_MAJOR}.0.0`
+    )
+  }
+}
+
+/**
+ * @param {string} rel відносний шлях `package.json`
+ * @param {Record<string, unknown>} obj `dependencies` / `devDependencies` / **…**
+ * @param {{ byPath: Map<string, string>, anyCapacitor: boolean }} out накопичувач **@capacitor** у дереві
+ */
+function recordCapacitorFromDependencyObject(rel, obj, out) {
+  for (const [name, val] of Object.entries(obj)) {
+    if (typeof name === 'string' && name.startsWith('@capacitor/')) {
+      out.anyCapacitor = true
+    }
+    if (name === '@capacitor/core' && typeof val === 'string' && val !== '') {
+      out.byPath.set(rel, val)
+    }
+  }
+}
+
+/**
+ * @param {string} absPath шлях до `package.json`
+ * @param {string} root корінь репозиторію
+ * @param {{ byPath: Map<string, string>, anyCapacitor: boolean }} out накопичувач **byPath** і **anyCapacitor**
+ * @returns {Promise<void>}
+ */
+export async function recordCapacitorFromOnePackageJson(absPath, root, out) {
+  let raw
+  try {
+    raw = await readFile(absPath, 'utf8')
+  } catch {
+    return
+  }
+  let pkg
+  try {
+    pkg = JSON.parse(raw)
+  } catch {
+    return
+  }
+  const rel = (relative(root, absPath) || absPath).replaceAll('\\', '/')
+  for (const block of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    const rec = pkg?.[block]
+    if (rec !== null && rec !== undefined && typeof rec === 'object' && !Array.isArray(rec)) {
+      recordCapacitorFromDependencyObject(rel, /** @type {Record<string, unknown>} */ (rec), out)
+    }
+  }
+}
+
+/**
+ * Зчитує всі `package.json` з дерева, накопичує `byPath` і `anyCapacitor`.
+ * @param {string} root корінь репозиторію
+ * @param {{ byPath: Map<string, string>, anyCapacitor: boolean }} out накопичувач
+ * @returns {Promise<void>}
+ */
+export async function collectCapacitorDataFromAllPackageJson(root, out) {
+  out.anyCapacitor = false
+  if (out.byPath) {
+    out.byPath.clear()
+  } else {
+    out.byPath = new Map()
+  }
+
+  /**
+   * @param {string} dir абсолютний **каталог** для `readdir`
+   * @returns {Promise<void>}
+   */
+  async function walk(dir) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const absPath = join(dir, entry.name)
+      if (entry.isDirectory() && !IGNORED_DIRS_FOR_PACKAGE_JSON.has(entry.name)) {
+        await walk(absPath)
+      } else if (entry.isFile() && entry.name === 'package.json') {
+        await recordCapacitorFromOnePackageJson(absPath, root, out)
+      }
+    }
+  }
+
+  await walk(root)
+}
+
+/**
+ * @param {string} root абсолютний або **cwd**-відносний **корінь** репозиторію
+ * @returns {boolean} **true** якщо `capacitor.config.{json,ts,mjs}` існує
+ */
+export function hasCapacitorConfigInRoot(root) {
+  return (
+    existsSync(join(root, 'capacitor.config.json')) ||
+    existsSync(join(root, 'capacitor.config.ts')) ||
+    existsSync(join(root, 'capacitor.config.mjs'))
+  )
+}
+
+/**
+ * Чи варто застосовувати правила: конфіг **або** **@capacitor/** у залежностях.
+ * @param {string} root корінь
+ * @param {boolean} anyCapacitor чи зустрілось **@capacitor/** у **package.json**
+ * @returns {boolean} **true** якщо застосовуємо **check capacitor**
+ */
+export function isCapacitorRelevantForCheck(root, anyCapacitor) {
+  return hasCapacitorConfigInRoot(root) || anyCapacitor
+}
+
+/**
+ * Рекурсивно шукає `Podfile` у **ios/**, **не** заходячи в **Pods** (кеш CocoaPods) і типові build-каталоги.
+ * @param {string} root корінь репозиторію
+ * @param {string} dir абсолютний каталог
+ * @param {(rel: string) => void} onPodfileRelative **callback** з **posix**-шляхом `Podfile` від **root**
+ * @returns {Promise<boolean>} **true** — знайдено **хоча б один** `Podfile`
+ */
+export async function walkIosForPodfileSkipPods(root, dir, onPodfileRelative) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  for (const e of entries) {
+    if (e.name === 'Pods' || e.name === 'build' || e.name === 'DerivedData') {
+      // skip
+    } else if (e.isFile() === true && e.name === 'Podfile') {
+      const abs = join(dir, e.name)
+      onPodfileRelative((relative(root, abs) || abs).replaceAll('\\', '/'))
+      return true
+    } else if (e.isDirectory() === true) {
+      const abs = join(dir, e.name)
+      const found = await walkIosForPodfileSkipPods(root, abs, onPodfileRelative)
+      if (found === true) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * @param {string} root корінь
+ * @returns {Promise<string | null>} **relative**-шлях `Podfile` (або **null**)
+ */
+export async function findFirstPodfileUnderIosExcludingPods(root) {
+  const iosDir = join(root, 'ios')
+  if (!existsSync(iosDir)) {
+    return null
+  }
+  let first = /** @type {string | null} */ (null)
+  await walkIosForPodfileSkipPods(root, iosDir, rel => {
+    if (first === null || rel.length < first.length) {
+      first = rel
+    }
+  })
+  return first
+}
+
+/**
+ * Чи дозволяє об’єкт **nitra** використання **Podfile** (CocoaPods) на iOS (див. **capacitor.mdc**; **@nitra/**
+ * **SPM** **не** аналізуємо).
+ * @param {unknown} o об’єкт **nitra** з **package.json** / **capacitor.config**
+ * @returns {boolean} **true** якщо **Podfile** дозволено (один з прапорів **true**)
+ */
+export function nitrAObjectAllowsIosCocoaPods(o) {
+  if (o === null || o === undefined || typeof o !== 'object' || Array.isArray(o)) {
+    return false
+  }
+  const r = /** @type {Record<string, unknown>} */ (o)
+  if (r.iosCocoaPodsBecausePluginsLackSpm === true) {
+    return true
+  }
+  return r.iosCocoaPodsAllowed === true
+}
+
+/**
+ * Витягає вихідний текст тіла **{ ... }** після **nitra:** / **"nitra":** у **config**-файлі (**ts** / **mjs**)
+ * (перша відповідність, баланс фігурних дужок).
+ * @param {string} source вміст **.ts** / **.mjs** config
+ * @returns {string | null} фрагмент **`{...}`** після **nitra:** або **null**
+ */
+function extractNitraObjectBodySource(source) {
+  const m = RE_NITRA_CONFIG_OBJECT_LEAD_IN.exec(source)
+  if (!m) {
+    return null
+  }
+  const openBrace = m.index + m[0].length - 1
+  let d = 0
+  for (let i = openBrace; i < source.length; i += 1) {
+    const c = source[i]
+    if (c === '{') {
+      d += 1
+    } else if (c === '}') {
+      d -= 1
+      if (d === 0) {
+        return source.slice(openBrace, i + 1)
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * @param {string} objectBody фрагмент **`{ ... }`** (текст)
+ * @returns {boolean} **true**, якщо в тілі є **iosCocoaPods**…**:** **true**
+ */
+function nitraObjectBodyStringAllowsCocoaPodsExempt(objectBody) {
+  return RE_COCOAPODS_EXEMPT_SPM.test(objectBody) || RE_COCOAPODS_EXEMPT_ALLOW.test(objectBody)
+}
+
+/**
+ * @param {string} absPath повний шлях до **JSON**-файла
+ * @returns {Promise<boolean>} **true**, якщо `obj.nitra` (ключ **nitra** у JSON) — виняток
+ */
+async function pathJsonShowsNitraCocoapodsExempt(absPath) {
+  if (existsSync(absPath) !== true) {
+    return false
+  }
+  try {
+    const t = await readFile(absPath, 'utf8')
+    const j = /** @type {Record<string, unknown>} */ (JSON.parse(t))
+    return nitrAObjectAllowsIosCocoaPods(j['nitra']) === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} root корінь репозиторію
+ * @returns {Promise<boolean>} **true**, якщо **.ts** / **.mjs** містить валідний виняток **nitra**
+ */
+async function capacitorConfigTsMjsNitraCocoapodsExempt(root) {
+  for (const name of ['capacitor.config.ts', 'capacitor.config.mjs']) {
+    const p = join(root, name)
+    if (existsSync(p) === true) {
+      const text = await readFile(p, 'utf8')
+      const body = extractNitraObjectBodySource(text)
+      if (body !== null && nitraObjectBodyStringAllowsCocoaPodsExempt(body)) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * @param {string} root корінь репозиторію (**process.cwd()** у **check**)
+ * @returns {Promise<boolean>} **true** якщо **Podfile** виправдано **nitra**-конфігом
+ */
+async function isIosCocoaPodsExemptByNitraConfig(root) {
+  if ((await pathJsonShowsNitraCocoapodsExempt(join(root, 'package.json'))) === true) {
+    return true
+  }
+  if ((await pathJsonShowsNitraCocoapodsExempt(join(root, 'capacitor.config.json'))) === true) {
+    return true
+  }
+  return capacitorConfigTsMjsNitraCocoapodsExempt(root)
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам capacitor.mdc.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат лінту
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+  const root = ctx.cwd
+
+  const acc = { byPath: new Map(), anyCapacitor: false }
+  await collectCapacitorDataFromAllPackageJson(root, acc)
+  const { byPath, anyCapacitor } = acc
+
+  if (!isCapacitorRelevantForCheck(root, anyCapacitor)) {
+    pass(
+      'Capacitor не виявлено (без capacitor.config у корені, без @capacitor/ у package.json) — check capacitor пропущено'
+    )
+    return reporter.result()
+  }
+
+  pass('Проєкт з ознаками Capacitor — застосовую capacitor.mdc')
+
+  if (byPath.size === 0) {
+    fail(
+      `додай залежність @capacitor/core з діапазоном ^${MIN_CAPACITOR_MAJOR}.0.0 (або іншим, сумісним лише з ${MIN_CAPACITOR_MAJOR}+) у package.json (capacitor.mdc)`
+    )
+  } else {
+    for (const [rel, range] of byPath) {
+      reportOneCapacitorCoreRange(fail, pass, rel, range)
+    }
+  }
+
+  const podfileRel = await findFirstPodfileUnderIosExcludingPods(root)
+  if (podfileRel === null) {
+    if (existsSync(join(root, 'ios'))) {
+      pass('ios/ без Podfile поза Pods/ (лише SPM, capacitor.mdc)')
+    } else {
+      pass('каталог ios/ не знайдено — вимогу iOS/SPM пропущено')
+    }
+  } else if ((await isIosCocoaPodsExemptByNitraConfig(root)) === true) {
+    pass(
+      `iOS: Podfile «${podfileRel}» — дозволено виняток (nitra.iosCocoaPodsBecausePluginsLackSpm / iosCocoaPodsAllowed, capacitor.mdc)`
+    )
+  } else {
+    fail(
+      `iOS: знайдено Podfile «${podfileRel}» — для Capacitor використовуй лише SPM, без CocoaPods, або додай виняток nitra (capacitor.mdc)`
+    )
+  }
+
+  return reporter.result()
+}

package/rules/changelog/consistency/concern.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": { "scope": "full", "glob": ["**/*"] }
+}

package/rules/changelog/consistency/docs/fix-consistency.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: fix-consistency.mjs
+resource: npm/rules/changelog/consistency/fix-consistency.mjs
+docgen:
+  crc: bbb30cf8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл виконує детерміноване створення change-файлів для воркспейсів, у яких виявлено релевантні зміни, але відсутній відповідний change-файл. Він автоматично зчитує опис змін з останнього коміту Git для кожного проблемного воркспейсу та генерує change-файл із рівнем збільшення `patch` в розділі `Changed`. Це реалізує T0-autofix для забезпечення узгодженості.
+
+## Поведінка
+
+Поведінка:
+
+1. Аналізує вихідний текст на наявність маркера, що вказує на наявність релевантних змін без відповідного change-файлу.
+2. Визначає всі воркспейси, які мають цю проблему, використовуючи `patterns`.
+3. Для кожного виявленого воркспейсу автоматично отримує опис змін на основі сутності останнього коміту Git.
+4. Створює change-файл для кожного воркспейсу, встановлюючи рівень збільшення (bump) як `patch` та розділ як `Changed`.
+5. Помилки під час створення change-файлу обробляються локально, і процес не генерує винятків.
+6. `patterns` містить визначення для виконання описаної логіки.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/changelog/consistency/docs/main.md

@@ -0,0 +1,41 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/changelog/consistency/main.mjs
+docgen:
+  crc: 59dac7bd
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 75
+  issues: internal-name:checkPublishedWorkspace,internal-name:runLocalOnlyChecks,anchor-miss:(n-changelog.mdc),judge:inaccurate:0.99
+---
+
+## Огляд
+
+Огляд:
+Цей файл гарантує готовність пакетів у монорепозиторії до публікації. Він сканує кореневі директорії, визначає локальні та зареєстровані пакети, використовуючи інформацію з конфігураційного файлу res.json. Далі він порівнює версію кожного пакета з даними, опублікованими на https://pypi.org/pypi/, та виконує локальні перевірки змін за допомогою Git.
+
+Поведінка:
+Ініціалізує процес перевірки, який аналізує кореневі директорії проєктів монорепозиторію. Проходиться по знайдених директоріях, визначаючись пакети з реєстру та локальні. Для кожного пакета, які можуть бути опубліковані в реєстрі, здійснюється перевірка відповідності `CHANGELOG.md` та порівняння версії з опублікованою через звернення до мережі. Якщо пакети не є опублікованими, виконується перевірка локальних змін на основі інформації з Git. Якщо виявлені зміни, і пакет не має файлу `.changes/CHANGELOG.md`, створюється цей файл з дефолтними даними. При виявленні розбіжностей версій виводиться повідомлення про заборону. Усі операції перехоплюють помилки (fail-safe), не генеруючи зовнішніх винятків, і повертають порожнє значення замість них за певних умов. Фінальний код виходу визначається на основі результатів перевірок.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається `main`.
+2. Merge пропускається цілком: і готовий merge-коміт (HEAD із другим предком), і merge У ПРОЦЕСІ (маркер `MERGE_HEAD` під час `git commit` у pre-commit hook, коли `HEAD^2` ще не існує) — changeset документують feature-коміти, autofix шумного «Merge…»-changeset не створює.
+3. Знаходяться кореневі директорії проєктів монорепо.
+4. Проходиться по знайдених директоріях, визначаються пакети з реєстру та ті, що є локальними.
+5. База порівняння feature-гілки — НОВІШИЙ merge-base серед локальної та `origin/`-версії базової гілки (dev/main): застарілий локальний `main` не видає реліз-коміти, вже інтегровані в origin, за «ручний bump поза CI»; локальний main попереду origin так само валідний; репо без remote працює на локальних гілках.
+6. Для кожного пакета, які можуть бути опубліковані в реєстрі, викликається `checkPublishedWorkspace`.
+7. `checkPublishedWorkspace` перевіряє наявність та відповідність `CHANGELOG.md`, а також порівнює версію пакета з опублікованою версією через мережевий запит до https://pypi.org/pypi/.
+8. Якщо пакети не є опублікованими, викликається `runLocalOnlyChecks` для перевірки змін.
+9. `runLocalOnlyChecks` використовує інформацію з Git для порівняння поточного стану з базою гілки.
+10. Якщо виявлені зміни, і пакет не має файлу `.changes/CHANGELOG.md`, то в режимі автоматичного виправлення створюється цей файл з дефолтними даними.
+11. При виявленні різниці версій, яка свідчить про ручний збій (version вищий, ніж опублікований), виводиться повідомлення про заборону.
+12. `main` повертає код виходу на основі результатів перевірок.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/changelog/consistency/fix-consistency.mjs

@@ -0,0 +1,71 @@
+/**
+ * T0-autofix для `changelog/consistency` — детерміноване створення change-файлу
+ * для воркспейсів з релевантними змінами без change-файлу. Subject останнього
+ * git-коміту стає описом; bump завжди `patch`.
+ *
+ * Unified lint surface: structured violations (test(violations)/apply(violations,ctx)).
+ * Назви воркспейсів читаються з `v.message` ("<ws>: є релевантні зміни, але немає
+ * change-файлу"), не з агрегованого output-рядка.
+ */
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+
+import { writeChange } from '../../release/change.mjs'
+
+const MISSING_CHANGE_RE = /є релевантні зміни, але немає change-файлу/u
+/** Витягує мітку воркспейсу з message-а одного violation. */
+const MISSING_CHANGE_LABEL_RE = /^(\S+): є релевантні зміни, але немає change-файлу/u
+
+const CHANGE_BUMP = 'patch'
+const CHANGE_SECTION = 'Changed'
+const CHANGE_FALLBACK_MESSAGE = 'оновлення'
+
+/**
+ * @param {string} cwd корінь репозиторію
+ * @returns {string} непорожній опис
+ */
+function autoChangeMessage(cwd) {
+  const r = spawnSync('git', ['log', '-1', '--format=%s'], { cwd, encoding: 'utf8' })
+  const subject = r.status === 0 ? (r.stdout ?? '').trim() : ''
+  return subject || CHANGE_FALLBACK_MESSAGE
+}
+
+/**
+ * Мітка воркспейсу (`<root>` для кореня) → шлях для `writeChange` (`.` для кореня).
+ * @param {string} label мітка з повідомлення
+ * @returns {string} workspace для writeChange
+ */
+function labelToWorkspace(label) {
+  return label === '<root>' ? '.' : label
+}
+
+/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'changelog-create-change-file',
+    test: violations => violations.some(v => MISSING_CHANGE_RE.test(v.message)),
+    apply: async (violations, ctx) => {
+      const cwd = ctx.cwd
+      const workspaces = []
+      for (const v of violations) {
+        const m = MISSING_CHANGE_LABEL_RE.exec(v.message)
+        if (m) workspaces.push(labelToWorkspace(m[1]))
+      }
+      if (workspaces.length === 0) return { touchedFiles: [] }
+
+      const message = autoChangeMessage(cwd)
+      const touchedFiles = []
+      for (const ws of new Set(workspaces)) {
+        const rel = await writeChange({ bump: CHANGE_BUMP, section: CHANGE_SECTION, message, ws, cwd })
+        const created = ws === '.' ? rel : join(ws, rel)
+        const abs = join(cwd, created)
+        ctx.recordWrite?.(abs)
+        touchedFiles.push(abs)
+      }
+      return {
+        touchedFiles,
+        message: `створено change-файл (${CHANGE_BUMP}/${CHANGE_SECTION}): ${touchedFiles.join(', ')}`
+      }
+    }
+  }
+]