# СомонСкрипт

<div align="center">
  <img src="https://raw.githubusercontent.com/lindentechde/Somon-Script/main/images/somon-script-banner.png" alt="СомонСкрипт Баннер" 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.ru.md) - Забони русӣ

---

## **Нест кардани монеаҳои забонӣ дар рушди нармафзор**

СомонСкрипт махсусан барои нест кардани монеаи забонӣ сохта шудааст, ки бисёре
аз барномарезони истеъдоднокро аз ифода кардани пурраи қобилиятҳои барномарезии
онҳо боздоштааст. Бо таъмини муҳити пурраи барномарезӣ дар хати кирилликаи
тоҷикӣ, СомонСкрипт ба барномарезон имкон медиҳад, ки дар забони модариашон фикр
кунанд, код нависанд ва ҳамкорӣ намоянд ва дар айни ҳол аз қувваи пурраи
парадигмаҳои муосири барномарезӣ истифода баранд.

Ин муносибати инноватсионӣ на танҳо фаҳмиши кодро беҳтар мекунад ва боркунии
когнитивиро кам мекунад, балки дарвозаҳоро барои насли навини барномарезон
мекушояд, ки акнун метавонанд ба экосистемаи ҷаҳонии нармафзор саҳм гузоранд, бе
он ки аз синтаксиси забони хориҷӣ маҳдуд шаванд.

---

## ✨ Чаро СомонСкриптро интихоб кунед?

### 🌍 **Нест кардани монеаҳои забонӣ дар барномарезӣ**

**Тавонманд кардани рушди забони модарӣ**

СомонСкрипт рушди нармафзорро инқилоб мекунад бо нест кардани монеаи асосии
забонӣ:

- **Табиӣ фикр кардан**: Алгоритмҳо ва мантиқи мураккабро дар шаклҳои забони
  модарӣ ифода кунед
- **Кам кардани боркунии когнитивӣ**: Қабати тарҷумаи ақлиро байни концепсия ва
  код нест кунед
- **Беҳтар кардани фаҳмиши код**: Коди худмуаррифшударо нависед, ки барои
  дастаҳои тоҷикзабон фавран хондашаванда аст
- **Суръат додан ба омӯхтан**: Барномарезони нав метавонанд ба консепсияҳои
  барномарезӣ тамаркуз кунанд, на ба синтаксиси хориҷӣ

### 🔒 **Бехатарии навъи синфи касбӣ**

Системи пешрафтаи таҳлили статикӣ бо хусусиятҳои бехатарии сатҳи TypeScript:

- Навъҳои иттиҳод ва буриш
- Навъҳои tuple бо хулосаи дарозӣ
- Мерос ва таркиби интерфейс
- Параметрҳои навъи умумӣ
- Ифодаҳои навъи шартӣ

### ⚡ **Манзараи рушди ҷорӣ**

- **Аудити худкори намунаҳо** – `npm run audit:examples` барномаҳои намунавиро
  пеш аз нашр санҷида мебарояд.
- **Маҷмӯи васеи тестҳо** – зиёда аз 300 тест марҳилаҳои лексер, парсер, санҷиши
  навъ ва CLI-ро мепӯшонад. Ҳисоботҳои пӯшиш бо дархост дастрасанд.
- **Услуб ва формати ягона** – ESLint ва Prettier покии кодро нигоҳ медоранд.
- **Меъмории қабатӣ** – Компилятор, CLI ва системаи модулӣ ҳамчун қисмҳои
  ҷудогона нигоҳ дошта мешаванд.
- **Рушди фаъол** – Барои арзёбӣ ва лоиҳаҳои пилотӣ мувофиқ аст; дар бораи
  мушкилоти дар муҳитҳои истеҳсолӣ дучоршуда хабар диҳед.

---

## 🎨 **Васеъшавии VS Code**

Дастгирии пурраи IDE бо рӯшноии синтаксис, IntelliSense ва фрагментҳои код:

- **Насб аз Бозори VS Code**: "SomonScript"-ро ҷустуҷӯ кунед ё
  [бевосита насб кунед](https://marketplace.visualstudio.com/items?itemName=LindenTechITConsulting.somonscript)
- **Хусусиятҳо**: Рӯшноии синтаксис, толеби худшиносъанд-намуд, 30+ фрагмент,
  вазнданиҳои ҳам-замон
- **Маълумоти Hovering**: Ҳуҷҷатгузории кунҷи тоҷикӣ бо эквивалентҳои
  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 СомонСкрипт акнун **се забонро** дастгирӣ мекунад: Англисӣ, Тоҷикӣ ва Русӣ.
Ин ба барномарезон имкон медиҳад, ки компиляторро дар забони дӯстдоштаашон
истифода баранд.

#### Танзими забон

```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 tj компайл файли-ман.som -o dist/файл.js
somon --lang tj иҷро барнома.som
somon --lang tj баста src/асосӣ.som --minify

# Паёмҳо ҳам дар забони интихобшуда нишон дода мешаванд:
# ✅ 'app.som' ба 'app.js' компайл шуд
# 📦 src/main.som-ро баста мекунем...
# 🔍 src/main.som-ро таҳлил мекунем...
```

### Барномаи аввалини шумо

```bash
# Намунаи Салом ҷаҳон
echo 'чоп.сабт("Салом, ҷаҳон!");' > hello.som
somon run hello.som

# Мантиқи тиҷоратӣ бо бехатарии навъ
cat > calculator.som << 'EOF'
функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

тағ натиҷа = ҷамъ(5, 3);
чоп.сабт("Натиҷа: " + натиҷа);
EOF

somon run calculator.som
```

### Бандлинг (Системаи модул)

- 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` замим мекунад,
агар ба шумо ниёз бошад, ки манбаъ дар артефакт мавҷуд бошад.

### **Омодагӣ барои истеҳсолот**

СомонСкрипт **барои истеҳсолот омода аст** бо хусусиятҳои амалиётии ҳамаҷониба:

- ✅ **Татбиқи пурраи забон** - Ҳамаи хусусиятҳои синтаксиси тоҷикӣ кор мекунанд
- ✅ **Коркарди хатоҳо** - Деградатсияи боадаб ва гузоришдиҳии ҳамаҷониба
- ✅ **Мониторинг ва мушоҳида** - Санҷишҳои саломатӣ, метрикаҳо, логгинги
  сохторӣ
- ✅ **Идораи захираҳо** - Маҳдудиятҳои хотира, таймаутҳо, хомӯшкунии боадаб
- ✅ **Тоқат ба хатоҳо** - Circuit breaker-ҳо, барқарорсозӣ аз хатоҳо
- ✅ **Дастгирии ҷойгиркунӣ** - Docker, Kubernetes, systemd, PM2

📖 **Тафсилот**: [PRODUCTION-READINESS.md](PRODUCTION-READINESS.md)

---

## 🎯 Хусусиятҳои забон

### **Қобилиятҳои асосии забон**

```som
// Тағйирёбандаҳо бо хулосаи навъ
тағ ном = "Дониёр";
собит МАКС_СИННУ_СОЛ: рақам = 120;

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

### **Воситаҳои барномарезии объекторавона**

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

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

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

## 🚀 Ҷойгиркунӣ барои истеҳсолот

### **Режими истеҳсолот**

СомонСкрипт дорои хусусиятҳои ҳамаҷонибаи истеҳсолот аст, ки бо флаги
`--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 breaker-ҳо барои тоқат ба хатоҳо
- ✅ Маҳдудиятҳои захираҳо (хотира, дастгираҳои файл)
- ✅ Логгинги сохтории 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** | `npm run build`          | Пеш аз нашр манбаи TypeScript-ро компил мекунад             |

---

## 🛠️ Рушд ва саҳмгузорӣ

### Талаботи пешакӣ

- 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.tj.md) -
  Маълумотномаи мукаммали ҳамаи методҳои `чоп.*` (сабт, хато, огоҳӣ, маълумот,
  исфти, тасдиқ, ҳисоб, вақт, ҷадвал, пайҷо ва бисёр дигар)
  - [English](examples/CONSOLE_METHODS.md)
  - [Русский](examples/CONSOLE_METHODS.ru.md)
- [🖨️ Намунаҳои содаи чоп](examples/console-log-simple.som) - Намунаҳои оддӣ
  барои оғоз
- [📊 Истифодаи пешрафтаи чоп](examples/console-methods-guide.som) - Дастури
  мукаммал бо ҳамаи методҳои чоп

---

## 🌍 Дастгирии касбӣ

### Хидматҳои техникӣ

- 💬
  [Муҳокимаҳои GitHub](https://github.com/lindentechde/Somon-Script/discussions) -
  Муҳокимаҳо ва саволу ҷавоб
- 🐛 [Мушкилот](https://github.com/lindentechde/Somon-Script/issues) -
  Гузоришҳои хатогӣ ва дархостҳои хусусият
- 📧 Почтаи электронӣ: **info@lindentech.de**

### Хидматҳои касбӣ

LindenTech IT Consulting хидматҳои касбии рушдро пешниҳод мекунад:

1. **Рушди асосӣ**: Беҳтар кардани қобилиятҳо ва самаранокии компилятор
2. **Ҳуҷҷатгузорӣ**: Беҳтар кардани ҳуҷҷатҳо ва дастурҳои техникӣ
3. **Тестгузаронӣ**: Васеъ кардани пӯшиши тест ва таъмини сифат
4. **Ҳамгироӣ**: Сохтани асбобҳо ва дастгирии IDE
5. **Самаранокӣ**: Оптимизатсияи компилятсия ва иҷрои вақти кор

**🚀 Нав: Раванди нашри автоматӣ**

СомонСкрипт акнун semantic-release-ро барои нашрҳои автоматӣ истифода мебарад:

- **Conventional Commits**: Дар паёмҳои commit `feat:`, `fix:`, `docs:` ва
  ғайраро истифода баред
- **Версияи автоматӣ**: Версияи семантикӣ дар асоси навъҳои commit
- **Нашр дар чанд регистр**: Нашри автоматӣ дар NPM, JSR ва GitHub Packages
- **Нашрҳои дастӣ лозим нестанд**: Танҳо commit ва push кунед - система худ кор
  мекунад!

📖 **Ҳуҷҷатгузорӣ**:

- [Дастури раванди нашр](docs/RELEASE-PROCESS.md) - Тафсилоти пурраи
  автоматизатсия
- [CONTRIBUTING.md](CONTRIBUTING.md) - Дастурҳои иштироки ҷомеа
- [AGENTS.md](AGENTS.md) - Қоидаҳои услуби код ва паёмҳои commit

---

## 📄 Иҷозатнома

SomonScript таҳти **иҷозатномаи MIT** паҳн мешавад. Матни пурра дар файли
[LICENSE](LICENSE) дастрас аст.

---

## 🏢 Шарикии корхона

### **Дар ҳамкорӣ бо LindenTech IT Consulting сохта шудааст**

СомонСкрипт дар ҳамкорӣ бо [**LindenTech IT Consulting**](https://lindentech.de)
сохта шудааст - консалтинги пешбари технологияи корхона.

**Веб-сайт**: [lindentech.de](https://lindentech.de)  
**Тамос**: info@lindentech.de

---

## 🌟 Олии техникӣ

Дар асоси принсипҳои исботшудаи муҳандисии нармафзор ва технологияи муосири
компилятор сохта шудааст:

- **Системаи пешрафтаи навъ** - Дар асоси тадқиқоти исботшудаи назарияи навъ
- **Меъмории тоза** - Тарроҳии модулӣ бо принсипҳои SOLID
- **Стандартҳои саноатӣ** - Мувофиқ бо экосистемаи JavaScript-и мавҷуда
- **Оптимизатсияи самаранокӣ** - Компилятсия ва иҷрои самараноки вақти кор

### Стеки технология

- Татбиқи асосии TypeScript барои эътимод
- Мувофиқати экосистемаи Node.js
- Компилятсияи мақсадноки JavaScript-и муосир
- Чаҳорчӯбаи ҳамаҷонибаи тестгузаронӣ

<div align="center">

**СомонСкрипт** - _Барномарезии касбӣ бо синтаксиси маҳаллӣ_

Ҳалли касбии рушди нармафзор

[Веб-сайт](https://somoni-script.org) _(дар рушд)_ •
[GitHub](https://github.com/lindentechde/Somon-Script) • [Ҳуҷҷатгузорӣ](docs/) •
[Дастгирӣ](https://github.com/lindentechde/Somon-Script/discussions)

</div>
