javascript-build.yml

name: JavaScript Build

concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true

on:
    workflow_dispatch:
        inputs:
            logLevel:
                description: 'Log level'
                required: true
                default: 'warning'
                type: choice
                options:
                    - info
                    - warning
                    - debug
    push:
        branches:
            - 'main'
        paths:
            - 'Source/**'
            - 'Migrator/**'
            - 'ESLint/**'
            - 'Conformance/**'
            - 'Adapters/**'
            - 'Storybook/**'
            - 'scripts/**'
            - 'compat-manifest.json'
            - 'README.md'
            - 'release.md'
            - 'run-task-on-workspaces.js'
            - 'package.json'
            - 'rollup.config.mjs'
            - 'yarn.lock'
            - '.yarnrc.yml'
            - '.yarn/releases/yarn-4.5.3.cjs'
            - '.github/workflows/javascript-build.yml'
            - '.github/workflows/publish.yml'
    pull_request:
        branches:
            - '**'
        paths:
            - 'Source/**'
            - 'Migrator/**'
            - 'ESLint/**'
            - 'Conformance/**'
            - 'Adapters/**'
            - 'Storybook/**'
            - 'scripts/**'
            - 'compat-manifest.json'
            - 'README.md'
            - 'release.md'
            - 'run-task-on-workspaces.js'
            - 'package.json'
            - 'rollup.config.mjs'
            - 'yarn.lock'
            - '.yarnrc.yml'
            - '.yarn/releases/yarn-4.5.3.cjs'
            - '.github/workflows/javascript-build.yml'
            - '.github/workflows/publish.yml'

permissions:
    contents: read

jobs:
    build:
        runs-on: ubuntu-latest
        timeout-minutes: 35

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build JS/TS
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn ci

            - name: Verify root-import codemod
              working-directory: Migrator
              run: |
                  yarn test
                  yarn verify-package

            - name: Verify packed ESLint plugin
              working-directory: ESLint
              run: yarn verify-package

            - name: Verify packed renderer conformance package
              working-directory: Conformance
              run: yarn verify-package

            # Every intentionally public declaration/member reachable from a JS `exports`
            # subpath must carry a TSDoc comment (Cratis/Components#173). Runs against
            # source, so it needs no build step; its own self-tests run first and fail
            # the job if the reachability/doc-presence walk itself regresses.
            - name: Verify public API TSDoc coverage
              working-directory: Source
              run: node scripts/verify-api-docs.mjs

            - name: Verify renderer Storybook type, inventory, specs, and peer isolation
              working-directory: Storybook
              run: yarn ci:preflight

            - name: Build composed renderer Storybook
              run: yarn workspace @cratis/components build-storybook

            - name: Verify every renderer Storybook index and build attestation
              working-directory: Source
              run: yarn verify-storybook-index

            - name: Install Storybook browser
              run: yarn playwright install --with-deps chromium

            - name: Test every Storybook story
              working-directory: Source
              run: yarn test-storybook

    # Builds and retains exact archives and SBOM evidence. This job is read-only; publication
    # authority remains isolated to the Publish workflow's OIDC-enabled npm job.
    release-evidence:
        runs-on: ubuntu-latest
        timeout-minutes: 20
        permissions:
            contents: read

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Test release-evidence generator
              run: yarn test-release-evidence

            - name: Generate release evidence
              run: >-
                  yarn generate-release-evidence
                  --output "${{ runner.temp }}/components-v4-release-evidence"

            - name: Upload release evidence
              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
              with:
                  name: components-v4-release-evidence-${{ github.sha }}
                  path: |
                      ${{ runner.temp }}/components-v4-release-evidence/*.tgz
                      ${{ runner.temp }}/components-v4-release-evidence/SHA256SUMS
                      ${{ runner.temp }}/components-v4-release-evidence/SHA512SUMS
                      ${{ runner.temp }}/components-v4-release-evidence/*.cdx.json
                      ${{ runner.temp }}/components-v4-release-evidence/release-evidence.json
                  if-no-files-found: error
                  retention-days: 30

    # Builds the artifact that actually ships to npm (the `prepare` script: tsc -b +
    # rollup + copy-css) and loads every subpath of the `exports` map from it.
    #
    # The `build` job above only runs `tsc -p tsconfig.json`, so nothing in CI had ever
    # imported the published shape. That gap is how Cratis/Components#118 - the published
    # ESM contains directory imports, so no node-environment spec can render Dialog or
    # CommandDialog - reached a release unnoticed.
    #
    # This job landed deliberately non-blocking, because it reproduced #118 and both of
    # that issue's causes were still open: the bare `primereact/*` directory imports
    # (fixed by the PrimeReact 11 migration) and the CSS side-effect imports rollup
    # externalised via /\.css$/ (fixed by moving component CSS out of the JavaScript
    # graph and into the `./styles` entry point). Both are resolved as of 3.0.0; all 25
    # subpaths load cleanly - so `continue-on-error` is gone and this is now a real gate.
    verify-published-exports:
        runs-on: ubuntu-latest
        timeout-minutes: 10

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify packed production tree shaking
              working-directory: Source
              run: yarn verify-packed-production

            - name: Verify published exports
              working-directory: Source
              run: node scripts/verify-exports.mjs

    # Verifies every public JS subpath's declarations against a strict external TypeScript 6
    # consumer of the packed artifact. Bounded upstream exceptions live in
    # Source/scripts/verify-public-types.exceptions.json; any Components-owned or otherwise
    # unlisted diagnostic fails this job, as does an exception that stops reproducing.
    verify-public-types:
        runs-on: ubuntu-latest
        timeout-minutes: 15

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify public types
              working-directory: Source
              run: node scripts/verify-public-types.mjs --report "${{ runner.temp }}/verify-public-types-report.json"

            - name: Upload verify-public-types report
              if: always()
              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
              with:
                  name: verify-public-types-report
                  path: ${{ runner.temp }}/verify-public-types-report.json
                  if-no-files-found: ignore

    # Deterministic dependency-closure check for the setup-only root architecture: every
    # non-spatial subpath (everything except ./Canvas and ./PivotViewer) must never reach
    # a file under Canvas/ or PivotViewer/, nor the external specifier pixi.js, in either
    # its runtime or declaration closure; ./Canvas and ./PivotViewer must still reach
    # pixi.js; and pixi.js must never be imported directly by any emitted file outside
    # those two directories, regardless of exports-map reachability.
    verify-package-graph:
        runs-on: ubuntu-latest
        timeout-minutes: 10

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify package graph
              working-directory: Source
              run: node scripts/verify-package-graph.mjs --report "${{ runner.temp }}/verify-package-graph-report.json"

            - name: Upload verify-package-graph report
              if: always()
              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
              with:
                  name: verify-package-graph-report
                  path: ${{ runner.temp }}/verify-package-graph-report.json
                  if-no-files-found: ignore

    # Proves a consumer who installs only the mandatory peers - never pixi.js - can fully
    # use the package root and every non-spatial subpath: runtime import, strict Bundler
    # and NodeNext TypeScript for the root with pixi.js genuinely absent from
    # node_modules, an SSR provider smoke test, and a clean packed root closure.
    verify-no-pixi-consumer:
        runs-on: ubuntu-latest
        timeout-minutes: 15

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify no-Pixi consumer
              working-directory: Source
              run: node scripts/verify-no-pixi-consumer.mjs

    # Complements verify-no-pixi-consumer: proves a consumer who installs the mandatory
    # peers and the optional pixi.js peer can use the spatial subpaths (./Canvas,
    # ./PivotViewer), that pixi.js resolves to exactly one instance with no nested copy,
    # and that ./Canvas type-checks with pixi.js installed.
    verify-spatial-consumer:
        runs-on: ubuntu-latest
        timeout-minutes: 15

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify spatial consumer
              working-directory: Source
              run: node scripts/verify-spatial-consumer.mjs

    # Proves the shared CratisComponentsContext (custom labels) and react-aria-components'
    # I18nProvider locale context stay one singleton across the root barrel and every
    # separately built subpath, against the packed artifact - source-level relative
    # imports would trivially share one module graph regardless of how the published
    # entry points are structured, so only the packed boundary can exercise this risk.
    verify-provider-context-identity:
        runs-on: ubuntu-latest
        timeout-minutes: 15

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
              id: yarn-cache
              with:
                  path: |
                      .yarn/cache
                      **/node_modules
                      **/.eslintcache
                  key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.5.3.cjs') }}

            - name: Yarn install
              run: yarn install --immutable

            - name: Build the published artifact
              working-directory: Source
              run: |
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  yarn run prepare

            - name: Verify provider-context identity
              working-directory: Source
              run: node scripts/verify-provider-context-identity.mjs

    verify-arc-consumers:
        runs-on: ubuntu-latest
        timeout-minutes: 15
        strategy:
            fail-fast: false
            matrix:
                arc-version: ['20.3.1', '21.19.4', '22.6.2']

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - name: Yarn install
              run: yarn install --immutable

            - name: Build and pack Components
              run: |
                  yarn workspace @cratis/components prepare
                  yarn workspace @cratis/components pack --out /tmp/cratis-components.tgz
                  yarn workspace @cratis/components verify-package-archive /tmp/cratis-components.tgz

            - name: Verify Arc ${{ matrix.arc-version }} rendering consumer
              run: |
                  CONSUMER="$(mktemp -d)"
                  cd "$CONSUMER"
                  printf '{"private":true,"type":"module"}\n' > package.json
                  npm install --ignore-scripts \
                    /tmp/cratis-components.tgz \
                    "@cratis/arc@${{ matrix.arc-version }}" \
                    "@cratis/arc.react@${{ matrix.arc-version }}" \
                    @cratis/fundamentals react@19 react-dom@19 \
                    reflect-metadata tsyringe
                  node --input-type=module - <<'NODE'
                  const commandDialog = await import('@cratis/components/CommandDialog');
                  const dataPage = await import('@cratis/components/DataPage');
                  const notifications = await import('@cratis/components/Notifications');
                  const required = {
                      CommandDialog: commandDialog.CommandDialog,
                      DataPage: dataPage.DataPage,
                      toast: notifications.toast,
                  };
                  for (const [name, value] of Object.entries(required)) {
                      if (!value) throw new Error(`Missing ${name}`);
                  }
                  for (const forbidden of ['primereact', '@primereact/core', '@primeuix/themes']) {
                      try {
                          import.meta.resolve(forbidden);
                          throw new Error(`Unexpected renderer dependency: ${forbidden}`);
                      } catch (error) {
                          if (error instanceof Error && error.message.startsWith('Unexpected')) throw error;
                      }
                  }
                  NODE

    verify-package-managers:
        runs-on: ubuntu-latest
        timeout-minutes: 20
        strategy:
            fail-fast: false
            matrix:
                include:
                    - manager: npm
                      pixi: absent
                    - manager: npm
                      pixi: present
                    - manager: pnpm
                      pixi: absent
                    - manager: pnpm
                      pixi: present
                    - manager: yarn-pnp
                      pixi: absent
                    - manager: yarn-pnp
                      pixi: present

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - name: Enable Corepack
              run: corepack enable

            - name: Yarn install
              run: yarn install --immutable

            - name: Build and pack Components
              run: |
                  yarn workspace @cratis/components prepare
                  yarn workspace @cratis/components pack --out /tmp/cratis-components.tgz
                  yarn workspace @cratis/components verify-package-archive /tmp/cratis-components.tgz

            - name: Create consumer fixture
              run: |
                  mkdir /tmp/components-consumer
                  cat > /tmp/components-consumer/package.json <<'JSON'
                  {"private":true,"type":"module"}
                  JSON
                  cp Source/scripts/lib/package-manager-consumer-probe.mjs \
                    /tmp/components-consumer/verify.mjs

            - name: Verify npm consumer
              if: matrix.manager == 'npm'
              working-directory: /tmp/components-consumer
              run: |
                  PIXI=()
                  if [ "${{ matrix.pixi }}" = 'present' ]; then PIXI+=(pixi.js@8.20.0); fi
                  npm install --ignore-scripts --no-audit --no-fund \
                    /tmp/cratis-components.tgz \
                    @cratis/arc@22.6.2 @cratis/arc.react@22.6.2 \
                    @cratis/fundamentals@7.18.1 @types/react@19.2.18 \
                    react@19.2.8 react-dom@19.2.8 \
                    reflect-metadata@0.2.2 tsyringe@4.10.0 "${PIXI[@]}"
                  node verify.mjs "${{ matrix.pixi }}"

            - name: Verify pnpm consumer
              if: matrix.manager == 'pnpm'
              working-directory: /tmp/components-consumer
              run: |
                  corepack prepare pnpm@10.17.1 --activate
                  PIXI=()
                  if [ "${{ matrix.pixi }}" = 'present' ]; then PIXI+=(pixi.js@8.20.0); fi
                  pnpm add --ignore-scripts --strict-peer-dependencies \
                    /tmp/cratis-components.tgz \
                    @cratis/arc@22.6.2 @cratis/arc.react@22.6.2 \
                    @cratis/fundamentals@7.18.1 @types/react@19.2.18 \
                    react@19.2.8 react-dom@19.2.8 \
                    reflect-metadata@0.2.2 tsyringe@4.10.0 "${PIXI[@]}"
                  pnpm exec node verify.mjs "${{ matrix.pixi }}"

            - name: Verify Yarn PnP consumer
              if: matrix.manager == 'yarn-pnp'
              working-directory: /tmp/components-consumer
              run: |
                  corepack prepare yarn@4.5.3 --activate
                  cat > .yarnrc.yml <<'YAML'
                  nodeLinker: pnp
                  # Arc React 22 imports rxjs without declaring it. Keep that upstream
                  # manifest issue explicit so this fixture can still isolate Components.
                  packageExtensions:
                    "@cratis/arc.react@*":
                      dependencies:
                        rxjs: "*"
                  YAML
                  PIXI=()
                  if [ "${{ matrix.pixi }}" = 'present' ]; then PIXI+=(pixi.js@8.20.0); fi
                  yarn add \
                    /tmp/cratis-components.tgz \
                    @cratis/arc@22.6.2 @cratis/arc.react@22.6.2 \
                    @cratis/fundamentals@7.18.1 @types/react@19.2.18 \
                    react@19.2.8 react-dom@19.2.8 \
                    reflect-metadata@0.2.2 tsyringe@4.10.0 rxjs@7.8.2 "${PIXI[@]}"
                  yarn node verify.mjs "${{ matrix.pixi }}"

    verify-renderer-adapters:
        name: Renderer adapter (${{ matrix.adapter }}, ${{ matrix.boundary }}, ${{ matrix.manager }})
        runs-on: ubuntu-latest
        timeout-minutes: 25
        strategy:
            fail-fast: false
            matrix:
                adapter: [mui, primereact11, primereact10]
                boundary: [minimum, current]
                manager: [npm, pnpm, yarn-pnp]

        steps:
            - name: Checkout code
              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

            - name: Setup node
              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
              with:
                  node-version: 23.x
                  registry-url: 'https://registry.npmjs.org'

            - name: Enable Corepack
              run: corepack enable

            - name: Yarn install
              run: yarn install --immutable

            - name: Test renderer adapter matrix validation
              run: yarn test-renderer-adapter-matrix

            - name: Verify packed ${{ matrix.adapter }} ${{ matrix.boundary }} boundary with ${{ matrix.manager }}
              run: >-
                  yarn verify-renderer-adapters
                  --adapter ${{ matrix.adapter }}
                  --boundary ${{ matrix.boundary }}
                  --manager ${{ matrix.manager }}