resolve-aliases

Post-tsgo 路径别名解析器。在 tsgo --build 之后将 dist 中未解析的 @/ 路径别名替换为相对路径。

背景

tsgo 是 TypeScript 官方的新一代编译器，但不支持解析 tsconfig.json 中的 paths 别名。这导致 dist 产物中保留了 @/xxx 形式的未解析别名，违反了 ADR-0007 要求 dist 中别名必须已解析的规范。

本工具作为 post-build 步骤，在 tsgo --build 之后自动将 dist 中的 @/ 别名替换为正确的相对路径。

用法

# 基本用法
resolve-aliases -p tsconfig/build.json

# 详细输出
resolve-aliases -p tsconfig/build.json --verbose

# 仅检查（不修改文件，有未解析别名时返回非零退出码）
resolve-aliases -p tsconfig/build.json --check

集成到 build 脚本

在 package.json 的 build 脚本末尾追加：

{
  "build": "tsgo --build tsconfig/build.json && resolve-aliases -p tsconfig/build.json"
}

工作原理

1. 解析 tsconfig/build.json（含 extends 继承链），提取 paths、outDir、rootDir
2. 扫描 outDir 中所有 .js、.mjs、.cjs、.d.ts、.d.mts、.d.cts 文件
3. 对每个文件扫描 import/export/require 语句中的 @/ 别名路径
4. 将别名路径映射到 dist 内的相对路径并替换

路径映射算法：

• @/application/mappers/foo.js -> 去掉前缀 -> application/mappers/foo.js
• 在 dist 中保持相同相对路径 -> outDir/application/mappers/foo.js
• 从当前文件目录计算相对路径 -> ../../mappers/foo.js

性能

• 使用 rayon 并行处理文件
• 字节级扫描，仅对 "@/ 和 '@/ 模式做路径计算
• 50 个文件处理耗时 < 50ms（release 模式）

致谢

本工具的思路和实现参考了以下开源项目：

• tsc-alias - Node.js post-tsc 别名替换工具，启发了解析 tsconfig paths 并替换 dist 中别名的核心思路
• oxc-resolver - Rust 模块解析器，研究了其 tsconfig paths 解析和路径计算算法（本工具完全自实现，但从中获得了重要的算法参考）
• tsconfig-paths - tsconfig paths 运行时解析库，提供了 paths 匹配逻辑（含通配符）的参考