@nitra/cursor 10.0.1 → 10.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [10.1.0] - 2026-06-15
+
+### Changed
+
+- Конформність-селекція: .n-cursor.json — єдине джерело правди. resolveCheckRuleIds бере активні правила прямо з конфіга (available ∩ enabled), .cursor/rules/*.mdc лишається лише fallback'ом коли конфіга нема. Прибрано дрейф «правило enabled, але .mdc нема → тихо пропущено». Per-rule whitelist-гейт у runRuleCli видалено як дубль — гейтинг живе виключно у селекції.
+
 ## [10.0.1] - 2026-06-14
 
 ### Changed

package/package.json

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

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * docgen-judge-measure.mjs — Q4 офлайн-вимірювач (spec 2026-06-14-docgen-judge-design).
+ *
+ * Міряє false-positive rate детермінованого `scoreDoc`: серед доків, що ПРОЙШЛИ
+ * (score ≥ threshold), який % сильна хмарна модель-суддя класифікує як
+ * `generic`/`inaccurate`. Це число вирішує, чи будувати рантайм-judge-гейт.
+ *
+ * Генерація: локальна (N_LOCAL_MIN_MODEL, omlx/* → прямий HTTP) — реальний пайплайн.
+ * Суддя: openai-codex/gpt-5.4-mini (сильніша хмара, ніж генератор — інакше вимір беззмістовний).
+ * Обидва — через існуючий `../../../lib/llm.mjs callLlm` (маршрутизація за префіксом).
+ *
+ * Кеш на диску (за хешем контенту) → повторні прогони не регенерують і не пересуджують.
+ *
+ * Usage:
+ *   node docgen-judge-measure.mjs <file1> <file2> ...
+ *   MEASURE_CACHE=/tmp/x N_CURSOR_DOCGEN_JUDGE_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { generateDoc } from './docgen-gen.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
+import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+
+const env = process.env
+const GEN_MODEL = env.N_LOCAL_MIN_MODEL ?? 'omlx/gemma-4-e4b-it-OptiQ-4bit'
+const JUDGE_MODEL = env.N_CURSOR_DOCGEN_JUDGE_MODEL ?? 'openai-codex/gpt-5.4-mini'
+const THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? QUALITY_THRESHOLD) || 70
+const CACHE_DIR = env.MEASURE_CACHE ?? '/tmp/docgen-judge-measure'
+const JUDGE_TIMEOUT = Number(env.MEASURE_JUDGE_TIMEOUT_MS ?? 120_000)
+
+const SYSTEM = `You are a strict technical-documentation reviewer. You receive a SOURCE file and an auto-generated Markdown DOC describing it. Classify the DOC into exactly one verdict:
+- "accurate": specific to THIS file AND every factual claim is supported by the source.
+- "generic": could describe almost any file of this kind; vague/boilerplate; lacks file-specific substance.
+- "inaccurate": contains at least one claim that is NOT supported by, or is contradicted by, the source code.
+Prefer "inaccurate" over "generic" if any claim is wrong. Respond with ONLY a JSON object, no prose:
+{"verdict":"accurate|generic|inaccurate","confidence":0.0-1.0,"reason":"<20-300 chars>","offending":["<short quote from doc>"]}`
+
+const sha = s => createHash('sha256').update(s).digest('hex').slice(0, 16)
+
+function cacheGet(key) {
+  const p = join(CACHE_DIR, key + '.json')
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null
+}
+function cacheSet(key, val) {
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
+}
+
+/** Генерує (з кешем за хешем src). */
+function genCached(file, src) {
+  const key = 'gen-' + sha(GEN_MODEL + '\0' + src)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const r = generateDoc(file, { model: GEN_MODEL })
+  const out = { md: r.md, score: r.score, issues: r.issues, degraded: r.degraded }
+  cacheSet(key, out)
+  return { ...out, cached: false }
+}
+
+/** Судить (з кешем за хешем src+doc). */
+function judgeCached(src, doc) {
+  const key = 'judge-' + sha(JUDGE_MODEL + '\0' + src + '\0' + doc)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
+  const raw = callLlm([{ role: 'system', content: SYSTEM }, { role: 'user', content: user }], JUDGE_MODEL, { timeoutMs: JUDGE_TIMEOUT, temperature: 0 })
+  const a = raw.indexOf('{'), b = raw.lastIndexOf('}')
+  if (a < 0 || b < 0) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
+  const v = JSON.parse(raw.slice(a, b + 1))
+  cacheSet(key, v)
+  return { ...v, cached: false }
+}
+
+function main() {
+  const files = process.argv.slice(2).filter(f => !f.startsWith('--'))
+  if (!files.length) {
+    console.error('Usage: node docgen-judge-measure.mjs <file1> <file2> ...')
+    process.exit(2)
+  }
+  console.error(`[measure] gen=${GEN_MODEL} judge=${JUDGE_MODEL} threshold=${THRESHOLD} files=${files.length} cache=${CACHE_DIR}`)
+
+  const rows = []
+  for (const [i, file] of files.entries()) {
+    const tag = `(${i + 1}/${files.length}) ${file}`
+    let src
+    try { src = readFileSync(file, 'utf8') } catch (e) { console.error(`[skip] ${tag}: read ${e.message}`); continue }
+
+    let gen
+    try { gen = genCached(file, src) } catch (e) { console.error(`[gen-err] ${tag}: ${e.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: e.message.slice(0, 200) }); continue }
+    if (gen.score == null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
+
+    const passed = gen.score >= THRESHOLD
+    const row = { file, score: gen.score, degraded: gen.degraded, passed, genCached: gen.cached }
+    console.error(`[gen${gen.cached ? '*' : ''}] ${tag} score=${gen.score} ${passed ? 'PASS' : 'degraded'}`)
+
+    if (passed) {
+      try {
+        const v = judgeCached(src, gen.md)
+        row.verdict = v.verdict; row.confidence = v.confidence; row.reason = v.reason; row.offending = v.offending; row.judgeCached = v.cached
+        console.error(`  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`)
+      } catch (e) { row.judgeError = e.message.slice(0, 200); console.error(`  [judge-err] ${e.message.slice(0, 120)}`) }
+    }
+    rows.push(row)
+  }
+
+  // Aggregate
+  const scored = rows.filter(r => typeof r.score === 'number')
+  const passedRows = scored.filter(r => r.passed && r.verdict)
+  const byVerdict = { accurate: 0, generic: 0, inaccurate: 0 }
+  for (const r of passedRows) byVerdict[r.verdict] = (byVerdict[r.verdict] ?? 0) + 1
+  const M = passedRows.length
+  const bad = byVerdict.generic + byVerdict.inaccurate
+  const pct = n => (M ? ((100 * n) / M).toFixed(1) : '—')
+
+  const report = {
+    config: { genModel: GEN_MODEL, judgeModel: JUDGE_MODEL, threshold: THRESHOLD },
+    counts: {
+      files: files.length, generated: scored.length,
+      unsupported: rows.filter(r => r.unsupported).length,
+      genErrors: rows.filter(r => r.error === 'gen').length,
+      passedDetScorer: scored.filter(r => r.passed).length,
+      judged: M, judgeErrors: rows.filter(r => r.judgeError).length
+    },
+    falsePositiveRate: { // серед PASSED+judged
+      accurate: byVerdict.accurate, generic: byVerdict.generic, inaccurate: byVerdict.inaccurate,
+      badPct: pct(bad), inaccuratePct: pct(byVerdict.inaccurate), genericPct: pct(byVerdict.generic)
+    },
+    offenders: passedRows.filter(r => r.verdict !== 'accurate').map(r => ({ file: r.file, score: r.score, verdict: r.verdict, confidence: r.confidence, reason: r.reason })),
+    rows
+  }
+
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  const out = join(CACHE_DIR, 'report.json')
+  writeFileSync(out, JSON.stringify(report, null, 2))
+
+  console.log('\n===== Q4 MEASUREMENT =====')
+  console.log(`generated: ${report.counts.generated}/${files.length}  (unsupported=${report.counts.unsupported}, gen-errors=${report.counts.genErrors})`)
+  console.log(`passed det-scorer (score≥${THRESHOLD}): ${report.counts.passedDetScorer}   judged: ${M}`)
+  console.log(`among PASSED+judged → accurate=${byVerdict.accurate} generic=${byVerdict.generic} inaccurate=${byVerdict.inaccurate}`)
+  console.log(`>>> det-scorer FALSE-POSITIVE rate: ${pct(bad)}%  (inaccurate=${pct(byVerdict.inaccurate)}%, generic=${pct(byVerdict.generic)}%)`)
+  console.log(`decision guide: <~5% → don't build gate; >~15% → build (inaccurate-only)`)
+  console.log(`report: ${out}`)
+}
+
+main()

package/scripts/lib/docs/run-rule-cli.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/lib/run-rule-cli.mjs
-  crc: 21a7b19a
+  crc: 264e7ab0
   score: 100
 ---
 
@@ -9,18 +9,15 @@ docgen:
 
 ## Огляд
 
-Файл є автономним CLI-запускачем для одного правила. Він читає конфігурацію з `.n-cursor.json`, перевіряє, чи існує запис для заданого ID у конфігурації, друкує звіт про перевірку та повертає агрегований код виходу.
+Файл є автономним CLI-запускачем для одного правила. Він друкує звіт про перевірку та повертає агрегований код виходу. Whitelist-гейту тут немає: гейтинг активних правил живе виключно у `resolveCheckRuleIds` (селекція за `.n-cursor.json`), а прямий запуск файлу правила — свідома debug/override-дія, тож виконується беззастережно.
 
 ## Поведінка
 
 1.  Викликається для запуску правила.
-2.  Читає конфігурацію з `.n-cursor.json`.
-3.  Перевіряє наявність правила у whitelist.
-4.  Якщо правило не дозволено, друкує повідомлення про пропуск.
-5.  Якщо правило дозволено, друкує повідомлення про перевірку правила.
-6.  Використовує кеш для перевірки.
-7.  Викликає функцію для виконання стандартного правила з кешем.
-8.  Повертає агрегований код виходу.
+2.  Друкує повідомлення про перевірку правила.
+3.  Використовує кеш для перевірки.
+4.  Викликає функцію для виконання стандартного правила з кешем.
+5.  Повертає агрегований код виходу.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/docs/run-fix-check.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/lib/fix/run-fix-check.mjs
-  crc: 2a0e5f0a
+  crc: 76874730
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -10,15 +10,16 @@ docgen:
 
 ## Огляд
 
-Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (включаючи завантаження конфігурації, whitelist та ізоляцію від збоїв).
+Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (crash-isolation). Селекція активних правил — єдине джерело: `resolveCheckRuleIds` за `.n-cursor.json`; per-rule whitelist у спавнених процесах прибрано як дубль.
 
 ## Поведінка
 
 1. Визначається наявність інструменту `conftest`.
 2. Отримується список усіх доступних ідентифікаторів правил з каталогу правил.
-3. Визначається список ідентифікаторів правил для прогону:
-    а. Якщо надано явний список правил, перевіряється, чи всі ці правила доступні.
-    б. Якщо явний список не надано, скануються файли `.cursor/rules/*.mdc` у корені проєкту. На основі знайдених файлів визначається список правил для прогону.
+3. Визначається список ідентифікаторів правил для прогону (`resolveCheckRuleIds`), де `.n-cursor.json` — єдине джерело правди:
+    а. Якщо надано явний список правил — він валідується проти доступних і звужується до активних (вимкнене правило не вмикається навіть на явний запит).
+    б. Якщо явного списку нема й конфіг є — беруться активні правила конфіга (`available ∩ enabled`); `.cursor/rules/*.mdc` ігнорується (фікс дрейфу «enabled, але .mdc нема»).
+    в. Якщо конфіга нема (open-by-default debug) — fallback на скан `.cursor/rules/*.mdc`.
 4. Якщо визначено ідентифікатори правил для прогону, для кожного ідентифікатора запускається окремий процес `bun` з файлом `fix.mjs` відповідного правила.
 5. Захоплюється вивід кожного процесу.
 6. Підраховується загальна кількість правил, що не пройшли перевірку.

package/scripts/lib/fix/run-fix-check.mjs

@@ -4,8 +4,11 @@
  * (`orchestrator.mjs`, `t0.mjs`) і PostToolUse-хук.
  *
  * Per-rule ізоляція зберігається: кожне `rules/<id>/fix.mjs` усе ще запускається окремим
- * процесом `bun` (config-loading + whitelist + crash-isolation). Прибрано лише зовнішній
- * wrapper-subprocess, що його раніше шелили оркестратор/хук.
+ * процесом `bun` (crash-isolation). Прибрано лише зовнішній wrapper-subprocess, що його
+ * раніше шелили оркестратор/хук.
+ *
+ * Селекція активних правил — виключно тут (`resolveCheckRuleIds` за `.n-cursor.json`);
+ * per-rule whitelist у спавнених процесах прибрано як дубль (див. `runRuleCli`).
  */
 import { spawnSync } from 'node:child_process'
 import { dirname, join } from 'node:path'
@@ -16,24 +19,42 @@ import { listRuleIds } from '../list-rule-ids.mjs'
 import { ensureTool } from '../ensure-tool.mjs'
 import { discoverCheckRulesFromCursorRules } from '../discover-check-rules-from-cursor.mjs'
 import { listProjectRulesMdcFiles } from '../list-project-rules-mdc.mjs'
+import { isRuleEnabled, readNCursorConfigLite } from '../read-n-cursor-config-lite.mjs'
 
 // Цей файл: npm/scripts/lib/fix/run-fix-check.mjs → npm/rules (чотири dirname угору + rules).
 const BUNDLED_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
 
 /**
- * Визначає id правил для прогону: явні (з валідацією) або discovery з `.cursor/rules/*.mdc`.
- * @param {string[]} requestedRules запитані (порожній → discovery)
- * @param {string[]} available доступні rule-id у пакеті
+ * Визначає id правил для прогону. `.n-cursor.json` — **єдине джерело правди** селекції:
+ *  - явні `requestedRules` — валідуються проти `available`, тоді звужуються до активних
+ *    (явний запит лише фільтрує всередині активних, не вмикає вимкнене правило);
+ *  - без явних і конфіг **є** — беремо саме активні правила конфіга (`available ∩ enabled`).
+ *    Це прибирає дрейф «правило в `.n-cursor.json:rules`, але `.cursor/rules/*.mdc` нема
+ *    (sync не прогнаний) → раніше тихо пропускалось»;
+ *  - без явних і конфіга **нема** — open-by-default debug: fallback на зматеріалізовані
+ *    `.cursor/rules/*.mdc` (єдиний сигнал «що встановлено», коли немає whitelist).
+ *
+ * Per-rule дубль-гейту (`runRuleCli → isRuleEnabled`) більше немає — гейтинг живе лише тут.
+ * @param {string[]} requestedRules запитані (порожній → auto-селекція)
+ * @param {string[]} available доступні rule-id у пакеті (алфавітно)
  * @param {string} cwd корінь
  * @returns {Promise<string[]>} id для прогону (можливо порожній)
  * @throws {Error} на невідомих явно заданих правилах
  */
-async function resolveCheckRuleIds(requestedRules, available, cwd) {
+export async function resolveCheckRuleIds(requestedRules, available, cwd) {
+  const config = await readNCursorConfigLite(cwd)
+
   if (requestedRules.length > 0) {
     const unknown = requestedRules.filter(id => !available.includes(id))
     if (unknown.length > 0) throw new Error(`Unknown rules: ${unknown.join(', ')}`)
-    return requestedRules
+    return requestedRules.filter(id => isRuleEnabled(config, id))
   }
+
+  if (config.exists) {
+    return available.filter(id => isRuleEnabled(config, id))
+  }
+
+  // Конфіга нема → fallback на зматеріалізоване (debug / open-by-default).
   const mdcFiles = await listProjectRulesMdcFiles(cwd)
   if (mdcFiles.length === 0) return []
   return discoverCheckRulesFromCursorRules(available, mdcFiles)

package/scripts/lib/run-rule-cli.mjs

@@ -1,14 +1,17 @@
 /**
  * Standalone CLI runner для одного правила. Викликається з `rules/<id>/fix.mjs`
  * у блоці `if (import.meta.main)` — це робить `bun rules/<id>/fix.mjs` повним
- * еквівалентом старого `npx \@nitra/cursor fix <id>`: читає `.n-cursor.json`,
- * перевіряє whitelist, друкує summary, повертає aggregated exit-code.
+ * еквівалентом `npx \@nitra/cursor fix <id>`: друкує summary, повертає aggregated exit-code.
+ *
+ * **Без whitelist-гейту.** Гейтинг активних правил — єдине джерело: `resolveCheckRuleIds`
+ * (`scripts/lib/fix/run-fix-check.mjs`) за `.n-cursor.json`. Прямий `bun rules/<id>/fix.mjs` —
+ * свідомий запуск саме цього правила (debug / override), тож виконується беззастережно;
+ * усі автоматичні шляхи (lint-конформність, orchestrator, t0, hook) уже спавнять лише активні.
  *
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.
  */
 import { basename } from 'node:path'
 
-import { isRuleEnabled, readNCursorConfigLite } from './read-n-cursor-config-lite.mjs'
 import { runStandardRule } from './run-standard-rule.mjs'
 import { getOrCreateWalkCache } from '../utils/walk-cache.mjs'
 
@@ -21,16 +24,10 @@ const PACKAGE_NAME = '@nitra/cursor'
 
 /**
  * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
- * @returns {Promise<number>} 0 — OK або правило не enabled; 1 — порушення
+ * @returns {Promise<number>} 0 — OK; 1 — порушення
  */
 export async function runRuleCli(ruleDir) {
   const ruleId = basename(ruleDir)
-  const config = await readNCursorConfigLite()
-
-  if (!isRuleEnabled(config, ruleId)) {
-    console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — правило не в \`.n-cursor.json:rules\`. Пропущено.\n`)
-    return 0
-  }
 
   console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — перевірка правила\n`)