tcdona_unilib 1.0.0 → 1.0.2

package/staticMeta/eff.ts

@@ -0,0 +1,203 @@
+/**
+ * Eff 框架：基于 Result 的异步任务管理
+ * - root/create：创建异步任务
+ * - all/any/race/allSettled：并行或竞速执行多个任务
+ * - Signal 传播：支持任务取消和自动清理
+ */
+import type { Result } from 'neverthrow';
+import { err, ok, ResultAsync } from 'neverthrow';
+
+export interface EffContext { signal: AbortSignal }
+
+type EffExecutor<T, E> = (ctx: EffContext) => PromiseLike<Result<T, E>>;
+type NonEmptyArray<T> = readonly [T, ...T[]];
+
+const ABORT_REASON = { SETTLED: 'settled', COMPLETED: 'completed' } as const;
+const noop = () => {};
+
+/**
+ * 将父 signal abort 传播到子 controller，返回解绑函数
+ */
+const linkSignal = (
+    parentSignal: AbortSignal,
+    controller: AbortController,
+): (() => void) => {
+    if (parentSignal.aborted) {
+        controller.abort(parentSignal.reason);
+        return noop;
+    }
+    const handler = () => controller.abort(parentSignal.reason);
+    parentSignal.addEventListener('abort', handler, { once: true });
+    return () => parentSignal.removeEventListener('abort', handler);
+};
+
+/**
+ * 并行运行多个任务，通过回调函数允许调用方控制何时 settle
+ */
+const runAll = <T, E>(
+    executors: NonEmptyArray<EffExecutor<T, E>>,
+    parentSignal: AbortSignal,
+    onResult: (
+        result: Result<T, E>,
+        index: number,
+        settle: (r: Result<unknown, unknown>) => void,
+        context: {
+            resultCount: number;
+            okValues: T[];
+            errValues: E[];
+            allResults: Result<T, E>[];
+        },
+    ) => void,
+): ResultAsync<unknown, unknown> =>
+    Eff.create(({ signal }) => {
+        const controller = new AbortController();
+        const childSignal = controller.signal;
+        const unlink = linkSignal(signal, controller);
+
+        return new Promise((resolve) => {
+            let done = false;
+            const context = {
+                resultCount: 0,
+                okValues: [] as T[],
+                errValues: [] as E[],
+                allResults: [] as Result<T, E>[],
+            };
+
+            const settle = (r: Result<unknown, unknown>) => {
+                if (done) return;
+                done = true;
+                unlink();
+                controller.abort(ABORT_REASON.SETTLED);
+                resolve(r);
+            };
+
+            if (signal.aborted) {
+                settle(ok([]));
+                return;
+            }
+
+            let remaining = executors.length;
+
+            executors.forEach((executor, i) => {
+                Eff.create(executor, childSignal).then((r) => {
+                    if (done) return;
+                    remaining--;
+                    onResult(r, i, settle, context);
+                    if (remaining === 0) settle(ok(context.allResults));
+                });
+            });
+        });
+    }, parentSignal);
+
+export class Eff {
+    /**
+     * 创建根级任务（无父 signal）
+     */
+    static root<T, E>(executor: EffExecutor<T, E>): ResultAsync<T, E> {
+        const controller = new AbortController();
+        const promise: Promise<Result<T, E>> = Promise.resolve()
+            .then(() => executor({ signal: controller.signal }))
+            .catch((e) => err(e as E))
+            .finally(() => controller.abort(ABORT_REASON.COMPLETED));
+        return new ResultAsync(promise);
+    }
+
+    /**
+     * 创建子任务（继承父 signal，支持取消传播）
+     */
+    static create<T, E>(
+        executor: EffExecutor<T, E>,
+        parentSignal: AbortSignal,
+    ): ResultAsync<T, E> {
+        const controller = new AbortController();
+        const unlink = linkSignal(parentSignal, controller);
+
+        const promise: Promise<Result<T, E>> = Promise.resolve()
+            .then(() => executor({ signal: controller.signal }))
+            .catch((e) => err(e as E))
+            .finally(() => {
+                unlink();
+                controller.abort(ABORT_REASON.COMPLETED);
+            });
+
+        return new ResultAsync(promise);
+    }
+
+    /**
+     * 全部成功才成功，任一失败立即失败并 abort 其他
+     */
+    static all<T, E>(
+        executors: NonEmptyArray<EffExecutor<T, E>>,
+        parentSignal: AbortSignal,
+    ): ResultAsync<T[], E> {
+        return runAll<T, E>(
+            executors,
+            parentSignal,
+            (result, index, settle, context) => {
+                result.match(
+                    (v) => {
+                        context.okValues[index] = v;
+                        context.resultCount++;
+                        if (context.resultCount === executors.length) {
+                            settle(ok(context.okValues));
+                        }
+                    },
+                    (e) => settle(err(e)),
+                );
+            },
+        ) as ResultAsync<T[], E>;
+    }
+
+    /**
+     * 任一成功立即成功并 abort 其他，全部失败才失败
+     */
+    static any<T, E>(
+        executors: NonEmptyArray<EffExecutor<T, E>>,
+        parentSignal: AbortSignal,
+    ): ResultAsync<T, E[]> {
+        return runAll<T, E>(
+            executors,
+            parentSignal,
+            (result, index, settle, context) => {
+                result.match(
+                    (v) => settle(ok(v)),
+                    (e) => {
+                        context.errValues[index] = e;
+                        context.resultCount++;
+                        if (context.resultCount === executors.length) {
+                            settle(err(context.errValues));
+                        }
+                    },
+                );
+            },
+        ) as ResultAsync<T, E[]>;
+    }
+
+    /**
+     * 任一完成立即返回其结果并 abort 其他
+     */
+    static race<T, E>(
+        executors: NonEmptyArray<EffExecutor<T, E>>,
+        parentSignal: AbortSignal,
+    ): ResultAsync<T, E> {
+        return runAll<T, E>(executors, parentSignal, (result, _index, settle) => {
+            settle(result);
+        }) as ResultAsync<T, E>;
+    }
+
+    /**
+     * 等待全部完成，收集所有结果（不因某个失败而 abort）
+     */
+    static allSettled<T, E>(
+        executors: NonEmptyArray<EffExecutor<T, E>>,
+        parentSignal: AbortSignal,
+    ): ResultAsync<Result<T, E>[], never> {
+        return runAll<T, E>(
+            executors,
+            parentSignal,
+            (result, index, _settle, context) => {
+                context.allResults[index] = result;
+            },
+        ) as ResultAsync<Result<T, E>[], never>;
+    }
+}

package/staticMeta/enum.api.ts

@@ -0,0 +1,142 @@
+/**
+ * 日志和错误处理 API：基于文件路径和事件 ID 生成统一的日志前缀
+ */
+
+// ==================== 日志配置 ====================
+
+const cons = console;
+
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4,
+}
+
+const logLevelUsed = LogLevel.INFO;
+
+const logFnMap: Record<LogLevel, (...args: unknown[]) => void> = {
+    [LogLevel.DEBUG]: cons.debug,
+    [LogLevel.INFO]: cons.log,
+    [LogLevel.WARN]: cons.warn,
+    [LogLevel.ERROR]: cons.error,
+    [LogLevel.FATAL]: cons.error,
+};
+
+// ==================== 日志链类型 ====================
+
+export interface TcLog {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    fatal: (...args: unknown[]) => void;
+}
+
+// ==================== 新的 fileId 配置类型 ====================
+
+/**
+ * fileId 的配置对象：包含事件 ID、源文件、标签
+ */
+export interface FileIdConf {
+    id: string; // 事件标识 key
+    srcFile: string; // 源文件路径
+    tag: string[]; // 标签数组（必须）
+}
+
+/**
+ * fileId：包含配置和日志方法（info, warn, error, debug）
+ */
+export interface FileId {
+    readonly conf: FileIdConf;
+
+    // 日志方法
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+
+/**
+ * 生成格式为 YYMMDD-HHmmss 的时间戳
+ */
+const getTimestamp = (): string => {
+    const now = new Date();
+    const yy = String(now.getFullYear()).slice(-2).padStart(2, '0');
+    const mm = String(now.getMonth() + 1).padStart(2, '0');
+    const dd = String(now.getDate()).padStart(2, '0');
+    const hh = String(now.getHours()).padStart(2, '0');
+    const min = String(now.getMinutes()).padStart(2, '0');
+    const ss = String(now.getSeconds()).padStart(2, '0');
+    return `${yy}${mm}${dd}-${hh}${min}${ss}`;
+};
+
+export class TcErr extends Error {
+    public fildId: FileId;
+    public ctx: Record<string, unknown>;
+    public cause?: Error; // 显式声明 cause 属性
+
+    constructor(
+        ctx: { fildId: FileId; cause?: unknown } & Record<string, unknown>,
+    ) {
+        const { fildId, cause, ...rest } = ctx;
+        super(fildId.conf?.id ?? 'TcErrId');
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'TcErr';
+        this.fildId = fildId;
+        if (cause) {
+            this.cause = cause as Error;
+        }
+        this.ctx = rest;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TcErr);
+        }
+
+        cons.error(getTimestamp(), fildId, cause, rest);
+    }
+}
+
+// ==================== 内部日志函数工厂 ====================
+
+const createLogFn = (
+    level: LogLevel,
+    prefix: string,
+): ((...args: unknown[]) => void) => {
+    if (level < logLevelUsed) return () => { };
+
+    const logFn = logFnMap[level] ?? (() => { });
+    return logFn.bind(null, `${getTimestamp()} ${prefix}`);
+};
+
+// ==================== 新的 fileInit API ====================
+
+/**
+ * 工厂函数类型：接收事件 ID 和可选标签，返回 FileId
+ */
+export type fileIdFactory = (id: string, ...tag: string[]) => FileId;
+
+/**
+ * 为模块创建 fileId 工厂函数
+ * @param modulePath 模块路径（相对路径字符串）
+ */
+export function fileInit(modulePath: string): fileIdFactory {
+    return (id: string, ...tag: string[]): FileId => {
+        const prefix = `[${modulePath}:${id}]${tag.length > 0 ? `[${tag.join(', ')}]` : ''}`;
+
+        const conf: FileIdConf = {
+            id,
+            srcFile: modulePath,
+            tag,
+        };
+
+        return {
+            conf,
+            info: createLogFn(LogLevel.INFO, prefix),
+            warn: createLogFn(LogLevel.WARN, prefix),
+            error: createLogFn(LogLevel.ERROR, prefix),
+            debug: createLogFn(LogLevel.DEBUG, prefix),
+        };
+    };
+}

package/staticMeta/file.yml.ts

@@ -0,0 +1,18 @@
+import { fs, YAML } from 'zx';
+
+/**
+ * YAML 文件读写：无 data 参数时读取，有 data 参数时写入
+ */
+export function yml(path: string, data?: unknown): unknown {
+    if (typeof data !== 'undefined') {
+        fs.writeFileSync(
+            path,
+            // @ts-expect-error YAML.stringify 类型定义有误
+            YAML.stringify(data, { singleQuote: true, sortKeys: true }),
+            'utf-8',
+        );
+    } else {
+        const ymlContent = fs.readFileSync(path, 'utf-8');
+        return YAML.parse(ymlContent);
+    }
+}

package/staticMeta/iduniq.ts

@@ -0,0 +1,320 @@
+/**
+ * fileId 调用规范检查：
+ * - 检查 fileInit 导入是否被重命名
+ * - 检查 fileInit 返回值是否命名为 fileId
+ * - 检查 fileId 调用中的 key 是否重复
+ */
+
+import { err, ok } from 'neverthrow';
+import type { EffContext } from './eff.js';
+import { Eff } from './eff.js';
+import type { Result, ResultAsync } from 'neverthrow';
+import { fileInit } from './enum.api.js';
+import { parseFileAsync, scanTypeScriptFilesAsync } from './ast.scan.js';
+import { extractKeyFromCall, findAllByKind, findFunctionCalls } from './ast.js';
+import type { AstNode } from './ast.js';
+
+type NonEmptyArray<T> = readonly [T, ...T[]];
+
+// ==================== 日志配置 ====================
+
+const fileId = fileInit('staticMeta/iduniq.ts');
+
+// ==================== 类型定义 ====================
+
+interface KeyUsage {
+    readonly key: string;
+    readonly tags?: string[];
+}
+
+interface CheckIssue {
+    readonly filePath: string;
+    readonly type: 'import-violation' | 'variable-name-violation' | 'duplicate';
+    readonly details: string;
+    readonly keys?: readonly {
+        key: string;
+        count: number;
+    }[];
+}
+
+// ==================== 导入规范检查 ====================
+
+/**
+ * 检查 fileInit 导入是否被 as 重命名（违反规范）
+ */
+function checkImportConvention(root: AstNode): Result<boolean, CheckIssue> {
+    const importStatements = findAllByKind(root, 'import_statement');
+
+    for (const stmt of importStatements) {
+        const specifiers = findAllByKind(stmt, 'import_specifier');
+        for (const spec of specifiers) {
+            const children = spec.children();
+            // import_specifier 的结构: identifier | (identifier 'as' identifier)
+            if (children.length >= 1) {
+                const firstName = children[0].text();
+                if (firstName === 'fileInit') {
+                    // 检查是否被 as 重命名
+                    if (children.length > 1) {
+                        const asNode = children.find((c: AstNode) => c.text() === 'as');
+                        if (asNode) {
+                            return err({
+                                filePath: '',
+                                type: 'import-violation',
+                                details: `fileInit 被重命名为 ${children[children.length - 1].text()}，违反导入规范`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return ok(true);
+}
+
+// ==================== 变量名规范检查 ====================
+
+/**
+ * 检查 fileInit() 返回值是否被命名为 fileId（违反规范则报错）
+ */
+function checkVariableNameConvention(root: AstNode): Result<boolean, CheckIssue> {
+    // 查找所有变量声明
+    const varDeclarations = findAllByKind(root, 'variable_declarator');
+
+    for (const decl of varDeclarations) {
+        const children = decl.children();
+        if (children.length < 2) continue;
+
+        // 检查初始化值是否是 fileInit 调用
+        const initPart = children[children.length - 1];
+        if (initPart?.kind() === 'call_expression') {
+            const callChildren = initPart.children();
+            if (callChildren.length > 0 && callChildren[0].text() === 'fileInit') {
+                // 获取变量名
+                const varName = children[0].text();
+                if (varName !== 'fileId') {
+                    return err({
+                        filePath: '',
+                        type: 'variable-name-violation',
+                        details: `fileInit 的返回值被命名为 ${varName}，应该命名为 fileId`,
+                    });
+                }
+            }
+        }
+    }
+
+    return ok(true);
+}
+
+// ==================== Key 唯一性检查 ====================
+
+/**
+ * 提取代码中所有 fileId 调用的 key 和 tags
+ */
+function collectFileIdUsages(root: AstNode): KeyUsage[] {
+    const usages: KeyUsage[] = [];
+    const allCalls = findFunctionCalls(root, 'fileId');
+
+    for (const call of allCalls) {
+        const usage = extractKeyFromCall(call, 'fileId');
+        if (usage) {
+            usages.push(usage);
+        }
+    }
+
+    return usages;
+}
+
+// ==================== 文件检测 ====================
+
+/**
+ * 检查单个文件：验证导入规范、变量名规范、key 唯一性
+ */
+function checkFile(filePath: string, root: AstNode): Result<CheckIssue | null, Error> {
+    // 步骤 1：导入约束检查
+    const importCheck = checkImportConvention(root);
+    if (importCheck.isErr()) {
+        return ok({
+            ...importCheck.error,
+            filePath,
+        });
+    }
+
+    // 步骤 2：变量名约束检查
+    const varNameCheck = checkVariableNameConvention(root);
+    if (varNameCheck.isErr()) {
+        return ok({
+            ...varNameCheck.error,
+            filePath,
+        });
+    }
+
+    // 步骤 3：Key 唯一性检查
+    const idUsages = collectFileIdUsages(root);
+    if (idUsages.length === 0) {
+        return ok(null);
+    }
+
+    const keyCountMap = new Map<string, number>();
+    for (const usage of idUsages) {
+        const count = keyCountMap.get(usage.key) ?? 0;
+        keyCountMap.set(usage.key, count + 1);
+    }
+
+    const duplicateKeys = Array.from(keyCountMap.entries()).filter(
+        ([, count]) => count > 1,
+    );
+
+    if (duplicateKeys.length > 0) {
+        return ok({
+            filePath,
+            type: 'duplicate',
+            details: 'Key 存在重复',
+            keys: duplicateKeys.map(([key, count]) => ({ key, count })),
+        });
+    }
+
+    return ok(null);
+}
+
+// ==================== 批量检测 ====================
+
+/**
+ * 并行检测所有文件（使用 Eff.allSettled）
+ */
+function checkAllFiles(allFiles: string[], parentSignal: AbortSignal): ResultAsync<CheckIssue[], Error> {
+    if (allFiles.length === 0) {
+        return Eff.root(() => Promise.resolve(ok([])));
+    }
+
+    // 直接传递 executor 函数给 Eff.allSettled，而不是 Eff.root 的返回值
+    const executors = allFiles.map((file) =>
+        async ({ signal }: EffContext) => {
+            if (signal.aborted) return err(new Error('任务已取消'));
+
+            fileId('checkProgress').info(`[正在扫描] ${file}`);
+
+            const parseResult = await parseFileAsync(file, signal);
+            if (parseResult.isErr()) {
+                return ok(null as CheckIssue | null);
+            }
+
+            const { root } = parseResult.value;
+            const checkResult = checkFile(file, root);
+            if (checkResult.isErr()) {
+                return ok(null as CheckIssue | null);
+            }
+
+            return ok(checkResult.value);
+        },
+    ) as unknown as NonEmptyArray<(ctx: EffContext) => Promise<Result<CheckIssue | null, Error>>>;
+
+    // 使用 Eff.allSettled 并行执行，支持 signal 传播
+    return Eff.allSettled(executors, parentSignal).map((results) => {
+        const issues: CheckIssue[] = [];
+        for (const result of results) {
+            if (result.isOk() && result.value !== null) {
+                issues.push(result.value);
+            }
+        }
+        return issues;
+    });
+}
+
+// ==================== 输出格式 ====================
+
+/**
+ * 分类并格式化输出检测结果
+ */
+function printAllIssues(issues: CheckIssue[]): void {
+    if (issues.length === 0) {
+        return;
+    }
+
+    fileId('summaryHeader').info(
+        `\n${'='.repeat(60)}\n检测结果汇总\n${'='.repeat(60)}`,
+    );
+
+    // 分类统计
+    const importViolations = issues.filter((i) => i.type === 'import-violation');
+    const varNameViolations = issues.filter((i) => i.type === 'variable-name-violation');
+    const duplicateIssues = issues.filter((i) => i.type === 'duplicate');
+
+    // 导入约束违反
+    if (importViolations.length > 0) {
+        fileId('importViolationsHeader').error(`\n❌ 导入约束违反 (${importViolations.length} 个)`);
+        for (const issue of importViolations) {
+            fileId('importViolationsPath').error(`   ${issue.filePath}`);
+            fileId('importViolationsDetail').error(`     └─ ${issue.details}`);
+        }
+    }
+
+    // 变量名约束违反
+    if (varNameViolations.length > 0) {
+        fileId('varNameViolationsHeader').error(`\n❌ 变量名约束违反 (${varNameViolations.length} 个)`);
+        for (const issue of varNameViolations) {
+            fileId('varNameViolationsPath').error(`   ${issue.filePath}`);
+            fileId('varNameViolationsDetail').error(`     └─ ${issue.details}`);
+        }
+    }
+
+    // Key 重复
+    if (duplicateIssues.length > 0) {
+        fileId('duplicateKeysHeader').error(`\n❌ 重复的 Key (${duplicateIssues.length} 个)`);
+        for (const issue of duplicateIssues) {
+            fileId('duplicateKeysPath').error(`   ${issue.filePath}`);
+            if (issue.keys) {
+                for (const k of issue.keys) {
+                    fileId('duplicateKeysItem').error(`     ├─ ${k.key} (${k.count} 次)`);
+                }
+            }
+        }
+    }
+
+    fileId('summaryFooter').info(`${'='.repeat(60)}\n`);
+}
+
+// ==================== 主函数 ====================
+
+export const tz = () => {
+    return Eff.root(async ({ signal }) => {
+        try {
+            const allFiles = await scanTypeScriptFilesAsync();
+            fileId('checkStart').info(`开始检测 kv2 keys... (共 ${allFiles.length} 个文件)\n`);
+
+            // 传递 signal 以支持取消传播
+            const issuesResult = await checkAllFiles(allFiles, signal);
+
+            if (issuesResult.isErr()) {
+                return err(issuesResult.error);
+            }
+
+            const issues = issuesResult.value;
+            printAllIssues(issues);
+
+            const issueCount = issues.length;
+            if (issueCount > 0) {
+                fileId('checkCompleteFail').error(
+                    `\n❌ 检测完成: 发现 ${issueCount} 个问题`,
+                );
+                process.exit(1);
+            } else {
+                fileId('checkCompleteSuccess').info(
+                    '\n✅ 检测完成: 无问题',
+                );
+            }
+
+            return ok(undefined);
+        } catch (e) {
+            return err(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+};
+
+tz().match(
+    () => { /* success */ },
+    (err) => {
+        fileId('scriptFailed').error(`脚本执行失败: ${err.message}`);
+        process.exit(1);
+    },
+);