docs-verify.yml

name: Verify docs

on:
  pull_request:
    branches: [develop]
    paths:
      - 'web/sites/guides/src/content/docs/v4-0-0/**'
      - 'web/sites/guides/scripts/verify-docs/**'
      - 'web/sites/guides/package.json'
      - 'web/sites/guides/src/sidebars/v4-0-0.json'
      - '.github/workflows/docs-verify.yml'
      # The harness exercises the checkout's CLI module (overlaid onto the
      # installed brew CLI below), so CLI changes can flip {test:cli} blocks
      # red — run the docs gate when the CLI module changes (#3042).
      - 'cli/lucli/**'

jobs:
  verify:
    # ubuntu-latest with Linuxbrew. Was macos-latest, but Node 22's test-runner
    # workers on macos-latest ARM64 have a broken child_process.spawn: ENOENT
    # on every exec, even /bin/bash, even with absolute paths that statSync
    # confirms exist. Direct `node -e "spawn('wheels')"` works fine; only
    # --test worker contexts fail. The wheels formula supports Linux via the
    # same install flow, and Linux posix_spawn is unaffected.
    runs-on: ubuntu-latest
    timeout-minutes: 20

    env:
      # Attestation mode (#3042): consumed by lib/exec.mjs
      # wheelsBinaryAttestation() and echoed by the smoke-test step, so the
      # log states exactly whose CLI code the {test:cli}/{test:tutorial}
      # blocks dispatched to. github.sha is hex-only (injection-safe).
      WHEELS_ATTEST_MODE: "checkout cli/lucli module overlay @ ${{ github.sha }} (released LuCLI runtime via brew)"

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

      - name: Set up pnpm
        uses: pnpm/action-setup@v5
        with:
          version: 10.23.0

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: pnpm
          cache-dependency-path: web/pnpm-lock.yaml

      - name: Install Node deps
        working-directory: web
        run: pnpm install --frozen-lockfile

      - name: Set up Linuxbrew
        uses: Homebrew/actions/setup-homebrew@master

      - name: Install Wheels CLI
        env:
          # Homebrew 5.x's Linux sandbox needs a rootless bwrap, which
          # ubuntu-latest runners don't provide (and 24.04's unprivileged
          # userns restrictions make it unreliable even when installed).
          # The ephemeral runner is already isolation enough for CI.
          HOMEBREW_NO_SANDBOX_LINUX: "1"
        run: |
          brew tap wheels-dev/wheels || true
          # Homebrew 5.1+ refuses to load formulae from untrusted third-party
          # taps; trust must be granted explicitly (no-op on older brew).
          brew trust wheels-dev/wheels || true
          brew install wheels

      - name: Patch wheels wrapper JAVA_HOME for Linux
        # The homebrew formula's wrapper hardcodes a macOS bundle path:
        #   JAVA_HOME="...openjdk@21/libexec/openjdk.jdk/Contents/Home"
        # On Linux, openjdk@21's opt_libexec IS the JAVA_HOME directly (no
        # macOS bundle nesting). Strip the trailing bundle path so the
        # wrapper's inner exec of $JAVA_HOME/bin/java resolves.
        # Follow-up: fix the formula to branch the export on OS.
        run: |
          WRAPPER="$(brew --prefix wheels)/bin/wheels"
          sed -i 's|/openjdk.jdk/Contents/Home||g' "$WRAPPER"
          grep JAVA_HOME "$WRAPPER"

      - name: Overlay checkout CLI module (branch attestation)
        # Binary attestation (#3042): `wheels` is the released LuCLI runtime
        # plus a CFML module — and the module IS this repo's cli/lucli/ (the
        # brew formula ships it verbatim as wheels-module-<ver>.tar.gz, plus
        # vendor/wheels/ staged inside it). The wrapper installed above syncs
        # that released module to $HOME/.wheels/modules/wheels the first time
        # a non-intercepted command runs. Write that directory from the
        # CHECKOUT instead, before anything triggers the first-run sync, so
        # every `wheels` invocation in this job dispatches to the branch's
        # CLI module. {test:cli} blocks then attest to the tree under review:
        # a branch change to a command's output flips its block red.
        #
        # The .module-version marker is copied from the formula so the
        # wrapper's version-diff sync never overwrites the overlay with the
        # released module mid-job. (Note: `wheels --version` and `--help`
        # are intercepted in the wrapper itself — kept in sync with
        # Module.cfc — so those two surfaces still answer with released
        # wrapper text; every real subcommand runs branch code.)
        #
        # Out of scope: the LuCLI runtime stays at the released version the
        # formula pins — runtime changes ship via LuCLI releases, not this
        # repo's PRs.
        run: |
          MODULE_DST="$HOME/.wheels/modules/wheels"
          rm -rf "$MODULE_DST"
          mkdir -p "$MODULE_DST/vendor/wheels"
          cp -R "$GITHUB_WORKSPACE/cli/lucli/." "$MODULE_DST/"
          cp -R "$GITHUB_WORKSPACE/vendor/wheels/." "$MODULE_DST/vendor/wheels/"
          cp "$(brew --prefix wheels)/share/wheels/.module-version" "$MODULE_DST/.module-version"
          echo "Overlaid $MODULE_DST from checkout (marker: $(cat "$MODULE_DST/.module-version"))"

      - name: Smoke-test the CLI (binary attestation)
        # verify-docs.mjs prints the full attestation line (binary path,
        # resolution source, version, and WHEELS_ATTEST_MODE) at run start;
        # this step is the early, human-greppable copy of the same facts.
        run: |
          command -v wheels
          wheels --version
          echo "attest mode: $WHEELS_ATTEST_MODE"

      - name: Run harness unit tests
        working-directory: web/sites/guides
        # Runs on Node 22 (no longer pinned to Node 20). The "spawn ENOENT"
        # that looked like a Node 22 posix_spawn regression was actually
        # caused by `wheels new` exiting 0 after a framework-not-found
        # error, leaving the fixture cwd missing; Node's spawn then reports
        # ENOENT against the program instead of the cwd. Setting
        # WHEELS_FRAMEWORK_PATH at the checked-out repo's vendor/wheels
        # lets `wheels new` succeed, which makes fixture cwds real. See
        # #2178 for the full root-cause write-up.
        #
        # Still soft-fail: surfaces the remaining tutorial-driver fixture
        # issues (e.g., blog-tutorial's lucee.json emission). Drop
        # continue-on-error once those are fixed.
        continue-on-error: true
        env:
          WHEELS_FRAMEWORK_PATH: ${{ github.workspace }}/vendor/wheels
        run: |
          export LUCLI_HOME="$HOME/.wheels"
          pnpm test:docs-harness

      - name: Verify v4 docs
        working-directory: web/sites/guides
        # Soft-fail: at 290 tagged blocks / 4-way concurrency, LuCLI's
        # lucee.json writer + concurrent JVM startup races cause ~24
        # blocks to consistently ENOENT even with in-driver retries and
        # concurrency caps. Tracked as framework gap #11 (atomic
        # lucee.json write upstream). 266/290 pass reliably; the
        # remaining 24 are infrastructure flakes, not content regressions.
        # Until the upstream fix ships, local `pnpm verify:docs` is the
        # canonical content gate (it runs serially and passes 290/290).
        continue-on-error: true
        run: |
          export LUCLI_HOME="$HOME/.wheels"
          pnpm verify:docs

      - name: Build guides site
        working-directory: web/sites/guides
        run: pnpm build