Start using Yarn to manage JavaScript dependencies (#1824)

* Start using `yarn` for vendor assets

Until this commit, Gollum has included JavaScript assets by committing
the source code to the `lib/gollum/public/gollum/javascript/` directory
and including them for compilation in the Sprockets asset manifest file
at `lib/gollum/public/gollum/javascript/app.js`. This has been a
reasonable way to deal with third-party JavaScript, but there are a few
downsides:

  - It's a burden to find out if JavaScript dependencies have been
    updated and require updating in Gollum.
  - It doesn't give us good visibility into the JavaScript dependencies
    required by our dependencies.
  - It forces us to commit external code to our repository, which can
    make our developer tools more difficult to configure or use. For
    example: when I search for key words in the repository using
    Ripgrep, I often get "garbage" results from minified JavaScript.

Managing JavaScript dependencies via a JS package manager can resolve
all of these issues.

This commit allows us to manage JavaScript dependencies using the Yarn
package manager for Node JS modules[1]. I chose Yarn over NPM for one
reason: Yarn is the JavaScript package manager that Rails uses by
default. So many Ruby developers will already be familiar with Yarn.

To demonstrate how this can change how we manage JS assets in Gollum,
I've configured Yarn and started to manage the `mousetrap` dependency
with it. I chose `mousetrap` to start because it's a smaller, mostly
uncomplicated dependency. I was easily able to manually test that
`mousetrap` is still working after re-compiling the assets.

Hopefully this gives anyone reading enough context to jump in and start
moving our third-party JS assets out of the codebase.

[1]: https://yarnpkg.com/

* Recompile assets

* Add dev environment setup info to CONTRIBUTING

Now that we require additional tooling to manage JavaScript
dependencies, it seemed reasonable to add more documentation around
setting up one's development environment.

* Don't compile assets without `yarn`-managed ones

If a developer compiled assets without first running `yarn install`, we
would get incomplete collection of up-to-date assets.

Let's ensure that the developer has all the required assets by enforcing
this in the precompile task they should be using to compile production
assets to begin with.

CONTRIBUTING.md

@@ -29,12 +29,83 @@ Lastly, please **consider helping out** by opening a Pull Request!
 
 You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to gollum on CodeTriage](https://www.codetriage.com/gollum/gollum).
 
+## Set up your development environment
+
+If you want to hack on Gollum, you'll need to set up a development
+environment.
+
+To get started, you'll need:
+
+  - A recent version of [Git][git]
+  - A recent version of [Ruby][rubylang].
+  - A recent version of [Node JS][nodejs].
+
+Refer to their installation instructions. Installation methods differ depending
+on your operating system.
+
+Once you have those:
+
+  - Install Bundler, the Ruby package manager. In a terminal:
+    ```sh
+    gem install bundler
+    ```
+  - Install Yarn, a JavaScript package manager. [See Yarn's install
+    guide][yarn-install].
+
+Now, you can start setting up Gollum to run locally:
+
+  1. Clone the git repository. In a terminal:
+
+     ```sh
+     git clone https://github.com/gollum/gollum.git
+     ```
+  2. Change directory into the cloned project:
+     ```sh
+     cd gollum
+     ```
+  3. Bundle the project's Ruby dependencies using Bundler:
+     ```sh
+     [sudo] bundle install
+     ```
+  4. Install the project's JavaScript dependencies using Yarn:
+     ```sh
+     yarn install
+     ```
+If all went well, you should now be able to run the test suite using the
+following command:
+
+```sh
+bundle exec rake
+```
+
+If you already have a Gollum wiki, you can also browse it via your local version
+of Gollum:
+
+```sh
+bundle exec gollum <path/to/my/wiki/root>
+```
+
+Or you can clone an example wiki and browse that:
+
+```sh
+git clone test/examples/lotr.git ~/lotr-wiki
+bundle exec gollum ~/lotr-wiki
+```
+
+With this, you're ready to start contributing and open your first [pull
+request](#opening-a-pull-request).
+
+[git]: https://git-scm.com/downloads
+[nodejs]: https://nodejs.org
+[rubylang]: https://www.ruby-lang.org
+[yarn-install]: https://yarnpkg.com/getting-started/install
 
 ## Opening a Pull Request
 
 Pull Requests fixing bugs, implementing new features, or updating documentation and dependencies are all very welcome! If you would like to help out with the project, you can pick an open issue from the issue tracker. We're more than happy to help you get started! Here's how you can proceed:
 
-1. Fork and clone Gollum.
+1. Fork and clone Gollum. See [Set up your development
+   environment](#set-up-your-development-environment).
 2. Create a thoughtfully named topic branch to contain your changes.
 3. If you haven't installed dependencies yet, navigate to your clone and execute:
 	```
@@ -47,8 +118,7 @@ Pull Requests fixing bugs, implementing new features, or updating documentation
 8. Push the branch to your fork on GitHub.
 9. Create a pull request for Gollum.
 
-**Notes:**
-* Do not change Gollum's version numbers, we will do that on our own.
+Do not change Gollum's version number, we will do that on our own.
 
 ### Running tests
 
@@ -63,7 +133,17 @@ Pull Requests fixing bugs, implementing new features, or updating documentation
 	bundle exec rake test
 	```
 
-To profile slow tests, you can use `bundle exec rake test TESTOPTS="--verbose"`.
+To profile slow tests, you can use the `--verbose` flag:
+
+```sh
+bundle exec rake test TESTOPTS="--verbose"
+```
+
+You can also run a single test file with the following command:
+
+```sh
+bundle exec ruby <test/test_the_file_i_want_to_run.rb>
+```
 
 ### Working with test repositories
 
@@ -82,7 +162,12 @@ git push ../lotr.git/ master
 
 ## Updating static assets
 
-This is necessary whenever changes have been made to the assets in `lib/gollum/public/gollum/javascript` (mostly SASS, CSS, and JS files), to ensure the changes are also present in the [released](#releasing-the-gem) version of the gem. Steps:
+This is necessary whenever changes have been made to the assets in
+`lib/gollum/public/gollum/javascript` (mostly SASS, CSS, and JS files), to
+ensure the changes are also present in the [released](#releasing-the-gem)
+version of the gem.
+
+Steps:
 
 1. `git rm -r lib/gollum/public/assets`
 1. `bundle exec rake precompile`

Rakefile

@@ -224,11 +224,29 @@ end
 
 desc 'Precompile assets'
 task :precompile do
+  # Attempt to install JavaScript dependencies managed by Yarn via the
+  # `package.json` file in Gollum's project root. If it fails, raise an error
+  # and exit the task early.
+  puts "\n  Installing `yarn`-managed JavaScript dependencies...  \n\n"
+  system "yarn install"
+    unless $?.success?
+    raise "This task tried to run `yarn install` to get up-to-date "          \
+      "JavaScript dependencies before precompilation. But it failed. Please " \
+      "run `yarn install` manually from your shell and resolve any issues. "  \
+      "It's possible that you just need to install `yarn` on your system."
+  end
+
   require './lib/gollum/app.rb'
+
+  # Next, configure the Sprockets asset pipeline and precompile production-
+  # ready assets.
   Precious::App.set(:environment, :production)
+
   env = Precious::Assets.sprockets
-  path = ENV.fetch('GOLLUM_ASSETS_PATH', ::File.join(File.dirname(__FILE__), 'lib/gollum/public/assets'))
+  path = ENV.fetch 'GOLLUM_ASSETS_PATH',
+    File.join(File.dirname(__FILE__), 'lib/gollum/public/assets')
   manifest = Sprockets::Manifest.new(env, path)
+
   Sprockets::Helpers.configure do |config|
     config.environment = env
     config.prefix      = Precious::Assets::ASSET_URL
@@ -236,6 +254,7 @@ task :precompile do
     config.public_path = path
     config.manifest    = manifest
   end
-  puts "Precompiling assets to #{path}..."
+
+  puts "\n  Precompiling assets to #{path}...  \n\n"
   manifest.compile(Precious::Assets::MANIFEST)
 end

lib/gollum/assets.rb

@@ -7,8 +7,12 @@ module Precious
 
     def self.sprockets(dir = File.dirname(File.expand_path(__FILE__)))
       env = Sprockets::Environment.new
-      env.append_path ::File.join(dir, 'public/gollum/stylesheets/')
+
+      env.append_path ::File.join(dir, '../../node_modules')
+
       env.append_path ::File.join(dir, 'public/gollum/javascript')
+      env.append_path ::File.join(dir, 'public/gollum/stylesheets/')
+
       env.append_path ::File.join(dir, 'public/gollum/images')
       env.append_path ::File.join(dir, 'public/gollum/fonts')
 

lib/gollum/public/assets/.sprockets-manifest-160337b312f8e438181baac4aaa37319.json

@@ -1 +0,0 @@
-{"files":{"app-f05401ee374f0c7f48fc2bc08e30b4f4db705861fd5895ed70998683b383bfb5.js":{"logical_path":"app.js","mtime":"2021-11-15T20:08:30-08:00","size":136040,"digest":"f05401ee374f0c7f48fc2bc08e30b4f4db705861fd5895ed70998683b383bfb5","integrity":"sha256-8FQB7jdPDH9I/CvAjjC09NtwWGH9WJXtcJmGg7ODv7U="},"editor-9881d0c7ae663293f0e3a7e72729eec7e940fa613185c076709b76d292f5703a.js":{"logical_path":"editor.js","mtime":"2021-11-15T20:08:30-08:00","size":744886,"digest":"9881d0c7ae663293f0e3a7e72729eec7e940fa613185c076709b76d292f5703a","integrity":"sha256-mIHQx65mMpPw46fnJynux+lA+mExhcB2cJt20pL1cDo="},"app-309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5.css":{"logical_path":"app.css","mtime":"2022-05-26T12:13:37+02:00","size":396731,"digest":"309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5","integrity":"sha256-MJvgMjlueDsTpH31jzibfI4RwrLUJkBWC4dPZ3wl9uU="},"criticmarkup-31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4.css":{"logical_path":"criticmarkup.css","mtime":"2020-03-29T22:28:51+02:00","size":646,"digest":"31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4","integrity":"sha256-Ma5dMoK7uOe3w8mRfp+2jjMVprSnXabOxI0huIRpBcQ="},"print-512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb.css":{"logical_path":"print.css","mtime":"2020-03-30T11:12:22+02:00","size":75,"digest":"512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb","integrity":"sha256-USSYw2i+DT+xuhBd+oQomuSDgOyfy++Ui9TiOwsJW/s="},"app-eb6effc9f708916af14718a5c9d2a5028625664f62c2528e5989538537f3f4a8.js":{"logical_path":"app.js","mtime":"2022-05-26T13:00:46+02:00","size":188288,"digest":"eb6effc9f708916af14718a5c9d2a5028625664f62c2528e5989538537f3f4a8","integrity":"sha256-627/yfcIkWrxRxilydKlAoYlZk9iwlKOWYlThTfz9Kg="},"editor-ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a.js":{"logical_path":"editor.js","mtime":"2022-05-26T13:00:46+02:00","size":745160,"digest":"ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a","integrity":"sha256-699TSgBj/jsFp+far3qkC3j6uYYxQrFh2I8yo/A1N4o="}},"assets":{"app.js":"app-eb6effc9f708916af14718a5c9d2a5028625664f62c2528e5989538537f3f4a8.js","editor.js":"editor-ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a.js","app.css":"app-309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5.css","criticmarkup.css":"criticmarkup-31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4.css","print.css":"print-512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb.css"}}

lib/gollum/public/assets/.sprockets-manifest-9ac24f50c124b745e80f4ecb2d86282b.json

@@ -0,0 +1 @@
+{"files":{"app-6bef6b19014c6620eab4daf7bc581f9d43fff778bdc78aa9fe53aaa2c927c8cc.js":{"logical_path":"app.js","mtime":"2022-06-03T19:51:43-07:00","size":188397,"digest":"6bef6b19014c6620eab4daf7bc581f9d43fff778bdc78aa9fe53aaa2c927c8cc","integrity":"sha256-a+9rGQFMZiDqtNr3vFgfnUP/93i9x4qp/lOqosknyMw="},"editor-ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a.js":{"logical_path":"editor.js","mtime":"2022-06-03T19:51:43-07:00","size":745160,"digest":"ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a","integrity":"sha256-699TSgBj/jsFp+far3qkC3j6uYYxQrFh2I8yo/A1N4o="},"app-309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5.css":{"logical_path":"app.css","mtime":"2022-06-03T19:51:43-07:00","size":396731,"digest":"309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5","integrity":"sha256-MJvgMjlueDsTpH31jzibfI4RwrLUJkBWC4dPZ3wl9uU="},"criticmarkup-31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4.css":{"logical_path":"criticmarkup.css","mtime":"2021-02-24T23:16:14-08:00","size":646,"digest":"31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4","integrity":"sha256-Ma5dMoK7uOe3w8mRfp+2jjMVprSnXabOxI0huIRpBcQ="},"print-512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb.css":{"logical_path":"print.css","mtime":"2021-02-24T23:16:14-08:00","size":75,"digest":"512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb","integrity":"sha256-USSYw2i+DT+xuhBd+oQomuSDgOyfy++Ui9TiOwsJW/s="}},"assets":{"app.js":"app-6bef6b19014c6620eab4daf7bc581f9d43fff778bdc78aa9fe53aaa2c927c8cc.js","editor.js":"editor-ebdf534a0063fe3b05a7e7daaf7aa40b78fab9863142b161d88f32a3f035378a.js","app.css":"app-309be032396e783b13a47df58f389b7c8e11c2b2d42640560b874f677c25f6e5.css","criticmarkup.css":"criticmarkup-31ae5d3282bbb8e7b7c3c9917e9fb68e3315a6b4a75da6cec48d21b8846905c4.css","print.css":"print-512498c368be0d3fb1ba105dfa84289ae48380ec9fcbef948bd4e23b0b095bfb.css"}}

lib/gollum/public/gollum/javascript/app.js

@@ -1,7 +1,10 @@
+// Require vendor assets from installed Node modules.
+//= require mousetrap/mousetrap.min
+
+// Require application assets.
 //= require jquery-1.7.2.min
 //= require identicon
 //= require date.min
-//= require mousetrap.min
 //= require clipboard.min
 //= require gollum
 //= require gollum.dialog

lib/gollum/public/gollum/javascript/mousetrap.min.js

@@ -1,11 +0,0 @@
-/* mousetrap v1.6.1 craig.is/killing/mice */
-(function(r,v,f){function w(a,b,g){a.addEventListener?a.addEventListener(b,g,!1):a.attachEvent("on"+b,g)}function A(a){if("keypress"==a.type){var b=String.fromCharCode(a.which);a.shiftKey||(b=b.toLowerCase());return b}return p[a.which]?p[a.which]:t[a.which]?t[a.which]:String.fromCharCode(a.which).toLowerCase()}function F(a){var b=[];a.shiftKey&&b.push("shift");a.altKey&&b.push("alt");a.ctrlKey&&b.push("ctrl");a.metaKey&&b.push("meta");return b}function x(a){return"shift"==a||"ctrl"==a||"alt"==a||
-"meta"==a}function B(a,b){var g,c,d,f=[];g=a;"+"===g?g=["+"]:(g=g.replace(/\+{2}/g,"+plus"),g=g.split("+"));for(d=0;d<g.length;++d)c=g[d],C[c]&&(c=C[c]),b&&"keypress"!=b&&D[c]&&(c=D[c],f.push("shift")),x(c)&&f.push(c);g=c;d=b;if(!d){if(!n){n={};for(var q in p)95<q&&112>q||p.hasOwnProperty(q)&&(n[p[q]]=q)}d=n[g]?"keydown":"keypress"}"keypress"==d&&f.length&&(d="keydown");return{key:c,modifiers:f,action:d}}function E(a,b){return null===a||a===v?!1:a===b?!0:E(a.parentNode,b)}function c(a){function b(a){a=
-a||{};var b=!1,l;for(l in n)a[l]?b=!0:n[l]=0;b||(y=!1)}function g(a,b,u,e,c,g){var l,m,k=[],f=u.type;if(!h._callbacks[a])return[];"keyup"==f&&x(a)&&(b=[a]);for(l=0;l<h._callbacks[a].length;++l)if(m=h._callbacks[a][l],(e||!m.seq||n[m.seq]==m.level)&&f==m.action){var d;(d="keypress"==f&&!u.metaKey&&!u.ctrlKey)||(d=m.modifiers,d=b.sort().join(",")===d.sort().join(","));d&&(d=e&&m.seq==e&&m.level==g,(!e&&m.combo==c||d)&&h._callbacks[a].splice(l,1),k.push(m))}return k}function f(a,b,c,e){h.stopCallback(b,
-b.target||b.srcElement,c,e)||!1!==a(b,c)||(b.preventDefault?b.preventDefault():b.returnValue=!1,b.stopPropagation?b.stopPropagation():b.cancelBubble=!0)}function d(a){"number"!==typeof a.which&&(a.which=a.keyCode);var b=A(a);b&&("keyup"==a.type&&z===b?z=!1:h.handleKey(b,F(a),a))}function p(a,c,u,e){function l(c){return function(){y=c;++n[a];clearTimeout(r);r=setTimeout(b,1E3)}}function g(c){f(u,c,a);"keyup"!==e&&(z=A(c));setTimeout(b,10)}for(var d=n[a]=0;d<c.length;++d){var m=d+1===c.length?g:l(e||
-B(c[d+1]).action);q(c[d],m,e,a,d)}}function q(a,b,c,e,d){h._directMap[a+":"+c]=b;a=a.replace(/\s+/g," ");var f=a.split(" ");1<f.length?p(a,f,b,c):(c=B(a,c),h._callbacks[c.key]=h._callbacks[c.key]||[],g(c.key,c.modifiers,{type:c.action},e,a,d),h._callbacks[c.key][e?"unshift":"push"]({callback:b,modifiers:c.modifiers,action:c.action,seq:e,level:d,combo:a}))}var h=this;a=a||v;if(!(h instanceof c))return new c(a);h.target=a;h._callbacks={};h._directMap={};var n={},r,z=!1,t=!1,y=!1;h._handleKey=function(a,
-c,d){var e=g(a,c,d),k;c={};var h=0,l=!1;for(k=0;k<e.length;++k)e[k].seq&&(h=Math.max(h,e[k].level));for(k=0;k<e.length;++k)e[k].seq?e[k].level==h&&(l=!0,c[e[k].seq]=1,f(e[k].callback,d,e[k].combo,e[k].seq)):l||f(e[k].callback,d,e[k].combo);e="keypress"==d.type&&t;d.type!=y||x(a)||e||b(c);t=l&&"keydown"==d.type};h._bindMultiple=function(a,b,c){for(var d=0;d<a.length;++d)q(a[d],b,c)};w(a,"keypress",d);w(a,"keydown",d);w(a,"keyup",d)}if(r){var p={8:"backspace",9:"tab",13:"enter",16:"shift",17:"ctrl",
-18:"alt",20:"capslock",27:"esc",32:"space",33:"pageup",34:"pagedown",35:"end",36:"home",37:"left",38:"up",39:"right",40:"down",45:"ins",46:"del",91:"meta",93:"meta",224:"meta"},t={106:"*",107:"+",109:"-",110:".",111:"/",186:";",187:"=",188:",",189:"-",190:".",191:"/",192:"`",219:"[",220:"\\",221:"]",222:"'"},D={"~":"`","!":"1","@":"2","#":"3",$:"4","%":"5","^":"6","&":"7","*":"8","(":"9",")":"0",_:"-","+":"=",":":";",'"':"'","<":",",">":".","?":"/","|":"\\"},C={option:"alt",command:"meta","return":"enter",
-escape:"esc",plus:"+",mod:/Mac|iPod|iPhone|iPad/.test(navigator.platform)?"meta":"ctrl"},n;for(f=1;20>f;++f)p[111+f]="f"+f;for(f=0;9>=f;++f)p[f+96]=f.toString();c.prototype.bind=function(a,b,c){a=a instanceof Array?a:[a];this._bindMultiple.call(this,a,b,c);return this};c.prototype.unbind=function(a,b){return this.bind.call(this,a,function(){},b)};c.prototype.trigger=function(a,b){if(this._directMap[a+":"+b])this._directMap[a+":"+b]({},a);return this};c.prototype.reset=function(){this._callbacks={};
-this._directMap={};return this};c.prototype.stopCallback=function(a,b){return-1<(" "+b.className+" ").indexOf(" mousetrap ")||E(b,this.target)?!1:"INPUT"==b.tagName||"SELECT"==b.tagName||"TEXTAREA"==b.tagName||b.isContentEditable};c.prototype.handleKey=function(){return this._handleKey.apply(this,arguments)};c.addKeycodes=function(a){for(var b in a)a.hasOwnProperty(b)&&(p[b]=a[b]);n=null};c.init=function(){var a=c(v),b;for(b in a)"_"!==b.charAt(0)&&(c[b]=function(b){return function(){return a[b].apply(a,
-arguments)}}(b))};c.init();r.Mousetrap=c;"undefined"!==typeof module&&module.exports&&(module.exports=c);"function"===typeof define&&define.amd&&define(function(){return c})}})("undefined"!==typeof window?window:null,"undefined"!==typeof window?document:null);

package.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": {
+    "mousetrap": "^1.6.5"
+  },
+  "engines": {
+    "node" : ">=16.15.0"
+  }
+}

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+mousetrap@^1.6.5:
+  version "1.6.5"
+  resolved "https://registry.yarnpkg.com/mousetrap/-/mousetrap-1.6.5.tgz#8a766d8c272b08393d5f56074e0b5ec183485bf9"
+  integrity sha512-QNo4kEepaIBwiT8CDhP98umTetp+JNfQYBWvC1pc6/OAibuXtRcxZ58Qz8skvEHYvURne/7R8T5VoOI7rDsEUA==