feat: print warning on use of deprecated API

deno.json

@@ -12,7 +12,7 @@
     "automation/": "https://raw.githubusercontent.com/denoland/automation/0.10.0/"
   },
   "tasks": {
-    "test": "deno test --doc --unstable --allow-all --parallel --coverage --trace-ops",
+    "test": "NO_DEPRECATION_WARNINGS=1 deno test --doc --unstable --allow-all --parallel --coverage --trace-ops",
     "test:browser": "git grep --name-only \"This module is browser compatible.\" | grep -v deno.json | grep -v .github/workflows | grep -v _tools | xargs deno check --config browser-compat.tsconfig.json",
     "fmt:licence-headers": "deno run --allow-read --allow-write ./_tools/check_licence.ts",
     "lint:deprecations": "deno run --allow-read --allow-net --allow-env=HOME ./_tools/check_deprecation.ts",

internal/mod.ts

@@ -0,0 +1,9 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Internal utilities for the public API of the Deno Standard Library.
+ *
+ * Note: for internal use only.
+ *
+ * @module
+ */

internal/warn_on_deprecated_api.ts

@@ -0,0 +1,94 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+// deno-lint-ignore no-explicit-any
+const { Deno } = globalThis as any;
+
+const ALREADY_WARNED_DEPRECATED = new Set<string>();
+
+interface WarnDeprecatedApiConfig {
+  /** The name of the deprecated API. */
+  apiName: string;
+  /** The stack trace of the deprecated API. */
+  stack: string;
+  /** The version in which the API will be removed. */
+  removalVersion: string;
+  /** An optional message to print. */
+  suggestion?: string;
+}
+
+/**
+ * Prints a warning message to the console for the given deprecated API.
+ *
+ * These warnings can be disabled by setting `NO_DEPRECATION_WARNINGS=1`
+ * in the current process.
+ */
+export function warnOnDeprecatedApi(config: WarnDeprecatedApiConfig) {
+  const variable = "NO_DEPRECATION_WARNINGS";
+  if (
+    Deno?.permissions.querySync({ name: "env", variable }).state ===
+      "granted" && Deno?.env.get(variable) === "1"
+  ) return;
+
+  const key = config.apiName + config.stack;
+  if (ALREADY_WARNED_DEPRECATED.has(key)) return;
+
+  // If we haven't warned yet, let's do some processing of the stack trace
+  // to make it more useful.
+  const stackLines = config.stack.split("\n");
+  stackLines.shift();
+
+  let isFromRemoteDependency = false;
+  const firstStackLine = stackLines[0];
+  if (firstStackLine && !firstStackLine.includes("file:")) {
+    isFromRemoteDependency = true;
+  }
+
+  ALREADY_WARNED_DEPRECATED.add(key);
+  console.log(
+    "%cWarning",
+    "color: yellow; font-weight: bold;",
+  );
+  console.log(
+    `%c\u251c Use of deprecated "${config.apiName}" API.`,
+    "color: yellow;",
+  );
+  console.log("%c\u2502", "color: yellow;");
+  console.log(
+    `%c\u251c This API will be removed in version ${config.removalVersion} of the Deno Standard Library.`,
+    "color: yellow;",
+  );
+  console.log("%c\u2502", "color: yellow;");
+  console.log(
+    `%c\u251c Suggestion: ${config.suggestion}`,
+    "color: yellow;",
+  );
+  if (isFromRemoteDependency) {
+    console.log("%c\u2502", "color: yellow;");
+    console.log(
+      `%c\u251c Suggestion: It appears this API is used by a remote dependency.`,
+      "color: yellow;",
+    );
+    console.log(
+      "%c\u2502             Try upgrading to the latest version of that dependency.",
+      "color: yellow;",
+    );
+  }
+
+  console.log("%c\u2502", "color: yellow;");
+  console.log("%c\u2502", "color: yellow;");
+  console.log(
+    "%c\u251c Set `NO_DEPRECATION_WARNINGS=1` to disable these deprecation warnings.",
+    "color: yellow;",
+  );
+  console.log("%c\u2514 Stack trace:", "color: yellow;");
+  for (let i = 0; i < stackLines.length; i++) {
+    console.log(
+      `%c  ${i == stackLines.length - 1 ? "\u2514" : "\u251c"}\u2500 ${
+        stackLines[i].trim()
+      }`,
+      "color: yellow;",
+    );
+  }
+  console.log();
+}

streams/read_all.ts

@@ -6,6 +6,7 @@ import {
   readAllSync as _readAllSync,
 } from "../io/read_all.ts";
 import type { Reader, ReaderSync } from "../io/types.ts";
+import { warnOnDeprecatedApi } from "../internal/warn_on_deprecated_api.ts";
 
 /**
  * Read {@linkcode Reader} `r` until EOF (`null`) and resolve to the content as
@@ -33,6 +34,12 @@ import type { Reader, ReaderSync } from "../io/types.ts";
  * @deprecated (will be removed in 0.214.0) Import from {@link https://deno.land/std/io/read_all.ts} instead.
  */
 export async function readAll(r: Reader): Promise<Uint8Array> {
+  warnOnDeprecatedApi({
+    apiName: "readAll()",
+    stack: new Error().stack!,
+    removalVersion: "0.214.0",
+    suggestion: "Import from `https://deno.land/std/io/read_all.ts` instead.",
+  });
   return await _readAll(r);
 }
 
@@ -62,5 +69,11 @@ export async function readAll(r: Reader): Promise<Uint8Array> {
  * @deprecated (will be removed in 0.214.0) Import from {@link https://deno.land/std/io/read_all.ts} instead.
  */
 export function readAllSync(r: ReaderSync): Uint8Array {
+  warnOnDeprecatedApi({
+    apiName: "readAllSync()",
+    stack: new Error().stack!,
+    removalVersion: "0.214.0",
+    suggestion: "Import from `https://deno.land/std/io/read_all.ts` instead.",
+  });
   return _readAllSync(r);
 }