npm package: @specverse/lang
Description: SpecVerse Language - YAML + Conventions + AI Inference for Specification-Driven Development
Author: SpecVerse Team
Latest version: 3.5.3

# SpecVerse Language

[![npm version](https://img.shields.io/npm/v/@specverse/lang.svg)](https://www.npmjs.com/package/@specverse/lang)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#testing)
[![AI-Powered](https://img.shields.io/badge/AI-powered-purple.svg)](#ai-powered-inference)
[![MCP Server](https://img.shields.io/badge/MCP%20Server-deployed-success.svg)](#mcp-server)

**The Revolutionary Application Specification Language for Human-AI Collaboration**

## 🌟 What is SpecVerse?

SpecVerse is a **specification language designed for seamless communication between humans and AI systems**. It enables you to describe applications at three architectural layers—Components, Deployments, and Manifests—using a human-readable YAML syntax enhanced with powerful conventions and AI-powered inference.

### 🏗️ **Three-Layer Architecture**

**1. 📦 Components Layer**
- Define your application's logical structure: models, controllers, services, events, and views
- Specify business logic, data relationships, and system boundaries
- Use lifecycle state machines and CURVED operations (Create, Update, Retrieve, Retrieve_many, Validate, Evolve, Delete)

**2. 🚀 Deployments Layer**
- Configure production-ready deployment topologies with logical instances
- Define storage, security, infrastructure, and monitoring capabilities
- Scale from personal projects to enterprise multi-tenant architectures

**3. 🛠️ Manifests Layer**
- Generate concrete deployment artifacts (Kubernetes, Docker, cloud configurations)
- Bridge the gap between specification and executable infrastructure
- Maintain perfect alignment between design intent and deployed reality

### 🧠 **Language Model: Distributed MVC + Lifecycle**

SpecVerse implements a **distributed Model-View-Controller pattern** enhanced with:

- **📊 Models**: Rich data definitions with relationships, attributes, and constraints
- **🎮 Controllers**: CURVED operations (Create, Update, Retrieve, Retrieve_many, Validate, Evolve, Delete) for complete lifecycle management
- **⚙️ Services**: Business logic components with event subscription capabilities
- **📱 Views**: User interface specifications with state binding and interaction patterns
- **🔄 Lifecycles**: State machines that govern entity transitions across all architectural layers
- **🎯 Conventions**: Smart defaults and shorthand syntax that reduce boilerplate by 90%
- **👤 Profiles**: Reusable component patterns for rapid composition

### 🤖 **AI-Powered Inference Engine**

The heart of SpecVerse: **21+ intelligent inference rules** that transform your minimal specifications into complete architectures:

- **Context-Aware Generation**: Understands relationships and generates appropriate controllers, services, and events
- **Scale Intelligence**: Automatically recognizes project complexity and generates appropriate enterprise features
- **Type Inference**: Complete type system generation from model definitions
- **Cascade Handling**: Smart relationship processing with eager loading and validation

### 📚 **Rich Library Ecosystem**

- **@specverse/primitives**: Core reusable types (Address, Money, PhoneNumber, PersonName, ContactInfo, AuditFields)
- **@specverse/business**: Business domain types (Organization, Employee)
- **@specverse/system**: System and technical types (Configuration, LogEntry)
- **@specverse/deployments**: Production deployment patterns (monolith, microservices, enterprise, jamstack)
- **Component Libraries**: Reusable architectural patterns (authentication, user management, notifications)
- **Deployment Libraries**: Production-ready deployment templates (monolith, microservices, serverless)
- **Domain Libraries**: Industry-specific models and patterns (e-commerce, healthcare, finance)

### 🛠️ **CLI Capabilities**

**Modern Grouped Commands:**
- `specverse gen` - Generate YAML, UML diagrams, documentation, and AI-optimized views
- `specverse dev` - Development workflow (validation, formatting, quick checks)
- `specverse test` - Testing workflows and validation cycles
- `specverse ai` - AI-assisted specification development (config, templates, suggestions)
- `specverse infer` - AI-powered architecture expansion and inference
- `specverse init` - Project initialization with intelligent templates

**Legacy Support:** Full backward compatibility with traditional commands (`validate`, `process`, `check`)

### 🔧 **Comprehensive Toolchain**

**Development Tools:**
- **🎨 VSCode Extension**: Full syntax highlighting, IntelliSense, real-time validation, and diagram preview
- **📊 Diagram Generator**: Mermaid-based UML diagrams (ER, sequence, architecture, lifecycle, deployment)
- **📝 Documentation Generator**: Auto-generated comprehensive documentation with cross-references
- **🤖 AI Orchestrator**: Interactive AI workflow system for collaborative specification development

**Integration Tools:**
- **🔌 MCP Server**: Universal AI assistant integration across all environments (Claude Desktop, web interfaces, enterprise)
- **📦 TypeScript/JavaScript API**: Complete programmatic access for custom applications and build tools
- **🐳 Docker Support**: Containerized deployment for enterprise environments
- **☁️ Multi-Cloud**: Generate deployment artifacts for AWS, Azure, GCP, and Kubernetes

SpecVerse combines YAML + Conventions with AI-powered inference to transform minimal specifications (`.specly` files) into complete system architectures. Write 90% less code while maintaining perfect alignment between design and implementation.

## 📈 Recent Releases

### 🎉 **v3.4.9 (Current)** - November 15, 2025

**Latest stable release** with comprehensive code generation improvements:

- **🐛 Debug Enhancements**: Enhanced path resolution logging (enable with `SPECVERSE_DEBUG=true`)
- **🔧 Build Fixes**: Fixed TypeScript compilation for libs/ directory
- **📦 Package Reliability**: Resolved tsx node_modules restrictions
- **🎨 Pattern Adapters**: Complete pattern adapter bundling for generated projects
- **✨ View Rendering**: Pattern-based architecture with 49 atomic component types

**Current View Syntax** (as of v3.4.x):
```yaml
views:
  TaskListView:
    uiComponents:        # ✅ Current standard property name
      taskTable:
        type: table
        properties:
          columns: [title, status, priority]
```

### ✨ **v3.3.0** - Generic Scaffolding Architecture

Complete project generation with technology-agnostic scaffolding:

- **🏗️ Complete Projects**: Single command generates entire runnable applications
- **⚙️ Framework Agnostic**: Works with any ORM/framework combination
- **📦 Smart Dependencies**: Auto-aggregates requirements, scripts, and environment variables
- **🚀 Production Ready**: From `specverse realize all` to `npm run dev` in seconds

### 📚 **Complete Version History**

For detailed release notes, migration guides, and breaking changes, see:
**📖 [CHANGELOG.md](CHANGELOG.md)** - Complete version history with all features and fixes

---

## 🔮 Roadmap

### **Planned Features**

#### **Registry Linter** (Future Release)
Optional validation of implementation manifests before code generation with typo detection and deprecation warnings.

**📖 See**: `docs/specs/registry-linter-specification.md` for complete specification


## 🚀 Quick Start

### Installation

**Option 1: From npm (recommended for new projects)**
```bash
npm install -g @specverse/lang
```

**Option 2: From source (for development)**
```bash
git clone https://github.com/SpecVerse/specverse-lang.git
cd specverse-lang
npm run setup && npm run build
```

### Standard AI Prompts 🤖

SpecVerse includes enhanced AI prompts for terminal/chat-based development:

```bash
# View the complete prompt collection
ls prompts/core/standard/default/

# create.prompt.yaml     - Generate specs from requirements
# analyse.prompt.yaml    - Extract specs from existing code
# materialise.prompt.yaml - Generate implementations
# realize.prompt.yaml    - Generate deployments (environment-adaptive)
```

**Quick Terminal Usage:**
```bash
# Get ready-to-use terminal prompts
cat prompts/core/base-terminal-prompt.md
```

**Complete Workflow:**
1. **Create** specification from natural language
2. **Materialise** into production-ready code
3. **Realize** deployment configurations
4. **Deploy** with generated automation scripts

[📖 Complete Terminal Guide](prompts/core/base-terminal-prompt.md)

### AI Commands (v3.2.10+) 🚀

SpecVerse provides a unified CLI for AI-assisted specification development:

#### Quick Start with AI Config

```bash
# Generate a default AI configuration template
specverse ai config --output my-project-config.yaml

# Edit the config file with your requirements
# Then use it to generate prompts with auto-enhancement
specverse ai template create --config my-project-config.yaml
```

#### Available Commands

**📚 `ai docs`** - Show AI documentation paths
```bash
specverse ai docs
# Displays paths to: AI schema, reference examples, prompt templates
```

**⚙️ `ai config`** - Generate default configuration template
```bash
specverse ai config                          # Display to console
specverse ai config --output ai-config.yaml  # Save to file
```

**📝 `ai template`** - Get/fill AI prompt templates (unified command)
```bash
# Get raw template
specverse ai template create

# Create from requirements
specverse ai template create "patient management system"

# Analyse existing code
specverse ai template analyse "FastAPI application at ./src"

# Materialise implementation
specverse ai template materialise --config ai-config.yaml

# Realize deployment
specverse ai template realize --config ai-config.yaml
```

**🔍 `ai suggest`** - Get SpecVerse library recommendations
```bash
# Suggest from inline requirements
specverse ai suggest --requirements "ecommerce platform with payments"

# Suggest from config file
specverse ai suggest --config ai-config.yaml
```

#### AI Config File Format

The config file supports comprehensive project specification:

```yaml
# Project requirements (multi-line support)
requirements: |
  A patient management system for a small clinic with:
  - Appointment scheduling
  - Patient records and medical history
  - HIPAA compliance

# Project scale
scale: business  # personal|business|enterprise

# Framework and domain
framework: fastapi
domain: healthcare

# Compliance and technology
compliance:
  - HIPAA
  - SOC2
technology:
  - postgresql
  - redis

# SpecVerse libraries (enables auto-enhancement)
libraries:
  - "@specverse/domains/healthcare"
  - "@specverse/deployments/enterprise"
  - "@specverse/manifests/postgresql"
```

**Key Features:**
- 🎯 **Auto-Enhancement**: When libraries are specified in config, prompts automatically include library context
- 📦 **90% Code Reduction**: Libraries provide pre-built domain models and deployment patterns
- 🔒 **Compliance-Ready**: Built-in HIPAA, SOC2, GDPR patterns in domain libraries
- 💰 **Cost Estimates**: Token counts and cost estimates for different LLM providers

#### Operations Available

All `ai template` commands support these operations:

- **`analyse`** - Extract specifications from existing codebases
- **`create`** - Generate specifications from requirements
- **`materialise`** - Generate implementation code from specs
- **`realize`** - Generate deployment configurations

### MCP Server (AI Assistant Integration)

SpecVerse includes a universal MCP server for AI assistant integration:

```bash
# Install the MCP server
npm install -g @specverse/mcp

# Local development with Claude Desktop, Cline, etc.
specverse-mcp --mode local

# Web deployment (with orchestrator support)
specverse-mcp --mode local --enable-orchestrator
```

**Live Demo**: [https://specverse-crezbwpnl-specverse.vercel.app](https://specverse-crezbwpnl-specverse.vercel.app)

The MCP server provides:
- 🤖 **Prompt Generation**: AI-optimized prompts for specification creation
- 📚 **Library Suggestions**: Contextual SpecVerse library recommendations  
- ✅ **Validation Tools**: Real-time specification validation
- 🔄 **Orchestrator Integration**: Full workflow automation (optional)

### Start a New Project

The fastest way to get started is with the project initializer:

```bash
# Create new project with working examples
specverse init my-project
cd my-project

# The generated specs/main.specly includes:
# - Working model definitions
# - Multiple deployment scale examples
# - Comprehensive comments and guidance
```

### 📦 Available Templates

SpecVerse includes three production-ready templates for different project types:

#### **1. Default Template (Fullstack Monorepo)**
Full-stack applications with frontend and backend in a monorepo structure.

```bash
specverse init MyApp
# or explicitly
specverse init MyApp --template default
```

**Stack**: Fastify + Prisma + PostgreSQL (backend) + React + Vite + React Router (frontend)
**Structure**: npm workspaces with `backend/` and `frontend/` directories
**Best for**: Integrated full-stack applications, MVPs, startups

#### **2. Backend-Only Template**
API-only services, microservices, or when frontend is a separate project.

```bash
specverse init MyAPI --template backend-only
```

**Stack**: Fastify + Prisma + PostgreSQL
**Structure**: Standalone (no subdirectories)
**Best for**: Microservices, API services, mobile backends, data services

#### **3. Frontend-Only Template**
JAMstack applications and SPAs connecting to external APIs.

```bash
specverse init MyFrontend --template frontend-only
```

**Stack**: React + Vite + React Router + React Query
**Structure**: Standalone (no backend)
**Best for**: JAMstack apps, static sites, frontends for existing APIs, PWAs

**📖 Complete template documentation:** [templates/README.md](templates/README.md)

### Quick Test - Validate the Generated Example

```bash
# Test the generated specification
specverse validate specs/main.specly

# Generate documentation
specverse gen docs specs/main.specly

# Generate UML diagrams
specverse gen uml specs/main.specly
```

### Your First Custom Specification

Create a simple `blog-system.specly` file:

```yaml
components:
  BlogSystem:
    version: "3.4.0"
    description: "Simple blog with posts and authors"

    models:
      Author:
        attributes:
          name: String required
          email: String required unique

      Post:
        attributes:
          title: String required
          content: String required
          publishedAt: String optional
        relationships:
          author: belongsTo Author

# Optional: Add deployment (see generated examples for patterns)
deployments:
  development:
    version: "3.4.0"
    environment: development
    instances:
      controllers:
        blog-api:
          component: "BlogSystem"
          scale: 1
```

### Generate Complete System

```bash
# GROUPED COMMANDS
specverse gen yaml blog-system.specly        # Generate processed YAML
specverse gen uml blog-system.specly         # Generate UML diagrams 
specverse gen docs blog-system.specly        # Generate documentation
specverse gen views blog-system.specly       # Generate AI-optimized views
specverse gen all blog-system.specly         # Generate everything

# Development workflow commands  
specverse dev quick blog-system.specly       # Quick validation
specverse dev format blog-system.specly      # Format specification

# LEGACY COMMANDS (deprecated but supported)
specverse validate blog-system.specly        # Use: specverse dev quick
specverse process blog-system.specly         # Use: specverse gen yaml
```

### Programmatic Usage (TypeScript/JavaScript API)

Use SpecVerse programmatically in your applications:

```typescript
import { SpecVerseParser, LogicalInferenceEngine } from '@specverse/lang';
import { readFileSync } from 'fs';

// Parse specification
const schema = JSON.parse(readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8'));
const parser = new SpecVerseParser(schema);
const result = parser.parseFile(content, 'blog-system.specly');

// Run AI inference
const config = {
  logical: { generateControllers: true, generateServices: true },
  rules: {
    logicalRulesPath: 'node_modules/@specverse/lang/dist/inference-engine/rules/logical'
  }
};
const engine = new LogicalInferenceEngine(config);
await engine.loadRules();
const inference = await engine.inferLogicalSpecification(result.ast.components.flatMap(c => c.models), 'BlogSystem');

console.log('Generated:', inference.statistics.controllersGenerated, 'controllers');
```

**✅ Fully tested examples:** [API Usage Guide](docs/guides/api-usage.md) - Working JavaScript & TypeScript examples

## 🛠️ CLI Commands

### Grouped Commands
```bash
# Generate various outputs (RECOMMENDED)
specverse gen views user-spec.specly     # AI-optimized implementation specs
specverse gen yaml user-spec.specly      # Process .specly to .yaml
specverse gen uml user-spec.specly       # Generate UML diagrams  
specverse gen docs user-spec.specly      # Generate documentation
specverse gen all user-spec.specly       # Generate everything

# Development and testing workflows
specverse dev quick <file>               # Quick validation (replaces 'check')
specverse dev format <file>              # Format specification
specverse test cycle <file>              # Full test cycle

# Library management (NEW)
specverse lib search --tags auth         # Search registry libraries by tags
specverse lib search auth                # Search libraries by name/description
specverse lib info @specverse/auth       # Get detailed library information
specverse lib list                       # List cached/used libraries
specverse lib tags                       # List available tags
specverse lib cache clear                # Clear library cache
```

### Legacy Commands (still supported)
```bash
specverse validate spec.specly           # Validate specifications
specverse process spec.specly            # Convert .specly to .yaml
specverse init MyProject                 # Initialize new project (WORKS GREAT!)
```

**📖 Complete reference:** [CLI Documentation](docs/reference/cli-reference.md)

## 📚 Registry Integration

SpecVerse includes built-in integration with the **SpecVerse Community Registry** for sharing and discovering reusable components:

### 🔍 **Registry-First Import Resolution**
- Automatically resolves imports from the production registry
- Falls back to local files and NPM packages if needed
- Built-in caching for offline development

### 🏷️ **Tag-Based Library Discovery**
```bash
# Search by multiple criteria
specverse lib search --tags authentication,oauth
specverse lib search --tags business,healthcare
specverse lib search payments

# Get detailed information
specverse lib info domains-primitives-contact-yaml-contactlibrary
```

### 📦 **Library Management**
- **Cache Management**: Automatic caching with manual clear options
- **Library Listing**: View all cached and currently used libraries
- **Tag Discovery**: Browse available tags for semantic search
- **Type Classification**: Libraries organized by component, deployment, manifest types

### 🌐 **Production Registry**
- **URL**: `https://specverse-lang-registry-api.vercel.app`
- **Libraries**: 20+ production-ready libraries covering primitives, business domains, deployments
- **Import Format**: Use actual library names from registry (e.g., `domains-primitives-contact-yaml-contactlibrary`)

## 🏗️ Architecture

SpecVerse features a clean, modular architecture with unified manifest support:

```
src/
├── parser/           # YAML + Conventions parser
├── inference-engine/ # AI-powered specification inference  
├── cli/             # Command-line interface
├── generators/      # Documentation and diagram generators

tools/
├── ai-orchestrator/  # AI workflow orchestration + configuration
├── diagram-generator/ # Standalone diagram generation
├── specverse-mcp/   # MCP server for AI assistants
└── vscode-extension/ # VSCode language support
```

## 🧠 AI-Powered Inference Engine

Transform minimal models into complete architectures with **intelligent scale recognition**:

**Personal Scale Example (4x Expansion):**
```yaml
GuestBedroom:
  attributes:
    roomName: String required
    capacity: Integer required
```
→ **207 lines become 807 lines** with guest-focused features

**Enterprise Scale Example (7.6x Expansion):**
```yaml
Organization:
  attributes:
    name: String required
    contactEmail: Email required
  relationships:
    properties: hasMany Property cascade
    users: hasMany User through=OrganizationMembership
```
→ **479 lines become 3,644 lines** with multi-tenancy, RBAC, international support

## 📊 Features & Capabilities

### Core Language Features
- **YAML + Conventions**: Human-readable syntax with powerful shorthand
- **Model Definitions**: Attributes, relationships, lifecycles, profiles
- **Component Architecture**: Logical components with clear boundaries
- **Deployment Specifications**: Production-ready deployment configs

### AI Inference
- **21 Inference Rules**: Generate controllers, services, events, views
- **Context-Aware**: Relationship-aware generation with cascade handling
- **Lifecycle Integration**: State machine integration across all layers
- **Type Inference**: Complete type specifications for all components

### Development Tools
- **CLI**: Full-featured command-line interface with deployment diagram support
- **VSCode Extension**: Syntax highlighting, validation, intellisense with deployment and manifest keywords
- **Diagram Generation**: Mermaid diagrams (ER, sequence, architecture, lifecycle, deployment)
- **Documentation**: Auto-generated MD/MDX documentation

## 🧪 Testing & Quality

### Comprehensive Test Suite

SpecVerse maintains a comprehensive multi-tier testing infrastructure covering all components:

- **Core Component Tests**: Unit and integration tests via Vitest
- **Inference Engine Tests**: AI rule validation and regression testing
- **Grammar Validation**: Language syntax validation across all features
- **Example Validation**: Real-world specifications with expected failure handling
- **Integration Tests**: API, CLI, Parser, and Package integration tests
- **Tool Tests**: AI Orchestrator, MCP Server, and Configuration tests

**📖 See [CHANGELOG.md](CHANGELOG.md)** for current test counts and success rates

### Diagram Generation Status

**Unified Diagram Generator**: 15 diagram types across 5 architectural categories.

| Category | Diagram Type | Status | Description |
|----------|-------------|--------|-------------|
| **Event Flow** | event-flow-layered | ✅ Complete | 5-layer architecture with dual event bus |
| | event-flow-sequence | ✅ Complete | Temporal event sequences |
| | event-flow-swimlane | ✅ Complete | Parallel event flows |
| **Model Diagrams** | er-diagram | ✅ Complete | Entity-relationship diagram |
| | model-inheritance | ✅ Complete | Model inheritance hierarchy |
| | profile-attachment | ✅ Complete | Profile attachments to models |
| | lifecycle | ✅ Complete | State machine lifecycles |
| **Architecture** | mvc-architecture | ✅ Complete | MVC architecture overview |
| | service-architecture | ✅ Complete | Service layer architecture |
| | component-dependencies | ✅ Complete | Component dependency graph |
| **Deployment** | deployment-topology | ✅ Complete | Deployment instance visualization |
| | capability-flow | ✅ Complete | Capability provider/consumer flow |
| **Manifest** | manifest-mapping | ✅ Complete | Component → Manifest → Implementation |
| | technology-stack | ✅ Complete | Technology stack by category |
| | capability-bindings | ✅ Complete | Capability → Implementation bindings |

**Progress**: 15/15 fully implemented (100%) ✅ COMPLETE

```bash
# Generate all diagram types
specverse gen diagram myapp.specly

# Generate specific diagram type
specverse gen diagram myapp.specly -d event-flow-layered

# Use different theme
specverse gen diagram myapp.specly -t dark-mode
```

### Documentation Validation (NEW)

**Zero-Tolerance Documentation Quality**: Every code example in documentation is automatically validated.

- **266 Documentation Snippets Validated**: All code examples must pass SpecVerse validation
- **Integrated Build Process**: Documentation validation runs on every build and release
- **Smart Classification**: Automatic detection of complete specs, fragments, and configuration files
- **Comprehensive Reporting**: Detailed analysis of skipped content with categorization
- **Auto-Fix Capabilities**: Intelligent suggestions and automatic fixes for common issues

```bash
# Documentation quality assurance
npm run docs:validate-snippets    # Validate all documentation code examples
npm run verify                    # Includes documentation validation in release process
```

### Enhanced Validation Coverage
```bash
# Comprehensive specification validation
node scripts/validate-all-specly.js

# Results: ✅ 50 files validated, 98.0% pass rate (49/50)
# Covers: All .specly examples + Core library files + Complete specifications
```

### Release Pipeline
```bash
# Run complete test suite
npm test

# Results: ✅ 800 tests, 100% success rate (excluding expected failures)
```

## 📚 Examples & Documentation

### 🎯 Learning Path
Start with generated examples from `specverse init`, then explore:

- **[01-fundamentals/](examples/01-fundamentals/README.md)** - Core concepts
- **[02-profiles/](examples/02-profiles/README.md)** - Dynamic model composition  
- **[03-architecture/](examples/03-architecture/README.md)** - System design patterns
- **[04-domains/](examples/04-domains/README.md)** - Real-world applications

### 📋 Reference
- **[API Usage Guide](docs/guides/api-usage.md)** - TypeScript/JavaScript API examples and patterns
- **[CLI Reference](docs/reference/cli-reference.md)** - Complete command reference

### 📖 Documentation Structure

**Comprehensive documentation organized by purpose:**

- **[docs/guides/](docs/guides/)** - User & developer guides (installation, development, testing, troubleshooting)
- **[docs/specs/](docs/specs/)** - Language specifications and architecture (view system, inference engine, registry linter)
- **[docs/architecture/](docs/architecture/)** - System architecture (parser, code generation, inference engine, schema)
- **[docs/implementation-plans/](docs/implementation-plans/)** - Active implementation plans and progress tracking
- **[docs/plans/](docs/plans/)** - Feature and enhancement plans (view renderers, frontend scaffolding, registry linter)
- **[docs/migration/](docs/migration/)** - Migration guides for version upgrades (v3.5.0, v3.6.0, view system)
- **[docs/analysis/](docs/analysis/)** - Technical analysis documents (schema extensibility, registry realization)
- **[docs/releases/](docs/releases/)** - Release notes and version documentation
- **[docs/archive/](docs/archive/)** - Historical documentation and completed work

**📚 See [docs/README.md](docs/README.md)** for complete documentation index and navigation guide.

## 🛠️ Development

### Prerequisites
- Node.js 18+
- TypeScript 5.3+
- npm or yarn

### Setup
```bash
git clone https://github.com/SpecVerse/specverse-lang.git
cd specverse-lang
npm run setup        # Install all dependencies (root, parser, extension, docs)
npm run build        # Build all components
```

### Development Commands
```bash
npm run dev          # Build and test (full development cycle + docs validation)
npm run build        # Build all components (parser, core, CLI, extension)
npm run test         # Run unit and integration tests
npm run verify       # Complete release validation (all tests + docs validation)
npm run docs         # Generate documentation (API + diagrams)

# Documentation Quality Assurance
npm run docs:validate-snippets    # Validate all documentation code examples
npm run docs:validate-snippets:verbose    # Detailed validation output
npm run docs:validate-snippets:fix       # Auto-fix common issues
```

### VSCode Extension
Install the SpecVerse extension for enhanced development experience:
- Syntax highlighting for `.specly` files with deployment and manifest keywords
- Real-time validation and error checking
- IntelliSense for conventions, keywords, and deployment properties
- Integrated diagram preview including deployment diagrams

## 🌟 Real-World Impact

**Specification Efficiency**: Write 90% less while maintaining complete system architecture

**Example Comparison:**
- **Traditional**: 1,200+ lines of manual architecture definitions
- **SpecVerse**: 120 lines (.specly specification)
- **AI-Inferred**: Complete system architecture with full type specifications

## 📦 Package Information

- **Package**: `@specverse/lang`
- **Latest Version**: See [npm package](https://www.npmjs.com/package/@specverse/lang)
- **License**: MIT
- **Repository**: [github.com/SpecVerse/specverse-lang](https://github.com/SpecVerse/specverse-lang)
- **Documentation**: Auto-generated in `docs/` directory

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines and:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Run the test suite (`npm run release-test`)
4. Commit your changes (`git commit -m 'Add amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🚀 Getting Started

Ready to transform your development workflow? 

```bash
npm install -g @specverse/lang
specverse init my-project
cd my-project
# Edit specs/main.specly with your specification  
specverse validate specs/main.specly
specverse gen all specs/main.specly
```

Experience the future of specification-driven development with SpecVerse!