blockly 12.4.0 → 12.4.1

package/scripts/gulpfiles/config.mjs

@@ -1,40 +0,0 @@
-/**
- * @license
- * Copyright 2021 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @fileoverview Common configuration for Gulp scripts.
- */
-
-import * as path from 'path';
-
-// Paths are all relative to the repository root.  Do not include
-// trailing slash.
-//
-// TODO(#5007): If you modify these values, you must also modify the
-// corresponding values in the following files:
-//
-// - tests/scripts/check_metadata.sh
-// - tests/scripts/update_metadata.sh
-
-// Directory to write compiled output to.
-export const BUILD_DIR = 'build';
-
-// Directory to write typings output to.
-export const TYPINGS_BUILD_DIR = path.join(BUILD_DIR, 'declarations');
-
-// Directory to write langfile output to.
-export const LANG_BUILD_DIR = path.join(BUILD_DIR, 'msg');
-
-// Directory where typescript compiler output can be found.
-// Matches the value in tsconfig.json: outDir
-export const TSC_OUTPUT_DIR = path.join(BUILD_DIR, 'src');
-
-// Directory for files generated by compiling test code.
-export const TEST_TSC_OUTPUT_DIR = path.join(BUILD_DIR, 'tests');
-
-// Directory in which to assemble (and from which to publish) the
-// blockly npm package.
-export const RELEASE_DIR = 'dist';

package/scripts/gulpfiles/docs_tasks.mjs

@@ -1,146 +0,0 @@
-import {execSync} from 'child_process';
-import {Extractor} from 'markdown-tables-to-json';
-import * as fs from 'fs';
-import * as gulp from 'gulp';
-import header from 'gulp-header';
-import replace from 'gulp-replace';
-
-const DOCS_DIR = 'docs';
-
-/**
- * Run API Extractor to generate the intermediate json file.
- */
-const generateApiJson = function(done) {
-  execSync('api-extractor run --local', {stdio: 'inherit'});
-  done();
-}
-
-/**
- * API Extractor output spuriously renames some functions. Undo that.
- * See https://github.com/microsoft/rushstack/issues/2534
- */
-const removeRenames = function() {
-  return gulp.src('temp/blockly.api.json')
-      .pipe(replace('_2', ''))
-      .pipe(gulp.dest('temp/'));
-}
-
-/**
- * Run API Documenter to generate the raw docs files.
- */
-const generateDocs = function(done) {
-  if (!fs.existsSync(DOCS_DIR)) {
-    // Create the directory if it doesn't exist.
-    // If it already exists, the contents will be deleted by api-documenter.
-    fs.mkdirSync(DOCS_DIR);
-  }
-  execSync(
-      `api-documenter markdown --input-folder temp --output-folder ${DOCS_DIR}`,
-      {stdio: 'inherit'});
-  done();
-}
-
-/**
- * Prepends the project and book metadata that devsite requires.
- */
-const prependBook = function() {
-  return gulp.src('docs/*.md')
-      .pipe(header(
-          'Project: /blockly/_project.yaml\nBook: /blockly/_book.yaml\n\n'))
-      .pipe(gulp.dest(DOCS_DIR));
-}
-
-/**
- * Creates a map of top-level pages to sub-pages, e.g. a mapping
- * of `block_class` to every page associated with that class.
- * This is needed to create an accurate table of contents.
- * @param {string[]} allFiles All files in docs directory.
- * @returns {Map<string, string[]>}
- */
-const buildAlternatePathsMap = function(allFiles) {
-  let map = new Map();
-  for (let file of allFiles) {
-    // Get the name of the class/namespaces/variable/etc., i.e. the top-level
-    // page.
-    let filePieces = file.split('.');
-    let name = filePieces[1];
-    if (!map.has(name)) {
-      map.set(name, []);
-    }
-    if (filePieces[2] === 'md') {
-      // Don't add the top-level page to the map.
-      continue;
-    }
-    // Add all sub-pages to the array for the corresponding top-level page.
-    map.get(name).push(file);
-  }
-  return map;
-}
-
-/**
- * Create the _toc.yaml file used by devsite to create the leftnav.
- * This file is generated from the contents of `blockly.md` which contains links
- * to the other top-level API pages (each class, namespace, etc.).
- *
- * The `alternate_paths` for each top-level page contains the path for
- * each associated sub-page. All subpages must be linked to their top-level page
- * in the TOC for the left nav bar to remain correct after drilling down into a
- * sub-page.
- */
-const createToc = function(done) {
-  const fileContent = fs.readFileSync(`${DOCS_DIR}/blockly.md`, 'utf8');
-  // Create the TOC file. The file should not yet exist; if it does, this
-  // operation will fail.
-  const toc = fs.openSync(`${DOCS_DIR}/_toc.yaml`, 'ax');
-  const files = fs.readdirSync(DOCS_DIR);
-  const map = buildAlternatePathsMap(files);
-  const referencePath = '/blockly/reference/js';
-
-  const tocHeader = `toc:
-- title: Overview
-  path: /blockly/reference/js/blockly.md\n`;
-  fs.writeSync(toc, tocHeader);
-
-  // Generate a section of TOC for each section/heading in the overview file.
-  const sections = fileContent.split('##');
-  for (let section of sections) {
-    // This converts the md table in each section to a JS object
-    const table = Extractor.extractObject(section, 'rows', false);
-    if (!table) {
-      continue;
-    }
-    // Get the name of the section, i.e. the text immediately after the `##` in
-    // the source doc
-    const sectionName = section.split('\n')[0].trim();
-    fs.writeSync(toc, `- heading: ${sectionName}\n`);
-    for (let row in table) {
-      // After going through the Extractor, the markdown is now HTML.
-      // Each row in the table is now a link (anchor tag).
-      // Get the target of the link, excluding the first `.` since we don't want
-      // a relative path.
-      const path = /href="\.(.*?)"/.exec(row)?.[1];
-      // Get the name of the link (text in between the <a> and </a>)
-      const name = /">(.*?)</.exec(row)?.[1];
-      if (!path || !name) {
-        continue;
-      }
-      fs.writeSync(toc, `- title: ${name}\n  path: ${referencePath}${path}\n`);
-      // Get the list of sub-pages for this page.
-      // Add each sub-page to the `alternate_paths` property.
-      let pages = map.get(path.split('.')[1]);
-      if (pages?.length) {
-        fs.writeSync(toc, `  alternate_paths:\n`);
-        for (let page of pages) {
-          fs.writeSync(toc, `  - ${referencePath}/${page}\n`);
-        }
-      }
-    }
-  }
-
-  done();
-}
-
-export const docs = gulp.series(
-    generateApiJson, removeRenames, generateDocs,
-    gulp.parallel(prependBook, createToc));
-

package/scripts/gulpfiles/git_tasks.mjs

@@ -1,167 +0,0 @@
-/**
- * @license
- * Copyright 2018 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @fileoverview Git-related gulp tasks for Blockly.
- */
-
-import * as gulp from 'gulp';
-import {execSync} from 'child_process';
-
-import * as buildTasks from './build_tasks.mjs';
-import * as packageTasks from './package_tasks.mjs';
-
-const UPSTREAM_URL = 'https://github.com/google/blockly.git';
-
-/**
- * Extra paths to include in the gh_pages branch (beyond the normal
- * contents of master / develop).  Passed to shell unquoted, so can
- * include globs.
- */
-const EXTRAS = [
-  'build/msg',
-  'dist/*_compressed.js*',
-  'node_modules/@blockly',
-  'build/*.loader.mjs',
-];
-
-let upstream = null;
-
-/**
- * Get name of git remote for upstream (typically 'upstream', but this
- * is just convention and can be changed.)
- */
-function getUpstream() {
-  if (upstream) return upstream;
-  for (const line of String(execSync('git remote -v')).split('\n')) {
-    if (line.includes('google/blockly')) {
-      upstream = line.split('\t')[0];
-      return upstream;
-    }
-  }
-  throw new Error('Unable to determine upstream URL');
-}
-
-/**
- * Stash current state, check out the named branch, and sync with
- * google/blockly.
- */
-function syncBranch(branchName) {
-  return function(done) {
-    execSync('git stash save -m "Stash for sync"', { stdio: 'inherit' });
-    checkoutBranch(branchName);
-    execSync(`git pull ${UPSTREAM_URL} ${branchName}`, { stdio: 'inherit' });
-    execSync(`git push origin ${branchName}`, { stdio: 'inherit' });
-    done();
-  };
-}
-
-/**
- * Stash current state, check out develop, and sync with
- * google/blockly.
- */
-export function syncDevelop() {
-  return syncBranch('develop');
-};
-
-/**
- * Stash current state, check out master, and sync with
- * google/blockly.
- */
-export function syncMaster() {
-  return syncBranch('master');
-};
-
-/**
- * Helper function: get a name for a rebuild branch. Format:
- * rebuild_mm_dd_yyyy.
- */
-function getRebuildBranchName() {
-  const date = new Date();
-  const mm = date.getMonth() + 1;  // Month, 0-11
-  const dd = date.getDate();  // Day of the month, 1-31
-  const yyyy = date.getFullYear();
-  return `rebuild_${mm}_${dd}_${yyyy}`;
-};
-
-/**
- * Helper function: get a name for a rebuild branch. Format:
- * rebuild_yyyy_mm.
- */
-function getRCBranchName() {
-  const date = new Date();
-  const mm = date.getMonth() + 1;  // Month, 0-11
-  const yyyy = date.getFullYear();
-  return `rc_${yyyy}_${mm}`;
-};
-
-/**
- * If branch does not exist then create the branch.
- * If branch exists switch to branch.
- */
-function checkoutBranch(branchName) {
-  execSync(`git switch -c ${branchName}`,
-      { stdio: 'inherit' });
-}
-
-/**
- * Create and push an RC branch.
- * Note that this pushes to google/blockly.
- */
-export const createRC = gulp.series(
-  syncDevelop(),
-  function(done) {
-    const branchName = getRCBranchName();
-    execSync(`git switch -C ${branchName}`, { stdio: 'inherit' });
-    execSync(`git push ${UPSTREAM_URL} ${branchName}`, { stdio: 'inherit' });
-    done();
-  }
-);
-
-/** Create the rebuild branch. */
-export function createRebuildBranch(done) {
-  const branchName = getRebuildBranchName();
-  console.log(`make-rebuild-branch: creating branch ${branchName}`);
-  execSync(`git switch -C ${branchName}`, { stdio: 'inherit' });
-  done();
-}
-
-/** Push the rebuild branch to origin. */
-export function pushRebuildBranch(done) {
-  console.log('push-rebuild-branch: committing rebuild');
-  execSync('git commit -am "Rebuild"', { stdio: 'inherit' });
-  const branchName = getRebuildBranchName();
-  execSync(`git push origin ${branchName}`, { stdio: 'inherit' });
-  console.log(`Branch ${branchName} pushed to GitHub.`);
-  console.log('Next step: create a pull request against develop.');
-  done();
-}
-
-/**
- * Update github pages with what is currently in develop.
- *
- * Prerequisites (invoked): clean, build.
- */
-export const updateGithubPages = gulp.series(
-  function(done) {
-    execSync('git stash save -m "Stash for sync"', { stdio: 'inherit' });
-    execSync('git switch -C gh-pages', { stdio: 'inherit' });
-    execSync(`git fetch ${getUpstream()}`, { stdio: 'inherit' });
-    execSync(`git reset --hard ${getUpstream()}/develop`, { stdio: 'inherit' });
-    done();
-  },
-  buildTasks.cleanBuildDir,
-  packageTasks.cleanReleaseDir,
-  buildTasks.build,
-  function(done) {
-    // Extra paths (e.g. build/, dist/ etc.) are normally gitignored,
-    // so we have to force add.
-    execSync(`git add -f ${EXTRAS.join(' ')}`, {stdio: 'inherit'});
-    execSync('git commit -am "Rebuild"', {stdio: 'inherit'});
-    execSync(`git push ${UPSTREAM_URL} gh-pages --force`, {stdio: 'inherit'});
-    done();
-  }
-);

package/scripts/gulpfiles/helper_tasks.mjs

@@ -1,25 +0,0 @@
-/**
- * @license
- * Copyright 2021 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @fileoverview Any gulp helper functions.
- */
-
-import Module from "node:module";
-
-const require = Module.createRequire(import.meta.url);
-
-/**
- * Load and return the contents of package.json.
- *
- * Uses require() rather than import, and clears the require cache, to
- * ensure the loaded package.json data is up to date.
- */
-export function getPackageJson() {
-  delete require.cache[require.resolve('../../package.json')];
-  return require('../../package.json');
-}
-

package/scripts/gulpfiles/package_tasks.mjs

@@ -1,257 +0,0 @@
-/**
- * @license
- * Copyright 2018 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @fileoverview Gulp tasks to package Blockly for distribution on NPM.
- */
-
-import * as gulp from 'gulp';
-import concat from 'gulp-concat';
-import replace from 'gulp-replace';
-import umd from 'gulp-umd';
-
-import * as path from 'path';
-import * as fs from 'fs';
-import {rimraf} from 'rimraf';
-import * as build from './build_tasks.mjs';
-import {getPackageJson} from './helper_tasks.mjs';
-import {BUILD_DIR, LANG_BUILD_DIR, RELEASE_DIR, TYPINGS_BUILD_DIR} from './config.mjs';
-
-// Path to template files for gulp-umd.
-const TEMPLATE_DIR = 'scripts/package/templates';
-
-/**
- * A helper method for wrapping a file into a Universal Module Definition.
- * @param {string} namespace The export namespace.
- * @param {Array<Object>} dependencies An array of dependencies to inject.
- */
-function packageUMD(namespace, dependencies, template = 'umd.template') {
-  return umd({
-    dependencies: function () { return dependencies; },
-    namespace: function () { return namespace; },
-    exports: function () { return namespace; },
-    template: path.join(TEMPLATE_DIR, template)
-  });
-};
-
-/**
- * This task wraps scripts/package/index.js into a UMD module.
- *
- * This module is the main entrypoint for the blockly package, and
- * loads blockly/core, blockly/blocks and blockly/msg/en and then
- * calls setLocale(en).
- */
-function packageIndex() {
-  return gulp.src('scripts/package/index.js')
-    .pipe(packageUMD('Blockly', [{
-        name: 'Blockly',
-        amd: 'blockly/core',
-        cjs: 'blockly/core',
-      },{
-        name: 'en',
-        amd: 'blockly/msg/en',
-        cjs: 'blockly/msg/en',
-        global: 'Blockly.Msg',
-      },{
-        name: 'blocks',
-        amd: 'blockly/blocks',
-        cjs: 'blockly/blocks',
-        global: 'Blockly.Blocks',
-      }]))
-    .pipe(gulp.dest(RELEASE_DIR));
-};
-
-/**
- * This task copies scripts/package/core-node.js into into the
- * package.  This module will be the 'blockly/core' entrypoint for
- * node.js environments.
- *
- * Note that, unlike index.js, this file does not get a UMD wrapper.
- * This is because it is only used in node.js environments and so is
- * guaranteed to be loaded as a CJS module.
- */
-function packageCoreNode() {
-  return gulp.src('scripts/package/core-node.js')
-    .pipe(gulp.dest(RELEASE_DIR));
-};
-
-/**
- * This task wraps each of the files in ${BUILD_DIR/msg/ into a UMD module.
- * @example import * as En from 'blockly/msg/en';
- */
-function packageLocales() {
-  // Remove references to goog.provide and goog.require.
-  return gulp.src(`${LANG_BUILD_DIR}/*.js`)
-      .pipe(replace(/goog\.[^\n]+/g, ''))
-      .pipe(packageUMD('Blockly.Msg', [], 'umd-msg.template'))
-      .pipe(gulp.dest(`${RELEASE_DIR}/msg`));
-};
-
-/**
- * This task creates a UMD bundle of Blockly which includes the Blockly
- * core files, the built-in blocks, the JavaScript code generator and the
- * English localization files.
- * @example <script src="https://unpkg.com/blockly/blockly.min.js"></script>
- */
-function packageUMDBundle() {
-  const srcs = [
-    `${RELEASE_DIR}/blockly_compressed.js`,
-    `${RELEASE_DIR}/msg/en.js`,
-    `${RELEASE_DIR}/blocks_compressed.js`,
-    `${RELEASE_DIR}/javascript_compressed.js`,
-  ];
-  return gulp.src(srcs)
-      .pipe(concat('blockly.min.js'))
-      .pipe(gulp.dest(`${RELEASE_DIR}`));
-};
-
-
-/**
- * This task creates shims for the submodule entrypoints, for the
- * benefit of bundlers and other build tools that do not correctly
- * support the exports declaration in package.json.  These shims just
- * require() and reexport the corresponding *_compressed.js bundle.
- *
- * This should solve issues encountered by users of bundlers that don't
- * support exports at all (e.g. browserify) as well as ones that don't
- * support it in certain circumstances (e.g., when using webpack's
- * resolve.alias configuration option to alias 'blockly' to
- * 'node_modules/blockly', as we formerly did in most plugins, which
- * causes webpack to ignore blockly's package.json entirely).
- *
- * Assumptions:
- * - Such bundlers will _completely_ ignore the exports declaration.
- * - The bundles are intended to be used in a browser—or at least not
- *   in node.js—so the core entrypoint never needs to route to
- *   core-node.js.  This is reasonable since there's little reason to
- *   bundle code for node.js, and node.js has supported the exports
- *   clause since at least v12, consideably older than any version of
- *   node.js we officially support.
- * - It suffices to provide only a CJS entrypoint (because we can only
- *   provide CJS or ESM, not both.  (We could in future switch to
- *   providing only an ESM entrypoint instead, though.)
- *
- * @param {Function} done Callback to call when done.
- */
-function packageLegacyEntrypoints(done) {
-  for (const entrypoint of [
-    'core', 'blocks', 'dart', 'javascript', 'lua', 'php', 'python'
-  ]) {
-    const bundle =
-        (entrypoint === 'core' ? 'blockly' : entrypoint) + '_compressed.js';
-    fs.writeFileSync(path.join(RELEASE_DIR, `${entrypoint}.js`),
-        `// Shim for backwards-compatibility with bundlers that do not
-// support the 'exports' clause in package.json, to allow them
-// to load the blockly/${entrypoint} submodule entrypoint.
-module.exports = require('./${bundle}');
-`);
-  }
-  done();
-}
-
-/**
- * This task copies all the media/* files into the release directory.
- */
-function packageMedia() {
-  return gulp.src('media/*', {encoding: false})
-    .pipe(gulp.dest(`${RELEASE_DIR}/media`));
-};
-
-/**
- * This task copies the package.json file into the release directory,
- * with modifications:
- *
- * - The scripts section is removed.
- *
- * Prerequisite: buildLangfiles.
- *
- * @param {Function} done Callback to call when done.
- */
-function packageJSON(done) {
-  // Copy package.json, so we can safely modify it.
-  const json = JSON.parse(JSON.stringify(getPackageJson()));
-  // Remove unwanted entries.
-  delete json['scripts'];
-  // Set "type": "commonjs", since that's what .js files in the
-  // package root are.  This should be a no-op since that's the
-  // default, but by setting it explicitly we ensure that any chage to
-  // the repository top-level package.json to set "type": "module"
-  // won't break the published package accidentally.
-  json.type = 'commonjs';
-  // Write resulting package.json file to release directory.
-  if (!fs.existsSync(RELEASE_DIR)) {
-    fs.mkdirSync(RELEASE_DIR, {recursive: true});
-  }
-  fs.writeFileSync(`${RELEASE_DIR}/package.json`,
-      JSON.stringify(json, null, 2));
-  done();
-};
-
-/**
- * This task copies the scripts/package/README.md file into the
- * release directory.  This file is what developers will see at
- * https://www.npmjs.com/package/blockly .
- */
-function packageReadme() {
-  return gulp.src('scripts/package/README.md')
-    .pipe(gulp.dest(RELEASE_DIR));
-};
-
-/**
- * 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 = [
-    'typings/*.d.ts',
-    'typings/msg/*.d.ts',
-  ];
-  return gulp.src(handwrittenSrcs, {base: 'typings'})
-      .pipe(gulp.src(`${TYPINGS_BUILD_DIR}/**/*.d.ts`, {ignore: [
-	`${TYPINGS_BUILD_DIR}/blocks/**/*`,
-      ]}))
-      .pipe(replace('AnyDuringMigration', 'any'))
-      .pipe(gulp.dest(RELEASE_DIR));
-};
-
-/**
- * This task cleans the release directory (by deleting it).
- */
-export function cleanReleaseDir() {
-  // Sanity check.
-  if (RELEASE_DIR === '.' || RELEASE_DIR === '/') {
-    return Promise.reject(`Refusing to rm -rf ${RELEASE_DIR}`);
-  }
-  return rimraf(RELEASE_DIR);
-}
-
-/**
- * This task prepares the files to be included in the NPM by copying
- * them into the release directory.
- *
- * This task was formerly called "package" but was renamed in
- * preparation for porting gulpfiles to ESM because "package" is a
- * reserved word.
- *
- * Prerequisite: build.
- */
-export const pack = gulp.series(
-    gulp.parallel(
-        build.cleanBuildDir,
-        cleanReleaseDir),
-    build.build,
-    gulp.parallel(
-        packageIndex,
-        packageCoreNode,
-        packageLegacyEntrypoints,
-        packageMedia,
-        gulp.series(packageLocales, packageUMDBundle),
-        packageJSON,
-        packageReadme,
-        packageDTS)
-    );