@taicode/common-server 4.0.0-beta.1 → 4.0.0-beta.10

package/output/core/test-support/testdata.d.ts

@@ -0,0 +1,255 @@
+import type { AppEnv, ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+/**
+ * **测试数据（testdata）机制**：`packages/server/testdata/*.ts|js` 下的脚本，在 `development` /
+ * `test` 启动时自动加载，并在用例之间被重新加载。
+ *
+ * ## 为什么是「目录 + 约定方法」，而不是资源上的生命周期
+ *
+ * 「这条用例需要哪些样本数据」与「这份数据怎么删掉」是**同一件事的正反面**，写在同一个文件里
+ * 才不容易漏。把 `cleanup` 挂到资源单元上做不到这一点：资源只知道「有哪些表 / 哪些 key」，
+ * 不知道「谁往里写了什么」——新增一个 model 就要回去改一次清库清单，漏改只会安静地变脏。
+ *
+ * 所以机制倒过来：**数据脚本自己负责自己**。
+ *
+ * ```ts
+ * // packages/server/testdata/01-base.ts（推荐写法）
+ * import { defineTestData } from '@taicode/common-server/app'
+ * import type { AppResources } from '../source/resources'
+ *
+ * export default defineTestData<AppResources>({
+ *   async load(ctx) { …插入样本数据… },
+ * })
+ * ```
+ *
+ * 命名导出 `load(ctx)` / `cleanup(ctx)`（+ 可选 `dependsOn`）继续支持；两者都有时默认导出优先。
+ *
+ * ## 契约（只有三条）
+ *
+ * 1. **目录固定**：`<cwd>/testdata`（`tsx watch ./source/index.ts` 与 `vitest` 的 cwd 都是
+ *    `packages/server`）。目录不存在 = 没有脚本。
+ * 2. **`load` 必需，`cleanup` 可选**：只写 `load` 的脚本是**合法**的——它的数据由资源单元的
+ *    `clean()`（典型实现 `TRUNCATE ... CASCADE`）在重装前清掉。需要「资源清不掉的东西」
+ *    （下游 mock 预置、临时文件）时才写 `cleanup`。
+ * 3. **顺序**：文件名（字典序升序）是默认序；需要「我必须排在某脚本之后」时用
+ *    `dependsOn` 显式声明，见下节。
+ *
+ * ## 顺序：`dependsOn` 是权威，文件名只做同层破平
+ *
+ * ```ts
+ * // packages/server/testdata/02-organization.ts
+ * import { defineTestData } from '@taicode/common-server/app'
+ *
+ * export default defineTestData({
+ *   dependsOn: ['01-database'],
+ *   async load(ctx) { … },
+ * })
+ * ```
+ *
+ * - **引用名 = 去扩展名的文件名**（`01-base.ts` → `'01-base'`），与 `TestDataUnit.name` 一致。
+ * - **只影响顺序，不注入任何东西**：声明依赖**不会**把前一个脚本的客户端/数据递给你——需要共享
+ *   资源时用 `ctx.resources`（框架注入的装配产物），而不是依赖另一个脚本。
+ * - **`cleanup` 不用声明**：它是装配序的逆序，依赖自动反向成立（后建的先拆）。
+ * - **同层按文件名升序**：没有依赖关系的脚本之间的相对顺序由文件名决定，结果确定可复现。
+ * - **缺依赖 / 自依赖 / 环一律报错**（不是跳过、不是猜测顺序）：顺序是安全属性，猜错只会
+ *   变成偶发的外键冲突。
+ *
+ * 为什么要有这个字段：数字前缀是「顺序的替身」，中间插一个脚本就得重命名后面全部文件——
+ * 纯噪音改动，还会切断 git 历史。依赖声明让「谁必须在谁之后」贴着原因写。
+ *
+ * > 字段名与已删除的**模块装配期** `dependsOn`（连同 `validateLifecycleDependencies`，§11-2）
+ * > 无关：那个是资源/模块之间的构造依赖，这个是数据脚本之间的**执行顺序**。
+ *
+ * ## 两条与「安全」有关的约定
+ *
+ * - **`_` 开头的文件不是脚本**：它们是脚本之间共享的 helper（`_client.ts`），不会被 `load` /
+ *   `cleanup`。否则扫描目录就会把工具文件也当成脚本执行。
+ * - **只在可清理环境执行**：`load` / `cleanup` 两个执行入口的**第 0 步**都是
+ *   `assertCleanableEnvironment(ctx.env.ENV)`。判据是装配期的 `ctx.env` 快照（事后改写
+ *   `process.env` 不影响结论）。
+ *
+ * ## 执行顺序与失败语义
+ *
+ * | 入口 | 顺序 | 失败 |
+ * | --- | --- | --- |
+ * | `loadTestData` | **执行序**（`dependsOn` 拓扑序，同层按文件名升序） | 立即冒泡 |
+ * | `cleanupTestData` | **执行序逆序**（无 `cleanup` 的脚本跳过） | 立即冒泡 |
+ *
+ * `cleanup` 逆序是「后建的先拆」，依赖因此不必反向声明。
+ *
+ * 失败**一律冒泡**，不降级成「跳过这条脚本」：数据没准备好时静默继续只会让后续用例读到脏状态，
+ * 制造伪绿。
+ *
+ * ## 脚本拿到什么：`ctx`
+ *
+ * 脚本不再自己读 env、不再自己建连接——框架把装配好的东西注入进来。`load` 跑在
+ * `app.ready()` 之后、`listen` 之前，所以装配产物**全部已经存在**：
+ *
+ * | 字段 | 是什么 | 为什么给 |
+ * | --- | --- | --- |
+ * | `env` | 装配快照 `AppEnv<Env>` | 脚本不碰 `process.env`；看到的就是应用看到的那份 |
+ * | `resources` | `ResourcesView<Resources>`（单元已解包） | 脚本写数据的地方就是被测服务读数据的地方 |
+ * | `config` | 启动期配置快照 `Awaited<Config>`（只读） | 有些基线必须以配置为输入（按配置里的管理员名单造账号） |
+ * | `clients` | `ClientsView<Clients>` | 预置 / 清理下游 mock 状态的唯一正当通道 |
+ * | `services` | `Awaited<Services>`（已 `init()`） | 走服务造数据才会自动满足业务不变量（哈希、缓存失效、审计） |
+ * | `log` | `ctx.log` | 日志与装配期同一路输出 |
+ *
+ * 「脚本自己建一份客户端」是**错的**：同一份数据经两条连接写/读，缓存与连接级状态对不上
+ * （account 曾经的 `globalThis` 重置注册表就是这个坑的产物）。所以注入 `resources` 是结构性的，
+ * 不是便利。
+ *
+ * **为什么不给 `app`**：拿到 `app` 就能 `inject()`，等于「跑一条业务链路来造数据」。那会一次性
+ * 引入中间件链（鉴权 / 限流 / requestId）、响应信封与错误映射，让基线脚本的失败语义、执行顺序、
+ * 耗时全部失控——而这三样正是 `dependsOn` 与「失败直接冒泡」想守住的东西。要跑链路请写在用例里。
+ *
+ * ## 三条使用边界
+ *
+ * 1. **首选 `resources`，`services` 只在「必须满足业务不变量」时用**，并在文件头写明原因。
+ *    同一个目录里一半 raw write、一半走 service，数据形状迟早会不一致。
+ * 2. **`config` 是快照**：脚本写配置表**不会**刷新当前实例的 `ctx.config`，要生效只能重新装配。
+ * 3. **`clients` 只用于预置 / 清理下游 mock**：`development` 会跑同一批脚本，误发就是真的发出去了。
+ */
+export interface TestDataContext<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /** 本次装配的 env 快照（框架固定约定 + 应用扩展字段）；脚本**不必也不该**再读 `process.env` */
+    readonly env: AppEnv<Env>;
+    /** 装配好的资源（单元已解包）：写数据 / 清缓存都用它，而不是另建一份客户端 */
+    readonly resources: ResourcesView<Resources>;
+    /** 启动期配置快照（只读）：写配置表不会刷新它，要生效需重新装配 */
+    readonly config: Awaited<Config>;
+    /** 外部客户端：只用于预置 / 清理下游 mock，不得产生真实外部副作用 */
+    readonly clients: ClientsView<Clients>;
+    /** 已 `init()` 完成的服务实例：走它造数据才会满足业务不变量 */
+    readonly services: Awaited<Services>;
+    /** 记录型 logger（与装配期同一个） */
+    readonly log: LoggerLike;
+}
+/** 一个测试数据脚本（`testdata/*.ts` 的约定导出） */
+export interface TestDataScript<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /** 加载本脚本负责的测试数据（可重复执行） */
+    load(ctx: TestDataContext<Resources, Env, Config, Clients, Services>): void | Promise<void>;
+    /**
+     * 清理本脚本负责的测试数据（可选）。
+     *
+     * **大多数脚本不需要它**：内存数据库的行由资源单元的 `clean()`（典型实现
+     * `TRUNCATE ... CASCADE`）在重新装配前清掉。只有「资源清不掉的东西」才需要自己写
+     * `cleanup`——下游 mock 的预置状态、临时文件、外部队列的 key。
+     *
+     * 提供时必须能把 `load()` 的效果完全撤销；不提供时重装前由资源兜底。
+     */
+    cleanup?(ctx: TestDataContext<Resources, Env, Config, Clients, Services>): void | Promise<void>;
+    /**
+     * 必须在哪些脚本**之后**执行（去扩展名的文件名；缺省 = 无要求）。
+     *
+     * 只影响排序：`load` 按依赖拓扑序（同层按文件名升序），`cleanup` 取其逆序。
+     * 校验严格：引用不存在的脚本、引用自己、循环依赖都会让装载阶段**抛错**。
+     */
+    readonly dependsOn?: readonly string[];
+}
+/** `defineTestData()` 的入参：与 `TestDataScript` 同形（只有 `load` 必需） */
+export type TestDataDefinition<Resources = object, Env = object, Config = object, Clients = object, Services = object> = TestDataScript<Resources, Env, Config, Clients, Services>;
+/**
+ * 由**一个** `Server` 类型推出脚本类型（`defineTestData<typeof server>({ … })` 用的就是这个）。
+ *
+ * 五个槽位泛型本来要一个个手写、顺序还得对上（`Resources, Env, Config, Clients, Services` 与
+ * `Server` 的 `Resources, Config, Clients, Services, Env` 不同序）；直接给 `server` 就没这个问题：
+ * 写错泛型名会当场报错，而不是静默拿到 `object`。
+ *
+ * 非 `Server` 类型（如直接传 `AccountResources`）退化为「只声明 `resources`」的老写法。
+ */
+export type TestDataScriptOf<S, Env = object> = S extends Server<infer Resources, infer Config, infer Clients, infer Services, infer AppEnvShape> ? TestDataScript<Resources, AppEnvShape, Config, Clients, Services> : TestDataScript<S, Env>;
+/** `defineTestData<S>()` 的入参（`TestDataScriptOf` 的别名，语义更贴近调用处） */
+export type TestDataDefinitionOf<S, Env = object> = TestDataScriptOf<S, Env>;
+/**
+ * 声明一个测试数据脚本（**唯一正当的写法**）。
+ *
+ * ```ts
+ * // packages/server/testdata/03-system-config.ts
+ * import { defineTestData } from '@taicode/common-server/app'
+ * import type { server } from '../source/server' // 纯类型导入，无副作用
+ *
+ * export default defineTestData<typeof server>({
+ *   dependsOn: ['01-database'],
+ *   async load(ctx) { …插入样本数据… },
+ *   async cleanup(ctx) { …删掉自己插入的数据… },
+ * })
+ * ```
+ *
+ * 泛型写 `typeof server` 而不是逐个槽位：`ctx` 上的 `resources` / `config` / `clients` /
+ * `services` / `env` 类型一次到位。只想声明 `resources` 时也可以写
+ * `defineTestData<AccountResources>({ … })`（其余槽位退化为 `object`）。
+ *
+ * ## 它解决什么
+ *
+ * 命名导出 `load` 是**约定**，写错只在装载期才会暴露（少写 `load` = 启动直接失败）。
+ * `defineTestData` 把这份约定变成**定义期**就检查的东西：
+ *
+ * 1. **缺 `load` 当场报错**（不是等到 `discoverTestDataModules()` 扫描到它）；
+ * 2. **`dependsOn` 当场校验**（必须是字符串数组、不能有重复项；引用不存在的脚本 / 自依赖 /
+ *    环属于跨文件问题，仍在装载期由 `sortByDependencies()` 统一判定）；
+ * 3. **结果冻结**：脚本之间不会互相改写 `load` / `cleanup`（执行器拿到的就是定义时那份）。
+ *
+ * `ctx` 的类型由 `S` 一次性带进来：`defineTestData<typeof server>({ load(ctx) {…} })` 里
+ * `ctx.services` / `ctx.resources` / `ctx.config` 全部有类型，不需要每个脚本再手写
+ * `type Ctx = TestDataContext<…>`。
+ *
+ * ## 与「命名导出」的关系
+ *
+ * 两种写法都合法，`defineTestData` 只是把结构显式化：
+ *
+ * ```ts
+ * // 推荐：默认导出一个定义对象
+ * export default defineTestData<typeof server>({ load })
+ *
+ * // 等价：命名导出（旧写法，继续支持）
+ * export async function load(ctx: TestDataContext<AccountResources>) { … }
+ * export const dependsOn = ['01-database']
+ * ```
+ *
+ * 同一个文件里两者都有时，**默认导出优先**——避免「改了默认导出、命名导出还在生效」的歧义。
+ */
+export declare function defineTestData<S = object, Env = object>(definition: TestDataDefinitionOf<S, Env>): TestDataScriptOf<S, Env>;
+/** 一个已从磁盘装载好的脚本单元（含名字，用于日志与报错定位） */
+export interface TestDataUnit<Resources = object, Env = object, Config = object, Clients = object, Services = object> extends TestDataScript<Resources, Env, Config, Clients, Services> {
+    /** 脚本文件名去掉扩展名（`01-base.ts` → `01-base`） */
+    readonly name: string;
+}
+/** 两个执行入口的共同入参 */
+export interface TestDataRunParams<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /**
+     * 本次装配的 ctx（`env` + `resources` + `config` + `clients` + `services` + `log`）。**必填**：
+     *
+     * - 闸门读 `ctx.env.ENV`：非 `CLEANABLE_ENVS`（`development` / `test`）一律抛错，一个脚本都不跑；
+     * - 脚本拿到的就是这份 ctx，所以它看到的环境 / 资源与本次装配完全一致。
+     */
+    ctx: TestDataContext<Resources, Env, Config, Clients, Services>;
+    /** 已装载的脚本（`discoverTestDataModules()` 的产物）；缺省 = 没有脚本 */
+    units?: readonly TestDataUnit<Resources, Env, Config, Clients, Services>[];
+    /** 日志标签（`defineServer({ app: { service } })`） */
+    service?: string;
+}
+/** 默认脚本目录（相对 `process.cwd()`） */
+export declare function resolveTestDataDirectory(): string;
+/**
+ * 扫描目录并**装载**全部脚本（`import()` 一次，模块本身由 ESM 缓存复用）。
+ *
+ * 目录不存在 → 空数组（不是错误：没写测试数据的服务是合法的）。
+ * 文件存在但缺 `load` → **抛错**，并指出是哪个文件。
+ *
+ * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
+ * `cleanup` 直接逆序跑）。
+ */
+export declare function discoverTestDataModules<Resources = object, Env = object, Config = object, Clients = object, Services = object>(directory?: string): Promise<TestDataUnit<Resources, Env, Config, Clients, Services>[]>;
+/**
+ * 加载测试数据：按**执行序**逐项 `await load(ctx)`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` / `startServer()` 装配完成后自动执行一次；也可以由测试自己再调。
+ */
+export declare function loadTestData<Resources, Env, Config, Clients, Services>(params: TestDataRunParams<Resources, Env, Config, Clients, Services>): Promise<void>;
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。没有 `cleanup` 的脚本直接跳过。
+ *
+ * 注意：它只负责「把脚本插入的东西撤掉」，不是「把整个库清空」——库由资源单元的 `clean()` 清。
+ */
+export declare function cleanupTestData<Resources, Env, Config, Clients, Services>(params: TestDataRunParams<Resources, Env, Config, Clients, Services>): Promise<void>;
+//# sourceMappingURL=testdata.d.ts.map

package/output/core/test-support/testdata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testdata.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM;IACrH,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC5C,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IACtC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CACzB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM;IACpH,0BAA0B;IAC1B,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3F;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/F;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,IAAI,cAAc,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;AAElL;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,SAAS,EAAE,MAAM,MAAM,EAAE,MAAM,OAAO,EAAE,MAAM,QAAQ,EAAE,MAAM,WAAW,CAAC,GAC7I,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,GACjE,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAE1B,iEAAiE;AACjE,MAAM,MAAM,oBAAoB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,IAAI,gBAAgB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,GAAG,CAAC,CA4B3H;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAE,SAAQ,cAAc,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;IACrL,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,kBAAkB;AAClB,MAAM,WAAW,iBAAiB,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM;IACvH;;;;;OAKG;IACH,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC/D,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,YAAY,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAA;IAC1E,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,iCAAiC;AACjC,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AA4GD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,SAAS,GAAE,MAAmC,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,CAmDxP;AAqBD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjK;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpK"}

package/output/core/test-support/testdata.js

@@ -0,0 +1,271 @@
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertCleanableEnvironment } from '../env.js';
+/**
+ * 声明一个测试数据脚本（**唯一正当的写法**）。
+ *
+ * ```ts
+ * // packages/server/testdata/03-system-config.ts
+ * import { defineTestData } from '@taicode/common-server/app'
+ * import type { server } from '../source/server' // 纯类型导入，无副作用
+ *
+ * export default defineTestData<typeof server>({
+ *   dependsOn: ['01-database'],
+ *   async load(ctx) { …插入样本数据… },
+ *   async cleanup(ctx) { …删掉自己插入的数据… },
+ * })
+ * ```
+ *
+ * 泛型写 `typeof server` 而不是逐个槽位：`ctx` 上的 `resources` / `config` / `clients` /
+ * `services` / `env` 类型一次到位。只想声明 `resources` 时也可以写
+ * `defineTestData<AccountResources>({ … })`（其余槽位退化为 `object`）。
+ *
+ * ## 它解决什么
+ *
+ * 命名导出 `load` 是**约定**，写错只在装载期才会暴露（少写 `load` = 启动直接失败）。
+ * `defineTestData` 把这份约定变成**定义期**就检查的东西：
+ *
+ * 1. **缺 `load` 当场报错**（不是等到 `discoverTestDataModules()` 扫描到它）；
+ * 2. **`dependsOn` 当场校验**（必须是字符串数组、不能有重复项；引用不存在的脚本 / 自依赖 /
+ *    环属于跨文件问题，仍在装载期由 `sortByDependencies()` 统一判定）；
+ * 3. **结果冻结**：脚本之间不会互相改写 `load` / `cleanup`（执行器拿到的就是定义时那份）。
+ *
+ * `ctx` 的类型由 `S` 一次性带进来：`defineTestData<typeof server>({ load(ctx) {…} })` 里
+ * `ctx.services` / `ctx.resources` / `ctx.config` 全部有类型，不需要每个脚本再手写
+ * `type Ctx = TestDataContext<…>`。
+ *
+ * ## 与「命名导出」的关系
+ *
+ * 两种写法都合法，`defineTestData` 只是把结构显式化：
+ *
+ * ```ts
+ * // 推荐：默认导出一个定义对象
+ * export default defineTestData<typeof server>({ load })
+ *
+ * // 等价：命名导出（旧写法，继续支持）
+ * export async function load(ctx: TestDataContext<AccountResources>) { … }
+ * export const dependsOn = ['01-database']
+ * ```
+ *
+ * 同一个文件里两者都有时，**默认导出优先**——避免「改了默认导出、命名导出还在生效」的歧义。
+ */
+export function defineTestData(definition) {
+    // 类型上 `load` 必填，但脚本是纯 JS 生态：运行期仍要挡一次（写错时在定义期就炸，而不是装载期）
+    const script = definition;
+    if (typeof script.load !== 'function') {
+        throw new Error('[testdata] defineTestData 缺少 load：必须导出 load(ctx)');
+    }
+    if (script.cleanup !== undefined && typeof script.cleanup !== 'function') {
+        throw new Error('[testdata] defineTestData 的 cleanup 必须是函数（不需要清理就不写）');
+    }
+    const dependsOn = script.dependsOn;
+    if (dependsOn === undefined) {
+        // `TestDataScriptOf<S, Env>` 是条件类型，裸泛型参数上无法自动归约；这里的结构已经由入参约束过
+        return Object.freeze({ load: definition.load, cleanup: definition.cleanup });
+    }
+    if (!Array.isArray(dependsOn) || dependsOn.some((item) => typeof item !== 'string' || item.length === 0)) {
+        throw new Error('[testdata] defineTestData 的 dependsOn 必须是非空字符串数组（引用其它脚本的去扩展名文件名）');
+    }
+    if (new Set(dependsOn).size !== dependsOn.length) {
+        throw new Error(`[testdata] defineTestData 的 dependsOn 有重复项：${dependsOn.join(', ')}`);
+    }
+    return Object.freeze({
+        load: definition.load,
+        cleanup: definition.cleanup,
+        dependsOn: Object.freeze([...dependsOn]),
+    });
+}
+/** 默认脚本目录（相对 `process.cwd()`） */
+export function resolveTestDataDirectory() {
+    return resolve(process.cwd(), DEFAULT_TESTDATA_DIRECTORY);
+}
+const DEFAULT_TESTDATA_DIRECTORY = 'testdata';
+/** 会被当作脚本的扩展名 */
+const TESTDATA_EXTENSIONS = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+/** `_` 前缀 = 共享 helper，不参与 load / cleanup */
+const HELPER_PREFIX = '_';
+function isTestDataFile(name) {
+    if (name.startsWith(HELPER_PREFIX)) {
+        return false;
+    }
+    // `.d.ts` 是纯声明，没有运行期实现
+    if (name.endsWith('.d.ts')) {
+        return false;
+    }
+    return TESTDATA_EXTENSIONS.includes(extname(name));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** 读一个脚本模块的 `dependsOn`（缺省 = 空数组；类型不对直接报错） */
+function readDependsOn(file, script) {
+    const value = script.dependsOn;
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`[testdata] "${file}" 的 dependsOn 必须是字符串数组（引用其它脚本的去扩展名文件名）`);
+    }
+    return value;
+}
+/**
+ * 从一个已 `import()` 的模块里取出脚本本体。
+ *
+ * **默认导出优先**：`export default defineTestData({ … })` 是推荐写法；同一个文件里还留着
+ * 命名导出时以默认导出为准，避免「改了默认导出、命名导出仍在生效」这种看不见的分裂。
+ */
+function readScript(file, loaded) {
+    const candidate = loaded.default;
+    if (isRecord(candidate) && typeof candidate.load === 'function') {
+        return candidate;
+    }
+    return loaded;
+}
+/**
+ * 按 `dependsOn` 做**稳定**拓扑排序（Kahn）：同层取文件名升序。
+ *
+ * 三个不变式：
+ * - **依赖是权威**：只要 A 声明依赖 B，A 一定排在 B 之后，文件名管不了它。
+ * - **同层可复现**：没有依赖关系的脚本按文件名升序，跑多少次都是同一个序。
+ * - **坏图直接报错**：未知依赖 / 自依赖 / 循环依赖都在装载期抛错，不猜顺序——
+ *   猜错只会变成偶发的外键冲突，比当场失败难查得多。
+ */
+function sortByDependencies(units) {
+    const known = new Set(units.map((unit) => unit.name));
+    const pending = new Map();
+    const dependents = new Map();
+    for (const unit of units) {
+        const deps = [...new Set(unit.dependsOn ?? [])];
+        for (const dep of deps) {
+            if (dep === unit.name) {
+                throw new Error(`[testdata] "${unit.name}" 依赖了自己：dependsOn 只能引用其它脚本`);
+            }
+            if (!known.has(dep)) {
+                throw new Error(`[testdata] "${unit.name}" 依赖的 "${dep}" 不存在：dependsOn 用去扩展名的文件名`);
+            }
+        }
+        pending.set(unit.name, deps.length);
+        for (const dep of deps) {
+            dependents.set(dep, [...(dependents.get(dep) ?? []), unit.name]);
+        }
+    }
+    // 候选池保持升序：同层先跑文件名小的
+    const ready = units.filter((unit) => pending.get(unit.name) === 0).map((unit) => unit.name).sort();
+    const order = [];
+    while (ready.length > 0) {
+        const name = ready.shift();
+        order.push(name);
+        for (const next of dependents.get(name) ?? []) {
+            const rest = (pending.get(next) ?? 0) - 1;
+            pending.set(next, rest);
+            if (rest === 0) {
+                ready.push(next);
+            }
+        }
+        ready.sort();
+    }
+    if (order.length !== units.length) {
+        const stuck = units.filter((unit) => !order.includes(unit.name)).map((unit) => unit.name);
+        throw new Error(`[testdata] 存在循环依赖：${stuck.join(' → ')}`);
+    }
+    return order.map((name) => units.find((unit) => unit.name === name));
+}
+/**
+ * 扫描目录并**装载**全部脚本（`import()` 一次，模块本身由 ESM 缓存复用）。
+ *
+ * 目录不存在 → 空数组（不是错误：没写测试数据的服务是合法的）。
+ * 文件存在但缺 `load` → **抛错**，并指出是哪个文件。
+ *
+ * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
+ * `cleanup` 直接逆序跑）。
+ */
+export async function discoverTestDataModules(directory = resolveTestDataDirectory()) {
+    let entries;
+    try {
+        entries = (await readdir(directory, { withFileTypes: true }))
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const files = entries.filter(isTestDataFile).sort();
+    const units = [];
+    for (const file of files) {
+        const name = basename(file, extname(file));
+        const moduleUrl = pathToFileURL(join(directory, file)).href;
+        let loaded;
+        try {
+            loaded = await import(moduleUrl);
+        }
+        catch (error) {
+            throw new Error(`[testdata] 装载 "${file}" 失败：${error instanceof Error ? error.message : String(error)}`, {
+                cause: error,
+            });
+        }
+        if (!isRecord(loaded)) {
+            throw new Error(`[testdata] "${file}" 没有导出任何东西：必须导出 load（或用 defineTestData 作为默认导出）`);
+        }
+        const script = readScript(file, loaded);
+        if (typeof script.load !== 'function') {
+            throw new Error(`[testdata] "${file}" 缺少 load 导出：必须导出 load(ctx)`);
+        }
+        if (script.cleanup !== undefined && typeof script.cleanup !== 'function') {
+            throw new Error(`[testdata] "${file}" 的 cleanup 必须是函数（不需要清理就删掉这个导出）`);
+        }
+        units.push({
+            name,
+            dependsOn: readDependsOn(file, script),
+            load: script.load,
+            cleanup: script.cleanup,
+        });
+    }
+    return sortByDependencies(units);
+}
+/** 跑一个脚本步骤（统一日志，失败冒泡给调用方决定） */
+async function runTestDataUnit(params, unit, phase) {
+    const step = unit[phase];
+    if (!step) {
+        // `cleanup` 可选：没写的脚本由资源单元的 `clean()` 兜底
+        return;
+    }
+    const fields = { service: params.service ?? '', unit: unit.name, stage: 'testdata', phase };
+    params.ctx.log.debug(fields, `[testdata] ${phase} "${unit.name}" start`);
+    try {
+        await step(params.ctx);
+        params.ctx.log.debug(fields, `[testdata] ${phase} "${unit.name}" done`);
+    }
+    catch (error) {
+        params.ctx.log.error({ ...fields, error }, `[testdata] ${phase} "${unit.name}" failed`);
+        throw error;
+    }
+}
+/**
+ * 加载测试数据：按**执行序**逐项 `await load(ctx)`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` / `startServer()` 装配完成后自动执行一次；也可以由测试自己再调。
+ */
+export async function loadTestData(params) {
+    // 闸门先于一切：非可清理环境下一个脚本都不许跑
+    assertCleanableEnvironment(params.ctx.env.ENV);
+    for (const unit of sortByDependencies(params.units ?? [])) {
+        await runTestDataUnit(params, unit, 'load');
+    }
+}
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。没有 `cleanup` 的脚本直接跳过。
+ *
+ * 注意：它只负责「把脚本插入的东西撤掉」，不是「把整个库清空」——库由资源单元的 `clean()` 清。
+ */
+export async function cleanupTestData(params) {
+    assertCleanableEnvironment(params.ctx.env.ENV);
+    for (const unit of sortByDependencies(params.units ?? []).reverse()) {
+        await runTestDataUnit(params, unit, 'cleanup');
+    }
+}

package/output/core/test-support/testdata.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testdata.test.d.ts.map

package/output/core/test-support/testdata.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testdata.test.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.test.ts"],"names":[],"mappings":""}