@longzai-intelligence-builder/config 0.2.8 → 0.2.10

package/dist/index.d.ts

@@ -1,2 +1,1198 @@
-export type { Arrayable, AttwOptions, BuildContext, BuildFormat, BuilderConfig, BuilderConfigExport, BuilderConfigFn, BuilderHooks, CIOption, ConfigLoader, ConfigOptions, CopyEntry, CopyOptions, CopyOptionsFn, DepsOptions, DevtoolsOptions, DtsOptions, EntryConfig, ExportsOptions, Logger, LoggerOptions, LogLevel, LogType, NoExternalFn, PackageJsonWithPath, PresetDefinition, PublintOptions, ReportOptions, ResolvedBuilderConfig, RolldownChunk, RolldownContext, TsdownInputOption, WithEnabled, Workspace } from './types.js';
-//# sourceMappingURL=index.d.ts.map
+import { Options } from "@longzai-intelligence-builder/rolldown-plugin-dts";
+import { Hookable } from "hookable";
+import { BuildOptions, ChecksOptions, ExternalOption, InputOptions, ModuleFormat, OutputAsset, OutputChunk, OutputOptions, Plugin } from "rolldown";
+//#region src/types.d.ts
+/**
+ * 日志类型
+ *
+ * 对齐 tsdown `LogType`（`src/utils/logger.ts`）。
+ */
+type LogType = 'error' | 'warn' | 'info';
+/**
+ * 日志级别
+ *
+ * 对齐 tsdown `LogLevel`（`src/utils/logger.ts`）。
+ */
+type LogLevel = LogType | 'silent';
+/**
+ * Logger 接口
+ *
+ * 对齐 tsdown `Logger`（`src/utils/logger.ts`）。
+ * config 包不依赖 core，故在此独立声明结构兼容的接口；
+ * core 的 `createLogger` 返回值与此接口结构兼容（TS 结构类型）。
+ */
+interface Logger {
+  level: LogLevel;
+  options?: LoggerOptions;
+  info: (...args: any[]) => void;
+  warn: (...args: any[]) => void;
+  warnOnce: (...args: any[]) => void;
+  error: (...args: any[]) => void;
+  success: (...args: any[]) => void;
+  clearScreen: (type: LogType) => void;
+}
+/**
+ * Logger 选项
+ *
+ * 对齐 tsdown `LoggerOptions`（`src/utils/logger.ts`）。
+ */
+interface LoggerOptions {
+  allowClearScreen?: boolean;
+  customLogger?: Logger;
+  console?: Console;
+  failOnWarn?: boolean | CIOption;
+}
+/**
+ * 带 packageJsonPath 的 package.json（对齐 tsdown PackageJsonWithPath）
+ *
+ * 在 config 包声明（而非 core/utils/package.ts），避免 core→config 循环依赖。
+ */
+type PackageJsonWithPath = {
+  name?: string;
+  type?: string;
+  main?: string;
+  module?: string;
+  types?: string;
+  typings?: string;
+  exports?: unknown;
+  bin?: string | Record<string, string>;
+  engines?: {
+    node?: string;
+  };
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  publishConfig?: Record<string, unknown>;
+  packageJsonPath: string;
+  [key: string]: unknown;
+};
+/**
+ * rolldown 产物 chunk（附加 outDir）
+ *
+ * 对齐 tsdown `RolldownChunk`（`src/utils/chunks.ts`）。
+ */
+type RolldownChunk = (OutputChunk | OutputAsset) & {
+  outDir: string;
+};
+/**
+ * 构建上下文（对齐 tsdown BuildContext）
+ */
+interface BuildContext {
+  options: BuilderConfig;
+  hooks: Hookable<BuilderHooks>;
+}
+/**
+ * rolldown 构建上下文（对齐 tsdown RolldownContext）
+ */
+interface RolldownContext {
+  buildOptions: BuildOptions;
+  /**
+   * 是否为 cjs 的第二次独立 dts 构建（emitDtsOnly）
+   */
+  cjsDts?: boolean;
+  /**
+   * 是否为双格式构建（es + cjs）
+   */
+  isDualFormat?: boolean;
+}
+/**
+ * builder 构建生命周期 hooks（对齐 tsdown TsdownHooks）
+ */
+interface BuilderHooks {
+  'build:prepare': (ctx: BuildContext) => void | Promise<void>;
+  'build:before': (ctx: BuildContext & RolldownContext) => void | Promise<void>;
+  'build:done': (ctx: BuildContext & {
+    chunks: RolldownChunk[];
+  }) => void | Promise<void>;
+}
+/**
+ * Awaitable 类型（对齐 tsdown utils/types.ts）
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * @vitejs/devtools start 选项的最小类型
+ */
+interface DevtoolsStartOptions {
+  host?: string;
+  open?: boolean;
+}
+/**
+ * Devtools 选项（对齐 tsdown DevtoolsOptions）
+ *
+ * 扩展 rolldown 的 inputOptions.devtools，新增 ui / clean 字段。
+ */
+interface DevtoolsOptions extends NonNullable<InputOptions['devtools']> {
+  /**
+   * **[experimental]** Enable devtools integration. `@vitejs/devtools` must be installed as a
+   * dependency.
+   *
+   * Defaults to true, if `@vitejs/devtools` is installed.
+   */
+  ui?: boolean | Partial<DevtoolsStartOptions>;
+  /**
+   * Clean devtools stale sessions.
+   *
+   * @default true
+   */
+  clean?: boolean;
+}
+/**
+ * Workspace 配置（对齐 tsdown Workspace）
+ *
+ * monorepo 多包构建配置。
+ */
+interface Workspace {
+  /**
+   * Workspace 目录，支持 glob 模式
+   *
+   * - `auto`：自动检测 package.json 文件
+   *
+   * @default 'auto'
+   */
+  include?: 'auto' | (string & {}) | string[];
+  /**
+   * 排除目录
+   *
+   * @default ['**\/node_modules/**', '**\/dist/**', '**\/test?(s)/**', '**\/t?(e)mp/**']
+   */
+  exclude?: Arrayable<string>;
+  /**
+   * Workspace 配置文件路径
+   */
+  config?: boolean | string;
+}
+/**
+ * copy 条目（对齐 tsdown CopyEntry）
+ */
+interface CopyEntry {
+  /**
+   * 源路径或 glob 模式
+   */
+  from: string | string[];
+  /**
+   * 目标路径（未指定时默认为输出目录）
+   */
+  to?: string;
+  /**
+   * 是否展平（不保留目录结构）
+   *
+   * @default true
+   */
+  flatten?: boolean;
+  /**
+   * 是否输出复制项到控制台
+   *
+   * @default false
+   */
+  verbose?: boolean;
+  /**
+   * 修改目标文件或文件夹名
+   */
+  rename?: string | ((name: string, extension: string, fullPath: string) => string);
+}
+/**
+ * copy 选项（对齐 tsdown CopyOptions）
+ */
+type CopyOptions = Arrayable<string | CopyEntry>;
+/**
+ * copy 选项函数（对齐 tsdown CopyOptionsFn）
+ */
+type CopyOptionsFn = (options: BuilderConfig) => Awaitable<CopyOptions>;
+/**
+ * report 选项（对齐 tsdown ReportOptions）
+ */
+interface ReportOptions {
+  /**
+   * 是否报告 gzip 压缩大小
+   *
+   * @default true
+   */
+  gzip?: boolean;
+  /**
+   * 是否报告 brotli 压缩大小
+   *
+   * @default false
+   */
+  brotli?: boolean;
+  /**
+   * 超过此大小的文件跳过压缩计算
+   *
+   * @default 1000000 (1 MB)
+   */
+  maxCompressSize?: number;
+}
+/**
+ * exports 选项（对齐 tsdown ExportsOptions）
+ *
+ * package.json exports 字段自动生成配置。
+ */
+interface ExportsOptions {
+  /**
+   * 开发模式下 exports 指向源码
+   */
+  devExports?: boolean | string;
+  /**
+   * 是否生成 package.json 的 exports 字段
+   */
+  packageJson?: boolean;
+  /**
+   * 是否为所有文件生成 exports
+   */
+  all?: boolean;
+  /**
+   * 排除的文件模式
+   */
+  exclude?: (RegExp | string)[];
+  /**
+   * 是否生成 legacy 字段（main/module）
+   */
+  legacy?: boolean;
+  /**
+   * 自定义追加的 exports
+   */
+  customExports?: Record<string, unknown> | ((exports: Record<string, unknown>, context: {
+    pkg: Record<string, unknown>;
+    chunks: unknown;
+    isPublish: boolean;
+  }) => Promise<Record<string, unknown>> | Record<string, unknown>);
+  /**
+   * 是否生成 inlinedDependencies 字段
+   */
+  inlinedDependencies?: boolean;
+  /**
+   * 子路径导出键是否加 .js 扩展名
+   */
+  extensions?: boolean;
+  /**
+   * bin 字段生成（auto-detect / string / Record / boolean）
+   */
+  bin?: boolean | string | Record<string, string>;
+}
+/**
+ * publint 选项（对齐 tsdown PublintOptions）
+ *
+ * 包质量检查。需安装 publint。
+ */
+interface PublintOptions {
+  /**
+   * 预加载的 publint 模块
+   */
+  module?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * attw 选项（对齐 tsdown AttwOptions）
+ *
+ * 类型导出正确性检查。需安装 @arethetypeswrong/core。
+ */
+interface AttwOptions {
+  /**
+   * 预加载的 attw 模块
+   */
+  module?: unknown;
+  /**
+   * 解析模式
+   */
+  profile?: 'strict' | 'node16' | 'esm-only';
+  /**
+   * 检查级别
+   */
+  level?: 'error' | 'warn';
+  /**
+   * 忽略的规则
+   */
+  ignoreRules?: string[];
+  [key: string]: unknown;
+}
+/**
+ * CI 条件选项（对齐 tsdown CIOption）
+ *
+ * - `'ci-only'`：仅在 CI 环境启用
+ * - `'local-only'`：仅在本地（非 CI）环境启用
+ */
+type CIOption = 'ci-only' | 'local-only';
+/**
+ * 带 enabled 开关的选项类型（对齐 tsdown WithEnabled）
+ *
+ * 支持以下形态：
+ * - `boolean`：true 用默认值，false 关闭
+ * - `undefined`：同 true
+ * - `CIOption`：按 CI 环境条件判定
+ * - `T & { enabled?: boolean | CIOption }`：对象配置，enabled 控制开关
+ */
+type WithEnabled<T> = boolean | undefined | CIOption | (T & {
+  enabled?: boolean | CIOption;
+});
+/**
+ * 构建格式类型
+ */
+type BuildFormat = ModuleFormat | 'es' | 'cjs';
+/**
+ * 单值或数组
+ *
+ * 对齐 tsdown `Arrayable`（`src/utils/types.ts`）。
+ */
+type Arrayable<T> = T | T[];
+/**
+ * 自定义"是否打包"判定函数
+ *
+ * 对齐 tsdown `NoExternalFn`（`src/features/deps.ts:25-28`）。返回真值表示
+ * 该依赖命中规则（如 alwaysBundle 命中则强制打包、onlyBundle 命中则允许打包）。
+ */
+type NoExternalFn = (id: string, importer: string | undefined) => boolean | null | undefined | void;
+/**
+ * 入口配置类型，支持 glob 与取反模式
+ *
+ * 对齐 tsdown `TsdownInputOption`：
+ * - 字符串：单个入口或 glob 模式
+ * - 数组：多个字符串/对象，支持 `!` 取反
+ * - 对象：键为入口名（可含 glob），值为路径或 glob 数组
+ */
+type TsdownInputOption = Arrayable<string | Record<string, Arrayable<string>>>;
+/**
+ * dts 配置选项（对齐 tsdown DtsOptions extends RolldownPluginDtsOptions）
+ *
+ * 继承 rolldown-plugin-dts 的完整 Options（generator/oxc/tsgo/parallel/incremental/
+ * build/eager/newContext/compilerOptions/resolver/entry/emitJs/cjsDefault/emitDtsOnly 等），
+ * 追加 builder 专有的 enabled 与 cjsReexport。
+ */
+type DtsOptions = Options & {
+  /**
+   * 是否生成声明文件（builder 专有，对齐 tsdown DtsOptions.enabled）
+   */
+  enabled?: boolean;
+  /**
+   * cjs 双格式时用 re-export stub 代替第二次 tsc（builder 专有，对齐 tsdown DtsOptions.cjsReexport）
+   *
+   * 双格式 ['es','cjs'] 时，cjs 的 .d.cts 生成 `export type * from './xxx.d.mts'` stub，
+   * 完全跳过 tsc。仅双格式生效（单格式 cjs 仍走完整 dts）。
+   */
+  cjsReexport?: boolean;
+};
+/**
+ * 依赖处理选项
+ */
+type DepsOptions = {
+  /**
+   * 始终打包进产物的依赖
+   *
+   * 对齐 tsdown `deps.alwaysBundle`：接受单值或数组，或自定义判定函数。
+   */
+  alwaysBundle?: Arrayable<string | RegExp> | NoExternalFn;
+  /**
+   * 始终外部化的依赖
+   */
+  neverBundle?: ExternalOption;
+  /**
+   * 是否跳过 node_modules 打包（库包默认 true，应用默认 false）
+   */
+  skipNodeModulesBundle?: boolean;
+  /**
+   * 允许打包的依赖白名单
+   *
+   * 对齐 tsdown `deps.onlyBundle`：
+   * - `undefined`（默认）：检测到内联依赖时打提示，建议配置白名单
+   * - 数组或单值：仅允许列出的依赖被打包，未列出的内联依赖触发构建错误；未使用的白名单项打提示
+   * - `false`：关闭内联依赖检测提示
+   */
+  onlyBundle?: Arrayable<string | RegExp> | false;
+  /**
+   * 仅作用于声明文件（.d.ts）生成的依赖处理覆盖
+   *
+   * 对齐 tsdown `deps.dts`：dts 产物里 `alwaysBundle` 强制打包、`neverBundle`
+   * 强制外部化的判定独立于 JS 产物。典型场景：应用/CLI 包 JS 全量打包但希望
+   * dts 保留对某依赖的外部引用（避免内联整个类型源码）。
+   */
+  dts?: {
+    /**
+     * 仅在生成 .d.ts 时强制打包的依赖（覆盖顶层的 alwaysBundle）
+     */
+    alwaysBundle?: Arrayable<string | RegExp> | NoExternalFn;
+    /**
+     * 仅在生成 .d.ts 时强制外部化的依赖（追加到顶层的 neverBundle）
+     */
+    neverBundle?: ExternalOption;
+  };
+};
+/**
+ * builder 构建配置，基于 rolldown 的输入输出选项扩展
+ */
+type BuilderConfig = {
+  /**
+   * 入口配置，支持 glob 与 `!` 取反（对齐 tsdown `TsdownInputOption`）
+   */
+  entry?: TsdownInputOption;
+  /**
+   * 当前工作目录
+   *
+   * 对齐 tsdown `cwd`（@default process.cwd()）。配置解析与构建的基准目录。
+   */
+  cwd?: string;
+  /**
+   * 输出格式
+   */
+  format?: BuildFormat[] | BuildFormat;
+  /**
+   * 输出目录
+   */
+  outdir?: string;
+  /**
+   * 是否生成 dts 声明文件
+   */
+  dts?: DtsOptions | boolean;
+  /**
+   * tsconfig 文件路径
+   */
+  tsconfig?: string;
+  /**
+   * 是否压缩产物
+   *
+   * 对齐 tsdown `minify`：`boolean` 开关、`'dce-only'` 仅死代码消除、或 MinifyOptions 精细配置。
+   * 透传至 rolldown `output.minify`。
+   */
+  minify?: OutputOptions['minify'];
+  /**
+   * 是否生成 sourcemap
+   */
+  sourcemap?: boolean | 'inline';
+  /**
+   * 构建前清理
+   *
+   * 对齐 tsdown `clean`：
+   * - `true`（默认）：清理输出目录
+   * - `false`：不清理
+   * - `string[]`：清理指定路径列表（glob 模式）
+   */
+  clean?: boolean | string[];
+  /**
+   * 输出文件扩展名
+   */
+  outExtensions?: () => {
+    js?: string;
+    dts?: string;
+  };
+  /**
+   * 依赖处理选项
+   */
+  deps?: DepsOptions;
+  /**
+   * 额外的 rolldown 插件
+   */
+  plugins?: Plugin[];
+  /**
+   * 外部依赖声明
+   */
+  external?: InputOptions['external'];
+  /**
+   * 构建目标平台
+   *
+   * 决定 rolldown 如何处理 Node 内置模块（`node:fs` / `node:path` 等）与
+   * 第三方包内部的裸名 `require('crypto')`。
+   *
+   * esm/dual 预设默认 `'neutral'`（不假定运行时，产物可同时被 Node 与浏览器
+   * 消费方安全打包，详见 issue 0057）。`'node'` 会让 rolldown 为 `__exportAll`
+   * 等 helper 注入带 `import "node:module"` 的 runtime chunk，被 webpack 二次
+   * 打包时抛 `UnhandledSchemeError`（issue 0033）。
+   *
+   * **按真实运行时覆盖此默认**：
+   *
+   * - 真有 `node:*` 依赖的纯 Node 包 → 设 `platform: 'node'`（消除 `node:` 内置 模块的 `UNRESOLVED_IMPORT` 警告，见 issue
+   *   0004）。
+   * - 零 Node 依赖、被浏览器/混合运行时消费的包 → 保持默认 `'neutral'`。
+   *
+   * 透传至 rolldown 的 `inputOptions.platform`；亦可直接通过
+   * `inputOptions.platform` 覆盖（优先级更高）。cjs 格式强制 `'node'`，不可覆盖。
+   *
+   * @default 'neutral'（esm/dual 预设）
+   */
+  platform?: InputOptions['platform'];
+  /**
+   * 是否注入 ESM 下 `__dirname` / `__filename` 的 polyfill
+   *
+   * 对齐 tsdown `shims`（默认 false）。仅在 `format 含 es && platform === 'node'`
+   * 时生效：通过 rolldown 的 `transform.inject` 把源码里的 `__dirname` / `__filename`
+   * 替换为从 `@longzai-intelligence-builder/core/shims` 导入的导出，使其在 ESM + Node
+   * 下可用（CJS 全局在 ESM 运行时不存在）。
+   *
+   * @default false
+   */
+  shims?: boolean;
+  /**
+   * 控制 Node 内置模块的 `node:` 协议
+   *
+   * 对齐 tsdown `nodeProtocol`：
+   * - `'strip'`：移除 `node:` 前缀（`node:fs` → `fs`）
+   * - `true`：添加 `node:` 前缀（`fs` → `node:fs`）
+   * - `false`（默认）：不转换
+   */
+  nodeProtocol?: 'strip' | boolean;
+  /**
+   * 构建成功后执行的回调
+   *
+   * /**
+   * 构建成功后执行的回调
+   *
+   * 对齐 tsdown `onSuccess`：
+   *
+   * - string：以 shell 执行（tinyexec shell:true）
+   * - 函数：调用 `onSuccess(config, signal)`，传入 AbortSignal（watch 模式下可中断）
+   */
+  onSuccess?: string | ((config: BuilderConfig, signal: AbortSignal) => void | Promise<void>);
+  /**
+   * CommonJS 默认导出
+   *
+   * 对齐 tsdown `cjsDefault`：cjs 格式产物使用 `module.exports =` 默认导出。
+   * 透传至 rolldown `output.exports: 'auto'`。
+   *
+   * @default false
+   */
+  cjsDefault?: boolean;
+  /**
+   * dual 格式（esm + cjs）下，为 cjs 的 .d.cts 生成 re-export stub
+   *
+   * 对齐 tsdown `cjsReexport`：生成 `.d.cts` 文件，内容为 `export type * from './xxx.d.mts'`，
+   * 避免 TS2352 类型不重叠错误。仅 esm + cjs 同时输出时生效。
+   *
+   * @default false
+   */
+  cjsReexport?: boolean;
+  /**
+   * 编译目标（语法降级）
+   *
+   * 对齐 tsdown `target`，透传至 rolldown `transform.target`。
+   */
+  target?: string | string[] | false;
+  /**
+   * 编译期常量定义
+   *
+   * 对齐 tsdown `define`，透传至 rolldown `transform.define`。
+   */
+  define?: Record<string, string>;
+  /**
+   * 模块说明符别名
+   *
+   * 对齐 tsdown `alias`，透传至 rolldown `resolve.alias`。
+   */
+  alias?: Record<string, string>;
+  /**
+   * Tree shaking 配置
+   *
+   * 对齐 tsdown `treeshake`，透传至 rolldown `treeshake`。
+   */
+  treeshake?: InputOptions['treeshake'];
+  /**
+   * 文件 loader 映射
+   *
+   * 对齐 tsdown `loader`，透传至 rolldown `moduleTypes`。
+   */
+  loader?: InputOptions['moduleTypes'];
+  /**
+   * 输出 banner（注入到每个 chunk 头部）
+   *
+   * 对齐 tsdown `banner`，透传至 rolldown `output.postBanner`。
+   */
+  banner?: OutputOptions['postBanner'];
+  /**
+   * 输出 footer（注入到每个 chunk 尾部）
+   *
+   * 对齐 tsdown `footer`，透传至 rolldown `output.postFooter`。
+   */
+  footer?: OutputOptions['postFooter'];
+  /**
+   * IIFE/UMD 全局变量名
+   *
+   * 对齐 tsdown `globalName`，透传至 rolldown `output.name`。
+   */
+  globalName?: string;
+  /**
+   * 非打包模式（输出镜像源码结构）
+   *
+   * 对齐 tsdown `unbundle`，透传至 rolldown `output.preserveModules`。
+   *
+   * @default false
+   */
+  unbundle?: boolean;
+  /**
+   * 输入文件根目录（影响输出结构）
+   *
+   * 对齐 tsdown `root`，unbundle 时透传至 rolldown `output.preserveModulesRoot`。
+   */
+  root?: string;
+  /**
+   * chunk 文件名追加 hash
+   *
+   * 对齐 tsdown `hash`。
+   *
+   * @default false
+   */
+  hash?: boolean;
+  /**
+   * 使用固定扩展名（.cjs/.mjs）
+   *
+   * 对齐 tsdown `fixedExtension`。
+   */
+  fixedExtension?: boolean;
+  /**
+   * 额外的 rolldown 输入选项（支持函数形态按 format 分流，对齐 tsdown）
+   */
+  inputOptions?: InputOptions | ((options: InputOptions, format: BuildFormat) => InputOptions | void | null | Promise<InputOptions | void | null>);
+  /**
+   * 额外的 rolldown 输出选项（支持函数形态按 format 分流，对齐 tsdown）
+   */
+  outputOptions?: OutputOptions | ((options: OutputOptions, format: BuildFormat) => OutputOptions | void | null | Promise<OutputOptions | void | null>);
+  /**
+   * 日志级别
+   *
+   * 对齐 tsdown `logLevel`（@default 'info'）。透传至 `createLogger` 的 level 参数。
+   */
+  logLevel?: LogLevel;
+  /**
+   * 自定义 logger 实例
+   *
+   * 对齐 tsdown `customLogger`。提供时直接使用该实例，绕过内部 logger 实现。
+   */
+  customLogger?: Logger;
+  /**
+   * 警告视为错误（构建失败）
+   *
+   * 对齐 tsdown `failOnWarn`（@default false）。开启时 warn/warnOnce 升级为 error，
+   * rolldown 的 onLog warn 也会被升级为构建错误。
+   */
+  failOnWarn?: boolean | CIOption;
+  /**
+   * 抑制匹配模式的告警
+   *
+   * 对齐 tsdown `suppressWarnings`。接受 string（子串匹配）、RegExp、数组、或谓词函数。
+   * 被匹配的告警在 failOnWarn 之前丢弃，不会导致构建失败。
+   */
+  suppressWarnings?: Arrayable<RegExp | string> | ((msg: string) => boolean);
+  /**
+   * CLI 输出中显示的包名标签
+   *
+   * 对齐 tsdown `name`。monorepo/workspace 场景下区分不同包的构建日志。
+   */
+  name?: string;
+  /**
+   * 构建生命周期 hooks
+   *
+   * 对齐 tsdown `hooks`。支持对象式（`{ 'build:prepare': fn }`）或函数式
+   * （`(hooks) => { hooks.hook('build:prepare', fn) }`）。
+   *
+   * 三个生命周期事件：
+   * - `build:prepare`：构建开始前
+   * - `build:before`：每次 rolldown 构建前（dual-format 每个 format 一次）
+   * - `build:done`：每次构建完成后
+   */
+  hooks?: Partial<BuilderHooks> | ((hooks: Hookable<BuilderHooks>) => Awaitable<void>);
+  /**
+   * Watch 模式
+   *
+   * 对齐 tsdown `watch`。boolean 启用监听；Arrayable<string> 指定额外监听路径。
+   *
+   * @default false
+   */
+  watch?: boolean | Arrayable<string>;
+  /**
+   * Watch 模式下不监听的文件/模式
+   *
+   * 对齐 tsdown `ignoreWatch`。
+   */
+  ignoreWatch?: Arrayable<string | RegExp>;
+  /**
+   * Devtools 集成
+   *
+   * 对齐 tsdown `devtools`。false 关闭；对象配置 ui/clean 等。
+   *
+   * @default false
+   */
+  devtools?: WithEnabled<DevtoolsOptions>;
+  /**
+   * Workspace 模式
+   *
+   * 对齐 tsdown `workspace`。启用 monorepo 多包构建：
+   * - true：自动检测所有含 package.json 的子包
+   * - string / string[]：glob 匹配子包目录
+   * - Workspace 对象：精细配置 include/exclude/config
+   *
+   * @default false
+   */
+  workspace?: Workspace | Arrayable<string> | true;
+  /**
+   * 构建后文件复制
+   *
+   * 对齐 tsdown `copy`。把静态资源（assets、css 等）复制到输出目录。
+   * 支持 string（glob）、CopyEntry 对象、数组、或函数。
+   *
+   * @default false
+   */
+  copy?: CopyOptions | CopyOptionsFn;
+  /**
+   * 构建后体积报告
+   *
+   * 对齐 tsdown `report`。输出产物大小汇总（raw/gzip/brotli）。
+   *
+   * @default true
+   */
+  report?: WithEnabled<ReportOptions>;
+  /**
+   * package.json exports 自动生成
+   *
+   * 对齐 tsdown `exports`。构建后根据产物入口、格式、types 自动生成 exports 字段。
+   *
+   * @default false
+   */
+  exports?: WithEnabled<ExportsOptions>;
+  /**
+   * publint 包质量检查
+   *
+   * 对齐 tsdown `publint`。构建后运行 publint 检查。
+   * 需安装 publint。
+   *
+   * @default false
+   */
+  publint?: WithEnabled<PublintOptions>;
+  /**
+   * attw 类型导出正确性检查
+   *
+   * 对齐 tsdown `attw`。构建后运行 @arethetypeswrong/core 检查。
+   * 需安装 @arethetypeswrong/core。
+   *
+   * @default false
+   */
+  attw?: WithEnabled<AttwOptions>;
+  /**
+   * import.meta.glob 支持
+   *
+   * 对齐 tsdown `globImport`（@default true）。启用后注入 rolldown 的 importGlobPlugin，
+   * 支持 Vite 风格的批量文件导入。
+   */
+  globImport?: boolean;
+  /**
+   * CSS 处理选项
+   *
+   * 对齐 tsdown `css`（来自 @tsdown/css）。builder 当前未集成 CSS 插件（见 0046），
+   * 此字段保留最小形状（splitting），供 exports 生成时判断是否跳过 CSS 子路径导出。
+   */
+  css?: {
+    splitting?: boolean;
+    inject?: unknown;
+  };
+  /**
+   * 可执行文件打包（对齐 tsdown exe）
+   *
+   * 启用后使用 Node.js SEA 将产物打成单文件可执行文件。
+   * 需要 @longzai-intelligence-builder/exe 包。
+   */
+  exe?: WithEnabled<{
+    /**
+     * 跨平台目标列表（platform/arch/nodeVersion 组合）
+     */
+    targets?: Array<{
+      platform: 'win' | 'darwin' | 'linux';
+      arch: 'x64' | 'arm64';
+      nodeVersion: string;
+    }>;
+    /**
+     * SEA 配置
+     */
+    seaConfig?: Record<string, unknown>;
+    /**
+     * 输出文件名（不含扩展名和平台后缀）
+     */
+    fileName?: string | ((chunk: {
+      fileName: string;
+    }) => string);
+    /**
+     * 输出目录（默认 'build'）
+     */
+    outDir?: string;
+  }>;
+  /**
+   * 配置过滤器（workspace 多包场景）
+   *
+   * 对齐 tsdown `InlineConfig.filter`。按 cwd 相对路径或 name 过滤配置，
+   * 不匹配的配置在 resolveConfig 中返回 null（调用方跳过）。
+   * string 精确匹配、RegExp 正则匹配、数组任一匹配。
+   */
+  filter?: string | RegExp | (string | RegExp)[];
+  /**
+   * 是否将产物写入磁盘
+   *
+   * 对齐 tsdown `write`（@default true）。false 时只编译不写盘（试编译），
+   * 与 watch 模式互斥。
+   */
+  write?: boolean;
+  /**
+   * 构建检查选项
+   *
+   * 对齐 tsdown `checks`。继承 rolldown 的 ChecksOptions（circularDependency/eval/
+   * missingGlobalName 等），追加 builder 专有的 legacyCjs（控制 cjs + 新版 Node 告警）。
+   *
+   * @default { legacyCjs: true }
+   */
+  checks?: ChecksOptions & {
+    /**
+     * cjs 格式 + 支持require(ESM) 的 Node 版本时是否告警
+     *
+     * @default true
+     */
+    legacyCjs?: boolean;
+  };
+  /**
+   * @deprecated 使用 `unbundle` 代替
+   *
+   * 对齐 tsdown deprecated `bundle`。true → unbundle=false，false → unbundle=true。
+   */
+  bundle?: boolean;
+  /**
+   * @deprecated 使用 `nodeProtocol: 'strip'` 代替
+   *
+   * 对齐 tsdown deprecated `removeNodeProtocol`。true → nodeProtocol='strip'。
+   * 与 nodeProtocol 同时设置时抛错。
+   */
+  removeNodeProtocol?: boolean;
+  /**
+   * @deprecated 使用 `css.inject` 代替
+   *
+   * 对齐 tsdown deprecated `injectStyle`。合并到 css.inject，与 css.inject 同时设置时抛错。
+   */
+  injectStyle?: unknown;
+  /**
+   * @deprecated 使用 `copy` 代替
+   *
+   * 对齐 tsdown deprecated `publicDir`。映射到 copy，与 copy 同时设置时抛错。
+   */
+  publicDir?: unknown;
+  /**
+   * @deprecated 使用 `outExtensions` 代替
+   *
+   * 对齐 tsdown deprecated `outExtension`。映射到 outExtensions，同时设置时抛错。
+   */
+  outExtension?: () => {
+    js?: string;
+    dts?: string;
+  };
+  /**
+   * 注入到产物的环境变量（process.env.* / import.meta.env.*）
+   *
+   * 对齐 tsdown `env`。优先级：env file < process.env < config.env。
+   */
+  env?: Record<string, string>;
+  /**
+   * env 文件路径（如 `.env`）
+   *
+   * 对齐 tsdown `envFile`。读取后按 envPrefix 过滤，合并到 env。
+   * 依赖 Node.js >= 20.12.0 的 `util.parseEnv()`。
+   */
+  envFile?: string;
+  /**
+   * env 变量名前缀过滤（默认 'LZI_BUILDER_'）
+   *
+   * 对齐 tsdown `envPrefix`。只有匹配前缀的变量才注入产物。
+   * 含空字符串时禁用过滤（注入全部，需谨慎）。
+   */
+  envPrefix?: string | string[];
+  /**
+   * 复用 Vite/Vitest 配置文件
+   *
+   * 对齐 tsdown `fromVite`。true 时加载 vite.config.ts，string 指定文件名。
+   * 合并 resolve.alias 与插件到当前构建。
+   */
+  fromVite?: boolean | string;
+  /**
+   * 未使用依赖检查（对齐 tsdown unused）
+   *
+   * 启用后集成 unplugin-unused 检测 package.json 中声明但实际未使用的依赖。
+   * 需要安装 unplugin-unused（动态 import）。
+   */
+  unused?: WithEnabled<Record<string, unknown>>;
+};
+/**
+ * 配置选项类型，消费方传入 defineConfig 的参数
+ */
+type ConfigOptions = Partial<BuilderConfig>;
+/**
+ * 入口配置类型
+ */
+type EntryConfig = string | Record<string, string>;
+/**
+ * 预设配置定义
+ */
+type PresetDefinition = {
+  /**
+   * 入口配置
+   */
+  entry: EntryConfig;
+  /**
+   * 外部依赖
+   */
+  external?: string[];
+  /**
+   * 额外配置
+   */
+  extraConfig?: Partial<BuilderConfig>;
+};
+/**
+ * 解析后的构建配置（对齐 tsdown ResolvedConfig 的概念）
+ *
+ * resolveConfig 把 BuilderConfig 的可选字段填充默认值后返回此类型。
+ * 核心字段变为 required（解析后保证有值），新增 formats（归一化后的格式数组）
+ * 与 dtsEnabled（dts 是否启用）。
+ */
+type ResolvedBuilderConfig = Required<Omit<BuilderConfig, 'format' | 'dts' | 'tsconfig' | 'onSuccess' | 'name' | 'customLogger' | 'target' | 'banner' | 'footer' | 'globalName' | 'root' | 'inputOptions' | 'outputOptions' | 'define' | 'alias' | 'treeshake' | 'loader' | 'banner' | 'footer' | 'hooks' | 'ignoreWatch' | 'external' | 'platform' | 'outExtensions' | 'deps' | 'entry' | 'minify' | 'sourcemap' | 'workspace' | 'copy' | 'report' | 'exports' | 'devtools' | 'failOnWarn' | 'suppressWarnings' | 'publint' | 'attw' | 'globImport' | 'clean' | 'css' | 'filter' | 'write' | 'checks' | 'bundle' | 'removeNodeProtocol' | 'injectStyle' | 'publicDir' | 'outExtension' | 'env' | 'envFile' | 'envPrefix' | 'fromVite' | 'unused' | 'exe'>> & {
+  /**
+   * 归一化后的格式数组（默认 ['es']）
+   */
+  formats: BuildFormat[];
+  /**
+   * 当前 bundle 的格式（单值，per-format 视图）
+   *
+   * 对齐 tsdown ResolvedConfig.format。builder 单 config 多 format 场景下，
+   * build.ts 的 format 循环里构造 per-format 视图 { ...resolved, format }。
+   * 默认取 formats[0]。
+   */
+  format: BuildFormat;
+  /**
+   * package.json（带 packageJsonPath，resolveConfig 读 cwd 向上查找）
+   *
+   * 对齐 tsdown ResolvedConfig.pkg。无 package.json 时为 undefined。
+   * 供 writeExports/publint/attw/bundleDone 使用。
+   */
+  pkg?: PackageJsonWithPath;
+  /**
+   * 包名标签（带颜色，用于日志输出）
+   *
+   * 对齐 tsdown ResolvedConfig.nameLabel。由 generateColor(name) + getNameLabel() 生成。
+   */
+  nameLabel: string | undefined;
+  /**
+   * dts 是否启用（dts !== false && dts !== undefined && dts.enabled !== false）
+   */
+  dtsEnabled: boolean;
+  /**
+   * dts 选项（dtsEnabled 时有值）
+   */
+  dts: DtsOptions | true | undefined;
+  /**
+   * tsconfig 路径（可能为 undefined）
+   */
+  tsconfig: string | undefined;
+  /**
+   * onSuccess 回调或 shell 命令（可能为 undefined）
+   */
+  onSuccess: BuilderConfig['onSuccess'];
+  /**
+   * 包名标签（可能为 undefined）
+   */
+  name: string | undefined;
+  /**
+   * 自定义 logger（可能为 undefined）
+   */
+  customLogger: Logger | undefined;
+  /**
+   * logger 实例（customLogger 优先，否则 createLogger）
+   *
+   * 对齐 tsdown ResolvedConfig.logger。供 writeExports/publint/attw 等使用。
+   */
+  logger: Logger;
+  /**
+   * 编译目标（可能为 undefined 或 false）
+   */
+  /**
+   * 解析后的编译目标（false/undefined 禁用，string[] 已展开 baseline）
+   *
+   * 对齐 tsdown ResolvedConfig.target。resolveConfig 内调 resolveTarget 解析。
+   */
+  target: string[] | undefined;
+  /**
+   * 入口配置（可能为 undefined，runBuild 用 resolveEntry 处理）
+   */
+  entry: BuilderConfig['entry'];
+  /**
+   * 外部依赖（可能为 undefined）
+   */
+  external: BuilderConfig['external'];
+  /**
+   * 构建平台（可能为 undefined）
+   */
+  platform: BuilderConfig['platform'];
+  /**
+   * 输出扩展名函数（可能为 undefined）
+   */
+  outExtensions: BuilderConfig['outExtensions'];
+  /**
+   * deps 选项（可能为 undefined）
+   */
+  deps: BuilderConfig['deps'];
+  /**
+   * hooks（可能为 undefined）
+   */
+  hooks: BuilderConfig['hooks'];
+  /**
+   * ignoreWatch（可能为 undefined）
+   */
+  ignoreWatch: BuilderConfig['ignoreWatch'];
+  /**
+   * define 常量（可能为 undefined）
+   */
+  define: BuilderConfig['define'];
+  /**
+   * 模块别名（可能为 undefined）
+   */
+  alias: BuilderConfig['alias'];
+  /**
+   * treeshake 配置（可能为 undefined）
+   */
+  treeshake: BuilderConfig['treeshake'];
+  /**
+   * loader 映射（可能为 undefined）
+   */
+  loader: BuilderConfig['loader'];
+  /**
+   * banner（可能为 undefined）
+   */
+  banner: BuilderConfig['banner'];
+  /**
+   * footer（可能为 undefined）
+   */
+  footer: BuilderConfig['footer'];
+  /**
+   * IIFE/UMD 全局变量名（可能为 undefined）
+   */
+  globalName: BuilderConfig['globalName'];
+  /**
+   * 输入根目录（可能为 undefined）
+   */
+  root: BuilderConfig['root'];
+  /**
+   * 额外输入选项（可能为 undefined）
+   */
+  inputOptions: BuilderConfig['inputOptions'];
+  /**
+   * 额外输出选项（可能为 undefined）
+   */
+  outputOptions: BuilderConfig['outputOptions'];
+  /**
+   * 产物压缩（可能为 undefined，由 rolldown 默认处理）
+   */
+  minify: BuilderConfig['minify'];
+  /**
+   * sourcemap（可能为 undefined，由 rolldown 默认处理）
+   */
+  sourcemap: BuilderConfig['sourcemap'];
+  /**
+   * workspace 配置（可能为 undefined）
+   */
+  workspace: BuilderConfig['workspace'];
+  /**
+   * copy 选项（可能为 undefined）
+   */
+  copy: BuilderConfig['copy'];
+  /**
+   * report 选项（可能为 undefined 或 false）
+   */
+  report: ReportOptions | false;
+  /**
+   * exports 选项（可能为 undefined 或 false）
+   */
+  exports: ExportsOptions | false;
+  /**
+   * 解析后的 devtools 选项（false 关闭 / DevtoolsOptions）
+   */
+  devtools: DevtoolsOptions | false;
+  /**
+   * 解析后的 failOnWarn（boolean）
+   */
+  failOnWarn: boolean;
+  /**
+   * 解析后的 publint 选项（false 关闭 / PublintOptions）
+   */
+  publint: PublintOptions | false;
+  /**
+   * 解析后的 attw 选项（false 关闭 / AttwOptions）
+   */
+  attw: AttwOptions | false;
+  /**
+   * import.meta.glob 支持（boolean）
+   */
+  globImport: boolean;
+  /**
+   * CSS 处理选项（可能为 undefined，未集成 CSS 插件时）
+   */
+  css: BuilderConfig['css'];
+  /**
+   * 解析后的 clean 路径列表（glob 模式）
+   */
+  clean: string[];
+  /**
+   * 是否写入磁盘（对齐 tsdown ResolvedConfig.write）
+   */
+  write: boolean;
+  /**
+   * 解析后的 checks 选项（含 legacyCjs，对齐 tsdown ResolvedConfig.checks）
+   */
+  checks: ChecksOptions & {
+    legacyCjs: boolean;
+  };
+  /**
+   * 解析后的环境变量（合并 envFile + process.env + config.env，按 envPrefix 过滤）
+   */
+  env: Record<string, string>;
+  /**
+   * env 前缀数组（归一化后）
+   */
+  envPrefix: string[];
+  /**
+   * 解析后的 unused 选项（false 关闭 / Record 选项）
+   */
+  unused: false | Record<string, unknown>;
+  /**
+   * 解析后的 exe 选项（false 关闭 / ExeOptions）
+   */
+  exe: false | {
+    targets?: Array<{
+      platform: 'win' | 'darwin' | 'linux';
+      arch: 'x64' | 'arm64';
+      nodeVersion: string;
+    }>;
+    seaConfig?: Record<string, unknown>;
+    fileName?: string | ((chunk: {
+      fileName: string;
+    }) => string);
+    outDir?: string;
+  };
+};
+/**
+ * 配置加载器策略（对齐 tsdown configLoader）
+ *
+ * - auto：自动选择（bun/native TS → native，否则 unrun）
+ * - native：原生 import()（通过 import-without-cache 追踪依赖）
+ * - tsx：tsx/esm/api 加载
+ * - unrun：unrun 加载（返回传递性依赖）
+ */
+type ConfigLoader = 'auto' | 'native' | 'tsx' | 'unrun';
+/**
+ * 配置函数（对齐 tsdown UserConfigFn）
+ *
+ * 配置文件可导出函数，接收 inlineConfig + CI 状态 + rootConfig（workspace 场景）。
+ *
+ * @param inlineConfig - 内联配置（CLI flags 等）
+ * @param context - CI 状态 + workspace 根配置
+ * @returns 单个或数组 BuilderConfig
+ */
+type BuilderConfigFn = (inlineConfig?: {
+  config?: boolean | string;
+  configLoader?: ConfigLoader;
+  cwd?: string;
+}, context?: {
+  ci: boolean;
+  rootConfig?: BuilderConfig;
+}) => Awaitable<Arrayable<BuilderConfig>>;
+/**
+ * 配置文件导出类型（对齐 tsdown UserConfigExport）
+ *
+ * 配置文件可导出：单个配置对象、数组、或配置函数。
+ */
+type BuilderConfigExport = Awaitable<Arrayable<BuilderConfig> | BuilderConfigFn>;
+//#endregion
+export type { Arrayable, AttwOptions, BuildContext, BuildFormat, BuilderConfig, BuilderConfigExport, BuilderConfigFn, BuilderHooks, CIOption, ConfigLoader, ConfigOptions, CopyEntry, CopyOptions, CopyOptionsFn, DepsOptions, DevtoolsOptions, DtsOptions, EntryConfig, ExportsOptions, LogLevel, LogType, Logger, LoggerOptions, NoExternalFn, PackageJsonWithPath, PresetDefinition, PublintOptions, ReportOptions, ResolvedBuilderConfig, RolldownChunk, RolldownContext, TsdownInputOption, WithEnabled, Workspace };