@hyacine/helper 0.0.1

package/src/getInjectPointSelector.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { getInjectPointSelector } from "./getInjectPointSelector";
+
+describe("getInjectPointSelector", () => {
+  test("应该返回正确的选择器", () => {
+    const injectPoints = {
+      footer: "#footer",
+      sidebar: "#sidebar",
+      header: ".header-container",
+      "custom-point": "[data-custom]",
+    };
+
+    expect(getInjectPointSelector("footer", injectPoints)).toBe("#footer");
+    expect(getInjectPointSelector("sidebar", injectPoints)).toBe("#sidebar");
+    expect(getInjectPointSelector("header", injectPoints)).toBe(".header-container");
+    expect(getInjectPointSelector("custom-point", injectPoints)).toBe("[data-custom]");
+  });
+
+  test("当 injectPoint 不存在时应该抛出错误", () => {
+    const injectPoints = {
+      footer: "#footer",
+      sidebar: "#sidebar",
+    };
+
+    expect(() => {
+      getInjectPointSelector("nonexistent", injectPoints);
+    }).toThrow(/未找到 injectPoint "nonexistent" 对应的选择器/);
+
+    expect(() => {
+      getInjectPointSelector("header", injectPoints);
+    }).toThrow(/未找到 injectPoint "header" 对应的选择器/);
+  });
+
+  test("当映射表无效时应该抛出错误", () => {
+    expect(() => {
+      // @ts-expect-error: 故意传入 null 以测试错误处理
+      getInjectPointSelector("footer", null);
+    }).toThrow(/injectPoints 映射表无效/);
+
+    expect(() => {
+      // @ts-expect-error: 故意传入 undefined 以测试错误处理
+      getInjectPointSelector("footer", undefined);
+    }).toThrow(/injectPoints 映射表无效/);
+  });
+
+  test("当选择器值为空字符串时应该抛出错误", () => {
+    const injectPoints = {
+      footer: "",
+      sidebar: "   ",
+    };
+
+    expect(() => {
+      getInjectPointSelector("footer", injectPoints);
+    }).toThrow(/injectPoint "footer" 对应的选择器无效/);
+
+    expect(() => {
+      getInjectPointSelector("sidebar", injectPoints);
+    }).toThrow(/injectPoint "sidebar" 对应的选择器无效/);
+  });
+
+  test("错误消息应该包含可用的注入点列表", () => {
+    const injectPoints = {
+      footer: "#footer",
+      sidebar: "#sidebar",
+      header: ".header",
+    };
+
+    try {
+      getInjectPointSelector("nonexistent", injectPoints);
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      const message = (error as Error).message;
+      expect(message).toContain("footer");
+      expect(message).toContain("sidebar");
+      expect(message).toContain("header");
+    }
+  });
+
+  test("应该处理复杂的选择器", () => {
+    const injectPoints = {
+      complex: "div.container > .item:first-child",
+      attribute: '[data-inject="point"]',
+      pseudo: ".element::before",
+    };
+
+    expect(getInjectPointSelector("complex", injectPoints)).toBe(
+      "div.container > .item:first-child",
+    );
+    expect(getInjectPointSelector("attribute", injectPoints)).toBe('[data-inject="point"]');
+    expect(getInjectPointSelector("pseudo", injectPoints)).toBe(".element::before");
+  });
+
+  test("应该处理包含特殊字符的 injectPoint 键", () => {
+    const injectPoints = {
+      "post-footer": "#post-footer",
+      "footer-status": ".footer-status",
+      "segments-sticky": "[data-segments-sticky]",
+    };
+
+    expect(getInjectPointSelector("post-footer", injectPoints)).toBe("#post-footer");
+    expect(getInjectPointSelector("footer-status", injectPoints)).toBe(".footer-status");
+    expect(getInjectPointSelector("segments-sticky", injectPoints)).toBe("[data-segments-sticky]");
+  });
+});

package/src/getInjectPointSelector.ts

@@ -0,0 +1,50 @@
+/**
+ * 根据 injectPoint 获取对应的 querySelector 选择器
+ * 该函数会自动读取配置文件中的 injectPoints 作为映射表
+ *
+ * @param injectPoint - 注入点名称
+ * @param injectPointsMap - injectPoints 映射表（通常来自配置文件）
+ * @returns 对应的 querySelector 选择器
+ * @throws {Error} 如果映射表中不包含该 injectPoint
+ *
+ * @example
+ * ```ts
+ * import { getInjectPointSelector } from './helper/getInjectPointSelector';
+ * import config from '../path/to/config';
+ *
+ * try {
+ *   const selector = getInjectPointSelector('footer', config.injectPoints);
+ *   console.log(selector); // "#footer"
+ * } catch (error) {
+ *   console.error(error.message);
+ * }
+ * ```
+ */
+export function getInjectPointSelector(
+  injectPoint: string,
+  injectPointsMap: Record<string, string>,
+): string {
+  if (!injectPointsMap || typeof injectPointsMap !== "object") {
+    throw new Error(
+      `[hyacine-plugin] injectPoints 映射表无效。收到的类型: ${typeof injectPointsMap}`,
+    );
+  }
+
+  const selector = injectPointsMap[injectPoint];
+
+  if (selector === undefined || selector === null) {
+    const availablePoints = Object.keys(injectPointsMap).join(", ");
+    throw new Error(
+      `[hyacine-plugin] 未找到 injectPoint "${injectPoint}" 对应的选择器。` +
+        `\n可用的注入点有: ${availablePoints || "(无)"}`,
+    );
+  }
+
+  if (typeof selector !== "string" || selector.trim() === "") {
+    throw new Error(
+      `[hyacine-plugin] injectPoint "${injectPoint}" 对应的选择器无效: ${JSON.stringify(selector)}`,
+    );
+  }
+
+  return selector;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./generateTempFile";
+export * from "./getInjectPointSelector";
+export * from "./integration-utils";

package/src/inject-point.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+function teardownInjectPoints() {
+  delete globalThis.__HYACINE_INJECT_POINTS__;
+}
+
+// 导入需要测试的函数
+import { getInjectPointSelector } from "./inject-point";
+
+describe("getInjectPointSelector", () => {
+  beforeEach(() => {
+    // 设置全局注入点映射表
+    globalThis.__HYACINE_INJECT_POINTS__ = {
+      footer: "#footer",
+      sidebar: "#sidebar",
+      header: ".header-container",
+      "custom-point": "[data-custom]",
+    };
+  });
+
+  afterEach(() => {
+    teardownInjectPoints();
+  });
+
+  test("应该返回正确的选择器", () => {
+    expect(getInjectPointSelector("footer")).toBe("#footer");
+    expect(getInjectPointSelector("sidebar")).toBe("#sidebar");
+    expect(getInjectPointSelector("header")).toBe(".header-container");
+    expect(getInjectPointSelector("custom-point")).toBe("[data-custom]");
+  });
+
+  test("当 injectPoint 不存在时应该抛出错误", () => {
+    expect(() => {
+      getInjectPointSelector("nonexistent");
+    }).toThrow(/未找到 injectPoint "nonexistent" 对应的选择器/);
+  });
+
+  test("当映射表未初始化时应该抛出错误", () => {
+    delete globalThis.__HYACINE_INJECT_POINTS__;
+
+    expect(() => {
+      getInjectPointSelector("footer");
+    }).toThrow(/注入点映射表未初始化/);
+  });
+
+  test("当选择器值为空字符串时应该抛出错误", () => {
+    globalThis.__HYACINE_INJECT_POINTS__ = {
+      footer: "",
+      sidebar: "   ",
+    };
+
+    expect(() => {
+      getInjectPointSelector("footer");
+    }).toThrow(/injectPoint "footer" 对应的选择器无效/);
+
+    expect(() => {
+      getInjectPointSelector("sidebar");
+    }).toThrow(/injectPoint "sidebar" 对应的选择器无效/);
+  });
+});

package/src/inject-point.ts

@@ -0,0 +1,47 @@
+/**
+ * Inject Point Selector API
+ *
+ * This module provides utilities for retrieving CSS selectors for inject points.
+ */
+
+// 扩展 globalThis 类型以包含注入点映射表
+declare global {
+  // biome-ignore lint: Using var for global augmentation
+  var __HYACINE_INJECT_POINTS__: Record<string, string> | undefined;
+}
+
+/**
+ * 获取注入点对应的 CSS 选择器
+ *
+ * Note: 此函数依赖于全局注入点映射表
+ * 该映射表由插件系统在运行时初始化
+ *
+ * @param injectPoint - 注入点名称
+ * @returns CSS 选择器字符串
+ * @throws {Error} 如果映射表中不包含该 injectPoint
+ */
+export function getInjectPointSelector(injectPoint: string): string {
+  const injectPointsMap = globalThis.__HYACINE_INJECT_POINTS__;
+
+  if (!injectPointsMap || typeof injectPointsMap !== "object") {
+    throw new Error(`[hyacine-plugin] 注入点映射表未初始化。请确保插件系统已正确初始化。`);
+  }
+
+  const selector = injectPointsMap[injectPoint];
+
+  if (selector === undefined || selector === null) {
+    const availablePoints = Object.keys(injectPointsMap).join(", ");
+    throw new Error(
+      `[hyacine-plugin] 未找到 injectPoint "${injectPoint}" 对应的选择器。` +
+        `\n可用的注入点有: ${availablePoints || "(无)"}`,
+    );
+  }
+
+  if (typeof selector !== "string" || selector.trim() === "") {
+    throw new Error(
+      `[hyacine-plugin] injectPoint "${injectPoint}" 对应的选择器无效: ${JSON.stringify(selector)}`,
+    );
+  }
+
+  return selector;
+}

package/src/integration-utils.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { HyacinePluginSystemConfig, PluginManifest } from "@hyacine/core";
+import {
+  CONFIG_FILE_NAMES,
+  collectRuntimeOnlyEntries,
+  findConfigFilePath,
+  getPluginManifests,
+  groupEntriesByInjectPoint,
+} from "./integration-utils";
+
+describe("integration-utils", () => {
+  describe("CONFIG_FILE_NAMES", () => {
+    test("应该包含正确的配置文件名", () => {
+      expect(CONFIG_FILE_NAMES).toEqual(["hyacine.plugin.ts", "hyacine.plugin.mjs"]);
+    });
+  });
+
+  describe("findConfigFilePath", () => {
+    test("应该找到 .ts 配置文件", () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), "hyacine-test-"));
+      const tsConfigPath = join(tmpDir, "hyacine.plugin.ts");
+      writeFileSync(tsConfigPath, "export default {};");
+
+      try {
+        const result = findConfigFilePath(tmpDir);
+        expect(result).toBe(tsConfigPath);
+      } finally {
+        rmSync(tmpDir, { recursive: true });
+      }
+    });
+
+    test("应该找到 .mjs 配置文件", () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), "hyacine-test-"));
+      const mjsConfigPath = join(tmpDir, "hyacine.plugin.mjs");
+      writeFileSync(mjsConfigPath, "export default {};");
+
+      try {
+        const result = findConfigFilePath(tmpDir);
+        expect(result).toBe(mjsConfigPath);
+      } finally {
+        rmSync(tmpDir, { recursive: true });
+      }
+    });
+
+    test("应该优先选择 .ts 配置文件", () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), "hyacine-test-"));
+      const tsConfigPath = join(tmpDir, "hyacine.plugin.ts");
+      const mjsConfigPath = join(tmpDir, "hyacine.plugin.mjs");
+      writeFileSync(tsConfigPath, "export default {};");
+      writeFileSync(mjsConfigPath, "export default {};");
+
+      try {
+        const result = findConfigFilePath(tmpDir);
+        expect(result).toBe(tsConfigPath);
+      } finally {
+        rmSync(tmpDir, { recursive: true });
+      }
+    });
+
+    test("找不到配置文件时应返回 null", () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), "hyacine-test-"));
+
+      try {
+        const result = findConfigFilePath(tmpDir);
+        expect(result).toBeNull();
+      } finally {
+        rmSync(tmpDir, { recursive: true });
+      }
+    });
+  });
+
+  describe("getPluginManifests", () => {
+    test("应该返回配置中的插件列表", () => {
+      const mockConfig: HyacinePluginSystemConfig = {
+        injectPoints: {
+          header: "header",
+          footer: "footer",
+        },
+        plugins: [
+          {
+            name: "test-plugin-1",
+            version: "1.0.0",
+            minRenderCapability: "runtime-only" as const,
+            entry: [],
+          },
+          {
+            name: "test-plugin-2",
+            version: "1.0.0",
+            minRenderCapability: "runtime-only" as const,
+            entry: [],
+          },
+        ],
+      };
+
+      const manifests = getPluginManifests(mockConfig);
+
+      expect(manifests).toHaveLength(2);
+      expect(manifests[0]!.name).toBe("test-plugin-1");
+      expect(manifests[1]!.name).toBe("test-plugin-2");
+    });
+  });
+
+  describe("collectRuntimeOnlyEntries", () => {
+    test("应该只收集 runtime-only 类型的 entry", () => {
+      const manifests: PluginManifest[] = [
+        {
+          name: "plugin-1",
+          version: "1.0.0",
+          minRenderCapability: "ssr" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "runtime-only",
+              name: "runtime-1",
+              path: "/path/to/runtime1.ts",
+            },
+            {
+              type: "ssr",
+              name: "ssr-1",
+              path: "/path/to/ssr1.ts",
+              injectPoint: "header",
+              platform: "astro",
+            },
+          ],
+        },
+        {
+          name: "plugin-2",
+          version: "1.0.0",
+          minRenderCapability: "ssr" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "runtime-only",
+              name: "runtime-2",
+              path: "/path/to/runtime2.ts",
+            },
+            {
+              type: "custom-element",
+              name: "ce-1",
+              path: "/path/to/ce1.ts",
+              injectPoint: "layout",
+            },
+          ],
+        },
+      ];
+
+      const result = collectRuntimeOnlyEntries(manifests);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]!.type).toBe("runtime-only");
+      expect(result[0]!.name).toBe("runtime-1");
+      expect(result[1]!.type).toBe("runtime-only");
+      expect(result[1]!.name).toBe("runtime-2");
+    });
+
+    test("所有 entry 都不是 runtime-only 时应返回空数组", () => {
+      const manifests: PluginManifest[] = [
+        {
+          name: "plugin-1",
+          version: "1.0.0",
+          minRenderCapability: "ssr" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "ssr",
+              name: "ssr-1",
+              path: "/path/to/ssr1.ts",
+              injectPoint: "header",
+              platform: "astro",
+            },
+          ],
+        },
+      ];
+
+      const result = collectRuntimeOnlyEntries(manifests);
+
+      expect(result).toHaveLength(0);
+    });
+
+    test("空 manifests 应返回空数组", () => {
+      const result = collectRuntimeOnlyEntries([]);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("groupEntriesByInjectPoint", () => {
+    test("应该按 injectPoint 对 SSR 和 CustomElement entry 进行分组", () => {
+      const manifests: PluginManifest[] = [
+        {
+          name: "plugin-1",
+          version: "1.0.0",
+          minRenderCapability: "ssr" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "ssr",
+              name: "ssr-1",
+              path: "/path/to/ssr1.ts",
+              injectPoint: "header",
+              platform: "astro",
+            },
+            {
+              type: "ssr",
+              name: "ssr-2",
+              path: "/path/to/ssr2.ts",
+              injectPoint: "footer",
+              platform: "astro",
+            },
+          ],
+        },
+        {
+          name: "plugin-2",
+          version: "1.0.0",
+          minRenderCapability: "custom-element" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "custom-element",
+              name: "ce-1",
+              path: "/path/to/ce1.ts",
+              injectPoint: "layout",
+            },
+          ],
+        },
+      ];
+
+      const result = groupEntriesByInjectPoint(manifests);
+
+      expect(result.size).toBe(3);
+      expect(result.get("header")).toHaveLength(1);
+      expect(result.get("footer")).toHaveLength(1);
+      expect(result.get("layout")).toHaveLength(1);
+      expect(result.get("header")?.[0]?.name).toBe("ssr-1");
+      expect(result.get("footer")?.[0]?.name).toBe("ssr-2");
+      expect(result.get("layout")?.[0]?.name).toBe("ce-1");
+    });
+
+    test("应该排除 runtime-only entry", () => {
+      const manifests: PluginManifest[] = [
+        {
+          name: "plugin-1",
+          version: "1.0.0",
+          minRenderCapability: "ssr" as const,
+          supportedPlatforms: ["astro"],
+          entry: [
+            {
+              type: "runtime-only",
+              name: "runtime-1",
+              path: "/path/to/runtime1.ts",
+            },
+            {
+              type: "ssr",
+              name: "ssr-1",
+              path: "/path/to/ssr1.ts",
+              injectPoint: "header",
+              platform: "astro",
+            },
+          ],
+        },
+      ];
+
+      const result = groupEntriesByInjectPoint(manifests);
+
+      expect(result.size).toBe(1);
+      expect(result.get("header")).toHaveLength(1);
+      expect(result.get("header")?.[0]?.name).toBe("ssr-1");
+    });
+
+    test("所有 entry 都是 runtime-only 时应返回空 Map", () => {
+      const manifests: PluginManifest[] = [
+        {
+          name: "plugin-1",
+          version: "1.0.0",
+          minRenderCapability: "runtime-only" as const,
+          entry: [
+            {
+              type: "runtime-only",
+              name: "runtime-1",
+              path: "/path/to/runtime1.ts",
+            },
+          ],
+        },
+      ];
+
+      const result = groupEntriesByInjectPoint(manifests);
+
+      expect(result.size).toBe(0);
+    });
+
+    test("空 manifests 应返回空 Map", () => {
+      const result = groupEntriesByInjectPoint([]);
+      expect(result.size).toBe(0);
+    });
+  });
+});

package/src/integration-utils.ts

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  CustomElementEntry,
+  HyacinePluginSystemConfig,
+  PluginManifest,
+  RuntimeOnlyEntry,
+  SSREntry,
+} from "@hyacine/core";
+
+/**
+ * 配置文件名常量
+ */
+export const CONFIG_FILE_NAMES = ["hyacine.plugin.ts", "hyacine.plugin.mjs"] as const;
+
+/**
+ * 查找插件配置文件路径
+ * @param rootPath 项目根目录路径
+ * @returns 配置文件的绝对路径，如果未找到则返回 null
+ */
+export function findConfigFilePath(rootPath: string): string | null {
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const configPath = join(rootPath, fileName);
+    if (existsSync(configPath)) {
+      return configPath;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取插件 manifest 列表
+ * @param config 插件系统配置
+ * @returns manifest 列表
+ */
+export function getPluginManifests(config: HyacinePluginSystemConfig): PluginManifest[] {
+  return config.plugins;
+}
+
+/**
+ * 收集所有 runtime-only 类型的 entry（不包含警告逻辑）
+ * @param manifests manifest 列表
+ * @returns runtime-only entry 数组
+ */
+export function collectRuntimeOnlyEntries(manifests: PluginManifest[]): RuntimeOnlyEntry[] {
+  const entries: RuntimeOnlyEntry[] = [];
+
+  for (const manifest of manifests) {
+    for (const entry of manifest.entry) {
+      if (entry.type === "runtime-only") {
+        entries.push(entry);
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * 按照 injectPoint 对 entry 进行分组（排除 runtime-only entry）
+ * @param manifests manifest 列表
+ * @returns 按 injectPoint 分组的 entry map
+ */
+export function groupEntriesByInjectPoint(
+  manifests: PluginManifest[],
+): Map<string, Array<SSREntry | CustomElementEntry>> {
+  const groups = new Map<string, Array<SSREntry | CustomElementEntry>>();
+
+  for (const manifest of manifests) {
+    for (const entry of manifest.entry) {
+      if (entry.type === "runtime-only") {
+        // runtime-only 单独处理，不在这里分组
+        continue;
+      }
+
+      const injectPoint = entry.injectPoint;
+      if (!groups.has(injectPoint)) {
+        groups.set(injectPoint, []);
+      }
+      groups.get(injectPoint)!.push(entry);
+    }
+  }
+
+  return groups;
+}