@halospv3/hce.shared-config 2.3.2 → 2.4.2

package/src/dotnet/dotnetHelpers.ts

@@ -3,6 +3,111 @@ import { getGithubNugetRegistryPair, nugetGitHubUrlBase } from './dotnetGHPR.js'
 import { getGitlabNugetRegistryPair } from './dotnetGLPR.js';
 import { MSBuildProject, MSBuildProjectPreDefinedProperties } from './MSBuildProject.js';
 
+
+function formatDotnetPublish(projectsToPublish: string[], publishProperties: string[]): string {
+	/* Fun Fact: You can define a property and get the evaluated value in the same command!
+	```pwsh
+	dotnet msbuild .\src\HXE.csproj -property:RuntimeIdentifiers="""place;holder""" -getProperty:RuntimeIdentifiers
+	place;holder
+	```
+	 enclosing with """ is required in pwsh to prevent the semicolon from breaking the string.
+	*/
+	if (!(Array.isArray(projectsToPublish) && projectsToPublish.length > 0))
+		throw new Error(`Type of projectsToPublish (${typeof projectsToPublish}) is not allowed. Expected a string[] where length > 0.`);
+
+	// each may have TargetFramework OR TargetFrameworks (plural)
+	const evaluatedProjects: MSBuildProject[] = projectsToPublish.map(
+		(proj) => new MSBuildProject(proj, publishProperties),
+	);
+	// args appended to "dotnet publish", joined by space
+
+	return evaluatedProjects.flatMap(proj => {
+		const args: string[] = [proj.Properties.FullPath];
+
+		function appendCustomProperties(publishProperties: string[]) {
+			// convert to dictionary and filter for user-defined properties.
+			const dictionary = Object.entries(proj.Properties).filter(
+				(p) => !publishProperties.includes(p[0]),
+			);
+			if (dictionary.length > 0) {
+				/* format remaining properties as "-p:Property=Value" and append to args */
+				args.push(
+					...dictionary.map((keyValuePair) => `-p:${keyValuePair[0]}=${keyValuePair[1]}`),
+				);
+			}
+		}
+		appendCustomProperties(publishProperties);
+
+		const cmdPermutations: string[][] = []; // forEach, run dotnet [...args,...v]
+
+		function formatFrameworksAndRuntimes() {
+			const RIDs: string[] =
+				proj.Properties.RuntimeIdentifiers.length > 0
+					? proj.Properties.RuntimeIdentifiers.split(';')
+					: [];
+			const TFMs: string[] =
+				proj.Properties.TargetFrameworks.length > 0
+					? proj.Properties.TargetFrameworks.split(';')
+					: [];
+			if (RIDs.length > 0) {
+				if (TFMs.length > 0) {
+					for (const RID of RIDs) {
+						for (const TFM of TFMs) {
+							cmdPermutations.push(['--runtime', RID, '--framework', TFM]);
+						}
+					}
+				} else {
+					// assume singular TFM. No need to specify it.
+					for (const RID of RIDs) {
+						cmdPermutations.push(['--runtime', RID]);
+					}
+				}
+			} else if (TFMs.length > 0) {
+				for (const TFM of TFMs) {
+					cmdPermutations.push(['--framework', TFM]);
+				}
+			}
+		}
+		formatFrameworksAndRuntimes();
+
+		return cmdPermutations.length > 0
+			? cmdPermutations.map((permArgs) => [...args, ...permArgs]) // string[][]
+			: [args]; // string[][]
+	}).map((args) => `dotnet publish ${args.join(' ')}`).join(' && ');
+}
+
+function formatDotnetPack(projectsToPackAndPush: string[] | false): string {
+	return projectsToPackAndPush === false
+		? ""
+		: projectsToPackAndPush
+			.map(v => `dotnet pack ${v}`)
+			.join(' && ');
+}
+
+function formatDotnetNugetSign(dotnetNugetSignArgs: string[]): string {
+	switch (dotnetNugetSignArgs.length) {
+		case 0:
+			return '';
+		default:
+			return `dotnet nuget sign ${dotnetNugetSignArgs.join(' ')}`;
+		// default: {
+		//     throw new Error("")
+		//     // this needs a rework.
+		//     const packagePaths: string[] = [];
+		//     dotnetNugetSignArgs.forEach((dotnetNugetSignArg, i) => {
+		//         // if current arg doesn't start with '-' and (current arg is first -OR- previous arg also does not start with '-')...
+		//         if (!dotnetNugetSignArg.startsWith("-") && (i === 0 || (i > 0 && !dotnetNugetSignArgs[i - 1].startsWith("-")))) {
+		//             // ...then it's probably a package path.
+		//             packagePaths.push(dotnetNugetSignArg);
+		//         }
+		//     });
+		//     if (packagePaths.length === 0)
+		//         return `dotnet nuget sign ${dotnetNugetSignArgs.join(" ")}`
+		//     else return
+		// }
+	}
+}
+
 /**
  * Build a prepareCmd string from .NET project paths and `dotnet nuget sign` arguments.
  *
@@ -10,122 +115,22 @@ import { MSBuildProject, MSBuildProjectPreDefinedProperties } from './MSBuildPro
  * todo: cleanup, docs
  * @export
  * @param {string[]} projectsToPublish
- * @param {string[]} projectsToPackAndPush Relative and/or full file paths of projects to pass to `dotnet pack`. By default, these will be output to `./publish/`.
+ * @param {string[]|false} projectsToPackAndPush Relative and/or full file paths of projects to pass to `dotnet pack`. By default, these will be output to `./publish/`.
  * @param {string[]} dotnetNugetSignArgs Arguments appended to `dotnet nuget sign`. You can also append '&&' if you want to start a new command or if you want to sign different sets of packages with different keys.
  */
 export function configurePrepareCmd(
 	projectsToPublish: string[],
-	projectsToPackAndPush: string[],
+	projectsToPackAndPush: string[] | false,
 	dotnetNugetSignArgs: string[] = ['./publish'],
 ) {
 	// These are later evaluated with MSBuild, but are passed via --framework and --runtime arguments instead of -p:TargetFramework
 	const publishProperties = MSBuildProjectPreDefinedProperties;
 
-	function formatDotnetPublish(): string {
-		/* Fun Fact: You can define a property and get the evaluated value in the same command!
-		```pwsh
-		dotnet msbuild .\src\HXE.csproj -property:RuntimeIdentifiers="""place;holder""" -getProperty:RuntimeIdentifiers
-		place;holder
-		```
-			enclosing with """ is required in pwsh to prevent the semicolon from breaking the string.
-		*/
-		if (!(Array.isArray(projectsToPublish) && projectsToPublish.length > 0))
-			throw new Error(`Type of projectsToPublish (${typeof projectsToPublish}) is not allowed. Expected a string[] where length > 0.`);
-
-		// each may have TargetFramework OR TargetFrameworks (plural)
-		const evaluatedProjects: MSBuildProject[] = projectsToPublish.map(
-			(proj) => new MSBuildProject(proj, publishProperties),
-		);
-		// args appended to "dotnet publish", joined by space
-		const dotnetPublishArgs = evaluatedProjects.flatMap((proj) => {
-			const args: string[] = [proj.Properties.FullPath];
-
-			function appendCustomProperties() {
-				// convert to dictionary and filter for user-defined properties.
-				const dictionary = Object.entries(proj.Properties).filter(
-					(p) => !publishProperties.includes(p[0]),
-				);
-				if (dictionary.length > 0) {
-					/* format remaining properties as "-p:Property=Value" and append to args */
-					args.push(
-						...dictionary.map((keyValuePair) => `-p:${keyValuePair[0]}=${keyValuePair[1]}`),
-					);
-				}
-			}
-			appendCustomProperties();
-
-			const cmdPermutations: string[][] = []; // forEach, run dotnet [...args,...v]
-
-			function formatFrameworksAndRuntimes() {
-				const RIDs: string[] =
-					proj.Properties.RuntimeIdentifiers.length > 0
-						? proj.Properties.RuntimeIdentifiers.split(';')
-						: [];
-				const TFMs: string[] =
-					proj.Properties.TargetFrameworks.length > 0
-						? proj.Properties.TargetFrameworks.split(';')
-						: [];
-				if (RIDs.length > 0) {
-					if (TFMs.length > 0) {
-						for (const RID of RIDs) {
-							for (const TFM of TFMs) {
-								cmdPermutations.push(['--runtime', RID, '--framework', TFM]);
-							}
-						}
-					} else {
-						// assume singular TFM. No need to specify it.
-						for (const RID of RIDs) {
-							cmdPermutations.push(['--runtime', RID]);
-						}
-					}
-				} else if (TFMs.length > 0) {
-					for (const TFM of TFMs) {
-						cmdPermutations.push(['--framework', TFM]);
-					}
-				}
-			}
-			formatFrameworksAndRuntimes();
-
-			return cmdPermutations.length > 0
-				? cmdPermutations.map((permArgs) => [...args, ...permArgs]) // string[][]
-				: [args]; // string[][]
-		}); // string[][][] -> string[][]
-
-		return dotnetPublishArgs.map((args) => `dotnet publish ${args.join(' ')}`).join(' && ');
-	}
-
-	function formatDotnetPack(): string {
-		return projectsToPackAndPush.map((v) => `dotnet pack ${v}`).join(' && ');
-	}
-
-	function formatDotnetNugetSign(): string {
-		switch (dotnetNugetSignArgs.length) {
-			case 0:
-				return '';
-			default:
-				return `dotnet nuget sign ${dotnetNugetSignArgs.join(' ')}`;
-			// default: {
-			//     throw new Error("")
-			//     // this needs a rework.
-			//     const packagePaths: string[] = [];
-			//     dotnetNugetSignArgs.forEach((dotnetNugetSignArg, i) => {
-			//         // if current arg doesn't start with '-' and (current arg is first -OR- previous arg also does not start with '-')...
-			//         if (!dotnetNugetSignArg.startsWith("-") && (i === 0 || (i > 0 && !dotnetNugetSignArgs[i - 1].startsWith("-")))) {
-			//             // ...then it's probably a package path.
-			//             packagePaths.push(dotnetNugetSignArg);
-			//         }
-			//     });
-			//     if (packagePaths.length === 0)
-			//         return `dotnet nuget sign ${dotnetNugetSignArgs.join(" ")}`
-			//     else return
-			// }
-		}
-	}
-
-	const dotnetPublish = formatDotnetPublish();
-	const dotnetPack = formatDotnetPack();
-	const dotnetNugetSign = formatDotnetNugetSign();
-	return [dotnetPublish, dotnetPack, dotnetNugetSign].join(' && ');
+	return [
+		formatDotnetPublish(projectsToPublish, publishProperties),
+		formatDotnetPack(projectsToPackAndPush),
+		formatDotnetNugetSign(dotnetNugetSignArgs)
+	].join(' && ');
 }
 
 export interface NuGetRegistryInfo {
@@ -139,7 +144,7 @@ export const nugetDefault: NuGetRegistryInfo = {
 };
 
 /**
- * todo
+ * todo -
  * @param nupkgDir
  * @param registries
  * @param pushToGitHub

package/src/eslintConfig.ts

@@ -2,8 +2,11 @@ import jsonc from "eslint-plugin-jsonc";
 import tseslint from "typescript-eslint";
 import { type TSESLint } from "@typescript-eslint/utils";
 import eslint from "@eslint/js";
-import globals from "globals" with {type: "json"};
+import { createRequire } from "module";
 
+// CJS compatibility; it started transpiling to a top-level await after upgrading from packemon 4.0.1 to 4.1.0
+const require = createRequire(import.meta.url);
+const globals = require("globals") as typeof import("globals", {with: {type: "json"}});
 // https://eslint.org/docs/latest/use/configure/migration-guide#using-eslintrc-configs-in-flat-config
 // https://www.google.com/search?q=javascript+recurse+through+object+and+remove+undefined+properties
 

package/src/semantic-release__commit-analyzer.d.ts

@@ -0,0 +1,44 @@
+declare module '@semantic-release/commit-analyzer' {
+
+    interface RuleObject {
+        type?: string,
+        scope?: string,
+        release: string
+    }
+
+    type AnyRecord = Record<keyof unknown, unknown>;
+
+    export interface CommitAnalyzerConfig {
+        preset?: string,
+        config?: string,
+        parserOpts?: AnyRecord,
+        releaseRules?: string | RuleObject[],
+        presetConfig?: AnyRecord
+    }
+
+    /**
+     * Determine the type of release to create based on a list of commits.
+     *
+     * @param {Object} pluginConfig The plugin configuration.
+     * @param {String} pluginConfig.preset conventional-changelog preset ('angular', 'atom', 'codemirror', 'ember', 'eslint', 'express', 'jquery', 'jscs', 'jshint')
+     * @param {String} pluginConfig.config Requireable npm package with a custom conventional-changelog preset
+     * @param {String|Array} pluginConfig.releaseRules A `String` to load an external module or an `Array` of rules.
+     * @param {Object} pluginConfig.parserOpts Additional `conventional-changelog-parser` options that will overwrite ones loaded by `preset` or `config`.
+     * @param {Object} context The semantic-release context.
+     * @param {Array<Object>} context.commits The commits to analyze.
+     * @param {String} context.cwd The current working directory.
+     *
+     * @returns {Promise<String|null>} the type of release to create based on the list of commits or `null` if no release has to be done.
+     * 
+     * @see 'file://./../node_modules/@semantic-release/commit-analyzer/index.js'
+     */
+    export function analyzeCommits(pluginConfig: {
+        preset: string;
+        config: string;
+        releaseRules: string | AnyRecord[];
+        parserOpts: unknown;
+    }, context: {
+        commits: unknown[];
+        cwd: string;
+    }): Promise<string | null>;
+}

package/src/semantic-release__git.d.ts

@@ -1,4 +1,6 @@
+/** @see 'file://./../node_modules/@semantic-release/git/index.js' */
 declare module '@semantic-release/git' {
+	import type { Options as SemanticReleaseOptions } from "semantic-release";
 	export type MicromatchGlob = string;
 	export interface AssetObject {
 		path: MicromatchGlob;
@@ -64,4 +66,26 @@ declare module '@semantic-release/git' {
 		 */
 		message?: string;
 	}
+
+	function verifyConditions(
+		pluginConfig: Options,
+		context: {
+			options: {
+				prepare: unknown
+			}
+		}
+	): void;
+	async function prepare(
+		pluginConfig: Options,
+		context: {
+			env,
+			cwd: string,
+			branch: { name: string },
+			options: SemanticReleaseOptions,
+			lastRelease,
+			nextRelease: { version, notes, gitTag },
+			logger: { log(_0: string, _1: unknown | number): void },
+		}
+	): Promise<void>;
+	export { verifyConditions, prepare }
 }

package/src/semanticReleaseConfig.ts

@@ -1,15 +1,52 @@
-import { readFileSync } from 'node:fs';
-import jsYaml from 'js-yaml';
 import type { Options, PluginSpec } from 'semantic-release';
-import { findStaticConfig } from './findStaticConfig.js';
+import type { Options as GitOptions } from '@semantic-release/git'
+import type { Options as GithubOptions } from '@semantic-release/github'
+import { DefaultOptions } from './setupGitPluginSpec.js';
 
-export const defaultPlugins = [
-	'@semantic-release/commit-analyzer' as PluginSpec,
+export const defaultPlugins: readonly PluginSpec[] = [
+	'@semantic-release/commit-analyzer',
 	'@semantic-release/release-notes-generator',
 	'@semantic-release/npm',
 	'@semantic-release/github',
 ];
 
-export const baseConfig: Options = jsYaml.load(
-	readFileSync(findStaticConfig(), { encoding: 'utf8' }),
-) as Options;
+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;
+
+/// (OPTIONAL) update static Version strings before Git plugin
+// https://github.com/jpoehnelt/semantic-release-replace-plugin
+// https://github.com/droidsolutions/semantic-release-update-file

package/src/semanticReleaseConfigDotnet.ts

@@ -11,11 +11,11 @@
  *
  */
 
-import { log } from 'node:console';
 import type { Options, PluginSpec } from 'semantic-release';
 import { configureDotnetNugetPush, configurePrepareCmd } from './dotnet/dotnetHelpers.js';
 import { baseConfig, defaultPlugins } from './semanticReleaseConfig.js';
 import { setupGitPluginSpec } from './setupGitPluginSpec.js';
+import debug from './debug.js'
 
 /**
  * TODO: options/params for inserts/edits. NOT ready for production. Currently, this can only add Git plugin's options if undefined or one or more is missing.
@@ -28,24 +28,29 @@ import { setupGitPluginSpec } from './setupGitPluginSpec.js';
  * @returns a modified copy of {@link config}
  */
 export function insertAndEditPlugins(config: Options): Options {
-	const newConfig = config;
 	// const insertAndEditCommands = [];
-	newConfig.plugins = [...(config.plugins ?? defaultPlugins)];
+	config.plugins = [...(config.plugins ?? defaultPlugins)];
 
-	newConfig.plugins = setupGitPluginSpec(newConfig.plugins as PluginSpec[]);
+	config.plugins = setupGitPluginSpec(config.plugins as PluginSpec[]);
 
-	return newConfig;
+	return config;
 }
 
+/**
+ * Currently, only configures `@semantic-release/exec` with `prepareCmd: configurePrepareCmd(projectsToPublish, projectsToPackAndPush)` and `publishCmd: configureDotnetNugetPush()`
+ * @param config 
+ * @param projectsToPublish 
+ * @param projectsToPackAndPush 
+ * @returns config with the specified plugins and plugin options.
+ */
 export function appendPlugins(
 	config: Options,
 	projectsToPublish: string[],
-	projectsToPackAndPush: string[],
-) {
-	const newConfig = config;
-	if (newConfig.plugins === undefined)
+	projectsToPackAndPush: string[] | false,
+): Options {
+	if (config.plugins === undefined)
 		throw new Error('Plugins array was undefined when it should be an array!');
-	(newConfig.plugins as PluginSpec[]).push(
+	(config.plugins as PluginSpec[]).push(
 		// APPEND this array of [pluginName, pluginConfig] to plugins
 		// https://github.com/semantic-release/exec#usage
 		[
@@ -57,27 +62,67 @@ export function appendPlugins(
 			},
 		],
 	);
-	return newConfig;
+	return config;
 }
 
 /**
  * Configures {@link baseConfig} with `@semantic-release/exec` to `dotnet` publish, pack, and push.
- * @param projectsToPublish 
- * @param projectsToPackAndPush 
- * @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 provided projects.
+ * @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
+ * false, `dotnet pack` and `dotnet nuget push` will be left out of the exec
+ * commands. If empty or unspecified, tries getting projects'
+ * semi-colon-separated relative paths from the `PROJECTS_TO_PACK_AND_PUSH`
+ * environment variable. If configured as recommended, `dotnet pack` will output
+ * the nupkg/snupk 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.
  */
-export function getConfig(projectsToPublish: string[], projectsToPackAndPush: string[]): Options {
-	if (process.argv.includes('--debug') || process.argv.includes('--verbose')) {
-		log(`hce.shared-config:\n${JSON.stringify(baseConfig, null, 2)}`);
+export function getConfig(projectsToPublish: string[] = [], projectsToPackAndPush: string[] | false = []): Options {
+	if (debug.enabled) {
+		debug('hce.shared-config:\n%o', baseConfig);
+	}
+
+	const errors: Error[] = [];
+
+	if (projectsToPublish.length === 0) {
+		const _ = process.env["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(';');
 	}
 
-	let newConfig = { ...baseConfig };
-	newConfig = insertAndEditPlugins(newConfig);
-	newConfig = appendPlugins(newConfig, projectsToPublish, projectsToPackAndPush);
+	if (projectsToPackAndPush && projectsToPackAndPush.length) {
+		const _ = process.env["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 (process.argv.includes('--debug') || process.argv.includes('--verbose')) {
-		log(`modified plugins array:\n${JSON.stringify(newConfig.plugins, null, 2)}`);
+	if (errors.length > 0) {
+		throw new Error(
+			[
+				"getConfig cannot continue. One or more errors occurred.",
+				...(errors.map(v => v.message))
+			].join('\n')
+		)
 	}
 
-	return newConfig;
+	let config = { ...baseConfig };
+	config = insertAndEditPlugins(config);
+	if (projectsToPublish)
+		config = appendPlugins(config, projectsToPublish, projectsToPackAndPush);
+
+	if (debug.enabled) {
+		debug('modified plugins array:\n%o', config.plugins);
+	}
+
+	return config;
 }
+
+export default getConfig;

package/src/setupGitPluginSpec.ts

@@ -2,8 +2,9 @@ import type { PluginSpec } from 'semantic-release';
 import type { AssetEntry, Options as GitOptions } from '@semantic-release/git';
 
 export const GitPluginId = '@semantic-release/git';
+/** As specified at https://github.com/semantic-release/git#options */
 export const DefaultOptions = {
-	assets: ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'],
+	assets: ['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'],
 	// eslint-disable-next-line no-template-curly-in-string
 	message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
 } satisfies GitOptions;