@nitra/cursor 1.8.191 → 1.8.192

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 Формат — [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

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.191",
+  "version": "1.8.192",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

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()
+}