feat: generate node compat list from files (#931)

denoland · Oct 3, 2024 · 71f25aa · 71f25aa
1 parent c78806b
commit 71f25aa
Show file tree

Hide file tree

Showing 49 changed files with 1,698 additions and 2,061 deletions.
diff --git a/deno.lock b/deno.lock
diff --git a/reference_gen/node-docs.ts b/reference_gen/node-docs.ts
@@ -1,47 +1,8 @@
 import { Node, Project, ts } from "ts-morph";
 import EXCLUDE_MAP from "./node-exclude-map.json" with { type: "json" };
-import { walk } from "@std/fs";
-import { parse as yamlParse } from "@std/yaml";
+import { generateDescriptions, Description } from "../runtime/_data.ts";
 
-interface Description {
-  kind: "NOTE" | "TIP" | "IMPORTANT" | "WARNING" | "CAUTION";
-  description: string;
-}
-function handleDescription(description: Description | string): Description {
-  if (typeof description === "string") {
-    return {
-      kind: "WARNING",
-      description,
-    };
-  } else {
-    return description;
-  }
-}
-
-const descriptions: Record<
-  string,
-  { description?: Description; symbols?: Record<string, Description> }
-> = {};
-for await (const dirEntry of walk("node_descriptions", { exts: ["yaml"] })) {
-  const file = await Deno.readTextFile(dirEntry.path);
-  const parsed = yamlParse(file);
-  if (!parsed) {
-    continue;
-  }
-  if (parsed.description) {
-    parsed.description = handleDescription(parsed.description);
-  }
-
-  if (parsed.symbols) {
-    parsed.symbols = Object.fromEntries(
-      Object.entries(parsed.symbols).map((
-        [key, value],
-      ) => [key, handleDescription(value)]),
-    );
-  }
-
-  descriptions[dirEntry.name.slice(0, -5)] = parsed;
-}
+const descriptions = await generateDescriptions();
 
 await Deno.mkdir("types/node", { recursive: true });
 

diff --git a/reference_gen/node_descriptions/assert.yaml b/reference_gen/node_descriptions/assert.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/async_hooks.yaml b/reference_gen/node_descriptions/async_hooks.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   AsyncResource: The AsyncResource implementation is a non-functional stub.
   executionAsyncId: The executionAsyncId implementation is a non-functional stub.

diff --git a/reference_gen/node_descriptions/buffer.yaml b/reference_gen/node_descriptions/buffer.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/child_process.yaml b/reference_gen/node_descriptions/child_process.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/cluster.yaml b/reference_gen/node_descriptions/cluster.yaml
@@ -1,3 +1,4 @@
+status: unsupported
 description: All exports are non-functional stubs.
 symbols:
   "*": This symbol is a non-functional stub.
diff --git a/reference_gen/node_descriptions/console.yaml b/reference_gen/node_descriptions/console.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/crypto.yaml b/reference_gen/node_descriptions/crypto.yaml
@@ -1,3 +1,4 @@
+status: good
 symbols:
   Certificate: The methods are non-functional stubs.
   generateKeyPair: The `x448` option is not supported.

diff --git a/reference_gen/node_descriptions/dgram.yaml b/reference_gen/node_descriptions/dgram.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   Socket: |
    The following methods are non-functional stubs:

diff --git a/reference_gen/node_descriptions/diagnostics_channel.yaml b/reference_gen/node_descriptions/diagnostics_channel.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/dns.yaml b/reference_gen/node_descriptions/dns.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   resolve: The `ttl` option is not supported.
   resolve4: The `ttl` option is not supported.

diff --git a/reference_gen/node_descriptions/domain.yaml b/reference_gen/node_descriptions/domain.yaml
@@ -1,3 +1,4 @@
+status: unsupported
 description: |
   All exports are non-functional stubs.
   This is a deprecated Node module.

diff --git a/reference_gen/node_descriptions/events.yaml b/reference_gen/node_descriptions/events.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/fs--promises.yaml b/reference_gen/node_descriptions/fs--promises.yaml
@@ -1,2 +1,3 @@
+status: good
 symbols:
   lchmod: The lchmod implementation is a non-functional stub.
diff --git a/reference_gen/node_descriptions/fs.yaml b/reference_gen/node_descriptions/fs.yaml
@@ -1,3 +1,4 @@
+status: good
 symbols:
   writeFile: Missing `utf16le`, `latin1` and `ucs2` encoding.
   writeFileSync: Missing `utf16le`, `latin1` and `ucs2` encoding.
diff --git a/reference_gen/node_descriptions/http.yaml b/reference_gen/node_descriptions/http.yaml
@@ -1,3 +1,4 @@
+status: good
 symbols:
   RequestOptions: Option `createConnection` is not supported.
   ClientRequestArgs: Option `createConnection` is not supported.

diff --git a/reference_gen/node_descriptions/http2.yaml b/reference_gen/node_descriptions/http2.yaml
@@ -1 +1,2 @@
-description:  Partially supported, major work in progress to enable `grpc-js`.
+status: partial
+description: Partially supported, major work in progress to enable `grpc-js`.
diff --git a/reference_gen/node_descriptions/https.yaml b/reference_gen/node_descriptions/https.yaml
@@ -1,2 +1,3 @@
+status: partial
 symbols:
   Server: The `cert` and `key` options do not support an array input.
diff --git a/reference_gen/node_descriptions/inspector.yaml b/reference_gen/node_descriptions/inspector.yaml
@@ -1 +1,2 @@
+status: partial
 description: "`console` is supported. Other APIs are non-functional stubs and will throw an error."
diff --git a/reference_gen/node_descriptions/module.yaml b/reference_gen/node_descriptions/module.yaml
@@ -1,2 +1,3 @@
+status: good
 symbols:
   Module: The `register` method is not supported.
diff --git a/reference_gen/node_descriptions/net.yaml b/reference_gen/node_descriptions/net.yaml
@@ -1,2 +1,3 @@
+status: partial
 symbols:
   Socket: The `fd` option is not supported.
diff --git a/reference_gen/node_descriptions/os.yaml b/reference_gen/node_descriptions/os.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/path.yaml b/reference_gen/node_descriptions/path.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/perf_hooks.yaml b/reference_gen/node_descriptions/perf_hooks.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   performance: |
     The `eventLoopUtilization` method is a non-functional stub.

diff --git a/reference_gen/node_descriptions/process.yaml b/reference_gen/node_descriptions/process.yaml
@@ -1 +1,2 @@
+status: partial
 description: The `multipleResolves` and `worker` events are not supported.
diff --git a/reference_gen/node_descriptions/punycode.yaml b/reference_gen/node_descriptions/punycode.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/querystring.yaml b/reference_gen/node_descriptions/querystring.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/readilne.yaml b/reference_gen/node_descriptions/readilne.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/repl.yaml b/reference_gen/node_descriptions/repl.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   REPLServer: This symbol is not supported.
   start: This symbol is not supported.
diff --git a/reference_gen/node_descriptions/sea.yaml b/reference_gen/node_descriptions/sea.yaml
@@ -0,0 +1 @@
+status: unsupported
diff --git a/reference_gen/node_descriptions/sqlite.yaml b/reference_gen/node_descriptions/sqlite.yaml
@@ -1,3 +1,4 @@
+status: unsupported
 description: This module is not implemented.
 symbols:
   "*": This module is not implemented.
diff --git a/reference_gen/node_descriptions/stream.yaml b/reference_gen/node_descriptions/stream.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/string_decoder.yaml b/reference_gen/node_descriptions/string_decoder.yaml
@@ -0,0 +1,2 @@
+
+status: good
diff --git a/reference_gen/node_descriptions/test.yaml b/reference_gen/node_descriptions/test.yaml
@@ -1,2 +1,4 @@
 # TODO: we currently don't render the test module
-#  Currently only `test` API is supported.
+status: partial
+description: Currently only `test` API is supported.
+
diff --git a/reference_gen/node_descriptions/timers.yaml b/reference_gen/node_descriptions/timers.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/tls.yaml b/reference_gen/node_descriptions/tls.yaml
@@ -1,2 +1,3 @@
+status: partial
 symbols:
   createSecurePair: This symbol is currently not supported.
diff --git a/reference_gen/node_descriptions/trace_events.yaml b/reference_gen/node_descriptions/trace_events.yaml
@@ -1,3 +1,4 @@
+status: unsupported
 description: All exports are non-functional stubs.
 symbols:
   "*": This symbol is a non-functional stub.
diff --git a/reference_gen/node_descriptions/tty.yaml b/reference_gen/node_descriptions/tty.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/url.yaml b/reference_gen/node_descriptions/url.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/reference_gen/node_descriptions/util.yaml b/reference_gen/node_descriptions/util.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   transferableAbortSignal: This symbol is currently not supported.
   transferableAbortController: This symbol is currently not supported.

diff --git a/reference_gen/node_descriptions/v8.yaml b/reference_gen/node_descriptions/v8.yaml
@@ -1,3 +1,4 @@
+status: partial
 description: |
   `cachedDataVersionTag` and `getHeapStatistics` are supported. 
   `setFlagsFromStrings` is a noop.

diff --git a/reference_gen/node_descriptions/vm.yaml b/reference_gen/node_descriptions/vm.yaml
@@ -1 +1,2 @@
+status: partial
 description: This module is supported only partially.
diff --git a/reference_gen/node_descriptions/wasi.yaml b/reference_gen/node_descriptions/wasi.yaml
@@ -1,3 +1,4 @@
+status: unsupported
 description: All exports are non-functional stubs.
 symbols:
   "*": This symbol is a non-functional stub.
diff --git a/reference_gen/node_descriptions/worker_threads.yaml b/reference_gen/node_descriptions/worker_threads.yaml
@@ -1,3 +1,4 @@
+status: partial
 symbols:
   parentPort: |
     The `emit` method is not supported.

diff --git a/reference_gen/node_descriptions/zlib.yaml b/reference_gen/node_descriptions/zlib.yaml
@@ -0,0 +1 @@
+status: good
diff --git a/runtime/_data.ts b/runtime/_data.ts
@@ -1,4 +1,6 @@
 import { Sidebar } from "../types.ts";
+import { walk } from "jsr:@std/fs";
+import { parse as yamlParse } from "jsr:@std/yaml";
 
 export const sidebar = [
   {
@@ -240,3 +242,97 @@ export const sidebar = [
 
 export const sectionTitle = "Runtime";
 export const sectionHref = "/runtime/";
+
+export interface Description {
+  kind: "NOTE" | "TIP" | "IMPORTANT" | "WARNING" | "CAUTION";
+  description: string;
+}
+function handleDescription(description: Description | string): Description {
+  if (typeof description === "string") {
+    return {
+      kind: "WARNING",
+      description,
+    };
+  } else {
+    return description;
+  }
+}
+
+export type Descriptions = Record<
+  string,
+  {
+    status: "good" | "partial" | "stubs" | "unsupported";
+    description?: Description;
+    symbols?: Record<string, Description>;
+  }
+>;
+
+export async function generateDescriptions(): Promise<Descriptions> {
+  const descriptions: Descriptions = {};
+  for await (
+    const dirEntry of walk(
+      new URL(import.meta.resolve("../reference_gen/node_descriptions")),
+      { exts: ["yaml"] },
+    )
+  ) {
+    const file = await Deno.readTextFile(dirEntry.path);
+    const parsed = yamlParse(file);
+    if (!parsed) {
+      throw `Invalid or empty file: ${dirEntry.path}`;
+    }
+    if (parsed.description) {
+      parsed.description = handleDescription(parsed.description);
+    }
+
+    if (parsed.symbols) {
+      parsed.symbols = Object.fromEntries(
+        Object.entries(parsed.symbols).map((
+          [key, value],
+        ) => [key, handleDescription(value)]),
+      );
+    }
+
+    if (
+      !(parsed.status === "good" || parsed.status === "partial" ||
+        parsed.status === "stubs" || parsed.status === "unsupported")
+    ) {
+      throw `Invalid status provided in '${dirEntry.name}': ${parsed.status}`;
+    }
+
+    descriptions[dirEntry.name.slice(0, -5)] = parsed;
+  }
+
+  return descriptions;
+}
+
+/*
+generates the node compat list for the Node Support page.
+This the data is read from the files in the reference_gen/node_description directory.
+This function is called in node.md through the templating engine Vento,
+after which the normal markdown rendered is called.
+ */
+export async function generateNodeCompatability() {
+  const descriptions = await generateDescriptions();
+
+  return Object.entries(descriptions).sort(([keyA], [keyB]) =>
+    keyA.localeCompare(keyB)
+  ).map(([key, content]) => {
+    let out =
+      `<div class="module-info compat-status-${content.status}">\n\n### [\`node:${key}\`](/api/node/${key})\n\n</div>\n\n`;
+
+    if (content) {
+      if (content.description) {
+        out += `${content.description.description}\n\n`;
+      }
+      if (content.symbols) {
+        for (const [symbol, description] of Object.entries(content.symbols)) {
+          out += `**${
+            symbol === "*" ? "All symbols" : symbol
+          }**: ${description.description}<br />`;
+        }
+      }
+    }
+
+    return out;
+  }).join("\n\n");
+}
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		status: partial
		description: "`console` is supported. Other APIs are non-functional stubs and will throw an error."
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		status: partial
		description: The `multipleResolves` and `worker` events are not supported.
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		status: partial
		description: This module is supported only partially.