abstracta-contracts 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec5dbea4ff031eb0fc61d786f5e5c443b0f9ecb6570e4f914531d4db4ae9e19d
-  data.tar.gz: 5c03262e0801b1be7cec8f63ef3d9a8338ef363888abbbc95d135d0ec5df4155
+  metadata.gz: e53d4729e866578c1bf2c42041f2d31e6342014dd9e7630ed8b20a3a61d7ed7d
+  data.tar.gz: 5a41643d7443f7a2d615b85a0f356f4d29ea2d657c29bc0574a7aaff147a7d08
 SHA512:
-  metadata.gz: 78c6dd7e8fe309f40d7e58a6485b01c3852a921c95064a9bb452ae834f3d81365bfe92f8abc254a17eedcef62993be46417ca6db26cf5d2f7b18cf8ea23eb727
-  data.tar.gz: 0c2218ef59335cf982a665184427c103aba124d78a7ee8e14966ec50db413196273ac9c0712c42ad5db45636c3264c8d87b711545443084d3f47a81edff9083f
+  metadata.gz: ba6cacb1bf1693a2ef04cd0b21eec16c42493b4e5a4509f0afd4ac09845b7acb1bd0a8ee1be23beae3bda1110e22a8e1187350f715e97d91a89aa80a535d8463
+  data.tar.gz: 6873cef89d4ca90309737095debf5b0f03d0db8d3a02b7da2eb13423909558e98157f8894745d31dff54e790dd2276a5a1f53610b3e00f2deea9d2be63dc1c6b

data/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 All notable changes to AbstractaContracts will be documented in this file.
 
-## [0.1.0] - Unreleased
+## Unreleased
+
+## [0.1.1] - 2026-09-08
+
+### Added
+
+- Public YARD reference, generation task, and documentation check in CI.
+
+### Changed
+
+- Group interface specs by definition, implementation, inheritance, and introspection.
+- Make each spec explicitly load its helper for standalone execution.
+- Correct the reusable-contract README example to preserve local variable scope.
+
+## [0.1.0] - 2026-09-04
 
 ### Added
 

data/README.md

@@ -89,7 +89,7 @@ end
 ```ruby
 cache_contract = AbstractaContracts.with_methods(:read, :write, :delete)
 
-class RedisCache
+RedisCache = Class.new do
   include cache_contract
 
   def read(key) = nil
@@ -186,6 +186,23 @@ RedisCache.missing_interface_class_methods
 - Interface requirements can be satisfied by the class, inherited implementations, or interface defaults.
 - AbstractaContracts has no runtime dependencies.
 
+## API reference
+
+Run `bundle exec rake yard` and open `doc/index.html` for the public API.
+The DSL entries on the AbstractaContracts page are methods installed on
+consuming classes. Implementation details under `Internal` are unsupported.
+Interface modules expose `interface?` (always true), `interface_methods`, and
+`interface_class_methods` (frozen, deduplicated symbol arrays including parent
+interfaces). Use `implements` to register an interface for validation; ordinary
+Ruby inclusion alone does not register it as a class requirement.
+
+Validation checks presence, not arity, argument types, or return values.
+The constructor guard validates before forwarding arguments and blocks to
+`new`; it does not prevent lower-level allocation or arbitrary Ruby overrides.
+Rescue `AbstractaContracts::Error` for contract failures. Empty factory inputs
+raise `ArgumentError`; including a factory result in the wrong kind of object
+raises `TypeError`.
+
 ## Development
 
 ```bash

data/lib/abstracta_contracts/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module AbstractaContracts
-  VERSION = "0.1.0"
+  # Current gem version.
+  # @return [String]
+  VERSION = "0.1.1"
 end

data/lib/abstracta_contracts.rb

@@ -7,15 +7,141 @@ require_relative "abstracta_contracts/internal/constructor_guard"
 require_relative "abstracta_contracts/internal/contract"
 require_relative "abstracta_contracts/internal/interface"
 
+# Declarative abstract classes and reusable interfaces.
+#
+# Include this module in a class to install the class DSL documented below.
+# The instance-method entries on this page describe methods installed on the
+# consuming class, not methods on its instances or on AbstractaContracts itself.
+# Contracts check method presence and ownership, not signatures or return types.
+# Private and protected implementations count as present.
+#
+# @example Declare and implement a contract
+#   class Reader
+#     include AbstractaContracts.with_methods(:read)
+#   end
+#   class FileReader < Reader
+#     def read = :contents
+#   end
+#   FileReader.new.read # => :contents
 module AbstractaContracts
+  # @!method abstract_class!
+  #   Mark only this class explicitly abstract; descendants do not inherit the marker.
+  #   @return [Class] self
+  #
+  # @!method abstract_method(*names)
+  #   Declare inherited instance requirements. Redeclaration requires a fresh implementation.
+  #   @return [Class] self
+  #   @param names [Array<String, Symbol, Array>] names to flatten and deduplicate
+  #   @raise [AbstractaContracts::Error] for invalid method names
+  #
+  # @!method abstract_class_method(*names)
+  #   Declare inherited class requirements. Redeclaration requires a fresh implementation.
+  #   @return [Class] self
+  #   @param names [Array<String, Symbol, Array>] names to flatten and deduplicate
+  #   @raise [AbstractaContracts::Error] for invalid method names
+  #
+  # @!method implements(*interfaces)
+  #   Register interfaces and include their modules. Repeated registrations are deduplicated.
+  #   @return [Class] self
+  #   @param interfaces [Array<Module, Array>] interface modules, optionally nested
+  #   @raise [AbstractaContracts::Error] if any module is not an interface
+  #
+  # @!method explicitly_abstract?
+  #   Whether this class itself was marked explicitly abstract.
+  #   @return [Boolean]
+  #
+  # @!method abstract?
+  #   Whether explicitly abstract or missing any abstract or interface requirement.
+  #   @return [Boolean]
+  #
+  # @!method concrete?
+  #   Whether this class can pass contract validation.
+  #   @return [Boolean]
+  #
+  # @!method valid_implementation?
+  #   Whether this class is concrete, including its explicit abstract marker.
+  #   @return [Boolean]
+  #
+  # @!method validate_implementation!
+  #   Validate all requirements and the explicit abstract marker without constructing an instance.
+  #   @return [true] when concrete
+  #   @raise [AbstractaContracts::Error] if methods are missing or the class is explicitly abstract
+  #
+  # @!method abstract_methods
+  #   Required abstract instance names, including inherited declarations.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method abstract_class_methods
+  #   Required abstract class names, including inherited declarations.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method direct_interfaces
+  #   Interfaces registered directly on this class.
+  #   @return [Array<Module>] frozen snapshot
+  #
+  # @!method interfaces
+  #   Registered interfaces including class inheritance and interface ancestry.
+  #   @return [Array<Module>] deduplicated frozen snapshot
+  #
+  # @!method implements?(interface)
+  #   Whether an interface occurs in the complete registered interface hierarchy.
+  #   @return [Boolean]
+  #   @param interface [Module] an interface module
+  #   @raise [AbstractaContracts::Error] if the argument is not an interface
+  #
+  # @!method interface_methods
+  #   Required instance names from all registered interfaces.
+  #   @return [Array<Symbol>] deduplicated frozen names
+  #
+  # @!method interface_class_methods
+  #   Required class names from all registered interfaces.
+  #   @return [Array<Symbol>] deduplicated frozen names
+  #
+  # @!method missing_abstract_methods
+  #   Unresolved abstract instance requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method missing_abstract_class_methods
+  #   Unresolved abstract class requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method missing_interface_methods
+  #   Unresolved interface instance requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method missing_interface_class_methods
+  #   Unresolved interface class requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method missing_methods
+  #   Unresolved combined abstract and interface instance requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @!method missing_class_methods
+  #   Unresolved combined abstract and interface class requirements.
+  #   @return [Array<Symbol>] frozen names
+  #
+  # @private
   MUTEX_CREATION_LOCK = Mutex.new
   private_constant :MUTEX_CREATION_LOCK
 
   class << self
+    # @private
     def included(base)
       install(base)
     end
 
+    # Build a reusable abstract contract for inclusion in classes.
+    # Names are flattened, converted to symbols, and deduplicated. Requirements
+    # are inherited; redeclarations require an implementation at or below the
+    # new declaration in the method lookup chain.
+    # @param methods [Array<String, Symbol, Array>] instance method names
+    # @param class_methods [Array<String, Symbol>] class method names
+    # @return [Module] reusable contract; include it in each consuming class
+    # @raise [ArgumentError] if both lists are empty
+    # @raise [AbstractaContracts::Error] if a name is neither a string nor a symbol,
+    #   is empty, or contains whitespace
+    # @raise [TypeError] when the returned contract is included in a module
     def with_methods(*methods, class_methods: [])
       instance_methods = normalize_method_names(methods)
       singleton_methods = normalize_method_names(Array(class_methods))
@@ -27,6 +153,24 @@ module AbstractaContracts
       Internal::Contract.new(instance_methods: instance_methods, class_methods: singleton_methods)
     end
 
+    # Build an interface definition for inclusion in a module.
+    # Include the result once in a module, then use the class DSL's implements
+    # method to register that module. Interfaces may include other interfaces
+    # and supply default instance methods. Inherited implementations also count.
+    # @param methods [Array<String, Symbol, Array>] instance method names
+    # @param class_methods [Array<String, Symbol>] class method names
+    # @return [Module] definition to include in an interface module
+    # @raise [ArgumentError] if both lists are empty
+    # @raise [AbstractaContracts::Error] for invalid names or repeated definition
+    # @raise [TypeError] when the definition is included in a class
+    # @example Define and implement an interface
+    #   readable = Module.new { include AbstractaContracts.interface(:read) }
+    #   reader = Class.new do
+    #     include AbstractaContracts
+    #     implements readable
+    #     def read = :contents
+    #   end
+    #   reader.new.read # => :contents
     def interface(*methods, class_methods: [])
       instance_methods = normalize_method_names(methods)
       singleton_methods = normalize_method_names(Array(class_methods))
@@ -38,6 +182,7 @@ module AbstractaContracts
       Internal::Interface.new(instance_methods: instance_methods, class_methods: singleton_methods)
     end
 
+    # @private
     def install(base)
       raise TypeError, "AbstractaContracts can only be included in classes" unless base.is_a?(Class)
 
@@ -47,6 +192,7 @@ module AbstractaContracts
       base
     end
 
+    # @private
     def define_interface(base, instance_methods:, class_methods:)
       if base.instance_variable_defined?(:@abstracta_contracts_interface_defined)
         raise Internal::InterfaceAlreadyDefinedError,
@@ -60,20 +206,24 @@ module AbstractaContracts
       base
     end
 
+    # @private
     def interface?(object)
       object.is_a?(Module) && object.respond_to?(:interface?) && object.interface?
     end
 
+    # @private
     def validate_interface!(interface)
       return interface if interface?(interface)
 
       raise Internal::InvalidInterfaceError, "#{interface.inspect} is not an AbstractaContracts interface"
     end
 
+    # @private
     def normalize_interfaces(interfaces)
       interfaces.flatten.map { |interface| validate_interface!(interface) }.uniq.freeze
     end
 
+    # @private
     def normalize_method_names(names)
       names.flatten.map do |name|
         unless name.is_a?(String) || name.is_a?(Symbol)
@@ -89,6 +239,7 @@ module AbstractaContracts
       end.uniq.freeze
     end
 
+    # @private
     def register_instance_methods(base, names)
       install(base)
       synchronize(base) do
@@ -97,6 +248,7 @@ module AbstractaContracts
       end
     end
 
+    # @private
     def register_class_methods(base, names)
       install(base)
       synchronize(base) do
@@ -105,26 +257,31 @@ module AbstractaContracts
       end
     end
 
+    # @private
     def required_instance_methods_for(klass)
       required_methods_for(klass, :abstracta_contracts_declared_instance_methods)
     end
 
+    # @private
     def required_class_methods_for(klass)
       required_methods_for(klass, :abstracta_contracts_declared_class_methods)
     end
 
+    # @private
     def missing_instance_methods_for(klass)
       required_instance_methods_for(klass).filter_map do |name, declaration_owner|
         name unless implemented_after_declaration?(klass, name, declaration_owner, singleton: false)
       end
     end
 
+    # @private
     def missing_class_methods_for(klass)
       required_class_methods_for(klass).filter_map do |name, declaration_owner|
         name unless implemented_after_declaration?(klass, name, declaration_owner, singleton: true)
       end
     end
 
+    # @private
     def interfaces_for(klass)
       result = []
 
@@ -140,6 +297,7 @@ module AbstractaContracts
       result
     end
 
+    # @private
     def interface_instance_methods_for(interface)
       validate_interface!(interface)
       interface_hierarchy(interface).flat_map do |candidate|
@@ -147,6 +305,7 @@ module AbstractaContracts
       end.uniq.freeze
     end
 
+    # @private
     def interface_class_methods_for(interface)
       validate_interface!(interface)
       interface_hierarchy(interface).flat_map do |candidate|
@@ -154,40 +313,48 @@ module AbstractaContracts
       end.uniq.freeze
     end
 
+    # @private
     def required_interface_instance_methods_for(klass)
       interfaces_for(klass).flat_map { |interface| interface_instance_methods_for(interface) }.uniq
     end
 
+    # @private
     def required_interface_class_methods_for(klass)
       interfaces_for(klass).flat_map { |interface| interface_class_methods_for(interface) }.uniq
     end
 
+    # @private
     def missing_interface_instance_methods_for(klass)
       required_interface_instance_methods_for(klass).reject do |name|
         method_available?(klass, name, singleton: false)
       end
     end
 
+    # @private
     def missing_interface_class_methods_for(klass)
       required_interface_class_methods_for(klass).reject do |name|
         method_available?(klass, name, singleton: true)
       end
     end
 
+    # @private
     def synchronize(base, &)
       mutex_for(base).synchronize(&)
     end
 
+    # @private
     def class_name(klass)
       klass.name || klass.inspect
     end
 
+    # @private
     def interface_name(interface)
       interface.name || interface.inspect
     end
 
     private
 
+    # @private
     def mutex_for(base)
       if base.instance_variable_defined?(:@abstracta_contracts_mutex)
         return base.instance_variable_get(:@abstracta_contracts_mutex)
@@ -199,6 +366,7 @@ module AbstractaContracts
       end
     end
 
+    # @private
     def required_methods_for(klass, reader)
       declarations = {}
 
@@ -212,6 +380,7 @@ module AbstractaContracts
       declarations.freeze
     end
 
+    # @private
     def implemented_after_declaration?(klass, name, declaration_owner, singleton:)
       lookup_class = singleton ? klass.singleton_class : klass
       declaration_lookup_owner = singleton ? declaration_owner.singleton_class : declaration_owner
@@ -228,6 +397,7 @@ module AbstractaContracts
       false
     end
 
+    # @private
     def method_available?(klass, name, singleton:)
       lookup = singleton ? klass.singleton_class : klass
       lookup.instance_method(name)
@@ -236,6 +406,7 @@ module AbstractaContracts
       false
     end
 
+    # @private
     def interface_hierarchy(interface)
       validate_interface!(interface)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abstracta-contracts
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Juan Furattini