chore: update doc linter, replace hardcoded entry list with dynamically created one (#6491)

Author: timreichen

_tools/check_docs.ts

@@ -23,132 +23,48 @@ import {
   type Location,
   type TsTypeDef,
 } from "@deno/doc";
-import { pooledMap } from "@std/async/pool";
+import { walk } from "@std/fs/walk";
+import { join } from "@std/path/join";
+import { distinctBy } from "@std/collections/distinct-by";
+import { toFileUrl } from "@std/path/to-file-url";
 
 type DocNodeWithJsDoc<T = DocNodeBase> = T & {
   jsDoc: JsDoc;
 };
 
-const ENTRY_POINTS = [
-  "../assert/mod.ts",
-  "../assert/unstable_never.ts",
-  "../async/mod.ts",
-  "../bytes/mod.ts",
-  "../cache/mod.ts",
-  "../cbor/mod.ts",
-  "../cli/mod.ts",
-  "../cli/unstable_spinner.ts",
-  "../cli/unstable_prompt_multiple_select.ts",
-  "../crypto/mod.ts",
-  "../collections/mod.ts",
-  "../csv/mod.ts",
-  "../csv/unstable_stringify.ts",
-  "../data_structures/mod.ts",
-  "../data_structures/unstable_bidirectional_map.ts",
-  "../datetime/mod.ts",
-  "../dotenv/mod.ts",
-  "../encoding/mod.ts",
-  "../encoding/unstable_hex.ts",
-  "../encoding/unstable_base32.ts",
-  "../encoding/unstable_base64.ts",
-  "../encoding/unstable_hex.ts",
-  "../encoding/unstable_base64_stream.ts",
-  "../encoding/unstable_base32_stream.ts",
-  "../encoding/unstable_hex_stream.ts",
-  "../expect/mod.ts",
-  "../fmt/bytes.ts",
-  "../fmt/colors.ts",
-  "../fmt/duration.ts",
-  "../fmt/printf.ts",
-  "../front_matter/mod.ts",
-  "../front_matter/unstable_yaml.ts",
-  "../fs/mod.ts",
-  "../fs/unstable_chmod.ts",
-  "../fs/unstable_copy_file.ts",
-  "../fs/unstable_link.ts",
-  "../fs/unstable_lstat.ts",
-  "../fs/unstable_make_temp_dir.ts",
-  "../fs/unstable_make_temp_file.ts",
-  "../fs/unstable_mkdir.ts",
-  "../fs/unstable_read_dir.ts",
-  "../fs/unstable_read_file.ts",
-  "../fs/unstable_read_link.ts",
-  "../fs/unstable_read_text_file.ts",
-  "../fs/unstable_real_path.ts",
-  "../fs/unstable_remove.ts",
-  "../fs/unstable_rename.ts",
-  "../fs/unstable_stat.ts",
-  "../fs/unstable_symlink.ts",
-  "../fs/unstable_truncate.ts",
-  "../fs/unstable_types.ts",
-  "../fs/unstable_umask.ts",
-  "../fs/unstable_utime.ts",
-  "../fs/unstable_write_file.ts",
-  "../fs/unstable_write_text_file.ts",
-  "../html/mod.ts",
-  "../html/unstable_is_valid_custom_element_name.ts",
-  "../http/mod.ts",
-  "../http/unstable_header.ts",
-  "../http/unstable_method.ts",
-  "../http/unstable_signed_cookie.ts",
-  "../ini/mod.ts",
-  "../internal/mod.ts",
-  "../io/mod.ts",
-  "../json/mod.ts",
-  "../jsonc/mod.ts",
-  "../log/base_handler.ts",
-  "../log/file_handler.ts",
-  "../log/warn.ts",
-  "../log/critical.ts",
-  "../log/debug.ts",
-  "../log/error.ts",
-  "../log/info.ts",
-  "../log/console_handler.ts",
-  "../log/formatters.ts",
-  "../log/get_logger.ts",
-  "../log/logger.ts",
-  "../media_types/mod.ts",
-  "../msgpack/mod.ts",
-  "../net/mod.ts",
-  "../net/unstable_get_network_address.ts",
-  "../path/mod.ts",
-  "../path/unstable_basename.ts",
-  "../path/unstable_dirname.ts",
-  "../path/unstable_extname.ts",
-  "../path/unstable_join.ts",
-  "../path/unstable_normalize.ts",
-  "../path/posix/mod.ts",
-  "../path/windows/mod.ts",
-  "../random/mod.ts",
-  "../regexp/mod.ts",
-  "../semver/mod.ts",
-  "../streams/mod.ts",
-  "../streams/unstable_fixed_chunk_stream.ts",
-  "../streams/unstable_to_lines.ts",
-  "../streams/unstable_to_bytes.ts",
-  "../tar/mod.ts",
-  "../text/mod.ts",
-  "../text/unstable_slugify.ts",
-  "../text/unstable_to_constant_case.ts",
-  "../testing/bdd.ts",
-  "../testing/mock.ts",
-  "../testing/snapshot.ts",
-  "../testing/time.ts",
-  "../testing/types.ts",
-  "../toml/mod.ts",
-  "../ulid/mod.ts",
-  "../uuid/mod.ts",
-  "../uuid/unstable_v7.ts",
-  "../webgpu/mod.ts",
-  "../yaml/mod.ts",
-] as const;
+const ROOT = new URL("../", import.meta.url);
+const ENTRY_POINT_URLS = [];
+for await (
+  const { path } of walk(ROOT, { exts: [".json"], match: [/deno.json$/] })
+) {
+  const { exports } = await Deno.readTextFile(path).then(JSON.parse);
+
+  if (!exports) continue;
+  for (const relativeFilePath of Object.values<string>(exports)) {
+    if (!relativeFilePath.endsWith(".ts")) continue;
+
+    const filePath = join(path, "..", relativeFilePath);
+
+    // Ignores 4 files in @std/log package
+    if (
+      /log[/\\](mod|levels|setup|rotating_file_handler)\.ts$/.test(filePath)
+    ) {
+      // deno-lint-ignore no-console
+      console.warn(
+        `Doc check for ${filePath} is ignored. Visit https://github.com/denoland/std/issues/6124 for more details.`,
+      );
+      continue;
+    }
+
+    ENTRY_POINT_URLS.push(toFileUrl(filePath).href);
+  }
+}
 
 const TS_SNIPPET = /```ts[\s\S]*?```/g;
 const ASSERTION_IMPORT =
   /from "@std\/(assert(\/[a-z-]+)?|testing\/(mock|snapshot|types))"/g;
 const NEWLINE = "\n";
 const diagnostics: DocumentError[] = [];
-const snippetPromises: (() => Promise<void>)[] = [];
 
 class DocumentError extends Error {
   constructor(
@@ -274,10 +190,8 @@ function assertSnippetsWork(
           document,
         ),
       );
-      return;
-    } else {
-      return;
     }
+    return;
   }
   for (let snippet of snippets) {
     const delim = snippet.split(NEWLINE)[0];
@@ -413,7 +327,9 @@ function assertClassDocs(document: DocNodeWithJsDoc<DocNodeClass>) {
   for (const typeParam of document.classDef.typeParams) {
     assertHasTypeParamTags(document, typeParam.name);
   }
-  assertHasExampleTag(document);
+  if (!document.jsDoc.tags?.some((tag) => tag.kind === "example")) {
+    assertHasExampleTag(document);
+  }
 
   for (const property of document.classDef.properties) {
     if (property.jsDoc === undefined) continue; // this is caught by `deno doc --lint`
@@ -547,10 +463,13 @@ async function checkDocs(specifier: string) {
   const docs = (await doc([specifier], { resolve }))[specifier]!;
   for (const d of docs.filter(isExported)) {
     if (d.jsDoc === undefined) continue; // this is caught by other checks
+
     const document = d as DocNodeWithJsDoc<DocNode>;
     switch (document.kind) {
       case "moduleDoc": {
-        assertModuleDoc(document);
+        if (document.location.filename.endsWith("/mod.ts")) {
+          assertModuleDoc(document);
+        }
         break;
       }
       case "function": {
@@ -567,10 +486,6 @@ async function checkDocs(specifier: string) {
   }
 }
 
-const ENTRY_POINT_URLS = ENTRY_POINTS.map((entry) =>
-  new URL(entry, import.meta.url).href
-);
-
 const lintStatus = await new Deno.Command(Deno.execPath(), {
   args: ["doc", "--lint", ...ENTRY_POINT_URLS],
   stdin: "inherit",
@@ -587,18 +502,13 @@ if (!lintStatus.success) {
   Deno.exit(1);
 }
 
-await Promise.all(ENTRY_POINT_URLS.map(checkDocs));
-
-const iter = pooledMap(
-  navigator.hardwareConcurrency,
-  snippetPromises,
-  (fn) => fn(),
-);
-for await (const _ of iter) {
-  // noop
+for (const url of ENTRY_POINT_URLS) {
+  await checkDocs(url);
 }
+
 if (diagnostics.length > 0) {
-  for (const error of diagnostics) {
+  const errors = distinctBy(diagnostics, (e) => e.message + e.cause);
+  for (const error of errors) {
     // deno-lint-ignore no-console
     console.error(
       `%c[error] %c${error.message} %cat ${error.cause}`,
@@ -609,6 +519,6 @@ if (diagnostics.length > 0) {
   }
 
   // deno-lint-ignore no-console
-  console.log(`%c${diagnostics.length} errors found`, "color: red");
+  console.log(`%c${errors.length} errors found`, "color: red");
   Deno.exit(1);
 }

_tools/check_mod_exports.ts

@@ -6,40 +6,13 @@ import { relative } from "../path/relative.ts";
 import { dirname } from "../path/dirname.ts";
 import * as colors from "../fmt/colors.ts";
 import ts from "npm:typescript";
+import { isTestFile } from "./utils.ts";
 
 const ROOT = new URL("../", import.meta.url);
 const FAIL_FAST = Deno.args.includes("--fail-fast");
 
 let shouldFail = false;
 
-function hasExports(filePath: string): boolean {
-  const source = Deno.readTextFileSync(filePath);
-  const sourceFile = ts.createSourceFile(
-    filePath,
-    source,
-    ts.ScriptTarget.Latest,
-  );
-
-  let result = false;
-
-  function visitNode(node: ts.Node) {
-    if (
-      ts.isExportSpecifier(node) ||
-      ts.isExportAssignment(node) ||
-      ts.isExportDeclaration(node) ||
-      node.kind === ts.SyntaxKind.ExportKeyword
-    ) {
-      result = true;
-    } else {
-      ts.forEachChild(node, visitNode);
-    }
-  }
-
-  visitNode(sourceFile);
-
-  return result;
-}
-
 for await (
   const { path: modFilePath } of walk(ROOT, {
     includeDirs: true,
@@ -95,8 +68,7 @@ for await (
       .replaceAll("\\", "/");
 
     if (!modExportSpecifiers.has(relativeSpecifier)) {
-      // ignore test.ts files have no exports (which means that are Deno.test() files)
-      if (relativeSpecifier === "./test.ts" && !hasExports(filePath)) continue;
+      if (isTestFile(filePath)) continue;
 
       console.warn(
         `${

_tools/utils.ts

@@ -1,5 +1,7 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 
+import ts from "npm:typescript";
+
 const workspaces = JSON.parse(await Deno.readTextFile("deno.json"))
   .workspace as string[];
 // deno-lint-ignore no-explicit-any
@@ -34,3 +36,37 @@ export function resolveWorkspaceSpecifiers(
     return new URL(specifier).href;
   }
 }
+
+/**
+ * Checks whether a file is named `test.ts` and has no exports.
+ * @param filePath
+ * @returns true if file is named `test.ts` and has no exports, false otherwise
+ */
+export function isTestFile(filePath: string): boolean {
+  if (!filePath.endsWith("test.ts")) return false;
+  const source = Deno.readTextFileSync(filePath);
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+  );
+
+  let result = true;
+
+  function visitNode(node: ts.Node) {
+    if (!result) return;
+    if (
+      ts.isExportSpecifier(node) ||
+      ts.isExportAssignment(node) ||
+      ts.isExportDeclaration(node) ||
+      node.kind === ts.SyntaxKind.ExportKeyword
+    ) {
+      result = false;
+    } else {
+      ts.forEachChild(node, visitNode);
+    }
+  }
+
+  visitNode(sourceFile);
+  return result;
+}

cli/unstable_progress_bar.ts

@@ -82,6 +82,10 @@ export interface ProgressBarOptions {
    * Default Style: `[mm:ss] [###-------] [0.24/97.6 KiB]`.
    */
   fmt?: (fmt: ProgressBarFormatter) => string;
+  /**
+   * Whether the writable should be kept open when progress bar stops.
+   * @default {true}
+   */
   keepOpen?: boolean;
 }
 
@@ -242,6 +246,13 @@ export class ProgressBar {
   /**
    * Increments the progress by `x`.
    *
+   * @example Usage
+   * ```ts ignore
+   * import { ProgressBar } from "@std/cli/unstable-progress-bar";
+   *
+   * const progressBar = new ProgressBar(Deno.stdout.writable, { max: 100 });
+   * progressBar.add(10);
+   * ```
    * @param x The amount of progress that has been made.
    */
   add(x: number): void {
@@ -250,6 +261,14 @@ export class ProgressBar {
 
   /**
    * Ends the progress bar and cleans up any lose ends.
+   *
+   * @example Usage
+   * ```ts ignore
+   * import { ProgressBar } from "@std/cli/unstable-progress-bar";
+   *
+   * const progressBar = new ProgressBar(Deno.stdout.writable, { max: 100 });
+   * await progressBar.end()
+   * ```
    */
   async end(): Promise<void> {
     clearInterval(this.#id);