tcdona_unilib 1.0.1 → 1.0.2

package/@ast-grep.ts

@@ -0,0 +1,18 @@
+// -----Type Only Export!-----//
+export type { FileOption, FindConfig, NapiConfig } from "@ast-grep/napi"
+export type { DynamicLangRegistrations } from "@ast-grep/napi"
+export type { Edit, Pos, Range } from "@ast-grep/napi"
+export type { Rule } from "@ast-grep/napi"
+
+// -----Runtime Value Export!-----//
+export {
+  findInFiles,
+  kind,
+  parse,
+  parseAsync,
+  parseFiles,
+  pattern,
+} from "@ast-grep/napi"
+export { Lang } from "@ast-grep/napi"
+export { registerDynamicLanguage } from "@ast-grep/napi"
+export { SgNode, SgRoot } from "@ast-grep/napi"

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "tcdona_unilib",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Unified dependency aggregation layer for shared libraries",
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./astgrep": "./@ast-grep.ts",
+    "./staticMeta/eff": "./staticMeta/eff.ts",
+    "./staticMeta/file": "./staticMeta/file.yml.ts",
+    "./staticMeta/path": "./staticMeta/path.init.ts",
+    "./staticMeta/string": "./staticMeta/string.nanoid.ts",
+    "./staticMeta/url": "./staticMeta/url.ts",
+    "./staticMeta/iduniq": "./staticMeta/iduniq.ts",
+    "./staticMeta/idupdate": "./staticMeta/idupdate.ts",
+    "./staticMeta/pkgjson": "./staticMeta/pkg.json.ts",
     "./neverthrow": "./neverthrow.ts",
     "./zod": "./zod.ts",
     "./zx": "./zx.ts",
@@ -40,9 +49,11 @@
   "license": "ISC",
   "devDependencies": {
     "@types/bun": "^1.3.5",
-    "@types/node": "^20.10.6"
+    "@types/node": "^20.10.6",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
+    "@ast-grep/napi": "^0.40.3",
     "@dotenvx/dotenvx": "^1.51.2",
     "@inquirer/prompts": "^8.1.0",
     "@types/big.js": "^6.2.2",

package/staticMeta/ast.scan.ts

@@ -0,0 +1,131 @@
+/**
+ * 异步文件操作中心：提供统一的文件读写、AST 解析、扫描等功能
+ * 基于 Eff 框架和 neverthrow 处理错误
+ */
+
+import { glob } from 'zx';
+import { promises as fs } from 'node:fs';
+import { fileInit } from './enum.api.js';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Eff } from './eff.js';
+import type { ResultAsync } from 'neverthrow';
+import { err, ok } from 'neverthrow';
+import { Lang, parse } from '@ast-grep/napi';
+import type { AstNode } from './ast.js';
+
+// ==================== 配置 ====================
+
+const meta = dirname(fileURLToPath(import.meta.url));
+const fileId = fileInit('staticMeta/ast.scan.ts');
+
+export const projectRoot = process.cwd();
+
+// ==================== 类型定义 ====================
+
+export interface FileParseInfo {
+    readonly filePath: string;
+    readonly root: AstNode;
+}
+
+// ==================== 异步文件操作 ====================
+
+/**
+ * 异步读取文件（UTF-8 编码）
+ */
+export function readFileAsync(filePath: string, signal: AbortSignal): ResultAsync<string, Error> {
+    return Eff.create(async ({ signal: effSignal }) => {
+        if (effSignal.aborted) return err(new Error('操作已取消'));
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return ok(content);
+        } catch (e) {
+            return err(e instanceof Error ? e : new Error(String(e)));
+        }
+    }, signal);
+}
+
+/**
+ * 异步写入文件（UTF-8 编码）
+ */
+export function writeFileAsync(filePath: string, content: string, signal: AbortSignal): ResultAsync<void, Error> {
+    return Eff.create(async ({ signal: effSignal }) => {
+        if (effSignal.aborted) return err(new Error('操作已取消'));
+        try {
+            await fs.writeFile(filePath, content, 'utf-8');
+            return ok(undefined);
+        } catch (e) {
+            return err(e instanceof Error ? e : new Error(String(e)));
+        }
+    }, signal);
+}
+
+/**
+ * 异步读取并解析 TypeScript 文件为 AST
+ */
+export function parseFileAsync(filePath: string, signal: AbortSignal): ResultAsync<FileParseInfo, Error> {
+    return Eff.create(async ({ signal: effSignal }) => {
+        if (effSignal.aborted) return err(new Error('操作已取消'));
+
+        return readFileAsync(filePath, effSignal)
+            .andThen((content) => {
+                try {
+                    const parsed = parse(Lang.TypeScript, content);
+                    const root = parsed.root();
+                    return ok({ filePath, root });
+                } catch (e) {
+                    return err(e instanceof Error ? e : new Error(String(e)));
+                }
+            });
+    }, signal);
+}
+
+/**
+ * 并行处理多个文件（通过 Eff.all）
+ */
+export function processFilesAsync<T>(
+    files: readonly string[],
+    processor: (filePath: string, signal: AbortSignal) => ResultAsync<T, Error>,
+    signal: AbortSignal,
+): ResultAsync<T[], Error> {
+    if (files.length === 0) {
+        return Eff.create(async () => ok([]), signal);
+    }
+
+    const tasks = files.map((file) =>
+        (ctx: { signal: AbortSignal }) =>
+            processor(file, ctx.signal),
+    );
+
+    return Eff.all(tasks as any, signal) as ResultAsync<T[], Error>;
+}
+
+/**
+ * 获取相对于项目根目录的相对路径
+ */
+export function getRelativePath(filePath: string): string {
+    return relative(projectRoot, filePath);
+}
+
+/**
+ * 扫描项目中所有 TS/TSX/Vue 文件
+ */
+export async function scanTypeScriptFilesAsync(
+    ignorePatterns: string[] = [],
+): Promise<string[]> {
+    const files = await glob('**/*.{ts,tsx,vue}', {
+        cwd: projectRoot,
+        ignore: [
+            '**/node_modules/**',
+            '**/*.d.ts',
+            '**/*.test.ts',
+            '**/*.spec.ts',
+            'dist/**',
+            '.git/**',
+            ...ignorePatterns,
+        ],
+        absolute: true,
+        onlyFiles: true,
+    });
+    return files;
+}

package/staticMeta/ast.ts

@@ -0,0 +1,259 @@
+/**
+ * AST 工具集：代码解析、遍历、分析和文本替换
+ */
+
+import type { SgNode } from '@ast-grep/napi';
+import { Lang, parse } from '@ast-grep/napi';
+import { fromThrowable } from 'neverthrow';
+import type { Result } from 'neverthrow';
+
+// ==================== 类型定义 ====================
+
+export type AstNode = InstanceType<typeof SgNode>;
+
+export interface FileParseInfo {
+    readonly filePath: string;
+    readonly relativePath: string;
+    readonly root: AstNode;
+}
+
+// ==================== AST 遍历工具 ====================
+
+/**
+ * 递归查找 AST 中所有匹配类型的节点
+ */
+export function findAllByKind(
+    node: AstNode,
+    kind: string,
+    results: AstNode[] = [],
+): AstNode[] {
+    if (node.kind() === kind) {
+        results.push(node);
+    }
+    for (const child of node.children()) {
+        findAllByKind(child, kind, results);
+    }
+    return results;
+}
+
+// ==================== 字符串处理 ====================
+
+/**
+ * 删除字符串的首尾引号
+ */
+export function stripQuotes(str: string): string {
+    if (
+        (str.startsWith('"') && str.endsWith('"'))
+        || (str.startsWith('\'') && str.endsWith('\''))
+        || (str.startsWith('`') && str.endsWith('`'))
+    ) {
+        return str.slice(1, -1);
+    }
+    return str;
+}
+
+// ==================== 代码解析 ====================
+
+/**
+ * 解析代码为 AST 根节点
+ */
+export function parseCode(
+    content: string,
+    lang: Lang = Lang.TypeScript,
+): Result<AstNode, Error> {
+    return fromThrowable(
+        () => {
+            const parsed = parse(lang, content);
+            return parsed.root();
+        },
+        (error) => new Error(`代码解析失败: ${error}`),
+    )();
+}
+
+// ==================== 函数调用分析 ====================
+
+export interface CallExpressionInfo {
+    readonly functionName: string;
+    readonly arguments: AstNode;
+}
+
+/**
+ * 从 arguments 节点提取第一个字符串参数值
+ */
+export function extractArgumentValue(argsNode: AstNode): string | null {
+    const argChildren = argsNode.children();
+
+    for (const child of argChildren) {
+        const kind = child.kind();
+
+        // 跳过标点符号
+        if (kind === '(' || kind === ')' || kind === ',') continue;
+
+        // 处理字符串字面量
+        if (kind === 'string') {
+            // 优先查找 string_fragment 子节点
+            for (const frag of child.children()) {
+                if (frag.kind() === 'string_fragment') {
+                    return frag.text();
+                }
+            }
+            // 降级：直接处理文本
+            const text = child.text();
+            if (text.length >= 2 && (text[0] === '"' || text[0] === '\'')) {
+                return text.slice(1, -1);
+            }
+        }
+
+        // 处理模板字符串（只支持纯字符串，不支持插值）
+        if (kind === 'template_string') {
+            const text = child.text();
+            if (!text.includes('${')) {
+                return text.slice(1, -1);
+            }
+            return null;
+        }
+
+        // 变量或其他类型
+        return null;
+    }
+
+    return null;
+}
+
+/**
+ * 从函数调用提取函数名（支持 identifier 和 member_expression）
+ */
+export function extractFunctionName(call: AstNode): string | null {
+    const children = call.children();
+    if (children.length < 1) return null;
+
+    const callee = children[0];
+    if (callee.kind() === 'identifier') {
+        return callee.text();
+    }
+
+    if (callee.kind() === 'member_expression') {
+        const memberChildren = callee.children();
+        const lastIdentifier = memberChildren.findLast(
+            (c) => c.kind() === 'property_identifier' || c.kind() === 'identifier',
+        );
+        if (lastIdentifier) {
+            return lastIdentifier.text();
+        }
+    }
+
+    return null;
+}
+
+// ==================== 导入检测 ====================
+
+/**
+ * 检查代码中是否导入了指定的名称
+ */
+export function hasImport(root: AstNode, importName: string): boolean {
+    // 查找所有 import_statement
+    const importStatements = findAllByKind(root, 'import_statement');
+
+    for (const stmt of importStatements) {
+        // 查找 named_imports 中的标识符
+        const namedImports = findAllByKind(stmt, 'import_specifier');
+        for (const specifier of namedImports) {
+            const children = specifier.children();
+            // import_specifier 的结构: identifier | (identifier 'as' identifier)
+            if (children.length >= 1) {
+                const firstName = children[0].text();
+                if (firstName === importName) {
+                    return true;
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * 查找代码中所有对指定函数的调用
+ */
+export function findFunctionCalls(
+    root: AstNode,
+    functionName: string,
+): AstNode[] {
+    const calls = findAllByKind(root, 'call_expression');
+    return calls.filter((call) => {
+        const fname = extractFunctionName(call);
+        return fname === functionName;
+    });
+}
+
+/**
+ * 从函数调用提取第一个参数（key）和其他字符串参数（tags）
+ */
+export function extractKeyFromCall(
+    call: AstNode,
+    fnName: string,
+): { key: string; tags?: string[] } | null {
+    const children = call.children();
+    if (children.length < 2) return null;
+
+    const callee = children[0];
+    const args = children[1];
+
+    if (callee?.kind() !== 'identifier' || callee.text() !== fnName) {
+        return null;
+    }
+
+    if (args?.kind() !== 'arguments') return null;
+
+    const argChildren = args.children().filter((c) => c.kind() === 'string');
+    if (argChildren.length === 0) return null;
+
+    const key = stripQuotes(argChildren[0].text());
+
+    let tags: string[] = [];
+    if (argChildren.length > 1) {
+        tags = argChildren.slice(1).map((c) => stripQuotes(c.text()));
+    }
+
+    return { key, tags };
+}
+
+/**
+ * 按指定范围替换文本内容（从后往前替换以避免位置偏移）
+ */
+export function replaceRanges(
+    content: string,
+    replacements: {
+        startIndex: number;
+        endIndex: number;
+        replacement: string;
+    }[],
+): string {
+    // 从后往前排序，避免位置偏移
+    const sorted = [...replacements].sort((a, b) => b.startIndex - a.startIndex);
+
+    let result = content;
+    for (const { startIndex, endIndex, replacement } of sorted) {
+        const before = result.slice(0, startIndex);
+        const after = result.slice(endIndex);
+        result = before + replacement + after;
+    }
+
+    return result;
+}
+
+// ==================== 导出默认函数 ====================
+
+// 统一导出所有 AST 工具函数
+export const astTools = {
+    findAllByKind,
+    stripQuotes,
+    parseCode,
+    extractArgumentValue,
+    extractFunctionName,
+    hasImport,
+    findFunctionCalls,
+    replaceRanges,
+};
+
+export default astTools;

package/staticMeta/eff.delay.ts

@@ -0,0 +1,17 @@
+import { ok } from 'neverthrow';
+import { Eff } from './eff';
+
+/**
+ * 异步延迟函数：返回延迟是否完成（true）或被取消（false）
+ */
+export const delayEff = (time: number, parentSignal: AbortSignal) => {
+    return Eff.create<boolean, never>(({ signal }) => {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(ok(true)), time);
+            signal.addEventListener('abort', () => {
+                clearTimeout(timer);
+                resolve(ok(false));
+            }, { once: true });
+        });
+    }, parentSignal);
+};