@hzab/vite-config 0.0.2-alpha.0 → 0.0.3-alpha.1

package/src/plugins/hash-dir-name.ts

@@ -0,0 +1,212 @@
+/**
+ * Hash 子目录名模式串 → 实际目录名，以及清理历史目录用的匹配器。
+ *
+ * 与 `@hzab/webpack-config` 的 `hashDirName` 共用同一套 token 语义（两个包各自实现，不互相依赖）：
+ * token 展开为值，其余字符（含 `-`）原样保留。
+ * - `hash`      12 位 commit（非 git 仓库回退 `local`）
+ * - `timestamp` 毫秒时间戳（`Date.now()`）
+ * - `YYYY` / `MM` / `DD` / `HH` / `mm` / `ss` / `SSS`  本地时区格式化时间
+ *
+ * 例（now = 2026-09-17 15:30:52.123，commit = a1b2c3d4e5f6）：
+ * - `hash-timestamp`                   -> `a1b2c3d4e5f6-1789630252123`
+ * - `hash-timestamp-YYYYMMDDHHmmssSSS` -> `a1b2c3d4e5f6-1789630252123-20260917153052123`
+ * - `hash-YYYYMMDDHHmmssSSS`           -> `a1b2c3d4e5f6-20260917153052123`
+ *
+ * 约束：模式串必须至少含一个时间 token（`timestamp` 或日期 token）。只含 `hash` 的目录名会让
+ * 同一 commit 的多次构建互相覆盖，因此被拒绝。
+ *
+ * 只做纯字符串计算（无 I/O），命名与清理排序共用同一套 token 定义。
+ */
+
+/** token 交替顺序：长 token 在前，避免被短 token 抢先切分。每次取新实例，避免共享 `lastIndex`。 */
+const tokenPattern = (): RegExp => /YYYY|SSS|MM|DD|HH|mm|ss|timestamp|hash/g;
+
+const DATE_TOKEN_WIDTH = { YYYY: 4, MM: 2, DD: 2, HH: 2, mm: 2, ss: 2, SSS: 3 } as const;
+
+type DateToken = keyof typeof DATE_TOKEN_WIDTH;
+
+/** 日期 token → `Date` 字段 */
+const DATE_TOKEN_SLOT = {
+  YYYY: "year",
+  MM: "month",
+  DD: "day",
+  HH: "hour",
+  mm: "minute",
+  ss: "second",
+  SSS: "millisecond",
+} as const satisfies Record<DateToken, string>;
+
+type DateSlot = (typeof DATE_TOKEN_SLOT)[DateToken];
+
+const TIME_TOKENS = ["timestamp", "YYYY", "MM", "DD", "HH", "mm", "ss", "SSS"] as const;
+
+const AVAILABLE_TOKENS = ["hash", ...TIME_TOKENS];
+
+/** 默认模式串：与历史默认目录名 `{commit}-{Date.now()}` 等价 */
+export const DEFAULT_HASH_DIR_NAME_PATTERN = "hash-timestamp";
+
+/** 目录名不允许出现的字符（路径分隔符、Windows 保留字符） */
+const ILLEGAL_DIR_CHAR_PATTERN = /[\\/:*?"<>|]/;
+
+const pad = (value: number, length = 2): string => String(value).padStart(length, "0");
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function assertPatternValue(pattern: string): void {
+  if (pattern.trim() === "") {
+    throw new Error("[vite-config] hashDirName must be a non-empty string.");
+  }
+}
+
+/** 展开后的目录名必须留在 deployRoot 之下（模式串不能借字面文本跳出产物根目录） */
+function assertSafeDirName(dirName: string, pattern: string): void {
+  const unsafe =
+    ILLEGAL_DIR_CHAR_PATTERN.test(dirName) ||
+    dirName.includes("..") ||
+    dirName.startsWith(".") ||
+    dirName.endsWith(".") ||
+    dirName !== dirName.trim();
+
+  if (unsafe) {
+    throw new Error(
+      `[vite-config] hashDirName "${pattern}" resolves to unsafe directory name "${dirName}".`,
+    );
+  }
+}
+
+/**
+ * 把目录名模式串展开为目录名。
+ * `timestamp` 与日期 token 共用同一个 `now`，保证描述同一时刻。
+ */
+export function expandHashDirName(options: {
+  pattern: string;
+  commitHash: string;
+  now?: number;
+}): string {
+  const { pattern, commitHash, now = Date.now() } = options;
+  assertPatternValue(pattern);
+
+  const date = new Date(now);
+  const values: Record<string, string> = {
+    hash: commitHash || "local",
+    timestamp: String(now),
+    YYYY: String(date.getFullYear()),
+    MM: pad(date.getMonth() + 1),
+    DD: pad(date.getDate()),
+    HH: pad(date.getHours()),
+    mm: pad(date.getMinutes()),
+    ss: pad(date.getSeconds()),
+    SSS: pad(date.getMilliseconds(), 3),
+  };
+
+  let timeMatched = false;
+  // 单次 replace：替换结果不会被二次扫描，避免 commit / 时间戳里的字符被再次展开
+  const dirName = pattern.replace(tokenPattern(), (token) => {
+    if ((TIME_TOKENS as readonly string[]).includes(token)) timeMatched = true;
+    return values[token] ?? token;
+  });
+
+  // 只含 commit（如 "hash"）的目录名会让同一 commit 的多次构建互相覆盖，直接拒绝
+  if (!timeMatched) {
+    throw new Error(
+      `[vite-config] hashDirName "${pattern}" must contain a time token; available tokens: ${AVAILABLE_TOKENS.join(", ")}.`,
+    );
+  }
+
+  assertSafeDirName(dirName, pattern);
+
+  return dirName;
+}
+
+/**
+ * 模式串是否含可排序的时间 token（`timestamp` 或日期 token）。
+ * 清理器按目录名里的时间判断新旧，没有时间 token 就无从排序，必须让调用方提前报错。
+ */
+export function hasTimeToken(pattern: string): boolean {
+  if (pattern.trim() === "") return false;
+
+  return [...pattern.matchAll(tokenPattern())].some((match) =>
+    (TIME_TOKENS as readonly string[]).includes(match[0]),
+  );
+}
+
+/**
+ * 由模式串编译出的历史目录匹配器：只认本模式串生成的目录名，并给出可排序时间戳。
+ */
+export interface HashDirNameMatcher {
+  regex: RegExp;
+  /** 目录名 → 时间戳（毫秒）；目录名不匹配本模式串时返回 `undefined` */
+  parseTimestamp(name: string): number | undefined;
+}
+
+/**
+ * 编译模式串：字面文本转义为 `^...$`，token 转为捕获组。
+ * - `timestamp` 存在时直接取其毫秒值排序；
+ * - 否则按日期 token 回推本地时间（缺省字段为 1970-01-01 00:00:00.000）。
+ * 模式串必须含时间 token（由 `expandHashDirName` 保证），故时间戳总是可解析。
+ */
+export function compileHashDirNameMatcher(pattern: string): HashDirNameMatcher {
+  assertPatternValue(pattern);
+
+  let source = "^";
+  let cursor = 0;
+  let groupIndex = 1;
+  let epochGroup = -1;
+  const dateTokens: DateToken[] = [];
+
+  for (const match of pattern.matchAll(tokenPattern())) {
+    const index = match.index;
+    source += escapeRegExp(pattern.slice(cursor, index));
+
+    const token = match[0];
+    if (token === "hash") {
+      source += "(?:[0-9a-f]{12}|local)";
+    } else if (token === "timestamp") {
+      source += "(\\d{1,15})";
+      epochGroup = groupIndex;
+      groupIndex += 1;
+    } else {
+      const width = DATE_TOKEN_WIDTH[token as DateToken];
+      source += `(\\d{${width}})`;
+      dateTokens.push(token as DateToken);
+      groupIndex += 1;
+    }
+
+    cursor = index + token.length;
+  }
+  source += `${escapeRegExp(pattern.slice(cursor))}$`;
+
+  const regex = new RegExp(source);
+
+  return {
+    regex,
+    parseTimestamp(name: string): number | undefined {
+      const matched = regex.exec(name);
+      if (!matched) return undefined;
+
+      if (epochGroup > 0) {
+        const epoch = matched[epochGroup];
+        return epoch == null ? undefined : Number(epoch);
+      }
+      if (dateTokens.length === 0) return undefined;
+
+      const slots: Partial<Record<DateSlot, number>> = {};
+      dateTokens.forEach((token, position) => {
+        const raw = matched[position + 1];
+        if (raw != null) slots[DATE_TOKEN_SLOT[token]] = Number(raw);
+      });
+
+      return new Date(
+        slots.year ?? 1970,
+        (slots.month ?? 1) - 1,
+        slots.day ?? 1,
+        slots.hour ?? 0,
+        slots.minute ?? 0,
+        slots.second ?? 0,
+        slots.millisecond ?? 0,
+      ).getTime();
+    },
+  };
+}

package/src/plugins/less-tilde.ts

@@ -1,44 +1,72 @@
-import type { LessOptions } from "../types.ts";
-
-/**
- * Less 插件：把 webpack 遗留的 `~pkg/...` 导入解析到 node_modules。
- *
- * Less 自身不认识 `~`（那是 webpack `less-loader` 的约定：从 node_modules 解析）；Vite 的
- * Less 预处理器也不处理 `~`，会回退到 Less 默认 FileManager 去查找 `node_modules/~pkg/...` 而失败。
- * 本插件注册一个 FileManager：仅当导入以 `~` 开头时拦截，去掉前缀后交给默认 FileManager 解析
- * （Vite 恒向 `less.render` 注入 `paths: ["node_modules"]`）。
- *
- * 第三方包（如 formily 系）自带 `@import "~antd/..."` 时尤其需要——消费方无法修改 node_modules。
- * @public
- */
-export function lessTildeResolutionPlugin() {
-  return {
-    install(less: any, pluginManager: any) {
-      class TildeFileManager extends less.FileManager {
-        supports(filename: string) {
-          return filename.startsWith("~");
-        }
-        loadFile(filename: string, currentDirectory: string, options: any, environment: any) {
-          // `~pkg/...` → `pkg/...`，让默认 FileManager 从 node_modules 解析
-          return super.loadFile(filename.slice(1), currentDirectory, options, environment);
-        }
-      }
-      pluginManager.addFileManager(new TildeFileManager());
-    },
-  };
-}
-
-/**
- * 组装 `css.preprocessorOptions.less`：映射 webpack `less-loader` 选项，
- * `less.resolveTilde: true` 时注入 `~` 解析插件（默认关闭）。
- * @public
- */
-export function buildLessOptions(less?: LessOptions) {
-  const resolveTilde = less?.resolveTilde === true;
-  return {
-    ...(less?.additionalData != null ? { additionalData: less.additionalData } : {}),
-    ...(less?.modifyVars != null ? { modifyVars: less.modifyVars } : {}),
-    ...(less?.javascriptEnabled != null ? { javascriptEnabled: less.javascriptEnabled } : {}),
-    ...(resolveTilde ? { plugins: [lessTildeResolutionPlugin()] } : {}),
-  };
-}
+import type { LessOptions } from "../types.ts";
+
+/**
+ * less 插件注入的 FileManager 实例表面类型。less@4 不自带 TS 类型，按实际使用的最小面声明。
+ */
+interface LessFileManagerInstance {
+  supports(filename: string): boolean;
+  loadFile(
+    filename: string,
+    currentDirectory: string,
+    options: unknown,
+    environment: unknown,
+  ): unknown;
+}
+
+/** less.js 传给插件 `install` 的 less 环境实例表面。 */
+interface LessPluginHost {
+  FileManager: new (...args: unknown[]) => LessFileManagerInstance;
+}
+
+/** less.js 插件管理器表面。 */
+interface LessPluginManager {
+  addFileManager(manager: LessFileManagerInstance): void;
+}
+
+/**
+ * Less 插件：把 webpack 遗留的 `~pkg/...` 导入解析到 node_modules。
+ *
+ * Less 自身不认识 `~`（那是 webpack `less-loader` 的约定：从 node_modules 解析）；Vite 的
+ * Less 预处理器也不处理 `~`，会回退到 Less 默认 FileManager 去查找 `node_modules/~pkg/...` 而失败。
+ * 本插件注册一个 FileManager：仅当导入以 `~` 开头时拦截，去掉前缀后交给默认 FileManager 解析
+ * （Vite 恒向 `less.render` 注入 `paths: ["node_modules"]`）。
+ *
+ * 第三方包（如 formily 系）自带 `@import "~antd/..."` 时尤其需要——消费方无法修改 node_modules。
+ * @public
+ */
+export function lessTildeResolutionPlugin() {
+  return {
+    install(less: LessPluginHost, pluginManager: LessPluginManager) {
+      class TildeFileManager extends less.FileManager {
+        override supports(filename: string) {
+          return filename.startsWith("~");
+        }
+        override loadFile(
+          filename: string,
+          currentDirectory: string,
+          options: unknown,
+          environment: unknown,
+        ) {
+          // `~pkg/...` → `pkg/...`，让默认 FileManager 从 node_modules 解析
+          return super.loadFile(filename.slice(1), currentDirectory, options, environment);
+        }
+      }
+      pluginManager.addFileManager(new TildeFileManager());
+    },
+  };
+}
+
+/**
+ * 组装 `css.preprocessorOptions.less`：映射 webpack `less-loader` 选项，
+ * `less.resolveTilde: true` 时注入 `~` 解析插件（默认关闭）。
+ * @public
+ */
+export function buildLessOptions(less?: LessOptions) {
+  const resolveTilde = less?.resolveTilde === true;
+  return {
+    ...(less?.additionalData != null ? { additionalData: less.additionalData } : {}),
+    ...(less?.modifyVars != null ? { modifyVars: less.modifyVars } : {}),
+    ...(less?.javascriptEnabled != null ? { javascriptEnabled: less.javascriptEnabled } : {}),
+    ...(resolveTilde ? { plugins: [lessTildeResolutionPlugin()] } : {}),
+  };
+}

package/src/plugins/lifecycle.ts

@@ -1,40 +1,40 @@
-import type { PluginOption } from "vite";
-
-/** @public */
-export interface LifecyclePluginOptions {
-  /** 构建开始（Vite `buildStart`）。仅同步。 */
-  onRun?: () => void;
-  /**
-   * 产物写盘成功之后（`writeBundle` sequential post）。
-   * 工厂中排在 Hash 根入口写入之后；Hash 写入失败不会调用。
-   */
-  onDone?: () => void | Promise<void>;
-}
-
-/**
- * 构建起止回调。`onDone` 使用 sequential post `writeBundle`，
- * 以便排在 Hash 部署等其它 post 写入之后。
- * @public
- */
-export function lifecyclePlugin(options: LifecyclePluginOptions = {}): PluginOption {
-  const { onRun, onDone } = options;
-
-  return {
-    name: "build-lifecycle",
-    enforce: "post",
-    buildStart() {
-      if (typeof onRun === "function") {
-        onRun();
-      }
-    },
-    writeBundle: {
-      sequential: true,
-      order: "post",
-      async handler() {
-        if (typeof onDone === "function") {
-          await onDone();
-        }
-      },
-    },
-  };
-}
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface LifecyclePluginOptions {
+  /** 构建开始（Vite `buildStart`）。仅同步。 */
+  onRun?: () => void;
+  /**
+   * 产物写盘成功之后（`writeBundle` sequential post）。
+   * 工厂中排在 Hash 根入口写入之后；Hash 写入失败不会调用。
+   */
+  onDone?: () => void | Promise<void>;
+}
+
+/**
+ * 构建起止回调。`onDone` 使用 sequential post `writeBundle`，
+ * 以便排在 Hash 部署等其它 post 写入之后。
+ * @public
+ */
+export function lifecyclePlugin(options: LifecyclePluginOptions = {}): PluginOption {
+  const { onRun, onDone } = options;
+
+  return {
+    name: "build-lifecycle",
+    enforce: "post",
+    buildStart() {
+      if (typeof onRun === "function") {
+        onRun();
+      }
+    },
+    writeBundle: {
+      sequential: true,
+      order: "post",
+      async handler() {
+        if (typeof onDone === "function") {
+          await onDone();
+        }
+      },
+    },
+  };
+}

package/src/plugins/public-assets.ts

@@ -1,28 +1,28 @@
-import { copyPlugin } from "./copy.ts";
-
-import type { PluginOption } from "vite";
-
-/** @public */
-export interface PublicAssetsPluginOptions {
-  /**
-   * 源目录，相对项目 root。
-   * @defaultValue "public"
-   */
-  dir?: string;
-}
-
-/**
- * 将 `public/**` 复制到产物 `public/` 子目录（保留目录结构），替代 Vite 默认 publicDir 根目录散落。
- * @public
- */
-export function publicAssetsPlugin(options: PublicAssetsPluginOptions = {}): PluginOption {
-  const { dir = "public" } = options;
-  return copyPlugin({
-    targets: [
-      {
-        src: `${dir}/**/*`,
-        dest: ".",
-      },
-    ],
-  });
-}
+import { copyPlugin } from "./copy.ts";
+
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface PublicAssetsPluginOptions {
+  /**
+   * 源目录，相对项目 root。
+   * @defaultValue "public"
+   */
+  dir?: string;
+}
+
+/**
+ * 将 `public/**` 复制到产物 `public/` 子目录（保留目录结构），替代 Vite 默认 publicDir 根目录散落。
+ * @public
+ */
+export function publicAssetsPlugin(options: PublicAssetsPluginOptions = {}): PluginOption {
+  const { dir = "public" } = options;
+  return copyPlugin({
+    targets: [
+      {
+        src: `${dir}/**/*`,
+        dest: ".",
+      },
+    ],
+  });
+}

package/src/plugins/public-config.ts

@@ -1,34 +1,34 @@
-import { copyPlugin } from "./copy.ts";
-
-import type { PluginOption } from "vite";
-
-/** @public */
-export interface PublicConfigPluginOptions {
-  /** 源 glob，如 `config/public-config/development/*` */
-  sourceGlob: string;
-  /**
-   * 产物目标目录（可由消费方覆盖）。
-   * @defaultValue "config"（站点根 `/config/`）
-   * @example "public/config"
-   */
-  dest?: string;
-}
-
-/**
- * 将运行时 public-config 复制到产物目录（默认 `config/`，配合 `window.globalConfig`）。
- * @public
- */
-export function publicConfigPlugin(options: PublicConfigPluginOptions): PluginOption {
-  const { sourceGlob, dest = "config" } = options;
-  return copyPlugin({
-    targets: [
-      {
-        src: sourceGlob,
-        dest,
-        rename: {
-          stripBase: true,
-        },
-      },
-    ],
-  });
-}
+import { copyPlugin } from "./copy.ts";
+
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface PublicConfigPluginOptions {
+  /** 源 glob，如 `config/public-config/development/*` */
+  sourceGlob: string;
+  /**
+   * 产物目标目录（可由消费方覆盖）。
+   * @defaultValue "config"（站点根 `/config/`）
+   * @example "public/config"
+   */
+  dest?: string;
+}
+
+/**
+ * 将运行时 public-config 复制到产物目录（默认 `config/`，配合 `window.globalConfig`）。
+ * @public
+ */
+export function publicConfigPlugin(options: PublicConfigPluginOptions): PluginOption {
+  const { sourceGlob, dest = "config" } = options;
+  return copyPlugin({
+    targets: [
+      {
+        src: sourceGlob,
+        dest,
+        rename: {
+          stripBase: true,
+        },
+      },
+    ],
+  });
+}

package/src/plugins/react-compiler.ts

@@ -1,32 +1,32 @@
-import babel from "@rolldown/plugin-babel";
-import { reactCompilerPreset } from "@vitejs/plugin-react";
-
-import type { ReactCompilerMode } from "../types.ts";
-import type { PluginOption } from "vite";
-
-/** @public */
-export interface ReactCompilerPluginOptions {
-  command: string;
-  /**
-   * - `true`：始终启用
-   * - `"build-only"`：仅 build，且 `REACT_COMPILER=false` 可关
-   * - `false`：关闭
-   */
-  mode?: ReactCompilerMode;
-}
-
-/**
- * React Compiler（babel preset）。默认仅生产构建启用。
- * @public
- */
-export function reactCompilerPlugin(options: ReactCompilerPluginOptions): PluginOption[] {
-  const { command, mode = "build-only" } = options;
-  if (mode === false) return [];
-
-  const isBuild = command === "build";
-  const enabled = mode === true ? true : isBuild && process.env.REACT_COMPILER !== "false";
-
-  if (!enabled) return [];
-
-  return [babel({ presets: [reactCompilerPreset()] })];
-}
+import babel from "@rolldown/plugin-babel";
+import { reactCompilerPreset } from "@vitejs/plugin-react";
+
+import type { ReactCompilerMode } from "../types.ts";
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface ReactCompilerPluginOptions {
+  command: string;
+  /**
+   * - `true`：始终启用
+   * - `"build-only"`：仅 build，且 `REACT_COMPILER=false` 可关
+   * - `false`：关闭
+   */
+  mode?: ReactCompilerMode;
+}
+
+/**
+ * React Compiler（babel preset）。默认仅生产构建启用。
+ * @public
+ */
+export function reactCompilerPlugin(options: ReactCompilerPluginOptions): PluginOption[] {
+  const { command, mode = "build-only" } = options;
+  if (mode === false) return [];
+
+  const isBuild = command === "build";
+  const enabled = mode === true ? true : isBuild && process.env.REACT_COMPILER !== "false";
+
+  if (!enabled) return [];
+
+  return [babel({ presets: [reactCompilerPreset()] })];
+}

package/src/plugins/relative-base.ts

@@ -1,20 +1,20 @@
-import type { PluginOption } from "vite";
-
-/**
- * hash 部署场景下，把资源路径与 `import.meta.env.BASE_URL` 改写成相对部署目录。
- * @public
- */
-export function relativeBasePlugin(deployPath: string = "./"): PluginOption {
-  return {
-    name: "relative-base",
-    transformIndexHtml(html: string) {
-      return html
-        .replace(/href="\.?\/assets\//g, `href="${deployPath}assets/`)
-        .replace(/src="\.?\/assets\//g, `src="${deployPath}assets/`);
-    },
-    transform(code: string, id: string) {
-      if (id.includes("node_modules")) return null;
-      return code.replace(/import\.meta\.env\.BASE_URL/g, `'${deployPath}'`);
-    },
-  };
-}
+import type { PluginOption } from "vite";
+
+/**
+ * hash 部署场景下，把资源路径与 `import.meta.env.BASE_URL` 改写成相对部署目录。
+ * @public
+ */
+export function relativeBasePlugin(deployPath: string = "./"): PluginOption {
+  return {
+    name: "relative-base",
+    transformIndexHtml(html: string) {
+      return html
+        .replace(/href="\.?\/assets\//g, `href="${deployPath}assets/`)
+        .replace(/src="\.?\/assets\//g, `src="${deployPath}assets/`);
+    },
+    transform(code: string, id: string) {
+      if (id.includes("node_modules")) return null;
+      return code.replace(/import\.meta\.env\.BASE_URL/g, `'${deployPath}'`);
+    },
+  };
+}