@vzn/vx 0.0.21 → 0.0.23

package/src/graph/task-graph.ts

@@ -1,5 +1,12 @@
-import type { TaskConfig } from '../config.js'
-import { UserError } from '../util/index.js'
+import type { ProjectConfig, TaskConfig } from '../config.js'
+import {
+  asTrees,
+  isLiteralPattern,
+  staticPrefix,
+  taskGlob,
+  UserError,
+  wholeSubtreePrefixes,
+} from '../util/index.js'
 import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
 import {
   DependencySpecError,
@@ -8,6 +15,7 @@ import {
   parseDependencySpec,
   type DependencySpec,
 } from './dependency-spec.js'
+import type { TaskOutcome } from './scheduler.js'
 
 // Re-exported so existing importers keep working while the type's home
 // moves to workspace (it's the joint product of discovery + loading).
@@ -44,31 +52,38 @@ export interface TaskNode {
    * Absent when no plugin declares the stage.
    */
   keyParts?: ReadonlyArray<readonly [name: string, value: string]>
+  /**
+   * Ids of upstream tasks whose declared outputs this task's outputs
+   * overlap: this task ADDS to their trees (twenty's `build:individual`
+   * into `build`'s `dist`; item 588). Its own output set is what its run
+   * added or changed, it cleans and restores only its recorded rows, and
+   * it is never restore-tier. Set by `detectOutputCollisions`, which refuses
+   * the same overlap without an edge.
+   */
+  addsToOutputsOf?: string[]
+  /**
+   * Declared output globs of dependants that add into this task's tree.
+   * The hit path ignores paths they match when it decides whether this
+   * task's tree is already current, so an addition below is not a stray.
+   */
+  outputsAddedToBy?: string[]
+  /**
+   * The dependencies `--exclude-dependencies` took out of the schedule, as
+   * outcomes carrying the key each would have (`excludeDependencies`, then
+   * `prepareRun`). The scheduler never sees them; the key folds them next
+   * to `deps`' own outcomes, so a key is the same whatever the selection.
+   */
+  excludedUpstream?: TaskOutcome[]
 }
 
 export function taskId(project: string, task: string): string {
   return `${project}#${task}`
 }
 
-/**
- * The inverse of `taskId`. Splits on the FIRST `#`, so a task name that itself
- * contains one round-trips: `taskId('a', 'b#c')` → `'a#b#c'` → `['a', 'b#c']`.
- *
- * This exists because it kept being written by hand as `id.split('#', 2)`,
- * which is NOT the inverse — it discards everything after the second segment,
- * so `'a#b#c'` reads back as task `'b'`. Six call sites had that form while
- * `parseDependencySpec` (the surface that decides what actually runs) has
- * always split on the first `#`, so the query layer and the graph disagreed
- * about the identity of the same task: a lookup either found nothing or, worse,
- * answered with a different task's history.
- *
- * A `#`-containing task name is legal and pinned elsewhere in the suite, so
- * this is reachable rather than theoretical.
- */
-export function splitTaskId(id: string): [project: string, task: string] {
-  const i = id.indexOf('#')
-  return i < 0 ? [id, ''] : [id.slice(0, i), id.slice(i + 1)]
-}
+// `splitTaskId` lives in util so the cache (which may not import graph)
+// reads the same rule instead of a copy; re-exported here because the
+// graph is where every reader of a task id looks for it.
+export { splitTaskId } from '../util/index.js'
 
 /**
  * A task is a "group" if it has no `exec` — it exists only to chain
@@ -170,9 +185,23 @@ export function expandRequested(
   return out
 }
 
+/**
+ * The task a config declares under `name`, by OWN property. `tasks` is a
+ * plain object, so `tasks['constructor']` and `tasks['toString']` are
+ * Object.prototype's: `vx show constructor` printed a group task for every
+ * project and `vx run a#toString` ran nothing, exit 0 (item 897).
+ */
+export function declaredTask(
+  config: ProjectConfig | null | undefined,
+  name: string,
+): TaskConfig | undefined {
+  const tasks = config?.tasks
+  return tasks !== undefined && Object.hasOwn(tasks, name) ? tasks[name] : undefined
+}
+
 /** Shared by `expandRequested` + `unresolvedRequests` so the two can't drift. */
 function declaresTask(projects: Map<string, ProjectEntry>, project: string, task: string): boolean {
-  return projects.get(project)?.config.tasks?.[task] !== undefined
+  return declaredTask(projects.get(project)?.config, task) !== undefined
 }
 
 /**
@@ -214,39 +243,87 @@ export interface BuildGraphOptions {
   /** Initial set: `{ project, task }` pairs the user asked to run. */
   requested: Array<{ project: string; task: string }>
   /**
-   * Filter `dependsOn` expansion.
-   *   - `undefined` → every dependsOn entry is followed (default).
-   *   - `'all'`     → no expansion; only the requested nodes are added.
-   *   - `string[]`  → expand normally, but drop edges whose target
-   *                   task name is in the list. `dependsOn.self` and
-   *                   `dependsOn.dependencies` are both filtered.
+   * Set when `projects` is a scoped load rather than the whole workspace. A
+   * literal `^name` no project in `projects` declares may still be declared
+   * by one that was not loaded, so the builder hands it here instead of
+   * refusing it, and the caller judges it against the rest
+   * (`undeclaredDepsError` is the refusal). Unset, `projects` is the whole
+   * workspace and the builder refuses it itself.
    */
-  excludeDependencies?: 'all' | readonly string[]
+  undeclaredDeps?: (taskId: string, name: string) => void
+}
+
+/**
+ * The refusal of a literal `^name` that no project in the workspace
+ * declares: it has no holder anywhere, so it can only be a typo (nx#32779
+ * ran such an edge as no edge, green). A name SOME project declares stays
+ * legal without a holder — a preset spreads `^build` over projects whose
+ * dependencies lack it.
+ */
+export function undeclaredDepsError(taskId: string, name: string): UserError {
+  return new UserError(
+    `Task ${taskId} depends on ^${name} but no project in the workspace declares ${name}`,
+  )
+}
+
+/** One task mid-expansion in `buildTaskGraph`'s walk. */
+interface Frame {
+  node: TaskNode
+  /** Index of the next `dependsOn` entry to resolve. */
+  entry: number
+  /** Whether the current entry has added a new node yet. */
+  added: boolean
+  /** The current entry's later new nodes, not yet in the graph. */
+  pending: TaskNode[] | null
+  /** Index into `pending` of the next one to add. */
+  next: number
 }
 
 export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode> {
-  const { projects, packageGraph, requested, excludeDependencies } = options
-  const skipAll = excludeDependencies === 'all'
-  const skipNames =
-    Array.isArray(excludeDependencies) && excludeDependencies.length > 0
-      ? new Set(excludeDependencies)
-      : null
+  const { projects, packageGraph, requested, undeclaredDeps } = options
   const nodes = new Map<string, TaskNode>()
 
-  function addNode(projectName: string, taskName: string, requested: boolean): TaskNode | null {
+  // The walk keeps its own stack instead of recursing once per edge: a
+  // `dependsOn` chain or ring ~20,000 deep overflowed V8's call stack
+  // (nx#28788's shape) before `detectCycle` could name the cycle. It adds
+  // nodes in the order the recursion did — depth-first, each target's
+  // subtree before the next target — and `detectCycle` walks that order,
+  // so it names the same cycle. Resolving an entry only reads configs and
+  // the package graph, so its targets can all be found first: the first
+  // new one is added at once (its subtree is expanded next, on top of the
+  // stack), the later ones wait in `pending` for their turn.
+  const stack: Frame[] = []
+
+  function add(node: TaskNode): void {
+    nodes.set(node.id, node)
+    if ((node.config.dependsOn?.length ?? 0) > 0) {
+      stack.push({ node, entry: 0, added: false, pending: null, next: 0 })
+    }
+  }
+
+  // Adds `projectName#taskName` to the graph if it is new, and the edge to
+  // it from `frame`'s task (null for a requested task). False when the
+  // project or the task is not declared.
+  function visit(
+    frame: Frame | null,
+    projectName: string,
+    taskName: string,
+    requested: boolean,
+  ): boolean {
     const id = taskId(projectName, taskName)
     const existing = nodes.get(id)
     if (existing) {
       // Promote an already-added node to requested if any caller asked
       // for it directly. Once requested, never demoted.
       if (requested) existing.requested = true
-      return existing
+      frame?.node.deps.push(id)
+      return true
     }
 
     const project = projects.get(projectName)
-    if (!project) return null
-    const taskConfig = project.config.tasks?.[taskName]
-    if (!taskConfig) return null
+    if (!project) return false
+    const taskConfig = declaredTask(project.config, taskName)
+    if (!taskConfig) return false
 
     const node: TaskNode = {
       id,
@@ -257,146 +334,263 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       deps: [],
       requested,
     }
-    nodes.set(id, node)
-
-    if (skipAll) return node
-
-    const rawSpecs = taskConfig.dependsOn ?? []
-    for (const raw of rawSpecs) {
-      let spec: DependencySpec
-      try {
-        spec = parseDependencySpec(raw)
-      } catch (err) {
-        if (err instanceof DependencySpecError) {
-          throw new UserError(`Task ${id}: ${err.message}`)
-        }
-        throw err
-      }
+    if (frame === null) {
+      add(node)
+      return true
+    }
+    frame.node.deps.push(id)
+    if (frame.added) (frame.pending ??= []).push(node)
+    else {
+      frame.added = true
+      add(node)
+    }
+    return true
+  }
 
-      // dependsOn is about which tasks to ADD to the graph, not which
-      // to filter. BARE wildcards ("*"/"^*" = "everything upstream") and
-      // negation aren't meaningful here — they're cache.inputs.tasks
-      // operations. PARTIAL patterns (`build.*`, `^build.*`) are legal:
-      // they name a namespace of tasks to add (Nx 19.5 parity).
-      if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
-        throw new UserError(`Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`)
-      }
-      if (spec.negated) {
-        throw new UserError(`Task ${id}: dependsOn does not accept negation (got "${raw}")`)
+  // Every task name `projects` declares, built on the first `^name` that
+  // finds no holder and whose own project does not declare it either.
+  let declared: Set<string> | null = null
+  function declaredAnywhere(projectName: string, name: string): boolean {
+    if (declaresTask(projects, projectName, name)) return true
+    if (declared === null) {
+      declared = new Set()
+      for (const p of projects.values()) {
+        for (const t of Object.keys(p.config.tasks ?? {})) declared.add(t)
       }
-      if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
-        throw new UserError(
-          `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
-        )
+    }
+    return declared.has(name)
+  }
+
+  // Resolves one `dependsOn` entry of `frame`'s task into its edges.
+  function resolveEntry(frame: Frame, raw: string): void {
+    const { node } = frame
+    const { id, projectName, taskName } = node
+    let spec: DependencySpec
+    try {
+      spec = parseDependencySpec(raw)
+    } catch (err) {
+      if (err instanceof DependencySpecError) {
+        throw new UserError(`Task ${id}: ${err.message}`)
       }
-      // CLI `--exclude-dependencies=name1,name2` drops edges whose target
-      // task name matches, regardless of bucket (self / deps / cross).
-      // Pattern specs re-apply the filter per EXPANDED name below.
-      if (skipNames?.has(spec.task)) continue
-
-      if (spec.kind === 'self') {
-        if (isTaskPattern(spec.task)) {
-          // `build.*` — every OTHER same-project task matching the
-          // pattern (the declaring task never matches itself — that
-          // would be an instant self-cycle). Zero matches is legal: a
-          // preset-spread pattern needn't match in every project.
-          const re = compileTaskPattern(spec.task)
-          for (const name of Object.keys(project.config.tasks ?? {})) {
-            if (name === taskName || !re.test(name)) continue
-            if (skipNames?.has(name)) continue
-            const child = addNode(projectName, name, false)
-            if (child) node.deps.push(child.id)
-          }
-        } else {
-          // Missing target is a hard error — the user typed a name that
-          // doesn't resolve in this project.
-          const child = addNode(projectName, spec.task, false)
-          if (!child) {
-            throw new UserError(
-              `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
-            )
-          }
-          node.deps.push(child.id)
-        }
-      } else if (spec.kind === 'deps') {
-        // Nearest-holder frontier (Turbo/Nx direct-deps parity +
-        // sparse bridging): walk the package dep graph from this
-        // project's direct deps; each path stops at the FIRST package
-        // declaring the task — a holder's own dependsOn is responsible
-        // for anything deeper. Packages without the task are passed
-        // through so a sparse dep doesn't break ordering to deeper
-        // holders. The visited set both dedupes shared subtrees and
-        // terminates on package-graph cycles (legal in PMs).
-        //
-        // With a pattern (`^build.*`), a holder is a package declaring
-        // AT LEAST ONE matching task and it receives edges to ALL its
-        // matches — holder-ness is about declaration, so a holder still
-        // stops the walk even when every match is --exclude-dependencies'd.
-        //
-        // The declaring project seeds `visited`: package graphs may legally
-        // contain cycles (the common "b devDepends on a for its tests"
-        // shape), and a cycle walks the frontier straight back to the
-        // origin. Mirrors the self-pattern rule below — a task can never
-        // depend on itself.
-        const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
-        const visited = new Set<string>([projectName])
-        const frontier = [...packageGraph.directDeps(projectName)]
-        while (frontier.length > 0) {
-          const target = frontier.pop()!
-          if (visited.has(target)) continue
-          visited.add(target)
-          if (re === null) {
-            const child = addNode(target, spec.task, false)
-            if (child) node.deps.push(child.id)
-            else frontier.push(...packageGraph.directDeps(target))
-          } else {
-            const names = Object.keys(projects.get(target)?.config.tasks ?? {}).filter((n) =>
-              re.test(n),
-            )
-            if (names.length > 0) {
-              for (const name of names) {
-                if (skipNames?.has(name)) continue
-                const child = addNode(target, name, false)
-                if (child) node.deps.push(child.id)
-              }
-            } else {
-              frontier.push(...packageGraph.directDeps(target))
-            }
-          }
+      throw err
+    }
+
+    // dependsOn is about which tasks to ADD to the graph, not which
+    // to filter. BARE wildcards ("*"/"^*" = "everything upstream") and
+    // negation aren't meaningful here — they're cache.inputs.tasks
+    // operations. PARTIAL patterns (`build.*`, `^build.*`) are legal:
+    // they name a namespace of tasks to add (Nx 19.5 parity).
+    if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
+      throw new UserError(`Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`)
+    }
+    if (spec.negated) {
+      throw new UserError(`Task ${id}: dependsOn does not accept negation (got "${raw}")`)
+    }
+    if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
+      throw new UserError(
+        `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
+      )
+    }
+    if (spec.kind === 'self') {
+      if (isTaskPattern(spec.task)) {
+        // `build.*` — every OTHER same-project task matching the
+        // pattern (the declaring task never matches itself — that
+        // would be an instant self-cycle). Zero matches is legal: a
+        // preset-spread pattern needn't match in every project.
+        const re = compileTaskPattern(spec.task)
+        for (const name of Object.keys(projects.get(projectName)!.config.tasks ?? {})) {
+          if (name === taskName || !re.test(name)) continue
+          visit(frame, projectName, name, false)
         }
       } else {
-        // Cross-project edge: pkg#task. Missing target is a hard error
-        // because the user named the package + task explicitly.
-        const child = addNode(spec.project, spec.task, false)
-        if (!child) {
+        // Missing target is a hard error — the user typed a name that
+        // doesn't resolve in this project.
+        if (!visit(frame, projectName, spec.task, false)) {
           throw new UserError(
-            `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+            `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+          )
+        }
+      }
+    } else if (spec.kind === 'deps') {
+      // Nearest-holder frontier (Turbo/Nx direct-deps parity +
+      // sparse bridging): walk the package dep graph from this
+      // project's direct deps; each path stops at the FIRST package
+      // declaring the task — a holder's own dependsOn is responsible
+      // for anything deeper. Packages without the task are passed
+      // through so a sparse dep doesn't break ordering to deeper
+      // holders. The visited set both dedupes shared subtrees and
+      // terminates on package-graph cycles (legal in PMs).
+      //
+      // With a pattern (`^build.*`), a holder is a package declaring
+      // AT LEAST ONE matching task and it receives edges to ALL its
+      // matches — holder-ness is about declaration, so a holder still
+      // stops the walk even when `--exclude-dependencies` drops every
+      // edge to it (`excludeDependencies`).
+      //
+      // The declaring project seeds `visited`: package graphs may legally
+      // contain cycles (the common "b devDepends on a for its tests"
+      // shape), and a cycle walks the frontier straight back to the
+      // origin. Mirrors the self-pattern rule above — a task can never
+      // depend on itself.
+      const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
+      const visited = new Set<string>([projectName])
+      const frontier = [...packageGraph.directDeps(projectName)]
+      let held = false
+      while (frontier.length > 0) {
+        const target = frontier.pop()!
+        if (visited.has(target)) continue
+        visited.add(target)
+        if (re === null) {
+          if (visit(frame, target, spec.task, false)) held = true
+          else frontier.push(...packageGraph.directDeps(target))
+        } else {
+          const names = Object.keys(projects.get(target)?.config.tasks ?? {}).filter((n) =>
+            re.test(n),
           )
+          if (names.length > 0) {
+            for (const name of names) visit(frame, target, name, false)
+          } else {
+            frontier.push(...packageGraph.directDeps(target))
+          }
         }
-        node.deps.push(child.id)
+      }
+      // A pattern that matches nothing stays legal, as `build.*` does.
+      if (re === null && !held && !declaredAnywhere(projectName, spec.task)) {
+        if (undeclaredDeps === undefined) throw undeclaredDepsError(id, spec.task)
+        undeclaredDeps(id, spec.task)
+      }
+    } else {
+      // Cross-project edge: pkg#task. Missing target is a hard error
+      // because the user named the package + task explicitly.
+      if (!visit(frame, spec.project, spec.task, false)) {
+        throw new UserError(
+          `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+        )
       }
     }
-
-    // Stable ordering for deterministic scheduling and cache keys — deduped:
-    // a target named twice (an exact entry + a pattern matching it, or a
-    // literal duplicate) must contribute ONE edge, not a double-folded
-    // upstream hash and a doubled DOT edge.
-    node.deps = [...new Set(node.deps)].sort()
-    return node
   }
 
   for (const { project, task } of requested) {
-    addNode(project, task, true)
+    visit(null, project, task, true)
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      const { node, pending } = frame
+      if (pending !== null && frame.next < pending.length) {
+        // An earlier target's subtree may have added it meanwhile.
+        const next = pending[frame.next++]!
+        if (!nodes.has(next.id)) add(next)
+        continue
+      }
+      const entries = node.config.dependsOn!
+      if (frame.entry < entries.length) {
+        frame.added = false
+        frame.pending = null
+        frame.next = 0
+        resolveEntry(frame, entries[frame.entry++]!)
+        continue
+      }
+      // Stable ordering for deterministic scheduling and cache keys — deduped:
+      // a target named twice (an exact entry + a pattern matching it, or a
+      // literal duplicate) must contribute ONE edge, not a double-folded
+      // upstream hash and a doubled DOT edge.
+      node.deps = [...new Set(node.deps)].sort()
+      stack.pop()
+    }
   }
 
+  checkGraph(nodes)
+  return nodes
+}
+
+/**
+ * What a task graph must hold before it is scheduled: each node under its
+ * own id, every dep a node, no cycle, and no two tasks deleting each
+ * other's outputs. The builder's output holds the first two by
+ * construction; the `graph` stage runs this again after its plugins, which
+ * could move a node to another key (the scheduler then died on a raw
+ * TypeError) or drop the edge that made two overlapping outputs an
+ * addition, and a green run lost one task's files (item 981). The addition
+ * marks are derived here, so they are cleared first and follow the edges
+ * the graph has now.
+ */
+export function checkGraph(nodes: Map<string, TaskNode>): void {
+  for (const [key, node] of nodes) {
+    if (node.id !== key) {
+      throw new Error(`the task ${node.id} is stored under '${key}', not its own id`)
+    }
+    for (const dep of node.deps) {
+      if (!nodes.has(dep)) {
+        throw new Error(`${node.id} depends on '${dep}', which is not a task in this run's graph`)
+      }
+    }
+    delete node.addsToOutputsOf
+    delete node.outputsAddedToBy
+  }
   detectCycle(nodes)
   detectOutputCollisions(nodes)
-  return nodes
 }
 
-/** A glob with no wildcard — it names exactly one path. */
-function isLiteralGlob(g: string): boolean {
-  return g.search(/[*?[\]]/) === -1
+/**
+ * `--exclude-dependencies`: take `dependsOn` edges out of the SCHEDULE, not
+ * out of the graph. `'all'` drops every edge; a name list drops each edge
+ * whose target task has one of those names, whichever `dependsOn` form
+ * reached it. What stays scheduled is what the requested tasks still reach;
+ * the rest leaves `nodes` and is returned with its `deps` intact, and each
+ * scheduled task that lost an edge is listed in `dropped` with the ids it
+ * lost. An edge to a task that stays scheduled (requested itself, or
+ * reached another way) is kept: the two still run in order.
+ *
+ * Under `'all'` a group's own edges stay: a group is its members (running
+ * one is running them), so `vx run ci --exclude-dependencies` runs what
+ * `ci` names without what THEY depend on. Dropping them left the group
+ * alone, and the run ran nothing and exited 0 (item 894). A name list
+ * still drops a group's edge it names: `--exclude-dependencies=lint.oxfmt`
+ * takes one member out of `lint`.
+ *
+ * Run on the whole graph, after the `graph` and `key` stages, because a
+ * dropped dependency is still KEYED: a key is a function of inputs, never of
+ * the selection (nx#35234), so the caller derives each dropped task's key
+ * as a full run would and hands it to the dependant (`excludedUpstream`).
+ */
+export function excludeDependencies(
+  nodes: Map<string, TaskNode>,
+  exclude: 'all' | readonly string[],
+): { keyOnly: Map<string, TaskNode>; dropped: Map<string, string[]> } {
+  const names = exclude === 'all' ? null : new Set(exclude)
+  const keptBy =
+    (node: TaskNode) =>
+    (dep: string): boolean =>
+      names === null ? isGroupTask(node) : !names.has(nodes.get(dep)!.taskName)
+  const scheduled = new Set<string>()
+  const stack = [...nodes.values()].filter((n) => n.requested).map((n) => n.id)
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (scheduled.has(id)) continue
+    scheduled.add(id)
+    const node = nodes.get(id)!
+    const kept = keptBy(node)
+    for (const dep of node.deps) if (kept(dep)) stack.push(dep)
+  }
+  const keyOnly = new Map<string, TaskNode>()
+  const dropped = new Map<string, string[]>()
+  for (const [id, node] of nodes) {
+    if (!scheduled.has(id)) {
+      keyOnly.set(id, node)
+      continue
+    }
+    // An edge to a task this run schedules anyway stays: dropped, the two
+    // ran unordered, and `a#build` read `b`'s output mid-rewrite or from
+    // the run before (item 980). Only an edge to a task that leaves the
+    // schedule is taken out.
+    const kept = keptBy(node)
+    const stays = (d: string): boolean => kept(d) || scheduled.has(d)
+    const lost = node.deps.filter((d) => !stays(d))
+    if (lost.length === 0) continue
+    dropped.set(id, lost)
+    node.deps = node.deps.filter(stays)
+  }
+  for (const id of keyOnly.keys()) nodes.delete(id)
+  return { keyOnly, dropped }
 }
 
 /**
@@ -409,7 +603,10 @@ function isLiteralGlob(g: string): boolean {
  *
  *   both literal    — equal paths
  *   literal vs glob — ask the glob whether it matches the literal (exact)
- *   both globs      — only identical strings; anything else is undecided
+ *   both globs      — identical strings, or one a whole subtree `P/**`
+ *                     and the other's literal prefix P or under it: every
+ *                     path the second matches is under P, so the first
+ *                     covers it (item 941). Anything else is undecided
  *                     here and deliberately allowed through
  *
  * The rejected alternative was comparing each glob's static prefix. It is
@@ -417,12 +614,61 @@ function isLiteralGlob(g: string): boolean {
  * `dist/vx-*` and `dist/other.txt` share the prefix `dist` while matching
  * disjoint sets, so a prefix check refuses a legitimate config. (vx's own
  * `build.bun.*` tasks escape only because they declare distinct literals.)
+ *
+ * All three cases compare SPELLINGS, so each side is run through
+ * `asTrees` first — the same rule the resolver and `cleanOutputs` read,
+ * and `cleanOutputs` is what actually does the deleting. That folds two
+ * things this check used to miss, both of them the data loss it exists to
+ * prevent:
+ *
+ *   - the SPELLING: `./dist/**` and `dist/**` are one tree to every
+ *     matcher in vx, and `Bun.Glob('dist/**')` does not match the literal
+ *     `./dist/app.js` either (item 441, probed one spelling at a time);
+ *   - the literal DIRECTORY: `outputs: ['dist']` means everything under
+ *     `dist` — `asTrees` compiles it to `dist` + `dist/**` — while this
+ *     compared it to `dist/app.js` as two unequal literals. Measured end
+ *     to end: the task declaring `dist` wiped the other's `dist/app.js`
+ *     and the run reported success (item 442).
+ *
+ * Neither is a widening. Both read the declaration the way the code that
+ * deletes reads it, which is the only reading that decides the hazard.
+ *
+ * Exported through the façade because `@vzn/vx-migrate` asks the same
+ * question at MIGRATION time — it uncaches the losers so the generated
+ * config loads — and it used to ask it with a copy of this function. The
+ * copy did not get items 441 and 442, so it reported clean on configs
+ * core then refused, including `outputs: ['dist']` against
+ * `dist/app.js`, which is the commonest turbo.json shape there is (item
+ * 445). One rule, one place: the copy is gone.
  */
-function outputsOverlap(a: string, b: string): boolean {
-  if (isLiteralGlob(a) && isLiteralGlob(b)) return a === b
-  if (isLiteralGlob(a)) return new Bun.Glob(b).match(a)
-  if (isLiteralGlob(b)) return new Bun.Glob(a).match(b)
-  return a === b
+export function outputsOverlap(rawA: string, rawB: string): boolean {
+  for (const a of asTrees([rawA])) {
+    for (const b of asTrees([rawB])) {
+      if (isLiteralPattern(a) && isLiteralPattern(b)) {
+        if (a === b) return true
+      } else if (isLiteralPattern(a)) {
+        if (taskGlob(b).match(a)) return true
+      } else if (isLiteralPattern(b)) {
+        if (taskGlob(a).match(b)) return true
+      } else if (a === b || covers(a, b) || covers(b, a)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Does the whole-subtree glob `tree` (`P/**`) match every path `glob` can?
+ * It does when `glob`'s literal prefix is P or a directory under it. Left
+ * undecided, `dist/**` beside `dist/extra/**` was no overlap: each task
+ * cleaned and restored the other's files, and a hit of the wide one put
+ * back its own stale copy of the narrow one's output under a green run
+ * (item 941).
+ */
+function covers(tree: string, glob: string): boolean {
+  const dir = wholeSubtreePrefixes([tree])?.[0]
+  if (dir === undefined) return false
+  const prefix = staticPrefix(glob)
+  return prefix === dir || prefix.startsWith(`${dir}/`)
 }
 
 /**
@@ -445,6 +691,24 @@ function outputsOverlap(a: string, b: string): boolean {
  * this only refuses a graph that was already destroying files.
  */
 function detectOutputCollisions(nodes: Map<string, TaskNode>): void {
+  // Does `from` reach `to` through deps? Asked only for a colliding pair,
+  // so the walk is rare; memoised per source across the detector's calls.
+  const reachMemo = new Map<string, Set<string>>()
+  const reaches = (from: string, to: string): boolean => {
+    let seen = reachMemo.get(from)
+    if (seen === undefined) {
+      seen = new Set<string>()
+      const stack = [...(nodes.get(from)?.deps ?? [])]
+      while (stack.length > 0) {
+        const id = stack.pop()!
+        if (seen.has(id)) continue
+        seen.add(id)
+        for (const d of nodes.get(id)?.deps ?? []) if (!seen.has(d)) stack.push(d)
+      }
+      reachMemo.set(from, seen)
+    }
+    return seen.has(to)
+  }
   // INDEX FIRST, then compare — never all-pairs over the graph. A naive
   // pairwise loop that filters by project INSIDE the loop is quadratic in the
   // whole graph: measured 1.6 SECONDS at this project's stated target of 1000
@@ -454,11 +718,13 @@ function detectOutputCollisions(nodes: Map<string, TaskNode>): void {
   //
   // Both namespaces have a much smaller natural domain:
   //   files          — project-relative, so only same-project tasks can
-  //                    collide. Bucketing makes this O(sum of k^2) over
-  //                    per-project task counts, and k is single digits.
+  //                    collide.
   //   workspaceFiles — root-anchored and boundary-free, so any two tasks can
-  //                    collide — but only tasks that DECLARE it participate,
-  //                    and that set is nearly always empty.
+  //                    collide — but only tasks that DECLARE it participate.
+  // Within a domain all pairs was still quadratic in ONE project's tasks
+  // (4,000 with outputs spent 10.7 s here, item 741), so each domain is
+  // indexed again by path (`overlapCandidates`) and only the pairs that can
+  // overlap are compared, in the order the all-pairs loop met them.
   const byProject = new Map<string, TaskNode[]>()
   const wsDeclarers: TaskNode[] = []
   for (const n of nodes.values()) {
@@ -471,28 +737,110 @@ function detectOutputCollisions(nodes: Map<string, TaskNode>): void {
     if ((outs?.workspaceFiles?.length ?? 0) > 0) wsDeclarers.push(n)
   }
 
+  const filesOf = (n: TaskNode): readonly string[] | undefined => n.config.cache?.outputs.files
+  const wsFilesOf = (n: TaskNode): readonly string[] | undefined =>
+    n.config.cache?.outputs.workspaceFiles
   for (const bucket of byProject.values()) {
-    for (let i = 0; i < bucket.length; i++) {
-      for (let j = i + 1; j < bucket.length; j++) {
-        const a = bucket[i]!
-        const b = bucket[j]!
-        collide(a, b, a.config.cache?.outputs.files, b.config.cache?.outputs.files, 'files')
+    // Most projects hold one task with outputs, and a call per project
+    // cost the cold build a measured 0.4 ms at 1,000 projects.
+    if (bucket.length < 2) continue
+    for (const [i, j] of overlapCandidates(bucket, filesOf)) {
+      const a = bucket[i]!
+      const b = bucket[j]!
+      collide(a, b, filesOf(a), filesOf(b), 'files', reaches)
+    }
+  }
+  if (wsDeclarers.length < 2) return
+  for (const [i, j] of overlapCandidates(wsDeclarers, wsFilesOf)) {
+    const a = wsDeclarers[i]!
+    const b = wsDeclarers[j]!
+    collide(a, b, wsFilesOf(a), wsFilesOf(b), 'workspaceFiles', reaches)
+  }
+}
+
+/**
+ * Where a glob's literal head ends: every character `Bun.Glob` may read as
+ * something other than itself. `*?{}` are the task-glob wildcards; `\`
+ * escapes (`x\y/*` matches `xy/a`), and a leading `!` negates (`!a/**`
+ * matches `b`). Ending early only widens the candidate set. A fuzz of
+ * nearly four million glob/literal pairs (over 400,000 of them matching)
+ * found no match outside the head this cuts, and thousands once `\` and
+ * `!` were left out (item 746).
+ */
+const GLOB_HEAD_END = /[*?{}\\!]/
+
+/**
+ * The pairs `[i, j]`, `i < j`, of `tasks` whose declared outputs CAN
+ * overlap, ascending by `i` then `j`: a superset of the pairs
+ * `outputsOverlap` accepts, so `collide` over them decides exactly what it
+ * decided over all pairs, and in the same order (the first refusal named,
+ * and the addition marks pushed, are all-pairs' own).
+ *
+ * `outputsOverlap` compares the `asTrees` forms three ways. Two equal
+ * globs are one lookup. Two equal literals are too, since each literal
+ * carries its `/**` twin. And a glob matches a literal only when the
+ * literal lies under the directory the glob's literal head names
+ * (`dist/sub/**` → `dist/sub`; `*.js` → the root, so a wildcard in the
+ * first segment meets every literal): a literal meets the globs filed at
+ * each of its ancestors. The fuzz above found no glob matching the
+ * directory its own head names. A whole subtree meets the globs whose
+ * literal prefix lies at or under it, found the same way from the glob's
+ * side (item 941).
+ */
+function overlapCandidates(
+  tasks: readonly TaskNode[],
+  globsOf: (n: TaskNode) => readonly string[] | undefined,
+): Array<[number, number]> {
+  const globs = new Map<string, number[]>()
+  const globsUnder = new Map<string, number[]>()
+  const literals: Array<[task: number, path: string]> = []
+  // `covers` (item 941): a whole subtree `P/**` meets every glob whose
+  // literal prefix is P or under it, so each glob looks up the subtrees
+  // filed at its prefix and at each of that prefix's ancestors.
+  const subtrees = new Map<string, number[]>()
+  const prefixes: Array<[task: number, prefix: string]> = []
+  const file = (index: Map<string, number[]>, key: string, i: number): void => {
+    const list = index.get(key)
+    if (list === undefined) index.set(key, [i])
+    else list.push(i)
+  }
+  for (let i = 0; i < tasks.length; i++) {
+    for (const tree of asTrees(globsOf(tasks[i]!) ?? [])) {
+      if (isLiteralPattern(tree)) {
+        literals.push([i, tree])
+        continue
       }
+      file(globs, tree, i)
+      const dir = wholeSubtreePrefixes([tree])?.[0]
+      if (dir !== undefined) file(subtrees, dir, i)
+      prefixes.push([i, staticPrefix(tree)])
+      const head = tree.slice(0, tree.search(GLOB_HEAD_END))
+      file(globsUnder, head.slice(0, Math.max(0, head.lastIndexOf('/'))), i)
     }
   }
-  for (let i = 0; i < wsDeclarers.length; i++) {
-    for (let j = i + 1; j < wsDeclarers.length; j++) {
-      const a = wsDeclarers[i]!
-      const b = wsDeclarers[j]!
-      collide(
-        a,
-        b,
-        a.config.cache?.outputs.workspaceFiles,
-        b.config.cache?.outputs.workspaceFiles,
-        'workspaceFiles',
-      )
+  const n = tasks.length
+  const pairs = new Set<number>()
+  const pair = (x: number, y: number): void => {
+    if (x !== y) pairs.add(x < y ? x * n + y : y * n + x)
+  }
+  for (const list of globs.values()) {
+    for (let x = 0; x < list.length; x++) {
+      for (let y = x + 1; y < list.length; y++) pair(list[x]!, list[y]!)
+    }
+  }
+  for (const [i, prefix] of prefixes) {
+    for (const j of subtrees.get(prefix) ?? []) pair(i, j)
+    for (let sep = prefix.indexOf('/'); sep !== -1; sep = prefix.indexOf('/', sep + 1)) {
+      for (const j of subtrees.get(prefix.slice(0, sep)) ?? []) pair(i, j)
     }
   }
+  for (const [i, path] of literals) {
+    for (const j of globsUnder.get('') ?? []) pair(i, j)
+    for (let sep = path.indexOf('/'); sep !== -1; sep = path.indexOf('/', sep + 1)) {
+      for (const j of globsUnder.get(path.slice(0, sep)) ?? []) pair(i, j)
+    }
+  }
+  return [...pairs].sort((x, y) => x - y).map((p) => [Math.floor(p / n), p % n])
 }
 
 /**
@@ -521,11 +869,27 @@ function collide(
   aGlobs: readonly string[] | undefined,
   bGlobs: readonly string[] | undefined,
   field: 'files' | 'workspaceFiles',
+  reaches: (from: string, to: string) => boolean,
 ): void {
   if (neverWritesLocally(a) || neverWritesLocally(b)) return
   for (const ga of aGlobs ?? []) {
     for (const gb of bGlobs ?? []) {
       if (!outputsOverlap(ga, gb)) continue
+      // An overlap WITH an edge is the addition shape (item 588): the
+      // dependant runs after its upstream and adds to that tree, so the
+      // order is fixed and the dependant's own set can be told apart from
+      // what it found. Marked on both, and the pair is allowed. Without an
+      // edge the two run in either order, and the refusal below stands.
+      const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
+      if (up !== undefined && down !== undefined) {
+        const downGlobs =
+          field === 'files'
+            ? down.config.cache?.outputs.files
+            : down.config.cache?.outputs.workspaceFiles
+        ;(down.addsToOutputsOf ??= []).push(up.id)
+        ;(up.outputsAddedToBy ??= []).push(...(downGlobs ?? []))
+        return
+      }
       throw new UserError(
         `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
           (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
@@ -537,7 +901,7 @@ function collide(
   }
 }
 
-export function detectCycle(nodes: Map<string, TaskNode>): void {
+function detectCycle(nodes: Map<string, TaskNode>): void {
   // Iterative DFS over dense-indexed colors. Recursion + `Map<string,
   // number>` worked, but deep workspaces (long chains of `dependsOn`)
   // can blow V8's frame budget, and per-node Map lookups dominate the