@dxtmisha/scripts 0.7.2 → 0.7.6

package/src/classes/Git/__tests__/GitRead.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { GitRead } from '../GitRead'
+import { execSync } from 'node:child_process'
+import { PropertiesFile } from '../../Properties/PropertiesFile'
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn()
+}))
+
+vi.mock('../../Properties/PropertiesFile', () => ({
+  PropertiesFile: {
+    getTime: vi.fn()
+  }
+}))
+
+describe('GitRead', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('getDirPrefix should return the result of git rev-parse', () => {
+    vi.mocked(execSync).mockReturnValue('packages/scripts/' as any)
+    const result = GitRead.getDirPrefix()
+    expect(execSync).toHaveBeenCalledWith('git rev-parse --show-prefix', expect.anything())
+    expect(result).toBe('packages/scripts/')
+  })
+
+  it('getFilesPath should return list of HEAD files', () => {
+    vi.mocked(execSync).mockReturnValue('file1.ts\nfile2.ts\n' as any)
+    const result = GitRead.getFilesPath()
+    expect(result).toEqual(['file1.ts', 'file2.ts'])
+  })
+
+  it('getList should return files with metadata', () => {
+    vi.mocked(execSync).mockImplementation((cmd: string) => {
+      if (cmd.startsWith('git rev-parse')) return 'prefix/' as any
+      if (cmd.startsWith('git ls-tree')) return 'file.ts\n' as any
+      if (cmd.startsWith('git log')) return '2023-10-27 12:00:00 +0300' as any
+      return '' as any
+    })
+
+    const result = GitRead.getList()
+    expect(result[0]).toMatchObject({
+      path: 'file.ts',
+      pathFull: 'prefix/file.ts',
+      date: expect.stringContaining('2023-10-27')
+    })
+  })
+
+  it('getListPorcelain should parse git status and metadata', () => {
+    vi.mocked(execSync).mockImplementation((cmd: string) => {
+      if (cmd.startsWith('git rev-parse')) return 'prefix/' as any
+      if (cmd.startsWith('git status')) return 'M  file.ts\nA  new.ts\n' as any
+      return '' as any
+    })
+    vi.mocked(PropertiesFile.getTime).mockReturnValue('2023-10-27 12:00:00' as any)
+
+    const result = GitRead.getListPorcelain()
+    expect(result).toHaveLength(2)
+    expect(result[0]).toMatchObject({
+      path: 'file.ts',
+      status: 'M'
+    })
+  })
+
+  it('splitPath should correctly split string', () => {
+    expect(GitRead.splitPath('a/b/c')).toEqual(['a', 'b', 'c'])
+    expect(GitRead.splitPath('/a/b/')).toEqual(['a', 'b'])
+  })
+})

package/src/classes/Library/LibraryAiWiki.ts

@@ -99,7 +99,7 @@ export class LibraryAiWiki {
       `<script setup lang="ts">
 // This file is generated by a script, do not edit.
 
-import { DxtTestPage, DxtTestWikiAnchor } from '@dxtmisha/test'
+import { DxtTestPage, DxtTestWikiAnchor, DxtTestWikiHide } from '@dxtmisha/test'
 import { aiList } from '../library/${this.getFileList()}.wiki'
 
 defineOptions({
@@ -112,6 +112,7 @@ defineOptions({
     title="List of available UI components"
     description="Below is a list of Vue 3 components available in the UI. These components are available immediately and do not need to be imported."
   >
+    <DxtTestWikiHide/>
     <DxtTestWikiAnchor :list="aiList"/>
     <component
       v-for="(item, key) in aiList"

package/src/classes/Library/LibraryFlags.ts

@@ -8,24 +8,26 @@ import { LibraryItems } from './LibraryItems'
 import { UI_FILE_NAME_FLAGS } from '../../config'
 
 /**
- * Class for generating a file to connect flags.
+ * Class for generating connection files for country flags and providing a list of flag identifiers.
  *
- * Класс для формирования файла для подключения флагов.
+ * Класс для формирования файлов подключения флагов стран и предоставления списка идентификаторов флагов.
  */
 export class LibraryFlags {
   /**
-   * Constructor
-   * @param items object for working with the list of components/ объект для работы со списком компонентов
+   * Constructor for LibraryFlags.
+   *
+   * Конструктор для LibraryFlags.
+   * @param items object for working with the list of components / объект для работы со списком компонентов
    */
-
   constructor(
     protected readonly items: LibraryItems
   ) {
   }
 
   /**
-   * Adds a file with flags.<br>
-   * Добавляет файл с флагами.
+   * Generates flag connection files (TypeScript) and a list of flag keys (JSON).
+   *
+   * Генерирует файлы подключения флагов (TypeScript) и список ключей флагов (JSON).
    */
   make(): void {
     const data: string[] = []

package/src/classes/Library/LibraryItems.ts

@@ -55,6 +55,15 @@ export class LibraryItems {
     return this.getComponentList().length
   }
 
+  /**
+   * Returns the path to the design system components directory
+   *
+   * Возвращает путь к директории компонентов дизайн-системы
+   */
+  getComponentsPath(): string[] {
+    return [...UI_DIRS_COMPONENTS, PropertiesConfig.getProjectName()]
+  }
+
   /**
    * Writes data in the file.
    *
@@ -113,15 +122,6 @@ export class LibraryItems {
     return list
   }
 
-  /**
-   * Returns the path to the design system components directory
-   *
-   * Возвращает путь к директории компонентов дизайн-системы
-   */
-  protected getComponentsPath(): string[] {
-    return [...UI_DIRS_COMPONENTS, PropertiesConfig.getProjectName()]
-  }
-
   /**
    * Initializes data about the component.
    *

package/src/classes/Library/LibraryList.ts

@@ -9,15 +9,17 @@ import { PropertiesFile } from '../Properties/PropertiesFile'
 import { UI_DIRS_STYLES, UI_FILE_NAME_DESIGN } from '../../config'
 
 /**
- * Class for creating a file with a list of components.
+ * Class for generating the design system overview file, including component imports and regular expressions.
  *
- * Класс для создания файла со списком компонентов.
+ * Класс для создания обзорного файла дизайн-системы, включая импорты компонентов и регулярные выражения.
  */
 export class LibraryList {
   protected readonly packageName: string
 
   /**
-   * Constructor
+   * Constructor for LibraryList.
+   *
+   * Конструктор для LibraryList.
    * @param items object for working with the list of components / объект для работы со списком компонентов
    */
   constructor(
@@ -27,9 +29,10 @@ export class LibraryList {
   }
 
   /**
-   * Creates files with a list of components.
+   * Creates the design system overview file (`design.ts`) with metadata and component lists.
    *
-   * Создает файлы со списком компонентов.
+   * Создает обзорный файл дизайн-системы (`design.ts`) с метаданными и списками компонентов.
+   * @returns this
    */
   make(): this {
     const list = this.getComponents()
@@ -121,6 +124,8 @@ export class LibraryList {
 
     if (only) {
       code = `^${code}$`
+    } else {
+      code = `${code}(?![\\w-])`
     }
 
     return `/${code}/ig`

package/src/classes/Library/LibraryMedia.ts

@@ -1,31 +1,39 @@
 // export:none
 
-import { toCamelCase } from '@dxtmisha/functional-basic'
+import { toCamelCase, toCamelCaseFirst } from '@dxtmisha/functional-basic'
 
 import { PropertiesConfig } from '../Properties/PropertiesConfig'
 import { PropertiesFile } from '../Properties/PropertiesFile'
 
 import { LibraryItems } from './LibraryItems'
 
-import { UI_DIRS_ICONS, UI_FILE_NAME_MEDIA } from '../../config'
+import { UI_DIRS_ICONS, UI_FILE_NAME_MEDIA, UI_FILE_NAME_STYLE } from '../../config'
 import type { LibraryIconItem } from '../../types/libraryTypes'
 
 /**
- * Class for generating the media data connection file.
+ * Class for generating connection files for media data (primarily icons) and style entry points.
  *
- * Класс для формирования файла подключения медиа-данных.
+ * Класс для формирования файлов подключения медиа-данных (прежде всего иконок) и точек входа стилей.
  */
 export class LibraryMedia {
   /**
-   * Constructor
-   * @param items object for working with the list of components/ объект для работы со списком компонентов
+   * Constructor for LibraryMedia.
+   *
+   * Конструктор для LibraryMedia.
+   * @param items object for working with the list of components / объект для работы со списком компонентов
    */
   constructor(
     protected readonly items: LibraryItems
   ) {
   }
 
+  /**
+   * Generates media connection files and style entries.
+   *
+   * Генерирует файлы подключения медиа и записи стилей.
+   */
   make(): void {
+    const projectName = toCamelCaseFirst(PropertiesConfig.getProjectName())
     const name = toCamelCase(PropertiesConfig.getDesignName())
     const isIcons = this.getIconImport().length > 0
 
@@ -43,6 +51,13 @@ export class LibraryMedia {
         ]
       )
     }
+
+    this.items.write(
+      UI_FILE_NAME_STYLE,
+      [
+        `import '../styles/${projectName}/main.scss'`
+      ]
+    )
   }
 
   /**

package/src/classes/Library/LibraryPlugin.ts

@@ -6,13 +6,15 @@ import { LibraryItems } from './LibraryItems'
 import { UI_FILE_NAME_PLUGIN } from '../../config'
 
 /**
- * Class for creating a plugin file.
+ * Class for creating a plugin file for the design system.
  *
- * Класс для создания файла плагина.
+ * Класс для создания файла плагина для дизайн-системы.
  */
 export class LibraryPlugin {
   /**
-   * Constructor
+   * Constructor for LibraryPlugin.
+   *
+   * Конструктор для LibraryPlugin.
    * @param items object for working with the list of components / объект для работы со списком компонентов
    */
   constructor(
@@ -21,9 +23,10 @@ export class LibraryPlugin {
   }
 
   /**
-   * Creates a plugin file.
+   * Creates a plugin file that initializes the Vite plugin for the library.
    *
-   * Создает файл плагина.
+   * Создает файл плагина, который инициализирует плагин Vite для библиотеки.
+   * @returns this
    */
   make(): this {
     const design = PropertiesConfig.getDesignName()

package/src/classes/Library/LibraryTypes.ts

@@ -4,13 +4,15 @@ import { LibraryItems } from './LibraryItems'
 import type { LibraryData } from '../../types/libraryTypes'
 
 /**
- * Class for creating a file with type exports.
+ * Class for generating global type definitions for Vue components.
  *
- * Класс для создания файла с экспортом типов.
+ * Класс для создания глобальных определений типов для компонентов Vue.
  */
 export class LibraryTypes {
   /**
-   * Constructor
+   * Constructor for LibraryTypes.
+   *
+   * Конструктор для LibraryTypes.
    * @param items object for working with the list of components / объект для работы со списком компонентов
    */
   constructor(
@@ -19,17 +21,26 @@ export class LibraryTypes {
   }
 
   /**
-   * Creates a file with type exports.
+   * Creates the type definition file (`types.d.ts`) for global Vue components.
    *
-   * Создает файл с экспортом типов.
+   * Создает файл определений типов (`types.d.ts`) для глобальных компонентов Vue.
    */
   make(): void {
     this.items.write(
       'types',
       [
+        // 'import { type App } from \'vue\'',
         ...this.initImports(),
-        '',
-        ...this.initExports(),
+        // '',
+        // 'export const components = {',
+        // this.initExports(),
+        // '}',
+        // '',
+        // 'export const useVueComponentsPlugin = {',
+        // '  install: async (app: App) => {',
+        // ...this.initIncludeVueComponents(),
+        // '  }',
+        // '}',
         '',
         'declare module \'@vue/runtime-core\' {',
         '  export interface GlobalComponents {',
@@ -73,13 +84,26 @@ export class LibraryTypes {
    *
    * Возвращает список экспортов для файла.
    */
-  protected initExports(): string[] {
+  protected initExports(): string {
+    const list: string[] = []
+
+    this.items.getComponentList()
+      .forEach((component) => {
+        list.push(
+          `  ${component.codeFull}: _${component.codeFull}`
+        )
+      })
+
+    return list.join(',\r\n')
+  }
+
+  protected initIncludeVueComponents(): string[] {
     const list: string[] = []
 
     this.items.getComponentList()
       .forEach((component) => {
         list.push(
-          `export const ${component.codeFull} = _${component.codeFull}`
+          `    app.component('${component.codeFull}', _${component.codeFull})`
         )
       })
 
@@ -97,7 +121,7 @@ export class LibraryTypes {
     this.items.getComponentList()
       .forEach((component) => {
         list.push(
-          `    ${component.codeFull}: typeof ${component.codeFull}`
+          `    ${component.codeFull}: typeof _${component.codeFull}`
         )
       })
 

package/src/classes/Package/PackageInit.ts

@@ -6,11 +6,19 @@ import { PackageInitItem } from './PackageItem'
 import { UI_DIR_PACKAGES } from '../../config'
 
 /**
- * Initializes the package configuration and environment.
+ * Class for initializing the package structure and development environment based on templates.
  *
- * Инициализирует конфигурацию пакета и окружение.
+ * Класс для инициализации структуры пакета и среды разработки на основе шаблонов.
  */
 export class PackageInit {
+  /**
+   * Constructor for PackageInit.
+   *
+   * Конструктор для PackageInit.
+   * @param type package type identifier / идентификатор типа пакета
+   * @param templates optional list of templates to apply / необязательный список шаблонов для применения
+   * @param dir base directory for packages / базовая директория для пакетов
+   */
   constructor(
     protected readonly type: string,
     protected readonly templates?: string,
@@ -19,9 +27,9 @@ export class PackageInit {
   }
 
   /**
-   * Creates the package structure and initializes files.
+   * Triggers the package creation process and initializes required files.
    *
-   * Создает структуру пакета и инициализирует файлы.
+   * Запускает процесс создания пакета и инициализирует необходимые файлы.
    */
   make() {
     console.log(`Initializing package of type: ${this.type} with templates: ${this.templates}`)

package/src/classes/Package/PackageItem.ts

@@ -29,11 +29,20 @@ type PackageInitItemFile = {
 }
 
 /**
- * Represents a single package item with its metadata and operations.
+ * Class for initializing a single package component, managing its files, dependencies, and integration.
  *
- * Представляет отдельный элемент пакета с его метаданными и операциями.
+ * Класс для инициализации отдельного компонента пакета, управления его файлами, зависимостями и интеграцией.
  */
 export class PackageInitItem {
+  /**
+   * Constructor for PackageInitItem.
+   *
+   * Конструктор для PackageInitItem.
+   * @param name unique name of the component / уникальное имя компонента
+   * @param dir path to the component directory / путь к директории компонента
+   * @param type package type identifier / идентификатор типа пакета
+   * @param templates optional list of templates to apply / необязательный список шаблонов для применения
+   */
   constructor(
     protected readonly name: string,
     protected readonly dir: string[],
@@ -43,9 +52,9 @@ export class PackageInitItem {
   }
 
   /**
-   * Initializes the package item by creating files from samples and templates.
+   * Performs the full initialization cycle for the package item, including file creation and integration updates.
    *
-   * Инициализирует элемент пакета, создавая файлы из образцов и шаблонов.
+   * Выполняет полный цикл инициализации элемента пакета, включая создание файлов и обновление интеграций.
    */
   make() {
     console.log('Package init in:', this.dir)

package/src/classes/Properties/Properties.ts

@@ -45,22 +45,33 @@ import { type PropertyList } from '../../types/propertyTypes'
 const FILE_CACHE = 'properties'
 
 /**
- * The main class for working with tokens.
+ * Central orchestrator for the design system's token management.
+ * Responsible for loading, merging, and executing a multi-stage transformation pipeline to convert raw property definitions into structured, resolved data for various output formats.
  *
- * Главный класс для работы с токенами.
+ * Центральный оркестратор для управления токенами дизайн-системы.
+ * Отвечает за загрузку, слияние и выполнение многоэтапного конвейера преобразований для конвертации необработанных определений свойств в структурированные, разрешенные данные для различных выходных форматов.
  */
 export class Properties {
   private readonly designs: string[]
   private readonly items: PropertiesItems
 
   /**
-   * Constructor
+   * Constructor for Properties.
+   * Initializes the list of designs and triggers the token processing pipeline.
+   *
+   * Конструктор для Properties.
+   * Инициализирует список дизайнов и запускает конвейер обработки токенов.
    */
   constructor() {
     this.designs = PropertiesTool.getDesigns()
     this.items = new PropertiesItems(this.read())
   }
 
+  /**
+   * Returns the processed collection of design tokens.
+   *
+   * Возвращает обработанную коллекцию токенов дизайна.
+   */
   get() {
     return this.items
   }

package/src/classes/Properties/PropertiesCache.ts

@@ -20,9 +20,11 @@ type PropertiesCacheSystem = {
 }
 
 /**
- * Processing for storing temporary files.
+ * Static orchestrator for managing persistent file caching in the design system.
+ * Provides a structured mechanism for storing transformed tokens, tracking file dependencies, and ensuring incremental build performance by avoiding redundant processing.
  *
- * Обработка для хранения временных файлов.
+ * Статический оркестратор для управления постоянным файловым кэшированием в дизайн-системе.
+ * Предоставляет структурированный механизм для хранения трансформированных токенов, отслеживания зависимостей файлов и обеспечения производительности инкрементальной сборки за счет исключения повторной обработки.
  */
 export class PropertiesCache {
   private static time = 0
@@ -31,16 +33,13 @@ export class PropertiesCache {
   private static readonly listenerName: string[] = ['global']
 
   /**
-   * Reads data from the cache or updates the cache if the data is outdated.
+   * Retrieves data from the cache or executes the callback to regenerate and store it if the cache is missing or outdated.
    *
-   * Читает данные из кэша или обновляет кэш, если данные устарели.
-   * @param path path to the file/ путь к файлу
-   * @param name file name/ название файла
-   * @param callback if the file is not found, the callback function is called
-   * and its result is saved in the current file /
-   * если файл не найден, вызывается функция обратного вызова (callback) и её
-   * результат сохраняется в текущем файле
-   * @param extension file extension by default is json/ расширение файла по умолчанию - json
+   * Извлекает данные из кэша или выполняет функцию обратного вызова для регенерации и сохранения данных, если кэш отсутствует или устарел.
+   * @param path the logical path structure for the cache file/ логическая структура пути для файла кэша
+   * @param name the unique identifier for the cache entry/ уникальный идентификатор записи кэша
+   * @param callback the generator function to execute on cache miss/ функция-генератор, выполняемая при отсутствии данных в кэше
+   * @param extension the file extension, typically 'json'/ расширение файла, обычно 'json'
    */
   static get<T extends PropertiesFileValue>(
     path: PropertiesFilePath,
@@ -67,10 +66,10 @@ export class PropertiesCache {
   }
 
   /**
-   * Returns the content of the file by the specified path
+   * Directly reads a file and registers it as a dependency for the currently active cache listener.
    *
-   * Возвращает содержимое файла по указанному пути.
-   * @param path filename/ имя файла
+   * Напрямую читает файл и регистрирует его как зависимость для текущего активного слушателя кэша.
+   * @param path the path to the file to be read/ путь к считываемому файлу
    */
   static read<R>(path: PropertiesFilePath): R | undefined {
     if (PropertiesFile.is(path)) {
@@ -89,20 +88,20 @@ export class PropertiesCache {
   }
 
   /**
-   * Saves intermediate data
+   * Persists intermediate results to the temporary step-based cache directory.
    *
-   * Сохраняет промежуточные данные.
-   * @param name file name/ название файла
-   * @param value values for storage/ значения для хранения
+   * Сохраняет промежуточные результаты во временную директорию пошагового кэша.
+   * @param name the name of the cached step result/ название кэшированного результата шага
+   * @param value the data structure to persist/ структура данных для сохранения
    */
   static write<T extends PropertiesFileValue>(name: string, value: T): void {
     this.writeFile<T>(DIR_STEP, name, value)
   }
 
   /**
-   * Clear cached data
+   * Recursively removes all cached data from the `.cache` directory.
    *
-   * Очистить кешированные данные.
+   * Рекурсивно удаляет все кэшированные данные из директории `.cache`.
    */
   static clear(): void {
     PropertiesFile.removeDir(this.getPath([]))