assistant 0.1.0 → 1.0.0.rc1

data/lib/assistant/input_builder/registry.rbs

@@ -0,0 +1,13 @@
+# Type signatures for `lib/assistant/input_builder/registry.rb`.
+
+module Assistant::InputBuilder::Registry
+  @input_definitions: Hash[Symbol, Hash[Symbol, untyped]]
+
+  def input_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
+
+  def register_input_definition: (
+    name: Symbol,
+    type: untyped,
+    options: Hash[Symbol, untyped]
+  ) -> Hash[Symbol, untyped]
+end

data/lib/assistant/input_builder/require_validator.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Generators for the per-input requirement validators. Canonical names
+# (M9):
+#
+#   #valid_required_<name>?              # for `required: true`
+#   #valid_required_conditional_<name>?  # for `required: true, if: ...`
+#
+# Pre-M9 names (`valid_require_*?`, `valid_require_conditional_*?`) are
+# kept as deprecated aliases that delegate to the canonical method and
+# emit a one-shot `Kernel.warn` per call site. They are scheduled for
+# removal in `assistant 2.0`.
+module Assistant::InputBuilder::RequireValidator
+  # Guard so each deprecated alias warns at most once per textual call
+  # site (file + lineno), regardless of how many times it is invoked or
+  # how many input names are involved. Internal; tests reset it via
+  # `.send(:__reset_deprecation_warnings__)`.
+  DEPRECATION_WARNED = Set.new
+  private_constant :DEPRECATION_WARNED
+
+  # Emit the M9 one-shot deprecation warning for a `valid_require_*?`
+  # call. Deduped per `[canonical, caller path, caller lineno]` so the
+  # same call site never warns twice in one process.
+  #
+  # @param deprecated_name [Symbol] e.g. `:valid_require_name?`
+  # @param canonical_name  [Symbol] e.g. `:valid_required_name?`
+  # @param caller_location [Thread::Backtrace::Location]
+  # @return [void]
+  def self.warn_deprecated(deprecated_name, canonical_name, caller_location)
+    key = [canonical_name, caller_location.path, caller_location.lineno]
+    return if DEPRECATION_WARNED.include?(key)
+
+    DEPRECATION_WARNED << key
+    Kernel.warn("assistant: `##{deprecated_name}` is deprecated; use `##{canonical_name}` (removed in assistant 2.0)")
+  end
+
+  # Test-only hook: clears the per-call-site dedupe set so a single
+  # test process can exercise multiple "first warn" scenarios.
+  #
+  # @return [void]
+  def self.__reset_deprecation_warnings__
+    DEPRECATION_WARNED.clear
+  end
+
+  # Define `#valid_required_<name>?` on the host class plus the
+  # deprecated `#valid_require_<name>?` alias.
+  #
+  # @param name [Symbol] input name
+  # @return [void]
+  def input_require_validator_meth(name:, **)
+    canonical = :"valid_required_#{name}?"
+    define_required_validator(canonical:, name:, **)
+    define_deprecated_alias(:"valid_require_#{name}?", canonical)
+  end
+
+  # Define `#valid_required_conditional_<name>?` on the host class
+  # plus the deprecated `#valid_require_conditional_<name>?` alias.
+  #
+  # @param name [Symbol] input name
+  # @return [void]
+  def input_require_conditional_meth(name:, **)
+    canonical = :"valid_required_conditional_#{name}?"
+    define_required_conditional_validator(canonical:, name:, **)
+    define_deprecated_alias(:"valid_require_conditional_#{name}?", canonical)
+  end
+
+  private
+
+  def define_required_validator(canonical:, name:, **options)
+    allow_nil = options.fetch(:allow_nil, false) == true
+
+    define_method(canonical) do |log = true|
+      # M2: explicit nil counts as "supplied" when allow_nil: true is set.
+      return true if allow_nil && @inputs.key?(name)
+      return true if options[:required] == true && send("#{name}?") == true
+
+      log && send(
+        :log_item_error_initialize, attr_name: name, message: "Service is missing argument with name #{name}"
+      )
+      false
+    end
+  end
+
+  def define_required_conditional_validator(canonical:, name:, **options)
+    define_method(canonical) do
+      return false if send(:"valid_required_#{name}?", false) == false
+      return true if options[:if].call(send(name))
+
+      send(
+        :log_item_error_initialize,
+        attr_name: name,
+        message: "Service argument conditional requirement not met properly for #{name}"
+      )
+      false
+    end
+  end
+
+  def define_deprecated_alias(deprecated, canonical)
+    define_method(deprecated) do |*args, **kwargs|
+      ::Assistant::InputBuilder::RequireValidator.warn_deprecated(deprecated, canonical, caller_locations(1, 1).first)
+      send(canonical, *args, **kwargs)
+    end
+  end
+end

data/lib/assistant/input_builder/require_validator.rbs

@@ -0,0 +1,24 @@
+# Type signatures for `lib/assistant/input_builder/require_validator.rb`
+# (M9). Generates the canonical `valid_required_*?` and
+# `valid_required_conditional_*?` instance methods plus deprecated
+# `valid_require_*?` aliases.
+
+module Assistant::InputBuilder::RequireValidator
+  DEPRECATION_WARNED: Set[Array[untyped]]
+
+  def self.warn_deprecated: (Symbol deprecated_name, Symbol canonical_name, Thread::Backtrace::Location caller_location) -> void
+
+  def self.__reset_deprecation_warnings__: () -> void
+
+  def input_require_validator_meth: (name: Symbol, **untyped) -> Symbol
+
+  def input_require_conditional_meth: (name: Symbol, **untyped) -> Symbol
+
+  private
+
+  def define_required_validator: (canonical: Symbol, name: Symbol, **untyped) -> Symbol
+
+  def define_required_conditional_validator: (canonical: Symbol, name: Symbol, **untyped) -> Symbol
+
+  def define_deprecated_alias: (Symbol deprecated, Symbol canonical) -> Symbol
+end

data/lib/assistant/input_builder/type_validator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Generators for the per-input `valid_type_<name>?` validator (M3:
+# multi-type accepted; M2: `allow_nil:` short-circuits the check).
+module Assistant::InputBuilder::TypeValidator
+  # Define `#valid_type_<name>?` on the host class.
+  #
+  # @param name    [Symbol] input name
+  # @param type    [Class, Array<Class>] declared type(s); `Array(type)` is unioned
+  # @param options [Hash]   remaining `#input` keyword options (reads `:allow_nil`)
+  # @return [void]
+  def input_type_validator_meth(name:, type:, **options)
+    allow_nil = options.fetch(:allow_nil, false) == true
+    types = Array(type)
+    message_builder = type_mismatch_message_builder(name:, types:)
+    body = type_validator_body(name:, types:, allow_nil:, message_builder:)
+
+    define_method("valid_type_#{name}?", &body)
+  end
+
+  # Builds the Proc body for the per-input valid_type_<name>? method.
+  # Extracted to keep input_type_validator_meth under metric limits.
+  def type_validator_body(name:, types:, allow_nil:, message_builder:)
+    lambda do
+      value = @inputs[name]
+      # M2: when allow_nil: true is set, any supplied key short-circuits
+      # the type check (mirrors the require validator's behaviour).
+      next true if allow_nil && @inputs.key?(name)
+      next true if types.any? { |klass| value.is_a?(klass) }
+
+      send("#{name}?") &&
+        send(:log_item_error_initialize, attr_name: name, message: message_builder.call(send(name).class))
+      false
+    end
+  end
+
+  # Returns a Proc that, given the actual class of a failing input,
+  # produces the error message. Single-type keeps the original 0.1.0
+  # wording for back-compat; multi-type uses "is not one of […]". (M3)
+  def type_mismatch_message_builder(name:, types:)
+    if types.size == 1
+      ->(actual) { "Service argument with name #{name} is not a #{types.first} but #{actual}" }
+    else
+      ->(actual) { "Service argument with name #{name} is not one of [#{types.join(', ')}] but #{actual}" }
+    end
+  end
+end

data/lib/assistant/input_builder/type_validator.rbs

@@ -0,0 +1,18 @@
+# Type signatures for `lib/assistant/input_builder/type_validator.rb`
+# (M3 multi-type; M2 `allow_nil:`).
+
+module Assistant::InputBuilder::TypeValidator
+  def input_type_validator_meth: (name: Symbol, type: untyped, **untyped) -> Symbol
+
+  def type_validator_body: (
+    name: Symbol,
+    types: Array[untyped],
+    allow_nil: bool,
+    message_builder: ^(Class) -> String
+  ) -> ^() -> bool
+
+  def type_mismatch_message_builder: (
+    name: Symbol,
+    types: Array[untyped]
+  ) -> ^(Class) -> String
+end

data/lib/assistant/input_builder.rb

@@ -1,84 +1,28 @@
 # frozen_string_literal: true
 
-require 'assistant/refinements/string_blankness'
-
-module Assistant
-  # This module has the building blocks for the input validation.
-  # The building blocks of listing inputs with the #input and #inputs methods
-  # and the building blocks of validating inputs with the methods that are called within those methods.
-  module InputBuilder
-    using Assistant::Refinements::StringBlankness
-
-    # Lists all inputs that have the same type and options.
-    def inputs(attr_names, type:, **)
-      attr_names.each do |attr_name|
-        input(attr_name, type:, **)
-      end
-    end
-
-    # Individual input with a specific type or options
-    def input(attr_name, type:, **options)
-      # Base Methods
-      input_getter_meth(attr_name)
-      input_checker_meth(attr_name)
-
-      # Input type validation method, simple and conditional requirement validation methods
-      input_type_validator_meth(attr_name, type)
-      input_require_validator_meth(attr_name, **options) if options[:required] == true
-      input_require_conditional_meth(attr_name, **options) if options[:required] == true && options[:if]
-    end
-
-    def input_getter_meth(attr_name)
-      define_method(attr_name) do
-        @inputs[attr_name]
-      end
-    end
-
-    def input_checker_meth(attr_name)
-      define_method("#{attr_name}?") do
-        val = @inputs[attr_name]
-        return false if val.nil? || val == false
-        return !val.whitespace? if val.is_a?(String)
-
-        val.respond_to?(:empty?) ? !val.empty? : true
-      end
-    end
-
-    def input_require_validator_meth(attr_name, **options)
-      define_method("valid_require_#{attr_name}?") do |log = true|
-        return true if options[:required] == true && send("#{attr_name}?") == true
-
-        log && send(
-          :log_item_error_initialize, attr_name:, message: "Service is missing argument with name #{attr_name}"
-        )
-        false
-      end
-    end
-
-    def input_require_conditional_meth(attr_name, **options)
-      define_method("valid_require_conditional_#{attr_name}?") do
-        return false if send("valid_require_#{attr_name}?", false) == false
-        return true if options[:if].call(send(attr_name))
-
-        send(
-          :log_item_error_initialize,
-          attr_name:, message: "Service argument conditional requirement not met properly for #{attr_name}"
-        )
-        false
-      end
-    end
-
-    def input_type_validator_meth(attr_name, type)
-      define_method("valid_type_#{attr_name}?") do
-        return true if @inputs[attr_name].is_a?(type)
-
-        send("#{attr_name}?") &&
-          send(
-            :log_item_error_initialize,
-            attr_name:, message: "Service argument with name #{attr_name} is not a #{type} but #{send(attr_name).class}"
-          )
-        false
-      end
-    end
-  end
+# Umbrella for the input DSL. Each submodule owns one cohesive
+# responsibility; this file wires them into a single `Assistant::InputBuilder`
+# module that `Service` extends. (M13, v1 plan)
+require 'assistant/input_builder/accessors'
+require 'assistant/input_builder/default_option'
+require 'assistant/input_builder/dsl'
+require 'assistant/input_builder/optional_option'
+require 'assistant/input_builder/registry'
+require 'assistant/input_builder/require_validator'
+require 'assistant/input_builder/type_validator'
+
+# Declarative input DSL for `Assistant::Service` subclasses. `#input`
+# registers a definition and generates the per-input reader, `?`-checker,
+# type validator, and (when `required:` is set) requirement validator(s).
+# Behaviour is unchanged from pre-M13; the umbrella only re-exports the
+# submodule methods. See the per-submodule files for the specific concern
+# each owns.
+module Assistant::InputBuilder
+  include Registry
+  include DefaultOption
+  include OptionalOption
+  include Accessors
+  include RequireValidator
+  include TypeValidator
+  include Dsl
 end

data/lib/assistant/input_builder.rbs

@@ -0,0 +1,15 @@
+# Type signatures for `lib/assistant/input_builder.rb` — the umbrella
+# module that includes every per-concern submodule. The submodule
+# signatures live alongside the corresponding `.rb` files under
+# `lib/assistant/input_builder/`. See docs/v1/01-api-surface.md and
+# docs/v1/02-features.md (M13).
+
+module Assistant::InputBuilder
+  include Registry
+  include DefaultOption
+  include OptionalOption
+  include Accessors
+  include RequireValidator
+  include TypeValidator
+  include Dsl
+end

data/lib/assistant/log_item.rb

@@ -1,24 +1,67 @@
 # frozen_string_literal: true
 
 module Assistant
-  # Log base class
+  # A single structured log entry produced by `Service` (directly via
+  # `LogList#add_log` or through one of the `log_item_*` shorthands).
+  # Construction is **strict** since 1.0 (M10): invalid attributes raise
+  # `ArgumentError` rather than producing an instance whose `#valid?`
+  # returns `false`. See `docs/v1/06-migration-0x-to-1.md` for the
+  # rationale.
+  #
+  # @example Build an error log entry
+  #   Assistant::LogItem.new(
+  #     level: :error,
+  #     source: :create_user,
+  #     detail: :email,
+  #     message: 'must not be blank'
+  #   )
   class LogItem
+    # The exhaustive set of accepted `level:` values, in display order.
+    # @return [Array<Symbol>]
     VALID_LEVELS = %i[info warning error].freeze
 
+    # Validation rules applied in `#initialize`. Each entry pairs a
+    # human message with the predicate that must hold. Internal.
+    # @api private
+    ERRORS = [
+      ["level must be one of [#{VALID_LEVELS.join(', ')}]", :valid_level?],
+      ['source must be present and different from detail', :valid_source?],
+      ['detail must be present and different from source', :valid_detail?],
+      ['message must be present', :valid_message?]
+    ].freeze
+
+    # @return [Symbol] severity (`:info`, `:warning`, or `:error`)
+    # @!attribute [r] level
+    # @return [Symbol] high-level subsystem the entry came from (e.g. `:initialize`, `:hook`)
+    # @!attribute [r] source
+    # @return [Symbol] finer-grained detail under `source` (often an attribute name)
+    # @!attribute [r] detail
+    # @return [String] human-readable message
+    # @!attribute [r] message
+    # @return [Array<String>, nil] optional backtrace captured at construction
+    # @!attribute [r] trace
     attr_reader :level, :source, :detail, :message, :trace
 
+    # @param level   [Symbol, #to_sym] one of {VALID_LEVELS}
+    # @param source  [Symbol, #to_sym] subsystem identifier; must differ from `detail`
+    # @param detail  [Symbol, #to_sym] sub-identifier; must differ from `source`
+    # @param message [#to_s] human-readable message; must not be blank
+    # @param trace   [Array<String>, nil] optional backtrace
+    # @raise [ArgumentError] when any of the constructor checks in {ERRORS} fail
     def initialize(level:, source:, detail:, message:, trace: nil)
-      @level = level.to_sym
-      @source = source.to_sym
-      @detail = detail.to_sym
+      @level = normalize_symbol(level)
+      @source = normalize_symbol(source)
+      @detail = normalize_symbol(detail)
       @message = message.to_s
       @trace = trace
+      validate!
     end
 
-    def valid?
-      [valid_level?, valid_source?, valid_detail?, valid_message?].all?
-    end
+    # @return [Boolean] always `true` for instances constructed via {#initialize} (which raises on invalid input).
+    #   Retained for introspection and downstream tooling.
+    def valid? = [valid_level?, valid_source?, valid_detail?, valid_message?].all?
 
+    # @return [Hash{Symbol => Object}] hash view with keys `:level`, `:source`, `:detail`, `:message`, `:trace`
     def item
       { level:, source:, detail:, message:, trace: }
     end
@@ -30,20 +73,35 @@ module Assistant
       end
     end
 
-    def valid_level?
-      VALID_LEVELS.include?(level)
-    end
+    # @return [Boolean] true when `level` is one of {VALID_LEVELS}
+    def valid_level? = VALID_LEVELS.include?(level)
+
+    # @return [Boolean] true when `source` is non-empty and not equal to `detail`
+    def valid_source? = present_log_attribute?(source) && detail != source
+
+    # @return [Boolean] true when `detail` is non-empty and not equal to `source`
+    def valid_detail? = present_log_attribute?(detail) && source != detail
 
-    def valid_source?
-      source.size.positive? && detail != source
+    # @return [Boolean] true when `message` contains at least one non-whitespace character
+    def valid_message? = !message.strip.empty?
+
+    private
+
+    def validate!
+      errors = validation_errors
+      return if errors.empty?
+
+      raise ArgumentError, "invalid LogItem: #{errors.join('; ')}"
     end
 
-    def valid_detail?
-      detail.size.positive? && source != detail
+    def validation_errors = ERRORS.reject { |_, validation_method| send(validation_method) }.map(&:first)
+
+    def normalize_symbol(value)
+      value.respond_to?(:to_sym) ? value.to_sym : value
     end
 
-    def valid_message?
-      message.size.positive?
+    def present_log_attribute?(value)
+      value.respond_to?(:size) && value.size.positive?
     end
   end
 end

data/lib/assistant/log_item.rbs

@@ -0,0 +1,40 @@
+# Type signatures for `lib/assistant/log_item.rb`. See
+# docs/v1/01-api-surface.md for the frozen surface.
+
+class Assistant::LogItem
+  VALID_LEVELS: Array[Symbol]
+  ERRORS: Array[[String, Symbol]]
+
+  attr_reader level: Symbol
+  attr_reader source: Symbol
+  attr_reader detail: Symbol
+  attr_reader message: String
+  attr_reader trace: untyped
+
+  def initialize: (
+    detail: Symbol | String,
+    message: String | _ToS,
+    level: Symbol | String,
+    source: Symbol | String,
+    ?trace: untyped
+  ) -> void
+
+  def valid?: () -> bool
+  def valid_level?: () -> bool
+  def valid_source?: () -> bool
+  def valid_detail?: () -> bool
+  def valid_message?: () -> bool
+
+  def info?: () -> bool
+  def warning?: () -> bool
+  def error?: () -> bool
+
+  def item: () -> Hash[Symbol, untyped]
+
+  private
+
+  def validate!: () -> void
+  def validation_errors: () -> Array[String]
+  def normalize_symbol: (untyped value) -> untyped
+  def present_log_attribute?: (untyped value) -> bool
+end

data/lib/assistant/log_list.rb

@@ -1,26 +1,52 @@
 # frozen_string_literal: true
 
-module Assistant
-  # Service level list of logs
-  module LogList
-    def add_log(level:, source:, detail:, message:, trace: nil)
-      @logs << Assistant::LogItem.new(level:, source:, detail:, message:, trace:)
-    end
+# Mixin that gives `Assistant::Service` its log timeline. Owns the
+# `@logs` array and exposes the public helpers (`#add_log`, `#merge_logs`,
+# the `log_item_*` shorthands, `#infos` / `#warnings` / `#errors`) used
+# by service code to record observations and by callers to read the
+# result.
+module Assistant::LogList
+  # Append a single {Assistant::LogItem} to the timeline.
+  #
+  # @param level   [Symbol] `:info`, `:warning`, or `:error`
+  # @param source  [Symbol] subsystem identifier
+  # @param detail  [Symbol] sub-identifier (often an attribute name)
+  # @param message [String] human-readable message
+  # @param trace   [Array<String>, nil] optional backtrace
+  # @return [Array<Assistant::LogItem>] the updated timeline
+  # @raise [ArgumentError] if {Assistant::LogItem#initialize} rejects the inputs
+  def add_log(level:, source:, detail:, message:, trace: nil)
+    @logs << Assistant::LogItem.new(level:, source:, detail:, message:, trace:)
+  end
 
-    def merge_logs(other_logs)
-      @logs.concat(other_logs)
-    end
+  # Concatenate an existing log timeline onto this service's `@logs`,
+  # preserving insertion order. Used by `Service#call_service` (M-S2).
+  #
+  # @param logs [Array<Assistant::LogItem>] entries to append
+  # @return [Array<Assistant::LogItem>] the updated timeline
+  def merge_logs(logs:)
+    @logs.concat(logs)
+  end
+
+  # Convenience used by InputBuilder-generated validators to record an
+  # initialization-time error for a specific input attribute.
+  #
+  # @param attr_name [Symbol] the offending input name (recorded as `detail`)
+  # @param message   [String] human-readable explanation
+  # @return [Array<Assistant::LogItem>] the updated timeline
+  def log_item_error_initialize(attr_name:, message:)
+    @logs << Assistant::LogItem.new(detail: attr_name, level: :error, message:, source: :initialize)
+  end
 
-    # Convenience used by InputBuilder-generated validators to record an
-    # initialization-time error for a specific input attribute.
-    def log_item_error_initialize(attr_name:, message:)
-      @logs << Assistant::LogItem.new(detail: attr_name, level: :error, message:, source: :initialize)
+  ::Assistant::LogItem::VALID_LEVELS.each do |level|
+    define_method("#{level}s") do
+      @logs.select { |log| log.send("#{level}?") }
     end
 
-    ::Assistant::LogItem::VALID_LEVELS.each do |level|
-      define_method("#{level}s") do
-        @logs.select { |log| log.send("#{level}?") }
-      end
+    # Shorthand: log_item_info / log_item_warning / log_item_error.
+    # See docs/v1/02-features.md M5.
+    define_method("log_item_#{level}") do |source:, detail:, message:, trace: nil|
+      add_log(level:, source:, detail:, message:, trace:)
     end
   end
 end

data/lib/assistant/log_list.rbs

@@ -0,0 +1,48 @@
+# Type signatures for `lib/assistant/log_list.rb`. See
+# docs/v1/01-api-surface.md for the frozen surface.
+#
+# `Assistant::LogList` is mixed into `Assistant::Service`; the `@logs`
+# instance variable it operates on is declared on `Service` itself.
+
+module Assistant::LogList
+  def add_log: (
+    detail: Symbol | String,
+    level: Symbol | String,
+    message: String | _ToS,
+    source: Symbol | String,
+    ?trace: untyped
+  ) -> Array[Assistant::LogItem]
+
+  def merge_logs: (logs: Array[Assistant::LogItem]) -> Array[Assistant::LogItem]
+
+  def log_item_error_initialize: (
+    attr_name: Symbol | String,
+    message: String | _ToS
+  ) -> Array[Assistant::LogItem]
+
+  # M5 shorthands: `log_item_info`, `log_item_warning`, `log_item_error`.
+  def log_item_info: (
+    detail: Symbol | String,
+    message: String | _ToS,
+    source: Symbol | String,
+    ?trace: untyped
+  ) -> Array[Assistant::LogItem]
+
+  def log_item_warning: (
+    detail: Symbol | String,
+    message: String | _ToS,
+    source: Symbol | String,
+    ?trace: untyped
+  ) -> Array[Assistant::LogItem]
+
+  def log_item_error: (
+    detail: Symbol | String,
+    message: String | _ToS,
+    source: Symbol | String,
+    ?trace: untyped
+  ) -> Array[Assistant::LogItem]
+
+  def infos: () -> Array[Assistant::LogItem]
+  def warnings: () -> Array[Assistant::LogItem]
+  def errors: () -> Array[Assistant::LogItem]
+end