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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halospv3/hce.shared-config",
-  "version": "3.0.0-develop.2",
+  "version": "3.0.0-develop.21",
   "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",
@@ -23,9 +23,11 @@
     "!dotnet/samples/",
     "!tests/",
     "CHANGELOG.md",
-    "dotnet/**/*",
+    "dotnet/*",
+    "dotnet/.github/**/*",
     "mjs/**/*",
-    "src/**/*"
+    "src/**/*",
+    "tsconfig*.json"
   ],
   "main": "./mjs/index.mjs",
   "infra": "polyrepo",
@@ -43,16 +45,15 @@
     "lint": "eslint --cache --fix .",
     "lint:check": "eslint --cache .",
     "eslint-inspector": "eslint --inspect-config",
-    "pack": "packemon pack --addExports --addFiles --declaration --loadConfigs && npm run validate",
+    "prepack": "packemon pack --addExports --addFiles --declaration --loadConfigs",
+    "pack": "echo 'You should use `npm pack`' && exit 1",
     "prepare": "husky",
-    "presemantic-release": "npm run pack && npm run check",
+    "presemantic-release": "npm pack",
     "semantic-release": "semantic-release",
-    "test": "npm run build && npm run test:noBuild",
+    "pretest": "npm run build && npm run test:cacheSampleProjects",
+    "test": "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: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",
+    "test:watch": "npm run test -- --watch",
     "type": "tsc --build",
     "validate": "packemon validate",
     "watch": "packemon watch --loadConfigs"
@@ -75,6 +76,7 @@
     "chardet": "^2.1.0",
     "conventional-changelog-conventionalcommits": "^9.1.0",
     "debug": "^4.4.1",
+    "es-main": "^1.3.0",
     "eslint-plugin-jsonc": "^2.20.1",
     "globals": "^16.3.0",
     "husky": "^9.1.7",
@@ -85,20 +87,22 @@
     "typescript-eslint": "^8.37.0"
   },
   "devDependencies": {
+    "@amanda-mitchell/semantic-release-npm-multiple": "^3.16.0",
     "@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",
+    "@sebbo2002/semantic-release-jsr": "^3.0.0",
     "@semantic-release/gitlab": "^13.2.6",
     "@tsconfig/node20": "^20.1.6",
     "@types/debug": "^4.1.12",
     "@types/tmp": "^0.2.6",
     "conventional-changelog-preset-loader": "^5.0.0",
     "eslint": "^9.31.0",
-    "eslint-plugin-jsdoc": "^51.4.0",
-    "eslint-plugin-unicorn": "^59.0.1",
+    "eslint-plugin-jsdoc": "^54.0.0",
+    "eslint-plugin-unicorn": "^60.0.0",
     "packemon": "^4.1.2",
     "tmp": "^0.2.3",
     "tslib": "^2.8.1",
@@ -110,10 +114,6 @@
     "npm": ">=10.5.0"
   },
   "engineStrict": true,
-  "publishConfig": {
-    "tag": "latest",
-    "provenance": true
-  },
   "exports": {
     ".": {
       "types": "./mjs/index.d.ts",
@@ -138,5 +138,5 @@
       "setupGitPluginSpec": "src/setupGitPluginSpec.ts"
     }
   },
-  "packageManager": "pnpm@10.13.1+sha512.37ebf1a5c7a30d5fabe0c5df44ee8da4c965ca0c5af3dbab28c3a1681b70a256218d05c81c9c0dcf767ef6b8551eb5b960042b9ed4300c59242336377e01cfad"
+  "packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748"
 }

package/src/debug.ts

@@ -1,9 +1,10 @@
-import debug from 'debug';
+// note: @types/debug is incorrect. There is no .log function!
+import createDebugger, { type Debugger } from 'debug';
 
-const _debug = debug('@halospv3/hce.shared-config');
+const _debug = createDebugger('@halospv3/hce.shared-config') as Debugger & { log: never };
 
-if (process.argv.some(v => v.includes('--debug')) || debug.enabled('@halospv3/hce.shared-config')) {
-  debug.enable(_debug.namespace);
+if (process.argv.some(v => v.includes('--debug')) || createDebugger.enabled('@halospv3/hce.shared-config')) {
+  createDebugger.enable(_debug.namespace);
 }
 
 export default _debug;

package/src/dotnet/GithubNugetRegistryInfo.ts

@@ -1,22 +1,21 @@
+import type { Type } from 'arktype';
 import { getEnvVarValue } from '../utils/env.js';
+import type { MSBuildProject, MSBuildEvaluationOutput } from './MSBuildProject.js';
+import type { NugetProjectProperties } from './NugetProjectProperties.js';
 import {
   NugetRegistryInfo,
   NRIOptsBase,
 } from './NugetRegistryInfo.js';
+import type { Default } from 'arktype/internal/attributes.ts';
 
 const NUGET_PKG_GITHUB_COM = 'https://nuget.pkg.github.com';
-const DefaultGithubTokenEnvVars = Object.freeze([
+export const DefaultGithubTokenEnvVars: readonly ['GH_TOKEN', 'GITHUB_TOKEN'] = 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(...)
   /**
@@ -48,13 +47,22 @@ const GHNRI = GithubNugetRegistryInfo;
  * {@link GHNRI.getNugetGitHubUrl} and will default to an empty string if the
  * environment variable `GITHUB_REPOSITORY_OWNER` is undefined!
  */
-export const GHNRIOpts = NRIOptsBase.merge({
+export const GHNRIOpts: Type<{
+  project: MSBuildProject | {
+    readonly Items: Readonly<Required<MSBuildEvaluationOutput>['Items']>;
+    readonly Properties: Readonly<NugetProjectProperties>;
+    readonly Targets: readonly string[];
+    readonly TargetResults: Required<MSBuildEvaluationOutput>['TargetResults'][];
+  };
+  source: Default<string, string>;
+  tokenEnvVars: Default<readonly string[], readonly ['GH_TOKEN', 'GITHUB_TOKEN']>;
+}> = 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,
+      (): typeof DefaultGithubTokenEnvVars => DefaultGithubTokenEnvVars,
     ),
 });

package/src/dotnet/GitlabNugetRegistryInfo.ts

@@ -5,6 +5,11 @@ import {
   NRIOpts,
   NRIOptsBase,
 } from './NugetRegistryInfo.js';
+import type { Out } from 'arktype';
+import type { Default } from 'arktype/internal/attributes.ts';
+import type { ObjectType } from 'arktype/internal/methods/object.ts';
+import type { MSBuildProject, MSBuildEvaluationOutput } from './MSBuildProject.js';
+import type { NugetProjectProperties } from './NugetProjectProperties.js';
 
 // https://docs.gitlab.com/ee/user/packages/nuget_repository/
 export class GitlabNugetRegistryInfo extends NugetRegistryInfo {
@@ -13,7 +18,7 @@ export class GitlabNugetRegistryInfo extends NugetRegistryInfo {
    * @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() {
+  static get CI_API_V4_URL(): string {
     return getEnvVarValue('CI_API_V4_URL') ?? 'https://gitlab.com/api/v4';
   }
 
@@ -23,7 +28,7 @@ export class GitlabNugetRegistryInfo extends NugetRegistryInfo {
    * @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() {
+  static get projectId(): string | undefined {
     return getEnvVarValue('CI_PROJECT_ID');
   }
 
@@ -32,11 +37,11 @@ export class GitlabNugetRegistryInfo extends NugetRegistryInfo {
    * 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() {
+  static get ownerId(): string | undefined {
     return getEnvVarValue('CI_PROJECT_NAMESPACE_ID');
   }
 
-  static readonly DefaultGitlabTokenEnvVars = Object.freeze([
+  static readonly DefaultGitlabTokenEnvVars: readonly ['GL_TOKEN', 'GITLAB_TOKEN', 'CI_JOB_TOKEN'] = Object.freeze([
     'GL_TOKEN',
     'GITLAB_TOKEN',
     'CI_JOB_TOKEN',
@@ -83,7 +88,16 @@ 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({
+export const GLNRIOpts: ObjectType<{
+  project: MSBuildProject | {
+    readonly Items: Readonly<Required<MSBuildEvaluationOutput>['Items']>;
+    readonly Properties: Readonly<NugetProjectProperties>;
+    readonly Targets: readonly string[];
+    readonly TargetResults: Required<MSBuildEvaluationOutput>['TargetResults'][];
+  };
+  tokenEnvVars: Default<readonly string[], readonly ['GL_TOKEN', 'GITLAB_TOKEN', 'CI_JOB_TOKEN']>;
+  source: (In: Default<string | Error, string | Error>) => Out<string | Error>;
+}> = NRIOpts.merge({
   tokenEnvVars: NRIOptsBase.get('tokenEnvVars').default(
     () => GLNRI.DefaultGitlabTokenEnvVars,
   ),

package/src/dotnet/IsNextVersionAlreadyPublished.cli.ts

@@ -1,44 +1,61 @@
 import { NugetRegistryInfo, getGithubOutput } from './NugetRegistryInfo.js';
+import esMain from 'es-main';
 
-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;
+/**
+ * @returns if successful
+ * @throws if...
+ * - {@link process.argv} does not include...
+ *   - `--packageId [string]`
+ *   - `--source [string]`
+ * - Value of `await getGithubOutput())['new-release-version']`...
+ *   - is not a valid Version
+ *   - already exists at `source`
+ */
+async function main(): Promise<0> {
+  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] = 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');
+  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 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,
   );
 
-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.`);
+
+  return 0;
+}
 
-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.`);
+if (esMain(import.meta))
+  await main();

package/src/dotnet/MSBuildProject.ts

@@ -1,4 +1,4 @@
-import { type } from 'arktype';
+import { type, type Scope } from 'arktype';
 import { warn } from 'node:console';
 import { type Dirent } from 'node:fs';
 import { readdir, realpath, stat } from 'node:fs/promises';
@@ -12,6 +12,7 @@ import {
   NPPGetterNames,
   NugetProjectProperties,
 } from './NugetProjectProperties.js';
+import type { ObjectType } from 'arktype/internal/methods/object.ts';
 
 /**
  * See [MSBuild well-known item metadata](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-well-known-item-metadata).
@@ -72,7 +73,65 @@ const targetFailure = type({
   Items: 'never[]',
 });
 
-const msbuildEvaluationOutput = type({
+const msbuildEvaluationOutput: ObjectType<{
+  Properties?: Record<string, string> | undefined;
+  Items?: Record<string, {
+    [x: string]: string | undefined;
+    Identity: string;
+    FullPath: string;
+    RootDir: string;
+    Filename: string;
+    Extension: string;
+    RelativeDir: string;
+    Directory: string;
+    RecursiveDir: string;
+    ModifiedTime: string;
+    CreatedTime: string;
+    AccessedTime: string;
+    DefiningProjectFullPath: string;
+    DefiningProjectDirectory: string;
+    DefiningProjectName: string;
+    DefiningProjectExtension: string;
+    SubType?: string;
+    TargetFrameworkIdentifier?: string | undefined;
+    TargetPlatformMoniker?: string | undefined;
+    CopyUpToDateMarker?: string | undefined;
+    TargetPlatformIdentifier?: string | undefined;
+    TargetFrameworkVersion?: string | undefined;
+    ReferenceAssembly?: string | undefined;
+  }[]> | undefined;
+  TargetResults?: Record<string, {
+    Result: 'Success';
+    Items: {
+      [x: string]: string | undefined;
+      Identity: string;
+      FullPath: string;
+      RootDir: string;
+      Filename: string;
+      Extension: string;
+      RelativeDir: string;
+      Directory: string;
+      RecursiveDir: string;
+      ModifiedTime: string;
+      CreatedTime: string;
+      AccessedTime: string;
+      DefiningProjectFullPath: string;
+      DefiningProjectDirectory: string;
+      DefiningProjectName: string;
+      DefiningProjectExtension: string;
+      SubType?: string | undefined;
+      TargetFrameworkIdentifier?: string | undefined;
+      TargetPlatformMoniker?: string | undefined;
+      CopyUpToDateMarker?: string | undefined;
+      TargetPlatformIdentifier?: string | undefined;
+      TargetFrameworkVersion?: string | undefined;
+      ReferenceAssembly?: string | undefined;
+    }[];
+  } | {
+    Result: 'Failure';
+    Items: never[];
+  }> | undefined;
+}> = type({
   'Properties?': type({ '[string]': 'string' }),
   'Items?': type({ '[string]': interface_ItemMetadataBuiltIn.array() }),
   'TargetResults?': type({ '[string]': targetSuccess.or(targetFailure) }),
@@ -111,7 +170,30 @@ export class MSBuildEvaluationOutput {
   TargetResults?: typeof msbuildEvaluationOutput.infer.TargetResults;
 }
 
-export const EvaluationOptions = Object.freeze(
+export const EvaluationOptions: ObjectType<{
+  FullName: string;
+  Property: {
+    MSBuildProjectFullPath?: string | undefined;
+    AssemblyName?: string | undefined;
+    BaseIntermediateOutputPath?: string | undefined;
+    BaseOutputPath?: string | undefined;
+    Description?: string | undefined;
+    IntermediateOutput?: string | undefined;
+    OutDir?: string | undefined;
+    OutputPath?: string | undefined;
+    Version?: string | undefined;
+    VersionPrefix?: string | undefined;
+    VersionSuffix?: string | undefined;
+    TargetFramework?: string | undefined;
+    TargetFrameworks?: string | undefined;
+    RuntimeIdentifier?: string | undefined;
+    RuntimeIdentifiers?: string | undefined;
+  };
+  Targets: readonly string[] | string[];
+  GetItem: readonly string[] | string[];
+  GetProperty: readonly string[] | string[];
+  GetTargetResult: readonly string[] | string[];
+}> = Object.freeze(
   type({
     /**
      * The project file's full path.
@@ -508,8 +590,71 @@ const T_PseudoMSBPInstance = type({
 
 });
 
-/** ArkType type definitions for internal usage, but may be re-used elsewhere */
-export const _InternalMSBuildEvaluationTypes = type.scope({
+/**
+ * ArkType type definitions for internal usage, but may be re-used elsewhere
+ * @internal
+ */
+export const _InternalMSBuildEvaluationTypes: Scope<{
+  msbuildEvaluationOutput: {
+    Properties?: Record<string, string> | undefined;
+    Items?: Record<string, {
+      [x: string]: string | undefined;
+      Identity: string;
+      FullPath: string;
+      RootDir: string;
+      Filename: string;
+      Extension: string;
+      RelativeDir: string;
+      Directory: string;
+      RecursiveDir: string;
+      ModifiedTime: string;
+      CreatedTime: string;
+      AccessedTime: string;
+      DefiningProjectFullPath: string;
+      DefiningProjectDirectory: string;
+      DefiningProjectName: string;
+      DefiningProjectExtension: string;
+      SubType?: string | undefined;
+      TargetFrameworkIdentifier?: string | undefined;
+      TargetPlatformMoniker?: string | undefined;
+      CopyUpToDateMarker?: string | undefined;
+      TargetPlatformIdentifier?: string | undefined;
+      TargetFrameworkVersion?: string | undefined;
+      ReferenceAssembly?: string | undefined;
+    }[]> | undefined;
+    TargetResults?: Record<string, {
+      Result: 'Success';
+      Items: {
+        [x: string]: string | undefined;
+        Identity: string;
+        FullPath: string;
+        RootDir: string;
+        Filename: string;
+        Extension: string;
+        RelativeDir: string;
+        Directory: string;
+        RecursiveDir: string;
+        ModifiedTime: string;
+        CreatedTime: string;
+        AccessedTime: string;
+        DefiningProjectFullPath: string;
+        DefiningProjectDirectory: string;
+        DefiningProjectName: string;
+        DefiningProjectExtension: string;
+        SubType?: string | undefined;
+        TargetFrameworkIdentifier?: string | undefined;
+        TargetPlatformMoniker?: string | undefined;
+        CopyUpToDateMarker?: string | undefined;
+        TargetPlatformIdentifier?: string | undefined;
+        TargetFrameworkVersion?: string | undefined;
+        ReferenceAssembly?: string | undefined;
+      }[];
+    } | {
+      Result: 'Failure';
+      Items: never[];
+    }> | undefined;
+  };
+}> = type.scope({
   msbuildEvaluationOutput,
 });
 

package/src/dotnet/MSBuildProjectProperties.ts

@@ -23,8 +23,9 @@ export class MSBuildProjectProperties {
    * Resolve the given path if it is not absolute. If the path exists, it is returned. Else, an Error is thrown.
    * @param path The full file path of an MSBuild project.
    * @returns The absolute path to the MSBuild project file.
+   * @throws {Error} if the path cannot be resolved to an existing file.
    */
-  static GetFullPath(path: string) {
+  static GetFullPath(path: string): string {
     if (!node_path.isAbsolute(path))
       path = node_path.resolve(path);
     if (!existsSync(path))

package/src/dotnet/NugetProjectProperties.ts

@@ -14,9 +14,10 @@ import {
   type WithProto,
 } from '../utils/reflection.js';
 import { MSBuildProjectProperties, type Class_MSBPP } from './MSBuildProjectProperties.js';
+import type { StringType } from 'arktype/internal/methods/string.ts';
 
-const Type_RepositoryType = type('""|"git"|"tfs"');
-const Type_SymbolPackageFormat = type('"symbols.nupkg" | "snupkg"');
+const Type_RepositoryType: StringType<'' | 'git' | 'tfs'> = type('""|"git"|"tfs"');
+const Type_SymbolPackageFormat: StringType<'symbols.nupkg' | 'snupkg'> = type('"symbols.nupkg" | "snupkg"');
 
 /**
  * A readonly record of a .csproj or .fsproj with NuGet configuration properties in