@longzai-intelligence-bun/alias-plugin 0.0.9

package/README.md

@@ -0,0 +1,122 @@
+# @longzai-intelligence-bun/alias-plugin
+
+Bun.build 路径别名解析插件，在打包时将路径别名（如 `@webview/*`、`@bun/*`）解析为实际文件绝对路径。
+
+## 背景
+
+`Bun.build()` 打包器既不支持 `alias` 选项，也不自动解析 `tsconfig.json` 的 `paths`。这导致使用路径别名的源码在 `Bun.build()` 打包时报「无法解析模块」。本插件通过 `onResolve` 钩子在打包时把别名前缀映射为实际文件绝对路径，补齐 `Bun.build()` 的别名解析能力缺口。
+
+## 安装
+
+```bash
+bun add -D @longzai-intelligence-bun/alias-plugin
+```
+
+## 快速开始
+
+```typescript
+import { createAliasPlugin } from '@longzai-intelligence-bun/alias-plugin';
+
+const aliasPlugin = createAliasPlugin(import.meta.dir, {
+  '@webview': 'src/webview',
+  '@bun': 'src/bun',
+});
+
+const result = await Bun.build({
+  entrypoints: ['src/bun/index.ts'],
+  plugins: [aliasPlugin],
+});
+```
+
+## 核心 API
+
+### createAliasPlugin(rootDir, aliasMap)
+
+创建路径别名解析插件实例。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `rootDir` | `string` | 项目根目录的绝对路径，别名目标目录相对此解析 |
+| `aliasMap` | `AliasMap` | 别名前缀到目标目录的映射 |
+
+`AliasMap` 类型：
+
+```typescript
+type AliasMap = Record<string, string>;
+```
+
+键为别名前缀（如 `@webview`），值为 `rootDir` 下的目标目录（如 `src/webview`）。插件匹配 `@webview/foo/bar` 后，会解析为 `rootDir/src/webview/foo/bar`。
+
+### aliasMap 配置示例
+
+```typescript
+const aliasMap = {
+  '@webview': 'src/webview',
+  '@bun': 'src/bun',
+  '@shared': 'src/shared',
+} as const;
+```
+
+## 工作原理
+
+1. 根据 `aliasMap` 的键构建别名前缀正则表达式，作为 `onResolve` 的 `filter`。
+2. 对匹配别名前缀的导入路径，剥除别名前缀得到相对路径。
+3. 拼接 `rootDir + 目标目录 + 相对路径` 得到待解析基础路径。
+4. 依次尝试补全扩展名和 index 文件，命中第一个存在的文件即返回其绝对路径。
+
+扩展名补全顺序：
+
+| 序号 | 候选路径 |
+| --- | --- |
+| 1 | 原路径 |
+| 2 | `.ts` |
+| 3 | `.tsx` |
+| 4 | `.js` |
+| 5 | `/index.ts` |
+| 6 | `/index.tsx` |
+
+## 能力边界
+
+### 支持
+
+- 前缀式别名（`@alias/sub/path` → 目标目录 + 子路径）。
+- 自动补全 `.ts` / `.tsx` / `.js` 及对应 `index` 文件。
+- 多别名共存（一个插件实例处理多个别名前缀）。
+
+### 不支持
+
+- **通配符路径**（如 tsconfig `paths` 的 `@/*`、`*` 占位符）。本插件只做前缀匹配，不做 glob 通配。
+- **node_modules 包别名**（如把 `react` 重映射到 `preact`）。本插件仅解析文件系统路径。
+- **构建后别名替换**。本插件作用于打包时（`onResolve`），不处理 dist 产物的文本替换——后者由 `@longzai-intelligence-typescript/resolve-aliases`（post-tsgo 工具）负责，两者时机与机制完全不同。
+
+## 典型场景：Electrobun 桌面应用
+
+[Longzai Intelligence Electrobun](../../../longzai-intelligence-electrobun) 直接调用 `Bun.build()` 打包主进程与 webview 视图，其配置（`lzi-electrobun.config.ts`）的 `build.bun.plugins` / `build.views.*.plugins` 接受 `Bun.build()` 插件。将本插件传入即可在 Electrobun 打包链路启用别名解析：
+
+```typescript
+import { createAliasPlugin } from '@longzai-intelligence-bun/alias-plugin';
+
+const aliasPlugin = createAliasPlugin(import.meta.dir, {
+  '@webview': 'src/webview',
+  '@bun': 'src/bun',
+});
+
+export default {
+  build: {
+    bun: {
+      entrypoint: 'src/bun/index.ts',
+      plugins: [aliasPlugin],
+    },
+    views: {
+      webview: {
+        entrypoint: 'src/webview/index.tsx',
+        plugins: [aliasPlugin],
+      },
+    },
+  },
+};
+```
+
+## 许可证
+
+UNLICENSED

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+//#region src/index.d.ts
+/**
+ * Bun.build 路径别名解析插件
+ *
+ * Bun.build 不支持 alias 选项，也不自动解析 tsconfig paths。
+ * 此插件在打包时将路径别名（如 @webview/*、@bun/*）解析为实际文件绝对路径，
+ * 支持自动补全扩展名和 index 文件解析。
+ */
+/**
+ * 别名映射规则
+ *
+ * 键为别名前缀（如 "@webview"），值为项目根目录下的目标目录（如 "src/webview"）。
+ */
+type AliasMap = Record<string, string>;
+/**
+ * 创建路径别名解析插件
+ *
+ * @param rootDir - 项目根目录的绝对路径
+ * @param aliasMap - 别名前缀到目标目录的映射
+ * @returns Bun.build 插件实例
+ */
+declare function createAliasPlugin(rootDir: string, aliasMap: AliasMap): BunPlugin;
+//#endregion
+export { AliasMap, createAliasPlugin };

package/dist/index.js

@@ -0,0 +1 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{statSync as e}from"node:fs";import{resolve as t}from"node:path";function n(t){try{return e(t).isFile()}catch{return!1}}function r(e){let t=[e,`${e}.ts`,`${e}.tsx`,`${e}.js`,`${e}/index.ts`,`${e}/index.tsx`];for(let e of t)if(n(e))return e;return null}function i(e,n){let i=Object.keys(n).map(e=>e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)),a=RegExp(`^(${i.join(`|`)})/`);return{name:`alias-resolver`,setup(i){i.onResolve({filter:a},i=>{for(let[a,o]of Object.entries(n))if(i.path.startsWith(a+`/`)){let n=i.path.slice(a.length),s=r(t(e,o+n));if(s)return{path:s}}})}}}export{i as createAliasPlugin};

package/dist/rolldown-runtime-BqT_7tdF.js

@@ -0,0 +1 @@
+import"node:module";export{};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@longzai-intelligence-bun/alias-plugin",
+  "version": "0.0.9",
+  "description": "Bun.build 路径别名解析插件",
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}