klenod-build 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a05a70d821a5b94964b4bade32066b9fd1bdade13d2b3899becdeb46d3d33ef
+  data.tar.gz: 68ac76064521f6ca7678d51256672d5ea9161814215bf4c9e3b5a3f743350bc8
+SHA512:
+  metadata.gz: 440df52a915ecb0b8312622268b94d413c3447d80912ef42a797a959aaadca42ec3c108a08439d79eb7cf9fff0d7baf4a5425e565d087b4f6b18efee84d0f2df
+  data.tar.gz: 1ddb4e48b0156a21160fa3d93f855ab657bc4ed40d323e5f3d2f6bbd9dc3d27b36c093ec9731b1eeb791a4b601499721ce89665c23c84be4ad57c02c84491d9f

data/README.md

@@ -0,0 +1,29 @@
+# klenod-build
+
+`klenod-build` builds [Klenod](https://github.com/aalin/klenod) bundles.
+
+It owns development and build-time behavior:
+
+- module resolving and graph collection
+- plugins
+- asset generation
+- bundle serialization
+- a basic `klenod` CLI
+- file watching and updates in development mode
+
+Use this gem when building an application, running development tooling, or authoring build plugins.
+
+```ruby
+require "klenod/build"
+
+context = Klenod::Build::Context.new(source_dir: "src")
+context.build(entrypoints: ["pages/server"], output: "dist/klenod.bundle")
+```
+
+Then you can load that bundle with [klenod-runtime](https://github.com/aalin/klenod/tree/main/gems/klenod-runtime).
+
+The CLI can also generate a [Graphviz](https://graphviz.org/) DOT-file from a generated bundle:
+
+```sh
+bundle exec klenod graph dist/klenod.bundle > graph.dot
+```

data/lib/klenod/build/asset.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "async"
+require "fileutils"
+require "stringio"
+
+module Klenod
+  module Build
+    class Asset
+      attr_reader :logical_name, :content_hash, :output_path, :source_path, :content_type, :metadata, :queue_kind, :error
+
+      def initialize(logical_name, content_hash, output_path, source_path, bytes, content_type, metadata, generator: nil, writer: nil, queue: nil, queue_kind: :cpu)
+        @logical_name = logical_name
+        @content_hash = content_hash
+        @output_path = output_path
+        @source_path = source_path
+        @bytes = bytes
+        @content_type = content_type
+        @metadata = metadata
+        @generator = generator
+        @writer = writer
+        @queue = queue
+        @queue_kind = queue_kind
+        @disk_path = nil
+        @task = nil
+        @mutex = Mutex.new
+        @state = (bytes || (source_path && !generator && !writer)) ? :ready : :pending
+        @error = nil
+      end
+
+      def self.generated(logical_name, content_hash, output_path, source_path, content_type, metadata, writer: nil, queue: nil, queue_kind: :cpu, &generator)
+        new(logical_name, content_hash, output_path, source_path, nil, content_type, metadata, generator: generator, writer: writer, queue: queue, queue_kind: queue_kind)
+      end
+
+      def bytes
+        wait
+        @bytes || File.binread(@disk_path || @source_path)
+      end
+
+      def wait
+        return self if ready?
+        raise error if failed?
+
+        task = start_generation
+        task ? wait_for_task(task) : generate_now_or_queued
+        raise error if failed?
+
+        self
+      end
+
+      def ready?
+        @state == :ready
+      end
+
+      def pending?
+        @state == :pending
+      end
+
+      def running?
+        @state == :running
+      end
+
+      def failed?
+        @state == :failed
+      end
+
+      def static?
+        @generator.nil? && @writer.nil?
+      end
+
+      def generated?
+        !static?
+      end
+
+      def write_to(path, &block)
+        path = path.to_s
+
+        return skip_existing(path) if File.file?(path)
+
+        task = start_write(path, &block)
+        task ? wait_for_task(task) : write_now_or_queued(path, &block)
+        raise error if failed?
+
+        :written
+      end
+
+      private
+
+      def start_generation
+        @mutex.synchronize do
+          return @task if @task
+          return nil if ready?
+
+          task = current_async_task
+          return nil unless task
+
+          @state = :running
+          @task = queued_task(task) { generate_now }
+        end
+      end
+
+      def start_write(path, &block)
+        @mutex.synchronize do
+          return @task if @task
+          return nil if ready? && materialized_for?(path)
+
+          task = current_async_task
+          return nil unless task
+
+          @state = :running
+          @task = queued_task(task) { write_now(path, &block) }
+        end
+      end
+
+      def wait_for_task(task)
+        task.wait
+      rescue => e
+        fail_with(e)
+        raise
+      end
+
+      def generate_now
+        return self if ready?
+
+        @mutex.synchronize do
+          return self if ready?
+
+          @state = :running
+        end
+        @bytes = generate_bytes
+        @mutex.synchronize do
+          @state = :ready
+          @task = nil
+        end
+        self
+      rescue => e
+        fail_with(e)
+        raise
+      end
+
+      def write_now(path, &block)
+        return skip_existing(path) if File.file?(path)
+        return mark_disk_ready(path) if ready? && materialized_for?(path)
+
+        temp_path = "#{path}.tmp.#{$$}.#{object_id}"
+        FileUtils.mkdir_p(File.dirname(path))
+        block&.call(generated? ? :generate_start : :write_start, self, path)
+
+        write_bytes_to(temp_path)
+
+        File.rename(temp_path, path)
+        mark_disk_ready(path)
+      rescue => e
+        FileUtils.rm_f(temp_path) if temp_path
+        fail_with(e)
+        raise
+      end
+
+      def fail_with(error)
+        @mutex.synchronize do
+          @error ||= error
+          @state = :failed
+          @task = nil
+        end
+      end
+
+      def skip_existing(path)
+        @mutex.synchronize do
+          @disk_path = path
+          @state = :ready
+          @task = nil
+        end
+        :skipped
+      end
+
+      def mark_disk_ready(path)
+        @mutex.synchronize do
+          @disk_path = path
+          @state = :ready
+          @task = nil
+        end
+        :written
+      end
+
+      def materialized_for?(path)
+        @disk_path == path
+      end
+
+      def current_async_task
+        Async::Task.current
+      rescue RuntimeError
+        nil
+      end
+
+      def queued_task(task, &block)
+        return @queue.run(kind: queue_kind, &block) if @queue
+
+        task.async(&block)
+      end
+
+      def generate_now_or_queued
+        return @queue.run(kind: queue_kind) { generate_now } if @queue
+
+        generate_now
+      end
+
+      def write_now_or_queued(path, &block)
+        return @queue.run(kind: queue_kind) { write_now(path, &block) } if @queue
+
+        write_now(path, &block)
+      end
+
+      def write_bytes_to(path)
+        return FileUtils.copy_file(@source_path, path) if static? && @bytes.nil? && @source_path
+
+        File.open(path, "wb") do |file|
+          if @writer
+            @writer.call(file)
+          else
+            file.write(@bytes || generate_bytes)
+          end
+        end
+      end
+
+      def generate_bytes
+        return @generator.call if @generator
+        return File.binread(@source_path) unless @writer
+
+        io = StringIO.new("".b)
+        @writer.call(io)
+        io.string
+      end
+    end
+  end
+end

data/lib/klenod/build/asset_compression.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "brotli"
+require "fileutils"
+
+module Klenod
+  module Build
+    module AssetCompression
+      TEXT_CONTENT_TYPES = [
+        "application/javascript",
+        "application/json",
+        "application/manifest+json",
+        "application/rss+xml",
+        "application/xml",
+        "image/svg+xml"
+      ].freeze
+
+      def self.compressible?(asset)
+        content_type = asset.content_type.to_s.split(";", 2).first
+        content_type.start_with?("text/") || TEXT_CONTENT_TYPES.include?(content_type)
+      end
+
+      def self.sidecar_path(path)
+        "#{path}.br"
+      end
+
+      def self.write_sidecar(asset, path)
+        return nil unless compressible?(asset)
+
+        brotli_path = sidecar_path(path)
+        return :skipped if File.file?(brotli_path)
+
+        bytes = asset.bytes
+        compressed = Brotli.deflate(bytes, quality: 11, mode: :text)
+        return nil unless compressed.bytesize < bytes.bytesize
+
+        write_atomic(brotli_path, compressed)
+        :written
+      end
+
+      def self.remove_sidecar(path)
+        brotli_path = sidecar_path(path)
+        FileUtils.rm_f(brotli_path)
+        brotli_path
+      end
+
+      def self.write_atomic(path, bytes)
+        temp_path = "#{path}.tmp.#{$$}.#{object_id}"
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(temp_path, bytes)
+        File.rename(temp_path, path)
+      rescue
+        FileUtils.rm_f(temp_path) if temp_path
+        raise
+      end
+    end
+  end
+end

data/lib/klenod/build/asset_generation_queue.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+require "etc"
+
+module Klenod
+  module Build
+    class AssetGenerationQueue
+      DEFAULT_CONCURRENCY = [Etc.nprocessors / 2, 2].max
+      DEFAULT_DOWNLOAD_CONCURRENCY = 4
+
+      attr_reader :concurrency, :download_concurrency
+
+      def initialize(concurrency: DEFAULT_CONCURRENCY, download_concurrency: DEFAULT_DOWNLOAD_CONCURRENCY)
+        @concurrency = Integer(concurrency)
+        @download_concurrency = Integer(download_concurrency)
+        raise ArgumentError, "concurrency must be positive" unless @concurrency.positive?
+        raise ArgumentError, "download_concurrency must be positive" unless @download_concurrency.positive?
+
+        @semaphores = {
+          cpu: Async::Semaphore.new(@concurrency),
+          io: Async::Semaphore.new(@download_concurrency)
+        }
+      end
+
+      def run(kind: :cpu, &block)
+        semaphore = semaphore_for(kind)
+        task = current_async_task
+        return semaphore.acquire { block.call } unless task
+
+        semaphore.async(parent: task) { block.call }
+      end
+
+      private
+
+      def semaphore_for(kind)
+        @semaphores.fetch(kind) do
+          raise ArgumentError, "unknown asset generation queue kind: #{kind.inspect}"
+        end
+      end
+
+      def current_async_task
+        Async::Task.current
+      rescue RuntimeError
+        nil
+      end
+    end
+  end
+end

data/lib/klenod/build/cli/application.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+begin
+  previous_verbose = $VERBOSE
+  $VERBOSE = nil
+  require "samovar"
+ensure
+  $VERBOSE = previous_verbose
+end
+
+require_relative "../context"
+require_relative "../graphviz"
+require_relative "../version"
+
+module Klenod
+  module Build
+    module CLI
+      class Build < Samovar::Command
+        self.description = "Build a Klenod runtime bundle."
+
+        options do
+          option "--executable", "Write a Ruby executable bundle that loads all entrypoints."
+        end
+
+        def call
+          config_path = Klenod::Build::ConfigLoader.find
+          raise Samovar::InvalidInputError.new(self, ["Could not find klenod.config.rb"]) unless config_path
+
+          config = nil
+          Dir.chdir(File.dirname(config_path)) do
+            config = Klenod::Build::ConfigLoader.load(config_path)
+          end
+          entrypoints = config.entrypoints
+          raise Samovar::MissingValueError.new(self, :entry) if entrypoints.empty?
+
+          output = config.output_path
+          assets_dir = config.assets_path
+
+          bundle = nil
+          Dir.chdir(config.base_dir) do
+            context = config.context(mode: :build)
+            bundle =
+              if @options[:executable]
+                context.build_executable(entrypoints: entrypoints, output: output, assets_dir: assets_dir)
+              else
+                context.build(entrypoints: entrypoints, output: output, assets_dir: assets_dir)
+              end
+          end
+
+          self.output.puts "Built #{build_kind} #{output}"
+          self.output.puts "Source root: #{bundle.source_root}"
+          self.output.puts "Entrypoints: #{bundle.entrypoints.keys.join(", ")}"
+          self.output.puts "Assets: #{bundle.assets.length}"
+          self.output.puts "Assets directory: #{assets_dir}" if assets_dir
+
+          bundle
+        end
+
+        private
+
+        def build_kind
+          @options[:executable] ? "executable bundle" : "runtime bundle"
+        end
+      end
+
+      class Graph < Samovar::Command
+        self.description = "Export a Klenod runtime bundle as Graphviz DOT."
+
+        options do
+          option "--no-assets", "Hide generated asset nodes and edges."
+        end
+
+        one :bundle_path, "Path to a Klenod runtime bundle.", required: true
+
+        def call
+          bundle = Klenod::Runtime.load_bundle(@bundle_path)
+          dot = Klenod::Build::Graphviz.call(bundle, include_assets: !@options[:no_assets])
+          output.write(dot)
+          dot
+        end
+      end
+
+      class Application < Samovar::Command
+        self.description = "Build and develop Klenod applications."
+
+        options do
+          option "-h/--help", "Print this help."
+          option "-v/--version", "Print the Klenod version."
+        end
+
+        nested :command, {
+          "build" => Build,
+          "graph" => Graph
+        }
+
+        def call
+          if @options[:version]
+            output.puts Klenod::Build::VERSION
+          elsif @options[:help] || !@command
+            print_usage
+          else
+            @command.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klenod/build/cli.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cli/application"

data/lib/klenod/build/config.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Build
+    Config =
+      Data.define(:source_dir, :entrypoints, :output, :assets_dir, :plugins, :mode, :base_dir) do
+        def initialize(source_dir: "src", entrypoints: [], output: "dist/klenod.bundle", assets_dir: nil, plugins: Context::DEFAULT_PLUGINS, mode: :development, base_dir: Dir.pwd)
+          super(
+            source_dir: source_dir,
+            entrypoints: Array(entrypoints),
+            output: output,
+            assets_dir: assets_dir,
+            plugins: plugins,
+            mode: mode,
+            base_dir: base_dir
+          )
+        end
+
+        def with(**attributes)
+          self.class.new(**to_h.merge(attributes))
+        end
+
+        def context(**overrides)
+          Context.new(
+            source_dir: source_path,
+            plugins: plugins,
+            mode: mode,
+            **overrides
+          )
+        end
+
+        def source_path
+          expand_path(source_dir)
+        end
+
+        def output_path
+          expand_path(output)
+        end
+
+        def assets_path
+          assets_dir && expand_path(assets_dir)
+        end
+
+        private
+
+        def expand_path(path)
+          path = path.to_s
+          return File.expand_path(path) if path.start_with?("/")
+
+          File.expand_path(path, base_dir)
+        end
+      end
+
+    class ConfigBuilder
+      def initialize(base_dir: Dir.pwd)
+        @source_dir = "src"
+        @entrypoints = []
+        @output = "dist/klenod.bundle"
+        @assets_dir = nil
+        @plugins = Context::DEFAULT_PLUGINS
+        @mode = :development
+        @base_dir = base_dir
+      end
+
+      def source_dir(value = nil)
+        return @source_dir unless value
+
+        @source_dir = value
+      end
+
+      def entrypoint(value)
+        @entrypoints << value
+      end
+
+      def entrypoints(*values)
+        @entrypoints.concat(values.flatten)
+      end
+
+      def output(value = nil)
+        return @output unless value
+
+        @output = value
+      end
+
+      def assets_dir(value = nil)
+        return @assets_dir unless value
+
+        @assets_dir = value
+      end
+
+      def plugins(value = nil, &block)
+        return @plugins unless value || block
+
+        @plugins = block ? block.call : value
+      end
+
+      def mode(value = nil)
+        return @mode unless value
+
+        @mode = value
+      end
+
+      def config
+        Config.new(
+          source_dir: @source_dir,
+          entrypoints: @entrypoints,
+          output: @output,
+          assets_dir: @assets_dir,
+          plugins: @plugins,
+          mode: @mode,
+          base_dir: @base_dir
+        )
+      end
+    end
+
+    module ConfigLoader
+      CONFIG_FILE = "klenod.config.rb"
+
+      module_function
+
+      def find(start_dir = Dir.pwd)
+        dir = File.expand_path(start_dir)
+
+        loop do
+          path = File.join(dir, CONFIG_FILE)
+          return path if File.file?(path)
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      def load(path)
+        builder = ConfigBuilder.new(base_dir: File.dirname(File.expand_path(path)))
+        builder.instance_eval(File.read(path), path, 1)
+        builder.config
+      end
+    end
+  end
+end