synthra 0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,307 @@
+# Contributing to FakeDataDSL
+
+Thank you for your interest in contributing to FakeDataDSL! This document provides guidelines and information for contributors.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Code Style](#code-style)
+- [Testing Guidelines](#testing-guidelines)
+- [Documentation](#documentation)
+
+## Code of Conduct
+
+This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/fake_data_dsl.git
+   cd fake_data_dsl
+   ```
+3. Add the upstream remote:
+   ```bash
+   git remote add upstream https://github.com/talaatmagdyx/fake_data_dsl.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.1.0 or higher
+- Bundler 2.0+
+
+### Installation
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests to verify setup
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+### Running the CLI locally
+
+```bash
+# From the project root
+bundle exec exe/fake_data_dsl --help
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before creating a bug report:
+
+1. Check the [existing issues](https://github.com/talaatmagdyx/fake_data_dsl/issues)
+2. Ensure you're using the latest version
+3. Collect information about the bug:
+   - Stack trace
+   - Ruby version (`ruby --version`)
+   - Gem version (`bundle show fake_data_dsl`)
+   - Your operating system
+   - Steps to reproduce
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:
+
+- A clear and descriptive title
+- A detailed description of the proposed functionality
+- Examples of how the feature would be used
+- Why this enhancement would be useful
+
+### Adding New Types
+
+To add a new data type:
+
+1. Create a new file in `lib/fake_data_dsl/types/` in the appropriate domain folder
+2. Inherit from `FakeDataDSL::Types::Base`
+3. Implement `generate_random`, `generate_edge`, and `generate_invalid` methods
+4. Register the type in `lib/fake_data_dsl.rb` in `register_builtin_types!`
+5. Add tests in `spec/types/`
+6. Document in `tech_docs/dsl/core_types.md`
+
+Example:
+
+```ruby
+# lib/fake_data_dsl/types/personal_names/nickname.rb
+module FakeDataDSL
+  module Types
+    module PersonalNames
+      class Nickname < Base
+        def generate_random(rng, context, args)
+          rng.element(["Ace", "Buddy", "Chief", "Duke", "Flash"])
+        end
+
+        def generate_edge(rng, context, args)
+          rng.element(["", "X", "A" * 100])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.element([nil, 123, [], {}])
+        end
+      end
+    end
+  end
+end
+```
+
+### Adding New Behaviors
+
+To add a new behavior:
+
+1. Create a new file in `lib/fake_data_dsl/behaviors/`
+2. Inherit from `FakeDataDSL::Behaviors::Base`
+3. Implement the `apply` method
+4. Register in `lib/fake_data_dsl/behaviors/registry.rb`
+5. Add tests and documentation
+
+### Adding New Export Formats
+
+To add a new export format:
+
+1. Create a new file in `lib/fake_data_dsl/export/`
+2. Inherit from `FakeDataDSL::Export::Base`
+3. Implement `export` and optionally `export_all` methods
+4. Register in `lib/fake_data_dsl/export.rb`
+5. Add CLI support in `lib/fake_data_dsl/cli.rb` if needed
+6. Add tests and documentation
+
+## Pull Request Process
+
+1. Create a new branch from `main`:
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. Make your changes and commit:
+   ```bash
+   git add .
+   git commit -m "feat: add new feature X"
+   ```
+
+3. Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+   - `feat:` - New features
+   - `fix:` - Bug fixes
+   - `docs:` - Documentation changes
+   - `style:` - Code style changes (formatting, etc.)
+   - `refactor:` - Code refactoring
+   - `test:` - Adding or updating tests
+   - `chore:` - Maintenance tasks
+
+4. Ensure all tests pass:
+   ```bash
+   bundle exec rspec
+   ```
+
+5. Ensure code style compliance:
+   ```bash
+   bundle exec rubocop
+   ```
+
+6. Update documentation if needed
+
+7. Push your branch and create a Pull Request
+
+### PR Requirements
+
+- [ ] Tests pass
+- [ ] RuboCop passes
+- [ ] New code has test coverage
+- [ ] Documentation updated (if applicable)
+- [ ] CHANGELOG.md updated (for user-facing changes)
+
+## Code Style
+
+We follow the Ruby Style Guide with some customizations. RuboCop is configured to enforce these rules.
+
+### Key Guidelines
+
+- Use 2 spaces for indentation
+- Use `frozen_string_literal` pragma
+- Maximum line length: 120 characters
+- Document public methods with YARD
+- Prefer explicit over implicit
+- Keep methods small and focused
+
+### Example
+
+```ruby
+# frozen_string_literal: true
+
+module FakeDataDSL
+  module Example
+    # Generate a random example value
+    #
+    # @param count [Integer] number of values to generate
+    # @return [Array<String>] generated values
+    #
+    # @example
+    #   generate_examples(3)
+    #   # => ["example1", "example2", "example3"]
+    #
+    def generate_examples(count)
+      count.times.map { |i| "example#{i + 1}" }
+    end
+  end
+end
+```
+
+## Testing Guidelines
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific file
+bundle exec rspec spec/types/core_types_spec.rb
+
+# Run with coverage
+bundle exec rspec --coverage
+```
+
+### Writing Tests
+
+- Place tests in `spec/` mirroring the `lib/` structure
+- Use descriptive `describe` and `it` blocks
+- Test edge cases and error conditions
+- Use factories or fixtures for complex data
+
+### Example Test
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe FakeDataDSL::Types::PersonalNames::Nickname do
+  subject(:generator) { described_class.new }
+
+  describe "#generate_random" do
+    it "returns a string" do
+      result = generator.generate_random(rng, context, {})
+      expect(result).to be_a(String)
+    end
+
+    it "returns consistent results with same seed" do
+      rng1 = FakeDataDSL::Generator::RNG.new(42)
+      rng2 = FakeDataDSL::Generator::RNG.new(42)
+      
+      result1 = generator.generate_random(rng1, context, {})
+      result2 = generator.generate_random(rng2, context, {})
+      
+      expect(result1).to eq(result2)
+    end
+  end
+
+  describe "#generate_edge" do
+    it "returns edge case values" do
+      result = generator.generate_edge(rng, context, {})
+      expect(result).to satisfy { |v| v.empty? || v.length == 1 || v.length >= 100 }
+    end
+  end
+end
+```
+
+## Documentation
+
+### Code Documentation
+
+- Use YARD for API documentation
+- Document all public methods
+- Include usage examples
+- Document parameters and return values
+
+### User Documentation
+
+- Update `tech_docs/` for user-facing features
+- Include examples that users can copy/paste
+- Keep tutorials up to date
+
+### Generating Docs
+
+```bash
+# Generate YARD documentation
+bundle exec yard doc
+```
+
+## Questions?
+
+If you have questions about contributing:
+
+1. Check existing documentation
+2. Search existing issues
+3. Open a new issue with the "question" label
+
+Thank you for contributing to FakeDataDSL! 🎉

data/DOCUMENTATION.md

@@ -0,0 +1,204 @@
+# Documentation Guide
+
+This guide explains how to generate and view the documentation for FakeDataDSL.
+
+## Prerequisites
+
+First, install the documentation dependencies:
+
+```bash
+bundle install
+```
+
+This will install:
+- `yard` - YARD documentation generator
+- `redcarpet` - Markdown processor for YARD
+- `webrick` - Web server for viewing docs
+
+## Generating Documentation
+
+### Method 1: Using Rake (Recommended)
+
+```bash
+# Generate documentation
+bundle exec rake docs
+
+# This will:
+# - Generate HTML documentation in the doc/ directory
+# - Include README, CHANGELOG, and all code documentation
+# - Show a message with the location
+```
+
+After generation, open `doc/index.html` in your browser.
+
+### Method 2: Using YARD Directly
+
+```bash
+# Generate documentation
+bundle exec yard doc
+
+# Generate with specific options
+bundle exec yard doc --no-cache --private
+```
+
+### Method 3: View Documentation Online
+
+If the gem is published to RubyGems, documentation is automatically available at:
+- [RubyDoc.info](https://www.rubydoc.info/gems/fake_data_dsl)
+- [RubyGems.org](https://rubygems.org/gems/fake_data_dsl)
+
+## Viewing Documentation Locally
+
+### Option 1: Open HTML Files
+
+After generating docs:
+
+```bash
+# macOS
+open doc/index.html
+
+# Linux
+xdg-open doc/index.html
+
+# Windows
+start doc/index.html
+```
+
+### Option 2: YARD Server (Live Reload)
+
+Start a local documentation server with auto-reload:
+
+```bash
+# Using Rake
+bundle exec rake docs_server
+
+# Or directly
+bundle exec yard server --reload
+```
+
+Then open http://localhost:8808 in your browser.
+
+The server will automatically reload when you make changes to the code.
+
+## Documentation Structure
+
+The generated documentation includes:
+
+- **README.md** - Full project documentation and usage guide
+- **API Reference** - All classes, modules, and methods
+- **Examples** - Code examples from YARD comments
+- **Type System** - All built-in types with descriptions
+- **Behaviors** - All simulation behaviors
+- **Configuration** - Configuration options
+- **Error Classes** - All error types
+
+## Writing Documentation
+
+### YARD Comments
+
+All public methods should have YARD documentation:
+
+```ruby
+# Generates a UUID value.
+#
+# Supports UUID versions 4, 6, and 7 for different use cases.
+# Version 4 is random, version 6/7 are time-sortable.
+#
+# @param rng [Generator::RNG] random number generator
+# @param args [Hash] generation arguments
+# @option args [Integer] :version UUID version (4, 6, or 7)
+# @return [String] UUID string in standard format
+#
+# @example Generate UUID v4
+#   uuid = type.generate_random(rng, {})
+#   # => "550e8400-e29b-41d4-a716-446655440000"
+#
+# @see https://www.rfc-editor.org/rfc/rfc9562 RFC 9562 - UUID
+#
+def generate_random(rng, args)
+  # Implementation
+end
+```
+
+### Documentation Tags
+
+Common YARD tags:
+
+- `@param` - Method parameters
+- `@return` - Return value
+- `@option` - Hash options
+- `@example` - Usage examples
+- `@raise` - Exceptions raised
+- `@see` - Related references
+- `@since` - Version introduced
+- `@deprecated` - Deprecated methods
+- `@api` - API visibility (public/private)
+
+## Updating Documentation
+
+After making code changes:
+
+1. Update YARD comments in code
+2. Regenerate documentation: `bundle exec rake docs`
+3. Review changes in `doc/index.html`
+4. Commit documentation updates with code changes
+
+## Documentation Files
+
+- **README.md** - Main project documentation
+- **CHANGELOG.md** - Version history
+- **CONTRIBUTING.md** - Contribution guidelines
+- **CODE_OF_CONDUCT.md** - Community standards
+- **DOCUMENTATION.md** - This file
+- **.yardopts** - YARD configuration
+
+## Troubleshooting
+
+### Documentation Not Generating
+
+```bash
+# Check if YARD is installed
+bundle exec yard --version
+
+# Clear YARD cache
+rm -rf .yardoc doc/
+
+# Regenerate
+bundle exec rake docs
+```
+
+### Missing Examples
+
+Ensure examples in YARD comments use the `@example` tag:
+
+```ruby
+# @example Basic usage
+#   schema = FakeDataDSL.load('user.dsl')
+#   user = schema.generate
+```
+
+### Private Methods Not Showing
+
+By default, private methods are hidden. To include them:
+
+```bash
+bundle exec yard doc --private
+```
+
+Or update `.yardopts` to include `--private`.
+
+## Publishing Documentation
+
+When releasing a new version:
+
+1. Generate documentation: `bundle exec rake docs`
+2. Commit the `doc/` directory (if hosting yourself)
+3. Push to RubyGems (auto-publishes to RubyDoc.info)
+4. Update any external documentation sites
+
+## Additional Resources
+
+- [YARD Documentation](https://yardoc.org/)
+- [YARD Tags Reference](https://www.rubydoc.info/gems/yard/file/docs/Tags.md)
+- [RubyDoc.info](https://www.rubydoc.info/)
+

data/DOCUMENTATION_GUIDE.md

@@ -0,0 +1,194 @@
+# FakeDataDSL Documentation Guide
+
+## 📚 Documentation Structure
+
+The FakeDataDSL documentation consists of:
+
+1. **YARD Documentation** - Auto-generated from code comments
+2. **Markdown Guides** - Comprehensive guides in `docs/` folder
+3. **API Reference** - Programmatic API documentation
+
+## 🚀 Quick Start
+
+### Generate Documentation
+
+```bash
+# Navigate to project directory
+cd /path/to/fake_data_dsl
+
+# Generate YARD documentation
+bundle exec yard doc
+```
+
+### View Documentation
+
+```bash
+# Open in browser (macOS)
+open doc/index.html
+
+# Open in browser (Linux)
+xdg-open doc/index.html
+
+# Or use a local server
+cd doc
+python3 -m http.server 8000
+# Visit http://localhost:8000
+```
+
+## 📖 Documentation Files
+
+All documentation is in the `docs/` folder:
+
+- **README.md** - Documentation index
+- **getting_started.md** - Quick start guide
+- **dsl_reference.md** - Complete DSL syntax
+- **type_reference.md** - All available types
+- **behaviors.md** - Behaviors guide
+- **generation_modes.md** - Generation modes
+- **advanced_features.md** - Advanced features
+- **examples.md** - Real-world examples
+- **api_reference.md** - Programmatic API
+- **best_practices.md** - Best practices
+- **troubleshooting.md** - Common issues
+- **HOW_TO_GENERATE_DOCS.md** - This guide
+- **QUICK_REFERENCE.md** - Quick reference card
+
+## 🔧 Configuration
+
+The `.yardopts` file configures YARD:
+
+- Includes markdown files from `docs/`
+- Sets output directory to `doc/`
+- Configures markup provider (Redcarpet)
+
+## 📝 Adding Documentation
+
+### Add New Guide
+
+1. Create markdown file in `docs/`:
+   ```bash
+   touch docs/my_guide.md
+   ```
+
+2. Add to `docs/README.md` table of contents
+
+3. Regenerate docs:
+   ```bash
+   bundle exec yard doc
+   ```
+
+### Update Code Documentation
+
+1. Add YARD comments to code:
+   ```ruby
+   # My method
+   #
+   # @param arg [String] description
+   # @return [Integer] description
+   #
+   def my_method(arg)
+     # ...
+   end
+   ```
+
+2. Regenerate docs:
+   ```bash
+   bundle exec yard doc
+   ```
+
+## 🌐 Publishing
+
+### GitHub Pages
+
+1. Generate docs:
+   ```bash
+   bundle exec yard doc
+   ```
+
+2. Push to `gh-pages` branch:
+   ```bash
+   git checkout --orphan gh-pages
+   git rm -rf .
+   cp -r doc/* .
+   git add .
+   git commit -m "Update documentation"
+   git push origin gh-pages
+   ```
+
+3. Enable GitHub Pages in repository settings
+
+## 📊 Documentation Stats
+
+Current documentation coverage:
+- **94.37% documented**
+- 154 classes (0 undocumented)
+- 588 methods (9 undocumented)
+- 99 constants (36 undocumented)
+
+## 🔍 Accessing Documentation
+
+### Local Access
+
+```bash
+# Generate
+bundle exec yard doc
+
+# View
+open doc/index.html
+```
+
+### Online Access
+
+If published to GitHub Pages:
+- Visit: `https://yourusername.github.io/fake_data_dsl/`
+
+## 📚 Documentation Sections
+
+### For Users
+
+- [Getting Started](docs/getting_started.md)
+- [DSL Reference](docs/dsl_reference.md)
+- [Type Reference](docs/type_reference.md)
+- [Examples](docs/examples.md)
+
+### For Developers
+
+- [API Reference](docs/api_reference.md)
+- [Advanced Features](docs/advanced_features.md)
+- [Best Practices](docs/best_practices.md)
+
+### For Troubleshooting
+
+- [Troubleshooting](docs/troubleshooting.md)
+- [Best Practices](docs/best_practices.md)
+
+## 🛠️ Troubleshooting
+
+### YARD Not Found
+
+```bash
+gem install yard
+# or
+bundle install
+```
+
+### Documentation Not Updating
+
+```bash
+rm -rf .yardoc doc/
+bundle exec yard doc
+```
+
+### Missing Markdown Files
+
+Ensure `.yardopts` includes:
+```
+docs/**/*.md
+```
+
+## 📞 Need Help?
+
+- Check [Troubleshooting](docs/troubleshooting.md)
+- Review [Examples](docs/examples.md)
+- Open an issue on GitHub
+

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Synthra Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+