@nitra/cursor 1.10.0 → 1.11.0

package/scripts/utils/discover-checkable-rules.mjs

@@ -0,0 +1,123 @@
+/**
+ * Discovery rules для CLI `check`. Шукає правила, для яких є щось «прогонне»:
+ *   - JS concerns:   `rules/<id>/js/<concern>/<check.mjs | check-*.mjs>` — кожен concern окремий вузол.
+ *   - Policy concerns: `rules/<id>/policy/<concern>/target.json` — пара з `<concern>.rego`.
+ *   - Legacy JS (на час міграції): `rules/<id>/js/check.mjs` (плаский) — мапиться у concern `legacy`,
+ *     щоб не ламати ще не мігровані правила.
+ *
+ * Каталог `utils/` всередині `js/` свідомо пропускається — це хелпери, не концерни.
+ * Файли `*.test.mjs` фільтруються regex (`^check(?:-.+)?\.mjs$`).
+ *
+ * Намеренно НЕ парсимо `target.json` тут (це робить runner). Discovery — швидкий скан структури:
+ * шляхи + назви, без I/O вмісту.
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const CHECK_FILENAME_RE = /^check(?:-.+)?\.mjs$/u
+const TEST_SUFFIX = '.test.mjs'
+
+/**
+ * @typedef {object} JsConcern
+ * @property {string} name імʼя концерну (`<name>` у `js/<name>/`); для legacy — `'legacy'`
+ * @property {string[]} files імена `check*.mjs` у концерні (відсортовані алфавітно)
+ * @property {boolean} legacy чи це fallback на плаский `js/check.mjs`
+ */
+
+/**
+ * @typedef {object} PolicyConcern
+ * @property {string} name імʼя концерну (`<name>` у `policy/<name>/`)
+ */
+
+/**
+ * @typedef {object} CheckableRule
+ * @property {string} id ідентифікатор правила (імʼя каталогу `rules/<id>/`)
+ * @property {JsConcern[]} jsConcerns
+ * @property {PolicyConcern[]} policyConcerns
+ */
+
+/**
+ * Перелічує JS-концерни одного правила: підкаталоги `js/<name>/` з принаймні одним `check*.mjs`,
+ * плюс legacy-fallback на плаский `js/check.mjs` (без підкаталогу).
+ *
+ * `js/utils/` свідомо пропускається — це хелпери, а не концерни.
+ * @param {string} jsDir абсолютний шлях `rules/<id>/js/`
+ * @returns {Promise<JsConcern[]>} концерни в алфавітному порядку
+ */
+async function listJsConcerns(jsDir) {
+  if (!existsSync(jsDir)) return []
+  const topLevel = await readdir(jsDir, { withFileTypes: true })
+
+  // Перевага — нова concern-структура (`js/<concern>/check*.mjs`).
+  /** @type {JsConcern[]} */
+  const concerns = []
+  for (const entry of topLevel) {
+    if (!entry.isDirectory() || entry.name === 'utils' || entry.name.startsWith('.')) continue
+    const concernDir = join(jsDir, entry.name)
+    const files = (await readdir(concernDir))
+      .filter(n => CHECK_FILENAME_RE.test(n) && !n.endsWith(TEST_SUFFIX))
+      .toSorted((a, b) => a.localeCompare(b))
+    if (files.length > 0) {
+      concerns.push({ name: entry.name, files, legacy: false })
+    }
+  }
+
+  // Legacy fallback — лише якщо subdir-концернів немає взагалі. Гібридні правила
+  // (одночасно legacy check.mjs + нові концерни) трактуються як уже мігровані:
+  // CLI запускає тільки субдиректорні концерни, flat-файл лишається для backward-compat
+  // тестів, які імпортують `check` напряму.
+  if (concerns.length === 0) {
+    const flatChecks = topLevel
+      .filter(e => e.isFile() && CHECK_FILENAME_RE.test(e.name) && !e.name.endsWith(TEST_SUFFIX))
+      .map(e => e.name)
+      .toSorted((a, b) => a.localeCompare(b))
+    if (flatChecks.length > 0) {
+      concerns.push({ name: 'legacy', files: flatChecks, legacy: true })
+    }
+  }
+
+  return concerns.toSorted((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Перелічує policy-концерни: підкаталоги `policy/<name>/` з наявним `target.json`.
+ * @param {string} policyDir абсолютний шлях `rules/<id>/policy/`
+ * @returns {Promise<PolicyConcern[]>} концерни в алфавітному порядку
+ */
+async function listPolicyConcerns(policyDir) {
+  if (!existsSync(policyDir)) return []
+  const entries = await readdir(policyDir, { withFileTypes: true })
+  /** @type {PolicyConcern[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    if (existsSync(join(policyDir, entry.name, 'target.json'))) {
+      out.push({ name: entry.name })
+    }
+  }
+  return out.toSorted((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Сканує `rules/` і повертає правила, для яких є JS-концерни або policy-концерни.
+ * Правила без жодної прогонної частини (тільки `.mdc` + `auto.md`) фільтруються.
+ * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
+ * @returns {Promise<CheckableRule[]>} відсортовані за id
+ */
+export async function discoverCheckableRules(bundledRulesDir) {
+  if (!existsSync(bundledRulesDir)) return []
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  /** @type {CheckableRule[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const ruleDir = join(bundledRulesDir, entry.name)
+    const jsConcerns = await listJsConcerns(join(ruleDir, 'js'))
+    const policyConcerns = await listPolicyConcerns(join(ruleDir, 'policy'))
+    if (jsConcerns.length > 0 || policyConcerns.length > 0) {
+      out.push({ id: entry.name, jsConcerns, policyConcerns })
+    }
+  }
+  return out.toSorted((a, b) => a.id.localeCompare(b.id))
+}

package/scripts/utils/resolve-target-files.mjs

@@ -0,0 +1,109 @@
+/**
+ * Резолвер списку файлів для одного `policy/<name>/target.json` у новій структурі правил.
+ *
+ * Дві форми у `target.json:files`:
+ *   - `{ "single": "<rel>" }` — конкретний відносний шлях. Якщо `existsSync(root/single)` → `[single]`;
+ *     інакше `[]` (caller сам вирішує fail vs silent skip за `required`).
+ *   - `{ "walkGlob": <glob | glob[]> }` — picomatch проти posix-відносних шляхів, отриманих обходом
+ *     `walkDir` від `root` із загальними skip-ами та `.n-cursor.json:ignore`. Обхід кешований у
+ *     `walkCache` (Map ключ — підпис ignorePaths) — повторні таргети з тим самим набором ignore
+ *     перевикористовують список без нового readdir.
+ *
+ * Path-traversal у `single` — кидаємо помилку при resolve. Реалізує інваріант контракту: полісі
+ * читають лише файли в репо.
+ */
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, normalize, relative, sep } from 'node:path'
+
+import picomatch from 'picomatch'
+
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+import { walkDir } from './walkDir.mjs'
+
+/** Узгоджений regex для path-traversal: `..` як сегмент або абсолютний шлях. */
+const PARENT_SEGMENT_RE = /(^|[\\/])\.\.([\\/]|$)/u
+
+/**
+ * Перевіряє, що `single`-шлях у `target.json:files` лежить у межах репозиторію.
+ * Кидає помилку, якщо шлях абсолютний або містить сегмент `..`.
+ * @param {string} singlePath значення `files.single`
+ * @returns {void}
+ */
+function assertSafeSinglePath(singlePath) {
+  if (isAbsolute(singlePath)) {
+    throw new Error(`target.json: files.single має бути відносним шляхом (отримано: ${singlePath})`)
+  }
+  if (PARENT_SEGMENT_RE.test(singlePath)) {
+    throw new Error(`target.json: files.single не може містити '..' (отримано: ${singlePath})`)
+  }
+}
+
+/**
+ * Збирає всі файли (posix-відносні шляхи від `root`) одним обходом дерева.
+ * Скіпи: загальні з `walkDir` + `.n-cursor.json:ignore`.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+async function walkAllRelative(root, ignorePaths) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(
+    root,
+    abs => {
+      const rel = relative(root, abs).split(sep).join('/')
+      if (rel.length > 0) out.push(rel)
+    },
+    ignorePaths
+  )
+  return out.toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Витягує (або обчислює і кешує) список усіх файлів у дереві для заданого набору ignore-шляхів.
+ * Кеш — мapа `signature → Promise<string[]>`, тож паралельні виклики одного й того ж набору
+ * чекають один обхід.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @param {Map<string, Promise<string[]>>} walkCache мутабельний кеш від caller-а
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+function getAllFilesCached(root, ignorePaths, walkCache) {
+  const signature = `${root}|${ignorePaths.join('|')}`
+  let p = walkCache.get(signature)
+  if (!p) {
+    p = walkAllRelative(root, ignorePaths)
+    walkCache.set(signature, p)
+  }
+  return p
+}
+
+/**
+ * Резолвить список файлів для одного `target.json:files`.
+ * @param {object} filesSpec поле `files` з `target.json` (вже після schema-валідації)
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {Map<string, Promise<string[]>>} walkCache кеш обходів дерева (cross-target у межах одного check-прогону)
+ * @returns {Promise<string[]>} абсолютні шляхи знайдених файлів (порожній — нічого не знайдено)
+ */
+export async function resolveTargetFiles(filesSpec, root, walkCache) {
+  if (typeof filesSpec?.single === 'string') {
+    assertSafeSinglePath(filesSpec.single)
+    const normalized = normalize(filesSpec.single).split(sep).join('/')
+    const abs = join(root, normalized)
+    return existsSync(abs) ? [abs] : []
+  }
+  if (filesSpec?.walkGlob !== undefined) {
+    const ignorePaths = await loadCursorIgnorePaths(root)
+    const all = await getAllFilesCached(root, ignorePaths, walkCache)
+    const globs = Array.isArray(filesSpec.walkGlob) ? filesSpec.walkGlob : [filesSpec.walkGlob]
+    // picomatch у масиві трактує `!neg` як ОКРЕМИЙ позитивний матчер «не-neg» (some-OR логіка),
+    // тож наївне `picomatch(['pos','!neg'])` повертає true майже на всьому. Розділяємо вручну:
+    // позитиви join-имо через picomatch(...), негативні фільтруємо окремим isExcluded.
+    const positives = globs.filter(g => !g.startsWith('!'))
+    const negatives = globs.filter(g => g.startsWith('!')).map(g => g.slice(1))
+    const isMatch = positives.length > 0 ? picomatch(positives, { dot: false }) : () => false
+    const isExcluded = negatives.length > 0 ? picomatch(negatives, { dot: false }) : () => false
+    return all.filter(rel => isMatch(rel) && !isExcluded(rel)).map(rel => join(root, rel))
+  }
+  throw new Error(`target.json: files має містити single або walkGlob (отримано: ${JSON.stringify(filesSpec)})`)
+}

package/scripts/utils/run-rule.mjs

@@ -0,0 +1,131 @@
+/**
+ * Оркестратор одного правила під CLI `check`.
+ *
+ * Послідовність (concerns у межах правила — алфавітно):
+ *   1. **applies-гейт** з `js/applies/check.mjs`. Якщо модуль експортує `applies()` і вона повертає
+ *      false — друкуємо `✅ правило не застосовне` і завершуємо без подальших викликів.
+ *   2. **JS-концерни** — кожен `check*.mjs` у `js/<concern>/`. Concern `applies` теж може мати
+ *      `check()` для друку контексту (його `applies()` уже відпрацював на кроці 1, він не повторюється).
+ *      Legacy-fallback: плаский `js/check.mjs` лежить як concern `legacy` — імпортується з кореня `js/`,
+ *      а не з підкаталога.
+ *   3. **Policy-концерни** — кожен `policy/<concern>/target.json` через `runConftestBatch`.
+ *      Реcолвер `resolveTargetFiles` ділить cache (`walkCache`) між концернами.
+ *
+ * Кожен concern має власний `createCheckReporter` — їхні exit-коди OR-яться в один на рівні правила.
+ * Це дає той самий 0/1 контракт, що й попередня модель «один check.mjs на правило».
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createCheckReporter } from './check-reporter.mjs'
+import { resolveTargetFiles } from './resolve-target-files.mjs'
+import { runConftestBatch } from './run-conftest-batch.mjs'
+
+const APPLIES_CONCERN_NAME = 'applies'
+
+/**
+ * Обчислює абсолютний шлях до файла-check у JS-концерні.
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {string} ruleId id правила
+ * @param {import('./discover-checkable-rules.mjs').JsConcern} concern опис концерну
+ * @param {string} fileName імʼя файла з `concern.files`
+ * @returns {string} абсолютний шлях
+ */
+function resolveJsCheckPath(bundledRulesDir, ruleId, concern, fileName) {
+  return concern.legacy
+    ? join(bundledRulesDir, ruleId, 'js', fileName)
+    : join(bundledRulesDir, ruleId, 'js', concern.name, fileName)
+}
+
+/**
+ * Спробувати викликати applies() гейт з `js/applies/check.mjs` правила.
+ * Гейт активний лише за наявності концерну з імʼям `applies` і експортом-функцією `applies` у його
+ * першому check-файлі (алфавіт).
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {import('./discover-checkable-rules.mjs').CheckableRule} rule опис правила
+ * @returns {Promise<boolean>} `true` — правило застосовне (або гейту немає); `false` — пропустити
+ */
+async function evaluateAppliesGate(bundledRulesDir, rule) {
+  const concern = rule.jsConcerns.find(c => c.name === APPLIES_CONCERN_NAME)
+  if (!concern || concern.files.length === 0) return true
+  const path = resolveJsCheckPath(bundledRulesDir, rule.id, concern, concern.files[0])
+  const mod = await import(path)
+  if (typeof mod.applies !== 'function') return true
+  return Boolean(await mod.applies())
+}
+
+/**
+ * Запускає одну policy-полісі через `runConftestBatch`. Створює локальний репортер,
+ * читає `target.json`, резолвить файли, фіксує fail/pass — і повертає exit-код.
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {string} ruleId id правила
+ * @param {string} concernName імʼя полісі (= підкаталог у `policy/`)
+ * @param {Map<string, Promise<string[]>>} walkCache shared cache між концернами одного check-прогону
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення
+ */
+async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache) {
+  const reporter = createCheckReporter()
+  const targetPath = join(bundledRulesDir, ruleId, 'policy', concernName, 'target.json')
+  /** @type {{ files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
+  const target = JSON.parse(await readFile(targetPath, 'utf8'))
+  const files = await resolveTargetFiles(target.files, process.cwd(), walkCache)
+  if (files.length === 0) {
+    if (target.files.required && target.files.single) {
+      const msg =
+        target.missingMessage ?? `${target.files.single} не існує — створи згідно ${ruleId}.mdc (${ruleId}.${concernName})`
+      reporter.fail(msg)
+    }
+    return reporter.getExitCode()
+  }
+  // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
+  // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
+  const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
+  const violations = runConftestBatch({
+    policyDirRel: `${ruleId}/${concernName}`,
+    namespace: regoNamespace,
+    files
+  })
+  if (violations.length === 0) {
+    reporter.pass(`${concernName}: ${files.length} файл(ів) OK (rego)`)
+  } else {
+    for (const v of violations) reporter.fail(v.message)
+  }
+  return reporter.getExitCode()
+}
+
+/**
+ * Запускає одне правило: applies-гейт → JS-концерни → policy-концерни.
+ * @param {import('./discover-checkable-rules.mjs').CheckableRule} rule
+ * @param {string} bundledRulesDir абсолютний шлях до `rules/`
+ * @param {Map<string, Promise<string[]>>} walkCache shared cache (один на check-прогон)
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення в одному чи більше концернів
+ */
+export async function runRule(rule, bundledRulesDir, walkCache) {
+  console.log(`📋 ${rule.id}:`)
+
+  if (!(await evaluateAppliesGate(bundledRulesDir, rule))) {
+    console.log(`  ✅ Правило ${rule.id} не застосовне до цього репо — пропущено`)
+    return 0
+  }
+
+  let totalCode = 0
+
+  for (const concern of rule.jsConcerns) {
+    for (const fileName of concern.files) {
+      const path = resolveJsCheckPath(bundledRulesDir, rule.id, concern, fileName)
+      // eslint-disable-next-line no-unsanitized/method -- path будується з discovered concern/file, які пройшли regex CHECK_FILENAME_RE
+      const mod = await import(path)
+      if (typeof mod.check === 'function') {
+        const code = await mod.check()
+        if (code !== 0) totalCode = 1
+      }
+    }
+  }
+
+  for (const policyConcern of rule.policyConcerns) {
+    const code = await runPolicyConcern(bundledRulesDir, rule.id, policyConcern.name, walkCache)
+    if (code !== 0) totalCode = 1
+  }
+
+  return totalCode
+}