variant reads a TypeScript diff at the AST level and tells you which tests that change actually needs. This guide runs it against your own repository — no config file, no setup — and then covers the task runner underneath it.
Prefer a guided run on a sample project first? The tutorial walks through every command on a three-package monorepo.
- Node.js ≥ 20
- A git repository with at least one prior commit
- TypeScript sources (
.ts/.tsx)
impact needs no config file. Point it at a commit range:
npx @blzsky/variant impact --base HEAD~1The package is @blzsky/variant; the command it installs is variant. npx @blzsky/variant runs it
without installing. (npx variant would fetch an unrelated package of that
name, so never write that.) To install it:
npm install -D @blzsky/variantAfter which the command is variant:
variant impact --base origin/mainFor a change that only touched the body of one exported function:
Base ref: HEAD~1
Workspace: no workspace packages found
You changed 1 file.
internal src/math.ts
Impact: 1 file
Run: 1 test file
Skip: 1 test file (of 2 total)
Verdict: build recommended
Confidence: high (100%) (report-only — run the full suite; skipping unlocks after shadow-mode validation)
Reading it:
internal— the exported signature did not change, only the body. Dependents still compile, so the change does not spread through the blast radius (Impact). Every test that importsmath.ts, directly or through other files, is still selected: a new implementation can change what a test observes. The three classifications arenon-impacting,internalandbreaking; anything that is not TypeScript isunanalyzed.- Run / Skip — the tests whose static import closure reaches an affected
file, and the rest. Here the skipped test never imports
math.ts. - Confidence — how much of the import graph resolved, not a safety
number. Unresolved specifiers and dynamic
import()lower it and add a note. - Report-only. variant never skips anything for you. Every prediction is
appended to
.variant/history/impact.jsonlso the false-skip rate can be measured before skipping is ever offered.
Add --json for the machine-readable form, which includes the full blast
radius and every note; its shape is in the API reference.
--base compares the ref's commit with your working tree, so on a branch that
has fallen behind main, --base main also reports what landed on main
since. Pass --base "$(git merge-base main HEAD)" to see only your branch; the
CLI reference has the details.
To check a prediction against reality, keep the test runner's JSON report and reconcile it:
npx vitest run --reporter=json --outputFile=report.json
variant impact verify report.jsonThat reports false skips — tests that failed and that the prediction did not select. See impact-and-workspace.md.
variant pr check --base origin/main
variant pr report --base origin/main --markdown --output pr-report.mdpr check classifies every changed TypeScript file and rolls the result into
one verdict. pr report says what the change needs verified (tests and why,
package checks, and what no test reaches) as JSON or as markdown suitable
for a sticky PR comment — see pr-commands.md, and
examples/github-actions for workflows to copy.
In a monorepo, variant workspace check is a CI gate for undeclared
dependencies and cross-package relative imports. Both commands are covered in
impact-and-workspace.md, including the cases where
static analysis cannot see an edge.
variant also runs your tasks as a cached DAG. This part needs a config file.
variant init --tasksinit --tasks detects your package manager, framework, and existing package.json
scripts, then writes variant.config.ts:
// variant.config.ts
import { defineConfig } from "@blzsky/variant";
export default defineConfig({
strategy: "adaptive",
tasks: {
build: {
command: "npm run build",
inputs: ["src/**/*", "package.json"],
},
test: {
command: "npm test",
inputs: ["src/**/*", "tests/**/*"],
dependsOn: ["build"],
},
},
});Check it:
variant doctor[✓] Node v22.4.0 meets requirement ≥20
[✓] Config found: variant.config.ts
[✓] Config is valid
[✓] Cache directory is 0 MB
First run — every input hashes to a miss, so both tasks execute in dependency order:
variant buildTASK DURATION STATUS
-------------------------------
build 4200ms MISS
test 12100ms MISS
Run it again without touching a source file and both are served from the cache:
TASK DURATION STATUS
-------------------------------
build - HIT
test - HIT
variant insight shows each task's last run timestamp and duration from the
local cache history.
- tutorial.md — every change-intelligence command on a sample monorepo, including reconciling a prediction with a real test run.
- impact-and-workspace.md — what
impactcan and cannot see, and howworkspace checkis configured. - cli-reference.md and api.md — every command, flag and JSON output.
- pr-commands.md —
pr checkandpr reportin CI. - monorepo.md — workspace task generation and
--affected. - config-reference.md — every config key.
- Tune
inputsto be as narrow as possible: the narrower the glob, the fewer cache invalidations.