# SomonScript

<div align="center">
  <img src="https://raw.githubusercontent.com/lindentechde/Somon-Script/main/images/somon-script-banner.png" alt="SomonScript Баннер" width="500" style="max-width: 100%; height: auto;" />
</div>

**Язык программирования производственного уровня с таджикским синтаксисом**

[![Версия](https://img.shields.io/npm/v/@lindentech/somon-script)](https://www.npmjs.com/package/@lindentech/somon-script)
[![Расширение VS Code](https://img.shields.io/visual-studio-marketplace/v/LindenTechITConsulting.somonscript?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=LindenTechITConsulting.somonscript)
[![Статус Сборки](https://img.shields.io/github/actions/workflow/status/lindentechde/Somon-Script/automated-release.yml?branch=main&label=build)](https://github.com/lindentechde/Somon-Script/actions)
[![Покрытие Тестов](https://img.shields.io/codecov/c/github/lindentechde/Somon-Script)](https://codecov.io/gh/lindentechde/Somon-Script)
[![Успех Примеров](https://img.shields.io/github/actions/workflow/status/lindentechde/Somon-Script/automated-release.yml?branch=main&label=examples&job=test)](https://github.com/lindentechde/Somon-Script/actions)
[![Лицензия](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[![Статус Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=lindentechde_Somon-Script&metric=alert_status)](https://sonarcloud.io/project/overview?id=lindentechde_Somon-Script)
[![Ошибки](https://sonarcloud.io/api/project_badges/measure?project=lindentechde_Somon-Script&metric=bugs)](https://sonarcloud.io/project/overview?id=lindentechde_Somon-Script)
[![Проблемы Кода](https://sonarcloud.io/api/project_badges/measure?project=lindentechde_Somon-Script&metric=code_smells)](https://sonarcloud.io/project/overview?id=lindentechde_Somon-Script)
[![Рейтинг Безопасности](https://sonarcloud.io/api/project_badges/measure?project=lindentechde_Somon-Script&metric=security_rating)](https://sonarcloud.io/project/overview?id=lindentechde_Somon-Script)
[![Рейтинг Поддерживаемости](https://sonarcloud.io/api/project_badges/measure?project=lindentechde_Somon-Script&metric=sqale_rating)](https://sonarcloud.io/project/overview?id=lindentechde_Somon-Script)

Полнофункциональный язык программирования с современной типобезопасностью и
синтаксисом таджикской кириллицы, компилирующийся в оптимизированный JavaScript.
Проект активно развивается, сопровождается автоматизированными тестами и
подробной документацией по языковым возможностям.

## 🗣️ **Другие языки**

- 🇺🇸 [English](README.md) - Основной язык
- 🇹🇯 [Тоҷикӣ](README.tj.md) - Родной язык
- 🇷🇺 **Русский** - Русский язык

---

## **Преодоление языковых барьеров в разработке программного обеспечения**

SomonScript был специально создан для устранения языкового барьера, который
мешает многим талантливым разработчикам полностью выразить свой программистский
потенциал. Предоставляя полную среду программирования на таджикской кириллице,
SomonScript позволяет разработчикам думать, кодить и сотрудничать на родном
языке, используя всю мощь современных парадигм программирования.

Этот инновационный подход не только улучшает понимание кода и снижает
когнитивную нагрузку, но также открывает двери для нового поколения
разработчиков, которые теперь могут вносить вклад в глобальную экосистему
программного обеспечения, не ограничиваясь синтаксисом иностранного языка.

---

## ✨ Почему выбрать SomonScript?

### 🌍 **Преодоление языковых барьеров в программировании**

**Расширение возможностей разработки на родном языке**

SomonScript революционизирует разработку программного обеспечения, устраняя
фундаментальный языковой барьер:

- **Естественное мышление**: Выражайте сложные алгоритмы и логику в паттернах
  родного языка
- **Снижение когнитивной нагрузки**: Устраните слой ментального перевода между
  концепцией и кодом
- **Улучшение понимания кода**: Пишите самодокументирующийся код, который сразу
  читается таджикскими командами
- **Ускорение обучения**: Новые программисты могут сосредоточиться на концепциях
  программирования, а не на иностранном синтаксисе

### 🔒 **Типобезопасность профессионального уровня**

Передовая система статического анализа с возможностями уровня TypeScript:

- Объединение и пересечение типов
- Кортежные типы с выводом длины
- Наследование и композиция интерфейсов
- Универсальные параметры типов
- Условные выражения типов

### ⚡ **Статус разработки**

- **Автоматический аудит примеров** – `npm run audit:examples` проверяет
  эталонные программы перед релизами.
- **Расширенный набор тестов** – более 300 тестов охватывают лексер, парсер,
  проверку типов и CLI. Отчёты о покрытии доступны по запросу.
- **Единый стиль кода** – ESLint и Prettier поддерживают чистую кодовую базу
  TypeScript.
- **Слоистая архитектура** – Компилятор, CLI и модульная система развиваются как
  отдельные, чётко определённые пакеты.
- **Активное развитие** – Подходит для оценки и пилотных проектов; сообщайте о
  проблемах, которые вы обнаружите в производственной среде.

---

## 🎨 **Расширение VS Code**

Получите полную поддержку IDE с подсветкой синтаксиса, IntelliSense и
фрагментами кода:

- **Установка из VS Code Marketplace**: Поиск "SomonScript" или
  [прямая установка](https://marketplace.visualstudio.com/items?itemName=LindenTechITConsulting.somonscript)
- **Функции**: Подсветка синтаксиса, автодополнение с учётом типов, 30+
  фрагментов, диагностика в реальном времени
- **Информация при наведении**: Просмотрите документацию таджикских ключевых
  слов с эквивалентами JavaScript

---

## 🚀 Быстрый старт

### Установка

```bash
# NPM (рекомендуется для большинства пользователей)
npm install -g @lindentech/somon-script

# JSR (рекомендуется для проектов TypeScript)
npx jsr add @lindentechde/somon-script

# Или используйте в проекте
npm install @lindentech/somon-script --save-dev
```

### Многоязычный интерфейс CLI

CLI SomonScript теперь поддерживает **три языка**: английский, таджикский и
русский. Это позволяет разработчикам использовать компилятор на предпочитаемом
языке.

#### Установка языка

```bash
# Использование таджикского интерфейса
somon --lang tj компайл app.som

# Использование русского интерфейса
somon --lang ru компилировать app.som

# Использование английского интерфейса (по умолчанию)
somon --lang en compile app.som
```

#### Автоматическое определение языка

CLI автоматически определяет язык вашей системы из переменных окружения:

```bash
# Установка предпочитаемого языка через окружение
export SOMON_LANG=tj  # Таджикский
export SOMON_LANG=ru  # Русский
export SOMON_LANG=en  # Английский

# Или использование системной локали
export LANG=tg_TJ.UTF-8  # Автоматически использует таджикский
export LANG=ru_RU.UTF-8  # Автоматически использует русский
```

#### Доступные команды на каждом языке

<table>
<tr><th>Английский</th><th>Таджикский</th><th>Русский</th></tr>
<tr>
<td>

```bash
compile app.som
run app.som
init my-project
bundle src/main.som
module-info src/main.som
resolve "./utils"
serve --port 8080
```

</td>
<td>

```bash
компайл app.som
иҷро app.som
оғоз лоиҳаи-ман
баста src/main.som
маълумоти-модул src/main.som
ҳал "./utils"
хидмат --port 8080
```

</td>
<td>

```bash
компилировать app.som
запустить app.som
инициализация мой-проект
пакет src/main.som
информация-модуля src/main.som
разрешить "./utils"
сервер --port 8080
```

</td>
</tr>
</table>

#### Примеры использования

```bash
# На русском языке
somon --lang ru компилировать мой-файл.som -o dist/файл.js
somon --lang ru запустить программа.som
somon --lang ru пакет src/главный.som --minify

# Сообщения также отображаются на выбранном языке:
# ✅ Скомпилировано 'app.som' в 'app.js'
# 📦 Собираем src/main.som...
# 🔍 Анализируем src/main.som...
```

### Ваша первая программа

```bash
# Пример Hello World
echo 'чоп.сабт("Привет, мир!");' > hello.som
somon run hello.som

# Бизнес-логика с типобезопасностью
cat > calculator.som << 'EOF'
функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

тағ натиҷа = ҷамъ(5, 3);
чоп.сабт("Результат: " + натиҷа);
EOF

somon run calculator.som
```

### Сборка (Module System)

- SomonScript генерирует готовые к запуску CommonJS-бандлы.

```bash
somon bundle src/main.som -o dist/bundle.js
```

Для отладки используйте `--source-map`, чтобы получить карту исходников:

```bash
somon bundle src/main.som -o dist/bundle.js --source-map
```

Карта теперь содержит пути модулей, относительные каталогу точки входа, что
исключает утечки абсолютных путей. Флаг `--inline-sources` (или параметр
`inlineSources: true` в конфигурации) встраивает текст SomonScript в `.map`,
если вам нужно иметь исходный код прямо в артефакте.

### **Готовность к производственной эксплуатации**

SomonScript **готов к производственной эксплуатации** с комплексными
операционными функциями:

- ✅ **Полная реализация языка** - Все функции таджикского синтаксиса работают
- ✅ **Обработка ошибок** - Изящная деградация и комплексная отчетность
- ✅ **Мониторинг и наблюдаемость** - Проверки здоровья, метрики,
  структурированное логирование
- ✅ **Управление ресурсами** - Ограничения памяти, таймауты, изящное завершение
- ✅ **Отказоустойчивость** - Circuit breakers, восстановление после ошибок
- ✅ **Поддержка развертывания** - Docker, Kubernetes, systemd, PM2

📖 **Подробности**: [PRODUCTION-READINESS.md](PRODUCTION-READINESS.md)

---

## 🎯 Возможности языка

### **Основные возможности языка**

```som
// Переменные с выводом типов
тағ ном = "Донёр";
собит МАКС_СИННУ_СОЛ: рақам = 120;

// Функции с аннотациями типов
функсия ҳисоб_кардан(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}
```

### **Инструменты объектно-ориентированного программирования**

```som
синф Ҳайвон {
    хосусӣ ном: сатр;

    конструктор(ном: сатр) {
        ин.ном = ном;
    }

    ҷамъиятӣ овоз_додан(): сатр {
        бозгашт "Общий звук";
    }
}
```

## 🚀 Развертывание в производственной среде

### **Производственный режим**

SomonScript включает комплексные производственные функции, активируемые флагом
`--production`:

```bash
# Компиляция в производственном режиме
somon compile app.som --production

# Запуск в производственном режиме
somon run app.som --production

# Сборка в производственном режиме
somon bundle app.som --production

# Или через переменную окружения
NODE_ENV=production somon compile app.som
```

**Производственный режим автоматически включает:**

- ✅ Проверка окружения (версия Node, разрешения)
- ✅ Circuit breakers для отказоустойчивости
- ✅ Ограничения ресурсов (память, файловые дескрипторы)
- ✅ Структурированное логирование JSON
- ✅ Сбор метрик
- ✅ Изящное завершение работы

### **Варианты развертывания**

#### **Docker**

```bash
docker run -d \
  --name somon \
  -p 8080:8080 \
  -e NODE_ENV=production \
  somon-script:latest
```

#### **Kubernetes**

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: somon-script
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: somon
          image: somon-script:latest
          env:
            - name: NODE_ENV
              value: production
```

#### **Systemd**

```bash
# Установка сервиса
sudo cp somon-script.service /etc/systemd/system/
sudo systemctl enable somon-script
sudo systemctl start somon-script
```

📖 **Полное руководство**: [DEPLOYMENT.md](DEPLOYMENT.md)

---

## 📊 Проверки качества

Проект включает автоматические проверки, которые можно запускать локально:

| Проверка                     | Команда                  | Назначение                                               |
| ---------------------------- | ------------------------ | -------------------------------------------------------- |
| **Аудит примеров**           | `npm run audit:examples` | Убеждается, что эталонные программы продолжают работать  |
| **Тестовый набор**           | `npm test`               | Проверяет компилятор, CLI и поведение времени выполнения |
| **Linting и форматирование** | `npm run lint`           | Контролирует стиль и статический анализ TypeScript       |
| **Сборка TypeScript**        | `npm run build`          | Компилирует исходники перед публикацией                  |

---

## 🛠️ Разработка и вклад

### Предварительные требования

- Node.js 20.x, 22.x, 23.x или 24.x
- npm 8.x или выше
- Знание TypeScript (для внутренней разработки)

### Настройка

```bash
# Клонирование репозитория
git clone https://github.com/lindentechde/Somon-Script.git
cd Somon-Script

# Установка зависимостей
npm install

# Сборка компилятора
npm run build

# Запуск тестов
npm test

# Режим разработки (отслеживание изменений)
npm run dev
```

### Тестирование

```bash
# Полный набор тестов
npm test

# С покрытием
npm run test:coverage

# Конкретные категории тестов
npm run test:unit
npm run test:integration
npm run audit:examples
```

---

## 📚 Образовательные ресурсы

### **Для бизнес-команд**

- [🎓 Учебник](docs/tutorial/) - Структурированный путь обучения
- [📋 Примеры](examples/) - 32+ готовых к производству примеров кода
- [🎯 Краткий справочник](docs/reference/quick-start.md) - Руководство по
  основному синтаксису

### **Для технических команд**

- [📘 Справочник по языку](docs/reference/) - Полная документация API
- [🔧 Практические руководства](docs/how-to/) - Паттерны реализации
- [⚡ Лучшие практики](docs/how-to/best-practices.md) - Стандарты промышленного
  кодирования

### **Для команд разработки**

- [🏛️ Руководство по архитектуре](docs/explanation/architecture.md) - Принципы
  системного проектирования
- [🧪 Руководство по тестированию](docs/explanation/testing.md) - Методология
  обеспечения качества
- [🤝 Участие сообщества](CONTRIBUTING.md) - Рекомендации по участию

### **Встроенные функции и API**

- [📖 Справочник методов консоли](examples/CONSOLE_METHODS.ru.md) - Полная
  справка по всем методам `чоп.*` (log, error, warn, info, debug, assert, count,
  time, table, trace и многое другое)
  - [English](examples/CONSOLE_METHODS.md)
  - [Тоҷикӣ](examples/CONSOLE_METHODS.tj.md)
- [🖨️ Простые примеры вывода](examples/console-log-simple.som) - Простые примеры
  для начала работы
- [📊 Продвинутое использование консоли](examples/console-methods-guide.som) -
  Полное руководство со всеми методами консоли

---

## 🌍 Профессиональная поддержка

### Технические услуги

- 💬
  [Обсуждения GitHub](https://github.com/lindentechde/Somon-Script/discussions) -
  Технические обсуждения и Q&A
- 🐛 [Проблемы](https://github.com/lindentechde/Somon-Script/issues) - Отчеты об
  ошибках и запросы функций
- 📧 Электронная почта: **info@lindentech.de**

### Профессиональные услуги

LindenTech IT Consulting предлагает профессиональные услуги разработки:

1. **Основная разработка**: Улучшение возможностей и производительности
   компилятора
2. **Документация**: Улучшение технической документации и руководств
3. **Тестирование**: Расширение тестового покрытия и обеспечение качества
4. **Интеграция**: Создание инструментария и поддержка IDE
5. **Производительность**: Оптимизация компиляции и времени выполнения

**🚀 Новое: Автоматизированный процесс релизов**

SomonScript теперь использует semantic-release для автоматизированных релизов:

- **Conventional Commits**: Используйте `feat:`, `fix:`, `docs:` и т.д. в
  сообщениях коммитов
- **Автоматическое версионирование**: Семантическое версионирование на основе
  типов коммитов
- **Публикация в несколько реестров**: Автоматическая публикация в NPM, JSR и
  GitHub Packages
- **Никаких ручных релизов**: Просто коммитьте и пушьте - система обработает
  остальное!

📖 **Документация**:

- [Руководство по процессу релизов](docs/RELEASE-PROCESS.md) - Полная информация
  об автоматизации
- [CONTRIBUTING.md](CONTRIBUTING.md) - Рекомендации по участию сообщества
- [AGENTS.md](AGENTS.md) - Стиль кода, сообщения коммитов и правила тестирования

---

## 📄 Лицензия

SomonScript распространяется по **лицензии MIT**. Полный текст доступен в
[LICENSE](LICENSE).

---

## 🏢 Корпоративное партнерство

### **Разработано в партнерстве с LindenTech IT Consulting**

SomonScript профессионально разработан в сотрудничестве с
[**LindenTech IT Consulting**](https://lindentech.de) - ведущей консалтинговой
компанией корпоративных технологий.

**Веб-сайт**: [lindentech.de](https://lindentech.de)  
**Контакты**: info@lindentech.de

---

## 🌟 Техническое превосходство

Построен на проверенных принципах программной инженерии и современной технологии
компиляторов:

- **Продвинутая система типов** - Основана на проверенных исследованиях теории
  типов
- **Чистая архитектура** - Модульный дизайн с принципами SOLID
- **Отраслевые стандарты** - Совместимость с существующей экосистемой JavaScript
- **Оптимизированная производительность** - Эффективная компиляция и время
  выполнения

### Технологический стек

- Базовая реализация на TypeScript для надежности
- Совместимость с экосистемой Node.js
- Компиляция в современный JavaScript
- Комплексная тестовая инфраструктура

<div align="center">

**SomonScript** - _Профессиональное программирование с локализованным
синтаксисом_

Профессиональное решение для разработки программного обеспечения

[Веб-сайт](https://somoni-script.org) _(в разработке)_ •
[GitHub](https://github.com/lindentechde/Somon-Script) • [Документация](docs/) •
[Поддержка](https://github.com/lindentechde/Somon-Script/discussions)

</div>
