A miss on a fresh checkout runs tsc --incremental with no build info, though the step's entry archived it #936

Written by an AI agent (Claude) on behalf of @jasonkuhrt.

Part of the work in #929. Since #913, a task that rewrites its tool cache, such as tsc --incremental with tsconfig.tsbuildinfo, is cached, and a hit restores that file with the task's other outputs. A miss restores nothing, so on a fresh checkout, which is where CI runs, every miss starts the tool cold.

What happens

// vite.config.ts
import { defineConfig } from 'vite-plus';

export default defineConfig({
  run: {
    tasks: {
      'check:types': { command: 'tsc --incremental --noEmit' },
    },
  },
});

1. A run on main executes check:types. tsc writes tsconfig.tsbuildinfo, and the entry archives it as an output.
2. A pull request edits src/a.ts. CI checks out a fresh tree, so there's no build info on disk. The entry under the step's cache key fails validation ('src/a.ts' modified), so it's a miss.
3. tsc runs with no build info and checks every file. The entry's archive holds the build info from step 1, but only a hit extracts it (ExecutionCache::restore, crates/vt/src/session/cache/mod.rs:589 at c4b2aacf). For a remote entry, a failed validation also means its archive is never downloaded (mod.rs:446-451).

With incremental compilation enabled, TypeScript records each input's content version in its build info, so the next compilation can skip what hasn't changed (incremental).

The ask

A per-task list of tool cache files that a miss restores from the entry under the step's cache key, before the command runs:

'check:types': {
  command: 'tsc --incremental --noEmit',
  cache: { restoreOnMiss: ['tsconfig.tsbuildinfo'] },
},

The name is only a suggestion.

Which files qualify

• Only a cache the tool validates itself. Listing a file says the command's result is the same with or without it. A cache whose keys can miss a change, such as a transform cache keyed by a module's text alone, doesn't qualify. The runner can't tell the two apart, so this is opt-in per file.
• Not an emitting build. An emitting build's build info vouches for its emitted files, and TypeScript emits only the files it finds affected. Build info restored beside missing or older outputs would leave them wrong, and restoring the two together would need all-or-nothing rules this ask doesn't cover. That's why the example is --noEmit.

Where the copy comes from

The entry under the step's current cache key (same command, env and cache config):

• A local entry: the listed files are extracted from its archive in the cache directory.
• A remote entry: its archive is downloaded and the listed files are extracted. Only a task that lists files pays for that download.
• A remote fallback names another key and carries no archive, so it restores nothing.
• No entry under the key in either tier, as on a first run: nothing is restored, and the command runs as it does today.

When a file is restored

• Only when it's missing, which is the fresh-checkout case. A file already on disk is the tool's latest state, possibly from a run that failed and so stored no entry (crates/vt/src/session/execute/cache_update.rs:90-91), and is left alone.
• With its archived modification time, as a hit's outputs are today. tsc --build's up-to-date check compares modification times, so build info dated at restore can make changed inputs look up to date there. Cache replay restores outputs with their archived modification times, so mtime-based tools skip changed files #881 proposes dating a hit's outputs when they land; a file restored on a miss needs its archived time either way.
• Never at the task's expense: a listed file the archive doesn't hold, or a restore that fails, leaves the command to run as it does today.

What the run records

• A listed file counts as one the run wrote. It's archived from disk after the run and recorded as possibly missing, as feat(cache): cache tasks that rewrite files they read #913 records a file a task rewrites, even when this run only read it. Otherwise a run that reads the build info without rewriting it would store an entry that requires the file and holds no copy of it.
• A positive cache.input glob that matches a listed file keeps its meaning today: it's hashed before the run.

What stays the same

• A hit restores every output, the listed files included.
• --dry-run (docs(rfc): JSON task graph, and dry-run plans with cache status #933, proposed) downloads and restores nothing, so this changes no status it reports.

Alternatives considered

• Restore every file a task rewrites. That includes caches that can change the result, and the runner can't tell which those are.
• CACHEDIR.TAG (Let tools mark cache directories with CACHEDIR.TAG #793). A tag says a directory is a cache, not that its tool validates it, so it can't opt a directory into this. A tool that tags its cache could still list it here.
• The CI provider's cache (GitHub's actions/cache, a runner's persistent disk). It needs the path and a key per job and per provider, outside the task graph, while Vite Task already holds the file in the step's entry.

Our case

We restore build info today with a wrapper around each type-check command: it fetches the branch's last build info from our own server before tsc runs and stores it after. With this, Vite Task would restore it from the entry it already holds, and the wrapper's restore and store would go. Our pnpm layout also needs the build info's dependency paths rewritten for the machine, which stays on our side.