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

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/{app → core}/type-augment.d.ts

@@ -4,7 +4,7 @@
  * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
  * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
  */
-import type { RequestContext } from '../context/index.js';
+import type { RequestContext } from './modules/context/index.js';
 /** 路由级访问控制声明（各服务在 `routeOptions.config.accessControls` 里写） */
 export type AccessControl = 'NoLoginRequired' | 'IgnorePermission' | 'RequiredSecurityCode';
 /** 路由级限流规则（`createRateLimitMiddleware` 消费，另有路由级 `config.rateLimit`） */
@@ -21,7 +21,7 @@ declare module 'fastify' {
         user?: unknown;
         /** 认证后由 `auth` 中间件填充 */
         token?: unknown;
-        /** `createContextMiddleware()` 注入的请求级上下文 */
+        /** 由 core 固定注入的请求级上下文（`registerRequestContext`） */
         ctx?: RequestContext;
     }
     interface FastifyContextConfig {

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