factory_bot_instrumentation 2.9.0 → 3.0.0

data/lib/factory_bot/instrumentation/asset_bundler.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module FactoryBot
+  module Instrumentation
+    # A tiny, dependency-free replacement for Sprockets' +require_tree+
+    # directive. It concatenates the JavaScript or CSS sources shipped
+    # with this engine into a single +application.{js,css}+ asset so
+    # that the engine no longer needs an asset pipeline at runtime.
+    #
+    # The bundles are regenerated in two situations:
+    #
+    # * During gem release, via the +bundle_assets+ Rake task which is
+    #   hooked into +rake build+.
+    # * On +gem install+ / +bundle install+ (including Git source installs
+    #   in third-party applications), via the RubyGems extension shim at
+    #   +ext/factory_bot_instrumentation/extconf.rb+.
+    module AssetBundler
+      module_function
+
+      # Absolute path to the gem root (where the +app+ and +lib+ folders
+      # live), derived from this file's location.
+      ROOT_DIR = File.expand_path('../../..', __dir__)
+
+      # Per-kind configuration. Each entry describes where the sources
+      # live, which extension to bundle, where to write the manifest and
+      # how to format the comments wrapping each chunk.
+      KINDS = {
+        js: {
+          source_dir: File.join(
+            ROOT_DIR, 'app', 'assets', 'javascripts',
+            'factory_bot_instrumentation'
+          ),
+          output_name: 'application.js',
+          extension: 'js',
+          line_comment: '// %s',
+          banner_format: :line
+        },
+        css: {
+          source_dir: File.join(
+            ROOT_DIR, 'app', 'assets', 'stylesheets',
+            'factory_bot_instrumentation'
+          ),
+          output_name: 'application.css',
+          extension: 'css',
+          line_comment: '/* %s */',
+          banner_format: :block
+        }
+      }.freeze
+
+      # Plain-text banner content, formatted per kind by +banner+. The
+      # +%<kind>s+ and +%<source_rel>s+ placeholders are interpolated at
+      # render time via +format+.
+      BANNER_TEMPLATE = <<~TEXT
+        !!! AUTO-GENERATED FILE - DO NOT EDIT !!!
+
+        This file bundles every %<kind>s source under
+        +%<source_rel>s/+ into a single asset. It is regenerated:
+          * on `gem install` / `bundle install` (via a RubyGems extension
+            hook), and
+          * during gem release (via the `bundle_assets` Rake task).
+
+        To rebuild it manually, run:
+
+          $ bundle exec rake bundle_assets
+      TEXT
+
+      # All asset kinds known to the bundler.
+      #
+      # @return [Array<Symbol>] the registered kind identifiers
+      def kinds
+        KINDS.keys
+      end
+
+      # Build the bundle for the given +kind+ and write it to the
+      # corresponding manifest. The manifest itself is excluded from the
+      # input set so that re-runs are idempotent.
+      #
+      # @param kind [Symbol] one of +:js+ or +:css+
+      # @return [Array<String>] absolute paths of the source files that
+      #   were concatenated, in the order they appear in the output
+      # @raise [ArgumentError] if +kind+ is not a known asset kind
+      def bundle!(kind)
+        conf = config(kind)
+        files = sources(kind)
+        File.write(
+          File.join(conf[:source_dir], conf[:output_name]),
+          banner(kind) + files.map { |f| chunk(kind, f) }.join
+        )
+        files
+      end
+
+      # Build every known asset kind in turn.
+      #
+      # @return [Hash{Symbol => Array<String>}] a mapping of kind to the
+      #   absolute paths of the source files that were concatenated for
+      #   that kind
+      #
+      # rubocop:disable Rails/IndexWith -- because we're
+      #   dependency-free in here
+      def bundle_all!
+        kinds.to_h { |kind| [kind, bundle!(kind)] }
+      end
+      # rubocop:enable Rails/IndexWith
+
+      # All sources to include for +kind+, sorted so the result is
+      # stable across platforms and filesystems. The manifest itself is
+      # excluded to avoid recursive inclusion.
+      #
+      # @param kind [Symbol] one of +:js+ or +:css+
+      # @return [Array<String>] absolute paths of the matching source
+      #   files, sorted ascending
+      # @raise [ArgumentError] if +kind+ is not a known asset kind
+      def sources(kind)
+        conf = config(kind)
+        output = File.expand_path(File.join(conf[:source_dir],
+                                            conf[:output_name]))
+        Dir.glob(File.join(conf[:source_dir], '**', "*.#{conf[:extension]}"))
+           .reject { |path| File.expand_path(path) == output }
+           .sort
+      end
+
+      # Look up the configuration for +kind+, raising on unknown values.
+      #
+      # @param kind [Symbol] the kind identifier to look up
+      # @return [Hash] the configuration entry from +KINDS+, with keys
+      #   +:source_dir+, +:output_name+, +:extension+, +:line_comment+
+      #   and +:banner_format+
+      # @raise [ArgumentError] if +kind+ is not a known asset kind
+      def config(kind)
+        KINDS.fetch(kind) do
+          raise ArgumentError,
+                "Unknown asset kind #{kind.inspect}; expected one of " \
+                "#{KINDS.keys.inspect}"
+        end
+      end
+
+      # Path of +file+ relative to its kind's source directory, used in
+      # the per-chunk comment marker so the bundled output remains
+      # debuggable.
+      #
+      # @param kind [Symbol] one of +:js+ or +:css+
+      # @param file [String] the absolute path of a source file
+      # @return [String] +file+ stripped of the kind's source directory
+      #   prefix
+      def relative_source(kind, file)
+        file.sub("#{config(kind)[:source_dir]}/", '')
+      end
+
+      # Wrap a single source file with a comment that names its relative
+      # path. The returned snippet starts with a newline so that chunks
+      # concatenate cleanly under the banner.
+      #
+      # @param kind [Symbol] one of +:js+ or +:css+
+      # @param path [String] the absolute path of the source file to
+      #   wrap
+      # @return [String] the comment-wrapped source contents
+      def chunk(kind, path)
+        conf = config(kind)
+        body = File.read(path)
+        body += "\n" unless body.end_with?("\n")
+        marker = format(conf[:line_comment],
+                        ">>> #{relative_source(kind, path)}")
+        "\n#{marker}\n#{body}"
+      end
+
+      # Render the auto-generation banner in the comment style of +kind+.
+      # JavaScript bundles get line comments (+// ...+), CSS bundles get
+      # a single block comment (+/* ... */+).
+      #
+      # @param kind [Symbol] one of +:js+ or +:css+
+      # @return [String] the banner ready to be prepended to the bundle,
+      #   including the trailing newline
+      def banner(kind)
+        conf = config(kind)
+        text = format(
+          BANNER_TEMPLATE,
+          kind: conf[:extension].upcase,
+          source_rel: conf[:source_dir].sub("#{ROOT_DIR}/", '')
+        )
+
+        case conf[:banner_format]
+        when :line
+          lines = text.each_line
+                      .map { |l| format(conf[:line_comment], l.chomp).rstrip }
+                      .join("\n")
+          "#{lines}\n"
+        when :block
+          body = text.each_line.map { |l| " * #{l.chomp}".rstrip }.join("\n")
+          "/*\n#{body}\n */\n"
+        end
+      end
+    end
+  end
+end

data/lib/factory_bot/instrumentation/engine.rb

@@ -38,6 +38,30 @@ module FactoryBot
       paths['app/views'].push(
         app_path.join('views/factory_bot/instrumentation').to_s
       )
+
+      # Register the engine's assets with the host application's Sprockets
+      # precompile list so they are picked up by +rake assets:precompile+.
+      # The Sprockets 4+ syntax expects bare logical paths, while older
+      # versions need a +proc+ matcher - we handle both.
+      initializer 'factory_bot_instrumentation.assets', group: :all do |app|
+        if app.config.respond_to?(:assets) && defined?(Sprockets)
+          sprockets_4_or_later =
+            Gem::Version.new(Sprockets::VERSION) >= Gem::Version.new('4')
+
+          %w[
+            factory_bot_instrumentation/application.js
+            factory_bot_instrumentation/application.css
+          ].each do |asset_path|
+            app.config.assets.precompile << (
+              if sprockets_4_or_later
+                asset_path
+              else
+                proc { |path| path == asset_path }
+              end
+            )
+          end
+        end
+      end
     end
   end
 end

data/lib/factory_bot/instrumentation/version.rb

@@ -4,7 +4,7 @@ module FactoryBot
   # The gem version details.
   module Instrumentation
     # The version of the +factory_bot_instrumentation+ gem
-    VERSION = '2.9.0'
+    VERSION = '3.0.0'
 
     class << self
       # Returns the version of gem as a string.

data/lib/factory_bot/instrumentation.rb

@@ -19,6 +19,9 @@ module FactoryBot
     # Setup a Zeitwerk autoloader instance and configure it
     loader = Zeitwerk::Loader.for_gem_extension(FactoryBot)
 
+    # Do not auto load some parts of the gem
+    loader.ignore("#{__dir__}/instrumentation/asset_bundler.rb")
+
     # Finish the auto loader configuration
     loader.setup
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factory_bot_instrumentation
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Hermann Mayer
@@ -105,12 +105,7 @@ files:
 - Makefile
 - README.md
 - Rakefile
-- app/assets/config/factory_bot_instrumentation_manifest.js
 - app/assets/javascripts/factory_bot_instrumentation/application.js
-- app/assets/javascripts/factory_bot_instrumentation/create.js
-- app/assets/javascripts/factory_bot_instrumentation/hooks.js
-- app/assets/javascripts/factory_bot_instrumentation/lib/form.js
-- app/assets/javascripts/factory_bot_instrumentation/lib/utils.js
 - app/assets/stylesheets/factory_bot_instrumentation/application.css
 - app/controllers/factory_bot/instrumentation/application_controller.rb
 - app/controllers/factory_bot/instrumentation/root_controller.rb
@@ -139,6 +134,7 @@ files:
 - factory_bot_instrumentation.gemspec
 - gemfiles/rails_8.1.gemfile
 - lib/factory_bot/instrumentation.rb
+- lib/factory_bot/instrumentation/asset_bundler.rb
 - lib/factory_bot/instrumentation/configuration.rb
 - lib/factory_bot/instrumentation/engine.rb
 - lib/factory_bot/instrumentation/version.rb

data/app/assets/config/factory_bot_instrumentation_manifest.js

@@ -1,2 +0,0 @@
-//= link_directory ../javascripts/factory_bot_instrumentation .js
-//= link_directory ../stylesheets/factory_bot_instrumentation .css

data/app/assets/javascripts/factory_bot_instrumentation/create.js

@@ -1,134 +0,0 @@
-window.CreateForm = CreateForm = function()
-{
-  this.scope = '#generate';
-  this.form = new Form(this.scope);
-  this.scenarios = window.scenarios;
-  this.select = $(`${this.scope} .scenario`);
-  this.desc = $(`${this.scope} .description`);
-
-  let self = this;
-
-  this.form.errorContent = function(payload, output, cb)
-  {
-    window.utils.waterfallWithHooks({
-      data: {
-        alert: `An unexpected error occurred. Looks like something went wrong
-                while generating your new entity. This might be a bug, or an
-                unexpected feature. It could be a temporary issue. When this
-                is persistent contact your friendly API Instrumentation
-                administrator.`,
-        output: output,
-        payload: payload,
-        pre: '',
-        post: ''
-      },
-      pre: window.hooks.preCreateError,
-      post: window.hooks.postCreateError,
-      action: (payload, innerCb) => {
-        cb(null, `
-          ${payload.pre}
-          <div class="alert alert-danger" role="alert">${payload.alert}</div>
-          <pre id="data">${payload.output}</pre>
-          ${window.utils.clipboardButton()}
-          ${payload.post}
-        `);
-        innerCb(null, payload);
-      }
-    });
-  };
-
-  this.form.resultContent = function(payload, output, cb)
-  {
-    let card = window.utils.card({
-      body: `
-        <pre id="data">${output}</pre>
-        ${window.utils.clipboardButton()}
-      `
-    });
-
-    window.utils.waterfallWithHooks({
-      data: {
-        alert: `A new ${self.scenario().name.toLowerCase()} was created.`,
-        output: output,
-        payload: payload,
-        cards: [card],
-        pre: '',
-        post: '',
-        openCard: '#details'
-      },
-      pre: window.hooks.preCreateResult,
-      post: window.hooks.postCreateResult,
-      action: (payload, innerCb) => {
-        cb(null, `
-          ${payload.pre}
-          <div class="alert alert-success" role="alert">${payload.alert}</div>
-          <div class="accordion" id="response">
-            ${payload.cards.join(' ')}
-          </div>
-          ${payload.post}
-        `);
-        innerCb(null, payload);
-        if (payload.openCard) {
-          $(
-            `.accordion#response button[data-target="${payload.openCard}"]`
-          ).click();
-        }
-      }
-    });
-  };
-};
-
-CreateForm.prototype.updateDesc = function()
-{
-  this.desc.html(this.scenario().desc);
-};
-
-CreateForm.prototype.activeScenario = function()
-{
-  raw = this.select.find(':selected').val().split('/');
-  return { group: raw[0], index: raw[1] };
-};
-
-CreateForm.prototype.scenario = function()
-{
-  scenario = this.activeScenario();
-  return this.scenarios[scenario.group][scenario.index];
-};
-
-CreateForm.prototype.bind = function()
-{
-  this.form.bind((event) => {
-    this.submit();
-  });
-
-  this.select.on('change', this.updateDesc.bind(this));
-  this.updateDesc();
-};
-
-CreateForm.prototype.submit = function()
-{
-  let form = this.form;
-  let conf = this.scenario();
-
-  window.utils.waterfallWithHooks({
-    data: {
-      factory: conf.factory,
-      traits: conf.traits,
-      overwrite: conf.overwrite
-    },
-    pre: window.hooks.preCreate,
-    post: window.hooks.postCreate,
-    action: (payload, cb) => {
-      window.utils.request({
-        url: window.createUrl,
-        data: JSON.stringify(payload)
-      }, (err, result) => {
-        if (err) { return cb && cb(err); }
-        cb(null, { request: payload, response: result });
-      });
-    }
-  }, function(err, result) {
-    if (err) { return form.showError(err, err.responseText); }
-    form.showResult(result, result.response);
-  });
-};

data/app/assets/javascripts/factory_bot_instrumentation/hooks.js

@@ -1,123 +0,0 @@
-// You can define some custom hooks to enhance the functionality. With the help
-// of the following hooks you are able to customize the outputs, perform
-// additional HTTP requests or anything you like.
-//
-// All the hooks are designed to passthrough a payload. They receive this
-// payload as the first argument, and a callback function to signal the end of
-// the hook. You MUST pass the payload as second parameter to the callback, or
-// pass an error object as first argument. You can modify the payload as you
-// wish, eg. adding some data from subsequent requests.
-//
-// Example hooks:
-//
-//   // Error case
-//   window.hooks.postCreate.push((payload, cb) => {
-//     cb({ error: true});
-//   });
-//
-//   // Happy case
-//   window.hooks.postCreate.push((payload, cb) => {
-//     cb(null, Object.assign(payload, { additional: { data: true } }));
-//   });
-//
-// Mind the fact that you can define multiple custom functions per hook type.
-// They are executed after each other in a waterfall like flow. The order of
-// the hooks array is therefore essential.
-window.hooks = {
-  // With the help of the +perCreate+ hooks you can manipulate the create
-  // request parameters. Think of an additional handling which reads an
-  // overwrite form or a kind of trait checkboxes to customize the factory
-  // call. The +payload+ looks like this:
-  //
-  //   {
-  //     factory: 'user',
-  //     traits: ['confirmed'],
-  //     overwrite: { password: 'secret' }
-  //   }
-  preCreate: [],
-
-  // The +postCreate+ hook allows you to perform subsequent requests to fetch
-  // additional data. Think of a user instrumentation where you want to request
-  // a one time token for this user. This token can be added to the payload and
-  // can be shown with the help of the +preCreateResult+ hook. The payload
-  // contains the request parameters and the response body from the
-  // instrumentation request. Here comes an example +payload+:
-  //
-  //   {
-  //     request: { factory: 'user', /* [..] */ },
-  //     response: { /* [..] */ }
-  //   }
-  postCreate: [],
-
-  // With the help of the +preCreateResult+ hook you can customize the output
-  // of the result. You could also perform some subsequent requests or some UI
-  // preparations. You can access the output options and the runtime payload
-  // with all its data and make modifications to them. This hook is triggered
-  // before the result is rendered. A sample payload comes here:
-  //
-  //   {
-  //     alert: 'Your alert text.',
-  //     output: 'Formatted response',
-  //     payload: { request: { /* [..] */ }, response: { /* [..] */ } },
-  //     cards: [
-  //       `The details accordion card,
-  //        you can add more, remove the details card
-  //        or reorder them`
-  //     ],
-  //     openCard: '#details', // Open a custom card, or none
-  //     pre: 'Additinal HTML content before the alert.',
-  //     post: 'Additinal HTML content after the formatted response output.'
-  //   }
-  preCreateResult: [],
-
-  // In case you want to perform some logic after the result is rendered, you
-  // can use the +postCreateResult+ hook. You can access the output options and
-  // the runtime payload with all its data, but changes to them won't take
-  // effect. The +payload+ looks like this:
-  //
-  //   {
-  //     alert: 'Your alert text.',
-  //     output: 'Formatted response',
-  //     payload: { request: { /* [..] */ }, response: { /* [..] */ } },
-  //     cards: [
-  //       `The details accordion card,
-  //        you can add more, remove the details card
-  //        or reorder them`
-  //     ],
-  //     openCard: '#details', // Open a custom card, or none
-  //     pre: 'Additinal HTML content before the alert.',
-  //     post: 'Additinal HTML content after the formatted response output.'
-  //   }
-  postCreateResult: [],
-
-  // With the help of the +preCreateError+ hook you can customize the output of
-  // the error. Furthermore you can perform some subsequent requests or
-  // whatever comes to your mind. You can access the output options and the
-  // runtime payload with all its data and make modifications to them. This
-  // hook is triggered before the error is rendered. A sample payload comes
-  // here:
-  //
-  //   {
-  //     alert: 'Your alert text.',
-  //     output: 'Formatted response',
-  //     payload: { request: { /* [..] */ }, response: { /* [..] */ } },
-  //     pre: 'Additinal HTML content before the alert.',
-  //     post: 'Additinal HTML content after the formatted response output.'
-  //   }
-  preCreateError: [],
-
-  // In case you want to perform some magic after an error occurred, you can use
-  // the +postCreateError+ hook. You can access the output options and the
-  // runtime payload with all its data, but changes to them won't take effect
-  // because this hook is triggered after the error is rendered. The +payload+
-  // looks like this:
-  //
-  //   {
-  //     alert: 'Your alert text.',
-  //     output: 'Formatted response',
-  //     payload: { request: { /* [..] */ }, response: { /* [..] */ } },
-  //     pre: 'Additinal HTML content before the alert.',
-  //     post: 'Additinal HTML content after the formatted response output.'
-  //   }
-  postCreateError: []
-};

data/app/assets/javascripts/factory_bot_instrumentation/lib/form.js

@@ -1,66 +0,0 @@
-window.Form = Form = function(scope)
-{
-  this.button = $(scope).find('button');
-  this.result = $('#result');
-  this.spinner = $('#spinner');
-};
-
-Form.prototype.bind = function(action)
-{
-  this.button.on('click', (event) => {
-    event.preventDefault();
-    this.hideResult();
-    action(event);
-    return false;
-  });
-};
-
-Form.prototype.hideResult = function()
-{
-  this.result.hide();
-  this.button.prop('disabled', true);
-  this.spinner.show();
-};
-
-Form.prototype.showResultContainer = function(html)
-{
-  this.result.html(html);
-  $('pre').each((i, block) => hljs.highlightBlock(block));
-  new ClipboardJS('.cb-copy');
-  this.result.show();
-  this.button.prop('disabled', false);
-};
-
-Form.prototype.showError = function(payload, output)
-{
-  this.spinner.hide();
-  output = window.utils.prepareOutput(output);
-  this.errorContent(payload, output, (err, html) => {
-    this.showResultContainer(html);
-  });
-};
-
-Form.prototype.errorContent = function(payload, output, cb)
-{
-  cb(null, `
-    <pre id="data">${output}</pre>
-    ${window.utils.clipboardButton()}
-  `);
-};
-
-Form.prototype.showResult = function(payload, output)
-{
-  this.spinner.hide();
-  output = window.utils.prepareOutput(output);
-  this.resultContent(payload, output, (err, html) => {
-    this.showResultContainer(html);
-  });
-};
-
-Form.prototype.resultContent = function(payload, output, cb)
-{
-  cb(null, `
-    <pre id="data">${output}</pre>
-    ${window.utils.clipboardButton()}
-  `);
-};