@nitra/cursor 12.6.1 → 12.7.0

package/rules/js-lint/js/tooling.mjs

@@ -1,11 +1,7 @@
 /** @see ./docs/tooling.md */
-import { existsSync } from 'node:fs'
-import { copyFile, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
-
 /** Шлях до канонічного oxlint JSON у цьому пакеті (для перевірки та тестів). */
 export const OXLINT_CANONICAL_JSON_PATH = join(
   dirname(fileURLToPath(import.meta.url)),
@@ -22,15 +18,13 @@ export const KNIP_CANONICAL_JSON_PATH = join(
   'knip-canonical.json'
 )
 
-const NON_DIGITS_RE = /\D+/u
-
 // Канонічний рядок `lint-js`-скрипта і мінімальна версія `@nitra/eslint-config` —
 // у rego (`npm/policy/js_lint/package_json/`). JS-копії (`CANONICAL_LINT_JS`,
 // `isCanonicalLintJs`, `nitraEslintConfigMeetsMinVersion`) видалено, щоб не
 // було двох джерел істини й ризику дрифту.
 
 /**
- * Рекурсивне порівняння фрагментів канону oxlint (масиви — порядок як у каноні; об’єкти — той самий набір ключів і вкладеність).
+ * Рекурсивне порівняння фрагментів канону oxlint (масиви — порядок як у каноні; об'єкти — той самий набір ключів і вкладеність).
  * @param {unknown} actual значення з `.oxlintrc.json`
  * @param {unknown} expected значення з канону
  * @returns {boolean} true, якщо значення збігаються за правилами канону
@@ -154,261 +148,3 @@ export function verifyOxlintRcAgainstCanonical(cfg, canonical) {
 
   return { ok: failures.length === 0, failures }
 }
-
-/**
- * Перевіряє ESLint flat config файл.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkEslintConfig(passFn, failFn, cwd) {
-  let eslintPath
-  if (existsSync(join(cwd, 'eslint.config.js'))) {
-    eslintPath = 'eslint.config.js'
-    passFn('eslint.config.js існує')
-  } else if (existsSync(join(cwd, 'eslint.config.mjs'))) {
-    eslintPath = 'eslint.config.mjs'
-    passFn('eslint.config.mjs існує')
-  } else {
-    failFn('Відсутній eslint.config.js або eslint.config.mjs — flat config з getConfig (js-lint.mdc)')
-    return
-  }
-  const eslintRaw = await readFile(join(cwd, eslintPath), 'utf8')
-  const checks = [
-    {
-      needle: 'getConfig',
-      ok: `${eslintPath}: містить getConfig`,
-      err: `${eslintPath}: потрібен виклик getConfig (js-lint.mdc)`
-    },
-    {
-      needle: '@nitra/eslint-config',
-      ok: `${eslintPath}: імпорт @nitra/eslint-config`,
-      err: `${eslintPath}: імпортуй getConfig з @nitra/eslint-config`
-    },
-    {
-      needle: '**/auto-imports.d.ts',
-      ok: `${eslintPath}: ignores містить **/auto-imports.d.ts`,
-      err: `${eslintPath}: додай у ignores запис **/auto-imports.d.ts (js-lint.mdc)`
-    }
-  ]
-  for (const { needle, ok, err } of checks) {
-    if (eslintRaw.includes(needle)) {
-      passFn(ok)
-    } else {
-      failFn(err)
-    }
-  }
-}
-
-// Перевірки `prettier` / `@nitra/prettier-config` у залежностях (text.mdc) і
-// `@nitra/eslint-config ≥ 3.10.0` тепер у Rego: відповідно
-// `npm/policy/text/package_json/` і `npm/policy/js_lint/package_json/`. Тут
-// лишилася лише workspace-ітерація для `type: "module"` і engines, бо js_lint
-// Rego запускається лише на кореневому `package.json`.
-
-/**
- * Перевіряє, що package.json має `"type": "module"`.
- * @param {string} label шлях або назва пакета для повідомлень
- * @param {{ type?: string }} pkg parsed package.json
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- */
-function checkPackageJsonTypeModule(label, pkg, passFn, failFn) {
-  if (pkg.type === 'module') {
-    passFn(`${label}: "type": "module"`)
-  } else {
-    failFn(`${label}: має містити "type": "module" (js-lint.mdc)`)
-  }
-}
-
-/**
- * `"type": "module"`, `engines.node >= 24` і `engines.bun >= 1.3` у кожному workspace `package.json`.
- * @param {unknown[]} workspaces поле workspaces з package.json
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkWorkspacePackages(workspaces, passFn, failFn, cwd) {
-  for (const ws of workspaces) {
-    const wsPkgRel = `${ws}/package.json`
-    const wsPkgAbs = join(cwd, wsPkgRel)
-    if (existsSync(wsPkgAbs)) {
-      const wsPkg = JSON.parse(await readFile(wsPkgAbs, 'utf8'))
-      checkPackageJsonTypeModule(wsPkgRel, wsPkg, passFn, failFn)
-      checkEnginesNode(wsPkgRel, wsPkg, passFn, failFn)
-      checkEnginesBun(wsPkgRel, wsPkg, passFn, failFn)
-    }
-  }
-}
-
-/**
- * engines.node >= 24.
- * @param {string} label шлях або назва пакета для повідомлень
- * @param {{ engines?: { node?: string } }} pkg розпарсений package.json
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- */
-function checkEnginesNode(label, pkg, passFn, failFn) {
-  const nodeEngine = pkg.engines?.node
-  if (nodeEngine) {
-    const firstNumeric = String(nodeEngine).split(NON_DIGITS_RE).find(Boolean)
-    if (firstNumeric && Number(firstNumeric) >= 24) {
-      passFn(`${label}: engines.node "${nodeEngine}"`)
-    } else {
-      failFn(`${label}: engines.node "${nodeEngine}" — має бути >=24`)
-    }
-  } else {
-    failFn(`${label} не містить engines.node — додай: "engines": { "node": ">=24" }`)
-  }
-}
-
-/**
- * engines.bun >= 1.3.
- * @param {string} label шлях або назва пакета для повідомлень
- * @param {{ engines?: { bun?: string } }} pkg розпарсений package.json
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- */
-function checkEnginesBun(label, pkg, passFn, failFn) {
-  const bunEngine = pkg.engines?.bun
-  if (bunEngine) {
-    const [major, minor] = String(bunEngine).split(NON_DIGITS_RE).filter(Boolean).map(Number)
-    if (Number.isFinite(major) && Number.isFinite(minor) && (major > 1 || (major === 1 && minor >= 3))) {
-      passFn(`${label}: engines.bun "${bunEngine}"`)
-    } else {
-      failFn(`${label}: engines.bun "${bunEngine}" — має бути >=1.3`)
-    }
-  } else {
-    failFn(`${label} не містить engines.bun — додай: "engines": { "bun": ">=1.3" }`)
-  }
-}
-
-/**
- * Workspace-ітерація: для кожного workspace `package.json` перевіряємо
- * `type: "module"` і `engines.{node,bun}`. Кореневий `package.json` ці поля
- * валідує `npm/policy/js_lint/package_json/`; lint-js скрипт і `@nitra/eslint-config`
- * — теж у Rego.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkPackageJsonJsLint(passFn, failFn, cwd) {
-  const pkgPath = join(cwd, 'package.json')
-  if (!existsSync(pkgPath)) return
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-  const workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : []
-  await checkWorkspacePackages(workspaces, passFn, failFn, cwd)
-}
-
-/**
- * Перевіряє .oxlintrc.json.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkOxlintRc(passFn, failFn, cwd) {
-  const oxPath = join(cwd, '.oxlintrc.json')
-  if (!existsSync(oxPath)) {
-    failFn('.oxlintrc.json не існує — додай конфіг oxlint (js-lint.mdc)')
-    return
-  }
-  let oxCfg
-  try {
-    oxCfg = JSON.parse(await readFile(oxPath, 'utf8'))
-  } catch {
-    failFn('.oxlintrc.json не є валідним JSON')
-    return
-  }
-  passFn('.oxlintrc.json існує')
-  let canonical
-  try {
-    canonical = JSON.parse(await readFile(OXLINT_CANONICAL_JSON_PATH, 'utf8'))
-  } catch {
-    failFn('внутрішня помилка: не вдалося прочитати канон oxlint з пакета @nitra/cursor')
-    return
-  }
-  const oxV = verifyOxlintRcAgainstCanonical(oxCfg, canonical)
-  if (oxV.ok) {
-    passFn('.oxlintrc.json збігається з каноном oxlint (@nitra/cursor)')
-  } else {
-    for (const msg of oxV.failures) {
-      failFn(msg)
-    }
-  }
-}
-
-/**
- * FS-existence для `lint-js.yml` + cross-file перевірка, що `lint.yml` (якщо існує)
- * не дублює лінт JS-кроки. Структуру `lint-js.yml` (`actions/checkout@v6`,
- * `persist-credentials: false`, `setup-bun-deps`, `bunx oxlint/eslint/jscpd .`,
- * заборона `--fix` у CI) валідує `npm/policy/js_lint/lint_js_yml/`.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkLintJsWorkflows(passFn, failFn, cwd) {
-  if (existsSync(join(cwd, '.github/workflows/lint-js.yml'))) {
-    passFn('.github/workflows/lint-js.yml є (структуру перевіряє npx @nitra/cursor fix → js_lint.lint_js_yml)')
-  } else {
-    failFn('.github/workflows/lint-js.yml не існує — створи його (див. rules/js-lint/fix.mjs / js-lint.mdc)')
-  }
-
-  const lintYmlPath = join(cwd, '.github/workflows/lint.yml')
-  if (existsSync(lintYmlPath)) {
-    const lintYml = await readFile(lintYmlPath, 'utf8')
-    if (lintYml.includes('bunx oxlint') && lintYml.includes('bunx eslint') && lintYml.includes('jscpd')) {
-      failFn('.github/workflows/lint.yml дублює кроки lint-js.yml — залиш один workflow на лінт JS (js-lint.mdc)')
-    } else {
-      passFn('.github/workflows/lint.yml не дублює oxlint/eslint/jscpd з lint-js.yml')
-    }
-  }
-}
-
-/**
- * Перевіряє наявність `knip.json` у корені проєкту. Якщо файл відсутній —
- * копіює канонічний `knip-canonical.json` з пакета `@nitra/cursor` як стартовий
- * baseline; зміст подальших модифікацій локально не валідується (`entry` /
- * `project` / `ignore` / `ignoreDependencies` / `ignoreBinaries` дозволені
- * будь-які; це side effect — описано у js-lint.mdc).
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkKnipConfig(passFn, failFn, cwd) {
-  const knipPath = join(cwd, 'knip.json')
-  if (existsSync(knipPath)) {
-    passFn('knip.json існує')
-    return
-  }
-  if (!existsSync(KNIP_CANONICAL_JSON_PATH)) {
-    failFn(
-      `knip.json відсутній, і канонічний шаблон у пакеті не знайдено (${KNIP_CANONICAL_JSON_PATH}) — ` +
-        'перевстанови @nitra/cursor'
-    )
-    return
-  }
-  await copyFile(KNIP_CANONICAL_JSON_PATH, knipPath)
-  passFn('knip.json створено з канонічного npm/rules/js-lint/js/data/tooling/knip-canonical.json (js-lint.mdc)')
-}
-
-/**
- * Перевіряє відповідність проєкту правилам js-lint.mdc
- * @param {string} [cwd] корінь репозиторію
- * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
- */
-export async function check(cwd = process.cwd()) {
-  const reporter = createCheckReporter()
-  const { pass, fail } = reporter
-
-  await checkEslintConfig(pass, fail, cwd)
-  await checkPackageJsonJsLint(pass, fail, cwd)
-  await checkOxlintRc(pass, fail, cwd)
-  await checkLintJsWorkflows(pass, fail, cwd)
-  await checkKnipConfig(pass, fail, cwd)
-
-  for (const dup of ['.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.yml']) {
-    if (existsSync(join(cwd, dup))) fail(`Знайдено застарілий конфіг ESLint: ${dup} — видали, використовуй flat config`)
-  }
-
-  return reporter.getExitCode()
-}

package/rules/js-lint/{js/lint.mjs → main.mjs}

@@ -1,8 +1,20 @@
 /** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
-import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'
-import { classifyFindings, parseEslint, parseOxlint, renderFindings } from './lint-findings.mjs'
+import { addedLinesByFile } from '../../scripts/lib/diff-added-lines.mjs'
+import { classifyFindings, parseEslint, parseOxlint, renderFindings } from './js/lint-findings.mjs'
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (oxlint+eslint), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 const JS_EXT_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx|vue)$/u
 
@@ -119,3 +131,8 @@ export function lint(files, cwd = process.cwd(), opts = {}) {
   if (js.length === 0) return Promise.resolve(0)
   return Promise.resolve(lintChangedClassified(js, cwd, readOnly))
 }
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/js-lint/main.mjs — повний еквівалент `npx @nitra/cursor check js-lint`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/js-lint-ci/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/js-lint-ci/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/js-lint-ci/docs/main.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/js-lint-ci/main.mjs
+docgen:
+  crc: 59cd2fd3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль надає інструменти для глибокого аналізу коду. Функція `run` виконує перевірку коду відповідно до заданого контексту прогону. Функція `lint` порівнює файли репозиторію для виявлення дублікатів та неіспользумого коду.
+
+## Поведінка
+
+run виконує перевірку на основі контексту прогону.
+lint виконує крос-файловий аналіз репозиторію на дублікати та мертвий код.
+
+## Публічний API
+
+run — точка входу для виконання правила, що включає перевірку логіки застосування (JS-занепокложення $\to$ політика $\to$ посилання MDC) та аналіз коду (jscpd + knip) по всьому репозиторію.
+lint — аналіз коду по всьому репозиторію на наявність дублікатів (jscpd) та мертвого коду (knip).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js-lint-ci/main.mjs

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process'
+
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` — lint-поверхня (jscpd + knip, крос-файловий аналіз).
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+/**
+ * lint-поверхня: jscpd (дублікати) + knip (мертвий код) по всьому репо.
+ * @param {string[] | undefined} _files ігнорується (крос-файловий аналіз)
+ * @param {string} [cwd] корінь репо
+ * @returns {Promise<number>} 0 — OK, ≠0 — порушення
+ */
+export function lint(_files, cwd = process.cwd()) {
+  const jscpd = spawnSync('bunx', ['jscpd', '.'], { cwd, stdio: 'inherit' })
+  const jc = typeof jscpd.status === 'number' ? jscpd.status : 1
+  if (jc !== 0) return Promise.resolve(jc)
+  const knip = spawnSync('bunx', ['knip', '--no-config-hints'], { cwd, stdio: 'inherit' })
+  return Promise.resolve(typeof knip.status === 'number' ? knip.status : 1)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/js-mssql/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/js-mssql/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/js-mssql/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/js-mssql/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль валідує відповідність даних, використовуючи логіку, визначену у meta.json. Він перевіряє відповідність конфігурацій та білих списків. Публічна функція run ініціює процес. Модуль є Read-only, тобто не виконує запис у файлову систему чи базу даних.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання `run` застосовує логіку, визначену в `meta.json`, включаючи конфігурації.
+3. Виконання `run` виконує перевірку, яка включає логіку, пов'язану з JS-зацікавленостями та політиками.
+4. Якщо скрипт запускається як окрема програма (CLI), виконується повний цикл виконання правила.
+5. Цей цикл включає завантаження конфігурацій, застосування білих списків та підбиття підсумків.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки щодо JS-зацікавленостей, політики та посилань MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/js-mssql/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/js-run/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/js-run/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/js-run/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/js-run/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує визначене правило. Він ініціює стандартний запуск правила, використовуючи директорію правила та контекст прогону. При запуску як окрема програма, він завантажує конфігурації, на які спирається код, зокрема `meta.json`. Функціональність є read-only, і дані кешуються у межах прогону. Фінальний результат визначається викликом публічної функції `run`.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Функція `run` ініціює стандартне правило, використовуючи директорію цього правила та наданий контекст прогону.
+3. Якщо код виконується як окрема програма (CLI), ініціюється повний запуск правила.
+4. Повний запуск включає завантаження конфігурацій (наприклад, `meta.json`), застосування білих списків та підсумок.
+5. Результат виконання визначає код виходу процесу.
+
+## Публічний API
+
+run — виконує основну перевірку правила, застосовуючи вимоги JS-контексту, політики та посилання MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/js-run/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/k8s/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/k8s/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/k8s/docs/main.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/k8s/main.mjs
+docgen:
+  crc: 1caca447
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 85
+---
+
+## Огляд
+
+Модуль знаходить унікальні корені каталогів із іменем `k8s` за шляхами файлів `*.yaml` у репозиторії. Якщо таких файлів немає, виконання завершується з кодом 0 без виклику зовнішніх CLI. Для знайдених коренів виконується перевірка YAML-маніфестів. `kubeconform` перевіряє маніфести проти OpenAPI-схем Kubernetes (https://github.com/yannh/kubeconform#readme), використовуючи версію, узгоджену з лінією релізу. `kubescape` сканує маніфести на misconfiguration та відповідність стандартам (NSA, MITRE, CIS), використовуючи конфігураційний файл `.kubescape-exceptions.json`. Орієнтир цільового кластера для `kubescape` визначається за тією ж лінією релізу, що й для `kubeconform`. Обидві утиліти (`kubeconform` та `kubescape`) повинні бути доступні в системному PATH.
+
+## Поведінка
+
+run виконує стандартну перевірку правила.
+pathHasK8sSegment визначає, чи містить шлях сегмент директорії `k8s` відносно кореня репозиторію.
+k8sRootFromFile знаходить абсолютний шлях до каталогу `…/k8s`, що містить маніфест, виходячи з абсолютного шляху до YAML-файлу.
+findK8sRoots знаходить унікальні абсолютні шляхи до каталогів `k8s` за наявності файлів `*.yaml`, ігноруючи шляхи, що починаються з `.github/`.
+buildKubescapeExceptionsArgs будує аргументи для `kubescape`, якщо існує файл `.kubescape-exceptions.json` у корені репозиторію.
+findKustomizationDirs знаходить абсолютні шляхи до каталогів, що містять білдабельний `kustomization.yaml` у межах каталогу `…/k8s`, виключаючи компоненти (`kind: Component`).
+runLintK8s виконує повний цикл перевірки Kubernetes-маніфестів за допомогою `kubeconform` та `kubescape`.
+lint делегує виконання повного циклу перевірки Kubernetes-маніфестів функції `runLintK8s`.
+
+## Публічний API
+
+run — виконує перевірку конфігурацій (applies → JS-concerns → policy → mdc-refs) та лінтинг (kubeconform/kubescape).
+pathHasK8sSegment — визначає, чи містить шлях сегмент директорії `k8s`.
+k8sRootFromFile — знаходить каталог `…/k8s`, що містить маніфест, рухаючись від файлу вгору.
+findK8sRoots — збирає список унікальних коренів `k8s`, якщо в поточному каталозі є файли `*.yaml`.
+buildKubescapeExceptionsArgs — створює аргументи `--exceptions <file>` для kubescape, якщо існує `.kubescape-exceptions.json` у корені проєкту.
+findKustomizationDirs — знаходить каталоги, які є точками входу Kustomize (містять `kustomization.yaml` з `kind: Kustomization`).
+runLintK8s — виконує публічну CLI-операцію лінтингу конфігурацій, використовуючи механізм блокування та дедуплікації за станом git-дерева.
+lint — слугує оркестратором, який делегує виконання лінтингу конфігурацій (`n-cursor lint k8s`) функції `runLintK8s`.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.github`, `.git`.

package/rules/k8s/js/docs/index.md

@@ -0,0 +1,12 @@
+---
+type: Directory Index
+title: npm/rules/k8s/js
+resource: npm/rules/k8s/js/
+---
+
+# npm/rules/k8s/js
+
+| Файл | Тип |
+|---|---|
+| [lint.mjs](lint.md) | JS Module |
+| [manifests](manifests.md) | Source File |

package/rules/k8s/{lint/lint.mjs → main.mjs}

@@ -2,14 +2,14 @@
  * Запуск kubeconform та kubescape для каталогів `…/k8s`, де є YAML-маніфести (див. k8s.mdc).
  *
  * Знаходить унікальні корені каталогів із іменем `k8s` за шляхами файлів **`*.yaml`**
- * (той самий принцип сегмента `k8s`, що й у rules/k8s/fix.mjs; розширення **`.yml`** під `k8s` не використовується). Якщо таких файлів немає — вихід 0
+ * (той самий принцип сегмента `k8s`, що й у rules/k8s/check.mjs; розширення **`.yml`** під `k8s` не використовується). Якщо таких файлів немає — вихід 0
  * без виклику зовнішніх CLI.
  *
  * kubeconform перевіряє маніфести проти OpenAPI-схем Kubernetes; kubescape — сканування на
  * misconfiguration / compliance (NSA, MITRE, CIS тощо). Обидві утиліти очікуються в PATH
  * (локально: Homebrew, релізи GitHub; у CI — крок установки з k8s.mdc).
  *
- * Версія `-kubernetes-version` для kubeconform узгоджена з PIN yannh у rules/k8s/fix.mjs / k8s.mdc.
+ * Версія `-kubernetes-version` для kubeconform узгоджена з PIN yannh у rules/k8s/check.mjs / k8s.mdc.
  * Kubescape не має аналога цього прапорця; орієнтир цільового кластера — та сама лінія релізу (див. k8s.mdc).
  *
  * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
@@ -23,12 +23,24 @@ import { basename, dirname, join, relative } from 'node:path'
 
 import { parse } from 'yaml'
 
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
-import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { walkDir } from '../../../scripts/utils/walkDir.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import { isRunAsCli } from '../../scripts/cli-entry.mjs'
+import { ensureTool } from '../../scripts/lib/ensure-tool.mjs'
+import { loadCursorIgnorePaths } from '../../scripts/lib/load-cursor-config.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { walkDir } from '../../scripts/utils/walkDir.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (kubeconform/kubescape), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /** Per-project kubescape exceptions file; підмішується через --exceptions, якщо існує в корені. */
 const KUBESCAPE_EXCEPTIONS_FILE = '.kubescape-exceptions.json'
@@ -342,11 +354,21 @@ async function runLintK8sSteps() {
 
 /**
  * Публічна CLI-форма: серіалізує через `withLock('lint-k8s')` + дедуп за станом git-дерева.
- * Експортовано як `runLintK8s` — використовується з `bin/n-cursor.js` як підкоманда `lint-k8s`.
+ * Експортовано як `runLintK8s` — викликається через `n-cursor lint k8s` (оркестраторний адаптер `lint()` делегує сюди); окремої bin-підкоманди `lint-k8s` немає.
  * @returns {Promise<number>} код виходу
  */
 export const runLintK8s = () => runStandardLint(import.meta.dirname, runLintK8sSteps)
 
+/**
+ * Оркестраторний адаптер `n-cursor lint k8s`: делегує у `runLintK8s`.
+ * @param {string[] | undefined} _files ігнорується (whole-repo обхід `.../k8s`)
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files) {
+  return runLintK8s()
+}
+
 if (isRunAsCli(import.meta.url)) {
-  process.exitCode = await runLintK8s()
+  // Standalone: bun rules/k8s/main.mjs — повний еквівалент `npx @nitra/cursor check k8s`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
 }

package/rules/nginx-default-tpl/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/nginx-default-tpl/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |