@nitra/cursor 1.8.189 → 1.8.191

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.191] - 2026-05-07
+
+### Added
+
+- `check-npm-module.mjs`: перший заголовок **`## [version]`** у `npm/CHANGELOG.md` має збігатися з **`version`** у `npm/package.json` (найсвіжіший реліз зверху — Keep a Changelog); якщо є незакомічені зміни під **`npm/`**, `version` у робочому `npm/package.json` має відрізнятися від **`HEAD`** (інакше ризик дописати новий функціонал без bump).
+
+### Changed
+
+- `npm-module` (mdc v1.9 → v1.10): розширено **«Build версія»** і **«CHANGELOG»** — чеклист для агента, заборона дописувати нові пункти в уже існуючу секцію релізу замість нового номера; впорядковано `CHANGELOG` (1.8.190 перед 1.8.189).
+
+## [1.8.190] - 2026-05-07
+
+### Added
+
+- `js-run` (mdc v1.4 → v1.5): секція **`jsconfig.json`** — канонічний файл для backend-пакетів із каталогом **`src/`** (NodeNext, `include: ['src/**/*']`); для пакетів без `src/` вимога не діє.
+- `check-js-run.mjs`: перевірка наявності та вмісту `jsconfig.json`, якщо в workspace-пакеті (без vite) є **`src/`**; тести у `check-js-run-fixture.test.mjs`.
+
 ## [1.8.189] - 2026-05-07
 
 ### Added

package/mdc/js-run.mdc

@@ -1,7 +1,7 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.4'
+version: '1.5'
 ---
 
 ## Область застосування
@@ -28,6 +28,25 @@ package.json
 readme.md
 ```
 
+## `jsconfig.json` (редактор / перевірка типів)
+
+Якщо в **backend** workspace-пакеті (без `vite` у `devDependencies`) є каталог **`src/`**, у **корені цього пакета** має бути **`jsconfig.json`**. Якщо файлу ще немає — створи його з таким вмістом (канон js-run):
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "esnext",
+    "checkJs": false
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Якщо пакет не слідує структурі з `src/` (наприклад, лише `scripts/` у корені) — ця вимога не застосовується; для типових сервісів із `src/` файл обов’язковий і має збігатися з каноном.
+
 ## Використання @nitra/pino
 
 Проект використовує @nitra/pino для логування.
@@ -170,4 +189,4 @@ on:
 
 ## Перевірка
 
-`npx @nitra/cursor check js-run`
+`npx @nitra/cursor check js-run` — зокрема для кожного backend workspace-пакета з каталогом **`src/`** перевіряє наявність **`jsconfig.json`** і збіг вмісту з каноном вище.

package/mdc/npm-module.mdc

@@ -1,7 +1,7 @@
 ---
 description: Оформлення репозиторію для npm модуля
 alwaysApply: true
-version: '1.9'
+version: '1.10'
 ---
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
@@ -47,12 +47,18 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 У робочій копії не повинно бути більше одного незбереженого в **git** підвищення **build**-версії за раз.
 
+**Чеклист у тому ж наборі змін, що й правки під `npm/`:** `version` у **`npm/package.json`** → **+1**; зверху **`npm/CHANGELOG.md`** нова секція **`## [нова версія] - …`**; у секції лише те, що входить у цей реліз.
+
+**Антипатерн:** не дописувати нові bullet-и в уже існуючу секцію **`## [X.Y.Z]`**, якщо паралельно не піднімаєш **`version`** до нового номера й не створюєш **нову** секцію зверху. Інакше змішуються різні релізи в одному номері, а `check npm-module` / `check changelog` гірше ловлять порушення.
+
 **Підказка:** щоб не дублювати bump і бачити різницю зі збереженим деревом, перевір `git status npm/package.json` або `git diff HEAD -- npm/package.json` перед другим підвищенням у тій самій гілці / наборі змін.
 
 ## CHANGELOG
 
 Окреме правило **`changelog`** ([changelog.mdc](changelog.mdc)) вимагає `npm/CHANGELOG.md` із записом для поточної версії (Keep a Changelog) і присутність `"CHANGELOG.md"` у масиві `files` у `npm/package.json`. Логіка — PR-scoped (сума по гілці vs `dev`).
 
+Найновіша версія — **перша** секція **`## [version]`** у файлі (зверху після заголовка). Вона **має збігатися** з полем **`version`** у **`npm/package.json`** — це перевіряє **`npx @nitra/cursor check npm-module`**.
+
 ## npm publish
 
 **`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
@@ -96,4 +102,4 @@ jobs:
 
 ## Перевірка
 
-`npx @nitra/cursor check npm-module`
+`npx @nitra/cursor check npm-module` — зокрема узгодженість першої секції **`npm/CHANGELOG.md`** з **`version`** у **`npm/package.json`** і нагадування про bump при незакомічених змінах під **`npm/`** (через `git`).

package/package.json

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

package/scripts/check-js-run.mjs

@@ -24,9 +24,11 @@
  *    `working-directory: <rootDir>` (див. `utils/depcheck-workflow.mjs`);
  *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
  *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
- *    (див. `utils/promise-settimeout-scan.mjs`).
+ *    (див. `utils/promise-settimeout-scan.mjs`);
+ *  - «jsconfig.json»: у backend-пакеті з каталогом `src/` у корені має бути `jsconfig.json`,
+ *    вміст якого збігається з каноном js-run.mdc (NodeNext і include на дерево `src`).
  */
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 
@@ -52,6 +54,99 @@ import {
 import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
+/** Канонічний `jsconfig.json` для backend workspace-пакетів із каталогом `src/` (js-run.mdc). */
+const CANONICAL_BACKEND_JSCONFIG = Object.freeze({
+  compilerOptions: Object.freeze({
+    lib: Object.freeze(['esnext']),
+    module: 'NodeNext',
+    moduleResolution: 'NodeNext',
+    target: 'esnext',
+    checkJs: false
+  }),
+  include: Object.freeze(['src/**/*'])
+})
+
+/**
+ * Глибока рівність для JSON-подібних значень (масиви — порядок важливий).
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+function deepEqualJson(a, b) {
+  if (a === b) return true
+  if (a === null || b === null || typeof a !== typeof b) return false
+  if (typeof a !== 'object') return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a)) {
+    if (a.length !== b.length) return false
+    for (const [i, v] of a.entries()) {
+      if (!deepEqualJson(v, b[i])) return false
+    }
+    return true
+  }
+  const ao = /** @type {Record<string, unknown>} */ (a)
+  const bo = /** @type {Record<string, unknown>} */ (b)
+  const keysA = Object.keys(ao).sort()
+  const keysB = Object.keys(bo).sort()
+  if (keysA.length !== keysB.length) return false
+  for (const [i, k] of keysA.entries()) {
+    if (k !== keysB[i]) return false
+    if (!deepEqualJson(ao[k], bo[k])) return false
+  }
+  return true
+}
+
+/**
+ * Чи існує непорожній за змістом маркер каталогу `src/` (рекомендована структура js-run).
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @returns {boolean}
+ */
+function backendPackageHasSrcDir(absPackageRoot) {
+  const srcPath = join(absPackageRoot, 'src')
+  try {
+    return statSync(srcPath).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Перевіряє `jsconfig.json` для backend-пакетів із `src/`.
+ * @param {string} rootDir відносний шлях workspace
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string} label префікс `[pkg] `
+ * @param {(msg: string) => void} fail
+ * @param {(msg: string) => void} passFn
+ * @returns {Promise<void>}
+ */
+async function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn) {
+  if (!backendPackageHasSrcDir(absPackageRoot)) return
+
+  const jcPath = join(rootDir, 'jsconfig.json')
+  if (!existsSync(jcPath)) {
+    fail(
+      `${label}є каталог src/, але немає jsconfig.json — додай канонічний файл з js-run.mdc ` +
+        `(NodeNext, include: src/**/*).`
+    )
+    return
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(await readFile(jcPath, 'utf8'))
+  } catch {
+    fail(`${label}jsconfig.json не вдалося розпарсити як JSON`)
+    return
+  }
+  if (!deepEqualJson(parsed, CANONICAL_BACKEND_JSCONFIG)) {
+    fail(
+      `${label}jsconfig.json не збігається з каноном js-run.mdc — заміни на шаблон з правила ` +
+        `(compilerOptions: lib esnext, module/moduleResolution NodeNext, target esnext, checkJs false; include: src/**/*).`
+    )
+    return
+  }
+  passFn(`${label}jsconfig.json узгоджено з js-run (пакет з src/)`)
+}
+
 /**
  * Перетворює абсолютний шлях у posix-формі відносно кореня пакета.
  * @param {string} absPackageRoot абсолютний корінь пакета
@@ -216,6 +311,8 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
     return
   }
 
+  await checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn)
+
   const importViolations = await checkBunyanImports(absPackageRoot, ignorePaths, label, fail)
   if (importViolations === 0) {
     passFn(`${label}немає імпортів '@nitra/bunyan' / 'bunyan' у джерелах`)

package/scripts/check-npm-module.mjs

@@ -10,10 +10,16 @@
  * файл під `./types/…`, у hk — `tsc -p tsconfig.emit-types.json`, у JSON-конфігу — потрібні compilerOptions для emit.
  *
  * Поля workflow перевіряються після **YAML parse**, щоб не плутати з коментарями.
+ *
+ * Версія та CHANGELOG: перший заголовок `## [version]` у `npm/CHANGELOG.md` має збігатися з `version` у
+ * `npm/package.json` (найсвіжіший реліз зверху). Якщо в git є незакомічені зміни під `npm/`, `version` у робочому
+ * файлі має відрізнятися від `HEAD` — інакше типовий пропуск bump після правок у пакеті.
  */
+import { execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { join } from 'node:path'
+import { promisify } from 'node:util'
 
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import {
@@ -26,8 +32,13 @@ import {
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
 import { walkDir } from './utils/walkDir.mjs'
 
+const execFileAsync = promisify(execFile)
+
 const TYPES_FILE_RE = /^\.\/types\/.+\.d\.(ts|mts)$/
 
+/** Перший заголовок релізу у Keep a Changelog (`## [1.2.3]`). */
+const CHANGELOG_FIRST_VERSION_RE = /^## \[([^\]]+)\]/m
+
 /** Канонічний entrypoint типів для пакетів із вихідним `.js` під каталогом `npm/src` */
 const TYPES_INDEX = './types/index.d.ts'
 
@@ -233,6 +244,122 @@ async function checkEmitTypesConfig(passFn, failFn) {
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  */
+/**
+ * Чи виконано `git` у корені робочого дерева.
+ * @returns {Promise<boolean>}
+ */
+async function gitInsideWorkTree() {
+  try {
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' })
+    return stdout.trim() === 'true'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Список незакомічених шляхів під `npm/` відносно `HEAD`.
+ * @returns {Promise<string[] | null>} шляхи або `null`, якщо `git` недоступний
+ */
+async function gitDiffNameOnlyNpm() {
+  try {
+    const { stdout } = await execFileAsync('git', ['diff', '--name-only', 'HEAD', '--', 'npm'], { encoding: 'utf8' })
+    return stdout.trim().split('\n').filter(Boolean)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Поле `version` з `npm/package.json` на заданому git-ref (`HEAD:npm/package.json`).
+ * @param {string} refPath на кшталт `HEAD:npm/package.json`
+ * @returns {Promise<string | null>}
+ */
+async function gitShowNpmPackageVersionAt(refPath) {
+  try {
+    const { stdout } = await execFileAsync('git', ['show', refPath], { encoding: 'utf8' })
+    const m = stdout.match(/"version":\s*"([^"]+)"/)
+    return m ? m[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Версія з першого заголовка `## […]` у тексті CHANGELOG.
+ * @param {string} changelogText
+ * @returns {string | null}
+ */
+function firstChangelogSectionVersion(changelogText) {
+  const m = changelogText.match(CHANGELOG_FIRST_VERSION_RE)
+  return m ? m[1] : null
+}
+
+/**
+ * Перший реліз у CHANGELOG має збігатися з `version` у `npm/package.json`.
+ * @param {(msg: string) => void} passFn
+ * @param {(msg: string) => void} failFn
+ * @returns {Promise<void>}
+ */
+async function checkChangelogTopMatchesPackageVersion(passFn, failFn) {
+  if (!existsSync('npm/CHANGELOG.md') || !existsSync('npm/package.json')) return
+  const pkg = JSON.parse(await readFile('npm/package.json', 'utf8'))
+  const ver = typeof pkg.version === 'string' ? pkg.version : null
+  if (!ver) {
+    failFn('npm/package.json: відсутнє поле version')
+    return
+  }
+  const cl = await readFile('npm/CHANGELOG.md', 'utf8')
+  const first = firstChangelogSectionVersion(cl)
+  if (!first) {
+    failFn('npm/CHANGELOG.md: не знайдено жодного заголовка ## [version]')
+    return
+  }
+  if (first !== ver) {
+    failFn(
+      `npm/CHANGELOG.md: перша секція [${first}] не збігається з npm/package.json version "${ver}" ` +
+        '(зверху має бути найсвіжіший реліз і той самий номер — npm-module.mdc).'
+    )
+    return
+  }
+  passFn(`npm/CHANGELOG.md: перша секція [${first}] збігається з npm/package.json`)
+}
+
+/**
+ * Незакомічені зміни під `npm/` вимагають підвищення `version` відносно `HEAD`.
+ * @param {(msg: string) => void} passFn
+ * @param {(msg: string) => void} failFn
+ * @returns {Promise<void>}
+ */
+async function checkDirtyNpmRequiresVersionBump(passFn, failFn) {
+  if (!(await gitInsideWorkTree())) {
+    passFn('npm-module: git недоступний або поза work tree — перевірку незакоміченого bump пропущено')
+    return
+  }
+  const changed = await gitDiffNameOnlyNpm()
+  if (changed === null) {
+    passFn('npm-module: git diff під npm/ недоступний — пропущено')
+    return
+  }
+  if (changed.length === 0) return
+
+  const headVer = await gitShowNpmPackageVersionAt('HEAD:npm/package.json')
+  if (headVer === null) return
+
+  const pkg = JSON.parse(await readFile('npm/package.json', 'utf8'))
+  const cur = typeof pkg.version === 'string' ? pkg.version : null
+  if (!cur) return
+
+  if (cur === headVer) {
+    failFn(
+      `Незакомічені зміни під npm/ (${changed.join(', ')}), але "version" у npm/package.json лишився ${cur} ` +
+        '(як у HEAD). Підвищ version (+1) і додай секцію ## [нова версія] зверху CHANGELOG (npm-module.mdc).'
+    )
+    return
+  }
+  passFn(`npm/: незакомічені зміни під npm/ узгоджені з підвищенням version (${headVer} → ${cur})`)
+}
+
 async function checkPublishWorkflow(passFn, failFn) {
   const publishWf = '.github/workflows/npm-publish.yml'
   if (!existsSync(publishWf)) {
@@ -371,5 +498,8 @@ export async function check() {
 
   await checkPublishWorkflow(pass, fail)
 
+  await checkChangelogTopMatchesPackageVersion(pass, fail)
+  await checkDirtyNpmRequiresVersionBump(pass, fail)
+
   return reporter.getExitCode()
 }