semantic-release 21.0.9 → 21.1.1

package/docs/recipes/ci-configurations/gitlab-ci.md

@@ -6,6 +6,11 @@ The [Authentication](../../usage/ci-configuration.md#authentication) environment
 
 **Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables.
 
+## npm provenance
+
+Since GitLab CI is a [supported provider](https://docs.npmjs.com/generating-provenance-statements#provenance-limitations) for [npm provenance](https://docs.npmjs.com/generating-provenance-statements), it is recommended to enable this to increase supply-chain security for your npm packages.
+Find more detail about configuring npm to publish with provenance through semantic-release [in the documentation for our npm plugin](https://github.com/semantic-release/npm#npm-provenance).
+
 ## Node project configuration
 
 GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.

package/index.d.ts

@@ -0,0 +1,711 @@
+declare interface AggregateError extends Error {
+  errors: any[];
+}
+
+declare module "semantic-release" {
+  import { Signale } from "signale";
+  export interface EnvCi {
+    /**
+     * Boolean, true if the environment is a CI environment
+     */
+    isCi: boolean;
+
+    /**
+     * Commit hash
+     */
+    commit: string;
+
+    /**
+     * Current branch name
+     */
+    branch: string;
+  }
+
+  /**
+   * Base context used in every semantic release step.
+   */
+  export interface BaseContext {
+    /**
+     * stdout for semantic-release process
+     */
+    stdout: NodeJS.WriteStream;
+
+    /**
+     * stderr for semantic-release process
+     */
+    stderr: NodeJS.WriteStream;
+
+    /**
+     * Signale console loger instance.
+     *
+     * Has error, log and success methods.
+     */
+    logger: Signale<"error" | "log" | "success">;
+  }
+
+  /**
+   * Context used for the verify conditions step.
+   */
+  export interface VerifyConditionsContext extends BaseContext {
+    /**
+     * The current working directory to use. It should be configured to
+     * the root of the Git repository to release from.
+     *
+     * It allows to run semantic-release from a specific path without
+     * having to change the local process cwd with process.chdir().
+     *
+     * @default process.cwd
+     */
+    cwd?: string | undefined;
+
+    /**
+     * The environment variables to use.
+     *
+     * It allows to run semantic-release with specific environment
+     * variables without having to modify the local process.env.
+     *
+     * @default process.env
+     */
+    env: Record<string, string>;
+
+    /**
+     * Information about the CI environment.
+     */
+    envCi: EnvCi;
+
+    /**
+     * Information of the current branch
+     */
+    branch: BranchObject;
+
+    /**
+     * Information on branches
+     */
+    branches: ReadonlyArray<BranchObject>;
+  }
+
+  /**
+   * Context used for the analyze commits step.
+   */
+  export interface AnalyzeCommitsContext extends VerifyConditionsContext {
+    /**
+     * List of commits taken into account when determining the new version.
+     */
+    commits: ReadonlyArray<Commit>;
+
+    /**
+     * List of releases
+     */
+    releases: ReadonlyArray<Release>;
+
+    /**
+     * Last release
+     */
+    lastRelease: LastRelease;
+  }
+
+  /**
+   * Context used for the verify release step.
+   */
+  export interface VerifyReleaseContext extends AnalyzeCommitsContext {
+    /**
+     * The next release.
+     */
+    nextRelease: NextRelease;
+  }
+
+  /**
+   * Context used for the generate notes step.
+   */
+  export type GenerateNotesContext = VerifyReleaseContext;
+
+  /**
+   * Context used for the add channel step.
+   */
+  export type AddChannelContext = VerifyReleaseContext;
+
+  /**
+   * Context used for the prepare step.
+   */
+  export type PrepareContext = VerifyReleaseContext;
+
+  /**
+   * Context used for the publish step.
+   */
+  export type PublishContext = VerifyReleaseContext;
+
+  /**
+   * Context used for the success step.
+   */
+  export type SuccessContext = VerifyReleaseContext;
+
+  export interface FailContext extends BaseContext {
+    /**
+     * Errors that occurred during the release process.
+     */
+    errors: AggregateError;
+  }
+
+  export interface Commit {
+    /**
+     * The commit abbreviated and full hash.
+     */
+    commit: {
+      /**
+       * The commit hash.
+       */
+      long: string;
+
+      /**
+       * The commit abbreviated hash.
+       */
+      short: string;
+    };
+
+    /**
+     * The commit abbreviated and full tree hash.
+     */
+    tree: {
+      /**
+       * The commit tree hash.
+       */
+      long: string;
+
+      /**
+       * The commit abbreviated tree hash.
+       */
+      short: string;
+    };
+
+    /**
+     * The commit author information.
+     */
+    author: {
+      /**
+       * The commit author name.
+       */
+      name: string;
+
+      /**
+       * The commit author email.
+       */
+      email: string;
+
+      /**
+       * The commit author date.
+       */
+      short: string;
+    };
+
+    /**
+     * The committer information.
+     */
+    committer: {
+      /**
+       * The committer name.
+       */
+      name: string;
+
+      /**
+       * The committer email.
+       */
+      email: string;
+
+      /**
+       * The committer date.
+       */
+      short: string;
+    };
+
+    /**
+     * The commit subject.
+     */
+    subject: string;
+
+    /**
+     * The commit body.
+     */
+    body: string;
+
+    /**
+     * The commit full message (subject and body).
+     */
+    message: string;
+
+    /**
+     * The commit hash.
+     */
+    hash: string;
+
+    /**
+     * The committer date.
+     */
+    committerDate: string;
+  }
+
+  export interface BranchObject {
+    /**
+     * The name of git branch.
+     *
+     * A `name` is required for all types of branch. It can be defined as a
+     * [glob](https://github.com/micromatch/micromatch#matching-features)
+     * in which case the definition will be expanded to one per matching
+     * branch existing in the repository.
+     *
+     * If `name` doesn't match any branch existing in the repository, the
+     * definition will be ignored. For example, the default configuration
+     * includes the definition `next` and `next-major` which will become
+     * active only  when the branches `next` and/or `next-major` are
+     * created in the repository.
+     */
+    name: string;
+
+    /**
+     * The distribution channel on which to publish releases from this
+     * branch.
+     *
+     * If this field is set to `false`, then the branch will be released
+     * on the default distribution channel (for example the `@latest`
+     * [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm). This is
+     * also the default behavior for the first
+     * [release branch](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#release-branches)
+     * if the channel property is not set.
+     *
+     * For all other branches, if the channel property is not set, then the
+     * channel name will be the same as the branch name.
+     *
+     * The value of `channel`, if defined as a string, is generated with
+     * [Lodash template](https://lodash.com/docs#template) with the
+     * variable `name` set to the branch name.
+     *
+     * For example `{name: 'next', channel: 'channel-${name}'}` will be
+     * expanded to `{name: 'next', channel: 'channel-next'}`.
+     */
+    channel?: string | false | undefined;
+
+    /**
+     * The range of [semantic versions](https://semver.org/) to support on
+     * this branch.
+     *
+     * A `range` only applies to maintenance branches and must be formatted
+     * like `N.N.x` or `N.x` (`N` is a number). If no range is specified
+     * but the `name` is formatted as a range, then the branch will be
+     * considered a maintenance branch and the `name` value will be used
+     * for the `range`.
+     *
+     * Required for maintenance branches, unless `name` is formatted like
+     * `N.N.x` or `N.x` (`N` is a number).
+     */
+    range?: string | undefined;
+
+    /**
+     * The pre-release identifier to append to [semantic versions](https://semver.org/)
+     * released from this branch.
+     *
+     * A `prerelease` property applies only to pre-release branches and
+     * the `prerelease` value must be valid per the [Semantic Versioning
+     * Specification](https://semver.org/#spec-item-9). It will determine
+     * the name of versions. For example if `prerelease` is set to
+     * `"beta"`, the version will be formatted like `2.0.0-beta.1`,
+     * `2.0.0-beta.2`, etc.
+     *
+     * The value of `prerelease`, if defined as a string, is generated with
+     * [Lodash template](https://lodash.com/docs#template) with the
+     * variable `name` set to the name of the branch.
+     *
+     * If the `prerelease property is set to `true` then the name of the
+     * branch is used as the pre-release identifier.
+     *
+     * Required for pre-release branches.
+     */
+    prerelease?: string | boolean | undefined;
+  }
+
+  /**
+   * Specifies a git branch holding commits to analyze and code to release.
+   *
+   * Each branch may be defined either by a string or an object. Specifying
+   * a string is a shortcut for specifying that string as the `name` field,
+   * for example `"master"` expands to `{name: "master"}`.
+   */
+  export type BranchSpec = string | BranchObject;
+
+  /**
+   * A semver release type.
+   * See https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-types.js
+   */
+  export type ReleaseType = "prerelease" | "prepatch" | "patch" | "preminor" | "minor" | "premajor" | "major";
+
+  /**
+   * Details of a release published by a publish plugin.
+   */
+  export interface Release {
+    /**
+     * The release name, only if set by the corresponding publish plugin.
+     */
+    name?: string | undefined;
+
+    /**
+     * The release URL, only if set by the corresponding publish plugin.
+     */
+    url?: string | undefined;
+
+    /**
+     * The semver export type of the release.
+     */
+    type: ReleaseType;
+
+    /**
+     * The version of the release.
+     */
+    version: string;
+
+    /**
+     * The sha of the last commit being part of the release.
+     */
+    gitHead: string;
+
+    /**
+     * The Git tag associated with the release.
+     */
+    gitTag: string;
+
+    /**
+     * The release notes for the release.
+     */
+    notes: string;
+
+    /**
+     * The name of the plugin that published the release.
+     */
+    pluginName: string;
+  }
+
+  export interface LastRelease {
+    /**
+     * The version name of the release.
+     */
+    version: string;
+
+    /**
+     * The Git tag of the release.
+     */
+    gitTag: string;
+
+    /**
+     * List of channels the release was published to.
+     */
+    channels: string[];
+
+    /**
+     * The Git checksum of the last commit of the release.
+     */
+    gitHead: string;
+
+    /**
+     * The Release name
+     */
+    name: string;
+  }
+
+  export interface NextRelease extends Omit<LastRelease, "channels"> {
+    /**
+     * The semver export type of the release.
+     */
+    type: ReleaseType;
+
+    /**
+     * The release channel of the release.
+     */
+    channel: string;
+
+    /**
+     * The release notes of the next release.
+     */
+    notes?: string | undefined;
+  }
+
+  /**
+   * Specifies a plugin to use.
+   *
+   * The plugin is specified by its module name.
+   *
+   * To pass options to a plugin, specify an array containing the plugin module
+   * name and an options object.
+   */
+  export type PluginSpec<T = any> = string | [string, T];
+
+  /**
+   * semantic-release options, after normalization and defaults have been
+   * applied.
+   */
+  export interface GlobalConfig extends Options {
+    /**
+     * The branches on which releases should happen. By default
+     * **semantic-release** will release:
+     *
+     *  * regular releases to the default distribution channel from the
+     *    branch `master`
+     *  * regular releases to a distribution channel matching the branch
+     *    name from any existing branch with a name matching a maintenance
+     *    release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a
+     *    number)
+     *  * regular releases to the `next` distribution channel from the
+     *    branch `next` if it exists
+     *  * regular releases to the `next-major` distribution channel from
+     *    the branch `next-major` if it exists.
+     *  * prereleases to the `beta` distribution channel from the branch
+     *    `beta` if it exists
+     *  * prereleases to the `alpha` distribution channel from the branch
+     *    `alpha` if it exists
+     *
+     * **Note**: If your repository does not have a release branch, then
+     * **semantic-release** will fail with an `ERELEASEBRANCHES` error
+     * message. If you are using the default configuration, you can fix
+     * this error by pushing a `master` branch.
+     *
+     * **Note**: Once **semantic-release** is configured, any user with the
+     * permission to push commits on one of those branches will be able to
+     * publish a release. It is recommended to protect those branches, for
+     * example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches).
+     *
+     * See [Workflow configuration](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#workflow-configuration)
+     * for more details.
+     */
+    branches: ReadonlyArray<BranchSpec> | BranchSpec;
+
+    /**
+     * The git repository URL.
+     *
+     * Any valid git url format is supported (see
+     * [git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols))
+     *
+     * Default: `repository` property in `package.json`, or git origin url.
+     */
+    repositoryUrl: string;
+
+    /**
+     * The git tag format used by **semantic-release** to identify
+     * releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template)
+     * and will be compiled with the `version` variable.
+     *
+     * **Note**: The `tagFormat` must contain the `version` variable
+     * exactly once and compile to a
+     * [valid git reference](https://git-scm.com/docs/git-check-ref-format#_description).
+     */
+    tagFormat: string;
+
+    /**
+     * Define the list of plugins to use. Plugins will run in series, in
+     * the order defined, for each [step](https://semantic-release.gitbook.io/semantic-release/#release-steps)
+     * if they implement it.
+     *
+     * Plugins configuration can be defined by wrapping the name and an
+     * options object in an array.
+     *
+     * See [Plugins configuration](https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugins)
+     * for more details.
+     *
+     * Default: `[
+     *     "@semantic-release/commit-analyzer",
+     *     "@semantic-release/release-notes-generator",
+     *     "@semantic-release/npm",
+     *     "@semantic-release/github"
+     * ]`
+     */
+    plugins: ReadonlyArray<PluginSpec>;
+  }
+
+  /** semantic-release configuration specific for API usage. */
+  export interface Config {
+    /**
+     * The current working directory to use. It should be configured to
+     * the root of the Git repository to release from.
+     *
+     * It allows to run semantic-release from a specific path without
+     * having to change the local process cwd with process.chdir().
+     *
+     * @default process.cwd
+     */
+    cwd?: string | undefined;
+
+    /**
+     * The environment variables to use.
+     *
+     * It allows to run semantic-release with specific environment
+     * variables without having to modify the local process.env.
+     *
+     * @default process.env
+     */
+    env?: Record<string, any> | undefined;
+
+    /**
+     * The writable stream used to log information.
+     *
+     * It allows to configure semantic-release to write logs to a specific
+     * stream rather than the local process.stdout.
+     *
+     * @default process.stdout
+     */
+    stdout?: NodeJS.WriteStream | undefined;
+
+    /**
+     * The writable stream used to log errors.
+     *
+     * It allows to configure semantic-release to write errors to a
+     * specific stream rather than the local process.stderr.
+     *
+     * @default process.stderr
+     */
+    stderr?: NodeJS.WriteStream | undefined;
+  }
+
+  /**
+   * semantic-release options.
+   *
+   * Can be used to set any core option or plugin options.
+   * Each option will take precedence over options configured in the
+   * configuration file and shareable configurations.
+   */
+  export interface Options {
+    /**
+     * List of modules or file paths containing a
+     * [shareable configuration](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations).
+     * If multiple shareable configurations are set, they will be imported
+     * in the order defined with each configuration option taking
+     * precedence over the options defined in a previous shareable
+     * configuration.
+     *
+     * **Note**: Options defined via CLI arguments or in the configuration
+     * file will take precedence over the ones defined in any shareable
+     * configuration.
+     */
+    extends?: ReadonlyArray<string> | string | undefined;
+
+    /**
+     * The branches on which releases should happen. By default
+     * **semantic-release** will release:
+     *
+     *  * regular releases to the default distribution channel from the
+     *    branch `master`
+     *  * regular releases to a distribution channel matching the branch
+     *    name from any existing branch with a name matching a maintenance
+     *    release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a
+     *    number)
+     *  * regular releases to the `next` distribution channel from the
+     *    branch `next` if it exists
+     *  * regular releases to the `next-major` distribution channel from
+     *    the branch `next-major` if it exists.
+     *  * prereleases to the `beta` distribution channel from the branch
+     *    `beta` if it exists
+     *  * prereleases to the `alpha` distribution channel from the branch
+     *    `alpha` if it exists
+     *
+     * **Note**: If your repository does not have a release branch, then
+     * **semantic-release** will fail with an `ERELEASEBRANCHES` error
+     * message. If you are using the default configuration, you can fix
+     * this error by pushing a `master` branch.
+     *
+     * **Note**: Once **semantic-release** is configured, any user with the
+     * permission to push commits on one of those branches will be able to
+     * publish a release. It is recommended to protect those branches, for
+     * example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches).
+     *
+     * See [Workflow configuration](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#workflow-configuration)
+     * for more details.
+     */
+    branches?: ReadonlyArray<BranchSpec> | BranchSpec | undefined;
+
+    /**
+     * The git repository URL.
+     *
+     * Any valid git url format is supported (see
+     * [git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols))
+     *
+     * Default: `repository` property in `package.json`, or git origin url.
+     */
+    repositoryUrl?: string | undefined;
+
+    /**
+     * The git tag format used by **semantic-release** to identify
+     * releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template)
+     * and will be compiled with the `version` variable.
+     *
+     * **Note**: The `tagFormat` must contain the `version` variable
+     * exactly once and compile to a
+     * [valid git reference](https://git-scm.com/docs/git-check-ref-format#_description).
+     */
+    tagFormat?: string | undefined;
+
+    /**
+     * Define the list of plugins to use. Plugins will run in series, in
+     * the order defined, for each [step](https://semantic-release.gitbook.io/semantic-release/#release-steps)
+     * if they implement it.
+     *
+     * Plugins configuration can be defined by wrapping the name and an
+     * options object in an array.
+     *
+     * See [Plugins configuration](https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugins)
+     * for more details.
+     *
+     * Default: `[
+     *     "@semantic-release/commit-analyzer",
+     *     "@semantic-release/release-notes-generator",
+     *     "@semantic-release/npm",
+     *     "@semantic-release/github"
+     * ]`
+     */
+    plugins?: ReadonlyArray<PluginSpec> | undefined;
+
+    /**
+     * Dry-run mode, skip publishing, print next version and release notes.
+     */
+    dryRun?: boolean | undefined;
+
+    /**
+     * Set to false to skip Continuous Integration environment verifications.
+     * This allows for making releases from a local machine.
+     */
+    ci?: boolean | undefined;
+
+    /**
+     * Any other options supported by plugins.
+     */
+    [name: string]: any;
+  }
+
+  /**
+   * An object with details of the release if a release was published, or
+   * false if no release was published.
+   */
+  export type Result =
+    | false
+    | {
+        /**
+         * Information related to the last release found.
+         */
+        lastRelease: LastRelease;
+
+        /**
+         * The list of commits included in the new release.
+         */
+        commits: Commit[];
+
+        /**
+         * Information related to the newly published release.
+         */
+        nextRelease: NextRelease;
+
+        /**
+         * The list of releases published, one release per publish plugin.
+         */
+        releases: Release[];
+      };
+
+  /**
+   * Run semantic-release and returns a Promise that resolves to a Result
+   * object.
+   * @async
+   */
+  export default function (options: Options, environment?: Config): Promise<Result>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "semantic-release",
   "description": "Automated semver compliant package publishing",
-  "version": "21.0.9",
+  "version": "21.1.1",
   "type": "module",
   "author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
   "ava": {
@@ -81,6 +81,7 @@
     "bin",
     "docs",
     "lib",
+    "index.d.ts",
     "index.js",
     "cli.js"
   ],
@@ -98,6 +99,7 @@
   ],
   "license": "MIT",
   "main": "index.js",
+  "types": "index.d.ts",
   "c8": {
     "include": [
       "lib/**/*.js",