@tabularis/explain 0.2.0 → 0.3.1

package/dist/index.js

@@ -304,13 +304,17 @@ function parseMysqlQueryBlock(value, ids) {
       if (item["table"] !== void 0) {
         children.push(parseMysqlQueryBlock(item, ids));
       } else if (item["read_sorted_file"] !== void 0) {
-        children.push(parseMariadbWrapper(item["read_sorted_file"], "Read Sorted File", ids));
+        children.push(
+          parseMariadbWrapper(item["read_sorted_file"], "Read Sorted File", ids)
+        );
       } else if (asObject(item["filesort"]) !== null) {
         children.push(parseMariadbFilesort(item["filesort"], ids));
       } else if (item["temporary_table"] !== void 0) {
         children.push(parseMariadbTemporaryTable(item["temporary_table"], ids));
       } else if (item["materialized"] !== void 0) {
-        children.push(parseMariadbWrapper(item["materialized"], "Materialized Subquery", ids));
+        children.push(
+          parseMariadbWrapper(item["materialized"], "Materialized Subquery", ids)
+        );
       } else if (item["buffer_result"] !== void 0) {
         children.push(parseMariadbWrapper(item["buffer_result"], "Buffer Result", ids));
       }
@@ -698,9 +702,7 @@ function parsePgPlanNode(node, ids) {
       extra[key] = value;
     }
   }
-  const children = (asArray(obj["Plans"]) ?? []).map(
-    (child) => parsePgPlanNode(child, ids)
-  );
+  const children = (asArray(obj["Plans"]) ?? []).map((child) => parsePgPlanNode(child, ids));
   return createExplainNode(id, {
     node_type: asString(obj["Node Type"]) ?? "Unknown",
     relation: asString(obj["Relation Name"]),
@@ -724,7 +726,10 @@ function parsePostgresText(raw) {
   let planningTime = null;
   let executionTime = null;
   let hasAnalyzeData = false;
+  let hasBuffers = false;
   const ids = new NodeIdAllocator();
+  let rootIndent = null;
+  let inTrailer = false;
   const stack = [];
   let root = null;
   const promoteOrAttach = (node) => {
@@ -766,12 +771,16 @@ function parsePostgresText(raw) {
       if (node.actual_rows !== null || node.actual_time_ms !== null) {
         hasAnalyzeData = true;
       }
+      rootIndent ??= indent;
+      inTrailer = false;
       popUntilShallower(indent);
       stack.push({ indent, node });
     } else {
+      if (rootIndent !== null && indent <= rootIndent) inTrailer = true;
+      if (inTrailer) continue;
       const top = stack[stack.length - 1];
-      if (top !== void 0) {
-        applyTextAttribute(top.node, trimmed);
+      if (top !== void 0 && applyTextAttribute(top.node, trimmed)) {
+        hasBuffers = true;
       }
     }
   }
@@ -779,6 +788,7 @@ function parsePostgresText(raw) {
   if (root === null) {
     throw new Error("No plan nodes found in EXPLAIN text output");
   }
+  if (hasBuffers) fillMissingBuffers(root);
   return {
     root,
     planning_time_ms: planningTime,
@@ -882,7 +892,7 @@ function parseCostFields(inner) {
 function parseActualFields(inner) {
   const trimmed = inner.trim();
   if (trimmed.toLowerCase() === "never executed") {
-    return [null, null, null];
+    return [0, 0, 0];
   }
   const rest = trimmed.startsWith("actual ") ? trimmed.slice(7) : trimmed;
   let totalTime = null;
@@ -909,6 +919,10 @@ function parseFiniteNumber(text) {
   return Number.isFinite(value) ? value : null;
 }
 function applyTextAttribute(node, content) {
+  if (content.startsWith("Buffers:")) {
+    applyBuffers(node, content.slice("Buffers:".length));
+    return true;
+  }
   if (content.startsWith("Filter:")) {
     node.filter = content.slice("Filter:".length).trim();
   } else if (content.startsWith("Index Cond:")) {
@@ -923,6 +937,32 @@ function applyTextAttribute(node, content) {
       node.extra[content.slice(0, sep).trim()] = content.slice(sep + 1).trim();
     }
   }
+  return false;
+}
+function applyBuffers(node, content) {
+  node.buffers_hit = 0;
+  node.buffers_read = 0;
+  for (const group of content.split(",")) {
+    const [scope, ...counters] = group.trim().split(/\s+/);
+    if (scope === void 0 || scope === "") continue;
+    const scopeLabel = scope.charAt(0).toUpperCase() + scope.slice(1).toLowerCase();
+    for (const counter of counters) {
+      const eq = counter.indexOf("=");
+      if (eq === -1) continue;
+      const name = counter.slice(0, eq).toLowerCase();
+      const value = parseFiniteNumber(counter.slice(eq + 1));
+      if (value === null) continue;
+      if (scopeLabel === "Shared" && name === "hit") node.buffers_hit = value;
+      else if (scopeLabel === "Shared" && name === "read") node.buffers_read = value;
+      else
+        node.extra[`${scopeLabel} ${name.charAt(0).toUpperCase()}${name.slice(1)} Blocks`] = value;
+    }
+  }
+}
+function fillMissingBuffers(node) {
+  node.buffers_hit ??= 0;
+  node.buffers_read ??= 0;
+  for (const child of node.children) fillMissingBuffers(child);
 }
 
 // src/parsers/sqlite.ts
@@ -1053,16 +1093,12 @@ var BUILTIN_EXPLAIN_PARSERS = Object.freeze([
   Object.freeze({
     engine: "mysql",
     format: "mysql-tabular-rows",
-    parse: (payload) => parseMysqlTabularRows(
-      parseJsonRows(payload, "mysql-tabular-rows")
-    )
+    parse: (payload) => parseMysqlTabularRows(parseJsonRows(payload, "mysql-tabular-rows"))
   }),
   Object.freeze({
     engine: "sqlite",
     format: "sqlite-eqp-rows",
-    parse: (payload) => parseSqliteEqpRows(
-      parseJsonRows(payload, "sqlite-eqp-rows")
-    )
+    parse: (payload) => parseSqliteEqpRows(parseJsonRows(payload, "sqlite-eqp-rows"))
   })
 ]);
 
@@ -1144,19 +1180,19 @@ function explainEngineFromDriverName(name) {
   );
   return parser?.engine ?? null;
 }
-function detectFormat(raw) {
-  return detectFormatFor(raw, null);
+async function detectFormat(raw) {
+  return await detectFormatFor(raw, null);
 }
-function detectFormatFor(raw, engine) {
+async function detectFormatFor(raw, engine) {
   switch (engine) {
     case "postgres":
-      return detectPostgresFormat(raw);
+      return Promise.resolve(detectPostgresFormat(raw));
     case "mysql":
-      if (looksLikeJson(raw)) return "mysql-json";
+      if (looksLikeJson(raw)) return Promise.resolve("mysql-json");
       if (raw.trim() === "") {
         throw new Error("Unsupported EXPLAIN file format: input is empty");
       }
-      return "mysql-text";
+      return Promise.resolve("mysql-text");
     case "sqlite":
       throw new Error(
         "SQLite EXPLAIN QUERY PLAN has no text form here: pass its (id, parent, detail) rows to buildSqliteTree"
@@ -1164,14 +1200,14 @@ function detectFormatFor(raw, engine) {
     case null: {
       const builtinFormat = detectPostgresFormatOrNull(raw);
       if (builtinFormat !== null) return builtinFormat;
-      const customFormat = sniffRegisteredFormat(raw, null);
+      const customFormat = await sniffRegisteredFormat(raw, null);
       if (customFormat !== null) return customFormat;
       throw new Error(
         "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
       );
     }
     default: {
-      const format = sniffRegisteredFormat(raw, engine);
+      const format = await sniffRegisteredFormat(raw, engine);
       if (format !== null) return format;
       throw new Error(`Unsupported EXPLAIN file format for engine '${engine}'`);
     }
@@ -1180,16 +1216,14 @@ function detectFormatFor(raw, engine) {
 function detectPostgresFormat(raw) {
   const format = detectPostgresFormatOrNull(raw);
   if (format !== null) return format;
-  throw new Error(
-    "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
-  );
+  throw new Error("Unsupported EXPLAIN file format: expected Postgres JSON or text output");
 }
 function detectPostgresFormatOrNull(raw) {
   if (looksLikeJson(raw)) return "postgres-json";
   if (looksLikePostgresText(raw)) return "postgres-text";
   return null;
 }
-function sniffRegisteredFormat(raw, engine) {
+async function sniffRegisteredFormat(raw, engine) {
   const normalizedEngine = engine?.trim().toLowerCase() ?? null;
   for (const parser of listExplainParsers()) {
     if (normalizedEngine === null && BUILTIN_SOURCE_FORMATS.has(parser.format)) {
@@ -1200,7 +1234,7 @@ function sniffRegisteredFormat(raw, engine) {
     }
     if (parser.sniff === void 0) continue;
     try {
-      if (parser.sniff(raw)) return parser.format;
+      if (await parser.sniff(raw)) return parser.format;
     } catch {
     }
   }
@@ -1216,8 +1250,9 @@ function looksLikePostgresText(raw) {
 function parseExplain(raw) {
   return parseExplainFor(raw, null);
 }
-function parseExplainFor(raw, engine) {
-  return parserFor(detectFormatFor(raw, engine)).parse(raw);
+async function parseExplainFor(raw, engine) {
+  const format = await detectFormatFor(raw, engine);
+  return await parserFor(format).parse(raw);
 }
 function withSourceLabel(plan, name) {
   if (plan.original_query === "") {
@@ -1227,14 +1262,14 @@ function withSourceLabel(plan, name) {
 }
 
 // src/raw.ts
-function parseRawExplain(raw) {
+async function parseRawExplain(raw) {
   const parser = getExplainParser(raw.format);
   if (parser === null) {
     throw new Error(
       `No EXPLAIN parser registered for format '${raw.format}' (engine '${raw.engine}'). Import the parser package for '${raw.engine}' before parsing.`
     );
   }
-  const plan = parser.parse(raw.payload);
+  const plan = await parser.parse(raw.payload);
   return {
     ...plan,
     driver: raw.engine,
@@ -1242,7 +1277,7 @@ function parseRawExplain(raw) {
   };
 }
 function resolveExplainOutput(output) {
-  return output.kind === "plan" ? output.plan : parseRawExplain(output.raw);
+  return output.kind === "plan" ? Promise.resolve(output.plan) : parseRawExplain(output.raw);
 }
 
 // src/metrics.ts
@@ -1323,16 +1358,10 @@ function computeExplainMetrics(plan) {
   let maxExclusiveBuffers = 0;
   let totalExclusiveTimeMs = 0;
   for (const metrics of order) {
-    maxExclusiveTimeMs = Math.max(
-      maxExclusiveTimeMs,
-      metrics.exclusiveTimeMs ?? 0
-    );
+    maxExclusiveTimeMs = Math.max(maxExclusiveTimeMs, metrics.exclusiveTimeMs ?? 0);
     maxExclusiveCost = Math.max(maxExclusiveCost, metrics.exclusiveCost ?? 0);
     maxTotalRows = Math.max(maxTotalRows, metrics.totalRows ?? 0);
-    maxExclusiveBuffers = Math.max(
-      maxExclusiveBuffers,
-      metrics.exclusiveBuffers ?? 0
-    );
+    maxExclusiveBuffers = Math.max(maxExclusiveBuffers, metrics.exclusiveBuffers ?? 0);
     totalExclusiveTimeMs += metrics.exclusiveTimeMs ?? 0;
   }
   if (totalExclusiveTimeMs > 0) {
@@ -1481,7 +1510,7 @@ function getRowEstimateRatio(node) {
   }
   return node.actual_rows / node.plan_rows;
 }
-function getMismatchMagnitude(node) {
+function getRowEstimateGap(node) {
   const ratio = getRowEstimateRatio(node);
   if (ratio == null) {
     return null;
@@ -1527,7 +1556,7 @@ function getExplainPlanSummary(plan, metrics) {
       };
     }
     const ratio = getRowEstimateRatio(node);
-    const magnitude = getMismatchMagnitude(node);
+    const magnitude = getRowEstimateGap(node);
     if (ratio != null && magnitude != null && (largestRowMismatchNode == null || magnitude > largestRowMismatchNode.value)) {
       largestRowMismatchNode = {
         nodeId: node.id,
@@ -1571,14 +1600,33 @@ function getExplainDriverLegend(plan) {
         "editor.visualExplain.mysqlEstimateLegend2"
       ];
     case "sqlite":
-      return [
-        "editor.visualExplain.sqliteLegend1",
-        "editor.visualExplain.sqliteLegend2"
-      ];
+      return ["editor.visualExplain.sqliteLegend1", "editor.visualExplain.sqliteLegend2"];
     default:
       return [];
   }
 }
+function getExplainTableRow(node, hasAnalyzeData, nodeMetrics, fallbackIndex = 1) {
+  return {
+    index: nodeMetrics?.index ?? fallbackIndex,
+    depth: nodeMetrics?.depth ?? 0,
+    nodeType: node.node_type,
+    relation: node.relation ?? null,
+    startupCost: node.startup_cost ?? null,
+    totalCost: node.total_cost ?? null,
+    planRows: node.plan_rows ?? null,
+    actualRows: hasAnalyzeData ? node.actual_rows ?? null : null,
+    actualLoops: hasAnalyzeData ? node.actual_loops ?? null : null,
+    exclusiveTimeMs: hasAnalyzeData ? nodeMetrics?.exclusiveTimeMs ?? null : null,
+    estimateGap: getRowEstimateGap(node),
+    filter: node.filter ?? null
+  };
+}
+function getExplainTableRows(plan, metrics) {
+  const planMetrics = metrics ?? computeExplainMetrics(plan);
+  return flattenExplainNodes(plan.root).map(
+    (node, i) => getExplainTableRow(node, plan.has_analyze_data, planMetrics.byId.get(node.id), i + 1)
+  );
+}
 
 // src/diagnostics.ts
 var EXPLAIN_DIAGNOSTIC_THRESHOLDS = {
@@ -1764,9 +1812,7 @@ function getNodeDiagnostics(node, metrics) {
       value: formatRows(node.buffers_read)
     });
   }
-  return diagnostics.sort(
-    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
-  );
+  return diagnostics.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
 }
 function getPlanDiagnostics(plan, metrics) {
   const result = /* @__PURE__ */ new Map();
@@ -1910,4 +1956,478 @@ function compareByTimeThenCount(a, b) {
   return (b.exclusiveTimeMs ?? 0) - (a.exclusiveTimeMs ?? 0) || b.count - a.count || a.nodeType.localeCompare(b.nodeType);
 }
 
-export { EXPLAIN_DIAGNOSTIC_THRESHOLDS, EXPLAIN_METRIC_KINDS, NodeIdAllocator, buildSqliteTree, computeExplainMetrics, countDiagnosticsBySeverity, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatRatio, formatRows, formatTime, getAvailableMetricKinds, getDefaultMetricKind, getExplainDriverLegend, getExplainParser, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getMetricMax, getMetricValue, getNodeCostStyle, getNodeDiagnostics, getNodeMetrics, getPlanDiagnostics, getRowEstimateRatio, getWorstSeverity, hasAnalyzeDataRecursive, isMetricAvailable, listExplainParsers, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, registerExplainParser, resolveExplainOutput, unregisterExplainParser, withSourceLabel };
+// src/tableColumns.ts
+var EXPLAIN_TABLE_COLUMNS = [
+  "operation",
+  "relation",
+  "cost",
+  "estRows",
+  "actualRows",
+  "loops",
+  "selfTime",
+  "estimateGap",
+  "filter"
+];
+var EXPLAIN_TABLE_ANALYZE_COLUMNS = /* @__PURE__ */ new Set([
+  "actualRows",
+  "loops"
+]);
+function isExplainTableColumnId(value) {
+  return typeof value === "string" && EXPLAIN_TABLE_COLUMNS.includes(value);
+}
+function normalizeExplainTableColumnOrder(saved) {
+  const order = [];
+  if (Array.isArray(saved)) {
+    for (const id of saved) {
+      if (isExplainTableColumnId(id) && !order.includes(id)) order.push(id);
+    }
+  }
+  EXPLAIN_TABLE_COLUMNS.forEach((id, defaultIndex) => {
+    if (order.includes(id)) return;
+    const previous = EXPLAIN_TABLE_COLUMNS.slice(0, defaultIndex).reverse();
+    const anchor = previous.find((candidate) => order.includes(candidate));
+    order.splice(anchor ? order.indexOf(anchor) + 1 : 0, 0, id);
+  });
+  return order;
+}
+function moveExplainTableColumn(order, column, target) {
+  const from = order.indexOf(column);
+  const to = order.indexOf(target);
+  if (from === -1 || to === -1 || from === to) return order;
+  const next = order.filter((id) => id !== column);
+  next.splice(to, 0, column);
+  return next;
+}
+function shiftExplainTableColumn(order, column, direction, visible = order) {
+  const shown = order.filter((id) => visible.includes(id));
+  const at = shown.indexOf(column);
+  const neighbour = at === -1 ? void 0 : shown[at + direction];
+  return neighbour ? moveExplainTableColumn(order, column, neighbour) : order;
+}
+function isDefaultExplainTableColumnOrder(order) {
+  return order.length === EXPLAIN_TABLE_COLUMNS.length && order.every((id, index) => id === EXPLAIN_TABLE_COLUMNS[index]);
+}
+
+// src/nodeDetails.ts
+var DEFAULT_LABELS = {
+  "editor.visualExplain.nodeType": "Operation",
+  "editor.visualExplain.relation": "Table",
+  "editor.visualExplain.cost": "Cost",
+  "editor.visualExplain.selfCost": "Self Cost",
+  "editor.visualExplain.estRows": "Est. Rows",
+  "editor.visualExplain.filter": "Filter",
+  "editor.visualExplain.indexCondition": "Index Cond.",
+  "editor.visualExplain.joinType": "Join Type",
+  "editor.visualExplain.hashCondition": "Hash Cond.",
+  "editor.visualExplain.actualRows": "Actual Rows",
+  "editor.visualExplain.rowsAllLoops": "Rows (All Loops)",
+  "editor.visualExplain.selfTime": "Self Time",
+  "editor.visualExplain.totalTime": "Total Time",
+  "editor.visualExplain.timePerLoop": "Time per Loop",
+  "editor.visualExplain.loops": "Loops",
+  "editor.visualExplain.buffersHit": "Buffers Hit",
+  "editor.visualExplain.buffersRead": "Buffers Read",
+  "editor.visualExplain.general": "General",
+  "editor.visualExplain.analyzeData": "Analyze Data",
+  "editor.visualExplain.extraDetails": "Extra",
+  "editor.visualExplain.diagnostics.title": "Diagnostics"
+};
+function getExplainNodeDetailSections(node, options = {}) {
+  const { hasAnalyzeData = false, metrics = null, diagnostics = [], t } = options;
+  const tr = (key, fallback) => {
+    if (t) {
+      return t(key, fallback ?? DEFAULT_LABELS[key] ?? key);
+    }
+    return fallback ?? DEFAULT_LABELS[key] ?? key;
+  };
+  const generalEntries = [
+    { label: tr("editor.visualExplain.nodeType", "Operation"), value: node.node_type },
+    ...node.relation ? [{ label: tr("editor.visualExplain.relation", "Table"), value: node.relation }] : [],
+    ...node.startup_cost != null && node.total_cost != null ? [
+      {
+        label: tr("editor.visualExplain.cost", "Cost"),
+        value: `${formatCost(node.startup_cost)} - ${formatCost(node.total_cost)}`
+      }
+    ] : node.total_cost != null ? [
+      {
+        label: tr("editor.visualExplain.cost", "Cost"),
+        value: formatCost(node.total_cost)
+      }
+    ] : [],
+    ...metrics?.exclusiveCost != null ? [
+      {
+        label: tr("editor.visualExplain.selfCost", "Self Cost"),
+        value: formatCost(metrics.exclusiveCost)
+      }
+    ] : [],
+    ...node.plan_rows != null ? [
+      {
+        label: tr("editor.visualExplain.estRows", "Est. Rows"),
+        value: formatRows(node.plan_rows)
+      }
+    ] : [],
+    ...node.filter ? [{ label: tr("editor.visualExplain.filter", "Filter"), value: node.filter }] : [],
+    ...node.index_condition ? [
+      {
+        label: tr("editor.visualExplain.indexCondition", "Index Cond."),
+        value: node.index_condition
+      }
+    ] : [],
+    ...node.join_type ? [{ label: tr("editor.visualExplain.joinType", "Join Type"), value: node.join_type }] : [],
+    ...node.hash_condition ? [
+      {
+        label: tr("editor.visualExplain.hashCondition", "Hash Cond."),
+        value: node.hash_condition
+      }
+    ] : []
+  ];
+  const analyzeEntries = hasAnalyzeData ? [
+    ...node.actual_rows != null ? [
+      {
+        label: tr("editor.visualExplain.actualRows", "Actual Rows"),
+        value: formatRows(node.actual_rows)
+      }
+    ] : [],
+    ...metrics?.totalRows != null && node.actual_loops != null && node.actual_loops > 1 ? [
+      {
+        label: tr("editor.visualExplain.rowsAllLoops", "Rows (All Loops)"),
+        value: formatRows(metrics.totalRows)
+      }
+    ] : [],
+    ...metrics?.exclusiveTimeMs != null ? [
+      {
+        label: tr("editor.visualExplain.selfTime", "Self Time"),
+        value: metrics.timeShare != null ? `${formatTime(metrics.exclusiveTimeMs)} (${Math.round(metrics.timeShare * 100)}%)` : formatTime(metrics.exclusiveTimeMs)
+      }
+    ] : [],
+    ...metrics?.inclusiveTimeMs != null ? [
+      {
+        label: tr("editor.visualExplain.totalTime", "Total Time"),
+        value: formatTime(metrics.inclusiveTimeMs)
+      }
+    ] : [],
+    ...node.actual_time_ms != null ? [
+      {
+        label: tr("editor.visualExplain.timePerLoop", "Time per Loop"),
+        value: formatTime(node.actual_time_ms)
+      }
+    ] : [],
+    ...node.actual_loops != null ? [
+      {
+        label: tr("editor.visualExplain.loops", "Loops"),
+        value: String(node.actual_loops)
+      }
+    ] : [],
+    ...node.buffers_hit != null ? [
+      {
+        label: tr("editor.visualExplain.buffersHit", "Buffers Hit"),
+        value: String(node.buffers_hit)
+      }
+    ] : [],
+    ...node.buffers_read != null ? [
+      {
+        label: tr("editor.visualExplain.buffersRead", "Buffers Read"),
+        value: String(node.buffers_read)
+      }
+    ] : []
+  ] : [];
+  const extraEntries = Object.entries(node.extra ?? {}).map(
+    ([key, value]) => ({
+      label: key,
+      value: typeof value === "string" ? value : JSON.stringify(value)
+    })
+  );
+  const sections = [];
+  if (generalEntries.length > 0) {
+    sections.push({
+      title: tr("editor.visualExplain.general", "General"),
+      titleKey: "editor.visualExplain.general",
+      entries: generalEntries
+    });
+  }
+  if (analyzeEntries.length > 0) {
+    sections.push({
+      title: tr("editor.visualExplain.analyzeData", "Analyze Data"),
+      titleKey: "editor.visualExplain.analyzeData",
+      entries: analyzeEntries
+    });
+  }
+  if (extraEntries.length > 0) {
+    sections.push({
+      title: tr("editor.visualExplain.extraDetails", "Extra"),
+      titleKey: "editor.visualExplain.extraDetails",
+      entries: extraEntries
+    });
+  }
+  if (diagnostics && diagnostics.length > 0) {
+    const diagEntries = diagnostics.map((d) => ({
+      label: tr(d.labelKey, d.kind),
+      value: d.value ? `${tr(d.descriptionKey, d.kind)} (${d.value})` : tr(d.descriptionKey, d.kind)
+    }));
+    sections.push({
+      title: tr("editor.visualExplain.diagnostics.title", "Diagnostics"),
+      titleKey: "editor.visualExplain.diagnostics.title",
+      entries: diagEntries
+    });
+  }
+  return sections;
+}
+function formatExplainNodeDetails(node, options = {}) {
+  const sections = getExplainNodeDetailSections(node, options);
+  const parts = [];
+  for (const section of sections) {
+    if (section.entries.length === 0) continue;
+    const lines = section.entries.map((entry) => `${entry.label}: ${entry.value}`);
+    if (options.includeSectionHeaders || section.titleKey !== "editor.visualExplain.general") {
+      parts.push(`${section.title}:
+${lines.join("\n")}`);
+    } else {
+      parts.push(lines.join("\n"));
+    }
+  }
+  return parts.join("\n\n");
+}
+
+// src/planComparison.ts
+function checkEngineCompatibility(baselineEngine, currentEngine) {
+  const b = (baselineEngine || "").toLowerCase().trim();
+  const c = (currentEngine || "").toLowerCase().trim();
+  if (b && c && b !== c) {
+    return {
+      compatible: false,
+      reason: `Engines differ (${b} vs ${c}). Explain metrics and costs cannot be compared across different database engines.`
+    };
+  }
+  return { compatible: true };
+}
+function calculateMetricDelta(baselineValue, currentValue) {
+  const b = baselineValue ?? null;
+  const c = currentValue ?? null;
+  if (b == null || c == null) {
+    return {
+      baselineValue: b,
+      currentValue: c,
+      delta: null,
+      ratio: null
+    };
+  }
+  const delta = c - b;
+  const ratio = b !== 0 ? c / b : null;
+  return {
+    baselineValue: b,
+    currentValue: c,
+    delta,
+    ratio
+  };
+}
+function flattenTree(root, prefix = "0", depth = 0) {
+  const result = [{ node: root, path: prefix, depth }];
+  root.children.forEach((child, i) => {
+    result.push(...flattenTree(child, `${prefix}.${i}`, depth + 1));
+  });
+  return result;
+}
+function alignPlanNodes(baselineRoot, currentRoot, baselineMetrics, currentMetrics) {
+  if (!baselineRoot && !currentRoot) return [];
+  if (!baselineRoot && currentRoot) {
+    const currentFlat2 = flattenTree(currentRoot);
+    return currentFlat2.map(({ node }) => {
+      const m = currentMetrics?.get(node.id);
+      return {
+        baselineNodeId: null,
+        currentNodeId: node.id,
+        operatorChanged: false,
+        baselineNodeType: null,
+        currentNodeType: node.node_type,
+        relation: node.relation,
+        status: "added",
+        costDelta: calculateMetricDelta(null, m?.totalCost ?? node.total_cost),
+        timeDelta: calculateMetricDelta(null, m?.inclusiveTimeMs ?? node.actual_time_ms),
+        rowsDelta: calculateMetricDelta(
+          null,
+          m?.totalRows ?? node.actual_rows ?? node.plan_rows
+        )
+      };
+    });
+  }
+  if (baselineRoot && !currentRoot) {
+    const baselineFlat2 = flattenTree(baselineRoot);
+    return baselineFlat2.map(({ node }) => {
+      const m = baselineMetrics?.get(node.id);
+      return {
+        baselineNodeId: node.id,
+        currentNodeId: null,
+        operatorChanged: false,
+        baselineNodeType: node.node_type,
+        currentNodeType: null,
+        relation: node.relation,
+        status: "removed",
+        costDelta: calculateMetricDelta(m?.totalCost ?? node.total_cost, null),
+        timeDelta: calculateMetricDelta(m?.inclusiveTimeMs ?? node.actual_time_ms, null),
+        rowsDelta: calculateMetricDelta(
+          m?.totalRows ?? node.actual_rows ?? node.plan_rows,
+          null
+        )
+      };
+    });
+  }
+  const baselineFlat = flattenTree(baselineRoot);
+  const currentFlat = flattenTree(currentRoot);
+  const matchedCurrent = /* @__PURE__ */ new Set();
+  const matchedBaseline = /* @__PURE__ */ new Set();
+  const comparisons = [];
+  const currentByPath = new Map(currentFlat.map((item) => [item.path, item]));
+  for (const bItem of baselineFlat) {
+    const cItem = currentByPath.get(bItem.path);
+    if (cItem && !matchedCurrent.has(cItem.node.id)) {
+      const typeMatch = bItem.node.node_type === cItem.node.node_type;
+      const relMatch = bItem.node.relation === cItem.node.relation;
+      if (typeMatch || bItem.node.relation && relMatch) {
+        matchedBaseline.add(bItem.node.id);
+        matchedCurrent.add(cItem.node.id);
+        const bM = baselineMetrics?.get(bItem.node.id);
+        const cM = currentMetrics?.get(cItem.node.id);
+        comparisons.push({
+          baselineNodeId: bItem.node.id,
+          currentNodeId: cItem.node.id,
+          operatorChanged: !typeMatch,
+          baselineNodeType: bItem.node.node_type,
+          currentNodeType: cItem.node.node_type,
+          relation: cItem.node.relation ?? bItem.node.relation,
+          status: "matched",
+          costDelta: calculateMetricDelta(
+            bM?.totalCost ?? bItem.node.total_cost,
+            cM?.totalCost ?? cItem.node.total_cost
+          ),
+          timeDelta: calculateMetricDelta(
+            bM?.inclusiveTimeMs ?? bItem.node.actual_time_ms,
+            cM?.inclusiveTimeMs ?? cItem.node.actual_time_ms
+          ),
+          rowsDelta: calculateMetricDelta(
+            bM?.totalRows ?? bItem.node.actual_rows ?? bItem.node.plan_rows,
+            cM?.totalRows ?? cItem.node.actual_rows ?? cItem.node.plan_rows
+          )
+        });
+      }
+    }
+  }
+  for (const bItem of baselineFlat) {
+    if (matchedBaseline.has(bItem.node.id)) continue;
+    const candidate = currentFlat.find(
+      (cItem) => !matchedCurrent.has(cItem.node.id) && bItem.node.relation && bItem.node.relation === cItem.node.relation
+    );
+    if (candidate) {
+      matchedBaseline.add(bItem.node.id);
+      matchedCurrent.add(candidate.node.id);
+      const bM = baselineMetrics?.get(bItem.node.id);
+      const cM = currentMetrics?.get(candidate.node.id);
+      const typeMatch = bItem.node.node_type === candidate.node.node_type;
+      comparisons.push({
+        baselineNodeId: bItem.node.id,
+        currentNodeId: candidate.node.id,
+        operatorChanged: !typeMatch,
+        baselineNodeType: bItem.node.node_type,
+        currentNodeType: candidate.node.node_type,
+        relation: candidate.node.relation,
+        status: "matched",
+        isAmbiguous: true,
+        costDelta: calculateMetricDelta(
+          bM?.totalCost ?? bItem.node.total_cost,
+          cM?.totalCost ?? candidate.node.total_cost
+        ),
+        timeDelta: calculateMetricDelta(
+          bM?.inclusiveTimeMs ?? bItem.node.actual_time_ms,
+          cM?.inclusiveTimeMs ?? candidate.node.actual_time_ms
+        ),
+        rowsDelta: calculateMetricDelta(
+          bM?.totalRows ?? bItem.node.actual_rows ?? bItem.node.plan_rows,
+          cM?.totalRows ?? candidate.node.actual_rows ?? candidate.node.plan_rows
+        )
+      });
+    }
+  }
+  for (const bItem of baselineFlat) {
+    if (!matchedBaseline.has(bItem.node.id)) {
+      const bM = baselineMetrics?.get(bItem.node.id);
+      comparisons.push({
+        baselineNodeId: bItem.node.id,
+        currentNodeId: null,
+        operatorChanged: false,
+        baselineNodeType: bItem.node.node_type,
+        currentNodeType: null,
+        relation: bItem.node.relation,
+        status: "removed",
+        costDelta: calculateMetricDelta(bM?.totalCost ?? bItem.node.total_cost, null),
+        timeDelta: calculateMetricDelta(
+          bM?.inclusiveTimeMs ?? bItem.node.actual_time_ms,
+          null
+        ),
+        rowsDelta: calculateMetricDelta(
+          bM?.totalRows ?? bItem.node.actual_rows ?? bItem.node.plan_rows,
+          null
+        )
+      });
+    }
+  }
+  for (const cItem of currentFlat) {
+    if (!matchedCurrent.has(cItem.node.id)) {
+      const cM = currentMetrics?.get(cItem.node.id);
+      comparisons.push({
+        baselineNodeId: null,
+        currentNodeId: cItem.node.id,
+        operatorChanged: false,
+        baselineNodeType: null,
+        currentNodeType: cItem.node.node_type,
+        relation: cItem.node.relation,
+        status: "added",
+        costDelta: calculateMetricDelta(null, cM?.totalCost ?? cItem.node.total_cost),
+        timeDelta: calculateMetricDelta(
+          null,
+          cM?.inclusiveTimeMs ?? cItem.node.actual_time_ms
+        ),
+        rowsDelta: calculateMetricDelta(
+          null,
+          cM?.totalRows ?? cItem.node.actual_rows ?? cItem.node.plan_rows
+        )
+      });
+    }
+  }
+  return comparisons;
+}
+function comparePlanSnapshots(baseline, current, baselineMetrics, currentMetrics) {
+  const engineCheck = checkEngineCompatibility(baseline.context.engine, current.context.engine);
+  const hasAnalyzeMismatch = baseline.hasAnalyzeData !== current.hasAnalyzeData;
+  const nodeComparisons = engineCheck.compatible ? alignPlanNodes(baseline.plan.root, current.plan.root, baselineMetrics, currentMetrics) : [];
+  let nodesAdded = 0;
+  let nodesRemoved = 0;
+  let operatorsChanged = 0;
+  for (const cmp of nodeComparisons) {
+    if (cmp.status === "added") nodesAdded++;
+    if (cmp.status === "removed") nodesRemoved++;
+    if (cmp.status === "matched" && cmp.operatorChanged) operatorsChanged++;
+  }
+  return {
+    isCompatible: engineCheck.compatible,
+    incompatibilityReason: engineCheck.reason,
+    hasAnalyzeMismatch,
+    baselineSnapshotId: baseline.id,
+    currentSnapshotId: current.id,
+    summary: {
+      totalCostDelta: calculateMetricDelta(baseline.totalCost, current.totalCost),
+      executionTimeDelta: calculateMetricDelta(
+        baseline.executionTimeMs,
+        current.executionTimeMs
+      ),
+      planningTimeDelta: calculateMetricDelta(
+        baseline.planningTimeMs,
+        current.planningTimeMs
+      ),
+      nodesAdded,
+      nodesRemoved,
+      operatorsChanged
+    },
+    nodeComparisons
+  };
+}
+
+export { EXPLAIN_DIAGNOSTIC_THRESHOLDS, EXPLAIN_METRIC_KINDS, EXPLAIN_TABLE_ANALYZE_COLUMNS, EXPLAIN_TABLE_COLUMNS, NodeIdAllocator, alignPlanNodes, buildSqliteTree, calculateMetricDelta, checkEngineCompatibility, comparePlanSnapshots, computeExplainMetrics, countDiagnosticsBySeverity, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatExplainNodeDetails, formatRatio, formatRows, formatTime, getAvailableMetricKinds, getDefaultMetricKind, getExplainDriverLegend, getExplainNodeDetailSections, getExplainParser, getExplainPlanStats, getExplainPlanSummary, getExplainTableRows, getHeatBarClass, getMaxCost, getMaxTime, getMetricMax, getMetricValue, getNodeCostStyle, getNodeDiagnostics, getNodeMetrics, getPlanDiagnostics, getRowEstimateRatio, getWorstSeverity, hasAnalyzeDataRecursive, isDefaultExplainTableColumnOrder, isMetricAvailable, listExplainParsers, moveExplainTableColumn, normalizeExplainTableColumnOrder, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, registerExplainParser, resolveExplainOutput, shiftExplainTableColumn, unregisterExplainParser, withSourceLabel };