klenod-build 0.0.25 → 0.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ceb99aac4328e67769eebf0c137e9e2f8412bbfc65c51c0757906f7e5e1ce88f
-  data.tar.gz: 7bd420cb85700ace2a34e6e0460ee5f63f8a9b1530264f8b1f5d4a8f7f4583e3
+  metadata.gz: 2b1c963370596392fc4e48311db021c836c182e27665d8b62652bda1a55744e2
+  data.tar.gz: 454ee9440b137797885ee3b45d5fecc789fb64cc7adcf43e9a61eead08602299
 SHA512:
-  metadata.gz: a8225fdd2f9208f17b2feeb832d03ed7bbb0fd5669bfd875fccdff579d05050a846f229996ccdce028e028d47b48cc70f24355b7a9384409d99c77e31a0a4a62
-  data.tar.gz: 0c5e2b51e492c0a56772ff6a9ed4309924a2da19e3a973c60782b1182605be59cec2cc3b10cc4c20a1641c21ae8102d9d37c3a6b00549fcf0e6a2b6347e84430
+  metadata.gz: fc351535e38a0599165dc4794cecfdc84064b5cf8b0273f7e3f763643a152d43391f413a2ab2d97845f0d3774c41989c925da95c4f2d12e32261569e963ec34c
+  data.tar.gz: 0e8b90fbaef71ccb01e419ac58e4f394cafe69c61d2926bac649802404a075cf89c1ee8df77b9cf9cc4acf6e958b3547bd9e338cc4ef6ba85e4d158d0ef2993d

data/lib/klenod/build/exception_formatter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "klenod/runtime/backtrace_rewriter"
+
+require_relative "source_excerpt"
+
+module Klenod
+  module Build
+    # A runtime exception as a development report, in the same shape as a
+    # SourceError: the class and message, an excerpt of the first frame that
+    # has source, then the frames.
+    #
+    #   × NameError: undefined local variable or method 'x'
+    #
+    #       ╭─[app:/routes/page.haml:4]
+    #     3 │ %h1 Hello
+    #   > 4 │ %p= x
+    #       ╰────
+    #     at app:/routes/page.haml:4:in 'render'
+    #     at /gems/rack/lib/rack.rb:12:in 'call'
+    #
+    # Rewriting lives in Klenod::Runtime::BacktraceRewriter, so a production
+    # application keeps corrected backtraces without loading any of this.
+    module ExceptionFormatter
+      Entry = Runtime::BacktraceRewriter::ParsedBacktraceEntry
+
+      module_function
+
+      # `mods` maps module IDs to evaluated modules, as Graph#mods does. The
+      # error is rewritten in place.
+      def format(error, mods: {}, ansi: true, links: ansi && SourceExcerpt.hyperlinks?)
+        rewriter = Runtime::BacktraceRewriter.new(mods)
+        rewriter.rewrite_exception(error)
+        module_ids = mods.values.select { it.respond_to?(:eval_path) }.to_h { [it.eval_path.to_s, it.path.to_s] }
+        frames = Array(error.backtrace).map { Entry.parse(it) || it.to_s }
+
+        [
+          SourceExcerpt.header(error.class.name, error.message, ansi:),
+          [
+            excerpt(frames, rewriter, module_ids, ansi:, links:),
+            *frames.map { "  #{frame(it, module_ids, ansi:, links:)}" }
+          ].compact.join("\n")
+        ].reject(&:empty?).join("\n\n")
+      end
+
+      # The first frame the rewriter has original source for, boxed.
+      def excerpt(frames, rewriter, module_ids, ansi:, links:)
+        frames.grep(Entry).each do |entry|
+          source = rewriter.source_for(entry.file)
+          next unless source
+
+          location = location(entry, module_ids, ansi:, links:)
+          excerpt = SourceExcerpt.excerpt(source:, line: entry.line, ansi:, location:)
+          return excerpt if excerpt
+        end
+
+        nil
+      end
+
+      # "at app:/routes/page.haml:4:in 'render'". Frames outside the graph are
+      # dimmed so the application's own frames stand out.
+      def frame(entry, module_ids, ansi:, links:)
+        return SourceExcerpt.dim("at #{entry}", ansi:) unless entry.is_a?(Entry) && module_ids.key?(entry.file)
+
+        "#{SourceExcerpt.dim("at", ansi:)} #{location(entry, module_ids, ansi:, links:)}#{SourceExcerpt.dim(":in '#{entry.description}'", ansi:)}"
+      end
+
+      # Graph modules are named by module ID and linked to the file they were
+      # evaluated from.
+      def location(entry, module_ids, ansi:, links:)
+        SourceExcerpt.styled_location(
+          module_id: module_ids.fetch(entry.file, entry.file),
+          line: entry.line,
+          path: entry.file,
+          ansi:,
+          links:
+        )
+      end
+    end
+  end
+end

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

@@ -16,7 +16,8 @@ module Klenod
           evaluated_module_ids = mods.keys
           changed_module_ids = module_ids_for_paths(changed_paths)
           removed_module_ids = module_ids_for_paths(removed_paths)
-          failed_retry_ids = failed_module_ids_for_created_paths(changed_paths)
+          failed_retry_ids = failed_module_ids - removed_module_ids
+          imported_module_ids = records.each_key.select { |module_id| graph.dependents(module_id).any? }
           pattern_owner_ids = module_ids_for_watched_paths(changed_paths + removed_paths)
           plugin_owner_ids = plugin_invalidated_module_ids(changed_paths + removed_paths)
           reload_module_ids = (changed_module_ids + failed_retry_ids + pattern_owner_ids + plugin_owner_ids).uniq
@@ -31,6 +32,12 @@ module Klenod
           failed_reload_ids = []
           reloaded_module_ids =
             reload_module_ids.filter_map do |module_id|
+              if orphaned_failure?(module_id, imported_module_ids)
+                graph.remove_record(module_id)
+                mods.delete(module_id)
+                next
+              end
+
               if evaluated_module_ids.include?(module_id)
                 graph.load_module(module_id, force: true)
               else
@@ -124,28 +131,22 @@ module Klenod
           end
         end
 
-        def failed_module_ids_for_created_paths(paths)
-          relative_paths = relative_paths_for(paths)
-          return [] if relative_paths.empty?
-
-          records.filter_map do |module_id, record|
-            next unless record.status == :failed
-
-            unresolved_path = record.metadata.fetch(:error).unresolved_path if record.metadata.fetch(:error).respond_to?(:unresolved_path)
-            module_id if unresolved_path && relative_paths.any? { |path| path_satisfies_unresolved_path?(path, unresolved_path) }
-          end
-        end
-
-        def relative_paths_for(paths)
-          paths.filter_map do |path|
-            Pathname.new(path).expand_path.relative_path_from(resolver.source_dir).to_s
-          rescue ArgumentError
-            nil
-          end
+        # A failed record keeps no dependency links, so nothing ties it to the file
+        # that broke it: a missing import, or a new dependency that fails to parse.
+        # Retry every failed module on each change. Failures are rare, and a retry
+        # that fails again reports its error again.
+        def failed_module_ids
+          records.filter_map { |module_id, record| module_id if record.status == :failed }
         end
 
-        def path_satisfies_unresolved_path?(path, unresolved_path)
-          path == unresolved_path || path.start_with?("#{unresolved_path}.")
+        # A failed module whose last importer dropped it earlier in this update.
+        # Nothing can demand it any more, so retrying it would report its error
+        # on every change. Its record goes; importing it again collects it anew.
+        # A failed entry never had an importer and keeps being retried.
+        def orphaned_failure?(module_id, imported_module_ids)
+          records[module_id]&.status == :failed &&
+            imported_module_ids.include?(module_id) &&
+            graph.dependents(module_id).empty?
         end
 
         def plugin_invalidated_module_ids(paths)

data/lib/klenod/build/graph.rb

@@ -386,6 +386,18 @@ module Klenod
           @mods[module_id] = mod
           record
         end
+      rescue SourceError => error
+        error.path ||= source_path_for(error.module_id)
+        raise
+      end
+
+      # The file behind an app module, so error reports can link to it.
+      def source_path_for(module_id)
+        return nil unless module_id.is_a?(ModuleId) && module_id.scheme == :app
+
+        absolute_path(module_id).to_s
+      rescue ResolveError
+        nil
       end
 
       def collect_module(module_id, force: false)
@@ -443,6 +455,9 @@ module Klenod
           @profiler.progress(:collect_module, module_id: record.id.to_s, total_records: @records.length)
           record
         end
+      rescue SourceError => error
+        error.path ||= source_path_for(error.module_id)
+        raise
       end
 
       def evaluate_module(module_id)

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

@@ -60,9 +60,14 @@ module Klenod
               begin
                 attributes, rest, last_line = super
               rescue ::Haml::SyntaxError => error
-                raise unless pairs && error.message.start_with?("Invalid attribute list")
-
-                raise ::Haml::SyntaxError.new("#{error.message}\n\n#{hash_attributes_hint(tag_prefix, pairs)}", error.line)
+                raise unless error.message.start_with?("Invalid attribute list")
+
+                # Haml quotes the list with String#inspect, which escapes every
+                # `"` in it. Show the source as written instead.
+                attribute_list = ::Haml::Util.balance(text, "(", ")")&.first || text
+                message = "Invalid attribute list: `#{attribute_list}`."
+                message = "#{message}\n\n#{hash_attributes_hint(tag_prefix, pairs)}" if pairs
+                raise ::Haml::SyntaxError.new(message, error.line)
               end
               return [attributes, rest, last_line + joined_lines]
             end

data/lib/klenod/build/resolution_error_formatter.rb

@@ -1,34 +1,23 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "source_excerpt"
 
 module Klenod
   module Build
     module ResolutionErrorFormatter
-      ANSI_BACKGROUND = "\e[0;48;5;52m"
-
       module_function
 
       def format(error, source_root: nil, source_context: nil, ansi: false)
         return error.message unless error.resolution_failure?
 
-        lines = [error.title, "", "  Import:      #{error.requested_specifier}"]
+        lines = [SourceExcerpt.header(error.title, "", ansi:), "", "  Import:      #{error.requested_specifier}"]
         lines << "  Imported by: #{error.imported_by}" if error.imported_by
         lines << "  Source root: #{source_root}" if source_root
         append_suggestions(lines, error)
         lines.concat(["", source_context]) if source_context
-        text = lines.join("\n")
-        ansi ? format_ansi(text) : text
-      end
-
-      def format_ansi(text)
-        title, separator, body = text.partition("\n")
-        body = body.gsub("\e[0m", ANSI_BACKGROUND)
-        body = "\n#{body}" unless separator.empty?
-
-        "\e[1;31;47m ERROR \e[1;37;41m #{title} #{ANSI_BACKGROUND}#{body}\e[0m"
+        lines.join("\n")
       end
-      private_class_method :format_ansi
 
       def append_suggestions(lines, error)
         return if error.suggestions.empty?

data/lib/klenod/build/source_error.rb

@@ -27,7 +27,7 @@ module Klenod
         def initialize(line: nil, column: nil, detail: nil, hints: []) = super
       end
 
-      attr_reader :module_id, :source, :line, :column, :cause, :detail, :hints
+      attr_reader :module_id, :source, :line, :column, :cause, :detail, :hints, :path
 
       def initialize(error, source:, module_id:)
         @cause = error
@@ -40,19 +40,31 @@ module Klenod
         @detail = found.detail || message_for(error)
         @hints = Array(found.hints).map(&:to_s).reject(&:empty?).freeze
 
-        super(
+        super(@detail)
+
+        set_backtrace(backtrace_for(error))
+      end
+
+      # The file the module was read from, when it has one. The graph sets it
+      # as the error leaves the module, since plugins only know the module ID,
+      # and the message links the location to it.
+      def path=(path)
+        @path = path
+        @message = nil
+      end
+
+      def to_s
+        @message ||=
           SourceExcerpt.message(
             module_id:,
-            line: @line,
-            column: @column,
+            line:,
+            column:,
             kind:,
             source:,
-            message: @detail,
-            hints: @hints
+            message: detail,
+            hints:,
+            path:
           )
-        )
-
-        set_backtrace(backtrace_for(error))
       end
 
       # "JavaScript parse error". Used as the label in the browser error dialog,

data/lib/klenod/build/source_excerpt.rb

@@ -10,34 +10,120 @@ module Klenod
     # `ansi: false` to get the same layout without escape codes.
     module SourceExcerpt
       MARKED_LINE = "\e[1;31m"
+      KIND = "\e[1;31m"
+      DETAIL = "\e[31m"
+      HINT_LABEL = "\e[1;36m"
+      HINT = "\e[36m"
+      LOCATION = "\e[34m"
+      BOLD = "\e[1m"
+      NOT_BOLD = "\e[22m"
+      DIM = "\e[2m"
       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
+      # "app:/pages/thing.tsx:33:9"
+      def location(module_id:, line:, column: nil)
+        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
+      end
 
-        location ? "#{location}: #{kind}" : kind
+      # The kind and detail share a header line. The location goes in the
+      # excerpt's frame, or on an "at" line when there is no excerpt, and the
+      # hints follow:
+      #
+      #   × Haml parse error: Could not parse Ruby filter
+      #
+      #       ╭─[app:/pages/page.haml:4]
+      #     3 │     @count = 0
+      #   > 4 │
+      #       ╰────
+      #     hint: Unmatched keyword, missing `end' ?
+      #
+      # With `path`, the file the module was read from, the location links to
+      # that file when `links` is on.
+      def message(module_id:, line:, kind:, source:, message:, column: nil, hints: [], context: 2, ansi: true, path: nil, links: ansi && hyperlinks?)
+        location = styled_location(module_id:, line:, column:, path:, ansi:, links:)
+        excerpt = excerpt(source:, line:, column:, context:, ansi:, location:)
+        hints = hint_section(hints, ansi:)&.gsub(/^/, "  ")
+        header = header(kind, message, ansi:)
+
+        unless excerpt
+          header = "#{header}\n  #{dim("at", ansi:)} #{location}" if location
+          return [header, hints].compact.join("\n\n")
+        end
+
+        [header, [excerpt, hints].compact.join("\n")].join("\n\n")
       end
 
-      def message(module_id:, line:, kind:, source:, message:, column: nil, hints: [], context: 2, ansi: true)
+      # "× JSON parse error: expected object key". Later lines of a multi-line
+      # detail are indented under the first.
+      def header(kind, message, ansi: true)
+        first, *rest = message.to_s.lines(chomp: true)
+        label = first ? "× #{kind}:" : "× #{kind}"
+        label = "#{KIND}#{label}#{RESET}" if ansi
+        return label unless first
+
         [
-          title(module_id:, line:, column:, kind:),
-          message,
-          excerpt(source:, line:, column:, context:, ansi:),
-          hint_section(hints)
-        ].compact.join("\n\n")
+          "#{label} #{detail(first, ansi:)}",
+          *rest.map { it.empty? ? it : "  #{detail(it, ansi:)}" }
+        ].join("\n")
+      end
+
+      # The location in blue with the file name in bold, linked to `path` when
+      # `links` is on and the file exists.
+      def styled_location(module_id:, line: nil, column: nil, path: nil, ansi: true, links: ansi && hyperlinks?)
+        location = location(module_id:, line:, column:)
+        return location unless ansi && location
+
+        location = bold_file_name(location, module_id) if module_id
+        location = file_link(location, path:, line:, column:) if links && path && File.file?(path.to_s)
+        "#{LOCATION}#{location}#{RESET}"
+      end
+
+      # "app:\e[1m/pages/thing.tsx\e[22m:33:9": the file name stands out from its
+      # scheme and position.
+      def bold_file_name(location, module_id)
+        scheme, name = module_id.to_s.match(/\A([a-z][a-z0-9+.-]*:)?(.*)\z/i).captures
+        location.sub(module_id.to_s) { "#{scheme}#{BOLD}#{name}#{NOT_BOLD}" }
+      end
+
+      # Whether the terminal turns OSC 8 sequences into clickable links. There
+      # is no way to ask, so this recognises the terminals known to do it.
+      def hyperlinks?(env = ENV)
+        return false if env.key?("NO_COLOR")
+        return true if %w[iTerm.app WezTerm vscode ghostty Hyper Tabby rio].include?(env["TERM_PROGRAM"])
+        return true if %w[xterm-kitty foot contour].include?(env["TERM"])
+        return true if env.key?("KITTY_WINDOW_ID") || env.key?("WT_SESSION") || env.key?("ALACRITTY_WINDOW_ID")
+        return true if env["VTE_VERSION"].to_i >= 5000
+        return true if env["KONSOLE_VERSION"].to_i >= 201200
+
+        false
+      end
+
+      # Wraps `text` in an OSC 8 hyperlink to `path`, with the line and column
+      # as the fragment: "file:///app/pages/thing.tsx#33:9".
+      def file_link(text, path:, line: nil, column: nil)
+        encoded = path.to_s.b.gsub(%r{[^A-Za-z0-9\-._~/]}) { format("%%%02X", it.ord) }
+        fragment = line && "##{[line, column].compact.join(":")}"
+
+        "\e]8;;file://#{encoded}#{fragment}\e\\#{text}\e]8;;\e\\"
+      end
+
+      # Colored per line so loggers that prefix each line do not carry the
+      # color into their gutter.
+      def detail(message, ansi: true)
+        return message unless ansi && message
+
+        message.to_s.lines(chomp: true).map { it.empty? ? it : "#{DETAIL}#{it}#{RESET}" }.join("\n")
       end
 
-      def excerpt(source:, line:, column: nil, context: 2, ansi: true)
+      def excerpt(source:, line:, column: nil, context: 2, ansi: true, location: nil)
         return nil unless line
 
         lines = source.to_s.lines
@@ -49,35 +135,53 @@ module Klenod
         first = [index - context, 0].max
         last = [index + context, lines.length - 1].min
         width = (last + 1).to_s.length
+        gutter = " " * (width + 3)
 
         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]
+            code = lines.fetch(line_index).chomp
+            formatted =
+              if marked
+                row = "> #{number} │ #{code}".rstrip
+                ansi ? "#{MARKED_LINE}#{row}#{RESET}" : row
+              else
+                "#{dim("  #{number} │", ansi:)} #{code}".rstrip
+              end
+
+            marked ? [formatted, caret_row(width, column, ansi:)].compact : [formatted]
           end
 
-        "Source:\n#{rows.join("\n")}"
+        [
+          location ? "#{gutter}#{dim("╭─[", ansi:)}#{location}#{dim("]", ansi:)}" : "#{gutter}#{dim("╭────", ansi:)}",
+          *rows,
+          "#{gutter}#{dim("╰────", ansi:)}"
+        ].join("\n")
+      end
+
+      # `text` without color codes or OSC 8 links, as a terminal would show it.
+      def strip(text)
+        text.to_s.gsub(/\e\[[0-9;]*m|\e\]8;[^\e\a]*(?:\e\\|\a)/, "")
+      end
+
+      def dim(text, ansi: true)
+        ansi ? "#{DIM}#{text}#{RESET}" : text
       end
 
-      # "    |       ^", aligned under the offending column of the marked line.
-      def caret_row(width, column)
+      # "    ·       ^", aligned under the offending column of the marked line.
+      def caret_row(width, column, ansi: true)
         return nil unless column&.positive?
 
-        "#{" " * (width + 3)}| #{" " * (column - 1)}^"
+        "#{" " * (width + 3)}#{dim("·", ansi:)} #{" " * (column - 1)}^"
       end
 
-      # What to try next. Rendered like the "Source:" section so the two read as
-      # one report.
-      def hint_section(hints)
+      # What to try next, one "hint: ..." line per hint.
+      def hint_section(hints, ansi: true)
         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")}"
+        hints.map { ansi ? "#{HINT_LABEL}hint:#{RESET} #{HINT}#{it}#{RESET}" : "hint: #{it}" }.join("\n")
       end
     end
   end

data/lib/klenod/build/version.rb

@@ -2,6 +2,6 @@
 
 module Klenod
   module Build
-    VERSION = "0.0.25"
+    VERSION = "0.0.26"
   end
 end

data/lib/klenod/build.rb

@@ -3,6 +3,8 @@
 require_relative "build/version"
 require "klenod/runtime"
 require_relative "build/context"
+require_relative "build/exception_formatter"
+require_relative "build/resolution_error_formatter"
 
 module Klenod
   class Error < StandardError; end unless const_defined?(:Error, false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: klenod-build
 version: !ruby/object:Gem::Version
-  version: 0.0.25
+  version: 0.0.26
 platform: ruby
 authors:
 - Andrés Alin
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.25
+        version: 0.0.26
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.25
+        version: 0.0.26
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -257,6 +257,7 @@ files:
 - lib/klenod/build/context.rb
 - lib/klenod/build/dependency.rb
 - lib/klenod/build/errors.rb
+- lib/klenod/build/exception_formatter.rb
 - lib/klenod/build/filesystem_resolver.rb
 - lib/klenod/build/graph.rb
 - lib/klenod/build/graph/invalidator.rb