Minotaur - Advanced Compiler-Compiler Platform

Minotaur is a powerful compiler-compiler platform that revolutionizes grammar development through automated grammar generation, error-driven refinement, and comprehensive language analysis capabilities.

🚀 Key Features

Automated Grammar Generation

• Source Code Analysis: Automatically analyzes existing codebases to extract grammar patterns
• Token Pattern Recognition: Identifies keywords, operators, literals, and structural elements
• Syntax Structure Discovery: Discovers expression precedence, statement types, and control flow patterns
• Error-Driven Refinement: Uses parsing errors to iteratively improve grammar accuracy

Advanced Language Support

• Context-Aware Processing: Leverages advanced context analysis for precise grammar generation
• Multi-Language Support: Handles diverse programming languages and domain-specific languages
• Embedded Grammar Support: Processes languages embedded within other languages (e.g., JavaScript in HTML)
• Grammar File Creation Guide Compliance: Outputs standard-compliant grammar files

Interactive Development Environment

• Command-Line Interface: Comprehensive CLI for grammar generation, validation, and testing
• Real-Time Progress Tracking: Monitor grammar generation progress with detailed metrics
• Quality Assessment: Built-in validation and quality scoring for generated grammars
• Comprehensive Testing: Extensive test suites for grammar validation and refinement

📦 Installation

dotnet add package DevelApp.Minotaur

🔧 Quick Start

StepParser Integration

using Minotaur.Parser;
using Minotaur.Plugins;
using Minotaur.Core;

// Create integration with plugin manager
using var integration = new StepParserIntegration();

// Parse source code to cognitive graph
var sourceCode = "var x = 42;";
var cognitiveGraph = await integration.ParseToCognitiveGraphAsync(sourceCode);

// Edit the graph
cognitiveGraph.AddChild(new TerminalNode("comment", "// Generated"));

// Unparse back to code
var csharpPlugin = integration.PluginManager.GetPlugin("csharp");
var regeneratedCode = await csharpPlugin.UnparseAsync(cognitiveGraph);

Cognitive Graph V2 Support

Minotaur supports both V1 and V2 cognitive graphs:

• V1: Optimized for small to medium projects
• V2: Optimized for large-scale project analysis (CognitiveGraph 1.1.0+)

using Minotaur.Parser;

// Automatic version selection (default)
var autoConfig = new ParserConfiguration
{
    GraphVersion = CognitiveGraphVersion.Auto  // Selects V1 or V2 based on project size
};
using var autoIntegration = new StepParserIntegration(autoConfig);

// Force V2 for large projects
var v2Config = new ParserConfiguration
{
    GraphVersion = CognitiveGraphVersion.V2  // Always use V2
};
using var v2Integration = new StepParserIntegration(v2Config);

// Customize thresholds for auto-detection
var integration = new StepParserIntegration();
integration.SizeAnalyzer.LargeProjectLineThreshold = 5000;  // Lines of code
integration.SizeAnalyzer.LargeProjectCharThreshold = 250000;  // Characters
integration.SizeAnalyzer.LargeProjectFileThreshold = 50;  // Number of files

Plugin System

using Minotaur.Plugins;

// Built-in language plugins
using var pluginManager = new LanguagePluginManager();

// Get plugin by language
var csharpPlugin = pluginManager.GetPlugin("csharp");
var jsPlugin = pluginManager.GetPlugin("javascript");
var pythonPlugin = pluginManager.GetPlugin("python");

// Get plugin by file extension
var plugin = pluginManager.GetPluginByExtension(".cs");

// Generate backend rules for compiler-compiler
var backendRules = await csharpPlugin.GenerateCompilerBackendRulesAsync();
Console.WriteLine($"Generated {backendRules.GenerationRules.Count} rules");

🏗️ Architecture

Core Components

• StepParserIntegration: Integration with DevelApp.StepParser for parsing
• LanguagePluginManager: Runtime plugin discovery and management
• GraphUnparser: Core unparsing engine for code generation
• CognitiveGraphNode: Base node type for cognitive graph representation
• GrammarGenerator: Automated grammar discovery and generation
• SymbolicAnalysisEngine: Advanced code analysis and verification

Architectural Separation

• StepParser: Handles ALL parsing, grammar, and syntax (single source of truth)
• Plugins: Handle unparsing and compiler backend generation ONLY
• Zero-Copy Integration: Seamless data flow between parsing and unparsing

📊 Implementation Status

• ✅ StepParser Integration - Parse source code to cognitive graphs
• ✅ 111 Comprehensive Unit Tests (100% passing)
• ✅ Multi-Language Plugin System - C#, JavaScript, Python, LLVM support
• ✅ Graph Unparsing - Generate code from cognitive graphs
• ✅ Compiler Backend Rules - Generate backend code generation rules
• ✅ Grammar Generation - Automated grammar discovery and generation
• ✅ Symbolic Analysis - Advanced code analysis capabilities
• ✅ Production NuGet Dependencies

🧪 Testing

# Run all tests
dotnet test src/Minotaur.sln

# Run with coverage
dotnet test src/Minotaur.sln --collect:"XPlat Code Coverage"

🖥️ Desktop Application

Minotaur is available as a native Linux desktop application using Electron:

cd src/Minotaur.UI.Electron
npm install
npm run dev

Features:

• Native Linux application (AppImage, deb, rpm packages)
• Integrated Blazor UI with automatic server management
• Full keyboard shortcuts and menu integration
• Native file dialogs for grammar files
• Cross-platform support (x64, arm64)

See Electron Desktop App documentation for details.

📚 Documentation

User Guides

• UI Flow Documentation - Comprehensive guide to all UI pages with screenshots
• Code Development Guide - Using Minotaur for application code analysis
• Implementation Status - Track progress of visualization features

Feature Documentation

• Grammar Generation Guide - Automated grammar generation and refinement
• Electron Desktop App - Native Linux desktop application
• Electron Integration Guide - Blazor-Electron integration details
• Examples - Grammar configuration and usage examples

Historical Documentation

• Old Documentation - Outdated design documents and analysis reports

🔗 Dependencies

Core Dependencies

• DevelApp.CognitiveGraph 1.1.0 - Includes V2 cognitive graph support for massive project analysis with simplified GraphQL and fluid interface
• DevelApp.StepLexer 1.12.0 - Advanced lexical analysis with improved performance
• DevelApp.StepParser 1.12.0 - GLR parser with V2 cognitive graph integration
• DevelApp.RuntimePluggableClassFactory 2.0.1 - Dynamic plugin system

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Special Exception for Generated Output: The copyright owner of Minotaur grants you permission to link, compile, or otherwise combine the output of Minotaur with your own code and distribute the resulting combined work under terms of your choice. This exception applies to any files generated by Minotaur's code and grammar generation facilities.

🤝 Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

🏷️ Releases

• v1.0.0: Initial release with complete Minotaur implementation
• v1.0.0-preview: Pre-release versions for testing

📈 Roadmap

Completed ✅

• Core compiler-compiler functionality
• StepParser integration
• Multi-language plugin system
• Grammar generation and analysis
• Blazor-based web UI
• Phase 2: Project loading with real-time progress
• Phase 3: Linux Electron desktop application

In Progress 🚧

• Enhanced IDE integration
• Additional language plugins
• Performance optimizations

Planned 📋

• MAUI mobile applications (iOS, Android)
• Advanced visualization features
• Extended documentation
• Cloud-based grammar sharing