senko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 746b5439c7763d09f66b22bac6b9f924423a2c62c6524301dd1607c4ce9d8bfa
+  data.tar.gz: d6fa6a836ab232d508feed3dc603a066b762f81e6ee1b1cce9c46ebf638df19e
+SHA512:
+  metadata.gz: 0caebf41b4dfaffbafcf8b0bde2ba6e3c3eaa98c8c8dd13eec8e1221290669fd1a6cb2c18b404f7ec7cac4766ef25957970643148b93cd54164472d644ce1611
+  data.tar.gz: c2f482f18118b8b173be18c64853d848deedfa1c6d208444ffbbd619a9eb08642772cbede0743a114470e8b88c5dce8b4206202cedcc356bff8a9a1768744a90

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'benchmark-ips'
+  gem 'json_schemer'
+  gem 'minitest'
+  gem 'rake'
+  gem 'rake-compiler'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yudai Takada
+
+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,235 @@
+# Senko
+
+Senko is a fast JSON Schema validator for Ruby. It compiles schemas into a
+reusable representation, uses generated Ruby code for simple boolean
+validation, and falls back to a full interpreter for detailed errors and
+advanced JSON Schema semantics.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'senko'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install senko
+```
+
+Senko includes a native extension for validation hot paths. If the extension
+cannot be loaded, validation continues through the pure Ruby fallback.
+
+## Usage
+
+Compile a schema once and reuse it:
+
+```ruby
+require 'senko'
+
+schema = Senko.compile(
+  'type' => 'object',
+  'required' => ['name'],
+  'properties' => {
+    'name' => { 'type' => 'string', 'minLength' => 1 }
+  },
+  'additionalProperties' => false
+)
+
+schema.valid?({ 'name' => 'senko' })
+# => true
+
+schema.valid?({ 'name' => '' })
+# => false
+```
+
+`Senko.compile` accepts either a schema hash or schema keywords directly.
+
+```ruby
+Senko.compile({ 'type' => 'string' })
+Senko.compile('type' => 'string')
+```
+
+### Validation
+
+```ruby
+schema.valid?(data)          # boolean-only validation
+schema.validate(data)        # returns Senko::Result
+schema.validate!(data)       # returns data or raises Senko::ValidationError
+schema.valid_json?(json)     # parses and validates a JSON string
+schema.validate_json(json)   # parses JSON and returns Senko::Result
+```
+
+One-shot helpers are also available:
+
+```ruby
+Senko.valid?(schema_hash, data)
+Senko.validate(schema_hash, data)
+Senko.valid_json?(schema_hash, '[1, 2, 3]')
+Senko.validate_json(schema_hash, '[1, 2, 3]')
+```
+
+Compile from a JSON file:
+
+```ruby
+schema = Senko.compile_file('schema.json')
+```
+
+### Errors and Output
+
+`validate` returns a `Senko::Result`.
+
+```ruby
+result = schema.validate({ 'name' => '' })
+
+result.valid?
+# => false
+
+result.errors.map(&:to_h)
+# => [
+#      {
+#        'keywordLocation' => '/properties/name/minLength',
+#        'instanceLocation' => '/name',
+#        'error' => 'string length must be >= 1'
+#      }
+#    ]
+```
+
+Result objects can be rendered in JSON Schema output-style shapes:
+
+```ruby
+result.to_basic
+result.to_detailed
+result.to_verbose
+```
+
+### Options
+
+Options can be passed to `compile` or to the one-shot helpers.
+
+```ruby
+schema = Senko.compile(
+  schema_hash,
+  format: :assertion,
+  fail_fast: true,
+  validate_meta_schema: true,
+  codegen: :auto
+)
+```
+
+Common options:
+
+- `format: :annotation` records format annotations without failing validation.
+- `format: :assertion` makes supported formats validation errors.
+- `fail_fast: true` stops detailed validation after the first error.
+- `validate_meta_schema: true` checks schema shape before compilation.
+- `codegen: false` disables the generated boolean fast path.
+- `messages: { type: 'custom message' }` customizes built-in error messages.
+- `schemas: { uri => schema_hash }` registers external schemas for `$ref`.
+
+### Custom Formats and Keywords
+
+Register process-wide extensions:
+
+```ruby
+Senko.register_format('starts-with-x') do |value|
+  value.start_with?('x-')
+end
+
+Senko.register_keyword('even') do |data, enabled|
+  !enabled || data.even?
+end
+
+Senko.clear_registry!
+```
+
+Or pass extensions to a single compiled schema:
+
+```ruby
+schema = Senko.compile(
+  { 'format' => 'starts-with-x' },
+  format: :assertion,
+  custom_formats: {
+    'starts-with-x' => ->(value) { value.start_with?('x-') }
+  }
+)
+```
+
+### Drafts and OpenAPI
+
+Senko detects `$schema` when present and defaults to Draft 2020-12 otherwise.
+It supports compatibility paths for Draft 2019-09, Draft 7, Draft 6, and
+Draft 4.
+
+Legacy and OpenAPI forms are normalized where possible:
+
+- `definitions`
+- tuple `items` and `additionalItems`
+- `dependencies`
+- legacy `id`
+- Draft 4 boolean exclusive numeric bounds
+- OpenAPI 3.0 `nullable: true`
+
+OpenAPI-style `oneOf` and `anyOf` schemas with a required const discriminator
+property, or an explicit `discriminator.mapping`, are compiled into direct
+discriminator dispatch.
+
+### Performance
+
+`valid?` uses generated Ruby code when the schema is supported by the code
+generator. Schemas that require full JSON Schema semantics use the interpreter.
+`validate` always uses the interpreter so detailed errors and annotations remain
+available.
+
+Run the local performance gate:
+
+```sh
+bundle exec rake benchmark:check
+```
+
+The benchmark compares Senko against `json_schemer` across codegen,
+interpreter, `$ref`, `oneOf`, and `unevaluatedProperties` scenarios.
+
+## Development
+
+After checking out the repo, install dependencies:
+
+```sh
+bundle install
+```
+
+`Gemfile.lock` is intentionally ignored for this gem.
+
+Useful commands:
+
+```sh
+bundle exec rake native:compile
+bundle exec rake test
+bundle exec rake suite:install
+bundle exec rake suite:optional
+bundle exec rake benchmark:check
+bundle exec rake ci
+```
+
+`rake ci` compiles the native extension, runs the unit tests, runs the optional
+JSON Schema Test Suite, checks performance, and builds the gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Before opening a pull request, run:
+
+```sh
+bundle exec rake ci
+```
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rbconfig'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << 'test'
+  task.test_files = FileList['test/**/*_test.rb']
+  task.warning = false
+end
+
+task default: :test
+
+namespace :suite do
+  desc 'Install JSON-Schema-Test-Suite into test/suite'
+  task :install do
+    suite_dir = File.expand_path('test/suite', __dir__)
+    if Dir.exist?(suite_dir)
+      puts 'test/suite already exists'
+    else
+      sh 'git', 'clone', 'https://github.com/json-schema-org/JSON-Schema-Test-Suite.git', suite_dir
+    end
+  end
+
+  desc 'Run the JSON-Schema-Test-Suite including optional tests'
+  task :optional do
+    sh({ 'SENKO_OPTIONAL_SUITE' => '1' }, RbConfig.ruby, '-Itest', '-Ilib', 'test/suite_runner_test.rb')
+  end
+end
+
+namespace :native do
+  desc 'Build the native extension in ext/senko'
+  task :compile do
+    Dir.chdir(File.expand_path('ext/senko', __dir__)) do
+      sh RbConfig.ruby, 'extconf.rb'
+      sh 'make', 'clean'
+      sh 'make'
+    end
+  end
+end
+
+namespace :benchmark do
+  desc 'Compare Senko validation speed against json_schemer'
+  task :compare do
+    sh RbConfig.ruby, 'test/benchmark/bench_compare.rb'
+  end
+
+  desc 'Fail if Senko misses the configured json_schemer performance target'
+  task :check do
+    sh RbConfig.ruby, 'test/benchmark/performance_check.rb'
+  end
+end
+
+desc 'Run the local CI checks'
+task ci: ['suite:install', 'native:compile', :test, 'suite:optional', 'benchmark:check', :build]

data/ext/senko/extconf.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+create_makefile('senko/senko')

data/ext/senko/instructions.c

@@ -0,0 +1 @@
+#include "instructions.h"

data/ext/senko/instructions.h

@@ -0,0 +1,12 @@
+#ifndef SENKO_INSTRUCTIONS_H
+#define SENKO_INSTRUCTIONS_H 1
+
+#define SENKO_TYPE_NULL    1
+#define SENKO_TYPE_BOOLEAN 2
+#define SENKO_TYPE_INTEGER 4
+#define SENKO_TYPE_NUMBER  12
+#define SENKO_TYPE_STRING  16
+#define SENKO_TYPE_ARRAY   32
+#define SENKO_TYPE_OBJECT  64
+
+#endif

data/ext/senko/senko.c

@@ -0,0 +1,17 @@
+#include "ruby.h"
+#include "validator.h"
+
+void
+Init_senko(void)
+{
+    VALUE mSenko = rb_define_module("Senko");
+    VALUE mNative = rb_define_module_under(mSenko, "Native");
+
+    rb_define_singleton_method(mNative, "type_mask", senko_native_type_mask, 1);
+    rb_define_singleton_method(mNative, "string_length", senko_native_string_length, 1);
+    rb_define_singleton_method(mNative, "numeric_lte?", senko_native_numeric_lte, 2);
+    rb_define_singleton_method(mNative, "numeric_lt?", senko_native_numeric_lt, 2);
+    rb_define_singleton_method(mNative, "numeric_gte?", senko_native_numeric_gte, 2);
+    rb_define_singleton_method(mNative, "numeric_gt?", senko_native_numeric_gt, 2);
+    rb_define_singleton_method(mNative, "unique_array?", senko_native_unique_array_p, 1);
+}

data/ext/senko/validator.c

@@ -0,0 +1,107 @@
+#include "ruby.h"
+#include <math.h>
+#include "validator.h"
+#include "instructions.h"
+
+static int
+senko_integer_number_p(VALUE value)
+{
+    switch (TYPE(value)) {
+      case T_FIXNUM:
+      case T_BIGNUM:
+        return 1;
+      case T_FLOAT: {
+        double number = RFLOAT_VALUE(value);
+        return isfinite(number) && floor(number) == number;
+      }
+      default:
+        if (rb_obj_is_kind_of(value, rb_path2class("BigDecimal")) == Qtrue) {
+            VALUE integer = rb_funcall(value, rb_intern2("to_i", 4), 0);
+            return RTEST(rb_funcall(value, rb_intern2("==", 2), 1, integer));
+        }
+        return 0;
+    }
+}
+
+VALUE
+senko_native_type_mask(VALUE self, VALUE value)
+{
+    switch (TYPE(value)) {
+      case T_NIL:
+        return INT2NUM(SENKO_TYPE_NULL);
+      case T_TRUE:
+      case T_FALSE:
+        return INT2NUM(SENKO_TYPE_BOOLEAN);
+      case T_FIXNUM:
+      case T_BIGNUM:
+        return INT2NUM(SENKO_TYPE_INTEGER);
+      case T_FLOAT:
+        return INT2NUM(senko_integer_number_p(value) ? SENKO_TYPE_INTEGER : (SENKO_TYPE_NUMBER & ~SENKO_TYPE_INTEGER));
+      case T_STRING:
+        return INT2NUM(SENKO_TYPE_STRING);
+      case T_ARRAY:
+        return INT2NUM(SENKO_TYPE_ARRAY);
+      case T_HASH:
+        return INT2NUM(SENKO_TYPE_OBJECT);
+      default:
+        if (rb_obj_is_kind_of(value, rb_path2class("BigDecimal")) == Qtrue)
+            return INT2NUM(senko_integer_number_p(value) ? SENKO_TYPE_INTEGER : (SENKO_TYPE_NUMBER & ~SENKO_TYPE_INTEGER));
+        return INT2NUM(0);
+    }
+}
+
+VALUE
+senko_native_string_length(VALUE self, VALUE value)
+{
+    Check_Type(value, T_STRING);
+    ID id_length = rb_intern2("length", 6);
+    return rb_funcall(value, id_length, 0);
+}
+
+VALUE
+senko_native_numeric_lte(VALUE self, VALUE left, VALUE right)
+{
+    ID id_lte = rb_intern2("<=", 2);
+    return RTEST(rb_funcall(left, id_lte, 1, right)) ? Qtrue : Qfalse;
+}
+
+VALUE
+senko_native_numeric_lt(VALUE self, VALUE left, VALUE right)
+{
+    ID id_lt = rb_intern2("<", 1);
+    return RTEST(rb_funcall(left, id_lt, 1, right)) ? Qtrue : Qfalse;
+}
+
+VALUE
+senko_native_numeric_gte(VALUE self, VALUE left, VALUE right)
+{
+    ID id_gte = rb_intern2(">=", 2);
+    return RTEST(rb_funcall(left, id_gte, 1, right)) ? Qtrue : Qfalse;
+}
+
+VALUE
+senko_native_numeric_gt(VALUE self, VALUE left, VALUE right)
+{
+    ID id_gt = rb_intern2(">", 1);
+    return RTEST(rb_funcall(left, id_gt, 1, right)) ? Qtrue : Qfalse;
+}
+
+VALUE
+senko_native_unique_array_p(VALUE self, VALUE array)
+{
+    long i, j, length;
+    ID id_eq;
+
+    Check_Type(array, T_ARRAY);
+    length = RARRAY_LEN(array);
+    id_eq = rb_intern2("==", 2);
+
+    for (i = 0; i < length; i++) {
+        for (j = i + 1; j < length; j++) {
+            if (RTEST(rb_funcall(rb_ary_entry(array, i), id_eq, 1, rb_ary_entry(array, j))))
+                return Qfalse;
+        }
+    }
+
+    return Qtrue;
+}

data/ext/senko/validator.h

@@ -0,0 +1,14 @@
+#ifndef SENKO_VALIDATOR_H
+#define SENKO_VALIDATOR_H 1
+
+#include "ruby.h"
+
+VALUE senko_native_type_mask(VALUE self, VALUE value);
+VALUE senko_native_string_length(VALUE self, VALUE value);
+VALUE senko_native_numeric_lte(VALUE self, VALUE left, VALUE right);
+VALUE senko_native_numeric_lt(VALUE self, VALUE left, VALUE right);
+VALUE senko_native_numeric_gte(VALUE self, VALUE left, VALUE right);
+VALUE senko_native_numeric_gt(VALUE self, VALUE left, VALUE right);
+VALUE senko_native_unique_array_p(VALUE self, VALUE array);
+
+#endif

data/lib/senko/cache.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Senko
+  class Cache
+    def initialize(max_size: 256)
+      @store = {}
+      @max_size = max_size
+      @access_order = []
+      @mutex = Mutex.new
+    end
+
+    def get(key)
+      @mutex.synchronize do
+        value = @store[key]
+        touch(key) if value
+        value
+      end
+    end
+
+    def put(key, value)
+      @mutex.synchronize do
+        evict_lru if @store.size >= @max_size && !@store.key?(key)
+        @store[key] = value
+        touch(key)
+      end
+      value
+    end
+
+    def fetch(key)
+      cached = get(key)
+      return cached if cached
+
+      put(key, yield)
+    end
+
+    def clear
+      @mutex.synchronize do
+        @store.clear
+        @access_order.clear
+      end
+    end
+
+    private
+
+    def touch(key)
+      @access_order.delete(key)
+      @access_order << key
+    end
+
+    def evict_lru(count = [@max_size / 4, 1].max)
+      count.times do
+        key = @access_order.shift
+        @store.delete(key) if key
+      end
+    end
+  end
+end