@tabularis/explain 0.1.0 → 0.3.0

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"]),
@@ -925,80 +927,6 @@ function applyTextAttribute(node, content) {
   }
 }
 
-// src/parsers/source.ts
-var SOURCE_PARSERS = [
-  { engine: "postgres", format: "postgres-json", parse: parsePostgresJson },
-  { engine: "postgres", format: "postgres-text", parse: parsePostgresText },
-  { engine: "mysql", format: "mysql-json", parse: parseMysqlJson },
-  { engine: "mysql", format: "mysql-text", parse: parseMysqlText }
-];
-function parserFor(format) {
-  const parser = SOURCE_PARSERS.find((candidate) => candidate.format === format);
-  if (parser === void 0) {
-    throw new Error(`No parser registered for format '${format}'`);
-  }
-  return parser;
-}
-function explainEngineFromDriverName(name) {
-  switch (name.trim().toLowerCase()) {
-    case "postgres":
-    case "postgresql":
-    case "pg":
-      return "postgres";
-    case "mysql":
-    case "mariadb":
-      return "mysql";
-    case "sqlite":
-    case "sqlite3":
-      return "sqlite";
-    default:
-      return null;
-  }
-}
-function detectFormat(raw) {
-  return detectFormatFor(raw, null);
-}
-function detectFormatFor(raw, engine) {
-  switch (engine) {
-    case "postgres":
-    case null:
-      if (looksLikeJson(raw)) return "postgres-json";
-      if (looksLikePostgresText(raw)) return "postgres-text";
-      throw new Error(
-        "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
-      );
-    case "mysql":
-      if (looksLikeJson(raw)) return "mysql-json";
-      if (raw.trim() === "") {
-        throw new Error("Unsupported EXPLAIN file format: input is empty");
-      }
-      return "mysql-text";
-    case "sqlite":
-      throw new Error(
-        "SQLite EXPLAIN QUERY PLAN has no text form here: pass its (id, parent, detail) rows to buildSqliteTree"
-      );
-  }
-}
-function looksLikeJson(raw) {
-  const trimmed = raw.trimStart();
-  return trimmed.startsWith("[") || trimmed.startsWith("{");
-}
-function looksLikePostgresText(raw) {
-  return raw.split("\n").some((line) => line.includes("(cost=") && line.includes("width="));
-}
-function parseExplain(raw) {
-  return parseExplainFor(raw, null);
-}
-function parseExplainFor(raw, engine) {
-  return parserFor(detectFormatFor(raw, engine)).parse(raw);
-}
-function withSourceLabel(plan, name) {
-  if (plan.original_query === "") {
-    return { ...plan, original_query: `-- loaded from ${name}` };
-  }
-  return plan;
-}
-
 // src/parsers/sqlite.ts
 function buildSqliteTree(entries, parentId, ids) {
   const rootEntry = entries.find(
@@ -1085,44 +1013,234 @@ function parseSqliteDetail(detail) {
   return [detail, null, null];
 }
 
-// src/raw.ts
-function parseRawExplain(raw) {
-  const plan = parseRawPayload(raw);
-  return {
-    ...plan,
-    driver: raw.engine,
-    original_query: raw.original_query
-  };
-}
-function resolveExplainOutput(output) {
-  return output.kind === "plan" ? output.plan : parseRawExplain(output.raw);
-}
-function parseRawPayload(raw) {
-  switch (raw.format) {
-    case "postgres-json":
-      return parsePostgresJson(raw.payload);
-    case "mysql-json":
-      return parseMysqlJson(raw.payload);
-    case "mysql-analyze-text":
-      return parseMysqlText(raw.payload);
-    case "mysql-tabular-rows":
-      return parseMysqlTabularRows(parseJsonRows(raw));
-    case "sqlite-eqp-rows":
-      return parseSqliteEqpRows(parseJsonRows(raw));
-  }
-}
-function parseJsonRows(raw) {
+// src/parsers/builtins.ts
+function parseJsonRows(payload, format) {
   let value;
   try {
-    value = JSON.parse(raw.payload);
+    value = JSON.parse(payload);
   } catch (err) {
     throw new Error(`Failed to parse EXPLAIN rows: ${String(err)}`);
   }
   if (!Array.isArray(value)) {
-    throw new Error(`EXPLAIN rows payload for '${raw.format}' must be a JSON array`);
+    throw new Error(`EXPLAIN rows payload for '${format}' must be a JSON array`);
   }
   return value;
 }
+var BUILTIN_EXPLAIN_PARSERS = Object.freeze([
+  Object.freeze({
+    engine: "postgres",
+    format: "postgres-json",
+    parse: parsePostgresJson
+  }),
+  Object.freeze({
+    engine: "postgres",
+    format: "postgres-text",
+    parse: parsePostgresText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-json",
+    parse: parseMysqlJson
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-text",
+    parse: parseMysqlText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-analyze-text",
+    parse: parseMysqlText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "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"))
+  })
+]);
+
+// src/registry.ts
+var builtinParsersByFormat = new Map(
+  BUILTIN_EXPLAIN_PARSERS.map((parser) => [parser.format, parser])
+);
+var parserOverlays = /* @__PURE__ */ new Map();
+var customFormatOrder = [];
+function registerExplainParser(parser) {
+  validateParser(parser);
+  const replacing = getExplainParser(parser.format) !== null;
+  if (replacing) {
+    console.warn(
+      `EXPLAIN parser format '${parser.format}' is already registered; replacing it.`
+    );
+  } else {
+    customFormatOrder.push(parser.format);
+  }
+  parserOverlays.set(parser.format, parser);
+}
+function unregisterExplainParser(format) {
+  if (!parserOverlays.delete(format)) return;
+  if (builtinParsersByFormat.has(format)) return;
+  const index = customFormatOrder.indexOf(format);
+  if (index !== -1) customFormatOrder.splice(index, 1);
+}
+function getExplainParser(format) {
+  return parserOverlays.get(format) ?? builtinParsersByFormat.get(format) ?? null;
+}
+function listExplainParsers() {
+  const parsers = BUILTIN_EXPLAIN_PARSERS.map(
+    (parser) => parserOverlays.get(parser.format) ?? parser
+  );
+  for (const format of customFormatOrder) {
+    const parser = parserOverlays.get(format);
+    if (parser !== void 0) parsers.push(parser);
+  }
+  return Object.freeze(parsers);
+}
+function validateParser(parser) {
+  if (typeof parser !== "object" || parser === null || typeof parser.engine !== "string" || parser.engine.trim() === "" || typeof parser.format !== "string" || parser.format.trim() === "" || typeof parser.parse !== "function") {
+    throw new TypeError(
+      "EXPLAIN parser registration requires non-empty engine and format strings and a parse function"
+    );
+  }
+}
+
+// src/parsers/source.ts
+var BUILTIN_SOURCE_FORMATS = /* @__PURE__ */ new Set([
+  "postgres-json",
+  "postgres-text",
+  "mysql-json",
+  "mysql-text"
+]);
+function parserFor(format) {
+  const parser = getExplainParser(format);
+  if (parser === null) {
+    throw new Error(`No parser registered for format '${format}'`);
+  }
+  return parser;
+}
+function explainEngineFromDriverName(name) {
+  const normalizedName = name.trim().toLowerCase();
+  switch (normalizedName) {
+    case "postgres":
+    case "postgresql":
+    case "pg":
+      return "postgres";
+    case "mysql":
+    case "mariadb":
+      return "mysql";
+    case "sqlite":
+    case "sqlite3":
+      return "sqlite";
+  }
+  const parser = listExplainParsers().find(
+    (candidate) => candidate.engine.trim().toLowerCase() === normalizedName
+  );
+  return parser?.engine ?? null;
+}
+async function detectFormat(raw) {
+  return await detectFormatFor(raw, null);
+}
+async function detectFormatFor(raw, engine) {
+  switch (engine) {
+    case "postgres":
+      return Promise.resolve(detectPostgresFormat(raw));
+    case "mysql":
+      if (looksLikeJson(raw)) return Promise.resolve("mysql-json");
+      if (raw.trim() === "") {
+        throw new Error("Unsupported EXPLAIN file format: input is empty");
+      }
+      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"
+      );
+    case null: {
+      const builtinFormat = detectPostgresFormatOrNull(raw);
+      if (builtinFormat !== null) return builtinFormat;
+      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 = await sniffRegisteredFormat(raw, engine);
+      if (format !== null) return format;
+      throw new Error(`Unsupported EXPLAIN file format for engine '${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");
+}
+function detectPostgresFormatOrNull(raw) {
+  if (looksLikeJson(raw)) return "postgres-json";
+  if (looksLikePostgresText(raw)) return "postgres-text";
+  return null;
+}
+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)) {
+      continue;
+    }
+    if (normalizedEngine !== null && parser.engine.trim().toLowerCase() !== normalizedEngine) {
+      continue;
+    }
+    if (parser.sniff === void 0) continue;
+    try {
+      if (await parser.sniff(raw)) return parser.format;
+    } catch {
+    }
+  }
+  return null;
+}
+function looksLikeJson(raw) {
+  const trimmed = raw.trimStart();
+  return trimmed.startsWith("[") || trimmed.startsWith("{");
+}
+function looksLikePostgresText(raw) {
+  return raw.split("\n").some((line) => line.includes("(cost=") && line.includes("width="));
+}
+function parseExplain(raw) {
+  return parseExplainFor(raw, null);
+}
+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 === "") {
+    return { ...plan, original_query: `-- loaded from ${name}` };
+  }
+  return plan;
+}
+
+// src/raw.ts
+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 = await parser.parse(raw.payload);
+  return {
+    ...plan,
+    driver: raw.engine,
+    original_query: raw.original_query
+  };
+}
+function resolveExplainOutput(output) {
+  return output.kind === "plan" ? Promise.resolve(output.plan) : parseRawExplain(output.raw);
+}
 
 // src/metrics.ts
 var EXPLAIN_METRIC_KINDS = [
@@ -1202,16 +1320,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) {
@@ -1360,7 +1472,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;
@@ -1406,7 +1518,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,
@@ -1450,14 +1562,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 = {
@@ -1643,9 +1774,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();
@@ -1789,4 +1918,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, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getMetricMax, getMetricValue, getNodeCostStyle, getNodeDiagnostics, getNodeMetrics, getPlanDiagnostics, getRowEstimateRatio, getWorstSeverity, hasAnalyzeDataRecursive, isMetricAvailable, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, resolveExplainOutput, 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 };