herb-embedded 0.10.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 157b3e70e039e8e93b06852fc5772ed1838a007b18d5e7de1eadbe65adf15f74
+  data.tar.gz: 1fc22a475a411316c609f84398db4750a9791694bcffb04e6139bb54ca0f2650
+SHA512:
+  metadata.gz: 6c0e5e74c9d63cd191424ab8804e712b46948f02e98eb40d30c777626c0b991a490ce792a6cb36afd41b4b322942d4e0e635f9cbcd30f9ed617d3a369602a11d
+  data.tar.gz: e9e08f1c2cadd8626accc273de42629b34977e4f3e3051ab1d1351c8d66b2ae39d8f97abe88d02f37e696cf0c8d95a6064b038be5a061d0f4900e66060992976

data/exe/herb-lint-rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "herb/embedded"
+require "herb/embedded/cli"
+
+exit(Herb::Embedded::CLI.new(ARGV, stdout: $stdout, stderr: $stderr).run)

data/js/host_shim.js

@@ -0,0 +1,137 @@
+// Minimal UTF-8 TextDecoder/TextEncoder for bare V8 embeddings (e.g.
+// mini_racer), which provide ECMAScript but not WHATWG host APIs.
+//
+// Strict on purpose: real TextDecoder throws on non-buffer input rather
+// than coercing it. A shim that coerces turns loud failures into silent
+// ones — decode("a string") must throw, not return empty output.
+(function (global) {
+  "use strict";
+
+  function toUint8Array(input) {
+    if (input instanceof Uint8Array) {
+      return input;
+    }
+    if (input instanceof ArrayBuffer) {
+      return new Uint8Array(input);
+    }
+    if (ArrayBuffer.isView(input)) {
+      return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    }
+    throw new TypeError(
+      "Failed to execute 'decode': The provided value is not of type " +
+        "'(ArrayBuffer or ArrayBufferView)'"
+    );
+  }
+
+  class TextDecoder {
+    constructor(encoding) {
+      if (encoding !== undefined && encoding !== "utf-8" && encoding !== "utf8") {
+        throw new RangeError("TextDecoder only supports utf-8");
+      }
+      this.encoding = "utf-8";
+    }
+
+    decode(input) {
+      const bytes = toUint8Array(input);
+      let result = "";
+      let i = 0;
+
+      while (i < bytes.length) {
+        const byte1 = bytes[i];
+        let codePoint;
+        let extraBytes;
+
+        if (byte1 < 0x80) {
+          codePoint = byte1;
+          extraBytes = 0;
+        } else if ((byte1 & 0xe0) === 0xc0) {
+          codePoint = byte1 & 0x1f;
+          extraBytes = 1;
+        } else if ((byte1 & 0xf0) === 0xe0) {
+          codePoint = byte1 & 0x0f;
+          extraBytes = 2;
+        } else if ((byte1 & 0xf8) === 0xf0) {
+          codePoint = byte1 & 0x07;
+          extraBytes = 3;
+        } else {
+          throw new TypeError("Invalid UTF-8 byte sequence");
+        }
+
+        for (let j = 0; j < extraBytes; j++) {
+          i++;
+          const nextByte = bytes[i];
+          if (nextByte === undefined || (nextByte & 0xc0) !== 0x80) {
+            throw new TypeError("Invalid UTF-8 continuation byte");
+          }
+          codePoint = (codePoint << 6) | (nextByte & 0x3f);
+        }
+
+        if (codePoint > 0xffff) {
+          codePoint -= 0x10000;
+          result += String.fromCharCode(
+            0xd800 + (codePoint >> 10),
+            0xdc00 + (codePoint & 0x3ff)
+          );
+        } else {
+          result += String.fromCharCode(codePoint);
+        }
+
+        i++;
+      }
+
+      return result;
+    }
+  }
+
+  class TextEncoder {
+    constructor() {
+      this.encoding = "utf-8";
+    }
+
+    encode(input) {
+      if (typeof input !== "string") {
+        throw new TypeError(
+          "Failed to execute 'encode': parameter 1 is not of type 'string'."
+        );
+      }
+
+      const bytes = [];
+
+      for (let i = 0; i < input.length; i++) {
+        let codePoint = input.charCodeAt(i);
+
+        if (codePoint >= 0xd800 && codePoint <= 0xdbff && i + 1 < input.length) {
+          const next = input.charCodeAt(i + 1);
+          if (next >= 0xdc00 && next <= 0xdfff) {
+            codePoint = (codePoint - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
+            i++;
+          }
+        }
+
+        if (codePoint < 0x80) {
+          bytes.push(codePoint);
+        } else if (codePoint < 0x800) {
+          bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+        } else if (codePoint < 0x10000) {
+          bytes.push(
+            0xe0 | (codePoint >> 12),
+            0x80 | ((codePoint >> 6) & 0x3f),
+            0x80 | (codePoint & 0x3f)
+          );
+        } else {
+          bytes.push(
+            0xf0 | (codePoint >> 18),
+            0x80 | ((codePoint >> 12) & 0x3f),
+            0x80 | ((codePoint >> 6) & 0x3f),
+            0x80 | (codePoint & 0x3f)
+          );
+        }
+      }
+
+      return new Uint8Array(bytes);
+    }
+  }
+
+  global.TextDecoder = TextDecoder;
+  global.TextEncoder = TextEncoder;
+})(typeof globalThis !== "undefined" ? globalThis : this);

data/js/ruby_backend.js

@@ -0,0 +1,204 @@
+// Wires the vendored @herb-tools/linter bundle to Ruby. Must load after
+// vendor/herb-linter.js and after the six rbXxx callbacks below are
+// attached (Bridge#boot handles the ordering).
+//
+// HerbBackend (from @herb-tools/core) must be subclassed: its `version`
+// getter calls the abstract backendVersion(), which the base class
+// doesn't implement. Instantiating HerbBackend directly fails.
+var libHerbBackend = {
+  parse: function (source, options) {
+    return JSON.parse(rbParse(source, options));
+  },
+  lex: function (source) {
+    return JSON.parse(rbLex(source));
+  },
+  extractRuby: function (source, options) {
+    return rbExtractRuby(source, options);
+  },
+  extractHTML: function (source) {
+    return rbExtractHTML(source);
+  },
+  parseRuby: function (source) {
+    return rbParseRuby(source);
+  },
+  version: function () {
+    return rbVersion();
+  },
+  diff: function () {
+    throw new Error("diff is not implemented by the Ruby backend");
+  },
+};
+
+// rbParse (via ResultEnvelope#inject_prism_nodes) injects prism_node bytes
+// produced by Ruby's Prism.dump, which always serializes a whole
+// ProgramNode — there is no public API to dump an arbitrary sub-node
+// directly. But every prism_nodes-dependent rule (see CHARTER.md) expects
+// an ERB*Node's prismNode to BE the single embedded-Ruby expression node
+// itself (e.g. isAssignmentNode checks prismNode.constructor.name), not a
+// Program wrapping it. Unwrap here, once, for every ERB node class that
+// defines the prismNode getter, rather than patching the vendored bundle.
+// Only unwraps when the parse yielded exactly one top-level statement —
+// the case single-tag Ruby content always produces — leaving anything
+// else (multiple ';'-separated statements in one tag) as the ProgramNode,
+// same as an unhandled edge case would fall back to.
+Object.keys(HerbLinter).forEach(function (name) {
+  if (!/^ERB.*Node$/.test(name)) return;
+
+  var proto = HerbLinter[name] && HerbLinter[name].prototype;
+  var descriptor = proto && Object.getOwnPropertyDescriptor(proto, "prismNode");
+  if (!descriptor || typeof descriptor.get !== "function") return;
+
+  var originalGet = descriptor.get;
+
+  Object.defineProperty(proto, "prismNode", {
+    configurable: true,
+    enumerable: descriptor.enumerable,
+    get: function () {
+      var raw = originalGet.call(this);
+      var body = raw && raw.constructor && raw.constructor.name === "ProgramNode" && raw.statements && raw.statements.body;
+
+      return body && body.length === 1 ? body[0] : raw;
+    },
+  });
+});
+
+class RubyBackend extends HerbLinter.HerbBackend {
+  backendVersion() {
+    return "mini_racer";
+  }
+}
+
+// A Promise returned directly from a Ruby<->JS call marshals to Ruby as
+// {} — mini_racer doesn't drive V8's microtask queue on its own timeline,
+// only between separate eval/call invocations. So boot is a two-step
+// handshake: this call kicks off the async load without awaiting it;
+// Bridge#boot observes __herbEmbeddedBridge.ready in a second, separate
+// call, by which point the microtask queue has drained and the promise
+// has resolved.
+var __herbEmbeddedBridge = {
+  instance: new RubyBackend(function () {
+    return Promise.resolve(libHerbBackend);
+  }),
+  ready: false,
+  error: null,
+};
+
+__herbEmbeddedBridge.instance
+  .load()
+  .then(function () {
+    __herbEmbeddedBridge.ready = true;
+  })
+  .catch(function (e) {
+    __herbEmbeddedBridge.error = String(e && e.message ? e.message : e);
+  });
+
+function __herbRuleNames() {
+  return HerbLinter.rules.map(function (ruleClass) {
+    return ruleClass.ruleName;
+  });
+}
+
+// Rule selection happens before execution: Linter's constructor takes an
+// explicit rules array, so an unselected rule is never instantiated or
+// checked, not merely filtered out of the offenses it already produced.
+// With no explicit selection, match upstream's own default: only rules
+// enabled by their own defaultConfig (Linter.filterRulesByConfig with no
+// user config still filters on that), not every available rule class.
+// An explicit selection bypasses that filtering entirely — matching
+// --only's real semantics — so a caller can still opt into a
+// not-enabled-by-default rule by naming it.
+function __herbSelectRules(ruleNames) {
+  var wanted = ruleNames && ruleNames.length ? ruleNames : null;
+
+  if (!wanted) {
+    return HerbLinter.Linter.filterRulesByConfig(HerbLinter.rules).enabled;
+  }
+
+  return HerbLinter.rules.filter(function (ruleClass) {
+    return wanted.indexOf(ruleClass.ruleName) !== -1;
+  });
+}
+
+// Registers a custom rule from Ruby-rewritten source (see
+// CustomRuleLoader.rewrite): an IIFE expression that destructures its
+// base class from HerbLinter and returns the rule class. A rule sharing
+// a ruleName with an existing one (built-in or previously-registered
+// custom) replaces it in place, matching upstream's override behavior —
+// the caller (CustomRuleLoader#load_all) is told via `overrode` so it can
+// warn on the Ruby side.
+function __herbRegisterCustomRule(rewrittenSource, path) {
+  var RuleClass;
+
+  try {
+    RuleClass = eval(rewrittenSource);
+  } catch (e) {
+    throw new Error("Failed to evaluate custom rule at " + path + ": " + (e && e.message ? e.message : String(e)));
+  }
+
+  if (!RuleClass || typeof RuleClass !== "function" || typeof RuleClass.ruleName !== "string" || typeof RuleClass.prototype.check !== "function") {
+    throw new Error("No valid default export found in " + path + ". Custom rules must use default export.");
+  }
+
+  var existingIndex = HerbLinter.rules.findIndex(function (ruleClass) {
+    return ruleClass.ruleName === RuleClass.ruleName;
+  });
+  var overrode = existingIndex !== -1;
+
+  if (overrode) {
+    HerbLinter.rules.splice(existingIndex, 1, RuleClass);
+  } else {
+    HerbLinter.rules.push(RuleClass);
+  }
+
+  return { ruleName: RuleClass.ruleName, overrode: overrode };
+}
+
+// A single Linter across all selected rules, matching upstream's own
+// lint-then-fix composition (Linter#autofix mutates a running source as
+// it walks offenses from every selected rule together, unlike #lint's
+// per-rule crash isolation). The parse-doesn't-break safety check lives
+// on the Ruby side (Bridge#autofix), since it just needs Herb.parse.
+function __herbAutofix(source, file, ruleNames, includeUnsafe) {
+  var ruleClasses = __herbSelectRules(ruleNames);
+  var context = { fileName: file, filename: file };
+  var linter = new HerbLinter.Linter(__herbEmbeddedBridge.instance, ruleClasses, undefined, HerbLinter.rules);
+  var result = linter.autofix(source, context, undefined, { includeUnsafe: !!includeUnsafe });
+
+  return JSON.stringify({ source: result.source, fixed: result.fixed });
+}
+
+// One Linter per selected rule, each in its own try/catch: a rule that
+// throws must not abort the run (spike 2 finding) — the real Linter#lint
+// has no such isolation internally, since it runs every selected rule's
+// check() in one uncaught loop.
+//
+// The 4th constructor arg (allAvailableRules) must be the full registry,
+// not just the one rule being run: herb-disable-comment-unnecessary reads
+// context.validRuleNames (built from Linter#getAvailableRules, which
+// falls back to allAvailableRules) to decide whether a `herb:disable
+// some-other-rule` comment references a real rule — omitting this arg
+// left validRuleNames scoped to whatever single rule __herbLint happened
+// to be running, so the rule silently never matched anything outside
+// itself. Caught by conformance fixture coverage (herb-embedded-ag7).
+function __herbLint(source, file, ruleNames) {
+  var ruleClasses = __herbSelectRules(ruleNames);
+  var context = { fileName: file, filename: file };
+  var offenses = [];
+
+  ruleClasses.forEach(function (ruleClass) {
+    try {
+      var linter = new HerbLinter.Linter(__herbEmbeddedBridge.instance, [ruleClass], undefined, HerbLinter.rules);
+      var result = linter.lint(source, context);
+      offenses = offenses.concat(result.offenses);
+    } catch (e) {
+      offenses.push({
+        rule: ruleClass.ruleName,
+        message: "Rule '" + ruleClass.ruleName + "' crashed: " + (e && e.message ? e.message : String(e)),
+        severity: "error",
+        location: null,
+      });
+    }
+  });
+
+  return JSON.stringify(offenses);
+}

data/lib/herb/embedded/adapters/mini_racer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mini_racer"
+require_relative "../engine_adapter"
+
+module Herb
+  module Embedded
+    module Adapters
+      # Reference EngineAdapter backed by mini_racer (bundled V8).
+      class MiniRacer < EngineAdapter
+        def initialize
+          super
+          @context = ::MiniRacer::Context.new
+        end
+
+        def load(source)
+          @context.eval(source)
+          self
+        end
+
+        def attach(name, &block)
+          wrapped = proc do |*args|
+            result = block.call(*args)
+            result.is_a?(Binary) ? ::MiniRacer::Binary.new(result.raw) : result
+          end
+          @context.attach(name, wrapped)
+          self
+        end
+
+        def call(function, *args)
+          converted = args.map { |arg| arg.is_a?(Binary) ? arg.raw.bytes : arg }
+          @context.call(function, *converted)
+        end
+
+        def dispose
+          @context.dispose
+        end
+      end
+    end
+  end
+end

data/lib/herb/embedded/bridge.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "prism"
+require_relative "../embedded"
+require_relative "engine_adapter"
+require_relative "result_envelope"
+require_relative "diagnostic"
+
+module Herb
+  module Embedded
+    # Boots the JS engine: loads the host shim and vendored bundle,
+    # attaches the six Ruby callbacks HerbBackend needs, then loads the
+    # RubyBackend subclass and waits for its async init to resolve.
+    class Bridge
+      # Rescuing Herb::Embedded::Error catches any of these without also
+      # catching unrelated bugs.
+      class VersionMismatchError < Error; end
+      class NotBootedError < Error; end
+      class BootError < Error; end
+
+      HOST_SHIM_PATH = File.expand_path("../../../js/host_shim.js", __dir__)
+      RUBY_BACKEND_PATH = File.expand_path("../../../js/ruby_backend.js", __dir__)
+
+      READY_CHECK_JS = <<~JS
+        function __herbEmbeddedReady() { return __herbEmbeddedBridge.ready; }
+        function __herbEmbeddedError() { return __herbEmbeddedBridge.error; }
+        function __herbEmbeddedVersion() { return __herbEmbeddedBridge.instance.version; }
+      JS
+
+      def initialize(adapter:, bundle:)
+        @adapter = adapter
+        @bundle = bundle
+        @booted = false
+      end
+
+      def boot
+        # Herb is pre-1.0: the major version never moves (0.8 -> 0.9 -> 0.10
+        # are all "0"), so semver-range gating can't distinguish a validated
+        # version from an unvalidated one. Gate on the recorded set instead.
+        unless @bundle.herb_versions.include?(::Herb::VERSION)
+          raise VersionMismatchError,
+                "herb #{::Herb::VERSION} has not been validated against this bundle " \
+                "(validated versions: #{@bundle.herb_versions.join(", ")})"
+        end
+
+        @adapter.load(File.read(HOST_SHIM_PATH))
+        @adapter.load(@bundle.source)
+        attach_callbacks
+        @adapter.load(File.read(RUBY_BACKEND_PATH))
+        @adapter.load(READY_CHECK_JS)
+
+        unless @adapter.call("__herbEmbeddedReady")
+          raise BootError, "Bridge failed to boot: #{@adapter.call("__herbEmbeddedError")}"
+        end
+
+        @booted = true
+        self
+      end
+
+      def backend_version
+        ensure_booted!
+        @adapter.call("__herbEmbeddedVersion")
+      end
+
+      def rule_names
+        ensure_booted!
+        @adapter.call("__herbRuleNames")
+      end
+
+      def lint(source, file:, rules: nil)
+        ensure_booted!
+        offenses = JSON.parse(@adapter.call("__herbLint", source, file, rules))
+        offenses.map { |offense| Diagnostic.from_js(offense, file: file) }
+      end
+
+      def register_custom_rule(source, path)
+        ensure_booted!
+        @adapter.call("__herbRegisterCustomRule", source, path)
+      end
+
+      # A formatter-adjacent tool must never write source that fails to
+      # parse into a user's working tree. If the fixed output fails to
+      # parse while the original input parsed cleanly, the fix is
+      # discarded rather than trusted.
+      def autofix(source, file:, rules: nil, unsafe: false)
+        ensure_booted!
+        raw = JSON.parse(@adapter.call("__herbAutofix", source, file, rules, unsafe))
+
+        if source_parses?(source) && !source_parses?(raw["source"])
+          return { source: source, applied: [], discarded: true }
+        end
+
+        applied = raw["fixed"].map { |offense| Diagnostic.from_js(offense, file: file) }
+        { source: raw["source"], applied: applied, discarded: false }
+      end
+
+      def dispose
+        @adapter.dispose
+      end
+
+      private
+
+      def ensure_booted!
+        raise NotBootedError, "Bridge#boot must be called before this method" unless @booted
+      end
+
+      def attach_callbacks
+        @adapter.attach("rbParse") { |source, options| ResultEnvelope.parse(source, options || {}) }
+        @adapter.attach("rbLex") { |source| ResultEnvelope.lex(source) }
+        @adapter.attach("rbExtractRuby") { |source, options| ::Herb.extract_ruby(source, **symbolize(options)) }
+        @adapter.attach("rbExtractHTML") { |source| ::Herb.extract_html(source) }
+        @adapter.attach("rbParseRuby") { |source| EngineAdapter.binary(::Prism.dump(source)) }
+        @adapter.attach("rbVersion") { ::Herb.version }
+      end
+
+      def symbolize(hash)
+        (hash || {}).transform_keys(&:to_sym)
+      end
+
+      def source_parses?(source)
+        JSON.parse(ResultEnvelope.parse(source, {}))["errors"].empty?
+      end
+    end
+  end
+end

data/lib/herb/embedded/bundle.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Herb
+  module Embedded
+    # The vendored @herb-tools/linter JS bundle (see rakelib/bundle.rake).
+    module Bundle
+      LINTER_VERSION = "0.10.3"
+      HERB_VERSIONS = ["0.10.3"].freeze
+
+      VENDOR_PATH = File.expand_path("../../../vendor/herb-linter.js", __dir__)
+
+      module_function
+
+      def source
+        File.read(VENDOR_PATH)
+      end
+
+      def linter_version
+        LINTER_VERSION
+      end
+
+      def herb_versions
+        HERB_VERSIONS
+      end
+    end
+  end
+end