@vzn/vx-migrate 0.0.0 → 0.0.484

package/src/nx/nx-deps.ts

@@ -0,0 +1,272 @@
+// An Nx target's `dependsOn` as vx edges. Nx separates a specific
+// project's target with a COLON (`ui:build`); vx's separator is `#`.
+// Passed through, the string form read as a task named `ui:build` in the
+// DEPENDENT's own project and the migrated workspace refused to run —
+// "depends on web#ui:build but no such task is declared", from a config
+// vx-migrate itself wrote (walked the Nx path, 2026-09-20). Extracted from
+// `buildTask` in item 606; the rules are unchanged.
+
+import type { ProjectMeta } from '@vzn/vx'
+
+/** The vx task an Nx `project:target:configuration` reaches, or null when the target lacks it. */
+export type TaskNameFor = (project: string, target: string, configuration: string) => string | null
+
+/**
+ * Nx adds an edge to a project's target only when the project HAS that
+ * target (`processTasksForSingleProject`), and says nothing otherwise:
+ * nx-examples' `targetDefaults` give every `typecheck` a `codegen` that
+ * one project declares. Passed through, core refused the whole run —
+ * "depends on …#codegen but no such task is declared". Dropped here as
+ * Nx drops it, for this project and a named one alike.
+ */
+export type HasTarget = (project: string, target: string) => boolean
+
+/**
+ * The graph nodes a `projects` list names, ported from Nx's
+ * `findMatchingProjects` (nx 23.2): a `name:`, `tag:` or `directory:`
+ * label, or none, which tries the name and then the project's root
+ * directory; minimatch globs (`dot`); a bare word that names no project
+ * matches names it stands in as a word, case-insensitive (`foo` is
+ * `foo_bar`, not `foo-e2e`); `!` excludes, and a list that opens with an
+ * exclusion starts from every node. vx read names and `*` alone, so
+ * `libs/shared/*` (a directory) matched nothing and its edge or input
+ * was dropped.
+ */
+export function matchNxProjects(
+  patterns: readonly string[],
+  nodes: ReadonlyArray<{
+    readonly name: string
+    readonly tags: readonly string[]
+    readonly root?: string
+  }>,
+): string[] {
+  if (patterns.every((p) => p.length === 0)) return []
+  const byName = new Map(nodes.map((n) => [n.name, n]))
+  const glob = (p: string, s: string): boolean => s === p || new Bun.Glob(p).match(s)
+  const out = new Set<string>()
+  const list = patterns[0]!.startsWith('!') ? ['*', ...patterns] : patterns
+  for (const raw of list) {
+    if (raw.length === 0 || raw.startsWith('nx-cloud:')) continue
+    const exclude = raw.startsWith('!')
+    let value = exclude ? raw.slice(1) : raw
+    let type = 'unlabeled'
+    if (byName.has(value)) type = 'name'
+    else if (value.includes(':')) {
+      // Nx drops the head whether or not it is a label it knows.
+      const head = value.slice(0, value.indexOf(':'))
+      if (['name', 'tag', 'directory'].includes(head)) type = head
+      value = value.slice(value.indexOf(':') + 1)
+    }
+    const put = (name: string): void => {
+      if (exclude) out.delete(name)
+      else out.add(name)
+    }
+    if (value === '*') {
+      for (const n of nodes) put(n.name)
+      continue
+    }
+    const pattern = TARGET_GLOB.test(value)
+    const byNames = (): void => {
+      if (byName.has(value)) return put(value)
+      if (!pattern) {
+        const word = new RegExp(`(?<![@a-zA-Z0-9-])${value}(?![@a-zA-Z0-9-])`, 'i')
+        for (const n of nodes) if (word.test(n.name)) put(n.name)
+        return
+      }
+      for (const n of nodes) if (glob(value, n.name)) put(n.name)
+    }
+    const byDirectory = (): void => {
+      for (const n of nodes) if (n.root !== undefined && glob(value, n.root)) put(n.name)
+    }
+    if (type === 'tag') {
+      for (const n of nodes)
+        if (n.tags.includes(value) || (pattern && n.tags.some((t) => glob(value, t)))) put(n.name)
+    } else if (type === 'name') byNames()
+    else if (type === 'directory') byDirectory()
+    else {
+      const size = out.size
+      byNames()
+      if (out.size === size) byDirectory()
+    }
+  }
+  return [...out]
+}
+
+/** Nx's `isGlobPattern`: a target holding one of these is a pattern. */
+const TARGET_GLOB = /[*|{}()[]/
+
+/**
+ * Nx (19.5+) expands a target glob in `dependsOn` over every target name
+ * in the workspace (`expandWildcardTargetConfiguration`), after reading a
+ * `project:` head, and keeps the edge where the project has the target.
+ * Read as `project:target`, TanStack/router's `test:e2e--*` named project
+ * `test` and each of 140 aggregators lost the modes it fans out to
+ * (2026-09-28).
+ */
+function expandTargetGlobs(
+  entries: readonly unknown[],
+  targetNames: readonly string[],
+  isProject: (name: string) => boolean,
+  ownTarget: (name: string) => boolean,
+): unknown[] {
+  const expand = (pattern: string): string[] => {
+    const glob = new Bun.Glob(pattern)
+    return targetNames.filter((t) => glob.match(t))
+  }
+  // A glob's match another entry names already is that entry's edge (`^bui*` beside `^build`).
+  const literal = new Set(entries.filter((d) => typeof d === 'string'))
+  const fresh = (ds: string[]): string[] => ds.filter((d) => !literal.has(d))
+  return entries.flatMap((d): unknown[] => {
+    if (typeof d === 'string') {
+      if (!TARGET_GLOB.test(d)) return [d]
+      if (d.startsWith('^')) return fresh(expand(d.slice(1)).map((t) => `^${t}`))
+      const colon = d.indexOf(':')
+      const head = colon > 0 ? d.slice(0, colon) : ''
+      if (head !== '' && isProject(head)) {
+        return fresh(expand(d.slice(colon + 1)).map((t) => `${head}:${t}`))
+      }
+      // A same-project glob keeps only this project's targets: a match
+      // another project declares (`test:e2e--webkit`) read as project
+      // `test` and drew a dropped-edge todo per aggregator (TanStack/router).
+      return fresh(expand(d).filter(ownTarget))
+    }
+    if (d && typeof d === 'object') {
+      const t = (d as Record<string, unknown>).target
+      if (typeof t === 'string' && TARGET_GLOB.test(t)) {
+        return expand(t).map((target) => ({ ...(d as Record<string, unknown>), target }))
+      }
+    }
+    return [d]
+  })
+}
+
+export function mapNxDeps(
+  raw: readonly unknown[],
+  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  ownTarget: (name: string) => boolean,
+  taskNameFor: TaskNameFor,
+  hasTarget: HasTarget,
+  todos: string[],
+  matchProjects: (patterns: readonly string[]) => string[] = (ps) => [...ps],
+  targetNames: readonly string[] = [],
+  asked?: { readonly node: string; readonly configuration: string },
+  /** This target's options, its configuration's merged in: what `options: "forward"` hands on. */
+  forwarded?: Readonly<Record<string, unknown>>,
+): string[] {
+  const entries = expandTargetGlobs(raw, targetNames, (p) => metaByNode.has(p), ownTarget)
+  const deps: string[] = []
+  // Said once per task and without the dependency's name: cypress's
+  // atomized `e2e-ci` forwards params to each spec's task, and a line
+  // per spec name was a warning line per spec on every run.
+  const forwards = { options: false, params: false }
+  // Nx hands every edge the configuration the run asked for, and each
+  // target runs it where it declares it, else its default
+  // (`resolveConfiguration`). `build:ci`'s `lint` ran lint's default.
+  const named = (project: string, t: string): string =>
+    (asked && taskNameFor(project, t, asked.configuration)) ?? t
+  const self = asked?.node ?? ''
+  for (const d of entries) {
+    if (typeof d === 'string') {
+      // `^name` is every dependency's `name`, whatever the name holds: the
+      // colon in `^rsbuild:typecheck` (an inferred target) is the target's
+      // own, and splitting there read project `^rsbuild`, which no graph
+      // has, and dropped the edge.
+      if (d.startsWith('^')) {
+        deps.push(d)
+        continue
+      }
+      const colon = d.indexOf(':')
+      if (colon <= 0) {
+        if (ownTarget(d)) deps.push(named(self, d))
+        continue
+      }
+      const project = d.slice(0, colon)
+      const rest = d.slice(colon + 1)
+      const m = metaByNode.get(project)
+      // Nx splits at the colon only when the head names a project; else
+      // the whole string is a target of this project (`test:unit`, as
+      // script-inferred targets are named). It was read as project `test`
+      // and the edge dropped (item 915). This project's own target ranks
+      // first (`splitTargetFromNodes`).
+      if (ownTarget(d)) {
+        deps.push(named(self, d))
+        continue
+      }
+      if (m === undefined || rest === '') {
+        todos.push(
+          `dependsOn ${JSON.stringify(d)} names ${JSON.stringify(project)}, which is not a ` +
+            'workspace package in this graph — edge dropped',
+        )
+        continue
+      }
+      // The rest is ONE target name, colons and all, as Nx's
+      // `readProjectAndTargetFromTargetString` joins it: `ui:build:esm` is
+      // ui's `build:esm`, and `ui:build:ci` names target `build:ci`, never
+      // build's `ci` configuration (the run's configuration is what an edge
+      // passes on). Nx draws no edge where ui has no such target; vx sent
+      // one to the configuration's task, or to `build` with a todo.
+      if (hasTarget(project, rest)) deps.push(`${m.name}#${named(project, rest)}`)
+      continue
+    }
+    if (d && typeof d === 'object') {
+      const o = d as Record<string, unknown>
+      const t = typeof o.target === 'string' ? o.target : undefined
+      if (t === undefined) {
+        todos.push(`dependsOn ${JSON.stringify(d)} has no target — dropped`)
+        continue
+      }
+      // `options: "forward"` hands the dependency this target's options as
+      // overrides (`createTaskOverrides`): a different command, which vx's
+      // one task per target cannot be. Nothing to hand on, nothing to say
+      // (cypress's atomized `e2e-ci` forwards its empty options).
+      if (o.options === 'forward' && forwarded !== undefined && Object.keys(forwarded).length > 0)
+        forwards.options = true
+      // `ignore` is Nx's default; only `forward` asks for something vx lacks.
+      if (o.params === 'forward') forwards.params = true
+      const raw = o.projects ?? (o.dependencies === true ? 'dependencies' : undefined)
+      // Nx reads a lone string as a one-entry list (`projects: "b"`); it
+      // was not representable here, and the edge dropped (item 1053).
+      const projects =
+        typeof raw === 'string' && raw !== 'self' && raw !== 'dependencies' ? [raw] : raw
+      if (projects === undefined || projects === 'self') {
+        if (ownTarget(t)) deps.push(named(self, t))
+      } else if (projects === 'dependencies') deps.push(`^${t}`)
+      else if (Array.isArray(projects) && projects.every((p) => typeof p === 'string')) {
+        // Patterns and tags (`lib-*`, `tag:lib`) name the graph's nodes;
+        // only an exact name that is no package is worth a line.
+        for (const node of matchProjects(projects)) {
+          const m = metaByNode.get(node)
+          if (m && hasTarget(node, t)) deps.push(`${m.name}#${named(node, t)}`)
+        }
+        // A pattern, or a word or directory Nx matches, is no name to report.
+        for (const p of projects) {
+          if (
+            /^!|^tag:|\*/.test(p) ||
+            metaByNode.has(p) ||
+            matchProjects([p]).some((n) => metaByNode.has(n))
+          )
+            continue
+          todos.push(
+            `dependsOn project ${JSON.stringify(p)} is not a workspace package — edge dropped`,
+          )
+        }
+      } else todos.push(`dependsOn ${JSON.stringify(d)} not representable in vx`)
+      continue
+    }
+    todos.push(`dependsOn ${JSON.stringify(d)} not representable in vx`)
+  }
+  if (forwards.options) {
+    todos.push(
+      'dependsOn `options: "forward"` is not supported — the dependency runs with its own ' +
+        "options, not this target's",
+    )
+  }
+  if (forwards.params) {
+    todos.push(
+      'dependsOn `params: "forward"` is not supported — forward args via `vx run … -- args` instead',
+    )
+  }
+  // One edge spelled twice (`ui:gen` and `{ projects: ["ui"], target: "gen" }`)
+  // is one dependency; the written config listed it twice.
+  return [...new Set(deps)]
+}

package/src/nx/nx-dotenv.ts

@@ -0,0 +1,106 @@
+// Which `.env` files Nx loads for a task: `getEnvPathsForTask`
+// (tasks-runner/task-env-paths.ts) and `getOwnerTargetForTask`
+// (task-env.ts), the same in Nx 22.7 and 23.2. The project's own files come
+// before the workspace root's, the most specific name first
+// (`.env.build.production.local` … `.env`), and the first file to define a
+// name wins. The mapper keeps the ones that EXIST, from one directory
+// listing per project per run, so a task with none costs nothing at run
+// time; the bins load them (`nx-dotenv.cjs`).
+
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+/** A target's `metadata`, as far as the owner-target rule reads it. */
+interface TargetMeta {
+  readonly metadata?: { readonly nonAtomizedTarget?: unknown }
+}
+
+/** `.env` file names per directory (workspace-relative, `.` for the root). */
+export type DotenvListing = ReadonlyMap<string, ReadonlySet<string>>
+
+function variants(identifier: string, root: string | undefined): string[] {
+  const p = root ? `${root}/` : ''
+  if (identifier) {
+    return [
+      `${p}.env.${identifier}.local`,
+      `${p}.env.${identifier}`,
+      `${p}.${identifier}.local.env`,
+      `${p}.${identifier}.env`,
+    ]
+  }
+  return [`${p}.env.local`, `${p}.local.env`, `${p}.env`]
+}
+
+/** Nx's candidate list, workspace-relative, in load order. */
+export function dotenvCandidates(
+  projectRoot: string,
+  target: string,
+  configuration: string | undefined,
+  nonAtomizedTarget: string | undefined,
+): string[] {
+  const ids: string[] = []
+  if (configuration) {
+    ids.push(`${target}.${configuration}`)
+    if (nonAtomizedTarget) ids.push(`${nonAtomizedTarget}.${configuration}`)
+    ids.push(configuration)
+  }
+  ids.push(target)
+  if (nonAtomizedTarget) ids.push(nonAtomizedTarget)
+  ids.push('')
+  return [
+    ...ids.flatMap((id) => variants(id, projectRoot)),
+    ...ids.flatMap((id) => variants(id, undefined)),
+  ]
+}
+
+/**
+ * The target and parent whose names a task's `.env` files carry, as Nx's
+ * `getOwnerTargetForTask` finds them: the first member of the task's
+ * `targetGroups` group that has a `nonAtomizedTarget`, with that parent.
+ * An atomized `e2e-ci--src/a.cy.ts` loads `.env.e2e-ci` and `.env.e2e`
+ * (cypress puts the metadata on `e2e-ci`); read as its own name and the
+ * metadata of the task itself, it loaded neither.
+ */
+export function ownerTargetOf(
+  target: string,
+  targets: Readonly<Record<string, TargetMeta>>,
+  targetGroups: unknown,
+): readonly [string, string | undefined] {
+  if (typeof targetGroups !== 'object' || targetGroups === null) return [target, undefined]
+  for (const group of Object.values(targetGroups as Record<string, unknown>)) {
+    if (!Array.isArray(group) || !group.includes(target)) continue
+    for (const t of group) {
+      const parent = typeof t === 'string' ? targets[t]?.metadata?.nonAtomizedTarget : undefined
+      if (typeof parent === 'string' && parent.length > 0) return [t as string, parent]
+    }
+  }
+  return [target, undefined]
+}
+
+/** Could `name` be one of Nx's `.env` variants? */
+function isDotenvName(name: string): boolean {
+  return name.startsWith('.env') || (name.startsWith('.') && name.endsWith('.env'))
+}
+
+/** One listing of each directory, the `.env`-shaped names only. */
+export async function listDotenv(root: string, dirs: readonly string[]): Promise<DotenvListing> {
+  const unique = [...new Set(['.', ...dirs])]
+  const lists = await Promise.all(
+    unique.map((d) =>
+      readdir(path.join(root, d)).then(
+        (names) => new Set(names.filter(isDotenvName)),
+        () => new Set<string>(),
+      ),
+    ),
+  )
+  return new Map(unique.map((d, i) => [d, lists[i]!]))
+}
+
+/** The candidates that exist, workspace-relative, in load order. */
+export function existingDotenv(candidates: readonly string[], listing: DotenvListing): string[] {
+  return candidates.filter((c) => {
+    const slash = c.lastIndexOf('/')
+    const dir = slash === -1 ? '.' : c.slice(0, slash)
+    return listing.get(dir === '' ? '.' : dir)?.has(c.slice(slash + 1)) === true
+  })
+}

package/src/nx/nx-inputs.ts

@@ -0,0 +1,210 @@
+// An Nx target's `inputs` as vx's cache inputs. Named inputs expand from
+// the project's scope (nx.json's merged under its own); a path's tokens
+// interpolate as Nx's do, and it is a project glob when it lands in the
+// project, else a workspace one; `{ env }` and
+// `{ runtime }` map to their vx twins, `{ json }` to its whole file; `^x` is recorded for the mapper to
+// resolve over the project graph (nx-upstream.ts). What vx folds through `dependsOn` already
+// (`dependentTasksOutputFiles`) is nothing; `externalDependencies` is a todo saying
+// so. Extracted from `buildTask` in item 606.
+
+import { nxWorkspacePath, underProject } from './nx-outputs.js'
+import { minimatchToVx } from '../glob-grammar.js'
+import { shellQuote } from '../nx-command.js'
+
+export interface NxInputs {
+  readonly files: string[]
+  readonly wsFiles: string[]
+  readonly envNames: string[]
+  /**
+   * Nx's `{ runtime: "<cmd>" }` hashes the command's output, run at the
+   * WORKSPACE ROOT (`hash_runtime.rs`): `cache.inputs.workspaceRuntime`.
+   * It was mapped to `runtime`, which runs in the project dir, so
+   * `cat tools/version.txt` failed the run and a command that runs in both
+   * hashed a different fact (item 913). It was once reported "not
+   * representable in vx" (walked the Nx path, 2026-09-20).
+   */
+  readonly runtimeCmds: string[]
+  /** `^name` / `{ input, dependencies | projects }`: whose `name` to fold. */
+  readonly upstream: Array<{ readonly name: string; readonly of: 'deps' | readonly string[] }>
+}
+
+export function emptyNxInputs(): NxInputs {
+  return { files: [], wsFiles: [], envNames: [], runtimeCmds: [], upstream: [] }
+}
+
+/** Expands `entries` into `into`; a gap is a line in `todos`. */
+export function expandNxInputs(
+  entries: readonly unknown[],
+  named: Readonly<Record<string, unknown[]>>,
+  at: {
+    readonly rel: string
+    readonly name: string
+    readonly outputs?: readonly string[]
+    /** The root package.json's dependency names: every task's key holds them. */
+    readonly rootDeps?: ReadonlySet<string>
+  },
+  into: NxInputs,
+  todos: string[],
+): void {
+  const expand = (entry: unknown, seen: Set<string>): void => {
+    if (typeof entry === 'string') {
+      let s = entry
+      let neg = ''
+      if (s.startsWith('!')) {
+        neg = '!'
+        s = s.slice(1)
+      }
+      if (s.startsWith('^')) {
+        // vx folds each dependency's key through the dependsOn edges, so
+        // taking a dependency input out (`!^prod`) has nothing to remove.
+        if (neg !== '') return
+        into.upstream.push({ name: s.slice(1), of: 'deps' })
+        return
+      }
+      if (s.includes('{')) {
+        // A token anywhere, as Nx interpolates it (item 912).
+        const p = nxWorkspacePath(s, at.rel, at.name)
+        if (p === null) {
+          todos.push(`input ${JSON.stringify(entry)} uses a token vx does not support`)
+          return
+        }
+        if (neg === '' && at.outputs?.some((o) => p === o || p.startsWith(`${o}/`))) {
+          todos.push(
+            `input ${JSON.stringify(entry)} is an output of the project's own targets: git does not ` +
+              'list it, so vx cannot key on it — dropped; the task that writes it keys its dependants through dependsOn',
+          )
+          return
+        }
+        const g = minimatchToVx(p, neg !== '')
+        if (g === null) {
+          todos.push(`input ${JSON.stringify(entry)}: glob syntax vx cannot take — map manually`)
+          return
+        }
+        const own = underProject(g, at.rel)
+        if (own === null) into.wsFiles.push(neg + g)
+        else into.files.push(neg + own)
+        return
+      }
+      // Bare string = named-input reference.
+      const members = named[s]
+      if (members === undefined) {
+        // Over-keyed, never under: an empty input list keyed a cached task
+        // on its config alone, a stale hit after every source edit (an
+        // nx.json `extends` preset not installed where the snapshot is read).
+        if (neg === '') into.files.push('**/*')
+        todos.push(
+          `named input ${JSON.stringify(s)} not found in nx.json or the project — keyed on the whole project (\`**/*\`) until its globs are declared`,
+        )
+        return
+      }
+      if (seen.has(s)) return
+      seen.add(s)
+      for (const e of members) expand(e, seen)
+      return
+    }
+    if (entry && typeof entry === 'object') {
+      const o = entry as Record<string, unknown>
+      if (typeof o.env === 'string') {
+        into.envNames.push(o.env)
+        return
+      }
+      if (typeof o.runtime === 'string') {
+        into.runtimeCmds.push(o.runtime)
+        return
+      }
+      if (typeof o.fileset === 'string' && o.includeIgnored === true) {
+        ignored(entry, o.fileset, o.dependencies === true)
+        return
+      }
+      if (typeof o.fileset === 'string') {
+        // `dependencies: true` is each dependency's fileset, as `^{projectRoot}/…`
+        // is. Expanded as the project's own, a dependency's edit re-keyed
+        // nothing here (nx-examples' inferred `typecheck` carries both).
+        if (o.dependencies === true) into.upstream.push({ name: o.fileset, of: 'deps' })
+        else expand(o.fileset, seen)
+        return
+      }
+      if (typeof o.json === 'string') {
+        // `{ json, fields }` hashes only those fields; the whole file is a
+        // superset. Reported and dropped, a `compilerOptions` edit to the
+        // root tsconfig.json was a hit where Nx re-ran (@nx/vitest infers
+        // it, 2026-09-28).
+        expand(o.json.includes('{') ? o.json : `{workspaceRoot}/${o.json}`, seen)
+        return
+      }
+      if (o.externalDependencies !== undefined) {
+        // Not the project's package.json: Nx's inferred targets name root
+        // devDependencies (eslint, vitest), which only the lockfile keys.
+        // One the root declares is keyed already, with or without a
+        // lockfile plugin (it keys the root's dependencies): nothing to
+        // say. The todo sat on 32 tasks of analogjs for `eslint`.
+        const names = Array.isArray(o.externalDependencies) ? o.externalDependencies : []
+        if (names.length > 0 && names.every((n) => typeof n === 'string' && at.rootDeps?.has(n)))
+          return
+        todos.push(
+          `input {externalDependencies: ${JSON.stringify(o.externalDependencies)}}: vx keys ` +
+            'every task on the lockfile (the whole file, or with a @vzn/vx-lockfile plugin the ' +
+            "project's and the root's dependencies) — safe to drop unless only another project installs one",
+        )
+        return
+      }
+      // Nx hashes the outputs of the tasks this one depends on; vx folds
+      // those tasks' keys (their inputs, transitively) through `dependsOn`,
+      // and an output follows from its inputs. Nothing to map, and the todo
+      // it was sat on 881 tasks of three real Nx repos (G-49).
+      if (o.dependentTasksOutputFiles !== undefined) return
+      // `{ workingDirectory }` hashes where Nx was started (`cwd:relative`
+      // in its plan). A vx task runs in its project dir from wherever vx
+      // is started, so the fact is the same for every run: nothing to key.
+      if (o.workingDirectory === 'relative' || o.workingDirectory === 'absolute') return
+      if (typeof o.input === 'string') {
+        // Nx 23 still reads the pre-17 spellings `projects: "dependencies"`
+        // (`^input`) and `projects: "self"` (the project's own); taken as
+        // project names, each was a todo and the input was dropped.
+        if (o.dependencies === true || o.projects === 'dependencies') {
+          into.upstream.push({ name: o.input, of: 'deps' })
+          return
+        }
+        if (o.projects !== undefined && o.projects !== 'self') {
+          const of = typeof o.projects === 'string' ? [o.projects] : o.projects
+          if (!Array.isArray(of) || !of.every((p) => typeof p === 'string')) {
+            todos.push(`input ${JSON.stringify(entry)} not representable in vx`)
+            return
+          }
+          into.upstream.push({ name: o.input, of: of as string[] })
+          return
+        }
+        expand(o.input, seen)
+        return
+      }
+    }
+    todos.push(`input ${JSON.stringify(entry)} not representable in vx`)
+  }
+  // `{ fileset, includeIgnored: true }` (Nx 23) hashes the path from disk,
+  // gitignored or generated, a missing one included. vx's globs see only
+  // what git lists: mapped as one, a gitignored literal failed the task
+  // before it ran. A literal path is read by a probe at the workspace root
+  // instead, its exit telling a missing file from an empty one.
+  const ignored = (entry: unknown, fileset: string, deps: boolean): void => {
+    const neg = fileset.startsWith('!')
+    const p = nxWorkspacePath(neg ? fileset.slice(1) : fileset, at.rel, at.name)
+    if (deps || p === null || /[*?[{]/.test(p)) {
+      todos.push(
+        `input ${JSON.stringify(entry)}: vx keys only the files git lists, so a gitignored ` +
+          'match is not in the key — read it with a cache.inputs.workspaceRuntime probe',
+      )
+      return
+    }
+    // A negation filters only other includeIgnored matches, and a literal
+    // reads no others.
+    if (!neg) into.runtimeCmds.push(`cat -- ${shellQuote(p)} 2>/dev/null; echo "$?"`)
+  }
+  for (const entry of entries) expand(entry, new Set())
+  // Nx matches a project fileset with no positive glob against every project
+  // file, the negations taken out: nx-recipes' `noMarkdown` is
+  // `["!{projectRoot}/**/*.md"]`, and a `.tsx` edit re-runs its build while a
+  // `.md` edit hits (nx 17.1.3, 2026-10-01). Mapped as written, core refused
+  // the negation-only list and no task of the workspace ran.
+  if (into.files.length > 0 && into.files.every((f) => f.startsWith('!')))
+    into.files.unshift('**/*')
+}