astroturf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79d39987b44a757f2689d900dd7256baef7b9d95a3206bf33384b84d57c84b9a
+  data.tar.gz: '004561878c96134cdfe94faf12bfb503985aa941e608e353b6a055f8d39073dc'
+SHA512:
+  metadata.gz: 49b5b8e9dba709aaef0bb233a04a0be9d97feac081a59a139a193b915a7b300316dfd39d5440469a12d568ac3052093f7eb9ff5930729c262f8fa9592d072dc4
+  data.tar.gz: 1d660ba73e13a93ea2c385815a7ea8283093aac4329bd5321b5b4b77d779caa5ebe523b50a72b94f23ae1b6d951ab4762f6d7ef8ba5de6d9cd10eb2647ec4965

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Bundler
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# Environment / IDE
+.DS_Store
+.vscode/
+.idea/

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Lunt <jefflunt@gmail.com>
+
+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.

data/README.md

@@ -0,0 +1,188 @@
+# Astroturf
+
+Exhaustive synthetic data generator for Rails and Ruby applications.
+
+---
+
+## Why Astroturf?
+
+Most test suites test only the happy path.
+
+Hand-written fixtures rot. Factory builders are slow and sample only a tiny fraction of valid states. When you undertake a large architectural overhaul or an automated AI-driven refactoring pass, hidden edge cases surface in production: an unhandled enum state, a `nil` middle name, an unexpected boolean combination, or a broken foreign key relationship.
+
+**Astroturf aims for total coverage of your value and combination space.**
+
+You define the dimensions in a YAML file. Astroturf computes the Cartesian product across every attribute, wires relational foreign keys, generates deterministic labels, and produces in-memory datasets in milliseconds.
+
+Use these datasets to:
+- Verify behavioral equivalence before and after sweeping refactors.
+- Generate deterministic Rails fixtures (`test/fixtures/*.yml`).
+- Seed development databases with every permutation of your domain model.
+
+---
+
+## Features
+
+- **Full Cartesian Matrix Generation**: Computes every combination across arbitrary attribute dimensions.
+- **Relational Graph Wiring**: Supports nested `has_many` and `has_one` hierarchies with automatic foreign key resolution.
+- **Two Association Modes**:
+  - `mode: combinations` (default): Generates the full Cartesian explosion of child records for every parent record.
+  - `mode: count`: Cycles or samples a fixed count of children per parent.
+- **Semantic Fixture Labels**: Automatically names records from their matrix values (e.g., `user_admin_active_true`, `user_admin_post_draft`).
+- **Pluggable Primary Keys**:
+  - Sequential integers (`1, 2, 3...`) with configurable starting points and steps.
+  - Deterministic RFC 4122 UUIDv5 strings based on record labels.
+  - Custom callable procs.
+- **Attribute Interpolation**: Dynamically references `%{label}`, `%{seq}`, `%{id}`, parent attributes (`%{parent.label}`, `%{parent.id}`), or current matrix values in string templates.
+- **Zero External Dependencies**: Pure Ruby. Generates fast in-memory hashes without requiring an active database connection.
+
+---
+
+## The Matrix Specification: `astroturf.yml`
+
+```yaml
+users:
+  primary_key: integer  # Options: integer (default), uuid, or hash options
+  matrix:
+    role: [admin, member, guest]
+    status: [active, suspended]
+    email_verified: [true, false]
+  defaults:
+    name: "User %{label}"
+    email: "%{label}@example.com"
+    created_at: 2026-01-01 00:00:00 UTC
+
+  has_many:
+    # Mode 1: Full Cartesian Explosion (Default)
+    # 12 users * 4 post combinations = 48 posts total
+    posts:
+      mode: combinations
+      matrix:
+        visibility: [public, private]
+        published: [true, false]
+      defaults:
+        title: "Post for %{parent.label}"
+
+    # Mode 2: Fixed Cardinality
+    # Each user gets exactly 2 tokens
+    tokens:
+      mode: count
+      count: 2
+      defaults:
+        token: "tok_%{parent.id}_%{seq}"
+
+  has_one:
+    profile:
+      defaults:
+        bio: "Bio for %{parent.label}"
+```
+
+---
+
+## Usage
+
+### 1. Generate In-Memory Hashes
+
+```ruby
+require "astroturf"
+
+dataset = Astroturf.load_file("astroturf.yml")
+# or: dataset = Astroturf.load(yaml_string_or_hash)
+
+# Access all generated tables and records
+dataset.tables.keys
+# => ["users", "posts", "tokens", "profiles"]
+
+# Inspect a single table
+users = dataset["users"]
+# => {
+#   "user_admin_active_true" => {
+#     "id" => 1,
+#     "role" => "admin",
+#     "status" => "active",
+#     "email_verified" => true,
+#     "name" => "User user_admin_active_true",
+#     "email" => "user_admin_active_true@example.com",
+#     "created_at" => 2026-01-01 00:00:00 UTC
+#   },
+#   ...
+# }
+
+# Total record count
+dataset.total_records
+# => 74
+```
+
+### 2. Export Rails Fixtures
+
+Generate standard Rails fixture YAML strings or write them directly to your test suite:
+
+```ruby
+# Export as a YAML string for a single table
+yaml_output = dataset.to_fixtures("users")
+
+# Write .yml fixture files directly to disk
+dataset.write_fixtures!("test/fixtures")
+# Creates:
+#   test/fixtures/users.yml
+#   test/fixtures/posts.yml
+#   test/fixtures/tokens.yml
+#   test/fixtures/profiles.yml
+```
+
+---
+
+## Primary Key Strategies
+
+### Integer Sequences (Default)
+
+```yaml
+users:
+  primary_key: integer
+  # Or with custom offset and step:
+  # primary_key:
+  #   type: integer
+  #   start_at: 1000
+  #   step: 5
+```
+
+### Deterministic UUIDs
+
+Astroturf produces RFC 4122 UUIDv5 values derived from the record's label. Generating the same dataset always produces identical UUIDs.
+
+```yaml
+accounts:
+  primary_key: uuid
+  matrix:
+    plan: [free, pro]
+```
+
+---
+
+## Running Tests
+
+Run the test suite using Rake:
+
+```bash
+bundle exec rake test
+```
+
+Or run tests directly with Ruby:
+
+```bash
+ruby -Ilib -Itest test/astroturf_test.rb
+ruby -Ilib -Itest test/matrix_test.rb
+ruby -Ilib -Itest test/primary_key_test.rb
+ruby -Ilib -Itest test/labeler_test.rb
+ruby -Ilib -Itest test/definition_test.rb
+ruby -Ilib -Itest test/generator_test.rb
+ruby -Ilib -Itest test/dataset_test.rb
+ruby -Ilib -Itest test/inflector_test.rb
+```
+
+---
+
+## License
+
+This project is available as open source under the terms of the [MIT License](LICENSE.txt).
+Authored by Jeff Lunt (<jefflunt@gmail.com>).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

data/astroturf.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "lib/astroturf/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "astroturf"
+  spec.version       = Astroturf::VERSION
+  spec.authors       = ["Jeff Lunt"]
+  spec.email         = ["jefflunt@gmail.com"]
+  spec.summary       = "Exhaustive synthetic data generator for Rails and Ruby applications"
+  spec.description   = "Astroturf generates combinatorial synthetic data graphs in memory from declarative YAML matrix specifications."
+  spec.homepage      = "https://github.com/elabs/astroturf"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 12.0"
+end

data/lib/astroturf/dataset.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Astroturf
+  class Dataset
+    attr_reader :tables
+
+    def initialize(tables = {})
+      @tables = tables
+    end
+
+    def to_h
+      @tables
+    end
+
+    def [](table_name)
+      @tables[table_name.to_s] || {}
+    end
+
+    def table_names
+      @tables.keys
+    end
+
+    def records(table_name)
+      self[table_name].values
+    end
+
+    def total_records
+      @tables.values.map(&:size).sum
+    end
+
+    def to_fixtures(table_name = nil)
+      if table_name
+        data = self[table_name]
+        data.empty? ? "{}\n" : YAML.dump(data)
+      else
+        @tables.each_with_object({}) do |(tbl, data), hash|
+          hash[tbl] = data.empty? ? "{}\n" : YAML.dump(data)
+        end
+      end
+    end
+
+    def write_fixtures!(dir_path)
+      FileUtils.mkdir_p(dir_path)
+
+      written_files = []
+      @tables.each do |tbl, data|
+        file_path = File.join(dir_path, "#{tbl}.yml")
+        File.write(file_path, data.empty? ? "{}\n" : YAML.dump(data))
+        written_files << file_path
+      end
+      written_files
+    end
+  end
+end

data/lib/astroturf/definition.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "matrix"
+require_relative "primary_key"
+require_relative "inflector"
+require_relative "errors"
+
+module Astroturf
+  class Definition
+    attr_reader :name, :matrix, :defaults, :pk_spec, :associations, :options
+
+    def self.from_hash(hash)
+      raise ConfigurationError, "Astroturf definition must be a Hash" unless hash.is_a?(Hash)
+
+      hash.map do |entity_name, config|
+        new(entity_name, config || {})
+      end
+    end
+
+    def initialize(name, config = {})
+      @name = name.to_s
+      @options = config || {}
+      @matrix = Matrix.new(config[:matrix] || config["matrix"] || {})
+      @defaults = config[:defaults] || config["defaults"] || {}
+      @pk_spec = config[:primary_key] || config["primary_key"] || :integer
+      @associations = parse_associations(config)
+    end
+
+    def singular_name
+      Inflector.singularize(@name)
+    end
+
+    def table_name
+      @options[:table_name] || @options["table_name"] || Inflector.tableize(@name)
+    end
+
+    def foreign_key_name
+      @options[:foreign_key] || @options["foreign_key"] || "#{singular_name}_id"
+    end
+
+    private
+
+    def parse_associations(config)
+      associations = []
+
+      # Parse has_many
+      raw_has_many = config[:has_many] || config["has_many"] || {}
+      raw_has_many.each do |assoc_name, assoc_config|
+        associations << build_association(:has_many, assoc_name, assoc_config)
+      end
+
+      # Parse has_one
+      raw_has_one = config[:has_one] || config["has_one"] || {}
+      raw_has_one.each do |assoc_name, assoc_config|
+        associations << build_association(:has_one, assoc_name, assoc_config)
+      end
+
+      associations
+    end
+
+    def build_association(type, assoc_name, assoc_config)
+      assoc_config ||= {}
+      mode = (assoc_config[:mode] || assoc_config["mode"] || :combinations).to_sym
+      count = assoc_config[:count] || assoc_config["count"]
+      foreign_key = assoc_config[:foreign_key] || assoc_config["foreign_key"]
+
+      Association.new(
+        type: type,
+        name: assoc_name.to_s,
+        definition: Definition.new(assoc_name, assoc_config),
+        mode: mode,
+        count: count ? count.to_i : nil,
+        foreign_key: foreign_key
+      )
+    end
+  end
+
+  class Association
+    attr_reader :type, :name, :definition, :mode, :count, :foreign_key
+
+    def initialize(type:, name:, definition:, mode: :combinations, count: nil, foreign_key: nil)
+      @type = type
+      @name = name
+      @definition = definition
+      @mode = mode
+      @count = count
+      @foreign_key = foreign_key
+    end
+
+    def has_many?
+      @type == :has_many
+    end
+
+    def has_one?
+      @type == :has_one
+    end
+  end
+end

data/lib/astroturf/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Astroturf
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class InvalidMatrixError < Error; end
+  class UnknownPrimaryKeyStrategyError < Error; end
+end

data/lib/astroturf/generator.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "dataset"
+require_relative "labeler"
+require_relative "primary_key"
+
+module Astroturf
+  class Generator
+    def self.generate(definitions)
+      new(definitions).generate
+    end
+
+    def initialize(definitions)
+      @definitions = Array(definitions)
+      @tables = Hash.new { |h, k| h[k] = {} }
+      @pk_generators = {}
+    end
+
+    def generate
+      @definitions.each do |definition|
+        generate_root(definition)
+      end
+
+      Dataset.new(@tables)
+    end
+
+    private
+
+    def pk_generator_for(definition)
+      @pk_generators[definition.table_name] ||= PrimaryKey.build(definition.pk_spec)
+    end
+
+    def generate_root(definition)
+      combos = definition.matrix.combinations
+      pk_gen = pk_generator_for(definition)
+
+      combos.each_with_index do |combo, index|
+        label = Labeler.generate(definition.singular_name, combo)
+        pk = pk_gen.next_id(label, combo)
+
+        attributes = build_attributes(
+          definition: definition,
+          combo: combo,
+          label: label,
+          pk: pk,
+          sequence: index + 1
+        )
+
+        @tables[definition.table_name][label] = attributes
+
+        generate_associations(definition, attributes, label, pk)
+      end
+    end
+
+    def generate_associations(definition, parent_attrs, parent_label, parent_pk)
+      definition.associations.each do |assoc|
+        assoc_def = assoc.definition
+        pk_gen = pk_generator_for(assoc_def)
+        fk_name = assoc.foreign_key || definition.foreign_key_name
+        child_name = assoc_def.singular_name
+
+        if assoc.has_one?
+          combo = assoc_def.matrix.combinations.first || {}
+          label = Labeler.generate(child_name, combo, parent_label: parent_label)
+          pk = pk_gen.next_id(label, combo)
+
+          child_attrs = build_attributes(
+            definition: assoc_def,
+            combo: combo,
+            label: label,
+            pk: pk,
+            parent_attrs: parent_attrs,
+            parent_label: parent_label,
+            parent_pk: parent_pk,
+            foreign_key_name: fk_name,
+            sequence: 1
+          )
+
+          @tables[assoc_def.table_name][label] = child_attrs
+          generate_associations(assoc_def, child_attrs, label, pk)
+
+        elsif assoc.has_many?
+          combos = assoc_def.matrix.combinations
+
+          if assoc.mode == :count && assoc.count
+            combos_to_generate = if combos.empty?
+                                   Array.new(assoc.count) { {} }
+                                 else
+                                   combos.cycle.take(assoc.count)
+                                 end
+
+            combos_to_generate.each_with_index do |combo, idx|
+              seq = idx + 1
+              label = Labeler.generate(child_name, combo, parent_label: parent_label, sequence: seq)
+              pk = pk_gen.next_id(label, combo)
+
+              child_attrs = build_attributes(
+                definition: assoc_def,
+                combo: combo,
+                label: label,
+                pk: pk,
+                parent_attrs: parent_attrs,
+                parent_label: parent_label,
+                parent_pk: parent_pk,
+                foreign_key_name: fk_name,
+                sequence: seq
+              )
+
+              @tables[assoc_def.table_name][label] = child_attrs
+              generate_associations(assoc_def, child_attrs, label, pk)
+            end
+          else
+            # :combinations mode (Default)
+            combos.each_with_index do |combo, idx|
+              label = Labeler.generate(child_name, combo, parent_label: parent_label)
+              pk = pk_gen.next_id(label, combo)
+
+              child_attrs = build_attributes(
+                definition: assoc_def,
+                combo: combo,
+                label: label,
+                pk: pk,
+                parent_attrs: parent_attrs,
+                parent_label: parent_label,
+                parent_pk: parent_pk,
+                foreign_key_name: fk_name,
+                sequence: idx + 1
+              )
+
+              @tables[assoc_def.table_name][label] = child_attrs
+              generate_associations(assoc_def, child_attrs, label, pk)
+            end
+          end
+        end
+      end
+    end
+
+    def build_attributes(definition:, combo:, label:, pk:, sequence:, parent_attrs: nil, parent_label: nil, parent_pk: nil, foreign_key_name: nil)
+      context = {
+        "id" => pk,
+        "label" => label,
+        "seq" => sequence
+      }
+
+      if parent_label
+        context["parent.label"] = parent_label
+        context["parent.id"] = parent_pk
+      end
+
+      # Add combo attributes into context
+      combo.each do |k, v|
+        context[k.to_s] = v
+      end
+
+      attributes = { "id" => pk }
+      attributes[foreign_key_name] = parent_pk if foreign_key_name && parent_pk
+
+      # Merge defaults with interpolation
+      definition.defaults.each do |key, val|
+        attributes[key.to_s] = resolve_value(val, context)
+      end
+
+      # Matrix values override defaults
+      combo.each do |key, val|
+        attributes[key.to_s] = val
+      end
+
+      attributes
+    end
+
+    def resolve_value(val, context)
+      case val
+      when String
+        interpolate(val, context)
+      when Proc
+        val.arity == 0 ? val.call : val.call(context)
+      else
+        val
+      end
+    end
+
+    def interpolate(template, context)
+      template.gsub(/%\{([^}]+)\}/) do
+        key = Regexp.last_match(1)
+        if context.key?(key)
+          context[key].to_s
+        else
+          "%{#{key}}"
+        end
+      end
+    end
+  end
+end

data/lib/astroturf/inflector.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Astroturf
+  module Inflector
+    PLURAL_TO_SINGULAR = [
+      [/(quiz)zes$/i, '\1'],
+      [/(matr)ices$/i, '\1ix'],
+      [/(vert|ind)ices$/i, '\1ex'],
+      [/^(ox)en$/i, '\1'],
+      [/(alias|status)es$/i, '\1'],
+      [/(octop|vir)i$/i, '\1us'],
+      [/(cris|ax|test)es$/i, '\1is'],
+      [/(shoe)s$/i, '\1'],
+      [/(o)es$/i, '\1'],
+      [/(bus)es$/i, '\1'],
+      [/([m|l])ice$/i, '\1ouse'],
+      [/(x|ch|ss|sh)es$/i, '\1'],
+      [/(m)ovies$/i, '\1ovie'],
+      [/(s)eries$/i, '\1eries'],
+      [/([^aeiouy]|qu)ies$/i, '\1y'],
+      [/([lr])ves$/i, '\1f'],
+      [/(tive)s$/i, '\1'],
+      [/(hive)s$/i, '\1'],
+      [/(li|wi|kni)ves$/i, '\1fe'],
+      [/(shea|loa|lea|thie)ves$/i, '\1f'],
+      [/(^analy)ses$/i, '\1sis'],
+      [/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i, '\1\2sis'],
+      [/([ti])a$/i, '\1um'],
+      [/(n)ews$/i, '\1ews'],
+      [/(h|j|k|l|m|n|p|q|r|s|t|v|w|x|z)zes$/i, '\1'],
+      [/s$/i, ""]
+    ].freeze
+
+    SINGULAR_TO_PLURAL = [
+      [/(quiz)$/i, '\1zes'],
+      [/^(ox)$/i, '\1en'],
+      [/([m|l])ouse$/i, '\1ice'],
+      [/(matr|vert|ind)ix|ex$/i, '\1ices'],
+      [/(x|ch|ss|sh)$/i, '\1es'],
+      [/([^aeiouy]|qu)y$/i, '\1ies'],
+      [/(hive)$/i, '\1s'],
+      [/(?:([^f])fe|([lr])f)$/i, '\1\2ves'],
+      [/sis$/i, "ses"],
+      [/([ti])um$/i, '\1a'],
+      [/(buffal|tomat)o$/i, '\1oes'],
+      [/(bu)s$/i, '\1ses'],
+      [/(alias|status)$/i, '\1es'],
+      [/(octop|vir)us$/i, '\1i'],
+      [/(ax|test)is$/i, '\1es'],
+      [/s$/i, "s"],
+      [/$/i, "s"]
+    ].freeze
+
+    IRREGULAR = {
+      "person" => "people",
+      "man" => "men",
+      "child" => "children",
+      "sex" => "sexes",
+      "move" => "moves",
+      "zombie" => "zombies"
+    }.freeze
+
+    def self.singularize(word)
+      str = word.to_s
+      return str if str.empty?
+
+      IRREGULAR.each do |singular, plural|
+        return singular.dup if str.downcase == plural
+      end
+
+      PLURAL_TO_SINGULAR.each do |rule, replacement|
+        if str =~ rule
+          return str.sub(rule, replacement)
+        end
+      end
+
+      str
+    end
+
+    def self.pluralize(word)
+      str = word.to_s
+      return str if str.empty?
+
+      IRREGULAR.each do |singular, plural|
+        return plural.dup if str.downcase == singular
+      end
+
+      SINGULAR_TO_PLURAL.each do |rule, replacement|
+        if str =~ rule
+          return str.sub(rule, replacement)
+        end
+      end
+
+      "#{str}s"
+    end
+
+    def self.tableize(word)
+      pluralize(underscore(word))
+    end
+
+    def self.underscore(word)
+      word.to_s
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
+          .downcase
+    end
+  end
+end

data/lib/astroturf/labeler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Astroturf
+  class Labeler
+    def self.generate(entity_name, coordinates = {}, parent_label: nil, sequence: nil)
+      new.generate(entity_name, coordinates, parent_label: parent_label, sequence: sequence)
+    end
+
+    def generate(entity_name, coordinates = {}, parent_label: nil, sequence: nil)
+      parts = []
+      parts << sanitize(parent_label) if parent_label && !parent_label.empty?
+      parts << sanitize(entity_name)
+
+      if coordinates && !coordinates.empty?
+        coordinates.each do |_key, val|
+          parts << sanitize(format_value(val))
+        end
+      end
+
+      parts << sequence.to_s if sequence
+
+      parts.reject(&:empty?).join("_")
+    end
+
+    def sanitize(value)
+      str = value.to_s.strip
+      # Replace spaces, hyphens, and non-alphanumeric chars with underscore
+      str = str.gsub(/[^a-zA-Z0-9]+/, "_")
+      # Collapse multiple underscores
+      str = str.gsub(/_+/, "_")
+      # Strip leading/trailing underscores
+      str = str.gsub(/\A_+|_+\z/, "")
+      str.downcase
+    end
+
+    private
+
+    def format_value(val)
+      case val
+      when nil
+        "nil"
+      when true
+        "true"
+      when false
+        "false"
+      else
+        val.to_s
+      end
+    end
+  end
+end

data/lib/astroturf/matrix.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Astroturf
+  class Matrix
+    attr_reader :dimensions
+
+    def self.combinations(dimensions)
+      new(dimensions).combinations
+    end
+
+    def initialize(dimensions = {})
+      @dimensions = normalize_dimensions(dimensions || {})
+    end
+
+    def combinations
+      return [{}] if @dimensions.empty?
+
+      keys = @dimensions.keys
+      value_arrays = @dimensions.values
+
+      return [] if value_arrays.any?(&:empty?)
+
+      value_arrays.first.product(*value_arrays[1..-1]).map do |tuple|
+        keys.zip(tuple).to_h
+      end
+    end
+
+    def size
+      return 1 if @dimensions.empty?
+      return 0 if @dimensions.values.any?(&:empty?)
+
+      @dimensions.values.map(&:size).inject(1, :*)
+    end
+    alias_method :count, :size
+
+    def empty?
+      size.zero?
+    end
+
+    private
+
+    def normalize_dimensions(raw_dimensions)
+      raise InvalidMatrixError, "Matrix dimensions must be a Hash" unless raw_dimensions.is_a?(Hash)
+
+      raw_dimensions.each_with_object({}) do |(key, values), hash|
+        hash[key.to_s] = case values
+                         when Range
+                           values.to_a
+                         when Array
+                           values
+                         else
+                           [values]
+                         end
+      end
+    end
+  end
+end

data/lib/astroturf/primary_key/integer_sequence.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Astroturf
+  module PrimaryKey
+    class IntegerSequence
+      attr_reader :current, :start_at, :step
+
+      def initialize(start_at: 1, step: 1)
+        @start_at = start_at
+        @step = step
+        @current = start_at
+      end
+
+      def next_id(_label = nil, _context = {})
+        val = @current
+        @current += @step
+        val
+      end
+
+      def reset!
+        @current = @start_at
+      end
+    end
+  end
+end

data/lib/astroturf/primary_key/uuid.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Astroturf
+  module PrimaryKey
+    class Uuid
+      DEFAULT_NAMESPACE = "astroturf"
+
+      attr_reader :namespace
+
+      def initialize(namespace: DEFAULT_NAMESPACE)
+        @namespace = namespace
+        @counter = 0
+      end
+
+      def next_id(label = nil, _context = {})
+        @counter += 1
+        name = label ? "#{label}" : "record_#{@counter}"
+        generate_uuid_v5(@namespace, name)
+      end
+
+      def reset!
+        @counter = 0
+      end
+
+      private
+
+      # Generates a standard RFC 4122 compliant UUIDv5 using SHA-1
+      def generate_uuid_v5(ns, name)
+        hash = Digest::SHA1.hexdigest("#{ns}:#{name}")
+        time_low = hash[0...8]
+        time_mid = hash[8...12]
+        time_hi = ((hash[12...16].to_i(16) & 0x0fff) | 0x5000).to_s(16).rjust(4, "0")
+        clock_seq = ((hash[16...20].to_i(16) & 0x3fff) | 0x8000).to_s(16).rjust(4, "0")
+        node = hash[20...32]
+
+        "#{time_low}-#{time_mid}-#{time_hi}-#{clock_seq}-#{node}"
+      end
+    end
+  end
+end

data/lib/astroturf/primary_key.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "primary_key/integer_sequence"
+require_relative "primary_key/uuid"
+require_relative "errors"
+
+module Astroturf
+  module PrimaryKey
+    def self.build(spec = :integer)
+      case spec
+      when :integer, "integer", nil
+        IntegerSequence.new
+      when :uuid, "uuid"
+        Uuid.new
+      when Hash
+        build_from_hash(spec)
+      else
+        if spec.respond_to?(:next_id)
+          spec
+        elsif spec.respond_to?(:call)
+          CallableAdapter.new(spec)
+        else
+          raise UnknownPrimaryKeyStrategyError, "Unsupported primary key strategy: #{spec.inspect}"
+        end
+      end
+    end
+
+    def self.build_from_hash(hash)
+      strategy = (hash[:type] || hash["type"] || :integer).to_s
+      case strategy
+      when "integer"
+        start_at = hash[:start_at] || hash["start_at"] || 1
+        step = hash[:step] || hash["step"] || 1
+        IntegerSequence.new(start_at: start_at.to_i, step: step.to_i)
+      when "uuid"
+        namespace = hash[:namespace] || hash["namespace"] || Uuid::DEFAULT_NAMESPACE
+        Uuid.new(namespace: namespace.to_s)
+      else
+        raise UnknownPrimaryKeyStrategyError, "Unsupported primary key strategy: #{strategy.inspect}"
+      end
+    end
+
+    class CallableAdapter
+      def initialize(callable)
+        @callable = callable
+      end
+
+      def next_id(label = nil, context = {})
+        if @callable.arity == 0
+          @callable.call
+        elsif @callable.arity == 1
+          @callable.call(label)
+        else
+          @callable.call(label, context)
+        end
+      end
+
+      def reset!
+        @callable.reset! if @callable.respond_to?(:reset!)
+      end
+    end
+  end
+end

data/lib/astroturf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Astroturf
+  VERSION = "0.1.0"
+end

data/lib/astroturf.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "time"
+require_relative "astroturf/version"
+require_relative "astroturf/errors"
+require_relative "astroturf/matrix"
+require_relative "astroturf/primary_key"
+require_relative "astroturf/labeler"
+require_relative "astroturf/definition"
+require_relative "astroturf/dataset"
+require_relative "astroturf/generator"
+
+module Astroturf
+  def self.load_file(path)
+    content = File.read(path)
+    load(content)
+  end
+
+  def self.load(yaml_or_hash)
+    hash = case yaml_or_hash
+           when String
+             YAML.safe_load(yaml_or_hash, permitted_classes: [Date, Time, Symbol], aliases: true)
+           when Hash
+             yaml_or_hash
+           else
+             raise ConfigurationError, "Expected YAML string or Hash, got #{yaml_or_hash.class}"
+           end
+
+    definitions = Definition.from_hash(hash)
+    Generator.generate(definitions)
+  end
+
+  class << self
+    alias_method :generate, :load
+    alias_method :build, :load
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: astroturf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff Lunt
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+description: Astroturf generates combinatorial synthetic data graphs in memory from
+  declarative YAML matrix specifications.
+email:
+- jefflunt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- astroturf.gemspec
+- lib/astroturf.rb
+- lib/astroturf/dataset.rb
+- lib/astroturf/definition.rb
+- lib/astroturf/errors.rb
+- lib/astroturf/generator.rb
+- lib/astroturf/inflector.rb
+- lib/astroturf/labeler.rb
+- lib/astroturf/matrix.rb
+- lib/astroturf/primary_key.rb
+- lib/astroturf/primary_key/integer_sequence.rb
+- lib/astroturf/primary_key/uuid.rb
+- lib/astroturf/version.rb
+homepage: https://github.com/elabs/astroturf
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/elabs/astroturf
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Exhaustive synthetic data generator for Rails and Ruby applications
+test_files: []