sparkforensics-cli 0.1.0

package/vendor-core/evidence-report.js

@@ -0,0 +1,459 @@
+// 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 }.
+import { analyze, auditConfig } from './analyzer.js';
+import { detectorCatalog } from './detectors.js';
+import { typeTag, formatBytes, formatDuration, IMPACT_BAND_ORDER } from './format-utils.js';
+import { redactReport } from './redact.js';
+import { coreFindingActionLabel } from './finding-action-label.js';
+import { matchesFindingFilterCriteria } from './finding-filter-predicate.js';
+import { buildRecommendationRollup, isEligible, rankFindings,                  } from './recommendation-rollup.js';
+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.
+//
+// `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.
+                             
+                                                                                        
+                                                                                                                 
+                                                             
+                                                                                   
+                                                                              
+                                                                          
+                                                                            
+                                     
+                      
+                                                                       
+                                  
+ 
+
+// 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.
+                                    
+               
+              
+                                      
+                      
+                       
+                       
+                      
+                             
+                      
+                 
+                                                     
+                        
+ 
+
+// 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.
+                                  
+               
+              
+                           
+ 
+
+                                     
+                        
+            
+                                                                                    
+                                                                                          
+                                                                          
+    
+                                                    
+                     
+                         
+                                       
+                                 
+ 
+
+// 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',
+  'recommendation', 'detectorVersion', 'confidence', 'validationRequired', 'docAnchor', 'impactEstimate',
+  'actionLabel',
+]);
+
+function findingRow(f         )             {
+  const evidence                          = {};
+  for (const k of Object.keys(f).sort()) {
+    if (!CORE_KEYS.has(k)) evidence[k] = (f                           )[k];
+  }
+  const row             = {
+    id: f.id ?? null,
+    type: f.type,
+    tag: typeTag(f.type),
+    impactBand: f.impactBand,
+    stageId: f.stageId ?? null,
+    metric: f.metric ?? null,
+    value: f.value ?? null,
+    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.
+    actionLabel: coreFindingActionLabel(f) ?? f.type,
+  };
+  // Threshold/confidence provenance, only when the detector emitted it.
+  if (f.confidence != null) row.confidence = f.confidence;
+  if (f.validationRequired != null) row.validationRequired = f.validationRequired;
+  if (f.docAnchor != null) row.docAnchor = f.docAnchor;
+  if (f.impactEstimate != null) row.impactEstimate = f.impactEstimate;
+  return row;
+}
+
+// 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);
+    if (s !== 0) return s;
+    if (a.type !== b.type) return a.type < b.type ? -1 : 1;
+    const sa = a.stageId ?? -1;
+    const sb = b.stageId ?? -1;
+    if (sa !== sb) return sa - sb;
+    return (a.id ?? '') < (b.id ?? '') ? -1 : (a.id ?? '') > (b.id ?? '') ? 1 : 0;
+  });
+}
+
+// `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.
+
+// 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.
+function buildRecommendations(
+  findings           ,
+  stages                                                             ,
+)                      {
+  const eligible = findings.filter(isEligible);
+  const groups = buildRecommendationRollup(eligible, stages);
+  return groups.map((group             )                    => {
+    const ranked = rankFindings(group.findings);
+    const representative = ranked[0];
+    const findingIds = ranked.map((f) => f.id).filter((id)               => id != null);
+    const base = {
+      type: group.type,
+      tag: typeTag(group.type),
+      actionLabel: coreFindingActionLabel(representative) ?? representative.type,
+      findingCount: group.findingCount,
+      findingIds,
+    };
+    if (group.kind === 'time') {
+      return {
+        ...base,
+        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.
+        impact: formatWallClockRange(group.recoverableMsHigh, group.recoverableMsHigh),
+      };
+    }
+    if (group.kind === 'resource') {
+      return {
+        ...base,
+        kind: 'resource',
+        unit: group.unit,
+        total: group.total,
+        impact: formatRawWaste({ value: group.total, unit: group.unit }),
+      };
+    }
+    return {
+      ...base,
+      kind: 'count',
+      byImpactBand: group.byImpactBand,
+      // No single quantifiable figure for a count group; the impact-band tally
+      // (byImpactBand above) is the payload instead.
+      impact: null,
+    };
+  });
+}
+
+// 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.
+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.
+  for (const d of detectorCatalog()                           ) {
+    if (firedTypes.has(d.type) || seen.has(d.type)) continue;
+    seen.add(d.type);
+    entries.push({ type: d.type, tag: typeTag(d.type), thresholdSummary: getThresholdSummary(d.type) });
+  }
+  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.
+const jsonCache = new WeakMap                              ();
+
+function buildJson(appModel          )                     {
+  const cached = jsonCache.get(appModel);
+  if (cached) return cached;
+  const { app, stages, executors, sql, jobs, runAggregates, evidenceAvailability } = appModel;
+  const catalog = analyze(
+    app, stages, executors?.added ?? [], executors?.removed ?? [],
+    jobs ?? new Map(), sql ?? new Map(),
+    runAggregates ?? null,
+  );
+  const config = auditConfig(app);
+  const allFindings = [...catalog, ...config];
+  const rows = sortFindings(allFindings.map(findingRow));
+  const recommendations = buildRecommendations(allFindings, stages ?? new Map());
+  const cleanChecks = buildCleanChecks(allFindings);
+
+  const impactBandCounts = { critical: 0, warning: 0, info: 0 };
+  for (const r of rows) if (r.impactBand in impactBandCounts) impactBandCounts[r.impactBand] += 1;
+
+  const result                     = {
+    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.
+        id: app?.id ?? null,
+        name: app?.name ?? null,
+        sparkVersion: app?.sparkVersion ?? null,
+      },
+      stageCount: stages?.size ?? 0,
+      jobCount: jobs?.size ?? 0,
+      sqlExecutionCount: sql?.size ?? 0,
+      findingCount: rows.length,
+      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.
+    detectors: detectorCatalog(),
+    findings: rows,
+    recommendations,
+    cleanChecks,
+  };
+  jsonCache.set(appModel, result);
+  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.
+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);
+  return String(value);
+}
+
+function formatWallClockRange(low        , high        )         {
+  const fmtMs = (ms        ) => (ms === 0 ? '0s' : formatDuration(ms));
+  return low === high ? `Est. ${fmtMs(high)}` : `Est. ${fmtMs(low)}-${fmtMs(high)}`;
+}
+
+function formatRawWaste(rawWaste                )         {
+  const rounded = Math.round(rawWaste.value * 10) / 10;
+  switch (rawWaste.unit) {
+    case 'bytes': return formatBytes(rawWaste.value);
+    case 'ms': return formatDuration(rawWaste.value);
+    case 'mbSeconds': return `${rounded} MB-s`;
+    case 'coreHours': return `${rounded.toFixed(1)} core-h`;
+    case 'coreMs': return `${rounded} core-ms`;
+    default: return String(rawWaste.value);
+  }
+}
+
+// `basis: 'informational'` findings carry no wallClock/rawWaste at all, so
+// there's nothing quantifiable to print; the caller skips the line entirely.
+function renderImpactEstimate(estimate                )                {
+  const rangeText = estimate.wallClock ? formatWallClockRange(estimate.wallClock.low, estimate.wallClock.high) : null;
+  const wasteText = estimate.rawWaste ? formatRawWaste(estimate.rawWaste) : null;
+  if (!rangeText && !wasteText) return null;
+  const parts = [rangeText, wasteText].filter((p)              => p != null).join(' · ');
+  return `${parts} (estimateMethod: ${estimate.estimateMethod})`;
+}
+
+function renderMarkdown(json                    )         {
+  const { summary, findings, evidenceAvailability, detectors, recommendations, cleanChecks } = json;
+  const lines           = [];
+  lines.push('# Spark run evidence report');
+  lines.push('');
+  lines.push(`- Application: ${summary.app.name ?? '(unknown)'} (${summary.app.id ?? 'n/a'})`);
+  lines.push(`- Spark version: ${summary.app.sparkVersion ?? 'n/a'}`);
+  lines.push(`- Stages: ${summary.stageCount} · Jobs: ${summary.jobCount} · SQL executions: ${summary.sqlExecutionCount}`);
+  lines.push(`- Findings: ${summary.findingCount} (critical ${summary.impactBandCounts.critical}, warning ${summary.impactBandCounts.warning}, info ${summary.impactBandCounts.info})`);
+  lines.push('');
+  if (recommendations.length > 0) {
+    lines.push(`## Fix these first (${recommendations.length})`);
+    lines.push('');
+    recommendations.forEach((r, i) => {
+      lines.push(`${i + 1}. [${r.tag}] ${r.actionLabel}`);
+      const detail = r.kind === 'count'
+        ? Object.entries(r.byImpactBand ?? {}).map(([impactBand, count]) => `${count} ${impactBand}`).join(', ')
+        : r.impact;
+      lines.push(`   - ${detail} · ×${r.findingCount} finding(s)`);
+    });
+    lines.push('');
+  }
+  lines.push(`## Findings (${findings.length})`);
+  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(`- action: ${r.actionLabel}`);
+    if (r.metric != null) lines.push(`- ${r.metric}: ${r.value}`);
+    if (r.recommendation) lines.push(`- ${r.recommendation}`);
+    if (r.confidence) lines.push(`- confidence: ${r.confidence}`);
+    if (r.validationRequired) lines.push(`- validation: ${r.validationRequired}`);
+    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.
+    const evidence = Object.entries(r.evidence ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    if (evidence.length) {
+      lines.push('- evidence:');
+      for (const [k, v] of evidence) lines.push(`  - ${k}: ${renderEvidenceValue(k, v)}`);
+    }
+    lines.push('');
+  }
+  if (evidenceAvailability?.entries?.length) {
+    lines.push('## Evidence availability');
+    lines.push('');
+    for (const e of evidenceAvailability.entries) {
+      lines.push(`- ${e.key}: ${e.state} (${e.summary})`);
+    }
+    lines.push('');
+  }
+  // Detector catalog: the version + threshold set that produced each finding,
+  // so the Markdown (the format pasted into a ticket) carries provenance too.
+  if (Array.isArray(detectors) && detectors.length) {
+    lines.push('## Detectors');
+    lines.push('');
+    for (const d of detectors) {
+      lines.push(`- ${d.type} (v${d.version}, ${d.scope}), thresholds: ${JSON.stringify(d.thresholds)}`);
+    }
+    lines.push('');
+  }
+  if (cleanChecks.length > 0) {
+    lines.push(`## Clean checks (${cleanChecks.length})`);
+    lines.push('');
+    for (const c of cleanChecks) {
+      lines.push(`- [${c.tag}] ${c.type}: ${c.thresholdSummary}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+                                 
+                        
+                  
+                   
+ 
+
+// 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.
+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`).
+ */
+export function toFindingsFilter(
+  impactBand           , type           , stageId         ,
+)                             {
+  return (impactBand || type || stageId !== undefined) ? { impactBand, type, stageId } : undefined;
+}
+
+/**
+ * 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.
+ */
+export function buildEvidenceReport(
+  appModel          ,
+  { redact = false, markdown: computeMarkdown = true, findingsFilter }   
+                                                                          
+    = {},
+)                                                 {
+  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.
+  if (findingsFilter) json = { ...json, findings: json.findings.filter((row) => matchesFindingsFilter(row, findingsFilter)) };
+  const markdown = computeMarkdown ? renderMarkdown(json) : '';
+  return { markdown, json };
+}

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

@@ -0,0 +1,97 @@
+                                          
+
+/** 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. */
+export function coreFindingActionLabel(finding         )                     {
+  switch (finding.type) {
+    case 'skew':
+      return 'Fix task skew';
+    case 'stageShape':
+      switch (finding.rule) {
+        case 'lowParallelism': return 'Increase parallelism';
+        case 'dataExplosion': return 'Check for exploding join';
+        case 'taskStageSkew': return 'Fix straggler task';
+      }
+      break;
+    case 'shuffle':
+      return 'Reduce shuffle size';
+    case 'partitionSizing':
+      switch (finding.rule) {
+        case 'shufflePartitionSkew': return 'Fix skewed partition';
+        case 'lowShuffleParallelism': return 'Add shuffle partitions';
+        case 'maxPartitionTooBig': return 'Repartition oversized data';
+      }
+      break;
+    case 'spill':
+      return 'Reduce spill';
+    case 'gc':
+      return finding.direction === 'low' ? 'Right-size executor memory' : 'Reduce GC pressure';
+    case 'slowHost':
+      if (finding.variant === 'durationShare') return 'Fix data locality';
+      if (finding.variant === 'multiDim') return 'Investigate degraded executor';
+      return 'Check slow host';
+    case 'stageSlowness':
+      return 'Profile slow stage';
+    case 'stageFailed':
+      return 'Inspect stage failure';
+    case 'failures':
+      return 'Investigate task failures';
+    case 'straggler':
+      return 'Fix stragglers';
+    case 'speculationWaste':
+      return 'Tune speculation settings';
+    case 'retryWaste':
+      return 'Investigate retry cause';
+    case 'tinyTask':
+      return 'Coalesce small tasks';
+    case 'coldStart':
+      return 'Pre-warm cluster';
+    case 'utilization':
+      return 'Reduce cluster size';
+    case 'memoryUtilization':
+      switch (finding.variant) {
+        case 'idleCores': return 'Reduce idle cores';
+        case 'wasteModel': return 'Right-size executor memory';
+        case 'memoryBand':
+          if (finding.dataUnavailable) return 'Enable memory metrics';
+          return finding.rule === 'heapNearCapacity' ? 'Increase executor memory' : 'Reduce executor memory';
+      }
+      break;
+    case 'cacheUtilization':
+      return 'Increase cache memory';
+    case 'coreLocality':
+      return 'Fix data locality';
+    case 'autoscalingChurn':
+      return 'Reduce autoscaling churn';
+    case 'cachingOpportunity':
+      return finding.variant === 'composite' ? 'Cache repeated result' : 'Cache shared table';
+    case 'jobFailureRate':
+      return 'Investigate failed jobs';
+    case 'configAudit':
+      switch (finding.property) {
+        case 'spark.shuffle.service.enabled': return 'Enable shuffle service';
+        case 'spark.dynamicAllocation.minExecutors': return 'Fix autoscaling bounds';
+        case 'spark.dynamicAllocation.maxExecutors': return 'Set max executors';
+        case 'spark.serializer': return 'Switch to Kryo';
+        case 'spark.executor.memoryOverhead': return 'Raise memory overhead';
+      }
+      break;
+    case 'duplicatePlanSubtree':
+      return 'Dedupe repeated subtree';
+    case 'smallFiles':
+      return finding.direction === 'write' ? 'Coalesce output files' : 'Compact small files';
+    case 'underBroadcast':
+      return 'Use broadcast join';
+    case 'overBroadcast':
+      return 'Fix oversized broadcast';
+  }
+  return undefined;
+}

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

@@ -0,0 +1,38 @@
+// 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.
+                                                   
+
+function isNonEmpty   (m                           )                     {
+  if (m == null) return false;
+  return (Array.isArray(m) ? m.length : (m                  ).size) > 0;
+}
+
+function has   (m               , value   )          {
+  return Array.isArray(m) ? m.includes(value) : (m                  ).has(value);
+}
+
+                                        
+                                  
+                            
+                                        
+ 
+
+export function matchesFindingFilterCriteria(
+  row                                                               ,
+  criteria                       ,
+)          {
+  if (isNonEmpty(criteria.impactBand) && !has(criteria.impactBand, row.impactBand)) return false;
+  if (isNonEmpty(criteria.type) && !has(criteria.type, row.type)) return false;
+  const { stageId } = criteria;
+  if (typeof stageId === 'number') {
+    if (row.stageId !== stageId) return false;
+  } else if (isNonEmpty(stageId)) {
+    if (row.stageId == null || !has(stageId, row.stageId)) return false;
+  }
+  return true;
+}