@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/scripts/classes/DesignWikiStorm/DesignWikiStorm.en.mdx

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignWikiStorm - IDE Metadata Generator'/>
+
+# DesignWikiStorm Class
+
+The `DesignWikiStorm` class is a specialized utility designed to bridge the gap between the design system's code and developer productivity tools. It automates the generation of `web-types.json`, a standardized metadata format used by JetBrains IDEs (WebStorm, IntelliJ IDEA) to provide advanced IntelliSense, auto-completion, and documentation tooltips for Vue components.
+
+## Key Features
+
+- **Web-Types Standard Compliance** — Generates metadata strictly adhering to the official Web-Types JSON schema.
+- **IntelliSense Optimization** — Transforms component properties, events, and slots into IDE-friendly definitions.
+- **Automated Directory Discovery** — Recursively scans the library to identify all components and their respective metadata.
+- **Dynamic Versioning** — Automatically synchronizes the generated metadata version with the current `package.json` version.
+- **Framework Integration** — Specifically configured for Vue.js, ensuring that component tags and attributes are correctly recognized in `.vue` files.
+
+## Initialization
+
+Initialize the generator by specifying the target directory where the `web-types.json` file should be stored.
+
+**Parameters:**
+- `dir: string` — The path to the output directory (default is `'dist'`).
+
+```typescript
+import { DesignWikiStorm } from '@dxtmisha/scripts'
+
+const generator = new DesignWikiStorm('dist')
+await generator.make()
+```
+
+## Methods
+
+### Control
+
+- `make(): Promise<void>` — Triggers the main generation process.
+
+## Operations
+
+### The Web-Types Generation Workflow
+
+When `make()` is called, the class coordinates a multi-stage data synthesis:
+1. **Context Acquisition**: It loads the `package.json` to retrieve the library name and current version.
+2. **Schema Bootstrapping**: It initializes an object based on the Web-Types schema, setting the framework to Vue and defining the documentation markup as Markdown.
+3. **Component Iteration**: It iterates through every component registered in `LibraryItems`.
+4. **Member Analysis**: For each component, it instantiates `DesignWikiStormItem`, which performs deep analysis of the component's source files to extract:
+    - **Tags**: Component names (e.g., `d1-button`).
+    - **Attributes**: Property names, types, and default values.
+    - **Events**: Emitted event names and their payloads.
+    - **Slots**: Available customization points and their scoped variables.
+5. **Persistence**: The final consolidated metadata object is written to `web-types.json` in the specified directory.
+
+### Impact on Developer Experience
+
+By generating `web-types.json`, the design system ensures that developers using JetBrains tools receive the same level of support as they would with native HTML elements. Property types are validated in real-time within the IDE, and documentation comments are displayed directly in the code editor, significantly reducing the need to consult external wiki pages.

package/src/media/functional/scripts/classes/DesignWikiStorm/DesignWikiStorm.ru.mdx

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignWikiStorm - Генератор метаданных для IDE'/>
+
+# Класс DesignWikiStorm
+
+Класс `DesignWikiStorm` — это специализированная утилита, предназначенная для сокращения разрыва между кодом дизайн-системы и инструментами продуктивности разработчиков. Он автоматизирует генерацию `web-types.json` — стандартизированного формата метаданных, используемого IDE от JetBrains (WebStorm, IntelliJ IDEA) для обеспечения продвинутого IntelliSense, автодополнения и подсказок по документации для компонентов Vue.
+
+## Ключевые особенности
+
+- **Соответствие стандарту Web-Types** — генерирует метаданные, строго соответствующие официальной JSON-схеме Web-Types.
+- **Оптимизация IntelliSense** — преобразует свойства компонентов, события и слоты в определения, удобные для IDE.
+- **Автоматическое обнаружение директорий** — рекурсивно сканирует библиотеку для идентификации всех компонентов и их соответствующих метаданных.
+- **Динамическое управление версиями** — автоматически синхронизирует версию сгенерированных метаданных с текущей версией в `package.json`.
+- **Интеграция с фреймворком** — специально настроен для Vue.js, что гарантирует правильное распознавание тегов и атрибутов компонентов в `.vue` файлах.
+
+## Инициализация
+
+Инициализируйте генератор, указав целевую директорию, в которой должен быть сохранен файл `web-types.json`.
+
+**Параметры:**
+- `dir: string` — путь к выходной директории (по умолчанию `'dist'`).
+
+```typescript
+import { DesignWikiStorm } from '@dxtmisha/scripts'
+
+const generator = new DesignWikiStorm('dist')
+await generator.make()
+```
+
+## Методы
+
+### Управление
+
+- `make(): Promise<void>` — запускает основной процесс генерации.
+
+## Операции
+
+### Рабочий процесс генерации Web-Types
+
+При вызове `make()` класс координирует многоэтапный синтез данных:
+1. **Получение контекста**: загружает `package.json` для получения имени библиотеки и текущей версии.
+2. **Инициализация схемы**: создает объект на основе схемы Web-Types, устанавливая фреймворк Vue и определяя разметку документации как Markdown.
+3. **Итерация компонентов**: обходит каждый компонент, зарегистрированный в `LibraryItems`.
+4. **Анализ элементов**: для каждого компонента создает экземпляр `DesignWikiStormItem`, который выполняет глубокий анализ исходных файлов компонента для извлечения:
+    - **Tags**: имена компонентов (например, `d1-button`).
+    - **Attributes**: имена свойств, типы и значения по умолчанию.
+    - **Events**: имена генерируемых событий и их полезная нагрузка.
+    - **Slots**: доступные точки настройки и их переменные области видимости.
+5. **Сохранение**: финальный консолидированный объект метаданных записывается в `web-types.json` в указанной директории.
+
+### Влияние на опыт разработчика
+
+Благодаря генерации `web-types.json`, дизайн-система гарантирует, что разработчики, использующие инструменты JetBrains, получают тот же уровень поддержки, что и при работе с нативными HTML-элементами. Типы свойств проверяются в реальном времени внутри IDE, а комментарии к документации отображаются прямо в редакторе кода, что значительно снижает необходимость обращения к внешним страницам вики.

package/src/media/functional/scripts/classes/DesignWikiStorm/DesignWikiStorm.vi.mdx

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignWikiStorm - Trình tạo siêu dữ liệu cho IDE'/>
+
+# Lớp DesignWikiStorm
+
+Lớp `DesignWikiStorm` là một tiện ích chuyên dụng được thiết kế để thu hẹp khoảng cách giữa mã nguồn của hệ thống thiết kế và các công cụ hỗ trợ năng suất cho nhà phát triển. Nó tự động hóa việc tạo `web-types.json`, một định dạng siêu dữ liệu chuẩn hóa được sử dụng bởi các IDE của JetBrains (WebStorm, IntelliJ IDEA) để cung cấp IntelliSense nâng cao, tự động hoàn thành và các mô tả tài liệu (tooltips) cho các thành phần Vue.
+
+## Các tính năng chính
+
+- **Tuân thủ tiêu chuẩn Web-Types** — Tạo siêu dữ liệu tuân thủ nghiêm ngặt giản đồ (schema) JSON chính thức của Web-Types.
+- **Tối ưu hóa IntelliSense** — Chuyển đổi các thuộc tính, sự kiện và slot của thành phần thành các định nghĩa thân thiện với IDE.
+- **Khám phá thư mục tự động** — Quét đệ quy thư viện để xác định tất cả các thành phần và siêu dữ liệu tương ứng của chúng.
+- **Tự động cập nhật phiên bản** — Tự động đồng bộ hóa phiên bản siêu dữ liệu được tạo ra với phiên bản hiện tại trong `package.json`.
+- **Tích hợp Framework** — Được cấu hình đặc biệt cho Vue.js, đảm bảo rằng các thẻ và thuộc tính thành phần được nhận diện chính xác trong các tệp `.vue`.
+
+## Khởi tạo
+
+Khởi tạo trình tạo bằng cách chỉ định thư mục đích nơi tệp `web-types.json` sẽ được lưu trữ.
+
+**Tham số:**
+- `dir: string` — Đường dẫn đến thư mục đầu ra (mặc định là `'dist'`).
+
+```typescript
+import { DesignWikiStorm } from '@dxtmisha/scripts'
+
+const generator = new DesignWikiStorm('dist')
+await generator.make()
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `make(): Promise<void>` — Kích hoạt quy trình tạo chính.
+
+## Các thao tác (Operations)
+
+### Quy trình tạo Web-Types (Web-Types Generation Workflow)
+
+Khi `make()` được gọi, lớp sẽ điều phối một quy trình tổng hợp dữ liệu đa giai đoạn:
+1. **Thu thập ngữ cảnh**: Nó tải `package.json` để lấy tên thư viện và phiên bản hiện tại.
+2. **Khởi tạo Giản đồ**: Nó khởi tạo một đối tượng dựa trên giản đồ Web-Types, đặt framework thành Vue và xác định định dạng tài liệu là Markdown.
+3. **Duyệt qua các thành phần**: Nó duyệt qua mọi thành phần được đăng ký trong `LibraryItems`.
+4. **Phân tích chi tiết**: Đối với mỗi thành phần, nó khởi tạo `DesignWikiStormItem`, thực hiện phân tích sâu các tệp mã nguồn của thành phần để trích xuất:
+    - **Tags**: Tên thành phần (ví dụ: `d1-button`).
+    - **Attributes**: Tên thuộc tính, kiểu dữ liệu và giá trị mặc định.
+    - **Events**: Tên các sự kiện được phát ra và dữ liệu kèm theo (payload).
+    - **Slots**: Các điểm tùy chỉnh có sẵn và các biến phạm vi (scoped variables) của chúng.
+5. **Lưu trữ**: Đối tượng siêu dữ liệu hợp nhất cuối cùng được ghi vào tệp `web-types.json` trong thư mục đã chỉ định.
+
+### Tác động đến trải nghiệm nhà phát triển
+
+Bằng cách tạo `web-types.json`, hệ thống thiết kế đảm bảo rằng các nhà phát triển sử dụng công cụ của JetBrains nhận được mức độ hỗ trợ tương đương với khi làm việc với các phần tử HTML gốc. Các kiểu thuộc tính được xác thực theo thời gian thực ngay trong IDE và các chú thích tài liệu được hiển thị trực tiếp trong trình soạn thảo mã, giảm đáng kể nhu cầu tham khảo các trang wiki bên ngoài.

package/src/media/functional/scripts/classes/DesignWikiStormItem/DesignWikiStormItem.en.mdx

@@ -0,0 +1,62 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignWikiStormItem - Component IDE Metadata Resolver'/>
+
+# DesignWikiStormItem Class
+
+The `DesignWikiStormItem` class is a granular resolver responsible for extracting, analyzing, and formatting metadata for a single UI component. It acts as the bridge between internal Storybook-oriented documentation and the `web-types.json` format, ensuring that every property and description is correctly mapped for IDE IntelliSense.
+
+## Key Features
+
+- **Storeybook-to-WebTypes Mapping** — Automatically converts `WikiStorybook` objects into JetBrains-compatible tag definitions.
+- **Dynamic Module Resolution** — Calculates the correct module paths for components to support "Jump to Definition" in IDEs.
+- **Context-Aware Documentation** — Preserves and formats component descriptions, property types, and default values.
+- **AST-Like Data Retrieval** — Programmatically imports and parses `wikiData.ts` files to retrieve live component metadata.
+- **Attribute Synthesis** — Iteratively builds attribute lists by resolving complex types into human-readable IDE strings.
+
+## Initialization
+
+Initialize the resolver by providing the project context, the structural path, and the component's library metadata.
+
+**Parameters:**
+- `project: string` — The name of the project (e.g., `'@dxtmisha/ui'`).
+- `path: string[]` — Segments of the file system path leading to the component folder.
+- `data: LibraryData` — Core metadata of the component (name, alias, directory).
+
+```typescript
+import { DesignWikiStormItem } from '@dxtmisha/scripts'
+
+const resolver = new DesignWikiStormItem(
+  '@dxtmisha/ui',
+  ['packages', 'core', 'src', 'components'],
+  componentData
+)
+await resolver.init()
+const tagMetadata = resolver.get()
+```
+
+## Methods
+
+### Information Acquisition
+
+- `get(): WebTypesTagItem | undefined` — Returns the consolidated tag definition containing the name, description, source, and attributes.
+- `getAttribute(item: WikiStorybookProp): WebTypesAttributeItem` — Transforms a single Storybook property into a Web-Types attribute definition.
+- `getAttributes(): WebTypesAttributes` — Compiles the full list of attributes for the component.
+
+### Control
+
+- `init(): Promise<this>` — Asynchronously initializes the internal `WikiStorybook` instance by loading the component's documentation data.
+
+## Operations
+
+### The Metadata Extraction Flow
+
+When the resolver is initialized and queried, it follows a structured data pipeline:
+1. **Wiki Data Loading (`initWiki`)**: It resolves the file path to the component's `wikiData.ts` and performs a dynamic import to fetch live metadata (props, defaults, design tokens).
+2. **Tag Synthesis (`get`)**: It constructs the IDE tag name by combining the design system alias with the internal component name.
+3. **Source Mapping**: It defines the `module` and `symbol` properties, allowing IDEs to link the metadata back to the actual source code.
+4. **Attribute Compilation (`getAttributes`)**: It traverses every property defined in the wiki, resolving its documentation comment, TypeScript type, and default value into a standardized JSON structure.
+
+### Role in the IDE Engine
+
+`DesignWikiStormItem` is the "workhorse" of the metadata generation suite. While `DesignWikiStorm` manages the overall file structure, this class handles the complexity of individual component analysis, ensuring that specialized UI logic is accurately represented in a format that development tools can understand.

package/src/media/functional/scripts/classes/DesignWikiStormItem/DesignWikiStormItem.ru.mdx

@@ -0,0 +1,62 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignWikiStormItem - Резолвер метаданных IDE компонента'/>
+
+# Класс DesignWikiStormItem
+
+Класс `DesignWikiStormItem` — это гранулярный резолвер, отвечающий за извлечение, анализ и форматирование метаданных для отдельного UI-компонента. Он выступает в качестве моста между внутренней документацией, ориентированной на Storybook, и форматом `web-types.json`, гарантируя, что каждое свойство и описание правильно сопоставлены для IntelliSense в IDE.
+
+## Ключевые особенности
+
+- **Маппинг Storybook в WebTypes** — автоматически конвертирует объекты `WikiStorybook` в определения тегов, совместимые с разработками JetBrains.
+- **Динамическое разрешение модулей** — вычисляет правильные пути к модулям компонентов для поддержки функции «Перейти к определению» в IDE.
+- **Контекстная документация** — сохраняет и форматирует описания компонентов, типы свойств и значения по умолчанию.
+- **Программное извлечение данных** — импортирует и анализирует файлы `wikiData.ts` для получения актуальных метаданных компонентов.
+- **Синтез атрибутов** — итеративно выстраивает списки атрибутов, преобразуя сложные типы в понятные для IDE строки.
+
+## Инициализация
+
+Инициализируйте резолвер, указав контекст проекта, структурный путь и библиотечные метаданные компонента.
+
+**Параметры:**
+- `project: string` — имя проекта (например, `'@dxtmisha/ui'`).
+- `path: string[]` — сегменты пути в файловой системе к папке компонента.
+- `data: LibraryData` — основные метаданные компонента (имя, алиас, директория).
+
+```typescript
+import { DesignWikiStormItem } from '@dxtmisha/scripts'
+
+const resolver = new DesignWikiStormItem(
+  '@dxtmisha/ui',
+  ['packages', 'core', 'src', 'components'],
+  componentData
+)
+await resolver.init()
+const tagMetadata = resolver.get()
+```
+
+## Методы
+
+### Получение информации
+
+- `get(): WebTypesTagItem | undefined` — возвращает консолидированное определение тега, содержащее имя, описание, источник и атрибуты.
+- `getAttribute(item: WikiStorybookProp): WebTypesAttributeItem` — преобразует отдельное свойство Storybook в определение атрибута Web-Types.
+- `getAttributes(): WebTypesAttributes` — компилирует полный список атрибутов для компонента.
+
+### Управление
+
+- `init(): Promise<this>` — асинхронно инициализирует внутренний экземпляр `WikiStorybook`, загружая данные документации компонента.
+
+## Операции
+
+### Рабочий процесс извлечения метаданных
+
+При инициализации и запросе резолвер следует структурированному конвейеру данных:
+1. **Загрузка данных вики (`initWiki`)**: разрешает путь к файлу компонента `wikiData.ts` и выполняет динамический импорт для получения актуальных метаданных (пропсы, значения по умолчанию, токены дизайна).
+2. **Синтез тега (`get`)**: конструирует имя тега для IDE, объединяя алиас дизайн-системы с внутренним именем компонента.
+3. **Маппинг источника**: определяет свойства `module` и `symbol`, позволяя IDE связывать метаданные с реальным исходным кодом.
+4. **Компиляция атрибутов (`getAttributes`)**: обходит каждое свойство, определенное в вики, преобразуя его комментарий JSDoc, тип TypeScript и значение по умолчанию в стандартизированную структуру JSON.
+
+### Роль в движке IDE
+
+`DesignWikiStormItem` — это «рабочая лошадка» всей системы генерации метаданных. В то время как `DesignWikiStorm` берет на себя общую структуру файла, этот класс управляет сложностью анализа каждого отдельного компонента, гарантируя, что специфичная логика UI точно представлена в формате, понятном инструментам разработки.

package/src/media/functional/scripts/classes/DesignWikiStormItem/DesignWikiStormItem.vi.mdx

@@ -0,0 +1,62 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignWikiStormItem - Bộ phân giải siêu dữ liệu IDE cho thành phần'/>
+
+# Lớp DesignWikiStormItem
+
+Lớp `DesignWikiStormItem` là một bộ phân giải chi tiết (granular resolver) chịu trách nhiệm trích xuất, phân tích và định dạng siêu dữ liệu cho một thành phần UI duy nhất. Nó đóng vai trò là cầu nối giữa tài liệu nội bộ hướng đến Storybook và định dạng `web-types.json`, đảm bảo rằng mọi thuộc tính và mô tả đều được ánh xạ chính xác cho IntelliSense trong IDE.
+
+## Các tính năng chính
+
+- **Ánh xạ Storybook sang WebTypes** — Tự động chuyển đổi các đối tượng `WikiStorybook` thành các định nghĩa thẻ (tags) tương thích với JetBrains.
+- **Phân giải Module động** — Tính toán chính xác các đường dẫn module cho các thành phần để hỗ trợ tính năng "Jump to Definition" trong các IDE.
+- **Tài liệu theo ngữ cảnh** — Bảo tồn và định dạng các mô tả thành phần, kiểu dữ liệu thuộc tính và các giá trị mặc định.
+- **Truy xuất dữ liệu theo chương trình** — Nhập (import) và phân tích các tệp `wikiData.ts` theo chương trình để lấy siêu dữ liệu thực tế của thành phần.
+- **Tổng hợp thuộc tính** — Xây dựng danh sách các thuộc tính bằng cách phân giải các kiểu dữ liệu phức tạp thành các chuỗi IDE dễ đọc cho con người.
+
+## Khởi tạo
+
+Khởi tạo bộ phân giải bằng cách cung cấp ngữ cảnh dự án, đường dẫn cấu trúc và siêu dữ liệu thư viện của thành phần.
+
+**Tham số:**
+- `project: string` — Tên của dự án (ví dụ: `'@dxtmisha/ui'`).
+- `path: string[]` — Các đoạn đường dẫn trong hệ thống tệp dẫn đến thư mục thành phần.
+- `data: LibraryData` — Siêu dữ liệu cốt lõi của thành phần (tên, bí danh, thư mục).
+
+```typescript
+import { DesignWikiStormItem } from '@dxtmisha/scripts'
+
+const resolver = new DesignWikiStormItem(
+  '@dxtmisha/ui',
+  ['packages', 'core', 'src', 'components'],
+  componentData
+)
+await resolver.init()
+const tagMetadata = resolver.get()
+```
+
+## Các phương thức
+
+### Thu thập thông tin
+
+- `get(): WebTypesTagItem | undefined` — Trả về định nghĩa thẻ đã hợp nhất chứa tên, mô tả, nguồn và các thuộc tính.
+- `getAttribute(item: WikiStorybookProp): WebTypesAttributeItem` — Chuyển đổi một thuộc tính Storybook duy nhất thành định nghĩa thuộc tính Web-Types.
+- `getAttributes(): WebTypesAttributes` — Biên soạn danh sách đầy đủ các thuộc tính cho thành phần.
+
+### Điều khiển
+
+- `init(): Promise<this>` — Khởi tạo bất đồng bộ instance `WikiStorybook` nội bộ bằng cách tải dữ liệu tài liệu của thành phần.
+
+## Các thao tác (Operations)
+
+### Quy trình trích xuất siêu dữ liệu
+
+Khi bộ phân giải được khởi tạo và truy vấn, nó tuân theo một quy trình dữ liệu có cấu trúc:
+1. **Tải dữ liệu Wiki (`initWiki`)**: Nó phân giải đường dẫn tệp đến `wikiData.ts` của thành phần và thực hiện import động để lấy siêu dữ liệu thực tế (props, defaults, design tokens).
+2. **Tổng hợp thẻ (`get`)**: Nó xây dựng tên thẻ IDE bằng cách kết hợp bí danh của hệ thống thiết kế với tên thành phần nội bộ.
+3. **Ánh xạ nguồn (Source Mapping)**: Nó xác định các thuộc tính `module` và `symbol`, cho phép các IDE liên kết siêu dữ liệu ngược lại mã nguồn thực tế.
+4. **Biên soạn thuộc tính (`getAttributes`)**: Nó duyệt qua mọi thuộc tính được định nghĩa trong wiki, phân giải chú thích tài liệu, kiểu dữ liệu TypeScript và giá trị mặc định của nó thành một cấu trúc JSON chuẩn hóa.
+
+### Vai trò trong Động cơ IDE
+
+`DesignWikiStormItem` là "ngựa thồ" (workhorse) của bộ công cụ tạo siêu dữ liệu. Trong khi `DesignWikiStorm` quản lý cấu trúc tệp tổng thể, lớp này xử lý sự phức tạp của việc phân tích từng thành phần riêng lẻ, đảm bảo rằng logic UI chuyên biệt được biểu diễn chính xác dưới định dạng mà các công cụ phát triển có thể hiểu được.

package/src/media/functional/scripts/classes/GitRead/GitRead.en.mdx

@@ -0,0 +1,285 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/GitRead - Git Repository Reader'/>
+
+# GitRead Class
+
+A powerful utility class for interacting with a Git repository. It provides high-level methods to retrieve file lists, commit dates, status information in porcelain format, and more.
+
+## Key Features
+
+- **File Discovery** — retrieves all tracked files in the current repository or filtered by specific directories.
+- **Status Reporting** — parses `git status --porcelain` to identify modified, added, or untracked files.
+- **Commit History** — extracts the last modification date for individual files.
+- **Path Management** — handles relative paths and directory prefixes within the repository structure.
+
+## Core Methods
+
+### `getList`
+
+Retrieves a simplified list of all tracked files in the current repository HEAD, including basic metadata like modified dates.
+
+**Parameters:**
+- `filter?: (file: string) => boolean` — A callback function to include only files that match specific criteria.
+
+**Returns:** `GitFileList` — An array of `GitFileItem` objects representing the tracked files.
+
+**Example:**
+```typescript
+const files = GitRead.getList((f) => f.endsWith('.ts'))
+/**
+ * [
+ *   {
+ *     path: 'src/index.ts',
+ *     pathByOS: ['src', 'index.ts'],
+ *     pathFull: 'packages/scripts/src/index.ts',
+ *     date: '2024-03-20 12:00:00',
+ *     status: undefined
+ *   },
+ *   ...
+ * ]
+ */
+```
+
+### `getListPorcelain`
+
+Retrieves the current status of files in the repository using the `--porcelain` format. This includes changes in the working tree and the index.
+
+**Parameters:**
+- `filter?: (file: string) => boolean` — A callback function to filter the resulting status list.
+
+**Returns:** `GitFileList` — An array of `GitFileItem` objects, each containing a `status` field.
+
+**Example:**
+```typescript
+const status = GitRead.getListPorcelain()
+/**
+ * [
+ *   {
+ *     path: 'src/classes/GitRead.ts',
+ *     pathByOS: ['src', 'classes', 'GitRead.ts'],
+ *     pathFull: 'packages/scripts/src/classes/GitRead.ts',
+ *     date: '2024-03-21 10:30:00',
+ *     status: 'M'
+ *   },
+ *   ...
+ * ]
+ */
+```
+
+### `getListUnique`
+
+Orchestrates a merge between the tracked files (`getList`) and the current status (`getListPorcelain`). It ensures each file is represented only once, prioritizing status information if available.
+
+**Parameters:**
+- `filter: (file: string) => boolean` — Required callback function to filter the unified list.
+
+**Returns:** `GitFileList` — A deduplicated list of files combining baseline and changed states.
+
+**Example:**
+```typescript
+const unique = GitRead.getListUnique((f) => f.includes('src/'))
+/**
+ * [
+ *   {
+ *     path: 'src/main.ts',
+ *     pathByOS: ['src', 'main.ts'],
+ *     pathFull: 'packages/scripts/src/main.ts',
+ *     date: '2024-03-19 15:45:00',
+ *     status: 'A'
+ *   }
+ * ]
+ */
+```
+
+### `getListByDirectory`
+
+A convenience method for retrieving unique file lists specifically from a given directory, filtered to include only `.ts` files and excluding `.test.ts` files.
+
+**Parameters:**
+- `directory: string | RegExp` — The target directory path or a pattern to match against file paths.
+
+**Returns:** `GitFileList`
+
+**Example:**
+```typescript
+const classes = GitRead.getListByDirectory('/classes/')
+/**
+ * [
+ *   {
+ *     path: 'classes/GitRead.ts',
+ *     ...
+ *   }
+ * ]
+ */
+```
+
+## Utility Methods
+
+### `getClassesList`
+Gets all non-test TypeScript files in the `/classes/` directory.
+
+**Example:**
+```typescript
+const classes = GitRead.getClassesList()
+/**
+ * [
+ *   {
+ *     path: 'classes/GitRead.ts',
+ *     pathByOS: ['classes', 'GitRead.ts'],
+ *     pathFull: 'packages/scripts/src/classes/GitRead.ts',
+ *     date: '2024-03-21 10:30:00',
+ *     status: undefined
+ *   },
+ *   ...
+ * ]
+ */
+```
+
+### `getFunctionsList`
+Gets all non-test TypeScript files in the `/functions/` directory.
+
+**Example:**
+```typescript
+const funcs = GitRead.getFunctionsList()
+/**
+ * [
+ *   {
+ *     path: 'functions/myFunction.ts',
+ *     pathByOS: ['functions', 'myFunction.ts'],
+ *     pathFull: 'packages/scripts/src/functions/myFunction.ts',
+ *     date: '2024-03-20 15:00:00',
+ *     status: undefined
+ *   }
+ * ]
+ */
+```
+
+### `getFilesPath`
+Returns an array of all tracked file paths in the repository.
+
+**Example:**
+```typescript
+const paths = GitRead.getFilesPath()
+// ['src/index.ts', 'package.json', ...]
+```
+
+### `getFilesPorcelain`
+Returns the raw output of `git status --porcelain` as an array of strings.
+
+**Example:**
+```typescript
+const porcelain = GitRead.getFilesPorcelain()
+// [' M src/index.ts', '?? new-file.txt']
+```
+
+### `getFileDate`
+Returns the date of the last commit for a specific file.
+
+**Parameters:**
+- `filePath: string` — The path to the target file.
+
+**Example:**
+```typescript
+const date = GitRead.getFileDate('src/index.ts')
+// '2024-03-20 12:00:00 +0300'
+```
+
+### `getDirPrefix`
+Returns the current directory's prefix within the Git repository.
+
+**Example:**
+```typescript
+const prefix = GitRead.getDirPrefix()
+// 'packages/scripts/'
+```
+
+### `getDate`
+Formats a date string into a standardized full format.
+
+**Parameters:**
+- `date?: string` — The date string to format (optional).
+
+**Example:**
+```typescript
+const formatted = GitRead.getDate('2024-03-20')
+// '2024-03-20 00:00:00'
+```
+
+### `filterByDirectory`
+Filters a `GitFileList` to include only items that belong to the current directory prefix.
+
+**Parameters:**
+- `list: GitFileList` — The list of files to filter.
+
+**Example:**
+```typescript
+const filtered = GitRead.filterByDirectory(myList)
+```
+
+### `mergeUnique`
+Merges two `GitFileList` arrays, ensuring each file path is unique.
+
+**Parameters:**
+- `listA: GitFileList` — First list.
+- `listB: GitFileList` — Second list.
+
+**Example:**
+```typescript
+const merged = GitRead.mergeUnique(list1, list2)
+```
+
+### `splitPath`
+Splits a file path string into an array of path segments.
+
+**Parameters:**
+- `path: string` — The path to split.
+
+**Example:**
+```typescript
+const parts = GitRead.splitPath('src/classes/GitRead.ts')
+// ['src', 'classes', 'GitRead.ts']
+```
+
+## Data Structures
+
+### `GitFileItem`
+
+The primary object representing a file's state in Git:
+
+- `path: string` — The relative path to the file.
+- `pathByOS: string[]` — The file path split into system-agnostic segments.
+- `pathFull: string` — The full path including any repository-wide directory prefixes.
+- `date: string` — The last modification date (standardized).
+- `status?: GitStatus` — The Git status code (e.g., `'M'`, `'A'`, `'??'`).
+
+### `GitStatus`
+
+Enum representing common Git status codes:
+
+- `MODIFIED` (`'M'`) — Existing file has been changed.
+- `ADDED` (`'A'`) — New file added to the index.
+- `DELETED` (`'D'`) — File has been removed.
+- `UNTRACKED` (`'??'`) — New file not yet tracked by Git.
+- `RENAMED` (`'R'`) — File has been moved or renamed.
+
+## Examples
+
+### Getting Modified Files
+Retrieve a list of files that have been modified or added to the repository.
+
+```typescript
+import { GitRead } from '@dxtmisha/scripts'
+
+const modifiedFiles = GitRead.getListPorcelain()
+console.log(modifiedFiles)
+```
+
+### Filtering Classes
+Get only the class files for a specific module.
+
+```typescript
+const componentClasses = GitRead.getListUnique(
+  (file) => file.includes('packages/ui/src/classes/')
+)
+```