zentao-api 0.3.1 → 0.3.3

package/dist/modules/registry-store.js

@@ -0,0 +1,181 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isRecord } from '../utils/object.js';
+import { BUILTIN_MODULES } from './generated.js';
+// 动作类型到 HTTP 方法 / 结果形态的默认推导表：当动作未显式声明 method / resultType 时按 type 补齐。
+const METHOD_BY_TYPE = {
+    list: 'get',
+    get: 'get',
+    create: 'post',
+    update: 'put',
+    delete: 'delete',
+    action: 'post',
+};
+const RESULT_TYPE_BY_TYPE = {
+    list: 'list',
+    get: 'object',
+    create: 'object',
+    update: 'object',
+    delete: 'text',
+    action: 'text',
+};
+// 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
+// - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
+// - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
+//   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
+//
+// 该模块是「定义」（define）与「查询」（query）两侧共享的底层存储：
+// - define 侧通过 mutate* 系列函数维护状态，并复用 freeze/clone/merge/validate 原语；
+// - query 侧只读访问 modules / moduleMap。
+let modules = freezeModules(cloneBuiltinModules());
+let moduleMap = buildModuleMap(modules);
+export function deepClone(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => deepClone(item));
+    }
+    if (value && typeof value === 'object' && !(value instanceof Function)) {
+        const result = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            result[key] = deepClone(nestedValue);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * 深度合并：以 `patch` 覆盖 `base`，返回新对象，不修改任何入参。
+ *
+ * - 仅当两侧同为普通对象时递归合并；其余情况（含数组）由 `patch` 整体替换。
+ * - `patch` 中值为 `undefined` 的键会被跳过，因此扩展方只需给出待修改的字段。
+ * - 未被 `patch` 触及的嵌套值沿用 `base` 的引用（外层会重新深冻结，引用本就不可变）。
+ */
+export function deepMerge(base, patch) {
+    if (!isRecord(patch)) {
+        return (patch === undefined ? base : deepClone(patch));
+    }
+    const result = isRecord(base) ? { ...base } : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const current = result[key];
+        result[key] = isRecord(value) && isRecord(current) ? deepMerge(current, value) : deepClone(value);
+    }
+    return result;
+}
+export function cloneBuiltinModules() {
+    return deepClone(BUILTIN_MODULES);
+}
+export function deepFreeze(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    for (const key of Object.keys(value)) {
+        deepFreeze(value[key]);
+    }
+    return Object.freeze(value);
+}
+/**
+ * 按 {@link ModuleAction.type} 就地补齐省略的 `method` / `resultType`。
+ *
+ * 已显式声明的字段保持不变；当 `type` 无法推导出对应默认值时抛错，提示显式指定。
+ *
+ * @throws {ZentaoError} `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`
+ */
+export function normalizeAction(action) {
+    if (action.method === undefined) {
+        const method = METHOD_BY_TYPE[action.type];
+        if (method === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_METHOD', { action: String(action.name), type: String(action.type) });
+        }
+        action.method = method;
+    }
+    if (action.resultType === undefined) {
+        const resultType = RESULT_TYPE_BY_TYPE[action.type];
+        if (resultType === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_RESULT_TYPE', { action: String(action.name), type: String(action.type) });
+        }
+        action.resultType = resultType;
+    }
+    return action;
+}
+export function freezeAction(action) {
+    return deepFreeze(normalizeAction(action));
+}
+export function freezeModule(module) {
+    module.actions.forEach(freezeAction);
+    return deepFreeze(module);
+}
+export function freezeModules(source) {
+    source.forEach(freezeModule);
+    return source;
+}
+export function findActionIndex(source, actionName) {
+    const key = actionName.toLowerCase();
+    return source.findIndex((action) => String(action.name).toLowerCase() === key);
+}
+export function mergeActions(base, extension) {
+    const next = base.slice();
+    for (const action of extension) {
+        const index = findActionIndex(next, String(action.name));
+        const frozen = freezeAction(deepClone(action));
+        if (index >= 0) {
+            next[index] = frozen;
+        }
+        else {
+            next.push(frozen);
+        }
+    }
+    return next;
+}
+export function mergeModule(base, extension) {
+    return freezeModule({
+        ...base,
+        ...deepClone(extension),
+        actions: mergeActions(base.actions, extension.actions),
+    });
+}
+export function buildModuleMap(source) {
+    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
+}
+export function validateModule(module) {
+    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
+        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
+    }
+}
+export function validateAction(action) {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    // method / resultType 可省略（由 normalizeAction 按 type 推导），但显式给出时必须是字符串。
+    if (action.method !== undefined && typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    if (action.resultType !== undefined && typeof action.resultType !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+}
+/** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
+export function getModulesState() {
+    return modules;
+}
+/** 当前模块名（小写）到模块定义的查找表（O(1) 查询）。 */
+export function getModuleMapState() {
+    return moduleMap;
+}
+/** 依据当前 modules 重建 moduleMap。所有写入完成后调用以保持二者一致。 */
+export function rebuildModuleMap() {
+    moduleMap = buildModuleMap(modules);
+}
+// 重置后钩子：在 resetState 把状态还原为内置基线之后触发，
+// 用于让上层（barrel）重新应用内置覆盖（override），而无需 store / define 直接依赖 override。
+let postResetHook;
+/** 注册「重置后钩子」，在每次 {@link resetState} 还原内置基线后调用。 */
+export function setPostResetHook(hook) {
+    postResetHook = hook;
+}
+/** 将注册表重置为内置模块（深克隆 + 深冻结），重建查找表，并触发重置后钩子。 */
+export function resetState() {
+    modules = freezeModules(cloneBuiltinModules());
+    rebuildModuleMap();
+    postResetHook?.();
+}

package/dist/modules/registry.d.ts

@@ -1,5 +1,5 @@
-import type { ModuleAction, ModuleDefinition } from '../types/index.js';
 import { BUILTIN_MODULES } from './generated.js';
+import { applyBuiltinOverrides } from './override.js';
 export { BUILTIN_MODULES };
 export declare const MODULES: readonly [{
     readonly name: "user";
@@ -173,7 +173,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly userID: "用户ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "program";
@@ -354,7 +353,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly programID: "项目集ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "product";
@@ -579,7 +577,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly productID: "产品ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "project";
@@ -775,7 +772,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly projectID: "项目ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "execution";
@@ -1028,7 +1024,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly executionID: "执行ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "productplan";
@@ -1231,7 +1226,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly productplanID: "产品计划ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "story";
@@ -1479,7 +1473,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly storyID: "需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活需求";
@@ -1507,7 +1500,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更需求";
@@ -1547,7 +1539,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭需求";
@@ -1576,7 +1567,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "epic";
@@ -1809,7 +1799,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly epicID: "业务需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活业务需求";
@@ -1837,7 +1826,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更业务需求";
@@ -1877,7 +1865,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭业务需求";
@@ -1906,7 +1893,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "requirement";
@@ -2138,7 +2124,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly requirementID: "用户需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活用户需求";
@@ -2166,7 +2151,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更用户需求";
@@ -2198,7 +2182,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭用户需求";
@@ -2227,7 +2210,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "bug";
@@ -2465,7 +2447,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly bugID: "Bug ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活Bug";
@@ -2500,7 +2481,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭Bug";
@@ -2524,7 +2504,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "resolve";
         readonly display: "解决Bug";
@@ -2565,7 +2544,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["resolution"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testcase";
@@ -2816,7 +2794,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly testcasID: "测试用例ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "task";
@@ -3050,7 +3027,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly taskID: "任务ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活任务";
@@ -3083,7 +3059,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭任务";
@@ -3107,7 +3082,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "finish";
         readonly display: "完成任务";
@@ -3154,7 +3128,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["currentConsumed", "realStarted", "finishedDate"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "start";
         readonly display: "启动任务";
@@ -3197,7 +3170,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["realStarted"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "feedback";
@@ -3403,7 +3375,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly feedbackID: "反馈ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活反馈";
@@ -3431,7 +3402,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭反馈";
@@ -3460,7 +3430,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "ticket";
@@ -3682,7 +3651,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly ticketID: "工单ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活工单";
@@ -3710,7 +3678,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭工单";
@@ -3739,7 +3706,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason", "comment"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "system";
@@ -3992,7 +3958,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly buildID: "版本ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testtask";
@@ -4157,7 +4122,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly testtaskID: "测试单ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "release";
@@ -4290,7 +4254,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly releasID: "发布ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "file";
@@ -4327,87 +4290,8 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly fileID: "附件ID";
         };
-        readonly render: "action";
     }];
 }];
-/** {@link defineModules} 的选项。 */
-export interface DefineModulesOptions {
-    /**
-     * 同名模块的写入策略。
-     *
-     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
-     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
-     */
-    replace?: boolean;
-}
-/**
- * 注册或扩展模块定义。
- *
- * 行为细节：
- * - 模块名匹配大小写不敏感。
- * - 未知模块直接追加到注册表末尾。
- * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
- *   `options.replace` 为 `true` 时整体替换。
- * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
- *
- * @param input - 单个或一组模块定义。
- * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
- */
-export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
-/**
- * 为已存在的模块追加或覆盖动作。
- *
- * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
- *
- * @param moduleName - 目标模块名（大小写不敏感）。
- * @param input - 单个或一组动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path` / `method` 等必填字段）。
- */
-export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
-/**
- * 获取模块定义。
- *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
- * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
- *
- * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
- */
-export declare function getModule(moduleName: string): ModuleDefinition;
-/**
- * 获取指定模块下的某个动作。
- *
- * 解析顺序：
- * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
- * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
- *
- * 返回值同样是已深冻结的引用，请勿尝试修改。
- *
- * @param moduleName - 模块名（大小写不敏感）。
- * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
- */
-export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
-/**
- * 返回当前运行时注册表中的所有模块名。
- *
- * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
- *
- * @returns 模块名数组（保留原始大小写）。
- */
-export declare function getModuleNames(): string[];
-/**
- * 判断模块名是否已注册。
- *
- * @param moduleName - 模块名；匹配大小写不敏感。
- * @returns 已注册返回 `true`，否则 `false`。
- */
-export declare function isModuleName(moduleName: string): boolean;
-/** @internal */
-export declare function resetModuleDefinitions(): void;
+export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
+export { applyBuiltinOverrides };
+export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';