Alexandr Kravchuk 0c6436d5da docs: add CI infrastructure fix guide for maintainers

Comprehensive documentation of CI issues and solutions for chalk maintainers.
Includes workflow changes that require direct repository access to apply.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

2026-03-17 12:15:32 +01:00

3.1 KiB

Raw Blame History

CI Infrastructure Fix Guide

Summary

This document explains the CI infrastructure issues in the chalk project and how to fix them.

Current Problems

1. Node.js 14 - xo Dependency Incompatibility ❌

Error:

SyntaxError: Unexpected token '&&=' in xo/node_modules/meow/build/index.js:29

Root Cause:

xo@0.57 dependency chain includes meow which uses ES2021 logical assignment operators (&&=)
These operators require Node.js 15+
Node.js 14 reached EOL on April 30, 2023

Evidence: CI has been failing on Node.js 14 since August 2025 (well before this PR).

2. Node.js 16 - Codecov Rate Limiting ❌

Error:

Error 429 - Rate limit reached. Please upload with the Codecov repository 
upload token to resolve issue.

Root Cause:

Codecov limits uploads without authentication token
Tests pass successfully; only the upload step fails
Setting fail_ci_if_error: true causes entire CI to fail

Solutions Applied

✅ Solution 1: Update package.json engines

File: package.json

- "node": "^12.17.0 || ^14.13 || >=16.0.0"
+ "node": ">=16.0.0"

Status: ✅ COMMITTED AND PUSHED

This correctly documents that Node.js 16+ is required.

📋 Solution 2: Update CI workflow (for maintainers)

File: .github/workflows/main.yml

Changes needed:

     matrix:
       node-version:
         - 18
         - 16
-        - 14

     - uses: codecov/codecov-action@v2
       if: matrix.node-version == 16
       with:
-        fail_ci_if_error: true
+        fail_ci_if_error: false

Why this wasn't pushed:

Modifying GitHub Actions workflows requires workflow scope
OAuth app used by GitHub Copilot doesn't have this scope
Maintainers with full repo access can apply this change

How maintainers can apply:

Edit .github/workflows/main.yml directly on GitHub
Or pull the branch and push with workflow scope
Or manually apply the diff above

Alternative Solutions (Optional)

Option A: Fix xo dependency

Lock xo and its dependencies to versions compatible with Node.js 14:

{
  "devDependencies": {
    "xo": "0.54.2"
  }
}

Not recommended: Node.js 14 is EOL, maintaining compatibility is not worthwhile.

Option B: Add CODECOV_TOKEN

Add Codecov token to GitHub repository secrets to avoid rate limits:

Get token from https://codecov.io/gh/chalk/chalk
Add to GitHub Secrets as CODECOV_TOKEN
Update workflow to use token

Recommended for long-term: But changing fail_ci_if_error to false is simpler.

Expected Results

After applying all fixes:

✅ Node.js 18: Tests pass
✅ Node.js 16: Tests pass (Codecov optional)
✅ No Node.js 14 failures (removed from matrix)

Testing

To verify locally:

# Install with Node.js 16+
nvm use 16
npm install
npm test  # Should pass

Node.js Support Policy

Current recommendation for chalk:

Support Node.js 16, 18, 20, 22 (active LTS and current releases)
Drop Node.js 14 (EOL April 2023)
Drop Node.js 12 (EOL April 2022)

This aligns with Node.js official support schedule and common industry practice.

3.1 KiB Raw Blame History