@nitra/cursor 1.13.2 → 1.13.11

package/rules/vue/fix/packages/check.mjs

@@ -1,8 +1,12 @@
 /**
  * Знаходить пакети з `vue` у dependencies і перевіряє їх за правилом vue.mdc.
  *
- * Версії Vite та плагінів, vue-macros, auto-import, layouts, вміст `vite.config`;
- * у репозиторії — рекомендацію розширення Vue.volar.
+ * Вміст `vite.config`, editor-файли для Vite client types, у репозиторії —
+ * рекомендацію розширення Vue.volar.
+ *
+ * Залежності Vue/Vite (`vite >= 8`, `@vitejs/plugin-vue`, `vue-macros`,
+ * `unplugin-auto-import`, `vite-plugin-vue-layouts-next`, заборона `esbuild`) —
+ * у policy `vue.package_json`.
  *
  * У кожному Vue+Vite-пакеті очікується `src/vite-env.d.ts` з `/// <reference types="vite/client" />`
  * та `jsconfig.json` у корені пакета (типи для імпортів асетів у `.vue`).
@@ -183,30 +187,6 @@ function ukFilesCountPhrase(n) {
   return `${n} файлів`
 }
 
-/**
- * Перевіряє наявність залежності в об'єкті deps.
- * @param {Record<string,string>} deps об'єкт залежностей
- * @param {string} name ім'я пакета
- * @param {string} prefix префікс повідомлення
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} fail callback при помилці
- * @param {string} hint підказка при відсутності
- */
-function checkRequiredDep(deps, name, prefix, passFn, fail, hint = `${name} відсутній`) {
-  if (deps[name]) {
-    passFn(`${prefix}${name}: ${deps[name]}`)
-  } else {
-    fail(`${prefix}${hint}`)
-  }
-}
-
-/**
- * Перевіряє версію vite у devDependencies.
- * @param {Record<string,string>} devDeps devDependencies з package.json
- * @param {string} prefix параметр prefix
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} fail callback при помилці
- */
 /**
  * Перевіряє `src/vite-env.d.ts` і наявність `jsconfig.json` для підтягування типів асетів Vite у IDE.
  * @param {string} rootDir відносний шлях до кореня пакета
@@ -433,44 +413,7 @@ async function checkVueImportViolations(rootDir, absPackageRoot, ignorePaths, ha
  */
 async function checkVuePackage(rootDir, ignorePaths, fail, passFn) {
   const prefix = `[${packageLabel(rootDir)}] `
-  const pkg = JSON.parse(await readFile(join(rootDir, 'package.json'), 'utf8'))
-  const deps = pkg.dependencies || {}
-  const devDeps = pkg.devDependencies || {}
-  const allDeps = { ...deps, ...devDeps }
-
-  if (allDeps.esbuild) {
-    fail(`${prefix}esbuild заборонено (знайдено: ${allDeps.esbuild}). Замінити на rolldown та прибрати esbuild.`)
-  }
-
-  checkRequiredDep(deps, 'vue', prefix, passFn, fail, 'vue відсутній в dependencies')
-  // `vite >= 8` перенесено в Rego (`npm/policy/vue/package_json/`); запуск
-  // через `npx @nitra/cursor check`. Залишені вимоги — present-/missing-deps
-  // (vue-macros, unplugin-auto-import, тощо) — у самому JS-чекері.
-  checkRequiredDep(
-    devDeps,
-    '@vitejs/plugin-vue',
-    prefix,
-    passFn,
-    fail,
-    '@vitejs/plugin-vue відсутній в devDependencies'
-  )
-  checkRequiredDep(allDeps, 'vue-macros', prefix, passFn, fail, 'vue-macros відсутній — bun add -d vue-macros')
-  checkRequiredDep(
-    allDeps,
-    'unplugin-auto-import',
-    prefix,
-    passFn,
-    fail,
-    'unplugin-auto-import відсутній — bun add -d unplugin-auto-import'
-  )
-  checkRequiredDep(
-    allDeps,
-    'vite-plugin-vue-layouts-next',
-    prefix,
-    passFn,
-    fail,
-    'vite-plugin-vue-layouts-next відсутній — bun add -d vite-plugin-vue-layouts-next'
-  )
+  passFn(`${prefix}package.json залежності перевіряє npx @nitra/cursor check → vue.package_json`)
 
   await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail)
 

package/rules/vue/policy/package_json/package_json.rego

@@ -5,8 +5,9 @@
 #   conftest test path/to/package.json -p npm/policy/vue \
 #     --namespace vue.package_json
 #
-# Перевіряє: якщо в `dependencies` є `vue`, то у `devDependencies.vite` має бути
-# мажорна версія ≥ 8.
+# Перевіряє: якщо в `dependencies` є `vue`, то потрібні канонічні Vue/Vite
+# залежності, `devDependencies.vite` має бути мажорної версії ≥ 8, а `esbuild`
+# у dependencies/devDependencies заборонений (міграція на rolldown).
 #
 # AST-сканування коду (заборона явних value-імпортів `from 'vue'`, заборона
 # Node-нативних модулів у `.vue` SFC, перевірка `vite.config` на
@@ -34,12 +35,54 @@ deny contains msg if {
 	msg := sprintf("Vue-пакет: vite має бути >= 8 (зараз %q) (vue.mdc)", [vite_range])
 }
 
+deny contains msg if {
+	uses_vue
+	not "@vitejs/plugin-vue" in dev_dependency_names
+	msg := "Vue-пакет: @vitejs/plugin-vue відсутній у devDependencies (vue.mdc)"
+}
+
+deny contains msg if {
+	uses_vue
+	not "vue-macros" in all_dependency_names
+	msg := "Vue-пакет: vue-macros відсутній (vue.mdc)"
+}
+
+deny contains msg if {
+	uses_vue
+	not "unplugin-auto-import" in all_dependency_names
+	msg := "Vue-пакет: unplugin-auto-import відсутній (vue.mdc)"
+}
+
+deny contains msg if {
+	uses_vue
+	not "vite-plugin-vue-layouts-next" in all_dependency_names
+	msg := "Vue-пакет: vite-plugin-vue-layouts-next відсутній (vue.mdc)"
+}
+
+deny contains msg if {
+	uses_vue
+	"esbuild" in all_dependency_names
+	msg := "Vue-пакет: esbuild заборонено — заміни на rolldown і прибери залежність (vue.mdc)"
+}
+
 # ── helpers ────────────────────────────────────────────────────────────────
 
 uses_vue if {
 	"vue" in object.keys(object.get(input, "dependencies", {}))
 }
 
+dependency_names := {n | some n in object.keys(object.get(input, "dependencies", {}))}
+
+dev_dependency_names := {n | some n in object.keys(object.get(input, "devDependencies", {}))}
+
+all_dependency_names contains n if {
+	some n in dependency_names
+}
+
+all_dependency_names contains n if {
+	some n in dev_dependency_names
+}
+
 vite_in_dev_dependencies if {
 	"vite" in object.keys(object.get(input, "devDependencies", {}))
 }

package/rules/vue/vue.mdc

@@ -1,6 +1,6 @@
 ---
 description: Vue
-version: '1.8'
+version: '1.9'
 globs: "**/*.vue"
 alwaysApply: false
 ---
@@ -104,7 +104,20 @@ const additionalInstructions = `
 
 ### Тестування
 
-- **Unit / component:** **Vue Test Utils**; з **Vite** зручно **Vitest**.
+- **Unit:** **Bun Test Runner** (`bun test`) — використовуй його замість **Vitest**. API сумісне (`describe` / `it` / `expect` з `bun:test`), моки через `mock` і `mock.module`. У `package.json` тримай `"test": "bun test <шляхи>"`; не додавай `vitest`, `vitest.config.*` і пов’язані залежності.
+- **Component / DOM:** **Vue Test Utils** + **Bun Test Runner** з **happy-dom** як DOM-середовищем. Підключення — через `@happy-dom/global-registrator` у preload-файлі та `bunfig.toml`:
+
+```toml title="bunfig.toml"
+[test]
+preload = ["./test/happy-dom.preload.js"]
+```
+
+```js title="test/happy-dom.preload.js"
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+GlobalRegistrator.register()
+```
+
+`jsdom` не використовуй — happy-dom швидший і достатній для типових Vue-компонентних тестів.
 - **E2E:** **Playwright** змістовні сценарії користувацьких потоків.
 
 ### Інструменти (узгоджено з Vite і цим правилом)

package/scripts/ensure-nitra-cursor-dev-dependencies.mjs

@@ -1,10 +1,11 @@
 /**
- * Дописує `\@nitra/cursor` у `devDependencies` кореневого `package.json` проєкту, якщо пакет ще не
- * оголошено ні в `devDependencies`, ні в `dependencies`.
+ * Дописує `\@nitra/cursor` у `devDependencies` workspace-root `package.json` проєкту, якщо пакет ще
+ * не оголошено ні в `devDependencies`, ні в `dependencies`.
  *
  * Використовується CLI `n-cursor` при кожному запуску (`npx \@nitra/cursor`, зокрема `check`), щоб
  * команда `check` і скрипти з `node_modules/\@nitra/cursor/scripts/` були відтворювані після
- * `bun install` / `npm install`, а не лише з кешу npx.
+ * `bun install` / `npm install`, а не лише з кешу npx. Корінь визначається тільки за наявністю поля
+ * `workspaces` у `package.json` поруч із поточною директорією запуску.
  *
  * Версія діапазону: `^<version>` з поля `version` установленого пакету `\@nitra/cursor`.
  */
@@ -37,36 +38,55 @@ export async function readBundledPackageVersion() {
 }
 
 /**
- * Якщо в `root/package.json` немає `\@nitra/cursor` у `devDependencies` і `dependencies`, дописує
- * `devDependencies["\@nitra/cursor"]` зі значенням `^<bundledVersion>`.
- * @param {string} root абсолютний шлях кореня проєкту (зазвичай `process.cwd()`)
- * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
- *   `silent` — не писати в консоль при успішному оновленні
- * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ * Читає JSON-обʼєкт із диска.
+ * @param {string} path шлях до JSON-файлу
+ * @returns {Promise<Record<string, unknown> | null>} обʼєкт або `null`, якщо файл нечитабельний
  */
-export async function ensureNitraCursorInRootDevDependencies(root, options = {}) {
-  const pkgPath = join(root, 'package.json')
-  if (!existsSync(pkgPath)) {
-    return false
-  }
-
+async function readJsonObject(path) {
   let raw
   try {
-    raw = await readFile(pkgPath, 'utf8')
+    raw = await readFile(path, 'utf8')
   } catch {
-    return false
+    return null
   }
 
-  let pkg
   try {
-    pkg = JSON.parse(raw)
+    const value = JSON.parse(raw)
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
   } catch {
-    return false
+    return null
   }
+}
 
-  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+/**
+ * Читає `package.json` поруч зі стартовою директорією, якщо це workspace-root.
+ * @param {string} startDir директорія, з якої запущено CLI
+ * @returns {Promise<{ path: string, pkg: Record<string, unknown> } | null>} workspace-root package або `null`
+ */
+async function readAdjacentWorkspaceRootPackageJson(startDir) {
+  const pkgPath = join(startDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return null
+  }
+
+  const pkg = await readJsonObject(pkgPath)
+  return pkg && Object.hasOwn(pkg, 'workspaces') ? { path: pkgPath, pkg } : null
+}
+
+/**
+ * Якщо у workspace-root `package.json` немає `\@nitra/cursor` у `devDependencies` і `dependencies`,
+ * дописує `devDependencies["\@nitra/cursor"]` зі значенням `^<bundledVersion>`.
+ * @param {string} root стартова директорія проєкту (зазвичай `process.cwd()`)
+ * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
+ *   `silent` — не писати в консоль при успішному оновленні
+ * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ */
+export async function ensureNitraCursorInRootDevDependencies(root, options = {}) {
+  const workspaceRoot = await readAdjacentWorkspaceRootPackageJson(root)
+  if (!workspaceRoot) {
     return false
   }
+  const { path: pkgPath, pkg } = workspaceRoot
 
   const devDeps = pkg.devDependencies
   const deps = pkg.dependencies

package/scripts/utils/check-mdc-template-refs.mjs

@@ -0,0 +1,47 @@
+/**
+ * Returns list of template/ files that are NOT referenced in <id>.mdc as
+ * markdown link targets. Paths returned are relative to ruleDir.
+ *
+ * @param {string} ruleDir absolute path to npm/rules/<id>/
+ * @param {string} ruleId basename (e.g. "security")
+ * @returns {Promise<string[]>}
+ */
+import { existsSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+async function walkTemplateDirs(ruleDir) {
+  const out = []
+  for (const kind of ['fix', 'policy']) {
+    const kindDir = join(ruleDir, kind)
+    if (!existsSync(kindDir)) continue
+    for (const concern of await readdir(kindDir)) {
+      const tpl = join(kindDir, concern, 'template')
+      if (!existsSync(tpl)) continue
+      if (!(await stat(tpl)).isDirectory()) continue
+      out.push(...(await collectFiles(tpl)))
+    }
+  }
+  return out.map(p => relative(ruleDir, p))
+}
+
+async function collectFiles(dir) {
+  const out = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...(await collectFiles(full)))
+    else out.push(full)
+  }
+  return out
+}
+
+export async function findMissingMdcRefs(ruleDir, ruleId) {
+  const mdcPath = join(ruleDir, `${ruleId}.mdc`)
+  if (!existsSync(mdcPath)) return []
+  const mdc = await readFile(mdcPath, 'utf8')
+  const allFiles = await walkTemplateDirs(ruleDir)
+  return allFiles.filter(rel => {
+    // Match markdown link to ./<rel> or (<rel>) anywhere in the .mdc
+    return !mdc.includes(`./${rel}`) && !mdc.includes(`(${rel})`)
+  })
+}

package/scripts/utils/inline-template-links.mjs

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+
+const TEMPLATE_LINK_RE = /\[([^\]]+)\]\((\.\/[^)]*\/template\/[^)]+)\)/g
+const SLOTS = ['snippet', 'deny', 'contains']
+
+/** @param {string} filePath */
+function langFromExt(filePath) {
+  const ext = extname(filePath)
+  if (ext === '.json') return 'json'
+  if (ext === '.toml') return 'toml'
+  if (ext === '.yml' || ext === '.yaml') return 'yaml'
+  return ''
+}
+
+// Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the
+// real target file name (e.g. `package.json.snippet.json` → `package.json`).
+/** @param {string} fileBasename */
+function normalizeTargetName(fileBasename) {
+  for (const slot of SLOTS) {
+    const m = fileBasename.match(new RegExp(`^(.+)\\.${slot}\\.[^.]+$`))
+    if (m) return m[1]
+  }
+  return fileBasename
+}
+
+/**
+ * Finds markdown links whose path contains /template/ and replaces them with
+ * inline fenced blocks. Reads file from join(ruleDir, rel-path).
+ * Throws Error if a matched link target doesn't exist (fail loud — user must know).
+ *
+ * @param {string} text .mdc file contents
+ * @param {string} ruleDir absolute path to the rule directory (e.g. .../npm/rules/security/)
+ * @returns {Promise<string>} transformed text
+ */
+export async function inlineTemplateLinks(text, ruleDir) {
+  const matches = [...text.matchAll(TEMPLATE_LINK_RE)]
+  if (matches.length === 0) return text
+
+  let result = text
+  for (const match of matches) {
+    const [fullMatch, , href] = match
+    // href starts with ./ and contains /template/ — already guaranteed by regex
+    const relPath = href.slice(2) // strip leading ./
+    const absPath = join(ruleDir, relPath)
+
+    if (!existsSync(absPath)) {
+      throw new Error(`inlineTemplateLinks: file not found: ${absPath} (referenced from .mdc)`)
+    }
+
+    const contents = (await readFile(absPath, 'utf8')).trim()
+    const lang = langFromExt(absPath)
+    const targetName = normalizeTargetName(basename(absPath))
+    const replacement = `\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``
+    result = result.replace(fullMatch, () => replacement)
+  }
+
+  return result
+}

package/scripts/utils/run-conftest-batch.mjs

@@ -15,7 +15,8 @@
  * робить для opa/regal).
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -57,8 +58,30 @@ function failConftestMissing() {
  * @property {string} namespace повне імʼя rego-пакета (наприклад `abie.base_deployment_preem`)
  * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
  * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
+ * @property {object} [templateData] опціональне merged-дерево; серіалізується у JSON `{ "template": <data> }` і передається як `--data <tmpfile>` (cleanup після завершення)
  */
 
+/**
+ * Pure args builder for conftest test. Extracted for unit-testability.
+ * Preserves the existing args layout (files before -p; --output json --no-color
+ * for parseable output); inserts --data right after --namespace when provided.
+ * @param {{ policyAbs: string, namespace: string, files: string[], extraArgs: string[], tmpDataFile: string|null }} p
+ * @returns {string[]}
+ */
+export function buildConftestArgs(p) {
+  const args = [
+    'test',
+    ...p.files,
+    '-p',
+    p.policyAbs,
+    '--namespace',
+    p.namespace
+  ]
+  if (p.tmpDataFile) args.push('--data', p.tmpDataFile)
+  args.push('--output', 'json', '--no-color', ...p.extraArgs)
+  return args
+}
+
 /**
  * Виконує `conftest test` для всіх файлів одним спавном і повертає масив
  * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
@@ -81,40 +104,44 @@ export function runConftestBatch(opts) {
   if (!existsSync(policyAbs)) {
     throw new Error(`runConftestBatch: rego-каталог не знайдено: ${policyAbs}`)
   }
-  const args = [
-    'test',
-    ...opts.files,
-    '-p',
-    policyAbs,
-    '--namespace',
-    opts.namespace,
-    '--output',
-    'json',
-    '--no-color',
-    ...(opts.extraArgs ?? [])
-  ]
-  const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
-  if (result.error) {
-    throw result.error
+  let tmpDataDir = null
+  let tmpDataFile = null
+  if (opts.templateData) {
+    tmpDataDir = mkdtempSync(join(tmpdir(), 'n-cursor-tpl-'))
+    tmpDataFile = join(tmpDataDir, 'template-data.json')
+    writeFileSync(tmpDataFile, JSON.stringify({ template: opts.templateData }))
   }
-  // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
-  if (result.status !== 0 && result.status !== 1) {
-    throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
-  }
-  /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
-  let parsed
   try {
-    parsed = JSON.parse(result.stdout)
-  } catch {
-    throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
-  }
-  /** @type {ConftestViolation[]} */
-  const out = []
-  for (const entry of parsed) {
-    const failures = entry.failures ?? []
-    for (const f of failures) {
-      out.push({ filename: entry.filename, namespace: entry.namespace, message: f.msg })
+    const args = buildConftestArgs({
+      policyAbs,
+      namespace: opts.namespace,
+      files: opts.files,
+      extraArgs: opts.extraArgs ?? [],
+      tmpDataFile
+    })
+    const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
+    if (result.error) throw result.error
+    // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
+    if (result.status !== 0 && result.status !== 1) {
+      throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
+    }
+    /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
+    let parsed
+    try {
+      parsed = JSON.parse(result.stdout)
+    } catch {
+      throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
+    }
+    /** @type {ConftestViolation[]} */
+    const out = []
+    for (const entry of parsed) {
+      const failures = entry.failures ?? []
+      for (const f of failures) {
+        out.push({ filename: entry.filename, namespace: entry.namespace, message: f.msg })
+      }
     }
+    return out
+  } finally {
+    if (tmpDataDir) rmSync(tmpDataDir, { recursive: true, force: true })
   }
-  return out
 }

package/scripts/utils/run-rule.mjs

@@ -15,9 +15,11 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
+import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
 import { createCheckReporter } from './check-reporter.mjs'
 import { resolveTargetFiles } from './resolve-target-files.mjs'
 import { runConftestBatch } from './run-conftest-batch.mjs'
+import { resolveConcernTemplateData } from './template.mjs'
 
 const APPLIES_CONCERN_NAME = 'applies'
 
@@ -80,10 +82,13 @@ async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache)
   // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
   // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
   const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
+  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
+  const templateData = await resolveConcernTemplateData(concernAbsDir, target)
   const violations = runConftestBatch({
     policyDirRel: `${ruleId}/${concernName}`,
     namespace: regoNamespace,
-    files
+    files,
+    templateData
   })
   if (violations.length === 0) {
     reporter.pass(`${concernName}: ${files.length} файл(ів) OK (rego)`)
@@ -127,5 +132,15 @@ export async function runRule(rule, bundledRulesDir, walkCache) {
     if (code !== 0) totalCode = 1
   }
 
+  const ruleDir = join(bundledRulesDir, rule.id)
+  const missing = await findMissingMdcRefs(ruleDir, rule.id)
+  if (missing.length > 0) {
+    const reporter = createCheckReporter()
+    for (const rel of missing) {
+      reporter.fail(`${rule.id}.mdc: відсутнє markdown-посилання на template-файл ${rel}`)
+    }
+    if (reporter.getExitCode() !== 0) totalCode = 1
+  }
+
   return totalCode
 }