@specverse/lang

v3.5.1

Published

6 hours ago

SpecVerse Language - YAML + Conventions + AI Inference for Specification-Driven Development

0High
0Medium
0Low

cainen

davidharvey

specverse specification yaml conventions ai-inference code-generation domain-driven-design ddd architecture

SpecVerse Language

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):

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 - 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)

npm install -g @specverse/lang

Option 2: From source (for development)

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:

# 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:

# Get ready-to-use terminal prompts
cat prompts/core/base-terminal-prompt.md

Complete Workflow:

Create specification from natural language
Materialise into production-ready code
Realize deployment configurations
Deploy with generated automation scripts

📖 Complete Terminal Guide

AI Commands (v3.2.10+) 🚀

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

Quick Start with AI Config

# 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

specverse ai docs
# Displays paths to: AI schema, reference examples, prompt templates

⚙️ ai config - Generate default configuration template

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)

# 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

# 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:

# 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:

# 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

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:

# 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.

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.

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.

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

Quick Test - Validate the Generated Example

# 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:

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

# 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:

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 - Working JavaScript & TypeScript examples

🛠️ CLI Commands

Grouped Commands

# 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)

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

📚 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

# 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):

GuestBedroom:
  attributes:
    roomName: String required
    capacity: Integer required

→ 207 lines become 807 lines with guest-focused features

Enterprise Scale Example (7.6x Expansion):

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 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

# 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

# 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

# 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

# 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/ - Core concepts
02-profiles/ - Dynamic model composition
03-architecture/ - System design patterns
04-domains/ - Real-world applications

📋 Reference

API Usage Guide - TypeScript/JavaScript API examples and patterns
CLI Reference - Complete command reference

📖 Documentation Structure

Comprehensive documentation organized by purpose:

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

📚 See docs/README.md for complete documentation index and navigation guide.

🛠️ Development

Prerequisites

Node.js 18+
TypeScript 5.3+
npm or yarn

Setup

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

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
License: MIT
Repository: github.com/SpecVerse/specverse-lang
Documentation: Auto-generated in docs/ directory

🤝 Contributing

We welcome contributions! Please see our contributing guidelines and:

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Getting Started

Ready to transform your development workflow?

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!