Bug 1903390 - Make it easy to update typelibs when changing interfaces, add instructions r=mossop,saschanaz,smaug DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D214162

tools/@types/README

@@ -0,0 +1,22 @@
+# Gecko typelibs
+
+This directory contains TypeScript declarations for types and components
+exposed to js on the Gecko platform. lib.gecko.*.d.ts files are generated
+from xpidl and webidl sources using tools/ts/build_*.js scripts.
+
+If you're modifying some of the interfaces or other source files, until we
+find the best way to integrate this process, updating the typelibs is optional.
+If you want to see the result of your changes right away, you can run:
+
+    mach ts build && mach ts update
+
+This will update the typelibs inside your source tree, and you can commit
+them alongside your changes. Because this step is not automated, it's likely
+it will pick up previous updates unrelated to your patch, in which case it
+might be worth splitting out into a separate commit.
+
+If there's an error with the process, updating the typelibs is not a blocker
+for landing your patch, but please file a bug in the Linting and Formatting
+component and ni?zombie.
+
+https://bugzilla.mozilla.org/enter_bug.cgi?product=Developer+Infrastructure&component=Lint+and+Formatting

tools/@types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * NOTE: Do not modify this file by hand.
- * Run `mach ts update` to reference typelibs generated in <objdir>.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 /// <reference types="./lib.gecko.dom.d.ts" />

tools/@types/lib.gecko.nsresult.d.ts

@@ -1,6 +1,7 @@
 /**
  * NOTE: Do not modify this file by hand.
  * Content was generated from xpc.msg and error_list.json.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 interface nsIXPCComponents_Results {

tools/@types/lib.gecko.services.d.ts

@@ -1,6 +1,7 @@
 /**
  * NOTE: Do not modify this file by hand.
  * Content was generated from services.json.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 interface JSServices {

tools/ts/build_dom.js

@@ -18,6 +18,7 @@ const TAGLIST = require.resolve("../../parser/htmlparser/nsHTMLTagList.h");
 const HEADER = `/**
  * NOTE: Do not modify this file by hand.
  * Content was generated from source .webidl files.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 /// <reference no-default-lib="true" />

tools/ts/build_nsresult.js

@@ -17,6 +17,7 @@ const peggy = require("peggy");
 const HEADER = `/**
  * NOTE: Do not modify this file by hand.
  * Content was generated from xpc.msg and error_list.json.
+ * If you're updating some of the sources, see README for instructions.
  */
 `;
 

tools/ts/build_services.js

@@ -15,6 +15,7 @@ const fs = require("fs");
 const HEADER = `/**
  * NOTE: Do not modify this file by hand.
  * Content was generated from services.json.
+ * If you're updating some of the sources, see README for instructions.
  */
 `;
 

tools/ts/build_xpcom.js

@@ -16,6 +16,7 @@ const URL = "https://searchfox.org/mozilla-central/source/";
 const HEADER = `/**
  * NOTE: Do not modify this file by hand.
  * Content was generated from source XPCOM .idl files.
+ * If you're updating some of the sources, see README for instructions.
  */
 `;
 

tools/ts/config/builtin.webidl

@@ -3,6 +3,7 @@
 
 // Builtin types that TypeScript-DOM-lib-generator needs to know about.
 [LegacyNoInterfaceObject,Exposed=*] interface BufferSource {};
+[LegacyNoInterfaceObject,Exposed=*] interface CSSPageDescriptors {};
 [LegacyNoInterfaceObject,Exposed=*] interface DOMApplication {};
 [LegacyNoInterfaceObject,Exposed=*] interface EventListenerOrEventListenerObject {};
 [LegacyNoInterfaceObject,Exposed=*] interface EventHandler {};

tools/ts/config/test_builtin.webidl

@@ -1,6 +1,7 @@
 
 // Builtins needed for running tests.
 [LegacyNoInterfaceObject,Exposed=*] interface AnyCallback {};
+[LegacyNoInterfaceObject,Exposed=*] interface Element {};
 [LegacyNoInterfaceObject,Exposed=*] interface IsInstance {};
 [LegacyNoInterfaceObject,Exposed=*] interface Location {};
 [LegacyNoInterfaceObject,Exposed=*] interface Node {};

tools/ts/mach_commands.py

@@ -4,10 +4,13 @@
 
 import json
 import os
+import shutil
 
 import mozpack.path as mozpath
 from mach.decorators import Command, CommandArgument, SubCommand
 
+targets = ["dom", "nsresult", "services", "xpcom"]
+
 
 @Command("ts", category="misc", description="Run TypeScript and related commands.")
 def ts(ctx):
@@ -23,9 +26,15 @@ def ts(ctx):
 
 
 @SubCommand("ts", "build", description="Build typelibs.")
-@CommandArgument("lib", choices=["dom", "nsresult", "services", "xpcom"])
-def buld(ctx, lib):
-    """Command to build one of the typelibs."""
+@CommandArgument("lib", choices=targets, nargs="?")
+def build(ctx, lib):
+    """Command to build the target typelibs."""
+
+    if lib is None:
+        for t in targets:
+            if rv := build(ctx, t):
+                return rv
+        return 0
 
     types_dir = mozpath.join(ctx.distdir, "@types")
     lib_dts = mozpath.join(types_dir, f"lib.gecko.{lib}.d.ts")
@@ -87,11 +96,24 @@ def setup(ctx):
     return ctx._sub_mach(["npm", "ci"])
 
 
-@SubCommand("ts", "update", description="Update tools/@types lib references.")
+@SubCommand("ts", "update", description="Update tools/@types libraries.")
 def update(ctx):
-    types_dir = mozpath.join(ctx.distdir, "@types")
-    index_dts = mozpath.join(ctx.topsrcdir, "tools/@types/index.d.ts")
-    return node(ctx, "update_refs", index_dts, types_dir)
+    typelib_dir = mozpath.join(ctx.topsrcdir, "tools/@types")
+
+    for lib in targets:
+        file = f"lib.gecko.{lib}.d.ts"
+        path = mozpath.join(ctx.distdir, "@types", file)
+        if not os.path.exists(path):
+            print(f"[ERROR] {path} not found. Did you run `mach ts build`?")
+            return 1
+
+        # This command inherently goes in a confusing direction, we're copying:
+        # from `<topobjdir>/dist/@types` files generated with `mach ts build`,
+        # into `<topsrcdir>/tools/@types` typelib dir back in your source tree.
+        print(f"[INFO] Updating {typelib_dir}/{file}")
+        shutil.copy(path, typelib_dir)
+
+    print("[WARNING] Your source tree was updated, you should commit the changes.")
 
 
 def node(ctx, script, *args):

tools/ts/test/baselines/domtest.d.ts

@@ -1,6 +1,7 @@
 /**
  * NOTE: Do not modify this file by hand.
  * Content was generated from source .webidl files.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 /// <reference no-default-lib="true" />
@@ -67,6 +68,9 @@ interface TestInterfaceJSUnionableDictionary {
 interface AnyCallback {
 }
 
+interface Element {
+}
+
 
 interface Location {
 }
@@ -351,6 +355,17 @@ declare var TestInterfaceSetlikeNode: {
     isInstance: IsInstance<TestInterfaceSetlikeNode>;
 };
 
+interface TestReflectedHTMLAttribute {
+    reflectedHTMLAttribute: Element[] | null;
+    setReflectedHTMLAttributeValue(seq: Element[]): void;
+}
+
+declare var TestReflectedHTMLAttribute: {
+    prototype: TestReflectedHTMLAttribute;
+    new(): TestReflectedHTMLAttribute;
+    isInstance: IsInstance<TestReflectedHTMLAttribute>;
+};
+
 interface TestTrialInterface {
 }
 
@@ -457,6 +472,10 @@ interface TestInterfaceSetlike extends Set<string> {
 interface TestInterfaceSetlikeNode extends Set<Node> {
 }
 
+interface TestReflectedHTMLAttribute {
+    setReflectedHTMLAttributeValue(seq: Iterable<Element>): void;
+}
+
 /////////////////////////////
 /// Window Async Iterable APIs
 /////////////////////////////

tools/ts/test/baselines/xpctest.d.ts

@@ -1,6 +1,7 @@
 /**
  * NOTE: Do not modify this file by hand.
  * Content was generated from source XPCOM .idl files.
+ * If you're updating some of the sources, see README for instructions.
  */
 
 declare global {

tools/ts/update_refs.js

@@ -1,35 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-"use strict";
-
-/**
- * Update:    <srcdir>/tools/@types/index.d.ts,
- *
- * reference: <objdir>/dist/@types/lib.gecko.*.d.json,
- *            generated by a ts build lib step.
- */
-
-const fs = require("fs");
-const libs = ["dom", "nsresult", "services", "xpcom"];
-
-function main(index_dts, lib_dir) {
-  let index = fs.readFileSync(index_dts, "utf8");
-
-  for (let lib of libs) {
-    let file = `lib.gecko.${lib}.d.ts`;
-    let path = `${lib_dir}/${file}`;
-    let found = fs.existsSync(path);
-    console.log(`[INFO] ${path} (found: ${found})`);
-
-    if (found) {
-      let re = RegExp(` types=".+/${file}" />`);
-      index = index.replace(re, ` types="${path}" />`);
-    }
-  }
-
-  console.log(`[INFO] ${index_dts} (${index.length.toLocaleString()} bytes)`);
-  fs.writeFileSync(index_dts, index);
-}
-
-main(...process.argv.slice(2));