@halospv3/hce.shared-config 3.0.0-develop.2 → 3.0.0-develop.21

package/mjs/semanticReleaseConfigDotnet.mjs

@@ -0,0 +1,268 @@
+import { inspect } from 'node:util';
+import _debug from './debug.mjs';
+import { configurePrepareCmd, configureDotnetNugetPush } from './dotnet/helpers.mjs';
+import { getEnvVarValue } from './utils/env.mjs';
+import { baseConfig } from './semanticReleaseConfig.mjs';
+import { NugetRegistryInfo } from './dotnet/NugetRegistryInfo.mjs';
+import { MSBuildProject } from './dotnet/MSBuildProject.mjs';
+import { insertPlugin } from './insertPlugins.mjs';
+
+/**
+ * # Semantic-Release Config Factory (dotnet)
+ * A functional Semantic-Release configuration for dotnet projects
+ *
+ * extends {@link baseConfig }
+ *
+ * <-- TABLE OF CONTENTS -->
+ * - configureDotnetRelease
+ * - Insert-Edit Plugins
+ * - Append Plugins
+ *
+ */
+
+/**
+ */
+class SemanticReleaseConfigDotnet {
+  options;
+  _projectsToPublish;
+  _projectsToPackAndPush;
+  _evaluatedProjects;
+
+  /**
+   * Creates an instance of SemanticReleaseConfigDotnet.
+   * Configures {@link baseConfig} with `@semantic-release/exec` to `dotnet` publish, pack, and push.
+   *
+   * Note: To sign packages, create a Target in the corresponding project(s) e.g.
+   * ```xml
+   * <Target Name="SignNupkgs" AfterTargets="Pack">
+   *   <Exec Command="dotnet nuget sign $(PackageOutputPath) [remaining args]" ConsoleToMsBuild="true" />
+   * </Target>
+   * ```
+   * Alternatively, splice your signing commands into the publishCmd string,
+   * inserting them before `dotnet nuget push`.
+   * If you sign different signatures depending on the NuGet registry,
+   * splice your signing command (with "overwrite signature" enabled, if
+   * desired) before the corresponding registry's `dotnet nuget push` command.
+   * @param projectsToPublish An array of dotnet projects' relative paths. If
+   * empty or unspecified, tries getting projects' semi-colon-separated relative
+   * paths from the `PROJECTS_TO_PUBLISH` environment variable. If configured as
+   * recommended, the projects' publish outputs will be zipped to '$PWD/publish'
+   * for use in the `publish` semantic-release step (typically, GitHub release).
+   * @param projectsToPackAndPush An array of dotnet projects' relative paths.
+   * If empty or unspecified, tries getting projects' semi-colon-separated
+   * relative paths from the `PROJECTS_TO_PACK_AND_PUSH` environment variable.
+   * Otherwise, no packages will be packed and pushed.
+   * If configured as recommended, `dotnet pack` will output the nupkg/snupkg
+   * files to `$PWD/publish` where they will be globbed by `dotnet nuget push`.
+   */
+  constructor(projectsToPublish, projectsToPackAndPush) {
+    this.options = baseConfig;
+    /* normalize PluginSpecs to tuples */
+    this.options.plugins = this.options.plugins.map(pluginSpec => typeof pluginSpec === 'string' ? [pluginSpec, {}] : pluginSpec);
+    this._projectsToPublish = projectsToPublish;
+    if (this._projectsToPublish.length === 0) {
+      const p = getEnvVarValue('PROJECTS_TO_PUBLISH')?.split(';');
+      if (p && p.length > 0) {
+        this._projectsToPublish = p;
+      } else if (_debug.enabled) {
+        _debug(new Error('At least one project must be published. `projectsToPackAndPush` is empty and environment variable `PROJECTS_TO_PUBLISH` is undefined or empty.'));
+      }
+    }
+    this._projectsToPackAndPush = projectsToPackAndPush;
+    if (this._projectsToPackAndPush.length === 0) {
+      const p = getEnvVarValue('PROJECTS_TO_PACK_AND_PUSH')?.split(';');
+      if (p && p.length > 0) {
+        this._projectsToPackAndPush = p;
+      } else if (_debug.enabled) {
+        _debug(new Error('projectsToPackAndPush.length must be > 0 or PROJECTS_TO_PACK_AND_PUSH must be defined and contain at least one path.'));
+      }
+    }
+
+    // may be zero-length array
+    this._evaluatedProjects = [...this._projectsToPublish.filter(v => v instanceof MSBuildProject), ...this._projectsToPackAndPush.filter(v => v instanceof NugetRegistryInfo).map(v => v.project)];
+  }
+  get ProjectsToPublish() {
+    return this._projectsToPublish;
+  }
+  get ProjectsToPackAndPush() {
+    return this._projectsToPackAndPush;
+  }
+  get EvaluatedProjects() {
+    return this._evaluatedProjects;
+  }
+  insertPlugin(afterPluginsIDs, insertPluginIDs, beforePluginsIDs) {
+    this.options.plugins = insertPlugin(this.options.plugins, afterPluginsIDs, insertPluginIDs, beforePluginsIDs);
+  }
+
+  /**
+   * generate dotnet commands for \@semantic-release/exec, appending commands with ' && ' when necessary.
+   *
+   * Note: All strings in {@link this.ProjectsToPackAndPush} will be converted to basic {@link NugetRegistryInfo} instances with default values.
+   * If you need specific NRI settings or you need to push to GitLab-like or GitHub-like registries, instantiate them instead of passing their paths.
+   * @todo change to builder method? e.g. static async SetupDotnetCommands(this: SemanticReleaseConfigDotnet): Promise<SemanticReleaseConfigDotnet>
+   * @todo Add options param to allow users to enable pushing to GitLab, GitHub, NuGet.org with default settings -OR- with entirely custom settings.
+   * @see https://github.com/semantic-release/exec#usage
+   */
+  async setupDotnetCommands() {
+    let srExecIndex = this.options.plugins.findIndex(v => v[0] === '@semantic-release/exec');
+    if (srExecIndex === -1) {
+      const message = `\
+Unable to find\`['@semantic-release/exec', unknown]\` in plugins array!
+Appending it to the end of the array...This may cause an unexpected order of operations!`;
+      console.warn(message);
+      srExecIndex = this.options.plugins.push(['@semantic-release/exec', {}]) - 1;
+    }
+    const execOptions = this.options.plugins[srExecIndex];
+
+    // ensure all packable projects are evaluated
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    this._projectsToPackAndPush = await Promise.all(this._projectsToPackAndPush.map(async project => {
+      if (typeof project === 'string') {
+        const packableProjects = await Promise.all(await MSBuildProject.PackableProjectsToMSBuildProjects([project]));
+        if (packableProjects.length === 0) throw new Error('No MSBuildProject instances were returned!');
+        this._evaluatedProjects.push(...packableProjects);
+
+        // if the user doesn't want a defaulted NRI, they should pass their own NRI (or derived) instance.
+        return packableProjects.map(project => new NugetRegistryInfo({
+          project
+        }));
+      } else return [project];
+    })).then(p => p.flat());
+
+    // todo: double-check token-testing commands. Are they formatted prepended correctly?
+    const verifyConditionsCmdAppendix = await Promise.all(this._projectsToPackAndPush.map(async project => await project.PackDummyPackage({}).then(() => project.GetPushDummyCommand({})))).then(cmds => cmds.join(' && '));
+    execOptions.verifyConditionsCmd = execOptions.verifyConditionsCmd && execOptions.verifyConditionsCmd.trim().length > 0 ? `${execOptions.verifyConditionsCmd} && ${verifyConditionsCmdAppendix}` : verifyConditionsCmdAppendix;
+    const verifyReleaseCmdAppendix = await Promise.all(this.ProjectsToPackAndPush.filter(project => typeof project !== 'string').map(project => project.GetIsNextVersionAlreadyPublishedCommand())).then(cmds => cmds.join(' && '));
+    execOptions.verifyReleaseCmd = execOptions.verifyReleaseCmd && execOptions.verifyReleaseCmd.trim().length > 0 ? `${execOptions.verifyReleaseCmd} && ${verifyReleaseCmdAppendix}` : verifyConditionsCmdAppendix;
+    const prepareCmdAppendix = await configurePrepareCmd(this._projectsToPublish, this._projectsToPackAndPush);
+
+    // 'ZipPublishDir' zips each publish folder to ./publish/*.zip
+    execOptions.prepareCmd = execOptions.prepareCmd && execOptions.prepareCmd.trim().length > 0 ? `${execOptions.prepareCmd} && ${prepareCmdAppendix}` : prepareCmdAppendix;
+
+    // FINISHED execOptions.prepareCmd
+    // STARTING execOptions.publishCmd
+    if (this._projectsToPackAndPush.length > 0) {
+      const publishCmdAppendix = configureDotnetNugetPush(this._projectsToPackAndPush);
+      execOptions.publishCmd = execOptions.publishCmd && execOptions.publishCmd.trim().length > 0 ? `${execOptions.publishCmd} && ${publishCmdAppendix}` : publishCmdAppendix;
+    }
+
+    // FINISHED execOptions.publishCmd
+  }
+
+  /**
+   * Insert a plugin into the plugins array.
+   * @deprecated EXPERIMENTAL: needs thorough tests implemented before use in production!
+   * @param insertAfterPluginIDs Plugins which should appear BEFORE
+   * {@link insertPluginIDs}.
+   * @param insertPluginIDs The plugin(s) to insert into the plugins array.
+   * @param insertBeforePluginsIDs plugins which should appear AFTER the
+   * inserted plugin(s).
+   */
+  splicePlugin(insertAfterPluginIDs, insertPluginIDs, insertBeforePluginsIDs) {
+    const errors = [];
+    const pluginIDs = this.options.plugins.map(v => typeof v === 'string' ? v : v[0]);
+
+    // if any beforePluginIDs are ordered before the last afterPlugin, throw. Impossible to sort.
+
+    const indexOfLastPreceding = insertAfterPluginIDs.filter(v => pluginIDs.includes(v)).map(v => pluginIDs.indexOf(v)).sort().find((_v, i, obj) => i === obj.length - 1);
+    if (!indexOfLastPreceding) throw new ReferenceError('An attempt to get the last element of indexOfLastAfter returned undefined.');
+    const indicesOfBefore = insertBeforePluginsIDs.filter(v => pluginIDs.includes(v)).map(v => pluginIDs.indexOf(v)).sort();
+    for (const index of indicesOfBefore) {
+      if (index <= indexOfLastPreceding) {
+        const formattedInsertIds = '[' + insertPluginIDs.map(v => `"${v}"`).join(', ') + ']';
+        const formattedAfterIds = '[' + insertAfterPluginIDs.map(v => `"${v}"`).join(', ') + ']';
+        const formattedBeforeIds = '[' + insertBeforePluginsIDs.map(v => `"${v}"`).join(', ') + ']';
+        errors.push(new Error(`insertPlugin was instructed to insert ${formattedInsertIds} after ${formattedAfterIds} and before ${formattedBeforeIds}, ` + `but ${JSON.stringify(pluginIDs[indexOfLastPreceding])} is ordered after ${JSON.stringify(pluginIDs[index])}!`));
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, 'One or more errors occurred while splicing plugin-option tuples into the Semantic Release config!');
+    this.options.plugins.splice(indexOfLastPreceding + 1, 0, ...insertPluginIDs.map(v => [v, {}]));
+  }
+
+  // todo: join result with dummy pack commands
+  async getTokenTestingCommands() {
+    const promiseProjects = this.ProjectsToPackAndPush.every(nri => nri instanceof NugetRegistryInfo) ? this.ProjectsToPackAndPush.map(nri => nri.project) : await Promise.all(await MSBuildProject.PackableProjectsToMSBuildProjects(this.ProjectsToPackAndPush));
+
+    /** if a project is not in {@link EvaluatedProjects}, add it */
+    for (const project of promiseProjects) {
+      if (!this.EvaluatedProjects.includes(project)) this.EvaluatedProjects.push(project);
+    }
+    const regInfos = promiseProjects.map(p => new NugetRegistryInfo({
+      project: p
+    }));
+    const nupkgPaths = await Promise.all(regInfos.map(async nri => nri.PackDummyPackage({}).then(nupkgs => {
+      // this is a full file path.
+      const mainNupkg = nupkgs.find(nupkg => new RegExp(/(?<!symbols)\.nupkg$/).test(nupkg));
+      if (mainNupkg !== undefined) return {
+        nri: nri,
+        nupkgPath: mainNupkg
+      };
+      throw new Error('None of the following dummy packages are non-symbol .nupkg files:\n' + nupkgs.map(nupkg => `  - ${nupkg}`).join('\n') + '\nIf you intended to push only symbol packages, check if a feature request already exists (https://github.com/HaloSPV3/HCE.Shared/issues?q=push+snupkg) and, if one does not exist, create one containing the keywords "push snupkg".');
+    })));
+    const pushCommands = nupkgPaths.map(pair => pair.nri.GetPushDummyCommand({}));
+    return pushCommands.join(' && ');
+  }
+  toOptions() {
+    return this.options;
+  }
+}
+
+/**
+ * Configures {@link baseConfig} with `@semantic-release/exec` to `dotnet`
+ * publish, pack, and nuget-push.
+ * @param projectsToPublish
+ * An array of dotnet projects' relative paths -OR- an array of
+ * {@link MSBuildProject} instances.
+ * - If `MSBuildProject[]`, the instances will be used as-is.
+ * - If `[]`, tries getting projects' semi-colon-separated relative paths from
+ *   the `PROJECTS_TO_PUBLISH` environment variable.
+ * - If configured as recommended, the projects' publish outputs will be zipped
+ *   to '$PWD/publish' for use in the `publish` semantic-release step e.g. for a
+ *   GitHub release.
+ * @param projectsToPackAndPush An array of dotnet projects' relative paths -OR-
+ * an array of instances of {@link NugetRegistryInfo} and/or derived classes.
+ * - If `NugetRegistryInfo[]`, no conversions or modifications will occur.
+ * - If `string[]`, the project paths will be converted to
+ * {@link NugetRegistryInfo} instances with default values. This may be undesired.
+ * - If `[]`, `dotnet pack` and `dotnet nuget push` commands will not be configured.
+ * - If `undefined`, tries getting projects' semi-colon-separated relative paths
+ * from the `PROJECTS_TO_PACK_AND_PUSH` environment variable.
+ * With the recommended configuration, `dotnet pack` will write the nupkg/snupkg
+ * files to `$PWD/publish` where they will be globbed by `dotnet nuget push`.
+ * @returns a semantic-release Options object, based on
+ * `@halospv3/hce.shared-config` (our base config), with the
+ * `@semantic-release/exec` plugin configured to `dotnet publish`, `pack`, and
+ * `push` the specified projects.
+ */
+async function getConfig(projectsToPublish, projectsToPackAndPush) {
+  if (_debug.enabled) {
+    _debug('hce.shared-config:\n' + inspect(baseConfig, false, Infinity, true));
+  }
+  const errors = [];
+  if (projectsToPublish.length === 0) {
+    const _ = getEnvVarValue('PROJECTS_TO_PUBLISH');
+    if (_ === undefined) errors.push(new Error('projectsToPublish.length must be > 0 or PROJECTS_TO_PUBLISH must be defined and contain at least one path.'));else projectsToPublish = _.split(';');
+  }
+  if (!projectsToPackAndPush) {
+    const _ = getEnvVarValue('PROJECTS_TO_PACK_AND_PUSH');
+    if (_ === undefined) errors.push(new Error('projectsToPackAndPush.length must be > 0 or PROJECTS_TO_PACK_AND_PUSH must be defined and contain at least one path.'));else projectsToPackAndPush = _.split(';');
+  }
+  if (errors.length > 0) {
+    throw new Error(['getConfig cannot continue. One or more errors occurred.', ...errors.map(v => v.stack)].join('\n'));
+  }
+  const config = new SemanticReleaseConfigDotnet(projectsToPublish, projectsToPackAndPush ?? []);
+  await config.setupDotnetCommands();
+  const options = config.toOptions();
+  if (_debug.enabled) {
+    _debug('modified plugins array:');
+    _debug(inspect(options.plugins, false, Infinity));
+  }
+  return options;
+}
+
+/**
+ * @module semanticReleaseConfigDotnet
+ */
+
+export { SemanticReleaseConfigDotnet, getConfig };
+//# sourceMappingURL=semanticReleaseConfigDotnet.mjs.map

package/mjs/semanticReleaseConfigDotnet.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticReleaseConfigDotnet.mjs","sources":["../src/semanticReleaseConfigDotnet.ts"],"sourcesContent":null,"names":["debug"],"mappings":"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"}

package/mjs/setupGitPluginSpec.d.ts

@@ -0,0 +1,22 @@
+import type { PluginSpecTuple } from './semanticReleaseConfig.js';
+export declare const GitPluginId = "@semantic-release/git";
+/**
+ * As specified at https://github.com/semantic-release/git#options
+ * To use, assign or create an object with the same (but mutable) properties and deeply-copy to the object
+ * @satisfies { GitOptions }
+ */
+export declare const DefaultOptions: {
+    readonly assets: ['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'];
+    readonly message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}';
+};
+/**
+ * https://github.com/semantic-release/git#options
+ *
+ * This plugin may be deprecated at a later date.
+ * Q: Why would I need to commit during release?
+ * A: This is for committing your changelog, README, and/or other files updated during the release procedure.
+ * @param plugins An ordered array of {@link PluginSpecTuple PluginSpecTuples}.
+ * @returns A {@link PluginSpecTuple}[]. Duplicate `@semantic-release/git` plugin entries are merged or overridden. The last entry takes priority e.g. if the last entry is `{assets: false}`, previous entries' assets are ignored.
+ */
+export declare function setupGitPluginSpec(plugins: PluginSpecTuple[]): PluginSpecTuple[];
+//# sourceMappingURL=setupGitPluginSpec.d.ts.map

package/mjs/setupGitPluginSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupGitPluginSpec.d.ts","sourceRoot":"","sources":["../src/setupGitPluginSpec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEnF,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IAC3G,QAAQ,CAAC,OAAO,EAAE,0EAA0E,CAAC;CAWhE,CAAC;AAuFhC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAkDhF"}

package/mjs/setupGitPluginSpec.mjs

@@ -0,0 +1,144 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+const GitPluginId = '@semantic-release/git';
+
+/**
+ * As specified at https://github.com/semantic-release/git#options
+ * To use, assign or create an object with the same (but mutable) properties and deeply-copy to the object
+ * @satisfies { GitOptions }
+ */
+const DefaultOptions = {
+  assets: ['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'],
+  message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}'
+};
+
+/**
+ * Check if {@link unk} is an {@link AssetEntry}.
+ * @param unk Anything.
+ * @returns `true` if {@link unk} is an {@link AssetEntry}. Else, `false`.
+ */
+function isGitAsset(unk) {
+  if (typeof unk === 'string') return true;
+  // Avoid ending condition with `typeof unk.path === 'string'`.
+  // TS narrowing is bugged; requires the check to be performed TWICE!!
+  if (typeof unk === 'object' && unk != undefined && 'path' in unk) {
+    return typeof unk.path === 'string';
+  }
+  return false;
+}
+
+/**
+ * Convert one or more {@link AssetEntry AssetEntries} to a `string[]`.
+ * @param assets The `assets` property of a {@link GitOptions} object. This may not be `false`.
+ * @returns A `string[]` of the given {@link AssetEntry} objects or strings.
+ */
+function gitAssetsToStringArray(assets) {
+  if (assets === undefined) return [];
+  if (Array.isArray(assets)) {
+    return assets.filter(asset => isGitAsset(asset)).map(v => typeof v === 'string' ? v : v.path);
+  }
+  if (typeof assets === 'string') return [assets];
+  if (typeof assets.path === 'string') return [assets.path];else throw new TypeError('assets is not typeof GitOptions[\'assets\'!');
+}
+
+/**
+ * Sanitize a {@link GitOptions} object so its {@link GitOptions#assets} property is either `false` or a `string[]`.
+ * @param opts A {@link GitOptions} object.
+ * @returns A {@link GitOptions} object whose {@link GitOptions#assets} is `string[] | false`.
+ */
+function sanitizeGitOptions(opts) {
+  return _objectSpread(_objectSpread({}, opts), {}, {
+    assets: opts.assets === false ? opts.assets : gitAssetsToStringArray(opts.assets)
+  });
+}
+
+/**
+ *Determine if {@link opts} is a {@link GitOptions} object.
+ * @param opts Anything.
+ * @returns `true` if {@link opts} is a {@link GitOptions} object. Else, `false`.
+ */
+function isGitOptions(opts) {
+  let isOptions = false;
+  if (typeof opts !== 'object' || opts == undefined) return isOptions;
+  if ('assets' in opts) {
+    isOptions = Array.isArray(opts.assets) ? opts.assets.every(unk => isGitAsset(unk)) : isGitAsset(opts.assets);
+  }
+  if ('message' in opts) isOptions = typeof opts.message === 'string';
+  return isOptions;
+}
+
+/**
+ * Determine if {@link pluginSpec} includes a {@link GitOptions} object.
+ * @param pluginSpec a {@link PluginSpecTuple}.
+ * @returns `true` if {@link pluginSpec[1]} is a {@link GitOptions} object. Else, `false`.
+ */
+function hasGitOptions(pluginSpec) {
+  return isGitOptions(pluginSpec[1]);
+}
+;
+
+/**
+ * Determined if the plugin ID in {@link pluginSpec} is {@link GitPluginId}.
+ * @param pluginSpec A {@link PluginSpecTuple}
+ * @returns `true` if {@link pluginSpec[0]} is {@link GitPluginId}
+ */
+function isGitPluginSpecTuple(pluginSpec) {
+  return pluginSpec[0] === GitPluginId;
+}
+
+/**
+ * https://github.com/semantic-release/git#options
+ *
+ * This plugin may be deprecated at a later date.
+ * Q: Why would I need to commit during release?
+ * A: This is for committing your changelog, README, and/or other files updated during the release procedure.
+ * @param plugins An ordered array of {@link PluginSpecTuple PluginSpecTuples}.
+ * @returns A {@link PluginSpecTuple}[]. Duplicate `@semantic-release/git` plugin entries are merged or overridden. The last entry takes priority e.g. if the last entry is `{assets: false}`, previous entries' assets are ignored.
+ */
+function setupGitPluginSpec(plugins) {
+  /** if Git plugin not in load order, return as-is. */
+  const firstGitPluginIndex = plugins.findIndex(plugin => isGitPluginSpecTuple(plugin));
+  if (firstGitPluginIndex === -1) return plugins;
+
+  /**
+   * the following two const variables are references--not clones.
+   * Modifying them will affect the plugins array.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const firstGitPlugin = plugins[firstGitPluginIndex];
+  const firstGitOpts = isGitOptions(firstGitPlugin[1]) ? sanitizeGitOptions(firstGitPlugin[1]) : DefaultOptions;
+
+  /**
+   * remove duplicate Git plugin entries;
+   * merge extra options into firstGitPlugin's options
+   * if `firstGitOpts.assets === false`, do not change it.
+   * All duplicate PluginSpecSRGit entries are then reassigned `undefined` and all
+   * `undefined` items are filtered from the plugins array.
+   */
+  return plugins.map((current, index) => {
+    // skip everything up to and including the first Git PluginSpec
+    if (index <= firstGitPluginIndex || !isGitPluginSpecTuple(current)) return current;
+
+    /** if another Git PluginSpec is discovered, copy its options to the first Git PluginSpec and return undefined. */
+    if (hasGitOptions(current)) {
+      const currentGitOpts = sanitizeGitOptions(current[1]);
+      if (currentGitOpts.assets === false) {
+        firstGitOpts.assets = false;
+      } else {
+        const assets = gitAssetsToStringArray(currentGitOpts.assets);
+        if (Array.isArray(firstGitOpts.assets)) {
+          firstGitOpts.assets.push(...assets);
+        } else {
+          firstGitOpts.assets = assets;
+        }
+      }
+      if (typeof currentGitOpts.message === 'string') firstGitOpts.message = currentGitOpts.message;
+    }
+    return undefined;
+  }).filter(pluginSpec => pluginSpec !== undefined);
+}
+export { DefaultOptions, GitPluginId, setupGitPluginSpec };
+//# sourceMappingURL=setupGitPluginSpec.mjs.map

package/mjs/setupGitPluginSpec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupGitPluginSpec.mjs","sources":["../src/setupGitPluginSpec.ts"],"sourcesContent":null,"names":[],"mappings":"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"}

package/mjs/utils/Exact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ### `Exact<T, S>`
+ *
+ * [issue](https://github.com/microsoft/TypeScript/issues/12936#issuecomment-2816928183)\
+ * [author](https://github.com/ahrjarrett)\
+ * license: unlicensed[!]
+ * @see
+ * - {@link https://tsplay.dev/NnGG6m}
+ */
+export type Exact<T, S> = [keyof T] extends [keyof S] ? [T] extends [S] ? {
+    [K in keyof T]: T[K];
+} : S : {
+    [K in keyof T as K extends keyof S ? never : K]: TypeError<`Excess: '${Coerce<K>}'`>;
+};
+interface TypeError<Message> {
+    [' TypeError']: Message;
+}
+type Coerce<T> = `${T & (string | number)}`;
+export {};
+//# sourceMappingURL=Exact.d.ts.map

package/mjs/utils/Exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exact.d.ts","sourceRoot":"","sources":["../../src/utils/Exact.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GACjD,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,CAAC,GAC9C;KAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC,YAAY,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;CAAE,CAAC;AA2B7F,UAAU,SAAS,CAAC,OAAO;IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;AAGxD,KAAK,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC"}

package/mjs/utils/Exact.mjs

@@ -0,0 +1,75 @@
+/**
+ * ### `Exact<T, S>`
+ *
+ * [issue](https://github.com/microsoft/TypeScript/issues/12936#issuecomment-2816928183)\
+ * [author](https://github.com/ahrjarrett)\
+ * license: unlicensed[!]
+ * @see
+ * - {@link https://tsplay.dev/NnGG6m}
+ */
+
+// eslint-disable-next-line jsdoc/require-jsdoc, @typescript-eslint/no-unused-vars
+function exact(x, _y) {
+  return x;
+}
+;
+
+// should succeed
+exact({
+  a: 1
+}, {
+  a: 1
+});
+exact({
+  a: 1,
+  b: 'two'
+}, {
+  a: 1,
+  b: 'two'
+});
+
+// should raise a TypeError
+try {
+  // @ts-expect-error Type 'boolean' is not assignable to type 'TypeError<"Excess: 'c'">'.ts(2322)
+  exact({
+    a: 1
+  }, {
+    a: 1,
+    b: 'two',
+    c: false
+  });
+} catch {/* empty */}
+try {
+  // @ts-expect-error Type 'number' is not assignable to type 'TypeError<"Excess: 'c'">'.ts(2322)
+  exact({
+    a: 1,
+    b: 2
+  }, {
+    a: 1,
+    b: 2,
+    c: 3
+  });
+} catch {/* empty */}
+try {
+  // @ts-expect-error Argument of type '{ a: number; }' is not assignable to parameter of type '{ a: number; b: number; }'. Property 'b' is missing in type '{ a: number; }' but required in type '{ a: number; b: number; }'.ts(2345)
+  exact({
+    a: 1,
+    b: 2
+  }, {
+    a: 1
+  });
+} catch {/* empty */}
+
+// prior art: use arktype's ^^^ leading whitespace trick to avoid collisions
+
+try {
+  // @ts-expect-error Should error
+  exact({
+    a: 1
+  }, {
+    a: 1,
+    b: 2
+  });
+  //                           ^ 🚫 raises a TypeError here
+} catch {/* empty */}
+//# sourceMappingURL=Exact.mjs.map

package/mjs/utils/Exact.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exact.mjs","sources":["../../src/utils/Exact.ts"],"sourcesContent":null,"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,SAAS,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE;AACtB,EAAE,OAAO,CAAC;AACV;AACA;;AAEA;AACA,KAAK,CAAC;AACN,EAAE,CAAC,EAAE;AACL,CAAC,EAAE;AACH,EAAE,CAAC,EAAE;AACL,CAAC,CAAC;AACF,KAAK,CAAC;AACN,EAAE,CAAC,EAAE,CAAC;AACN,EAAE,CAAC,EAAE;AACL,CAAC,EAAE;AACH,EAAE,CAAC,EAAE,CAAC;AACN,EAAE,CAAC,EAAE;AACL,CAAC,CAAC;;AAEF;AACA,IAAI;AACJ;AACA,EAAE,KAAK,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,EAAE;AACL,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE,KAAK;AACZ,IAAI,CAAC,EAAE;AACP,GAAG,CAAC;AACJ,CAAC,CAAC,MAAM;AACR,IAAI;AACJ;AACA,EAAE,KAAK,CAAC;AACR,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,EAAE;AACL,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,CAAC;AACJ,CAAC,CAAC,MAAM;AACR,IAAI;AACJ;AACA,EAAE,KAAK,CAAC;AACR,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,EAAE;AACL,IAAI,CAAC,EAAE;AACP,GAAG,CAAC;AACJ,CAAC,CAAC,MAAM;;AAER;;AAEA,IAAI;AACJ;AACA,EAAE,KAAK,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,EAAE;AACL,IAAI,CAAC,EAAE,CAAC;AACR,IAAI,CAAC,EAAE;AACP,GAAG,CAAC;AACJ;AACA,CAAC,CAAC,MAAM"}

package/mjs/utils/GracefulRecursion.d.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=GracefulRecursion.d.mjs.map

package/mjs/utils/GracefulRecursion.d.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"GracefulRecursion.d.mjs","sources":[],"sourcesContent":null,"names":[],"mappings":""}

package/mjs/utils/env.d.ts

@@ -0,0 +1,24 @@
+import { type DotenvConfigOptions, type GetOptions } from '@dotenvx/dotenvx';
+/**
+ * A thin wrapper for {@link loadDotenv}. Loads a .env file from {@link process.cwd()} with the given options (or defaults), returns the new value of {@link process.env} with optional overrides.
+ * @param [dotenvOptions] An optional {@link DotenvConfigOptions} object to pass to {@link loadDotenv}.
+ * @param [overrides] If provided, this {@link NodeJS.ProcessEnv} object is merged into the return value, overriding existing properties where overlap occurs.
+ * @returns A {@link NodeJS.ProcessEnv} object whose properties are variables loaded from the
+ * process environment, the nearest .env file, and {@link overrides} (if provided). Where
+ * overlap occurs, the later source takes priority.
+ */
+export declare function getEnv(dotenvOptions?: DotenvConfigOptions, overrides?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Get the value from the given env var in the current process or nearby .env file.
+ * If found in process environment, its value is returned.
+ * Else, try to get it from the nearest .env file.
+ * If NOT found, return `undefined`
+ * @param envVar The environment variable to lookup.
+ * @param [options] Options to pass to {@link get}
+ * @returns The string value of the environment variable or `undefined`.
+ * `undefined` may be returned when the variable is undefined or its string is
+ * empty, whitespace, or appears to have been converted from `null` or
+ * `undefined`.
+ */
+export declare function getEnvVarValue(envVar: string, options?: GetOptions): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/mjs/utils/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,aAAa,CAAC,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAO5G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAOvF"}

package/mjs/utils/env.mjs

@@ -0,0 +1,39 @@
+import { config, get } from '@dotenvx/dotenvx';
+import { env } from 'node:process';
+
+/**
+ * A thin wrapper for {@link loadDotenv}. Loads a .env file from {@link process.cwd()} with the given options (or defaults), returns the new value of {@link process.env} with optional overrides.
+ * @param [dotenvOptions] An optional {@link DotenvConfigOptions} object to pass to {@link loadDotenv}.
+ * @param [overrides] If provided, this {@link NodeJS.ProcessEnv} object is merged into the return value, overriding existing properties where overlap occurs.
+ * @returns A {@link NodeJS.ProcessEnv} object whose properties are variables loaded from the
+ * process environment, the nearest .env file, and {@link overrides} (if provided). Where
+ * overlap occurs, the later source takes priority.
+ */
+function getEnv(dotenvOptions, overrides) {
+  config(dotenvOptions);
+  if (overrides) Object.assign(env, overrides);
+  return env;
+}
+
+/**
+ * Get the value from the given env var in the current process or nearby .env file.
+ * If found in process environment, its value is returned.
+ * Else, try to get it from the nearest .env file.
+ * If NOT found, return `undefined`
+ * @param envVar The environment variable to lookup.
+ * @param [options] Options to pass to {@link get}
+ * @returns The string value of the environment variable or `undefined`.
+ * `undefined` may be returned when the variable is undefined or its string is
+ * empty, whitespace, or appears to have been converted from `null` or
+ * `undefined`.
+ */
+function getEnvVarValue(envVar, options) {
+  options ??= {
+    ignore: ['MISSING_KEY', 'MISSING_ENV_FILE']
+  };
+  const value = String(env[envVar] ?? get(envVar, options)).trim();
+  // I hate this. Why is undefined converted to a string?
+  return value === '' || value === 'undefined' ? undefined : value;
+}
+export { getEnv, getEnvVarValue };
+//# sourceMappingURL=env.mjs.map