doc: make stability labels more consistent

PR-URL: https://github.com/nodejs/node/pull/57516
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

doc/api/buffer.md

@@ -5356,8 +5356,6 @@ instance.
 deprecated: v6.0.0
 -->
 
-> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead.
-
 * `size` {integer} The desired length of the new `SlowBuffer`.
 
 See [`Buffer.allocUnsafeSlow()`][].

doc/api/cli.md

@@ -61,6 +61,8 @@ changes:
                  Node.js options as well, in addition to V8 options.
 -->
 
+> Stability: 2 - Stable
+
 All options, including V8 options, allow words to be separated by both
 dashes (`-`) or underscores (`_`). For example, `--pending-deprecation` is
 equivalent to `--pending_deprecation`.
@@ -199,8 +201,6 @@ changes:
     description: Paths delimited by comma (`,`) are no longer allowed.
 -->
 
-> Stability: 2 - Stable.
-
 This flag configures file system read permissions using
 the [Permission Model][].
 
@@ -244,8 +244,6 @@ changes:
     description: Paths delimited by comma (`,`) are no longer allowed.
 -->
 
-> Stability: 2 - Stable.
-
 This flag configures file system write permissions using
 the [Permission Model][].
 
@@ -453,8 +451,6 @@ changes:
     description: The flag is no longer experimental.
 -->
 
-> Stability: 2 - Stable
-
 Provide custom [conditional exports][] resolution conditions.
 
 Any number of custom string condition names are permitted.
@@ -480,8 +476,6 @@ changes:
     description: The `--cpu-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Starts the V8 CPU profiler on start up, and writes the CPU profile to disk
 before exit.
 
@@ -518,8 +512,6 @@ changes:
     description: The `--cpu-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the directory where the CPU profiles generated by `--cpu-prof` will
 be placed.
 
@@ -538,8 +530,6 @@ changes:
     description: The `--cpu-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the sampling interval in microseconds for the CPU profiles generated
 by `--cpu-prof`. The default is 1000 microseconds.
 
@@ -555,8 +545,6 @@ changes:
     description: The `--cpu-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the file name of the CPU profile generated by `--cpu-prof`.
 
 ### `--diagnostic-dir=directory`
@@ -1294,8 +1282,6 @@ changes:
     description: The `--heap-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Starts the V8 heap profiler on start up, and writes the heap profile to disk
 before exit.
 
@@ -1323,8 +1309,6 @@ changes:
     description: The `--heap-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the directory where the heap profiles generated by `--heap-prof` will
 be placed.
 
@@ -1343,8 +1327,6 @@ changes:
     description: The `--heap-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the average sampling interval in bytes for the heap profiles generated
 by `--heap-prof`. The default is 512 \* 1024 bytes.
 
@@ -1360,8 +1342,6 @@ changes:
     description: The `--heap-prof` flags are now stable.
 -->
 
-> Stability: 2 - Stable
-
 Specify the file name of the heap profile generated by `--heap-prof`.
 
 ### `--heapsnapshot-near-heap-limit=max_count`
@@ -1906,8 +1886,6 @@ changes:
     description: Permission Model is now stable.
 -->
 
-> Stability: 2 - Stable.
-
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
@@ -2220,8 +2198,6 @@ changes:
                  `PATH` environment variable accordingly.
 -->
 
-> Stability: 2 - Stable
-
 This runs a specified command from a package.json's `"scripts"` object.
 If a missing `"command"` is provided, it will list the available scripts.
 
@@ -3019,8 +2995,6 @@ changes:
     description: Test runner now supports running in watch mode.
 -->
 
-> Stability: 2 - Stable
-
 Starts Node.js in watch mode.
 When in watch mode, changes in the watched files cause the Node.js process to
 restart.
@@ -3049,8 +3023,6 @@ changes:
     description: Watch mode is now stable.
 -->
 
-> Stability: 2 - Stable
-
 Starts Node.js in watch mode and specifies what paths to watch.
 When in watch mode, changes in the watched paths cause the Node.js process to
 restart.
@@ -3093,6 +3065,8 @@ instances.
 
 ## Environment variables
 
+> Stability: 2 - Stable
+
 ### `FORCE_COLOR=[1, 2, 3]`
 
 The `FORCE_COLOR` environment variable is used to

doc/api/diagnostics_channel.md

@@ -635,8 +635,6 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
-
 * `subscribers` {Object} Set of [TracingChannel Channels][] subscribers
   * `start` {Function} The [`start` event][] subscriber
   * `end` {Function} The [`end` event][] subscriber
@@ -704,8 +702,6 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
-
 * `subscribers` {Object} Set of [TracingChannel Channels][] subscribers
   * `start` {Function} The [`start` event][] subscriber
   * `end` {Function} The [`end` event][] subscriber
@@ -775,8 +771,6 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
-
 * `fn` {Function} Function to wrap a trace around
 * `context` {Object} Shared object to correlate events through
 * `thisArg` {any} The receiver to be used for the function call
@@ -826,8 +820,6 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
-
 * `fn` {Function} Promise-returning function to wrap a trace around
 * `context` {Object} Shared object to correlate trace events through
 * `thisArg` {any} The receiver to be used for the function call
@@ -880,8 +872,6 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
-
 * `fn` {Function} callback using function to wrap a trace around
 * `position` {number} Zero-indexed argument position of expected callback
   (defaults to last argument if `undefined` is passed)
@@ -985,8 +975,6 @@ added:
  - v20.13.0
 -->
 
-> Stability: 1 - Experimental
-
 * Returns: {boolean} `true` if any of the individual channels has a subscriber,
   `false` if not.
 

doc/api/esm.md

@@ -275,8 +275,6 @@ changes:
     description: Switch from Import Assertions to Import Attributes.
 -->
 
-> Stability: 2 - Stable
-
 [Import attributes][Import Attributes MDN] are an inline syntax for module import
 statements to pass on more information alongside the module specifier.
 
@@ -640,8 +638,6 @@ changes:
     description: JSON modules are no longer experimental.
 -->
 
-> Stability: 2 - Stable
-
 JSON files can be referenced by `import`:
 
 ```js

doc/api/events.md

@@ -2444,8 +2444,6 @@ changes:
     description: No longer behind `--experimental-global-customevent` CLI flag.
 -->
 
-> Stability: 2 - Stable
-
 * Extends: {Event}
 
 The `CustomEvent` object is an adaptation of the [`CustomEvent` Web API][].
@@ -2465,8 +2463,6 @@ changes:
     description: CustomEvent is now stable.
 -->
 
-> Stability: 2 - Stable
-
 * Type: {any} Returns custom data passed when initializing.
 
 Read-only.

doc/api/globals.md

@@ -31,6 +31,8 @@ changes:
     description: No longer experimental.
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 A utility class used to signal cancelation in selected `Promise`-based APIs.
@@ -230,6 +232,8 @@ If `abortSignal.aborted` is `true`, throws `abortSignal.reason`.
 added: v18.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 See {Blob}.
@@ -240,6 +244,8 @@ See {Blob}.
 added: v0.1.103
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 * {Function}
@@ -282,6 +288,8 @@ Global alias for [`buffer.atob()`][].
 added: v18.0.0
 -->
 
+> Stability: 2 - Stable
+
 See {BroadcastChannel}.
 
 ## `btoa(data)`
@@ -300,6 +308,8 @@ Global alias for [`buffer.btoa()`][].
 added: v0.9.1
 -->
 
+> Stability: 2 - Stable
+
 <!--type=global-->
 
 [`clearImmediate`][] is described in the [timers][] section.
@@ -310,6 +320,8 @@ added: v0.9.1
 added: v0.0.1
 -->
 
+> Stability: 2 - Stable
+
 <!--type=global-->
 
 [`clearInterval`][] is described in the [timers][] section.
@@ -320,6 +332,8 @@ added: v0.0.1
 added: v0.0.1
 -->
 
+> Stability: 2 - Stable
+
 <!--type=global-->
 
 [`clearTimeout`][] is described in the [timers][] section.
@@ -330,6 +344,8 @@ added: v0.0.1
 added: v23.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `CloseEvent` class. See [`CloseEvent`][] for more details.
@@ -355,6 +371,8 @@ A browser-compatible implementation of [`CompressionStream`][].
 added: v0.1.100
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 * {Object}
@@ -388,7 +406,7 @@ changes:
     description: No longer behind `--experimental-global-webcrypto` CLI flag.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 A browser-compatible implementation of {Crypto}. This global is available
 only if the Node.js binary was compiled with including support for the
@@ -409,7 +427,7 @@ changes:
     description: No longer behind `--experimental-global-webcrypto` CLI flag.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 A browser-compatible implementation of the [Web Crypto API][].
 
@@ -428,7 +446,7 @@ changes:
     description: No longer behind `--experimental-global-webcrypto` CLI flag.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 A browser-compatible implementation of {CryptoKey}. This global is available
 only if the Node.js binary was compiled with including support for the
@@ -482,6 +500,8 @@ changes:
     description: No longer experimental.
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 A browser-compatible implementation of the `Event` class. See
@@ -510,6 +530,8 @@ changes:
     description: No longer experimental.
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 A browser-compatible implementation of the `EventTarget` class. See
@@ -545,6 +567,8 @@ A browser-compatible implementation of the [`fetch()`][] function.
 added: v20.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 See {File}.
@@ -630,6 +654,8 @@ of a server, it is shared across all users and requests.
 added: v15.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `MessageChannel` class. See [`MessageChannel`][] for more details.
@@ -640,6 +666,8 @@ The `MessageChannel` class. See [`MessageChannel`][] for more details.
 added: v15.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `MessageEvent` class. See [`MessageEvent`][] for more details.
@@ -650,6 +678,8 @@ The `MessageEvent` class. See [`MessageEvent`][] for more details.
 added: v15.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `MessagePort` class. See [`MessagePort`][] for more details.
@@ -772,6 +802,8 @@ console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21"
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details.
@@ -782,6 +814,8 @@ The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details.
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceMark` class. See [`PerformanceMark`][] for more details.
@@ -792,6 +826,8 @@ The `PerformanceMark` class. See [`PerformanceMark`][] for more details.
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details.
@@ -802,6 +838,8 @@ The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details.
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details.
@@ -812,6 +850,8 @@ The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details.
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceObserverEntryList` class. See
@@ -823,6 +863,8 @@ The `PerformanceObserverEntryList` class. See
 added: v19.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The `PerformanceResourceTiming` class. See [`PerformanceResourceTiming`][] for
@@ -834,6 +876,8 @@ more details.
 added: v16.0.0
 -->
 
+> Stability: 2 - Stable
+
 The [`perf_hooks.performance`][] object.
 
 ## `process`
@@ -842,6 +886,8 @@ The [`perf_hooks.performance`][] object.
 added: v0.1.7
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 * {Object}
@@ -854,6 +900,8 @@ The process object. See the [`process` object][] section.
 added: v11.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 * `callback` {Function} Function to be queued.
@@ -1022,6 +1070,8 @@ the currently running process, and is not shared between workers.
 added: v0.9.1
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 [`setImmediate`][] is described in the [timers][] section.
@@ -1032,6 +1082,8 @@ added: v0.9.1
 added: v0.0.1
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 [`setInterval`][] is described in the [timers][] section.
@@ -1042,6 +1094,8 @@ added: v0.0.1
 added: v0.0.1
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 [`setTimeout`][] is described in the [timers][] section.
@@ -1063,6 +1117,8 @@ A browser-compatible implementation of [`Storage`][]. Enable this API with the
 added: v17.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG [`structuredClone`][] method.
@@ -1079,7 +1135,7 @@ changes:
     description: No longer behind `--experimental-global-webcrypto` CLI flag.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 A browser-compatible implementation of {SubtleCrypto}. This global is available
 only if the Node.js binary was compiled with including support for the
@@ -1091,6 +1147,8 @@ only if the Node.js binary was compiled with including support for the
 added: v17.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG `DOMException` class. See [`DOMException`][] for more details.
@@ -1101,6 +1159,8 @@ The WHATWG `DOMException` class. See [`DOMException`][] for more details.
 added: v11.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section.
@@ -1123,6 +1183,8 @@ A browser-compatible implementation of [`TextDecoderStream`][].
 added: v11.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section.
@@ -1169,6 +1231,8 @@ A browser-compatible implementation of [`TransformStreamDefaultController`][].
 added: v10.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG `URL` class. See the [`URL`][] section.
@@ -1179,6 +1243,8 @@ The WHATWG `URL` class. See the [`URL`][] section.
 added: v10.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section.
@@ -1189,6 +1255,8 @@ The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section.
 added: v8.0.0
 -->
 
+> Stability: 2 - Stable
+
 <!-- type=global -->
 
 * {Object}
@@ -1212,7 +1280,7 @@ changes:
     description: No longer behind `--experimental-websocket` CLI flag.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 A browser-compatible implementation of [`WebSocket`][]. Disable this API
 with the [`--no-experimental-websocket`][] CLI flag.

doc/api/module.md

@@ -1026,9 +1026,6 @@ changes:
     description: Add support for import assertions.
 -->
 
-> Stability: 1.2 - Release candidate (asynchronous version)
-> Stability: 1.1 - Active development (synchronous version)
-
 * `specifier` {string}
 * `context` {Object}
   * `conditions` {string\[]} Export conditions of the relevant `package.json`
@@ -1142,9 +1139,6 @@ changes:
       its return.
 -->
 
-> Stability: 1.2 - Release candidate (asynchronous version)
-> Stability: 1.1 - Active development (synchronous version)
-
 * `url` {string} The URL returned by the `resolve` chain
 * `context` {Object}
   * `conditions` {string\[]} Export conditions of the relevant `package.json`

doc/api/permissions.md

@@ -38,7 +38,7 @@ changes:
     description: This feature is no longer experimental.
 -->
 
-> Stability: 2 - Stable.
+> Stability: 2 - Stable
 
 The Node.js Permission Model is a mechanism for restricting access to specific
 resources during execution.

doc/api/test.md

@@ -2240,8 +2240,6 @@ changes:
     description: The Mock Timers is now stable.
 -->
 
-> Stability: 2 - Stable
-
 Mocking timers is a technique commonly used in software testing to simulate and
 control the behavior of timers, such as `setInterval` and `setTimeout`,
 without actually waiting for the specified time intervals.

doc/api/typescript.md

@@ -55,8 +55,6 @@ To use TypeScript with full support for all TypeScript features, including
 added: v22.6.0
 -->
 
-> Stability: 1.1 - Active development
-
 By default Node.js will execute TypeScript files that contains only
 erasable TypeScript syntax.
 Node.js will replace TypeScript syntax with whitespace,

doc/api/url.md

@@ -1560,8 +1560,6 @@ changes:
     description: The Legacy URL API is deprecated. Use the WHATWG URL API.
 -->
 
-> Stability: 3 - Legacy: Use the WHATWG URL API instead.
-
 The legacy `urlObject` (`require('node:url').Url` or
 `import { Url } from 'node:url'`) is
 created and returned by the `url.parse()` function.
@@ -1689,8 +1687,6 @@ changes:
                  times.
 -->
 
-> Stability: 3 - Legacy: Use the WHATWG URL API instead.
-
 * `urlObject` {Object|string} A URL object (as returned by `url.parse()` or
   constructed otherwise). If a string, it is converted to an object by passing
   it to `url.parse()`.
@@ -1851,8 +1847,6 @@ changes:
                  contains a hostname.
 -->
 
-> Stability: 3 - Legacy: Use the WHATWG URL API instead.
-
 * `from` {string} The base URL to use if `to` is a relative URL.
 * `to` {string} The target URL to resolve.
 

doc/api/zlib.md

@@ -733,8 +733,6 @@ streams:
 
 #### Flush operations
 
-> Stability: 1 - Experimental
-
 The following values are valid flush operations for Zstd-based streams:
 
 * `zlib.constants.ZSTD_e_continue` (default for all operations)
@@ -743,8 +741,6 @@ The following values are valid flush operations for Zstd-based streams:
 
 #### Compressor options
 
-> Stability: 1 - Experimental
-
 There are several options that can be set on Zstd encoders, affecting
 compression efficiency and speed. Both the keys and the values can be accessed
 as properties of the `zlib.constants` object.
@@ -757,16 +753,12 @@ The most important options are:
 
 #### Pledged Source Size
 
-> Stability: 1 - Experimental
-
 It's possible to specify the expected total size of the uncompressed input via
 `opts.pledgedSrcSize`. If the size doesn't match at the end of the input,
 compression will fail with the code `ZSTD_error_srcSize_wrong`.
 
 #### Decompressor options
 
-> Stability: 1 - Experimental
-
 These advanced options are available for controlling decompression:
 
 * `ZSTD_d_windowLogMax`

doc/api_assets/style.css

@@ -294,6 +294,10 @@ li.picker-header a span {
   margin: 0 0 1rem;
   padding: 1rem;
   line-height: 1.5;
+
+  position: sticky;
+  top: 3rem;
+  z-index: 1;
 }
 
 .api_stability * {
@@ -827,6 +831,9 @@ kbd {
     position: relative;
     top: 0;
   }
+  .api_stability {
+    top: 0;
+  }
 }
 
 @media not screen, (max-height: 1000px) {

tools/doc/html.mjs

@@ -216,6 +216,22 @@ export function preprocessElements({ filename }) {
     visit(tree, null, (node, index, parent) => {
       if (node.type === 'heading') {
         headingIndex = index;
+        if (heading) {
+          node.parentHeading = heading;
+          for (let d = heading.depth; d >= node.depth; d--) {
+            node.parentHeading = node.parentHeading.parentHeading;
+          }
+
+          if (heading.depth > 2 || node.depth > 2) {
+            const isNonWrapped = node.depth > 2; // For depth of 1 and 2, there's already a wrapper.
+            parent.children.splice(index++, 0, {
+              type: 'html',
+              value:
+                `</div>`.repeat(heading.depth - node.depth + isNonWrapped) +
+                (isNonWrapped ? '<div>' : ''),
+            });
+          }
+        }
         heading = node;
       } else if (node.type === 'code') {
         if (!node.lang) {
@@ -286,13 +302,20 @@ export function preprocessElements({ filename }) {
 
           if (heading && isStabilityIndex) {
             heading.stability = number;
+            for (let h = heading; h != null; h = h.parentHeading) {
+              if (!h.hasStabilityIndexElement) continue;
+              if (h.stability === number && h.explication === explication) {
+                throw new Error(`Duplicate stability index at ${filename}:${node.position.start.line}, it already inherits it from a parent heading ${filename}:${h.position.start.line}`);
+              } else break;
+            }
+            heading.hasStabilityIndexElement = true;
+            heading.explication = explication;
             headingIndex = -1;
-            heading = null;
           }
 
           // Do not link to the section we are already in.
           const noLinking = filename.includes('documentation') &&
-            heading !== null && heading.children[0].value === 'Stability index';
+            !heading.hasStabilityIndexElement && heading.children[0].value === 'Stability index';
 
           // Collapse blockquote and paragraph into a single node
           node.type = 'paragraph';
@@ -316,6 +339,10 @@ export function preprocessElements({ filename }) {
           node.children.push({ type: 'html', value: '</div>' });
         }
       }
+
+      // In case we've inserted/removed node(s) before the current one, we need
+      // to make sure we're not visiting the same node again or skipping one.
+      return [true, index + 1];
     });
   };
 }