@nitra/cursor 1.13.34 → 1.13.40

package/rules/text/policy/lint_text/template/lint-text.yml.snippet.yml

@@ -0,0 +1,61 @@
+name: Lint Text
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/*.js'
+      - '**/*.ts'
+      - '**/*.vue'
+      - '**/*.html'
+      - '**/*.css'
+      - '**/*.scss'
+      - '**/*.less'
+      - '**/*.json'
+      - '**/*.jsonc'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.toml'
+      - '**/*.xml'
+      - '**/*.md'
+      - '**/*.mdc'
+      - '**/*.mdс'
+      - '**/*.txt'
+      - '**/*.go'
+      - '**/*.py'
+      - '**/*.php'
+      - '**/*.sh'
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  text:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Install dotenv-linter
+        run: >-
+          curl -sSfL https://git.io/JLbXn
+          | sh -s -- -b /usr/local/bin
+
+      - name: Lint text
+        run: bun run lint-text

package/rules/text/policy/markdownlint/markdownlint.rego

@@ -47,7 +47,7 @@ deny contains msg if {
 	msg := sprintf(".markdownlint-cli2.jsonc: %s.%s.%s має бути %v (text.mdc)", [section, inner_key, leaf, expected])
 }
 
-# ── deny: vкладеного обʼєкта взагалі немає ──────────────────────────────
+# ── deny: вкладеного обʼєкта взагалі немає ──────────────────────────────
 
 deny contains msg if {
 	some section, expected_inner in data.template.snippet

package/rules/text/policy/oxfmtrc/template/.oxfmtrc.json.snippet.json

@@ -4,9 +4,5 @@
   "tabWidth": 2,
   "useTabs": false,
   "printWidth": 120,
-  "ignorePatterns": [
-    "**/hasura/metadata/**",
-    "**/schema.graphql",
-    "**/auto-imports.d.ts"
-  ]
+  "ignorePatterns": ["**/hasura/metadata/**", "**/schema.graphql", "**/auto-imports.d.ts"]
 }

package/rules/text/policy/vscode_extensions/template/extensions.json.snippet.json

@@ -1,7 +1,3 @@
 {
-  "recommendations": [
-    "DavidAnson.vscode-markdownlint",
-    "oxc.oxc-vscode",
-    "timonwong.shellcheck"
-  ]
+  "recommendations": ["DavidAnson.vscode-markdownlint", "oxc.oxc-vscode", "timonwong.shellcheck"]
 }

package/rules/text/text.mdc

@@ -1,7 +1,7 @@
 ---
 description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), dotenv-linter (.env*), markdownlint-cli2, v8r, CI
 alwaysApply: true
-version: '1.28'
+version: '1.29'
 ---
 
 **oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **[dotenv-linter](https://dotenv-linter.github.io/)** (`.env*` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
@@ -172,63 +172,9 @@ version: '1.28'
 
 Додай workflow `.github/workflows/lint-text.yml`:
 
-```yaml title=".github/workflows/lint-text.yml"
-name: Lint Text
-
-on:
-  push:
-    branches:
-      - dev
-      - main
-    paths:
-      - '**/*.js'
-      - '**/*.ts'
-      - '**/*.vue'
-      - '**/*.html'
-      - '**/*.css'
-      - '**/*.scss'
-      - '**/*.less'
-      - '**/*.json'
-      - '**/*.jsonc'
-      - '**/*.yaml'
-      - '**/*.yml'
-      - '**/*.toml'
-      - '**/*.xml'
-      - '**/*.md'
-      - '**/*.mdc'
-      - '**/*.mdс'
-      - '**/*.txt'
-      - '**/*.go'
-      - '**/*.py'
-      - '**/*.php'
-      - '**/*.sh'
-
-  pull_request:
-    branches:
-      - dev
-      - main
-
-concurrency:
-  group: ${{ github.ref }}-${{ github.workflow }}
-  cancel-in-progress: true
-
-jobs:
-  text:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: ./.github/actions/setup-bun-deps
-
-      - name: Lint text
-        run: bun run lint-text
-```
+- Канон: [lint-text.yml.snippet.yml](./policy/lint_text/template/lint-text.yml.snippet.yml)
 
-Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
+Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Після composite — кроки **`Install shellcheck`** (apt) і **`Install dotenv-linter`** (curl), бо `n-cursor lint-text` вимагає обидва бінарники в PATH; на ubuntu-latest shellcheck часто вже є, dotenv-linter — ні. Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
 
 Не дублюй окремий workflow з тими самими кроками cspell/markdownlint.
 

package/rules/vue/vue.mdc

@@ -118,6 +118,7 @@ GlobalRegistrator.register()
 ```
 
 `jsdom` не використовуй — happy-dom швидший і достатній для типових Vue-компонентних тестів.
+
 - **E2E:** **Playwright** змістовні сценарії користувацьких потоків.
 
 ### Інструменти (узгоджено з Vite і цим правилом)

package/scripts/sync-claude-config.mjs

@@ -84,7 +84,7 @@ const ADR_NORMALIZE_STOP_HOOK_GROUP = Object.freeze({
 /** Канонічний Cursor stop-hook для ADR capture. Cursor передає payload через stdin JSON. */
 const CURSOR_ADR_STOP_HOOK = Object.freeze({
   command: [
-    "bash -lc 'root=\"$PWD\";",
+    'bash -lc \'root="$PWD";',
     `if [ ! -f "$root/${CURSOR_ADR_HOOK_COMMAND_MARKER}" ] && [ -f "$root/../${CURSOR_ADR_HOOK_COMMAND_MARKER}" ]; then root="$root/.."; fi;`,
     `bash "$root/${CURSOR_ADR_HOOK_COMMAND_MARKER}"'`
   ].join(' '),
@@ -94,7 +94,7 @@ const CURSOR_ADR_STOP_HOOK = Object.freeze({
 /** Канонічний Cursor stop-hook для ADR normalize. */
 const CURSOR_ADR_NORMALIZE_STOP_HOOK = Object.freeze({
   command: [
-    "bash -lc 'root=\"$PWD\";",
+    'bash -lc \'root="$PWD";',
     `if [ ! -f "$root/${CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER}" ] && [ -f "$root/../${CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER}" ]; then root="$root/.."; fi;`,
     `bash "$root/${CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER}"'`
   ].join(' '),

package/scripts/utils/check-mdc-template-refs.mjs

@@ -1,15 +1,15 @@
 /**
  * Returns list of template/ files that are NOT referenced in <id>.mdc as
  * markdown link targets. Paths returned are relative to ruleDir.
- *
- * @param {string} ruleDir absolute path to npm/rules/<id>/
- * @param {string} ruleId basename (e.g. "security")
- * @returns {Promise<string[]>}
  */
 import { existsSync } from 'node:fs'
 import { readdir, readFile, stat } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 
+/**
+ * @param {string} ruleDir абсолютний шлях до каталогу правила
+ * @returns {Promise<string[]>} абсолютні шляхи всіх файлів у template/
+ */
 async function walkTemplateDirs(ruleDir) {
   const out = []
   for (const kind of ['fix', 'policy']) {
@@ -18,13 +18,18 @@ async function walkTemplateDirs(ruleDir) {
     for (const concern of await readdir(kindDir)) {
       const tpl = join(kindDir, concern, 'template')
       if (!existsSync(tpl)) continue
-      if (!(await stat(tpl)).isDirectory()) continue
+      const tplStat = await stat(tpl)
+      if (!tplStat.isDirectory()) continue
       out.push(...(await collectFiles(tpl)))
     }
   }
   return out.map(p => relative(ruleDir, p))
 }
 
+/**
+ * @param {string} dir каталог для обходу
+ * @returns {Promise<string[]>} абсолютні шляхи знайдених файлів
+ */
 async function collectFiles(dir) {
   const out = []
   for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -35,6 +40,11 @@ async function collectFiles(dir) {
   return out
 }
 
+/**
+ * @param {string} ruleDir абсолютний шлях до npm/rules/<id>/
+ * @param {string} ruleId basename правила (напр. "security")
+ * @returns {Promise<string[]>} відносні шляхи template-файлів без посилань у .mdc
+ */
 export async function findMissingMdcRefs(ruleDir, ruleId) {
   const mdcPath = join(ruleDir, `${ruleId}.mdc`)
   if (!existsSync(mdcPath)) return []

package/scripts/utils/inline-template-links.mjs

@@ -2,10 +2,14 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, extname, join } from 'node:path'
 
-const TEMPLATE_LINK_RE = /\[([^\]]+)\]\((\.\/[^)]*\/template\/[^)]+)\)/g
+const MD_LINK_RE = /\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g
+const TEMPLATE_SEGMENT_RE = /\/template\//
 const SLOTS = ['snippet', 'deny', 'contains']
 
-/** @param {string} filePath */
+/**
+ * @param {string} filePath шлях до файлу
+ * @returns {string} назва мови для fenced-блока
+ */
 function langFromExt(filePath) {
   const ext = extname(filePath)
   if (ext === '.json') return 'json'
@@ -16,10 +20,13 @@ function langFromExt(filePath) {
 
 // Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the
 // real target file name (e.g. `package.json.snippet.json` → `package.json`).
-/** @param {string} fileBasename */
+/**
+ * @param {string} fileBasename базове ім'я template-файлу
+ * @returns {string} ім'я реального target-файлу
+ */
 function normalizeTargetName(fileBasename) {
   for (const slot of SLOTS) {
-    const m = fileBasename.match(new RegExp(`^(.+)\\.${slot}\\.[^.]+$`))
+    const m = fileBasename.match(new RegExp(String.raw`^(.+)\.${slot}\.[^.]+$`))
     if (m) return m[1]
   }
   return fileBasename
@@ -29,19 +36,18 @@ function normalizeTargetName(fileBasename) {
  * Finds markdown links whose path contains /template/ and replaces them with
  * inline fenced blocks. Reads file from join(ruleDir, rel-path).
  * Throws Error if a matched link target doesn't exist (fail loud — user must know).
- *
  * @param {string} text .mdc file contents
  * @param {string} ruleDir absolute path to the rule directory (e.g. .../npm/rules/security/)
  * @returns {Promise<string>} transformed text
  */
 export async function inlineTemplateLinks(text, ruleDir) {
-  const matches = [...text.matchAll(TEMPLATE_LINK_RE)]
+  const matches = [...text.matchAll(MD_LINK_RE)].filter(m => TEMPLATE_SEGMENT_RE.test(m[2]))
   if (matches.length === 0) return text
 
   let result = text
   for (const match of matches) {
     const [fullMatch, , href] = match
-    // href starts with ./ and contains /template/ — already guaranteed by regex
+    // href starts with ./ (regex) and contains /template/ (filter above)
     const relPath = href.slice(2) // strip leading ./
     const absPath = join(ruleDir, relPath)
 
@@ -49,7 +55,8 @@ export async function inlineTemplateLinks(text, ruleDir) {
       throw new Error(`inlineTemplateLinks: file not found: ${absPath} (referenced from .mdc)`)
     }
 
-    const contents = (await readFile(absPath, 'utf8')).trim()
+    const raw = await readFile(absPath, 'utf8')
+    const contents = raw.trim()
     const lang = langFromExt(absPath)
     const targetName = normalizeTargetName(basename(absPath))
     const replacement = `\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``

package/scripts/utils/package-manifest.mjs

@@ -10,16 +10,24 @@ import { parse as parseToml } from 'smol-toml'
 
 import { getMonorepoPackageRootDirs } from './workspaces.mjs'
 
-/** @typedef {'npm' | 'python'} PackageKind */
-
 /**
+  @typedef {'npm' | 'python'} PackageKind
+ */
+
+/*
  * @typedef {object} PackageManifest
- * @property {PackageKind} kind
+
+ * @property {PackageKind} kind поле
  * @property {string} ws відносний шлях воркспейсу (`'.'` для кореня)
+
  * @property {string} manifestRel `package.json` | `pyproject.toml`
+
  * @property {string | null} name ім'я пакета (npm / PyPI)
+
  * @property {string | null} version semver-рядок
+
  * @property {boolean} registryPublishable чи застосовується режим порівняння з реєстром
+
  * @property {string[] | null} [npmFiles] лише npm: `files` з package.json
  */
 
@@ -27,7 +35,7 @@ const PYPROJECT_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**', '**/.venv/**'
 
 /**
  * @param {unknown} doc розпарсений pyproject.toml
- * @returns {{ name: string | null, version: string | null }}
+ * @returns {{ name: string | null, version: string | null }} витягнуті поля project / tool.poetry
  */
 function projectFieldsFromPyprojectDoc(doc) {
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
@@ -39,7 +47,7 @@ function projectFieldsFromPyprojectDoc(doc) {
     const p = /** @type {Record<string, unknown>} */ (project)
     return {
       name: typeof p.name === 'string' ? p.name : null,
-      version: typeof p.version === 'string' ? p.version : null,
+      version: typeof p.version === 'string' ? p.version : null
     }
   }
   const tool = root.tool
@@ -49,7 +57,7 @@ function projectFieldsFromPyprojectDoc(doc) {
       const po = /** @type {Record<string, unknown>} */ (poetry)
       return {
         name: typeof po.name === 'string' ? po.name : null,
-        version: typeof po.version === 'string' ? po.version : null,
+        version: typeof po.version === 'string' ? po.version : null
       }
     }
   }
@@ -58,7 +66,7 @@ function projectFieldsFromPyprojectDoc(doc) {
 
 /**
  * @param {string} text вміст pyproject.toml
- * @returns {{ name: string | null, version: string | null }}
+ * @returns {{ name: string | null, version: string | null }} витягнуті поля project / tool.poetry
  */
 export function parsePyprojectFields(text) {
   try {
@@ -70,7 +78,7 @@ export function parsePyprojectFields(text) {
 
 /**
  * @param {string} ws шлях воркспейсу
- * @returns {Promise<PackageManifest | null>}
+ * @returns {Promise<PackageManifest | null>} маніфест пакета або null
  */
 export async function readPackageManifest(ws) {
   const pkgPath = join(ws, 'package.json')
@@ -82,10 +90,7 @@ export async function readPackageManifest(ws) {
       }
       const pkg = /** @type {Record<string, unknown>} */ (parsed)
       const registryPublishable =
-        typeof pkg.name === 'string' &&
-        pkg.name.length > 0 &&
-        pkg.private !== true &&
-        Array.isArray(pkg.files)
+        typeof pkg.name === 'string' && pkg.name.length > 0 && pkg.private !== true && Array.isArray(pkg.files)
       return {
         kind: 'npm',
         ws,
@@ -93,7 +98,7 @@ export async function readPackageManifest(ws) {
         name: typeof pkg.name === 'string' ? pkg.name : null,
         version: typeof pkg.version === 'string' ? pkg.version : null,
         registryPublishable,
-        npmFiles: Array.isArray(pkg.files) ? pkg.files : null,
+        npmFiles: Array.isArray(pkg.files) ? pkg.files : null
       }
     } catch {
       return null
@@ -113,14 +118,14 @@ export async function readPackageManifest(ws) {
     name: fields.name,
     version: fields.version,
     registryPublishable,
-    npmFiles: null,
+    npmFiles: null
   }
 }
 
 /**
  * Каталоги пакетів: npm (`package.json` / workspaces) + Python (`pyproject.toml` без package.json).
- * @param {string} [repoRoot]
- * @returns {Promise<string[]>}
+ * @param {string} [repoRoot] параметр
+ * @returns {Promise<string[]>} результат
  */
 export async function getMonorepoProjectRootDirs(repoRoot = '.') {
   const roots = new Set(await getMonorepoPackageRootDirs(repoRoot))
@@ -149,9 +154,9 @@ export async function getMonorepoProjectRootDirs(repoRoot = '.') {
 
 /**
  * Шлях до файлу маніфесту воркспейсу.
- * @param {string} ws
- * @param {PackageManifest} manifest
- * @returns {string}
+ * @param {string} ws параметр
+ * @param {PackageManifest} manifest параметр
+ * @returns {string} результат
  */
 export function manifestFilePath(ws, manifest) {
   return join(ws, manifest.manifestRel)

package/scripts/utils/run-conftest-batch.mjs

@@ -22,7 +22,9 @@ import { fileURLToPath } from 'node:url'
 
 import { resolveCmd } from './resolve-cmd.mjs'
 
-/** Каталог пакета `@nitra/cursor`, від якого ресолвимо вшиті директорії правил. */
+/**
+  Каталог пакета `@nitra/cursor`, від якого ресолвимо вшиті директорії правил.
+ */
 const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
 
 /** Шлях до кореня правил. У npm-tarball публікується через `files: ["rules"]`. Кожне правило: `rules/<id>/policy/<name>/`. */
@@ -45,19 +47,27 @@ function failConftestMissing() {
   )
 }
 
-/**
+/*
  * @typedef {object} ConftestViolation
+
  * @property {string} filename абсолютний шлях до файла, що дав порушення (з output conftest)
+
  * @property {string} message текст порушення (як у `deny` rego-пакета)
+
  * @property {string} namespace namespace rego-пакета (наприклад `abie.base_deployment_preem`)
  */
 
-/**
+/*
  * @typedef {object} ConftestBatchOptions
+
  * @property {string} policyDirRel шлях до підкаталогу `npm/policy/...` (наприклад `abie/base_deployment_preem`)
+
  * @property {string} namespace повне імʼя rego-пакета (наприклад `abie.base_deployment_preem`)
+
  * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
+
  * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
+
  * @property {object} [templateData] опціональне merged-дерево; серіалізується у JSON `{ "template": <data> }` і передається як `--data <tmpfile>` (cleanup після завершення)
  */
 
@@ -65,18 +75,11 @@ function failConftestMissing() {
  * Pure args builder for conftest test. Extracted for unit-testability.
  * Preserves the existing args layout (files before -p; --output json --no-color
  * for parseable output); inserts --data right after --namespace when provided.
- * @param {{ policyAbs: string, namespace: string, files: string[], extraArgs: string[], tmpDataFile: string|null }} p
- * @returns {string[]}
+ * @param {{ policyAbs: string, namespace: string, files: string[], extraArgs: string[], tmpDataFile: string|null }} p параметри батчу
+ * @returns {string[]} args для виклику conftest
  */
 export function buildConftestArgs(p) {
-  const args = [
-    'test',
-    ...p.files,
-    '-p',
-    p.policyAbs,
-    '--namespace',
-    p.namespace
-  ]
+  const args = ['test', ...p.files, '-p', p.policyAbs, '--namespace', p.namespace]
   if (p.tmpDataFile) args.push('--data', p.tmpDataFile)
   args.push('--output', 'json', '--no-color', ...p.extraArgs)
   return args
@@ -125,14 +128,18 @@ export function runConftestBatch(opts) {
     if (result.status !== 0 && result.status !== 1) {
       throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
     }
-    /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
+    /**
+  @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>}
+     */
     let parsed
     try {
       parsed = JSON.parse(result.stdout)
     } catch {
       throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
     }
-    /** @type {ConftestViolation[]} */
+    /**
+  @type {ConftestViolation[]}
+     */
     const out = []
     for (const entry of parsed) {
       const failures = entry.failures ?? []