From a374846a6ff8309dd1fe9a7940c012a6426474d9 Mon Sep 17 00:00:00 2001 From: Jason Quense Date: Fri, 1 Mar 2019 11:10:32 -0500 Subject: [PATCH] feat: support all the config resolving related babel options --- README.md | 165 ++++++++++++++++++++++----------------------- src/babelParser.js | 45 +++++++------ 2 files changed, 106 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index 5e309fe7aad..f46c43d29a4 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,6 @@ yarn add react-docgen --dev npm install --save-dev react-docgen ``` - ## CLI Installing the module adds a `react-docgen` executable which allows you to convert @@ -85,7 +84,7 @@ As with the CLI, this will look for the exported component created through `Reac | source | string | The source text | | resolver | function | A function of the form `(ast: ASTNode, recast: Object) => (NodePath|Array)`. Given an AST and a reference to recast, it returns an (array of) NodePath which represents the component definition. | | handlers | Array\ | An array of functions of the form `(documentation: Documentation, definition: NodePath) => void`. Each function is called with a `Documentation` object and a reference to the component definition as returned by `resolver`. Handlers extract relevant information from the definition and augment `documentation`. | -| options | Object | Pass options to react-docgen, see below. | +| opt #### options @@ -104,6 +103,14 @@ Default: `process.cwd()` The working directory that babel configurations will be searched in. +##### ∙ babelrc, babelrcRoots, root, rootMode, configFile, envName + +Type: `boolean` +Default: `true` + +These options, will be passed directly to `babel` for locating and resolving a local config or babelrc. To see +documentation for each option consult the [babel website](https://babeljs.io/docs/en/options#config-loading-options). + ##### ∙ parserOptions Type: `BabelParserOptions` @@ -129,7 +136,7 @@ module.exports = Component; and returns the ObjectExpression to which `` resolves to, or the class declaration itself. -`findAllComponentDefinitions` works similarly, but finds *all* `React.createClass` calls and class definitions, not only the one that is exported. +`findAllComponentDefinitions` works similarly, but finds _all_ `React.createClass` calls and class definitions, not only the one that is exported. This makes it easy, together with the utility methods created to analyze the AST, to introduce new or custom resolver methods. For example, a resolver could look for plain ObjectExpressions with a `render` method. @@ -145,7 +152,7 @@ For example, while the `propTypesHandler` expects the prop types definition to b - Modules have to export a single component, and only that component is analyzed. - When using `React.createClass`, the component definition (the value passed to it) must resolve to an object literal. -- When using classes, the class must either `extend React.Component` *or* define a `render()` method. +- When using classes, the class must either `extend React.Component` _or_ define a `render()` method. - `propTypes` must be an object literal or resolve to an object literal in the same file. - The `return` statement in `getDefaultProps` must contain an object literal. @@ -179,14 +186,11 @@ MyComponent.propTypes = { bar: function(props, propName, componentName) { // ... }, - baz: PropTypes.oneOfType([ - PropTypes.number, - PropTypes.string - ]), + baz: PropTypes.oneOfType([PropTypes.number, PropTypes.string]), }; MyComponent.defaultProps = { - bar: 21 + bar: 21, }; export default MyComponent; @@ -263,7 +267,6 @@ type Props = { * General component description. */ export default class MyComponent extends Component { - props: Props; render(): ?ReactElement { @@ -276,83 +279,77 @@ we are getting this output: ```json { - "description":"General component description.", - "props":{ - "primitive":{ - "flowType":{ "name":"number" }, - "required":true, - "description":"Description of prop \"foo\"." + "description": "General component description.", + "props": { + "primitive": { + "flowType": { "name": "number" }, + "required": true, + "description": "Description of prop \"foo\"." }, - "literalsAndUnion":{ - "flowType":{ - "name":"union", - "raw":"'string' | 'otherstring' | number", - "elements":[ - { "name":"literal", "value":"'string'" }, - { "name":"literal", "value":"'otherstring'" }, - { "name":"number" } + "literalsAndUnion": { + "flowType": { + "name": "union", + "raw": "'string' | 'otherstring' | number", + "elements": [ + { "name": "literal", "value": "'string'" }, + { "name": "literal", "value": "'otherstring'" }, + { "name": "number" } ] }, - "required":true, - "description":"Description of prop \"bar\"." + "required": true, + "description": "Description of prop \"bar\"." }, - "arr":{ - "flowType":{ - "name":"Array", - "elements":[ - { "name":"any" } - ], - "raw":"Array" + "arr": { + "flowType": { + "name": "Array", + "elements": [{ "name": "any" }], + "raw": "Array" }, - "required":true + "required": true }, - "func":{ - "flowType":{ - "name":"signature", - "type":"function", - "raw":"(value: string) => void", - "signature":{ - "arguments":[ - { "name":"value", "type":{ "name":"string" } } - ], - "return":{ "name":"void" } + "func": { + "flowType": { + "name": "signature", + "type": "function", + "raw": "(value: string) => void", + "signature": { + "arguments": [{ "name": "value", "type": { "name": "string" } }], + "return": { "name": "void" } } }, - "required":false + "required": false }, - "noParameterName":{ - "flowType":{ - "name":"signature", - "type":"function", - "raw":"string => void", - "signature":{ - "arguments":[ - { "name":"", "type":{ "name":"string" } } - ], - "return":{ "name":"void" } + "noParameterName": { + "flowType": { + "name": "signature", + "type": "function", + "raw": "string => void", + "signature": { + "arguments": [{ "name": "", "type": { "name": "string" } }], + "return": { "name": "void" } } }, - "required":false + "required": false }, - "obj":{ - "flowType":{ - "name":"signature", - "type":"object", - "raw":"{ subvalue: ?boolean }", - "signature":{ - "properties":[ + "obj": { + "flowType": { + "name": "signature", + "type": "object", + "raw": "{ subvalue: ?boolean }", + "signature": { + "properties": [ { - "key":"subvalue", - "value":{ - "name":"boolean", - "nullable":true, - "required":true + "key": "subvalue", + "value": { + "name": "boolean", + "nullable": true, + "required": true } } ] } }, - "required":false + "required": false } } } @@ -362,18 +359,18 @@ we are getting this output: Here is a list of all the available types and its result structure. -Name | Examples | Result -------------- | ------------- | ------------- -Simple | ```let x: string;```
```let x: number;```
```let x: boolean;```
```let x: any;```
```let x: void;```
```let x: Object;```
```let x: String;```
```let x: MyClass;``` | ```{ "name": "" }``` -Literals | ```let x: 'foo';```
```let x: 1;```
```let x: true;``` | ```{ "name": "literal", "value": "" }``` -Typed Classes | ```let x: Array;```
```let x: Class;```
```let x: MyClass;``` | ```{ "name": "", "elements": [{ }, ...] }``` -Object Signature | ```let x: { foo: string, bar?: mixed };```
```let x: { [key: string]: string, foo: number };``` | ```{ "name": "signature", "type": "object", "raw": "", "signature": { "properties": [{ "key": ""|{ }, "value": { , "required": } }, ...] } }``` -Function Signature | ```let x: (x: string) => void;``` | ```{ "name": "signature", "type": "function", "raw": "", "signature": { "arguments": [{ "name": "", "type": { } }, ...], "return": { } } }``` -Callable-Object/Function-Object Signature | ```let x: { (x: string): void, prop: string };``` | ```{ "name": "signature", "type": "object", "raw": "", "signature": { "properties": [{ "key": ""|{ }, "value": { , "required": } }, ...], "constructor": { } } }``` -Tuple | ```let x: [foo, "value", number];``` | ```{ "name": "tuple", "raw": "", "elements": [{ }, ...] }``` -Union | ```let x: number | string;``` | ```{ "name": "union", "raw": "", "elements": [{ }, ...] }``` -Intersect | ```let x: number & string;``` | ```{ "name": "intersect", "raw": "", "elements": [{ }, ...] }``` -Nullable modifier | ```let x: ?number;``` | ```{ "name": "number", "nullable": true }``` +| Name | Examples | Result | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Simple | `let x: string;`
`let x: number;`
`let x: boolean;`
`let x: any;`
`let x: void;`
`let x: Object;`
`let x: String;`
`let x: MyClass;` | `{ "name": "" }` | +| Literals | `let x: 'foo';`
`let x: 1;`
`let x: true;` | `{ "name": "literal", "value": "" }` | +| Typed Classes | `let x: Array;`
`let x: Class;`
`let x: MyClass;` | `{ "name": "", "elements": [{ }, ...] }` | +| Object Signature | `let x: { foo: string, bar?: mixed };`
`let x: { [key: string]: string, foo: number };` | `{ "name": "signature", "type": "object", "raw": "", "signature": { "properties": [{ "key": ""|{ }, "value": { , "required": } }, ...] } }` | +| Function Signature | `let x: (x: string) => void;` | `{ "name": "signature", "type": "function", "raw": "", "signature": { "arguments": [{ "name": "", "type": { } }, ...], "return": { } } }` | +| Callable-Object/Function-Object Signature | `let x: { (x: string): void, prop: string };` | `{ "name": "signature", "type": "object", "raw": "", "signature": { "properties": [{ "key": ""|{ }, "value": { , "required": } }, ...], "constructor": { } } }` | +| Tuple | `let x: [foo, "value", number];` | `{ "name": "tuple", "raw": "", "elements": [{ }, ...] }` | +| Union | `let x: number | string;` | `{ "name": "union", "raw": "", "elements": [{ }, ...] }` | +| Intersect | `let x: number & string;` | `{ "name": "intersect", "raw": "", "elements": [{ }, ...] }` | +| Nullable modifier | `let x: ?number;` | `{ "name": "number", "nullable": true }` | ## Result data structure @@ -402,14 +399,14 @@ The structure of the JSON blob / JavaScript object is as follows: ["composes": ] } ``` + (`[...]` means the property may not exist if such information was not found in the component definition) -- ``: For each prop that was found, there will be an entry in `props` under the same name. -- ``: The name of the type, which is usually corresponds to the function name in `React.PropTypes`. However, for types define with `oneOf`, we use `"enum"` and for `oneOfType` we use `"union"`. If a custom function is provided or the type cannot be resolved to anything of `React.PropTypes`, we use `"custom"`. +- ``: For each prop that was found, there will be an entry in `props` under the same name. +- ``: The name of the type, which is usually corresponds to the function name in `React.PropTypes`. However, for types define with `oneOf`, we use `"enum"` and for `oneOfType` we use `"union"`. If a custom function is provided or the type cannot be resolved to anything of `React.PropTypes`, we use `"custom"`. - ``: Some types accept parameters which define the type in more detail (such as `arrayOf`, `instanceOf`, `oneOf`, etc). Those are stored in ``. The data type of `` depends on the type definition. - ``: If using flow type this property contains the parsed flow type as can be seen in the table above. - [react]: http://facebook.github.io/react/ [flow]: http://flowtype.org/ [recast]: https://github.com/benjamn/recast diff --git a/src/babelParser.js b/src/babelParser.js index 0cb9ba9d960..046e58bf090 100644 --- a/src/babelParser.js +++ b/src/babelParser.js @@ -43,56 +43,61 @@ type ParserOptions = { tokens?: boolean, }; -export type Options = { +type BabelOptions = { cwd?: string, filename?: string, + envName?: string, + babelrc?: boolean, + root?: string, + rootMode?: string, + configFile?: string | false, + babelrcRoots?: true | string | string[], +}; + +export type Options = BabelOptions & { parserOptions?: ParserOptions, }; -function buildOptions({ - cwd, - filename, - parserOptions, -}: Options): ParserOptions { - let options = { +function buildOptions( + parserOptions: ?ParserOptions, + babelOptions: BabelOptions, +): ParserOptions { + let parserOpts = { plugins: [], }; if (parserOptions) { - options = { + parserOpts = { ...parserOptions, plugins: parserOptions.plugins ? [...parserOptions.plugins] : [], }; } - const partialConfig = babel.loadPartialConfig({ - cwd, - filename, - }); + const partialConfig = babel.loadPartialConfig(babelOptions); - if (!partialConfig.hasFilesystemConfig() && options.plugins.length === 0) { - options.plugins = [...defaultPlugins]; + if (!partialConfig.hasFilesystemConfig() && parserOpts.plugins.length === 0) { + parserOpts.plugins = [...defaultPlugins]; } // Recast needs tokens to be in the tree // $FlowIssue tokens is clearly in the Options - options.tokens = true; + parserOpts.tokens = true; // Ensure we always have estree plugin enabled, if we add it a second time // here it does not matter - options.plugins.push('estree'); + parserOpts.plugins.push('estree'); - return options; + return parserOpts; } export default function buildParse(options?: Options = {}) { - const parserOpts = buildOptions(options); + const { parserOptions, ...babelOptions } = options; + const parserOpts = buildOptions(parserOptions, babelOptions); return { parse(src: string) { return babel.parseSync(src, { parserOpts, - cwd: options.cwd, - filename: options.filename, + ...babelOptions, }); }, };