@7n/rules 1.0.0

package/scripts/lib/assert-project-root.mjs

@@ -0,0 +1,77 @@
+/**
+ * Guard для дефолтної синхронізації `npx \@7n/rules` (гілка без підкоманди).
+ *
+ * Дефолтний sync (`runSync` у `bin/n-rules.js`) скаффолдить у `cwd()` керовані
+ * артефакти — `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`,
+ * `CLAUDE.md`, `.n-rules.json`, `.gitignore` — і запускає `bun install`. Усе це
+ * розраховане на **корінь** проєкту-споживача. Якщо бінар викликати напряму
+ * (`bun npm/bin/n-rules.js`, `node …/n-rules.js`) з піддиректорії git-репо,
+ * `cwd()` — та піддиректорія, і конфіг розкидається не туди.
+ *
+ * `bun run start`/`npm start` цей кейс не створює (менеджер скидає cwd на корінь
+ * пакета), але прямий виклик бінаря — створює. Тому guard прив'язаний до
+ * **git-кореня**, а не до конкретного монорепо: CLI публічний і легітимно
+ * запускається в корені будь-якого репо-споживача.
+ */
+import { spawnSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { cwd } from 'node:process'
+
+/**
+ * Корінь git-репозиторію для `dir` через `git rev-parse --show-toplevel`.
+ * Повертає realpath-шлях кореня або `null`, якщо `dir` поза git-репо чи `git`
+ * недоступний — у такому разі визначити корінь неможливо, тож не блокуємо.
+ * @param {string} [dir] каталог, з якого питаємо git
+ * @returns {string | null} абсолютний (realpath) корінь репо або null
+ */
+export function gitToplevel(dir = cwd()) {
+  const res = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' })
+  if (res.status !== 0 || typeof res.stdout !== 'string') return null
+  const top = res.stdout.trim()
+  return top.length > 0 ? top : null
+}
+
+/**
+ * Безпечний realpath: повертає реальний шлях `dir`, а якщо його не існує —
+ * сам `dir` без змін (порівняння нижче все одно дасть коректний результат).
+ * Потрібен бо `git rev-parse --show-toplevel` віддає realpath (symlink'и
+ * розгорнуті), а `cwd()` — ні; без нормалізації корінь під symlink-шляхом
+ * (типово `/var` → `/private/var` на macOS) хибно вважався б піддиректорією.
+ * @param {string} dir шлях для нормалізації
+ * @returns {string} realpath або вихідний шлях
+ */
+function safeRealpath(dir) {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return dir
+  }
+}
+
+/**
+ * Кидає помилку, якщо `dir` — піддиректорія git-репозиторію (тобто не його
+ * корінь). Поза git-репо (немає toplevel) — пропускає без помилки. У git-worktree
+ * (`.worktrees/<branch>/`) toplevel = корінь самого worktree, тож запуск із нього
+ * проходить — гард ловить лише старт із піддиректорії робочого дерева.
+ *
+ * Викликати перед мутаційними діями (default sync, `fix`, `lint`, `coverage`,
+ * `change`, `release`), які скаффолдять / переписують файли в CWD. Не для
+ * підкоманд із власним `--root` чи read-only-логікою.
+ * @param {string} [dir] каталог, що перевіряємо (типово `cwd()`)
+ * @param {string} [action] людинозрозумілий опис дії для тексту помилки
+ * @throws {Error} коли `dir` всередині git-репо, але не його корінь
+ * @returns {void}
+ */
+export function assertCwdIsProjectRoot(dir = cwd(), action = 'Команда @7n/rules мутує проєкт у поточному каталозі') {
+  const top = gitToplevel(dir)
+  if (top === null) return
+  const here = safeRealpath(dir)
+  if (here === top) return
+  throw new Error(
+    `❌ @7n/rules запущено не в корені проєкту.\n` +
+      `   Поточний каталог: ${here}\n` +
+      `   Корінь git-репо:  ${top}\n` +
+      `   ${action} — із піддиректорії це зачепило б не той каталог.\n` +
+      `   Перейдіть у корінь репозиторію: cd ${top}`
+  )
+}

package/scripts/lib/blue-oak.mjs

@@ -0,0 +1,41 @@
+/**
+ * Читає вбудований Blue Oak Council snapshot (`npm/data/blue-oak.json`).
+ * Повертає множину SPDX-ідентифікаторів рівнів Model+Gold+Silver+Bronze.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DATA_PATH = join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), 'data', 'blue-oak.json')
+
+/**
+ * Прибирає обрамлювальні дужки й пробіли навколо SPDX-ідентифікатора.
+ * @param {string} s SPDX-фрагмент (можливо у дужках)
+ * @returns {string} нормалізований ідентифікатор без обрамлення
+ */
+const clean = s => s.trim().replaceAll(/^\(|\)$/g, '')
+
+/**
+ * Множина SPDX-ідентифікаторів Blue Oak Bronze і вище (Model+Gold+Silver+Bronze).
+ * Ліцензії з цього списку вважаються permissive-safe для комерційного проєкту.
+ * @returns {Set<string>} множина дозволених SPDX-ідентифікаторів
+ */
+export function getBronzeAndAbove() {
+  const { bronzeAndAbove } = JSON.parse(readFileSync(DATA_PATH, 'utf8'))
+  return new Set(bronzeAndAbove)
+}
+
+/**
+ * Перевіряє SPDX-вираз проти Blue Oak Bronze+ allowlist.
+ * Підтримує: одиночний ID, `A OR B` (будь-який дозволений = OK), `A AND B` (усі мають бути дозволені).
+ * `NOASSERTION` і `NONE` завжди → false.
+ * @param {string} expression SPDX-вираз з pip-licenses або іншого інструмента
+ * @param {Set<string>} allowed множина дозволених SPDX-ідентифікаторів
+ * @returns {boolean} чи дозволений вираз згідно allowlist
+ */
+export function isSpdxAllowed(expression, allowed) {
+  if (!expression || expression === 'NOASSERTION' || expression === 'NONE') return false
+  if (expression.includes(' AND ')) return expression.split(' AND ').every(p => allowed.has(clean(p)))
+  if (expression.includes(' OR ')) return expression.split(' OR ').some(p => allowed.has(clean(p)))
+  return allowed.has(clean(expression))
+}

package/scripts/lib/changed-files.mjs

@@ -0,0 +1,83 @@
+/**
+ * Збір змінених файлів для quick-режиму lint-оркестратора.
+ *
+ * Quick лінтить лише те, що змінено в робочому дереві: tracked-modified + staged
+ * (`git diff HEAD`) і нові untracked (`git ls-files --others --exclude-standard`).
+ * Видалені файли не повертаються. Поза git-репо або при помилці git — порожній список.
+ */
+import { spawnSync } from 'node:child_process'
+
+/**
+ * @param {string[]} args аргументи git
+ * @param {string} cwd корінь
+ * @returns {string[]} непорожні рядки stdout або [] при помилці
+ */
+function gitLines(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  if (r.status !== 0 || r.error) return []
+  return r.stdout
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+/**
+ * Relative-posix список змінених + untracked файлів робочого дерева.
+ * @param {string} [cwd] корінь репо
+ * @returns {string[]} унікальні шляхи (без видалених)
+ */
+export function collectChangedFiles(cwd = process.cwd()) {
+  const modified = gitLines(['diff', 'HEAD', '--name-only', '--diff-filter=ACMR'], cwd)
+  const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
+  return [...new Set([...modified, ...untracked])]
+}
+
+/**
+ * Визначає git base для scoped-перевірок без зовнішнього runtime-стану.
+ * Пріоритет: локальна `main`, потім `origin/main`; якщо обидві відсутні,
+ * повертає null і caller порівнює лише робоче дерево з HEAD.
+ * @param {string} [cwd] корінь репо
+ * @returns {string|null} merge-base commit або null
+ */
+export function resolveChangedBase(cwd = process.cwd()) {
+  for (const ref of ['main', 'origin/main']) {
+    const result = spawnSync('git', ['merge-base', 'HEAD', ref], { cwd, encoding: 'utf8' })
+    const base = result.status === 0 && !result.error ? result.stdout.trim() : ''
+    if (base) return base
+  }
+  return null
+}
+
+/**
+ * Список змінених + untracked файлів **відносно базового комміту**.
+ *
+ * `git diff <base>` (без `..`/`...`, без `HEAD`) порівнює base-комміт із поточним
+ * **робочим деревом** — тобто однаково ловить і закомічене від base, і staged, і
+ * незакомічені модифікації. Це гарантує однакову поведінку незалежно від того, чи
+ * зміни вже закомічені у worktree. Без `base` — fallback на `collectChangedFiles`
+ * (робоче дерево vs HEAD).
+ * @param {string|null} [base] базовий комміт
+ * @param {string} [cwd] корінь репо
+ * @returns {string[]} унікальні шляхи (без видалених)
+ */
+export function collectChangedFilesSince(base, cwd = process.cwd()) {
+  if (!base) return collectChangedFiles(cwd)
+  // Fail-closed: недосяжний base (rebase/force-update/shallow prune) інакше дав би `git diff`
+  // exit 128 → порожній список → gate мовчки пройшов би без перевірки. Краще явна помилка.
+  // `^{commit}` — git peel-синтаксис (літерал), не template-інтерполяція; окрема строкова
+  // константа тримає обидва правила тихими (no-useless-concat і no-incorrect-template-string-interpolation).
+  const commitPeel = '^{commit}'
+  const verify = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${base}${commitPeel}`], {
+    cwd,
+    encoding: 'utf8'
+  })
+  if (verify.status !== 0 || verify.error) {
+    throw new Error(
+      `collectChangedFilesSince: base-комміт «${base}» недосяжний у ${cwd} ` +
+        '(rebase/force-update?) — coverage --changed не може визначити scope'
+    )
+  }
+  const changed = gitLines(['diff', base, '--name-only', '--diff-filter=ACMR'], cwd)
+  const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
+  return [...new Set([...changed, ...untracked])]
+}

package/scripts/lib/check-reporter.mjs

@@ -0,0 +1,27 @@
+/**
+ * Спільний репортер для check-скриптів і lint-docker.
+ *
+ * Об’єднує вивід успіхів (`pass` з `pass.mjs`) і помилок з префіксом ❌; накопичує код виходу **1**,
+ * якщо хоча б раз викликано `fail`.
+ *
+ * Використовуй `getExitCode()` у `return`, а не деструктуризацію `exitCode` — геттер «знімається» один раз.
+ */
+import { pass } from '../utils/pass.mjs'
+
+/**
+ * Створює пару `pass` / `fail` з накопиченням ненульового коду виходу.
+ * @returns {{ pass: typeof pass, fail: (msg: string) => void, getExitCode: () => number }} об’єкт з `pass`, `fail` і `getExitCode()` (0 або 1 після будь-якого `fail`)
+ */
+export function createCheckReporter() {
+  let exitCode = 0
+  return {
+    pass,
+    fail(msg) {
+      console.log(`  ❌ ${msg}`)
+      exitCode = 1
+    },
+    getExitCode() {
+      return exitCode
+    }
+  }
+}

package/scripts/lib/collect-test-files.mjs

@@ -0,0 +1,48 @@
+/**
+ * Спільна логіка для `test/no-*`-концернів, що сканують `*.test.{mjs,js}`: визначення
+ * тестового файлу й обхід дерева з `.n-rules.json`-ignore. Виносено з дублювання між
+ * `no-bun-test-import` і `no-process-chdir` (jscpd).
+ */
+import { basename, relative } from 'node:path'
+
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+import { walkDir } from '../utils/walkDir.mjs'
+
+/**
+ * Чи файл — JS-тест (`*.test.mjs` або `*.test.js`).
+ * @param {string} absPath абсолютний шлях
+ * @returns {boolean} `true` для імен з `.test.{mjs,js}` суфіксом
+ */
+export function isTestFile(absPath) {
+  const name = basename(absPath)
+  return name.endsWith('.test.mjs') || name.endsWith('.test.js')
+}
+
+/**
+ * Збирає всі `*.test.{mjs,js}` у дереві `cwd`, поважаючи `.n-rules.json`-ignore.
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @returns {Promise<string[]>} абсолютні шляхи тестових файлів
+ */
+export async function collectTestFiles(cwd) {
+  const ignorePaths = await loadCursorIgnorePaths(cwd)
+  /** @type {string[]} */
+  const testFiles = []
+  await walkDir(
+    cwd,
+    absPath => {
+      if (isTestFile(absPath)) testFiles.push(absPath)
+    },
+    ignorePaths
+  )
+  return testFiles
+}
+
+/**
+ * posix-відносний шлях файлу від `cwd` (уніфіковано для violation-message).
+ * @param {string} cwd абсолютний корінь репозиторію
+ * @param {string} absPath абсолютний шлях файлу
+ * @returns {string} posix-відносний шлях
+ */
+export function toRelPosix(cwd, absPath) {
+  return relative(cwd, absPath).split('\\').join('/')
+}

package/scripts/lib/concern-meta.mjs

@@ -0,0 +1,140 @@
+/**
+ * Парсер і нормалізатор `concern.json`. Єдине місце де читається і валідується схема concern-а.
+ * @see ../../schemas/concern.json
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * @typedef {object} LintSurface
+ * @property {'per-file'|'full'} scope область лінту: per-file чи повний прогін.
+ * @property {string[]} glob масив glob-ів (нормалізований з string|string[]); порожній якщо не задано
+ */
+
+/**
+ * @typedef {object} PolicySurface
+ * @property {'rego'|'template'} engine канонічне поле; derived з legacy `check:'template'`
+ * @property {{ single?: string, walkGlob?: string|string[], required?: boolean }} files опис файлів policy-поверхні.
+ * @property {'template'|undefined} check legacy (deprecated) — лишається для backward-compat
+ * @property {string|undefined} missingMessage повідомлення про відсутній файл (опційно).
+ */
+
+/**
+ * @typedef {'code'|'config'|'structural'} Fixability
+ */
+
+/**
+ * @typedef {object} ConcernMeta
+ * @property {string} name ім'я concern-а (= basename каталогу)
+ * @property {string} dir абсолютний шлях до каталогу concern-а
+ * @property {boolean} check чи є JS check поверхня
+ * @property {PolicySurface|undefined} policy policy-поверхня concern-а (rego/template) або undefined.
+ * @property {LintSurface|undefined} lint lint-поверхня concern-а або undefined.
+ * @property {Fixability} fixability маршрутизація fix-движка (дефолт `code`): `config`/`structural` пропускають LLM-ladder.
+ */
+
+/**
+ * Нормалізує `raw.fixability`. Невідоме/відсутнє значення → `code` (ladder-eligible дефолт).
+ * @param {unknown} rawFixability сире поле `raw.fixability`
+ * @returns {Fixability} нормалізована fixability-мітка
+ */
+function parseFixability(rawFixability) {
+  return rawFixability === 'config' || rawFixability === 'structural' ? rawFixability : 'code'
+}
+
+/**
+ * Нормалізує `raw.lint` у `LintSurface`. Повертає `null` при невалідному scope,
+ * `undefined` якщо lint-блок відсутній.
+ * @param {unknown} rawLint сирий блок `raw.lint`
+ * @returns {LintSurface|null|undefined} нормалізована lint-поверхня, `null` (невалідний scope) або `undefined` (немає блоку)
+ */
+function parseLintSurface(rawLint) {
+  if (!rawLint || typeof rawLint !== 'object') return
+  const scope = rawLint.scope
+  if (scope !== 'per-file' && scope !== 'full') return null
+  const rawGlob = rawLint.glob
+  let glob = []
+  if (Array.isArray(rawGlob)) {
+    glob = rawGlob
+  } else if (typeof rawGlob === 'string') {
+    glob = [rawGlob]
+  }
+  return { scope, glob }
+}
+
+/**
+ * Нормалізує `raw.policy` у `PolicySurface` (engine derived з legacy `check:'template'`).
+ * @param {unknown} rawPolicy сирий блок `raw.policy`
+ * @returns {PolicySurface|undefined} нормалізована policy-поверхня або `undefined` якщо блоку немає
+ */
+function parsePolicySurface(rawPolicy) {
+  if (!rawPolicy || typeof rawPolicy !== 'object') return
+  const legacyTemplate = rawPolicy.check === 'template'
+  let engine
+  if (rawPolicy.engine === 'template' || rawPolicy.engine === 'rego') {
+    engine = rawPolicy.engine
+  } else {
+    engine = legacyTemplate ? 'template' : 'rego'
+  }
+  return {
+    engine,
+    files: rawPolicy.files,
+    check: legacyTemplate ? 'template' : undefined,
+    missingMessage: typeof rawPolicy.missingMessage === 'string' ? rawPolicy.missingMessage : undefined
+  }
+}
+
+/**
+ * Читає і нормалізує `concern.json` з каталогу.
+ * Повертає `null` якщо файл відсутній або не валідний.
+ * @param {string} concernDir абсолютний шлях до підкаталогу concern-а
+ * @param {string} name ім'я concern-а (basename)
+ * @returns {Promise<ConcernMeta|null>} нормалізований meta або `null` якщо файл відсутній/невалідний.
+ */
+export async function readConcernMeta(concernDir, name) {
+  const metaPath = join(concernDir, 'concern.json')
+  if (!existsSync(metaPath)) return null
+  let raw
+  try {
+    raw = JSON.parse(await readFile(metaPath, 'utf8'))
+  } catch {
+    return null
+  }
+  if (typeof raw !== 'object' || raw === null) return null
+
+  const lint = parseLintSurface(raw.lint)
+  if (lint === null) return null
+
+  const policy = parsePolicySurface(raw.policy)
+
+  const check = raw.check === true
+
+  if (!check && !policy && !lint) return null
+
+  return { name, dir: concernDir, check, policy, lint, fixability: parseFixability(raw.fixability) }
+}
+
+/**
+ * Сканує підкаталоги `ruleDir` і повертає всі concern-и (у алфавітному порядку).
+ * Каталоги без `concern.json` ігноруються.
+ * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
+ * @returns {Promise<ConcernMeta[]>} масив concern-ів у алфавітному порядку.
+ */
+export async function listConcerns(ruleDir) {
+  const { readdir } = await import('node:fs/promises')
+  let entries
+  try {
+    entries = await readdir(ruleDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  /** @type {ConcernMeta[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const meta = await readConcernMeta(join(ruleDir, entry.name), entry.name)
+    if (meta) out.push(meta)
+  }
+  return out.toSorted((a, b) => a.name.localeCompare(b.name))
+}

package/scripts/lib/diff-added-lines.mjs

@@ -0,0 +1,86 @@
+/**
+ * Додані/змінені рядки на файл (vs HEAD) — для класифікації lint-findings на
+ * introduced (рядок у diff) vs pre-existing (поза diff), беклог #6.
+ *
+ * Парсимо `git diff --unified=0 HEAD -- <files>`: hunk-заголовок `@@ -a,b +c,d @@`
+ * дає додані рядки c..c+d-1. Untracked (нові, поза HEAD) — усі рядки introduced (маркер `ALL`).
+ */
+import { spawnSync } from 'node:child_process'
+
+/** Маркер «усі рядки файлу introduced» (новий untracked-файл). */
+export const ALL_LINES = 'ALL'
+
+/** Шлях цільового файлу у рядку `+++ b/path` (або `/dev/null`). */
+const PLUS_FILE_RE = /^\+\+\+ (?:b\/)?(.*)$/u
+/** Діапазон доданих рядків у hunk-заголовку `@@ -a,b +c,d @@`. */
+const HUNK_ADD_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/u
+
+/**
+ * Парсить вивід `git diff --unified=0` у мапу доданих рядків на файл.
+ * @param {string} diffText сирий вивід git diff
+ * @returns {Map<string, Set<number>>} файл → множина доданих рядків
+ */
+export function parseAddedLines(diffText) {
+  const byFile = new Map()
+  let current = null
+  for (const line of String(diffText).split('\n')) {
+    const fileMatch = PLUS_FILE_RE.exec(line)
+    if (fileMatch) {
+      current = fileMatch[1] === '/dev/null' ? null : fileMatch[1]
+      if (current && !byFile.has(current)) byFile.set(current, new Set())
+      continue
+    }
+    const hunk = current && HUNK_ADD_RE.exec(line)
+    if (hunk) {
+      const start = Number(hunk[1])
+      const count = hunk[2] === undefined ? 1 : Number(hunk[2])
+      for (let i = 0; i < count; i++) byFile.get(current).add(start + i)
+    }
+  }
+  return byFile
+}
+
+/**
+ * Тихий git → stdout або `''`.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {string} stdout
+ */
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return r.status === 0 ? (r.stdout ?? '') : ''
+}
+
+/**
+ * Додані рядки на файл (vs HEAD) для заданих файлів. Tracked → з diff;
+ * untracked (нові) → маркер `ALL_LINES`.
+ * @param {string[]} files відносні шляхи (від cwd)
+ * @param {string} [cwd] корінь репо
+ * @param {{ git?: (args: string[], cwd: string) => string }} [deps] ін'єкція git (тести)
+ * @returns {Map<string, Set<number> | typeof ALL_LINES>} файл → додані рядки / `ALL`
+ */
+export function addedLinesByFile(files, cwd = process.cwd(), deps = {}) {
+  if (!files || files.length === 0) return new Map()
+  const run = deps.git ?? git
+  const map = parseAddedLines(run(['diff', '--unified=0', 'HEAD', '--', ...files], cwd))
+  const untracked = run(['ls-files', '--others', '--exclude-standard', '--', ...files], cwd)
+  for (const f of untracked.split('\n')) {
+    if (!f) continue
+    map.set(f, ALL_LINES)
+  }
+  return map
+}
+
+/**
+ * Чи рядок `line` у файлі `file` — доданий (introduced).
+ * @param {Map<string, Set<number> | typeof ALL_LINES>} addedLines результат `addedLinesByFile`
+ * @param {string} file відносний шлях
+ * @param {number} line номер рядка
+ * @returns {boolean} результат
+ */
+export function isIntroducedLine(addedLines, file, line) {
+  const entry = addedLines.get(file)
+  if (entry === undefined) return false
+  if (entry === ALL_LINES) return true
+  return entry.has(line)
+}

package/scripts/lib/discover-check-rules-from-cursor.mjs

@@ -0,0 +1,40 @@
+/**
+ * Визначає список id правил для `npx \@7n/rules fix` без аргументів:
+ * зчитує базові імена `*.mdc` у `.cursor/rules/` і залишає лише ті id,
+ * для яких у пакеті є programmatic перевірка (JS-концерн або policy з target.json).
+ */
+
+/** Префікс керованих правил пакета у `.cursor/rules/`. */
+export const MANAGED_RULE_FILE_PREFIX = 'n-'
+
+/**
+ * Перетворює базове ім'я `.mdc` у id правила для `check <id>`.
+ * @param {string} mdcBasename наприклад `n-bun.mdc` або `my-rule.mdc`
+ * @returns {string} id без `.mdc`; для `n-*` — без префікса `n-`
+ */
+export function mdcBasenameToCheckId(mdcBasename) {
+  const base = mdcBasename.includes('/') ? mdcBasename.slice(mdcBasename.lastIndexOf('/') + 1) : mdcBasename
+  const withoutExt = base.endsWith('.mdc') ? base.slice(0, -'.mdc'.length) : base
+  return withoutExt.startsWith(MANAGED_RULE_FILE_PREFIX)
+    ? withoutExt.slice(MANAGED_RULE_FILE_PREFIX.length)
+    : withoutExt
+}
+
+/**
+ * Будує впорядкований список id перевірок за файлами правил на диску.
+ * @param {string[]} available id з `discoverCheckableRules` (алфавітний порядок пакета)
+ * @param {string[]} mdcBasenames відсортовані імена `*.mdc` з `.cursor/rules/`
+ * @returns {string[]} унікальні id у порядку `mdcBasenames`, лише присутні в `available`
+ */
+export function discoverCheckRulesFromCursorRules(available, mdcBasenames) {
+  const seen = new Set()
+  const ordered = []
+  for (const basename of mdcBasenames) {
+    const id = mdcBasenameToCheckId(basename)
+    if (available.includes(id) && !seen.has(id)) {
+      seen.add(id)
+      ordered.push(id)
+    }
+  }
+  return ordered
+}

package/scripts/lib/discover-checkable-rules.mjs

@@ -0,0 +1,49 @@
+/**
+ * Discovery правил для CLI `fix`/`check`. Сканує `rules/<id>/` для підкаталогів із `concern.json`.
+ * Правила без жодного concern-а (тільки `.mdc`) фільтруються.
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { listConcerns } from './concern-meta.mjs'
+
+/**
+ * @typedef {import('./concern-meta.mjs').ConcernMeta} ConcernMeta
+ */
+
+/**
+ * @typedef {object} CheckableRule
+ * @property {string} id ідентифікатор правила (ім'я каталогу `rules/<id>/`)
+ * @property {ConcernMeta[]} concerns усі concerns правила (алфавітно)
+ */
+
+/**
+ * Будує `CheckableRule` для одного каталогу правила.
+ * @param {string} ruleDir абсолютний шлях `rules/<id>/`
+ * @param {string} ruleId id правила
+ * @returns {Promise<CheckableRule>} правило з переліком його concerns
+ */
+export async function discoverOneRule(ruleDir, ruleId) {
+  const concerns = await listConcerns(ruleDir)
+  return { id: ruleId, concerns }
+}
+
+/**
+ * Сканує `rules/` і повертає правила з хоча б одним concern-ом, відсортовані за id.
+ * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
+ * @returns {Promise<CheckableRule[]>} правила з ≥1 concern-ом, відсортовані за id
+ */
+export async function discoverCheckableRules(bundledRulesDir) {
+  if (!existsSync(bundledRulesDir)) return []
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  /** @type {CheckableRule[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const ruleDir = join(bundledRulesDir, entry.name)
+    const rule = await discoverOneRule(ruleDir, entry.name)
+    if (rule.concerns.length > 0) out.push(rule)
+  }
+  return out.toSorted((a, b) => a.id.localeCompare(b.id))
+}

package/scripts/lib/docs/assert-project-root.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: assert-project-root.mjs
+resource: npm/scripts/lib/assert-project-root.mjs
+docgen:
+  crc: e3686006
+  score: 100
+---
+
+Файл перевіряє розташування поточного каталогу відносно кореня git-репозиторію. Функції надають доступ до шляху кореня репозиторію та перевірку, чи знаходиться поточний каталог саме в цьому корені. Код спирається на конфіги, визначені у `.n-rules.json`.
+
+## Поведінка
+
+gitToplevel
+Повертає абсолютний шлях до кореня git-репозиторію або null, якщо git недоступний або не повертає кореня.
+
+assertCwdIsProjectRoot
+Перевіряє, чи знаходиться поточний каталог у корені git-репозиторію. Кидає помилку, якщо каталог знаходиться всередині репозиторію, але не в корені. Пропускає перевірку, якщо git не знаходить кореня.
+
+## Публічний API
+
+- gitToplevel — повертає шлях до кореня git-репозиторію через `git rev-parse --show-toplevel`. Повертає `null`, якщо `dir` не є частиною git-репозиторію або `git` недоступний.
+- assertCwdIsProjectRoot — генерує помилку, якщо `dir` знаходиться у піддиректорії git-репозиторію. Пропускає, якщо `toplevel` відсутній (наприклад, у `git-worktree`), дозволяючи запуск.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/scripts/lib/docs/blue-oak.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: blue-oak.mjs
+resource: npm/scripts/lib/blue-oak.mjs
+docgen:
+  crc: 18c24b0c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль читає конфігурацію Blue Oak Council (`blue-oak.json`) для визначення дозволених рівнів SPDX. Він повертає множину SPDX-ідентифікаторів рівнів Model, Gold, Silver та Bronze. Модуль також генерує правила заборони ліцензій у форматі TOML та перевіряє відповідність будь-якого SPDX-ідентифікатора цьому списку.
+
+## Поведінка
+
+getBronzeAndAbove повертає множину SPDX-ідентифікаторів рівнів Model+Gold+Silver+Bronze, які беруться з конфігурації blue-oak.json.
+generateDenyTomlLicenses генерує TOML-рядок для `deny.toml` (cargo-deny), дозволяючи лише SPDX-ідентифікатори, що знаходяться у множині Blue Oak Bronze+.
+isSpdxAllowed перевіряє, чи відповідає наданий SPDX-вираз дозволеним ідентифікаторам, враховуючи логічні оператори `AND` та `OR`.
+
+## Публічний API
+
+getBronzeAndAbove — Визначає набір SPDX-ідентифікаторів (Model, Gold, Silver, Bronze), які вважаються безпечними для комерційного використання.
+generateDenyTomlLicenses — Створює конфігураційний рядок TOML для файлу `deny.toml`, що забороняє використання ліцензій нижче рівня Blue Oak Bronze.
+isSpdxAllowed — Визначає, чи відповідає заданий SPDX-ідентифікатор дозволеному списку Blue Oak Bronze+ згідно з логікою (одиночний ID, `A OR B`, `A AND B`).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).