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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halospv3/hce.shared-config",
-  "version": "2.6.4",
+  "version": "3.0.0-develop.2",
   "description": "Automate commit message quality, changelogs, and CI/CD releases. Exports a semantic-release shareable configuration deserialized from this package's '.releaserc.yml'. Shared resources for .NET projects are also distributed with this package.",
   "keywords": [
     "halo",
@@ -20,124 +20,123 @@
     "!.husky/",
     "!.vscode/",
     "!_tsout/",
+    "!dotnet/samples/",
     "!tests/",
     "CHANGELOG.md",
-    "cjs/**/*",
     "dotnet/**/*",
     "mjs/**/*",
-    "src/**/*",
-    "static/**/*"
+    "src/**/*"
   ],
-  "main": "./cjs/index.cjs",
+  "main": "./mjs/index.mjs",
   "infra": "polyrepo",
-  "repository": "github:halospv3/hce.shared",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HaloSPV3/HCE.Shared.git"
+  },
   "scripts": {
     "build": "packemon build --addExports --addFiles --declaration --loadConfigs",
+    "build:clean": "npm run clean-build",
     "check": "npm run type && npm run test && npm run lint",
     "clean": "packemon clean",
-    "coverage": "npm run test --coverage",
-    "format": "prettier --write",
+    "clean-build": "npm run clean && npm run build",
+    "coverage": "npm run test -- --experimental-test-coverage",
     "lint": "eslint --cache --fix .",
+    "lint:check": "eslint --cache .",
     "eslint-inspector": "eslint --inspect-config",
     "pack": "packemon pack --addExports --addFiles --declaration --loadConfigs && npm run validate",
     "prepare": "husky",
     "presemantic-release": "npm run pack && npm run check",
-    "semantic-release": "npx semantic-release",
-    "pretest": "npm run build",
-    "test": "tsx --test ./tests/**/*.test.ts",
+    "semantic-release": "semantic-release",
+    "test": "npm run build && npm run test:noBuild",
+    "test:cacheSampleProjects": "echo \"START: Cache Sample Projects\" && tsx ./tests/dotnet/MSBuildProject.projects.ts && echo \"DONE: Cache Sample Projects\"",
+    "pretest:noBuild": "npm run test:cacheSampleProjects",
+    "test:noBuild": "npm run test:justTest",
+    "test:justTest": "tsx --test --experimental-test-coverage --enable-source-maps --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.txt --test-reporter=junit --test-reporter-destination=junit.xml",
+    "test:watch": "npm run test:justTest -- -- --watch",
     "type": "tsc --build",
     "validate": "packemon validate",
-    "watch": "packemon watch"
+    "watch": "packemon watch --loadConfigs"
   },
   "dependencies": {
-    "@commitlint/cli": "^19.3.0",
-    "@commitlint/config-conventional": "^19.2.2",
-    "@commitlint/types": "^19.0.3",
-    "@eslint/js": "^9.3.0",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@dotenvx/dotenvx": "^1.47.6",
+    "@eslint/js": "^9.31.0",
     "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^13.0.0",
-    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^10.0.4",
-    "@semantic-release/npm": "^12.0.0",
-    "@semantic-release/release-notes-generator": "^14.0.0",
-    "@stylistic/eslint-plugin": "^5.0.0",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.12.12",
-    "@types/semantic-release": "^20.0.6",
-    "conventional-changelog-conventionalcommits": "^8.0.0",
-    "debug": "^4.3.4",
-    "eslint-plugin-jsonc": "^2.15.1",
-    "globals": "^15.3.0",
-    "husky": "^9.0.11",
-    "js-yaml": "^4.1.0",
-    "node-fetch": "^3.3.2",
-    "semantic-release": "^24.0.0",
-    "semantic-release-export-data": "^1.0.1",
-    "typescript-eslint": "^8.35.1"
+    "@semantic-release/github": "^11.0.3",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@stylistic/eslint-plugin": "^5.1.0",
+    "@types/node": "~20.11.0",
+    "arktype": "^2.1.20",
+    "chardet": "^2.1.0",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "debug": "^4.4.1",
+    "eslint-plugin-jsonc": "^2.20.1",
+    "globals": "^16.3.0",
+    "husky": "^9.1.7",
+    "sanitize-filename": "^1.6.3",
+    "semantic-release": "^24.2.7",
+    "semantic-release-export-data": "^1.1.0",
+    "ts-essentials": "^10.1.1",
+    "typescript-eslint": "^8.37.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.24.6",
-    "@babel/core": "^7.24.6",
-    "@babel/eslint-parser": "^7.24.6",
-    "@eslint/eslintrc": "^3.1.0",
-    "@tsconfig/node-lts": "^20.1.2",
-    "@types/babel__core": "^7.20.5",
+    "@babel/cli": "^7.28.0",
+    "@babel/core": "^7.28.0",
+    "@babel/eslint-parser": "^7.28.0",
+    "@commitlint/types": "^19.8.1",
+    "@eslint/config-inspector": "^1.1.0",
+    "@eslint/markdown": "^7.0.0",
+    "@semantic-release/gitlab": "^13.2.6",
+    "@tsconfig/node20": "^20.1.6",
     "@types/debug": "^4.1.12",
     "@types/tmp": "^0.2.6",
-    "ajv": "^8.13.0",
-    "ajv-draft-04": "^1.0.0",
-    "dotenv": "^16.4.5",
-    "eslint": "^9.0.0",
-    "node-fetch": "^3.3.2",
-    "packemon": "^4.0.1",
-    "prettier": "^3.2.5",
-    "prettier-config-moon": "^1.1.2",
+    "conventional-changelog-preset-loader": "^5.0.0",
+    "eslint": "^9.31.0",
+    "eslint-plugin-jsdoc": "^51.4.0",
+    "eslint-plugin-unicorn": "^59.0.1",
+    "packemon": "^4.1.2",
     "tmp": "^0.2.3",
-    "tslib": "^2.6.2",
-    "tsx": "^4.10.5",
-    "typescript": "^5.4.5"
+    "tslib": "^2.8.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
   },
   "engines": {
-    "node": ">=20.8.1",
+    "node": "^20.11.0 || >=21.2.0",
     "npm": ">=10.5.0"
   },
   "engineStrict": true,
   "publishConfig": {
-    "tag": "latest"
+    "tag": "latest",
+    "provenance": true
   },
   "exports": {
+    ".": {
+      "types": "./mjs/index.d.ts",
+      "import": "./mjs/index.mjs"
+    },
     "./package.json": "./package.json",
     "./*": {
-      "types": "./cjs/*.d.ts",
-      "default": "./cjs/*.cjs"
-    },
-    "./dotnet/*": {
-      "types": "./cjs/dotnet/*.d.ts",
-      "default": "./cjs/dotnet/*.cjs"
-    },
-    ".": {
-      "types": "./cjs/index.d.ts",
-      "import": "./cjs/index-wrapper.mjs",
-      "default": "./cjs/index.cjs"
+      "types": "./mjs/*.d.ts",
+      "import": "./mjs/*.mjs"
     }
   },
-  "types": "./cjs/index.d.ts",
+  "types": "./mjs/index.d.ts",
   "packemon": {
-    "format": [
-      "cjs"
-    ],
     "platform": "node",
     "inputs": {
+      "CaseInsensitiveMap": "src/CaseInsensitiveMap.ts",
       "commitlintConfig": "src/commitlintConfig.ts",
-      "dotnet": "src/dotnet.ts",
       "eslintConfig": "src/eslintConfig.ts",
-      "envUtils": "src/envUtils.ts",
-      "findStaticConfig": "src/findStaticConfig.ts",
       "index": "src/index.ts",
       "semanticReleaseConfig": "src/semanticReleaseConfig.ts",
       "semanticReleaseConfigDotnet": "src/semanticReleaseConfigDotnet.ts",
       "setupGitPluginSpec": "src/setupGitPluginSpec.ts"
     }
-  }
+  },
+  "packageManager": "pnpm@10.13.1+sha512.37ebf1a5c7a30d5fabe0c5df44ee8da4c965ca0c5af3dbab28c3a1681b70a256218d05c81c9c0dcf767ef6b8551eb5b960042b9ed4300c59242336377e01cfad"
 }

package/src/CaseInsensitiveMap.ts

@@ -0,0 +1,34 @@
+/**
+ * https://stackoverflow.com/a/50022230/14894786
+ * licensed under CC BY-SA 4.0
+ * changes: add overrides, remove "as any", remove empty lines
+ */
+export class CaseInsensitiveMap<T, U> extends Map<T, U> {
+  override delete(key: T): boolean {
+    if (typeof key === 'string') {
+      key = key.toLowerCase() as T;
+    }
+    return super.delete(key);
+  }
+
+  override get(key: T): U | undefined {
+    if (typeof key === 'string') {
+      key = key.toLowerCase() as T;
+    }
+    return super.get(key);
+  }
+
+  override has(key: T): boolean {
+    if (typeof key === 'string') {
+      key = key.toLowerCase() as T;
+    }
+    return super.has(key);
+  }
+
+  override set(key: T, value: U): this {
+    if (typeof key === 'string') {
+      key = key.toLowerCase() as T;
+    }
+    return super.set(key, value);
+  }
+}

package/src/commitlintConfig.ts

@@ -1,14 +1,22 @@
-import { type RuleConfigSeverity, type UserConfig } from '@commitlint/types';
+import type { RuleConfigSeverity, UserConfig } from '@commitlint/types';
+
+// explicit type annotations for isolatedDeclarations. Allows for faster processing.
 
-// CJS compatibility; This enum cannot be required.
 const disabled = 0 as RuleConfigSeverity.Disabled;
-const commitlintConfig: UserConfig = {
-	extends: ['@commitlint/config-conventional'],
-	rules: {
-		'body-max-line-length': [disabled],
-		'footer-max-line-length': [disabled],
-		'header-max-length': [disabled],
-	},
+const commitlintConfig: UserConfig & {
+  extends: UserConfig['extends'] | ['@commitlint/config-conventional'];
+  rules: {
+    'body-max-line-length': [typeof disabled];
+    'footer-max-line-length': [typeof disabled];
+    'header-max-length': [typeof disabled];
+  };
+} = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'body-max-line-length': [disabled],
+    'footer-max-line-length': [disabled],
+    'header-max-length': [disabled],
+  },
 };
 
 // only `default` export is loaded via `extends` config key!

package/src/debug.ts

@@ -2,8 +2,8 @@ import debug from 'debug';
 
 const _debug = debug('@halospv3/hce.shared-config');
 
-if (process.argv.some(v => v.includes('--debug')) || debug.enabled('*')) {
-    debug.enable(_debug.namespace);
+if (process.argv.some(v => v.includes('--debug')) || debug.enabled('@halospv3/hce.shared-config')) {
+  debug.enable(_debug.namespace);
 }
 
-export default _debug;
+export default _debug;

package/src/dotnet/GithubNugetRegistryInfo.ts

@@ -0,0 +1,60 @@
+import { getEnvVarValue } from '../utils/env.js';
+import {
+  NugetRegistryInfo,
+  NRIOptsBase,
+} from './NugetRegistryInfo.js';
+
+const NUGET_PKG_GITHUB_COM = 'https://nuget.pkg.github.com';
+const DefaultGithubTokenEnvVars = Object.freeze([
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+] as const);
+
+export class GithubNugetRegistryInfo extends NugetRegistryInfo {
+  static readonly NUGET_PKG_GITHUB_COM = 'https://nuget.pkg.github.com';
+  // todo: deduplicate definition
+  static readonly DefaultGithubTokenEnvVars = Object.freeze([
+    'GH_TOKEN',
+    'GITHUB_TOKEN',
+  ] as const);
+
+  // GithubNugetRegistryInfo.CtorArgs(...) behaves differently than NugetRegistryInfo.CtorArgs(...)
+  /**
+   * Creates an instance of GithubNugetRegistryInfo.
+   * @param opts The input type of {@link GHNRIOpts.from}
+   */
+  constructor(opts: typeof GHNRIOpts.inferIn) {
+    super(GHNRIOpts.from(opts));
+  }
+
+  /**
+   * Returns `https://nuget.pkg.github.com/${GITHUB_REPOSITORY_OWNER}/index.json`
+   * or (if GITHUB_REPOSITORY_OWNER is not defined in {@link process.env} nor
+   * {@link process.cwd() $CWD}/.env) `undefined`.
+   * @returns If GITHUB_REPOSITORY_OWNER is defined, returns the GitHub Package Repository URL endpoint for NuGet pushes (--source).\
+   * Otherwise, returns `undefined`
+   */
+  static getNugetGitHubUrl(): string | undefined {
+    const owner = getEnvVarValue('GITHUB_REPOSITORY_OWNER');
+    return owner === undefined
+      ? undefined
+      : `${NUGET_PKG_GITHUB_COM}/${owner}/index.json`;
+  }
+}
+const GHNRI = GithubNugetRegistryInfo;
+
+/**
+ * The default value of {@link GHNRIOpts.t.source `source`} is dependent on
+ * {@link GHNRI.getNugetGitHubUrl} and will default to an empty string if the
+ * environment variable `GITHUB_REPOSITORY_OWNER` is undefined!
+ */
+export const GHNRIOpts = NRIOptsBase.merge({
+  /** @see {@link GHNRI.getNugetGitHubUrl } */
+  source: NRIOptsBase.get('source')
+    .default(() => GHNRI.getNugetGitHubUrl() ?? ''),
+  tokenEnvVars: NRIOptsBase.get('tokenEnvVars')
+    .default(
+      /* must be a function. A fixed-length array is NOT a primitive type! */
+      () => DefaultGithubTokenEnvVars,
+    ),
+});

package/src/dotnet/GitlabNugetRegistryInfo.ts

@@ -0,0 +1,112 @@
+import { isNativeError } from 'node:util/types';
+import { getEnvVarValue } from '../utils/env.js';
+import {
+  NugetRegistryInfo,
+  NRIOpts,
+  NRIOptsBase,
+} from './NugetRegistryInfo.js';
+
+// https://docs.gitlab.com/ee/user/packages/nuget_repository/
+export class GitlabNugetRegistryInfo extends NugetRegistryInfo {
+  /**
+   * The GitLab API v4 root URL.
+   * @returns The value of the environment variable `CI_API_V4_URL`.
+   * If that's `undefined`, 'https://gitlab.com/api/v4' is returned, instead.
+   */
+  static get CI_API_V4_URL() {
+    return getEnvVarValue('CI_API_V4_URL') ?? 'https://gitlab.com/api/v4';
+  }
+
+  /**
+   * CI_PROJECT_ID - If you want to publish to your GitLab server, this needs to be set to the Id of the project you want to publish to. When running in GitLab CI this is already set to the project the pipeline runs in by GitLab.
+   * This method checks the contents of your `.env` file, if present.
+   * @returns The value of the environment variable `CI_PROJECT_ID` or `undefined`.
+   * @todo add URI encoded project pathname as alternative e.g. 'halospv3%2FHCE.Shared' in 'https://gitlab.com/api/v4/projects/halospv3%2FHCE.Shared'
+   */
+  static get projectId() {
+    return getEnvVarValue('CI_PROJECT_ID');
+  }
+
+  /**
+   * CI_PROJECT_NAMESPACE_ID
+   * This method checks the contents of your `.env` file, if present.
+   * @returns The value of the environment variable 'CI_PROJECT_NAMESPACE_ID' or `undefined`.
+   */
+  static get ownerId() {
+    return getEnvVarValue('CI_PROJECT_NAMESPACE_ID');
+  }
+
+  static readonly DefaultGitlabTokenEnvVars = Object.freeze([
+    'GL_TOKEN',
+    'GITLAB_TOKEN',
+    'CI_JOB_TOKEN',
+  ] as const);
+
+  /**
+   * Creates an instance of GitlabNugetRegistryInfo.
+   * @param opts The input type of {@link GLNRIOpts.from}
+   */
+  constructor(opts: typeof GLNRIOpts.inferIn) {
+    const optsOut = GLNRIOpts.from(opts);
+    if (isNativeError(optsOut.source))
+      throw optsOut.source;
+    super(optsOut as typeof optsOut & { source: string });
+  }
+
+  /**
+   * Get the GitLab Nuget API for your project url as seen in https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html#publish-a-nuget-package-by-using-cicd
+   * ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json
+   * @returns If {@link this.projectId} is a string, a string formatted like
+   * `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json`.
+   * Else, {@link Error}.
+   */
+  static get projectUrl(): string | Error {
+    return this.projectId
+      ? `${this.CI_API_V4_URL}/projects/${this.projectId}/packages/nuget/index.json`
+      : new Error('The project-type URL was specified, but one or more of the required environment variables (CI_API_V4_URL, CI_PROJECT_ID) were undefined.');
+  }
+
+  /**
+   * ${CI_API_V4_URL}/groups/${CI_PROJECT_NAMESPACE_ID}/-/packages/nuget/index.json
+   * @returns If {@link ownerId} is a string, then a string formatted like
+   * `${CI_API_V4_URL}/groups/${CI_PROJECT_NAMESPACE_ID}/-/packages/nuget/index.json`.
+   * Else, {@link Error}.
+   */
+  static get groupUrl(): string | Error {
+    return this.ownerId
+      ? `${this.CI_API_V4_URL}/groups/${this.ownerId}/-/packages/nuget/index.json`
+      : new Error('env.CI_PROJECT_NAMESPACE_ID must be defined to use its GitLab API endpoint!');
+  }
+}
+const GLNRI = GitlabNugetRegistryInfo;
+
+/**
+ * The Arktype definition for {@link GitlabNugetRegistryInfo}'s constructor parameter. Construct an object of this type by calling {@link GLNRIOpts.from}
+ */
+export const GLNRIOpts = NRIOpts.merge({
+  tokenEnvVars: NRIOptsBase.get('tokenEnvVars').default(
+    () => GLNRI.DefaultGitlabTokenEnvVars,
+  ),
+  /**
+   * The GitLab Nuget API URL to push packages to -OR- a keyword such as "group"
+   * or "project" used to determine URL.
+   * @default GLNRI.projectUrl
+   * @see {@link GLNRI.projectUrl}, {@link GLNRI.groupUrl}
+   */
+  // todo: change '"group" | "project"' to '"GITLAB:PROJECT" | "GITLAB:GROUP"'
+  source: NRIOptsBase.get('source')
+    .or('"group" | "project" | Error')
+    .pipe((source: string | Error): string | Error => {
+      switch (source) {
+        case 'group': {
+          return GLNRI.groupUrl;
+        }
+        case 'project': {
+          return GLNRI.projectUrl;
+        }
+        default: {
+          return source;
+        }
+      }
+    }).default(() => GLNRI.projectUrl),
+});

package/src/dotnet/IsNextVersionAlreadyPublished.cli.ts

@@ -0,0 +1,44 @@
+import { NugetRegistryInfo, getGithubOutput } from './NugetRegistryInfo.js';
+
+const args = process.argv.slice(2);
+
+// Parse command-line arguments - https://stackoverflow.com/a/76298476/14894786
+const options: {
+  packageId?: string;
+  source?: string;
+} & Record<string, string> = {};
+for (let i = 0; i < args.length; i += 2) {
+  const argName = args[i];
+  const argValue = args[i + 1];
+  if (argValue !== undefined && argName?.startsWith('--') === true && options[argName.slice(2)] !== undefined) {
+    options[argName.slice(2)] = argValue;
+  }
+}
+
+if (typeof options.packageId !== 'string')
+  throw new Error('packageId must be a string');
+if (typeof options.source !== 'string')
+  throw new Error('source must be a string');
+
+const packageId = options.packageId,
+  source = options.source,
+  versionPattern = new RegExp(/\d+\.\d+\.\d+([-+].+)?/);
+const ghOutput = await getGithubOutput() ?? {};
+const matches = versionPattern.exec(ghOutput['new-release-version'] ?? '');
+if (matches === null || matches.length === 0)
+  throw new Error(
+    'The variable new-release-version is not present in the GITHUB_OUTPUT env file or its value contains invalid characters.',
+  );
+
+const nextVersion = matches[0];
+const isPublished = await NugetRegistryInfo.IsNextVersionAlreadyPublished(
+  source,
+  packageId,
+  nextVersion,
+);
+
+if (typeof isPublished !== 'boolean')
+  throw new Error('isPublished is not a boolean');
+if (isPublished)
+  throw new Error(`${packageId}@${nextVersion} already exists at ${source}.`);
+console.log(`OK: ${packageId}@${nextVersion} does NOT yet exist at ${source}. Yay.`);