@vzn/vx 0.0.21 → 0.0.22

package/src/workspace/config-imports.ts

@@ -25,12 +25,119 @@
 //     closure, and the containment channel already selects the project that
 //     owns it.
 
+import { existsSync } from 'node:fs'
 import { realpath } from 'node:fs/promises'
+import { builtinModules } from 'node:module'
 import path from 'node:path'
 import type { ProjectMeta } from './workspace.js'
 
+const BUILTINS = new Set(builtinModules)
+
+/**
+ * One transpiler per loader, made on first use: constructing one costs
+ * 42 µs against 12 µs for the scan itself (measured 2026-09-16), and a
+ * fresh one per config put 1000 cold evaluations 130 ms behind.
+ */
+const transpilers: Partial<Record<'ts' | 'js', Bun.Transpiler>> = {}
+function scanner(loader: 'ts' | 'js'): Bun.Transpiler {
+  return (transpilers[loader] ??= new Bun.Transpiler({ loader }))
+}
+
+/**
+ * Whether Bun's own parser finds an ESM `export` in `source` — the one
+ * syntax that makes Bun evaluate a file as a module whatever else it says.
+ * Without one, a file that touches `module`, `exports`, `require`, `this`
+ * or `__dirname` at the top level is CommonJS to Bun. False on source the
+ * parser refuses: the evaluation names that error.
+ */
+export function hasEsmExport(source: string, loader: 'ts' | 'js'): boolean {
+  try {
+    return scanner(loader).scan(source).exports.length > 0
+  } catch {
+    return false
+  }
+}
+
+/** The package a bare specifier names: `@scope/name` or the first segment. */
+function packageOf(spec: string): string {
+  const parts = spec.split('/')
+  return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]!
+}
+
+const SPECIFIER =
+  /\b(?:from|import)\s*\(?\s*["']([^"'./][^"']*)["']|\brequire\s*\(\s*["']([^"'./][^"']*)["']/g
+
+/** Whether a specifier is one the walk would have to look up at all. */
+function needsLookup(spec: string): boolean {
+  if (spec.includes(':') || BUILTINS.has(spec)) return false
+  return !(spec === '@vzn/vx' || spec.startsWith('@vzn/vx/'))
+}
+
+/**
+ * A textual pass before the transpiler's: its scan costs ~50 µs per config
+ * in situ (1000 cold evaluations: 50 ms, measured 2026-09-16), and most
+ * configs import `@vzn/vx` and nothing else. Every static specifier is a
+ * quoted string after `from`, `import` or `require(`; a candidate found
+ * here is checked exactly by the scan (a comment or a type-only import is
+ * the scan's to drop), and a source with no candidate skips it.
+ */
+function hasBareCandidate(source: string): boolean {
+  SPECIFIER.lastIndex = 0
+  for (let m = SPECIFIER.exec(source); m !== null; m = SPECIFIER.exec(source)) {
+    if (needsLookup(m[1] ?? m[2] ?? '')) return true
+  }
+  return false
+}
+
+/**
+ * The bare specifiers of `source` that no `node_modules/<package>` above
+ * `fromDir` provides — the imports Bun would AUTO-INSTALL from the npm
+ * registry rather than fail, when no `node_modules` exists anywhere above
+ * (measured 2026-09-16: sixteen registry connections and 150 ms before
+ * "cannot find"; with one present, 0 and 1 ms). A config is evaluated in
+ * the user's process with the user's network: a fresh clone before its
+ * install, or a typo, must be a refusal, never a download. Builtins
+ * (`node:fs`, `fs`, `bun:sqlite`) and `@vzn/vx` (served by the core alias
+ * inside the compiled binary) are never in the list; relative and absolute
+ * specifiers resolve by path and are the loader's to refuse.
+ */
+export function unprovidedBareImports(
+  source: string,
+  fromDir: string,
+  loader: 'ts' | 'js',
+): string[] {
+  if (!hasBareCandidate(source)) return []
+  let specifiers: string[]
+  try {
+    specifiers = scanner(loader)
+      .scanImports(source)
+      .map((i) => i.path)
+  } catch {
+    return [] // unparseable: the evaluation names the syntax error
+  }
+  const out: string[] = []
+  for (const spec of specifiers) {
+    if (spec.startsWith('.') || spec.startsWith('/') || !needsLookup(spec)) continue
+    const pkg = packageOf(spec)
+    let dir = path.resolve(fromDir)
+    let provided = false
+    for (;;) {
+      if (existsSync(path.join(dir, 'node_modules', pkg))) {
+        provided = true
+        break
+      }
+      const up = path.dirname(dir)
+      if (up === dir) break
+      dir = up
+    }
+    if (!provided && !out.includes(spec)) out.push(spec)
+  }
+  return out
+}
+
 /**
- * Absolute resolved targets of the RELATIVE specifiers in `source`.
+ * Absolute resolved targets of the RELATIVE specifiers in `source`; one that
+ * does not resolve contributes the paths it names.
  *
  * Paths come back realpath'd, because `Bun.resolveSync` realpaths them — see
  * the caller, which realpaths everything it compares against for exactly that
@@ -40,7 +147,9 @@ import type { ProjectMeta } from './workspace.js'
 function scanLocalImports(source: string, fromDir: string, loader: 'ts' | 'js'): string[] {
   let specifiers: string[]
   try {
-    specifiers = new Bun.Transpiler({ loader }).scanImports(source).map((i) => i.path)
+    specifiers = scanner(loader)
+      .scanImports(source)
+      .map((i) => i.path)
   } catch {
     return [] // unparseable source contributes no edges
   }
@@ -50,9 +159,18 @@ function scanLocalImports(source: string, fromDir: string, loader: 'ts' | 'js'):
     try {
       out.push(Bun.resolveSync(spec, fromDir))
     } catch {
-      // Unresolvable (deleted, typo, extensionless miss) — a config that will
-      // not load cannot be shown to import anything, and failing selection
-      // over it would break a working build.
+      // Unresolvable: most often the change itself deleted or renamed the
+      // target, and the config that imports it is exactly the project the
+      // change broke. The edge is the path the specifier names (and, bare
+      // of an extension, the files Bun would have tried), so the deleted
+      // path in the diff still reaches its importer (item 958). Selection
+      // may widen; it is never hashed.
+      const named = path.resolve(fromDir, spec)
+      out.push(named)
+      if (path.extname(spec) === '') {
+        for (const ext of RESOLVED_EXTENSIONS)
+          out.push(named + ext, path.join(named, 'index' + ext))
+      }
     }
   }
   return out
@@ -92,6 +210,9 @@ async function realDirIndex(projects: readonly ProjectMeta[]): Promise<Map<strin
 
 const TS_EXT = new Set(['.ts', '.mts', '.cts'])
 
+/** The extensions Bun tries for a specifier that names none. */
+const RESOLVED_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json']
+
 /** The deepest project containing `file`, or undefined when none does. */
 function ownerOf(file: string, dirToName: ReadonlyMap<string, string>): string | undefined {
   let dir = path.dirname(file)

package/src/workspace/config-schema.ts

@@ -5,6 +5,7 @@
 // it accepts, and `validateProjectConfig` is the one boundary the loader,
 // the lockfile's frozen path and the plugin `project` stage all cross.
 
+import path from 'node:path'
 import {
   PLUGIN_FUNCTION_HOOKS,
   PLUGIN_HOOKS,
@@ -18,17 +19,67 @@ import {
   MAX_TIMEOUT_MS,
   nearest,
   normalizeGlob,
+  parseDuration,
+  parseSize,
   UserError,
+  BUN_GLOB_WILDCARDS,
 } from '../util/index.js'
-import { WORKSPACE_FINGERPRINT_FILES } from './fingerprint.js'
+import { nonJsonMessage, nonJsonPaths } from './json-data.js'
 
 // Mirrors `WorkspaceConfig` in src/config.ts. Unknown keys are REJECTED for
 // the same reason the task levels reject them: `plugin: [...]` (singular)
 // declared no plugins and ran the workspace bare, `cacheDirectory` left the
 // cache where it was — a config that loads and quietly does nothing it says.
-const WORKSPACE_FIELDS = new Set(['concurrency', 'cacheDir', 'timeout', 'plugins'])
+const WORKSPACE_FIELDS = new Set([
+  'concurrency',
+  'cacheDir',
+  'timeout',
+  'cacheRetention',
+  'plugins',
+])
+
+const RETENTION_FIELDS = new Set(['olderThan', 'maxSize'])
+
+function validateRetention(retention: unknown, configPath: string): void {
+  const where = `${configPath}: \`cacheRetention\``
+  if (retention === null || typeof retention !== 'object' || Array.isArray(retention)) {
+    throw new UserError(`${where} must be { olderThan?: '30d', maxSize?: '10G' }`)
+  }
+  assertKnownFields(retention as Record<string, unknown>, RETENTION_FIELDS, where)
+  const { olderThan, maxSize } = retention as { olderThan?: unknown; maxSize?: unknown }
+  // An empty object would load and evict nothing, which reads as a policy.
+  if (olderThan === undefined && maxSize === undefined) {
+    throw new UserError(`${where} names neither \`olderThan\` nor \`maxSize\``)
+  }
+  if (
+    olderThan !== undefined &&
+    (typeof olderThan !== 'string' || parseDuration(olderThan) === null)
+  ) {
+    throw new UserError(`${where}.olderThan must be a duration like '30d', '12h', '90m' or '45s'`)
+  }
+  if (maxSize !== undefined && (typeof maxSize !== 'string' || parseSize(maxSize) === null)) {
+    throw new UserError(`${where}.maxSize must be a size like '10G', '500MB' or '64KB'`)
+  }
+  // The bounds `vx cache prune` refuses, for the same reason: each evicts
+  // every entry, and here it would do so at the end of every run, the
+  // entries that run just saved included, so nothing ever hits (item 969).
+  if (olderThan !== undefined && parseDuration(olderThan) === 0) {
+    throw new UserError(`${where}.olderThan of 0 evicts every entry after every run`)
+  }
+  if (maxSize !== undefined && parseSize(maxSize) === 0) {
+    throw new UserError(`${where}.maxSize of 0 evicts every entry after every run`)
+  }
+  if (maxSize !== undefined && /^\d+$/.test(maxSize)) {
+    throw new UserError(
+      `${where}.maxSize '${maxSize}' reads as ${maxSize} bytes — give a unit (e.g. '${maxSize}M', '${maxSize}G')`,
+    )
+  }
+}
 
 export function validateWorkspace(config: WorkspaceConfig, configPath: string): void {
+  // No JSON-data rule here, unlike `validateProjectConfig`: `plugins` holds
+  // objects of functions by design, the file is evaluated in-process on
+  // every load (never through the config worker), and no key folds its JSON.
   assertKnownFields(config, WORKSPACE_FIELDS, configPath)
   if (config.concurrency !== undefined) {
     if (
@@ -53,6 +104,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     }
     assertTimeoutInRange(config.timeout, `${configPath}: \`timeout\``)
   }
+  if (config.cacheRetention !== undefined) validateRetention(config.cacheRetention, configPath)
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
@@ -150,11 +202,20 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           )
         }
         for (const file of claim.files as unknown[]) {
-          // A name core never folds has nothing to take out; claiming it
-          // would read as covered while the plugin's material is all there is.
-          if (typeof file !== 'string' || !WORKSPACE_FINGERPRINT_FILES.includes(file)) {
+          // A bare name at the workspace root: a lockfile core folds (taken
+          // out of the fingerprint), or a root file the plugin's stages read
+          // (`turbo.json`: nothing to take out; `--affected` and `vx watch`
+          // ask the claimant about it, item 961). A path is refused: the
+          // root arm `vx watch` keeps is not recursive.
+          if (
+            typeof file !== 'string' ||
+            file === '' ||
+            file === '.' ||
+            file === '..' ||
+            /[/\\]/.test(file)
+          ) {
             throw new UserError(
-              `${configPath}: plugin '${plug.name}' claims fingerprint file ${JSON.stringify(file)}, which core does not fold — one of ${WORKSPACE_FINGERPRINT_FILES.join(', ')}`,
+              `${configPath}: plugin '${plug.name}' claims fingerprint file ${JSON.stringify(file)}, which is not a file name at the workspace root`,
             )
           }
           const owner = fileClaimants.get(file)
@@ -186,6 +247,12 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
  * back from `vx-lock.json` (a hand-editable file — same boundary).
  */
 export function validateProjectConfig(config: ProjectConfig, configPath: string): void {
+  // Before the schema, on the object as it stands: the key folds its JSON,
+  // so a value JSON cannot carry is refused here and in the config worker
+  // alike (json-data.ts). A plugin's `project` edit and a lock entry cross
+  // this line too.
+  const [nonJson] = nonJsonPaths(config)
+  if (nonJson !== undefined) throw new UserError(nonJsonMessage(configPath, nonJson))
   // The top level too: `task:` (singular) loaded as a project with no
   // tasks and every request against it said "no projects declare".
   assertKnownFields(config, PROJECT_FIELDS, configPath)
@@ -199,6 +266,7 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
   }
   for (const [name, task] of Object.entries(tasks)) {
     const where = `${configPath}: tasks.${name}`
+    assertTaskName(name, configPath)
     if (!task || typeof task !== 'object') {
       throw new UserError(`${where} must be an object`)
     }
@@ -234,6 +302,15 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       if (remote !== undefined && typeof remote !== 'boolean' && remote !== 'only') {
         throw new UserError(`${where}.exec.remote must be a boolean or 'only' (or omitted)`)
       }
+      // Documented and never held: an uncached 'only' task loaded, and the
+      // REAPI executor refused it at run time for want of described inputs
+      // (item 1001).
+      if (remote === 'only' && cache === undefined) {
+        throw new UserError(
+          `${where}.exec.remote 'only' needs \`cache\`: its inputs are what a worker reproduces ` +
+            `and its key is the address of its remote record`,
+        )
+      }
       const env = (exec as { env?: unknown }).env
       if (env !== undefined) {
         if (typeof env !== 'object' || env === null) {
@@ -247,12 +324,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
           // A non-array here reaches `buildIsolatedEnv`'s `for (const name of
           // passThrough)` — a number throws "not iterable" mid-run, a string
           // silently char-iterates. Fail loud at load with a config pointer.
-          if (
-            !Array.isArray(passThrough) ||
-            passThrough.some((n) => typeof n !== 'string' || n.length === 0)
-          ) {
+          if (!Array.isArray(passThrough) || passThrough.some((n) => !isEnvName(n))) {
             throw new UserError(
-              `${where}.exec.env.passThrough must be an array of non-empty env var names`,
+              `${where}.exec.env.passThrough must be an array of env var names (non-empty, no '=' or NUL)`,
             )
           }
         }
@@ -264,8 +338,13 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
             )
           }
           for (const [k, val] of Object.entries(define as Record<string, unknown>)) {
-            if (typeof val !== 'string') {
-              throw new UserError(`${where}.exec.env.define.${k} must be a string`)
+            if (!isEnvName(k)) {
+              throw new UserError(
+                `${where}.exec.env.define: ${JSON.stringify(k)} is not an env var name (non-empty, no '=' or NUL)`,
+              )
+            }
+            if (typeof val !== 'string' || val.includes('\0')) {
+              throw new UserError(`${where}.exec.env.define.${k} must be a string with no NUL`)
             }
           }
         }
@@ -287,6 +366,17 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         if (readyWhen !== undefined && typeof readyWhen !== 'string') {
           throw new UserError(`${where}.exec.persistent.readyWhen must be a string regex`)
         }
+        // Compiled here as the runner compiles it: an unbalanced `(` loaded
+        // and then failed the task as "internal error" (item 998).
+        if (readyWhen !== undefined) {
+          try {
+            new RegExp(readyWhen)
+          } catch (err) {
+            throw new UserError(
+              `${where}.exec.persistent.readyWhen is not a valid regex (${(err as Error).message})`,
+            )
+          }
+        }
         if (cache !== undefined) {
           throw new UserError(
             `${where}: \`cache\` is not allowed on a persistent task — persistent tasks ` +
@@ -301,9 +391,13 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         }
       }
     } else {
-      // Group task: no exec, just dependencies. Must declare something to
-      // depend on, otherwise the task is a literal no-op with nothing to
-      // chain (almost certainly a config mistake).
+      // Group task: no exec, just dependencies. Only an ABSENT `dependsOn`
+      // is refused — a task with neither is a typo, not a declaration. An
+      // EMPTY one is deliberate and documented: `build: { dependsOn: [] }`
+      // is how a package consumed as source says it has nothing to build,
+      // so a dependant's `^build` finds it and waits on nothing
+      // (the quickstart). The comment here used to call that case
+      // "almost certainly a config mistake" while the docs taught it.
       if (dependsOn === undefined) {
         throw new UserError(
           `${where}: a task with no \`exec\` must declare \`dependsOn\` ` +
@@ -346,10 +440,11 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       if (envList !== undefined) {
         if (
           !Array.isArray(envList) ||
-          envList.some((s) => typeof s !== 'string' || s.length === 0)
+          // A NUL can be in no env name, and the key fold's delimiter is one.
+          envList.some((s) => !isEnvName(s))
         ) {
           throw new UserError(
-            `${where}.cache.inputs.env must be an array of non-empty env var names`,
+            `${where}.cache.inputs.env must be an array of env var names (non-empty, no '=' or NUL)`,
           )
         }
         for (const name of envList as string[]) {
@@ -359,7 +454,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
           // we add expansion later it'll be additive — until then,
           // surface the footgun instead of returning '' for the
           // literal env name `'VERCEL_*'`.
-          if (/[*?[\]]/.test(name)) {
+          // An env name is no path, so a bracket is no route directory: the
+          // whole `Bun.Glob` alphabet stays refused here.
+          if (BUN_GLOB_WILDCARDS.test(name)) {
             throw new UserError(
               `${where}.cache.inputs.env: wildcards in env names are not supported ` +
                 `(got "${name}") — list explicit env var names instead`,
@@ -398,7 +495,8 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         }
         if (namesDirItself(g)) {
           throw new UserError(
-            `${where}.cache.outputs.files: "${g}" names the project directory itself and selects nothing — use "**" for everything under it`,
+            `${where}.cache.outputs.files: "${g}" names the project directory itself and selects nothing — ` +
+              `name the directory the task writes, such as "dist/**"`,
           )
         }
         if (g.startsWith('!')) {
@@ -408,6 +506,14 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
               `path beginning with '!' and matches nothing. List the outputs you DO produce.`,
           )
         }
+        const own = ownFileCovered(g, configPath)
+        if (own !== null) {
+          throw new UserError(
+            `${where}.cache.outputs.files: "${g}" covers the project's own ${own} — vx deletes a ` +
+              `task's outputs before it runs and restores them on a hit, so the project would lose ` +
+              `its manifest and config. Name the directory the task writes, such as "dist/**".`,
+          )
+        }
       }
       // Same for inputs.files.
       for (const g of (inputs as { files: unknown[] }).files) {
@@ -432,6 +538,15 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
             `${where}.cache.inputs.files: "${g}" names the project directory itself and selects nothing — use "**" for everything under it`,
           )
         }
+        // A negated absolute path subtracts nothing (the positive globs are
+        // project-relative), so it would sit in the config as a silent no-op;
+        // `workspaceFiles` refuses both spellings the same way (item 679).
+        if (g.startsWith('!/')) {
+          throw new UserError(
+            `${where}.cache.inputs.files: absolute paths are not allowed (got "${g}") — ` +
+              `inputs must be project-relative globs`,
+          )
+        }
         assertNotDoubleNegated(g, `${where}.cache.inputs.files`)
       }
       // A list of ONLY negations selects nothing at all. `resolveFiles`
@@ -519,6 +634,15 @@ const CACHE_INPUT_FIELDS = new Set([
 const CACHE_OUTPUT_FIELDS = new Set(['files', 'workspaceFiles'])
 
 function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: string): void {
+  // `typeof [] === 'object'`, so an array reaches here and its indices read
+  // as fields: `outputs: ['dist/**']` (Turbo's spelling) was refused as
+  // `unknown field "0"`. Name the shape instead, and the one meant.
+  if (Array.isArray(value)) {
+    throw new UserError(
+      `${where} must be an object (fields: ${[...allowed].sort().join(', ')}), not an array` +
+        (allowed.has('files') ? ' — did you mean `{ files: [...] }`?' : ''),
+    )
+  }
   for (const key of Object.keys(value)) {
     if (!allowed.has(key)) {
       // The nearest accepted spelling first: the list says what the level
@@ -554,14 +678,16 @@ function assertTimeoutInRange(ms: number, where: string): void {
 }
 
 /**
- * True when a glob contains a `..` PATH SEGMENT (`../x`, `a/../b`, `x/..`), which
- * escapes its base dir — `foo..bar` / `a..b` inside a filename are fine. A
- * leading negation marker is stripped first so `!../x` is caught too. Used to
- * keep output globs inside the project and workspace globs inside the workspace
- * root: `cleanOutputs` rm()s resolved output paths before every run, and
- * `Bun.Glob.scan` follows `..` out of its cwd, so a `..` glob is a data-loss
- * vector (delete files outside the project / above the repo root).
+ * The project file an output glob would take, or null. `outputs: ['**']`
+ * loaded, and the clean before the run deleted the project's source,
+ * `package.json` and `vx.config` while the run reported success (item
+ * 1002); the message for `'.'` had even suggested `**`.
  */
+function ownFileCovered(glob: string, configPath: string): string | null {
+  const g = new Bun.Glob(normalizeGlob(glob))
+  return ['package.json', path.basename(configPath)].find((f) => g.match(f)) ?? null
+}
+
 /**
  * `.`, `./`, `././` (with or without a `!`) name the directory itself, which
  * no matcher expands: the entry selected nothing and said so nowhere.
@@ -572,6 +698,15 @@ function namesDirItself(glob: string): boolean {
   return g === '' || g === '/'
 }
 
+/**
+ * True when a glob contains a `..` PATH SEGMENT (`../x`, `a/../b`, `x/..`), which
+ * escapes its base dir — `foo..bar` / `a..b` inside a filename are fine. A
+ * leading negation marker is stripped first so `!../x` is caught too. Used to
+ * keep output globs inside the project and workspace globs inside the workspace
+ * root: `cleanOutputs` rm()s resolved output paths before every run, and
+ * `Bun.Glob.scan` follows `..` out of its cwd, so a `..` glob is a data-loss
+ * vector (delete files outside the project / above the repo root).
+ */
 function hasParentSegment(glob: string): boolean {
   const g = glob.startsWith('!') ? glob.slice(1) : glob
   return g.split('/').some((seg) => seg === '..')
@@ -616,35 +751,96 @@ function assertNotDoubleNegated(glob: string, where: string): void {
  * next upstream change. `['buidl']` for `['build']` is the shape. Patterns,
  * wildcards and negations stay silent (a preset-spread pattern legitimately
  * matches nothing in some projects; excluding what is absent is harmless);
- * an exact name must be named by some `dependsOn` entry, exactly or by that
- * entry's own `*` pattern. `[]` is the explicit way to decouple.
+ * an exact name must be named by some `dependsOn` entry of a form that can
+ * reach the same node, exactly or by that entry's own `*` pattern. The form
+ * matters: `build` selects this project's `build` and `^build` only other
+ * projects', so `['build']` against `dependsOn: ['^build']` folded nothing
+ * and served a stale hit (item 994). A `pkg#task` entry may name this
+ * project or a dependency, which the schema cannot tell apart, so it pairs
+ * with any form whose task half matches. `[]` is the explicit way to
+ * decouple.
  */
 function assertFilterNamesDeclaredDeps(
   filters: readonly string[],
   dependsOn: readonly string[] | undefined,
   where: string,
 ): void {
-  const taskHalf = (spec: string): string => {
-    const body = spec.startsWith('^') ? spec.slice(1) : spec
-    const hash = body.lastIndexOf('#')
-    return hash === -1 ? body : body.slice(hash + 1)
-  }
-  const declared = (dependsOn ?? []).map(taskHalf)
-  const named = (task: string): boolean =>
-    declared.some((d) => (d.includes('*') ? taskPatternRegExp(d).test(task) : d === task))
+  const declared = (dependsOn ?? []).map(specForm)
+  const matches = (pattern: string, name: string): boolean =>
+    pattern.includes('*') ? taskPatternRegExp(pattern).test(name) : pattern === name
+  const named = (f: SpecForm): boolean =>
+    declared.some((d) => {
+      if (!matches(d.task, f.task)) return false
+      if (d.form === 'cross' && f.form === 'cross') {
+        return f.project.includes('*') || matches(d.project, f.project)
+      }
+      return d.form === f.form || d.form === 'cross' || f.form === 'cross'
+    })
   for (const raw of filters) {
-    if (raw.startsWith('!') || raw === '*' || raw === '^*') continue
-    const task = taskHalf(raw)
-    if (task.length === 0 || task.includes('*') || named(task)) continue
+    // `*` and `^*` need no arm of their own: their task half is `*`, which
+    // the wildcard skip below takes (item 678).
+    if (raw.startsWith('!')) continue
+    const f = specForm(raw)
+    if (f.task.length === 0 || f.task.includes('*') || named(f)) continue
     throw new UserError(
       `${where}.cache.inputs.tasks: "${raw}" names no task in ${where}.dependsOn ` +
         `(${declared.length === 0 ? 'none declared' : dependsOn!.map((d) => `'${d}'`).join(', ')}) — ` +
         `it would match nothing and fold no upstream hash, decoupling the task from its ` +
-        `dependencies. Fix the name, or use [] to decouple on purpose.`,
+        `dependencies. \`name\` is this project's task, \`^name\` its dependencies', ` +
+        `\`pkg#name\` one project's. Fix the name, or use [] to decouple on purpose.`,
     )
   }
 }
 
+type SpecForm =
+  | { form: 'self' | 'deps'; task: string }
+  | { form: 'cross'; project: string; task: string }
+
+/** A `dependsOn` / filter entry's form, as `parseDependencySpec` splits it. */
+function specForm(spec: string): SpecForm {
+  if (spec.startsWith('^')) return { form: 'deps', task: spec.slice(1) }
+  const hash = spec.indexOf('#')
+  if (hash === -1) return { form: 'self', task: spec }
+  return { form: 'cross', project: spec.slice(0, hash), task: spec.slice(hash + 1) }
+}
+
+/**
+ * A name an environment can hold. An `=` splits at the first one, so
+ * `define: { 'A=B': 'x' }` gave the child `A` with the value `B=x`; `''`
+ * was dropped; a NUL failed the spawn with a hint about exit 127 (item
+ * 999). Refused at load, where the config is named.
+ */
+function isEnvName(name: unknown): name is string {
+  return typeof name === 'string' && name.length > 0 && !name.includes('=') && !name.includes('\0')
+}
+
+/**
+ * A task name `dependsOn`, `cache.inputs.tasks` and the CLI can name. Each
+ * refused shape loaded and could not be referenced: `x#y` read as project
+ * `x`, `^gen` as every dependency's `gen`, a `*` as a pattern, `''` ran
+ * under `--all` as `a#` and `vx run a#` refused it, and a padded name was
+ * trimmed away by the reader (item 1000).
+ */
+function assertTaskName(name: string, configPath: string): void {
+  const why =
+    name.trim().length === 0
+      ? 'is empty'
+      : name.trim() !== name
+        ? 'has surrounding whitespace'
+        : name.includes('#')
+          ? "holds '#', which separates a project from its task"
+          : name.includes('*')
+            ? "holds '*', which makes it a pattern"
+            : name.startsWith('^') || name.startsWith('!')
+              ? `starts with '${name[0]}', which names dependencies' tasks or negates`
+              : null
+  if (why === null) return
+  throw new UserError(
+    `${configPath}: task name ${JSON.stringify(name)} ${why} — dependsOn, cache.inputs.tasks and ` +
+      `the CLI could not name it. Rename the task.`,
+  )
+}
+
 /** The graph's `*`-only task glob (`compileTaskPattern`), mirrored: `*` is the sole metacharacter. */
 function taskPatternRegExp(pattern: string): RegExp {
   const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')