[added] findBinary function; switched Flow from a global prerequisi…

…te to a local `webcompiler` managed dependency - "flow-bin" (yay!)

README.md

@@ -34,8 +34,7 @@ Any feedback on [Discord] would be greatly appreciated. It does not require regi
 
 ### Prerequisites
 
-1. [Facebook Flow](http://flowtype.org/)
-2. [Watchman](https://facebook.github.io/watchman/)
+1. [Watchman](https://facebook.github.io/watchman/)
 
 ### A note about [Facebook Flow](http://flowtype.org/)
 

interfaces/sinon.js

@@ -6,6 +6,7 @@ type Spy = {
 };
 
 type Stub = {
+  (...args: Array<any>): any;
   returns(obj: any): any;
   returnsArg(i: number): any;
   throws(err: Error): any;

interfaces/webcompiler.js

@@ -1,13 +1,13 @@
 /* @flow */
 
-import type {ProgramData, ProgramDataCallback, NativeProcessCallback,
+import type {ProgramData, ProgramDataCallback, StringOrErrorCallback, ResultOrErrorCallback,
   ObjectOrErrorCallback, DevServerConfig, LintError, LintCallback, PostCSSWarning, NodeSassError} from '../src/typedef';
 
 declare module 'webcompiler' {
 
   declare class NativeProcess {
     constructor(task: string): void;
-    run(callback: ?NativeProcessCallback, args: ?Array<string>, opts: ?Object): void;
+    run(callback: ?StringOrErrorCallback, args: ?Array<string>, opts: ?Object): void;
     kill(): void;
   }
 
@@ -29,6 +29,7 @@ declare module 'webcompiler' {
 
   declare function watch(dir: string, type: string, callback: () => void): void;
   declare function yaml(filename: string, callback: ObjectOrErrorCallback): void;
+  declare function findBinary(name: string, callback: ResultOrErrorCallback): void;
 
   declare class Message {}
 

package.json

@@ -77,6 +77,7 @@
     "eslint-plugin-lodash": "^2.2.5",
     "eslint-plugin-react": "^6.9.0",
     "fb-watchman": "^1.9.0",
+    "flow-bin": "^0.37.4",
     "js-yaml": "^3.7.0",
     "jsdoc": "^3.4.3",
     "jsdom": "^9.9.1",

src/Documentation.js

@@ -1,13 +1,12 @@
 /* @flow */
 
-import {NativeProcess} from './NativeProcess';
-import {stat} from 'fs';
+import type {NativeProcess} from './NativeProcess';
 import {join} from 'path';
 import noop from 'lodash/noop';
 import {logError} from './logger';
+import {findBinary} from './findBinary';
 
-const npm = new NativeProcess('npm'),
-  cwd = process.cwd(),
+const cwd = process.cwd(),
   defaultOptions = {
     inputDir: join(cwd, 'src'),
     outputDir: join(cwd, 'docs'),
@@ -42,16 +41,6 @@ const npm = new NativeProcess('npm'),
  */
 export class Documentation {
 
-  /**
-   * JSDoc3
-   *
-   * @member {NativeProcess} jsdoc
-   * @memberof Documentation
-   * @private
-   * @instance
-   */
-  jsdoc: ?NativeProcess;
-
   /**
    * documentation generator configuration object
    *
@@ -68,31 +57,6 @@ export class Documentation {
     this.options = {...defaultOptions, ...options};
   }
 
-  /**
-   * Finds a path to the project level JSDoc3 executable
-   *
-   * @memberof Documentation
-   * @static
-   * @private
-   * @method findExecutable
-   * @param {Function} callback - a callback function
-   */
-  static findExecutable(callback: Function) {
-    npm.run((stderr, stdout) => {
-      if (stderr) {
-        return logError(stderr);
-      }
-      const path = join(stdout.trimRight(), 'jsdoc');
-
-      stat(path, statErr => {
-        if (statErr) {
-          return logError(statErr);
-        }
-        callback(path);
-      });
-    }, ['bin']);
-  }
-
   /**
    * Generate the documentation
    *
@@ -107,38 +71,19 @@ export class Documentation {
    * });
    */
   run(callback: () => void = noop) {
-    if (this.jsdoc) {
-      return this.doRun(this.jsdoc, callback);
-    }
-    Documentation.findExecutable(file => {
-      this.jsdoc = new NativeProcess(file);
-      this.doRun(this.jsdoc, callback);
-    });
-  }
-
-  /**
-   * Given a JSDoc3 executable, generate the documentation
-   *
-   * @memberof Documentation
-   * @instance
-   * @private
-   * @method doRun
-   * @param {NativeProcess} jsdoc    - JSDoc3
-   * @param {Function}      callback - a callback function
-   * @example
-   * docs.doRun(jsdoc, () => {
-   *   // generated the API documentation
-   * });
-   */
-  doRun(jsdoc: NativeProcess, callback: () => void) {
-    const {inputDir, outputDir, readMe, template, jsdocConfig} = this.options;
-
-    jsdoc.run(stderr => {
-      if (stderr) {
-        return logError(stderr);
+    findBinary('jsdoc', (error, jsdoc: NativeProcess) => {
+      if (error) {
+        return logError(error);
       }
-      callback();
-    }, [inputDir, '-d', outputDir, '-R', readMe, '-c', jsdocConfig, '-t', template]);
+      const {inputDir, outputDir, readMe, template, jsdocConfig} = this.options;
+
+      jsdoc.run(stderr => {
+        if (stderr) {
+          return logError(stderr);
+        }
+        callback();
+      }, [inputDir, '-d', outputDir, '-R', readMe, '-c', jsdocConfig, '-t', template]);
+    });
   }
 
 }

src/JS.js

@@ -1,10 +1,11 @@
 /* @flow */
 
 import {JSCompiler} from './JSCompiler';
-import {NativeProcess} from './NativeProcess';
+import type {NativeProcess} from './NativeProcess';
 import {JSLint} from './JSLint';
 import noop from 'lodash/noop';
 import {logError, logLintingErrors} from './logger';
+import {findBinary} from './findBinary';
 
 /**
  * JavaScript compilation tools
@@ -31,16 +32,6 @@ export class JS {
    */
   compiler: JSCompiler;
 
-  /**
-   * flow static analyzer
-   *
-   * @member {NativeProcess} flow
-   * @memberof JS
-   * @private
-   * @instance
-   */
-  flow: NativeProcess = new NativeProcess('flow');
-
   /**
    * JavaScript linter
    *
@@ -62,24 +53,29 @@ export class JS {
    * Performs static analysis
    *
    * @memberof JS
-   * @instance
+   * @static
    * @method typecheck
    * @param {Function} callback - a callback function, invoked only when successfully typechecked
    * @example
-   * js.typecheck(() => {
+   * JS.typecheck(() => {
    *   // successfully typechecked
    * });
    */
-  typecheck(callback: () => void) {
-    this.flow.run((flowErr, stdout) => {
-      if (flowErr) {
-        return logError(flowErr);
-      }
-      if (!JSON.parse(stdout).passed) {
-        return this.flow.run(noop, [], {stdio: 'inherit'});
+  static typecheck(callback: () => void) {
+    findBinary('flow', (error, flow: NativeProcess) => {
+      if (error) {
+        return logError(error);
       }
-      callback();
-    }, ['--json']);
+      flow.run((flowErr, stdout) => {
+        if (flowErr) {
+          return logError(flowErr);
+        }
+        if (!JSON.parse(stdout).passed) {
+          return flow.run(noop, [], {stdio: 'inherit'});
+        }
+        callback();
+      }, ['--json']);
+    });
   }
 
   /**
@@ -120,7 +116,7 @@ export class JS {
    * });
    */
   validate(inPath: string, lintPaths: Array<string>, callback: () => void) {
-    this.typecheck(() => {
+    JS.typecheck(() => {
       this.lint(lintPaths.concat([inPath]), callback);
     });
   }

src/NativeProcess.js

@@ -1,6 +1,6 @@
 /* @flow */
 
-import type {NativeProcessCallback} from './typedef';
+import type {StringOrErrorCallback} from './typedef';
 import {spawn} from 'child_process';
 import noop from 'lodash/noop';
 
@@ -52,7 +52,7 @@ export class NativeProcess {
    * @memberof NativeProcess
    * @instance
    * @method run
-   * @param  {NativeProcessCallback} [callback=function () {}] - a callback function
+   * @param  {StringOrErrorCallback} [callback=function () {}] - a callback function
    * @param  {Array<string>}         [args=[]]                 - an array of arguments to pass to the process
    * @param  {Object}                [opts={}]                 - a configuration object for the process
    * @return {void}
@@ -66,7 +66,7 @@ export class NativeProcess {
    *   // created a directory named "example" in cwd
    * }, ['example']);
    */
-  run(callback: NativeProcessCallback = noop, args: Array<string> = [], opts: Object = {}) {
+  run(callback: StringOrErrorCallback = noop, args: Array<string> = [], opts: Object = {}) {
     if (this.proc) {
       return callback(new Error('Still working'), '');
     }

src/findBinary.js

@@ -0,0 +1,52 @@
+/* @flow */
+
+import type {ResultOrErrorCallback} from './typedef';
+import {NativeProcess} from './NativeProcess';
+import {stat} from 'fs';
+import {join} from 'path';
+
+const npm = new NativeProcess('npm'),
+  cache = {};
+
+/**
+ * Finds the path to a project level binary, creates a {@link NativeProcess} for that binary, caches it for all
+ * subsequent invocations, and provides it to the callback.
+ *
+ * @function findBinary
+ * @param {string}                name     - the binary name
+ * @param {ResultOrErrorCallback} callback - a callback function
+ * @return {void}
+ * @example
+ * import {findBinary, logError} from 'webcompiler';
+ * // or - import {findBinary} from 'webcompiler/lib/findBinary';
+ * // or - var findBinary = require('webcompiler').findBinary;
+ * // or - var findBinary = require('webcompiler/lib/findBinary').findBinary;
+ * // import logError somehow
+ *
+ * findBinary('something', (error, binary) => {
+ *   if (error) {
+ *     return logError(error);
+ *   }
+ *   binary.run(() => {
+ *     // called the `something` binary from the local project level "node_modules/.bin" directory
+ *   });
+ * });
+ */
+export function findBinary(name: string, callback: ResultOrErrorCallback) {
+  if (cache[name]) {
+    return callback(null, cache[name]);
+  }
+  npm.run((stderr, stdout) => {
+    if (stderr) {
+      return callback(stderr);
+    }
+    const path = join(stdout.trimRight(), name);
+
+    stat(path, statErr => {
+      if (statErr) {
+        return callback(statErr);
+      }
+      callback(null, cache[name] = new NativeProcess(path));
+    });
+  }, ['bin']);
+}

src/index.js

@@ -5,6 +5,7 @@ export {Documentation} from './Documentation';
 
 export {watch} from './watch';
 export {yaml} from './yaml';
+export {findBinary} from './findBinary';
 export {consoleStyles, log, logError, logPostCSSWarnings, logSASSError, logLintingErrors} from './logger';
 export {babelBEOptions, babelFEOptions} from './webpack';
 

src/typedef.js

@@ -142,19 +142,26 @@ export type ProgramDataCallback = (data: ProgramData) => void;
 export type LintCallback = (errors: ?LintError[]) => void;
 
 /**
- * @callback NativeProcessCallback
- * @param {Error} [stderr] - an error message
- * @param {string} stdout  - the process output
+ * @callback StringOrErrorCallback
+ * @param {Error}  [error] - an error object
+ * @param {string} result  - the resulting string
  */
-export type NativeProcessCallback = (stderr: ?Error, stdout: string) => void;
+export type StringOrErrorCallback = (error: ?Error, result: string) => void;
 
 /**
  * @callback ObjectOrErrorCallback
- * @param {Error} [error] - an error message
+ * @param {Error}  [error] - an error object
  * @param {Object} result  - the resulting object
  */
 export type ObjectOrErrorCallback = (error: ?Error, result: Object) => void;
 
+/**
+ * @callback ResultOrErrorCallback
+ * @param {Error} [error] - an error object
+ * @param {*}     result  - the resulting value
+ */
+export type ResultOrErrorCallback = (error: ?Error, result: any) => void;
+
 /**
  * Describes a file a change in which was caught.
  *