@vzn/vx 0.0.646 → 0.0.649

package/src/graph/critical-path.ts

@@ -0,0 +1,79 @@
+// The critical-path score a `schedule` plugin feeds the scheduler, from
+// whatever timings it learned. It imports only types, so the Learn page's
+// scheduler simulator (through private/vx-bench/schedule-policy.ts) bundles
+// it for the browser without the rest of `@vzn/vx`.
+
+import type { TaskNode } from './task-graph.js'
+
+/** Default duration when neither task history nor a workspace median exists. */
+const DEFAULT_DURATION_MS = 1000
+
+/**
+ * For each node, the expected remaining critical-path duration: its own p50
+ * plus the maximum over its dependents. A node with no history takes its
+ * assumed duration if one was given, else the workspace median; an empty
+ * history takes a flat default.
+ */
+export function criticalPath(
+  nodes: readonly TaskNode[],
+  history: ReadonlyMap<string, { readonly p50DurationMs?: number | undefined }>,
+  assume: Readonly<Record<string, number>> = {},
+): ReadonlyMap<string, number> {
+  const p50s: number[] = []
+  for (const h of history.values()) {
+    if (h.p50DurationMs !== undefined) p50s.push(h.p50DurationMs)
+  }
+  p50s.sort((a, b) => a - b)
+  const workspaceMedian =
+    p50s.length > 0
+      ? (p50s[Math.floor(p50s.length / 2)] ?? DEFAULT_DURATION_MS)
+      : DEFAULT_DURATION_MS
+
+  const dependentsOf = new Map<string, string[]>()
+  for (const n of nodes) {
+    for (const upstreamId of n.deps) {
+      const list = dependentsOf.get(upstreamId)
+      if (list) list.push(n.id)
+      else dependentsOf.set(upstreamId, [n.id])
+    }
+  }
+  // A group runs nothing, so it has no history; the median would charge it
+  // a whole task and let a gate outrank the longest chain (PR #3286).
+  const ownDuration = (n: TaskNode): number =>
+    n.config.exec?.command === undefined
+      ? 0
+      : (history.get(n.id)?.p50DurationMs ?? assume[n.id] ?? workspaceMedian)
+
+  // Reverse-topological pass: a node's value is final once every dependent's
+  // is, so start from the sinks (no dependents) and release each upstream
+  // when its last dependent has been scored.
+  const memo = new Map<string, number>()
+  const nodeById = new Map<string, TaskNode>(nodes.map((n) => [n.id, n]))
+  const pending = new Map<string, number>()
+  const queue: TaskNode[] = []
+  for (const n of nodes) {
+    const count = dependentsOf.get(n.id)?.length ?? 0
+    pending.set(n.id, count)
+    if (count === 0) queue.push(n)
+  }
+  let head = 0
+  while (head < queue.length) {
+    const n = queue[head++]!
+    let downstream = 0
+    for (const dep of dependentsOf.get(n.id) ?? []) {
+      const d = memo.get(dep) ?? 0
+      if (d > downstream) downstream = d
+    }
+    memo.set(n.id, ownDuration(n) + downstream)
+    for (const up of n.deps) {
+      const left = (pending.get(up) ?? 0) - 1
+      pending.set(up, left)
+      if (left === 0) {
+        const upNode = nodeById.get(up)
+        if (upNode) queue.push(upNode)
+      }
+    }
+  }
+  for (const n of nodes) if (!memo.has(n.id)) memo.set(n.id, ownDuration(n))
+  return memo
+}

package/src/graph/default-build.ts

@@ -0,0 +1,19 @@
+import type { TaskConfig } from '../config.js'
+
+/**
+ * The `build` a project gets when neither its config nor a plugin declared
+ * one (2026-10-04): a group behind `^build`, keyed on every file of
+ * the project. A package consumed as source then carries its files to every
+ * dependent behind `^build`, in the key and in `--affected`, and the chain
+ * through it to deeper builds holds. A keyed group, as a config may
+ * declare one (config-schema.ts).
+ */
+export const DEFAULT_BUILD: TaskConfig = Object.freeze({
+  dependsOn: Object.freeze(['^build']),
+  inputs: Object.freeze({ files: Object.freeze(['**']) }),
+})
+
+/** The default `build`, which a menu of the tasks a user declared leaves out. */
+export function isDefaultBuild(task: TaskConfig | undefined): boolean {
+  return task === DEFAULT_BUILD
+}

package/src/graph/definition.ts

@@ -0,0 +1,38 @@
+// What a task is, for its history: a task whose command changed under the
+// same name is a new task, and its timings start over (2026-10-23: "task
+// can disappear and appear as a completely new one with the same name").
+// Only what decides what the command costs: the command and the values it
+// is given (`env.define`). Inputs, outputs, cache, sandbox grants, timeout,
+// description and dependencies change no cost, so editing them keeps the
+// history.
+
+import { xxh3hex } from '../util/index.js'
+import type { TaskNode } from './task-graph.js'
+
+const memo = new WeakMap<TaskNode, string | undefined>()
+
+/** The task's definition hash; undefined for one with no command (a group). */
+export function taskDefinition(node: TaskNode): string | undefined {
+  if (memo.has(node)) return memo.get(node)
+  const exec = node.config.exec
+  const def =
+    exec?.command === undefined
+      ? undefined
+      : xxh3hex(
+          `${node.id}\0${exec.command}\0${JSON.stringify(
+            Object.entries(exec.env?.define ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+          )}`,
+        )
+  memo.set(node, def)
+  return def
+}
+
+/** Each task's definition (`taskDefinition`) by id, groups left out: what a history reader matches rows to. */
+export function taskDefinitions(nodes: Iterable<TaskNode>): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const n of nodes) {
+    const def = taskDefinition(n)
+    if (def !== undefined) out.set(n.id, def)
+  }
+  return out
+}

package/src/graph/folds.ts

@@ -2,14 +2,14 @@
 // alone: the hash path, the sandbox's keyed set and `vx lock`'s
 // input-overlap rule read this one selection, so they cannot drift.
 
-import { UserError } from '../util/index.js'
 import {
+  UserError,
   DependencySpecError,
   compileTaskPattern,
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
-} from './dependency-spec.js'
+} from '../util/index.js'
 import type { TaskNode } from './task-graph.js'
 
 /**
@@ -49,7 +49,6 @@ export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>)
     if (filter === undefined || filter.length === 0) continue
     const deps = keyedDeps(node).flatMap((id) => nodes.get(id) ?? [])
     const groups = deps.filter(isGroupTask)
-    if (groups.length === 0) continue
     for (const raw of filter) {
       const spec = parseSpec(raw, node.id)
       if (spec.negated) continue
@@ -63,16 +62,50 @@ export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>)
           `${node.id}: inputs.tasks: '${raw}' matches ${member.id} only through the group ${group.id}, so it selects nothing; name '${group.taskName}' or depend on ${member.id} directly`,
         )
       }
+      if (namesNoDependency(spec, node.config.dependsOn ?? [])) {
+        const named = deps.map((d) => d.id).join(', ') || 'none'
+        throw new UserError(
+          `${node.id}: inputs.tasks: '${raw}' names none of its dependencies (${named}), so it selects nothing and the key would not move with them; fix the name, or use [] to decouple on purpose`,
+        )
+      }
     }
   }
 }
 
+/**
+ * An exact filter that matched no dependency, where no `dependsOn` entry
+ * may resolve to nothing for it. The load pairs a `pkg#task` entry, or a
+ * `pkg#task` dependency, with any form whose task half matches, since it
+ * cannot tell this project's name from another's
+ * (`assertFilterNamesDeclaredDeps`), so `['nope#build']` over
+ * `dependsOn: ['build']`, `['gen']` over `['b#gen']` and `['^gen']` over
+ * this project's own `['a#gen']` each selected nothing and the key stopped
+ * moving with the dependency: a stale hit. A `^` entry or a pattern naming
+ * the task may match nothing in a preset's project, as a `^build` filter
+ * may, so it lets the entry through.
+ */
+function namesNoDependency(spec: DependencySpec, dependsOn: readonly string[]): boolean {
+  if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps' || isTaskPattern(spec.task))
+    return false
+  if (spec.kind === 'cross' && isTaskPattern(spec.project)) return false
+  return !dependsOn.some((raw) => {
+    let d: DependencySpec
+    try {
+      d = parseDependencySpec(raw, 'dependsOn')
+    } catch {
+      return false
+    }
+    if (d.kind !== 'self' && d.kind !== 'deps' && d.kind !== 'cross') return false
+    return (d.kind === 'deps' || isTaskPattern(d.task)) && nameMatcher(d.task)(spec.task)
+  })
+}
+
 function parseSpec(raw: string, selfTaskId: string): DependencySpec {
   try {
-    return parseDependencySpec(raw)
+    return parseDependencySpec(raw, 'inputs.tasks')
   } catch (err) {
     if (err instanceof DependencySpecError) {
-      throw new UserError(`${selfTaskId}: inputs.tasks: ${err.message}`)
+      throw new UserError(`${selfTaskId}: ${err.message}`)
     }
     throw err
   }

package/src/graph/index.ts

@@ -7,7 +7,7 @@ export {
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
-} from './dependency-spec.js'
+} from '../util/index.js'
 export {
   type FoldCandidate,
   foldedDeps,
@@ -16,7 +16,10 @@ export {
   refuseFiltersThroughGroups,
   selectFoldedDeps,
 } from './folds.js'
+export { DEFAULT_BUILD, isDefaultBuild } from './default-build.js'
 export { computeReverseDepCount } from './priorities.js'
+export { criticalPath } from './critical-path.js'
+export { taskDefinition, taskDefinitions } from './definition.js'
 export {
   type ContinueMode,
   deadServerBehind,

package/src/graph/priorities.ts

@@ -1,6 +1,6 @@
 // The ready-queue ranking, apart from the scheduler that uses it. Nothing
 // here touches the platform: the Learn page's scheduler simulator
-// (packages/vx-docs, through packages/vx-bench/schedule-policy.ts) bundles
+// (private/vx-docs, through private/vx-bench/schedule-policy.ts) bundles
 // these two functions for the browser, and an import of the scheduler would
 // bring `util/` and its load-time `Bun` reads with them.
 
@@ -10,7 +10,8 @@ import type { TaskNode } from './task-graph.js'
  * `computeReverseDepCount` for a run with a restore tier (item 754). A
  * restore-tier task is a confirmed hit that never waits on its deps, so it
  * blocks only the exec-tier tasks that depend on it: an exec-tier task's
- * count is taken over the exec tier alone, which is exact, and a restore's
+ * count is taken over the exec tier, an edge through a restore it holds
+ * back counted too, and a restore's
  * is the sum over its direct exec-tier dependents of one plus theirs, plus
  * the weight of each restore that depends on it, so a restore that feeds
  * pending work, directly or through other restores, still goes first. A warm run's exec tier
@@ -37,16 +38,22 @@ export function tieredReverseDepCount(
     for (const id of nodes.keys()) zeros.set(id, 0)
     return zeros
   }
+  // A restore releases its dependents only once its own deps have settled
+  // (scheduler.ts, item 963), so an exec task under a restore blocks what
+  // that restore feeds: e1 → r → e2 held e2 until e1 ran, and e1 ranked 0
+  // behind every idle task. The exec tier is counted with each restore dep
+  // replaced by the exec tasks it waits on, through restores.
+  const view = execThroughRestores(nodes, exec, restoreTier)
   // An exec tier with no edge inside it (a warm run's groups) counts 0
   // everywhere: no closure to build.
   let linked = false
-  for (const node of exec.values()) {
-    if (node.deps.some((d) => exec.has(d))) {
+  for (const node of view.values()) {
+    if (node.deps.some((d) => view.has(d))) {
       linked = true
       break
     }
   }
-  const counts = linked ? computeReverseDepCount(exec) : new Map<string, number>()
+  const counts = linked ? computeReverseDepCount(view) : new Map<string, number>()
   if (!linked) for (const id of exec.keys()) counts.set(id, 0)
   let feeds = false
   for (const node of exec.values()) {
@@ -89,6 +96,52 @@ export function tieredReverseDepCount(
   return counts
 }
 
+/**
+ * The exec tier with each restore dep replaced by the exec tasks that
+ * restore waits on (directly or through other restores). A node with no
+ * restore dep is itself; the restore tier is walked once, post-order.
+ */
+function execThroughRestores(
+  nodes: Map<string, TaskNode>,
+  exec: Map<string, TaskNode>,
+  restoreTier: ReadonlySet<string>,
+): Map<string, TaskNode> {
+  const isRestore = (id: string): boolean => restoreTier.has(id) && nodes.has(id)
+  const below = new Map<string, readonly string[]>()
+  const belowOf = (root: string): readonly string[] => {
+    const stack: Array<[id: string, depsDone: boolean]> = [[root, false]]
+    while (stack.length > 0) {
+      const [id, depsDone] = stack.pop()!
+      if (below.has(id)) continue
+      const deps = nodes.get(id)!.deps
+      if (!depsDone) {
+        stack.push([id, true])
+        for (const d of deps) if (isRestore(d) && !below.has(d)) stack.push([d, false])
+        continue
+      }
+      const out = new Set<string>()
+      for (const d of deps) {
+        if (exec.has(d)) out.add(d)
+        else for (const e of below.get(d) ?? []) out.add(e)
+      }
+      below.set(id, [...out])
+    }
+    return below.get(root)!
+  }
+  let view: Map<string, TaskNode> | undefined
+  for (const node of exec.values()) {
+    if (!node.deps.some(isRestore)) continue
+    const deps = new Set<string>()
+    for (const d of node.deps) {
+      if (isRestore(d)) for (const e of belowOf(d)) deps.add(e)
+      else deps.add(d)
+    }
+    view ??= new Map(exec)
+    view.set(node.id, { ...node, deps: [...deps] })
+  }
+  return view ?? exec
+}
+
 /**
  * Compute, for each task in the graph, how many OTHER tasks are
  * transitively blocked on it. Tasks with the highest count are the
@@ -98,7 +151,11 @@ export function tieredReverseDepCount(
  * dependents only (`calculateReverseDeps` in
  * `packages/nx/src/tasks-runner/utils.ts`, read 2026-09-24).
  */
-export function computeReverseDepCount(nodes: ReadonlyMap<string, TaskNode>): Map<string, number> {
+export function computeReverseDepCount(
+  nodes: ReadonlyMap<string, TaskNode>,
+  /** Count only these dependents (the exec tier); every one when absent. */
+  counted?: ReadonlyMap<string, unknown>,
+): Map<string, number> {
   // Exact transitive-dependent COUNTS need closure SETS (diamonds
   // double-count under naive summing). Set-of-strings closures are
   // O(N²) entries and took 8.5s on a 1090-package, 100-layer repo;
@@ -145,6 +202,10 @@ export function computeReverseDepCount(nodes: ReadonlyMap<string, TaskNode>): Ma
   // half the words of indexing by insertion order on a layered graph.
   const pos = new Int32Array(n)
   for (let t = 0; t < tail; t++) pos[topo[t]!] = t
+  const mask = new Uint32Array(words)
+  if (counted === undefined) mask.fill(0xffffffff)
+  else
+    for (let t = 0; t < tail; t++) if (counted.has(ids[topo[t]!]!)) mask[t >>> 5]! |= 1 << (t & 31)
   const closure = new Uint32Array(n * words)
   const counts = new Map<string, number>()
   for (let t = tail - 1; t >= 0; t--) {
@@ -158,7 +219,7 @@ export function computeReverseDepCount(nodes: ReadonlyMap<string, TaskNode>): Ma
     }
     let count = 0
     for (let w = t >>> 5; w < words; w++) {
-      let v = closure[base + w]!
+      let v = closure[base + w]! & mask[w]!
       v = v - ((v >>> 1) & 0x55555555)
       v = (v & 0x33333333) + ((v >>> 2) & 0x33333333)
       count += (((v + (v >>> 4)) & 0x0f0f0f0f) * 0x01010101) >>> 24
@@ -240,11 +301,16 @@ export function mergePriorities(
   // Baseline reverse-deps counts are bounded by N; scale the override so
   // it sorts above the baseline for any node it covers, and add the
   // baseline as a tie-break for parity within the override set.
+  // The lowest weight maps to one SCALE, not to 0: a weight of 0 (a p50
+  // that rounds to 0 ms) or below otherwise tied or sank under the
+  // unscored nodes it is meant to outrank.
   const SCALE = 1 << 20
+  let lo = 0
+  for (const w of overrides.values()) if (w < lo) lo = w
   const out = new Map(baseline)
   for (const [id, w] of overrides) {
     const b = baseline.get(id) ?? 0
-    out.set(id, w * SCALE + b)
+    out.set(id, (w - lo + 1) * SCALE + b)
   }
   return out
 }