@vzn/vx 0.0.354 → 0.0.355

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">vx</h1>
 
 <p align="center">
-  <strong>A faster runner for your Turborepo or Nx repo.</strong><br>
-  Keep <code>turbo.json</code> or <code>nx.json</code> and run it unchanged.
+  <strong>The fastest task runner for JS monorepos.</strong><br>
+  Measured against Turborepo and Nx, each in its own native config.
 </p>
 
 <p align="center">
@@ -18,50 +18,20 @@
 
 <!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| 1,090 packages, 3,270 tasks      | vx         | Turborepo  | Nx       |
-| -------------------------------- | ---------- | ---------- | -------- |
-| Cold build: time the runner adds | **9 s**    | 1 min 35 s | 31 min   |
-| Cold build: CPU burned           | **34 s**   | 1 min 13 s | 114 min  |
-| Fully cached run                 | **476 ms** | 760 ms     | 3.59 s   |
-| Overhead per package             | **8 ms**   | 88 ms      | 1,712 ms |
+| 1,090 packages, 3,270 tasks      | vx         | Turborepo                  | Nx                       |
+| -------------------------------- | ---------- | -------------------------- | ------------------------ |
+| Cold build: time the runner adds | **9 s**    | 1 min 35 s (vx 91% faster) | 31 min (vx 99% faster)   |
+| Cold build: CPU burned           | **34 s**   | 1 min 13 s (vx 53% faster) | 114 min (vx 99% faster)  |
+| Fully cached run                 | **476 ms** | 760 ms (vx 37% faster)     | 3.59 s (vx 86% faster)   |
+| Overhead per package             | **8 ms**   | 88 ms (vx 91% faster)      | 1,712 ms (vx 99% faster) |
+
+vx N% faster: vx takes N% less time than that tool (1 − vx ÷ theirs); N% slower: N% more (vx ÷ theirs − 1).
 
 Time added is the wall time over the tasks' own ideal schedule (3 min 38 s).
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 
 <!-- bench:end -->
 
-## Tried on real repos
-
-Public monorepos, each run with its own `turbo.json` or Nx graph against
-the tool it ships with, same machine and tasks per row, medians.
-
-<!-- repos:start — generated by packages/vx-bench/update-site.ts from real-repos.json; do not hand-edit -->
-
-| Repo                                                                | Against | Cold build            | Restore outputs     | Nothing to do          |
-| ------------------------------------------------------------------- | ------- | --------------------- | ------------------- | ---------------------- |
-| [solidjs/solid](https://github.com/solidjs/solid)                   | Turbo   | 40.6 s / 45.5 s       | 66 ms / 127 ms      | 51 ms / 95 ms          |
-| [withastro/astro](https://github.com/withastro/astro)               | Turbo   | 48.0 s / 57.9 s       | 478 ms / 1.43 s     | 249 ms / 1.38 s        |
-| [payloadcms/payload](https://github.com/payloadcms/payload)         | Turbo   | 126.9 s / 127.5 s     | 3.44 s / 3.46 s     | 256 ms / **237 ms**    |
-| [medusajs/medusa](https://github.com/medusajs/medusa)               | Turbo   | 308 s / 315 s         | 3.86 s / 7.16 s     | 947 ms / 3.29 s        |
-| [n8n-io/n8n](https://github.com/n8n-io/n8n)                         | Turbo   | 137.2 s / **133.7 s** | 8.27 s / 12.5 s     | 842 ms / 1.36 s        |
-| [calcom/cal.com](https://github.com/calcom/cal.com)                 | Turbo   | 245.7 s / 250.7 s     | 17.4 s / 19.9 s     | 14.7 s / 18.5 s        |
-| [unocss/unocss](https://github.com/unocss/unocss)                   | Turbo   | 45.1 s / 47.3 s       | 859 ms / **185 ms** | 770 ms / **126 ms**    |
-| [vueuse/vueuse](https://github.com/vueuse/vueuse)                   | Turbo   | 21.4 s / 29.2 s       | 263 ms / **128 ms** | 246 ms / **51–161 ms** |
-| [t3-oss/create-t3-turbo](https://github.com/t3-oss/create-t3-turbo) | Turbo   | 27.2 s / 29.6 s       | 199 ms / 340 ms     | 174 ms / 342 ms        |
-| [TanStack/query](https://github.com/TanStack/query)                 | Nx      | 34.6 s / 37.1 s       | 910 ms / 1.62 s     | 291 ms / 1.60 s        |
-| [strapi/strapi](https://github.com/strapi/strapi)                   | Nx      | 238.2 s / 245.7 s     | 1.61 s / 3.94 s     | 341 ms / 4.02 s        |
-| [novuhq/novu](https://github.com/novuhq/novu)                       | Nx      | 291.2 s / 299.4 s     | 3.10 s / 9.05 s     | 655 ms / 8.55 s        |
-| [TanStack/router](https://github.com/TanStack/router)               | Nx      | 123.0 s / 138.0 s     | 1.27 s / 3.82 s     | 626 ms / 3.91 s        |
-| [refinedev/refine](https://github.com/refinedev/refine)             | Nx      | 96.2 s / 105.9 s      | 1.06 s / 1.19 s     | 303 ms / 1.16 s        |
-
-vx first, theirs second; **bold** marks the other tool winning. These
-rows ran vx without a lock (every config evaluated per run); the harness
-now runs it from a `vx lock` snapshot (`--frozen`). How each
-repo was run, versions, dates and why a tool wins where it does:
-[vx on real Turbo and Nx repos](https://vznjs.github.io/vx/benchmarks/real-repos/).
-
-<!-- repos:end -->
-
 ## Why it is faster
 
 - **Nothing boots per task.** No daemon, no Node process per task: vx
@@ -71,46 +41,20 @@ repo was run, versions, dates and why a tool wins where it does:
 - **One pass over the repo.** One git walk per run; each stat and
   lookup happens once.
 
-## Try it on your repo
-
-In a Turborepo or Nx workspace:
-
-```sh
-npm install -D @vzn/vx @vzn/vx-migrate
-npx vx init                 # writes vx.workspace.ts, below; nothing else
-npx vx run build --all      # your turbo.json or Nx targets, run by vx
-npx vx run build --all      # again: up-to-date in milliseconds
-```
-
-The one file `vx init` writes (in an Nx repo, `nx` for `turbo`):
-
-```ts
-import type { WorkspaceConfig } from '@vzn/vx/config'
-import { turbo } from '@vzn/vx-migrate'
-
-export default { plugins: [turbo()] } satisfies WorkspaceConfig
-```
-
-Nothing is rewritten. `@vzn/vx-migrate` is not on npm yet (first publish
-pending); [`examples/turbo`](examples/turbo) runs this setup, and
-`packages/vx/tests/try-it.unsafe.test.ts` runs these exact lines on a Turbo
-and an Nx repo, on every commit. Which `turbo.json`, `nx.json` and `project.json` keys vx honours,
-key by key: [Turbo and Nx config support](https://vznjs.github.io/vx/compare/turbo-nx-support/).
-
 ## Install
 
 ```sh
 npm install -D @vzn/vx     # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
 ```
 
-The package ships a prebuilt binary for Linux and macOS, x64 and arm64
-(Windows via WSL); no Bun needed. The binary alone, from a
+The package ships a prebuilt binary for Linux and macOS, x64 and arm64;
+no Bun needed. The binary alone, from a
 [release](https://github.com/vznjs/vx/releases), needs no Node either.
+Windows: use WSL.
 
 ## Quick start
 
-In a git repo with a `package.json` workspace and no `turbo.json` or
-`nx.json` (those get the one file above):
+In a git repo with a `package.json` workspace:
 
 ```sh
 npx vx init               # a vx.config.ts per package, from its scripts
@@ -151,13 +95,13 @@ runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/)
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
 [playground](https://vznjs.github.io/vx/playground/) (the planner, in your browser).
 
-## Configs of your own
+## Coming from Turbo or Nx
 
-When you want them, `bunx @vzn/vx-migrate` writes a `vx.config.ts` per
-package from `turbo.json` or the Nx graph. They derive the same cache
-keys, so what `turbo()` cached still hits. `turboCache()` and `nxCache()`
-keep your Turbo or Nx remote cache. [Parity map](packages/vx/docs/parity.md) ·
-[migration guide](https://vznjs.github.io/vx/guides/migrate/).
+`bunx @vzn/vx-migrate` writes a `vx.config.ts` per package from
+`turbo.json` or the Nx graph; `vx init` in such a repo writes a
+`vx.workspace.ts` that reads them in place. Either is a temporary start:
+move to native vx config, which is what the numbers above measure.
+[Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## More than speed
 
@@ -197,7 +141,7 @@ machine.
 
 | Package                                                    | What it adds                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Run a Turbo or Nx repo unchanged; write configs; keep its remote cache        |
+| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Migrate from Turbo or Nx: write native configs, keep its remote cache         |
 | [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
 | [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
 | [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |

package/package.json

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

package/src/cache/git-inputs.ts

@@ -556,7 +556,8 @@ export interface BlobSizeMemo {
  * the ones it lacks from one `cat-file` (65 ms over 3,000 loose objects,
  * the whole of the cost, measured 2026-10-02). A smudged (racy) entry
  * records 0 and is hashed from disk. An answer that cannot be read trusts
- * nothing.
+ * nothing. A filter that keeps the size (`tr a-z A-Z`) is not caught: only
+ * a read of every trusted file would be (caching.md, step 12).
  */
 async function dropResizedOids(enumeration: GitEnumeration, memo?: BlobSizeMemo): Promise<void> {
   const { trusted, indexed } = enumeration

package/src/config.ts

@@ -24,8 +24,9 @@ export interface WorkspaceConfig {
   cacheRetention?: { olderThan?: string; maxSize?: string }
   /**
    * The git ref a bare `--affected` compares with (`origin/develop`).
-   * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, else
-   * `HEAD~1`. Never folded into a cache key.
+   * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, then the
+   * first of `origin/main`, `origin/master`, `main`, `master` that is not
+   * HEAD, else `HEAD~1`. Never folded into a cache key.
    */
   affectedBase?: string
   /**

package/src/workspace/config-schema.ts

@@ -282,7 +282,14 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
     const where = `${configPath}: tasks.${name}`
     assertTaskName(name, configPath)
     if (!task || typeof task !== 'object') {
-      throw new UserError(`${where} must be an object`)
+      // package.json's shape, `name: 'command'`, was refused without the
+      // object that holds the command.
+      const raw: unknown = task
+      throw new UserError(
+        typeof raw === 'string' && raw.trim() !== ''
+          ? `${where} must be an object — a command is { exec: { command: ${JSON.stringify(raw)} } }`
+          : `${where} must be an object`,
+      )
     }
     assertKnownFields(task, TASK_FIELDS, where)
     const exec = (task as { exec?: unknown }).exec

package/src/workspace/package-graph.ts

@@ -60,7 +60,6 @@ export function buildPackageGraph(
   // insurance against a future rule that does depend on it; it is not
   // what the stability rests on.
   const directDeps = new Map<string, string[]>()
-  const reachDeps = new Map<string, string[]>()
   const order = new Map<string, Set<string>>()
   const peers = new Map<string, Set<string>>()
   const sorted = [...projects].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
@@ -128,22 +127,30 @@ export function buildPackageGraph(
       if (!own.has(peer) && !reaches(peer, p.name)) own.add(peer)
     }
   }
-  for (const p of sorted) {
-    const own = order.get(p.name)!
-    directDeps.set(p.name, [...own].sort())
-    reachDeps.set(p.name, [...new Set([...own, ...peers.get(p.name)!])].sort())
-  }
+  for (const p of sorted) directDeps.set(p.name, [...order.get(p.name)!].sort())
 
-  // Reverse adjacency: who declares X as a workspace dep.
+  // REACH and its reverse (who declares X as a workspace dep) are read only
+  // by the transitive questions below, which an unscoped run never asks:
+  // built on the first one, as the closures are.
+  const reachDeps = new Map<string, string[]>()
   const directDependents = new Map<string, string[]>()
-  for (const [name, deps] of reachDeps) {
-    for (const d of deps) {
-      const arr = directDependents.get(d)
-      if (arr) arr.push(name)
-      else directDependents.set(d, [name])
+  let reachBuilt = false
+  const buildReach = (): void => {
+    if (reachBuilt) return
+    reachBuilt = true
+    for (const p of sorted) {
+      const own = order.get(p.name)!
+      reachDeps.set(p.name, [...new Set([...own, ...peers.get(p.name)!])].sort())
+    }
+    for (const [name, deps] of reachDeps) {
+      for (const d of deps) {
+        const arr = directDependents.get(d)
+        if (arr) arr.push(name)
+        else directDependents.set(d, [name])
+      }
     }
+    for (const arr of directDependents.values()) arr.sort()
   }
-  for (const arr of directDependents.values()) arr.sort()
 
   // Set-union DFS closures are O(P²) entries on dense layered graphs
   // (same disease the scheduler's reachOf had — 68 ms at 1090
@@ -224,6 +231,7 @@ export function buildPackageGraph(
     return (name) => {
       const cached = memo.get(name)
       if (cached) return cached
+      buildReach()
       if (closures === undefined) closures = bitsetClosures(edges)
       if (closures === null) {
         const result = reachableFrom(name, edges)