@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/run-records.ts

@@ -0,0 +1,149 @@
+// What a finished run leaves behind: the `runs` rows, the `invocations`
+// header row, and — only when a telemetry sink is active — the per-task
+// telemetry mirror. One pass over the outcome list builds all three, so
+// `invocations.task_count`, the terminal's "N total" and the number of
+// telemetry tasks are the same count by construction (`tallyOutcomes`
+// applies the same group/aborted filter).
+
+import type { InvocationRecord, RunRecord } from '../cache/index.js'
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
+import { VERSION } from '../version.js'
+import type { CiContext, GitContext, HostContext } from './run-context.js'
+import { deriveCacheSource, isCacheHit, type TaskTelemetry } from './telemetry.js'
+
+export interface RunRecordsInput {
+  outcomes: readonly TaskOutcome[]
+  runId: string
+  /** Wall-clock ms at run start; every per-task ns offset is anchored to it. */
+  startedAtMs: number
+  endedAtMs: number
+  totalMs: number
+  ok: boolean
+  command: string
+  requestedTasks: readonly string[]
+  /** Already compacted (`compactCachePolicy`), the form the header row stores. */
+  cachePolicy: string
+  concurrency: number
+  flow: InvocationRecord['flow']
+  forwardArgs?: readonly string[] | undefined
+  tags: Record<string, string>
+  git: GitContext
+  ci: CiContext
+  host: HostContext
+  /** Build the telemetry mirror; a run with no sink allocates none. */
+  withTelemetry: boolean
+}
+
+export interface RunRecords {
+  runs: RunRecord[]
+  invocation: InvocationRecord
+  telemetryTasks: TaskTelemetry[]
+}
+
+/**
+ * Every non-group, non-aborted outcome gets a row. An outcome with NO hash
+ * (a `skipped` task never probed the cache; a `persistent` one is never
+ * cacheable) used to be dropped because `runs.hash` is NOT NULL — which
+ * made a failing persistent task record `0 tasks, 0 failures` on a run the
+ * terminal called red, and a failed task with a skipped dependent record
+ * 1 of 2. `bindRun` stores `''` for those instead; the key-diff readers
+ * guard it.
+ */
+export function assembleRunRecords(input: RunRecordsInput): RunRecords {
+  const { outcomes, runId, startedAtMs, endedAtMs } = input
+  const runs: RunRecord[] = []
+  const telemetryTasks: TaskTelemetry[] = []
+  let failedCount = 0
+  let hitLocalCount = 0
+  let hitRemoteCount = 0
+  for (const o of outcomes) {
+    if (isGroupTask(o.node)) continue
+    // aborted (killed by a shutdown signal) isn't a real run.
+    if (o.status === 'aborted') continue
+    if (input.withTelemetry) telemetryTasks.push(telemetryOf(o))
+    runs.push({
+      ...(o.hash !== undefined ? { hash: o.hash } : {}),
+      project: o.node.projectName,
+      task: o.node.taskName,
+      status: o.status,
+      exitCode: o.exitCode,
+      durationMs: o.durationMs,
+      ...(input.forwardArgs !== undefined ? { forwardArgs: input.forwardArgs } : {}),
+      // Anchor to the REAL per-task wall-clock window: run-start wall time +
+      // the task's ns offset (captured for hits and executed tasks alike).
+      // The `end - duration` fallback applies to outcomes without an offset —
+      // today only `skipped`, which the scheduler finishes synchronously with
+      // no span, so it collapses to a zero-width mark at the run's end. Using
+      // run-end-minus-duration for EVERYTHING was the old bug that piled every
+      // task at the right edge of the timeline.
+      startedAt:
+        o.wallclockStartNs !== undefined
+          ? startedAtMs + Math.round(Number(o.wallclockStartNs) / 1e6)
+          : endedAtMs - o.durationMs,
+      endedAt:
+        o.wallclockEndNs !== undefined
+          ? startedAtMs + Math.round(Number(o.wallclockEndNs) / 1e6)
+          : endedAtMs,
+      runId,
+      ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
+      ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+      ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: o.wallclockStartNs } : {}),
+      ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: o.wallclockEndNs } : {}),
+      cacheHit: isCacheHit(o.status),
+      ...(o.attempts !== undefined ? { attempts: o.attempts } : {}),
+      cached: o.node.config.cache !== undefined,
+    })
+    if (o.status === 'failed') failedCount++
+    if (o.status === 'cache-hit') hitLocalCount++
+    if (o.status === 'cache-hit-remote') hitRemoteCount++
+  }
+  const invocation: InvocationRecord = {
+    runId,
+    command: input.command,
+    requestedTasks: JSON.stringify([...input.requestedTasks]),
+    cachePolicy: input.cachePolicy,
+    concurrency: input.concurrency,
+    flow: input.flow,
+    startedAt: startedAtMs,
+    endedAt: endedAtMs,
+    totalDurationMs: Math.round(input.totalMs),
+    taskCount: runs.length,
+    failedCount,
+    hitCount: hitLocalCount + hitRemoteCount,
+    hitLocalCount,
+    hitRemoteCount,
+    exitOk: input.ok,
+    commitSha: input.git.commitSha,
+    branch: input.git.branch,
+    dirty: input.git.dirty,
+    ci: input.ci.ci,
+    ciProvider: input.ci.provider,
+    host: input.host.host,
+    os: input.host.os,
+    arch: input.host.arch,
+    vxVersion: VERSION,
+    tags: JSON.stringify(input.tags),
+  }
+  return { runs, invocation, telemetryTasks }
+}
+
+function telemetryOf(o: TaskOutcome): TaskTelemetry {
+  const t: TaskTelemetry = {
+    taskId: o.node.id,
+    project: o.node.projectName,
+    task: o.node.taskName,
+    status: o.status,
+    cacheSource: deriveCacheSource(o.status),
+    exitCode: o.exitCode,
+    durationMs: o.durationMs,
+  }
+  if (o.hash !== undefined) t.hash = o.hash
+  if (o.cpuMs !== undefined) t.cpuMs = o.cpuMs
+  if (o.peakRssBytes !== undefined) t.peakRssBytes = o.peakRssBytes
+  if (o.where !== undefined) t.where = o.where
+  if (o.outputs !== undefined) t.outputs = o.outputs
+  if (o.attempts !== undefined) t.attempts = o.attempts
+  if (o.wallclockStartNs !== undefined) t.wallclockStartNs = o.wallclockStartNs.toString()
+  if (o.wallclockEndNs !== undefined) t.wallclockEndNs = o.wallclockEndNs.toString()
+  return t
+}

package/src/orchestrator/run-report.ts

@@ -1,64 +1,66 @@
-// Markdown run report (`vx run --report=markdown`). A moon-style table —
-// one row per task plus a header line of totals — written verbatim to
-// stdout after a run so CI can append it to a step summary
-// (`vx run ci --report=markdown >> $GITHUB_STEP_SUMMARY`). Pure: the
-// run's finished outcomes in, a markdown string out. No ANSI, no live
-// region — keep it machine-clean and diffable.
+// Markdown run report (`vx run --report=markdown` / `--report-file=<path>`).
+// A moon-style table — one row per task plus a header line of totals —
+// rendered after a run so CI can put it in a step summary
+// (`vx run ci --report-file="$GITHUB_STEP_SUMMARY"`). Pure: the run's
+// finished outcomes in, a markdown string out. No ANSI, no live region —
+// keep it machine-clean and diffable.
+//
+// Machine-clean is a property of this STRING, not of stdout: the status
+// logger shares that stream, so redirecting it captures the whole run log
+// too. `--report-file` is the sink that carries the property end to end.
 
-import type { RunResult } from './protocol.js'
 import type { OutcomeView } from './events.js'
 
 /**
- * Outcome buckets for the report header. Mirrors the terminal summary's
- * `tallyOutcomes` partition (success counts hits; `aborted` is no work
- * and excluded), but derives from the serializable `OutcomeView` the CLI
- * holds after a run rather than the in-process `TaskOutcome` — so it
- * needs no graph back-ref and stays self-contained here.
+ * One finished run, reduced to what a report needs. Used to live in
+ * `protocol.ts` as the return type of the whole-run `backend` seam; that
+ * seam is gone (a run always executes in-process — see
+ * `docs/modules/executor.md`), so the shape lives with its only consumer.
  */
-interface ReportTally {
-  total: number
-  successful: number
-  failed: number
-  skipped: number
-  cached: number
+export interface RunResult {
+  ok: boolean
+  outcomes: OutcomeView[]
+}
+import { tallyViews, type Tally } from './tally.js'
+
+/**
+ * The report header's numbers. The outcome BUCKETS come from the shared
+ * `tallyViews` — the same rules the terminal summary and `--summarize` use,
+ * so three surfaces describing one run cannot disagree. Only the two
+ * durations are report-specific.
+ *
+ * This used to be a private copy of the partition, and it drifted: it had no
+ * group filter (it could not have one — `OutcomeView` had no `isGroup`), so
+ * every organizational node was counted as a successful task and rendered as
+ * a row claiming `success | miss | 0ms`.
+ */
+interface ReportTally extends Tally {
   /** Wall-clock ms summed over tasks that actually executed (misses). */
   executedMs: number
-  /** Wall-clock ms summed over cache hits — the work the cache skipped. */
+  /**
+   * Ms of work the cache SKIPPED — the sum of the hits' STORED exec times.
+   * Deliberately not `durationMs`, which for a hit is the restore this run
+   * paid: summing that reported a 2.01 s task as "6ms saved".
+   */
   savedMs: number
 }
 
 function tally(outcomes: readonly OutcomeView[]): ReportTally {
-  const t: ReportTally = {
-    total: 0,
-    successful: 0,
-    failed: 0,
-    skipped: 0,
-    cached: 0,
-    executedMs: 0,
-    savedMs: 0,
-  }
+  const t: ReportTally = { ...tallyViews(outcomes), executedMs: 0, savedMs: 0 }
   for (const o of outcomes) {
-    // A child killed by a shutdown signal (Ctrl-C teardown) is no work —
-    // excluded from totals and every bucket, like the terminal tally.
-    if (o.status === 'aborted') continue
-    t.total++
+    if (o.isGroup === true) continue
     switch (o.status) {
       case 'success':
-        t.successful++
+      case 'failed':
         t.executedMs += o.durationMs
         break
       case 'cache-hit':
       case 'cache-hit-remote':
-        t.successful++
-        t.cached++
-        t.savedMs += o.durationMs
-        break
-      case 'failed':
-        t.failed++
-        t.executedMs += o.durationMs
-        break
-      case 'skipped':
-        t.skipped++
+        // An outcome that doesn't know what it skipped contributes nothing:
+        // better to omit the claim than to substantiate it with the restore
+        // cost. (Only reachable across a version skew — every hit this
+        // binary produces carries the stored duration.)
+        t.savedMs += o.storedDurationMs ?? 0
         break
     }
   }
@@ -87,7 +89,7 @@ function cacheWord(o: OutcomeView): string {
       return o.restored === false ? 'up-to-date' : 'remote'
     case 'success':
     case 'failed':
-      return 'miss'
+      return o.noCache === true ? 'no-cache' : 'miss'
     default:
       return '—'
   }
@@ -98,6 +100,24 @@ function fmtDuration(ms: number): string {
   return `${(ms / 1000).toFixed(2)}s`
 }
 
+/**
+ * Make a value safe inside a GFM table cell. Task names are arbitrary TS
+ * object keys and the loader accepts `|` and newlines, either of which
+ * silently breaks the table on the consumer (`>> $GITHUB_STEP_SUMMARY`):
+ * a bare pipe adds a column, a newline splits the row.
+ *
+ * Exported because this file is not the only markdown table describing a run:
+ * the cloud plugin's GitHub job summary renders the same data from the same
+ * unvalidated names and shipped WITHOUT this escape, so a `|` in a task name
+ * or an output path shifted its columns. One definition, so the two
+ * cannot disagree about what a cell may contain.
+ */
+export function escapeMarkdownCell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+}
+
+const cell = escapeMarkdownCell
+
 /**
  * Render the finished run as a markdown report. A header line of totals
  * followed by a per-task table. Self-contained — everything is derived
@@ -105,13 +125,15 @@ function fmtDuration(ms: number): string {
  */
 export function formatRunReportMarkdown(result: RunResult): string {
   const t = tally(result.outcomes)
+  const cached = t.cachedLocal + t.cachedRemote
   const parts = [
     `**${t.total} task${t.total === 1 ? '' : 's'}**`,
     `${t.successful} success`,
     `${t.failed} failed`,
-    `${t.cached} cached`,
+    `${cached} cached`,
   ]
   if (t.skipped > 0) parts.push(`${t.skipped} skipped`)
+  if (t.aborted > 0) parts.push(`${t.aborted} aborted`)
   parts.push(`${fmtDuration(t.executedMs)} total`)
   if (t.savedMs > 0) parts.push(`${fmtDuration(t.savedMs)} saved`)
 
@@ -123,9 +145,14 @@ export function formatRunReportMarkdown(result: RunResult): string {
   lines.push('| Task | Status | Cache | Duration |')
   lines.push('| --- | --- | --- | --- |')
   for (const o of result.outcomes) {
-    if (o.status === 'aborted') continue
+    // A group node did no work: no command, no cache decision, 0ms. Rendering
+    // one as `success | miss | 0ms` invents a task the user never wrote a
+    // command for. Same exclusion the header's tally makes.
+    if (o.isGroup === true) continue
     lines.push(
-      `| ${o.taskId} | ${statusWord(o)} | ${cacheWord(o)} | ${fmtDuration(o.durationMs)} |`,
+      `| ${cell(o.taskId)} | ${cell(statusWord(o))} | ${cell(cacheWord(o))} | ${cell(
+        fmtDuration(o.durationMs),
+      )} |`,
     )
   }
   return lines.join('\n') + '\n'