argot 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96b176358ac20b03d7377f0555b06de9d0054cf464b686b9fda573381a0628c0
+  data.tar.gz: 8837551ecd8af3fe9306f37734e37a8a2ea1b8fc31c5b0568f4db7b410d53f70
+SHA512:
+  metadata.gz: 65f000cb80437135c29ec679b712b6684f41b0a34e3cf8bab66511bd8a35ab1f4e12ef5a8b7b0b22be960f4d89180e528f69357aff8ecb3b1acb1ff0da72207b
+  data.tar.gz: 11ab730c7e7887a0c7d3dbc412b56f733a437594c82f1cc834a64a0c26da73e7fe7629a8fae79827b5a534945ea1d998a1140b397a8df72cb633d057d8586a26

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2024 Charlton Trezevant
+
+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,107 @@
+# Argot
+
+> **Argot** (/är′gō/)
+> _noun_
+> 
+> A characteristic language of a particular group (as among thieves).
+
+Argot is a simple gem for quickly and flexibly building minimal, validatable YAML schemas. Its original inspiration came from [this blog post](https://notes.burke.libbey.me/yaml-schema/) by [@burke](https://github.com/burke).
+
+Argot aims to be:
+  - Simple (i.e., non-bureuacratic)
+  - Flexible
+  - Easy to Understand and Extend
+
+Argot aims to avoid:
+  - Arcane syntax
+  - Having many layers of abstraction between the schema you write and the document you validate
+
+### Example Schema
+
+```yaml
+%TAG ! tag:argot.packfiles.io,2024:
+---
+
+# "version" is optional. When supplied, it must be the literal string "latest" or match the regular expression ^\d+.\d+.\d+$
+# The !one tag describes a sequence of acceptable validation rules for a given key
+!o version: !one
+- !l "latest"
+- !x '^\d+.\d+.\d+$'
+
+# "farmer_name" is required, and its value must match the regular expression ^Farmer [a-zA-Z]+$
+!r farmer_name: !x '^Farmer [a-zA-Z]+$'
+
+# "farmer_level" must be an Integer type
+!o farmer_level: !t Integer
+
+# The !x tag can also be used to describe validations that are applied 
+# to any keys in a mapping whose name matches a regular expression
+!o meats:
+  !x 'beef_from_.*':
+    !r grade: !one
+      - !l "A"
+      - !l "B"
+      - !l "C"
+      - !l "F"
+
+# When a parent key is marked as optional, validation rules will be applied to its children only
+# when that parent key is present in the document. In this case, the absence of the required 
+# pasture_uuid key will only fail validation if its parent goat_zone key is present.
+!o farm:
+  !o goat_zone:
+    !r pasture_uuid: !x '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
+    !o goats_count: !t Integer
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add argot
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install argot
+
+## Usage
+
+First, register an Argot schema:
+
+```ruby
+test_schema = File.read("./test/fixtures/schemas/01.yml")
+Argot::Schema.register(:test_schema, test_schema)
+```
+
+Then, validate some YAML files:
+
+```ruby
+rules = Argot::Schema.for(:test_schema)
+
+passing_document = File.read("./test/fixtures/documents/01-pass.yml")
+failing_document = File.read("./test/fixtures/documents/01-fail.yml")
+
+
+validator = Argot::Validator.parse_and_validate(rules, failing_document)
+validator.errors? # true
+validator.safe_load # nil
+
+validator = Argot::Validator.parse_and_validate(rules, passing_document)
+validator.errors? # false
+validator.safe_load # parsed document Hash
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/chtzvt/argot.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Made with :heart: by [Packfiles :package:](https://packfiles.io)

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/argot/annotation.rb

@@ -0,0 +1,64 @@
+module Argot
+  class Annotation
+    include Comparable
+
+    NOTICE = :notice
+    WARNING = :warning
+    FAILURE = :failure
+
+    ORDERED_LEVELS = {
+      NOTICE => 0,
+      WARNING => 1,
+      FAILURE => 2
+    }
+
+    attr_reader :start_line, :end_line, :start_column, :end_column, :level, :message, :title, :details
+    attr_accessor :path
+
+    def initialize(path: nil, location: nil, level: nil, message: nil, title: nil, details: nil)
+      @path = path || "input"
+
+      self.location = if location.is_a? Argot::Location
+        location
+      else
+        Argot::Location.new(**location)
+      end
+
+      @level = level || NOTICE
+      @message = message
+      @title = title || message
+      @details = details || message
+    end
+
+    def location=(location)
+      @start_line = location.start_line
+      @end_line = location.end_line
+      @start_column = location.start_column
+      @end_column = location.end_column
+    end
+
+    def to_h
+      {
+        path: @path,
+        start_line: @start_line,
+        end_line: @end_line,
+        start_column: @start_column,
+        end_column: @end_column,
+        annotation_level: @level,
+        message: @message,
+        title: @title,
+        raw_details: @details
+      }
+    end
+
+    def to_s
+      msg = "[#{@level.to_s.upcase}] At lines:#{@start_line}-#{@end_line} cols:#{@start_column}-#{@end_column} of #{@path} -- #{@title}: #{@message}"
+      msg += " (#{@details})" unless @details == @message
+      msg
+    end
+
+    def <=>(other)
+      ORDERED_LEVELS[level] <=> ORDERED_LEVELS[other.level]
+    end
+  end
+end

data/lib/argot/location.rb

@@ -0,0 +1,12 @@
+module Argot
+  class Location
+    attr_accessor :start_line, :end_line, :start_column, :end_column
+
+    def initialize(start_line: nil, end_line: nil, start_column: nil, end_column: nil)
+      @start_line = start_line || 1
+      @end_line = end_line || start_line || 1
+      @start_column = start_column || 1
+      @end_column = end_column || start_column || 1
+    end
+  end
+end

data/lib/argot/schema.rb

@@ -0,0 +1,386 @@
+module Argot
+  module Schema
+    def self.register(id, schema_yaml)
+      @schemas ||= {}
+      @schemas[id.is_a?(Symbol) ? id : id.to_sym] = load(schema_yaml)
+    end
+
+    def self.for(id)
+      @schemas[id]&.dup
+    end
+
+    def self.load(schema_yaml)
+      schema = Schema::Parser.parse(schema_yaml)
+      ruleset = Schema::Ruleset.new
+      Schema::Compiler.compile(schema.tree, ruleset)
+      ruleset
+    end
+
+    class Ruleset
+      attr_reader :rules
+
+      def initialize
+        @rules = Hash.new { |hash, key| hash[key] = {key: [], value: []} }
+      end
+
+      def add(type, tag, path)
+        case type
+        when :key
+          @rules[path][:key] << tag
+        when :value
+          @rules[path][:value] << tag
+        end
+      end
+
+      def permit_path?(path)
+        return false if path.empty? || path.nil?
+
+        @rules.each_key do |key_path|
+          return true if match_path?(key_path, path)
+        end
+
+        false
+      end
+
+      def permit_value?(path, value)
+        rule = lookup(path)
+
+        return false if rule.nil?
+
+        rule[:value].any? { |tag| tag.validate(value) }
+      end
+
+      def lookup(path)
+        @rules.each do |key_path, rule_set|
+          return rule_set if match_path?(key_path, path)
+        end
+        nil
+      end
+
+      def paths
+        @rules.keys
+      end
+
+      def subkeys(partial_path)
+        return @rules.keys if partial_path.empty?
+
+        @rules.keys.map do |key_path|
+          if match_subpath?(key_path, partial_path)
+            next_element = key_path[partial_path.size]
+            [next_element] if next_element
+          end
+        end.compact!.uniq
+      end
+
+      def required_path?(path)
+        parent_path = path.take((path.length >= 1) ? path.length - 1 : 0)
+        parent_rule_set = lookup(parent_path)
+        rule_set = lookup(path)
+
+        if parent_rule_set.nil? && rule_set.nil?
+          false
+        elsif parent_rule_set.nil? && rule_set[:key].any? { |tag| tag.is_a?(Argot::Tag::Required) }
+          true
+        elsif !parent_rule_set.nil? && parent_rule_set[:key].any? { |tag| tag.is_a?(Argot::Tag::Optional) } && !rule_set.nil? && rule_set[:key].any? { |tag| tag.is_a?(Argot::Tag::Required) }
+          true
+        else
+          false
+        end
+      end
+
+      def match_path?(key_path, lookup_path)
+        return false unless key_path.size == lookup_path.size
+
+        key_path.zip(lookup_path).all? do |key_part, lookup_part|
+          case key_part
+          when String
+            key_part == lookup_part
+          when Regexp
+            if lookup_part.is_a?(String)
+              key_part.match?(lookup_part)
+            elsif lookup_part.is_a?(Regexp)
+              key_part == lookup_part
+            end
+          else
+            false
+          end
+        end
+      end
+
+      def match_subpath?(key_path, partial_path)
+        return false unless key_path.size > partial_path.size
+
+        key_path.first(partial_path.size).zip(partial_path).all? do |key_part, partial_part|
+          case key_part
+          when String
+            key_part == partial_part
+          when Regexp
+            if partial_part.is_a?(String)
+              key_part.match?(partial_part)
+            elsif partial_part.is_a?(Regexp)
+              key_part == partial_part
+            end
+          else
+            false
+          end
+        end
+      end
+    end
+
+    class Compiler
+      def self.compile(node, ruleset)
+        return unless node.is_a? Argot::Schema::Node
+
+        return unless node.value.is_a?(Array)
+
+        node.value.each do |child|
+          next if child.is_a? Argot::Schema::Node
+
+          child_node_annotation = child.first
+          child_node = child.last
+
+          if child_node_annotation.tag_is_a?(Tag::Pattern)
+            ruleset.add(:key, Tag::Optional.new, child_node.path)
+          else
+            ruleset.add(:key, child_node_annotation.tag, child_node.path)
+          end
+
+          if child_node.tag?
+            if child_node.tag_is_a?(Argot::Tag::OneOf)
+              child_node.value.each do |oneof_opt|
+                if oneof_opt.tag?
+                  ruleset.add(:value, oneof_opt.tag, oneof_opt.path)
+                else
+                  compile(oneof_opt, ruleset)
+                end
+              end
+            else
+              ruleset.add(:value, child_node.tag, child_node.path)
+            end
+          end
+
+          compile(child_node, ruleset)
+        end
+      end
+    end
+
+    class Node
+      attr_accessor :value, :path
+      attr_reader :tag, :location
+
+      def initialize(value: nil, tag: nil, location: nil, path: [])
+        @value = value
+        self.tag = tag
+        configure_tag!
+        self.location = location
+        @path = path
+      end
+
+      def tag?
+        !@tag.nil?
+      end
+
+      def tag_is_a?(klass)
+        @tag.is_a?(klass)
+      end
+
+      def configure_tag!
+        @tag.configure(@value) if tag?
+      end
+
+      def tag=(tag)
+        @tag = Argot::Tag.for(tag)
+      end
+
+      def location=(loc)
+        @location = Argot::Location.new(**loc)
+      end
+    end
+
+    class Parser < ::Psych::Handler
+      attr_reader :tree, :locations, :current_path
+
+      class << self
+        def parse(schema_yaml)
+          handler = Argot::Schema::Parser.new
+          parser = Psych::Parser.new(handler)
+          parser.parse(schema_yaml)
+          handler
+        end
+      end
+
+      def initialize
+        super
+        @context = []
+        @tree = nil
+        @current_path = []
+        @locations = {}
+        @scalar_scanner = build_safe_scalar_scanner
+      end
+
+      def build_safe_scalar_scanner
+        class_loader = Psych::ClassLoader::Restricted.new([], [])
+        Psych::ScalarScanner.new(class_loader)
+      end
+
+      def context_empty?
+        @context.empty?
+      end
+
+      def current_context
+        @context.last
+      end
+
+      def in_sequence?
+        current_context&.key?(:sequence)
+      end
+
+      def in_mapping?
+        current_context&.key?(:mapping)
+      end
+
+      def push_path(val)
+        @current_path.push(val)
+      end
+
+      def pop_path
+        @current_path.pop
+      end
+
+      def dup_path
+        @current_path.dup
+      end
+
+      def event_location(start_line, start_column, end_line, end_column)
+        @current_location = {
+          start_line: start_line + 1,
+          end_line: end_line + 1,
+          start_column: start_column + 1,
+          end_column: end_column + 1
+        }
+      end
+
+      def start_mapping(anchor, tag, implicit, style)
+        @context.push({mapping: [], tag: tag, key: nil})
+      end
+
+      def end_mapping
+        mapping = @context.pop
+
+        node = Node.new(
+          value: mapping[:mapping],
+          tag: mapping[:tag],
+          location: @current_location.dup,
+          path: dup_path
+        )
+
+        if context_empty?
+          @tree = node
+          return
+        end
+
+        if in_sequence?
+          current_context[:sequence] << node
+        elsif in_mapping?
+          if current_context[:key].nil?
+            raise Argot::Unprocessable, "Unexpected state in end_mapping"
+          else
+            current_context[:mapping] << [current_context[:key], node]
+            current_context[:key] = nil
+            pop_path
+          end
+        else
+          raise Argot::Unprocessable, "Unknown context in end_mapping"
+        end
+      end
+
+      def scalar(value, anchor, tag, plain, quoted, style)
+        parsed_value = parse_scalar(value)
+
+        node = Node.new(
+          value: parsed_value,
+          tag: tag,
+          location: @current_location.dup,
+          path: dup_path
+        )
+
+        if context_empty?
+          @tree = node
+          return
+        end
+
+        if in_sequence?
+          current_context[:sequence] << node
+          return
+        end
+
+        if in_mapping?
+          if current_context[:key].nil?
+            # We are processing a key
+            if node.tag_is_a?(Tag::Pattern)
+              push_path Regexp.new(parsed_value)
+            else
+              push_path parsed_value.to_s
+            end
+
+            location_key = @current_path.join(".")
+            @locations[location_key] = node.location
+
+            current_context[:key] = node
+          else
+            # We are processing a value
+
+            current_context[:mapping] << [current_context[:key], node]
+            current_context[:key] = nil
+            pop_path
+          end
+          return
+        end
+
+        raise Argot::Unprocessable, "Unknown context in scalar"
+      end
+
+      def start_sequence(anchor, tag, implicit, style)
+        @context.push({sequence: [], tag: tag})
+      end
+
+      def end_sequence
+        sequence = @context.pop
+
+        node = Node.new(
+          value: sequence[:sequence],
+          tag: sequence[:tag],
+          location: @current_location.dup,
+          path: dup_path
+        )
+
+        if context_empty?
+          @tree = node
+          return
+        end
+
+        if in_sequence?
+          current_context[:sequence] << node
+        elsif in_mapping?
+          if current_context[:key].nil?
+            raise Argot::Unprocessable, "Unexpected state in end_sequence"
+          else
+            current_context[:mapping] << [current_context[:key], node]
+            current_context[:key] = nil
+            pop_path
+          end
+        else
+          raise Argot::Unprocessable, "Unknown context in end_sequence"
+        end
+      end
+
+      private
+
+      def parse_scalar(value)
+        @scalar_scanner.tokenize(value)
+      rescue ArgumentError, Psych::SyntaxError
+        value.to_s
+      end
+    end
+  end
+end

data/lib/argot/tag.rb

@@ -0,0 +1,76 @@
+module Argot
+  module Tag
+    @tags = {}
+    @global_uri = "tag:argot.packfiles.io,2024"
+
+    def self.register(klass)
+      full_tag = "#{klass.uri}:#{klass.tag_name}"
+      @tags[full_tag] = Object.const_get(klass.name)
+    end
+
+    def self.for(tag)
+      @tags[tag]&.new
+    end
+
+    def self.tags
+      @tags
+    end
+
+    def self.global_uri
+      @global_uri
+    end
+
+    def self.global_uri=(uri)
+      @global_uri = uri
+    end
+
+    class Base
+      class << self
+        attr_reader :annotation_type
+
+        def annotates_key?
+          @annotation_type == :key || @annotation_type == :key_or_value
+        end
+
+        def annotates_value?
+          @annotation_type == :value || @annotation_type == :key_or_value
+        end
+
+        def annotates(arg)
+          @annotation_type = arg if %i[key value key_or_value].include?(arg)
+        end
+
+        def tag_name(name = nil)
+          if name
+            @tag_name = name
+            Argot::Tag.register(self)
+          end
+          @tag_name
+        end
+
+        def uri(uri = nil)
+          return Argot::Tag.global_uri if uri.nil?
+
+          @uri = "tag:" + uri
+        end
+      end
+
+      def annotation_type
+        self.class.annotation_type
+      end
+
+      def annotates_key?
+        self.class.annotates_key?
+      end
+
+      def annotates_value?
+        self.class.annotates_value?
+      end
+
+      def configure(value)
+      end
+    end
+  end
+end
+
+Dir[File.join(__dir__, "tags", "*.rb")].each { |file| require file }

data/lib/argot/tags/literal.rb

@@ -0,0 +1,25 @@
+module Argot
+  module Tag
+    class Literal < Base
+      tag_name "literal"
+      tag_name "l"
+      annotates :value
+
+      def initialize
+        @expected_value = nil
+      end
+
+      def configure(value)
+        @expected_value = value
+      end
+
+      def expectation
+        "'#{@expected_value}'"
+      end
+
+      def validate(value)
+        value == @expected_value
+      end
+    end
+  end
+end

data/lib/argot/tags/oneof.rb

@@ -0,0 +1,17 @@
+module Argot
+  module Tag
+    class OneOf < Base
+      tag_name "oneof"
+      tag_name "one"
+
+      def initialize
+        super
+        @options = []
+      end
+
+      def configure(options)
+        @options = options
+      end
+    end
+  end
+end

data/lib/argot/tags/optional.rb

@@ -0,0 +1,14 @@
+module Argot
+  module Tag
+    class Optional < Base
+      tag_name "optional"
+      tag_name "o"
+      annotates :key
+
+      def validate(value)
+        # Optional fields do not produce errors if missing
+        true
+      end
+    end
+  end
+end

data/lib/argot/tags/pattern.rb

@@ -0,0 +1,26 @@
+module Argot
+  module Tag
+    class Pattern < Base
+      tag_name "rexpr"
+      tag_name "x"
+      annotates :key_or_value
+
+      def initialize
+        super
+        @regex = nil
+      end
+
+      def configure(pattern)
+        @regex = Regexp.new(pattern)
+      end
+
+      def expectation
+        "a match for the regular expression '#{@regex.source}'"
+      end
+
+      def validate(value)
+        value.to_s.match?(@regex)
+      end
+    end
+  end
+end

data/lib/argot/tags/range.rb

@@ -0,0 +1,47 @@
+module Argot
+  module Tag
+    class Range < Base
+      tag_name "range"
+      tag_name "rg"
+      annotates :value
+
+      def initialize
+        super
+        @range = nil
+      end
+
+      def configure(range_str)
+        # Parse the range string using a regex
+        # Supports formats like '1..10', '1...10', '1-10', '1 to 10'
+        if range_str =~ /\A\s*(\d+)\s*(\.\.\.?|-|to)\s*(\d+)\s*\z/
+          start_num = Regexp.last_match(1).to_i
+          operator = Regexp.last_match(2)
+          end_num = Regexp.last_match(3).to_i
+
+          inclusive = ["..", "-", "to"].include?(operator)
+          exclusive = operator == "..."
+
+          @range = if inclusive
+            (start_num..end_num)
+          elsif exclusive
+            (start_num...end_num)
+          end
+        else
+          @range = nil
+        end
+      end
+
+      def expectation
+        "a value between #{@range.min} and #{@range.max}"
+      end
+
+      def validate(value)
+        return false if @range.nil?
+
+        return false unless value.is_a?(Numeric)
+
+        @range.cover?(value)
+      end
+    end
+  end
+end

data/lib/argot/tags/required.rb

@@ -0,0 +1,14 @@
+module Argot
+  module Tag
+    class Required < Base
+      tag_name "required"
+      tag_name "r"
+
+      annotates :key
+
+      def validate(value)
+        true
+      end
+    end
+  end
+end

data/lib/argot/tags/type.rb

@@ -0,0 +1,45 @@
+module Argot
+  module Tag
+    class Type < Base
+      tag_name "type"
+      tag_name "t"
+      annotates :value
+
+      def initialize
+        super
+        @expected_types = nil
+      end
+
+      def configure(type_name)
+        @expected_types = case type_name.downcase
+        when "string"
+          [String]
+        when "integer"
+          [Integer]
+        when "float"
+          [Float]
+        when "array"
+          [Array]
+        when "hash", "map"
+          [Hash]
+        when "boolean"
+          [TrueClass, FalseClass]
+        else
+          []
+        end
+      end
+
+      def expectation
+        return "Boolean" if @expected_types.length == 2
+
+        @expected_types.first.name
+      end
+
+      def validate(value)
+        return false if @expected_types.empty?
+
+        @expected_types.any? { |t| value.is_a?(t) }
+      end
+    end
+  end
+end

data/lib/argot/validator.rb

@@ -0,0 +1,291 @@
+module Argot
+  class Validator < Psych::Handler
+    attr_reader :errors
+
+    class << self
+      def parse_and_validate(ruleset, file_content, file_name: "input")
+        handler = Argot::Validator.new(ruleset, file_name)
+        parser = Psych::Parser.new(handler)
+        parser.parse(file_content)
+        handler.validate_document
+        handler
+      end
+
+      def load(ruleset, file_content, file_name: "input", **)
+        handler = parse_and_validate(ruleset, file_content, file_name: file_name)
+
+        handler.safe_load(**)
+      end
+    end
+
+    def initialize(ruleset, file_name)
+      super()
+      @ruleset = ruleset
+      @file_name = file_name || "input"
+      @context = []
+      @current_path = []
+      @encountered_paths = {}
+      @missing_keys = {}
+      @errors = []
+      @current_location = {}
+      @scalar_scanner = build_safe_scalar_scanner
+
+      @stream_node = Psych::Nodes::Stream.new
+      @document_node = Psych::Nodes::Document.new([], [], true)
+      @stream_node.children << @document_node
+    end
+
+    def build_safe_scalar_scanner
+      class_loader = Psych::ClassLoader::Restricted.new([], [])
+      Psych::ScalarScanner.new(class_loader)
+    end
+
+    def errors?
+      !@errors.empty?
+    end
+
+    def tree
+      @stream_node
+    end
+
+    def safe_load(permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false, ignore_validation_errors: false)
+      return nil if errors? && !ignore_validation_errors
+      return fallback unless @document_node
+
+      class_loader = Psych::ClassLoader::Restricted.new(permitted_classes.map(&:to_s), permitted_symbols.map(&:to_s))
+
+      scanner = Psych::ScalarScanner.new class_loader, strict_integer: strict_integer
+
+      visitor = if aliases
+        Psych::Visitors::ToRuby.new scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze
+      else
+        Psych::Visitors::NoAliasRuby.new scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze
+      end
+
+      begin
+        result = visitor.accept @document_node
+      rescue Psych::DisallowedClass => e
+        raise Argot::MaliciousInput, e.message
+      end
+
+      result
+    end
+
+    def event_location(start_line, start_column, end_line, end_column)
+      @current_location = {
+        start_line: start_line + 1,
+        end_line: end_line + 1,
+        start_column: start_column + 1,
+        end_column: end_column + 1
+      }
+    end
+
+    def start_mapping(anchor, tag, implicit, style)
+      mapping = Psych::Nodes::Mapping.new(anchor, tag, implicit, style)
+      push_context({node: mapping, key: nil})
+    end
+
+    def end_mapping
+      mapping = pop_context[:node]
+
+      if context_empty?
+        append_tree mapping
+        return
+      end
+
+      if in_sequence?
+        append_child mapping
+      elsif in_mapping?
+        raise Argot::Unprocessable, "Unexpected state in end_mapping" if current_context[:key].nil?
+
+        append_child current_context[:key]
+        append_child mapping
+        current_context[:key] = nil
+        pop_path
+      end
+    end
+
+    def scalar(value, anchor, tag, plain, quoted, style)
+      scalar = Psych::Nodes::Scalar.new(value, anchor, tag, plain, quoted, style)
+
+      if in_sequence?
+        append_child scalar
+        validate_node scalar
+        pop_path
+      elsif in_mapping?
+        if current_context[:key].nil?
+          push_path value
+          current_context[:key] = scalar
+        else
+          append_child current_context[:key]
+          append_child scalar
+          validate_node scalar
+
+          current_context[:key] = nil
+          pop_path
+        end
+      else
+        raise Argot::Unprocessable, "Unknown context in scalar"
+      end
+    end
+
+    def start_sequence(anchor, tag, implicit, style)
+      sequence = Psych::Nodes::Sequence.new(anchor, tag, implicit, style)
+      push_context({node: sequence})
+    end
+
+    def end_sequence
+      sequence = pop_context[:node]
+
+      if context_empty?
+        append_tree sequence
+      elsif in_sequence?
+        append_child sequence
+      elsif in_mapping?
+        raise Argot::Unprocessable, "Unexpected state in end_sequence" if current_context[:key].nil?
+
+        append_child current_context[:key]
+        append_child sequence
+        current_context[:key] = nil
+      end
+    end
+
+    def validate_document
+      # Check for required keys
+      @ruleset.paths.each do |ruleset_path|
+        parent_path = ruleset_path.take(ruleset_path.length - 1)
+
+        if @ruleset.required_path?(ruleset_path) && !encountered_path?(ruleset_path) && encountered_path?(parent_path)
+          emit_missing_key_error(ruleset_path)
+        end
+      end
+
+      # Check for optionally required keys (required keys that are children of an optional parent key)
+      @encountered_paths.each_key do |tracked_path|
+        subkey_paths = @ruleset.subkeys(tracked_path)
+
+        subkey_paths.each do |subkey_path_part|
+          subkey_path = tracked_path + subkey_path_part
+          rule_set = @ruleset.lookup(subkey_path)
+
+          next unless rule_set&.key?(:key)
+
+          emit_missing_key_error(subkey_path) if @ruleset.required_path?(subkey_path) && !encountered_path?(subkey_path)
+        end
+      end
+    end
+
+    private
+
+    def in_sequence?
+      current_context[:node].is_a?(Psych::Nodes::Sequence)
+    end
+
+    def in_mapping?
+      current_context[:node].is_a?(Psych::Nodes::Mapping)
+    end
+
+    def append_child(node)
+      return unless @ruleset.permit_path?(@current_path)
+
+      @encountered_paths[@current_path.dup] = @current_location.dup unless @encountered_paths.key?(@current_path)
+      current_context[:node].children << node
+    end
+
+    def append_tree(node)
+      @document_node.children << node
+    end
+
+    def context_empty?
+      @context.empty?
+    end
+
+    def clear_context
+      @context = []
+    end
+
+    def push_context(val)
+      @context.push(val)
+    end
+
+    def pop_context
+      @context.pop
+    end
+
+    def current_context
+      @context.last
+    end
+
+    def push_path(val)
+      @current_path.push(val)
+    end
+
+    def pop_path
+      @current_path.pop
+    end
+
+    def parse_scalar(value)
+      @scalar_scanner.tokenize(value)
+    rescue ArgumentError, Psych::SyntaxError
+      value.to_s
+    end
+
+    def validate_node(node)
+      value = parse_scalar(node.value)
+
+      rule_set = @ruleset.lookup(@current_path)
+
+      if rule_set.nil?
+        @errors << Argot::Annotation.new(path: @file_name,
+          location: @current_location.dup,
+          level: Annotation::WARNING,
+          title: "Invalid Key",
+          message: "'#{@current_path.join(".")}' is not permitted in this document.")
+        return
+      end
+
+      return unless rule_set[:value].any?
+
+      validation_errors = []
+      valid = false
+
+      rule_set[:value].each do |tag|
+        validation_errors.append(tag.expectation)
+        valid = true if tag.validate(value)
+      end
+
+      return if valid
+
+      expectations = (validation_errors.size > 1) ? "#{validation_errors[0..-2].join(", ")}, or #{validation_errors[-1]}" : validation_errors.first
+
+      @errors << Argot::Annotation.new(path: @file_name,
+        location: @current_location.dup,
+        level: Annotation::FAILURE,
+        title: "Invalid Value",
+        message: "The value '#{value}' is invalid for #{@current_path.join(".")}",
+        details: "Expected #{expectations}")
+    end
+
+    def encountered_path?(subkey_path)
+      return true if subkey_path.empty?
+
+      @encountered_paths.keys.any? do |tracked_path|
+        @ruleset.match_path?(subkey_path, tracked_path)
+      end
+    end
+
+    def emit_missing_key_error(subkey_path)
+      return if @missing_keys.key?(subkey_path)
+
+      @errors << Argot::Annotation.new(
+        path: @file_name,
+        location: @encountered_paths[subkey_path] || @encountered_paths[subkey_path[..subkey_path.length - 2]] || {},
+        level: Argot::Annotation::FAILURE,
+        title: "Missing Key",
+        message: "The key '#{subkey_path.join(".")}' is required, but missing."
+      )
+
+      @missing_keys[subkey_path] = nil
+    end
+  end
+end

data/lib/argot/version.rb

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

data/lib/argot.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "psych"
+require_relative "argot/version"
+require_relative "argot/location"
+require_relative "argot/annotation"
+require_relative "argot/tag"
+require_relative "argot/validator"
+require_relative "argot/schema"
+
+module Argot
+  class Error < StandardError; end
+
+  class Unprocessable < Error; end
+
+  class MaliciousInput < Unprocessable; end
+end

data/sig/argot.rbs

@@ -0,0 +1,4 @@
+module Argot
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: argot
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Charlton Trezevant
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+description: Quickly and flexibly build minimal, validatable YAML schemas.
+email:
+- charlton@packfiles.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/argot.rb
+- lib/argot/annotation.rb
+- lib/argot/location.rb
+- lib/argot/schema.rb
+- lib/argot/tag.rb
+- lib/argot/tags/literal.rb
+- lib/argot/tags/oneof.rb
+- lib/argot/tags/optional.rb
+- lib/argot/tags/pattern.rb
+- lib/argot/tags/range.rb
+- lib/argot/tags/required.rb
+- lib/argot/tags/type.rb
+- lib/argot/validator.rb
+- lib/argot/version.rb
+- sig/argot.rbs
+homepage: https://github.com/chtzvt/argot
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chtzvt/argot
+  source_code_uri: https://github.com/chtzvt/argot
+  changelog_uri: https://github.com/chtzvt/argot
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Argot is a simple gem for quickly and flexibly building minimal, validatable
+  YAML schemas.
+test_files: []