@path-ioc/unplugin 0.1.1

package/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+  <h1>@path-ioc/unplugin</h1>
+  <p><b>Universal Dev Plugin for Path-IoC (Virtual Container & Type Generator)</b></p>
+  <p>跨构建工具（Vite / Rolldown / Webpack / Rspack / Rollup / Esbuild）的通用虚拟模块注入与 TypeScript 类型自动推导插件</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@path-ioc/unplugin"><img src="https://img.shields.io/npm/v/@path-ioc/unplugin.svg" alt="NPM version"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/@path-ioc/unplugin.svg" alt="License"></a>
+    <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
+    <a href="https://vite.dev"><img src="https://img.shields.io/badge/powered%20by-Vite-646CFF?logo=vite&logoColor=white" alt="Vite"></a>
+    <a href="https://rolldown.rs"><img src="https://img.shields.io/badge/Rolldown-ready-FF6B6B?logo=rust&logoColor=white" alt="Rolldown"></a>
+    <a href="https://rspack.dev"><img src="https://img.shields.io/badge/Rspack-compatible-EE6338?logo=rspack&logoColor=white" alt="Rspack"></a>
+    <a href="https://webpack.js.org"><img src="https://img.shields.io/badge/Webpack-5-8DD6F9?logo=webpack&logoColor=black" alt="Webpack"></a>
+  </p>
+</div>
+
+> 💡 **核心定位**：`@path-ioc/unplugin` 是 [`@path-ioc/core`](../core) 的编译期伴生驱动引擎。在真实生产工程中，两者密不可分：`unplugin` 负责在构建期自动扫描物理目录并实时生成 `.d.ts` 类型推导，`core` 负责在运行时进行极速无锁 DAG 拓扑装配。  
+> **完整的架构设计哲学、模块编写规范、依赖查找与端到端完整指南，请直接查阅：**  
+> 📖 **[`@path-ioc/core` 官方指南](../core/README.md)** 或访问官方主站 **[https://path-ioc.dev](https://path-ioc.dev)**。
+
+---
+
+## 核心职能 (Key Responsibilities)
+
+- **全构建器原生支持 (Universal Bundler Support)**：
+  基于 `unplugin` 规范，一套逻辑原生适配 **Vite**、**Rolldown (Rust)**、**Webpack 5**、**Rspack**、**Rollup** 与 **Esbuild**。
+- **`virtual:modular-container` 虚拟模块流式注入**：
+  构建期自动扫描 `src/modules/**/index.{ts,tsx}`，动态生成全量模块注册表。在 Vite/Rolldown/Rollup 环境下纯内存流式注入，在 Webpack/Rspack 下自动创建临时代理桥接。
+- **TypeScript 零配置类型合成**：
+  开发时与 HMR 热更新时毫秒级生成 `ignore.modular.d.ts`，自动扩充全局 `ModularContainer` 接口，解构享 100% 准确 IDE 提示。
+- **Git 规避自愈 (`.gitignore` 自动维护)**：
+  自动向项目 `.gitignore` 补充 `ignore.*` 规则，防止生成的临时声明污染版本控制。
+
+---
+
+## 安装 (Installation)
+
+```bash
+pnpm add -D @path-ioc/unplugin
+pnpm add @path-ioc/core
+```
+
+---
+
+## 构建工具集成速查 (Bundler Quick Reference)
+
+### 1. Vite (`vite.config.ts`)
+```typescript
+import { defineConfig } from "vite";
+import { vitePlugin as pathIoc } from "@path-ioc/unplugin";
+
+export default defineConfig({
+  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+});
+```
+
+### 2. Rolldown (`rolldown.config.ts`)
+```typescript
+import { defineConfig } from "rolldown";
+import { rolldownPlugin as pathIoc } from "@path-ioc/unplugin";
+
+export default defineConfig({
+  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+});
+```
+
+### 3. Rspack (`rspack.config.js`)
+```javascript
+const { rspackPlugin: pathIoc } = require("@path-ioc/unplugin");
+
+module.exports = {
+  plugins: [pathIoc()],
+};
+```
+
+### 4. Webpack 5 (`webpack.config.js`)
+```javascript
+const { webpackPlugin: pathIoc } = require("@path-ioc/unplugin");
+
+module.exports = {
+  plugins: [pathIoc({ modulesPath: "src/modules" })],
+};
+```
+
+### 5. Rollup (`rollup.config.js`) / Esbuild
+```javascript
+// Rollup
+import { rollupPlugin as pathIoc } from "@path-ioc/unplugin";
+// Esbuild
+import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
+```
+
+---
+
+## 插件配置项 (Plugin Options)
+
+| 配置项 | 类型 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| **`modulesPath`** | `string` | `'src/modules'` | 模块扫描的物理根目录路径。 |
+| **`typeFileOutput`** | `string` | `'types'` | 自动生成的类型声明文件 `ignore.modular.d.ts` 存放相对目录。 |
+
+---
+
+## 真实应用与模块编写
+
+关于如何编写 `main` 纯函数模块、声明依赖、在应用入口一行唤醒容器，请参阅：  
+👉 **[查看 @path-ioc/core 完整实战指南](../core/README.md)**
+
+
+---
+
+## 许可证 (License)
+
+Released under the [MIT License](./LICENSE).  
+Copyright © 2026 [Path-IoC Organization](https://github.com/path-ioc) & Lian HanLin.

package/dist/index.cjs

@@ -0,0 +1,351 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PathIocPlugin: () => PathIocPlugin,
+  default: () => index_default,
+  esbuildPlugin: () => esbuildPlugin,
+  rolldownPlugin: () => rolldownPlugin,
+  rollupPlugin: () => rollupPlugin,
+  rspackPlugin: () => rspackPlugin,
+  vitePlugin: () => vitePlugin,
+  webpackPlugin: () => webpackPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_path2 = __toESM(require("path"), 1);
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_unplugin = require("unplugin");
+
+// src/generator.ts
+var import_node_path = __toESM(require("path"), 1);
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_lodash_es = require("lodash-es");
+var import_fast_glob = __toESM(require("fast-glob"), 1);
+
+// src/utils.ts
+function createTrailingRunner(asyncFn) {
+  let isRunning = false;
+  let pendingArgs = null;
+  let pendingWaiters = [];
+  const startLoop = async (initialArgs) => {
+    isRunning = true;
+    let latestResult;
+    let currentArgs = initialArgs;
+    while (true) {
+      const argsToRun = currentArgs;
+      const currentWaiters = pendingWaiters;
+      pendingArgs = null;
+      pendingWaiters = [];
+      try {
+        latestResult = await asyncFn(...argsToRun);
+        currentWaiters.forEach((w) => w.resolve(latestResult));
+      } catch (err) {
+        currentWaiters.forEach((w) => w.reject(err));
+      }
+      if (pendingArgs !== null) {
+        currentArgs = pendingArgs;
+      } else {
+        break;
+      }
+    }
+    isRunning = false;
+    return latestResult;
+  };
+  return (...args) => {
+    if (!isRunning) {
+      return startLoop(args);
+    }
+    pendingArgs = args;
+    return new Promise((resolve, reject) => {
+      pendingWaiters.push({ resolve, reject });
+    });
+  };
+}
+
+// src/generator.ts
+var cachedFolderSet = null;
+function generateModuleMapContent(folders, rootDir, typeDir, modulesPathStr) {
+  if (folders.length === 0) {
+    return `// This file is generated by @path-ioc/unplugin, do not edit.
+
+declare global {
+  interface ModuleMap {
+    [key: string]: any;
+  }
+  interface ModularContainer {
+    [key: string]: any;
+  }
+}
+
+export {};
+`;
+  }
+  const dtsDir = import_node_path.default.resolve(rootDir, typeDir);
+  const modulesRoot = import_node_path.default.resolve(rootDir, modulesPathStr);
+  const moduleFolderMap = /* @__PURE__ */ new Map();
+  const shortNameFullNamesMap = /* @__PURE__ */ new Map();
+  folders.forEach((relDir) => {
+    const dirPath = import_node_path.default.resolve(rootDir, relDir);
+    let importRelPath = import_node_path.default.relative(dtsDir, dirPath).replace(/\\/g, "/");
+    if (!importRelPath.startsWith(".")) {
+      importRelPath = "./" + importRelPath;
+    }
+    const logicalPath = import_node_path.default.relative(modulesRoot, dirPath).replace(/\\/g, "/");
+    const folderName = logicalPath.split("/").pop();
+    if (!folderName) return;
+    const moduleName = folderName.charAt(0) + (0, import_lodash_es.camelCase)(folderName).slice(1);
+    const logicalDir = logicalPath.substring(0, logicalPath.lastIndexOf(folderName));
+    const moduleFullName = `/${logicalDir}${moduleName}`;
+    moduleFolderMap.set(moduleFullName, importRelPath);
+    moduleFolderMap.set(moduleName, importRelPath);
+    const fullNames = shortNameFullNamesMap.get(moduleName) || [];
+    fullNames.push(moduleFullName);
+    shortNameFullNamesMap.set(moduleName, fullNames);
+  });
+  for (const [shortName, fullNames] of shortNameFullNamesMap.entries()) {
+    if (fullNames.length > 1) {
+      moduleFolderMap.delete(shortName);
+    }
+  }
+  const entries = [];
+  const containerEntries = [];
+  for (const [key, relPath] of moduleFolderMap.entries()) {
+    entries.push(`    "${key}": typeof import("${relPath}/index");`);
+    containerEntries.push(`    "${key}": Awaited<ReturnType<typeof import("${relPath}/index")["main"]>>;`);
+  }
+  return `// This file is generated by @path-ioc/unplugin, do not edit.
+/// <reference types="@path-ioc/unplugin/virtual" />
+
+declare global {
+  interface ModuleMap {
+    [key: string]: any;
+${entries.join("\n")}
+  }
+  interface ModularContainer {
+    [key: string]: any;
+${containerEntries.join("\n")}
+  }
+}
+
+export {};
+`;
+}
+var doGenerateTypeDefinitions = async (rootDir, typeDir, modulesPathStr) => {
+  try {
+    const modulesRoot = import_node_path.default.resolve(rootDir, modulesPathStr);
+    const dotIgnorePath = import_node_path.default.resolve(rootDir, ".gitignore");
+    try {
+      const dotIgnoreContent = await import_promises.default.readFile(dotIgnorePath, "utf-8");
+      if (!dotIgnoreContent.includes("ignore.*")) {
+        await import_promises.default.appendFile(
+          dotIgnorePath,
+          `
+
+# @path-ioc/unplugin
+ignore.*
+`
+        );
+      }
+    } catch (e) {
+    }
+    const dtsDir = import_node_path.default.resolve(rootDir, typeDir);
+    await import_promises.default.mkdir(dtsDir, { recursive: true });
+    const dtsPath = import_node_path.default.resolve(dtsDir, "ignore.modular.d.ts");
+    const searchPattern = import_node_path.default.posix.join(modulesRoot.replace(/\\/g, "/"), "**/index.{ts,tsx}");
+    const files = await (0, import_fast_glob.default)(searchPattern, { absolute: true });
+    const folders = files.map((f) => import_node_path.default.relative(rootDir, import_node_path.default.dirname(f)));
+    if (cachedFolderSet && cachedFolderSet.size === folders.length && import_node_fs.default.existsSync(dtsPath)) {
+      let isIdentical = true;
+      for (let i = 0; i < folders.length; i++) {
+        if (!cachedFolderSet.has(folders[i])) {
+          isIdentical = false;
+          break;
+        }
+      }
+      if (isIdentical) {
+        return;
+      }
+    }
+    cachedFolderSet = new Set(folders);
+    const content = generateModuleMapContent(folders, rootDir, typeDir, modulesPathStr);
+    await import_promises.default.writeFile(dtsPath, content, { flag: "w" });
+  } catch (e) {
+  }
+};
+var generateTypeDefinitions = createTrailingRunner(doGenerateTypeDefinitions);
+
+// src/index.ts
+var VIRTUAL_MODULE_ID = "virtual:modular-container";
+var RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+var PathIocPlugin = (0, import_unplugin.createUnplugin)((options = {}, meta) => {
+  const { typeFileOutput = "types", modulesPath = "src/modules" } = options;
+  let projectRoot = process.cwd();
+  const isWebpackLike = meta.framework === "webpack" || meta.framework === "rspack";
+  return {
+    name: "unplugin-path-ioc",
+    enforce: "pre",
+    // Webpack / Vite 钩子获取根目录
+    vite: {
+      configResolved(config) {
+        if (config && typeof config === "object" && "root" in config && typeof config.root === "string") {
+          projectRoot = import_node_path2.default.resolve(config.root);
+        }
+      },
+      async handleHotUpdate(ctx) {
+        if (ctx && typeof ctx === "object" && "file" in ctx && typeof ctx.file === "string") {
+          const file = ctx.file;
+          if (file.endsWith(".d.ts") || file.includes("ignore.")) return;
+          const relativeModulesPath = import_node_path2.default.normalize(modulesPath);
+          if (file.includes(import_node_path2.default.join(projectRoot, relativeModulesPath))) {
+            await generateTypeDefinitions(projectRoot, typeFileOutput, modulesPath);
+          }
+        }
+      }
+    },
+    webpack(compiler) {
+      projectRoot = compiler.context;
+      const cleanPath = modulesPath.replace(/\/$/, "");
+      const virtualPath = import_node_path2.default.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      const absModulesPath = import_node_path2.default.resolve(projectRoot, cleanPath).replace(/\\/g, "/");
+      const virtualCode = `
+        import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+        const reqContext = require.context('${absModulesPath}', true, /\\/index\\.[jt]sx?$/);
+        export const modules = reqContext.keys().map((k) => {
+          const rawKey = k.replace(/^\\.\\//, '').replace(/\\/index\\.[jt]sx?$/, '');
+          return { key: '/' + rawKey, module: reqContext(k) };
+        });
+
+        let compiledGraph = null;
+
+        export async function createModularContainer(modularContainer = {}) {
+          if (!compiledGraph) {
+            compiledGraph = compileModuleGraph(modules);
+          }
+          await instantiateModuleContainer(compiledGraph, modularContainer);
+          return modularContainer;
+        }
+      `;
+      try {
+        import_node_fs2.default.mkdirSync(import_node_path2.default.dirname(virtualPath), { recursive: true });
+        import_node_fs2.default.writeFileSync(virtualPath, virtualCode, "utf-8");
+      } catch (e) {
+      }
+      if (compiler.webpack && compiler.webpack.NormalModuleReplacementPlugin) {
+        new compiler.webpack.NormalModuleReplacementPlugin(
+          /^virtual:modular-container$/,
+          virtualPath
+        ).apply(compiler);
+      }
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID || id.includes("virtual:modular-container")) {
+        if (isWebpackLike && projectRoot) {
+          return import_node_path2.default.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+        }
+        return RESOLVED_VIRTUAL_MODULE_ID;
+      }
+    },
+    loadInclude(id) {
+      const virtualPath = import_node_path2.default.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      return id === RESOLVED_VIRTUAL_MODULE_ID || id === virtualPath || id.endsWith(".virtual-modular-container.js") || id.includes("virtual:modular-container");
+    },
+    load(id) {
+      const virtualPath = import_node_path2.default.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      if (id === RESOLVED_VIRTUAL_MODULE_ID || id === virtualPath || id.endsWith(".virtual-modular-container.js") || id.includes("virtual:modular-container")) {
+        const cleanPath = modulesPath.replace(/\/$/, "");
+        if (isWebpackLike) {
+          const absModulesPath = import_node_path2.default.resolve(projectRoot, cleanPath).replace(/\\/g, "/");
+          return `
+            import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+            const reqContext = require.context('${absModulesPath}', true, /\\/index\\.[jt]sx?$/);
+            export const modules = reqContext.keys().map((k) => {
+              const rawKey = k.replace(/^\\.\\//, '').replace(/\\/index\\.[jt]sx?$/, '');
+              return { key: '/' + rawKey, module: reqContext(k) };
+            });
+
+            let compiledGraph = null;
+
+            export async function createModularContainer(modularContainer = {}) {
+              if (!compiledGraph) {
+                compiledGraph = compileModuleGraph(modules);
+              }
+              await instantiateModuleContainer(compiledGraph, modularContainer);
+              return modularContainer;
+            }
+          `;
+        }
+        return `
+          import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+          const viteModules = import.meta.glob(['/${cleanPath}/**/index.{ts,tsx}', './${cleanPath}/**/index.{ts,tsx}'], { eager: true });
+          export const modules = Object.entries(viteModules).map(([k, iocModule]) => {
+            const rawKey = k.replace(/^(\\.\\/|\\/)+/, '').replace('${cleanPath}', '').replace(/^(\\.\\/|\\/)+/, '').replace(/\\/index\\.(ts|tsx)$/, '');
+            return { key: '/' + rawKey, module: iocModule };
+          });
+
+          let compiledGraph = null;
+
+          export async function createModularContainer(modularContainer = {}) {
+            if (!compiledGraph) {
+              compiledGraph = compileModuleGraph(modules);
+            }
+            await instantiateModuleContainer(compiledGraph, modularContainer);
+            return modularContainer;
+          }
+        `;
+      }
+    },
+    async buildStart() {
+      await generateTypeDefinitions(projectRoot, typeFileOutput, modulesPath);
+    }
+  };
+});
+var vitePlugin = PathIocPlugin.vite;
+var webpackPlugin = PathIocPlugin.webpack;
+var rollupPlugin = PathIocPlugin.rollup;
+var rspackPlugin = PathIocPlugin.rspack;
+var esbuildPlugin = PathIocPlugin.esbuild;
+var rolldownPlugin = PathIocPlugin.rolldown;
+var pathIoc = PathIocPlugin;
+var index_default = pathIoc;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PathIocPlugin,
+  esbuildPlugin,
+  rolldownPlugin,
+  rollupPlugin,
+  rspackPlugin,
+  vitePlugin,
+  webpackPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+import * as rolldown from 'rolldown';
+import * as esbuild from 'esbuild';
+import * as rollup from 'rollup';
+import * as webpack from 'webpack';
+import * as unplugin from 'unplugin';
+import { Plugin } from 'vite';
+
+interface PathIocPluginOptions {
+    /**
+     * 生成的类型文件的输出目录
+     * @default 'types'
+     */
+    typeFileOutput?: string;
+    /**
+     * 模块扫描的根目录，相对于项目根目录
+     * @default 'src/modules'
+     */
+    modulesPath?: string;
+}
+declare const PathIocPlugin: unplugin.UnpluginInstance<PathIocPluginOptions | undefined, boolean>;
+type PathIocVitePlugin = Pick<Plugin, "name" | "enforce"> & {
+    buildStart?: () => Promise<void> | void;
+    resolveId?: (source: string, importer?: string, options?: any) => Promise<string | null | undefined | false | {
+        id: string;
+    }> | string | null | undefined | false | {
+        id: string;
+    };
+    load?: (id: string, options?: any) => Promise<string | null | undefined | {
+        code: string;
+    }> | string | null | undefined | {
+        code: string;
+    };
+    transform?: (code: string, id: string) => Promise<string | null | undefined | {
+        code: string;
+    }> | string | null | undefined | {
+        code: string;
+    };
+};
+type PathIocPluginType = Omit<typeof PathIocPlugin, "vite"> & {
+    vite: (options?: PathIocPluginOptions) => PathIocVitePlugin;
+};
+declare const vitePlugin: (options?: PathIocPluginOptions) => PathIocVitePlugin;
+declare const webpackPlugin: (options?: PathIocPluginOptions | undefined) => webpack.WebpackPluginInstance;
+declare const rollupPlugin: (options?: PathIocPluginOptions | undefined) => rollup.Plugin<any> | rollup.Plugin<any>[];
+declare const rspackPlugin: (options?: PathIocPluginOptions | undefined) => unplugin.RspackPluginInstance;
+declare const esbuildPlugin: (options?: PathIocPluginOptions | undefined) => esbuild.Plugin;
+declare const rolldownPlugin: (options?: PathIocPluginOptions | undefined) => rolldown.Plugin<any> | rolldown.Plugin<any>[];
+declare const pathIoc: PathIocPluginType;
+
+export { PathIocPlugin, type PathIocPluginOptions, type PathIocPluginType, type PathIocVitePlugin, pathIoc as default, esbuildPlugin, rolldownPlugin, rollupPlugin, rspackPlugin, vitePlugin, webpackPlugin };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import * as rolldown from 'rolldown';
+import * as esbuild from 'esbuild';
+import * as rollup from 'rollup';
+import * as webpack from 'webpack';
+import * as unplugin from 'unplugin';
+import { Plugin } from 'vite';
+
+interface PathIocPluginOptions {
+    /**
+     * 生成的类型文件的输出目录
+     * @default 'types'
+     */
+    typeFileOutput?: string;
+    /**
+     * 模块扫描的根目录，相对于项目根目录
+     * @default 'src/modules'
+     */
+    modulesPath?: string;
+}
+declare const PathIocPlugin: unplugin.UnpluginInstance<PathIocPluginOptions | undefined, boolean>;
+type PathIocVitePlugin = Pick<Plugin, "name" | "enforce"> & {
+    buildStart?: () => Promise<void> | void;
+    resolveId?: (source: string, importer?: string, options?: any) => Promise<string | null | undefined | false | {
+        id: string;
+    }> | string | null | undefined | false | {
+        id: string;
+    };
+    load?: (id: string, options?: any) => Promise<string | null | undefined | {
+        code: string;
+    }> | string | null | undefined | {
+        code: string;
+    };
+    transform?: (code: string, id: string) => Promise<string | null | undefined | {
+        code: string;
+    }> | string | null | undefined | {
+        code: string;
+    };
+};
+type PathIocPluginType = Omit<typeof PathIocPlugin, "vite"> & {
+    vite: (options?: PathIocPluginOptions) => PathIocVitePlugin;
+};
+declare const vitePlugin: (options?: PathIocPluginOptions) => PathIocVitePlugin;
+declare const webpackPlugin: (options?: PathIocPluginOptions | undefined) => webpack.WebpackPluginInstance;
+declare const rollupPlugin: (options?: PathIocPluginOptions | undefined) => rollup.Plugin<any> | rollup.Plugin<any>[];
+declare const rspackPlugin: (options?: PathIocPluginOptions | undefined) => unplugin.RspackPluginInstance;
+declare const esbuildPlugin: (options?: PathIocPluginOptions | undefined) => esbuild.Plugin;
+declare const rolldownPlugin: (options?: PathIocPluginOptions | undefined) => rolldown.Plugin<any> | rolldown.Plugin<any>[];
+declare const pathIoc: PathIocPluginType;
+
+export { PathIocPlugin, type PathIocPluginOptions, type PathIocPluginType, type PathIocVitePlugin, pathIoc as default, esbuildPlugin, rolldownPlugin, rollupPlugin, rspackPlugin, vitePlugin, webpackPlugin };

package/dist/index.js

@@ -0,0 +1,310 @@
+// src/index.ts
+import path2 from "path";
+import fsSync2 from "fs";
+import { createUnplugin } from "unplugin";
+
+// src/generator.ts
+import path from "path";
+import fs from "fs/promises";
+import fsSync from "fs";
+import { camelCase } from "lodash-es";
+import fg from "fast-glob";
+
+// src/utils.ts
+function createTrailingRunner(asyncFn) {
+  let isRunning = false;
+  let pendingArgs = null;
+  let pendingWaiters = [];
+  const startLoop = async (initialArgs) => {
+    isRunning = true;
+    let latestResult;
+    let currentArgs = initialArgs;
+    while (true) {
+      const argsToRun = currentArgs;
+      const currentWaiters = pendingWaiters;
+      pendingArgs = null;
+      pendingWaiters = [];
+      try {
+        latestResult = await asyncFn(...argsToRun);
+        currentWaiters.forEach((w) => w.resolve(latestResult));
+      } catch (err) {
+        currentWaiters.forEach((w) => w.reject(err));
+      }
+      if (pendingArgs !== null) {
+        currentArgs = pendingArgs;
+      } else {
+        break;
+      }
+    }
+    isRunning = false;
+    return latestResult;
+  };
+  return (...args) => {
+    if (!isRunning) {
+      return startLoop(args);
+    }
+    pendingArgs = args;
+    return new Promise((resolve, reject) => {
+      pendingWaiters.push({ resolve, reject });
+    });
+  };
+}
+
+// src/generator.ts
+var cachedFolderSet = null;
+function generateModuleMapContent(folders, rootDir, typeDir, modulesPathStr) {
+  if (folders.length === 0) {
+    return `// This file is generated by @path-ioc/unplugin, do not edit.
+
+declare global {
+  interface ModuleMap {
+    [key: string]: any;
+  }
+  interface ModularContainer {
+    [key: string]: any;
+  }
+}
+
+export {};
+`;
+  }
+  const dtsDir = path.resolve(rootDir, typeDir);
+  const modulesRoot = path.resolve(rootDir, modulesPathStr);
+  const moduleFolderMap = /* @__PURE__ */ new Map();
+  const shortNameFullNamesMap = /* @__PURE__ */ new Map();
+  folders.forEach((relDir) => {
+    const dirPath = path.resolve(rootDir, relDir);
+    let importRelPath = path.relative(dtsDir, dirPath).replace(/\\/g, "/");
+    if (!importRelPath.startsWith(".")) {
+      importRelPath = "./" + importRelPath;
+    }
+    const logicalPath = path.relative(modulesRoot, dirPath).replace(/\\/g, "/");
+    const folderName = logicalPath.split("/").pop();
+    if (!folderName) return;
+    const moduleName = folderName.charAt(0) + camelCase(folderName).slice(1);
+    const logicalDir = logicalPath.substring(0, logicalPath.lastIndexOf(folderName));
+    const moduleFullName = `/${logicalDir}${moduleName}`;
+    moduleFolderMap.set(moduleFullName, importRelPath);
+    moduleFolderMap.set(moduleName, importRelPath);
+    const fullNames = shortNameFullNamesMap.get(moduleName) || [];
+    fullNames.push(moduleFullName);
+    shortNameFullNamesMap.set(moduleName, fullNames);
+  });
+  for (const [shortName, fullNames] of shortNameFullNamesMap.entries()) {
+    if (fullNames.length > 1) {
+      moduleFolderMap.delete(shortName);
+    }
+  }
+  const entries = [];
+  const containerEntries = [];
+  for (const [key, relPath] of moduleFolderMap.entries()) {
+    entries.push(`    "${key}": typeof import("${relPath}/index");`);
+    containerEntries.push(`    "${key}": Awaited<ReturnType<typeof import("${relPath}/index")["main"]>>;`);
+  }
+  return `// This file is generated by @path-ioc/unplugin, do not edit.
+/// <reference types="@path-ioc/unplugin/virtual" />
+
+declare global {
+  interface ModuleMap {
+    [key: string]: any;
+${entries.join("\n")}
+  }
+  interface ModularContainer {
+    [key: string]: any;
+${containerEntries.join("\n")}
+  }
+}
+
+export {};
+`;
+}
+var doGenerateTypeDefinitions = async (rootDir, typeDir, modulesPathStr) => {
+  try {
+    const modulesRoot = path.resolve(rootDir, modulesPathStr);
+    const dotIgnorePath = path.resolve(rootDir, ".gitignore");
+    try {
+      const dotIgnoreContent = await fs.readFile(dotIgnorePath, "utf-8");
+      if (!dotIgnoreContent.includes("ignore.*")) {
+        await fs.appendFile(
+          dotIgnorePath,
+          `
+
+# @path-ioc/unplugin
+ignore.*
+`
+        );
+      }
+    } catch (e) {
+    }
+    const dtsDir = path.resolve(rootDir, typeDir);
+    await fs.mkdir(dtsDir, { recursive: true });
+    const dtsPath = path.resolve(dtsDir, "ignore.modular.d.ts");
+    const searchPattern = path.posix.join(modulesRoot.replace(/\\/g, "/"), "**/index.{ts,tsx}");
+    const files = await fg(searchPattern, { absolute: true });
+    const folders = files.map((f) => path.relative(rootDir, path.dirname(f)));
+    if (cachedFolderSet && cachedFolderSet.size === folders.length && fsSync.existsSync(dtsPath)) {
+      let isIdentical = true;
+      for (let i = 0; i < folders.length; i++) {
+        if (!cachedFolderSet.has(folders[i])) {
+          isIdentical = false;
+          break;
+        }
+      }
+      if (isIdentical) {
+        return;
+      }
+    }
+    cachedFolderSet = new Set(folders);
+    const content = generateModuleMapContent(folders, rootDir, typeDir, modulesPathStr);
+    await fs.writeFile(dtsPath, content, { flag: "w" });
+  } catch (e) {
+  }
+};
+var generateTypeDefinitions = createTrailingRunner(doGenerateTypeDefinitions);
+
+// src/index.ts
+var VIRTUAL_MODULE_ID = "virtual:modular-container";
+var RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+var PathIocPlugin = createUnplugin((options = {}, meta) => {
+  const { typeFileOutput = "types", modulesPath = "src/modules" } = options;
+  let projectRoot = process.cwd();
+  const isWebpackLike = meta.framework === "webpack" || meta.framework === "rspack";
+  return {
+    name: "unplugin-path-ioc",
+    enforce: "pre",
+    // Webpack / Vite 钩子获取根目录
+    vite: {
+      configResolved(config) {
+        if (config && typeof config === "object" && "root" in config && typeof config.root === "string") {
+          projectRoot = path2.resolve(config.root);
+        }
+      },
+      async handleHotUpdate(ctx) {
+        if (ctx && typeof ctx === "object" && "file" in ctx && typeof ctx.file === "string") {
+          const file = ctx.file;
+          if (file.endsWith(".d.ts") || file.includes("ignore.")) return;
+          const relativeModulesPath = path2.normalize(modulesPath);
+          if (file.includes(path2.join(projectRoot, relativeModulesPath))) {
+            await generateTypeDefinitions(projectRoot, typeFileOutput, modulesPath);
+          }
+        }
+      }
+    },
+    webpack(compiler) {
+      projectRoot = compiler.context;
+      const cleanPath = modulesPath.replace(/\/$/, "");
+      const virtualPath = path2.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      const absModulesPath = path2.resolve(projectRoot, cleanPath).replace(/\\/g, "/");
+      const virtualCode = `
+        import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+        const reqContext = require.context('${absModulesPath}', true, /\\/index\\.[jt]sx?$/);
+        export const modules = reqContext.keys().map((k) => {
+          const rawKey = k.replace(/^\\.\\//, '').replace(/\\/index\\.[jt]sx?$/, '');
+          return { key: '/' + rawKey, module: reqContext(k) };
+        });
+
+        let compiledGraph = null;
+
+        export async function createModularContainer(modularContainer = {}) {
+          if (!compiledGraph) {
+            compiledGraph = compileModuleGraph(modules);
+          }
+          await instantiateModuleContainer(compiledGraph, modularContainer);
+          return modularContainer;
+        }
+      `;
+      try {
+        fsSync2.mkdirSync(path2.dirname(virtualPath), { recursive: true });
+        fsSync2.writeFileSync(virtualPath, virtualCode, "utf-8");
+      } catch (e) {
+      }
+      if (compiler.webpack && compiler.webpack.NormalModuleReplacementPlugin) {
+        new compiler.webpack.NormalModuleReplacementPlugin(
+          /^virtual:modular-container$/,
+          virtualPath
+        ).apply(compiler);
+      }
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID || id.includes("virtual:modular-container")) {
+        if (isWebpackLike && projectRoot) {
+          return path2.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+        }
+        return RESOLVED_VIRTUAL_MODULE_ID;
+      }
+    },
+    loadInclude(id) {
+      const virtualPath = path2.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      return id === RESOLVED_VIRTUAL_MODULE_ID || id === virtualPath || id.endsWith(".virtual-modular-container.js") || id.includes("virtual:modular-container");
+    },
+    load(id) {
+      const virtualPath = path2.resolve(projectRoot, "node_modules/.virtual-modular-container.js");
+      if (id === RESOLVED_VIRTUAL_MODULE_ID || id === virtualPath || id.endsWith(".virtual-modular-container.js") || id.includes("virtual:modular-container")) {
+        const cleanPath = modulesPath.replace(/\/$/, "");
+        if (isWebpackLike) {
+          const absModulesPath = path2.resolve(projectRoot, cleanPath).replace(/\\/g, "/");
+          return `
+            import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+            const reqContext = require.context('${absModulesPath}', true, /\\/index\\.[jt]sx?$/);
+            export const modules = reqContext.keys().map((k) => {
+              const rawKey = k.replace(/^\\.\\//, '').replace(/\\/index\\.[jt]sx?$/, '');
+              return { key: '/' + rawKey, module: reqContext(k) };
+            });
+
+            let compiledGraph = null;
+
+            export async function createModularContainer(modularContainer = {}) {
+              if (!compiledGraph) {
+                compiledGraph = compileModuleGraph(modules);
+              }
+              await instantiateModuleContainer(compiledGraph, modularContainer);
+              return modularContainer;
+            }
+          `;
+        }
+        return `
+          import { compileModuleGraph, instantiateModuleContainer } from '@path-ioc/core';
+
+          const viteModules = import.meta.glob(['/${cleanPath}/**/index.{ts,tsx}', './${cleanPath}/**/index.{ts,tsx}'], { eager: true });
+          export const modules = Object.entries(viteModules).map(([k, iocModule]) => {
+            const rawKey = k.replace(/^(\\.\\/|\\/)+/, '').replace('${cleanPath}', '').replace(/^(\\.\\/|\\/)+/, '').replace(/\\/index\\.(ts|tsx)$/, '');
+            return { key: '/' + rawKey, module: iocModule };
+          });
+
+          let compiledGraph = null;
+
+          export async function createModularContainer(modularContainer = {}) {
+            if (!compiledGraph) {
+              compiledGraph = compileModuleGraph(modules);
+            }
+            await instantiateModuleContainer(compiledGraph, modularContainer);
+            return modularContainer;
+          }
+        `;
+      }
+    },
+    async buildStart() {
+      await generateTypeDefinitions(projectRoot, typeFileOutput, modulesPath);
+    }
+  };
+});
+var vitePlugin = PathIocPlugin.vite;
+var webpackPlugin = PathIocPlugin.webpack;
+var rollupPlugin = PathIocPlugin.rollup;
+var rspackPlugin = PathIocPlugin.rspack;
+var esbuildPlugin = PathIocPlugin.esbuild;
+var rolldownPlugin = PathIocPlugin.rolldown;
+var pathIoc = PathIocPlugin;
+var index_default = pathIoc;
+export {
+  PathIocPlugin,
+  index_default as default,
+  esbuildPlugin,
+  rolldownPlugin,
+  rollupPlugin,
+  rspackPlugin,
+  vitePlugin,
+  webpackPlugin
+};

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@path-ioc/unplugin",
+  "version": "0.1.1",
+  "description": "Universal dev plugin for Path-IoC generating virtual modular container and TypeScript typings",
+  "keywords": [
+    "unplugin",
+    "vite-plugin",
+    "webpack-plugin",
+    "rspack-plugin",
+    "rollup-plugin",
+    "ioc",
+    "dependency-injection",
+    "code-generation"
+  ],
+  "homepage": "https://path-ioc.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/path-ioc/path-ioc.git",
+    "directory": "packages/unplugin"
+  },
+  "bugs": {
+    "url": "https://github.com/path-ioc/path-ioc/issues"
+  },
+  "author": "Lian HanLin",
+  "license": "MIT",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./vite": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./webpack": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./rspack": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./rollup": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./esbuild": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./rolldown": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./virtual": {
+      "types": "./virtual.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "virtual.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "lodash-es": "^4.17.21",
+    "unplugin": "^3.3.0",
+    "webpack-virtual-modules": "^0.6.2"
+  },
+  "peerDependencies": {
+    "vite": "*",
+    "webpack": "*",
+    "esbuild": "*",
+    "rollup": "*",
+    "rspack": "*",
+    "rolldown": "*"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    },
+    "rollup": {
+      "optional": true
+    },
+    "rspack": {
+      "optional": true
+    },
+    "rolldown": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.5",
+    "vite": "^8.2.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  }
+}

package/virtual.d.ts

@@ -0,0 +1,6 @@
+declare module "virtual:modular-container" {
+  export const modules: Array<{ key: string; module: any }>;
+  export function createModularContainer(
+    modularContainer?: ModularContainer
+  ): Promise<ModularContainer>;
+}