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

<Meta title='@dxtmisha/ru/scripts/bin/dxt-ai-doc - Генератор AI-документации'/>

# dxt-ai-doc

Скрипт `ai-doc.ts` представляет собой автоматизированный генератор документации проекта на базе ИИ. Он использует `vite-node` для запуска процесса, который анализирует исходный код TypeScript (классы, композитные функции и обычные функции), связывается с моделью ИИ для получения описания кода и создаёт или обновляет файлы документации в формате MDX.

## Ключевые возможности

- **Контекстные промпты**: Генерирует документацию с использованием различных шаблонов промптов в зависимости от типа файла (Class, Composable или стандартная функция).
- **Многоязычная поддержка**: Автоматически подставляет целевой язык документации (`[wikiLanguage]`) в промпт для ИИ.
- **Компиляция в реальном времени**: Перед отправкой контекста ИИ скрипт создаёт сборку, чтобы получить точный контекст поведения TypeScript.

## Как это работает?

Скрипт координирует ряд ключевых процессов для автоматизации создания документации:

1. Скрипт считывает список файлов из директорий, указанных в ваших конфигурационных файлах свойств проекта.
2. Он определяет тип кода (класс, композитная функция, обычная функция) и подготавливает специфичный для него контекст.
3. Выполняется компиляция кода в реальном времени для получения точной информации о типах TypeScript.
4. Собранный контекст вместе с шаблонами промптов отправляется в модель ИИ.
5. ИИ формирует ответ, скрипт анализирует его и напрямую создаёт или обновляет `MDX` файлы в репозитории.

## Настройка и запуск

Конфигурация генератора ИИ определяется централизованно в файле `design.config.json` вашего проекта. **Создайте этот файл в корне вашего проекта.** Выполните эти точные шаги для настройки:

1. **Настройте параметры ИИ в `design.config.json`**:
   Добавьте ключ API, целевую модель и язык напрямую в конфигурационный объект.
   ```json
   {
     "wikiLanguage": "ru",
     "aiType": "gemini",
     "aiModel": "gemini-2.0-flash",
     "aiKey": "ВАШ_API_КЛЮЧ"
   }
   ```
2. **Настройте целевые директории**:
   В том же `design.config.json` укажите, какие директории следует сканировать, переопределив пути по умолчанию `aiDocDirectory`. (По умолчанию это `/classes/`, `/composables/` и `/functions/`).
   ```json
   {
     "aiDocDirectory": [
       "/path/to/my/classes/",
       "/path/to/my/composables/"
     ]
   }
   ```
3. **Запустите команду**:
   Скрипт зарегистрирован в `package.json` как часть `@dxtmisha/scripts`. Просто выполните команду `dxt-ai-doc` через `npx` или `npm`:
   ```bash
   npx dxt-ai-doc
   ```
   Скрипту не нужны никакие аргументы — он автоматически прочитает настройки из `design.config.json` и обновит нужные файлы документации.

## Дополнительная информация

### Зависимость от сборки проекта

Генератор сильно зависит от процесса сборки проекта. **Он выполняет команду `npm run build`** во временной директории сборки (`dist-temporary`), чтобы точно получить ваши определения TypeScript, экспорты и структуру компонентов. **Если в вашем проекте есть ошибки TypeScript или сборки, скрипт генерации документации завершится сбоем.**

### Исключение файлов (Директива пропуска)

Вы можете исключить конкретные файлы из обработки `dxt-ai-doc`, добавив комментарий `// wiki:build-none` в любом месте файла.

