@vzn/vx 0.0.18 → 0.0.22

package/src/workspace/filter.ts

@@ -6,6 +6,7 @@
 //   <pattern>...     pattern + its transitive workspace dependencies
 //   ...<pattern>     pattern + its transitive workspace dependents
 //   <pattern>^...    only the transitive deps of pattern (excluding the matched package)
+//   ...^<pattern>    only the transitive dependents of pattern (excluding the matched package)
 //   !<pattern>       exclude packages matching pattern from the selection
 //   [<since>]        projects affected since the given git ref
 //                    (Turbo-style; resolved upstream of applyFilters via
@@ -16,6 +17,7 @@
 // given, the base set is "all projects" and excluded packages are removed.
 
 import path from 'node:path'
+import { BUN_GLOB_WILDCARDS } from '../util/index.js'
 import type { PackageGraph } from './package-graph.js'
 import type { ProjectMeta } from './workspace.js'
 
@@ -25,6 +27,8 @@ export interface ParsedFilter {
   withDeps: boolean
   withDependents: boolean
   onlyDeps: boolean
+  /** `...^<pattern>`: the dependents alone, the matched package left out. */
+  onlyDependents: boolean
   isPath: boolean
   /** Glob pattern (for name match) or absolute path (for path match). */
   matcher: string
@@ -34,6 +38,10 @@ export interface ParsedFilter {
    * to a concrete set of project names before calling applyFilters.
    */
   gitSince?: string
+  /** A path form carrying a glob (`./packages/*`): matched over the root-relative project dir. */
+  pathGlob?: Bun.Glob
+  /** The workspace root `pathGlob` is relative to. */
+  pathRoot?: string
 }
 
 export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
@@ -43,6 +51,10 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
 
   const withDependents = s.startsWith('...')
   if (withDependents) s = s.slice(3)
+  // `...^a`: cli.md listed it, and the `^` stayed in the name glob, so it
+  // matched no package and the run refused (item 890).
+  const onlyDependents = withDependents && s.startsWith('^')
+  if (onlyDependents) s = s.slice(1)
 
   let onlyDeps = false
   let withDeps = false
@@ -63,6 +75,7 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
       withDeps,
       withDependents,
       onlyDeps,
+      onlyDependents,
       isPath: false,
       matcher: '',
       gitSince: s.slice(1, -1),
@@ -71,15 +84,37 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
 
   let isPath = false
   let matcher = s
-  if (s.startsWith('./') || s === '.') {
+  let pathGlob: Bun.Glob | undefined
+  const pathForm =
+    s.startsWith('./') || s === '.'
+      ? s
+      : s.startsWith('{') && s.endsWith('}')
+        ? s.slice(1, -1)
+        : undefined
+  if (pathForm !== undefined) {
     isPath = true
-    matcher = path.resolve(workspaceRoot, s)
-  } else if (s.startsWith('{') && s.endsWith('}')) {
-    isPath = true
-    matcher = path.resolve(workspaceRoot, s.slice(1, -1))
+    matcher = path.resolve(workspaceRoot, pathForm)
+    // `./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.
+    // A member glob, not a task glob: `Bun.Glob`'s alphabet, the class included.
+    if (BUN_GLOB_WILDCARDS.test(pathForm)) {
+      const rel = path.relative(workspaceRoot, matcher).split(path.sep).join('/')
+      pathGlob = new Bun.Glob(rel.replace(/\/+$/, ''))
+    }
   }
 
-  return { raw, negate, withDeps, withDependents, onlyDeps, isPath, matcher }
+  return {
+    raw,
+    negate,
+    withDeps,
+    withDependents,
+    onlyDeps,
+    onlyDependents,
+    isPath,
+    matcher,
+    ...(pathGlob !== undefined ? { pathGlob, pathRoot: workspaceRoot } : {}),
+  }
 }
 
 function matchProjects(
@@ -99,14 +134,28 @@ function matchProjects(
     for (const p of projects) {
       if (p.dir === filter.matcher || p.dir.startsWith(prefix)) out.push(p.name)
     }
-    return out
-  }
-  if (!filter.matcher.includes('*')) {
-    for (const p of projects) {
-      if (p.name === filter.matcher) out.push(p.name)
+    // A path that names a project directory literally means that directory,
+    // as git reads a pathspec, even when it holds glob characters
+    // (`./packages/[abc]`); only a path that selects nothing literally is
+    // read as a glob.
+    if (out.length > 0) return out
+    if (filter.pathGlob !== undefined) {
+      // The glob is matched against the project's own dir, as pnpm and
+      // Turbo do: `./packages/*` is the packages directly under `packages`,
+      // `./packages/**` reaches the nested ones too.
+      for (const p of projects) {
+        const rel = path
+          .relative(filter.pathRoot ?? '', p.dir)
+          .split(path.sep)
+          .join('/')
+        if (filter.pathGlob.match(rel)) out.push(p.name)
+      }
     }
     return out
   }
+  // A `*`-free name compiles to an exact anchored match, so a bare name
+  // needs no branch of its own: the one this had was deleted with the
+  // whole core suite green (item 649).
   const re = compileNameGlob(filter.matcher)
   for (const p of projects) {
     if (re.test(p.name)) out.push(p.name)
@@ -149,12 +198,17 @@ export function applyFilters(opts: ApplyFiltersOptions): Set<string> {
   const hasInclude = opts.filters.some((f) => !f.negate)
   const selected = new Set<string>(hasInclude ? [] : allNames)
 
+  // Every include before any exclude, as pnpm does: applied in argv order,
+  // `--filter '!b' --filter 'a...'` let the later include add back what the
+  // exclude had removed, and b ran (item 979). The expansions are still
+  // taken in argv order, so `onNoMatch` names the filters as typed.
+  const excludes: Set<string>[] = []
   for (const f of opts.filters) {
     const matched = matchProjects(f, opts.projects, opts.affectedByFilter)
     if (matched.length === 0) opts.onNoMatch?.(f)
     const expanded = new Set<string>()
     for (const name of matched) {
-      if (!f.onlyDeps) expanded.add(name)
+      if (!f.onlyDeps && !f.onlyDependents) expanded.add(name)
       if (f.withDeps || f.onlyDeps) {
         for (const d of opts.graph.transitiveDeps(name)) expanded.add(d)
       }
@@ -162,12 +216,10 @@ export function applyFilters(opts: ApplyFiltersOptions): Set<string> {
         for (const d of opts.graph.transitiveDependents(name)) expanded.add(d)
       }
     }
-    if (f.negate) {
-      for (const name of expanded) selected.delete(name)
-    } else {
-      for (const name of expanded) selected.add(name)
-    }
+    if (f.negate) excludes.push(expanded)
+    else for (const name of expanded) selected.add(name)
   }
+  for (const expanded of excludes) for (const name of expanded) selected.delete(name)
 
   return selected
 }

package/src/workspace/fingerprint.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { xxh3 } from '../util/index.js'
+import { type LoadReads, readOnce } from './load-reads.js'
 
 // Every package-manager lockfile we know about, plus the workspace
 // definition files. Whichever ones exist get folded into the
@@ -23,6 +24,12 @@ export const WORKSPACE_FINGERPRINT_FILES = [
   // Workspace definition (pnpm); package.json is hashed per-project
   // via projectPackageJsonHash, not here.
   'pnpm-workspace.yaml',
+  // Yarn 4 catalogs: yarn.lock records a `catalog:` dependency as that
+  // literal, so a catalog flip to a range the file already resolves
+  // leaves it byte-identical while the workspace's install moves
+  // (turborepo#12635). pnpm's catalogs live in pnpm-workspace.yaml, and
+  // its lockfile records each importer's resolved version besides.
+  '.yarnrc.yml',
 ]
 
 // DELIBERATELY ABSENT: `vx.workspace.{ts,mts,js,mjs}`. Everything it can
@@ -43,14 +50,59 @@ export const WORKSPACE_FINGERPRINT_FILES = [
  * `npm install`, `bun install`, …) or a workspace-shape change
  * invalidates every cached entry. Coarse but correct.
  */
-export async function computeWorkspaceFingerprint(workspaceRoot: string): Promise<string> {
-  let h = 0n
+export async function computeWorkspaceFingerprint(
+  workspaceRoot: string,
+  reads?: LoadReads,
+): Promise<string> {
+  return (await computeWorkspaceFingerprints(workspaceRoot, NONE, reads)).all
+}
+
+const NONE: ReadonlySet<string> = new Set()
+
+export interface WorkspaceFingerprints {
+  /** Every file folded — what the config-evaluation cache keys on. */
+  readonly all: string
+  /**
+   * The same fold minus the files a plugin claims (`VxPlugin.fingerprint`)
+   * — what every task key folds. Identical to `all` with nothing claimed.
+   */
+  readonly unclaimed: string
+  /**
+   * The bytes folded, by file name — what a mid-run check compares against
+   * when a task may have rewritten one (orchestrator/fingerprint-watch.ts).
+   * Already in memory for the fold; kept, not copied.
+   */
+  readonly files: ReadonlyMap<string, Uint8Array>
+}
+
+/**
+ * Both digests from one read of each file — none at all for the
+ * `pnpm-workspace.yaml` discovery already read into the load's `reads`. A
+ * claimed file leaves the key digest entirely (its name too): the claimant
+ * folds what it means per project, and a fold of "present" would still
+ * re-key the workspace when the file appeared.
+ */
+export async function computeWorkspaceFingerprints(
+  workspaceRoot: string,
+  claimed: ReadonlySet<string>,
+  reads?: LoadReads,
+): Promise<WorkspaceFingerprints> {
+  let all = 0n
+  let unclaimed = 0n
+  const files = new Map<string, Uint8Array>()
   for (const f of WORKSPACE_FINGERPRINT_FILES) {
-    const full = path.join(workspaceRoot, f)
-    const file = Bun.file(full)
-    if (!(await file.exists())) continue
-    h = xxh3(`${f}\0`, h)
-    h = xxh3(await file.bytes(), h)
+    const bytes = await readOnce(reads, path.join(workspaceRoot, f))
+    if (bytes === null) continue
+    files.set(f, bytes)
+    all = xxh3(`${f}\0`, all)
+    all = xxh3(bytes, all)
+    if (claimed.has(f)) continue
+    unclaimed = xxh3(`${f}\0`, unclaimed)
+    unclaimed = xxh3(bytes, unclaimed)
   }
+  return { all: hex(all), unclaimed: hex(unclaimed), files }
+}
+
+function hex(h: bigint): string {
   return h.toString(16).padStart(16, '0')
 }

package/src/workspace/index.ts

@@ -1,9 +1,20 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { affectedProjects, defaultAffectedBase, workspaceGlobsMatch } from './affected.js'
+export {
+  affectedProjects,
+  defaultAffectedBase,
+  type FingerprintClaims,
+  refIsHead,
+  workspaceGlobsMatch,
+} from './affected.js'
 export { applyFilters, parseFilter } from './filter.js'
-export { computeWorkspaceFingerprint, WORKSPACE_FINGERPRINT_FILES } from './fingerprint.js'
+export {
+  computeWorkspaceFingerprint,
+  computeWorkspaceFingerprints,
+  WORKSPACE_FINGERPRINT_FILES,
+  type WorkspaceFingerprints,
+} from './fingerprint.js'
 export { computeNestedProjectDirs } from './nested-dirs.js'
 export { buildPackageGraph, type PackageGraph } from './package-graph.js'
 export {
@@ -11,6 +22,7 @@ export {
   LOCKFILE_NAME,
   LOCKFILE_VERSION,
   lockfilePath,
+  FROZEN_WITHOUT_LOCK,
   readLockfile,
   writeLockfile,
   type Lockfile,
@@ -20,20 +32,42 @@ export {
   loadProjectConfig,
   loadProjectConfigs,
   loadWorkspaceConfig,
-  validateProjectConfig,
+  WORKSPACE_CONFIG_FILENAMES,
 } from './project-loader.js'
+export { validateProjectConfig } from './config-schema.js'
 export type { LoadProjectConfigOptions } from './project-loader.js'
 export {
   blobOidOf,
   configEvalKey,
   configEvalKeyFromClosure,
+  configImports,
   type ConfigEvalStore,
 } from './config-cache.js'
 export {
   findWorkspaceRoot,
   listProjects,
   loadWorkspace,
+  unreachedHint,
+  unreachedPackages,
+  memberBaseDirs,
+  PROJECT_CONFIG_FILENAMES,
   resolveCacheDir,
   type ProjectEntry,
   type ProjectMeta,
 } from './workspace.js'
+export type { LoadReads } from './load-reads.js'
+// The migration seam (see migration.ts) and core's own mapper, the scripts one.
+export {
+  applyMigration,
+  foldScriptHooks,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+  quoteTsLiteral,
+  type ApplyMigrationArgs,
+  type MigrationFormat,
+  type GeneratedProject,
+  type GeneratedTask,
+  type MigrationPlan,
+  type RawExpr,
+} from './migration.js'
+export { delegatedScript, migrateScripts } from './migrate-scripts.js'

package/src/workspace/json-data.ts

@@ -0,0 +1,90 @@
+// A project config is JSON data (item 701).
+//
+// The cache key folds `JSON.stringify` of a task's config, `vx lock`
+// stores the same JSON, and a repeat load (`vx watch`) crosses back from
+// its worker as JSON. A value JSON cannot carry faithfully was therefore
+// refused by one path and dropped by another — `description: () => 'x'`
+// failed `vx run`'s first load ("must be a string") and passed the
+// worker's, which never saw it — or, where the validator does not type
+// the value, it was silently outside the key on both. So every path
+// refuses it, before schema validation, by this one rule: the first load
+// on the live object (`validateProjectConfig`), the worker before its
+// `JSON.stringify` (config-eval.ts), and the site's playground in its own
+// Worker. The two workers embed `nonJsonPaths` by its source text, so
+// the function must stay self-contained: no import, no module-scope name.
+//
+// An `undefined` PROPERTY is allowed: JSON drops it, the validator reads
+// it as absent, and configs write it with conditional spreads. Inside an
+// array it is refused, because JSON writes it as `null`.
+
+/** A value JSON cannot carry, at the path the validator would name. */
+export interface NonJsonValue {
+  path: string
+  /** What it is, as the message reads: `a function`, `NaN`, `an instance of Map`. */
+  is: string
+}
+
+/** Every value in `value` that `JSON.stringify` would drop, rewrite or throw on. */
+export function nonJsonPaths(value: unknown): NonJsonValue[] {
+  const out: NonJsonValue[] = []
+  // The key or index at each level, rendered only for a finding: the walk
+  // runs on every first load, and a path string built per node cost three
+  // times the schema check itself.
+  const keys: Array<string | number> = []
+  // The objects on the path to the one being walked: a cycle throws in
+  // `JSON.stringify` and would recurse here forever. A DAG is data.
+  const ancestors: object[] = []
+  const found = (is: string): void => {
+    let path = ''
+    for (const k of keys) path += typeof k === 'number' ? `[${k}]` : path === '' ? k : `.${k}`
+    out.push({ path: path === '' ? 'the default export' : path, is })
+  }
+  const walk = (v: unknown, inArray: boolean): void => {
+    if (typeof v === 'function') found('a function')
+    else if (typeof v === 'symbol') found('a symbol')
+    else if (typeof v === 'bigint') found('a bigint')
+    else if (typeof v === 'number' && !Number.isFinite(v)) found(String(v))
+    else if (v === undefined && inArray) found('undefined in an array, which JSON writes as null')
+    else if (typeof v === 'object' && v !== null) {
+      if (ancestors.includes(v)) {
+        found('a cyclic reference')
+        return
+      }
+      if (Array.isArray(v)) {
+        ancestors.push(v)
+        // By index, not `forEach`: a hole is `undefined` to JSON too.
+        for (let i = 0; i < v.length; i++) {
+          keys.push(i)
+          walk(v[i], true)
+          keys.pop()
+        }
+        ancestors.pop()
+        return
+      }
+      const proto: unknown = Object.getPrototypeOf(v)
+      if (proto !== Object.prototype && proto !== null) {
+        const name = (proto as { constructor?: { name?: unknown } }).constructor?.name
+        found(
+          typeof name === 'string' && name !== ''
+            ? `an instance of ${name}`
+            : 'an object whose prototype is not Object.prototype',
+        )
+        return
+      }
+      ancestors.push(v)
+      for (const key of Object.keys(v)) {
+        keys.push(key)
+        walk((v as Record<string, unknown>)[key], false)
+        keys.pop()
+      }
+      ancestors.pop()
+    }
+  }
+  walk(value, false)
+  return out
+}
+
+/** The refusal every path gives, the CLI's and the playground's. */
+export function nonJsonMessage(configPath: string, found: NonJsonValue): string {
+  return `${configPath}: ${found.path} is ${found.is} — a config must be JSON data, because the cache key folds its JSON`
+}

package/src/workspace/load-reads.ts

@@ -0,0 +1,32 @@
+// A load reads each root file once. Finding the root reads its manifest,
+// listing the package globs read it again and the workspace fingerprint a
+// third time. Every such read goes through a `LoadReads` the load owns, so
+// a file costs one probe and one read per load however many stages ask for
+// it. The map lives exactly as long as the load: a `vx watch` cycle is a
+// new load and reads fresh bytes.
+
+/** The files one load has read, by absolute path: the bytes, or null when no file is there. */
+export type LoadReads = Map<string, Promise<Uint8Array | null>>
+
+/**
+ * `file`'s bytes, read at most once per `reads`; null when there is no file
+ * there (`Bun.file(<dir>).exists()` is false, so a directory is none).
+ *
+ * The probe stays ahead of the read: most names asked about are absent (six
+ * of the seven fingerprint files, three of the four workspace config names),
+ * and a failed read costs 90–200 µs building its error where `exists()`
+ * answers in 15–40 µs (measured 2026-09-24) — so one stat per present file
+ * is cheaper than letting the open answer both questions.
+ */
+export function readOnce(reads: LoadReads | undefined, file: string): Promise<Uint8Array | null> {
+  const held = reads?.get(file)
+  if (held !== undefined) return held
+  const pending = readIfFile(file)
+  reads?.set(file, pending)
+  return pending
+}
+
+async function readIfFile(file: string): Promise<Uint8Array | null> {
+  const f = Bun.file(file)
+  return (await f.exists()) ? await f.bytes() : null
+}

package/src/workspace/lockfile.ts

@@ -2,19 +2,22 @@
 //
 // `vx lock` evaluates every project's vx.config.* in the CURRENT
 // environment and freezes the resolved objects (plus a content hash of
-// each config file) into `vx-lock.json` at the workspace root. While the
-// lock exists, runs load configs from it instead of evaluating —
-// frozen-env semantics. See docs/design/config-lock-2026-06.md.
+// each config file) into `vx-lock.json` at the workspace root. A run
+// under `--frozen` loads configs from it instead of evaluating —
+// frozen-env semantics; a plain run always evaluates live. See
+// docs/design/config-lock-2026-06.md.
 //
 // Verification asymmetry (deliberate):
-//   - runs TRUST the lock: hash-only staleness check, eval-free.
-//   - `vx lock --check` AUDITS it: full re-evaluation + deep equality,
-//     which catches eval-time env drift that file hashes cannot see.
+//   - `--frozen` runs TRUST the lock: no staleness check, eval-free.
+//   - `vx lock --check` AUDITS it: the file hashes, then full
+//     re-evaluation + deep equality, which catches eval-time env drift
+//     that file hashes cannot see.
 
+import { rename, rm } from 'node:fs/promises'
 import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
 import { relPosix, UserError } from '../util/index.js'
-import { validateProjectConfig } from './project-loader.js'
+import { validateProjectConfig } from './config-schema.js'
 
 export const LOCKFILE_NAME = 'vx-lock.json'
 export const LOCKFILE_VERSION = 1
@@ -37,6 +40,10 @@ export function lockfilePath(root: string): string {
   return path.join(root, LOCKFILE_NAME)
 }
 
+/** What a `--frozen` verb says when there is no lock to read. */
+export const FROZEN_WITHOUT_LOCK =
+  "--frozen requires vx-lock.json at the workspace root — run 'vx lock' and commit it"
+
 /**
  * Read and shape-validate `vx-lock.json`. Returns `null` when no lock
  * exists (the common case — the feature is opt-in). The lock is a
@@ -92,16 +99,36 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
 }
 
 export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
-  await Bun.write(lockfilePath(root), `${JSON.stringify(lock, null, 2)}\n`)
+  // Written beside its name and renamed over it: `Bun.write` truncates in
+  // place, so a `--frozen` run, or `vx watch --frozen` woken by the write
+  // itself (item 971), could read an empty or half-written lock and fail
+  // on "not valid JSON" (item 972).
+  const file = lockfilePath(root)
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
+  try {
+    await Bun.write(tmp, `${JSON.stringify(lock, null, 2)}\n`)
+    await rename(tmp, file)
+  } catch (err) {
+    // Best effort: where the write was refused the temp cannot be named
+    // either (ENOTDIR), and that must not replace the refusal itself.
+    await rm(tmp, { force: true }).catch(() => {})
+    // The refusal names the file the user knows: a read-only checkout read
+    // `open '…/vx-lock.json.tmp-…'` where it had read the lock's own name.
+    const e = err as NodeJS.ErrnoException
+    if (typeof e.message === 'string') e.message = e.message.split(tmp).join(file)
+    if (e.path === tmp) e.path = file
+    throw err
+  }
 }
 
 /**
- * Run-time config load from the lock: verify the config file's content
- * hash against the lock entry, then return the FROZEN resolved config.
- * No evaluation happens — this is the fast, eval-free trust path. A
- * changed file or an unlocked project is a hard error: the lock's
- * contract is "what runs is what was locked", and silently falling
- * back to evaluation would break frozen-env semantics.
+ * Run-time config load from the lock: return the FROZEN resolved config
+ * for a project the lock has an entry for. No evaluation happens — this
+ * is the fast, eval-free trust path — and no staleness check either (see
+ * below): the lock's contract is "what runs is what was locked", so a
+ * config file edited since `vx lock` still runs as locked until
+ * `vx lock --check` says otherwise. An unlocked project is a hard error;
+ * silently falling back to evaluation would break frozen-env semantics.
  */
 export async function frozenProjectConfig(
   lock: Lockfile,