docs: add permission tags to JSDocs (#15541)

Co-authored-by: Leo Kettmeir <crowlkats@toaxl.com>

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

@@ -562,7 +562,10 @@ declare namespace Deno {
    */
   export function exit(code?: number): never;
 
-  /** @category Runtime Environment */
+  /**
+   * @tags allow-env
+   * @category Runtime Environment
+   */
   export const env: {
     /** Retrieve the value of an environment variable. Returns `undefined` if that
      * key doesn't exist.
@@ -571,7 +574,10 @@ declare namespace Deno {
      * console.log(Deno.env.get("HOME"));  // e.g. outputs "/home/alice"
      * console.log(Deno.env.get("MADE_UP_VAR"));  // outputs "undefined"
      * ```
-     * Requires `allow-env` permission. */
+     * Requires `allow-env` permission.
+     *
+     * @tags allow-env
+     */
     get(key: string): string | undefined;
 
     /** Set the value of an environment variable.
@@ -581,7 +587,10 @@ declare namespace Deno {
      * Deno.env.get("SOME_VAR");  // outputs "Value"
      * ```
      *
-     * Requires `allow-env` permission. */
+     * Requires `allow-env` permission.
+     *
+     * @tags allow-env
+     */
     set(key: string, value: string): void;
 
     /** Delete the value of an environment variable.
@@ -591,7 +600,10 @@ declare namespace Deno {
      * Deno.env.delete("SOME_VAR");  // outputs "undefined"
      * ```
      *
-     * Requires `allow-env` permission. */
+     * Requires `allow-env` permission.
+     *
+     * @tags allow-env
+     */
     delete(key: string): void;
 
     /** Returns a snapshot of the environment variables at invocation.
@@ -604,7 +616,10 @@ declare namespace Deno {
      * console.log(myEnv.TEST_VAR);  // outputs "A"
      * ```
      *
-     * Requires `allow-env` permission. */
+     * Requires `allow-env` permission.
+     *
+     * @tags allow-env
+     */
     toObject(): { [index: string]: string };
   };
 
@@ -617,6 +632,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category Runtime Environment
    */
   export function execPath(): string;
@@ -636,6 +652,7 @@ declare namespace Deno {
    *
    * Requires --allow-read.
    *
+   * @tags allow-read
    * @category Runtime Environment
    */
   export function chdir(directory: string | URL): void;
@@ -654,6 +671,7 @@ declare namespace Deno {
    *
    * Requires --allow-read
    *
+   * @tags allow-read
    * @category Runtime Environment
    */
   export function cwd(): string;
@@ -667,6 +685,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read
    * @category File System
    */
   export function linkSync(oldpath: string, newpath: string): void;
@@ -680,6 +699,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read
    * @category File System
    */
   export function link(oldpath: string, newpath: string): Promise<void>;
@@ -935,6 +955,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and/or `allow-write` permissions depending on options.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function openSync(path: string | URL, options?: OpenOptions): FsFile;
@@ -952,6 +973,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and/or `allow-write` permissions depending on options.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function open(
@@ -968,6 +990,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function createSync(path: string | URL): FsFile;
@@ -981,6 +1004,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function create(path: string | URL): Promise<FsFile>;
@@ -1615,6 +1639,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function mkdirSync(path: string | URL, options?: MkdirOptions): void;
@@ -1631,6 +1656,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function mkdir(
@@ -1673,6 +1699,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   // TODO(ry) Doesn't check permissions.
@@ -1696,6 +1723,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   // TODO(ry) Doesn't check permissions.
@@ -1719,6 +1747,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function makeTempFileSync(options?: MakeTempOptions): string;
@@ -1741,6 +1770,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function makeTempFile(options?: MakeTempOptions): Promise<string>;
@@ -1758,6 +1788,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function chmodSync(path: string | URL, mode: number): void;
@@ -1791,6 +1822,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function chmod(path: string | URL, mode: number): Promise<void>;
@@ -1806,6 +1838,7 @@ declare namespace Deno {
    *
    * Throws Error (not implemented) if executed on Windows
    *
+   * @tags allow-write
    * @category File System
    *
    * @param path path to the file
@@ -1829,6 +1862,7 @@ declare namespace Deno {
    *
    * Throws Error (not implemented) if executed on Windows
    *
+   * @tags allow-write
    * @category File System
    *
    * @param path path to the file
@@ -1860,6 +1894,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function removeSync(path: string | URL, options?: RemoveOptions): void;
@@ -1876,6 +1911,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function remove(
@@ -1899,6 +1935,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function renameSync(
@@ -1922,6 +1959,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permission.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function rename(
@@ -1939,6 +1977,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readTextFileSync(path: string | URL): string;
@@ -1953,6 +1992,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readTextFile(
@@ -1972,6 +2012,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readFileSync(path: string | URL): Uint8Array;
@@ -1988,6 +2029,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readFile(
@@ -2078,6 +2120,7 @@ declare namespace Deno {
    * Also requires `allow-read` permission for the CWD if the target path is
    * relative.
    *
+   * @tags allow-read
    * @category File System
    */
   export function realPathSync(path: string | URL): string;
@@ -2097,6 +2140,7 @@ declare namespace Deno {
    * Also requires `allow-read` permission for the CWD if the target path is
    * relative.
    *
+   * @tags allow-read
    * @category File System
    */
   export function realPath(path: string | URL): Promise<string>;
@@ -2121,6 +2165,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readDirSync(path: string | URL): Iterable<DirEntry>;
@@ -2138,6 +2183,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readDir(path: string | URL): AsyncIterable<DirEntry>;
@@ -2153,6 +2199,7 @@ declare namespace Deno {
    * Requires `allow-read` permission on fromPath.
    * Requires `allow-write` permission on toPath.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function copyFileSync(
@@ -2171,6 +2218,7 @@ declare namespace Deno {
    * Requires `allow-read` permission on fromPath.
    * Requires `allow-write` permission on toPath.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function copyFile(
@@ -2189,6 +2237,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readLinkSync(path: string | URL): string;
@@ -2204,6 +2253,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function readLink(path: string | URL): Promise<string>;
@@ -2220,6 +2270,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function lstat(path: string | URL): Promise<FileInfo>;
@@ -2236,6 +2287,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function lstatSync(path: string | URL): FileInfo;
@@ -2251,6 +2303,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function stat(path: string | URL): Promise<FileInfo>;
@@ -2266,6 +2319,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
+   * @tags allow-read
    * @category File System
    */
   export function statSync(path: string | URL): FileInfo;
@@ -2306,6 +2360,7 @@ declare namespace Deno {
    * Requires `allow-write` permission, and `allow-read` if `options.create` is
    * `false`.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function writeFileSync(
@@ -2328,6 +2383,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function writeFile(
@@ -2345,6 +2401,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function writeTextFileSync(
@@ -2362,6 +2419,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function writeTextFile(
@@ -2388,6 +2446,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function truncateSync(name: string, len?: number): void;
@@ -2409,6 +2468,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function truncate(name: string, len?: number): Promise<void>;
@@ -2556,6 +2616,7 @@ declare namespace Deno {
    * }
    * ```
    *
+   * @tags allow-read
    * @category File System
    */
   export function watchFs(
@@ -2769,6 +2830,7 @@ declare namespace Deno {
    *
    * Requires `allow-run` permission.
    *
+   * @tags allow-run
    * @category Sub Process
    */
   export function run<T extends RunOptions = RunOptions>(opt: T): Process<T>;
@@ -3073,6 +3135,7 @@ declare namespace Deno {
    *
    * Requires full `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function symlinkSync(
@@ -3093,6 +3156,7 @@ declare namespace Deno {
    *
    * Requires full `allow-read` and `allow-write` permissions.
    *
+   * @tags allow-read, allow-write
    * @category File System
    */
   export function symlink(
@@ -3310,6 +3374,7 @@ declare namespace Deno {
    *
    * Requires `allow-run` permission.
    *
+   * @tags allow-run
    * @category Sub Process
    */
   export function kill(pid: number, signo: Signal): void;
@@ -3474,6 +3539,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function resolveDns(

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

@@ -586,6 +586,8 @@ declare class Performance extends EventTarget {
    * const t = performance.now();
    * console.log(`${t} ms since start!`);
    * ```
+   *
+   * @tags allow-hrtime
    */
   now(): number;
 

cli/dts/lib.deno.unstable.d.ts

@@ -242,6 +242,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Observability
    */
   export function loadavg(): number[];
@@ -258,6 +259,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Runtime Environment
    */
   export function osRelease(): string;
@@ -275,6 +277,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Runtime Environment
    */
   export function systemMemoryInfo(): SystemMemoryInfo;
@@ -331,6 +334,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Network
    */
   export function networkInterfaces(): NetworkInterfaceInfo[];
@@ -345,6 +349,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Runtime Environment
    */
   export function getUid(): number | null;
@@ -359,6 +364,7 @@ declare namespace Deno {
    *
    * Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Runtime Environment
    */
   export function getGid(): number | null;
@@ -790,6 +796,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function utimeSync(
@@ -810,6 +817,7 @@ declare namespace Deno {
    *
    * Requires `allow-write` permission.
    *
+   * @tags allow-write
    * @category File System
    */
   export function utime(
@@ -842,6 +850,7 @@ declare namespace Deno {
    *
    *  Requires `allow-env` permission.
    *
+   * @tags allow-env
    * @category Runtime Environment
    */
   export function hostname(): string;
@@ -992,6 +1001,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permission.
    *
+   * @tags allow-read, allow-write
    * @category Network
    */
   export function listen(
@@ -1016,6 +1026,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function listenDatagram(
@@ -1035,6 +1046,7 @@ declare namespace Deno {
    *
    * Requires `allow-read` and `allow-write` permission.
    *
+   * @tags allow-read, allow-write
    * @category Network
    */
   export function listenDatagram(
@@ -1062,6 +1074,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission for "tcp" and `allow-read` for "unix".
    *
+   * @tags allow-net, allow-read
    * @category Network
    */
   export function connect(
@@ -1118,6 +1131,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
@@ -1502,7 +1516,10 @@ declare namespace Deno {
   }
 }
 
-/** @category Fetch API */
+/**
+ * @tags allow-net, allow-read
+ * @category Fetch API
+ */
 declare function fetch(
   input: Request | URL | string,
   init?: RequestInit & { client: Deno.HttpClient },
@@ -1563,7 +1580,10 @@ declare interface WebSocketCloseInfo {
   reason?: string;
 }
 
-/** @category Web Sockets */
+/**
+ * @tags allow-net
+ * @category Web Sockets
+ */
 declare class WebSocketStream {
   constructor(url: string, options?: WebSocketStreamOptions);
   url: string;

ext/fetch/lib.deno_fetch.d.ts

@@ -464,6 +464,7 @@ declare class Response implements Body {
  * const jsonData = await response.json();
  * ```
  *
+ * @tags allow-net, allow-read
  * @category Fetch API
  */
 declare function fetch(

ext/net/lib.deno_net.d.ts

@@ -102,6 +102,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function listen(
@@ -117,11 +118,13 @@ declare namespace Deno {
     /** Path to a file containing a PEM formatted CA certificate. Requires
      * `--allow-read`.
      *
+     * @tags allow-read
      * @deprecated This option is deprecated and will be removed in Deno 2.0.
      */
     certFile?: string;
     /** Server private key file. Requires `--allow-read`.
      *
+     * @tags allow-read
      * @deprecated This option is deprecated and will be removed in Deno 2.0.
      */
     keyFile?: string;
@@ -138,6 +141,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function listenTls(options: ListenTlsOptions): TlsListener;
@@ -165,6 +169,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission for "tcp".
    *
+   * @tags allow-net
    * @category Network
    */
   export function connect(options: ConnectOptions): Promise<TcpConn>;
@@ -225,6 +230,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
@@ -255,6 +261,7 @@ declare namespace Deno {
    *
    * Requires `allow-net` permission.
    *
+   * @tags allow-net
    * @category Network
    */
   export function startTls(

ext/websocket/lib.deno_websocket.d.ts

@@ -44,6 +44,7 @@ interface WebSocketEventMap {
  * If you are looking to create a WebSocket server, please take a look at
  * `Deno.upgradeWebSocket()`.
  *
+ * @tags allow-net
  * @category Web Sockets
  */
 declare class WebSocket extends EventTarget {