herb-embedded 0.10.3.0

data/lib/herb/embedded/cli.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+require_relative "version"
+require_relative "bundle"
+require_relative "config"
+require_relative "bridge"
+require_relative "runner"
+require_relative "formatters"
+require_relative "adapters/mini_racer"
+
+module Herb
+  module Embedded
+    # The user-facing entry point (exe/herb-lint-rb). Flags mirror
+    # herb-lint; the -rb suffix lets both binaries coexist.
+    class CLI
+      EXIT_CLEAN = 0
+      EXIT_OFFENSES = 1
+      EXIT_CONFIG_ERROR = 2
+
+      VALID_FORMATS = %w[detailed simple json github].freeze
+      VALID_FAIL_LEVELS = %w[error warning info hint].freeze
+
+      HERB_YML_TEMPLATE = <<~YAML
+        version: "%<version>s"
+        files:
+          include:
+            - "**/*.html.erb"
+            - "**/*.herb"
+          exclude: []
+        linter:
+          fail_level: error
+          rules: {}
+      YAML
+
+      def initialize(argv, stdout:, stderr:)
+        @argv = argv.dup
+        @stdout = stdout
+        @stderr = stderr
+        @format = "detailed"
+        @fail_level = nil
+        @only = []
+        @fix = false
+        @unsafe = false
+        @mode = :lint
+      end
+
+      def run
+        parser.parse!(@argv)
+
+        case @mode
+        when :help
+          @stdout.puts parser.help
+          EXIT_CLEAN
+        when :version
+          print_version
+        when :init
+          write_init_file
+        else
+          lint_and_report
+        end
+      rescue OptionParser::ParseError => e
+        @stderr.puts e.message
+        EXIT_CONFIG_ERROR
+      rescue Psych::SyntaxError => e
+        @stderr.puts "Invalid .herb.yml: #{e.message}"
+        EXIT_CONFIG_ERROR
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: herb-lint-rb [options] [files...]"
+
+          define_fix_options(opts)
+          define_report_options(opts)
+          define_mode_options(opts)
+        end
+      end
+
+      def define_fix_options(opts)
+        opts.on("--fix", "Apply safe autocorrections") { @fix = true }
+        opts.on("--fix-unsafely", "Apply unsafe autocorrections too") do
+          @fix = true
+          @unsafe = true
+        end
+      end
+
+      def define_report_options(opts)
+        opts.on("--format FORMAT", VALID_FORMATS, "detailed | simple | json | github (default: detailed)") do |v|
+          @format = v
+        end
+        opts.on("--fail-level LEVEL", VALID_FAIL_LEVELS, "error | warning | info | hint") do |v|
+          @fail_level = v.to_sym
+        end
+        opts.on("--only RULE", "Run only this rule (repeatable)") { |v| @only << v }
+      end
+
+      def define_mode_options(opts)
+        opts.on("--init", "Write .herb.yml pinning the current linter version") { @mode = :init }
+        opts.on("--version", "Print herb-embedded and bundled @herb-tools/linter versions") { @mode = :version }
+        opts.on("-h", "--help", "Show this help") { @mode = :help }
+      end
+
+      def print_version
+        @stdout.puts "herb-embedded #{Herb::Embedded::VERSION} (bundled @herb-tools/linter #{Bundle.linter_version})"
+        EXIT_CLEAN
+      end
+
+      def write_init_file
+        path = File.join(Dir.pwd, ".herb.yml")
+        File.write(path, format(HERB_YML_TEMPLATE, version: Bundle.linter_version))
+        @stdout.puts "Wrote #{path}"
+        EXIT_CLEAN
+      end
+
+      def lint_and_report
+        root = Dir.pwd
+        config = Config.load(root)
+        bridge, runner = boot_bridge_and_runner(root, config)
+
+        unknown_rules = @only - bridge.rule_names
+        return report_unknown_rules(unknown_rules) if unknown_rules.any?
+
+        report = run_or_fix(runner)
+        @stdout.puts Formatters.fetch(@format.to_sym).render(report)
+        report.exit_code(fail_level: @fail_level || config.fail_level)
+      ensure
+        bridge&.dispose
+      end
+
+      def boot_bridge_and_runner(root, config)
+        bridge = Bridge.new(adapter: Adapters::MiniRacer.new, bundle: Bundle).boot
+        runner = Runner.new(root: root, config: config, bridge: bridge)
+        runner.load_custom_rules!
+        [bridge, runner]
+      end
+
+      def report_unknown_rules(unknown_rules)
+        @stderr.puts "Unknown rule(s): #{unknown_rules.join(", ")}"
+        EXIT_CONFIG_ERROR
+      end
+
+      def run_or_fix(runner)
+        paths = @argv.empty? ? nil : @argv
+        rules = @only.empty? ? nil : @only
+
+        if @fix
+          runner.fix(paths, rules: rules, unsafe: @unsafe)
+        else
+          runner.run(paths, rules: rules)
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/config.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Herb
+  module Embedded
+    # Reads .herb.yml. The engine has no filesystem, so Ruby owns config
+    # entirely. Uses the same nested schema as upstream @herb-tools/config
+    # (only version, files.include/exclude, linter.fail_level, and
+    # linter.rules.<name>.enabled are read; other upstream keys are
+    # parsed as inert and ignored, not errored on).
+    class Config
+      CONFIG_FILENAME = ".herb.yml"
+      DEFAULT_INCLUDE_GLOBS = ["**/*.html.erb", "**/*.herb"].freeze
+      DEFAULT_EXCLUDE_GLOBS = [].freeze
+      DEFAULT_FAIL_LEVEL = :error
+
+      attr_reader :include_globs, :exclude_globs, :fail_level, :linter_version
+
+      def self.load(dir)
+        path = File.join(dir, CONFIG_FILENAME)
+        data = File.exist?(path) ? (YAML.load_file(path) || {}) : {}
+
+        new(data)
+      end
+
+      def initialize(data)
+        files = data["files"] || {}
+        linter = data["linter"] || {}
+
+        @include_globs = files["include"] || DEFAULT_INCLUDE_GLOBS.dup
+        @exclude_globs = files["exclude"] || DEFAULT_EXCLUDE_GLOBS.dup
+        @fail_level = (linter["fail_level"] || DEFAULT_FAIL_LEVEL).to_sym
+        @linter_version = data["version"]
+        @disabled_rule_names = disabled_rule_names(linter["rules"])
+      end
+
+      def enabled_rule_names(all_rule_names)
+        all_rule_names - @disabled_rule_names
+      end
+
+      private
+
+      def disabled_rule_names(rules)
+        (rules || {}).each_with_object([]) do |(name, rule_config), disabled|
+          disabled << name if rule_config.is_a?(Hash) && rule_config["enabled"] == false
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/custom_rule_loader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # Loads project-local rules from .herb/rules/**/*.mjs. Upstream's own
+    # loader uses pathToFileURL, tinyglobby, and dynamic import() — none of
+    # which exist in an embedded engine. Ruby replaces the loader entirely:
+    # it globs and reads the files, rewrites their one supported import
+    # (@herb-tools/linter) into a destructure from the already-loaded
+    # bundle, and hands the result to the engine for registration.
+    class CustomRuleLoader
+      class UnsupportedImportError < StandardError; end
+      class InvalidRuleError < StandardError; end
+
+      RULES_GLOB = File.join(".herb", "rules", "**", "*.mjs")
+      ALLOWED_SPECIFIER = "@herb-tools/linter"
+      IMPORT_LINE = /^import\b.*$/
+      NAMED_IMPORT_LINE = /^import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["'];?\s*$/
+      EXPORT_DEFAULT_CLASS = /export\s+default\s+class\s+(\w+)/
+
+      def initialize(root:, bridge:)
+        @root = root
+        @bridge = bridge
+      end
+
+      def load_all
+        Dir.glob(File.join(@root, RULES_GLOB)).map do |path|
+          rewritten = self.class.rewrite(File.read(path), path)
+          result = @bridge.register_custom_rule(rewritten, path)
+
+          if result["overrode"]
+            warn("Custom rule '#{result["ruleName"]}' at #{path} overrides a built-in rule of the same name")
+          end
+
+          result["ruleName"]
+        end
+      end
+
+      # Only a single supported specifier is rewritten: named imports from
+      # "@herb-tools/linter" become a destructure from the bundle-global
+      # HerbLinter. Anything else — a different specifier, or an import
+      # form other than named braces — fails loudly rather than producing
+      # a mysterious ReferenceError at rule-execution time.
+      def self.rewrite(source, path)
+        named_imports = extract_named_imports(source, path)
+        body = strip_import_lines(source)
+        body = rewrite_default_export(body, path)
+        destructure = named_imports.empty? ? "" : "const { #{named_imports.join(", ")} } = HerbLinter;\n"
+
+        <<~JS
+          (function () {
+            #{destructure}#{body}
+            return __herbCustomRule;
+          })()
+        JS
+      end
+
+      def self.extract_named_imports(source, path)
+        named_imports = []
+
+        source.each_line do |line|
+          next unless line.match?(IMPORT_LINE)
+
+          match = line.match(NAMED_IMPORT_LINE)
+          raise UnsupportedImportError, "#{path}: unsupported import statement: #{line.strip}" unless match
+
+          names, specifier = match.captures
+          if specifier != ALLOWED_SPECIFIER
+            raise UnsupportedImportError,
+                  "#{path}: unsupported import from \"#{specifier}\" (only \"#{ALLOWED_SPECIFIER}\" is supported)"
+          end
+
+          named_imports.concat(names.split(",").map(&:strip).reject(&:empty?))
+        end
+
+        named_imports
+      end
+      private_class_method :extract_named_imports
+
+      def self.strip_import_lines(source)
+        source.gsub(IMPORT_LINE, "")
+      end
+      private_class_method :strip_import_lines
+
+      def self.rewrite_default_export(body, path)
+        unless body.match?(EXPORT_DEFAULT_CLASS)
+          raise InvalidRuleError, "#{path}: no default export found; custom rules must use `export default class`"
+        end
+
+        body.sub(EXPORT_DEFAULT_CLASS, 'const __herbCustomRule = class \1')
+      end
+      private_class_method :rewrite_default_export
+    end
+  end
+end

data/lib/herb/embedded/diagnostic.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # A single lint offense. Shaped to match upstream Herb::Diagnostic /
+    # Herb::LintOffense (marcoroth/herb#455, unmerged): #to_h's key set
+    # mirrors that class's #to_h exactly, so this drops into its socket
+    # without rewriting every consumer if/when that PR lands. #file,
+    # #line, #column, and #correctable? are this gem's own convenience
+    # accessors on top of that shape — upstream has no per-file scope
+    # (a single Herb.lint call is per-source) and derives correctability
+    # from a rule's static autocorrectable flag rather than a reader.
+    class Diagnostic
+      SEVERITIES = %i[error warning info hint].freeze
+      DEFAULT_SEVERITY = :error
+
+      attr_reader :file, :rule, :message, :severity, :location, :code, :source
+
+      # rubocop:disable Metrics/ParameterLists -- value object, one flat field per keyword
+      def initialize(file:, rule:, message:, severity:, location:, code: nil, source: nil, correctable: false)
+        @file = file
+        @rule = rule
+        @message = message
+        @severity = SEVERITIES.include?(severity) ? severity : DEFAULT_SEVERITY
+        @location = location
+        @code = code
+        @source = source
+        @correctable = correctable
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def self.from_js(hash, file:)
+        new(
+          file: file,
+          rule: hash["rule"],
+          message: hash["message"],
+          severity: hash["severity"]&.to_sym,
+          location: hash["location"],
+          code: hash["code"],
+          source: hash["source"],
+          correctable: !hash["autofixContext"].nil?,
+        )
+      end
+
+      def line
+        location&.dig("start", "line")
+      end
+
+      def column
+        location&.dig("start", "column")
+      end
+
+      def correctable?
+        @correctable
+      end
+
+      def to_h
+        {
+          message: message,
+          location: location,
+          severity: severity,
+          code: code,
+          source: source,
+          rule: rule,
+        }
+      end
+    end
+  end
+end

data/lib/herb/embedded/engine_adapter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # Port between Ruby and whichever JavaScript engine executes Herb's
+    # rule code. Concrete engines (MiniRacer, and later QuickJS/Wasmtime)
+    # implement this interface; callers depend only on it.
+    class EngineAdapter
+      # Marks a Ruby string as binary data that must cross the engine
+      # boundary as a byte array (e.g. a Uint8Array), not a JS string,
+      # since arbitrary bytes are not valid UTF-8.
+      Binary = Struct.new(:raw)
+
+      def self.binary(bytes)
+        Binary.new(bytes)
+      end
+
+      def load(source)
+        raise NotImplementedError, "#{self.class} must implement #load"
+      end
+
+      def attach(name, &)
+        raise NotImplementedError, "#{self.class} must implement #attach"
+      end
+
+      def call(function, *args)
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      def dispose
+        raise NotImplementedError, "#{self.class} must implement #dispose"
+      end
+    end
+  end
+end

data/lib/herb/embedded/formatters/detailed.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    module Formatters
+      # Offenses grouped by file, with correctable offenses flagged.
+      class Detailed
+        def render(report)
+          report.diagnostics
+                .group_by(&:file)
+                .flat_map { |file, diagnostics| render_file(file, diagnostics) }
+                .join("\n")
+        end
+
+        private
+
+        def render_file(file, diagnostics)
+          ["#{file}:"] + diagnostics.map { |diagnostic| render_diagnostic(diagnostic) }
+        end
+
+        def render_diagnostic(diagnostic)
+          flag = diagnostic.correctable? ? " [correctable]" : ""
+          "  #{diagnostic.line}:#{diagnostic.column} #{diagnostic.severity} " \
+            "#{diagnostic.message} (#{diagnostic.rule})#{flag}"
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/formatters/github.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    module Formatters
+      # One GitHub Actions annotation line per offense:
+      # ::error file=...,line=...,col=...::message
+      class Github
+        def render(report)
+          report.diagnostics.map { |diagnostic| annotation(diagnostic) }.join("\n")
+        end
+
+        private
+
+        def annotation(diagnostic)
+          "::error file=#{diagnostic.file},line=#{diagnostic.line},col=#{diagnostic.column}::#{diagnostic.message}"
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/formatters/json.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Herb
+  module Embedded
+    module Formatters
+      # { offenses: [...], summary: { files_checked, offenses, correctable } }
+      class Json
+        def render(report)
+          {
+            offenses: report.diagnostics.map { |diagnostic| offense_hash(diagnostic) },
+            summary: {
+              files_checked: report.files_checked,
+              offenses: report.diagnostics.size,
+              correctable: report.correctable_count,
+            },
+          }.to_json
+        end
+
+        private
+
+        def offense_hash(diagnostic)
+          diagnostic.to_h.merge(
+            file: diagnostic.file,
+            line: diagnostic.line,
+            column: diagnostic.column,
+            correctable: diagnostic.correctable?,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/formatters/simple.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    module Formatters
+      # One "file:line:col severity message (rule)" line per offense, plus
+      # a summary line.
+      class Simple
+        def render(report)
+          lines = report.diagnostics.map { |diagnostic| format_diagnostic(diagnostic) }
+          lines << summary(report)
+          lines.join("\n")
+        end
+
+        private
+
+        def format_diagnostic(diagnostic)
+          "#{diagnostic.file}:#{diagnostic.line}:#{diagnostic.column} " \
+            "#{diagnostic.severity} #{diagnostic.message} (#{diagnostic.rule})"
+        end
+
+        def summary(report)
+          "#{report.files_checked} files checked, #{report.diagnostics.size} offenses"
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/formatters.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "formatters/simple"
+require_relative "formatters/detailed"
+require_relative "formatters/json"
+require_relative "formatters/github"
+
+module Herb
+  module Embedded
+    # Formatters are pure functions of a Report: #render(report) -> String.
+    module Formatters
+      REGISTRY = {
+        simple: Simple,
+        detailed: Detailed,
+        json: Json,
+        github: Github,
+      }.freeze
+
+      module_function
+
+      def fetch(name)
+        formatter_class = REGISTRY[name]
+        raise ArgumentError, "Unknown formatter: #{name.inspect}" unless formatter_class
+
+        formatter_class.new
+      end
+    end
+  end
+end

data/lib/herb/embedded/lint_result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # The diagnostics produced for a single file.
+    class LintResult
+      attr_reader :file, :diagnostics
+
+      def initialize(file:, diagnostics: [])
+        @file = file
+        @diagnostics = diagnostics
+      end
+    end
+  end
+end

data/lib/herb/embedded/report.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # Aggregates LintResults across a run.
+    class Report
+      SEVERITY_RANK = { error: 3, warning: 2, info: 1, hint: 0 }.freeze
+
+      def initialize
+        @lint_results = []
+      end
+
+      def add(lint_result)
+        @lint_results << lint_result
+      end
+
+      def diagnostics
+        @lint_results.flat_map(&:diagnostics)
+      end
+
+      def files_checked
+        @lint_results.size
+      end
+
+      def files_with_offenses
+        @lint_results.select { |result| result.diagnostics.any? }.map(&:file).uniq.size
+      end
+
+      def correctable_count
+        diagnostics.count(&:correctable?)
+      end
+
+      def exit_code(fail_level:)
+        threshold = SEVERITY_RANK.fetch(fail_level)
+        reached = diagnostics.any? { |diagnostic| SEVERITY_RANK.fetch(diagnostic.severity) >= threshold }
+        reached ? 1 : 0
+      end
+    end
+  end
+end