@vzn/vx 0.0.18 → 0.0.21

package/src/{cli/migrate.ts → workspace/migration.ts}

@@ -1,42 +1,47 @@
-// `vx migrate [--dry] [--force]` — generate per-package vx.config.ts
-// from an existing Turbo or Nx setup. Source auto-detect: turbo.json →
-// Turbo; .nx/workspace-data/project-graph.json → Nx (the resolved
-// snapshot). Mappers live in migrate-turbo.ts / migrate-nx.ts and
-// return an IR; this file owns detection, TS emission, the overwrite
-// guard, and the final report.
+// The migration seam: what any adoption tool needs once it has a plan —
+// the plan's shape, TS emission, the overwrite guard, the writes and the
+// report. `vx init` (package.json scripts, in core) and `@vzn/vx-migrate`
+// (Turbo, Nx) share it, so a generated config reads the same whichever
+// tool wrote it. Core knows no source format here: a mapper returns a
+// `MigrationPlan` and this file does the rest.
 
 import path from 'node:path'
 import { relPosix, UserError } from '../util/index.js'
-import { findWorkspaceRoot, listProjects, loadWorkspace } from '../workspace/index.js'
-import { quote } from './migrate-emit.js'
-import { migrateNx } from './migrate-nx.js'
-import { migrateScripts } from './migrate-scripts.js'
-import { migrateTurbo } from './migrate-turbo.js'
+import type { ProjectMeta } from './workspace.js'
 
-export interface MigrateArgs {
-  dry: boolean
-  force: boolean
-  from?: 'turbo' | 'nx' | 'scripts'
-  error?: string
+/**
+ * Escape an arbitrary string into a single-quoted TS literal. Escapes
+ * backslash + quote AND raw newlines/CR — a value with an embedded newline
+ * (legal JSON, e.g. a script `"echo a\necho b"`, or a glob with a `'`) would
+ * otherwise splice into a single-quoted literal as an unterminated / malformed
+ * string that fails to load (generated files must round-trip through the
+ * loader).
+ */
+export function quoteTsLiteral(s: string): string {
+  return `'${s
+    .replaceAll('\\', '\\\\')
+    .replaceAll("'", "\\'")
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')}'`
 }
 
-export function parseMigrateArgs(args: readonly string[]): MigrateArgs {
-  const out: MigrateArgs = { dry: false, force: false }
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i]
-    if (a === '--dry') out.dry = true
-    else if (a === '--force') out.force = true
-    else if (a === '--from' || a?.startsWith('--from=')) {
-      const v = a === '--from' ? args[++i] : a.slice('--from='.length)
-      if (v !== 'turbo' && v !== 'nx' && v !== 'scripts') {
-        return { ...out, error: `--from must be turbo, nx or scripts` }
-      }
-      out.from = v
-    } else if (a?.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
-    else return { ...out, error: `unexpected argument: ${a}` }
-  }
-  return out
-}
+/**
+ * Task names that conventionally never exit. Every mapper guesses the same
+ * way from a name — a source that SAYS a task is long-running (turbo's
+ * `persistent: true`, an Nx dev-server executor) is believed instead.
+ */
+export const PERSISTENT_TASK_NAMES: ReadonlySet<string> = new Set([
+  'dev',
+  'start',
+  'serve',
+  'watch',
+  'preview',
+])
+
+/** The one wording every mapper emits for a task it made persistent. */
+export const PERSISTENT_TODO =
+  'persistent task — set persistent.readyWhen (regex matched against output) so ' +
+  'dependents unblock on readiness, and consider exec.timeout to bound the wait'
 
 /** Verbatim TS expression spliced into a generated array (preset spreads). */
 export interface RawExpr {
@@ -71,65 +76,47 @@ export interface MigrationPlan {
   notes: string[]
 }
 
-export async function migrateCmd(
-  args: readonly string[],
-  opts: { init?: boolean } = {},
-): Promise<number> {
-  const parsed = parseMigrateArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx migrate: ${parsed.error}\n`)
-    return 1
-  }
-  const root = await findWorkspaceRoot(process.cwd())
-  const metas = await listProjects(await loadWorkspace(root))
+export interface ApplyMigrationArgs {
+  root: string
+  metas: readonly ProjectMeta[]
+  plan: MigrationPlan
+  /** Named in the report and the generated header, e.g. `turbo.json`. */
+  source: string
+  /** The command the user typed, e.g. `vx init` — named in the report. */
+  verb: string
+  dry: boolean
+  force: boolean
+  /**
+   * `vx init` on a workspace with no scripts still has a job (the workspace
+   * file, and a worked example); a migration with nothing to convert is an
+   * error. Default false.
+   */
+  init?: boolean
+  /** Report lines printed under the source line (e.g. "turbo.json found and not read"). */
+  notes?: readonly string[]
+  /**
+   * `ts` (default) writes `vx.config.ts` with the type-only import and
+   * `satisfies`; `mjs` writes `vx.config.mjs` — the same object, untyped —
+   * for a package whose own `tsc --build` includes every `.ts` under it
+   * and compiled the config into its dist (TanStack/query, 2026-09-11).
+   */
+  format?: MigrationFormat
+}
 
-  const hasTurbo = await Bun.file(path.join(root, 'turbo.json')).exists()
-  const graphRel = path.join('.nx', 'workspace-data', 'project-graph.json')
-  const hasGraph = await Bun.file(path.join(root, graphRel)).exists()
-  const hasNxJson = await Bun.file(path.join(root, 'nx.json')).exists()
+export type MigrationFormat = 'ts' | 'mjs'
 
-  // Evaluating teams routinely have both runners checked in — never
-  // ask anyone to delete anything; --from disambiguates.
-  if (parsed.from === undefined && hasTurbo && (hasGraph || hasNxJson)) {
-    throw new UserError(
-      'both turbo.json and an nx workspace are present — pass --from turbo or --from nx',
-    )
-  }
-  if (parsed.from === 'turbo' && !hasTurbo) {
-    throw new UserError('--from turbo, but no turbo.json at the workspace root')
-  }
-
-  let source: string
-  let plan: MigrationPlan
-  if (parsed.from === 'scripts') {
-    source = 'package.json scripts'
-    plan = migrateScripts(metas)
-  } else if (parsed.from === 'nx' || (parsed.from === undefined && !hasTurbo)) {
-    if (hasGraph) {
-      source = '.nx/workspace-data/project-graph.json'
-      plan = await migrateNx(root, metas)
-    } else if (hasNxJson || parsed.from === 'nx') {
-      // Modern Nx stores the graph in SQLite — the JSON snapshot only
-      // exists when exported explicitly.
-      throw new UserError(
-        'no resolved Nx graph found — export one with ' +
-          '`nx graph --file=.nx/workspace-data/project-graph.json`, then re-run vx migrate',
-      )
-    } else {
-      // A workspace from nowhere: the scripts are the source (`vx init`).
-      source = 'package.json scripts'
-      plan = migrateScripts(metas)
-    }
-  } else {
-    source = 'turbo.json'
-    plan = await migrateTurbo(root, metas)
-  }
-  // `vx init` on a workspace with no scripts still has a job: the
-  // workspace file, which every run needs, and a worked example of the
-  // config the user writes next. `vx migrate` with nothing to convert is
-  // an error: the user asked for a conversion that has no input.
+/**
+ * Render a plan to files, refuse to overwrite without `force`, write (or
+ * print, under `dry`), and report. Returns the process exit code.
+ */
+export async function applyMigration(args: ApplyMigrationArgs): Promise<number> {
+  const { root, metas, plan, source, verb, dry, force } = args
+  const init = args.init === true
+  const format: MigrationFormat = args.format ?? 'ts'
+  const configName = `vx.config.${format}`
+  const workspaceName = `vx.workspace.${format}`
   const empty = plan.projects.length === 0
-  if (empty && opts.init !== true) {
+  if (empty && !init) {
     throw new UserError(
       `nothing to migrate: no ${source === 'package.json scripts' ? 'package.json scripts in any workspace member' : 'tasks in ' + source}`,
     )
@@ -138,8 +125,12 @@ export async function migrateCmd(
   const files: { relPath: string; abs: string; contents: string }[] = []
   for (const p of plan.projects) {
     if (p.tasks.length === 0) continue
-    const abs = path.join(p.dir, 'vx.config.ts')
-    files.push({ relPath: relPosix(root, abs), abs, contents: renderConfigFile(source, p) })
+    const abs = path.join(p.dir, configName)
+    files.push({
+      relPath: relPosix(root, abs),
+      abs,
+      contents: renderConfigFile(source, p, verb, format),
+    })
   }
   for (const f of plan.extraFiles) {
     files.push({ relPath: f.relPath, abs: path.join(root, f.relPath), contents: f.contents })
@@ -155,11 +146,11 @@ export async function migrateCmd(
     )
   ).some(Boolean)
   if (!hasWorkspaceFile) {
-    const abs = path.join(root, 'vx.workspace.ts')
-    files.push({ relPath: relPosix(root, abs), abs, contents: WORKSPACE_FILE })
+    const abs = path.join(root, workspaceName)
+    files.push({ relPath: relPosix(root, abs), abs, contents: workspaceFile(format) })
   }
 
-  if (!parsed.dry && !parsed.force) {
+  if (!dry && !force) {
     const conflicts = new Set<string>()
     // A discovered project with ANY existing vx config (.ts/.mjs/.js) — refuse
     // so we never shadow a hand-written config with a fresh .ts.
@@ -183,7 +174,7 @@ export async function migrateCmd(
     }
   }
 
-  if (parsed.dry) {
+  if (dry) {
     for (const f of files) {
       process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
     }
@@ -202,20 +193,22 @@ export async function migrateCmd(
   const report: string[] = []
   if (empty) {
     report.push(
-      'vx init: no package.json scripts to turn into tasks.',
+      `${verb}: no package.json scripts to turn into tasks.`,
       hasWorkspaceFile
-        ? 'vx.workspace.ts already exists.'
-        : parsed.dry
-          ? 'would write vx.workspace.ts (dry run, nothing written).'
-          : 'wrote vx.workspace.ts.',
-      'Declare tasks in a vx.config.ts beside a package.json — your own command, for example:',
+        ? `${workspaceName} already exists.`
+        : dry
+          ? `would write ${workspaceName} (dry run, nothing written).`
+          : `wrote ${workspaceName}.`,
+      `Declare tasks in a ${configName} beside a package.json — your own command, for example:`,
       '',
-      ...EXAMPLE_CONFIG.trimEnd()
+      ...exampleConfig(format)
+        .trimEnd()
         .split('\n')
         .map((l) => `  ${l}`),
     )
   } else {
-    report.push(`vx migrate: ${source} → vx.config.ts`)
+    report.push(`${verb}: ${source} → ${configName}`)
+    for (const n of args.notes ?? []) report.push(`note: ${n}`)
     for (const n of plan.headerNotes) report.push(`note: ${n}`)
     report.push(
       '',
@@ -224,7 +217,7 @@ export async function migrateCmd(
     )
     for (const line of todoList) report.push(`  ${line}`)
     report.push(...plan.notes)
-    report.push(parsed.dry ? 'files (dry run, nothing written):' : 'files written:')
+    report.push(dry ? 'files (dry run, nothing written):' : 'files written:')
     for (const f of files) report.push(`  ${f.relPath}`)
   }
   const firstTask =
@@ -236,9 +229,7 @@ export async function migrateCmd(
   return 0
 }
 
-const EXAMPLE_CONFIG = `import type { ProjectConfig } from '@vzn/vx'
-
-export default {
+const EXAMPLE_BODY = `export default {
   tasks: {
     build: {
       exec: { command: 'tsc -b' },
@@ -246,19 +237,31 @@ export default {
       cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
     },
   },
-} satisfies ProjectConfig
-`
+}`
+
+function exampleConfig(format: MigrationFormat): string {
+  return format === 'ts'
+    ? `import type { ProjectConfig } from '@vzn/vx'\n\n${EXAMPLE_BODY} satisfies ProjectConfig\n`
+    : `${EXAMPLE_BODY}\n`
+}
 
 // ─── TS emission ──────────────────────────────────────────────────────
 
-const WORKSPACE_FILE = `import { defineWorkspace } from '@vzn/vx'
-import { localExecutorPlugin } from '@vzn/vx/plugins/local-executor'
-import { localCachePlugin } from '@vzn/vx/plugins/local-cache'
+// Type-only import + `satisfies`, like the project configs: a runtime
+// `import { defineWorkspace } from '@vzn/vx'` loads a SECOND copy of core
+// into every run — measured 2026-09-09 at ~17 ms on a two-package
+// workspace, a fifth of the whole run — for an identity function.
+const WORKSPACE_BODY = `// Plugins are consulted in this order; running here and caching in
+// .vx/cache are the floor under all of them, so an empty list is a
+// complete workspace. Add a remote cache, a remote executor or telemetry
+// as one entry each — those imports are the runtime ones.
+export default { plugins: [] }`
 
-// Nothing runs that is not declared here. Put a remote executor or cache
-// plugin BEFORE the local one to prefer it.
-export default defineWorkspace({ plugins: [localExecutorPlugin(), localCachePlugin()] })
-`
+function workspaceFile(format: MigrationFormat): string {
+  return format === 'ts'
+    ? `import type { WorkspaceConfig } from '@vzn/vx'\n\n${WORKSPACE_BODY} satisfies WorkspaceConfig\n`
+    : `${WORKSPACE_BODY}\n`
+}
 
 const IDENT = /^[A-Za-z_$][\w$]*$/
 
@@ -272,34 +275,40 @@ function renderValue(v: unknown, indent: string): string {
   // with a raw stack mid-write. Mappers no longer produce a null, but a
   // literal is a readable thing to leave behind if one ever does.
   if (v === null) return 'null'
-  if (typeof v === 'string') return quote(v)
+  if (typeof v === 'string') return quoteTsLiteral(v)
   if (typeof v === 'number' || typeof v === 'boolean') return String(v)
   if (Array.isArray(v)) return `[${v.map((x) => renderValue(x, indent)).join(', ')}]`
   const entries = Object.entries(v as Record<string, unknown>).filter(([, x]) => x !== undefined)
   if (entries.length === 0) return '{}'
   const inner = `${indent}  `
   const body = entries.map(
-    ([k, x]) => `${inner}${IDENT.test(k) ? k : quote(k)}: ${renderValue(x, inner)},`,
+    ([k, x]) => `${inner}${IDENT.test(k) ? k : quoteTsLiteral(k)}: ${renderValue(x, inner)},`,
   )
   return `{\n${body.join('\n')}\n${indent}}`
 }
 
-function renderConfigFile(source: string, p: GeneratedProject): string {
+function renderConfigFile(
+  source: string,
+  p: GeneratedProject,
+  verb: string,
+  format: MigrationFormat,
+): string {
   // A type-only import: the editor type-checks against the installed
   // package, and Bun erases it, so the config loads in a workspace that
-  // runs the vx binary without the package installed.
+  // runs the vx binary without the package installed. `mjs` is the same
+  // object with nothing to erase.
   const lines: string[] = [
-    `// Generated by \`vx migrate\` from ${source}. Review the TODO(vx-migrate) comments.`,
-    "import type { ProjectConfig } from '@vzn/vx'",
+    `// Generated by \`${verb}\` from ${source}. Review the TODO(vx-migrate) comments.`,
   ]
+  if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx'")
   if (p.importLines.length > 0) lines.push(...p.importLines)
   lines.push('', 'export default {', '  tasks: {')
   for (const t of p.tasks) {
     for (const todo of t.todos) lines.push(`    // TODO(vx-migrate): ${todo}`)
     if (t.task === null) continue // skipped target — the TODO above explains
-    const key = IDENT.test(t.name) ? t.name : quote(t.name)
+    const key = IDENT.test(t.name) ? t.name : quoteTsLiteral(t.name)
     lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
   }
-  lines.push('  },', '} satisfies ProjectConfig', '')
+  lines.push('  },', format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
   return lines.join('\n')
 }

package/src/workspace/package-graph.ts

@@ -1,40 +1,108 @@
 import type { ProjectMeta } from './workspace.js'
 
 export interface PackageGraph {
-  /** Immediate workspace deps (sorted). */
+  /** Immediate workspace deps the package builds AFTER (sorted): every bucket but peers. */
   directDeps: (name: string) => string[]
-  /** All transitive workspace deps for each project. */
+  /** All transitive workspace deps a change can reach the package through — peers included. */
   transitiveDeps: (name: string) => string[]
-  /** All transitive workspace dependents (packages that depend on the named one). */
+  /** All transitive workspace dependents (packages a change here can reach) — peers included. */
   transitiveDependents: (name: string) => string[]
 }
 
-export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
+/**
+ * `taskEdges`: project → the projects its tasks name in a cross-project
+ * `dependsOn` (`e2e` → `app` from `dependsOn: ['app#build']`). A dependent
+ * the manifest does not know but the task graph does; without it
+ * `--filter '...app'` never selected `e2e`, and a CI that runs "what
+ * changed and everything depending on it" silently left it out
+ * (2026-09-10). The `^task` walk still reads `directDeps`, which carries
+ * both — a task edge IS a dependency.
+ */
+export function buildPackageGraph(
+  projects: ProjectMeta[],
+  taskEdges?: ReadonlyMap<string, readonly string[]>,
+): PackageGraph {
   const byName = new Map<string, ProjectMeta>()
   for (const p of projects) byName.set(p.name, p)
 
+  // Two adjacencies. ORDER (`directDeps`, the `^task` walk) is what the
+  // package imports at build time: dependencies, devDependencies,
+  // optionalDependencies, the task edges, and a workspace peer that does
+  // not close a cycle. REACH (the transitive closures `--filter pkg...`
+  // and `--affected` read) is ORDER plus every workspace peer.
+  //
+  // A peer on a workspace sibling is an import that resolves to that
+  // sibling's build: every package manager links or hoists it (pnpm's
+  // `linkWorkspacePackages`, the hoisted root of bun/npm/yarn), and
+  // TanStack/router's `router-devtools-core` peers on `router-core` and
+  // type-checks against its `dist` — Nx orders `^build` on the peer,
+  // vx built the devtools first and failed (2026-09-11). But peers are
+  // the one bucket that routinely cycles (medusa's test-utils peers on
+  // medusa, which dev-depends on it through analytics; Turbo, which
+  // reads no peers, runs it; an unconditional order edge made `^build`
+  // a task cycle, 2026-09-11), so a peer edge that would close a cycle
+  // through the order graph is reach only: the consumer above provides
+  // that peer. Peers are tried in (package, peer) name order, so which
+  // edge of a two-peer cycle stays is stable across runs.
   const directDeps = new Map<string, string[]>()
-  for (const p of projects) {
-    const seen = new Set<string>()
-    for (const field of [
-      'dependencies',
-      'devDependencies',
-      'peerDependencies',
-      'optionalDependencies',
-    ] as const) {
+  const reachDeps = new Map<string, string[]>()
+  const order = new Map<string, Set<string>>()
+  const peers = new Map<string, Set<string>>()
+  const sorted = [...projects].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  for (const p of sorted) {
+    const own = new Set<string>()
+    for (const name of taskEdges?.get(p.name) ?? []) {
+      if (name !== p.name && byName.has(name)) own.add(name)
+    }
+    const add = (
+      field: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies',
+      into: Set<string>,
+    ) => {
       const obj = p.packageJson[field]
-      if (!obj) continue
+      if (!obj) return
       for (const name of Object.keys(obj)) {
-        if (name === p.name) continue
-        if (byName.has(name)) seen.add(name)
+        if (name !== p.name && byName.has(name)) into.add(name)
+      }
+    }
+    add('dependencies', own)
+    add('devDependencies', own)
+    add('optionalDependencies', own)
+    order.set(p.name, own)
+    const peer = new Set<string>()
+    add('peerDependencies', peer)
+    peers.set(p.name, peer)
+  }
+  // `to` reaches `from` through the order edges so far ⇒ from → to
+  // would close a cycle.
+  const reaches = (start: string, goal: string): boolean => {
+    const seen = new Set<string>([start])
+    const stack = [start]
+    while (stack.length > 0) {
+      for (const next of order.get(stack.pop()!) ?? []) {
+        if (next === goal) return true
+        if (!seen.has(next)) {
+          seen.add(next)
+          stack.push(next)
+        }
       }
     }
-    directDeps.set(p.name, [...seen].sort())
+    return false
+  }
+  for (const p of sorted) {
+    const own = order.get(p.name)!
+    for (const peer of [...peers.get(p.name)!].sort()) {
+      if (!own.has(peer) && !reaches(peer, p.name)) own.add(peer)
+    }
+  }
+  for (const p of sorted) {
+    const own = order.get(p.name)!
+    directDeps.set(p.name, [...own].sort())
+    reachDeps.set(p.name, [...new Set([...own, ...peers.get(p.name)!])].sort())
   }
 
   // Reverse adjacency: who declares X as a workspace dep.
   const directDependents = new Map<string, string[]>()
-  for (const [name, deps] of directDeps) {
+  for (const [name, deps] of reachDeps) {
     for (const d of deps) {
       const arr = directDependents.get(d)
       if (arr) arr.push(name)
@@ -110,22 +178,24 @@ export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
     return [...seen].sort()
   }
 
+  // The closures are built on the FIRST query, not here: an unscoped run
+  // seeds every project and never asks for a transitive set, and neither
+  // does a `^task` walk (it reads `directDeps`). Building both closures
+  // eagerly was 12 ms of a 240 ms warm run at 1000 projects × 30 deps
+  // (profiled 2026-09-09) for answers nobody read.
   function makeAccessor(edges: Map<string, string[]>): (name: string) => string[] {
-    const closures = bitsetClosures(edges)
     const memo = new Map<string, string[]>()
-    if (closures === null) {
-      return (name) => {
-        const cached = memo.get(name)
-        if (cached) return cached
-        const result = reachableFrom(name, edges)
-        memo.set(name, result)
-        return result
-      }
-    }
+    let closures: Uint32Array | null | undefined
     const words = (names.length + 31) >>> 5
     return (name) => {
       const cached = memo.get(name)
       if (cached) return cached
+      if (closures === undefined) closures = bitsetClosures(edges)
+      if (closures === null) {
+        const result = reachableFrom(name, edges)
+        memo.set(name, result)
+        return result
+      }
       const i = index.get(name)
       if (i === undefined) return []
       const base = i * words
@@ -145,7 +215,7 @@ export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
 
   return {
     directDeps: (name) => directDeps.get(name) ?? [],
-    transitiveDeps: makeAccessor(directDeps),
+    transitiveDeps: makeAccessor(reachDeps),
     transitiveDependents: makeAccessor(directDependents),
   }
 }