@vzn/vx 0.0.16 → 0.0.21

package/src/workspace/filter.ts

@@ -1,6 +1,6 @@
-// Filter DSL — pnpm-style selectors for `-F / --filter`.
+// Filter DSL — pnpm-style selectors for `--filter`.
 //
-//   <pattern>        name glob (e.g. foo, @scope/*)
+//   <pattern>        name glob, `*` = any characters (e.g. foo, @scope/*)
 //   ./<dir>          packages whose dir is at or under <dir> (relative to workspace root)
 //   {<dir>}          same as ./<dir>
 //   <pattern>...     pattern + its transitive workspace dependencies
@@ -34,6 +34,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 {
@@ -71,15 +75,35 @@ 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.
+    if (/[*?[\]{}]/.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,
+    isPath,
+    matcher,
+    ...(pathGlob !== undefined ? { pathGlob, pathRoot: workspaceRoot } : {}),
+  }
 }
 
 function matchProjects(
@@ -95,6 +119,19 @@ function matchProjects(
   }
   const out: string[] = []
   if (filter.isPath) {
+    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
+    }
     const prefix = filter.matcher + path.sep
     for (const p of projects) {
       if (p.dir === filter.matcher || p.dir.startsWith(prefix)) out.push(p.name)
@@ -107,13 +144,24 @@ function matchProjects(
     }
     return out
   }
-  const glob = new Bun.Glob(filter.matcher)
+  const re = compileNameGlob(filter.matcher)
   for (const p of projects) {
-    if (glob.match(p.name)) out.push(p.name)
+    if (re.test(p.name)) out.push(p.name)
   }
   return out
 }
 
+/**
+ * Compile a name pattern where `*` is the sole metacharacter and means "any
+ * characters" — pnpm's rule. A path glob would treat `/` as a separator, so
+ * `*` could never cross the `@scope/` boundary: `--filter '*'` would select
+ * only UNSCOPED packages, and `*core*` would match nothing at all.
+ */
+function compileNameGlob(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
 export interface ApplyFiltersOptions {
   filters: ParsedFilter[]
   projects: ProjectMeta[]
@@ -125,6 +173,12 @@ export interface ApplyFiltersOptions {
    * stays pure + sync.
    */
   affectedByFilter?: Map<ParsedFilter, Set<string>>
+  /**
+   * 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.
+   */
+  onNoMatch?: (filter: ParsedFilter) => void
 }
 
 export function applyFilters(opts: ApplyFiltersOptions): Set<string> {
@@ -134,6 +188,7 @@ export function applyFilters(opts: ApplyFiltersOptions): 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)

package/src/workspace/fingerprint.ts

@@ -8,7 +8,11 @@ import { xxh3 } from '../util/index.js'
 // for projects that have that file present, which is fine: that's the
 // whole point of bumping CACHE_VERSION when the fingerprint surface
 // expands.
-const WORKSPACE_FINGERPRINT_FILES = [
+// Exported so `--affected` can consult the SAME list. A change to any of
+// these re-keys every task in the workspace, so selection has to widen to
+// match — two copies of this list would silently drift into a run that
+// rebuilds everything while selecting nothing.
+export const WORKSPACE_FINGERPRINT_FILES = [
   // Lockfiles
   'pnpm-lock.yaml',
   'package-lock.json',
@@ -21,6 +25,17 @@ const WORKSPACE_FINGERPRINT_FILES = [
   'pnpm-workspace.yaml',
 ]
 
+// DELIBERATELY ABSENT: `vx.workspace.{ts,mts,js,mjs}`. Everything it can
+// declare — `concurrency`, `cacheDir`, `timeout`, and the
+// plugin list — is placement, storage or observability, never what a
+// command produces; core's three seams may change WHERE a task runs, not
+// WHAT it runs (architecture principle #3). Folding it in would also do
+// active harm: a laptop declaring only the local plugins and a CI runner
+// declaring `reapi()` would compute different fingerprints and share not
+// one cache entry — the same split the rejected `NODE_OPTIONS` non-goal
+// describes. A per-task input that genuinely varies belongs in
+// `cache.inputs`, which is the surface built for it.
+
 /**
  * One hash for the workspace as a whole, derived from whichever
  * lockfile + workspace-definition files exist at the root. Folded
@@ -29,13 +44,47 @@ const WORKSPACE_FINGERPRINT_FILES = [
  * invalidates every cached entry. Coarse but correct.
  */
 export async function computeWorkspaceFingerprint(workspaceRoot: string): Promise<string> {
-  let h = 0n
+  return (await computeWorkspaceFingerprints(workspaceRoot, NONE)).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
+}
+
+/**
+ * Both digests from one read of each file. 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>,
+): Promise<WorkspaceFingerprints> {
+  let all = 0n
+  let unclaimed = 0n
   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 file.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) }
+}
+
+function hex(h: bigint): string {
   return h.toString(16).padStart(16, '0')
 }

package/src/workspace/index.ts

@@ -1,9 +1,19 @@
 // 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 } from './affected.js'
+export {
+  affectedProjects,
+  defaultAffectedBase,
+  type FingerprintClaims,
+  workspaceGlobsMatch,
+} from './affected.js'
 export { applyFilters, parseFilter } from './filter.js'
-export { computeWorkspaceFingerprint } 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,17 +21,46 @@ export {
   LOCKFILE_NAME,
   LOCKFILE_VERSION,
   lockfilePath,
+  FROZEN_WITHOUT_LOCK,
   readLockfile,
   writeLockfile,
   type Lockfile,
   type LockfileEntry,
 } from './lockfile.js'
-export { loadProjectConfig, loadWorkspaceConfig } from './project-loader.js'
+export {
+  loadProjectConfig,
+  loadProjectConfigs,
+  loadWorkspaceConfig,
+  WORKSPACE_CONFIG_FILENAMES,
+} from './project-loader.js'
+export { validateProjectConfig } from './config-schema.js'
+export type { LoadProjectConfigOptions } from './project-loader.js'
+export {
+  blobOidOf,
+  configEvalKey,
+  configEvalKeyFromClosure,
+  type ConfigEvalStore,
+} from './config-cache.js'
 export {
   findWorkspaceRoot,
   listProjects,
   loadWorkspace,
+  memberBaseDirs,
   resolveCacheDir,
   type ProjectEntry,
   type ProjectMeta,
 } from './workspace.js'
+// The migration seam (see migration.ts) and core's own mapper, the scripts one.
+export {
+  applyMigration,
+  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/lockfile.ts

@@ -14,7 +14,7 @@
 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
@@ -43,6 +43,10 @@ export function lockfilePath(root: string): string {
  * user-editable file, so this is a system boundary: malformed content
  * throws a `UserError` instead of crashing deeper in the run.
  */
+/** 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"
+
 export async function readLockfile(root: string): Promise<Lockfile | null> {
   const file = Bun.file(lockfilePath(root))
   if (!(await file.exists())) return null
@@ -52,7 +56,14 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
   } catch {
     throw new UserError(`${LOCKFILE_NAME} is not valid JSON — re-run \`vx lock\` or delete it`)
   }
-  if (typeof parsed !== 'object' || parsed === null) {
+  // `Array.isArray` is not redundant with the `typeof` check: `typeof [] ===
+  // 'object'` and `[] !== null`, so an array sails through and the NEXT check
+  // reports `unsupported version undefined` — a version diagnostic for what is
+  // actually a shape problem, sending the reader to re-run `vx lock` for a file
+  // that was never the right shape. `validateProjectConfig` one layer down
+  // already guards this explicitly, which is what makes the omission here an
+  // inconsistency rather than an oversight.
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     throw new UserError(`${LOCKFILE_NAME} must be a JSON object — re-run \`vx lock\``)
   }
   const lock = parsed as { version?: unknown; projects?: unknown }
@@ -62,7 +73,11 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
         `(this vx expects ${LOCKFILE_VERSION}) — re-run \`vx lock\``,
     )
   }
-  if (typeof lock.projects !== 'object' || lock.projects === null) {
+  // Same trap, and this one is worse than a bad message: an ARRAY of entries is
+  // ACCEPTED, because `Object.entries` happily walks it — yielding a project
+  // literally named "0". `--frozen` then looks up real project names against a
+  // lock that declares none of them.
+  if (typeof lock.projects !== 'object' || lock.projects === null || Array.isArray(lock.projects)) {
     throw new UserError(`${LOCKFILE_NAME}: \`projects\` must be an object — re-run \`vx lock\``)
   }
   for (const [name, entry] of Object.entries(lock.projects)) {
@@ -85,12 +100,13 @@ export async function writeLockfile(root: string, lock: Lockfile): Promise<void>
 }
 
 /**
- * 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,

package/src/workspace/migrate-scripts.ts

@@ -0,0 +1,134 @@
+// package.json scripts → vx tasks: the source for a workspace that comes
+// from nowhere (no turbo.json, no nx). `vx init` is this mapper.
+//
+// Scripts carry a command and nothing else, so the mapping is honest about
+// what it cannot know: every task gets `exec.command` verbatim; `build`
+// gets the conventional `dependsOn: ['^build']` and `test` / `typecheck`
+// wait for `build` when the package has one (`lint` does not); a dev-server
+// shaped script becomes persistent. Caching is opt-in and needs declared
+// inputs AND outputs, which a script cannot tell us — so NO task gets a
+// cache block; `build` carries a TODO showing the block to add. Until
+// 2026-09-04 `build` was emitted with whole-project inputs and EMPTY
+// outputs "to fill in": that is not an uncached task but a no-output one —
+// it hits on unchanged inputs and skips the build with nothing to restore,
+// so a deleted `dist` stayed deleted under a green `up-to-date` run
+// (reproduced on the init walkthrough). A block that guessed `dist/**`
+// would restore the wrong tree for every package that writes somewhere
+// else, and a wrong restore is the worst failure vx has.
+//
+// Two npm conventions are mapped rather than copied, because copying them
+// loses behaviour: `pre<x>` / `post<x>` hooks, which npm runs around `x`
+// without being named, are folded into `x`'s command in that order (a
+// standalone `prebuild` task is one `vx run build` never runs — and the
+// hook is usually `rimraf dist`); and a script that is nothing but
+// `<pm> run <other>` becomes a GROUP over `<other>`, so the graph sees the
+// dependency instead of a package-manager subprocess it cannot cache.
+
+import type { ProjectMeta } from './workspace.js'
+import {
+  type GeneratedProject,
+  type GeneratedTask,
+  type MigrationPlan,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+} from './migration.js'
+
+// `lint` is not here: a linter reads sources, and an edge to `build`
+// serialises the two for nothing (the init walkthrough, 2026-09-04).
+const AFTER_BUILD = new Set(['test', 'typecheck', 'check', 'e2e'])
+const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepublishOnly|install)$/
+
+/**
+ * The script a command delegates to when it is NOTHING but a package-manager
+ * invocation of another script: `npm run x`, `pnpm x`, `yarn run x`, `bun run
+ * x`, plus npm's bare `npm test` / `npm start`. Flags, arguments or a chain
+ * make it a real command again, which is left verbatim.
+ */
+export function delegatedScript(command: string): string | null {
+  const m =
+    /^(?:(?:npm run|pnpm(?: run)?|yarn(?: run)?|bun(?: run)?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+      command.trim(),
+    )
+  return m === null ? null : (m[1] ?? m[2])!
+}
+
+function scriptsOf(meta: ProjectMeta): Record<string, unknown> {
+  // package.json is a boundary: `scripts` is whatever the file holds. A
+  // string or an array would enumerate its indices as script names.
+  const raw = (meta.packageJson as unknown as { scripts?: unknown }).scripts
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {}
+  return raw as Record<string, unknown>
+}
+
+export function migrateScripts(metas: readonly ProjectMeta[]): MigrationPlan {
+  const projects: GeneratedProject[] = []
+  for (const meta of metas) {
+    const scripts = scriptsOf(meta)
+    const names = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '',
+    )
+    if (names.length === 0) continue
+    const hasBuild = names.includes('build')
+    const has = (n: string): boolean => names.includes(n)
+    const tasks: GeneratedTask[] = []
+    for (const name of names) {
+      // Lifecycle hooks are npm's, not tasks anyone runs by name.
+      if (LIFECYCLE.test(name)) continue
+      // A hook of a script that exists rides inside that script's command.
+      const hookOf = /^(pre|post)(.+)$/.exec(name)
+      if (hookOf !== null && has(hookOf[2]!) && !LIFECYCLE.test(hookOf[2]!)) continue
+
+      const todos: string[] = []
+      const own = scripts[name] as string
+      const delegate = delegatedScript(own)
+      // npm lifecycle hooks (`prepack`, `prepublishOnly`, …) belong to the
+      // package manager and never ride inside a task — `pack` stays alone.
+      const hook = (h: string): boolean => has(h) && !LIFECYCLE.test(h)
+      const hooks = [`pre${name}`, `post${name}`].filter(hook)
+      if (delegate !== null && has(delegate) && delegate !== name && hooks.length === 0) {
+        // A group: no exec, the graph runs the target. `npm test` calling
+        // `vitest` through `npm run test:unit` is two tasks, not a subprocess.
+        const task: Record<string, unknown> = { dependsOn: [delegate] }
+        if (AFTER_BUILD.has(name) && hasBuild && delegate !== 'build') {
+          task['dependsOn'] = [delegate, 'build']
+        }
+        tasks.push({ name, todos, task })
+        continue
+      }
+
+      const command = [
+        ...(hook(`pre${name}`) ? [scripts[`pre${name}`] as string] : []),
+        own,
+        ...(hook(`post${name}`) ? [scripts[`post${name}`] as string] : []),
+      ].join(' && ')
+      if (hooks.length > 0) {
+        todos.push(
+          `npm ran ${hooks.map((h) => `\`${h}\``).join(' and ')} around this script without being asked; folded into the command in that order`,
+        )
+      }
+      const task: Record<string, unknown> = { exec: { command } }
+      if (PERSISTENT_TASK_NAMES.has(name)) {
+        task['exec'] = { command, persistent: {} }
+        todos.push(PERSISTENT_TODO)
+      }
+      if (name === 'build') {
+        task['dependsOn'] = ['^build']
+        todos.push(
+          "cache: add `cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } }` with this package's real inputs and outputs — without it the task always runs; a block with EMPTY outputs would be a cached no-op, not an uncached task",
+        )
+      } else if (AFTER_BUILD.has(name) && hasBuild) {
+        task['dependsOn'] = ['build']
+      }
+      tasks.push({ name, todos, task })
+    }
+    if (tasks.length > 0) projects.push({ name: meta.name, dir: meta.dir, importLines: [], tasks })
+  }
+  return {
+    headerNotes: [
+      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so no task got a cache block — `build` carries a TODO showing the one to add',
+    ],
+    projects,
+    extraFiles: [],
+    notes: [],
+  }
+}