@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/prepare.ts

@@ -8,10 +8,11 @@
 // try/finally around its plan() call.
 
 import path from 'node:path'
-import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import type { WorkspaceConfig } from '../config.js'
 import { mark, UserError } from '../util/index.js'
 import {
   Cache,
+  noteSchemaReset,
   type CacheLayer,
   type CachePolicy,
   FULL_CACHE_POLICY,
@@ -25,34 +26,35 @@ import {
 import {
   buildPackageGraph,
   computeNestedProjectDirs,
-  computeWorkspaceFingerprint,
+  computeWorkspaceFingerprints,
   findWorkspaceRoot,
-  frozenProjectConfig,
+  type LoadReads,
   listProjects,
-  loadProjectConfigs,
   loadWorkspace,
-  loadWorkspaceConfig,
+  FROZEN_WITHOUT_LOCK,
   readLockfile,
   resolveCacheDir,
-  validateProjectConfig,
   type ProjectEntry,
 } from '../workspace/index.js'
 import {
   buildTaskGraph,
+  excludeDependencies,
   expandRequested,
-  parseDependencySpec,
   type TaskNode,
+  undeclaredDepsError,
   unresolvedRequests,
 } from '../graph/index.js'
 import {
-  applyConfigHooks,
   applyGraphHooks,
   applyKeyHooks,
-  applyProjectHooks,
   applyScheduleHooks,
+  fingerprintClaims,
   hasHook,
   resolveCache,
 } from './plugin-host.js'
+import { loadProjects, loadWorkspacePlugins, type LoadedProjects } from './projects.js'
+import { keyExcludedDependencies } from './excluded-keys.js'
+import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import type { Logger } from './logger.js'
@@ -76,8 +78,7 @@ export interface PreparedRun {
    * injected remote layer, or one a plugin's `cache` capability built. The
    * remote axes of the policy only mean anything then: without a remote
    * layer a `remote:w` policy writes NOWHERE, so a task that believed it
-   * would be saved still cleans its outputs before executing and (under
-   * `--verify`) restores an artifact that was never written.
+   * would be saved still cleans its outputs before executing.
    */
   hasRemoteLayer: boolean
   /**
@@ -96,7 +97,15 @@ export interface PreparedRun {
   unresolvedTasks: readonly string[]
   /** Every discovered project — the declared task names a typo is measured against. */
   projects: ReadonlyMap<string, ProjectEntry>
+  /**
+   * True iff at least one package in the workspace has a `vx.config.*` at
+   * all — regardless of scope, so a `--filter` that matched nothing is not
+   * mistaken for a workspace vx was never set up in.
+   */
+  anyProjectConfig: boolean
   workspaceFingerprint: string
+  /** Whether a task has since rewritten what that fingerprint folded (fingerprint-watch.ts). */
+  fingerprintWatch: FingerprintWatch
   nestedDirsByProject: Map<string, string[]>
   /**
    * Per-run memo for `git ls-files` output, keyed by project dir.
@@ -129,25 +138,6 @@ export interface PreparedRun {
   empty: null | 'no-tasks-declared' | 'empty-graph'
 }
 
-/** Project names named by a `pkg#task` dependsOn entry anywhere in `config`. */
-function crossDepProjects(config: ProjectConfig): string[] {
-  const out: string[] = []
-  for (const task of Object.values(config.tasks ?? {})) {
-    for (const raw of task.dependsOn ?? []) {
-      // A malformed spec is the graph builder's error to report — it names
-      // the offending task. Here it just contributes no project.
-      if (!raw.includes('#')) continue
-      try {
-        const spec = parseDependencySpec(raw)
-        if (spec.kind === 'cross') out.push(spec.project)
-      } catch {
-        continue
-      }
-    }
-  }
-  return out
-}
-
 /**
  * Build the prepared-run context: workspace discovery, project-config
  * load, package + task graph, cache handle (local, optionally wrapped
@@ -160,7 +150,10 @@ function crossDepProjects(config: ProjectConfig): string[] {
  */
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
   mark('startup')
-  const workspaceRoot = await findWorkspaceRoot(options.cwd)
+  // The root manifest is read once for the root, the globs and the
+  // fingerprint. A watch cycle is a new run and reads it afresh.
+  const reads: LoadReads = new Map()
+  const workspaceRoot = await findWorkspaceRoot(options.cwd, reads)
   // An UNSCOPED run (no explicit scope, at least one bare task name)
   // enumerates the whole tree whatever the configs say, so git starts
   // HERE — the walk needs only the root — and overlaps the workspace
@@ -177,17 +170,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // handler keeps that from surfacing as an unhandled rejection (the real
   // await further down still sees the error).
   earlyGit?.catch(() => {})
-  const workspace = await loadWorkspace(workspaceRoot)
-  const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
-  // The `config` stage runs before anything is derived from the workspace
-  // config; the plugin list itself is already fixed.
-  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
-  if (workspaceConfig !== null && hasHook(plugins, 'config')) {
-    await applyConfigHooks(plugins, workspaceConfig, {
-      workspaceRoot,
-      warn: (m) => log.status(m),
-    })
-  }
+  const workspace = await loadWorkspace(workspaceRoot, reads)
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, (m) =>
+    log.status(m),
+  )
   mark('workspace config')
   const projectMetas = await listProjects(workspace)
   mark('discover projects')
@@ -201,17 +187,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // Turbo-like: a broken config in an unrelated package no longer
   // fails a scoped run — it surfaces when that package enters scope.
   const packageGraph = buildPackageGraph(projectMetas)
-  const projectsWithConfigs = projectMetas.filter(
-    (m): m is typeof m & { configPath: string } =>
-      typeof m.configPath === 'string' && m.configPath.length > 0,
-  )
-  const haveConfig = new Set(projectsWithConfigs.map((m) => m.name))
-
-  // Seeds: explicit scope, plus anchored pkg#task targets (which
-  // bypass scope by design). With no explicit scope, bare task names
-  // fan out across the whole workspace — but when EVERY spec is
-  // anchored, the anchors alone are the scope and nothing else needs
-  // its config evaluated.
+  // Seeds: explicit scope, plus anchored pkg#task targets (which bypass
+  // scope by design). With no explicit scope, bare task names fan out
+  // across the whole workspace — but when EVERY spec is anchored, the
+  // anchors alone are the scope and nothing else needs its config
+  // evaluated.
   const anchored: string[] = []
   let hasBare = false
   for (const spec of options.tasks) {
@@ -219,16 +199,13 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     if (hashIdx > 0) anchored.push(spec.slice(0, hashIdx))
     else hasBare = true
   }
-  const seeds = new Set<string>(
-    options.projects
-      ? options.projects.filter((p) => haveConfig.has(p))
-      : hasBare
-        ? haveConfig
-        : [],
-  )
-  for (const project of anchored) {
-    if (haveConfig.has(project)) seeds.add(project)
-  }
+  const seeds: 'all' | string[] =
+    options.projects !== undefined ? [...options.projects, ...anchored] : hasBare ? 'all' : anchored
+  // Its own mark: the package graph is the bulk of what used to be charged
+  // to `open cache` (measured on a 1,000-project tree, 2026-09-20 — the
+  // graph 3-8 ms against the cache open's ~1 ms and the fingerprints' ~0.3),
+  // so a reader profiling that stage was sent to the wrong code.
+  mark('package graph')
 
   // The local cache opens BEFORE the configs load: it is also where their
   // cached evaluations live. `--cache-dir <path>` (RunOptions.cacheDir)
@@ -238,26 +215,26 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const cacheDir = options.cacheDir
     ? path.resolve(options.cwd, options.cacheDir)
     : resolveCacheDir(workspaceRoot, workspaceConfig)
-  const localCache = new Cache(cacheDir, { read: policy.localRead, write: policy.localWrite })
-  const workspaceFingerprint = await computeWorkspaceFingerprint(workspaceRoot)
+  const localCache = new Cache(
+    cacheDir,
+    { read: policy.localRead, write: policy.localWrite },
+    workspaceRoot,
+    options.artifactCeiling,
+  )
+  localCache.assertWritable()
+  noteSchemaReset(localCache, (m) => log.status(m))
+  // Two digests from one read: the config-evaluation cache keys on every
+  // file (a config may import a dependency), the task keys on the files no
+  // plugin claims (`VxPlugin.fingerprint`).
+  const fingerprintsAt = Date.now()
+  const fingerprints = await computeWorkspaceFingerprints(
+    workspaceRoot,
+    new Set(fingerprintClaims(plugins).keys()),
+    reads,
+  )
+  const workspaceFingerprint = fingerprints.unclaimed
   mark('open cache')
 
-  type ConfigMeta = (typeof projectsWithConfigs)[number]
-  const metaByName = new Map<string, ConfigMeta>(projectsWithConfigs.map((m) => [m.name, m]))
-  const needed = new Set<string>()
-  const pending: ConfigMeta[] = []
-  const consider = (name: string): void => {
-    if (needed.has(name)) return
-    needed.add(name)
-    const meta = metaByName.get(name)
-    if (meta) pending.push(meta)
-  }
-  const considerWithDeps = (name: string): void => {
-    consider(name)
-    for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
-  }
-  for (const seed of seeds) considerWithDeps(seed)
-
   // Frozen mode (--frozen, CI): configs load FROM vx-lock.json after a
   // content-hash tripwire — no evaluation; env-dependent configs keep
   // their locked values. Default (local) runs ALWAYS evaluate live:
@@ -267,55 +244,34 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // See docs/design/config-lock-2026-06.md.
   const lock = options.frozen === true ? await readLockfile(workspaceRoot) : null
   if (options.frozen === true && lock === null) {
-    throw new UserError(
-      `--frozen requires vx-lock.json at the workspace root — run 'vx lock' and commit it`,
-    )
+    throw new UserError(FROZEN_WITHOUT_LOCK)
   }
 
-  // Load in rounds to a fixpoint. A `pkg#task` dependsOn entry names a
-  // project the PACKAGE graph cannot reach (the cross form ignores npm
-  // deps by design), so its config has to be pulled in — and that config
-  // may declare cross edges of its own. The common case (no cross deps)
-  // is a single round, identical to loading the closure in one batch.
-  const projects = new Map<string, ProjectEntry>()
-  const projectStage = hasHook(plugins, 'project')
+  const loadArgs = {
+    workspaceRoot,
+    cacheDir,
+    plugins,
+    projectMetas,
+    packageGraph,
+    lock,
+    evalCache: { store: localCache, workspaceFingerprint: fingerprints.all },
+    warn: (m: string) => log.status(m),
+  }
+  let loaded: LoadedProjects
   try {
-    while (pending.length > 0) {
-      const round = pending.splice(0, pending.length)
-      const configs = lock
-        ? await Promise.all(round.map((m) => frozenProjectConfig(lock, m, workspaceRoot)))
-        : await loadProjectConfigs(
-            round.map((m) => m.configPath),
-            { evalCache: { store: localCache, workspaceFingerprint } },
-          )
-      for (let i = 0; i < round.length; i++) {
-        const meta = round[i]!
-        const config = configs[i] as ProjectConfig
-        if (projectStage) {
-          // The `project` stage edits the validated object in place; core
-          // then re-validates so a plugin can only produce what the loader
-          // accepts from a user. The message names the config file — the
-          // plugin's edit is a defect in THAT project's tasks.
-          await applyProjectHooks(plugins, config, {
-            workspaceRoot,
-            cacheDir,
-            warn: (m) => log.status(m),
-            name: meta.name,
-            dir: meta.dir,
-            packageJson: meta.packageJson as unknown as Readonly<Record<string, unknown>>,
-          })
-          validateProjectConfig(config, `${meta.configPath} (after plugins)`)
-        }
-        projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
-        for (const name of crossDepProjects(config)) considerWithDeps(name)
-      }
-    }
+    loaded = await loadProjects({
+      ...loadArgs,
+      seeds,
+      closure: true,
+      ...(options.staged !== undefined ? { staged: options.staged } : {}),
+    })
   } catch (err) {
     // The cache opened before the configs loaded (it holds their cached
     // evaluations); a config error must not leak the handle.
     localCache.close()
     throw err
   }
+  const { projects, configured: projectsWithConfigs } = loaded
   mark('load configs')
 
   // Boundary geometry considers every config-bearing project in the
@@ -333,24 +289,32 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const unresolvedTasks = unresolvedRequests(options.tasks, candidateProjects, projects)
 
   // Cache seam precedence: an EXPLICITLY injected remote layer
-  // (RunOptions.remoteCache — a distribution agent or serve that already
+  // (RunOptions.remoteCache — a distribution agent or daemon that already
   // holds a wire client) wins outright; else a plugin's `cache` capability;
   // else the local cache alone. Core ships no wire client — the remote
-  // cache is a plugin concern (native-cache-wire-2026-07). Injection
+  // cache is a plugin concern (docs/patterns.md § Remote cache wire). Injection
   // winning prevents double-wrapping when the workspace also declares a
   // cache plugin.
-  const cache = options.remoteCache
-    ? new LayeredCache(localCache, options.remoteCache, {
-        policy,
-        onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
-      })
-    : await resolveCache(plugins, {
-        workspaceRoot,
-        cacheDir,
-        warn: (m) => log.status(m),
-        localCache,
-        policy,
-      })
+  let cache: CacheLayer
+  try {
+    cache = options.remoteCache
+      ? new LayeredCache(localCache, options.remoteCache, {
+          policy,
+          onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
+        })
+      : await resolveCache(plugins, {
+          workspaceRoot,
+          cacheDir,
+          warn: (m) => log.status(m),
+          localCache,
+          policy,
+        })
+  } catch (err) {
+    // A cache plugin that throws or returns something off-contract is
+    // refused by name; the local handle opened above must not leak with it.
+    localCache.close()
+    throw err
+  }
   // Ask the LAYER, don't infer. Identity against `localCache` answers a
   // DIFFERENT question — "did the plugin hand back something other than the
   // handle I passed in?" — which an ordinary pass-through decorator (a
@@ -381,6 +345,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   applyGitEnumeration(enumeration, workspaceRoot, projectDirs, gitFilesCache, usesWorkspaceInputs)
   mark('git enumeration')
   const hashCache = createHashCache()
+  const fingerprintWatch = new FingerprintWatch(workspaceRoot, fingerprints, fingerprintsAt)
 
   // Empty-cases bookkeeping. We still construct the cache + fingerprint
   // so the caller's try/finally pattern can close it uniformly.
@@ -397,7 +362,9 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       nodes: new Map(),
       unresolvedTasks,
       projects,
+      anyProjectConfig: projectsWithConfigs.length > 0,
       workspaceFingerprint,
+      fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache,
       hashCache,
@@ -406,14 +373,31 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     }
   }
 
+  // The whole graph, whatever `--exclude-dependencies` says: the stages
+  // below shape and key the tasks it drops as a full run would, because
+  // a dropped task is still keyed (excluded-keys.ts). A scoped load is not
+  // the whole workspace: a `^name` nothing loaded declares may be declared
+  // by a config the scope left out, so the builder hands it back instead of
+  // refusing it, and the rest decide.
+  const unproven: Array<[taskId: string, name: string]> = []
   const nodes = buildTaskGraph({
     projects,
     packageGraph,
     requested,
-    ...(options.excludeDependencies !== undefined
-      ? { excludeDependencies: options.excludeDependencies }
+    ...(projects.size < projectsWithConfigs.length
+      ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
       : {}),
   })
+  if (unproven.length > 0) {
+    await refuseUndeclaredDeps(unproven, () =>
+      loadProjects({ ...loadArgs, seeds: 'all', closure: false, staged: projects }),
+    )
+  }
+  // The graph is built; what follows is the plugins' (graph, key,
+  // schedule). Two rows, so a plugin's key stage reads as its own cost
+  // and not as graph building — a lockfile plugin's 1000 stats per run
+  // hid inside one `prepare (graph)` row until 2026-09-10.
+  mark('build graph')
   if (hasHook(plugins, 'graph')) {
     await applyGraphHooks(plugins, nodes, {
       workspaceRoot,
@@ -425,6 +409,24 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   if (hasHook(plugins, 'key')) {
     await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: (m) => log.status(m) })
   }
+  const exclude = options.excludeDependencies
+  if (exclude !== undefined && (exclude === 'all' || exclude.length > 0)) {
+    const { keyOnly, dropped } = excludeDependencies(nodes, exclude)
+    if (dropped.size > 0) {
+      await keyExcludedDependencies({
+        nodes,
+        keyOnly,
+        dropped,
+        cache,
+        workspaceRoot,
+        workspaceFingerprint,
+        forwardArgs: options.forwardArgs,
+        nestedDirsByProject,
+        gitFilesCache,
+        hashCache,
+      })
+    }
+  }
   let priorities: ReadonlyMap<string, number> = new Map()
   if (hasHook(plugins, 'schedule')) {
     priorities = await applyScheduleHooks(plugins, nodes, {
@@ -447,7 +449,9 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     nodes,
     unresolvedTasks,
     projects,
+    anyProjectConfig: projectsWithConfigs.length > 0,
     workspaceFingerprint,
+    fingerprintWatch,
     nestedDirsByProject,
     gitFilesCache,
     hashCache,
@@ -455,3 +459,30 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     empty: nodes.size === 0 ? 'empty-graph' : null,
   }
 }
+
+/**
+ * Refuses the first `^name` in `unproven` that no project in the whole
+ * workspace declares. `load` evaluates the configs a scoped run left out;
+ * it is reached only when a `^name` found no holder and nothing loaded
+ * declares it, so a run that names only declared tasks never pays for it.
+ * The rest failing to load leaves the names unjudged: an out-of-scope
+ * broken config does not fail a scoped run.
+ */
+async function refuseUndeclaredDeps(
+  unproven: ReadonlyArray<readonly [taskId: string, name: string]>,
+  load: () => Promise<LoadedProjects>,
+): Promise<void> {
+  let all: LoadedProjects
+  try {
+    all = await load()
+  } catch {
+    return
+  }
+  const declared = new Set<string>()
+  for (const p of all.projects.values()) {
+    for (const t of Object.keys(p.config.tasks ?? {})) declared.add(t)
+  }
+  for (const [id, name] of unproven) {
+    if (!declared.has(name)) throw undeclaredDepsError(id, name)
+  }
+}