Generate TypesScript Library Declaration (#2016)

* Initial ts processing script

* Process jsx files only

* Change script name

* Allow console.log in scripts folder

* Pass correct file list to process

* Generate declaation files for each converted file

* Monitor all ts errors via preEmitDiagnostics and emitted ones

* Fix gathering diagnostics

* Fix ReactNode type

* Disable isolatedModules option

* Add api extractor

* Remove flow-to-ts internal from flow checking

* Inline utility types

* Fix file handler event

* Remove .typescript folder from flow check

* Fix textConsts

* Update react import

* Fix react node

* Fix freezed consts types

* Fixes of consts/enums

* Fix ts errors

* Deduplicate yarn

* Fix yarn lock

* Fixe ts errors

* Fix flow

* Remove forwardRef generic params

* Fix object lookup

* Fix object lookup type

* Fix flow and ts errors in accordion

* Fix error

* Generate global API declaration

* Change types folder

* Fix linters

* Add building types to package build and CI

* Remove out dir from ts cfg

* Remove types dir at the begining

* Fix typo in props name of accordion

* Resuse tsconfig.json in typsecript compiler api

* Emit declaration only

* Export prop types with unique names

* Fix typo

Author: coderitual

.flowconfig

@@ -1,6 +1,7 @@
 [ignore]
 <PROJECT_ROOT>/node_modules/.*gulp-prettify
-[include]
+<PROJECT_ROOT>/node_modules/@khanacademy/flow-to-ts/test.json
+<PROJECT_ROOT>/.typescript/**
 
 [libs]
 

.gitignore

@@ -2,6 +2,7 @@ dist/
 esm/
 commonjs/
 /css/
+types/
 .scss-lint.yml
 .editorconfig
 .eslintrc-es5
@@ -16,6 +17,8 @@ package-lock.json
 yarn-error.log
 .storybook-static
 .cache
+.typescript
+temp
 
 # Generated images
 /src/images/*.js

.storybook/preview.js

@@ -1,4 +1,4 @@
-import React from 'react';
+import * as React from 'react';
 import {
   Title,
   Subtitle,

api-extractor.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/.typescript/index.d.ts",
+
+  "bundledPackages": [],
+
+  "compiler": {},
+
+  "apiReport": {
+    "enabled": false,
+    "reportFolder": "<projectFolder>/.typescript/"
+  },
+
+  "docModel": {
+    "enabled": false,
+    "apiJsonFilePath":  "<projectFolder>/.typescript/"
+  },
+
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/types/<unscopedPackageName>.d.ts"
+  },
+
+  "tsdocMetadata": {},
+
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "extractorMessageReporting": {
+      "ae-missing-release-tag": {
+        "logLevel": "none"
+      },
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

package.json

@@ -7,11 +7,14 @@
   "license": "GPL-3.0-only",
   "module": "esm/index.js",
   "main": "commonjs/index.js",
+  "types": "types/brainly-style-guide.d.ts",
+  "typings": "types/brainly-style-guide.d.ts",
   "files": [
     "src/",
     "esm/",
     "commonjs/",
-    "css/"
+    "css/",
+    "types/"
   ],
   "engines": {
     "node": ">=8.0.0",
@@ -32,6 +35,8 @@
     "@babel/preset-typescript": "^7.12.1",
     "@brainly/s3": "^4.4.0",
     "@hot-loader/react-dom": "^16.8.6",
+    "@khanacademy/flow-to-ts": "^0.1.9",
+    "@microsoft/api-extractor": "^7.13.0",
     "@storybook/addon-a11y": "@next",
     "@storybook/addon-actions": "@next",
     "@storybook/addon-docs": "@next",
@@ -49,7 +54,7 @@
     "del": "^2.2.0",
     "enzyme": "^3.1.0",
     "enzyme-adapter-react-16": "^1.0.1",
-    "eslint": "^6.1.0",
+    "eslint": "^7.18.0",
     "eslint-config-brainly-react": "^2.7.0",
     "eslint-config-prettier": "^6.0.0",
     "eslint-plugin-babel": "^5.3.0",
@@ -80,10 +85,12 @@
     "http-server": "^0.9.0",
     "husky": "^0.11.3",
     "jest": "^24.0.0",
+    "jscodeshift": "^0.11.0",
     "polished": "^4.0.3",
     "postcss": "^8.2.2",
     "postcss-loader": "^4.1.0",
     "prettier": "^1.18.2",
+    "progress-estimator": "^0.3.0",
     "query-string": "^6.5.0",
     "react": "^16.2.0",
     "react-dom": "^16.2.0",
@@ -101,6 +108,7 @@
     "tailwindcss": "^2.0.1",
     "terser-webpack-plugin": "^1.2.3",
     "through2": "^2.0.3",
+    "typescript": "^4.1.3",
     "webpack": "^4.6.0",
     "webpack-cli": "^3.3.6",
     "webpack-dev-server": "^3.7.2",
@@ -110,20 +118,21 @@
     "js-lint": "yarn run eslint --ext .js --ext .jsx src/",
     "scss-lint": "sass-lint -c node_modules/sass-lint-config-brainly/.sass-lint.yml -v -q 'src/**/*.scss'",
     "scss-unused-variables": "./scripts/find_scss_unused_variables.sh src/",
-    "js-typecheck": "flow",
+    "js-typecheck": "flow && node ./scripts/build-types.js",
     "build": "gulp build",
     "start": "http-server ./dist -p 8000",
     "deploy": "gulp deploy",
     "postversion": "git push && git push --tags",
     "watch": "gulp build && gulp watch & yarn start",
-    "test": "yarn run scss-lint && yarn run scss-unused-variables && yarn flow && yarn run js-lint && jest",
+    "test": "yarn run scss-lint && yarn run scss-unused-variables && yarn run js-typecheck && yarn run js-lint && jest",
     "eslint": "./node_modules/.bin/eslint",
     "beta:watch": "webpack-dev-server --hot --inline --open --watch --mode=development",
-    "package-clean": "yarn rimraf esm/ commonjs/ css/",
+    "package-clean": "yarn rimraf esm/ commonjs/ css/ types/",
     "package-esm": "BABEL_ENV=esm babel src --out-dir esm --only 'src/components' --only 'src/js' --only 'src/index.js' --ignore '**/*.spec.jsx' --ignore '**/pages/**' --ignore '**/iframe-pages/**' --ignore '**/__mocks__/**'",
     "package-commonjs": "BABEL_ENV=commonjs babel src --out-dir commonjs --only 'src/components' --only 'src/js' --only 'src/index.js' --ignore '**/*.spec.jsx' --ignore '**/pages/**' --ignore '**/iframe-pages/**' --ignore '**/__mocks__/**'",
     "package-css": "node ./scripts/build-css.js",
-    "package-prepare": "yarn package-clean && concurrently --names 'commonjs,esm,css' 'yarn run package-commonjs' 'yarn run package-esm' 'yarn run package-css'",
+    "package-types": "node ./scripts/build-types.js",
+    "package-prepare": "yarn package-clean && concurrently --names 'commonjs,esm,css' 'yarn run package-commonjs' 'yarn run package-esm' 'yarn run package-css' 'yarn run package-types'",
     "prepublishOnly": "yarn package-prepare",
     "storybook": "start-storybook -p 6006 -s ./.storybook/public",
     "storybook-docs": "start-storybook --docs -p 6006 -s ./.storybook/public",

scripts/.eslintrc

@@ -0,0 +1,5 @@
+{
+  "rules": {
+      "no-console": "off"
+  }
+}

scripts/build-types.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const glob = require('glob');
+const path = require('path');
+const fs = require('fs-extra');
+const jsc = require('jscodeshift');
+const flowParser = require('jscodeshift/parser/flow');
+const convert = require('@khanacademy/flow-to-ts/src/convert');
+const ts = require('typescript');
+const apiExtractor = require('@microsoft/api-extractor');
+const tsConfig = require('../tsconfig.json');
+
+const ROOT_DIR = path.resolve(__dirname, '../');
+const SOURCE_DIR = path.join(ROOT_DIR, 'src');
+const DEST_DIR = path.join(ROOT_DIR, '.typescript');
+const TYPES_DIR = path.join(ROOT_DIR, 'types');
+
+const files = glob.sync(
+  `{/components/**/*.{js,jsx},/js/generateRandomString.js,/index.js}`,
+  {
+    ignore: [`/**/{pages,iframe-pages,__mocks__}/*`, '/**/*{stories,spec}.*'],
+    root: SOURCE_DIR,
+  }
+);
+
+console.log(`Found ${files.length} source files.`);
+
+fs.removeSync(DEST_DIR);
+fs.removeSync(TYPES_DIR);
+
+files.forEach(sourceFile => {
+  const flowCode = fs.readFileSync(sourceFile, 'utf-8');
+
+  const ast = jsc(flowCode, {
+    parser: flowParser(),
+  });
+
+  let transformedCode = ast.toSource();
+
+  // Code transformations before converting to typescript
+  // to remove incompatibilities weren't caught by flow-to-ts
+
+  // Remove generic parameters from forwardRef as Flow uses opposite order
+  // forwardRef<Prop, Element> -> forwardRef
+  if (ast.find(jsc.Identifier, {name: 'forwardRef'}).length) {
+    transformedCode = transformedCode.replace(/forwardRef<.*>/g, 'forwardRef');
+  }
+
+  const typescriptCode = convert(transformedCode, {
+    printWidth: 80,
+    singleQuote: true,
+    semi: false,
+    prettier: true,
+    inlineUtilityTypes: true,
+  });
+
+  const sourceExtension = path.extname(sourceFile);
+  const destinationExtension = mapExtension(sourceExtension);
+
+  const relativeSourceFile = path.relative(SOURCE_DIR, sourceFile);
+  const outputFile = path.join(
+    DEST_DIR,
+    relativeSourceFile.replace(sourceExtension, destinationExtension)
+  );
+
+  fs.outputFileSync(outputFile, typescriptCode, noop => noop);
+});
+
+const tsFiles = glob.sync('.typescript/**/*.{ts,tsx}');
+
+const options = {...tsConfig.compilerOptions, declarationDir: '.typescript'};
+
+console.log('Generating declaration files...');
+
+const program = ts.createProgram(tsFiles, options);
+
+const res = program.emit();
+
+const allDiagnostics = ts
+  .getPreEmitDiagnostics(program)
+  .concat(res.diagnostics);
+
+allDiagnostics.forEach(diagnostics => {
+  if (diagnostics.file) {
+    const {line, character} = diagnostics.file.getLineAndCharacterOfPosition(
+      diagnostics.start
+    );
+    const message = ts.flattenDiagnosticMessageText(
+      diagnostics.messageText,
+      '\n'
+    );
+
+    console.log(
+      `${diagnostics.file.fileName} (${line + 1}, ${character + 1}): ${message}`
+    );
+  } else {
+    console.log(ts.flattenDiagnosticMessageText(diagnostics.messageText, '\n'));
+  }
+});
+
+console.log(
+  `Found ${allDiagnostics.length > 0 ? allDiagnostics.length : 'No'} errors.`
+);
+
+// Extract API
+// Combine all d.ts files into one library.d.ts
+
+console.log('Generating library API declaration...');
+
+const apiExtractorJsonPath = path.join(ROOT_DIR, 'api-extractor.json');
+
+const extractorConfig = apiExtractor.ExtractorConfig.loadFileAndPrepare(
+  apiExtractorJsonPath
+);
+
+fs.ensureDirSync(TYPES_DIR);
+
+const extractorResult = apiExtractor.Extractor.invoke(extractorConfig, {
+  localBuild: true,
+  showVerboseMessages: true,
+});
+
+if (extractorResult.succeeded) {
+  console.log(`API Extractor completed successfully`);
+  process.exitCode = 0;
+} else {
+  console.error(
+    `API Extractor completed with ${extractorResult.errorCount} errors` +
+      ` and ${extractorResult.warningCount} warnings`
+  );
+  process.exitCode = 1;
+}
+
+function mapExtension(extension = '') {
+  const map = {
+    '.js': '.ts',
+    '.jsx': '.tsx',
+  };
+
+  const ext = map[extension];
+
+  if (!ext) {
+    throw new Error(
+      `Extension '${extension}' doesn't have matching element in map.`
+    );
+  }
+
+  return ext;
+}

src/_docs/blocks/DocsStory.jsx

@@ -1,6 +1,6 @@
 // @flow
 
-import React from 'react';
+import * as React from 'react';
 import deprecate from 'util-deprecate';
 import dedent from 'ts-dedent';
 import {

src/_docs/blocks/IconGallery.jsx

@@ -1,7 +1,6 @@
 // @flow
 
-import React from 'react';
-import type {Node} from 'react';
+import * as React from 'react';
 import {styled} from '@storybook/theming';
 import {ResetWrapper} from '@storybook/components/dist/typography/DocumentFormatting';
 
@@ -43,7 +42,7 @@ const List = styled.div({
 interface IconItemProps {
   name: string;
   size: number;
-  children: Node;
+  children: React.Node;
 }
 
 export const IconItem = ({name, size, children}: IconItemProps) => (
@@ -54,7 +53,7 @@ export const IconItem = ({name, size, children}: IconItemProps) => (
 );
 
 interface IconGalleryProps {
-  children: Node;
+  children: React.Node;
 }
 
 export const IconGallery = ({children, ...props}: IconGalleryProps) => (