@nitra/cursor 3.22.0 → 3.23.1

package/scripts/lib/docs/gha-workflow.md

@@ -0,0 +1,326 @@
+# gha-workflow.mjs
+
+## Огляд
+
+Модуль `gha-workflow.mjs` — це набір допоміжних чистих функцій для **структурного аналізу GitHub Actions workflow-файлів** (`.yml`) після їх розбору як YAML.
+
+Призначення модуля — замінити крихкий пошук підрядків у сирому тексті workflow-файла на **типобезпечну** перевірку значень `uses:` та `run:` у кроках (`steps`) робіт (`jobs`). Модуль використовується сценаріями перевірки (checkers) проєктних правил:
+
+- `check-ga` — загальна перевірка GitHub Actions workflows;
+- `check-js-lint` — перевірка структури `lint-js.yml`;
+- `check-text` — перевірка наявності викликів `bun run lint-text` у CI;
+- `check-style-lint` — перевірка викликів стайл-лінту в CI;
+- `check-npm-module` — перевірка workflow npm-модуля.
+
+Крім перевірки значень `uses:` та `run:`, модуль уміє:
+
+- розпізнавати локальну composite-action `./.github/actions/setup-bun-deps`;
+- перевіряти, що `actions/checkout@v6` викликається з `with.persist-credentials: false`;
+- виявляти заборонені в CI прапорці `--fix` у викликах `oxlint` та `eslint`;
+- перевіряти включення точного `glob` у списки `on.push.paths` / `on.pull_request.paths`.
+
+Модуль виконує лише читання та обчислення — він **не змінює** жодних файлів і **не виконує** жодних команд. Поведінка детермінована й залежить тільки від переданих аргументів.
+
+## Експорти / API
+
+Усі експорти з модуля — це **named exports** (іменовані експорти), `default export` немає.
+
+| Експорт                                      | Тип      | Короткий опис                                                                            |
+| -------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `parseWorkflowYaml(content)`                 | function | Парсить YAML вміст у звичайний об’єкт; при помилці повертає `null`.                      |
+| `flattenWorkflowSteps(root)`                 | function | Збирає всі кроки з усіх jobs у плоский список з метаданими `{ jobId, stepIndex, step }`. |
+| `getStepUses(step)`                          | function | Повертає значення `uses:` кроку або порожній рядок.                                      |
+| `getStepRun(step)`                           | function | Повертає значення `run:` кроку (підтримує рядок та масив рядків).                        |
+| `eventPathsIncludeExact(root, event, exact)` | function | Перевіряє, чи містить `on.<event>.paths` точне значення glob.                            |
+| `verifyLintJsWorkflowStructure(root)`        | function | Виконує повний набір структурних перевірок для `lint-js.yml`.                            |
+| `anyRunStepIncludes(root, needle)`           | function | Перевіряє, чи містить будь-який `run` кроку заданий підрядок.                            |
+
+Внутрішні (неекспортовані) функції-помічники:
+
+- `workflowJobsEntries(root)` — повертає `[jobId, job][]`;
+- `workflowJobSteps(job)` — повертає масив об’єктних кроків job;
+- `hasCheckoutWithPersistCredentialsFalse(steps)` — перевіряє `checkout@v6` з `persist-credentials: false`;
+- `appendCiFixFlagFailures(failures, steps)` — додає у `failures` рядки про заборонені `--fix` у CI.
+
+Внутрішні константи модуля:
+
+- `CHECKOUT_V6_USES = 'actions/checkout@v6'` — очікувана дія checkout та її версія.
+- `LOCAL_SETUP_BUN_DEPS_MARKER = './.github/actions/setup-bun-deps'` — шлях до локальної composite-action для встановлення Bun-залежностей.
+- `BUNX_OXLINT_FIX_RE = /bunx\s+oxlint[^\n]*--fix/u` — регулярний вираз для виявлення `bunx oxlint ... --fix` в одному рядку.
+
+## Функції
+
+### `parseWorkflowYaml(content)`
+
+**Сигнатура:** `parseWorkflowYaml(content: string): Record<string, unknown> | null`
+
+**Параметри:**
+
+- `content` — рядок із вмістом workflow-файла `.yml`.
+
+**Повертає:**
+
+- розібраний YAML як звичайний об’єкт (`Record<string, unknown>`), якщо вміст парситься і має тип `object` та не є `null`;
+- `null` — якщо `yaml.parse` кинув виняток або результат не є об’єктом.
+
+**Side effects:** немає. Помилка парсингу мовчки перехоплюється `try/catch`.
+
+**Примітки:** ця функція безпечна для викликача — навіть на некоректному YAML вона не падає, а повертає `null`, що далі обробляється у `verifyLintJsWorkflowStructure` як спеціальний випадок.
+
+---
+
+### `flattenWorkflowSteps(root)`
+
+**Сигнатура:** `flattenWorkflowSteps(root: Record<string, unknown>): { jobId: string, stepIndex: number, step: Record<string, unknown> }[]`
+
+**Параметри:**
+
+- `root` — корінь розібраного YAML (об’єкт із полем `jobs`).
+
+**Повертає:** плоский масив об’єктів, кожен з яких містить:
+
+- `jobId` — ім’я job (ключ у `jobs`);
+- `stepIndex` — порядковий номер кроку всередині `steps` цього job (починається з 0);
+- `step` — сам об’єкт кроку.
+
+**Side effects:** немає.
+
+**Алгоритм:** ітерує через `workflowJobsEntries(root)`, для кожного job отримує `workflowJobSteps(job)`, нумерує кроки за допомогою `Array.prototype.entries()` та пуш у акумулятор. Невалідні (необ’єктні) jobs та невалідні steps пропускаються.
+
+---
+
+### `getStepUses(step)`
+
+**Сигнатура:** `getStepUses(step: Record<string, unknown>): string`
+
+**Параметри:**
+
+- `step` — об’єкт одного елемента масиву `steps`.
+
+**Повертає:** значення `step.uses`, якщо це рядок; інакше — порожній рядок `''`.
+
+**Side effects:** немає.
+
+**Призначення:** уніфікований доступ до значення `uses:` без перевірок типу у викликачів.
+
+---
+
+### `getStepRun(step)`
+
+**Сигнатура:** `getStepRun(step: Record<string, unknown>): string`
+
+**Параметри:**
+
+- `step` — об’єкт одного елемента масиву `steps`.
+
+**Повертає:** текст команди `run:`:
+
+- якщо `step.run` — рядок, повертається як є;
+- якщо `step.run` — масив, кожен елемент конвертується через `String(...)` та з’єднується через `\n`;
+- інакше — `''`.
+
+**Side effects:** немає.
+
+**Примітки:** YAML дозволяє запис `run:` як багаторядкового скаляра (`|` / `>-`) або як масиву рядків. Функція нормалізує обидва випадки до одного `string`, який потім зручно перевіряти через `.includes(...)` або регулярним виразом.
+
+---
+
+### `eventPathsIncludeExact(root, event, exact)`
+
+**Сигнатура:** `eventPathsIncludeExact(root: Record<string, unknown>, event: 'push' | 'pull_request', exact: string): boolean`
+
+**Параметри:**
+
+- `root` — корінь workflow;
+- `event` — ім’я ключа в `on`: `'push'` або `'pull_request'`;
+- `exact` — очікуваний рядок (glob), який має бути присутній у `paths`.
+
+**Повертає:** `true`, якщо у `root.on[event].paths` є масив і він містить точне значення `exact`. У всіх інших випадках (відсутній `on`, відсутній `event`, `paths` не масив тощо) — `false`.
+
+**Side effects:** немає.
+
+**Гарантії безпеки:** функція захищена від відсутніх та некоректних типів проміжних об’єктів, тому її можна викликати на будь-якому `root`, повернутому з `parseWorkflowYaml`.
+
+---
+
+### `verifyLintJsWorkflowStructure(root)`
+
+**Сигнатура:** `verifyLintJsWorkflowStructure(root: Record<string, unknown> | null): { ok: boolean, failures: string[] }`
+
+**Параметри:**
+
+- `root` — корінь розібраного workflow або `null`, якщо парсинг не вдався.
+
+**Повертає:** об’єкт результату:
+
+- `{ ok: true, failures: [] }` — усі перевірки пройдено;
+- `{ ok: false, failures: [...] }` — список причин відмови у вигляді людинозрозумілих українських повідомлень.
+
+**Side effects:** немає.
+
+**Перевірки, які виконуються (у порядку додавання до `failures`):**
+
+1. Якщо `root === null` — повертається одразу `{ ok: false, failures: ['YAML не вдалося розібрати — перевір синтаксис workflow'] }`.
+2. У жодному кроці немає `uses:` з підрядком `'actions/checkout@v6'` → `'немає кроку uses: actions/checkout@v6'`.
+3. Серед кроків з `actions/checkout@v6` немає такого, що містить `with.persist-credentials === false` → `'checkout@v6 без with.persist-credentials: false'`.
+4. У жодному кроці немає `uses:` з підрядком `'./.github/actions/setup-bun-deps'` → `'немає uses: ./.github/actions/setup-bun-deps'`.
+5. У сумарному `run`-блобі немає `'bunx oxlint'` → `'у run немає bunx oxlint'`.
+6. У сумарному `run`-блобі немає `'bunx eslint .'` → `'у run немає bunx eslint .'`.
+7. У сумарному `run`-блобі немає `'bunx jscpd .'` → `'у run немає bunx jscpd .'`.
+8. Для кожного кроку, чий `run` матчиться `BUNX_OXLINT_FIX_RE`, додається `'у run є oxlint з --fix (у CI заборонено)'`.
+9. Для кожного кроку, чий `run` містить `'eslint --fix'`, додається `'у run є eslint --fix (у CI заборонено)'`.
+
+**Примітка:** «сумарний `run`-блоб» — це `flattenWorkflowSteps(root).map(s => getStepRun(s.step)).join('\n')`. Тобто перевірки 5–7 пасять, навіть якщо `bunx oxlint`, `bunx eslint .` та `bunx jscpd .` рознесені по різних кроках.
+
+---
+
+### `anyRunStepIncludes(root, needle)`
+
+**Сигнатура:** `anyRunStepIncludes(root: Record<string, unknown>, needle: string): boolean`
+
+**Параметри:**
+
+- `root` — корінь workflow;
+- `needle` — підрядок для пошуку в текстах `run:`.
+
+**Повертає:** `true`, якщо знайдено принаймні один крок, у `run:` якого є `needle`; інакше `false`.
+
+**Side effects:** немає. Ітерація припиняється на першому збігу (рання передача).
+
+**Типовий приклад:** `anyRunStepIncludes(root, 'bun run lint-text')` для `check-text` — перевірити, що CI взагалі викликає таргет лінту текстів.
+
+---
+
+### `workflowJobsEntries(root)` (internal)
+
+**Сигнатура:** `workflowJobsEntries(root: Record<string, unknown>): [string, Record<string, unknown>][]`
+
+**Параметри:** `root` — корінь workflow.
+
+**Повертає:** список пар `[jobId, job]` для тих ключів `jobs`, у яких значення є непорожнім об’єктом.
+
+**Side effects:** немає.
+
+**Алгоритм:** перевіряє наявність та тип `root.jobs`, далі `Object.entries(jobs).flatMap(...)` фільтрує невалідні значення (масив порожніх або одно-елементних масивів).
+
+---
+
+### `workflowJobSteps(job)` (internal)
+
+**Сигнатура:** `workflowJobSteps(job: Record<string, unknown>): Record<string, unknown>[]`
+
+**Параметри:** `job` — один job-об’єкт.
+
+**Повертає:** масив об’єктних кроків з `job.steps`; невалідні (необ’єктні / `null`) елементи фільтруються.
+
+**Side effects:** немає.
+
+---
+
+### `hasCheckoutWithPersistCredentialsFalse(steps)` (internal)
+
+**Сигнатура:** `hasCheckoutWithPersistCredentialsFalse(steps: { step: Record<string, unknown> }[]): boolean`
+
+**Параметри:** `steps` — результат `flattenWorkflowSteps` (використовується тільки поле `step`).
+
+**Повертає:** `true`, якщо знайдено крок, у якого:
+
+- `uses` містить `'actions/checkout@v6'`;
+- `step.with` — об’єкт;
+- `step.with['persist-credentials'] === false` (саме `false`, а не «фолсі»).
+
+**Side effects:** немає.
+
+**Призначення:** перевірити, що `actions/checkout@v6` явно вимкнув збереження токена в git-конфізі — це вимога безпеки в правилі `n-ga`.
+
+---
+
+### `appendCiFixFlagFailures(failures, steps)` (internal)
+
+**Сигнатура:** `appendCiFixFlagFailures(failures: string[], steps: { step: Record<string, unknown> }[]): void`
+
+**Параметри:**
+
+- `failures` — акумулятор-масив, у який функція **пушить** нові рядки помилок;
+- `steps` — результат `flattenWorkflowSteps`.
+
+**Повертає:** `undefined` (мутує `failures`).
+
+**Side effects:** мутація переданого масиву `failures` через `Array.prototype.push`.
+
+**Логіка:** для кожного кроку:
+
+- якщо `BUNX_OXLINT_FIX_RE.test(run)` — додає повідомлення про заборонений `--fix` у `bunx oxlint`;
+- якщо `run.includes('eslint --fix')` — додає повідомлення про заборонений `eslint --fix`.
+
+**Примітка:** функція може додати **обидва** повідомлення для одного і того ж кроку, якщо в `run` присутні обидва патерни. Якщо в різних кроках присутній один і той самий патерн — повідомлення додасться **кілька разів** (по одному на крок).
+
+## Залежності
+
+**Зовнішні npm-пакети:**
+
+- `yaml` — функція `parse(content)` для розбору YAML у JS-об’єкт. Імпорт іменований: `import { parse } from 'yaml'`.
+
+**Стандартна бібліотека JS:** `Object.entries`, `Array.isArray`, `Array.prototype.flatMap`, `Array.prototype.map`, `Array.prototype.entries`, `Array.prototype.some`, `Array.prototype.includes`, `Array.prototype.join`, `RegExp.prototype.test`, `String.prototype.includes`.
+
+**Внутрішні залежності проєкту:** жодних модулів проєкту не імпортує — це листовий хелпер.
+
+**Хто залежить від цього модуля (зворотні залежності):** згідно з docstring файла — скрипти `check-ga`, `check-js-lint`, `check-text`, `check-style-lint`, `check-npm-module`. Конкретні шляхи до цих скриптів живуть у `npm/scripts/` / `npm/checks/` та використовують іменовані експорти модуля.
+
+## Потік виконання / Використання
+
+### Типовий цикл використання сценарієм-checker
+
+1. Сценарій читає вміст файла `.github/workflows/<name>.yml` як рядок (наприклад через `node:fs/promises`).
+2. Викликає `const root = parseWorkflowYaml(content)`.
+3. Якщо `root === null` — повідомляє про синтаксичну помилку YAML.
+4. Інакше викликає одну зі спеціалізованих перевірок (наприклад `verifyLintJsWorkflowStructure(root)`) або серію загальних (`flattenWorkflowSteps`, `getStepUses`, `getStepRun`, `anyRunStepIncludes`, `eventPathsIncludeExact`).
+5. На основі результату формує звіт перевірки.
+
+### Приклад: перевірка `lint-js.yml`
+
+```js
+import { readFile } from 'node:fs/promises'
+import { parseWorkflowYaml, verifyLintJsWorkflowStructure } from './gha-workflow.mjs'
+
+const content = await readFile('.github/workflows/lint-js.yml', 'utf8')
+const root = parseWorkflowYaml(content)
+const result = verifyLintJsWorkflowStructure(root)
+
+if (!result.ok) {
+  for (const f of result.failures) {
+    console.error('lint-js.yml:', f)
+  }
+  process.exit(1)
+}
+```
+
+### Приклад: перевірка наявності таргета `bun run lint-text`
+
+```js
+import { parseWorkflowYaml, anyRunStepIncludes } from './gha-workflow.mjs'
+
+const root = parseWorkflowYaml(content)
+if (root && !anyRunStepIncludes(root, 'bun run lint-text')) {
+  console.error('у CI відсутній виклик bun run lint-text')
+}
+```
+
+### Приклад: перевірка `on.pull_request.paths`
+
+```js
+import { parseWorkflowYaml, eventPathsIncludeExact } from './gha-workflow.mjs'
+
+const root = parseWorkflowYaml(content)
+if (root && !eventPathsIncludeExact(root, 'pull_request', '**/*.vue')) {
+  console.error('on.pull_request.paths не містить **/*.vue')
+}
+```
+
+### Властивості, корисні викликачам
+
+- **Чисті функції.** Жодних бічних ефектів (крім явної мутації `failures` в `appendCiFixFlagFailures`, яка інкапсульована всередині `verifyLintJsWorkflowStructure`).
+- **Безпечність до помилок типів.** Усі публічні функції захищені від некоректних або відсутніх ключів — повертають `''`, `false` або `[]` замість падіння.
+- **Уніфікований доступ.** `getStepUses` та `getStepRun` нормалізують форму YAML (рядок vs масив), щоб викликач завжди працював із `string`.
+- **Точне `paths`-зіставлення.** `eventPathsIncludeExact` вимагає **точного** елемента масиву, а не підрядка — тому glob-патерни мають бути записані як є.
+- **Сумарний `run`-блоб.** У `verifyLintJsWorkflowStructure` пункти 5–7 не вимагають, щоб усі команди жили в одному `run`-кроці — вони можуть бути рознесені по кроках/jobs.

package/scripts/lib/docs/inline-template-links.md

@@ -0,0 +1,303 @@
+# inline-template-links.mjs
+
+## Огляд
+
+Модуль `inline-template-links.mjs` — допоміжна утиліта для **build-кроку обробки `.mdc`-правил**. Її роль: у текстовому вмісті `.mdc`-документа знайти Markdown-посилання, які ведуть на template-файли (шлях містить сегмент `/template/` або `/templates/`), і **замінити** ці посилання на **інлайн fenced-блоки** з фактичним вмістом target-файлу.
+
+Простими словами: замість того щоб у згенерованому правилі читач бачив посилання `[конфіг](./templates/package.json.snippet.json)`, він побачить безпосередньо назву реального файлу (`package.json`) і fenced-блок із його вмістом — це робить правило «самодостатнім», без потреби клікати по лінках.
+
+Особливості:
+
+- Працює асинхронно (`async`), бо читає файли через `node:fs/promises`.
+- Робить **fail-loud** валідацію: якщо посилання вказує на неіснуючий файл — кидає `Error` (а не мовчки пропускає), щоб автор правила одразу побачив проблему.
+- «Розгортає» спеціальні суфікси `.snippet.<ext>` / `.deny.<ext>` / `.contains.<ext>` до імені реального target-файлу, який вони описують (наприклад `package.json.snippet.json` → `package.json`).
+- Безпечно щодо ReDoS: усі regexp — статичні літерали з обмеженням довжини, без `new RegExp(variable)` із користувацьких даних.
+
+Модуль експортує єдину функцію `inlineTemplateLinks(text, ruleDir)`.
+
+## Експорти / API
+
+| Експорт               | Тип                                                              | Призначення                                                                                                         |
+| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `inlineTemplateLinks` | `async function(text: string, ruleDir: string): Promise<string>` | Замінює Markdown-посилання на template-файли в `.mdc`-тексті на інлайн fenced-блоки з фактичним вмістом цих файлів. |
+
+Усі інші імена в модулі (`langFromExt`, `normalizeTargetName`, константи `MD_LINK_RE`, `TEMPLATE_SEGMENT_RE`, `SLOT_SUFFIX_RES`) — **внутрішні** (не експортуються).
+
+## Внутрішні константи
+
+### `MD_LINK_RE`
+
+```js
+;/\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g
+```
+
+Глобальний regexp, який ловить **Markdown-посилання вигляду `[label](./path)`** із обов'язковим префіксом `./` у href. Group 1 — текст посилання (до 200 символів), group 2 — шлях (до 500 символів, що починається з `./`). Обмеження довжин — захист від ReDoS / pathological input.
+
+### `TEMPLATE_SEGMENT_RE`
+
+```js
+;/\/templates?\//
+```
+
+Перевіряє, чи шлях містить сегмент `/template/` або `/templates/`. Тільки такі посилання вважаються «template-посиланнями» і підлягають заміні; інші Markdown-лінки залишаються недоторканими.
+
+### `SLOT_SUFFIX_RES`
+
+Масив із трьох **статичних** regexp:
+
+```js
+;[/^(.+)\.snippet\.[^.]+$/, /^(.+)\.deny\.[^.]+$/, /^(.+)\.contains\.[^.]+$/]
+```
+
+Кожен ловить ім'я файлу з суфіксом-«слотом»: `<name>.snippet.<ext>`, `<name>.deny.<ext>`, `<name>.contains.<ext>`. Group 1 — це ім'я реального target-файлу (без суфікса слоту і без власного розширення). Коментар у коді явно зазначає: regexp-літерали статичні, без `RegExp(variable)`.
+
+## Функції
+
+### `langFromExt(filePath)` — internal
+
+Сигнатура:
+
+```js
+function langFromExt(filePath: string): string
+```
+
+Параметри:
+
+- `filePath` — рядок зі шляхом до файлу (досить навіть базового імені, бо використовується лише розширення).
+
+Повертає:
+
+- Рядок-ідентифікатор мови для Markdown fenced-блока:
+  - `'json'` — якщо розширення `.json`;
+  - `'toml'` — якщо `.toml`;
+  - `'yaml'` — якщо `.yml` або `.yaml`;
+  - `''` (порожній рядок) — для будь-яких інших розширень.
+
+Side effects: жодних — чиста функція над рядком.
+
+Призначення: визначити, який мовний таг ставити після відкривального ` ``` ` у згенерованому fenced-блоці, щоб підсвічування синтаксису працювало коректно.
+
+### `normalizeTargetName(fileBasename)` — internal
+
+Сигнатура:
+
+```js
+function normalizeTargetName(fileBasename: string): string
+```
+
+Параметри:
+
+- `fileBasename` — базове ім'я файлу (без шляху), наприклад `package.json.snippet.json`.
+
+Повертає:
+
+- Якщо ім'я **збігається з одним із regexp у `SLOT_SUFFIX_RES`** (тобто має суфікс `.snippet.<ext>`, `.deny.<ext>` або `.contains.<ext>`) — повертається **group 1** першого збігу (ім'я без слоту). Приклади:
+  - `package.json.snippet.json` → `package.json`
+  - `eslint.config.js.deny.js` → `eslint.config.js`
+  - `Caddyfile.contains.txt` → `Caddyfile`
+- Якщо жоден з regexp не збігся — повертається оригінальне `fileBasename` без змін.
+
+Side effects: відсутні.
+
+Призначення: для template-файлу з суфіксом-слотом відновити **реальне ім'я target-файлу**, на який цей template посилається; саме це ім'я потім підставляється як заголовок перед fenced-блоком у згенерованому Markdown.
+
+Коментар над функцією у вихіднику прямо описує цю поведінку: «Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the real target file name».
+
+### `inlineTemplateLinks(text, ruleDir)` — **exported**
+
+Сигнатура:
+
+```js
+export async function inlineTemplateLinks(
+  text: string,
+  ruleDir: string,
+): Promise<string>
+```
+
+Параметри:
+
+- `text` — вміст `.mdc`-файлу (повний текст) як рядок.
+- `ruleDir` — **абсолютний** шлях до директорії правила (наприклад `.../npm/rules/security/`). Усі відносні href із `./` резолвляться **відносно цього каталогу**.
+
+Повертає:
+
+- `Promise<string>` — трансформований текст, у якому всі **template-посилання** замінено на блоки виду:
+
+  ````text
+  `<targetName>`:
+
+  ```<lang>
+  <contents>
+  ````
+
+  ```
+
+  де `targetName` — результат `normalizeTargetName(basename(absPath))`, `lang` — результат `langFromExt(absPath)`, а `contents` — вміст файлу після `.trim()`.
+
+  ```
+
+- Якщо у тексті немає жодного template-посилання — повертається **той самий `text` без змін** (early-exit).
+
+Алгоритм роботи:
+
+1. Знаходимо **всі** збіги `MD_LINK_RE` у `text` через `text.matchAll(...)`.
+2. Фільтруємо їх: залишаємо лише ті, у яких href (group 2) містить `/template/` або `/templates/` (через `TEMPLATE_SEGMENT_RE.test(m[2])`).
+3. Якщо після фільтрації збігів **немає** — повертаємо `text` як є.
+4. Кладемо стартовий результат `result = text`.
+5. Для кожного збігу послідовно (`for ... of`, з `await` на читанні файлу):
+   1. Деструктуруємо: `const [fullMatch, , href] = match` (label не використовується, тому позиція пропущена).
+   2. Будуємо відносний шлях: `relPath = href.slice(2)` — обрізаємо префікс `./` (його гарантує regexp).
+   3. Збираємо абсолютний шлях: `absPath = join(ruleDir, relPath)`.
+   4. Перевіряємо існування: `existsSync(absPath)`. Якщо файлу немає — **кидаємо** `Error`:
+
+      ```text
+      inlineTemplateLinks: file not found: <absPath> (referenced from .mdc)
+      ```
+
+      Жодного fallback / тихого пропуску — це fail-loud за дизайном.
+
+   5. Читаємо файл: `raw = await readFile(absPath, 'utf8')`, далі `contents = raw.trim()` (прибираємо хвостові пробіли / переноси).
+   6. Обчислюємо `lang = langFromExt(absPath)`.
+   7. Обчислюємо `targetName = normalizeTargetName(basename(absPath))`.
+   8. Формуємо `replacement` — backtick-екранований заголовок, порожній рядок і fenced-блок із `lang`:
+
+      ```js
+      ;`\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``
+      ```
+
+   9. Робимо заміну: `result = result.replace(fullMatch, () => replacement)`. Передача **callback-форми** в `.replace` критично важлива: інакше спецсимволи у `replacement` (наприклад `$&`, `$1` із вмісту шаблону) трактувалися б як backreferences і зламали б вивід.
+
+6. Повертаємо `result`.
+
+Side effects:
+
+- **Читання** файлів із диска (синхронна перевірка `existsSync` + асинхронне `readFile`).
+- **Кидання `Error`** при відсутності target-файлу — це навмисна поведінка («fail loud — user must know»), а не баг.
+- Запису на диск або мережевих викликів **не робить**.
+
+Складність та обмеження:
+
+- Цикл лінійний за кількістю template-посилань у тексті; для кожного — один `existsSync` і один `readFile`.
+- Файли читаються **послідовно** (через `await` у тілі `for...of`), а не паралельно через `Promise.all`. Це осмислений вибір: правил, як правило, мало, а послідовність робить порядок помилок передбачуваним.
+- Заміна виконується через простий `result.replace(fullMatch, ...)` — перший збіг `fullMatch` у `result`. Якщо однакове Markdown-посилання трапляється кілька разів — модифікується лише перше входження (фактичний `matchAll` дасть і інші входження, але кожен з них має той самий `fullMatch`, і їх теж замінить — по одному за крок ітерації; для повних дублікатів це працює коректно).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:fs` → `existsSync` — синхронна перевірка наявності файлу перед читанням.
+- `node:fs/promises` → `readFile` — асинхронне читання вмісту target-файлу як UTF-8.
+- `node:path` → `basename`, `extname`, `join` — робота з шляхами:
+  - `extname` — у `langFromExt` для визначення мови;
+  - `basename` — для отримання базового імені файлу, з якого `normalizeTargetName` витягне target-ім'я;
+  - `join` — для побудови абсолютного шляху від `ruleDir` + `relPath`.
+
+### Зовнішні залежності
+
+Жодних npm-пакетів. Модуль працює лише на Node.js стандарті.
+
+### Споживачі модуля
+
+Файл лежить у `npm/scripts/lib/` поряд із іншими допоміжними утилітами для збірки правил, тому очікувані споживачі — build-скрипти у `npm/scripts/`, які генерують підсумкові `.mdc`-документи для cursor-rules / Claude-rules. Експортована функція `inlineTemplateLinks` викликається на проміжній стадії пайплайна обробки тексту `.mdc`-файлу разом із `ruleDir`, обчисленим від шляху до самого `.mdc`.
+
+## Потік виконання / Використання
+
+Типовий сценарій інтеграції в build-скрипт:
+
+```js
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { inlineTemplateLinks } from './lib/inline-template-links.mjs'
+
+const mdcPath = '/abs/path/to/npm/rules/security/n-security.mdc'
+const original = await readFile(mdcPath, 'utf8')
+
+const ruleDir = dirname(mdcPath) // важливо: каталог, де лежить .mdc
+const transformed = await inlineTemplateLinks(original, ruleDir)
+
+await writeFile(mdcPath, transformed, 'utf8')
+```
+
+Що відбувається крок-за-кроком на прикладі.
+
+Вхідний `.mdc`-фрагмент (`ruleDir = .../npm/rules/security/`):
+
+```text
+Snippet вимоги до `package.json` — див. [тут](./templates/package.json.snippet.json).
+```
+
+Файл `.../npm/rules/security/templates/package.json.snippet.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+Що зробить `inlineTemplateLinks`:
+
+1. `matchAll(MD_LINK_RE)` знайде один збіг із href `./templates/package.json.snippet.json`.
+2. `TEMPLATE_SEGMENT_RE` пропустить його (бо є `/templates/`).
+3. `relPath = 'templates/package.json.snippet.json'`, `absPath = '.../npm/rules/security/templates/package.json.snippet.json'`.
+4. `existsSync(absPath)` → `true`, файл читається.
+5. `langFromExt(absPath)` → `'json'`.
+6. `normalizeTargetName('package.json.snippet.json')` → `'package.json'` (спрацює regexp `/^(.+)\.snippet\.[^.]+$/`).
+7. `replacement` буде:
+
+   ````text
+   `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "lint": "eslint ."
+     }
+   }
+   ````
+
+   ```
+
+   ```
+
+8. Результат заміняє оригінальний Markdown-лінк у тексті.
+
+Випадки помилок:
+
+- Якщо `href` веде на неіснуючий файл — кидається `Error` із повним абсолютним шляхом у повідомленні; build-скрипт має право або впасти, або зловити цю помилку.
+- Якщо у `text` немає Markdown-посилань або жодне з них не містить `/template(s)/` — функція повертає `text` без модифікацій.
+- Якщо template-файл має нерозпізнаване розширення (наприклад `.txt` або `.conf`) — `langFromExt` поверне порожній рядок, і fenced-блок буде без мовного тегу (Markdown це допускає).
+- Якщо ім'я template-файлу **не** має одного з суфіксів `.snippet.<ext>` / `.deny.<ext>` / `.contains.<ext>` — `normalizeTargetName` поверне його як є; це нормальна поведінка для «звичайних» template-файлів, у яких саме ім'я і є target-ім'ям.
+
+## Rebuild Test
+
+Якщо видалити цей файл і відтворити його з нуля, мінімально достатній рецепт такий:
+
+1. Створи модуль `inline-template-links.mjs` у `npm/scripts/lib/`.
+2. Імпортуй з `node:fs` функцію `existsSync`, з `node:fs/promises` — `readFile`, з `node:path` — `basename`, `extname`, `join`.
+3. Оголоси константи:
+   - `MD_LINK_RE = /\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g` — глобальний regexp для Markdown-посилань `[label](./path)`.
+   - `TEMPLATE_SEGMENT_RE = /\/templates?\//` — фільтр шляхів, що містять `/template/` чи `/templates/`.
+   - `SLOT_SUFFIX_RES` — масив із трьох **статичних** regexp: `/^(.+)\.snippet\.[^.]+$/`, `/^(.+)\.deny\.[^.]+$/`, `/^(.+)\.contains\.[^.]+$/`. Принципово: жодного `new RegExp(variable)` — захист від ReDoS.
+4. Реалізуй `langFromExt(filePath)`:
+   - `extname(filePath)` → за вмістом повернути `'json' | 'toml' | 'yaml' | ''` (для `.yml` теж `'yaml'`).
+5. Реалізуй `normalizeTargetName(fileBasename)`:
+   - Пройди `SLOT_SUFFIX_RES` у заданому порядку; при першому збігу поверни `match[1]`. Інакше — оригінал.
+6. Експортуй `async function inlineTemplateLinks(text, ruleDir)`:
+   - `matchAll(MD_LINK_RE)` → відфільтруй за `TEMPLATE_SEGMENT_RE.test(href)`.
+   - Якщо нічого не залишилося — поверни `text`.
+   - Для кожного збігу: `relPath = href.slice(2)`, `absPath = join(ruleDir, relPath)`; якщо `!existsSync(absPath)` — `throw new Error('inlineTemplateLinks: file not found: <absPath> (referenced from .mdc)')`.
+   - Читай файл `utf8`, роби `.trim()`, обчисли `lang` і `targetName`, побудуй `replacement = \`\\\`${targetName}\\\`:\\n\\n\\\`\\\`\\\`${lang}\\n${contents}\\n\\\`\\\`\\\``.
+   - Заміни через `result = result.replace(fullMatch, () => replacement)` (саме callback-форма — щоб уникнути інтерпретації `$&`/`$1` у вмісті template-файлу).
+7. Поверни `result`.
+
+Контракт, який має зберегтися:
+
+- Чиста функція над текстом + читання файлів (без записів і без мережі).
+- **Fail-loud** на відсутній target.
+- Підтримка трьох слот-суфіксів: `snippet`, `deny`, `contains`.
+- Підтримка мов підсвічування: `json`, `toml`, `yaml`, інакше — без таргу.
+- Жодного `RegExp(variable)`.
+- Префікс href повинен починатися з `./`, інакше посилання ігнорується (це закладено в `MD_LINK_RE`).