@vzn/vx 0.0.636 → 0.0.637

package/src/cli/lock.ts

@@ -1,24 +1,44 @@
-// `vx lock` — freeze every resolved vx.config.* into vx-lock.json.
+// `vx lock` — freeze every resolved vx.config.* into .vx/projects.lock.json, and
+// each one, pretty, into a `vx.lock.json` beside it for review.
 // `vx lock --check` — audit the lock against a fresh evaluation in the
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
+import { open } from 'node:fs/promises'
+import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
-import { relPosix, secretMask, xxh3hex } from '../util/index.js'
+import { buildTaskGraph, expandRequested } from '../graph/index.js'
 import {
+  applyGraphStage,
+  discoverProjects,
+  hasHook,
+  isDefaultBuild,
+  loadProjects,
+} from '../orchestrator/index.js'
+import { resolveSetting, runRules } from '../settings.js'
+import {
+  configErrorFrame,
+  DOT_VX_GITATTRIBUTES,
+  isUserError,
+  relPosix,
+  secretMask,
+} from '../util/index.js'
+import {
+  findProjectConfigs,
   findWorkspaceRoot,
-  type LoadReads,
-  loadProjectConfig,
-  loadWorkspace,
+  loadProjectConfigs,
   LOCKFILE_NAME,
   LOCKFILE_VERSION,
+  lockKey,
   readLockfile,
+  buildPackageGraph,
+  checkDependencyRules,
   writeLockfile,
   type Lockfile,
-  type LockfileEntry,
   type ProjectMeta,
 } from '../workspace/index.js'
-import { discoverCliProjects } from './workspace-config.js'
+import { taskEdgesFrom } from './select.js'
+import { loadCliWorkspace, warnToStderr } from './workspace-config.js'
 
 interface LockArgs {
   check: boolean
@@ -57,55 +77,238 @@ export async function lockCmd(args: readonly string[]): Promise<number> {
       `--format json answers --check only${seeHelp('lock')}`,
       'VX_E_USAGE',
     )
-  const reads: LoadReads = new Map()
-  const root = await findWorkspaceRoot(process.cwd(), reads)
-  const workspace = await loadWorkspace(root, reads)
-  // As a run discovers them: a project a plugin's `discover` stage adds
-  // was left out of the lock, and every `--frozen` run then refused it
-  // with "run vx lock", which changed nothing (X-143).
-  // Sorted by name, as core's discovery is, for stable lockfile diffs.
-  const all = (await discoverCliProjects(workspace)).sort((a, b) =>
-    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
-  )
-  const metas = all.filter((m): m is ConfiguredMeta => m.configPath !== null)
-  // A project with no vx.config has nothing to freeze: its tasks (a plugin's,
-  // or none) load live under --frozen too, so both verbs say how many the
-  // count above leaves out — `locked 0 project configs` on a turbo() repo
-  // read like an audit of something (2026-09-16).
-  const bare = all.length - metas.length
-  if (parsed.check) return await checkLock(root, metas, bare, parsed.format === 'json')
-  return await writeLock(root, metas, bare)
-}
-
-/** Evaluate one config in the current env, returning its lock entry. */
-async function evaluateEntry(root: string, meta: ConfiguredMeta): Promise<LockfileEntry> {
-  const bytes = await Bun.file(meta.configPath).bytes()
-  // `fresh: true` — the lock freezes this environment's evaluation, never
-  // a stored one, whatever options a later edit passes beside it.
-  const config = await loadProjectConfig(meta.configPath, { fresh: true })
-  return {
-    configPath: relPosix(root, meta.configPath),
-    configHash: xxh3hex(bytes),
-    // Stored through `writeLockfile`'s JSON.stringify, which drops a field
-    // left `undefined` — the form `--check` compares a fresh evaluation in.
-    config,
-  }
-}
-
-function bareNote(bare: number): string {
-  return bare === 0
-    ? ''
-    : ` (${bare} project${bare === 1 ? ' has' : 's have'} no vx.config; their tasks are never frozen)`
-}
-
-async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
-  const entries = await Promise.all(metas.map((m) => evaluateEntry(root, m)))
-  // Sorted by name above — stable lockfile diffs. Defined,
-  // not assigned: a project named `__proto__` set the map's prototype (D-152).
-  const projects: Record<string, LockfileEntry> = Object.fromEntries(
-    metas.map((m, i) => [m.name, entries[i]!]),
+  const root = await findWorkspaceRoot(process.cwd())
+  if (parsed.check) return await checkLock(root, parsed.format === 'json')
+  return await lockWorkspace(root)
+}
+
+/**
+ * Projects with tasks and no vx.config: a plugin's tasks, which load live
+ * in every run, so both verbs name them — `locked 0 project configs`
+ * on a turbo() repo read like an audit of something (2026-09-16). One with
+ * no task is left out: solidjs/solid's solid-ssr, which has no script Turbo
+ * runs, read as a project whose tasks come live from the plugin `project` stage.
+ */
+function bareProjects(all: readonly ProjectMeta[], tasked: ReadonlySet<string>): string[] {
+  return all.filter((m) => m.configPath === null && tasked.has(m.name)).map((m) => m.name)
+}
+
+/**
+ * `vx lock`: find and evaluate every config, check the graph rules over
+ * every task, and write the lock: the only writer of it.
+ */
+export async function lockWorkspace(
+  root: string,
+  warn: (message: string) => void = warnToStderr,
+): Promise<number> {
+  const check = await audit(root, warn)
+  if (check.broken !== null) {
+    process.stderr.write(`vx lock: ${LOCKFILE_NAME} not written: ${framed(check.broken)}\n`)
+    return 1
+  }
+  return await writeLock(root, check)
+}
+
+/**
+ * The lock as `vx lock` would write it, and the graph rules (`run.rules`)
+ * checked over every project and task the workspace declares: a run trusts
+ * the lock and does not check them (owner, 2026-10-13). Every config is
+ * found (`findProjectConfigs`) and evaluated once; the projects, names and
+ * graph are the ones a run builds from that lock, the `discover` and
+ * `graph` stages included.
+ */
+async function audit(root: string, warn: (message: string) => void): Promise<GraphCheck> {
+  const tasked = new Set<string>()
+  const resolved = new Map<string, ProjectConfig>()
+  const out: GraphCheck = {
+    broken: null,
+    fresh: { version: LOCKFILE_VERSION, projects: {} },
+    all: [],
+    tasked,
+    resolved,
+    reviewFiles: true,
+  }
+  try {
+    const { workspaceConfig, plugins, cacheDir } = await loadCliWorkspace(root)
+    out.reviewFiles = resolveSetting('lock.reviewFiles', workspaceConfig).value !== false
+    const found = await findProjectConfigs(root)
+    // The one load that evaluates: every reader reads the lock this writes.
+    const configs = await loadProjectConfigs(found.map((f) => f.configPath))
+    // In the lock's form: a field left `undefined` is a key the stored JSON
+    // never has. Entries, not assignment: a directory named `__proto__` is
+    // a key of its own (D-152).
+    out.fresh.projects = Object.fromEntries(
+      found.map((f, i) => [
+        lockKey(root, f.dir),
+        {
+          file: path.basename(f.configPath),
+          config: JSON.parse(JSON.stringify(configs[i])) as ProjectConfig,
+        },
+      ]),
+    )
+    // The stages edit what they are handed; the lock keeps what the configs say.
+    const view = structuredClone(out.fresh)
+    const lock = async (): Promise<Lockfile> => view
+    out.all = await discoverProjects(root, lock, plugins, cacheDir, warn)
+    const { projects } = await loadProjects({
+      workspaceRoot: root,
+      cacheDir,
+      plugins,
+      projectMetas: out.all,
+      seeds: 'all',
+      closure: false,
+      configs: lock,
+      warn,
+    })
+    for (const entry of projects.values()) resolved.set(entry.name, entry.config)
+    const names = new Set<string>()
+    for (const entry of projects.values()) {
+      const tasks = Object.entries(entry.config.tasks ?? {})
+      // Every project has a `build`; core's default one is nothing to freeze.
+      if (tasks.some(([, t]) => !isDefaultBuild(t))) tasked.add(entry.name)
+      for (const [t] of tasks) names.add(t)
+    }
+    const dependencyRules = workspaceConfig?.run?.rules?.dependencies ?? []
+    if (dependencyRules.length > 0)
+      checkDependencyRules(
+        dependencyRules,
+        [...projects.keys()],
+        new Map([...projects.values()].map((p) => [p.name, p.config.tags ?? []])),
+        buildPackageGraph(out.all, taskEdgesFrom(projects)),
+      )
+    const rules = runRules(workspaceConfig)
+    const nodes = buildTaskGraph({
+      projects,
+      packageGraph: buildPackageGraph(out.all),
+      requested: expandRequested([...names], [...projects.keys()], projects, isDefaultBuild),
+      workspaceRoot: root,
+      rules,
+    })
+    if (hasHook(plugins, 'graph'))
+      await applyGraphStage(plugins, nodes, {
+        workspaceRoot: root,
+        cacheDir,
+        projectMetas: out.all,
+        warn,
+        rules,
+      })
+  } catch (err) {
+    if (isUserError(err)) return { ...out, broken: err.message }
+    throw err
+  }
+  return out
+}
+
+interface GraphCheck {
+  /** A graph rule's refusal, or a config that does not load; null when sound. */
+  broken: string | null
+  /** The lock the configs evaluate to here. */
+  fresh: Lockfile
+  /** Every project, as a run discovers them from `fresh`. */
+  all: ProjectMeta[]
+  /** The projects that have a task. */
+  tasked: Set<string>
+  /** Each project's config as a run resolves it, plugins applied. */
+  resolved: Map<string, ProjectConfig>
+  /** `lock.reviewFiles`. */
+  reviewFiles: boolean
+}
+
+function configured(all: readonly ProjectMeta[]): ConfiguredMeta[] {
+  return all.filter((m): m is ConfiguredMeta => m.configPath !== null)
+}
+
+/**
+ * `vx init`'s last step: the lock, as `vx lock` writes it. A refusal (a
+ * graph rule, a config that does not load) is printed and leaves the
+ * written configs in place.
+ */
+export async function lockAfterMigration(root: string): Promise<number> {
+  try {
+    return await lockWorkspace(root)
+  } catch (err) {
+    if (!isUserError(err)) throw err
+    process.stderr.write(`vx lock: ${LOCKFILE_NAME} not written: ${framed(err.message)}\n`)
+    return 1
+  }
+}
+
+/** A config refusal as a run used to print it: path:line:col and the source line. */
+function framed(message: string): string {
+  return configErrorFrame(message, process.cwd()) ?? message
+}
+
+/** Names shown per note: a turbo() repo can have hundreds of bare projects. */
+const BARE_SHOWN = 5
+
+function bareNames(bare: readonly string[]): string {
+  const more = bare.length - BARE_SHOWN
+  return more > 0 ? `${bare.slice(0, BARE_SHOWN).join(', ')} and ${more} more` : bare.join(', ')
+}
+
+function bareNote(bare: readonly string[]): string {
+  return bare.length === 0 ? '' : ` (no vx.config, so not locked: ${bareNames(bare)})`
+}
+
+/** The name `vx lock` writes each project's review copy under. */
+const REVIEW_FILE = 'vx.lock.json'
+
+interface Review {
+  name: string
+  file: string
+  config: ProjectConfig
+  text: string
+}
+
+/** Each configured project's review copy: its resolved config, pretty. */
+function sameJson(text: string, config: ProjectConfig): boolean {
+  try {
+    return Bun.deepEquals(JSON.parse(text), JSON.parse(JSON.stringify(config)), true)
+  } catch {
+    return false
+  }
+}
+
+function reviewsOf(metas: ConfiguredMeta[], resolved: Map<string, ProjectConfig>): Review[] {
+  return metas.flatMap((m) => {
+    const config = resolved.get(m.name)
+    if (config === undefined) return []
+    return [
+      {
+        name: m.name,
+        file: path.join(path.dirname(m.configPath), REVIEW_FILE),
+        config,
+        text: `${JSON.stringify(config, null, 2)}\n`,
+      },
+    ]
+  })
+}
+
+/** Writes `text` to `file` unless it exists: one a user edited stays theirs. */
+async function writeIfMissing(file: string, text: string): Promise<void> {
+  try {
+    const fh = await open(file, 'wx')
+    await fh.writeFile(text)
+    await fh.close()
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+  }
+}
+
+async function writeLock(root: string, check: GraphCheck): Promise<number> {
+  const metas = configured(check.all)
+  const bare = bareProjects(check.all, check.tasked)
+  // By project name, as the refusal names them.
+  const projects: Record<string, ProjectConfig> = Object.fromEntries(
+    metas.map((m) => [m.name, check.fresh.projects[lockKey(root, m.dir)]!.config]),
   )
+  const reviews = check.reviewFiles ? reviewsOf(metas, check.resolved) : []
+  // The review copies are committed too; a plugin's `project` stage can add
+  // a value the bare config lacks. A place both hold is named once.
   const leaks = secretsIn(projects)
+  const named = new Set(leaks.map((l) => l.at))
+  for (const l of secretsIn(Object.fromEntries(reviews.map((r) => [r.name, r.config]))))
+    if (!named.has(l.at)) leaks.push(l)
   if (leaks.length > 0) {
     process.stderr.write(
       `vx lock: ${LOCKFILE_NAME} is committed, and these configs evaluated to a secret value:\n` +
@@ -114,8 +317,11 @@ async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): P
     )
     return 1
   }
-  const lock: Lockfile = { version: LOCKFILE_VERSION, projects }
-  await writeLockfile(root, lock)
+  await writeLockfile(root, check.fresh)
+  await Promise.all([
+    ...reviews.map((r) => Bun.write(r.file, r.text)),
+    writeIfMissing(path.join(root, '.vx', '.gitattributes'), DOT_VX_GITATTRIBUTES),
+  ])
   const n = metas.length
   process.stdout.write(
     `vx lock: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
@@ -128,12 +334,12 @@ async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): P
  * environment, by the rule output masking uses (a secret-named variable,
  * or one a task lists in `exec.env.secret`). The lock is committed, so
  * such a value would be published, and masking it would freeze a `***`
- * that `--frozen` runs (L-42).
+ * that every run runs (L-42).
  */
-function secretsIn(projects: Record<string, LockfileEntry>): Array<{ at: string; name: string }> {
+function secretsIn(projects: Record<string, ProjectConfig>): Array<{ at: string; name: string }> {
   const named = new Set<string>()
-  for (const entry of Object.values(projects)) {
-    for (const task of Object.values(entry.config.tasks ?? {}))
+  for (const config of Object.values(projects)) {
+    for (const task of Object.values(config.tasks ?? {}))
       for (const n of task?.exec?.env?.secret ?? []) named.add(n)
   }
   const secrets: [value: string, name: string][] = []
@@ -153,30 +359,27 @@ function secretsIn(projects: Record<string, LockfileEntry>): Array<{ at: string;
       for (const [k, x] of Object.entries(v)) walk(project, at === '' ? k : `${at}.${k}`, x)
     }
   }
-  for (const [project, entry] of Object.entries(projects)) walk(project, '', entry.config)
+  for (const [project, config] of Object.entries(projects)) walk(project, '', config)
   return found
 }
 
 /**
- * Audit the lock. Two layers, strictly stronger than what runs do:
- *   1. The same hash check runs perform (file bytes vs lock hash).
- *   2. A full re-evaluation of every config in the CURRENT environment,
- *      deep-compared against the lock's stored resolved object. This
- *      catches eval-time env-var drift that file hashes cannot see —
- *      file bytes unchanged, resolved value changed.
+ * Audit the lock: find and re-evaluate every config in the CURRENT
+ * environment and deep-compare it with the locked object. That sees an
+ * edit to the config, to a file it imports, and to the environment it
+ * reads alike, and a config added or removed since.
  */
-async function checkLock(
-  root: string,
-  metas: ConfiguredMeta[],
-  bare: number,
-  json: boolean,
-): Promise<number> {
+async function checkLock(root: string, json: boolean): Promise<number> {
+  const check = await audit(root, warnToStderr)
+  const { broken } = check
+  const metas = configured(check.all)
+  const bare = bareProjects(check.all, check.tasked)
   const answer = (problems: string[]): number => {
     if (json) {
       const out = {
         upToDate: problems.length === 0,
         audited: metas.length,
-        notAudited: bare,
+        notAudited: bare.length,
         problems,
       }
       process.stdout.write(`${JSON.stringify(out)}\n`)
@@ -189,42 +392,61 @@ async function checkLock(
     if (!json) process.stderr.write(`vx lock --check: ${problem}\n`)
     return answer([problem])
   }
-  const results = await Promise.all(
-    metas.map(async (m): Promise<string | null> => {
-      const rel = relPosix(root, m.configPath)
-      const entry = lock.projects[m.name]
-      if (!entry || entry.configPath !== rel) {
-        return `"${m.name}" (${rel}) is not in the lock — run 'vx lock'`
-      }
-      const hash = xxh3hex(await Bun.file(m.configPath).bytes())
-      if (hash !== entry.configHash) {
-        return `config file changed since lock (${m.name}: ${rel}) — run 'vx lock'`
-      }
-      // The lock's form: a first load is the module's live export, where a
-      // field left `undefined` is a key the stored JSON never has.
-      const fresh = JSON.parse(
-        JSON.stringify(await loadProjectConfig(m.configPath, { fresh: true })),
-      ) as ProjectConfig
-      if (!Bun.deepEquals(fresh, entry.config, true)) {
-        // Bytes unchanged, so the drift is in what the evaluation read: a
-        // file the config imports, or the environment. Blaming only the
-        // environment sent an edited preset's author looking for env reads
-        // the config does not have (item 1044).
-        return (
-          `lock differs from fresh evaluation in this environment (${m.name}) — ` +
-          `a file the config imports changed, or the config reads the environment; run 'vx lock' here`
-        )
-      }
-      return null
-    }),
-  )
-  const failures = results.filter((r): r is string => r !== null)
-  const inWorkspace = new Set(metas.map((m) => m.name))
-  for (const name of Object.keys(lock.projects)) {
-    if (!inWorkspace.has(name)) {
-      failures.push(
-        `locked project "${name}" no longer has a config in the workspace — run 'vx lock'`,
-      )
+  const failures: string[] = []
+  const drifted = new Set<string>()
+  for (const [dir, fresh] of Object.entries(check.fresh.projects)) {
+    const rel = dir === '.' ? fresh.file : `${dir}/${fresh.file}`
+    const locked = Object.hasOwn(lock.projects, dir) ? lock.projects[dir] : undefined
+    const problem =
+      locked === undefined
+        ? `${rel} is not in the lock — run 'vx lock'`
+        : locked.file !== fresh.file
+          ? `${rel} is not the ${locked.file} the lock holds for ${dir} — run 'vx lock'`
+          : !Bun.deepEquals(fresh.config, locked.config, true)
+            ? `${rel} evaluates differently from the lock here — its config, a file ` +
+              `it imports, or the environment it reads changed; run 'vx lock'`
+            : null
+    if (problem === null) continue
+    failures.push(problem)
+    drifted.add(dir)
+  }
+  if (broken !== null) failures.push(broken)
+  if (check.reviewFiles && broken === null) {
+    // A project the lock already fails is named once.
+    const stale = await Promise.all(
+      reviewsOf(
+        metas.filter((m) => !drifted.has(lockKey(root, m.dir))),
+        check.resolved,
+      ).map(async (r) => {
+        const text = await Bun.file(r.file)
+          .text()
+          .catch(() => null)
+        // Compared as JSON: a formatter may lay the copy out its own way.
+        if (text !== null && sameJson(text, r.config)) return null
+        const rel = relPosix(root, r.file)
+        return text === null
+          ? `"${r.name}" has no ${rel} — run 'vx lock'`
+          : `"${r.name}" (${rel}) is not what its config resolves to here — run 'vx lock'`
+      }),
+    )
+    for (const f of stale) if (f !== null) failures.push(f)
+    // A copy left beside a config since deleted shows reviewers tasks
+    // nothing runs. vx never deletes a committed file; it names it.
+    const orphans = await Promise.all(
+      check.all
+        .filter((m) => m.configPath === null)
+        .map(async (m) => {
+          const file = path.join(m.dir, REVIEW_FILE)
+          return (await Bun.file(file).exists())
+            ? `${relPosix(root, file)} has no vx.config beside it — delete it`
+            : null
+        }),
+    )
+    for (const f of orphans) if (f !== null) failures.push(f)
+  }
+  for (const dir of Object.keys(lock.projects)) {
+    if (!Object.hasOwn(check.fresh.projects, dir)) {
+      failures.push(`the lock holds ${dir}, which has no vx.config now — run 'vx lock'`)
     }
   }
   if (json) return answer(failures)
@@ -234,7 +456,7 @@ async function checkLock(
   }
   const n = metas.length
   const audited = `${n} project${n === 1 ? '' : 's'}`
-  const skipped = bare === 0 ? '' : `; ${bare} without a vx.config not audited`
+  const skipped = bare.length === 0 ? '' : `; not audited, no vx.config: ${bareNames(bare)}`
   process.stdout.write(`vx lock --check: up to date (${audited}${skipped})\n`)
   return 0
 }

package/src/cli/plan-format.ts

@@ -76,7 +76,7 @@ export function formatPlanText(plan: RunPlan): string {
   lines.push('')
   lines.push(summary.join(', ') + '.')
 
-  // `--download` is invisible without this: the eligibility gate silently
+  // `--cache-download` is invisible without this: the eligibility gate silently
   // keeps producers eager, so a user who asked for `none` and got no
   // deferral has nothing to read. Say what WOULD stay remote, and name the
   // refusals when nothing would.
@@ -169,7 +169,7 @@ export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
         }),
         ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
         // The gate's refusals belong on the SCRIPTING surface too: a CI job
-        // asking "did --download=none actually defer anything, and if not
+        // asking "did --cache-download=none actually defer anything, and if not
         // why" reads this, not the human table. (This object enumerates its
         // fields deliberately — the plan's internal shape is not the wire —
         // which is exactly why a new PlannedTask field does not appear here

package/src/cli/plugin-commands.ts

@@ -8,10 +8,9 @@
 // before this is asked, so a plugin cannot shadow `run`.
 
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
-import { existsSync } from 'node:fs'
-import path from 'node:path'
-import { findWorkspaceRoot, WORKSPACE_CONFIG_FILENAMES } from '../workspace/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
 import { machineParallelism, maskedLine } from '../util/index.js'
+import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
   plugin: VxPlugin
@@ -53,11 +52,6 @@ async function workspacePlugins(
   } catch {
     return null
   }
-  // Plugins are declared only in a workspace file. Without one, the load
-  // below is the orchestrator's import graph (~50 ms) for an empty list,
-  // paid by `vx help` and by the `vx completions` a shell sources at start.
-  if (!WORKSPACE_CONFIG_FILENAMES.some((f) => existsSync(path.join(workspaceRoot, f))))
-    return { workspaceRoot, cacheDir: '', concurrency: 0, plugins: [] }
   let ws
   try {
     const { loadCliWorkspace } = await import('./workspace-config.js')
@@ -69,7 +63,9 @@ async function workspacePlugins(
     workspaceRoot,
     cacheDir: ws.cacheDir,
     // What run.ts takes when no --concurrency is given.
-    concurrency: ws.workspaceConfig?.concurrency ?? machineParallelism(),
+    concurrency:
+      (resolveSetting('run.concurrency', ws.workspaceConfig).value as number | undefined) ??
+      machineParallelism(),
     plugins: ws.plugins,
   }
 }