liminal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c8b9358afd48ae00ba175c322616177fea6b11b28b68039866960250ecac6ad
+  data.tar.gz: 7336f7cf8458cb1da841cc08b3647df2345cbea98849ed87dbca9f118bdb9de5
+SHA512:
+  metadata.gz: e2fb7bae0338e67a6971d6aa072e310be23c3dae0f948fbc91ff0b067135e99f51a667c700a3a08b5de4d769ea02e7b448adde5fb61d3d5d25ca886c4d66d5bd
+  data.tar.gz: 35b0ba788a0b564d7b0fb65e9e674653515f4117122c90321240ca5767d773cddad697488dd121fc12a5d53f89ed81c2aaaf04e4e681946da763608b4044bafd

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes are documented here. The project follows Semantic Versioning.
+
+## 0.1.0 - Unreleased
+
+- Add strict dry-schema 1.x AST compilation to OpenAPI 3.0 Schema Objects.
+- Add exclusions, enrichment and authoritative overrides, and immutable predicate extensions.
+- Add idempotent OpenAPI component registration with collision detection.
+- Compile the standard dry-types boolean union emitted as `true?`/`false?` value predicates.
+- Add strict Schema Object normalization and non-mutating `required`, `exactly_one`, and `all_of` composition.
+- Reject ambiguous paths and keys, non-JSON numeric values, unsafe regular-expression anchors, and malformed metadata objects.

data/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Liminal intentionally supports only declarative behavior visible in `Dry::Schema#to_ast`. Changes that infer or execute
+application rules are outside the project boundary.
+
+Install dependencies and run the default checks:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+Run a dry-schema compatibility appraisal by selecting its Gemfile:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/dry_schema_1_13.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/dry_schema_1_13.gemfile bundle exec rspec
+```
+
+Repeat for `dry_schema_1_14`, `dry_schema_1_15`, and `dry_schema_1_16`. Tests use randomized order. Enable line and branch
+coverage locally with `COVERAGE=true bundle exec rspec`.
+
+Before proposing a new predicate, show that its semantics can be represented safely in OpenAPI 3.0 and add real
+dry-schema AST coverage. Do not publish, release, or widen the supported dependency range without the maintainers'
+explicit approval and a green compatibility matrix.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Liminal contributors
+
+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,227 @@
+# Liminal
+
+Liminal strictly compiles declarative `Dry::Schema#to_ast` structure and predicates into deterministic OpenAPI 3.0
+Schema Objects. It is useful when a dry-schema definition is the application source of truth and silently dropping a
+validation constraint would make generated API documentation misleading.
+
+The Ruby API lives under `Liminal`; it does not use `Dry::` and is not an official dry-rb project.
+
+## Compatibility
+
+| Concern | Supported |
+| --- | --- |
+| Ruby | 3.2 and newer |
+| dry-schema | 1.13.4 through 1.16.x (`>= 1.13.4`, `< 1.17`) |
+| OpenAPI | 3.0.x only |
+| OpenAPI integration | Provided separately by the `liminal-openapi` companion gem |
+
+The dependency matrix runs the same real dry-schema definitions against 1.13, 1.14, 1.15, and 1.16. OpenAPI 3.1 syntax,
+including type arrays and numeric `exclusiveMinimum` values, is rejected.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "liminal", "~> 0.1.0"
+```
+
+Then run `bundle install` and require `liminal`.
+
+## Compilation
+
+```ruby
+require "dry/schema"
+require "liminal"
+
+schema = Dry::Schema.Params do
+  required(:name).filled(:string)
+  optional(:score).filled(:float, gt?: 0)
+end
+
+openapi_schema = Liminal.compile(
+  schema,
+  dialect: :openapi_3_0,
+  source_name: "CreateEventSchema"
+)
+```
+
+The result is a plain recursively string-keyed `Hash`. Required fields become `required`; optional fields do not.
+Arrays always include `items`, empty `required` arrays are omitted, and stable AST order produces stable output.
+
+Liminal depends on `dry-schema`, not `dry-validation`. Applications using contracts can expose a convenience method:
+
+```ruby
+class Contracts::Base < Dry::Validation::Contract
+  def self.openapi_schema(**options)
+    Liminal.compile(schema, source_name: name, **options)
+  end
+end
+```
+
+`Dry::Schema::Params` may coerce input strings before validation, while OpenAPI describes their post-coercion JSON
+representation. Use `Dry::Schema::JSON` when differential tests should compare non-coercing behavior directly.
+
+## Exclusions
+
+Array paths are canonical and preserve property names containing dots:
+
+```ruby
+Liminal.compile(
+  schema,
+  exclude: [[:message_id], %i[data internal_metadata]]
+)
+```
+
+Exclusions happen before the field rule is compiled, remove the field from its parent's `required` list, and can conceal
+an intentionally undocumented unsupported predicate. Unknown paths raise `Liminal::UnknownExclusionPathError`. Dotted
+strings are accepted only as a convenience.
+
+## Overrides
+
+An enrichment override deep-merges documentation or representable structural details into a successfully generated field:
+
+```ruby
+overrides = {
+  %i[data attributes event_at] => {
+    "format" => "date",
+    "description" => "Calendar date"
+  }
+}
+```
+
+`required` arrays are unioned during enrichment. An authoritative override may replace a field whose node or predicate
+cannot be compiled, but it must contain one of `type`, `$ref`, `oneOf`, `anyOf`, or `allOf`:
+
+```ruby
+overrides = {
+  [:opaque_id] => {"type" => "string", "format" => "uuid"}
+}
+```
+
+A description alone never hides an unsupported construct. Unknown paths raise `Liminal::UnknownOverridePathError`.
+An override cannot target an excluded path or one of its descendants; contradictory path configuration raises
+`Liminal::InvalidOverrideError`. A parent override may enrich a schema after one of its descendants is excluded.
+OpenAPI 3.1-only keywords are rejected. OpenAPI 3.0 forbids `$ref` siblings, so use `allOf` when a reference also needs a
+description:
+
+```ruby
+{ "allOf" => [{ "$ref" => "#/components/schemas/User" }], "description" => "User" }
+```
+
+## Schema composition
+
+`Liminal::Schema.normalize` is the public boundary for precompiled Schema
+Objects. It copies the input, normalizes object keys, validates OpenAPI 3.0
+keywords and nested values, and produces deterministic keyword order:
+
+```ruby
+normalized = Liminal::Schema.normalize({type: "string"})
+required = Liminal::Schema.required(schema, :mobile_phone)
+exclusive = Liminal::Schema.exactly_one(schema, :mobile_phone, :email)
+combined = Liminal::Schema.all_of(base_schema, detail_schema)
+```
+
+Precompiled values must already be JSON-native: strings, booleans, `nil`,
+integers, finite floats, arrays, and string- or symbol-keyed hashes. Ambiguous
+string/symbol keys and Ruby-only scalar values fail validation instead of being
+silently coerced.
+
+`required` unions the named properties with an existing `required` array.
+`exactly_one` emits one `oneOf` required-property branch per name and preserves
+an existing `oneOf` as a separate `allOf` constraint. `all_of` keeps each input
+as an independent branch. Applying a combinator to a `$ref` uses `allOf`, since
+OpenAPI 3.0 forbids `$ref` siblings.
+
+## Predicate extensions
+
+The default registry is immutable. `with` returns a copy:
+
+```ruby
+predicates = Liminal::PredicateRegistry.default.with(:uuid_v4?) do |_arguments, context|
+  raise "unexpected dialect" unless context.dialect.name == :openapi_3_0
+
+  {"type" => "string", "format" => "uuid"}
+end
+
+Liminal.compile(schema, predicates: predicates)
+```
+
+Handlers receive semantic arguments with dry input placeholders removed and a context containing the canonical path and
+dialect. They must return a Hash. Duplicate registration requires `replace: true`; incompatible keywords and types are
+rejected.
+
+Built-in predicates cover arrays, booleans, dates and times, numbers, hashes, integers, strings, `type?` for the documented
+Ruby primitive classes, equality and inclusion enums, safe regular expressions, filled and size constraints, numeric
+boundaries, and integer parity. `and`, `or`, nullable implications, and `each` are compiled without exposing raw AST nodes.
+Ruby `\A` and `\z` anchors are translated to their ECMA-262 equivalents. Raw `^`
+and `$` anchors are rejected because their Ruby line semantics cannot be
+preserved safely.
+
+## Strict failures and custom rules
+
+Unsupported AST nodes and predicates raise contextual `Liminal::UnsupportedNodeError` or
+`Liminal::UnsupportedPredicateError`, including the source, canonical field path, and failing operation. Compilation never
+has a permissive mode.
+
+A dry-validation rule such as this is arbitrary Ruby and is not part of the declarative schema AST:
+
+```ruby
+rule("data.attributes.event_at") do
+  ValidateIso8601Date.call(date: value)
+end
+```
+
+Liminal does not execute, introspect, or pretend to translate such rules. Represent structural documentation explicitly
+with an override. Database checks and cross-field business rules belong in endpoint prose rather than a Schema Object.
+
+## Components
+
+Register a generated component in any mutable OpenAPI document:
+
+```ruby
+reference = Liminal::Components.register(
+  document: openapi_document,
+  name: :calendar_event,
+  schema: openapi_schema
+)
+# => {"$ref"=>"#/components/schemas/calendar_event"}
+```
+
+Missing maps are created. A document may use either string or symbol container
+keys, but declaring both logical forms is rejected as ambiguous. Component
+names may contain only letters, digits, periods, hyphens, and underscores.
+Re-registering the same normalized schema is idempotent; a different schema or
+duplicate string/symbol component key raises `Liminal::ComponentCollisionError`.
+Returned references are immutable.
+
+## Rswag boundary
+
+The core gem contains no Rails, Active Support, RSpec, or Rswag runtime dependency and performs no global monkey-patching.
+Until a separately versioned Rswag companion is requested, an application-side opt-in helper can keep the integration at
+the metadata boundary:
+
+```ruby
+def request_body_from_schema(schema:, component:, parameter_name:, source_name: nil, **options)
+  generated = Liminal.compile(schema, source_name: source_name, **options)
+  reference = Liminal::Components.register(
+    document: selected_openapi_document,
+    name: component,
+    schema: generated
+  )
+
+  parameter name: parameter_name, in: :body, required: true, schema: reference
+end
+```
+
+Application action-to-contract metadata remains outside Liminal. Request examples remain Rswag metadata and are not
+embedded into structural schemas.
+
+## Development
+
+Run `bundle exec rake` for randomized RSpec and RuboCop checks, `COVERAGE=true bundle exec rspec` for line and branch
+coverage, and `bundle exec rake build` to build the gem locally. The development suite validates a generated minimal
+document with `openapi3_parser` and compares representative non-coercing payload behavior with `json_schemer`.
+
+The project is versioned from `0.1.0` while its extension API is being proven. No release or publication is performed by
+the implementation workflow.

data/lib/liminal/adapters/dry_schema_v1.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Adapters
+    # Converts the documented dry-schema 1.x AST into semantic nodes. No raw
+    # AST layout escapes this adapter.
+    class DrySchemaV1
+      SetNode = Struct.new(:children, keyword_init: true)
+      FieldNode = Struct.new(:name, :required, :rule, keyword_init: true)
+      PredicateNode = Struct.new(:name, :arguments, keyword_init: true)
+      AndNode = Struct.new(:children, keyword_init: true)
+      OrNode = Struct.new(:children, keyword_init: true)
+      NullableNode = Struct.new(:rule, keyword_init: true)
+      ImplicationNode = Struct.new(:left, :right, keyword_init: true)
+      NotNode = Struct.new(:rule, keyword_init: true)
+      EachNode = Struct.new(:rule, keyword_init: true)
+      KeyNode = Struct.new(:name, :rule, keyword_init: true)
+      UnknownNode = Struct.new(:operation, keyword_init: true)
+
+      def call(ast)
+        visit(ast)
+      end
+
+      private
+
+      def visit(ast)
+        return UnknownNode.new(operation: :invalid_ast) unless ast.is_a?(Array) && ast.length == 2
+
+        operation, payload = ast
+        case operation
+        when :set then SetNode.new(children: array_payload(payload).map { |child| visit(child) })
+        when :and then visit_and(payload)
+        when :or then OrNode.new(children: array_payload(payload).map { |child| visit(child) })
+        when :implication then visit_implication(payload)
+        when :not then NotNode.new(rule: visit(payload))
+        when :each then EachNode.new(rule: visit(payload))
+        when :key then visit_key(payload)
+        when :predicate then visit_predicate(payload)
+        else UnknownNode.new(operation: operation || :invalid_ast)
+        end
+      end
+
+      def visit_and(payload)
+        children = array_payload(payload)
+        field = field_from_wrapper(children, required: true)
+        field || AndNode.new(children: children.map { |child| visit(child) })
+      end
+
+      def visit_implication(payload)
+        children = array_payload(payload)
+        field = field_from_wrapper(children, required: false)
+        return field if field
+        return NullableNode.new(rule: visit(children[1])) if nullable_guard?(children[0]) && children.length == 2
+
+        ImplicationNode.new(left: visit(children[0]), right: visit(children[1]))
+      end
+
+      def field_from_wrapper(children, required:)
+        return unless children.length == 2
+
+        name = key_presence_name(children[0])
+        key_ast = children[1]
+        return unless name && raw_operation(key_ast) == :key
+
+        key_name, rule_ast = key_ast[1]
+        return unless key_name.to_s == name.to_s
+
+        FieldNode.new(name: key_name.to_s, required: required, rule: visit(rule_ast))
+      end
+
+      def nullable_guard?(ast)
+        return false unless raw_operation(ast) == :not
+
+        predicate = ast[1]
+        raw_operation(predicate) == :predicate && predicate.dig(1, 0) == :nil?
+      end
+
+      def key_presence_name(ast)
+        return unless raw_operation(ast) == :predicate
+
+        name, tagged_arguments = ast[1]
+        return unless name == :key?
+
+        tagged_arguments.find { |tag, _value| tag == :name }&.last
+      end
+
+      def visit_key(payload)
+        name, rule = payload
+        KeyNode.new(name: name.to_s, rule: visit(rule))
+      end
+
+      def visit_predicate(payload)
+        name, tagged_arguments = payload
+        arguments = Array(tagged_arguments).filter_map do |tag, value|
+          value unless input_placeholder?(name, tag)
+        end
+        PredicateNode.new(name: name.to_sym, arguments: arguments.freeze)
+      end
+
+      def input_placeholder?(predicate, tag)
+        tag == :input ||
+          (predicate == :eql? && tag == :right) ||
+          (%i[true? false?].include?(predicate) && tag == :value)
+      end
+
+      def raw_operation(ast)
+        ast[0] if ast.is_a?(Array)
+      end
+
+      def array_payload(payload)
+        payload.is_a?(Array) ? payload : []
+      end
+    end
+  end
+end