synthra 0.1.0

data/lib/synthra/deterministic_ids.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Synthra
+  # Deterministic ID Assignment
+  #
+  # Generates stable, reproducible IDs based on context.
+  # Useful for testing and seeding where you need consistent IDs.
+  #
+  # @example DSL syntax
+  #   User:
+  #     id: uuid(variant: "user", index: $index)
+  #
+  # @example Ruby API
+  #   Synthra::DeterministicIds.uuid(variant: "user", index: 1, seed: 42)
+  #   # => "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" (always the same)
+  #
+  module DeterministicIds
+    # UUID namespace for Synthra (generated once, fixed)
+    NAMESPACE = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+
+    class << self
+      # Generate a deterministic UUID
+      #
+      # @param variant [String] variant name (e.g., "user", "order")
+      # @param index [Integer] index for sequence
+      # @param seed [Integer, nil] random seed
+      # @return [String] deterministic UUID
+      #
+      # @example
+      #   DeterministicIds.uuid(variant: "user", index: 0)
+      #   # => "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+      #
+      def uuid(variant: nil, index: 0, seed: nil)
+        input = build_input(variant, index, seed)
+        hash = Digest::SHA256.hexdigest(input)
+        
+        # Format as UUID v4
+        format_as_uuid(hash)
+      end
+
+      # Generate a deterministic integer ID
+      #
+      # @param variant [String] variant name
+      # @param index [Integer] index
+      # @param seed [Integer, nil] random seed
+      # @param max [Integer] maximum value
+      # @return [Integer] deterministic ID
+      #
+      def integer(variant: nil, index: 0, seed: nil, max: 2_147_483_647)
+        input = build_input(variant, index, seed)
+        hash = Digest::MD5.hexdigest(input)
+        
+        # Convert first 8 bytes to integer
+        hash[0, 16].to_i(16) % max
+      end
+
+      # Generate a deterministic short ID (like YouTube IDs)
+      #
+      # @param variant [String] variant name
+      # @param index [Integer] index
+      # @param seed [Integer, nil] random seed
+      # @param length [Integer] ID length
+      # @return [String] deterministic short ID
+      #
+      def short_id(variant: nil, index: 0, seed: nil, length: 11)
+        alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+        input = build_input(variant, index, seed)
+        hash = Digest::SHA256.hexdigest(input)
+        
+        result = +""
+        length.times do |i|
+          byte = hash[(i * 2), 2].to_i(16)
+          result << alphabet[byte % alphabet.length]
+        end
+        
+        result
+      end
+
+      # Generate a deterministic slug
+      #
+      # @param variant [String] variant name
+      # @param index [Integer] index
+      # @param seed [Integer, nil] random seed
+      # @param words [Integer] number of words
+      # @return [String] deterministic slug
+      #
+      def slug(variant: nil, index: 0, seed: nil, words: 3)
+        word_list = %w[
+          alpha beta gamma delta epsilon zeta eta theta iota kappa
+          lambda mu nu xi omicron pi rho sigma tau upsilon
+          able baker charlie delta echo foxtrot golf hotel india juliet
+          quick brown fox jumps over lazy dog hello world test
+        ]
+        
+        input = build_input(variant, index, seed)
+        hash = Digest::SHA256.hexdigest(input)
+        
+        selected = []
+        words.times do |i|
+          byte = hash[(i * 2), 2].to_i(16)
+          selected << word_list[byte % word_list.length]
+        end
+        
+        selected.join("-")
+      end
+
+      # Generate deterministic IDs for a batch
+      #
+      # @param count [Integer] number of IDs
+      # @param type [Symbol] ID type (:uuid, :integer, :short_id, :slug)
+      # @param variant [String] variant name
+      # @param seed [Integer, nil] random seed
+      # @return [Array<String|Integer>] array of IDs
+      #
+      def batch(count, type: :uuid, variant: nil, seed: nil, **options)
+        count.times.map do |i|
+          send(type, variant: variant, index: i, seed: seed, **options)
+        end
+      end
+
+      private
+
+      def build_input(variant, index, seed)
+        parts = [NAMESPACE]
+        parts << variant.to_s if variant
+        parts << index.to_s
+        parts << seed.to_s if seed
+        parts.join("-")
+      end
+
+      def format_as_uuid(hash)
+        # RFC 4122 v4: the leading "4" sets the version nibble; the 17th nibble must encode variant
+        # 10xx (i.e. 8/9/a/b) or strict UUID validators reject it. Mask hash[16] into that range.
+        variant = ((hash[16].to_i(16) & 0x3) | 0x8).to_s(16)
+        "#{hash[0, 8]}-#{hash[8, 4]}-4#{hash[13, 3]}-#{variant}#{hash[17, 3]}-#{hash[20, 12]}"
+      end
+    end
+  end
+
+  # Register deterministic ID types
+  module Types
+    module Core
+      # Deterministic UUID type
+      class DeterministicUuid < Base
+        def generate_random(rng, context, args)
+          variant = args[:variant]
+          index = args[:index] || context&.shared_context&.dig(:index) || 0
+          seed = args[:seed] || context[:seed]
+          
+          DeterministicIds.uuid(variant: variant, index: index, seed: seed)
+        end
+
+        def generate_edge(rng, context, args)
+          generate_random(rng, context, args)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample(["", "invalid-uuid", "12345", nil])
+        end
+
+        def generate_hostile(rng, context, args)
+          "'; DROP TABLE users;--"
+        end
+      end
+
+      # Deterministic integer ID type
+      class DeterministicId < Base
+        def generate_random(rng, context, args)
+          variant = args[:variant]
+          index = args[:index] || context&.shared_context&.dig(:index) || 0
+          seed = args[:seed] || context[:seed]
+          max = args[:max] || 2_147_483_647
+          
+          DeterministicIds.integer(variant: variant, index: index, seed: seed, max: max)
+        end
+
+        def generate_edge(rng, context, args)
+          # Edge cases: 0, 1, max
+          rng.sample([0, 1, args[:max] || 2_147_483_647])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([-1, nil, "not_a_number", 0.5])
+        end
+
+        def generate_hostile(rng, context, args)
+          -1
+        end
+      end
+
+      # Deterministic short ID type
+      class ShortId < Base
+        def generate_random(rng, context, args)
+          variant = args[:variant]
+          index = args[:index] || context&.shared_context&.dig(:index) || 0
+          seed = args[:seed] || context[:seed]
+          length = args[:length] || 11
+          
+          DeterministicIds.short_id(variant: variant, index: index, seed: seed, length: length)
+        end
+
+        def generate_edge(rng, context, args)
+          rng.sample(["", "a", "A" * (args[:length] || 11)])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, 123, "!@#$%"])
+        end
+
+        def generate_hostile(rng, context, args)
+          "<script>alert(1)</script>"
+        end
+      end
+    end
+  end
+end

data/lib/synthra/documentation_generator.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Synthra
+  # Schema Documentation Generator
+  #
+  # Generates beautiful HTML documentation from schemas.
+  #
+  # @example CLI usage
+  #   $ synthra docs schemas/ --output docs/schemas/
+  #
+  # @example Ruby usage
+  #   generator = Synthra::DocumentationGenerator.new(registry)
+  #   generator.generate_html("output/")
+  #
+  class DocumentationGenerator
+    attr_reader :registry, :options
+
+    def initialize(registry, **options)
+      @registry = registry
+      @options = {
+        title: "Synthra Schema Documentation",
+        theme: "dark"
+      }.merge(options)
+    end
+
+    # Generate HTML documentation
+    #
+    # @param output_dir [String] output directory
+    # @return [Array<String>] created file paths
+    #
+    def generate_html(output_dir)
+      FileUtils.mkdir_p(output_dir)
+      
+      files = []
+      
+      # Generate index
+      files << generate_index(output_dir)
+      
+      # Generate individual schema pages
+      @registry.names.each do |name|
+        files << generate_schema_page(name, output_dir)
+      end
+      
+      # Generate styles
+      files << generate_styles(output_dir)
+      
+      files
+    end
+
+    private
+
+    def generate_index(output_dir)
+      path = File.join(output_dir, "index.html")
+      
+      schemas = @registry.names.sort.map do |name|
+        schema = @registry.schema(name)
+        {
+          name: name,
+          field_count: schema.fields.count,
+          description: extract_description(schema)
+        }
+      end
+      
+      content = ERB.new(index_template).result(binding)
+      File.write(path, content)
+      
+      path
+    end
+
+    def generate_schema_page(name, output_dir)
+      path = File.join(output_dir, "#{to_filename(name)}.html")
+      
+      schema = @registry.schema(name)
+      sample = schema.generate(seed: 42)
+      edge_sample = schema.generate(seed: 42, mode: :edge)
+      
+      fields = schema.fields.map do |field|
+        {
+          name: field.name,
+          type: field.type_name,
+          optional: field.optional?,
+          nullable: field.respond_to?(:nullable?) ? field.nullable? : false,
+          description: field.respond_to?(:description) ? field.description : nil
+        }
+      end
+      
+      content = ERB.new(schema_template).result(binding)
+      File.write(path, content)
+      
+      path
+    end
+
+    def generate_styles(output_dir)
+      path = File.join(output_dir, "styles.css")
+      File.write(path, css_styles)
+      path
+    end
+
+    def extract_description(schema)
+      # Try to get description from first field comment or behaviors
+      nil
+    end
+
+    def to_filename(name)
+      name.gsub(/[^a-zA-Z0-9]/, "_").downcase
+    end
+
+    def index_template
+      <<~ERB
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title><%= @options[:title] %></title>
+          <link rel="stylesheet" href="styles.css">
+        </head>
+        <body>
+          <div class="container">
+            <header>
+              <h1>📚 <%= @options[:title] %></h1>
+              <p class="meta">Generated on <%= Time.now.strftime("%Y-%m-%d %H:%M:%S") %></p>
+            </header>
+            
+            <main>
+              <section class="stats">
+                <div class="stat-card">
+                  <span class="stat-value"><%= schemas.count %></span>
+                  <span class="stat-label">Schemas</span>
+                </div>
+                <div class="stat-card">
+                  <span class="stat-value"><%= schemas.sum { |s| s[:field_count] } %></span>
+                  <span class="stat-label">Total Fields</span>
+                </div>
+              </section>
+              
+              <section class="schema-list">
+                <h2>Available Schemas</h2>
+                <div class="schema-grid">
+                  <% schemas.each do |schema| %>
+                    <a href="<%= to_filename(schema[:name]) %>.html" class="schema-card">
+                      <h3><%= schema[:name] %></h3>
+                      <p class="field-count"><%= schema[:field_count] %> fields</p>
+                    </a>
+                  <% end %>
+                </div>
+              </section>
+            </main>
+            
+            <footer>
+              <p>Generated with Synthra</p>
+            </footer>
+          </div>
+        </body>
+        </html>
+      ERB
+    end
+
+    def schema_template
+      <<~ERB
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title><%= name %> | <%= @options[:title] %></title>
+          <link rel="stylesheet" href="styles.css">
+        </head>
+        <body>
+          <div class="container">
+            <header>
+              <nav>
+                <a href="index.html">← Back to Index</a>
+              </nav>
+              <h1><%= name %></h1>
+            </header>
+            
+            <main>
+              <section class="field-table">
+                <h2>Fields</h2>
+                <table>
+                  <thead>
+                    <tr>
+                      <th>Name</th>
+                      <th>Type</th>
+                      <th>Required</th>
+                      <th>Nullable</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    <% fields.each do |field| %>
+                      <tr>
+                        <td class="field-name"><%= field[:name] %></td>
+                        <td class="field-type"><code><%= field[:type] %></code></td>
+                        <td><%= field[:optional] ? '⚪ Optional' : '🔴 Required' %></td>
+                        <td><%= field[:nullable] ? '✅ Yes' : '❌ No' %></td>
+                      </tr>
+                    <% end %>
+                  </tbody>
+                </table>
+              </section>
+              
+              <section class="sample-data">
+                <h2>Sample Data (Random Mode)</h2>
+                <pre><code><%= JSON.pretty_generate(sample) %></code></pre>
+              </section>
+              
+              <section class="sample-data">
+                <h2>Sample Data (Edge Mode)</h2>
+                <pre><code><%= JSON.pretty_generate(edge_sample) %></code></pre>
+              </section>
+            </main>
+            
+            <footer>
+              <p>Generated with Synthra</p>
+            </footer>
+          </div>
+        </body>
+        </html>
+      ERB
+    end
+
+    def css_styles
+      <<~CSS
+        :root {
+          --bg: #0d1117;
+          --surface: #161b22;
+          --primary: #58a6ff;
+          --secondary: #bc8cff;
+          --success: #3fb950;
+          --warning: #d29922;
+          --danger: #f85149;
+          --text: #c9d1d9;
+          --text-muted: #8b949e;
+          --border: #30363d;
+        }
+        
+        * {
+          box-sizing: border-box;
+          margin: 0;
+          padding: 0;
+        }
+        
+        body {
+          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+          background: var(--bg);
+          color: var(--text);
+          line-height: 1.6;
+        }
+        
+        .container {
+          max-width: 1200px;
+          margin: 0 auto;
+          padding: 2rem;
+        }
+        
+        header {
+          margin-bottom: 2rem;
+          padding-bottom: 1rem;
+          border-bottom: 1px solid var(--border);
+        }
+        
+        header nav {
+          margin-bottom: 1rem;
+        }
+        
+        header nav a {
+          color: var(--primary);
+          text-decoration: none;
+        }
+        
+        header nav a:hover {
+          text-decoration: underline;
+        }
+        
+        h1 {
+          font-size: 2rem;
+          margin-bottom: 0.5rem;
+        }
+        
+        h2 {
+          font-size: 1.25rem;
+          margin-bottom: 1rem;
+          color: var(--text-muted);
+        }
+        
+        .meta {
+          color: var(--text-muted);
+          font-size: 0.875rem;
+        }
+        
+        .stats {
+          display: flex;
+          gap: 1rem;
+          margin-bottom: 2rem;
+        }
+        
+        .stat-card {
+          background: var(--surface);
+          border: 1px solid var(--border);
+          border-radius: 8px;
+          padding: 1.5rem;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+        }
+        
+        .stat-value {
+          font-size: 2rem;
+          font-weight: bold;
+          color: var(--primary);
+        }
+        
+        .stat-label {
+          color: var(--text-muted);
+          font-size: 0.875rem;
+        }
+        
+        .schema-grid {
+          display: grid;
+          grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+          gap: 1rem;
+        }
+        
+        .schema-card {
+          background: var(--surface);
+          border: 1px solid var(--border);
+          border-radius: 8px;
+          padding: 1.5rem;
+          text-decoration: none;
+          color: inherit;
+          transition: border-color 0.2s, transform 0.2s;
+        }
+        
+        .schema-card:hover {
+          border-color: var(--primary);
+          transform: translateY(-2px);
+        }
+        
+        .schema-card h3 {
+          color: var(--primary);
+          margin-bottom: 0.5rem;
+        }
+        
+        .field-count {
+          color: var(--text-muted);
+          font-size: 0.875rem;
+        }
+        
+        section {
+          margin-bottom: 2rem;
+        }
+        
+        table {
+          width: 100%;
+          border-collapse: collapse;
+          background: var(--surface);
+          border-radius: 8px;
+          overflow: hidden;
+        }
+        
+        th, td {
+          padding: 1rem;
+          text-align: left;
+          border-bottom: 1px solid var(--border);
+        }
+        
+        th {
+          background: var(--bg);
+          font-weight: 600;
+          color: var(--text-muted);
+          text-transform: uppercase;
+          font-size: 0.75rem;
+        }
+        
+        .field-name {
+          font-weight: 600;
+        }
+        
+        .field-type code {
+          background: var(--bg);
+          padding: 0.25rem 0.5rem;
+          border-radius: 4px;
+          font-family: 'JetBrains Mono', 'Fira Code', monospace;
+          color: var(--secondary);
+        }
+        
+        pre {
+          background: var(--surface);
+          border: 1px solid var(--border);
+          border-radius: 8px;
+          padding: 1rem;
+          overflow-x: auto;
+        }
+        
+        code {
+          font-family: 'JetBrains Mono', 'Fira Code', monospace;
+          font-size: 0.875rem;
+        }
+        
+        footer {
+          margin-top: 3rem;
+          padding-top: 1rem;
+          border-top: 1px solid var(--border);
+          text-align: center;
+          color: var(--text-muted);
+          font-size: 0.875rem;
+        }
+      CSS
+    end
+  end
+end