@dxtmisha/scripts 0.7.2 → 0.7.6

package/src/classes/Design/DesignTypes.ts

@@ -1,16 +1,19 @@
 import { forEach } from '@dxtmisha/functional-basic'
+import { getPackageJson } from '../../functions/getPackageJson'
 import { useAi } from '../../composables/useAi'
 
 import { PropertiesFile } from '../Properties/PropertiesFile'
 
 import type { DesignTypesList } from '../../types/designTypes'
 
-import { UI_FILE_AI_TYPES } from '../../config'
+import { UI_DIR_CONSTRUCTOR, UI_FILE_AI_TYPES } from '../../config'
 
 /**
- * Class for generating AI-optimized type definitions.
+ * Engine for generating compressed and AI-optimized TypeScript type definitions.
+ * It scans the build output for declaration files, sanitizes them, and uses AI to produce a minimal, context-rich type library for use in automated coding assistants.
  *
- * Класс для генерации оптимизированных ИИ определений типов.
+ * Движок для генерации сжатых и оптимизированных для ИИ определений типов TypeScript.
+ * Сканирует выходные данные сборки на наличие файлов деклараций, очищает их и использует ИИ для создания минимальной, насыщенной контекстом библиотеки типов для использования в автоматизированных помощниках по кодированию.
  */
 export class DesignTypes {
   /**
@@ -21,8 +24,10 @@ export class DesignTypes {
   protected readonly dirArray: string[]
 
   /**
-   * Constructor
-   * @param dir directory path / путь к директории
+   * Constructor for DesignTypes.
+   *
+   * Конструктор для DesignTypes.
+   * @param dir input directory path containing declaration files / входной путь к директории, содержащей файлы деклараций
    */
   constructor(
     protected readonly dir: string = 'dist'
@@ -58,12 +63,14 @@ export class DesignTypes {
    */
   protected isFile(file: string): boolean {
     return file.endsWith('.d.ts')
+      && !file.endsWith('.vue.d.ts')
+      && !file.endsWith('wiki.d.ts')
+      && !file.endsWith('wikiData.d.ts')
       && (
-        !file.includes('constructors/')
-        || (
-          !file.endsWith('/props.d.ts')
-          && !file.endsWith('/types.d.ts')
-        )
+        !file.includes(`${UI_DIR_CONSTRUCTOR}/`)
+        || file.endsWith('/basicTypes.d.ts')
+        || file.endsWith('/types.d.ts')
+        || file.endsWith('/props.d.ts')
       )
   }
 
@@ -75,11 +82,9 @@ export class DesignTypes {
    */
   protected isContent(content?: string): content is string {
     return Boolean(
-      content && (
-        content.includes('export interface')
-        || content.includes('export type')
-        || content.includes('export enum')
-      ))
+      content
+      && content.includes('export')
+    )
   }
 
   /**
@@ -143,10 +148,23 @@ export class DesignTypes {
    * @param content content to save / контент для сохранения
    */
   protected save(content: string) {
-    PropertiesFile.writeByPath(
-      UI_FILE_AI_TYPES,
-      content
-    )
+    const packageJson = getPackageJson()
+
+    if (packageJson) {
+      PropertiesFile.writeByPath(
+        UI_FILE_AI_TYPES,
+        [
+          `1) All these methods are in the ${packageJson.name} library.`,
+          '2) Everything that is exported can be used.',
+          '3) Use what is in this library if it exists; do not use other libraries if there is an analogue here. Do not create new ones if an analogue already exists here.',
+          '',
+          'The following is the content of "exports" from package.json:',
+          JSON.stringify(packageJson.exports, null, 2),
+          '',
+          content
+        ].join('\n')
+      )
+    }
   }
 
   /**
@@ -173,18 +191,25 @@ export class DesignTypes {
     const ai = useAi()
 
     if (ai) {
-      ai.addPrompt(`File Content: ${content}`)
-
-      const generate = await ai.generate(
+      ai.addPrompt(
         'Remove all Russian comments from this code. '
-        + 'Remove comments if the property name makes its purpose obvious. '
+        + 'Simplify and shorten all English comments for AI readability while maintaining a clear balance between brevity and context. Do not delete them even if the code seems obvious. '
+        + 'Always keep All JSDoc "@example", "@remarks", "@note", and any other notes or warnings. '
         + 'Remove all imports. '
-        + 'Remove empty lines. '
-        + 'Remove the "export" keyword if possible. '
-        + 'Keep only "type", "interface" and "enum" definitions, remove everything else. '
-        + 'Minimize the content as much as possible without losing any data or logic. '
-        + 'Return only the corrected code without any additional text or explanations.'
+        + 'Remove all non-public content: delete all private and protected class methods and properties, and any non-exported elements. The final output must contain only the members and entities that are accessible from outside. '
+        + 'Remove any code segments or data that do not provide useful information for an AI assistant. '
+        + 'You may remove abstract classes or other structures that provide no practical value for code generation, but do so with extreme caution. Maintain a strict balance: if there is even a 5% chance the item might be relevant for understanding the API or generating code, keep it. Think carefully before every deletion. '
+        + 'Remove any large Enums that add excessive length without providing critical context. '
+        + 'Your goal is to create a compact, context-rich file that enables any AI coding assistant to generate high-quality code for a developer. '
+        + 'Ensure that no public API surface, essential data types, or required logic is lost. '
+        + 'Do not delete any "type" definitions; they are strictly required. '
+        + 'Do not delete file paths (labels starting with "// File:"). '
+        + 'All instructions are mandatory and must be executed perfectly. '
+        + 'Return ONLY the resulting code. No markdown code blocks, no tags, no explanations, and no additional comments from the AI. NOTHING but the pure code.'
       )
+      ai.addPrompt(`File Content: ${content}`)
+
+      const generate = await ai.generate('go!')
 
       if (generate) {
         return generate

package/src/classes/Design/DesignTypescript.ts

@@ -9,9 +9,11 @@ import type {
 } from '../../types/designTypes'
 
 /**
- * Class for working with TypeScript types
+ * Utility for interacting with the TypeScript Compiler API to analyze and extract type metadata from source files.
+ * It parses interfaces and type aliases to retrieve property details, including types, literal unions, and documentation comments.
  *
- * Класс для работы с типами TypeScript
+ * Утилита для взаимодействия с TypeScript Compiler API для анализа и извлечения метаданных типов из исходных файлов.
+ * Анализирует интерфейсы и псевдонимы типов для получения сведений о свойствах, включая типы, литеральные объединения и комментарии к документации.
  */
 export class DesignTypescript {
   protected readonly program: ts.Program
@@ -19,6 +21,13 @@ export class DesignTypescript {
   protected readonly sourceFile?: ts.SourceFile
   protected types?: DesignTypescriptList
 
+  /**
+   * Constructor for DesignTypescript.
+   *
+   * Конструктор для DesignTypescript.
+   * @param path path to the TypeScript source file to analyze / путь к исходному файлу TypeScript для анализа
+   * @param options compiler options for the TypeScript program / опции компилятора для программы TypeScript
+   */
   constructor(
     path: string = '',
     options: ts.CompilerOptions = {}

package/src/classes/Design/DesignUi.ts

@@ -18,14 +18,23 @@ import { LibraryList } from '../Library/LibraryList'
 import { LibraryPlugin } from '../Library/LibraryPlugin'
 import { LibraryTypes } from '../Library/LibraryTypes'
 
-import { UI_FILE_PACKAGE } from '../../config'
-
+import { UI_FILE_PACKAGE, UI_FILE_STYLE_PROPERTIES } from '../../config'
+
+/**
+ * Orchestrator class for managing and initializing the Design System UI.
+ * It coordinates the generation of styles, documentation, component structures, and library-level exports (media, plugins, types).
+ *
+ * Класс-оркестратор для управления и инициализации пользовательского интерфейса дизайн-системы.
+ * Координирует генерацию стилей, документации, структур компонентов и экспортов на уровне библиотеки (медиа, плагины, типы).
+ */
 export class DesignUi {
   protected readonly components: LibraryItems
 
   /**
-   * Constructor
-   * @param name component name/ названия компонента
+   * Constructor for DesignUi.
+   *
+   * Конструктор для DesignUi.
+   * @param name specific component name to initialize, or empty for all / название конкретного компонента для инициализации или пусто для всех
    */
   constructor(
     protected readonly name: string = ''
@@ -54,7 +63,8 @@ export class DesignUi {
     new DesignWiki().make()
 
     this.makeConstructorComponent()
-    this.makePackage()
+      .makePackage()
+      .makeUiProperties()
 
     new LibraryMedia(this.components).make()
     new LibraryList(this.components).make()
@@ -90,23 +100,44 @@ export class DesignUi {
    *
    * Обновляет файл package.json, добавляя пути экспорта для стилей UI, и сохраняет изменения.
    */
-  protected makePackage(): void {
+  protected makePackage(): this {
     const packageJson = getPackageJson()
     const projectName = toCamelCaseFirst(PropertiesConfig.getProjectName())
 
     if (packageJson?.exports) {
+      packageJson.exports['.'] = {
+        types: './dist/library/types.d.ts',
+        default: './dist/types.js'
+      }
       packageJson.exports['./plugin'] = {
-        import: './dist/plugin.js',
-        types: './dist/library/plugin.d.ts'
+        types: './dist/library/plugin.d.ts',
+        default: './dist/plugin.js'
+      }
+      packageJson.exports['./media'] = {
+        types: './dist/library/media.d.ts',
+        default: './dist/media.js'
       }
       packageJson.exports['./style.css'] = './dist/style.css'
       packageJson.exports['./style/ui.scss'] = `./src/styles/${projectName}/main.scss`
-      packageJson.exports['./style/ui-properties.scss'] = `./src/styles/${projectName}/style.scss`
-      packageJson.exports['./types.d.ts'] = {
-        types: './dist/library/types.d.ts'
+      packageJson.exports['./ui-properties'] = {
+        sass: './ui-properties.scss',
+        default: './ui-properties.scss'
       }
+      packageJson.exports['./types.d.ts'] = './dist/library/types.d.ts'
+      packageJson['web-types'] = './dist/web-types.json'
 
       PropertiesFile.writeByPath(UI_FILE_PACKAGE, packageJson)
     }
+
+    return this
+  }
+
+  protected makeUiProperties(): this {
+    PropertiesFile.writeByPath(
+      UI_FILE_STYLE_PROPERTIES,
+      '@forward "./src/styles/Ui/style.scss";'
+    )
+
+    return this
   }
 }

package/src/classes/Design/DesignWiki.ts

@@ -11,13 +11,11 @@ import {
 } from '../../config'
 
 /**
- * The DesignWiki class is responsible for managing and generating files
- * that contain descriptions of components for the wiki. It ensures that
- * the necessary files are created and initialized properly.
+ * Utility for managing and generating the central wiki configuration for the design system.
+ * It ensures that the primary registry for storybook arguments and component descriptions is correctly initialized and synchronized with the project's design configuration.
  *
- * Класс DesignWiki отвечает за управление и генерацию файлов,
- * содержащих описания компонентов для wiki. Он гарантирует, что
- * необходимые файлы создаются и инициализируются должным образом.
+ * Утилита для управления и генерации центральной конфигурации вики для дизайн-системы.
+ * Гарантирует, что основной реестр аргументов Storybook и описаний компонентов правильно инициализирован и синхронизирован с конфигурацией дизайна проекта.
  */
 export class DesignWiki {
   /**

package/src/classes/Design/DesignWikiStorm.ts

@@ -0,0 +1,94 @@
+import { toCamelCaseFirst } from '@dxtmisha/functional-basic'
+import { getPackageJson } from '../../functions/getPackageJson'
+
+import { PropertiesConfig } from '../Properties/PropertiesConfig'
+import { PropertiesFile } from '../Properties/PropertiesFile'
+import { LibraryItems } from '../Library/LibraryItems'
+import { DesignWikiStormItem } from './DesignWikiStormItem'
+
+import type { WebTypesTags, WebTypesVueJson } from '../../types/webTypes'
+
+/**
+ * Engine for generating `web-types.json` to provide rich metadata and IDE support (IntelliSense) for the design system components in JetBrains editors (IntelliJ IDEA, WebStorm).
+ * It aggregates component tags, attributes, and events from the entire library and formats them into the standard Web-Types schema.
+ *
+ * Движок для генерации `web-types.json`, обеспечивающий расширенные метаданные и поддержку IDE (IntelliSense) для компонентов дизайн-системы в редакторах JetBrains (IntelliJ IDEA, WebStorm).
+ * Он агрегирует теги компонентов, атрибуты и события из всей библиотеки и форматирует их в стандартную схему Web-Types.
+ */
+export class DesignWikiStorm {
+  protected readonly components: LibraryItems
+
+  /**
+   * Constructor for DesignWikiStorm.
+   *
+   * Конструктор для DesignWikiStorm.
+   * @param dir target directory for saving the `web-types.json` file / целевая директория для сохранения файла `web-types.json`
+   */
+  constructor(
+    protected dir: string = 'dist'
+  ) {
+    this.components = new LibraryItems()
+  }
+
+  /**
+   * Generates the web-types.json file.
+   *
+   * Генерирует файл web-types.json.
+   */
+  async make(): Promise<void> {
+    const packageFile = getPackageJson()
+
+    console.log('[DesignWikiStorm] make')
+
+    if (packageFile) {
+      const data: WebTypesVueJson = {
+        $schema: 'https://json.schemastore.org/web-types',
+        framework: 'vue',
+        name: toCamelCaseFirst(PropertiesConfig.getDesignName()),
+        version: packageFile.version,
+        contributions: {
+          html: {
+            'types-syntax': 'typescript',
+            'description-markup': 'markdown',
+            'tags': await this.getComponents()
+          }
+        }
+      }
+
+      PropertiesFile.writeByPath(
+        [this.dir, 'web-types.json'],
+        data
+      )
+    }
+  }
+
+  /**
+   * Creates or updates the list of components.
+   *
+   * Создает или обновляет список компонентов.
+   */
+  protected async getComponents(): Promise<WebTypesTags> {
+    const packageFile = getPackageJson()
+    const tags: WebTypesTags = []
+
+    if (packageFile) {
+      for (const component of this.components.getComponentList()) {
+        const item = new DesignWikiStormItem(
+          packageFile.name,
+          this.components.getComponentsPath(),
+          component
+        )
+
+        await item.init()
+
+        const tag = await item.get()
+
+        if (tag) {
+          tags.push(tag)
+        }
+      }
+    }
+
+    return tags
+  }
+}

package/src/classes/Design/DesignWikiStormItem.ts

@@ -0,0 +1,246 @@
+import { toCamelCaseFirst } from '@dxtmisha/functional'
+import { type WikiDataItem, WikiStorybook, WikiStorybookProp } from '@dxtmisha/wiki'
+import { wiki, wikiDescriptions } from '@dxtmisha/wiki/media'
+
+import { PropertiesConfig } from '../Properties/PropertiesConfig'
+import { PropertiesFile } from '../Properties/PropertiesFile'
+
+import type { LibraryData } from '../../types/libraryTypes'
+import type { WebTypesAttributeItem, WebTypesAttributes, WebTypesEvents, WebTypesSlots, WebTypesTagItem } from '../../types/webTypes'
+
+/**
+ * Resolver for extracting and formatting IDE metadata for a specific component.
+ * It coordinates the transformation of Storybook-specific wiki data into JetBrains Web-Types tag and attribute definitions.
+ *
+ * Резолвер для извлечения и форматирования метаданных IDE для конкретного компонента.
+ * Координирует преобразование данных вики для Storybook в определения тегов и атрибутов JetBrains Web-Types.
+ */
+export class DesignWikiStormItem {
+  protected wiki?: WikiStorybook
+  protected dataComponent?: WikiDataItem
+
+  /**
+   * Constructor for DesignWikiStormItem.
+   *
+   * Конструктор для DesignWikiStormItem.
+   * @param project name of the project for module mapping / имя проекта для маппинга модулей
+   * @param path array of directory path segments to the component / массив сегментов пути к директории компонента
+   * @param data component metadata from the library / метаданные компонента из библиотеки
+   */
+  constructor(
+    protected readonly project: string,
+    protected readonly path: string[],
+    protected readonly data: LibraryData
+  ) {
+  }
+
+  /**
+   * Returns the tag definition for web-types.
+   *
+   * Возвращает определение тега для web-types.
+   */
+  async get(): Promise<WebTypesTagItem | undefined> {
+    if (this.wiki) {
+      const name = `${toCamelCaseFirst(PropertiesConfig.getDesignName())}${this.wiki.getName()}`
+
+      const tag: WebTypesTagItem = {
+        name,
+        description: this.wiki.getDescription(),
+        source: {
+          module: `${this.project}/${name}`,
+          symbol: name
+        },
+        attributes: this.getAttributes()
+      }
+
+      const slots = await this.getSlots()
+
+      if (slots) {
+        tag.slots = slots
+      }
+
+      const events = await this.getEvents()
+
+      if (events) {
+        tag.events = events
+      }
+
+      return tag
+    }
+
+    return undefined
+  }
+
+  /**
+   * Returns the attribute definition.
+   *
+   * Возвращает определение атрибута.
+   * @param item prop item / элемент свойства
+   */
+  getAttribute(item: WikiStorybookProp): WebTypesAttributeItem {
+    return {
+      name: item.getName(),
+      description: item.getDescription(),
+      default: item.getDefaultValue(),
+      value: {
+        kind: 'expression',
+        type: item.getType()
+      }
+    }
+  }
+
+  /**
+   * Returns a list of attributes.
+   *
+   * Возвращает список атрибутов.
+   */
+  getAttributes(): WebTypesAttributes {
+    const attributes: WebTypesAttributes = []
+
+    if (this.wiki) {
+      this.wiki.getWikiObject()
+        .forEach(
+          props => attributes.push(this.getAttribute(props))
+        )
+    }
+
+    return attributes
+  }
+
+  /**
+   * Returns a list of slots.
+   *
+   * Возвращает список слотов.
+   */
+  async getSlots(): Promise<WebTypesSlots | undefined> {
+    const data = await this.getData()
+
+    if (data && data.slots) {
+      const slots: WebTypesSlots = []
+
+      data.slots.forEach(
+        props => slots.push({
+          name: props.name,
+          description: props.description,
+          'vue-properties': props.properties ?? []
+        })
+      )
+
+      return slots
+    }
+
+    return undefined
+  }
+
+  /**
+   * Returns a list of events.
+   *
+   * Возвращает список событий.
+   */
+  async getEvents(): Promise<WebTypesEvents | undefined> {
+    const data = await this.getData()
+
+    if (data && data.events) {
+      const events: WebTypesEvents = []
+
+      data.events.forEach(
+        event => events.push({
+          name: event.name,
+          description: event.description,
+          arguments: event.properties ?? []
+        })
+      )
+
+      return events
+    }
+
+    return undefined
+  }
+
+  /**
+   * Returns the directory name.
+   *
+   * Возвращает имя директории.
+   */
+  getDirName() {
+    return this.data.dir
+  }
+
+  /**
+   * Initializes the class.
+   *
+   * Инициализирует класс.
+   */
+  async init(): Promise<this> {
+    this.wiki = await this.initWiki()
+    return this
+  }
+
+  /**
+   * Gets data from wikiData.ts.
+   *
+   * Получает данные из wikiData.ts.
+   */
+  protected async getData(): Promise<WikiDataItem | undefined> {
+    if (!this.dataComponent) {
+      const filePath = this.getPaths(['wikiData.ts'])
+
+      if (PropertiesFile.is(filePath)) {
+        const wiki: Record<string, any> = await import(filePath.join('/'))
+        const data: WikiDataItem | undefined = Object.values(wiki).find(item => 'component' in item)
+
+        this.dataComponent = data
+      }
+    }
+
+    return this.dataComponent
+  }
+
+  /**
+   * Returns the list of directories.
+   *
+   * Возвращает список директорий.
+   */
+  protected getDirs(): string[] {
+    return [
+      '.',
+      ...this.path,
+      this.getDirName()
+    ]
+  }
+
+  /**
+   * Returns the full path to the file.
+   *
+   * Возвращает полный путь к файлу.
+   * @param paths path segments / сегменты пути
+   */
+  protected getPaths(paths: string[]): string[] {
+    return [
+      ...this.getDirs(),
+      ...paths
+    ]
+  }
+
+  /**
+   * Initializes the wiki object.
+   *
+   * Инициализирует объект wiki.
+   */
+  protected async initWiki(): Promise<WikiStorybook | undefined> {
+    const data = await this.getData()
+
+    if (data) {
+      return new WikiStorybook(
+        data.component,
+        data.props,
+        data.defaults,
+        data.wikiDesign,
+        wiki,
+        wikiDescriptions
+      )
+    }
+
+    return undefined
+  }
+}

package/src/classes/Git/GitRead.ts

@@ -253,6 +253,7 @@ export class GitRead {
    *
    * Выполняет Git команду и возвращает результат.
    * @param command - command to execute / команда для выполнения
+   * @protected
    */
   protected static exec(command: string): string {
     return execSync(command, { encoding: 'utf8' }).trim()