chatbot-analyze-qweasd 1.0.0

package/apiflow5.mjs

@@ -0,0 +1,1036 @@
+#!/usr/bin/env node
+/**
+ * apiflow5: staged function flow -> flowchart SVG
+ * Stage 1: overview with checks
+ * Stage 2: detail for a selected node
+ * Requirements:
+ * - `codex` CLI available in PATH
+ * - devDep: @mermaid-js/mermaid-cli (provides mmdc)
+ * - schema: ir5-stage1.schema.json / ir5-stage2.schema.json
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import path from "node:path";
+
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+// 進度輸出（給 GUI 捕獲）
+function emitProgress(stage, percent, message) {
+  const payload = JSON.stringify({ stage, percent, message });
+  console.error(`[PROGRESS] ${payload}`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    folder: process.cwd(),
+    project: "",
+    query: "",
+    path: "",
+    out: "",
+    schema: "",
+    wrap: 85,
+    keep: false,
+    stage: 1,
+    node: "",
+    nodeLabel: "",
+    nodeFocus: ""
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => (i + 1 < argv.length ? argv[++i] : "");
+
+    if (a === "--folder" || a === "-f") args.folder = next();
+    else if (a === "--project" || a === "-p") args.project = next();
+    else if (a === "--path") args.path = next();
+    else if (a === "--query") args.query = next();
+    else if (a === "--out" || a === "-o") args.out = next();
+    else if (a === "--schema") args.schema = next();
+    else if (a === "--wrap") args.wrap = Number(next() || "85");
+    else if (a === "--keep") args.keep = true;
+    else if (a === "--stage") args.stage = Number(next() || "1");
+    else if (a === "--node") args.node = next();
+    else if (a === "--node-label") args.nodeLabel = next();
+    else if (a === "--node-focus") args.nodeFocus = next();
+    else if (a === "--help" || a === "-h") args.help = true;
+  }
+
+  // 支援兩種輸入：--path 或 --query
+  // --path 會自動組成 query: `path: ...`
+  if (!args.query && args.path) args.query = `path: ${args.path}`;
+
+  return args;
+}
+
+function help() {
+  console.log(`
+用法：
+  apiflow5 --folder <workspaceRoot> --project <projectName> --path "<symbol>" --out <svgPath> --stage 1
+  apiflow5 --folder <workspaceRoot> --project <projectName> --path "<symbol>" --out <svgPath> --stage 2 --node <nodeId>
+
+範例：
+  apiflow5 --folder /Users/Timothy/IdeaProjects --project gemini \\
+    --path "ai.omnichat.service.AiService#enterAiSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, ai.omnichat.dto.social.webhook.OcMessage)" \\
+    --out dist/flow.svg --stage 1
+
+參數：
+  --folder, -f   workspace 根目錄（folder A）
+  --project,-p   目標 project 名稱（例如 gemini）
+  --path         function/symbol 位置（會自動變成 query: path: ...）
+  --query        直接給 codex 用的查詢（若你不用 --path）
+  --out, -o      輸出 svg 檔案路徑
+  --schema       schema 檔路徑（預設：stage1/2 的 schema）
+  --wrap         label 自動換行寬度（預設 85）
+  --keep         保留中間檔（ir.json / flow-stage1.mmd / flow-stage2.mmd / codex.last.json）
+  --stage        1=概要 2=細化（預設 1）
+  --node         stage=2 時要細化的節點 id
+  --node-label   stage=2 時節點 label（選填）
+  --node-focus   stage=2 時節點 focus（選填）
+`.trim());
+}
+
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { ...opts, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    p.stdout.on("data", (d) => (out += d.toString("utf8")));
+    p.stderr.on("data", (d) => (err += d.toString("utf8")));
+    p.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`${cmd} exit ${code}\n${err}`));
+      resolve({ out, err });
+    });
+  });
+}
+
+function runCmdWithInput(cmd, args, input, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { ...opts, stdio: ["pipe", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    p.stdout.on("data", (d) => (out += d.toString("utf8")));
+    p.stderr.on("data", (d) => (err += d.toString("utf8")));
+    p.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`${cmd} exit ${code}\n${err}`));
+      resolve({ out, err });
+    });
+    p.stdin.write(input || "");
+    p.stdin.end();
+  });
+}
+
+function escapeText(s) {
+  return String(s).replace(/\r?\n/g, " ").replace(/"/g, "'");
+}
+
+function wrapText(text, maxLen = 85) {
+  const s = String(text);
+  if (s.length <= maxLen) return s;
+
+  // 先以 <br/> 為硬換行，避免把 HTML tag 切爛
+  const hardLines = s.split("<br/>");
+
+  const wrapped = hardLines.map((line) => {
+    if (line.length <= maxLen) return line;
+
+    const parts = line.split(/([\/\-\_\s\|\(\)\,\:])/);
+    const lines = [];
+    let current = "";
+
+    for (const part of parts) {
+      if (!part) continue;
+      if ((current + part).length > maxLen) {
+        if (current.trim()) lines.push(current.trim());
+        current = part;
+      } else {
+        current += part;
+      }
+    }
+    if (current.trim()) lines.push(current.trim());
+    return lines.join("<br/>");
+  });
+
+  return wrapped.join("<br/>");
+}
+
+function pid(name) {
+  return String(name || "unknown").replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+function normalizeProjectName(p) {
+  if (!p) return "unknown";
+  return String(p).trim() || "unknown";
+}
+
+function extractFeatureToggle(text) {
+  const m = String(text || "").match(/\bImTeamFeature\.([A-Z0-9_]+)\b/);
+  return m ? m[1] : "";
+}
+
+const classLocationCache = new Map();
+const methodLocationCache = new Map();
+
+function resolveCallLocation({ folder, project, className, methodName }) {
+  if (!folder || !project || !className) return null;
+  const cacheKey = [project, className, methodName || ""].join("::");
+  if (classLocationCache.has(cacheKey)) return classLocationCache.get(cacheKey);
+  const projectRoot = path.join(folder, project);
+  const safeClass = className.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const defPattern = `\\b(interface|class|enum)\\s+${safeClass}\\b`;
+
+  const findDef = spawnSync(
+    "rg",
+    ["-n", "-m", "1", "--glob", "*.java", "--glob", "*.kt", defPattern],
+    { cwd: projectRoot, encoding: "utf8" }
+  );
+  if (findDef.error || findDef.status !== 0 || !findDef.stdout) {
+    classLocationCache.set(cacheKey, null);
+    return null;
+  }
+
+  const defLine = findDef.stdout.trim().split("\n")[0];
+  const match = defLine.match(/^(.+?):(\d+):/);
+  if (!match) {
+    classLocationCache.set(cacheKey, null);
+    return null;
+  }
+  const fileRel = match[1];
+  const defLineNum = Number(match[2]) || null;
+
+  let methodLine = defLineNum;
+  if (methodName) {
+    const findMethod = spawnSync(
+      "rg",
+      ["-n", "-m", "1", "--fixed-strings", methodName, fileRel],
+      { cwd: projectRoot, encoding: "utf8" }
+    );
+    if (!findMethod.error && findMethod.status === 0 && findMethod.stdout) {
+      const methodMatch = findMethod.stdout.trim().match(/^.+?:(\d+):/);
+      if (methodMatch) methodLine = Number(methodMatch[1]) || methodLine;
+    }
+  }
+
+  const result = { file: fileRel, line: methodLine };
+  classLocationCache.set(cacheKey, result);
+  return result;
+}
+
+function resolveMethodInProject({ folder, project, methodName }) {
+  if (!folder || !project || !methodName) return null;
+  const cacheKey = [project, methodName].join("::");
+  if (methodLocationCache.has(cacheKey)) return methodLocationCache.get(cacheKey);
+  const projectRoot = path.join(folder, project);
+  const safeMethod = methodName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = `\\b${safeMethod}\\s*\\(`;
+
+  const findMethod = spawnSync(
+    "rg",
+    ["-n", "-m", "1", "--glob", "*.java", "--glob", "*.kt", pattern],
+    { cwd: projectRoot, encoding: "utf8" }
+  );
+  if (findMethod.error || findMethod.status !== 0 || !findMethod.stdout) {
+    methodLocationCache.set(cacheKey, null);
+    return null;
+  }
+  const match = findMethod.stdout.trim().match(/^(.+?):(\d+):/);
+  if (!match) {
+    methodLocationCache.set(cacheKey, null);
+    return null;
+  }
+  const result = { file: match[1], line: Number(match[2]) || null };
+  methodLocationCache.set(cacheKey, result);
+  return result;
+}
+
+function resolveMethodInFile({ folder, project, fileRel, methodName }) {
+  if (!folder || !project || !fileRel || !methodName) return null;
+  const cacheKey = [project, fileRel, methodName].join("::");
+  if (methodLocationCache.has(cacheKey)) return methodLocationCache.get(cacheKey);
+  const projectRoot = path.join(folder, project);
+  const findMethod = spawnSync(
+    "rg",
+    ["-n", "-m", "1", "--fixed-strings", `${methodName}(`, fileRel],
+    { cwd: projectRoot, encoding: "utf8" }
+  );
+  if (findMethod.error || findMethod.status !== 0 || !findMethod.stdout) {
+    methodLocationCache.set(cacheKey, null);
+    return null;
+  }
+  const match = findMethod.stdout.trim().match(/^.+?:(\d+):/);
+  if (!match) {
+    methodLocationCache.set(cacheKey, null);
+    return null;
+  }
+  const result = { file: fileRel, line: Number(match[1]) || null };
+  methodLocationCache.set(cacheKey, result);
+  return result;
+}
+
+function buildMethodIndexFromFile({ folder, project, fileRel }) {
+  if (!folder || !project || !fileRel) return {};
+  const projectRoot = path.join(folder, project);
+  try {
+    const text = readFileSync(path.join(projectRoot, fileRel), "utf8");
+    const lines = text.split(/\r?\n/);
+    const map = {};
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let match = line.match(/^\s*(public|protected|private|\s)*\s*(static\s+)?[\w<>\[\], ?]+\s+([A-Za-z_][\w]*)\s*\(/);
+      if (match && !map[match[3]]) {
+        map[match[3]] = i + 1;
+        continue;
+      }
+      match = line.match(/^\s*fun\s+([A-Za-z_][\w]*)\s*\(/);
+      if (match && !map[match[1]]) {
+        map[match[1]] = i + 1;
+      }
+    }
+    return map;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 預處理：提取目標函數的程式碼上下文
+ * 這樣 Codex 就不需要自己搜尋，可以直接分析
+ */
+async function extractContext({ folder, project, functionPath, onProgress }) {
+  const projectRoot = path.join(folder, project);
+
+  // 解析 functionPath: ai.omnichat.service.AiService#enterAiSession(...)
+  const hashIdx = functionPath.indexOf("#");
+  let className, methodName, fullClassName;
+
+  if (hashIdx !== -1) {
+    fullClassName = functionPath.slice(0, hashIdx);
+    const methodPart = functionPath.slice(hashIdx + 1);
+    methodName = methodPart.replace(/\(.*\)$/, ""); // 去掉參數
+    className = fullClassName.split(".").pop();
+  } else {
+    fullClassName = functionPath;
+    className = functionPath.split(".").pop();
+    methodName = null;
+  }
+
+  onProgress?.({ stage: 1, percent: 10, message: `正在尋找 ${className}...` });
+
+  // Step 1: 用 rg 找到 class 定義的檔案
+  const safeClass = className.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const classPattern = `\\b(class|interface|enum)\\s+${safeClass}\\b`;
+
+  const findClass = spawnSync(
+    "rg",
+    ["-l", "--glob", "*.java", "--glob", "*.kt", classPattern],
+    { cwd: projectRoot, encoding: "utf8" }
+  );
+
+  if (findClass.error || findClass.status !== 0 || !findClass.stdout.trim()) {
+    return {
+      success: false,
+      error: `找不到 class: ${className}`,
+      extractedCode: null,
+      filePath: null,
+      imports: []
+    };
+  }
+
+  const files = findClass.stdout.trim().split("\n").filter(Boolean);
+  // 優先選擇名稱完全匹配的檔案
+  let targetFile = files.find(f => f.endsWith(`${className}.java`) || f.endsWith(`${className}.kt`)) || files[0];
+
+  onProgress?.({ stage: 1, percent: 20, message: `找到檔案: ${targetFile}` });
+
+  // Step 2: 讀取整個檔案
+  const fullPath = path.join(projectRoot, targetFile);
+  let fileContent;
+  try {
+    fileContent = readFileSync(fullPath, "utf8");
+  } catch (err) {
+    return {
+      success: false,
+      error: `無法讀取檔案: ${fullPath}`,
+      extractedCode: null,
+      filePath: null,
+      imports: []
+    };
+  }
+
+  const lines = fileContent.split("\n");
+
+  // Step 3: 提取 import 語句
+  const imports = [];
+  for (const line of lines) {
+    const importMatch = line.match(/^\s*import\s+(.+?)\s*;/);
+    if (importMatch) {
+      imports.push(importMatch[1]);
+    }
+  }
+
+  onProgress?.({ stage: 1, percent: 25, message: `提取了 ${imports.length} 個 import` });
+
+  // Step 4: 如果有 methodName，提取該方法；否則提取整個 class
+  let extractedCode;
+  let methodStartLine = null;
+  let methodEndLine = null;
+
+  if (methodName) {
+    onProgress?.({ stage: 1, percent: 28, message: `正在提取方法: ${methodName}...` });
+
+    // 找到方法定義行
+    // 匹配模式：方法名後面跟著 (，前面是修飾符和回傳類型
+    const methodPattern = new RegExp(
+      `\\b${methodName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\(`
+    );
+
+    for (let i = 0; i < lines.length; i++) {
+      if (methodPattern.test(lines[i])) {
+        // 確認這是方法定義（不是呼叫）- 前面應該有類型或修飾符
+        const prevChars = lines[i].slice(0, lines[i].search(methodPattern));
+        if (/\b(public|private|protected|static|final|void|int|long|String|boolean|List|Map|Set|Optional|\w+)\s*$/.test(prevChars) ||
+            /^\s*(public|private|protected|static|final|abstract|synchronized|@\w+)/.test(lines[i])) {
+          methodStartLine = i;
+          break;
+        }
+      }
+    }
+
+    if (methodStartLine !== null) {
+      // 使用 brace matching 找到方法結束
+      let braceCount = 0;
+      let foundFirstBrace = false;
+
+      for (let i = methodStartLine; i < lines.length; i++) {
+        for (const char of lines[i]) {
+          if (char === "{") {
+            braceCount++;
+            foundFirstBrace = true;
+          } else if (char === "}") {
+            braceCount--;
+          }
+        }
+
+        if (foundFirstBrace && braceCount === 0) {
+          methodEndLine = i;
+          break;
+        }
+      }
+
+      if (methodEndLine !== null) {
+        // 往上找 annotation（@Override, @Transactional 等）
+        let annotationStart = methodStartLine;
+        for (let i = methodStartLine - 1; i >= 0; i--) {
+          const trimmed = lines[i].trim();
+          if (trimmed.startsWith("@") || trimmed === "") {
+            annotationStart = i;
+          } else {
+            break;
+          }
+        }
+
+        extractedCode = lines.slice(annotationStart, methodEndLine + 1).join("\n");
+      }
+    }
+  }
+
+  // 如果沒找到方法，或者沒指定方法，就提取整個 class（但限制長度）
+  if (!extractedCode) {
+    onProgress?.({ stage: 1, percent: 28, message: `提取整個 class...` });
+
+    // 找到 class 定義開始
+    let classStartLine = null;
+    for (let i = 0; i < lines.length; i++) {
+      if (new RegExp(classPattern).test(lines[i])) {
+        classStartLine = i;
+        break;
+      }
+    }
+
+    if (classStartLine !== null) {
+      // 限制最多 300 行
+      const maxLines = Math.min(lines.length, classStartLine + 300);
+      extractedCode = lines.slice(0, maxLines).join("\n");
+      if (maxLines < lines.length) {
+        extractedCode += "\n// ... (truncated, total " + lines.length + " lines)";
+      }
+    } else {
+      // fallback: 取前 300 行
+      extractedCode = lines.slice(0, 300).join("\n");
+    }
+  }
+
+  onProgress?.({ stage: 1, percent: 30, message: `程式碼提取完成 (${extractedCode.split("\n").length} 行)` });
+
+  return {
+    success: true,
+    error: null,
+    extractedCode,
+    filePath: targetFile,
+    fullPath,
+    className,
+    methodName,
+    fullClassName,
+    imports,
+    methodStartLine: methodStartLine !== null ? methodStartLine + 1 : null, // 1-based
+    methodEndLine: methodEndLine !== null ? methodEndLine + 1 : null
+  };
+}
+
+function isNoise(call) {
+  const t = `${call.from} ${call.to}`.toLowerCase();
+
+  // Framework 內部方法（不是真正的 API 呼叫）
+  // 匹配 #execute, #doExecute, #exchange, #getDatabase 等結尾
+  if (/#(execute|doexecute|exchange|invoke|call|doinvoke|request|send|getdatabase|getcollection|getconnection)$/i.test(call.to || "")) {
+    return true;
+  }
+
+  return (
+    t.includes("mongotemplate") ||
+    t.includes("mongorepository") ||
+    t.includes("mongodb") ||
+    t.includes("mongodbmanager") ||
+    t.includes("mongoclient") ||
+    t.includes("datasource") ||
+    t.includes("connectionpool") ||
+    t.includes("mapper#") ||
+    t.includes("mybatis") ||
+    t.includes("repo#") ||
+    t.includes("repository#") ||
+    t.includes("springframework") ||
+    t.includes("resttemplate") ||
+    t.includes("restclient") ||
+    t.includes("webclient") ||
+    t.includes("httpclient") ||
+    t.includes("hikari") ||
+    t.includes("jdbctemplate")
+  );
+}
+
+function splitMember(ref) {
+  const s = String(ref || "");
+  const idx = s.lastIndexOf("#");
+  if (idx === -1) return { owner: s, member: "" };
+  return { owner: s.slice(0, idx), member: s.slice(idx + 1) };
+}
+function shortClassName(owner) {
+  const s = String(owner || "");
+  const parts = s.split(".");
+  return parts[parts.length - 1] || s;
+}
+function methodFirstLabel(ref) {
+  const { owner, member } = splitMember(ref);
+  const cls = shortClassName(owner);
+  if (member) return `${escapeText(member)}<br/>${escapeText(cls)}`;
+  return escapeText(cls);
+}
+
+// 簡潔版：只取方法名
+function methodOnlyLabel(ref) {
+  const { member } = splitMember(ref);
+  // 去掉參數列表，只保留方法名
+  const methodName = member ? member.replace(/\(.*\)$/, "") : "";
+  return methodName ? escapeText(methodName) : escapeText(shortClassName(ref));
+}
+
+// 抽 endpoint（可選）
+function extractEndpointFromEvidence(evidence) {
+  const e = String(evidence || "");
+  const m1 = e.match(/@(Get|Post|Put|Patch|Delete)Mapping\(\s*["']([^"']+)["']\s*\)/i);
+  if (m1) return `${m1[1].toUpperCase()} ${m1[2]}`;
+  const m2 = e.match(/\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b\s+([\/][^\s,"')]+)/i);
+  if (m2) return `${m2[1].toUpperCase()} ${m2[2]}`;
+  return null;
+}
+
+function buildPrompt({ project, query, context, stage, focus }) {
+  const baseRules = `
+你是程式碼分析助手，請在目前 workspace（你啟動所在資料夾）分析程式碼。
+
+【硬性規則】
+- 只允許輸出 JSON，禁止輸出任何解釋文字、Markdown
+- 輸出必須完全符合 JSON Schema；若無法符合，請自行調整直到符合
+- 只分析指定 function 本體，不展開被呼叫的 function 內部
+`.trim();
+
+  const headerFromContext = context && context.success && context.extractedCode
+    ? (() => {
+        const fileInfo = context.filePath ? `檔案: ${context.filePath}` : "";
+        const lineInfo = context.methodStartLine ? ` (行 ${context.methodStartLine}-${context.methodEndLine})` : "";
+        const importsInfo = context.imports.length > 0
+          ? `\n相關 imports:\n${context.imports.slice(0, 20).map(i => `  - ${i}`).join("\n")}`
+          : "";
+        return `
+${baseRules}
+
+【分析目標】
+project: ${project}
+class: ${context.fullClassName || context.className}
+method: ${context.methodName || "(整個 class)"}
+${fileInfo}${lineInfo}
+${importsInfo}
+
+【已提取的程式碼】
+\`\`\`java
+${context.extractedCode}
+\`\`\`
+`.trim();
+      })()
+    : `
+${baseRules}
+
+【分析入口】
+project: ${project}
+${query}
+`.trim();
+
+  if (stage === 2) {
+    return `
+${headerFromContext}
+
+【細化目標】
+focus_node: ${focus?.id || ""}
+focus_label: ${focus?.label || ""}
+focus_hint: ${focus?.focus || ""}
+
+【任務】
+1) 只針對 focus_node 對應的那一段流程做「細節化」展開。
+2) 只涵蓋 A function 本體，不展開被呼叫方法內部。
+3) 以流程圖輸出，包含 start 與 end 節點。
+4) if 節點需提供條件，edges 用 label 標示 true/false。
+5) call 節點需提供簡短功能描述（1-2 句），可根據命名/註解推測。
+6) 外部呼叫（HTTP/DB/第三方）只需顯示呼叫名稱或 endpoint，不需展開。
+7) 遇到 return 就結束流程，不要列出 return 之後的語句或步驟。
+8) 不要把「解析錯誤/JSON parse」這類內部處理訊息當成流程步驟。
+9) DB 查詢（例如 findByTeamAndChannelIdAndUserId）只需顯示方法名，不要附加說明。
+
+【節點欄位說明】
+- call 節點需帶 call 欄位：
+  - name: 呼叫目標全名（盡量包含 class#method）
+  - kind: method/http/db/external/unknown
+  - project/file/line: 若為專案內部方法，請提供檔案相對路徑與行號
+- label: 用於圖上顯示，請簡短
+- summary: call 節點的功能描述（1-2 句，純文字）
+
+【輸出資料結構】
+- focus_node: 必須等於 focus_node
+- nodes: 流程節點列表，id 請用簡單編號（如 n1, n2, n3）。
+- edges: 連線關係，if 分支用 label 標示 true/false。
+- 所有欄位都必須出現，若沒有值請填 null。
+`.trim();
+  }
+
+  return `
+${headerFromContext}
+
+【任務】
+1) 產生「概要流程圖」，只涵蓋 A function 的主要步驟與檢核點。
+2) nodes/edges 以步驟順序描述呼叫與 if 判斷，避免過細節。
+3) 對重要檢核/外部呼叫節點填寫 focus（供後續細化用）。
+4) call 節點需提供簡短功能描述（1-2 句），可根據命名/註解推測。
+5) 外部呼叫（HTTP/DB/第三方）只需顯示呼叫名稱或 endpoint，不需展開。
+6) if 節點需提供條件，並用 edges 標記 true/false。
+7) 若為專案內部方法，盡量提供檔案路徑與行號（相對於專案根目錄）。
+8) nodes 請包含 start 與 end 節點，並把流程串起來。
+9) 遇到 return 就結束流程，不要列出 return 之後的語句或步驟。
+10) 不要把「解析錯誤/JSON parse」這類內部處理訊息當成流程步驟。
+11) DB 查詢（例如 findByTeamAndChannelIdAndUserId）只需顯示方法名，不要附加說明。
+
+【節點欄位說明】
+- call 節點需帶 call 欄位：
+  - name: 呼叫目標全名（盡量包含 class#method）
+  - kind: method/http/db/external/unknown
+  - project/file/line: 若為專案內部方法，請提供檔案相對路徑與行號
+- label: 用於圖上顯示，請簡短
+- summary: call 節點的功能描述（1-2 句，純文字）
+- focus: 需要細化的節點用簡短關鍵字描述；不需要細化則填 null
+
+【輸出資料結構】
+- nodes: 流程節點列表，id 請用簡單編號（如 n1, n2, n3）。
+- edges: 連線關係，if 分支用 label 標示 true/false。
+- 所有欄位都必須出現，若沒有值請填 null。
+`.trim();
+}
+
+async function runCodexIR({ folder, schemaPath, project, query, keepDir, context, stage, focus }) {
+  const prompt = buildPrompt({ project, query, context, stage, focus });
+  const outputPath = keepDir
+    ? path.join(keepDir, "codex.last.json")
+    : path.join(folder, ".apiflow.tmp.codex.json");
+
+  // 如果有預提取的程式碼，不需要 --cd（避免 Codex 索引整個 workspace）
+  const hasExtractedCode = context?.success && context?.extractedCode;
+
+  const args = hasExtractedCode
+    ? [
+        "exec",
+        "--output-schema",
+        schemaPath,
+        "--output-last-message",
+        outputPath,
+        "-"
+      ]
+    : [
+        "exec",
+        "--output-schema",
+        schemaPath,
+        "--output-last-message",
+        outputPath,
+        "--cd",
+        folder,
+        "-"
+      ];
+
+  await runCmdWithInput("codex", args, prompt, { cwd: folder });
+  const jsonText = readFileSync(outputPath, "utf8");
+
+  let structured = null;
+  try {
+    structured = JSON.parse(jsonText);
+  } catch (err) {
+    die("codex 輸出不是有效 JSON，請確認 --output-schema 或 prompt 是否正確。");
+  }
+
+  if (keepDir) {
+    writeFileSync(path.join(keepDir, "codex.last.json"), JSON.stringify(structured, null, 2), "utf8");
+    writeFileSync(path.join(keepDir, "ir.json"), JSON.stringify(structured, null, 2), "utf8");
+  } else {
+    try {
+      unlinkSync(outputPath);
+    } catch {}
+  }
+
+  return structured;
+}
+
+function renderMermaidFlowchart(ir, wrapWidth = 85, opts = {}) {
+  const folder = opts.folder || "";
+  const targetProject = normalizeProjectName(ir.target_project || opts.defaultProject || "");
+  const entryName = String(ir.entry || "");
+  const entryOwner = entryName.split("#")[0] || "";
+  const entryClass = entryOwner.split(".").pop() || "";
+  const entryMethod = (entryName.split("#")[1] || "").replace(/\(.*\)$/, "");
+  const entryLocation = resolveCallLocation({
+    folder,
+    project: targetProject,
+    className: entryClass,
+    methodName: entryMethod
+  });
+  const entryMethodIndex = entryLocation
+    ? buildMethodIndexFromFile({
+        folder,
+        project: targetProject,
+        fileRel: entryLocation.file
+      })
+    : {};
+  const allNodes = Array.isArray(ir.nodes) ? ir.nodes : [];
+  const allEdges = Array.isArray(ir.edges) ? ir.edges : [];
+  const noisePatterns = [
+    /parse error json/i,
+    /parse json string/i,
+    /json parse/i
+  ];
+  const isNoise = (node) => {
+    const text = `${node?.label || ""} ${node?.summary || ""}`.trim();
+    return noisePatterns.some((re) => re.test(text));
+  };
+
+  const nodes = allNodes.filter((n) => !isNoise(n));
+  const validIds = new Set(nodes.map((n) => n.id));
+  const edges = allEdges.filter((e) => validIds.has(e.from) && validIds.has(e.to));
+  const functionMap = {};
+
+  const idMap = new Map();
+  const getId = (id) => {
+    if (!idMap.has(id)) idMap.set(id, pid(id));
+    return idMap.get(id);
+  };
+
+  let mmd = "";
+  mmd += "flowchart TD\n";
+
+  for (const node of nodes) {
+    let callInfo = node.call ? { ...node.call } : null;
+    const feature = node.type === "if"
+      ? extractFeatureToggle(`${node.condition || ""} ${node.label || ""} ${node.summary || ""} ${callInfo?.name || ""}`)
+      : "";
+    const nodeLabelOverride = feature ? `feature toggle: ${feature}` : "";
+    if (node.type === "call" && callInfo && !callInfo.project && targetProject !== "unknown") {
+      callInfo.project = targetProject;
+    }
+    if (node.type === "call" && callInfo && !callInfo.file && callInfo.name) {
+      const owner = callInfo.name.split("#")[0] || "";
+      const methodName = (callInfo.name.split("#")[1] || "").replace(/\(.*\)$/, "");
+      const className = owner.split(".").pop() || owner;
+      const resolved = resolveCallLocation({
+        folder,
+        project: callInfo.project || targetProject,
+        className,
+        methodName
+      });
+      if (resolved) {
+        callInfo.file = resolved.file;
+        callInfo.line = resolved.line;
+      } else if (entryLocation && methodName) {
+        const localLine = entryMethodIndex[methodName];
+        if (localLine) {
+          callInfo.file = entryLocation.file;
+          callInfo.line = localLine;
+        } else {
+          const any = resolveMethodInProject({
+            folder,
+            project: callInfo.project || targetProject,
+            methodName
+          });
+          if (any) {
+            callInfo.file = any.file;
+            callInfo.line = any.line;
+          }
+        }
+      } else if (methodName) {
+        const any = resolveMethodInProject({
+          folder,
+          project: callInfo.project || targetProject,
+          methodName
+        });
+        if (any) {
+          callInfo.file = any.file;
+          callInfo.line = any.line;
+        }
+      }
+    }
+
+    const safeId = getId(node.id || "");
+    const labelBase = wrapText(escapeText(nodeLabelOverride || node.label || ""), wrapWidth);
+    const isDbCall = node.type === "call" && callInfo && callInfo.kind === "db";
+    const summary = !isDbCall && node.summary ? wrapText(escapeText(node.summary), wrapWidth) : "";
+    const label = summary ? `${labelBase}<br/>${summary}` : labelBase;
+
+    if (node.type === "if") {
+      mmd += `    ${safeId}{${label}}\n`;
+    } else if (node.type === "start" || node.type === "end") {
+      mmd += `    ${safeId}([${label}])\n`;
+    } else {
+      mmd += `    ${safeId}["${label}"]\n`;
+    }
+
+    if (node.type === "call" && callInfo && callInfo.file) {
+      functionMap[safeId] = {
+        file: callInfo.file,
+        line: callInfo.line,
+        project: callInfo.project,
+        name: callInfo.name
+      };
+    }
+  }
+
+  for (const edge of edges) {
+    const fromId = getId(edge.from || "");
+    const toId = getId(edge.to || "");
+    const label = edge.label ? wrapText(escapeText(edge.label), wrapWidth) : "";
+    if (label) {
+      mmd += `    ${fromId} --|${label}|--> ${toId}\n`;
+    } else {
+      mmd += `    ${fromId} --> ${toId}\n`;
+    }
+  }
+
+  return { mmd, functionMap };
+}
+
+function findMmdcBin(folder) {
+  const local = path.join(folder, "node_modules", ".bin", process.platform === "win32" ? "mmdc.cmd" : "mmdc");
+  return existsSync(local) ? local : "mmdc";
+}
+
+async function renderSvg({ folder, mmdText, outSvgPath, keepDir, functionMap, mmdName }) {
+  const name = mmdName || "flow.mmd";
+  const mmdPath = keepDir
+    ? path.join(keepDir, name)
+    : path.join(folder, `.apiflow.tmp.${name}`);
+
+  writeFileSync(mmdPath, mmdText, "utf8");
+
+  const mmdc = findMmdcBin(folder);
+  const absOut = path.isAbsolute(outSvgPath) ? outSvgPath : path.join(folder, outSvgPath);
+  mkdirSync(path.dirname(absOut), { recursive: true });
+
+  await runCmd(mmdc, ["-i", mmdPath, "-o", absOut], { cwd: folder });
+
+  // SVG 後處理：加入 data 屬性讓節點可點擊
+  if (functionMap && Object.keys(functionMap).length > 0) {
+    let svg = readFileSync(absOut, "utf8");
+
+    // 加入可點擊的 CSS 樣式
+    svg = svg.replace(
+      "<style>",
+      `<style>
+  .clickable-node { cursor: pointer; }
+  .clickable-node:hover .label text { fill: #007aff !important; }
+  .clickable-node:hover .label span { color: #007aff !important; }
+`
+    );
+
+    const escapeAttr = (s) =>
+      String(s ?? "")
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+
+    for (const [nodeId, info] of Object.entries(functionMap)) {
+      const dataAttrs = ` data-function="${escapeAttr(info.name)}" data-file="${escapeAttr(
+        info.file || ""
+      )}" data-line="${escapeAttr(info.line || "")}" data-project="${escapeAttr(info.project || "")}"`;
+      const regex = new RegExp(`<g\\s+[^>]*id="flowchart-${nodeId}-[^"]*"[^>]*>`, "g");
+      svg = svg.replace(regex, (tag) => {
+        let updated = tag;
+        if (updated.includes('class="')) {
+          updated = updated.replace(/class="([^"]*)"/, (m, cls) => `class="${cls} clickable-node"`);
+        } else {
+          updated = updated.replace(/^<g\s+/, '<g class="clickable-node" ');
+        }
+        if (!updated.includes("data-file=")) {
+          updated = updated.replace(/>$/, `${dataAttrs}>`);
+        }
+        return updated;
+      });
+    }
+
+    writeFileSync(absOut, svg, "utf8");
+
+    // 同時輸出 function-map.json
+    if (keepDir) {
+      writeFileSync(
+        path.join(keepDir, "function-map.json"),
+        JSON.stringify(functionMap, null, 2),
+        "utf8"
+      );
+    }
+  }
+
+  // 如果沒 keep，就清理暫存 mmd
+  if (!keepDir) {
+    try {
+      // 不強求刪除，避免權限問題造成失敗
+      // eslint-disable-next-line no-empty
+    } catch {}
+  }
+
+  return absOut;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) return help();
+
+  if (!args.project) die("缺少 --project，例如 --project gemini");
+  if (!args.query) die("缺少 --path 或 --query");
+  if (!args.out) die("缺少 --out，例如 --out dist/flow.svg");
+  if (![1, 2].includes(args.stage)) die("無效的 --stage，請使用 1 或 2");
+  if (args.stage === 2 && !args.node) die("stage=2 需要 --node");
+
+  const folder = path.resolve(args.folder);
+  const schemaPath = args.schema
+    ? path.resolve(args.schema)
+    : path.join(folder, args.stage === 2 ? "ir5-stage2.schema.json" : "ir5-stage1.schema.json");
+
+  if (!existsSync(schemaPath)) {
+    die(`找不到 schema：${schemaPath}\n請放 ir5-stage1.schema.json / ir5-stage2.schema.json 在 workspace root，或用 --schema 指定。`);
+  }
+
+  // 中間檔輸出目錄（keep 模式才寫）
+  const keepDir = args.keep ? path.join(folder, "dist") : null;
+  if (keepDir) mkdirSync(keepDir, { recursive: true });
+
+  // Stage 1: 預處理 - 提取程式碼
+  emitProgress(1, 5, "準備分析環境...");
+
+  // 從 query 中提取 functionPath（如果是 path: xxx 格式）
+  let functionPath = args.path;
+  if (!functionPath && args.query) {
+    const pathMatch = args.query.match(/^path:\s*(.+)$/);
+    if (pathMatch) functionPath = pathMatch[1].trim();
+  }
+
+  let context = null;
+  if (functionPath) {
+    emitProgress(1, 8, "正在提取程式碼上下文...");
+    context = await extractContext({
+      folder,
+      project: args.project,
+      functionPath,
+      onProgress: (p) => emitProgress(p.stage, p.percent, p.message)
+    });
+
+    if (context.success) {
+      emitProgress(1, 30, `程式碼提取完成: ${context.filePath} (${context.extractedCode.split("\n").length} 行)`);
+
+      // 保存提取的上下文到 dist（方便除錯）
+      if (keepDir) {
+        writeFileSync(
+          path.join(keepDir, "extracted-context.txt"),
+          `File: ${context.filePath}\nClass: ${context.fullClassName}\nMethod: ${context.methodName}\nLines: ${context.methodStartLine}-${context.methodEndLine}\n\n${context.extractedCode}`,
+          "utf8"
+        );
+      }
+    } else {
+      emitProgress(1, 30, `無法提取程式碼: ${context.error}，將使用 Codex 搜尋`);
+    }
+  }
+
+  // Stage 2: Codex 產生 IR
+  if (context && context.success) {
+    emitProgress(2, 35, "Codex 正在分析程式碼（純分析模式，較快）...");
+  } else {
+    emitProgress(2, 35, "Codex 正在搜尋並分析程式碼（需索引 workspace，較慢）...");
+  }
+
+  const focus = args.stage === 2
+    ? { id: args.node, label: args.nodeLabel || "", focus: args.nodeFocus || "" }
+    : null;
+
+  const ir = await runCodexIR({
+    folder,
+    schemaPath,
+    project: args.project,
+    query: args.query,
+    keepDir,
+    context,
+    stage: args.stage,
+    focus
+  });
+
+  // Stage 3: IR -> Mermaid
+  emitProgress(3, 85, "分析完成，正在生成 Mermaid 圖表...");
+  const { mmd, functionMap } = renderMermaidFlowchart(
+    ir,
+    Number.isFinite(args.wrap) ? args.wrap : 85,
+    { folder, defaultProject: args.project }
+  );
+
+  // Stage 4: Mermaid -> SVG
+  emitProgress(4, 92, "正在轉換為 SVG...");
+  const mmdName = args.stage === 2 ? "flow-stage2.mmd" : "flow-stage1.mmd";
+  const outSvg = await renderSvg({
+    folder,
+    mmdText: mmd,
+    outSvgPath: args.out,
+    keepDir,
+    functionMap,
+    mmdName
+  });
+
+  // Stage 5: 完成
+  emitProgress(5, 100, "完成！");
+  console.log(`OK: ${outSvg}`);
+  if (!args.keep) {
+    console.log("提示：加上 --keep 可以保留 dist/ir.json、dist/flow-stage1.mmd、dist/flow-stage2.mmd、dist/codex.last.json");
+  }
+}
+
+main().catch((e) => die(e?.stack || e?.message || String(e)));