openapi-sourcetools 0.7.1 → 0.8.1

data/lib/openapi/sourcetools/gen.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+require_relative 'helper'
+require_relative 'docs'
+require_relative 'output'
+require_relative 'config'
+require 'deep_merge'
+require 'singleton'
+
+# The generation module that contains things visible to tasks.
+class Gen
+  include Singleton
+
+  @docsrc = []
+  def self.add_doc(symbol, docstr)
+    @docsrc.push("- #{symbol} : #{docstr}")
+  end
+  private_class_method :add_doc
+
+  def self.attrib_reader(symbol, docstr, initial_value = nil)
+    add_doc(symbol, docstr)
+    attr_reader(symbol)
+    instance_eval("def #{symbol}; Gen.instance.#{symbol}; end")
+    Gen.instance.instance_variable_set("@#{symbol}", initial_value) unless initial_value.nil?
+  end
+  private_class_method :attrib_reader
+
+  def self.attrib_accessor(symbol, docstr, initial_value = nil)
+    add_doc(symbol, docstr)
+    attr_accessor(symbol)
+    instance_eval("def #{symbol}; Gen.instance.#{symbol}; end")
+    instance_eval("def #{symbol}=(v); Gen.instance.#{symbol} = v; end")
+    Gen.instance.instance_variable_set("@#{symbol}", initial_value) unless initial_value.nil?
+  end
+  private_class_method :attrib_accessor
+
+  attrib_reader :doc, 'OpenAPI document.'
+  attrib_reader :outdir, 'Output directory name.'
+  attrib_reader :d, 'Other documents object.', OpenAPISourceTools::Docs.new
+  attrib_reader :wd, 'Original working directory', Dir.pwd
+  attrib_reader :configuration, 'Generator internal configuration'
+  attrib_accessor :config, 'Configuration file name for next gem or Ruby file.'
+  attrib_accessor :separator, 'Key separator in config file names.'
+  attrib_accessor :in_name, 'OpenAPI document name, nil if stdin.'
+  attrib_accessor :in_basename, 'OpenAPI document basename, nil if stdin.'
+  attrib_reader :g, 'Hash for storing values visible to all tasks.', {}
+  attrib_accessor :x, 'Hash for storing values visible to tasks from processor.', {}
+  attrib_accessor :h, 'Instance of class with helper methods.'
+  attrib_accessor :tasks, 'Tasks array.', []
+  attrib_accessor :t, 'Current task instance.'
+  attrib_accessor :task_index, 'Current task index.'
+  attrib_accessor :loaders, 'Array of processor loader methods.', []
+  attrib_accessor :output, 'Output-formatting helper.', OpenAPISourceTools::Output.new
+
+  def self.load_config(name_prefix, extensions = [ '.*' ])
+    cfg = {}
+    cfgs = OpenAPISourceTools::ConfigLoader.find_files(name_prefix:, extensions:)
+    cfgs = OpenAPISourceTools::ConfigLoader.read_contents(cfgs)
+    cfgs.each { |c| cfg.deep_merge!(c) }
+    cfg
+  end
+
+  def setup(document_content, input_name, output_directory, config_prefix)
+    @doc = document_content
+    @outdir = output_directory
+    unless input_name.nil?
+      @in_name = File.basename(input_name)
+      @in_basename = File.basename(input_name, '.*')
+    end
+    @configuration = Gen.load_config(config_prefix)
+    add_task(task: OpenAPISourceTools::HelperTask.new)
+  end
+
+  def self.setup(document_content, input_name, output_directory, config_prefix)
+    Gen.instance.setup(document_content, input_name, output_directory, config_prefix)
+  end
+
+  def add_task(task:, name: nil, executable: false, x: nil)
+    @tasks.push(task)
+    # Since this method allows the user to pass their own task type instance,
+    # assign optional values with defaults only when clearly given.
+    @tasks.last.name = name unless name.nil?
+    @tasks.last.executable = executable unless executable == false
+    @tasks.last.x = x unless x.nil?
+  end
+
+  def self.add_task(task:, name: nil, executable: false, x: nil)
+    Gen.instance.add_task(task:, name:, executable:, x:)
+  end
+
+  def add_write_content(name:, content:, executable: false)
+    add_task(task: OpenAPISourceTools::WriteTask.new(name, content, executable))
+  end
+
+  def self.add_write_content(name:, content:, executable: false)
+    Gen.instance.add_write_content(name:, content:, executable:)
+  end
+
+  def add(source:, template: nil, template_name: nil, name: nil, executable: false, x: nil)
+    add_task(task: OpenAPISourceTools::Task.new(source, template, template_name),
+      name:, executable:, x:)
+  end
+
+  def self.add(source:, template: nil, template_name: nil, name: nil, executable: false, x: nil)
+    Gen.instance.add(source:, template:, template_name:, name:, executable:, x:)
+  end
+
+  def self.document
+    @docsrc.join("\n") + %(
+- add_task(task:, name: nil, executable: false, x: nil) : Adds task object.
+- add_write_content(name:, content:, executable: false) : Add file write task.
+- add(source:, template: nil, template_name: nil, name: nil,
+    executable: false, x: nil) :
+  Adds template task with source as object to process.
+)
+  end
+end

data/lib/openapi/sourcetools/generate.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require_relative 'loaders'
+require_relative 'gen'
+
+
+module OpenAPISourceTools
+  def self.executable_bits_on(mode)
+    mode = mode.to_s(8).chars
+    mode.size.times do |k|
+      m = mode[k].to_i(8)
+      # Applies to Unix-likes. Other system, check and handle.
+      m += 1 unless 3 < mode.size - k || m.zero? || m.odd?
+      mode[k] = m
+    end
+    m = 0
+    mode.each do |v|
+      m = 8 * m + v
+    end
+    m
+  end
+
+  # Runs all tasks that generate the results.
+  # Used internally by openapi-generate.
+  class Generator
+    def initialize(document_content, input_name, output_directory, config_prefix)
+      Gen.setup(document_content, input_name, output_directory, config_prefix)
+      Gen.loaders = Loaders.loaders
+    end
+
+    def context_binding
+      binding
+    end
+
+    def load(generator_names)
+      generator_names.each do |name|
+        idx = Gen.loaders.index { |loader| loader.call(name) }
+        return Common.aargh("No loader could handle #{name}", 2) if idx.nil?
+      end
+      0
+    rescue StandardError => e
+      Common.aargh(e.to_s, 2)
+    end
+
+    def generate(t)
+      t.generate(context_binding)
+    rescue Exception => e
+      Common.aargh(e.to_s, 4)
+    end
+
+    def output_name(t, index)
+      name = t.output_name
+      name = "#{index}.txt" if name.nil?
+      File.join(Gen.outdir, name)
+    end
+
+    def save(name, contents, executable)
+      d = File.dirname(name)
+      FileUtils.mkdir_p(d) unless File.directory?(d)
+      f = File.new(name, File::WRONLY | File::CREAT | File::TRUNC)
+      s = executable ? f.stat : nil
+      f.write(contents)
+      f.close
+      return unless executable
+      mode = OpenAPISourceTools.executable_bits_on(s.mode)
+      File.chmod(mode, name) unless mode == s.mode
+    end
+
+    def run
+      # This allows tasks to be added while processing.
+      # Not intended to be done but might prove handy.
+      # Also exposes current task index in case new task is added in the middle.
+      Gen.task_index = 0
+      while Gen.task_index < Gen.tasks.size
+        Gen.t = Gen.tasks[Gen.task_index]
+        out = generate(Gen.t)
+        Gen.task_index += 1
+        return out if out.is_a?(Integer)
+        next if Gen.t.discard || out.empty?
+        name = output_name(Gen.t, Gen.task_index - 1)
+        begin
+          save(name, out, Gen.t.executable)
+        rescue StandardError => e
+          return Common.aargh("Error writing output file: #{name}\n#{e}", 3)
+        end
+      end
+      0
+    end
+  end
+end

data/lib/openapi/sourcetools/helper.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+module OpenAPISourceTools
+  # Helper class supposed to contain helpful methods.
+  # Exposed as Gen.h if HelperTask has been run. It is automatically
+  # added as the first task but later tasks can remove it.
+  class Helper
+    attr_reader :doc, :parents
+    attr_accessor :parent_parameters
+
+    # Stores the nearest Hash for each Hash.
+    def store_parents(obj, parent = nil)
+      if obj.is_a?(Hash)
+        @parents[obj] = parent
+        obj.each_value do |v|
+          store_parents(v, obj)
+        end
+      elsif obj.is_a?(Array)
+        obj.each do |v|
+          store_parents(v, parent)
+        end
+      end
+    end
+
+    def initialize(doc)
+      @doc = doc
+      @parents = {}.compare_by_identity
+      store_parents(@doc)
+    end
+
+    def parent(object)
+      @parents[object]
+    end
+
+    COMPONENTS = '#/components/'
+
+    def category_and_name(ref_or_obj)
+      ref = ref_or_obj.is_a?(Hash) ? ref_or_obj['$ref'] : ref_or_obj
+      return nil unless ref.is_a?(String)
+      return nil unless ref.start_with?(Helper::COMPONENTS)
+      idx = ref.index('/', Helper::COMPONENTS.size)
+      return nil if idx.nil?
+      category = ref[Helper::COMPONENTS.size...idx]
+      [ category, ref[(idx + 1)...ref.size] ]
+    end
+
+    def dereference(ref_or_obj)
+      cn = category_and_name(ref_or_obj)
+      return nil if cn.nil?
+      cs = @doc.dig('components', cn.first) || {}
+      cs[cn.last]
+    end
+
+    def basename(ref_or_obj)
+      cn = category_and_name(ref_or_obj)
+      return nil if cn.nil?
+      cn.last
+    end
+
+    def parameters(operation_object, empty_unless_local = false)
+      return [] if empty_unless_local && !operation_object.key?('parameters')
+      cps = @doc.dig('components', 'parameters') || {}
+      uniqs = {}
+      path_item_object = parent(operation_object)
+      [path_item_object, operation_object].each do |p|
+        p.fetch('parameters', []).each do |param|
+          r = basename(param)
+          r = cps[r] if r.is_a?(String)
+          uniqs["#{r['name']}:#{r['in']}"] = param
+        end
+      end
+      uniqs.keys.sort!.map { |k| uniqs[k] }
+    end
+  end
+
+  # Task class to add an Helper instance to Gen.h, for convenience.
+  class HelperTask
+    include OpenAPISourceTools::TaskInterface
+
+    def generate(_context_binding)
+      Gen.h = Helper.new(Gen.doc) if Gen.h.nil?
+    end
+
+    def discard
+      true
+    end
+  end
+end

data/lib/openapi/sourcetools/loaders.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+require_relative 'gen'
+
+
+# Original loader functions. These are accessible via Gen.loaders. New loaders
+# should be added there.
+module OpenAPISourceTools
+  # Loaders used to load gems and files and set config etc.
+  # Exposed as Gen.loaders if you need to modify the array.
+  module Loaders
+    # Prefix etc. and loader pairs for all loaders.
+
+    REQ_PREFIX = 'req:'
+
+    def self.req_loader(name)
+      return false unless name.downcase.start_with?(REQ_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = name.slice(REQ_PREFIX.size...name.size)
+        require(base)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      true
+    end
+
+    EVAL_PREFIX = 'eval:'
+
+    def self.eval_loader(name)
+      return false unless name.downcase.start_with?(EVAL_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        code = name.slice(EVAL_PREFIX.size...name.size)
+        eval(code)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      true
+    end
+
+    RUBY_EXT = '.rb'
+
+    def self.ruby_loader(name)
+      return false unless name.downcase.end_with?(RUBY_EXT)
+      origwd = Dir.pwd
+      d = File.dirname(name)
+      Dir.chdir(d) unless d == '.'
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = File.basename(name)
+        Gen.config = base[0..-4] if Gen.config.nil?
+        load(File.join(Dir.pwd, base))
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to load #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      Dir.chdir(origwd) unless d == '.'
+      true
+    end
+
+    YAML_PREFIX = 'yaml:'
+    YAML_EXTS = [ '.yaml', '.yml' ].freeze
+
+    def self.yaml_loader(name)
+      d = name.downcase
+      if d.start_with?(YAML_PREFIX)
+        name = name.slice(YAML_PREFIX.size...name.size)
+      elsif (YAML_EXTS.index { |s| d.end_with?(s) }).nil?
+        return false
+      end
+      n, _sep, f = name.partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = YAML.safe_load_file(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read as YAML: #{f}\n#{e}"
+    end
+
+    BIN_PREFIX = 'bin:'
+
+    def self.bin_loader(name)
+      return false unless name.downcase.start_with?(BIN_PREFIX)
+      n, _sep, f = name.slice(BIN_PREFIX.size...name.size).partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = File.binread(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read #{f}\n#{e}"
+    end
+
+    CONFIG_PREFIX = 'config:'
+
+    def self.config_loader(name)
+      return false unless name.downcase.start_with?(CONFIG_PREFIX)
+      raise StandardError, "Config name remains: #{Gen.config}" unless Gen.config.nil?
+      n = name.slice(CONFIG_PREFIX.size...name.size)
+      raise StandardError, 'No name given.' if n.empty?
+      # Interpretation left completely to config loading.
+      Gen.config = n
+      true
+    end
+
+    SEPARATOR_PREFIX = 'separator:'
+
+    def self.separator_loader(name)
+      return false unless name.downcase.start_with?(SEPARATOR_PREFIX)
+      n = name.slice(SEPARATOR_PREFIX.size...name.size)
+      n = nil if n.empty?
+      Gen.separator = n
+      true
+    end
+
+    def self.loaders
+      [
+        method(:req_loader),
+        method(:eval_loader),
+        method(:ruby_loader),
+        method(:yaml_loader),
+        method(:bin_loader),
+        method(:config_loader),
+        method(:separator_loader)
+      ]
+    end
+
+    def self.document
+      <<EOB
+- #{Loaders::REQ_PREFIX}req_name : requires the gem.
+- #{Loaders::EVAL_PREFIX}code : runs code to add gem tasks again.
+- ruby_file#{Loaders::RUBY_EXT} : changes to Ruby file directory and requires the file.
+- #{Loaders::YAML_PREFIX}name:filename : Loads YAML file into Gen.d.name.
+- name:filename.{#{(Loaders::YAML_EXTS.map { |s| s[1...s.size] }).join('|')}} : Loads YAML file into Gen.d.name.
+- #{Loaders::BIN_PREFIX}name:filename : Loads binary file into Gen.d.name.
+- #{Loaders::CONFIG_PREFIX}name : Sets Gen.config for next gem/Ruby file configuration loading.
+- #{Loaders::SEPARATOR_PREFIX}string : Sets Gen.separator to string.
+EOB
+    end
+  end
+end

data/lib/openapi/sourcetools/output.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+
+module OpenAPISourceTools
+  # Output configuration settings for easy storage.
+  # You can have it in configuration and pass hash to initialize.
+  class OutputConfiguration
+    attr_reader :indent_character, :indent_step
+    attr_reader :tab, :tab_replaces_count
+
+    def initialize(cfg = {})
+      @indent_character = cfg['indent_character'] || ' '
+      @indent_step = cfg['indent_step'] || 4
+      @tab = cfg['tab'] || "\t"
+      @tab_replaces_count = cfg['tab_replaces_count'] || 0
+    end
+  end
+
+  # Output indentation helper class.
+  # Exposed as Gen.output for use from templates.
+  class Output
+    attr_reader :config
+    attr_accessor :last_indent
+
+    def initialize(cfg = OutputConfiguration.new)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    def config=(cfg)
+      cfg = OutputConfiguration.new(cfg) if cfg.is_a?(Hash)
+      raise ArgumentError, "Expected OutputConfiguration or Hash, got #{cfg.class}" unless cfg.is_a?(OutputConfiguration)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    # Takes an array of code blocks/lines or integers/booleans and produces
+    # indented output using the separator character.
+    # Set class attributes to obtain desired outcome.
+    def join(blocks, separator = "\n")
+      indented = []
+      blocks.flatten!
+      indent = 0
+      blocks.each do |block|
+        if block.nil?
+          indent = 0
+        elsif block.is_a?(Integer)
+          indent += block
+        elsif block.is_a?(TrueClass)
+          indent += @config.indent_step
+        elsif block.is_a?(FalseClass)
+          indent -= @config.indent_step
+        else
+          block = block.to_s unless block.is_a?(String)
+          if block.empty?
+            indented.push('')
+            next
+          end
+          if indent.zero?
+            indented.push(block)
+            next
+          end
+          if @config.tab_replaces_count.positive?
+            tabs = @config.tab * (indent / @config.tab_replaces_count)
+            chars = @config.indent_character * (indent % @config.tab_replaces_count)
+          else
+            tabs = ''
+            chars = @config.indent_character * indent
+          end
+          lines = block.lines(chomp: true)
+          lines.each do |line|
+            indented.push("#{tabs}#{chars}#{line}")
+          end
+        end
+      end
+      @last_indent = indent
+      indented.join(separator)
+    end
+  end
+end

data/lib/openapi/sourcetools/task.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require 'erb'
+
+
+module OpenAPISourceTools
+
+  # Required interface for tasks, with default implementation for some methods.
+  module TaskInterface
+    def generate(context_binding)
+      raise NotImplementedError
+    end
+
+    def output_name
+      raise NotImplementedError
+    end
+
+    def discard
+      false
+    end
+
+    def executable
+      false
+    end
+
+    def system
+      false
+    end
+  end
+
+  # Loads template or takes it as argument. Renders template using ERB.
+  class Task
+    include TaskInterface
+
+    attr_reader :src, :template, :template_name
+    attr_accessor :name, :executable, :discard, :x
+
+    def initialize(src, template, template_name)
+      @src = src
+      @template = template
+      @template_name = template_name
+      if @template.nil?
+        raise ArgumentError, 'template_name or template must be given' if @template_name.nil?
+        begin
+          @template = File.read(@template_name)
+        rescue Errno::ENOENT
+          raise StandardError, "Could not load #{@template_name}"
+        rescue StandardError => e
+          raise StandardError, "#{e}\nFailed to read #{@template_name}"
+        end
+      end
+      @name = nil
+      @executable = false
+      @discard = false
+      @x = nil
+    end
+
+    # If this is overridden to perform some processing but not to produce output,
+    # set @discard = true and return value will be ignored. No other methods are
+    # called in that case.
+    def internal_generate(context_binding)
+      ERB.new(@template).result(context_binding)
+    end
+
+    # You can override this instead of internal_generate if you do not need the
+    # exception handling.
+    def generate(context_binding)
+      n = @template_name.nil? ? '' : "#{@template_name} "
+      internal_generate(context_binding)
+    rescue SyntaxError => e
+      OpenAPISourceTools::Common.aargh("Template #{n}syntax error: #{e.full_message}", 5)
+    rescue Exception => e # Some unexpected error.
+      OpenAPISourceTools::Common.aargh("Template #{n}error: #{e.full_message}", 6)
+    end
+
+    # This is only called when generate produced output that is not discarded.
+    def output_name
+      return @name unless @name.nil?
+      # Using template name may show where name assignment is missing.
+      # Name assignment may also be missing in the task creation stage.
+      return File.basename(@template_name) unless @template_name.nil?
+      nil
+    end
+  end
+
+  # A task that provides contents to be written to a named file.
+  # Optionaly the file may be made executable.
+  class WriteTask
+    include TaskInterface
+
+    attr_reader :name, :contents, :executable
+
+    def initialize(name, contents, executable = false)
+      raise ArgumentError, 'name and contents must be given' if name.nil? || contents.nil?
+      @name = name
+      @contents = contents
+      @executable = executable
+    end
+
+    def generate(_context_binding)
+      @contents
+    end
+
+    def output_name
+      @name
+    end
+  end
+
+  # Sets Gen.x to empty hash. Inserted after gem tasks.
+  class RestoreProcessorStorage
+    include TaskInterface
+
+    attr_accessor :x # Allows setting the current value when setup code finishes.
+
+    # Sets initial default value.
+    def initialize(x = {})
+      @x = x
+      Gen.x = @x
+    end
+
+    def generate(_context_binding)
+      Gen.x = @x # Restore whatever was current when setup code finished.
+    end
+
+    def discard
+      true
+    end
+
+    def system
+      true
+    end
+  end
+end

data/lib/openapi/sourcetools/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Copyright © 2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+module OpenAPISourceTools
+  NAME = 'openapi-sourcetools'
+  VERSION = '0.8.1'
+
+  def self.info(separator = ': ')
+    "#{NAME}#{separator}#{VERSION}"
+  end
+end