@vzn/vx 0.0.612 → 0.0.614

package/package.json

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

package/src/cli/help.ts

@@ -210,7 +210,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     "  vx show <pkg>#<task> Print a single task's resolved config.",
     '  vx show <task>       That task in every project declaring it.',
     "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
-    '      --affected[=<ref>]  Only what `vx run --affected` selects: changed and dependents.',
+    "      --affected[=<ref>]  A task's projects `vx run <task> --affected` runs; no task:",
+    '                       the changed projects and their dependents.',
     '      --format <fmt>   pretty (default) | json.',
     '  vx info              Workspace doctor: vx/bun/git versions, project +',
     '                       task counts, cache dir/entries/size, recent runs,',

package/src/cli/select.ts

@@ -360,6 +360,10 @@ export async function resolveFilters(
 
   const unmatched: string[] = []
   const emptyWalks: string[] = []
+  // The `[<since>]` includes whose diff itself matched nothing: only then is
+  // "nothing affected" the fact. A diff that matched, then lost every
+  // project to an exclusion or an empty walk, says which (X-146).
+  const emptyDiffs = new Set<(typeof parsed)[number]>()
   const selected = applyFilters({
     filters: parsed,
     projects,
@@ -371,11 +375,12 @@ export async function resolveFilters(
     // matched nothing is worth flagging as a probable typo.
     onNoMatch: (f) => {
       if (f.gitSince === undefined) unmatched.push(f.raw)
+      else emptyDiffs.add(f)
     },
     // A pattern that matched, with nothing on the walk it asked for: the
     // fact to say, where "no projects matched" read as a typo (item 1030).
     onEmptyWalk: (f, matched) => {
-      if (f.negate || f.gitSince !== undefined) return
+      if (f.negate) return
       const which = matched.join(', ')
       emptyWalks.push(
         f.onlyDeps
@@ -389,28 +394,35 @@ export async function resolveFilters(
     // commit must not red `vx run … --affected=origin/main`. Only report an
     // error when the user named something concrete that failed to resolve.
     const includes = parsed.filter((f) => !f.negate)
+    // Every pattern matched and an exclusion took them all back: "no
+    // projects matched filter(s): one, !one" read as a typo of `one`.
+    const negations = parsed.filter((f) => f.negate).map((f) => f.raw)
+    const excluded = `${negations.join(', ')} excluded every project the other filters matched`
     if (includes.length > 0 && includes.every((f) => f.gitSince !== undefined)) {
-      const refs = includes.map((f) => f.gitSince).join(', ')
-      // A base that IS HEAD (a single-branch clone whose `origin/HEAD` is
-      // the branch under test) can never mark anything affected, and this
-      // exit-0 note was the only sign (CI persona, 2026-09-16). Say so.
-      const self = includes.find((f) => refIsHead(root, f.gitSince!))
-      const hint =
-        self === undefined
-          ? ''
-          : ` — ${self.gitSince} is HEAD itself: compare with the branch you merge into (--affected=origin/main) or the previous commit (--affected=HEAD~1)`
-      return { empty: `nothing affected since ${refs}${hint}` }
+      if (includes.every((f) => emptyDiffs.has(f))) {
+        const refs = includes.map((f) => f.gitSince).join(', ')
+        // A base that IS HEAD (a single-branch clone whose `origin/HEAD` is
+        // the branch under test) can never mark anything affected, and this
+        // exit-0 note was the only sign (CI persona, 2026-09-16). Say so.
+        const self = includes.find((f) => refIsHead(root, f.gitSince!))
+        const hint =
+          self === undefined
+            ? ''
+            : ` — ${self.gitSince} is HEAD itself: compare with the branch you merge into (--affected=origin/main) or the previous commit (--affected=HEAD~1)`
+        return { empty: `nothing affected since ${refs}${hint}` }
+      }
+      // The diff matched and a walk or an exclusion left nothing: still the
+      // exit-0 outcome (`--affected --filter '!docs'` on a docs-only change
+      // must not red CI), said as what happened (X-146).
+      return {
+        empty: `no projects selected: ${emptyWalks.length > 0 ? emptyWalks.join('; ') : excluded}`,
+      }
     }
     if (unmatched.length === 0 && emptyWalks.length > 0) {
       return { error: `no projects selected: ${emptyWalks.join('; ')}` }
     }
-    // Every pattern matched and an exclusion took them all back: "no
-    // projects matched filter(s): one, !one" read as a typo of `one`.
-    const negations = parsed.filter((f) => f.negate).map((f) => f.raw)
     if (unmatched.length === 0 && negations.length > 0) {
-      return {
-        error: `no projects selected: ${negations.join(', ')} excluded every project the other filters matched`,
-      }
+      return { error: `no projects selected: ${excluded}` }
     }
     // One line, not a warning per pattern and then an error saying the same:
     // the patterns are in the error, and the nearest project name is the

package/src/cli/show.ts

@@ -9,12 +9,19 @@
 import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
-import { isDefaultBuild } from '../orchestrator/index.js'
+import { affectedTaskProjects, isDefaultBuild } from '../orchestrator/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
 import { affectedFilterFor, resolveFilters } from './select.js'
-import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 import {
+  discoverCliProjects,
+  loadCliProjects,
+  loadCliWorkspace,
+  warnToStderr,
+} from './workspace-config.js'
+import {
+  type AffectedChanges,
+  buildPackageGraph,
   findWorkspaceRoot,
   type LoadReads,
   loadWorkspace,
@@ -124,6 +131,9 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   // `turbo ls --filter` / `nx show projects --affected`: the list, and a
   // task's projects, narrowed by the selection `vx run` would make.
   let selected: Set<string> | undefined
+  // A task's projects under `--affected` are the ones whose task the run
+  // keeps: the change reaches another project only along a task edge.
+  let byDiff: { changes: AffectedChanges; outright?: readonly string[] | undefined } | undefined
   if (parsed.filters.length > 0 || parsed.affected !== undefined) {
     if (scope !== 'all') {
       throw new UserError(
@@ -142,6 +152,8 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     if ('error' in r) throw new UserError(`vx show: ${r.error}`)
     if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
     selected = new Set('empty' in r ? [] : r.names)
+    if ('names' in r && r.affected !== undefined)
+      byDiff = { changes: r.affected, outright: r.outright }
   }
   const inSelection = (name: string): boolean => selected === undefined || selected.has(name)
 
@@ -171,7 +183,27 @@ export async function showCmd(args: readonly string[]): Promise<number> {
         `vx show: unknown project or task: "${projectName}"${nx}${suggest(projectName!, [...byName.keys(), ...names], '', 'projects and tasks')}`,
       )
     }
-    const shown = declaring.filter((p) => inSelection(p.name))
+    let shown = declaring.filter((p) => inSelection(p.name))
+    if (byDiff !== undefined) {
+      const ws = await loadCliWorkspace(root)
+      const kept = new Set(
+        await affectedTaskProjects({
+          task: projectName!,
+          candidates: shown.map((p) => p.name),
+          changes: byDiff.changes,
+          outright: byDiff.outright,
+          projects,
+          packageGraph: buildPackageGraph(metas),
+          projectMetas: metas,
+          plugins: ws.plugins,
+          workspaceRoot: root,
+          cacheDir: ws.cacheDir,
+          rules: ws.workspaceConfig?.rules,
+          warn: warnToStderr,
+        }),
+      )
+      shown = shown.filter((p) => kept.has(p.name))
+    }
     process.stdout.write(renderTaskAcross(root, shown, projectName!, parsed.format))
     return 0
   }

package/src/orchestrator/affected-tasks.ts

@@ -4,9 +4,12 @@
 // behind `^build` runs when `ui#build` (or what it depends on) is reached,
 // and a spec edit `ui#build`'s inputs leave out stops at `ui`'s own tasks.
 
+import type { WorkspaceRules } from '../config.js'
 import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
 import {
+  buildTaskGraph,
   compileTaskPattern,
+  expandRequested,
   isGroupTask,
   isTaskPattern,
   parseDependencySpec,
@@ -17,7 +20,12 @@ import {
   type PackageGraph,
   PROJECT_CONFIG_FILENAMES,
   type ProjectEntry,
+  type ProjectMeta,
 } from '../workspace/index.js'
+import { applyGraphStage } from './graph-stage.js'
+import { hasHook } from './plugin-host.js'
+import type { VxPlugin } from './plugin.js'
+import { isDefaultBuild } from './projects.js'
 
 /** Every file in this set re-keys each of its project's tasks, whatever their inputs. */
 const KEYED_BY_EVERY_TASK = new Set(['package.json', ...PROJECT_CONFIG_FILENAMES])
@@ -146,3 +154,60 @@ export function affectedRoots(
   }
   return ids.filter(reaches)
 }
+
+/**
+ * The requested tasks `--affected` keeps, in their order: one the user
+ * named (`pkg#task`), one in a project another include selected outright
+ * (X-10), and one whose closure the change reaches.
+ */
+export function keptByAffected<R extends { project: string; task: string }>(
+  nodes: ReadonlyMap<string, TaskNode>,
+  requested: readonly R[],
+  changes: AffectedChanges,
+  projects: ReadonlyMap<string, ProjectEntry>,
+  packageGraph: PackageGraph,
+  keep: { named?: ReadonlySet<string>; outright?: ReadonlySet<string> } = {},
+): R[] {
+  const ids = requested.map((r) => `${r.project}#${r.task}`)
+  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph))
+  return requested.filter(
+    (r, i) =>
+      keep.named?.has(ids[i]!) === true ||
+      keep.outright?.has(r.project) === true ||
+      reached.has(ids[i]!),
+  )
+}
+
+/**
+ * The projects whose `task` a `vx run <task> --affected` over `candidates`
+ * keeps (`vx show <task> --affected`): the run's graph, `graph` stage and
+ * selection, without opening a cache or keying a task.
+ */
+export async function affectedTaskProjects(args: {
+  task: string
+  candidates: readonly string[]
+  changes: AffectedChanges
+  outright?: readonly string[] | undefined
+  projects: Map<string, ProjectEntry>
+  packageGraph: PackageGraph
+  projectMetas: readonly ProjectMeta[]
+  plugins: readonly VxPlugin[]
+  workspaceRoot: string
+  cacheDir: string
+  rules?: WorkspaceRules | undefined
+  warn: (message: string) => void
+}): Promise<string[]> {
+  const requested = expandRequested([args.task], args.candidates, args.projects, isDefaultBuild)
+  const nodes = buildTaskGraph({
+    projects: args.projects,
+    packageGraph: args.packageGraph,
+    requested,
+    workspaceRoot: args.workspaceRoot,
+    rules: args.rules,
+  })
+  if (hasHook(args.plugins, 'graph')) await applyGraphStage(args.plugins, nodes, args)
+  const kept = keptByAffected(nodes, requested, args.changes, args.projects, args.packageGraph, {
+    outright: new Set(args.outright),
+  })
+  return kept.map((r) => r.project)
+}

package/src/orchestrator/graph-stage.ts

@@ -0,0 +1,48 @@
+// The `graph` stage as a run applies it, shared by `prepareRun` and the
+// CLI's `--affected` task selection (`vx show <task> --affected`), so both
+// select over the graph the hooks leave.
+
+import type { WorkspaceRules } from '../config.js'
+import type { TaskNode } from '../graph/index.js'
+import { type ProjectMeta, validateProjectConfig } from '../workspace/index.js'
+import { applyGraphHooks } from './plugin-host.js'
+import type { VxPlugin } from './plugin.js'
+import { isDefaultBuild } from './projects.js'
+
+export async function applyGraphStage(
+  plugins: readonly VxPlugin[],
+  nodes: Map<string, TaskNode>,
+  args: {
+    workspaceRoot: string
+    cacheDir: string
+    projectMetas: readonly ProjectMeta[]
+    warn: (message: string) => void
+    rules?: WorkspaceRules | undefined
+  },
+): Promise<void> {
+  // A hook edits each node's config in place, as `project` does, so the
+  // edit is held to what the loader accepts from a user: a misspelled
+  // `exec` field ran as an empty command and failed with no reason.
+  const configPaths = new Map(args.projectMetas.map((m) => [m.name, m.configPath]))
+  await applyGraphHooks(
+    plugins,
+    nodes,
+    {
+      workspaceRoot: args.workspaceRoot,
+      cacheDir: args.cacheDir,
+      warn: args.warn,
+      requested: [...nodes.values()].filter((n) => n.requested).map((n) => n.id),
+    },
+    (plugin) => {
+      for (const n of nodes.values()) {
+        if (isDefaultBuild(n.config)) continue
+        const where = configPaths.get(n.projectName) ?? `${n.projectName} (no config file)`
+        validateProjectConfig(
+          { tasks: { [n.taskName]: n.config } },
+          `${where} (after plugin '${plugin.name}')`,
+        )
+      }
+    },
+    args.rules,
+  )
+}

package/src/orchestrator/index.ts

@@ -3,6 +3,7 @@
 
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
+export { affectedTaskProjects } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,

package/src/orchestrator/plugin-host.ts

@@ -34,7 +34,16 @@ function describeValue(v: unknown): string {
   if (v === null) return 'null'
   if (Array.isArray(v)) return 'an array'
   const t = typeof v
-  return t === 'object' ? 'an object' : `a ${t}`
+  if (t !== 'object') return `a ${t}`
+  const proto: unknown = Object.getPrototypeOf(v)
+  if (proto === Object.prototype || proto === null) return 'an object'
+  return `a ${(v as object).constructor?.name || 'class instance'}`
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== 'object' || v === null) return false
+  const proto: unknown = Object.getPrototypeOf(v)
+  return proto === Object.prototype || proto === null
 }
 
 /** Every method `CacheLayer` requires (the optional ones are probed with `?.`). */
@@ -197,7 +206,8 @@ export async function applyProjectHooks(
  * against the LAST plugin that ran: usually the one whose edit made it so,
  * but an earlier plugin's edit that a later one left in place is blamed on
  * the later one, since the structure is not checked between plugins.
- * Each node's task config is (`afterEach`), like the `project` stage's.
+ * Each node's task config is re-validated after EACH plugin (`afterEach`),
+ * like the `project` stage's.
  */
 export async function applyGraphHooks(
   plugins: readonly VxPlugin[],
@@ -271,8 +281,10 @@ export async function applyKeyHooks(
       if (material === undefined) continue
       // `Object.entries` over a string yields its characters as string
       // values, so a plugin returning `'v22'` used to fold parts named
-      // '0', '1', '2' into every key — silently, and permanently.
-      if (typeof material !== 'object' || material === null || Array.isArray(material)) {
+      // '0', '1', '2' into every key — silently, and permanently. A Map or a
+      // class instance keeps its data off own enumerable keys, so
+      // `Object.entries` read it as no material at all: a silent miskey.
+      if (!isRecord(material)) {
         throw new UserError(
           `plugin '${plugin.name}' failed in key: returned ${describeValue(material)}, not a record of string values`,
         )

package/src/orchestrator/prepare.ts

@@ -39,7 +39,6 @@ import {
   resolveCacheDir,
   resolveStoreRoot,
   type ProjectEntry,
-  validateProjectConfig,
 } from '../workspace/index.js'
 import {
   buildTaskGraph,
@@ -51,7 +50,6 @@ import {
   unresolvedRequests,
 } from '../graph/index.js'
 import {
-  applyGraphHooks,
   applyKeyHooks,
   applyScheduleHooks,
   fingerprintClaims,
@@ -68,7 +66,8 @@ import {
   loadWorkspacePlugins,
   type LoadedProjects,
 } from './projects.js'
-import { affectedRoots } from './affected-tasks.js'
+import { keptByAffected } from './affected-tasks.js'
+import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
@@ -527,33 +526,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       })
     let nodes = graphOf(requested)
     const hasGraphHook = hasHook(plugins, 'graph')
-    const graphStage = async (): Promise<void> => {
-      // A hook edits each node's config in place, as `project` does, so the
-      // edit is held to what the loader accepts from a user: a misspelled
-      // `exec` field ran as an empty command and failed with no reason.
-      const configPaths = new Map(projectMetas.map((m) => [m.name, m.configPath]))
-      await applyGraphHooks(
-        plugins,
-        nodes,
-        {
-          workspaceRoot,
-          cacheDir,
-          warn: (m) => log.status(m),
-          requested: [...nodes.values()].filter((n) => n.requested).map((n) => n.id),
-        },
-        (plugin) => {
-          for (const n of nodes.values()) {
-            if (isDefaultBuild(n.config)) continue
-            const where = configPaths.get(n.projectName) ?? `${n.projectName} (no config file)`
-            validateProjectConfig(
-              { tasks: { [n.taskName]: n.config } },
-              `${where} (after plugin '${plugin.name}')`,
-            )
-          }
-        },
-        workspaceConfig?.rules,
-      )
-    }
+    const graphStage = (): Promise<void> =>
+      applyGraphStage(plugins, nodes, {
+        workspaceRoot,
+        cacheDir,
+        projectMetas,
+        warn: (m) => log.status(m),
+        rules: workspaceConfig?.rules,
+      })
     // `--affected` selects over the FINAL graph: an edge or an input a
     // `graph` hook adds moves a key, so the hooks run first, over every
     // candidate, and the selection prunes what they left.
@@ -563,16 +543,13 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     if (options.affected !== undefined) {
       const before = hooksFirst ? new Set(nodes.keys()) : null
       if (hooksFirst) await graphStage()
-      const named = new Set(tasks.filter((t) => t.includes('#')))
-      const outright = new Set(options.selectedOutright)
-      const ids = requested.map((r) => `${r.project}#${r.task}`)
-      const reached = new Set(affectedRoots(nodes, ids, options.affected, projects, packageGraph))
-      const kept = requested.filter(
-        (r, i) => named.has(ids[i]!) || outright.has(r.project) || reached.has(ids[i]!),
-      )
+      const kept = keptByAffected(nodes, requested, options.affected, projects, packageGraph, {
+        named: new Set(tasks.filter((t) => t.includes('#'))),
+        outright: new Set(options.selectedOutright),
+      })
       if (kept.length === 0) return emptyRun('none-affected')
       if (before !== null) {
-        const asked = new Set(ids)
+        const asked = new Set(requested.map((r) => `${r.project}#${r.task}`))
         // What a hook added or asked for is the plugin's choice, kept as it
         // would be on a run without the diff.
         const roots = [

package/src/workspace/config-schema.ts

@@ -254,12 +254,16 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
       }
       for (const cap of PLUGIN_FUNCTION_HOOKS) {
         if (plug[cap] !== undefined && typeof plug[cap] !== 'function') {
-          throw new UserError(`${configPath}: \`plugins[${i}].${cap}\` must be a function`)
+          throw new UserError(
+            `${configPath}: \`plugins[${i}].${cap}\` of plugin '${pkg}' must be a function`,
+          )
         }
       }
       if (plug.commands !== undefined) {
         if (plug.commands === null || typeof plug.commands !== 'object') {
-          throw new UserError(`${configPath}: \`plugins[${i}].commands\` must be an object`)
+          throw new UserError(
+            `${configPath}: \`plugins[${i}].commands\` of plugin '${pkg}' must be an object`,
+          )
         }
         // A list of commands loaded as the verbs `0`, `1`, … that help listed.
         if (Array.isArray(plug.commands)) {
@@ -276,7 +280,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
             typeof c.description !== 'string'
           ) {
             throw new UserError(
-              `${configPath}: \`plugins[${i}].commands.${verb}\` must be { description: string, run: function }`,
+              `${configPath}: \`plugins[${i}].commands.${verb}\` of plugin '${pkg}' must be { description: string, run: function }`,
             )
           }
           // A verb the dispatcher would never reach is refused, not left
@@ -287,10 +291,12 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           // package: two plugins one package exports (`bun()` and `pnpm()`
           // both carry `prune`) are one owner, and the first declared runs.
           // `vx --version` and `vx ''` never reach a plugin: a flag is
-          // core's, and an empty word is no verb (X-21).
-          if (verb.trim() === '' || verb.startsWith('-')) {
+          // core's, and an empty word is no verb (X-21). `vx completions`
+          // writes verbs unquoted into a shell script, so a space or a `$(`
+          // in one would break or inject into the user's rc.
+          if (!/^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(verb)) {
             throw new UserError(
-              `${configPath}: plugin '${plug.name}' declares command '${verb}', which no command line reaches — a verb is a word, not a flag or empty`,
+              `${configPath}: plugin '${plug.name}' declares command '${verb}', which is not a word — a verb is a letter or digit, then letters, digits, ':', '.', '_' or '-'`,
             )
           }
           if ((CORE_VERBS as readonly string[]).includes(verb)) {
@@ -317,7 +323,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           typeof claim.affected !== 'function'
         ) {
           throw new UserError(
-            `${configPath}: \`plugins[${i}].fingerprint\` must be { files: [name, …], affected: function }`,
+            `${configPath}: \`plugins[${i}].fingerprint\` of plugin '${pkg}' must be { files: [name, …], affected: function }`,
           )
         }
         for (const file of claim.files as unknown[]) {
@@ -357,7 +363,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
       // — an empty `{ name }` object is a no-op authoring mistake.
       if (PLUGIN_HOOKS.every((hook) => plug[hook] === undefined)) {
         throw new UserError(
-          `${configPath}: \`plugins[${i}]\` must contribute at least one of ${PLUGIN_HOOKS.join('/')}`,
+          `${configPath}: \`plugins[${i}]\` (plugin '${pkg}') must contribute at least one of ${PLUGIN_HOOKS.join('/')}`,
         )
       }
     }