sparkforensics-server 0.3.0 → 0.5.0

package/vendor-core/core-usage-locality.js

@@ -18,6 +18,8 @@ export const LOCALITY_TIERS           = ['PROCESS_LOCAL', 'NODE_LOCAL', 'RACK_LO
                                     
                    
                                    
+                                                                                                 
+                  
  
 
 export function computeLocalityAreaSeries(
@@ -25,7 +27,7 @@ export function computeLocalityAreaSeries(
   { bucketWidthMs = 60_000, tiers = LOCALITY_TIERS }                            = {},
 )                           {
   const valid = stages.filter(s => (s.completedAt ?? 0) > (s.submittedAt ?? 0) && (s.executorRunTime ?? 0) > 0);
-  if (valid.length === 0) return { labels: [], series: {} };
+  if (valid.length === 0) return { labels: [], series: {}, endTime: 0 };
   const startTime = valid.reduce((m, s) => Math.min(m, s.submittedAt ?? m), Infinity);
   const endTime = valid.reduce((m, s) => Math.max(m, s.completedAt ?? m), -Infinity);
   const nBuckets = Math.max(1, Math.ceil((endTime - startTime) / bucketWidthMs));
@@ -65,5 +67,57 @@ export function computeLocalityAreaSeries(
 
   const labels           = [];
   for (let b = 0; b < nBuckets; b++) labels.push(startTime + b * bucketWidthMs);
-  return { labels, series };
+  return { labels, series, endTime };
 }
+
+/** How many time buckets the Core Usage by Locality chart aims for across a run. */
+export const LOCALITY_CHART_TARGET_BUCKETS = 60;
+
+                                     
+                                
+            
+                         
+ 
+
+                           
+                          
+                                                                                            
+
+/** The Core Usage by Locality chart's points and its "busy at the peak" figure, shared by the
+ * dashboard widget and the CLI/MCP run summary. Buckets are at least a minute wide; a last bucket
+ * the stages only partly cover is rescaled to the covered part, and each bucket's idle cores are
+ * the peak minus its busy cores. */
+export function buildLocalityChart(
+  stages                 ,
+  app                                                               ,
+  targetBuckets         = LOCALITY_CHART_TARGET_BUCKETS,
+)                {
+  const hasActivity = stages.some((s) => (s.executorRunTime ?? 0) > 0 && (s.completedAt ?? 0) > (s.submittedAt ?? 0));
+  if (!hasActivity) return { hasActivity: false };
+
+  const start = app?.startTime ?? 0;
+  const end = app?.endTime ?? start;
+  const bucketWidthMs = Math.max(60_000, Math.ceil(Math.max(1, end - start) / targetBuckets));
+  const { labels, series, endTime: seriesEnd } = computeLocalityAreaSeries(stages, { bucketWidthMs });
+  const order = [...LOCALITY_TIERS.filter((t) => series[t]), ...(series.OTHER ? ['OTHER'] : []), 'idle'];
+
+  const points                       = labels.map((t, i) => {
+    const point                     = { t: Math.round((t - start) / 1000) };
+    // The series averages each bucket over its full width, so a last bucket
+    // that runs past the series' own end (or a run shorter than one bucket)
+    // reads diluted: a 10s stage in a 60s bucket showed well under its busy
+    // cores. Rescale to the part of the bucket the series actually covers.
+    const coveredMs = Math.min(bucketWidthMs, seriesEnd - t);
+    const scale = bucketWidthMs / coveredMs;
+    for (const tier of order) if (tier !== 'idle') point[tier] = (series[tier]?.[i] ?? 0) * scale;
+    return point;
+  });
+  const busyTiers = order.filter((t) => t !== 'idle');
+  const busyTotal = (p                    ) => busyTiers.reduce((sum, t) => sum + p[t], 0);
+  const peakCores = points.reduce((max, p) => Math.max(max, busyTotal(p)), 0);
+  // Same rule as the core series (peak busy minus each bucket's busy), redone
+  // on the rescaled values so the stack still tops out at the peak.
+  for (const p of points) p.idle = Math.max(0, peakCores - busyTotal(p));
+  return { hasActivity: true, order, points, peakCores };
+}
+

package/vendor-core/detector-docs.js

@@ -0,0 +1,58 @@
+// Type-level doc anchors, read off the detector catalog. Kept out of docs-config.ts so the docs
+// URL helpers (used by every renderer) don't pull in the detectors themselves.
+import { DETECTORS, ENTRY_BY_TYPE } from './detectors.js';
+import { isKnownDocAnchor } from './docs-config.js';
+import { getThresholdSummary } from './threshold-summary.js';
+                                               
+
+// DETECTORS is static, so this grouping is built once (lazily) instead of re-scanning per
+// docAnchorForType call (called once per TagBadge per render). Keyed by emitted finding type, so
+// broadcastSizing's anchor lands on underBroadcast/overBroadcast.
+let anchorsByTypeCache                                                  ;
+
+function anchorsByType()                                       {
+  if (!anchorsByTypeCache) {
+    anchorsByTypeCache = new Map();
+    for (const entry of DETECTORS                       ) {
+      for (const type of entry.emits) {
+        const anchors = anchorsByTypeCache.get(type) ?? new Set();
+        anchors.add(entry.docAnchor);
+        anchorsByTypeCache.set(type, anchors);
+      }
+    }
+  }
+  return anchorsByTypeCache;
+}
+
+/** Resolves a finding `type` to its documented anchor from the DETECTORS entries that emit it.
+ * Returns undefined when entries sharing the type disagree on docAnchor (only configAudit today),
+ * or when the resolved anchor isn't in the allowlist (isKnownDocAnchor, the same gate DocsLink uses). */
+export function docAnchorForType(type        )                     {
+  const anchors = anchorsByType().get(type) ?? new Set();
+  if (anchors.size !== 1) return undefined;
+  const [anchor] = anchors;
+  return anchor && isKnownDocAnchor(anchor) ? anchor : undefined;
+}
+
+/** What a renderer shows about one finding type without running its detector. */
+                               
+                                                       
+                
+                                                                              
+                           
+                                                          
+                           
+                                                                                             
+                           
+ 
+
+/** Every emitted finding type's `DetectorInfo`, in `DETECTORS` declaration order of each entry's
+ * `emits` list (a type repeated across entries takes its first position, as `ENTRY_BY_TYPE` does).
+ * The key order is the widget order's tie-break, so it is part of the result. */
+export function detectorInfoByType()                               {
+  const info                               = {};
+  for (const [type, { order, scope }] of ENTRY_BY_TYPE) {
+    info[type] = { order, docAnchor: docAnchorForType(type) ?? null, thresholdSummary: getThresholdSummary(type), scope };
+  }
+  return info;
+}