@nitra/cursor 1.8.135 → 1.8.138

package/mdc/capacitor.mdc

@@ -11,8 +11,28 @@ version: '1.0'
 **`*`**, `latest` і діапазони, де можлива 7-мажор, — неприйнятні. Програма перевірки — **`check-capacitor.mjs`**
 (репозиторій **@nitra/cursor**).
 
-## iOS: лише SPM
+## iOS: зазвичай лише SPM, виняток Podfile
 
-Нативний iOS-шар **не** повинен використовувати **CocoaPods** (наприклад файл **`Podfile`**
-поза каталогом `Pods/`) — **Swift Package Manager (SPM)**. Якщо каталога **`ios/`** немає, перевірка iOS
-у цьому кроці пропускається.
+- **Правило за замовчуванням:** не залишай `Podfile` (поза `Pods/`) у вихідному iOS-шарі, **якщо** уся потрібна
+  iOS-функціональність (нативні плагіни/модулі) може працювати **лише** через **SPM** (Swift Package Manager).
+
+- **Плагіни зі скоупу @nitra/:** за політикою вони **підтримуюють SPM**; **перевіряти** їх на **SPM** **не
+  потрібно** (і **check** цього **не** робить — **немає** обходу `package.json` на предмет **@nitra/**).
+
+- **Коли `Podfile` дозволений:** якщо **не** вся потрібна iOS-функціональність **поза** **@nitra/** (сторонні
+  **Capacitor**-плагіни, інша нативна залежність) **доступна** через **SPM** — `Podfile` **дозволяється**,
+  але це **обов’язково** треба явно задати в кореневому **`package.json`** або в
+  **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**
+
+  - **`"iosCocoaPodsBecausePluginsLackSpm": true`** (семантика: **не** **вся** потрібна нативна частина
+    **поза** **@nitra/** **на** **SPM**; **@nitra/** у це **не** входить);
+  - або **`"iosCocoaPodsAllowed": true`** (короткий **alias** для того самого **винятку**);
+
+  Без **одного** з цих прапорів `true` наявний **Podfile** поза **`Pods/`** вважається **порушенням** правила **«лише** **SPM**».
+
+- Перевірка читає **лише** кореневі файли: **`package.json`**, потім **capacitor-конфіги** у **корені** (див. вище).
+  У **`.ts` / `.mjs`**: шукається блок **nitra** `{ ... }` і **на його тілі** перевіряються ці **boolean**-поля.
+
+## Перевірка
+
+`npx @nitra/cursor check capacitor` (коли **check-скрипт** підключено до цієї **ruleset**).

package/mdc/docker.mdc

@@ -13,10 +13,13 @@ alwaysApply: false
 
 Також Dockerfile/Containerfile **має бути multistage build**: окремий build stage (залежності/компіляція) і окремий runtime stage. У фінальному stage дозволені лише мінімальні базові образи:
 
-- **backend**: `mirror.gcr.io/library/alpine:*`
-- **frontend**: `mirror.gcr.io/library/nginx:*` aбо `mirror.gcr.io/openresty/openresty:*`
+- **backend (типово)**: `mirror.gcr.io/library/alpine:*`
+- **ультра-легкі (glibc / одна статична збірка)**: `scratch` — тільки як `FROM scratch` (офіційний порожній базовий шар), коли весь **runtime** уже в `COPY --from=…`
+- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`
+- **виняток (інтерпретовані стеки)**: `mirror.gcr.io/library/php:*` або `mirror.gcr.io/library/python:*` — якщо сервіс має крутитися в офіційному runtime PHP чи Python, а не як один бінарник на Alpine; інакше лишай **alpine** у фінальному stage
+- **frontend**: `mirror.gcr.io/library/nginx:*` або `mirror.gcr.io/openresty/openresty:*`
 
-Це гарантує, що результуючий образ містить лише runtime (alpine) або nginx, без build tooling і node_modules.
+Це стримує зайвий build tooling (Bun, **node_modules** зі збірки) у фінальному образі; для **alpine** / **nginx** / **openresty** у **runtime** лишаються лише відповідні вимоги, для **php** / **python** (виняток) — цільовий інтерпретований **stack**; **scratch** і **debian** з тегом **`*slim*`** — коли glibc і мінімальне оточення Debian важливіші за musl в **alpine**.
 
 ## компіляція
 
@@ -182,7 +185,10 @@ jobs:
 ```yaml title=".hadolint.yaml"
 ignored:
   - DL3007
+  - DL3018
 ```
+Де DL3007 - «Не використовуй тег latest у FROM»
+Де DL3018 - «Піни версії пакетів у apk add»
 
 Якщо немає файлів у межах відповідного набору (**`lint-docker`** або **`check docker`**) — перевірка пропускається (exit 0).
 

package/package.json

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

package/scripts/check-capacitor.mjs

@@ -14,10 +14,12 @@
  * варто задати явний діапазон, наприклад **`^8.0.0`**. Якщо оголошено `capacitor.config.*` без жодного
  * **`@capacitor/core`** у дереві `package.json` — також помилка.
  *
- * **iOS лише через SPM (Swift Package Manager):** якщо в корні є каталог **`ios/`** — у ньому **не** має
- * бути файлів **Podfile** (CocoaPods) **поза** каталогом **Pods** (тобто не використовувати **Podfile**
- * у вихідному iOS-шарі; присутній **Podfile** — порушення). Якщо **немає** `ios/` — вимогу iOS у цьому
- * прогоні пропущено.
+ * **iOS:** зазвичай **без** **Podfile** поза **Pods** (тільки **SPM**). **@nitra/**-плагіни за політикою **SPM** —
+ * їх **не** перелічуємо й **не** перевіряємо. Якщо **Podfile** є, його можна зареєструвати як **виняток**
+ * (див. **capacitor.mdc**): у кореневому **`package.json`** або
+ * **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**, об’єкт **nitra** з
+ * **`iosCocoaPodsBecausePluginsLackSpm: true`** (або **`iosCocoaPodsAllowed: true`**); тоді **Podfile** **не** fail.
+ * Якщо **`ios/`** **немає** — iOS-умови не застосовуються.
  */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
@@ -41,9 +43,11 @@ const IGNORED_DIRS_FOR_PACKAGE_JSON = new Set([
 ])
 
 /** `||` у діапазоні npm-версій */
+// eslint-disable-next-line sonarjs/slow-regex -- короткі **semver**-підрядки у **package.json**
 const NPM_OR_PARTS_RE = /\s*\|\|\s*/
 
 /** `a - b` (діапазон діапазонів) */
+// eslint-disable-next-line sonarjs/slow-regex -- форма **X - Y** у **npm**-range
 const NPM_HYPHEN_RANGE_RE = /^(.+?)\s+-\s+(.+)$/
 
 const FIRST_VERSION_NUM_RE = /^(?:v)?(\d+)/i
@@ -52,6 +56,14 @@ const PREFIX_GEQ_RE = /^>=\s*/u
 const PREFIX_GT_RE = /^>\s*/u
 const STRIP_CARET_TILDE_EQ_RE = /^[=^~]+\s*/u
 
+/**
+ * Початок блока **nitra: {** у **.ts** / **.mjs** (**capacitor.config**; ключ **nitra**).
+ */
+const RE_NITRA_CONFIG_OBJECT_LEAD_IN = /\bnitra\b\s*:\s*\{|[\u0027"]nitra[\u0027"]\s*:\s*\{/
+
+const RE_COCOAPODS_EXEMPT_SPM = /\biosCocoaPodsBecausePluginsLackSpm\s*:\s*true\b/
+const RE_COCOAPODS_EXEMPT_ALLOW = /\biosCocoaPodsAllowed\s*:\s*true\b/
+
 /**
  * Мінімальний **major** (нижня межа) для **однієї** OR-частини діапазону npm (без `||` всередині).
  * @param {string} segment одна частина після `||` або весь рядок
@@ -158,6 +170,22 @@ function reportOneCapacitorCoreRange(fail, pass, rel, range) {
   }
 }
 
+/**
+ * @param {string} rel відносний шлях `package.json`
+ * @param {Record<string, unknown>} obj `dependencies` / `devDependencies` / **…**
+ * @param {{ byPath: Map<string, string>, anyCapacitor: boolean }} out накопичувач **@capacitor** у дереві
+ */
+function recordCapacitorFromDependencyObject(rel, obj, out) {
+  for (const [name, val] of Object.entries(obj)) {
+    if (typeof name === 'string' && name.startsWith('@capacitor/')) {
+      out.anyCapacitor = true
+    }
+    if (name === '@capacitor/core' && typeof val === 'string' && val !== '') {
+      out.byPath.set(rel, val)
+    }
+  }
+}
+
 /**
  * @param {string} absPath шлях до `package.json`
  * @param {string} root корінь репозиторію
@@ -181,15 +209,7 @@ export async function recordCapacitorFromOnePackageJson(absPath, root, out) {
   for (const block of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
     const rec = pkg?.[block]
     if (rec !== null && rec !== undefined && typeof rec === 'object' && !Array.isArray(rec)) {
-      const obj = /** @type {Record<string, unknown>} */ (rec)
-      for (const [name, val] of Object.entries(obj)) {
-        if (typeof name === 'string' && name.startsWith('@capacitor/')) {
-          out.anyCapacitor = true
-        }
-        if (name === '@capacitor/core' && typeof val === 'string' && val !== '') {
-          out.byPath.set(rel, val)
-        }
-      }
+      recordCapacitorFromDependencyObject(rel, /** @type {Record<string, unknown>} */ (rec), out)
     }
   }
 }
@@ -269,18 +289,18 @@ export async function walkIosForPodfileSkipPods(root, dir, onPodfileRelative) {
     return false
   }
   for (const e of entries) {
-    if (e.name !== 'Pods' && e.name !== 'build' && e.name !== 'DerivedData') {
+    if (e.name === 'Pods' || e.name === 'build' || e.name === 'DerivedData') {
+      // skip
+    } else if (e.isFile() === true && e.name === 'Podfile') {
+      const abs = join(dir, e.name)
+      onPodfileRelative((relative(root, abs) || abs).replaceAll('\\', '/'))
+      return true
+    } else if (e.isDirectory() === true) {
       const abs = join(dir, e.name)
-      if (e.isFile() && e.name === 'Podfile') {
-        onPodfileRelative((relative(root, abs) || abs).replaceAll('\\', '/'))
+      const found = await walkIosForPodfileSkipPods(root, abs, onPodfileRelative)
+      if (found === true) {
         return true
       }
-      if (e.isDirectory()) {
-        const found = await walkIosForPodfileSkipPods(root, abs, onPodfileRelative)
-        if (found) {
-          return true
-        }
-      }
     }
   }
   return false
@@ -304,6 +324,112 @@ export async function findFirstPodfileUnderIosExcludingPods(root) {
   return first
 }
 
+/**
+ * Чи дозволяє об’єкт **nitra** використання **Podfile** (CocoaPods) на iOS (див. **capacitor.mdc**; **@nitra/**
+ * **SPM** **не** аналізуємо).
+ * @param {unknown} o об’єкт **nitra** з **package.json** / **capacitor.config**
+ * @returns {boolean} **true** якщо **Podfile** дозволено (один з прапорів **true**)
+ */
+export function nitrAObjectAllowsIosCocoaPods(o) {
+  if (o === null || o === undefined || typeof o !== 'object' || Array.isArray(o)) {
+    return false
+  }
+  const r = /** @type {Record<string, unknown>} */ (o)
+  if (r.iosCocoaPodsBecausePluginsLackSpm === true) {
+    return true
+  }
+  if (r.iosCocoaPodsAllowed === true) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Витягає вихідний текст тіла **{ ... }** після **nitra:** / **"nitra":** у **config**-файлі (**ts** / **mjs**)
+ * (перша відповідність, баланс фігурних дужок).
+ * @param {string} source вміст **.ts** / **.mjs** config
+ * @returns {string | null} фрагмент **`{...}`** після **nitra:** або **null**
+ */
+function extractNitraObjectBodySource(source) {
+  const m = RE_NITRA_CONFIG_OBJECT_LEAD_IN.exec(source)
+  if (!m) {
+    return null
+  }
+  const openBrace = m.index + m[0].length - 1
+  let d = 0
+  for (let i = openBrace; i < source.length; i += 1) {
+    const c = source[i]
+    if (c === '{') {
+      d += 1
+    } else if (c === '}') {
+      d -= 1
+      if (d === 0) {
+        return source.slice(openBrace, i + 1)
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * @param {string} objectBody фрагмент **`{ ... }`** (текст)
+ * @returns {boolean} **true**, якщо в тілі є **iosCocoaPods**…**:** **true**
+ */
+function nitraObjectBodyStringAllowsCocoaPodsExempt(objectBody) {
+  return (
+    RE_COCOAPODS_EXEMPT_SPM.test(objectBody) === true || RE_COCOAPODS_EXEMPT_ALLOW.test(objectBody) === true
+  )
+}
+
+/**
+ * @param {string} absPath повний шлях до **JSON**-файла
+ * @returns {Promise<boolean>} **true**, якщо `obj.nitra` (ключ **nitra** у JSON) — виняток
+ */
+async function pathJsonShowsNitraCocoapodsExempt(absPath) {
+  if (existsSync(absPath) !== true) {
+    return false
+  }
+  try {
+    const t = await readFile(absPath, 'utf8')
+    const j = /** @type {Record<string, unknown>} */ (JSON.parse(t))
+    return nitrAObjectAllowsIosCocoaPods(j['nitra']) === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} root корінь репозиторію
+ * @returns {Promise<boolean>} **true**, якщо **.ts** / **.mjs** містить валідний виняток **nitra**
+ */
+async function capacitorConfigTsMjsNitraCocoapodsExempt(root) {
+  for (const name of ['capacitor.config.ts', 'capacitor.config.mjs']) {
+    const p = join(root, name)
+    if (existsSync(p) === true) {
+      const text = await readFile(p, 'utf8')
+      const body = extractNitraObjectBodySource(text)
+      if (body !== null && nitraObjectBodyStringAllowsCocoaPodsExempt(body) === true) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * @param {string} root корінь репозиторію (**process.cwd()** у **check**)
+ * @returns {Promise<boolean>} **true** якщо **Podfile** виправдано **nitra**-конфігом
+ */
+async function isIosCocoaPodsExemptByNitraConfig(root) {
+  if ((await pathJsonShowsNitraCocoapodsExempt(join(root, 'package.json'))) === true) {
+    return true
+  }
+  if ((await pathJsonShowsNitraCocoapodsExempt(join(root, 'capacitor.config.json'))) === true) {
+    return true
+  }
+  return capacitorConfigTsMjsNitraCocoapodsExempt(root)
+}
+
 /**
  * @returns {Promise<number>} **0** — **ok**; **1** — **fail** (див. **capacitor.mdc**)
  */
@@ -340,9 +466,13 @@ export async function check() {
     } else {
       pass('каталог ios/ не знайдено — вимогу iOS/SPM пропущено')
     }
+  } else if ((await isIosCocoaPodsExemptByNitraConfig(root)) === true) {
+    pass(
+      `iOS: Podfile «${podfileRel}» — дозволено виняток (nitra.iosCocoaPodsBecausePluginsLackSpm / iosCocoaPodsAllowed, capacitor.mdc)`
+    )
   } else {
     fail(
-      `iOS: знайдено Podfile «${podfileRel}» — для Capacitor використовуй лише SPM, без CocoaPods (прибери Podfile, capacitor.mdc)`
+      `iOS: знайдено Podfile «${podfileRel}» — для Capacitor використовуй лише SPM, без CocoaPods, або додай виняток nitra (capacitor.mdc)`
     )
   }
 

package/scripts/check-docker.mjs

@@ -5,8 +5,10 @@
  * вказуються через `mirror.gcr.io` (див. `utils/docker-mirror.mjs`).
  *
  * Також перевіряє, що Dockerfile/Containerfile має **multistage build** і що фінальний stage
- * використовує мінімальний runtime-образ:
- * - backend: `mirror.gcr.io/library/alpine:*`
+ * використовує дозволений runtime-образ (див. docker.mdc):
+ * - backend: `mirror.gcr.io/library/alpine:*`, `scratch`, `mirror.gcr.io/library/debian:` з тегом, що
+ *   містить `slim` (не повний `debian:bookworm`), за винятком PHP/Python — `mirror.gcr.io/library/php:*` або
+ *   `mirror.gcr.io/library/python:*`
  * - frontend: `mirror.gcr.io/library/nginx:*` або `mirror.gcr.io/openresty/openresty:*`
  *
  * Якщо в Dockerfile є крок `bun install` і це не frontend-образ (фінальний stage — alpine),
@@ -14,7 +16,7 @@
  * фінальному stage не повинно залишатися build tooling (Bun/Node).
  *
  * Мета — щоб у фінальному образі не було build tooling (Bun/Node та залежностей), а лише
- * runtime (alpine), nginx або openresty.
+ * дозволений runtime (alpine, scratch, debian slim, за потреби php/python, nginx або openresty).
  *
  * Знаходить Dockerfile, Dockerfile.*, Containerfile, Containerfile.*; пропускає node_modules, .git
  * тощо. Спочатку hadolint з PATH, інакше docker run з образом hadolint/hadolint.
@@ -84,10 +86,31 @@ export function parseFromStages(fileContent) {
 
 const RUNTIME_IMAGES = /** @type {const} */ ([
   'mirror.gcr.io/library/alpine',
+  'mirror.gcr.io/library/php',
+  'mirror.gcr.io/library/python',
   'mirror.gcr.io/library/nginx',
   'mirror.gcr.io/openresty/openresty'
 ])
 
+/** @type {RegExp} */
+const DEBIAN_VIA_MIRROR_RE = /^mirror\.gcr\.io\/library\/debian:(.+)$/i
+
+/**
+ * Чи ref фінального `FROM` відповідає дозволеним у docker.mdc (multistage / runtime).
+ * @param {string} lastLower ref без digest, lower case
+ * @returns {boolean}
+ */
+function isAllowedFinalRuntimeImage(lastLower) {
+  if (lastLower === 'scratch' || lastLower.startsWith('scratch:')) {
+    return true
+  }
+  const deb = lastLower.match(DEBIAN_VIA_MIRROR_RE)
+  if (deb) {
+    return deb[1].toLowerCase().includes('slim')
+  }
+  return RUNTIME_IMAGES.some(img => lastLower.startsWith(`${img}:`) || lastLower === img)
+}
+
 /**
  * Розбиває Dockerfile на stages за `FROM` (порожній масив, якщо FROM немає).
  * @param {string} fileContent вміст Dockerfile/Containerfile
@@ -113,7 +136,7 @@ export function splitDockerfileStages(fileContent) {
 /**
  * Перевіряє базові вимоги до структури Dockerfile:
  * - multistage: мінімум 2 FROM
- * - фінальний FROM: alpine/nginx/openresty з mirror.gcr.io
+ * - фінальний FROM: дозволені образи в docker.mdc (alpine, scratch, debian slim, php, python, nginx, openresty, …)
  * @param {string} fileContent вміст Dockerfile/Containerfile
  * @returns {string | null} повідомлення помилки або null
  */
@@ -129,9 +152,8 @@ export function getMultistageAndRuntimeHint(fileContent) {
   const lastImage = (last?.image || '').split('@')[0] || ''
   const lastLower = lastImage.toLowerCase()
 
-  const okRuntime = RUNTIME_IMAGES.some(img => lastLower.startsWith(`${img}:`) || lastLower === img)
-  if (!okRuntime) {
-    return `фінальний FROM має бути ${RUNTIME_IMAGES.join(' або ')} (runtime stage), зараз: ${last?.image} (рядок ${last?.line})`
+  if (!isAllowedFinalRuntimeImage(lastLower)) {
+    return `фінальний FROM має бути дозволеним runtime-образом (див. docker.mdc: multistage), зараз: ${last?.image} (рядок ${last?.line})`
   }
 
   return null

package/scripts/check-text.mjs

@@ -5,6 +5,7 @@
  * VSCode (formatOnSave, defaultFormatter для js/ts/json/vue/css/html),
  * відсутність Prettier у конфігах і залежностях.
  *
+ * cspell: `.cspell.json` з обовʼязковим набором `ignorePaths` (клон text.mdc: node_modules, vscode, git, report, svg, k8s yaml);
  * cspell, markdownlint через `bunx markdownlint-cli2` у `lint-text` (без оголошення пакета в package.json); у кореневих **`devDependencies`**
  * дозволені лише **`@nitra/*`** (як у bun.mdc), зокрема **`@nitra/cspell-dict` ^2.0.0+**; без імпорту **`@cspell/dict-*`** у `.cspell.json`, заборона
  * `markdownlint-cli2` у dependencies/devDependencies, v8r (`run-v8r.mjs` або чотири `bunx v8r`),
@@ -31,6 +32,17 @@ const UK_APOSTROPHE_HEADING = '**Український апостроф:**'
 /** Мінімальні glob-и в `ignorePatterns` у `.oxfmtrc.json` (text.mdc). */
 const OXFMT_REQUIRED_IGNORE_PATTERNS = ['**/hasura/metadata/**', '**/schema.graphql']
 
+/** Канонічні записи `ignorePaths` у `.cspell.json` (text.mdc) — кожен має бути присутнім. */
+const CSPELL_REQUIRED_IGNORE_PATHS = [
+  '**/node_modules/**',
+  '**/vscode-extension/**',
+  '**/.git/**',
+  '.vscode',
+  'report',
+  '*.svg',
+  '**/k8s/**/*.yaml',
+]
+
 /**
  * Чи діапазон версії `@nitra/cspell-dict` у package.json означає лінію 2.0.0+ (з цієї версії словники входять у пакет).
  * @param {string|undefined} range наприклад "^2.0.0"
@@ -384,6 +396,14 @@ async function checkCspellConfig(pass, fail) {
   } else {
     fail('.cspell.json не містить ignorePaths')
   }
+  if (Array.isArray(cfg.ignorePaths)) {
+    const missing = CSPELL_REQUIRED_IGNORE_PATHS.filter(p => !cfg.ignorePaths.includes(p))
+    if (missing.length === 0) {
+      pass(`.cspell.json ignorePaths містить усі обовʼязкові glob-и з text.mdc`)
+    } else {
+      fail(`.cspell.json ignorePaths бракує за замовчанням: ${missing.join(', ')} (див. text.mdc)`)
+    }
+  }
 }
 
 /**