ruby-rego 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0d83031bd5f63d45c1b362c9c43554d9d64a01f5bd880ab0886ed4ef33ec343
+  data.tar.gz: df9479201e044759b097f18bad760c3677811eba312b3ad1288406828dc7a4f9
+SHA512:
+  metadata.gz: 75ad38b961532569e213ec86d48636a1a22626b5f0de69107216278d276aff1644ae0c975b6e36a5758bea86521681f6d9864e29c7a95fd1fc327e106cb3dc8a
+  data.tar.gz: 252603fe30c8c3b8c4e1bf80dea95ab215980d67c47c856df5c7d66fe8bb9ceb636985952bd5557346e17690fbd0f76bf019ea14dc037f58860bdc23065005fc

data/.reek.yml

@@ -0,0 +1,80 @@
+# Reek configuration
+# The lexer is inherently complex and table-driven; exclude it from high-churn detectors.
+# Core parser/evaluator/unifier paths are algorithmic and currently exceed Reek thresholds;
+# suppress targeted detectors to keep the signal actionable until a deeper refactor.
+# TODO(2026-02-09): Narrow these exclusions as evaluator/parser refactors progress.
+
+detectors:
+  TooManyMethods:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Parser
+      - Ruby::Rego::Compiler
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Evaluator::RuleEvaluator
+      - Ruby::Rego::Unifier
+  TooManyConstants:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::OperatorEvaluator
+  TooManyInstanceVariables:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::ReferenceResolver
+  TooManyStatements:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Parser
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Evaluator::RuleEvaluator
+      - Ruby::Rego::Evaluator::OperatorEvaluator
+      - Ruby::Rego::Unifier
+      - Ruby::Rego::WithModifiers::WithModifierBuiltinOverride
+      - Ruby::Rego::ParserError#initialize
+      - Ruby::Rego::TypeError#initialize
+      - Ruby::Rego::UnificationError#initialize
+  DuplicateMethodCall:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Evaluator::RuleEvaluator
+      - Ruby::Rego::Unifier
+      - Ruby::Rego::WithModifiers::WithModifierBuiltinOverride
+  UtilityFunction:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Unifier
+  FeatureEnvy:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::RuleEvaluator
+      - Ruby::Rego::Evaluator::ReferenceKeyResolver
+      - Ruby::Rego::Evaluator::BoundVariableCollector
+      - Ruby::Rego::Unifier
+  ControlParameter:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::RuleEvaluator
+      - Ruby::Rego::Unifier
+      - Ruby::Rego::WithModifiers::WithModifierBuiltinOverride
+  NilCheck:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Unifier
+  RepeatedConditional:
+    exclude:
+      - Ruby::Rego::Lexer
+      - Ruby::Rego::Evaluator::ReferenceResolver
+      - Ruby::Rego::Evaluator::RuleEvaluator
+  NestedIterators:
+    exclude:
+      - Ruby::Rego::Evaluator::RuleEvaluator
+  UncommunicativeVariableName:
+    accept:
+      - e
+      - _
+    exclude:
+      - Ruby::Rego::Builtins::Collections::ObjectOps#self.object_remove
+      - Ruby::Rego::Evaluator::ExpressionDispatch#handler_for

data/.vscode/extensions.json

@@ -0,0 +1,19 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+  // List of extensions which should be recommended for users of this workspace.
+  "recommendations": [
+    "Shopify.ruby-lsp",
+    "soutaro.steep-vscode",
+    "soutaro.rbs-syntax",
+    "rubocop.vscode-rubocop",
+    "davidanson.vscode-markdownlint",
+    "markis.code-coverage",
+    "GitHub.copilot-chat",
+    "GitHub.vscode-pull-request-github",
+    "eamodio.gitlens"
+  ],
+  // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+  "unwantedRecommendations": []
+}

data/.vscode/launch.json

@@ -0,0 +1,35 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "rdbg",
+      "name": "Debug RSpec file",
+      "request": "launch",
+      "command": "bundle",
+      "script": "exec",
+      "args": ["rspec", "${file}"],
+      "cwd": "${workspaceFolder}",
+      "useTerminal": true
+    },
+    {
+      "type": "rdbg",
+      "name": "Debug RSpec example",
+      "request": "launch",
+      "command": "bundle",
+      "script": "exec",
+      "args": ["rspec", "${file}:${lineNumber}"],
+      "cwd": "${workspaceFolder}",
+      "useTerminal": true
+    },
+    {
+      "type": "rdbg",
+      "name": "Debug RSpec suite",
+      "request": "launch",
+      "command": "bundle",
+      "script": "exec",
+      "args": ["rspec"],
+      "cwd": "${workspaceFolder}",
+      "useTerminal": true
+    }
+  ]
+}

data/.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "[ruby]": {
+    "editor.defaultFormatter": "Shopify.ruby-lsp",
+    "editor.formatOnSave": true
+  },
+  "rubyLsp.formatter": "rubocop_internal",
+  "rubyLsp.linters": ["rubocop_internal"],
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "search.exclude": {
+    "**/coverage/**": true,
+    "**/tmp/**": true
+  },
+  "steep.enabled": true,
+  "steep.command": "bundle exec steep",
+  "steep.steepfile": "Steepfile",
+  "steep.gemfile": "Gemfile",
+  "steep.loglevel": "info",
+  "steep.hideDiagnostics": "Information",
+  "chat.tools.terminal.autoApprove": {
+    "bundle": true
+  }
+}

data/.vscode/tasks.json

@@ -0,0 +1,117 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "RSpec: current file",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "rspec", "${file}"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "test",
+      "problemMatcher": []
+    },
+    {
+      "label": "RSpec: suite",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "rspec"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "test",
+      "problemMatcher": []
+    },
+    {
+      "label": "Reek",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "reek", "${workspaceFolder}/lib"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "Steep",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "steep", "check"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "TypeProf",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "typeprof", "lib/**/*.rb"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "Bundler Audit",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "bundler-audit", "check", "--update"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "RubyCritic",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "rubycritic", "lib"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "Rubocop",
+      "type": "shell",
+      "command": "bundle",
+      "args": ["exec", "rubocop", "--format", "simple", "--no-color"],
+      "options": {
+        "shell": {
+          "executable": "/bin/zsh",
+          "args": ["-lc"]
+        }
+      },
+      "group": "none",
+      "problemMatcher": []
+    }
+  ]
+}

data/.yardopts

@@ -0,0 +1,12 @@
+--markup markdown
+--markup-provider kramdown
+--no-private
+--protected
+--hide-tag private
+--output-dir doc/yard
+README.md
+ARCHITECTURE.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE.txt
+lib/**/*.rb

data/ARCHITECTURE.md

@@ -0,0 +1,39 @@
+# Architecture
+
+## Overview
+
+Ruby::Rego is a pure Ruby implementation of the Rego policy language. It follows a compiler-style pipeline: parse source into an AST, compile the AST into indexed structures, and evaluate those structures against input and data.
+
+## Component responsibilities
+
+- Lexer: converts source code into tokens.
+- Parser: builds an AST from the token stream.
+- AST nodes: model Rego constructs (rules, expressions, references).
+- Compiler: validates and indexes rules, produces a CompiledModule.
+- CompiledModule: immutable bundle of rules, package path, and dependency graph.
+- Evaluator: executes queries or rule groups using the compiled module.
+- Environment: stores input, data, local bindings, and builtins.
+- Values: wrap Ruby primitives for Rego semantics and undefined handling.
+- Builtins: registry of supported functions.
+- Unifier: resolves pattern matching and binding logic.
+- CLI: validates inputs against policies via the public API.
+
+## Data flow
+
+1. Source -> Lexer -> Tokens
+2. Tokens -> Parser -> AST::Module
+3. AST -> Compiler -> CompiledModule
+4. CompiledModule + input/data -> Evaluator -> Result
+
+The evaluator walks the AST through rule evaluators and expression evaluators, resolving references against the Environment and invoking builtins when needed. Errors bubble up with location metadata to provide actionable diagnostics.
+
+## Extension points
+
+- Builtins: add new functions by extending the builtin registry and adding tests.
+- Parser: add new syntax by introducing AST nodes and parser rules.
+- Evaluator: support new expressions or keywords by adding evaluators.
+- CLI: add new flags or output modes by extending the CLI classes.
+
+## Error handling
+
+Public API calls wrap errors with location information to present a consistent error shape. Internal helpers raise specialized error subclasses to clarify failure sources (lexer, parser, compiler, evaluator, unifier).

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- Documentation refresh, architecture notes, and runnable examples.
+- YARD documentation for public APIs.
+
+## 0.1.0
+
+### Features
+
+- Lexer, parser, and AST support for core Rego syntax.
+- Compiler that validates, indexes, and freezes rules.
+- Evaluator with rule execution, unification, and reference resolution.
+- Core built-in functions (types, aggregates, strings, collections, comparisons).
+- CLI for validation workflows.
+
+### Planned additions
+
+- Expanded built-in function coverage.
+- Broader OPA compatibility for advanced keywords and patterns.
+- Performance tuning and memoization work.
+- Compliance and integration test suites.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ruby-rego" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["me@r6e.dev"](mailto:"me@r6e.dev").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rob Trame
+
+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,183 @@
+# Ruby::Rego
+
+Ruby::Rego is a pure Ruby implementation of the Open Policy Agent (OPA) Rego policy language. The project targets a clean, Ruby-idiomatic API with strong test coverage and type signatures while working toward broader Rego compatibility.
+
+## Project goals
+
+- Provide a stable Ruby API for parsing, compiling, and evaluating Rego policies.
+- Offer a deterministic evaluator with clear error reporting.
+- Keep compiled modules immutable and safe to reuse.
+- Ship a CLI for common validation workflows.
+
+## Status
+
+The gem is under active development and does not yet cover the full OPA specification. Please review the supported feature list below before relying on it in production.
+
+## Installation
+
+Install the gem and add it to your Gemfile:
+
+```bash
+bundle add ruby-rego
+```
+
+If you are not using Bundler, install it directly:
+
+```bash
+gem install ruby-rego
+```
+
+## Quick start
+
+```ruby
+require "ruby/rego"
+
+policy = <<~REGO
+  package example
+  default allow = false
+  allow { input.user == "admin" }
+REGO
+
+result = Ruby::Rego.evaluate(policy, input: {"user" => "admin"}, query: "data.example.allow")
+puts result.value.to_ruby
+```
+
+## API documentation
+
+### Basic parsing
+
+```ruby
+require "ruby/rego"
+
+tokens = Ruby::Rego::Lexer.new(policy).tokenize
+ast_module = Ruby::Rego::Parser.new(tokens).parse
+```
+
+### Policy evaluation
+
+```ruby
+require "ruby/rego"
+
+compiled = Ruby::Rego.compile(policy)
+evaluator = Ruby::Rego::Evaluator.new(compiled, input: {"user" => "admin"})
+result = evaluator.evaluate("data.example.allow")
+puts result.to_h
+```
+
+### Validation use case
+
+```ruby
+require "ruby/rego"
+require "yaml"
+
+policy_source = File.read("examples/validation_policy.rego")
+config_hash = YAML.safe_load(File.read("examples/sample_config.yaml"))
+
+policy = Ruby::Rego::Policy.new(policy_source)
+result = policy.evaluate(input: config_hash, query: "data.validation.deny")
+
+if result.undefined?
+  puts "No decision"
+elsif result.success?
+  puts "OK"
+else
+  puts "Errors: #{result.value.to_ruby.inspect}"
+end
+```
+
+### CLI usage
+
+```bash
+bundle exec exe/rego-validate --policy examples/validation_policy.rego --config examples/sample_config.yaml
+```
+
+The CLI attempts to infer a validation query in this order: `deny`, `violations`, `violation`, `errors`, `error`, then falls back to `allow`. You can override this with `--query`.
+
+## Supported Rego features
+
+### Language support
+
+- Packages and imports.
+- Rule definitions (complete and partial rules, defaults, else).
+- Literals and references, including input/data.
+- Collections: arrays, objects, sets.
+- Comprehensions (array, object, set).
+- Operators: assignment, unification, comparisons, arithmetic, and boolean logic.
+- Keywords: `some`, `not`, `every` (experimental), and `with` (limited).
+
+### Built-in functions
+
+Built-ins are currently limited to core categories: types, aggregates, strings, collections, and comparisons. See the builtins registry for the current list.
+
+### Known limitations
+
+- Not full OPA spec coverage yet.
+- Advanced `with` semantics, partial evaluation, and additional built-ins are still in progress.
+- Performance work is ongoing; expect lower throughput than OPA.
+
+## Performance and benchmarks
+
+Ruby::Rego focuses on correctness and clarity over raw throughput. Expect performance to scale with
+policy complexity: deep references, large comprehensions, and heavy use of `with` modifiers cost more.
+Memoization caches rule outputs and static references during a single evaluation to reduce repeated work.
+
+### Comparison with OPA
+
+OPA (Go) is highly optimized and typically faster, especially on large policies or high-throughput workloads.
+Use Ruby::Rego when you need a pure Ruby runtime or tight integration with Ruby applications, and prefer OPA
+for latency-critical or batch-heavy policy evaluation.
+
+### Tips for performant policies
+
+- Prefer indexed data structures and avoid deep, repeated reference chains.
+- Keep comprehensions small; filter early and avoid nested comprehensions when possible.
+- Use built-ins like `count`, `sum`, and `object.get` instead of manual loops.
+- Avoid `with` modifiers on hot paths; they are intentionally isolated and reset memoization caches.
+- Keep rule dependencies shallow to minimize repeated rule evaluation.
+
+### Running benchmarks
+
+Benchmarks use `benchmark-ips` and live in the `benchmark/` directory:
+
+```bash
+bundle exec ruby benchmark/simple_rules.rb
+bundle exec ruby benchmark/comprehensions.rb
+bundle exec ruby benchmark/builtin_calls.rb
+bundle exec ruby benchmark/complex_policy.rb
+```
+
+### CLI profiling
+
+Use `--profile` to capture timing and memory deltas for compilation and evaluation. Profiling output is
+emitted to stderr so JSON output remains machine-readable.
+
+```bash
+bundle exec exe/rego-validate --policy examples/validation_policy.rego --config examples/sample_config.yaml --profile
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/r6e/ruby-rego](https://github.com/r6e/ruby-rego).
+
+1. Run `bin/setup` to install dependencies.
+2. Run tests with `bundle exec rspec`.
+3. Run quality checks:
+
+```bash
+bundle exec rubocop
+bundle exec reek lib/
+bundle exec rubycritic lib/
+bundle exec steep check
+bundle exec typeprof lib/**/*.rb
+bundle exec bundler-audit check --update
+```
+
+Please include tests and documentation updates with your changes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Ruby::Rego project is expected to follow the code of conduct.

data/RELEASING.md

@@ -0,0 +1,37 @@
+# Releasing Ruby::Rego
+
+## 1) Prepare the release
+
+- Update [lib/ruby/rego/version.rb](lib/ruby/rego/version.rb) with the new version.
+- Update [CHANGELOG.md](CHANGELOG.md) with notable changes and release date.
+- Run the full suite locally:
+  - `bundle exec rspec`
+  - `bundle exec rubocop --format simple --no-color`
+  - `bundle exec reek lib`
+  - `bundle exec steep check`
+  - `bundle exec typeprof lib/**/*.rb`
+- Verify coverage is above 90% in `coverage/`.
+
+## 2) Build and validate the gem
+
+- Build the gem:
+  - `gem build ruby-rego.gemspec`
+- Install the built gem locally:
+  - `gem install ./ruby-rego-<version>.gem`
+- Smoke test the CLI:
+  - `rego-validate --policy examples/validation_policy.rego --config examples/sample_config.yaml`
+
+## 3) Tag and publish
+
+- Create a signed tag:
+  - `git tag -a v<version> -m "Release v<version>"`
+- Push tags and main:
+  - `git push origin main --tags`
+- Publish to RubyGems:
+  - `gem push ruby-rego-<version>.gem`
+
+## 4) Post-release checks
+
+- Confirm the release appears on RubyGems.
+- Confirm the GitHub Pages docs deployed successfully.
+- Create a GitHub release with release notes from the changelog.

data/Rakefile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+desc "Run Reek"
+task :reek do
+  sh "bundle exec reek lib"
+end
+
+desc "Run RubyCritic"
+task :rubycritic do
+  sh "bundle exec rubycritic lib"
+end
+
+desc "Run Steep type checking"
+task :steep do
+  sh "bundle exec steep check"
+end
+
+desc "Run TypeProf for signatures"
+task :typeprof do
+  sh "bundle exec typeprof lib/**/*.rb"
+end
+
+desc "Run bundler-audit security checks"
+task :bundler_audit do
+  sh "bundle exec bundler-audit check --update"
+end
+
+task default: %i[spec rubocop reek rubycritic steep typeprof bundler_audit]

data/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+We support the latest release on the `main` branch. Security fixes are released as soon as possible. If you are using an older version, please upgrade to the latest release.
+
+## Reporting a Vulnerability
+
+Please report security issues responsibly by using GitHub Security Advisories:
+
+1. Go to the repository’s “Security” tab.
+2. Click “Report a vulnerability”.
+3. Provide a detailed report with steps to reproduce, impact, and any suggested fixes.
+
+You can also open a private advisory using:
+[https://github.com/r6e/ruby-rego/security/advisories/new](https://github.com/r6e/ruby-rego/security/advisories/new)
+
+We will acknowledge receipt as soon as possible, typically within 5 business days, and will work with you to understand and resolve the issue. We may ask for additional information during triage.
+
+## Disclosure Policy
+
+We follow coordinated disclosure. Please do not publicly disclose the issue until we have had a chance to investigate and provide a fix or mitigation.
+
+## Supported Scope
+
+This policy applies to the code and artifacts in this repository, including the published gem and documentation. Vulnerabilities in third‑party dependencies should be reported to their respective maintainers.