abstract-synthesizer 0.0.12 → 0.0.13

data/GEMINI.md

@@ -0,0 +1,13 @@
+# Project Root Directory
+
+This directory contains the core files for the `abstract-synthesizer` Ruby gem.
+
+- `README.md`: Provides a general overview of the project.
+- `abstract-synthesizer.gemspec`: Defines the gem's metadata, dependencies, and files to be included in the gem. It specifies the gem's name, version, authors, description, and development dependencies.
+- `Rakefile`: Contains Rake tasks for common development operations such as running tests (`rspec`) and linting (`rubocop`).
+- `Gemfile`, `Gemfile.lock`, `gemset.nix`, `flake.nix`, `flake.lock`: These files are related to dependency management using Bundler and Nix. `gemset.nix` is generated by `bundix` for Nix integration.
+- `.rubocop.yml`: Configuration file for RuboCop, a Ruby static code analyzer.
+- `.gitignore`: Specifies files and directories to be ignored by Git.
+- `LICENSE`: Contains the licensing information for the project (MIT License).
+
+The primary purpose of this gem is to "create resource based configuration DSL".

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    abstract-synthesizer (0.0.12)
+    abstract-synthesizer (0.0.13)
 
 GEM
   remote: https://rubygems.org/
@@ -24,7 +24,7 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.5)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -33,7 +33,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.76.1)
+    rubocop (1.77.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -41,7 +41,7 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.45.0, < 2.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.45.1)

data/docs/overview.md

@@ -0,0 +1,36 @@
+# Abstract Synthesizer Overview
+
+The `abstract-synthesizer` gem provides a Ruby DSL (Domain Specific Language) for defining hierarchical, resource-based configurations. It allows users to create structured data (manifests) using a declarative syntax, similar to how configuration files are often written.
+
+## Core Concepts
+
+- **Synthesizer**: The main component responsible for processing the DSL and building the manifest. It dynamically handles method calls to interpret resource definitions and field assignments.
+- **Manifest**: The resulting hierarchical data structure (a Ruby Hash) generated by the synthesizer, representing the defined configuration.
+- **Keys**: A predefined set of allowed methods that the synthesizer recognizes as valid resource or field names within the DSL.
+- **Bury**: A utility module that extends the `Hash` class, enabling nested assignment of values, which is fundamental for building the hierarchical manifest.
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    A[User DSL Input] --> B{AbstractSynthesizer};
+    B -- "method_missing calls" --> C[abstract_method_missing];
+    C -- "Validates method/args" --> D{Validation Logic};
+    D -- "Raises Errors" --> E[Custom Errors];
+    C -- "Builds nested hash" --> F[Bury Module (extends Hash)];
+    F --> G[Manifest (Ruby Hash)];
+    B -- "Returns" --> G;
+
+    subgraph SynthesizerFactory
+        H[create_synthesizer] --> B;
+    end
+```
+
+## How it Works
+
+1.  **Initialization**: A `Synthesizer` instance is created, optionally via the `SynthesizerFactory`, which injects the allowed `keys` for the DSL.
+2.  **DSL Evaluation**: The `synthesize` method evaluates a Ruby block or string. Inside this context, method calls are intercepted.
+3.  **Dynamic Method Handling**: The `method_missing` method (overridden in `AbstractSynthesizer` or dynamically defined by `SynthesizerFactory`) delegates to `abstract_method_missing`.
+4.  **Validation**: `abstract_method_missing` validates the called method against the allowed `keys` and checks argument counts.
+5.  **Manifest Building**: Based on the method and arguments, the synthesizer uses the `bury` method (provided by the `Bury` module) to insert data into the `translation[:manifest]` hash, creating nested structures as needed.
+6.  **Result**: The final `manifest` hash represents the structured configuration defined by the DSL.

data/docs/usage.md

@@ -0,0 +1,116 @@
+# Usage Guide
+
+This guide explains how to use the `abstract-synthesizer` gem to define resource-based configurations.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'abstract-synthesizer'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install abstract-synthesizer
+```
+
+## Basic Usage
+
+To use the synthesizer, you typically create an instance using the `SynthesizerFactory` and then define your configuration within a `synthesize` block.
+
+```ruby
+require 'abstract-synthesizer'
+
+# Define the allowed keys for your DSL
+# These keys will be the valid methods you can call in your DSL block
+resource_keys = %i[server database user]
+
+synthesizer = SynthesizerFactory.create_synthesizer(name: :my_config, keys: resource_keys)
+
+synthesizer.synthesize do
+  server :web_server, :production do
+    host 'example.com'
+    port 8080
+    ssl true
+  end
+
+  server :api_server, :development do
+    host 'localhost'
+    port 3000
+  end
+
+  database :main_db, :mysql do
+    username 'admin'
+    password 'secret'
+    host 'db.example.com'
+  end
+
+  user :admin_user do
+    name 'Administrator'
+    email 'admin@example.com'
+  end
+end
+
+# Access the generated manifest
+puts synthesizer.synthesis.inspect
+# Expected Output (simplified):
+# {
+#   :server => {
+#     :web_server => {
+#       :production => {
+#         :host => "example.com", :port => 8080, :ssl => true
+#       }
+#     },
+#     :api_server => {
+#       :development => {
+#         :host => "localhost", :port => 3000
+#       }
+#     }
+#   },
+#   :database => {
+#     :main_db => {
+#       :mysql => {
+#         :username => "admin", :password => "secret", :host => "db.example.com"
+#       }
+#     }
+#   },
+#   :user => {
+#     :admin_user => {
+#       :name => "Administrator", :email => "admin@example.com"
+#     }
+#   }
+# }
+```
+
+## DSL Structure
+
+The DSL follows a hierarchical structure:
+
+- **Resource Definition**: The top-level methods in your `synthesize` block correspond to the `keys` you provided to `create_synthesizer`. These methods can take multiple arguments, which become nested keys in the manifest.
+  ```ruby
+  resource_key :first_level_identifier, :second_level_identifier do
+    # ... fields or nested resources
+  end
+  ```
+
+- **Field Assignment**: Inside a resource block, methods without a block are treated as field assignments. They take a single argument, which is the value for that field.
+  ```ruby
+  field_name 'field_value'
+  another_field 123
+  ```
+
+## Error Handling
+
+The gem provides specific error classes for common issues:
+
+- `InvalidSynthesizerKeyError`: Raised when you try to use a method in your DSL that was not included in the `keys` provided to `SynthesizerFactory.create_synthesizer`.
+- `TooManyFieldValuesError`: Raised when a field assignment method receives more than one argument.
+- `NotEnoughResourceKeys`: Raised when a resource definition does not receive the expected number of arguments (e.g., if a top-level resource expects two identifiers but only one is provided).

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1739319052,
-        "narHash": "sha256-L8Tq1dnW96U70vrNpCCGCLHz4rX1GhNRCrRI/iox9wc=",
+        "lastModified": 1751031243,
+        "narHash": "sha256-LE6HorMxlsjj0sJ5MzV0UMAQzzG2R438rVFjSM9/LCU=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "83a2581c81ff5b06f7c1a4e7cc736a455dfcf7b4",
+        "rev": "618b6ce64508a2c821111fffc3f4153c6675acef",
         "type": "github"
       },
       "original": {
@@ -59,11 +59,11 @@
         "nixpkgs": "nixpkgs_2"
       },
       "locked": {
-        "lastModified": 1725677741,
-        "narHash": "sha256-CySXGzqycagfrWdcTwzM3Zo1MMm9uUtePYER9BvrW8s=",
+        "lastModified": 1744623277,
+        "narHash": "sha256-0HWA2YD9v71SHyMF11PKnVJcHnrHhRLHDCldlUbzYII=",
         "owner": "inscapist",
         "repo": "ruby-nix",
-        "rev": "1f3756f8a713171bf891b39c0d3b1fe6d83a4a63",
+        "rev": "43964ced23803f49e2d307fbbfd4e03ed23760c0",
         "type": "github"
       },
       "original": {

data/gemset.nix

@@ -6,7 +6,7 @@
       path = ./.;
       type = "path";
     };
-    version = "0.0.12";
+    version = "0.0.13";
   };
   ast = {
     groups = ["default" "development"];
@@ -146,10 +146,10 @@
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "0n1rlagplpcgp41s3r68z01539aivwj0cn3v19hq4p3pgdmibnpr";
+      sha256 = "18sgga9zjrd5579m9rpb78l7yn9a0bjzwz51z5kiq4y6jwl6hgxb";
       type = "gem";
     };
-    version = "3.13.4";
+    version = "3.13.5";
   };
   rspec-expectations = {
     dependencies = ["diff-lcs" "rspec-support"];
@@ -189,10 +189,10 @@
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "1rz0wwhxy6rv0kk2m8jp77fbhwgs7m01p2yys9bj3kwl0xsjsnp1";
+      sha256 = "1h48rhmp178ppzc4ybfj42a2savs4bxgy3bvw95i4ypgfm2hndhz";
       type = "gem";
     };
-    version = "1.76.1";
+    version = "1.77.0";
   };
   rubocop-ast = {
     dependencies = ["parser" "prism"];

data/lib/GEMINI.md

@@ -0,0 +1,26 @@
+# lib/ Directory
+
+This directory contains the main source code for the `abstract-synthesizer` gem.
+
+- `abstract-synthesizer.rb`: This is the primary entry point for the gem. It defines the `AbstractSynthesizer` class and the `SynthesizerFactory` module.
+
+## AbstractSynthesizer Class
+
+The `AbstractSynthesizer` class is designed to create a resource-based configuration DSL (Domain Specific Language). It allows users to define hierarchical data structures (manifests) using a Ruby-like syntax.
+
+Key features and methods:
+- `initialize`: Initializes the synthesizer with a `translation` hash, which stores the `ancestors` (current path in the manifest), `manifest` (the generated data structure), and `context`.
+- `clear!`: Resets the `manifest`.
+- `synthesis`: Returns the generated `manifest`.
+- `synthesize(content = nil, &block)`: Evaluates the provided content or block to build the manifest. This is where the DSL is processed.
+- `manifest`: An alias for `synthesis`.
+- `valid_method?(method, keys)`: Internal method to check if a method call is valid within the current context (resource definition or field assignment).
+- `validate_method(method, keys)`: Raises `InvalidSynthesizerKeyError` if a method is not valid.
+- `validate_args(args)`: Validates the number of arguments based on the current context, raising `NotEnoughResourceKeys` or `TooManyFieldValuesError`.
+- `abstract_method_missing(method, keys, *args)`: This is the core of the DSL. It dynamically handles method calls, interpreting them as resource keys or field assignments, and building the `translation[:manifest]` accordingly. It uses the `Bury` module for nested data insertion.
+
+## SynthesizerFactory Module
+
+This module provides a factory method to create instances of `AbstractSynthesizer`.
+
+- `create_synthesizer(name:, keys:)`: Creates a new `AbstractSynthesizer` instance and dynamically defines its `method_missing` method. This `method_missing` delegates to `abstract_method_missing` within the `AbstractSynthesizer` instance, passing the allowed `keys` for the DSL. This allows for flexible definition of the DSL structure based on the provided `keys`.

data/lib/abstract-synthesizer/GEMINI.md

@@ -0,0 +1,5 @@
+# lib/abstract-synthesizer/ Directory
+
+This directory contains modules and core components that support the `AbstractSynthesizer`.
+
+- `version.rb`: Defines the version number of the `abstract-synthesizer` gem within the `Meta` module. This file is used by the `gemspec` to set the gem's version.

data/lib/abstract-synthesizer/errors/GEMINI.md

@@ -0,0 +1,7 @@
+# lib/abstract-synthesizer/errors/ Directory
+
+This directory contains custom error classes used by the `abstract-synthesizer` gem. These errors are raised when specific conditions are not met during the synthesis process, providing clear feedback to the user.
+
+- `invalid_synthesizer_key_error.rb`: Defines `InvalidSynthesizerKeyError`. This error is raised when the synthesizer attempts to process a key (method call) that is not defined or recognized as a valid resource key within the DSL.
+- `not_enough_resource_keys.rb`: Defines `NotEnoughResourceKeys`. This error is raised when an insufficient number of resource keys are provided, typically during the initial definition of a resource.
+- `too_many_field_values.rb`: Defines `TooManyFieldValuesError`. This error is raised when too many field values are provided for a given field, indicating an incorrect usage of the DSL.

data/lib/abstract-synthesizer/primitives/GEMINI.md

@@ -0,0 +1,5 @@
+# lib/abstract-synthesizer/primitives/ Directory
+
+This directory contains primitive modules or classes that provide fundamental functionalities used by the `abstract-synthesizer`.
+
+- `bury.rb`: Defines the `Bury` module. This module extends the `Hash` class with a `bury` method. The `bury` method allows for nested assignment of values within a hash, creating intermediate hashes as needed. This is crucial for building the hierarchical `manifest` within the `AbstractSynthesizer`.

data/lib/abstract-synthesizer/version.rb

@@ -1,3 +1,3 @@
 module Meta
-  VERSION = %(0.0.12).freeze
+  VERSION = %(0.0.13).freeze
 end

data/lib/abstract-synthesizer.rb

@@ -78,7 +78,7 @@ class AbstractSynthesizer
     method = method.to_sym
 
     validate_method(method, keys)
-    # validate_args(args)
+    validate_args(args)
 
     keys.each do |key|
       if key.eql?(translation[:context])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abstract-synthesizer
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.13
 platform: ruby
 authors:
 - drzzln@protonmail.com
@@ -60,20 +60,28 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".nix_shell_env.sh"
 - ".rubocop.yml"
+- GEMINI.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
 - README.md
 - Rakefile
 - abstract-synthesizer.gemspec
+- docs/overview.md
+- docs/usage.md
 - flake.lock
 - flake.nix
 - gemset.nix
+- lib/GEMINI.md
 - lib/abstract-synthesizer.rb
+- lib/abstract-synthesizer/GEMINI.md
+- lib/abstract-synthesizer/errors/GEMINI.md
 - lib/abstract-synthesizer/errors/invalid_synthesizer_key_error.rb
 - lib/abstract-synthesizer/errors/not_enough_resource_keys.rb
 - lib/abstract-synthesizer/errors/too_many_field_values.rb
+- lib/abstract-synthesizer/primitives/GEMINI.md
 - lib/abstract-synthesizer/primitives/bury.rb
 - lib/abstract-synthesizer/version.rb
 homepage: https://github.com/drzln/abstract-synthesizer