@dxtmisha/scripts 0.11.8 → 1.0.0

package/src/classes/Design/DesignTypesPrompts.ts

@@ -1,332 +0,0 @@
-import { createHash } from 'node:crypto'
-import { forEach, isFilled } from '@dxtmisha/functional-basic'
-import { PropertiesFile } from '../Properties/PropertiesFile'
-import { DesignTypesAi } from './DesignTypesAi'
-
-import type {
-  DesignTypesItem,
-  DesignTypesList,
-  DesignTypesPromptCacheItem,
-  DesignTypesPromptCacheList,
-  DesignTypesPromptData,
-  DesignTypesPromptResult
-} from '../../types/designTypes'
-
-import { UI_DIR_AI_TYPES_LIST, UI_DIR_RESOURCES, UI_MODULES } from '../../config'
-
-/**
- * Class for reading prompt files, managing individual prompt metadata files, and generating AI project rules and prompt triggers description.
- *
- * Класс для чтения файлов промптов, управления отдельными файлами метаданных промптов и генерации описания правил проекта ИИ и триггеров промптов.
- */
-export class DesignTypesPrompts {
-  /** Cached list of prompt files / Кэшированный список файлов с промптами */
-  protected listPrompts?: DesignTypesList
-
-  /** Cached prompt AI metadata list / Кэшированный список метаданных промптов ИИ */
-  protected cacheList?: DesignTypesPromptCacheList
-
-  /**
-   * Constructor for DesignTypesPrompts.
-   *
-   * Конструктор для DesignTypesPrompts.
-   * @param promptsDir input directory path containing prompt files / входной путь к директории, содержащей файлы промптов
-   * @param ai instance of DesignTypesAi for AI interactions / экземпляр DesignTypesAi для ИИ взаимодействия
-   */
-  constructor(
-    protected readonly promptsDir: string = 'ai-resources',
-    protected readonly ai: DesignTypesAi
-  ) { }
-
-  /**
-   * Reads and returns the prompt cache list from individual JSON files in the resources directory.
-   *
-   * Читает и возвращает список кэша промптов из отдельных JSON файлов в директории ресурсов.
-   * @returns prompt cache list / список кэша промптов
-   */
-  getCacheList(): DesignTypesPromptCacheList {
-    if (this.cacheList === undefined) {
-      const cacheDir = this.getCacheDir()
-      const files = PropertiesFile.readDirRecursive(cacheDir)
-      const list: DesignTypesPromptCacheList = []
-
-      for (const file of files) {
-        if (file.endsWith('.json')) {
-          const item = PropertiesFile.readFile<DesignTypesPromptCacheItem>([cacheDir, file])
-
-          if (
-            item
-            && isFilled(item.path)
-            && isFilled(item.name)
-            && isFilled(item.description)
-          ) {
-            list.push(item)
-          }
-        }
-      }
-
-      this.cacheList = list
-    }
-
-    return this.cacheList
-  }
-
-  /**
-   * Gets a list of prompt files.
-   *
-   * Получает список файлов с промптами.
-   * @returns list of prompt files / список файлов с промптами
-   */
-  getListPrompts(): DesignTypesList {
-    if (this.listPrompts === undefined) {
-      const files = PropertiesFile.readDirRecursive(this.promptsDir)
-
-      this.listPrompts = forEach(
-        files,
-        (file) => {
-          if (file.endsWith('.json')) {
-            return undefined
-          }
-
-          const path = `${this.promptsDir}/${file}`
-          const content = PropertiesFile.readFileOnly(path)
-
-          if (content) {
-            return {
-              path,
-              content,
-              md5: this.getMd5(content)
-            }
-          }
-        }
-      ) as DesignTypesList
-    }
-
-    return this.listPrompts
-  }
-
-  /**
-   * Initializes prompt rules by executing cache processing and returning formatted prompt rule strings.
-   *
-   * Инициализирует правила промптов, выполняя обработку кэша и возвращая список отформатированных строк правил промптов.
-   * @returns array of formatted prompt rule strings / массив отформатированных строк правил промптов
-   */
-  async init(): Promise<string[]> {
-    await this.make()
-
-    const list = this.getListPrompts()
-    const cache = this.getCacheList()
-    const prompts: string[] = []
-
-    for (const item of list) {
-      const cachedItem = cache.find(itemCache => itemCache.path === item.path)
-
-      if (cachedItem && isFilled(cachedItem.description)) {
-        prompts.push(this.getPromptLine(item.path, cachedItem.description))
-      }
-    }
-
-    return prompts
-  }
-
-  /**
-   * Processes prompt files using AI and updates individual JSON cache files if changes are detected.
-   *
-   * Обрабатывает файлы промптов с помощью ИИ и обновляет отдельные JSON файлы кэша при обнаружении изменений.
-   * @returns current instance / текущий экземпляр
-   */
-  async make(): Promise<this> {
-    const list = this.getListPrompts()
-
-    for (const item of list) {
-      await this.toAiPromptItem(item)
-    }
-
-    return this
-  }
-
-  /**
-   * Generates project rules and prompt triggers description using AI.
-   *
-   * Генерирует описание правил проекта и триггеров промптов с помощью ИИ.
-   * @returns prompt rules description / описание правил промптов
-   */
-  async toAiPrompts(): Promise<string> {
-    const prompts = await this.init()
-
-    if (prompts.length > 0) {
-      return '## Mandatory Rules\n'
-        + 'You MUST evaluate whether your task relates to any of the following topics (even if not working directly with this package). If related material is present, you are strictly obligated to read and study the corresponding file before proceeding:\n'
-        + `${prompts.join('\n')}`
-    }
-
-    return ''
-  }
-
-  /**
-   * Gets the cache directory path for individual prompt JSON files.
-   *
-   * Получает путь к директории кэша для отдельных JSON файлов промптов.
-   * @returns cache directory path / путь к директории кэша
-   */
-  protected getCacheDir(): string {
-    return PropertiesFile.joinPath([UI_DIR_AI_TYPES_LIST, UI_DIR_RESOURCES])
-  }
-
-  /**
-   * Gets the cache JSON file path for a specific prompt file path.
-   *
-   * Получает путь к JSON файлу кэша для конкретного пути к файлу промпта.
-   * @param path relative file path of the prompt / относительный путь к файлу промпта
-   * @returns cache JSON file path / путь к JSON файлу кэша
-   */
-  protected getCachePath(path: string): string {
-    const relativePath = path
-      .replace(new RegExp(`^${this.promptsDir}/`), '')
-      .replace(/\.[^/.]+$/, '.json')
-
-    return PropertiesFile.joinPath([
-      this.getCacheDir(),
-      relativePath
-    ])
-  }
-
-  /**
-   * Generates MD5 hash for the given content.
-   *
-   * Генерирует MD5 хэш для переданного содержимого.
-   * @param content file or text content / содержимое файла или текста
-   * @returns MD5 hash string / MD5 хэш строка
-   */
-  protected getMd5(content: string): string {
-    return createHash('md5').update(content.trim()).digest('hex')
-  }
-
-  /**
-   * Formats a prompt rule entry line for a file and description.
-   *
-   * Форматирует строку элемента правила промпта для файла и описания.
-   * @param path relative file path / относительный путь к файлу
-   * @param description rule description / описание правила
-   * @returns formatted prompt rule line / отформатированная строка правила промпта
-   */
-  protected getPromptLine(
-    path: string,
-    description: string
-  ): string {
-    return `- '${UI_MODULES}/${this.ai.getProjectName()}/${path}': ${description}`
-  }
-
-  /**
-   * Saves an individual prompt cache item to its JSON cache file.
-   *
-   * Сохраняет отдельный элемент кэша промпта в его JSON файл кэша.
-   * @param item prompt cache item to save / элемент кэша промпта для сохранения
-   */
-  protected saveCacheItem(item: DesignTypesPromptCacheItem): void {
-    PropertiesFile.writeByPath(
-      this.getCachePath(item.path),
-      item
-    )
-  }
-
-  /**
-   * Saves the prompt cache list to individual JSON cache files.
-   *
-   * Сохраняет список кэша промптов в отдельные JSON файлы кэша.
-   * @param cache cache list to save / список кэша для сохранения
-   */
-  protected saveCacheList(cache: DesignTypesPromptCacheList): void {
-    this.cacheList = cache
-
-    for (const item of cache) {
-      this.saveCacheItem(item)
-    }
-  }
-
-  /**
-   * Generates document metadata (title and description) for studying a prompt file using AI.
-   *
-   * Генерирует метаданные документа (название и описание) для изучения файла промпта с помощью ИИ.
-   * @param content prompt file content / содержимое файла промпта
-   * @returns object with document title and description or undefined / объект с названием и описанием документа или undefined
-   */
-  protected async toAiPromptData(content: string): Promise<DesignTypesPromptData | undefined> {
-    return this.ai.toAiJson<DesignTypesPromptData>(
-      content,
-      'Goal: Generate a document metadata object in valid JSON format for an AI coding assistant.\n\n'
-      + 'CRITICAL RESTRICTIONS:\n'
-      + '- The output MUST be a valid JSON object with keys: "name" and "description".\n'
-      + '- Field "name": Short and concise document title (maximum 4-5 words).\n'
-      + '- Field "description": Clear description for an AI agent explaining what exact standards, rules, or tools this file contains and what commercial or technical task it solves (maximum 3 sentences).\n'
-      + '- Do NOT include markdown code block wrappers (```json). Return ONLY the raw JSON string.\n\n'
-      + 'EXAMPLES OF GOOD OUTPUT:\n'
-      + '{\n'
-      + '  "name": "Coding Standards",\n'
-      + '  "description": "Строгие архитектурные конвенции и стандарты написания кода для продукта"\n'
-      + '}\n\n'
-      + 'OUTPUT REQUIREMENTS:\n'
-      + 'Return ONLY the JSON object. No explanations, no markdown formatting, no conversational text.'
-    )
-  }
-
-  /**
-   * Processes a single prompt file item using cache or AI into a formatted rule entry string and updates individual cache file if changed.
-   *
-   * Обрабатывает один элемент файла промпта с использованием кэша или ИИ в отформатированную строку правила и обновляет отдельный файл кэша при изменениях.
-   * @param item prompt file item / элемент файла промпта
-   * @returns object with formatted rule string and changed flag / объект с отформатированной строкой правила и флагом изменений
-   */
-  protected async toAiPromptItem(
-    item: DesignTypesItem
-  ): Promise<DesignTypesPromptResult> {
-    const md5 = item.md5 ?? this.getMd5(item.content)
-    const cache = this.getCacheList()
-    const cacheIndex = cache.findIndex(itemCache => itemCache.path === item.path)
-    const cachedItem = cacheIndex >= 0 ? cache[cacheIndex] : undefined
-
-    if (
-      cachedItem
-      && cachedItem.md5 === md5
-      && isFilled(cachedItem.name)
-      && isFilled(cachedItem.description)
-    ) {
-      return {
-        prompt: this.getPromptLine(item.path, cachedItem.description),
-        isChanged: false
-      }
-    }
-
-    console.log(`-- processing prompt metadata for ${item.path}...`)
-
-    const data = await this.toAiPromptData(item.content)
-
-    if (
-      data
-      && isFilled(data.name)
-      && isFilled(data.description)
-    ) {
-      const newItem: DesignTypesPromptCacheItem = {
-        path: item.path,
-        md5,
-        name: data.name,
-        description: data.description
-      }
-
-      if (cacheIndex >= 0) {
-        cache[cacheIndex] = newItem
-      } else {
-        cache.push(newItem)
-      }
-
-      this.saveCacheItem(newItem)
-
-      return {
-        prompt: this.getPromptLine(item.path, data.description),
-        isChanged: true
-      }
-    }
-
-    return { isChanged: false }
-  }
-}

package/src/classes/Design/DesignTypescript.ts

@@ -1,244 +0,0 @@
-import { forEach } from '@dxtmisha/functional-basic'
-import ts from 'typescript'
-
-import type {
-  DesignTypescriptItem,
-  DesignTypescriptList,
-  DesignTypescriptProp,
-  DesignTypescriptProps
-} from '../../types/designTypes'
-
-/**
- * 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 Compiler API для анализа и извлечения метаданных типов из исходных файлов.
- * Анализирует интерфейсы и псевдонимы типов для получения сведений о свойствах, включая типы, литеральные объединения и комментарии к документации.
- */
-export class DesignTypescript {
-  protected readonly program: ts.Program
-  protected readonly checker: ts.TypeChecker
-  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 = {}
-  ) {
-    this.program = ts.createProgram([path], options)
-    this.checker = this.program.getTypeChecker()
-    this.sourceFile = this.program.getSourceFiles().find(source => source.fileName.endsWith(path))
-  }
-
-  /**
-   * Returns the TypeScript types from the source file
-   *
-   * Возвращает типы TypeScript из исходного файла
-   */
-  getTypes(): DesignTypescriptList {
-    if (!this.types && this.sourceFile) {
-      const data: DesignTypescriptList = []
-
-      ts.forEachChild(
-        this.sourceFile,
-        (node) => {
-          if (
-            ts.isTypeAliasDeclaration(node)
-            || ts.isInterfaceDeclaration(node)
-          ) {
-            const type = this.checker.getTypeAtLocation(node.name)
-            const props: DesignTypescriptProps = []
-
-            this.checker
-              .getPropertiesOfType(type)
-              .forEach((prop) => {
-                props.push(this.getPropInformation(node, prop))
-              })
-
-            data.push({
-              name: node.name.text,
-              props
-            })
-          }
-        })
-
-      this.types = data
-      return data
-    }
-
-    return []
-  }
-
-  /**
-   * Returns the TypeScript type by name
-   *
-   * Возвращает тип TypeScript по имени
-   * @param name Name of the type/ имя типа
-   */
-  getType(name: string): DesignTypescriptItem | undefined {
-    return this.getTypes().find(type => type.name === name)
-  }
-
-  /**
-   * Returns the type of the property
-   *
-   * Возвращает тип свойства
-   * @param type TypeScript type/ тип TypeScript
-   * @param prop Symbol of the property/ символ свойства
-   */
-  protected getPropType(
-    type: ts.Type,
-    prop?: ts.Symbol
-  ): string {
-    const option = this.getPropOption(type)
-
-    if (
-      type.isUnion()
-      && option
-      && option.length > 0
-    ) {
-      if (
-        type.types.every(
-          type => type.isNumberLiteral()
-        )
-      ) {
-        return 'number'
-      }
-
-      return 'string'
-    }
-
-    let text = this.checker.typeToString(type)
-
-    if (
-      prop
-      && (
-        text === 'any'
-        || text === '{}'
-        || text === 'unknown'
-      )
-    ) {
-      const decl = prop.getDeclarations()?.find(d =>
-        ts.isPropertySignature(d) || ts.isPropertyDeclaration(d)
-      )
-
-      if (decl?.type) {
-        text = decl.type.getText().trim() || text
-      }
-    }
-
-    return text.replace(/'/g, '\\\'')
-  }
-
-  /**
-   * Returns the option of the property
-   *
-   * Возвращает опцию свойства
-   * @param type TypeScript type/ тип TypeScript
-   */
-  protected getPropOption(type: ts.Type): DesignTypescriptProp['option'] {
-    if (type.isUnion()) {
-      const option = forEach(
-        type.types,
-        (item) => {
-          if (
-            item.isStringLiteral()
-            || item.isNumberLiteral()
-          ) {
-            return String(item.value)
-          }
-        }
-      ) as string[]
-
-      if (option.length > 0) {
-        return option
-      }
-    }
-
-    return undefined
-  }
-
-  /**
-   * Extracts literal options from a property TypeNode union
-   *
-   * Извлекает литеральные опции из узла типа свойства (union)
-   * @param type Property type AST node/ узел AST типа свойства
-   * @returns Array of literal values or undefined/ Массив литеральных значений или undefined
-   */
-  protected getPropOptionByNode(type: ts.TypeNode): DesignTypescriptProp['option'] {
-    if (ts.isUnionTypeNode(type)) {
-      const list: string[] = []
-
-      for (const item of type.types) {
-        if (
-          ts.isLiteralTypeNode(item)
-          && ts.isStringLiteral(item.literal)
-        ) {
-          list.push(item.literal.text)
-        }
-      }
-
-      return list
-    }
-
-    return undefined
-  }
-
-  /**
-   * Extracts literal options from property declarations by reading their type nodes
-   *
-   * Извлекает литеральные опции из деклараций свойства, анализируя их узлы типа
-   * @param declarations Symbol declarations/ декларации символа
-   * @returns Array of literal values or empty array/ Массив литеральных значений или пустой массив
-   */
-  protected getPropOptionByDeclarations(declarations?: ts.Declaration[]): DesignTypescriptProp['option'] {
-    if (declarations) {
-      for (const declaration of declarations) {
-        if (
-          (
-            ts.isPropertySignature(declaration)
-            || ts.isPropertyDeclaration(declaration)
-          )
-          && declaration.type
-        ) {
-          const types = this.getPropOptionByNode(declaration.type)
-          if (types && types.length > 0) {
-            return types
-          }
-        }
-      }
-    }
-
-    return []
-  }
-
-  /**
-   * Returns information about the property
-   *
-   * Возвращает информацию о свойстве
-   * @param node Type alias or interface declaration/ объявление псевдонима типа или интерфейса
-   * @param prop Symbol of the property/ символ свойства
-   */
-  protected getPropInformation(
-    node: ts.TypeAliasDeclaration | ts.InterfaceDeclaration,
-    prop: ts.Symbol
-  ): DesignTypescriptProp {
-    const type = this.checker.getTypeOfSymbolAtLocation(prop, node.name)
-    const descriptionRaw = ts.displayPartsToString(prop.getDocumentationComment(this.checker)).trim()
-    const description = descriptionRaw.length > 0 ? descriptionRaw : undefined
-
-    return {
-      name: prop.name,
-      type: this.getPropType(type, prop),
-      option: this.getPropOption(type) ?? this.getPropOptionByDeclarations(prop.getDeclarations()),
-      description
-    }
-  }
-}