@nitra/cursor 1.13.34 → 1.13.40

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
 }