@yunzai-ng/core 0.1.0

package/src/plugin/define.test.ts

@@ -0,0 +1,120 @@
+/**
+ * 模块职责：`definePlugin()` 与两个判定函数的测试
+ * 依赖方向：测试文件
+ * 生命周期：纯函数，无需清理
+ * 注意事项：插件名会被同时用作**配置文件名、KV 命名空间、URL 前缀、日志 scope**，
+ *          因此"非法名称必须在 import 的那一刻即抛错"是此处的核心断言 ——
+ *          若予放行，症状将表现为写入配置时一个无从解释的 ENOENT，或更为严重的情形：
+ *          一个插件读写到了其他插件的 KV 命名空间。
+ */
+import { describe, expect, it } from "vitest"
+import { definePlugin, isPluginDefinition, looksLikePlugin } from "./define.js"
+import { s } from "../config/schema.js"
+
+/** 品牌标记用的注册表符号（插件与内核可能来自不同模块实例，故用 Symbol.for） */
+const BRAND = Symbol.for("yunzai-ng.plugin")
+
+describe("definePlugin", () => {
+  it("返回带品牌标记的定义", () => {
+    const def = definePlugin({ name: "demo", setup: () => undefined })
+
+    expect(def.name).toBe("demo")
+    expect(isPluginDefinition(def)).toBe(true)
+  })
+
+  it("原样保留元信息与 schema", () => {
+    const schema = s.object({ cookie: s.string().default("") })
+    const def = definePlugin({
+      name: "mhy-game",
+      version: "1.0.0",
+      description: "米哈游游戏插件",
+      author: "someone",
+      dependencies: ["renderer-puppeteer"],
+      priority: 50,
+      configSchema: schema,
+      setup: () => undefined
+    })
+
+    expect(def).toMatchObject({
+      name: "mhy-game",
+      version: "1.0.0",
+      description: "米哈游游戏插件",
+      dependencies: ["renderer-puppeteer"],
+      priority: 50
+    })
+    expect(def.configSchema).toBe(schema)
+  })
+
+  it("冻结定义，插件改不动自己的元信息", () => {
+    const def = definePlugin({ name: "demo", setup: () => undefined })
+    // 改了内核也不会重新读，只会让人以为改生效了
+    expect(() => {
+      ;(def as { name: string }).name = "别的名字"
+    }).toThrow()
+  })
+
+  it("缺 name 就抛错", () => {
+    expect(() => definePlugin({ setup: () => undefined } as never)).toThrow(/缺少 name/)
+    expect(() => definePlugin({ name: "", setup: () => undefined })).toThrow(/缺少 name/)
+  })
+
+  it("非法插件名抛错并说明规则", () => {
+    for (const name of ["1abc", "有中文", "with space", "a:b", "a/b", "-lead", "_lead"]) {
+      expect(() => definePlugin({ name, setup: () => undefined }), name).toThrow(/不合法/)
+    }
+  })
+
+  it("合法插件名放行", () => {
+    for (const name of ["demo", "mhy-game-plugin", "adapter.napcat", "A_b-1", "x"]) {
+      expect(() => definePlugin({ name, setup: () => undefined }), name).not.toThrow()
+    }
+  })
+
+  it("缺 setup 抛错", () => {
+    expect(() => definePlugin({ name: "demo" } as never)).toThrow(/缺少 setup/)
+  })
+
+  it("dependencies 写法错误抛错", () => {
+    expect(() => definePlugin({ name: "demo", dependencies: "other" as never, setup: () => undefined })).toThrow(
+      /必须是字符串数组/
+    )
+    expect(() => definePlugin({ name: "demo", dependencies: [""], setup: () => undefined })).toThrow(/含空项/)
+    expect(() => definePlugin({ name: "demo", dependencies: ["demo"], setup: () => undefined })).toThrow(/依赖了自己/)
+  })
+
+  it("priority 必须是数字", () => {
+    expect(() => definePlugin({ name: "demo", priority: Number.NaN, setup: () => undefined })).toThrow(
+      /priority 必须是数字/
+    )
+  })
+})
+
+describe("isPluginDefinition", () => {
+  it("只认 definePlugin 的产物", () => {
+    expect(isPluginDefinition({ name: "demo", setup: () => undefined })).toBe(false)
+    expect(isPluginDefinition(undefined)).toBe(false)
+    expect(isPluginDefinition(null)).toBe(false)
+    expect(isPluginDefinition("demo")).toBe(false)
+    expect(isPluginDefinition(() => undefined)).toBe(false)
+  })
+
+  it("品牌用注册表符号，跨模块实例也认得", () => {
+    // 插件可能链接了另一份 @yunzai-ng/core（版本不同的两个 node_modules 副本）。
+    // Symbol.for 是全进程共享的，所以这种情况下判定仍然成立 ——
+    // 换成模块内的 Symbol() 就会退化成"看起来像插件"的宽松路径。
+    expect(isPluginDefinition({ name: "demo", setup: () => undefined, [BRAND]: true })).toBe(true)
+  })
+})
+
+describe("looksLikePlugin", () => {
+  it("有 name 与 setup 即可（手写定义、compat 插件动态生成的定义）", () => {
+    expect(looksLikePlugin({ name: "demo", setup: () => undefined })).toBe(true)
+  })
+
+  it("缺一个就不算", () => {
+    expect(looksLikePlugin({ name: "demo" })).toBe(false)
+    expect(looksLikePlugin({ setup: () => undefined })).toBe(false)
+    expect(looksLikePlugin({ name: 1, setup: () => undefined })).toBe(false)
+    expect(looksLikePlugin(null)).toBe(false)
+  })
+})

package/src/plugin/define.ts

@@ -0,0 +1,142 @@
+/**
+ * 模块职责：`definePlugin()` —— 插件的声明入口与配置类型推导
+ * 依赖方向：依赖 config/schema、类型包
+ * 生命周期：模块加载期执行一次（纯校验，无副作用）
+ * 注意事项：两个设计要点 ——
+ *
+ *          1) **配置类型自动推导**。`configSchema: s.object({ cookie: s.string() })`
+ *             之后，`ctx.config.get().cookie` 就是 `string`，写错字段名编译期报错。
+ *             类型包为保持叶子（不许依赖任何工作区包）故把 `configSchema` 声明为
+ *             `unknown`，推导只能在这里做 —— 这也是插件必须从 `@yunzai-ng/core`
+ *             导入 `definePlugin` 而不是自己拼对象的原因。
+ *
+ *          2) **在声明期就校验元信息**。插件名会被当作配置文件名、KV 命名空间、
+ *             URL 前缀和日志 scope 使用，非法名字必须在 `import` 的那一刻就报错，
+ *             而不是等到写文件时抛一个看不出所以然的 ENOENT。
+ */
+import type { Awaitable, Disposer, PluginContext, PluginDefinition, PluginMeta } from "@yunzai-ng/types"
+import type { Schema } from "../config/schema.js"
+
+/**
+ * 插件名合法形式
+ *
+ * 与配置名规则保持一致（见 config/store.ts）：插件名直接就是
+ * `config/<name>.yaml` 的文件名。额外排除了 `:`（KV 命名空间分隔符）
+ * 与路径分隔符，否则一个插件能读写别人的命名空间。
+ */
+const NAME_RE = /^[a-z][a-z0-9._-]*$/i
+
+/** 标记"这是 definePlugin 的产物"，用于加载时校验默认导出 */
+const BRAND = Symbol.for("yunzai-ng.plugin")
+
+/**
+ * 从 schema 推出配置类型
+ *
+ * 未声明 schema 时给出 `Record<string, never>`：`ctx.config.get()` 仍可调用，
+ * 但读取任何字段均会在编译期报错，以提示作者"尚未声明配置"。
+ */
+export type ConfigOf<S> = S extends Schema<infer T> ? T : Record<string, never>
+
+/** `definePlugin` 的入参 */
+export interface DefinePluginInput<S extends Schema<unknown> | undefined = undefined> extends PluginMeta {
+  /**
+   * 配置 schema
+   *
+   * 用 `s.object({...})` 构造。内核据此生成带中文注释的 YAML、
+   * 渲染 WebUI 表单、校验用户输入 —— 三处共用一份声明，永不脱节。
+   */
+  configSchema?: S
+
+  /**
+   * 插件入口
+   *
+   * 在这里注册命令、中间件、定时任务等。**不要**在这里做耗时的网络请求：
+   * 内核对 setup 有超时（默认 30s），超时会把插件标记为加载失败。
+   * 需要预热的资源请注册 `ctx.on("app/ready", ...)` 或用 `ctx.cron`。
+   * @param ctx 注入的上下文
+   * @returns 可选的清理函数，等价于在里面调 `ctx.onDispose`
+   */
+  setup(ctx: PluginContext<ConfigOf<S>>): Awaitable<void | Disposer>
+}
+
+/** 带品牌标记的插件定义（内核内部使用） */
+export interface BrandedPluginDefinition<C = unknown> extends PluginDefinition<C> {
+  /** 品牌标记 */
+  readonly [BRAND]: true
+}
+
+/**
+ * 声明一个插件
+ *
+ * @param input 插件定义
+ * @returns 供内核加载的插件定义（已冻结）
+ * @throws 插件名缺失/非法、`setup` 不是函数、依赖项写法错误时
+ * @example
+ * ```ts
+ * export default definePlugin({
+ *   name: "mhy-game",
+ *   configSchema: s.object({ cookie: s.string().default("") }),
+ *   setup(ctx) {
+ *     ctx.command("#体力").desc("查询实时便笺").action(async e => {
+ *       await e.reply(ctx.config.get().cookie ? "查询中" : "请先配置 cookie")
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export function definePlugin<S extends Schema<unknown> | undefined = undefined>(
+  input: DefinePluginInput<S>
+): PluginDefinition<ConfigOf<S>> {
+  if (typeof input?.name !== "string" || input.name.length === 0) {
+    throw new Error("definePlugin：缺少 name，插件必须有名字")
+  }
+  if (!NAME_RE.test(input.name)) {
+    throw new Error(`definePlugin：插件名 ${input.name} 不合法。需以字母开头，只含字母、数字与 . - _（它同时是配置文件名与存储命名空间）`)
+  }
+  if (typeof input.setup !== "function") {
+    throw new Error(`definePlugin：插件 ${input.name} 缺少 setup 函数`)
+  }
+  if (input.dependencies && !Array.isArray(input.dependencies)) {
+    throw new Error(`definePlugin：插件 ${input.name} 的 dependencies 必须是字符串数组`)
+  }
+  for (const dep of input.dependencies ?? []) {
+    if (typeof dep !== "string" || dep.length === 0) {
+      throw new Error(`definePlugin：插件 ${input.name} 的 dependencies 含空项`)
+    }
+    if (dep === input.name) {
+      throw new Error(`definePlugin：插件 ${input.name} 依赖了自己`)
+    }
+  }
+  if (input.priority !== undefined && !Number.isFinite(input.priority)) {
+    throw new Error(`definePlugin：插件 ${input.name} 的 priority 必须是数字`)
+  }
+
+  // 浅冻结：防止插件在运行期改自己的元信息（改了内核也不会重新读，只会造成困惑）
+  return Object.freeze({ ...input, [BRAND]: true }) as unknown as PluginDefinition<ConfigOf<S>>
+}
+
+/**
+ * 判断一个值是否 `definePlugin` 的产物
+ *
+ * 加载器用它区分"插件写错了默认导出"和"插件确实是插件"，
+ * 从而给出"请用 definePlugin 包一层"这种能直接照做的提示。
+ * @param value 待判定值
+ * @returns 是否为插件定义
+ */
+export function isPluginDefinition(value: unknown): value is BrandedPluginDefinition {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[BRAND] === true
+}
+
+/**
+ * 宽松判定：像插件定义但可能没走 `definePlugin`
+ *
+ * 允许手写对象（如测试里的假插件、compat 插件动态生成的定义），
+ * 只要有 name 与 setup 就接受，但加载器会记一条 debug 提示。
+ * @param value 待判定值
+ * @returns 是否可当作插件定义使用
+ */
+export function looksLikePlugin(value: unknown): value is PluginDefinition {
+  if (typeof value !== "object" || value === null) return false
+  const obj = value as Partial<PluginDefinition>
+  return typeof obj.name === "string" && typeof obj.setup === "function"
+}

package/src/plugin/discover.test.ts

@@ -0,0 +1,253 @@
+/**
+ * 模块职责：插件发现与加载顺序规划的测试
+ * 依赖方向：测试文件，依赖 plugin/discover、testing/fake
+ * 生命周期：每个用例一个临时插件目录
+ * 注意事项：`resolveLoadOrder` 的**确定性**是重点断言对象 —— 同一份插件集合在任何机器上
+ *          都须得到相同顺序，否则"甲机器正常、乙机器异常"会耗费大量排障时间。
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { discoverPlugins, resolveLoadOrder } from "./discover.js"
+import { fakeLogger } from "../testing/fake.js"
+
+/** 造一个插件目录 */
+async function makePlugin(
+  root: string,
+  name: string,
+  opts: { pkg?: Record<string, unknown>; entry?: string; content?: string } = {}
+): Promise<string> {
+  const dir = join(root, name)
+  await mkdir(dir, { recursive: true })
+  if (opts.pkg) await writeFile(join(dir, "package.json"), JSON.stringify(opts.pkg))
+  const entry = opts.entry ?? "index.js"
+  if (entry) {
+    await mkdir(join(dir, entry.includes("/") ? entry.split("/").slice(0, -1).join("/") : "."), { recursive: true })
+    await writeFile(join(dir, entry), opts.content ?? "export default {}\n")
+  }
+  return dir
+}
+
+describe("discoverPlugins", () => {
+  let root: string
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "yzng-discover-"))
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it("找到带 index.js 的插件目录", async () => {
+    await makePlugin(root, "demo")
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+
+    expect(found).toHaveLength(1)
+    expect(found[0]?.id).toBe("demo")
+    expect(found[0]?.entry).toBe(join(root, "demo", "index.js"))
+    expect(found[0]?.builtin).toBe(false)
+  })
+
+  it("优先用 package.json 声明的入口", async () => {
+    await makePlugin(root, "custom", { pkg: { name: "custom", main: "lib/boot.js" }, entry: "lib/boot.js" })
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found[0]?.entry).toBe(join(root, "custom", "lib", "boot.js"))
+  })
+
+  it("认 exports 的条件导出", async () => {
+    await makePlugin(root, "exp", {
+      pkg: { name: "exp", exports: { ".": { import: "./dist/mod.js" } } },
+      entry: "dist/mod.js"
+    })
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found[0]?.entry).toBe(join(root, "exp", "dist", "mod.js"))
+  })
+
+  it("scope 包名去掉 scope 作为名字线索", async () => {
+    await makePlugin(root, "scoped", { pkg: { name: "@acme/cool-plugin" } })
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found[0]?.id).toBe("cool-plugin")
+  })
+
+  it("yunzai.name 优先于包名与目录名", async () => {
+    await makePlugin(root, "dirname", { pkg: { name: "pkgname", yunzai: { name: "declared" } } })
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found[0]?.id).toBe("declared")
+  })
+
+  it("跳过隐藏目录、下划线开头目录与 node_modules", async () => {
+    await makePlugin(root, ".hidden")
+    await makePlugin(root, "_disabled")
+    await makePlugin(root, "node_modules")
+    await makePlugin(root, "real")
+
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found.map(f => f.id)).toEqual(["real"])
+  })
+
+  it("package.json 自标记 disabled 的插件不加载", async () => {
+    await makePlugin(root, "off", { pkg: { name: "off", yunzai: { disabled: true } } })
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found).toHaveLength(0)
+  })
+
+  it("找不到入口时给出照着能解决的警告，而不是静默跳过", async () => {
+    const dir = join(root, "broken")
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, "readme.md"), "# 忘了写 index.js")
+
+    const logger = fakeLogger()
+    const found = await discoverPlugins({ dirs: [root], logger })
+
+    expect(found).toHaveLength(0)
+    const line = logger.lines.find(l => l.includes("broken"))
+    expect(line).toBeDefined()
+    expect(line).toContain("index.js")
+  })
+
+  it("支持顶层单文件插件", async () => {
+    await writeFile(join(root, "小功能.js"), "export default {}\n")
+    await writeFile(join(root, "_草稿.js"), "export default {}\n")
+
+    const found = await discoverPlugins({ dirs: [root], logger: fakeLogger() })
+    expect(found.map(f => f.id)).toEqual(["小功能"])
+    expect(found[0]?.dir).toBe(root)
+  })
+
+  it("同名插件先扫到的胜出，并给出警告", async () => {
+    const userDir = await mkdtemp(join(tmpdir(), "yzng-user-"))
+    try {
+      await makePlugin(userDir, "dup")
+      await makePlugin(root, "dup")
+
+      const logger = fakeLogger()
+      // 用户目录排在前面 —— 复制一份预置插件加以修改即应覆盖原插件
+      const found = await discoverPlugins({ dirs: [userDir, root], builtinDirs: [root], logger })
+
+      expect(found).toHaveLength(1)
+      expect(found[0]?.dir).toBe(join(userDir, "dup"))
+      expect(logger.lines.some(l => l.includes("同名插件"))).toBe(true)
+    } finally {
+      await rm(userDir, { recursive: true, force: true })
+    }
+  })
+
+  it("给预置目录里的插件打 builtin 标记", async () => {
+    await makePlugin(root, "builtin-one")
+    const found = await discoverPlugins({ dirs: [root], builtinDirs: [root], logger: fakeLogger() })
+    expect(found[0]?.builtin).toBe(true)
+  })
+
+  it("被用户禁用的插件不出现在结果里", async () => {
+    await makePlugin(root, "nope")
+    const found = await discoverPlugins({ dirs: [root], disabled: ["nope"], logger: fakeLogger() })
+    expect(found).toHaveLength(0)
+  })
+
+  it("相对路径目录被拒绝并警告（相对路径会随启动方式漂移）", async () => {
+    const logger = fakeLogger()
+    const found = await discoverPlugins({ dirs: ["./plugins"], logger })
+    expect(found).toHaveLength(0)
+    expect(logger.lines.some(l => l.includes("绝对路径"))).toBe(true)
+  })
+
+  it("目录不存在时安静返回空数组", async () => {
+    const found = await discoverPlugins({ dirs: [join(root, "not-there")], logger: fakeLogger() })
+    expect(found).toEqual([])
+  })
+})
+
+describe("resolveLoadOrder", () => {
+  it("依赖先于依赖方加载", () => {
+    const { order, skipped } = resolveLoadOrder([
+      { name: "game", dependencies: ["renderer"] },
+      { name: "renderer" }
+    ])
+
+    expect(order.map(u => u.name)).toEqual(["renderer", "game"])
+    expect(skipped).toEqual([])
+  })
+
+  it("多层依赖链按拓扑顺序展开", () => {
+    const { order } = resolveLoadOrder([
+      { name: "c", dependencies: ["b"] },
+      { name: "a" },
+      { name: "b", dependencies: ["a"] }
+    ])
+    expect(order.map(u => u.name)).toEqual(["a", "b", "c"])
+  })
+
+  it("同层内按 priority 再按名字排序（确定性）", () => {
+    const { order } = resolveLoadOrder([
+      { name: "zebra", priority: 10 },
+      { name: "alpha", priority: 50 },
+      { name: "beta", priority: 50 },
+      { name: "omega" }
+    ])
+    expect(order.map(u => u.name)).toEqual(["zebra", "alpha", "beta", "omega"])
+  })
+
+  it("同一集合的不同输入顺序得到同一结果", () => {
+    const units = [
+      { name: "b", dependencies: ["a"] },
+      { name: "a" },
+      { name: "d", dependencies: ["a"] },
+      { name: "c", dependencies: ["a"] }
+    ]
+    const first = resolveLoadOrder(units).order.map(u => u.name)
+    const second = resolveLoadOrder([...units].reverse()).order.map(u => u.name)
+    expect(second).toEqual(first)
+    expect(first).toEqual(["a", "b", "c", "d"])
+  })
+
+  it("缺依赖的插件被跳过，其余照常加载", () => {
+    const { order, skipped } = resolveLoadOrder([{ name: "needs-genshin", dependencies: ["genshin"] }, { name: "solo" }])
+
+    expect(order.map(u => u.name)).toEqual(["solo"])
+    expect(skipped).toHaveLength(1)
+    expect(skipped[0]?.name).toBe("needs-genshin")
+    expect(skipped[0]?.reason).toContain("genshin")
+  })
+
+  it("依赖缺失会级联剔除依赖它的插件", () => {
+    const { order, skipped } = resolveLoadOrder([
+      { name: "a", dependencies: ["missing"] },
+      { name: "b", dependencies: ["a"] },
+      { name: "c", dependencies: ["b"] },
+      { name: "healthy" }
+    ])
+
+    expect(order.map(u => u.name)).toEqual(["healthy"])
+    expect(skipped.map(s => s.name).sort()).toEqual(["a", "b", "c"])
+  })
+
+  it("依赖成环时整环跳过，并在原因里列出环成员", () => {
+    const { order, skipped } = resolveLoadOrder([
+      { name: "x", dependencies: ["y"] },
+      { name: "y", dependencies: ["x"] },
+      { name: "fine" }
+    ])
+
+    expect(order.map(u => u.name)).toEqual(["fine"])
+    expect(skipped.map(s => s.name)).toEqual(["x", "y"])
+    expect(skipped[0]?.reason).toContain("成环")
+    expect(skipped[0]?.reason).toContain("y")
+  })
+
+  it("重名只留第一个", () => {
+    const { order, skipped } = resolveLoadOrder([
+      { name: "dup", priority: 1 },
+      { name: "dup", priority: 2 }
+    ])
+
+    expect(order).toHaveLength(1)
+    expect(order[0]?.priority).toBe(1)
+    expect(skipped[0]?.reason).toContain("重复")
+  })
+
+  it("空输入不报错", () => {
+    expect(resolveLoadOrder([])).toEqual({ order: [], skipped: [] })
+  })
+})