@nitra/cursor 1.9.9 → 1.9.12

package/CHANGELOG.md

@@ -4,6 +4,34 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.9.12] - 2026-05-13
+
+### Removed
+
+- **`check-js-lint.mjs` — видалено дубльовані JS-копії канону `lint-js`:** експорти `CANONICAL_LINT_JS`, `isCanonicalLintJs`, `normalizeLintJsScript`, `nitraEslintConfigMeetsMinVersion` і константу `WHITESPACE_RE` видалено. Ці функції експортувалися, але **не використовувалися** у `check()` — пер-документна перевірка кореневого `package.json` (канонічний `lint-js`, `@nitra/eslint-config ≥ 3.9.2`, `type: "module"`, `engines.{node,bun}`) давно мігровано до rego-полісі `npm/policy/js_lint/package_json/`. Залишені експорти створювали два джерела істини: при оновленні канону (`bunx knip --no-config-hints`) доводилось правити і `.rego`, і `.mjs`-константу, що відкриває дрифт. Тепер канон лише в rego, JS-копії немає. У `check-js-lint.mjs` додано коментар з посиланням на rego-полісі.
+
+### Added
+
+- **`npm/policy/js_lint/package_json/package_json_test.rego` — rego-тести для канону `lint-js`:** перенесено покриття з JS-тестів (`normalizeLintJsScript`, `isCanonicalLintJs`, `nitraEslintConfigMeetsMinVersion`) у rego через `json.patch`-фікстури: 16 нових `test_*`-кейсів — happy path, неправильний порядок команд, відсутність `bunx knip`, відсутність `--no-config-hints`, `type` не `module`, `engines.node < 24`, `engines.bun < 1.3`, `@nitra/eslint-config` < 3.9.2, `workspace:*` дозволено. Покривається `bun run lint-rego` (`conftest verify`).
+
+### Changed
+
+- **`npm/tests/check-js-lint.test.mjs` — прибрано тести для видалених JS-копій:** видалено блоки `describe('normalizeLintJsScript / isCanonicalLintJs')` і `describe('nitraEslintConfigMeetsMinVersion')` разом з імпортами. Залишилися тести `verifyOxlintRcAgainstCanonical` (там JS усе ще authoritative — потрібен readFile + рекурсивне порівняння канон-блока).
+
+## [1.9.11] - 2026-05-13
+
+### Changed
+
+- **`lint-js` — `bunx knip --no-config-hints` у каноні (js-lint.mdc `1.20 → 1.21`):** до канонічного `lint-js`-скрипта додано прапор `--no-config-hints`, щоб knip не друкував щоразу інформаційну секцію «Configuration hints» (`Remove from ignoreDependencies/ignoreBinaries`). Hints не впливають на exit code і часто стосуються свідомо доданих ignore (`graphql` як peer-залежність) — щоразу їх читати немає сенсу. Оновлено: `CANONICAL_LINT_JS` у `check-js-lint.mjs`, `canonical_lint_js` у `npm_module_unused.../js_lint.package_json.rego`, приклади `lint-js`-скрипта і CI-блока у `npm/mdc/js-lint.mdc` + дзеркало `.cursor/rules/n-js-lint.mdc`, реальний `package.json#scripts.lint-js` у корені, реальний `.github/workflows/lint-js.yml`. Rego-deny `lint-js.yml: у run немає bunx knip` ловиться через `contains` — новий рядок з прапором проходить як раніше.
+
+## [1.9.10] - 2026-05-13
+
+### Added
+
+- **`npm/scripts/utils/knip-canonical.json` — канонічний baseline `knip.json` для проєктів-споживачів:** покриває типові false-positives `bunx knip` для наших правил — `entry` зі CLI-конфігами (eslint/stylelint/oxlint/jscpd/markdownlint-cli2/commitlint), `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`, `ignore` для `**/__fixtures__/**`, `ignoreDependencies` (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`), `ignoreBinaries` для CLI з канону `bunx`/`npx` (`actionlint`, `cspell`, `depcheck`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`). Структурно поряд з `oxlint-canonical.json` / `oxlint-canonical-skeleton.json` у `npm/scripts/utils/`.
+- **`js-lint.mdc` — секція про канонічний `knip.json` (версія `1.19 → 1.20`):** правило тепер вимагає `knip.json` у корені проєкту як стартовий baseline з канонічного файлу пакета. Перевіряється **лише наявність** — зміст подальших модифікацій локально не валідується (`entry` / `project` / `ignore` / `ignoreDependencies` / `ignoreBinaries` дозволені будь-які). Дзеркало — `.cursor/rules/n-js-lint.mdc`. Прибрано згадку про обовʼязковий `ignoreDependencies: ["graphql"]` як зміст-вимогу (тепер це лише стартова рекомендація через канон).
+- **`check-js-lint.mjs::checkKnipConfig` — auto-create з канону:** якщо `knip.json` відсутній у корені, чек копіює `KNIP_CANONICAL_JSON_PATH` у `knip.json` і повідомляє pass про створення. Раніше функція падала з fail на відсутність і додатково перевіряла `ignoreDependencies ∋ "graphql"` — обидві перевірки замінено на FS-existence + копію канону (side effect, описано у `js-lint.mdc`).
+
 ## [1.9.9] - 2026-05-13
 
 ### Changed

package/mdc/js-lint.mdc

@@ -1,7 +1,7 @@
 ---
 description: Перевірка JavaScript коду
 alwaysApply: true
-version: '1.19'
+version: '1.21'
 ---
 
 **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` мінімум `^3.9.2`** (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint); пакет **`@e18e/eslint-plugin`** окремо не додавай. Пакети oxlint/eslint/jscpd/knip не додавай без потреби монорепо.
@@ -22,7 +22,7 @@ version: '1.19'
 {
   "type": "module",
   "scripts": {
-    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip"
+    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
   },
   "devDependencies": {
     "@nitra/eslint-config": "^3.9.4"
@@ -65,15 +65,9 @@ version: '1.19'
 
 Перевірку невикористаних залежностей і експортів виконує **knip** (заміна `depcheck`). Викликається у скрипті `lint-js` і в CI разом з oxlint/eslint/jscpd — окремий крок у CI не потрібен.
 
-У корені проєкту має бути `knip.json` із `ignoreDependencies` для `graphql` (peer-залежність, часто використовується без прямого імпорту):
+У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@nitra/cursor` — файл [`npm/scripts/utils/knip-canonical.json`](../scripts/utils/knip-canonical.json). Він покриває типові false-positives для наших правил: `entry` зі CLI-конфігами (eslint, stylelint, oxlint, jscpd, markdownlint-cli2, `commitlint`), `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`, `ignore` для `**/__fixtures__/**`, `ignoreDependencies` для пакетів, посилання на які є лише в не-JS-конфігах (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`), і `ignoreBinaries` для CLI, які канон вимагає викликати через `npx`/`bunx` і яких заборонено додавати в `devDependencies` (`actionlint`, `cspell`, `depcheck`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`).
 
-```json title="knip.json"
-{
-  "ignoreDependencies": [
-    "graphql"
-  ]
-}
-```
+Якщо `knip.json` відсутній — `npx @nitra/cursor check js-lint` копіює канон у корінь проєкту (side effect). Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
 
 Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.
 
@@ -134,7 +128,7 @@ jobs:
           bunx oxlint
           bunx eslint .
           bunx jscpd .
-          bunx knip
+          bunx knip --no-config-hints
 ```
 
 Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.

package/package.json

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

package/policy/js_lint/package_json/package_json.rego

@@ -17,7 +17,7 @@ package js_lint.package_json
 
 import rego.v1
 
-canonical_lint_js := "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip"
+canonical_lint_js := "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
 
 # ── deny: `lint-js` скрипт ─────────────────────────────────────────────────
 

package/policy/js_lint/package_json/package_json_test.rego

@@ -0,0 +1,130 @@
+# Тести для `js_lint.package_json`. Запуск:
+#   conftest verify -p npm/policy/js_lint/package_json
+package js_lint.package_json_test
+
+import rego.v1
+
+import data.js_lint.package_json
+
+canonical_lint_js := "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
+
+valid_pkg := {
+	"type": "module",
+	"scripts": {"lint-js": canonical_lint_js},
+	"engines": {"node": ">=24", "bun": ">=1.3"},
+	"devDependencies": {"@nitra/eslint-config": "^3.9.2"},
+}
+
+# ── happy path ────────────────────────────────────────────────────────────
+
+test_allow_canonical if {
+	count(package_json.deny) == 0 with input as valid_pkg
+}
+
+test_allow_workspace_eslint_config if {
+	pkg := json.patch(
+		valid_pkg,
+		[{"op": "replace", "path": "/devDependencies/@nitra~1eslint-config", "value": "workspace:*"}],
+	)
+	count(package_json.deny) == 0 with input as pkg
+}
+
+# ── lint-js ───────────────────────────────────────────────────────────────
+
+test_deny_missing_lint_js if {
+	pkg := json.patch(valid_pkg, [{"op": "remove", "path": "/scripts/lint-js"}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_deny_lint_js_without_knip if {
+	pkg := json.patch(
+		valid_pkg,
+		[{"op": "replace", "path": "/scripts/lint-js", "value": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd ."}],
+	)
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_deny_lint_js_without_no_config_hints if {
+	without_flag := "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip"
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/scripts/lint-js", "value": without_flag}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_deny_lint_js_wrong_order if {
+	wrong_order := "bunx eslint --fix . && bunx oxlint --fix && bunx jscpd . && bunx knip --no-config-hints"
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/scripts/lint-js", "value": wrong_order}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_allow_lint_js_with_extra_whitespace if {
+	pkg := json.patch(
+		valid_pkg,
+		[{"op": "replace", "path": "/scripts/lint-js", "value": concat("  ", ["", canonical_lint_js, ""])}],
+	)
+	count(package_json.deny) == 0 with input as pkg
+}
+
+# ── type: module ──────────────────────────────────────────────────────────
+
+test_deny_type_not_module if {
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/type", "value": "commonjs"}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_deny_type_missing if {
+	pkg := json.patch(valid_pkg, [{"op": "remove", "path": "/type"}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+# ── engines ──────────────────────────────────────────────────────────────
+
+test_deny_node_below_24 if {
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/engines/node", "value": ">=22"}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_allow_node_above_24 if {
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/engines/node", "value": ">=25"}])
+	count(package_json.deny) == 0 with input as pkg
+}
+
+test_deny_bun_below_1_3 if {
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/engines/bun", "value": ">=1.2"}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_allow_bun_2_x if {
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/engines/bun", "value": "^2.0.0"}])
+	count(package_json.deny) == 0 with input as pkg
+}
+
+# ── @nitra/eslint-config ─────────────────────────────────────────────────
+
+test_deny_eslint_config_below_3_9_2 if {
+	cases := [
+		"^3.9.1",
+		"^3.8.0",
+		"^3.6.12",
+		"^3.4.3",
+	]
+	some bad in cases
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/devDependencies/@nitra~1eslint-config", "value": bad}])
+	count(package_json.deny) > 0 with input as pkg
+}
+
+test_allow_eslint_config_above_3_9_2 if {
+	cases := [
+		"^3.9.2",
+		"^3.9.10",
+		"^3.10.0",
+		"^4.0.0",
+	]
+	some good in cases
+	pkg := json.patch(valid_pkg, [{"op": "replace", "path": "/devDependencies/@nitra~1eslint-config", "value": good}])
+	count(package_json.deny) == 0 with input as pkg
+}
+
+test_deny_missing_eslint_config if {
+	pkg := json.patch(valid_pkg, [{"op": "remove", "path": "/devDependencies/@nitra~1eslint-config"}])
+	count(package_json.deny) > 0 with input as pkg
+}

package/scripts/check-js-lint.mjs

@@ -12,7 +12,7 @@
  * `engines.bun` >= 1.3, `"type": "module"` у кореневому і всіх workspace `package.json`. Дубль перевірки JS у `lint.yml` — заборонено.
  */
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { copyFile, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -25,55 +25,18 @@ export const OXLINT_CANONICAL_JSON_PATH = join(
   'oxlint-canonical.json'
 )
 
-/** Очікуваний локальний скрипт. */
-export const CANONICAL_LINT_JS = 'bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip'
+/** Шлях до канонічного knip JSON у цьому пакеті — копіюється у корінь проєкту-споживача, якщо відсутній. */
+export const KNIP_CANONICAL_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), 'utils', 'knip-canonical.json')
 
 /** Мінімальні рекомендації розширень редактора з js-lint.mdc (eslint, oxlint, GA). */
 export const REQUIRED_VSCODE_EXTENSIONS = ['dbaeumer.vscode-eslint', 'github.vscode-github-actions', 'oxc.oxc-vscode']
 
-const WHITESPACE_RE = /\s+/gu
 const NON_DIGITS_RE = /\D+/u
 
-/**
- * Нормалізує рядок скрипта для порівняння (зайві пробіли).
- * @param {string} s вихідний рядок скрипта `lint-js`
- * @returns {string} рядок без зайвих пробілів на краях і з одиничними пробілами всередині
- */
-export function normalizeLintJsScript(s) {
-  return String(s).trim().replaceAll(WHITESPACE_RE, ' ')
-}
-
-/**
- * Чи рядок `lint-js` збігається з каноном (`bunx oxlint`, `bunx eslint`, `bunx jscpd`).
- * @param {string} script значення `scripts.lint-js` з package.json
- * @returns {boolean} true, якщо рядок канонічний
- */
-export function isCanonicalLintJs(script) {
-  return normalizeLintJsScript(script) === CANONICAL_LINT_JS
-}
-
-/**
- * Чи діапазон `@nitra/eslint-config` у `package.json` задовольняє мінімум `>= 3.9.2`
- * (заборона `for...in` через `no-restricted-syntax` з 3.8.0 + вбудований ignore для ADR-каталогів
- * у `getConfig` з 3.9.2 + транзитивний `@e18e/eslint-plugin` для oxlint).
- * @param {unknown} versionSpec значення `devDependencies['@nitra/eslint-config']`
- * @returns {boolean} true для `workspace:*` або першої semver у рядку >= 3.9.2
- */
-export function nitraEslintConfigMeetsMinVersion(versionSpec) {
-  const s = String(versionSpec).trim()
-  if (s.startsWith('workspace:')) {
-    return true
-  }
-  const parts = s.split(NON_DIGITS_RE).filter(Boolean)
-  if (parts.length < 3) {
-    return false
-  }
-  const [major, minor, patch] = parts.slice(0, 3).map(Number)
-  if ([major, minor, patch].some(n => Number.isNaN(n))) {
-    return false
-  }
-  return major > 3 || (major === 3 && (minor > 9 || (minor === 9 && patch >= 2)))
-}
+// Канонічний рядок `lint-js`-скрипта і мінімальна версія `@nitra/eslint-config` —
+// у rego (`npm/policy/js_lint/package_json/`). JS-копії (`CANONICAL_LINT_JS`,
+// `isCanonicalLintJs`, `nitraEslintConfigMeetsMinVersion`) видалено, щоб не
+// було двох джерел істини й ризику дрифту.
 
 /**
  * Рекурсивне порівняння фрагментів канону oxlint (масиви — порядок як у каноні; об’єкти — той самий набір ключів і вкладеність).
@@ -473,31 +436,28 @@ async function checkJscpdConfig(passFn, failFn) {
 }
 
 /**
- * Перевіряє `knip.json`: файл існує і `ignoreDependencies` містить `graphql`
- * (peer-залежність, що часто використовується без прямого імпорту — без цього
- * `knip` фолсово репортить її як unused).
+ * Перевіряє наявність `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 при помилці
  */
 async function checkKnipConfig(passFn, failFn) {
-  if (!existsSync('knip.json')) {
-    failFn('knip.json не існує — додай конфіг з ignoreDependencies: ["graphql"] (js-lint.mdc)')
+  if (existsSync('knip.json')) {
+    passFn('knip.json існує')
     return
   }
-  let cfg
-  try {
-    cfg = JSON.parse(await readFile('knip.json', 'utf8'))
-  } catch {
-    failFn('knip.json не є валідним JSON')
+  if (!existsSync(KNIP_CANONICAL_JSON_PATH)) {
+    failFn(
+      `knip.json відсутній, і канонічний шаблон у пакеті не знайдено (${KNIP_CANONICAL_JSON_PATH}) — ` +
+        'перевстанови @nitra/cursor'
+    )
     return
   }
-  passFn('knip.json існує')
-  const ignoreDeps = cfg?.ignoreDependencies
-  if (Array.isArray(ignoreDeps) && ignoreDeps.includes('graphql')) {
-    passFn('knip.json: ignoreDependencies містить "graphql"')
-  } else {
-    failFn('knip.json: ignoreDependencies має містити "graphql" (peer-залежність) (js-lint.mdc)')
-  }
+  await copyFile(KNIP_CANONICAL_JSON_PATH, 'knip.json')
+  passFn('knip.json створено з канонічного npm/scripts/utils/knip-canonical.json (js-lint.mdc)')
 }
 
 /**

package/scripts/utils/knip-canonical.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "eslint.config.{js,mjs,cjs}",
+    "stylelint.config.{js,cjs,mjs}",
+    "oxlint.config.{js,mjs}",
+    "jscpd.config.{js,mjs}",
+    "markdownlint-cli2.config.{js,mjs,cjs,jsonc}",
+    ".markdownlint-cli2.{jsonc,cjs,mjs}",
+    "commitlint.config.{js,cjs,mjs}"
+  ],
+  "project": ["**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}"],
+  "ignore": ["**/__fixtures__/**"],
+  "ignoreDependencies": ["@nitra/cspell-dict", "/@cspell\\/dict-.+/", "graphql"],
+  "ignoreBinaries": [
+    "actionlint",
+    "cspell",
+    "eslint",
+    "git-ai",
+    "jscpd",
+    "markdownlint-cli2",
+    "oxfmt",
+    "oxlint",
+    "shellcheck",
+    "uvx",
+    "v8r",
+    "zizmor"
+  ]
+}