@vzn/vx 0.0.621 → 0.0.623

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.621",
+  "version": "0.0.623",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.621",
-    "@vzn/vx-linux-arm64": "0.0.621",
-    "@vzn/vx-darwin-x64": "0.0.621",
-    "@vzn/vx-darwin-arm64": "0.0.621"
+    "@vzn/vx-linux-x64": "0.0.623",
+    "@vzn/vx-linux-arm64": "0.0.623",
+    "@vzn/vx-darwin-x64": "0.0.623",
+    "@vzn/vx-darwin-arm64": "0.0.623"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/why.ts

@@ -9,7 +9,9 @@ import path from 'node:path'
 import { Cache } from '../cache/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
+import type { Database } from 'bun:sqlite'
 import {
+  type CacheKeyDiff,
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
   latestRunId,
@@ -232,9 +234,13 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       )
     }
     const diff = cacheKeyDiff(db, runId, taskId)
+    // An upstream change is never the cause, only its carrier: follow
+    // each moved dependency in this run down to the tasks whose own
+    // inputs moved, so one `vx why` names the file, not the next task.
+    const roots = rootCauses(db, runId, taskId, diff.entries)
 
     if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff })}\n`)
+      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff, roots })}\n`)
       return 0
     }
 
@@ -293,7 +299,22 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
           `    ${e.change.padEnd(7)} ${e.kind.padEnd(kindW)}  ${printable(e.name)}  ${beforeAfter}`.trimEnd(),
         )
       }
-      const kinds = [...new Set(diff.entries.map((e) => e.kind))].filter((k) => k in WHAT_TO_DO)
+      if (roots.length > 0) {
+        lines.push('', '  root cause:')
+        for (const r of roots.slice(0, ROOTS_SHOWN)) {
+          const what = r.entries.map((e) =>
+            e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
+          )
+          lines.push(
+            `    ${r.chain.join(' \u2190 ')} \u2190 ${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
+          )
+        }
+        if (roots.length > ROOTS_SHOWN) lines.push(`    and ${roots.length - ROOTS_SHOWN} more`)
+      }
+      const rootKinds = roots.flatMap((r) => r.entries.map((e) => e.kind))
+      const kinds = [...new Set([...diff.entries.map((e) => e.kind), ...rootKinds])].filter(
+        (k) => k in WHAT_TO_DO && !(k === 'upstream' && roots.length > 0),
+      )
       if (kinds.length > 0) {
         lines.push('', '  what to do:')
         // An upstream row names the task to ask next: the command, not a
@@ -321,3 +342,40 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     cache.close()
   }
 }
+
+const ROOTS_SHOWN = 5
+
+interface RootCause {
+  /** From the asked task down to the one whose own inputs moved. */
+  chain: string[]
+  entries: CacheKeyDiff['entries']
+}
+
+/**
+ * The tasks under `taskId`'s moved upstreams whose OWN key components
+ * moved in the same run, each with the chain that carried it up. A task
+ * visited once is not walked again (a diamond names its root once).
+ */
+function rootCauses(
+  db: Database,
+  runId: string,
+  taskId: string,
+  entries: CacheKeyDiff['entries'],
+): RootCause[] {
+  const roots: RootCause[] = []
+  const seen = new Set([taskId])
+  const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
+    for (const e of moved) {
+      if (e.kind !== 'upstream' || seen.has(e.name)) continue
+      seen.add(e.name)
+      const next = [...chain, e.name]
+      const d = cacheKeyDiff(db, runId, e.name)
+      if (!d.found) continue
+      const own = d.entries.filter((x) => x.kind !== 'upstream')
+      if (own.length > 0) roots.push({ chain: next, entries: own })
+      walk(next, d.entries)
+    }
+  }
+  walk([taskId], entries)
+  return roots
+}

package/src/orchestrator/logger.ts

@@ -283,6 +283,7 @@ export function defaultLogger(
   let restoredLocal = 0
   let restoredRemote = 0
   let skippedCount = 0
+  let savedMs = 0
   // Cache-miss duration spread, accumulated incrementally (the same
   // numbers the final summary computes from the outcome list).
   let spreadMax = 0
@@ -369,6 +370,7 @@ export function defaultLogger(
         restoredRemote,
         miss: succeeded + failed - noCache,
         noCache,
+        savedMs,
         left: total - done,
         spread:
           spreadCount > 0
@@ -698,10 +700,12 @@ export function defaultLogger(
           case 'cache-hit':
             if (outcome.restored === false) upToDate++
             else restoredLocal++
+            savedMs += outcome.storedDurationMs ?? 0
             break
           case 'cache-hit-remote':
             if (outcome.restored === false) upToDate++
             else restoredRemote++
+            savedMs += outcome.storedDurationMs ?? 0
             break
           case 'skipped':
             skippedCount++

package/src/orchestrator/summary.ts

@@ -6,6 +6,7 @@
 import type { TaskOutcome } from '../graph/index.js'
 import { paint, type ColorSupport } from './colors.js'
 import { tallyOutcomes } from './tally.js'
+import { isCacheHit } from './telemetry.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
 import { isGroupTask } from '../graph/index.js'
 import { formatElapsed } from '../util/index.js'
@@ -119,6 +120,8 @@ export interface SummaryStats {
   spread: { maxMs: number; minMs: number; sumMs: number; count: number } | null
   /** Tasks an `admit` policy held with a worker free, and the waits summed. Absent with no hold. */
   held?: { count: number; sumMs: number }
+  /** The hits' stored exec times summed: the work the cache skipped. */
+  savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
   emptyGroups?: readonly string[]
 }
@@ -320,6 +323,10 @@ function resultLine(
         : `${hits} cached (${Math.floor((hits / cacheable) * 100)}%)`,
     )
   if (noCache > 0) parts.push(paint('', `${noCache} no-cache`, colors, { dim: true }))
+  // What the cache paid back, beside what the run cost: the stored exec
+  // time of every hit, never the restore this run spent on it.
+  if ((stats.savedMs ?? 0) >= 1)
+    parts.push(paint(SUCCESS, `${formatElapsed(stats.savedMs!)} saved`, colors))
   parts.push(formatElapsed(totalMs))
   return parts.join(` ${paint('', '\u00b7', colors, { dim: true })} `)
 }
@@ -373,6 +380,9 @@ export function formatRunSummary(
   const durations = outcomes
     .filter((o) => (o.status === 'success' || o.status === 'failed') && !isGroupTask(o.node))
     .map((o) => o.durationMs)
+  let savedMs = 0
+  for (const o of outcomes)
+    if (isCacheHit(o.status) && !isGroupTask(o.node)) savedMs += o.storedDurationMs ?? 0
   const heldOutcomes = outcomes.filter((o) => o.admissionHeldMs !== undefined)
   const notRun = outcomes.filter((o) => neverStarted(o) && !isGroupTask(o.node)).length
   const emptyGroups = outcomes.every((o) => isGroupTask(o.node))
@@ -391,6 +401,7 @@ export function formatRunSummary(
       restoredRemote: t.restoredRemote,
       miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote) - noCache,
       noCache,
+      savedMs,
       spread:
         durations.length > 0
           ? {