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

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":""}

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

@@ -0,0 +1,334 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanupTestData, defineTestData, discoverTestDataModules, loadTestData, resolveTestDataDirectory } from './testdata.js';
+const ORIGINAL_ENV = { ...process.env };
+const tempDirs = [];
+afterEach(async () => {
+    process.env = { ...ORIGINAL_ENV };
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+/** 造一个临时脚本目录（内容按 `文件名 → 模块源码` 写入） */
+async function makeDirectory(files) {
+    const dir = await mkdtemp(join(tmpdir(), 'common-testdata-'));
+    tempDirs.push(dir);
+    await Promise.all(Object.entries(files).map(([name, source]) => writeFile(join(dir, name), source)));
+    return dir;
+}
+/** 造一个记录调用顺序的脚本源码（模块级数组挂在 globalThis 上，跨 import 共享） */
+function scriptSource(name, recorder) {
+    return `
+const record = (phase) => globalThis.${recorder}.push(\`\${phase}:${name}\`)
+export function load() { record('load') }
+export function cleanup() { record('cleanup') }
+`;
+}
+describe('discoverTestDataModules', () => {
+    it('目录不存在时返回空数组（没写测试数据的服务是合法的）', async () => {
+        const dir = join(tmpdir(), `common-testdata-missing-${Date.now()}`);
+        await expect(discoverTestDataModules(dir)).resolves.toEqual([]);
+    });
+    it('按文件名升序装载，name 为去扩展名的文件名', async () => {
+        const dir = await makeDirectory({
+            '02-second.mjs': scriptSource('second', '__order02'),
+            '01-first.mjs': scriptSource('first', '__order01'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-first', '02-second']);
+        expect(units.every((unit) => typeof unit.load === 'function' && typeof unit.cleanup === 'function')).toBe(true);
+    });
+    it('`_` 开头的文件是共享 helper，不参与 load / cleanup', async () => {
+        const dir = await makeDirectory({
+            '_shared.mjs': 'export const helper = 1',
+            '01-real.mjs': scriptSource('real', '__orderShared'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-real']);
+    });
+    it('非脚本文件（.md / .json / .d.ts）被忽略', async () => {
+        const dir = await makeDirectory({
+            'README.md': '# 说明',
+            'data.json': '{}',
+            'types.d.ts': 'export declare function load(): void',
+            '01-real.mjs': scriptSource('real', '__orderIgnore'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-real']);
+    });
+    it('缺 cleanup 不报错（库里的行由资源单元的 clean() 兜底）', async () => {
+        const dir = await makeDirectory({
+            '01-plain.mjs': 'export function load() { globalThis.__orderNoCleanup.push(\'load\') }',
+        });
+        const order = globalThis.__orderNoCleanup = [];
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-plain']);
+        expect(units[0]?.cleanup).toBeUndefined();
+        // `load` 照跑，`cleanup` 直接跳过（不是报错）
+        await loadTestData({ ctx: makeCtx('test'), units });
+        await cleanupTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['load']);
+    });
+    it('缺 load 导出直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-bad.mjs': 'export function cleanup() {}',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/缺少 load 导出/);
+    });
+    it('装载期抛错时带上文件名（定位不要靠猜）', async () => {
+        const dir = await makeDirectory({
+            '01-broken.mjs': 'throw new Error("boom")',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/装载 "01-broken.mjs" 失败/);
+    });
+    it('dependsOn 缺省时按文件名升序', async () => {
+        const dir = await makeDirectory({
+            '02-b.mjs': scriptSource('b', '__orderNoDep'),
+            '01-a.mjs': scriptSource('a', '__orderNoDep'),
+        });
+        await expect(discoverTestDataModules(dir)).resolves.toMatchObject([{ name: '01-a' }, { name: '02-b' }]);
+    });
+    it('dependsOn 决定顺序：依赖在前，文件名管不了它', async () => {
+        const dir = await makeDirectory({
+            '01-late.mjs': `export const dependsOn = ['99-early']\n${scriptSource('late', '__orderDep')}`,
+            '99-early.mjs': scriptSource('early', '__orderDep'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['99-early', '01-late']);
+    });
+    it('同层按文件名升序（无依赖关系的脚本可复现）', async () => {
+        const dir = await makeDirectory({
+            '03-c.mjs': `export const dependsOn = ['01-base']\n${scriptSource('c', '__orderTie')}`,
+            '02-b.mjs': `export const dependsOn = ['01-base']\n${scriptSource('b', '__orderTie')}`,
+            '01-base.mjs': scriptSource('base', '__orderTie'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-base', '02-b', '03-c']);
+    });
+    it('依赖不存在的脚本直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['99-missing']\n${scriptSource('a', '__orderMissing')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/依赖的 "99-missing" 不存在/);
+    });
+    it('依赖自己直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['01-a']\n${scriptSource('a', '__orderSelf')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/依赖了自己/);
+    });
+    it('循环依赖直接抛错（不猜顺序）', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['02-b']\n${scriptSource('a', '__orderCycle')}`,
+            '02-b.mjs': `export const dependsOn = ['01-a']\n${scriptSource('b', '__orderCycle')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/循环依赖/);
+    });
+    it('dependsOn 不是字符串数组直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = [1]\n${scriptSource('a', '__orderType')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/dependsOn 必须是字符串数组/);
+    });
+    it('`export default { load, cleanup }` 也是合法写法（定义对象直接可用）', async () => {
+        const dir = await makeDirectory({
+            '01-default.mjs': `
+export default {
+  dependsOn: ['01-default'],
+  load() {},
+  cleanup() {},
+}
+`,
+        });
+        // 自依赖应被排序器拦下：证明默认导出的 dependsOn 确实被读到了
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/依赖了自己/);
+    });
+    it('默认导出优先于同名命名导出（不留「改了默认导出、旧导出还生效」的歧义）', async () => {
+        const dir = await makeDirectory({
+            '01-both.mjs': `
+export default { load() { globalThis.__orderBoth.push('load:default') }, cleanup() {} }
+export function load() { globalThis.__orderBoth.push('load:named') }
+export function cleanup() {}
+`,
+        });
+        const order = globalThis.__orderBoth = [];
+        const units = await discoverTestDataModules(dir);
+        await loadTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['load:default']);
+    });
+});
+describe('defineTestData', () => {
+    it('原样返回 load / cleanup，并保留 dependsOn', () => {
+        const load = () => { };
+        const cleanup = () => { };
+        const script = defineTestData({ dependsOn: ['01-database'], load, cleanup });
+        expect(script.load).toBe(load);
+        expect(script.cleanup).toBe(cleanup);
+        expect(script.dependsOn).toEqual(['01-database']);
+    });
+    it('没有 dependsOn 时结果里没有这个字段', () => {
+        expect(defineTestData({ load: () => { } })).not.toHaveProperty('dependsOn');
+    });
+    it('缺 load 直接抛错（定义期就发现，而不是装载期）', () => {
+        expect(() => defineTestData({ cleanup: () => { } })).toThrow(/缺少 load/);
+    });
+    it('不写 cleanup 是合法的（库里那半由资源单元划掉）', () => {
+        const script = defineTestData({ load: () => { } });
+        expect(script.cleanup).toBeUndefined();
+    });
+    it('cleanup 写了但不是函数则抛错（写错了不要静默跣过）', () => {
+        expect(() => defineTestData({ load: () => { }, cleanup: 'yes' })).toThrow(/cleanup 必须是函数/);
+    });
+    it('dependsOn 不是字符串数组直接抛错', () => {
+        expect(() => defineTestData({ dependsOn: [1], load: () => { }, cleanup: () => { } })).toThrow(/非空字符串数组/);
+    });
+    it('dependsOn 含空字符串直接抛错（空名指不到任何脚本）', () => {
+        expect(() => defineTestData({ dependsOn: [''], load: () => { }, cleanup: () => { } })).toThrow(/非空字符串数组/);
+    });
+    it('dependsOn 重复项直接抛错（重复声明没有意义，多半是写错）', () => {
+        expect(() => defineTestData({ dependsOn: ['01-a', '01-a'], load: () => { }, cleanup: () => { } })).toThrow(/重复项/);
+    });
+    it('结果冻结：外部改不动 load / cleanup / dependsOn', () => {
+        const script = defineTestData({ dependsOn: ['01-a'], load: () => { }, cleanup: () => { } });
+        expect(Object.isFrozen(script)).toBe(true);
+        expect(Object.isFrozen(script.dependsOn)).toBe(true);
+    });
+    it('泛型写 typeof server 时 ctx 带上全部槽位的类型', async () => {
+        const calls = [];
+        const script = defineTestData({
+            load(ctx) {
+                // 五个字段都有类型：写错（如 services.user.remove）会在 tsc 阶段报错
+                calls.push(ctx.resources.database.marker, String(ctx.config.feature), ctx.env.FOO ?? 'none');
+                ctx.clients.webhook.send();
+                ctx.services.user.create();
+            },
+            cleanup() { },
+        });
+        // 类型正确还不够：真跑一遍，确认运行时拿到的就是这些字段
+        await script.load({
+            env: { ENV: 'test' },
+            resources: { database: { marker: 'db' } },
+            config: { feature: true },
+            clients: { webhook: { send: () => { calls.push('webhook'); } } },
+            services: { user: { create: () => { calls.push('user'); } } },
+            log: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+        });
+        expect(calls).toEqual(['db', 'true', 'none', 'webhook', 'user']);
+    });
+});
+/** 造一个最小 ctx（`resources` 用不着时给空对象；`log` 静默） */
+function makeCtx(env, resources = {}) {
+    return {
+        env: { ENV: env },
+        resources: resources,
+        config: {},
+        clients: {},
+        services: {},
+        log: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+    };
+}
+/** 造一批内存脚本单元（不经磁盘，专测执行语义） */
+function unitsOf(order, names) {
+    return names.map((name) => ({
+        name,
+        load: () => {
+            order.push(`load:${name}`);
+        },
+        cleanup: () => {
+            order.push(`cleanup:${name}`);
+        },
+    }));
+}
+describe('testdata 执行语义', () => {
+    it('load 正序、cleanup 逆序', async () => {
+        const order = [];
+        const units = unitsOf(order, ['a', 'b', 'c']);
+        await loadTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['load:a', 'load:b', 'load:c']);
+        order.length = 0;
+        await cleanupTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['cleanup:c', 'cleanup:b', 'cleanup:a']);
+    });
+    it('先整体 cleanup（逆序）再整体 load（正序）就是一次干净基线', async () => {
+        const order = [];
+        const units = unitsOf(order, ['a', 'b']);
+        // `TestServer.reprovision()` 就是这两步的顺序：先拆干净，再重建
+        await cleanupTestData({ ctx: makeCtx('test'), units });
+        await loadTestData({ ctx: makeCtx('test'), units });
+        // 分两趟而不是「逐脚本 cleanup + load」：后者会让前一个脚本刚插入的数据
+        // 被后一个脚本的 cleanup 顺手删掉（顺序依赖）。
+        expect(order).toEqual(['cleanup:b', 'cleanup:a', 'load:a', 'load:b']);
+    });
+    it('每个脚本收到的就是同一个 ctx（env / resources / log 都是装配产物）', async () => {
+        const seen = [];
+        const resources = { database: { marker: 'live-db' } };
+        const ctx = makeCtx('test', resources);
+        const units = [
+            { name: 'a', load: (received) => { seen.push(received); }, cleanup: () => { } },
+        ];
+        await loadTestData({ ctx, units });
+        // 同一个对象：脚本里 `ctx.resources.database` 就是被测服务用的那个实例，不是副本
+        expect(seen[0]).toBe(ctx);
+        expect(seen[0].resources.database).toBe(resources.database);
+    });
+    it('执行器自己按 dependsOn 定序，不信任调用方传入的顺序', async () => {
+        const order = [];
+        const units = [
+            { name: '01-late', dependsOn: ['99-early'], load: () => { order.push('load:late'); }, cleanup: () => { order.push('cleanup:late'); } },
+            { name: '99-early', load: () => { order.push('load:early'); }, cleanup: () => { order.push('cleanup:early'); } },
+        ];
+        await loadTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['load:early', 'load:late']);
+        order.length = 0;
+        await cleanupTestData({ ctx: makeCtx('test'), units });
+        expect(order).toEqual(['cleanup:late', 'cleanup:early']);
+    });
+    it('没有脚本时两个入口都是空操作（但闸门照样生效）', async () => {
+        await expect(loadTestData({ ctx: makeCtx('test') })).resolves.toBeUndefined();
+        await expect(cleanupTestData({ ctx: makeCtx('development') })).resolves.toBeUndefined();
+    });
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+    ])('%s：脚本失败直接冒泡（不降级成「跳过这条」）', async (_name, run) => {
+        const order = [];
+        const units = [
+            { name: 'ok', load: () => { order.push('load:ok'); }, cleanup: () => { order.push('cleanup:ok'); } },
+            { name: 'broken', load: () => { throw new Error('insert failed'); }, cleanup: () => { throw new Error('delete failed'); } },
+        ];
+        await expect(run({ ctx: makeCtx('test'), units })).rejects.toThrow(/failed/);
+    });
+});
+describe('testdata 的环境闸门', () => {
+    const units = (order) => unitsOf(order, ['a']);
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+    ])('%s：非可清理环境一个脚本都不跑', async (_name, run) => {
+        const order = [];
+        await expect(run({ ctx: makeCtx('production'), units: units(order) })).rejects.toThrow(/拒绝在 ENV=/);
+        expect(order).toEqual([]);
+    });
+    it.each(['production', 'staging', ''])('ENV=%s 时拒绝，报错带上当前值', async (env) => {
+        await expect(loadTestData({ ctx: makeCtx(env) })).rejects.toThrow(/ENV="/);
+    });
+    it.each(['development', 'test'])('ENV=%s 时放行', async (env) => {
+        const order = [];
+        await loadTestData({ ctx: makeCtx(env), units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+    it('闸门先于一切：没有脚本也要在非可清理环境下失败', async () => {
+        await expect(cleanupTestData({ ctx: makeCtx('production') })).rejects.toThrow(/ENV="production"/);
+    });
+    it('判据是 ctx.env 快照，不是 process.env（事后改写不影响结论）', async () => {
+        const order = [];
+        process.env.ENV = 'production';
+        await loadTestData({ ctx: makeCtx('test'), units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+});
+describe('resolveTestDataDirectory', () => {
+    it('默认是 <cwd>/testdata', () => {
+        expect(resolveTestDataDirectory()).toBe(join(process.cwd(), 'testdata'));
+    });
+});

package/output/core/type-augment.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 框架统一提供的类型增强（设计 §8「类型增强」红线）。
+ *
+ * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
+ * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
+ */
+import type { RequestContext } from './modules/context/index.js';
+/** 路由级访问控制声明（各服务在 `routeOptions.config.accessControls` 里写） */
+export type AccessControl = 'NoLoginRequired' | 'IgnorePermission' | 'RequiredSecurityCode';
+/** 路由级限流规则（`createRateLimitMiddleware` 消费，另有路由级 `config.rateLimit`） */
+export interface RateLimitRule {
+    limit: number;
+    /** 窗口大小（秒） */
+    window: number;
+    /** 限流键维度，默认 `['ip']` */
+    keys?: string[];
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** 认证后由 `auth` 中间件填充 */
+        user?: unknown;
+        /** 认证后由 `auth` 中间件填充 */
+        token?: unknown;
+        /** 由 core 固定注入的请求级上下文（`registerRequestContext`） */
+        ctx?: RequestContext;
+    }
+    interface FastifyContextConfig {
+        /** 路由级访问控制（`NoLoginRequired` / `IgnorePermission` / `RequiredSecurityCode`） */
+        accessControls?: AccessControl[];
+        /** 路由级限流规则 */
+        rateLimit?: RateLimitRule;
+    }
+}
+//# sourceMappingURL=type-augment.d.ts.map

package/output/core/type-augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-augment.d.ts","sourceRoot":"","sources":["../../source/core/type-augment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,sBAAsB,CAAA;AAE3F,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc;IACd,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,wBAAwB;QACxB,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,wBAAwB;QACxB,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,mDAAmD;QACnD,GAAG,CAAC,EAAE,cAAc,CAAA;KACrB;IAED,UAAU,oBAAoB;QAC5B,+EAA+E;QAC/E,cAAc,CAAC,EAAE,aAAa,EAAE,CAAA;QAChC,cAAc;QACd,SAAS,CAAC,EAAE,aAAa,CAAA;KAC1B;CACF"}

package/output/core/type-augment.js

@@ -0,0 +1,7 @@
+/**
+ * 框架统一提供的类型增强（设计 §8「类型增强」红线）。
+ *
+ * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
+ * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
+ */
+export {};