css-enforcement.yml

# ============================================================
# STD-TOOLCHAIN-001 v1.3 — CSS / Build Limits Enforcement
# Workflow ref: see caller for pin; never use @main in production.
# Profile: wp-plugin | standalone-react | standalone-node
# ============================================================
#
# STATICALLY ENFORCED HERE:
#   - CSS-LINT-001: Stylelint
#   - CSS-PERF-001/002/003/004: prohibited properties (blur, backdrop-filter, etc.)
#   - CSS-SPEC-001: no ID selectors
#   - CSS-TOKEN-001: no hardcoded hex colors outside token definitions
#   - CSS-TYPE-001: no px font sizes
#   - CSS-A11Y-001: no outline:none or outline:0
#   - CSS-BUILD-001: production build
#   - CSS-BUNDLE-001: gzipped CSS bundle size limit
#
# VERIFIED VIA PRESENCE VALIDATION (warn-only pending §4 fixtures):
#   - stylelint config present (for standalone profiles)
#
# NOT MACHINE-CHECKED (requires conformance test suite — §6):
#   - Stylelint extends correct config per profile
#   - @wordpress/stylelint-config used in WP repos
#
# Caller example: see caller-templates/standards-php-wordpress.yml
# ============================================================

name: CSS enforcement (STD-TOOLCHAIN-001 v1.3)

on:
  workflow_call:
    inputs:
      repo_type:
        description: 'Repo type: wp-plugin | standalone-react | standalone-node'
        required: false
        type: string
        default: standalone-react
      profile_version:
        description: 'Profile version to validate against (e.g. v1).'
        required: false
        type: string
        default: v1
      enforcement_mode:
        description: 'gate (fail-closed) | advisory (warn-only) | (empty = legacy mode fallback)'
        required: false
        type: string
        default: ''
      mode:
        description: 'DEPRECATED: use enforcement_mode.'
        # REMOVAL: 2027-01-01 — all callers must migrate to enforcement_mode before this date
        required: false
        type: string
        default: draft
      node-version:
        description: 'Node.js version to use.'
        required: false
        type: string
        default: '22'
      css-size-limit-kb:
        description: 'Max gzipped CSS bundle size in KB (CSS-BUNDLE-001, default 50).'
        required: false
        type: number
        default: 50
    secrets:
      COMPOSER_RESOLVER_PRIVATE_KEY:
        required: true

jobs:
  enforce:
    name: CSS standards conformance
    runs-on: ubuntu-latest

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

      - name: Parse standards exceptions (.standards/standards-exceptions.yml)
        id: exceptions
        # GitHub's YAML parser breaks on Python heredoc syntax when code is at column 0.
        # Script is stored in an env var; textwrap.dedent strips the YAML-induced indentation.
        env:
          PARSE_SCRIPT: |
            import sys, os, textwrap
            from datetime import date
            try:
                import yaml
            except ImportError:
                print("::error::PyYAML not available after install attempt — cannot parse exceptions file")
                sys.exit(1)
            today = date.today().isoformat()
            active = []
            expired = []
            malformed = []
            try:
                with open(".standards/standards-exceptions.yml") as f:
                    data = yaml.safe_load(f) or {}
            except Exception as e:
                print(f"::error::standards-exceptions.yml malformed — {e}")
                sys.exit(1)
            exceptions = data.get("exceptions", [])
            if not isinstance(exceptions, list):
                print("::error::standards-exceptions.yml malformed — 'exceptions' must be a list")
                sys.exit(1)
            for exc in exceptions:
                if not isinstance(exc, dict):
                    malformed.append("<no-id>")
                    continue
                required_fields = ["id", "rule", "reason", "owner", "expires", "approval"]
                missing = [f for f in required_fields if f not in exc]
                if missing:
                    malformed.append(exc.get("id", "<no-id>"))
                    continue
                expires = exc["expires"]
                if expires is None:
                    malformed.append(exc.get("id", "<no-id>"))
                    continue
                if not isinstance(expires, str):
                    if hasattr(expires, "isoformat"):
                        expires = expires.isoformat()
                    else:
                        malformed.append(exc.get("id", "<no-id>"))
                        continue
                if expires < today:
                    expired.append(exc["id"])
                else:
                    active.append(exc["id"])
                    print(f"::notice::Active exception: {exc['id']} — {exc['rule']} — expires {expires} — {exc['reason']}")
            if expired:
                print(f"::error::Expired exceptions (fail-closed per STD-TOOLCHAIN-001 §8): {', '.join(expired)}")
                sys.exit(1)
            if malformed:
                print(f"::error::Malformed exception entries: {', '.join(malformed)}")
                sys.exit(1)
            with open(os.environ["GITHUB_OUTPUT"], "a") as out:
                out.write(f"active_exceptions={','.join(active)}\n")
        shell: bash
        run: |
          set -euo pipefail
          if [ ! -f ".standards/standards-exceptions.yml" ]; then
            echo "active_exceptions=" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          pip3 install pyyaml --quiet
          python3 -c "import textwrap, os; exec(textwrap.dedent(os.environ['PARSE_SCRIPT']))"

      - name: Warn on deprecated 'mode' input
        if: inputs.enforcement_mode == ''
        shell: bash
        run: |
          echo "::warning::DEPRECATED: 'mode' input will be removed 2027-01-01 — migrate to 'enforcement_mode: gate | advisory' (STD-TOOLCHAIN-001 §3)"

      - name: Presence validation — CSS/stylelint config
        # WARN-ONLY — flips to required after self-test fixtures authored (STD-TOOLCHAIN-001 §4)
        env:
          INPUT_REPO_TYPE: ${{ inputs.repo_type }}
        shell: bash
        run: |
          set -euo pipefail
          repo_type="$INPUT_REPO_TYPE"
          # Standalone profiles require a stylelint config
          if [ "$repo_type" = "standalone-react" ] || [ "$repo_type" = "standalone-node" ]; then
            if [ ! -f ".stylelintrc.json" ] && [ ! -f "stylelint.config.js" ] && [ ! -f ".stylelintrc.js" ] && [ ! -f ".stylelintrc.yml" ]; then
              echo "::warning::PRESENCE: no stylelint config found (standalone profile requires .stylelintrc.json or stylelint.config.js)"
            fi
          fi

      - name: Setup Node.js
        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4
        with:
          node-version: ${{ inputs['node-version'] }}

      - name: Enable corepack (pnpm)
        if: hashFiles('package.json') != ''
        shell: bash
        run: corepack enable

      - name: Mint read token (composer-resolver)
        if: hashFiles('package.json') != ''
        id: read-token
        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
        with:
          app-id: ${{ vars.COMPOSER_RESOLVER_CLIENT_ID }}
          private-key: ${{ secrets.COMPOSER_RESOLVER_PRIVATE_KEY }}
          owner: Starisian-Technologies

      - name: Configure Git auth for private dependencies
        if: hashFiles('package.json') != ''
        env:
          GH_TOKEN: ${{ steps.read-token.outputs.token }}
        shell: bash
        run: |
          git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf "https://github.com/"

      - name: Install dependencies
        if: hashFiles('package.json') != ''
        env:
          INPUT_EM: ${{ inputs.enforcement_mode }}
          INPUT_LM: ${{ inputs.mode }}
        shell: bash
        run: |
          em="$INPUT_EM"
          lm="$INPUT_LM"
          if [ "$em" = "gate" ] || { [ -z "$em" ] && { [ "$lm" = "development" ] || [ "$lm" = "production" ]; }; }; then
            pnpm install --frozen-lockfile
          else
            pnpm install
          fi

      - name: Determine block behavior
        id: mode
        env:
          INPUT_EM: ${{ inputs.enforcement_mode }}
          INPUT_LM: ${{ inputs.mode }}
        shell: bash
        run: |
          # enforcement_mode takes precedence; fall back to legacy mode input when empty
          em="$INPUT_EM"
          lm="$INPUT_LM"
          block=""
          if [ "$em" = "gate" ]; then
            block="true"
          elif [ "$em" = "advisory" ]; then
            block="false"
          elif [ -z "$em" ]; then
            # REMOVAL: 2027-01-01 — legacy mode bridge; callers must migrate to enforcement_mode
            case "$lm" in
              draft)                    block="false" ;;
              development|production)   block="true"  ;;
              *)
                echo "::error::Unknown mode '$lm' — migrate to enforcement_mode: gate | advisory (STD-TOOLCHAIN-001 §3)"
                exit 1 ;;
            esac
          else
            echo "::error::Unknown enforcement_mode '$em' — expected gate | advisory (STD-TOOLCHAIN-001 §3)"
            exit 1
          fi
          echo "block=$block" >> "$GITHUB_OUTPUT"
          echo "BLOCK_MODE=$block" >> "$GITHUB_ENV"

      - name: CSS-LINT-001 — Stylelint
        if: (hashFiles('.stylelintrc*') != '' || hashFiles('stylelint.config.*') != '') && hashFiles('package.json') != ''
        shell: bash
        run: |
          set -euo pipefail
          if ! pnpm exec stylelint "**/*.css" "**/*.scss" "**/*.less" \
               --ignore-path .gitignore \
               --max-warnings 0 2>&1; then
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::CSS-LINT-001: Stylelint violations found"
              exit 1
            else
              pnpm exec stylelint "**/*.css" "**/*.scss" "**/*.less" \
                --ignore-path .gitignore || true
              echo "::warning::CSS-LINT-001: Stylelint violations (non-blocking)"
            fi
          fi

      - name: CSS-PERF-001 — no prohibited CSS properties
        shell: bash
        run: |
          set -euo pipefail
          violations=()

          check_pattern() {
            local label="$1" pattern="$2"
            local hits
            hits=$(grep -Prn \
              --include='*.css' --include='*.scss' --include='*.less' \
              --exclude-dir=node_modules --exclude-dir=vendor \
              "$pattern" . 2>/dev/null || true)
            if [ -n "$hits" ]; then
              violations+=("$label:"$'\n'"$hits")
            fi
          }

          check_pattern "CSS-PERF-001 filter:blur" 'filter\s*:\s*blur\s*\('
          check_pattern "CSS-PERF-002 backdrop-filter" 'backdrop-filter\s*:'
          check_pattern "CSS-PERF-004 animation on layout properties" \
            'animation\s*:[^;]*(width|height|top|left|right|bottom|margin|padding)'
          check_pattern "CSS-PERF-004 transition on layout properties" \
            'transition\s*:[^;]*(width|height|top|left|right|bottom|margin|padding)'

          if [ ${#violations[@]} -gt 0 ]; then
            msg="Prohibited CSS performance patterns found:"$'\n'"${violations[*]}"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      - name: CSS-SPEC-001 — no ID selectors in stylesheets
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            '^[[:space:]]*#[a-zA-Z][a-zA-Z0-9_-]*[[:space:]]*\{|,[[:space:]]*#[a-zA-Z]' \
            . 2>/dev/null || true)
          if [ -n "$hits" ]; then
            msg=$'CSS-SPEC-001: ID selectors found — use class selectors only:\n'"$hits"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      - name: CSS-TOKEN-001 — no hardcoded hex colors outside token definitions
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            '^\s*(color|background(-color)?|border(-color)?|fill|stroke)\s*:\s*#[0-9a-fA-F]{3,8}' \
            . 2>/dev/null \
            | grep -Pv ':root' \
            | grep -Pv 'tokens\.' \
            | grep -Pv '_tokens\.' \
            || true)
          if [ -n "$hits" ]; then
            msg=$'CSS-TOKEN-001: hardcoded hex colors found — use CSS custom properties:\n'"$hits"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      - name: CSS-TYPE-001 — no px font sizes
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            'font-size\s*:\s*[0-9]+px' \
            . 2>/dev/null || true)
          if [ -n "$hits" ]; then
            msg=$'CSS-TYPE-001: px font sizes found — use rem units:\n'"$hits"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      - name: CSS-A11Y-001 — no outline:none or outline:0
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            'outline\s*:\s*(none|0)' \
            . 2>/dev/null || true)
          if [ -n "$hits" ]; then
            msg=$'CSS-A11Y-001: outline:none or outline:0 found — provide visible focus replacement:\n'"$hits"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      - name: CSS-BUILD-001 — production build
        if: hashFiles('package.json') != ''
        shell: bash
        run: |
          set -euo pipefail
          if ! pnpm run --if-present build 2>&1; then
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::CSS-BUILD-001: CSS production build failed"
              exit 1
            else
              echo "::warning::CSS-BUILD-001: CSS production build failed (non-blocking)"
            fi
          fi

      - name: CSS-BUNDLE-001 — total bundle size limit check
        env:
          CSS_SIZE_LIMIT_KB: ${{ inputs['css-size-limit-kb'] }}
        shell: bash
        run: |
          set -euo pipefail
          limit_kb="$CSS_SIZE_LIMIT_KB"
          limit_bytes=$(( limit_kb * 1024 ))

          css_dir=""
          for candidate in dist build out; do
            if [ -d "$candidate" ]; then css_dir="$candidate"; break; fi
          done

          if [ -z "$css_dir" ]; then
            echo "::notice::CSS-BUNDLE-001: no build output directory found — skipping"
            exit 0
          fi

          total_bytes=0
          while IFS= read -r -d '' file; do
            size=$(gzip -c "$file" | wc -c)
            total_bytes=$(( total_bytes + size ))
          done < <(find "$css_dir" -name '*.css' -not -name '*.map' -print0)

          total_kb=$(( total_bytes / 1024 ))
          echo "::notice::CSS-BUNDLE-001: total CSS bundle ${total_kb} KB gzipped (limit ${limit_kb} KB)"

          if [ "$total_bytes" -gt "$limit_bytes" ]; then
            msg="CSS-BUNDLE-001: total CSS bundle ${total_kb} KB gzipped exceeds limit of ${limit_kb} KB"
            if [ "$BLOCK_MODE" = "true" ]; then
              echo "::error::$msg"; exit 1
            else
              echo "::warning::$msg"
            fi
          fi

      # ── Bucket-3: warn-only gaps (Directive 5 — pending ADR ratification) ──

      - name: CSS-PERF-003 (warn-only) — large box-shadow values
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            'box-shadow\s*:[^;]*\s[1-9][0-9]{2,}px' \
            . 2>/dev/null || true)
          [ -n "$hits" ] && echo "::warning::CSS-PERF-003 (advisory): large px value in box-shadow — verify spread/blur radius is intentional:"$'\n'"$hits" || true

      - name: CSS-PERF-005 (warn-only) — text-shadow on body text
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            'text-shadow\s*:' \
            . 2>/dev/null || true)
          [ -n "$hits" ] && echo "::warning::CSS-PERF-005 (advisory): text-shadow found — verify not applied to body/paragraph text:"$'\n'"$hits" || true

      - name: CSS-MAINT-001 (warn-only) — !important outside utility files
        shell: bash
        run: |
          set -euo pipefail
          hits=$(grep -Prn \
            --include='*.css' --include='*.scss' --include='*.less' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            '!important' \
            . 2>/dev/null \
            | grep -Pv 'utilities?\.(css|scss|less)|_utils\.|_helpers?\.' || true)
          [ -n "$hits" ] && echo "::warning::CSS-MAINT-001 (advisory): !important outside utility files:"$'\n'"$hits" || true

      - name: CSS-PERF-006 (warn-only) — @font-face missing font-display
        shell: bash
        run: |
          set -euo pipefail
          missing=$(grep -PrlZn \
            --include='*.css' --include='*.scss' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            '@font-face' \
            . 2>/dev/null \
            | xargs -0 -r grep -PZL 'font-display\s*:' 2>/dev/null \
            | xargs -0 -r printf '%s\n' \
            || true)
          [ -n "$missing" ] && echo "::warning::CSS-PERF-006 (advisory): @font-face without font-display in:"$'\n'"$missing" || true

      - name: CSS-A11Y-002 (warn-only) — @keyframes without prefers-reduced-motion
        shell: bash
        run: |
          set -euo pipefail
          files=$(grep -Prln \
            --include='*.css' --include='*.scss' \
            --exclude-dir=node_modules --exclude-dir=vendor \
            '@keyframes' \
            . 2>/dev/null || true)
          if [ -n "$files" ]; then
            missing=$(echo "$files" | xargs grep -PL 'prefers-reduced-motion' 2>/dev/null || true)
            [ -n "$missing" ] && echo "::warning::CSS-A11Y-002 (advisory): @keyframes without prefers-reduced-motion guard in:"$'\n'"$missing" || true
          fi