docs: add or update JSDoc comments (#172)

prisis · cursoragent · web-flow · commit d392c8249ed8 · 2025-07-02T17:59:11.000+02:00
Co-authored-by: d.bannert &lt;d.bannert@anolilab.de&gt;
Co-authored-by: Cursor Agent &lt;cursoragent@cursor.com&gt;
diff --git a/packages/rc/src/index.ts b/packages/rc/src/index.ts
@@ -166,6 +166,29 @@ const getConfigFiles = (name: string, home: string, internalCwd: string, stopAt?
     return [...configFiles];
 };
 
+/**
+ * Aggregates configuration from multiple sources (defaults, configuration files, and environment variables)
+ * into a single object, following the same resolution logic as the original `rc` npm package.
+ *
+ * The resolution order is (highest precedence last):
+ * 1. `options.defaults` – default values supplied by the caller
+ * 2. Configuration files discovered by {@link getConfigFiles}
+ * 3. Environment variables that start with `${name}_` (nested via `__`)
+ *
+ * The function also returns the list of configuration file paths that were read while resolving the
+ * configuration. No mutation is performed on any of the discovered files – they are only read.
+ *
+ * @param {string} name               The base name of the application (used to derive env-var prefix and file names).
+ * @param {object} [options]          Optional behaviour switches.
+ * @param {string} [options.config]   Explicit path to a configuration file that should be merged last.
+ * @param {string} [options.cwd]      Working directory to start searching for local configuration files.
+ * @param {object} [options.defaults] Default configuration values that act as the lowest precedence.
+ * @param {string} [options.home]     Home directory to look for user-level configuration files. Defaults to the current user home directory.
+ * @param {string} [options.stopAt]   Absolute path that acts as a boundary when traversing up the directory tree.
+ *
+ * @returns {{ config: Record<string, any>, files: string[] }}
+ * An object containing the final merged `config` and the ordered list of `files` that were considered.
+ */
 // eslint-disable-next-line import/prefer-default-export
 export const rc = (
     name: string,
diff --git a/packages/semantic-release-clean-package-json/src/index.ts b/packages/semantic-release-clean-package-json/src/index.ts
@@ -9,7 +9,18 @@ import type { CommonContext, PublishContext } from "./definitions/context";
 import type { PluginConfig } from "./definitions/plugin-config";
 import getPackage from "./utils/get-pkg";
 
-// eslint-disable-next-line sonarjs/cognitive-complexity
+/**
+ * Clean the `package.json` that will be published by removing properties that are not relevant for the
+ * published artifact. All properties defined in `defaultKeepProperties` plus any properties provided
+ * via the `pluginConfig.keep` option are preserved. The original `package.json` is backed-up to
+ * `package.json.back` before the clean-up starts so that it can be restored later in the `success`
+ * step.
+ *
+ * @param {PluginConfig} pluginConfig Configuration object passed to the plugin.
+ * @param {PublishContext} context     Semantic-release publish context.
+ *
+ * @returns {Promise<void>} Resolves once the cleaned `package.json` has been written to disk.
+ */
 export const publish = async (pluginConfig: PluginConfig, context: PublishContext): Promise<void> => {
     const packageJson = await getPackage(pluginConfig, context);
     const cwd = pluginConfig.pkgRoot ? resolve(context.cwd, pluginConfig.pkgRoot) : context.cwd;
@@ -61,6 +72,16 @@ export const publish = async (pluginConfig: PluginConfig, context: PublishContex
     });
 };
 
+/**
+ * Restore the original `package.json` after a successful release. The backed-up version is read from
+ * `package.json.back`, its version is replaced with the version that was just released and finally it
+ * is written back to `package.json` (overwriting the temporary, cleaned version).
+ *
+ * @param {PluginConfig} pluginConfig Configuration object passed to the plugin.
+ * @param {CommonContext} context     Semantic-release success context.
+ *
+ * @returns {Promise<void>} Resolves once the original `package.json` has been restored.
+ */
 export const success = async (pluginConfig: PluginConfig, context: CommonContext): Promise<void> => {
     const cwd = pluginConfig.pkgRoot ? resolve(context.cwd, pluginConfig.pkgRoot) : context.cwd;
 
diff --git a/packages/semantic-release-clean-package-json/src/utils/get-error.ts b/packages/semantic-release-clean-package-json/src/utils/get-error.ts
@@ -3,6 +3,16 @@ import SemanticReleaseError from "@semantic-release/error";
 import type { ErrorContext, ErrorDefinition } from "../definitions/errors";
 import { errors } from "../definitions/errors";
 
+/**
+ * Create a typed {@link SemanticReleaseError} instance from the predefined error catalogue.
+ *
+ * @typeParam T - A key of the {@link errors} map.
+ *
+ * @param {T}          code     Error code referencing the entry inside {@link errors}.
+ * @param {ErrorContext} [context={}] Additional interpolation values used by the error factory.
+ *
+ * @returns {SemanticReleaseError} Fully initialised semantic-release error.
+ */
 export default <T extends keyof typeof errors>(code: T, context: ErrorContext = {}): SemanticReleaseError => {
     // eslint-disable-next-line security/detect-object-injection
     const { details, message }: { details?: string; message: string } = (errors[code] as ErrorDefinition)(context);
diff --git a/packages/semantic-release-clean-package-json/src/utils/get-pkg.ts b/packages/semantic-release-clean-package-json/src/utils/get-pkg.ts
@@ -8,6 +8,18 @@ import type { PackageJson } from "type-fest";
 import type { CommonContext } from "../definitions/context";
 import getError from "./get-error";
 
+/**
+ * Locate the closest `package.json` starting from the provided directory and return its parsed
+ * contents together with the absolute file path.
+ *
+ * @private
+ *
+ * @param {string | URL | undefined} [cwd] Directory to start searching in. When omitted the current
+ *        working directory is used.
+ *
+ * @returns {Promise<{packageJson: PackageJson; path: string}>} Resolves with the parsed JSON object
+ *          and its path or rejects with {@link NotFoundError} if no file could be found.
+ */
 const findPackageJson = async (
     cwd?: URL | string,
 ): Promise<{
@@ -34,6 +46,17 @@ const findPackageJson = async (
     };
 };
 
+/**
+ * Read and validate the `package.json` file for the current project (or a sub-path defined via
+ * `pkgRoot`). A semantic-release compatible {@link AggregateError} is thrown when either the file is
+ * missing or it does not contain a `name` field.
+ *
+ * @param {{ pkgRoot?: string }} options     Plugin options containing an optional `pkgRoot` that
+ *                                           points to the publish sub-directory.
+ * @param {{ cwd: string }}       context     Semantic-release context providing the base cwd.
+ *
+ * @returns {Promise<PackageJson>} The parsed package.json object.
+ */
 export default async (
     {
         pkgRoot,
diff --git a/packages/semantic-release-pnpm/src/add-channel.ts b/packages/semantic-release-pnpm/src/add-channel.ts
@@ -10,6 +10,20 @@ import type { ReleaseInfo } from "./utils/get-release-info";
 import { getReleaseInfo } from "./utils/get-release-info";
 import { reasonToNotPublish, shouldPublish } from "./utils/should-publish";
 
+/**
+ * After a successful publish this step adds the newly released version to another npm distribution
+ * tag (also known as a "channel") using `pnpm dist-tag add`.
+ *
+ * Typical use-case: publish a version on `next` first and, after manual verification, promote the
+ * same version to the `latest` channel in a follow-up release.
+ *
+ * @param {PluginConfig}     pluginConfig – Plugin configuration object.
+ * @param {PackageJson}      packageJson  – The package manifest that has just been published.
+ * @param {AddChannelContext} context      – Semantic-release addChannel context.
+ *
+ * @returns {Promise<ReleaseInfo | false>} A release info object when the dist-tag was added or
+ *                                        `false` when the operation was skipped.
+ */
 export default async (pluginConfig: PluginConfig, packageJson: PackageJson, context: AddChannelContext): Promise<ReleaseInfo | false> => {
     const {
         cwd,
diff --git a/packages/semantic-release-pnpm/src/definitions/constants.ts b/packages/semantic-release-pnpm/src/definitions/constants.ts
@@ -1,2 +1,8 @@
+/**
+ * Public npm registry used as default when no custom registry is configured via `package.json`,
+ * environment variables or `.npmrc`.
+ *
+ * @see https://registry.npmjs.org/
+ */
 // eslint-disable-next-line import/prefer-default-export
 export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
diff --git a/packages/semantic-release-pnpm/src/definitions/errors.ts b/packages/semantic-release-pnpm/src/definitions/errors.ts
@@ -1,5 +1,13 @@
 import packageJson from "../../package.json";
 
+/**
+ * Build an absolute URL to a file within the repository based on the `homepage` field of the plugin
+ * package.json (which points to the GitHub repository).
+ *
+ * @param {string} file – Relative path within the repository.
+ *
+ * @returns {string} GitHub URL to the requested file on the `main` branch.
+ */
 // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
 const linkify = (file: string) => packageJson.homepage + "/blob/main/" + file;
 
diff --git a/packages/semantic-release-pnpm/src/index.ts b/packages/semantic-release-pnpm/src/index.ts
@@ -12,6 +12,18 @@ const PLUGIN_NAME = "semantic-release-pnpm";
 let verified: boolean;
 let prepared: boolean;
 
+/**
+ * Verify that the environment and plugin configuration are ready for a semantic-release run. This
+ * step is executed during the `verifyConditions` phase.
+ *
+ * The function delegates the heavy lifting to the local `verify` helper and caches the verification
+ * result so that subsequent life-cycle steps can skip running the checks again.
+ *
+ * @param {PluginConfig}          pluginConfig Plugin configuration object.
+ * @param {VerifyConditionsContext} context     Semantic-release provided context.
+ *
+ * @returns {Promise<void>} Resolves once verification has finished.
+ */
 export const verifyConditions = async (pluginConfig: PluginConfig, context: VerifyConditionsContext): Promise<void> => {
     /**
      * If the plugin is used and has `npmPublish`, `tarballDir` or
@@ -40,6 +52,15 @@ export const verifyConditions = async (pluginConfig: PluginConfig, context: Veri
     verified = true;
 };
 
+/**
+ * Prepare the package for publication. On success the information is cached so that it is not
+ * executed again during `publish` when running the single-package plugin flow.
+ *
+ * @param {PluginConfig}     pluginConfig Plugin configuration object.
+ * @param {PrepareContext}   context      Semantic-release provided context.
+ *
+ * @returns {Promise<void>} Resolves when preparation steps have completed.
+ */
 export const prepare = async (pluginConfig: PluginConfig, context: PrepareContext): Promise<void> => {
     if (!verified) {
         await verify(pluginConfig, context);
@@ -50,6 +71,16 @@ export const prepare = async (pluginConfig: PluginConfig, context: PrepareContex
     prepared = true;
 };
 
+/**
+ * Publish the package to the npm registry using `pnpm publish` if the plugin decides that the package
+ * should indeed be published.
+ *
+ * @param {PluginConfig}    pluginConfig Plugin configuration object.
+ * @param {PublishContext}  context      Semantic-release provided context containing the upcoming release.
+ *
+ * @returns {Promise<ReleaseInfo | false>} Information about the published release or `false` when the
+ *                                        package was not published.
+ */
 export const publish = async (pluginConfig: PluginConfig, context: PublishContext): Promise<ReleaseInfo | false> => {
     const packageJson = await getPackage(pluginConfig, context);
 
@@ -64,6 +95,16 @@ export const publish = async (pluginConfig: PluginConfig, context: PublishContex
     return await publishNpm(pluginConfig, packageJson, context);
 };
 
+/**
+ * Add the freshly published version to an additional npm distribution tag ("channel"). This step is
+ * executed in the `addChannel` lifecycle phase.
+ *
+ * @param {PluginConfig}    pluginConfig Plugin configuration object.
+ * @param {AddChannelContext} context    Semantic-release provided context containing the upcoming release.
+ *
+ * @returns {Promise<ReleaseInfo | false>} Information about the operation or `false` when nothing was
+ *                                        done.
+ */
 export const addChannel = async (pluginConfig: PluginConfig, context: AddChannelContext): Promise<ReleaseInfo | false> => {
     if (!verified) {
         await verify(pluginConfig, context);
diff --git a/packages/semantic-release-pnpm/src/prepare.ts b/packages/semantic-release-pnpm/src/prepare.ts
@@ -5,6 +5,23 @@ import { execa } from "execa";
 import type { PrepareContext } from "./definitions/context";
 import type { PluginConfig } from "./definitions/plugin-config";
 
+/**
+ * Prepare the package for publishing by
+ * 1. writing the upcoming semantic-release version to the `package.json` with `pnpm version` (without
+ *    creating a git tag) and
+ * 2. optionally creating a tarball via `pnpm pack` which is moved to the configured `tarballDir`.
+ *
+ * The function mirrors the behaviour of the official semantic-release `@semantic-release/npm` plugin
+ * while using the `pnpm` CLI instead of `npm`.
+ *
+ * @param {PluginConfig}  pluginConfig – Plugin configuration. Only `pkgRoot` and `tarballDir` are
+ *                                       relevant for this function.
+ * @param {PrepareContext} context      – Semantic-release prepare context containing IO streams,
+ *                                       logger, environment variables and release information.
+ *
+ * @returns {Promise<void>} A promise that resolves once the version has been written and the optional
+ *                          tarball has been created (and moved).
+ */
 export default async ({ pkgRoot, tarballDir }: PluginConfig, { cwd, env, logger, nextRelease: { version }, stderr, stdout }: PrepareContext): Promise<void> => {
     const basePath = pkgRoot ? resolve(cwd, pkgRoot) : cwd;
 
diff --git a/packages/semantic-release-pnpm/src/publish.ts b/packages/semantic-release-pnpm/src/publish.ts
@@ -10,6 +10,23 @@ import type { ReleaseInfo } from "./utils/get-release-info";
 import { getReleaseInfo } from "./utils/get-release-info";
 import { reasonToNotPublish, shouldPublish } from "./utils/should-publish";
 
+/**
+ * Publish the package to the npm registry using `pnpm publish` when the plugin configuration and
+ * package manifest indicate that publishing should occur.
+ *
+ * The function calculates the correct distribution tag, resolves the registry URL, ensures the
+ * package manager operates in the correct `pkgRoot` (if any) and finally executes the `pnpm` CLI.
+ * It mirrors the behaviour of the official `@semantic-release/npm` plugin but utilises the `pnpm`
+ * ecosystem.
+ *
+ * @param {PluginConfig}   pluginConfig – Plugin configuration for the semantic-release run.
+ * @param {PackageJson}    packageJson  – Parsed `package.json` of the project.
+ * @param {PublishContext} context      – Semantic-release publish context.
+ *
+ * @returns {Promise<ReleaseInfo | false>} Information about the published release (name, channel,
+ *                                        url) or `false` if the package was not published for any
+ *                                        reason (e.g. `npmPublish: false`).
+ */
 export default async (pluginConfig: PluginConfig, packageJson: PackageJson, context: PublishContext): Promise<ReleaseInfo | false> => {
     const {
         cwd,
diff --git a/packages/semantic-release-pnpm/src/utils/get-channel.ts b/packages/semantic-release-pnpm/src/utils/get-channel.ts
@@ -1,3 +1,16 @@
 import { validRange } from "semver";
 
-export default (channel: string | null | undefined): string => (channel ? (validRange(channel) ? `release-${channel}` : channel) : "latest");
+/**
+ * Map a semantic-release `channel` value to the dist-tag that should be used when publishing to the
+ * npm registry.
+ *
+ * If the provided channel is a valid semver range (`1.x`, `2&#x2F;beta`, …) it will be prefixed with
+ * `release-` to avoid clashes with the default tags like `latest` or `next` (mirrors the behaviour of
+ * the official npm plugin). Otherwise the value is returned unchanged. When the channel is `null` or
+ * `undefined` the function returns the default tag `latest`.
+ *
+ * @param {string | null | undefined} channel – The channel coming from `context.nextRelease.channel`.
+ *
+ * @returns {string} The npm dist-tag that should be used for the publish operation.
+ */
+export default (channel: string | null | undefined): string => (channel ? (validRange(channel) ? `release-${channel}` : channel) : "latest");
diff --git a/packages/semantic-release-pnpm/src/utils/get-error.ts b/packages/semantic-release-pnpm/src/utils/get-error.ts
@@ -3,6 +3,18 @@ import SemanticReleaseError from "@semantic-release/error";
 import type { ErrorContext, ErrorDefinition } from "../definitions/errors";
 import { errors } from "../definitions/errors";
 
+/**
+ * Return a {@link SemanticReleaseError} instance pre-configured with message and details from the
+ * plugin's error catalogue. This helper guarantees type-safety by ensuring that `code` is one of the
+ * known keys.
+ *
+ * @typeParam T – One of the keys from the internal {@link errors} map.
+ *
+ * @param {T}               code     – Error code referencing a predefined error factory.
+ * @param {ErrorContext}    [context={}] – Optional values injected into the error message template.
+ *
+ * @returns {SemanticReleaseError} Fully initialised semantic-release error instance.
+ */
 export default <T extends keyof typeof errors>(code: T, context: ErrorContext = {}): SemanticReleaseError => {
     // eslint-disable-next-line security/detect-object-injection
     const { details, message }: { details?: string; message: string } = (errors[code] as ErrorDefinition)(context);
diff --git a/packages/semantic-release-pnpm/src/utils/get-npmrc-path.ts b/packages/semantic-release-pnpm/src/utils/get-npmrc-path.ts
@@ -1,6 +1,22 @@
 import { ensureFileSync, isAccessibleSync } from "@visulima/fs";
 import { resolve } from "@visulima/path";
 
+/**
+ * Determine the path to the `.npmrc` file that should be used for authentication and configuration
+ * during the publish process.
+ *
+ * The resolution logic is:
+ * 1. When the environment variable `NPM_CONFIG_USERCONFIG` is set **and** points to an existing
+ *    file, that path wins (it allows CI systems to inject custom npmrc files).
+ * 2. When a `.npmrc` exists in the provided `cwd`, return that path.
+ * 3. Otherwise create an empty `.npmrc` file inside `cwd` (so later steps can write credentials) and
+ *    return the newly created path.
+ *
+ * @param {string} cwd                     – Working directory from which to derive the default path.
+ * @param {NodeJS.ProcessEnv} environment  – Environment variables (typically `context.env`).
+ *
+ * @returns {string} Absolute path to the `.npmrc` file that should be used/written.
+ */
 const getNpmrcPath = (cwd: string, environment: NodeJS.ProcessEnv): string => {
     const npmrcPath = resolve(cwd, ".npmrc");
 
diff --git a/packages/semantic-release-pnpm/src/utils/get-pkg.ts b/packages/semantic-release-pnpm/src/utils/get-pkg.ts
@@ -10,6 +10,16 @@ interface Options {
     pkgRoot?: string;
 }
 
+/**
+ * Locate and read the `package.json` for the current project (or the sub-directory specified by
+ * `pkgRoot`). Ensures that the manifest contains a `name` field and throws semantic-release style
+ * errors otherwise (for better aggregation in the caller).
+ *
+ * @param {{ pkgRoot?: string }} options  – Options object containing an optional `pkgRoot` path.
+ * @param {{ cwd: string }}       context  – Semantic-release context limited to the `cwd` property.
+ *
+ * @returns {Promise<PackageJson>} The parsed `package.json` object.
+ */
 export default async ({ pkgRoot }: Options, { cwd }: { cwd: CommonContext["cwd"] }): Promise<PackageJson> => {
     try {
         const { packageJson } = await findPackageJson(pkgRoot ? resolve(cwd, pkgRoot) : cwd);
diff --git a/packages/semantic-release-pnpm/src/utils/get-registry.ts b/packages/semantic-release-pnpm/src/utils/get-registry.ts
@@ -6,6 +6,15 @@ import type { AuthOptions } from "registry-auth-token";
 import { DEFAULT_NPM_REGISTRY } from "../definitions/constants";
 import type { CommonContext } from "../definitions/context";
 
+/**
+ * Derive the registry URL for a given npm scope from a parsed npm configuration object (`npmrc`).
+ * Falls back to {@link DEFAULT_NPM_REGISTRY} when no registry is configured.
+ *
+ * @param {string}                   scope  – The npm scope (e.g., `@my-org`).
+ * @param {AuthOptions["npmrc"]} npmrc – Parsed npm configuration returned by `rc`.
+ *
+ * @returns {string} A registry URL guaranteed to end with a trailing slash.
+ */
 const getRegistryUrl = (scope: string, npmrc: AuthOptions["npmrc"]): string => {
     let url: string = DEFAULT_NPM_REGISTRY;
 
@@ -20,6 +29,18 @@ const getRegistryUrl = (scope: string, npmrc: AuthOptions["npmrc"]): string => {
     return url.endsWith("/") ? url : `${url}/`;
 };
 
+/**
+ * Resolve the registry that should be used for publishing a package. The resolution order is:
+ * 1. `package.json#publishConfig.registry`
+ * 2. `process.env.NPM_CONFIG_REGISTRY`
+ * 3. registry derived from the local (or user supplied) `.npmrc` file
+ * 4. {@link DEFAULT_NPM_REGISTRY}
+ *
+ * @param {PackageJson}      pkg     – The package manifest whose registry is to be determined.
+ * @param {CommonContext}    context – Semantic-release execution context.
+ *
+ * @returns {string} The registry URL (always trailing slash suffixed).
+ */
 export default ({ name, publishConfig: { registry } = {} }: PackageJson, { cwd, env }: CommonContext): string =>
     registry ??
     env.NPM_CONFIG_REGISTRY ??
diff --git a/packages/semantic-release-pnpm/src/utils/get-release-info.ts b/packages/semantic-release-pnpm/src/utils/get-release-info.ts
diff --git a/packages/semantic-release-pnpm/src/utils/set-npmrc-auth.ts b/packages/semantic-release-pnpm/src/utils/set-npmrc-auth.ts
diff --git a/packages/semantic-release-pnpm/src/utils/should-publish.ts b/packages/semantic-release-pnpm/src/utils/should-publish.ts
diff --git a/packages/semantic-release-pnpm/src/verify/index.ts b/packages/semantic-release-pnpm/src/verify/index.ts
diff --git a/packages/semantic-release-pnpm/src/verify/verify-auth.ts b/packages/semantic-release-pnpm/src/verify/verify-auth.ts
diff --git a/packages/semantic-release-pnpm/src/verify/verify-config.ts b/packages/semantic-release-pnpm/src/verify/verify-config.ts
diff --git a/packages/semantic-release-pnpm/src/verify/verify-pnpm.ts b/packages/semantic-release-pnpm/src/verify/verify-pnpm.ts
