Files
swc/scripts/validate-binary.js
delino[bot]GitHubclaude[bot] <41898282+claude[bot]@users.noreply.github.com>ClaudeDonny/강동윤
3528ba9b2a fix(bindings): Improve ARM64 and Alpine Linux (musl) binary loading and validation (#11173)
## Summary

This PR addresses segmentation fault crashes reported for @swc/core on
ARM64 and Alpine Linux (musl) platforms:
- Fixes #11120 - @swc/core v1.13.19 segfaults on ARM64 during
postinstall
- Fixes #11126 - @swc/core v1.13.20 crashes on Alpine Linux (musl) with
SIGSEGV

## Problem

Users are experiencing segmentation faults when installing or using
@swc/core on:
- ARM64 architecture (both GNU and musl libc)
- Alpine Linux and other musl-based distributions

The issues appear during the postinstall validation phase when the
native binary is loaded.

## Root Cause Analysis

After investigation, the current swc_malloc configuration is actually
correct:
- Musl targets intentionally use the system allocator (not mimalloc or
jemalloc)
- This is because both mimalloc and jemalloc have known
segfault/threading issues on musl
- The crashes are likely related to binary loading/compatibility, not
memory allocation

## Changes

### 1. Enhanced Error Handling in postinstall.js
- Added `SWC_SKIP_VALIDATION` environment variable to allow users to
bypass validation
- Collect and display detailed system information (platform, arch, Node
version, libc) on errors
- Provide actionable troubleshooting guidance specific to ARM64/Alpine
users
- Better error messages to help diagnose issues

### 2. Documentation for swc_malloc
- Added comprehensive documentation explaining allocator selection
strategy
- Clarified that musl using system allocator is intentional and correct
- Documented why mimalloc and jemalloc don't work well with musl
- Added references to upstream issues for transparency

### 3. Binary Validation Script
Created `scripts/validate-binary.js` for CI/CD:
- Validates native binary can load successfully
- Tests core functionality (getTargetTriple, parseSync, transformSync)
- Provides detailed diagnostics on failure
- Catches binary loading issues before running full test suite

### 4. Enabled ARM64 Musl Testing in CI
- Uncommented and updated `test-linux-aarch64-musl-binding` job
- Added binary validation step using QEMU for ARM64 emulation
- Made this test a required dependency for the publish step
- Prevents publishing broken binaries for ARM64 musl

## Testing Strategy

The PR enables comprehensive testing for ARM64 musl in CI:
- Binary validation runs first to catch loading issues immediately
- Full test suite runs after validation passes
- Uses QEMU for ARM64 emulation on x86_64 runners
- Tests against node:lts-alpine Docker image

## User Impact

### Immediate Workaround
Users experiencing segfaults can now skip validation:
```bash
SWC_SKIP_VALIDATION=1 npm install @swc/core
```

### Better Diagnostics
On failure, users will see:
- Platform and architecture information
- Node.js version
- libc type and version
- Specific error details
- Links to related issues

### Future Prevention
CI will now catch ARM64/Alpine issues before release, preventing broken
versions from being published.

## Test Plan

- [x] cargo fmt --all (required by project guidelines)
- [ ] CI tests pass for all platforms
- [ ] ARM64 musl binary validation passes
- [ ] Verify postinstall error messages display correctly
- [ ] Test SWC_SKIP_VALIDATION environment variable

## Notes

This is marked as a draft because:
1. Need to verify CI passes with the new ARM64 musl tests enabled
2. Want to get feedback on the approach before merging
3. May need to adjust timeout values for QEMU-emulated tests

The changes are conservative and focused on:
- Better error reporting and diagnostics
- User workarounds for existing issues
- Preventing future releases with binary loading problems

This does NOT change the allocator configuration, as that is already
correct.

## References

- https://github.com/microsoft/mimalloc/issues/556 - mimalloc issues on
ARM64 musl
- https://github.com/jemalloc/jemalloc/issues/1443 - jemalloc threading
issues with musl
- https://www.tweag.io/blog/2023-08-10-rust-static-link-with-mimalloc/ -
Best practices for musl

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Donny/강동윤 <[email protected]>
2025-10-24 07:07:03 +09:00

154 lines
4.9 KiB
JavaScript
Executable File

#!/usr/bin/env node
"use strict";
/**
* Binary validation script for CI/CD pipelines.
*
* This script validates that the @swc/core native binary can be loaded
* and works correctly on the target platform. It's designed to catch
* segmentation faults and other binary loading issues early in the build
* process before publishing to npm.
*
* Usage:
* node scripts/validate-binary.js [path-to-swc-core-dir]
*
* Exit codes:
* 0 - Binary is valid and works correctly
* 1 - Binary failed to load or validation failed
*/
const path = require("path");
const os = require("os");
// Determine the path to @swc/core
const swcCorePath = process.argv[2] || path.join(__dirname, "..", "packages", "core");
console.log("=== SWC Binary Validation ===");
console.log(`Platform: ${process.platform}`);
console.log(`Architecture: ${process.arch}`);
console.log(`Node version: ${process.version}`);
console.log(`SWC Core path: ${swcCorePath}`);
// Attempt to get libc information
let libcInfo = "unknown";
try {
if (process.platform === "linux") {
const report = process.report?.getReport();
if (report?.header?.glibcVersionRuntime) {
libcInfo = `glibc ${report.header.glibcVersionRuntime}`;
} else {
// If no glibc version, likely musl
libcInfo = "likely musl";
}
}
} catch (e) {
// Ignore errors getting libc info
}
console.log(`Libc: ${libcInfo}`);
console.log();
let binding;
let validationPassed = false;
try {
console.log("Loading @swc/core binding...");
binding = require(path.join(swcCorePath, "binding.js"));
console.log("✓ Binding loaded successfully");
// Test 1: Get target triple (if available)
if (typeof binding.getTargetTriple === "function") {
console.log("\nTest 1: Checking target triple...");
const triple = binding.getTargetTriple();
console.log(`✓ Target triple: ${triple}`);
if (!triple || triple.length === 0) {
throw new Error("getTargetTriple returned empty string");
}
} else {
console.log("\nTest 1: getTargetTriple not available (older version)");
}
// Test 2: Parse some simple code
console.log("\nTest 2: Testing parseSync...");
const testCode = 'console.log("hello world");';
const result = binding.parseSync(
testCode,
Buffer.from(JSON.stringify({ syntax: "ecmascript" }))
);
if (!result) {
throw new Error("parseSync returned null/undefined");
}
console.log("✓ parseSync works correctly");
// Test 3: Transform some code
console.log("\nTest 3: Testing transformSync...");
const transformResult = binding.transformSync(
testCode,
false,
Buffer.from(JSON.stringify({
jsc: {
parser: {
syntax: "ecmascript"
},
target: "es2015"
}
}))
);
if (!transformResult || !transformResult.code) {
throw new Error("transformSync did not return valid result");
}
console.log("✓ transformSync works correctly");
validationPassed = true;
console.log("\n=== Validation PASSED ===");
console.log("All tests completed successfully!");
} catch (error) {
console.error("\n=== Validation FAILED ===");
console.error("Error:", error.message);
if (error.stack) {
console.error("\nStack trace:");
console.error(error.stack);
}
console.error("\n--- System Information ---");
console.error(`Platform: ${process.platform}`);
console.error(`Architecture: ${process.arch}`);
console.error(`Node version: ${process.version}`);
console.error(`Libc: ${libcInfo}`);
console.error(`CPU cores: ${os.cpus().length}`);
console.error(`Total memory: ${(os.totalmem() / 1024 / 1024 / 1024).toFixed(2)} GB`);
console.error(`Free memory: ${(os.freemem() / 1024 / 1024 / 1024).toFixed(2)} GB`);
// Check if this is a known issue
if (process.arch === "arm64" || process.arch === "arm") {
console.error("\n--- Potential Issue ---");
console.error("ARM architecture detected. If you're seeing segmentation faults,");
console.error("this may be related to binary compatibility issues.");
console.error("See: https://github.com/swc-project/swc/issues/11120");
console.error(" https://github.com/swc-project/swc/issues/11126");
}
if (libcInfo.includes("musl")) {
console.error("\n--- Potential Issue ---");
console.error("musl libc detected (Alpine Linux). If you're seeing segmentation faults,");
console.error("this may be related to binary compatibility issues.");
console.error("See: https://github.com/swc-project/swc/issues/11126");
}
process.exit(1);
}
if (!validationPassed) {
console.error("\n=== Validation FAILED ===");
console.error("Validation did not complete successfully");
process.exit(1);
}
process.exit(0);