herb 0.10.4 → 0.11.0

data/lib/herb/colors.rb

@@ -11,8 +11,22 @@ module Herb
 
     module_function
 
+    #: [T] (bool) { () -> T } -> T
+    def with_color(enabled)
+      previous = Thread.current[:herb_colors]
+      Thread.current[:herb_colors] = enabled
+
+      yield
+    ensure
+      Thread.current[:herb_colors] = previous
+    end
+
     #: () -> bool
     def enabled?
+      forced = Thread.current[:herb_colors]
+
+      return forced unless forced.nil?
+
       return false if ENV["NO_COLOR"]
       return false if defined?(IRB)
       return false if defined?(Minitest)

data/lib/herb/configuration.rb

@@ -11,7 +11,8 @@ module Herb
     VALID_FRAMEWORKS = OPTIONS["framework"]["values"].freeze #: Array[String]
     VALID_TEMPLATE_ENGINES = OPTIONS["template_engine"]["values"].freeze #: Array[String]
 
-    CONFIG_FILENAMES = [".herb.yml"].freeze
+    CONFIG_FILENAMES = [".herb.yml"].freeze #: Array[String]
+    MISNAMED_CONFIG_FILENAMES = [".herb.yaml", "herb.yml", "herb.yaml"].freeze #: Array[String]
 
     PROJECT_INDICATORS = [
       ".git",
@@ -23,18 +24,23 @@ module Herb
       "README.md",
       "*.gemspec",
       "config/application.rb"
-    ].freeze
+    ].freeze #: Array[String]
 
     DEFAULTS_PATH = File.expand_path("defaults.yml", __dir__ || __FILE__).freeze
     DEFAULTS = YAML.safe_load_file(DEFAULTS_PATH).freeze
 
-    attr_reader :config, :user_config, :config_path, :project_root
+    GLOB_CHARACTERS = /[*?\[\]{}]/ #: Regexp
+
+    attr_reader :config, :user_config, :config_path, :project_root, :misnamed_config_paths
 
     def initialize(project_path = nil)
       @start_path = project_path ? Pathname.new(project_path) : Pathname.pwd
       @config_path, @project_root = find_config_file
+      @misnamed_config_paths = find_misnamed_config_paths
       @user_config = load_user_config
       @config = deep_merge(DEFAULTS, @user_config)
+
+      warn_about_misnamed_config_files
     end
 
     def [](key)
@@ -85,6 +91,22 @@ module Herb
       files["exclude"] || DEFAULTS.dig("files", "exclude") || []
     end
 
+    def parser
+      @config["parser"] || {}
+    end
+
+    #: () -> Array[String]
+    def erb_openers
+      parser["erb_openers"] || []
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def parser_options
+      openers = erb_openers
+
+      openers.empty? ? {} : { erb_openers: openers }
+    end
+
     def linter
       @config["linter"] || {}
     end
@@ -105,6 +127,7 @@ module Herb
         security: config.fetch("security", true),
         nesting: config.fetch("nesting", true),
         accessibility: config.fetch("accessibility", true),
+        generator_template: config.fetch("generator_template", true),
       }.merge(
         overrides.to_h { |key, value| [key.to_sym, !!value] }
       )
@@ -141,17 +164,7 @@ module Herb
     end
 
     def enabled_for_path?(path, tool)
-      tool_config = send(tool.to_s)
-      tool_include = tool_config["include"] || []
-      tool_exclude = tool_config["exclude"] || []
-
-      if tool_include.any? && path_included?(path, tool_include)
-        return !path_excluded?(path, tool_exclude)
-      end
-
-      exclude_patterns = exclude_patterns_for(tool)
-
-      !path_excluded?(path, exclude_patterns)
+      !path_excluded?(path, exclude_patterns_for(tool), include_patterns_for(tool))
     end
 
     def linter_enabled_for_path?(path)
@@ -162,42 +175,51 @@ module Herb
       enabled_for_path?(path, :formatter)
     end
 
-    def path_excluded?(path, patterns)
-      patterns.any? { |pattern| File.fnmatch?(pattern, path, File::FNM_PATHNAME) }
+    def path_excluded?(path, patterns, include_patterns = [])
+      matching_excludes = patterns.select { |pattern| File.fnmatch?(pattern, path, File::FNM_PATHNAME) }
+      return false if matching_excludes.empty?
+
+      matching_includes = include_patterns.select { |pattern| File.fnmatch?(pattern, path, File::FNM_PATHNAME) }
+      return true if matching_includes.empty?
+
+      matching_excludes.any? do |exclude_pattern|
+        matching_includes.none? { |include_pattern| include_overrides_exclude?(include_pattern, exclude_pattern) }
+      end
     end
 
     def path_included?(path, patterns)
       patterns.any? { |pattern| File.fnmatch?(pattern, path, File::FNM_PATHNAME) }
     end
 
-    def find_files(search_path = nil)
-      search_path ||= @project_root || @start_path
-      expanded_path = File.expand_path(search_path.to_s)
+    def include_overrides_exclude?(include_pattern, exclude_pattern)
+      exclude_prefix = literal_prefix_segments(exclude_pattern)
+      return false if exclude_prefix.empty?
 
-      all_files = file_include_patterns.flat_map do |pattern|
-        Dir[File.join(expanded_path, pattern)]
-      end.uniq
+      include_prefix = literal_prefix_segments(include_pattern)
 
-      all_files.reject do |file|
-        relative = file.sub("#{expanded_path}/", "")
-        path_excluded?(relative, file_exclude_patterns)
-      end.sort
+      include_prefix.length >= exclude_prefix.length && include_prefix.first(exclude_prefix.length) == exclude_prefix
+    end
+
+    def literal_prefix_segments(pattern)
+      pattern.split("/").take_while { |segment| !segment.match?(GLOB_CHARACTERS) }
+    end
+
+    def find_files(search_path = nil)
+      collect_files(search_path, file_include_patterns, file_exclude_patterns)
     end
 
     def find_files_for_tool(tool, search_path = nil)
+      collect_files(search_path, include_patterns_for(tool), exclude_patterns_for(tool))
+    end
+
+    def collect_files(search_path, include_patterns, exclude_patterns)
       search_path ||= @project_root || @start_path
       expanded_path = File.expand_path(search_path.to_s)
 
-      include_patterns = include_patterns_for(tool)
-      exclude_patterns = exclude_patterns_for(tool)
-
-      all_files = include_patterns.flat_map do |pattern|
-        Dir[File.join(expanded_path, pattern)]
-      end.uniq
+      all_files = include_patterns.flat_map { |pattern| Dir[File.join(expanded_path, pattern)] }.uniq
 
       all_files.reject do |file|
-        relative = file.sub("#{expanded_path}/", "")
-        path_excluded?(relative, exclude_patterns)
+        path_excluded?(file.sub("#{expanded_path}/", ""), exclude_patterns, include_patterns)
       end.sort
     end
 
@@ -247,6 +269,20 @@ module Herb
       [nil, @start_path]
     end
 
+    def find_misnamed_config_paths
+      search_path = @project_root || @start_path
+      search_path = search_path.parent if search_path.file?
+
+      MISNAMED_CONFIG_FILENAMES.map { |filename| search_path / filename }.select(&:exist?)
+    end
+
+    def warn_about_misnamed_config_files
+      @misnamed_config_paths.each do |misnamed_path|
+        warn "[Herb] Ignoring #{misnamed_path}: Herb only reads `#{CONFIG_FILENAMES.first}`. " \
+             "Rename it to `#{CONFIG_FILENAMES.first}` to apply it."
+      end
+    end
+
     def project_root?(path)
       PROJECT_INDICATORS.any? do |indicator|
         if indicator.include?("*")
@@ -261,7 +297,7 @@ module Herb
       return {} unless @config_path&.exist?
 
       begin
-        YAML.safe_load_file(@config_path, permitted_classes: [Symbol]) || {}
+        YAML.safe_load_file(@config_path, permitted_classes: [Symbol], aliases: true) || {}
       rescue Psych::SyntaxError => e
         warn "Warning: Invalid YAML in #{@config_path}: #{e.message}"
 

data/lib/herb/defaults.yml

@@ -1,4 +1,3 @@
-framework: ruby
 template_engine: erubi
 
 files:
@@ -24,6 +23,7 @@ engine:
     security: true
     nesting: true
     accessibility: true
+    generator_template: true
 
 linter:
   enabled: true
@@ -32,4 +32,5 @@ linter:
 formatter:
   enabled: false
   indentWidth: 2
+  indentStyle: space
   maxLineLength: 80

data/lib/herb/dev/assets.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "../fingerprint"
+
+module Herb
+  module Dev
+    # Tracks the build outputs a project's asset watchers write.
+    #
+    # A build tool rewrites its output on every run, and most runs change nothing,
+    # so only a moved digest counts as a change.
+    #
+    class Assets
+      ROOT = "app/assets/builds" #: String
+      PATTERNS = ["#{ROOT}/**/*.css", "#{ROOT}/**/*.js"].freeze #: Array[String]
+
+      #: () -> void
+      def initialize
+        @digests = {} #: Hash[String, String]
+      end
+
+      #: (String) -> Symbol
+      def self.kind_for(path)
+        path.end_with?(".css") ? :stylesheet : :script
+      end
+
+      #: (String) -> void
+      def index(root)
+        PATTERNS.each do |pattern|
+          Dir.glob(File.join(root, pattern)).each do |asset|
+            digest = Herb::Fingerprint.file(asset)
+
+            @digests[asset] = digest if digest
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      #: (String) -> bool
+      def changed?(path)
+        return false unless File.exist?(path)
+
+        digest = Herb::Fingerprint.file(path)
+
+        return false unless digest
+        return false if @digests[path] == digest
+
+        @digests[path] = digest
+
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/herb/dev/classifier.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "../../herb"
+
+module Herb
+  module Dev
+    # Says what kind of change an edit to a template is.
+    #
+    # The watcher hands it the previous and current source, and everything downstream decides
+    # what to do from the kind alone. `:none` and `:whitespace` render the same as before, so
+    # nothing needs to happen. `:static` moved markup without touching any ERB. `:dynamic` is
+    # everything else. `:parse_error` carries the errors instead of a diff.
+    #
+    # The kinds are ordered checks, and the whitespace check has to come before the patchable
+    # one. `whitespace_changed` is not a patchable operation, so a reindent classified in the
+    # wrong order would read as `:dynamic` and cost a page reload.
+    #
+    # The diff parses without the configured ERB openers, so a custom opener reads as text on
+    # both sides and its edits would pass the patchable check. With openers configured, no
+    # change classifies better than `:dynamic`.
+    #
+    class Classifier
+      PATCHABLE_TYPES = ["text_changed", "attribute_value_changed", "attribute_added", "attribute_removed"].freeze #: Array[String]
+
+      Classification = Data.define(
+        :kind,       #: Symbol
+        :operations, #: Array[Herb::Diff::Operation]
+        :node_path,  #: Array[Integer]
+        :errors      #: Array[Herb::Errors::Error]
+      )
+
+      #: (Array[Herb::Diff::Operation]) -> bool
+      def self.can_patch?(operations)
+        operations.all? { |operation|
+          next false unless PATCHABLE_TYPES.include?(operation.type.to_s)
+          next false if operation.new_node&.type&.to_s&.include?("ERB")
+          next false if operation.old_node&.type&.to_s&.include?("ERB")
+
+          true
+        }
+      end
+
+      #: (?configuration: Herb::Configuration?) -> void
+      def initialize(configuration: nil)
+        @parser_options = configuration&.parser_options || {} #: Hash[Symbol, untyped]
+      end
+
+      #: (String, String) -> Classification
+      def call(previous, current)
+        parse = Herb.parse(current, strict: true, analyze: true, **@parser_options)
+
+        return classification(:parse_error, errors: parse.errors) if parse.errors.any?
+
+        diff = Herb.diff(previous, current, track_whitespace_changes: true)
+
+        return classification(:none) if diff.identical?
+
+        operations = diff.operations
+        significant = operations.reject { |operation| operation.type.to_s == "whitespace_changed" }
+
+        return classification(:whitespace, operations: operations) if significant.empty?
+
+        kind = self.class.can_patch?(significant) && @parser_options.empty? ? :static : :dynamic
+
+        classification(kind, operations: operations, node_path: covering_path(significant))
+      end
+
+      private
+
+      #: (Symbol, ?operations: Array[Herb::Diff::Operation], ?node_path: Array[Integer], ?errors: Array[Herb::Errors::Error]) -> Classification
+      def classification(kind, operations: [], node_path: [], errors: [])
+        Classification.new(kind: kind, operations: operations, node_path: node_path, errors: errors)
+      end
+
+      #: (Array[Herb::Diff::Operation]) -> Array[Integer]
+      def covering_path(operations)
+        paths = operations.map(&:path)
+
+        paths.reduce { |common, path| common.zip(path).take_while { |left, right| left == right }.map(&:first) } || []
+      end
+    end
+  end
+end

data/lib/herb/dev/embedded.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  module Dev
+    class Embedded
+      #: (Server, Watcher, Pipeline, Integer) -> void
+      def initialize(server, watcher, pipeline, pid)
+        @server = server
+        @watcher = watcher
+        @pipeline = pipeline
+        @pid = pid
+      end
+
+      attr_reader :server #: Server
+      attr_reader :watcher #: Watcher
+      attr_reader :pipeline #: Pipeline
+      attr_reader :pid #: Integer
+
+      #: () -> void
+      def stop
+        @watcher.stop
+        @server.stop
+      end
+    end
+  end
+end

data/lib/herb/dev/pipeline.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "classifier"
+require_relative "protocol"
+
+module Herb
+  module Dev
+    # Turns one watcher event into the messages the browsers need.
+    #
+    # The pipeline holds what it learned about every file so far. The version a file last
+    # compiled to says whether an edit changed the template's shape, the slot entries feed
+    # the remap, and the error state decides when a clean compile has to say so out loud.
+    # Parse errors and compile diagnostics live in the same state machine, so a template
+    # that stops compiling behaves exactly like one that stops parsing.
+    #
+    # The compiler is looked up per event. A host that registers one after the pipeline
+    # started is picked up on the next change.
+    #
+    class Pipeline
+      STATES = [:ok, :parse_error, :diagnostics].freeze #: Array[Symbol]
+
+      Failure = Struct.new(:mode, :manifest, :version, :slot_entries, :statics, :static_markup, :diagnostics)
+
+      #: (server: untyped, ?configuration: Herb::Configuration?, ?compiler: ^() -> Herb::Dev::_Compiler?) -> void
+      def initialize(server:, configuration: nil, compiler: -> { Herb::Dev.compiler })
+        @server = server
+        @classifier = Classifier.new(configuration: configuration)
+        @compiler = compiler
+        @versions = {} #: Hash[String, String?]
+        @slot_entries = {} #: Hash[String, Array[Hash[Symbol, untyped]]]
+        @state_manifests = {} #: Hash[String, untyped]
+        @statics = {} #: Hash[String, Hash[String, String]?]
+        @file_state = {} #: Hash[String, Symbol]
+        @broken = {} #: Hash[String, Hash[Symbol, untyped]]
+        @on_classified = nil #: untyped
+      end
+
+      #: () { (untyped, Classifier::Classification?) -> void } -> void
+      def on_classified(&block)
+        @on_classified = block
+      end
+
+      #: (Hash[String, String]) -> Array[String]
+      def remember_broken(sources)
+        sources.each do |file, source|
+          errors = Herb.parse(source, strict: true, analyze: true).errors
+
+          next if errors.empty?
+
+          @file_state[file] = :parse_error
+          @broken[file] = Protocol.broken(file: file, source: source, errors: errors)
+        end
+
+        broken_files
+      end
+
+      #: () -> Array[String]
+      def broken_files
+        @broken.keys
+      end
+
+      #: () -> Array[Hash[Symbol, untyped]]
+      def broken_entries
+        @broken.values
+      end
+
+      #: () -> bool
+      def compiles?
+        !@compiler.call.nil?
+      end
+
+      #: (Watcher::Event) -> void
+      def handle_event(event)
+        case event.kind
+        when :removed
+          handle_removed(event)
+        when :added
+          handle_added(event)
+        when :changed
+          handle_changed(event)
+        when :stylesheet, :script
+          broadcast(Protocol.asset(kind: event.kind, file: event.relative_path))
+        end
+      end
+
+      private
+
+      #: (Watcher::Event) -> void
+      def handle_removed(event)
+        file = event.relative_path
+        was_broken = @file_state[file] && @file_state[file] != :ok
+        from = @versions[file]
+
+        @versions.delete(file)
+        @slot_entries.delete(file)
+        @state_manifests.delete(file)
+        @statics.delete(file)
+        @file_state.delete(file)
+        @broken.delete(file)
+
+        broadcast(Protocol.schema(file: file, mode: nil, from: from, to: nil)) if was_broken
+
+        notify(event, nil)
+      end
+
+      #: (Watcher::Event) -> void
+      def handle_added(event)
+        notify(event, nil)
+      end
+
+      #: (Watcher::Event) -> void
+      def handle_changed(event)
+        event.relative_path
+        classification = @classifier.call(event.previous.to_s, event.current.to_s)
+
+        case classification.kind
+        when :parse_error
+          handle_parse_error(event, classification)
+        when :none, :whitespace
+          nil
+        else
+          handle_content_change(event, classification)
+        end
+
+        notify(event, classification)
+      end
+
+      #: (Watcher::Event, Classifier::Classification) -> void
+      def handle_parse_error(event, classification)
+        file = event.relative_path
+        source = event.current.to_s
+
+        @file_state[file] = :parse_error
+        @broken[file] = Protocol.broken(file: file, source: source, errors: classification.errors)
+
+        broadcast(Protocol.error(file: file, source: source, errors: classification.errors))
+      end
+
+      #: (Watcher::Event, Classifier::Classification) -> void
+      def handle_content_change(event, classification)
+        compiler = @compiler.call
+
+        return handle_without_compiler(event, classification) unless compiler
+
+        file = event.relative_path
+        compiled = compile(compiler, event)
+
+        return handle_without_compiler(event, classification) if compiled == :unsupported
+
+        broadcast(schema_for(file, event, compiled, classification))
+        broadcast(invalidate_for(file, classification, compiled))
+
+        remember(file, compiled)
+      end
+
+      #: (Herb::Dev::_Compiler, Watcher::Event) -> untyped
+      def compile(compiler, event)
+        result = compiler.call(event.current.to_s, event.relative_path)
+
+        result || :unsupported
+      rescue StandardError => e
+        failure(e)
+      end
+
+      #: (StandardError) -> untyped
+      def failure(error)
+        diagnostic = {
+          message: "#{error.class}: #{error.message}",
+          severity: :error,
+          origin: "Herb Dev Server",
+        }
+
+        Failure.new(nil, nil, nil, nil, nil, nil, [diagnostic])
+      end
+
+      #: (String, Watcher::Event, untyped, Classifier::Classification) -> Hash[Symbol, untyped]
+      def schema_for(file, event, compiled, classification)
+        diagnostics = diagnostics_of(compiled)
+
+        Protocol.schema(
+          file: file,
+          mode: compiled.mode,
+          from: @versions[file],
+          to: compiled.version,
+          manifest: compiled.manifest,
+          static_markup: compiled.static_markup,
+          statics: compiled.statics,
+          changed_statics: changed_statics_for(file, compiled),
+          remap: remap_for(file, compiled, classification),
+          diagnostics: diagnostics,
+          source: event.current
+        )
+      end
+
+      #: (String, Classifier::Classification, untyped) -> Hash[Symbol, untyped]
+      def invalidate_for(file, classification, compiled)
+        Protocol.invalidate(
+          file: file,
+          version: compiled.version,
+          node_path: classification.node_path,
+          scope: scope_for(file, classification, compiled)
+        )
+      end
+
+      #: (String, Classifier::Classification, untyped) -> Symbol
+      def scope_for(file, classification, compiled)
+        return :static if classification.kind == :static
+
+        unchanged = compiled.version && compiled.version == @versions[file]
+
+        return :state if unchanged && @state_manifests.key?(file) && @state_manifests[file] != states_of(compiled)
+
+        :fetch
+      end
+
+      #: (untyped) -> untyped
+      def states_of(compiled)
+        manifest = compiled.manifest
+
+        manifest.is_a?(Hash) ? manifest["states"] : nil
+      end
+
+      #: (String, untyped, Classifier::Classification) -> Hash[String, untyped]?
+      def remap_for(file, compiled, classification)
+        previous = @slot_entries[file]
+        current = compiled.slot_entries
+
+        return nil unless previous && current
+        return { "slots" => current.to_h { |entry| [entry[:index].to_s, entry[:index]] } } if compiled.version == @versions[file]
+
+        Protocol.remap(previous, current, classification.operations)
+      end
+
+      #: (String, untyped) -> Array[String]?
+      def changed_statics_for(file, compiled)
+        previous = @statics[file]
+        current = compiled.statics
+
+        return nil unless previous && current
+
+        current.keys.reject { |key| previous[key] == current[key] }
+      end
+
+      #: (String, untyped) -> void
+      def remember(file, compiled)
+        @versions[file] = compiled.version
+        @slot_entries[file] = compiled.slot_entries
+        @state_manifests[file] = states_of(compiled)
+        @statics[file] = compiled.statics
+
+        record_diagnostics(file, diagnostics_of(compiled))
+      end
+
+      #: (String, Array[Hash[Symbol, untyped]]) -> void
+      def record_diagnostics(file, diagnostics)
+        if diagnostics.empty?
+          @file_state[file] = :ok
+          @broken.delete(file)
+        else
+          @file_state[file] = :diagnostics
+          @broken[file] = Protocol.broken(file: file, diagnostics: diagnostics)
+        end
+      end
+
+      #: (untyped) -> Array[Hash[Symbol, untyped]]
+      def diagnostics_of(compiled)
+        (compiled.diagnostics || []).map { |diagnostic|
+          diagnostic.respond_to?(:to_h) ? diagnostic.to_h : diagnostic
+        }
+      end
+
+      #: (Watcher::Event, Classifier::Classification) -> void
+      def handle_without_compiler(event, classification)
+        file = event.relative_path
+
+        if @file_state[file] == :parse_error
+          broadcast(Protocol.schema(file: file, mode: nil, from: nil, to: nil))
+        end
+
+        @file_state[file] = :ok
+        @broken.delete(file)
+
+        message = Protocol.invalidate(
+          file: file,
+          version: nil,
+          node_path: classification.node_path,
+          scope: classification.kind == :static ? :static : :fetch
+        )
+
+        broadcast(message)
+      end
+
+      #: (Hash[Symbol, untyped]) -> void
+      def broadcast(message)
+        @server.broadcast(message, to: :browsers)
+      end
+
+      #: (Watcher::Event, Classifier::Classification?) -> void
+      def notify(event, classification)
+        @on_classified&.call(event, classification)
+      end
+    end
+  end
+end