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

package/src/semantic-release__github.d.ts

@@ -1,145 +1,145 @@
-declare module "@semantic-release/github" {
-    /**
-     * @see https://github.com/semantic-release/github#configuration
-     */
-    export interface Env extends NodeJS.ProcessEnv {
-        /**
-         * __Required__. The token used to authenticate with GitHub.
-         */
-        GITHUB_TOKEN?: string,
-        /** 
-         * {@inheritDoc GitHubEnv.GITHUB_TOKEN}
-         */
-        GH_TOKEN?: string,
+declare module '@semantic-release/github' {
+  /**
+   * @see https://github.com/semantic-release/github#configuration
+   */
+  export interface Env extends NodeJS.ProcessEnv {
+    /**
+     * __Required__. The token used to authenticate with GitHub.
+     */
+    GITHUB_TOKEN?: string;
+    /**
+     * {@inheritDoc GitHubEnv.GITHUB_TOKEN}
+     */
+    GH_TOKEN?: string;
 
-        /**
-         *  The GitHub server endpoint.
-         */
-        GITHUB_URL?: string,
-        /** 
-         * {@inheritDoc GitHubEnv.GITHUB_URL}
-         */
-        GH_URL?: string,
+    /**
+     *  The GitHub server endpoint.
+     */
+    GITHUB_URL?: string;
+    /**
+     * {@inheritDoc GitHubEnv.GITHUB_URL}
+     */
+    GH_URL?: string;
 
-        /**
-         * The GitHub API prefix, relative to {@link Env.GITHUB_URL GITHUB_URL}.
-         */
-        GITHUB_PREFIX?: string,
-        /** {@inheritDoc GitHubEnv.GITHUB_PREFIX} */
-        GH_PREFIX?: string,
+    /**
+     * The GitHub API prefix, relative to {@link Env.GITHUB_URL GITHUB_URL}.
+     */
+    GITHUB_PREFIX?: string;
+    /** {@inheritDoc GitHubEnv.GITHUB_PREFIX} */
+    GH_PREFIX?: string;
 
-        /**
-         * The GitHub API endpoint. Note that this overwrites {@link Env.GITHUB_PREFIX GITHUB_PREFIX}.
-         */
-        GITHUB_API_URL?: string
-    }
+    /**
+     * The GitHub API endpoint. Note that this overwrites {@link Env.GITHUB_PREFIX GITHUB_PREFIX}.
+     */
+    GITHUB_API_URL?: string;
+  }
 
-    /** https://github.com/isaacs/node-glob#glob-primer */
-    type Glob = string;
+  /** https://github.com/isaacs/node-glob#glob-primer */
+  type Glob = string;
 
-    /** @see https://github.com/semantic-release/github#assets */
-    interface Asset {
-        /** __Required__. A {@link https://github.com/isaacs/node-glob#glob-primer glob} to identify the files to upload. */
-        path: Glob,
-        /** 
-         * The name of the downloadable file on the GitHub release.
-         * @defaultValue File name extracted from the {@link Asset.path path}.
-         */
-        name?: string,
-        /** Short description of the file displayed on the GitHub release. */
-        label?: string
-    }
+  /** @see https://github.com/semantic-release/github#assets */
+  interface Asset {
+    /** __Required__. A {@link https://github.com/isaacs/node-glob#glob-primer glob} to identify the files to upload. */
+    path: Glob;
+    /**
+     * The name of the downloadable file on the GitHub release.
+     * Defaults to the file name extracted from the {@link Asset.path}.
+     */
+    name?: string;
+    /** Short description of the file displayed on the GitHub release. */
+    label?: string;
+  }
 
-    /** @see https://github.com/semantic-release/github#configuration */
-    export interface Options {
-        /**
-         * The GitHub server endpoint.
-         * @defaultValue {@link Env.GH_URL GH_URL} or  {@link Env.GITHUB_URL GITHUB_URL} environment variables.
-         */
-        githubUrl?: string,
-        /**
-         * The GitHub API prefix, relative to `githubUrl`.
-         * @defaultValue {@link Env.GH_PREFIX GH_PREFIX} or {@link Env.GITHUB_PREFIX GITHUB_PREFIX} environment variables
-         */
-        githubApiPathPrefix?: string,
-        /**
-         * The GitHub API endpoint.
-         * Note that this overwrites {@link Options.githubApiPathPrefix githubApiPathPrefix}.
-         */
-        githubApiUrl?: string,
-        /** 
-         * The proxy to use to access the GitHub API.
-         * Set to `false` to disable usage of proxy.
-         * See {@link https://github.com/semantic-release/github#proxy proxy}.
-        */
-        proxy?: string | false,
-        /**
-         * An array of files to upload to the release.
-         * See {@link https://github.com/semantic-release/github#assets assets}.
-         */
-        assets?: Glob | (Asset | Glob)[],
-        /**
-         * The comment to add to each issue and pull request resolved by the release.
-         * Set to `false` to disable commenting on issues and pull requests.
-         * See {@link https://github.com/semantic-release/github?tab=readme-ov-file#successcomment successComment}.
-         * @defaultValue `:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)`
-         */
-        successComment?: string | false,
-        /** 
-         * The content of the issue created when a release fails.
-         * Set to `false` to disable opening an issue when a release fails.
-         * See {@link https://github.com/semantic-release/github?tab=readme-ov-file#failcomment failComment}.
-         * @defaultValue Friendly message with links to semantic-release documentation and support, with the list of errors that caused the release to fail.
-         */
-        failComment?: string | false,
-        /**
-         * The title of the issue created when a release fails.
-         * Set to `false` to disable opening an issue when a release fails.
-         * @defaultValue `The automated release is failing 🚨`
-         */
-        failTitle?: string | false,
-        /**
-         * The {@link https://help.github.com/articles/about-labels labels} to add to the issue created when a release fails.
-         * Set to `false` to not add any label.
-         * @default ['semantic-release']
-         */
-        labels?: string[] | false,
-        /** 
-         * The {@link https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users assignees} to add to the issue created when a release fails.
-         */
-        assignees?: unknown,
-        /**
-         *  The {@link https://help.github.com/articles/about-labels labels} to add to each issue and pull request resolved by the release.
-         * Set to `false` to not add any label.
-         * See {@link https://github.com/semantic-release/github#releasedlabels releasedLabels}.
-         * @default [ 'released<%= nextRelease.channel ? \` on @\${nextRelease.channel}\` : "" %>' ]
-         */
-        releasedLabels?: string[],
-        /**
-         * Will add release links to the GitHub Release. Can be `false`, `"bottom"` or `"top"`. See {@link https://github.com/semantic-release/github#addReleases addReleases}.
-         * @default false
-         */
-        addReleases?: false | "bottom" | "top",
-        /**
-         * A boolean indicating if a GitHub Draft Release should be created instead of publishing an actual GitHub Release.
-         * @default false
-         */
-        draftRelease?: boolean,
-        /**
-         * A {@link https://lodash.com/docs#template Lodash template} to customize the github release's name
-         * @default '<%= nextverison.name %>'
-         */
-        releaseNameTemplate?: string,
-        /**
-         * A {@link https://lodash.com/docs#template Lodash template} to customize the github release's body
-         * @default '<%= nextverison.notes %>'
-         */
-        releaseBodyTemplate?: string,
-        /**
-         * The category name in which to create a linked discussion to the release.
-         * Set to `false` to disable creating discussion for a release.
-         * @default false
-         */
-        discussionCategoryName?: string | false
-    }
-}
+  /** @see https://github.com/semantic-release/github#configuration */
+  export interface Options {
+    /**
+     * The GitHub server endpoint.
+     * Defaults to the values of the {@link Env.GH_URL GH_URL} or {@link Env.GITHUB_URL GITHUB_URL} environment variables.
+     */
+    githubUrl?: string;
+    /**
+     * The GitHub API prefix, relative to `githubUrl`.
+     * Defaults to the values of the {@link Env.GH_PREFIX GH_PREFIX} or {@link Env.GITHUB_PREFIX GITHUB_PREFIX} environment variables
+     */
+    githubApiPathPrefix?: string;
+    /**
+     * The GitHub API endpoint.
+     * Note that this overwrites {@link Options.githubApiPathPrefix githubApiPathPrefix}.
+     */
+    githubApiUrl?: string;
+    /**
+     * The proxy to use to access the GitHub API.
+     * Set to `false` to disable usage of proxy.
+     * See {@link https://github.com/semantic-release/github#proxy proxy}.
+     */
+    proxy?: string | false;
+    /**
+     * An array of files to upload to the release.
+     * See {@link https://github.com/semantic-release/github#assets assets}.
+     */
+    assets?: Glob | (Asset | Glob)[];
+    /**
+     * The comment to add to each issue and pull request resolved by the release.
+     * Set to `false` to disable commenting on issues and pull requests.
+     * See {@link https://github.com/semantic-release/github?tab=readme-ov-file#successcomment successComment}.
+     * Defaults to `:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)`
+     */
+    successComment?: string | false;
+    /**
+     * The content of the issue created when a release fails.
+     * Set to `false` to disable opening an issue when a release fails.
+     * See {@link https://github.com/semantic-release/github?tab=readme-ov-file#failcomment failComment}.
+     * Defaults to a friendly message with links to semantic-release documentation and support, with the list of errors that caused the release to fail.
+     */
+    failComment?: string | false;
+    /**
+     * The title of the issue created when a release fails.
+     * Set to `false` to disable opening an issue when a release fails.
+     * Defaults to `The automated release is failing 🚨`
+     */
+    failTitle?: string | false;
+    /**
+     * The {@link https://help.github.com/articles/about-labels labels} to add to the issue created when a release fails.
+     * Set to `false` to not add any label.
+     * @default ['semantic-release']
+     */
+    labels?: string[] | false;
+    /**
+     * The {@link https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users assignees} to add to the issue created when a release fails.
+     */
+    assignees?: unknown;
+    /**
+     *  The {@link https://help.github.com/articles/about-labels labels} to add to each issue and pull request resolved by the release.
+     * Set to `false` to not add any label.
+     * See {@link https://github.com/semantic-release/github#releasedlabels releasedLabels}.
+     * @default [ 'released<%= nextRelease.channel ? \` on @\${nextRelease.channel}\` : "" %>' ]
+     */
+    releasedLabels?: string[];
+    /**
+     * Will add release links to the GitHub Release. Can be `false`, `"bottom"` or `"top"`. See {@link https://github.com/semantic-release/github#addReleases addReleases}.
+     * @default false
+     */
+    addReleases?: false | 'bottom' | 'top';
+    /**
+     * A boolean indicating if a GitHub Draft Release should be created instead of publishing an actual GitHub Release.
+     * @default false
+     */
+    draftRelease?: boolean;
+    /**
+     * A {@link https://lodash.com/docs#template Lodash template} to customize the github release's name
+     * @default '<%= nextRelease.name %>'
+     */
+    releaseNameTemplate?: string;
+    /**
+     * A {@link https://lodash.com/docs#template Lodash template} to customize the github release's body
+     * @default '<%= nextRelease.notes %>'
+     */
+    releaseBodyTemplate?: string;
+    /**
+     * The category name in which to create a linked discussion to the release.
+     * Set to `false` to disable creating discussion for a release.
+     * @default false
+     */
+    discussionCategoryName?: string | false;
+  }
+}

package/src/semanticReleaseConfig.ts

@@ -1,52 +1,111 @@
-import type { Options as GitOptions } from '@semantic-release/git';
-import type { Options as GithubOptions } from '@semantic-release/github';
+import type { Options as SRCommitAnalyzerOptions } from '@semantic-release/commit-analyzer';
+import type { Options as SRExecOptions } from '@semantic-release/exec';
+import type { Options as SRGitOptions } from '@semantic-release/git';
+import type { Options as SRGithubOptions } from '@semantic-release/github';
 import type { Options, PluginSpec } from 'semantic-release';
 import { DefaultOptions } from './setupGitPluginSpec.js';
 
-export const defaultPlugins: readonly PluginSpec[] = [
-	'@semantic-release/commit-analyzer',
-	'@semantic-release/release-notes-generator',
-	'@semantic-release/npm',
-	'@semantic-release/github',
-];
+export interface SRReleaseNotesGeneratorOptions {
+  /**
+   * conventional-changelog preset.
+   * @default 'angular'
+   */
+  preset?: 'angular' | 'atom' | 'codemirror' | 'ember' | 'eslint' | 'express' | 'jquery' | 'jscs' | 'jshint' | 'conventionalcommits' | (string & Record<never, never>) | undefined;
+  /**
+   * Requireable npm package with a custom conventional-changelog preset.
+   */
+  config?: string | undefined;
+  /**
+   * Additional `conventional-changelog-parser` options that will overwrite ones loaded by `preset` or `config`.
+   */
+  parserOpts: object;
+  /**
+   * Additional `conventional-changelog-writer` options that will overwrite ones loaded by `preset` or `config`.
+   */
+  writerOpts: object;
+}
 
-export const baseConfig = {
-	/** @see https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugin-options-configuration */
-	preset: 'conventionalcommits',
-	branches: [
-		'main',
-		{
-			name: 'develop',
-			channel: 'develop',
-			prerelease: true
-		}
-	],
-	plugins: [
-		["@semantic-release/commit-analyzer", {}],
-		["semantic-release-export-data", {}],
-		["@semantic-release/release-notes-generator", {}],
-		["@semantic-release/changelog", {}],
-		[
-			"@semantic-release/git",
-			DefaultOptions
-		] as PluginSpec<GitOptions>,
-		// Arbitrary shell commands - https://github.com/semantic-release/exec
-		// hint: set 'prepareCmd' to`dotnet publish`.
-		//   Because this is sorted after @semantic-release / git, the new Git tag will
-		//   be visible to dotnet(and GitVersion).Dotnet artifacts will be
-		//   versioned accordingly.
-		// Plugins' Steps: https://github.com/semantic-release/semantic-release/blob/master/docs/extending/plugins-list.md
-		["@semantic-release/exec", {}],
-		["@semantic-release/github",
-			{
-				assets: [{
-					path: './publish/*'
-				}]
-			}
-		] as PluginSpec<GithubOptions>
-	]
-} as Options;
+/**
+ * A two-type PluginSpec to tie a plugin's name to its Options type. This is
+ * intended for use by plugins to associate their Options type with their plugin
+ * name.
+ */
+export type PluginSpecTuple<P extends string = string, T = unknown> = [P, T];
+export type PluginSpecSRCommitAnalyzer<V extends SRCommitAnalyzerOptions = SRCommitAnalyzerOptions> = PluginSpecTuple<'@semantic-release/commit-analyzer', V>;
+export type PluginSpecSRChangelog<V extends Record<'changelogFile' | 'changelogTitle', string>> = PluginSpecTuple<'@semantic-release/changelog', V>;
+export type PluginSpecExportData<V extends Record<string, unknown> = Record<string, unknown>> = PluginSpecTuple<'semantic-release-export-data', V>;
+export type PluginSpecSRReleaseNotesGen<V extends SRReleaseNotesGeneratorOptions = SRReleaseNotesGeneratorOptions> = PluginSpecTuple<'@semantic-release/release-notes-generator', V>;
+export type PluginSpecSRExec<V extends SRExecOptions = SRExecOptions> = PluginSpecTuple<'@semantic-release/exec', V>;
+export type PluginSpecSRGit<V extends SRGitOptions = SRGitOptions> = PluginSpecTuple<'@semantic-release/git', V>;
+export type PluginSpecSRGithub<V extends SRGithubOptions = SRGithubOptions> = PluginSpecTuple<'@semantic-release/github', V>;
 
-/// (OPTIONAL) update static Version strings before Git plugin
-// https://github.com/jpoehnelt/semantic-release-replace-plugin
-// https://github.com/droidsolutions/semantic-release-update-file
+/**
+ * @satisfies { Readonly<PluginSpec[]> }
+ */
+export const defaultPlugins = Object.freeze([
+  '@semantic-release/commit-analyzer',
+  '@semantic-release/release-notes-generator',
+  '@semantic-release/npm',
+  '@semantic-release/github',
+] as const) satisfies readonly PluginSpec[];
+
+// define as const for string literals in type, then...
+/**
+ *  @see baseConfig
+ */
+const _baseConfig = {
+  /** @see https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugin-options-configuration */
+  preset: 'conventionalcommits' as const,
+  branches: [
+    'main',
+    { name: 'develop', channel: 'develop', prerelease: true },
+  ] as ['main', { name: 'develop'; channel: 'develop'; prerelease: true }],
+  plugins: [
+    ['@semantic-release/commit-analyzer', {}],
+    ['semantic-release-export-data', {}],
+    ['@semantic-release/release-notes-generator', {}],
+    ['@semantic-release/changelog', {}],
+    ['@semantic-release/git', DefaultOptions],
+    ['@semantic-release/exec', {}],
+    ['@semantic-release/github', { addReleases: 'bottom', assets: [{ path: './publish/*' }] }],
+  ] as [
+    PluginSpecSRCommitAnalyzer,
+    PluginSpecExportData,
+    PluginSpecSRReleaseNotesGen,
+    PluginSpecSRChangelog<Record<'changelogFile' | 'changelogTitle', string>>,
+    PluginSpecSRGit<typeof DefaultOptions>,
+    PluginSpecSRExec,
+    PluginSpecSRGithub<{ addReleases: 'bottom'; assets: [{ path: './publish/*' }] }>,
+  ] | PluginSpec[],
+};
+
+/**
+ * The base configuration for various Semantic Release scenarios.
+ * - Prefers preset "conventionalcommits"
+ *   (Conventional-Changelog-ConventionalCommits).
+ * - Creates tags and release commits on "main" branch, pre-releases on
+ *   "develop" branch in "develop" channel.
+ * - Creates GitHub Releases.
+ * - Exports the following variables as GitHub Actions outputs:
+ *   - "new-release-published": "true" | "false"
+ *   - "new-release-version" : string
+ *   - "new-release-git-tag" : string
+ * - includes default plugins (except `@semantic-release/npm`) and more
+ *   - `@semantic-release/commit-analyzer`
+ *   - semantic-release-export-data
+ *   - `@semantic-release/release-notes-generator`
+ *   - `@semantic-release/changelog`
+ *   - `@semantic-release/git`
+ *     - add modified CHANGELOG.md in release commit
+ *   - `@semantic-release/exec`
+ *     - does nothing by default. Included for convenience.
+ *   - `@semantic-release/github`
+ *     - uploads all files from `./publish/*`. This is non-recursive.
+ *     - adds a list of links to related release pages (e.g. the release's page on npmjs.com)
+ *
+ * (OPTIONAL) update static Version strings before Git plugin
+ * - https://github.com/jpoehnelt/semantic-release-replace-plugin
+ * - https://github.com/droidsolutions/semantic-release-update-file
+ * @satisfies {Options}
+ */
+export const baseConfig: typeof _baseConfig = _baseConfig satisfies Options;