amoskeag-rb 0.1.1c

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbaa0e7ea45334ed0a0e3963aacc1f4c37183ab440a64ce1434f5973d1978b66
+  data.tar.gz: e65ac6e2c7cf6ee14a0907021847116f4f2ceea86b7214d9fd2e0a5073a8fe44
+SHA512:
+  metadata.gz: 686fcac6a64a05575ebbefb37381dcf8faadac4cd20866a438cc5fd9fb7036e01e2019c3a2387d9bf125e2c3f4789e502d87ff3b9f87a349bac55b8cb79f79f2
+  data.tar.gz: 916788a2f717bbea591429ff371cc8dd6404bc7ec7e778aca98ee119d6b0b396ddce16685a032a3fa9893aab78ecee8bd4f7ecb75f7c84fd4f220446e4b2c2b1

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to the amoskeag-rb gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-20
+
+### Added
+- Initial release of amoskeag-rb gem
+- Native Ruby bindings to Amoskeag DSL
+- FFI layer using statically compiled Rust library
+- Core API methods:
+  - `Amoskeag.compile(source, symbols)` - Compile programs with symbol validation
+  - `Amoskeag.evaluate(program, data)` - Evaluate compiled programs
+  - `Amoskeag.eval_expression(source, data, symbols)` - Compile and evaluate in one step
+- Full support for all Amoskeag data types:
+  - Numbers, Strings, Booleans, Nil
+  - Arrays and Dictionaries
+  - Symbols with compile-time validation
+- Ruby-friendly API with automatic type conversion
+- Thread-safe compiled programs
+- Comprehensive error handling with CompileError and EvalError
+- Complete documentation and examples
+- JSON-based marshalling between Ruby and native code
+
+### Features
+- Business Rules Engine capabilities
+- Template Engine functionality
+- Spreadsheet Formula support
+- 60+ standard library functions
+- Excel-compatible financial functions
+- Safe navigation (nil-safe property access)
+- Pure functional evaluation (no side effects)
+- Security-first design (immune to code injection)
+
+[0.1.0]: https://github.com/durable-oss/amoskeag-rb/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,335 @@
+# Amoskeag Ruby Gem
+
+Native Ruby bindings for [Amoskeag](https://github.com/durable-oss/amoskeag) - a secure, purely functional DSL for business rules, templates, and spreadsheet formulas.
+
+## Features
+
+- **Security-First Design**: Immune to code injection attacks (SSTI, RCE)
+- **Purely Functional**: No side effects, no mutation, no I/O
+- **Static Validation**: Symbols and functions validated at compile-time
+- **High Performance**: Native Rust implementation with zero-copy FFI
+- **Rich Standard Library**: 60+ built-in functions for strings, numbers, collections, and finance
+- **Multiple Use Cases**:
+  - Business Rules Engine (insurance, loans, eligibility)
+  - Template Engine (secure alternative to ERB)
+  - Spreadsheet Formulas (Excel-compatible financial functions)
+
+## Installation
+
+### Prerequisites
+
+- Ruby 2.7 or higher
+- Rust and Cargo (for building the native extension)
+
+### Install from source
+
+```bash
+gem build amoskeag-rb.gemspec
+gem install amoskeag-rb-0.1.0.gem
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'amoskeag-rb', path: 'path/to/amoskeag-rb'
+```
+
+## Quick Start
+
+```ruby
+require 'amoskeag-rb'
+
+# Basic arithmetic
+Amoskeag.eval_expression("2 + 2", {})
+# => 4.0
+
+# Using variables
+Amoskeag.eval_expression("user.age * 2", { "user" => { "age" => 25 } })
+# => 50.0
+
+# String operations with pipe
+Amoskeag.eval_expression('"hello world" | upcase', {})
+# => "HELLO WORLD"
+
+# Business rules with symbols
+code = "if user.age >= 18 :adult else :minor end"
+Amoskeag.eval_expression(code, { "user" => { "age" => 25 } }, [:adult, :minor])
+# => :adult
+```
+
+## Core Concepts
+
+### Compile Once, Evaluate Many
+
+For best performance, compile programs once and evaluate them multiple times:
+
+```ruby
+# Compile the program (with symbol validation)
+program = Amoskeag.compile(
+  "if score >= 90 :A else :B end",
+  [:A, :B, :C, :D, :F]
+)
+
+# Evaluate with different data
+Amoskeag.evaluate(program, { "score" => 95 })  # => :A
+Amoskeag.evaluate(program, { "score" => 85 })  # => :B
+```
+
+### Data Types
+
+Amoskeag supports seven fundamental types:
+
+```ruby
+# Numbers (64-bit float)
+Amoskeag.eval_expression("42", {})  # => 42.0
+
+# Strings
+Amoskeag.eval_expression('"hello"', {})  # => "hello"
+
+# Booleans
+Amoskeag.eval_expression("true and false", {})  # => false
+
+# Nil
+Amoskeag.eval_expression("nil", {})  # => nil
+
+# Arrays
+Amoskeag.eval_expression("[1, 2, 3]", {})  # => [1.0, 2.0, 3.0]
+
+# Dictionaries (hashes)
+Amoskeag.eval_expression('{"name": "Alice", "age": 30}', {})
+# => {"name" => "Alice", "age" => 30.0}
+
+# Symbols (validated at compile-time)
+Amoskeag.eval_expression(":approved", {}, [:approved, :denied])
+# => :approved
+```
+
+### Safe Navigation
+
+Missing keys return `nil` instead of raising errors:
+
+```ruby
+Amoskeag.eval_expression("user.address.street", { "user" => {} })
+# => nil
+```
+
+## Examples
+
+### Business Rules Engine
+
+```ruby
+# Define eligibility rules
+rules = <<~AMOSKEAG
+  let applicant = {
+    "age": user.age,
+    "state": user.state,
+    "credit_score": user.credit_score
+  }
+  in let restricted_states = ["FL", "LA", "TX"]
+  in
+    if contains(restricted_states, applicant.state)
+      :deny
+    else if applicant.age < 18
+      :deny
+    else if applicant.credit_score < 650
+      :conditional
+    else
+      :approve
+    end
+AMOSKEAG
+
+# Compile once
+program = Amoskeag.compile(rules, [:approve, :deny, :conditional])
+
+# Evaluate for different users
+user1 = { "age" => 25, "state" => "CA", "credit_score" => 720 }
+Amoskeag.evaluate(program, { "user" => user1 })  # => :approve
+
+user2 = { "age" => 30, "state" => "FL", "credit_score" => 750 }
+Amoskeag.evaluate(program, { "user" => user2 })  # => :deny
+```
+
+### Template Engine
+
+```ruby
+template = <<~AMOSKEAG
+  "Hello, " + user.name + "! " +
+  if user.premium
+    "Welcome to Premium. "
+  else
+    "Upgrade to Premium today! "
+  end +
+  "You have " + user.messages | string + " new messages."
+AMOSKEAG
+
+program = Amoskeag.compile(template, [])
+
+data = {
+  "user" => {
+    "name" => "Alice",
+    "premium" => true,
+    "messages" => 5
+  }
+}
+
+Amoskeag.evaluate(program, data)
+# => "Hello, Alice! Welcome to Premium. You have 5 new messages."
+```
+
+### Financial Calculations
+
+```ruby
+# Monthly payment for a $250,000 loan at 4.5% APR for 30 years
+formula = "pmt(rate / 12, years * 12, -principal) | round(2)"
+program = Amoskeag.compile(formula, [])
+
+data = {
+  "rate" => 0.045,
+  "years" => 30,
+  "principal" => 250000
+}
+
+Amoskeag.evaluate(program, data)
+# => 1266.71
+```
+
+### Array and Collection Operations
+
+```ruby
+# Calculate average of filtered values
+code = <<~AMOSKEAG
+  let nums = [95, 82, 67, 88, 91, 73]
+  in let passing = nums | filter(lambda(x) { x >= 70 })
+  in passing | avg | round(2)
+AMOSKEAG
+
+Amoskeag.eval_expression(code, {})
+# => 85.8
+```
+
+## Standard Library
+
+Amoskeag includes 60+ built-in functions organized into categories:
+
+### String Functions
+- `upcase`, `downcase`, `capitalize`
+- `strip`, `lstrip`, `rstrip`
+- `split`, `join`, `replace`
+- `truncate`, `prepend`, `append`
+
+### Numeric Functions
+- `abs`, `ceil`, `floor`, `round`
+- `max`, `min`, `clamp`
+- `plus`, `minus`, `times`, `divided_by`
+
+### Collection Functions
+- `size`, `first`, `last`, `at`
+- `contains`, `sort`, `reverse`
+- `sum`, `avg`, `max`, `min`
+- `keys`, `values`
+
+### Logic Functions
+- `if_then_else`, `choose`
+- `is_number`, `is_string`, `is_boolean`, `is_nil`, `is_array`, `is_dictionary`
+- `coalesce`, `default`
+
+### Financial Functions (Excel-compatible)
+- **Time Value**: `pmt`, `pv`, `fv`, `nper`, `rate`
+- **Investment**: `npv`, `irr`, `mirr`
+- **Depreciation**: `sln`, `ddb`, `db`
+- **Payment Components**: `ipmt`, `ppmt`, `cumipmt`, `cumprinc`
+
+## Error Handling
+
+```ruby
+begin
+  # Undefined symbol will raise CompileError
+  Amoskeag.compile(":invalid_symbol", [:valid, :symbols])
+rescue Amoskeag::CompileError => e
+  puts "Compilation failed: #{e.message}"
+end
+
+begin
+  # Missing variable will raise EvalError
+  program = Amoskeag.compile("missing_var", [])
+  Amoskeag.evaluate(program, {})
+rescue Amoskeag::EvalError => e
+  puts "Evaluation failed: #{e.message}"
+end
+```
+
+## Performance Tips
+
+1. **Compile once, evaluate many**: Compilation has overhead, so reuse compiled programs
+2. **Use native types**: Ruby Symbols map directly to Amoskeag Symbols with zero overhead
+3. **Keep data shallow**: Deep nesting requires more JSON serialization
+4. **Avoid string concatenation in loops**: Use `join` function instead
+
+## Thread Safety
+
+Compiled programs are immutable and thread-safe. You can safely evaluate the same program from multiple threads concurrently:
+
+```ruby
+program = Amoskeag.compile("x * 2", [])
+
+threads = 10.times.map do |i|
+  Thread.new do
+    Amoskeag.evaluate(program, { "x" => i })
+  end
+end
+
+results = threads.map(&:value)
+# => [0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0]
+```
+
+## Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/durable-oss/amoskeag-rb.git
+cd amoskeag-rb
+
+# Build and install the gem
+gem build amoskeag-rb.gemspec
+gem install amoskeag-rb-0.1.0.gem
+```
+
+### Development
+
+```bash
+# Build the native extension
+cd amoskeag
+ruby extconf.rb
+make
+
+# Run tests
+rake test
+```
+
+## Architecture
+
+The gem consists of four layers:
+
+1. **Rust Core**: Pure Rust implementation of the Amoskeag compiler and interpreter (from [durable-oss/amoskeag](https://github.com/durable-oss/amoskeag))
+2. **FFI Layer** (`amoskeag/src/lib.rs`): C-compatible FFI bindings using static library
+3. **Ruby Extension** (`amoskeag/amoskeag_native.c`): Native Ruby C extension
+4. **Ruby Wrapper** (`lib/amoskeag-rb.rb`): Idiomatic Ruby API with proper marshalling
+
+Data flows through JSON serialization at the Ruby/C boundary for simplicity and type safety.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on the [GitHub repository](https://github.com/durable-oss/amoskeag-rb).
+
+## Support
+
+- GitHub Issues: https://github.com/durable-oss/amoskeag-rb/issues
+- Documentation: https://github.com/durable-oss/amoskeag-rb
+
+## Credits
+
+Amoskeag is built by [Durable Programming](https://github.com/durable-oss) with a focus on security, correctness, and developer experience.

data/ext/amoskeag/extconf.rb

@@ -0,0 +1,10 @@
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+# Check for cargo
+unless system("which cargo > /dev/null 2>&1")
+  abort "Cargo (Rust build tool) not found in PATH. Please install Rust from https://rustup.rs/"
+end
+
+# Create the Makefile using rb_sys
+create_rust_makefile("amoskeag_native")

data/lib/amoskeag-rb/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Amoskeag
+  VERSION = "0.1.1c"
+  AMOSKEAG_VERSION = "0.1.1e"
+end

data/lib/amoskeag-rb.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'amoskeag-rb/version'
+
+# Load the native extension
+begin
+  # Try relative path first (for development)
+  begin
+    require_relative '../lib/amoskeag_native'
+  rescue LoadError
+    # Fall back to standard require (for installed gem)
+    require 'amoskeag_native'
+  end
+rescue LoadError => e
+  raise LoadError, "Failed to load amoskeag_native extension. " \
+                   "Make sure the gem is properly installed and compiled. " \
+                   "Original error: #{e.message}"
+end
+
+# Amoskeag - A secure, functional DSL for business rules
+#
+# The native extension defines:
+# - Amoskeag::Error < StandardError
+# - Amoskeag::CompileError < Amoskeag::Error
+# - Amoskeag::EvalError < Amoskeag::Error
+# - Amoskeag::Program (compiled program class)
+# - Amoskeag.compile(source, symbols = []) -> Program
+# - Amoskeag.evaluate(program, data) -> Object
+# - Amoskeag.eval_expression(source, data, symbols = []) -> Object
+
+module Amoskeag
+  class << self
+    # Alias native methods for potential future wrapper use
+    alias compile_native compile
+    alias evaluate_native evaluate
+    alias eval_expression_native eval_expression
+
+    # Unwrap symbols from their hash representation at the top level only
+    # This allows expression results like `:adult` to be returned as symbols
+    # while keeping symbols nested in data structures in wrapped format
+    def unwrap_symbols(value)
+      case value
+      when Hash
+        # Check if this is a wrapped symbol at the top level
+        if value.keys == ["__symbol__"]
+          value["__symbol__"].to_sym
+        else
+          # Don't unwrap nested symbols - they're part of data structures
+          value
+        end
+      else
+        value
+      end
+    end
+
+    # Recursively wrap symbols for native processing
+    def wrap_symbols(value)
+      case value
+      when Symbol
+        { "__symbol__" => value.to_s }
+      when Hash
+        value.transform_values { |v| wrap_symbols(v) }
+      when Array
+        value.map { |v| wrap_symbols(v) }
+      else
+        value
+      end
+    end
+
+    # Validate that data is JSON-serializable
+    def validate_data(data, path = "data")
+      case data
+      when String, Integer, Float, TrueClass, FalseClass, NilClass, Symbol
+        # These are valid types (note: not all Numeric, only Integer and Float)
+        data
+      when Hash
+        data.each do |key, value|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "#{path} key must be String or Symbol, got #{key.class}"
+          end
+          validate_data(value, "#{path}[#{key.inspect}]")
+        end
+        data
+      when Array
+        data.each_with_index do |item, idx|
+          validate_data(item, "#{path}[#{idx}]")
+        end
+        data
+      else
+        # Invalid type - include path information
+        raise ArgumentError, "#{path} contains invalid type #{data.class}"
+      end
+    end
+  end
+
+  # Override the compile method (no wrapping needed, just validation)
+  def self.compile(source, symbols = [])
+    compile_native(source, symbols)
+  end
+
+  # Override the evaluate method to wrap/unwrap symbols and validate data
+  def self.evaluate(program, data)
+    validate_data(data)
+    result = evaluate_native(program, data)
+    unwrap_symbols(result)
+  end
+
+  # Override the eval_expression method to wrap/unwrap symbols and validate data
+  def self.eval_expression(source, data, symbols = [])
+    validate_data(data)
+    result = eval_expression_native(source, data, symbols)
+    unwrap_symbols(result)
+  end
+
+  # Override Program.new to raise NoMethodError
+  class Program
+    def self.new(*)
+      raise NoMethodError, "undefined method `new' for Amoskeag::Program"
+    end
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: amoskeag-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.1c
+platform: ruby
+authors:
+- Durable Programming
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !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: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  Amoskeag is a purely functional, statically-validated Domain-Specific Language (DSL)
+  designed for high-security, sandboxed evaluation. It's perfect for:
+
+  - Business Rules Engines (insurance underwriting, loan approval)
+  - Template Engines (secure alternative to ERB with more power than Liquid)
+  - Spreadsheet Formula Engines (Excel-like calculations)
+
+  This gem provides native Ruby bindings to the Amoskeag library, compiled from Rust
+  for maximum performance and security.
+email:
+- contact@example.com
+executables: []
+extensions:
+- ext/amoskeag/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- ext/amoskeag/extconf.rb
+- lib/amoskeag-rb.rb
+- lib/amoskeag-rb/version.rb
+homepage: https://github.com/durable-oss/amoskeag-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/durable-oss/amoskeag-rb
+  source_code_uri: https://github.com/durable-oss/amoskeag-rb
+  changelog_uri: https://github.com/durable-oss/amoskeag-rb/blob/main/CHANGELOG.md
+post_install_message: |2+
+
+  Thank you for installing amoskeag-rb!
+
+  Amoskeag is a secure, purely functional DSL for business rules, templates,
+  and spreadsheet formulas. It's designed to be immune to code injection
+  attacks while providing powerful expression evaluation capabilities.
+
+  Get started:
+    require 'amoskeag-rb'
+    result = Amoskeag.eval_expression("2 + 2", {})  # => 4.0
+
+  Documentation: https://github.com/durable-oss/amoskeag-rb
+
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for Amoskeag - a secure, functional DSL for business rules
+test_files: []
+...