chore: properly package .ts and .d.ts files (#6257)

* fix: package .ts sources

* chore: add generating type defs

* chore: copy generated type defs into dist dir

* chore: fix adding generated def files

* chore: remove unnecessary imports

* chore: make handcrafted files reference generated

* chore: replace AnyDuringMigration with any

* chore: use replace instead of regex-replace

* chore: use value in config instead of magic strings

* chore: remove blockly.d.ts

* chore: update jsdocs

* chore: remove old references to typings

gulpfile.js

@@ -32,8 +32,6 @@ module.exports = {
   buildAdvancedCompilationTest: buildTasks.advancedCompilationTest,
   buildJavaScript: buildTasks.javaScript,
   buildJavaScriptAndDeps: buildTasks.javaScriptAndDeps,
-  // TODO(5621): Re-enable once typings generation is fixed.
-  // checkin: gulp.parallel(buildTasks.checkinBuilt, typings.checkinTypings),
   checkin: gulp.parallel(buildTasks.checkinBuilt),
   checkinBuilt: buildTasks.checkinBuilt,
   clangFormat: buildTasks.format,
@@ -44,9 +42,6 @@ module.exports = {
   gitSyncMaster: gitTasks.syncMaster,
   gitCreateRC: gitTasks.createRC,
   gitUpdateGithubPages: gitTasks.updateGithubPages,
-  // TODO(5621): Re-enable once typings generation is fixed.
-  // typings: gulp.series(typings.typings, typings.msgTypings),
-  // checkinTypings: typings.checkinTypings,
   package: packageTasks.package,
   prepare: buildTasks.prepare,
   checkLicenses: licenseTasks.checkLicenses,

package.json

@@ -33,7 +33,6 @@
     "clean:release": "gulp cleanReleaseDir",
     "checkin": "gulp checkin",
     "checkin:built": "gulp checkinBuilt",
-    "checkin:typings": "gulp checkinTypings",
     "deployDemos": "gulp deployDemos",
     "deployDemos:beta": "gulp deployDemosBeta",
     "format": "gulp clangFormat",

scripts/gulpfiles/build_tasks.js

@@ -25,7 +25,7 @@ var closureDeps = require('google-closure-deps');
 var argv = require('yargs').argv;
 var rimraf = require('rimraf');
 
-var {BUILD_DIR, DEPS_FILE, TEST_DEPS_FILE, TSC_OUTPUT_DIR} = require('./config');
+var {BUILD_DIR, DEPS_FILE, TEST_DEPS_FILE, TSC_OUTPUT_DIR, TYPINGS_BUILD_DIR} = require('./config');
 var {getPackageJson} = require('./helper_tasks');
 
 ////////////////////////////////////////////////////////////
@@ -317,7 +317,9 @@ const buildJavaScriptAndDeps = gulp.series(buildJavaScript, buildDeps);
  * buildCompiled.
  */
 function buildJavaScript(done) {
-  execSync(`tsc -outDir "${TSC_OUTPUT_DIR}"`, {stdio: 'inherit'});
+  execSync(
+      `tsc -outDir "${TSC_OUTPUT_DIR}" -declarationDir "${TYPINGS_BUILD_DIR}"`,
+      {stdio: 'inherit'});
   done();
 }
 

scripts/gulpfiles/config.js

@@ -32,7 +32,7 @@ exports.DEPS_FILE = path.join(exports.BUILD_DIR, 'deps.js');
 exports.TEST_DEPS_FILE = path.join(exports.BUILD_DIR, 'deps.mocha.js');
 
 // Directory to write typings output to.
-exports.TYPINGS_BUILD_DIR = path.join(exports.BUILD_DIR, 'typings');
+exports.TYPINGS_BUILD_DIR = path.join(exports.BUILD_DIR, 'declarations');
 
 // Directory where typescript compiler output can be found.
 // Matches the value in tsconfig.json: outDir

scripts/gulpfiles/package_tasks.js

@@ -14,6 +14,7 @@ gulp.replace = require('gulp-replace');
 gulp.rename = require('gulp-rename');
 gulp.insert = require('gulp-insert');
 gulp.umd = require('gulp-umd');
+gulp.replace = require('gulp-replace');
 
 var path = require('path');
 var fs = require('fs');
@@ -82,7 +83,7 @@ function checkBuildDir(done) {
  * This task copies source files into the release directory.
  */
 function packageSources() {
-  return gulp.src(['core/**/**.js', 'blocks/**.js', 'generators/**/**.js'],
+  return gulp.src(['core/**/**', 'blocks/**', 'generators/**/**'],
       {base: '.'})
     .pipe(gulp.dest(RELEASE_DIR));
 };
@@ -377,13 +378,10 @@ function packageReadme() {
 };
 
 /**
- * This task copies the typings/blockly.d.ts TypeScript definition
- * file into the release directory.  The bundled declaration file is
- * referenced in package.json in the types property.
- * As of Q4 2021 this simply copies the existing ts definition files, since
- * generation through typescript-closure-tools does not work with goog.module.
- * TODO(5621): Regenerate definition files and copy them into the release dir as
- * needed.
+ * This task copies the generated .d.ts files in build/declarations and the
+ * hand-written .d.ts files in typings/ into the release directory. The main
+ * entrypoint file (index.d.ts) is referenced in package.json in the types
+ * property.
  */
 function packageDTS() {
   const handwrittenSrcs = [
@@ -391,6 +389,8 @@ function packageDTS() {
     'typings/msg/msg.d.ts',
   ];
   return gulp.src(handwrittenSrcs, {base: 'typings'})
+      .pipe(gulp.src(`${BUILD_DIR}/${TYPINGS_BUILD_DIR}/**/*.d.ts`))
+      .pipe(gulp.replace('AnyDuringMigration', 'any'))
       .pipe(gulp.dest(RELEASE_DIR));
 };
 

scripts/gulpfiles/release_tasks.js

@@ -153,10 +153,6 @@ const rebuildAll = gulp.series(
   buildTasks.cleanBuildDir,
   buildTasks.build,
   buildTasks.checkinBuilt,
-  // TODO(5621): Re-enable once typings generation is fixed.
-  // typings.typings,
-  // typings.msgTypings,
-  // typings.checkinTypings,
   );
 
 // Package and publish to npm.

tsconfig.json

@@ -3,18 +3,16 @@
     "core/**/*",  // N.B.: also pulls in closure/goog/goog.js if needed.
     "closure/**/*",  // Just for ouptut directory structure.
   ],
+  "exclude": [
+    "core/blockly.js"
+  ],
   "compilerOptions": {
     // Tells TypeScript to read JS files, as
     // normally they are ignored as source files
     "allowJs": true,
 
-    // Enable the next few options for type declarations.
     // Generate d.ts files
-    //"declaration": true,
-    // Types should go into this directory.
-    // Removing this would place the .d.ts files
-    // next to the .js files
-    //"declarationDir": "build/ts/declarations",
+    "declaration": true,
 
     "module": "ES2015",
     "moduleResolution": "node",

typings/blocks.d.ts

@@ -9,8 +9,6 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
 export const colour: any;
 export const lists: any;
 export const logic: any;

typings/core.d.ts

@@ -9,6 +9,4 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="blockly.d.ts" />
-
-export * from 'core/blockly';
+export * from './declarations/core/blockly';

typings/dart.d.ts

@@ -9,8 +9,5 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
-import * as Blockly from './core';
 declare const dart: any;
 export = dart;

typings/index.d.ts

@@ -9,12 +9,6 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-/// <reference path="blocks.d.ts" />
-/// <reference path="javascript.d.ts" />
-/// <reference path="msg/msg.d.ts" />
-
-export * from './core';
-export * as libraryBlocks from './blocks';
+export * from './declarations/core/blockly';
+export * as libraryBlocks from './blocks';  // Handcrafted file.
 export const JavaScript: any;
-import './msg/msg';

typings/javascript.d.ts

@@ -9,8 +9,5 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
-import * as Blockly from './core';
 declare const javascript: any;
 export = javascript;

typings/lua.d.ts

@@ -9,8 +9,5 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
-import * as Blockly from './core';
 declare const lua: any;
 export = lua;

typings/php.d.ts

@@ -9,8 +9,5 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
-import * as Blockly from './core';
 declare const php: any;
 export = php;

typings/python.d.ts

@@ -9,8 +9,5 @@
  * @author samelh@google.com (Sam El-Husseini)
  */
 
-/// <reference path="core.d.ts" />
-
-import * as Blockly from './core';
 declare const python: any;
 export = python;