Language::Node.npm_install_args: add helper method (#37)

* add Language::Node helper module

This adds a language module for Node module based formulas.
It contains the 2 public methods `std_npm_install_args(libexec)` and
`local_npm_install_args`:

* `std_npm_install_args` is intended to be used in formulas for
  standard node modules and returns `npm install` args for a global
  style module installation to libexec.
* `local_npm_install_args` is for formulas, in which the `npm install`
  step is only one of multiple parts of the installation process and
  returns `npm install` args for a default local installation in place.

Both methods have in common, that they are

* making sure that a working copy of npm and node-gyp from node's
  libexec is prepended to the PATH (to not rely of a user managed npm)
* seting the npm cache to HOMEBREW_CACHE/npm, which fixes issues caused
  by overriding $HOME resulting in long install times + high disk usage
  (see https://github.com/Homebrew/brew/pull/37#issuecomment-208840366)

* audit: update npm install check for Language::Node

* cleanup: remove npm_cache too

* doc: add Node-for-Formula-Authors.md

4 files changed, 47 insertions, 8 deletions

diff --git a/Library/Homebrew/cleanup.rb b/Library/Homebrew/cleanup.rb
index 15805ae8e..2dba60bb9 100644
--- a/Library/Homebrew/cleanup.rb
+++ b/Library/Homebrew/cleanup.rb
@@ -50,7 +50,7 @@ module Homebrew
           cleanup_path(path) { path.unlink }
           next
         end
-        if path.basename.to_s == "java_cache" && path.directory?
+        if %w[java_cache npm_cache].include?(path.basename.to_s) && path.directory?
           cleanup_path(path) { FileUtils.rm_rf path }
           next
         end
diff --git a/Library/Homebrew/cmd/audit.rb b/Library/Homebrew/cmd/audit.rb
index eca4fbb1e..64b61ec22 100644
--- a/Library/Homebrew/cmd/audit.rb
+++ b/Library/Homebrew/cmd/audit.rb
@@ -656,13 +656,6 @@ class FormulaAuditor
     if text =~ /def plist/ && text !~ /plist_options/
       problem "Please set plist_options when using a formula-defined plist."
     end
-
-    if text =~ /system "npm", "install"/ && text !~ %r[opt_libexec\}/npm/bin] && formula.name !~ /^kibana(\d{2})?$/
-      need_npm = "\#{Formula[\"node\"].opt_libexec\}/npm/bin"
-      problem <<-EOS.undent
-       Please add ENV.prepend_path \"PATH\", \"#{need_npm}"\ to def install
-      EOS
-    end
   end
 
   def audit_line(line, lineno)
@@ -885,6 +878,10 @@ class FormulaAuditor
       problem "Use `assert_match` instead of `assert ...include?`"
     end
 
+    if line =~ /system "npm", "install"/ && line !~ /Language::Node/
+      problem "Use Language::Node for npm install args"
+    end
+
     if @strict
       if line =~ /system (["'][^"' ]*(?:\s[^"' ]*)+["'])/
         bad_system = $1
diff --git a/Library/Homebrew/language/node.rb b/Library/Homebrew/language/node.rb
new file mode 100644
index 000000000..15a2ddc10
--- /dev/null
+++ b/Library/Homebrew/language/node.rb
@@ -0,0 +1,35 @@
+module Language
+  module Node
+    def self.npm_cache_config
+      "cache=#{HOMEBREW_CACHE}/npm_cache\n"
+    end
+
+    def self.setup_npm_environment
+      npmrc = Pathname.new("#{ENV["HOME"]}/.npmrc")
+      # only run setup_npm_environment once per formula
+      return if npmrc.exist?
+      # explicitly set npm's cache path to HOMEBREW_CACHE/npm_cache to fix
+      # issues caused by overriding $HOME (long build times, high disk usage)
+      # https://github.com/Homebrew/brew/pull/37#issuecomment-208840366
+      npmrc.write npm_cache_config
+      # explicitly use our npm and node-gyp executables instead of the user
+      # managed ones in HOMEBREW_PREFIX/lib/node_modules which might be broken
+      ENV.prepend_path "PATH", Formula["node"].opt_libexec/"npm/bin"
+    end
+
+    def self.std_npm_install_args(libexec)
+      setup_npm_environment
+      # tell npm to not install .brew_home by adding it to the .npmignore file
+      # (or creating a new one if no .npmignore file already exists)
+      open(".npmignore", "a") { |f| f.write( "\n.brew_home\n") }
+      # npm install args for global style module format installed into libexec
+      ["--verbose", "--global", "--prefix=#{libexec}", "."]
+    end
+
+    def self.local_npm_install_args
+      setup_npm_environment
+      # npm install args for local style module format
+      ["--verbose"]
+    end
+  end
+end
diff --git a/Library/Homebrew/test/test_cleanup.rb b/Library/Homebrew/test/test_cleanup.rb
index bccfa1e54..1351c85a6 100644
--- a/Library/Homebrew/test/test_cleanup.rb
+++ b/Library/Homebrew/test/test_cleanup.rb
@@ -73,4 +73,11 @@ class CleanupTests < Homebrew::TestCase
     shutup { Homebrew::Cleanup.cleanup_cache }
     refute_predicate java_cache, :exist?
   end
+
+  def test_cleanup_cache_npm_cache
+    npm_cache = (HOMEBREW_CACHE/"npm_cache")
+    npm_cache.mkpath
+    shutup { Homebrew::Cleanup.cleanup_cache }
+    refute_predicate npm_cache, :exist?
+  end
 end