@meng-xi/vite-plugin 0.1.4 → 0.1.5

package/dist/plugins/autoImport/index.cjs

@@ -0,0 +1,17 @@
+"use strict";const factory_index=require("../../factory/index.cjs"),p=require("node:fs"),i=require("node:path");require("../../logger/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs");function _interopDefaultCompat(s){return s&&typeof s=="object"&&"default"in s?s.default:s}const p__default=_interopDefaultCompat(p),i__default=_interopDefaultCompat(i);function resolveImports(s){if(!s)return[];const e=[];if(Array.isArray(s))for(const t of s)if("module"in t&&"names"in t){const n=t;for(const o of n.names)e.push({module:n.module,name:o,isDefault:n.defaultImport??!1})}else{const n=t;for(const[o,r]of Object.entries(n))for(const a of r)e.push({module:o,name:a,isDefault:!1})}else for(const[t,n]of Object.entries(s))for(const o of n)e.push({module:t,name:o,isDefault:!1});return e}function buildNameLookup(s){const e=new Map;for(const t of s)e.set(t.name,t);return e}function h(s){const e=i__default.basename(s,i__default.extname(s));return e==="index"?i__default.basename(i__default.dirname(s)):e}function scanDirectories(s,e){const t=[];for(const n of s){const o=i__default.isAbsolute(n)?n:i__default.resolve(e,n);!p__default.existsSync(o)||!p__default.statSync(o).isDirectory()||f$1(o,t)}return t}function f$1(s,e){const t=p__default.readdirSync(s,{withFileTypes:!0});for(const n of t){const o=i__default.join(s,n.name);if(n.isDirectory()){if(n.name==="node_modules"||n.name.startsWith("."))continue;f$1(o,e);continue}if(!n.isFile())continue;const r=i__default.extname(n.name).toLowerCase();if(![".ts",".js",".mts",".mjs"].includes(r)||n.name.endsWith(".d.ts"))continue;const a=parseModuleExports(o);a&&e.push(a)}}function parseModuleExports(s){try{const e=p__default.readFileSync(s,"utf-8"),t=[];let n=null;const o=/export\s+(?:async\s+)?function\s+(\w+)/g;let r;for(;(r=o.exec(e))!==null;)t.push(r[1]);const a=/export\s+(?:const|let|var)\s+(\w+)/g;for(;(r=a.exec(e))!==null;)t.push(r[1]);const u=/export\s+class\s+(\w+)/g;for(;(r=u.exec(e))!==null;)t.push(r[1]);const l=/export\s*\{([^}]+)\}/g;for(;(r=l.exec(e))!==null;){const S=r[1].split(",").map(m=>{const v=m.trim().split(/\s+as\s+/);return v.length>1?v[v.length-1].trim():v[0].trim()});for(const m of S)m&&m!=="default"&&t.push(m)}const c=/export\s+default\s+(?:function\s+(\w+)|class\s+(\w+)|(\w+))?/.exec(e);c&&(n=c[1]||c[2]||c[3]||h(s));const $=/export\s+(?:type|interface)\s+(\w+)/g;for(;(r=$.exec(e))!==null;)t.push(r[1]);return t.length===0&&n===null?null:{filePath:s,exports:t,defaultExport:n}}catch{return null}}function scannedModulesToImports(s){const e=[];for(const t of s){for(const n of t.exports)e.push({module:t.filePath,name:n,isDefault:!1});t.defaultExport&&e.push({module:t.filePath,name:t.defaultExport,isDefault:!0})}return e}const g=new Set(["break","case","catch","continue","debugger","default","delete","do","else","finally","for","function","if","in","instanceof","new","return","switch","this","throw","try","typeof","var","void","while","with","class","const","enum","export","extends","import","super","implements","interface","let","package","private","protected","public","static","yield","async","await","of","true","false","null","undefined","NaN","Infinity","console","window","document","global","globalThis","process","require","module","exports","__dirname","__filename","Object","Array","String","Number","Boolean","Symbol","BigInt","Map","Set","WeakMap","WeakSet","Promise","Proxy","Reflect","Error","TypeError","RangeError","SyntaxError","ReferenceError","Date","RegExp","Math","JSON","Intl","ArrayBuffer","DataView","Float32Array","Float64Array","Int8Array","Int16Array","Int32Array","Uint8Array","Uint16Array","Uint32Array","Uint8ClampedArray"]);function y(s){const e=[];let t=0;const n=s.length;for(;t<n;){if(s[t]==="/"&&s[t+1]==="/"){for(;t<n&&s[t]!==`
+`;)e.push(" "),t++;continue}if(s[t]==="/"&&s[t+1]==="*"){for(e.push(" "),e.push(" "),t+=2;t<n&&!(s[t-1]==="*"&&s[t]==="/");)e.push(s[t]===`
+`?`
+`:" "),t++;t<n&&(e.push(" "),t++);continue}if(s[t]==="'"){for(e.push(" "),t++;t<n&&s[t]!=="'";){if(s[t]==="\\"&&t+1<n){e.push(" "),e.push(" "),t+=2;continue}e.push(s[t]===`
+`?`
+`:" "),t++}t<n&&(e.push(" "),t++);continue}if(s[t]==='"'){for(e.push(" "),t++;t<n&&s[t]!=='"';){if(s[t]==="\\"&&t+1<n){e.push(" "),e.push(" "),t+=2;continue}e.push(s[t]===`
+`?`
+`:" "),t++}t<n&&(e.push(" "),t++);continue}if(s[t]==="`"){for(e.push(" "),t++;t<n&&s[t]!=="`";){if(s[t]==="\\"&&t+1<n){e.push(" "),e.push(" "),t+=2;continue}if(s[t]==="$"&&s[t+1]==="{"){e.push(" "),e.push(" "),t+=2;let o=1;for(;t<n&&o>0;)s[t]==="{"&&o++,s[t]==="}"&&o--,o>0&&(e.push(s[t]),t++);t<n&&(e.push(" "),t++);continue}e.push(s[t]===`
+`?`
+`:" "),t++}t<n&&(e.push(" "),t++);continue}e.push(s[t]),t++}return e.join("")}function f(s){return s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function detectUsedImports(s,e,t){const n=[],o=new Set,r=y(s),a=/(?<![.\w$])([a-zA-Z_$][\w$]*)(?=\s*[<(.,:;\n\r)\]}]|$)/g;let u;for(;(u=a.exec(r))!==null;){const l=u[1];if(g.has(l)||o.has(l)||t.has(l))continue;const c=e.get(l);c&&(o.add(l),n.push(c))}return n}function isAlreadyImported(s,e){return!!(new RegExp(`import\\s*\\{[^}]*\\b${f(e)}\\b[^}]*\\}\\s*from`,"m").test(s)||new RegExp(`import\\s+${f(e)}\\s+from`,"m").test(s)||new RegExp(`import\\s*\\*\\s*as\\s+${f(e)}\\s+from`,"m").test(s))}function generateImportStatements(s){const e=new Map;for(const n of s){e.has(n.module)||e.set(n.module,{named:[],default_:null});const o=e.get(n.module);n.isDefault?o.default_===null&&(o.default_=n.name):o.named.includes(n.name)||o.named.push(n.name)}const t=[];for(const[n,o]of e){const r=[];o.default_&&r.push(o.default_),o.named.length>0&&r.push(`{ ${o.named.join(", ")} }`),r.length>0&&t.push(`import ${r.join(", ")} from '${n}'`)}return t.join(`
+`)}function injectImports(s,e,t){if(!e.trim())return s;if(t==="top")return d(s,e);const n=findLastImportEnd(s);return n===-1?d(s,e):s.slice(0,n)+`
+`+e+`
+`+s.slice(n)}function d(s,e){let t=0;if(s.startsWith("#!")){const o=s.indexOf(`
+`);o!==-1?t=o+1:t=s.length}const n=s.slice(t).match(/^\s*["']use strict["'];?\s*\n?/);return n&&(t+=n[0].length),s.slice(0,t)+e+`
+`+s.slice(t)}function findLastImportEnd(s){let e=-1;const t=/^import\s+[\s\S]+?from\s+['"][^'"]+['"];?\s*$/gm;let n;for(;(n=t.exec(s))!==null;){const o=n.index+n[0].length;o>e&&(e=o)}return e}function detectVueTemplateImports(s,e,t){const n=s.match(/<template[^>]*>([\s\S]*?)<\/template>/);if(!n)return[];const o=n[1],r=[],a=/\{\{([\s\S]*?)\}\}/g;let u;for(;(u=a.exec(o))!==null;)r.push(u[1]);const l=/(?:v-[\w-]+|:[\w-]+|@[\w-]+)(?:\.[\w-]+)*="([^"]*)"/g;for(;(u=l.exec(o))!==null;)r.push(u[1]);const c=/v-model="([^"]*)"/g;for(;(u=c.exec(o))!==null;)r.push(u[1]);if(r.length===0)return[];const $=r.join(`
+`),S=[],m=new Set,v=/(?<![.\w$])([a-zA-Z_$][\w$]*)(?=\s*[<(.,:;\n\r)\]}]|$)/g;for(;(u=v.exec($))!==null;){const x=u[1];if(m.has(x)||t.has(x)||g.has(x)||R(x)||I(x))continue;const A=e.get(x);A&&(m.add(x),S.push(A))}return S}const b=new Set(["div","span","p","a","img","ul","ol","li","h1","h2","h3","h4","h5","h6","table","tr","td","th","thead","tbody","form","input","button","select","option","textarea","label","section","article","header","footer","nav","main","aside","script","style","link","meta","title","head","body","html","br","hr","pre","code","em","strong","b","i","u","sub","sup","small","mark","del","ins","blockquote","q","cite","abbr","dfn","kbd","samp","var","time","figure","figcaption","details","summary","dialog","menu","template","slot","component","transition","transition-group","keep-alive","teleport","suspense","video","audio","source","canvas","svg","path","circle","rect","line","polygon","iframe","embed","object","picture","area","map","base","col","colgroup","datalist","fieldset","legend","meter","optgroup","output","progress","ruby","rt","rp","wbr"]);function R(s){return b.has(s.toLowerCase())}function I(s){return s.startsWith("v")&&s.length>1&&s[1]===s[1].toUpperCase()}function generateDtsContent(s){const e=[];e.push("// Auto generated by @meng-xi/vite-plugin autoImport"),e.push("// @ts-nocheck"),e.push("export {}"),e.push("");const t=new Map;for(const n of s)t.has(n.module)||t.set(n.module,[]),t.get(n.module).push(n);e.push("declare global {");for(const[n,o]of t){e.push(`  // from '${n}'`);for(const r of o)r.isDefault?e.push(`  const ${r.name}: typeof import('${n}')['default']`):e.push(`  const ${r.name}: typeof import('${n}')['${r.name}']`);e.push("")}return e.push("}"),e.join(`
+`)}function writeDtsFile(s,e){const t=i__default.dirname(s);p__default.existsSync(t)||p__default.mkdirSync(t,{recursive:!0}),p__default.writeFileSync(s,e,"utf-8")}function shouldUpdateDts(s,e){if(!p__default.existsSync(s))return!0;try{return p__default.readFileSync(s,"utf-8")!==e}catch{return!0}}class w extends factory_index.BasePlugin{nameLookup=new Map;allResolvedImports=[];ignoreSet=new Set;initialized=!1;getDefaultOptions(){return{imports:{},dirs:[],dts:"auto-imports.d.ts",vueTemplate:!1,ignore:[],fileFilter:/\.(vue|jsx|tsx|ts|js|mjs)$/,injectAtPosition:"top"}}validateOptions(){this.validator.field("dts").custom(e=>e===!1||typeof e=="string","dts \u5FC5\u987B\u4E3A false \u6216\u5B57\u7B26\u4E32\u8DEF\u5F84").field("vueTemplate").boolean().field("injectAtPosition").enum(["top","after-last-import"]).validate()}getPluginName(){return"auto-import"}addPluginHooks(e){e.configResolved=()=>{this.initialize()},e.transform={order:"pre",handler:(t,n)=>!this.initialized||!this.options.fileFilter.test(n)?null:this.transformCode(t,n)},e.buildEnd=()=>{this.options.dts&&this.initialized&&this.generateDts()}}initialize(){const e=resolveImports(this.options.imports),t=this.viteConfig?.root||process.cwd(),n=scanDirectories(this.options.dirs,t),o=scannedModulesToImports(n);this.allResolvedImports=[...e,...o],this.nameLookup=buildNameLookup(this.allResolvedImports),this.ignoreSet=new Set(this.options.ignore),this.initialized=!0,this.logger.info(`\u521D\u59CB\u5316\u5B8C\u6210: ${this.allResolvedImports.length} \u4E2A\u81EA\u52A8\u5BFC\u5165\u6620\u5C04, ${n.length} \u4E2A\u626B\u63CF\u6A21\u5757`),this.options.dts&&this.generateDts()}transformCode(e,t){let n=detectUsedImports(e,this.nameLookup,this.ignoreSet);if(this.options.vueTemplate&&t.endsWith(".vue")){const r=detectVueTemplateImports(e,this.nameLookup,this.ignoreSet),a=new Set(n.map(u=>u.name));for(const u of r)a.has(u.name)||(a.add(u.name),n.push(u))}if(n=n.filter(r=>!isAlreadyImported(e,r.name)),n.length===0)return null;const o=generateImportStatements(n);return{code:injectImports(e,o,this.options.injectAtPosition)}}generateDts(){if(this.allResolvedImports.length===0)return;const e=this.viteConfig?.root||process.cwd(),t=i__default.isAbsolute(this.options.dts)?this.options.dts:i__default.resolve(e,this.options.dts),n=generateDtsContent(this.allResolvedImports);shouldUpdateDts(t,n)&&this.safeExecuteSync(()=>{writeDtsFile(t,n),this.logger.info(`\u7C7B\u578B\u58F0\u660E\u6587\u4EF6\u5DF2\u751F\u6210: ${this.options.dts}`)},"\u751F\u6210\u7C7B\u578B\u58F0\u660E\u6587\u4EF6")}getResolvedImports(){return[...this.allResolvedImports]}getNameLookup(){return new Map(this.nameLookup)}}const autoImport=factory_index.createPluginFactory(w);exports.autoImport=autoImport;

package/dist/plugins/autoImport/index.d.cts

@@ -0,0 +1,291 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
+import 'vite';
+import '../../shared/vite-plugin.B8FuZce1.cjs';
+import '../../shared/vite-plugin.DRRlWY8P.cjs';
+
+/**
+ * 单个导入映射项
+ *
+ * @description 定义从某个模块导入的名称列表，
+ * 支持命名导入和默认导入两种方式。
+ * 用于 `AutoImportOptions.imports` 数组格式中。
+ *
+ * @example
+ * ```typescript
+ * const mapping: ImportMapping = {
+ *   module: 'lodash',
+ *   names: ['debounce', 'throttle'],
+ *   defaultImport: false
+ * }
+ * ```
+ */
+interface ImportMapping {
+    /**
+     * 模块路径
+     *
+     * @description 可以是 npm 包名（如 `'vue'`、`'vue-router'`）
+     * 或相对/绝对文件路径（如 `'./utils/helper'`）
+     */
+    module: string;
+    /**
+     * 要导入的名称列表
+     *
+     * @description 从指定模块导入的标识符名称数组。
+     * 当 `defaultImport` 为 `true` 时，列表中的名称将作为默认导入的别名。
+     */
+    names: string[];
+    /**
+     * 是否为默认导入
+     *
+     * @default false
+     *
+     * @description 设为 `true` 时，生成的 import 语句形式为
+     * `import name from 'module'` 而非 `import { name } from 'module'`
+     */
+    defaultImport?: boolean;
+}
+/**
+ * 自动导入插件的配置选项
+ *
+ * @interface AutoImportOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 配置自动导入插件的行为，包括导入映射、目录扫描、
+ * 类型声明生成、Vue 模板支持等。
+ *
+ * @example
+ * ```typescript
+ * autoImport({
+ *   imports: {
+ *     vue: ['ref', 'reactive', 'computed', 'watch', 'onMounted'],
+ *     'vue-router': ['useRouter', 'useRoute']
+ *   },
+ *   dirs: ['src/composables', 'src/stores'],
+ *   dts: 'src/auto-imports.d.ts',
+ *   vueTemplate: true,
+ *   injectAtPosition: 'top'
+ * })
+ * ```
+ */
+interface AutoImportOptions extends BasePluginOptions {
+    /**
+     * 导入映射配置
+     *
+     * @description 支持三种格式：
+     * 1. **简写格式**：`Record<string, string[]>` — 键为模块路径，值为导入名称数组
+     *    ```typescript
+     *    { vue: ['ref', 'reactive'] }
+     *    ```
+     * 2. **完整格式**：`ImportMapping[]` — 支持默认导入配置
+     *    ```typescript
+     *    [{ module: 'lodash', names: ['debounce'], defaultImport: true }]
+     *    ```
+     * 3. **混合格式**：两种格式可以在数组中混合使用
+     *
+     * @default {}
+     */
+    imports?: Record<string, string[]> | ImportMapping[] | Array<Record<string, string[]> | ImportMapping>;
+    /**
+     * 需要扫描的目录列表
+     *
+     * @description 自动扫描这些目录下的 `.ts`/`.js`/`.mts`/`.mjs` 文件，
+     * 将导出的函数、变量、类等注册为可自动导入的标识符。
+     * 支持绝对路径和相对路径（相对于项目根目录）。
+     *
+     * **扫描规则：**
+     * - 递归扫描子目录
+     * - 跳过 `node_modules` 和隐藏目录（以 `.` 开头）
+     * - 跳过 `.d.ts` 类型声明文件
+     *
+     * @default []
+     */
+    dirs?: string[];
+    /**
+     * TypeScript 类型声明文件输出路径
+     *
+     * @description 控制是否生成 `.d.ts` 类型声明文件：
+     * - `string`：在指定路径生成类型声明文件
+     * - `false`：不生成类型声明文件
+     *
+     * 路径可以是相对路径（相对于项目根目录）或绝对路径。
+     *
+     * @default 'auto-imports.d.ts'
+     */
+    dts?: string | boolean;
+    /**
+     * 是否为 Vue 模板启用自动导入
+     *
+     * @description 开启后，Vue SFC 文件 `<template>` 中使用的 API
+     * （如 `ref`、`computed`）也会被自动导入，
+     * 无需在 `<script>` 中显式 `import`。
+     *
+     * **检测范围：**
+     * - 插值表达式 `{{ }}` 中的标识符
+     * - 指令绑定 `v-if`、`v-show`、`v-model` 等中的表达式
+     * - 属性绑定 `:prop="expr"` 中的表达式
+     * - 事件绑定 `@event="handler"` 中的表达式
+     *
+     * @default false
+     */
+    vueTemplate?: boolean;
+    /**
+     * 需要忽略的标识符列表
+     *
+     * @description 这些标识符即使匹配到映射规则也不会被自动导入。
+     * 适用于与全局变量冲突的场景，例如某些标识符在运行时已通过
+     * 其他方式全局注册。
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * ignore: ['React'] // 如果 React 已通过 CDN 全局注入
+     * ```
+     */
+    ignore?: string[];
+    /**
+     * 文件过滤正则表达式
+     *
+     * @description 只有文件路径匹配此正则的文件才会被 `transform` 钩子处理。
+     * 不匹配的文件将被跳过，不进行自动导入注入。
+     *
+     * @default /\.(vue|jsx|tsx|ts|js|mjs)$/
+     */
+    fileFilter?: RegExp;
+    /**
+     * import 语句注入位置
+     *
+     * @description 控制自动生成的 import 语句在文件中的插入位置：
+     * - `'top'`：注入到文件有效代码最顶部（自动跳过 shebang 和 `"use strict"`）
+     * - `'after-last-import'`：注入到最后一个已有 import 语句之后；
+     *   若无已有 import，回退到顶部注入
+     *
+     * @default 'top'
+     */
+    injectAtPosition?: 'top' | 'after-last-import';
+}
+/**
+ * 内部使用的解析后映射项
+ *
+ * @description 统一的导入映射结构，由用户配置（`imports` 和 `dirs` 扫描结果）
+ * 解析而来。所有格式的导入配置最终都会转换为这个统一结构。
+ */
+interface ResolvedImport {
+    /**
+     * 模块路径
+     *
+     * @description 可以是 npm 包名（如 `'vue'`）或文件绝对路径
+     * （目录扫描结果使用绝对路径）
+     */
+    module: string;
+    /**
+     * 导入标识符名称
+     *
+     * @description 在代码中检测到此名称使用时，将自动从对应模块导入
+     */
+    name: string;
+    /**
+     * 是否为默认导入
+     *
+     * @description `true` 时生成 `import name from 'module'`，
+     * `false` 时生成 `import { name } from 'module'`
+     */
+    isDefault: boolean;
+}
+/**
+ * 扫描到的模块信息
+ *
+ * @description 从目录中扫描到的文件导出信息，
+ * 由 {@link parseModuleExports} 函数解析生成
+ */
+interface ScannedModule {
+    /**
+     * 模块文件的绝对路径
+     *
+     * @description 用于生成 import 语句中的模块来源路径
+     */
+    filePath: string;
+    /**
+     * 命名导出名称列表
+     *
+     * @description 包含所有通过 `export function`、`export const`、
+     * `export class`、`export { ... }`、`export type`、`export interface`
+     * 等语法导出的标识符名称
+     */
+    exports: string[];
+    /**
+     * 默认导出名称
+     *
+     * @description 通过 `export default` 导出的标识符名称。
+     * 如果默认导出没有命名（如 `export default {}`），
+     * 则使用文件名作为标识符名称。无默认导出时为 `null`。
+     */
+    defaultExport: string | null;
+}
+/**
+ * 代码转换结果
+ *
+ * @description `transformCode` 方法的返回类型，
+ * 包含转换后的代码和可选的 source map
+ */
+interface TransformResult {
+    /**
+     * 转换后的代码字符串
+     *
+     * @description 注入了自动 import 语句后的完整源代码
+     */
+    code: string;
+    /**
+     * Source map 信息（可选）
+     *
+     * @description 用于支持调试时映射回原始源代码位置，
+     * 当前实现中暂未生成 source map
+     */
+    map?: any;
+}
+
+/**
+ * 创建自动导入插件
+ *
+ * @function autoImport
+ * @param {AutoImportOptions} [options] - 插件配置选项
+ * @returns {Plugin} Vite 插件实例
+ *
+ * @description 自动注入 import 语句的 Vite 插件工厂函数。
+ * 支持预设映射和目录扫描两种方式发现可自动导入的标识符，
+ * 可选生成 TypeScript 类型声明文件，支持 Vue 模板自动导入。
+ *
+ * **特性：**
+ * - 多格式导入映射配置（简写 / 完整 / 混合）
+ * - 递归目录扫描，自动发现导出
+ * - 智能去重，跳过已显式导入的标识符
+ * - Vue SFC 模板自动导入支持
+ * - TypeScript 类型声明自动生成
+ * - 可配置注入位置（顶部 / 最后 import 后）
+ * - 自动跳过 shebang 和 `"use strict"`
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { autoImport } from '@meng-xi/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     autoImport({
+ *       imports: {
+ *         vue: ['ref', 'reactive', 'computed', 'watch', 'onMounted'],
+ *         'vue-router': ['useRouter', 'useRoute']
+ *       },
+ *       dirs: ['src/composables'],
+ *       dts: 'src/auto-imports.d.ts',
+ *       vueTemplate: true,
+ *       injectAtPosition: 'after-last-import'
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare const autoImport: PluginFactory<AutoImportOptions, AutoImportOptions>;
+
+export { autoImport };
+export type { AutoImportOptions, ImportMapping, ResolvedImport, ScannedModule, TransformResult };

package/dist/plugins/autoImport/index.d.mts

@@ -0,0 +1,291 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
+import 'vite';
+import '../../shared/vite-plugin.B8FuZce1.mjs';
+import '../../shared/vite-plugin.DRRlWY8P.mjs';
+
+/**
+ * 单个导入映射项
+ *
+ * @description 定义从某个模块导入的名称列表，
+ * 支持命名导入和默认导入两种方式。
+ * 用于 `AutoImportOptions.imports` 数组格式中。
+ *
+ * @example
+ * ```typescript
+ * const mapping: ImportMapping = {
+ *   module: 'lodash',
+ *   names: ['debounce', 'throttle'],
+ *   defaultImport: false
+ * }
+ * ```
+ */
+interface ImportMapping {
+    /**
+     * 模块路径
+     *
+     * @description 可以是 npm 包名（如 `'vue'`、`'vue-router'`）
+     * 或相对/绝对文件路径（如 `'./utils/helper'`）
+     */
+    module: string;
+    /**
+     * 要导入的名称列表
+     *
+     * @description 从指定模块导入的标识符名称数组。
+     * 当 `defaultImport` 为 `true` 时，列表中的名称将作为默认导入的别名。
+     */
+    names: string[];
+    /**
+     * 是否为默认导入
+     *
+     * @default false
+     *
+     * @description 设为 `true` 时，生成的 import 语句形式为
+     * `import name from 'module'` 而非 `import { name } from 'module'`
+     */
+    defaultImport?: boolean;
+}
+/**
+ * 自动导入插件的配置选项
+ *
+ * @interface AutoImportOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 配置自动导入插件的行为，包括导入映射、目录扫描、
+ * 类型声明生成、Vue 模板支持等。
+ *
+ * @example
+ * ```typescript
+ * autoImport({
+ *   imports: {
+ *     vue: ['ref', 'reactive', 'computed', 'watch', 'onMounted'],
+ *     'vue-router': ['useRouter', 'useRoute']
+ *   },
+ *   dirs: ['src/composables', 'src/stores'],
+ *   dts: 'src/auto-imports.d.ts',
+ *   vueTemplate: true,
+ *   injectAtPosition: 'top'
+ * })
+ * ```
+ */
+interface AutoImportOptions extends BasePluginOptions {
+    /**
+     * 导入映射配置
+     *
+     * @description 支持三种格式：
+     * 1. **简写格式**：`Record<string, string[]>` — 键为模块路径，值为导入名称数组
+     *    ```typescript
+     *    { vue: ['ref', 'reactive'] }
+     *    ```
+     * 2. **完整格式**：`ImportMapping[]` — 支持默认导入配置
+     *    ```typescript
+     *    [{ module: 'lodash', names: ['debounce'], defaultImport: true }]
+     *    ```
+     * 3. **混合格式**：两种格式可以在数组中混合使用
+     *
+     * @default {}
+     */
+    imports?: Record<string, string[]> | ImportMapping[] | Array<Record<string, string[]> | ImportMapping>;
+    /**
+     * 需要扫描的目录列表
+     *
+     * @description 自动扫描这些目录下的 `.ts`/`.js`/`.mts`/`.mjs` 文件，
+     * 将导出的函数、变量、类等注册为可自动导入的标识符。
+     * 支持绝对路径和相对路径（相对于项目根目录）。
+     *
+     * **扫描规则：**
+     * - 递归扫描子目录
+     * - 跳过 `node_modules` 和隐藏目录（以 `.` 开头）
+     * - 跳过 `.d.ts` 类型声明文件
+     *
+     * @default []
+     */
+    dirs?: string[];
+    /**
+     * TypeScript 类型声明文件输出路径
+     *
+     * @description 控制是否生成 `.d.ts` 类型声明文件：
+     * - `string`：在指定路径生成类型声明文件
+     * - `false`：不生成类型声明文件
+     *
+     * 路径可以是相对路径（相对于项目根目录）或绝对路径。
+     *
+     * @default 'auto-imports.d.ts'
+     */
+    dts?: string | boolean;
+    /**
+     * 是否为 Vue 模板启用自动导入
+     *
+     * @description 开启后，Vue SFC 文件 `<template>` 中使用的 API
+     * （如 `ref`、`computed`）也会被自动导入，
+     * 无需在 `<script>` 中显式 `import`。
+     *
+     * **检测范围：**
+     * - 插值表达式 `{{ }}` 中的标识符
+     * - 指令绑定 `v-if`、`v-show`、`v-model` 等中的表达式
+     * - 属性绑定 `:prop="expr"` 中的表达式
+     * - 事件绑定 `@event="handler"` 中的表达式
+     *
+     * @default false
+     */
+    vueTemplate?: boolean;
+    /**
+     * 需要忽略的标识符列表
+     *
+     * @description 这些标识符即使匹配到映射规则也不会被自动导入。
+     * 适用于与全局变量冲突的场景，例如某些标识符在运行时已通过
+     * 其他方式全局注册。
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * ignore: ['React'] // 如果 React 已通过 CDN 全局注入
+     * ```
+     */
+    ignore?: string[];
+    /**
+     * 文件过滤正则表达式
+     *
+     * @description 只有文件路径匹配此正则的文件才会被 `transform` 钩子处理。
+     * 不匹配的文件将被跳过，不进行自动导入注入。
+     *
+     * @default /\.(vue|jsx|tsx|ts|js|mjs)$/
+     */
+    fileFilter?: RegExp;
+    /**
+     * import 语句注入位置
+     *
+     * @description 控制自动生成的 import 语句在文件中的插入位置：
+     * - `'top'`：注入到文件有效代码最顶部（自动跳过 shebang 和 `"use strict"`）
+     * - `'after-last-import'`：注入到最后一个已有 import 语句之后；
+     *   若无已有 import，回退到顶部注入
+     *
+     * @default 'top'
+     */
+    injectAtPosition?: 'top' | 'after-last-import';
+}
+/**
+ * 内部使用的解析后映射项
+ *
+ * @description 统一的导入映射结构，由用户配置（`imports` 和 `dirs` 扫描结果）
+ * 解析而来。所有格式的导入配置最终都会转换为这个统一结构。
+ */
+interface ResolvedImport {
+    /**
+     * 模块路径
+     *
+     * @description 可以是 npm 包名（如 `'vue'`）或文件绝对路径
+     * （目录扫描结果使用绝对路径）
+     */
+    module: string;
+    /**
+     * 导入标识符名称
+     *
+     * @description 在代码中检测到此名称使用时，将自动从对应模块导入
+     */
+    name: string;
+    /**
+     * 是否为默认导入
+     *
+     * @description `true` 时生成 `import name from 'module'`，
+     * `false` 时生成 `import { name } from 'module'`
+     */
+    isDefault: boolean;
+}
+/**
+ * 扫描到的模块信息
+ *
+ * @description 从目录中扫描到的文件导出信息，
+ * 由 {@link parseModuleExports} 函数解析生成
+ */
+interface ScannedModule {
+    /**
+     * 模块文件的绝对路径
+     *
+     * @description 用于生成 import 语句中的模块来源路径
+     */
+    filePath: string;
+    /**
+     * 命名导出名称列表
+     *
+     * @description 包含所有通过 `export function`、`export const`、
+     * `export class`、`export { ... }`、`export type`、`export interface`
+     * 等语法导出的标识符名称
+     */
+    exports: string[];
+    /**
+     * 默认导出名称
+     *
+     * @description 通过 `export default` 导出的标识符名称。
+     * 如果默认导出没有命名（如 `export default {}`），
+     * 则使用文件名作为标识符名称。无默认导出时为 `null`。
+     */
+    defaultExport: string | null;
+}
+/**
+ * 代码转换结果
+ *
+ * @description `transformCode` 方法的返回类型，
+ * 包含转换后的代码和可选的 source map
+ */
+interface TransformResult {
+    /**
+     * 转换后的代码字符串
+     *
+     * @description 注入了自动 import 语句后的完整源代码
+     */
+    code: string;
+    /**
+     * Source map 信息（可选）
+     *
+     * @description 用于支持调试时映射回原始源代码位置，
+     * 当前实现中暂未生成 source map
+     */
+    map?: any;
+}
+
+/**
+ * 创建自动导入插件
+ *
+ * @function autoImport
+ * @param {AutoImportOptions} [options] - 插件配置选项
+ * @returns {Plugin} Vite 插件实例
+ *
+ * @description 自动注入 import 语句的 Vite 插件工厂函数。
+ * 支持预设映射和目录扫描两种方式发现可自动导入的标识符，
+ * 可选生成 TypeScript 类型声明文件，支持 Vue 模板自动导入。
+ *
+ * **特性：**
+ * - 多格式导入映射配置（简写 / 完整 / 混合）
+ * - 递归目录扫描，自动发现导出
+ * - 智能去重，跳过已显式导入的标识符
+ * - Vue SFC 模板自动导入支持
+ * - TypeScript 类型声明自动生成
+ * - 可配置注入位置（顶部 / 最后 import 后）
+ * - 自动跳过 shebang 和 `"use strict"`
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { autoImport } from '@meng-xi/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     autoImport({
+ *       imports: {
+ *         vue: ['ref', 'reactive', 'computed', 'watch', 'onMounted'],
+ *         'vue-router': ['useRouter', 'useRoute']
+ *       },
+ *       dirs: ['src/composables'],
+ *       dts: 'src/auto-imports.d.ts',
+ *       vueTemplate: true,
+ *       injectAtPosition: 'after-last-import'
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare const autoImport: PluginFactory<AutoImportOptions, AutoImportOptions>;
+
+export { autoImport };
+export type { AutoImportOptions, ImportMapping, ResolvedImport, ScannedModule, TransformResult };