apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/export/pipeline.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class Pipeline
+      class << self
+        def generate(export_name, api_base_path, format: nil, key_format: nil, locale: nil, version: nil)
+          Export.generate(export_name, api_base_path, format:, key_format:, locale:, version:)
+        end
+
+        def write(api_base_path: nil, export_name: nil, format: nil, key_format: nil, locale: nil, output:, version: nil)
+          raise ArgumentError, 'output path required' unless output
+
+          if Writer.file_path?(output) && (api_base_path.nil? || export_name.nil?)
+            raise ArgumentError,
+                  'api_base_path and export_name required when output is a file'
+          end
+
+          api_classes = api_base_path ? [find_api_class(api_base_path)] : API.values
+
+          start_time = Time.zone.now
+          count = 0
+
+          Rails.logger.debug 'Generating artifacts...'
+
+          api_classes.each do |api_class|
+            available_exports = export_name ? [export_name.to_sym] : api_class.export_configs.keys
+
+            available_exports.each do |name|
+              count += generate_file(
+                api_class:,
+                format:,
+                key_format:,
+                locale:,
+                output:,
+                version:,
+                export_name: name,
+              )
+            end
+          end
+
+          Rails.logger.debug "\nGenerated #{count} file#{count == 1 ? '' : 's'} in #{(Time.zone.now - start_time).round(2)}s"
+
+          count
+        end
+
+        def clean(output:)
+          raise ArgumentError, 'output path required' unless output
+
+          Writer.clean(output:)
+        end
+
+        private
+
+        def find_api_class(api_base_path)
+          API.find!(api_base_path)
+        end
+
+        def generate_file(api_class:, export_name:, format:, key_format:, locale:, output:, version:)
+          api_base_path = api_class.base_path
+
+          options = { format:, key_format:, locale:, version: }.compact
+          options_label = options.any? ? " (#{options.map { |key, value| "#{key}: #{value}" }.join(', ')})" : ''
+          Rails.logger.debug "  ✓ #{api_base_path} to #{export_name}#{options_label}"
+
+          content = generate(export_name, api_base_path, format:, key_format:, locale:, version:)
+          export_class = Registry.find!(export_name)
+          extension = export_class.file_extension_for(format:)
+
+          file_path = Writer.write(
+            api_base_path:,
+            content:,
+            export_name:,
+            extension:,
+            output:,
+          )
+
+          Rails.logger.debug "    to #{file_path}"
+          1
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/export/registry.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class Registry < Apiwork::Registry
+      class << self
+        def register(export_class)
+          raise ArgumentError, 'Export must inherit from Apiwork::Export::Base' unless export_class < Base
+          raise ArgumentError, "Export #{export_class} must define an export_name" unless export_class.export_name
+
+          store[export_class.export_name] = export_class
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/export/surface_resolver.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class SurfaceResolver
+      class << self
+        def resolve(api)
+          new(api)
+        end
+      end
+
+      def initialize(api)
+        @api = api
+      end
+
+      def types
+        @types ||= compute_reachable_types
+      end
+
+      def enums
+        @enums ||= compute_reachable_enums
+      end
+
+      private
+
+      def compute_reachable_types
+        type_names = collect_type_names_from_actions
+        expand_transitive_dependencies(type_names)
+        @api.types.select { |name, _| type_names.include?(name) }
+      end
+
+      def compute_reachable_enums
+        enum_names = collect_enum_names_from_actions
+        collect_enum_names_from_types(types, enum_names)
+        @api.enums.select { |name, _| enum_names.include?(name) }
+      end
+
+      def collect_type_names_from_actions
+        type_names = Set.new
+        @api.resources.each_value do |resource|
+          collect_types_from_resource(resource, type_names)
+        end
+        type_names
+      end
+
+      def collect_types_from_resource(resource, type_names)
+        resource.actions.each_value do |action|
+          collect_types_from_action(action, type_names)
+        end
+        resource.resources.each_value do |nested|
+          collect_types_from_resource(nested, type_names)
+        end
+      end
+
+      def collect_types_from_action(action, type_names)
+        action.request.query.each_value { |param| collect_types_from_param(param, type_names) }
+        action.request.body.each_value { |param| collect_types_from_param(param, type_names) }
+        collect_types_from_param(action.response.body, type_names) if action.response.body
+      end
+
+      def collect_types_from_param(param, type_names)
+        type_names << param.reference if param.reference?
+
+        param.shape.each_value { |nested| collect_types_from_param(nested, type_names) } if param.object?
+
+        if param.array?
+          collect_types_from_param(param.of, type_names) if param.of
+          param.shape.each_value { |nested| collect_types_from_param(nested, type_names) }
+        end
+
+        return unless param.union?
+
+        param.variants.each { |variant| collect_types_from_param(variant, type_names) }
+      end
+
+      def expand_transitive_dependencies(type_names)
+        added = true
+
+        while added
+          added = false
+          type_names.dup.each do |type_name|
+            type = @api.types[type_name]
+            next unless type
+
+            collect_reference_names_from_type(type).each do |reference_name|
+              next unless @api.types.key?(reference_name)
+              next if type_names.include?(reference_name)
+
+              type_names << reference_name
+              added = true
+            end
+          end
+        end
+      end
+
+      def collect_reference_names_from_type(type)
+        reference_names = []
+
+        if type.object?
+          reference_names.concat(type.extends) if type.extends?
+          type.shape.each_value { |param| collect_reference_names_from_param(param, reference_names) }
+        elsif type.union?
+          type.variants.each { |param| collect_reference_names_from_param(param, reference_names) }
+        end
+
+        reference_names.uniq
+      end
+
+      def collect_reference_names_from_param(param, reference_names)
+        reference_names << param.reference if param.reference?
+
+        param.shape.each_value { |nested| collect_reference_names_from_param(nested, reference_names) } if param.object?
+
+        if param.array?
+          collect_reference_names_from_param(param.of, reference_names) if param.of
+          param.shape.each_value { |nested| collect_reference_names_from_param(nested, reference_names) }
+        end
+
+        param.variants.each { |variant| collect_reference_names_from_param(variant, reference_names) } if param.union?
+      end
+
+      def collect_enum_names_from_actions
+        enum_names = Set.new
+        @api.resources.each_value do |resource|
+          collect_enums_from_resource(resource, enum_names)
+        end
+        enum_names
+      end
+
+      def collect_enums_from_resource(resource, enum_names)
+        resource.actions.each_value do |action|
+          collect_enums_from_action(action, enum_names)
+        end
+        resource.resources.each_value do |nested|
+          collect_enums_from_resource(nested, enum_names)
+        end
+      end
+
+      def collect_enums_from_action(action, enum_names)
+        action.request.query.each_value { |param| collect_enums_from_param(param, enum_names) }
+        action.request.body.each_value { |param| collect_enums_from_param(param, enum_names) }
+        collect_enums_from_param(action.response.body, enum_names) if action.response.body
+      end
+
+      def collect_enums_from_param(param, enum_names)
+        enum_names << param.enum if param.enum_reference?
+
+        param.shape.each_value { |nested| collect_enums_from_param(nested, enum_names) } if param.object?
+
+        if param.array?
+          collect_enums_from_param(param.of, enum_names) if param.of
+          param.shape.each_value { |nested| collect_enums_from_param(nested, enum_names) }
+        end
+
+        return unless param.union?
+
+        param.variants.each { |variant| collect_enums_from_param(variant, enum_names) }
+      end
+
+      def collect_enum_names_from_types(resolved_types, enum_names)
+        resolved_types.each_value do |type|
+          collect_enums_from_type(type, enum_names)
+        end
+      end
+
+      def collect_enums_from_type(type, enum_names)
+        if type.object?
+          type.shape.each_value { |param| collect_enums_from_type_param(param, enum_names) }
+        elsif type.union?
+          type.variants.each { |param| collect_enums_from_type_param(param, enum_names) }
+        end
+      end
+
+      def collect_enums_from_type_param(param, enum_names)
+        enum_names << param.enum if param.enum_reference?
+        enum_names << param.reference if param.reference? && @api.enums.key?(param.reference)
+
+        param.shape.each_value { |nested| collect_enums_from_type_param(nested, enum_names) } if param.object?
+
+        if param.array?
+          collect_enums_from_type_param(param.of, enum_names) if param.of
+          param.shape.each_value { |nested| collect_enums_from_type_param(nested, enum_names) }
+        end
+
+        param.variants.each { |variant| collect_enums_from_type_param(variant, enum_names) } if param.union?
+      end
+    end
+  end
+end

data/lib/apiwork/export/type_analysis.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class TypeAnalysis
+      PRIMITIVE_TYPES = %i[
+        string integer boolean datetime date uuid object array
+        decimal float literal union enum text binary json number time
+        unknown
+      ].to_set.freeze
+
+      class << self
+        def topological_sort_types(all_types)
+          graph = build_dependency_graph(all_types)
+          lazy_types = find_cycle_breaking_types(graph)
+          sort_with_lazy_types(all_types, graph, lazy_types)
+        end
+
+        def cycle_breaking_types(all_types)
+          find_cycle_breaking_types(build_dependency_graph(all_types))
+        end
+
+        def type_references(definition, filter: :custom_only)
+          references = []
+          collect_references(definition, references, filter)
+          references.uniq
+        end
+
+        def primitive_type?(type)
+          PRIMITIVE_TYPES.include?(type)
+        end
+
+        private
+
+        def build_dependency_graph(all_types)
+          type_keys = all_types.keys
+          all_types.transform_values { |shape| type_references(shape, filter: type_keys) }
+        end
+
+        def find_cycle_breaking_types(graph)
+          lazy_types = Set.new
+
+          find_strongly_connected_components(graph).each do |component|
+            next if component.size == 1 && !graph[component.first].include?(component.first)
+
+            lazy_types.add(component.min_by(&:to_s))
+          end
+
+          lazy_types
+        end
+
+        def sort_with_lazy_types(all_types, graph, lazy_types)
+          dependencies = build_non_lazy_dependencies(all_types, graph, lazy_types)
+          sorted = lazy_types.to_a.sort_by(&:to_s)
+          remaining = dependencies.keys.sort_by(&:to_s)
+
+          until remaining.empty?
+            ready = remaining.select { |type_name| dependencies[type_name].empty? }
+            break if ready.empty?
+
+            ready.sort_by(&:to_s).each do |type_name|
+              sorted << type_name
+              remaining.delete(type_name)
+              dependencies.each_value { |type_dependencies| type_dependencies.delete(type_name) }
+            end
+          end
+
+          sorted.concat(remaining.sort_by(&:to_s))
+          sorted.map { |type_name| [type_name, all_types[type_name]] }
+        end
+
+        def build_non_lazy_dependencies(all_types, graph, lazy_types)
+          all_types.each_key.with_object({}) do |type_name, dependencies|
+            next if lazy_types.include?(type_name)
+
+            dependencies[type_name] = (graph[type_name] - lazy_types.to_a - [type_name]).to_set
+          end
+        end
+
+        def find_strongly_connected_components(graph)
+          state = { components: [], index: 0, indices: {}, lowlinks: {}, on_stack: Set.new, stack: [] }
+
+          graph.each_key do |node|
+            tarjan_visit(node, graph, state) unless state[:indices][node]
+          end
+
+          state[:components]
+        end
+
+        def tarjan_visit(node, graph, state)
+          state[:indices][node] = state[:lowlinks][node] = state[:index]
+          state[:index] += 1
+          state[:stack].push(node)
+          state[:on_stack].add(node)
+
+          (graph[node] || []).each do |successor|
+            if state[:indices][successor].nil?
+              tarjan_visit(successor, graph, state)
+              state[:lowlinks][node] = [state[:lowlinks][node], state[:lowlinks][successor]].min
+            elsif state[:on_stack].include?(successor)
+              state[:lowlinks][node] = [state[:lowlinks][node], state[:indices][successor]].min
+            end
+          end
+
+          return unless state[:lowlinks][node] == state[:indices][node]
+
+          component = []
+          loop do
+            successor = state[:stack].pop
+            state[:on_stack].delete(successor)
+            component << successor
+            break if successor == node
+          end
+          state[:components] << component
+        end
+
+        def collect_references(node, references, filter)
+          return unless node.is_a?(Hash)
+
+          extract_type_field(node, references, filter)
+          extract_of_field(node[:of], references, filter)
+          extract_extends_field(node[:extends], references, filter)
+
+          node[:variants]&.each { |variant| collect_references(variant, references, filter) }
+          node[:shape]&.each_value { |param| collect_references(param, references, filter) }
+        end
+
+        def extract_type_field(node, references, filter)
+          type_value = node[:type]
+          return unless type_value
+
+          type_to_add = [:reference, 'reference'].include?(type_value) ? node[:reference] : type_value
+          add_if_matches_filter(references, type_to_add, filter)
+        end
+
+        def extract_of_field(of, references, filter)
+          return unless of
+
+          if of.is_a?(Hash)
+            collect_references(of, references, filter)
+          else
+            add_if_matches_filter(references, of, filter)
+          end
+        end
+
+        def extract_extends_field(extends, references, filter)
+          extends&.each do |extended_type|
+            if extended_type.is_a?(Hash)
+              collect_references(extended_type, references, filter)
+            else
+              add_if_matches_filter(references, extended_type, filter)
+            end
+          end
+        end
+
+        def add_if_matches_filter(references, type_symbol, filter)
+          type_symbol = type_symbol.to_sym if type_symbol.is_a?(String)
+          return unless type_symbol.is_a?(Symbol)
+
+          case filter
+          when :custom_only
+            references << type_symbol unless primitive_type?(type_symbol)
+          when Array
+            references << type_symbol if filter.include?(type_symbol)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/export/type_script.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class TypeScript < Base
+      export_name :typescript
+      output :string
+      file_extension '.ts'
+
+      option :version, default: '5', enum: %w[4 5], type: :string
+
+      def generate
+        TypeScriptMapper.map(self, surface)
+      end
+
+      private
+
+      def surface
+        @surface ||= SurfaceResolver.resolve(api)
+      end
+    end
+  end
+end