@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/projects.ts

@@ -0,0 +1,259 @@
+// The project-config load every consumer of "what tasks exist" shares:
+// `prepareRun` (a run, a plan) and `vx show` (introspection). One code
+// path, so what `show` prints is what a run would see — including the
+// plugin `project` stage, which can give tasks to a package that never
+// wrote a `vx.config.ts`.
+
+import type { ProjectConfig } from '../config.js'
+import {
+  frozenProjectConfig,
+  loadProjectConfigs,
+  validateProjectConfig,
+  type LoadProjectConfigOptions,
+  type Lockfile,
+  type PackageGraph,
+  type ProjectEntry,
+  type ProjectMeta,
+} from '../workspace/index.js'
+import type { WorkspaceConfig } from '../config.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import {
+  buildPackageGraph,
+  computeWorkspaceFingerprint,
+  listProjects,
+  loadWorkspace,
+  loadWorkspaceConfig,
+  resolveCacheDir,
+} from '../workspace/index.js'
+import { parseDependencySpec } from '../graph/index.js'
+import { applyConfigHooks, applyProjectHooks, hasHook } from './plugin-host.js'
+import type { VxPlugin } from './plugin.js'
+
+/**
+ * The workspace config with the plugin `config` stage applied — the first
+ * stage of the pipeline, run before anything is derived from the config.
+ * The plugin list itself is already fixed by then.
+ */
+export async function loadWorkspacePlugins(
+  workspaceRoot: string,
+  warn: (message: string) => void,
+): Promise<{ workspaceConfig: WorkspaceConfig | null; plugins: readonly VxPlugin[] }> {
+  const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
+  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
+  if (workspaceConfig !== null && hasHook(plugins, 'config')) {
+    await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn })
+  }
+  return { workspaceConfig, plugins }
+}
+
+export interface LoadProjectsArgs {
+  workspaceRoot: string
+  cacheDir: string
+  plugins: readonly VxPlugin[]
+  projectMetas: readonly ProjectMeta[]
+  packageGraph: PackageGraph
+  /**
+   * Projects whose configs must load — `'all'`, or names (unknown and
+   * config-less ones are ignored). With `closure`, each seed's transitive
+   * package dependencies load too, which bounds `^task` frontier
+   * expansion; a `pkg#task` dependsOn entry pulls its project in either
+   * way, since the package graph cannot see the cross form.
+   */
+  seeds: 'all' | Iterable<string>
+  closure: boolean
+  /** Read configs from the lock instead of evaluating them (`--frozen`). */
+  lock: Lockfile | null
+  evalCache: LoadProjectConfigOptions['evalCache']
+  warn: (message: string) => void
+  /**
+   * Entries a load in this same process already produced with the same
+   * cache dir and lock (the CLI's selection pass, which stages every
+   * config to walk `pkg#task` edges). Seeding and scoping run exactly as
+   * without it; a project found here is taken as is instead of being
+   * evaluated and put through the `project` stage a second time — the
+   * stage's cost, and its warnings, once per run. Never carried across
+   * runs: a config can change between them.
+   */
+  staged?: ReadonlyMap<string, ProjectEntry>
+}
+
+export interface LoadedProjects {
+  projects: Map<string, ProjectEntry>
+  /**
+   * Every project that can carry tasks: it has a config file, or a plugin
+   * fills the `project` stage and may give it tasks. Boundary geometry
+   * fences all of them, loaded or not.
+   */
+  configured: readonly ProjectMeta[]
+}
+
+/**
+ * SCOPED config loading: configs are programs, and evaluating 1090 of
+ * them costs ~200 ms — the dominant fixed cost of small runs. Only the
+ * seeds, their closure and any project a `pkg#task` entry names can
+ * contribute graph nodes, so only those configs are evaluated. Side
+ * effect, deliberate and Turbo-like: a broken config in an unrelated
+ * package does not fail a scoped run — it surfaces when that package
+ * enters scope.
+ */
+export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjects> {
+  const { plugins, packageGraph, lock, workspaceRoot } = args
+  // A package with no config file declares no tasks — unless a plugin
+  // fills the `project` stage, in which case it is a project the stage may
+  // give tasks to (the zero-migration shape: `turbo.json` or `package.json`
+  // scripts mapped onto packages that never wrote a `vx.config.ts`). It
+  // then loads as `{ tasks: {} }` — nothing to evaluate, nothing to freeze
+  // — and the stage runs on that like on any loaded config. With no
+  // `project` plugin a plain run never visits (or fences, or seeds) a
+  // config-less package.
+  const projectStage = hasHook(plugins, 'project')
+  const configured = args.projectMetas.filter(
+    (m) => projectStage || (typeof m.configPath === 'string' && m.configPath.length > 0),
+  )
+  const metaByName = new Map<string, ProjectMeta>(configured.map((m) => [m.name, m]))
+  const needed = new Set<string>()
+  const pending: ProjectMeta[] = []
+  const consider = (name: string): void => {
+    if (needed.has(name)) return
+    needed.add(name)
+    const meta = metaByName.get(name)
+    if (meta) pending.push(meta)
+  }
+  const considerWithDeps = (name: string): void => {
+    consider(name)
+    // Every config-bearing project already pending: the closure can add
+    // nothing, and asking for it would build the package graph's
+    // transitive bitsets — a cost the unscoped run (every project a seed)
+    // otherwise never pays.
+    if (pending.length === metaByName.size) return
+    for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
+  }
+  const seeds = args.seeds === 'all' ? metaByName.keys() : [...args.seeds]
+  for (const seed of seeds) consider(seed)
+  if (args.closure && pending.length < metaByName.size) {
+    for (const seed of args.seeds === 'all' ? metaByName.keys() : seeds) considerWithDeps(seed)
+  }
+
+  // Load in rounds to a fixpoint. A `pkg#task` dependsOn entry names a
+  // project the PACKAGE graph cannot reach (the cross form ignores npm
+  // deps by design), so its config has to be pulled in — and that config
+  // may declare cross edges of its own. The common case (no cross deps)
+  // is a single round, identical to loading the closure in one batch.
+  const projects = new Map<string, ProjectEntry>()
+  while (pending.length > 0) {
+    const round = pending.splice(0, pending.length)
+    // Only a config FILE is evaluated (or read from the lock); a
+    // config-less project in the round starts from an empty task table,
+    // and a project the caller already staged is neither.
+    const withFile = round.filter(
+      (m): m is ProjectMeta & { configPath: string } =>
+        typeof m.configPath === 'string' && args.staged?.get(m.name) === undefined,
+    )
+    const loaded = lock
+      ? await Promise.all(withFile.map((m) => frozenProjectConfig(lock, m, workspaceRoot)))
+      : await loadProjectConfigs(
+          withFile.map((m) => m.configPath),
+          args.evalCache !== undefined ? { evalCache: args.evalCache } : {},
+        )
+    let next = 0
+    for (const meta of round) {
+      const pre = args.staged?.get(meta.name)
+      if (pre !== undefined) {
+        projects.set(meta.name, pre)
+        for (const name of crossDepProjects(pre.config)) {
+          if (args.closure) considerWithDeps(name)
+          else consider(name)
+        }
+        continue
+      }
+      const config: ProjectConfig =
+        meta.configPath === null ? { tasks: {} } : (loaded[next++] as ProjectConfig)
+      if (projectStage) {
+        // The `project` stage edits the validated object in place; core
+        // re-validates after EACH plugin so a plugin can only produce what
+        // the loader accepts from a user, and the refusal names both the
+        // config file and the plugin whose edit broke it.
+        const where = meta.configPath ?? `${meta.name} (no config file)`
+        await applyProjectHooks(
+          plugins,
+          config,
+          {
+            workspaceRoot,
+            cacheDir: args.cacheDir,
+            warn: args.warn,
+            name: meta.name,
+            dir: meta.dir,
+            packageJson: meta.packageJson as unknown as Readonly<Record<string, unknown>>,
+            projects: args.projectMetas,
+          },
+          (plugin) => validateProjectConfig(config, `${where} (after plugin '${plugin.name}')`),
+        )
+      }
+      projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
+      for (const name of crossDepProjects(config)) {
+        if (args.closure) considerWithDeps(name)
+        else consider(name)
+      }
+    }
+  }
+  return { projects, configured }
+}
+
+/** Project names named by a `pkg#task` dependsOn entry anywhere in `config`. */
+function crossDepProjects(config: ProjectConfig): string[] {
+  const out: string[] = []
+  for (const task of Object.values(config.tasks ?? {})) {
+    for (const raw of task.dependsOn ?? []) {
+      // A malformed spec is the graph builder's error to report — it names
+      // the offending task. Here it just contributes no project.
+      if (!raw.includes('#')) continue
+      try {
+        const spec = parseDependencySpec(raw)
+        if (spec.kind === 'cross') out.push(spec.project)
+      } catch {
+        continue
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * The run path's view of a workspace's projects for a reader — `vx show`,
+ * the MCP server, an embedder: discovery, the plugin `config` and
+ * `project` stages, and the local cache opened only to serve cached
+ * evaluations, so a pure config costs a stat, not an evaluation. `scope`
+ * is every project or a list of names; no closure, no lock (a reader
+ * reads live, as a default run does). Plugin warnings go to `warn`.
+ */
+export async function loadResolvedProjects(
+  workspaceRoot: string,
+  opts: { scope?: 'all' | readonly string[]; warn?: (message: string) => void } = {},
+): Promise<Map<string, ProjectEntry>> {
+  const warn = opts.warn ?? ((): void => {})
+  const metas = await listProjects(await loadWorkspace(workspaceRoot))
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warn)
+  const cacheDir = resolveCacheDir(workspaceRoot, workspaceConfig)
+  const cache = new Cache(cacheDir)
+  noteSchemaReset(cache, warn)
+  try {
+    const loaded = await loadProjects({
+      workspaceRoot,
+      cacheDir,
+      plugins,
+      projectMetas: metas,
+      packageGraph: buildPackageGraph([...metas]),
+      seeds: opts.scope ?? 'all',
+      closure: false,
+      lock: null,
+      evalCache: {
+        store: cache,
+        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
+      },
+      warn,
+    })
+    return loaded.projects
+  } finally {
+    cache.close()
+  }
+}

package/src/orchestrator/remote-prefetch.ts

@@ -70,7 +70,7 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   // tells us which of the N stable hashes exist remotely, so we GET only the
   // hits and pre-mark the misses — their lazy `get` then short-circuits with
   // no network. This collapses N probe waves into 1 and skips every GET that
-  // would 404. When the remote can't batch (`null` — an older serve, reads
+  // would 404. When the remote can't batch (`null` — an older remote, reads
   // disabled, or a layer that doesn't implement the hook at all), fall back to
   // prefetching every stable key, exactly as before.
   let toPrefetch = stableKeys

package/src/orchestrator/run-artifacts.ts

@@ -16,6 +16,7 @@
 import path from 'node:path'
 import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
+import type { FlakyFinding } from './failure-mode.js'
 
 export interface SummarizeArgs {
   /** Empty string → default path; otherwise the explicit file path. */
@@ -29,10 +30,12 @@ export interface SummarizeArgs {
   /** The run's verdict — the same value the CLI turns into the exit code. */
   ok: boolean
   outcomes: readonly TaskOutcome[]
+  /** What `detectFlaky` found this run; the footer's Flaky section, typed. */
+  flaky?: readonly FlakyFinding[]
 }
 
 /** One task's entry. Shared by `tasks` and `aborted` so they read alike. */
-function taskEntry(o: TaskOutcome): Record<string, unknown> {
+function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): Record<string, unknown> {
   return {
     id: o.node.id,
     project: o.node.projectName,
@@ -41,8 +44,26 @@ function taskEntry(o: TaskOutcome): Record<string, unknown> {
     exitCode: o.exitCode,
     durationMs: o.durationMs,
     hash: o.hash ?? null,
+    // A task with no `cache` block executes every run by design; without
+    // the flag a consumer computing a hit rate cannot tell a miss from a
+    // task that could never hit (its `hash` is still set — dependents fold
+    // it). Present only when true, so every other row is byte-identical.
+    ...(o.node.config.cache === undefined ? { noCache: true } : {}),
+    // Present only when the run proved the task flaky: this exact key has
+    // both passed and failed on record (this run counted), or the task
+    // needed a retry. A consumer gating on `failed` can tell a break from a
+    // flake without the history; every other row is byte-identical.
+    ...(flaky !== undefined
+      ? { flaky: { passes: flaky.passes, failures: flaky.failures, attempts: flaky.attempts } }
+      : {}),
     ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
     ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+    // A hit's row names what the PRODUCING execution used under its own
+    // keys, so a consumer never reads a remote worker's peak as this run's.
+    ...(o.storedCpuMs !== undefined ? { storedCpuMs: o.storedCpuMs } : {}),
+    ...(o.storedPeakRssBytes !== undefined ? { storedPeakRssBytes: o.storedPeakRssBytes } : {}),
+    // Present only when an `admit` policy held the task with a worker free.
+    ...(o.admissionHeldMs !== undefined ? { admissionHeldMs: o.admissionHeldMs } : {}),
     // hrtime spans are bigints → emit as strings so JSON.parse on
     // the consumer side doesn't truncate the ns precision.
     ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
@@ -65,6 +86,7 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
   // exit — the terminal has said so in its Aborted section all along, and a
   // parser must not be told less than a human is.
   const aborted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status === 'aborted')
+  const flakyById = new Map((args.flaky ?? []).map((f) => [f.taskId, f]))
   const payload = {
     runId: args.runId,
     // The run-level verdict, first: a consumer gating on this artifact must
@@ -74,8 +96,8 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
     startedAt: new Date(args.startedAtMs).toISOString(),
     endedAt: new Date(args.endedAtMs).toISOString(),
     totalMs: args.totalMs,
-    tasks: counted.map(taskEntry),
-    aborted: aborted.map(taskEntry),
+    tasks: counted.map((o) => taskEntry(o, flakyById.get(o.node.id))),
+    aborted: aborted.map((o) => taskEntry(o)),
     // The FULL list: `tallyOutcomes` applies the same group/aborted
     // exclusions internally, so every counted bucket is unchanged by passing
     // it — but `summary.aborted` is only non-zero if it sees them.

package/src/orchestrator/run-context.ts

@@ -81,7 +81,7 @@ export function captureGitContext(
       // defaultBranch`) means it is at least never mistaken for trunk, but
       // every PR collapses into one scope — so one PR's timings feed another's
       // baseline, cross-branch regression detection counts them as a single
-      // branch, and the dashboard's branch column reads "HEAD".
+      // branch, and a consumer grouping runs by branch reads "HEAD".
       if (br && br !== 'HEAD') branch = br
     }
   } catch {

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

@@ -89,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 '—'
   }
@@ -109,7 +109,7 @@ function fmtDuration(ms: number): string {
  * 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 a `--verify` output path shifted its columns. One definition, so the two
+ * 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 {