From ef5df5e0ac0d3e29bb574685d034f4eb301f35c7 Mon Sep 17 00:00:00 2001 From: KHeo Date: Fri, 24 Apr 2020 01:55:42 +0900 Subject: [PATCH 1/7] Replace espree with babel. --- package-lock.json | 56 +---------------------------------- packages/docgen/package.json | 2 +- packages/docgen/src/engine.js | 22 +++++++------- 3 files changed, 14 insertions(+), 66 deletions(-) diff --git a/package-lock.json b/package-lock.json index 149f6c5168c811..4d235361eae192 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10098,8 +10098,8 @@ "version": "file:packages/docgen", "dev": true, "requires": { + "@babel/parser": "^7.9.2", "doctrine": "^2.1.0", - "espree": "^4.0.0", "lodash": "^4.17.15", "mdast-util-inject": "1.1.0", "optionator": "0.8.2", @@ -10769,45 +10769,6 @@ "negotiator": "0.6.1" } }, - "acorn": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/acorn/-/acorn-5.7.1.tgz", - "integrity": "sha512-d+nbxBUGKg7Arpsvbnlq61mc12ek3EY8EQldM3GPAhWJ1UVxC6TDGbIvUMNU6obBX3i1+ptCIzV4vq0gFPEGVQ==", - "dev": true - }, - "acorn-globals": { - "version": "4.3.4", - "resolved": "https://registry.npmjs.org/acorn-globals/-/acorn-globals-4.3.4.tgz", - "integrity": "sha512-clfQEh21R+D0leSbUdWf3OcfqyaCSAQ8Ryq00bofSekfr9W8u1jyYZo6ir0xu9Gtcf7BjcHJpnbZH7JOCpP60A==", - "dev": true, - "requires": { - "acorn": "^6.0.1", - "acorn-walk": "^6.0.1" - }, - "dependencies": { - "acorn": { - "version": "6.4.1", - "resolved": "https://registry.npmjs.org/acorn/-/acorn-6.4.1.tgz", - "integrity": "sha512-ZVA9k326Nwrj3Cj9jlh3wGFutC2ZornPNARZwsNYqQYgN0EsV2d53w5RN/co65Ohn4sUAUtb1rSUAOD6XN9idA==", - "dev": true - }, - "acorn-walk": { - "version": "6.2.0", - "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-6.2.0.tgz", - "integrity": "sha512-7evsyfH1cLOCdAzZAd43Cic04yKydNx0cF+7tiA19p1XnLLPU4dpCQOqpjqwokFe//vS0QqfqqjCS2JkiIs0cA==", - "dev": true - } - } - }, - "acorn-jsx": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-4.1.1.tgz", - "integrity": "sha512-JY+iV6r+cO21KtntVvFkD+iqjtdpRUpGqKWgfkCdZq1R+kbreEl8EcdcJR4SmiIgsIQT33s6QzheQ9a275Q8xw==", - "dev": true, - "requires": { - "acorn": "^5.0.3" - } - }, "acorn-walk": { "version": "7.1.1", "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-7.1.1.tgz", @@ -19241,21 +19202,6 @@ "integrity": "sha512-qzm/XxIbxm/FHyH341ZrbnMUpe+5Bocte9xkmFMzPMjRaZMcXww+MpBptFvtU+79L362nqiLhekCxCxDPaUMBQ==", "dev": true }, - "espree": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/espree/-/espree-4.0.0.tgz", - "integrity": "sha512-kapdTCt1bjmspxStVKX6huolXVV5ZfyZguY1lcfhVVZstce3bqxH9mcLzNn3/mlgW6wQ732+0fuG9v7h0ZQoKg==", - "dev": true, - "requires": { - "acorn": "^5.6.0", - "acorn-jsx": "^4.1.1" - } - }, - "esprima": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" - }, "esquery": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.2.0.tgz", diff --git a/packages/docgen/package.json b/packages/docgen/package.json index 8ce4df2ccb83ee..27c10d1977cbda 100644 --- a/packages/docgen/package.json +++ b/packages/docgen/package.json @@ -23,7 +23,7 @@ }, "dependencies": { "doctrine": "^2.1.0", - "espree": "^4.0.0", + "@babel/parser": "^7.9.2", "lodash": "^4.17.15", "mdast-util-inject": "1.1.0", "optionator": "0.8.2", diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index 55b50c8c0b7bba..20d56103222045 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -1,25 +1,27 @@ /** * External dependencies. */ -const espree = require( 'espree' ); +const babel = require( '@babel/parser' ); const { flatten } = require( 'lodash' ); /** * Internal dependencies. */ const getIntermediateRepresentation = require( './get-intermediate-representation' ); +const babelConfig = require( '../../../babel.config' ); -const getAST = ( source ) => - espree.parse( source, { - attachComment: true, - loc: true, - ecmaVersion: 2018, - ecmaFeatures: { - jsx: true, - }, - sourceType: 'module', +const getAST = ( source ) => { + const { presets, plugins } = babelConfig( { + cache: () => {}, // To bypass api.cache is not a function error. } ); + return babel.parse( source, { + presets, + plugins: [ ...plugins, 'jsx' ], + sourceType: 'module', + } ).program; // unlike espree, the root of babel AST is File, not Program. +}; + const getExportTokens = ( ast ) => ast.body.filter( ( node ) => [ From 39be5f731b2344e104b29b24989b65191a1cc2c6 Mon Sep 17 00:00:00 2001 From: KHeo Date: Fri, 24 Apr 2020 11:52:28 +0900 Subject: [PATCH 2/7] Fix test failure. --- packages/docgen/src/engine.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index 20d56103222045..41b588113339e9 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -15,7 +15,7 @@ const getAST = ( source ) => { cache: () => {}, // To bypass api.cache is not a function error. } ); - return babel.parse( source, { + return babel.parse( source || '', { presets, plugins: [ ...plugins, 'jsx' ], sourceType: 'module', From 520021484ed298cd3bd2f053d3e02fd91392b35e Mon Sep 17 00:00:00 2001 From: KHeo Date: Fri, 24 Apr 2020 12:22:32 +0900 Subject: [PATCH 3/7] Fix lint. --- packages/docgen/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docgen/package.json b/packages/docgen/package.json index 27c10d1977cbda..30b90a61a5b8e2 100644 --- a/packages/docgen/package.json +++ b/packages/docgen/package.json @@ -22,8 +22,8 @@ "docgen": "./bin/cli.js" }, "dependencies": { - "doctrine": "^2.1.0", "@babel/parser": "^7.9.2", + "doctrine": "^2.1.0", "lodash": "^4.17.15", "mdast-util-inject": "1.1.0", "optionator": "0.8.2", From e78cc61260404a880bc4591a5ac7ed72eff84518 Mon Sep 17 00:00:00 2001 From: KHeo Date: Mon, 27 Apr 2020 12:52:51 +0900 Subject: [PATCH 4/7] Remove config. --- packages/docgen/src/engine.js | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index 41b588113339e9..de038b21180f35 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -8,18 +8,12 @@ const { flatten } = require( 'lodash' ); * Internal dependencies. */ const getIntermediateRepresentation = require( './get-intermediate-representation' ); -const babelConfig = require( '../../../babel.config' ); const getAST = ( source ) => { - const { presets, plugins } = babelConfig( { - cache: () => {}, // To bypass api.cache is not a function error. - } ); - return babel.parse( source || '', { - presets, - plugins: [ ...plugins, 'jsx' ], + plugins: [ 'jsx' ], sourceType: 'module', - } ).program; // unlike espree, the root of babel AST is File, not Program. + } ).program; }; const getExportTokens = ( ast ) => From 7048609c1087c0928cbb45cf7934e44c0504bb09 Mon Sep 17 00:00:00 2001 From: KHeo Date: Mon, 27 Apr 2020 13:55:32 +0900 Subject: [PATCH 5/7] Update package-lock.json --- package-lock.json | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/package-lock.json b/package-lock.json index 4d235361eae192..db87472d671ddd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10769,6 +10769,30 @@ "negotiator": "0.6.1" } }, + "acorn": { + "version": "6.4.1", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-6.4.1.tgz", + "integrity": "sha512-ZVA9k326Nwrj3Cj9jlh3wGFutC2ZornPNARZwsNYqQYgN0EsV2d53w5RN/co65Ohn4sUAUtb1rSUAOD6XN9idA==", + "dev": true + }, + "acorn-globals": { + "version": "4.3.4", + "resolved": "https://registry.npmjs.org/acorn-globals/-/acorn-globals-4.3.4.tgz", + "integrity": "sha512-clfQEh21R+D0leSbUdWf3OcfqyaCSAQ8Ryq00bofSekfr9W8u1jyYZo6ir0xu9Gtcf7BjcHJpnbZH7JOCpP60A==", + "dev": true, + "requires": { + "acorn": "^6.0.1", + "acorn-walk": "^6.0.1" + }, + "dependencies": { + "acorn-walk": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-6.2.0.tgz", + "integrity": "sha512-7evsyfH1cLOCdAzZAd43Cic04yKydNx0cF+7tiA19p1XnLLPU4dpCQOqpjqwokFe//vS0QqfqqjCS2JkiIs0cA==", + "dev": true + } + } + }, "acorn-walk": { "version": "7.1.1", "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-7.1.1.tgz", @@ -19202,6 +19226,11 @@ "integrity": "sha512-qzm/XxIbxm/FHyH341ZrbnMUpe+5Bocte9xkmFMzPMjRaZMcXww+MpBptFvtU+79L362nqiLhekCxCxDPaUMBQ==", "dev": true }, + "esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" + }, "esquery": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.2.0.tgz", From c1f4deb5598efb4bfd4f4bb15e70fec5f46376b9 Mon Sep 17 00:00:00 2001 From: KHeo Date: Tue, 28 Apr 2020 15:04:37 +0900 Subject: [PATCH 6/7] Use @babel/core instead. --- package-lock.json | 2 +- packages/docgen/package.json | 2 +- packages/docgen/src/engine.js | 7 ++----- 3 files changed, 4 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index db87472d671ddd..0defcaa6e740f1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10098,7 +10098,7 @@ "version": "file:packages/docgen", "dev": true, "requires": { - "@babel/parser": "^7.9.2", + "@babel/core": "^7.9.0", "doctrine": "^2.1.0", "lodash": "^4.17.15", "mdast-util-inject": "1.1.0", diff --git a/packages/docgen/package.json b/packages/docgen/package.json index 30b90a61a5b8e2..8ac42fb05336ac 100644 --- a/packages/docgen/package.json +++ b/packages/docgen/package.json @@ -22,7 +22,7 @@ "docgen": "./bin/cli.js" }, "dependencies": { - "@babel/parser": "^7.9.2", + "@babel/core": "^7.9.0", "doctrine": "^2.1.0", "lodash": "^4.17.15", "mdast-util-inject": "1.1.0", diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index de038b21180f35..a6f4ce646193b4 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -1,7 +1,7 @@ /** * External dependencies. */ -const babel = require( '@babel/parser' ); +const babel = require( '@babel/core' ); const { flatten } = require( 'lodash' ); /** @@ -10,10 +10,7 @@ const { flatten } = require( 'lodash' ); const getIntermediateRepresentation = require( './get-intermediate-representation' ); const getAST = ( source ) => { - return babel.parse( source || '', { - plugins: [ 'jsx' ], - sourceType: 'module', - } ).program; + return babel.parse( source || '' ).program; }; const getExportTokens = ( ast ) => From 4dc276c523ea78a48b2b3ecbf4f782c0919049da Mon Sep 17 00:00:00 2001 From: KHeo Date: Wed, 29 Apr 2020 11:49:05 +0900 Subject: [PATCH 7/7] Update doc. --- packages/docgen/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/docgen/README.md b/packages/docgen/README.md index e39594cb4fc644..e4543095e867f6 100644 --- a/packages/docgen/README.md +++ b/packages/docgen/README.md @@ -38,6 +38,12 @@ This command will generate a file named `entry-point-api.md` containing all the * **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token <!-- START TOKEN(my-api) --> and the end token <!-- END TOKEN(my-api) -->. Depends on `--to-token`. * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging. +### Babel Configuration + +`@wordpress/docgen` follows the default [project-wide configuration of Babel](https://babeljs.io/docs/en/next/config-files#project-wide-configuration). Like Babel, it will automatically search for a `babel.config.json` file, or an equivalent one using the [supported extensions](https://babeljs.io/docs/en/next/config-files#supported-file-extensions), in the project root directory. + +Without it, `@wordpress/docgen` runs with the default option. In other words, it cannot parse JSX or other advanced syntaxes. + ## Examples ### Default export