@vzn/vx-migrate 0.0.0 → 0.0.484

package/src/script-command.ts

@@ -0,0 +1,69 @@
+// The command a package.json script becomes. Inlining the body is the
+// rule — one process less per task than `<pm> run <name>` — with two npm
+// conventions mapped rather than lost, the way core's `vx init` maps
+// them (workspace/migrate-scripts.ts):
+//
+// - `pre<name>` / `post<name>` hooks, which npm and pnpm run around
+//   `<name>` without being asked, are folded into the command in that
+//   order (novu's `prebuild` copies the CSS its `build` inlines,
+//   2026-09-11; Nx and Turbo run `pnpm run build`, so they get the hooks
+//   for free). Lifecycle hooks of the package manager's own verbs
+//   (`preinstall`, `prepublishOnly`, …) never ride inside a task.
+// - yarn ≥ 2 runs scripts in its own shell, where `run` is a builtin
+//   (`run -T rollup -c` is "the root's rollup", `run build:code` the
+//   sibling script); inlined into sh that body is `run: command not
+//   found` in every strapi package (2026-09-11), so such a script runs
+//   through `yarn run <name>`, exactly as Nx and Turbo run it — and yarn
+//   ≥ 2 runs no pre/post hooks, so none are folded there either.
+// - A Yarn Plug'n'Play workspace has no node_modules: a dependency's
+//   `require` resolves only through `.pnp.cjs` and its bins only through
+//   the shims `yarn run` writes, so inlined, `node -e "require('left-pad')"`
+//   was MODULE_NOT_FOUND (2026-09-28). Every script runs as `yarn run <name>`.
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { foldScriptHooks } from '@vzn/vx'
+
+const YARN_RUN_BUILTIN = /(^|&&|\|\||;|\(|\|)\s*run\s/
+const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepublishOnly|install)$/
+
+function usable(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0
+}
+
+export function scriptCommand(
+  name: string,
+  body: string,
+  scripts: Readonly<Record<string, unknown>> = {},
+  pnp = false,
+): string {
+  if (pnp) return `yarn run ${name}`
+  const hook = (h: string): string | undefined =>
+    !LIFECYCLE.test(h) && usable(scripts[h]) ? scripts[h] : undefined
+  const parts = [hook(`pre${name}`), body, hook(`post${name}`)]
+  if (parts.some((p) => p !== undefined && YARN_RUN_BUILTIN.test(p))) return `yarn run ${name}`
+  return foldScriptHooks(parts[0], body, parts[2])
+}
+
+/**
+ * Yarn ≥ 2 links Plug'n'Play unless `.yarnrc.yml` names another `nodeLinker`.
+ * Read once per mapping; synchronous so every mapper, the synchronous ones
+ * included, can ask it.
+ */
+export function yarnPnp(root: string): boolean {
+  let rc: string
+  try {
+    rc = readFileSync(path.join(root, '.yarnrc.yml'), 'utf8')
+  } catch {
+    return false
+  }
+  const linker = /^nodeLinker:[ \t]*["']?([\w-]+)/m.exec(rc)?.[1]
+  return linker === undefined || linker === 'pnp'
+}
+
+/** `.yarnrc.yml` as a mapping cache reads it: `yarnPnp` decides every script command from it. */
+export async function yarnrcText(root: string): Promise<string> {
+  return Bun.file(path.join(root, '.yarnrc.yml'))
+    .text()
+    .catch(() => '\0absent')
+}

package/src/shared-outputs.ts

@@ -0,0 +1,373 @@
+// Two targets of one project on one output path. vx cleans a task's
+// declared outputs before it runs and before a cache-hit restore, so the
+// loader refuses two cached tasks whose outputs provably overlap — UNLESS
+// a same-project edge orders them (core item 588): then the dependant is
+// ADDITIVE, keeps its cache, and owns only what its run added. strapi
+// (2026-09-11) declares `build`, `build:code` and `build:types` all on
+// `dist/**`, and the refusal came at load time, after the migration had
+// reported clean. The mapping resolves it: the task with a `^` edge keeps
+// its cache (it is the one a dependant waits for), or the first declared
+// when none has one; every other task on that path stays cached when an
+// edge orders it against every kept task it overlaps, and otherwise runs
+// uncached, with a todo that names the keeper and the fix (its own output
+// path, or the edge).
+//
+// The overlap question is core's own `outputsOverlap`, asked through the
+// façade. It used to be a COPY of it here, and the copy stopped being the
+// same test the moment core's grew: `./dist/**` against `dist/**` (item
+// 441) and the literal `dist` against `dist/app.js` (item 442) are
+// refused by the loader and were missed here — so the migration reported
+// clean on a config core would not load, which is the exact failure this
+// file exists to prevent (item 445).
+
+import { isLiteralPattern, outputsOverlap, type GeneratedTask } from '@vzn/vx'
+import { relPosix } from './paths.js'
+import type { TrackedKinds } from './tracked-outputs.js'
+
+// Core refuses an output glob that covers the project's own package.json
+// or vx.config (config-schema's `ownFilesCovered`): vx cleans outputs before
+// a run and restores them on a hit, so the manifest would go. Turbo caches
+// it: trpc's client build lists `package.json` (it rewrites `exports`), and
+// the one task made core refuse the whole run (2026-09-28). The façade does
+// not export the check; tests/own-file-outputs.test.ts holds this copy to
+// the loader in both directions.
+const OWN_FILES = ['package.json', 'vx.config.ts', 'vx.config.mts', 'vx.config.js', 'vx.config.mjs']
+
+/**
+ * The first positive output glob that covers a project's own file, and that
+ * file. `config` is the config file the mapped task will live beside, as
+ * core checks it (null: none); absent, every spelling a user may add later.
+ * sanity's builds output `*.js` (top-level shims) beside no vx.config.js.
+ */
+export function ownFileOutput(
+  files: readonly string[],
+  config?: string | null,
+): { glob: string; file: string } | undefined {
+  const own =
+    config === undefined ? OWN_FILES : config === null ? ['package.json'] : ['package.json', config]
+  for (const glob of files) {
+    if (glob.startsWith('!')) continue
+    const g = new Bun.Glob(glob.replace(/^(\.\/)+/, ''))
+    const file = own.find((f) => g.match(f))
+    if (file !== undefined) return { glob, file }
+  }
+  return undefined
+}
+
+/**
+ * The `!` entries that take the project's own files back from `files`: each
+ * own file a positive glob covers and no `!` already takes back. Taken back,
+ * it is never cleaned, saved or restored (core's A-44), and core loads it.
+ */
+export function ownFileTakeBacks(files: readonly string[], config?: string | null): string[] {
+  const own =
+    config === undefined ? OWN_FILES : config === null ? ['package.json'] : ['package.json', config]
+  const glob = (g: string) => new Bun.Glob(g.replace(/^(\.\/)+/, ''))
+  const positive = files.filter((g) => !g.startsWith('!')).map(glob)
+  const taken = files.filter((g) => g.startsWith('!')).map((g) => glob(g.slice(1)))
+  return own
+    .filter((f) => positive.some((g) => g.match(f)) && !taken.some((g) => g.match(f)))
+    .map((f) => `!${f}`)
+}
+
+export function ownFileTodo(own: { glob: string; file: string }): string {
+  return (
+    `output ${JSON.stringify(own.glob)} covers the project's own ${own.file}, which vx cleans ` +
+    'before every run — task runs uncached; declare the outputs without it in a vx.config to cache it'
+  )
+}
+
+// Turbo and Nx never clean an output; vx cleans it before a run and a
+// restore, so `**/*.d.ts` deleted a hand-written `src/env.d.ts` and an
+// uncommitted edit to it was lost for good (item 1031). A wildcard first
+// segment can reach the sources, and a `!` beside it (medusa: `*/**` minus
+// `!src/**`) takes back only what it names. typescript-eslint's Nx tests
+// output `{projectRoot}/**/*.shot`, 3,656 committed snapshots in one
+// package, and nx() lacked the rule (2026-09-29).
+
+/**
+ * The first positive output glob whose first segment is a wildcard. Two
+ * shapes reach no source when `tracked` is known and says the project has
+ * none of their kind, and are let through: one segment ending in a literal
+ * extension no tracked file carries (n8n's `*.xml` junit reports, 143 test
+ * tasks), and `**` followed by `/<dir>/**` where no tracked file sits
+ * under a directory of that name (vercel/ai's builds, `dist` at any depth,
+ * 69 of them). A third: a first segment with no `**` that names no tracked
+ * top-level entry, and so reaches nothing tracked (tldraw's `dist-*`
+ * directories, 35 builds). `*.ts` beside tracked TypeScript, that form over
+ * `src`, or a bare `*` directory beside any tracked file is not.
+ */
+export function wildcardOutput(
+  files: readonly string[],
+  tracked?: TrackedKinds,
+  /** Let a literal-tail glob through once its tracked matches are taken back (`literalTailMatches`). */
+  literalTail = false,
+): string | undefined {
+  return files.find(
+    (o) =>
+      !o.startsWith('!') &&
+      !isLiteralPattern(o.split('/')[0] ?? '') &&
+      !untrackedKind(o, tracked) &&
+      !(
+        literalTail &&
+        (literalTailMatches(o, tracked)?.every((m) => files.includes(`!${m}`)) ?? false)
+      ),
+  )
+}
+
+/**
+ * The tracked files a wildcard-first glob with a literal rest can reach
+ * (clerk's builds output `*\/package.json`, the subpath stubs it commits):
+ * it reaches no other file, so with each of these taken back by a `!` it
+ * reaches no source. Null for any other shape, or with `tracked` unknown.
+ */
+export function literalTailMatches(glob: string, tracked?: TrackedKinds): string[] | null {
+  if (tracked === undefined || glob.startsWith('!')) return null
+  const segs = glob.replace(/^(\.\/)+/, '').split('/')
+  const [first, ...rest] = segs
+  if (first === undefined || rest.length === 0 || first.includes('**')) return null
+  if (/[^A-Za-z0-9*?._@+-]/.test(first) || !rest.every((s) => isLiteralPattern(s) && s !== ''))
+    return null
+  const tail = `/${rest.join('/')}`
+  const head = new Bun.Glob(first)
+  return tracked.files.filter(
+    (f) => f.endsWith(tail) && f.split('/').length === segs.length && head.match(f.split('/')[0]!),
+  )
+}
+
+function untrackedKind(glob: string, tracked: TrackedKinds | undefined): boolean {
+  if (tracked === undefined) return false
+  const g = glob.replace(/^(\.\/)+/, '')
+  const ext = /^[^/]*\.([A-Za-z0-9]+)$/.exec(g)?.[1]
+  if (ext !== undefined) return !tracked.exts.has(ext.toLowerCase())
+  const dir = /^\*\*\/([^*?[\]{}()!/]+)\/\*\*$/.exec(g)?.[1]
+  if (dir !== undefined) return !tracked.dirs.has(dir)
+  // Brackets, parens and `!` are left out: vx and Bun.Glob read them apart.
+  const first = /^([^/[\]()!\\]+)\//.exec(g)?.[1]
+  if (first === undefined || first.includes('**')) return false
+  const matcher = new Bun.Glob(first)
+  return ![...tracked.tops].some((top) => matcher.match(top))
+}
+
+export function wildcardTodo(glob: string): string {
+  return (
+    `output ${JSON.stringify(glob)}: a wildcard first segment reaches the sources, which ` +
+    'vx cleans before every run — task runs uncached; declare the exact outputs in a ' +
+    'vx.config to cache it'
+  )
+}
+
+interface Cached {
+  index: number
+  name: string
+  files: string[]
+  hasUpstreamEdge: boolean
+  /** Same-project `dependsOn` names (no `^`), for the ordering test. */
+  localDeps: string[]
+}
+
+function cachedOutputs(t: GeneratedTask, index: number): Cached | null {
+  const task = t.task
+  if (task === null) return null
+  const cache = task['cache'] as { outputs?: { files?: unknown } } | undefined
+  const files = cache?.outputs?.files
+  if (!Array.isArray(files)) return null
+  // Where a task's outputs might land is its positive globs, as core reads
+  // them: a `!` compiled as a glob is true of every other path.
+  const strings = files.filter((f): f is string => typeof f === 'string' && !f.startsWith('!'))
+  if (strings.length === 0) return null
+  const deps = task['dependsOn']
+  const hasUpstreamEdge =
+    Array.isArray(deps) && deps.some((d) => typeof d === 'string' && d.startsWith('^'))
+  const localDeps = Array.isArray(deps)
+    ? deps.filter((d): d is string => typeof d === 'string' && !d.startsWith('^'))
+    : []
+  return { index, name: t.name, files: strings, hasUpstreamEdge, localDeps }
+}
+
+/**
+ * Uncache every task whose declared outputs overlap a keeper's, in place,
+ * and return the tasks. Deterministic: keepers are chosen in declaration
+ * order, so the same graph maps the same way every run.
+ */
+export function resolveSharedOutputs(tasks: GeneratedTask[]): GeneratedTask[] {
+  const cached: Cached[] = []
+  tasks.forEach((t, i) => {
+    const c = cachedOutputs(t, i)
+    if (c !== null) cached.push(c)
+  })
+  // Does `from` reach `to` through same-project edges? The generated
+  // tasks of one project are the whole graph here.
+  // Every task, cached or not: a hop through an uncached group task is an
+  // edge too.
+  const depsByName = new Map<string, string[]>()
+  for (const t of tasks) {
+    const deps = t.task?.['dependsOn']
+    depsByName.set(
+      t.name,
+      Array.isArray(deps)
+        ? deps.filter((d): d is string => typeof d === 'string' && !d.startsWith('^'))
+        : [],
+    )
+  }
+  const reaches = (from: Cached, to: Cached): boolean => {
+    const seen = new Set<string>()
+    const stack = [...from.localDeps]
+    while (stack.length > 0) {
+      const n = stack.pop()!
+      if (n === to.name) return true
+      if (seen.has(n)) continue
+      seen.add(n)
+      for (const d of depsByName.get(n) ?? []) stack.push(d)
+    }
+    return false
+  }
+  const ordered = (x: Cached, y: Cached): boolean => reaches(x, y) || reaches(y, x)
+  const dropped = new Set<number>()
+  for (const a of cached) {
+    if (dropped.has(a.index)) continue
+    const group = cached.filter(
+      (b) =>
+        b !== a &&
+        !dropped.has(b.index) &&
+        a.files.some((ga) => b.files.some((gb) => outputsOverlap(ga, gb))),
+    )
+    if (group.length === 0) continue
+    const all = [a, ...group]
+    const keeper = all.find((c) => c.hasUpstreamEdge) ?? all[0]!
+    const kept: Cached[] = [keeper]
+    for (const c of all) {
+      if (c === keeper) continue
+      // Additive under core's rule when an edge orders it against every
+      // kept task whose outputs it overlaps: it stays cached, no todo.
+      const unordered = kept.find(
+        (k) => c.files.some((gb) => k.files.some((ga) => outputsOverlap(ga, gb))) && !ordered(c, k),
+      )
+      if (unordered === undefined) {
+        kept.push(c)
+        continue
+      }
+      dropped.add(c.index)
+      const t = tasks[c.index]!
+      const shared = c.files.find((gb) => unordered.files.some((ga) => outputsOverlap(ga, gb)))!
+      delete t.task!['cache']
+      t.todos.push(
+        `declares the output ${JSON.stringify(shared)} that ${JSON.stringify(unordered.name)} also ` +
+          "declares — vx cleans a task's outputs before it runs and before a restore, so two " +
+          "cached tasks on one path would delete each other's work; this one runs uncached. " +
+          `Give it its own output path to cache it, or a dependsOn edge on ${JSON.stringify(unordered.name)} ` +
+          'so vx orders them and caches what this one adds.',
+      )
+    }
+  }
+  return tasks
+}
+
+/**
+ * The same across projects, for workspace outputs: cal.com's shared
+ * `post-install` writes `../../node_modules/@prisma/client/**` from every
+ * package that has the script, one workspace path, and core refused the
+ * whole run over the first pair (two projects' outputs on one path with
+ * no edge between them). A project's own outputs take part at their
+ * workspace path: typescript-eslint's root project caches `dist` and every
+ * package's typecheck `dist/packages/<name>`, and core refused the run
+ * over the nesting. Keepers are the first in project and task order;
+ * every later task on a kept path runs uncached, with a todo. Edges are
+ * not read: across projects they are the package graph's, which the
+ * mapping does not hold, so an ordered pair loses its cache too.
+ */
+export function resolveSharedWorkspaceOutputs(
+  root: string,
+  projects: readonly {
+    readonly name: string
+    readonly dir: string
+    readonly tasks: GeneratedTask[]
+  }[],
+): void {
+  const positive = (v: unknown): string[] =>
+    Array.isArray(v)
+      ? v.filter((f): f is string => typeof f === 'string' && !f.startsWith('!'))
+      : []
+  const kept: { id: string; project: string; ws: string[]; own: string[] }[] = []
+  // Two globs can match one path only when one's literal prefix is a
+  // directory of the other's (`packages/*/dist/**` and `packages/a/dist/**`),
+  // so a kept glob is a candidate only along its prefix's chain. Every pair
+  // was compared: 1,000 packages' builds and tests took 9 s to map.
+  const at = new Map<string, number[]>()
+  const under = new Map<string, number[]>()
+  const chain = (g: string): string[] => {
+    const segs: string[] = []
+    for (const seg of g.split('/')) {
+      if (/[*?{}[\]()!]/.test(seg)) break
+      segs.push(seg)
+    }
+    return segs.map((_, i) => segs.slice(0, i + 1).join('/'))
+  }
+  const index = (i: number, globs: readonly string[]): void => {
+    for (const g of globs) {
+      const c = chain(g)
+      const push = (m: Map<string, number[]>, k: string) => {
+        const list = m.get(k)
+        if (list === undefined) m.set(k, [i])
+        else if (list.at(-1) !== i) list.push(i)
+      }
+      push(at, c.at(-1) ?? '')
+      for (const k of ['', ...c]) push(under, k)
+    }
+  }
+  const candidates = (globs: readonly string[]): number[] => {
+    const found = new Set<number>()
+    for (const g of globs) {
+      const c = chain(g)
+      for (const k of ['', ...c]) for (const i of at.get(k) ?? []) found.add(i)
+      for (const i of under.get(c.at(-1) ?? '') ?? []) found.add(i)
+    }
+    return [...found].sort((a, b) => a - b)
+  }
+  for (const p of projects) {
+    const rel = relPosix(root, p.dir)
+    for (const t of p.tasks) {
+      const cache = t.task?.['cache'] as
+        | { outputs?: { files?: unknown; workspaceFiles?: unknown } }
+        | undefined
+      const ws = positive(cache?.outputs?.workspaceFiles)
+      const own = positive(cache?.outputs?.files).map((g) =>
+        rel === '' ? g.replace(/^(\.\/)+/, '') : `${rel}/${g.replace(/^(\.\/)+/, '')}`,
+      )
+      if (ws.length === 0 && own.length === 0) continue
+      // Two own outputs of one project are resolveSharedOutputs', which
+      // reads the edges that order them.
+      const overlap = (a: string[], b: string[]): string | undefined =>
+        a.find((g) => b.some((h) => outputsOverlap(h, g)))
+      let clash: (typeof kept)[number] | undefined
+      let shared: string | undefined
+      for (const i of candidates([...ws, ...own])) {
+        const k = kept[i]!
+        shared =
+          overlap(ws, [...k.ws, ...k.own]) ??
+          overlap(own, k.project === p.name ? k.ws : [...k.ws, ...k.own])
+        if (shared !== undefined) {
+          clash = k
+          break
+        }
+      }
+      if (clash === undefined) {
+        index(kept.length, [...ws, ...own])
+        kept.push({ id: `${p.name}#${t.name}`, project: p.name, ws, own })
+        continue
+      }
+      delete t.task!['cache']
+      t.todos.push(
+        `declares the workspace output ${JSON.stringify(shared)} that ${clash.id} also declares — ` +
+          "vx cleans a task's outputs before it runs and before a restore, so two cached tasks " +
+          "on one path would delete each other's work; this one runs uncached. Give it its own " +
+          'output path to cache it.',
+      )
+    }
+  }
+}
+
+/** A `!` output with no positive beside it takes back nothing, and core refuses a list of them alone. */
+export function takingBack(globs: readonly string[]): string[] {
+  return globs.some((g) => !g.startsWith('!')) ? [...globs] : []
+}

package/src/tracked-outputs.ts

@@ -0,0 +1,248 @@
+// vx cleans a task's declared outputs before it runs (core's rule, kept on
+// purpose: a stale file in an output is a stale artifact). Turbo and Nx
+// never clean, so an output a repo declares over committed files is safe
+// there and destructive here: typescript-eslint's website build caches
+// `data`, which holds the committed `sponsors.json`, and the first vx run
+// deleted it (2026-09-29). Each committed file under a mapped output is taken
+// back with a `!` entry (core's A-44): not cleaned, not saved, not restored,
+// still an input. The task keeps its cache.
+
+import { lstat, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { outputsOverlap } from '@vzn/vx'
+
+/** The files git tracks under `root`, root-relative; null outside a repo or without git. */
+export async function trackedFiles(root: string): Promise<string[] | null> {
+  try {
+    const p = Bun.spawn(['git', 'ls-files', '-z'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    const out = await new Response(p.stdout).text()
+    if ((await p.exited) !== 0) return null
+    return out.split('\0').filter((f) => f !== '')
+  } catch {
+    return null
+  }
+}
+
+const sortedMemo = new WeakMap<readonly string[], readonly string[]>()
+
+/**
+ * The files under `rel/` (all of them for the root). In a sorted list they
+ * are one run, found by a binary search: every project scanned the whole
+ * list, twice, and a cold mapping of 1,000 packages spent 177 ms there.
+ */
+function filesUnder(files: readonly string[], rel: string): readonly string[] {
+  if (rel === '' || rel === '.') return files
+  let sorted = sortedMemo.get(files)
+  if (sorted === undefined) sortedMemo.set(files, (sorted = [...files].sort()))
+  const prefix = `${rel}/`
+  let lo = 0
+  let hi = sorted.length
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1
+    if (sorted[mid]! < prefix) lo = mid + 1
+    else hi = mid
+  }
+  const out: string[] = []
+  for (let i = lo; i < sorted.length && sorted[i]!.startsWith(prefix); i++) out.push(sorted[i]!)
+  return out
+}
+
+/**
+ * Which of `rels` (root-relative) git ignores: a path no glob over git's
+ * files can key. Untracked only (a tracked file is never ignored); empty
+ * outside a repo or without git.
+ */
+export async function gitIgnored(root: string, rels: readonly string[]): Promise<Set<string>> {
+  if (rels.length === 0) return new Set()
+  try {
+    const p = Bun.spawn(['git', 'check-ignore', '--stdin', '-z'], {
+      cwd: root,
+      stdin: new TextEncoder().encode(rels.map((r) => `${r}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const out = await new Response(p.stdout).text()
+    // 1: none ignored; anything else past 0 is no answer.
+    if ((await p.exited) !== 0) return new Set()
+    return new Set(out.split('\0').filter((f) => f !== ''))
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * What a project's tracked files are: their extensions (lower case, no
+ * dot), directory names at any depth, and top-level entry names.
+ */
+export interface TrackedKinds {
+  readonly exts: ReadonlySet<string>
+  readonly dirs: ReadonlySet<string>
+  readonly tops: ReadonlySet<string>
+  /** The files themselves, project-relative. */
+  readonly files: readonly string[]
+}
+
+/**
+ * Per project directory (root-relative, `.` or empty for the root), the
+ * kinds of the files git tracks under it at any depth: what a
+ * wildcard-first output glob may not claim (`wildcardOutput`).
+ */
+export function trackedKinds(tracked: readonly string[]): (rel: string) => TrackedKinds {
+  const memo = new Map<string, TrackedKinds>()
+  return (rel) => {
+    let kinds = memo.get(rel)
+    if (kinds === undefined) {
+      const exts = new Set<string>()
+      const dirs = new Set<string>()
+      const tops = new Set<string>()
+      const files: string[] = []
+      const all = rel === '' || rel === '.'
+      for (const f of filesUnder(tracked, rel)) {
+        const own = all ? f : f.slice(rel.length + 1)
+        files.push(own)
+        const ext = path.posix.extname(own)
+        if (ext !== '') exts.add(ext.slice(1).toLowerCase())
+        const segs = own.split('/')
+        tops.add(segs[0]!)
+        for (let i = 0; i < segs.length - 1; i++) dirs.add(segs[i]!)
+      }
+      memo.set(rel, (kinds = { exts, dirs, tops, files }))
+    }
+    return kinds
+  }
+}
+
+/**
+ * What moves when the tracked set can: the HEAD reflog's size (a commit, a
+ * checkout, a pull appends to it), HEAD itself, and the index's size and
+ * mtime (`git add`, `git rm`). Stats and a small read, so a kept mapping
+ * stays a hit between them; a run does not write the index. Without the
+ * index, a file `git add`ed under an output and not yet committed was not
+ * taken back by the kept mapping, and the run's clean deleted it. Under
+ * reftable storage HEAD reads `ref: refs/heads/.invalid` and no reflog file
+ * exists, so the ref stack's table list stands for both: every ref update
+ * names a new table in it.
+ */
+export async function headStamp(root: string): Promise<string> {
+  for (let dir = root; ;) {
+    const dotGit = path.join(dir, '.git')
+    const st = await lstat(dotGit).catch(() => null)
+    if (st !== null) {
+      let gitDir = dotGit
+      if (st.isFile()) {
+        const m = /^gitdir: (.*)$/m.exec(await readFile(dotGit, 'utf8').catch(() => ''))
+        if (m !== null) gitDir = path.resolve(dir, m[1]!.trim())
+      }
+      const head = await readFile(path.join(gitDir, 'HEAD'), 'utf8').catch(() => '')
+      const log = await lstat(path.join(gitDir, 'logs', 'HEAD')).catch(() => null)
+      const index = await lstat(path.join(gitDir, 'index')).catch(() => null)
+      // A worktree's own stack holds its HEAD; the common one, its branches.
+      const common = await readFile(path.join(gitDir, 'commondir'), 'utf8').catch(() => null)
+      const tables = await Promise.all(
+        [gitDir, ...(common === null ? [] : [path.resolve(gitDir, common.trim())])].map((d) =>
+          readFile(path.join(d, 'reftable', 'tables.list'), 'utf8').catch(() => ''),
+        ),
+      )
+      return `${head.trim()}\0${log?.size ?? ''}\0${index?.size ?? ''}\0${index?.mtimeMs ?? ''}\0${tables.join('\0')}`
+    }
+    const up = path.dirname(dir)
+    if (up === dir) return 'no-git'
+    dir = up
+  }
+}
+
+/** A glob's leading literal segments: every path it can match starts there. */
+function literalPrefix(glob: string): string {
+  const out: string[] = []
+  for (const seg of glob.replace(/^(\.\/)+/, '').split('/')) {
+    if (/[*?[\]{}()!]/.test(seg)) break
+    out.push(seg)
+  }
+  return out.join('/')
+}
+
+/** The tracked `files` (relative to the same base as `globs`) the positive globs cover and no `!` takes back. */
+function coveredTracked(globs: readonly string[], files: readonly string[]): string[] {
+  const positive = globs.filter((g) => !g.startsWith('!'))
+  const taken = globs.filter((g) => g.startsWith('!')).map((g) => g.slice(1))
+  const hit = new Set<string>()
+  for (const g of positive) {
+    const prefix = literalPrefix(g)
+    for (const f of files) {
+      if (prefix !== '' && f !== prefix && !f.startsWith(`${prefix}/`)) continue
+      if (!outputsOverlap(g, f)) continue
+      if (taken.some((t) => outputsOverlap(t, f))) continue
+      hit.add(f)
+    }
+  }
+  return [...hit].sort()
+}
+
+/** Past this many, a task's take-backs cost its runs more than its cache saves. */
+export const MAX_SPARED = 16
+
+interface Outputs {
+  files?: unknown
+  workspaceFiles?: unknown
+}
+
+/**
+ * Take back every committed file a mapped task's outputs cover, in place,
+ * and return one `[pkg#task, todo]` per task that had any. `tracked` is
+ * root-relative.
+ */
+export function spareTrackedOutputs(
+  root: string,
+  projects: readonly {
+    readonly name: string
+    readonly dir: string
+    readonly tasks: readonly {
+      readonly name: string
+      readonly task: Record<string, unknown> | null
+    }[]
+  }[],
+  tracked: readonly string[],
+): [string, string][] {
+  const todos: [string, string][] = []
+  for (const p of projects) {
+    const rel = path.relative(root, p.dir).split(path.sep).join('/')
+    const own = rel === '' ? tracked : filesUnder(tracked, rel).map((f) => f.slice(rel.length + 1))
+    for (const t of p.tasks) {
+      const outputs = (t.task?.['cache'] as { outputs?: Outputs } | undefined)?.outputs
+      if (outputs === undefined) continue
+      const hits: [key: 'files' | 'workspaceFiles', globs: string[], hit: string[]][] = []
+      for (const [key, base] of [
+        ['files', own],
+        ['workspaceFiles', tracked],
+      ] as const) {
+        const globs = outputs[key]
+        if (!Array.isArray(globs) || globs.length === 0) continue
+        const strings = globs.filter((g): g is string => typeof g === 'string')
+        const hit = coveredTracked(strings, base)
+        if (hit.length > 0) hits.push([key, strings, hit])
+      }
+      const spared = hits.flatMap(([, , hit]) => hit)
+      if (spared.length === 0) continue
+      const shown = spared.slice(0, 3).join(', ') + (spared.length > 3 ? ', …' : '')
+      // Each `!` is matched against every output path on each save, clean
+      // and restore: 4,200 of them cost typescript-eslint's warm run 1.2 s.
+      if (spared.length > MAX_SPARED) {
+        delete t.task!['cache']
+        todos.push([
+          `${p.name}#${t.name}`,
+          `outputs cover ${spared.length} committed files (${shown}), which vx cleans before ` +
+            'every run — task runs uncached; declare the exact outputs in a vx.config to cache it',
+        ])
+        continue
+      }
+      for (const [key, strings, hit] of hits)
+        outputs[key] = [...strings, ...hit.map((f) => `!${f}`)]
+      todos.push([
+        `${p.name}#${t.name}`,
+        `outputs cover ${spared.length} committed file(s) (${shown}) — vx cleans outputs ` +
+          'before a run, so they are taken back with `!` and kept',
+      ])
+    }
+  }
+  return todos
+}