Improve builtin globals creation (#303)

Author: fisker

.github/workflows/es-yearly-globals.yml

@@ -18,14 +18,15 @@
 		"test": "npm run build && xo && ava && tsd",
 		"prepare": "npm run build",
 		"update": "node scripts/update.mjs",
-		"update:browser": "node scripts/update.mjs --environment=browser",
-		"update:builtin": "node scripts/update.mjs --environment=builtin",
-		"update:nodeBuiltin": "node scripts/update.mjs --environment=nodeBuiltin",
-		"update:worker": "node scripts/update.mjs --environment=worker",
-		"update:serviceworker": "node scripts/update.mjs --environment=serviceworker",
-		"update:shelljs": "node scripts/update.mjs --environment=shelljs",
-		"update:jest": "node scripts/update.mjs --environment=jest",
-		"update:vitest": "node scripts/update.mjs --environment=vitest",
+		"update:browser": "node scripts/update.mjs --job=browser",
+		"update:builtin": "node scripts/update.mjs --job=builtin",
+		"update:builtin-yearly": "node scripts/update.mjs --job=builtin-yearly",
+		"update:nodeBuiltin": "node scripts/update.mjs --job=nodeBuiltin",
+		"update:worker": "node scripts/update.mjs --job=worker",
+		"update:serviceworker": "node scripts/update.mjs --job=serviceworker",
+		"update:shelljs": "node scripts/update.mjs --job=shelljs",
+		"update:jest": "node scripts/update.mjs --job=jest",
+		"update:vitest": "node scripts/update.mjs --job=vitest",
 		"build": "run-s build:data build:types",
 		"build:data": "node scripts/generate-data.mjs",
 		"build:types": "node scripts/generate-types.mjs"

package.json

@@ -0,0 +1,128 @@
+import fs from 'node:fs/promises';
+import * as cheerio from 'cheerio';
+import {outdent} from 'outdent';
+import {
+	DATA_DIRECTORY,
+	readGlobals,
+} from '../utilities.mjs';
+import {getDataDiff} from './utilities.mjs';
+
+// https://tc39.es/ecma262/
+const SPECIFICATION_URLS = [
+	'https://raw.githubusercontent.com/tc39/ecma262/HEAD/spec.html',
+	'https://cdn.jsdelivr.net/gh/tc39/ecma262/spec.html',
+];
+const CACHE_FILE = new URL('../.cache/spec.html', import.meta.url);
+
+const additionalGlobals = [
+	// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects#internationalization
+	// https://www.ecma-international.org/publications-and-standards/standards/ecma-402/
+	'Intl',
+
+	// Annex B
+	// https://tc39.es/ecma262/#sec-additional-built-in-properties
+	'escape',
+	'unescape',
+];
+
+const getText = async url => {
+	const response = await fetch(url);
+	const text = await response.text();
+	return text;
+};
+
+const getSpecification = async () => {
+	let stat;
+
+	try {
+		stat = await fs.stat(CACHE_FILE);
+	} catch {}
+
+	if (stat) {
+		if (Date.now() - stat.ctimeMs < /* 10 hours */ 10 * 60 * 60 * 1000) {
+			return fs.readFile(CACHE_FILE, 'utf8');
+		}
+
+		await fs.rm(CACHE_FILE);
+	}
+
+	const text = await Promise.any(SPECIFICATION_URLS.map(url => getText(url)));
+
+	await fs.mkdir(new URL('./', CACHE_FILE), {recursive: true});
+	await fs.writeFile(CACHE_FILE, text);
+
+	return text;
+};
+
+function * getGlobalObjects($) {
+	for (const element of $('emu-clause#sec-global-object emu-clause:not([type]) > h1')) {
+		let text = $(element).text().trim();
+
+		// Function shape `Array ( . . . )`
+		text = text.match(/^(?<functionName>\w+?)\s*\(.*?\)$/)?.groups.functionName ?? text;
+
+		if (!/^\w+$/.test(text)) {
+			continue;
+		}
+
+		yield text;
+	}
+}
+
+async function parseSpecification() {
+	const specification = await getSpecification();
+	const $ = cheerio.load(specification);
+	const meta = $('pre.metadata').text();
+	const {year} = meta.match(/title: ECMAScript® (?<year>\d{4})/).groups;
+
+	return {
+		year,
+		data: Object.fromEntries([...getGlobalObjects($), ...additionalGlobals].map(name => [name, false])),
+	};
+}
+
+async function buildYearlyBuiltinGlobals(job, options) {
+	const {year, data} = await parseSpecification();
+	const environment = `es${year}`;
+	const original = await readGlobals(environment, {ignoreNonExits: true});
+	const previousYear = Number(year) - 1;
+	const previousYearData = await readGlobals(`es${previousYear}`);
+	const previousYearProperties = new Set(Object.keys(previousYearData));
+	const addedEntries = Object.entries(data).filter(([name]) => !previousYearProperties.has(name));
+
+	const content = addedEntries.length === 0
+		? `export {default} from './es${previousYear}.mjs';`
+		: outdent`
+			import {mergeGlobals} from '../utilities.mjs';
+			import es${previousYear}Globals from './es${previousYear}.mjs';
+
+			export default mergeGlobals(es${previousYear}Globals, {
+			${addedEntries.map(([name, value]) => `\t${name}: ${value},`).join('\n')}
+			});
+		`;
+
+	const file = new URL(`${environment}.mjs`, DATA_DIRECTORY);
+
+	const code = outdent`
+		// This file is autogenerated by scripts
+		// Do NOT modify this file manually
+
+		${content};
+	`;
+
+	if (!options.dryRun) {
+		await fs.writeFile(file, code + '\n');
+	}
+
+	return {
+		environment,
+		...getDataDiff(original, data),
+	};
+}
+
+async function getBuiltinGlobals() {
+	const {data} = await parseSpecification();
+	return data;
+}
+
+export {getBuiltinGlobals, buildYearlyBuiltinGlobals};