openapi-sourcetools 0.7.1 → 0.8.0

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.0'
+
+  def self.info(separator = ': ')
+    "#{NAME}#{separator}#{VERSION}"
+  end
+end

data/lib/openapi/sourcetools.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'sourcetools/task'
+require_relative 'sourcetools/config'
+require_relative 'sourcetools/version'
+# Other modules or classes are exposed via Gen attributes as class instances as needed.
+# Docs is only needed for run-time storage of whatever loaders can handle.
+# Loaders array is exposed and can be added to at run-time.
+# Helper instance is accessible via Gen.h.
+# Output is exposed via Gen.o and Gen.output. Note that if you assign to one,
+# the other will not change.
+# The rest are for internal implementation.

metadata

@@ -1,20 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-28 00:00:00.000000000 Z
-dependencies: []
-description: |2
+date: 2025-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: deep_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+description: |-
+  Tools for handling API specification in OpenAPI format.
+  Programs to replace of duplicate definitions with references. Other checks.
 
-  Tools for handling API specification in OpenAPI format. Replacement of
-  duplicate definitions with references. Other checks. Does not validate
-  the document against OpenAPI format specification.
+  Does not validate the document against OpenAPI format specification.
 email: ismokarkkainen@icloud.com
 executables:
 - openapi-addheaders
@@ -41,15 +61,19 @@ files:
 - bin/openapi-merge
 - bin/openapi-modifypaths
 - bin/openapi-processpaths
-- lib/apiobjects.rb
-- lib/common.rb
-- lib/docs.rb
-- lib/gen.rb
-- lib/generate.rb
-- lib/helper.rb
-- lib/loaders.rb
-- lib/output.rb
-- lib/task.rb
+- lib/openapi/sourcetools.rb
+- lib/openapi/sourcetools/apiobjects.rb
+- lib/openapi/sourcetools/common.rb
+- lib/openapi/sourcetools/config.rb
+- lib/openapi/sourcetools/docs.rb
+- lib/openapi/sourcetools/gen.rb
+- lib/openapi/sourcetools/generate.rb
+- lib/openapi/sourcetools/helper.rb
+- lib/openapi/sourcetools/loaders.rb
+- lib/openapi/sourcetools/output.rb
+- lib/openapi/sourcetools/securityschemes.rb
+- lib/openapi/sourcetools/task.rb
+- lib/openapi/sourcetools/version.rb
 homepage: https://xn--ismo-krkkinen-gfbd.fi/openapi-sourcetools/index.html
 licenses:
 - UPL-1.0
@@ -63,14 +87,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Tools for creating source code from API specification.

data/lib/apiobjects.rb

@@ -1,306 +0,0 @@
-# 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, :anchor2ref, :schema_names
-  attr_accessor :items, :ignored_keys
-
-  def initialize(path, prefix, ignored_keys = %w[summary description examples example $anchor])
-    path = "#/#{path.join('/')}/" if path.is_a?(Array)
-    path = "#{path}/" unless path.end_with?('/')
-    @path = path
-    @prefix = prefix
-    @anchor2ref = {}
-    @schema_names = Set.new
-    @items = {}
-    @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 add_schema_name(name)
-    @schema_names.add(name)
-  end
-
-  def ref_string(name)
-    return nil if name.nil?
-    "#{@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
-      @schema_names.add(cand)
-      return ref_string(cand)
-    end
-  end
-
-  def store_anchor(obj, ref = nil)
-    anchor_name = obj['$anchor']
-    return if anchor_name.nil?
-    ref = obj['$ref'] if ref.nil?
-    raise Exception, 'ref is nil and no $ref or it is nil' if ref.nil?
-    @anchor2ref[anchor_name] = ref
-  end
-
-  def alter_anchors
-    replacements = {}
-    @anchor2ref.each do |a, r|
-      next if @schema_names.member?(a)
-      replacements[a] = ref_string(a)
-      @schema_names.add(a)
-    end
-    replacements.each do |a, r|
-      @anchor2ref[a] = r
-    end
-  end
-
-  def anchor_ref_replacement(ref)
-    @anchor2ref[ref[1...ref.size]] || ref
-  end
-end
-
-class ServerPath
-  # Probably moves to a separate file once processpaths and frequencies receive
-  # some attention.
-  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
-
-# The rest probably ends up in a gem that orders schemas and does nothing else.
-
-# 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

data/lib/common.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-# 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
-  return_value
-end
-
-def yesno(boolean)
-  boolean ? 'yes' : 'no'
-end
-
-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
-
-module Out
-  attr_reader :count
-
-  def put(message)
-    aargh(message)
-    count += 1
-  end
-end
-
-def split_path(p, spec = false)
-  parts = []
-  p = p.strip
-  unless spec
-    q = p.index('?')
-    p.slice!(0...q) unless q.nil?
-  end
-  p.split('/').each do |s|
-    next if s.empty?
-    s = { var: s } if spec && s.include?('{')
-    parts.push(s)
-  end
-  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)
-  doc = YAML.dump(doc, line_width: 1_000_000) unless doc.is_a?(String)
-  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
-  # 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
-        return -1 unless ppk.is_a? String
-        c = pk <=> ppk
-      else
-        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
-
-  # 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
-    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