scripts-orchestrator 2.14.0 → 2.15.1

package/lib/recommend-phases.js

@@ -0,0 +1,340 @@
+/**
+ * @file recommend-phases.js
+ * @description Memory-aware phase recommender (advisory).
+ *
+ * Reads a results JSON (the same payload the orchestrator writes via `metrics: ['time','memory']`)
+ * and proposes a phase layout that keeps each phase's concurrent peak memory under a per-host
+ * budget while letting long-running steps overlap. It only reports — it does not change how a
+ * run is scheduled.
+ *
+ * Algorithm: First-Fit-Decreasing bin-packing by step duration. Steps are sorted longest-first
+ * and each is placed into the earliest phase where adding it keeps Σ(concurrent peak memory) ≤ budget
+ * and concurrent step count ≤ core share; otherwise a new phase is opened. Long steps seed phases;
+ * short steps fill the gaps beneath them, so makespan (Σ of each phase's longest step) stays near the
+ * theoretical floor (the single longest step) without oversubscribing RAM.
+ */
+
+import os from 'os';
+import chalk from 'chalk';
+
+const KB = 1024;
+const GB = 1024 * 1024 * 1024;
+
+/**
+ * Resolve the per-host scheduling budget.
+ *
+ * budget = totalmem × memSafety ÷ fanout   (overridable wholesale via budgetMb)
+ * coreShare = (cores − 2) ÷ fanout         (≥ 1)
+ *
+ * `fanout` models the workspace-level parallelism: when N workspaces gate concurrently they share
+ * the host, so each gets 1/N of RAM and cores.
+ */
+export function computeBudget(opts = {}) {
+  const totalMemBytes = opts.totalMemBytes != null ? Number(opts.totalMemBytes) : os.totalmem();
+  const cores = opts.cores != null ? Number(opts.cores) : os.cpus().length;
+  const fanout = Math.max(1, Number(opts.fanout) || 1);
+  const memSafety = opts.memSafety != null ? Number(opts.memSafety) : 0.8;
+  const budgetBytes =
+    opts.budgetMb != null
+      ? Number(opts.budgetMb) * 1024 * 1024
+      : (totalMemBytes * memSafety) / fanout;
+  const coreShare = Math.max(1, Math.floor((cores - 2) / fanout));
+  return { totalMemBytes, cores, fanout, memSafety, budgetBytes, coreShare };
+}
+
+/**
+ * Extract the steps that actually ran and were timed. Skipped/disabled commands and untimed
+ * entries are excluded — they tell us nothing about contention. `memoryKb` defaults to 0 when the
+ * memory metric wasn't collected (the report then warns and packs by core share alone).
+ */
+export function usableSteps(payload) {
+  const commands = Array.isArray(payload?.commands) ? payload.commands : [];
+  return commands
+    .filter((c) => c && typeof c.durationMs === 'number' && c.durationMs > 0 && !c.skipReason)
+    .map((c) => ({
+      command: c.command,
+      phase: c.phase != null ? c.phase : '(no phase)',
+      durationMs: c.durationMs,
+      memoryKb: typeof c.memoryKb === 'number' && c.memoryKb > 0 ? c.memoryKb : 0,
+    }));
+}
+
+/**
+ * Group steps by their original phase (first-seen order) and, for each phase, report the
+ * concurrent peak memory (Σ of member peaks — conservative, since peaks rarely coincide exactly)
+ * and the phase wall-clock (max member duration, because the phase runs them in parallel).
+ */
+export function observedTimeline(steps, budgetBytes) {
+  const order = [];
+  const byPhase = new Map();
+  for (const s of steps) {
+    if (!byPhase.has(s.phase)) {
+      byPhase.set(s.phase, []);
+      order.push(s.phase);
+    }
+    byPhase.get(s.phase).push(s);
+  }
+  return order.map((name) => {
+    const members = byPhase.get(name);
+    const concurrentMemBytes = members.reduce((sum, s) => sum + s.memoryKb * KB, 0);
+    const wallclockMs = Math.max(...members.map((s) => s.durationMs));
+    return {
+      name,
+      steps: members,
+      concurrentMemBytes,
+      wallclockMs,
+      overBudget: concurrentMemBytes > budgetBytes,
+    };
+  });
+}
+
+/**
+ * First-Fit-Decreasing bin-packing by duration. A step too large to fit any existing bin under the
+ * budget opens a new bin; a single step whose own peak exceeds the budget still gets its own bin
+ * (it can't be split) and is flagged.
+ */
+export function packPhases(steps, budgetBytes, coreShare) {
+  const sorted = [...steps].sort((a, b) => b.durationMs - a.durationMs);
+  const bins = [];
+  for (const step of sorted) {
+    const stepBytes = step.memoryKb * KB;
+    let placed = false;
+    for (const bin of bins) {
+      if (bin.memBytes + stepBytes <= budgetBytes && bin.steps.length < coreShare) {
+        bin.steps.push(step);
+        bin.memBytes += stepBytes;
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      bins.push({ steps: [step], memBytes: stepBytes });
+    }
+  }
+  for (const bin of bins) {
+    bin.wallclockMs = Math.max(...bin.steps.map((s) => s.durationMs));
+    bin.exceedsBudget = bin.memBytes > budgetBytes; // only possible for a lone oversized step
+  }
+  return bins;
+}
+
+/**
+ * Produce a full recommendation object from a results payload. Pure — all host inputs are taken from
+ * `opts` or `os`, so it's testable without a real machine.
+ */
+export function recommendPhases(payload, opts = {}) {
+  const budget = computeBudget(opts);
+  const steps = usableSteps(payload);
+  const warnings = [];
+
+  if (steps.length === 0) {
+    warnings.push('No completed, timed commands found in the results — nothing to recommend.');
+  }
+  const hasMemory = steps.some((s) => s.memoryKb > 0);
+  if (steps.length > 0 && !hasMemory) {
+    warnings.push(
+      'No memory metrics in the results — re-run with metrics including "memory" for a meaningful budget. Packing falls back to the core-share limit only.',
+    );
+  }
+
+  const observed = observedTimeline(steps, budget.budgetBytes);
+  const bins = packPhases(steps, budget.budgetBytes, budget.coreShare);
+
+  const observedMakespanMs = observed.reduce((sum, p) => sum + p.wallclockMs, 0);
+  const recommendedMakespanMs = bins.reduce((sum, b) => sum + b.wallclockMs, 0);
+  const optimalMakespanMs = steps.length ? Math.max(...steps.map((s) => s.durationMs)) : 0;
+  const longestStep = steps.length
+    ? steps.reduce((a, b) => (b.durationMs > a.durationMs ? b : a))
+    : null;
+
+  const verdict = decideVerdict({
+    steps,
+    observedMakespanMs,
+    recommendedMakespanMs,
+    optimalMakespanMs,
+    longestStep,
+    binCount: bins.length,
+  });
+
+  return {
+    ...budget,
+    steps,
+    observed,
+    observedMakespanMs,
+    recommended: { bins, makespanMs: recommendedMakespanMs },
+    optimalMakespanMs,
+    verdict,
+    warnings,
+  };
+}
+
+/**
+ * Reduce the numbers to a single yes/no answer: "is re-grouping these phases worth it?".
+ *
+ * Re-grouping helps only when packing meaningfully beats the observed makespan. It cannot beat the
+ * single longest step (the theoretical floor), so when one step dominates the makespan the honest
+ * answer is "no — splitting that step is the only lever left", not "re-group".
+ *
+ * Returns `{ worthwhile, savedMs, reason }`. Thresholds are deliberately conservative so the advice
+ * stays quiet unless there's a real, non-trivial win.
+ */
+export function decideVerdict({
+  steps,
+  observedMakespanMs,
+  recommendedMakespanMs,
+  optimalMakespanMs,
+  longestStep,
+  binCount,
+}) {
+  if (!steps.length) {
+    return { worthwhile: false, savedMs: 0, reason: 'No timed steps to analyse.' };
+  }
+
+  const savedMs = observedMakespanMs - recommendedMakespanMs;
+  const savedFraction = observedMakespanMs > 0 ? savedMs / observedMakespanMs : 0;
+  const dominantFraction = observedMakespanMs > 0 ? optimalMakespanMs / observedMakespanMs : 0;
+
+  // A real win: packing trims at least 5% AND at least 5s off the observed makespan.
+  const significant = savedMs >= 5000 && savedFraction >= 0.05;
+  if (significant) {
+    return {
+      worthwhile: true,
+      savedMs,
+      reason:
+        `Re-grouping into ${binCount} phase(s) could trim ~${fmtDuration(savedMs)} ` +
+        `(${Math.round(savedFraction * 100)}%) off the makespan.`,
+    };
+  }
+
+  // One step is ≥95% of the makespan: nothing else matters until it's broken up.
+  if (dominantFraction >= 0.95 && longestStep) {
+    return {
+      worthwhile: false,
+      savedMs,
+      reason:
+        `One step ("${longestStep.command}", ${fmtDuration(optimalMakespanMs)}) is ` +
+        `~${Math.round(dominantFraction * 100)}% of the makespan, so re-grouping the rest cannot help. ` +
+        'To go faster, split that step into smaller commands the orchestrator can schedule separately.',
+    };
+  }
+
+  return {
+    worthwhile: false,
+    savedMs,
+    reason:
+      `The current layout is already within ~${fmtDuration(Math.max(0, savedMs))} of the packed ` +
+      'optimum — re-grouping is not worth it.',
+  };
+}
+
+// ---- formatting helpers ---------------------------------------------------
+
+export function fmtDuration(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = Math.round(seconds % 60);
+  return `${minutes}m ${rem}s`;
+}
+
+export function fmtMemKb(kb) {
+  if (!kb) return '0';
+  const bytes = kb * KB;
+  if (bytes >= GB) return `${(bytes / GB).toFixed(2)} GB`;
+  return `${Math.round(bytes / (1024 * 1024))} MB`;
+}
+
+function stepLine(s) {
+  return `      ${fmtDuration(s.durationMs).padStart(8)}  ${fmtMemKb(s.memoryKb).padStart(9)}  ${s.command}`;
+}
+
+/**
+ * Render a recommendation as a human-readable, optionally-colored report.
+ */
+export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
+  const c = chalk;
+  const L = [];
+
+  L.push(c.bold('🧮 Scripts-Orchestrator — memory-aware phase recommendation (advisory)'));
+  if (sourcePath) L.push(c.dim(`   Source: ${sourcePath}`));
+  L.push(
+    `   Budget: ${c.yellow(fmtMemKb(rec.budgetBytes / KB))} ` +
+      `(RAM ${fmtMemKb(rec.totalMemBytes / KB)} × ${rec.memSafety} ÷ fan-out ${rec.fanout}) · ` +
+      `core share: ${c.yellow(String(rec.coreShare))} (${rec.cores} cores − 2 ÷ ${rec.fanout})`,
+  );
+
+  for (const w of rec.warnings) L.push(c.yellow(`   ⚠ ${w}`));
+  if (rec.steps.length === 0) {
+    L.push('');
+    L.push(`${c.bold('Verdict:')} ${verdictLine(rec.verdict)}`);
+    return L.join('\n');
+  }
+
+  // Observed timeline
+  L.push('');
+  L.push(
+    c.bold(
+      `Observed timeline — ${rec.steps.length} steps · ${rec.observed.length} phase(s) · makespan ${fmtDuration(rec.observedMakespanMs)}`,
+    ),
+  );
+  for (const ph of rec.observed) {
+    const flag = ph.overBudget ? c.red('  ⚠ concurrent peak over budget') : '';
+    L.push(
+      `  ${c.cyan(ph.name)}  ${fmtDuration(ph.wallclockMs)} · ${ph.steps.length} step(s) · Σ peak ${fmtMemKb(ph.concurrentMemBytes / KB)}${flag}`,
+    );
+    for (const s of [...ph.steps].sort((a, b) => b.durationMs - a.durationMs)) L.push(stepLine(s));
+  }
+
+  // Recommended layout
+  L.push('');
+  L.push(
+    c.bold(
+      `Recommended layout — First-Fit-Decreasing by duration (≤ ${fmtMemKb(rec.budgetBytes / KB)} mem, ≤ ${rec.coreShare} concurrent)`,
+    ),
+  );
+  rec.recommended.bins.forEach((bin, i) => {
+    const flag = bin.exceedsBudget ? c.red('  ⚠ lone step exceeds budget (cannot split)') : '';
+    L.push(
+      `  ${c.green('phase ' + (i + 1))}  ${fmtDuration(bin.wallclockMs)} · ${bin.steps.length} step(s) · Σ peak ${fmtMemKb(bin.memBytes / KB)}${flag}`,
+    );
+    for (const s of [...bin.steps].sort((a, b) => b.durationMs - a.durationMs)) L.push(stepLine(s));
+  });
+
+  // Summary
+  const saved = rec.observedMakespanMs - rec.recommended.makespanMs;
+  L.push('');
+  L.push(c.bold('Estimated makespan'));
+  L.push(`  observed (sequential phases): ${fmtDuration(rec.observedMakespanMs)}`);
+  const delta =
+    saved > 0
+      ? c.green(`(−${fmtDuration(saved)})`)
+      : saved < 0
+        ? c.red(`(+${fmtDuration(-saved)})`)
+        : c.dim('(no change)');
+  L.push(`  recommended (packed):         ${fmtDuration(rec.recommended.makespanMs)}  ${delta}`);
+  L.push(`  theoretical floor (∞ RAM):    ${fmtDuration(rec.optimalMakespanMs)}`);
+
+  // Verdict — the one-line yes/no the reader actually wants.
+  L.push('');
+  L.push(`${c.bold('Verdict:')} ${verdictLine(rec.verdict)}`);
+
+  L.push('');
+  L.push(
+    c.dim(
+      '  Note: advisory only — peaks are per-process maxima summed conservatively, and packing ignores\n' +
+        '  inter-phase data dependencies (e.g. build → post-build checks). Validate against a real run.',
+    ),
+  );
+
+  return L.join('\n');
+}
+
+/** Render the verdict as a colored ✅/❌ one-liner. */
+function verdictLine(verdict) {
+  if (!verdict) return '';
+  return verdict.worthwhile
+    ? `${chalk.green('✅ Yes')} — ${verdict.reason}`
+    : `${chalk.yellow('❌ No')} — ${verdict.reason}`;
+}

package/lib/recommend-phases.test.js

@@ -0,0 +1,164 @@
+import {
+  computeBudget,
+  usableSteps,
+  observedTimeline,
+  packPhases,
+  recommendPhases,
+  decideVerdict,
+  formatRecommendationReport,
+} from './recommend-phases.js';
+
+const GB_KB = 1024 * 1024; // 1 GB expressed in KB
+
+// A small synthetic run loosely modelled on the finalyzerui worktree profile.
+const payload = {
+  success: true,
+  commands: [
+    { command: 'build', phase: 'build', success: true, durationMs: 123000, memoryKb: 3.5 * GB_KB },
+    { command: 'type-check', phase: 'build', success: true, durationMs: 28000, memoryKb: 1.9 * GB_KB },
+    { command: 'test-ci', phase: 'tests', success: true, durationMs: 92000, memoryKb: 1.3 * GB_KB },
+    { command: 'build-storybook', phase: 'storybook', success: true, durationMs: 97000, memoryKb: 6.8 * GB_KB },
+    { command: 'lint-ci', phase: 'lint', success: true, durationMs: 6500, memoryKb: 0.3 * GB_KB },
+    { command: 'disabled-thing', phase: 'lint', success: true, durationMs: 0, skipReason: 'disabled' },
+  ],
+};
+
+describe('computeBudget', () => {
+  test('derives budget and core share from host inputs and fan-out', () => {
+    const b = computeBudget({ totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1, memSafety: 0.8 });
+    expect(b.budgetBytes).toBeCloseTo(16 * 1024 ** 3 * 0.8);
+    expect(b.coreShare).toBe(8); // (10 - 2) / 1
+  });
+
+  test('fan-out divides both memory and core budgets', () => {
+    const b = computeBudget({ totalMemBytes: 32 * 1024 ** 3, cores: 12, fanout: 2, memSafety: 0.8 });
+    expect(b.budgetBytes).toBeCloseTo((32 * 1024 ** 3 * 0.8) / 2);
+    expect(b.coreShare).toBe(5); // floor((12 - 2) / 2)
+  });
+
+  test('budgetMb overrides the computed budget; core share never drops below 1', () => {
+    const b = computeBudget({ totalMemBytes: 8 * 1024 ** 3, cores: 2, budgetMb: 4096 });
+    expect(b.budgetBytes).toBe(4096 * 1024 * 1024);
+    expect(b.coreShare).toBe(1);
+  });
+});
+
+describe('usableSteps', () => {
+  test('drops skipped/untimed commands and normalises fields', () => {
+    const steps = usableSteps(payload);
+    expect(steps.map((s) => s.command)).not.toContain('disabled-thing');
+    expect(steps).toHaveLength(5);
+    expect(steps.every((s) => s.durationMs > 0)).toBe(true);
+  });
+});
+
+describe('observedTimeline', () => {
+  test('groups by phase, sums concurrent peaks, flags over-budget phases', () => {
+    const steps = usableSteps(payload);
+    const budgetBytes = 4 * 1024 ** 3; // 4 GB
+    const tl = observedTimeline(steps, budgetBytes);
+    const build = tl.find((p) => p.name === 'build');
+    // build (3.5) + type-check (1.9) = 5.4 GB > 4 GB budget
+    expect(build.overBudget).toBe(true);
+    expect(build.wallclockMs).toBe(123000); // max of its members
+  });
+});
+
+describe('packPhases (First-Fit-Decreasing)', () => {
+  test('keeps each bin under the memory budget and respects core share', () => {
+    const steps = usableSteps(payload);
+    const budgetBytes = 12.8 * 1024 ** 3; // 16 GB laptop @ 0.8
+    const bins = packPhases(steps, budgetBytes, 8);
+    for (const bin of bins) {
+      expect(bin.memBytes).toBeLessThanOrEqual(budgetBytes);
+      expect(bin.steps.length).toBeLessThanOrEqual(8);
+    }
+    // longest step seeds the first bin
+    expect(bins[0].steps[0].command).toBe('build');
+  });
+
+  test('a lone oversized step gets its own bin and is flagged', () => {
+    const big = [{ command: 'huge', phase: 'p', durationMs: 1000, memoryKb: 10 * GB_KB }];
+    const bins = packPhases(big, 4 * 1024 ** 3, 8);
+    expect(bins).toHaveLength(1);
+    expect(bins[0].exceedsBudget).toBe(true);
+  });
+});
+
+describe('recommendPhases', () => {
+  test('packed makespan beats the sequential-phase makespan on a constrained host', () => {
+    const rec = recommendPhases(payload, { totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1 });
+    expect(rec.recommended.makespanMs).toBeLessThan(rec.observedMakespanMs);
+    expect(rec.optimalMakespanMs).toBe(123000); // single longest step
+  });
+
+  test('warns when no memory metrics are present', () => {
+    const rec = recommendPhases({
+      commands: [{ command: 'a', phase: 'p', success: true, durationMs: 1000 }],
+    });
+    expect(rec.warnings.join(' ')).toMatch(/memory/i);
+  });
+
+  test('empty results produce a graceful warning, no throw', () => {
+    const rec = recommendPhases({ commands: [] });
+    expect(rec.steps).toHaveLength(0);
+    expect(rec.warnings.join(' ')).toMatch(/nothing to recommend/i);
+    expect(() => formatRecommendationReport(rec)).not.toThrow();
+  });
+
+  test('attaches a verdict object to the recommendation', () => {
+    const rec = recommendPhases(payload, { totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1 });
+    expect(rec.verdict).toBeDefined();
+    expect(typeof rec.verdict.worthwhile).toBe('boolean');
+    expect(typeof rec.verdict.reason).toBe('string');
+  });
+});
+
+describe('decideVerdict', () => {
+  const longest = { command: 'build', durationMs: 600000 };
+
+  test('says yes when packing trims a meaningful chunk off the makespan', () => {
+    const v = decideVerdict({
+      steps: [{}, {}, {}],
+      observedMakespanMs: 100000,
+      recommendedMakespanMs: 70000, // 30s / 30% saved
+      optimalMakespanMs: 60000,
+      longestStep: longest,
+      binCount: 2,
+    });
+    expect(v.worthwhile).toBe(true);
+    expect(v.savedMs).toBe(30000);
+  });
+
+  test('says no — and points at the monolith — when one step dominates', () => {
+    const v = decideVerdict({
+      steps: [{}, {}],
+      observedMakespanMs: 610000,
+      recommendedMakespanMs: 610000,
+      optimalMakespanMs: 600000, // ~98% of makespan
+      longestStep: longest,
+      binCount: 1,
+    });
+    expect(v.worthwhile).toBe(false);
+    expect(v.reason).toMatch(/split that step/i);
+    expect(v.reason).toContain('build');
+  });
+
+  test('says no when the saving is below the threshold', () => {
+    const v = decideVerdict({
+      steps: [{}, {}, {}, {}],
+      observedMakespanMs: 100000,
+      recommendedMakespanMs: 98000, // only 2% / 2s
+      optimalMakespanMs: 40000,
+      longestStep: longest,
+      binCount: 2,
+    });
+    expect(v.worthwhile).toBe(false);
+    expect(v.reason).toMatch(/isn't worth it|within/i);
+  });
+
+  test('handles the no-steps case', () => {
+    const v = decideVerdict({ steps: [], observedMakespanMs: 0, recommendedMakespanMs: 0, optimalMakespanMs: 0, longestStep: null, binCount: 0 });
+    expect(v.worthwhile).toBe(false);
+  });
+});