sparkforensics-cli 0.1.0 → 0.2.0

package/vendor-core/evidence-report.js

@@ -1,11 +1,10 @@
-// Portable, redacted evidence report (ELV-002). Pure builder over an appModel:
-// runs the detectors, then serializes a run summary + every finding into a
-// deterministic, byte-stable JSON document plus a human-readable Markdown
-// rendering. Raw task records are never included (privacy baseline); identifier
-// redaction is opt-in via { redact: true }.
+// Portable, redacted evidence report. Pure builder over an appModel: runs the detectors,
+// then serializes a run summary + findings into a deterministic, byte-stable JSON + Markdown.
+// Raw task records are never included (privacy baseline); redaction is opt-in via { redact: true }.
 import { analyze, auditConfig } from './analyzer.js';
 import { detectorCatalog } from './detectors.js';
 import { typeTag, formatBytes, formatDuration, IMPACT_BAND_ORDER } from './format-utils.js';
+import { FINDING_NAMES, titleCase } from './finding-names.js';
 import { redactReport } from './redact.js';
 import { coreFindingActionLabel } from './finding-action-label.js';
 import { matchesFindingFilterCriteria } from './finding-filter-predicate.js';
@@ -17,42 +16,28 @@ import { getThresholdSummary } from './threshold-summary.js';
 
 export const EVIDENCE_SCHEMA_VERSION         = 3;
 
-// NOTE on deviations from the plan's literal interface text: `findingRow`
-// below always sets `id`/`metric`/`value`/`recommendation` via `?? null`
-// (never omits the key), and `buildJson` always sets `evidenceAvailability`
-// and `summary.app.{id,name,sparkVersion}` via `?? null` too (AppModel's own
-// `evidenceAvailability` field is `EvidenceAvailability | null`, `app` is
-// `SparkAppInfo | null`, and `SparkAppInfo.sparkVersion` documents `null` as
-// a deliberate "unknown version" sentinel distinct from absence). So these
-// can genuinely be `null` at runtime even though the plan pins them as
-// plain/optional non-null types. Widened here to match reality rather than
-// masking it with a cast, and kept as `?? null`, not `?? undefined`: since
-// JSON.stringify drops `undefined` keys but keeps `null`, using `undefined`
-// here would silently strip these fields from the serialized report.
+// findingRow always sets id/metric/value/recommendation via `?? null` (never omits the key), and
+// buildJson does the same for evidenceAvailability and summary.app.{id,name,sparkVersion}: these
+// are genuinely nullable at runtime (AppModel.app is nullable, sparkVersion documents null as an
+// "unknown version" sentinel). Kept as `?? null`, not `?? undefined`: JSON.stringify drops
+// undefined keys but keeps null, so undefined would silently strip these from the report.
 //
-// `value` is further widened to `number | string | null` (Task 22,
-// src/detectors.ts): `stageFailed` and the four `configAudit` entries put
-// human-readable text in `Finding.value` instead of a magnitude, and this
-// row shape carries that value through unchanged.
+// `value` is number|string|null: stageFailed and the configAudit entries put text in Finding.value
+// instead of a magnitude, carried through unchanged.
                              
-                                                                                        
+                                                                                                      
                                                                                                                  
                                                              
-                                                                                   
-                                                                              
-                                                                          
-                                                                            
-                                     
+                                                                                                  
+                                                                                                 
+                                                              
                       
                                                                        
                                   
  
 
-// The `Fix these first` rollup row (ELV-002 extension): one entry per
-// `buildRecommendationRollup` group, carrying the same impact-ranked
-// aggregation the dashboard's `FixTheseFirst.tsx` widget renders, so the
-// CLI/MCP/download paths get the "what's the highest-leverage fix" ranking
-// too, not just the flat impact-sorted `findings` list above.
+// The `Fix these first` rollup row: one entry per buildRecommendationRollup
+// group, so the CLI/MCP/download paths get the same impact-ranked aggregation the dashboard shows.
                                     
                
               
@@ -68,9 +53,8 @@ export const EVIDENCE_SCHEMA_VERSION         = 3;
                         
  
 
-// One line per detector `type` that fired zero findings this run, so a flat
-// evidence report can state "these were checked and came back clean" the
-// same way the dashboard's clean-checks table does.
+// One line per detector `type` that fired zero findings, so a flat report can state "these were
+// checked and came back clean" like the dashboard's clean-checks table.
                                   
                
               
@@ -94,19 +78,27 @@ export const EVIDENCE_SCHEMA_VERSION         = 3;
 // Fields surfaced as first-class report columns. Everything else on a finding
 // becomes its `evidence` payload (sorted for stable key order).
 const CORE_KEYS = new Set([
-  'id', 'type', 'impactBand', 'stageId', 'metric', 'value',
+  'id', 'type', 'name', 'impactBand', 'stageId', 'metric', 'value',
   'recommendation', 'detectorVersion', 'confidence', 'validationRequired', 'docAnchor', 'impactEstimate',
   'actionLabel',
 ]);
 
+// Internal-only fields with no meaning to a human reading this report: never surfaced as a core
+// column, and also excluded from the generic evidence dump (unlike stageIds, which IS actionable
+// to a reader). `planNodeIds` is view-layer plan-graph node ids (Plan Advisor detectors, see
+// plan-graph-model.ts): on a real log it can carry a hundred-plus ids, which would otherwise print
+// as one unreadable `- planNodeIds: [...]` line and bloat the report for no reader benefit.
+const NON_EVIDENCE_KEYS = new Set(['planNodeIds']);
+
 function findingRow(f         )             {
   const evidence                          = {};
   for (const k of Object.keys(f).sort()) {
-    if (!CORE_KEYS.has(k)) evidence[k] = (f                           )[k];
+    if (!CORE_KEYS.has(k) && !NON_EVIDENCE_KEYS.has(k)) evidence[k] = (f                           )[k];
   }
   const row             = {
     id: f.id ?? null,
     type: f.type,
+    name: titleCase(FINDING_NAMES[f.type] ?? f.type),
     tag: typeTag(f.type),
     impactBand: f.impactBand,
     stageId: f.stageId ?? null,
@@ -115,11 +107,9 @@ function findingRow(f         )             {
     recommendation: f.recommendation ?? null,
     detectorVersion: f.detectorVersion ?? 1,
     evidence,
-    // Deliberate simplification vs. the view layer's `REGISTRY[type]?.findingLabel`
-    // fallback (src/view/finding-action-label.ts): there's no widget registry at
-    // this layer, and falling back to the finding's own `type` is reasonable
-    // since coreFindingActionLabel's switch already covers every type the real
-    // detectors emit; only obscure/future unmatched sub-variants hit this fallback.
+    // Deliberate simplification vs the view layer's REGISTRY fallback: no widget registry here, and
+    // falling back to the finding's own `type` is fine since coreFindingActionLabel already covers
+    // every emitted type; only obscure/future sub-variants hit this fallback.
     actionLabel: coreFindingActionLabel(f) ?? f.type,
   };
   // Threshold/confidence provenance, only when the detector emitted it.
@@ -130,8 +120,8 @@ function findingRow(f         )             {
   return row;
 }
 
-// Deterministic finding order: impact band, then type, then stage, then id, so a
-// fixed appModel always serializes byte-for-byte identically.
+// Deterministic finding order: impact band, then type, then stage, then id, so a fixed appModel
+// always serializes byte-for-byte identically.
 function sortFindings(rows              )               {
   return [...rows].sort((a, b) => {
     const s = (IMPACT_BAND_ORDER[a.impactBand] ?? 9) - (IMPACT_BAND_ORDER[b.impactBand] ?? 9);
@@ -144,20 +134,13 @@ function sortFindings(rows              )               {
   });
 }
 
-// `isEligible`/`rankFindings` are shared with FixTheseFirst.tsx via
-// src/recommendation-rollup.ts (both files used to duplicate this logic
-// near-verbatim); this file's own `isEligible` call site omits
-// FixTheseFirst.tsx's extra `REGISTRY[finding.type] != null` check: every
-// real finding reaching this file already came out of `analyze()`/
-// `auditConfig()`, so it's always a known type, and REGISTRY (a `.tsx` file)
-// isn't importable from this core module anyway.
+// isEligible/rankFindings are shared with FixTheseFirst.tsx via recommendation-rollup.ts; this
+// file's isEligible call omits FixTheseFirst's REGISTRY check: every finding here already came out
+// of analyze()/auditConfig() so it's a known type, and REGISTRY (.tsx) isn't importable here anyway.
 
-// The impact-ranked "what's the highest-leverage fix" rollup, ported from
-// FixTheseFirst.tsx so the CLI/MCP/download paths get the same ranking the
-// dashboard shows. `buildRecommendationRollup` already returns groups in the
-// correct cross-group order (time groups by recoverable ms descending, then
-// resource/count groups by worst impact band), so this only maps each group to
-// its JSON row shape without re-sorting.
+// The impact-ranked "highest-leverage fix" rollup, ported from FixTheseFirst.tsx so CLI/MCP/download
+// get the same ranking. buildRecommendationRollup already returns groups in the correct cross-group
+// order, so this only maps each group to its JSON row without re-sorting.
 function buildRecommendations(
   findings           ,
   stages                                                             ,
@@ -181,10 +164,8 @@ function buildRecommendations(
         kind: 'time',
         stageCount: group.stageCount,
         recoverableMsHigh: group.recoverableMsHigh,
-        // A point estimate, not a range: matches FixTheseFirst.tsx's own
-        // `trailingStat` for time groups, which prints the same figure twice
-        // rather than the finding-level low-high spread this group already
-        // collapsed away via computeStageUnionMs.
+        // A point estimate, not a range: matches FixTheseFirst.tsx's trailingStat for time groups,
+        // which prints the same figure twice rather than the finding-level spread computeStageUnionMs collapsed.
         impact: formatWallClockRange(group.recoverableMsHigh, group.recoverableMsHigh),
       };
     }
@@ -208,25 +189,16 @@ function buildRecommendations(
   });
 }
 
-// Detector types that fired zero findings this run, so a flat evidence
-// report can state "these were checked and came back clean" the same way
-// the dashboard's clean-checks table does. Deliberately differs from the
-// dashboard's Alerts.tsx "Clean checks" table, which excludes
-// memoryUtilization/utilization/coreLocality (the "always-mounted reference"
-// widgets; see isAlwaysMountedType in src/view/detector-registry.tsx)
-// because those are already always shown as their own widget elsewhere on
-// the board. A flat evidence report has no such separate always-visible
-// surface for them, so this list intentionally includes them when they have
-// zero findings, rather than mirroring the UI's display-consolidation
-// exclusion.
+// Detector types that fired zero findings, so a flat report can state "checked and clean". Differs
+// from the dashboard's Alerts.tsx "Clean checks", which excludes coreLocality (the one remaining
+// always-mounted reference widget, shown elsewhere); a flat report has no such separate surface,
+// so this includes it too when it has zero findings.
 function buildCleanChecks(findings           )                    {
   const firedTypes = new Set(findings.map((f) => f.type));
   const seen = new Set        ();
   const entries                    = [];
-  // detectorCatalog() can list the same `type` more than once (configAudit
-  // has 4 separate DETECTORS entries, all `type: 'configAudit'`); dedupe by
-  // type, keeping first occurrence, so a type with several sibling detector
-  // entries still contributes exactly one clean-check line.
+  // detectorCatalog() can list the same type more than once (configAudit has 4 entries); dedupe by
+  // type, keeping first, so a type with sibling entries contributes exactly one clean-check line.
   for (const d of detectorCatalog()                           ) {
     if (firedTypes.has(d.type) || seen.has(d.type)) continue;
     seen.add(d.type);
@@ -235,15 +207,10 @@ function buildCleanChecks(findings           )                    {
   return entries;
 }
 
-// Keyed by appModel object identity, not runId: mcp-tools.ts caches one fixed
-// appModel per runId for the run's whole cached lifetime (resolveOrCreateRun
-// never mutates a cached entry's appModel), so re-running analyze()/
-// auditConfig() for the same appModel always reproduces the same catalog.
-// getFindingEvidence in particular calls buildEvidenceReport once per
-// drill-down on an already-diagnosed run; without this, N findings looked up
-// on one run meant N full detector re-runs. A WeakMap needs no explicit
-// invalidation: once mcp-tools.ts evicts the appModel, this entry is
-// unreachable and collectible too.
+// Keyed by appModel object identity: mcp-tools.ts caches one fixed appModel per runId (never
+// mutated), so re-running analyze()/auditConfig() reproduces the same catalog. getFindingEvidence
+// calls buildEvidenceReport once per drill-down; without this, N lookups meant N detector re-runs.
+// A WeakMap needs no invalidation: once mcp-tools.ts evicts the appModel, this entry is collectible.
 const jsonCache = new WeakMap                              ();
 
 function buildJson(appModel          )                     {
@@ -268,12 +235,8 @@ function buildJson(appModel          )                     {
     schemaVersion: EVIDENCE_SCHEMA_VERSION,
     summary: {
       app: {
-        // `?? null`, not `?? undefined`: pre-migration behavior (and
-        // SparkAppInfo.sparkVersion's own doc comment) treats `null` as a
-        // deliberate "unknown/absent" sentinel distinct from an omitted key.
-        // JSON.stringify drops `undefined` keys but keeps `null`, so using
-        // `?? undefined` here would have silently dropped these fields from
-        // the serialized report whenever `app` is null or its fields unset.
+        // `?? null`, not `?? undefined`: JSON.stringify drops undefined keys but keeps null, and
+        // sparkVersion's null is a deliberate "unknown/absent" sentinel; undefined would drop these.
         id: app?.id ?? null,
         name: app?.name ?? null,
         sparkVersion: app?.sparkVersion ?? null,
@@ -285,9 +248,8 @@ function buildJson(appModel          )                     {
       impactBandCounts,
     },
     evidenceAvailability: evidenceAvailability ?? null,
-    // Detector metadata (type/version/scope/thresholds/docAnchor) so the
-    // threshold set that produced each finding travels with the evidence.
-    // Order follows DETECTORS, which is stable => byte-stable serialization.
+    // Detector metadata so the threshold set that produced each finding travels with the evidence.
+    // Order follows DETECTORS (stable) => byte-stable serialization.
     detectors: detectorCatalog(),
     findings: rows,
     recommendations,
@@ -297,9 +259,8 @@ function buildJson(appModel          )                     {
   return result;
 }
 
-// Human-readable rendering of an evidence value. Byte-magnitude keys are
-// humanized (avgFileSizeBytes: 3.1 MB); objects/arrays serialize compactly so
-// no payload is silently dropped from the Markdown.
+// Human-readable rendering of an evidence value. Byte-magnitude keys are humanized; objects/arrays
+// serialize compactly so no payload is silently dropped from the Markdown.
 function renderEvidenceValue(key        , value         )         {
   if (typeof value === 'number' && /bytes$/i.test(key)) return formatBytes(value);
   if (value !== null && typeof value === 'object') return JSON.stringify(value);
@@ -359,7 +320,7 @@ function renderMarkdown(json                    )         {
   lines.push('');
   for (const r of findings) {
     const where = r.stageId != null ? ` (stage ${r.stageId})` : '';
-    lines.push(`### [${r.tag}] ${r.type} · ${r.impactBand}${where}`);
+    lines.push(`### ${r.name} · ${r.impactBand}${where}`);
     lines.push(`- action: ${r.actionLabel}`);
     if (r.metric != null) lines.push(`- ${r.metric}: ${r.value}`);
     if (r.recommendation) lines.push(`- ${r.recommendation}`);
@@ -368,9 +329,8 @@ function renderMarkdown(json                    )         {
     const impactText = r.impactEstimate ? renderImpactEstimate(r.impactEstimate) : null;
     if (impactText) lines.push(`- impact: ${impactText}`);
     lines.push(`- detector version: ${r.detectorVersion}`);
-    // Evidence payload (sorted for stable order) so two rows differing only by
-    // evidence (two smallFiles by direction, two partitionSizing by rule)
-    // render distinctly and carry the full AC3 field set into the Markdown.
+    // Evidence payload (sorted for stable order) so two rows differing only by evidence (two
+    // smallFiles by direction, two partitionSizing by rule) render distinctly.
     const evidence = Object.entries(r.evidence ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     if (evidence.length) {
       lines.push('- evidence:');
@@ -386,8 +346,7 @@ function renderMarkdown(json                    )         {
     }
     lines.push('');
   }
-  // Detector catalog: the version + threshold set that produced each finding,
-  // so the Markdown (the format pasted into a ticket) carries provenance too.
+  // Detector catalog: the version + threshold set that produced each finding, so the Markdown carries provenance too.
   if (Array.isArray(detectors) && detectors.length) {
     lines.push('## Detectors');
     lines.push('');
@@ -413,19 +372,14 @@ function renderMarkdown(json                    )         {
                    
  
 
-// CLI/MCP-facing filter over FindingRow (post-row-transformation), delegating
-// to the shared core predicate (src/finding-filter-predicate.ts) that also
-// backs the dashboard's src/view/finding-filter.ts.
+// CLI/MCP-facing filter over FindingRow, delegating to the shared core predicate that also backs
+// the dashboard's finding-filter.
 function matchesFindingsFilter(row            , filter                )          {
   return matchesFindingFilterCriteria(row, filter);
 }
 
-/**
- * Build a `FindingsFilter` from the three optional CLI/MCP filter dimensions,
- * or `undefined` when none were passed (the "is anything actually set" gate
- * both `bin/sparkforensics-analyze.mjs` and `diagnoseRun` need before calling
- * `buildEvidenceReport`).
- */
+/** Build a FindingsFilter from the three optional CLI/MCP filter dimensions, or undefined when
+ * none were passed (the "is anything set" gate before calling buildEvidenceReport). */
 export function toFindingsFilter(
   impactBand           , type           , stageId         ,
 )                             {
@@ -434,13 +388,10 @@ export function toFindingsFilter(
 
 /**
  * Build a portable evidence report from an appModel.
- * @param appModel
- * @param opts redact=true pseudonymizes app ids / hosts; markdown=false skips
- *   rendering the Markdown string (returned as '' instead) for callers that
- *   only need `json`; findingsFilter narrows `json.findings` (and the
- *   rendered Markdown's Findings section) only — `summary`, `recommendations`,
- *   and `cleanChecks` stay computed from the full, unfiltered set, so a
- *   narrow filter never hides that other checks passed or other fixes exist.
+ * @param opts redact=true pseudonymizes app ids / hosts; markdown=false skips the Markdown string;
+ *   findingsFilter narrows json.findings (and the Markdown Findings section) only, summary,
+ *   recommendations, and cleanChecks stay computed from the full set, so a narrow filter never
+ *   hides that other checks passed or other fixes exist.
  */
 export function buildEvidenceReport(
   appModel          ,
@@ -450,9 +401,8 @@ export function buildEvidenceReport(
 )                                                 {
   let json = buildJson(appModel);
   if (redact) json = redactReport(json);
-  // Filter after redact, not before: redaction only replaces string values
-  // on rows that survive (app id / host tokens), it never adds/removes rows,
-  // so the two orderings produce identical final content either way.
+  // Filter after redact, not before: redaction only replaces string values on surviving rows,
+  // never adds/removes rows, so the two orderings produce identical final content.
   if (findingsFilter) json = { ...json, findings: json.findings.filter((row) => matchesFindingsFilter(row, findingsFilter)) };
   const markdown = computeMarkdown ? renderMarkdown(json) : '';
   return { markdown, json };

package/vendor-core/export-data.js

@@ -0,0 +1,48 @@
+             
+                                                            
+                                                                                
+                    
+
+export const EXPORT_DATA_SCHEMA_VERSION = 1;
+
+                                
+                        
+                           
+                  
+              
+                      
+                                                                              
+                                      
+                                                    
+                     
+                            
+                       
+ 
+
+/** Converts an in-memory AppModel (Map-based, as collectRun()/the browser
+ * worker produce it) plus the CLI's already-computed catalog/configFindings
+ * into a plain, JSON-serializable object for the HTML export's data.js.
+ * Maps become arrays; main-export.tsx rebuilds them client-side keyed the
+ * same way the store already expects (Stage.id, Job.id,
+ * SqlExecution.id). Deliberately excludes raw per-task TaskData, which is far
+ * too large to inline; task-detail widgets degrade gracefully in export mode. */
+export function buildExportRunData(
+  appModel          ,
+  catalog           ,
+  configFindings           ,
+  skippedLines        ,
+)                {
+  return {
+    schemaVersion: EXPORT_DATA_SCHEMA_VERSION,
+    app: appModel.app,
+    stages: [...appModel.stages.values()],
+    jobs: [...appModel.jobs.values()],
+    sql: [...appModel.sql.values()],
+    executors: appModel.executors,
+    runAggregates: appModel.runAggregates,
+    evidenceAvailability: appModel.evidenceAvailability,
+    catalog,
+    configFindings,
+    skippedLines,
+  };
+}

package/vendor-core/finding-action-label.js

@@ -1,15 +1,9 @@
                                           
 
-/** A short, imperative action label for a finding's row (e.g. "Reduce
- * shuffle size"). Keyed off `finding.type` plus whichever discriminant field
- * that detector uses for its sub-variants (`rule`, `direction`, `variant`, or
- * `property`: there's no single field name shared across detectors; see
- * detectors.ts). Core-safe: no `src/view/**` import, so both the dashboard
- * (`src/view/finding-action-label.ts`, which layers the REGISTRY fallback on
- * top of this) and `src/evidence-report.ts` (CLI/MCP path, which cannot
- * import React-only code) share the exact same switch logic instead of
- * forking it. Returns `undefined` for any (type, variant) combination this
- * switch doesn't cover: the caller decides what to fall back to. */
+/** A short, imperative action label for a finding's row. Keyed off finding.type plus whichever
+ * discriminant field that detector uses (rule/direction/variant/property). Core-safe (no view
+ * import) so the dashboard's wrapper and evidence-report.ts share the same switch. Returns
+ * undefined for any combination this switch doesn't cover; the caller decides the fallback. */
 export function coreFindingActionLabel(finding         )                     {
   switch (finding.type) {
     case 'skew':

package/vendor-core/finding-filter-predicate.js

@@ -1,10 +1,6 @@
-// Core-owned finding-filter predicate, shared by the CLI/MCP evidence report
-// (src/evidence-report.ts's FindingsFilter) and the dashboard's finding
-// filter bar (src/view/finding-filter.ts's FilterSelection): same precedent
-// as src/finding-action-label.ts, whose view-layer counterpart wraps it
-// instead of reimplementing its switch. Each dimension is unconstrained when
-// empty/absent; a `stageId` criterion (single value or a set, for the
-// dashboard's multi-select) only matches a row whose own stageId is present.
+// Core-owned finding-filter predicate, shared by the CLI/MCP evidence report and the dashboard's
+// filter bar (its view counterpart wraps this instead of reimplementing). Each dimension is
+// unconstrained when empty; a stageId criterion only matches a row whose own stageId is present.
                                                    
 
 function isNonEmpty   (m                           )                     {

package/vendor-core/finding-generic-recommendation.js

@@ -0,0 +1,112 @@
+                                          
+
+/** A generic, type-level recommendation sentence for a finding: the shape of the fix, with no
+ * instance data (numbers, stage ids, host names, file counts, config values). Mirrors
+ * coreFindingActionLabel's (type, discriminant) switch (same fields: rule/direction/variant/
+ * property, plus cacheUtilization's variant and memoryUtilization's dataUnavailable), but covers
+ * every finding type, not just the ones with a distinct action label.
+ *
+ * Used for a multi-finding group's muted description line (TypeGroupRow in FixTheseFirst.tsx),
+ * where the highest-impact member's own `recommendation` (real numbers, one stage) would
+ * misrepresent a summed-impact trailing stat covering every member. Returns undefined where a
+ * detector's real branch key isn't exposed as a Finding field (spill's skew/volume
+ * classification, tinyTask's shuffle-vs-no-shuffle fix, duplicatePlanSubtree's isExchangeRoot),
+ * so those combine into one sentence covering both cases, or for any (type, discriminant)
+ * combination this switch doesn't recognize; the caller shows no muted line rather than guess. */
+export function coreFindingGenericRecommendation(finding         )                     {
+  switch (finding.type) {
+    case 'skew':
+      return 'For join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key to reduce task skew.';
+    case 'stageShape':
+      switch (finding.rule) {
+        case 'lowParallelism': return 'Too few tasks run relative to the cores available, leaving cluster capacity idle: repartition to use more of it.';
+        case 'dataExplosion': return 'Output volume far exceeds input volume: check for an exploding join or a cross product.';
+        case 'taskStageSkew': return 'A single straggler task gates the whole stage\'s wall-clock duration.';
+      }
+      break;
+    case 'shuffle':
+      return 'Consider increasing spark.sql.shuffle.partitions or adding a broadcast join to shrink the shuffle.';
+    case 'partitionSizing':
+      switch (finding.rule) {
+        case 'shufflePartitionSkew': return 'For join skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.';
+        case 'lowShuffleParallelism': return 'Raise spark.sql.shuffle.partitions so each partition is smaller.';
+        case 'maxPartitionTooBig': return 'Repartition to break up the oversized partition before this stage.';
+      }
+      break;
+    case 'spill':
+      return 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise raise spark.sql.shuffle.partitions or increase executor memory.';
+    case 'gc':
+      return finding.direction === 'low'
+        ? 'Memory may be over-provisioned here: consider reducing spark.executor.memory for cost savings.'
+        : 'Reduce object creation, use primitive types, avoid UDFs, or increase executor memory to cut GC time.';
+    case 'slowHost':
+      if (finding.variant === 'durationShare') return 'Check for data locality or partition assignment skewing work onto one node.';
+      if (finding.variant === 'multiDim') return 'Investigate uneven partition assignment or a degraded executor.';
+      return 'Check what this host was running: it may just hold data locality for its tasks or carry one heavy stage, rather than a hardware fault. Enable spark.speculation to relaunch a lagging task automatically.';
+    case 'stageSlowness':
+      return 'Often a partition-count problem: raise parallelism via spark.sql.shuffle.partitions or spark.default.parallelism, or check for a large per-task data volume driving heavy shuffle and spill.';
+    case 'stageFailed':
+      return 'Inspect the driver log for the failure reason and the job that triggered it.';
+    case 'failures':
+      return 'Investigate driver logs for executor instability or data-driven errors.';
+    case 'straggler':
+      return 'Rule out a GC pause or a slow shuffle fetch before assuming a hardware issue. If a skewed key is the real cause, that is a candidate for AQE\'s skew-join handling.';
+    case 'speculationWaste':
+      return 'If task durations are naturally variable rather than genuine stragglers, consider tuning spark.speculation.multiplier/quantile.';
+    case 'retryWaste':
+      return 'Investigate executor loss or fetch failures behind the retried attempts.';
+    case 'tinyTask':
+      return 'Scheduler overhead may dominate: lower spark.sql.shuffle.partitions, or coalesce down to fewer, larger tasks.';
+    case 'coldStart':
+      return 'Keep a warm pool of idle executors, or if using dynamic allocation, raise the minimum/initial executor count so it does not scale up from zero.';
+    case 'utilization':
+      return 'Consider reducing cluster size or enabling dynamic allocation.';
+    case 'memoryUtilization':
+      switch (finding.variant) {
+        case 'idleCores': return 'Reduce cluster size or enable dynamic allocation.';
+        case 'wasteModel': return 'Review spark.executor.memory and executor count.';
+        case 'memoryBand':
+          if (finding.dataUnavailable) break;
+          return finding.rule === 'heapNearCapacity'
+            ? 'Memory may be too small: raise spark.executor.memory to avoid OOM/spill.'
+            : 'Memory may be over-provisioned: consider reducing spark.executor.memory for cost savings.';
+      }
+      break;
+    case 'cacheUtilization':
+      switch (finding.variant) {
+        case 'partialCache': return 'Increase executor memory or reduce the cached dataset size so more of it stays cached.';
+        case 'diskSpillover': return 'Executor memory may be too small for this cached dataset: increase executor memory or reduce its size.';
+      }
+      break;
+    case 'coreLocality':
+      return 'Check spark.locality.wait settings and executor/data colocation.';
+    case 'autoscalingChurn':
+      return 'This looks like wasteful re-provisioning rather than normal scale-down: consider raising spark.dynamicAllocation.executorIdleTimeout or widening the minExecutors/maxExecutors bounds to reduce flapping.';
+    case 'cachingOpportunity':
+      return finding.variant === 'composite'
+        ? 'Cache or persist the repeated join/union result so it is computed once instead of recomputed per query.'
+        : 'Cache the shared DataFrame, or broadcast it if it is a small join lookup.';
+    case 'jobFailureRate':
+      return 'Inspect the driver log for the failed job(s) and the stage failures that triggered them.';
+    case 'configAudit':
+      switch (finding.property) {
+        case 'spark.shuffle.service.enabled': return 'Set spark.shuffle.service.enabled=true so shuffle data survives executor removal.';
+        case 'spark.dynamicAllocation.minExecutors': return 'Set the minimum executor bound at or below the maximum.';
+        case 'spark.dynamicAllocation.maxExecutors': return 'Set spark.dynamicAllocation.maxExecutors to cap cluster growth.';
+        case 'spark.serializer': return 'Consider spark.serializer=org.apache.spark.serializer.KryoSerializer for faster, smaller buffers.';
+        case 'spark.executor.memoryOverhead': return 'Raise executor memoryOverhead above Spark\'s default floor to avoid off-heap OOM-kills.';
+      }
+      break;
+    case 'duplicatePlanSubtree':
+      return 'Check whether the repeated subtree could be computed once and reused, or cache/persist the shared computation.';
+    case 'smallFiles':
+      return finding.direction === 'write'
+        ? 'Repartition or coalesce before writing to raise the average file size.'
+        : 'Compact the upstream output so fewer, larger files are produced.';
+    case 'underBroadcast':
+      return 'This could have been a broadcast join: consider a broadcast() hint or raising spark.sql.autoBroadcastJoinThreshold.';
+    case 'overBroadcast':
+      return 'Check for a misapplied broadcast hint or a misconfigured spark.sql.autoBroadcastJoinThreshold.';
+  }
+  return undefined;
+}

package/vendor-core/finding-names.js

@@ -0,0 +1,51 @@
+// Canonical detector `type` -> human-readable label (single source of truth). detector-registry
+// imports this (web uses it lowercase); evidence-report.ts Title Cases it for CLI/MCP names.
+//
+// broadcastSizing is the DETECTORS-level type but no real Finding carries it (the detector pushes
+// underBroadcast/overBroadcast). Kept as a dead key so the DETECTORS-type completeness check finds it.
+export const FINDING_NAMES                         = {
+  incompleteRun: 'incomplete run',
+
+  skew: 'task skew',
+  stageShape: 'stage shape',
+  tinyTask: 'tiny tasks',
+
+  shuffle: 'shuffle I/O',
+  partitionSizing: 'partition sizing',
+
+  spill: 'spill',
+
+  gc: 'GC pressure',
+
+  stageFailed: 'failed stage',
+  failures: 'failed tasks',
+  retryWaste: 'retry waste',
+
+  slowHost: 'slow executor host',
+  stageSlowness: 'slow stage',
+  straggler: 'straggling task',
+  speculationWaste: 'speculation waste',
+  coldStart: 'cold start',
+
+  memoryUtilization: 'memory utilization',
+  utilization: 'executor utilization',
+  coreLocality: 'core locality',
+  cachingOpportunity: 'caching opportunity',
+  cacheUtilization: 'cache utilization',
+  jobFailureRate: 'job failure rate',
+  autoscalingChurn: 'autoscaling churn',
+
+  configAudit: 'config audit',
+
+  duplicatePlanSubtree: 'duplicate plan subtree',
+  smallFiles: 'small files',
+  broadcastSizing: 'broadcast sizing',
+  underBroadcast: 'missed broadcast join',
+  overBroadcast: 'oversized broadcast join',
+};
+
+// Capitalizes the first letter of each word, leaving other characters untouched so acronyms
+// ('GC', 'I/O') survive.
+export function titleCase(label        )         {
+  return label.replace(/\b\w/g, (c) => c.toUpperCase());
+}