@vzn/vx 0.0.645 → 0.0.648

package/src/workspace/config-schema.ts

@@ -7,6 +7,7 @@
 
 import path from 'node:path'
 import {
+  PLATFORMS,
   PLUGIN_FUNCTION_HOOKS,
   PLUGIN_HOOKS,
   PLUGIN_PACKAGE,
@@ -22,9 +23,14 @@ import {
   UserError,
   BUN_GLOB_WILDCARDS,
   EXTGLOB,
+  braceRange,
+  BRACE_RANGE_LIMIT,
   anyTaskGlob,
   asTrees,
   isLiteralPattern,
+  hasControl,
+  parseDependencySpec,
+  DependencySpecError,
 } from '../util/index.js'
 import {
   parseSettingValue,
@@ -36,6 +42,7 @@ import {
 } from '../settings.js'
 import { compileNameGlob, parseFilter } from './filter.js'
 import { nonJsonMessage, nonJsonPaths } from './json-data.js'
+import { projectNameProblem, ROOT_NAME } from './workspace.js'
 
 // Mirrors `WorkspaceConfig` in src/config.ts. Unknown keys are REJECTED for
 // the same reason the task levels reject them: `plugin: [...]` (singular)
@@ -49,27 +56,31 @@ export function isCacheScope(v: unknown): v is string {
   return typeof v === 'string' && /^[\w.@/:-]{1,128}$/.test(v)
 }
 
-/**
- * A branch's cache scope, `<owner>/<repo>:<branch>`: what CI writes for a
- * branch and a laptop on it reads (owner, 2026-10-17). The repository's
- * identity, not a remote's local name, so a clone whose `origin` is a fork
- * names the fork. A name may hold characters a scope may not; each
- * becomes `_`.
- */
 const BASE_BRANCH_RULE = "must be a branch name like 'main'"
 
 /**
  * A branch name git takes after `origin/`: a leading '-' would reach git
- * as an option, and whitespace, `..`, `~^:?*[\\` are no ref's.
+ * as an option, and whitespace, `..`, `~^:?*[\\` are no ref's. A ref
+ * spelling (`origin/main`, `refs/heads/main`) is no branch either: vx
+ * looked for `origin/origin/main`, found no base, and a run on main took
+ * a branch's cache scope.
  */
 function isBaseBranch(value: unknown): value is string {
   return (
     typeof value === 'string' &&
     /^[^-\s\0~^:?*[\\][^\s\0~^:?*[\\]*$/.test(value) &&
-    !value.includes('..')
+    !value.includes('..') &&
+    !/^(?:origin|refs)\//.test(value)
   )
 }
 
+/**
+ * A branch's cache scope, `<owner>/<repo>:<branch>`: what CI writes for a
+ * branch and a laptop on it reads (2026-10-17). The repository's
+ * identity, not a remote's local name, so a clone whose `origin` is a fork
+ * names the fork. A name may hold characters a scope may not; each
+ * becomes `_`.
+ */
 export function branchCacheScope(repo: string, branch: string): string {
   return `${repo.toLowerCase()}:${branch}`.replace(/[^\w.@/:-]/g, '_').slice(0, 128)
 }
@@ -79,16 +90,16 @@ export function cacheScopeError(source = 'VX_CACHE_SCOPE'): string {
   return `${source} ${CACHE_SCOPE_RULE}`
 }
 
-/** Why `VX_CACHE_SCOPE` is refused, as the run's error. */
-export function cacheScopeEnvError(): UserError {
-  return new UserError(cacheScopeError())
+/** Why `VX_CACHE_SCOPE` (`got`) is refused, as the run's error: usage, as every `VX_*` value is. */
+export function cacheScopeEnvError(got: string): UserError {
+  return new UserError(`${cacheScopeError()} (got ${got})`, 'VX_E_USAGE')
 }
 
 /** `baseBranch`: `VX_BASE_BRANCH`, else the workspace's; undefined lets git name it. */
 export function configuredBaseBranch(workspace: WorkspaceConfig | null): string | undefined {
   const env = settingEnv('baseBranch')
   if (env !== undefined && !isBaseBranch(env)) {
-    throw new UserError(`VX_BASE_BRANCH ${BASE_BRANCH_RULE}`, 'VX_E_USAGE')
+    throw new UserError(`VX_BASE_BRANCH ${BASE_BRANCH_RULE} (got ${env as string})`, 'VX_E_USAGE')
   }
   return (env as string | undefined) ?? workspace?.baseBranch
 }
@@ -178,6 +189,14 @@ function validateDependencyRules(value: unknown, where: string): void {
   const shape = `an array of { from, allow?, deny? }, each a selector like 'tag:app' or '@acme/*'`
   if (!Array.isArray(value)) throw new UserError(`${where} must be ${shape}`)
   const selector = (v: unknown) => typeof v === 'string' && v.trim() !== '' && v !== 'tag:'
+  const matchable = (v: string, field: string) => {
+    const why = ruleSelectorProblem(v)
+    if (why !== null)
+      throw new UserError(
+        `${field} ${JSON.stringify(v)} ${why}; a selector is 'tag:<tag>' or a project name, ` +
+          `either may hold '*' (like 'tag:app' or '@acme/*')`,
+      )
+  }
   for (const [i, rule] of (value as unknown[]).entries()) {
     const at = `${where}[${i}]`
     if (typeof rule !== 'object' || rule === null || Array.isArray(rule))
@@ -185,12 +204,14 @@ function validateDependencyRules(value: unknown, where: string): void {
     assertKnownFields(rule, RULE_FIELDS, at)
     const { from, allow, deny } = rule as Record<string, unknown>
     if (!selector(from)) throw new UserError(`${at}.from must be a selector like 'tag:app'`)
+    matchable(from as string, `${at}.from`)
     for (const [k, list] of [
       ['allow', allow],
       ['deny', deny],
     ] as const) {
       if (list !== undefined && (!Array.isArray(list) || !list.every(selector)))
         throw new UserError(`${at}.${k} must be an array of selectors like 'tag:lib'`)
+      for (const [j, v] of ((list ?? []) as string[]).entries()) matchable(v, `${at}.${k}[${j}]`)
     }
     // A rule that says nothing reads as a constraint and checks nothing.
     if (allow === undefined && deny === undefined)
@@ -198,6 +219,33 @@ function validateDependencyRules(value: unknown, where: string): void {
   }
 }
 
+/**
+ * Why a rule selector can match no project, or null. The checker reads a
+ * selector as a tag or name glob only, so a `--filter` form loaded and
+ * matched nothing, and a `deny` of it passed every edge. Asked of the
+ * filter parser itself, as `tagProblem`.
+ */
+function ruleSelectorProblem(s: string): string | null {
+  const glob = s.startsWith('tag:') ? s.slice(4) : s
+  if (s.trim() !== s || glob.trim() !== glob) return 'has surrounding whitespace'
+  // The root's own name, which the filter reads as the root's directory.
+  if (s === ROOT_NAME) return null
+  if (s.startsWith('!')) return "starts with '!', which a filter reads as an exclusion"
+  const walk = "starts or ends with '...', which a filter reads as a dependency walk"
+  let f: ReturnType<typeof parseFilter>
+  try {
+    f = parseFilter(s, '/')
+  } catch {
+    // `...` alone: the walk with no project between.
+    return walk
+  }
+  if (f.withDeps || f.withDependents || f.onlyDeps || f.onlyDependents) return walk
+  if (f.gitSince !== undefined)
+    return `ends in "[${f.gitSince}]", which a filter reads as a git range`
+  if (f.isPath) return 'reads as a directory to a filter'
+  return null
+}
+
 /** `value` as the setting at `path` takes it, refused in `where`'s words. */
 function validateSettingValue(value: unknown, path: string, where: string): void {
   const { kind } = setting(path)
@@ -206,7 +254,8 @@ function validateSettingValue(value: unknown, path: string, where: string): void
   const untyped =
     (kind.type === 'concurrency' && typeof value === 'string' && !value.endsWith('%')) ||
     (kind.type === 'int' && typeof value !== 'number') ||
-    (kind.type === 'bool' && typeof value !== 'boolean')
+    (kind.type === 'bool' && typeof value !== 'boolean') ||
+    (kind.type === 'size' && value === 'false')
   if (untyped || parseSettingValue(kind, value) === null) {
     throw new UserError(settingRefusal(path, where, value, shown(value)))
   }
@@ -231,11 +280,13 @@ function validateSettingsExtra(config: WorkspaceConfig, configPath: string): voi
 /**
  * A refused value as a message quotes it. A workspace file is evaluated
  * in-process and no JSON rule precedes its schema, so a value here may be
- * one `JSON.stringify` throws on (`30n`) or drops (a symbol): the refusal
- * became a TypeError with a stack.
+ * one `JSON.stringify` throws on (`30n`), drops (a symbol) or misnames
+ * (`Infinity` as null): the refusal became a TypeError with a stack.
  */
 function shown(v: unknown): string {
-  return typeof v === 'bigint' ? `${v}n` : (JSON.stringify(v) ?? String(v))
+  if (typeof v === 'bigint') return `${v}n`
+  if (typeof v === 'number' && !Number.isFinite(v)) return String(v)
+  return JSON.stringify(v) ?? String(v)
 }
 
 /** A `plugins` entry that stands for no plugin: `undefined`, `null` or `false`. */
@@ -258,18 +309,24 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     }
     const verbOwners = new Map<string, string>()
     const fileClaimants = new Map<string, { name: string; at: number }>()
+    const seenAt = new Map<object, number>()
     for (const [i, p] of (config.plugins as readonly unknown[]).entries()) {
       // A factory that declines returns nothing, and `cond && plugin()` is
       // false: both are skipped, as Vite skips them.
       if (isSkippedPlugin(p)) continue
       if (p === null || typeof p !== 'object') {
         // Nx's nx.json lists plugins by module name (`'@nx/vite/plugin'`);
-        // a vx plugin is the value its package's function returns.
+        // a vx plugin is the value its package's function returns, and
+        // `plugins: [otel]` is that function, not called.
         throw new UserError(
           `${configPath}: \`plugins[${i}]\` must be an object` +
             (typeof p === 'string'
               ? ` — a plugin is what its package's function returns (\`nx()\` from \`@vzn/vx-migrate\`), not a module name`
-              : ''),
+              : typeof p === 'function'
+                ? p.name === ''
+                  ? ' — it is a function; call the factory that returns the plugin'
+                  : ` — it is the function '${p.name}'; call it: ${p.name}()`
+                : ''),
         )
       }
       // The loose schema's shape (unknown-typed hooks) plus the one retired
@@ -297,6 +354,15 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           `${configPath}: \`plugins[${i}].name\` overrides the package name ('${String(plug.name)}' over '${pkg}') — a plugin's name is its package name; drop the field`,
         )
       }
+      // One instance twice (two presets sharing it) ran its setup, its
+      // handlers and its telemetry sinks twice. Two instances stay two.
+      const first = seenAt.get(p)
+      if (first !== undefined) {
+        throw new UserError(
+          `${configPath}: \`plugins[${i}]\` is \`plugins[${first}]\` again (plugin '${pkg}') — declare a plugin once`,
+        )
+      }
+      seenAt.set(p, i)
       // A misspelled hook (`excutor`, `setUp`) was never called and never
       // said: tasks ran here with the plugin's executor unheard (X-19).
       for (const key of Object.keys(plug)) {
@@ -462,6 +528,18 @@ export function validateProjectConfig(
         `${configPath}: \`name\` must be a non-empty string with no surrounding whitespace and no "#" (a task is <name>#<task>)`,
       )
     }
+    // Printed raw by the status line and summary: `ESC ]0;` retitled the terminal.
+    if (hasControl(name)) {
+      throw new UserError(
+        `${configPath}: \`name\` ${JSON.stringify(name)} holds a control character — rename the project`,
+      )
+    }
+    const why = projectNameProblem(name)
+    if (why !== null) {
+      throw new UserError(
+        `${configPath}: \`name\` ${JSON.stringify(name)} ${why} — dependsOn, --filter and the CLI could not name the project. Rename it.`,
+      )
+    }
   }
   const tags: unknown = config.tags
   if (
@@ -478,6 +556,12 @@ export function validateProjectConfig(
           `name it. Rename the tag.`,
       )
     }
+    // Printed raw by `vx show`, as a name is.
+    if (hasControl(tag)) {
+      throw new UserError(
+        `${configPath}: tag ${JSON.stringify(tag)} holds a control character — rename the tag`,
+      )
+    }
   }
   const tasks = config.tasks
   if (tasks === undefined) return
@@ -528,9 +612,7 @@ export function validateProjectConfig(
       }
       const retries = (exec as { retries?: unknown }).retries
       if (retries !== undefined) {
-        if (typeof retries !== 'number' || !Number.isInteger(retries) || retries < 0) {
-          throw new UserError(`${where}.exec.retries must be a non-negative integer`)
-        }
+        validateSettingValue(retries, 'run.retries', `${where}.exec.retries`)
       }
       const remote = (exec as { remote?: unknown }).remote
       if (remote !== undefined && typeof remote !== 'boolean' && remote !== 'only') {
@@ -545,6 +627,20 @@ export function validateProjectConfig(
             `and its key is the address of its remote record`,
         )
       }
+      const platforms = (exec as { platforms?: unknown }).platforms
+      if (platforms !== undefined) {
+        const known = PLATFORMS as readonly unknown[]
+        if (
+          !Array.isArray(platforms) ||
+          platforms.length === 0 ||
+          !platforms.every((p) => known.includes(p)) ||
+          new Set(platforms).size !== platforms.length
+        ) {
+          throw new UserError(
+            `${where}.exec.platforms must be a non-empty array of distinct platforms, each one of ${PLATFORMS.join(', ')}`,
+          )
+        }
+      }
       const env = (exec as { env?: unknown }).env
       if (env !== undefined) {
         if (typeof env !== 'object' || env === null) {
@@ -799,9 +895,9 @@ export function validateProjectConfig(
       // The only InputsConfig field that reached the run unvalidated: a
       // non-string entry crashes deep in `filterUpstreamHashes` /
       // `parseDependencySpec` with a raw TypeError naming neither the task
-      // nor the config. Entry SYNTAX is already checked downstream (a
-      // `DependencySpecError` becomes a UserError naming the task) — this
-      // only pins the shape.
+      // nor the config. Each entry's syntax too: a malformed one (`^`,
+      // `a#`) passed `vx lock` and failed the task at hash time, after its
+      // upstream ran.
       const taskFilters = (inputs as { tasks?: unknown }).tasks
       if (taskFilters !== undefined) {
         if (
@@ -813,6 +909,14 @@ export function validateProjectConfig(
               `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name', '*', '^*', '!name')`,
           )
         }
+        for (const raw of taskFilters as string[]) {
+          try {
+            parseDependencySpec(raw, 'inputs.tasks')
+          } catch (err) {
+            if (err instanceof DependencySpecError) throw new UserError(`${where}: ${err.message}`)
+            throw err
+          }
+        }
         assertFilterNamesDeclaredDeps(taskFilters, task.dependsOn, where)
       }
       for (const field of ['runtime', 'workspaceRuntime'] as const) {
@@ -893,8 +997,8 @@ export function validateProjectConfig(
         if (hasParentSegment(g)) {
           throw new UserError(
             `${where}.cache.outputs.files: '..' path segments are not allowed (got "${g}") — ` +
-              `outputs must stay within the project (a glob that escapes the project dir would ` +
-              `let cleanOutputs delete files outside it)`,
+              `outputs must stay within the project (vx clears a task's outputs before it runs, ` +
+              `so a glob that escapes the project would delete files outside it)`,
           )
         }
         assertPosixGlob(g, `${where}.cache.outputs.files`, 'project')
@@ -931,6 +1035,7 @@ export function validateProjectConfig(
         }
       }
       assertOutputsNotNegationOnly(outFiles as string[], `${where}.cache.outputs.files`)
+      assertNoLiteralTakenBack(outFiles as string[], `${where}.cache.outputs.files`, OUTPUT_LOST)
       const wsOutputs = (outputs as { workspaceFiles?: unknown }).workspaceFiles
       if (wsOutputs !== undefined) {
         validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`, false)
@@ -958,6 +1063,7 @@ const EXEC_FIELDS = new Set([
   'interactive',
   'remote',
   'sandbox',
+  'platforms',
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
@@ -1028,7 +1134,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       files: "the task's `inputs.files`",
       output: '`outputs.files`',
       env: "the task's `inputs.env`",
-      dependencies: "the task's `dependsOn` (an upstream's key folds into this one)",
+      dependencies: "the task's `dependsOn` (an upstream's key goes into this one)",
       enabled: 'no field: a task with a `cache` block caches, one without runs every time',
     },
   ],
@@ -1134,6 +1240,23 @@ function nearestSetting(key: string): string | undefined {
   return name === undefined ? undefined : `\`${byName.get(name)}\``
 }
 
+/**
+ * Where a field one level down lives: `retries`, `timeout` or `sandbox` on
+ * a task, beside `exec` rather than in it, was refused with the task's
+ * fields alone, none of which is it.
+ */
+function nestedHome(allowed: ReadonlySet<string>, key: string): string | undefined {
+  if (allowed !== TASK_FIELDS) return undefined
+  for (const [field, own] of [
+    ['exec', EXEC_FIELDS],
+    ['inputs', INPUT_FIELDS],
+    ['cache', CACHE_FIELDS],
+  ] as const) {
+    if (own.has(key)) return `\`${field}.${key}\``
+  }
+  return undefined
+}
+
 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
@@ -1148,7 +1271,7 @@ function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: s
     if (!allowed.has(key)) {
       // The nearest accepted spelling first: the list says what the level
       // takes, the hint says which one was meant.
-      const foreign = FOREIGN_FIELDS.get(allowed)?.[key]
+      const foreign = FOREIGN_FIELDS.get(allowed)?.[key] ?? nestedHome(allowed, key)
       const near =
         nearest(key, allowed) ?? (allowed === WORKSPACE_FIELDS ? nearestSetting(key) : undefined)
       throw new UserError(
@@ -1246,6 +1369,63 @@ function assertNoForeignToken(glob: string, where: string): void {
         `files it names. Write ${rewrite} instead.`,
     )
   }
+  assertNoBareGroup(glob, body, where)
+  assertNoBraceRange(glob, where)
+  assertNoGluedGlobstar(glob, where)
+}
+
+/**
+ * `Bun.Glob` reads `**` glued to other text (`src/**.ts`, `a**`) as `*`, one
+ * level: deeper inputs left the key and deeper outputs were never saved.
+ * Turbo rewrites it to the deep reading (vercel/turborepo#5431); vx refuses
+ * and names both.
+ */
+function assertNoGluedGlobstar(glob: string, where: string): void {
+  const body = glob.startsWith('!') ? glob.slice(1) : glob
+  if (!body.split(/[/{},]/).some((seg) => seg.includes('**') && /[^*]/.test(seg))) return
+  const deep = glob.replace(/\*\*([^*/{},]+)/g, '**/*$1').replace(/([^*/{},]+)\*\*/g, '$1*/**')
+  const one = glob.replace(/\*{2,}/g, (run, at: number) =>
+    /[^*/{},]/.test(glob[at - 1] ?? '') || /[^*/{},]/.test(glob[at + run.length] ?? '') ? '*' : run,
+  )
+  throw new UserError(
+    `${where}: "${glob}" glues ** to other text in one path segment, which vx's glob engine ` +
+      `reads as one *, a single directory level. Write "${deep}" for every depth, or "${one}" ` +
+      `for one level.`,
+  )
+}
+
+/** `(a|b)` with no extglob sigil: `Bun.Glob` reads parens and `|` as literal text. */
+const BARE_GROUP = /(?<!\\)\(([^()|]*(?:\|[^()|]*)+)\)/
+
+function assertNoBareGroup(glob: string, body: string, where: string): void {
+  const group = BARE_GROUP.exec(body)
+  if (group === null) return
+  const names = group[1]!.split('|')
+  const rewrite = BUN_GLOB_WILDCARDS.test(group[1]!)
+    ? 'braces ("{a,b}") or one entry per alternative'
+    : `"${glob.replace(group[0], `{${names.join(',')}}`)}"`
+  throw new UserError(
+    `${where}: "${glob}" holds a bare (…|…) group, which vx's glob engine reads as literal ` +
+      `text, never as the alternatives it lists, so the cache key would miss the files it ` +
+      `names. Write ${rewrite} instead.`,
+  )
+}
+
+const BRACE_RANGE = /(?<!\\)\{(-?\d+|[a-zA-Z])\.\.(-?\d+|[a-zA-Z])(\.\.-?\d+)?\}/g
+
+/**
+ * A range vx expands is any task glob's (`braceRange`). One it does not —
+ * mixed case, or past the limit — `Bun.Glob` would still read, so the
+ * readings would differ by engine: refused.
+ */
+function assertNoBraceRange(glob: string, where: string): void {
+  // Every range, not the first: `a{1..2}{A..c}` held one vx reads past.
+  const m = [...glob.matchAll(BRACE_RANGE)].find((r) => braceRange(r[0].slice(1, -1)) === null)
+  if (m === undefined) return
+  throw new UserError(
+    `${where}: "${glob}" holds the brace range ${m[0]}, which vx expands only within one case ` +
+      `and up to ${BRACE_RANGE_LIMIT} names. Write a smaller range or a comma brace.`,
+  )
 }
 
 /**
@@ -1331,7 +1511,7 @@ function assertPosixGlob(glob: string, where: string, base: string): void {
   )
 }
 
-const ONE_ALTERNATIVE_BRACE = /(?<!\\)\{[^{},]*\}/
+const ONE_ALTERNATIVE_BRACE = /(?<!\\)\{[^{},]*\}/g
 
 /**
  * What every run would refuse, or silently key nothing for, refused at
@@ -1341,8 +1521,11 @@ const ONE_ALTERNATIVE_BRACE = /(?<!\\)\{[^{},]*\}/
  * named. A path under `.git` is never listed by git, so it keyed nothing.
  */
 function assertInputGlob(glob: string, where: string): void {
-  const m = ONE_ALTERNATIVE_BRACE.exec(glob)
-  if (m !== null) {
+  // A range is a brace vx expands (`braceRange`), not one alternative.
+  const m = [...glob.matchAll(ONE_ALTERNATIVE_BRACE)].find(
+    (b) => braceRange(b[0].slice(1, -1)) === null,
+  )
+  if (m !== undefined) {
     const inner = m[0].slice(1, -1)
     throw new UserError(
       `${where}: "${glob}" holds a brace with one alternative, which matches ` +
@@ -1427,7 +1610,7 @@ function assertFilterNamesDeclaredDeps(
     // 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
+    if (f.task.includes('*') || named(f)) continue
     // `where` opens with the config's path; the message names it once.
     const task = where.slice(where.lastIndexOf(': tasks.') + 2)
     throw new UserError(
@@ -1501,7 +1684,9 @@ export function taskNameProblem(name: string): string | null {
           ? "holds '*', which makes it a pattern"
           : name.startsWith('^') || name.startsWith('!')
             ? `starts with '${name[0]}', which names dependencies' tasks or negates`
-            : null
+            : hasControl(name)
+              ? 'holds a control character'
+              : null
 }
 
 /**
@@ -1512,11 +1697,19 @@ export function taskNameProblem(name: string): string | null {
 function tagProblem(tag: string): string | null {
   if (tag.trim() !== tag) return 'has surrounding whitespace'
   if (tag.includes('*')) return "holds '*', which makes it a pattern"
-  const f = parseFilter(`tag:${tag}`, '/')
+  const walk = "ends in '...', which a filter reads as a dependency walk"
+  let f: ReturnType<typeof parseFilter>
+  try {
+    f = parseFilter(`tag:${tag}`, '/')
+  } catch {
+    // `...` alone: the walk leaves the filter no tag, and its refusal
+    // named neither the config nor the tag.
+    return walk
+  }
   if (f.gitSince !== undefined) {
     return `ends in "[${f.gitSince}]", which a filter reads as a git range`
   }
-  if (f.withDeps || f.onlyDeps) return "ends in '...', which a filter reads as a dependency walk"
+  if (f.withDeps || f.onlyDeps) return walk
   return null
 }
 
@@ -1548,7 +1741,12 @@ function assertNotNegationOnly(globs: readonly string[], where: string): void {
  * entered the key, and an edit to it replayed the old output. Refusing is
  * free: the literal already selected nothing.
  */
-function assertNoLiteralTakenBack(globs: readonly string[], where: string): void {
+function assertNoLiteralTakenBack(
+  globs: readonly string[],
+  where: string,
+  // An output's literal is never saved: a hit left it missing and said up-to-date.
+  lost = 'the file never enters the key',
+): void {
   const negative = globs.filter((g) => g.startsWith('!')).map((g) => g.slice(1))
   if (negative.length === 0) return
   const taken = anyTaskGlob(asTrees(negative))
@@ -1559,7 +1757,7 @@ function assertNoLiteralTakenBack(globs: readonly string[], where: string): void
     const by = negative.find((n) => anyTaskGlob(asTrees([n]))(lit))
     throw new UserError(
       `${where}: "${g}" is taken back by "!${by}" — a \`!\` entry subtracts wherever it sits in ` +
-        `the list, so the file never enters the key. Narrow the negation so it leaves "${g}".`,
+        `the list, so ${lost}. Narrow the negation so it leaves "${g}".`,
     )
   }
 }
@@ -1601,13 +1799,18 @@ function validateWorkspaceGlobs(v: unknown, where: string, negation: boolean): v
   if (negation) {
     assertNotNegationOnly(v as string[], where)
     assertNoLiteralTakenBack(v as string[], where)
-  } else assertOutputsNotNegationOnly(v as string[], where)
+  } else {
+    assertOutputsNotNegationOnly(v as string[], where)
+    assertNoLiteralTakenBack(v as string[], where, OUTPUT_LOST)
+  }
 }
 
 /**
  * An output list of only `!` entries selects nothing: the task saves and
  * restores nothing while it reads as if it declared outputs (A-44).
  */
+const OUTPUT_LOST = 'the file is never saved or restored'
+
 function assertOutputsNotNegationOnly(globs: readonly string[], where: string): void {
   if (globs.length === 0 || globs.some((g) => !g.startsWith('!'))) return
   throw new UserError(

package/src/workspace/filter.ts

@@ -24,6 +24,7 @@
 import path from 'node:path'
 import { BUN_GLOB_WILDCARDS, relPosix, UserError } from '../util/index.js'
 import type { PackageGraph } from './package-graph.js'
+import { canonicalDir } from './canonical-dir.js'
 import type { ProjectMeta } from './workspace.js'
 
 export interface ParsedFilter {
@@ -54,7 +55,7 @@ export interface ParsedFilter {
   pathGlob?: Bun.Glob
   /** `./a/**`'s `a`: a trailing `**` matches zero dirs, and `Bun.Glob` does not (D-84). */
   pathGlobBase?: Bun.Glob
-  /** The workspace root `pathGlob` is relative to. */
+  /** The workspace root a path form is relative to. */
   pathRoot?: string
   /** `//`: the project at `matcher` itself, never the ones under it. */
   exactDir?: true
@@ -67,7 +68,12 @@ export interface ParsedFilter {
   dirFallback?: ParsedFilter
 }
 
-export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
+export function parseFilter(
+  raw: string,
+  workspaceRoot: string,
+  /** The filter as typed, when `raw` is the `./` reading of a name (`dirFallback`). */
+  typed = raw,
+): ParsedFilter {
   let s = raw
   const negate = s.startsWith('!')
   if (negate) s = s.slice(1)
@@ -180,8 +186,18 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
         ? s.slice(1, -1)
         : undefined
   if (pathForm !== undefined) {
+    // `{}` resolved to the root, every project under it: an unset
+    // variable in `--filter "{$PKG}"` ran the whole workspace.
+    if (pathForm.trim() === '') throw new UserError(`filter "${raw}" names no project`)
     isPath = true
     matcher = path.resolve(workspaceRoot, pathForm)
+    // `../` (pnpm's cwd-relative sibling) climbed out of the root, and
+    // every project sat under the directory it named: all of them ran.
+    const up = path.relative(workspaceRoot, matcher)
+    if (up === '..' || up.startsWith(`..${path.sep}`))
+      throw new UserError(
+        `filter "${typed}" names a directory outside the workspace root: a path filter is relative to the root`,
+      )
     // `./packages/*` — pnpm's and Turbo's spelling for "every package under
     // packages": a glob over the root-relative project dir. Resolved
     // against the workspace root like the literal form.
@@ -200,7 +216,7 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
   // 23.2.1), and `-p 'apps/*'` matched nothing here.
   const dirFallback =
     !isPath && s.includes('/') && !s.startsWith('@')
-      ? parseFilter(`./${s}`, workspaceRoot)
+      ? parseFilter(`./${s}`, workspaceRoot, raw)
       : undefined
 
   return {
@@ -213,7 +229,8 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
     isPath,
     matcher,
     ...(dirFallback !== undefined ? { dirFallback } : {}),
-    ...(pathGlob !== undefined ? { pathGlob, pathRoot: workspaceRoot } : {}),
+    ...(isPath ? { pathRoot: workspaceRoot } : {}),
+    ...(pathGlob !== undefined ? { pathGlob } : {}),
     ...(pathGlobBase !== undefined ? { pathGlobBase } : {}),
     ...(gitSince !== undefined ? { gitSince } : {}),
     ...(sinceViaDeps ? { sinceViaDeps: true as const } : {}),
@@ -261,7 +278,13 @@ function matchSelector(
     // pnpm read it: `.` is the root project, never every project under the
     // root, and `./packages/app` leaves the examples nested in it (D-43).
     // A directory that is no project keeps the "at or under" reading.
-    const exact = projects.find((p) => p.dir === filter.matcher)
+    // A link to a project's directory (`./widgets/a -> ../submodules/a`)
+    // names that project, which discovery holds at its real directory.
+    let exact = projects.find((p) => p.dir === filter.matcher)
+    if (exact === undefined && filter.pathRoot !== undefined) {
+      const real = canonicalDir(filter.pathRoot, filter.matcher)
+      if (real !== null && real !== filter.matcher) exact = projects.find((p) => p.dir === real)
+    }
     if (exact !== undefined) return [exact.name]
     if (filter.exactDir === true) return out
     const prefix = filter.matcher + path.sep
@@ -339,9 +362,10 @@ export interface ApplyFiltersOptions {
   /**
    * Called once per filter that matched zero projects, before expansion.
    * Only the TOTAL empty selection is an error, so without this a typo among
-   * several filters silently under-selects.
+   * several filters silently under-selects. `emptyDiff`: a `[<since>]`
+   * filter whose name or dir part names projects, none of them changed.
    */
-  onNoMatch?: (filter: ParsedFilter) => void
+  onNoMatch?: (filter: ParsedFilter, emptyDiff: boolean) => void
   /**
    * Called once per filter whose pattern matched projects but whose walk
    * selected none (`...^c` for a `c` nothing depends on), with what it
@@ -362,7 +386,12 @@ export function applyFilters(opts: ApplyFiltersOptions): Set<string> {
   const excludes: Set<string>[] = []
   for (const f of opts.filters) {
     const matched = matchProjects(f, opts.projects, opts.affectedByFilter, opts.graph, opts.tags)
-    if (matched.length === 0) opts.onNoMatch?.(f)
+    if (matched.length === 0)
+      opts.onNoMatch?.(
+        f,
+        f.gitSince !== undefined &&
+          (f.matcher === '' || matchSelector(f, opts.projects, opts.tags).length > 0),
+      )
     const expanded = new Set<string>()
     for (const name of matched) {
       if (!f.onlyDeps && !f.onlyDependents) expanded.add(name)