@vzn/vx-migrate 0.0.642 → 0.0.643

package/README.md

@@ -76,7 +76,7 @@ Rules:
 - A task's `tags` (Turbo main, after 2.11.5) map to nothing: Turbo keeps them out of the hash and the run.
 - `envMode: "loose"` (top-level or in `global`, or `TURBO_ENV_MODE=loose`, which wins) is a note: Turbo hands every task the whole environment, vx only the declared names.
 - The workspace keys vx has a home for, top level or in `global`, fill what `.vx/workspace.ts` leaves unset: `run.concurrency` (`"10"`, `"50%"` of the cores) → `run.concurrency`; `cacheMaxSize` / `cacheMaxAge` (`"0"` is off; weeks become days, a bare number days; a size in Turbo's grammar, `7.5GB` or bare bytes, restated whole: `7680MB`) → `cache.retention.maxSize` / `.olderThan`. `TURBO_CONCURRENCY`, `TURBO_CACHE_MAX_SIZE` and `TURBO_CACHE_MAX_AGE` win over turbo.json, as under Turbo; a set one decides, its `0` included.
-- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is `run.affectedBase` when `.vx/workspace.ts` sets none: a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
+- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is the run's base commit (`setBranch({ base })`): a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
 - Turbo hashes each package's `microfrontends.json` (or `.jsonc`) into every task, or the one file `VC_MICROFRONTENDS_CONFIG_FILE_NAME` names; so does `turbo()`.
 - Turbo 2.11's `global` block (`futureFlags.globalConfiguration`) is read as the `globalDependencies`, `globalEnv` and `globalPassThroughEnv` it replaces.
 - An unknown Turbo key is a todo naming it; `extends` is accepted and ignored (the overlay order above is what it means).
@@ -169,7 +169,7 @@ Two cached tasks on one workspace path cannot both keep their cache, and the fir
 
 ### nx.json `defaultBase`
 
-`NX_BASE`, else `defaultBase` (Nx 19's `affected.defaultBase` before it), is `run.affectedBase` when `.vx/workspace.ts` sets none: a bare `vx run test --affected` compares with the ref `nx affected` does.
+`NX_BASE` is the run's base commit (`setBranch({ base })`), and `defaultBase` (Nx 19's `affected.defaultBase` before it, an `origin/` prefix dropped) is `baseBranch` when `.vx/workspace.ts` sets none: a bare `vx run test --affected` compares with the ref `nx affected` does.
 
 ### nx.json `maxCacheSize`
 
@@ -259,7 +259,7 @@ Reads the root pipeline (`tasks` in Turbo 2, `pipeline` in Turbo 1), per-package
 
 ### Nx
 
-Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A repo with no `package.json` at all (Nx's `nx init` outside JS: Nx pinned in `.nx/installation`, projects as `project.json`) is migrated too, natively only: the root is the directory holding `nx.json`, the graph is exported by `.nx/installation`'s `nx`, each config writes the project's Nx `name`, every edge is the explicit `project#target` Nx's graph draws (a `^` edge needs a lockfile plugin, which has no lockfile to read), and `.vx/workspace.ts` declares no plugin, so nothing is installed and core runs the configs alone; `--keep` refuses, as `nx()` would have no `package.json` to install into, and an executor target's `nx-exec` line is a note to rewrite as a command. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `run.affectedBase`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
+Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A repo with no `package.json` at all (Nx's `nx init` outside JS: Nx pinned in `.nx/installation`, projects as `project.json`) is migrated too, natively only: the root is the directory holding `nx.json`, the graph is exported by `.nx/installation`'s `nx`, each config writes the project's Nx `name`, every edge is the explicit `project#target` Nx's graph draws (a `^` edge needs a lockfile plugin, which has no lockfile to read), and `.vx/workspace.ts` declares no plugin, so nothing is installed and core runs the configs alone; `--keep` refuses, as `nx()` would have no `package.json` to install into, and an executor target's `nx-exec` line is a note to rewrite as a command. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `baseBranch`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
 
 ### Vite Task
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.642",
+  "version": "0.0.643",
   "license": "MIT",
   "description": "Adopt @vzn/vx from Turborepo, Nx or package.json scripts: run the repo unchanged, migrate it to vx.config.ts, and keep your Turbo or Nx remote cache",
   "keywords": [
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.642"
+    "@vzn/vx": "^0.0.643"
   },
   "repository": {
     "type": "git",

package/src/migrate-nx.ts

@@ -164,8 +164,8 @@ async function unlistedProjects(
 
 /** A `.vx/workspace.ts` field nx.json's run settings call for. */
 export interface NxWorkspaceField {
-  /** The setting's path: its group, then its field. */
-  readonly field: 'run.concurrency' | 'run.affectedBase' | 'cache.retention'
+  /** The setting's path: its group, then its field, or a top-level key. */
+  readonly field: 'run.concurrency' | 'baseBranch' | 'cache.retention'
   /** The value as TypeScript source; undefined when vx cannot read it. */
   readonly source: string | undefined
   /** What to tell a user whose workspace file this run does not write. */
@@ -199,12 +199,14 @@ export function nxWorkspaceFields(json: Record<string, unknown> | undefined): Nx
       note: `nx.json \`parallel: ${parallel}\`: add \`run: { concurrency: ${parallel} }\` to .vx/workspace.ts`,
     })
   const base = nx?.defaultBase ?? nx?.affected?.defaultBase
-  if (typeof base === 'string' && base.trim() !== '')
+  if (typeof base === 'string' && base.trim() !== '') {
+    const branch = base.trim().replace(/^origin\//, '')
     out.push({
-      field: 'run.affectedBase',
-      source: quoted(base.trim()),
-      note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`run: { affectedBase: ${JSON.stringify(base.trim())} }\` to .vx/workspace.ts`,
+      field: 'baseBranch',
+      source: quoted(branch),
+      note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`baseBranch: ${JSON.stringify(branch)}\` to .vx/workspace.ts`,
     })
+  }
   const size = nxSizeText(nx?.maxCacheSize)
   if (size !== undefined)
     out.push({

package/src/nx/index.ts

@@ -148,9 +148,11 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
     {
       async config(workspace, ctx) {
         const root = options.root ?? ctx.workspaceRoot
-        if (workspace.run?.affectedBase === undefined) {
-          const base = await nxBase(root)
-          if (base !== undefined) workspace.run = { ...workspace.run, affectedBase: base }
+        const nxBaseCommit = Bun.env['NX_BASE']?.trim()
+        if (nxBaseCommit) ctx.setBranch({ base: nxBaseCommit })
+        if (workspace.baseBranch === undefined) {
+          const branch = await nxDefaultBase(root)
+          if (branch !== undefined) workspace.baseBranch = branch
         }
         if (workspace.run?.concurrency === undefined) {
           const parallel = await nxParallel(root)
@@ -278,19 +280,18 @@ async function nxParallel(root: string): Promise<number | undefined> {
 }
 
 /**
- * What `nx affected` compares with when no `--base` is given: `NX_BASE`,
- * then nx.json's `defaultBase` (Nx 19's `affected.defaultBase` before it).
- * Read by nothing, a git-flow repo's `develop` was lost and a bare
- * `vx run … --affected` diffed against origin/HEAD.
+ * nx.json's `defaultBase` (Nx 19's `affected.defaultBase` before it), the
+ * branch `nx affected` compares with. Read by nothing, a git-flow repo's
+ * `develop` was lost and a bare `vx run … --affected` diffed against
+ * origin/HEAD.
  */
-async function nxBase(root: string): Promise<string | undefined> {
-  const env = Bun.env['NX_BASE']?.trim()
-  if (env) return env
+async function nxDefaultBase(root: string): Promise<string | undefined> {
   const json = (await readNxJson(root).catch(() => null))?.json as
     | { defaultBase?: unknown; affected?: { defaultBase?: unknown } }
     | undefined
   const b = json?.defaultBase ?? json?.affected?.defaultBase
-  return typeof b === 'string' && b.trim() !== '' ? b.trim() : undefined
+  // `baseBranch` is the branch; vx compares with it on `origin`.
+  return typeof b === 'string' && b.trim() !== '' ? b.trim().replace(/^origin\//, '') : undefined
 }
 
 /**

package/src/turbo/index.ts

@@ -78,8 +78,7 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
         const base =
           Bun.env['TURBO_SCM_BASE']?.trim() ||
           githubActionsBase(options.root ?? ctx.workspaceRoot, keys.remoteBaseFallback === true)
-        if (workspace.run?.affectedBase === undefined && base)
-          workspace.run = { ...workspace.run, affectedBase: base }
+        if (base) ctx.setBranch({ base })
       },
       // Turbo's packages are the package manager's members, each a project
       // with no vx.config written. `//#task` keys run on the root, as Turbo

package/src/workspace-plugins.ts

@@ -42,16 +42,21 @@ function entries(plugins: readonly WorkspacePlugin[], indent: string): string[]
   return plugins.map((p) => `${indent}${p.factory}(),`)
 }
 
-/** `run.concurrency` and `run.affectedBase` as one `run: { … }` line. */
+/** `baseBranch: 'main',` as its own line; `run.concurrency` and its group's other fields as one `run: { … }` line. */
 function groupLines(
   fields: readonly { readonly field: string; readonly source: string }[],
 ): string[] {
+  const top: string[] = []
   const groups = new Map<string, string[]>()
   for (const f of fields) {
-    const [group, key] = f.field.split('.') as [string, string]
-    groups.set(group, [...(groups.get(group) ?? []), `${key}: ${f.source}`])
+    const [group, key] = f.field.split('.') as [string, string | undefined]
+    if (key === undefined) top.push(`  ${group}: ${f.source},`)
+    else groups.set(group, [...(groups.get(group) ?? []), `${key}: ${f.source}`])
   }
-  return [...groups].map(([group, entries]) => `  ${group}: { ${entries.join(', ')} },`)
+  return [
+    ...top,
+    ...[...groups].map(([group, entries]) => `  ${group}: { ${entries.join(', ')} },`),
+  ]
 }
 
 /** `.vx/workspace.<format>` declaring `plugins`. */