Add --resolver option (closes #42)

`--resolver` either accepts the name of a built-in resolver
(findExportedComponentDefinition, findAllComponentDefinitions) or a path
to a module that exports a resolver function.

With this option, react-docgen can be more easily customized. It is not
necessary anymore to create a custom script and use the API just to use
a different / custom resolver.

Author: fkling

README.md

@@ -4,7 +4,10 @@
 
 It uses [recast][] and [babylon][] to parse the source into an AST and provides methods to process this AST to extract the desired information. The output / return value is a JSON blob / JavaScript object.
 
-It provides a default implementation for React components defined via `React.createClass` or [ES2015 class definitions][classes]. These component definitions must follow certain guidelines in order to be analyzable (see below for more info).
+It provides a default implementation for React components defined via 
+`React.createClass`, [ES2015 class definitions][classes] or functions 
+(stateless components). These component definitions must follow certain 
+guidelines in order to be analyzable (see below for more info).
 
 ## Install
 
@@ -31,15 +34,22 @@ Options:
    --pretty              pretty print JSON
    -x, --extension       File extensions to consider. Repeat to define multiple extensions. Default:  [js,jsx]
    -i, --ignore          Folders to ignore. Default:  [node_modules,__tests__]
+   --resolver RESOLVER   Resolver name (findAllComponentDefinitions, findExportedComponentDefinition) or
+      path to a module that exports a resolver.  [findExportedComponentDefinition]
 
 Extract meta information from React components.
 If a directory is passed, it is recursively traversed.
 ```
 
-By default, `react-docgen` will look for the exported component created through `React.createClass` or a class definition in each file. Have a look below for how to customize this behavior.
+By default, `react-docgen` will look for the exported component created through 
+`React.createClass`, a class definition or a function (stateless component) in 
+each file. You can change that behavior with the `--resolver` option, which 
+either expects the name of a built-in resolver or a path to JavaScript module 
+exporting a resolver function. Have a look below for [more information about 
+resolvers](#resolver).
 
-Have a look at `example/` for an example of how to use the result to generate
-a markdown version of the documentation.
+Have a look at `example/` for an example of how to use the result to generate a
+markdown version of the documentation.
 
 ## API
 

bin/__tests__/example/MultipleComponents.js

@@ -0,0 +1,25 @@
+/*
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ *
+ */
+
+var React = require('react');
+
+exports.ComponentA = React.createClass({
+  displayName: 'ComponentA',
+  render: function() {
+    // ...
+  },
+});
+
+exports.ComponentB = React.createClass({
+  displayName: 'ComponentB',
+  render: function() {
+    // ...
+  },
+});

bin/__tests__/example/customResolver.js

@@ -0,0 +1,24 @@
+/*
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ *
+ */
+
+/**
+ * Dummy resolver that always returns the same AST node
+ */
+
+const code = `
+  ({
+    displayName: 'Custom',
+  })
+`;
+
+module.exports = function(ast, recast) {
+  return (new recast.types.NodePath(recast.parse(code)))
+    .get('program', 'body', 0, 'expression');
+};

bin/__tests__/react-docgen-test.js

@@ -204,4 +204,44 @@ describe('react-docgen CLI', () => {
     ]);
   });
 
+  describe('--resolver', () => {
+    pit('accepts the names of built in resolvers', () => {
+      return Promise.all([
+        // No option passed: same as --resolver=findExportedComponentDefinition
+        run([
+          path.join(__dirname, '../../example/components/Component.js'),
+        ]).then(([stdout]) => {
+          expect(stdout).toContain('Component');
+        }),
+
+        run([
+          '--resolver=findExportedComponentDefinition',
+          path.join(__dirname, '../../example/components/Component.js'),
+        ]).then(([stdout]) => {
+          expect(stdout).toContain('Component');
+        }),
+
+        run([
+          '--resolver=findAllComponentDefinitions',
+          path.join(__dirname, './example/MultipleComponents.js'),
+        ]).then(([stdout]) => {
+          expect(stdout).toContain('ComponentA');
+          expect(stdout).toContain('ComponentB');
+        }),
+      ]);
+    });
+
+    pit('accepts a path to a resolver function', () => {
+      return Promise.all([
+        run([
+          '--resolver='+path.join(__dirname, './example/customResolver.js'),
+          path.join(__dirname, '../../example/components/Component.js'),
+        ]).then(([stdout, stderr]) => {
+          console.log(stderr);
+          expect(stdout).toContain('Custom');
+        }),
+      ]);
+    });
+  });
+
 });

bin/react-docgen.js

@@ -9,6 +9,8 @@
  *
  */
 
+/*eslint no-process-exit: 0*/
+
 var argv = require('nomnom')
   .script('react-docgen')
   .help(
@@ -20,46 +22,70 @@ var argv = require('nomnom')
       position: 0,
       help: 'A component file or directory. If no path is provided it reads from stdin.',
       metavar: 'PATH',
-      list: true
+      list: true,
     },
     out: {
       abbr: 'o',
       help: 'store extracted information in FILE',
-      metavar: 'FILE'
+      metavar: 'FILE',
     },
     pretty: {
       help: 'pretty print JSON',
-      flag: true
+      flag: true,
     },
     extension: {
       abbr: 'x',
       help: 'File extensions to consider. Repeat to define multiple extensions. Default:',
       list: true,
-      default: ['js', 'jsx']
+      default: ['js', 'jsx'],
     },
     ignoreDir: {
       abbr: 'i',
       full: 'ignore',
       help: 'Folders to ignore. Default:',
       list: true,
-      default: ['node_modules', '__tests__']
-    }
+      default: ['node_modules', '__tests__'],
+    },
+    resolver: {
+      help: 'Resolver name (findAllComponentDefinitions, findExportedComponentDefinition) or path to a module that exports a resolver.',
+      metavar: 'RESOLVER',
+      default: 'findExportedComponentDefinition',
+    },
   })
   .parse();
 
 var async = require('async');
 var dir = require('node-dir');
 var fs = require('fs');
 var parser = require('../dist/main.js');
+var path = require('path');
 
 var output = argv.out;
 var paths = argv.path || [];
 var extensions = new RegExp('\\.(?:' + argv.extension.join('|') + ')$');
 var ignoreDir = argv.ignoreDir;
+var resolver;
+
+if (argv.resolver) {
+  switch(argv.resolver) {
+    case 'findAllComponentDefinitions':
+      resolver = require('../dist/resolver/findAllComponentDefinitions');
+      break;
+    case 'findExportedComponentDefinition':
+      resolver = require('../dist/resolver/findExportedComponentDefinition');
+      break;
+    default: // treat value as module path
+      resolver = require(path.resolve(process.cwd(), argv.resolver));
+  }
+}
+
+function parse(source) {
+  return parser.parse(source, resolver);
+}
 
-function writeError(msg, path) {
+function writeError(msg, filePath) {
   if (path) {
-    process.stderr.write('Error with path "' + path + '": ');
+    process.stderr.write('Error with path "' + filePath + '": ');
   }
   process.stderr.write(msg + '\n');
   if (msg instanceof Error) {
@@ -84,19 +110,19 @@ function exitWithResult(result) {
   process.exit(0);
 }
 
-function traverseDir(path, result, done) {
+function traverseDir(filePath, result, done) {
   dir.readFiles(
-    path,
+    filePath,
     {
       match: extensions,
-      excludeDir: ignoreDir
+      excludeDir: ignoreDir,
     },
     function(error, content, filename, next) {
       if (error) {
         exitWithError(error);
       }
       try {
-        result[filename] = parser.parse(content);
+        result[filename] = parse(content);
       } catch(error) {
         writeError(error, filename);
       }
@@ -127,7 +153,7 @@ if (paths.length === 0) {
   });
   process.stdin.on('end', function () {
     try {
-      exitWithResult(parser.parse(source));
+      exitWithResult(parse(source));
     } catch(error) {
       writeError(error);
     }
@@ -137,21 +163,21 @@ if (paths.length === 0) {
    * 2. Paths are passed.
    */
   var result = Object.create(null);
-  async.eachSeries(paths, function(path, done) {
-    fs.stat(path, function(error, stats) {
+  async.eachSeries(paths, function(filePath, done) {
+    fs.stat(filePath, function(error, stats) {
       if (error) {
-        writeError(error, path);
+        writeError(error, filePath);
         done();
         return;
       }
       if (stats.isDirectory()) {
-        traverseDir(path, result, done);
+        traverseDir(filePath, result, done);
       }
       else {
         try {
-          result[path] = parser.parse(fs.readFileSync(path));
+          result[filePath] = parse(fs.readFileSync(filePath));
         } catch(error) {
-          writeError(error, path);
+          writeError(error, filePath);
         }
         finally {
           done();

example/components/Component.js

@@ -5,6 +5,8 @@ var Foo = require('Foo');
  * General component description.
  */
 var Component = React.createClass({
+  displayName: 'Component',
+
   propTypes: {
     ...Foo.propTypes,
     /**

package.json

@@ -46,6 +46,9 @@
       "bin",
       "src"
     ],
+    "testPathIgnorePatterns": [
+      "/bin/__tests__/example/"
+    ],
     "unmockedModulePathPatterns": [
       "node_modules",
       "tests/utils",