Function recommendNextScope

src/cli/maintain-stats.ts:62–76

(
  runs: MaintainRun[],
  stats: MaintainStats,
  allScopes: readonly string[],
)

/** Auto-recommend the next scope to run, with a reason. Prefers a never-run scope; else the scope
 *  blocking most often (a backlog it can't currently clear); else the least-used. PURE. */
export function recommendNextScope(
  runs: MaintainRun[],
  stats: MaintainStats,
  allScopes: readonly string[],
): { scope: string; why: string } | null {
  const never = suggestNextScopes(stats, allScopes);
  if (never.length) return { scope: never[0]!, why: 'never run here yet — try it' };
  // count blocks per scope (a scope that keeps blocking has a backlog worth a look)
  const blocks = new Map<string, number>();
  for (const r of runs) if (r.status === 'blocked') blocks.set(r.scope, (blocks.get(r.scope) ?? 0) + 1);
  const topBlock = [...blocks.entries()].sort((a, b) => b[1] - a[1])[0];
  if (topBlock && topBlock[1] >= 2) return { scope: topBlock[0], why: `blocked ${topBlock[1]}× recently — review the backlog` };
  const leastUsed = [...stats.byScope].sort((a, b) => a.runs - b.runs)[0];
  return leastUsed ? { scope: leastUsed.scope, why: 'least-exercised scope' } : null;
}

export interface MaintainWeekly {
  opened: number; blocked: number; filesCleaned: number; minutesSaved: number;