openapi-sourcetools 0.4.3 → 0.6.0

data/lib/apiobjects.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'set'
+
+def same(a, b, ignored_keys = Set.new(%w[summary description]))
+  return a == b unless a.is_a?(Hash) && b.is_a?(Hash)
+  keys = Set.new(a.keys + b.keys) - ignored_keys
+  keys.to_a.each do |k|
+    return false unless a.key?(k) && b.key?(k)
+    return false unless same(a[k], b[k], ignored_keys)
+  end
+  true
+end
+
+def ref_string(name, schema_path)
+  "#{schema_path}/#{name}"
+end
+
+def reference(obj, schemas, schema_path, ignored_keys = Set.new(%w[summary description]), prefix = 'Schema')
+  # Check if identical schema has been added and if so, return the $ref string.
+  schemas.keys.sort.each do |k|
+    return ref_string(k, schema_path) if same(obj, schemas[k], ignored_keys)
+  end
+  # One of the numbers will not match existing keys. More number than keys.
+  (schemas.size + 1).times do |n|
+    # 'x' is to simplify find and replace (Schema1x vs Schema1 and Schema10)
+    k = "#{prefix}#{n}x"
+    next if schemas.key?(k)
+    schemas[k] = obj.merge
+    return ref_string(k, schema_path)
+  end
+end
+
+class Components
+  attr_reader :path, :prefix
+  attr_accessor :items, :ignored_keys
+
+  def initialize(path, prefix, ignored_keys = %w[summary description examples example])
+    @items = {}
+    path = "#/#{path.join('/')}/" if path.is_a?(Array)
+    path = "#{path}/" unless path.end_with?('/')
+    @path = path
+    @prefix = prefix
+    @ignored_keys = Set.new(ignored_keys)
+  end
+
+  def add_options(opts)
+    opts.on('--use FIELD', 'Use FIELD in comparisons.') do |f|
+      @ignored_keys.delete(f)
+    end
+    opts.on('--ignore FIELD', 'Ignore FIELD in comparisons.') do |f|
+      @ignored_keys.add(f)
+    end
+  end
+
+  def help
+    %(All fields are used in object equality comparisons except:\n#{@ignored_keys.to_a.sort!.join("\n")})
+  end
+
+  def ref_string(name)
+    "#{@path}#{name}"
+  end
+
+  def reference(obj)
+    # Check if identical schema has been added. If so, return the $ref string.
+    @items.each do |k, v|
+      return ref_string(k) if same(obj, v, @ignored_keys)
+    end
+    # One of the numbers will not match existing keys. More number than keys.
+    (@items.size + 1).times do |n|
+      # 'x' is to simplify find and replace (Schema1x vs Schema1 and Schema10)
+      cand = "#{@prefix}#{n}x"
+      next if @items.key?(cand)
+      @items[cand] = obj.merge
+      return ref_string(cand)
+    end
+  end
+end
+
+
+class PathOperation
+  attr_accessor :path, :operation, :info, :parameters
+  attr_accessor :servers, :security, :tags
+  attr_accessor :summary, :description
+end
+
+# One could have a convenience
+# method that determines how many bytes the value needs, and if it needs to be
+# signed.
+
+# When creating types for schemas or otherwise, the type name can be added
+# into the item and that way be used as an indicator that the type has been
+# declared or needs a declaration.
+
+def make_path_operations(apidoc)
+  # Check openapi
+  # Store info as is for reference
+  # Store servers as is for default value for PathOperation
+  # Process components. Lazy manner, only when referenced.
+  # Store security as is for default value for PathOperation.
+  # Store tags as mapping from name to object for use with PathOperation.
+  # Process paths:
+  # Store parameters as is for default value for PathOperation.
+  # All other fields, check if it looks like OperationObject and create a
+  # PathOperation using it. For others, store as is for default value.
+
+end
+
+
+class ServerPath
+  include Comparable
+
+  attr_accessor :parts
+
+  def initialize(parts)
+    @parts = parts
+  end
+
+  def <=>(other) # Variables are after fixed strings.
+    pp = other.is_a?(Array) ? other : p.parts
+    parts.each_index do |k|
+      return 1 if pp.size <= k # Longer comes after shorter.
+      pk = parts[k]
+      ppk = pp[k]
+      if pk.is_a? String
+        if ppk.is_a? String
+          c = pk <=> ppk
+        else
+          return -1
+        end
+      else
+        if ppk.is_a? String
+          return 1
+        else
+          c = pk.fetch('var', '') <=> ppk.fetch('var', '')
+        end
+      end
+      return c unless c.zero?
+    end
+    (parts.size < pp.size) ? -1 : 0
+  end
+
+  def compare(p, range = nil) # Not fit for sorting. Variable equals anything.
+    pp = p.is_a?(Array) ? p : p.parts
+    if range.nil?
+      range = 0...parts.size
+    elsif range.is_a? Number
+      range = range...(range + 1)
+    end
+    range.each do |k|
+      return 1 if pp.size <= k # Longer comes after shorter.
+      ppk = pp[k]
+      next unless ppk.is_a? String
+      pk = parts[k]
+      next unless pk.is_a? String
+      c = pk <=> ppk
+      return c unless c.zero?
+    end
+    (parts.size < pp.size) ? -1 : 0
+  end
+end
+
+# Adds all refs found in the array to refs with given required state.
+def gather_array_refs(refs, items, required)
+  items.each do |s|
+    r = s['$ref']
+    next if r.nil?
+    refs[r] = required || refs.fetch(r, false)
+  end
+end
+
+# For any key '$ref' adds to refs whether referred type is required.
+# Requires that there are no in-lined schemas, openapi-addschemas has been run.
+def gather_refs(refs, schema)
+  # This implies types mixed together according to examples. Needs mixed type.
+  # AND. Also, mixing may fail. Adds a new schema, do here.
+  items = schema['allOf']
+  return gather_array_refs(refs, items, true) unless items.nil?
+  # As long as one schema is fulfilled, it is ok. OR, first that fits.
+  items = schema['anyOf'] if items.nil?
+  # oneOf implies selection between different types. No multiple matches. XOR.
+  # Needs to ensure that later types do not match.
+  # Should check if there is enough difference to ensure single match.
+  # Use separate program run after addschemas to create allOf mixed schema
+  # and verify the others can be dealt with.
+  items = schema['oneOf'] if items.nil?
+  return gather_array_refs(refs, items, false) unless items.nil?
+  # Defaults below handle it if "type" is not "object".
+  reqs = schema.fetch('required', [])
+  schema.fetch('properties', {}).each do |name, spec|
+    r = spec['$ref']
+    next if r.nil?
+    refs[r] = reqs.include?(name) || refs.fetch(r, false)
+  end
+end
+
+class SchemaInfo
+  attr_accessor :ref, :schema, :direct_refs, :name, :post_refs
+
+  def initialize(ref, name, schema)
+    @ref = ref
+    @name = name
+    @schema = schema
+    @direct_refs = {}
+    gather_refs(@direct_refs, schema)
+  end
+
+  def set_post_refs(seen)
+    @post_refs = Set.new(@direct_refs.keys) - seen
+  end
+
+  def to_s
+    v = @direct_refs.keys.sort.map { |k| "#{k}:#{@direct_refs[k] ? 'req' : 'opt'}" }
+    "#{@ref}: #{v.join(' ')}"
+  end
+end
+
+def var_or_method_value(x, name)
+  if name.start_with?('@')
+    n = name
+  else
+    n = "@#{name}"
+  end
+  return x.instance_variable_get(n) if x.instance_variable_defined?(n)
+  return x.public_send(name) if x.respond_to?(name)
+  raise ArgumentError, "#{name} is not #{x.class} instance variable nor public method"
+end
+
+class SchemaOrderer
+  attr_accessor :schemas, :order, :orderer
+
+  def initialize(path, schema_specs)
+    @schemas = {}
+    schema_specs.each do |name, schema|
+      r = "#{path}#{name}"
+      @schemas[r] = SchemaInfo.new(r, name, schema)
+    end
+  end
+
+  def sort!(orderer = 'required_first')
+    case orderer
+    when 'required_first' then @order = required_first
+    when '<=>' then @order = @schemas.values.sort { |a, b| a <=> b }
+    else
+      @order = @schemas.values.sort do |a, b|
+        va = var_or_method_value(a, orderer)
+        vb = var_or_method_value(b, orderer)
+        va <=> vb
+      end
+    end
+    @orderer = orderer
+    seen = Set.new
+    @order.each do |si|
+      si.set_post_refs(seen)
+      seen.add(si.ref)
+    end
+    @order
+  end
+
+  def required_first
+    chosen = []
+    until chosen.size == @schemas.size
+      used = Set.new(chosen.map { |si| si.ref })
+      avail = @schemas.values.select { |si| !used.member?(si.ref) }
+      best = nil
+      avail.each do |si|
+        prereq = chosen.count { |x| x.direct_refs.fetch(si.ref, false) }
+        fulfilled = chosen.count { |x| si.direct_refs.fetch(x.ref, false) }
+        postreq = si.direct_refs.size - (prereq + fulfilled)
+        better = false
+        if best.nil?
+          better = true
+        else
+          # Minimize preceding types requiring this.
+          if prereq < best.first
+            better = true
+          elsif prereq == best.first
+            # Minimize remaining unfulfilled requires.
+            if postreq < best[1]
+              better = true
+            elsif postreq == best[1]
+              # Check mutual direct requirements.
+              best_req_si = best.last.direct_refs.fetch(si.ref, false)
+              si_req_best = si.direct_refs.fetch(best.last.ref, false)
+              if best_req_si
+                better = true unless si_req_best
+              end
+              # Order by name if no other difference.
+              better = si.ref < best.last.ref unless better
+            end
+          end
+        end
+        best = [ prereq, postreq, si ] if better
+      end
+      chosen.push(best.last)
+    end
+    chosen
+  end
+end
+
+class HeaderOrderer
+end
+
+class ResponseOrderer
+end
+
+class PathOrderer
+end
+
+class Tasker
+  attr_reader :doc
+  def initialize(doc)
+    @doc = doc
+  end
+end
+
+class SchemaTasker < Tasker
+# initialize with doc
+# Orderer set somehow.
+# Method ot create one task per schema.
+# Method to create one task for all schemas.
+end
+
+class HeaderTasker < Tasker
+# initialize with doc
+# Orderer set somehow.
+# Method ot create one task per schema.
+# Method to create one task for all schemas.
+end
+
+
+

data/lib/common.rb

@@ -1,25 +1,33 @@
 # frozen_string_literal: true
 
-def aargh(message, exit_code = nil)
+# Copyright © 2021-2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require 'pathname'
+
+
+def aargh(message, return_value = nil)
+  message = message.map(&:to_s).join("\n") if message.is_a? Array
   $stderr.puts message
-  exit exit_code unless exit_code.nil?
+  return_value
 end
 
-def env(var, value = nil)
-  k = var.to_s.upcase
-  ENV[k] = { false => '0', true => '1' }.fetch(value, value) unless value.nil?
-  v = ENV.fetch(k, nil)
-  case v
-  when '0' then false
-  when '1' then true
-  else
-    v
+def bury(doc, path, value)
+  (path.size - 1).times do |k|
+    p = path[k]
+    doc[p] = {} unless doc.key?(p)
+    doc = doc[p]
   end
+  doc[path.last] = value
 end
 
-def default_env(var, value)
-  v = env(var)
-  env(var, value) if v.nil?
+module Out
+  attr_reader :count
+
+  def put(message)
+    aargh(message)
+    count += 1
+  end
 end
 
 def split_path(p, spec = false)
@@ -37,32 +45,50 @@ def split_path(p, spec = false)
   parts
 end
 
+def load_source(input)
+  YAML.safe_load(input.nil? ? $stdin : File.read(input))
+rescue Errno::ENOENT
+  aargh "Could not load #{input || 'stdin'}"
+rescue StandardError => e
+  aargh "#{e}\nFailed to read #{input || 'stdin'}"
+end
+
+def dump_result(output, doc, error_return)
+  if output.nil?
+    $stdout.puts doc
+  else
+    fp = Pathname.new output
+    fp.open('w') do |f|
+      f.puts doc
+    end
+  end
+  0
+rescue StandardError => e
+  aargh([ e, "Failed to write output: #{output || 'stdout'}" ], error_return)
+end
+
 ServerPath = Struct.new(:parts) do
-  def <=>(p) # Variables are after fixed strings.
-    pp = p.is_a?(Array) ? p : p.parts
+  # Variables are after fixed strings.
+  def <=>(other)
+    pp = other.is_a?(Array) ? other : other.parts
     parts.each_index do |k|
       return 1 if pp.size <= k # Longer comes after shorter.
       pk = parts[k]
       ppk = pp[k]
       if pk.is_a? String
-        if ppk.is_a? String
-          c = pk <=> ppk
-        else
-          return -1
-        end
+        return -1 unless ppk.is_a? String
+        c = pk <=> ppk
       else
-        if ppk.is_a? String
-          return 1
-        else
-          c = pk.fetch('var', '') <=> ppk.fetch('var', '')
-        end
+        return 1 if ppk.is_a? String
+        c = pk.fetch('var', '') <=> ppk.fetch('var', '')
       end
       return c unless c.zero?
     end
     (parts.size < pp.size) ? -1 : 0
   end
 
-  def compare(p, range = nil) # Not fit for sorting. Variable equals anything.
+  # Not fit for sorting. Variable equals anything.
+  def compare(p, range = nil)
     pp = p.is_a?(Array) ? p : p.parts
     if range.nil?
       range = 0...parts.size

data/lib/gen.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+require_relative 'helper'
+
+
+module Gen
+  def self.mod_attr_reader(symbol, docstr = nil)
+    attr_reader(symbol)
+    module_function(symbol)
+    return if docstr.nil?
+    @docsrc = [] unless Gen.instance_variable_defined?('@docsrc')
+    @docsrc.push("- #{symbol.to_s} : #{docstr}")
+  end
+
+  def self.mod_attr_accessor(symbol, docstr = nil)
+    attr_accessor(symbol)
+    module_function(symbol)
+    s = symbol.to_s
+    module_function((s + '=').to_sym)
+    return if docstr.nil?
+    @docsrc = [] unless Gen.instance_variable_defined?('@docsrc')
+    @docsrc.push("- #{s} : #{docstr}")
+  end
+
+  mod_attr_reader :doc, 'OpenAPI document.'
+  mod_attr_reader :outdir, 'Output directory name.'
+  mod_attr_accessor :in_name, 'OpenAPI document name, nil if stdin.'
+  mod_attr_accessor :in_basename, 'OpenAPI document basename, nil if stdin.'
+  mod_attr_accessor :tasks, 'Tasks array.'
+  mod_attr_accessor :g, 'Hash for storing values visible to all tasks.'
+  mod_attr_accessor :a, 'Intended for instance with defined attributes.'
+  mod_attr_accessor :h, 'Instance of class with helper methods.'
+  mod_attr_accessor :t, 'Current task instance.'
+  mod_attr_accessor :task_index, 'Current task index.'
+  mod_attr_accessor :loaders, 'Array of generator loader methods.'
+
+  def self.setup(document_content, input_name, output_directory)
+    @doc = document_content
+    @outdir = output_directory
+    if input_name.nil?
+      @in_name = nil
+      @in_basename = nil
+    else
+      @in_name = File.basename(input_name)
+      @in_basename = File.basename(input_name, '.*')
+    end
+    @tasks = []
+    @g = {}
+    @a = nil
+    @h = nil
+    @t = nil
+    @task_index = nil
+    @loaders = []
+    add_task(task: HelperTask.new)
+  end
+
+  def self.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_write_content(name:, content:, executable: false)
+    add_task(task: WriteTask.new(name, content, executable))
+  end
+
+  def self.add(source:, template: nil, template_name: nil, name: nil, executable: false, x: nil)
+    add_task(task: Task.new(source, template, template_name), name: name, executable: executable, x: 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/generate.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require_relative 'loaders'
+require_relative 'gen'
+
+def executable_bits_on(mode)
+  mode = mode.to_s(8).split('')
+  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 % 2 == 1
+    mode[k] = m
+  end
+  m = 0
+  mode.each do |v|
+    m = 8 * m + v
+  end
+  m
+end
+
+class Generator
+  def initialize(document_content, input_name, output_directory)
+    Gen.setup(document_content, input_name, output_directory)
+    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 aargh("No loader could handle #{name}", 2) if idx.nil?
+    end
+    0
+  rescue StandardError => e
+    aargh(e.to_s, 2)
+  end
+
+  def generate(t)
+    t.generate(context_binding)
+  rescue Exception => e
+    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)
+    f = File.new(name, File::WRONLY | File::CREAT | File::TRUNC)
+    s = executable ? f.stat : nil
+    f.write(contents)
+    f.close
+    return unless executable
+    mode = 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
+      next if Gen.t.discard # Check first to ignore result if no output.
+      return out if out.is_a?(Integer)
+      next if out.empty? # Allows no output but return value still checked.
+      name = output_name(Gen.t, Gen.task_index - 1)
+      begin
+        save(name, out, Gen.t.executable)
+      rescue StandardError => e
+        return aargh("Error writing output file: #{name}\n#{e}", 3)
+      end
+    end
+    0
+  end
+end