release.yml

name: Release

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:
    inputs:
      tag:
        description: "Tag to release (e.g., v1.0.1) — must already exist on origin"
        required: true
        type: string

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write

jobs:
  validate:
    name: Validate (pre-release gate)
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: "22"
          cache: npm

      - name: Install dependencies
        run: npm ci || (sleep 10 && npm ci)

      - name: Format check
        run: npm run fmt:check

      - name: Schema + invariant validation
        run: npm run validate

      - name: Tests
        run: npm test

      - name: Lockfile drift check
        run: npm run lock:check

  verify-tag:
    name: Verify tag matches package.json + CHANGELOG
    runs-on: ubuntu-latest
    needs: validate
    timeout-minutes: 5
    outputs:
      version: ${{ steps.extract.outputs.version }}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Extract tag and package.json version
        id: extract
        shell: bash
        run: |
          # Resolve the tag from either the push event or workflow_dispatch input.
          if [ -n "${{ github.event.inputs.tag }}" ]; then
            TAG_REF="${{ github.event.inputs.tag }}"
          else
            TAG_REF="${GITHUB_REF#refs/tags/}"
          fi

          # Strip the leading 'v' so we can compare against package.json's plain semver.
          TAG_VERSION="${TAG_REF#v}"
          PKG_VERSION=$(node -p "require('./package.json').version")

          echo "tag_ref=$TAG_REF" >> "$GITHUB_OUTPUT"
          echo "tag_version=$TAG_VERSION" >> "$GITHUB_OUTPUT"
          echo "version=$TAG_VERSION" >> "$GITHUB_OUTPUT"

          echo "Tag: $TAG_REF (version: $TAG_VERSION)"
          echo "package.json version: $PKG_VERSION"

          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
            echo "::error::Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
            exit 1
          fi

          {
            echo "### Tag verification"
            echo ""
            echo "- Tag: \`$TAG_REF\`"
            echo "- package.json version: \`$PKG_VERSION\`"
            echo "- Match: yes"
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Verify CHANGELOG has section for tag version
        shell: bash
        run: |
          VERSION="${{ steps.extract.outputs.tag_version }}"

          if [ ! -f CHANGELOG.md ]; then
            echo "::error::CHANGELOG.md is missing"
            exit 1
          fi

          # Look for either "## [VERSION]" or "## [VERSION] - YYYY-MM-DD".
          if grep -E "^## \[$VERSION\]" CHANGELOG.md > /dev/null; then
            echo "Found CHANGELOG section for $VERSION"
            {
              echo "### CHANGELOG verification"
              echo ""
              echo "- Section \`## [$VERSION]\` found"
            } >> "$GITHUB_STEP_SUMMARY"
          else
            echo "::error::CHANGELOG.md has no section for [$VERSION]. Add a '## [$VERSION] - YYYY-MM-DD' header before tagging."
            exit 1
          fi

  release:
    name: Create GitHub Release
    runs-on: ubuntu-latest
    needs: [validate, verify-tag]
    timeout-minutes: 5
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0

      - name: Resolve tag ref
        id: tag
        shell: bash
        run: |
          if [ -n "${{ github.event.inputs.tag }}" ]; then
            echo "ref=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
          else
            echo "ref=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
          fi

      - name: Create release with auto-generated notes
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          TAG="${{ steps.tag.outputs.ref }}"

          # If the release already exists, leave it alone — re-runs should be idempotent.
          if gh release view "$TAG" > /dev/null 2>&1; then
            echo "Release $TAG already exists; skipping creation."
            {
              echo "### Release"
              echo ""
              echo "- Existing release for \`$TAG\` left unchanged"
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          gh release create "$TAG" \
            --title "$TAG" \
            --generate-notes \
            --verify-tag

          {
            echo "### Release"
            echo ""
            echo "- Created GitHub release \`$TAG\`"
          } >> "$GITHUB_STEP_SUMMARY"