@vzn/vx 0.0.16 → 0.0.21

package/src/workspace/migration.ts

@@ -0,0 +1,314 @@
+// 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 type { ProjectMeta } from './workspace.js'
+
+/**
+ * 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')}'`
+}
+
+/**
+ * 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 {
+  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 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
+}
+
+export type MigrationFormat = 'ts' | 'mjs'
+
+/**
+ * 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 && !init) {
+    throw new UserError(
+      `nothing to migrate: no ${source === 'package.json scripts' ? 'package.json scripts in any workspace member' : 'tasks in ' + source}`,
+    )
+  }
+
+  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, 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 })
+  }
+  // A migrated workspace must declare its executor and cache — nothing is
+  // applied by default. Emit the workspace file unless the repo already has
+  // one in any supported extension.
+  const hasWorkspaceFile = (
+    await Promise.all(
+      ['vx.workspace.ts', 'vx.workspace.mjs', 'vx.workspace.js'].map((n) =>
+        Bun.file(path.join(root, n)).exists(),
+      ),
+    )
+  ).some(Boolean)
+  if (!hasWorkspaceFile) {
+    const abs = path.join(root, workspaceName)
+    files.push({ relPath: relPosix(root, abs), abs, contents: workspaceFile(format) })
+  }
+
+  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.
+    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.add(relPosix(root, meta.configPath))
+    }
+    // ALSO stat every actual write target. A SYNTHESIZED project (e.g. the Nx
+    // workspace-root node, dir === root) has no discovered meta, so the meta
+    // scan alone would miss an existing vx.config.ts at that path and clobber
+    // it. This also covers the extraFiles (vx-preset.ts).
+    for (const f of files) {
+      if (await Bun.file(f.abs).exists()) conflicts.add(f.relPath)
+    }
+    if (conflicts.size > 0) {
+      throw new UserError(
+        'refusing to overwrite existing files (pass --force to overwrite):\n' +
+          `  ${[...conflicts].join('\n  ')}`,
+      )
+    }
+  }
+
+  if (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[] = []
+  if (empty) {
+    report.push(
+      `${verb}: no package.json scripts to turn into tasks.`,
+      hasWorkspaceFile
+        ? `${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:`,
+      '',
+      ...exampleConfig(format)
+        .trimEnd()
+        .split('\n')
+        .map((l) => `  ${l}`),
+    )
+  } else {
+    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(
+      '',
+      `${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(dry ? 'files (dry run, nothing written):' : 'files written:')
+    for (const f of files) report.push(`  ${f.relPath}`)
+  }
+  const firstTask =
+    plan.projects.flatMap((p) => p.tasks.map((t) => t.name)).find((n) => n === 'build') ??
+    plan.projects[0]?.tasks[0]?.name ??
+    'build'
+  report.push('', `next: vx run ${firstTask} --all`)
+  process.stdout.write(`${report.join('\n')}\n`)
+  return 0
+}
+
+const EXAMPLE_BODY = `export default {
+  tasks: {
+    build: {
+      exec: { command: 'tsc -b' },
+      dependsOn: ['^build'],
+      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
+    },
+  },
+}`
+
+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 ──────────────────────────────────────────────────────
+
+// 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: [] }`
+
+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$]*$/
+
+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
+  // `Object.entries(null)` throws, which would abort the whole migration
+  // 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 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 : quoteTsLiteral(k)}: ${renderValue(x, inner)},`,
+  )
+  return `{\n${body.join('\n')}\n${indent}}`
+}
+
+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. `mjs` is the same
+  // object with nothing to erase.
+  const lines: string[] = [
+    `// 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 : quoteTsLiteral(t.name)
+    lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
+  }
+  lines.push('  },', format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
+  return lines.join('\n')
+}

package/src/workspace/nested-dirs.ts

@@ -7,11 +7,18 @@ import type { ProjectEntry } from './workspace.js'
  * project's task cannot see files inside another project, even if its
  * globs would otherwise match.
  *
- * Sort once, then scan: nested projects of `p` form a contiguous run
- * immediately after `p` in the sorted order (any non-descendant breaks
- * the prefix-match). O(P log P) instead of the naive O(P²) cross
- * product. Stable for any project set with no dir collisions, which
- * the workspace loader already enforces.
+ * Sort once, then scan forward: every dir sharing `p.dir` as a STRING
+ * prefix is contiguous in sorted order, and `p`'s nested descendants
+ * (`p.dir + sep + …`) are a sub-run within that block. But a SIBLING whose
+ * name extends `p.dir` by a char that sorts BELOW `sep` (`-`, `.`, `+`, a
+ * space; `/` is 0x2F) lands BETWEEN `p.dir` and `p.dir + sep` — so a plain
+ * `break` on the first non-descendant would stop before reaching the nested
+ * children (e.g. `foo`, `foo-utils`, `foo/nested` → `foo/nested` missed,
+ * silently breaking the project-boundary invariant). So: collect descendants,
+ * SKIP interlopers that merely share the `p.dir` string prefix, and break only
+ * once we leave the `p.dir` block entirely. The inner loop is still bounded by
+ * that block (near-O(P log P) on real trees; interlopers are few), not the
+ * full tail.
  */
 export function computeNestedProjectDirs(
   entries: Array<Pick<ProjectEntry, 'name' | 'dir'>>,
@@ -25,8 +32,15 @@ export function computeNestedProjectDirs(
     const nested: string[] = []
     for (let j = i + 1; j < sorted.length; j++) {
       const other = sorted[j]!
-      if (!other.dir.startsWith(prefix)) break
-      nested.push(other.dir)
+      if (other.dir.startsWith(prefix)) {
+        nested.push(other.dir)
+      } else if (!other.dir.startsWith(p.dir)) {
+        // Past every dir sharing `p.dir`'s string prefix — no descendant can
+        // follow (they'd sort inside this block), so stop.
+        break
+      }
+      // else: an interloping sibling (`foo-utils` for `foo`) that shares the
+      // string prefix but isn't nested — skip it, descendants may follow.
     }
     result.set(p.name, nested)
   }

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)
@@ -51,7 +119,7 @@ export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
   // per-call sort. Package graphs (unlike task graphs) may legally
   // contain cycles; the bitset sweep requires a DAG, so a cycle
   // (detected by the Kahn pass not draining) falls back wholesale to
-  // the legacy DFS — byte-identical behavior for that rare case.
+  // a per-query reachability search for that rare case.
   const names = [...byName.keys()].sort()
   const index = new Map<string, number>()
   for (let i = 0; i < names.length; i++) index.set(names[i]!, i)
@@ -92,37 +160,42 @@ export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
     return closure
   }
 
-  function legacyTransitive(
-    name: string,
-    edges: Map<string, string[]>,
-    cache: Map<string, string[]>,
-    stack: Set<string> = new Set(),
-  ): string[] {
-    const cached = cache.get(name)
-    if (cached) return cached
-    if (stack.has(name)) return []
-    stack.add(name)
-    const out = new Set<string>()
-    for (const d of edges.get(name) ?? []) {
-      out.add(d)
-      for (const t of legacyTransitive(d, edges, cache, stack)) out.add(t)
+  // Cyclic fallback: everything reachable from `name` via ≥1 edge (so a
+  // node inside a cycle includes itself). Deliberately a self-contained
+  // per-query search rather than a memoized recursion over sub-results:
+  // in a cycle the back-edge contributes nothing, so a shared recursion
+  // computes TRUNCATED closures for the nodes below it and caching those
+  // makes every later answer depend on which node was asked for first.
+  function reachableFrom(name: string, edges: Map<string, string[]>): string[] {
+    const seen = new Set<string>()
+    const stack = [...(edges.get(name) ?? [])]
+    while (stack.length > 0) {
+      const cur = stack.pop()!
+      if (seen.has(cur)) continue
+      seen.add(cur)
+      for (const d of edges.get(cur) ?? []) stack.push(d)
     }
-    stack.delete(name)
-    const result = [...out].sort()
-    cache.set(name, result)
-    return result
+    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) => legacyTransitive(name, edges, memo)
-    }
+    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
@@ -142,7 +215,7 @@ export function buildPackageGraph(projects: ProjectMeta[]): PackageGraph {
 
   return {
     directDeps: (name) => directDeps.get(name) ?? [],
-    transitiveDeps: makeAccessor(directDeps),
+    transitiveDeps: makeAccessor(reachDeps),
     transitiveDependents: makeAccessor(directDependents),
   }
 }