klenod-build 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b99708644a67ef46ca03814e2ea175347cfdea450ac8ac33d53e8a7b0c9a9f4
-  data.tar.gz: f7b5935d6d9ddcbd442dfdb95873c5e23fe3ed5c28ab891c4c5996b26ce8b9f0
+  metadata.gz: af646580bbf44262cf5f2262b5fd81eb7a77eeb94498d7ae00e44383cc26ce42
+  data.tar.gz: 6c84bd8dcc4d42be762dabd59bcb918d3aa42418772bd54f68b55e5cd0f3d17d
 SHA512:
-  metadata.gz: 1cf296164f848ae53f748d9dff80dffcccaae0abcbad3eee0b0071366042ae5ad3c66069526baadb02ec34154b90453c0cf464998613fd286293f7b896b88108
-  data.tar.gz: 726527a490d7dc39cd1eb13515f80351dcdbfcf1735519131a52c74ac046b041580dcf131090e3484a17d98c385dc750ab721a3688b5f54ae8c98f9b10610bd8
+  metadata.gz: ce727e4c814158c472b04f3fed395faa53c812d9b6b397ea7bdf57f7c30305459fb057631021cdaf83979860f252d91f7c3d86ac2fde9518d92f983c284cb900
+  data.tar.gz: 72bc4a860585664b9b9c210d89676c50feb0a594d10120d788516ef7cea0c735e983e25145aa89f022b42d6fee0df8064f6f69ac15b45e8c86bd78b55464f389

data/lib/klenod/build/graph/invalidator.rb

@@ -28,6 +28,7 @@ module Klenod
             mods.delete(module_id)
           end
 
+          failed_reload_ids = []
           reloaded_module_ids =
             reload_module_ids.filter_map do |module_id|
               if evaluated_module_ids.include?(module_id)
@@ -36,12 +37,15 @@ module Klenod
                 graph.collect_module(module_id, force: true)
               end
               module_id
-            rescue => e
+            rescue StandardError, ScriptError => e
+              # ScriptError too: a syntax error in a module is not a
+              # StandardError, and letting it escape here kills the watcher
+              # thread rather than reporting the module that failed.
               mark_module_failed(module_id, e)
-              errors << [module_id, e]
+              failed_reload_ids << module_id
+              record_error(errors, module_id, e)
               nil
             end
-          failed_reload_ids = errors.map(&:first) & reload_module_ids
           blocked_dependent_ids = dependent_closure(failed_reload_ids)
           blocked_dependent_ids.each { |module_id| mods.delete(module_id) }
 
@@ -58,8 +62,8 @@ module Klenod
                 graph.collect_module(module_id, force: true)
                 nil
               end
-            rescue => e
-              errors << [module_id, e]
+            rescue StandardError, ScriptError => e
+              record_error(errors, module_id, e)
               nil
             end
           asset_updates = diff_assets(previous_assets, graph.assets)
@@ -80,6 +84,16 @@ module Klenod
 
         private
 
+        # One failure, reported once. A module whose dependency already failed
+        # in this invalidation re-raises that same error when it reloads, so a
+        # broken companion would otherwise be reported once for itself and
+        # again for every module that imports it.
+        def record_error(errors, module_id, error)
+          return if errors.any? { |(_id, recorded)| recorded.equal?(error) }
+
+          errors << [module_id, error]
+        end
+
         attr_reader :graph, :resolver, :source_loader
 
         def records

data/lib/klenod/build/graph.rb

@@ -7,6 +7,7 @@ require "klenod/runtime/mod"
 require "klenod/runtime/bundle"
 require_relative "asset_generation_queue"
 require_relative "errors"
+require_relative "source_error"
 require_relative "graph/invalidator"
 require_relative "hashing"
 require_relative "invalidation_result"
@@ -24,9 +25,12 @@ module Klenod
       include TSort
 
       AsyncResult = Data.define(:value, :error) do
+        # ScriptError too, so a syntax error in a module comes back to the
+        # parent graph path instead of surfacing as an unhandled Async::Task
+        # exception.
         def self.capture
           new(yield, nil)
-        rescue => e
+        rescue StandardError, ScriptError => e
           new(nil, e)
         end
 
@@ -281,8 +285,9 @@ module Klenod
           dependency_records = load_eager_dependency_records(resolved_dependencies)
           transform = finalize_transform_result(module_id, transform, resolved_dependencies, dependency_records)
           assert_supported_transform!(module_id, source, transform)
+          assert_generated_ruby_parses!(module_id, transform)
           transformed_hash = Hashing.hexdigest(transform.code)
-          mod = instantiate_module(module_id, transform, resolved_dependencies, dependency_records, cached)
+          mod = instantiate_module(module_id, transform, resolved_dependencies, dependency_records, cached, source)
           record = build_module_record(module_id, source, source_hash, transformed_hash, transform, resolved_dependencies, mod)
 
           @records[module_id] = record
@@ -336,6 +341,7 @@ module Klenod
           dependency_records = collect_eager_dependency_records(resolved_dependencies)
           transform = finalize_transform_result(module_id, transform, resolved_dependencies, dependency_records)
           assert_supported_transform!(module_id, source, transform)
+          assert_generated_ruby_parses!(module_id, transform)
           transformed_hash = Hashing.hexdigest(transform.code)
           record = build_module_record(module_id, source, source_hash, transformed_hash, transform, resolved_dependencies, cached)
 
@@ -347,22 +353,31 @@ module Klenod
       end
 
       def evaluate_module(module_id)
-        return @mods.fetch(module_id) if @mods.key?(module_id)
+        if @mods.key?(module_id)
+          mod = @mods.fetch(module_id)
+          # A failed reload is remembered so later demand raises the stored
+          # error rather than serving stale exports.
+          raise mod.error if mod.is_a?(FailedModule)
+
+          return mod
+        end
 
         record = @records.fetch(module_id) { collect_module(module_id) }
         raise_failed_module!(record)
         evaluate_eager_dependencies(record.resolved_dependencies)
         dependency_records = dependency_records_for(eager_dependencies(record.resolved_dependencies))
         mod =
-          Runtime::Mod.new(
-            module_id.to_s,
-            record.transformed_source,
-            imports: imports_for(record.resolved_dependencies, dependency_records),
-            source_map: record.source_map,
-            version: record.version,
-            eval_path: eval_path_for(module_id),
-            namespace: namespace
-          )
+          evaluating(module_id, record.transformed_source, record.source) do
+            Runtime::Mod.new(
+              module_id.to_s,
+              record.transformed_source,
+              imports: imports_for(record.resolved_dependencies, dependency_records),
+              source_map: record.source_map,
+              version: record.version,
+              eval_path: eval_path_for(module_id),
+              namespace: namespace
+            )
+          end
 
         @mods[module_id] = mod
       end
@@ -532,20 +547,50 @@ module Klenod
         raise UnsupportedFileError, "No plugin transformed #{module_id.path.inspect}. Add a plugin for #{module_id.extname.inspect} files."
       end
 
+      # A plugin that generates Ruby can generate Ruby that does not parse.
+      # Without this the failure waits until the module is evaluated, and a
+      # production build never evaluates application modules, so the bundle
+      # would ship broken. Ruby modules are already checked by RubyPlugin
+      # against their original source, which reports better locations.
+      def assert_generated_ruby_parses!(module_id, transform)
+        return if ruby_module_extension?(module_id.extname)
+        return if Prism.parse_success?(transform.code)
+
+        raise GeneratedRubyError.new(Prism.parse(transform.code), source: transform.code, module_id: module_id)
+      end
+
       def ruby_module_extension?(extname)
         extname.empty? || extname == ".rb"
       end
 
-      def instantiate_module(module_id, transform, resolved_dependencies, dependency_records, cached)
-        Runtime::Mod.new(
-          module_id.to_s,
-          transform.code,
-          imports: imports_for(resolved_dependencies, dependency_records),
-          source_map: transform.source_map,
-          version: cached ? cached.version + 1 : 0,
-          eval_path: eval_path_for(module_id),
-          namespace: namespace
-        )
+      def instantiate_module(module_id, transform, resolved_dependencies, dependency_records, cached, source)
+        evaluating(module_id, transform.code, source) do
+          Runtime::Mod.new(
+            module_id.to_s,
+            transform.code,
+            imports: imports_for(resolved_dependencies, dependency_records),
+            source_map: transform.source_map,
+            version: cached ? cached.version + 1 : 0,
+            eval_path: eval_path_for(module_id),
+            namespace: namespace
+          )
+        end
+      end
+
+      # Evaluating a module runs its Ruby, and a syntax error there is a
+      # ScriptError that escapes every `rescue => e` in the build. Only a syntax
+      # error is wrapped: a LoadError from the module's own `require` is also a
+      # ScriptError, and reporting that as a syntax error would be wrong.
+      #
+      # The reported line refers to the evaluated source, so the excerpt has to
+      # come from that -- except for a Ruby module, whose transform only
+      # rewrites import calls in place and leaves every line where it was. There
+      # the original source reads better.
+      def evaluating(module_id, evaluated_source, original_source)
+        yield
+      rescue ::SyntaxError => error
+        excerpt_source = ruby_module_extension?(module_id.extname) ? original_source : evaluated_source
+        raise GeneratedRubyError.new(error, source: excerpt_source || evaluated_source, module_id: module_id)
       end
 
       def eval_path_for(module_id)
@@ -670,7 +715,7 @@ module Klenod
 
         tasks.each_with_object({}) do |(dependency_id, child_task), records|
           records[dependency_id] = AsyncResult.unwrap(child_task.wait)
-        rescue => e
+        rescue StandardError, ScriptError => e
           first_error ||= e
         end.tap do
           raise first_error if first_error

data/lib/klenod/build/invalidation_result.rb

@@ -38,6 +38,23 @@ module Klenod
         :asset_updates,
         :errors
       ) do
+        # An invalidation that blew up before it could inspect any module, so
+        # subscribers still get told about the failure instead of the build
+        # going quiet.
+        def self.failed(error, module_id: nil)
+          new(
+            changed_module_ids: [].freeze,
+            removed_module_ids: [].freeze,
+            reloaded_module_ids: [].freeze,
+            reevaluated_module_ids: [].freeze,
+            added_assets: [].freeze,
+            changed_assets: [].freeze,
+            removed_assets: [].freeze,
+            asset_updates: [].freeze,
+            errors: [[module_id, error]].freeze
+          )
+        end
+
         def asset_changes
           AssetChanges.new(added_assets, changed_assets, removed_assets)
         end

data/lib/klenod/build/plugins/data_plugin.rb

@@ -5,6 +5,7 @@ require "toml-rb"
 require "yaml"
 
 require_relative "../plugin"
+require_relative "../source_error"
 require_relative "../transform_result"
 
 module Klenod
@@ -16,14 +17,24 @@ module Klenod
         end
 
         class Plugin < Klenod::Build::Plugin
+          # A format that cannot fail to parse declares no wrapped errors, and
+          # `rescue *[]` then catches nothing.
+          WRAPPED_ERRORS = [].freeze
+
           def self.extensions(*values)
             const_set(:EXTENSIONS, values.freeze)
           end
 
+          # Names the SourceError to raise and the library exceptions it wraps.
+          def self.parse_error(error_class, *wrapped)
+            const_set(:PARSE_ERROR, error_class)
+            const_set(:WRAPPED_ERRORS, wrapped.freeze)
+          end
+
           def transform(module_id, code, _context)
             return super unless self.class::EXTENSIONS.include?(module_id.extname)
 
-            data = parse(code)
+            data = parse_source(code, module_id)
             TransformResult.new(module_source(data), [], nil, [], [], {data: data})
           end
 
@@ -41,6 +52,15 @@ module Klenod
 
           private
 
+          # Each format's library raises its own exception type. Wrapping them
+          # here keeps every `parse` hook a one-liner and gives all four formats
+          # the same report.
+          def parse_source(code, module_id)
+            parse(code)
+          rescue *self.class::WRAPPED_ERRORS => error
+            raise self.class::PARSE_ERROR.new(error, source: code, module_id: module_id)
+          end
+
           def module_source(data)
             <<~RUBY
               Default = #{data.inspect}
@@ -54,8 +74,32 @@ module Klenod
           Plugin.new(...)
         end
 
+        class ParseError < Klenod::Build::SourceError
+          # "expected ':' after object key, got: '2' at line 3 column 7"
+          LOCATION = /\s+at line \d+ column \d+\z/
+
+          def kind
+            "JSON parse error"
+          end
+
+          private
+
+          def location(error)
+            return nil unless error.line
+
+            # The location is rendered as the title and the caret, so drop the
+            # copy the parser appends to its message.
+            Location.new(
+              line: error.line,
+              column: error.column,
+              detail: error.message.sub(LOCATION, "")
+            )
+          end
+        end
+
         class Plugin < DataPlugin::Plugin
           extensions ".json"
+          parse_error ParseError, JSON::ParserError
 
           private
 
@@ -70,8 +114,32 @@ module Klenod
           Plugin.new(...)
         end
 
+        class ParseError < Klenod::Build::SourceError
+          def kind
+            "YAML parse error"
+          end
+
+          private
+
+          def location(error)
+            # Psych::DisallowedClass and friends carry no location.
+            return nil unless error.is_a?(Psych::SyntaxError)
+
+            # One-based. libyaml points at the construct it was parsing when it
+            # gave up, which is not always the offending line, so `context` is
+            # worth surfacing.
+            Location.new(
+              line: error.line,
+              column: error.column,
+              detail: error.problem,
+              hints: [error.context&.capitalize].compact
+            )
+          end
+        end
+
         class Plugin < DataPlugin::Plugin
           extensions ".yaml", ".yml"
+          parse_error ParseError, Psych::Exception
 
           private
 
@@ -86,8 +154,34 @@ module Klenod
           Plugin.new(...)
         end
 
+        class ParseError < Klenod::Build::SourceError
+          # "Failed to parse input on line 2 at offset 9\ninvalid =\n\n         ^"
+          LOCATION = /\AFailed to parse input on line (?<line>\d+) at offset (?<column>\d+)/
+
+          def kind
+            "TOML parse error"
+          end
+
+          private
+
+          def location(error)
+            found = LOCATION.match(error.message)
+            return nil unless found
+
+            # toml-rb embeds its own caret diagram in the message; we render our
+            # own from the line and column instead.
+            Location.new(
+              line: found[:line].to_i,
+              # citrus reports a zero-based offset into the line.
+              column: found[:column].to_i + 1,
+              detail: "Could not parse TOML"
+            )
+          end
+        end
+
         class Plugin < DataPlugin::Plugin
           extensions ".toml"
+          parse_error ParseError, TomlRB::Error
 
           private
 

data/lib/klenod/build/plugins/haml_plugin/errors.rb

@@ -1,27 +1,34 @@
 # frozen_string_literal: true
 
 require "klenod/runtime/source_map"
+require_relative "../../source_error"
 
 module Klenod
   module Build
     module Plugins
       module HamlPlugin
-        class ParseError < StandardError
-          attr_reader :module_id, :source, :line, :column, :cause
-
-          def initialize(error, source:, module_id:)
-            @cause = error
-            @module_id = module_id
-            @source = source
-            @line = source_line_for(error)
-            @column = nil
-
-            super(message_for(error))
-            set_backtrace(error.backtrace)
+        class ParseError < Klenod::Build::SourceError
+          def kind
+            "Haml parse error"
           end
 
           private
 
+          def location(error)
+            detail, *sections = error.message.split(/\n\n+/)
+
+            Location.new(line: source_line_for(error), detail: detail.to_s, hints: hints_from(sections))
+          end
+
+          # A RubyParseError explains itself in trailing "Errors:"/"Missing:"
+          # sections, each an indented list of what to fix.
+          def hints_from(sections)
+            sections.flat_map do |section|
+              _heading, *lines = section.lines.map(&:chomp)
+              lines.map(&:strip)
+            end
+          end
+
           def source_line_for(error)
             line = error.line if error.respond_to?(:line)
             line ||= full_message_line_for(error)
@@ -40,50 +47,6 @@ module Klenod
           def error_line_zero_based?(error)
             error.respond_to?(:line) && error.line.is_a?(Integer) && !error.is_a?(RubyParseError)
           end
-
-          def message_for(error)
-            location =
-              if module_id && line
-                "#{module_id}:#{line}"
-              elsif module_id
-                module_id.to_s
-              elsif line
-                "line #{line}"
-              end
-
-            title = location ? "#{location}: Haml parse error" : "Haml parse error"
-
-            [
-              title,
-              error.message,
-              source_excerpt
-            ].compact.join("\n\n")
-          end
-
-          def source_excerpt
-            return nil unless line
-
-            lines = source.lines
-            return nil if lines.empty?
-
-            index = line - 1
-            first = [index - 2, 0].max
-            last = [index + 2, lines.length - 1].min
-            width = (last + 1).to_s.length
-            excerpt =
-              (first..last).map do |line_index|
-                marker = (line_index == index) ? ">" : " "
-                number = (line_index + 1).to_s.rjust(width)
-                formatted = "#{marker} #{number} | #{lines.fetch(line_index).chomp}"
-                if marker == ">"
-                  "\e[1;31m#{formatted}\e[0m"
-                else
-                  formatted
-                end
-              end
-
-            "Source:\n#{excerpt.join("\n")}"
-          end
         end
 
         class RubyParseError < StandardError

data/lib/klenod/build/plugins/image_plugin.rb

@@ -10,6 +10,7 @@ require_relative "../dependency"
 require_relative "../hashing"
 require_relative "../load_result"
 require_relative "../plugin"
+require_relative "../source_error"
 require_relative "../transform_result"
 require_relative "asset_javascript_metadata"
 
@@ -21,6 +22,46 @@ module Klenod
           Plugin.new(...)
         end
 
+        # An image that cannot be read. There is no line to point at, so the
+        # report is the file, what went wrong, and -- when the bytes turn out to
+        # be a different format than the extension claims -- what to rename it
+        # to.
+        class DecodeError < Klenod::Build::SourceError
+          # image_size names the format it recognised in its own message, e.g.
+          # "EOF in JPEG".
+          DETECTED_FORMAT = /\b(?<format>JPEG|PNG|GIF|WEBP|AVIF|HEIC|BMP|TIFF|SVG)\b/i
+
+          def initialize(error, module_id:, source: nil)
+            super(error, source: source, module_id: module_id)
+          end
+
+          def kind
+            "Image decode error"
+          end
+
+          private
+
+          def location(error)
+            detail = message_for(error)
+
+            Location.new(detail: detail, hints: [hint_for(detail)])
+          end
+
+          # When the bytes turn out to be a format the extension does not claim,
+          # renaming the file is the fix.
+          def hint_for(detail)
+            extname = module_id.extname.delete_prefix(".").downcase
+            detected = DETECTED_FORMAT.match(detail) { it[:format].downcase }
+
+            if detected && detected != extname && !(detected == "jpeg" && extname == "jpg")
+              basename = File.basename(module_id.path, module_id.extname)
+              "The file contains #{detected.upcase} data. Did you mean #{basename}.#{detected}?"
+            else
+              "The file is not a valid #{extname.upcase} image. It may be truncated or corrupt."
+            end
+          end
+        end
+
         class Plugin < Klenod::Build::Plugin
           EXTENSIONS = [".avif", ".gif", ".jpeg", ".jpg", ".png", ".webp"].freeze
           IMAGE_RUNTIME_SPECIFIER = "virtual:klenod/image"
@@ -51,11 +92,11 @@ module Klenod
 
             source_path = context.absolute_path(module_id)
             source_hash = Hashing.file_hexdigest(source_path)
-            dimensions = image_dimensions(source_path)
+            dimensions = image_dimensions(source_path, module_id)
             image_options = image_options_for(module_id)
             asset = default_image_asset(module_id, source_path, source_hash, dimensions, image_options, context.asset_generation_queue)
             variant_assets = generate_variant_assets(module_id, source_path, source_hash, dimensions, image_options, context.asset_generation_queue)
-            placeholder = image_placeholder(source_path, source_hash)
+            placeholder = image_placeholder(source_path, source_hash, module_id)
             [asset, *variant_assets].each { |image_asset| image_asset.url = context.asset_url(image_asset.output_path) }
             javascript_asset = javascript_image_asset(module_id, asset, variant_assets, context, placeholder:)
             javascript_asset.url = context.asset_url(javascript_asset.output_path)
@@ -101,11 +142,20 @@ module Klenod
 
           Dimensions = Data.define(:width, :height, :format)
 
-          def image_dimensions(path)
+          # A file whose bytes are not an image at all used to pass silently with
+          # nil dimensions, and only failed later -- inside the asset generation
+          # queue -- if a variant happened to be requested.
+          def image_dimensions(path, module_id)
             size = ImageSize.path(path)
+            # A file that is not an image at all reports no format rather than
+            # raising, which used to pass silently with nil dimensions and only
+            # fail later, inside the asset generation queue, if a variant
+            # happened to be requested.
+            raise DecodeError.new("Could not read the image", module_id: module_id) if size.format.nil?
+
             Dimensions.new(size.width, size.height, size.format)
-          rescue ImageSize::FormatError
-            Dimensions.new(nil, nil, nil)
+          rescue ImageSize::FormatError => error
+            raise DecodeError.new(error, module_id: module_id)
           end
 
           def default_image_asset(module_id, source_path, source_hash, dimensions, image_options, queue)
@@ -165,11 +215,11 @@ module Klenod
               source_path,
               content_type(extname),
               metadata,
-              writer: ->(io) { write_image_bytes(source_path, format, quality, io) },
+              writer: ->(io) { write_image_bytes(module_id, source_path, format, quality, io) },
               queue: queue,
               queue_kind: :cpu
             ) do
-              generate_image_bytes(source_path, format, quality:)
+              generate_image_bytes(module_id, source_path, format, quality:)
             end
           end
 
@@ -262,12 +312,12 @@ module Klenod
             RUBY
           end
 
-          def image_placeholder(source_path, source_hash)
+          def image_placeholder(source_path, source_hash, module_id)
             return nil unless @placeholder
 
             key = ImagePlaceholderKey.new(source_path.to_s, source_hash, @placeholder.width, @placeholder.format, @placeholder.quality)
             @placeholder_cache[key] ||= begin
-              bytes = generate_image_bytes(source_path, @placeholder.format, width: @placeholder.width, quality: @placeholder.quality)
+              bytes = generate_image_bytes(module_id, source_path, @placeholder.format, width: @placeholder.width, quality: @placeholder.quality)
               "data:image/#{@placeholder.format};base64,#{Base64.strict_encode64(bytes)}"
             end
           end
@@ -393,16 +443,16 @@ module Klenod
               source_path,
               content_type(extname),
               metadata,
-              writer: ->(io) { write_variant_bytes(source_path, width, format, quality, io) },
+              writer: ->(io) { write_variant_bytes(module_id, source_path, width, format, quality, io) },
               queue: queue,
               queue_kind: :cpu
             ) do
-              generate_image_bytes(source_path, format, width: width, quality:)
+              generate_image_bytes(module_id, source_path, format, width: width, quality:)
             end
           end
 
-          def generate_image_bytes(source_path, format, width: nil, quality: nil)
-            image = Magick::Image.read(source_path.to_s).first
+          def generate_image_bytes(module_id, source_path, format, width: nil, quality: nil)
+            image = read_image(module_id, source_path)
             output_image = width ? image.resize_to_fit(width) : image
             output_image.to_blob do |info|
               info.format = format.upcase
@@ -413,12 +463,24 @@ module Klenod
             image&.destroy!
           end
 
-          def write_variant_bytes(source_path, width, format, quality, io)
-            io.write(generate_image_bytes(source_path, format, width: width, quality:))
+          # ImageMagick raises for a corrupt file and returns nothing at all for
+          # one it cannot identify. Both run inside the asset generation queue,
+          # where an unhandled failure says nothing about which import caused it.
+          def read_image(module_id, source_path)
+            image = Magick::Image.read(source_path.to_s).first
+            return image if image
+
+            raise DecodeError.new("ImageMagick could not identify the image", module_id: module_id)
+          rescue Magick::ImageMagickError => error
+            raise DecodeError.new(error, module_id: module_id)
+          end
+
+          def write_variant_bytes(module_id, source_path, width, format, quality, io)
+            io.write(generate_image_bytes(module_id, source_path, format, width: width, quality:))
           end
 
-          def write_image_bytes(source_path, format, quality, io)
-            io.write(generate_image_bytes(source_path, format, quality:))
+          def write_image_bytes(module_id, source_path, format, quality, io)
+            io.write(generate_image_bytes(module_id, source_path, format, quality:))
           end
 
           def scaled_height(dimensions, width)

data/lib/klenod/build/plugins/intl_plugin.rb

@@ -3,6 +3,8 @@
 require "toml-rb"
 
 require_relative "../plugin"
+require_relative "../source_error"
+require_relative "data_plugin"
 
 module Klenod
   module Build
@@ -12,6 +14,15 @@ module Klenod
           Plugin.new(...)
         end
 
+        # Translations are TOML, so the report is the TOML one. It names the
+        # companion file rather than the component that imports it, because that
+        # is the file the developer has to fix.
+        class ParseError < TomlPlugin::ParseError
+          def kind
+            "Intl parse error"
+          end
+        end
+
         class Plugin < Klenod::Build::Plugin
           INTL_FILE_RE = /\.intl\.(?<locale>[^\/]+)\.toml\z/
 
@@ -24,9 +35,30 @@ module Klenod
               .sort
               .to_h do |path|
                 locale = File.basename(path).match(INTL_FILE_RE)[:locale]
-                [locale, TomlRB.load_file(path)]
+                [locale, translations_from(path, module_id)]
               end
           end
+
+          private
+
+          # Read the file here rather than using TomlRB.load_file, so a parse
+          # failure can carry the source for the excerpt.
+          def translations_from(path, module_id)
+            source = File.read(path)
+
+            begin
+              TomlRB.parse(source)
+            rescue TomlRB::Error => error
+              raise ParseError.new(error, source: source, module_id: companion_id(path, module_id))
+            end
+          end
+
+          # The companion is not a module in the graph, but its id resolves to a
+          # path for display just the same.
+          def companion_id(path, module_id)
+            directory = File.dirname(module_id.path)
+            ModuleId.new(File.join(directory, File.basename(path)), nil)
+          end
         end
       end
     end

data/lib/klenod/build/plugins/markdown_plugin.rb

@@ -7,10 +7,12 @@ require "yaml"
 require_relative "../dependency"
 require_relative "../module_id"
 require_relative "../plugin"
+require_relative "../source_error"
 require_relative "../transform_result"
 require_relative "../watched_pattern"
 require_relative "class_names_runtime"
 require_relative "component_defaults"
+require_relative "data_plugin"
 require_relative "haml_plugin"
 require_relative "markdown_compiler"
 
@@ -22,6 +24,30 @@ module Klenod
           Plugin.new(...)
         end
 
+        # Frontmatter is YAML, so the report is the YAML one, shifted to file
+        # lines. Kramdown does not fail on malformed Markdown -- it collects
+        # warnings -- so frontmatter is the only parse failure a .md file has.
+        class FrontmatterError < YamlPlugin::ParseError
+          def initialize(error, source:, module_id:, line_offset: 0)
+            @line_offset = line_offset
+
+            super(error, source: source, module_id: module_id)
+          end
+
+          def kind
+            "Markdown frontmatter error"
+          end
+
+          private
+
+          def location(error)
+            found = super
+            return found unless found&.line
+
+            found.with(line: found.line + @line_offset)
+          end
+        end
+
         class Plugin < Klenod::Build::Plugin
           include ClassNamesRuntime
 
@@ -49,7 +75,7 @@ module Klenod
           def transform(module_id, code, context)
             return super unless module_id.extname == ".md"
 
-            frontmatter, markdown_source = parse_frontmatter(code)
+            frontmatter, markdown_source = parse_frontmatter(code, module_id)
             builder = HamlPlugin::Transformer::RubyBuilder.new(profiler: context.profiler)
             dependency = markdown_components_dependency(module_id, context)
             class_names_dependency = class_names_runtime_dependency(module_id)
@@ -96,19 +122,31 @@ module Klenod
 
           private
 
-          def parse_frontmatter(source)
+          def parse_frontmatter(source, module_id)
             match = source.match(/\A---[ \t]*\r?\n(?<frontmatter>.*?\r?\n)---[ \t]*(?:\r?\n|\z)/m)
             return [{}, source] unless match
 
-            frontmatter = YAML.safe_load(match[:frontmatter], permitted_classes: [Date, Time, Symbol], aliases: false, symbolize_names: true) || {}
+            frontmatter = load_frontmatter(match[:frontmatter], source, module_id) || {}
 
             unless frontmatter.is_a?(Hash)
-              raise ArgumentError, "Markdown frontmatter must be a mapping"
+              raise FrontmatterError.new(
+                ArgumentError.new("Markdown frontmatter must be a mapping"),
+                source: source,
+                module_id: module_id
+              )
             end
 
             [normalize_frontmatter(frontmatter), source.byteslice(match.end(0)..) || ""]
           end
 
+          # Psych reports lines within the frontmatter slice, which starts after
+          # the opening "---", so shift them to match the file.
+          def load_frontmatter(frontmatter, source, module_id)
+            YAML.safe_load(frontmatter, permitted_classes: [Date, Time, Symbol], aliases: false, symbolize_names: true)
+          rescue Psych::Exception => error
+            raise FrontmatterError.new(error, source: source, module_id: module_id, line_offset: 1)
+          end
+
           def normalize_frontmatter(value)
             case value
             when Hash

data/lib/klenod/build/plugins/ruby_plugin.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+require "prism"
+
 require_relative "../plugin"
 require_relative "../ruby_import_rewriter"
+require_relative "../source_error"
 require_relative "../transform_result"
 
 module Klenod
@@ -12,21 +15,75 @@ module Klenod
           Plugin.new(...)
         end
 
+        class ParseError < Klenod::Build::SourceError
+          def kind
+            "Ruby parse error"
+          end
+
+          private
+
+          def location(error)
+            return prism_location(error) if error.is_a?(Prism::ParseResult)
+            return nil unless error.respond_to?(:lineno)
+
+            Location.new(
+              line: error.lineno,
+              # SyntaxTree reports a zero-based column.
+              column: error.column && error.column + 1,
+              detail: error.message
+            )
+          end
+
+          # Prism reports each failure as data rather than a message to scrape,
+          # and phrases the first as "what is wrong; what was expected".
+          def prism_location(result)
+            first, *rest = result.errors
+            detail, _, expected = first.message.partition("; ")
+
+            Location.new(
+              line: first.location.start_line,
+              column: first.location.start_column + 1,
+              detail: detail,
+              hints: [expected, *rest.map(&:message)].reject(&:empty?).map(&:capitalize)
+            )
+          end
+        end
+
         class Plugin < Klenod::Build::Plugin
           def transform(module_id, code, context)
             return TransformResult.identity(code) unless module_id.extname == ".rb"
 
+            assert_parses!(module_id, code)
+
             result =
-              RubyImportRewriter
-                .new(
-                  module_id: module_id,
-                  kind: :ruby_import,
-                  source_dir: context.source_dir,
-                  profiler: context.profiler
-                )
-                .rewrite(code)
+              begin
+                RubyImportRewriter
+                  .new(
+                    module_id: module_id,
+                    kind: :ruby_import,
+                    source_dir: context.source_dir,
+                    profiler: context.profiler
+                  )
+                  .rewrite(code)
+              rescue SyntaxTree::Parser::ParseError => error
+                raise ParseError.new(error, source: code, module_id: module_id)
+              end
             TransformResult.new(result.code, result.dependencies, nil, [], result.watched_patterns, {})
           end
+
+          private
+
+          # The rewriter only parses a file that contains an import it cannot
+          # rewrite literally, so without this check most syntax errors would
+          # not surface until the module was evaluated -- and a production build
+          # never evaluates application modules, so the bundle would ship
+          # broken. Prism is the parser CRuby itself uses, and validating costs
+          # well under a tenth of a millisecond per file.
+          def assert_parses!(module_id, code)
+            return if Prism.parse_success?(code)
+
+            raise ParseError.new(Prism.parse(code), source: code, module_id: module_id)
+          end
         end
       end
     end

data/lib/klenod/build/plugins/svg_plugin.rb

@@ -6,6 +6,7 @@ require_relative "../errors"
 require_relative "../hashing"
 require_relative "../module_id"
 require_relative "../plugin"
+require_relative "../source_error"
 require_relative "../transform_result"
 require_relative "asset_javascript_metadata"
 
@@ -17,6 +18,23 @@ module Klenod
           Plugin.new(...)
         end
 
+        # SVG markup is scraped with a regex rather than parsed, so malformed
+        # markup is tolerated. A file that is not text at all is not.
+        class EncodingError < Klenod::Build::SourceError
+          def kind
+            "SVG encoding error"
+          end
+
+          private
+
+          def location(error)
+            Location.new(
+              detail: error.message,
+              hints: ["An SVG file must be valid UTF-8 text."]
+            )
+          end
+        end
+
         class Plugin < Klenod::Build::Plugin
           EXTENSIONS = [".svg"].freeze
           SVG_RUNTIME_SPECIFIER = "virtual:klenod/svg"
@@ -39,7 +57,7 @@ module Klenod
 
             raise UnsupportedFileError, "SVG imports do not support query options: #{module_id}" if module_id.query
 
-            dimensions = svg_dimensions(code)
+            dimensions = svg_dimensions(code, module_id)
             hash = Hashing.short(code)
             output_path = "/#{asset_name(module_id)}.#{hash}.svg"
             asset =
@@ -146,8 +164,8 @@ module Klenod
             JAVASCRIPT
           end
 
-          def svg_dimensions(code)
-            attributes = svg_attributes(code)
+          def svg_dimensions(code, module_id)
+            attributes = svg_attributes(code, module_id)
             return Dimensions.new(nil, nil) unless attributes
 
             explicit_width = parse_length(attributes["width"])
@@ -157,13 +175,18 @@ module Klenod
             view_box_dimensions(attributes["viewBox"] || attributes["viewbox"])
           end
 
-          def svg_attributes(code)
+          # Malformed markup is tolerated: no <svg> match just means unknown
+          # dimensions. Only a file that is not text at all fails here, and
+          # String#match raises without saying which file it was reading.
+          def svg_attributes(code, module_id)
             match = code.match(/<svg(?=[\s>])(?<attributes>[^>]*)>/im)
             return nil unless match
 
             match[:attributes].scan(/([:\w.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/).to_h do |name, double_quoted, single_quoted, unquoted|
               [name, double_quoted || single_quoted || unquoted]
             end
+          rescue ArgumentError => error
+            raise EncodingError.new(error, source: "", module_id: module_id)
           end
 
           def view_box_dimensions(view_box)

data/lib/klenod/build/source_error.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "errors"
+require_relative "source_excerpt"
+
+module Klenod
+  module Build
+    # Base class for a build failure attributable to one source file.
+    #
+    # Plugins parse very different formats with very different libraries, but the
+    # report a developer needs is the same every time: which file, which line and
+    # column, what went wrong, and what to try next. A subclass supplies `kind`
+    # and a `location` that unpacks its library's exception. Everything else --
+    # the message layout, the source excerpt, the synthesized backtrace frame --
+    # is shared, so every format renders identically in the terminal and in the
+    # browser error dialog.
+    #
+    # Being a StandardError matters: a bare Ruby SyntaxError is a ScriptError and
+    # escapes every `rescue => e` in the build, taking the watcher thread down
+    # with it.
+    class SourceError < Error
+      # `hints` is free-form advice, one entry per line, e.g.
+      # "Did you mean hero.jpeg?".
+      Location = Data.define(:line, :column, :detail, :hints) do
+        def initialize(line: nil, column: nil, detail: nil, hints: []) = super
+      end
+
+      attr_reader :module_id, :source, :line, :column, :cause, :detail, :hints
+
+      def initialize(error, source:, module_id:)
+        @cause = error
+        @module_id = module_id
+        @source = source
+
+        found = location_for(error)
+        @line = found.line
+        @column = found.column
+        @detail = found.detail || message_for(error)
+        @hints = Array(found.hints).map(&:to_s).reject(&:empty?).freeze
+
+        super(
+          SourceExcerpt.message(
+            module_id:,
+            line: @line,
+            column: @column,
+            kind:,
+            source:,
+            message: @detail,
+            hints: @hints
+          )
+        )
+
+        set_backtrace(backtrace_for(error))
+      end
+
+      # "JavaScript parse error". Used as the label in the browser error dialog,
+      # so it names the format rather than the plugin.
+      def kind
+        "Parse error"
+      end
+
+      private
+
+      # Re-wrapping is idempotent: a plugin that catches its own SourceError to
+      # attach the source keeps the location the first construction worked out.
+      def location_for(error)
+        return location(error) || Location.new unless error.is_a?(SourceError)
+
+        Location.new(line: error.line, column: error.column, detail: error.detail, hints: error.hints)
+      end
+
+      # Subclasses override to pull line, column, detail and hints out of the
+      # exception their parsing library raised. Returning nil keeps the wrapped
+      # message as the detail and renders no excerpt.
+      def location(_error)
+        nil
+      end
+
+      # Prism reports each failure as data rather than a message to scrape, and
+      # phrases the first as "what is wrong; what was expected".
+      def prism_location(result)
+        first, *rest = result.errors
+        detail, _, expected = first.message.partition("; ")
+
+        Location.new(
+          line: first.location.start_line,
+          column: first.location.start_column + 1,
+          detail: detail,
+          hints: [expected, *rest.map(&:message)].reject(&:empty?).map(&:capitalize)
+        )
+      end
+
+      # A native extension can raise with a bare message rather than an
+      # exception, so do not assume #message exists.
+      def message_for(error)
+        error.respond_to?(:message) ? error.message : error.to_s
+      end
+
+      # The browser dialog highlights source lines by matching backtrace frames
+      # against the filename. A native parser, or one that raises while
+      # evaluating generated source, leaves no Ruby frame pointing at the
+      # module, so synthesize one.
+      def backtrace_for(error)
+        frames = error.respond_to?(:backtrace) ? Array(error.backtrace) : []
+        return frames unless line
+
+        ["#{module_id}:#{[line, column].compact.join(":")}", *frames]
+      end
+    end
+
+    # Ruby generated from another format that does not parse.
+    #
+    # This is a bug in the plugin that generated it rather than in anything the
+    # developer wrote, so the excerpt shows the generated source. It is checked
+    # while collecting, and again as a backstop when a module is evaluated: a
+    # bare SyntaxError there is a ScriptError, which escapes every `rescue => e`
+    # in the build and takes the watcher thread down with it.
+    class GeneratedRubyError < SourceError
+      # "app:/x.rb:3: syntax error found"
+      HEADER = /\A(?<file>.+?):(?<line>\d+): (?<detail>.+?)$/
+      # "    | ^~~ unexpected 'end'; expected a `)` to close the arguments"
+      CARET = /^ *\| (?<pad> *)\^+~* *(?<message>.*)$/
+
+      def kind
+        "Generated Ruby syntax error"
+      end
+
+      private
+
+      # Prism renders its own excerpt into the message it puts on a SyntaxError.
+      # We re-render it from the line and column, and keep the explanation it
+      # prints beside the caret.
+      def location(error)
+        return prism_location(error) if error.is_a?(Prism::ParseResult)
+
+        header = HEADER.match(error.message)
+        return nil unless header
+
+        caret = CARET.match(error.message)
+        detail, _, hint = (caret ? caret[:message] : header[:detail]).partition("; ")
+
+        Location.new(
+          line: header[:line].to_i,
+          column: caret && caret[:pad].length + 1,
+          detail: detail,
+          hints: [hint.empty? ? nil : hint.capitalize].compact
+        )
+      end
+    end
+  end
+end

data/lib/klenod/build/source_excerpt.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Build
+    # Shared formatting for build errors that can point at a line of source.
+    #
+    # Plugins raise errors carrying the original source and a location, and the
+    # resulting message is shown both in the terminal and in the browser error
+    # dialog, so it needs to read well as plain text. The browser passes
+    # `ansi: false` to get the same layout without escape codes.
+    module SourceExcerpt
+      MARKED_LINE = "\e[1;31m"
+      RESET = "\e[0m"
+
+      module_function
+
+      # "app:/pages/thing.tsx:33:9: JavaScript parse error"
+      def title(module_id:, line:, kind:, column: nil)
+        location =
+          if module_id && line
+            "#{module_id}:#{[line, column].compact.join(":")}"
+          elsif module_id
+            module_id.to_s
+          elsif line
+            column ? "line #{line} column #{column}" : "line #{line}"
+          end
+
+        location ? "#{location}: #{kind}" : kind
+      end
+
+      def message(module_id:, line:, kind:, source:, message:, column: nil, hints: [], context: 2, ansi: true)
+        [
+          title(module_id:, line:, column:, kind:),
+          message,
+          excerpt(source:, line:, column:, context:, ansi:),
+          hint_section(hints)
+        ].compact.join("\n\n")
+      end
+
+      def excerpt(source:, line:, column: nil, context: 2, ansi: true)
+        return nil unless line
+
+        lines = source.to_s.lines
+        return nil if lines.empty?
+
+        index = line - 1
+        return nil unless index.between?(0, lines.length - 1)
+
+        first = [index - context, 0].max
+        last = [index + context, lines.length - 1].min
+        width = (last + 1).to_s.length
+
+        rows =
+          (first..last).flat_map do |line_index|
+            marked = line_index == index
+            number = (line_index + 1).to_s.rjust(width)
+            formatted = "#{marked ? ">" : " "} #{number} | #{lines.fetch(line_index).chomp}"
+            formatted = "#{MARKED_LINE}#{formatted}#{RESET}" if marked && ansi
+
+            marked ? [formatted, caret_row(width, column)].compact : [formatted]
+          end
+
+        "Source:\n#{rows.join("\n")}"
+      end
+
+      # "    |       ^", aligned under the offending column of the marked line.
+      def caret_row(width, column)
+        return nil unless column&.positive?
+
+        "#{" " * (width + 3)}| #{" " * (column - 1)}^"
+      end
+
+      # What to try next. Rendered like the "Source:" section so the two read as
+      # one report.
+      def hint_section(hints)
+        hints = Array(hints).map(&:to_s).reject(&:empty?)
+        return nil if hints.empty?
+
+        heading = (hints.length == 1) ? "Hint:" : "Hints:"
+        "#{heading}\n#{hints.map { "  #{it}" }.join("\n")}"
+      end
+    end
+  end
+end

data/lib/klenod/build/version.rb

@@ -2,6 +2,6 @@
 
 module Klenod
   module Build
-    VERSION = "0.0.13"
+    VERSION = "0.0.14"
   end
 end

data/lib/klenod/build/watcher.rb

@@ -129,11 +129,20 @@ module Klenod
 
       def emit_update(changed_paths, removed_paths)
         @graph_version += 1
-        result = @context.invalidate_paths(changed_paths, removed_paths: removed_paths)
+        result = invalidate(changed_paths, removed_paths)
 
         @context.emit_update(UpdateEvent.new(changed_paths, removed_paths, @graph_version, result))
       end
 
+      # Invalidation runs on the worker thread, so anything escaping here
+      # would kill it and take hot reloading down for the rest of the
+      # process. Report the failure as a result instead.
+      def invalidate(changed_paths, removed_paths)
+        @context.invalidate_paths(changed_paths, removed_paths: removed_paths)
+      rescue StandardError, ScriptError => e
+        InvalidationResult.failed(e)
+      end
+
       def monotonic_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: klenod-build
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Andrés Alin
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -297,6 +297,8 @@ files:
 - lib/klenod/build/resolution_error_formatter.rb
 - lib/klenod/build/resolver.rb
 - lib/klenod/build/ruby_import_rewriter.rb
+- lib/klenod/build/source_error.rb
+- lib/klenod/build/source_excerpt.rb
 - lib/klenod/build/source_map.rb
 - lib/klenod/build/source_map/editor.rb
 - lib/klenod/build/source_map/map.rb