@nitra/cursor 1.13.31 → 1.13.38

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 ?? []

package/scripts/utils/template.mjs

@@ -2,7 +2,6 @@
  * Reads template/ for a concern directory and returns a merged structure indexed
  * by target basename. For each <target>, returns whichever of snippet/deny/contains
  * exist (parsed in native format by extension).
- *
  * @param {string} concernDir absolute path to fix/<concern>/ or policy/<concern>/
  * @returns {Promise<Record<string, { snippet?: any, deny?: any, contains?: any }>>}
  */
@@ -13,8 +12,15 @@ import { basename as _basename, extname, join, relative } from 'node:path'
 import { parse as parseToml } from 'smol-toml'
 
 const SLOTS = ['snippet', 'deny', 'contains']
+const IDENT_RE = /^[a-zA-Z_$][\w$]*$/
+const NEWLINE_RE = /\r?\n/
+const LEADING_BANG_RE = /^!/
 
-/** Parse file contents by extension; returns JS object for structured formats, string for text. */
+/**
+ * Parse file contents by extension; returns JS object for structured formats, string for text.
+ * @param {string} path шлях до файлу
+ * @returns {Promise<unknown>} розпарсений вміст
+ */
 async function parseByExt(path) {
   const raw = await readFile(path, 'utf8')
   const ext = extname(path).toLowerCase()
@@ -27,12 +33,21 @@ async function parseByExt(path) {
   return raw // text-only
 }
 
+/**
+ * @param {string} s сирий вміст JSON/JSONC
+ * @returns {string} текст без коментарів, рядкові літерали збережено
+ */
 function stripJsonComments(s) {
   // Match string literals OR comments. Strings are returned unchanged so we never
   // strip `/*` / `//` / `*/` that appear inside values (e.g. glob `**/node_modules/**`).
-  return s.replace(/"(?:\\.|[^"\\])*"|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, m => (m.startsWith('"') ? m : ''))
+  return s.replaceAll(/"(?:\\.|[^"\\])*"|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, m => (m.startsWith('"') ? m : ''))
 }
 
+/**
+ * @param {string} dir каталог для рекурсивного обходу
+ * @param {string} [base] базовий шлях для відносних результатів
+ * @returns {Promise<string[]>} список відносних шляхів файлів
+ */
 async function walk(dir, base = dir) {
   const out = []
   for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -46,23 +61,48 @@ async function walk(dir, base = dir) {
 /**
  * Parse "<target>.<slot>.<ext>" or "<target>" (text-only).
  * Returns { target, slot } where slot is one of snippet|deny|contains|null (null = text-only target).
+ * @param {string} relPath відносний шлях template-файлу
+ * @returns {{ target: string, slot: string | null }} класифікація
  */
 function classifyTemplateFile(relPath) {
   // Try ".<slot>." suffix detection
   for (const slot of SLOTS) {
-    const m = relPath.match(new RegExp(`^(?<target>.+)\\.${slot}\\.[^.]+$`))
+    const m = relPath.match(new RegExp(String.raw`^(?<target>.+)\.${slot}\.[^.]+$`))
     if (m?.groups?.target) return { target: m.groups.target, slot }
   }
   // No slot suffix → text-only canon for the literal target name
   return { target: relPath, slot: null }
 }
 
+/**
+ * @param {string|number} p сегмент шляху
+ * @returns {string} токен у форматі ідентифікатор / [n] / JSON-рядок
+ */
+function tokenizePathPart(p) {
+  if (typeof p === 'number') return `[${p}]`
+  if (IDENT_RE.test(p)) return p
+  return JSON.stringify(p)
+}
+
+/**
+ * @param {Array<string|number>} parts сегменти шляху
+ * @returns {string} дотовий шлях для повідомлень
+ */
 function formatPath(parts) {
-  return parts
-    .map(p => (typeof p === 'number' ? `[${p}]` : /^[a-zA-Z_$][\w$]*$/.test(p) ? p : JSON.stringify(p)))
-    .reduce((acc, p) => (acc === '' ? p : p.startsWith('[') ? acc + p : acc + '.' + p), '')
+  const tokens = parts.map(p => tokenizePathPart(p))
+  let out = ''
+  for (const p of tokens) {
+    if (out === '') out = p
+    else if (p.startsWith('[')) out += p
+    else out += '.' + p
+  }
+  return out
 }
 
+/**
+ * @param {unknown} v значення
+ * @returns {string} JSON-рядок для рядків, інакше String(v)
+ */
 function quote(v) {
   return typeof v === 'string' ? JSON.stringify(v) : String(v)
 }
@@ -71,9 +111,14 @@ function quote(v) {
  * Deep subset-of check. Every leaf in `snippet` must equal same path in `actual`.
  * Arrays in snippet: every element must be present in actual array.
  * Returns array of violation messages.
+ * @param {unknown} actual фактичне значення з документа
+ * @param {unknown} snippet канонічний фрагмент із template
+ * @param {{ targetPath: string, source: string }} opts опції джерела
+ * @param {Array<string|number>} [path] поточний шлях у дереві
+ * @returns {string[]} список порушень
  */
 export function checkSnippet(actual, snippet, opts, path = []) {
-  if (snippet == null) return []
+  if (snippet === null || snippet === undefined) return []
   const { targetPath, source } = opts
   const violations = []
   if (Array.isArray(snippet)) {
@@ -89,8 +134,8 @@ export function checkSnippet(actual, snippet, opts, path = []) {
     }
     return violations
   }
-  if (snippet !== null && typeof snippet === 'object') {
-    if (actual == null || typeof actual !== 'object' || Array.isArray(actual)) {
+  if (typeof snippet === 'object') {
+    if (actual === null || actual === undefined || typeof actual !== 'object' || Array.isArray(actual)) {
       violations.push(`${targetPath}: ${formatPath(path)} має бути об'єктом (${source})`)
       return violations
     }
@@ -109,11 +154,16 @@ export function checkSnippet(actual, snippet, opts, path = []) {
 /**
  * Walks deny tree; for any leaf path that exists in actual, returns violation
  * with the deny's leaf string as reason.
+ * @param {unknown} actual фактичне значення з документа
+ * @param {unknown} deny дерево заборонених шляхів із template
+ * @param {{ targetPath: string, source: string }} opts опції джерела
+ * @param {Array<string|number>} [path] поточний шлях у дереві
+ * @returns {string[]} список порушень
  */
 export function checkDeny(actual, deny, opts, path = []) {
-  if (deny == null) return []
+  if (deny === null || deny === undefined) return []
   const { targetPath, source } = opts
-  if (deny !== null && typeof deny === 'object' && !Array.isArray(deny)) {
+  if (typeof deny === 'object' && !Array.isArray(deny)) {
     const out = []
     for (const [k, v] of Object.entries(deny)) {
       const childActual = actual && typeof actual === 'object' ? actual[k] : undefined
@@ -132,9 +182,14 @@ export function checkDeny(actual, deny, opts, path = []) {
 /**
  * For each leaf path that has an array of strings in `contains`, every string
  * must appear as substring in the same path of `actual` (string leaf).
+ * @param {unknown} actual фактичне значення з документа
+ * @param {unknown} contains дерево обов'язкових підрядків із template
+ * @param {{ targetPath: string, source: string }} opts опції джерела
+ * @param {Array<string|number>} [path] поточний шлях у дереві
+ * @returns {string[]} список порушень
  */
 export function checkContains(actual, contains, opts, path = []) {
-  if (contains == null) return []
+  if (contains === null || contains === undefined) return []
   const { targetPath, source } = opts
   if (Array.isArray(contains)) {
     const out = []
@@ -146,7 +201,7 @@ export function checkContains(actual, contains, opts, path = []) {
     }
     return out
   }
-  if (contains !== null && typeof contains === 'object') {
+  if (typeof contains === 'object') {
     const out = []
     for (const [k, v] of Object.entries(contains)) {
       const childActual = actual && typeof actual === 'object' ? actual[k] : undefined
@@ -160,13 +215,21 @@ export function checkContains(actual, contains, opts, path = []) {
 /**
  * For text-only targets (e.g. .stylelintignore): every non-empty, non-comment
  * line in `template` must appear (trimmed) in `actual`.
+ * @param {unknown} actual фактичний текст документа
+ * @param {unknown} template канонічний текст із template
+ * @param {{ targetPath: string, source: string }} opts опції джерела
+ * @returns {string[]} список порушень
  */
 export function checkTextSubset(actual, template, opts) {
-  if (template == null) return []
+  if (template === null || template === undefined) return []
   const { targetPath, source } = opts
-  const actualLines = new Set(String(actual ?? '').split(/\r?\n/).map(l => l.trim()))
+  const actualLines = new Set(
+    String(actual ?? '')
+      .split(NEWLINE_RE)
+      .map(l => l.trim())
+  )
   const out = []
-  for (const raw of String(template).split(/\r?\n/)) {
+  for (const raw of String(template).split(NEWLINE_RE)) {
     const line = raw.trim()
     if (line === '' || line.startsWith('#')) continue
     if (!actualLines.has(line)) {
@@ -176,17 +239,23 @@ export function checkTextSubset(actual, template, opts) {
   return out
 }
 
+/**
+ * @param {string} concernDir абсолютний шлях до fix/<concern>/ або policy/<concern>/
+ * @returns {Promise<Record<string, { snippet?: any, deny?: any, contains?: any }>>} merged template-дерево, індексоване за target
+ */
 export async function loadTemplate(concernDir) {
   const tplDir = join(concernDir, 'template')
   if (!existsSync(tplDir)) return {}
-  if (!(await stat(tplDir)).isDirectory()) return {}
+  const tplStat = await stat(tplDir)
+  if (!tplStat.isDirectory()) return {}
   const files = await walk(tplDir)
   const result = {}
   for (const rel of files) {
     const { target, slot } = classifyTemplateFile(rel)
     if (!result[target]) result[target] = {}
     const value = await parseByExt(join(tplDir, rel))
-    if (slot === null) result[target].snippet = value // text-only treated as snippet
+    if (slot === null)
+      result[target].snippet = value // text-only treated as snippet
     else result[target][slot] = value
   }
   return result
@@ -204,7 +273,7 @@ export async function resolveConcernTemplateData(concernAbsDir, targetJson) {
   const single = targetJson?.files?.single
   if (single) return tpl[_basename(single)]
   const glob = targetJson?.files?.walkGlob
-  if (typeof glob === 'string') return tpl[_basename(glob.replace(/^!/, ''))]
+  if (typeof glob === 'string') return tpl[_basename(glob.replace(LEADING_BANG_RE, ''))]
   if (Array.isArray(glob)) {
     for (const g of glob) {
       if (g.startsWith('!')) continue
@@ -212,5 +281,4 @@ export async function resolveConcernTemplateData(concernAbsDir, targetJson) {
       if (data) return data
     }
   }
-  return undefined
 }