feat(ci): category & unstable tags checker (#23568)

.github/workflows/ci.generate.ts

@@ -664,6 +664,12 @@ const ci = {
           run:
             "deno run --unstable --allow-write --allow-read --allow-run --allow-net ./tools/lint.js",
         },
+        {
+          name: "jsdoc_checker.js",
+          if: "matrix.job == 'lint'",
+          run:
+            "deno run --allow-read --allow-env --allow-sys ./tools/jsdoc_checker.js",
+        },
         {
           name: "node_compat/setup.ts --check",
           if: "matrix.job == 'lint' && matrix.os == 'linux'",

.github/workflows/ci.yml

@@ -396,6 +396,9 @@ jobs:
       - name: lint.js
         if: '!(matrix.skip) && (matrix.job == ''lint'')'
         run: deno run --unstable --allow-write --allow-read --allow-run --allow-net ./tools/lint.js
+      - name: jsdoc_checker.js
+        if: '!(matrix.skip) && (matrix.job == ''lint'')'
+        run: deno run --allow-read --allow-env --allow-sys ./tools/jsdoc_checker.js
       - name: node_compat/setup.ts --check
         if: '!(matrix.skip) && (matrix.job == ''lint'' && matrix.os == ''linux'')'
         run: deno run --allow-write --allow-read --allow-run=git ./tests/node_compat/runner/setup.ts --check

cli/tsc/dts/lib.deno.ns.d.ts

@@ -882,7 +882,7 @@ declare namespace Deno {
   /**
    * @category Testing
    */
-  interface DenoTest {
+  export interface DenoTest {
     /** Register a test which will be run when `deno test` is used on the command
      * line and the containing module looks like a test module.
      *
@@ -4095,7 +4095,7 @@ declare namespace Deno {
    * @deprecated This will be removed in Deno 2.0.
    *
    * @category Observability */
-  interface ResourceMap {
+  export interface ResourceMap {
     [rid: number]: unknown;
   }
 

cli/tsc/dts/lib.deno.shared_globals.d.ts

@@ -628,6 +628,7 @@ declare interface PerformanceMarkOptions {
   startTime?: number;
 }
 
+/** @category Performance */
 declare interface PerformanceMeasureOptions {
   /** Metadata to be included in the measure. */
   detail?: any;

cli/tsc/dts/lib.deno.window.d.ts

@@ -206,6 +206,7 @@ declare function removeEventListener<
   listener: (this: Window, ev: WindowEventMap[K]) => any,
   options?: boolean | EventListenerOptions,
 ): void;
+/** @category DOM Events */
 declare function removeEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject,

ext/broadcast_channel/lib.deno_broadcast_channel.d.ts

@@ -5,13 +5,19 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
-/** @category Broadcast Channel */
+/**
+ * @category Broadcast Channel
+ * @tags unstable
+ */
 declare interface BroadcastChannelEventMap {
   "message": MessageEvent;
   "messageerror": MessageEvent;
 }
 
-/** @category Broadcast Channel */
+/**
+ * @category Broadcast Channel
+ * @tags unstable
+ */
 declare interface BroadcastChannel extends EventTarget {
   /**
    * Returns the channel name (as passed to the constructor).
@@ -51,7 +57,10 @@ declare interface BroadcastChannel extends EventTarget {
   ): void;
 }
 
-/** @category Broadcast Channel */
+/**
+ * @category Broadcast Channel
+ * @tags unstable
+ */
 declare var BroadcastChannel: {
   readonly prototype: BroadcastChannel;
   new (name: string): BroadcastChannel;

ext/canvas/lib.deno_canvas.d.ts

@@ -21,7 +21,7 @@ declare type ResizeQuality = "high" | "low" | "medium" | "pixelated";
 declare type ImageBitmapSource = Blob | ImageData;
 
 /** @category Web APIs */
-interface ImageBitmapOptions {
+declare interface ImageBitmapOptions {
   colorSpaceConversion?: ColorSpaceConversion;
   imageOrientation?: ImageOrientation;
   premultiplyAlpha?: PremultiplyAlpha;
@@ -46,7 +46,7 @@ declare function createImageBitmap(
 ): Promise<ImageBitmap>;
 
 /** @category Web APIs */
-interface ImageBitmap {
+declare interface ImageBitmap {
   readonly height: number;
   readonly width: number;
   close(): void;

ext/websocket/lib.deno_websocket.d.ts

@@ -28,6 +28,7 @@ declare interface CloseEvent extends Event {
   readonly wasClean: boolean;
 }
 
+/** @category Web Sockets */
 declare var CloseEvent: {
   readonly prototype: CloseEvent;
   new (type: string, eventInitDict?: CloseEventInit): CloseEvent;

tests/integration/lsp_tests.rs

@@ -1459,7 +1459,8 @@ fn lsp_hover_asset() {
           "language": "typescript",
           "value": "interface Date",
         },
-        "Enables basic storage and retrieval of dates and times."
+        "Enables basic storage and retrieval of dates and times.",
+        "\n\n*@category* - Temporal  \n\n*@tags* - unstable"
       ],
       "range": {
         "start": { "line": 111, "character": 10, },
@@ -2035,7 +2036,7 @@ fn lsp_hover_unstable_always_enabled() {
           "value":"interface Deno.ForeignLibraryInterface"
         },
         "**UNSTABLE**: New API, yet to be vetted.\n\nA foreign library interface descriptor.",
-        "\n\n*@category* - FFI",
+        "\n\n*@category* - FFI  \n\n*@tags* - unstable",
       ],
       "range":{
         "start":{ "line":0, "character":14 },
@@ -2080,7 +2081,7 @@ fn lsp_hover_unstable_enabled() {
           "value":"interface Deno.ForeignLibraryInterface"
         },
         "**UNSTABLE**: New API, yet to be vetted.\n\nA foreign library interface descriptor.",
-        "\n\n*@category* - FFI",
+        "\n\n*@category* - FFI  \n\n*@tags* - unstable",
       ],
       "range":{
         "start":{ "line":0, "character":14 },

tools/jsdoc_checker.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env -S deno run --allow-read --allow-env --allow-sys
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { Node, Project, ts } from "npm:ts-morph@22.0.0";
+import { join, ROOT_PATH } from "./util.js";
+
+const libs = [
+  join(ROOT_PATH, "ext/cache/lib.deno_cache.d.ts"),
+  join(ROOT_PATH, "ext/console/lib.deno_console.d.ts"),
+  join(ROOT_PATH, "ext/url/lib.deno_url.d.ts"),
+  join(ROOT_PATH, "ext/web/lib.deno_web.d.ts"),
+  join(ROOT_PATH, "ext/fetch/lib.deno_fetch.d.ts"),
+  join(ROOT_PATH, "ext/websocket/lib.deno_websocket.d.ts"),
+  join(ROOT_PATH, "ext/webstorage/lib.deno_webstorage.d.ts"),
+  join(ROOT_PATH, "ext/canvas/lib.deno_canvas.d.ts"),
+  join(ROOT_PATH, "ext/crypto/lib.deno_crypto.d.ts"),
+  join(ROOT_PATH, "ext/net/lib.deno_net.d.ts"),
+  join(ROOT_PATH, "cli/tsc/dts/lib.deno.ns.d.ts"),
+  join(ROOT_PATH, "cli/tsc/dts/lib.deno.shared_globals.d.ts"),
+  join(ROOT_PATH, "cli/tsc/dts/lib.deno.window.d.ts"),
+];
+
+const unstableLibs = [
+  join(ROOT_PATH, "ext/broadcast_channel/lib.deno_broadcast_channel.d.ts"),
+  join(ROOT_PATH, "cli/tsc/dts/lib.deno_webgpu.d.ts"),
+  join(ROOT_PATH, "cli/tsc/dts/lib.deno.unstable.d.ts"),
+];
+
+const errors = [];
+
+const project = new Project();
+project.addSourceFilesAtPaths(libs);
+const unstableFiles = project.addSourceFilesAtPaths(unstableLibs);
+
+for (const file of project.getSourceFiles()) {
+  for (
+    const node of file.getDescendants().filter((descendant) =>
+      Node.isExportable(descendant)
+    )
+  ) {
+    if (
+      node.getKind() === ts.SyntaxKind.ModuleDeclaration &&
+      node.getName() === "Deno"
+    ) {
+      continue;
+    }
+
+    const parent = node.getFirstAncestorByKind(ts.SyntaxKind.ModuleDeclaration);
+
+    if (parent) {
+      if (!node.isExported()) {
+        errors.push(getErrorPrefix(node) + "export keyword");
+        continue;
+      }
+    } else if (!node.hasDeclareKeyword()) {
+      errors.push(getErrorPrefix(node) + "declare keyword");
+      continue;
+    }
+
+    const jsDoc = node.getFirstChildIfKind(ts.SyntaxKind.JSDoc);
+    if (!jsDoc) {
+      errors.push(getErrorPrefix(node) + "JSDoc comment");
+      continue;
+    }
+
+    const tags = jsDoc.getTags();
+
+    if (!tags.find((tag) => tag.getTagName() === "category")) {
+      errors.push(getErrorPrefix(node) + "JSDoc @category tag");
+      continue;
+    }
+
+    if (unstableFiles.includes(file)) {
+      const tagsTag = tags.find((tag) => tag.getTagName() === "tags");
+      if (
+        !(tagsTag?.getComment() &&
+          tagsTag.getCommentText().includes("unstable"))
+      ) {
+        errors.push(
+          getErrorPrefix(node) + "JSDoc @tags tag with value 'unstable'",
+        );
+      }
+    }
+  }
+}
+
+if (errors.length > 0) {
+  throw new AggregateError(errors);
+}
+
+function getErrorPrefix(node) {
+  return `Symbol at file://${node.getSourceFile().getFilePath()}:${node.getStartLineNumber()} is missing a `;
+}