torikago 0.0.1

data/lib/torikago/gateway.rb

@@ -0,0 +1,86 @@
+require "pathname"
+require "yaml"
+
+module Torikago
+  # Runtime entrypoint for all cross-module calls. It validates the package API
+  # manifest before dispatching into the target module container.
+  class Gateway
+    class << self
+      def call(...)
+        Torikago.gateway.call(...)
+      end
+    end
+
+    def initialize(registry:, configuration:, manifest_loader: nil)
+      @registry = registry
+      @configuration = configuration
+      @manifest_loader = manifest_loader || method(:load_manifest)
+      @manifests = {}
+    end
+
+    def call(public_api_class_name, *args, **kwargs)
+      target_module = infer_target_module(public_api_class_name)
+      caller_module = CurrentExecution.current_box
+
+      # Validation happens before resolving the container so denied calls do not
+      # accidentally boot or load the target module.
+      validate_public_api!(target_module, public_api_class_name, caller_module)
+      registry.resolve(target_module).call(public_api_class_name, *args, **kwargs)
+    end
+
+    private
+
+    attr_reader :configuration, :manifest_loader, :manifests, :registry
+
+    def validate_public_api!(target_module, public_api_class_name, caller_module)
+      target_name = target_module.to_sym
+      definition = configuration.fetch(target_name)
+      manifest = manifests.fetch(target_name) do
+        manifests[target_name] = manifest_loader.call(definition)
+      end
+
+      public_api_entry = exported_package_apis(manifest).fetch(public_api_class_name, nil)
+      if public_api_entry.nil?
+        raise PublicApiError, "package api export not declared for #{target_name}: #{public_api_class_name}"
+      end
+
+      return if caller_module.nil?
+
+      caller_name = caller_module.to_sym
+      # A module may always call its own public API; allowed_callers only governs
+      # calls crossing from one module box into another.
+      return if caller_name == target_name
+      return if dependency_allowed?(public_api_entry, caller_name)
+
+      raise DependencyError,
+            "module dependency not allowed: #{caller_name} -> #{target_name}##{public_api_class_name}"
+    end
+
+    def load_manifest(definition)
+      manifest_path = package_api_manifest_path(definition)
+
+      unless manifest_path.exist?
+        raise DependencyError,
+              "package_api manifest not found for #{definition.name}: #{manifest_path}"
+      end
+
+      YAML.safe_load(manifest_path.read, permitted_classes: [], aliases: false) || {}
+    end
+
+    def package_api_manifest_path(definition)
+      Pathname(definition.root).join("package_api.yml")
+    end
+
+    def infer_target_module(public_api_class_name)
+      public_api_class_name.split("::").first.downcase.to_sym
+    end
+
+    def exported_package_apis(manifest)
+      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+    end
+
+    def dependency_allowed?(public_api_entry, caller_name)
+      Array(public_api_entry["allowed_callers"]).map(&:to_sym).include?(caller_name)
+    end
+  end
+end

data/lib/torikago/package_api_updater.rb

@@ -0,0 +1,101 @@
+require "pathname"
+require "yaml"
+
+module Torikago
+  # Regenerates package_api.yml from files under a module's public API
+  # entrypoint while preserving caller permissions already chosen by humans.
+  class PackageApiUpdater
+    def initialize(configuration:)
+      @configuration = configuration
+    end
+
+    def call(module_name = nil)
+      definitions_for(module_name).each_with_object({}) do |definition, updates|
+        manifest_path = definition.root.join("package_api.yml")
+        existing_manifest = load_manifest(manifest_path)
+        updated_manifest = build_manifest(definition, existing_manifest)
+
+        manifest_path.write(render_manifest(updated_manifest))
+        updates[definition.name] = manifest_path
+      end
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def definitions_for(module_name)
+      return configuration.each_definition.to_a if module_name.nil?
+
+      [configuration.fetch(module_name)]
+    end
+
+    def load_manifest(path)
+      return {} unless path.exist?
+
+      YAML.safe_load(path.read, permitted_classes: [], aliases: false) || {}
+    end
+
+    def build_manifest(definition, existing_manifest)
+      existing_public_api = exported_package_apis(existing_manifest)
+
+      public_api_entries = discover_public_api_classes(definition).each_with_object({}) do |class_name, entries|
+        existing_entry = existing_public_api.fetch(class_name, {})
+
+        # update-package-api owns discovery, not policy. Keep allowed_callers so
+        # the command does not silently widen or narrow module dependencies.
+        entries[class_name] = {
+          "allowed_callers" => Array(existing_entry["allowed_callers"]).map(&:to_s)
+        }
+      end
+
+      { "exports" => public_api_entries }
+    end
+
+    def exported_package_apis(manifest)
+      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+    end
+
+    def render_manifest(manifest)
+      <<~YAML
+        # This file declares the Package APIs exported by this module.
+        #
+        # Each key under exports is a class that may be called through:
+        #
+        #   Torikago::Gateway.call("ModuleName::SomeQuery")
+        #
+        # allowed_callers lists other modules that may call that export. The
+        # host app and the module itself are allowed implicitly.
+        #
+      YAML
+        .then { |header| header + YAML.dump(manifest) }
+    end
+
+    def discover_public_api_classes(definition)
+      Dir[public_api_root(definition).join("**/*.rb").to_s].sort.map do |path|
+        relative_path = Pathname(path).relative_path_from(public_api_root(definition)).to_s
+        class_name_from(relative_path)
+      end
+    end
+
+    def public_api_root(definition)
+      return definition.root.join("app/package_api") if definition.entrypoint.nil?
+
+      # Match EngineContainer and Checker: directory entrypoints are roots,
+      # while file entrypoints imply implementations live beside the file.
+      candidate = definition.root.join(definition.entrypoint)
+      return candidate if candidate.directory?
+      return candidate unless candidate.extname == ".rb"
+
+      candidate.dirname
+    end
+
+    def class_name_from(relative_path)
+      relative_path.delete_suffix(".rb").split("/").map { |segment| camelize(segment) }.join("::")
+    end
+
+    def camelize(segment)
+      segment.split("_").map(&:capitalize).join
+    end
+  end
+end

data/lib/torikago/registry.rb

@@ -0,0 +1,34 @@
+module Torikago
+  # Lazily builds one EngineContainer per registered module and reuses it for
+  # subsequent Gateway calls.
+  class Registry
+    def initialize(configuration:, &container_factory)
+      @configuration = configuration
+      @containers = {}
+      @container_factory = container_factory || method(:build_container)
+    end
+
+    def resolve(name)
+      normalized_name = name.to_sym
+
+      @containers.fetch(normalized_name) do
+        definition = @configuration.fetch(name)
+        container = @container_factory.call(definition)
+
+        @containers[definition.name] = container
+      end
+    end
+
+    private
+
+    def build_container(definition)
+      EngineContainer.new(
+        name: definition.name,
+        module_root: definition.root,
+        entrypoint: definition.entrypoint,
+        setup: definition.setup,
+        gemfile: definition.gemfile
+      )
+    end
+  end
+end

data/lib/torikago/version.rb

@@ -0,0 +1,3 @@
+module Torikago
+  VERSION = "0.0.1"
+end

data/lib/torikago.rb

@@ -0,0 +1,71 @@
+require_relative "torikago/configuration"
+require_relative "torikago/current_execution"
+require_relative "torikago/checker"
+require_relative "torikago/cli"
+require_relative "torikago/engine_container"
+require_relative "torikago/errors"
+require_relative "torikago/gateway"
+require_relative "torikago/package_api_updater"
+require_relative "torikago/registry"
+require_relative "torikago/version"
+
+module Torikago
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      # Rebuild runtime collaborators after configuration changes so newly
+      # registered modules are visible to future Gateway calls.
+      reset_runtime_state!
+      configuration
+    end
+
+    def gateway
+      @gateway ||= Gateway.new(registry: registry, configuration: configuration)
+    end
+
+    def registry
+      @registry ||= Registry.new(configuration: configuration)
+    end
+
+    def version
+      VERSION
+    end
+
+    private
+
+    def rails_app?
+      return false unless defined?(Rails)
+      return false unless Rails.respond_to?(:application)
+
+      !Rails.application.nil?
+    end
+
+    def ruby_box_enabled?
+      ENV["RUBY_BOX"] == "1"
+    end
+
+    def warn_if_ruby_box_is_disabled_in_rails!
+      return unless rails_app?
+      return if ruby_box_enabled?
+
+      # The gem can run without Ruby::Box for local development, but a Rails app
+      # using torikago usually expects runtime isolation to be active.
+      warn "[warn] torikago is loaded in a Rails app without RUBY_BOX=1; Ruby::Box isolation is disabled."
+    end
+
+    def reset_runtime_state!
+      @gateway = nil
+      @registry = nil
+    end
+  end
+
+  def version
+    VERSION
+  end
+end
+
+Torikago.send(:warn_if_ruby_box_is_disabled_in_rails!)

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+require "minitest/autorun"
+
+ENV["RUBY_BOX"] = "1"
+ENV["RAILS_ENV"] = "test"
+
+lib_dir = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require "torikago"

data/test/torikago/checker.rb

@@ -0,0 +1,164 @@
+require_relative "../test_helper"
+require "fileutils"
+require "tmpdir"
+
+class TorikagoCheckerTest < Minitest::Test
+  def test_check_returns_no_errors_for_declared_calls
+    with_project do |root, configuration|
+      FileUtils.mkdir_p(File.join(root, "modules/foo"))
+      File.write(
+        File.join(root, "modules/foo/service.rb"),
+        <<~RUBY
+          class FooService
+            def call
+              Torikago::Gateway.call("Bar::SubmitOrderCommand")
+            end
+          end
+        RUBY
+      )
+
+      checker = Torikago::Checker.new(
+        configuration: configuration,
+        source_roots: [File.join(root, "modules")]
+      )
+
+      result = Dir.chdir(root) { checker.call }
+
+      assert result.ok?
+      assert_equal [], result.errors
+      assert_equal 2, result.scanned_file_count
+      assert_equal 1, result.gateway_call_count
+      assert_equal 2, result.manifest_count
+    end
+  end
+
+  def test_check_reports_undeclared_calls_and_missing_public_api_files
+    with_project do |root, configuration|
+      FileUtils.mkdir_p(File.join(root, "modules/foo"))
+      File.write(
+        File.join(root, "modules/foo/service.rb"),
+        <<~RUBY
+          class FooService
+            def call
+              Torikago::Gateway.call("Bar::MissingCommand")
+            end
+          end
+        RUBY
+      )
+
+      File.write(
+        File.join(root, "modules/bar/package_api.yml"),
+        <<~YAML
+          exports:
+            Bar::MissingCommand:
+              allowed_callers:
+                - foo
+        YAML
+      )
+
+      checker = Torikago::Checker.new(
+        configuration: configuration,
+        source_roots: [File.join(root, "modules")]
+      )
+
+      result = Dir.chdir(root) { checker.call }
+
+      refute result.ok?
+      assert_equal 1, result.errors.size
+      assert_match(/matching file/, result.errors.first)
+    end
+  end
+
+  def test_check_uses_a_configured_entrypoint_directory_when_matching_manifest_files
+    with_project(entrypoint: "components/public_api") do |root, configuration|
+      FileUtils.mkdir_p(File.join(root, "modules/foo"))
+      File.write(
+        File.join(root, "modules/foo/service.rb"),
+        <<~RUBY
+          class FooService
+            def call
+              Torikago::Gateway.call("Bar::SubmitOrderCommand")
+            end
+          end
+        RUBY
+      )
+
+      checker = Torikago::Checker.new(
+        configuration: configuration,
+        source_roots: [File.join(root, "modules")]
+      )
+
+      result = Dir.chdir(root) { checker.call }
+
+      assert result.ok?
+      assert_equal [], result.errors
+    end
+  end
+
+  def test_check_does_not_match_manifest_entries_against_parent_when_configured_entrypoint_directory_is_missing
+    Dir.mktmpdir("torikago-checker") do |root|
+      foo_root = File.join(root, "modules/foo")
+      FileUtils.mkdir_p(File.join(foo_root, "app/models/foo"))
+      File.write(File.join(foo_root, "app/models/foo/widget.rb"), "")
+      File.write(
+        File.join(foo_root, "package_api.yml"),
+        <<~YAML
+          exports:
+            Models::Foo::Widget:
+              allowed_callers: []
+        YAML
+      )
+
+      configuration = Torikago::Configuration.new
+      configuration.register(:foo, root: foo_root, entrypoint: "app/package_api")
+
+      checker = Torikago::Checker.new(
+        configuration: configuration,
+        source_roots: [File.join(root, "modules")]
+      )
+
+      result = Dir.chdir(root) { checker.call }
+
+      refute result.ok?
+      assert_equal 1, result.errors.size
+      assert_match(/matching file/, result.errors.first)
+    end
+  end
+
+  private
+
+  def with_project(entrypoint: nil)
+    Dir.mktmpdir("torikago-checker") do |root|
+      foo_root = File.join(root, "modules/foo")
+      bar_root = File.join(root, "modules/bar")
+      public_api_root = entrypoint ? File.join(bar_root, entrypoint, "bar") : File.join(bar_root, "app/package_api/bar")
+      FileUtils.mkdir_p(public_api_root)
+
+      File.write(
+        File.join(bar_root, "package_api.yml"),
+        <<~YAML
+          exports:
+            Bar::SubmitOrderCommand:
+              allowed_callers:
+                - foo
+        YAML
+      )
+
+      File.write(
+        File.join(public_api_root, "submit_order_command.rb"),
+        <<~RUBY
+          class Bar::SubmitOrderCommand
+            def call
+            end
+          end
+        RUBY
+      )
+
+      configuration = Torikago::Configuration.new
+      configuration.register(:foo, root: foo_root)
+      configuration.register(:bar, root: bar_root, entrypoint: entrypoint)
+
+      yield root, configuration
+    end
+  end
+end

data/test/torikago/cli.rb

@@ -0,0 +1,143 @@
+require_relative "../test_helper"
+require "stringio"
+require "tmpdir"
+require "fileutils"
+require "yaml"
+
+class TorikagoCliTest < Minitest::Test
+  def test_help_option_prints_usage
+    stdout = StringIO.new
+    stderr = StringIO.new
+
+    exit_code = Torikago::CLI.new(stdout: stdout, stderr: stderr).run(["--help"])
+
+    assert_equal 0, exit_code
+    assert_match(/usage: torikago COMMAND/, stdout.string)
+    assert_match(/init/, stdout.string)
+    assert_match(/configured public API entrypoint/, stdout.string)
+    assert_equal "", stderr.string
+  end
+
+  def test_init_interactively_generates_manifests_and_initializer
+    Dir.mktmpdir("torikago-init") do |root|
+      FileUtils.mkdir_p(File.join(root, "config/initializers"))
+      FileUtils.mkdir_p(File.join(root, "modules/foo/app/package_api/foo"))
+      FileUtils.mkdir_p(File.join(root, "modules/bar/components/public_api/bar"))
+
+      File.write(
+        File.join(root, "modules/foo/app/package_api/foo/list_products_query.rb"),
+        <<~RUBY
+          class Foo::ListProductsQuery
+          end
+        RUBY
+      )
+
+      File.write(
+        File.join(root, "modules/bar/components/public_api/bar/submit_order_command.rb"),
+        <<~RUBY
+          class Bar::SubmitOrderCommand
+          end
+        RUBY
+      )
+
+      stdin = StringIO.new("modules\ncomponents/public_api\n\nY\n")
+      stdout = StringIO.new
+      stderr = StringIO.new
+
+      exit_code = Dir.chdir(root) do
+        Torikago::CLI.new(stdin: stdin, stdout: stdout, stderr: stderr).run(["init"])
+      end
+
+      assert_equal 0, exit_code
+      assert_equal "", stderr.string
+
+      foo_manifest = YAML.safe_load(File.read(File.join(root, "modules/foo/package_api.yml")))
+      bar_manifest = YAML.safe_load(File.read(File.join(root, "modules/bar/package_api.yml")))
+      initializer = File.read(File.join(root, "config/initializers/torikago.rb"))
+
+      assert_equal({ "allowed_callers" => [] }, foo_manifest.dig("exports", "Foo::ListProductsQuery"))
+      assert_equal({ "allowed_callers" => [] }, bar_manifest.dig("exports", "Bar::SubmitOrderCommand"))
+      assert_match(/root: Rails\.root\.join\("modules\/bar"\)/, initializer)
+      assert_match(/entrypoint: "components\/public_api"/, initializer)
+      assert_match(/root: Rails\.root\.join\("modules\/foo"\)/, initializer)
+      assert_match(/entrypoint: "app\/package_api"/, initializer)
+      assert_match(/Run `torikago update-package-api` now\?/, stdout.string)
+      assert_match(/updated 2 package_api manifests/, stdout.string)
+    end
+  end
+
+  def test_check_prints_summary_information
+    with_cli_project do |root|
+      stdout = StringIO.new
+      stderr = StringIO.new
+
+      exit_code = Dir.chdir(root) do
+        Torikago::CLI.new(stdout: stdout, stderr: stderr).run(["check"])
+      end
+
+      assert_equal 0, exit_code
+      assert_match(/scanned 2 Ruby files/, stdout.string)
+      assert_match(/found 1 Gateway\.call usages/, stdout.string)
+      assert_match(/validated 2 package_api manifests/, stdout.string)
+      assert_equal "", stderr.string
+    end
+  end
+
+  def test_update_package_api_prints_updated_count
+    with_cli_project do |root|
+      stdout = StringIO.new
+      stderr = StringIO.new
+
+      exit_code = Dir.chdir(root) do
+        Torikago::CLI.new(stdout: stdout, stderr: stderr).run(["update-package-api", "bar"])
+      end
+
+      assert_equal 0, exit_code
+      assert_match(/updated .*modules\/bar\/package_api\.yml/, stdout.string)
+      assert_match(/updated 1 package_api manifest/, stdout.string)
+      assert_equal "", stderr.string
+    end
+  end
+
+  private
+
+  def with_cli_project
+    Dir.mktmpdir("torikago-cli") do |root|
+      FileUtils.mkdir_p(File.join(root, "modules/foo"))
+      FileUtils.mkdir_p(File.join(root, "modules/bar/app/package_api/bar"))
+
+      File.write(
+        File.join(root, "modules/foo/service.rb"),
+        <<~RUBY
+          class FooService
+            def call
+              Torikago::Gateway.call("Bar::SubmitOrderCommand")
+            end
+          end
+        RUBY
+      )
+
+      File.write(
+        File.join(root, "modules/bar/package_api.yml"),
+        <<~YAML
+          exports:
+            Bar::SubmitOrderCommand:
+              allowed_callers:
+                - foo
+        YAML
+      )
+
+      File.write(
+        File.join(root, "modules/bar/app/package_api/bar/submit_order_command.rb"),
+        <<~RUBY
+          class Bar::SubmitOrderCommand
+            def call
+            end
+          end
+        RUBY
+      )
+
+      yield root
+    end
+  end
+end

data/test/torikago/configuration.rb

@@ -0,0 +1,74 @@
+require_relative "../test_helper"
+
+class TorikagoConfigurationTest < Minitest::Test
+  def setup
+    @configuration = Torikago::Configuration.new
+  end
+
+  def test_register_stores_definition_for_a_module
+    @configuration.register(
+      :foo,
+      root: "/modules/foo",
+      entrypoint: "lib/foo/box_runtime.rb",
+      setup: "config/box_setup.rb",
+      gemfile: "Gemfile"
+    )
+
+    definition = @configuration.fetch(:foo)
+
+    assert_equal :foo, definition.name
+    assert_equal "/modules/foo", definition.root.to_s
+    assert_equal "lib/foo/box_runtime.rb", definition.entrypoint
+    assert_equal "config/box_setup.rb", definition.setup
+    assert_equal "Gemfile", definition.gemfile
+  end
+
+  def test_registered_distinguishes_registered_and_unregistered_modules
+    @configuration.register(
+      :foo,
+      root: "/modules/foo",
+      entrypoint: "lib/foo/box_runtime.rb"
+    )
+
+    assert @configuration.registered?(:foo)
+    refute @configuration.registered?(:bar)
+  end
+
+  def test_module_names_are_normalized_between_string_and_symbol
+    @configuration.register(
+      "foo",
+      root: "/modules/foo",
+      entrypoint: "lib/foo/box_runtime.rb"
+    )
+
+    assert @configuration.registered?(:foo)
+    assert @configuration.registered?("foo")
+    assert_equal :foo, @configuration.fetch("foo").name
+  end
+
+  def test_fetch_fails_clearly_for_an_unknown_module
+    error = assert_raises(KeyError) do
+      @configuration.fetch(:missing)
+    end
+
+    assert_match(/missing/, error.message)
+  end
+
+  def test_register_rejects_duplicate_module_names
+    @configuration.register(
+      :foo,
+      root: "/modules/foo",
+      entrypoint: "lib/foo/box_runtime.rb"
+    )
+
+    error = assert_raises(ArgumentError) do
+      @configuration.register(
+        "foo",
+        root: "/modules/another_foo",
+        entrypoint: "lib/foo/alternative_runtime.rb"
+      )
+    end
+
+    assert_match(/foo/, error.message)
+  end
+end