@vzn/vx 0.0.585 → 0.0.586

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.585",
+  "version": "0.0.586",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.585",
-    "@vzn/vx-linux-arm64": "0.0.585",
-    "@vzn/vx-darwin-x64": "0.0.585",
-    "@vzn/vx-darwin-arm64": "0.0.585"
+    "@vzn/vx-linux-x64": "0.0.586",
+    "@vzn/vx-linux-arm64": "0.0.586",
+    "@vzn/vx-darwin-x64": "0.0.586",
+    "@vzn/vx-darwin-arm64": "0.0.586"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/index.ts

@@ -30,6 +30,8 @@ export {
 } from './cache.js'
 export { ABSENT_INPUT, absentOr, CACHE_VERSION } from './key-fold.js'
 export {
+  addedInput,
+  type InputListing,
   cleanOutputs,
   cleanWorkspaceOutputs,
   declaresInput,

package/src/cache/inputs.ts

@@ -24,6 +24,7 @@ import {
   anyTaskGlob,
   asTrees,
   isExecutableMissing,
+  isInstalledPath,
   isLiteralPattern,
   normalizeGlob,
   outputMatcher,
@@ -35,6 +36,7 @@ import {
   UserError,
 } from '../util/index.js'
 import { GitFilesCache, runGitLsFiles } from './git-inputs.js'
+import { FILE_HASH_RACY_MS, racyWindowMs } from './layer.js'
 
 // The git side lives in git-inputs.ts; its whole public surface is
 // re-exported here so a reader that reaches the resolver for it (the
@@ -93,6 +95,8 @@ const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
 
 export interface ResolvedInputs {
   files: string[]
+  /** What `files` was filtered from, for {@link addedInput}. */
+  listings: InputListing[]
   envValues: Array<[name: string, value: string | undefined]>
   runtimeValues: Array<[command: string, output: string]>
   workspaceRuntimeValues: Array<[command: string, output: string]>
@@ -177,7 +181,7 @@ export type ProjectFilesCache = Map<
 >
 
 export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedInputs> {
-  const projectFiles = await resolveFiles({
+  const { files: projectFiles, listing } = await resolveFiles({
     projectDir: args.projectDir,
     workspaceRoot: args.workspaceRoot,
     files: args.inputs?.files,
@@ -187,15 +191,18 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
     ...(args.projectFilesCache !== undefined ? { projectFilesCache: args.projectFilesCache } : {}),
   })
   let files = projectFiles
+  const listings = listing === undefined ? [] : [listing]
   const wsDecl = args.inputs?.workspaceFiles
   if (wsDecl !== undefined && wsDecl.length > 0) {
-    const wsFiles = await resolveWorkspaceFiles({
+    const ws = resolveWorkspaceFiles({
       workspaceRoot: args.workspaceRoot,
       workspaceFiles: wsDecl,
       ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
       ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
       ...(args.workspaceFilesCache !== undefined ? { memo: args.workspaceFilesCache } : {}),
     })
+    if (ws !== undefined) listings.push(ws.listing)
+    const wsFiles = ws === undefined ? [] : await ws.files
     // Dedupe: when the project dir IS the workspace root (or a glob
     // overlaps), the same absolute path can arrive via both lists —
     // it must contribute to the key exactly once.
@@ -228,6 +235,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
         ])
   return {
     files,
+    listings,
     envValues: resolveEnvValues(args.inputs?.env ?? [], args.envSource),
     runtimeValues,
     workspaceRuntimeValues,
@@ -245,13 +253,13 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
  * codegen); the hard boundary continues to apply to project-relative
  * `files` globs only.
  */
-async function resolveWorkspaceFiles(args: {
+function resolveWorkspaceFiles(args: {
   workspaceRoot: string
   workspaceFiles: readonly string[]
   ownWorkspaceOutputs: readonly string[]
   gitFilesCache?: GitFilesCache
   memo?: WorkspaceFilesCache
-}): Promise<string[]> {
+}): { files: Promise<string[]>; listing: InputListing } | undefined {
   const positive: string[] = []
   const negative: string[] = []
   refuseOneAlternativeBrace(args.workspaceFiles, 'workspaceFiles')
@@ -259,7 +267,7 @@ async function resolveWorkspaceFiles(args: {
     if (entry.startsWith('!')) negative.push(entry.slice(1))
     else positive.push(entry)
   }
-  if (positive.length === 0) return []
+  if (positive.length === 0) return undefined
 
   const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
   // A path the task's own outputs take back with `!` is no output, so it
@@ -285,20 +293,30 @@ async function resolveWorkspaceFiles(args: {
     args.memo === undefined
       ? undefined
       : JSON.stringify([positive, negative, args.ownWorkspaceOutputs])
+  let isPositive: ((rel: string) => boolean) | undefined
+  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel)
+  const listing: InputListing = {
+    root: args.workspaceRoot,
+    listed: gitFiles,
+    isInput: (rel) => (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) && !excluded(rel),
+    nested: () => false,
+    ...reachOf(positive),
+  }
   if (memoKey !== undefined) {
     const hit = args.memo!.get(memoKey)
-    if (hit !== undefined && hit.snapshot === gitFiles) return hit.result
+    if (hit !== undefined && hit.snapshot === gitFiles) return { files: hit.result, listing }
   }
+  isPositive ??= anyTaskGlob(asTrees(positive))
   const result = resolveWorkspaceFilesOver(
     args,
     gitFiles,
     positive,
-    anyTaskGlob(asTrees(positive)),
-    (rel) => isExcluded(rel) || ownOutput(rel),
+    isPositive,
+    excluded,
     undecodable,
   )
   if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
-  return result
+  return { files: result, listing }
 }
 
 async function resolveWorkspaceFilesOver(
@@ -1160,6 +1178,8 @@ interface FilesPlan {
   isPositive: (rel: string) => boolean
   /** The literal entries, each naming one path (see `unanswered`). */
   literals: string[]
+  /** The directories a positive entry reaches; see `InputListing`. */
+  prefixes: string[]
   /**
    * Whether a project-relative path is an input by the declaration alone:
    * a positive glob selects it, and no exclude and no own output takes it
@@ -1208,7 +1228,7 @@ function filesPlan(
           ownOutput: outputMatcher(ownOutputs),
           positiveGlobs: asTrees(positive).map(globFor),
           isPositive: anyTaskGlob(asTrees(positive)),
-          literals: positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
+          ...reachOf(positive),
           verdicts: new Map<string, boolean>(),
         }
   filesPlans.set(key, plan)
@@ -1264,9 +1284,11 @@ function workspaceMatcher(
   return m
 }
 
-async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
+async function resolveFiles(
+  args: ResolveFilesArgs,
+): Promise<{ files: string[]; listing?: InputListing }> {
   const plan = filesPlan(args.files, args.ownOutputs)
-  if (plan === null) return []
+  if (plan === null) return { files: [] }
   const { positive, negative, isExcluded, ownOutput, positiveGlobs, isPositive } = plan
 
   const nested = inNestedProject(args.projectDir, args.nestedProjectDirs)
@@ -1289,7 +1311,12 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
     // Identity, not equality: a re-enumeration hands back a new array even
     // when the file set is unchanged, and that is exactly when this task's
     // inputs must be walked again.
-    if (memo !== undefined && memo.snapshot === gitFiles) return [...memo.result]
+    if (memo !== undefined && memo.snapshot === gitFiles) {
+      return {
+        files: [...memo.result],
+        listing: listingFor(args.projectDir, gitFiles, plan, nested),
+      }
+    }
   }
   if (gitFiles === undefined) {
     // Mid-run re-enumeration — or a project the workspace-wide populate
@@ -1365,7 +1392,23 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // Stored only on the way out: a declaration whose literal named an
   // invisible file threw above, and every task sharing it must throw too.
   args.projectFilesCache?.set(memoKey, { snapshot: gitFiles, result: resolved })
-  return [...resolved]
+  return { files: [...resolved], listing: listingFor(args.projectDir, gitFiles, plan, nested) }
+}
+
+function listingFor(
+  root: string,
+  listed: readonly string[],
+  plan: FilesPlan,
+  nested: (rel: string) => boolean,
+): InputListing {
+  return {
+    root,
+    listed,
+    isInput: (rel) => inPlan(plan, rel),
+    nested,
+    prefixes: plan.prefixes,
+    literals: plan.literals,
+  }
 }
 
 /**
@@ -1417,6 +1460,135 @@ function undecodableOnDisk(abs: string): boolean {
   return false
 }
 
+/**
+ * The listing a task's input files were filtered from, and what reading it
+ * again takes: {@link addedInput} looks for a file the listing lacked.
+ */
+export interface InputListing {
+  root: string
+  /** Root-relative paths, as git listed them. */
+  listed: readonly string[]
+  isInput: (rel: string) => boolean
+  nested: (rel: string) => boolean
+  /** Root-relative directories a positive entry reaches, `''` for the root. */
+  prefixes: readonly string[]
+  /** The literal entries, each naming one path. */
+  literals: readonly string[]
+}
+
+function reachOf(positive: readonly string[]): { prefixes: string[]; literals: string[] } {
+  const prefixes = new Set<string>()
+  for (const p of asTrees(positive)) {
+    if (isLiteralPattern(p)) continue
+    const prefix = staticPrefix(p)
+    prefixes.add(prefix === '.' ? '' : prefix)
+  }
+  return {
+    prefixes: [...prefixes],
+    literals: positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
+  }
+}
+
+/** Every directory holding a listed path, `''` for the root, once per listing. */
+const listedDirsMemo = new WeakMap<readonly string[], Set<string>>()
+function listedDirs(listed: readonly string[]): Set<string> {
+  let dirs = listedDirsMemo.get(listed)
+  if (dirs !== undefined) return dirs
+  dirs = new Set([''])
+  for (const rel of listed) {
+    for (let i = rel.lastIndexOf('/'); i > 0; i = rel.lastIndexOf('/', i - 1)) {
+      const dir = rel.slice(0, i)
+      if (dirs.has(dir)) break
+      dirs.add(dir)
+    }
+  }
+  listedDirsMemo.set(listed, dirs)
+  return dirs
+}
+
+function reaches(prefixes: readonly string[], rel: string): boolean {
+  return prefixes.some(
+    (p) => p === '' || rel === p || rel.startsWith(`${p}/`) || p.startsWith(`${rel}/`),
+  )
+}
+
+/**
+ * An input file that exists now and that the key did not fold, or undefined.
+ * The facts re-check only the files the key folded, so a file ADDED under
+ * an input glob while the command ran — and read by it — was saved under a
+ * key without it, and replayed once the file was gone.
+ *
+ * Adding a name changes its directory's ctime, so the listing's directories
+ * that a positive entry reaches are stat'ed, and only one changed since
+ * `listedAt` (the listing's time, less the racy window) is read. A name
+ * there that the key lacks and the declaration matches, or an unlisted
+ * directory, is asked of git, which alone knows what is ignored; so is a
+ * missing literal that now exists. Not seen: a file added inside a
+ * directory that held no listed file before (only ignored ones, or none)
+ * and was not itself created during the run — its parent's ctime stays.
+ */
+export function addedInput(
+  listings: readonly InputListing[],
+  keyFiles: ReadonlySet<string>,
+  listedAt: number,
+): string | undefined {
+  for (const l of listings) {
+    const found = addedTo(l, keyFiles, listedAt)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+function addedTo(
+  l: InputListing,
+  keyFiles: ReadonlySet<string>,
+  listedAt: number,
+): string | undefined {
+  const candidates: string[] = []
+  for (const lit of l.literals) {
+    if (l.nested(lit) || keyFiles.has(path.resolve(l.root, lit))) continue
+    if (existsOnDisk(path.resolve(l.root, lit))) candidates.push(lit)
+  }
+  const known = listedDirs(l.listed)
+  for (const dir of known) {
+    if (!reaches(l.prefixes, dir) || (dir !== '' && l.nested(`${dir}/`))) continue
+    const abs = dir === '' ? l.root : path.resolve(l.root, dir)
+    let entries
+    try {
+      const st = lstatSync(abs, { throwIfNoEntry: false })
+      if (st === undefined) continue
+      if (st.ctimeMs < listedAt - racyWindowMs(st.ctimeMs, FILE_HASH_RACY_MS)) continue
+      entries = readdirSync(abs, { withFileTypes: true })
+    } catch {
+      // Unreadable here: git answers for the whole directory instead.
+      candidates.push(dir)
+      continue
+    }
+    for (const e of entries) {
+      const rel = dir === '' ? e.name : `${dir}/${e.name}`
+      if (e.isDirectory()) {
+        if (known.has(rel) || e.name === 'node_modules' || l.nested(`${rel}/`)) continue
+        if (reaches(l.prefixes, rel)) candidates.push(rel)
+      } else if (
+        l.isInput(rel) &&
+        !l.nested(rel) &&
+        !isInstalledPath(rel) &&
+        !keyFiles.has(path.resolve(abs, e.name))
+      ) {
+        candidates.push(rel)
+      }
+    }
+  }
+  if (candidates.length === 0) return undefined
+  for (const rel of runGitLsFiles(l.root).files) {
+    if (!candidates.some((c) => c === '' || rel === c || rel.startsWith(`${c}/`))) continue
+    if (isInstalledPath(rel) || l.nested(rel) || !l.isInput(rel)) continue
+    const abs = path.resolve(l.root, rel)
+    if (!keyFiles.has(abs) && isInputOnDisk(abs)) return abs
+  }
+  return undefined
+}
+
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
 
 /**

package/src/orchestrator/execute-task.ts

@@ -1330,14 +1330,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   /**
-   * The input that no longer holds what the key folded: `null` when the
-   * key re-derived just before the command already differed (the file
-   * unnamed), undefined when none moved.
+   * The input that no longer holds what the key folded, or one the key did
+   * not fold that is there now: `null` when the key re-derived just before
+   * the command already differed (the file unnamed), undefined when none
+   * moved.
    */
   async function movedSinceKey(): Promise<string | null | undefined> {
-    return described!.hash !== hash
-      ? null
-      : await movedInput(described!.facts, cache, described!.describedAt)
+    if (described!.hash !== hash) return null
+    return (await movedInput(described!.facts, cache, described!.describedAt)) ?? described!.added()
   }
 
   /**

package/src/orchestrator/task-hash.ts

@@ -5,6 +5,8 @@ import type { ProjectFilesCache, WorkspaceFilesCache } from '../cache/index.js'
 import {
   ABSENT_INPUT,
   absentOr,
+  addedInput,
+  type InputListing,
   type CacheKeyInput,
   type CacheLayer,
   FILE_HASH_RACY_MS,
@@ -111,7 +113,7 @@ export interface ComputeHashArgs {
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   const end = span('task hash')
   try {
-    return await args.cache.key(await resolveKeyInput(args))
+    return await args.cache.key((await resolveKeyInput(args)).input)
   } finally {
     end()
   }
@@ -138,11 +140,16 @@ export interface InputFact {
  * same sources as the fold: the index-OID map for clean tracked files,
  * else `hashFile`'s stat memo (already warm after `key()`).
  */
-export async function describeTaskInputs(
-  args: ComputeHashArgs,
-): Promise<{ hash: string; inputs: TaskInputs; facts: InputFact[]; describedAt: number }> {
+export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
+  hash: string
+  inputs: TaskInputs
+  facts: InputFact[]
+  describedAt: number
+  /** An input file the key did not fold that exists now (see `addedInput`). */
+  added: () => string | undefined
+}> {
   const hashedAt = Date.now()
-  const input = await resolveKeyInput(args)
+  const { input, listings } = await resolveKeyInput(args)
   const hash = await args.cache.key(input)
   const sorted = [...input.inputFiles].sort()
   const digests = await Promise.all(
@@ -194,10 +201,14 @@ export async function describeTaskInputs(
     })
   }
   let upstream: TaskInputs['upstream'] | undefined
+  // A listing from the run's enumeration is as old as it; one listed with
+  // no run cache was listed during this describe.
+  const listedAt = args.gitFilesCache === undefined ? hashedAt : indexedAt
   return {
     hash,
     facts,
     describedAt: hashedAt,
+    added: () => addedInput(listings, new Set(input.inputFiles), listedAt),
     inputs: {
       files,
       env: input.envValues.map(([name, value]) => ({ name, value })),
@@ -260,7 +271,9 @@ export async function movedInput(
   return undefined
 }
 
-async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
+async function resolveKeyInput(
+  args: ComputeHashArgs,
+): Promise<{ input: CacheKeyInput; listings: InputListing[] }> {
   const cfg = args.node.config
   const cacheCfg: CacheConfig | undefined = cfg.cache
   const outputs = cacheCfg?.outputs.files ?? []
@@ -327,7 +340,7 @@ async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
 
   const effectiveForwardArgs = args.node.requested ? (args.forwardArgs ?? []) : []
 
-  return {
+  const input: CacheKeyInput = {
     taskId: args.node.id,
     taskConfigHash,
     projectPackageJsonHash,
@@ -345,6 +358,7 @@ async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
     ...(args.node.keyParts !== undefined ? { pluginParts: args.node.keyParts } : {}),
     ...(args.captureInto !== undefined ? { captureInto: args.captureInto } : {}),
   }
+  return { input, listings: resolved.listings }
 }
 
 /**