docs(web/guides): add v4 Overriding Core Methods guide (#3343) #275
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |