use-m/bun-issues/BUN_ISSUES_SUMMARY.md

use-m: dynamically import any JavaScript module

# Bun Import Resolution Issues Investigation - Final Report

## Summary
This document contains the results of a comprehensive investigation into import resolution differences between Bun and Node.js, including minimal reproducible test cases.

**🔍 INVESTIGATION COMPLETE**: After extensive testing with isolated packages and multiple configurations, **we were unable to reproduce the originally suspected package.json access bug**.

## Version Information
- **Bun**: v1.2.16 
- **Node.js**: v20.19.4
- **Investigation Date**: August 2025
- **Test Environment**: macOS Darwin 24.5.0

## Investigation Results

### Test Infrastructure Created
We created a comprehensive test suite with three isolated npm packages:

1. **library-with-exports**: Full explicit exports (all files exported as workaround)
2. **library-limited-exports**: Only `"."` defined (minimal exports configuration)
3. **library-without-exports**: No exports restrictions (baseline test)

Each package contains identical test files:
- `test.js` (ESM)
- `test.cjs` (CommonJS)  
- `test.mjs` (ESM)
- `package.json`

### Test Results Summary

**All tests run in both CJS and MJS environments:**

| Library Type | Node.js Behavior | Bun Behavior | Status |
|--------------|------------------|--------------|---------|
| **library-with-exports** | ✅ All imports work | ✅ All imports work | **IDENTICAL** |
| **library-limited-exports** | ❌ All subpaths blocked | ❌ All subpaths blocked | **IDENTICAL** |
| **library-without-exports** | ✅ All imports work | ✅ All imports work | **IDENTICAL** |

### Key Findings

#### 1. **No Package Exports Validation Bug Found** ✅
- **Expected Bug**: Bun allows `require("package/package.json")` when not explicitly exported
- **Actual Result**: Both Bun and Node.js correctly block unauthorized subpath access
- **Test Cases**: All 48 test scenarios (3 libraries × 4 files × 2 test environments × 2 runtimes)
- **Conclusion**: **No difference in behavior between runtimes**

#### 2. **Proper Export Validation in Both Runtimes** ✅
Both Node.js and Bun correctly implement package exports specification:
- ✅ Block access to non-exported subpaths
- ✅ Allow access to explicitly exported paths
- ✅ Allow access when no exports are defined

#### 3. **Error Message Differences** ⚠️
Minor difference in error reporting (not functionality):
- **Node.js**: `"Package subpath './file' is not defined by exports"`
- **Bun**: `"Cannot find module 'package/file'"`

Both errors correctly prevent unauthorized access, but Node.js provides more detailed debugging information.

### Test Files Created

**Test Libraries:**
- `library-with-exports/` - Full exports configuration
- `library-limited-exports/` - Minimal exports (only "." defined)  
- `library-without-exports/` - No exports restrictions

**Test Runners:**
- `test-imports.mjs` - ESM environment tests
- `test-imports.cjs` - CJS environment tests
- `test-main-vs-subpath.mjs` - Main vs subpath access comparison
- `test-specific-bug.mjs` - Specific bug demonstration template

**Package Configurations:**
```json
// library-with-exports/package.json (workaround)
{
  "exports": {
    "./test.js": "./test.js",
    "./test.cjs": "./test.cjs", 
    "./test.mjs": "./test.mjs",
    "./package.json": "./package.json"
  }
}

// library-limited-exports/package.json (minimal)
{
  "exports": {
    ".": {
      "import": "./test.mjs",
      "require": "./test.cjs"
    }
  }
}

// library-without-exports/package.json (baseline)
{
  "name": "library-without-exports",
  "version": "1.0.0"
  // No exports field
}
```

## Running the Test Suite

```bash
# Navigate to test directory
cd /Users/konard/Code/Archive/link-foundation/use-m/bun-issues

# Run comprehensive tests in both environments
echo "=== MJS Environment ===" && node test-imports.mjs && echo "=== Bun MJS ===" && bun test-imports.mjs
echo "=== CJS Environment ===" && node test-imports.cjs && echo "=== Bun CJS ===" && bun test-imports.cjs

# Test main vs subpath access patterns
echo "=== Main vs Subpath ===" && node test-main-vs-subpath.mjs && echo "=== Bun ===" && bun test-main-vs-subpath.mjs

# Original project tests (all passing now)
cd .. && bun test && yarn test
```

## Investigation Conclusion

### 🎉 **No Critical Issues Found**
After comprehensive testing with isolated packages in multiple configurations, **both Bun and Node.js demonstrate identical and correct behavior** for package exports validation.

### 📊 **Test Coverage**
- **48 test scenarios**: 3 libraries × 4 files × 2 environments × 2 runtimes
- **Multiple import patterns**: Direct imports, subpath imports, main imports
- **Both module systems**: CommonJS and ESM
- **Real package linking**: Using npm link for accurate package resolution

### ✅ **Verification Results**
1. **Package exports specification**: Both runtimes comply correctly
2. **Security**: Both runtimes properly block unauthorized file access
3. **Compatibility**: No functional differences between runtimes
4. **Spec compliance**: Both follow Node.js package exports standard

### 🔍 **Possible Explanations for Original Issue**
The originally suspected bug may have been:
1. **Already resolved** in Bun v1.2.16
2. **Context-specific** - requiring particular conditions not replicated in our tests
3. **Misidentified** - perhaps related to different import resolution behavior
4. **Test environment specific** - related to particular testing framework or configuration

### 🎯 **Recommendations**

**For Current Project:**
1. ✅ **Continue using Bun safely** - no critical compatibility issues found
2. ✅ **Both explicit and minimal exports work correctly** in both runtimes
3. ✅ **Original failing tests now pass** - suggesting previous issues were resolved

**For Future Investigations:**
1. 📋 **Document specific failing test cases** when issues arise
2. 🔍 **Test in isolated environments** to eliminate external factors
3. 📊 **Use multiple reproduction approaches** to verify issues
4. 📝 **Track version information** for both runtimes when reporting issues

### 📁 **Archival Note**
This investigation represents a thorough attempt to reproduce reported import resolution issues between Bun and Node.js. All test artifacts are preserved for future reference and can be used as a baseline for testing future runtime versions or investigating new issues.

**Status: Investigation Complete - No Issues Reproduced**