@vzn/vx 0.0.16 → 0.0.21

package/src/util/tail.ts

@@ -0,0 +1,66 @@
+// Bounded head-evicting tail for one stream of one still-running task.
+//
+// A PERSISTENT task (dev server, watcher, daemon) is unbounded by
+// construction: unlike a one-shot command, nothing about it terminating
+// bounds how much it writes. Anything that accumulates its output therefore
+// needs a cap, and the cap has to be honest — a truncated log that reads as
+// complete is worse than one that says what it lost.
+//
+// `orchestrator/logger.ts` is the sole holder: it registers a tail per
+// persistent task at taskStart and keeps one for the rest of the run, so a
+// single mechanism covers both the pre-ready window and everything after.
+// `exec/runner.ts` used to keep a SECOND pre-ready copy fed from the same
+// chunks that nothing ever read; it was deleted rather than kept in sync,
+// since two copies of this rule is how they drift — one grew a bound and
+// the other did not, which is the defect this file was extracted to close
+// (a never-ready `readyWhen` grew vx's heap ~100 MiB/s with the 64 KiB cap
+// sitting unused, because it was only ever engaged once the task became
+// ready). It stays in `util` because `exec` cannot import `orchestrator`,
+// so a future second holder on that side has somewhere to import from.
+
+/** Per-stream cap on retained output for a task that may never end. */
+export const PERSISTENT_TAIL_CHARS = 64 * 1024
+
+export interface Tail {
+  chunks: string[]
+  chars: number
+  /** Characters evicted from the head. Non-zero means the tail is partial. */
+  dropped: number
+}
+
+export function createTail(): Tail {
+  return { chunks: [], chars: 0, dropped: 0 }
+}
+
+export function appendTail(t: Tail, chunk: string, limit = PERSISTENT_TAIL_CHARS): void {
+  if (chunk.length === 0) return
+  t.chunks.push(chunk)
+  t.chars += chunk.length
+  // Evict WHOLE chunks from the head — no concatenation until the flush
+  // joins once, so a chatty server costs one array push per chunk.
+  while (t.chars > limit && t.chunks.length > 1) {
+    const gone = t.chunks.shift()!
+    t.chars -= gone.length
+    t.dropped += gone.length
+  }
+  // A single chunk over the cap is the one place we copy.
+  if (t.chars > limit) {
+    const only = t.chunks[0]!
+    const keep = only.slice(only.length - limit)
+    t.dropped += only.length - keep.length
+    t.chunks[0] = keep
+    t.chars = keep.length
+  }
+}
+
+/** Join the retained text. The tail keeps its chunks — see `resetTail`. */
+export function tailText(t: Tail): string {
+  return t.chunks.length === 1 ? t.chunks[0]! : t.chunks.join('')
+}
+
+/** Drop everything retained, keeping the tail usable for a new phase. */
+export function resetTail(t: Tail): void {
+  t.chunks.length = 0
+  t.chars = 0
+  t.dropped = 0
+}

package/src/util/timing.ts

@@ -0,0 +1,63 @@
+// Stage timing for the run path, printed to stderr when `VX_TIMING` is set.
+//
+// The CPU profiler attributes a tight loop's cost unreliably and hides
+// where an `await` waited; a stage table answers "where did the warm run
+// go?" directly, and costs one boolean check per mark when off. Marks are
+// cumulative from process start; the table shows each stage's own share.
+
+const enabled = process.env.VX_TIMING !== undefined && process.env.VX_TIMING !== ''
+const t0 = Bun.nanoseconds()
+const marks: Array<[label: string, ns: number]> = []
+
+/** Record the end of a stage. No-op unless `VX_TIMING` is set. */
+export function mark(label: string): void {
+  if (!enabled) return
+  marks.push([label, Bun.nanoseconds() - t0])
+}
+
+const spans = new Map<string, [count: number, ns: number]>()
+const noop = (): void => {}
+
+/**
+ * Time one occurrence of a repeated operation (a per-task probe, a restore):
+ * `const end = span('probe'); …; end()`. Accumulated by label and printed
+ * under the stage table. Returns a shared no-op when off, so the hot path
+ * allocates nothing.
+ */
+export function span(label: string): () => void {
+  if (!enabled) return noop
+  const start = Bun.nanoseconds()
+  return () => {
+    const cur = spans.get(label)
+    const ns = Bun.nanoseconds() - start
+    if (cur === undefined) spans.set(label, [1, ns])
+    else {
+      cur[0]++
+      cur[1] += ns
+    }
+  }
+}
+
+/** Print the stage table (once, at the end of a run). No-op unless enabled. */
+export function printTimings(): void {
+  if (!enabled || marks.length === 0) return
+  const width = Math.max(...marks.map(([l]) => l.length))
+  let prev = 0
+  const lines = ['[vx timing]  stage'.padEnd(width + 14) + '    own   cumulative']
+  for (const [label, ns] of marks) {
+    const own = (ns - prev) / 1e6
+    lines.push(
+      `             ${label.padEnd(width)}  ${own.toFixed(1).padStart(6)}ms  ${(ns / 1e6).toFixed(1).padStart(8)}ms`,
+    )
+    prev = ns
+  }
+  if (spans.size > 0) {
+    lines.push('[vx timing]  accumulated                     total   count')
+    for (const [label, [count, ns]] of [...spans].sort((a, b) => b[1][1] - a[1][1])) {
+      lines.push(
+        `             ${label.padEnd(24)}  ${(ns / 1e6).toFixed(1).padStart(8)}ms  ${String(count).padStart(6)}`,
+      )
+    }
+  }
+  process.stderr.write(lines.join('\n') + '\n')
+}

package/src/util/verbs.ts

@@ -0,0 +1,39 @@
+/**
+ * The verbs the CLI dispatcher (`cli/index.ts`) owns; `stats` is a
+ * deprecated alias of `info` and stays out of hints but is still matched
+ * first. Lives in util rather than cli because the workspace VALIDATOR
+ * refuses a plugin verb that names one of these — a verb core matches
+ * first could never run — and the workspace module cannot import cli.
+ */
+export const CORE_VERBS = [
+  'run',
+  'watch',
+  'cache',
+  'lock',
+  'init',
+  'upgrade',
+  'show',
+  'info',
+  'why',
+  'last',
+  'completions',
+  'help',
+  'version',
+] as const
+
+/** Every word the dispatcher matches before consulting plugins. */
+export const DISPATCHED_VERBS: readonly string[] = [...CORE_VERBS, 'stats']
+
+/**
+ * Verbs core owned once and a package owns now. Not core verbs: a plugin
+ * may declare them, and the dispatcher prints the
+ * pointer only when no declared plugin claimed the name.
+ */
+export const MOVED_VERBS: Readonly<Record<string, string>> = {
+  migrate:
+    'vx migrate moved to @vzn/vx-migrate: run `bunx @vzn/vx-migrate` (turbo.json or an Nx ' +
+    'project graph → vx.config.ts); `vx init` reads package.json scripts',
+  prune:
+    'vx prune was removed (2026-09-11): the Docker-subset verb is not shipped; copy the ' +
+    'workspace and `--filter` the build instead',
+}

package/src/workspace/affected.ts

@@ -1,17 +1,16 @@
 // `--affected` — git-relative project selection.
 //
 // Resolves the set of project names whose files have changed since a
-// given git ref. The diff is `<since>...HEAD` plus working-tree
-// changes (uncommitted edits), so it captures everything you've
-// touched on the current branch.
-//
-// We use `git diff --name-only <since>` which by default compares the
-// `<since>` commit to the working tree — i.e. commits-from-`<since>`
-// + index + unstaged. Matches Turbo's `[<since>]` filter semantics.
+// given git ref: `git diff --name-only <merge-base(since, HEAD)>`, which
+// compares that commit to the working tree — commits on this branch +
+// index + unstaged — so it captures everything you touched and nothing
+// the base branch moved on with. Matches Turbo's `[<since>]` semantics.
 
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { LOCKFILE_NAME } from './lockfile.js'
+import { configImportOwners } from './config-imports.js'
+import { WORKSPACE_FINGERPRINT_FILES } from './fingerprint.js'
 import type { ProjectMeta } from './workspace.js'
 
 export interface AffectedArgs {
@@ -19,6 +18,39 @@ export interface AffectedArgs {
   /** Git ref / commit / branch to compare against. Required. */
   since: string
   projects: readonly ProjectMeta[]
+  /**
+   * Which projects declare a `cache.inputs.workspaceFiles` glob matching one of
+   * these workspace-relative paths.
+   *
+   * A workspace-anchored glob is the documented escape hatch for shared files
+   * that belong to NO project, so mapping changed paths to project directories
+   * structurally cannot see it — the path resolves to no project and the run
+   * selects nothing for a change that re-keyed the task.
+   *
+   * Answering needs the RESOLVED configs, which selection runs before loading;
+   * that ordering is what left this open. It is resolved by asking only when
+   * the question can matter: this is called ONLY with paths that belong to no
+   * project, so a run whose every change is inside a project — the common case
+   * — never invokes it and pays nothing.
+   */
+  workspaceGlobOwners?: (orphanPaths: readonly string[]) => Promise<Iterable<string>>
+  /**
+   * The fingerprint files a plugin claims (`VxPlugin.fingerprint`) and its
+   * answer for a change to one. Resolved lazily: loading the workspace
+   * file costs an evaluation, and a diff that touches no fingerprint file
+   * — the common one — never needs it.
+   */
+  fingerprintClaims?: () => Promise<FingerprintClaims>
+}
+
+export interface FingerprintClaims {
+  readonly files: ReadonlySet<string>
+  /** Project names a change to a claimed file affects; `undefined` = all. */
+  affected(change: {
+    file: string
+    before: Uint8Array | null
+    after: Uint8Array | null
+  }): Promise<ReadonlySet<string> | undefined>
 }
 
 /**
@@ -27,17 +59,188 @@ export interface AffectedArgs {
  * or `<since>` doesn't resolve to a commit.
  */
 export async function affectedProjects(args: AffectedArgs): Promise<Set<string>> {
+  // The base reaches git as an argument, never through a shell, so `$(…)`
+  // is opaque — but an option-like value is not: `--output=<path>` is a
+  // real `git diff` option and an arbitrary file write. This is a security
+  // boundary, so it is a check that knows it is one, before any spawn, and
+  // every git call below also ends its options (`--end-of-options`) so a
+  // second caller cannot lose the guard by accident.
+  if (args.since.length === 0 || args.since.startsWith('-')) {
+    throw new UserError(
+      `git ref "${args.since}" is not a ref: a base cannot be empty or start with "-".`,
+    )
+  }
   await verifyRef(args.workspaceRoot, args.since)
+  // Diff from the MERGE BASE of `since` and HEAD, not from `since` itself:
+  // on a branch whose base has moved on, `git diff <base>` reports every
+  // file OTHER people changed on the base (over-selection that defeats a
+  // CI `--affected`), and hides your own edit when the base later landed
+  // byte-identical content. Turbo and Nx both diff from the merge base;
+  // when there is none (unrelated histories, a detached probe) the ref
+  // itself is the base, as before.
+  const base = await mergeBase(args.workspaceRoot, args.since)
 
-  const proc = Bun.spawn({
+  const [diffed, untracked] = await Promise.all([
     // `--no-renames` is crucial for project-affected detection: with
     // git's auto rename-detection on (the default in modern git), a
     // cross-project `git mv` collapses to a single rename entry that
     // surfaces only the destination path. We'd then miss flagging the
     // source project as affected. Treating renames as delete+add gives
     // us both halves so both projects get correctly marked.
-    cmd: ['git', 'diff', '--no-renames', '--name-only', args.since],
-    cwd: args.workspaceRoot,
+    //
+    // `--relative` prints paths relative to the cwd (the workspace root), NOT
+    // the git repo root. Without it, when the workspace root is a SUBDIR of the
+    // git repo, `git diff` emits repo-root-relative paths (`code/pkg/x`) that
+    // `path.resolve(workspaceRoot, …)` mangles into `<root>/code/…`, matching no
+    // project → the project is silently NOT flagged affected. `--relative` also
+    // (correctly) drops changes ABOVE the workspace, which belong to no project.
+    // No-op when the workspace root IS the git root.
+    //
+    // `-z` because git otherwise C-quotes and octal-escapes any path with a
+    // non-ASCII / `"` / `\` character — the quoted string then resolves to no
+    // project, while the cache-input enumeration (which uses `-z`) sees the
+    // real name and re-keys the task. The two surfaces must agree.
+    gitPaths(args.workspaceRoot, [
+      'diff',
+      '--no-renames',
+      '--relative',
+      '--name-only',
+      '-z',
+      '--end-of-options',
+      base,
+    ]),
+    // `git diff` never reports untracked-but-not-ignored files, but input
+    // enumeration does (`git ls-files --cached --others --exclude-standard`),
+    // so a brand-new source file changes a task's cache key. Union it in or
+    // `--affected` skips a package that genuinely has new work.
+    gitPaths(args.workspaceRoot, ['ls-files', '--others', '--exclude-standard', '-z']),
+  ])
+
+  // vx-lock.json (workspace-root metadata) is excluded like a gitignored
+  // file: re-running `vx lock` must not mark every project affected.
+  const changed = [...diffed, ...untracked].filter((s) => s !== LOCKFILE_NAME)
+
+  // A lockfile or workspace-definition change re-keys EVERY task, because the
+  // workspace fingerprint folds those files into every cache key. Mapping
+  // changed paths to project directories cannot see that — they sit at the
+  // root and belong to no project — so `--affected` selected ZERO projects for
+  // a change that invalidates the entire cache. `vx run test --affected` after
+  // a `pnpm update` exited 0 having run nothing, which is precisely the
+  // failure `docs/cli.md` warns against in the sentence it states as a
+  // principle: "input hashing sees it, so `--affected` must too."
+  //
+  // Selection is not hashed, so widening it here changes no cache key.
+  //
+  // A file a plugin CLAIMS is the exception: the key folds what the plugin
+  // says per project, so selection asks the plugin the same question, with
+  // the bytes at the base ref and in the working tree. Its answer is
+  // unioned with the path-owned projects below; only "cannot tell" widens.
+  const fingerprintChanged = changed.filter((p) => FINGERPRINT_SET.has(p))
+  const claimedOwned = new Set<string>()
+  if (fingerprintChanged.length > 0) {
+    const claims = args.fingerprintClaims === undefined ? undefined : await args.fingerprintClaims()
+    for (const file of fingerprintChanged) {
+      if (claims === undefined || !claims.files.has(file)) {
+        return new Set(args.projects.map((p) => p.name))
+      }
+      const answer = await claims.affected({
+        file,
+        before: await gitBytesAt(args.workspaceRoot, base, file),
+        after: await bytesOrNull(path.join(args.workspaceRoot, file)),
+      })
+      if (answer === undefined) return new Set(args.projects.map((p) => p.name))
+      for (const name of answer) claimedOwned.add(name)
+    }
+  }
+
+  const { owned, orphans } = projectsContaining(args.workspaceRoot, changed, args.projects)
+  for (const name of claimedOwned) owned.add(name)
+
+  // THIRD CHANNEL: a project whose `vx.config.*` IMPORTS a changed file.
+  // Resolved-config hashing folds those values into the key, so the same
+  // sentence above applies — input hashing sees it, so selection must. This
+  // runs on the FULL changed set, not just `orphans`: the common shape is a
+  // config reaching into ANOTHER project (`../../src/index.ts`), whose target
+  // is owned and therefore never an orphan at all.
+  for (const name of await configImportOwners({
+    workspaceRoot: args.workspaceRoot,
+    projects: args.projects,
+    changed,
+    skip: owned,
+  })) {
+    owned.add(name)
+  }
+
+  if (orphans.length === 0 || args.workspaceGlobOwners === undefined) return owned
+  for (const name of await args.workspaceGlobOwners(orphans)) owned.add(name)
+  return owned
+}
+
+/**
+ * Does any `cache.inputs.workspaceFiles` entry in `globs` match `rel`?
+ *
+ * Mirrors `resolveWorkspaceFiles`' partition: a leading `!` is an EXCLUDE, and
+ * with no positive glob nothing matches. Paths are workspace-root-relative and
+ * POSIX-separated, which is the form both git enumeration and the glob
+ * resolver already speak.
+ */
+export function workspaceGlobsMatch(globs: readonly string[], rel: string): boolean {
+  const positive: Bun.Glob[] = []
+  const negative: Bun.Glob[] = []
+  for (const entry of globs) {
+    if (entry.startsWith('!')) negative.push(new Bun.Glob(entry.slice(1)))
+    else positive.push(new Bun.Glob(entry))
+  }
+  if (positive.length === 0) return false
+  if (!positive.some((g) => g.match(rel))) return false
+  return !negative.some((g) => g.match(rel))
+}
+
+/**
+ * The fingerprint files as workspace-root-relative paths. Read from the same
+ * constant the fingerprint itself walks, so a new lockfile format cannot be
+ * taught to one surface and not the other.
+ */
+const FINGERPRINT_SET: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FILES)
+
+/**
+ * A root file's bytes at `ref`, or null when the ref has no such file.
+ * `./` anchors the path to the cwd (the workspace root) rather than the
+ * repository root, for a workspace that is a subdirectory of its repo.
+ */
+async function gitBytesAt(
+  workspaceRoot: string,
+  ref: string,
+  file: string,
+): Promise<Uint8Array | null> {
+  const proc = Bun.spawn({
+    cmd: ['git', 'show', '--end-of-options', `${ref}:./${file}`],
+    cwd: workspaceRoot,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [bytes, stderr, exit] = await Promise.all([
+    new Response(proc.stdout).bytes(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (exit === 0) return bytes
+  // "exists on disk but not in <ref>" and "path does not exist in <ref>"
+  // are the file being absent at the ref; anything else is git failing.
+  if (/does not exist in|exists on disk, but not in/.test(stderr)) return null
+  throw new UserError(`git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`)
+}
+
+async function bytesOrNull(file: string): Promise<Uint8Array | null> {
+  const f = Bun.file(file)
+  return (await f.exists()) ? await f.bytes() : null
+}
+
+/** Run a NUL-separated path-listing git command from the workspace root. */
+async function gitPaths(workspaceRoot: string, cmd: string[]): Promise<string[]> {
+  const proc = Bun.spawn({
+    cmd: ['git', ...cmd],
+    cwd: workspaceRoot,
     stdout: 'pipe',
     stderr: 'pipe',
   })
@@ -45,13 +248,9 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   const stderr = await new Response(proc.stderr).text()
   const exit = await proc.exited
   if (exit !== 0) {
-    throw new UserError(`git diff failed (exit ${exit}): ${stderr.trim()}`)
+    throw new UserError(`git ${cmd[0]} failed (exit ${exit}): ${stderr.trim()}`)
   }
-
-  // vx-lock.json (workspace-root metadata) is excluded like a gitignored
-  // file: re-running `vx lock` must not mark every project affected.
-  const changed = stdout.split('\n').filter((s) => s.length > 0 && s !== LOCKFILE_NAME)
-  return projectsContaining(args.workspaceRoot, changed, args.projects)
+  return stdout.split('\0').filter((s) => s.length > 0)
 }
 
 /**
@@ -72,25 +271,47 @@ export async function defaultAffectedBase(workspaceRoot: string): Promise<string
   return 'HEAD~1'
 }
 
+/** `git merge-base <ref> HEAD`, or `ref` itself when the two share no ancestor. */
+async function mergeBase(workspaceRoot: string, ref: string): Promise<string> {
+  const proc = Bun.spawn({
+    cmd: ['git', 'merge-base', '--end-of-options', ref, 'HEAD'],
+    cwd: workspaceRoot,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [out, exit] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+  const sha = out.trim()
+  return exit === 0 && sha.length > 0 ? sha : ref
+}
+
 async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
   const proc = Bun.spawnSync({
-    cmd: ['git', 'rev-parse', '--verify', '--quiet', ref],
+    cmd: ['git', 'rev-parse', '--verify', '--quiet', '--end-of-options', ref],
     cwd: workspaceRoot,
     stdout: 'pipe',
     stderr: 'pipe',
   })
-  if (proc.exitCode !== 0) {
+  if (proc.exitCode === 0) return
+  // `--verify --quiet` exits 1 for "that ref does not exist" and 128 for
+  // "git could not run here at all" (not a repository, corrupt objects,
+  // permissions). Reporting the second as a ref problem sends you hunting
+  // for a branch name when the real fault is the repository — so only exit
+  // 1 gets the ref message; anything else surfaces what git actually said.
+  const stderr = new TextDecoder().decode(proc.stderr).trim()
+  if (proc.exitCode !== 1) {
     throw new UserError(
-      `git ref "${ref}" did not resolve. Pass a branch or commit you have locally.`,
+      `git rev-parse failed (exit ${proc.exitCode}) in ${workspaceRoot}` +
+        (stderr.length > 0 ? `: ${stderr}` : ''),
     )
   }
+  throw new UserError(`git ref "${ref}" did not resolve. Pass a branch or commit you have locally.`)
 }
 
 function projectsContaining(
   workspaceRoot: string,
   changedRelPaths: readonly string[],
   projects: readonly ProjectMeta[],
-): Set<string> {
+): { owned: Set<string>; orphans: string[] } {
   // Index projects by their (canonical) dir, then for each changed path walk
   // its ancestor dirs bottom-up until one is a project dir. The FIRST hit is
   // the DEEPEST containing project — so a nested project still wins over its
@@ -100,19 +321,25 @@ function projectsContaining(
   // pays for.
   const dirToName = new Map<string, string>()
   for (const p of projects) dirToName.set(p.dir, p.name)
-  const out = new Set<string>()
+  const owned = new Set<string>()
+  // Paths that belong to no project. Only these can reach a task through a
+  // workspace-anchored glob, so they are the exact set worth asking about.
+  const orphans: string[] = []
   for (const rel of changedRelPaths) {
     let dir = path.resolve(workspaceRoot, rel)
+    let hit = false
     for (;;) {
       const name = dirToName.get(dir)
       if (name !== undefined) {
-        out.add(name)
+        owned.add(name)
+        hit = true
         break
       }
       const parent = path.dirname(dir)
       if (parent === dir) break // reached the filesystem root
       dir = parent
     }
+    if (!hit) orphans.push(rel)
   }
-  return out
+  return { owned, orphans }
 }