@nitra/cursor 1.8.191 → 1.8.193

package/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.193] - 2026-05-07
+
+### Fixed
+
+- `check-image.mjs`: cleanup AVIF-сиріт більше не зачіпає `.avif` файли всередині пакетів з опт-аутом (`"@nitra/minify-image": { "disable-avif": true }`). Раніше: пакет з опт-аутом не сканувався на refs → його `.avif` потрапляли у список «сиріт» і видалялись, навіть якщо насправді використовувалися через alias / runtime-обчислений шлях. Тепер `checkVueAvifImports` повертає список абсолютних коренів opt-out пакетів, а `cleanupOrphanAvifs` пропускає `.avif` під ними.
+- `check-image.mjs`: запис у `.vue`/`.html` тепер строго послідовний з cleanup (write-then-cleanup): перший виконує `checkVueAvifImports` (per-file `writeFile` після обробки), і тільки після цього `cleanupOrphanAvifs` читає вже оновлені `usedAvifAbs` і видаляє лише дійсних сиріт.
+- `check-image.mjs`: введено агреговані лічильники `RewriteStats` (`rewrittenRefs` / `rewrittenFiles` / `failedRefs`) і єдиний фінальний рядок-підсумок `image: rewrote N references in M files; deleted K orphan AVIFs; failed to rewrite L references` — раніше підсумок дублювався per-package і не виокремлював orphan-cleanup vs failed-rewrites.
+
+### Added
+
+- `tests/check-image.test.mjs`: 5 нових кейсів — статичний `<img src="a.png">` авто-переписується (за наявності `a.png` і `a.png.avif`); реактивне `:src="dyn"` залишається незмінним і orphan AVIF видаляється; змішані форми у одному файлі (статичний + import + реактивний + `data-src=`) — переписуються лише покривані; opt-out пакет — AVIF всередині не вважається сиротою; ідемпотентність повторного `check image` на чистому стані.
+
+## [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.193",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/check-image.mjs

@@ -250,13 +250,26 @@ function resolveImagePath(importPath, sourceAbsPath) {
   return null
 }
 
+/**
+ * Аґреговані лічильники по проходу `check image`:
+ *   - `rewrittenRefs` — скільки конкретних посилань (по одному на match) переписано на `.avif`;
+ *   - `rewrittenFiles` — у скількох `.vue`/`.html` файлах хоч одне посилання змінилося;
+ *   - `failedRefs` — скільки конкретних посилань не вдалося переписати (`.avif` не існував).
+ * @typedef {object} RewriteStats
+ * @property {number} rewrittenRefs
+ * @property {number} rewrittenFiles
+ * @property {number} failedRefs
+ */
+
 /**
  * Сканує `.vue` і `.html` файли одного workspace-пакета: де можемо, переписує raster-посилання
- * на `<path>.avif`, де не можемо — фейлимо. Повертає множину `.avif`-двійників, на які
- * лишилось живе посилання після проходу — потрібно для подальшого прибирання сиріт.
+ * на `<path>.avif`, де не можемо — фейлимо. Доповнює `usedAvifAbs` шляхами AVIF-двійників, на
+ * які лишилось живе посилання, і `stats` лічильниками rewrite/fail для глобального підсумку.
  *
  * Заміна виконується ТІЛЬКИ якщо AVIF-двійник реально існує на диску. Якщо AVIF немає
  * (наприклад, оригіналу теж немає, тож `--avif` його не згенерував) — фейл, як раніше.
+ * Запис файла відбувається ОДРАЗУ після обробки одного файла (write-then-fail): провал на
+ * наступному файлі НЕ відкочує вже записані зміни попередніх.
  *
  * Файли, що належать іншим workspace-пакетам, ігноруються — кожен пакет перевіряється рівно
  * один раз (інакше при обході кореня `.` ми б повторно зайшли в `demo/` і подвоїли звіти).
@@ -265,11 +278,11 @@ function resolveImagePath(importPath, sourceAbsPath) {
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`, що мають
  * хоч одне посилання у `.vue`/`.html` (доповнюється у цій функції)
- * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {RewriteStats} stats глобальні лічильники, що мутуються тут
  * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<void>} резолвиться по завершенню перевірки одного пакета
  */
-async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, usedAvifAbs, pass, fail) {
+async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, usedAvifAbs, stats, fail) {
   const absRoot = join(process.cwd(), packageRoot)
   const label = packageRoot === '.' ? 'корінь' : packageRoot
   /** @type {string[]} */
@@ -285,8 +298,6 @@ async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePa
   )
   if (targetFiles.length === 0) return
 
-  let violations = 0
-  let replacements = 0
   for (const absPath of targetFiles) {
     const rel = relative(process.cwd(), absPath).split('\\').join('/')
     const original = await readFile(absPath, 'utf8')
@@ -302,11 +313,11 @@ async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePa
         const replaced = full.replace(importPath, newImportPath)
         const imageAbs = resolveImagePath(importPath, absPath)
         if (imageAbs && existsSync(`${imageAbs}.avif`)) {
-          replacements++
+          stats.rewrittenRefs++
           usedAvifAbs.add(`${imageAbs}.avif`)
           return replaced
         }
-        violations++
+        stats.failedRefs++
         fail(renderFailure(importPath))
         return full
       })
@@ -333,28 +344,34 @@ async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePa
 
     if (updated !== original) {
       await writeFile(absPath, updated, 'utf8')
+      stats.rewrittenFiles++
     }
   }
-  if (violations === 0) {
-    const summary = replacements > 0 ? `усі raster-посилання у .vue/.html переписано на .avif (замін: ${replacements})` : 'усі raster-посилання у .vue/.html вже на .avif (або відсутні)'
-    pass(`[${label}] ${summary}`)
-  }
 }
 
 /**
  * Сканує всі workspace-пакети: для кожного перевіряє opt-out і за потреби викликає
  * перевірку Vue-imports. Перевірка пропускається, якщо в репозиторії немає workspaces
  * або немає `.vue`-файлів — тоді `image` правило не для цього проєкту.
+ *
+ * Повертає список абсолютних коренів пакетів, у яких ввімкнено opt-out (`disable-avif: true`).
+ * Це окремий результат, бо AVIF всередині такого пакета НЕ можна вважати «сиротою» лише
+ * на підставі відсутності посилань у його `.vue`/`.html` (ми взагалі не сканували його
+ * шаблони) — інакше cleanup помилково затирав би AVIF, що використовуються через alias /
+ * runtime-обчислений шлях / зовнішні посилання, які тут не видно.
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`-двійників,
  * на які лишилось хоча б одне посилання у `.vue`/`.html` (заповнюється у викликаних функціях)
+ * @param {RewriteStats} stats глобальні лічильники rewrite/fail (мутуються нижче)
  * @param {(msg: string) => void} pass callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
- * @returns {Promise<void>} резолвиться по завершенню перевірки всіх workspace-пакетів
+ * @returns {Promise<string[]>} абсолютні шляхи коренів пакетів з активним opt-out
  */
-async function checkVueAvifImports(ignorePaths, usedAvifAbs, pass, fail) {
+async function checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail) {
   const roots = await getMonorepoPackageRootDirs()
   const absRootsByRel = new Map(roots.map(r => [r, join(process.cwd(), r)]))
+  /** @type {string[]} */
+  const optedOutAbs = []
   for (const root of roots) {
     const pkgPath = join(root, 'package.json')
     if (!existsSync(pkgPath)) continue
@@ -363,11 +380,13 @@ async function checkVueAvifImports(ignorePaths, usedAvifAbs, pass, fail) {
       pass(
         `[${root === '.' ? 'корінь' : root}] avif-import enforcement вимкнено через "@nitra/minify-image.disable-avif"`
       )
+      optedOutAbs.push(absRootsByRel.get(root) ?? join(process.cwd(), root))
       continue
     }
     const otherRootsAbs = roots.filter(r => r !== root && r !== '.').map(r => absRootsByRel.get(r) ?? '')
-    await checkVueAvifImportsInPackage(root, otherRootsAbs, ignorePaths, usedAvifAbs, pass, fail)
+    await checkVueAvifImportsInPackage(root, otherRootsAbs, ignorePaths, usedAvifAbs, stats, fail)
   }
+  return optedOutAbs
 }
 
 /**
@@ -423,12 +442,18 @@ function runAvifGeneration() {
  * Видаляє AVIF-сироти — `<...>.avif` файли, на які не лишилось жодного посилання
  * у `.vue`/`.html` репозиторію. Реалізує умову правила: «AVIF лишається лише там,
  * де заміна реально вдалася».
+ *
+ * AVIF файли всередині opt-out пакетів (`disable-avif: true`) пропускаються — ми не
+ * сканували їх шаблони, тож не маємо права вважати їх AVIF сиротами. Це гарантує
+ * ідемпотентність повторного `check image` для пакетів, що навмисно вимкнули правило
+ * (наприклад, мобільний бандл, де AVIF підтримка не гарантована).
  * @param {Set<string>} usedAvifAbs абсолютні шляхи `.avif`, що мають живі посилання
+ * @param {string[]} optedOutAbs абсолютні шляхи коренів пакетів з опт-аутом —
+ * `.avif` під ними не вважаємо сиротами і не видаляємо
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
- * @param {(msg: string) => void} pass callback при успішній перевірці
- * @returns {Promise<void>} резолвиться після видалення всіх сиріт
+ * @returns {Promise<number>} кількість видалених сиріт
  */
-async function cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass) {
+async function cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths) {
   /** @type {string[]} */
   const orphans = []
   await walkDir(
@@ -436,6 +461,7 @@ async function cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass) {
     absPath => {
       if (!absPath.endsWith('.avif')) return
       if (usedAvifAbs.has(absPath)) return
+      if (optedOutAbs.some(root => absPath === root || absPath.startsWith(`${root}/`))) return
       orphans.push(absPath)
     },
     ignorePaths
@@ -443,9 +469,7 @@ async function cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass) {
   for (const absPath of orphans) {
     await unlink(absPath)
   }
-  if (orphans.length > 0) {
-    pass(`видалено AVIF-сиріт без посилань у .vue/.html: ${orphans.length}`)
-  }
+  return orphans.length
 }
 
 /**
@@ -493,8 +517,16 @@ export async function check() {
 
   /** @type {Set<string>} */
   const usedAvifAbs = new Set()
-  await checkVueAvifImports(ignorePaths, usedAvifAbs, pass, fail)
-  await cleanupOrphanAvifs(usedAvifAbs, ignorePaths, pass)
+  /** @type {RewriteStats} */
+  const stats = { rewrittenRefs: 0, rewrittenFiles: 0, failedRefs: 0 }
+  const optedOutAbs = await checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail)
+  const orphansDeleted = await cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths)
+
+  pass(
+    `image: rewrote ${stats.rewrittenRefs} reference${stats.rewrittenRefs === 1 ? '' : 's'} in ${stats.rewrittenFiles} file${stats.rewrittenFiles === 1 ? '' : 's'}; ` +
+      `deleted ${orphansDeleted} orphan AVIF${orphansDeleted === 1 ? '' : 's'}; ` +
+      `failed to rewrite ${stats.failedRefs} reference${stats.failedRefs === 1 ? '' : 's'}`
+  )
 
   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()
+}