|
| 1 | +# 2025-10-06: Renovate Docs and Infra Deps |
| 2 | + |
| 3 | +## Problem |
| 4 | + |
| 5 | +The Renovate PR for `docs-and-infra-deps` introduced several dependency updates. These updates caused two separate failures in the CI/CD pipeline: one in the GitHub Actions workflows and another in the Cloudflare Pages deployment for the documentation site. |
| 6 | + |
| 7 | +## GitHub Actions Workflow Failures |
| 8 | + |
| 9 | +### Observation |
| 10 | + |
| 11 | +The `Code Quality`, `Smoke Tests`, and other workflows began failing with the error `Error: Unable to locate executable file: pnpm`. This coincided with the upgrade of the `actions/setup-node` action from `v4` to `v5`. |
| 12 | + |
| 13 | +### Diagnosis and Fix |
| 14 | + |
| 15 | +Version 5 of `actions/setup-node` automatically detects the project's package manager from the root `package.json` (`pnpm` in this case) and attempts to configure it. However, our workflows were set up to enable `corepack` (which makes `pnpm` available) *after* the `setup-node` step. The action was therefore running before `pnpm` was in the environment's `PATH`. |
| 16 | + |
| 17 | +The solution was to modify the workflows to ensure `corepack` is enabled *before* `setup-node` runs. |
| 18 | + |
| 19 | +**Changes Implemented:** |
| 20 | + |
| 21 | +1. Added a dedicated "Enable Corepack" step (`run: corepack enable`) before the "Setup Node.js" step. |
| 22 | +2. Added `cache: 'pnpm'` to the `setup-node` step to speed up dependency installation. |
| 23 | +3. Removed the redundant `corepack enable` from the subsequent `pnpm install` step. |
| 24 | + |
| 25 | +This fix was applied to all relevant workflow files and resolved the GitHub Actions failures. |
| 26 | + |
| 27 | +## Cloudflare Docs Deployment Failure |
| 28 | + |
| 29 | +### Observation |
| 30 | + |
| 31 | +After fixing the GitHub Actions workflows, the Cloudflare Pages deployment for the docs site started failing with a new error during the `astro build` step: `Dynamic require of "path" is not supported`. |
| 32 | + |
| 33 | +The stack trace pointed to `@fujocoded/expressive-code-output`, which had been updated by Renovate from `0.0.1` to `0.1.0`. |
| 34 | + |
| 35 | +### Attempt 1: Dynamic Import |
| 36 | + |
| 37 | +**Hypothesis:** The error suggested a CommonJS vs. ES Module compatibility issue. It seemed possible that the new version of the package was a CJS module being improperly imported into our ESM-based Astro configuration (`ec.config.mjs`). |
| 38 | + |
| 39 | +**Action:** I modified `docs/ec.config.mjs` to use a dynamic `await import(...)` for `@fujocoded/expressive-code-output`, as Astro's configuration files support top-level await. |
| 40 | + |
| 41 | +**Result:** The local development server failed with the exact same error. This proved the issue was not with how the module was being imported. |
| 42 | + |
| 43 | +### Attempt 2: Deeper Investigation |
| 44 | + |
| 45 | +**Hypothesis:** The problem must be internal to the package itself. |
| 46 | + |
| 47 | +**Action: ** Using the full file path from the local error log, I inspected the contents of the problematic file: `.../node_modules/.pnpm/@[email protected]/node_modules/@fujocoded/expressive-code-output/dist/index.js`. |
| 48 | + |
| 49 | +**Finding:** The bundled JavaScript file contains a compatibility shim for `require`. The error is thrown by this shim because a `require('path')` call was not correctly processed and replaced by the package's build tool. This is a build issue within the dependency itself and cannot be fixed by configuration changes in our project. |
| 50 | + |
| 51 | +### Conclusion |
| 52 | + |
| 53 | +The investigation confirmed a bug within the `@fujocoded/[email protected]` package. After discussing the findings, I have reverted the attempts to fix it, and will now investigate a proper solution myself. |
| 54 | + |
| 55 | +### Update: Pinpointing the Bug |
| 56 | + |
| 57 | +After further investigation, the precise issue was identified. The `package.json` for `@fujocoded/expressive-code-output` has its `exports` map conditions swapped. |
| 58 | + |
| 59 | +- The `import` condition points to `./dist/index.js`, which incorrectly contains CommonJS `require()` calls. |
| 60 | +- The `require` condition points to `./dist/index.cjs`, which is the correct CommonJS bundle. |
| 61 | + |
| 62 | +This is a packaging bug in the dependency. When our ESM-based Astro build tries to import the package, it's served the wrong file, causing the build to fail. |
| 63 | + |
| 64 | +### Final Resolution |
| 65 | + |
| 66 | +After reviewing the dependency's repository and observing an unstable versioning history (`1.0.0` then `0.1.0`), the decision was made to revert to the last known stable version to ensure stability and avoid further issues. The `pnpm patch` solution was considered but ultimately rejected in favor of using a stable version. |
| 67 | + |
| 68 | +The `@fujocoded/expressive-code-output` package has been downgraded to `0.0.1`. |
![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4&size=40){kind=avatar}
0 commit comments