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

package/README.md

@@ -1,14 +1,11 @@
 # HCE.Shared
 
-## NOTICE
-
-> Activity is held up by a rewrite for the `next/3.0.0` branch.
->
-> A fix for the `2.x` branch may be feasible if all that's wrong is async functions in CJS. The `2.x` release channel will not receive feature updates, but fixes and dependency updates are acceptable.
+[![.github/workflows/npm-release.yml](https://github.com/HaloSPV3/HCE.Shared/actions/workflows/npm-release.yml/badge.svg?branch=next%2F3.x&event=push)](https://github.com/HaloSPV3/HCE.Shared/actions/workflows/npm-release.yml)
 
 Infrastructure resources shared with other HaloSPV3 repositories.
 
-It is recommended to "install" this repo via [Node Package Manager](#npm)
+**NOTE**
+HCE.Shared's API offers convenience and flexibility not present in similar .NET/NuGet-publishing NPM packages, but this project is incredibly messy. You'll find many traces of scrapped or unfinished ideas in the form of both documentation and code. These wrinkles will be ironed out before `3.x` is merged into `main`.
 
 ## Usage
 
@@ -26,7 +23,7 @@ WARNING! Defining a property will _overwrite_ the previous value. Arrays and
 objects are _not_ merged. You can...
 
 - Assign to certain top-level variables (e.g. `options.preset`) to avoid
-  modifying the plugins array. Caveat: only *some* plugins read these properties.
+  modifying the plugins array. Caveat: only _some_ plugins read these properties.
 - Write your config in MJS; It is recommended you use
   [deepmerge](https://www.npmjs.com/package/deepmerge) to recursively merge
   objects and arrays instead of using `extends`. Doing so will allow your IDE to
@@ -41,11 +38,11 @@ objects are _not_ merged. You can...
 > - Configures [`@semantic-release/git`](https://github.com/semantic-release/git) to add README.md and CHANGELOG.md in a release commit if they have changes. Uses GitHub job's token to commit.
 > - Configures [`@semantic-release/github`](https://github.com/semantic-release/github) to release all files found in `$PWD/publish`.
 
-##### Usage
+##### Base Config - Usage
 
 ```js
 // releaserc.config.js
-import hceSharedConfig from "@halospv3/hce.shared-config"
+import hceSharedConfig from '@halospv3/hce.shared-config';
 
 // modify it however you wish before the export statement!
 
@@ -55,55 +52,62 @@ export default hceSharedConfig;
 ```js
 // releaserc.config.js
 export default {
-	extends: ["@halospv3/hce.shared-config"]
-}
+  extends: ['@halospv3/hce.shared-config'],
+};
 ```
 
 ```json
 // package.json
 {
-	"release": {
-		"extends": ["@halospv3/hce.shared-config"]
-	}
+  "release": {
+    "extends": ["@halospv3/hce.shared-config"]
+  }
 }
 ```
 
 #### Dotnet Config
 
 > An extension of our base config.
+>
 > Exports a function with parameters for 'projects to pack' and 'projects to push (to nuget)'.
 > Although `@halospv3/hce.shared-config/semanticReleaseConfigDotnet` can be used
-  via `extends` and configured via the `PROJECTS_TO_PUBLISH` and
-  `PROJECTS_TO_PACK_AND_PUSH` environment variables, it is recommended to call
-  the function and pass it parameters so errors are caught before they reach
-  production.
+> via `extends` and configured via the `PROJECTS_TO_PUBLISH` and
+> `PROJECTS_TO_PACK_AND_PUSH` environment variables, it is recommended to call
+> the function and pass it parameters so errors are caught before they reach
+> production.
 >
 > Differences to the base config:
+>
 > - Utilizes `@semantic-release/exec` for shell commands.
 >   - Executes `dotnet publish` and `dotnet pack` upon the configured projects during the `prepare` step.
 >   - (WIP) Executes `dotnet nuget sign` during `prepare` upon the `dotnet pack` outputs if `projectsToPackAndPush` is not set to `false` (default: `[]`).
 >   - Executes `dotnet nuget push` during the `publish` step.
 
-##### Usage
+##### Dotnet Config - Usage
 
-```js
+TODO: add "non-best-guess" config example
+
+For a basic "best-guess" config...
+
+```ts
 // releaserc.config.js
-import { getConfig } from "@halospv3/hce.shared-config/semanticReleaseConfigDotnet"
+// TODO: getConfig was removed. Update instructions!
+import { getConfig } from '@halospv3/hce.shared-config/semanticReleaseConfigDotnet';
 
 /* Caveat: semantic-release will version and release all specified projects under the same Git tags and GitHub releases.
  * To version and release them separately, use [https://github.com/pmowrer/semantic-release-monorepo](semantic-release-monorepo).
  */
 
-/* `prepareCmd` will contain command lines to publish 
+/* `prepareCmd` will contain command lines to publish
  * both Library and Sample to your GitHub release.
  * Their `TargetFrameworks` and `RuntimeIdentifiers`
- * properties will be evaluated and a command line 
- * will be added for each unique combination, 
+ * properties will be evaluated and a command line
+ * will be added for each unique combination,
  * _regardless of compatibility and intended combinations_.
  */
 const projectsToPublish = [
-	"./Library/Library.csproj",
-	"./Sample/Sample.csproj"
+  './Library/Library.csproj',
+  './Sample/Sample.csproj',
 ];
 /*
  * `prepareCmd` will also contain `dotnet pack` and
@@ -111,28 +115,29 @@ const projectsToPublish = [
  * `publishCmd` will contain `dotnet nuget push` commands
  *  to push Library to Nuget.org and GitHub Package Registry.
  */
-const projectsToPackAndPush = ["./Library/Library.csproj"];
+const projectsToPackAndPush = ['./Library/Library.csproj'];
 
 // runs getConfig and exports its return value
-export default getConfig(projectsToPublish, projectsToPackAndPush)
+export default await getConfig(projectsToPublish, projectsToPackAndPush);
 ```
 
 ###### `extends` key in a javascript config file
 
 Using `extends` is NOT recommended, but I won't stop you.
 Your projects' paths must be assigned to environment variables. See [Dotnet Config](#dotnet-config).
+
 ```js
 // releaserc.config.js (if {"type": "module"} in package.json)
 export default {
-	extends: ["@halospv3/hce.shared-config"]
-}
+  extends: ['@halospv3/hce.shared-config'],
+};
 ```
 
 ```js
 // releaserc.config.js (if {"type": "commonjs"} in package.json)
 module.exports = {
-	extends: ["@halospv3/hce.shared-config"]
-}
+  extends: ['@halospv3/hce.shared-config'],
+};
 ```
 
 ###### `release` key in package.json
@@ -141,47 +146,49 @@ module.exports = {
 // package.json
 // `npm install --save-dev cross-env`
 {
-	"scripts":{
-		"release":"cross-env PROJECTS_TO_PUBLISH=\"./Library/Library.csproj;./Sample/Sample.csproj\" semantic-release"
-	},
-	"release": {
-		"extends": ["@halospv3/hce.shared-config/semanticReleaseConfigDotnet"]
-	}
+  "scripts": {
+    "release": "cross-env PROJECTS_TO_PUBLISH=\"./Library/Library.csproj;./Sample/Sample.csproj\" semantic-release"
+  },
+  "release": {
+    "extends": ["@halospv3/hce.shared-config/semanticReleaseConfigDotnet"]
+  }
 }
 ```
 
 ---
 
-**Notable Plugin Properties**
+#### Notable Plugin Properties
 
 - [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer#options)
-	- preset (set to `conventionalcommits`)
-	- parserOpts
-	- releaseRules
+  - preset (set to `conventionalcommits`)
+  - parserOpts
+  - releaseRules
 - [`@semantic-release/release-notes-generator`](https://github.com/semantic-release/release-notes-generator#options)
-	- preset (set to `conventionalcommits`)
-	- parserOpts
-	- writerOpts
+  - preset (set to `conventionalcommits`)
+  - parserOpts
+  - writerOpts
 - [`@semantic-release/changelog`](https://github.com/semantic-release/changelog#options)
-	- changelogFile (default: `'CHANGELOG.md'`)
+  - changelogFile (default: `'CHANGELOG.md'`)
 - [`@semantic-release/git`](https://github.com/semantic-release/git#options)
-	- assets (default: `['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']`)
+  - assets (default:
+    `['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']`)
 - `@semantic-release/exec`
-	- prepareCmd
+  - prepareCmd
 - [`@semantic-release/github`](https://github.com/semantic-release/github#options)
-	- assets
-	- draftRelease (default: false)
+  - assets
+  - draftRelease (default: false)
 
 ### 3. Set Up CommitLint
 
 ```json
 // package.json
 {
-	"commitlint": {
-		"extends": ["@halospv3/hce.shared-config/commitlintConfig"]
-	}
+  "commitlint": {
+    "extends": ["@halospv3/hce.shared-config/commitlintConfig"]
+  }
 }
 ```
+
 or
 
 ```ts
@@ -192,6 +199,7 @@ export default commitlintConfig;
 ```
 
 Then...
+
 ```sh
 npx husky
 npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'
@@ -201,21 +209,22 @@ npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'
 
 ```xml
 <Project>
-	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.targets"/>
+  <Import Project="$(HCESharedDir)/dotnet/HCE.Shared.targets"/>
 
-	<PropertyGroup>
-		<RepoRoot Condition="'$(RepoRoot)' == ''">$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), '.git/index'))</RepoRoot>
-		<HCESharedDir Condition="'$(HCESharedDir)' == ''">$(RepoRoot)node_modules/@halospv3/hce.shared-config/</HCESharedDir>
-		<!--<GitVersion_Path Condition="'$(GitVersion_Path)' == ''">Path/To/Your/GitVersion.yml</GitVersion_Path>-->
-	</PropertyGroup>
+  <PropertyGroup>
+    <RepoRoot Condition="'$(RepoRoot)' == ''">$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), '.git/index'))</RepoRoot>
+    <HCESharedDir Condition="'$(HCESharedDir)' == ''">$(RepoRoot)node_modules/@halospv3/hce.shared-config/</HCESharedDir>
+    <!--<GitVersion_Path Condition="'$(GitVersion_Path)' == ''">Path/To/Your/GitVersion.yml</GitVersion_Path>-->
+  </PropertyGroup>
 </Project>
 ```
 
 These may evaluate to the following:
-| Property     | Evaluated Value|
-| ------------ | -------------- |
-|`RepoRootDir` | `c:\Repos\HaloSPV3\HCE.Shared\` |
-|`HCESharedDir`| `c:\Repos\HaloSPV3\HCE.Shared\node_modules\@halospv3\hce.shared-config\` |
+
+| Property       | Evaluated Value                                                          |
+| -------------- | ------------------------------------------------------------------------ |
+| `RepoRootDir`  | `c:\Repos\HaloSPV3\HCE.Shared\`                                          |
+| `HCESharedDir` | `c:\Repos\HaloSPV3\HCE.Shared\node_modules\@halospv3\hce.shared-config\` |
 
 #### CI/CD-Only Properties
 
@@ -227,15 +236,15 @@ conditional property group to the props file:
 
 ```xml, diff
 <Project>
-	<PropertyGroup>
-		...
-	</PropertyGroup>
-
-	<PropertyGroup Condition=" '$(CI)' == 'true' ">
-		<Configuration>Release</Configuration>
-		<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
-		<Deterministic>true</Deterministic>
-	</PropertyGroup>
+  <PropertyGroup>
+    ...
+  </PropertyGroup>
+
+  <PropertyGroup Condition=" '$(CI)' == 'true' ">
+    <Configuration>Release</Configuration>
+    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+    <Deterministic>true</Deterministic>
+  </PropertyGroup>
 </Project>
 ```
 
@@ -256,25 +265,28 @@ packages.
 You can...
 
 ...define it yourself
+
 ```xml
 <Project>
-	<PropertyGroup>
-		<GitVersion_Path>$(ProjectRootDir)/node_modules/@halospv3/hce.shared-config/dotnet/GitVersion.yml</GitVersion_Path>
-	</PropertyGroup>
+  <PropertyGroup>
+    <GitVersion_Path>$(ProjectRootDir)/node_modules/@halospv3/hce.shared-config/dotnet/GitVersion.yml</GitVersion_Path>
+  </PropertyGroup>
 </Project>
 ```
 
 ...import HCE.Shared.props
+
 ```xml
 <Project>
-	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
+  <Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
 </Project>
 ```
 
 ...import HCE.Shared.Targets (which imports HCE.Shared.props)
+
 ```xml
 <Project>
-	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
+  <Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
 </Project>
 ```
 
@@ -286,6 +298,7 @@ If you want to use this information in other Semantic Release steps, you'll need
 `semantic-release-export-data`.
 
 Run the following to preview the version:
+
 ```sh
 npx semantic-release --dry-run --plugins "@semantic-release/commit-analyzer,semantic-release-export-data"
 ```
@@ -301,7 +314,7 @@ Add the following to `package.json`:
 
 ```json
 {
-	"private": true,
+  "private": true
 }
 ```
 
@@ -313,13 +326,13 @@ See callable workflows such as [dotnet-ci](./.github/workflows/dotnet-ci.yml)
 
 ```yml
 jobs:
-	release:
-		steps:
-		- uses: actions/checkout@v3
-		- name: dotnet build/publish; copy release artifacts to './publish/'
-			uses: ./node_modules/@halospv3/hce.shared/dotnet/.github/workflows/dotnet-release.yml
-				with:
-					projects:
-					- src/lib/lib.csproj
-					- src/lib-sample/sample.csproj
+  release:
+    steps:
+    - uses: actions/checkout@v3
+    - name: dotnet build/publish; copy release artifacts to './publish/'
+      uses: ./node_modules/@halospv3/hce.shared/dotnet/.github/workflows/dotnet-release.yml
+        with:
+          projects:
+          - src/lib/lib.csproj
+          - src/lib-sample/sample.csproj
 ```

package/dotnet/.github/workflows/_unit_test.yml

@@ -2,7 +2,7 @@
 on:
   workflow_call:
 env:
-  DOTNET_ROLL_FORWARD: "Major"
+  DOTNET_ROLL_FORWARD: 'Major'
 
 jobs:
   unit_test:
@@ -14,12 +14,15 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
-          cache: "npm"
+          cache: 'npm'
           check-latest: true
           node-version-file: package.json
       - run: npm i -g npm@latest
@@ -27,6 +30,6 @@ jobs:
 
       - uses: actions/setup-dotnet@v4.3.1
         with:
-          dotnet-version: "8.x"
+          dotnet-version: '8.x'
 
       - run: dotnet test

package/dotnet/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ on:
   workflow_call:
 
 env:
-  DOTNET_ROLL_FORWARD: "Major"
+  DOTNET_ROLL_FORWARD: 'Major'
   DOTNET_CLI_TELEMETRY_OPTOUT: 1
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
   DOTNET_NOLOGO: 1
@@ -19,4 +19,4 @@ env:
 jobs:
   unit_test:
     name: Unit Test
-    uses: ./.github/workflows/_unit_test.yml # <- your unit test workflow here. Example: file://./_unit_test.yml
+    uses: ./dotnet/.github/workflows/_unit_test.yml # <- your unit test workflow here. Example: file://./_unit_test.yml

package/dotnet/.github/workflows/dotnet-release.yml

@@ -6,16 +6,16 @@ name: dotnet-release
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [main, develop]
     paths-ignore:
-    - ".github/**/*.*"
-    - "**/*.md"
-    - "**/*.txt"
+      - '.github/**/*.*'
+      - '**/*.md'
+      - '**/*.txt'
 
 jobs:
   ci:
     name: CI # run test.yml. If it fails, this job fails.
-    uses: ./.github/workflows/ci.yml # <- your CI workflow here. Example: 'file://./ci.yml'
+    uses: ./dotnet/.github/workflows/ci.yml # <- your CI workflow here. Example: 'file://./ci.yml'
   release:
     needs: [ci] # start 'release' if 'ci' completes successfully
     runs-on: ubuntu-latest
@@ -24,27 +24,30 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-    ################
-    # SETUP
-    ################
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0 # Required by GitVersion, Semantic Release
-        submodules: "recursive" # submodule fetch depth unknown
-    - uses: actions/setup-dotnet@v4
-    - uses: actions/setup-node@v4
-    - run: npm install -g npm@latest
-    - run: npm ci # Required by Semantic Release
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
+      ################
+      # SETUP
+      ################
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required by GitVersion, Semantic Release
+          submodules: 'recursive' # submodule fetch depth unknown
+      - uses: actions/setup-dotnet@v4
+      - uses: actions/setup-node@v4
+      - run: npm install -g npm@latest
+      - run: npm ci # Required by Semantic Release
 
-    ################
-    # RELEASE
-    # @semantic-release/exec should be configured to execute
-    # `dotnet publish`, `dotnet pack`, and `dotnet nuget push`
-    # You can use this package's semanticReleaseConfigDotnet exports to do so.
-    ################
-    # https://github.com/semantic-release/semantic-release
-    - name: Semantic Release
-      run: npx semantic-release
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        NUGET_TOKEN: ${{ secrets.NUGET_TOKEN }}
+      ################
+      # RELEASE
+      # @semantic-release/exec should be configured to execute
+      # `dotnet publish`, `dotnet pack`, and `dotnet nuget push`
+      # You can use this package's semanticReleaseConfigDotnet exports to do so.
+      ################
+      # https://github.com/semantic-release/semantic-release
+      - name: Semantic Release
+        run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NUGET_TOKEN: ${{ secrets.NUGET_TOKEN }}

package/dotnet/.github/workflows/sample-dotnet-build.yml

@@ -9,15 +9,20 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-      with:
-        submodules: 'recursive'
-        fetch-depth: 0
-    - uses: actions/setup-dotnet@v4
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+          fetch-depth: 0
+      - uses: actions/setup-dotnet@v4
 
-    - run: dotnet build src/SPV3.csproj -c Release -p:ContinuousIntegrationBuild=true
-      # ContinuousIntegrationBuild comes from dotnet/sourcelink. 
-      # Make sure Deterministic is also true!
-      # If you use this package's dotnet props/targets files, you're good to go!
-      # 
-      # Alternatively, add a PropertyGroup with the condition " '$(CI)' != '' "
+      - run:
+          dotnet build src/SPV3.csproj -c Release
+          -p:ContinuousIntegrationBuild=true
+        # ContinuousIntegrationBuild comes from dotnet/sourcelink.
+        # Make sure Deterministic is also true!
+        # If you use this package's dotnet props/targets files, you're good to go!
+        #
+        # Alternatively, add a PropertyGroup with the condition " '$(CI)' != '' "

package/dotnet/ExecNupkgDeterministicator.README.md

@@ -0,0 +1,20 @@
+<h1 align="center">ExecNupkgDeterministicator.target</h1>
+
+This target runs after "Pack" and utilizes `kuinox.nupkgdeterministicator` to make the nupkg (and snupkg!) deterministic. However, this target does not include `kuinox.nupkgdeterministicator`. As such, an Error task will be executed if the dotnet tool `kuinox.nupkgdeterministicator` is not installed locally nor globally. Cake and NUKE are not supported by this MSBuild Target.
+
+Learn more about Kuinox's NupkgDeterministicator\
+[GitHub](https://github.com/Kuinox/NupkgDeterministicator) | [Nuget](https://www.nuget.org/packages/Kuinox.NupkgDeterministicator)
+
+## Install `kuinox.nupkgdeterministicator`
+
+### .NET CLI (Global)
+
+```sh
+dotnet tool install -g NupkgDeterministicator
+```
+
+### .NET CLI (Local)
+
+```sh
+dotnet tool install -g NupkgDeterministicator
+```