@dxtmisha/scripts 0.7.2 → 0.7.7

package/src/classes/Properties/PropertiesConfig.ts

@@ -13,125 +13,136 @@ import {
 } from '../../config'
 
 /**
- * Class for retrieving configuration data.
+ * Static configuration orchestrator for the design system.
+ * Responsible for locating, loading, and merging the `design-ui.json` configuration file, handling recursive extensions, and providing a centralized interface for accessing project-wide settings including naming, separators, and AI integration parameters.
  *
- * Класс для получения данных конфигурации.
+ * Статический оркестратор конфигурации для дизайн-системы.
+ * Отвечает за поиск, загрузку и слияние файла конфигурации `design-ui.json`, обработку рекурсивных расширений и предоставление централизованного интерфейса для доступа к общепроектным настройкам, включая именование, разделители и параметры интеграции ИИ.
  */
 export class PropertiesConfig {
   protected static config: DesignUiConfig
 
   /**
-   * Returns the project name.
+   * Retrieves the global project identifier.
    *
-   * Возвращает название проекта.
+   * Получает глобальный идентификатор проекта.
    */
   static getProjectName(): string {
     return this.config.project ?? 'ui'
   }
 
   /**
-   * Returns the project name.
+   * Retrieves the primary design system name.
    *
-   * Возвращает название проекта.
+   * Получает основное название дизайн-системы.
    */
   static getDesignName(): string {
     return this.config.name ?? 'ui'
   }
 
   /**
-   * Returns alternative design names.
+   * Returns alternative design system aliases.
    *
-   * Возвращает альтернативные названия дизайна.
+   * Возвращает альтернативные алиасы дизайн-системы.
    */
   static getDesignAlternativeName(): string[] | undefined {
     return this.config?.alternativeName
   }
 
   /**
-   * Returns the separator symbol.
+   * Returns the token path separator character.
    *
-   * Возвращает символ разделителя.
+   * Возвращает символ-разделитель пути токена.
    */
   static getSeparator(): string {
     return this.config.separator ?? '/'
   }
 
   /**
-   * Returns the base name of the separator.
+   * Returns the identifier for the base level separator.
    *
-   * Возвращает базовое название разделителя.
+   * Возвращает идентификатор для базового разделителя.
    */
   static getSeparatorBasicName(): string {
     return this.config.separatorBasicName ?? 'basic'
   }
 
   /**
-   * Returns the limit of separator characters in a single key.
+   * Returns the maximum depth for token path segments.
    *
-   * Возвращает лимит символов-разделителей в одном ключе.
+   * Возвращает максимальную глубину сегментов пути токена.
    */
   static getSeparatorLimit(): number {
     return this.config.separatorLimit ?? 6
   }
 
   /**
-   * Returns the wiki language.
+   * Returns the primary language for documentation generation.
    *
-   * Возвращает язык wiki.
+   * Возвращает основной язык для генерации документации.
    */
   static getWikiLanguage(): string {
     return this.config.wikiLanguage ?? 'en'
   }
 
   /**
-   * Returns the package prefix.
+   * Returns the prefix for generated npm packages.
    *
-   * Возвращает префикс пакета.
+   * Возвращает префикс для генерируемых npm-пакетов.
    */
   static getPackagePrefix(): string | undefined {
     return this.config.packagePrefix ?? undefined
   }
 
   /**
-   * Returns the AI type.
+   * Returns the configured AI provider type.
    *
-   * Возвращает тип ИИ.
+   * Возвращает настроенный тип ИИ-провайдера.
    */
   static getAiType(): AiType {
     return this.config.aiType ?? 'gemini'
   }
 
   /**
-   * Returns the AI model.
+   * Returns the specific AI model identifier.
    *
-   * Возвращает модель ИИ.
+   * Возвращает конкретный идентификатор модели ИИ.
    */
   static getAiModel(): string {
     return this.config.aiModel ?? ''
   }
 
   /**
-   * Returns the AI API key.
+   * Returns the secure API key for AI authentication.
    *
-   * Возвращает API ключ ИИ.
+   * Возвращает безопасный API-ключ для аутентификации ИИ.
    */
   static getAiKey(): string {
     return this.config.aiKey ?? ''
   }
 
   /**
-   * Returns the directories for AI documentation generation.
+   * Returns the AI configuration object.
    *
-   * Возвращает каталоги для генерации AI документации.
+   * Возвращает объект конфигурации ИИ.
+   */
+  static getAiConfig(): Record<string, any> {
+    return this.config.aiConfig ?? {}
+  }
+
+  /**
+   * Returns the list of directories targeted for AI-driven documentation.
+   *
+   * Возвращает список директорий, предназначенных для автоматической документации через ИИ.
    */
   static getAiDocDirectory(): string[] {
     return this.config.aiDocDirectory ?? UI_AI_DOC_DIRECTORY
   }
 
   /**
-   * Returns the Storybook path for AI documentation generation.
+   * Returns the export path for Storybook-compatible AI documentation.
    *
-   * Возвращает путь Storybook для генерации AI документации.
+   * Возвращает путь экспорта для AI-документации, совместимой со Storybook.
    */
   static getAiDocStorybookPath(): string {
     return this.config.aiDocStorybookPath ?? UI_AI_DOC_STORYBOOK

package/src/classes/Properties/PropertiesConvector.ts

@@ -17,16 +17,20 @@ const LIST: Record<string, (item: PropertyItemInput) => void> = {
 }
 
 /**
- * Class for data type conversion.<br>
- * Класс для преобразования типов данных.
+ * Static utility for semantic token transformation.
+ * This class orchestrates the conversion of raw property values into specialized design formats (e.g., color processing, typography synthesis, shadow normalization) by dispatching items to specific convectors based on their metadata type.
+ *
+ * Статическая утилита для семантического преобразования токенов.
+ * Этот класс координирует преобразование необработанных значений свойств в специализированные форматы дизайна (например, обработка цвета, синтез типографики, нормализация теней), распределяя элементы по конкретным конвертерам на основе их типа метаданных.
  */
 export class PropertiesConvector {
   /**
-   * Basic value transformation.
+   * Recursively transforms property lists or individual data structures.
+   * Identifies the property type and applies the corresponding specialized convector if available, or continues recursive traversal for nested objects.
    *
-   * Базовое преобразование значения.
-   * @param properties an array that needs to be transformed/
-   * массив, который нужно преобразовать
+   * Рекурсивно преобразует списки свойств или отдельные структуры данных.
+   * Определяет тип свойства и применяет соответствующий специализированный конвертер, если он доступен, или продолжает рекурсивный обход для вложенных объектов.
+   * @param properties the property cluster to be transformed / кластер свойств для преобразования
    */
   static to(properties: PropertyListOrData): void {
     forEach(properties, (item) => {

package/src/classes/Properties/PropertiesFile.ts

@@ -12,34 +12,31 @@ export type PropertiesFileValue<T = any> = string | Record<string, T> | Buffer
 const dirnamePath = hasNativeDirname() ? __dirname : requirePath.dirname(fileURLToPath(import.meta.url))
 
 /**
- * A class for working with files.
+ * Universal static utility for filesystem orchestration.
+ * This class provides a standardized interface for all IO operations within the design system, including path normalization, recursive directory traversal, synchronized file reading/writing, and metadata retrieval. It abstracts platform-specific path differences and ensures consistent data handling across the toolchain.
  *
- * Класс для работы с файлами.
+ * Универсальная статическая утилита для оркестрации файловой системы.
+ * Этот класс предоставляет стандартизированный интерфейс для всех операций ввода-вывода в рамках дизайн-системы, включая нормализацию путей, рекурсивный обход директорий, синхронное чтение/запись файлов и получение метаданных. Он абстрагирует различия путей в разных ОС и обеспечивает согласованную обработку данных во всей цепочке инструментов.
  */
 export class PropertiesFile {
   protected static root: string
   protected static module: boolean
 
   /**
-   * The fs.existsSync() method is used to synchronously check if a file already
-   * exists in the given path or not. It returns a boolean value which indicates
-   * the presence of a file.
+   * Synchronously checks for the existence of a file or directory at the specified path.
    *
-   * Метод fs.existsSync() используется для синхронной проверки наличия файла в
-   * указанном пути. Он возвращает логическое значение, которое указывает на
-   * наличие файла.
-   * @param path it holds the path of the file that has to be checked /
-   * это содержит путь к файлу, который необходимо проверить
+   * Синхронно проверяет существование файла или директории по указанному пути.
+   * @param path target filesystem path to verify / целевой путь в файловой системе для проверки
    */
   static is(path: PropertiesFilePath): boolean {
     return requireFs.existsSync(this.joinPath(path))
   }
 
   /**
-   * Checks whether it is a directory.
+   * Determines if the specified path points to a directory.
    *
-   * Проверяет, является ли это директорией.
-   * @param path name of the element being checked/ название проверяемого элемента
+   * Определяет, указывает ли указанный путь на директорию.
+   * @param path path to the filesystem element / путь к элементу файловой системы
    */
   static isDir(path: PropertiesFilePath): boolean {
     if (this.is(path)) {
@@ -59,13 +56,10 @@ export class PropertiesFile {
   }
 
   /**
-   * The path.joinPath() method joins all given path segments together using the
-   * platform-specific separator as a delimiter, then normalizes the resulting path.
+   * Joins multiple path segments into a single normalized path string using the OS separator.
    *
-   * Метод path.joinPath() объединяет все указанные сегменты пути с использованием
-   * специфического для платформы разделителя в качестве разделителя,
-   * а затем нормализует полученный путь.
-   * @param path a sequence of path segments/ последовательность сегментов пути
+   * Объединяет несколько сегментов пути в одну нормализованную строку пути, используя разделитель ОС.
+   * @param path array or string of path segments / массив или строка сегментов пути
    */
   static joinPath(path: PropertiesFilePath): string {
     const pathArray = forEach(
@@ -344,10 +338,10 @@ export class PropertiesFile {
   }
 
   /**
-   * Returns the contents of the path.
+   * Synchronously reads and parses the contents of a file (JSON or raw text).
    *
-   * Возвращает содержимое пути.
-   * @param path filename/ имя файла
+   * Синхронно читает и парсит содержимое файла (JSON или обычный текст).
+   * @param path path to the target file / путь к целевому файлу
    */
   static readFile<R>(path: PropertiesFilePath): R | undefined {
     if (this.is(path)) {
@@ -391,13 +385,13 @@ export class PropertiesFile {
   }
 
   /**
-   * Writing data to a file.
+   * Writes data to a file at the specified location, automatically creating directories and formatting objects as JSON by default.
    *
-   * Запись данных в файл.
-   * @param path path to the file/ путь к файлу
-   * @param name file name/ название файла
-   * @param value values for storage/ значения для хранения
-   * @param extension file extension by default is ts/ расширение файла по умолчанию - ts
+   * Записывает данные в файл по указанному адресу, автоматически создавая директории и форматируя объекты в JSON по умолчанию.
+   * @param path base directory path / путь к базовой директории
+   * @param name target filename (without extension if extension provided) / имя целевого файла
+   * @param value data to be stored / данные для хранения
+   * @param extension file extension (defaults to 'json') / расширение файла (по умолчанию 'json')
    */
   static write<T extends PropertiesFileValue>(
     path: PropertiesFilePath,

package/src/classes/Properties/PropertiesImport.ts

@@ -20,9 +20,11 @@ import {
 } from '../../types/propertyTypes'
 
 /**
- * Class for working with external files, which adds them to the current list of properties.
+ * Resolver for external property references.
+ * This class orchestrates the inclusion of external design tokens into the primary property tree. It identifies file references, resolves paths (including nested directory imports and specific object path deep-linking via hashes), and merges the external data into the current configuration cluster.
  *
- * Класс для работы с внешними файлами, который подключает их к текущему списку свойств.
+ * Резолвер внешних ссылок на свойства.
+ * Этот класс координирует включение внешних токенов дизайна в основное дерево свойств. Он идентифицирует ссылки на файлы, разрешает пути (включая импорт вложенных директорий и глубокие ссылки на конкретные объекты через хеш) и объединяет внешние данные с текущим кластером конфигурации.
  */
 export class PropertiesImport {
   /**
@@ -38,12 +40,13 @@ export class PropertiesImport {
   }
 
   /**
-   * Method that adds external files to the current property.
+   * Resolves and merges external file references within a property cluster.
+   * Iterates through the properties, looks for items of type 'file', and recursively imports their content, supporting deep-linking (e.g., 'file.json#path.to.data').
    *
-   * Метод подключает внешние файлы к текущему свойству.
-   * @param properties An array that needs to be transformed/
-   * Массив, который нужно преобразовать
-   * @param root path to the directory/ путь к директории
+   * Разрешает и объединяет ссылки на внешние файлы внутри кластера свойств.
+   * Итерирует по свойствам, ищет элементы типа 'file' и рекурсивно импортирует их содержимое, поддерживая глубокие ссылки (например, 'file.json#path.to.data').
+   * @param properties the property list to process / список свойств для обработки
+   * @param root the base path segments for resolution / базовые сегменты пути для разрешения
    */
   to(
     properties = this.properties,

package/src/classes/Properties/PropertiesItems.ts

@@ -31,9 +31,11 @@ const SUPPORT_NAME = [
 ]
 
 /**
- * Class for working with a list of all properties.
+ * Coordinator for design property collections.
+ * This class provides a high-level API for traversing, searching, and extracting metadata from complex design token trees. It manages state related to design focusing (filtering view to a specific design set), converts complex path strings into normalized keys, and facilitates deep recursive iteration for token processing engines.
  *
- * Класс для работы со списком всех свойств.
+ * Координатор коллекций свойств дизайна.
+ * Этот класс предоставляет высокоуровневый API для обхода, поиска и извлечения метаданных из сложных деревьев токенов дизайна. Он управляет состоянием, связанным с фокусировкой дизайна (фильтрация представления для конкретного набора дизайнов), преобразует сложные строки путей в нормализованные ключи и упрощает глубокую рекурсивную итерацию для движков обработки токенов.
  */
 export class PropertiesItems {
   private focusDesign?: string
@@ -65,9 +67,11 @@ export class PropertiesItems {
   }
 
   /**
-   * Getting full structure property.
+   * Retrieves the current property structure.
+   * If a focus design is set, returns only the subset corresponding to that design and common constructor data; otherwise, returns the full collection.
    *
-   * Получение полной структуры свойства.
+   * Получает текущую структуру свойств.
+   * Если установлен фокус на дизайн, возвращает только подмножество, соответствующее этому дизайну и общим данным конструктора; в противном случае возвращает полную коллекцию.
    */
   get(): PropertyList {
     if (this.focusDesign) {
@@ -114,10 +118,12 @@ export class PropertiesItems {
   }
 
   /**
-   * Returns the full information about the element by its link.
+   * Resolves comprehensive metadata for a property element by its dotted index.
+   * Decodes the index, traverses the tree to find the target node, and synthesizes a detailed info object including parent hierarchy, name normalization, and raw values.
    *
-   * Возвращает полную информацию об элементе по его ссылке.
-   * @param index index for splitting/ индекс для разделения
+   * Разрешает полные метаданные элемента свойства по его индексу через точку.
+   * Декодирует индекс, обходит дерево для поиска целевого узла и синтезирует подробный объект информации, включая иерархию родителей, нормализацию имен и необработанные значения.
+   * @param index index for splitting / индекс для разделения
    */
   getInfo(index: string): PropertyItemsItem | undefined {
     const keys = this.getKeys(index)
@@ -376,12 +382,13 @@ export class PropertiesItems {
   }
 
   /**
-   * Recursively applies a custom function to each element of the property.
+   * Performs a deep recursive traversal of the property tree.
+   * Executes a callback for every node discovered. If a specific property node is provided, the traversal is restricted to its children; otherwise, the entire tree is visited.
    *
-   * Рекурсивно применяет пользовательскую функцию к каждому элементу свойства.
-   * @param callback the callback function is executed for each element/
-   * выполняется функция обратного вызова (callback) для каждого элемента
-   * @param property
+   * Выполняет глубокий рекурсивный обход дерева свойств.
+   * Выполняет callback для каждого обнаруженного узла. Если предоставлен конкретный узел свойства, обход ограничивается его дочерними элементами; в противном случае посещается все дерево.
+   * @param callback the callback function to execute for each element / функция обратного вызова для каждого элемента
+   * @param property optional start node for traversal / опциональный начальный узел для обхода
    */
   each<T>(
     callback: PropertyItemsCallback<T>,

package/src/classes/Properties/PropertiesKeys.ts

@@ -8,16 +8,20 @@ import { PropertiesTypes } from './PropertiesTypes'
 import { type PropertyItem } from '../../types/propertyTypes'
 
 /**
- * Key with all special keys for token processing.
+ * Parser and transformer for property key semantics.
+ * This static utility class handles the identification of special system keys (like metadata or internal references) and orchestrates the transformation of raw key names into normalized, context-aware tokens (e.g., prepending media types or converting to camelCase).
  *
- * Ключ со всеми специальными ключами для обработки токенов.
+ * Парсер и трансформер семантики ключей свойств.
+ * Этот статический вспомогательный класс обрабатывает идентификацию специальных системных ключей (таких как метаданные или внутренние ссылки) и координирует преобразование необработанных имен ключей в нормализованные токены с учетом контекста (например, добавление типов медиа или преобразование в camelCase).
  */
 export class PropertiesKeys {
   /**
-   * Checks if the variable is a special value.
+   * Identifies if a key is a protected system metadata key or an internal reference.
+   * Special keys include 'value', 'type', 'description', and any key starting with an underscore (internal engine states).
    *
-   * Проверяет, является ли переменная специальным значением.
-   * @param key key name/ название ключа
+   * Определяет, является ли ключ защищенным системным ключом метаданных или внутренней ссылкой.
+   * Специальные ключи включают 'value', 'type', 'description' и любой ключ, начинающийся с подчеркивания (внутренние состояния движка).
+   * @param key the key name to verify / название ключа для проверки
    */
   static isSpecialKey(key: string | number): key is keyof PropertyItem {
     return typeof key === 'string' && (
@@ -48,11 +52,13 @@ export class PropertiesKeys {
   }
 
   /**
-   * Returns the property name, discarding its prefix.
+   * Normalizes a raw key name by removing metadata prefixes and applying casing rules.
+   * Strips internal type symbols and leading pipes, then optionally converts the result to camelCase (unless the name is a path separator).
    *
-   * Возвращает имя свойства, отбрасывая его префикс.
-   * @param name key name/ название ключа
-   * @param camelCase to convert case/ преобразуйте этот текст в верхний регистр
+   * Нормализует необработанное имя ключа, удаляя префиксы метаданных и применяя правила регистра.
+   * Очищает внутренние символы типов и ведущие вертикальные черты, затем опционально преобразует результат в camelCase (если имя не является разделителем пути).
+   * @param name the raw key name / необработанное имя ключа
+   * @param camelCase whether to apply camelCase transformation / нужно ли применять преобразование в camelCase
    */
   static getName(name: string, camelCase = true): string {
     const newName = name

package/src/classes/Properties/PropertiesMain.ts

@@ -19,9 +19,11 @@ import type {
 const DIR_NAME = 'main'
 
 /**
- * A class for transforming global tokens.
+ * Orchestrator for global design token transformation.
+ * This class serves as the primary engine for loading, validating, and normalizing "main" tokens across all supported designs. It coordinates a multi-stage pipeline—including semantic conversion, reference import, and structural wrapping—to synthesize a unified property tree ready for consumption by external builders.
  *
- * Класс для преобразования глобальных токенов.
+ * Оркестратор глобальной трансформации токенов дизайна.
+ * Этот класс служит основным движком для загрузки, валидации и нормализации «основных» (main) токенов во всех поддерживаемых дизайнах. Он координирует многоэтапный конвейер — включая семантическую конвертацию, импорт ссылок и структурную обертку — для синтеза унифицированного дерева свойств, готового к использованию внешними строителями.
  */
 export class PropertiesMain {
   /**
@@ -34,9 +36,11 @@ export class PropertiesMain {
   }
 
   /**
-   * Returns all main tokens.
+   * Executes the full transformation pipeline for all main design tokens.
+   * Discovers token files via the path manager, then sequentially applies reading, conversion, standardization, link resolution, and structural wrapping for every design entry.
    *
-   * Возвращает все основные токены.
+   * Выполняет полный конвейер трансформации для всех основных токенов дизайна.
+   * Обнаруживает файлы токенов через менеджер путей, затем последовательно применяет чтение, конвертацию, стандартизацию, разрешение ссылок и структурную обертку для каждой записи дизайна.
    */
   get(): PropertyList {
     return this.path.toAll(DIR_NAME, (
@@ -66,10 +70,12 @@ export class PropertiesMain {
   }
 
   /**
-   * We get the main property taking into account the change of settings.
+   * Synchronizes global tokens with a provided settings cluster.
+   * Retrieves the full set of main tokens and deeply merges internal state flags from the settings list into the corresponding nodes of the global tree.
    *
-   * Получаем главное свойство с учетом изменения настроек.
-   * @param list list of settings/ список настроек
+   * Синхронизирует глобальные токены с предоставленным кластером настроек.
+   * Получает полный набор основных токенов и глубоко объединяет флаги внутреннего состояния из списка настроек в соответствующие узлы глобального дерева.
+   * @param list the settings cluster to apply / кластер настроек для применения
    */
   getBySettings(list: PropertyList): PropertyList {
     const data = this.get()

package/src/classes/Properties/PropertiesPalette.ts

@@ -14,9 +14,11 @@ import {
 } from '../../types/propertyTypes'
 
 /**
- * Class for working with colors.
+ * Manager for design palette and color saturation.
+ * This class handles the extraction of available shade levels (saturation steps) and tracks the usage of palette colors across the design system. It facilitates the mapping between functional variables and their underlying palette definitions, ensuring that generated styles correctly reference the intended theme colors.
  *
- * Класс для работы с цветами.
+ * Менеджер палитры дизайна и насыщенности цветов.
+ * Этот класс обрабатывает извлечение доступных уровней оттенков (шагов насыщенности) и отслеживает использование цветов палитры в системе дизайна. Он упрощает сопоставление функциональных переменных с их базовыми определениями в палитре, гарантируя, что сгенерированные стили правильно ссылаются на нужные цвета темы.
  */
 export class PropertiesPalette {
   /**
@@ -28,9 +30,11 @@ export class PropertiesPalette {
   }
 
   /**
-   * Returns a list of available saturation levels.
+   * Retrieves a list of available saturation levels (shades) grouped by design.
+   * Scans the token cluster for items categorized as 'shade' and returns their resolved value structures.
    *
-   * Возвращает список доступных уровней насыщенности.
+   * Возвращает список доступных уровней насыщенности (оттенков), сгруппированных по дизайну.
+   * Сканирует кластер токенов на наличие элементов, классифицированных как 'shade', и возвращает их разрешенные структуры значений.
    */
   getShade(): PropertyPaletteList {
     return forEach(this.items.findCategory(PropertyCategory.shade), ({
@@ -49,9 +53,11 @@ export class PropertiesPalette {
   }
 
   /**
-   * Getting a list of used values.
+   * Generates a report of all palette colors currently utilized in functional variables.
+   * Iterates through the entire property tree to identify variables referencing palette colors and maps them to their corresponding CSS variable names.
    *
-   * Получаем список использованных значений.
+   * Генерирует отчет обо всех цветах палитры, используемых в данный момент в функциональных переменных.
+   * Итерирует по всему дереву свойств для идентификации переменных, ссылающихся на цвета палитры, и сопоставляет их с соответствующими именами CSS-переменных.
    */
   getUsed(): PropertyPaletteUsed[] {
     const list = this.getList()

package/src/classes/Properties/PropertiesPath.ts

@@ -24,9 +24,11 @@ export type PropertiesPathList = PropertiesPathItem[]
 const DIR_CACHE = 'read'
 
 /**
- * Class for working with paths by the given name of the design.
+ * Directory and path resolver for multi-design token environments.
+ * This class translates abstract design names into concrete filesystem paths for global tokens and component-specific settings. It coordinates the cross-platform path discovery flow and provided cached traversal mechanisms (`to`, `toAll`) to efficiently process token files across the entire project structure.
  *
- * Класс для работы с путями по заданному названию дизайна.
+ * Резолвер директорий и путей для сред с несколькими дизайнами токенов.
+ * Этот класс преобразует абстрактные названия дизайнов в конкретные пути файловой системы для глобальных токенов и настроек компонентов. Он координирует процесс обнаружения путей на разных платформах и предоставляет механизмы кэшированного обхода (`to`, `toAll`) для эффективной обработки файлов токенов во всей структуре проекта.
  */
 export class PropertiesPath {
   private readonly paths: PropertiesPathList
@@ -92,12 +94,14 @@ export class PropertiesPath {
   }
 
   /**
-   * Processes all token values for the selected design and combines them into one-big array.
+   * Executes a cached transformation for a specific design and token group.
+   * Resolves paths for the target design, executes the provided callback to process the data, and caches the result for future performance. Ideal for processing individual themes or component layers within a theme.
    *
-   * Обрабатывает все значения токена у выбранного дизайна и соединяет их в одну-большую массива.
-   * @param name name of the group/ названия группы
-   * @param design design name/ название дизайна
-   * @param callback function for processing/ функция для обработки
+   * Выполняет кэшированную трансформацию для конкретного дизайна и группы токенов.
+   * Разрешает пути для целевого дизайна, выполняет предоставленный callback для обработки данных и кэширует результат. Идеально подходит для обработки отдельных тем или слоев компонентов внутри темы.
+   * @param name unique name for the processing group (used as cache key) / уникальное имя группы обработки (используется как ключ кэша)
+   * @param design names of the design to process / названия дизайна для обработки
+   * @param callback function that receives resolved paths and returns processed data / функция, которая получает разрешенные пути и возвращает обработанные данные
    */
   to(
     name: string,
@@ -128,11 +132,13 @@ export class PropertiesPath {
   }
 
   /**
-   * Processes all token values for all designs and combines them into one-big array.
+   * Orchestrates a global cached transformation across all registered designs.
+   * Iterates through every design defined in the constructor, processes its tokens using the provided callback, and merges the results into a single unified property tree.
    *
-   * Обрабатывает все значения токена у всех дизайнов и соединяет их в одну-большую массива.
-   * @param name name of the group/ названия группы
-   * @param callback function for processing/ функция для обработки
+   * Координирует глобальную кэшированную трансформацию для всех зарегистрированных дизайнов.
+   * Итерирует по каждому дизайну, определенному в конструкторе, обрабатывает его токены с помощью предоставленного callback и объединяет результаты в единое унифицированное дерево свойств.
+   * @param name unique name for the global processing group / уникальное имя глобальной группы обработки
+   * @param callback function for processing individual designs / функция для обработки отдельных дизайнов
    */
   toAll(
     name: string,