sparkforensics-mcp 0.3.0 → 0.4.0

package/vendor-core/run-comparison.js

@@ -2,8 +2,12 @@ import { computeWallClock } from './wall-clock.js';
 import { normalizeDetail } from './detectors.js';
 import { cyrb53 } from './string-hash.js';
 import { captureSnapshot } from './session-snapshot.js';
-                                                                                   
+import { tunedRunNote } from './threshold-overrides.js';
+                                                                                                    
                                                              
+                                                                                        
+import { isIncompleteRun } from './check-coverage.js';
+import { summarizeRunOutcome } from './run-outcome.js';
 
                                  
                              
@@ -12,7 +16,7 @@ import { captureSnapshot } from './session-snapshot.js';
                              
  
                                    
-                                                                                                          
+                                                                                                                        
  
                                     
                                                 
@@ -23,7 +27,16 @@ import { captureSnapshot } from './session-snapshot.js';
                                                                                                                                                   
                                                                             
                                                                             
+                                                                                            
+                                                                                               
+                                   
+                                                                             
  
+
+function jobOutcome(snapshot                 )                    {
+  const { failedJobs, totalJobs } = summarizeRunOutcome(snapshot.jobs, snapshot.catalog);
+  return { failedJobs, totalJobs, incomplete: isIncompleteRun(snapshot.catalog) };
+}
 
 // Replace run-varying tokens (digit runs, long hex ids) with a stable marker so
 // the same logical stage across two runs normalizes to one identity.
@@ -282,14 +295,14 @@ export function metricDeltas(baseSnap                 , candSnap
 export function findingsDelta(baseSnap                 , candSnap                 )   
                                                                
   {
-                                                                                                
+                                                                                                              
   const tally = (snap                 )                          => {
     const m = new Map                    (); // `${rule}§${impactBand}` -> { rule, impactBand, count, stages:Set }
     for (const f of snap.catalog) {
-      const rule = typeof f.rule === 'string' ? f.rule : f.type;
+      const rule = 'rule' in f && typeof f.rule === 'string' ? f.rule : f.type;
       const impactBand = f.impactBand ?? 'unknown';
       const key = `${rule}§${impactBand}`;
-      const e = m.get(key) ?? { rule, impactBand, count: 0, stages: new Set        () };
+      const e = m.get(key) ?? { rule, type: f.type, impactBand, count: 0, stages: new Set        () };
       e.count++;
       // Resolve stageId → name on this snapshot only: a single-side lookup, so
       // it needs no cross-run identity. App-level findings (stageId null) add none.
@@ -308,7 +321,7 @@ export function findingsDelta(baseSnap                 , candSnap
     if (candCount === baseCount) continue;
     const meta = ce ?? be ;
     const more = candCount > baseCount ? ce  : be ; // the side with more supplies the labels
-    const row                   = { rule: meta.rule, impactBand: meta.impactBand, baseCount, candCount,
+    const row                   = { rule: meta.rule, type: meta.type, impactBand: meta.impactBand, baseCount, candCount,
       delta: candCount - baseCount, stages: [...more.stages].sort() };
     (candCount > baseCount ? introduced : resolved).push(row);
   }
@@ -428,6 +441,7 @@ export function compareRuns(
     stageSkew: stageSkewDeltas(baseSnap, candSnap, match),
     baseStages: stageList(baseSnap),
     candStages: stageList(candSnap),
+    jobOutcomes: { baseline: jobOutcome(baseSnap), candidate: jobOutcome(candSnap) },
   };
 }
 
@@ -445,8 +459,19 @@ function renderFindingsSection(title        , findings                    )
 // evidence-report.ts's renderMarkdown house style (## section heading, ###
 // subheadings, `- key: value` bullets). Shared by the CLI's --baseline
 // markdown output and the MCP server's compare_runs `format: 'md'`.
-export function renderComparisonMarkdown(comparison                   )         {
+/** `tuned`: tunedDetectors() for the overrides both runs were analyzed with, named in the output
+ * as the evidence report names them. */
+export function renderComparisonMarkdown(
+  comparison                   , verdict                        , tuned                                         ,
+)         {
   const lines = ['', '## Comparison to baseline', ''];
+  if (tuned) lines.push(`- Tuned thresholds (both runs): ${tunedRunNote(tuned)}`, '');
+  if (verdict) {
+    // The dashboard comparison page's headline: run A is the baseline, run B the candidate.
+    lines.push(`Run A: ${comparison.baselineLabel} · Run B: ${comparison.candidateLabel}`, '', verdict.title);
+    if (verdict.sentences.length > 0) lines.push('', verdict.sentences.join(' '));
+    lines.push('');
+  }
   if (comparison.confidence === 'low') {
     lines.push(`- confidence: low, ${comparison.reason}`);
     lines.push('');

package/vendor-core/run-interpretation.js

@@ -0,0 +1,290 @@
+// The interpretation layer of a run as plain data: the verdict, which checks could not run and
+// why, every finding's formatted savings, and the run-shape figures. Everything here can change
+// the conclusion about a run, so it is computed once, by the core that ran the detectors, and
+// handed to the renderer as data. The live dashboard (useIngest) and both HTML-export producers
+// (html-export.ts) call `interpretRun`; the exported bundle only renders what it carries, so an
+// exported file shows the conclusions of the core that wrote it, not of the core that opens it.
+import { checkCoverage, hasFinishedStage, verdictGaps } from './check-coverage.js';
+import { computeCoreLocalityRatio } from './core-locality-ratio.js';
+import { buildLocalityChart,                    } from './core-usage-locality.js';
+import { detectorInfoByType,                   } from './detector-docs.js';
+import { computeEfficiencyModel } from './efficiency-model.js';
+import { attributeEtlPhases } from './etl-phases.js';
+import { IMPACT_BAND_ORDER, worstImpactBand } from './format-utils.js';
+import {
+  estimateProvenance, impactEstimateCompact, impactEstimateFigure, impactFigure, savingsMeaning,
+} from './impact-format.js';
+import { isEligible, rankedRollup,                        } from './recommendation-rollup.js';
+import { quotesReasonOf } from './run-outcome.js';
+import { computeRunShape,               } from './run-shape.js';
+import {
+  buildNextSteps, buildRunVerdict, FINDING_DISPLAY_ORDER, locationKey, quotedReasonText, rankBySavings, stepCopyText,
+} from './run-verdict.js';
+import { recommendationText } from './finding-names.js';
+import { getScorecardEstimates } from './scorecard-estimates.js';
+import { checkConcurrentJobGroups } from './job-groups.js';
+import { computeWallClock } from './wall-clock.js';
+import { computeWastedCoreHours,                            } from './wasted-core-hours.js';
+                                                    
+
+/** A finding's savings figures, formatted with their units, so a widget shows the figure
+ * without formatting it. */
+                                 
+                                                                                               
+                                                        
+                        
+                                                              
+                         
+                                                                                                  
+                       
+                                            
+                         
+                                                                            
+                            
+ 
+
+/** One verdict step, fully worded. `leadIndex` names the finding the step routes to. */
+                                  
+              
+                    
+                         
+                                                              
+                         
+                                                                                      
+                                 
+                         
+                                    
+                   
+ 
+
+                                 
+                
+                    
+                  
+                 
+                                                          
+                               
+                           
+                                                           
+                    
+                                                               
+                          
+ 
+
+                               
+                            
+                                                                                          
+                                        
+                                                                                          
+                 
+ 
+
+                                                          
+
+/** The Scorecard's three headline figures (the ones the report's runShape also states) and how
+ * each is graded. `wallClockMs` is null without a complete application timing interval. */
+                                                                                                             
+                                
+                                    
+                                                                                                            
+ 
+
+                                                                
+
+                                                                       
+
+                                                                  
+
+                                   
+                                          
+                       
+                                                                           
+                                                     
+ 
+
+/** A stage's findings as the stage dialog lists them, in the verdict's step order. */
+                                    
+                           
+                                                                                              
+                      
+ 
+
+/** One row group of the Findings board: a finding type (split by impact kind, and by unit for
+ * resource figures), its members representative first, the band it sits under, and its trailing
+ * figure. */
+                                                                             
+                                       
+                          
+ 
+
+/** The unfiltered Findings board: which findings it lists and its groups in fix-first order. */
+                             
+                            
+                            
+ 
+
+/** Findings are referred to by index into the run's findings in catalog-then-config order
+ * (`[...catalog, ...configFindings]`), the order both producers pass them in: no copies, so a
+ * renderer resolves them to the very objects it already holds. */
+                                    
+                                                                
+                            
+                          
+                         
+                         
+                                                                                           
+                           
+                                       
+                                         
+                                                                                    
+                                    
+                                                                                            
+                             
+                                        
+                           
+                                 
+                                                                              
+                                          
+                                                                      
+                        
+                                                                 
+                                            
+                     
+ 
+
+export function findingSavings(finding         )                 {
+  return {
+    figure: impactFigure(finding),
+    meaning: savingsMeaning(finding),
+    board: impactEstimateFigure(finding.impactEstimate)?.text ?? null,
+    compact: impactEstimateCompact(finding.impactEstimate),
+    provenance: estimateProvenance(finding),
+  };
+}
+
+// The Scorecard's severity rule: a tile is flagged only when the figure is bad enough to act on.
+function efficiencyFlag(pct               )                {
+  if (pct == null) return null;
+  return pct < 75 ? 'critical' : pct < 90 ? 'warning' : null;
+}
+
+function unusedCoreTimeFlag(pct               )                {
+  if (pct == null) return null;
+  return pct >= 70 ? 'critical' : pct >= 40 ? 'warning' : null;
+}
+
+function interpretRunShape(appModel          )               {
+  const { wallClockMs, efficiencyPct, unusedCoreTimePct } = computeRunShape(appModel);
+  const estimates = getScorecardEstimates(appModel);
+  return {
+    wallClockMs,
+    efficiencyPct,
+    unusedCoreTimePct,
+    efficiencyFlag: efficiencyFlag(efficiencyPct),
+    unusedCoreTimeFlag: unusedCoreTimeFlag(unusedCoreTimePct),
+    unusedCoreTimeUnavailableReason: estimates.wastage.unavailableReason,
+  };
+}
+
+function interpretEfficiency(appModel          )                        {
+  if (!appModel.runAggregates) return null;
+  return computeEfficiencyModel({
+    app: appModel.app,
+    stages: appModel.stages,
+    executorsAdded: appModel.executors.added,
+    runAggregates: appModel.runAggregates,
+  });
+}
+
+function interpretCoverage(appModel          , allFindings           )               {
+  const noFinishedStages = !hasFinishedStage(appModel.stages);
+  const { notRunReason } = checkCoverage(appModel.stages, allFindings);
+  const notRunReasons                         = {};
+  for (const type of FINDING_DISPLAY_ORDER) {
+    const reason = notRunReason(type);
+    if (reason != null) notRunReasons[type] = reason;
+  }
+  return { noFinishedStages, notRunReasons, gaps: verdictGaps(allFindings, noFinishedStages) };
+}
+
+// The stage dialog's grouping: the verdict's location rule (a sql-scope finding touching only
+// this stage counts), ordered by the stage's own verdict step, then by worst band.
+function interpretStages(
+  catalog           , indexOf                      , failedJobStageIds                            ,
+)                                    {
+  const byStage = new Map                   ();
+  for (const finding of catalog) {
+    const { stageId } = locationKey(finding);
+    if (stageId == null) continue;
+    const list = byStage.get(stageId) ?? [];
+    list.push(finding);
+    byStage.set(stageId, list);
+  }
+  const stages                                    = {};
+  for (const [stageId, findings] of byStage) {
+    const [step] = buildNextSteps(findings, failedJobStageIds ? { failedJobStageIds } : {});
+    const stepTypes = step ? [step.lead.type, ...step.related.map((f) => f.type)] : [];
+    const worstBand = (type        ) => IMPACT_BAND_ORDER[worstImpactBand(findings.filter((f) => f.type === type)) ];
+    const otherTypes = [...new Set(findings.map((f) => f.type))]
+      .filter((type) => !stepTypes.includes(type))
+      .sort((a, b) => worstBand(a) - worstBand(b));
+    stages[String(stageId)] = { findingIndexes: findings.map((f) => indexOf.get(f) ), typeOrder: [...stepTypes, ...otherTypes] };
+  }
+  return stages;
+}
+
+const DISPLAY_TYPES                      = new Set(FINDING_DISPLAY_ORDER);
+
+/** Every conclusion the dashboard shows about a run whose detectors already ran. */
+export function interpretRun(appModel          , catalog           , configFindings           )                    {
+  const allFindings = [...catalog, ...configFindings];
+  const indexOf = new Map(allFindings.map((finding, index) => [finding, index]));
+  const verdict = buildRunVerdict(appModel, allFindings);
+  const { outcome } = verdict;
+  const failed = outcome.failedJobs > 0;
+  // A board row needs a widget to route to, and every display type has one.
+  const eligible = allFindings.filter((finding) => isEligible(finding) && DISPLAY_TYPES.has(finding.type));
+  const steps                    = verdict.shown.map((step) => {
+    const quoted = quotesReasonOf(step.lead, outcome) && outcome.reason ? quotedReasonText(outcome.reason) : null;
+    return {
+      key: step.key,
+      leadIndex: indexOf.get(step.lead) ,
+      stageId: step.stageId,
+      relatedTypes: step.related.map((f) => f.type),
+      recommendation: quoted?.shown ?? recommendationText(step.lead),
+      copyText: stepCopyText(step.lead, quoted?.copied ?? recommendationText(step.lead)),
+    };
+  });
+  return {
+    savings: allFindings.map(findingSavings),
+    verdict: {
+      title: verdict.title,
+      summary: verdict.summary,
+      failed,
+      clean: verdict.facts.clean,
+      failureReason: outcome.reason,
+      steps,
+      remaining: verdict.remaining,
+      copyText: verdict.copyText,
+    },
+    coverage: interpretCoverage(appModel, allFindings),
+    runShape: interpretRunShape(appModel),
+    wallClock: computeWallClock(appModel.app, appModel.stages),
+    wastedCoreHours: computeWastedCoreHours(appModel.app, appModel.executors.added, appModel.runAggregates),
+    efficiency: interpretEfficiency(appModel),
+    wallClockReliable: checkConcurrentJobGroups(appModel.jobs).wallClockReliable,
+    etlPhases: attributeEtlPhases(appModel.stages),
+    coreLocality: {
+      chart: buildLocalityChart([...appModel.stages.values()], appModel.app),
+      ratio: computeCoreLocalityRatio([...appModel.stages.values()], { topN: Infinity }),
+    },
+    detectors: detectorInfoByType(),
+    savingsRank: rankBySavings(allFindings).map((finding) => indexOf.get(finding) ),
+    stages: interpretStages(catalog, indexOf, failed ? outcome.failedJobStageIds : null),
+    rollup: {
+      eligibleIndexes: eligible.map((finding) => indexOf.get(finding) ),
+      groups: rankedRollup(eligible, appModel.stages)
+        .map(({ members, ...group }) => ({ ...group, memberIndexes: members.map((finding) => indexOf.get(finding) ) })),
+    },
+  };
+}

package/vendor-core/run-outcome.js

@@ -0,0 +1,74 @@
+                                                          
+
+/** Finding types that mean work did not finish: a stage attempt that failed
+ * outright, and jobs that ended without succeeding. Failed tasks that a retry
+ * recovered (`failures`) are not in this set: the run still completed. */
+export const FAILURE_TYPES                      = new Set(['stageFailed', 'jobFailureRate']);
+
+/** Longest failure reason the verdict quotes; Spark reasons can carry a whole
+ * stack trace, and the first line already names the cause. */
+export const FAILURE_REASON_MAX_CHARS = 240;
+
+/** How the run ended, as far as its jobs say. `failedJobs` and `totalJobs`
+ * count only jobs with an end record, so a job still running when an
+ * incomplete log stops is neither. */
+                             
+                     
+                    
+                                                                          
+                                         
+                                                                           
+                                  
+                        
+                                                                            
+                                                
+                               
+ 
+
+function firstLine(text        )                {
+  const line = text.split('\n')[0].trim();
+  if (line.length === 0) return null;
+  return line.length > FAILURE_REASON_MAX_CHARS ? `${line.slice(0, FAILURE_REASON_MAX_CHARS - 3).trimEnd()}...` : line;
+}
+
+function exceptionText(exception         )                {
+  if (typeof exception === 'string') return exception;
+  return null;
+}
+
+/** Summarizes the run's job results. The reason prefers a failed stage that
+ * belongs to a failed job (the stage is the nearer cause), then any failed
+ * stage, then the first failed job's exception message. */
+export function summarizeRunOutcome(jobs                  , findings           )             {
+  const ended = [...jobs.values()].filter((job) => job.result != null);
+  const failed = ended.filter((job) => job.succeeded === false).sort((a, b) => a.id - b.id);
+  const failedStageIds = new Set(failed.flatMap((job) => job.stageIds));
+  const stageReasons = findings
+    .filter((finding)                                      => finding.type === 'stageFailed')
+    .sort((a, b) => Number(failedStageIds.has(b.stageId          )) - Number(failedStageIds.has(a.stageId          )));
+  const stageSource = stageReasons[0];
+  const rawReason =
+    stageSource?.valueText
+    ?? failed.map((job) => exceptionText(job.exception)).find((text) => text != null)
+    ?? null;
+  return {
+    failedJobs: failed.length,
+    totalJobs: ended.length,
+    failedJobStageIds: failedStageIds,
+    reason: failed.length > 0 && rawReason != null ? firstLine(rawReason) : null,
+    reasonStageId: stageSource?.stageId ?? null,
+  };
+}
+
+/** Whether the quoted reason is this finding's own: the stage failure whose
+ * first line it is, or the job-failure finding when exactly one job failed
+ * and the reason belongs to that job. Any other failure has a cause the
+ * verdict does not show. */
+export function quotesReasonOf(finding         , outcome            )          {
+  if (outcome.reason == null) return false;
+  if (finding.type === 'stageFailed') return firstLine(finding.valueText) === outcome.reason;
+  if (finding.type === 'jobFailureRate') {
+    return outcome.failedJobs === 1 && (outcome.reasonStageId == null || outcome.failedJobStageIds.has(outcome.reasonStageId));
+  }
+  return false;
+}

package/vendor-core/run-payload.js

@@ -0,0 +1,17 @@
+// How an encoded HTML-export payload reaches the export app: a window global
+// that data.js (or the inlined script) assigns and main-export.tsx reads.
+// Dependency-free, so the export bundle can read the global without pulling in
+// the producer side (html-export.ts and the analysis it runs).
+
+/** The window global the payload statement assigns and the export app reads. */
+export const RUN_PAYLOAD_GLOBAL = '__SPARKFORENSICS_RUN_GZ__';
+
+/** The one JavaScript statement that hands an encoded payload to the export
+ * app. base64's alphabet (A-Za-z0-9+/=) can't contain "<" or a quote, so log
+ * free text can't inject a "</script>" break-out or end the string literal:
+ * the statement is safe to place inside an inline <script> with no escaping.
+ * That only holds while `base64` really is base64; keep any new encoding
+ * inside that alphabet or escape it here. */
+export function runPayloadScript(base64        )         {
+  return `window.${RUN_PAYLOAD_GLOBAL} = "${base64}";`;
+}

package/vendor-core/run-shape.js

@@ -0,0 +1,40 @@
+// The run's shape as the dashboard's Scorecard, ETL Phase Attribution and Core Usage by Locality
+// cards show it, for the CLI/MCP paths: every figure comes from the same core function those cards
+// read, and null means the card would show "Not measured" or "Unavailable".
+import { hasFinishedStage } from './check-coverage.js';
+import { buildLocalityChart } from './core-usage-locality.js';
+import { attributeEtlPhases } from './etl-phases.js';
+import { getScorecardEstimates, hasCompleteApplicationInterval } from './scorecard-estimates.js';
+import { computeWallClock } from './wall-clock.js';
+                                           
+
+                           
+                                                                                      
+                             
+                                                                                              
+                                                      
+                               
+                                                                                               
+                                                                                          
+                                   
+                                                                                               
+                                                
+                                                                           
+                                                                                           
+                       
+                               
+ 
+
+export function computeRunShape(appModel          )           {
+  const timed = hasCompleteApplicationInterval(appModel.app);
+  const estimates = getScorecardEstimates(appModel);
+  const phases = attributeEtlPhases(appModel.stages);
+  const chart = buildLocalityChart([...appModel.stages.values()], appModel.app);
+  return {
+    wallClockMs: timed ? computeWallClock(appModel.app, appModel.stages).total : null,
+    efficiencyPct: hasFinishedStage(appModel.stages) ? estimates.efficiency.value : null,
+    unusedCoreTimePct: estimates.wastage.value,
+    etlPhasesMs: phases.extract + phases.transform + phases.load > 0 ? phases : null,
+    peakBusyCores: chart.hasActivity ? chart.peakCores : null,
+  };
+}