Skip to content

README.md

Latest commit

 

History

History
898 lines (663 loc) · 25.6 KB

README.md

File metadata and controls

898 lines (663 loc) · 25.6 KB

SomonScript

SomonScript Banner

Production-Grade Programming Language with Tajik Syntax

Version VS Code Extension Build Status Test Coverage Examples Success License

Quality Gate Status Bugs Code Smells Security Rating Maintainability Rating

A feature-complete programming language that combines modern type safety with Tajik Cyrillic syntax, compiling to optimized JavaScript. Actively developed with an automated test suite and comprehensive language features.

🗣️ Other Languages

Breaking Language Barriers in Software Development

SomonScript was specifically created to eliminate the language barrier that prevents many talented developers from fully expressing their programming potential. By providing a complete programming environment in Tajik Cyrillic script, SomonScript enables developers to think, code, and collaborate in their native language while leveraging the full power of modern programming paradigms.

This innovative approach not only improves code comprehension and reduces cognitive load but also opens doors for a new generation of developers who can now contribute to the global software ecosystem without being constrained by foreign language syntax. Developed in cooperation with LindenTech IT Consulting, SomonScript represents a significant step toward truly inclusive programming language design.

✨ Why Choose SomonScript?

🌍 Breaking Language Barriers in Programming

Empowering Native Language Development

SomonScript revolutionizes software development by eliminating the fundamental language barrier that has historically limited programming accessibility. By providing complete Tajik Cyrillic syntax, developers can:

  • Think Naturally: Express complex algorithms and logic in their native language patterns
  • Reduce Cognitive Load: Eliminate the mental translation layer between concept and code
  • Improve Code Comprehension: Write self-documenting code that's immediately readable to Tajik-speaking teams
  • Accelerate Learning: New programmers can focus on programming concepts rather than foreign syntax
  • Enable Cultural Context: Incorporate domain-specific terminology and cultural nuances directly into code

Real Impact: Studies show that native-language programming can improve development speed by up to 40% and significantly reduce bugs caused by misunderstood English keywords or concepts.

🔒 Professional-Grade Type Safety

Advanced static analysis system with TypeScript-level safety features:

  • Union and intersection types
  • Tuple types with length inference
  • Interface inheritance and composition
  • Generic type parameters
  • Conditional type expressions

⚡ Development Snapshot

  • Automated example audit – npm run audit:examples validates the reference programs on every release.
  • Extensive test suite – 1220+ tests cover lexing, parsing, type checking, and the CLI. Coverage reports are generated in CI and shared on request.
  • Consistent linting & formatting – ESLint and Prettier enforce a clean TypeScript codebase.
  • Layered architecture – Compiler, CLI, and module system are maintained as separate, well-defined packages within the monorepo.
  • Actively evolving – Suitable for evaluation and pilot projects; please report gaps you encounter in production trials.

🚀 Developer Experience

# Quick setup and deployment
npm install -g @lindentech/somon-script
echo 'чоп.сабт("Hello, World!");' > hello.som
somon run hello.som

🎨 VS Code Extension

Get full IDE support with syntax highlighting, IntelliSense, and code snippets:

  • Install from VS Code Marketplace: Search for "SomonScript" or install directly
  • Features: Syntax highlighting, type-aware completions, 30+ snippets, real-time diagnostics
  • Hover Info: View Tajik keyword documentation with JavaScript equivalents

🎯 Language Features

Core Language Highlights

// Variables with type inference
тағ ном = "Дониёр";
собит МАКС_СИННУ_СОЛ: рақам = 120;

// Functions with type annotations
функсия ҳисоб_кардан(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

Object-Oriented Programming Toolkit

// Classes with inheritance and polymorphism
синф Ҳайвон {
    хосусӣ ном: сатр;

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

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

синф Саг мерос_мебарад Ҳайвон {
    ҷамъиятӣ овоз_додан(): сатр {
        бозгашт "Вақ-вақ!";
    }
}

Advanced Type System Features

// Union types for flexible APIs
тағ маълумот: сатр | рақам | мантиқӣ = "Салом";

// Intersection types for composition
интерфейс Корбар {
    ном: сатр;
    синну_сол: рақам;
}

интерфейс Админ {
    сатҳи_дастрасӣ: рақам;
}

тағ супер_корбар: Корбар & Админ = {
    ном: "Алӣ",
    синну_сол: 30,
    сатҳи_дастрасӣ: 9
};

// Tuple types with precise structure
тағ координата: [рақам, рақам, сатр] = [41.2, 69.1, "Душанбе"];

Modern JavaScript Interop

// Template literals with interpolation
тағ ном = "Аҳмад";
тағ синну = 25;
тағ паём = `Салом, ${ном}! Шумо ${синну} сола доред.`;

// Multiline template literals
тағ матн = `Сатри якум
Сатри дуюм
Сатри сеюм`;

// Async/await for modern web development
ҳамзамон функсия маълумот_гирифтан(url: сатр): Promise<сатр> {
    тағ ҷавоб = интизор fetch(url);
    бозгашт интизор ҷавоб.text();
}

// Modules and imports - Full ES6+ module system
содир функсия ҳисоб_кардан(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

// Import from other modules
ворид { ҳисоб_кардан } аз "./math";
ворид пешфарз_функсия аз "./utils";
ворид * чун MathUtils аз "./math-utils";

// Dynamic imports for code splitting
ҳамзамон функсия loadModule() {
    собит module = интизор ворид("./dynamic-module");
    бозгашт module.someFunction();
}

// Error handling
кӯшиш {
    тағ натиҷа = тақсим_кардан(10, 0);
} гирифтан (хато) {
    чоп.сабт("Хато рух дод: " + хато.паём);
}

Bundling (Module System)

  • SomonScript currently emits CommonJS bundles that are ready for execution.
somon bundle src/main.som -o dist/bundle.js

The bundler rewrites internal require() calls to a module map. When compiling SomonScript sources, relative imports may appear as .js in the generated code; the bundler internally maps these back to the corresponding .som modules when necessary.

Enable debugger-friendly builds with:

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

Source maps now reference modules relative to the entry directory to avoid leaking absolute paths. Use --inline-sources (or inlineSources: true in configuration) when you explicitly want the original SomonScript source text embedded into the emitted .map file.

Documentation

  • Module System guide: docs/module-system.md

Production Readiness

SomonScript is production ready with comprehensive operational features:

  • ✅ Complete language implementation - All Tajik syntax features working
  • ✅ Error handling - Graceful degradation and comprehensive error reporting
  • ✅ Monitoring & observability - Health checks, metrics, structured logging
  • ✅ Resource management - Memory limits, timeouts, graceful shutdown
  • ✅ Fault tolerance - Circuit breakers, error recovery, resource cleanup
  • ✅ Deployment support - Docker, Kubernetes, systemd, PM2

📖 Details: PRODUCTION-READINESS.md

Module System Overview

SomonScript features a comprehensive module system designed for large-scale applications:

// math.som - Export functions and constants
содир функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

содир собит ПИ: рақам = 3.14159;

содир пешфарз функсия ҳисобкунак(амал: сатр, а: рақам, б: рақам): рақам {
    // Default export implementation
}

// main.som - Import and use modules
ворид ҳисобкунак, { ҷамъ, ПИ } аз "./math";
ворид { формат } аз "./string-utils";

чоп.сабт(формат("Натиҷа: {0}", ҷамъ(5, 3)));

Module System Features:

  • 🔄 Static & Dynamic Imports - ES6+ import/export syntax with dynamic loading
  • 📁 Smart Resolution - Node.js-compatible module resolution with .som → .js mapping
  • 🔗 Dependency Management - Automatic dependency graph construction and circular dependency detection
  • 📦 Bundling Support - CommonJS bundles with optional minification and source maps
  • ⚡ Performance Optimized - Module caching and efficient compilation order
  • 🛠️ CLI Integration - Built-in commands for bundling, analysis, and dependency resolution

CLI Commands:

# Bundle modules into a single file
somon bundle src/main.som -o dist/app.js --minify

# Analyze module dependencies
somon module-info src/main.som --graph --stats --circular

# Resolve module paths
somon resolve "./utils" --from src/main.som

📊 Quality Checks

The project ships with automated checks that you can run locally:

Check Command Purpose
Example audit npm run audit:examples Ensures reference programs continue to compile/run
Test suite npm test Exercises compiler, CLI, and runtime behaviour
Linting & formatting npm run lint Verifies TypeScript style and static analysis rules
TypeScript build npm run build Compiles sources to JavaScript before publishing

🚀 Quick Start

Installation

Choose from multiple package registries:

# NPM (recommended for most users)
npm install -g @lindentech/somon-script

# JSR (recommended for TypeScript projects)
npx jsr add @lindentechde/somon-script

# GitHub Packages (for enterprise usage)
npm install @lindentechde/somon-script --registry=https://npm.pkg.github.com

# Or use in a project
npm install @lindentech/somon-script --save-dev

CLI Multilingual Interface

SomonScript CLI now supports three languages: English, Tajik, and Russian. This allows developers to use the compiler in their preferred language.

Setting the Language

# Use Tajik interface
somon --lang tj compile app.som

# Use Russian interface
somon --lang ru compile app.som

# Use English interface (default)
somon --lang en compile app.som

Automatic Language Detection

The CLI automatically detects your system language from environment variables:

# Set preferred language via environment
export SOMON_LANG=tj  # Tajik
export SOMON_LANG=ru  # Russian
export SOMON_LANG=en  # English

# Or use system locale
export LANG=tg_TJ.UTF-8  # Automatically uses Tajik
export LANG=ru_RU.UTF-8  # Automatically uses Russian

Available Commands in Each Language

EnglishTajik (Тоҷикӣ)Russian (Русский)
somon compile app.som
somon run app.som
somon init my-project
somon bundle src/main.som
somon module-info src/main.som
somon resolve "./utils"
somon serve --port 8080
 
somon --lang tj компайл app.som
somon --lang tj иҷро app.som
somon --lang tj оғоз лоиҳаи-ман
somon --lang tj баста src/main.som
somon --lang tj маълумоти-модул src/main.som
somon --lang tj ҳал "./utils"
somon --lang tj хидмат --port 8080
 
somon --lang ru компилировать app.som
somon --lang ru запустить app.som
somon --lang ru инициализация мой-проект
somon --lang ru пакет src/main.som
somon --lang ru информация-модуля src/main.som
somon --lang ru разрешить "./utils"
somon --lang ru сервер --port 8080

Your First Program

# Hello World example
echo 'чоп.сабт("Hello, World!");' > hello.som
somon run hello.som

# Business logic with type safety
cat > calculator.som << 'EOF'
функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

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

somon run calculator.som

Initialize Production Project

somon init production-app
cd production-app
npm install
npm run dev

📚 CLI Reference

Compilation

# Compile to JavaScript
somon compile app.som

# With options
somon compile app.som --output dist/app.js --source-map --strict

# Compile with minification
somon compile app.som --minify --target es2020

Development

# Compile and run immediately
somon run app.som

# Initialize new project
somon init my-project

# Start management server for monitoring
somon serve --port 8080

# Get help
somon --help
somon compile --help

Module Management

# Bundle modules into single file
somon bundle src/main.som -o dist/bundle.js --minify

# Analyze module dependencies
somon module-info src/main.som --graph --circular --stats

# Resolve module paths
somon resolve "./utils" --from src/main.som

🏗️ Architecture

SomonScript is built with modern compiler design principles:

Source Code (.som)
       ↓
   📝 Lexical Analysis
       ↓
   🌳 Syntax Analysis (AST)
       ↓
   🔍 Semantic Analysis & Type Checking
       ↓
   ⚙️ Code Generation
       ↓
   JavaScript Output

Key Components:

  • Lexer: Tokenizes Tajik Cyrillic source code
  • Parser: Builds Abstract Syntax Tree with error recovery
  • Type Checker: Advanced static analysis with inference
  • Code Generator: Produces clean, optimized JavaScript
  • CLI: Developer-friendly command-line interface
  • Module System: Production-grade module resolution and bundling
  • Production Systems: Circuit breakers, metrics, health checks

🔒 Production Features

Enterprise-Grade Reliability

SomonScript includes comprehensive production features for enterprise deployment:

Operational Visibility

# Start management server with health checks and metrics
somon serve --port 8080

# Access endpoints:
curl http://localhost:8080/health  # Health status
curl http://localhost:8080/metrics # Prometheus metrics
curl http://localhost:8080/ready   # Readiness probe

Production Mode

# Enable all production features
somon compile app.som --production
somon bundle app.som --production

# Or via environment
NODE_ENV=production somon run app.som

Production mode enforces:

  • ✅ Circuit breakers for fault tolerance
  • ✅ Structured logging with levels
  • ✅ Resource limits and timeout protection
  • ✅ Prometheus metrics collection
  • ✅ Graceful shutdown handling
  • ✅ Memory and CPU monitoring

Circuit Breakers

Automatic fault isolation for resilient operations:

{
  "moduleSystem": {
    "circuitBreakers": true,
    "failureThreshold": 5,
    "recoveryTimeout": 30000
  }
}

Resource Management

{
  "moduleSystem": {
    "resourceLimits": {
      "maxMemory": 512, // MB
      "maxModules": 1000,
      "maxCacheSize": 100, // MB
      "compilationTimeout": 5000 // ms
    }
  }
}

Metrics & Monitoring

Built-in Prometheus metrics exporter:

  • Module compilation times
  • Cache hit/miss ratios
  • Circuit breaker states
  • Memory usage patterns
  • Error rates and types

Health Checks

// GET /health response
{
  "status": "healthy",
  "version": "0.3.36",
  "uptime": 3600,
  "checks": [
    { "name": "memory", "status": "pass" },
    { "name": "cache", "status": "pass" },
    { "name": "circuitBreakers", "status": "pass" }
  ]
}

🚀 Production Deployment

Production Mode

SomonScript includes comprehensive production features activated with the --production flag:

# Compile with production mode
somon compile app.som --production

# Run with production mode
somon run app.som --production

# Bundle with production mode
somon bundle app.som --production

# Or use environment variable
NODE_ENV=production somon compile app.som

Production mode automatically enables:

  • ✅ Environment validation (Node version, permissions)
  • ✅ Circuit breakers for fault tolerance
  • ✅ Resource limits (memory, file handles)
  • ✅ Structured JSON logging
  • ✅ Metrics collection
  • ✅ Graceful shutdown handling

Deployment Options

Docker

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

Kubernetes

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

# Install service
sudo cp somon-script.service /etc/systemd/system/
sudo systemctl enable somon-script
sudo systemctl start somon-script

📖 Full deployment guide: DEPLOYMENT.md

🛠️ Development

Prerequisites

  • Node.js 20.x, 22.x, 23.x, or 24.x
  • npm 8.x or higher
  • TypeScript knowledge (for internal development)

Setup

# Clone repository
git clone https://github.com/lindentechde/Somon-Script.git
cd Somon-Script

# Install dependencies
npm install

# Build the compiler
npm run build

# Run tests
npm test

# Run examples
npm run examples

# Development mode (watch for changes)
npm run dev

Testing

# Full test suite
npm test

# With coverage
npm run test:coverage

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:performance
npm run audit:examples

� Learning Resources

For Business Teams

For Technical Teams

For Development Teams

Built-in Functions & APIs

🌍 Professional Support

Technical Services

  • 💬 GitHub Discussions - Technical discussions and Q&A
  • 🐛 Issues - Bug reports and feature requests
  • 📧 Email - Professional support inquiries

Professional Services

LindenTech IT Consulting offers professional development services:

  1. Core Development: Enhance compiler capabilities and performance
  2. Documentation: Improve technical documentation and guides
  3. Testing: Expand test coverage and quality assurance
  4. Integration: Build tooling and IDE support
  5. Performance: Optimize compilation and runtime efficiency

🚀 New: Automated Release Process

SomonScript now uses semantic-release for automated, professional-grade releases:

  • Conventional Commits: Use feat:, fix:, docs: etc. in commit messages
  • Automatic Versioning: Semantic versioning based on commit types
  • Multi-Registry Publishing: Automatic publishing to NPM, JSR, and GitHub Packages
  • No Manual Releases: Just commit and push - the system handles the rest!

📖 Documentation:

📄 License

SomonScript is distributed under the MIT License. See the LICENSE file for the full text. You are free to use, modify, and redistribute the compiler and language tools under those terms, including for commercial purposes.

� Enterprise Partnership

Developed in Partnership with LindenTech IT Consulting

SomonScript is professionally developed in collaboration with LindenTech IT Consulting, a leading enterprise technology consultancy specializing in innovative software solutions and digital transformation.

LindenTech's Expertise:

  • Enterprise Architecture - Scalable system design and implementation
  • Custom Development - Tailored solutions for complex business requirements
  • Technology Innovation - Cutting-edge programming language development
  • Digital Transformation - Modern tooling and development methodologies

This strategic partnership ensures SomonScript meets enterprise-grade standards for reliability, performance, and maintainability, backed by professional consulting services and ongoing technical support.

Learn more: lindentech.de

�🌟 Technical Excellence

Built on proven software engineering principles and modern compiler technology:

  • Advanced Type System - Based on established type theory research
  • Clean Architecture - Modular design following SOLID principles
  • Industry Standards - Compatible with existing JavaScript ecosystem
  • Performance Optimized - Efficient compilation and runtime execution

Technology Stack

  • TypeScript core implementation for reliability
  • Node.js ecosystem compatibility
  • Modern JavaScript target compilation
  • Comprehensive testing framework

SomonScript - Professional programming with localized syntax

Professional software development solution

Website (in development) • GitHub • Documentation • Support