synthra 0.1.0

data/docs/HOW_TO_GENERATE_DOCS.md

@@ -0,0 +1,252 @@
+# How to Generate and Access YARD Documentation
+
+This guide explains how to generate and view the YARD documentation for FakeDataDSL.
+
+## Prerequisites
+
+Make sure you have the required gems installed:
+
+```bash
+bundle install
+```
+
+Or install YARD and Redcarpet manually:
+
+```bash
+gem install yard
+gem install redcarpet
+```
+
+## Generating Documentation
+
+### Basic Generation
+
+Generate documentation with default settings:
+
+```bash
+cd /path/to/fake_data_dsl
+bundle exec yard doc
+```
+
+This will:
+- Parse all Ruby files in `lib/`
+- Include markdown files from `docs/`
+- Generate HTML documentation in `doc/` directory
+
+### With Options
+
+Generate with specific options:
+
+```bash
+# Generate to custom directory
+bundle exec yard doc --output-dir public/docs
+
+# Generate with statistics
+bundle exec yard doc --stats
+
+# Generate without private methods
+bundle exec yard doc --no-private
+
+# Generate with all methods (including private)
+bundle exec yard doc --private
+```
+
+### Clean Generation
+
+Remove old documentation and regenerate:
+
+```bash
+# Remove old docs
+rm -rf doc/
+
+# Generate fresh
+bundle exec yard doc
+```
+
+## Accessing Documentation
+
+### Local HTML Files
+
+After generation, open the documentation:
+
+```bash
+# On macOS
+open doc/index.html
+
+# On Linux
+xdg-open doc/index.html
+
+# On Windows
+start doc/index.html
+```
+
+Or use a web server:
+
+```bash
+# Using Python
+cd doc
+python3 -m http.server 8000
+# Then visit http://localhost:8000
+
+# Using Ruby
+cd doc
+ruby -run -e httpd . -p 8000
+# Then visit http://localhost:8000
+```
+
+### File Structure
+
+The generated documentation structure:
+
+```
+doc/
+├── index.html              # Main documentation page
+├── _index.html            # Class/module index
+├── file_list.html         # List of all files
+├── class_list.html        # List of all classes
+├── method_list.html       # List of all methods
+├── FakeDataDSL.html      # Main module documentation
+├── FakeDataDSL/
+│   ├── Types.html         # Types module
+│   ├── Types/
+│   │   ├── Base.html      # Base type class
+│   │   ├── Uuid.html      # UUID type
+│   │   └── ...            # Other types
+│   └── ...
+└── docs/                  # Markdown documentation
+    ├── README.html
+    ├── getting_started.html
+    └── ...
+```
+
+## Documentation Features
+
+### Navigation
+
+- **Classes** - Browse all classes and modules
+- **Methods** - View all methods
+- **Files** - See source file structure
+- **Search** - Search across all documentation
+
+### Markdown Files
+
+All markdown files from `docs/` are included:
+
+- Getting Started Guide
+- DSL Reference
+- Type Reference
+- Behaviors Guide
+- Generation Modes
+- Advanced Features
+- Examples
+- API Reference
+- Best Practices
+- Troubleshooting
+
+### Code Examples
+
+All code examples are syntax-highlighted and can be copied directly.
+
+## Continuous Documentation
+
+### Pre-commit Hook
+
+Generate docs before committing:
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+bundle exec yard doc
+git add doc/
+```
+
+### CI/CD Integration
+
+Generate docs in CI:
+
+```yaml
+# .github/workflows/docs.yml
+name: Documentation
+on:
+  push:
+    branches: [main]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+      - run: bundle install
+      - run: bundle exec yard doc
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc
+```
+
+## Publishing Documentation
+
+### GitHub Pages
+
+1. Generate documentation:
+   ```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
+
+### Read the Docs
+
+1. Install `sphinx` and `sphinx-rtd-theme`
+2. Convert YARD docs to Sphinx format
+3. Configure Read the Docs
+
+## Troubleshooting
+
+### YARD Not Found
+
+```bash
+# Install YARD
+gem install yard
+
+# Or use bundle
+bundle install
+```
+
+### Redcarpet Not Found
+
+```bash
+# Install Redcarpet for markdown support
+gem install redcarpet
+```
+
+### Documentation Not Updating
+
+```bash
+# Clear cache and regenerate
+rm -rf .yardoc doc/
+bundle exec yard doc
+```
+
+### Missing Markdown Files
+
+Ensure `.yardopts` includes:
+```
+docs/**/*.md
+```
+
+## See Also
+
+- [YARD Documentation](https://yardoc.org/)
+- [YARD Guides](https://rubydoc.info/gems/yard/file/docs/GettingStarted.md)
+

data/docs/LSP.md

@@ -0,0 +1,189 @@
+# LSP Server Integration
+
+FakeDataDSL includes a full Language Server Protocol (LSP) server for IDE integration.
+
+## Features
+
+- **Go to Definition** - Jump to schema definitions from `Ref(User.id)` references
+- **Real-time Diagnostics** - See errors as you type with line/column numbers
+- **Auto-completion** - Suggestions for types, behaviors, and schemas
+- **Hover Documentation** - See type and behavior documentation on hover
+
+## Quick Start
+
+### 1. Start the LSP Server
+
+```bash
+fake_data_dsl lsp
+```
+
+The server will run on stdin/stdout, communicating via JSON-RPC.
+
+### 2. Configure Your IDE
+
+#### VS Code / Cursor
+
+Create `.vscode/settings.json`:
+
+```json
+{
+  "fakeDataDSL.lsp.enabled": true,
+  "fakeDataDSL.lsp.command": "fake_data_dsl",
+  "fakeDataDSL.lsp.args": ["lsp"]
+}
+```
+
+#### Neovim
+
+Add to your Neovim config:
+
+```lua
+require('lspconfig').fake_data_dsl.setup({
+  cmd = { 'fake_data_dsl', 'lsp' },
+  filetypes = { 'fakedatadsl', 'dsl' },
+  root_dir = require('lspconfig.util').root_pattern('.git', 'schemas'),
+})
+```
+
+## Supported LSP Features
+
+### textDocument/definition
+
+Jump to schema definitions:
+
+```dsl
+Order:
+  user_id: Ref(User.id)  # Ctrl+Click to jump to User schema
+```
+
+### textDocument/hover
+
+Hover over types and behaviors to see documentation:
+
+```dsl
+User:
+  id: uuid        # Hover to see UUID type docs
+  @latency 100ms  # Hover to see latency behavior docs
+```
+
+### textDocument/completion
+
+Auto-complete suggestions:
+
+- Types: `uuid`, `name`, `email`, etc.
+- Behaviors: `@latency`, `@failure`, `@partial_data`, etc.
+- Schemas: `User`, `Order`, `Product`, etc.
+
+### textDocument/diagnostic
+
+Real-time error reporting:
+
+- Parse errors with line/column numbers
+- Path validation errors for `copy()` references
+- Cycle detection for circular schema references
+- Field order validation errors
+
+## Architecture
+
+The LSP server reuses existing FakeDataDSL components:
+
+- **Parser** - For syntax validation and AST generation
+- **Validator** - For semantic validation (paths, cycles)
+- **Registry** - For schema lookup and cross-references
+
+No code duplication - the LSP server is a thin wrapper around existing functionality.
+
+## Troubleshooting
+
+### Server Not Starting
+
+Check that `fake_data_dsl` is in your PATH:
+
+```bash
+which fake_data_dsl
+```
+
+### No Diagnostics Appearing
+
+Ensure your `.dsl` files are recognized:
+
+1. Check file extension (`.dsl` or `.fdsl`)
+2. Verify language mode is set to "FakeDataDSL"
+3. Check LSP server logs for errors
+
+### Completion Not Working
+
+The LSP server needs schemas loaded to provide completion:
+
+1. Open a `.dsl` file with schema definitions
+2. Use `load` command in REPL to load schemas
+3. Completion will work for loaded schemas
+
+## API Reference
+
+### Server Class
+
+```ruby
+server = FakeDataDSL::LSP::Server.new(input: $stdin, output: $stdout)
+server.run
+```
+
+### Supported Methods
+
+- `initialize` - Initialize LSP server
+- `textDocument/didOpen` - Document opened
+- `textDocument/didChange` - Document changed
+- `textDocument/didClose` - Document closed
+- `textDocument/definition` - Go to definition
+- `textDocument/hover` - Hover information
+- `textDocument/completion` - Completion suggestions
+- `textDocument/diagnostic` - Validation diagnostics
+- `shutdown` - Shutdown server
+- `exit` - Exit server
+
+## Examples
+
+### Basic Setup
+
+```bash
+# Terminal 1: Start LSP server
+fake_data_dsl lsp
+
+# Terminal 2: Connect IDE to server
+# (IDE handles connection automatically)
+```
+
+### Custom Configuration
+
+```ruby
+# Custom LSP server with logging
+require 'fake_data_dsl/lsp/server'
+
+input = File.open('lsp_input.log', 'w')
+output = File.open('lsp_output.log', 'w')
+
+server = FakeDataDSL::LSP::Server.new(input: input, output: output)
+server.run
+```
+
+## Performance
+
+The LSP server is lightweight:
+
+- **Memory**: ~10MB baseline
+- **CPU**: Minimal (only validates on change)
+- **Latency**: <10ms for most operations
+
+## Limitations
+
+- Currently single-file workspace (multi-file support planned)
+- No incremental parsing (full parse on each change)
+- No semantic tokens (syntax highlighting only)
+
+## Future Enhancements
+
+- Multi-file workspace support
+- Incremental parsing
+- Semantic tokens for better highlighting
+- Code actions (quick fixes)
+- Rename refactoring