assistant 0.1.0 → 1.0.0.rc1

data/lib/assistant/rbs_generator/cli.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Assistant::RbsGenerator
+  # Command-line entry point. Parses argv, loads the input files,
+  # discovers Service subclasses, renders, writes.
+  class Cli
+    # Usage banner printed by `--help`.
+    # @return [String]
+    USAGE = <<~USAGE
+      Usage: assistant-rbs [PATH...] [--output DIR] [--quiet]
+
+      Loads every Ruby file under the given PATHs (default: lib/) and
+      writes one .rbs file per Assistant::Service subclass found, under
+      DIR (default: sig/).
+
+      Existing .rbs files without the generator marker comment on their
+      first line are left untouched.
+    USAGE
+
+    class << self
+      # Convenience wrapper that builds a `Cli` and runs it.
+      #
+      # @param argv   [Array<String>] command-line arguments
+      # @param stdout [IO] output stream for non-error messages
+      # @param stderr [IO] output stream for warnings and errors
+      # @return [Integer] process exit status (0 on success)
+      def run(argv, stdout: $stdout, stderr: $stderr)
+        new(argv, stdout:, stderr:).run
+      end
+    end
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv
+      @stdout = stdout
+      @stderr = stderr
+      @output_dir = Assistant::RbsGenerator::DEFAULT_OUTPUT_DIR
+      @quiet = false
+      @paths = nil
+    end
+
+    # Returns an exit status (0 on success, non-zero on failure).
+    def run
+      parse_options!
+      before = service_subclasses
+      load_paths(@paths || Assistant::RbsGenerator::DEFAULT_INPUT_PATHS)
+      emit(service_subclasses - before)
+      0
+    rescue SystemExit => e
+      e.status
+    end
+
+    private
+
+    def emit(services)
+      writer = Assistant::RbsGenerator::Writer.new(
+        output_dir: @output_dir, quiet: @quiet, stdout: @stdout, stderr: @stderr
+      )
+      services.sort_by(&:name).each do |service_class|
+        writer.write(service_class, Assistant::RbsGenerator::Renderer.render(service_class))
+      end
+    end
+
+    def parse_options!
+      OptionParser.new { |opts| configure_parser(opts) }.then { |p| @paths = p.parse(@argv) }
+    end
+
+    def configure_parser(opts)
+      opts.banner = USAGE
+      default = Assistant::RbsGenerator::DEFAULT_OUTPUT_DIR
+      opts.on('-o', '--output DIR', "Output directory (default: #{default})") do |dir|
+        @output_dir = dir
+      end
+      opts.on('-q', '--quiet', 'Suppress non-error output') { @quiet = true }
+      opts.on('-h', '--help', 'Show this message') do
+        @stdout.puts opts
+        raise SystemExit, 0
+      end
+    end
+
+    def load_paths(paths)
+      paths.each do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, '**/*.rb')).each { |file| safe_require(file) }
+        elsif File.file?(path)
+          safe_require(path)
+        else
+          @stderr.puts "[warn]      no such file or directory: #{path}"
+        end
+      end
+    end
+
+    def safe_require(path)
+      require File.expand_path(path)
+    rescue LoadError, StandardError => e
+      @stderr.puts "[warn]      failed to load #{path}: #{e.class}: #{e.message}"
+    end
+
+    # Snapshot of every loaded Service subclass. Used to diff before /
+    # after `load_paths` so we only emit signatures for classes whose
+    # source files we were actually asked to scan -- this keeps a
+    # long-running process (or a test suite) from re-emitting sigs for
+    # every Service subclass it has ever seen.
+    def service_subclasses
+      ObjectSpace.each_object(Class).select { |klass| klass < Assistant::Service && klass.name }
+    end
+  end
+end

data/lib/assistant/rbs_generator/cli.rbs

@@ -0,0 +1,24 @@
+class Assistant::RbsGenerator::Cli
+  USAGE: String
+
+  @argv: Array[String]
+  @stdout: IO
+  @stderr: IO
+  @output_dir: String
+  @quiet: bool
+  @paths: Array[String]?
+
+  def self.run: (Array[String] argv, ?stdout: IO, ?stderr: IO) -> Integer
+
+  def initialize: (Array[String] argv, ?stdout: IO, ?stderr: IO) -> void
+  def run: () -> Integer
+
+  private
+
+  def emit: (Array[singleton(Assistant::Service)] services) -> void
+  def parse_options!: () -> void
+  def configure_parser: (OptionParser opts) -> void
+  def load_paths: (Array[String] paths) -> void
+  def safe_require: (String path) -> void
+  def service_subclasses: () -> Array[singleton(Assistant::Service)]
+end

data/lib/assistant/rbs_generator/renderer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Converts a Service subclass to a `.rbs` source string. Pure
+# function; does no I/O.
+module Assistant::RbsGenerator::Renderer
+  class << self
+    # Render a `.rbs` source string for the given `Service` subclass.
+    # Module-prefix segments of the class name are wrapped in nested
+    # `module ... end` blocks; the trailing segment becomes the
+    # `class X < Assistant::Service` declaration. The body lists one
+    # `def name: () -> Type` and `def name?: () -> bool` per declared
+    # input.
+    #
+    # @param service_class [Class<Assistant::Service>]
+    # @return [String] the rendered `.rbs` source, ending with a newline
+    # @raise [RuntimeError] when `service_class` is anonymous or declares
+    #   an input with a non-Class / anonymous `type:`
+    def render(service_class)
+      name = service_class.name or raise 'anonymous Service class cannot be rendered'
+      segments = name.split('::')
+      # `String#split` on a non-empty string always returns at least
+      # one element, but Steep can't prove that -- guard for narrowing.
+      class_name = segments.pop or raise "unexpected empty name for #{service_class.inspect}"
+      body_lines = render_class_body(class_name, service_class.input_definitions)
+      nested_lines = nest_in_modules(segments, body_lines)
+      "#{[Assistant::RbsGenerator::MARKER, '', *nested_lines].join("\n")}\n"
+    end
+
+    private
+
+    def render_class_body(class_name, definitions)
+      header = "class #{class_name} < Assistant::Service"
+      method_lines = definitions.flat_map { |name, options| input_method_lines(name, options) }
+      return [header, 'end'] if method_lines.empty?
+
+      [header, '', *method_lines.map { |line| "  #{line}" }, '', 'end']
+    end
+
+    def nest_in_modules(segments, body_lines)
+      segments.reverse.reduce(body_lines) do |body, segment|
+        indented = body.map { |line| line.empty? ? '' : "  #{line}" }
+        ["module #{segment}", *indented, 'end']
+      end
+    end
+
+    def input_method_lines(name, options)
+      [
+        "def #{name}: () -> #{render_type(name, options)}",
+        "def #{name}?: () -> bool"
+      ]
+    end
+
+    def render_type(name, options)
+      raise "input #{name.inspect} has no `type:` declared" unless options.key?(:type)
+
+      rendered = Array(options[:type]).map { |type| render_single_type(name, type) }
+      union = rendered.length == 1 ? rendered.first : "(#{rendered.join(' | ')})"
+      options[:allow_nil] == true ? "#{union}?" : union
+    end
+
+    def render_single_type(name, type)
+      raise "input #{name.inspect} has non-Class type #{type.inspect}" unless type.is_a?(Module)
+
+      type.name || raise("input #{name.inspect} has anonymous type")
+    end
+  end
+end

data/lib/assistant/rbs_generator/renderer.rbs

@@ -0,0 +1,11 @@
+module Assistant::RbsGenerator::Renderer
+  def self.render: (singleton(Assistant::Service) service_class) -> String
+
+  private
+
+  def self.render_class_body: (String class_name, Hash[Symbol, untyped] definitions) -> Array[String]
+  def self.nest_in_modules: (Array[String] segments, Array[String] body_lines) -> Array[String]
+  def self.input_method_lines: (Symbol name, Hash[Symbol, untyped] options) -> Array[String]
+  def self.render_type: (Symbol name, Hash[Symbol, untyped] options) -> String
+  def self.render_single_type: (Symbol name, untyped type) -> String
+end

data/lib/assistant/rbs_generator/writer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Assistant::RbsGenerator
+  # File-writing layer with marker-aware idempotency.
+  class Writer
+    def initialize(output_dir:, quiet: false, stdout: $stdout, stderr: $stderr)
+      @output_dir = output_dir
+      @quiet = quiet
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # Returns one of :written, :unchanged, :skipped.
+    def write(service_class, contents)
+      target = path_for(service_class)
+      return skip!(target) if exists_without_marker?(target)
+      return unchanged!(target) if File.exist?(target) && File.read(target) == contents
+
+      FileUtils.mkdir_p(File.dirname(target))
+      File.write(target, contents)
+      announce("[written]   #{target}")
+      :written
+    end
+
+    private
+
+    attr_reader :output_dir, :quiet, :stdout, :stderr
+
+    def exists_without_marker?(target)
+      File.exist?(target) && !generated_file?(target)
+    end
+
+    def skip!(target)
+      stderr.puts "[skipped]   #{target} (no generator marker; will not overwrite)"
+      :skipped
+    end
+
+    def unchanged!(target)
+      announce("[unchanged] #{target}")
+      :unchanged
+    end
+
+    def path_for(service_class)
+      name = service_class.name or raise "anonymous Service class #{service_class.inspect}"
+      relative = name.split('::').map { |seg| underscore(seg) }.join('/')
+      File.join(output_dir, "#{relative}.rbs")
+    end
+
+    # ASCII-only underscoring -- the gem ships no runtime deps, so this
+    # mirrors the common ActiveSupport rule without pulling it in.
+    def underscore(camel)
+      camel.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+
+    def generated_file?(path)
+      File.foreach(path).first&.chomp == Assistant::RbsGenerator::MARKER
+    end
+
+    def announce(message)
+      stdout.puts(message) unless quiet
+    end
+  end
+end

data/lib/assistant/rbs_generator/writer.rbs

@@ -0,0 +1,24 @@
+class Assistant::RbsGenerator::Writer
+  @output_dir: String
+  @quiet: bool
+  @stdout: IO
+  @stderr: IO
+
+  def initialize: (output_dir: String, ?quiet: bool, ?stdout: IO, ?stderr: IO) -> void
+  def write: (singleton(Assistant::Service) service_class, String contents) -> Symbol
+
+  private
+
+  attr_reader output_dir: String
+  attr_reader quiet: bool
+  attr_reader stdout: IO
+  attr_reader stderr: IO
+
+  def path_for: (singleton(Assistant::Service) service_class) -> String
+  def exists_without_marker?: (String target) -> bool
+  def skip!: (String target) -> Symbol
+  def unchanged!: (String target) -> Symbol
+  def underscore: (String camel) -> String
+  def generated_file?: (String path) -> bool
+  def announce: (String message) -> void
+end

data/lib/assistant/rbs_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Per-class RBS generator for `Assistant::Service` subclasses. The
+# generic RBS shipped in `lib/assistant/service.rbs` cannot describe the
+# per-input getter / predicate methods produced by the
+# `Assistant::InputBuilder` DSL because their names and return types are
+# only known at class-definition time. Users with Steep run this
+# generator over their service files to obtain accurate signatures for
+# their own subclasses.
+#
+# The generator is intentionally **not** loaded by `require 'assistant'`
+# -- it is a developer-time tool. The shipped `exe/assistant-rbs`
+# binary requires it explicitly.
+#
+# Marked Experimental in `docs/v1/01-api-surface.md` so the output
+# format may evolve within 1.x.
+#
+# See `docs/v1/02-features.md` (M11) for the contract.
+module Assistant::RbsGenerator
+  # Header marker written as the first line of every generated `.rbs`
+  # file. {Writer} refuses to overwrite a file whose first line is
+  # not this exact string, so hand-edited signatures are preserved.
+  # @return [String]
+  MARKER = '# Generated by assistant-rbs; do not edit.'
+
+  # Default value for the `--output DIR` option of `exe/assistant-rbs`.
+  # @return [String]
+  DEFAULT_OUTPUT_DIR = 'sig'
+
+  # Default value for the positional `PATH` arguments of
+  # `exe/assistant-rbs` when none are supplied.
+  # @return [Array<String>]
+  DEFAULT_INPUT_PATHS = ['lib'].freeze
+end
+
+require 'assistant/rbs_generator/cli'
+require 'assistant/rbs_generator/renderer'
+require 'assistant/rbs_generator/writer'

data/lib/assistant/rbs_generator.rbs

@@ -0,0 +1,5 @@
+module Assistant::RbsGenerator
+  MARKER: String
+  DEFAULT_OUTPUT_DIR: String
+  DEFAULT_INPUT_PATHS: Array[String]
+end

data/lib/assistant/refinements/string_blankness.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
-module Assistant
-  module Refinements
-    # Refines String with `#whitespace?`, true when a string is empty or
-    # contains only whitespace characters. Used by `InputBuilder` validators
-    # to treat whitespace-only strings as missing input without depending on
-    # ActiveSupport's `String#blank?`.
-    module StringBlankness
-      refine String do
-        # True when the string is empty or contains only whitespace.
-        def whitespace?
-          strip.empty?
-        end
-      end
+# Refines String with `#whitespace?`, true when a string is empty or
+# contains only whitespace characters. Used by `InputBuilder` validators
+# to treat whitespace-only strings as missing input without depending on
+# ActiveSupport's `String#blank?`.
+module Assistant::Refinements::StringBlankness
+  refine String do
+    # True when the string is empty or contains only whitespace.
+    def whitespace?
+      strip.empty?
     end
   end
 end

data/lib/assistant/refinements/string_blankness.rbs

@@ -0,0 +1,6 @@
+# Type signatures for `lib/assistant/refinements/string_blankness.rb`.
+# RBS cannot fully model refinements; the bundled refinement module is
+# declared as an empty module so downstream signatures can name it.
+
+module Assistant::Refinements::StringBlankness
+end