KDL Parser (microsoft#2064)

Co-authored-by: Kagami Sascha Rosylight <saschanaz@outlook.com>

Author: Bashamega

inputfiles/addedTypes.jsonc

@@ -373,98 +373,6 @@
                     // Full support: https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API#browser_compatibility
                     "storage-access"
                 ]
-            },
-            "AutoFillBase": {
-                "name": "AutoFillBase",
-                "value": [
-                    // Off
-                    "off",
-                    // Automatic
-                    "on",
-                    ""
-                ]
-            },
-            "AutoFillAddressKind": {
-                "name": "AutoFillAddressKind",
-                "value": [
-                    "shipping",
-                    "billing"
-                ]
-            },
-            "AutoFillNormalField": {
-                "name": "AutoFillNormalField",
-                "value": [
-                    "name",
-                    "honorific-prefix",
-                    "given-name",
-                    "additional-name",
-                    "family-name",
-                    "honorific-suffix",
-
-                    "username",
-                    "new-password",
-                    "current-password",
-                    // Supported in iOS Safari too even though WPT tests
-                    // for Safari currently fail as of 2023-06.
-                    "one-time-code",
-
-                    "organization",
-                    "street-address",
-                    "address-line1",
-                    "address-line2",
-                    "address-line3",
-                    "address-level4",
-                    "address-level3",
-                    "address-level2",
-                    "address-level1",
-                    "country",
-                    "country-name",
-                    "postal-code",
-
-                    "cc-name",
-                    "cc-given-name",
-                    "cc-family-name",
-                    "cc-number",
-                    "cc-exp",
-                    "cc-exp-month",
-                    "cc-exp-year",
-                    "cc-csc",
-                    "cc-type",
-                    "transaction-currency",
-                    "transaction-amount",
-
-                    "bday-day",
-                    "bday-month",
-                    "bday-year"
-                ]
-            },
-            "AutoFillContactKind": {
-                "name": "AutoFillContactKind",
-                "value": [
-                    "home",
-                    "work",
-                    "mobile"
-                ]
-            },
-            "AutoFillContactField": {
-                "name": "AutoFillContactField",
-                "value": [
-                    "tel",
-                    "tel-country-code",
-                    "tel-national",
-                    "tel-area-code",
-                    "tel-local",
-                    "tel-local-prefix",
-                    "tel-local-suffix",
-                    "tel-extension",
-                    "email"
-                ]
-            },
-            "AutoFillCredentialField": {
-                "name": "AutoFillCredentialField",
-                "value": [
-                    "webauthn"
-                ]
             }
         }
     },

inputfiles/patches/autocomplete.kdl

@@ -0,0 +1,74 @@
+enum AutoFillBase {
+  // Off
+  off
+  // Automatic
+  on
+  ""
+}
+enum AutoFillAddressKind {
+  shipping
+  billing
+}
+enum AutoFillNormalField {
+  name
+  honorific-prefix
+  given-name
+  additional-name
+  family-name
+  honorific-suffix
+
+  username
+  new-password
+  current-password
+  // Supported in iOS Safari too even though WPT tests
+  // for Safari currently fail as of 2023-06.
+  one-time-code
+
+  organization
+  street-address
+  address-line1
+  address-line2
+  address-line3
+  address-level4
+  address-level3
+  address-level2
+  address-level1
+  country
+  country-name
+  postal-code
+
+  cc-name
+  cc-given-name
+  cc-family-name
+  cc-number
+  cc-exp
+  cc-exp-month
+  cc-exp-year
+  cc-csc
+  cc-type
+  transaction-currency
+  transaction-amount
+
+  bday-day
+  bday-month
+  bday-year
+}
+enum AutoFillContactKind {
+  home
+  work
+  mobile
+}
+enum AutoFillContactField {
+  tel
+  tel-country-code
+  tel-national
+  tel-area-code
+  tel-local
+  tel-local-prefix
+  tel-local-suffix
+  tel-extension
+  email
+}
+enum AutoFillCredentialField {
+  webauthn
+}

package-lock.json

@@ -58,6 +58,7 @@
     "eslint-plugin-prettier": "^5.1.3",
     "globals": "^16.0.0",
     "jsonc-parser": "^3.2.1",
+    "kdljs": "^0.3.0",
     "node-fetch": "^3.3.2",
     "prettier": "^3.2.5",
     "print-diff": "^2.0.0",

package.json

@@ -14,6 +14,7 @@ import { getInterfaceToEventMap } from "./build/webref/events.js";
 import { getWebidls } from "./build/webref/idl.js";
 import jsonc from "jsonc-parser";
 import { generateDescriptions } from "./build/mdn-comments.js";
+import readPatches from "./build/patches.js";
 
 function mergeNamesakes(filtered: Browser.WebIdl) {
   const targets = [
@@ -93,6 +94,7 @@ async function emitDom() {
 
   const overriddenItems = await readInputJSON("overridingTypes.jsonc");
   const addedItems = await readInputJSON("addedTypes.jsonc");
+  const patches = await readPatches();
   const comments = await readInputJSON("comments.json");
   const deprecatedInfo = await readInputJSON("deprecatedMessage.json");
   const documentationFromMDN = await generateDescriptions();
@@ -230,6 +232,7 @@ async function emitDom() {
   webidl = mergeApiDescriptions(webidl, documentationFromMDN);
   webidl = merge(webidl, addedItems);
   webidl = merge(webidl, overriddenItems);
+  webidl = merge(webidl, patches);
   webidl = merge(webidl, comments);
   webidl = mergeDeprecatedMessage(webidl, deprecatedInfo);
   for (const name in webidl.interfaces!.interface) {

src/build.ts

@@ -0,0 +1,74 @@
+import { parse } from "kdljs";
+import type { Enum } from "./types";
+import { readdir, readFile } from "fs/promises";
+import { merge } from "./helpers.js";
+
+/**
+ * Converts patch files in KDL to match the [types](types.d.ts).
+ */
+function parseKDL(kdlText: string) {
+  const { output, errors } = parse(kdlText);
+
+  if (errors.length) {
+    throw new Error("KDL parse errors", { cause: errors });
+  }
+
+  const nodes = output!;
+  const enums: Record<string, Enum> = {};
+
+  for (const node of nodes) {
+    if (node.name === "enum") {
+      handleEnum(node, enums);
+    }
+  }
+
+  return { enums: { enum: enums } };
+}
+
+/**
+ * Handles an enum node by extracting its name and values.
+ * Throws an error if the enum name is missing or if the values are not in the correct format.
+ * @param node The enum node to handle.
+ * @param enums The record of enums to update.
+ */
+function handleEnum(node: any, enums: Record<string, Enum>) {
+  const name = node.values[0];
+  if (typeof name !== "string") {
+    throw new Error("Missing enum name");
+  }
+  const values: string[] = [];
+
+  for (const child of node.children ?? []) {
+    values.push(child.name);
+  }
+
+  enums[name] = { name, value: values };
+}
+
+/**
+ * Collect all file URLs in a directory.
+ */
+async function getAllFileURLs(folder: URL): Promise<URL[]> {
+  const entries = await readdir(folder, { withFileTypes: true });
+  return entries.map((entry) => new URL(entry.name, folder));
+}
+
+/**
+ * Read and parse a single KDL file.
+ */
+export async function readPatch(fileUrl: URL): Promise<any> {
+  const text = await readFile(fileUrl, "utf8");
+  return parseKDL(text);
+}
+
+/**
+ * Read, parse, and merge all KDL files under the input folder.
+ */
+export default async function readPatches(): Promise<any> {
+  const patchDirectory = new URL("../../inputfiles/patches/", import.meta.url);
+  const fileUrls = await getAllFileURLs(patchDirectory);
+
+  const parsedContents = await Promise.all(fileUrls.map(readPatch));
+
+  return parsedContents.reduce((acc, current) => merge(acc, current), {});
+}