klenod-build 0.0.13 → 0.0.15

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

@@ -163,7 +163,9 @@ module Klenod
             return nil unless google_fonts_module?(module_id)
 
             url = google_fonts_url_for(module_id)
-            css = fetch_css(url)
+            css = context.analysis? ? cached_css(url) : fetch_css(url)
+            return analysis_load(module_id, url, context) unless css
+
             font_faces = FontFaceParser.new(css).font_faces_by_url
             font_assets = {}
             rewritten_css =
@@ -220,6 +222,22 @@ module Klenod
             raise Error, "Could not download Google Fonts asset #{url.inspect}: #{error.message}"
           end
 
+          # Analysis never touches the network: a warm cache is used as is,
+          # and a cold one yields an empty stylesheet that keeps importers
+          # transforming.
+          def cached_css(url)
+            return nil unless @css_cache && !@refresh_cache
+
+            @css_cache.read(url)
+          end
+
+          def analysis_load(module_id, url, context)
+            css_asset = css_asset(module_id, url, "", [])
+            css_asset.url = context.asset_url(css_asset.output_path)
+            @assets_by_module_id[module_id] = [css_asset]
+            ruby_module_source(css_asset.url)
+          end
+
           def fetch_css(url)
             if @css_cache && !@refresh_cache
               css = @css_cache.read(url)

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/haml_plugin/transformer.rb

@@ -136,6 +136,8 @@ module Klenod
             end
           rescue RubyParseError => error
             raise ParseError.new(error, source: source, module_id: module_id)
+          rescue RubyImportRewriter::ParseError => error
+            raise ParseError.new(RubyParseError.new(error.message, line: error.line), source: source, module_id: module_id)
           ensure
             @profiler = previous_profiler
             @module_id = previous_module_id

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

@@ -78,6 +78,10 @@ module Klenod
             @transformer = Transformer.new
           end
 
+          # The validated `variables` mapping, so tooling such as the language
+          # server can tell whether `$name` reads a framework prop.
+          attr_reader :variables
+
           def resolve(dependency, _context)
             styles_dependency = resolve_class_names_runtime(dependency)
             return styles_dependency if styles_dependency

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"
@@ -50,12 +91,14 @@ module Klenod
             return nil unless EXTENSIONS.include?(module_id.extname)
 
             source_path = context.absolute_path(module_id)
+            return analysis_load(module_id, source_path, context) if context.analysis?
+
             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 +144,52 @@ 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
+
+          # Analysis keeps the module shape (dimensions, content type, a
+          # single asset reference) without hashing the file, decoding it, or
+          # describing variants nobody will generate.
+          def analysis_load(module_id, source_path, context)
+            source_hash = Hashing.file_key(source_path)
+            dimensions = image_dimensions(source_path, module_id)
+            asset = static_image_asset(module_id, source_path, source_hash, dimensions)
+            asset.url = context.asset_url(asset.output_path)
+            image_runtime_dependency = image_runtime_dependency_for(module_id)
+            transform =
+              TransformResult.new(
+                image_module_source(module_id, [asset], image_runtime_dependency, context, placeholder: nil),
+                [image_runtime_dependency],
+                nil,
+                [asset],
+                [],
+                {}
+              )
+
+            LoadResult.new(image_source(module_id), source_hash, transform)
+          end
+
+          def image_runtime_dependency_for(module_id)
+            Dependency
+              .create(
+                specifier: IMAGE_RUNTIME_SPECIFIER,
+                importer_id: module_id,
+                kind: :image_runtime
+              )
+              .with(id: "#{module_id}:image_runtime")
           end
 
           def default_image_asset(module_id, source_path, source_hash, dimensions, image_options, queue)
@@ -165,11 +249,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 +346,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 +477,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 +497,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,9 +14,24 @@ 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/
 
+          CachedTranslations = Data.define(:mtime, :size, :translations)
+
+          def initialize
+            @cache = {}
+          end
+
           def translations_for(context, module_id)
             base = module_id.path.delete_suffix(module_id.extname)
             pattern = context.absolute_path(ModuleId.new("#{base}.intl.*.toml", nil)).to_s
@@ -24,8 +41,47 @@ 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
+
+          # Changed or removed companions leave the cache immediately, so it
+          # only ever holds live files. Nothing else needs invalidating: the
+          # owning Haml module is re-transformed by HamlPlugin's own hook.
+          def invalidate_module_ids(paths, _context)
+            paths.each { |path| @cache.delete(File.expand_path(path)) }
+            []
+          end
+
+          private
+
+          # Parsed translations are kept per file and validated by stat, so a
+          # module that transforms often, as in the language server, does not
+          # re-read and re-parse companions that did not change. 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)
+            stat = File.stat(path)
+            cached = @cache[path]
+            return cached.translations if cached && cached.mtime == stat.mtime && cached.size == stat.size
+
+            source = File.read(path)
+            translations =
+              begin
+                TomlRB.parse(source)
+              rescue TomlRB::Error => error
+                raise ParseError.new(error, source: source, module_id: companion_id(path, module_id))
               end
+
+            @cache[path] = CachedTranslations.new(stat.mtime, stat.size, translations)
+            translations
+          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

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/static_asset_plugin.rb

@@ -2,6 +2,7 @@
 
 require_relative "../asset"
 require_relative "../hashing"
+require_relative "../load_result"
 require_relative "../plugin"
 require_relative "../transform_result"
 
@@ -21,6 +22,13 @@ module Klenod
             ".woff2" => "font/woff2"
           }.freeze
 
+          # Analysis never needs the bytes of a font, so the file is not read.
+          def load(module_id, context)
+            return nil unless context.analysis? && CONTENT_TYPES.key?(module_id.extname)
+
+            LoadResult.new("", Hashing.short(module_id.to_s), TransformResult.new("Default = nil\n", [], nil, [], [], {}))
+          end
+
           def transform(module_id, code, context)
             return super unless CONTENT_TYPES.key?(module_id.extname)