@nitra/cursor 12.3.3 → 12.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.4.0] - 2026-06-21
+
+### Changed
+
+- Уніфіковано selection linter-фази: unscoped n-cursor lint бере правила з .n-cursor.json, а meta.json#lint лишається тільки scope-класифікацією.
+
 ## [12.3.3] - 2026-06-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.3.3",
+  "version": "12.4.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/bun/bun.mdc

@@ -68,8 +68,8 @@ FROM oven/bun:alpine AS build-env
 
 Лінт запускається через CLI **`n-cursor`**, **не** через `package.json`-скрипти:
 
-- **`n-cursor lint --full`** — весь репо: усі правила (per-file лінтери + конформність) + `oxfmt` у кінці (fix-режим);
-- **`n-cursor lint`** — дельта vs origin (per-file лінтери лише змінених файлів);
+- **`n-cursor lint --full`** — весь репо: активні у `.n-cursor.json` правила (per-file + full лінтери за `meta.json#lint` scope, конформність) + `oxfmt` у кінці (fix-режим);
+- **`n-cursor lint`** — дельта vs origin (активні у `.n-cursor.json` per-file лінтери лише змінених файлів);
 - **`n-cursor lint <rule…>`** — конкретні правила (лінтер + конформність), напр. **`n-cursor lint ga`**.
 
 У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI `n-cursor`. У CI кожен workflow викликає **`n-cursor lint <rule> --read-only`** напряму (без обгорток).

package/rules/lint/js/docs/orchestrate.md

@@ -11,12 +11,12 @@ docgen:
 
 ## Огляд
 
-Модуль відповідає за визначення та виконання процесу лінтування коду. Функція `selectLintRules` вибирає та сортує ідентифікатори правил лінтування на основі конфігурацій, визначених у meta.json. Функція `runLint` запускає перевірку обраних правил для змінених або всіх файлів репозиторію.
+Модуль відповідає за визначення та виконання процесу лінтування коду. Unscoped linter-фаза бере активні правила з `.n-cursor.json`, а `meta.json#lint` використовує лише як класифікацію scope (`per-file` або `full`). Функція `runLint` запускає перевірку обраних правил для змінених або всіх файлів репозиторію.
 
 ## Поведінка
 
-selectLintRules вибирає і сортує ідентифікатори правил для лінтування на основі їхніх конфігурацій, включаючи можливість включення правил, що застосовуються до всього репозиторію.
-runLint запускає процес лінтування, виконуючи перевірку правил для змінених файлів або для всього репозиторію, залежно від наданих опцій, і може виконувати форматування.
+selectLintRules вибирає і сортує ідентифікатори правил для лінтування з уже активованого списку `.n-cursor.json`, включаючи можливість включення правил, що застосовуються до всього репозиторію.
+runLint запускає процес лінтування, виконуючи перевірку активних правил для змінених файлів або для всього репозиторію, залежно від наданих опцій, і може виконувати форматування. Scoped режим `lint <rule…>` запускає названі правила напряму та не потребує `.n-cursor.json` для linter-фази.
 
 ## Публічний API
 

package/rules/lint/js/orchestrate.mjs

@@ -8,6 +8,7 @@ import { spawnSync } from 'node:child_process'
 import { parseRuleLintSpec, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
 import { collectChangedFilesSince, resolveChangedBase } from '../../../scripts/lib/changed-files.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { isRuleEnabled, readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
 
 // Цей файл: npm/rules/lint/js/orchestrate.mjs → PACKAGE_ROOT = npm (чотири dirname угору).
 const PACKAGE_ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
@@ -42,17 +43,33 @@ async function runConformance(cwd, readOnly, log, filter = []) {
  * Вибирає id правил для контексту, алфавітно.
  * @param {Record<string, {lint?: unknown}>} metaById мапа id → meta-обʼєкт
  * @param {boolean} full `false` → лише `per-file` правила; `true` → усі (`per-file` ∪ `full`)
+ * @param {string[]} enabledRuleIds активні rule-id з `.n-cursor.json`
  * @returns {string[]} відсортовані id
  */
-export function selectLintRules(metaById, full) {
+export function selectLintRules(metaById, full, enabledRuleIds) {
+  const enabled = new Set(enabledRuleIds)
   const out = []
   for (const [id, raw] of Object.entries(metaById)) {
+    if (!enabled.has(id)) continue
     const scope = parseRuleLintSpec(raw?.lint)
     if (scope === 'per-file' || (full && scope === 'full')) out.push(id)
   }
   return out.toSorted((a, b) => a.localeCompare(b))
 }
 
+/**
+ * Активні правила для unscoped linter-фази. `.n-cursor.json` — єдине джерело
+ * whitelist/disable, `meta.json#lint` нижче використовується лише як scope (`per-file`/`full`).
+ * @param {Record<string, unknown>} metaById доступні bundled правила
+ * @param {string} cwd корінь
+ * @returns {Promise<string[]>} активні rule-id з конфіга, що існують у пакеті
+ */
+async function readEnabledLintRuleIds(metaById, cwd) {
+  const config = await readNCursorConfigLite(cwd)
+  if (!config.exists) return []
+  return Object.keys(metaById).filter(id => isRuleEnabled(config, id))
+}
+
 /**
  * Зчитує meta всіх правил пакета.
  * @param {string} rulesDir каталог rules
@@ -130,7 +147,7 @@ async function runFullConformancePhase(cwd, readOnly, log) {
  * @param {(s: string) => void} log логер
  * @returns {Promise<number>} код виходу oxfmt (0 — OK або пропущено)
  */
-async function runFormat(cwd, log) {
+function runFormat(cwd, log) {
   const oxfmt = resolveCmd('oxfmt')
   if (!oxfmt) {
     log('ℹ️  lint: oxfmt недоступний у PATH — формат-крок пропущено.\n')
@@ -201,7 +218,8 @@ export async function runLint(opts = {}) {
   }
 
   const metaById = readAllMeta(rulesDir)
-  const ids = selectLintRules(metaById, full)
+  const enabledRuleIds = await readEnabledLintRuleIds(metaById, cwd)
+  const ids = selectLintRules(metaById, full, enabledRuleIds)
   const perFile = await runPerFileRules(ids, { rulesDir, changed, cwd, readOnly, metaById, log })
   if (perFile.stop) return perFile.code
   let worst = perFile.code
@@ -219,7 +237,7 @@ export async function runLint(opts = {}) {
   // Формат-крок (oxfmt): fix-режим — завжди (будь-який scope); read-only пропускаємо (нуль
   // мутацій). Кастомний rulesDir (юніт-тести) — реальний пакет недоступний, тож пропускаємо.
   if (!readOnly && opts.rulesDir === undefined) {
-    const fmtCode = await runFormat(cwd, log)
+    const fmtCode = runFormat(cwd, log)
     if (fmtCode !== 0) worst = fmtCode
   }
   return worst

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

@@ -8,4 +8,5 @@ resource: npm/rules/php/js/
 
 | Файл | Тип |
 |---|---|
+| [lint.mjs](lint.md) | JS Module |
 | [tooling.mjs](tooling.md) | JS Module |

package/rules/php/js/docs/lint.md

@@ -0,0 +1,20 @@
+---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/php/js/lint.mjs
+docgen:
+  crc: 7de6b473
+  score: 100
+---
+
+Оркестраторний адаптер правила `php` для `n-cursor lint`. Делегує лінтер-фазу наявній функції `run` із `../lint/lint.mjs` (composer audit, php-cs-fixer у `--dry-run`, phpstan/psalm). Режиму на рівні окремих файлів немає — composer-інструменти працюють по всьому проєкту, тож параметр `files` ігнорується. Інструменти read-only (`--dry-run`/`analyse`), тож мутацій робочого дерева немає.
+
+## Поведінка
+
+1. Викликає `run` — лінтер-фаза php по всьому проєкту.
+2. Повертає код виходу інструменту.
+
+## Гарантії поведінки
+
+- Read-only: інструменти не мутують робоче дерево.
+- Не звертається до мережі напряму (composer-кроки можуть, але це поведінка делегата, не цього модуля).

package/rules/php/js/lint.mjs

@@ -0,0 +1,13 @@
+/** @see ./docs/lint.md */
+import { run } from '../lint/lint.mjs'
+
+/**
+ * Оркестраторний адаптер `n-cursor lint php` (лінтер-фаза): composer audit + php-cs-fixer
+ * (`--dry-run`) + phpstan/psalm через `run` (read-only — мутацій немає, тож `opts` ігнорується).
+ * Структурні php.mdc-перевірки — у конформність-фазі. Без composer-інструментів крок — no-op.
+ * @param {string[] | undefined} _files ігнорується (whole-repo обхід)
+ * @returns {number} exit code
+ */
+export function lint(_files) {
+  return run()
+}

package/rules/php/php.mdc

@@ -63,9 +63,7 @@ composer audit
 
 ## lint-php
 
-`composer`-інструмененти не мають єдиного CLI, який сам обходить репозиторій, тому `lint-php` зручно делегувати у JS-скрипт-обгортку (як `lint-docker`, `lint-k8s`).
-
-- Канон `package.json#scripts.lint-php` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
+`composer`-інструмененти не мають єдиного CLI, який сам обходить репозиторій, тому php-лінт делегується у JS-скрипт-обгортку. Запуск — через **`n-cursor lint php`** (CI — `--read-only`); окремого `package.json`-скрипта немає.
 
 Скрипт `run-php.mjs`:
 

package/rules/php/policy/lint_php_yml/template/lint-php.yml.snippet.yml

@@ -44,4 +44,4 @@ jobs:
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Lint PHP
-        run: bun run lint-php
+        run: n-cursor lint php --read-only

package/rules/python/policy/lint_python_yml/template/lint-python.yml.snippet.yml

@@ -38,4 +38,4 @@ jobs:
         run: uv sync --frozen
 
       - name: Lint Python
-        run: bun run lint-python
+        run: n-cursor lint python --read-only

package/rules/python/python.mdc

@@ -27,9 +27,7 @@ Python-проєкти ведуться **виключно** на [uv](https://do
 
 ## lint-python
 
-Інструменти uv-екосистеми не мають єдиного CLI, що сам обходить репозиторій, тому `lint-python` делегується у JS-скрипт-обгортку (як `lint-php`, `lint-docker`).
-
-- Канон `package.json#scripts.lint-python` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
+Інструменти uv-екосистеми не мають єдиного CLI, що сам обходить репозиторій, тому python-лінт делегується у JS-скрипт-обгортку. Запуск — через **`n-cursor lint python`** (CI — `--read-only`); окремого `package.json`-скрипта немає.
 
 Скрипт `rules/python/lint/lint.mjs`:
 

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

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

package/rules/rust/js/docs/lint.md

@@ -0,0 +1,21 @@
+---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/rust/js/lint.mjs
+docgen:
+  crc: 5d7c4123
+  score: 100
+---
+
+Оркестраторний адаптер правила `rust` для `n-cursor lint`: rustfmt + clippy через `cargo`. Запускається на `n-cursor lint rust`. За відсутності `Cargo.toml` у корені — no-op (вихід 0). `cargo`/`rustfmt`/`clippy` резолвляться з PATH (Rust toolchain через rustup), не з npm-залежностей; якщо `cargo` відсутній за наявного `Cargo.toml` — помилка.
+
+## Поведінка
+
+1. `readOnly` (CI): `cargo fmt --all -- --check` + `cargo clippy --all-targets --all-features -- -D warnings` — детект без мутацій.
+2. fix-режим: `cargo fmt --all` + `cargo clippy --fix` + фінальний `cargo clippy … -D warnings`.
+3. Перший ненульовий cargo-крок спиняє ланцюг і повертає його код.
+
+## Гарантії поведінки
+
+- Read-only за наявності `readOnly`: cargo не мутує робоче дерево (`--check`, без `--fix`).
+- Не звертається до мережі напряму (cargo-кроки можуть тягнути crates, але це поведінка тулчейну).

package/rules/rust/js/lint.mjs

@@ -0,0 +1,67 @@
+/** @see ./docs/lint.md */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+
+/**
+ * Запускає cargo-крок і репортить результат.
+ * @param {string} label назва кроку
+ * @param {string} cargo абсолютний шлях до `cargo`
+ * @param {string[]} args аргументи
+ * @param {(m: string) => void} pass callback pass
+ * @param {(m: string) => void} fail callback fail
+ * @returns {boolean} true якщо крок успішний
+ */
+function runCargo(label, cargo, args, pass, fail) {
+  const r = spawnSync(cargo, args, { stdio: 'inherit', shell: false })
+  if (r.status === 0) {
+    pass(`lint-rust: ${label} — OK`)
+    return true
+  }
+  const code = typeof r.status === 'number' ? r.status : 1
+  fail(`lint-rust: ${label} — помилка (код ${code}, rust.mdc)`)
+  return false
+}
+
+/**
+ * Оркестраторний адаптер `n-cursor lint rust`: rustfmt + clippy через cargo. Без `Cargo.toml` —
+ * no-op (0). `cargo`/`rustfmt`/`clippy` — Rust toolchain (rustup), не npm-залежності.
+ * readOnly (CI): `cargo fmt --all -- --check` + `cargo clippy … -D warnings` (нуль мутацій).
+ * fix: `cargo fmt --all` + `cargo clippy --fix` + фінальний `cargo clippy … -D warnings`.
+ * @param {string[] | undefined} _files ігнорується (cargo обходить crate сам)
+ * @param {string} [cwd] корінь
+ * @param {{ readOnly?: boolean }} [opts] readOnly → без мутацій
+ * @returns {number} exit code
+ */
+export function lint(_files, cwd = process.cwd(), opts = {}) {
+  const readOnly = opts.readOnly === true
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  if (!existsSync(join(cwd, 'Cargo.toml'))) {
+    pass('lint-rust: немає Cargo.toml — кроки Rust пропущено')
+    return reporter.getExitCode()
+  }
+
+  const cargo = resolveCmd('cargo')
+  if (!cargo) {
+    fail('lint-rust: `cargo` не знайдено в PATH (Rust toolchain через rustup, rust.mdc)')
+    return reporter.getExitCode()
+  }
+
+  const fmtArgs = readOnly ? ['fmt', '--all', '--', '--check'] : ['fmt', '--all']
+  if (!runCargo(readOnly ? 'cargo fmt --check' : 'cargo fmt', cargo, fmtArgs, pass, fail)) {
+    return reporter.getExitCode()
+  }
+
+  if (!readOnly) {
+    const fixArgs = ['clippy', '--fix', '--allow-staged', '--allow-dirty', '--all-targets', '--all-features']
+    if (!runCargo('cargo clippy --fix', cargo, fixArgs, pass, fail)) return reporter.getExitCode()
+  }
+
+  runCargo('cargo clippy -D warnings', cargo, ['clippy', '--all-targets', '--all-features', '--', '-D', 'warnings'], pass, fail)
+  return reporter.getExitCode()
+}

package/rules/rust/rust.mdc

@@ -5,12 +5,10 @@ alwaysApply: false
 version: '1.4'
 ---
 
-**rustfmt** ([rust-lang/rustfmt](https://github.com/rust-lang/rustfmt)) — форматер; **clippy** ([rust-lang/rust-clippy](https://github.com/rust-lang/rust-clippy)) — лінтер. У скрипті **`lint-rust`** локально йдуть три кроки в одному рядку: `cargo fmt --all` → `cargo clippy --fix --allow-staged --allow-dirty --all-targets --all-features` → фінальний `cargo clippy --all-targets --all-features -- -D warnings`. У CI — без `--fix`: `cargo fmt --all -- --check` і `cargo clippy ... -- -D warnings` (див. `lint-rust.yml`).
+**rustfmt** ([rust-lang/rustfmt](https://github.com/rust-lang/rustfmt)) — форматер; **clippy** ([rust-lang/rust-clippy](https://github.com/rust-lang/rust-clippy)) — лінтер. Запуск — через **`n-cursor lint rust`** (адаптер `js/lint.mjs`): локально (fix) `cargo fmt --all` → `cargo clippy --fix --allow-staged --allow-dirty --all-targets --all-features` → фінальний `cargo clippy --all-targets --all-features -- -D warnings`; у `--read-only` (детект) — `cargo fmt --all -- --check` + `cargo clippy ... -- -D warnings`. Окремого `package.json`-скрипта немає. У CI cargo викликається напряму (див. `lint-rust.yml`).
 
 `cargo`, `rustfmt`, `clippy` не додавай у `devDependencies` — це Rust toolchain, ставиться через `rustup` локально або через `dtolnay/rust-toolchain@stable` у CI.
 
-Канон `scripts.lint-rust` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
-
 У `.vscode/extensions.json` `recommendations` мають містити `rust-lang.rust-analyzer` і `tamasfe.even-better-toml`: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
 
 Канон workflow `.github/workflows/lint-rust.yml`: [lint-rust.yml.snippet.yml](./policy/lint_rust_yml/template/lint-rust.yml.snippet.yml)
@@ -21,7 +19,7 @@ version: '1.4'
 
 Tauri-проєкт завжди має `src-tauri/Cargo.toml`, тому правило `rust` активується автоматично разом з `tauri`. Поділ обов'язків:
 
-- `rust` — `lint-rust` скрипт, `rust-analyzer`, `even-better-toml`, CI workflow.
+- `rust` — лінт через `n-cursor lint rust`, `rust-analyzer`, `even-better-toml`, CI workflow.
 - `tauri` — `tauri-apps.tauri-vscode` (див. **tauri.mdc**).
 
 Обидва правила перевіряють `.vscode/extensions.json` за `contains`-семантикою; конкурентного запису немає.

package/rules/php/policy/package_json/package_json.rego

@@ -1,16 +0,0 @@
-# Перевірка `package.json` (php.mdc).
-#
-# Канон надходить через --data: { "template": { "contains": ... } }
-# Структура --data сформована з template/package.json.contains.json.
-# FS-перевірки (`composer.json`, наявність `package.json` як такого) — у JS.
-package php.package_json
-
-import rego.v1
-
-deny contains msg if {
-	some script_name, needles in data.template.contains.scripts
-	actual := object.get(object.get(input, "scripts", {}), script_name, "")
-	some needle in needles
-	not contains(actual, needle)
-	msg := sprintf("package.json: scripts.%s має містити %q (php.mdc)", [script_name, needle])
-}

package/rules/php/policy/package_json/target.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
-  "files": { "single": "package.json" }
-}

package/rules/php/policy/package_json/template/package.json.contains.json

@@ -1,5 +0,0 @@
-{
-  "scripts": {
-    "lint-php": ["bun"]
-  }
-}

package/rules/python/policy/package_json/package_json.rego

@@ -1,16 +0,0 @@
-# Перевірка `package.json` (python.mdc).
-#
-# Канон надходить через --data: { "template": { "contains": ... } }
-# Структура --data сформована з template/package.json.contains.json.
-# FS-перевірки (наявність `package.json` як такого) — у JS.
-package python.package_json
-
-import rego.v1
-
-deny contains msg if {
-	some script_name, needles in data.template.contains.scripts
-	actual := object.get(object.get(input, "scripts", {}), script_name, "")
-	some needle in needles
-	not contains(actual, needle)
-	msg := sprintf("package.json: scripts.%s має містити %q (python.mdc)", [script_name, needle])
-}

package/rules/python/policy/package_json/target.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
-  "files": { "single": "package.json" }
-}

package/rules/python/policy/package_json/template/package.json.contains.json

@@ -1,5 +0,0 @@
-{
-  "scripts": {
-    "lint-python": ["bun"]
-  }
-}

package/rules/rust/policy/package_json/package_json.rego

@@ -1,18 +0,0 @@
-# Перевірка `package.json` для правила rust (rust.mdc).
-#
-# Канон надходить через --data: { "template": { "contains": ... } }
-# Структура --data сформована з template/package.json.contains.json.
-# Перевіряємо substring-вимоги до scripts.lint-rust: усі три кроки
-# (`cargo fmt`, `cargo clippy --fix`, фінальний `cargo clippy ... -D warnings`)
-# мають бути присутніми у значенні скрипта.
-package rust.package_json
-
-import rego.v1
-
-deny contains msg if {
-	some script_name, needles in data.template.contains.scripts
-	actual := object.get(object.get(input, "scripts", {}), script_name, "")
-	some needle in needles
-	not contains(actual, needle)
-	msg := sprintf("package.json: scripts.%s має містити %q (rust.mdc)", [script_name, needle])
-}

package/rules/rust/policy/package_json/target.json

@@ -1,5 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
-  "files": { "single": "package.json", "required": true },
-  "missingMessage": "package.json не існує — створи зі scripts.lint-rust (rust.mdc)"
-}

package/rules/rust/policy/package_json/template/package.json.contains.json

@@ -1,9 +0,0 @@
-{
-  "scripts": {
-    "lint-rust": [
-      "cargo fmt --all",
-      "cargo clippy --fix --allow-staged --allow-dirty",
-      "cargo clippy --all-targets --all-features -- -D warnings"
-    ]
-  }
-}