feat: extract and publish core package (#629)

This PR addresses: #616 by:

- configuring CI to release a new module (in addition to
server/web/react we now release the "core" module (previously called
"shared").
- adding a peer dep to the above module to server/web/react
- adding a workflow to ensure that `shared` is released ahead of
associated web/server/react changes, and which also auto-increments the
peer dep version when the core module is released
- unrelated `typedoc` improvements/updates

> [!NOTE]  
> I intend to create a new PR that will rename the dir structure
according to the packages... so `shared/` will become `core/` and
`client/` will become `web/`. I just didn't want to add confusion and
noise to this PR.

---------

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

.github/workflows/audit-pending-releases.yml

@@ -0,0 +1,49 @@
+on:
+  push:
+    branches:
+      - 'release-please**'
+
+env:
+  CORE_PACKAGE: core
+
+name: Audit Pending Releases
+jobs:
+  npm-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.ref }}
+
+      # if this is an SDK release, make sure there's no pending releases for @openfeature/core
+      - name: Check for Pending Dependency PRs
+        if: ${{ !endsWith(github.ref_name, env.CORE_PACKAGE) }}
+        run: |
+          if [ $(gh pr list --search '"release ${{ env.CORE_PACKAGE }}" in:title' | wc -l) -gt 0 ]; \
+            then echo "Pending @openfeaure/${{ env.CORE_PACKAGE }} release. Please release @openfeaure/${{ env.CORE_PACKAGE }} first!" && exit 1; \
+            else echo "No pending @openfeaure/${{ env.CORE_PACKAGE }} releases"; \
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 16
+          registry-url: "https://registry.npmjs.org"
+          cache: 'npm'
+
+      # if this is an @openfeature/core release, but the SDKs to use this version as a peer, and commit back
+      - name: Update Peer Version in Dependants
+        if: ${{ endsWith(github.ref_name, env.CORE_PACKAGE) }}
+        run: |
+          npm run update-core-peers && \
+          ! git diff-files --quiet && \
+          ( echo 'Updated peer dependency in dependants, commiting...'
+          git add --all && \
+          git config user.name "openfeature-peer-update-bot" && \
+          git config user.email "[email protected]" && \
+          git commit -m 'chore: bump @openfeaure/${{ env.CORE_PACKAGE }} peer' -s && \
+          git push ) || echo 'Peer dependency in dependants is already up to date.'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pr-checks.yaml

@@ -53,6 +53,9 @@ jobs:
       - name: Install
         run: npm ci
 
+      - name: Install
+        run: npm run build
+
       - name: Docs
         run: npm run docs
 

.github/workflows/publish-experimental.yml

@@ -19,7 +19,10 @@ We value having as few runtime dependencies as possible. The addition of any dep
 ### Modules
 
 This repository uses [NPM workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces) to establish a simple monorepo.
-Within the root project, there is one common project (`packages/shared`) which features common interfaces and code, consumed by the published modules (`packages/server` and `packages/client`). The shared module is bundled transparently into the published modules - it is not published itself. Changes in `packages/shared` will result in releases of the dependant modules via Release Please.
+Within the root project, there is one common project (`packages/shared`) which features common interfaces and code, consumed by the published modules (`packages/server` and `packages/client`).
+The shared module is built and published separately, and is a peer dependency of the SDK packages.
+Consumers need not install it separately, since `npm` and `yarn` automatically install required peers.
+In order to prevent regressions cause by incompatibilities due to version mismatches, the SDKs are locked to a particular version of the `@openfeature/core` module, and the CI enforces that it's released before any dependant SDKs (see [the related workflow](./.github/workflows/audit-pending-releases.yml)).
 
 ### Testing
 
@@ -45,8 +48,6 @@ for the client e2e tests.
 
 Both ES modules and CommonJS modules are supported, so consumers can use both `require` and `import` functions to utilize this module. This is accomplished by building 2 variations of the output, under `dist/esm` and `dist/cjs`, respectively. To force resolution of the `dist/esm/**.js*` files as modules, a package json with only the context `{"type": "module"}` is included at a in a `postbuild` step. Type declarations are included at `/dist/types/`
 
-For testing purposes, you can add a comment containing "/publish" in any PR. This will publish an experimental SDK version with the git SHA appended to the version number.
-
 ## Pull Request
 
 All contributions to the OpenFeature project are welcome via GitHub pull requests.

CONTRIBUTING.md

@@ -119,12 +119,18 @@ export default {
       testEnvironment: 'node',
       preset: 'ts-jest',
       testMatch: ['<rootDir>/packages/server/test/**/*.spec.ts'],
+      moduleNameMapper: {
+        '@openfeature/core': '<rootDir>/packages/shared/src'
+      },
     },
     {
       displayName: 'client',
       testEnvironment: 'node',
       preset: 'ts-jest',
       testMatch: ['<rootDir>/packages/client/test/**/*.spec.ts'],
+      moduleNameMapper: {
+        '@openfeature/core': '<rootDir>/packages/shared/src'
+      }
     },
     {
       displayName: 'server-e2e',
@@ -133,6 +139,9 @@ export default {
       testMatch: ['<rootDir>/packages/server/e2e/**/*.spec.ts'],
       modulePathIgnorePatterns: ['.*/node-modules/'],
       setupFiles: ['<rootDir>/packages/server/e2e/step-definitions/setup.ts'],
+      moduleNameMapper: {
+        '@openfeature/core': '<rootDir>/packages/shared/src'
+      },
     },
     {
       displayName: 'client-e2e',
@@ -144,6 +153,7 @@ export default {
       moduleNameMapper: {
         '^uuid$': require.resolve('uuid'),
         '^(.*)\\.js$': ['$1', '$1.js'],
+        '@openfeature/core': '<rootDir>/packages/shared/src'
       },
     },
   ],