torikago 0.0.1 → 0.1.0

data/lib/torikago/checker.rb

@@ -1,4 +1,5 @@
 require "pathname"
+require "ripper"
 require "yaml"
 
 module Torikago
@@ -6,37 +7,145 @@ module Torikago
   # manifests. This is intentionally conservative; runtime enforcement still
   # lives in Gateway.
   class Checker
-    Result = Struct.new(
-      :errors,
-      :scanned_file_count,
-      :gateway_call_count,
-      :manifest_count,
-      keyword_init: true
-    ) do
+    class Result
+      attr_accessor :dynamic_gateway_call_count, :errors, :scanned_file_count, :gateway_call_count, :manifest_count
+
+      def initialize(errors: Array.new, scanned_file_count: 0, gateway_call_count: 0, dynamic_gateway_call_count: 0, manifest_count: 0)
+        @errors = errors
+        @scanned_file_count = scanned_file_count
+        @gateway_call_count = gateway_call_count
+        @dynamic_gateway_call_count = dynamic_gateway_call_count
+        @manifest_count = manifest_count
+      end
+
       def ok?
         errors.empty?
       end
     end
 
-    CALL_PATTERN = /
-      Torikago::Gateway\.call\(
-      \s*
-      ["'](?<class_name>[A-Z][A-Za-z0-9:]+)["']
-    /x.freeze
+    GatewayCall = Struct.new(:class_name, :method_name, keyword_init: true)
+
+    class GatewayCallExtractor
+      attr_reader :calls, :dynamic_call_count
+
+      def initialize(source)
+        @sexp = Ripper.sexp(source)
+        @calls = Array.new
+        @dynamic_call_count = 0
+      end
+
+      def call
+        walk(sexp)
+        self
+      end
+
+      private
+
+      attr_reader :sexp
+
+      def walk(node)
+        return unless node.is_a?(Array)
+
+        extract(node) if node.first == :method_add_arg
+        node.each { |child| walk(child) if child.is_a?(Array) }
+      end
+
+      def extract(node)
+        call_node = node[1]
+        return unless call_node&.first == :call
+        return unless token_value(call_node[3]) == "invoke"
+
+        receiver = call_node[1]
+        arguments = arguments_from(node[2])
+
+        if gateway_constant?(receiver)
+          record(string_literal(arguments[0]), symbol_literal(arguments[1]))
+        elsif build_call?(receiver)
+          build_arguments = arguments_from(receiver[2])
+          record(string_literal(build_arguments[0]), symbol_literal(arguments[0]))
+        end
+      end
+
+      def record(class_name, method_name)
+        if class_name && method_name
+          calls << GatewayCall.new(class_name: class_name, method_name: method_name)
+        else
+          @dynamic_call_count += 1
+        end
+      end
+
+      def build_call?(node)
+        return false unless node&.first == :method_add_arg
+
+        call_node = node[1]
+        call_node&.first == :call &&
+          token_value(call_node[3]) == "build" &&
+          gateway_constant?(call_node[1])
+      end
+
+      def gateway_constant?(node)
+        constant_name(node) == "Torikago::Gateway"
+      end
+
+      def constant_name(node)
+        return unless node.is_a?(Array)
+
+        case node.first
+        when :var_ref, :const_ref, :top_const_ref
+          token_value(node[1])
+        when :const_path_ref
+          [constant_name(node[1]), token_value(node[2])].compact.join("::")
+        end
+      end
+
+      def arguments_from(node)
+        return Array.new unless node&.first == :arg_paren
+
+        args_add_block = node[1]
+        return Array.new unless args_add_block&.first == :args_add_block
+
+        args_add_block[1] || Array.new
+      end
+
+      def string_literal(node)
+        return unless node&.first == :string_literal
+
+        content = node[1]
+        parts = content&.first == :string_content ? content.drop(1) : Array.new
+        return unless parts.length == 1 && parts.first&.first == :@tstring_content
+
+        token_value(parts.first)
+      end
+
+      def symbol_literal(node)
+        return unless node&.first == :symbol_literal
+
+        symbol = node[1]
+        token = symbol&.first == :symbol ? symbol[1] : nil
+        token_value(token)&.to_sym
+      end
+
+      def token_value(token)
+        token[1] if token.is_a?(Array) && token.first.to_s.start_with?("@")
+      end
+    end
 
     def initialize(configuration:, source_roots:)
       @configuration = configuration
       @source_roots = Array(source_roots).map { |root| Pathname(root) }
-      @manifests = {}
+      @manifests = Hash.new
     end
 
     def call
-      errors = []
+      errors = Array.new
       gateway_call_count = 0
+      dynamic_gateway_call_count = 0
       scanned_files = source_files
 
       scanned_files.each do |path|
-        gateway_call_count += scan_gateway_calls(path, errors)
+        static_count, dynamic_count = scan_gateway_calls(path, errors)
+        gateway_call_count += static_count
+        dynamic_gateway_call_count += dynamic_count
       end
 
       manifest_count = 0
@@ -49,6 +158,7 @@ module Torikago
         errors: errors,
         scanned_file_count: scanned_files.size,
         gateway_call_count: gateway_call_count,
+        dynamic_gateway_call_count: dynamic_gateway_call_count,
         manifest_count: manifest_count
       )
     end
@@ -62,11 +172,11 @@ module Torikago
     end
 
     def scan_gateway_calls(path, errors)
-      content = File.read(path)
-      call_count = 0
-      content.to_enum(:scan, CALL_PATTERN).each do
-        call_count += 1
-        class_name = Regexp.last_match[:class_name]
+      extraction = GatewayCallExtractor.new(File.read(path)).call
+      extraction.calls.each do |gateway_call|
+        class_name = gateway_call.class_name
+        method_name = gateway_call.method_name
+
         # Public API names are expected to start with their owning module
         # namespace, e.g. Foo::ListProductsQuery targets the :foo box.
         target_box = infer_box_name(class_name)
@@ -74,30 +184,54 @@ module Torikago
         caller_box = infer_caller_box_from_path(path)
 
         if manifest_entry.nil?
-          errors << "#{path}: #{class_name} is not declared in #{target_box}/package_api.yml exports"
+          errors << "#{path}: #{class_name}##{method_name} is not declared in #{target_box}/package_api.yml exports"
+          next
+        end
+
+        methods = exported_methods(manifest_entry)
+        if !methods.empty? && !methods.include?(method_name.to_s)
+          errors << "#{path}: #{class_name}##{method_name} is not exported by #{target_box}/package_api.yml"
           next
         end
 
         next if caller_box.nil?
         next if caller_box == target_box
 
-        allowed_callers = Array(manifest_entry["allowed_callers"]).map(&:to_s)
+        allowed_callers = allowed_callers(manifest_entry).map { |caller| caller.to_s }
         next if allowed_callers.include?(caller_box.to_s)
 
-        errors << "#{path}: #{caller_box} is not allowed to call #{class_name}"
+        errors << "#{path}: #{caller_box} is not allowed to call #{class_name}##{method_name}"
       end
 
-      call_count
+      [extraction.calls.size, extraction.dynamic_call_count]
     end
 
     def validate_manifest_entries(definition, errors)
-      exported_package_apis(load_manifest(definition)).each_key do |class_name|
+      manifest_path = definition.root.join("package_api.yml")
+      exported_package_apis(load_manifest(definition)).each do |class_name, manifest_entry|
+        methods = exported_methods(manifest_entry)
+        if methods.empty?
+          errors << "#{manifest_path}: #{class_name} must declare a non-empty methods array"
+        end
+
         # The manifest is the contract, but the checker also catches stale
         # entries whose implementation file has been deleted or moved.
         expected_path = expected_public_api_path(definition, class_name)
-        next if expected_path.exist?
+        unless expected_path.exist?
+          errors << "#{manifest_path}: #{class_name} does not have a matching file at #{expected_path}"
+          next
+        end
+
+        next if methods.empty?
+
+        implemented_methods, dynamic_definition = public_instance_methods(expected_path, class_name)
+        next if dynamic_definition
+
+        methods.each do |method_name|
+          next if implemented_methods.include?(method_name)
 
-        errors << "#{definition.root.join('package_api.yml')}: #{class_name} does not have a matching file at #{expected_path}"
+          errors << "#{expected_path}: #{class_name}##{method_name} is exported but no public instance method definition was found"
+        end
       end
     end
 
@@ -112,9 +246,9 @@ module Torikago
         manifest_path = definition.root.join("package_api.yml")
         manifests[definition.name] =
           if manifest_path.exist?
-            YAML.safe_load(manifest_path.read, permitted_classes: [], aliases: false) || {}
+            YAML.safe_load(manifest_path.read, permitted_classes: Array.new, aliases: false) || Hash.new
           else
-            {}
+            Hash.new
           end
       end
     end
@@ -135,7 +269,122 @@ module Torikago
     end
 
     def exported_package_apis(manifest)
-      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+      manifest.fetch("exports") { manifest.fetch("public_api", Hash.new) }
+    end
+
+    def allowed_callers(manifest_entry)
+      return Array.new unless manifest_entry.is_a?(Hash)
+
+      allowed = manifest_entry["allowed_callers"]
+      return allowed if allowed.is_a?(Array)
+
+      Array.new
+    end
+
+    def exported_methods(manifest_entry)
+      return Array.new unless manifest_entry.is_a?(Hash)
+
+      methods = manifest_entry["methods"]
+      return methods.map(&:to_s) if methods.is_a?(Array)
+
+      Array.new
+    end
+
+    def public_instance_methods(path, class_name)
+      sexp = Ripper.sexp(File.read(path))
+      methods = Array.new
+      dynamic_definition = false
+
+      visit_definitions = lambda do |node, namespace|
+        next unless node.is_a?(Array)
+
+        case node.first
+        when :program
+          Array(node[1]).each { |child| visit_definitions.call(child, namespace) }
+        when :module
+          name = qualified_constant_name(node[1], namespace)
+          visit_definitions.call(node[2], name)
+        when :class
+          name = qualified_constant_name(node[1], namespace)
+          if name == class_name
+            class_body_methods(node[3]).tap do |result|
+              methods.concat(result.fetch(:methods))
+              dynamic_definition ||= result.fetch(:dynamic)
+            end
+          else
+            visit_definitions.call(node[3], name)
+          end
+        when :bodystmt
+          Array(node[1]).each { |child| visit_definitions.call(child, namespace) }
+        else
+          node.each { |child| visit_definitions.call(child, namespace) if child.is_a?(Array) }
+        end
+      end
+
+      visit_definitions.call(sexp, nil)
+      [methods.uniq, dynamic_definition]
+    end
+
+    def class_body_methods(body)
+      visibility = :public
+      methods = Array.new
+      dynamic = false
+      statements = body&.first == :bodystmt ? Array(body[1]) : Array.new
+
+      statements.each do |statement|
+        visibility_name = bare_call_name(statement)
+        case visibility_name
+        when "public"
+          visibility = :public
+          next
+        when "private"
+          visibility = :private
+          next
+        when "protected"
+          visibility = :protected
+          next
+        end
+
+        if statement&.first == :def
+          methods << statement[1][1].to_s if visibility == :public
+        elsif contains_call?(statement, "define_method")
+          dynamic = true
+        end
+      end
+
+      { methods: methods, dynamic: dynamic }
+    end
+
+    def bare_call_name(node)
+      return unless node&.first == :vcall
+
+      token = node[1]
+      token[1] if token&.first == :@ident
+    end
+
+    def contains_call?(node, method_name)
+      return false unless node.is_a?(Array)
+      return true if %i[vcall fcall].include?(node.first) && node.dig(1, 1) == method_name
+
+      node.any? { |child| child.is_a?(Array) && contains_call?(child, method_name) }
+    end
+
+    def qualified_constant_name(node, namespace)
+      name = constant_name(node)
+      return name if name&.include?("::") || namespace.nil?
+
+      "#{namespace}::#{name}"
+    end
+
+    def constant_name(node)
+      return unless node.is_a?(Array)
+
+      case node.first
+      when :var_ref, :const_ref, :top_const_ref
+        node.dig(1, 1)
+      when :const_path_ref
+        [constant_name(node[1]), node.dig(2, 1)].compact.join("::")
+      end
     end
 
     def underscore(name)

data/lib/torikago/cli.rb

@@ -13,7 +13,7 @@ module Torikago
         init
             interactively generate package_api.yml files and config/initializers/torikago.rb
         check
-            validate Gateway.call usage against package_api.yml
+            validate Gateway invocations against package_api.yml
         update-package-api [BOX]
             regenerate package_api.yml entries from the configured public API entrypoint
         help, --help, -h
@@ -74,7 +74,7 @@ module Torikago
         )
 
         manifest_path = module_root.join("package_api.yml")
-        manifest = manifest_path.exist? ? load_yaml_file(manifest_path) : { "exports" => {} }
+        manifest = manifest_path.exist? ? load_yaml_file(manifest_path) : { "exports" => Hash.new }
         manifest_path.write(render_package_api_manifest(manifest))
         stdout.puts("generated #{manifest_path}")
       end
@@ -102,7 +102,7 @@ module Torikago
       if result.ok?
         stdout.puts(
           "ok: scanned #{result.scanned_file_count} Ruby files, " \
-          "found #{result.gateway_call_count} Gateway.call usages, " \
+          "found #{result.gateway_call_count} static Gateway invocations, " \
           "validated #{result.manifest_count} package_api manifests"
         )
         0
@@ -110,7 +110,7 @@ module Torikago
         result.errors.each { |error| stderr.puts(error) }
         stderr.puts(
           "failed: scanned #{result.scanned_file_count} Ruby files, " \
-          "found #{result.gateway_call_count} Gateway.call usages, " \
+          "found #{result.gateway_call_count} static Gateway invocations, " \
           "validated #{result.manifest_count} package_api manifests, " \
           "#{result.errors.size} errors"
         )
@@ -158,7 +158,7 @@ module Torikago
     end
 
     def load_yaml_file(path)
-      YAML.safe_load(path.read, permitted_classes: [], aliases: false) || {}
+      YAML.safe_load(path.read, permitted_classes: Array.new, aliases: false) || Hash.new
     end
 
     def render_initializer(configuration)
@@ -166,7 +166,7 @@ module Torikago
         "# This file registers torikago runtime boundaries for your Rails app.",
         "#",
         "# Each config.register call defines one module root. Calls between modules",
-        "# should go through Torikago::Gateway.call(\"Module::ExportedApi\") instead",
+        "# should go through Torikago::Gateway.invoke(\"Module::ExportedApi\", :call) instead",
         "# of reaching across module constants directly.",
         "#",
         "# Options:",
@@ -178,6 +178,11 @@ module Torikago
         "#     Directory containing exported Package API classes. The conventional",
         "#     default is app/package_api.",
         "#",
+        "#   rails_engine:",
+        "#     Set true when the module owns a Rails::Engine entrypoint at",
+        "#     lib/<module_name>.rb. That entrypoint is then left for Rails and",
+        "#     skipped by the module Box runtime.",
+        "#",
         "#   gemfile:",
         "#     Optional module-local Gemfile. When Ruby::Box isolation is enabled,",
         "#     torikago prepends that module's resolved gem require paths inside the",
@@ -192,7 +197,7 @@ module Torikago
         "#",
         "#   bin/torikago update-package-api",
         "#",
-        "# To validate Gateway.call usage against package_api.yml, run:",
+        "# To validate Gateway invocations against package_api.yml, run:",
         "#",
         "#   bin/torikago check",
         "",
@@ -203,8 +208,16 @@ module Torikago
         lines << "  config.register("
         lines << "    :#{definition.name},"
         lines << "    root: Rails.root.join(\"#{definition.root.to_s}\"),"
-        lines << "    entrypoint: #{definition.entrypoint.inspect}#{definition.gemfile ? "," : ""}"
-        lines << "    gemfile: #{definition.gemfile.inspect}" if definition.gemfile
+        option_lines = Array.new
+        option_lines << "    entrypoint: #{definition.entrypoint.inspect}" if definition.entrypoint
+        option_lines << "    rails_engine: #{definition.rails_engine.inspect}" if definition.rails_engine
+        option_lines << "    setup: #{definition.setup.inspect}" if definition.setup
+        option_lines << "    gemfile: #{definition.gemfile.inspect}" if definition.gemfile
+
+        option_lines.each_with_index do |option_line, index|
+          comma = index == option_lines.length - 1 ? "" : ","
+          lines << "#{option_line}#{comma}"
+        end
         lines << "  )"
         lines << ""
       end
@@ -219,8 +232,9 @@ module Torikago
         #
         # Each key under exports is a class that may be called through:
         #
-        #   Torikago::Gateway.call("ModuleName::SomeQuery")
+        #   Torikago::Gateway.invoke("ModuleName::SomeQuery", :call)
         #
+        # methods lists the public instance methods exposed through Gateway.
         # allowed_callers lists other modules that may call that export. The
         # host app and the module itself are allowed implicitly.
         #

data/lib/torikago/configuration.rb

@@ -4,13 +4,13 @@ module Torikago
   # Stores module definitions declared by the host application. Other runtime
   # objects treat this as the source of truth for module roots and boot options.
   class Configuration
-    Definition = Struct.new(:name, :root, :entrypoint, :setup, :gemfile, keyword_init: true)
+    Definition = Struct.new(:name, :root, :entrypoint, :rails_engine, :setup, :gemfile, keyword_init: true)
 
     def initialize
-      @definitions = {}
+      @definitions = Hash.new
     end
 
-    def register(name, root:, entrypoint: nil, setup: nil, gemfile: nil)
+    def register(name, root:, entrypoint: nil, rails_engine: false, setup: nil, gemfile: nil)
       if @definitions.key?(name.to_sym)
         raise ArgumentError, "module already registered: #{name}"
       end
@@ -19,6 +19,7 @@ module Torikago
         name: name.to_sym,
         root: Pathname(root),
         entrypoint: entrypoint,
+        rails_engine: rails_engine,
         setup: setup,
         gemfile: gemfile
       )

data/lib/torikago/controller_endpoint.rb

@@ -0,0 +1,30 @@
+module Torikago
+  # A host-owned Rack-compatible route endpoint that dispatches directly to a
+  # controller class loaded inside a registered module runtime. It is not Rack
+  # middleware. The host router never resolves the controller constant, so
+  # Rails::Engine is not required for isolation.
+  class ControllerEndpoint
+    def initialize(module_name, controller_name, action_name, registry: nil)
+      @module_name = module_name.to_sym
+      @controller_name = controller_name.to_s
+      @action_name = action_name.to_sym
+      @registry = registry
+    end
+
+    def call(env)
+      registry.resolve(module_name).dispatch_controller(
+        env,
+        controller_name: controller_name,
+        action_name: action_name
+      )
+    end
+
+    private
+
+    attr_reader :action_name, :controller_name, :module_name
+
+    def registry
+      @registry || Torikago.registry
+    end
+  end
+end