Replace espree and doctrine with typescript in docgen.

packages/docgen/package.json

@@ -22,13 +22,12 @@
 		"docgen": "./bin/cli.js"
 	},
 	"dependencies": {
-		"doctrine": "^2.1.0",
-		"espree": "^4.0.0",
 		"lodash": "^4.17.15",
 		"mdast-util-inject": "1.1.0",
 		"optionator": "0.8.2",
 		"remark": "10.0.1",
 		"remark-parse": "6.0.3",
+		"typescript": "3.8.3",
 		"unified": "7.1.0"
 	},
 	"publishConfig": {

packages/docgen/scripts/dump-ast.js

@@ -0,0 +1,16 @@
+/**
+ * External dependencies
+ */
+const ts = require( 'typescript' );
+const { readFileSync } = require( 'fs' );
+const { inspect } = require( 'util' );
+
+const filename = process.argv[ 2 ];
+
+const sourceFile = ts.createSourceFile(
+	filename,
+	readFileSync( filename ).toString(),
+	ts.ScriptTarget.ESNext
+);
+
+process.stdout.write( inspect( sourceFile, false, null ) );

packages/docgen/src/compile.js

@@ -0,0 +1,52 @@
+const ts = require( 'typescript' );
+const { readFileSync } = require( 'fs' );
+
+const { getExportStatements } = require( './get-export-statements' );
+
+/**
+ * Function that takes file path and returns compiled result
+ *
+ * @param {string} filePath the path to the file to be compiled
+ */
+module.exports = function( filePath ) {
+	const options = {
+		allowJs: true,
+	};
+	const host = ts.createCompilerHost( options, true );
+	const raw = readFileSync( filePath ).toString();
+	const code = raw
+		// typescript interprets @wordpress in @example code as a JSDoc tag.
+		// So, it should be replaced for the time being.
+		// They're restored in get-jsdoc-from-statement.js
+		.replace( /@wordpress/g, '__WORDPRESS_IMPORT__' )
+		// When <caption>ES(5|Next)<\/caption> exists next to @example tag,
+		// typescript cannot parse code correctly.
+		// So, they're removed.
+		.replace( /@example\s+<caption>ES(5|Next)<\/caption>/g, '@example' );
+	const internalSourceFile = ts.createSourceFile(
+		filePath,
+		code,
+		options.target,
+		true
+	);
+
+	host.getSourceFile = () => internalSourceFile;
+	host.readFile = () => code;
+
+	const program = ts.createProgram( [ filePath ], options, host );
+
+	const typeChecker = program.getTypeChecker();
+	const sourceFile = program.getSourceFile( filePath );
+	const exportStatements = getExportStatements( sourceFile );
+
+	// Without the line below, sourceFile.fileName is set to
+	// /gutenberg/node_modules/typescript/lib/lib.es2020.full.d.ts
+	sourceFile.fileName = filePath;
+
+	return {
+		program,
+		typeChecker,
+		sourceFile,
+		exportStatements,
+	};
+};

packages/docgen/src/get-export-entries.js

@@ -1,103 +1,109 @@
 /**
  * External dependencies
  */
-const { get } = require( 'lodash' );
+const { SyntaxKind } = require( 'typescript' );
+
+const { hasExportModifier, hasDefaultModifier } = require( './has-modifier' );
+
+/**
+ * @typedef {import('typescript').Statement} Statement
+ */
+
+/**
+ * @typedef ExportEntry
+ *
+ * @property {string} localName    name of an exported entry in its local file.
+ * @property {string} exportedName name of an exported entry in export statement.
+ * @property {?string} module      which file the name exported from.
+ */
 
 /**
  * Returns the export entry records of the given export statement.
  * Unlike [the standard](http://www.ecma-international.org/ecma-262/9.0/#exportentry-record),
  * the `importName` and the `localName` are merged together.
  *
- * @param {Object} token Espree node representing an export.
+ * @param {Statement} statement TypeScript AST node representing an export.
  *
- * @return {Array} Exported entry records. Example:
+ * @return {Array<ExportEntry>} Exported entry records. Example:
  * [ {
  *    localName: 'localName',
  *    exportName: 'exportedName',
  *    module: null,
- *    lineStart: 2,
- *    lineEnd: 3,
  * } ]
  */
-module.exports = function( token ) {
-	if ( token.type === 'ExportDefaultDeclaration' ) {
-		const getLocalName = ( t ) => {
-			let name;
-			switch ( t.declaration.type ) {
-				case 'Identifier':
-					name = t.declaration.name;
-					break;
-				case 'AssignmentExpression':
-					name = t.declaration.left.name;
-					break;
-				//case 'FunctionDeclaration'
-				//case 'ClassDeclaration'
-				default:
-					name = get( t.declaration, [ 'id', 'name' ], '*default*' );
-			}
-			return name;
-		};
+module.exports = function( statement ) {
+	if ( hasExportModifier( statement ) ) {
+		if ( hasDefaultModifier( statement ) ) {
+			return [
+				{
+					localName: statement.name
+						? statement.name.text
+						: '*default*',
+					exportName: 'default',
+					module: null,
+				},
+			];
+		}
+
+		if ( statement.kind === SyntaxKind.VariableStatement ) {
+			return statement.declarationList.declarations.map( ( decl ) => {
+				return {
+					localName: decl.name.text,
+					exportName: decl.name.text,
+					module: null,
+				};
+			} );
+		}
+
 		return [
 			{
-				localName: getLocalName( token ),
-				exportName: 'default',
+				localName: statement.name.text,
+				exportName: statement.name.text,
 				module: null,
-				lineStart: token.loc.start.line,
-				lineEnd: token.loc.end.line,
 			},
 		];
 	}
 
-	if ( token.type === 'ExportAllDeclaration' ) {
+	if ( statement.kind === SyntaxKind.ExportAssignment ) {
+		const getLocalName = ( s ) => {
+			switch ( s.expression.kind ) {
+				case SyntaxKind.Identifier:
+					return s.expression.text;
+				default:
+					return '*default*';
+			}
+		};
+
 		return [
 			{
-				localName: '*',
-				exportName: null,
-				module: token.source.value,
-				lineStart: token.loc.start.line,
-				lineEnd: token.loc.end.line,
+				localName: getLocalName( statement ),
+				exportName: 'default',
+				module: null,
 			},
 		];
 	}
 
-	const name = [];
-	if ( token.declaration === null ) {
-		token.specifiers.forEach( ( specifier ) =>
-			name.push( {
-				localName: specifier.local.name,
-				exportName: specifier.exported.name,
-				module: get( token.source, [ 'value' ], null ),
-				lineStart: specifier.loc.start.line,
-				lineEnd: specifier.loc.end.line,
-			} )
-		);
-		return name;
-	}
-
-	switch ( token.declaration.type ) {
-		case 'ClassDeclaration':
-		case 'FunctionDeclaration':
-			name.push( {
-				localName: token.declaration.id.name,
-				exportName: token.declaration.id.name,
-				module: null,
-				lineStart: token.declaration.loc.start.line,
-				lineEnd: token.declaration.loc.end.line,
-			} );
-			break;
-
-		case 'VariableDeclaration':
-			token.declaration.declarations.forEach( ( declaration ) => {
-				name.push( {
-					localName: declaration.id.name,
-					exportName: declaration.id.name,
-					module: null,
-					lineStart: token.declaration.loc.start.line,
-					lineEnd: token.declaration.loc.end.line,
-				} );
-			} );
-			break;
-	}
+	// statement.kind === SyntaxKind.ExportDeclaration
 
-	return name;
+	return statement.exportClause
+		? // export { a, b } from './module'
+		  statement.exportClause.elements.map( ( element ) => {
+				return {
+					localName: element.propertyName
+						? element.propertyName.text
+						: element.name.text,
+					exportName: element.name.text,
+					module: statement.moduleSpecifier
+						? statement.moduleSpecifier.text
+						: null,
+				};
+		  } )
+		: // export * from './namespace-module';
+		  [
+				{
+					localName: '*',
+					exportName: null,
+					module: statement.moduleSpecifier.text,
+				},
+		  ];
 };