@nitra/cursor 1.8.189 → 1.8.192

package/CHANGELOG.md

@@ -4,6 +4,34 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.192] - 2026-05-07
+
+### Added
+
+- `run-shellcheck-text.mjs`: для `lint-text` — перевірка наявності `shellcheck`/`patch`, авто-виправлення через `shellcheck -f diff` + `patch -p1`, фінальний прогін по tracked `*.sh` (git) або `**/*.sh` без `node_modules`.
+- `text` (mdc v1.25 → v1.26): **shellcheck** у ланцюжку `lint-text`, рекомендація **`timonwong.shellcheck`**, тригер workflow **`**/*.sh`**; тести `run-shellcheck-text.test.mjs`.
+
+### Changed
+
+- `check-text.mjs`: `lint-text` має містити `run-shellcheck-text.mjs`; `extensions.json` — `timonwong.shellcheck`.
+
+## [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/mdc/text.mdc

@@ -1,10 +1,10 @@
 ---
-description: Обробка та перевірка текстових файлів, oxfmt, cspell, markdownlint-cli2, v8r, CI
+description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), markdownlint-cli2, v8r, CI
 alwaysApply: true
-version: '1.25'
+version: '1.26'
 ---
 
-**oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint**, workflow **`lint-text`**.
+**oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
 
 ```json title=".vscode/extensions.json"
 {
@@ -13,6 +13,7 @@ version: '1.25'
     "github.vscode-github-actions",
     "oxc.oxc-vscode",
     "DavidAnson.vscode-markdownlint",
+    "timonwong.shellcheck",
     "redhat.vscode-yaml",
     "irongeek.vscode-env"
   ]
@@ -112,12 +113,14 @@ version: '1.25'
 
 **`package.json`:** скрипт **`lint-text`** і devDependencies **`@nitra/cspell-dict`** (**`^2.0.0`** або новіший у лінії 2.x) — з **2.0.0** у пакет транзитивно входять типові **`@cspell/dict-*`**, тому **не** додавай їх окремо в корінь. **`markdownlint-cli2`** викликай у `lint-text` лише через **`bunx markdownlint-cli2`**, не додавай пакет до devDependencies. **`v8r`** лише через **`bunx v8r`** (зазвичай **`bunx v8r`**), не в devDependencies. Окремий пакет **`markdownlint`** не потрібний.
 
+**shellcheck:** інструмент лише в **`PATH`** (як у **ga.mdc** для `lint-ga`), **не** додавай до `dependencies` / `devDependencies`. Якщо `shellcheck` відсутній — встанови локально (**macOS:** `brew install shellcheck`; **Debian/Ubuntu:** `sudo apt-get install -y shellcheck`; **Arch:** `sudo pacman -S shellcheck`). У **`lint-text`** після **`cspell`** викликай **`bun ./npm/scripts/run-shellcheck-text.mjs`** (у споживачі після синку — `node_modules/@nitra/cursor/scripts/run-shellcheck-text.mjs`): під капотом циклічно **`shellcheck -f diff`** і **`patch -p1`** для авто-виправлень, потім повний прогін **`shellcheck`** по всіх tracked `*.sh` (у git) або по `**/*.sh` без `node_modules`. Потрібен також **`patch`** у `PATH` (на macOS зазвичай уже є).
+
 У v8r **немає** прапорця тихого режиму; рекомендовано скрипт **`run-v8r.mjs`** з репозиторію пакета `@nitra/cursor` (`npm/scripts/run-v8r.mjs`): один виклик у `lint-text` — під капотом послідовні **`bunx v8r`** для кожного типу (**json**, **json5**, **yml**, **yaml**, **toml**), бо один процес v8r з кількома глобами падає з **98**, якщо хоч один glob порожній, і тоді інші розширення не перевіряються. Вивід при кодах **0** і **98** не показується. Каталог схем **`schemas/v8r-catalog.json`** пакета `@nitra/cursor` скрипт підставляє в v8r сам. За бажання можна передати власні glob-и аргументами скрипта. Шлях до скрипта: `./npm/scripts/…`, `./scripts/…` після копіювання, або `node_modules/@nitra/cursor/scripts/…`.
 
 ```json title="package.json"
 {
   "scripts": {
-    "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
+    "lint-text": "npx cspell . && bun ./npm/scripts/run-shellcheck-text.mjs && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
@@ -185,6 +188,7 @@ on:
       - '**/*.go'
       - '**/*.py'
       - '**/*.php'
+      - '**/*.sh'
 
   pull_request:
     branches:
@@ -232,7 +236,7 @@ jobs:
 ```json title="package.json"
 {
   "scripts": {
-    "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
+    "lint-text": "npx cspell . && bun ./npm/scripts/run-shellcheck-text.mjs && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
@@ -249,7 +253,7 @@ jobs:
 ```json title="package.json"
 {
   "scripts": {
-    "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
+    "lint-text": "npx cspell . && bun ./npm/scripts/run-shellcheck-text.mjs && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
@@ -291,4 +295,4 @@ jobs:
 
 ## Перевірка
 
-`npx @nitra/cursor check text` (охоплює oxfmt, cspell, markdownlint, v8r, CI для `lint-text`)
+`npx @nitra/cursor check text` (охоплює oxfmt, cspell, shellcheck у `lint-text`, markdownlint, v8r, CI для `lint-text`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.189",
+  "version": "1.8.192",
   "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()
 }

package/scripts/check-text.mjs

@@ -10,7 +10,7 @@
  * дозволені лише **`@nitra/*`** (як у bun.mdc), зокрема **`@nitra/cspell-dict` ^2.0.0+**; без імпорту **`@cspell/dict-*`** у `.cspell.json`, заборона
  * `markdownlint-cli2` у dependencies/devDependencies, v8r (`run-v8r.mjs` або чотири `bunx v8r`),
  * `.v8rignore` (vscode JSON),
- * workflow `lint-text.yml`, розширення VSCode (markdownlint, oxc).
+ * workflow `lint-text.yml`, розширення VSCode (markdownlint, oxc, shellcheck), `run-shellcheck-text.mjs` у `lint-text`.
  *
  * Якщо є `.cursor/rules/n-text.mdc` і/або `npm/mdc/text.mdc` — перевіряє наявність абзацу про український
  * апостроф (U+0027 vs U+2019) і приклад з символом U+2019 у тексті.
@@ -121,7 +121,7 @@ async function checkVscodeTextExtensions(passFn, failFn) {
   try {
     const ext = JSON.parse(await readFile('.vscode/extensions.json', 'utf8'))
     const rec = ext.recommendations
-    for (const id of ['DavidAnson.vscode-markdownlint', 'oxc.oxc-vscode']) {
+    for (const id of ['DavidAnson.vscode-markdownlint', 'oxc.oxc-vscode', 'timonwong.shellcheck']) {
       if (Array.isArray(rec) && rec.includes(id)) {
         passFn(`extensions.json містить ${id}`)
       } else {
@@ -329,15 +329,16 @@ function checkLintTextScript(lintText, passFn, failFn) {
   const ok =
     lt &&
     lt.includes('cspell') &&
+    lt.includes('run-shellcheck-text.mjs') &&
     lt.includes('bunx markdownlint-cli2') &&
     lt.includes('**/*.mdc') &&
     v8rTextOk &&
     (!globsRequired || globsOk)
   if (ok) {
-    passFn('package.json: lint-text — v8r: run-v8r.mjs (один виклик або чотири) або чотири bunx v8r з || [ $? -eq 98 ]')
+    passFn('package.json: lint-text — shellcheck (run-shellcheck-text.mjs), v8r: run-v8r.mjs або чотири bunx v8r')
   } else {
     failFn(
-      'package.json: lint-text — v8r: bun ./…/run-v8r.mjs або чотири (bunx v8r "<glob>" || [ $? -eq 98 ]) для json/yml/yaml/toml (див. n-text.mdc)'
+      'package.json: lint-text — додай bun ./…/run-shellcheck-text.mjs; v8r: bun ./…/run-v8r.mjs або чотири (bunx v8r "<glob>" || [ $? -eq 98 ]) (див. n-text.mdc)'
     )
   }
 }
@@ -407,7 +408,7 @@ async function checkCspellConfig(pass, fail) {
 }
 
 /**
- * Перевіряє відповідність проєкту правилам text.mdc (oxfmt, cspell, markdownlint через bunx, v8r)
+ * Перевіряє відповідність проєкту правилам text.mdc (oxfmt, cspell, shellcheck у lint-text, markdownlint через bunx, v8r)
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
  */
 export async function check() {

package/scripts/run-shellcheck-text.mjs

@@ -0,0 +1,193 @@
+/**
+ * Запуск shellcheck у ланцюжку lint-text: спочатку авто-застосування виправлень, потім фінальна перевірка.
+ *
+ * ShellCheck не має прапорця «--fix»; для виправлень, які інструмент уміє запропонувати, використовується
+ * формат виводу `diff` і застосування патчу через `patch -p1` у корені проєкту (шляхи у unified diff від ShellCheck
+ * узгоджуються з цим режимом).
+ *
+ * Якщо `shellcheck` відсутній у PATH, скрипт завершується з кодом 1 і друкує підказки встановлення
+ * (macOS: Homebrew; Debian/Ubuntu: apt; Arch: pacman). Аналогічно для `patch`, якщо його немає
+ * (рідко на macOS/Linux).
+ *
+ * Список файлів: у git-робочому дереві — `git ls-files` з pathspec `:(glob)` для всіх tracked `*.sh`;
+ * інакше — `globSync` з виключенням `node_modules`. Якщо скриптів не знайдено — вихід 0.
+ *
+ * Після циклу авто-виправлень виконується звичайний `shellcheck` по всіх зібраних файлах; будь-яке
+ * попередження чи помилка — ненульовий код виходу.
+ */
+import { spawnSync } from 'node:child_process'
+import { globSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { isRunAsCli } from './cli-entry.mjs'
+import { resolveCmd } from './utils/resolve-cmd.mjs'
+
+/** Підрядок у stderr ShellCheck, коли є зауваження, але без авто-виправлення у форматі diff. */
+const NON_AUTOFIXABLE_HINT = 'none were auto-fixable'
+
+/** Максимум ітерацій `diff`+`patch` на один файл (захист від зациклення). */
+const MAX_FIX_ROUNDS_PER_FILE = 32
+
+/**
+ * Друкує підказки встановлення shellcheck у stderr.
+ * @returns {void}
+ */
+function printShellcheckInstallHints() {
+  process.stderr.write(
+    [
+      '❌ shellcheck не знайдено в PATH.',
+      'Встанови інструмент і повтори lint-text:',
+      '  macOS:    brew install shellcheck',
+      '  Debian/Ubuntu: sudo apt-get install -y shellcheck',
+      '  Arch:     sudo pacman -S shellcheck',
+      ''
+    ].join('\n')
+  )
+}
+
+/**
+ * Друкує підказку для відсутнього patch.
+ * @returns {void}
+ */
+function printPatchInstallHints() {
+  process.stderr.write(
+    [
+      '❌ patch не знайдено в PATH (потрібен для застосування diff від shellcheck).',
+      '  macOS: patch зазвичай уже є; Debian/Ubuntu: sudo apt-get install -y patch',
+      ''
+    ].join('\n')
+  )
+}
+
+/**
+ * Повертає відносні шляхи до shell-скриптів для перевірки.
+ * @param {string} cwd корінь проєкту
+ * @returns {string[]} відсортований масив шляхів відносно cwd
+ */
+export function listShellScriptPaths(cwd) {
+  const gitOk = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+    cwd,
+    encoding: 'utf8',
+    env: process.env
+  })
+  if (gitOk.status === 0 && gitOk.stdout.trim() === 'true') {
+    const ls = spawnSync('git', ['ls-files', '-z', '--', ':(glob)**/*.sh'], {
+      cwd,
+      encoding: 'utf8',
+      env: process.env
+    })
+    if (ls.status !== 0) {
+      return []
+    }
+    const files = ls.stdout.split('\0').filter(Boolean)
+    return [...new Set(files)].sort()
+  }
+
+  const fromGlob = globSync('**/*.sh', {
+    cwd,
+    exclude: p =>
+      p.includes('node_modules') ||
+      p.startsWith(`node_modules/`) ||
+      p.split('/').includes('node_modules')
+  })
+  return [...new Set(fromGlob.map(p => p.replaceAll('\\', '/')))].sort()
+}
+
+/**
+ * Запускає shellcheck із авто-виправленнями і фінальною перевіркою.
+ * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
+ * @returns {number} 0 — OK; 1 — помилка середовища або залишкові зауваження shellcheck
+ */
+export function runShellcheckText(cwd = process.cwd()) {
+  const root = resolve(cwd)
+  const shellcheck = resolveCmd('shellcheck')
+  if (!shellcheck) {
+    printShellcheckInstallHints()
+    return 1
+  }
+  const patchBin = resolveCmd('patch')
+  if (!patchBin) {
+    printPatchInstallHints()
+    return 1
+  }
+
+  const files = listShellScriptPaths(root)
+  if (files.length === 0) {
+    return 0
+  }
+
+  for (const rel of files) {
+    for (let round = 0; round < MAX_FIX_ROUNDS_PER_FILE; round++) {
+      const diffResult = spawnSync(shellcheck, ['-f', 'diff', rel], {
+        cwd: root,
+        encoding: 'utf8',
+        env: process.env,
+        maxBuffer: 10 * 1024 * 1024
+      })
+
+      if (diffResult.error) {
+        process.stderr.write(`${diffResult.error.message}\n`)
+        return 1
+      }
+
+      const code = diffResult.status ?? 1
+      const out = (diffResult.stdout ?? '').trim()
+      const err = (diffResult.stderr ?? '').trim()
+
+      if (code === 0) {
+        break
+      }
+
+      if (err.includes(NON_AUTOFIXABLE_HINT) || !out) {
+        break
+      }
+
+      const patchRun = spawnSync(patchBin, ['-p1'], {
+        cwd: root,
+        input: diffResult.stdout ?? '',
+        encoding: 'utf8',
+        env: process.env
+      })
+
+      if (patchRun.status !== 0) {
+        if (patchRun.stderr?.length) {
+          process.stderr.write(patchRun.stderr)
+        }
+        if (patchRun.stdout?.length) {
+          process.stderr.write(patchRun.stdout)
+        }
+        process.stderr.write(`run-shellcheck-text: patch не застосував diff для ${rel}\n`)
+        return 1
+      }
+    }
+  }
+
+  const finalRun = spawnSync(shellcheck, files, {
+    cwd: root,
+    encoding: 'utf8',
+    env: process.env,
+    maxBuffer: 10 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  if (finalRun.error) {
+    process.stderr.write(`${finalRun.error.message}\n`)
+    return 1
+  }
+
+  if (finalRun.status !== 0) {
+    if (finalRun.stdout?.length) {
+      process.stdout.write(finalRun.stdout)
+    }
+    if (finalRun.stderr?.length) {
+      process.stderr.write(finalRun.stderr)
+    }
+    return 1
+  }
+
+  return 0
+}
+
+if (isRunAsCli()) {
+  process.exitCode = runShellcheckText()
+}