Support tsconfig path aliases in migration validation

[jalexw]

Summary

Adds support for resolving TypeScript compilerOptions.paths aliases (e.g., @/sql → src/sql.ts) when validating and importing migration modules. This allows consumers to use the same import aliases in their migrations as they do in their application code.

Key Changes

• New module src/utils/tsconfigPathAliases.ts: Implements tsconfig.json parsing and path alias resolution

  • Parses JSONC (comments + trailing commas) and resolves baseUrl and compilerOptions.paths
  • Follows extends chains to inherit aliases from parent configs
  • Discovers the nearest tsconfig declaring aliases by walking up from a directory
  • Resolves alias specifiers to actual file paths with extension probing (.ts, .tsx, .js, etc.)
  • Handles TypeScript's ESM-style imports (e.g., @/sql.js → sql.ts)

• New module src/utils/tsconfigAliasImportHooks.ts: Integrates alias resolution with Node.js and Bun runtimes

  • For Node.js (≥22.15): Uses module.registerHooks() to install a synchronous ESM resolve hook
  • For Bun: Pre-scans the migration import graph and registers alias specifiers as virtual modules (since Bun's runtime hooks don't fire)
  • Scopes alias resolution to the consumer project's files only (tsconfig directory + migration directory) to avoid rewriting imports from this package or dependencies

• Updated src/utils/validateMigrationDirectory.ts:

  • Accepts optional tsconfigPath option to explicitly specify a tsconfig
  • Auto-discovers the nearest tsconfig declaring aliases if not provided
  • Applies alias resolution when dynamically importing migration modules
  • Reports warnings when aliases are found but the runtime doesn't support resolution

• Updated src/cli.ts: Adds --tsconfig <path> flag to the validate-migration-directory command

• Test fixtures: Added three fixture projects demonstrating alias usage:

  • alias-project: Standard setup with baseUrl and both exact and wildcard aliases
  • nobase-project: Tsconfig without baseUrl (paths relative to config file) — exercises Bun's virtual module fallback
  • extends-chain: Demonstrates alias inheritance through extends

• Comprehensive test coverage: Tests for JSONC parsing, extends chain resolution, exact/wildcard alias matching, extension probing, and end-to-end validation with real migration files

Notable Implementation Details

• The JSONC parser manually strips comments and trailing commas while preserving string contents, avoiding a dependency on a JSON parser library
• Alias resolution follows TypeScript's pattern matching rules: exact patterns win, otherwise the wildcard with the longest matching prefix
• Extension probing mirrors how tsc and bundlers complete extensionless specifiers, including .js→.ts swaps for ESM compatibility
• The Node.js hook is installed once per process and driven by a mutable scope, allowing multiple validation runs with different tsconfig contexts
• Bun's virtual module approach uses Bun.Transpiler.scanImports() to statically discover alias usage in the import graph, avoiding the need for runtime hooks

https://claude.ai/code/session_01VvN4yt72bDNyFvUo8TS3z5