import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/scripts/Classes/DesignTypescript - Анализатор метаданных типов'/>

# Класс DesignTypescript

Класс `DesignTypescript` предоставляет высокоуровневую обертку вокруг TypeScript Compiler API, позволяя программно анализировать метаданные исходного кода. Он специализируется на извлечении структурированной информации из интерфейсов и псевдонимов типов, что делает его важным инструментом для генерации документации, схем валидации или оптимизированных определений типов для ИИ-помощников.

## Ключевые особенности

- **Интеграция с Compiler API** — бесшовное взаимодействие с внутренней программой и средством проверки типов TypeScript.
- **Глубокое извлечение типов** — разрешает сложные типы свойств, литеральные объединения и опциональность.
- **Получение документации** — автоматически извлекает комментарии JSDoc для сохранения контекста, написанного разработчиком.
- **AST-парсинг** — перемещается по абстрактному синтаксическому дереву (AST) для надежной идентификации интерфейсов и объявлений типов.
- **Обнаружение литеральных значений** — интеллектуально расширяет литеральные объединения в используемые строковые или числовые опции.

## Инициализация

Инициализируйте анализатор, указав путь к исходному файлу TypeScript. Вы также можете указать пользовательские опции компилятора в соответствии с окружением вашего проекта.

**Параметры:**
- `path: string` — абсолютный или относительный путь к файлу `.ts` (по умолчанию `''`).
- `options: ts.CompilerOptions` — необязательная конфигурация компилятора TypeScript (по умолчанию `{}`).

```typescript
import { DesignTypescript } from '@dxtmisha/scripts'

const analyzer = new DesignTypescript('src/types/component.ts')
const types = analyzer.getTypes()
```

## Методы

### Получение данных

- `getTypes(): DesignTypescriptList` — сканирует исходный файл и возвращает массив метаданных всех обнаруженных типов и интерфейсов.
- `getType(name: string): DesignTypescriptItem | undefined` — получает метаданные для конкретного типа или интерфейса по его имени.

## Операции

### Рабочий процесс анализа метаданных

При анализе файла `DesignTypescript` выполняет следующие шаги:
1. **Создание программы**: инициализирует программу TypeScript и Type Checker для указанного файла.
2. **Обход узлов**: посещает каждый узел в AST, специально разыскивая узлы `TypeAliasDeclaration` и `InterfaceDeclaration`.
3. **Разрешение свойств**: для каждого идентифицированного типа опрашивает Type Checker для получения его свойств (включая наследуемые).
4. **Синтез информации**: для каждого свойства строит объект метаданных, содержащий:
    - **Name**: идентификатор свойства.
    - **Type**: чистое строковое представление типа (например, `'string | number'`).
    - **Options**: если свойство является литеральным объединением, извлекает фактические значения.
    - **Description**: связанный комментарий JSDoc.

### Роль в инструментарии

Этот класс часто используется другими генераторами (такими как `DesignTypes` или `DesignCommand`) для преодоления разрыва между статическим кодом и динамической логикой. Предоставляя чистый API к сложному компилятору TypeScript, он позволяет дизайн-системе оставаться «знающей типы» во всех её автоматизированных процессах.
