import type { BuildOptions, Loader } from "esbuild";
/**
 * shared-esbuild-config.ts — DevCompiler 与 BuildCompiler 共享的 esbuild 基础配置
 *
 * DevCompiler（vext dev）和 BuildCompiler（vext build）使用相同的底层 esbuild 配置，
 * 确保开发环境与生产环境的编译行为一致（CJS 输出、相同 target、相同 loader 映射）。
 *
 * 各编译器在此基础上叠加自己的选项：
 *   - DevCompiler：sourcemap: true（inline）、outdir → .vext/dev/、packages: 'external'
 *   - BuildCompiler：sourcemap: 'external'、outdir → dist/、minify（可选）
 *
 * @module lib/build/shared-esbuild-config
 * @see 09a-build.md §2.1（与 DevCompiler 的关系）
 * @see 11a-dev-compiler.md §3（DevCompiler 实现）
 * @see IMPLEMENTATION-PLAN.md 任务 2.1
 */
/**
 * 文件扩展名到 esbuild Loader 的映射表
 *
 * 覆盖所有 Node.js/TypeScript 项目中可能出现的源文件类型：
 *   - .ts / .mts / .cts → 'ts'（TypeScript）
 *   - .js / .mjs / .cjs → 'js'（JavaScript）
 *   - .json → 'json'（JSON 配置文件）
 */
export declare const LOADER_MAP: Record<string, Loader>;
/**
 * 源文件扫描 glob 模式
 *
 * 用于 fast-glob 扫描 src/ 目录下的所有可编译文件。
 * DevCompiler.start() 和 BuildCompiler.build() 均使用此模式。
 */
export declare const SOURCE_GLOB = "**/*.{ts,mts,cts,js,mjs,cjs}";
/**
 * 入口扫描排除模式
 *
 * 排除声明文件、测试文件等不应进入编译管线的文件：
 *   - *.d.ts — TypeScript 类型声明（仅类型，无运行时代码）
 *   - *.test.* / *.spec.* — 测试文件
 *   - __tests__/ — 测试目录
 */
export declare const SOURCE_IGNORE: string[];
/**
 * createBaseEsbuildConfig — 创建 DevCompiler 与 BuildCompiler 共享的 esbuild 基础配置
 *
 * 返回一个 Partial<BuildOptions>，调用方需叠加以下必要字段：
 *   - entryPoints — 入口文件列表
 *   - outdir / outbase — 输出目录
 *   - sourcemap — 'inline' / true / 'external'（Dev 与 Build 不同）
 *   - packages — 'external'（Dev 使用，Build 可选）
 *
 * 设计选择说明：
 *   - format: 'cjs' — 统一输出 CommonJS，解决 ESM import 无法清除 require.cache 的问题
 *   - bundle: false — 逐文件编译，保持模块粒度（不合并文件）
 *   - treeShaking: true — 移除未使用的导出（即使不 bundle 也有效，可去除死代码分支）
 *   - keepNames: true — 保留函数/类名称（错误堆栈可读性、日志中可识别具名函数）
 *   - charset: 'utf8' — 强制 UTF-8 编码（避免 ASCII escape 导致中文乱码）
 *   - target: 'node20' — 与 package.json engines.node >= 20.19.0 对齐
 *
 * @param tsconfigPath tsconfig.json 路径（可选，默认 undefined 由 esbuild 自动查找）
 * @returns esbuild 基础配置对象
 *
 * @example
 * ```ts
 * const base = createBaseEsbuildConfig('/project/tsconfig.json');
 * const ctx = await esbuild.context({
 *   ...base,
 *   entryPoints: ['src/index.ts'],
 *   outdir: '.vext/dev/',
 *   outbase: 'src/',
 *   sourcemap: true,
 *   packages: 'external',
 * });
 * ```
 */
export declare function createBaseEsbuildConfig(tsconfigPath?: string): Partial<BuildOptions>;
/**
 * getLoaderForExtension — 从文件扩展名获取对应的 esbuild Loader
 *
 * 用于 esbuild.transform() 单文件编译场景（DevCompiler.compileSingle）。
 * .mjs / .cjs 映射为 'js' loader（esbuild 不区分 ESM/CJS 的 loader，
 * 输出格式由 format 选项决定）。
 *
 * @param ext 文件扩展名（含点号，如 '.ts'、'.mjs'）
 * @returns 对应的 esbuild Loader，未知扩展名返回 'default'
 */
export declare function getLoaderForExtension(ext: string): Loader;