@taicode/common-server 4.0.0-beta.5 → 4.0.0-beta.6

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

@@ -0,0 +1,202 @@
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertCleanableEnvironment } from '../env.js';
+/** 默认脚本目录（相对 `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, loaded) {
+    const value = loaded.dependsOn;
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`[testdata] "${file}" 的 dependsOn 必须是字符串数组（引用其它脚本的去扩展名文件名）`);
+    }
+    return value;
+}
+/**
+ * 按 `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` / `cleanup` 缺一个 → **抛错**，并指出是哪个文件缺哪个方法。
+ *
+ * 返回的顺序就是**执行序**：`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 与 cleanup`);
+        }
+        if (typeof loaded.load !== 'function') {
+            throw new Error(`[testdata] "${file}" 缺少 load 导出：load 与 cleanup 两个都必须有`);
+        }
+        if (typeof loaded.cleanup !== 'function') {
+            throw new Error(`[testdata] "${file}" 缺少 cleanup 导出：load 与 cleanup 两个都必须有`);
+        }
+        units.push({
+            name,
+            dependsOn: readDependsOn(file, loaded),
+            load: loaded.load,
+            cleanup: loaded.cleanup,
+        });
+    }
+    return sortByDependencies(units);
+}
+/** 跑一个脚本步骤（统一日志，失败冒泡给调用方决定） */
+async function runTestDataUnit(params, unit, phase) {
+    const fields = { service: params.service ?? '', unit: unit.name, stage: 'testdata', phase };
+    params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" start`);
+    try {
+        await unit[phase]();
+        params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" done`);
+    }
+    catch (error) {
+        params.log?.error({ ...fields, error }, `[testdata] ${phase} "${unit.name}" failed`);
+        throw error;
+    }
+}
+/**
+ * 加载测试数据：按**执行序**逐项 `await load()`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` 装配完成（`ready()` 之后）自动执行一次；也可以由测试自己再调。
+ */
+export async function loadTestData(params) {
+    // 闸门先于一切：非可清理环境下一个脚本都不许跑
+    assertCleanableEnvironment(params.env);
+    for (const unit of sortByDependencies(params.units ?? [])) {
+        await runTestDataUnit(params, unit, 'load');
+    }
+}
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。
+ *
+ * 单独调用它的场景很少（多半是要 `resetTestData`）：它与 `loadTestData` 成对，
+ * 语义是「把脚本插入的数据撤掉」，而不是「把整个库清空」。
+ */
+export async function cleanupTestData(params) {
+    assertCleanableEnvironment(params.env);
+    for (const unit of sortByDependencies(params.units ?? []).reverse()) {
+        await runTestDataUnit(params, unit, 'cleanup');
+    }
+}
+/**
+ * 重置测试数据：先**整体** `cleanup`（逆序），再**整体** `load`（正序）。
+ *
+ * 这是 `beforeEach` 的标准动作（`TestServer.resetTestData()` 的底层实现）：
+ * 先全部撤掉再全部重建，而不是「逐脚本 cleanup + load」——后者会让前一个脚本重新插入的数据
+ * 被后一个脚本的 `cleanup` 顺手删掉（顺序依赖）。分两趟就没有这个问题。
+ *
+ * ## 两点与「安全」有关的说明
+ *
+ * - **先在清理阶段**：万一 `load` 失败，库里留下的是「干净」而不是「半套数据 + 半套旧数据」。
+ * - **闸门只判一次**（三个入口各自开头），不做逐脚本判定：同一批脚本在同一环境里跑，
+ *   逐个判只是把一次判定复制 N 次。
+ */
+export async function resetTestData(params) {
+    assertCleanableEnvironment(params.env);
+    const units = sortByDependencies(params.units ?? []);
+    for (const unit of [...units].reverse()) {
+        await runTestDataUnit(params, unit, 'cleanup');
+    }
+    for (const unit of units) {
+        await runTestDataUnit(params, unit, 'load');
+    }
+}

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,220 @@
+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, discoverTestDataModules, loadTestData, resetTestData, 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 导出直接抛错（只写 load 的脚本等于「数据删不掉」）', async () => {
+        const dir = await makeDirectory({
+            '01-bad.mjs': 'export function load() {}',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/缺少 cleanup 导出/);
+    });
+    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 必须是字符串数组/);
+    });
+});
+/** 造一批内存脚本单元（不经磁盘，专测执行语义） */
+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({ env: 'test', units });
+        expect(order).toEqual(['load:a', 'load:b', 'load:c']);
+        order.length = 0;
+        await cleanupTestData({ env: 'test', units });
+        expect(order).toEqual(['cleanup:c', 'cleanup:b', 'cleanup:a']);
+    });
+    it('reset 先整体 cleanup（逆序）再整体 load（正序）', async () => {
+        const order = [];
+        const units = unitsOf(order, ['a', 'b']);
+        await resetTestData({ env: 'test', units });
+        // 分两趟而不是「逐脚本 cleanup + load」：后者会让前一个脚本刚插入的数据
+        // 被后一个脚本的 cleanup 顺手删掉（顺序依赖）。
+        expect(order).toEqual(['cleanup:b', 'cleanup:a', 'load:a', 'load:b']);
+    });
+    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({ env: 'test', units });
+        expect(order).toEqual(['load:early', 'load:late']);
+        order.length = 0;
+        await cleanupTestData({ env: 'test', units });
+        expect(order).toEqual(['cleanup:late', 'cleanup:early']);
+    });
+    it('没有脚本时三个入口都是空操作（但闸门照样生效）', async () => {
+        await expect(loadTestData({ env: 'test' })).resolves.toBeUndefined();
+        await expect(cleanupTestData({ env: 'development' })).resolves.toBeUndefined();
+        await expect(resetTestData({ env: 'test' })).resolves.toBeUndefined();
+    });
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+        ['resetTestData', resetTestData],
+    ])('%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({ env: 'test', units })).rejects.toThrow(/failed/);
+    });
+});
+describe('testdata 的环境闸门', () => {
+    const units = (order) => unitsOf(order, ['a']);
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+        ['resetTestData', resetTestData],
+    ])('%s：非可清理环境一个脚本都不跑', async (_name, run) => {
+        const order = [];
+        await expect(run({ env: 'production', units: units(order) })).rejects.toThrow(/拒绝在 ENV=/);
+        expect(order).toEqual([]);
+    });
+    it.each(['production', 'staging', ''])('ENV=%s 时拒绝，报错带上当前值', async (env) => {
+        await expect(loadTestData({ env })).rejects.toThrow(/ENV="/);
+    });
+    it.each(['development', 'test'])('ENV=%s 时放行', async (env) => {
+        const order = [];
+        await loadTestData({ env, units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+    it('闸门先于一切：没有脚本也要在非可清理环境下失败', async () => {
+        await expect(resetTestData({ env: 'production' })).rejects.toThrow(/ENV="production"/);
+    });
+    it('判据是传入的 env 参数，不是 process.env（事后改写不影响结论）', async () => {
+        const order = [];
+        process.env.ENV = 'production';
+        await loadTestData({ env: 'test', units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+});
+describe('resolveTestDataDirectory', () => {
+    it('默认是 <cwd>/testdata', () => {
+        expect(resolveTestDataDirectory()).toBe(join(process.cwd(), 'testdata'));
+    });
+});