@dxtmisha/scripts 0.6.3 → 0.7.6

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()

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

@@ -0,0 +1,127 @@
+import { PropertiesFile } from '../Properties/PropertiesFile'
+import { LibraryItems } from './LibraryItems'
+import { LibraryAiWikiItem } from './LibraryAiWikiItem'
+
+import { UI_DIRS_COMPONENTS } from '../../config'
+
+/**
+ * Class for creating a list of components for AI Wiki.
+ *
+ * Класс для создания списка компонентов для AI Wiki.
+ */
+export class LibraryAiWiki {
+  /**
+   * Constructor
+   * @param items object for working with the list of components / объект для работы со списком компонентов
+   */
+  constructor(
+    protected readonly items: LibraryItems
+  ) {
+  }
+
+  /**
+   * Creates files for AI Wiki.
+   *
+   * Создает файлы для AI Wiki.
+   */
+  make(): void {
+    this.makeList()
+    this.makeComponent()
+  }
+
+  /**
+   * Returns the file name for the list.
+   *
+   * Возвращает имя файла для списка.
+   */
+  protected getFileList(): string {
+    return 'ai-list'
+  }
+
+  /**
+   * Returns a list of components for AI Wiki.
+   *
+   * Возвращает список компонентов для AI Wiki.
+   */
+  protected getList(): LibraryAiWikiItem[] {
+    const data: LibraryAiWikiItem[] = []
+
+    this.items.getComponentList()
+      .forEach((component) => {
+        const aiWiki = new LibraryAiWikiItem(component)
+
+        if (aiWiki.isAiWiki()) {
+          data.push(aiWiki)
+        }
+      })
+
+    return data
+  }
+
+  /**
+   * Creates a file with a list of components.
+   *
+   * Создает файл со списком компонентов.
+   */
+  protected makeList(): void {
+    const data = this.getList()
+    const imports: string[] = []
+    const list: string[] = []
+
+    console.log('Ai wiki:', data.length, 'components')
+
+    data.forEach((item) => {
+      imports.push(item.getImport())
+      list.push(`  ${item.getCode()}`)
+    })
+
+    this.items.write(
+      this.getFileList(),
+      [
+        ...imports,
+        '',
+        'export const aiList: any[] = [',
+        list.join(',\r\n'),
+        ']'
+      ],
+      'wiki.ts'
+    )
+  }
+
+  /**
+   * Creates a component for displaying the list.
+   *
+   * Создает компонент для отображения списка.
+   */
+  protected makeComponent() {
+    PropertiesFile.writeByPath(
+      [...UI_DIRS_COMPONENTS, 'AiWiki.vue'],
+      `<script setup lang="ts">
+// This file is generated by a script, do not edit.
+
+import { DxtTestPage, DxtTestWikiAnchor, DxtTestWikiHide } from '@dxtmisha/test'
+import { aiList } from '../library/${this.getFileList()}.wiki'
+
+defineOptions({
+  name: 'AiWiki'
+})
+</script>
+
+<template>
+  <DxtTestPage
+    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"
+      :key="key"
+      :is="item"
+    />
+  </DxtTestPage>
+</template>
+`
+    )
+  }
+}

package/src/classes/Library/LibraryAiWikiItem.ts

@@ -0,0 +1,79 @@
+import type { LibraryData } from '../../types/libraryTypes'
+
+import { PropertiesConfig } from '../Properties/PropertiesConfig'
+import { PropertiesFile } from '../Properties/PropertiesFile'
+
+import { UI_DIRS_COMPONENTS } from '../../config'
+
+/**
+ * Class for working with the AI Wiki component.
+ *
+ * Класс для работы с компонентом AI Wiki.
+ */
+export class LibraryAiWikiItem {
+  /**
+   * Constructor
+   * @param item component data / данные компонента
+   */
+  constructor(
+    protected readonly item: LibraryData
+  ) {
+  }
+
+  /**
+   * Checks if the AI Wiki file exists.
+   *
+   * Проверяет, существует ли файл AI Wiki.
+   */
+  isAiWiki(): boolean {
+    return PropertiesFile.is(this.getPath())
+  }
+
+  /**
+   * Returns the component code.
+   *
+   * Возвращает код компонента.
+   */
+  getCode(): string {
+    return this.item.codeFull
+  }
+
+  /**
+   * Returns the file name for the AI Wiki component.
+   *
+   * Возвращает имя файла для компонента AI Wiki.
+   */
+  getComponentFileNameAiWiki(): string {
+    return `${this.item.codeFull}AiWiki.vue`
+  }
+
+  /**
+   * Returns the import string for the component.
+   *
+   * Возвращает строку импорта для компонента.
+   */
+  getImport(): string {
+    const code = this.item.codeFull
+    const path: string[] = [
+      '..',
+      '..',
+      ...this.getPath()
+    ]
+
+    return `import ${code} from '${path.join('/')}'`
+  }
+
+  /**
+   * Returns the path to the file.
+   *
+   * Возвращает путь к файлу.
+   */
+  protected getPath(): string[] {
+    return [
+      ...UI_DIRS_COMPONENTS,
+      PropertiesConfig.getProjectName(),
+      this.item.dir,
+      this.getComponentFileNameAiWiki()
+    ]
+  }
+}

package/src/classes/Library/LibraryExport.ts

@@ -1,5 +1,3 @@
-// export:none
-
 import { PropertiesFile } from '../Properties/PropertiesFile'
 
 import type { LibraryFiles } from '../../types/libraryTypes'

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