npm - @nitra/cursor - Versions diffs - 12.3.2 → 12.3.3 - Mend

@nitra/cursor 12.3.2 → 12.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/.claude-template/hooks/capture-decisions.sh CHANGED Viewed

@@ -91,26 +91,38 @@ if [[ -z "$TRANSCRIPT" ]]; then
   exit 0
 fi
+# Файли, змінені в сесії (file_path із tool_use Edit/Write/MultiEdit) — спільне
+# джерело для structural-скіпів нижче.
+CHANGED_FILES=$(jq -r '
+  select(.type == "assistant" or .role == "assistant")
+  | .message as $m
+  | ($m.content // [])
+  | if type == "array" then
+      map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
+          | .input.file_path // empty)
+      | .[]
+    else empty end
+' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || true)
+# Cross-project skip: якщо в сесії редагувалися файли, але ЖОДЕН не під $PROJECT_ROOT —
+# це паралельна робота в іншому проєкті; ADR сюди не пишемо (чужі рішення не змішуємо).
+# Сесії без редагувань (чисте Q&A / дизайн-дискусія) не відкидаємо — це валідний ADR.
+# ENV `ADR_CAPTURE_SKIP_CROSS_PROJECT=0` вимикає скіп.
+if [[ "${ADR_CAPTURE_SKIP_CROSS_PROJECT:-1}" = "1" && -n "$CHANGED_FILES" ]]; then
+  if ! printf '%s\n' "$CHANGED_FILES" | has_in_project_change "$PROJECT_ROOT"; then
+    log "  → skipping ADR capture: cross-project session (no in-project changes)"
+    log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
+    exit 0
+  fi
+fi
 # Structural skip: якщо в сесії змінювалися лише tooling-файли — не викликаємо LLM.
 # ENV `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0` вимикає скіп.
-if [[ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" ]]; then
-  CHANGED_FILES=$(jq -r '
-    select(.type == "assistant" or .role == "assistant")
-    | .message as $m
-    | ($m.content // [])
-    | if type == "array" then
-        map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
-            | .input.file_path // empty)
-        | .[]
-      else empty end
-  ' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || true)
-  if [[ -n "$CHANGED_FILES" ]]; then
-    if printf '%s\n' "$CHANGED_FILES" | is_tooling_only_change "$PROJECT_ROOT"; then
-      log "  → skipping ADR capture: tooling-only session"
-      log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
-      exit 0
-    fi
+if [[ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" && -n "$CHANGED_FILES" ]]; then
+  if printf '%s\n' "$CHANGED_FILES" | is_tooling_only_change "$PROJECT_ROOT"; then
+    log "  → skipping ADR capture: tooling-only session"
+    log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
+    exit 0
   fi
 fi
@@ -166,7 +178,12 @@ TRANSCRIPT FOLLOWS:
 EOF
 )
-PROMPT_FULL=$(printf '%s\n%s\n' "$PROMPT" "$TRANSCRIPT")
+# Scope: обмежуємо рішення поточним проєктом. Для змішаних сесій (правки і тут, і в
+# чужих репо) детермінований cross-project gate не спрацьовує, тож звужуємо обсяг у промпті.
+# Йде ПЕРЕД інструкціями, щоб не сприйматись як перший рядок транскрипту.
+SCOPE_LINE="CURRENT PROJECT ROOT: $PROJECT_ROOT
+SCOPE: Document ONLY decisions evidenced by changes within this project root. Ignore edits and discussion about files outside it (parallel work in other repositories)."
+PROMPT_FULL=$(printf '%s\n\n%s\n%s\n' "$SCOPE_LINE" "$PROMPT" "$TRANSCRIPT")
 CLAUDE_MODEL="${CAPTURE_DECISIONS_CLAUDE_MODEL:-sonnet}"
 CURSOR_MODEL="${CAPTURE_DECISIONS_CURSOR_MODEL:-claude-4.6-sonnet-medium}"

package/.claude-template/hooks/lib/tooling-only.sh CHANGED Viewed

@@ -39,6 +39,22 @@ is_tooling_only_change() {
   return 1
 }
+# Cross-project guard: чи серед змінених файлів є хоч один під $proj.
+# Вхід: рядки-шляхи у stdin (абсолютні file_path із tool_use).
+# Вихід: 0 — є хоч один файл під $proj; 1 — жодного (сесія цілком в інших проєктах).
+# Призначення: відсікти ADR-чернетки від паралельної роботи в чужих репозиторіях.
+has_in_project_change() {
+  local proj="$1"
+  local f
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    case "$f" in
+      "$proj"/*) return 0 ;;
+    esac
+  done
+  return 1
+}
 # Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
 # Поза git-репо або при помилці — вертаємо 1 (не tooling).
 git_diff_only_version_field() {

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,11 @@
 # Changelog
+## [12.3.3] - 2026-06-20
+### Changed
+- ♻️ refactor(pipeline): Оновлено логіку ADR-захоплення та цілісність збірки
 ## [12.3.2] - 2026-06-20
 ### Fixed

package/package.json CHANGED Viewed

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

package/rules/bun/bun.mdc CHANGED Viewed

@@ -66,10 +66,10 @@ FROM oven/bun:alpine AS build-env
 ## lint
-Якщо в кореневому @package.json  існують скрипти з префіксом `lint-`, обов'язково створюй `lint` скрипт, який буде запускати всі ці скрипти з лінт-префіксом.
+Лінт запускається через CLI **`n-cursor`**, **не** через `package.json`-скрипти:
-У кінці скрипта `lint` додай `&& oxfmt .`.
+- **`n-cursor lint --full`** — весь репо: усі правила (per-file лінтери + конформність) + `oxfmt` у кінці (fix-режим);
+- **`n-cursor lint`** — дельта vs origin (per-file лінтери лише змінених файлів);
+- **`n-cursor lint <rule…>`** — конкретні правила (лінтер + конформність), напр. **`n-cursor lint ga`**.
-Якщо в **`.n-cursor.json`** у масиві **`rules`** є **`docker`**, у кореневому `package.json` **обов'язково** скрипт **`lint-docker`** (див. **`docker.mdc`**) і рядок **`bun run lint-docker`** у **`lint`**. Якщо є **`k8s`** — **обов'язково** **`lint-k8s`** і **`bun run lint-k8s`** у **`lint`** (див. **`k8s.mdc`**).
-**Зворотній інваріант:** якщо правила **немає** в `rules` (або воно явно перенесене в **`disable-rules`**), скрипту **`lint-<id>`** у кореневому `package.json` бути **не може**, і ланцюжок агрегованого **`scripts.lint`** не має містити **`bun run lint-<id>`**. Інакше `bun run lint` падатиме на вимкненому правилі — `n-cursor lint-<id>` ігнорує `.n-cursor.json` і обходить дерево незалежно від `rules`/`disable-rules`. Для скриптів із кількома власниками (як **`lint-image`** — обслуговує і **`image-avif`**, і **`image-compress`**) скрипт лишається дозволеним, поки активний **хоч один** власник; зворотній інваріант тригериться лише коли в `rules` немає **жодного** з них. Перевірка — **`npx @nitra/cursor fix bun`**.
+У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI `n-cursor`. У CI кожен workflow викликає **`n-cursor lint <rule> --read-only`** напряму (без обгорток).

package/rules/bun/policy/package_json/package_json.rego CHANGED Viewed

@@ -8,7 +8,6 @@
 #  - `devDependencies` лише `@nitra/*` + root-only тестові peer/tools для `n-cursor coverage`
 #    (правило `test` enabled завжди — див. `test/auto.md`; published workspace-и не мають
 #     `devDependencies` за `npm-module.mdc`)
-#  - Агрегований `lint` скрипт (cross-script aggregation logic)
 #
 # Перевірки, які ЗАЛИШИЛИСЬ у JS (потребують FS / cross-file):
 #  - `lint-docker` / `lint-k8s` коли `.n-cursor.json:rules` містить відповідне
@@ -17,13 +16,6 @@ package bun.package_json
 import rego.v1
-# ── Шаблони повідомлень ────────────────────────────────────────────────────
-lint_aggregate_missing_template := concat(" ", [
-	"У package.json є скрипти %v, але немає агрегованого `lint`.",
-	"Додай скрипт, який запускає їх через `bun run` (bun.mdc)",
-])
 # ── deny: заборонені top-level поля (template-driven) ─────────────────────
 # Сентинельний value відрізняє «поле відсутнє» від «поле є з будь-яким значенням»
@@ -43,29 +35,6 @@ deny contains msg if {
 	msg := sprintf("Кореневі devDependencies: дозволені лише @nitra/* або root-only test peers — прибери або перенеси: %s (bun.mdc)", [name])
 }
-# ── deny: агрегований lint-скрипт (cross-script aggregation logic) ───────
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script == ""
-	msg := sprintf(lint_aggregate_missing_template, [lint_prefixed_scripts])
-}
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script != ""
-	some script in lint_prefixed_scripts
-	not contains(lint_script, sprintf("bun run %s", [script]))
-	msg := sprintf("Скрипт `lint` має викликати `%s` через `bun run` (bun.mdc)", [script])
-}
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script != ""
-	not regex.match(`&&[ \t]+oxfmt[ \t]+\.[ \t]*$`, lint_script)
-	msg := "Скрипт `lint` має закінчуватися на `&& oxfmt .` (bun.mdc)"
-}
 # ── helpers ────────────────────────────────────────────────────────────────
 allowed_root_test_deps := {"vitest", "@vitest/coverage-v8", "@stryker-mutator/vitest-runner", "@playwright/test"}

package/rules/ga/ga.mdc CHANGED Viewed

@@ -118,11 +118,9 @@ concurrency:
       - uses: ./.github/actions/setup-bun-deps
 ```
-**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Канонічний скрипт у корені делегує виконання CLI `n-cursor lint-ga` (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`:
+**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Запуск — через **`n-cursor lint ga`** (CI — `--read-only`; бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`. Окремого `package.json`-скрипта немає.
-- `package.json` — `scripts.lint-ga` має містити `n-cursor lint-ga`: [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
-> Не використовуй `npx --no @nitra/cursor lint-ga` — `bun run` автоматично транслює `npx` у `bun x`, а `bun x` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання. Виклик через bin-ім’я `n-cursor` працює і у `bun run`, і у `npm run`.
+> Виклик через bin-ім’я `n-cursor` (а **не** `npx @nitra/cursor`): `bun x`/`npx` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання, тому в CI-кроці `run:` використовуй саме `n-cursor lint <rule>`.
 CLI робить preflight на `shellcheck` і `uv` (`uvx`) у `PATH`, потім запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.

package/rules/ga/policy/lint_ga/lint_ga.rego CHANGED Viewed

@@ -100,8 +100,8 @@ deny contains msg if {
 deny contains msg if {
 	expected_run_blob != ""
-	not contains(job_run_blob, "bun run lint-ga")
-	msg := "lint-ga.yml: має бути крок run: bun run lint-ga (ga.mdc)"
+	not contains(job_run_blob, "n-cursor lint ga --read-only")
+	msg := "lint-ga.yml: має бути крок run: n-cursor lint ga --read-only (ga.mdc)"
 }
 # ── helpers ────────────────────────────────────────────────────────────────

package/rules/ga/policy/lint_ga/template/lint-ga.yml.snippet.yml CHANGED Viewed

@@ -38,4 +38,4 @@ jobs:
           | sudo tar -xz -C /usr/local/bin conftest
       - name: Lint GA
-        run: bun run lint-ga
+        run: n-cursor lint ga --read-only

package/rules/js-lint/js-lint.mdc CHANGED Viewed

@@ -5,23 +5,20 @@ alwaysApply: false
 version: '1.30'
 ---
-**oxlint**, **ESLint**, **jscpd**, **knip**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`**, **`bunx knip`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
+**oxlint**, **ESLint**, **jscpd**, **knip**. Запуск — **`n-cursor lint js-lint js-lint-ci`** (локально; у CI — `--read-only`, без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
 У кожному **`package.json`** проєкту (корінь і всі workspace-пакети) має бути **`"type": "module"`** — весь код у ESM.
 ```json title="package.json"
 {
   "type": "module",
-  "scripts": {
-    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
-  },
   "devDependencies": {
     "@nitra/eslint-config": "^3.10.0"
   }
 }
 ```
-Канон `type` + `scripts.lint-js` (substring requirement) і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
+Канон `type` і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json). Окремого `lint-js` скрипта немає — лінт через **`n-cursor lint js-lint js-lint-ci`** (CI — `--read-only`).
 ## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`

package/rules/js-lint/policy/lint_js_yml/template/lint-js.yml.snippet.yml CHANGED Viewed

@@ -37,8 +37,4 @@ jobs:
       - uses: ./.github/actions/setup-bun-deps
       - name: Eslint
-        run: |
-          bunx oxlint
-          bunx eslint .
-          bunx jscpd .
-          bunx knip --no-config-hints
+        run: n-cursor lint js-lint js-lint-ci --read-only

package/rules/js-lint/policy/package_json/template/package.json.snippet.json CHANGED Viewed

@@ -1,8 +1,5 @@
 {
   "type": "module",
-  "scripts": {
-    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
-  },
   "devDependencies": {
     "@nitra/eslint-config": "^3.10.0"
   }

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

@@ -3,30 +3,29 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: 0ab5b22c
+  crc: b0c7a4c2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
-Оркестратор `n-cursor lint` визначає, які правила лінтування застосовувати, керуючись двома ортогональними осями: консолідацією правил та уніфікацією режиму `readonly`. Вибір правил відбувається на основі конфігурацій, зокрема файлів `meta.json`, які визначають обсяг дії (`per-file` чи `full`) для кожного правила. Запуск лінтування може сканувати лише змінені файли відносно origin (за замовчуванням) або весь репозиторій при використанні прапорця `--full`.
+## Огляд
+Модуль відповідає за визначення та виконання процесу лінтування коду. Функція `selectLintRules` вибирає та сортує ідентифікатори правил лінтування на основі конфігурацій, визначених у meta.json. Функція `runLint` запускає перевірку обраних правил для змінених або всіх файлів репозиторію.
 ## Поведінка
-Поведінка
-selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
-runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах (`runPerFileRules`), запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
-**Fail-fast — лише в `--read-only`** (CI/детект): перший ненульовий код спиняє. У fix-режимі (default) ненульовий код per-file правила НЕ спиняє — проганяються всі правила й виконується крок виправлення (конформність-драбина), а повертається найгірший код.
-У режимі `--full` без `--read-only` після конформність-фази (`runFullConformancePhase`) друкується резюме викликів моделей за прогін (`reportRunStats`: локальна / cloud-min / cloud-avg) і викликається escalation-аналітика (`analyze-escalation.mjs`): фіксує зсув escalation-логу до фази, після — аналізує записи саме цього прогону. Жодне з цього не впливає на exit-код lint.
+selectLintRules вибирає і сортує ідентифікатори правил для лінтування на основі їхніх конфігурацій, включаючи можливість включення правил, що застосовуються до всього репозиторію.
+runLint запускає процес лінтування, виконуючи перевірку правил для змінених файлів або для всього репозиторію, залежно від наданих опцій, і може виконувати форматування.
 ## Публічний API
-selectLintRules — Вибирає ідентифікатори правил для контексту в алфавітному порядку.
+selectLintRules — Вибирає ідентифікатори правил для контексту, упорядковані за алфавітом.
 runLint — Запускає процес лінтування.
-  full — Сканує весь репозиторій порівняно з початковим станом.
+  full — Сканує весь репозиторій, порівнюючи його з початковим станом.
   readOnly — Виявляє проблеми без внесення змін.
-  rules — Перевіряє лише відповідність заданого набору правил, ігноруючи повне сканування.
+  rules — Виконує повне сканування лише для вказаних правил у заданому обсязі.
 ## Гарантії поведінки
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/lint/js/orchestrate.mjs CHANGED Viewed

@@ -3,9 +3,11 @@ import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { cwd as processCwd } from 'node:process'
+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'
 // Цей файл: npm/rules/lint/js/orchestrate.mjs → PACKAGE_ROOT = npm (чотири dirname угору).
 const PACKAGE_ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
@@ -120,12 +122,62 @@ async function runFullConformancePhase(cwd, readOnly, log) {
   return conformanceCode
 }
+/**
+ * Формат-крок (`oxfmt .`): whole-tree форматування у fix-режимі. У read-only НЕ викликається
+ * (CI/детект — нуль мутацій). `oxfmt` форматує не лише JS, а й root-конфіги (toml тощо), тож
+ * крок незалежний від набору правил і scope. Якщо `oxfmt` відсутній у PATH — пропуск (не fail).
+ * @param {string} cwd корінь
+ * @param {(s: string) => void} log логер
+ * @returns {Promise<number>} код виходу oxfmt (0 — OK або пропущено)
+ */
+async function runFormat(cwd, log) {
+  const oxfmt = resolveCmd('oxfmt')
+  if (!oxfmt) {
+    log('ℹ️  lint: oxfmt недоступний у PATH — формат-крок пропущено.\n')
+    return 0
+  }
+  const r = spawnSync(oxfmt, ['.'], { cwd, stdio: 'inherit', shell: false })
+  const code = typeof r.status === 'number' ? r.status : 1
+  if (code !== 0) log(`❌ lint: oxfmt — помилка (код ${code})\n`)
+  return code
+}
+/**
+ * Scoped-режим (`lint <rule…>`): повний прогін НАЗВАНИХ правил — їх лінтер (`js/lint.mjs`,
+ * whole-repo) для тих, що його мають, + конформність для всіх названих. Дзеркалить `--full`,
+ * але звужено до правил, тож `lint ga` ≡ standalone `lint-ga`. Конформність-only правила
+ * (напр. `changelog` із hk) не мають `js/lint.mjs` → проганяється лише їх конформність
+ * (зворотна сумісність із колишнім `fix <rule>`). oxfmt у scoped НЕ запускається — це
+ * таргетований прогін правил, а не глобальне форматування.
+ * @param {string[]} rules id названих правил
+ * @param {{ cwd: string, readOnly: boolean, rulesDir: string, conformance: boolean, log: (s: string) => void }} ctx контекст (`conformance` — чи запускати конформність; false для юніт-тестів із кастомним rulesDir, де реальний пакет недоступний)
+ * @returns {Promise<number>} найгірший код (read-only — fail-fast на першому ненульовому)
+ */
+async function runScopedRules(rules, ctx) {
+  const { cwd, readOnly, rulesDir, conformance, log } = ctx
+  const metaById = readAllMeta(rulesDir)
+  const linterIds = rules.filter(id => existsSync(join(rulesDir, id, 'js', 'lint.mjs')))
+  let worst = 0
+  if (linterIds.length > 0) {
+    const perFile = await runPerFileRules(linterIds, { rulesDir, changed: undefined, cwd, readOnly, metaById, log })
+    if (perFile.stop) return perFile.code
+    worst = perFile.code
+  }
+  if (!conformance) return worst
+  const conformanceCode = await runConformance(cwd, readOnly, log, rules)
+  if (conformanceCode !== 0) {
+    if (readOnly) return conformanceCode
+    worst = conformanceCode
+  }
+  return worst
+}
 /**
  * Запускає lint-оркестрацію.
  * @param {{ full?: boolean, readOnly?: boolean, rules?: string[], cwd?: string, rulesDir?: string, log?: (s: string) => void }} [opts] параметри
  *   - `full` — весь репо (`true`) проти дельти vs origin (`false`, default);
  *   - `readOnly` — лише детект без мутацій (`true`) проти fix (`false`, default);
- *   - `rules` — непорожній фільтр → лише конформність цих правил (без лінтер-скану; мапить `fix <rule>`).
+ *   - `rules` — непорожній scope → повний прогін лише цих правил (лінтер + конформність, whole-repo).
  * @returns {Promise<number>} exit code
  */
 export async function runLint(opts = {}) {
@@ -136,9 +188,9 @@ export async function runLint(opts = {}) {
   const rulesDir = opts.rulesDir ?? RULES_DIR
   const log = opts.log ?? (s => process.stdout.write(s))
-  // Rule-filter режим (напр. `lint changelog` із hk): лише конформність указаних правил, без лінтерів.
+  // Scoped режим (`lint <rule…>`): повний прогін названих правил — лінтер + конформність.
   if (rules.length > 0) {
-    return runConformance(cwd, readOnly, log, rules)
+    return runScopedRules(rules, { cwd, readOnly, rulesDir, conformance: opts.rulesDir === undefined, log })
   }
   // Default scope — дельта vs origin (merge-base main/origin/main); `--full` — весь репо.
@@ -163,5 +215,12 @@ export async function runLint(opts = {}) {
       worst = conformanceCode
     }
   }
+  // Формат-крок (oxfmt): fix-режим — завжди (будь-який scope); read-only пропускаємо (нуль
+  // мутацій). Кастомний rulesDir (юніт-тести) — реальний пакет недоступний, тож пропускаємо.
+  if (!readOnly && opts.rulesDir === undefined) {
+    const fmtCode = await runFormat(cwd, log)
+    if (fmtCode !== 0) worst = fmtCode
+  }
   return worst
 }

package/rules/python/js/docs/index.md CHANGED Viewed

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

package/rules/python/js/docs/lint.md ADDED Viewed

@@ -0,0 +1,21 @@
+---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/python/js/lint.mjs
+docgen:
+  crc: a0d17a44
+  score: 100
+---
+Оркестраторний адаптер правила `python` для `n-cursor lint`. Делегує перевірку наявній CLI-формі (`runLintPython` із `../lint/lint.mjs`). Режиму на рівні окремих файлів немає — `uv`/`ruff`/`mypy` працюють по всьому проєкту, тож параметр `files` ігнорується. За відсутності `pyproject.toml` у корені крок завершується успіхом без запуску інструментів.
+## Поведінка
+1. Викликає CLI-форму python-лінтера для всього проєкту.
+2. У `readOnly` пробрасує прапорець далі: `ruff` без `--fix`, `ruff format --check` (нуль мутацій для CI).
+3. Повертає код виходу інструменту.
+## Гарантії поведінки
+- Read-only за наявності `readOnly`: інструменти не мутують робоче дерево.
+- Не звертається до мережі (uv-кроки можуть, але це поведінка делегата, не цього модуля).

package/rules/python/js/lint.mjs ADDED Viewed

@@ -0,0 +1,14 @@
+/** @see ./docs/lint.md */
+import { runLintPython } from '../lint/lint.mjs'
+/**
+ * Ci-крок python: делегує у наявний CLI правила (per-file режиму немає — `files` ігнорується;
+ * uv/ruff/mypy працюють по всьому проєкту). Без `pyproject.toml` крок — no-op (exit 0).
+ * @param {string[] | undefined} _files ігнорується (whole-project аналіз)
+ * @param {string} [_cwd] корінь (CLI бере process.cwd())
+ * @param {{ readOnly?: boolean }} [opts] readOnly → ruff без `--fix`, format `--check` (нуль мутацій)
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, _cwd, opts = {}) {
+  return runLintPython({ readOnly: opts.readOnly === true })
+}

package/rules/python/lint/docs/lint.md CHANGED Viewed

@@ -3,324 +3,27 @@ type: JS Module
 title: lint.mjs
 resource: npm/rules/python/lint/lint.mjs
 docgen:
-  crc: 92c8f115
+  crc: 61a1e3c3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+  issues: internal-name:runStandardLint,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
-Модуль `npm/rules/python/lint/lint.mjs` реалізує крок `lint-python` — частину
-загального лінт-пайплайну монорепозиторію. Крок виконує перевірку Python-частини
-проєкту відповідно до правила `python.mdc` і базується на пакетному менеджері
-[uv](https://docs.astral.sh/uv/).
+## Огляд
-Поведінкові ключові точки:
+Забезпечує виконання обов'язкових кроків для валідації Python-коду відповідно до правил, визначених у `python.mdc`, використовуючи інструменти з [uv](https://docs.astral.sh/uv/). Якщо `pyproject.toml` відсутній у корені, процес завершується з кодом 0. Якщо файл присутній, але `uv` не знайдено в PATH, це розглядається як помилка. Обов'язкові кроки включають перевірку актуальності lock-файлу (`uv lock --check`) та збірку середовища (`uv sync --frozen`). Опціональні лінтери (`ruff`, `mypy`) запускаються лише за умови їх доступності через `uv run`. Цей процес реалізує канон патерну `lint-*` (серіалізація через `runStandardLint`).
-- Якщо у корені, переданому як `cwd` (за замовчуванням `process.cwd()`), немає
-  файлу `pyproject.toml`, крок завершується успіхом (`exit code 0`) без запуску
-  будь-яких інструментів. Це дозволяє безпечно вмикати крок у репозиторіях
-  без Python-частини.
-- Якщо `pyproject.toml` присутній, але бінарника `uv` немає в `PATH`, крок
-  завершується помилкою. Інших пакет-менеджерів (Poetry, pip, pdm тощо) модуль
-  не підтримує — `uv` є єдиним каноном.
-- Обовʼязкові кроки `uv lock --check` і `uv sync --frozen` запускаються завжди,
-  якщо `uv` доступний.
-- Опційні лінтери (`ruff check --fix`, `ruff format`, `mypy`) запускаються
-  лише якщо вони доступні через `uv run --frozen <tool> --version`. Якщо
-  відповідного інструмента у uv-середовищі немає — крок пропускається з
-  pass-повідомленням (аналогічно «optional vendor-tools» у `php.mdc`).
-- `ruff` працює в auto-fix-режимі (`--fix`, потім `format`), тобто може
-  мутувати робоче дерево, подібно до `markdownlint-cli2 --fix` у `lint-text`
-  чи `clippy --fix` у `lint-rust`.
-- Серіалізація запусків CLI організована через `runStandardLint` (а не через
-  безпосередній `withLock`) — це відповідає канону патерну `lint-*`, описаному
-  в `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»).
+## Поведінка
-Файл одночасно є:
+runLintPythonSteps виконує обов'язкові кроки для Python-лінтування за правилом python.mdc на базі [uv](https://docs.astral.sh/uv/). Якщо `pyproject.toml` відсутній, кроки пропускаються. Якщо `uv` не знайдено, виникає помилка. Виконує перевірку актуальності lock-файлу (`uv lock --check`) та збірку середовища (`uv sync --frozen`). Опціонально запускає лінтери (`ruff`, `mypy`) через `uv run`, якщо вони доступні.
+runLintPython серіалізує запуск кроків лінтування Python через механізм `runStandardLint` та повертає код виходу.
-1. Бібліотекою (експортує функції `runLintPythonSteps` та `runLintPython`).
-2. CLI-точкою входу — при запуску напряму (`isRunAsCli`) виконує
-   `runLintPython()` і виставляє `process.exitCode`.
+## Публічний API
-## Експорти / API
+runLintPythonSteps — Виконує внутрішні етапи перевірки коду Python без блокування.
+runLintPython — Виконує публічну команду перевірки коду Python, забезпечуючи унікальність виконання на основі стану Git-дерева та використовуючи механізм блокування.
-| Експорт              | Тип                     | Призначення                                                                                                                                               |
-| -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `runLintPythonSteps` | `function`              | Виконує внутрішні кроки `lint-python` (без зовнішнього локу). Призначений для повторного використання з обгортки `runStandardLint` та для тестування.     |
-| `runLintPython`      | `() => Promise<number>` | Публічна CLI-форма: запускає `runLintPythonSteps` через `runStandardLint`, який бере глобальний лок `lint-python` і дедупає прогони за станом git-дерева. |
+## Гарантії поведінки
-Модуль не має default-export. Усі експорти — іменовані ES Module exports.
-Side effect модуля верхнього рівня: якщо файл запущений як CLI
-(`isRunAsCli(import.meta.url)` повертає `true`), на верхньому рівні
-виконується `await runLintPython()` і результат записується у
-`process.exitCode`.
-## Функції
-### `runTool(label, cmd, args, pass, fail)`
-Внутрішня (не експортується) функція-обгортка над `child_process.spawnSync`,
-яка запускає вказаний CLI-крок і репортить результат через колбеки репортера.
-- Сигнатура: `runTool(label: string, cmd: string, args: string[], pass: (msg: string) => void, fail: (msg: string) => void): boolean`
-- Параметри:
-  - `label` — людиночитана назва кроку, використовується у повідомленнях
-    (`lint-python: <label> — OK` / `lint-python: <label> — помилка ...`).
-  - `cmd` — абсолютний шлях до виконуваного файлу (наприклад, отриманий через
-    `resolveCmd('uv')`).
-  - `args` — масив аргументів CLI.
-  - `pass` — callback репортера для успіху.
-  - `fail` — callback репортера для невдачі.
-- Повертає: `true`, якщо процес завершився з `status === 0`, інакше `false`.
-- Спосіб запуску: `spawnSync(cmd, args, { stdio: 'inherit', shell: false })`.
-  Це означає, що stdout/stderr CLI-кроку успадковуються від батьківського
-  процесу (видно користувачу), а інтерпретація аргументів shell-ом
-  вимкнена — аргументи передаються «as is».
-- Обробка статусу: якщо `r.status` не число (наприклад, процес був убитий
-  сигналом), у повідомлення про помилку підставляється `1`.
-- Side effects: запуск зовнішнього процесу; запис у stdout/stderr батька;
-  виклик `pass` або `fail` репортера.
-### `uvToolAvailable(uv, tool)`
-Внутрішня (не експортується) перевірка наявності лінтера всередині
-uv-середовища.
-- Сигнатура: `uvToolAvailable(uv: string, tool: string): boolean`
-- Параметри:
-  - `uv` — абсолютний шлях до бінарника `uv`.
-  - `tool` — назва бінарника, що перевіряється (`ruff`, `mypy`, тощо).
-- Повертає: `true`, якщо `uv run --frozen <tool> --version` завершився з
-  кодом `0`, інакше `false`.
-- Спосіб запуску: `spawnSync(uv, ['run', '--frozen', tool, '--version'],
-{ stdio: 'ignore', shell: false })`. `stdio: 'ignore'` гасить весь вивід
-  пробної команди, щоб не засмічувати лог.
-- Side effects: запуск дочірнього процесу `uv run --frozen <tool> --version`.
-  Опція `--frozen` гарантує, що `uv` не намагатиметься оновлювати lock-файл
-  під час перевірки.
-### `runLintPythonSteps(cwd?)`
-Експортована функція. Виконує всю послідовність кроків `lint-python` без
-зовнішнього серіалізаційного локу.
-- Сигнатура: `runLintPythonSteps(cwd?: string): number`
-- Параметри:
-  - `cwd` — корінь репозиторію. За замовчуванням `process.cwd()`.
-- Повертає: код виходу — `0`, якщо всі обовʼязкові кроки пройшли успішно,
-  `1` — якщо хоча б один крок зафейлив. Кінцевий код повертається через
-  `reporter.getExitCode()` (інстансу `createCheckReporter`).
-- Алгоритм:
-  1. Створює репортер: `const reporter = createCheckReporter()`,
-     дістає колбеки `{ pass, fail }`.
-  2. Перевіряє `existsSync(join(cwd, 'pyproject.toml'))`. Якщо файла
-     немає — викликає `pass(...)` з повідомленням «кроки Python пропущено»
-     і повертає `reporter.getExitCode()`.
-  3. `const uv = resolveCmd('uv')` — резолвить абсолютний шлях до `uv`.
-     Якщо `uv` не знайдено — `fail(...)` і повернення коду.
-  4. Виконує `runTool('uv lock --check', uv, ['lock', '--check'], pass, fail)`.
-     За невдачі — повертає поточний код (далі не йде).
-  5. Виконує `runTool('uv sync --frozen', uv, ['sync', '--frozen'], pass,
-fail)`. За невдачі — повертає поточний код.
-  6. Створює локальний хелпер `runOptionalUvTool(tool, label, args)`
-     (див. нижче) і послідовно запускає:
-     - `runOptionalUvTool('ruff', 'ruff check --fix', ['check', '--fix', '.'])`
-     - `runOptionalUvTool('ruff', 'ruff format', ['format', '.'])`
-     - `runOptionalUvTool('mypy', 'mypy', ['.'])`
-       За першої ж справжньої невдачі (повертає `false`) — повернення поточного
-       коду виходу.
-  7. Повертає `reporter.getExitCode()`.
-- Side effects:
-  - Запуск зовнішніх процесів (`uv lock`, `uv sync`, `uv run ruff`,
-    `uv run mypy`).
-  - `ruff check --fix` та `ruff format` можуть **модифікувати файли
-    проєкту** (auto-fix Python-коду).
-  - `uv sync --frozen` може створювати або оновлювати `.venv` (з повним
-    дотриманням `uv.lock`).
-  - Запис у stdout/stderr через `stdio: 'inherit'`.
-### `runOptionalUvTool(tool, label, args)` (вкладена у `runLintPythonSteps`)
-Внутрішній замикач, доступний лише всередині `runLintPythonSteps`. Захоплює
-`uv`, `pass`, `fail` із зовнішньої області видимості.
-- Сигнатура: `runOptionalUvTool(tool: string, label: string, args: string[]): boolean`
-- Параметри:
-  - `tool` — імʼя інструмента (`ruff`, `mypy`).
-  - `label` — назва кроку для повідомлень.
-  - `args` — аргументи, які слід передати інструменту після `uv run --frozen <tool>`.
-- Повертає: `true`, якщо крок успішно завершився **або** інструмент
-  відсутній у uv-середовищі (тоді крок пропускається з pass-повідомленням).
-  `false` повертається тільки коли інструмент доступний і завершився з
-  ненульовим статусом.
-- Логіка:
-  1. `if (!uvToolAvailable(uv, tool))` → `pass(...)` з повідомленням «крок
-     пропущено» і повертає `true` (це коректне продовження пайплайну,
-     інструмент трактується як optional).
-  2. Інакше викликає `runTool(label, uv, ['run', '--frozen', tool, ...args],
-pass, fail)`.
-- Side effects: ті ж, що й у `runTool` / `uvToolAvailable` (запуск дочірніх
-  процесів, оновлення репортера).
-### `runLintPython`
-Публічна обгортка-стрілкова функція.
-- Сигнатура: `runLintPython(): Promise<number>`
-- Параметри: немає.
-- Повертає: `Promise<number>` — код виходу, отриманий з `runStandardLint`.
-- Реалізація: `runStandardLint(import.meta.dirname, runLintPythonSteps)`.
-  Сенс параметрів:
-  - `import.meta.dirname` — директорія самого модуля; використовується
-    `runStandardLint` як ідентифікатор для дедуплікації / стану git-дерева.
-  - `runLintPythonSteps` — функція кроків, яку `runStandardLint` викличе
-    всередині глобального локу `lint-python`.
-- Серіалізація: `runStandardLint` бере глобальний лок `lint-python` (як
-  описано в `scripts.mdc`) та дедупає прогони за станом git-дерева, тому
-  паралельні виклики `runLintPython()` не перетинатимуться по запуску
-  `uv`.
-- Side effects: ті самі, що й у `runLintPythonSteps`, плюс блокування на
-  файловому локу.
-## CLI-вхід (верхній рівень модуля)
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exitCode = await runLintPython()
-}
-```
-- Перевірка `isRunAsCli(import.meta.url)` встановлює, чи запущений файл
-  безпосередньо як CLI-точка входу (наприклад, `node lint.mjs` або через
-  `n-cursor`), а не імпортований як модуль.
-- Якщо так — виконується top-level `await runLintPython()`, а результат
-  кладеться у `process.exitCode`. Це означає, що Node завершиться з цим
-  кодом після того, як event loop спорожніє.
-- Якщо файл імпортовано як модуль, цей блок не виконується — викликач сам
-  вирішує, як використати експортовані функції.
-## Залежності
-### Стандартна бібліотека Node.js
-- `node:child_process` → `spawnSync` — синхронний запуск зовнішніх процесів
-  (`uv`, `uv run …`).
-- `node:fs` → `existsSync` — перевірка наявності `pyproject.toml`.
-- `node:path` → `join` — побудова повного шляху до `pyproject.toml` від `cwd`.
-### Внутрішні модулі репозиторію
-- `../../../scripts/cli-entry.mjs` → `isRunAsCli` — детекція CLI-режиму
-  через `import.meta.url`.
-- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` —
-  фабрика репортера з методами `pass`, `fail`, `getExitCode`. Цей патерн
-  єдиний для всіх лінт-кроків.
-- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — пошук
-  виконуваного файлу в `PATH` (повертає абсолютний шлях або `null`).
-- `../../../scripts/lib/run-standard-lint.mjs` → `runStandardLint` —
-  стандартизована обгортка над лінт-кроком (глобальний лок + дедуплікація
-  за станом git-дерева).
-### Зовнішні бінарники (runtime-залежності)
-- `uv` — обовʼязковий у `PATH`, якщо в репозиторії є `pyproject.toml`.
-- `ruff` — опційний, перевіряється через `uv run --frozen ruff --version`.
-- `mypy` — опційний, перевіряється через `uv run --frozen mypy --version`.
-### Артефакти у проєкті
-- `pyproject.toml` (у корені `cwd`) — тригер запуску Python-частини.
-- `uv.lock` — використовується `uv lock --check` та `uv sync --frozen`,
-  має бути актуальним.
-## Потік виконання / Використання
-### Сценарій 1: Python-частини немає
-1. `runLintPython()` → `runStandardLint(...)` → `runLintPythonSteps()`.
-2. `existsSync('<cwd>/pyproject.toml')` повертає `false`.
-3. Репортер фіксує pass-повідомлення «немає pyproject.toml у корені — кроки
-   Python пропущено».
-4. Повертається `0`.
-### Сценарій 2: Python є, але `uv` не встановлений
-1. `existsSync('pyproject.toml')` → `true`.
-2. `resolveCmd('uv')` → `null`.
-3. `fail('lint-python: `uv` не знайдено в PATH ...')`.
-4. Повертається `1`.
-### Сценарій 3: Повний прогон з усіма лінтерами
-1. `uv lock --check` — перевірка lock-файлу. За невдачі вихід `1`.
-2. `uv sync --frozen` — інсталяція середовища строго за `uv.lock`. За
-   невдачі вихід `1`.
-3. `uvToolAvailable(uv, 'ruff')` → `true` → `uv run --frozen ruff check
---fix .`. Може **змінити файли**.
-4. `uv run --frozen ruff format .`. Також може **змінити файли**.
-5. `uvToolAvailable(uv, 'mypy')` → `true` → `uv run --frozen mypy .`.
-   Лише читає, не змінює дерево.
-6. Якщо всі кроки повернули `0` — підсумок `0`. Інакше — перший
-   ненульовий код розриває послідовність і повертається.
-### Сценарій 4: `ruff` або `mypy` не встановлені у uv-середовищі
-- Для відповідного інструмента `uvToolAvailable` поверне `false`.
-- Виводиться pass-повідомлення «<tool> недоступний у uv-середовищі —
-  крок пропущено».
-- Інші кроки виконуються штатно.
-### Як викликати з коду
-```js
-import { runLintPython, runLintPythonSteps } from './lint.mjs'
-// Стандартний шлях: з локом, дедуплікацією, асинхронно.
-const code = await runLintPython()
-process.exit(code)
-// Прямий виклик без локу (наприклад, у тестах або з власною серіалізацією):
-const codeRaw = runLintPythonSteps('/path/to/repo')
-```
-### Як викликати з CLI
-Файл є виконуваною точкою входу для лінт-пайплайну. У звичайному монорепо
-він викликається через спільний раннер (`n-cursor`, `bun run lint` тощо).
-Прямий запуск:
-```bash
-node npm/rules/python/lint/lint.mjs
-```
-Кодом виходу буде число з `runLintPython()` (`0` — OK, `1` — є помилки).
-## Rebuild Test
-За цією документацією можна відтворити модуль так:
-1. Створити ES Module-файл, що імпортує `spawnSync` з `node:child_process`,
-   `existsSync` з `node:fs`, `join` з `node:path`, а також `isRunAsCli`,
-   `createCheckReporter`, `resolveCmd`, `runStandardLint` з відповідних
-   шляхів `../../../scripts/...`.
-2. Реалізувати приватну `runTool(label, cmd, args, pass, fail)`:
-   `spawnSync` з `stdio: 'inherit'`, `shell: false`; при `status === 0`
-   викликати `pass`, інакше `fail` з кодом (типу number або `1` при
-   неприродному завершенні); повертати `boolean`.
-3. Реалізувати `uvToolAvailable(uv, tool)`: `spawnSync(uv, ['run',
-'--frozen', tool, '--version'], { stdio: 'ignore', shell: false })` →
-   `r.status === 0`.
-4. Експортувати `runLintPythonSteps(cwd = process.cwd())`:
-   - створити репортер;
-   - якщо `pyproject.toml` відсутній → `pass(...)` і повернути код;
-   - резолвити `uv`; якщо немає → `fail(...)` і повернути;
-   - послідовно: `uv lock --check`, `uv sync --frozen` (обовʼязкові);
-   - опційні через локальну функцію-замикач `runOptionalUvTool`: `ruff
-check --fix .`, `ruff format .`, `mypy .` — кожен через
-     `uvToolAvailable` + `runTool`;
-   - повернути `reporter.getExitCode()`.
-5. Експортувати `runLintPython = () => runStandardLint(import.meta.dirname,
-runLintPythonSteps)`.
-6. На верхньому рівні: `if (isRunAsCli(import.meta.url)) process.exitCode =
-await runLintPython()`.
-Результат повинен поведінково збігтися з оригіналом: ті самі повідомлення,
-ті самі коди виходу, така ж серіалізація та обробка опційних інструментів.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/python/lint/lint.mjs CHANGED Viewed

@@ -63,9 +63,11 @@ function uvToolAvailable(uv, tool) {
 /**
  * Внутрішні кроки `lint-python` без локу.
  * @param {string} [cwd] корінь репозиторію
+ * @param {{ readOnly?: boolean }} [opts] readOnly → `ruff` без `--fix`, `ruff format --check` (нуль мутацій, CI/детект)
  * @returns {number} 0 — OK, 1 — є помилки
  */
-export function runLintPythonSteps(cwd = process.cwd()) {
+export function runLintPythonSteps(cwd = process.cwd(), opts = {}) {
+  const readOnly = opts.readOnly === true
   const reporter = createCheckReporter()
   const { pass, fail } = reporter
@@ -98,8 +100,10 @@ export function runLintPythonSteps(cwd = process.cwd()) {
     return runTool(label, uv, ['run', '--frozen', tool, ...args], pass, fail)
   }
-  if (!runOptionalUvTool('ruff', 'ruff check --fix', ['check', '--fix', '.'])) return reporter.getExitCode()
-  if (!runOptionalUvTool('ruff', 'ruff format', ['format', '.'])) return reporter.getExitCode()
+  const ruffCheck = readOnly ? ['check', '.'] : ['check', '--fix', '.']
+  const ruffFormat = readOnly ? ['format', '--check', '.'] : ['format', '.']
+  if (!runOptionalUvTool('ruff', readOnly ? 'ruff check' : 'ruff check --fix', ruffCheck)) return reporter.getExitCode()
+  if (!runOptionalUvTool('ruff', readOnly ? 'ruff format --check' : 'ruff format', ruffFormat)) return reporter.getExitCode()
   if (!runOptionalUvTool('mypy', 'mypy', ['.'])) return reporter.getExitCode()
   return reporter.getExitCode()
@@ -107,10 +111,12 @@ export function runLintPythonSteps(cwd = process.cwd()) {
 /**
  * Публічна CLI-форма: серіалізує через `withLock('lint-python')` + дедуп за станом git-дерева.
+ * @param {{ readOnly?: boolean }} [opts] readOnly → детект без мутацій (проброс у кроки)
  * @returns {Promise<number>} код виходу
  */
-export const runLintPython = () => runStandardLint(import.meta.dirname, runLintPythonSteps)
+export const runLintPython = (opts = {}) =>
+  runStandardLint(import.meta.dirname, () => runLintPythonSteps(process.cwd(), opts))
 if (isRunAsCli(import.meta.url)) {
-  process.exitCode = await runLintPython()
+  process.exitCode = await runLintPython({ readOnly: process.argv.includes('--read-only') })
 }

package/rules/python/meta.json CHANGED Viewed

	@@ -1 +1 @@
1	- { "auto": { "glob": "pyproject.toml" } }
1	+ { "auto": { "glob": "pyproject.toml" }, "lint": "full" }

package/rules/rego/rego.mdc CHANGED Viewed

@@ -1,5 +1,5 @@
 ---
-description: Opa, Rego — інструментарій (VS Code, lint-rego)
+description: Opa, Rego — інструментарій (VS Code, opa/regal)
 version: '1.1'
 globs: "**/*.rego"
 alwaysApply: false
@@ -12,17 +12,13 @@ alwaysApply: false
 ## Перевірка
 ```bash
-bun run lint-rego
+n-cursor lint rego
 ```
 Цілі — `npm/rules/` (рекурсивно знаходить `.rego` у `<rule>/policy/<concern>/`). Інші *.rego поза деревом додай у `LINT_TARGETS` у `npm/rules/rego/lint/lint.mjs`.
 `opa` і `regal` — лише у `PATH`, **не** додавай у `dependencies` / `devDependencies`.
-### `package.json`
-- Канон `scripts.lint-rego`: [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
 ### `.vscode/extensions.json`
 - Канон `recommendations` має містити `tsandall.opa` (LSP, format-on-save через `opa fmt`): [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)

package/rules/security/policy/package_json/package_json.rego CHANGED Viewed

@@ -5,14 +5,6 @@ package security.package_json
 import rego.v1
-# ── deny: кожен snippet leaf має співпадати з input ──────────────────────────
-deny contains msg if {
-	some script_name, expected in data.template.snippet.scripts
-	actual := object.get(object.get(input, "scripts", {}), script_name, "")
-	actual != expected
-	msg := sprintf("package.json: scripts.%s має бути %q (security.mdc)", [script_name, expected])
-}
 # ── deny: жодного ключа з deny у dependencies/devDependencies ────────────────
 deny contains msg if {
 	some pkg, reason in data.template.deny.dependencies
@@ -25,14 +17,3 @@ deny contains msg if {
 	pkg in object.keys(object.get(input, "devDependencies", {}))
 	msg := sprintf("package.json: devDependencies.%s — %s (security.mdc)", [pkg, reason])
 }
-# ── deny: рядкові поля з contains мають містити кожен substring ──────────────
-# Перевіряємо лише наявні поля (якщо `scripts.<name>` відсутній — поле опціональне).
-deny contains msg if {
-	some script_name, needles in data.template.contains.scripts
-	actual := object.get(object.get(input, "scripts", {}), script_name, "")
-	actual != ""
-	some needle in needles
-	not contains(actual, needle)
-	msg := sprintf("package.json: scripts.%s має містити %q (security.mdc)", [script_name, needle])
-}

package/rules/security/security.mdc CHANGED Viewed

@@ -1,5 +1,5 @@
 ---
-description: Локальний та CI-секюріті-лінт через TruffleHog — скрипт `lint-security`, `.trufflehog-exclude`, інтеграція в агрегований `lint`; канонічний placeholder `sample-secret` у прикладних файлах
+description: Локальний та CI-секюріті-лінт через TruffleHog — `.trufflehog-exclude`, канонічний placeholder `sample-secret` у прикладних файлах
 globs: "**/.trufflehog-exclude,**/package.json,**/.github/workflows/**/*.yml"
 alwaysApply: false
 version: '2.1'
@@ -7,10 +7,10 @@ version: '2.1'
 [TruffleHog](https://github.com/trufflesecurity/trufflehog) — глобальний CLI (як `shellcheck`, `conftest`); **не** додавай до `dependencies`/`devDependencies`.
-## Канон `package.json#scripts`
+## Канон `package.json`
+Скан запускається через `n-cursor lint security` (CI — `n-cursor lint security --read-only`); окремого `lint-*` скрипта в `package.json` немає.
-- `lint-security` скрипт: [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
-- `lint` агрегатор повинен містити: [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
 - Заборонено `trufflehog` у `dependencies`/`devDependencies`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
 **Зауваження:**
@@ -19,8 +19,7 @@ version: '2.1'
 - `--no-update` — вимикає self-update check (CI-friendly).
 - `--exclude-paths .trufflehog-exclude` — файл з regex-patterns, які треба пропускати (аналог `[allowlist].paths` із gitleaks).
 - `--results=verified,unknown` — показує лише верифіковані секрети + ті, що TruffleHog не зміг перевірити (`unverified` дублікат відсіюється).
-- `--fail` — exit-code `183` за наявності знахідок (потрібно, щоб `bun run lint` падав).
-- Позиція в `lint`: за конвенцією після інших `lint-*` і перед `oxfmt`.
+- `--fail` — exit-code `183` за наявності знахідок (щоб лінт падав).
 ## `.trufflehog-exclude` (рекомендована основа)

package/rules/style-lint/policy/lint_style_yml/template/lint-style.yml.snippet.yml CHANGED Viewed

@@ -36,4 +36,4 @@ jobs:
       - uses: ./.github/actions/setup-bun-deps
       - name: StyleLint
-        run: npx stylelint '**/*.{css,scss,vue}'
+        run: n-cursor lint style-lint --read-only

package/rules/style-lint/policy/package_json/package_json.rego CHANGED Viewed

@@ -10,16 +10,6 @@ package style_lint.package_json
 import rego.v1
-# ── deny: substring requirements у scripts (contains) ────────────────────
-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 (style-lint.mdc)", [script_name, needle])
-}
 # ── deny: 2-level snippet walker (для stylelint.extends, якщо поле є) ────
 deny contains msg if {

package/rules/style-lint/style-lint.mdc CHANGED Viewed

@@ -95,16 +95,17 @@ $white-a1: color.adjust(white, $alpha: -0.85);
 - **Джерело правил:** перед тим як писати або суттєво змінювати **`.css`**, **`.scss`** або стилі в **`.vue`**, переглянь у корені проєкту (і в релевантних пакетах монорепо, якщо є) поле **`stylelint`** у **`package.json`** (зокрема `extends`), наявні **`.stylelintrc.*`**, **`stylelint.config.*`** та **`.stylelintignore`**. Не покладайся на «типові» правила stylelint з пам’яті — дотримуйся **проєктного** **`@nitra/stylelint-config`** і будь-яких локальних доповнень у репозиторії.
 - **Форматування** узгоджуй з **`n-text.mdc`** (oxfmt / `.oxfmtrc.json` для css, scss тощо), щоб форматер і stylelint не суперечили один одному.
-- **Запуск stylelint:** лише **`npx stylelint`**. Локально — через скрипт **`lint-style`** (`bun run lint-style`, з `--fix`); у **GitHub Actions** у кроці **`run`** викликай `npx stylelint '**/*.{css,scss,vue}'` напряму **без `--fix`** (CI — read-only, нуль мутацій; не через **`bun run lint-style`**). Не використовуй **`bunx stylelint`**. Після змін запускай **`bun run lint-style`** і виправляй усе, що лишилось після auto-fix; за потреби — повний `bun run lint` (навичка **`/n-lint`**).
+- **Запуск stylelint:** лише через **`n-cursor lint style-lint`** (локально — з auto-fix; у CI — `--read-only`, нуль мутацій). Під капотом — `npx stylelint`; **не** використовуй **`bunx stylelint`**. Після змін запускай **`n-cursor lint style-lint`** і виправляй усе, що лишилось після auto-fix; за потреби — повний прогін `n-cursor lint --full`.
 - **Не розширюй винятки:** не додавай зайві **`stylelint-disable`** без потреби; краще підлаштувати стилі під правила проєкту.
 ## Канон
 ### `package.json`
-- `lint-style` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
 - `stylelint.extends`: [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
+Окремого `lint-style` скрипта немає — запуск через **`n-cursor lint style-lint`** (CI — `--read-only`).
 ### `.vscode/extensions.json`
 - Канон `recommendations`: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
@@ -120,9 +121,6 @@ $white-a1: color.adjust(white, $alpha: -0.85);
 **`package.json`:**
 ```json title="package.json"
-  "scripts": {
-    "lint-style": "npx stylelint '**/*.{css,scss,vue}' --fix",
-  },
   "devDependencies": {
     "@nitra/stylelint-config": "^1.4.0"
   },
@@ -131,7 +129,7 @@ $white-a1: color.adjust(white, $alpha: -0.85);
   },
 ```
-Додай **`.github/workflows/lint-style.yml`** (лише **`.yml`**, **`ga.mdc`**): після **`checkout`** — локальний composite **`setup-bun-deps`**, далі `npx stylelint '**/*.{css,scss,vue}'` (CI — без `--fix`) у кроці **`run`**. **Не** дублюй окремі кроки **`setup-node`** / **`oven-sh/setup-bun`** / кеш / **`npm install`**.
+Додай **`.github/workflows/lint-style.yml`** (лише **`.yml`**, **`ga.mdc`**): після **`checkout`** — локальний composite **`setup-bun-deps`**, далі `n-cursor lint style-lint --read-only` у кроці **`run`**. **Не** дублюй окремі кроки **`setup-node`** / **`oven-sh/setup-bun`** / кеш / **`npm install`**.
 ```yaml title=".github/workflows/lint-style.yml"
 name: StyleLint

package/rules/text/js/formatting.mjs CHANGED Viewed

@@ -94,25 +94,20 @@ function checkTextConfigsExistence(passFn, failFn, cwd) {
 }
 /**
- * Перевіряє package.json для текстового стека: складний `lint-text` скрипт і
- * виклик `n-cursor lint-text --read-only` у відповідному workflow (CI — нуль мутацій). Решта (Prettier-заборона,
- * `@nitra/cspell-dict ^2.0.0+`, заборона `markdownlint-cli2` у залежностях,
- * `@nitra/*` гейт) — у Rego (`text.package_json`, `bun.package_json`).
+ * Перевіряє CI-workflow текстового стека: крок `n-cursor lint text --read-only` у
+ * `.github/workflows/lint-text.yml` (CI — нуль мутацій). Окремого `lint-text` скрипта в
+ * `package.json` немає — лінт через `n-cursor lint text`. Решта package.json-перевірок
+ * (Prettier-заборона, `@nitra/cspell-dict`, `@nitra/*` гейт) — у Rego (`text.package_json`, `bun.package_json`).
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  * @param {string} cwd корінь репозиторію
  */
-async function checkPackageJsonText(passFn, failFn, cwd) {
-  const pkgPath = join(cwd, 'package.json')
-  if (!existsSync(pkgPath)) return
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-  checkLintTextScript(pkg.scripts?.['lint-text'], passFn, failFn)
+async function checkLintTextWorkflow(passFn, failFn, cwd) {
   const lintTextWf = join(cwd, '.github/workflows/lint-text.yml')
   if (existsSync(lintTextWf)) {
     const wf = await readFile(lintTextWf, 'utf8')
     const root = parseWorkflowYaml(wf)
-    const canonRun = 'n-cursor lint-text --read-only'
+    const canonRun = 'n-cursor lint text --read-only'
     const ok = root ? anyRunStepIncludes(root, canonRun) : wf.includes(canonRun)
     if (ok) {
       passFn(`lint-text.yml викликає ${canonRun}`)
@@ -124,25 +119,6 @@ async function checkPackageJsonText(passFn, failFn, cwd) {
   }
 }
-/**
- * Перевіряє скрипт lint-text: канонічний — `n-cursor lint-text` (CLI пакета `@nitra/cursor` робить
- * `cspell` → `runShellcheckText()` → `bunx markdownlint-cli2 --fix` → `runV8rWithGlobs()`).
- * Дозволено whitespace навколо команди.
- * @param {unknown} lintText значення `scripts.lint-text` з package.json
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- */
-function checkLintTextScript(lintText, passFn, failFn) {
-  const lt = typeof lintText === 'string' ? lintText.trim() : ''
-  if (lt === 'n-cursor lint-text') {
-    passFn('lint-text делегує CLI n-cursor lint-text (cspell + shellcheck + markdownlint + v8r)')
-  } else {
-    failFn(
-      'package.json: lint-text має бути "n-cursor lint-text" — CLI пакета @nitra/cursor виконує cspell → shellcheck → markdownlint-cli2 → v8r (text.mdc)'
-    )
-  }
-}
 /**
  * Перевіряє відповідність проєкту правилам text.mdc.
  * @param {string} [cwd] корінь репозиторію
@@ -166,7 +142,7 @@ export async function check(cwd = process.cwd()) {
     }
   }
-  await checkPackageJsonText(pass, fail, cwd)
+  await checkLintTextWorkflow(pass, fail, cwd)
   return reporter.getExitCode()
 }

package/rules/text/policy/lint_text/template/lint-text.yml.snippet.yml CHANGED Viewed

@@ -58,4 +58,4 @@ jobs:
           | sh -s -- -b /usr/local/bin
       - name: Lint text
-        run: n-cursor lint-text --read-only
+        run: n-cursor lint text --read-only

package/rules/ga/policy/package_json/package_json.rego DELETED Viewed

@@ -1,20 +0,0 @@
-# Перевірка кореневого `package.json` для GitHub Actions tooling (ga.mdc).
-#
-# Канон надходить через --data: { "template": { "contains": ... } }
-# Структура --data сформована з template/package.json.contains.json.
-#
-# Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
-# (.cursor/rules/conftest.mdc). Лінт — `bun run lint-rego` (regal).
-package ga.package_json
-import rego.v1
-# Кожне рядкове поле з contains має містити кожен substring.
-# Відсутність ключа → `""` → contains() = false → deny.
-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 (ga.mdc)", [script_name, needle])
-}

package/rules/ga/policy/package_json/target.json DELETED Viewed

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

package/rules/ga/policy/package_json/template/package.json.contains.json DELETED Viewed

	@@ -1 +0,0 @@
1	- { "scripts": { "lint-ga": ["n-cursor lint-ga"] } }

package/rules/rego/policy/package_json/package_json.rego DELETED Viewed

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

package/rules/rego/policy/package_json/target.json DELETED Viewed

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

package/rules/rego/policy/package_json/template/package.json.snippet.json DELETED Viewed

	@@ -1 +0,0 @@
1	- { "scripts": { "lint-rego": "n-cursor lint-rego" } }

package/rules/security/policy/package_json/template/package.json.contains.json DELETED Viewed

	@@ -1 +0,0 @@
1	- { "scripts": { "lint": ["bun run lint-security"] } }

package/rules/security/policy/package_json/template/package.json.snippet.json DELETED Viewed

@@ -1,5 +0,0 @@
-{
-  "scripts": {
-    "lint-security": "trufflehog filesystem . --no-update --exclude-paths .trufflehog-exclude --results=verified,unknown --fail"
-  }
-}

package/rules/style-lint/policy/package_json/template/package.json.contains.json DELETED Viewed

@@ -1,5 +0,0 @@
-{
-  "scripts": {
-    "lint-style": ["npx stylelint"]
-  }
-}