@vzn/vx 0.0.0 → 0.0.12

package/src/cli/migrate-turbo.ts

@@ -0,0 +1,364 @@
+// Turbo → vx mapping. Reads turbo.json (tasks in turbo 2, pipeline in
+// turbo 1), per-package turbo.json `extends` overlays, and each
+// package's scripts. A task is emitted for a package only when the
+// package declares the script (turbo semantics). Global fields become
+// a root vx-preset.ts that configs import and spread — TypeScript
+// composition replaces turbo's global config.
+
+import path from 'node:path'
+import { relPosix, UserError } from '../util/index.js'
+import type { ProjectMeta } from '../workspace/index.js'
+import type { GeneratedProject, GeneratedTask, MigrationPlan, RawExpr } from './migrate.js'
+
+interface TurboTask {
+  dependsOn?: string[]
+  inputs?: string[]
+  outputs?: string[]
+  env?: string[]
+  passThroughEnv?: string[]
+  cache?: boolean
+  persistent?: boolean
+  [key: string]: unknown
+}
+
+interface TurboJson {
+  tasks?: Record<string, TurboTask>
+  pipeline?: Record<string, TurboTask>
+  globalDependencies?: string[]
+  globalEnv?: string[]
+  globalPassThroughEnv?: string[]
+}
+
+const KNOWN_TASK_KEYS = new Set([
+  'dependsOn',
+  'inputs',
+  'outputs',
+  'env',
+  'passThroughEnv',
+  'cache',
+  'persistent',
+  'extends',
+])
+
+const PRESET_FILE = 'vx-preset.ts'
+
+interface Globals {
+  inputs: boolean
+  env: boolean
+  pass: boolean
+}
+
+async function readTurboJson(file: string, root: string): Promise<TurboJson> {
+  const text = await Bun.file(file).text()
+  try {
+    // turbo.json allows comments + trailing commas.
+    return (Bun.JSONC.parse(text) ?? {}) as TurboJson
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new UserError(`failed to parse ${relPosix(root, file)}: ${msg}`)
+  }
+}
+
+function tasksOf(cfg: TurboJson): Record<string, TurboTask> {
+  return cfg.tasks ?? cfg.pipeline ?? {}
+}
+
+function scriptsOf(meta: ProjectMeta): Record<string, string> {
+  return (meta.packageJson as unknown as { scripts?: Record<string, string> }).scripts ?? {}
+}
+
+/** Declared task names for a package: plain root keys, `pkg#name` keys
+ * for this package, and per-package turbo.json keys — in that order. */
+function taskNamesFor(
+  pkgName: string,
+  rootTasks: Record<string, TurboTask>,
+  pkgTasks: Record<string, TurboTask> | undefined,
+): string[] {
+  const names: string[] = []
+  const push = (n: string): void => {
+    if (!names.includes(n)) names.push(n)
+  }
+  for (const key of Object.keys(rootTasks)) {
+    if (!key.includes('#')) push(key)
+    else if (key.startsWith(`${pkgName}#`)) push(key.slice(pkgName.length + 1))
+  }
+  for (const key of Object.keys(pkgTasks ?? {})) {
+    if (!key.includes('#')) push(key)
+  }
+  return names
+}
+
+export async function migrateTurbo(
+  root: string,
+  metas: readonly ProjectMeta[],
+): Promise<MigrationPlan> {
+  const rootCfg = await readTurboJson(path.join(root, 'turbo.json'), root)
+  const rootTasks = tasksOf(rootCfg)
+
+  const globalInputs = rootCfg.globalDependencies ?? []
+  const globalEnv = rootCfg.globalEnv ?? []
+  const globalPass = rootCfg.globalPassThroughEnv ?? []
+  const globals: Globals = {
+    inputs: globalInputs.length > 0,
+    env: globalEnv.length > 0,
+    pass: globalPass.length > 0,
+  }
+
+  const pkgTasksByName = new Map<string, Record<string, TurboTask>>()
+  for (const meta of metas) {
+    const file = path.join(meta.dir, 'turbo.json')
+    if (await Bun.file(file).exists()) {
+      pkgTasksByName.set(meta.name, tasksOf(await readTurboJson(file, root)))
+    }
+  }
+
+  const notes: string[] = []
+  for (const key of Object.keys(rootTasks)) {
+    if (key.startsWith('//#')) {
+      notes.push(`note: root task ${key} not migrated — vx has no workspace-root tasks`)
+    }
+  }
+
+  // First pass: which tasks does each package emit? Needed so dependsOn
+  // edges can be validated/dropped against the real emitted set.
+  const emitted = new Map<string, Set<string>>()
+  for (const meta of metas) {
+    const scripts = scriptsOf(meta)
+    const set = new Set<string>()
+    for (const name of taskNamesFor(meta.name, rootTasks, pkgTasksByName.get(meta.name))) {
+      if (scripts[name] !== undefined) set.add(name)
+    }
+    emitted.set(meta.name, set)
+  }
+
+  const projects: GeneratedProject[] = []
+  for (const meta of metas) {
+    const scripts = scriptsOf(meta)
+    const pkgTasks = pkgTasksByName.get(meta.name)
+    const own = emitted.get(meta.name)!
+    const used = new Set<string>()
+    const tasks: GeneratedTask[] = []
+    for (const name of taskNamesFor(meta.name, rootTasks, pkgTasks)) {
+      if (!own.has(name)) continue
+      const def: TurboTask = {
+        ...rootTasks[name],
+        ...rootTasks[`${meta.name}#${name}`],
+        ...pkgTasks?.[name],
+      }
+      tasks.push(buildTask(name, def, scripts[name]!, own, emitted, globals, used))
+    }
+    projects.push({
+      name: meta.name,
+      dir: meta.dir,
+      importLines: presetImportLines(used, root, meta.dir),
+      tasks,
+    })
+  }
+
+  const extraFiles: MigrationPlan['extraFiles'] = []
+  if (globals.inputs || globals.env || globals.pass) {
+    extraFiles.push({
+      relPath: PRESET_FILE,
+      contents: renderPreset(globalInputs, globalEnv, globalPass),
+    })
+  }
+
+  return { headerNotes: [], projects, extraFiles, notes }
+}
+
+function buildTask(
+  name: string,
+  def: TurboTask,
+  command: string,
+  own: ReadonlySet<string>,
+  emitted: ReadonlyMap<string, ReadonlySet<string>>,
+  globals: Globals,
+  used: Set<string>,
+): GeneratedTask {
+  const todos: string[] = []
+  const persistent = def.persistent === true
+  const cacheEnabled = def.cache !== false && !persistent
+
+  for (const [key, value] of Object.entries(def)) {
+    if (KNOWN_TASK_KEYS.has(key)) continue
+    todos.push(
+      `turbo key ${JSON.stringify(key)} (${JSON.stringify(value)}) has no vx equivalent — ` +
+        'map it manually',
+    )
+  }
+
+  const deps: string[] = []
+  for (const d of def.dependsOn ?? []) {
+    if (d.includes('$TURBO_ROOT$')) {
+      todos.push(
+        `dependsOn ${JSON.stringify(d)} uses $TURBO_ROOT$ — vx has no workspace-root tasks; ` +
+          'restructure manually',
+      )
+      continue
+    }
+    if (d.startsWith('^')) {
+      deps.push(d)
+      continue
+    }
+    const hashAt = d.indexOf('#')
+    if (hashAt !== -1) {
+      const pkg = d.slice(0, hashAt)
+      const task = d.slice(hashAt + 1)
+      if (emitted.get(pkg)?.has(task)) deps.push(d)
+      else
+        todos.push(
+          `dependsOn ${JSON.stringify(d)}: ${pkg} declares no ${task} script — edge dropped`,
+        )
+      continue
+    }
+    // Same-project dep on a script this package lacks: turbo silently
+    // skips the task there, so the edge simply doesn't exist.
+    if (own.has(d)) deps.push(d)
+  }
+
+  const envNames: string[] = []
+  for (const e of def.env ?? []) {
+    if (/[*?[\]!]/.test(e)) {
+      todos.push(
+        `env ${JSON.stringify(e)}: wildcards are not supported in vx env names — ` +
+          'list explicit names in cache.inputs.env + exec.env.passThrough',
+      )
+    } else envNames.push(e)
+  }
+  const passNames: string[] = []
+  for (const e of def.passThroughEnv ?? []) {
+    if (/[*?[\]!]/.test(e)) {
+      todos.push(
+        `passThroughEnv ${JSON.stringify(e)}: wildcards are not supported — list explicit names`,
+      )
+    } else passNames.push(e)
+  }
+
+  const passThrough: (string | RawExpr)[] = []
+  if (globals.env) {
+    passThrough.push({ raw: '...globalEnvInputs' })
+    used.add('globalEnvInputs')
+  }
+  if (globals.pass) {
+    passThrough.push({ raw: '...globalPassThroughEnv' })
+    used.add('globalPassThroughEnv')
+  }
+  passThrough.push(...envNames, ...passNames)
+
+  const exec: Record<string, unknown> = { command }
+  if (passThrough.length > 0) exec.env = { passThrough }
+  if (persistent) {
+    exec.persistent = {}
+    todos.push(
+      'persistent task — set persistent.readyWhen (regex matched against output) so ' +
+        'dependents unblock on readiness, and consider exec.timeout to bound the wait',
+    )
+  }
+
+  const task: Record<string, unknown> = { exec }
+  if (deps.length > 0) task.dependsOn = deps
+
+  if (cacheEnabled) {
+    const files: (string | RawExpr)[] = []
+    const wsFiles: (string | RawExpr)[] = []
+    // globalDependencies are workspace-root-relative by definition —
+    // they map to inputs.workspaceFiles, not project-relative files.
+    if (globals.inputs) {
+      wsFiles.push({ raw: '...globalInputs' })
+      used.add('globalInputs')
+    }
+    if (def.inputs === undefined) {
+      // Turbo's default input set is every package file.
+      files.push('**/*')
+    } else {
+      for (const i of def.inputs) {
+        if (i === '$TURBO_DEFAULT$') {
+          files.push('**/*')
+          continue
+        }
+        const neg = i.startsWith('!')
+        const body = neg ? i.slice(1) : i
+        if (body.startsWith('$TURBO_ROOT$/')) {
+          wsFiles.push((neg ? '!' : '') + body.slice('$TURBO_ROOT$/'.length))
+        } else if (i.includes('$TURBO_ROOT$')) {
+          todos.push(
+            `input ${JSON.stringify(i)}: $TURBO_ROOT$ only maps as a '$TURBO_ROOT$/<path>' ` +
+              'prefix (→ cache.inputs.workspaceFiles) — map manually',
+          )
+        } else files.push(i)
+      }
+    }
+
+    const outFiles: string[] = []
+    const wsOutFiles: string[] = []
+    for (const o of def.outputs ?? []) {
+      if (o.startsWith('!')) {
+        todos.push(
+          `output ${JSON.stringify(o)}: vx outputs have no negation — narrow the positive ` +
+            'globs instead',
+        )
+      } else if (o.startsWith('$TURBO_ROOT$/')) {
+        wsOutFiles.push(o.slice('$TURBO_ROOT$/'.length))
+      } else if (o.includes('$TURBO_ROOT$')) {
+        todos.push(
+          `output ${JSON.stringify(o)}: $TURBO_ROOT$ only maps as a '$TURBO_ROOT$/<path>' ` +
+            'prefix (→ cache.outputs.workspaceFiles) — map manually',
+        )
+      } else outFiles.push(o)
+    }
+
+    const cacheEnv: (string | RawExpr)[] = []
+    if (globals.env) cacheEnv.push({ raw: '...globalEnvInputs' })
+    cacheEnv.push(...envNames)
+
+    const inputs: Record<string, unknown> = { files }
+    if (wsFiles.length > 0) inputs.workspaceFiles = wsFiles
+    if (cacheEnv.length > 0) inputs.env = cacheEnv
+    const outputs: Record<string, unknown> = { files: outFiles }
+    if (wsOutFiles.length > 0) outputs.workspaceFiles = wsOutFiles
+    task.cache = { inputs, outputs }
+  }
+
+  return { name, todos, task }
+}
+
+function presetImportLines(used: ReadonlySet<string>, root: string, dir: string): string[] {
+  if (used.size === 0) return []
+  const rel = relPosix(dir, path.join(root, PRESET_FILE))
+  const spec = rel.startsWith('.') ? rel : `./${rel}`
+  return [`import { ${[...used].sort().join(', ')} } from '${spec}'`]
+}
+
+function renderPreset(inputs: string[], env: string[], pass: string[]): string {
+  const arr = (xs: string[]): string => `[${xs.map((x) => `'${x}'`).join(', ')}]`
+  const lines = [
+    '// Generated by `vx migrate` from turbo.json. TypeScript composition',
+    "// replaces turbo's global fields: each vx.config.ts imports these",
+    '// arrays and spreads them into the matching task fields.',
+  ]
+  if (inputs.length > 0) {
+    lines.push(
+      '',
+      '// From globalDependencies — workspace-root-relative, spread into each',
+      '// task’s cache.inputs.workspaceFiles (the $TURBO_ROOT$ equivalent).',
+      `export const globalInputs = ${arr(inputs)}`,
+    )
+  }
+  if (env.length > 0) {
+    lines.push(
+      '',
+      '// From globalEnv: cache inputs AND passed through to every task',
+      '// (vx child environments are isolated; see docs/schema.md).',
+      `export const globalEnvInputs = ${arr(env)}`,
+    )
+  }
+  if (pass.length > 0) {
+    lines.push(
+      '',
+      '// From globalPassThroughEnv: forwarded to every task, never hashed.',
+      `export const globalPassThroughEnv = ${arr(pass)}`,
+    )
+  }
+  lines.push('')
+  return lines.join('\n')
+}

package/src/cli/migrate.ts

@@ -0,0 +1,219 @@
+// `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.
+
+import path from 'node:path'
+import { relPosix, UserError } from '../util/index.js'
+import { findWorkspaceRoot, listProjects, loadWorkspace } from '../workspace/index.js'
+import { migrateNx } from './migrate-nx.js'
+import { migrateTurbo } from './migrate-turbo.js'
+
+export interface MigrateArgs {
+  dry: boolean
+  force: boolean
+  from?: 'turbo' | 'nx'
+  error?: string
+}
+
+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') return { ...out, error: `--from must be turbo or nx` }
+      out.from = v
+    } else if (a?.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    else return { ...out, error: `unexpected argument: ${a}` }
+  }
+  return out
+}
+
+/** Verbatim TS expression spliced into a generated array (preset spreads). */
+export interface RawExpr {
+  readonly raw: string
+}
+
+export interface GeneratedTask {
+  name: string
+  /** Rendered as `// TODO(vx-migrate): …` above the task + listed in the report. */
+  todos: string[]
+  /** TaskConfig-shaped object; arrays may contain RawExpr splices.
+   *  null = target has no vx representation (skipped; todos explain). */
+  task: Record<string, unknown> | null
+}
+
+export interface GeneratedProject {
+  /** package.json name */
+  name: string
+  /** absolute project dir */
+  dir: string
+  importLines: string[]
+  tasks: GeneratedTask[]
+}
+
+export interface MigrationPlan {
+  /** report lines printed right under the source line */
+  headerNotes: string[]
+  projects: GeneratedProject[]
+  /** extra root-relative files (e.g. the preset) */
+  extraFiles: { relPath: string; contents: string }[]
+  /** trailing report lines (e.g. implicit Nx deps) */
+  notes: string[]
+}
+
+export async function migrateCmd(args: readonly string[]): 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))
+
+  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()
+
+  // 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 === '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 {
+      throw new UserError('nothing to migrate: no turbo.json or nx.json at the workspace root')
+    }
+  } else if (hasTurbo) {
+    source = 'turbo.json'
+    plan = await migrateTurbo(root, metas)
+  } else {
+    throw new UserError('nothing to migrate: no turbo.json or nx.json at the workspace root')
+  }
+
+  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) })
+  }
+  for (const f of plan.extraFiles) {
+    files.push({ relPath: f.relPath, abs: path.join(root, f.relPath), contents: f.contents })
+  }
+
+  if (!parsed.dry && !parsed.force) {
+    const conflicts: string[] = []
+    for (const p of plan.projects) {
+      if (p.tasks.length === 0) continue
+      const meta = metas.find((m) => m.dir === p.dir)
+      if (meta?.configPath) conflicts.push(relPosix(root, meta.configPath))
+    }
+    for (const f of plan.extraFiles) {
+      if (await Bun.file(path.join(root, f.relPath)).exists()) conflicts.push(f.relPath)
+    }
+    if (conflicts.length > 0) {
+      throw new UserError(
+        'refusing to overwrite existing files (pass --force to overwrite):\n' +
+          `  ${conflicts.join('\n  ')}`,
+      )
+    }
+  }
+
+  if (parsed.dry) {
+    for (const f of files) {
+      process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
+    }
+  } else {
+    for (const f of files) await Bun.write(f.abs, f.contents)
+  }
+
+  const todoList: string[] = []
+  let clean = 0
+  for (const p of plan.projects) {
+    for (const t of p.tasks) {
+      if (t.todos.length === 0 && t.task !== null) clean++
+      for (const reason of t.todos) todoList.push(`${p.name}#${t.name}: ${reason}`)
+    }
+  }
+  const report: string[] = [`vx migrate: ${source} → vx.config.ts`]
+  for (const n of plan.headerNotes) report.push(`note: ${n}`)
+  report.push(
+    '',
+    `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
+      `${todoList.length} TODO${todoList.length === 1 ? '' : 's'}${todoList.length > 0 ? ':' : ''}`,
+  )
+  for (const line of todoList) report.push(`  ${line}`)
+  report.push(...plan.notes)
+  report.push(parsed.dry ? 'files (dry run, nothing written):' : 'files written:')
+  for (const f of files) report.push(`  ${f.relPath}`)
+  process.stdout.write(`${report.join('\n')}\n`)
+  return 0
+}
+
+// ─── TS emission ──────────────────────────────────────────────────────
+
+const IDENT = /^[A-Za-z_$][\w$]*$/
+
+function quote(s: string): string {
+  return `'${s.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
+}
+
+function isRawExpr(v: unknown): v is RawExpr {
+  return typeof v === 'object' && v !== null && typeof (v as RawExpr).raw === 'string'
+}
+
+function renderValue(v: unknown, indent: string): string {
+  if (isRawExpr(v)) return v.raw
+  if (typeof v === 'string') return quote(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)},`,
+  )
+  return `{\n${body.join('\n')}\n${indent}}`
+}
+
+function renderConfigFile(source: string, p: GeneratedProject): string {
+  const lines: string[] = [
+    `// Generated by \`vx migrate\` from ${source}. Review the TODO(vx-migrate)`,
+    "// comments, then wrap the object in defineProject() from '@vzn/vx' for",
+    '// editor type-checking.',
+  ]
+  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)
+    lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
+  }
+  lines.push('  },', '}', '')
+  return lines.join('\n')
+}