@nitra/cursor 3.21.1 → 3.22.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [3.22.0] - 2026-06-04
+
+### Added
+
+- js-lint quick-режим класифікує lint-findings на introduced (рядок у diff від HEAD) vs pre-existing (борг файлу) і позначає у виводі (🆕/🗄) — щоб дотик до файлу не плутав «моє чи старий борг». Захоплює oxlint/eslint --format=json, парсить added-lines git-diff, групує. Блокування без змін (#6/A). Краш інструмента не пропускається тихо.
+
 ## [3.21.1] - 2026-06-04
 
 ### Changed

package/package.json

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

package/rules/js-lint/js/lint-findings.mjs

@@ -0,0 +1,110 @@
+/**
+ * Нормалізація й класифікація lint-findings (oxlint + eslint) на introduced
+ * (рядок у diff від HEAD) vs pre-existing (борг файлу) — беклог #6, варіант A.
+ *
+ * Формати: oxlint `--format=json` → `{ diagnostics:[{ filename, code, labels:[{span:{line}}] }] }`;
+ * eslint `--format=json` → `[{ filePath, messages:[{ ruleId, line, message }] }]`. Шляхи абсолютні.
+ */
+import { isAbsolute, relative } from 'node:path'
+
+import { isIntroducedLine } from '../../../scripts/lib/diff-added-lines.mjs'
+
+/**
+ * @param {string} jsonText вивід `oxlint --format=json`
+ * @returns {{ file: string, line: number, rule: string, message: string, tool: string }[] | null} findings,
+ *   або `null` якщо json непарсабельний (краш/обрізаний вивід інструмента — НЕ «чисто»)
+ */
+export function parseOxlint(jsonText) {
+  let data
+  try {
+    data = JSON.parse(jsonText)
+  } catch {
+    return null
+  }
+  const diags = Array.isArray(data?.diagnostics) ? data.diagnostics : []
+  return diags
+    .filter(d => d?.filename)
+    .map(d => ({
+      file: d.filename,
+      line: d.labels?.[0]?.span?.line ?? 0,
+      rule: d.code ?? '',
+      message: d.message ?? '',
+      tool: 'oxlint'
+    }))
+}
+
+/**
+ * @param {string} jsonText вивід `eslint --format=json`
+ * @returns {{ file: string, line: number, rule: string, message: string, tool: string }[] | null} findings,
+ *   або `null` якщо json непарсабельний (краш/обрізаний вивід інструмента — НЕ «чисто»)
+ */
+export function parseEslint(jsonText) {
+  let data
+  try {
+    data = JSON.parse(jsonText)
+  } catch {
+    return null
+  }
+  const results = Array.isArray(data) ? data : []
+  const out = []
+  for (const r of results) {
+    for (const m of r?.messages ?? []) {
+      out.push({
+        file: r.filePath,
+        line: m.line ?? 0,
+        rule: m.ruleId ?? '(syntax)',
+        message: m.message ?? '',
+        tool: 'eslint'
+      })
+    }
+  }
+  return out.filter(f => f.file)
+}
+
+/**
+ * Розділяє findings на introduced / pre-existing за доданими рядками.
+ * @param {{ file: string, line: number }[]} findings нормалізовані findings
+ * @param {Map<string, Set<number> | string>} addedLines з `addedLinesByFile`
+ * @param {string} [cwd] корінь (для нормалізації абсолютних шляхів у relative)
+ * @returns {{ introduced: object[], preExisting: object[] }} класифікація
+ */
+export function classifyFindings(findings, addedLines, cwd = process.cwd()) {
+  const introduced = []
+  const preExisting = []
+  for (const f of findings) {
+    const rel = isAbsolute(f.file) ? relative(cwd, f.file) : f.file
+    if (isIntroducedLine(addedLines, rel, f.line)) introduced.push(f)
+    else preExisting.push(f)
+  }
+  return { introduced, preExisting }
+}
+
+/**
+ * Рядок одного finding: `<rel>:<line>  <rule>  <message>`.
+ * @param {{ file: string, line: number, rule: string, message: string }} f finding
+ * @param {string} cwd корінь
+ * @returns {string} рядок
+ */
+function formatFinding(f, cwd) {
+  const rel = isAbsolute(f.file) ? relative(cwd, f.file) : f.file
+  return `     ${rel}:${f.line}  ${f.rule}  ${f.message}`
+}
+
+/**
+ * Згрупований звіт: 🆕 introduced (виправ) + 🗄 pre-existing (борг файлу).
+ * @param {{ introduced: object[], preExisting: object[] }} classified результат `classifyFindings`
+ * @param {string} [cwd] корінь
+ * @returns {string} текст звіту
+ */
+export function renderFindings({ introduced, preExisting }, cwd = process.cwd()) {
+  const lines = []
+  if (introduced.length > 0) {
+    lines.push(`  🆕 introduced (${introduced.length}) — внесено цією зміною, виправ:`)
+    for (const f of introduced) lines.push(formatFinding(f, cwd))
+  }
+  if (preExisting.length > 0) {
+    lines.push(`  🗄 pre-existing (${preExisting.length}) — борг файлу, не з цієї зміни:`)
+    for (const f of preExisting) lines.push(formatFinding(f, cwd))
+  }
+  return lines.join('\n')
+}

package/rules/js-lint/js/lint.mjs

@@ -2,12 +2,17 @@
  * Quick-крок lint правила js-lint: oxlint + eslint (з автофіксом).
  *
  * Викликається lint-оркестратором (`n-cursor lint` / `lint-ci`):
- *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них;
- *  - `files` = undefined (ci) → лінтимо весь проєкт.
+ *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них і
+ *    КЛАСИФІКУЄМО лишені findings на introduced (рядок у diff від HEAD) vs
+ *    pre-existing (борг файлу) — беклог #6, варіант A (видимість; блокування без змін);
+ *  - `files` = undefined (ci) → лінтимо весь проєкт (стрімінг, без класифікації).
  * Крос-файлові jscpd/knip — окреме правило js-lint-ci (фаза ci).
  */
 import { spawnSync } from 'node:child_process'
 
+import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'
+import { classifyFindings, parseEslint, parseOxlint, renderFindings } from './lint-findings.mjs'
+
 const JS_EXT_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx|vue)$/u
 
 /**
@@ -20,15 +25,88 @@ export function filterJsFiles(files) {
 }
 
 /**
- * @param {string[]} args аргументи інструмента (бінар через bunx)
+ * Запуск інструмента (через bunx) зі стрімінгом у термінал.
+ * @param {string[]} args аргументи
  * @param {string} cwd корінь
  * @returns {number} exit code
  */
-function run(args, cwd) {
+function runInherit(args, cwd) {
   const r = spawnSync('bunx', args, { cwd, stdio: 'inherit' })
   return typeof r.status === 'number' ? r.status : 1
 }
 
+/**
+ * Авто-фікс-пас: застосовує `--fix`, stdout приглушено (findings перерендеримо
+ * класифіковано), stderr — назовні (краші інструмента видимі).
+ * @param {string[]} args аргументи
+ * @param {string} cwd корінь
+ * @returns {number} exit code
+ */
+function runFix(args, cwd) {
+  const r = spawnSync('bunx', args, { cwd, stdio: ['ignore', 'ignore', 'inherit'] })
+  return typeof r.status === 'number' ? r.status : 1
+}
+
+/** Запас буфера для json-виводу лінтерів (великі changeset-и > дефолтного ~1MB). */
+const JSON_MAX_BUFFER = 64 * 1024 * 1024
+
+/**
+ * Репорт-пас: `--format=json`. Повертає exit-код і stdout (щоб відрізнити
+ * «чисто/є-порушення» від краху інструмента).
+ * @param {string[]} args аргументи
+ * @param {string} cwd корінь
+ * @returns {{ status: number, stdout: string }} результат
+ */
+function runJson(args, cwd) {
+  const r = spawnSync('bunx', args, { cwd, encoding: 'utf8', maxBuffer: JSON_MAX_BUFFER })
+  return { status: typeof r.status === 'number' ? r.status : 1, stdout: r.stdout ?? '' }
+}
+
+/**
+ * Full-режим (ci): лінт усього проєкту зі стрімінгом і fail-fast (без класифікації).
+ * @param {string} cwd корінь
+ * @returns {number} exit code
+ */
+function lintFullProject(cwd) {
+  const ox = runInherit(['oxlint', '--fix'], cwd)
+  if (ox !== 0) return ox
+  return runInherit(['eslint', '--fix', '.'], cwd)
+}
+
+/**
+ * Quick-режим: авто-фікс змінених файлів, тоді класифікація лишених findings
+ * на introduced / pre-existing (беклог #6/A). Блокування на будь-якому finding.
+ * @param {string[]} js js-подібні змінені файли
+ * @param {string} cwd корінь
+ * @returns {number} exit code (0 — чисто; 1 — лишились findings)
+ */
+function lintChangedClassified(js, cwd) {
+  // Фікс-пас обох інструментів (послідовно; обидва — щоб репорт показав повну картину).
+  runFix(['oxlint', '--fix', ...js], cwd)
+  runFix(['eslint', '--fix', ...js], cwd)
+
+  // Репорт-пас по ФІНАЛЬНОМУ (пост-фікс) файлу — рядки findings і diff узгоджені.
+  const oxRes = runJson(['oxlint', '--format=json', ...js], cwd)
+  const esRes = runJson(['eslint', '--format=json', ...js], cwd)
+  const ox = parseOxlint(oxRes.stdout)
+  const es = parseEslint(esRes.stdout)
+
+  // Краш інструмента (ненульовий exit + непарсабельний json) НЕ можна тихо пропустити
+  // як «чисто» — це регресія проти старого fail-fast. Фейлимо явно.
+  if ((ox === null && oxRes.status !== 0) || (es === null && esRes.status !== 0)) {
+    process.stderr.write('❌ js-lint: інструмент завершився з помилкою (не lint-порушення) — json не розпарсено\n')
+    return 1
+  }
+
+  const findings = [...(ox ?? []), ...(es ?? [])]
+  if (findings.length === 0) return 0
+
+  const classified = classifyFindings(findings, addedLinesByFile(js, cwd), cwd)
+  const header = `❌ js-lint: ${findings.length} порушень (introduced ${classified.introduced.length}, pre-existing ${classified.preExisting.length})`
+  process.stdout.write(`${header}\n${renderFindings(classified, cwd)}\n`)
+  return 1
+}
+
 /**
  * Запускає oxlint+eslint з автофіксом.
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь проєкт
@@ -36,17 +114,10 @@ function run(args, cwd) {
  * @returns {Promise<number>} 0 — OK, ≠0 — порушення
  */
 export function lint(files, cwd = process.cwd()) {
-  let oxArgs = ['oxlint', '--fix']
-  let esArgs = ['eslint', '--fix']
   if (files === undefined) {
-    esArgs.push('.')
-  } else {
-    const js = filterJsFiles(files)
-    if (js.length === 0) return Promise.resolve(0)
-    oxArgs = ['oxlint', '--fix', ...js]
-    esArgs = ['eslint', '--fix', ...js]
+    return Promise.resolve(lintFullProject(cwd))
   }
-  const ox = run(oxArgs, cwd)
-  if (ox !== 0) return Promise.resolve(ox)
-  return Promise.resolve(run(esArgs, cwd))
+  const js = filterJsFiles(files)
+  if (js.length === 0) return Promise.resolve(0)
+  return Promise.resolve(lintChangedClassified(js, cwd))
 }

package/scripts/lib/diff-added-lines.mjs

@@ -0,0 +1,85 @@
+/**
+ * Додані/змінені рядки на файл (vs HEAD) — для класифікації lint-findings на
+ * introduced (рядок у diff) vs pre-existing (поза diff), беклог #6.
+ *
+ * Парсимо `git diff --unified=0 HEAD -- <files>`: hunk-заголовок `@@ -a,b +c,d @@`
+ * дає додані рядки c..c+d-1. Untracked (нові, поза HEAD) — усі рядки introduced (маркер `ALL`).
+ */
+import { spawnSync } from 'node:child_process'
+
+/** Маркер «усі рядки файлу introduced» (новий untracked-файл). */
+export const ALL_LINES = 'ALL'
+
+/** Шлях цільового файлу у рядку `+++ b/path` (або `/dev/null`). */
+const PLUS_FILE_RE = /^\+\+\+ (?:b\/)?(.*)$/u
+/** Діапазон доданих рядків у hunk-заголовку `@@ -a,b +c,d @@`. */
+const HUNK_ADD_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/u
+
+/**
+ * Парсить вивід `git diff --unified=0` у мапу доданих рядків на файл.
+ * @param {string} diffText сирий вивід git diff
+ * @returns {Map<string, Set<number>>} файл → множина доданих рядків
+ */
+export function parseAddedLines(diffText) {
+  const byFile = new Map()
+  let current = null
+  for (const line of String(diffText).split('\n')) {
+    const fileMatch = PLUS_FILE_RE.exec(line)
+    if (fileMatch) {
+      current = fileMatch[1] === '/dev/null' ? null : fileMatch[1]
+      if (current && !byFile.has(current)) byFile.set(current, new Set())
+      continue
+    }
+    const hunk = current && HUNK_ADD_RE.exec(line)
+    if (hunk) {
+      const start = Number(hunk[1])
+      const count = hunk[2] === undefined ? 1 : Number(hunk[2])
+      for (let i = 0; i < count; i++) byFile.get(current).add(start + i)
+    }
+  }
+  return byFile
+}
+
+/**
+ * Тихий git → stdout або `''`.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {string} stdout
+ */
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return r.status === 0 ? (r.stdout ?? '') : ''
+}
+
+/**
+ * Додані рядки на файл (vs HEAD) для заданих файлів. Tracked → з diff;
+ * untracked (нові) → маркер `ALL_LINES`.
+ * @param {string[]} files відносні шляхи (від cwd)
+ * @param {string} [cwd] корінь репо
+ * @param {{ git?: (args: string[], cwd: string) => string }} [deps] ін'єкція git (тести)
+ * @returns {Map<string, Set<number> | typeof ALL_LINES>} файл → додані рядки / `ALL`
+ */
+export function addedLinesByFile(files, cwd = process.cwd(), deps = {}) {
+  if (!files || files.length === 0) return new Map()
+  const run = deps.git ?? git
+  const map = parseAddedLines(run(['diff', '--unified=0', 'HEAD', '--', ...files], cwd))
+  const untracked = run(['ls-files', '--others', '--exclude-standard', '--', ...files], cwd)
+  for (const f of untracked.split('\n').filter(Boolean)) {
+    map.set(f, ALL_LINES)
+  }
+  return map
+}
+
+/**
+ * Чи рядок `line` у файлі `file` — доданий (introduced).
+ * @param {Map<string, Set<number> | typeof ALL_LINES>} addedLines результат `addedLinesByFile`
+ * @param {string} file відносний шлях
+ * @param {number} line номер рядка
+ * @returns {boolean} результат
+ */
+export function isIntroducedLine(addedLines, file, line) {
+  const entry = addedLines.get(file)
+  if (entry === undefined) return false
+  if (entry === ALL_LINES) return true
+  return entry.has(line)
+}