refactor(generators): Migrate Dart generators to TypeScript (#7646)

* refactor(generators): Migrate dart_generator.js to TypeScript

* refactor(generators): Simplify getAdjusted

  Slightly simplify the implementation of getAdjusted, in part to
  make it more readable.  Also improve its JSDoc comment.

* refactor(generators): Migrate generators/dart/* to TypeScript

  First pass doing very mechanistic migration, not attempting to fix
  all the resulting type errors.

* fix(generators): Fix type errors in generator functions

  This consists almost entirely of adding casts, so the code output
  by tsc should be as similar as possible to the pre-migration .js
  source files.

* fix(generators): Fix minor inconsistencies in JS and Python

  The migration of the JavaScript and Python generators
  inadvertently introduced some inconsistencies in the code,
  e.g.:

  - Incorrect import ordering.
  - Putting executable code before the initial comment line that
    most generator functions begin with, and/or deleting or
    replacing these comments.
    -  N.B. however that these inline comments should have been
       JSDocs; a task to convert them has been added to #7600.

* refactor(generators): Migrate generators/dart.js to TypeScript

  The way the generator functions are added to
  dartGenerator.forBlock has been modified so that incorrect
  generator function signatures will cause tsc to generate a type
  error.

* chore(generator): Format

  One block protected with // prettier-ignore to preserve careful
  comment formatting.

  Where there are repeated concatenations prettier has made a pretty
  mess of things, but the correct fix is probably to use template
  literals instead (rather than just locally disabling prettier).
  This is one of the items in the to-do list in #7600.

* fix(generators): Fix for PR #7646

generators/dart.js → generators/dart.ts

@@ -36,8 +36,17 @@ export const dartGenerator = new DartGenerator();
 dartGenerator.addReservedWords('Html,Math');
 
 // Install per-block-type generator functions:
-Object.assign(
-  dartGenerator.forBlock,
-  colour, lists, logic, loops, math, procedures,
-  text, variables, variablesDynamic
-);
+const generators: typeof dartGenerator.forBlock = {
+  ...colour,
+  ...lists,
+  ...logic,
+  ...loops,
+  ...math,
+  ...procedures,
+  ...text,
+  ...variables,
+  ...variablesDynamic,
+};
+for (const name in generators) {
+  dartGenerator.forBlock[name] = generators[name];
+}

generators/dart/colour.js → generators/dart/colour.ts

@@ -10,43 +10,62 @@
 
 // Former goog.module ID: Blockly.Dart.colour
 
+import type {Block} from '../../core/block.js';
+import type {DartGenerator} from './dart_generator.js';
 import {Order} from './dart_generator.js';
 
-
 // RESERVED WORDS: 'Math'
 
-export function colour_picker(block, generator) {
+export function colour_picker(
+  block: Block,
+  generator: DartGenerator,
+): [string, Order] {
   // Colour picker.
   const code = generator.quote_(block.getFieldValue('COLOUR'));
   return [code, Order.ATOMIC];
-};
+}
 
-export function colour_random(block, generator) {
+export function colour_random(
+  block: Block,
+  generator: DartGenerator,
+): [string, Order] {
   // Generate a random colour.
-  generator.definitions_['import_dart_math'] =
-      "import 'dart:math' as Math;";
-  const functionName = generator.provideFunction_('colour_random', `
+  // TODO(#7600): find better approach than casting to any to override
+  // CodeGenerator declaring .definitions protected.
+  (generator as AnyDuringMigration).definitions_['import_dart_math'] =
+    "import 'dart:math' as Math;";
+  const functionName = generator.provideFunction_(
+    'colour_random',
+    `
 String ${generator.FUNCTION_NAME_PLACEHOLDER_}() {
   String hex = '0123456789abcdef';
   var rnd = new Math.Random();
   return '#\${hex[rnd.nextInt(16)]}\${hex[rnd.nextInt(16)]}'
       '\${hex[rnd.nextInt(16)]}\${hex[rnd.nextInt(16)]}'
       '\${hex[rnd.nextInt(16)]}\${hex[rnd.nextInt(16)]}';
 }
-`);
+`,
+  );
   const code = functionName + '()';
   return [code, Order.UNARY_POSTFIX];
-};
+}
 
-export function colour_rgb(block, generator) {
+export function colour_rgb(
+  block: Block,
+  generator: DartGenerator,
+): [string, Order] {
   // Compose a colour from RGB components expressed as percentages.
   const red = generator.valueToCode(block, 'RED', Order.NONE) || 0;
   const green = generator.valueToCode(block, 'GREEN', Order.NONE) || 0;
   const blue = generator.valueToCode(block, 'BLUE', Order.NONE) || 0;
 
-  generator.definitions_['import_dart_math'] =
-      "import 'dart:math' as Math;";
-  const functionName = generator.provideFunction_('colour_rgb', `
+  // TODO(#7600): find better approach than casting to any to override
+  // CodeGenerator declaring .definitions protected.
+  (generator as AnyDuringMigration).definitions_['import_dart_math'] =
+    "import 'dart:math' as Math;";
+  const functionName = generator.provideFunction_(
+    'colour_rgb',
+    `
 String ${generator.FUNCTION_NAME_PLACEHOLDER_}(num r, num g, num b) {
   num rn = (Math.max(Math.min(r, 100), 0) * 2.55).round();
   String rs = rn.toInt().toRadixString(16);
@@ -62,23 +81,28 @@ String ${generator.FUNCTION_NAME_PLACEHOLDER_}(num r, num g, num b) {
   bs = bs.substring(bs.length - 2);
   return '#$rs$gs$bs';
 }
-`);
+`,
+  );
   const code = functionName + '(' + red + ', ' + green + ', ' + blue + ')';
   return [code, Order.UNARY_POSTFIX];
-};
+}
 
-export function colour_blend(block, generator) {
+export function colour_blend(
+  block: Block,
+  generator: DartGenerator,
+): [string, Order] {
   // Blend two colours together.
-  const c1 =
-      generator.valueToCode(block, 'COLOUR1', Order.NONE) || "'#000000'";
-  const c2 =
-      generator.valueToCode(block, 'COLOUR2', Order.NONE) || "'#000000'";
-  const ratio =
-      generator.valueToCode(block, 'RATIO', Order.NONE) || 0.5;
+  const c1 = generator.valueToCode(block, 'COLOUR1', Order.NONE) || "'#000000'";
+  const c2 = generator.valueToCode(block, 'COLOUR2', Order.NONE) || "'#000000'";
+  const ratio = generator.valueToCode(block, 'RATIO', Order.NONE) || 0.5;
 
-  generator.definitions_['import_dart_math'] =
-      "import 'dart:math' as Math;";
-  const functionName = generator.provideFunction_('colour_blend', `
+  // TODO(#7600): find better approach than casting to any to override
+  // CodeGenerator declaring .definitions protected.
+  (generator as AnyDuringMigration).definitions_['import_dart_math'] =
+    "import 'dart:math' as Math;";
+  const functionName = generator.provideFunction_(
+    'colour_blend',
+    `
 String ${generator.FUNCTION_NAME_PLACEHOLDER_}(String c1, String c2, num ratio) {
   ratio = Math.max(Math.min(ratio, 1), 0);
   int r1 = int.parse('0x\${c1.substring(1, 3)}');
@@ -101,7 +125,8 @@ String ${generator.FUNCTION_NAME_PLACEHOLDER_}(String c1, String c2, num ratio)
   bs = bs.substring(bs.length - 2);
   return '#$rs$gs$bs';
 }
-`);
+`,
+  );
   const code = functionName + '(' + c1 + ', ' + c2 + ', ' + ratio + ')';
   return [code, Order.UNARY_POSTFIX];
-};
+}