backtrace-console 0.0.1

package/lib/backtrace/tool.js

@@ -0,0 +1,333 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { createOptions } = require("./options");
+const {
+  logStep,
+  normalizeFingerprint,
+  ensureDirectoryExists,
+  ensureDirectory,
+  resolveCanonicalFingerprint,
+  mergeFingerprintFamilyDirectories,
+} = require("./utils");
+const {
+  BacktraceSession,
+  queryFingerprintDetail,
+  queryAllItems,
+  downloadItemLogs,
+} = require("./query");
+const {
+  summarizeFingerprintErrorLines,
+} = require("./analysis");
+
+async function writeFingerprintMetadata(items, options) {
+  const written = [];
+
+  for (const item of items) {
+    /* eslint-disable no-await-in-loop */
+    const fingerprint = normalizeFingerprint(item.fingerprint || item.values.fingerprint);
+    const fingerprintDir = path.join(options.storageDir, fingerprint);
+    const metaPath = path.join(fingerprintDir, "meta.json");
+    const meta = {
+      fingerprint,
+      firstSeen: item.values["fingerprint;first_seen"] || "",
+      issueState: item.values["fingerprint;issues;state"] || "",
+      errorMessage: item.values["error.message"] || "",
+      classifiers: item.values.classifiers || "",
+    };
+
+    await ensureDirectory(fingerprintDir);
+    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), "utf8");
+    written.push({ fingerprint, metaPath });
+    /* eslint-enable no-await-in-loop */
+  }
+
+  logStep("fingerprint", "fingerprint metadata written", {
+    count: written.length,
+    storageDir: options.storageDir,
+  });
+  return written;
+}
+
+function getRequestedFingerprints(options) {
+  return String(options?.fingerprint || "")
+    .split(",")
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+async function getLocalFingerprints(storageDir) {
+  const entries = await fs.readdir(storageDir, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name.trim())
+    .filter(Boolean);
+}
+
+async function listLocalFingerprints(options) {
+  const fingerprints = await getLocalFingerprints(options.storageDir);
+  const items = [];
+
+  for (const fingerprint of fingerprints) {
+    /* eslint-disable no-await-in-loop */
+    const metaPath = path.join(options.storageDir, fingerprint, "meta.json");
+    const rawMeta = await fs.readFile(metaPath, "utf8").catch(() => "");
+    if (!rawMeta) {
+      continue;
+    }
+    let meta = null;
+    try {
+      meta = JSON.parse(rawMeta);
+    } catch (error) {
+      meta = null;
+    }
+    if (!meta) {
+      continue;
+    }
+    items.push({
+      index: items.length + 1,
+      fingerprint,
+      errorMessage: meta.errorMessage || "",
+      issueState: meta.issueState || "",
+      metaPath,
+    });
+    /* eslint-enable no-await-in-loop */
+  }
+
+  return {
+    command: "list",
+    options,
+    items,
+  };
+}
+
+function buildDownloadItemsFromDetail(detail) {
+  return detail.objects.map((objectItem, index) => ({
+    index: index + 1,
+    objectIdDecimal: objectItem.objectIdDecimal,
+    objectIdHex: objectItem.objectIdHex,
+    fingerprint: detail.fingerprint,
+    values: {
+      fingerprint: detail.fingerprint,
+      timestamp: objectItem.timestamp || "",
+      "error.message": detail.summary.values["error.message"] || "",
+      classifiers: detail.summary.values.classifiers || "",
+      "fingerprint;first_seen": detail.summary.values["fingerprint;first_seen"] || "",
+      "fingerprint;issues;state": detail.summary.values["fingerprint;issues;state"] || "",
+      _count: detail.summary.values._count || detail.objects.length,
+    },
+  }));
+}
+
+function pickRandomItems(items, maxCount) {
+  if (!Array.isArray(items) || items.length <= maxCount) {
+    return Array.isArray(items) ? items : [];
+  }
+
+  const shuffled = [...items];
+  for (let index = shuffled.length - 1; index > 0; index -= 1) {
+    const swapIndex = Math.floor(Math.random() * (index + 1));
+    [shuffled[index], shuffled[swapIndex]] = [shuffled[swapIndex], shuffled[index]];
+  }
+
+  return shuffled
+    .slice(0, maxCount)
+    .map((item, index) => ({ ...item, index: index + 1 }));
+}
+
+async function ensureFingerprintMetadata(detail, options) {
+  const fingerprint = normalizeFingerprint(detail.fingerprint || detail.summary?.fingerprint || detail.summary?.values?.fingerprint);
+  const fingerprintDir = path.join(options.storageDir, fingerprint);
+  const fingerprintDirStat = await fs.stat(fingerprintDir).catch(() => null);
+
+  if (!fingerprintDirStat || !fingerprintDirStat.isDirectory()) {
+    await writeFingerprintMetadata([detail.summary], options);
+    return;
+  }
+
+  const metaPath = path.join(fingerprintDir, "meta.json");
+  const metaStat = await fs.stat(metaPath).catch(() => null);
+  if (!metaStat || !metaStat.isFile()) {
+    await writeFingerprintMetadata([detail.summary], options);
+  }
+}
+
+// 高层编排入口，负责串起查询、下载、本地目录规范化和报告生成流程。
+class BacktraceCodexTool {
+  constructor(defaultOverrides = {}) {
+    this.defaultOverrides = { ...defaultOverrides };
+  }
+
+  // 合并实例默认值和调用方覆盖值，并一次性标准化。
+  buildOptions(command, overrides = {}) {
+    return createOptions({ ...this.defaultOverrides, ...overrides, command });
+  }
+
+  // 执行一个完整的受支持命令流程。
+  async run(command, overrides = {}) {
+    const options = this.buildOptions(command, overrides);
+    // 除纯本地分析外，其余流程都依赖工作目录和存储目录先就绪。
+    await ensureDirectoryExists(options.workdir, "Working directory");
+    await ensureDirectory(options.storageDir);
+
+    if (command === "list") {
+      return listLocalFingerprints(options);
+    }
+
+    if (command === "summarize-fingerprint-errors") {
+      return summarizeFingerprintErrorLines(options);
+    }
+
+    const session = new BacktraceSession(options);
+    await session.login();
+
+    if (command === "fingerprint" && getRequestedFingerprints(options).length === 1) {
+      const detail = await queryFingerprintDetail(session, options);
+      const writtenMeta = await writeFingerprintMetadata([detail.summary], options);
+      return {
+        command,
+        mode: "detail",
+        options,
+        fingerprint: detail.fingerprint,
+        errorMessage: detail.summary.values["error.message"] || "",
+        classifiers: detail.summary.values.classifiers || "",
+        firstSeen: detail.summary.values["fingerprint;first_seen"] || "",
+        issueState: detail.summary.values["fingerprint;issues;state"] || "",
+        objectCount: detail.objects.length,
+        objects: detail.objects,
+        querySummary: detail.querySummary,
+        writtenMeta,
+      };
+    }
+
+    if (command === "collect-all") {
+      const requestedFingerprints = getRequestedFingerprints(options);
+      const sourceFingerprints = requestedFingerprints.length > 0
+        ? requestedFingerprints
+        : await getLocalFingerprints(options.storageDir);
+      const uniqueFingerprints = Array.from(new Set(sourceFingerprints.map((item) => String(item || "").trim()).filter(Boolean)));
+
+      if (uniqueFingerprints.length === 0) {
+        throw new Error("No local fingerprints found in storageDir");
+      }
+
+      const downloadedItems = [];
+      let totalRows = 0;
+      let pageLimit = 0;
+
+      for (const [fingerprintIndex, requestedFingerprint] of uniqueFingerprints.entries()) {
+        /* eslint-disable no-await-in-loop */
+        logStep("download", "processing fingerprint", {
+          current: fingerprintIndex + 1,
+          total: uniqueFingerprints.length,
+          fingerprint: requestedFingerprint,
+        });
+        const detail = await queryFingerprintDetail(session, { ...options, fingerprint: requestedFingerprint });
+        await ensureFingerprintMetadata(detail, options);
+        const rawItems = pickRandomItems(buildDownloadItemsFromDetail(detail), 10);
+        if (rawItems.length === 0) {
+          continue;
+        }
+
+        const fingerprint = await resolveCanonicalFingerprint(options.storageDir, requestedFingerprint, requestedFingerprint, options);
+        await mergeFingerprintFamilyDirectories(options.storageDir, fingerprint, [requestedFingerprint]);
+        const items = rawItems.map((item, index) => ({
+          ...item,
+          index: index + 1,
+          fingerprint,
+          values: { ...item.values, fingerprint },
+        }));
+
+        logStep("download", "starting fingerprint download phase", {
+          fingerprint,
+          objectCount: items.length,
+        });
+
+        const perFingerprintDownloaded = [];
+        for (const [itemIndex, item] of items.entries()) {
+          /* eslint-disable no-await-in-loop */
+          logStep("download", "downloading object", {
+            fingerprint,
+            current: itemIndex + 1,
+            total: items.length,
+            objectId: item.objectIdHex,
+          });
+          const downloadedItem = await downloadItemLogs(session, item, options);
+          perFingerprintDownloaded.push(downloadedItem);
+          /* eslint-enable no-await-in-loop */
+        }
+
+        downloadedItems.push(...perFingerprintDownloaded);
+        totalRows += detail.querySummary.totalRows;
+        pageLimit = Math.max(pageLimit, detail.querySummary.pageLimit || 0);
+        logStep("download", "fingerprint download phase completed", {
+          fingerprint,
+          objectCount: perFingerprintDownloaded.length,
+        });
+        /* eslint-enable no-await-in-loop */
+      }
+
+      return {
+        command,
+        options,
+        querySummary: {
+          totalRows,
+          fetchedRows: downloadedItems.length,
+          objectCount: downloadedItems.length,
+          pageLimit,
+          objectIds: downloadedItems.map((item) => item.objectIdHex),
+          selectedValues: downloadedItems.map((item) => item.values),
+        },
+        downloadedItems,
+      };
+    }
+    if (command === "fingerprint") {
+      const result = await queryAllItems(session, options);
+      const sharedQuerySummary = {
+        totalRows: result.totalRows,
+        fetchedRows: result.listedCount,
+        objectCount: result.items.length,
+        pageLimit: result.pageLimit,
+        objectIds: result.objectIds,
+        selectedValues: result.selectedValues,
+      };
+      const writtenMeta = await writeFingerprintMetadata(result.items, options);
+      return {
+        command,
+        mode: "list",
+        options,
+        querySummary: sharedQuerySummary,
+        items: result.items,
+        writtenMeta,
+      };
+    }
+
+    throw new Error(`Unsupported command: ${command}`);
+  }
+
+  // 这些便捷方法让库调用方的 API 更直观。
+  async fingerprint(overrides = {}) {
+    return this.run("fingerprint", overrides);
+  }
+
+  async list(overrides = {}) {
+    return this.run("list", overrides);
+  }
+
+  async collectAll(overrides = {}) {
+    return this.run("collect-all", overrides);
+  }
+
+  async summarizeFingerprintErrors(overrides = {}) {
+    return this.run("summarize-fingerprint-errors", overrides);
+  }
+}
+
+async function runBacktraceCommand(command, overrides = {}) {
+  const tool = new BacktraceCodexTool();
+  return tool.run(command, overrides);
+}
+
+module.exports = {
+  BacktraceCodexTool,
+  runBacktraceCommand,
+};

package/lib/backtrace/utils.js

@@ -0,0 +1,297 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+// 在查询、下载、分析、修复各阶段输出统一格式的进度日志。
+function logStep(scope, message, details) {
+  const prefix = `[backtrace-tool][${scope}]`;
+  if (details !== undefined) {
+    console.log(prefix, message, details);
+    return;
+  }
+  console.log(prefix, message);
+}
+
+// 默认把查询时间范围设为最近 24 小时，使用 Unix 秒时间戳。
+function nowRange() {
+  const now = Math.floor(Date.now() / 1000);
+  return {
+    from: "1",
+    to: String(now),
+  };
+}
+
+// 批次名使用时间戳，便于磁盘上的产物按时间自然排序。
+function formatBatchName(date) {
+  const year = String(date.getFullYear());
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hour = String(date.getHours()).padStart(2, "0");
+  const minute = String(date.getMinutes()).padStart(2, "0");
+  const second = String(date.getSeconds()).padStart(2, "0");
+  return `${year}${month}${day}-${hour}${minute}${second}`;
+}
+
+// 在作为目录名或 Map 键之前，先统一规范 fingerprint 字符串。
+function normalizeFingerprint(value) {
+  const fingerprint = String(value || "").trim().toLowerCase();
+  return fingerprint || "unknown-fingerprint";
+}
+
+// 获取一个 fingerprint 家族在存储目录下的根路径。
+function getFingerprintRoot(storageDir, fingerprint) {
+  return path.join(storageDir, normalizeFingerprint(fingerprint));
+}
+
+// 原始下载附件统一存放到 logs 子目录。
+function getFingerprintLogsRoot(storageDir, fingerprint) {
+  return path.join(getFingerprintRoot(storageDir, fingerprint), "logs");
+}
+
+// 生成的 markdown 和 json 报告统一存放到 reports 子目录。
+function getFingerprintReportsRoot(storageDir, fingerprint) {
+  return path.join(getFingerprintRoot(storageDir, fingerprint), "reports");
+}
+
+// 把前缀匹配的 fingerprint 视为同一家族，便于把截断值合并到一起。
+function areFingerprintsRelated(left, right) {
+  const normalizedLeft = normalizeFingerprint(left);
+  const normalizedRight = normalizeFingerprint(right);
+  if (normalizedLeft === "unknown-fingerprint" || normalizedRight === "unknown-fingerprint") {
+    return false;
+  }
+  return normalizedLeft === normalizedRight
+    || normalizedLeft.startsWith(normalizedRight)
+    || normalizedRight.startsWith(normalizedLeft);
+}
+
+// 读取本地所有 fingerprint 目录及其时间信息，供调用方选出规范目录。
+async function listExistingFingerprintDirectories(storageDir) {
+  const directories = await fs.readdir(storageDir, { withFileTypes: true }).catch(() => []);
+  return Promise.all(
+    directories
+      .filter((entry) => entry.isDirectory())
+      .map(async (entry) => {
+        const absolutePath = path.join(storageDir, entry.name);
+        const stats = await fs.stat(absolutePath).catch(() => null);
+        return {
+          name: normalizeFingerprint(entry.name),
+          absolutePath,
+          birthtimeMs: stats?.birthtimeMs || 0,
+          ctimeMs: stats?.ctimeMs || 0,
+        };
+      }),
+  );
+}
+
+// 优先复用最早创建的相关本地 fingerprint 目录，
+// 让重复下载和分析都落到同一个规范路径下。
+async function resolveCanonicalFingerprint(storageDir, preferredFingerprint, fallbackFingerprint = "", runtimeState = null) {
+  const candidates = [preferredFingerprint, fallbackFingerprint]
+    .map((item) => normalizeFingerprint(item))
+    .filter((item) => item && item !== "unknown-fingerprint");
+
+  const cachedFingerprint = runtimeState && runtimeState.canonicalFingerprintFamily
+    ? normalizeFingerprint(runtimeState.canonicalFingerprintFamily)
+    : "";
+  if (cachedFingerprint) {
+    const canReuseCached = candidates.some((candidate) => areFingerprintsRelated(candidate, cachedFingerprint));
+    if (canReuseCached) {
+      return cachedFingerprint;
+    }
+  }
+
+  const existingDirectories = await listExistingFingerprintDirectories(storageDir);
+  const relatedDirectories = existingDirectories.filter((entry) => {
+    return candidates.some((candidate) => areFingerprintsRelated(entry.name, candidate));
+  });
+
+  if (relatedDirectories.length > 0) {
+    const canonical = relatedDirectories
+      .sort((a, b) => (a.birthtimeMs || a.ctimeMs || 0) - (b.birthtimeMs || b.ctimeMs || 0) || a.name.localeCompare(b.name))[0]
+      .name;
+    if (runtimeState) {
+      runtimeState.canonicalFingerprintFamily = canonical;
+    }
+    return canonical;
+  }
+
+  const resolved = normalizeFingerprint(preferredFingerprint || fallbackFingerprint);
+  if (runtimeState && resolved !== "unknown-fingerprint") {
+    runtimeState.canonicalFingerprintFamily = resolved;
+  }
+  return resolved;
+}
+
+// 递归把别名目录内容合并到规范 fingerprint 目录中。
+async function mergeDirectoryContents(sourceDir, targetDir) {
+  const sourceStats = await fs.stat(sourceDir).catch(() => null);
+  if (!sourceStats || !sourceStats.isDirectory()) {
+    return;
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      await mergeDirectoryContents(sourcePath, targetPath);
+      const remaining = await fs.readdir(sourcePath).catch(() => []);
+      if (remaining.length === 0) {
+        await fs.rmdir(sourcePath).catch(() => {});
+      }
+      continue;
+    }
+    const targetStats = await fs.stat(targetPath).catch(() => null);
+    if (!targetStats) {
+      await fs.rename(sourcePath, targetPath).catch(async () => {
+        const data = await fs.readFile(sourcePath);
+        await fs.writeFile(targetPath, data);
+        await fs.unlink(sourcePath).catch(() => {});
+      });
+    }
+  }
+}
+
+// 把所有相关 fingerprint 别名目录收敛到同一个规范目录树下。
+async function mergeFingerprintFamilyDirectories(storageDir, canonicalFingerprint, relatedFingerprints) {
+  const canonical = normalizeFingerprint(canonicalFingerprint);
+  if (!canonical || canonical === "unknown-fingerprint") {
+    return canonical;
+  }
+
+  const directoryEntries = await listExistingFingerprintDirectories(storageDir);
+  const aliases = new Set(
+    [canonical, ...(relatedFingerprints || [])]
+      .map((item) => normalizeFingerprint(item))
+      .filter((item) => item && item !== "unknown-fingerprint"),
+  );
+
+  directoryEntries.forEach((entry) => {
+    if ([...aliases].some((candidate) => areFingerprintsRelated(entry.name, candidate))) {
+      aliases.add(entry.name);
+    }
+  });
+
+  const canonicalRoot = getFingerprintRoot(storageDir, canonical);
+  await fs.mkdir(canonicalRoot, { recursive: true });
+
+  for (const alias of aliases) {
+    if (alias === canonical) {
+      continue;
+    }
+    const aliasRoot = getFingerprintRoot(storageDir, alias);
+    const aliasStats = await fs.stat(aliasRoot).catch(() => null);
+    if (!aliasStats || !aliasStats.isDirectory()) {
+      continue;
+    }
+    await mergeDirectoryContents(aliasRoot, canonicalRoot);
+    const remaining = await fs.readdir(aliasRoot).catch(() => []);
+    if (remaining.length === 0) {
+      await fs.rmdir(aliasRoot).catch(() => {});
+    }
+    logStep("download", "merged fingerprint alias directory", { alias, canonical });
+  }
+
+  return canonical;
+}
+
+// 当接口元数据不足时，基于文件名推断一个粗粒度 content type。
+function inferContentType(fileName) {
+  const ext = path.extname(String(fileName || "")).toLowerCase();
+  if (ext === ".log" || ext === ".txt" || ext === ".xml" || ext === ".json" || ext === ".md") {
+    return "text/plain";
+  }
+  return "application/octet-stream";
+}
+
+// 重试流程里使用的简单休眠工具。
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// 为瞬时失败任务提供统一的重试、退避和日志输出。
+async function retry(label, maxAttempts, task) {
+  let lastError = null;
+  let attempt = 1;
+
+  while (maxAttempts === 0 || attempt <= maxAttempts) {
+    try {
+      if (attempt > 1) {
+        logStep("retry", `${label} retry`, { attempt, maxAttempts });
+      }
+      return await task(attempt);
+    } catch (error) {
+      lastError = error;
+      logStep("retry", `${label} failed`, {
+        attempt,
+        maxAttempts,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      const delayMs = Math.min(10000, 5000 + Math.floor(Math.random() * 5001));
+      logStep("retry", `${label} waiting before retry`, { attempt, delayMs });
+      await sleep(delayMs);
+      attempt += 1;
+    }
+  }
+
+  throw lastError;
+}
+
+// 对必须存在的目录做快速校验，避免后续流程在更深处失败。
+async function ensureDirectoryExists(targetPath, label) {
+  const stats = await fs.stat(targetPath).catch(() => null);
+  if (!stats || !stats.isDirectory()) {
+    throw new Error(`${label} does not exist or is not a directory: ${targetPath}`);
+  }
+}
+
+// 按需创建下载和报告所需目录。
+async function ensureDirectory(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+// 在限制并发度的前提下执行异步任务，并保持结果顺序与输入一致。
+async function mapWithConcurrency(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  // 每个 worker 都从共享索引里领取下一个任务，直到队列耗尽。
+  async function runWorker() {
+    while (true) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      if (currentIndex >= items.length) {
+        return;
+      }
+      /* eslint-disable no-await-in-loop */
+      results[currentIndex] = await worker(items[currentIndex], currentIndex);
+      /* eslint-enable no-await-in-loop */
+    }
+  }
+
+  const workerCount = Math.min(concurrency, items.length);
+  await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
+  return results;
+}
+
+module.exports = {
+  logStep,
+  nowRange,
+  formatBatchName,
+  normalizeFingerprint,
+  getFingerprintRoot,
+  getFingerprintLogsRoot,
+  getFingerprintReportsRoot,
+  areFingerprintsRelated,
+  listExistingFingerprintDirectories,
+  resolveCanonicalFingerprint,
+  mergeFingerprintFamilyDirectories,
+  inferContentType,
+  retry,
+  ensureDirectoryExists,
+  ensureDirectory,
+  mapWithConcurrency,
+};