tcdona_unilib 1.0.1 → 1.0.3

package/staticMeta/idupdate.ts

@@ -0,0 +1,374 @@
+/**
+ * 自动更新所有 fileInit() 调用的路径参数为正确的相对路径
+ */
+
+import { fileURLToPath } from "node:url"
+import { err, ok } from "neverthrow"
+import type { EffContext } from "./eff.js"
+import { Eff } from "./eff.js"
+import type { Result } from "neverthrow"
+import type { SgNode } from "@ast-grep/napi"
+import { fileInit } from "./enum.api.js"
+import {
+  extractArgumentValue,
+  findFunctionCalls,
+  hasImport,
+  replaceRanges,
+} from "./ast.js"
+import {
+  getRelativePath,
+  parseFileAsync,
+  readFileAsync,
+  scanTypeScriptFilesAsync,
+  writeFileAsync,
+} from "./ast.scan.js"
+
+type NonEmptyArray<T> = readonly [T, ...T[]]
+
+// ==================== 日志配置 ====================
+
+const fileId = fileInit("staticMeta/idupdate.ts")
+
+// ==================== 类型定义 ====================
+
+type UpdateError =
+  | { type: "VALIDATION_FILENAME_FAILED"; message: string }
+  | { type: "FILE_ERROR"; message: string; filePath: string }
+
+interface StaticMetaCallInfo {
+  startOffset: number
+  endOffset: number
+  currentValue: string | null
+}
+
+interface InvalidCall {
+  reason: "NO_ARGUMENT" | "VARIABLE_ARGUMENT" | "TEMPLATE_STRING"
+  line: number
+  text: string
+}
+
+// ==================== 初始化 ====================
+
+const __filename = fileURLToPath(import.meta.url)
+
+// ==================== 验证 ====================
+
+function validate(): {
+  isErr: () => boolean
+  isOk: () => boolean
+  value?: void
+  error?: UpdateError
+} {
+  // 验证 staticMeta 功能
+  const currentFileAbsPath = fileURLToPath(import.meta.url)
+  const expectedRelativePath = getRelativePath(currentFileAbsPath)
+
+  const conf = fileId("validate1").conf
+  if (conf.srcFile !== expectedRelativePath) {
+    return err({
+      type: "VALIDATION_FILENAME_FAILED",
+      message: `__filename 不正确:\n  期望: ${expectedRelativePath}\n  实际: ${conf.srcFile}`,
+    })
+  }
+
+  return ok(undefined)
+}
+
+// ==================== 文件处理 ====================
+
+/**
+ * 找出文件中所有 fileInit 调用（有效和无效）
+ */
+function findFileInitCalls(
+  root: SgNode
+): [StaticMetaCallInfo[], InvalidCall[]] {
+  const validCalls: StaticMetaCallInfo[] = []
+  const invalidCalls: InvalidCall[] = []
+
+  const allCalls = findFunctionCalls(root, "fileInit")
+
+  for (const call of allCalls) {
+    const children = call.children()
+    if (children.length < 2) continue
+
+    const args = children[1]
+
+    if (args?.kind() !== "arguments") continue
+
+    const value = extractArgumentValue(args)
+    const range = call.range()
+
+    if (value === null) {
+      const argText = args.text()
+      let reason: InvalidCall["reason"] = "NO_ARGUMENT"
+
+      if (argText.includes("`")) {
+        reason = "TEMPLATE_STRING"
+      } else if (
+        argText.length > 2 &&
+        !argText.includes('"') &&
+        !argText.includes("'")
+      ) {
+        reason = "VARIABLE_ARGUMENT"
+      }
+
+      invalidCalls.push({
+        reason,
+        line: range.start.line,
+        text: call.text(),
+      })
+      continue
+    }
+
+    validCalls.push({
+      startOffset: range.start.index,
+      endOffset: range.end.index,
+      currentValue: value,
+    })
+  }
+
+  return [validCalls, invalidCalls]
+}
+
+/**
+ * 更新文件中所有 fileInit 调用的路径参数
+ */
+async function updateStaticMeta(
+  filePath: string,
+  content: string,
+  root: SgNode,
+  dryRun: boolean,
+  signal: AbortSignal
+): Promise<{ isErr: boolean; error?: UpdateError; value?: boolean }> {
+  // 计算正确路径
+  const relativePath = getRelativePath(filePath)
+
+  // 检测导入 fileInit
+  if (!hasImport(root, "fileInit")) {
+    return { isErr: false, value: false }
+  }
+
+  // 查找 fileInit 调用
+  const [validCalls, invalidCalls] = findFileInitCalls(root)
+
+  // 记录无效调用
+  if (invalidCalls.length > 0) {
+    fileId("invalidFileInitCalls").warn(
+      `⚠️  ${filePath} 包含无效的 fileInit 调用:`
+    )
+    for (const invalid of invalidCalls) {
+      fileId("invalidFileInitDetail").warn(
+        `  L${invalid.line} [${invalid.reason}]: ${invalid.text}`
+      )
+    }
+  }
+
+  // 如果没有有效调用则跳过
+  if (validCalls.length === 0) {
+    return { isErr: false, value: false }
+  }
+
+  // 替换内容
+  const updatedContent = replaceRanges(
+    content,
+    validCalls.map((call) => ({
+      startIndex: call.startOffset,
+      endIndex: call.endOffset,
+      replacement: `fileInit('${relativePath}')`,
+    }))
+  )
+
+  // 写入文件
+  if (!dryRun) {
+    const writeResult = await writeFileAsync(filePath, updatedContent, signal)
+    if (writeResult.isErr()) {
+      return {
+        isErr: true,
+        error: {
+          type: "FILE_ERROR",
+          message: `无法写入文件: ${writeResult.error.message}`,
+          filePath,
+        },
+      }
+    }
+  }
+
+  return { isErr: false, value: true }
+}
+
+// ==================== 更新文件执行器 ====================
+
+/**
+ * 为单个文件创建更新任务 executor
+ */
+function createUpdateExecutor(
+  file: string,
+  dryRun: boolean
+): (
+  ctx: EffContext
+) => Promise<Result<{ updated: boolean; file: string } | null, UpdateError>> {
+  return async ({ signal: innerSignal }: EffContext) => {
+    if (innerSignal.aborted) {
+      return err({ type: "FILE_ERROR", message: "任务已取消", filePath: file })
+    }
+
+    const readResult = await readFileAsync(file, innerSignal)
+    if (readResult.isErr()) {
+      return err({
+        type: "FILE_ERROR",
+        message: `无法读取文件: ${readResult.error.message}`,
+        filePath: file,
+      })
+    }
+
+    const parseResult = await parseFileAsync(file, innerSignal)
+    if (parseResult.isErr()) {
+      return err({
+        type: "FILE_ERROR",
+        message: `AST 解析失败: ${parseResult.error.message}`,
+        filePath: file,
+      })
+    }
+
+    const updateResult = await updateStaticMeta(
+      file,
+      readResult.value,
+      parseResult.value.root,
+      dryRun,
+      innerSignal
+    )
+    if (updateResult.isErr) {
+      return err(updateResult.error!)
+    }
+
+    return ok(updateResult.value ? { updated: true, file } : null)
+  }
+}
+
+// ==================== 结果处理与汇总 ====================
+
+/**
+ * 统计、分类并输出更新结果
+ */
+function collectAndPrintResults(
+  results: Result<{ updated: boolean; file: string } | null, UpdateError>[],
+  files: string[],
+  dryRun: boolean
+): { updatedFiles: string[]; errors: UpdateError[] } {
+  const updatedFiles: string[] = []
+  const skippedFiles: string[] = []
+  const errors: UpdateError[] = []
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i]
+    const file = files[i]
+
+    if (result.isErr()) {
+      errors.push(result.error)
+    } else if (result.value?.updated) {
+      updatedFiles.push(getRelativePath(result.value.file))
+      fileId("updateProgress").info(`  ✓ ${getRelativePath(result.value.file)}`)
+    } else {
+      skippedFiles.push(getRelativePath(file))
+    }
+  }
+
+  // 打印汇总
+  fileId("summaryHeaderLine1").info(`\n${"=".repeat(60)}`)
+  fileId("summaryHeaderLine2").info("更新结果汇总")
+  fileId("summaryHeaderLine3").info(`${"=".repeat(60)}`)
+
+  if (updatedFiles.length > 0) {
+    fileId("updateSuccess").info(
+      `\n✅ ${dryRun ? "将更新" : "已更新"} ${updatedFiles.length} 个文件`
+    )
+  }
+
+  if (skippedFiles.length > 0) {
+    fileId("updateSkipped").info(
+      `⊘ 已跳过 ${skippedFiles.length} 个文件 (无 fileInit 调用)`
+    )
+  }
+
+  if (errors.length > 0) {
+    fileId("updateFailed").error(`\n❌ 更新失败 ${errors.length} 个文件:`)
+    for (const error of errors) {
+      const filePath = error.type === "FILE_ERROR" ? error.filePath : "(验证)"
+      const message = error.message
+      fileId("updateErrorPath").error(`   ${filePath}`)
+      fileId("updateErrorMessage").error(`     └─ ${message}`)
+    }
+  }
+
+  fileId("summaryFooter").info(`${"=".repeat(60)}\n`)
+
+  return { updatedFiles, errors }
+}
+
+// ==================== 主函数 ====================
+
+const main = () => {
+  return Eff.root(async ({ signal }) => {
+    if (signal.aborted) return err(new Error("操作已取消"))
+
+    const args = process.argv.slice(2)
+    const dryRun = args.includes("--dry-run") || args.includes("-n")
+
+    // 验证 staticMeta 功能
+    // const validationResult = validate();
+    // if (validationResult.isErr?.()) {
+    //     fileId('validateFailed').error(
+    //         '验证失败:',
+    //         (validationResult as any).error.message,
+    //     );
+    // // 下面的这个 as any 会让类型推断中断，从而无法保证，return 后面的所有语句的推导正确性，再一次证明了 as any 要少用
+    //     return err((validationResult as any).error);
+    // }
+
+    // 扫描文件
+    const files = await scanTypeScriptFilesAsync(["**/staticMeta/idupdate.ts"])
+    fileId("updateStart").info(
+      `开始更新 fileInit... (共 ${files.length} 个文件)\n`
+    )
+
+    if (files.length === 0) {
+      return ok(undefined)
+    }
+
+    // 创建并行更新任务
+    type UpdateResult = { updated: boolean; file: string } | null
+    const executors = files.map((file) =>
+      createUpdateExecutor(file, dryRun)
+    ) as unknown as NonEmptyArray<
+      (ctx: EffContext) => Promise<Result<UpdateResult, UpdateError>>
+    >
+
+    // 执行并行更新
+    const allResults = await Eff.allSettled(executors, signal)
+    const results = allResults.isOk() ? allResults.value : []
+
+    // 统计结果并输出汇总
+    const { errors } = collectAndPrintResults(results, files, dryRun)
+
+    if (errors.length > 0) {
+      const error = errors[0]
+      const message =
+        error.type === "FILE_ERROR"
+          ? `${error.message} (${error.filePath})`
+          : error.message
+      return err(new Error(message))
+    }
+
+    return ok(undefined)
+  })
+}
+
+main().match(
+  () => {
+    /* success */
+  },
+  (err) => {
+    fileId("scriptFailed").error(`脚本执行失败: ${err.message ?? String(err)}`)
+    process.exit(1)
+  }
+)

package/staticMeta/path.init.ts

@@ -0,0 +1,21 @@
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 初始化模块的路径元信息（__filename, __dirname, __relative, resolve）
+ * @param metaUrl 模块 URL（import.meta.url）
+ * @param root 根目录路径
+ */
+export function pathMeta(metaUrl: string, root: string) {
+    const __filename = fileURLToPath(metaUrl);
+    const __dirname = dirname(__filename);
+    const __rootname = resolve(root);
+
+    return {
+        __rootname,
+        __dirname,
+        __filename,
+        resolve: resolve.bind(null, __dirname),
+        __relative: relative(__rootname, __filename),
+    } as const;
+}

package/staticMeta/pkg.json.ts

@@ -0,0 +1,138 @@
+/**
+ * 自动生成 package.json 中的 staticMeta 相关脚本配置
+ * 依赖 zx 库查找外层的 package.json 并生成正确的脚本条目
+ *
+ * 使用方式:
+ *   bun run node_modules/tcdona_unilib/staticMeta/pkg.json.ts          # 更新 package.json
+ *   bun run node_modules/tcdona_unilib/staticMeta/pkg.json.ts --dry-run  # 预览将要进行的更改
+ */
+
+import { $ } from 'zx';
+import { resolve } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileInit, TcErr } from './enum.api.js';
+
+// ==================== 初始化 ====================
+
+const fileId = fileInit('staticMeta/pkg.json.ts');
+
+// ==================== 脚本配置定义 ====================
+
+/**
+ * staticMeta 脚本配置映射表
+ * 这是唯一的配置源，所有脚本更新都基于这个定义
+ */
+const STATIC_META_SCRIPTS = {
+    'iduniq': 'bun run node_modules/tcdona_unilib/staticMeta/iduniq.ts',
+    'idupdate': 'bun run node_modules/tcdona_unilib/staticMeta/idupdate.ts',
+    'idupdate:dry': 'bun run node_modules/tcdona_unilib/staticMeta/idupdate.ts --dry-run',
+} as const;
+
+// ==================== 查找 package.json ====================
+
+/**
+ * 从当前文件向上递归查找 package.json
+ * 优先使用 git 仓库根目录
+ */
+async function findPackageJsonPath(): Promise<string> {
+    try {
+        const result = await $`git rev-parse --show-toplevel`;
+        const gitRoot = result.stdout.trim();
+        const pkgPath = resolve(gitRoot, 'package.json');
+        return pkgPath;
+    } catch (error) {
+        throw new TcErr({
+            fildId: fileId('findPkgPathFailed'),
+            message: '无法查找 package.json',
+            cause: error,
+        });
+    }
+}
+
+// ==================== 更新 package.json ====================
+
+/**
+ * 更新 package.json 中的脚本配置
+ */
+function updatePackageJson(pkgPath: string, dryRun: boolean = false): void {
+    try {
+        const content = readFileSync(pkgPath, 'utf-8');
+        const pkg = JSON.parse(content);
+
+        if (!pkg.scripts) {
+            pkg.scripts = {};
+        }
+
+        let updated = false;
+        const changes: { key: string; oldValue?: string; newValue: string }[] = [];
+
+        // 检查并收集需要更新的脚本
+        for (const [key, value] of Object.entries(STATIC_META_SCRIPTS)) {
+            const oldValue = pkg.scripts[key];
+            if (oldValue !== value) {
+                changes.push({ key, oldValue, newValue: value });
+                updated = true;
+            }
+        }
+
+        // 输出变更信息
+        if (changes.length > 0) {
+            fileId('detectChanges').info(`检测到 ${changes.length} 个需要更新的脚本:`);
+            for (const change of changes) {
+                if (change.oldValue) {
+                    fileId('changeKey').info(`  • ${change.key}`);
+                    fileId('changeOldValue').warn(`    - 旧值: ${change.oldValue}`);
+                    fileId('changeNewValue').info(`    + 新值: ${change.newValue}`);
+                } else {
+                    fileId('addNewScript').info(`  + ${change.key}: ${change.newValue}`);
+                }
+            }
+        }
+
+        // 写入文件
+        if (updated && !dryRun) {
+            for (const { key, newValue } of changes) {
+                pkg.scripts[key] = newValue;
+            }
+            writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+            fileId('updateSuccess').info(`\n✅ 已成功更新 ${pkgPath}`);
+        } else if (updated && dryRun) {
+            fileId('dryRunWarning').warn('\n⊘ [Dry Run] 将要更新以上脚本 (使用 bun run pkg:json 执行实际更新)');
+        } else if (!updated) {
+            fileId('alreadyLatest').info('\n✓ 所有脚本配置已是最新');
+        }
+    } catch (error) {
+        throw new TcErr({
+            fildId: fileId('updatePkgJsonFailed'),
+            pkgPath,
+            cause: error,
+        });
+    }
+}
+
+// ==================== 主函数 ====================
+
+export const tz = async () => {
+    try {
+        const args = process.argv.slice(2);
+        const dryRun = args.includes('--dry-run') || args.includes('-n');
+
+        const modeLabel = dryRun ? '[预览]' : '[更新]';
+        fileId('startup').info(`${modeLabel} 生成 staticMeta 脚本配置\n`);
+
+        const pkgPath = await findPackageJsonPath();
+        fileId('foundPkgPath').info(`位置: ${pkgPath}\n`);
+
+        updatePackageJson(pkgPath, dryRun);
+    } catch (error) {
+        if (error instanceof TcErr) {
+            // TcErr 已经在构造器中输出了
+            process.exit(1);
+        }
+
+        throw new TcErr({
+            fildId: fileId('mainFailed'),
+            cause: error,
+        });
+    }
+};

package/staticMeta/string.nanoid.ts

@@ -0,0 +1,14 @@
+import { customAlphabet } from 'nanoid';
+
+/**
+ * 生成 18 字符的唯一 ID（使用自定义字符集，排除易混淆字符）
+ */
+export const tcNanoid = customAlphabet(
+    'useandom26T198340PX75pxJACKVERYMINDBUSHWOLFGQZbfghjklqvwyzrict',
+    18,
+);
+
+export const lowerNanoid = customAlphabet(
+    'useandom2619834075pxbfghjklqvwyzrict',
+    18,
+);