feat(api): add analyzeExports with symbolic mode

[privatenumber]

Problem

The library currently requires filesystem access to analyze package exports. This makes it impossible to use in:

• Browser-based tools and playgrounds
• Static analysis without actual files
• Educational demonstrations of exports behavior

Changes

New Public API

Added analyzeExports(exports, packageFiles?) function that operates in two modes:

Symbolic Mode (when packageFiles is omitted):

• Wildcard patterns returned as-is with the pattern itself
• Static paths accepted without validation
• Perfect for analysis tools and playgrounds without filesystem

Concrete Mode (when packageFiles is provided):

• Wildcard patterns matched against provided files
• Static paths validated against file list
• Original behavior maintained

Implementation Details

• Modified getConditions() to check for empty packageFiles array
• Added symbolic mode logic: returns [[exports, '*']] for wildcards
• Refactored getPackageEntryPoints() and getPackageEntryPointsSync() to use analyzeExports() internally
• No breaking changes - all existing functionality preserved

Test Coverage

• Added 10 new tests in tests/specs/symbolic-mode.ts
• Total: 90 tests passing (80 original + 10 new)
• Covers wildcards, static paths, conditions, fallback arrays, null exports

Documentation

• Added comprehensive API docs for analyzeExports()
• Added missing docs for getPackageEntryPointsSync()
• Included examples for both symbolic and concrete modes

Future Work

• Added PLAYGROUND.md outlining plan for interactive playground
• Playground will use symbolic mode to demonstrate exports behavior
• Will help identify dangerous wildcard patterns

Example

import { analyzeExports } from 'pkg-entry-points'

// Symbolic mode: wildcards returned as patterns
const symbolicResult = analyzeExports({
    './dist/*.js': './dist/*.js'
})
// { './dist/*.js': [[['default'], './dist/*.js']] }

// Concrete mode: wildcards matched against files
const concreteResult = analyzeExports(
    { './dist/*.js': './dist/*.js' },
    ['./dist/index.js', './dist/utils.js']
)
// {
//     './dist/index.js': [[['default'], './dist/index.js']],
//     './dist/utils.js': [[['default'], './dist/utils.js']]
// }

Files Changed

• src/index.ts - Added analyzeExports(), modified getConditions()
• tests/specs/symbolic-mode.ts - New test suite
• tests/index.ts - Import symbolic mode tests
• README.md - API documentation
• PLAYGROUND.md - Future playground plan