node.js.yml

name: Semiotic

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  testing:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source code
        uses: actions/checkout@v6

      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22.x
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Build library
        run: npm run dist

      - name: Build MCP server
        run: npm run build:mcp

      - name: Run tests with coverage
        run: npx vitest run --coverage

      - name: Run type check
        run: npm run typescript

      - name: Run test type check
        run: npm run typescript:tests

      - name: Run MCP type check
        run: npm run typescript:mcp

      - name: Check chart spec registry round-trip
        run: npm run check:chart-specs

      - name: Check capability matrix freshness
        run: npm run check:capabilities

      - name: Check blog metadata registry freshness
        run: npm run check:blog-entries

      - name: Check CLAUDE.md component coverage
        run: npm run check:claude-md-coverage

      - name: Check context7.json freshness
        run: npm run check:context7

      - name: Check MCP Registry submission cross-references
        run: npm run check:mcp-registry

      - name: Check AI/MCP surface parity
        run: npm run check:surface

      - name: Check SSR alignment
        run: npm run check:ssr

      - name: Check public API surface (no breaking changes)
        run: npm run check:api-surface

      - name: Check HOC JSDoc coverage (≥2 @example blocks per HOC)
        run: npm run check:jsdoc-coverage

      - name: Check ai/examples.md coverage + drift
        run: npm run check:ai-examples-coverage

      - name: Build production bundles
        run: npm run dist:prod

      - name: Check bundle-size docs (README + CLAUDE.md + ai/system-prompt.md)
        run: npm run check:bundle-sizes

      - name: Pack smoke test (verify all entry points resolve)
        run: npm run check:pack

      - name: Verify TypeScript declarations
        run: |
          for f in dist/semiotic.d.ts dist/semiotic-xy.d.ts dist/semiotic-ordinal.d.ts dist/semiotic-network.d.ts dist/semiotic-geo.d.ts dist/semiotic-realtime.d.ts dist/semiotic-ai.d.ts dist/semiotic-data.d.ts dist/semiotic-server.d.ts dist/semiotic-themes.d.ts; do
            if [ ! -f "$f" ]; then
              echo "MISSING: $f"
              exit 1
            fi
          done
          echo "All declaration files present"

      - name: Check bundle sizes
        run: npx size-limit

      - name: Validate canvas stub completeness
        run: |
          # Extract canvas method names used in production renderers
          USED=$(grep -roh 'ctx\.\([a-zA-Z]*\)' src/components/stream/renderers/ | \
            sed 's/ctx\.//' | sort -u | grep -v '^$')
          # Extract stubbed method names from setupTests.ts
          STUBBED=$(grep -oP '"\K[a-zA-Z]+(?=")' src/setupTests.ts | sort -u)
          # Find methods used in renderers but not stubbed
          MISSING=""
          for method in $USED; do
            if ! echo "$STUBBED" | grep -qx "$method"; then
              # Skip property assignments (not methods)
              case "$method" in
                fillStyle|strokeStyle|lineWidth|lineCap|lineJoin|globalAlpha|\
                globalCompositeOperation|font|textAlign|textBaseline|shadowColor|\
                shadowBlur|shadowOffsetX|shadowOffsetY|lineDashOffset|miterLimit|\
                canvas|imageSmoothingEnabled|direction|filter|letterSpacing|\
                fontKerning|fontStretch|fontVariantCaps|textRendering|wordSpacing)
                  ;; # property, not a method — skip
                *)
                  MISSING="$MISSING $method"
                  ;;
              esac
            fi
          done
          if [ -n "$MISSING" ]; then
            echo "Canvas methods used in renderers but not stubbed in setupTests.ts:"
            echo "$MISSING"
            echo ""
            echo "Add these to the canvasMethods array in src/setupTests.ts"
            exit 1
          fi
          echo "All canvas methods are stubbed"

  bench:
    name: Performance regression
    runs-on: ubuntu-latest
    # PR-only: captures main's bench numbers in the same job on the same
    # hardware, then compares the PR's results against them. Avoids the
    # cross-architecture noise that plagues a committed-baseline approach
    # (M-series Mac local capture vs. x86 Linux CI runner produces uniform
    # 60–90% "slowdowns" across every benchmark). On `push: main` there's
    # nothing to compare main against, so the job is skipped.
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout source code
        uses: actions/checkout@v6
        with:
          # `bench:pr-vs-main` worktrees `origin/main` to capture a
          # CI-native baseline. Default checkout is shallow to the
          # triggering ref only; full history makes worktree-add reliable
          # without needing extra fetch plumbing.
          fetch-depth: 0

      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22.x
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Compare PR vs main on identical hardware
        run: npm run bench:pr-vs-main

  e2e:
    runs-on: ubuntu-latest
    needs: testing

    steps:
      - name: Checkout source code
        uses: actions/checkout@v6

      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22.x
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium firefox webkit

      - name: Build library
        run: npm run dist

      - name: Run E2E tests
        # `--update-snapshots=missing` (playwright 1.42+) writes a baseline
        # only when the spec×browser×OS combination has none. Existing
        # baselines stay locked in — diff failures still fail the build,
        # so the regression gate is intact for everything that's been
        # bootstrapped. New tests / new OS-browser combos get their
        # baseline on first run instead of failing. The freshly-written
        # baselines flow into the `playwright-snapshots` artifact below;
        # maintainers commit them periodically to make the gate denser.
        #
        # Replaces a prior HAVE_LINUX binary gate that ran a full
        # `--update-snapshots` (no value, overwrites everything) the
        # first time and skipped on subsequent runs — which left
        # single-test misses (a flaky run, a renamed test) permanently
        # failing CI because no second bootstrap pass would fire.
        run: npx playwright test --update-snapshots=missing

      - name: Upload snapshot baselines
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-snapshots
          path: integration-tests/*.spec.ts-snapshots/
          retention-days: 30

      - name: Upload test artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: integration-tests/test-results/
          retention-days: 7