@7n/rules 1.0.0

package/scripts/ensure-n-rules-dev-dependencies.mjs

@@ -0,0 +1,217 @@
+/**
+ * Дописує `@7n/rules` у `devDependencies` workspace-root `package.json` проєкту, якщо пакет ще
+ * не оголошено ні в `devDependencies`, ні в `dependencies`.
+ *
+ * Використовується CLI `n-rules` при кожному запуску (`npx \@7n/rules`, зокрема `check`), щоб
+ * команда `check` і скрипти з `node_modules/@7n/rules/scripts/` були відтворювані після
+ * `bun install` / `npm install`, а не лише з кешу npx. Корінь визначається тільки за наявністю поля
+ * `workspaces` у `package.json` поруч із поточною директорією запуску.
+ *
+ * Версія діапазону: `^<version>` з поля `version` установленого пакету `@7n/rules`.
+ *
+ * Self-upgrade: якщо пакет уже присутній у `devDependencies` зі **старішим** числовим піном,
+ * пін апгрейдиться до `^<version>` (щоб `npx \@7n/rules` завжди підтягував devDep до версії CLI,
+ * а self-lint не відставав). Нижчі за bundled або нечислові піни (`workspace:*`, `latest`, git-url)
+ * не чіпаються; запис у `dependencies` (нестандартне розміщення) теж лишається незмінним.
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = '@7n/rules'
+const LEGACY_PACKAGE_NAME = '@nitra/cursor'
+
+// Числовий semver-діапазон: опційний (оператор + його пробіли) одним блоком + major[.minor[.patch]].
+// Пробіли після оператора всередині опційної групи (не окремим `\s*`), щоб прибрати неоднозначне
+// подвійне `\s*` і backtracking (super-linear-regex). Семантика збігу — та сама.
+const NUMERIC_RANGE_RE = /^\s*(?:(?:\^|~|>=|<=|>|<|=|v)\s*)?(\d+)(?:\.(\d+))?(?:\.(\d+))?/u
+
+/**
+ * Розбирає npm-діапазон на числові компоненти `[major, minor, patch]`.
+ * @param {unknown} range значення піна з `package.json` (напр. `"^12.19.0"`)
+ * @returns {[number, number, number] | null} компоненти версії або `null` для нечислового специфікатора
+ */
+function parseVersionParts(range) {
+  if (typeof range !== 'string') {
+    return null
+  }
+  const m = NUMERIC_RANGE_RE.exec(range)
+  if (!m) {
+    return null
+  }
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)]
+}
+
+/**
+ * Чи bundled-версія строго новіша за поточний пін (для рішення про self-upgrade).
+ * @param {string} bundled версія встановленого пакета (напр. `"13.2.6"`)
+ * @param {unknown} current поточний діапазон із `package.json`
+ * @returns {boolean} `true`, якщо bundled новіша і обидва піни числові; інакше `false`
+ */
+function isBundledNewer(bundled, current) {
+  const b = parseVersionParts(bundled)
+  const c = parseVersionParts(current)
+  if (!b || !c) {
+    return false
+  }
+  for (let i = 0; i < 3; i++) {
+    if (b[i] > c[i]) {
+      return true
+    }
+    if (b[i] < c[i]) {
+      return false
+    }
+  }
+  return false
+}
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const bundledPkgPath = join(scriptDir, '..', 'package.json')
+
+/**
+ * Версія з `package.json` пакету `@7n/rules` (каталог на рівень вище за `scripts/`).
+ * @returns {Promise<string | null>} поле `version` рядком або `null`, якщо файлу немає / помилка парсингу
+ */
+export async function readBundledPackageVersion() {
+  if (!existsSync(bundledPkgPath)) {
+    return null
+  }
+  try {
+    const raw = await readFile(bundledPkgPath, 'utf8')
+    const pkg = JSON.parse(raw)
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Читає JSON-обʼєкт із диска.
+ * @param {string} path шлях до JSON-файлу
+ * @returns {Promise<Record<string, unknown> | null>} обʼєкт або `null`, якщо файл нечитабельний
+ */
+async function readJsonObject(path) {
+  let raw
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return null
+  }
+
+  try {
+    const value = JSON.parse(raw)
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Читає `package.json` поруч зі стартовою директорією, якщо це workspace-root.
+ * @param {string} startDir директорія, з якої запущено CLI
+ * @returns {Promise<{ path: string, pkg: Record<string, unknown> } | null>} workspace-root package або `null`
+ */
+async function readAdjacentWorkspaceRootPackageJson(startDir) {
+  const pkgPath = join(startDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return null
+  }
+
+  const pkg = await readJsonObject(pkgPath)
+  return pkg && Object.hasOwn(pkg, 'workspaces') ? { path: pkgPath, pkg } : null
+}
+
+/**
+ * Переносить legacy-ключ `@nitra/cursor` на `@7n/rules` у devDependencies/dependencies (in-place).
+ * Пін зберігається; якщо нова назва вже оголошена у секції — legacy-ключ просто видаляється.
+ * @param {Record<string, unknown>} pkg вміст package.json (мутується)
+ * @param {{ silent?: boolean }} options `silent` — не писати в консоль
+ * @returns {boolean} `true`, якщо було що мігрувати
+ */
+function migrateLegacyPackageKey(pkg, options) {
+  let migrated = false
+  for (const section of ['devDependencies', 'dependencies']) {
+    const deps = pkg[section]
+    if (!deps || typeof deps !== 'object' || Array.isArray(deps) || !(LEGACY_PACKAGE_NAME in deps)) {
+      continue
+    }
+    if (!(PACKAGE_NAME in deps) && typeof deps[LEGACY_PACKAGE_NAME] === 'string') {
+      deps[PACKAGE_NAME] = deps[LEGACY_PACKAGE_NAME]
+    }
+    delete deps[LEGACY_PACKAGE_NAME]
+    migrated = true
+    if (!options.silent) {
+      console.error(`📝 Мігровано ${LEGACY_PACKAGE_NAME} → ${PACKAGE_NAME} у ${section}\n`)
+    }
+  }
+  return migrated
+}
+
+/**
+ * Якщо у workspace-root `package.json` немає `@7n/rules` у `devDependencies` і `dependencies`,
+ * дописує `devDependencies["@7n/rules"]` зі значенням `^<bundledVersion>`.
+ * @param {string} root стартова директорія проєкту (зазвичай `process.cwd()`)
+ * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
+ *   `silent` — не писати в консоль при успішному оновленні
+ * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ */
+export async function ensureNRulesInRootDevDependencies(root, options = {}) {
+  const workspaceRoot = await readAdjacentWorkspaceRootPackageJson(root)
+  if (!workspaceRoot) {
+    return false
+  }
+  const { path: pkgPath, pkg } = workspaceRoot
+
+  const ver = options.bundledVersion ?? (await readBundledPackageVersion())
+  if (!ver) {
+    return false
+  }
+
+  // Міграція перейменування: legacy-ключ @nitra/cursor → @7n/rules у тій самій секції
+  // (пін зберігається; гілка self-upgrade нижче за потреби його підніме).
+  const legacyMigrated = migrateLegacyPackageKey(pkg, options)
+  if (legacyMigrated) {
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+  }
+
+  // @7n/rules у dependencies — нестандартне розміщення, не чіпаємо.
+  const deps = pkg.dependencies
+  if (deps && typeof deps === 'object' && PACKAGE_NAME in deps) {
+    return legacyMigrated
+  }
+
+  const devDeps = pkg.devDependencies
+  const current = devDeps && typeof devDeps === 'object' && !Array.isArray(devDeps) ? devDeps[PACKAGE_NAME] : undefined
+
+  // Уже присутній у devDependencies: self-upgrade піна лише якщо bundled строго новіша
+  // (ніколи не понижуємо; нечислові піни — workspace:*/latest/git — лишаємо як є).
+  if (current !== undefined) {
+    if (!isBundledNewer(ver, current)) {
+      return legacyMigrated
+    }
+    pkg.devDependencies[PACKAGE_NAME] = `^${ver}`
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    if (!options.silent) {
+      console.error(`⬆️  Оновлено ${PACKAGE_NAME} ${current} → ^${ver} у devDependencies у package.json\n`)
+    }
+    return true
+  }
+
+  // Відсутній — дописуємо.
+  if (!pkg.devDependencies || typeof pkg.devDependencies !== 'object' || Array.isArray(pkg.devDependencies)) {
+    pkg.devDependencies = {}
+  }
+
+  pkg.devDependencies[PACKAGE_NAME] = `^${ver}`
+
+  const out = `${JSON.stringify(pkg, null, 2)}\n`
+  await writeFile(pkgPath, out, 'utf8')
+
+  if (!options.silent) {
+    console.error(`📝 Додано ${PACKAGE_NAME}@^${ver} у devDependencies у package.json\n`)
+  }
+
+  return true
+}

package/scripts/hook.mjs

@@ -0,0 +1,100 @@
+/**
+ * Thin hook entrypoint для Claude Code hooks: зчитує контекст (stdin / git),
+ * делегує в `detectAll` (read-only), перекодовує exit-код у hook-протокол (1 → 2).
+ *
+ * Режими:
+ *   --post-tool-use  PostToolUse: file_path зі stdin JSON Claude Code.
+ *   --stop           Stop: робоче дерево vs HEAD (`git diff HEAD` + untracked).
+ */
+import { once } from 'node:events'
+import { relative, resolve } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { detectAll } from './lib/lint-surface/run-detectors.mjs'
+import { collectChangedFiles } from './lib/changed-files.mjs'
+
+const RE_BACKSLASH = /\\/gu
+
+/**
+ * Абсолютний або відносний `file_path` від Claude Code → posix-relative до `cwd`, як і
+ * решта `ctx.files` (контракт `collectChangedFiles`). Без цього конкретні детектори
+ * (напр. `text/run-v8r`), що спавнять зовнішні тули, отримують абсолютний шлях і падають
+ * (`ignore`-залежність v8r вимагає `path.relative()`d pathname).
+ * @param {string} fp сирий `file_path` зі stdin
+ * @param {string} cwd корінь репо
+ * @returns {string} posix-шлях відносно cwd
+ */
+function toRelativePosix(fp, cwd) {
+  return relative(cwd, resolve(cwd, fp)).replace(RE_BACKSLASH, '/')
+}
+
+/**
+ * @returns {Promise<string>} вміст stdin або '' на TTY
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) return ''
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', c => {
+    chunks.push(c)
+  })
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // error на stdin — повертаємо що встигли
+  }
+  return chunks.join('')
+}
+
+/**
+ * Дістає `tool_input.file_path` зі stdin JSON Claude Code PostToolUse hook.
+ * @param {string} json сирий stdin
+ * @returns {string|null} шлях до файлу або null, якщо відсутній/невалідний JSON
+ */
+export function extractFilePath(json) {
+  if (!json) return null
+  try {
+    const fp = JSON.parse(json)?.tool_input?.file_path
+    return typeof fp === 'string' && fp !== '' ? fp : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Claude Code при exit 2 показує агенту лише stderr (stdout hook-протоколом ігнорується),
+ * тож звіт про порушення мусить іти саме туди — інакше агент бачить «blocking error»
+ * без жодного пояснення, що саме заблокувало tool-виклик.
+ * @param {string} s фрагмент звіту
+ * @returns {void} результат
+ */
+function logToStderr(s) {
+  process.stderr.write(s)
+}
+
+/**
+ * CLI для `n-rules hook`.
+ * @param {string[]} argv аргументи після 'hook'
+ * @returns {Promise<number>} exit-код (0 — чисто; 2 — є порушення hook-протокол)
+ */
+export async function runHookCli(argv) {
+  const cwd = processCwd()
+  const postToolUse = argv.includes('--post-tool-use')
+  const stop = argv.includes('--stop')
+
+  if (!postToolUse && !stop) {
+    process.stderr.write('hook: потрібен --post-tool-use або --stop\n')
+    return 1
+  }
+
+  if (postToolUse) {
+    const fp = extractFilePath(await readStdin())
+    if (!fp) return 0
+    const { exitCode } = await detectAll({ files: [toRelativePosix(fp, cwd)], cwd, log: logToStderr })
+    return exitCode === 0 ? 0 : 2
+  }
+
+  const files = collectChangedFiles(cwd)
+  const { exitCode } = await detectAll({ files, cwd, log: logToStderr })
+  return exitCode === 0 ? 0 : 2
+}

package/scripts/lib/adr/docs/index.md

@@ -0,0 +1,12 @@
+---
+type: Directory Index
+title: npm/scripts/lib/adr
+resource: npm/scripts/lib/adr/
+---
+
+# npm/scripts/lib/adr
+
+| Файл | Тип |
+|---|---|
+| [normalize-cli.mjs](normalize-cli.md) | JS Module |
+| [normalize-pipeline.mjs](normalize-pipeline.md) | JS Module |

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

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: normalize-cli.mjs
+resource: npm/scripts/lib/adr/normalize-cli.mjs
+docgen:
+  crc: c93ea883
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Виконувати локальну обгортку для нормалізації рішень ADR через `runAdrNormalizeLocalCli`. Цей механізм використовується замість одноразового виклику LLM у робочому процесі, де скрипт `.claude/hooks/normalize-decisions.sh` готує батч та список "clean"-ADR. Функція зчитує списки чернеток (задані через `--batch`) та "clean"-ADR (задані через `--clean`) з файлів. Конфігурація нормалізації визначається через змінні середовища, такі як `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES`. Пайплайн обробляє ці дані, виводячи JSON-контракт із операціями у стандартний вихід (stdout) для подальшого парсингу зовнішнім bash-скриптом, тоді як детальний прогрес записується у стандартний помилковий вихід (stderr).
+
+## Поведінка
+
+1. `runAdrNormalizeLocalCli` ініціалізує процес нормалізації, зчитуючи список шляхів до чернеток (`--batch`) та, за наявності, список імен очищених ADR (`--clean`).
+2. Система визначає директорію для пошуку ADR, використовуючи значення `--adr-dir` або за замовчуванням `cwd/docs/adr`.
+3. Якщо не надано файл для батчу, процес завершується з помилкою.
+4. Зчитуються вмісти та отримуються базові імена чернеток з файлу, вказаного у `--batch`, після нормалізації шляхів відносно `adrDir`.
+5. Зчитується список базових імен ADR, що вважаються "чистими", з файлу, вказаного у `--clean`.
+6. Система зчитує змінні середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES` для визначення конфігурації нормалізації.
+7. Викликається внутрішній пайплайн нормалізації з усіма зібраними даними.
+8. Прогрес виконання пайплайну виводиться у stderr.
+9. У stdout виводиться JSON-контракт, що містить список операцій, які потрібно застосувати.
+10. У stderr додатково виводиться кількість виконаних операцій та статистика процесу.
+
+## Публічний API
+
+- runAdrNormalizeLocalCli — Виводить JSON з операцій для нормалізації ADR у стандартний вивід.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,45 @@
+---
+type: JS Module
+title: normalize-pipeline.mjs
+resource: npm/scripts/lib/adr/normalize-pipeline.mjs
+docgen:
+  crc: 9c2cbb81
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+Реалізує локально-орієнтований конвеєр для нормалізації ADR. У цій системі JavaScript виконує оркестрацію, тоді як LLM відповідає виключно на вузькі, верифіковані питання. Процес включає відбір кандидатів на основі лексичної схожості (Stage 0: retrieval), бінарне судження між записами (Stage 1: edge-judge) та класифікацію драфтів (Stage 1b: kind-judge). Система об'єднує підтверджені ребра через алгоритм Union-Find (Stage 1c: cluster) для вибору опорного елемента (anchor) та призначення операцій. Далі, LLM вилучає секції в JSON (Stage 2: gen-MADR), після чого JS збирає канон. На фінальній стадії, LLM створює прозу про змін (Stage 3: gen-merge), яку JS додає до документа з відповідним заголовком.
+
+## Поведінка
+
+Поведінка
+tokenize токенізує назву чи слаг, повертаючи множину значущих токенів, фільтруючи стоп-слова та занадто короткі елементи.
+jaccard обчислює коефіцієнт Jaccard між двома множинами токенів.
+draftTitle витягує заголовок з тіла чернетки, використовуючи специфічні шаблони або шукаючи перший заголовок H1, не класифікований як секція MADR.
+isNoDecision перевіряє тіло чернетки на наявність маркерів, що свідчать про те, що рішення не було прийняте, без використання LLM.
+buildEdges будує пари (ребра) між чернетками та між чернетками і список чистих ADR, виходячи з лексичної схожості.
+validateMadr перевіряє згенерований текст MADR на відповідність формату OKF (наприклад, наявність YAML frontmatter, заголовок, статуси та секції).
+madrDate визначає стандартну ISO-дату для ADR, використовуючи або поле `captured` з чернетки, або префікс імені файлу.
+normalizeSections перетворює сирий JSON-вивід моделі на структурований об'єкт, нормалізуючи типи даних (наприклад, рядок у масив).
+assembleMadr збирає канонічний текст MADR, комбінуючи наданий заголовок, ISO-дату та нормалізовані секції, створюючи кінцевий markdown.
+genMadr викликає LLM для вилучення змісту ADR із чернетки, а потім конструює та валідує повний MADR за допомогою `assembleMadr` та `validateMadr`.
+normalizePipeline виконує повний конвеєр: ідентифікує кластери чернеток, визначає операції (delete, rewrite, merge-anchor тощо) та ініціює виклики LLM для генерації контенту та додатків.
+
+## Публічний API
+
+Here is the rewritten list as concise bullet points:
+
+* tokenize — Перетворює назву чи слаг у набір значущих слів, розділених пробілами та дефісами.
+* jaccard — Обчислює ступінь схожості між двома наборами слів.
+* draftTitle — Знаходить основний заголовок чернетки, починаючи з ADR-рядка; якщо його немає, шукає перший H1, інакше бере назву файлу.
+* isNoDecision — Автоматично виявляє чернетки, де рішення відсутнє (наприклад, через переривання транскрипту), щоб їх не обробляти LLM.
+* buildEdges — Створює потенційні зв'язки між елементами на основі схожості слів.
+* validateMadr — Перевіряє якість згенерованого документа MADR автоматично.
+* madrDate — Визначає дату документа у форматі ISO, використовуючи дані з метаданих чернетки або дату створення файлу.
+* normalizeSections — Стандартизує вивід генеративної моделі в чітку структуру секцій, виправляючи невеликі помилки формату.
+* assembleMadr — Збирає повний документ MADR у версії 4.0.0, використовуючи фіксовану структуру та контент від інших частин.
+* genMadr — Генерує чернетку документа MADR на основі заданих даних.
+* normalizePipeline — Виконує послідовність усіх кроків обробки даних, повертаючи список виконаних операцій та статистику.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

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

@@ -0,0 +1,74 @@
+/**
+ * CLI-обгортка локального ADR-нормалізатора (`n-rules adr-normalize-local`).
+ *
+ * Прод-шлях `.claude/hooks/normalize-decisions.sh` викликає цю команду як
+ * local-backend замість single-shot LLM-виклику: bash готує батч і clean-список,
+ * CLI проганяє `normalizePipeline` і друкує у stdout той самий контракт
+ * `{ "operations": [...] }`, що його далі парсить і застосовує bash. Прогрес —
+ * у stderr (потрапляє в normalize-decisions.log).
+ *
+ * Аргументи:
+ *   --batch <file>    newline-список абсолютних шляхів до чернеток батчу
+ *   --clean <file>    newline-список basename-ів clean-ADR (merge-into кандидати)
+ *   --adr-dir <dir>   тека docs/adr (для резолву basename ↔ шлях; default cwd/docs/adr)
+ *
+ * ENV:
+ *   ADR_NORMALIZE_ALLOW_CLOUD=1  дозволити хмарну ескалацію tier-каскаду (default off)
+ *   ADR_NORMALIZE_VOTES=N        голосів self-consistency для clean-ребер (default 2)
+ */
+import { env } from 'node:process'
+import { readFileSync } from 'node:fs'
+import { basename, isAbsolute, join } from 'node:path'
+import { normalizePipeline } from './normalize-pipeline.mjs'
+
+/**
+ * Парсить `--key value` пари у плоский об'єкт.
+ * @param {string[]} argv масив аргументів командного рядка
+ * @returns {Record<string, string>} мапа ключ→значення з `--key value` пар
+ */
+function parseArgs(argv) {
+  const out = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) { out[a.slice(2)] = argv[i + 1]; i++ }
+  }
+  return out
+}
+
+const readLines = (file) =>
+  readFileSync(file, 'utf8').split('\n').map((s) => s.trim()).filter(Boolean)
+
+/**
+ * Точка входу субкоманди. Друкує `{operations}` JSON у stdout, прогрес — у stderr.
+ * @param {string[]} argv аргументи після назви команди
+ * @returns {number} exit-code (0 — успіх, 1 — помилка вводу)
+ */
+export async function runAdrNormalizeLocalCli(argv) {
+  const args = parseArgs(argv)
+  const adrDir = args['adr-dir'] ?? join(process.cwd(), 'docs/adr')
+  if (!args.batch) {
+    console.error('Usage: n-rules adr-normalize-local --batch <file> [--clean <file>] [--adr-dir <dir>]')
+    return 1
+  }
+
+  const batchPaths = readLines(args.batch)
+  const drafts = batchPaths.map((p) => {
+    const abs = isAbsolute(p) ? p : join(adrDir, p)
+    return { file: basename(abs), body: readFileSync(abs, 'utf8') }
+  })
+  const cleanList = args.clean ? readLines(args.clean).map((c) => basename(c)) : []
+
+  const allowCloud = env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
+  const votes = Number(env.ADR_NORMALIZE_VOTES) || 2
+
+  const { operations, stats, trace } = await normalizePipeline(drafts, cleanList, {
+    allowCloud,
+    votes,
+    onProgress: (m) => console.error(`adr-normalize-local: ${m}`)
+  })
+
+  console.error(`adr-normalize-local: ${operations.length} операцій, stats=${JSON.stringify(stats)}`)
+  console.error(`adr-normalize-local: decisions=${JSON.stringify(trace.decisions)}`)
+  process.stdout.write(JSON.stringify({ operations }))
+  return 0
+}