@nitra/cursor 1.10.0 → 1.11.1

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,127 @@
+/**
+ * Оркестратор одного правила під CLI `check`.
+ *
+ * Послідовність (concerns у межах правила — алфавітно):
+ *   1. **applies-гейт** з `js/applies/check.mjs`. Якщо модуль експортує `applies()` і вона повертає
+ *      false — друкуємо `✅ правило не застосовне` і завершуємо без подальших викликів.
+ *   2. **JS-концерни** — кожен `check*.mjs` у `js/<concern>/`. Concern `applies` теж може мати
+ *      `check()` для друку контексту (його `applies()` уже відпрацював на кроці 1, він не повторюється).
+ *   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 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
+}