variant answers one question about a change to a TypeScript repository: what has to be verified before this is safe to merge?
It reads the diff at the level of the syntax tree, not the line, follows every import across workspace packages, and says, on the pull request:
- how risky each changed file is, and why;
- which test files reach the change, with the import chain from each test to the file that changed;
- which typecheck, build and lint commands apply to the packages it affects;
- which changed files no test reaches at all.
You set it up once. After that nobody types a variant command: your own test command and your pull requests are the interface.
npx @blzsky/variant initinit finds out how the repository installs, tests and runs CI, shows every
change it would make as a diff, and makes them when you agree. It adds one
line to your Vitest config and one workflow that keeps a comment on each pull
request.
It does not skip tests. Your full suite runs as it always did; in CI variant predicts beside it which test files the change needs, then checks that prediction against what failed and prints one line:
variant: predicted 8 of 55 test files (high). 2 failed, all predicted.
Leaving tests out is something variant has to earn in each repository, from that record, and is not built yet.
Status:
0.x. What is described here is published as a canary,0.3.0-canary.0, under thecanarytag: write@blzsky/variant@canarywherever this page says@blzsky/variant. Without the tag npm serves 0.2.1, which hasimpact,pr check,pr reportandworkspace check, aninitthat only writes a task-runner config, and no adapter. The adapter is for Vitest; a Jest repository gets the pull request report only. Test skipping is not implemented, deliberately. The task runner underneath (build,run,insight) works but is frozen. Any minor release can break, and every break is in the CHANGELOG.
variant needs Node 20 or newer and a git repository.
npx @blzsky/variant init # shows the changes, asks, then applies
npx @blzsky/variant init --dry-run # only lookinit installs @blzsky/variant as a dev dependency with your package
manager (npm, pnpm, Yarn or Bun), adds the
Vitest adapter to your test config, ignores
.variant/, gives your test workflow's checkout the history a prediction
needs, and writes .github/workflows/variant.yml. Anything it cannot edit
with confidence it leaves alone and tells you the lines to add.
The package is @blzsky/variant; the binary it installs is variant.
npx variant fetches an unrelated package, so always use the scope with npx.
npm install -D @blzsky/variant@latestBecause variant is 0.x, read the CHANGELOG before moving to a new minor
version.
After init there is nothing to run. What you see:
- On every pull request, one comment, kept up to date: the risk of each changed file, the tests to run and why, the checks, and what is not verified. An example.
- In every CI test run, one line saying what was predicted and whether a failure fell outside it.
The first runs after setup select every test, because the setup itself changes the lockfile and the test config. Narrowed predictions start with the next pull request.
The commands underneath are still there when you want them:
variant pr report --markdown # the pull request comment, locally
variant impact # which tests does this change need?
variant workspace check # undeclared dependencies (exits 1)| Command | What it does |
|---|---|
impact |
Predict which test files a change requires, and how much of the import graph resolved. Report-only. |
impact verify <report...> |
Reconcile the last prediction against one or more Vitest or Jest JSON reports and report false skips |
diff <file> |
Classify one file's change and list the exported symbols that changed |
init |
Set a repository up: the dependency, the adapter, the workflow. Once. |
pr check |
Classify every TypeScript change on the branch and roll them into one build verdict |
pr report |
What the branch changes and what has to be verified, as JSON or as markdown for a PR comment |
workspace check |
Fail when a package imports a dependency it does not declare |
Run variant <command> --help for its flags, or see the
CLI reference. The tutorial
walks through every command on a sample monorepo in about fifteen minutes.
Every changed file gets one of three classifications. non-impacting means
only comments or formatting changed, and selects no tests. internal means the
body changed but the exported surface did not, and selects every test that
imports the file. breaking means an exported signature changed, and also
follows the importers of the changed names for pr check's verdict. A change
to package.json, a lockfile, tsconfig*.json, a test runner config or a test
setup file selects every test.
init writes what CI needs. To wire the commands in by hand: check out
with fetch-depth: 0; the base is detected on GitHub Actions, and elsewhere
pass --base origin/<branch>. A shallow
clone has no base commit to compare against, and actions/checkout creates no
local branch for the target; variant stops with GIT_REF_ERROR rather than
guess.
Ready-to-copy GitHub Actions workflows are in
examples/github-actions:
pr-report.ymlkeeps one sticky comment with the verdict on every pull request.workspace-check.ymlfails the build on an undeclared dependency.impact-shadow.ymllogs a prediction, runs the full suite anyway, and reconciles the two.impact-shadow-workspace.ymldoes the same for a pnpm workspace that tests each package on its own. It needs a release newer than 0.2.1.
A false skip is a test that failed and that the prediction did not select. The false-skip rate is false skips divided by failed test files, with flaky failures counted against variant. One repository is not enough to trust it.
If you add impact-shadow.yml to your CI, it changes nothing about your build.
It uploads the counts as a variant-reconciliation artifact: commit SHAs,
branch names and numbers, no file paths and no source.
Share them in an issue,
and they go into the measurement that decides whether skipping ever ships. The
measurement log has every number collected so far.
Measured by CI on 2026-09-28 with benchmarks/bench.mjs,
on a generated git repository of 300 TypeScript files with 25 changed. Each
number is the median of the runs shown. Machine: AMD EPYC 9V74 (4 cores),
16 GB RAM, Linux, Node 22.23.2, hyperfine 1.18.0.
| Median | Runs | |
|---|---|---|
variant --help (startup) |
36.7 ms | 20 |
variant impact, 25 changed files of 300 |
988 ms | 10 |
- Startup is a CI gate. The benchmark workflow fails when the
--helpmedian passes 200 ms, because every command is loaded only when it runs. - The symbol index is cached.
.variant/graph/symbols.jsonkeeps each file's exports and imports keyed by content hash, so a later run re-parses only the files whose content changed. - Large real repositories are not measured yet. 300 generated files say how the pipeline behaves, not what it costs on your monorepo. Whether the analysis pays for itself depends on how long your suite takes, and that number has to come from real runs.
Reproduce with pnpm build && pnpm bench; the methodology is in
benchmarks/README.md.
Nx affected, Turborepo --filter. These work at the level of projects
and tasks: a change inside utils reruns the test target of utils and of
every project that depends on it. In the example above, that is all four test
files. variant works at the level of test files and follows each one's imports
across packages, so it runs two. Nx and Turborepo also cache and orchestrate
tasks; variant's impact does neither, and the two can be used together.
vitest related, jest --findRelatedTests. These follow imports at the
file level too, within one project. variant adds two things: import chains that
cross workspace packages, and classification, so a change to comments or
formatting selects no tests at all.
Not function-level. Test selection is by file: a test that imports a changed
file runs, whichever functions it calls. The exported-surface classification
decides pr check's build verdict and whether a change selects anything, not
which functions a test touches.
Worth knowing before you trust a prediction. variant reads source statically, so it sees imports and nothing else. It widens the selection or lowers its confidence wherever it can tell it is missing something, but some edges it cannot see at all:
- Runtime-only wiring is invisible. Dependency injection by token,
string-keyed registries and
evalnever appear as imports. A test that reaches code only this way is not selected, and nothing in the output says so. This is the largest blind spot. - Service boundaries end the graph. An end-to-end test that calls a running server imports none of the code it exercises.
- Setup files are recognized by name.
vitest.setup.ts,setupTests.ts,global-setup.tsand the like select every test; a setup file named anything else selects none. variant does not read the runner config. - Files read at runtime are outside the closure. A changed stylesheet or
JSON file that a TypeScript file imports selects that file's tests, but a
fixture, snapshot or asset a test reads with
fsis invisible. A changed file that reaches no test is listed asUnreached. - Only the directory it runs in is indexed. A file changed elsewhere in
the repository selects the tests of the files that import it by relative
path, and is listed as
Unreachedotherwise. - Unreached is not the same as untested. A changed file no test reaches
is listed as
Unreachedand the prediction readslow. variant cannot tell an untested file from one a runtime lookup uses. - JavaScript is indexed when git says it is yours. Tracked or new
.js,.jsx,.mjsand.cjsfiles are read like TypeScript; build output and bundles are not. A changed CommonJS module reaches everything that requires it. - Computed imports are followed only as far as their literal start.
import(`./locales/${lang}.js`)reaches everything under./locales/;import(name)could load anything, and is a standing note on every run. - Dynamic
import()is assumed to use everything. The change propagates and a note is printed; the run gets wider, not narrower. - Workspace discovery can miss a package, and a bare import of a package it
missed counts as external.
impactprints how many packages it found and notes imports no discovered package or manifest accounts for. - Type-only changes are not narrowed. Changing an interface selects every test that imports the file, though no runtime behavior changed.
- The confidence score is not a safety number. It says how much of the
import graph resolved, as
high,mediumorlowand a percentage. Only the false-skip rate says how safe a skip would have been.
The full list, with how each case is handled, is in Impact & workspace.
| Tutorial | Every command, step by step, on a sample monorepo |
| Getting started | Run it on your own repository, then set up the task runner |
| Impact & workspace | How impact and workspace check work, and what static analysis cannot see |
| PR commands | pr check and pr report |
| Vitest adapter | One config line in place of the commands: predict and check on every test run |
| CLI reference | Every command, flag, exit code and file |
| API reference | defineConfig, the config types, and every JSON output |
| Monorepo setup | Workspace tasks and --affected |
| Config reference | Every variant.config.ts key |
| Troubleshooting | Common problems and what they mean |
| Measurement log | Every prediction checked against a full run so far, and the gate skipping has to pass |
See CONTRIBUTORS.md to set up the repository, run the tests, and check a change before opening a pull request.
MIT — see LICENSE.
