sparkforensics-server 0.6.0 → 0.8.1

package/vendor-core/mcp-tools.js

@@ -1,17 +1,21 @@
 import { resolve as resolvePath, join, dirname } from 'node:path';
-import { existsSync, statSync, readFileSync } from 'node:fs';
+import { existsSync, statSync, readFileSync, readdirSync,            } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { collectRun } from './cli/collect-run.js';
 import { deriveEvidenceAvailability } from './evidence-availability.js';
 import { resolveFromShs, DEFAULT_MAX_ARCHIVE_BYTES, DEFAULT_IDLE_TIMEOUT_MS } from './shs-load.js';
 import { mcpError } from './mcp-error.js';
-import { buildEvidenceReport, runFindings, toFindingsFilter,                                                                                                               } from './evidence-report.js';
+import {
+  buildEvidenceReport, runFindings, toFindingsFilter,
+                                                                                                                                                       
+} from './evidence-report.js';
 import { computeWallClock } from './wall-clock.js';
 import { renderComparisonMarkdown,                        } from './run-comparison.js';
 import { buildComparisonOutput,                       } from './comparison-output.js';
 import { compileNormalizePatterns } from './stage-alignment.js';
-import { runOutputBlocks } from './run-output.js';
+import { compileConfIgnorePatterns } from './comparability.js';
+import { runOutputBlocks,                      } from './run-output.js';
 import { evaluateBudgets,                                       } from './cli/budgets.js';
 import { assertStageBudgetMetric, combineRegressionBudgets } from './cli/regression-budgets.js';
 import { FINDING_NAMES, titleCase } from './finding-names.js';
@@ -20,7 +24,7 @@ import { DETECTORS,                         } from './detectors.js';
 import { tunedDetectors } from './threshold-overrides.js';
 import { tuningDocSlugForAnchor, pageForAnchor } from './docs-config.js';
 import { typeTag } from './format-utils.js';
-                                                                                   
+                                                                                               
                                                
 
                                                                                                      
@@ -53,7 +57,7 @@ import { typeTag } from './format-utils.js';
                                                                 
                  
                  
-                                                                               
+                                                                                 
                                               
                                             
  
@@ -72,18 +76,70 @@ const CACHE_TTL_MS = envInt('SPARKFORENSICS_MCP_CACHE_TTL_MS', 15 * 60 * 1000);
 
 const byRunId = new Map                    ();   // runId -> { appModel, cacheKey, lastAccess }
 const byCacheKey = new Map                (); // cacheKey -> runId
+// Built comparisons, keyed by both runs and every option that changes the output. Each entry follows
+// its runs' TTL and eviction (deleteRunEntry), and the map is capped on its own: a comparison holds
+// a row per paired stage, and 8 runs allow 56 ordered pairs.
+const COMPARISON_CACHE_CAP = 16;
+                                                                                                                  
+const comparisonCache = new Map                              ();
+// Threshold overrides are one fixed object per server process (or DEFAULT for none): identity keys them.
+const thresholdsIds = new WeakMap                ();
+let nextThresholdsId = 1;
+function thresholdsKey(thresholds                                )         {
+  if (!thresholds) return 0;
+  let id = thresholdsIds.get(thresholds);
+  if (id === undefined) {
+    id = nextThresholdsId++;
+    thresholdsIds.set(thresholds, id);
+  }
+  return id;
+}
+
 const pendingByCacheKey = new Map                                                        (); // cacheKey -> in-flight Promise<{runId, appModel}>
 
 export function pathCacheKey(path        )         {
   const resolved = resolvePath(path);
   if (!existsSync(resolved)) throw mcpError('invalid-event-log', `No such file: ${resolved}`);
+  const stat = statSync(resolved);
+  // A rolling event-log directory grows by appending to its live events_N file, which leaves the
+  // directory's own mtime and size alone: the key covers the files inside it.
+  if (stat.isDirectory()) return `path:${resolved}:${directoryStatKey(resolved)}`;
   // Size narrows a same-millisecond mtime collision; ctime narrows the case where a copy tool
   // (rsync --preserve-times, tar) restores an identical mtime+size for different content: ctime
   // can't be set by the copying tool, so it still reflects when the file landed on disk.
-  const { mtimeMs, ctimeMs, size } = statSync(resolved);
-  return `path:${resolved}:${mtimeMs}:${ctimeMs}:${size}`;
+  return `path:${resolved}:${fileStatKey(stat)}`;
+}
+
+function fileStatKey({ mtimeMs, ctimeMs, size }       )         {
+  return `${mtimeMs}:${ctimeMs}:${size}`;
 }
 
+// The file count, newest mtime and ctime, and total size of the files under a directory (the
+// parts of a rolling log, which Spark appends to in place): any part growing, arriving or going
+// changes it.
+function directoryStatKey(dir        )         {
+  let files = 0, mtimeMs = 0, ctimeMs = 0, size = 0;
+  const walk = (path        , depth        )       => {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < ROLLING_LOG_DEPTH) walk(child, depth + 1);
+        continue;
+      }
+      const stat = statSync(child);
+      files++;
+      mtimeMs = Math.max(mtimeMs, stat.mtimeMs);
+      ctimeMs = Math.max(ctimeMs, stat.ctimeMs);
+      size += stat.size;
+    }
+  };
+  walk(dir, 0);
+  return `dir:${files}:${mtimeMs}:${ctimeMs}:${size}`;
+}
+// A rolling log's parts sit in the directory the path names, or one level down in its
+// eventlog_v2_* subdirectory.
+const ROLLING_LOG_DEPTH = 1;
+
 function shsCacheKey({ shsBaseUrl, appId, attemptId }                                                           )         {
   return `shs:${shsBaseUrl}:${appId}:${attemptId ?? ''}`;
 }
@@ -99,6 +155,10 @@ function touch(runId        )       {
 
 function deleteRunEntry(id        , entry            )       {
   byRunId.delete(id);
+  // A comparison outlives neither of its runs: its entry goes with the first one evicted.
+  for (const [key, cached] of comparisonCache) {
+    if (cached.runIdA === id || cached.runIdB === id) comparisonCache.delete(key);
+  }
   if (byCacheKey.get(entry.cacheKey) === id) byCacheKey.delete(entry.cacheKey);
 }
 
@@ -121,6 +181,11 @@ function evictOverflow()       {
   }
 }
 
+/** How many built comparisons the cache holds: the occupancy the cap and eviction rules bound. */
+export function comparisonCacheSize()         {
+  return comparisonCache.size;
+}
+
 export function getCachedAppModel(runId        )           {
   evictStale();
   const entry = byRunId.get(runId);
@@ -166,6 +231,8 @@ export async function resolveOrCreateRun(
       const appModel = 'path' in source
         ? await resolveFromPath(source.path)
         : (await resolveFromShs(source.shsBaseUrl, source.appId, source.attemptId, { fetchImpl, maxArchiveBytes, idleTimeoutMs })).appModel;
+      // The attempt the caller asked the History Server for, when the log itself does not name one.
+      if (!('path' in source) && source.attemptId && appModel.app && !appModel.app.attemptId) appModel.app.attemptId = source.attemptId;
 
       const newRunId = randomUUID();
       byRunId.set(newRunId, { appModel, cacheKey, lastAccess: Date.now() });
@@ -180,30 +247,83 @@ export async function resolveOrCreateRun(
   return resolution;
 }
 
+/** `compact`: an index, one short row per finding and no clean or not-run check lists. `full`: the
+ * report as the CLI writes it. */
+                                              
+
+/** A finding as `view: 'compact'` lists it: enough to rank it, name it and pair it across reruns.
+ * The rest of the row (recommendation, evidence, remediation, estimate) comes from
+ * `get_finding_evidence` by `id`. */
+                                    
+                                                                          
+                                                                                    
+                                                                  
+                                                 
+                                    
+ 
+
+export function compactFindingRow(row            )                    {
+  return {
+    id: row.id, key: row.key, type: row.type, tag: row.tag, name: row.name,
+    impactBand: row.impactBand, stageId: row.stageId, actionLabel: row.actionLabel,
+    metric: row.metric ?? null, value: row.value ?? null,
+    ...(row.valueText !== undefined ? { valueText: row.valueText } : {}),
+    ...(row.impact !== undefined ? { impact: row.impact, impactMeaning: row.impactMeaning ?? null } : {}),
+    // Kept: a tuned finding's impact figure is uncalibrated, and a reader must see that on its row.
+    ...(row.tunedThresholds !== undefined ? { tunedThresholds: row.tunedThresholds } : {}),
+  };
+}
+
+/** A verdict step with its lead finding's row, which `findings` may not list under `maxFindings` or
+ * `minBand`. Null for a step whose lead has no id. */
+                                                                                                          
+
+                                 
+                                    
+                                                                         
+                                                  
+                                                                    
+                          
+                       
+                                       
+                                                    
+                           
+                                                                     
+                                                                                 
+                                                                                                                
+
 // `thresholds` on every analyzing tool below: the server's --thresholds overrides, fixed for the
 // process by createMcpServer(). A client can't set them per call; the dashboard never has them.
+// `view` defaults to `full` here; the MCP tool defaults it to `compact`.
 export function diagnoseRun(runId        , opts    
                                                                                                           
-                                                                                            
- )   
-                                                                                                      
-                                                                                                         
-                                                    
-                                                                                 
-                                                                                                                {
+                                                                                                                         
+                                                                  
+ )                    {
   const appModel = getCachedAppModel(runId);
-  const findingsFilter = toFindingsFilter(opts?.impactBand, opts?.type, opts?.stageId);
-  const { json, markdown } = buildEvidenceReport(appModel, {
+  const view = opts?.view ?? 'full';
+  const findingsFilter = toFindingsFilter(opts?.impactBand, opts?.type, opts?.stageId, opts?.minBand, opts?.maxFindings);
+  const { json, markdown, findingsMatched } = buildEvidenceReport(appModel, {
     redact: opts?.redact, markdown: opts?.markdown, findingsFilter, thresholds: opts?.thresholds,
   });
+  // The lead rows come from the unfiltered report (cached, so this costs no second analysis).
+  const allRows = findingsFilter
+    ? buildEvidenceReport(appModel, { redact: opts?.redact, markdown: false, thresholds: opts?.thresholds }).json.findings
+    : json.findings;
+  const shape = (row            )                                 => (view === 'compact' ? compactFindingRow(row) : row);
+  const steps = json.verdict.steps.map((step)                      => {
+    const lead = step.leadFindingId == null ? undefined : allRows.find((row) => row.id === step.leadFindingId && row.type === step.type);
+    return { ...step, leadFinding: lead ? shape(lead) : null };
+  });
   const include = opts?.include ?? [];
   const tuned = json.summary.tunedThresholds;
   return {
-    runId, verdict: json.verdict, findings: json.findings, recommendations: json.recommendations, cleanChecks: json.cleanChecks,
-    notRunChecks: json.notRunChecks,
+    runId, view, verdict: { ...json.verdict, steps }, findings: json.findings.map(shape), findingsOmitted: findingsMatched - json.findings.length,
+    recommendations: json.recommendations,
+    ...(view === 'full' ? { cleanChecks: json.cleanChecks, notRunChecks: json.notRunChecks } : {}),
     // The CLI report's own blocks, so a run reads the same through either surface.
     writeTargets: json.writeTargets,
-    ...runOutputBlocks(appModel, { redact: opts?.redact, thresholds: opts?.thresholds }),
+    ...runOutputBlocks(appModel, { redact: opts?.redact, thresholds: opts?.thresholds, generator: opts?.generator }),
     runComplete: appModel.app?.endTime != null,
     // Top level too, so a client that never asks for `summary` still sees the run was tuned.
     ...(tuned ? { tunedThresholds: tuned } : {}),
@@ -214,6 +334,16 @@ export function diagnoseRun(runId        , opts
   };
 }
 
+/** The few fields `format: 'md'` returns as `structuredContent`: the Markdown carries the rest. */
+export function diagnoseHeadline(result                   )   
+                                                                                                                                 
+  {
+  return {
+    runId: result.runId, runComplete: result.runComplete, title: result.verdict.title,
+    findingCount: result.findings.length, findingsOmitted: result.findingsOmitted, recommendationCount: result.recommendations.length,
+  };
+}
+
 const DOCS_CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), 'docs-content');
 
 // Both vendored corpora lead with their own heading line; strips the leading '#'/'###' markers, an
@@ -351,6 +481,7 @@ async function resolveAndAnalyze(
 
 export async function compareRuns(
   a        , b        , opts                                                                                                              
+                                                                                    
                                                                                                                   ,
 )                                                                                                           {
   // Before any log is read: a bad pattern refuses the call, as the CLI's usage error does.
@@ -359,6 +490,11 @@ export async function compareRuns(
   } catch (e) {
     throw mcpError('access-or-upstream-failure', `normalizePath: ${(e         ).message}`);
   }
+  try {
+    compileConfIgnorePatterns(opts?.ignoreConf);
+  } catch (e) {
+    throw mcpError('access-or-upstream-failure', `ignoreConf: ${(e         ).message}`);
+  }
   const [
     { runId: runIdA, appModel: appModelA, catalog: catalogA },
     { runId: runIdB, appModel: appModelB, catalog: catalogB },
@@ -368,11 +504,30 @@ export async function compareRuns(
   // interactive stage-detail drill-down, which none of compare/matchStages/metricDeltas/findingsDelta
   // read. Findings/metrics come from `catalog` and appModel.stages/sql, both fully populated. Produces
   // identical output to the dashboard; the MCP tool just never exposes per-task drill-down.
-  const { comparison, output } = buildComparisonOutput(
-    { label: runIdA, appModel: appModelA, catalog: catalogA },
-    { label: runIdB, appModel: appModelB, catalog: catalogB },
-    { redact: opts?.redact, normalizePath: opts?.normalizePath, view: opts?.include?.includes('stagePairs') ? 'full' : 'summary' },
-  );
+  const view = opts?.include?.includes('stagePairs') ? 'full' : 'summary';
+  const cacheKey = JSON.stringify([runIdA, runIdB, thresholdsKey(opts?.thresholds), !!opts?.redact, view, opts?.normalizePath ?? [], opts?.ignoreConf ?? [], opts?.noiseBand ?? null, opts?.generator ?? null]);
+  let built = comparisonCache.get(cacheKey)?.built;
+  if (built) {
+    // Re-insert so the oldest entry is the least recently used.
+    comparisonCache.delete(cacheKey);
+    comparisonCache.set(cacheKey, { runIdA, runIdB, built });
+  } else {
+    built = buildComparisonOutput(
+      { label: runIdA, appModel: appModelA, catalog: catalogA },
+      { label: runIdB, appModel: appModelB, catalog: catalogB },
+      { redact: opts?.redact, normalizePath: opts?.normalizePath, ignoreConf: opts?.ignoreConf, noiseBand: opts?.noiseBand, view, generator: opts?.generator },
+    );
+    // Either run can be evicted while the other one is still being read or parsed (the awaits
+    // above): an entry for a run that is gone would outlive its eviction, so it is only kept
+    // while both are cached.
+    if (byRunId.has(runIdA) && byRunId.has(runIdB)) {
+      comparisonCache.set(cacheKey, { runIdA, runIdB, built });
+      while (comparisonCache.size > COMPARISON_CACHE_CAP) comparisonCache.delete(comparisonCache.keys().next().value );
+    }
+  }
+  const { comparison } = built;
+  // A copy, so a caller that changes the result cannot change what the next caller is served.
+  const output = structuredClone(built.output);
 
   return {
     runIdA,

package/vendor-core/median.js

@@ -1,5 +1,5 @@
-// The textbook median of values already sorted ascending: the middle value for an odd count, the
-// mean of the two middle values for an even one. 0 for an empty list.
+// Median of values already sorted ascending: the mean of the two middle values on an even count.
+// 0 for an empty list.
 export function medianOfSorted(sorted                   )         {
   const n = sorted.length;
   if (n === 0) return 0;

package/vendor-core/nested-loop-join.js

@@ -0,0 +1,73 @@
+// Reads a nested-loop join's operator, join type and condition from its plan line, and the row
+// counts around it from the executors' "number of output rows" metric.
+//
+// Spark plans a join with no equi-join keys as a BroadcastNestedLoopJoin when one side can be
+// broadcast, else a CartesianProduct for an inner-like join (JoinSelection in
+// sql/core/src/main/scala/org/apache/spark/sql/execution/SparkStrategies.scala, v3.5.0). Both
+// compare every left row with every right row.
+                                           
+
+                                                                                
+
+                                      
+                               
+                                                                                                
+                          
+                                                                                     
+                           
+ 
+
+const OUTPUT_ROWS = 'number of output rows';
+
+// BroadcastNestedLoopJoin <BuildLeft|BuildRight>, <JoinType>[, <condition>]
+const BNLJ_LINE = /^BroadcastNestedLoopJoin\s+Build(?:Left|Right),\s*(\w+)(?:,\s*([\s\S]+))?$/;
+// CartesianProduct[ <condition>]: the operator only plans inner-like joins and prints no type.
+const CARTESIAN_LINE = /^CartesianProduct(?:\s+([\s\S]+))?$/;
+
+function cleanCondition(raw                    )                {
+  const text = (raw ?? '').replace(/#\d+L?/g, '').trim();
+  return text.length > 0 ? text : null;
+}
+
+/** The nested-loop operator, join type and condition behind a plan node, or null for any other node. */
+export function parseNestedLoopJoin(node                                   )                             {
+  const detail = (node.detail ?? '').trim();
+  if (node.name === 'BroadcastNestedLoopJoin') {
+    const m = detail.match(BNLJ_LINE);
+    return { operator: 'BroadcastNestedLoopJoin', joinType: m?.[1] ?? null, condition: cleanCondition(m?.[2]) };
+  }
+  if (node.name === 'CartesianProduct') {
+    const m = detail.match(CARTESIAN_LINE);
+    return { operator: 'CartesianProduct', joinType: 'Inner', condition: cleanCondition(m?.[1]) };
+  }
+  return null;
+}
+
+// Operators that pass every row of their one child through, so the child's row count is theirs.
+// A node outside this list that reports no row metric (Expand, Union, Limit...) can change the
+// count, so the walk stops there rather than guess.
+const ROW_PRESERVING = new Set([
+  'WholeStageCodegen', 'InputAdapter', 'Project', 'Sort', 'Exchange', 'BroadcastExchange',
+  'ShuffleQueryStage', 'BroadcastQueryStage', 'AQEShuffleRead', 'CustomShuffleReader',
+  'ColumnarToRow', 'AdaptiveSparkPlan',
+]);
+
+/** The rows a subtree produced: the nearest "number of output rows" at or below `node`, walking
+ * through row-preserving single-child operators. Null when the log reports none for it. */
+export function outputRowsOf(node          )                {
+  let current                       = node;
+  while (current) {
+    const metric = current.metrics?.find((m) => m.name === OUTPUT_ROWS);
+    if (metric) return metric.value;
+    const preserving = ROW_PRESERVING.has(current.name) || /^WholeStageCodegen/.test(current.name);
+    if (!preserving || current.children.length !== 1) return null;
+    current = current.children[0];
+  }
+  return null;
+}
+
+/** The node's own "number of output rows" value, null when absent. */
+export function ownOutputRows(node          )                {
+  const metric = node.metrics?.find((m) => m.name === OUTPUT_ROWS);
+  return metric ? metric.value : null;
+}

package/vendor-core/occupancy.js

@@ -193,8 +193,7 @@ export function stragglerFixLongestTaskMs(stage           )         {
                                                                                           
                                 
                                                                                                   
-                                                                                                  
-                                                                                  
+                                                         
                              
                                                                                                 
                                                                                   

package/vendor-core/parser-worker.js

@@ -251,7 +251,7 @@ export async function runParseFiles(
   emitParseCompletion(state, emit, linesProcessed);
 }
 
-// ─── Worker message bus (only active when running as a Web Worker) ──────────────
+// Message bus, active only when running as a Web Worker.
 
 const isWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
 

package/vendor-core/plan-graph-model.js

@@ -1,11 +1,11 @@
 // Flattens a resolved planTree into a { nodes, edges } graph shape for the
 // React Flow + Dagre plan graph view ("Plan graph view" in
 // docs-site/contributor-guide/architecture/drill-down/plan-graph.md). The Exchange
-// write/read split is done upstream now, in resolvePlanTree
-// (event-handlers.ts): this file just walks the already-split tree and maps
-// each real PlanNode onto a PlanGraphNodeData. sourceNodeId still lets a
-// write half point back to its read half's id, so aggregate logic over
-// nodes can group a pair without special-casing exchangeRole everywhere.
+// write/read split happens upstream in resolvePlanTree (event-handlers.ts):
+// this file walks the already-split tree and maps each PlanNode onto a
+// PlanGraphNodeData. sourceNodeId lets a write half point back to its read
+// half's id, so aggregate logic can group a pair without special-casing
+// exchangeRole.
 import { walkPlanTree } from './plan-tree-walk.js';
 import {
   classifyNode,
@@ -82,15 +82,9 @@ export function buildPlanGraphModel(
 
   const durationMap =
     sqlExec && sqlExecutionId != null ? buildDurationMap(planTree, appModel, sqlExec, sqlExecutionId, durationMode) : null;
-  // A second, always-exclusive map, independent of the requested `durationMode`.
-  // Exclusive shares are a true, non-overlapping partition of each paired
-  // stage's wall time (computeExclusiveSharesForPairs), so their sum is a
-  // stable normalization total. PlanGraphCanvas needs this alongside
-  // `durationMap` (the mode-selected values actually shown) because summing
-  // `durationMap` itself would double/triple-count under 'inclusive' mode,
-  // where an ancestor's share already folds in every descendant's share.
-  // durationMode === 'exclusive' already computed the same map above; only
-  // redo the work when the requested mode actually differs.
+  // Always-exclusive map, independent of `durationMode`: the stable total a
+  // percentage denominator sums (see PlanGraphNodeData.exclusiveDurationShare).
+  // Reuses `durationMap` when the requested mode is already exclusive.
   const exclusiveDurationMap =
     durationMode === 'exclusive'
       ? durationMap
@@ -110,14 +104,12 @@ export function buildPlanGraphModel(
     }
   }
 
-  // resolvePlanTree (event-handlers.ts) now prefixes every id with its owning
-  // execution, but this filter stays as defense in depth: a finding is scoped
-  // to the execution whose graph is being built before it's indexed by node
-  // id, so a stale/synthetic finding whose planNodeIds happen to collide with
-  // this tree's ids (e.g. hand-built test fixtures, or data from before the
-  // prefix existed) still can't badge onto the wrong tree. No linked SQL
-  // execution means no findings attach, matching the sqlExec-falsy behavior
-  // used elsewhere in this function (durationMap, linkedStageIds).
+  // resolvePlanTree (event-handlers.ts) prefixes every id with its owning
+  // execution, but a finding is also scoped to the execution whose graph is
+  // being built, as defense in depth: a synthetic finding whose planNodeIds
+  // collide with this tree's ids (e.g. hand-built test fixtures) cannot badge
+  // onto the wrong tree. No linked SQL execution means no findings attach,
+  // like durationMap and linkedStageIds above.
   const findingsByNodeId = new Map                   ();
   if (sqlExecutionId != null) {
     for (const finding of findings) {

package/vendor-core/plan-node-detail.js

@@ -164,9 +164,8 @@ export function buildDurationMap(
     const s = appModel.stages.get(id);
     if (s) stagesById.set(id, { submittedAt: s.submittedAt, completedAt: s.completedAt });
   }
-  // attributeStageDurationToPlan reads its 3rd arg's own `.stageIds` field;
-  // override it with the derived array rather than the (always-empty on real
-  // data) one already on `sqlExec`.
+  // attributeStageDurationToPlan reads `.stageIds`; use the derived array, not sqlExec's own
+  // (see contributor-guide/architecture/detector-contract/plan-attribution.md).
   return durationMode === 'inclusive'
     ? attributeStageDurationToPlanInclusive(planTree, stagesById, { ...sqlExec, stageIds })
     : attributeStageDurationToPlan(planTree, stagesById, { ...sqlExec, stageIds });

package/vendor-core/plan-summary.js

@@ -1,4 +1,4 @@
-// Best-effort summary of a resolved plan tree (parser-worker `resolvePlanTree`).
+// Best-effort summary of a resolved plan tree (`resolvePlanTree` in event-handlers.ts).
 // Unparseable fragments are silently skipped, never surfaced as an error.
 
                                            
@@ -56,14 +56,14 @@ export function isDeltaLogRead(name        , detail        )          {
 }
 
 // Stable relation-identity key for a scan node: "<format>:<relation>" (e.g.
-// "delta:mx.store_map", "parquet:warehouse.sales", "jdbc:dw.dim_product")
+// "delta:db.t", "parquet:db.a", "jdbc:db.b")
 // or null when the node is internal Delta metadata / a non-scan / un-nameable.
 // The single source of truth for scan identity, shared by `visitScan` (summary)
 // and the `cachingOpportunity` detector so the regexes live in one place.
 export function scanRelationId(name        , detail        )                {
-  // 1. Named catalog table, untruncated, from the nodeName (the key fix; the
-  //    Location: path is truncated at ~100 chars and points at _delta_log for
-  //    Delta tables). All catalog tables surface as `spark_catalog.<db>.<table>`.
+  // Named catalog table, untruncated, from the nodeName (the Location: path is truncated at
+  // ~100 chars and points at _delta_log for Delta tables). All catalog tables surface as
+  // `spark_catalog.<db>.<table>`.
   let format = null, table = null;
   const nameM = name.match(/^Scan\s+(parquet|orc|csv|json)\s+(spark_catalog\.\S+)$/i);
   // Fast reject: every branch below that returns a key needs this name match, a FileScan
@@ -81,12 +81,12 @@ export function scanRelationId(name        , detail        )                {
     return `${format}:${table.replace(/^spark_catalog\./, '')}`;
   }
 
-  // 2. Internal Delta metadata (see isDeltaLogRead) → null.
+  // Internal Delta metadata (see isDeltaLogRead): no relation.
   if (isDeltaLogRead(name, detail)) return null;
 
-  // 3. Anonymous real file read (InMemoryFileIndex, no catalog name) →
-  //    best-effort Location basename. Preserves temp/snapshot self-reuse; a
-  //    truncated Location can still fragment these; inherent, unrecoverable.
+  // Anonymous real file read (InMemoryFileIndex, no catalog name): best-effort Location basename.
+  // Preserves temp/snapshot self-reuse; a truncated Location can still fragment these, which is
+  // unrecoverable.
   const fileM = detail.match(/FileScan\s+(parquet|orc|csv|json)\b/i);
   if (fileM) {
     const locM = detail.match(/Location:[^[]*\[([^\]]+)\]/);
@@ -94,15 +94,14 @@ export function scanRelationId(name        , detail        )                {
     return `${fileM[1].toLowerCase()}:${pathBasename(locM[1].split(',')[0].trim())}`;
   }
 
-  // 4. JDBC: the inner SQL's first real table, lowercased. null when the first
-  //    post-FROM token is a subquery `(` or there is no single table (CTE/UNION).
+  // JDBC: the inner SQL's first real table, lowercased. null when the first post-FROM token is a
+  // subquery `(` or there is no single table (CTE/UNION).
   if (/JDBCRelation/.test(detail)) {
     const fromM = jdbcSql(detail).match(/\bFROM\s+(\(|[A-Za-z_][\w.]*)/i);
     if (!fromM || fromM[1] === '(') return null;
     return `jdbc:${fromM[1].toLowerCase()}`;
   }
 
-  // 5. Non-scan / unrecognized.
   return null;
 }
 
@@ -139,9 +138,17 @@ function visitScan(name        , detail        , result             )          {
   return true;
 }
 
+// <JoinOp> [leftKeys], [rightKeys], <JoinType>[, BuildSide]; the join type is Spark's JoinType.sql
+// name (Inner, LeftOuter, RightOuter, FullOuter, LeftSemi, LeftAnti, Cross, ExistenceJoin(...)).
+const JOIN_DETAIL = /^(SortMergeJoin|BroadcastHashJoin|ShuffledHashJoin|BroadcastNestedLoopJoin)\s+(\[[^\]]*\]),\s*(\[[^\]]*\]),\s*(\w+)/;
+
+/** The join type a keyed join node's detail names, or null when the detail is not a join line. */
+export function parseJoinType(detail        )                {
+  return JOIN_DETAIL.exec(detail)?.[4] ?? null;
+}
+
 function visitJoin(_name        , detail        , result             )          {
-  // <JoinOp> [leftKeys], [rightKeys], <JoinType>[, BuildSide]
-  const m = detail.match(/^(SortMergeJoin|BroadcastHashJoin|ShuffledHashJoin|BroadcastNestedLoopJoin)\s+(\[[^\]]*\]),\s*(\[[^\]]*\]),\s*(\w+)/);
+  const m = detail.match(JOIN_DETAIL);
   if (m) {
     result.joins.push({ joinType: m[1], leftKeys: parseColList(m[2]), rightKeys: parseColList(m[3]) });
     if (/^Cross$/i.test(m[4])) pushCrossJoinWarning(result, 'Cross join');
@@ -217,13 +224,12 @@ export function describePlanNode(
     pushCrossJoinWarning(result, 'CartesianProduct');
   } else if (visitScan(name, detail, result)) {
     recognizedType = 'scan';
-    // handled
   } else if (/Join/i.test(name) && visitJoin(name, detail, result)) {
     recognizedType = 'join';
-    // handled (a Cross join type may also have pushed a crossJoin warning)
+    // A Cross join type may also have pushed a crossJoin warning.
   } else if (/Aggregate/i.test(name) && visitAgg(name, detail, result)) {
     recognizedType = 'agg';
-    // handled (a partial-aggregation pass pushes nothing into result.aggs)
+    // A partial-aggregation pass pushes nothing into result.aggs.
   } else if (isExchangeNode(node)) {
     recognizedType = 'exchange';
     visitExchange(detail, result);
@@ -242,10 +248,9 @@ export function describePlanNode(
   const fields = result.scans[0] ?? result.joins[0] ?? result.aggs[0] ?? result.exchanges[0] ?? null;
   const warning = result.warnings[0] ?? null;
 
-  // Return null if no recognized type, or if it's agg/filter with no content/warning
+  // An agg or filter with no content or warning is not described.
   if (!recognizedType) return null;
   if ((recognizedType === 'agg' || recognizedType === 'filter') && !kind && !warning) return null;
 
-  // For exchange or other types, or if there's content/warning, return the object
   return { kind, warning, ...(fields ?? {}) };
 }

package/vendor-core/plan-tree-walk.js

@@ -1,12 +1,10 @@
-// Canonical iterative walk over a resolved planTree (parser-worker.js
-// resolvePlanTree). Every plan-*.js consumer and the sql-scope detectors in
-// detectors.js need the same traversal: this is the single implementation
-// they all share, so it must not import from detectors.js (or vice versa).
+// Canonical iterative walk over a resolved planTree (resolvePlanTree in event-handlers.ts). Every
+// plan-*.ts consumer and the sql-scope detectors in detectors.ts need the same traversal: this is
+// the single implementation they all share, so it must not import from detectors.ts (or vice versa).
 //
-// Pre-order, left-to-right child order (children are reverse-pushed so the
-// leftmost pops first): plan-summary.js's finding order depends on this.
-// `visit(node, parent)` gets the parent so callers needing per-edge or
-// per-node state (plan-dot.js's edges, plan-duration-attribution.js's segment
+// Pre-order, left-to-right child order (children are reverse-pushed so the leftmost pops first):
+// plan-summary.ts's finding order depends on this. `visit(node, parent)` gets the parent so callers
+// needing per-edge or per-node state (plan-dot.ts's edges, plan-duration-attribution.ts's segment
 // index) can track it themselves via a Map keyed by node.
 export function walkPlanTree                              (
   root                      ,