feat(napi): expose resolve_file API as resolveFileSync and resolveFileAsync

[Boshen]

Summary

Exposes the Rust resolve_file API to NAPI as resolveFileSync and resolveFileAsync methods on the ResolverFactory class.

What's New

• resolveFileSync(file: string, request: string) - Synchronous file-based resolution
• resolveFileAsync(file: string, request: string) - Asynchronous file-based resolution

Key Difference from sync()

• sync(directory, specifier) - Takes a directory path, uses manually configured tsconfig if provided
• resolveFileSync(file, specifier) - Takes a file path, automatically discovers tsconfig.json by traversing parent directories

Why This Matters

When resolving from a specific file (e.g., in bundlers, linters, or language servers), resolveFileSync automatically finds the correct tsconfig.json by:

• Traversing parent directories from the file location
• Respecting TypeScript project references
• Honoring include, exclude, and files fields to determine which tsconfig applies
• Ensuring tsconfig paths aliases work correctly based on the file's context

Changes

Core Implementation (napi/src/lib.rs)

• Added resolve_file() helper function (mirrors existing resolve() pattern)
• Added ResolveFileTask struct for async operations
• Added resolve_file_sync() method to ResolverFactory
• Added resolve_file_async() method to ResolverFactory

TypeScript Definitions (napi/index.d.ts)

• Added type definitions for resolveFileSync() and resolveFileAsync()
• Includes JSDoc comments explaining automatic tsconfig discovery

Tests (napi/tests/file-resolve.test.mjs - NEW FILE)

• 12 comprehensive tests covering:
  • Basic sync/async file resolution
  • Error handling (file not found, invalid paths)
  • Module type detection
  • Builtin module handling
  • Consistency between sync and async methods

Documentation (README.md)

• Added "File-based Resolution" section with usage examples
• Explained when and why to use file-based resolution
• Documented automatic tsconfig discovery behavior

Test Plan

• All Rust tests pass (157 tests)
• All Node.js/NAPI tests pass (64 tests including 12 new tests)
• Formatting and linting checks pass
• Build successful
• TypeScript definitions generated correctly
• Documentation updated

Test Results

✓ tests/file-resolve.test.mjs (12 tests) 6ms
✓ tests/file-protocol.test.mjs (9 tests) 11ms
✓ tests/simple.test.mjs (3 tests) 17ms
✓ tests/options.test.mjs (7 tests | 5 skipped) 5ms
✓ tests/resolver.test.mjs (33 tests) 56ms

Test Files  5 passed (5)
Tests  59 passed | 5 todo (64)

🤖 Generated with Claude Code

[graphite-app]

How to use the Graphite Merge Queue

Add the label merge to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

[codspeed-hq]

CodSpeed Performance Report

Merging #900 will not alter performance

_{Comparing feat/expose-resolve-file-api (76ed10b) with main (00c33d0)}

Summary

✅ 12 untouched
⏩ 5 skipped¹

Footnotes

1. 5 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩